@master/internal-site 0.0.0-stage → 0.1.1

package/src/styles/documentation-illustration.css

@@ -0,0 +1,34 @@
+/* One accessible illustration: the bitmap for the current scheme fills the tray's 18px frame. */
+@layer components {
+  .document-illustration { overflow: hidden; border-radius: var(--ui-radius-xl); }
+  .document-illustration img { display: block; width: 100%; height: auto; margin: 0; }
+  .document-illustration img[data-scheme="dark"] { display: none; }
+  .ui-tray[data-illustration-expandable] .ui-tray-title { flex: 1; }
+  .document-illustration-expand { flex: none; }
+  .document-illustration-expand[data-scheme="dark"] { display: none; }
+  /* A quiet caption-level entry, independent of the demo's generated-code panel. */
+  .ui-tray > .ui-disclosure[data-variant="text-description"] { margin-top: 0; padding: 0; border: 0; border-radius: 0; background: transparent; box-shadow: none; }
+  .ui-tray > .ui-disclosure[data-variant="text-description"] > summary { width: fit-content; max-width: calc(100% - 2 * var(--ui-space-sm)); min-height: 2rem; margin-inline: var(--ui-space-sm); padding: 0; gap: var(--ui-space-2xs); color: var(--ui-text-muted); font-size: var(--ui-text-label); font-weight: var(--ui-weight-regular); }
+  .ui-tray > .ui-disclosure[data-variant="text-description"] > summary::before { width: 12px; height: 12px; }
+  .ui-tray > .ui-disclosure[data-variant="text-description"] > summary:hover { color: var(--ui-text-strong); }
+  .ui-tray > .ui-disclosure[data-variant="text-description"] > .ui-disclosure-body { margin-inline: 0; padding-top: var(--ui-space-xs); }
+  /* The text description reads at caption size inside the tray. */
+  .ui-tray-caption > ol { margin: 0; padding-left: 1.25em; }
+  .ui-tray-caption > ol > li + li { margin-top: var(--ui-space-2xs); }
+  .ui-tray-caption strong { color: var(--ui-text-body); font-weight: var(--ui-weight-strong); }
+  .dark .document-illustration img[data-scheme="light"] { display: none; }
+  .dark .document-illustration img[data-scheme="dark"] { display: block; }
+  .dark .document-illustration-expand[data-scheme="light"] { display: none; }
+  .dark .document-illustration-expand[data-scheme="dark"] { display: inline-flex; }
+  @media screen and (prefers-color-scheme: dark) {
+    :root:not(.light, .dark) .document-illustration img[data-scheme="light"] { display: none; }
+    :root:not(.light, .dark) .document-illustration img[data-scheme="dark"] { display: block; }
+    :root:not(.light, .dark) .document-illustration-expand[data-scheme="light"] { display: none; }
+    :root:not(.light, .dark) .document-illustration-expand[data-scheme="dark"] { display: inline-flex; }
+  }
+  @media print {
+    .document-illustration img[data-scheme="light"] { display: block !important; }
+    .document-illustration img[data-scheme="dark"] { display: none !important; }
+    .document-illustration-expand { display: none !important; }
+  }
+}

package/src/styles/documentation-index.css

@@ -0,0 +1,100 @@
+/*
+ * Guide and Reference overviews, set as a book's contents rather than a wall of cards: a numbered directory of the
+ * sections on hairlines, a toolbar with the underline tabs, then each section as a ruled spread — its number, name and
+ * summary held at the start while its entries run beside them. Links change ink, never lift; nothing here is a frame.
+ */
+@layer components {
+  .documentation-index { container-type: inline-size; }
+  .documentation-index :is(h2, h3, p, ul) { margin: 0; }
+  .documentation-index [id] { scroll-margin-top: 6rem; }
+  .documentation-index a { text-decoration: none; }
+  .documentation-index a:focus-visible { @apply --ui-focus-ring; outline-offset: 2px; border-radius: var(--ui-radius-xs); }
+  .documentation-index-count { margin-left: .5em; color: var(--ui-text-muted); font-size: .75rem; font-weight: var(--ui-weight-regular); letter-spacing: .02em; font-variant-numeric: tabular-nums; }
+
+  /* Directory: one row per section on its own hairline; the row's line inks under the pointer, like the contents ruler. */
+  .documentation-index-directory { display: grid; grid-template-columns: repeat(auto-fill, minmax(min(100%, 14rem), 1fr)); column-gap: var(--ui-space-xl); }
+  .documentation-index-directory > a { display: grid; grid-template-columns: 2rem minmax(0, 1fr) auto; align-items: baseline; padding-block: .875rem; color: var(--ui-text-body); box-shadow: inset 0 1px 0 var(--ui-line-hair); transition: color var(--ui-duration-quick), box-shadow var(--ui-duration-quick); }
+  .documentation-index-directory > a > small { color: var(--ui-text-muted); font-size: .75rem; letter-spacing: .04em; font-variant-numeric: tabular-nums; transition: color var(--ui-duration-quick); }
+  .documentation-index-directory > a > b { font-size: .9375rem; font-weight: var(--ui-weight-regular); line-height: 1.5; overflow-wrap: anywhere; }
+  .documentation-index-directory > a:hover { color: var(--ui-text-strong); box-shadow: inset 0 1px 0 var(--ui-text-strong); }
+  .documentation-index-directory > a:hover > small { color: var(--ui-text-strong); }
+  /* The sibling index closes the directory on a row of its own, its summary beside the name. */
+  .documentation-index-directory > a[data-related] { grid-column: 1 / -1; grid-template-columns: 2rem auto minmax(0, 1fr); }
+  .documentation-index-directory > a[data-related] > span { margin-left: var(--ui-space-md); color: var(--ui-text-muted); font-size: var(--ui-text-caption); line-height: 1.5; }
+  .documentation-index-directory > a[data-related] > small { font-size: .875rem; letter-spacing: 0; }
+
+  /* Toolbar: the view tabs stand on the toolbar's own hairline. */
+  .documentation-index-toolbar { display: flex; flex-wrap: wrap; align-items: center; justify-content: space-between; gap: 0 var(--ui-space-md); margin-top: var(--ui-space-3xl); box-shadow: inset 0 -1px 0 var(--ui-line-divider); }
+  .documentation-index-toolbar > p { color: var(--ui-text-muted); @apply --ui-eyebrow-type; }
+  .documentation-index-toolbar > p > .documentation-index-count { letter-spacing: .02em; }
+  .documentation-index-toolbar > .ui-segmented { box-shadow: none; }
+
+  /* Section: a ruled spread. Below 44rem the head sits over its entries. */
+  .documentation-index-section { display: grid; gap: var(--ui-space-lg); padding-block: var(--ui-space-xl) var(--ui-space-2xl); }
+  .documentation-index-section + .documentation-index-section { box-shadow: inset 0 1px 0 var(--ui-line-hair); }
+  .documentation-index-section > header { display: grid; align-content: start; gap: var(--ui-space-xs); }
+  .documentation-index-section > header > small { color: var(--ui-text-muted); font-size: .75rem; line-height: 1rem; letter-spacing: .04em; font-variant-numeric: tabular-nums; }
+  /* A catalog set inside an article (the Design System page) heads its spreads with h3 under the article's h2. */
+  .documentation-index-section h2, .documentation-index-section > header > h3 { color: var(--ui-text-strong); font-size: var(--ui-text-h3); font-weight: var(--ui-weight-heading); line-height: var(--ui-leading-h3); letter-spacing: var(--ui-tracking-h3); overflow-wrap: anywhere; }
+  .documentation-index-section h2 > .documentation-index-count, .documentation-index-section > header > h3 > .documentation-index-count { vertical-align: .125rem; }
+  .documentation-index-section > header > p { max-width: 30rem; color: var(--ui-text-muted); font-size: var(--ui-text-caption); line-height: var(--ui-leading-caption); text-wrap: pretty; }
+
+  /* A section's groups, listed under its summary so a long section can be entered part way. */
+  .documentation-index-groups { display: flex; flex-wrap: wrap; gap: 0 var(--ui-space-md); margin-top: var(--ui-space-2xs); }
+  .documentation-index-groups > a { padding-block: .3125rem; color: var(--ui-text-muted); font-size: var(--ui-text-caption); line-height: 1.5; transition: color var(--ui-duration-quick); }
+  .documentation-index-groups > a:hover { color: var(--ui-text-strong); }
+
+  .documentation-index-categories { display: grid; gap: var(--ui-space-xl); }
+  .documentation-index-categories h3 { margin-bottom: var(--ui-space-2xs); color: var(--ui-text-muted); @apply --ui-eyebrow-type; }
+  .documentation-index-categories h3 > .documentation-index-count { letter-spacing: .02em; }
+
+  /* Entries. Bare titles are a quiet list whose hover wash hangs past the column so the words keep its edge. */
+  .documentation-index-links { padding: 0; list-style: none; }
+  .documentation-index-links:not([data-described]) { margin-inline: -.625rem; }
+  .documentation-index-links li { break-inside: avoid; }
+  .documentation-index-links a { display: grid; align-content: center; min-height: 2.25rem; padding: .375rem .625rem; border-radius: var(--ui-radius-sm); color: var(--ui-text-body); font-size: var(--ui-text-small); line-height: 1.5; overflow-wrap: anywhere; transition: color var(--ui-duration-quick), background-color var(--ui-duration-quick); }
+  .documentation-index-links a > b { font-weight: var(--ui-weight-regular); }
+  .documentation-index-links a > small { color: var(--ui-text-muted); font-size: .75rem; }
+  .documentation-index-links a:has(> small) { display: flex; flex-wrap: wrap; align-items: baseline; align-content: center; gap: 0 var(--ui-space-xs); }
+  .documentation-index-links:not([data-described]) a:hover { color: var(--ui-text-strong); background: light-dark(oklch(22% .002 265 / .045), oklch(100% 0 none / .05)); }
+
+  /* Described entries are ruled rows: the title over its summary, an arrow stepping in under the pointer. */
+  .documentation-index-links[data-described] li + li { box-shadow: inset 0 1px 0 var(--ui-line-hair); }
+  .documentation-index-links[data-described] a { grid-template-columns: minmax(0, 1fr) 1.5rem; column-gap: var(--ui-space-md); padding: var(--ui-space-md) 0; border-radius: 0; }
+  .documentation-index-links[data-described] li:first-child a { padding-top: 0; }
+  .documentation-index-links[data-described] a > b { grid-column: 1; color: var(--ui-text-strong); font-size: var(--ui-text-base); line-height: 1.75rem; }
+  .documentation-index-links[data-described] a > span { grid-column: 1; max-width: 34rem; color: var(--ui-text-muted); font-size: var(--ui-text-small); line-height: 1.7; text-wrap: pretty; transition: color var(--ui-duration-quick); }
+  .documentation-index-links[data-described] a::after { content: "→"; grid-area: 1 / 2; justify-self: end; color: var(--ui-text-muted); line-height: 1.75rem; opacity: 0; translate: -.25rem 0; transition: opacity var(--ui-duration-quick) var(--ui-ease), translate var(--ui-duration-quick) var(--ui-ease), color var(--ui-duration-quick); }
+  .documentation-index-links[data-described] a:hover > span { color: var(--ui-text-body); }
+  .documentation-index-links[data-described] a:is(:hover, :focus-visible)::after { color: var(--ui-text-strong); opacity: 1; translate: 0 0; }
+
+  /* The jump letters hang by half a target so the first letter keeps the column's edge; each letter's own rule closes them. */
+  .documentation-index-letters { display: flex; flex-wrap: wrap; gap: 0 var(--ui-space-3xs); margin-inline-start: -.6875rem; padding-top: var(--ui-space-md); }
+  .documentation-index-letters > a { display: grid; place-items: center; min-width: 2rem; min-height: 2rem; color: var(--ui-text-muted); font-size: var(--ui-text-small); font-variant-numeric: tabular-nums; transition: color var(--ui-duration-quick); }
+  .documentation-index-letters > a:hover { color: var(--ui-text-strong); }
+
+  .documentation-index-alphabet { display: grid; grid-template-columns: repeat(auto-fill, minmax(min(100%, 15rem), 1fr)); gap: var(--ui-space-xl) var(--ui-space-xl); padding-block: var(--ui-space-lg) var(--ui-space-2xl); }
+  .documentation-index-alphabet h2 { margin-bottom: var(--ui-space-2xs); padding-top: var(--ui-space-sm); color: var(--ui-text-strong); font-size: var(--ui-text-h3); font-weight: var(--ui-weight-heading); line-height: var(--ui-leading-h3); box-shadow: inset 0 1px 0 var(--ui-line-hair); }
+
+  @container (width >= 30rem) {
+    .documentation-index-links[data-columns] { columns: 2; column-gap: var(--ui-space-xl); }
+  }
+  @container (width >= 44rem) {
+    .documentation-index-section { grid-template-columns: 13rem minmax(0, 1fr); column-gap: var(--ui-space-2xl); }
+    /* The head stays in view beside a long section, clear of the 60px header. */
+    .documentation-index-section > header { position: sticky; top: 5.5rem; align-self: start; }
+    .documentation-index-groups { flex-direction: column; align-items: start; }
+    /* A bare list's first row stands on the section name's line; a group's eyebrow on the head's number. */
+    .documentation-index-section > .documentation-index-links:not([data-described]) { margin-top: 1.25rem; }
+    .documentation-index-links[data-described] li:first-child a { padding-top: 1.5rem; }
+  }
+  @container (width >= 60rem) {
+    .documentation-index-links[data-columns] { columns: 3; }
+    .documentation-index-categories .documentation-index-links[data-columns] { columns: 2; }
+  }
+  @container (width < 30rem) {
+    .documentation-index-links:not([data-described]) a { min-height: 2.75rem; }
+    .documentation-index-directory > a[data-related] { grid-template-columns: 2rem minmax(0, 1fr); }
+    .documentation-index-directory > a[data-related] > span { grid-column: 2; margin-left: 0; }
+  }
+}

