trykeyline 0.0.0-stage → 0.1.1

package/plugins/keyline/skills/keyline/domains/type/prose-and-emphasis.md

@@ -0,0 +1,125 @@
+# Prose and emphasis
+
+The reading half: blocks sharing the body size and what separates them, emphasis per preset, and imported prose. Spacing values between blocks belong to the layout guide; this file names only the ratios that are type signals.
+
+## The container sets the register
+
+One wrapper carries the reading size, leading and tier; every block inside overrides only what differs.
+
+```css
+.prose {
+  font-size: var(<type.body size>);
+  line-height: var(<type.body leading>);
+  color: var(<text.primary>);
+  max-inline-size: var(<measure.reading>);
+}
+```
+
+A paragraph setting its own size inside `.prose` is a finding: it has opted out of the register, and the next restyle will miss it.
+
+## Reading blocks, and the axis each owns
+
+Each block at body size needs a signal the others don't use (law 4). A typical set:
+
+| Block | Role | Its signal | What it must not do |
+|---|---|---|---|
+| Body | `type.body` | none — the baseline | set its own size |
+| Lead | `type.lead` | more open leading, more space below | be larger than the heading above it |
+| Keyline | project role under `type.body` | `weight.strong`, symmetric space | appear twice in one section |
+| Dek | `type.supporting` | `text.secondary`, tighter leading | read as the first paragraph |
+| Pull quote | project role between `type.body` and `type.heading` | a solid bar and a voice — the reading family's italic or the display weight | rise above `type.heading` (law 3), or stay at body size, where it is a blockquote |
+| Note | project role under `type.meta` | one size down, `text.tertiary`, a lighter rule | share the quote's rule weight |
+| Caption | `type.meta` | one size down, `text.tertiary` | sit at body size, competing with the next paragraph |
+
+**Dek and lead are the tightest pairing** — often adjacent, told apart only by tier and leading. Check them first when a page looks undifferentiated.
+
+**Two indented rules on one page must be unmistakable.** If quote and note both carry a left rule, the rules differ in weight (a heavy bar against a hairline) *and* their type in size and tier. The Glass quote's bar is three times the note's rule; the note is a step smaller and two tiers quieter.
+
+**Heading space is asymmetric, and the ratio is the type signal**: about 3:1 above to below, so a heading belongs to what it introduces; equal space floats it between sections. The keyline is the deliberate exception, symmetric because it belongs to neither neighbour.
+
+## Two block types worth having
+
+Both came from one Glass diagnosis: a hundred-odd paragraphs and nothing else. Not too much content — **one texture**.
+
+**The keyline — the one sentence a section is for.** Promote a sentence out of its paragraph and delete it there; that discipline is the point, so a section that gains a keyline gets shorter. One per section, never two.
+
+**The note — an aside outside the argument**: a caveat, a scope limit, provenance. With somewhere to go, qualifications leave the main text.
+
+Enforce the discipline at build time: fail on a blank keyline or note, two keylines in one section, or a keyline grown back to paragraph length.
+
+## Quotes
+
+A pull quote may be set up to `type.heading`'s size, never above it (law 3), separated by the bar and a voice — the reading family's italic or the display weight. A quote at body size is a blockquote, not a pull quote: there the bar is the whole signal, so it has to be a real one:
+
+```css
+.quote { display: flex; gap: var(<space.tight>); }
+.quote::before {
+  content: "";
+  flex: none;
+  inline-size: 3px;           /* rule.emphasis */
+  border-radius: 999px;
+  background: var(<mark>);
+}
+.quote cite { display: block; font-style: normal; font-size: var(<type.meta size>); color: var(<text.tertiary>); }
+```
+
+A flex child, not `border-inline-start`: a border can't be rounded alone, and a squared bar reads as a table rule. With no vertical margin, flex's stretch runs it the full height, citation included. Wherever italic is off, `cite` needs `font-style: normal`: `<cite>` and `<blockquote>` carry user-agent italics a global `em` rule doesn't reach.
+
+## Lists
+
+Markers sit a tier below the text: `li::marker { color: var(<mark>) }`; at text colour, bullets pull the eye down the left edge. Ordered markers take `font-variant-numeric: tabular-nums` so item 10 doesn't shift its text. Items sit closer to each other than to what follows the list.
+
+## Emphasis, per preset
+
+Keep the semantic tags — assistive technology announces them — and map their look onto an existing axis.
+
+| | editorial | product | expressive |
+|---|---|---|---|
+| `<strong>` | `weight.strong` + `text.primary` | `weight.strong` | `weight.strong` |
+| `<em>` | true italic, if the family ships one; else `text.secondary`, no slant | `text.secondary`, no slant | true italic if the family ships one |
+| `<cite>`, titles of works | true italic, or the `<em>` mapping | the `<em>` mapping | true italic |
+| `<b>`, `<i>` | same as `strong`, `em` | same | same |
+
+`<em>` on a quieter tier gives two-directional emphasis — strong advances, em recedes — that a bold-only system can't, and suits interfaces without a usable italic. Where the family has a real text italic, use it: editorial without italic loses the convention readers rely on for titles and terms.
+
+Three rules hold whatever the mapping:
+
+```css
+html { font-synthesis: none; }       /* a missing style is a gap you see, not a smear you ship */
+strong, b { font-weight: var(<weight.strong>); }   /* not the UA's 700 */
+```
+
+- **Never heavier than a heading.** `<strong>` at 700 under a 500 heading outranks it (law 3, inside a line).
+- **Short.** Longer than a few words, it wants to be its own block (law 9).
+- **Weight only on states that don't follow the pointer.** Emphasis that changes on hover shifts the line.
+
+## Prose you can't put classes on
+
+Markdown, a CMS rich-text field, a README: a string with nothing to hang a class on. Style by element inside one scoped class, each element mapped onto an existing role:
+
+```css
+.prose-imported { font-size: var(<type.body size>); line-height: var(<type.body leading>); }
+.prose-imported > :first-child { margin-block-start: 0; }
+.prose-imported h1,
+.prose-imported h2 { font-size: var(<type.heading size>); line-height: var(<type.heading leading>);
+                     letter-spacing: var(<type.heading tracking>); font-weight: var(<weight.strong>); }
+.prose-imported h3 { font-size: var(<type.subheading size>); font-weight: var(<weight.strong>); }
+.prose-imported h4 { font-size: var(<type.meta size>); font-weight: var(<weight.strong>);
+                     color: var(<text.secondary>); }
+.prose-imported code { font-family: var(<family.mono>); font-size: 0.875em; }
+.prose-imported pre,
+.prose-imported .table-scroll { overflow-x: auto; }
+.prose-imported table { font-size: var(<type.meta size>); font-variant-numeric: tabular-nums; }
+.prose-imported li::marker { color: var(<mark>); font-variant-numeric: tabular-nums; }
+```
+
+What this must get right that authored prose doesn't (add a role only where the document needs something your pages don't):
+
+- **A document `h1` is not the page's title.** Map it to `type.heading`, or the imported text outranks its page.
+- **The first child's top margin goes**, or an opening heading pushes its space above nothing.
+- **Three heading levels, not two.** Documents nest deeper than designed pages: `h3` takes `type.subheading`, and `h4` a real role, not a browser default.
+- **Code blocks and tables scroll inside their own box**, being Markdown's two unbounded things. Wrap each `<table>` in a scrolling element at render time; the page never scrolls sideways.
+- **Your own markers.** A UA disc at body size is usually the heaviest thing on the page.
+- **Only mapped elements.** Unmapped ones — `<dl>`, `<kbd>`, `<sup>` — fall through to the browser. List what the source can emit and map each, or strip it at render.
+
+**Imported prose is a guest in the type system, not a second one.** A role added for it — only where the document needs something the pages don't — is a project role with a `DESIGN.md` row like any other.

