Adom UI Design System

@@ -19,7 +19,7 @@ The principles that matter most, in order. Usability and drivability first, poli 6. **Built and driven by the AI.** The AI writes the app, shows it to you, and drives it over a live SSE or WebSocket channel to test and perfect it. Anything the UI can do, a command can do, so state lives on the server and the channel keeps the UI, the CLI, and the AI in lockstep. 7. **One 44px header, three zones,** so people always know which app they are in and where the controls are. 8. **CLIs answer `OK:` or `ERROR:`,** with a `Hint:` that names the exact next command.-9. **Then the polish:** dark `#0d1117` and `#161b22`, one teal accent `#00b8b0`, monochrome-white icons, three fonts by role. **Never emoji, never em-dashes** (section 11). On-brand matters, but it comes last.+9. **Then the polish:** dark `#0d1117` and `#161b22`, one teal accent `#00b8b1`, monochrome-white icons, three fonts by role. **Never emoji, never em-dashes** (section 11). On-brand matters, but it comes last. 10. **Lint before you publish.** `adom-ui-linter` turns most of this into deterministic checks.  ---@@ -93,7 +93,7 @@ Toasts are the standard transient-feedback element, and in Adom they do double d  - **Build a `POST /ui/toast` hook from day one.** One mechanism serves both the user (feedback) and the AI (narration). The AI raises a toast with the same `mytool ui toast "..."` command it uses to drive everything else. - **Position:** bottom center, consistent across the app.-- **Types:** success (green `#3fb950`), error (red `#f85149`), info (teal `#00b8b0`), each with a clear icon and message.+- **Types:** success (green `#3fb950`), error (red `#f85149`), info (teal `#00b8b1`), each with a clear icon and message. - **Duration:** about 4 seconds for a confirmation, sticky for an error the user must read. Pause on hover. - **Stack** newest on top, cap the visible count, allow dismiss, and **carry an action when one exists**, above all **Undo** for anything destructive. @@ -114,7 +114,7 @@ Toasts are the standard transient-feedback element, and in Adom they do double d  - A toggle must **look** like its state. Flat styling for both on and off is a lie. Carry `aria-pressed="true|false"` and an `.is-on` class, and make the on state differ in at least **two** ways (background, border, inset shadow, accent text). A five percent tint shift is too subtle to read. - **Sync a toggle both ways.** Every other path that flips the underlying state (the HUD's own close X, a keyboard shortcut, a programmatic `setX(false)`) must update the button too. A button that drifts out of sync is worse than no button, because now it lies confidently.-- Primary actions use teal `#00b8b0`. Green means success, red means destructive, reserved for those meanings.+- Primary actions use teal `#00b8b1`. Green means success, red means destructive, reserved for those meanings. - **Any irreversible-feeling action gets a live preview** before it commits: a snap point, a deletion glow, a highlighted target. - **The preview must not be pickable.** Set `isPickable = false` (or the equivalent) on the preview mesh or element. Otherwise it becomes the hit target for the very next hover and the tool stalls, picking its own ghost. Dispose the preview the instant intent changes: filter switched, tool closed, selection limit reached. Stale ghost markers are their own bug report. @@ -210,30 +210,91 @@ The finishing tokens. They make an app on-brand once the interaction is already  ### Core theme tokens -| Token | Value | Use |-|---|---|---|-| `--bg` | `#0d1117` | Page, deepest background |-| `--surface` | `#161b22` | Panels, toolbars, cards |-| `--elevated` | `#1c2128` | Elevated cards, hover surfaces |-| `--overlay` | `#21262d` | Tooltips, dropdowns, modals |-| `--border` | `#30363d` | Standard border |-| `--text` | `#e6edf3` | Primary text |-| `--text-2` | `#8b949e` | Secondary text, labels |-| `--text-3` | `#484f58` | Disabled, placeholders |-| `--accent` | `#00b8b0` | Primary accent, the Adom teal |-| `--accent-bright` | `#00e6dc` | Hover and focus highlights |+Ratios are measured against `--bg` `#0d1117`. Read the **Use** column as a hard+constraint, not a suggestion: it is the only thing standing between a token and a+surface it fails on.++| Token | Value | On `--bg` | Use |+|---|---|---|---|+| `--bg` | `#0d1117` | ground | Page, deepest background |+| `--surface` | `#161b22` | ground | Panels, toolbars, cards |+| `--elevated` | `#1c2128` | ground | Elevated cards, hover surfaces |+| `--overlay` | `#21262d` | ground | Tooltips, dropdowns, modals |+| `--border` | `#30363d` | — | Standard border |+| `--text` | `#e6edf3` | 16.0:1 | **Emphasis only**: headings, active items. Too hot for paragraphs, see the ceiling below |+| `--text-body` | `#c9d1d9` | 12.3:1 | **The default for running text.** The comfortable one |+| `--text-2` | `#8b949e` | 6.2:1 | Secondary text, labels, placeholders |+| `--text-3` | `#484f58` | **2.3:1** | **NEVER text.** Borders and disabled chrome only |+| `--accent` | `#00b8b1` | 7.7:1 | Primary accent, the Adom teal |+| `--accent-hover` | `#00d4cb` | 10.2:1 | Hover state |+| `--accent-bright` | `#00e6dc` | 12.0:1 | Focus highlights |+| `--on-accent` | `#05221f` | 6.8:1 on teal | Text and icons sitting **on** a teal fill |++The teal is **`#00b8b1`**. Not `#00b8b0`. This page carried the wrong value for long+enough that it reached 148 places in the VS Code themes and 134 in Hydrogen Desktop+before anyone caught it, because a one-digit colour error is invisible to review and to+every build. Copy it, do not retype it.  ### Status and grouping -| Token | Value | Use |-|---|---|---|-| `--purple` | `#8c6bf7` | Group labels, secondary accent |-| `--blue` | `#58a6ff` | Links, informational accents |-| `--green` | `#3fb950` | Success only |-| `--red` | `#f85149` | Destructive only |-| `--yellow` | `#d29922` | Warning only |+| Token | Value | On `--bg` | Use |+|---|---|---|---|+| `--purple` | `#8c6bf7` | 5.0:1 | Group labels, secondary accent |+| `--blue` | `#64abff` | 7.9:1 | Links and informational **text** |+| `--blue-fill` | `#0061ef` | **3.6:1** | The brand blue. **Fills only, never text** |+| `--green` | `#3fb950` | 7.4:1 | Success only |+| `--red` | `#f85149` | 5.6:1 | Destructive only |+| `--yellow` | `#d29922` | 7.5:1 | Warning only |++### Contrast: the floor *and* the ceiling++Everyone documents the floor. The ceiling is why dark mode so often looks harsh, and+almost nobody writes it down:++- **Floor.** WCAG AA is **4.5:1** for normal text, **3:1** for large text (18.66px+ bold,+  or 24px+) and for UI boundaries a user must perceive. AAA is **7:1**. Adom targets AAA+  for anything a person reads for more than a moment.+- **Ceiling.** Past roughly **14:1**, light text on a dark ground haloes: the glyph edges+  bloom and the text feels like it is vibrating. This is why Material caps high-emphasis+  text at 87% white rather than 100%. Pure white on `--bg` is **18.9:1** and visibly+  glares, which is exactly why `--text` at 16.0:1 is reserved for short emphasis and+  `--text-body` at 12.3:1 carries paragraphs.+- **So the comfortable band for dark-mode body text is about 7:1 to 13:1.** Below it you+  fail AAA; above it you fatigue the reader. Both are real defects.+- The reason to prefer dark mode is that the panel emits less light overall, so cranking+  the text back toward white gives away the benefit you chose dark mode for.++**Two token roles are load-bearing and get violated constantly:**++- `--text-3` is **2.3:1**. It fails AA by a wide margin and is not text. Calling it+  "placeholder" invites exactly the wrong use, because a placeholder is text a person+  reads. Placeholders take `--text-2`.+- `--blue-fill` is **3.6:1**. It is the brand blue and it is beautiful as a fill, a bar,+  or a selected state. As text it fails AA. Informational text takes `--blue`.++**Measure, do not eyeball.** A colour that looks fine on your screen at your brightness+can be a hard fail. The check is four lines:++```python+def lum(h):+    h = h.lstrip('#'); c = [int(h[i:i+2], 16) / 255 for i in (0, 2, 4)]+    c = [x / 12.92 if x <= .03928 else ((x + .055) / 1.055) ** 2.4 for x in c]+    return .2126 * c[0] + .7152 * c[1] + .0722 * c[2]+def contrast(fg, bg):+    a, b = sorted([lum(fg), lum(bg)], reverse=True); return (a + .05) / (b + .05)+```++Common greys that **fail** and keep reappearing in Adom code: `#666` (3.3:1), `#777`+(4.3:1), `#888` (5.4:1 — passes AA, fails AAA). Reach for `--text-2` instead of inventing+a grey.++### Rules  - Never use **pure black** (`#000`) or **pure white** (`#fff`) for a large surface.+- **Never hardcode a hex where a token exists.** The property you are setting already+  declares the role: `color:` wants a text token, `background:` a ground token, `border:`+  `--border`. A hardcoded colour cannot follow a theme, so it is the thing that breaks+  when a second scheme ships. - Hover transitions are smooth, not snappy: `0.15s ease`. - Signature gradient, teal to blue to purple: `linear-gradient(100deg, #00e6dc, #39b8ff 60%, #8c6bf7)`. Headline accents and flagship art, not body UI. @@ -254,7 +315,7 @@ The finishing tokens. They make an app on-brand once the interaction is already - **Icons are monochrome white. No exceptions.** `#e6edf3` or `currentColor`, in-app icons, the tab-strip icon, and the favicon. Prefer a clean custom SVG (`viewBox="0 0 24 24"`, stroke 1.5 to 2px). No emoji as icons. The only place brand color is allowed is marketing art: the hero and the page thumbnail.   - Pre-publish icon audit, both must return zero hits:     ```bash-    grep -nE 'fill="(#00b8b0|#00d4cb)"|stroke="(#00b8b0|#00d4cb)"' docs/icon.svg src/**/*.html src/**/*.svg+    grep -nE 'fill="(#00b8b1|#00d4cb)"|stroke="(#00b8b1|#00d4cb)"' docs/icon.svg src/**/*.html src/**/*.svg     grep -nE '\.logo[^{]*\{[^}]*color:\s*var\(--accent\)|\.icon[^{]*\{[^}]*color:\s*var\(--accent\)' src/**/*.html src/**/*.css     ``` @@ -307,6 +368,26 @@ adom-ui-linter lint . --category ui-patterns,ai-drivability,header  Fix every FAIL (the hint tells you exactly what to do), address relevant WARNs, re-run to zero before publishing. +### What the linter cannot catch, so you must++The gate is deterministic, which is its strength and its blind spot. Three failure modes+slip straight through it, and all three have shipped:++- **A wrong hex that is still a valid hex.** This page itself carried `#00b8b0` instead of+  the real teal `#00b8b1` for months. Every build was green, every review passed, and the+  error propagated to 148 places in the VS Code themes and 134 in Hydrogen Desktop. A+  one-digit colour error is invisible to a compiler and nearly invisible to an eye. Copy+  brand values from the token table, never retype them, and never trust a colour you+  remember.+- **A colour used in a role it fails.** `--text-3` and `--blue-fill` are legitimate tokens+  that fail as text. Nothing flags `color: var(--text-3)`. Check the role column.+- **"It compiled" as evidence.** A CSS custom property that resolves to nothing still+  builds. A sweep that rewrote `--accent: #00b8b1` into `--accent: var(--accent)` produced+  a clean build, a matching commit SHA, and an app with no background. **The only proof a+  colour change worked is the computed value in the running app or a sampled pixel**, not+  a successful build.++ ---  ## 13. The skill map

@@ -28,8 +28,6 @@ description: >-  How the AI builds and tests interfaces that people genuinely love to use. In Adom you do not hand-write an app and then click through it to check it. You ask the AI to build it, and the AI builds it, shows it to you, drives it over a live channel, watches the result, and fixes it, looping until the experience is right. This page is the standard that makes that loop land on something pleasurable: a UI that treats the person using it as the center of everything, and an app that is built from the first commit to be driven and observed. Color and typography are the final polish, maybe three percent of the work. The rest is interaction quality and drivability. -![Build interfaces people love to use](screenshots/hero.png)- > **Why this page exists.** Two things are true in Adom that are not true elsewhere. First, good UI is not decoration, it is respect for the person on the other side of the screen. Second, the AI is the one building and driving the UI, so the app has to be controllable and observable end to end, or the AI cannot perfect it. This page teaches both: how to make an interface a pleasure to use, and how to build and test it the Adom way. If you only remember one thing: **build for the user first, make every action answer back, and make the whole app drivable so the AI can prove it.**  ---@@ -46,7 +44,7 @@ The principles that matter most, in order. Usability and drivability first, poli 6. **Built and driven by the AI.** The AI writes the app, shows it to you, and drives it over a live SSE or WebSocket channel to test and perfect it. Anything the UI can do, a command can do, so state lives on the server and the channel keeps the UI, the CLI, and the AI in lockstep. 7. **One 44px header, three zones,** so people always know which app they are in and where the controls are. 8. **CLIs answer `OK:` or `ERROR:`,** with a `Hint:` that names the exact next command.-9. **Then the polish:** dark `#0d1117` and `#161b22`, one teal accent `#00b8b0`, monochrome-white icons, three fonts by role. **Never emoji, never em-dashes** (section 11). On-brand matters, but it comes last.+9. **Then the polish:** dark `#0d1117` and `#161b22`, one teal accent `#00b8b1`, monochrome-white icons, three fonts by role. **Never emoji, never em-dashes** (section 11). On-brand matters, but it comes last. 10. **Lint before you publish.** `adom-ui-linter` turns most of this into deterministic checks.  ---@@ -120,7 +118,7 @@ Toasts are the standard transient-feedback element, and in Adom they do double d  - **Build a `POST /ui/toast` hook from day one.** One mechanism serves both the user (feedback) and the AI (narration). The AI raises a toast with the same `mytool ui toast "..."` command it uses to drive everything else. - **Position:** bottom center, consistent across the app.-- **Types:** success (green `#3fb950`), error (red `#f85149`), info (teal `#00b8b0`), each with a clear icon and message.+- **Types:** success (green `#3fb950`), error (red `#f85149`), info (teal `#00b8b1`), each with a clear icon and message. - **Duration:** about 4 seconds for a confirmation, sticky for an error the user must read. Pause on hover. - **Stack** newest on top, cap the visible count, allow dismiss, and **carry an action when one exists**, above all **Undo** for anything destructive. @@ -141,7 +139,7 @@ Toasts are the standard transient-feedback element, and in Adom they do double d  - A toggle must **look** like its state. Flat styling for both on and off is a lie. Carry `aria-pressed="true|false"` and an `.is-on` class, and make the on state differ in at least **two** ways (background, border, inset shadow, accent text). A five percent tint shift is too subtle to read. - **Sync a toggle both ways.** Every other path that flips the underlying state (the HUD's own close X, a keyboard shortcut, a programmatic `setX(false)`) must update the button too. A button that drifts out of sync is worse than no button, because now it lies confidently.-- Primary actions use teal `#00b8b0`. Green means success, red means destructive, reserved for those meanings.+- Primary actions use teal `#00b8b1`. Green means success, red means destructive, reserved for those meanings. - **Any irreversible-feeling action gets a live preview** before it commits: a snap point, a deletion glow, a highlighted target. - **The preview must not be pickable.** Set `isPickable = false` (or the equivalent) on the preview mesh or element. Otherwise it becomes the hit target for the very next hover and the tool stalls, picking its own ghost. Dispose the preview the instant intent changes: filter switched, tool closed, selection limit reached. Stale ghost markers are their own bug report. @@ -237,30 +235,91 @@ The finishing tokens. They make an app on-brand once the interaction is already  ### Core theme tokens -| Token | Value | Use |-|---|---|---|-| `--bg` | `#0d1117` | Page, deepest background |-| `--surface` | `#161b22` | Panels, toolbars, cards |-| `--elevated` | `#1c2128` | Elevated cards, hover surfaces |-| `--overlay` | `#21262d` | Tooltips, dropdowns, modals |-| `--border` | `#30363d` | Standard border |-| `--text` | `#e6edf3` | Primary text |-| `--text-2` | `#8b949e` | Secondary text, labels |-| `--text-3` | `#484f58` | Disabled, placeholders |-| `--accent` | `#00b8b0` | Primary accent, the Adom teal |-| `--accent-bright` | `#00e6dc` | Hover and focus highlights |+Ratios are measured against `--bg` `#0d1117`. Read the **Use** column as a hard+constraint, not a suggestion: it is the only thing standing between a token and a+surface it fails on.++| Token | Value | On `--bg` | Use |+|---|---|---|---|+| `--bg` | `#0d1117` | ground | Page, deepest background |+| `--surface` | `#161b22` | ground | Panels, toolbars, cards |+| `--elevated` | `#1c2128` | ground | Elevated cards, hover surfaces |+| `--overlay` | `#21262d` | ground | Tooltips, dropdowns, modals |+| `--border` | `#30363d` | — | Standard border |+| `--text` | `#e6edf3` | 16.0:1 | **Emphasis only**: headings, active items. Too hot for paragraphs, see the ceiling below |+| `--text-body` | `#c9d1d9` | 12.3:1 | **The default for running text.** The comfortable one |+| `--text-2` | `#8b949e` | 6.2:1 | Secondary text, labels, placeholders |+| `--text-3` | `#484f58` | **2.3:1** | **NEVER text.** Borders and disabled chrome only |+| `--accent` | `#00b8b1` | 7.7:1 | Primary accent, the Adom teal |+| `--accent-hover` | `#00d4cb` | 10.2:1 | Hover state |+| `--accent-bright` | `#00e6dc` | 12.0:1 | Focus highlights |+| `--on-accent` | `#05221f` | 6.8:1 on teal | Text and icons sitting **on** a teal fill |++The teal is **`#00b8b1`**. Not `#00b8b0`. This page carried the wrong value for long+enough that it reached 148 places in the VS Code themes and 134 in Hydrogen Desktop+before anyone caught it, because a one-digit colour error is invisible to review and to+every build. Copy it, do not retype it.  ### Status and grouping -| Token | Value | Use |-|---|---|---|-| `--purple` | `#8c6bf7` | Group labels, secondary accent |-| `--blue` | `#58a6ff` | Links, informational accents |-| `--green` | `#3fb950` | Success only |-| `--red` | `#f85149` | Destructive only |-| `--yellow` | `#d29922` | Warning only |+| Token | Value | On `--bg` | Use |+|---|---|---|---|+| `--purple` | `#8c6bf7` | 5.0:1 | Group labels, secondary accent |+| `--blue` | `#64abff` | 7.9:1 | Links and informational **text** |+| `--blue-fill` | `#0061ef` | **3.6:1** | The brand blue. **Fills only, never text** |+| `--green` | `#3fb950` | 7.4:1 | Success only |+| `--red` | `#f85149` | 5.6:1 | Destructive only |+| `--yellow` | `#d29922` | 7.5:1 | Warning only |++### Contrast: the floor *and* the ceiling++Everyone documents the floor. The ceiling is why dark mode so often looks harsh, and+almost nobody writes it down:++- **Floor.** WCAG AA is **4.5:1** for normal text, **3:1** for large text (18.66px+ bold,+  or 24px+) and for UI boundaries a user must perceive. AAA is **7:1**. Adom targets AAA+  for anything a person reads for more than a moment.+- **Ceiling.** Past roughly **14:1**, light text on a dark ground haloes: the glyph edges+  bloom and the text feels like it is vibrating. This is why Material caps high-emphasis+  text at 87% white rather than 100%. Pure white on `--bg` is **18.9:1** and visibly+  glares, which is exactly why `--text` at 16.0:1 is reserved for short emphasis and+  `--text-body` at 12.3:1 carries paragraphs.+- **So the comfortable band for dark-mode body text is about 7:1 to 13:1.** Below it you+  fail AAA; above it you fatigue the reader. Both are real defects.+- The reason to prefer dark mode is that the panel emits less light overall, so cranking+  the text back toward white gives away the benefit you chose dark mode for.++**Two token roles are load-bearing and get violated constantly:**++- `--text-3` is **2.3:1**. It fails AA by a wide margin and is not text. Calling it+  "placeholder" invites exactly the wrong use, because a placeholder is text a person+  reads. Placeholders take `--text-2`.+- `--blue-fill` is **3.6:1**. It is the brand blue and it is beautiful as a fill, a bar,+  or a selected state. As text it fails AA. Informational text takes `--blue`.++**Measure, do not eyeball.** A colour that looks fine on your screen at your brightness+can be a hard fail. The check is four lines:++```python+def lum(h):+    h = h.lstrip('#'); c = [int(h[i:i+2], 16) / 255 for i in (0, 2, 4)]+    c = [x / 12.92 if x <= .03928 else ((x + .055) / 1.055) ** 2.4 for x in c]+    return .2126 * c[0] + .7152 * c[1] + .0722 * c[2]+def contrast(fg, bg):+    a, b = sorted([lum(fg), lum(bg)], reverse=True); return (a + .05) / (b + .05)+```++Common greys that **fail** and keep reappearing in Adom code: `#666` (3.3:1), `#777`+(4.3:1), `#888` (5.4:1 — passes AA, fails AAA). Reach for `--text-2` instead of inventing+a grey.++### Rules  - Never use **pure black** (`#000`) or **pure white** (`#fff`) for a large surface.+- **Never hardcode a hex where a token exists.** The property you are setting already+  declares the role: `color:` wants a text token, `background:` a ground token, `border:`+  `--border`. A hardcoded colour cannot follow a theme, so it is the thing that breaks+  when a second scheme ships. - Hover transitions are smooth, not snappy: `0.15s ease`. - Signature gradient, teal to blue to purple: `linear-gradient(100deg, #00e6dc, #39b8ff 60%, #8c6bf7)`. Headline accents and flagship art, not body UI. @@ -281,7 +340,7 @@ The finishing tokens. They make an app on-brand once the interaction is already - **Icons are monochrome white. No exceptions.** `#e6edf3` or `currentColor`, in-app icons, the tab-strip icon, and the favicon. Prefer a clean custom SVG (`viewBox="0 0 24 24"`, stroke 1.5 to 2px). No emoji as icons. The only place brand color is allowed is marketing art: the hero and the page thumbnail.   - Pre-publish icon audit, both must return zero hits:     ```bash-    grep -nE 'fill="(#00b8b0|#00d4cb)"|stroke="(#00b8b0|#00d4cb)"' docs/icon.svg src/**/*.html src/**/*.svg+    grep -nE 'fill="(#00b8b1|#00d4cb)"|stroke="(#00b8b1|#00d4cb)"' docs/icon.svg src/**/*.html src/**/*.svg     grep -nE '\.logo[^{]*\{[^}]*color:\s*var\(--accent\)|\.icon[^{]*\{[^}]*color:\s*var\(--accent\)' src/**/*.html src/**/*.css     ``` @@ -334,6 +393,25 @@ adom-ui-linter lint . --category ui-patterns,ai-drivability,header  Fix every FAIL (the hint tells you exactly what to do), address relevant WARNs, re-run to zero before publishing. +### What the linter cannot catch, so you must++The gate is deterministic, which is its strength and its blind spot. Three failure modes+slip straight through it, and all three have shipped:++- **A wrong hex that is still a valid hex.** This page itself carried `#00b8b0` instead of+  the real teal `#00b8b1` for months. Every build was green, every review passed, and the+  error propagated to 148 places in the VS Code themes and 134 in Hydrogen Desktop. A+  one-digit colour error is invisible to a compiler and nearly invisible to an eye. Copy+  brand values from the token table, never retype them, and never trust a colour you+  remember.+- **A colour used in a role it fails.** `--text-3` and `--blue-fill` are legitimate tokens+  that fail as text. Nothing flags `color: var(--text-3)`. Check the role column.+- **"It compiled" as evidence.** A CSS custom property that resolves to nothing still+  builds. A sweep that rewrote `--accent: #00b8b1` into `--accent: var(--accent)` produced+  a clean build, a matching commit SHA, and an app with no background. **The only proof a+  colour change worked is the computed value in the running app or a sampled pixel**, not+  a successful build.+ ---  ## 13. The skill map