package/src/styles/documents.css

@@ -0,0 +1,4 @@
+/* Surfaces, code and prose: pages that render documents, examples or source. One local stylesheet emits its theme variables once. */
+@import './system/surfaces.css';
+@import './system/code.css';
+@import './system/prose.css';

package/src/styles/documents.ts

@@ -0,0 +1,2 @@
+// Document styles, loaded as the boundary after the interface; see routes.ts.
+import './documents.css'

package/src/styles/foundation.css

@@ -0,0 +1,4 @@
+@import './docs-shell/theme.css';
+@import './system/mixins.css';
+@import './system/tokens.css';
+@import './base.css';

package/src/styles/globals.css

@@ -0,0 +1,2 @@
+@import '@master/css';
+@import './foundation.css';

package/src/styles/interface.css

@@ -0,0 +1,3 @@
+/* Controls and shell: every page in the site shell renders them. One local stylesheet emits its theme variables once. */
+@import './system/controls.css';
+@import './system/shell.css';

package/src/styles/interface.ts

@@ -0,0 +1,2 @@
+// The interface of the site shell, loaded as the second asset boundary; see routes.ts.
+import './interface.css'

package/src/styles/site.ts

@@ -0,0 +1,2 @@
+// The site foundation (the Master CSS entry), loaded first as its own asset boundary; see routes.ts.
+import './globals.css'

package/src/styles/system/DESIGN.md