package/plugins/keyline/skills/keyline/domains/type/type-audit.md

@@ -0,0 +1,87 @@
+# Type audit and sweeps
+
+The type guide's *Auditing existing code* and the detector find values in source. This file checks what renders, and sweeps a product after a type decision so no instance is left on the old value.
+
+## Why source isn't enough
+
+The same class renders differently through inheritance, a component's own default and a variant prop, and a merge utility can drop a class without a trace. A raw `text-sm` doesn't say which role it was meant to be, so grep can count it but not judge it. Partial updates — the list rows on the new weight, the board cards still on the old — are the commonest type bug, and only the rendered page shows them.
+
+## The rendered inventory
+
+Every route has to be reachable: where pages need a backend, run the real app on mock data. Then, per route, list every distinct text style and how often it appears:
+
+```js
+const seen = new Map();
+for (const el of document.querySelectorAll("body *")) {
+  const own = [...el.childNodes].some((n) => n.nodeType === 3 && n.textContent.trim());
+  if (!own || !el.getClientRects().length) continue;
+  const s = getComputedStyle(el);
+  const key = [s.fontSize, s.lineHeight, s.fontWeight, s.letterSpacing, s.textTransform].join(" · ");
+  const hit = seen.get(key) ?? { count: 0, sample: el.textContent.trim().slice(0, 40) };
+  hit.count++; seen.set(key, hit);
+}
+console.table([...seen].map(([style, v]) => ({ style, ...v })).sort((a, b) => b.count - a.count));
+```
+
+Read it against the `## Type` table:
+
+- **A style with no row** is a stray or an unnamed role; say which.
+- **A style used once or twice** is usually a component that missed the last change.
+- **Two styles for one element across routes** — a header title at 13/500 here and 14/600 there — is law 2, by path.
+- **A role row in two weights in one set** — some card titles lifted, some not — is a partial update.
+
+## Icons beside text
+
+```js
+for (const svg of document.querySelectorAll("svg")) {
+  const host = svg.parentElement; if (!host?.textContent.trim()) continue;
+  const text = parseFloat(getComputedStyle(host).fontSize), icon = svg.getBoundingClientRect().height;
+  if (icon / text > 1.15 || icon / text < 0.9) console.log(Math.round(icon), "px icon beside", text, "px text", host);
+}
+```
+
+Then compare stroke widths across siblings in one strip: two buttons whose icons differ in size or stroke are a finding, fixed toward the better one.
+
+## Inputs on touch
+
+At a phone width, any `input`, `textarea` or `select` whose computed `font-size` is under 16px makes iOS Safari zoom on focus. Check one form per template.
+
+## Migrating raw sizes to roles
+
+Migrate by what the element is doing, not by its current value: two `text-sm` may be two roles — a nav row is `type.ui` and should have been 13, a description is `type.body`. Against the product ladder in `ladders.md`:
+
+| Raw value | Usually |
+|---|---|
+| `text-xs`, 12px | `type.label` or `type.meta`, told apart by tier |
+| `text-[13px]` | `type.ui`, or `type.data` with tabular figures |
+| `text-sm`, 14px | `type.body`, `type.subheading`, or a `type.ui` that drifted up |
+| `text-base`, 16px | `type.heading`, or an input on touch |
+
+Every instance moved to a role token is one less to find next time; a sweep that leaves raw values behind has to be repeated by hand.
+
+## The `tailwind-merge` trap
+
+`tailwind-merge` resolves conflicts by class group, and `text-*` is shared by size and colour. A name it doesn't know as a size — `text-label` — it files as a colour, so `cn("text-label", "text-muted-foreground")` keeps only the last and the size vanishes, with no error and no warning. Weights have the same trap: `font-strong` is filed as a family and loses to `font-sans`. Register the role names:
+
+```ts
+import { extendTailwindMerge } from "tailwind-merge";
+
+export const twMerge = extendTailwindMerge({
+  extend: {
+    classGroups: {
+      "font-size": [{ text: ["title", "heading", "body", "ui", "label", "meta", "code"] }],
+      "font-weight": [{ font: ["regular", "strong"] }],
+    },
+  },
+});
+```
+
+Use the project's names, and keep the list beside the theme tokens so a new role is registered in the same edit. To check, pass a role size and a text colour through `cn()` in one component and read the computed `font-size`.
+
+## The sweep
+
+The sweep is `domains/patterns/iteration.md`'s. For a type role, two steps of its own:
+
+- **Grep for the old value** in the role's raw forms (`font-semibold`, `text-[14px]`, `font-weight: 600`) and decide each hit; raw sizes are where a partial update hides.
+- **Check the generated strings** for case while you're there (patterns law 1): field names, column headers, tool labels, dialog titles and toasts that arrive in Title Case from a schema or a config.
+  `rg -n "(label|title|header|name):\s*['\"][A-Z][a-z]+ [A-Z][a-z]+" src`

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

