trykeyline 0.0.0-stage → 0.1.0

package/plugins/keyline/skills/keyline/domains/color/status-and-exceptions.md

@@ -0,0 +1,174 @@
+# Status colours and chromatic exceptions
+
+A status colour says *"what state is this in?"* from a small, fixed vocabulary; a hue family says what a thing is, where it lives or who; an exception asks *"may this element announce itself?"* and has to earn it. Each colour has exactly one of those jobs, written down. Mixing them grows the palette: a success green ends up on a "new" badge because it was there.
+
+## Does the project need a status palette?
+
+`product` requires one: a working reader meets errors, warnings and confirmations daily, each to be known at a glance. Elsewhere, only if something reports state — a form, a subscription flow, a build status, a changelog's breaking-change marker; four unused pairs are four tokens nobody maintains.
+
+## The pair, and what each half must pass
+
+Each status role is a **foreground** and a **background tint**, both re-picked per theme.
+
+| Half | Job | Must clear |
+|---|---|---|
+| Foreground | The icon, the message's lead word, a border on a field in error | 4.5:1 on `surface.page`, on its own tint, and on any surface a status row can sit on (`surface.hover` in a table) |
+| Background tint | The banner, the toast, the row, the field's fill | Reads as a surface, not a highlighter — about the `surface.hover` ratio against the page, with a little chroma |
+
+Banner body text stays in `text.primary` and `text.secondary`; only the icon and lead word take the foreground. Re-measure the lowest tier used inside on the tint.
+
+A **solid** fill — a destructive button — can often reuse the foreground: in light, a foreground at 4.5:1 on white gives white text 4.5:1 on it; in dark it takes dark `text.on-accent`-style text. Named separately: `status.danger.solid`.
+
+In `DESIGN.md`: `status.danger.fg` and `status.danger.bg`, one row each, per theme.
+
+### Destructive actions take red ground, not red decoration
+
+In a menu, a destructive item is a `status.danger.bg` row at rest and `status.danger.solid` with white text when highlighted. A red icon and red label on a neutral row is decoration, the coloured paragraph again, and reads as a one-off. Its icon, place and the items that take it are patterns law 3.
+
+## Figures take colour only while they report
+
+A count or stat is in ink unless it reports a problem or progress: overdue or failed in `status.danger.fg`, pending or due soon in `status.warning.fg`, done or logged in `status.success.fg` where the preset colours done. Plain counts stay in ink, and so does every zero; "0 overdue" in red is an alarm with nothing behind it. The label beside the figure always names what it counts, so the colour confirms a word rather than replacing one. One colour per figure: a chip beside it that would compete goes neutral.
+
+## Deriving the four
+
+1. **Hues.** Danger around OKLCH h 25, warning around 70 (amber, not yellow), success around 150, info around 250. Keep each at least ~40° from the `accent` and `focus` hue; an info that collides takes the accent's hue and loses its token, or drops colour — information rarely needs one.
+2. **Light tints.** L 0.965, chroma 0.015–0.02; push chroma until the script reports clipping, then back off.
+3. **Light foregrounds.** Chroma 0.10–0.12; solve lightness for the tertiary target against the *tint*, which is darker than the page and so the worst surface.
+4. **Dark tints.** L 0.25, chroma about 0.035 — tinted, not darkened, so the banner doesn't punch a hole in the page.
+5. **Dark foregrounds.** Chroma about 0.11; solve against the dark tint, then check against the lightest surface a status can sit on.
+
+**Amber, not yellow:** no yellow foreground at usable chroma clears 4.5:1 on white — by then it is brown-olive. An insisted-on yellow warning becomes the *tint*, with an amber or near-black foreground.
+
+### Harbour's status set
+
+From `deriving-a-ramp.md`; foreground on page / own tint / `surface.hover`:
+
+| Role | Light fg | Light bg | Ratios | Dark fg | Dark bg | Ratios |
+|---|---|---|---|---|---|---|
+| `status.danger` | `oklch(0.53 0.12 27)` | `oklch(0.965 0.015 27)` | 5.60 / 5.04 / 4.93 | `oklch(0.66 0.11 27)` | `oklch(0.25 0.035 27)` | 5.85 / 4.95 / 5.02 |
+| `status.warning` | `oklch(0.52 0.1 70)` | `oklch(0.965 0.02 70)` | 5.63 / 5.08 / 4.95 | `oklch(0.66 0.11 70)` | `oklch(0.25 0.035 70)` | 6.01 / 5.06 / 5.17 |
+| `status.success` | `oklch(0.51 0.12 150)` | `oklch(0.965 0.02 150)` | 5.44 / 4.95 / 4.78 | `oklch(0.64 0.11 150)` | `oklch(0.25 0.035 150)` | 5.95 / 4.93 / 5.12 |
+| `status.info` | `oklch(0.52 0.12 250)` | `oklch(0.965 0.015 250)` | 5.50 / 4.97 / 4.83 | `oklch(0.65 0.11 250)` | `oklch(0.25 0.035 250)` | 5.93 / 4.97 / 5.10 |
+
+Info at 250 sits 55° from Harbour's teal accent at h 195, so an info banner never reads as a focused button.
+
+## The non-colour half of every signal
+
+Name the carrier for each status and interactive state:
+
+| Signal | Carrier that survives without colour |
+|---|---|
+| A field in error | A message below it, in words, linked with `aria-describedby`; an icon; the border change is the third signal, not the first |
+| A status banner | A distinct icon *shape* per status (a cross, a triangle, a tick, an "i"), and a lead word — "Error", "Saved" |
+| A work item's state | A glyph whose shape moves with the work: empty ring, dashed ring, half, three-quarters, filled check; a cross for cancelled or failed, a "!" for blocked |
+| Priority | Bars, filled from one to three |
+| A toast | The same, plus `role="status"` or `role="alert"` so it is announced |
+| The current nav item | Its tinted pill (the shape carries it), a marker, a rule or a weight — and `aria-current` |
+| A selected row | `surface.selected` *and* a check, a rule or a bar at the edge |
+| A disabled control | Reduced contrast *and* no hover or pointer, plus `disabled` or `aria-disabled` |
+
+A field in error, in roles — the message and icon carry it, the colour confirms it:
+
+```html
+<label for="dob">Date of birth</label>
+<input id="dob" aria-invalid="true" aria-describedby="dob-error" />
+<p id="dob-error" class="field-error">
+  <svg aria-hidden="true"><!-- a cross, not a dot --></svg>
+  Enter a date in the past.
+</p>
+```
+
+```css
+input[aria-invalid="true"] { border-color: var(--status-danger-fg); }
+.field-error { color: var(--text-secondary); }          /* the sentence stays in ink */
+.field-error svg { color: var(--status-danger-fg); }    /* only the mark takes the colour */
+```
+
+The neutral case: a contents rail moving the current label from `text.secondary` to `text.primary` — 7.7:1 to 15:1, clear in a table, nearly invisible in daylight, to low vision, or mid-scroll. A 2px rule or marker at the edge carries the state; the colour change reinforces it.
+
+A ring that fills as work moves is legible in greyscale, so its colour only confirms what the shape says; that is what lets a product colour done without colour carrying it.
+
+## Done, and where the reader is
+
+Law 7's dial, decided by whether completion is the news:
+
+| The list is… | Done looks like | Why |
+|---|---|---|
+| A sequence the reader passes through: setup steps, passed checks, a wizard | An ink check on a neutral circle | Completion is expected; the pending item is the only news, and a column of green ticks outshouts it |
+| Work people open to see what got done: a task board, a review queue | `status.success` on a filled check | Completion is what they track. The glyph's shape already says done, and late or failed items take warning or danger, so the eye still finds what needs a person |
+| A long list of ticked checkboxes | A light grey box with an ink tick | An inverted ink or accent block per tick shouts down a long list; the tick's shape carries the state |
+| A switch | Its strong fill, on | A switch has no tick, so the fill is the state |
+
+The second row reverses the first on purpose: it is what the "too grey" product in law 7 changed on its boards. Record which lists take which row under `## Decisions`, so the next audit doesn't "fix" one into the other. Under `expressive`, completion may take a brand colour in any row, counted among its exceptions.
+
+Where the reader *is* in the interface (the current nav item or tab) takes the accent tint under product and expressive and stays neutral under editorial and glass (colour law 7). A place in the data with one member is different: on a calendar board, today's column may take a filled `accent` with `text.on-accent`, the one time the brand marks a place rather than an action. Record it as `exception.today`; it doesn't make a second.
+
+## Hue families: colour with a job
+
+Where the reader sorts by kind, place or person at a glance, each question gets its own family, and no family answers another's.
+
+| Question | Family | Takes the colour | Never |
+|---|---|---|---|
+| What is it? | `exception.type.<name>`, one per record type | Its icon, its tag, its chart bar | Text, a state, a whole row |
+| How is it doing? | `status.*` | Its glyph, a figure (above), a field's edge, a banner's tint | A kind, a place, anything merely live |
+| Where does it live? | `exception.area.<name>`, one per folder or area | Nav icon, breadcrumb step, page-title icon | Text, a state |
+| Who? | `exception.person.<n>`, a fixed set assigned from the person's id | Avatars only, coloured rather than grey circles | Names, rows |
+
+- **Marks only.** The family colours the glyph; the words beside it stay in ink.
+- **No crossing.** A late task's type icon keeps its hue; the status glyph beside it turns. Where a family hue falls near a status hue or the accent, move its lightness or chroma until it can't be read as one, and never reuse a status value.
+- **A brand avatar is not a family.** If the design gives every avatar the brand's colour or gradient, keep it: one shared treatment is identity, and it reads as the product. A person family is for when the reader must tell people apart at a glance, and it is added on top of the brand, never swapped in for it.
+- **Muted is fine for people.** When a person family is needed and the hues near the accent and the status colours are ruled out, leaving one that clips (an olive `#686800`), lower the chroma rather than force a saturated hue. Avatars and other "who" marks only need telling apart.
+- **3:1 on every ground, per theme.** A mark the reader needs is a non-text graphic: measure it with `contrast.mjs --min 3` on each surface it sits on (panel, frame, hover, selected) in each theme, and re-pick the family per theme like any accent.
+- **Listed.** Under **Exceptions** in `DESIGN.md`, each family with its question, its members and its marks: "`exception.area.*` — where a record lives. Nav icon, breadcrumb step, page-title icon. Never text, never state."
+
+## Chromatic exceptions
+
+### The test
+
+**Content, or the interface speaking about it?** An offer ("the short version?"), a way in, a warning before the reader begins is a category the eye is entitled to find quickly, and most pages have very few. The Glass preset's "short version" panel is the interface asking whether you want three lines instead of three thousand words; its colour is a gradient edge and a single accent mark, and the summary inside stays in the page's ink.
+
+This test is for colour being added. Colour the design already spends on a job stays (colour law 7), so the test is never a reason to strip it.
+
+Reasons that can't spread name a category with one member: "it's the only offer on the page", "it's the one call to action in the flow", "it's the live indicator, and only one thing is ever live". Reasons that can, and will: "it's important", "it's new", "it's premium", "it's the brand colour", "the page felt grey".
+
+### Containment
+
+- **Only the mark takes the colour** — the edge, the glyph, the icon, the dot; text inside stays in the page's ink.
+- **Its own named tokens**, `exception.<what-it's-for>-*`, so nothing borrows them by accident.
+- **Every stop moves per theme** by roughly the same lightness (law 8), with the fill tinted rather than darkened.
+
+### Counting
+
+Within the dial's allowance, an expressive palette still names each hue's place: "coral only on section backgrounds in the pricing band", "violet only on the one hero illustration". A hue without a written place is an uncounted exception. What weight, position and space can't make findable is usually what must be found before reading starts.
+
+### Live is not danger
+
+A recording or live state borrows nothing from `status.danger`: a red-filled record button reads as an error and as the destructive colour, and looks wrong. Live is the brand's: a well tinted with the accent, a 1px accent ring, a soft accent glow, and level bars that move with the input. Red survives only as a small live dot. The control shows Stop on hover and focus, and holds still while paused; both belong to the motion guide. Name it `exception.live`.
+
+### One gradient, for AI working now
+
+If a product has one gradient, it means one thing. A thin conic stroke in the accent's hues travels round the card where AI is working live, with a soft glow; everything else stays flat. Paused, the stroke stops and the glow dims; under reduced motion it holds still; under `prefers-contrast: more` it becomes a solid accent edge. Its stops are runtime values, every one moved per theme (laws 8 and 10). Name it `exception.ai-live`.
+
+### Marking AI output
+
+A small sparkle glyph in the accent beside what the AI wrote: not a robot avatar, not a coloured bubble. A bubble colours the content, which the reader judges in ink like any other, and an avatar gives a tool a face. Only the mark takes the colour, and a mark, never a fill, doesn't compete with the one action the accent marks.
+
+### When the brand hue is also a status hue
+
+A red brand and a red danger, or a green brand and a green success, read as each other; one gives way. Usually the status moves — danger to a deeper, bluer red, success to a teal-green — because a status must be unambiguous and a brand is also recognised by shape and placement. Where the brand colour must stay on a destructive action (a red brand's "Delete"), the word, the icon and a confirmation step say "destructive". Record the choice under `## Decisions`.
+
+### The accent is not an exception
+
+It is the one planned colour, its jobs set by the dial; colour law 5 covers the ring it can hide when over-spent.
+
+## Charts are a different palette
+
+Categorical series colours are neither status nor exception and need their own method (distinguishable in colour-vision deficiency, legible in both themes, ordered). Never borrow status foregrounds: a red line reads as "error" whatever it measures. The one overlap: series that *are* a family's members, such as record types, take that family's hues, since they answer the same question.
+
+| Series | Colour |
+|---|---|
+| One primary series | `accent` — it is what the screen is about, so the brand stays on it |
+| Comparison, previous period, target | Neutral: `mark` or a text tier, dashed or thinner where it shares an axis with the primary |
+| Three or more of equal standing | `chart.series.<n>`, an ordered set, below |
+
+The ordered set: start from the accent hue and step round, each hue at least ~40° from the status hues, alternating lightness so neighbours still part in greyscale and colour-vision deficiency. Every series clears 3:1 on the chart's surface in each theme, re-picked per theme like any accent. Past six or seven, group the tail as "Other" in a neutral; a legend nobody can match isn't a palette. Record the set in `DESIGN.md` `## Colour` with its order.

package/plugins/keyline/skills/keyline/domains/color/theming-mechanics.md

@@ -0,0 +1,121 @@
+# Theming mechanics
+
+The machinery behind laws 9 and 10, with notes where a framework changes the answer.
+
+## The switch: an attribute, a class, or the media query
+
+| The project has… | Mechanism |
+|---|---|
+| One theme | None. Declare `color-scheme` and stop |
+| Two themes, no toggle, follows the OS | `@media (prefers-color-scheme: dark)` re-declares the tokens. One source of truth, so the media query is fine |
+| A toggle | An attribute (`data-theme="dark"`) or a class (`.dark`) on `<html>`, set by script. The media query only *seeds* the first visit |
+
+An attribute suits more than two values. Every theme block keys off it:
+
+```css
+:root                    { color-scheme: light; --surface-page: …; --text-primary: …; }
+:root[data-theme="dark"] { color-scheme: dark;  --surface-page: …; --text-primary: …; }
+```
+
+Utility frameworks need telling. In Tailwind v4, `@custom-variant dark (&:where([data-theme="dark"], [data-theme="dark"] *));` — the `:where()` keeps specificity at zero, so a `dark:` utility doesn't outrank an unprefixed one just for the attribute selector. Tailwind v3: `darkMode: ["selector", '[data-theme="dark"]']`. A CSS-in-JS provider reads the same attribute instead of holding its own state.
+
+### Theme islands
+
+A region that must stay light in a dark page — an embedded document preview, a print-styled code sample — can't nest `data-theme="light"` if the dark selector matches descendants: the ancestor's match applies all the way down. Re-declare the custom properties and `color-scheme` on its container; since components reference role variables, everything inside re-themes. A dark band on a light-only page — a testimonial strip, a closing call to action — is the same island, and `--focus` is among what it re-declares, measured at 3:1 against the band.
+
+## No flash of wrong theme
+
+The theme must be on `<html>` before first paint:
+
+```html
+<script>
+  (function () {
+    try {
+      var t = localStorage.getItem("theme");
+      document.documentElement.dataset.theme = t === "dark" || t === "light" ? t
+        : matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+    } catch (e) {}
+  })();
+</script>
+```
+
+Inline, since an external script is a round trip the page paints during; blocking, with no `async`, `defer` or `type="module"` (which defers implicitly); before the stylesheet, so the attribute is there when the CSS applies; in `try/catch`, because storage throws in some private-browsing modes and cookie policies, and an uncaught throw stops every script after it. It duplicates the theme module on purpose; comment each to point at the other. Setting the theme in a mount effect instead flashes every dark-mode visitor white on every load.
+
+**Under SSR** a cookie is the only way, since the server can't read storage. Check that a theming library injects a blocking head script or renders server-side — some apply the theme only after hydration.
+
+## Persistence
+
+Keep three functions apart; they have different callers:
+
+```ts
+type Theme = "light" | "dark";
+
+export function readTheme(): Theme {          // initial UI state — mirrors the head script
+  try {
+    const t = localStorage.getItem("theme");
+    if (t === "dark" || t === "light") return t;
+  } catch {}
+  return matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+}
+export function applyTheme(t: Theme): void {  // the DOM write
+  document.documentElement.dataset.theme = t;
+}
+export function chooseTheme(t: Theme): void { // the user's action
+  try { localStorage.setItem("theme", t); } catch {}
+  applyTheme(t);                               // plus the crossfade, below
+}
+```
+
+**Compare, don't parse:** exact matching lets a stale, corrupted or older-version value fall through to the default. **Wrap every storage access:** a lost preference is an annoyance; a thrown exception is a broken page. Keeping `applyTheme` apart from `chooseTheme` lets the toggle animate and the first paint not.
+
+## Two states or three
+
+**Two (light, dark)** is predictable, and two buttons with `aria-pressed` are simpler to build and explain than a tri-state.
+
+**Three (light, dark, system)** costs two things; skipping either is the common bug:
+
+1. The head script resolves `system` too, with `matchMedia` inline, and a `readChoice()` returning the stored three-way choice sits beside `readTheme()`, which returns the resolved theme.
+2. A live listener, so the page follows the OS *while it's open*:
+
+The listener, and the transition hold it needs so an OS switch doesn't cross-fade, are in `domains/motion/patterns.md` (*Theme cross-fade*).
+
+Following the OS on load and then silently stopping is worse than not offering the option. Which to ship is a dial (the colour guide's theme control).
+
+## The crossfade on toggle
+
+A reader's toggle cross-fades and an OS switch doesn't; the CSS, the timing and the reduced-motion branch are motion's (`domains/motion/patterns.md`, *Theme cross-fade*), since `duration.theme` and `ease.colour` are its tokens. Call it around `applyTheme`.
+
+## `color-scheme`
+
+In every theme block. Beyond scrollbar tracks and thumbs it re-tints checkbox, radio and select chrome, date pickers, autofill and the default canvas before your background paints; a white scrollbar track reads as broken dark mode like little else.
+
+## Runtime or build-time
+
+| Value | Where it lives | Why |
+|---|---|---|
+| The role vocabulary — surfaces, text tiers, borders, accent | Custom properties per theme, surfaced through the framework's token system | Themes re-declare them |
+| Translucent material tints | Runtime custom properties | `prefers-reduced-transparency` swaps them for solids |
+| Lower text tiers, if the project supports it | Runtime custom properties | `prefers-contrast: more` may raise them |
+| Gradients, shadow stacks, filter chains | Runtime custom properties or one shared constant | No colour-token system has a slot for them |
+
+"Build-time" is any value compiled to a literal — a Sass variable, an inlined JS constant, a token pipeline resolving to hex, Tailwind v4's `@theme inline` holding a literal — which no media query or theme attribute can re-declare. Keep literals in the theme blocks and point the build-time layer at them: in Tailwind v4, `@theme` entries, or `@theme inline { --color-surface: var(--surface-page); }` so themes can re-declare them; in a Tailwind config, `theme.extend.colors` entries set to `var(--…)`, as in `colors: { surface: "var(--surface-page)" }`; in a JS theme object, keys holding the same `var()` references.
+
+### Preference overrides
+
+After every theme block, naming every theme selector:
+
+```css
+@media (prefers-reduced-transparency: reduce) {
+  :root, :root[data-theme="dark"] {
+    --material-nav-tint: var(--surface-raised);
+  }
+}
+```
+
+That swaps the tint only; dropping the blur is the other half, owned by the depth guide.
+
+In **forced-colours mode** system colours replace the palette: backgrounds and box-shadows vanish, outlines and borders survive — and with them goes a `box-shadow` focus ring and any state carried only by a background tint (law 6).
+
+## Where per-theme variants are still needed
+
+Tokens re-tint, so most components need no theme branching. The exceptions change *structure*: a shadow whose inset highlight weakens while its ambient layers strengthen several-fold; a two-toned edge that must nearly vanish in dark, where it reads as a glowing line. The test: **can this be one token whose value changes?** If not, it needs a variant — once, as one shared constant holding both theme forms.

package/plugins/keyline/skills/keyline/domains/depth/elevation-recipes.md

@@ -0,0 +1,191 @@
+# Elevation recipes
+
+Starting values for each level's bundle and shadow; the depth guide's Dials set their strength, `DESIGN.md` the project's choice.
+
+## The bundle, part by part
+
+| Part | Comes from | Job | Fails as |
+|---|---|---|---|
+| Surface | `surface.page`, `surface.raised`, `surface.inverse` (the colour guide) | Which object this is | Indistinguishable from the level below, especially in dark themes |
+| Edge | `border.default` or `border.layered`, at a `hairline.*` weight (the layout guide) | Exactly where it ends | Mushy outline; vanishes in forced colours if it was only a shadow |
+| Shadow | This guide | That it is above, and how far | Fog, halo, or a shape read as a second object |
+| Layer | `z.*` (the layout guide) | Makes paint order agree with the shadow | A shadow cast over something painted on top of it |
+
+Check the four together: three right and one borrowed is the commonest depth bug, and no single-property lint catches it.
+
+## The four levels
+
+| Level | Behaviour | Surface | Edge | Shadow | Layer | Scrim |
+|---|---|---|---|---|---|---|
+| `elevation.flat` | Scrolls with the page | `surface.page` or `surface.subtle` | `border.default`, or none with a surface step | None | Page flow | No |
+| `elevation.raised` | Picked up, dragged, or sticky over passing content | `surface.raised` | `border.default` | Contact + 1 ambient | `z.raised`, sticky chrome at `z.nav` | No |
+| `elevation.floating` | Summoned, dismissed on its own | `surface.raised` (dark: one step lighter) | `border.default` / `border.layered` | Contact + 1–2 ambient, optional highlight | `z.popover` | No — a transparent catcher at `z.dismiss` |
+| `elevation.overlay` | Blocks until answered | `surface.raised` (dark: two steps lighter) | `border.default` | Contact + 2 ambient, longest | `z.overlay` | Yes |
+
+Sticky chrome is raised in behaviour but high on the z ladder, because content passes under it — the one place level and layer differ, and why the layer is part of the bundle.
+
+A tooltip is floating and transient: no contact layer, a short ambient and, on `surface.inverse`, one shadow for both themes, its own surface being what the shadow separates.
+
+## Building a shadow
+
+Derive every layer from `Y`, the level's near-ambient offset; fixed proportions read as one light at different heights.
+
+```
+contact        0  1px   1px   0      α × 0.35
+near ambient   0  Y     2Y   −Y/2    α × 0.7
+far ambient    0  3Y    4Y   −Y      α            (floating and overlay only)
+inset highlight  inset 0 1px 0 white at h       (optional, per preset)
+```
+
+`α` is the level's peak opacity, from the Dials. Typical `Y`: raised 2px, floating 8px, overlay 16px. At `Y = 8px`, `α = 0.06`:
+
+```css
+--elevation-floating:
+  inset 0 1px 0 rgb(255 255 255 / 0.5),
+  0 1px 1px rgb(0 0 0 / 0.02),
+  0 8px 16px -4px rgb(0 0 0 / 0.04),
+  0 24px 32px -8px rgb(0 0 0 / 0.06);
+```
+
+**Why each proportion.** Blur at twice the offset keeps the penumbra soft without detaching; spread at minus half keeps the shadow under the footprint, displaced downward — tucked, not haloed. Opacity rises with distance, as ambient occlusion: the larger far layer is fainter per pixel, so needs slightly more alpha.
+
+**The contact layer is for resting things**, chrome and cards; tooltips and drag previews in flight hover, and skip it. **The inset highlight**, the specular catch on the top edge, is optional per preset; product usually omits it, a bright line on every menu in a dense screen being noise.
+
+## Per preset
+
+Light-theme floating shadows at the dial strengths; raised and overlay follow from the `Y` values above.
+
+| Preset | Floating recipe (light) |
+|---|---|
+| `editorial` | `inset 0 1px 0 rgb(255 255 255 / 0.5), 0 1px 1px rgb(0 0 0 / 0.02), 0 8px 16px -4px rgb(0 0 0 / 0.04), 0 24px 32px -8px rgb(0 0 0 / 0.06)` |
+| `product` | `0 1px 1px rgb(0 0 0 / 0.04), 0 12px 24px -8px rgb(0 0 0 / 0.10)` — edges carry the rest |
+| `expressive` | `inset 0 1px 0 rgb(255 255 255 / 0.6), 0 1px 2px rgb(0 0 0 / 0.06), 0 10px 20px -6px rgb(0 0 0 / 0.10), 0 32px 48px -12px rgb(0 0 0 / 0.16)` |
+
+Product leans on `border.default` with short shadows, so dense screens don't fill with grey, and draws that edge as a ring inside the shadow on cards, menus and dialogs alike (below). Expressive may add one decorative level — a branded pocket, a hero card — named, with its own bundle.
+
+## Dark theme: a different recipe
+
+Three things change; none is "the same shadow, darker":
+
+1. **The surface lifts** by the Dials' OKLCH step: page 0.18 → raised 0.22 → floating 0.26 → overlay 0.30 at +0.04. It carries most of the separation.
+2. **Drop layers rise to the dials' dark peak** (depth guide, *Floating shadow*). A 4% black shadow on a near-black page is invisible.
+3. **The highlight drops to a sixth.** `0.5` white along a dark top edge reads as a lit wire; `0.08` defines the edge without lighting it.
+
+```css
+[data-theme="dark"] {
+  --elevation-floating:
+    inset 0 1px 0 rgb(255 255 255 / 0.08),
+    0 1px 1px rgb(0 0 0 / 0.3),
+    0 8px 16px -4px rgb(0 0 0 / 0.4),
+    0 24px 32px -8px rgb(0 0 0 / 0.5);   /* editorial's 50% dark peak */
+}
+```
+
+A `#000` page leaves drop layers no room, so only the surface step separates and the top level must climb further. Then switch shadows off: if surface and edge can't tell floating from raised, the dark step is too small.
+
+## Shadows on tinted grounds
+
+On a tinted ground — warm off-white, a brand band — neutral black reads as dirt. Take the shadow from the ground's hue:
+
+```css
+--shadow-ink: oklch(from var(--surface-page) 0.25 calc(c * 1.5) h);
+--elevation-raised: 0 1px 1px rgb(from var(--shadow-ink) r g b / 0.05),
+                    0 2px 4px -1px rgb(from var(--shadow-ink) r g b / 0.08);
+```
+
+Without relative colour syntax, pick it by hand (the ground's hue, low lightness, slightly more chroma) and record it under its surface role, so re-tinting the ground moves the shadow.
+
+## Edges that survive
+
+A card animating by transform, as in a reordering stack, can't change its border without shifting layout; use `outline: 1px solid <border.default>; outline-offset: -1px`, which, unlike a `0 0 0 1px` shadow ring, survives forced colours. An edgeless surface carries `border: 1px solid transparent` — a boundary for exactly the users who asked for one.
+
+**The ring edge** (`product`): the edge as the first layer of the level's one shadow definition, so edge and shadow change together and every card, menu and dialog gets the same line.
+
+```css
+:root {
+  --elevation-floating:
+    0 0 0 0.5px var(--border-default),          /* the edge */
+    0 1px 1px rgb(0 0 0 / 0.04),
+    0 12px 24px -8px rgb(0 0 0 / 0.10);
+}
+.card, .menu, .dialog { border: 1px solid transparent; box-shadow: var(--elevation-floating); }
+@media (prefers-contrast: more) {
+  .card, .menu, .dialog { border-color: var(--text-primary); }   /* a real 1px edge, as for materials */
+}
+```
+
+Half a pixel is one device pixel on a 2x screen and rounds to a faint 1px on 1x, which is the point — quieter than any border — and why the contrast preference gets a real one. Forced colours paints the transparent border.
+
+## Moving between levels
+
+- **Hover on a raised card** may deepen the shadow, as raised's own state; if the lift overlaps a neighbour it also takes `z.raised`, or the next sibling paints over it. In `product`, hover is a surface wash and the bundle stays put; the motion guide says why.
+- **Drag** moves it to floating, whole — shadow, layer, dark surface — and drop moves it back.
+- **A popover promoted to a dialog** changes to overlay and gains a scrim at the same moment.
+
+## Closing an overlay
+
+A dialog hands focus back to its opener. Primitives do this for a trigger they rendered; a dialog opened from state — a row's menu item, a keyboard shortcut, a bulk selection — has none, and focus falls to `<body>`. Store the opener as it opens:
+
+```tsx
+const opener = useRef<HTMLElement | null>(null);
+const openDialog = () => { opener.current = document.activeElement as HTMLElement; setOpen(true); };
+
+<Dialog open={open} onOpenChange={setOpen}
+  onCloseAutoFocus={(e) => {                       // or the primitive's equivalent close hook
+    e.preventDefault();
+    const back = opener.current?.isConnected ? opener.current : fallback();
+    back?.focus();
+  }}>
+```
+
+- **Opened from a menu item:** the item unmounted with the menu; store the menu's trigger, not the item.
+- **The opener is gone** — the row was just deleted: `fallback()` focuses its neighbour, or the list's heading, never the page top.
+
+## The art panel
+
+Where a product keeps art (depth law 6) it is one inset panel; where it sits on a sign-in page is patterns law 13.
+
+- **Its own surface, not a level.** Inset by the page gutter, at `radius.container`, no shadow: it is part of the page, not above it.
+- **Its theme is scoped.** Art designed for one ground looks wrong on the other, so the panel pins a theme (`data-theme="dark"` on the panel, its tokens re-resolving inside) and reads the same in both.
+- **Generative over photographic.** A photograph or a soft gradient wash reads dated; art generated in the brand's colours reads current. Whether it moves is the motion guide's ambient class (motion law 4).
+- **A frosted element sits over still art** only, as the pocket in `translucent-materials.md`, with its opaque fallback.
+
+## One definition per level
+
+One custom property per level per theme, or one class, never inline copies. Utility arbitrary values add a hazard: spaces become underscores, commas stay unspaced, and a typo yields a class the build silently drops — no shadow, no error.
+
+## A worked example
+
+**Tally**, a fictional invoicing app on `product` with `app/(marketing)/**` on `expressive`, whose tokens call surfaces `canvas` and `panel` and the edge `line`: four opaque levels in the app, one chrome tier on the marketing header.
+
+```css
+:root {
+  --elevation-raised:   0 1px 1px rgb(20 20 30 / 0.04), 0 2px 6px -2px rgb(20 20 30 / 0.06);
+  --elevation-floating: 0 1px 1px rgb(20 20 30 / 0.05), 0 12px 24px -8px rgb(20 20 30 / 0.10);
+  --elevation-overlay:  0 1px 1px rgb(20 20 30 / 0.06), 0 24px 48px -12px rgb(20 20 30 / 0.16);
+  --scrim: rgb(20 20 30 / 0.40);
+}
+[data-theme="dark"] {
+  --color-panel:        oklch(0.25 0.01 270);   /* canvas is 0.21; each level +0.04 */
+  --color-panel-float:  oklch(0.29 0.01 270);   /* proposed: surface.floating */
+  --elevation-floating: 0 1px 1px rgb(0 0 0 / 0.40), 0 12px 24px -8px rgb(0 0 0 / 0.55);
+  --scrim: rgb(0 0 0 / 0.60);
+}
+```
+
+The theme-varying value stays a runtime custom property: Tailwind v4 `@theme inline { --shadow-floating: var(--elevation-floating); }`, so the utility follows each theme; v3 `boxShadow: { floating: 'var(--elevation-floating)' }`; a JS theme object `shadows.floating: 'var(--elevation-floating)'`.
+
+## Recording it
+
+```markdown
+## Surfaces
+
+| Level | Surface | Edge | Shadow | Layer |
+|---|---|---|---|---|
+| `elevation.flat` | `bg-canvas` | `border-line` | — | — |
+| `elevation.raised` | `bg-panel` | `border-line` | `shadow-raised` | `z-raised` |
+| `elevation.floating` | `bg-panel` · dark `bg-panel-float` (proposed) | `border-line` | `shadow-floating` | `z-popover` |
+| `elevation.overlay` | `bg-panel` · dark `bg-panel-overlay` (proposed) | `border-line` | `shadow-overlay` | `z-overlay` |
+
+**Scrim** — `bg-scrim`: 40% light, 60% dark. **Materials** — opaque only.
+```

package/plugins/keyline/skills/keyline/domains/depth/fallbacks-and-performance.md

@@ -0,0 +1,132 @@
+# Fallbacks and performance
+
+Every material ships four more paths — no support, reduced transparency, increased contrast, forced colours; opaque surfaces need only the last, or the last two where their edge is a shadow ring — and a cost model sets its budget.
+
+## The order
+
+The fallbacks re-declare the theme blocks' properties at the same specificity, so source order decides.
+
+```css
+/* 1. Theme blocks — tints and shadows per theme (tint colours: color-and-theming) */
+:root                { --chrome-tint: rgb(245 245 247 / 0.76); }
+[data-theme="dark"]  { --chrome-tint: rgb(34 34 38 / 0.76); }
+
+/* 2. Opaque baseline — the default, and so the tested path */
+.material-chrome {
+  background: var(--surface-raised);
+  border: 1px solid var(--border-layered);
+}
+
+/* 3. The material, as an enhancement */
+@supports (backdrop-filter: blur(1px)) or (-webkit-backdrop-filter: blur(1px)) {
+  .material-chrome {
+    background: var(--chrome-tint);
+    backdrop-filter: blur(20px) saturate(1.7);
+  }
+}
+
+/* 4. Preferences — after everything above */
+@media (prefers-reduced-transparency: reduce) {
+  :root, [data-theme="dark"] { --chrome-tint: var(--surface-raised); }
+  .material-chrome { backdrop-filter: none; }
+}
+@media (prefers-contrast: more) {
+  .material-chrome { border-color: var(--text-primary); }
+}
+@media (forced-colors: active) {
+  .material-chrome { border-color: CanvasText; }
+}
+```
+
+**The reduced-transparency block names every selector that set the tint**: if the dark theme is `:root[data-theme="dark"]`, so is the fallback, or it wins in light only.
+
+**`--surface-raised` is an existing surface, chosen per material:** chrome falls back to `surface.raised` and still reads as raised; a decorative soften-tier pocket, whose whole purpose was translucency, to `surface.page`.
+
+**Opaque is the default, the material layered on**; a fallback bolted underneath is the path nobody sees, so the one that ships broken.
+
+## Reduced transparency: both halves
+
+Blur is expensive on weak devices and translucency hurts reading; an opaque surface answers both, with both halves:
+
+| Only… | Result |
+|---|---|
+| Drops the filter | A thin tint over live content, suppressing nothing: text over text, worse than before |
+| Swaps the tint | Opaque, but still paying for the blur — half the preference's reason |
+
+It also makes text contrast computable and true for the users most likely to need it. Test with macOS *Reduce transparency*, Windows *Transparency effects* off, or the browser's rendering emulation.
+
+## Increased contrast
+
+A faint `border.layered` goes first. Promote the edge to `text.primary` and leave the surface — high contrast is about boundaries and text, not the material — so it composes with reduced transparency: opaque surface, strong edge. A half-pixel ring edge goes the same way, swapped for a real 1px border (`elevation-recipes.md`).
+
+## Forced colours
+
+System colours replace backgrounds and borders, and every `box-shadow` goes, leaving only law 3's edge — `1px solid transparent` on an edgeless surface, painted as `CanvasText`. **`background-clip: text` with transparent text** can render as nothing, which is why a sheen removes its class when it ends.
+
+Leave `forced-color-adjust: none` alone unless a component is broken without it; the user chose their colours.
+
+## The prefix and the pipeline
+
+Safari still needs `-webkit-backdrop-filter`; hand-writing it depends on the pipeline.
+
+- **Pipeline prefixes for you** (Lightning CSS — which Tailwind v4 uses — or Autoprefixer, with targets including Safari): write only `backdrop-filter`. Lightning CSS treats a hand-written `-webkit-` line beside the standard one as a duplicate and keeps the last, shipping the prefix alone: Firefox ignores it and loses every blur, invisibly in Chrome and Safari.
+- **No prefixing step:** write both, standard property last.
+
+The Glass preset's hand-written prefix did this on its live site. Verify the built output:
+
+```sh
+# the rule as shipped — both properties must appear
+grep -o '\.material-chrome{[^}]*}' dist/**/*.css
+```
+
+Or in Firefox, `getComputedStyle(el).backdropFilter` on a filtered element: `"none"` means the standard property didn't ship.
+
+## The cost model
+
+Each frame a visible filtered element's backdrop changes, the browser paints behind it, copies the region, filters and composites. So:
+
+- **Cost scales with area**: one full-viewport surface costs far more than five small ones of the same total perimeter.
+- **It re-runs whenever the backdrop changes** — every scroll frame for chrome over a scrolling page, the common case.
+- **It can't be cached** while the backdrop moves; a layer of its own doesn't help.
+- **Radius matters less than you'd think.** Implementations downsample before blurring, so trimming 20px to 12px buys little; reduce area and count.
+
+| Avoid | Why |
+|---|---|
+| Full-viewport translucent surfaces | Worst case of an area-proportional cost |
+| A translucent surface per list row or card | Multiplies passes by row count |
+| Animating the blur radius | A fresh pass at a new radius every frame |
+| Translucency over video, canvas or animation | Re-filters every backdrop frame, even when nothing in front moves |
+| Closed menus at `opacity: 0` or `visibility: hidden` | Still pay; visibility is decided after filtering. Unmount, or `display: none` |
+| A filter over a flat single-colour backdrop | Pays a pass to produce a plain tint |
+| `will-change: backdrop-filter` | Hints an unwanted animation; may force a needless layer |
+
+`contain: paint` on the filtered surface sometimes helps; measure before and after.
+
+**A blurred scrim**, the one full-viewport filter the Dials allow (`expressive` only), is affordable because the page behind a modal doesn't scroll, so it settles after the open transition. Fade its opacity, never its radius.
+
+## The budget
+
+Count what is on screen at once, not what exists — a header, a dock and one open menu are three — against the Dials' count and area ceiling.
+
+## Measuring
+
+- **Performance panel**, recording a scroll over a long page of images: filters show as long paint and composite blocks, not scripting.
+- **Paint flashing**, to see a filtered surface repaint its whole area every scroll frame.
+- **Layers panel**, to confirm you haven't made dozens of composited layers.
+
+Test on the slowest supported device — desktop GPUs hide this, mid-range phones don't — and watch for dropped frames during scroll.
+
+## Moving shadows cost too
+
+Transitioning `box-shadow` repaints every frame: fine on one card, but across a long list or a hovered grid, fade a pseudo-element's opacity, which the compositor handles:
+
+```css
+.card { position: relative; box-shadow: var(--elevation-raised); }
+.card::after {
+  content: ""; position: absolute; inset: 0; border-radius: inherit;
+  box-shadow: var(--elevation-raised-hover);
+  opacity: 0; transition: opacity <duration.state> <ease.standard>;
+  pointer-events: none;
+}
+.card:hover::after { opacity: 1; }
+```