@@ -0,0 +1,108 @@
+# Site design system: Moonstone / Obsidian
+
+The site's interface vocabulary. Light mode is moonstone (a clean zinc pearl), dark mode is obsidian (zinc-95 glass). The character is restrained and soft: light regular type, hairline contours, small radii, ink rather than blue. The homepage may compose its own layouts but uses these tokens.
+
+## Files
+
+| File | Scope | Loaded |
+| --- | --- | --- |
+| `mixins.css` | `--ui-sheet-face`, `--ui-focus-ring`, `--ui-label-type`, `--ui-eyebrow-type`: shared declarations the component files expand with `@apply` | foundation (Master CSS definitions) |
+| `tokens.css` | `--ui-*` roles: surfaces, lines, text, light, elevation, radius, rhythm, motion, tones, status, code | foundation |
+| `surfaces.css` | `ui-sheet`, `ui-well`, `ui-tray`, `ui-stage`, `ui-compare`, `ui-browser`, `ui-scroll`, `ui-expand` | documents |
+| `controls.css` | `ui-button`, `ui-segmented`, `ui-field`, `ui-input`, `ui-select`, `ui-range`, `ui-check`, `ui-switch`, `ui-copy`, `ui-kbd`, `ui-tooltip`, `ui-menu` | interface |
+| `code.css` | `ui-code`, `ui-tabs`, `ui-inline-code`, `ui-disclosure`, `ui-prompt`, `ui-tree` | documents |
+| `prose.css` | `ui-callout`, `ui-hint` and the article flow helpers | documents |
+| `shell.css` | `ui-header`, `ui-sidebar`, `ui-nav-group`, `ui-nav-link`, `ui-toc`, `ui-pagehead`, `ui-pager`, `ui-dialog`, `ui-results` | interface |
+| `specimens.css` | `ui-item`, `ui-badge`, `ui-label`, `ui-legend`, `ui-measure`, `ui-leader`, `ui-axes`, `ui-swatch`, `ui-palette`, `ui-spacing`, `ui-player` | imported by the components that use it |
+| `data.css` | `ui-table`, `ui-metrics`/`ui-metric`, `ui-bar`, `ui-source`, `ui-params`, `ui-steps`, `ui-index`, `ui-logos`, `ui-chart`, `ui-waterfall` | imported by the components that use it |
+
+Pages load the system in ordered asset boundaries (`site/routes.ts`), each one stylesheet:
+
+- **foundation**: `styles/globals.css`, the only Master CSS entry (`@import '@master/css'`). Every entry joins one project graph, so a second entry delivers the union of both; keep component files out of it.
+- **interface**: `styles/interface.css`, every page in the site shell.
+- **documents**: `styles/documents.css`, unless a page exports `documentStyles = false` because it renders no surfaces, code or prose (the Blog index, 404, the homepage icon handoff).
+
+Interface and documents are local stylesheets: each emits the theme variables it uses once, so add a component file to an existing boundary stylesheet rather than as another import. Bare sections (`/examples`) load the foundation and import only the system files their page renders.
+
+The approved visual specification is the published "Master CSS Site Design System：Moonstone" artifact.
+
+## Rules
+
+1. **Monochrome interface.** Chrome uses ink and pearl only. Hue appears in teaching specimens (`--ui-tone-*`, always named by a legend or label) and status (`--ui-status-*`). Brand gold (`data-variant="gold"`) belongs to the homepage and the brand page, one gold focus per view.
+2. **Zinc neutrals.** Every neutral is the preset's zinc: hue 265 at chroma .0005–.003. Lines and shadows carry no hue of their own (`oklch(22% .002 265 / α)` and `oklch(18% 0 none / α)` in light mode, white and black alphas in dark mode). No blue sheen.
+3. **One material ladder.** canvas → tray → stage → sheet → float; a well sits below its surroundings. Never invent a surface color. Light: canvas 98.6 · tray 96 · stage 98.9 · sheet 100 · well 96.6 · code 99.6. Dark: canvas 19.4 (zinc-95) · tray 17.4 · stage 20.4 · sheet 24.2 · float 26.4 · well 16.4 · code 21.2.
+4. **Legible dark edges.** Dark lines are firmer than light ones so surfaces never blur into each other: hair .075 · contour .11 · divider .13 · strong .22 · mark .32 (white alpha); light: .065 · .095 · .12 · .2 · .3.
+5. **Elevation order.** sink < flat < rise-1 < rise-1h < rise-2 < rise-3 < overlay. Hover lifts 0.5px to rise-1h; press sinks to the well. Do not express state by changing hue.
+6. **Small concentric radii.** 3 / 4 / 6 / 8 / 10 / 14 with a 4px tray inset: tray 14 → stage, code, table and sheet 10; menu 8 → item 4; segmented track 6 + its padding → thumb 6. Nothing rounder except pills and dots.
+7. **Light regular type.** English text runs at 350 (`:root:lang(en)` lowers `--ui-weight-regular`), Han text at 400. Headings are regular (400): size and ink carry the steps. Medium (460) marks a current entry, a control label or a small title; strong (500) is for `<strong>` and short emphasis only. Captions inside components (table heads, tray titles, metric names) are small sans in sentence case. Captions *over a group or a page* — sidebar groups, footer columns, the page kicker, "On this page", the pager's Previous/Next — are eyebrows (`--ui-eyebrow-type`): 11px sans capitals at medium weight, boldly tracked .14em, 16px line; Han text keeps 12px and .1em. A blog post's kicker (category · date) and its closing caption are eyebrows too. Never mono.
+8. **Two widths on one edge.** A documentation article starts every block on one edge. Running text — paragraphs, lists, headings, callouts, rules, disclosures — keeps the reading measure (`--docs-text`, 41rem; the 18px lead runs to 1.125× it). Steps, page tabs, the pager and framed surfaces take the wide column (`--docs-wide`, the measure plus the 252px contents rail). Framed surfaces (code, trays, previews, tables, chart figures, media) hang past both edges by the prose bleed (up to 2rem from 52rem, always leaving a 1rem gutter to the window) and keep their own padding: nothing inside a hanging surface is set back to the text's edge; document steps hang on the end side only, so a step's code ends where every surface ends. Index rows are links, not frames: they keep the column's edges. Where the rail shows (80rem up), a page with contents gives the rail the wide column's room; the article and rail centre together, so every page starts on the same x. Gutters: 20px, 40px from 52rem, then 40→80px beside the sidebar.
+9. **One reading rhythm.** Body 16/32 (line-height 2, `--line`), Han text too; paragraphs part by ¾ line, wide blocks by 1 line, h2 opens on 2 lines and closes on ½ — a section after the first opens on one hairline (`--ui-line-hair`) across the measure, ⅞ line above its heading, none under the page head or after a disclosure that already closes on a hairline — h3 on 1½ and ⅜, h4 on 1¼ and ¼; list items by ¼. Type scale: title 38/44 −.028em · h2 26/35 −.022em · h3 20/28 −.014em · h4 16/24 · lead 18/1.75 · small 14/1.8 · caption 13/1.65 · label 12. The documentation and the blog share it: a post's text is the documentation's measure and prose.
+10. **Converged shadows.** Every layer doubles offset and blur and pulls its spread in by half the offset. No single large blur.
+11. **Purposeful previews.** The stage's contents share the system's visual language, not just its outer frame. Controls that operate a preview use system components; self-contained teaching samples express the same restraint through public preset styles. Departures in color, size or material need a teaching purpose. Optional preview actions start absent: Theme is for a lesson about color schemes, resizing for a demonstrated viewport or container change, and replay for a motion sequence. Ordinary previews inherit the site theme. Source tabs, copying and Generated CSS remain useful inspection tools.
+
+## Shell
+
+The shell follows the original documentation layout, refined:
+
+- **Header** 60px, 32px gutters. Search leads the end group as a quiet hairline pill (glass + ⌘K, 30px tall, 11px / 13px insets — the round end takes a little more), 8px before the community icons; a plain glass in a full target on a phone; the homepage's wide header leaves it out. Section links are plain words (body ink, current one in strong ink at medium weight), no pill. The version is plain text with a chevron. End icons are 18px glyphs in 36px targets that only change ink on hover.
+- **Sidebar** 276px with a 32px start gutter aligned with the logo; it starts with its first group, whose caption stands level with the page kicker and the contents caption (y = header + 56px). Group captions are muted eyebrows; entries are 14px muted on one hairline guide, 32px rows; the current entry inks a short 2px bar on the guide and takes medium weight.
+- **Contents rail** (252px) is a ruler: h2 entries have 24px ticks and h3 entries have 12px ticks with their right ends aligned before the text; titles share a second edge without indentation. The current entry takes strong ink and medium weight without changing its tick length. 13px entries in 34px rows (44px touch targets); "On this page" is a muted eyebrow on the title edge, level with the page kicker. Long lists fold inactive subsections without adding icons; following the section opens them.
+- **Page head** a muted eyebrow kicker, a regular-weight title (fluid 30–38px), an 18px lead (a second lead line, such as a layout's subtitle, at reading size), then 48px of space — no rule — before the reading starts.
+- **Page tabs** between sibling documents (`Tabs`, `ui-segmented[data-variant="underline"]`) are words on one hairline, the current one underlined in ink — the original's tabs, not a raised segmented thumb.
+- **Search trigger** (`ui-search-trigger`, in the phone menu and on the 404) is a quiet row over one hairline with a flat `⌘K` hint; results in the dialog take a chip wash, never a raised frame.
+- **Pager** is one hairline over two links, 80px below the article: an eyebrow (Previous / Next) over a 16px title with a muted arrow; ink on hover, no boxes.
+- **Steps** hang on one hairline rail from flat 28px numbered rings (canvas face, strong contour, sans tabular figures) and take the wide column. A step title is 16px medium; its text is 14/1.8. A row step puts its text on two fifths and its code on three once the list is 46rem wide (narrower, the code stacks under its text). A preview after the steps hangs like any surface and the rail runs into it.
+- **Footer** in the documentation takes the article's wide column from the text's edge; elsewhere it is 72rem. Groups keep 11rem columns from the start (`auto-fill`), so a wide footer leaves the rest to the canvas. Link groups (Docs, Resources, Community, Legal — the license and the trademark policy) under strong-ink eyebrows, 14px links on a 32px pitch. One quiet base row under a hairline, every word 12px tracked .04em: the notice at the start, the theme and language preferences at the end, each an icon and its value with no "Theme:" or "Language:" label (the selects keep those names for assistive technology). No search field — the header carries search.
+
+## Markup
+
+| Layer | Convention |
+| --- | --- |
+| Root | One class per component, prefixed `ui-` |
+| Part | `ui-<component>-<part>`, used only inside that component |
+| Variant | Fixed vocabulary on data attributes: `data-variant`, `data-size`, `data-tone`, `data-elevation`, `data-background`, `data-padding`, `data-density`, `data-shape` |
+| State | Native pseudo-classes and ARIA: `aria-pressed`, `aria-selected`, `aria-current`, `aria-checked`, `[open]`, `:checked`, `:disabled`. `data-state` only to show a static state in documentation; `data-result` for an action's outcome |
+| Tokens | `--ui-*` roles; never raw palette steps in component CSS |
+| Utilities | Master CSS classes compose layout inside content and specimens. They do not paint components, and shell components do not carry long utility lists |
+| React | Components map one-to-one to classes; props only become data attributes |
+
+Content and example markup keep teaching the preset vocabulary (`bg-surface-raised`, `shadow-lg`, …); `--ui-*` tokens are deliberately not utility tokens.
+
+## Decisions and rejected directions
+
+- **Owner direction (2026-11-01 refinement, second pass):** the layout had regressed against a mature documentation site: mixed measures (41rem prose, full-width rules and pager, code bleeding 32px past both edges), a cramped footer, missing tracking, captions competing with entries. Continue the system and refine; captions may be uppercase with proper tracking.
+- Decided (round 1): one 46rem column with no bleed; the page head's closing hairline and the installation layout's italic subtitle removed (the subtitle is now the page head's second lead line); tracked sans eyebrows for group and page captions; borderless pager; footer regrouped into three columns with the search field removed.
+- Rejected (round 1): keeping a 41rem text measure inside a wider column for code and examples — two right edges was the regression the owner saw. A 48rem column (Tailwind's) — at 16px light text it runs past 95 characters a line; 46rem keeps about 88.
+- Rejected (round 1): centring a contents-less page in the full main area — the column jumped sideways between the Installation tabs and the next document.
+- **Owner correction (round 2):** some components bled past the text on purpose — Installation suits the original wider layout, and the messiness came from squeezing steps, previews and code into the reading column. Search moves from the sidebar to the header's end, low-key.
+- Decided (round 2): the two-width grid above, restoring the pre-Moonstone structure (text at 41rem, steps and surfaces wide, previews and code hanging 32px) with every edge aligned; the Installation content back to its original order; search as a header pill; index cards as free-standing hairline sheets (the tray showed empty grey cells under a short last row); rules an author sets before a section heading render as space; list markers in sans (filled disc, tabular figures); code in table cells as a fill without a hairline.
+- Rejected (round 2): one 44–46rem column for everything (round 1) — it cramped steps beside their code and made previews small; the owner preferred the original's breadth. A 42rem text measure inside a 46rem column (critique) — two right edges a few pixels apart read as misalignment; the measure and the wide column now differ by a whole rail.
+- Rejected (round 2): a search field in the sidebar's head — it pushed every group down and duplicated the header's job.
+- Decided (round 3): the corner copy button sits on the first code line's centre and the panel's face fades in behind it, so a long line scrolls under it without running through the glass; a copy group's instruction reads as a sans caption, not as a right-aligned mono status; the 404 search field is 20rem; chart labels and figure notes take the hang.
+- Rule (round 2): a rounded control's inner space is measured, not eyeballed — ink to edge on both sides; a pill's round end gets 1–2px more than its flat-feeling side.
+- **Owner direction (round 4, documentation and blog together):** a surface that hangs wide on purpose must not pull its contents back; the blog's frame opens wider while its text keeps the measure; bolder eyebrow tracking; a 12px tracked footer base row with the license and trademark links merged into the groups; body text at line-height 2 for air; fewer lines inside the browser chrome; a tray and its stage are already two layers, so nothing inside them may form a third.
+- Decided (round 4): `--hang` removed — code lines, file names, table cells, tray heads and captions, chart padding and figure captions keep their own insets; the blog post shares the documentation's 41rem measure inside a frame with 5rem of room on each side (from 64rem); code, examples, media and the next read hang the documentation's 2rem past the text, short of the frame, and the post's header steps out to that same edge with a smaller (28–44px) title that never runs past it and an italic description; the post's close mirrors the header — an eyebrow, the next read as an open title with an italic description, marked on hover by the index's artboard corners, then the way back under one hairline — instead of a raised card; its contents ruler drops the rail's inset so titles keep their room; the browser is one contour drawn over the window, a tray-tone toolbar and a plain address field, and a tray holding only a browser lends it its place without a frame; inside a tray the stage, the source code and its generated-CSS disclosure are told apart by tone, not rings, so the tray's ring is the example's one edge and a framed subject on the stage is the only line within (this reverses round 2's choice to keep the stage contour: the owner judged the third nested line the bigger problem); `DemoAsset` turns the stage itself light or dark instead of placing a sheet on it; a rule before a legacy anchor and its section heading is space only, as before a heading.
+- Rejected (round 4): a toolbar hairline and a sunken address well in the browser chrome — with the tray ring and the window contour they made four nested lines around one example.
+- **Owner direction (round 5, previews):** previews stay brief. No browser chrome unless the viewport is the lesson (`DemoViewport` shows it only when `responsive`; every other preview is `ui-browser[data-variant="plain"]`, a stage parted from the tray by tone), and never an address in it — the tray head names the document and the live width reads beside the range. No Theme toggle unless the example is about color schemes. Selected code tabs take the chip wash with an inset hairline: the tab row scrolls and clips outer shadows, and a raised sheet face is the code panel's own tone.
+- Decided (round 5): every code panel shares one corner (`--code-corner`, ≈11px): the copy action is centred on the first row (the bar, or the first code line) and set in from the end by the same distance; without a bar the code sits in 16px above and below. File names and a prompt's title start on the code's 16px edge; a tab chip is as tall as the copy button (32px) and sits the corner's distance from the start and the top, mirroring the copy action (owner: equal left and top).
+- **Owner direction (round 5, code titles):** a code bar appears only when it carries information — tabs that switch sources, a real file path, or a before/after pair's labels. No language or tool titles (`HTML`, `CSS`, `TypeScript`, `Source`, `Generated CSS`, `Terminal`, `prompt`); the project's CSS is "CSS", never the old "Configuration".
+
+- Decided (round 6, overviews): the Guide and Reference overviews (`DocumentationIndex`) read as a book's contents instead of a card grid. The section cards repeated the catalog below them, and a wall of raised sheets with uneven empty cells was the boxed look the shell had already left behind. Now: a numbered directory of sections on hairlines (the row's line inks under the pointer, like the contents ruler) closed by the cross-link on its own row; the view switch is the underline tabs on the toolbar's hairline under an eyebrow; each section a ruled spread whose number, name, summary and group shortcuts stay sticky beside its entries from 44rem; described entries as ruled rows (title over summary, an arrow stepping in); bare links in columns with the hanging wash; the A–Z view as a book's index with letters in columns. Section icons removed — the numbers order the sections.
+- Rejected (round 6): keeping the icon cards and only flattening them — the duplication between the section cards and the sections remained the problem.
+- **Owner direction (2026-11-01 polish):** return the sidebar, contents rail and header to the original documentation's layout; light regular type; finer spacing and rhythm; smaller radii; zinc rather than cool neutrals; clearer dark edges; restrained and soft overall. This overrides the approved spec's 4/6/10/14/18/24 radii, 520/560/600 weights, hue-255 pearl and mono uppercase labels.
+- Rejected: semibold (600) headings and 560 labels — too heavy against the 350 reading text, the "template" look the owner disliked.
+- Rejected: mono uppercase tracked eyebrows for group captions, table heads and kickers — read as an AI-made signature; captions are small sans now.
+- Rejected: the raised-sheet pill for the current sidebar entry and the sunken well for the current header link — the original ink bar and ink word are quieter.
+- Rejected: hue 255 pearl with a .012-chroma ink for lines and .022-chroma shadows — the visible blue cast made the interface cold.
+- Rejected: a darker obsidian canvas (17.4%) with .085 contours — surfaces and edges blurred together; the zinc-95 canvas with firmer lines separates them without raising the noise.
+- Rejected (round 2): a shorter 48px phone header — the blog and homepage offsets are built on the 60px header, and the gain was small.
+- Rejected (round 2): removing the tray's inner stage contour to avoid "card in card" — the tray is the system's example frame and the stage edge is what separates specimen from caption; instead the dark tray was lifted to 17.4% so it no longer reads as a hole.
+- Rejected (round 2): unframed tables as in the original — the framed sheet keeps sticky heads and horizontal scroll legible; its radius and contour are now small and quiet.
+- Rejected (round 3): a dark stage darker than the canvas (18.4% under a .12 black falloff) — specimens sat in a hole. The dark ladder now mirrors light: tray 17.4 < canvas 19.4 < stage 20.4, with a .08 falloff.
+- **Owner direction (2026-11-01, legacy sweep):** redesign the documentation UI and previews still left from the old site. Decided: the integration and migration logo grids (old `IconButtons`, a hairline table whose short last row left empty grey cells) become free-standing tiles — `ui-logos` for marks with names, `ui-index` with icons for described guides; related views (`Segments`) use `ui-segmented`; a clamped long table is `ui-expand` (canvas fade, one small `ui-button`); an example's usage line (`(resize)`, `(click)`, …) is a muted `ui-hint` led by its gesture, not a heavy paragraph; a setup step's result (`DemoHelloWorld`) is a plain stage without window dots; Theme toggles and responsive chrome removed from examples that are not about color schemes or viewports; the Layout example paints its chart with filled bars on one axis, underline section words and regular-weight figures.
+- **Owner direction (2026-11-01, section rules):** a very quiet divider before each article h2. Decided: the faintest line role across the reading measure (never the wide column), set closer to the heading than to the text before it so it reads as the section's opening; the page's first section, a heading after a disclosure (which closes on its own hairline) and the blog's contents disclosure while it shows keep space only. The documentation and the blog share it through `ui-prose`.
+- **Owner direction (2026-11-01, page-by-page polish, in the system's style):** a full review of every documentation page. Decided: a shell command or a plain-text prompt wraps (commands under a hanging indent, flags kept whole) instead of hiding behind the copy button, and the copy face runs to the panel's contour; every code line keeps one line of height; consecutive code panels part by a small gap; a Generated CSS disclosure right after its source closes the same panel; table values may wrap while the first column's names stay whole (paths break after a slash), numbers never wrap, and a column head's code is plain mono; row steps go two-column only from 46rem; a callout inside a step is an unframed note; callouts keep their tone mostly in the icon (2.5% wash, 12% contour); the stage's floor is 10rem so a single row never floats in an empty well; a demo about a container has no browser chrome and names its range "Container", and the range, its caption and its reading stay one group on phones; captions and readings inside specimens, chart subtitles, chart values and legends are small sans with tabular figures, never mono; demo headings are medium, not semibold; benchmark series start with hues that never read as a status; the integration mark beside a page title is 3.5rem; the footer sets its groups two by two on phones; the canvas paints the document itself; the Design System catalog is a ruled contents list like the Guide and Reference overviews.
+- Open (2026-11-01): the Design System handbook still has its own shell (46rem measure, its own page-head offsets); the delivery illustrations are bitmaps whose labels fall to ~6px at 390px; the color palette has no step ruler; the blog's newest-post gold tick conflicts with rule 1 unless recorded as an exception.
+- **Owner direction (2026-11-01, example controls):** the width presets, range and Fit looked odd inside the stage. Decided: a preview's controls belong to the example, not to the document it shows — they form one row on the tray itself, between the stage and the source, with no surface of their own: 12px to the stage, to the source and to a caption's first line, 16px in from both tray edges like the head's title, every control 32px tall, the live width a sans reading with tabular figures; a setup step's result (`DemoHelloWorld`) and the source that renders it share one tray, the stage over the code.
+
+- **Owner direction (2026-11-02, installation):** steps use open, tabular `01`, `02`, `03` labels without a circular badge; the shared `ui-steps` owns this across Guide and Design System. Installation links form a grouped directory with small marks, left-aligned names and quiet group rules, replacing the logo tiles. Step spacing resets apply only to panels placed by the step grid; nested trays retain their 4px stage-to-source inset and the joined source/generated-output panel.

package/src/styles/system/buttons.css

@@ -0,0 +1,51 @@
+/* Controls — one material, one state order: pressed (sink) < rest (rise-1) < hover (rise-1h, +0.5px) */
+@layer components {
+  .ui-button {
+    appearance: none; display: inline-flex; align-items: center; justify-content: center; gap: var(--ui-space-xs);
+    min-height: 2.375rem; padding: 0 var(--ui-space-md); border: 0; border-radius: var(--ui-radius-md);
+    @apply --ui-sheet-face; color: var(--ui-text-strong);
+    box-shadow: var(--ui-elevation-rise-1);
+    font: var(--ui-weight-medium) .84375rem/1 var(--font-family-sans); letter-spacing: 0; text-decoration: none; white-space: nowrap;
+    cursor: pointer; user-select: none; -webkit-user-select: none;
+    transition: box-shadow var(--ui-duration-quick) var(--ui-ease), background var(--ui-duration-quick) var(--ui-ease), translate var(--ui-duration-quick) var(--ui-ease), color var(--ui-duration-quick);
+  }
+  /* A label longer than its row (large text, narrow screens) wraps inside the button instead of overflowing. */
+  .ui-button:not([data-shape="icon"]) { max-width: 100%; white-space: normal; overflow-wrap: anywhere; line-height: 1.2; text-align: center; }
+  .ui-button > svg { flex: none; width: 1rem; height: 1rem; }
+  .ui-button:where(:hover, [data-state="hover"]):not(:disabled) { translate: 0 -.5px; box-shadow: var(--ui-elevation-rise-1h); }
+  .ui-button:where(:active, [data-state="pressed"]):not(:disabled) { translate: 0 .5px; background: var(--ui-surface-well); box-shadow: var(--ui-elevation-sink); transition-duration: var(--ui-duration-press); }
+  .ui-button:where(:focus-visible, [data-state="focus"]) { @apply --ui-focus-ring; outline-offset: 2px; }
+  .ui-button:disabled { color: var(--ui-text-disabled); background: var(--ui-surface-well); box-shadow: var(--ui-elevation-flat); cursor: not-allowed; }
+  .ui-button[data-size="sm"] { min-height: 2rem; padding-inline: var(--ui-space-sm); border-radius: 5px; font-size: .78125rem; }
+  .ui-button[data-size="lg"] { min-height: 2.75rem; padding-inline: 1.25rem; font-size: .9375rem; }
+
+  /* Primary: ink on moonstone, pearl on obsidian */
+  .ui-button[data-variant="primary"] {
+    color: var(--ui-text-inverse);
+    background: linear-gradient(180deg, light-dark(oklch(32% .0026 265), oklch(98.8% 0 none)), light-dark(oklch(19.5% .003 265), oklch(91.6% .0032 265)));
+    box-shadow: inset 0 1px 0 light-dark(oklch(100% 0 none / .17), oklch(100% 0 none)), inset 0 -1px 0 light-dark(oklch(0% 0 none / .3), oklch(0% 0 none / .13)),
+      0 0 0 1px light-dark(oklch(14% .003 265), oklch(0% 0 none / .6)), 0 1px 1px -.5px var(--ui-shade-1), 0 3px 3px -1.5px var(--ui-shade-2), 0 6px 6px -3px var(--ui-shade-3);
+  }
+  .ui-button[data-variant="primary"]:where(:hover, [data-state="hover"]):not(:disabled) {
+    background: linear-gradient(180deg, light-dark(oklch(36% .0028 265), oklch(100% 0 none)), light-dark(oklch(22% .0034 265), oklch(94% .003 265)));
+    box-shadow: inset 0 1px 0 light-dark(oklch(100% 0 none / .19), oklch(100% 0 none)), inset 0 -1px 0 light-dark(oklch(0% 0 none / .3), oklch(0% 0 none / .13)),
+      0 0 0 1px light-dark(oklch(14% .003 265), oklch(0% 0 none / .6)), 0 1px 1px -.5px var(--ui-shade-1), 0 3px 3px -1.5px var(--ui-shade-2), 0 6px 6px -3px var(--ui-shade-3), 0 10px 10px -5px var(--ui-shade-4);
+  }
+  .ui-button[data-variant="primary"]:where(:active, [data-state="pressed"]):not(:disabled) {
+    background: light-dark(oklch(18% .003 265), oklch(87.5% .0035 265));
+    box-shadow: inset 0 1px 3px light-dark(oklch(0% 0 none / .55), oklch(0% 0 none / .3)), 0 0 0 1px light-dark(oklch(14% .003 265), oklch(0% 0 none / .6));
+  }
+  /* Quiet: no material until touched — toolbars, headers, dense rows */
+  .ui-button[data-variant="quiet"] { background: transparent; color: var(--ui-text-muted); box-shadow: none; }
+  .ui-button[data-variant="quiet"]:where(:hover, [data-state="hover"]):not(:disabled) { color: var(--ui-text-strong); @apply --ui-sheet-face; box-shadow: var(--ui-elevation-rise-1); translate: none; }
+  .ui-button[data-variant="quiet"][aria-pressed="true"] { color: var(--ui-text-strong); background: var(--ui-surface-well); box-shadow: var(--ui-elevation-sink); }
+  /* Gold: brand moments only (homepage hero, brand page) */
+  .ui-button[data-variant="gold"] {
+    color: var(--ui-gold-ink); background: var(--ui-gold-face); text-shadow: 0 1px 0 oklch(100% 0 none / .35);
+    box-shadow: inset 0 1px 0 oklch(100% 0 none / .65), inset 0 -1px 0 oklch(52% .12 58 / .28), 0 0 0 1px light-dark(oklch(58% .12 66 / .7), oklch(82% .14 82 / .55)),
+      0 1px 1px -.5px var(--ui-shade-1), 0 3px 3px -1.5px var(--ui-shade-2), 0 10px 18px -8px light-dark(oklch(72% .16 72 / .42), oklch(82% .16 80 / .3));
+  }
+  .ui-button[data-shape="icon"] { width: 2.375rem; padding: 0; }
+  .ui-button[data-shape="icon"][data-size="sm"] { width: 2rem; }
+
+}

package/src/styles/system/code.css

@@ -0,0 +1,85 @@
+/* Code: a quiet panel that owns its frame. Inside a tray it shares the tray's 10px inner radius and 4px inset. */
+@layer components {
+  .ui-code { position: relative; min-width: 0; overflow: hidden; border-radius: var(--ui-radius-xl); background: var(--ui-surface-code); color: var(--ui-code-text); box-shadow: inset 0 0 0 1px var(--ui-line-contour), 0 1px 0 var(--ui-lip); }
+  /* One corner for every panel: the copy action is centred on the first line of text (a bar's row or the code's first line)
+     and set in from the end by the same distance. A file name starts where the code's lines start; a tab chip, as tall as
+     the copy button, takes the corner's distance from the start and the top. */
+  .ui-code, .ui-prompt { --code-corner: calc(var(--ui-space-md) + var(--ui-text-code) * var(--ui-leading-code) / 2 - 1rem); }
+  .ui-code-bar { display: flex; align-items: center; gap: var(--ui-space-xs); min-height: calc(var(--code-corner) + 2rem); padding: var(--code-corner) var(--code-corner) 0 var(--ui-space-md); }
+  .ui-code-bar > .ui-tabs { flex: 1; min-width: 0; margin-left: calc(var(--code-corner) - var(--ui-space-md)); }
+  .ui-code-file { display: inline-flex; align-items: center; gap: var(--ui-space-xs); flex: 1; min-width: 0; color: var(--ui-text-muted); font: var(--ui-weight-regular) .75rem/1 var(--font-family-mono); }
+  .ui-code-file svg { flex: none; width: 14px; height: 14px; }
+  /* Without a bar the code sits in equal space above and below, the same 16px that sets its lines in from the edge. */
+  .ui-code pre { margin: 0; padding: var(--ui-space-md) 0; overflow-x: auto; font: var(--ui-weight-regular) var(--ui-text-code)/var(--ui-leading-code) var(--font-family-mono); tab-size: 2; scrollbar-width: thin; }
+  .ui-code pre:focus-visible { @apply --ui-focus-ring; outline-offset: -4px; border-radius: var(--ui-radius-md); }
+  /* Under a bar the code starts a short step down, so the file name reads as its caption. */
+  .ui-code:has(> .ui-code-bar) pre { padding-top: var(--ui-space-2xs); }
+  .ui-code-line { display: block; padding: 0 var(--ui-space-lg) 0 var(--ui-space-md); }
+  /* A blank source line keeps one line of height, even when the highlighter leaves an empty token in it. */
+  .ui-code-line { min-height: 1lh; }
+  .ui-code[data-numbers] { counter-reset: line; }
+  .ui-code[data-numbers] .ui-code-line::before { counter-increment: line; content: counter(line); display: inline-block; width: 1.75rem; margin-right: var(--ui-space-sm); color: var(--ui-text-disabled); text-align: right; user-select: none; }
+  .ui-code-line[data-mark="active"] { background: var(--ui-code-active); box-shadow: inset 2px 0 0 var(--ui-line-mark); }
+  .ui-code-line[data-mark="added"] { background: var(--ui-code-added); box-shadow: inset 2px 0 0 color-mix(in oklab, var(--ui-status-success) 70%, transparent); }
+  .ui-code-line[data-mark="removed"] { background: var(--ui-code-removed); box-shadow: inset 2px 0 0 color-mix(in oklab, var(--ui-status-danger) 70%, transparent); }
+  .ui-code-line[data-mark="added"]::after, .ui-code-line[data-mark="removed"]::after { float: right; color: var(--ui-text-disabled); }
+  .ui-code-line[data-mark="added"]::after { content: "+"; }
+  .ui-code-line[data-mark="removed"]::after { content: "−"; }
+  .ui-code-line mark { padding: 1px 2px; border-radius: 3px; background: light-dark(oklch(22% .002 265 / .08), oklch(100% 0 none / .1)); color: inherit; box-shadow: inset 0 -1px 0 var(--ui-line-mark); }
+  .ui-code .t { color: var(--ui-code-function); } .ui-code .a { color: var(--ui-code-property); } .ui-code .s { color: var(--ui-code-string); }
+  .ui-code .p { color: var(--ui-code-punctuation); } .ui-code .k { color: var(--ui-code-keyword); } .ui-code .c { color: var(--ui-code-comment); font-style: italic; } .ui-code .n { color: var(--ui-code-number); }
+  .ui-code > .ui-disclosure { border-top: 1px solid var(--ui-line-hair); }
+  .ui-code > .ui-disclosure > summary { padding-inline: var(--ui-space-md); }
+  .ui-code > .ui-disclosure > pre { padding-top: 0; }
+  /* In a tray, source code (a file tree, a disclosed result) is a lighter field like the stage beside it: tone, not another ring. */
+  .ui-tray > :is(.ui-code, .ui-tree), .ui-tray > .ui-disclosure > .ui-code { box-shadow: none; }
+
+  /* Tabs: a row of quiet chips; the selected one is filled. The row scrolls and so clips any outer shadow, and a raised
+     sheet face is the code panel's own tone: the chip's fill and inset hairline keep it legible in both schemes. */
+  .ui-tabs { display: flex; gap: 2px; min-width: 0; overflow-x: auto; scrollbar-width: none; }
+  .ui-tabs::-webkit-scrollbar { display: none; }
+  .ui-tabs > [role="tab"] {
+    appearance: none; display: inline-flex; flex: none; align-items: center; gap: 6px; min-height: 2rem; padding: 0 .625rem; border: 0; border-radius: var(--ui-radius-md);
+    background: transparent; color: var(--ui-text-muted); font: var(--ui-weight-regular) .75rem/1 var(--font-family-mono); cursor: pointer; transition: color var(--ui-duration-quick), background-color var(--ui-duration-quick), box-shadow var(--ui-duration-quick);
+  }
+  .ui-tabs > [role="tab"] svg { width: 14px; height: 14px; }
+  .ui-tabs > [role="tab"]:hover { color: var(--ui-text-strong); }
+  .ui-tabs > [role="tab"][aria-selected="true"] { background: var(--ui-surface-chip); color: var(--ui-text-strong); box-shadow: inset 0 0 0 1px var(--ui-line-hair); }
+  .ui-tabs > [role="tab"]:focus-visible { @apply --ui-focus-ring; outline-offset: -2px; }
+
+  /* Inline code and file references */
+  .ui-inline-code { padding: .125em .375em; border-radius: var(--ui-radius-xs); background: var(--ui-surface-chip); color: var(--ui-text-strong); box-shadow: inset 0 0 0 1px var(--ui-line-hair); font: var(--ui-weight-regular) .84em/1 var(--font-family-mono); overflow-wrap: anywhere; }
+
+  /* Disclosure: native details, one chevron, calm motion */
+  .ui-disclosure { min-width: 0; }
+  .ui-disclosure > summary { display: flex; flex-wrap: wrap; align-items: center; gap: var(--ui-space-xs); min-height: 2.75rem; color: var(--ui-text-body); font: var(--ui-weight-medium) .8125rem/1.3 var(--font-family-sans); list-style: none; cursor: pointer; }
+  .ui-disclosure > summary::-webkit-details-marker { display: none; }
+  .ui-disclosure > summary::before { content: ""; flex: none; width: 14px; height: 14px; background: currentColor; opacity: .6; mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath d='m6 3.5 4.5 4.5L6 12.5' fill='none' stroke='black' stroke-width='1.6' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E") center / contain no-repeat; transition: rotate var(--ui-duration-base) var(--ui-ease); }
+  .ui-disclosure[open] > summary::before { rotate: 90deg; }
+  .ui-disclosure > summary:hover { color: var(--ui-text-strong); }
+  .ui-disclosure > summary:focus-visible { @apply --ui-focus-ring; outline-offset: 2px; border-radius: var(--ui-radius-md); }
+  .ui-disclosure > summary .ui-disclosure-meta { margin-left: auto; color: var(--ui-text-muted); font: var(--ui-weight-regular) .75rem/1 var(--font-family-sans); }
+  .ui-disclosure[data-variant="rule"] { border-block: 1px solid var(--ui-line-hair); }
+  .ui-disclosure[data-variant="rule"] + .ui-disclosure[data-variant="rule"] { border-top: 0; }
+  .ui-disclosure-body { padding-bottom: var(--ui-space-md); }
+  .ui-disclosure > .ui-disclosure-body > :first-child { margin-top: 0; }
+  .ui-disclosure > .ui-disclosure-body > :last-child { margin-bottom: 0; }
+
+  /* Prompt: copyable prose for agents — reads as text, copies as text */
+  .ui-prompt { display: grid; gap: 0; min-width: 0; overflow: hidden; border-radius: var(--ui-radius-xl); background: var(--ui-surface-code); box-shadow: inset 0 0 0 1px var(--ui-line-contour), 0 1px 0 var(--ui-lip); }
+  .ui-prompt-body { margin: 0; padding: var(--ui-space-xs) var(--ui-space-md) var(--ui-space-md); color: var(--ui-text-strong); font: var(--ui-weight-regular) .9375rem/1.7 var(--font-family-sans); white-space: pre-wrap; }
+  .ui-prompt-body var { padding: 0 .25em; border-radius: var(--ui-radius-xs); background: var(--ui-surface-chip); color: var(--ui-text-body); box-shadow: inset 0 0 0 1px var(--ui-line-hair); font: var(--ui-weight-regular) .8125rem/1 var(--font-family-mono); font-style: normal; }
+
+  /* File tree: names in mono, descriptions in the reading face, guides as hairlines */
+  .ui-tree { margin: 0; overflow-x: auto; overflow-wrap: anywhere; padding: var(--ui-space-sm) 0; border-radius: var(--ui-radius-xl); background: var(--ui-surface-code); box-shadow: inset 0 0 0 1px var(--ui-line-contour), 0 1px 0 var(--ui-lip); }
+  .ui-tree ul { margin: 0; padding: 0; list-style: none; }
+  .ui-tree ul ul { margin-left: 1.375rem; box-shadow: inset 1px 0 0 var(--ui-line-hair); }
+  .ui-tree li > div > * { min-width: 0; }
+  .ui-tree li > div { display: flex; flex-wrap: wrap; align-items: baseline; gap: 2px var(--ui-space-sm); padding: .3125rem var(--ui-space-md); }
+  .ui-tree ul ul li > div { padding-left: var(--ui-space-sm); }
+  .ui-tree svg { flex: none; align-self: center; width: 14px; height: 14px; color: var(--ui-text-muted); }
+  .ui-tree b { color: var(--ui-text-strong); font: var(--ui-weight-regular) var(--ui-text-code)/1.5 var(--font-family-mono); }
+  .ui-tree span { color: var(--ui-text-muted); font-size: .78125rem; }
+  .ui-tree [data-mark="added"] > div { background: var(--ui-code-added); }
+  .ui-tree [data-mark="added"] > div > b::after { content: " +"; color: var(--ui-status-success); }
+}

package/src/styles/system/controls.css

@@ -0,0 +1,110 @@
+@import './buttons.css';
+
+@layer components {
+  /* Segmented control: a sunken track, a raised thumb */
+  .ui-segmented { display: inline-flex; flex-wrap: wrap; gap: 2px; max-width: 100%; padding: 3px; border-radius: calc(var(--ui-radius-md) + 3px); background: var(--ui-surface-well); box-shadow: var(--ui-elevation-sink); }
+  /* Links to sibling pages use the same control; the page being read carries aria-current="page". */
+  .ui-segmented > :is(button, a) {
+    appearance: none; display: inline-flex; align-items: center; justify-content: center; min-height: 1.875rem; min-width: 3.5rem; padding: 0 .75rem; border: 0; border-radius: var(--ui-radius-md); background: transparent;
+    color: var(--ui-text-muted); font: var(--ui-weight-medium) .78125rem/1 var(--font-family-sans); text-decoration: none; white-space: nowrap; cursor: pointer; transition: color var(--ui-duration-quick), background-color var(--ui-duration-quick), box-shadow var(--ui-duration-quick);
+  }
+  .ui-segmented > :is(button, a):hover:not(:disabled) { color: var(--ui-text-strong); }
+  .ui-segmented > :is(button, a):is([aria-pressed="true"], [aria-selected="true"], [aria-checked="true"], [aria-current="page"]) { color: var(--ui-text-strong); @apply --ui-sheet-face; box-shadow: var(--ui-elevation-rise-1); }
+  .ui-segmented > :is(button, a):focus-visible { @apply --ui-focus-ring; outline-offset: 2px; }
+  .ui-segmented > button:disabled { color: var(--ui-text-disabled); cursor: not-allowed; }
+  /* Underline: page-level tabs between sibling documents — words on one hairline, the current one underlined in ink. */
+  .ui-segmented[data-variant="underline"] { display: flex; gap: 0 var(--ui-space-lg); padding: 0; border-radius: 0; background: none; box-shadow: inset 0 -1px 0 var(--ui-line-divider); }
+  .ui-segmented[data-variant="underline"] > :is(button, a) { min-width: 0; min-height: 2.75rem; padding: 0; border-radius: 0; color: var(--ui-text-muted); font: var(--ui-weight-regular) var(--ui-text-small)/1.4 var(--font-family-sans); }
+  .ui-segmented[data-variant="underline"] > :is(button, a):is([aria-pressed="true"], [aria-selected="true"], [aria-checked="true"], [aria-current="page"]) { color: var(--ui-text-strong); background: none; box-shadow: inset 0 -2px 0 var(--ui-text-strong); }
+  .ui-segmented[data-variant="underline"] > :is(button, a):focus-visible { outline-offset: -2px; border-radius: var(--ui-radius-xs); }
+  .ui-segmented[data-size="lg"] { padding: 4px; border-radius: calc(var(--ui-radius-md) + 4px); }
+  .ui-segmented[data-size="lg"] > :is(button, a) { min-height: 2.25rem; border-radius: var(--ui-radius-md); font-size: .8125rem; }
+
+  /* Fields: a well that floats back to the sheet on focus */
+  .ui-field { display: grid; gap: var(--ui-space-xs); color: var(--ui-text-strong); font-size: var(--ui-text-small); font-weight: var(--ui-weight-medium); }
+  .ui-field-hint { color: var(--ui-text-muted); font-size: .75rem; font-weight: var(--ui-weight-regular); }
+  .ui-input, .ui-select {
+    width: 100%; min-height: 2.5rem; padding: .5625rem .75rem; border: 0; border-radius: var(--ui-radius-md);
+    background: var(--ui-surface-well); color: var(--ui-text-strong); box-shadow: var(--ui-elevation-sink);
+    font: var(--ui-weight-regular) var(--ui-text-small)/1.45 var(--font-family-sans); resize: vertical;
+    transition: box-shadow var(--ui-duration-quick), background-color var(--ui-duration-quick);
+  }
+  .ui-input::placeholder { color: var(--ui-text-muted); }
+  .ui-input:hover:not(:focus, :disabled), .ui-select:hover:not(:focus, :disabled) { background: var(--ui-surface-well-hover); }
+  .ui-input:focus, .ui-select:focus-visible { outline: none; background: var(--ui-surface-sheet); box-shadow: inset 0 0 0 1px var(--ui-line-mark), 0 0 0 3px light-dark(oklch(22% .002 265 / .1), oklch(100% 0 none / .12)); }
+  .ui-input:disabled, .ui-select:disabled { color: var(--ui-text-disabled); cursor: not-allowed; }
+  .ui-select { appearance: none; padding-right: 2rem; cursor: pointer;
+    background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='none' stroke='%23888' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='m4.5 6.5 3.5 3.5 3.5-3.5'/%3E%3C/svg%3E");
+    background-repeat: no-repeat; background-position: right .625rem center; background-size: 14px; }
+  .ui-select[data-variant="raised"] { background-color: transparent; background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='none' stroke='%23888' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='m4.5 6.5 3.5 3.5 3.5-3.5'/%3E%3C/svg%3E"), linear-gradient(180deg, var(--ui-surface-sheet), var(--ui-surface-sheet-lo)); background-position: right .625rem center, 0 0; background-size: 14px, auto; box-shadow: var(--ui-elevation-rise-1); font-weight: var(--ui-weight-medium); }
+  /* Overlay: an invisible native select over a positioned label that shows the value (version, language, appearance) */
+  .ui-select[data-variant="overlay"] { position: absolute; inset: 0; width: 100%; height: 100%; min-height: 0; padding: 0; opacity: 0; cursor: pointer; }
+  :has(> .ui-select[data-variant="overlay"]:focus-visible) { @apply --ui-focus-ring; outline-offset: 2px; }
+
+  /* Range: hairline track, filled to value, raised thumb */
+  .ui-range { --value: 50%; appearance: none; width: 100%; min-width: 6rem; height: 1.75rem; margin: 0; background: transparent; cursor: ew-resize; }
+  .ui-range::-webkit-slider-runnable-track { height: 4px; border-radius: var(--ui-radius-pill); background: linear-gradient(90deg, var(--ui-text-strong) var(--value), var(--ui-line-divider) var(--value)); }
+  .ui-range::-moz-range-track { height: 4px; border-radius: var(--ui-radius-pill); background: var(--ui-line-divider); }
+  .ui-range::-moz-range-progress { height: 4px; border-radius: var(--ui-radius-pill); background: var(--ui-text-strong); }
+  .ui-range::-webkit-slider-thumb { appearance: none; width: 16px; height: 16px; margin-top: -6px; border: 0; border-radius: 50%; background: linear-gradient(180deg, oklch(100% 0 none), oklch(96.5% .0011 265)); box-shadow: 0 0 0 1px var(--ui-line-strong), 0 1px 1px var(--ui-shade-1), 0 2px 4px -1px var(--ui-shade-2); }
+  .ui-range::-moz-range-thumb { width: 16px; height: 16px; border: 0; border-radius: 50%; background: linear-gradient(180deg, oklch(100% 0 none), oklch(96.5% .0011 265)); box-shadow: 0 0 0 1px var(--ui-line-strong), 0 1px 1px var(--ui-shade-1), 0 2px 4px -1px var(--ui-shade-2); }
+  .ui-range:focus-visible { outline: none; }
+  .ui-range:focus-visible::-webkit-slider-thumb { box-shadow: 0 0 0 1px var(--ui-line-strong), 0 0 0 2px var(--ui-surface-stage), 0 0 0 4px var(--ui-focus); }
+  .ui-range:focus-visible::-moz-range-thumb { box-shadow: 0 0 0 1px var(--ui-line-strong), 0 0 0 2px var(--ui-surface-stage), 0 0 0 4px var(--ui-focus); }
+
+  /* Check and switch */
+  .ui-check { display: inline-flex; align-items: center; gap: var(--ui-space-xs); color: var(--ui-text-strong); font-size: var(--ui-text-small); cursor: pointer; }
+  .ui-check > input:not(.ui-switch) { appearance: none; display: grid; place-items: center; flex: none; width: 1.125rem; height: 1.125rem; margin: 0; border-radius: var(--ui-radius-sm); background: var(--ui-surface-well); box-shadow: var(--ui-elevation-sink); cursor: pointer; transition: background-color var(--ui-duration-quick), box-shadow var(--ui-duration-quick); }
+  /* An empty box is a small target on a stage of nearly its own tone: a firmer ring keeps it visible in both schemes. */
+  .ui-check > input:not(.ui-switch):not(:checked) { box-shadow: var(--ui-elevation-sink), inset 0 0 0 1px var(--ui-line-divider); }
+  .ui-check > input:not(.ui-switch)::after { content: ""; width: 10px; height: 10px; opacity: 0; background: var(--ui-text-inverse); mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 10 10'%3E%3Cpath d='M2 5.2 4.1 7.3 8 2.8' fill='none' stroke='black' stroke-width='1.6' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E") center / contain no-repeat; }
+  .ui-check > input:not(.ui-switch):checked { background: var(--ui-surface-ink); box-shadow: inset 0 1px 0 light-dark(oklch(100% 0 none / .16), oklch(100% 0 none)), 0 0 0 1px light-dark(oklch(14% .003 265), oklch(0% 0 none / .5)); }
+  .ui-check > input:not(.ui-switch):checked::after { opacity: 1; }
+  .ui-check > input[type="radio"] { border-radius: 50%; }
+  .ui-check > input[type="radio"]::after { width: 6px; height: 6px; border-radius: 50%; mask: none; }
+  .ui-check > input:focus-visible { @apply --ui-focus-ring; outline-offset: 2px; }
+  .ui-switch { position: relative; appearance: none; flex: none; width: 2.25rem; height: 1.375rem; margin: 0; border-radius: var(--ui-radius-pill); background: var(--ui-surface-well); box-shadow: var(--ui-elevation-sink); cursor: pointer; transition: background-color var(--ui-duration-base) var(--ui-ease); }
+  .ui-switch::before { content: ""; position: absolute; top: 3px; left: 3px; width: 1rem; height: 1rem; border-radius: 50%; background: linear-gradient(180deg, oklch(100% 0 none), oklch(96.5% .0011 265)); box-shadow: 0 0 0 1px var(--ui-line-contour), 0 1px 1px var(--ui-shade-1), 0 2px 3px -1px var(--ui-shade-2); transition: translate var(--ui-duration-base) var(--ui-ease); }
+  .ui-switch:checked { background: var(--ui-surface-ink); box-shadow: inset 0 1px 2px oklch(0% 0 none / .3); }
+  .ui-switch:checked::before { translate: .875rem 0; background: light-dark(linear-gradient(180deg, oklch(100% 0 none), oklch(96.5% .0011 265)), linear-gradient(180deg, oklch(26% .0024 265), oklch(20% .002 265))); }
+  .ui-switch:focus-visible { @apply --ui-focus-ring; outline-offset: 2px; }
+
+  /* Copy: an honest result next to the action */
+  .ui-copy { display: inline-flex; align-items: center; gap: var(--ui-space-xs); }
+  .ui-copy-status { color: var(--ui-text-muted); font: var(--ui-weight-regular) .75rem/1 var(--font-family-mono); }
+  .ui-copy-status[data-result="success"] { color: var(--ui-status-success); }
+  .ui-copy-status[data-result="error"] { color: var(--ui-status-danger); }
+
+  /* Keyboard key */
+  .ui-kbd { display: inline-grid; place-items: center; min-width: 1.375rem; height: 1.375rem; padding: 0 .3125rem; border-radius: var(--ui-radius-xs); background: transparent; color: var(--ui-text-muted); box-shadow: inset 0 0 0 1px var(--ui-line-contour); font: var(--ui-weight-regular) .6875rem/1 var(--font-family-mono); }
+
+  @media (pointer: coarse) {
+    .ui-button, .ui-input, .ui-select { min-height: 2.75rem; }
+    .ui-segmented > button { min-height: 2.5rem; }
+  }
+
+  /* Tooltip: a small ink chip; names icon-only controls */
+  .ui-tooltip { position: absolute; z-index: 60; padding: .3125rem .5rem; border-radius: var(--ui-radius-sm); background: var(--ui-surface-ink); color: var(--ui-text-inverse); box-shadow: 0 1px 2px var(--ui-shade-1), 0 4px 10px -4px var(--ui-shade-2); font: var(--ui-weight-regular) .71875rem/1.2 var(--font-family-sans); white-space: nowrap; pointer-events: none; }
+  .ui-tooltip[data-side="bottom"]::before { content: ""; position: absolute; bottom: 100%; left: 50%; translate: -50% 0; border: 4px solid transparent; border-bottom-color: var(--ui-surface-ink); }
+  .ui-tooltip > .ui-kbd { height: 1.125rem; min-width: 1.125rem; margin-left: 6px; background: color-mix(in oklab, var(--ui-text-inverse) 14%, transparent); color: var(--ui-text-inverse); box-shadow: none; }
+
+  /* Menu: a floating sheet of choices (version, language, appearance) */
+  .ui-menu { display: grid; gap: 1px; min-width: 12rem; margin: 0; padding: var(--ui-inset); border-radius: var(--ui-radius-lg); background: var(--ui-surface-float); box-shadow: var(--ui-elevation-rise-3); list-style: none; }
+  .ui-menu-label { padding: .375rem .625rem .25rem; color: var(--ui-text-muted); @apply --ui-label-type; }
+  .ui-menu-item { appearance: none; display: flex; align-items: center; gap: var(--ui-space-xs); width: 100%; min-height: 2rem; padding: 0 .625rem; border: 0; border-radius: var(--ui-radius-sm); background: transparent; color: var(--ui-text-body); font: var(--ui-weight-regular) var(--ui-text-small)/1 var(--font-family-sans); text-align: start; text-decoration: none; cursor: pointer; }
+  .ui-menu-item > svg { flex: none; width: 15px; height: 15px; color: var(--ui-text-muted); }
+  .ui-menu-item > small { margin-left: auto; color: var(--ui-text-muted); font: var(--ui-weight-regular) .6875rem/1 var(--font-family-mono); }
+  .ui-menu-item:is(:hover, [data-highlighted]) { color: var(--ui-text-strong); background: light-dark(oklch(22% .002 265 / .05), oklch(100% 0 none / .06)); }
+  .ui-menu-item[aria-checked="true"] { color: var(--ui-text-strong); font-weight: var(--ui-weight-medium); }
+  .ui-menu-item[aria-checked="true"]::after { content: ""; width: 14px; height: 14px; margin-left: auto; background: currentColor; mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath d='m3.5 8.5 3 3 6-7' fill='none' stroke='black' stroke-width='1.6' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E") center / contain no-repeat; }
+  .ui-menu-item:focus-visible { @apply --ui-focus-ring; outline-offset: -2px; }
+  .ui-menu-separator { height: 1px; margin: var(--ui-space-3xs) .375rem; background: var(--ui-line-hair); }
+
+  /* Result feedback on an icon action: the glyph swaps, the label says what happened */
+  .ui-button[data-result] > svg:first-of-type { display: none; }
+  .ui-button:not([data-result]) > .ui-result-icon { display: none; }
+  .ui-button[data-result="success"] { color: var(--ui-status-success); }
+  .ui-button[data-result="error"] { color: var(--ui-status-danger); }
+  .ui-button[data-result="error"] > svg:first-of-type { display: block; }
+  .ui-button[data-result="error"] > .ui-result-icon { display: none; }
+}