@nurix/etna 0.19.51 → 0.19.53

package/data/harnesses/code/skills/design/data/chrome/stat-cards.md

@@ -0,0 +1,62 @@
+---
+id: stat-cards
+class: d2
+sourced: 2026-07-12
+source: "@nurix/components Statistics compound family (+ AnimatedNumber, useStatHoverBridge; visuals host Gauge/Spark/ProgressBar/ChartLegend) — ~/dev/components"
+license: open
+---
+
+# Chrome recipe — stat cards
+
+The stat-card family: one compound grammar for every KPI tile, gauge card, sparkline card, legend card, and list card. The root is a structural flex column providing shared context (`size`, `comparisonLabel`); ~two dozen dotted parts compose the regions. The card draws no chart geometry itself — the visual slot hosts a chart element. The dashboard-tile obligation applies to every instance: **number + comparison + trend + state + door**.
+
+## Anatomy
+
+| Slot | Library part | Spec |
+| --- | --- | --- |
+| Root | `Statistics { size: "sm" \| "md" \| "lg", variant: "bare" \| "card" \| "elevated" \| "outline" \| "soft" \| "ghost", accent: "none" \| "primary" \| "success" \| "warning" \| "danger" \| "info", gap, justify, comparisonLabel }` | The surface. `bare` draws nothing (consumer owns the wrapper); the rest share `overflow-hidden rounded p-6` with their own background/border/shadow. `accent` draws a 4px left stripe. `size` scales the headline value and title through context. |
+| Section | `StatisticsSection` | Vertical region group for top/bottom cascades (`justify: "between"` pins one to each end). |
+| Header | `StatisticsHeader` → `StatisticsIcon { variant, tone: "soft" \| "solid" \| "outline" \| "plain", size (incl. "oversized"), shape }` + `StatisticsHeading` (`StatisticsTitle`, `StatisticsDescription`) + `StatisticsActions` | Icon/title block left, trailing actions (menu, info, tabs, date range) right. `oversized` icons bleed out the clipped top-right corner as a decorative watermark. |
+| Metric row | `StatisticsMetric` → `StatisticsValue { animated?, value, format, prefix, suffix }` + `StatisticsUnit` + `StatisticsTrend { value, direction?, invert?, pill?, format? }` + `StatisticsComparison` | Baseline-aligned: headline value (static, or digit-animated via NumberFlow with a formatted static first paint — SSR-safe), unit ("/ 5,000"), signed trend badge, comparison label (falls back to the card's `comparisonLabel`). |
+| Visual | `StatisticsVisual` (layout via `StatisticsGroup` horizontal/vertical) | Generic centered slot hosting `<Spark>`, `<Gauge>`, `<ProgressBar>`, `<ChartLegend>`, or any chart element. (Legacy `StatisticsGauge`/`Progress`/`SegmentedBar`/`Sparkline`/`Legend*` parts are deprecated thin wrappers over those same components.) |
+| Content | `StatisticsContent` | Escape hatch for list / table / paragraph cards. |
+| Footer | `StatisticsFooter` → `StatisticsCaption` + `StatisticsLink` | Freshness caption left ("Updated 2m ago" — the tile's *state*), link right (the tile's *door*). |
+| Hover bridge | `useStatHoverBridge()` | Headless hook lifting a hovered chart point into the header: hand its `onHoverChange` to the embedded graph, read `hover.value`/`hover.label` in the value/description with a resting fallback. |
+
+Every part emits `data-slot="statistics-…"` for styling and testing hooks.
+
+## The eight states
+
+| State | Spec | Token roles |
+| --- | --- | --- |
+| default | Card variant on the card surface with a hairline border; value at display scale with tabular numerals; title strong, description muted. | `card` + `card-foreground`, `border`, `foreground`, `muted-foreground` |
+| hover | Elevated variants lift per the package's elevation ramp; with the hover bridge wired, hovering the embedded chart live-rewrites the value and description to the hovered point, reverting on leave. | elevation system; value stays `foreground` |
+| focus | The door (footer link or whole-card link) and any header action are focus stops with visible rings. | `ring` |
+| active | A clickable card shows a pressed treatment; the accent stripe marks category or alert affiliation. | `accent` stripe via `primary`/status roles |
+| disabled | No permission for the metric: value masked (—), lock caption, non-interactive, ~50% presence — the tile keeps its footprint. | reduced-alpha, `muted-foreground` |
+| loading | Skeleton title bar + value block + visual area at the card's fixed height — the grid never reflows when data lands. | `muted` |
+| error / empty | Degraded: em-dash value + status-role caption ("stale as of 09:12") — never a fabricated number. Empty series: the visual slot shows a quiet hint, never a zeroed fake chart. | `warning` / `destructive` caption, `muted-foreground` |
+| success | Trend intent is the success surface: up = good on the success role, down = bad on `destructive`; `invert` flips the mapping for lower-is-better metrics (error rate, latency, churn); zero/no-direction = neutral muted. `pill` wraps it in a tinted badge. Exposed as `data-direction`. | `success` / `destructive` status roles |
+
+## Keyboard behavior
+
+- A stat card is mostly static content; its interactive elements — header actions, the footer link, a clickable card — join the tab order in reading order (header action → door), **Enter** activates.
+- The hover bridge is a pointer-only *enhancement*: the resting value is always the correct headline without any pointer, so keyboard and touch users lose nothing; point inspection falls to the embedded chart's own keyboard/tooltip behavior.
+- An actions menu follows menu semantics: Enter/Space opens, arrows move, Escape closes to the trigger.
+- Animated values render as real formatted text (static until the animation element registers), so the accessible name is always the current number — no aria gymnastics required.
+- **cmdk path**: none — tiles are destinations for the palette ("Go to revenue"), not hosts of it.
+
+## Token reach
+
+- `card` / `card-foreground` — surface and text; `border` — hairline (outline/card variants); `muted` / `muted-foreground` — description, captions, skeletons.
+- Accent stripe and `StatisticsIcon` variants — `primary` plus the status roles (`success`, `warning`, `destructive`/danger, `info`) at soft/solid/outline tones.
+- `StatisticsTrend` — **status roles only**. Known library deviation: the shipped component pins success intent to Tailwind `emerald-500` literals and has no success token; under `nurix` the trend/icon success tints are restyled in place to the package's `success` role (the no-jails law permits this; the token-reach report flags the literal), and under `native` the implementation uses status roles from the start.
+- Embedded visuals — `chart-1..5` for series color, chart chrome roles (`chart-grid`, `chart-tooltip-background/foreground`) for scaffolding; a spark/gauge/progress fill is never a hex literal. The default spark stroke (`var(--primary)`) already token-reaches.
+- The headline value inherits the type ramp's display size via the card `size`; mono/tabular figures come from the package's type roles, never a hardcoded family.
+
+## When to use / composition notes
+
+Stat cards are the dashboard's KPI strip (4–6 tiles full-width per the blueprint shapes) and the record header's vital signs; the same grammar scales from a bare number-plus-trend to a gauge card with a legend, so one card system covers the whole surface. Every tile carries all five obligations — a number without a comparison is decoration, a tile without a door is a dead end. Use `size` to build hierarchy (one `lg` hero metric, `md` support tiles) instead of ad-hoc font sizes; use `justify="between"` with two sections for cards whose visual anchors the bottom edge. Wire the hover bridge whenever a chart lives in the card — it is the cheapest "designed, not templated" signal in the set.
+
+- **`primitives: nurix`** — `import { Statistics, StatisticsHeader, StatisticsIcon, StatisticsHeading, StatisticsTitle, StatisticsDescription, StatisticsActions, StatisticsMetric, StatisticsValue, StatisticsUnit, StatisticsTrend, StatisticsComparison, StatisticsVisual, StatisticsFooter, StatisticsCaption, StatisticsLink, useStatHoverBridge } from "@nurix/components/statistics";` (visuals: `@nurix/components/spark`, `/gauge`, `/progress-bar`; the animated number: `@nurix/components/animated-number`).
+- **`primitives: native`** — this recipe is the build spec: a fixed-height card with header / baseline-aligned metric row / visual slot / footer regions, a display-scale tabular headline that is correct on first paint (animation optional and additive), a sign-driven trend badge with an invert switch on status roles, skeletons that hold the footprint, degraded states that never fabricate numbers, and all series color drawn from the token artifact's `chart-1..5`.

package/data/harnesses/code/skills/design/data/chrome/topbar.md

@@ -0,0 +1,65 @@
+---
+id: topbar
+class: d2
+sourced: 2026-07-12
+source: "@nurix/components — composed pattern: SidebarTrigger + Separator + Breadcrumb family + CommandTrigger + Button (the library's site-header pattern; no single Topbar export) — ~/dev/components"
+license: open
+---
+
+# Chrome recipe — topbar
+
+The app-shell top bar: the sticky row above the content pane carrying the sidebar toggle, the breadcrumb trail, global search, and screen-level actions. In `@nurix/components` this is a **documented composition, not a single export** — every shipped app-shell demo assembles it from `SidebarTrigger`, `Separator`, the `Breadcrumb` family, `CommandTrigger`, and `Button`. Page-level mastheads below it are separate components (`Header` at `@nurix/components/header` for config-driven record headers; `PageHeader` for list/detail mastheads with a stat ledger) and are not part of this recipe.
+
+## Anatomy
+
+| Slot | Library part | Spec |
+| --- | --- | --- |
+| Bar | flex row | Sticky (`top-0`), 48–56px tall, full width of the content pane, hairline bottom border. Optional glass treatment: `background` at ~95% alpha + backdrop blur. |
+| Sidebar toggle | `SidebarTrigger` | Leading icon button toggling the sidebar; reflects open state via `data-state`. |
+| Divider | `Separator orientation="vertical"` | 16px vertical hairline between toggle and breadcrumbs. |
+| Breadcrumbs | `Breadcrumb` → `BreadcrumbList` / `BreadcrumbItem` / `BreadcrumbLink` / `BreadcrumbSeparator` / `BreadcrumbPage` | The location trail. Ancestors are links; the last segment is `BreadcrumbPage` — plain text, `aria-current="page"`, never a link. Deep trails collapse middle segments into an ellipsis dropdown. |
+| Spring | flex spacer | Pushes the trailing cluster right. |
+| Search slot | `CommandTrigger { placeholder, shortcut }` | A bordered search chip with placeholder text and a right-aligned `⌘K` kbd hint; opens the command palette. |
+| Actions | `Button` (ghost/icon), overflow `DropdownMenu` | At most 3 visible screen-level actions; further actions collapse into an overflow menu. Theme toggle sits here. |
+| Identity | `Avatar` (optional) | Only when the shell has no sidebar user footer — one identity home per shell, never two. |
+
+## The eight states
+
+State is mostly per-control; the bar itself is stable chrome.
+
+| State | Spec | Token roles |
+| --- | --- | --- |
+| default | Bar on the content canvas with a hairline base; breadcrumb ancestors quiet, current page at full strength. | `background`, `border`, `muted-foreground` (ancestors), `foreground` (current) |
+| hover | Breadcrumb links sharpen to full foreground; icon buttons gain an accent fill. | `foreground`, `accent` + `accent-foreground` |
+| focus | Focus-visible ring on every control — toggle, links, chip, buttons. | `ring` |
+| active | Sidebar toggle mirrors the open sidebar (`data-state`); the current crumb is the persistent active marker; a pressed action holds its pressed fill. | `foreground`, `accent` |
+| disabled | Actions at ~50% opacity, no pointer events; breadcrumbs are never disabled. | reduced-alpha foreground |
+| loading | An in-flight screen action shows an inline spinner inside its own button. The bar never skeletons: breadcrumbs derive from the route and render immediately. | `muted-foreground` (spinner) |
+| error / empty | An empty trail renders the page title as the single `BreadcrumbPage`. Errors surface as toasts or content-level states — the bar itself hosts none; a degraded-environment banner may attach *beneath* the bar on a status-role tint. | `warning` / `destructive` (banner only) |
+| success | Transient: an action button briefly swaps to a check, or a toast confirms; nothing persistent lives in the bar. | `success` status role (transient) |
+
+## Keyboard behavior
+
+- **Tab order**: the bar follows the skip link and precedes the content pane — toggle → breadcrumb links → search chip → actions → identity. Plain sequential tabbing; no roving focus is needed at this control count.
+- **Enter** activates crumbs and buttons; **Space** activates buttons.
+- **Cmd/Ctrl+B** toggles the sidebar from anywhere (provider-owned); the `SidebarTrigger` is its visible affordance.
+- **cmdk path**: **⌘K / Ctrl+K** opens the command palette from anywhere; the search chip is the visible, clickable affordance and displays the shortcut as a kbd hint. Inside the palette: type to filter, arrows to move, Enter to run, Escape to close. Global navigation and infrequent actions belong in the palette, not as more topbar buttons.
+- Overflow menu: Enter/Space opens, arrows move, Escape closes and returns focus to the trigger.
+
+## Token reach
+
+- `background` — the bar surface (with optional alpha for the glass treatment). The bar sits on the content canvas: it never consumes the `sidebar-*` roles.
+- `border` — the bottom hairline and the vertical separator.
+- `foreground` / `muted-foreground` — current crumb vs ancestors; icon default strength.
+- `accent` / `accent-foreground` — icon-button hover/pressed fills.
+- `ring` — focus rings.
+- `popover` / `popover-foreground` — overflow and ellipsis dropdowns.
+- `primary` — at most one primary CTA, only when the screen genuinely has a single dominant action.
+- Status roles (`warning`, `destructive`, `success`) — only for the attached environment banner and transient confirmations; never as bar decoration.
+
+## When to use / composition notes
+
+Every screen inside the shell gets the topbar; it is the constant that makes the sidebar collapsible (the toggle must survive collapse) and the command palette discoverable. Keep it thin — the topbar locates and searches; identity-weight content (record title, status, metadata, stats) belongs to the page masthead below it (`Header` / `PageHeader` under `nurix`), and datasets' own toolbars belong to their tables. The three-zone rhythm — locate left, search center-right, act right — is the invariant; what varies per product is only which trailing actions earn a permanent slot.
+
+- **`primitives: nurix`** — composed, e.g.: `import { SidebarTrigger } from "@nurix/components/sidebar"; import { Breadcrumb, BreadcrumbList, BreadcrumbItem, BreadcrumbLink, BreadcrumbPage, BreadcrumbSeparator } from "@nurix/components/breadcrumb"; import { CommandTrigger } from "@nurix/components/command"; import { Separator } from "@nurix/components/separator"; import { Button } from "@nurix/components/button";`
+- **`primitives: native`** — this recipe is the build spec: a sticky 48–56px flex row with the slot order above, a real `<nav aria-label="Breadcrumb">` trail with `aria-current="page"` on the last segment, a search affordance wired to the stack's palette (or a plain search route) showing its shortcut, and the state/keyboard/token contracts implemented with the incumbent stack's own primitives.

package/data/harnesses/code/skills/design/data/elevation/ant-design-directional-shadow.md

@@ -0,0 +1,19 @@
+---
+id: ant-design-directional-shadow
+class: a3
+sourced: 2026-07-12
+source: "distilled from ant.design/docs/spec/shadow"
+license: open
+feel: "enterprise-friendly, directionally aware; drawers and fixed headers cast shadow toward the content they overlay, not just downward"
+---
+Ant Design is unusual in defining shadow **direction** as a first-class variable: the same three-layer blur/opacity recipe is mirrored down/up/left/right depending on where the component sits (a right-side drawer casts left, a bottom-fixed table header casts up). Three layers per direction blend from a tight, high-opacity contact shadow to a huge, near-invisible ambient one.
+
+```yaml values
+radius: { sm: 4, md: 6, lg: 8 }
+hairline: "none at rest; inputs use a separate 1px border token, not shared with the shadow system"
+shadow:
+  layer1-down: "0px 1px 2px -2px rgba(0,0,0,.16), 0px 3px 6px 0px rgba(0,0,0,.12), 0px 5px 12px 4px rgba(0,0,0,.09)"
+  layer2-down: "0px 3px 6px -4px rgba(0,0,0,.12), 0px 6px 16px 0px rgba(0,0,0,.08), 0px 9px 28px 8px rgba(0,0,0,.05)"
+  layer3-down: "0px 6px 16px -8px rgba(0,0,0,.08), 0px 9px 28px 0px rgba(0,0,0,.05), 0px 12px 48px 16px rgba(0,0,0,.03)"
+dark-ladder: { step: "+~5L per level (v5 dark algorithm inverts the neutral scale)", hue: held }
+```

package/data/harnesses/code/skills/design/data/elevation/apple-liquid-glass-material.md

@@ -0,0 +1,18 @@
+---
+id: apple-liquid-glass-material
+class: a3
+sourced: 2026-07-12
+source: "distilled from developer.apple.com/design/human-interface-guidelines/materials"
+license: reference-only
+feel: "spatial, translucent, light-reactive; depth comes from a refractive material simulating glass thickness, not a fixed shadow token"
+---
+Apple's newest materials model (Liquid Glass) ties elevation to simulated material *thickness* rather than a discrete shadow scale: as a glass element grows or is interacted with, it "flexes" to a thicker material with deeper shadow and more pronounced lensing/refraction. Darker, denser materials deliberately mute shadow legibility, trading depth for reduced visual noise — the opposite trade every other system here makes.
+
+```yaml values
+radius: { sm: 10, md: 16, lg: 28 }
+hairline: "none as a drawn line — edge definition comes from the material's own refractive/specular edge"
+shadow:
+  base: "shadow deepens dynamically as the glass element scales up (material 'flexes' thicker)"
+  scroll: "shadow intensifies as content scrolls beneath it, to preserve separation"
+dark-ladder: { step: "n/a — darker/denser materials intentionally reduce shadow legibility rather than laddering lightness", hue: held }
+```

package/data/harnesses/code/skills/design/data/elevation/atlassian-surface-shadow-pairing.md

@@ -0,0 +1,20 @@
+---
+id: atlassian-surface-shadow-pairing
+class: a3
+sourced: 2026-07-12
+source: "distilled from atlassian.design/foundations/elevation and /foundations/radius; radius px approximated from usage guidance, exact figures not published in source"
+license: open
+feel: "structured enterprise calm; every raised surface ships as a matched surface+shadow pair, never a shadow in isolation"
+---
+Atlassian defines four discrete elevations — sunken, default, raised, overlay — and enforces that `elevation.surface.*` and `elevation.shadow.*` tokens are always used together, never mixed across levels. In dark mode the rule inverts intuition: higher elevation surfaces get **lighter**, not darker, simulating front-lighting rather than cast shadow.
+
+Approximation note: radius px approximated from usage guidance — exact figures are not published in the source and should be checked before shipping.
+
+```yaml values
+radius: { sm: 3, md: 6, lg: 8 }
+hairline: "none at rest — sunken/default read via fill color, not a border line"
+shadow:
+  raised: "0px 1px 1px #091E4240, 0px 0px 1px #091E424F"
+  overlay: "0px 8px 12px #091E4226, 0px 0px 1px #091E424F"
+dark-ladder: { step: "+~4L per level — \"the higher the elevation, the lighter the surface looks\"", hue: held }
+```

package/data/harnesses/code/skills/design/data/elevation/fluent-2-key-ambient-ramp.md

@@ -0,0 +1,20 @@
+---
+id: fluent-2-key-ambient-ramp
+class: a3
+sourced: 2026-07-12
+source: "distilled from fluent2.microsoft.design/elevation"
+license: open
+feel: "Windows-native layered light; every shadow is a paired sharp key + soft ambient cast, doubling in blur up the ramp"
+---
+Fluent 2 generates its whole shadow ramp from one equation: each step doubles the prior step's blur (shadow2 → 4 → 8 → 16 → 28 → 64), always as a key+ambient pair. Dark mode doesn't lighten surfaces — it simply raises the shadow's own opacity (~0.14 → ~0.28) to stay visible against a dark canvas.
+
+```yaml values
+radius: { sm: 2, md: 4, lg: 6 }
+hairline: "none by default — shadow2 (near-hairline blur) covers the lowest resting state"
+shadow:
+  shadow2: "0 0.5px 1px rgba(0,0,0,.14)"
+  shadow8: "0 4px 8px rgba(0,0,0,.14)"
+  shadow16: "0 8px 16px rgba(0,0,0,.14)"
+  shadow64: "0 0.5px 1px rgba(0,0,0,.24), 0 0 8px rgba(0,0,0,.20)"
+dark-ladder: { step: "n/a — dark mode doubles shadow alpha (~.14→.28) rather than lightening surfaces", hue: held }
+```

package/data/harnesses/code/skills/design/data/elevation/github-primer-sparing-shadow.md

@@ -0,0 +1,19 @@
+---
+id: github-primer-sparing-shadow
+class: a3
+sourced: 2026-07-12
+source: "distilled from primer.style/product/css-utilities/box-shadow and primer.style/foundations/css-utilities/borders"
+license: open
+feel: "developer-tool restraint; flat-and-bordered by default, shadow is the deliberate exception, never the everyday chrome"
+---
+Primer's stated philosophy is to use shadow *sparingly*: small shadows for things that need to feel slightly elevated (pricing cards), medium for editorialized clickable content, and large reserved almost entirely for marketing pages and screenshots — never for ordinary product UI, which relies on `border-default` instead.
+
+```yaml values
+radius: { sm: 4, md: 6, lg: 8 }
+hairline: "border-default, 1px solid — the primary separation mechanic; shadow is the exception, not the rule"
+shadow:
+  small: "subtle lift — pricing cards, attention-getting UI"
+  medium: "diffused, larger — editorialized clickable content"
+  large: "very diffused, used sparingly — marketing content and screenshots only"
+dark-ladder: { step: "+~3L per level (canvas-default #0d1117 → canvas-subtle/overlay)", hue: held }
+```

package/data/harnesses/code/skills/design/data/elevation/ibm-carbon-layer-and-border.md

@@ -0,0 +1,19 @@
+---
+id: ibm-carbon-layer-and-border
+class: a3
+sourced: 2026-07-12
+source: "distilled from v11.carbondesignsystem.com/guidelines/color/implementation and Carbon's elevation guidance"
+license: open
+feel: "flat, rectilinear, enterprise-IBM; depth is a color-and-border swap between layers, almost never a cast shadow"
+---
+Carbon's default posture is nearly shadow-free: each of its layer tokens (`layer-01/02/03`) is paired 1:1 with a matching border token, so nesting a panel inside a panel is a background-color-plus-border swap, not a shadow stack. Shadow is reserved almost exclusively for true overlays — dropdowns and modals. Corners stay square almost everywhere, in keeping with Carbon's rectilinear IBM heritage.
+
+```yaml values
+radius: { sm: 0, md: 0, lg: 2 }
+hairline: "$border-strong-0X paired with $layer-0X — the layer+border pair IS the elevation cue"
+shadow:
+  layer: "none — flat; separation via layer-01/02/03 background swap + paired border"
+  overlay: "0 2px 6px 0 rgba(0,0,0,.30)"
+  modal: "0 8px 16px 0 rgba(0,0,0,.30)"
+dark-ladder: { step: "n/a — discrete named themes (White/g10 light, g90/g100 dark), not a continuous ladder", hue: held }
+```

package/data/harnesses/code/skills/design/data/elevation/linear-dark-surface-ladder.md

@@ -0,0 +1,17 @@
+---
+id: linear-dark-surface-ladder
+class: a3
+sourced: 2026-07-12
+source: "distilled from github.com/voltagent/awesome-design-md — linear.app/DESIGN.md"
+license: reference-only
+feel: "software-craft dark mode; restraint scales — one accent, hairlines, and a shallow surface ladder carry all the hierarchy, no shadows anywhere"
+---
+Linear runs dark-only and resists drop shadows almost entirely; elevation is a **four-step surface-lightness ladder** (surface-1 through surface-4) paired with 1px hairlines of increasing strength (default → strong → tertiary) for nested content. The steps are deliberately small — a whisper of lift, never a spotlight.
+
+```yaml values
+radius: { sm: 6, md: 8, lg: 12 }
+hairline: "1px solid {colors.hairline} #23252a at rest; {hairline-strong} #34343a on focus; {hairline-tertiary} #3e3e44 for nested surfaces"
+shadow:
+  all-levels: "none — drop shadows resisted almost entirely on dark surfaces"
+dark-ladder: { step: "+~2L per level (surface-1 #0f1011 → surface-2 #141516 → surface-3 #18191a → surface-4 #191a1b)", hue: held }
+```

package/data/harnesses/code/skills/design/data/elevation/material-2-key-ambient-dp-ramp.md

@@ -0,0 +1,19 @@
+---
+id: material-2-key-ambient-dp-ramp
+class: a3
+sourced: 2026-07-12
+source: "distilled from m2.material.io/design/environment/elevation.html and m1.material.io/resources/shadows.html"
+license: open
+feel: "classic Google-Material paper-stack; every raise reads as a discrete, physical dp jump"
+---
+The original Material model: a single dp scale (0–24) drives a fixed **key shadow + ambient shadow** pair at every level — sharp directional shadow layered under a soft diffuse one, both pure black at low opacity. No brand tint, no tonal color; the whole hierarchy is shadow-only, which is what later gave way to M3's tonal approach.
+
+```yaml values
+radius: { sm: 2, md: 4, lg: 8 }
+hairline: none
+shadow:
+  1dp: "0 1px 1px 0 rgba(0,0,0,.14), 0 2px 1px -1px rgba(0,0,0,.12), 0 1px 3px 0 rgba(0,0,0,.20)"
+  8dp: "0 8px 10px 1px rgba(0,0,0,.14), 0 3px 14px 2px rgba(0,0,0,.12), 0 5px 5px -3px rgba(0,0,0,.20)"
+  16dp: "0 16px 24px 2px rgba(0,0,0,.14), 0 6px 30px 5px rgba(0,0,0,.12), 0 8px 10px -5px rgba(0,0,0,.20)"
+dark-ladder: { step: "white-overlay 5%→16% across 1dp→24dp (~+1-2% per step)", hue: held }
+```

package/data/harnesses/code/skills/design/data/elevation/material-3-tonal-elevation.md

@@ -0,0 +1,21 @@
+---
+id: material-3-tonal-elevation
+class: a3
+sourced: 2026-07-12
+source: "distilled from m3.material.io/styles/elevation/tokens; shadow figures approximate Material Web's published elevation-level tokens"
+license: open
+feel: "quiet tech-forward calm; depth reads as a warm color shift more than a cast shadow, corners softly rounded"
+---
+Material 3's headline move: elevation is expressed primarily through **tonal surface tint** (a translucent overlay of the primary brand color, stronger at higher levels) with a thin shadow underneath as a secondary cue. No borders — surfaces separate by tone, not line. Best where a single brand hue should visibly "light up" whatever floats highest.
+
+Approximation note: shadow figures approximate Material Web's published elevation-level tokens — check exact rgba/opacity figures against the live source before shipping.
+
+```yaml values
+radius: { sm: 8, md: 12, lg: 16 }
+hairline: none
+shadow:
+  level1: "0px 1px 2px rgba(0,0,0,0.30), 0px 1px 3px 1px rgba(0,0,0,0.15) + {primary-hue tint / ~5% overlay}"
+  level2: "0px 1px 2px rgba(0,0,0,0.30), 0px 2px 6px 2px rgba(0,0,0,0.15) + {primary-hue tint / ~8% overlay}"
+  level3: "0px 4px 8px 3px rgba(0,0,0,0.15), 0px 1px 3px rgba(0,0,0,0.30) + {primary-hue tint / ~11% overlay}"
+dark-ladder: { step: "+~3% primary-tint per level (approx 5/8/11/12/14%)", hue: drift }
+```

package/data/harnesses/code/skills/design/data/elevation/neobrutalist-hard-offset.md

@@ -0,0 +1,19 @@
+---
+id: neobrutalist-hard-offset
+class: a3
+sourced: 2026-07-12
+source: "distilled from neubrutalism.com and community neobrutalism CSS references (community pattern, no single owning org)"
+license: open
+feel: "loud, tactile, intentionally raw; a solid offset shadow with zero blur reads as a physical card lifted straight off the page"
+---
+Neobrutalism inverts the entire elevation vocabulary: no blur, ever. A thick (3–4px) solid black border plus a flat, hard-edged offset shadow in pure black (or a bold flat color) does all the depth work — the shadow is a solid silhouette displaced down-right, not a soft cast. Radius stays at or near zero to keep the "raw" read.
+
+```yaml values
+radius: { sm: 0, md: 0, lg: 4 }
+hairline: "not a hairline — a 3-4px solid black border replaces the border/shadow distinction entirely"
+shadow:
+  sm: "4px 4px 0px #000000"
+  md: "6px 6px 0px #000000"
+  lg: "8px 8px 0px #000000"
+dark-ladder: { step: "n/a — most kits binary-invert black/white rather than laddering surfaces", hue: held }
+```

package/data/harnesses/code/skills/design/data/elevation/neumorphic-soft-dual-shadow.md

@@ -0,0 +1,18 @@
+---
+id: neumorphic-soft-dual-shadow
+class: a3
+sourced: 2026-07-12
+source: "distilled from neumorphism.io and community soft-UI CSS references (community pattern, no single owning org)"
+license: open
+feel: "soft, extruded, monochrome; elements look pressed into or popped out of a background that shares their exact color"
+---
+Neumorphism fakes physical extrusion with a **paired light+dark shadow** on an element whose background exactly matches its parent's — no border, no color contrast, only two offset shadows (one lighter, one darker than the shared base) doing all the modeling. Pressed/inset states simply invert the pair. Contrast-fragile by construction: raising shadow strength enough to pass accessibility checks destroys the soft illusion that is the entire point.
+
+```yaml values
+radius: { sm: 12, md: 16, lg: 24 }
+hairline: "none — a drawn border would break the illusion; edges exist only via the shadow pair"
+shadow:
+  raised: "10px 10px 20px #bebebe, -10px -10px 20px #ffffff"
+  pressed: "inset 6px 6px 12px #bebebe, inset -6px -6px 12px #ffffff"
+dark-ladder: { step: "n/a — dark variant is a manual per-surface retune (e.g. base #2d3239, shadows #23272d / #373d46), not a formula", hue: held }
+```

package/data/harnesses/code/skills/design/data/elevation/notion-warm-minimal-hairline.md

@@ -0,0 +1,17 @@
+---
+id: notion-warm-minimal-hairline
+class: a3
+sourced: 2026-07-12
+source: "distilled from github.com/VoltAgent/awesome-design-md — notion/DESIGN.md"
+license: reference-only
+feel: "warm, paper-like minimalism; content over chrome, separation is almost always a thin line rather than a cast shadow"
+---
+Notion's house rule is explicit: don't apply heavy shadows on flat documentation cards. Separation is carried almost entirely by a single hairline border token reused across nav, cards, and containers; the rare exception is a very soft lift on preview/mockup cards, kept subtle enough not to compete with content.
+
+```yaml values
+radius: { sm: 4, md: 6, lg: 10 }
+hairline: "1px solid {colors.hairline} #EDEEEC — the default separator for nav, cards, and containers; heavy shadows explicitly avoided"
+shadow:
+  rare-lift: "used sparingly, only on mockup/preview cards — e.g. 0 4px 16px rgba(0,0,0,.06)"
+dark-ladder: { step: "+~2-3L per level (approx #191919 → #202020 → #2f2f2f surfaces)", hue: held }
+```

package/data/harnesses/code/skills/design/data/elevation/polaris-elevation-inset-bevel.md

@@ -0,0 +1,21 @@
+---
+id: polaris-elevation-inset-bevel
+class: a3
+sourced: 2026-07-12
+source: "distilled from polaris-react.shopify.com/design/depth/shadow-tokens; radius px approximated, exact figures not published in source"
+license: open
+feel: "commerce-admin friendly; raised surfaces read as physically thick, machined edges rather than flat cards floated on a shadow"
+---
+Polaris splits shadow into three distinct token families used in combination: elevation (the classic cast drop-shadow), inset (an embedded/pressed look), and bevel (a thin inner highlight+shadow edge that gives a raised surface the sense of physical thickness). Combining bevel with elevation is the house move for "this is a real, liftable object."
+
+Approximation note: radius px approximated — exact figures are not published in the source and should be checked before shipping.
+
+```yaml values
+radius: { sm: 4, md: 8, lg: 12 }
+hairline: "implicit — bevel-100 supplies a 1px inner highlight/shadow edge in place of a plain border"
+shadow:
+  elevation-100: "cast shadow, lightest — resting cards"
+  elevation-300: "cast shadow, medium — popovers and overlays"
+  bevel-100: "inset highlight + inset shadow — thick machined edge on raised surfaces"
+dark-ladder: { step: "n/a — Shopify admin ships no official dark theme", hue: held }
+```

package/data/harnesses/code/skills/design/data/elevation/radix-themes-alpha-ring-scale.md

@@ -0,0 +1,19 @@
+---
+id: radix-themes-alpha-ring-scale
+class: a3
+sourced: 2026-07-12
+source: "distilled from radix-ui.com/themes/docs/theme/shadows, /radius, and the shadow.css token source"
+license: open
+feel: "quiet, correct, slightly clinical; a 6-step alpha ramp any accent color can flow through without redoing the shadows"
+---
+Radix builds its shadow ramp entirely from **gray-alpha and black-alpha overlays** rather than fixed opaque colors, so the same six shadow steps stay correct across every accent and every light/dark theme automatically. `shadow-1` is an inset ring that doubles as the hairline for flush, level-0 surfaces.
+
+```yaml values
+radius: { sm: 4, md: 8, lg: 12 }
+hairline: "shadow-1 — inset 0 0 0 1px var(--gray-a5), inset 0 1.5px 2px var(--gray-a2)/var(--black-a2)"
+shadow:
+  shadow-2: "0 0 0 1px var(--gray-a3), 0 0 0 .5px var(--black-a1), 0 1px 1px var(--gray-a2), 0 2px 1px -1px var(--black-a1), 0 1px 3px var(--black-a1)"
+  shadow-3: "0 0 0 1px var(--gray-a3), 0 2px 3px -2px var(--gray-a3), 0 3px 12px -4px var(--black-a2), 0 4px 16px -8px var(--black-a2)"
+  shadow-5: "0 0 0 1px var(--gray-a3), 0 12px 60px var(--black-a3), 0 12px 32px -16px var(--gray-a5)"
+dark-ladder: { step: "n/a — alpha-step ramp (gray-a3 → a5 → a7 in dark), not a lightness ladder", hue: held }
+```

package/data/harnesses/code/skills/design/data/elevation/shadcn-neutral-derived-radius.md

@@ -0,0 +1,19 @@
+---
+id: shadcn-neutral-derived-radius
+class: a3
+sourced: 2026-07-12
+source: "distilled from ui.shadcn.com/docs/theming; shadow values are the Tailwind defaults shadcn themes typically inherit"
+license: open
+feel: "neutral, restrained utility feel; nearly flat, with one hairline border doing most of the separating work"
+---
+shadcn/ui derives its entire radius scale from a single `--radius` variable (multiplied up/down for sm/md/lg/xl), and leans on a plain neutral `border` token rather than shadow for everyday separation — shadow is reserved for popovers/menus. The whole system is intentionally colorless so any brand palette can sit on top of it unchanged.
+
+```yaml values
+radius: { sm: 6, md: 8, lg: 10 }
+hairline: "border token — 1px solid, neutral gray/oklch; default separator for card, input, and popover"
+shadow:
+  sm: "0 1px 2px 0 rgb(0 0 0 / 0.05)"
+  md: "0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1)"
+  popover: "0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1)"
+dark-ladder: { step: "+0.03–0.05 L per surface (oklch background → card)", hue: held }
+```

package/data/harnesses/code/skills/design/data/elevation/stripe-brand-tinted-dual-shadow.md

@@ -0,0 +1,18 @@
+---
+id: stripe-brand-tinted-dual-shadow
+class: a3
+sourced: 2026-07-12
+source: "distilled from designmd.run/blog/stripe-design-system-breakdown and docs.stripe.com/elements/appearance-api"
+license: reference-only
+feel: "warm, trustworthy, faintly atmospheric; shadows carry Stripe's navy-purple brand hue instead of reading as neutral gray"
+---
+Stripe's shadows are two stacked layers where the far/ambient layer is tinted `rgba(50,50,93,...)` — the same blue-gray family as its navy-purple brand palette — with only the near/contact layer left as neutral black. Radius is deliberately conservative (Elements' own default is 4px) — Stripe treats restraint on both shadow and radius as part of feeling "trustworthy."
+
+```yaml values
+radius: { sm: 4, md: 6, lg: 8 }
+hairline: "none specified — separation relies on shadow against a cool-gray canvas (#F6F9FC)"
+shadow:
+  near: "rgba(0,0,0,.1) 0px 1px 2px 0px"
+  card: "rgba(50,50,93,.25) 0px 6px 12px -2px, rgba(0,0,0,.3) 0px 3px 7px -3px — {navy-purple tint / 0.25 alpha on far layer}"
+dark-ladder: { step: "unconfirmed — Stripe's public brand system is light-first with no published dark ramp", hue: held }
+```

