Skip to content

Latest commit

 

History

History
1741 lines (1484 loc) · 130 KB

DESIGN.md

File metadata and controls

1741 lines (1484 loc) · 130 KB

FundaCAD design spec

This is the visual language of FundaCAD as it exists in the code, written for whoever is about to build or change UI: a contributor, a plugin author or an AI agent. Read it before you write markup or styles, and run the checklist before you call the work done.

The code is the source of truth. Every value below is quoted from src/styles/_tokens.scss, src/styles/_glass.scss and the other partials in src/styles/. Where this page asks for something no code does yet, it says so with the words prescribed, no code does this yet. If you change one of those files, change this page in the same commit. tests/ui/designSpec.test.ts holds the rules a machine can check (section 15).

The workspace in FundaCAD Noir: every panel floats over the model as glass

1. Principles

  1. The model is the hero. The WebGL viewport fills the stage. Apart from the 36px title bar and, in Render mode, the Render dock column beside the stage, every piece of chrome floats over the model and leaves it visible around and through itself.
  2. Glass, never a slab. A surface over the model is translucent: a tinted fill with backdrop-filter: blur(24px) saturate(1.08), one soft shadow and squircle corners. The bodies behind smear into the panel. That smear is the product's signature.
  3. Float with air. Floating cards sit --float-gap (12px) from the stage edges and from each other. The layers that hold them pass pointer events through, so the model stays pickable in every gap.
  4. Depth without lines. Depth comes from fill and shadow, never from an outline around a rounded surface. Each level up is a touch lighter (card, tile, chip) and a field sinks a touch darker. A hover, a selection or a pressed state is a fill or a wash, never a border colour or a ring. Layout dividers stay: the title bar edge, the lines between the head, body and foot of a dialog, menu separators. The rules and the few exceptions are in Depth without lines.
  5. Calm accent. The accent appears only on what is active, selected, focused or primary, as a wash, a text colour, an underline or a small fill, never as a large flat fill. There is no glow, sheen, rim or inner highlight anywhere. One exception is in every tool panel: .measure-title is --accent-hot, so the readout reads as the tool's output (7.13). Card and dialog titles stay --text.
  6. Dense rows, generous shell. Rows and labels are small (--fs-small and --fs-body, 34px rows, 40px tiles). The air lives at the shell level: gaps, card padding, big corner radii.
  7. Tokens only. Every colour, radius, gap, duration and shadow is a custom property. Themes swap the colour tokens, and one shipped theme is light.
  8. Degrade, never redesign. Blur off (potato mode or a software renderer), animations off and touch input each have one shared switch. A new surface that uses the shared tokens and classes supports all three with no code of its own.
  9. Reuse before you invent. A new surface is an existing glass class, or a selector added to the existing lists in _glass.scss, and a new control is a base component (7). A new look is almost always a mistake.

Nothing is flat and opaque unless this spec names it. The legitimate exceptions:

Flat on purpose Why
#titlebar (opaque --panel, border-bottom: 1px solid var(--line)) and what sits in it (.tb-btn, .menu-btn, .seg-btn, #context-tab) The one full width strip that does not float; the stage starts below it
Inset wells inside a glass dialog (.pref-card, .prefs-pane-flow .prefs-row, .plug-consent, .mats-list) Groups inside the glass shell; they never blur, and they have no edge
Tiny labels on the model (.snap-tag, .areabox, .sketch-dim, viewport readouts) Labels, not panels
Everything under html.no-glass-blur A performance fallback, not a design (4.5)

One surface is glass but docked, not floating: #renderdock, the Render mode settings. #main is grid-template-columns: minmax(0, 1fr) auto (_layout.scss), so the dock is a grid column that narrows the stage. It keeps a var(--s-3) margin on the top, right and bottom and none against the stage, blurs the page behind it rather than the model, and under 560px stacks below the stage. It is the only docked panel. Do not dock a new one: a new panel floats in #float-layer or wears .measure-panel.

The failure this spec exists to prevent

Anti reference: the first Home screen, flat opaque panels and tiles

The first Home screen covered the stage with opaque var(--panel), used var(--raised) tiles with 1px solid var(--line) and --r-md corners, a one off box-shadow: -8px 0 24px rgba(0, 0, 0, 0.3), no blur, no squircle and hex fallbacks from an old palette. It followed the flat base rules of its sibling partials, which are not what the user sees: _glass.scss repaints a fixed list of selectors, and Home was not on it. If your screen would not look like the same product as the workspace shot above, it is wrong.

2. Tokens

All tokens live on :root in src/styles/_tokens.scss. There are no SCSS variables for design values, and src/styles/main.scss explains why.

