baldart 3.9.0 → 3.12.0

package/framework/.claude/skills/design-system-init/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: design-system-init
+description: >
+  Bootstrap a component registry / design system on a project that doesn't have
+  one yet. Scaffolds ${paths.design_system}/INDEX.md (component index +
+  Canonical Authority Matrix), tokens-reference.md (extracted from
+  ${paths.global_styles} / Tailwind config), and a components/<Name>.md spec
+  per primitive already present under ${paths.components_primitives}. Then
+  flips features.has_design_system: true in baldart.config.yml. Use when the
+  user says /design-system-init, "crea design system", "bootstrap design
+  system", "inizializza registro componenti", or when configure detected no
+  design-system path and the user wants one. Idempotent — refuses to overwrite
+  an existing registry, supports incremental re-runs to add specs for new
+  components.
+---
+
+# Design-System Init
+
+Scaffold the component registry that the registry-first protocol
+(`framework/agents/design-system-protocol.md`) treats as BLOCKING for every
+UI task. Without a registry, the BLOCKING reads in `ui-design`,
+`frontend-design`, `ui-expert`, and `/design-review` are inert — they have
+nothing to read. This skill creates the missing pieces from the codebase's
+current state so the discipline can kick in immediately.
+
+## Project Context
+
+**Reads from `baldart.config.yml`:** `paths.design_system`,
+`paths.components_primitives`, `paths.components_root`, `paths.global_styles`,
+`paths.ui_guidelines`, `identity.brand_name`, `identity.design_philosophy`,
+`stack.design_system_signals`.
+
+**Gated by features:** none — this skill is the bootstrap mechanism for
+`features.has_design_system`. It refuses to run when a registry is already
+present (`has_design_system: true` AND `paths.design_system/INDEX.md` exists).
+
+**Overlay:** loads `.baldart/overlays/design-system-init.md` if present —
+project-specific opinions (e.g. mandated section order in `components/<Name>.md`,
+brand-voice rules to inject into the scaffolded INDEX, custom token extraction
+recipe for non-Tailwind stacks).
+
+**On missing keys:** ask the user; do not assume defaults. See
+`framework/agents/project-context.md` § 3.
+
+## What This Skill Does
+
+1. **Refusal check.** Reads `baldart.config.yml`.
+   - If `features.has_design_system: true` AND `${paths.design_system}/INDEX.md`
+     exists: stop with "Registry already present at `${paths.design_system}`.
+     To extend it, edit it directly or invoke `ui-design` / `frontend-design`
+     which know how to propose registry additions."
+   - If `has_design_system: true` but the path is missing: warn about the
+     drift, offer to re-scaffold at the configured path.
+2. **Resolve target path.** Default `docs/design-system/`. Ask the user to
+   confirm or override. Use `${paths.design_system}` if already set in config.
+3. **Inventory existing primitives.** Launch the `codebase-architect` agent
+   on `${paths.components_primitives}` (and `${paths.components_root}/shared`
+   when present) to extract: file path, exported component name, props
+   signature, variants (if discoverable), accessibility hooks used, tokens
+   referenced.
+4. **Extract token contract.** Read `${paths.global_styles}` for CSS custom
+   properties; read `tailwind.config.{ts,js,mjs,cjs}` for theme extensions;
+   read any `tokens.{json,ts,js}` or Style Dictionary output. Group by
+   category (color, spacing, shadow, radius, typography, motion).
+5. **Scaffold the files** under the target path:
+   - `INDEX.md` — component index, Canonical Authority Matrix (empty
+     visual/behavioral/composition columns to be filled by the team),
+     pointer to `tokens-reference.md` and `components/`.
+   - `tokens-reference.md` — extracted tokens, grouped, with a note that
+     `tokens-reference.md` is the SSOT and hardcoded literals are forbidden.
+   - `components/<Name>.md` — one file per discovered primitive, generated
+     from `scripts/component-spec.template.md`. Fill the fields the inventory
+     could resolve; leave clearly-marked TODO sections for the rest.
+   - `patterns/.gitkeep` — empty dir for future pattern docs.
+6. **Update config.** Set `features.has_design_system: true` and
+   `paths.design_system: <target>` in `baldart.config.yml`. Use the same
+   YAML write path as `configure` (preserve user values, never clobber
+   unrelated keys).
+7. **Print next-steps.** Authority Matrix to fill, specs to review, suggested
+   first follow-up (`/design-review` on a key route to validate the registry).
+
+## Workflow
+
+1. **Refusal check** — see § What This Skill Does step 1.
+
+2. **Target path prompt:**
+   ```
+   Scaffold the registry at: docs/design-system/  [Y/n/custom]
+   ```
+
+3. **Inventory** — launch `codebase-architect` with this prompt skeleton:
+   > Enumerate the UI primitives under `${paths.components_primitives}`. For
+   > each: file path, exported name, props type (best-effort from TS/JSDoc),
+   > variants (e.g. `variant="primary|ghost"`), accessibility attributes
+   > (aria-*, role, focus management), design tokens referenced (CSS vars,
+   > Tailwind classes that map to tokens). Report as a JSON-friendly list.
+
+4. **Token extraction** — for each detected source:
+   - CSS custom properties: parse `--*: ...;` declarations and group by prefix.
+   - Tailwind theme: parse `theme.extend.{colors,spacing,boxShadow,borderRadius,fontFamily,transitionDuration,transitionTimingFunction}`.
+   - Style Dictionary / tokens file: parse the JSON tree.
+   - If nothing is found, leave a TODO section in `tokens-reference.md`
+     pointing the team to populate it before relying on the SSOT contract.
+
+5. **Generate files** using the template in
+   `scripts/component-spec.template.md` for each component, and the inline
+   templates below for INDEX and tokens-reference.
+
+6. **Persist config:**
+   ```yaml
+   paths:
+     design_system: docs/design-system   # or user-chosen
+   features:
+     has_design_system: true
+   ```
+
+7. **Output** — short status block (see Output Contract).
+
+## Output Contract
+
+```
+Design-system bootstrap:
+  ✓ Created docs/design-system/INDEX.md
+  ✓ Created docs/design-system/tokens-reference.md (32 tokens extracted)
+  ✓ Generated 17 component specs under docs/design-system/components/
+  ⚠ 4 components had no resolvable props — TODO sections marked
+Config updated: baldart.config.yml has_design_system=true, paths.design_system=docs/design-system
+Next: review INDEX.md Authority Matrix, fill TODO sections, run /design-review on a key route.
+```
+
+## INDEX.md template
+
+The generated `INDEX.md` has this skeleton (concrete values substituted from
+the inventory):
+
+```markdown
+# ${identity.brand_name} Design System
+
+Single source of truth for visual, behavioral, and compositional decisions on
+this product. Read this BEFORE producing or reviewing any UI. The registry-first
+protocol is defined in `framework/agents/design-system-protocol.md`.
+
+## Token Contract
+
+Tokens live in [`tokens-reference.md`](tokens-reference.md). Hardcoded color /
+shadow / radius / spacing / motion values are FORBIDDEN when these tokens
+cover the use case.
+
+## Component Index
+
+| Component | File | Purpose | Spec |
+|-----------|------|---------|------|
+| Button    | ${paths.components_primitives}/Button.tsx | … | [components/Button.md](components/Button.md) |
+| …         | …    | …       | …    |
+
+## Canonical Authority Matrix
+
+| Dimension          | Authority                       | Override path |
+|--------------------|---------------------------------|---------------|
+| Color / shadow / radius / spacing | `tokens-reference.md` | Propose a new token + ADR |
+| Props / variants / a11y           | per-component `components/<Name>.md` | Update the spec in the same change |
+| Composition (patterns)            | `patterns/<topic>.md`            | New pattern doc + INDEX entry |
+
+## Quick MUST Rules
+
+- Reuse from the Component Index before inventing a new primitive.
+- Consume tokens via the project's mechanism (CSS vars / Tailwind theme /
+  theme provider) — never hardcode literals.
+- Any new primitive ships with its `components/<Name>.md` spec in the same
+  change.
+- Authority Matrix violations require a registry update, not a local override.
+
+## How to Extend
+
+- New primitive → create `components/<Name>.md` (the template lives at
+  `.framework/framework/.claude/skills/design-system-init/scripts/component-spec.template.md`
+  after `npx baldart add` — copy it, fill it in, drop under
+  `${paths.design_system}/components/`),
+  implement under `${paths.components_primitives}`, add the row above.
+- New pattern → create `patterns/<topic>.md`, link from this INDEX.
+- New token → add to `tokens-reference.md`, propagate to the project's
+  token mechanism.
+```
+
+## tokens-reference.md template
+
+```markdown
+# Token Reference
+
+Single source of truth for design tokens. Values below are extracted from
+${paths.global_styles} and tailwind config (when present). DO NOT hardcode
+literals that duplicate these tokens in components.
+
+## Color
+- `--color-primary: <value>` — …
+- …
+
+## Spacing
+- `--space-1: <value>` — …
+- …
+
+## Shadow
+- …
+
+## Radius
+- …
+
+## Typography
+- …
+
+## Motion
+- duration: …
+- easing: …
+```
+
+## Notes
+
+- The skill never modifies source components — its only side effects are
+  creating files under `${paths.design_system}` and updating
+  `baldart.config.yml`.
+- Generated specs are starting points, not final docs. The expected next move
+  is human review + filling TODO sections + a `/design-review` pass.
+- Idempotent: re-running detects existing specs and only generates files for
+  new primitives (and updates the Component Index table).
+
+## See Also
+
+- `framework/agents/design-system-protocol.md` — the protocol this skill bootstraps.
+- `framework/agents/project-context.md` — config + overlay contract.
+- `framework/.claude/skills/ui-design/SKILL.md` — primary consumer (reads
+  the registry BLOCKING).
+- `scripts/component-spec.template.md` — per-component spec template.