package/data/harnesses/code/skills/design/data/elevation/tailwind-default-utility-scale.md

@@ -0,0 +1,19 @@
+---
+id: tailwind-default-utility-scale
+class: a3
+sourced: 2026-07-12
+source: "distilled from tailwindcss.com/docs/box-shadow default theme values"
+license: open
+feel: "the internet's default; a neutral gray shadow ramp so common it reads as 'no design system' unless overridden"
+---
+Tailwind's out-of-the-box shadow scale is the de facto baseline for a huge share of the web: six pure-neutral steps (sm → 2xl) with no brand tint, used independently of its separate border-color utilities rather than paired with them. Its very ubiquity is the point of including it here — it's the "control group" every more opinionated system in this list is reacting against.
+
+```yaml values
+radius: { sm: 4, md: 6, lg: 8 }
+hairline: "border-gray-200 (or theme border color), 1px solid — used independently of the shadow scale, not paired with it"
+shadow:
+  sm: "0 1px 2px 0 rgb(0 0 0 / 0.05)"
+  md: "0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1)"
+  xl: "0 20px 25px -5px rgb(0 0 0 / 0.1), 0 8px 10px -6px rgb(0 0 0 / 0.1)"
+dark-ladder: { step: "n/a — no shipped dark ramp; convention is dark:shadow-none or a manual opacity boost", hue: held }
+```

