cletus-plugins/docs/style-guide.md

# Style guide

Cletus is a professional tool for engineers, analysts and shop-floor teams.
A plugin should feel like part of it: calm, dense, exact, and never in the
way. Review checks this guide.

## 1. Principles

- **It just works.** Values that can be computed are computed. Nothing
  waits for a button press that could have been automatic.
- **Model the tool users already know.** A CAD screen behaves like the CAD
  viewers your users use; a forming screen like the forming tools they use.
  Keep familiar mouse controls and names.
- **Nothing jumps.** No layout shift from messages, panels or loading.
- **Professional density.** Small type, tight rows, icons. Never big
  friendly buttons.
- **Simple surface, depth underneath.** Show what most people need; put the
  rest one click away, not on screen.

## 2. Words

- Plain words, short sentences. Write for a manufacturing engineer, not a
  programmer.
- No internal codes, ids, hashes or stack traces in the interface. A
  technical detail appears only when it adds to the plain sentence, behind
  "Details".
- Errors say what happened and what to do: "The drawing has no tolerance
  table. Add one, or enter tolerances under Settings." Not "Error 422" or
  "Something went wrong".
- Sentence case for labels and buttons ("Save report", not "Save Report").
- Units always shown beside the value and the input (`10 mm`).
- Inexact values carry `~` with the reason on hover. Exact values carry no
  mark.

## 3. Theme

- Use the host's tokens (CSS variables) for every colour. Never hard-code a
  colour, and never assume the theme is dark.
- Cletus has three base themes (Amber, which is dark; Dark; Light) and
  customer variants. Test all three.
- Engineering and data-dense screens set `"theme": "tool"`. Style controls
  with the semantic tokens:
  - toggled buttons: `--pressed-fill / -text / -border / -indicator`
  - primary buttons: `--primary-*`
  - the active tab: `--tab-indicator`
  - density: `--tool-font` (12 px), `--tool-row` (22 px), `--tool-pad` (6 px)
- The accent colour is for thin indicators and small marks. No large filled
  accent areas.
- One surface per card. No boxes in boxes.
- Judge theming by intent (readable, consistent, calm), not by pixels.

## 4. Layout

- **One job per region.**
  - The left rail holds the thing being worked on (a model tree, a
    document list, jobs).
  - The right rail holds tools, in one collapsible `SidePanel` that floats
    over the content and never resizes it. Collapsed, it is a slim icon
    rail.
  - The top toolbar holds view controls only.
- A tool's sub-tools appear as a small strip at the top of the content only
  while that tool is active.
- A fixed-height status bar shows the selection, progress with cancel, and
  dismissable failures. Errors never push content around.
- Floating cards (properties, details) open only when asked for, are movable
  and closable, and never open on a click or right-click.
- Nothing a dialog opens may land under it. A setting a dialog needs appears
  inside that dialog.
- Settings sit behind a gear at the bottom right, not on screen-switching
  bars.
- Icons on every toolbar button (host `Icon` set), with the name and
  shortcut in the tooltip.

## 5. Behaviour

- **Esc** stops what is running or closes the innermost thing open (a menu,
  a live measurement, a panel). It never discards saved work.
- Every job over a second shows progress, an estimate where possible, and
  cancel.
- Instant values compute on selection with "Computing…" in place. A failure
  is a muted "unavailable" with the reason on hover, not a red banner.
- Selection is easy to clear: empty click, Esc, × on the status-bar chip,
  right-click → Clear selection. Hover shows exactly what a click will pick.
- Right-click shows only a menu. Menus are compact and grouped, like
  Cletus's own.
- A resize changes the aspect only. Never re-fit or re-zoom the user's view.
- Anything placed on the content (pins, labels, annotations) has a visible
  way to remove it.
- Files dropped on chat only attach to chat. Your plugin opens a file only
  when the user chooses "Open in <your plugin>" or drops it on your screen.

## 6. 3D and 2D viewports

- Use `sdk_viewport` for backgrounds and selection so every viewport looks
  the same.
- Selection: a soft tint on faces and bodies; the full accent only on
  selected edges and outlines. Never flood a part in the accent colour.
- Offer "Set orbit centre here" (trackpads have no middle button).
- Labels stay inside the viewport and hide or point off-screen when their
  anchor is hidden. Never draw over panels or toolbars.

## 7. Chat tools

- One tool, one operation. No hidden retries or fallbacks inside a tool: fail
  with the reason and the suggested next call, and let the AI decide.
- Results are short, factual and stable: the same input gives the same
  text.
- Name tools `<short plugin name>_<verb>[_<object>]` (`gauge_check_run`).
- Descriptions say when to use the tool and when not to.

## 8. Go

- `gofmt`, `go vet`, `staticcheck` clean. Standard library first.
- Small packages under `internal/`, named for what they do. No `util`,
  `common` or `helpers`.
- Errors wrap with context (`fmt.Errorf("read tolerance table: %w", err)`)
  inside the worker; the message that reaches the user is a plain sentence.
- Every blocking call takes `ctx`. No goroutine without a way to stop it.
- Comments say why, not what. Exported names have doc comments.

## 9. TypeScript and Svelte

- Svelte 5 runes. An `$effect` never reads and writes the same `$state`.
- Strict TypeScript. No `any` without a comment.
- Components small and named for what they show.
- No network calls; data comes from your worker or published links.

## 10. Tests

- Every tool, service method and `ui.*` method has a Go test.
- With screens (a later release): every screen feature gets a browser test
  that checks it changes what the user sees. Don't compare pixels.
- Fixtures are synthetic. Reproduce real-world failures with made-up files
  that have the same shape.