Rules:

  • Write var(--token) with no fallback. Fallbacks still sit in _modals.scss (var(--accent, #ff7a3c) and var(--accent-hot, #ff9a5c), from an old orange palette), _home.scss, _browser.scss, _layout.scss, _targetedit.scss and several overlay components (LiveSessionPill.vue, PropertiesPanel.vue, InterferencePanel.vue and others). They never fire, and copying one spreads a value the theme cannot change.
  • Never write a raw colour (#hex, rgb(), hsl(), a named colour) in a component or partial. Derive tints with color-mix on a token: color-mix(in srgb, var(--accent) 16%, transparent). The few literals that remain in _glass.scss are the scrims and the amber of .toast-warning (2.3).
  • Never invent a token name. These are read in the code but defined nowhere and must not spread: --danger (use --error), --fg (--text), --muted (--text-mute), --border (--line), --bg-panel and --panel-1 (--panel), --panel-3 (--panel-2), --fg-dim (--text-dim), --bg-sunken. A new token goes in _tokens.scss, and a new colour token also in PALETTE_TOKENS in src/ui/theme.ts.

2.1 Colours by role (FundaCAD Noir values)

Surfaces, back to front:

Token Noir Use
--bg #050409 Page background
--viewport-bg #0b0912 The scene background, read by the Three side (viewport/themeColors.ts), not by CSS
--panel #1b1826 Base of every glass fill (through --float-bg), the title bar, the no blur fill
--panel-2 #272233 Flat inner controls, native option background
--raised #322c42 Hover fill of flat rows and icon buttons
--raised-2 #3d3651 Off track of Switch (.ui-switch, .ft-switch)

Lines (layout dividers only, see Depth without lines):

Token Noir Use
--line #322c42 Hairline dividers between the parts of a dialog, menu or dock (.modal-head, .modal-foot, .menu-sep, .ctx-sep, .rd-tabs, .prefs-nav) and the title bar edge
--line-strong #847c9a The scrollbar thumb and any line that marks a boundary: 3:1 on --panel and --raised in every shipped theme (tests/ui/themeContrast.test.ts)

Text:

Token Noir Use
--text #f6f0e4 Primary text, titles, values
--text-dim #c4bcd0 Secondary labels, idle icons, a dimmed tree row
--text-mute #a9a2ba Hints, caps labels, idle close glyphs, metadata, a hidden tree row. 4.5:1 on --panel, --panel-2, --raised, --raised-2 and the rail pill glass in every shipped theme, like --text and --text-dim
--text-faint --text-mute 70% into --panel Decoration only (a rule, an idle glyph stroke), never text: it sits under 4.5:1 by design

Accent (also what selected edges, dimensions and manipulator handles are drawn in):

Token Noir Use
--accent #9a9ff0 Primary button fill, the focus outline, the tab underline, the .rd-tab bar, a checked checkbox, switch on
--accent-hot #bcc0f7 Text and icons of an active, selected or hovered row; primary hover
--accent-tint rgba(154, 159, 240, 0.14) Light selected fill (.prefs-nav-btn.active)
--accent-tint-2 rgba(154, 159, 240, 0.24) Stronger selected fill (.seg-btn.active, .rd-chip.active, .pref-seg .on)
--accent-wash color-mix(in srgb, var(--accent) 20%, transparent) The on state of a tile, laid over the tile fill as a gradient layer (.rail-btn.active .rail-tile, .icon-btn.active)
--on-accent #0c0d26 Text on an accent fill
--accent-blue var(--accent) Legacy alias kept for old plugins and palettes (theme.ts writes it with the accent). Never read it in new code

Fills of depth (3 puts them to use):

Token Noir Use
--float-bg color-mix(in srgb, var(--panel) 72%, transparent) A card over the model
--float-bg-solid color-mix(in srgb, var(--panel) 92%, transparent) Menus, popovers, dialogs, anything text heavy
--float-tile-bg color-mix(in srgb, #fff 5%, var(--float-bg)) A tile on a card: rail tiles, Home cards, wells
--float-chip-bg color-mix(in srgb, #fff 10%, var(--float-bg)) A chip, pill, button or key cap on a card
--field-bg rgba(0, 0, 0, 0.3) A text field or select, sunk below the surface it sits on
--check-off rgba(0, 0, 0, 0.45) An empty checkbox, a deeper well than a field so the small box still reads
--control-edge --text 50% over the control (68% in a light theme) The inset 1px edge of every field like control, 3:1 on the panel around it and on its own fill (src/ui/contrast.ts)
--hover-wash rgba(255, 255, 255, 0.07) A hover, laid over the fill of the control
--float-shadow 0 2px 5px rgba(0, 0, 0, 0.32), 0 16px 34px -14px rgba(0, 0, 0, 0.62) The one shadow of all glass

Retired tokens: --float-line, --glass-sheen, --glass-inset, --glass-rim and --accent-glow. They stay defined and transparent so an old plugin stylesheet that still reads one draws nothing. No core rule reads them, the guard fails if one does, and a new rule never should. An uploaded palette that sets --accent-glow still loads, the token is simply ignored.

Status:

Token Noir Use
--ok #17c99a A step deeper than the accent, so an ok mark and a selection differ
--warn #ffab2e Warnings, amber History steps, .perf-warn
--error #ff5c5c Errors, destructive items, failed steps
--error-tint rgba(255, 92, 92, 0.14) Error backgrounds
--pick-line #b48cff The second pick colour, apart from the accent: the Mirror line or plane, in the view and on its panel field
--axis-x, --axis-y, --axis-z #ff5a5a, #46d97a, #4d8dff X, Y and Z in the view: the origin triad and plane tiles, the Move, Pattern and datum gizmos. Colour-Blind Safe trades them for #e5483a, #eedf6b, #6aaef0. Every palette keeps them at 3:1 on --viewport-bg, so the light themes set darker ones
--sketch-free, --sketch-defined, --sketch-construction, --sketch-projected, --sketch-projected-stale, --sketch-loose-open, --sketch-loose-untied #5b9bff, #ffffff, #ffa64d, #b07fe8, #d9a24d, #e5484d, #f5a524 Sketch curves in the view: free to move, fully defined, construction, projected, a projection whose source is gone, open ends and untied ends. A conflict is drawn in --error. Colour-Blind Safe trades them for #3d8fe0, #f5f7fa, #e69f00, #f0e442, #98a3b0, #ff5c5c, #f4c542, the light themes and High Contrast Light for darker ones. Each is held at 3:1 on --viewport-bg (4.5:1 in High Contrast)
--sketch-aid, --sketch-snap, --sketch-preview, --sketch-fill #8fa4bd, #ffaa33, #ffffff, #3a7bd5 Sketch aids: dimension lines and control polygons, the snap marker and its alignment guides, the rubber band, region fills. Colour-Blind Safe uses #a6b4c4, #e69f00, #f5f7fa, #3d8fe0, the light themes darker ones. The three line colours are held at 3:1 on --viewport-bg (4.5:1 in High Contrast), the fill is a see-through wash and is not

There is no info, success tint, warn tint or disabled token. Derive them:

Need Write
Hover of a control linear-gradient(var(--hover-wash), var(--hover-wash)), <the control's own fill>
Menu or list row hover, selected row color-mix(in srgb, var(--accent) 16%, transparent), text --accent-hot, no ring
Tile on linear-gradient(var(--accent-wash), var(--accent-wash)), var(--float-tile-bg)
Field focus outline: var(--focus-ring-width) solid var(--accent), offset 1px, no ring and no border change
Warn or error surface color-mix(in srgb, var(--warn) 9%, var(--float-bg-solid)) (.perf-pop), color-mix(in srgb, var(--error) 22%, var(--float-bg-solid)) (.toast-error)
Warn or error small text on glass or a panel color-mix(in srgb, var(--warn) 60%, var(--text)) or the same with --error (.sketch-dim.conflict, .rel-row.over .rel-sym); the bare --warn and --error pass on the panels, keep them for borders and panel text

2.2 Shape and motion tokens

These are never themed. They are covered in their own sections: glass, type, spacing and radii, motion.

2.3 The fills of the glass

A control on glass is not drawn in --panel tones. It takes the fill of its level, so the surface under it still shows through the translucent card. A control gets its fill by being on a selector list in _glass.scss:

Fill Where
--float-tile-bg Rail tiles, Home cards, the wells of Preferences
--float-chip-bg Button (.btn), Chip, the Segmented chips, .pop-wide, .palette-btn, .choice-btn, .section-chip-btn, .key-chip kbd, .tl-btn, pills and chips on the model
--field-bg TextField and NumberField (.ui-field), Select (.sm-select), the Segmented bar, .sm-input, .param-row input, Home search and sort, the Items filter
--hover-wash Laid over the fill of any of the above on hover
--accent-wash Laid over --float-tile-bg for a tile that is on
rgba(5, 4, 9, 0.35) The scrim of .modal-overlay, .cmdk-backdrop, .choice-backdrop

To give a new control this look, use the base component that has it (Button, TextField, ListRow, SwitchRow, 7); a new surface's own selector goes on the matching list in _glass.scss. Never write a new fill with rgba() or a hex: the guard rejects a new literal anywhere. The light theme redefines these tokens (10), so a control that uses them follows.

3. Surfaces and elevation

Level What Fill Shadow Radius
0 The scene --viewport-bg under the model, --bg under the canvas none none
1 Glass over the model: cards, view control groups, the sketch palette, the tool prompt --float-bg (72%) --float-shadow float
1 tile Rail tiles, Home cards --float-tile-bg --float-shadow tile
1 chip Rail pills, dimension fields, the section and updating chips, viewport readouts --float-chip-bg --float-shadow chip
2 Solid glass for menus and text: popovers, context and title bar menus, the chooser, toasts, the console, the command palette, measure panels, and the docked Render dock (1) --float-bg-solid (92%) --float-shadow float or tile
3 A dialog on a scrim: .modal-panel --float-bg-solid --shadow-3 float
Chrome #titlebar var(--panel), opaque none none
Field Text fields and selects --field-bg, a sunken well none chip
Well Groups inside a dialog --float-tile-bg (.pref-card, .prefs-pane-flow .prefs-row), --panel-2 (.plug-consent), none (.mats-list) none 8px, 8px, 6px, --r-sm

Shadows:

  • --float-shadow is a tight contact shadow under a soft drop, 0 2px 5px rgba(0, 0, 0, 0.32), 0 16px 34px -14px rgba(0, 0, 0, 0.62). It is the one shadow of all glass, and with the fill the only thing that lifts a surface off the model.
  • --shadow-3 is used by glass in exactly one place, .modal-panel, because a soft black shadow has no contrast on the dark scrim. --shadow-1, --shadow-2, --shadow-3 and --shadow-pill are the older hard offset set in Noir. Never put them on anything over the model: "a hard offset over a lit model reads as a hole in the scene" (_tokens.scss). On a light theme they are soft (10).
  • Never write a new box-shadow with its own offsets and colours. There is no halo, glow or ring shadow in the language. Focus is an outline (11).

Depth without lines

A rounded surface has no outline. It is told apart from what is behind it by its fill and its shadow alone.

  • No edge. A rounded surface (anything with a border-radius or corner-shape) never sets a visible border, border-color, outline or a 1px box-shadow ring. Where the box needs a border for its geometry, write border: 1px solid transparent, so every control keeps its size.
  • Levels by fill. Card, tile and chip each step a touch lighter than the one below, and a field steps darker. Use --float-bg, --float-tile-bg, --float-chip-bg and --field-bg, never a hand mixed white or black.
  • State by fill. A hover lays --hover-wash over the control's own fill. A tile that is on lays --accent-wash over its fill. A row that is selected takes color-mix(in srgb, var(--accent) 16%, transparent) and --accent-hot text. A pressed control scales to 0.94. None of them changes a border or adds a ring.
  • Text steps, it does not fade. A dimmed or hidden tree row steps to --text-dim or --text-mute instead of lowering its opacity.
  • What keeps a line. Layout dividers, because they split the parts of one surface and are not its edge: the title bar's bottom edge, the lines between the head, body and foot of a dialog, menu separators, the segment dividers of a control, the Render dock tab bar. Signal borders that flag an error or a warning (--error, --warn). Sketch labels on the model, which tell their state by an accent, dashed, red or amber border. Drawn glyphs, swatches, material balls and screenshots, whose edge is the thing. The guide ring.
  • Focus is the one outline. Keyboard focus draws a crisp accent outline, never a ring shadow (11).

tests/ui/designSpec.test.ts fails on a new outline around a rounded surface, and on any rule that reads a retired token.

Scrims (.modal-overlay, .cmdk-backdrop, .choice-backdrop, final values in _glass.scss): background: rgba(5, 4, 9, 0.35) with backdrop-filter: blur(6px) saturate(1.05). The workspace stays visible behind a dialog, blurred and dimmed. A new modal reuses .modal-overlay rather than writing its own scrim.

Stacking tokens: --z-panel 19, --z-float 20, --z-popover 200, --z-menu 3000, --z-modal 4000, --z-toast 5000. Most layers still use literals, so pick your layer from what is actually on screen:

z Layer
17 .sketch-dim-leaders, calc(var(--z-panel) - 2), the sketch dimension leaders, under the panel
18 .stress-glyph-label, calc(var(--z-panel) - 1), the Stress readouts in the view, under the panel, so a pinned readout turns to the side of its point no panel or card covers
19 .measure-panel (--z-panel), every floating panel
20 #float-layer (--z-float), the cards and rail
200 .float-popover (--z-popover)
1000 .modal-overlay
2000 .menu-popup
2450 .logcon
2500 .toast-stack
3000 .context-menu
4000 .choice-backdrop
4001 .select-pop, calc(var(--z-modal) + 1), so a picker clears its dialog
5000 .cmdk-backdrop

New layers use a --z-* token or calc() on one, never a new literal. Every dialog and its popups (Select, Menu, the title bar menus) draw over the floating panels and the in-view chips, and a floating panel never draws over the rail or the view controls nor sets a z-index of its own; tests/ui/designSpec.test.ts holds all three, and e2e/stress_under_dialogs_e2e.cjs checks them in a real layout.

4. The glass recipe

There is no SCSS mixin. The glass is applied by allowlist: _glass.scss loads after every partial that lays a surface out (see main.scss) and repaints the selectors it names. A selector that is not on its lists renders with its flat base rules. That is the whole mechanism, and the reason Home came out flat.

4.1 The declarations

Group A, over the model (_glass.scss, first rule):

corner-shape: squircle;
background: var(--float-bg);
-webkit-backdrop-filter: var(--float-blur);
        backdrop-filter: var(--float-blur);
border: 1px solid transparent;
box-shadow: var(--float-shadow);

The transparent border only keeps the box size. .float-popover, .context-menu, .choice-card and .dim-unit-menu take the solid fill, var(--float-bg-solid). Tiles (.rail-tile, Home cards) take --float-tile-bg, and chips (.rail-pill, .dim-field, .dim-btn, .section-chip, .updating-chip and the other readouts) take --float-chip-bg. Group B (dialogs, menus, toasts, docks) is the same recipe with the solid fill throughout.

The tokens, with their values:

Token Value Role
--float-bg color-mix(in srgb, var(--panel) 72%, transparent) Translucent fill over the model
--float-bg-solid color-mix(in srgb, var(--panel) 92%, transparent) Fill for menus, popovers, dialogs, anything text heavy
--float-tile-bg color-mix(in srgb, #fff 5%, var(--float-bg)) A tile, one step above the card
--float-chip-bg color-mix(in srgb, #fff 10%, var(--float-bg)) A chip, two steps above the card
--float-blur blur(24px) saturate(1.08) The backdrop filter
--float-shadow see 3 Depth
--float-radius 16px (26px with squircle) Cards, groups, popovers, dialogs, docks
--float-tile-radius 11px (17px with squircle) Rail tiles, context menus, title bar menus, toasts, .rd-tile, card close buttons
--float-chip-radius 8px (12px with squircle) Pills, rows, inputs and buttons inside glass
--float-gap 12px Distance from the stage edges and between cards

The radii grow under @supports (corner-shape: squircle) because a squircle needs a larger radius to look the same size. Always pair a float radius with corner-shape: squircle, never a literal radius.

4.2 Use an existing glass class first

Class Component Use it for
.float-card components/ui/Card.vue; Items (#browser), History (#timeline), Fillet members A card over the model, with .float-card-head, .float-card-title (a heading, h2 unless level says otherwise, holding the toggle when collapsible), .float-card-close, .float-card-more, .float-card-body, .float-card-foot
.float-group ViewportControls.vue A column or row of .icon-btn
.float-popover components/ui/Popover.vue Anything that opens from a button: options, pickers, Select.vue's list
.context-menu ContextMenuHost.vue Right click menus
.measure-panel components/ui/Panel.vue (old name overlays/FloatingPanel.vue) A small tool or readout panel. Worn by MeasureReadout.vue, PropertiesPanel.vue, InterferencePanel.vue, OverhangPanel.vue, StressPanel.vue, MirrorToolPanel.vue and ParamsDialog.vue; check these before you build a new one. Contents and API in 7.13
.modal-panel components/ui/Dialog.vue (old frame overlays/ModalFrame.vue) A dialog, on .modal-overlay
.choice-card ModalHost.vue chooser A short question with a few answers
.cmdk-card CommandPalette.vue The command palette
IconButton md plain (.float-card-close) any glass surface A 28 by 28 icon button for close, copy or more, inside or outside a card (7.1)
.menu-popup MenuBar.vue Title bar menus
.toast ToastStack.vue through ui/toast.ts Short confirmations
.rail-tile, .rail-pill components/ui/RailButton.vue Tool buttons on the rail
#viewport .prompt PromptBanner.vue The tool prompt pill
.section-chip SectionChip.vue, in #viewport .vp-top A state that stays on over the model, with its word buttons
.updating-chip UpdatingChip.vue, in #viewport .vp-top A passing state over the model that takes no clicks, like a slow rebuild

4.3 A new surface

  1. Lay it out in its own partial in src/styles/ (or the partial it belongs to), loaded before glass in main.scss. Give it no background, border, shadow or radius there.
  2. Add its selector to the lists in _glass.scss: group A (over the model) or group B (dialog, menu, toast, dock, text heavy), the fill list of its level (card, tile or chip) and the matching radius list.
  3. Build its controls and rows from the base components (7), which bring their squircle, fills and states; a surface adds none of its own.
  4. Check it with blur off (4.5) and in the light theme (10).

Do not restate the recipe inline in a component. SurfaceNodeEditor.vue does, and is the one legacy exception.

4.4 What glass floats over, and what breaks it

App.vue lays out #titlebar, then #main holding #stage (relative), which holds #viewport (absolute, inset: 0, the canvas) and #float-layer (absolute, inset: 0, z-index: var(--z-float), pointer-events: none) with .float-left and .float-right. Cards set pointer-events: auto again. The Render dock is a second grid column of #main, beside the stage, and blurs the page behind it. Overlays (.measure-panel, dialogs, menus, toasts) are teleported to <body> and are position: fixed.

An ancestor with filter, backdrop-filter, opacity below 1, mask, clip-path, mix-blend-mode or will-change becomes the backdrop root, and glass inside it blurs nothing. So:

  • Keep #float-layer, .float-left and .float-right free of anything but layout and pointer events.
  • A full screen surface (such as Home) paints its backdrop on a ::before layer (position: absolute; inset: 0; z-index: -1; pointer-events: none), never on itself, so it is not the backdrop root of its own cards. Its backdrop may be a scrim or an opaque tone of the theme; its panels and cards are still glass. Prescribed, no code does this yet: on dev, Home paints .home { background: var(--panel) } itself (14).
  • Animate opacity on the glass element itself (pop-in, glass-in do), never on its parent.
  • .float-card uses overflow: hidden to clip to the squircle, so anything that should spill out of a card belongs on an unclipped element.

4.5 Blur off and potato mode

src/ui/glassBlur.ts puts no-glass-blur on <html> when potato mode is on (Preferences, Viewport) or the WebGL renderer is software (SwiftShader, llvmpipe, Microsoft Basic Render). A blurred panel over a WebGL canvas re-blurs on every repaint, which a CPU renderer cannot afford. _glass.scss then sets:

html.no-glass-blur {
  --float-blur: none;
  --float-bg: var(--panel);
  --float-bg-solid: var(--panel);
}
html.no-glass-blur *, html.no-glass-blur *::before, html.no-glass-blur *::after {
  -webkit-backdrop-filter: none !important;
          backdrop-filter: none !important;
}

The fills go opaque, while shape, shadow, spacing and accent use stay. The Solid panels setting (Settings, Accessibility) sets the class too, and so do More and Maximum contrast, so text over a white or busy model keeps 4.5:1. It also adds solid-panels, whose rule in _glass.scss makes --float-bg the opaque --float-bg-solid in light themes as well, where the plain no-glass-blur override loses to :root.theme-light. These are the only legitimate opaque glass, and they must still look finished:

Blur off: opaque fills, same shapes and shadows

To support it, do nothing special: use --float-bg, --float-bg-solid and --float-blur. A hand written translucent rgba() fill would show the model unblurred once blur is off. A backdrop that only works because of its blur (a scrim over busy content) needs an opaque value under html.no-glass-blur. tests/ui/glassBlur.spec.ts covers the switch.

5. Typography

Fonts (self hosted through Fontsource in src/main.ts, only the weights the chrome uses):

Token Family Loaded weights Use
--ui "Space Grotesk", "Inter", system-ui, sans-serif 400, 500, 700 Everything
--mono "JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace 400, 500 Key caps, shortcut hints, branch names, the grid size, console text

Weights 550, 600 and 650 have no face of their own and render as 700. The UI has three visual weights: 400 body, 500 controls, 600/700 titles and caps labels. New mono text uses 400 or 500. .key-chip kbd, .grid-btn, .versions-branch-name and .prompt-key use mono 600, which has no face and renders as a synthetic bold; do not copy it.

The base is font-size: var(--fs-body) with font-feature-settings: "cv11", "ss01", "tnum" on html, body, so numerals are tabular everywhere. Numbers in fields use the UI font, not mono. Text sizes are the rem tokens of _tokens.scss, so the browser's text size and Interface size both carry them, and nothing renders under 11px:

Token Size Role Examples
--fs-micro 0.6875rem, 11px The floor: caps micro labels, counts, badge digits, small secondary text .chip-xs, .ui-field-sm, .panel-title, .rail-sub
--fs-small 0.75rem, 12px Controls and body in panels, every error button, .ui-field-hint, an error hint, .prompt
--fs-body 0.8125rem, 13px Body, rows and labels of the floating shell, card titles body, .rail-label, .float-card-title (600)
--fs-title 0.9375rem, 15px Dialog titles, the command palette input .modal-head h2, .cmdk-input
--fs-display 1.125rem, 18px The two Preferences headings .prefs-pane-title

A size between two tokens takes the nearest one at or above the floor, so the old 10 and 10.5px become 11px, 11.5px becomes 12px and 12.5px becomes 13px. node scripts/check-font-sizes.mjs runs in CI beside the controls guard, and tests/ui/fontSizes.test.ts runs the same scan (scanFontSizes in scripts/fontSizes.mjs) in npm test: a font-size, the size in a font shorthand, an inline style or a style object in src/ or plugins/ has to be a var(--fs-*) token (a fallback, as in var(--fs-micro, 11px), and a unitless --*-scale factor in a calc are fine) or a global keyword like inherit. scripts/font-size-allow.json is a ratchet like the controls allowlist, one count per file: moving sizes to tokens lowers it with --lower, never raise it. Canvas fonts set from TS (ctx.font) are not CSS and follow Viewport label size instead.

There is no display type beyond --fs-display. Nothing in the chrome is above --fs-title except the two Preferences headings at --fs-display.

Caps labels are small, bold, uppercase and tracked, in --text-mute or --text-dim. The existing ones use px tracking: .panel-title --fs-micro/700, 1px, --text-mute; .palette-title 1.2px, #context-tab 0.8px and .home-nav-section 0.4px, all --text-dim. Match the sibling label when you extend a surface. A label in a new surface is font-size: var(--fs-micro); font-weight: 700; text-transform: uppercase; letter-spacing: 0.04em; color: var(--text-mute) (0.06em for a section head), and --text-dim only where it must be read, not just scanned. Titles and row labels are sentence case and untracked.

Line height is mostly left to the default. Paragraph text inside panels uses 1.45 (.pop-note), rail labels 1.2 to 1.25, icon buttons and chips 1.

6. Spacing, radii, sizes, touch and breakpoints

6.1 Spacing

Token Value Typical use
--s-0 2px Tight gaps in lists
--s-1 4px Card body top padding, menu popup padding
--s-2 8px The most used: row padding, gaps
--s-3 12px Popover padding, toast gap, button vertical padding
--s-4 16px Button horizontal padding, pref card padding
--s-5 20px Dialog head, body and foot padding
--s-6 28px Shortcut sheet padding
--s-7 36px The widest gap, .sm-grid columns, menu item label to shortcut

The shell still carries a few off scale px values (card head 10px 10px 6px 14px, rail gap 6px, .opt-row 7px var(--s-3)). Match them when you extend those components, use tokens for anything new.

6.2 Radii

Glass and everything inside it: --float-radius, --float-tile-radius, --float-chip-radius with corner-shape: squircle (4.1). An inner radius is the outer radius minus the inset, as .icon-btn does with calc(var(--float-radius) - 4px).

--r-xs 2px, --r-sm 3px, --r-md 4px, --r-lg 5px are the older square radii of flat controls (the title bar, panel fields). --r-pill 999px is for switch tracks, the scrollbar thumb and the prompt. Do not put --r-* on a floating surface. Dividers are always 1px.

Controls inside glass that still bend this, so do not copy them: the History transport .tl-btn (--r-sm), .float-toggle (6px, no squircle), .pref-seg (6px), .rd-search (--r-md) and .key-chip kbd (6px, squircle).

6.3 Sizes

Element Size
Title bar 36px tall, logo 22px, .tb-btn 26 by 24
Rail tile --rail-tile 40px, 32px in .tool-rail.compact; rail pill min height 28px
.icon-btn 40 by 40 inside a .float-group with 3px padding
Card close and more 28 by 28
History row 34px
Button md 32px tall at --fs-body, sm 28px at --fs-small; a hand written .btn has padding var(--s-3) var(--s-4) at --fs-small, about 33px
Switch 36 by 20, knob 14px
Checkbox 18 by 18
Fields, Segmented md 32px, sm 24px
Card widths Items 264px, History 288px, sketch palette 240px, Render dock 300px
Popovers min width 220px, max height calc(var(--win-h) - 16px)
Dialog min(720px, 0.92 * var(--win-w)) (lg, the default), sm 420px, md 560px, max height 0.88 * var(--win-h); Preferences min(960px, 0.94 * var(--win-w))
Toast max width 560px

A box capped or sized against the window uses --win-w and --win-h (_tokens.scss), never vw or vh: outside Tauri Interface size zooms the root, which scales vw and vh too, so a 100vh cap ran past the window from 110 percent. A box placed from window pixels (innerWidth, a bounding rect) divides them by pageZoom() (ui/interfaceSize.ts).

6.4 Icons

Use <Icon name="…" :size="N" /> (components/shell/Icon.vue), default 16, or IconButton.vue (20 at lg, 14 at md and sm). Icons are SVG files in src/assets/icons/forge/ (outline pack) and src/assets/icons/anvil/ (solid pack, falls back to forge): 24 by 24 viewBox, about 20 by 20 live area, stroke-width 1.4, round caps and joins, no fill, no hard colours (tests/ui/iconFiles.test.ts). Colour comes from currentColor: idle --text-dim or --text-mute, hover --text, active --accent-hot. Never use a Unicode glyph or emoji as an icon.

An Icon is hidden from screen readers (aria-hidden="true", focusable="false") unless it has a label, which makes it role="img" named by that label. Give a label only to an icon that says something no text beside it does, such as a status icon alone in a row; an icon inside a named control never takes one.

Names are the file names, in camelCase. Look in the folder before you pick one; a name that is not there renders nothing. The common actions:

Action Name
Close, dismiss close
Copy, copied copy, then check
More options more
Add, remove plus, minus
Search search
Show, hide visible, hidden
Expand, collapse caretRight, caretDown
Undo, redo undo, redo
Warning warning
Save, open, export, import save, open, export, import

There is no trash, settings, info, error, eye or chevron icon.

A native <details> takes class="disclosure" and leads its <summary> with a 10px caretRight as .disclosure-caret, turned down while open, never the browser's triangle.

Size Use
12 to 15 Inline in rows, close crosses, title bar buttons (15)
16 Default, row icons
18 History node glyph, rail group caret
20 View control icon buttons, rail tiles
28, 36 Empty states

6.5 Touch targets

src/input/pointerKind.ts sets <html data-pointer="mouse|pen|touch"> from the last pointer event; there is no pointer: coarse media query. A touch laptop flips between kinds, so nothing keyed on data-pointer="touch" may change layout. Keep the compact visual size and grow the hit area with a transparent pseudo element on a positioned host, sized to reach about 40px and held back where a neighbour or a scroller edge is closer (_touch.scss):

:root[data-pointer="touch"] .your-btn { position: relative; }
:root[data-pointer="touch"] .your-btn::before { content: ""; position: absolute; inset: -8px -6px; }

The floor is 36px for anything over the model. A hover that moves things (translateY) is cancelled under touch; a hover only affordance needs a @media (hover: none) fallback that shows it.

6.6 Breakpoints

Where Trigger What changes
Narrow stage #stage.narrow, stage under STAGE_NARROW_PX 820 (ui/layoutBreakpoints.ts, measured on the stage, not the window) Items and History become drawers over the model, one at a time, still glass. Focus in a card that folds goes to its drawer switch, and from a switch that goes away to its card (app/foldFocus.ts)
Compact title bar @media (max-width: 760px) Tighter title bar, segment labels hidden
Phone @media (max-width: 560px) Brand, context tab and doc name hidden, rail pills hidden, the Render dock stacks below
Preferences @media (max-width: 640px) One column
Short stage .tool-rail.compact (JS, by height) 32px tiles

Nothing changes above the breakpoints. There are no container queries.

7. Component recipes

Every control is a base component from src/components/ui/, the one set the app and plugins (7.12) draw with. A base component owns its markup, keys, ARIA, disabled model and look, so a caller passes props and restates none of them. Every interactive part has all five states: hover, pressed, focus visible, disabled and selected (or on), where they apply. If a row below says "none", that is a gap in the code, not permission. Much of the app predates the set: the old classes each subsection names are what those screens still wear until they move, and 14 counts them.

Outside src/components/ui/, do not write a raw <button>, <input>, <select> or <textarea>, a control role on a plain element, or a createElement of one: the controls guard refuses it. When nothing in the set fits, extend the closest base component, with a spec in tests/components/ui/; never fork it.

The base set

The props beyond tip, keys, disabled and disabledReason, which every control takes.

Select, ChoiceList, Combobox, Listbox, TextField, NumberField, Slider, Checkbox, Segmented and Tabs each need a name: label, the words, or labelledby, the id of a visible label (inside a FieldRow, the labelId its slot hands over), never both. Their props take the Named union of components/ui/useName.ts, so vue-tsc refuses a call with neither, and in dev a control given neither, nor an aria-label or aria-labelledby attribute, warns " has no name". A Checkbox may take its slot text instead. tip is the tooltip, and only names a control given nothing else (a plain JS plugin skips the type check), without its key chord, so a release build still says it. A Select trigger's name carries its value ("Theme, Dark", or the labelledby text then the value), since VoiceOver and Orca read only the name of a combobox named by aria-label; its open list is named by the label alone. A row button whose own text is not its name ("Choose…", "Edit", a file name) is labelled by the row label, then anything that says what it acts on, then itself: aria-labelledby="{labelId} {ownId}", so a file button reads "Heightmap, Choose…" and a selection button "Faces, 3 faces, Edit".

Component For Props that matter States
Button Any action with a word: dialog footers, panel actions, popover actions variant: secondary (default), primary (one per dialog), ghost, danger; size: sm 28px or md 32px; block spans the container; pressed makes it a toggle (aria-pressed); icon; type, always set, button by default hover, pressed, focus, disabled, on
IconButton An action shown only as an icon: close, copy, more, a viewport tile icon; tip, required, its only name; size: sm 24, md 28 (a card close), lg 40 (a tile, default); variant: tile (default), plain, danger; active makes it a toggle; badge, a count; clickable hover, pressed, focus, disabled, on
Chip A tag, a state or a count badge variant: neutral, accent, warn, error; size: xs (a count badge), sm, md (a chip on the model); icon; label; removable adds a "Remove X" button; as: span or button a button chip: hover, focus, disabled
KeyChip A shortcut drawn as key caps keys; inTitle hides it from a screen reader when the owner's title already says it none, it is a label
KeyCapture A shortcut setting: a button that opens a capture dialog, never armed on focus action, the start of its name; keys, in the table's form, empty shows Not set; problem, the owner's refusal, spoken in place of the new keys; clearable adds Clear; emits capture (key, code, ctrl, shift, alt) and clear as Button; the dialog's region shows when it listens
TextField Typed text: a name, a search, a URL modelValue; commit: live (default) or change; type: text, search, url; validate, error; selectOnFocus; size: sm 24 or md 32; leading and trailing slots; a refusal is described on the field and spoken once focus, error, disabled
NumberField Every number a person types, shown with the language's decimal mark modelValue: number | null; commit: change (default) or live; unit and units (the unit and its picker, and the unit a screen reader hears as the field's description, millimetres or degrees); caption, a unit word that is only text, so "in" or "deg" is not read as a measure; unitless, which says a count or a ratio has no unit and changes nothing; parse, ui/measure by default, so units, fractions and a decimal comma read, or readAs from ui/measure for a field of one kind, which refuses a written unit of another; validate; problem, a refusal from the kernel (described on the field and spoken once, at once in change mode and after a 700 ms pause in live mode); min, max, step; stepFrom, where an arrow starts on a blank field; limits: refuse (default) or arrows, which holds min and max to the arrow keys and lets typed text past them commit, as a native number input does, only for an owner that judges the value; nullable; preview and previewEnd; widthCh focus, error with the rejected text kept, disabled
UnitChip The unit beside a value unit; options makes it a picker, without them it is a caption; spokenElsewhere hides a caption from browse mode when the field already says the unit picker: hover, pressed, open, disabled
Select A choice from a list too long to show at once modelValue; options (value, label, hint, disabled); placeholder; size; variant: field (a well) or chip (the UnitChip look) hover, focus, open with an active row, disabled
Combobox A search field over the list of its matches, as the command palette is modelValue, the query; options (value, label, hint, disabled, keyshortcuts); active with v-model:active, -1 for none; listClass, optionClass; pick emits the chosen value; a default slot per option, an empty slot focus, the active row .is-active, a disabled option
Listbox A group of picks drawn as the caller's own elements: tiles, swatches, cards items (value, label, disabled); modelValue; multiple makes it an array, with v-model:anchor; the option slot hands attrs to bind on the caller's element; apply on Enter focus, selected, a disabled option
Checkbox A setting, on any settings page modelValue, label, indeterminate hover, pressed, focus, disabled, on, mixed
Switch A live toggle, whose change shows in the model as it flips modelValue; label, its name when there is no tip hover, pressed, focus, disabled, on
SwitchRow A labelled row holding a Switch, in a tool panel, a popover or feature properties modelValue, label, icon; layout: float (the view controls) or param (feature properties); a hint slot the row's hover, the switch's states; disabled fades the row as a whole
Segmented A choice of 2 to 5 values, all shown modelValue; options (value, label, icon, tip, keys, disabled); label, the group's name; size: sm 24 or md 32; variant: bar (one well) or chips (the Render dock); iconOnly hover, pressed, focus, selected, a disabled segment, a disabled group
Slider A value along a range modelValue, min, max, step, label, showValue, unit; commit: live or end (on release) hover, pressed, focus, disabled
Tabs The pages of one surface tabs (value, label, icon, disabled, title); modelValue; variant: underline (a card), bar (a dock), nav (a settings page list, aria-current); orientation; label; panels, an id base (useId) shared with a TabPanel around each page, which gives the selected tab aria-controls hover, pressed, focus, selected, disabled with its reason
Menu, MenuItem, MenuSeparator Popup and context menus Menu: anchor, or at (a point) for a context menu, side, align, focus; MenuItem: label, icon, keys, checked (a menuitemcheckbox), danger, a nested Menu for a submenu hover, keyboard focus, pressed, open, checked, danger, disabled
Popover A card that opens from a button: options, pickers anchor, side, align; kind, a class for the card; minWidth; label or labelledby makes it a dialog that takes focus to its first control when a key opened it (focus: keyboard) and gives it back to the opener on close (returnFocus); role="none" for a card that is part of its opener, like the Select list, which then needs no name; focus: first, keyboard or none open; it closes on Escape and on a press outside
Dialog A modal: a task that holds the rest of the app title or the title slot; size: sm, md, lg; closeOnEsc; initialFocus; returnFocus; a footer slot focus held inside, focus back on close
ConfirmDialog A short question with a few answers, or a checklist to confirm title, message; options (value, label, hint, primary, danger); danger; multi with min; confirmLabel, cancelLabel as Dialog, and its buttons
Panel A small tool or readout panel (7.13) open, title, hint, closable, closeOnEsc, panelClass; head-actions and foot slots none of its own, its controls carry theirs
Card A titled card in a pane, as Items and History are (7.1) title; collapsible with v-model:collapsed; head-actions and foot slots a collapsible title: hover, focus
FieldRow A label and its control; in inline and param a control that does not fit beside its label moves under it (7.9) label; for, or the id it hands its slot, or null for no for when aria-labelledby names the control; hint; error; layout: inline, stacked or param, the inspector row that keeps the .param-row classes, with controlClass for its value column and labelWidth for a fixed label column; the slot gets describedby, the hint only, and errorId while there is an error, for a control that does not speak its own error
ListRow A selectable row in a list, or a row that is a button label, hint, icon, selected; as: option (inside a listbox, whose owner moves focus) or button hover, pressed, focus, selected, disabled
ReadoutList Label and value pairs in a panel: Measure, Properties, the Stress key rows rows (k, v); rowClass, worn by each row; the value slot draws the dd for a row (row, index) none
RailButton A tool on the rail (7.3) as today as 7.3
Toolbar A row or column of controls that is one Tab stop: the rail, the view controls, a panel's actions label or labelledby; orientation: horizontal (default), vertical or both; wrap; tag. Its buttons are found in the slot, the arrows, Home and End move among them, a nested Segmented keeps its own stop and keys, a text field keeps its arrows none of its own, its controls carry theirs

Each look is in the subsections below. Three composables sit under them, for a base component that needs one: useDisabled (below), useRovingFocus (one Tab stop, the arrows, Home and End, wrapping; Segmented, Tabs, Menu, the Select list, the ConfirmDialog answers and Listbox, which adds the grid arrows and type ahead itself; Toolbar reuses its rovingIndex over the buttons it finds) and useCommitField (the draft, commit on Enter or blur, revert on Escape, the rejected text kept, the preview debounce; under TextField and NumberField).

States and the one disabled model

A base component marks its state with one class and the ARIA that goes with it. A few still write the old class beside it (IconButton .active, Switch .on, Select .open) so the rules of the markup they replace keep painting.

State Class and ARIA Look
Hover :hover:not(.is-disabled) --hover-wash over the fill, or the component's own, below
Pressed :active:not(.is-disabled) a scale (0.97 on a button, 0.94 on an icon button or a tile) or a deeper wash
Focus visible :focus-visible the shared outline (11); a field the same ring on its well, offset 1px; a segment, tab, menu item or list row inset by the ring width
On .is-on, aria-pressed or aria-checked --accent-wash over the fill with --accent-hot ink, or an --accent fill on Checkbox and Switch
Selected .is-selected, aria-selected or aria-checked accent 16% or --accent-wash, --accent-hot
Open .is-open, aria-expanded the hover look, held while its menu or list is open
Error .is-error, aria-invalid --error-tint, the accent ring kept while focused, the reason in title
Disabled .is-disabled, aria-disabled="true" opacity 0.45, cursor: default, no hover and no press

Disabled is one model everywhere, useDisabled (src/components/ui/useDisabled.ts):

  • disabled renders aria-disabled="true" and .is-disabled, never the native attribute. The title stays live (some webviews show no tooltip on a native disabled button), and the control stays focusable, so a keyboard still reaches it and a screen reader hears that it is disabled.
  • The component swallows its own activation, a click and Enter or Space, in the capture phase, so the caller's @click never runs. A field refuses typing, a slider refuses a drag, and the arrow keys skip a disabled segment, tab or row.
  • disabledReason takes over the tooltip while disabled. Say why and what lifts it ("Run the study first").
  • clickable (on IconButton) is the soft block: greyed and aria-disabled, but the click comes through, for a control whose press explains or lifts the block, like Path traced under the performance block. Use it only when that click does something useful.

Where the styles live

Each base component has one partial, src/styles/ui/_<name>.scss, forwarded once from src/styles/ui/_index.scss, which main.scss loads before _glass.scss (tests/ui/uiStyles.test.ts). The state looks every component shares are _states.scss. A base component carries no SFC <style> block. A partial reads tokens only: no colour literal, no var() fallback, no literal duration or easing, and a radius only from a radius token, or a calc() on one for an inner radius. The guard test fails on any of them (15).

A few base components still wear the classes of the markup they replace, and their looks stay there until that markup is gone: Button is the one .btn rule in _glass.scss (a variant sets only --btn-fill and --btn-hover), IconButton at lg is .icon-btn in _float.scss and _glass.scss, the Select well is .sm-select, Dialog is .modal-panel, Panel is .measure-panel, Card is .float-card and Popover is .float-popover. Change those looks where they are, never by restating them in a partial or a caller.

The controls guard

node scripts/check-ui-controls.mjs runs in CI right after the repo hygiene step, and tests/ui/uiControls.test.ts runs the same scan (scanControls in scripts/uiControls.mjs) in npm test. Outside src/components/ui/ it counts, per file:

Kind Where Use instead
button, input[type=…], select, textarea src/**/*.vue and plugins/**/*.vue templates the base component the message names: Button, IconButton, TextField, NumberField, Checkbox, Slider, Select
role=button, switch, tab, radio and the menuitem roles on a plain element the same templates Button, Switch, Tabs, Segmented, MenuItem
createElement:button and the other control tags, and those tags in a template string or innerHTML src/**/*.ts and plugins/**/*.ts the factories of src/components/ui/dom.ts, prescribed, no code does this yet
style:inline a :style or a style object with a colour, a border or font a class in src/styles/ that reads tokens
NumberField:no-unit a NumberField with no unit, caption, unitless or v-bind spread, or only a blank, null or false one unit="mm" (or a bound :unit) so the unit is spoken, unitless for a count or a ratio
IconButton:no-tip an IconButton without tip tip, which names it
class:btn, sm-input, pref-seg, ft-switch, param-switch, check the templates, only under --legacy-classes, which goes on once the old classes are gone Button, TextField or NumberField, Segmented, Switch, Checkbox

scripts/ui-controls-allow.json is a ratchet like COLOUR_BASELINE: one entry per file and kind, with an exact count and a reason. A count above its entry is a new raw control and fails. A count below fails too, so a migration cannot leave room behind it: run node scripts/check-ui-controls.mjs --lower, which lowers each entry to what it finds, drops the spent ones and never raises one, and commit the lowered list with the migration. Never raise an entry by hand. A new one is only for a control with no base twin yet, like a native colour picker, and its reason has to convince the review.

7.1 Floating card (.float-card)

Card.vue draws it: <Card title="History">, with collapsible and v-model:collapsed for a card that folds. Glass group A, --float-radius, overflow: hidden.

Part Recipe
.float-card-head flex, gap --s-2, padding 10px 10px 6px 14px
.float-card-title --fs-body, 600, --text
.float-card-close, .float-card-more The small icon button, see below
.float-card-body padding var(--s-1) var(--s-2) var(--s-2), scrolls, overscroll-behavior: contain
.float-card-foot padding 4px 6px, no divider line
Section label (.panel-title) --fs-micro, 700, uppercase, letter-spacing 1px, --text-mute

The small icon button is IconButton at size="md" with variant="plain". It is not tied to a card: it works in any glass surface, a card head, a Panel, a popover. Use it for any 28px icon action (close, copy, more) instead of a new class.

State Recipe
Idle 28 by 28, no fill or border, --float-tile-radius, squircle, --text-mute, icon 14
Hover fill --hover-wash, colour --text
Pressed transform: scale(0.94)
Disabled the disabled model, no hover
Focus visible the shared outline
Transition background, color, transform, each var(--t-fast) var(--ease)
Touch inset: -6px hit area
Markup title and aria-label from tip, <Icon> inside

The old markup for it, .float-card-close and .float-card-more (base in _float.scss, squircle in the control list of _glass.scss, hit area in _touch.scss), is the same button with a --raised hover. Panel's close still wears it.

7.2 Icon button (.icon-btn, IconButton.vue)

lg with variant="tile" is the viewport tile, inside a .float-group (glass A, padding 3px, gap 2px).

Size and variant Idle Hover On (active, aria-pressed)
lg tile (default) 40 by 40, no fill or border, radius calc(var(--float-radius) - 4px), squircle, --text-dim, icon 20 fill --raised, colour --text linear-gradient(var(--accent-wash), var(--accent-wash)), var(--float-tile-bg), colour --accent-hot, no shadow
md 28, sm 24, plain --float-tile-radius at md, --float-chip-radius at sm, --text-mute, icon 14 fill --hover-wash, colour --text as lg
danger as plain fill --error-tint, colour --error as lg
State Recipe
Pressed transform: scale(0.94)
Disabled the disabled model, no hover
Focus visible the shared outline
Badge badge draws an xs error Chip on the corner, and the aria-label reads "Name, 3"
Warn .perf-warn colour --warn, hover and active fill warn 16%
Touch sm and md grow a hit area, 8px and 6px each way

7.3 Rail tile (.rail-btn, .rail-tile, .rail-pill)

RailButton.vue. The tile is glass A at --rail-tile, --float-tile-radius, filled with --float-tile-bg. The pill (label) is glass A, --float-chip-radius, filled with --float-chip-bg, padding 3px 9px, label .rail-label --fs-body/600, sub label .rail-sub --fs-micro --text-mute. The pill is at most 14rem wide and its label and sub label wrap (overflow-wrap: break-word, hyphens: auto), so a long translated name grows the pill taller, never cut.

State Recipe
Hover tile fill linear-gradient(var(--hover-wash), var(--hover-wash)), var(--float-tile-bg), translateY(-1px); the pill does not change
Pressed transform: scale(0.94)
Selected .active, held .holding tile fill linear-gradient(var(--accent-wash), var(--accent-wash)), var(--float-tile-bg), icon --accent-hot, label --accent-hot; no ring, no halo
Disabled .disabled opacity 0.45
Focus visible the shared outline, on the .rail-btn button
Transition transform, background, border-color, box-shadow, color, each var(--t-fast) var(--ease)

7.4 Buttons

Button.vue. Its fills are the tokens of 2.3, set by the one .btn rule, never restated. A button has no visible border; its 1px solid transparent only keeps its size.

Variant Idle Hover (:hover:not(.is-disabled)) Notes
secondary (default) squircle, chip radius, fill --float-chip-bg, no shadow, 500 --hover-wash over the fill
primary fill --accent, text --on-accent, 600, no shadow fill --accent-hot One per dialog, last in its footer
ghost no fill, --text-dim --hover-wash, --text A quiet action beside a primary one
danger the chip fill, text --error --error-tint over the fill A destructive action, as Remove
On (pressed) --accent-wash over the fill, --accent-hot the wash and --hover-wash together A primary that is on fills --accent-hot
Size Recipe
sm min height 28px, padding var(--s-1) var(--s-3), --fs-small; a hit area under touch
md (default) min height 32px, padding var(--s-1) var(--s-4), --fs-body
block full width

Pressed is transform: scale(0.97), focus the shared outline, disabled the disabled model with the fill kept.

Markup that predates Button still wears the classes by hand: .btn and .btn-primary (the same rule), .pop-wide and .palette-btn (a full width .btn, which block gives), .choice-btn (the chooser in ModalHost.vue, which ConfirmDialog replaces), .tb-btn in the title bar (26 by 24, --panel-2, disabled 0.3) and .tl-btn in the History transport (26 by 26, --float-chip-bg, --r-sm, disabled 0.3). .modal-close is the close button Dialog draws (transparent, --text-dim, close icon 15px, "Close"); keep the class, the e2e scripts click it. The bare button rule (_layout.scss) still paints every raw button, with no disabled state; it goes with the last raw button.

7.5 Inputs and selects

A field is a sunken well: --field-bg, darker than the surface it sits on, ringed by the inset 1px --control-edge (box-shadow: inset 0 0 0 1px, never a border or outline). Focus draws the shared ring on the well, offset 1px, not on the input inside it, and the error state keeps it.

Component Idle Focus Error and other states
TextField, NumberField (.ui-field) squircle, chip radius, fill --field-bg, the inset --control-edge; md 32px, padding 0 var(--s-3), --fs-small; sm 24px, padding 0 var(--s-2), --fs-micro; placeholder --text-mute; NumberField in tabular numbers outline: var(--focus-ring-width) solid var(--accent) on :focus-within, offset 1px, no ring .is-error: fill --error-tint, the accent ring kept, the reason tells the error; disabled, the disabled model
UnitChip (.ui-unit-chip) a 600 --text-mute word on no fill, inside the well picker: hover and open --accent-hot on --hover-wash, pressed --accent-wash
Select (.sm-select.select-trigger) as the field, plus a .select-caret, a 10px caretRight Icon in --text-dim centred in the 26px right padding, never a background layer; sm 24px; the chip variant has none as the field, the edge kept .is-open: accent 14% into the well, the caret turns 90deg about its centre to point down (--t-fast), and a .float-popover.select-pop of .opt-rows whose keyboard row is .is-active, washed; hover never moves the caret; disabled keeps its caret; in forced colours it draws in the mapped text colour

Keys. TextField in change mode and NumberField: Enter commits, blur commits, Escape goes back to the last committed text and ends a preview; text that does not commit stays, with aria-invalid and the reason in its title. NumberField steps with ArrowUp and ArrowDown, ten times with Shift, inside min and max. Select is a role="combobox" trigger over a role="listbox": ArrowDown or ArrowUp opens it and moves, Home and End, type ahead, Enter or Space picks, Escape closes and gives focus back to the trigger.

Combobox keeps focus in its input (role="combobox") over a ChoiceList in driven mode: ArrowDown and ArrowUp move the aria-activedescendant row, without wrapping and skipping a disabled one, Enter picks it, and every other key edits the query. Listbox is one Tab stop: Left and Right step one option, Up and Down one row of the grid (its columns measured from where the options sit), Home and End, type ahead on the label, no wrapping, a disabled one skipped. Moving focus never selects, since a pick may start a render: Space selects, and Enter emits apply. With multiple (aria-multiselectable) Space toggles, Shift with Space or an arrow takes the run from the anchor, and Cmd+A on macOS or Ctrl+A elsewhere takes every enabled option. It stops the keys it uses from reaching the window shortcuts, so an arrow in a grid does not also turn the view. For plain rows its option slot holds a ListRow with as="option", bound to the slot's attrs, and aria-label when speech says more than label and hint (GeometryList.vue).

Old fields that still paint: .sm-input (dialogs, the dock), .param-row input (feature values; .input-error and .param-stale use hard coded reds and ambers), native <select>s, and .dim-field in the value box (7.16). Fields keep a visible focus; never outline: none without a replacement.

7.6 Checkboxes, switches and sliders

A setting is toggled with Checkbox. A switch is for a live toggle in a tool panel or popover, where the change shows in the model as you flip it.

  • Settings pages (Preferences, plugin settings, the plugin list, the sketch palette) use Checkbox, or the .check markup of _checkbox.scss it replaces. Never put Switch, SwitchRow, .ft-switch, .param-switch, ToggleRow or Toggle in anything Preferences renders, the guard test fails on it.
  • Live toggles use SwitchRow: layout="float" in the view controls (the old Toggle.vue, which now draws it, and its .float-toggle row), feature properties use ToggleRow, a FieldRow layout="param" row holding a Switch (the old .param-switch is retired; SwitchRow layout="param" stays unused there). The Export dialog and the Stress setup and results steps keep their switches too.
Component Idle On Disabled Focus
Checkbox (.ui-checkbox) an 18 by 18 box, squircle, radius half the chip radius, fill --check-off, the inset --control-edge; hover --hover-wash over it. The native input lies over the box, so ids, labels and change handlers stay native; Space flips it once .is-on: fill --accent and no edge, a --on-accent tick, hover --accent-hot; .is-mixed (indeterminate) a bar instead of the tick the box and label fade, no hover the ring width, offset 2px, round the box
Switch (.ui-switch, role="switch", aria-checked) 36 by 20, --r-pill track --raised-2 with the inset --control-edge, knob 14px --text; hover --hover-wash over the track; pressed, the knob stretches .is-on: track --accent and no edge, hover --accent-hot, knob translateX(16px) in --on-accent the disabled model the shared outline
SwitchRow (.ui-switch-row, a <label>) float: padding 6px var(--s-1), squircle, chip radius, --fs-body, the state "On" or "Off" in --fs-small --text-mute, row hover --hover-wash; param: a --fs-small --text-dim label with the switch at the end the switch's the row fades as a whole, the switch inside does not fade again the switch's
Slider (.ui-slider) label --text-dim, a 4px --r-pill track filled --accent up to the value, past it --control-edge over --check-off (a 4px rail takes the edge colour whole, not as a rim; .profile-slider too), a 14px --text thumb, the value in --fs-small tabular --text-dim; hover scale(1.15) on the thumb, pressed scale(1.25) and --accent-hot the disabled model the ring round the whole .ui-slider row, chip radius, through :has(.ui-slider-input:focus-visible); round the thumb, offset 2px, only where :has is missing, as WebKit paints no outline on the thumb

A click anywhere on a SwitchRow flips the switch once, since the row is the switch's label. The old .sm-slider is a native range with accent-color: var(--accent).

7.7 Tabs and segmented controls

Component Idle Hover Selected Focus
Segmented bar (.ui-segmented-bar) one well, --field-bg with the inset --control-edge, padding 2px, squircle, chip radius; segments calc(var(--float-chip-radius) - 2px), --text-dim, 500; md --fs-body, sm --fs-small --hover-wash, --text .is-selected: --accent-wash, --accent-hot, 600 the shared outline, inset
Segmented chips (the Render dock) separate chips in --float-chip-bg, md 32px, sm 24px --hover-wash over the chip as bar the shared outline, inset
Tabs underline (a card, .float-tabs) --fs-body, 600, --text-dim --text .is-selected: --text and a 2px --accent underline from 25% to 75% the shared outline, inset
Tabs bar (a dock) 32px chips, --fs-small, 500, --text-mute --hover-wash, --text-dim --accent-hot and a 2px --accent bar under it (a bar, not a fill) the shared outline, inset
Tabs nav (a settings page list) full width rows, min height 32px, --fs-body, padding var(--s-2) var(--s-3) --hover-wash, --text --accent-wash, --accent-hot, 600, aria-current the shared outline, inset

Both are one Tab stop: the arrow keys move and pick, Home and End go to the ends, and a disabled item is skipped. Segmented is a radiogroup of radios, Tabs a tablist (ArrowUp and ArrowDown when vertical, nav is vertical by default). Each page sits in a TabPanel (panels, value), a tabpanel labelled by its tab; the nav look has no tab panels.

A tab that cannot be chosen yet (the Stress panel's Results before a Run) passes disabled and a title saying why: opacity 0.45, cursor: default, no hover. Keep it in the bar rather than hiding it, a bar of one tab reads as a title.

The old markup: .pref-seg > button (Preferences, .on in --accent-tint-2), .seg-btn (the title bar Model or Render, .active in --accent-tint-2), .rd-tab (the Render dock, .active with an --accent bottom bar) and .prefs-nav-btn (.active in --accent-tint).

7.8 Chips and key caps

Class Recipe
Chip (.chip) squircle, chip radius, fill --float-chip-bg, no edge; sm --fs-micro/20px, 500, --text-dim, padding 0 var(--s-2); md --fs-small/26px, 600, --text; accent: --accent-wash over the fill, --accent-hot; warn: warn 16% over the fill; error: --error-tint, --error. A button chip hovers --hover-wash over its fill; removable adds a 16px IconButton "Remove X"
Chip xs (a count badge) --fs-micro/16px, 700, tabular, min width 16px; on an icon it is solid, --accent with --on-accent, --warn or --error with --bg
KeyChip (.key-chip kbd) mono --fs-micro, --text-dim, padding 0 4px, radius 6px, fill --float-chip-bg, no edge; inTitle hides it from a screen reader
.rd-chip padding 3px var(--s-2), --panel-2, pill radius, --fs-micro --text-dim; hover --raised, --text; .active fill --accent-tint-2, --accent-hot; disabled opacity 0.55
#context-tab --fs-micro, 700, uppercase, letter-spacing 0.8px, padding var(--s-1) var(--s-3); .sketch turns it accent (--accent-hot, fill --accent-tint-2)
.tree-count --fs-micro, 600, --text-mute, --panel-2 pill, hidden when empty
.section-chip (SectionChip.vue) glass A in --float-chip-bg, chip radius, padding var(--s-1) var(--s-1) var(--s-1) var(--s-3), gap --s-2, 600 --fs-small --text, the section icon in --accent, pop-in; role="toolbar"; shown only while a cut is on, absent otherwise; under 560px, or when the top row is too narrow for them, the words hide and the icon's title says them
.section-chip-btn chip fill of .pop-wide, chip radius, padding var(--s-1) var(--s-3), 600 --fs-small --text-dim; hover --text; .active (Edit while editing, aria-pressed) as .dim-btn.on; .disabled with aria-disabled opacity 0.45, no hover; shared focus outline; a 40px hit area on touch
.updating-chip (UpdatingChip.vue) glass A in --float-chip-bg, chip radius, padding var(--s-1) var(--s-3), gap --s-2, 500 --fs-small --text-dim, pop-in, role="status", pointer-events: none so a pick goes through to the model; a 10px ring spinner in --accent on a 25% accent track; shown while a rebuild other than a tool preview has run past OUT_OF_DATE_GRACE_MS (600 ms, app/staleModel.ts), gone when it lands, is cancelled or the document is replaced; it never ghosts the model

The chips on the model and in the dock above keep their own markup until they wear Chip.

7.9 Rows

Class Idle Hover Selected Disabled
ListRow (.ui-list-row) padding 7px var(--s-3), --fs-body, squircle, chip radius, icon --text-dim; pressed --accent-wash; focus the shared outline, inset --hover-wash, icon --accent-hot .is-selected: accent 16% fill, --accent-hot the disabled model, no hover
.opt-row (ChoiceList.vue) padding 7px var(--s-3), --fs-body, chip radius white 5% wash .selected: accent 16% fill, --accent-hot; in a Combobox the active row is also .is-active .disabled opacity 0.45, no hover
.ctx-item (context menu) padding var(--s-3) var(--s-4), --fs-body, chip radius, .ctx-key --fs-micro --text-dim accent 16%, --accent-hot .disabled opacity 0.45, pointer-events: none
.menu-item (title bar menu) padding var(--s-3) var(--s-4), gap --s-7, .menu-shortcut --fs-micro --text-mute accent 16%, --accent-hot .menu-check gutter in --accent [disabled] --text-mute, pointer-events: none
.cmdk-item a Combobox option (role="option"), padding var(--s-3) var(--s-4), gap --s-3, chip radius .is-active (pointer or keys, the aria-activedescendant row): accent 16%, --accent-hot
.tree-folder, .feature-row, #timeline .timeline-node padding var(--s-2) var(--s-1) on .tree-folder, --s-2 on the others (History rows 34px tall), chip radius --raised .selected: accent 16% fill, --accent-hot

A destructive row is red text: MenuItem with danger is --error, hover --error-tint. The old .ctx-item.danger (Remove body) still uses hard coded reds. Tree rows (TreeRow, TreeFolder, InlineLabel) keep their own keys and drag; new rows of that kind wear the ListRow look.

The sketch palette holds three lists under one heading each (SketchShapesList, SketchDimensionsList, SketchRelationsList), shown as a list of rows, never as controls on the canvas:

  • Shapes and Relations rows are a ListRow button with a spoken aria-label (the shape with its freedom, the rule with what it holds). A row that can be removed sits in an li.rel-row with a sibling IconButton (.rel-del, danger) named Delete and the same words. The button is a sibling, never inside the row button, so Tab reaches both. It shows on hover and on :focus-within, and stays in the tab order while hidden.
  • A row with a label and a control wraps: a control that does not fit beside its label moves to its own line under it, in every language, and a label is never cut with an ellipsis. FieldRow inline and param rows and .stress-field get this from the wrap-row and wrap-label mixins in src/styles/ui/_field-row.scss; a new row of this kind includes them, and a row that fits looks as it did. The rows of one group that should start their boxes at one x (the Stress material and its custom values) wear .stress-keyed, which gives their labels one share of the row. In plain text a .param-row select takes the width of its whole value (at least 120px), so a long option such as "Plan de l'esquisse" is read in full or the row stacks; Comfortable text wraps the value instead.
  • A Dimensions row is a FieldRow with a NumberField (commit="change", the unit of the dimension), named by the dimension's subject. A driven dimension is disabled and says why.
  • The line above Relations (.rel-summary) takes focus after a Delete, so the keys do not fall back to the page. A freedom change is spoken through the announcer, not by a live region on the list.
  • Freedom is words, never colour alone: a shape is "free in X", "free in X and Y", "free in size" or "fixed".

7.10 Popovers, menus, dialogs, palette, toasts, prompt

Surface Recipe
.float-popover (Popover.vue) glass solid, --float-radius, padding --s-3, min width 220px, z-index: var(--z-popover), glass-in entrance. Content: .pop-section --fs-body/600, .pop-rule a 10px gap with no line, .pop-note --fs-small --text-dim line height 1.45
Menu (.ui-menu) --float-bg-solid through --float-blur, --float-tile-radius, squircle, padding 5px, --float-shadow, --fs-body, pop-in. MenuItem (.ui-menu-item): padding var(--s-3) var(--s-4), chip radius; hover and keyboard focus accent 16% and --accent-hot, pressed accent 24%, keys .ui-menu-keys --fs-micro --text-dim, a check gutter when any item has checked; MenuSeparator 1px --line
.context-menu, .menu-popup the right click and title bar menus that predate Menu: glass solid and glass B, --float-tile-radius, separators .ctx-sep 1px
Dialog (.modal-panel.ui-dialog) glass B with --shadow-3, --float-radius, on .modal-overlay; sm min(420px, 0.92 * var(--win-w)), md 560px, lg 720px, unset is the .modal-panel width. .modal-head, .modal-body, .modal-foot share padding --s-5; head and foot are layout dividers, 1px solid var(--line); h2 --fs-title/600 and the .modal-close button in the head; the footer slot is right aligned, gap --s-3, Cancel present, one primary. role="dialog", aria-modal, aria-labelledby the h2
ConfirmDialog (.ui-confirm) a sm Dialog: the message in --text-dim, then one button per answer in even columns that fill the footer, the primary one focused, or with multi a checklist with Cancel and a confirm; danger paints the primary --error on --error-tint, and an option's own danger paints just that answer, so Cancel can keep the focus (confirmDanger in ui/choice.ts: Cancel first, then the red action)
.cmdk-card glass B, --float-radius, min(560px, 0.92 * var(--win-w)), on .cmdk-backdrop at padding-top: calc(0.12 * var(--win-h)), role="dialog", aria-modal, aria-label="Command palette"
.measure-panel see 7.13
.toast glass B, --float-tile-radius, padding var(--s-3) var(--s-4), --fs-body, bottom centre in .toast-stack; .toast-error and .toast-warning tint the fill; .toast-action accent chip
#viewport .prompt glass A, pill, padding var(--s-3) var(--s-5), --fs-small, a 6px accent dot, prompt-in entrance
#viewport .vp-top the top middle stack of the Section chip and Normal to Sketch: absolute, top --s-4, a column with gap --s-2, centred in the span the cards leave free (useClearOfCards.ts sets --row-left and --row-right, as PromptBanner does); when that span is too narrow it sets data-narrow (the chip drops its words), and when that is not enough it moves the stack down to the first row with room (--row-top), z-index: calc(var(--z-float) - 4), pointer events only on its children

Dialog holds the modal gate (composables/useModalGate.ts) while open, keeps Tab inside, focuses the [autofocus] control or else the first control after the close button, and gives focus back to its opener on close. Escape closes the topmost dialog only. ModalFrame.vue is the frame plugins import over it: the same Escape and focus moves but no gate, and props to opt out of Escape and focus for a plugin that still does those itself. Menu takes the arrows, Home and End, type ahead, Enter or Space to choose and close, ArrowRight and ArrowLeft into and out of a submenu, and Escape through claimEscape, and gives focus back to its opener. Popover with focus="first" moves focus into the card (or onto it, when it holds no control), and returnFocus gives it back on close.

A context menu and the selection state of the shell

Preferences: a glass dialog with inset wells and one primary button

7.11 Tooltips

There is no tooltip component. A tooltip is the native title, and a title is a bonus for the mouse only: VoiceOver and Orca mostly skip it, and a keyboard, touch or switch user never sees it. So a title never carries the only name, a state or an error. An icon only control takes an aria-label with the same text as its title, and the shortcut goes in brackets, written as in 9: title="Reset camera (Shift+Home)". A base control writes both from tip and keys: <IconButton icon="history" tip="History" :keys="chordKeys('history')" />, where a window chord that differs per platform (Items, History, the console) comes from chordKeys() or chordHint() in src/input/platform.ts, never a literal. A Button with a word keeps the word as its name and takes the tip as its title only, and while a control is disabled its disabledReason is the title. Anywhere else, a text that names Ctrl or Alt goes through fmtKeys() (src/input/platform.ts), which writes the Command and Option glyphs on a Mac: :title="fmtKeys('Redo (Ctrl+Shift+Z)')". Do not invent a tooltip popover. On the model, where a hand cannot spare a hover, show a real element instead.

State goes where every reader gets it: in the name, in aria-describedby pointing at text, or in a .sr-only span (_utilities.scss) beside the visible text, with the visual mark aria-hidden. The title bar's unsaved star is aria-hidden and followed by <span class="sr-only"> Unsaved changes</span>, a History chip says its file, its error or note, switched off or suppressed and rolled back in an .sr-only span after its name, a failed tree row adds ", failed", and a show or hide eye says its state through aria-pressed. A detail that only adds to a name, such as a home card's full path, goes in aria-describedby on a hidden span, and its title can stay.

7.12 Plugin UI

A plugin cannot add selectors to _glass.scss, so it draws with what the host gives it. fundacad/ui (src/plugins/hostUi.ts) exports the base set: Button, IconButton, Chip, KeyChip, TextField, NumberField, UnitChip, Select, Checkbox, Switch, SwitchRow, Segmented, Slider, Tabs, Menu, MenuItem, MenuSeparator, Popover, Dialog, ConfirmDialog, Panel, Card, FieldRow, ListRow, ReadoutList and Toolbar, with the SegmentedOption and TabItem types, plus Icon and InlineLabel. They are the app's own components, not copies, so a plugin and the app cannot drift (tests/components/plugins/hostUi.spec.ts).

The names it exported before stay: FloatingPanel and ModalFrame (the old contracts over Panel and Dialog), and the Render dock rows RenderSection, RenderSlider, RenderSwitch and RenderChoices. Inside them, use base components and tokens, and the .measure-* classes of 7.13 for a readout. The guard counts the raw controls in plugins/ too. Never ship a plugin panel with its own background, blur or shadow.

7.13 Tool and readout panels (.measure-panel)

Panel.vue is the shell; it draws the glass, and on request a head and a hint. FloatingPanel.vue is its old name, taking only open, a required title, closeOnEsc and panelClass; it passes titleHidden, so its content draws the visible head and marks that copy aria-hidden="true".

defineProps<{
  open: boolean;
  title?: string;
  hint?: string;
  titleHidden?: boolean; // false
  closable?: boolean; // false
  closeOnEsc?: boolean; // false
  panelClass?: string; // ""
}>(); // slots: default, head-actions, foot
defineEmits<{ close: [] }>();
  • open is required. The root is a <Teleport to="body"> holding <div v-if="open" class="measure-panel ui-panel" :class="panelClass">, so class, title and other attributes on <Panel> are dropped. Size or move a panel only through panelClass and a rule for that class in _modals.scss (.properties-panel min width 260px, .stress-panel 340px wide and scrolling).
  • title draws the panel's name as its .measure-title, an h2, and names the panel (role="region", aria-labelledby), so heading keys and the rotor reach it. titleHidden keeps that h2 for screen readers only. A panel given no title (a plain JS plugin) is still a region, named by a hidden h2 that reads Panel; head-actions sit beside it and closable adds the 28px Close button after them. hint is the last line, a .measure-hint; the foot slot sits under the content. Without them the content is yours, from the classes below.
  • closeOnEsc adds a capture phase keydown listener on window that emits close and does not stop the event, so Escape also reaches the global handler (clearing the selection, leaving the tool). See 11 for when to leave it off.
  • Placement is fixed for every panel: position: fixed; top: 128px; right: 268px; z-index: var(--z-panel), outside #float-layer and under it, so the rail, the view controls and every dialog draw over an open panel. panelStack.ts sets top and right under the view cube and clear of the right cards, and a max-width that keeps a wide panel clear of the rail, again whenever a panel, a card or #float-layer resizes. When the span beside the rail is under a panel's min-width, the column moves to the highest shelf right of the cards that holds it (under History in a narrow Render stage), and only when none does it keeps its min-width beside the rail, under the cards. An open panel stays open across the Model and Render switch, as every inspect panel does, narrowing to fit the smaller stage, so a row of buttons in a panel wraps rather than clips. The cap is on the panel's box, so a child with a fixed width or a min-width runs out of the glass and under the rail: size wide content with max-width: 100%, never against the window (vw), and let it reflow. panelClass measure-panel-column hands the panel's height cap down, so a scroller inside it with min-height set shrinks and the rows around it stay in view. The in-view chips (.dim-input, .sketch-dims, .snap-tag, .prompt and the like) draw over a panel they meet, so a form with its actions at the panel's foot keeps --prompt-clear free below them. The shell is min-width: 180px, padding: var(--s-4), font-size: var(--fs-small). The Stress panel's least is 160px, so at 1024x600 with History open it keeps the full height column left of History rather than a short shelf; its rows, tabs and buttons wrap in that column and the quarter ticks of its colour scale give way.
Class Recipe
.measure-title 600, --accent-hot, margin-bottom: var(--s-2). The panel's name, one per panel
.measure-row flex, justify-content: space-between, gap --s-5, padding var(--s-0) 0. A label and a value; ReadoutList draws each pair as one, inside a dl
.measure-k the label, --text-mute; a dt in a ReadoutList
.measure-v the value, font-variant-numeric: tabular-nums; a dd in a ReadoutList
.measure-divider 1px --line, margin var(--s-2) 0
.measure-select, .measure-number the old small inline fields; new work uses Select and NumberField at sm
.measure-hint --fs-micro, --text-mute, margin-top: var(--s-2). The last line, saying how the panel closes ("Esc to close", "Esc to exit", "Overhang again to close"); hint writes it
Fields FieldRow with its control, for a label and something to change; .measure-row is for a label and a value. A .stress-field row wraps like a FieldRow (7.9)
Actions Button, or Button variant="primary" for the one main action; a 28px icon action is IconButton size="md" variant="plain" (7.1)

Do not add a head with its own padding: the shell padding is the inset, and a second padded head doubles it. A minimal readout:

<Panel :open="!!panels.measure" title="Measure" hint="Esc to exit">
  <ReadoutList :rows="rows" />
</Panel>

Pick fields

A tool that collects more than one selection gives each its own row, as MirrorToolPanel.vue does (.mirror-panel, .mirror-field in _modals.scss):

  • a 28px IconButton toggle first, active on the field that takes the next clicks, and the field name and value after it ("Nothing picked", "3 bodies", "XY plane");
  • a 28px clear button last (IconButton size="md" variant="plain", today a .float-card-close), disabled while the field is empty;
  • .mirror-field.active wears the selected row look, so the live field reads at a glance in both themes;
  • buttons take @pointerdown.prevent, so Enter after a click still goes to the tool, and the tool leaves Tab and Enter alone while focus is in the panel;
  • no closeOnEsc: the tool owns Escape, and the prompt banner says why a pick was refused.

7.14 Feedback: copy, toasts and errors

toast(message, opts) (src/ui/toast.ts) takes opts: { kind?: "info" | "warning" | "error"; action?: { label, onClick }; timeout?: number; detail?: unknown; source?: string }. It returns the toast's id for dismissToast, or null for an error.

  • info (the default) and warning show a .toast. noticeHoldMs (src/ui/noticeTime.ts) gives its time from the Notification time setting: info 5s, warning 8s, error notice 10s, any message with a button at least 15s, and a caller's timeout only lengthens that. Longer is three times it, Until dismissed has no timer (hold: null), and the error notice then shows a Dismiss button. A fourth toast evicts the oldest one without a button.
  • The same message, kind and action label again restarts the toast already showing, with the newer action, rather than stacking a copy.
  • error does not show a toast. It goes to the title bar notice (showErrorNotice) and the console log, with detail kept for the report.
  • Every toast is spoken once by announce() from toast(): info polite, warning assertive, and the label of a button is added ("Deleted Box 2. Undo button in Notifications."). An error is spoken by the title bar notice. The stack is a permanent region named "Notifications", empty when no toast shows, and is not live, so nothing is said twice.
  • Under a dialog or the command palette the stack is inert and aria-hidden with the page, below the backdrop, so no region sits beside the modal. A toast with a button then waits and gets its full time once the modal closes, one without keeps its time. Home keeps the stack live, as it keeps its toggle.
  • The console is not a dialog but a role="region" named by its h2 "Console" (tabindex="-1"). Show Console, the error notice and its chord (outside a text field) focus that heading, and closing returns focus to the opener. The body is role="log" with aria-live="off", since toasts already speak, and each row starts with a .sr-only Error:, Warning: or Info:.
  • Every toast is also a console entry and a bug report breadcrumb, so do not toast on every keystroke or hover.

Copy has two patterns, pick by the button:

  • An icon button that copies (the console's .logcon-copy): swap the icon to check and the title to "Copied" for 1200ms, then back. If the clipboard refuses, fail silently, the text stays selectable.
  • A text action that copies (McpSection's config): toast("Copied."), and on failure toast("Could not copy. Select the text and copy it.", { kind: "error" }).

A progress bar for a long job, such as the Camera tab's traced picture, is role="progressbar" with a name, aria-valuemin, aria-valuemax and aria-valuenow, and an aria-valuetext when the unit is not a percent (64 of 256 samples). It sits in no live region, and its values change at most once a second, and at once at each quarter and at the total (src/ui/renderProgress.ts), so a reader is never pushed a number per frame. The button that starts the job keeps one name while it runs. Its speech goes through announce(): start, finish and cancel at Normal, each quarter at Verbose, and a failure drops a waiting line before its error is spoken. The start is said at the job's first report, so a job that never begins is not heard as one, and a finish whose result can no longer be used is not said. Escape in the job's tab cancels it too, see the Escape table in 11.

7.15 Marks in the scene

The origin triad and the origin plane tiles are drawn in the 3D scene, so the guard test cannot see them; hold them to these rules by hand.

  • Picks on the model follow --accent through one rule, pickColor in src/viewport/pickColors.ts: keep the accent's hue, raise its chroma to at least 0.12, and move its lightness away from the colour under the pick until what is seen clears a WCAG contrast floor against it (select 3.0, hover 1.6). A selected face takes the pick as its shaded tint and is drawn again as a 0.7 overlay, which is what Path traced, glass and an untinted Matcap show. A hovered face is only a 0.4 overlay, a light wash, so it never reads as a selection. A face is measured against its own colour, an edge against the faces beside it (a selected one in its pick colour) and --viewport-bg (its silhouette), a sketch selection against --viewport-bg. A picked edge is drawn again wide, 3px selected and 2.4px hovered over the 1.6px idle edge. No glow and no outline is added. A theme change repaints every pick live (Highlighter.refreshTheme).
  • A face a Geometry row lights, by hover or keyboard focus, is hatched: thin diagonal stripes in the pick colour, 12 across the face, each 0.3 of its period, at the select overlay's 0.7 and depth tested like it (src/viewport/litHatch.ts). The stripes lie on the surface, so an orbit carries them with the face, and they fade to an even wash where a period nears 5px. A selected face keeps its tint, and a lit selected face shows both, its stripes measured against the tint. The hatch tells looking at apart from picked without colour, in every theme, where a lighter tint could not in High Contrast Light. Canvas hover keeps its wash.
  • Axis colours are the --axis-x/y/z tokens, read through axisColor (src/viewport/originTriad.ts), whose AXIS_COLOR holds Noir's red, green and blue. A plane takes its normal axis colour: XY blue, XZ green, YZ red in Noir.
  • Neutral parts read tokens through themeColor and are read again on a theme change.
  • Sketch curves take the seven --sketch-* tokens through the functions in src/sketch/overlay.ts (sketchFreeColor and the like), a conflict takes --error. The open sketch redraws on a theme change, and installViewportWiring redraws the sketches that are not open. Colour-Blind Safe holds six pairs apart (overlaySeparation in src/ui/contrast.ts): free and projected, free and construction, projected and construction, free and defined, projected and its stale form, open and untied ends. Each pair is ΔE2000 15 or more under every dichromacy, or 10 L* apart. Noir and the other dark themes keep free and projected close in hue, so projected geometry relies on its dashes there.
  • Colour never carries a sketch state alone. Construction geometry is drawn in short dashes (gap to dash 0.63), projected geometry in long ones (14px dash, 3px gap, 0.21, sized in screen pixels so the ratio holds at every zoom), a free curve is solid. A loose end that touches nothing is a ring (LOOSE_RING_PX), an end that meets a curve with no rule a dot. The badge and glyph layers over the canvas are aria-hidden (not inert, a pointer still edits them), the palette lists carry what they say.
  • Sizes are screen pixels, held through gizmoScale.ts at every zoom.
  • Each tile spans the positive side of its two axes, set 10px out from both arrows (TILE_GAP_PX), so its two inner edges run parallel to the arrows and the three tiles stand apart instead of meeting at the origin. A tile is as long as an arrow, 64px, and while the tiles show both share one floor, so a tile edge and an arrow stay equal at every zoom and never fall below about 41px (hidden, the arrows may shrink to their own floor, triadMinScale). The gap scales with the tile. All four corners are rounded, 27px, the same squircle as corner-shape: squircle, a rail tile's 17px on 40px scaled up (TILE_CORNER_RADIUS_PX and SQUIRCLE_EXPONENT in src/viewport/originTiles.ts and cornerProfile.ts). The inner rims show in the plane's colour beside the axis coloured arrows. While the tiles show, the arrows draw over the tiles and under their names (OriginTriad.drawOver).
  • A tile's name sits at its centre. Where the tiles overlap, the tile drawn in front keeps its name there and a name that would cover another name or sit on that tile walks toward its own far corner. A tile seen edge on has its name beside it, on the side away from the other tiles. A press on a name, or in the 44px box around it (48px under a coarse pointer), takes its plane, so a plane mostly hidden behind another keeps a full target. The names keep those boxes apart, moving off their walk when they must. Elsewhere, where tiles overlap, a press goes to the one drawn in front (placeLabels and pickPlaneOnScreen in src/viewport/planeHit.ts). The origin lies on no tile, so a mouse press there picks nothing, but under a coarse pointer the 48px box round a foreshortened tile may still reach it, as XZ's does at the home view: a full touch target is worth more than an empty origin.
  • What a body hides draws faint, not gone.
  • A name in the scene is a camera facing sprite, --ui 700 at 15px times the Viewport label size, inked in --text or --viewport-bg, whichever reads on the ground. It fades out when what it names is seen edge on.

7.16 Floating value box (.dim-input, DimInput)

The box beside the cursor or the gizmo while a sketch or feature tool runs. One class, DimInput in src/sketch/dimInput.ts, builds it for every tool; a tool passes fields and options and never styles its own.

Part Recipe
Box One glass chip on the _glass.scss lists (--float-chip-bg, chip radius, squircle, --float-shadow, --float-blur), padding 3px, gap 2px, one row 32px tall (36px under a coarse pointer). Nothing inside has a fill or shadow of its own
Field (.dim-field) Name tag, input, unit, 24px tall, radius 7px. The tag is the field's icon at 14px with the name in its title, or a one or two letter word (W, H, L, R, N, D, X, Y) in --fs-micro 700 --text-mute; tag adds an axis letter after an icon. Typed: --hover-wash
Input --field-bg, 22px tall, radius 6px, --fs-small 600 tabular numbers, at least 7ch wide and only wider past that, so typing a usual number never resizes the box; focus is the 1px --accent outline
Unit (.dim-unit) A --fs-micro --text-mute word on no fill that opens the unit menu; hover --accent-hot on --hover-wash
Option (.dim-btn.dim-opt) 24 by 24, radius 7px, a 16px icon in --text-dim, hover --text on --hover-wash; the name in title and aria-label, its word kept in a hidden .dim-word. Each option is one Tab stop after the fields, with the 1px --accent focus outline; Space or Enter presses a switch or an action
Switch (.dim-toggle) An on or off mode (Symmetric, Copy, Total, Tangent faces follow). .on: --accent 24% into --panel, --accent-hot ink, aria-pressed. In the light theme on is --accent-tint-2 with --accent ink, above 3:1 on the paper chip
Segmented (.dim-seg) A choice of 2 to 5 named values (fillet continuity, press pull mode and direction, hole type): one icon segment each, built from a list, the chosen one .on like a switch, role="radio" and aria-checked. Values whose glyphs read alike show a short name beside a 12px glyph (text, G1 and G2). The group is one Tab stop (roving tabindex on the chosen segment); the arrow keys move and pick, Enter commits. A segment that cannot be picked now is .disabled at 0.45 with the reason in its tooltip (disabled, setSegmentDisabled). A segment may own a key: bare when no field has focus, Alt with it inside a field, where the digit belongs to the number. Fillet continuity is 1 and 2
Action (.dim-action) A one off verb (Hole's Center), the option button with no on state
Confirm and cancel Last, 4px apart from the options, check in --ok and cross in --error, the hover a wash of the same colour
Error (.dim-bad) Every field --error-tint with --error text, the message in .dim-problem hung under the box
Place Beside the cursor 16px right of and below the point at its natural size, flipped to the other side where the window ends, clamped into a window too small for either; never over the point. Flipped above, the box takes .dim-above and its error line hangs over it. Beside a gizmo pastTip or placeBeside
Touch Buttons stay 24px under a mouse; a ::before grows each to 36px tall. Under @media (pointer: coarse) they are 30px, 6px apart, so the hit area reaches 36px each way, the floor over the model
Keys Tab and Shift+Tab walk the shown fields, the tool's extra controls, each option, then Confirm and Cancel, and leave the box off either end; Enter in a field commits, Enter or Space on a button is that button's (a tool's capture listener skips it through isBoxButtonKey), Esc cancels (the tool's capture listener). Fillet and chamfer keep Tab in the field or on the canvas as the flip, Shift+Tab from the field steps back onto Cancel, and Tab off Cancel moves on past the box. A tool can fill a field as a keystroke would with typeInto(name, text), which replaces a seeded value and otherwise appends, and a field with free is one the tool reads itself, as the X and Y of a key drawn point (KeyDrawFlow)

A number the tool needs is a small field, never a chip that cycles. A new option goes through DimOption (DimToggleDef with an icon, DimSegmentedDef or DimActionDef), with an icon from src/assets/icons/forge/.

8. Motion

Token Value Use
--ease cubic-bezier(0.2, 0, 0.15, 1) The one easing
--t-fast 110ms Hover, press, colour, the entrance of menus, toasts and the palette
--t-med 160ms Larger entrances: glass popovers, the chooser, the tool prompt

The standard transition is transition: background var(--t-fast) var(--ease), color var(--t-fast) var(--ease);. Transition only background, color, box-shadow, opacity and transform, never layout. The one layout property that moves is the width of a progress fill inside a fixed track (.timeline-busy .busy-bar i and .timeline-node .t-bar i and .rd-progress-track i at 0.4s var(--ease), .rd-emitting-bar at 120ms linear), because it moves nothing around it.

Off the scale, do not copy: profile-panel-in 0.14s ease-out (_utilities.scss), the error notice's err-pop on cubic-bezier(0.3, 1.6, 0.5, 1) and logcon-flash 1.6s (_notice.scss).

Entrances are small, 4 to 6px of travel and a scale of 0.97 to 0.98:

Keyframes From Timing Used by
pop-in (_titlebar.scss) opacity: 0; transform: translateY(-4px) scale(0.98) var(--t-fast) var(--ease) Menus, toasts, the palette, the console, the selection editor
glass-in (_glass.scss) opacity: 0; transform: translateX(-4px) scale(0.97) var(--t-med) var(--ease) Popovers, the chooser, rail flyout tiles (staggered by calc(var(--i, 0) * 16ms))
prompt-in (_utilities.scss) opacity: 0; transform: translateY(-6px) var(--t-med) var(--ease) The tool prompt

Menus, popovers and dialogs have no exit animation, they unmount. A toast fades out over 0.18s. No bounce, except the error notice's triangle (err-pop). Camera moves fly with smootherstep (viewport/viewFlight.ts), between 0.18s and 0.5s.

Reduced motion: src/ui/motion.ts sets <html data-motion="off"> from the Animations switch (Preferences, Accessibility), following the system's prefers-reduced-motion until the user chooses. _motion.scss, loaded last, sets every animation and transition to 0.01ms (not 0, animationend must still fire). So a CSS transition needs no code of its own. An infinite animation needs a still state under both @media (prefers-reduced-motion: reduce) and :root[data-motion="off"] (see busy-bar-still in _timeline.scss). Script driven motion checks motionOn() (or cameraFlightsOn() for the camera).

9. Voice and wording

The UI speaks like the manual (manual/docs/): plain, short, calm, second person, present tense. No exclamation marks, no emoji, no marketing, no "simply" or "just", no blame. Never name another CAD product; say "mainstream MCAD convention" if you must compare. No em or en dashes and no spaced hyphen as punctuation, join clauses with a comma (scripts/check-repo-hygiene.sh). The product is spelled FundaCAD.

Kind Rule Good Bad
Button One or two words, the verb of what happens Save, Discard, Remove from list, Open copy OK, Yes, Submit
Command that opens a dialog Title Case, real ellipsis character Save As…, Export…, Keyboard Shortcuts… Save as..., Export Dialog
Confirm A full sentence naming the object, the consequence in the hint "Save changes to Bracket before closing?" with Discard "lose the unsaved changes" "Are you sure?"
Error What happened in plain words, then the way out, joined with a comma; lead with "Could not" "Could not reach the clipboard, so the report was not copied." "Error: clipboard write failed!"
Rejection in a tool Say what to do next "That face is curved, a hole needs a flat face" "Invalid selection"
Success Short, past tense or present state, full stop "Copied.", "Bracket is installed." "Success!!"
Empty state One sentence about what will appear, maybe the next step "Your modeling history will appear here. Start with a Sketch, or drop a STEP, STL or 3MF file." "Nothing here :("
Tool prompt Imperative, parts joined by " · ", ending with the key to leave "Click a profile · Ctrl-click adds areas · Enter" "Please select a profile to extrude."
Tooltip What the control does, sentence case, shortcut in brackets "Reset camera (Shift+Home)" "Camera"
Setting A noun label, then 1 to 3 sentences on the effect and the default Animations: "Off makes every transition instant…" "Enable animations?"

UI names are proper nouns mid sentence: History, Items, Home, Preferences. Tool names are Title Case (Linear Pattern, Press/Pull). Keys are joined with a plus, as in the menus, the command palette and the hint tables: Ctrl+S, Ctrl+Shift+Z, Shift+Home, Esc, Enter. Write Ctrl and Alt, never the Mac names, and show any text that names them through fmtKeys() (src/input/platform.ts), which turns them into the Command and Option glyphs on a Mac; Control+ names the literal Mac Control key and shows as its caret glyph. Use "No X yet" for lists that will fill and "X appear here" for passive sources. Technical engine text goes after a plain lead; the full text is kept in the console.

New UI text goes through t(), with its English line in src/i18n/locales/en.json and a translation in every other language file; I18N.md shows how to add a line or a language.

10. Light and dark themes

src/ui/theme.ts applies a theme by writing the colour tokens inline on <html>, plus color-scheme. Only the tokens in PALETTE_TOKENS change, as hex or rgb()/rgba() values: --bg --panel --panel-2 --raised --raised-2 --viewport-bg --line --line-strong --text --text-dim --text-mute --accent --accent-hot --accent-tint --accent-tint-2 --on-accent --ok --warn --error --error-tint --pick-line --accent-blue --axis-x --axis-y --axis-z, and the seven --sketch-* curve colours. Shape, glass, motion and z tokens never change from a palette. A palette that sets the retired --accent-glow still loads, the token is dropped.

Shipped: FundaCAD Noir (built in, dark), Dracula, Solarized Light (the light one: --bg #fdf6e3, --panel #eee8d5, --raised #ffffff, --text #073642, --text-dim #3a4f55, --text-mute #4d6165, --accent #25669b, --accent-hot #173f5f), FundaCAD Light (Noir's violet on paper, --bg #f5f3f9, --panel #ebe8f2, --text #1b1826, --accent #4a4fb5), High Contrast Dark and High Contrast Light, Colour-Blind Safe, and the Noir Blue, Red and Orange tints. Users can upload their own palette.

The High Contrast pair keeps a higher bar than the rest: every text token at 7:1 on every surface and on the panel glass, and --line-strong, --control-edge, the signals and the focus ring (--accent) at 4.5:1. Their surfaces are near black or near white and set --control-edge outright. The dark one uses a cyan accent, as yellow is --warn.

The same workspace in Solarized Light

The light theme

apply() in theme.ts toggles the class html.theme-light for every palette whose mode is light, shipped or uploaded. An uploaded light palette needs nothing more than "mode": "light": the :root.theme-light block in _tokens.scss derives the paper cards from its --raised, --bg, --panel and --text, so the cards follow the palette.

  • Paper cards. The card is a near white sheet: --float-bg-solid mixes --raised into --bg, and --float-bg is that at 97%. A tile is a step darker than the card, a chip another step, and a field a grey well (--field-bg mixes --text 11% into the card). --hover-wash and --check-off are mixes of --text.
  • Soft shadows. --float-shadow, --shadow-2, --shadow-3 and --shadow-pill are inked in --text and soft. A black offset slab reads as a hole on paper.
  • Clear of the grid. Floating chips, tiles and rails over the viewport stand clear of the pale scene: a card against --viewport-bg must reach a contrast above 1.15:1.
  • Readable text. Every text token (--text, --text-dim, --text-mute, --accent, --accent-hot) reads at 4.5:1 or better on every fill it sits on: the card, the solid card, a tile, a chip and a field. --on-accent on --accent is held above 4.5:1 too. A light theme's --accent-hot is darker than its --accent, not lighter, because it is text on an accent tint.
  • Signals stay apart. --ok, --warn and --error read at 4.5:1 as text on --panel and --panel-2, and --pick-line at 3:1 on --viewport-bg. Two signals that a protanope, deuteranope or tritanope sees within ΔE2000 15 of each other differ by at least 10 L*, so lightness tells them apart where hue does not (deltaE2000 in src/ui/contrast.ts).

tests/ui/designSpec.test.ts and tests/ui/themeContrast.test.ts hold these numbers for every shipped light theme (Solarized Light, FundaCAD Light and High Contrast Light). In every theme the focus ring reads at 3:1 on each surface and the axes at 3:1 on --viewport-bg.

What this means for you:

  • Build every fill from --panel, --panel-2, --raised, --line*, --text*, --accent*, the fill tokens of 2.1 or color-mix of them. The glass fills mix --panel, so glass recolours itself.
  • Do not add white or black overlays of your own. The fill tokens carry the light variants. A hard coded dark fill stays dark on a light theme and its text becomes unreadable, so viewport readouts are glass chips, and tests/ui/themeContrast.test.ts rejects a hard coded dark readout fill.
  • Check every screen in FundaCAD Noir and Solarized Light (Preferences, Appearance, Theme).

11. Accessibility

Focus:

  • The shared outline (_base.scss): :focus-visible { outline: var(--focus-ring-width) solid var(--accent); outline-offset: 1px; }. --focus-ring-width is 2px, and every focus outline reads it (tests/ui/focusRing.test.ts). It shows on keyboard focus only, never on a pointer click, and it is the one outline on a rounded surface (Depth without lines).
  • Fields (TextField, NumberField, Select, and the old .sm-input, .param-row input and Items filter) draw the same ring at a 1px offset while focused, and an error keeps it. Checkbox draws it at a 2px offset around its box. Slider draws it round its whole row through :has, since WebKit paints no outline on the thumb, and round the thumb only where :has is missing.
  • Tabs, segments, menu items and list rows use an inset outline (outline-offset: calc(-1 * var(--focus-ring-width))), so a clipped row does not hide it. On the rail the outline is on the .rail-btn button, not on the .rail-tile inside it.
  • Never use a ring box-shadow for focus, and never outline: none without a replacement.

Contrast (Noir): --text on --panel 15.35:1, --text-dim 9.50:1, --text-mute 7.11:1 (4.64:1 on --raised-2, the lowest), --accent 7.13:1, --accent-hot 9.97:1, --on-accent on --accent 7.80:1, --error 5.76:1, --line-strong 4.42:1 (3.39:1 on --raised) and --control-edge 4.72:1. --text-faint is the one token under 4.5:1, so it never carries text. src/ui/contrast.ts holds the pairs and tests/ui/themeContrast.test.ts runs them over every shipped theme:

Pair Standard High Contrast pair
--text, --text-dim, --text-mute on --panel, --panel-2, --raised, --raised-2, the panel glass and a solid panel over a white model; --on-accent on --accent 4.5:1 7:1
--line-strong on --panel and --raised 3:1 4.5:1
--control-edge on the field well, the empty checkbox, the slider rail and the switch track, and against the panel round them 3:1 4.5:1
--ok, --warn, --error as text on --panel and --panel-2 4.5:1 4.5:1
Two signals a protan, deutan or tritan view merges (dE2000 under 15) 10 L* apart 10 L* apart
The focus ring (--accent) on every surface and the glass 3:1 4.5:1
--axis-x, --axis-y, --axis-z and --pick-line on --viewport-bg 3:1 3:1
The seven --sketch-* curve colours, --sketch-aid, --sketch-snap, --sketch-preview and --error on --viewport-bg 3:1 4.5:1

An uploaded palette is checked against the same pairs at the standard bar: it still loads, and the Appearance pane lists the pairs it fails in a status line under the picker.

The Contrast setting (Settings, Accessibility: Follow system, Standard, More, Maximum) writes html[data-contrast], and _contrast.scss swaps tokens over any theme: More draws --text-mute and --control-edge as --text-dim, Maximum draws --text-dim, --text-mute, --line-strong and --control-edge as --text, and both set --focus-ring-width to 3px and turn Solid panels on. Follow system gives More when the OS asks for contrast. Solid panels (html.solid-panels, also in the Screen reader preset) turns the glass off and fills panels, tiles and chips with --float-bg-solid, so text keeps 4.5:1 over a white model.

The System theme, the first run default, follows the OS: dark gives FundaCAD Noir, light gives FundaCAD Light, and an OS that asks for contrast gives High Contrast Dark or Light. A theme the user picked always wins over it.

Semantics: an icon only button has an aria-label (and the same title). Toggles use aria-pressed, switches role="switch" with aria-checked, option groups role="radiogroup" with role="radio", tabs aria-selected. A dialog has role="dialog" and a name: aria-labelledby pointing at its visible title (Dialog.vue, ModalFrame.vue over it and the chooser in ModalHost.vue, through useId()), or an aria-label when it has no title (CommandPalette.vue, HomeScreen.vue, TargetEditPanel.vue). A modal one also has aria-modal="true". An Icon is aria-hidden unless it has a label (6.4). Every base control has a name (The base set), and a state, an error or a name never lives in a title alone (7.11).

Keyboard: every control is reachable and shows the focus outline. Single letter shortcuts are ignored while typing (isEditableTarget, ui/focus.ts). Every confirm offers Cancel.

Escape depends on what the surface is:

Surface Escape
A menu, popover, the command palette (MenuBar.vue, ui/menu.ts, ContextMenuHost.vue, Popover.vue, CommandPalette.vue) Closes the topmost one only. It calls claimEscape() (ui/escapeClaim.ts) while open, and tools check escapeClaimed() so the same key does not also cancel them
A dialog (Dialog.vue, ModalFrame.vue, the chooser) Closes the topmost one through the modal gate (composables/useModalGate.ts); Dialog does it itself, a ModalFrame dialog through its own handler
A non modal tool panel with nothing of its own to cancel (Properties, Interference, Parameters) close-on-esc on Panel (or FloatingPanel). It does not claim Escape, so the key also reaches the global handler; the hint says "Esc to close"
A panel that belongs to a running tool or mode (Measure, Overhang) No close-on-esc. Whatever owns the panel closes it: MeasureTool owns Escape for its whole run and drops the panel with its highlight ("Esc to exit"), Overhang goes with the Draft toggle ("toggle Draft to close")
A dock tab with a job running (the traced picture on the Camera tab, RenderCamera.vue) Cancels the job. It calls claimEscape() only while the job runs and focus is in the tab, and stops the key there so the keymap keeps the selection. With no job running the key goes on to whatever owned it before
A tool panel with layers of its own to back out of (Stress) No close-on-esc, its own bubble phase keydown in StressPanel.vue. One layer per press: a drag, placing a spot or Read a point first (viewport/stressGlyphs.ts takes them in capture and stops the key), then a focused field gives up focus, and only then the panel closes, keeping the setup and the last result as the Close button does

Never call claimEscape() from a tool panel: the tool would stop hearing its own Escape.

Disabled is the one model of 7: aria-disabled rather than the native attribute, so the reason stays readable in the title, opacity 0.45, cursor: default and no hover; the control swallows its own click and Enter. The old menu and context rows take pointer-events: none instead.

prefers-contrast and forced-colors only steer the System theme to High Contrast and Follow system contrast to More (ui/osTheme.ts), together with the Rust os_a11y_prefs command, which asks Windows, the desktop portal or gsettings on Linux and macOS Increase contrast, as WebKitGTK reports no prefers-contrast at all. It is asked at startup and again each time the window regains focus or changes theme, and gives up on a tool that has not answered within two seconds, which keeps the last answer rather than turning contrast off. Under forced-colors (a Windows contrast theme) _forced.scss redraws what the browser erases: control edges as an inset 1px ButtonText outline, selected and pressed states in Highlight and HighlightText (with forced-color-adjust: none, as Chromium otherwise draws a Canvas backplate behind their text), the focus ring in Highlight and the slider rail in system colours. Not handled yet: prefers-reduced-transparency, a role on the toast stack.

12. Do and don't

Do Don't
Reuse a glass class, or add your selector to the lists in _glass.scss Ship a flat opaque panel (var(--panel), var(--panel-2) or var(--raised) as a surface fill) over or instead of the workspace
Fill glass with --float-bg or --float-bg-solid, a tile with --float-tile-bg, a chip with --float-chip-bg, a field with --field-bg Write a translucent rgba() fill or your own backdrop-filter: blur(...)
Use colour tokens and color-mix on them; give controls their fill by wearing a class on the _glass.scss lists Write a hex, rgb(), hsl() or named colour, or a var(--token, #hex) fallback
Use var(--float-shadow) Add a one off shadow, a glow or a halo, or a hard --shadow-2/--shadow-3 on something over the model
Tell a surface apart by its fill and shadow; write border: 1px solid transparent where the box needs a border Draw an outline, a border colour or a 1px ring around a rounded surface
Show hover with --hover-wash, on with --accent-wash or an accent 16% fill Change a border colour or add a ring for a state
Divide the parts of a dialog, menu or dock with --line Draw the edge of a surface in --line or --line-strong
Use --float-radius, --float-tile-radius, --float-chip-radius with corner-shape: squircle Use --r-* or a px radius on a floating surface
Keep 12px (--float-gap) around floating surfaces Dock a new panel edge to edge (the Render dock is the one docked column) or cover the model with a sheet
Keep the accent for active, selected, focused and primary, and for .measure-title Fill a large area with the accent, or colour a card or dialog title
Draw every control with a base component from src/components/ui/ Write a raw <button>, <input>, <select> or <textarea>, or raise an entry of scripts/ui-controls-allow.json
Toggle a setting with Checkbox Put a Switch on a settings page; switches are for live toggles in tool panels
Grow small targets to about 40px with a pseudo element under touch Ship a 24px target, or change layout for touch
Give every control a visible focus outline Remove the outline and leave nothing, or draw focus as a ring shadow
Check FundaCAD Noir and Solarized Light Test only the dark theme
Check with blur off Rely on blur to make text legible
Use --t-fast, --t-med and --ease Write 0.14s ease-out
Write title plus aria-label, shortcuts as Ctrl+Shift+Z through fmtKeys() Build a custom tooltip, or write "Ctrl Alt H"
Name every base control with label or labelledby, and put a state in the name, aria-describedby or a .sr-only span Leave a state, an error or the only name in a title, or label an Icon inside a named control
Build a readout from Panel and the .measure-* classes Invent .my-panel-head and .my-row with their own padding
Leave Escape to the tool that owns the panel Call claimEscape() from a tool panel
Use --error Use --danger or a hard coded red

13. Checklist before UI work is done

Run all of it. Paste the screenshots into the review.

  1. Reuse first. Is the surface an existing class from 4.2 or 7, and is every control a base component? If the surface is new, is its selector on the _glass.scss lists (fill, radius)?

  2. Tokens only. No raw colour, no fallback, no invented token, no new shadow, radius or duration literal. Fills come from the _glass.scss lists. npx vitest run tests/ui/designSpec.test.ts passes, and so does node scripts/check-ui-controls.mjs (after --lower when you removed raw controls).

  3. Glass is live. In the browser, the bodies smear through the panel, the surface has no outline and is told apart by its fill and one soft shadow, the corners are squircle, and there is a 12px gap to the stage edges and neighbours. Hover, selected and on states are fills, not borders or rings.

  4. Both themes. FundaCAD Noir and Solarized Light, nothing stays dark on light or light on dark, the cards stand clear of the grid and every text reads at 4.5:1 on its fill in the light theme.

  5. Blur off. Turn on potato mode (Preferences, Viewport), or run document.documentElement.classList.add("no-glass-blur"). The screen is opaque and still looks finished.

  6. Narrow and wide. A wide window, a stage under 820px, and a window under 760px and 560px. Nothing overflows, nothing scrolls sideways.

  7. Touch. With <html data-pointer="touch">, every small target reaches about 40px and nothing moves.

  8. Keyboard. Tab through it: every control shows the accent outline, Escape does what 11 says for this kind of surface, Enter does the primary thing. A dialog has role="dialog" and a name. Every control has a name, and no state lives only in a title (7.11).

  9. Motion. Entrances use pop-in or glass-in; with Animations off (Preferences, Accessibility) everything jumps to its end state.

  10. Wording. Every string passes 9, and sh scripts/check-repo-hygiene.sh passes.

  11. Side by side. Screenshot the new UI next to an existing panel (the workspace shot in this page, or the real app) in both themes. If it would not pass for the same product, it is not done.

14. Known debt, do not copy

  • _home.scss on dev: opaque, no glass, hex fallbacks, a one off shadow. When the glass Home lands, its counts in COLOUR_BASELINE and FLAT_BASELINE drop, the guard fails until they are lowered, and this line, the anti reference caption in 1 and the Home bullet of 4.4 change in the same commit.
  • Flat leftovers: .timeline-props.floating, the bare .palette (only .float-right .palette is glass), .dropchip, .profile-panel.
  • Flat base rules under glassed surfaces (_modals.scss, _utilities.scss, _console.scss, _targetedit.scss), including hand written blurs and a stale comment about a "flat, zero-blur elevation". _glass.scss overrides them; read the final result, not the base.
  • Off palette literals: #e24a3b and #ff7a66 danger, #d2a83b warning (.toast-warning), #ff6b6b, #e0a020, #7fe08a, rgba(74, 208, 125, …) (button.finish).
  • Undefined tokens listed in 2, and --grid-minor and --grid-major, read by viewport/scene.ts but never defined.
  • --z-menu, --z-toast and --shadow-pill are defined and unused.
  • Raw colours inside the measure panels: OverhangPanel.vue writes color: #e24a3b, and PropertiesPanel.vue and InterferencePanel.vue write var(--accent-hot, #ff9a5c) inline.
  • Raw controls and the classes the base set replaces (.sm-input, .pref-seg, .ft-switch, .param-switch, .check, .opt-row rows, hand written .btn markup) still draw most of the app; scripts/ui-controls-allow.json counts every raw one and only shrinks. The bare button rule (_layout.scss) has no disabled state and paints every raw button until the last one goes.
  • No focus state on .rd-search.
  • 12 components carry an SFC <style> block although main.scss says there are none; new styles go in src/styles/.

15. The guard test

tests/ui/designSpec.test.ts reads every src/components/**/*.vue, src/styles/*.scss and src/styles/ui/*.scss through Vite and checks (the partials of src/styles/ui/ nest their selectors, so rules 1, 4 and 11 read them and the others do not):

  1. Colour literals are a ratchet. Each file holds exactly the raw colour literals (hex, colour functions, named colours) listed for it in COLOUR_BASELINE. A new file starts at zero. When you remove literals, lower the number in the same commit; the test fails until you do, so the room never stays open for new ones.
  2. No new flat slab or hard shadow. Outside a hover, press, focus or selected rule, a background of var(--panel), var(--panel-2), var(--raised) or var(--raised-2), and a box-shadow with --shadow-1/2/3, are counted per file against FLAT_BASELINE, exactly, a new file at zero. That is the signature of the flat Home. A floating surface goes on the _glass.scss lists instead; an inset well or flat control in a new file is the rare case where the number goes up, and the review should ask why.
  3. Blur goes through the glass. Outside _glass.scss, a backdrop-filter is var(--float-blur) or none, unless the file is on BLUR_ALLOWED with a reason.
  4. Tokens exist. Every var(--name) is defined in _tokens.scss or set locally (a declaration, an inline :style, a setProperty). The old undefined names are listed in UNDEFINED_ALLOWED; that list only shrinks.
  5. No outline around a rounded surface. A rule that rounds a surface, by its own declarations, by a class the templates give the same element or by a parent selector, may not paint an edge: a visible border, border-color, border-style, border-image, outline, outline-color, a ring box-shadow (zero offset, a blur of 1px at most, a spread, however it is spelled) or a masked ::after ring. Only a real :focus or :focus-visible state is exempt, not :focus-within. Signal borders (--error, --warn) and the entries of OUTLINE_ALLOWED (sketch labels, drawn glyphs, swatches, the guide ring) are exempt too (Depth without lines).
  6. Retired tokens stay invisible. --float-line, --glass-sheen, --glass-inset, --glass-rim and --accent-glow are defined as transparent in _tokens.scss, and no component or partial reads them.
  7. The accent is calm. --float-blur saturates only lightly (saturate(1.0x)) and --accent is #9a9ff0, a periwinkle.
  8. The light theme reads. On Solarized Light every text token reaches 4.5:1 on the card, solid card, tile, chip and field, --on-accent on --accent clears 4.5:1, and a card clears its viewport at above 1.15:1.
  9. Settings use the checkbox. Nothing Preferences renders contains a Switch, SwitchRow, .ui-switch, .param-switch, .ft-switch, ToggleRow or Toggle.
  10. An error shows on a typed field. Of the rules that name a dimension field in a .dim-bad box, the winning background keeps --error-tint, so a refused typed value does not look normal.
  11. Base partials read tokens only. No partial in src/styles/ui/ holds a colour literal, a var() fallback, a literal duration or easing, or a radius that is not a token (a calc() on one is fine), and none may appear in COLOUR_BASELINE: the base set starts and stays at zero.

It cannot see a screen. Whether a surface is glass, both themes and blur off are still yours to check with the checklist.