package/framework/.claude/skills/design-system-init/scripts/component-spec.template.md

@@ -0,0 +1,79 @@
+# {{ComponentName}}
+
+> Per-component spec. Authoritative for props, variants, accessibility, and
+> anti-patterns. Visual authority (color/shadow/radius/spacing) belongs to
+> [`../tokens-reference.md`](../tokens-reference.md).
+
+## Source
+
+- File: `{{file_path}}`
+- Exported as: `{{exported_name}}`
+- Used by: <!-- TODO: list 2-3 key consumers, e.g. pages or compound components -->
+
+## Purpose
+
+<!-- One-sentence statement of what this primitive is for and when to reach
+for it instead of an alternative. -->
+
+## Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+{{props_table}}
+
+<!-- TODO: if props were not auto-resolvable, fill the table from the source
+file. Keep types accurate — drift here is the most common bug. -->
+
+## Variants
+
+{{variants_section}}
+
+<!-- TODO: enumerate every variant the component exposes. For each, describe
+when to use it. Example:
+- `variant="primary"` — primary CTA, one per surface
+- `variant="ghost"` — secondary actions in dense layouts
+- `size="sm" | "md" | "lg"` — bind to spacing tokens
+-->
+
+## Tokens consumed
+
+{{tokens_section}}
+
+<!-- TODO: list the tokens this component reads from tokens-reference.md.
+Color, spacing, shadow, radius, motion. If you find hardcoded literals in
+the source, that's a registry violation — fix at the source. -->
+
+## Accessibility
+
+- Keyboard: <!-- focus order, shortcuts, escape behavior -->
+- ARIA: <!-- roles, labels, descriptions, live regions -->
+- Touch target: ≥ 44×44px when interactive
+- Color contrast: text ≥ 4.5:1, UI ≥ 3:1 (WCAG 2.1 AA)
+- Reduced motion: respects `prefers-reduced-motion`
+
+## Composition
+
+<!-- How this primitive composes with others. Patterns it appears in.
+Cross-link to patterns/ docs when applicable. -->
+
+## Anti-patterns
+
+<!-- Common misuses that should be rejected in code review. Examples:
+- Wrapping in a div with absolute positioning to fake a variant — add a
+  variant to the registry instead.
+- Hardcoding a custom color via inline style — add a token and consume it.
+-->
+
+## MUST rules
+
+<!-- HIGH-severity rules the code-reviewer agent enforces. Examples:
+- MUST consume `--color-primary` for background; never hardcode.
+- MUST set `aria-label` when icon-only.
+-->
+
+## Changelog
+
+<!-- Track breaking changes to the spec. Bump version when removing a variant
+or changing a default. -->
+
+- {{today}} — Spec scaffolded by `/design-system-init`.

