trykeyline 0.1.0 → 0.1.2

package/plugins/keyline/skills/keyline/glass/color/assets/color-tokens.css

@@ -5,39 +5,15 @@
 
 @import "tailwindcss";
 
-/* Drive the `dark:` variant off data-theme (set by theme.ts), not the OS —
-   a theme toggle has to be able to override the system, and once a user has
-   expressed a preference the OS shouldn't win.
-
-   :where() keeps specificity at zero, so a dark: utility doesn't outrank an
-   unprefixed one purely by virtue of the attribute selector. */
+/* `dark:` keys off data-theme (set by theme.ts), not the OS; :where() keeps
+   specificity at zero. */
 @custom-variant dark (&:where([data-theme="dark"], [data-theme="dark"] *));
 
 @theme {
-  /* ── The solid ramp ─────────────────────────────────────────────────────
-     Each step encodes an INTENT, not a lightness:
-
-       100  default surface for a raised element
-       200  that surface, hovered  ·  inert placeholder fill
-       300  that surface, active/pressed
-       400  BORDER
-       500  border hovered  ·  decorative marks (bullets, dots, rail markers)
-       600  border active
-       700  solid fill
-       800  solid fill hovered
-       900  SECONDARY TEXT
-      1000  PRIMARY TEXT  ·  inverted-element fill
-
-     NOTE 500-800 ARE NOT TEXT COLOURS. A border needs 3:1 against its
-     surface; text needs 4.5:1. On a light theme these mid steps are light
-     greys on white — 500 is 1.66:1, 600 is 2.38:1, 800 is 4.12:1 — so all
-     of them fail as text. Only 900 and 1000 are readable. Dark mode hides
-     this completely, because the same indices sit far lighter against a
-     near-black page. Text tiers below.
-
-     Note 400 is LIGHTER than 300 in this theme. Not a mistake — a border
-     sits beside content and must stay quieter than a pressed surface, which
-     sits under it. Intent beats monotonicity. */
+  /* ── The solid ramp, indexed by intent: 100–300 surface states, 400–600
+     border states, 700–800 solid fill, 900 secondary text, 1000 primary.
+     500–800 are NOT text colours, and 400 is lighter than 300 on purpose:
+     glass/color/intent-ramp.md. */
   --color-gray-100: #f2f2f2;
   --color-gray-200: #ebebeb;
   --color-gray-300: #e6e6e6;
@@ -49,11 +25,7 @@
   --color-gray-900: #4d4d4d;
   --color-gray-1000: #171717;
 
-  /* ── The translucent ramp ───────────────────────────────────────────────
-     Same indices, alpha instead of solid. Use these for ANYTHING LAYERED:
-     borders on glass, dividers, hairlines, overlays. A solid border on a
-     translucent panel doesn't participate in what's behind it and reads as
-     a pasted-on frame. */
+  /* ── The translucent ramp: anything layered (glass/color/guide.md §2). */
   --color-gray-alpha-100: #0000000d;
   --color-gray-alpha-200: #00000015;
   --color-gray-alpha-300: #0000001a;
@@ -61,41 +33,19 @@
   --color-gray-alpha-500: #00000036;
   --color-gray-alpha-600: #0000003d;
 
-  /* ── Surfaces ───────────────────────────────────────────────────────────
-     Held out of the ramp: a page background is categorically different from
-     a component surface. background-100 is also the TEXT colour for anything
-     inverted (a tooltip), which is why it's a token and not a literal white. */
+  /* ── Surfaces, held out of the ramp. background-100 is also the text of
+     anything inverted. */
   --color-background-100: #ffffff;
   --color-background-200: #fafafa;
 
-  /* ── Text tiers ─────────────────────────────────────────────────────────
-     Held apart from the ramp, because a border and a piece of text have
-     different contrast requirements (3:1 vs 4.5:1) and one step can't serve
-     both. Ratios against background-100:
-
-       gray-1000  primary    17.93:1   body copy, headings, active state
-       gray-900   secondary   8.45:1   emphasised, ancestor rows
-       muted                  6.48:1   deks, supporting copy, <em>
-       quiet                  5.49:1   resting icons, state labels, <cite>
-       faint                  4.61:1   dates, read times, meta
-
-     Worst real pairing is muted on gray-100 (a subtle surface) at 5.79:1.
-
-     The ladder is STRICTLY DESCENDING on purpose. Once every tier has to
-     clear 4.5:1 they crowd together and the hierarchy collapses — check the
-     ordering, not just the thresholds, or you pass WCAG and lose the design.
-
-     Icons ride `quiet` rather than getting their own token: they only need
-     3:1, but they usually sit beside a label and two tokens that must stay
-     visually matched is more coupling than it saves. */
+  /* ── Text tiers, apart from the ramp (glass/color/guide.md §4). Against
+     background-100: gray-1000 17.93 · gray-900 8.45 · muted 6.48 · quiet
+     5.49 · faint 4.61. Strictly descending; icons ride `quiet`. */
   --color-muted: #5e5e5e;
   --color-quiet: #696969;
   --color-faint: #757575;
 
-  /* ── The one accent ─────────────────────────────────────────────────────
-     Focus ring only. Links stay monochrome — in a monochrome interface
-     colour IS attention, so spend it on the one thing that must be
-     unmissable: where the keyboard is. */
+  /* ── The one accent: the focus ring only. */
   --color-blue-700: #006bff;
 
   /* Elevated surface for sliding highlights and active pills — white here,
@@ -103,30 +53,18 @@
   --color-highlight: #ffffff;
 }
 
-/* ── Runtime surfaces ─────────────────────────────────────────────────────
-   These are plain custom properties, NOT @theme tokens, because they must be
-   re-declarable per theme AND replaceable by the reduced-transparency
-   fallback at runtime — and because one of them is a gradient, which no
-   colour token system accepts.
-
-   Rule: a value that changes by CONTEXT belongs in :root; a value that's
-   part of the vocabulary belongs in @theme. */
+/* ── Runtime surfaces: plain custom properties, not @theme tokens, because
+   they re-declare per theme and under reduced transparency, and one is a
+   gradient (glass/color/guide.md §6). */
 :root {
   color-scheme: light;
   --glass-nav-bg: rgba(242, 242, 242, 0.72);
   --glass-panel-bg: rgba(243, 243, 243, 0.97);
   --folder-glass-bg: linear-gradient(to bottom, rgba(255, 255, 255, 0.55), rgba(255, 255, 255, 0.34));
 
-  /* ── The one chromatic exception ────────────────────────────────────────
-     Beyond the focus ring, a monochrome system can afford at most one place
-     colour goes — and the justification has to be structural. Here it's a
-     collapsed summary panel: it's an OFFER rather than content ("do you want
-     the three-line version?"), which makes it the one element allowed to
-     announce itself, and means the exception can't spread, because nothing
-     else on the site is an offer.
-
-     Delete this block if you don't have such an element. An exception with a
-     weak justification becomes a palette within two components. */
+  /* ── The one chromatic exception: the collapsed summary panel, an offer
+     rather than content (glass/color/guide.md §3). Delete this block if you
+     don't have such an element. */
   --sv-edge-top: #16276b;      /* deep navy at the top of the 1px stroke */
   --sv-edge-mid: #2f5ac4;
   --sv-edge-bottom: #6d97ea;   /* running to a lighter blue at the bottom */
@@ -135,9 +73,7 @@
   --sv-accent: #2f5ac4;        /* the MARK, and only the mark */
   --sv-sheen-hi: #8fb2f2;
 
-  /* Four shadows, not one. A single centred blur reads as a drop shadow
-     that happens to be blue; weighting it to the two SIDES is what makes it
-     read as light coming off the panel. See the Glass depth guide (`glass/depth/guide.md`). */
+  /* Weighted to the sides so it reads as light (glass/depth/guide.md §6). */
   --sv-glow:
     0 1px 2px rgba(22, 39, 107, 0.05),
     -10px 0 20px -18px rgba(47, 90, 196, 0.38),
@@ -150,15 +86,8 @@
     0 14px 34px -16px rgba(47, 90, 196, 0.6);
 }
 
-/* ── Dark theme ───────────────────────────────────────────────────────────
-   One block re-tints the same token names, so most of the site adapts with
-   no per-component dark: classes at all. Semantics hold: low steps are
-   surfaces, high steps are text, "border" still means 400.
-
-   Not a mechanical inversion. The bottom is compressed (100→400 spans only
-   twenty units) because the eye separates near-black surfaces easily, while
-   the middle jumps forty units at once (400→500) to pull "border" clear of
-   "text". 700 is the one step identical in both themes. */
+/* ── Dark theme: the same names re-tinted, not inverted
+   (glass/color/intent-ramp.md, dark-mode re-tinting). */
 :root[data-theme="dark"] {
   color-scheme: dark;
 
@@ -173,10 +102,7 @@
   --color-gray-900: #c4c4c4;
   --color-gray-1000: #ededed;
 
-  /* The crux of the whole system: the alpha ramp inverts to WHITE-based.
-     A dark-mode border is lighter than its surface, so a black overlay would
-     make it disappear. "A little more contrast than the surface" means black
-     in light mode and white in dark. */
+  /* The alpha ramp inverts to white-based. */
   --color-gray-alpha-100: #ffffff0d;
   --color-gray-alpha-200: #ffffff15;
   --color-gray-alpha-300: #ffffff1f;
@@ -184,43 +110,27 @@
   --color-gray-alpha-500: #ffffff36;
   --color-gray-alpha-600: #ffffff45;
 
-  /* Near-black, not #000: pure black gives shadows nothing to sit on and
-     produces harsh contrast with light text. */
+  /* Near-black, not #000. */
   --color-background-100: #0b0b0b;
   --color-background-200: #161616;
 
-  /* Text tiers, re-picked for the dark surface. Note how little `muted` had
-     to change — it keeps a value that already passed at 7.53:1. The contrast
-     failure this ladder exists to fix was overwhelmingly a LIGHT-theme
-     failure; only `faint` was genuinely broken in dark too (3.97:1).
-     Ratios against background-100: muted 7.53 · quiet 5.48 · faint 4.59. */
+  /* Re-picked for the dark surface: muted 7.53 · quiet 5.48 · faint 4.59. */
   --color-muted: #a0a0a0;
   --color-quiet: #878787;
   --color-faint: #7a7a7a;
 
-  /* Re-picked, not reused. The same blue that clears 4.5:1 on white has far
-     less on near-black — any accent needs a per-theme value. */
+  /* Every accent takes a per-theme value. */
   --color-blue-700: #3b82f6;
 
   --color-highlight: #2c2c2c;
 
   --glass-nav-bg: rgba(26, 26, 26, 0.72);
   --glass-panel-bg: rgba(22, 22, 22, 0.97);
-  /* Grey-based, not white — a white gradient over a dark page reads as fog
-     rather than glass. */
+  /* Grey-based: a white gradient over a dark page reads as fog. */
   --folder-glass-bg: linear-gradient(to bottom, rgba(48, 48, 48, 0.5), rgba(30, 30, 30, 0.34));
 
-  /* The same edge, LIFTED — every stop moved by roughly the same amount.
-     A #16276b top stop is within a few points of a #0b0b0b page, so the
-     stroke would simply go missing down its darker half. The instinct is to
-     lighten only the dark end, and that's the mistake: it pinches the ramp
-     and it stops reading as one gradient. A gradient is a relationship
-     between its stops, so re-picking it for a theme means re-picking all of
-     them — exactly as the accent rule says.
-
-     The fill is TINTED, not darkened. It sits at gray-100's weight so the
-     panel doesn't punch a hole in the page: "raised" means "more contrast
-     against the page", and the direction flips between themes. */
+  /* Every stop lifted by about the same amount, so it stays one gradient;
+     the fill is tinted to gray-100's weight, not darkened. */
   --sv-edge-top: #24407f;
   --sv-edge-mid: #3f6ed0;
   --sv-edge-bottom: #86adf7;
@@ -240,9 +150,8 @@
     0 14px 36px -16px rgba(90, 140, 240, 0.7);
 }
 
-/* Reduced transparency → solid surfaces in both themes. MUST come after both
-   theme blocks: it re-declares the same properties at the same specificity,
-   so source order decides. */
+/* Reduced transparency: the tint half (glass.css drops the filter). MUST
+   come after both theme blocks — same specificity, so source order decides. */
 @media (prefers-reduced-transparency: reduce) {
   :root,
   :root[data-theme="dark"] {
@@ -264,10 +173,7 @@
     color: var(--color-background-100);
   }
 
-  /* :focus-visible, never :focus — a mouse click shouldn't leave a ring.
-     outline-offset puts a gap of page colour between element and ring, so
-     the ring reads as a distinct object rather than a border. Links get more
-     because inline text has ragged edges the ring shouldn't crowd. */
+  /* :focus-visible, never :focus; the offset leaves a gap of page colour. */
   :focus-visible {
     outline: 2px solid var(--color-blue-700);
     outline-offset: 2px;
@@ -278,42 +184,5 @@
   }
 }
 
-/* ─────────────────────────────────────────────────────────────────────────
-   The .glass-* MATERIAL CLASSES that consume the tints above live in
-   glass/depth/assets/glass.css — the blur and saturation values, the
-   @supports guard with an opaque baseline, and the other half of the
-   reduced-transparency fallback (dropping backdrop-filter, which this file's
-   tint swap does not do on its own).
-
-   Both files are needed for working glass. They're split because the tints
-   are colour tokens that re-tint per theme, while the materials are surface
-   craft — different guides own them, and neither should duplicate the other.
-   ───────────────────────────────────────────────────────────────────────── */
-
-/* ─────────────────────────────────────────────────────────────────────────
-   Elevation, for reference — apply in components, not here. A shadow that
-   changes STRUCTURE between themes can't be a single token, so it needs a
-   dark: variant. Extract it once to a shared constant and import it.
-
-   Four layers, one light source:
-     inset 1px white   top-edge catch light — does more for "floating" than
-                       any of the shadows
-     1px/1px @ 2%      contact shadow: resting on something, not pasted over
-     8/16 @ 4%         near ambient
-     24/32 @ 6%        far ambient — two layers, because one large shadow
-                       reads as fog while two fall off like real penumbra
-
-   Negative spread (-4px, -8px) contracts before blurring, keeping the shadow
-   tucked under the element instead of haloing past its edges. This is the
-   detail most hand-written shadows miss.
-
-   Opacities are 2–6%. Elevation should be felt, not seen.
-
-   const SHADOW =
-     "shadow-[inset_0_1px_0_rgba(255,255,255,0.6),0_1px_1px_rgba(0,0,0,0.02),0_8px_16px_-4px_rgba(0,0,0,0.04),0_24px_32px_-8px_rgba(0,0,0,0.06)] " +
-     "dark:shadow-[inset_0_1px_0_rgba(255,255,255,0.10),0_1px_1px_rgba(0,0,0,0.3),0_8px_16px_-4px_rgba(0,0,0,0.5),0_24px_32px_-8px_rgba(0,0,0,0.6)]";
-
-   Dark inverts BOTH ways: shadows ~10x stronger (4% black on #0b0b0b is
-   mathematically invisible), inset highlight ~6x weaker (0.6 white on a dark
-   surface reads as a glowing edge, not a catch light).
-   ───────────────────────────────────────────────────────────────────────── */
+/* The .glass-* material classes and .dock-shadow live in
+   glass/depth/assets/glass.css; both files are needed for working glass. */

package/plugins/keyline/skills/keyline/glass/color/assets/theme.ts

@@ -1,33 +1,17 @@
 /**
  * Theme persistence. Two explicit modes, Light or Dark; Light is the default.
  * The choice sticks in localStorage and is reflected on <html> via data-theme,
- * which the dark token overrides key off (see color-tokens.css).
- *
- * Three separate functions because they have different callers:
- * getThemeChoice for initial React state, applyTheme for the DOM write,
- * setThemeChoice for the user action. Keeping them apart is what lets the
- * toggle animate while the initial paint doesn't.
- *
- * ─────────────────────────────────────────────────────────────────────────
- * PAIR THIS WITH THE HEAD SCRIPT AT THE BOTTOM OF THIS FILE. Without it,
- * every load flashes white before React mounts — the single most noticeable
- * bug a themed site can have.
- * ─────────────────────────────────────────────────────────────────────────
+ * which the dark token overrides key off (color-tokens.css). Three functions
+ * for three callers: initial React state, the DOM write, the user action.
+ * Pair it with the head script at the bottom of this file.
  */
 
 export type ThemeChoice = "light" | "dark";
 
 const KEY = "theme";
 
-/**
- * The comparison is `=== "dark"`, not a parse: anything unrecognised — a
- * stale value, a corrupted entry, a value from an older version of the site —
- * falls through to light.
- *
- * Every localStorage access is wrapped. It throws in Safari private browsing
- * and under some cookie policies. A preference that doesn't persist is a
- * minor annoyance; an uncaught throw is a broken page.
- */
+/** `=== "dark"`, not a parse: anything unrecognised falls through to light.
+    Every localStorage access is wrapped; it throws in some private modes. */
 export function getThemeChoice(): ThemeChoice {
   try {
     if (localStorage.getItem(KEY) === "dark") return "dark";
@@ -48,12 +32,8 @@ export function setThemeChoice(choice: ThemeChoice): void {
     /* preference just won't persist */
   }
 
-  /* The crossfade class is added for one interaction and then removed.
-     Left in the stylesheet permanently it would apply to every hover state
-     on the site — every link, every icon, every row becomes a 400ms colour
-     fade and the whole interface goes sluggish.
-
-     440ms = the 400ms transition plus a 40ms margin so nothing is cut off. */
+  /* Crossfade on explicit toggles only: the class (motion-tokens.css) is
+     added, then removed after 440ms — the 400ms fade plus a 40ms margin. */
   const root = document.documentElement;
   root.classList.add("theme-transition");
   applyTheme(choice);
@@ -73,47 +53,7 @@ export function setThemeChoice(choice: ThemeChoice): void {
        })();
      </script>
 
-   All four properties are load-bearing:
-     · INLINE      — an external file is a network round trip, and the page
-                     paints during it
-     · BLOCKING    — no async, no defer, no type="module" (which defers
-                     implicitly); it must run before the first paint
-     · BEFORE CSS  — so the attribute is set when the stylesheet applies
-     · try/catch   — an uncaught throw here blocks all subsequent scripts
-
-   For SSR, render the attribute server-side from a cookie instead —
-   localStorage isn't readable on the server, so a cookie is the only way to
-   get the value into the initial HTML.
-   ───────────────────────────────────────────────────────────────────────── */
-
-/* ─────────────────────────────────────────────────────────────────────────
-   Adding a third "system" state, if you want it.
-
-   The reference implementation ships two explicit modes because a theme
-   control should be predictable — "System" means the theme changes when the
-   OS crosses a sunset threshold, which is surprising if you picked it from a
-   site's own menu. But respecting the OS on a first visit is the more
-   considerate default. Both positions are defensible.
-
-   If you go to three, you owe the user two extra things:
-
-     export type ThemeChoice = "light" | "dark" | "system";
-
-     function resolve(choice: ThemeChoice): "light" | "dark" {
-       if (choice !== "system") return choice;
-       return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
-     }
-
-   1. The head script must resolve "system" too, so it needs the matchMedia
-      call inlined as well.
-
-   2. A live listener, so the page follows the OS WHILE OPEN:
-
-        window.matchMedia("(prefers-color-scheme: dark)").addEventListener(
-          "change",
-          () => { if (getThemeChoice() === "system") applyTheme(resolve("system")); }
-        );
-
-      Skipping this is the common bug: the theme follows the OS on load and
-      then silently stops, which is worse than not offering the option.
+   Inline, blocking, before the stylesheet, in try/catch; for SSR, render
+   the attribute from a cookie. Why each, and what a third "system" state
+   would add: domains/color/theming-mechanics.md.
    ───────────────────────────────────────────────────────────────────────── */

package/plugins/keyline/skills/keyline/glass/color/guide.md

@@ -109,7 +109,7 @@ A `#16276b` stop on a `#0b0b0b` page loses the stroke's darker half, so the whol
 
 ### Status colour is not an exception
 
-Nothing on the site reports state, so Glass ships no status pair; if you add one, it follows domain law 6 and `domains/color/status-and-exceptions.md` (`glass/color/intent-ramp.md` has Glass's notes). Every destructive or session-ending action (delete, clear, sign out) shares one red treatment, wherever it sits.
+Nothing on the site reports state, so Glass ships no status pair; if you add one, it follows domain law 6 and `domains/color/status-and-exceptions.md`. Every destructive or session-ending action (delete, clear, sign out) shares one red treatment, wherever it sits.
 
 ## 4. Text is a five-tier ladder — and it is *not* the grey ramp
 
@@ -156,20 +156,7 @@ Utilities read the variables, so most of the site needs **no per-component `dark
 
 ### No flash of wrong theme
 
-A blocking inline script in `<head>`, before any paint (domain law 9):
-
-```html
-<script>
-  (function () {
-    try {
-      document.documentElement.dataset.theme =
-        localStorage.getItem("theme") === "dark" ? "dark" : "light";
-    } catch (e) {}
-  })();
-</script>
-```
-
-→ Persistence, toggle crossfade, light/dark/system trade-offs: `glass/color/theming.md`
+A blocking `<head>` script sets the attribute before paint (domain law 9): `glass/color/assets/theme.ts`. → Two states, Light by default, and the toggle's 400ms plain-`ease` crossfade: `glass/color/theming.md`
 
 ## 6. Some colours are runtime, not build-time
 
@@ -183,24 +170,10 @@ The ramps and surfaces are vocabulary, in `@theme`; the **glass tints** are plai
 }
 ```
 
-The `prefers-reduced-transparency` fallback swaps each for a solid tint at runtime, and one isn't a colour at all. Gradients put the `--sv-*` family in `:root` too (two multi-stop gradients and a four-layer `box-shadow`).
+Runtime because the reduced-transparency fallback swaps them, after both theme blocks (`glass/depth/guide.md` §8), and one isn't a colour at all; the `--sv-*` gradients sit in `:root` too.
 
 The nav tint is `#f2f2f2` (`gray-100`), not white: grey chrome reads as an object, not a hole in the page. Dark tints are *lighter* than the dark page (domain law 8).
 
-The reduced-transparency swap comes **after** both theme blocks and names both selectors (domain law 10):
-
-```css
-@media (prefers-reduced-transparency: reduce) {
-  :root, :root[data-theme="dark"] {
-    --glass-nav-bg: var(--color-gray-100);
-    --glass-panel-bg: var(--color-gray-100);
-    --folder-glass-bg: var(--color-background-100);
-  }
-}
-```
-
-Dropping the `backdrop-filter` is the other half, and both are required. Blur, saturation, elevation shadows and text contrast over glass belong to `glass/depth/guide.md`.
-
 ## Assets
 
 - `glass/color/assets/color-tokens.css` — ramps, themes, glass tints and their fallback swap, focus ring; pairs with `glass/depth/assets/glass.css` (material classes).

package/plugins/keyline/skills/keyline/glass/color/intent-ramp.md

@@ -58,20 +58,7 @@ Held out of the ramp because a page background is categorically different from a
 
 ## Dark-mode re-tinting
 
-```css
-:root[data-theme="dark"] {
-  --color-gray-100: #1a1a1a;   /* 100–400: dark surfaces, rising slowly */
-  --color-gray-200: #212121;
-  --color-gray-300: #282828;
-  --color-gray-400: #2e2e2e;
-  --color-gray-500: #707070;   /* 500–800: the mid greys jump */
-  --color-gray-600: #7d7d7d;
-  --color-gray-700: #8f8f8f;
-  --color-gray-800: #a0a0a0;
-  --color-gray-900: #c4c4c4;   /* 900–1000: light text */
-  --color-gray-1000: #ededed;
-}
-```
+The values are the dark block of `glass/color/assets/color-tokens.css`.
 
 **It's not an inversion** (domain law 8). Inverting the light ramp would put 100 at `#0d0d0d` and 1000 at `#e8e8e8`, evenly spaced. The real dark ramp is *compressed at the bottom* (100→400 spans only `#1a1a1a`→`#2e2e2e`, twenty units) and *expanded in the middle* (400→500 jumps forty units), because dark surfaces must stay distinguishable at very low lightness, where the eye is more sensitive to small differences, while mid-greys need a big jump to separate "border" from "text."
 
@@ -98,18 +85,7 @@ Against the near-black page the same indices pass — 800 is 7.53:1, 700 is 6.09
 
 ### The fix: text tiers as their own tokens
 
-```css
-:root {
-  --color-muted: #5e5e5e;   /* 6.48:1 — deks, supporting copy, <em> */
-  --color-quiet: #696969;   /* 5.49:1 — resting icons, state labels, <cite> */
-  --color-faint: #757575;   /* 4.61:1 — dates, read times, meta */
-}
-:root[data-theme="dark"] {
-  --color-muted: #a0a0a0;   /* 7.53:1 */
-  --color-quiet: #878787;   /* 5.48:1 */
-  --color-faint: #7a7a7a;   /* 4.59:1 */
-}
-```
+`muted`, `quiet` and `faint`, per theme, are in `glass/color/assets/color-tokens.css`; their jobs are §4 of `glass/color/guide.md`.
 
 **Every tier clears 4.5:1 in both themes**, including the worst real pairing: muted on `gray-100`, a subtle surface, at 5.79:1.
 
@@ -126,11 +102,3 @@ Against the near-black page the same indices pass — 800 is 7.53:1, 700 is 6.09
 **A border step as text.** The one this guide got wrong for a whole revision (above).
 
 **"Something between 500 and 600"**, and **auditing contrast in dark mode only**: domain laws 1 and 3. Here the worst surface is a subtle `gray-100`, not `background-100`.
-
-## Adding a semantic colour
-
-The reference implementation has none, because nothing on the site reports state. Check that before you add them. If you do, they get their own pairs outside the grey ramp, kept out of the focus ring's territory, and follow domain law 6 and `domains/color/status-and-exceptions.md`: shape carries the state, red means loss and never a live state, destructive actions take a red ground (solid danger with `background-100` text when highlighted), and small marks clear 3:1 on every ground in each theme.
-
-## Spending your one chromatic exception
-
-Glass spends it once, on the collapsed summary panel: an offer, not content (domain law 7). Its containment rules — only the mark takes the accent; every stop re-picked for dark — are in §3 of `glass/color/guide.md`.

package/plugins/keyline/skills/keyline/glass/color/theming.md

@@ -10,74 +10,13 @@ Glass's theme switch, persistence and crossfade, with the values it ships. The m
 
 Tailwind v4 drives `dark:` off the OS media query by default; Glass has a toggle, so `data-theme` on `<html>` is the mechanism (domain law 9). For a permanently-light region inside a dark page, re-declare the custom properties on its container rather than nesting the attribute (`domains/color/theming-mechanics.md`, **Theme islands**).
 
-## No flash of wrong theme
-
-```html
-<head>
-  <!-- Before the stylesheet. Blocking on purpose. -->
-  <script>
-    (function () {
-      try {
-        document.documentElement.dataset.theme =
-          localStorage.getItem("theme") === "dark" ? "dark" : "light";
-      } catch (e) {}
-    })();
-  </script>
-  <link rel="stylesheet" href="…" />
-</head>
-```
-
-Inline, blocking, before the stylesheet, in `try/catch`; it duplicates a few lines of the theme module, with a comment in each place pointing at the other (`domains/color/theming-mechanics.md`, **No flash of wrong theme**).
-
-## Persistence and the crossfade
-
-```ts
-export type ThemeChoice = "light" | "dark";
-
-const KEY = "theme";
-
-export function getThemeChoice(): ThemeChoice {
-  try {
-    if (localStorage.getItem(KEY) === "dark") return "dark";
-  } catch { /* localStorage unavailable */ }
-  return "light";
-}
-
-export function applyTheme(choice: ThemeChoice): void {
-  document.documentElement.dataset.theme = choice;
-}
-
-export function setThemeChoice(choice: ThemeChoice): void {
-  try {
-    localStorage.setItem(KEY, choice);
-  } catch { /* preference just won't persist */ }
+## No flash of wrong theme, persistence and the crossfade
 
-  // Crossfade only on explicit toggles.
-  const root = document.documentElement;
-  root.classList.add("theme-transition");
-  applyTheme(choice);
-  window.setTimeout(() => root.classList.remove("theme-transition"), 440);
-}
-```
-
-Three functions for three callers — `getThemeChoice` for initial React state, `applyTheme` for the DOM write, `setThemeChoice` for the user action (`domains/color/theming-mechanics.md`, **Persistence**). The comparison is `=== "dark"`, so anything unrecognised falls through to light.
-
-### The 440ms class
-
-```css
-@media (prefers-reduced-motion: no-preference) {
-  :root.theme-transition,
-  :root.theme-transition *,
-  :root.theme-transition *::before,
-  :root.theme-transition *::after {
-    transition: background-color 400ms ease, color 400ms ease, border-color 400ms ease,
-      fill 400ms ease, stroke 400ms ease, box-shadow 400ms ease !important;
-  }
-}
-```
+The code lives in `glass/color/assets/theme.ts` — the three functions and, at the bottom, the inline head script — and the 440ms `.theme-transition` rule in `glass/motion/assets/motion-tokens.css`. The head script duplicates a few lines of the theme module, with a comment in each place pointing at the other. The mechanism, the head script's four requirements, the three callers and why the crossfade class is temporary and `!important`: `domains/color/theming-mechanics.md`.
 
-Why it's temporary, `!important`, inside `no-preference` and lists the pseudo-elements: `domains/color/theming-mechanics.md`, **The crossfade on toggle**. Glass's values:
+Glass's values:
 
+- **The comparison is `=== "dark"`**, so anything unrecognised falls through to light.
 - **440ms**: 400ms plus a 40ms margin so nothing is cut off. For those 440ms it has to beat every component's own `transition-colors duration-150`.
 - **400ms**: the longest duration in the system, for its largest change — every surface, text colour, border, icon fill and shadow at once.
 - **Plain `ease`, not the house curve.** The house easing overshoots, and on a colour that sends the background past its target and back — a wobble in the light.
@@ -99,13 +38,7 @@ The reference implementation ships **two** explicit modes, Light and Dark, with
 
 Most components need no theme branching; the test for when one does is in `domains/color/theming-mechanics.md`. Glass's cases:
 
-**Multi-layer shadows.** A shadow whose *structure* changes between themes (the inset highlight weakening while the ambient shadows strengthen 10×) can't live in one colour token. Extract it to a shared constant:
-
-```tsx
-const SHADOW =
-  "shadow-[inset_0_1px_0_rgba(255,255,255,0.6),0_1px_1px_rgba(0,0,0,0.02),…] " +
-  "dark:shadow-[inset_0_1px_0_rgba(255,255,255,0.10),0_1px_1px_rgba(0,0,0,0.3),…]";
-```
+**Multi-layer shadows.** A shadow whose *structure* changes between themes (the inset highlight weakening while the ambient shadows strengthen 10×) can't live in one colour token, but Glass keeps it out of `dark:` too: it's one class, `.dock-shadow`, with its `:root[data-theme="dark"]` twin beside it (`glass/depth/depth-cues.md`, §2), not a JS constant.
 
 **Ring/border colours as alpha of a specific hue.** `ring-black/[0.06] dark:ring-white/[0.08]` encodes what the alpha ramp does, where the utility won't take a token. Prefer `gray-alpha-*` where you can; use the pair where you can't.