@@ -0,0 +1,299 @@
+/* ─────────────────────────────────────────────────────────────────────────
+   Colour and theming — the complete drop-in
+   Tailwind v4. Both ramps, both themes, glass tints, focus ring.
+   ───────────────────────────────────────────────────────────────────────── */
+
+@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. */
+@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. */
+  --color-gray-100: #f2f2f2;
+  --color-gray-200: #ebebeb;
+  --color-gray-300: #e6e6e6;
+  --color-gray-400: #eaeaea;
+  --color-gray-500: #c9c9c9;
+  --color-gray-600: #a8a8a8;
+  --color-gray-700: #8f8f8f;
+  --color-gray-800: #7d7d7d;
+  --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. */
+  --color-gray-alpha-100: #0000000d;
+  --color-gray-alpha-200: #00000015;
+  --color-gray-alpha-300: #0000001a;
+  --color-gray-alpha-400: #00000014;
+  --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. */
+  --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. */
+  --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. */
+  --color-blue-700: #006bff;
+
+  /* Elevated surface for sliding highlights and active pills — white here,
+     a raised grey in dark (overridden below). */
+  --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. */
+: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. */
+  --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 */
+  --sv-fill-top: #f4f6fc;
+  --sv-fill-bottom: #eef2fa;
+  --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`). */
+  --sv-glow:
+    0 1px 2px rgba(22, 39, 107, 0.05),
+    -10px 0 20px -18px rgba(47, 90, 196, 0.38),
+    10px 0 20px -18px rgba(47, 90, 196, 0.38),
+    0 10px 24px -16px rgba(47, 90, 196, 0.3);
+  --sv-glow-lift:
+    0 1px 2px rgba(22, 39, 107, 0.08),
+    -14px 0 28px -18px rgba(47, 90, 196, 0.75),
+    14px 0 28px -18px rgba(47, 90, 196, 0.75),
+    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. */
+:root[data-theme="dark"] {
+  color-scheme: dark;
+
+  --color-gray-100: #1a1a1a;
+  --color-gray-200: #212121;
+  --color-gray-300: #282828;
+  --color-gray-400: #2e2e2e;
+  --color-gray-500: #707070;
+  --color-gray-600: #7d7d7d;
+  --color-gray-700: #8f8f8f;
+  --color-gray-800: #a0a0a0;
+  --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. */
+  --color-gray-alpha-100: #ffffff0d;
+  --color-gray-alpha-200: #ffffff15;
+  --color-gray-alpha-300: #ffffff1f;
+  --color-gray-alpha-400: #ffffff17;
+  --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. */
+  --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. */
+  --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. */
+  --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. */
+  --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. */
+  --sv-edge-top: #24407f;
+  --sv-edge-mid: #3f6ed0;
+  --sv-edge-bottom: #86adf7;
+  --sv-fill-top: #171d2a;
+  --sv-fill-bottom: #1b2230;
+  --sv-accent: #86adf7;
+  --sv-sheen-hi: #dbe8ff;
+  --sv-glow:
+    0 1px 2px rgba(0, 0, 0, 0.5),
+    -10px 0 22px -18px rgba(90, 140, 240, 0.45),
+    10px 0 22px -18px rgba(90, 140, 240, 0.45),
+    0 10px 26px -16px rgba(63, 110, 208, 0.35);
+  --sv-glow-lift:
+    0 1px 2px rgba(0, 0, 0, 0.55),
+    -14px 0 30px -18px rgba(120, 165, 250, 0.9),
+    14px 0 30px -18px rgba(120, 165, 250, 0.9),
+    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. */
+@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);
+  }
+}
+
+@layer base {
+  body {
+    background-color: var(--color-background-100);
+    color: var(--color-gray-1000);
+  }
+
+  /* Inverted selection — the primary text colour becomes the surface. */
+  ::selection {
+    background: var(--color-gray-1000);
+    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 {
+    outline: 2px solid var(--color-blue-700);
+    outline-offset: 2px;
+    border-radius: 2px;
+  }
+  a:focus-visible {
+    outline-offset: 3px;
+  }
+}
+
+/* ─────────────────────────────────────────────────────────────────────────
+   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 is not here. A shadow that changes STRUCTURE between themes can't
+   be a single token, so it lives in one class with its dark twin beside it:
+   .dock-shadow, at the foot of glass/depth/assets/glass.css. Not a JS
+   constant — the reference implementation started with one and moved to the
+   class (glass/depth/depth-cues.md, §2).
+   ───────────────────────────────────────────────────────────────────────── */

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

@@ -0,0 +1,119 @@
+/**
+ * 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.
+ * ─────────────────────────────────────────────────────────────────────────
+ */
+
+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.
+ */
+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 */
+  }
+
+  /* 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. */
+  const root = document.documentElement;
+  root.classList.add("theme-transition");
+  applyTheme(choice);
+  window.setTimeout(() => root.classList.remove("theme-transition"), 440);
+}
+
+/* ─────────────────────────────────────────────────────────────────────────
+   The no-flash head script. Copy this into index.html, inline, in <head>,
+   BEFORE the stylesheet. It duplicates the read above on purpose.
+
+     <script>
+       (function () {
+         try {
+           document.documentElement.dataset.theme =
+             localStorage.getItem("theme") === "dark" ? "dark" : "light";
+         } catch (e) {}
+       })();
+     </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.
+   ───────────────────────────────────────────────────────────────────────── */