package/framework/.claude/skills/frontend-design/SKILL.md

@@ -50,6 +50,11 @@ Remember: Claude is capable of extraordinary creative work. Don't hold back, sho
 
 ## MANDATORY Pre-Work Read (project design-system override)
 
+The registry-first cascade below is the consumer view of the SSOT in
+[`framework/agents/design-system-protocol.md`](../../../agents/design-system-protocol.md).
+When the cascade rules diverge between this file and the protocol module,
+the protocol module wins.
+
 When operating inside a repo that ships a design-system SSOT, the generic
 creative guidance above is BLOCKED by the project design-system until the
 reads below are complete. MANDATORY pre-work reads (skipping any of them is
@@ -72,6 +77,125 @@ Within those bounds, creative choices (typography nuance, composition, motion in
 
 ---
 
+## Performance Gates (Core Web Vitals 2026)
+
+Production-grade frontend is not just "looks good" — it ships within the CWV
+thresholds. Every page / component / route MUST be designed against these
+budgets, not retrofitted after Lighthouse complains.
+
+### Thresholds (p75, CrUX dataset)
+
+| Metric | Good | Poor | What it measures |
+|---|---|---|---|
+| **LCP** | ≤ 2.5s | > 4.0s | Largest Contentful Paint — usually the hero image or H1 |
+| **INP** | ≤ 200ms | > 500ms | Interaction to Next Paint — replaced FID in Mar 2024 |
+| **CLS** | ≤ 0.1 | > 0.25 | Cumulative Layout Shift |
+| TTFB | ≤ 0.8s | > 1.8s | Subset of LCP (~40% of budget) |
+| FCP | ≤ 1.8s | > 3.0s | Diagnostic only |
+
+A page passes CWV when all three (LCP/INP/CLS) are *good* at p75. INP is the
+hardest of the three on JS-heavy apps and the most commonly failed (~43% of
+sites globally).
+
+### LCP image: the only correct pattern
+
+```html
+<!-- in <head> — preload + fetchpriority for the hero -->
+<link rel="preload" as="image"
+      href="/hero.avif"
+      imagesrcset="/hero-800.avif 800w, /hero-1600.avif 1600w"
+      imagesizes="100vw"
+      fetchpriority="high">
+
+<!-- in body — picture with AVIF/WebP/fallback + explicit dimensions -->
+<picture>
+  <source srcset="/hero.avif" type="image/avif">
+  <source srcset="/hero.webp" type="image/webp">
+  <img src="/hero.jpg" alt="..."
+       fetchpriority="high"
+       width="1600" height="900">
+</picture>
+```
+
+**Never** apply `loading="lazy"` to the LCP image. **Never** render the LCP
+image via client-side JS after hydration — server-render it or preload it.
+
+### INP fixes
+
+- Break any task > 50ms into `await scheduler.yield()` chunks (Chrome 129+;
+  fallback `await new Promise(r => setTimeout(r, 0))`).
+- Debounce input handlers to one frame (~16ms) when they trigger expensive
+  recomputes. Throttle scroll/resize to `requestAnimationFrame`.
+- Move CPU-bound work (parsing, transforming, encoding) off the main thread
+  with Web Workers when latency matters.
+- Avoid `setInterval` polling for data — use SWR / React Query / TanStack
+  Query with stale-while-revalidate.
+
+### CLS budget — zero unexpected shift
+
+- Every `<img>`, `<iframe>`, `<video>` declares `width` + `height` or
+  `aspect-ratio` CSS.
+- Web fonts: `font-display: optional` (no FOIT/FOUT shift, accept fallback
+  on first load) OR `size-adjust` + matching `ascent-override` /
+  `descent-override` / `line-gap-override` to produce a metric-compatible
+  fallback font.
+- Skeleton screens mirror the real layout dimensions exactly — a skeleton
+  that's the wrong height *causes* CLS instead of preventing it.
+- Inserted UI (banners, cookie notices, ads) must reserve space upfront via
+  `min-height` — never push existing content down post-paint.
+
+## Modern CSS (2025–2026)
+
+Default to platform features instead of JS shims:
+
+- **Container queries** (`@container` + `container-type: inline-size`) —
+  default for any component that lives in variable-width contexts (sidebar,
+  grid cell, modal). Component decides its own breakpoint, independent of
+  viewport. Use viewport-based `@media` only for app-shell-level layout.
+- **`:has()`** — collapse `useState` that exists *only for styling*
+  (e.g. label color reacting to input invalid state). Never put business
+  logic into `:has()` — only visual reactions to DOM state.
+- **View Transitions API** — `document.startViewTransition()` for SPA
+  navigation and `view-transition-name` for shared-element morphs. See
+  `motion-design/reference/accessibility-and-modern-apis.md` for the full
+  pattern.
+- **Subgrid** — children align to the parent grid without re-declaring
+  tracks. Fixes the long-standing "card content alignment across rows"
+  problem.
+- **Logical properties** — `margin-inline-start` / `padding-block` instead
+  of `margin-left` / `padding-top` whenever the project might add RTL or
+  vertical-writing-mode locales. Free i18n with zero overhead.
+- **`color-mix()`** — derive hover / focus / disabled states from semantic
+  tokens without inventing new tokens
+  (`color-mix(in oklch, var(--color-action-primary) 90%, black)`).
+- **`@scope`** — scope CSS to a subtree without selector specificity wars or
+  CSS-in-JS. Useful when migrating off CSS Modules / styled-components.
+
+## Form quality (always-on requirements)
+
+These apply to every form, every project — they are not "nice to have":
+
+- `<label>` associated to input via `htmlFor` / `id` (never wrap-only — fails
+  some screen readers).
+- `autocomplete=` filled for every personal-data field
+  (`email | tel | given-name | family-name | street-address | postal-code |
+  cc-number | one-time-code` …). Required by WCAG 2.1 SC 1.3.5.
+- Validation **on blur**, not on every keystroke. Re-validate on submit.
+- Error messages are **actionable** ("Email manca @ — esempio:
+  nome@dominio.it"), never generic ("Invalid input").
+- `aria-invalid` + `aria-describedby` linking the input to its error
+  element. Error element has `role="alert"` only when it appears
+  dynamically.
+- `inputMode=` set when it differs from `type` (e.g. `type="text"
+  inputMode="numeric"` for SMS codes — keeps the field text-shaped but
+  triggers the numeric keypad).
+- Paste handling normalizes whitespace and format BEFORE validating
+  (cc-number without spaces, tel without separators).
+- Submit button disabled only **after** a failed attempt — never blocked
+  pre-emptively; users should be allowed to try and receive feedback.
+
+---
+
 ## Prototipi Standalone e Demo
 
 Quando il task richiede un prototipo HTML interattivo, demo animata, slide deck, mockup iOS/app, o design exploration **NON legato alla codebase Next.js** (nessun contesto `src/app/`), invocare la skill `huashu-design` in aggiunta o al posto di questa skill. Essa fornisce:

package/framework/.claude/skills/lsp-bootstrap/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: lsp-bootstrap
+description: >
+  Install, verify, and document the LSP symbol-search layer for this project.
+  Detects languages (TypeScript, Python, Go, Rust, Ruby), installs the matching
+  language servers (npm devDep where possible, system command otherwise),
+  verifies binaries are reachable, and writes lsp.installed_servers to
+  baldart.config.yml. Use when the user says /lsp-bootstrap, "install LSP",
+  "set up symbol search", or after enabling features.has_lsp_layer for the
+  first time. Idempotent — re-running on an already-configured project
+  re-verifies and reports drift.
+---
+
+# LSP Bootstrap
+
+Set up the LSP (Language Server Protocol) layer that lets agents and skills
+search by symbol instead of by string. Without this layer, code search burns
+context on textual collisions; with it, references resolve to the same symbol
+**before** Claude reads any file.
+
+## Project Context
+
+**Reads from `baldart.config.yml`:** `features.has_lsp_layer`, `lsp.installed_servers`, `lsp.auto_verify`.
+**Gated by features:** `features.has_lsp_layer` — this skill refuses to run when the flag is `false`, prompting the user to flip it via `npx baldart configure` first.
+**Overlay:** loads `.baldart/overlays/lsp-bootstrap.md` if present — project-specific install commands (e.g. a system-managed pyright via uv, a non-standard gopls path).
+**On missing keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.
+
+## What This Skill Does
+
+1. Reads `baldart.config.yml` and confirms `features.has_lsp_layer: true`.
+2. Probes the cwd via `src/utils/lsp-adapters/` to detect which languages are
+   present (markers: `tsconfig.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`,
+   `Gemfile`, plus heuristic fallbacks).
+3. For each detected language:
+   - **npm-dev** adapters (TypeScript, Python via pyright): runs `npm install
+     --save-dev <pkg>` with user confirmation.
+   - **system** adapters (Go gopls, Rust rust-analyzer, Ruby ruby-lsp): prints
+     the install command for the user to run in a separate terminal. Does NOT
+     execute system-level installs automatically.
+4. Verifies each binary is reachable (`<binary> --version`).
+5. Updates `lsp.installed_servers` in `baldart.config.yml` with the verified
+   set. System-mode servers are recorded even if not yet reachable (the user
+   may have a pending install) — `baldart doctor` will flag the mismatch.
+6. Prints a summary table and points the user to
+   `framework/agents/code-search-protocol.md` for runtime behavior.
+
+## Workflow
+
+1. **Refusal check.** If `features.has_lsp_layer: false` (or missing):
+   ```
+   This project hasn't opted in to the LSP layer yet.
+   Run `npx baldart configure` and answer YES to "Enable LSP symbol-search layer?"
+   then re-run /lsp-bootstrap.
+   ```
+   Stop here. Do not proceed.
+
+2. **Probe.** Call the BALDART installer (internally `src/utils/lsp-installer.js`):
+   ```
+   node -e 'const L=require("./.framework/src/utils/lsp-installer"); console.log(JSON.stringify(new L().recommend(),null,2))'
+   ```
+   Show the detected languages with their `installMode`.
+
+3. **Confirm per server.** For each recommended server, ask the user. Skip the
+   ones already in `lsp.installed_servers` unless they fail verify.
+
+4. **Install.** Run the appropriate `installCommand()`. Capture failures into a
+   "Skipped" bucket — never abort the whole skill on one failure.
+
+5. **Verify.** For each installed server, call its `verifyCommand()`. Mark the
+   results.
+
+6. **Persist.** Update `baldart.config.yml`:
+   ```yaml
+   lsp:
+     installed_servers: [typescript, python]
+     auto_verify: true
+   ```
+
+7. **Output.** A compact one-line status, in the project's `identity.language`
+   from `baldart.config.yml` (English default). Matches the brevity of
+   `/cont` rather than its specific Italian phrasing.
+
+## Output Contract
+
+A single short status block — never a multi-page report. Format:
+
+```
+LSP bootstrap:
+  ✓ typescript-language-server (npm devDep, verified)
+  ✓ pyright (npm devDep, verified)
+  ⚠ gopls — run `go install golang.org/x/tools/gopls@latest`, then `baldart doctor`
+  · ruby — not detected (no Gemfile)
+Config updated: baldart.config.yml lsp.installed_servers = [typescript, python, go]
+Next: codebase-architect will now prefer LSP find-references over Grep for symbols.
+```
+
+## Notes
+
+- This skill never edits source code or installs binaries that aren't language
+  servers — its only side effect is `npm install --save-dev <lsp-package>` and a
+  YAML write to `baldart.config.yml`.
+- For Claude Code users: in addition to the binaries, you may need to load a
+  code-intelligence plugin (`/plugin` in Claude Code). That step is documented
+  in the printed output when applicable, but the skill does NOT manage Claude
+  Code plugins directly.
+- Re-run safely. The skill diffs the current `lsp.installed_servers` against
+  recommended + verified, so additions / removals / repairs are all idempotent.
+
+## See Also
+
+- `framework/agents/code-search-protocol.md` — runtime fallback rules
+- `src/utils/lsp-adapters/` — per-language install/verify recipes
+- `src/commands/configure.js` — same install flow when first enabling the flag

package/framework/.claude/skills/motion-design/reference/accessibility-and-modern-apis.md

@@ -0,0 +1,114 @@
+# Accessibility & Modern Motion APIs
+
+## `prefers-reduced-motion` — collapse, don't disable
+
+```css
+:root {
+  --motion-duration-fast: 150ms;
+  --motion-duration-base: 250ms;
+  --motion-duration-slow: 400ms;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  :root {
+    --motion-duration-fast: 0.01ms;
+    --motion-duration-base: 0.01ms;
+    --motion-duration-slow: 0.01ms;
+  }
+}
+```
+
+**Why 0.01ms, not 0?** Some Safari/WebKit versions skip the `transitionend`
+event entirely when duration is exactly `0` — state machines that wait on
+that event hang. `0.01ms` is functionally instant but keeps the event
+pipeline intact.
+
+**What stays vs. what goes** when reduced-motion is requested:
+
+- KEEP: opacity fades < 200ms (no vestibular impact), color cross-fades,
+  scale changes < 5%, subtle elevation changes.
+- COLLAPSE: translate / parallax / scale > 5% / rotate / skew / 3D
+  perspective / spring overshoot — anything with apparent motion across the
+  viewport.
+
+**Don't** apply a global `* { animation: none !important }` reset — that
+breaks loading spinners, focus indicators, and any animation that
+*communicates state*. Token-level collapse is the right primitive.
+
+## View Transitions API
+
+For same-document navigation (SPA route change, list ↔ detail, tab switch):
+
+```js
+function navigate(to) {
+  if (!document.startViewTransition) {
+    applyDom(to); // graceful fallback — no transition
+    return;
+  }
+  document.startViewTransition(() => applyDom(to));
+}
+```
+
+For shared-element morph (hero image survives the route change):
+
+```css
+.hero-image {
+  view-transition-name: hero-image; /* unique per shared element */
+}
+
+::view-transition-old(hero-image),
+::view-transition-new(hero-image) {
+  animation-duration: var(--motion-duration-base);
+  animation-timing-function: cubic-bezier(0.2, 0, 0, 1); /* emphasized */
+}
+```
+
+For cross-document transitions (MPA, Chrome 126+, behind opt-in CSS):
+
+```css
+@view-transition { navigation: auto; }
+```
+
+**Accessibility**: View Transitions automatically respect
+`prefers-reduced-motion` when the page exposes the reduced-motion media
+query — no extra wiring needed beyond the token collapse above.
+
+**Use it for**: navigation, list ↔ detail morphs, sort / filter reorders,
+modal hero reveal. **Don't use it for**: per-frame interactive feedback
+(hover, focus, drag) — those need direct CSS / spring animations.
+
+## Spring vs. timing function — when to pick which
+
+| Use case | Pick |
+|---|---|
+| Direct manipulation (drag release, swipe, pull-to-refresh) | Spring |
+| Page / view transition | Cubic-bezier (deterministic, easy to choreograph) |
+| Acknowledgment / tap feedback | Cubic-bezier (short, predictable) |
+| Interruptible animation that should "settle naturally" | Spring |
+| Stagger choreography | Cubic-bezier (timeline easier to reason about) |
+
+**Spring rule of thumb**: stiffness 250–350 + damping 18–24 = "standard
+feel". Higher stiffness = snappier; lower damping = more oscillation. Cap
+total settle time at 600ms — beyond that the user perceives "lag", not
+physicality.
+
+## Choreography budget
+
+- Single-element transition: 100–500ms (see `timing-easing-tables.md`).
+- Stagger of multiple children: each child delay 30–50ms, **total budget
+  ≤ 600ms** (faster on dense lists — cap at 400ms for >10 items).
+- Page-load sequence: hero ≤ 250ms, secondary content stagger ≤ 400ms
+  total. Beyond that the user is staring at incomplete UI.
+
+## Animation that communicates state — never collapse these
+
+Reduced-motion does NOT mean *no feedback*. Always preserve:
+
+- Focus ring appearance (instant is fine — but visible).
+- Loading indicators (a static spinner or skeleton is still feedback).
+- Validation error appearance (color + icon — duration can be 0).
+- Toast / notification appearance (fade-in opacity ≤ 200ms is acceptable
+  under reduced-motion).
+
+Stripping these leaves users without feedback that an action registered —
+worse than the animation they tried to avoid.

package/framework/.claude/skills/new/SKILL.md

@@ -236,7 +236,7 @@ For each card, execute these phases in order:
    - If NOT `DONE` → HALT: log in `## Issues & Flags` and ask the user: "Card <CARD-ID> depends on <DEP-ID> which is `<status>`. Proceed anyway, or wait?" Do not start implementation until the user responds explicitly.
    - If `DONE` → continue.
 3. Update `${paths.references_dir}/project-status.md` Active Code Context (skip when the file does not exist in the project).
-4. Invoke the **codebase-architect** agent (MUST per AGENTS.md) to understand the relevant codebase area, existing patterns, and architecture before any implementation.
+4. Invoke the **codebase-architect** agent (MUST per AGENTS.md) to understand the relevant codebase area, existing patterns, and architecture before any implementation. When `features.has_lsp_layer: true`, the architect uses LSP find-references for any identifier-shaped lookups inside the card (transitive via `agents/code-search-protocol.md`).
 4b. **Plan-auditor grounding check** — invoke the **plan-auditor** agent in QUICK mode with this prompt:
    ```
    Quick grounding check only (not a full audit). Verify this backlog card's requirements are grounded in the actual codebase.