@telepath-computer/television 0.1.206 → 0.1.209

package/dist/skills/tv-theme/SKILL.md

@@ -32,245 +32,345 @@ The split matters because Television's token surface evolves across releases. A
 
 ## Styling surface
 
-Television's CSS has two layers: a **token contract** (semantic colors, palettes, scales) and a **component structure** (the chrome surfaces and content surfaces those tokens compose into). Themes work primarily by overriding tokens; targeted selector rules are escape hatches when the tokens can't fully express a design intent.
+A Television theme is one CSS overlay delivered to two consumers:
 
-### What you're skinning
+- Artifacts receive it after the canonical v1 stylesheet at `/canonical/v1/styles.css`.
+- The browser application fetches the same `theme.css` and adopts it after its bundled styles.
 
-Television is a single-screen-at-a-time display for AI-generated artifacts. The structural pieces:
+Canonical artifact styling is the stable public contract. The redesigned browser chrome also receives the overlay, but complete chrome appearance is a later theming milestone; some token or selector overrides may have no visible effect there. Verify every chrome-specific rule in the running application rather than assuming artifact coverage proves it.
 
-- **The app shell.** A single window that always shows one active screen. There's no home page; the active screen is the page.
-- **`<screen-select>`** — a top-edge or corner control listing available screens; lets the user switch.
-- **`<command-panel>`** — persistent chrome that floats over content (bottom or corner). Hosts global commands and command panel input/content. Uses paper material in dark tone by default.
-- **`<screen-view>` → `<layout-view>`** — page container holding the scrollable canvas where artifact cards live.
-- **`<artifact-view>`** — each artifact card. Glass-material title bar wrapping a paper-material content surface (the artifact's rendered HTML, in an iframe).
-- **Popovers, dropdowns, modals** — paper-material panels for transient and modal UI.
+Themes have two tools:
 
-### The material / tone / level system
+- Override custom properties on `:root` for system-wide choices such as type, spacing, color, and selection.
+- Add narrowly targeted selector rules for a specific surface. Put a purpose comment above each such rule so the intent survives a future re-render against a changed application structure.
 
-Three orthogonal attributes describe every UI surface:
+### Canonical token snapshot
 
-- **`material="paper" | "glass"`** — `paper` is opaque ("this is the content, read me"); `glass` is translucent with a backdrop-filter blur ("I'm chrome over content, peek through me"). Themes affect both: paper surfaces show your `--color-surface`; glass surfaces blend it with what's behind.
-- **`tone="light" | "dark"`** — flips three things on every descendant of the surface: body text color (descendants inherit a light foreground when `tone="dark"`), hairline edge color, and the overlay hover/active tokens. Anything using `currentColor` (icons, tints, `color: inherit` headings) flips automatically. This is what makes dark mode work without per-component overrides.
-- **`level="1" | "2" | "overlay"`** — shadow stack only. `1` = small drop-shadow (popovers, dropdowns), `2` = lifted card (artifact bodies), `overlay` = no shadow (persistent chrome bonded to viewport, like the command panel).
-
-If you want a dark theme: set `color-scheme: dark` and rely on the existing `[tone="dark"]` rules in `materials.css` to flip foregrounds across descendants — you don't need to override every component.
-
-### The token contract
-
-Two source files in `packages/ui/styles/`:
-
-- **`tokens.css`** — palette and scales. Raw values: `--neutral-50` through `--neutral-950`, color palettes (`--red-*`, `--blue-*`, etc.), `--alpha-50` through `--alpha-950`, `--tint-50` through `--tint-950`, type scale (`--text-base`, `--text-sm`, `--text-lg`), spacing (`--space-2`, `--space-4`, `--space-6`, `--space-8`, `--space-10`, `--space-12`, `--space-16`, `--space-20`, `--space-24`, `--space-32`, `--space-48`, `--space-64`), radii (`--radius-4` through `--radius-full`), control heights (`--control-height-xs/sm/md`), shadows (`--shadow-hairline`, `--shadow-control`), fonts (`--font-sans`, `--font-mono`, `--font-brand`).
-- **`theme.css`** — semantic mappings most themes override.
-
-Current `theme.css` content as of this skill build (always read live source for the latest — see below):
+The following build-time snapshot comes from Television's canonical foundation sources. It is useful for orientation, while the running server remains authoritative for the version being themed.
 
 ```css
+/* colors.css */
 :root {
-  --color-bg: var(--neutral-50);
-  --color-bg-muted: var(--neutral-100);
-  --color-surface: var(--white);
-  --color-surface-muted: var(--neutral-100);
-  --color-interactive: var(--neutral-200);
-  --color-interactive-hover: var(--neutral-300);
-
-  /* Borders use alpha so the same hairline reads on light, dark, or
-     image bgs without needing a tone-aware swap. */
-  --color-border: rgba(0, 0, 0, 0.10);
-  --color-border-muted: rgba(0, 0, 0, 0.06);
-
+  /* Colors */
+  --black: #000000;
+  --white: #ffffff;
+
+  /* Neutral */
+  --neutral-50: oklch(98.5% 0 none);
+  --neutral-100: oklch(97% 0 none);
+  --neutral-200: oklch(92.2% 0 none);
+  --neutral-300: oklch(87% 0 none);
+  --neutral-400: oklch(70.8% 0 none);
+  --neutral-500: oklch(55.6% 0 none);
+  --neutral-600: oklch(43.9% 0 none);
+  --neutral-700: oklch(37.1% 0 none);
+  --neutral-800: oklch(26.9% 0 none);
+  --neutral-900: oklch(20.5% 0 none);
+  --neutral-950: oklch(14.5% 0 none);
+
+  /* Alpha */
+  --alpha-50: 4%;
+  --alpha-100: 8%;
+  --alpha-200: 15%;
+  --alpha-300: 22%;
+  --alpha-400: 30%;
+  --alpha-500: 40%;
+  --alpha-600: 50%;
+  --alpha-700: 65%;
+  --alpha-800: 80%;
+  --alpha-900: 90%;
+  --alpha-950: 95%;
+
+  /* Blue */
+  --blue-50: oklch(0.97 0.014 254.604);
+  --blue-100: oklch(0.932 0.032 255.585);
+  --blue-200: oklch(0.882 0.059 254.128);
+  --blue-300: oklch(0.809 0.105 251.813);
+  --blue-400: oklch(0.707 0.165 254.624);
+  --blue-500: oklch(0.623 0.214 259.815);
+  --blue-600: oklch(0.546 0.245 262.881);
+  --blue-700: oklch(0.488 0.243 264.376);
+  --blue-800: oklch(0.424 0.199 265.638);
+  --blue-900: oklch(0.379 0.146 265.522);
+
+  /* Red — the destructive and error hue: a press that destroys, a rejected
+     token, a failure line. Tailwind's red, like the blue. */
+  --red-50: oklch(0.971 0.013 17.38);
+  --red-100: oklch(0.936 0.032 17.717);
+  --red-200: oklch(0.885 0.062 18.334);
+  --red-300: oklch(0.808 0.114 19.571);
+  --red-400: oklch(0.704 0.191 22.216);
+  --red-500: oklch(0.637 0.237 25.331);
+  --red-600: oklch(0.577 0.245 27.325);
+  --red-700: oklch(0.505 0.213 27.518);
+  --red-800: oklch(0.444 0.177 26.899);
+  --red-900: oklch(0.396 0.141 25.723);
+
+  /* Yellow — the attention color: worn by things that need noticing exactly
+     while they apply (the update bell), never for emphasis, which is the key
+     color's job. */
+  --yellow-50: oklch(0.987 0.026 102.212);
+  --yellow-100: oklch(0.973 0.071 103.193);
+  --yellow-200: oklch(0.945 0.129 101.54);
+  --yellow-300: oklch(0.905 0.182 98.111);
+  --yellow-400: oklch(0.852 0.199 91.936);
+  --yellow-500: oklch(0.795 0.184 86.047);
+  --yellow-600: oklch(0.681 0.162 75.834);
+  --yellow-700: oklch(0.554 0.135 66.442);
+  --yellow-800: oklch(0.476 0.114 61.907);
+  --yellow-900: oklch(0.421 0.095 57.708);
+  --yellow-950: oklch(0.286 0.066 53.813);
+
+  /* Green, orange, purple — accent ramps. Tailwind's values, like the
+     blue. */
+  --green-50: oklch(0.982 0.018 155.826);
+  --green-100: oklch(0.962 0.044 156.743);
+  --green-200: oklch(0.925 0.084 155.995);
+  --green-300: oklch(0.871 0.15 154.449);
+  --green-400: oklch(0.792 0.209 151.711);
+  --green-500: oklch(0.723 0.219 149.579);
+  --green-600: oklch(0.627 0.194 149.214);
+  --green-700: oklch(0.527 0.154 150.069);
+  --green-800: oklch(0.448 0.119 151.328);
+  --green-900: oklch(0.393 0.095 152.535);
+
+  --orange-50: oklch(0.98 0.016 73.684);
+  --orange-100: oklch(0.954 0.038 75.164);
+  --orange-200: oklch(0.901 0.076 70.697);
+  --orange-300: oklch(0.837 0.128 66.29);
+  --orange-400: oklch(0.75 0.183 55.934);
+  --orange-500: oklch(0.705 0.213 47.604);
+  --orange-600: oklch(0.646 0.222 41.116);
+  --orange-700: oklch(0.553 0.195 38.402);
+  --orange-800: oklch(0.47 0.157 37.304);
+  --orange-900: oklch(0.408 0.123 38.172);
+
+  --purple-50: oklch(0.977 0.014 308.299);
+  --purple-100: oklch(0.946 0.033 307.174);
+  --purple-200: oklch(0.902 0.063 306.703);
+  --purple-300: oklch(0.827 0.119 306.383);
+  --purple-400: oklch(0.714 0.203 305.504);
+  --purple-500: oklch(0.627 0.265 303.9);
+  --purple-600: oklch(0.558 0.288 302.321);
+  --purple-700: oklch(0.496 0.265 301.924);
+  --purple-800: oklch(0.438 0.218 303.724);
+  --purple-900: oklch(0.381 0.176 304.987);
+
+  /* Tint */
+  --tint-50: color-mix(in srgb, currentColor var(--alpha-50), transparent);
+  --tint-100: color-mix(in srgb, currentColor var(--alpha-100), transparent);
+  --tint-200: color-mix(in srgb, currentColor var(--alpha-200), transparent);
+  --tint-300: color-mix(in srgb, currentColor var(--alpha-300), transparent);
+  --tint-400: color-mix(in srgb, currentColor var(--alpha-400), transparent);
+  --tint-500: color-mix(in srgb, currentColor var(--alpha-500), transparent);
+  --tint-600: color-mix(in srgb, currentColor var(--alpha-600), transparent);
+  --tint-700: color-mix(in srgb, currentColor var(--alpha-700), transparent);
+  --tint-800: color-mix(in srgb, currentColor var(--alpha-800), transparent);
+  --tint-900: color-mix(in srgb, currentColor var(--alpha-900), transparent);
+  --tint-950: color-mix(in srgb, currentColor var(--alpha-950), transparent);
+
+  /* Color roles — what a color is for, resolved onto the ramps above. */
   --color-text: var(--neutral-900);
   --color-text-muted: var(--neutral-500);
+  /* The interface's key color — what carries emphasis and marks the thing
+     you are on. Selection reads as this rather than as a heavier grey, so
+     "hovered" and "selected" differ in hue, not just in weight. */
+  --color-primary: var(--blue-600);
+  /* A fill and the text that survives on it are a pair. Naming the foreground
+     keeps the contrast a stated decision rather than something each use site
+     guesses at — white on blue-500 measures 3.76:1 and fails AA at body size. */
+  --color-on-primary: var(--white);
+  --color-selected: var(--color-primary);
+  /* What the app's own content sits on, behind the surfaces it holds. Darker
+     than those surfaces rather than lighter, so a white one reads as lifted
+     off it — a gap of background is how the app shows where its own chrome
+     ends and something it is holding begins. */
+  --color-background: var(--neutral-200);
+  /* The ground of a document or artifact the app holds. Surface vocabulary
+     belongs to that held content; the chrome's own ground stays
+     --color-background. */
+  --color-surface: var(--white);
+  /* A quiet region within a held surface: distinct without reading as a
+     second layer of app chrome. */
+  --color-surface-muted: var(--neutral-100);
+  /* The ordinary seam between surface regions. Ten percent is deliberate:
+     the alpha ramp's neighbouring steps are too faint and too strong. */
+  --color-border: rgb(0 0 0 / 10%);
+  /* A repeated or subordinate seam should organize without boxing things in;
+     six percent stays below the ordinary border without disappearing. */
+  --color-border-muted: rgb(0 0 0 / 6%);
+  /* A link follows its surrounding text unless a theme gives it an accent. */
   --color-link: inherit;
-  --color-focus-ring: var(--neutral-500);
-  --color-overlay-backdrop: rgb(0 0 0 / 0.5);
-  --color-highlight: rgb(255 255 255 / 0.5);
-  --color-primary: var(--blue-500);
+  /* The destructive and error role. */
   --color-danger: var(--red-600);
+  /* The affirmative and completed-state role. */
+  --color-success: var(--green-600);
+  /* The caution and warning role. */
+  --color-warning: var(--orange-600);
 
   color-scheme: light;
 }
-```
 
-`color-scheme: dark` flips OS-level chrome (scrollbars, form controls) — set it for dark themes so native widgets don't fight the look.
-
-### Reading the live token surface
-
-The block above is a build-time snapshot. **For any nontrivial theme, also read the actual `tokens.css` and `theme.css` files at authoring time** to catch additions/renames/removals since this skill was last built.
+/* text.css */
+:root {
+  /* Type */
+  /* The base the steps below compute from. */
+  --text-base: 14px;
+  --text-sm: round(calc(var(--text-md) / var(--text-scale)), 1px);
+  --text-md: var(--text-base);
+  --text-lg: round(calc(var(--text-md) * var(--text-scale)), 1px);
+  --text-xl: round(calc(var(--text-lg) * var(--text-scale)), 1px);
+  --text-2xl: round(calc(var(--text-xl) * var(--text-scale)), 1px);
+  --text-3xl: 24px;
+  --text-4xl: 30px;
+  --text-scale: 1.125;
+  --leading-base: 1.5;
+
+  /* Fonts */
+  --font-sans: "Hind", -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
+  --font-mono: ui-monospace, "SF Mono", SFMono-Regular, Menlo, monospace;
+  --font-weight-normal: 400;
+  --font-weight-medium: 500;
+  --font-weight-body: var(--font-weight-medium);
+  --font-weight-semibold: 600;
+}
 
-Preferred — fetch from a running Television server:
+/* spacing.css */
+:root {
+  /* Spacing */
+  --space-2: 2px;
+  --space-4: 4px;
+  --space-6: 6px;
+  --space-8: 8px;
+  --space-10: 10px;
+  --space-12: 12px;
+  --space-16: 16px;
+  --space-20: 20px;
+  --space-24: 24px;
+  --space-32: 32px;
+  --space-48: 48px;
+  --space-64: 64px;
+
+  /* Radius */
+  --radius-4: 4px;
+  --radius-6: 6px;
+  --radius-8: 8px;
+  --radius-12: 12px;
+  --radius-16: 16px;
+  --radius-24: 24px;
+  --radius-full: 9999px; /* pill — fully rounded ends at any element size */
+}
 
-```bash
-# Default local server URL is http://localhost:32848
-curl http://localhost:32848/canonical/v1/styles.css | head -300
+/* shadows.css */
+:root {
+  /* The elevation a floating panel lifts off the page with: a broad soft
+     throw and a tight contact shadow. A role, not a ramp — there is one
+     elevation in the system; a scale grows if more appear. */
+  --shadow-panel:
+    0 8px 24px rgba(0, 0, 0, 0.12),
+    0 2px 8px rgba(0, 0, 0, 0.06);
+}
 ```
 
-The bundled canonical stylesheet inlines both `tokens.css` and `theme.css`. If you're talking to a non-default server, get the URL from `tv state` or from the connection the user is targeting.
-
-Alternative — from a Television source checkout:
+For nontrivial work, read the complete live canonical stylesheet:
 
 ```bash
-cat <television-checkout>/packages/ui/styles/tokens.css <television-checkout>/packages/ui/styles/theme.css
+# The default local server URL is http://localhost:32848.
+curl http://localhost:32848/canonical/v1/styles.css
 ```
 
-### Tokens vs. selectors — pick the right tool
-
-Themes have two complementary tools:
-
-- **Override semantic tokens on `:root`** when you want a change to propagate everywhere it's relevant — every paper surface, every body text, every focus ring. One token edit, system-wide effect. Use this for the look's foundations: backgrounds, foregrounds, primary accents, border weights.
-- **Override specific selectors** when the intent is local to a surface — the command panel input gets a special background, the artifact title bar uses a custom font, the layout canvas gets a subtle background image. Selectors give surgical control; tokens can't always express what a design wants.
-
-Both are first-class. A typical theme uses tokens for ~80% of its effect and selector-level rules for the rest. Don't avoid selectors out of orthodoxy; use them where they fit.
-
-The one rule for selector-level rules: **comment them with their purpose.** When Television's component structure shifts in a future release, the comment is what lets an agent re-author the rule against the new structure. Without the comment, a stale selector is just dead CSS — nobody knows what it was for.
-
-## Surface-by-surface guidance
-
-A theme that touches `:root` tokens will affect every surface listed below. The notes here describe what each surface consumes so you know which tokens drive which look — useful for predicting how a token change will land.
-
-### App background and wallpaper
-
-`<television-app>` is the root surface — the thing that fills the window. Out of the box it shows a bundled wallpaper image with a fallback background color. Two app-level tokens control this layer:
+For another server, run `tv status`, read `serverURL` from its JSON output, and fetch `<serverURL>/canonical/v1/styles.css`.
 
-- **`--app-bg`** — base background color, defaulting to `var(--color-bg)`. Shows through wherever `--app-wallpaper` is transparent or set to `none`.
-- **`--app-wallpaper`** — the `background-image` value, defaulting to the bundled wallpaper `url(...)`. Set this to `none` to remove the wallpaper (so `--app-bg` shows), or to a `url(...)` (typically pointing at a theme asset) to use a custom wallpaper.
+From a Television checkout, the authored canonical foundation lives under `specs/ui/foundation/`; `colors.css`, `text.css`, `spacing.css`, and `shadows.css` define its custom properties, while `prose.css` shows how artifact documents consume them.
 
-Theme levers:
+`color-scheme: dark` controls browser-native widgets such as scrollbars and form controls. Set it when the theme uses a dark ground.
 
-- Want a flat colored background? `:root { --app-wallpaper: none; }` and override `--color-bg` (or `--app-bg` directly for finer control).
-- Want a custom wallpaper? `:root { --app-wallpaper: url(my-bg.jpg); }` where `my-bg.jpg` is in the theme's `resources/` folder (the server will rewrite the relative URL).
-- The default-look bundled wallpaper is `packages/web/src/assets/wallpapers/clouds.jpg` — themes don't import or reference it; they replace the variable.
+## Current browser chrome structure
 
-### Buttons
+Use this map only for chrome-specific rules and verify the result in the running version:
 
-Television has three button stories: variant-styled buttons, ghost buttons (chromeless overlay hover), and bespoke chrome-button shapes (close buttons, breadcrumbs, etc.).
+- **`#app`** fills the window. Its `.app-sidebar` and `.app-main` children hold the sidebar and the main stage.
+- **`.sidebar`** is the permanent channel list. `.channel[aria-current]` is the selected channel; `.sidebar-foot` holds channel creation.
+- **`.top-bar`** holds stage navigation controls.
+- **`.stage`** is the artifact-page viewport. `.filmstrip` contains `.page` entries, and `.page[selected]` is the selected page.
+- **`.artifact-frame`** is the white document frame. `.artifact-content` holds the document and `.artifact-title-bar` is the quiet lower title band.
+- **Popovers and dialogs** use ordinary `[popover]` and `dialog` elements with the application foundation's panel treatment.
 
-What each consumes:
+These selectors are current implementation structure, not canonical artifact API. A theme skill should retain the visual purpose of each selector rule so an agent can map that purpose onto the running structure when re-rendering.
 
-- **Default `<button>`** — `--color-text` (text), `--color-interactive` (resting bg), `--color-interactive-hover` (hover bg), `--control-height-md` (28px outer height), `--shadow-control` (subtle drop shadow on resting state).
-- **`<button variant="ghost">`** — fully chromeless, no fill. Hover/active backgrounds use `--color-overlay-hover` / `--color-overlay-active` (semantic overlay tokens that auto-flip with the surface's `tone`). The transparent-chrome auto-tone watcher (`packages/ui/utils/button-tone.ts`) samples `[variant="ghost"]`, `[variant="glass"]`, and `[material="glass"]` when they create a new tone boundary; nested transparent chrome inherits an ancestor `tone` unless it explicitly declares its own.
-- **`<button variant="primary">`** — emphasis button. Fills with `--color-primary` for the bg, `--white` for text.
-- **Icon-only buttons** — `<button icon-only>` becomes a square at `--control-height-md` per side.
+## Surface guidance
 
-Theme levers:
+### Application and stage ground
 
-- Adjust `--color-interactive` / `--color-interactive-hover` for default-button affordance.
-- Adjust `--color-overlay-hover` / `--color-overlay-active` to change ghost-button hover intensity (these also affect dropdown items and other chromeless overlays).
-- Adjust `--color-primary` for emphasis-button fills.
-- Don't set `cursor: pointer` on buttons — there's a global rule in `elements.css` that sets `cursor: default` to match the macOS-native feel.
+`--color-background` is the main redesigned chrome ground behind stage pages. The sidebar and artifact frame use `--white` as their authored surface. Global text uses `--color-text` and `--color-text-muted`.
 
-### Artifact title bars
+A theme can establish its broad palette with current role tokens:
 
-The chrome strip at the top of each `<artifact-view>` card. Uses **glass** material (translucent + backdrop-blur). Tone is sampled from the artifact content beneath it, so the title bar adapts: a dark-content artifact gets `tone="dark"` and a light-foreground title; a light-content artifact gets the inverse.
-
-What it consumes:
-
-- The glass tint (which composites against the artifact body) — driven by `materials.css` rules referencing the alpha scale and current surface tone.
-- `--color-text` / `--color-text-muted` for the title text and any sub-text.
-- `--color-border` for the hairline rim around the glass surface.
-
-Theme levers:
-
-- Adjust `--color-border` to change the title bar's edge weight.
-- Adjust the title's font weight or letter spacing via selector-level rules on `artifact-view > header` if the design needs a non-token change (comment the rule with purpose).
-
-### Command panel — input + content
-
-`<command-panel>` is the persistent chrome at the bottom (or corner) of the app. It hosts the command panel input (typically a textarea) and command panel content above it. By default uses **paper** material in **dark** tone, **`level="overlay"`** (no shadow — it's bonded to the viewport).
-
-What it consumes:
-
-- The paper-dark surface — a near-black opaque fill defined by `materials.css` reading from the `[tone="dark"]` overrides of `--color-surface` and related tokens.
-- `--color-text` (descendants inherit, but with `tone="dark"` flipping descendants to a light foreground).
-- `--color-text-muted` for secondary text in the stream (timestamps, system messages).
-- `--color-border` / `--color-border-muted` for separators between messages.
-- The input's textarea consumes `--color-interactive` (background) and `--color-border` (rim).
-
-Theme levers:
-
-- Override the dark-tone surface color: target `[tone="dark"]` in your theme and set `--color-surface` (or set it on `command-panel` directly with a purpose comment).
-- Adjust message-stream separator weight via `--color-border-muted`.
-- Adjust the command panel input's affordance via `--color-interactive`.
-- For dramatic looks (a saturated command panel background, a textured command panel surface), target `command-panel` directly with a purpose comment.
-
-### Popovers and dropdowns
-
-Anchored panels for menus and inline forms. Paper material, light tone typically, `level="1"` (small drop-shadow). Dismiss on outside click.
-
-What they consume:
-
-- `--color-surface` (paper fill).
-- `--color-border` (hairline rim).
-- `--color-text` (label text), `--color-text-muted` (secondary labels).
-- `--color-overlay-hover` / `--color-overlay-active` for hover/active states on individual items (these are *also* used by ghost buttons, so changing them affects both surfaces — usually fine, since the relationship is semantic).
-- `--shadow-control` for the drop shadow (defined as a soft 2-layer shadow).
-
-Theme levers:
-
-- Surface color via `--color-surface`.
-- Hairline rim via `--color-border`.
-- The overlay-hover token controls both popover-item and ghost-button hover; usually move them together.
-
-### Modal sheets
-
-Full-screen overlays for blocking flows. Paper material, larger than popovers, no specific level (often `level="2"`).
-
-What they consume:
-
-- `--color-surface` (fill).
-- `--color-overlay-backdrop` for the scrim behind the modal (the dark veil over the rest of the app while the modal is open).
-- All the popover tokens for internal elements.
+```css
+:root {
+  --color-background: var(--neutral-900);
+  --color-text: var(--neutral-100);
+  --color-text-muted: var(--neutral-400);
+  --color-primary: var(--blue-400);
+  --color-selected: var(--color-primary);
+  --color-on-primary: var(--white);
+  color-scheme: dark;
+}
+```
 
-Theme levers:
+Changing `--white` has a wider meaning than changing a role token: canonical artifacts and several chrome surfaces use it directly. Prefer semantic roles where they express the intent, and visually inspect any raw-palette override.
 
-- The scrim via `--color-overlay-backdrop`.
-- The modal surface via `--color-surface`.
+### Sidebar
 
-### Layout canvas
+The selected channel uses `--color-selected` with `--color-on-primary`; group labels use `--color-text-muted`; the sidebar ground is `--white`. Local texture or typography needs a purpose-commented selector rule:
 
-The scrollable area inside `<screen-view>` where artifact cards live. Has its own scroll position and pan/zoom semantics.
+```css
+/* Keep the channel list visually distinct from the stage with a warm paper ground. */
+.sidebar {
+  background: #fffaf0;
+}
+```
 
-What it consumes:
+### Stage pages and artifact frames
 
-- `--color-bg` for the canvas background (the "page" surface).
-- `--color-bg-muted` if the canvas distinguishes content areas (e.g. gutter regions vs. card region).
-- `--color-border-muted` for any grid lines, if a future debug mode shows them.
+`.stage` consumes `--color-background`. A selected artifact is the `.page[selected]` entry. The frame itself is `.artifact-frame` with an inset `.artifact-content` and lower `.artifact-title-bar`.
 
-Theme levers:
+```css
+/* Give the selected document's lower title band a quiet orientation tint. */
+.page[selected] > .artifact-frame .artifact-title-bar {
+  background: color-mix(in srgb, var(--color-primary) 8%, transparent);
+}
+```
 
-- `--color-bg` is the highest-leverage single token in any theme — it determines the page's overall feel.
-- `--color-bg-muted` for related secondary surfaces.
+The artifact document renders inside its own iframe. Style the document through canonical tokens or document markup; a chrome selector cannot cross the iframe boundary.
 
-### Bare HTML in artifacts
+### Popovers and dialogs
 
-Artifact content is HTML rendered inside an iframe. The iframe links `/canonical/v1/styles.css`, which the server composes from the canonical bundle plus your active theme. So everything below works in artifacts the same way it does in the app chrome.
+Application popovers and dialogs share a white panel ground, radius, and `--shadow-panel`. Canonical artifact controls have their own public component and bare-element rules in the live stylesheet. Keep an app-chrome selector scoped when the change should not affect artifact documents.
 
-Default styling for bare tags is in `packages/ui/styles/elements.css`:
+### Artifact documents
 
-- `<body>` uses `--color-bg` background, `--color-text` text, `--font-sans` family.
-- `<h1>`–`<h6>` use `--font-brand` (often the same as `--font-sans` unless overridden), with the type scale tokens (`--text-base`, `--text-lg`, `--text-xl`) and `--color-text` for color.
-- `<a>` uses `--color-link` (defaults to `inherit` — links read in the body color unless a theme sets otherwise).
-- `<code>` and `<pre>` use `--font-mono`, `--color-bg-muted` for the background, `--color-text` for content.
-- Form controls (`<input>`, `<textarea>`, `<select>`) consume `--control-height-md`, `--color-interactive`, `--color-border`, `--color-focus-ring`.
+Artifacts load the canonical stylesheet plus the active theme. The canonical foundation provides:
 
-Theme levers:
+- palette and role properties such as `--neutral-*`, `--blue-*`, `--color-text`, `--color-text-muted`, `--color-primary`, and `--color-background`;
+- typography properties such as `--font-sans`, `--font-mono`, `--text-*`, and `--font-weight-*`;
+- spacing and radius properties such as `--space-*` and `--radius-*`;
+- `--shadow-panel`;
+- semantic bare-HTML prose and the canonical v1 components.
 
-- The same `:root` tokens that drive the app chrome drive bare HTML — there's no separate "artifact theme."
-- For a theme with a distinctive link color (e.g. a brand accent), set `--color-link: <value>`.
-- For a theme with a custom code/pre font, override `--font-mono`.
+Read the live stylesheet before using a property not present in the snapshot. Theme CSS may also include `@font-face`, media queries, and rules for authored artifact markup.
 
-## What's in scope for a theme
+## Theme contents
 
-- CSS custom properties on `:root` — the primary tool.
-- `@font-face` declarations for custom typography (font files in the skill's `resources/` folder; reference relatively from `theme.css`, e.g. `url(MyFont.woff2)` — the render step copies them into the theme folder).
-- Background images, decorative images (same path — `resources/` in the skill, copied alongside `theme.css`).
-- `@media (prefers-color-scheme: dark)` blocks if the theme should react to OS-level light/dark.
-- Selector-level rules **with purpose comments** for design intent the tokens can't fully express.
+A theme may contain:
 
-## What's out of scope
+- CSS custom-property overrides;
+- `@font-face` declarations, with files stored beside `theme.css`;
+- background and decorative images stored beside `theme.css`;
+- `@media` blocks;
+- purpose-commented selector rules.
 
-- JavaScript hooks — themes are static styling assets.
-- Theme manifests with metadata beyond the SKILL.md.
-- Multiple variants within one theme (a theme is one look; if you want a dark variant of a light theme, that's a separate theme).
+Themes are static CSS assets. They do not provide JavaScript hooks or a metadata manifest, and one theme name resolves to one `theme.css` overlay.
 
 ## Workflow
 
@@ -288,11 +388,11 @@ Theme authoring has two phases. **Iterate first** — work directly on `theme.cs
 
    ```css
    /*
-    * Active artifact title bar gets a faint warm tint as a quiet "you are here"
-    * cue — design wanted on-screen orientation without a heavier indicator.
+    * Give the selected document's lower title band a faint warm tint as a
+    * quiet orientation cue without adding a heavier indicator.
     */
-   [data-active] > .artifact-title {
-     background: color-mix(in srgb, var(--color-text) 4%, transparent);
+   .page[selected] > .artifact-frame .artifact-title-bar {
+     background: color-mix(in srgb, var(--color-primary) 8%, transparent);
    }
    ```
 
@@ -316,7 +416,7 @@ The SKILL.md should have:
 - **Design choices.** Bulleted list of decisions with rationale. E.g. *"Background is near-black to evoke low-light comfort"*, *"Primary accent is muted teal — saturated enough to read on dark, restrained enough not to scream."*
 - **Style overrides.** Copy the contents of the iterated `theme.css`, comments and all. The purpose comments you wrote during iteration are what make the theme re-renderable.
 - **Assets.** List of files in `resources/`, what each is, what `theme.css` rule references it. Copy the assets from the live theme folder into `resources/`.
-- **Render instructions.** A short section telling future invocations how to render this skill: "fetch the live Television token surface (`/canonical/v1/styles.css` or `<checkout>/packages/ui/styles/{tokens,theme}.css`); map this skill's Intent + Design choices + Style overrides onto the current surface; emit `<storagePath>/themes/<name>/theme.css` and copy `resources/*` to `<storagePath>/themes/<name>/`."
+- **Render instructions.** A short section telling future invocations how to render this skill: "fetch the live Television token surface from `/canonical/v1/styles.css` or read `<checkout>/specs/ui/foundation/{colors,text,spacing,shadows,prose}.css`; inspect the running browser structure for chrome selectors; map this skill's Intent + Design choices + Style overrides onto the current surface; emit `<storagePath>/themes/<name>/theme.css` and copy `resources/*` to `<storagePath>/themes/<name>/`."
 
 Once exported, the iterated `<storagePath>/themes/<name>/` folder and the skill should be in sync. Future edits should happen in both — update `theme.css` for the live feedback loop, update the skill's **Style overrides** section in lockstep so the durable record stays current. If they drift, the skill is the source of truth.
 
@@ -327,9 +427,9 @@ When Television's token surface or component structure changes (new tokens added
 Recovery procedure (the theme skill makes this possible):
 
 1. **Read the current Television surface:**
-   - Running server: `curl http://localhost:32848/canonical/v1/styles.css | head -300` (or substitute the actual server URL from `tv state`).
-   - Or, from a checkout: `cat <television-checkout>/packages/ui/styles/{tokens,theme}.css`.
-2. **Read the theme's skill** — especially the **Intent**, **Design choices**, and the *comments* in the **Style overrides** section. The comments are what let you re-author selector-level rules: even if `.artifact-title` no longer exists, the comment "*active card gets a faint warm tint as a 'you are here' cue*" tells you what to target with whatever selector achieves that intent on the new version.
+   - Running server: `curl http://localhost:32848/canonical/v1/styles.css` (or run `tv status`, read `serverURL`, and fetch `<serverURL>/canonical/v1/styles.css`).
+   - Or, from a checkout: read `specs/ui/foundation/{colors,text,spacing,shadows,prose}.css` for the canonical artifact contract and the current files under `packages/web/src/{elements,views}/` for any browser-chrome selector rules.
+2. **Read the theme's skill** — especially the **Intent**, **Design choices**, and the *comments* in the **Style overrides** section. The comments are what let you re-author selector-level rules: even if `.artifact-title-bar` is absent in the running version, the comment "*selected document's lower title band gets a faint warm tint as an orientation cue*" tells you what current selector should carry that intent.
 3. **Map the original intent onto the new surface.** Token overrides that reference tokens still present transfer directly. Renamed tokens get re-mapped. New semantic tokens added to Television may need to be set to fit the theme's vibe. Selector-level rules get re-expressed against the new structure.
 4. **Update the skill's Style overrides section** with the revised rules (keep the purpose comments updated).
 5. **Re-render**: write the updated CSS to `<storagePath>/themes/<name>/theme.css` and re-copy any new/changed assets from `resources/`.