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 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.
- 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. - 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. - 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.
- 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-titleis--accent-hot, so the readout reads as the tool's output (7.13). Card and dialog titles stay--text. - Dense rows, generous shell. Rows and labels are small (
--fs-smalland--fs-body, 34px rows, 40px tiles). The air lives at the shell level: gaps, card padding, big corner radii. - Tokens only. Every colour, radius, gap, duration and shadow is a custom property. Themes swap the colour tokens, and one shipped theme is light.
- 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.
- 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 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.
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)andvar(--accent-hot, #ff9a5c), from an old orange palette),_home.scss,_browser.scss,_layout.scss,_targetedit.scssand several overlay components (LiveSessionPill.vue,PropertiesPanel.vue,InterferencePanel.vueand 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 withcolor-mixon a token:color-mix(in srgb, var(--accent) 16%, transparent). The few literals that remain in_glass.scssare 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-paneland--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 inPALETTE_TOKENSinsrc/ui/theme.ts.
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 |
These are never themed. They are covered in their own sections: glass, type, spacing and radii, motion.
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.
| 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-shadowis 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-3is 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-3and--shadow-pillare 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-shadowwith its own offsets and colours. There is no halo, glow or ring shadow in the language. Focus is an outline (11).
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-radiusorcorner-shape) never sets a visibleborder,border-color,outlineor a 1pxbox-shadowring. Where the box needs a border for its geometry, writeborder: 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-bgand--field-bg, never a hand mixed white or black. - State by fill. A hover lays
--hover-washover the control's own fill. A tile that is on lays--accent-washover its fill. A row that is selected takescolor-mix(in srgb, var(--accent) 16%, transparent)and--accent-hottext. 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-dimor--text-muteinstead 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.
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.
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.
| 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 |
- Lay it out in its own partial in
src/styles/(or the partial it belongs to), loaded beforeglassinmain.scss. Give it no background, border, shadow or radius there. - 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. - Build its controls and rows from the base components (7), which bring their squircle, fills and states; a surface adds none of its own.
- 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.
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-leftand.float-rightfree of anything but layout and pointer events. - A full screen surface (such as Home) paints its backdrop on a
::beforelayer (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: ondev, Home paints.home { background: var(--panel) }itself (14). - Animate opacity on the glass element itself (
pop-in,glass-indo), never on its parent. .float-cardusesoverflow: hiddento clip to the squircle, so anything that should spill out of a card belongs on an unclipped element.
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:
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.
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.
| 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.
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).
| 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).
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 |
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.
| 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.
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 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).
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):
disabledrendersaria-disabled="true"and.is-disabled, never the native attribute. Thetitlestays 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
@clicknever runs. A field refuses typing, a slider refuses a drag, and the arrow keys skip a disabled segment, tab or row. disabledReasontakes over the tooltip while disabled. Say why and what lifts it ("Run the study first").clickable(onIconButton) is the soft block: greyed andaria-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.
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.
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.
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.
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 |
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) |
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.
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.
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.checkmarkup of_checkbox.scssit replaces. Never putSwitch,SwitchRow,.ft-switch,.param-switch,ToggleRoworTogglein anything Preferences renders, the guard test fails on it. - Live toggles use
SwitchRow:layout="float"in the view controls (the oldToggle.vue, which now draws it, and its.float-togglerow), feature properties useToggleRow, aFieldRow layout="param"row holding aSwitch(the old.param-switchis 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).
| 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).
| 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.
| 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
ListRowbutton with a spokenaria-label(the shape with its freedom, the rule with what it holds). A row that can be removed sits in anli.rel-rowwith a siblingIconButton(.rel-del,danger) namedDeleteand 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.
FieldRowinlineandparamrows and.stress-fieldget this from thewrap-rowandwrap-labelmixins insrc/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-rowselect 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
FieldRowwith aNumberField(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".
| 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.
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.
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.
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: [] }>();openis required. The root is a<Teleport to="body">holding<div v-if="open" class="measure-panel ui-panel" :class="panelClass">, soclass,titleand other attributes on<Panel>are dropped. Size or move a panel only throughpanelClassand a rule for that class in_modals.scss(.properties-panelmin width 260px,.stress-panel340px wide and scrolling).titledraws the panel's name as its.measure-title, anh2, and names the panel (role="region",aria-labelledby), so heading keys and the rotor reach it.titleHiddenkeeps thath2for screen readers only. A panel given no title (a plain JS plugin) is still a region, named by a hiddenh2that reads Panel;head-actionssit beside it andclosableadds the 28px Close button after them.hintis the last line, a.measure-hint; thefootslot sits under the content. Without them the content is yours, from the classes below.closeOnEscadds a capture phasekeydownlistener onwindowthat emitscloseand 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-layerand under it, so the rail, the view controls and every dialog draw over an open panel.panelStack.tssetstopandrightunder the view cube and clear of the right cards, and amax-widththat keeps a wide panel clear of the rail, again whenever a panel, a card or#float-layerresizes. When the span beside the rail is under a panel'smin-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 itsmin-widthbeside 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 amin-widthruns out of the glass and under the rail: size wide content withmax-width: 100%, never against the window (vw), and let it reflow.panelClassmeasure-panel-columnhands the panel's height cap down, so a scroller inside it withmin-heightset shrinks and the rows around it stay in view. The in-view chips (.dim-input,.sketch-dims,.snap-tag,.promptand the like) draw over a panel they meet, so a form with its actions at the panel's foot keeps--prompt-clearfree below them. The shell ismin-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>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
IconButtontoggle first,activeon 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.activewears 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.
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) andwarningshow 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'stimeoutonly 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.
errordoes not show a toast. It goes to the title bar notice (showErrorNotice) and the console log, withdetailkept for the report.- Every toast is spoken once by
announce()fromtoast(): 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-hiddenwith 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 itsh2"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 isrole="log"witharia-live="off", since toasts already speak, and each row starts with a.sr-onlyError:, 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 tocheckand thetitleto "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 failuretoast("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.
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
--accentthrough one rule,pickColorinsrc/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/ztokens, read throughaxisColor(src/viewport/originTriad.ts), whoseAXIS_COLORholds 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
themeColorand are read again on a theme change. - Sketch curves take the seven
--sketch-*tokens through the functions insrc/sketch/overlay.ts(sketchFreeColorand the like), a conflict takes--error. The open sketch redraws on a theme change, andinstallViewportWiringredraws the sketches that are not open. Colour-Blind Safe holds six pairs apart (overlaySeparationinsrc/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 arearia-hidden(notinert, a pointer still edits them), the palette lists carry what they say. - Sizes are screen pixels, held through
gizmoScale.tsat 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 ascorner-shape: squircle, a rail tile's 17px on 40px scaled up (TILE_CORNER_RADIUS_PXandSQUIRCLE_EXPONENTinsrc/viewport/originTiles.tsandcornerProfile.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 (
placeLabelsandpickPlaneOnScreeninsrc/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,
--ui700 at 15px times the Viewport label size, inked in--textor--viewport-bg, whichever reads on the ground. It fades out when what it names is seen edge on.
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/.
| 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).
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.
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.
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-solidmixes--raisedinto--bg, and--float-bgis that at 97%. A tile is a step darker than the card, a chip another step, and a field a grey well (--field-bgmixes--text11% into the card).--hover-washand--check-offare mixes of--text. - Soft shadows.
--float-shadow,--shadow-2,--shadow-3and--shadow-pillare inked in--textand 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-bgmust 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-accenton--accentis held above 4.5:1 too. A light theme's--accent-hotis darker than its--accent, not lighter, because it is text on an accent tint. - Signals stay apart.
--ok,--warnand--errorread at 4.5:1 as text on--paneland--panel-2, and--pick-lineat 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 (deltaE2000insrc/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 orcolor-mixof 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.tsrejects a hard coded dark readout fill. - Check every screen in FundaCAD Noir and Solarized Light (Preferences, Appearance, Theme).
Focus:
- The shared outline (
_base.scss)::focus-visible { outline: var(--focus-ring-width) solid var(--accent); outline-offset: 1px; }.--focus-ring-widthis 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 inputand Items filter) draw the same ring at a 1px offset while focused, and an error keeps it.Checkboxdraws it at a 2px offset around its box.Sliderdraws it round its whole row through:has, since WebKit paints no outline on the thumb, and round the thumb only where:hasis 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-btnbutton, not on the.rail-tileinside it. - Never use a ring
box-shadowfor focus, and neveroutline: nonewithout 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.
| 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 |
Run all of it. Paste the screenshots into the review.
-
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.scsslists (fill, radius)? -
Tokens only. No raw colour, no fallback, no invented token, no new shadow, radius or duration literal. Fills come from the
_glass.scsslists.npx vitest run tests/ui/designSpec.test.tspasses, and so doesnode scripts/check-ui-controls.mjs(after--lowerwhen you removed raw controls). -
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.
-
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.
-
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. -
Narrow and wide. A wide window, a stage under 820px, and a window under 760px and 560px. Nothing overflows, nothing scrolls sideways.
-
Touch. With
<html data-pointer="touch">, every small target reaches about 40px and nothing moves. -
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 atitle(7.11). -
Motion. Entrances use
pop-inorglass-in; with Animations off (Preferences, Accessibility) everything jumps to its end state. -
Wording. Every string passes 9, and
sh scripts/check-repo-hygiene.shpasses. -
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.
_home.scssondev: opaque, no glass, hex fallbacks, a one off shadow. When the glass Home lands, its counts inCOLOUR_BASELINEandFLAT_BASELINEdrop, 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 .paletteis 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.scssoverrides them; read the final result, not the base. - Off palette literals:
#e24a3band#ff7a66danger,#d2a83bwarning (.toast-warning),#ff6b6b,#e0a020,#7fe08a,rgba(74, 208, 125, …)(button.finish). - Undefined tokens listed in 2, and
--grid-minorand--grid-major, read byviewport/scene.tsbut never defined. --z-menu,--z-toastand--shadow-pillare defined and unused.- Raw colours inside the measure panels:
OverhangPanel.vuewritescolor: #e24a3b, andPropertiesPanel.vueandInterferencePanel.vuewritevar(--accent-hot, #ff9a5c)inline. - Raw controls and the classes the base set replaces (
.sm-input,.pref-seg,.ft-switch,.param-switch,.check,.opt-rowrows, hand written.btnmarkup) still draw most of the app;scripts/ui-controls-allow.jsoncounts every raw one and only shrinks. The barebuttonrule (_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 althoughmain.scsssays there are none; new styles go insrc/styles/.
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):
- 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. - No new flat slab or hard shadow. Outside a hover, press, focus or
selected rule, a
backgroundofvar(--panel),var(--panel-2),var(--raised)orvar(--raised-2), and abox-shadowwith--shadow-1/2/3, are counted per file againstFLAT_BASELINE, exactly, a new file at zero. That is the signature of the flat Home. A floating surface goes on the_glass.scsslists 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. - Blur goes through the glass. Outside
_glass.scss, abackdrop-filterisvar(--float-blur)ornone, unless the file is onBLUR_ALLOWEDwith a reason. - Tokens exist. Every
var(--name)is defined in_tokens.scssor set locally (a declaration, an inline:style, asetProperty). The old undefined names are listed inUNDEFINED_ALLOWED; that list only shrinks. - 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 ringbox-shadow(zero offset, a blur of 1px at most, a spread, however it is spelled) or a masked::afterring. Only a real:focusor:focus-visiblestate is exempt, not:focus-within. Signal borders (--error,--warn) and the entries ofOUTLINE_ALLOWED(sketch labels, drawn glyphs, swatches, the guide ring) are exempt too (Depth without lines). - Retired tokens stay invisible.
--float-line,--glass-sheen,--glass-inset,--glass-rimand--accent-gloware defined as transparent in_tokens.scss, and no component or partial reads them. - The accent is calm.
--float-blursaturates only lightly (saturate(1.0x)) and--accentis#9a9ff0, a periwinkle. - The light theme reads. On Solarized Light every text token reaches
4.5:1 on the card, solid card, tile, chip and field,
--on-accenton--accentclears 4.5:1, and a card clears its viewport at above 1.15:1. - Settings use the checkbox. Nothing Preferences renders contains a
Switch,SwitchRow,.ui-switch,.param-switch,.ft-switch,ToggleRoworToggle. - An error shows on a typed field. Of the rules that name a dimension
field in a
.dim-badbox, the winning background keeps--error-tint, so a refused typed value does not look normal. - Base partials read tokens only. No partial in
src/styles/ui/holds a colour literal, avar()fallback, a literal duration or easing, or a radius that is not a token (acalc()on one is fine), and none may appear inCOLOUR_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.