package/data/harnesses/code/skills/design/data/elevation/vercel-geist-shadow-as-border.md

@@ -0,0 +1,20 @@
+---
+id: vercel-geist-shadow-as-border
+class: a3
+sourced: 2026-07-12
+source: "distilled from vercel.com/geist/materials"
+license: reference-only
+feel: "razor-flat product chrome; the resting 'border' is secretly a zero-blur shadow, softness saved entirely for menus and modals"
+---
+Geist's signature trick: a zero-offset, zero-blur, 1px-spread shadow (`0 0 0 1px rgba(0,0,0,.08)`) stands in for a border at rest, avoiding box-model side effects. As elements go from card → menu → modal, additional shadow layers stack on top of that same base line rather than replacing it, so the "border" never disappears.
+
+```yaml values
+radius: { sm: 6, md: 12, lg: 16 }
+hairline: "shadow-emulated hairline — 0px 0px 0px 1px rgba(0,0,0,.08), zero blur, present at every rest state"
+shadow:
+  base: "0px 0px 0px 1px rgba(0,0,0,.08)"
+  small: "0px 0px 0px 1px rgba(0,0,0,.08), 0px 2px 4px rgba(0,0,0,.04)"
+  menu: "0px 0px 0px 1px rgba(0,0,0,.08), 0px 8px 24px -8px rgba(0,0,0,.12)"
+  modal: "0px 0px 0px 1px rgba(0,0,0,.08), 0px 16px 48px -12px rgba(0,0,0,.18)"
+dark-ladder: { step: "+1 surface swap per level (#000 → #0a0a0a → #111), occasional {blue-hue tint / low-alpha} wash surface", hue: drift }
+```