devrites 1.19.0

package/pack/.claude/skills/devrites-frontend-craft/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: devrites-frontend-craft
+description: Implement frontend at senior designer-engineer quality — every state covered, anti-AI-slop, WCAG 2.2 AA. Use when the user says "build the UI", "ship-quality frontend", "design system", "a11y", or `/rite-build` detects UI. Not for polishing a built feature or design exploration.
+user-invocable: false
+---
+
+# devrites-frontend-craft — UI like a senior designer-engineer
+
+Build UI that belongs in *this* product, handles every state, and avoids generic-AI
+tells. Integrated into the feature slice, not a separate design project.
+
+## 1. Foundation discovery
+Framework, routing, components, tokens, CSS methodology, icon set, existing UI patterns,
+and any `PRODUCT.md` / `DESIGN.md` / design docs. Use the project's system — don't
+import a new one. (Detail: `reference/design-references.md`.)
+- **Load the design brief + references the spec gathered** —
+  `.devrites/work/<slug>/design-brief.md` (the UX/UI contract from `devrites-ux-shape` — the
+  primary build target) plus `references.md` + the saved files in `references/`
+  (screenshots, Figma, video, links). When present they are the **build target**: match the
+  direction, layout, spacing, states, and behavior they show (pull Figma context if a Figma
+  integration is available) — extract type / spacing / color-roles / layout / component
+  behavior to it deliberately, don't eyeball it
+  (`reference/design-references.md` — *Building to a supplied reference*). A reference that
+  conflicts with the design system is a question for the user, not a silent choice.
+
+## Reuse first — search before you build
+Before creating any new component, style, token, icon, hook, util, or helper, search the
+project for an existing one and **reuse → extend → build new** — see
+[reference/reuse-first.md](reference/reuse-first.md) for the search targets, the AHA
+caveat, and the per-slice reuse record.
+
+## 2. Register detection
+- **Brand surface** — landing, marketing, portfolio, campaign: expressive type, larger
+  scale contrast, motion welcome.
+- **Product surface** — dashboard, admin, settings, app UI, tools: system fonts
+  legitimate, one family often enough, fixed rem scale, tight ratio, density is fine.
+
+## 3. Shape before code — build to the brief ([reference/shape.md](reference/shape.md))
+The feature's **`design-brief.md`** is your target — `/rite-spec` shaped it up front
+(`devrites-ux-shape`): design direction, key states, interaction model, the visual-direction
+probe. **Read it first and refine it for this slice's surface; don't re-derive the design
+from scratch.** Confirm the slice covers the brief's states for this surface (default,
+loading, empty, error, success, disabled, long-content), its information hierarchy +
+primary action, responsive behavior, a11y, and interaction model. **If a UI slice has no
+`design-brief.md`** (a spec written before shaping), shape it now via `devrites-ux-shape`
+before coding. **Ask before coding if the visual direction or UX flow is still ambiguous.**
+
+## 4. Build ([reference/craft.md](reference/craft.md))
+- Compose from existing components/tokens (reuse-first, above) before reaching for new code.
+- Build the **smallest UI** the current slice needs — don't pre-build screens.
+- Don't add a second component library or icon set without asking.
+- Cover the states you shaped, not just the happy path.
+- **Reduce cognitive load** — no wall of options: group, mark the recommended choice, use
+  progressive disclosure.
+- **Copy in the product's voice**; shift tone by moment — success brief, error empathetic
+  + actionable, loading reassuring, destructive serious. Never humor in errors. Empty
+  states say *why* + the next action.
+- **First-use**: get the user to first value fast; onboarding proves worth, it doesn't
+  teach the whole product.
+
+## 5. Verify & record (meet the bar)
+- Hit the [2026 quality bar](reference/quality-standards.md): Core Web Vitals
+  (LCP ≤2.5s / INP ≤200ms / CLS ≤0.1), WCAG 2.2 AA (keyboard, visible focus, contrast,
+  ≥24px targets / 44px touch, no drag-only), responsive at 320/768/1024/1440 — and run
+  its verification gate (no console errors, no axe violations, all states).
+- Verify in the browser (`devrites-browser-proof`) — screenshots opened and described,
+  console clean, responsive + keyboard checked.
+- **Every interactive element has an asserting test at the right level** — each field,
+  checkbox, radio, select, toggle, button, and actionable link gets a unit/component test for
+  what it *does* (validation, toggle, options, enabled/disabled, handler); critical journeys
+  get one E2E. Browser proof shows it renders; the asserting test proves it works. No element
+  ships unverified — `rules/testing.md` "Completeness"; inventory in `test-plan.md`.
+- **Append build-time refinements** to `.devrites/work/<slug>/design-brief.md` — the
+  design-contract artifact `devrites-ux-shape` produced at spec; this skill refines it per
+  slice (the "Build-time refinements" section), it does not own or recreate it. `/rite-polish`
+  reads it in its UI phase and `/rite-seal` includes it in its artifact read list. Record
+  runtime evidence in `browser-evidence.md`.
+
+## Fullstack (frontend + backend in one feature)
+When the feature needs both sides, follow [reference/fullstack.md](reference/fullstack.md):
+define the **API/data contract first** (`devrites-api-interface`), slice **vertically**
+through the layers (DB → service → API → UI) one capability at a time, apply the
+engineering rules to the backend and this craft to the frontend, map every contract error
+to a real UI state, and **prove both layers** (contract tests + browser proof).
+
+## Anti-AI-slop (banned defaults unless the project's system uses them)
+Purple/blue gradients · gradient text · glassmorphism by default · cards-in-cards ·
+identical card grids everywhere · rounded-square icon tile above every heading ·
+gray-on-color text · hero-metric cliché · decorative bounce/elastic easing · random
+Inter-for-everything · modal-first thinking. Full list + rationale:
+`rite-polish/reference/anti-ai-slop.md`.
+
+## Default vs departure
+Preserve the existing identity (default, ~90%). Reject it only on an explicit signal (a
+design doc naming *this* surface as the failure, or the user asking to rebuild). If
+unsure, you're in default mode — the cost of a wrong departure is unrecoverable.

package/pack/.claude/skills/devrites-frontend-craft/reference/craft.md

@@ -0,0 +1,59 @@
+# Craft — build the UI
+
+With the shape decided and the system discovered, build the smallest correct UI for the
+slice. Quality is in the details and the states, not in novelty. If the brief names a
+supplied Figma / screenshot / image as the build target, extract to it first — type,
+spacing, color roles, layout, component behavior (`design-references.md` — *Building to a
+supplied reference*).
+
+## Build order
+1. **Structure** — semantic markup that expresses the hierarchy from the shape note.
+2. **Compose from the system** — use existing shared components and tokens. If a needed
+   component doesn't exist, build it in the project's style (don't import a new library
+   without asking).
+3. **State coverage** — wire up every state you shaped (loading/empty/error/success/
+   disabled/long-content), not just the populated happy path.
+4. **Interaction** — feedback on every action; focus management; keyboard support;
+   sensible defaults (Enter submits, Esc closes, etc.).
+5. **Responsive** — verify the reflow at the target viewports.
+
+## Use the system, don't fight it
+- Tokens for spacing/color/type — never hard-code a value a token covers.
+- Match the nearest neighbor's patterns for forms, buttons, menus, toasts.
+- One icon set (the project's). Consistent sizing/alignment.
+
+## Smallest UI for the slice
+Build what *this* slice needs. Don't scaffold future screens, settings, or variations
+"while you're here" — that's scope creep and it dodges its own review.
+
+## Quality tells (the difference between fine and crafted)
+- The primary action is unmistakable.
+- Empty states teach the next step; error states offer recovery.
+- Spacing reads as deliberate; alignment holds at every breakpoint.
+- Copy is in the product's voice, specific, and short.
+- No console noise; no layout shift.
+
+## Avoid the slop
+Don't reach for the banned defaults (`rite-polish/reference/anti-ai-slop.md`). If the
+project genuinely uses one, follow the project — consistency wins.
+
+## Record
+Append slice build-time refinements → `design-brief.md` (the brief `devrites-ux-shape`
+produced at spec; refine it, don't recreate it). Then verify in the browser
+(`devrites-browser-proof`) and record evidence before claiming the UI works.
+
+## NEVER (craft)
+
+- Never hard-code a value a token covers (color, spacing, type, radius,
+  shadow). If the token is missing, ask before adding one.
+- Never import a new component library or icon set without asking — the
+  project has one already.
+- Never ship only the populated state. The full state set (loading / empty
+  / error / success / disabled / long-content) is the minimum.
+- Never animate as decoration. Motion is feedback or a focus shift, not
+  jewellery.
+- Never use raw `#000` / `#fff`, viewport queries for component-internal
+  reflows, or raw `z-index` numbers outside the semantic scale
+  (`quality-standards.md` — Numerical bar).
+- Never write `console.log` or leave commented-out code in shipped UI.
+- Never scaffold "future screens" — out of slice scope.

package/pack/.claude/skills/devrites-frontend-craft/reference/design-references.md

@@ -0,0 +1,116 @@
+# Design references — discover, don't impose
+
+What to read in the project before designing, and how register changes the rules.
+
+## Discover these
+| Thing | Where |
+|---|---|
+| Design docs | `PRODUCT.md`, `DESIGN.md`, `docs/design/*`, Storybook, READMEs |
+| Tokens | `tailwind.config.*`, CSS custom properties, `theme.*`, token files |
+| Shared components | components/ui dir, design-system package, what neighbors import |
+| Type | families, weights, the size scale actually in use |
+| Spacing | the spacing scale / tokens in use |
+| Color roles | semantic names (primary/surface/muted/danger), not raw hex |
+| Icons | the one icon library already imported |
+| Patterns | how existing buttons/menus/dialogs/forms/toasts behave |
+| Neighbors | the closest existing feature — match its flow shape |
+
+## Register-specific rules
+**Product surface** (dashboard/admin/app):
+- System fonts are legitimate (`-apple-system, BlinkMacSystemFont, "Segoe UI",
+  system-ui, sans-serif`); Inter is a fine default for a reason.
+- One family usually carries headings, body, labels, data.
+- Fixed rem scale (not fluid `clamp()` headings); tighter ratio (1.125–1.2).
+- Density is a feature; tables can run dense; prose still ~65–75ch.
+
+**Brand surface** (landing/marketing/campaign):
+- More expressive type and larger scale contrast are appropriate.
+- Display/body pairing can be worth it; motion is welcome (still purposeful).
+
+## The rule
+Match what exists. A new token, font, or component library is a decision the user makes,
+not a default you reach for. When the system is ambiguous, ask — don't invent the
+project's intent. When a project `DESIGN.md` is present it is the **rolled-up design
+memory** earlier features sealed (`../../rite-ship/reference/design-memory.md`) — the
+inherited system to build *to*, ahead of re-deriving direction from scratch.
+
+## Scene-sentence — commit before choosing theme / direction
+Dark vs light is not a default, and neither is "playful", "serious", or "editorial".
+Before picking any of those, write **one sentence** that fixes the physical scene:
+
+> *who* uses this, *where*, under *what ambient light / device*, in *what mood*.
+
+If that sentence doesn't make the answer feel inevitable, it isn't concrete enough —
+add detail until it does. Then design *for that scene*, not for the category.
+
+Examples:
+- ❌ "An observability dashboard" → forces nothing; "dark blue tech" is the reflex.
+- ✅ "An on-call SRE glancing at incident severity at 2am on a 27-inch monitor in a
+  dim room" → forces dark, high-contrast severity colours, scannable rows.
+- ❌ "A finance app" → forces nothing; "navy + gold" is the reflex.
+- ✅ "A self-employed designer reconciling last month's invoices at a kitchen table
+  in afternoon light, on a 13-inch laptop" → forces a calm light theme with one
+  committed accent for the running total.
+
+Run the sentence, not the category. When the user supplies the brief, paraphrase the
+sentence back to them as confirmation before designing.
+
+## Named anchor references — steer with specifics, not adjectives
+After the scene sentence, name **2-3 specific anchors** the surface should feel like —
+real products, brands, or objects ("Linear's command bar", "a Teenage Engineering device",
+"the Stripe dashboard"), **not adjectives** ("modern", "clean", "premium"). Adjectives are
+unfalsifiable; a named anchor is checkable — you can hold the built UI next to it and ask
+"does it read like that?" Anchors steer *direction*, not pixel-copying: take the relevant
+trait (density, type voice, restraint), not the literal layout, and never the parts that
+clash with this project's register or design system. The supplied `references/` files are
+themselves anchors — name what trait each contributes. Record the anchors in
+`design-brief.md`'s **Design direction** so build, polish, and seal share the same target.
+
+## Building to a supplied reference (Figma / screenshot / image)
+When the spec gathered a Figma frame, screenshot, or image and the brief names it the
+**build target** (not just inspiration), the reference *is* the art direction and the code
+is the implementation layer. This is the build-time counterpart to the shape-time
+visual-direction probe (`../../devrites-ux-shape/reference/visual-direction-probe.md`):
+the probe *chose* a lane; here you *match* the chosen target.
+
+**Extract before you write** — read the reference deliberately, don't eyeball it:
+- **Type** — family, the size steps actually used, weights, line-height, letter-spacing,
+  the heading→body ratio. Map each to the project's type scale (or flag a missing step).
+- **Spacing & rhythm** — padding, gaps, section spacing; infer the underlying step and
+  round to the project's 4 pt scale rather than hard-coding the measured pixel.
+- **Color** — the roles in play (surface / text / accent / border), not raw hex; bind to
+  existing tokens, propose a token only where one is genuinely missing.
+- **Layout & hierarchy** — grid, what's seen 1st / 2nd / 3rd, the density and motion the
+  reference implies (cross-check against the brief's Calibration).
+- **Component behavior** — the states the reference shows (and the ones it can't: hover,
+  focus, loading, empty, error — design those from the brief, the reference won't have them).
+
+Then implement to match, in the project's system:
+- **Match the target, fill the gaps from the brief.** A static reference shows one state;
+  ship the full state set (`quality-standards.md` — Focus & states).
+- **A reference that conflicts with the design system is a question for the user**, not a
+  silent override — name the conflict (token, font, spacing, a second system) and ask.
+- **Don't crop a multi-section reference into pieces** to "extract" a section — work from
+  the cleanest whole frame; if a region is unreadable, ask for a clearer asset rather than
+  guessing.
+- **Fidelity is faithfulness, not pixel-tracing** — carry the reference's hierarchy, rhythm,
+  and voice; never copy a layout that clashes with this project's register or a11y floor.
+- Record what the reference dictated (and any deviation + why) in the brief's
+  **Build-time refinements**, so polish and seal check the build against the same target.
+
+## NEVER (design references)
+
+- Never default to **Inter / DM Sans / Plus Jakarta / Fraunces / Newsreader**
+  because they're the "tasteful 2024 default". Use what the project uses.
+- Never default to a **purple/blue gradient** when the project has a brand
+  palette.
+- Never pick a tone (playful / serious / corporate / hand-drawn) that
+  contradicts the surface's **register** — brand vs product
+  (`devrites-frontend-craft/SKILL.md` §2).
+- Never add a second design system to "modernize" without explicit user
+  approval. One design system per project; consistency beats local taste.
+- Never invent a token. If a needed color/spacing/type slot doesn't exist,
+  ask whether to add it to the system.
+- Never use a screenshot of another product as a target without checking
+  the *register* matches. A landing page reference is not a product UI
+  reference.

package/pack/.claude/skills/devrites-frontend-craft/reference/fullstack.md

@@ -0,0 +1,45 @@
+# Fullstack work (frontend + backend together)
+
+Most UI features also need backend. Don't build the two sides blind to each other, and
+don't build "all backend, then all frontend" — that hides integration risk until the end.
+
+## Contract first
+Define the **API / data contract** before either side codes against it — shape, field
+types + units, status codes, **error bodies**, pagination, idempotency. Use
+`devrites-api-interface`; doubt it with `devrites-doubt` before standing it. With the
+contract fixed:
+- the **backend** slice can land against it (consumer stubbed),
+- the **frontend** slice can build against a mock or the real contract.
+Neither side blocks the other, and the seam stays stable.
+
+## Slice vertically through the layers
+Each slice cuts **one capability** end-to-end — data/model → service → API → UI — and
+leaves a **working, demoable path**. "Create item" is a slice (persist + endpoint +
+minimal form); "all the models" is not. Order by dependency; the first slice is the
+thinnest end-to-end path so integration surprises surface early and cheap.
+
+## Apply the right discipline to each layer
+- **Backend part** → the engineering rules: validate untrusted input at the boundary,
+  authz on every sensitive action, parameterized queries, fail closed, no secrets in
+  logs (`security.md`); fail-fast errors with meaningful messages (`error-handling.md`);
+  measure-first performance (no N+1) (`performance.md`).
+- **Frontend part** → frontend craft: shape (all states), the design system, and the
+  2026 [quality-standards](quality-standards.md) (CWV, WCAG 2.2, responsive, motion).
+- Map the API's error/edge responses to **real UI states** — every error the contract can
+  return needs a handled, helpful UI state, not a blank screen.
+
+## Placement spans both sides
+The investigation's placement analysis covers **where the backend logic lives** *and*
+**where the UI component lives**, plus the contract that joins them — so each side is
+correctly placed, not bolted on.
+
+## Prove BOTH layers
+A fullstack slice is proven only when both sides have evidence:
+- backend/contract: tests for the endpoint + its error/edge cases (and a real
+  request/response observation);
+- frontend: browser proof (states exercised, console clean, responsive, a11y).
+If only one side is proven, the slice is **not** done.
+
+## Keep them in sync
+A change to the contract after both sides exist is a **Spec Drift Guard** event — it
+affects FE and BE together. Stop, record it, re-plan the contract, then update both sides.

package/pack/.claude/skills/devrites-frontend-craft/reference/quality-standards.md

@@ -0,0 +1,215 @@
+# Frontend quality standards (2026)
+
+The measurable bar UI work is held to. Project conventions win where they're stricter;
+these are the floor, not the ceiling.
+
+## Performance — Core Web Vitals (field/p75 targets)
+- **LCP** (Largest Contentful Paint) ≤ **2.5 s**
+- **INP** (Interaction to Next Paint — the current responsiveness metric, replaced FID)
+  ≤ **200 ms**
+- **CLS** (Cumulative Layout Shift) ≤ **0.1**
+- Keep an interactive page's shipped JS lean (a budget around **≤400 KB gzipped** is a
+  good default); lazy-load below-the-fold and heavy/optional code; minimize hydration;
+  size and reserve space for images/media to avoid layout shift.
+
+## Accessibility — WCAG 2.2 AA
+- **Semantic HTML first** — real `<button>`/`<nav>`/`<label>`/headings; ARIA only to fill
+  gaps semantics can't.
+- **Keyboard**: every interactive element operable by keyboard; logical tab order; **focus
+  visible** with ≥ **3:1** contrast against its background (never remove the outline
+  without an equal replacement).
+- **Contrast**: text ≥ **4.5:1** (≥ 3:1 for large text and UI/graphics).
+- **Target size**: ≥ **24×24** CSS px (WCAG 2.2 AA, SC 2.5.8); prefer **44×44** for primary
+  touch targets.
+- **No drag-only** interactions — provide a single-pointer alternative (SC 2.5.7).
+- Labels/names on all controls; errors announced; respects `prefers-reduced-motion`.
+- **Test** with keyboard, a screen reader, and an automated checker (e.g. axe) — early.
+
+## Motion
+- Purposeful only; UI feedback ~≤200 ms, transitions ~≤500 ms. Never animate to mask slow
+  loading. Honor `prefers-reduced-motion` (reduce/remove non-essential motion).
+
+## Responsive
+- Fluid layouts; no fixed widths that break. Verify at **320 / 768 / 1024 / 1440** px; no
+  horizontal scroll; survives **200% text zoom**.
+
+## Design system
+- Use the project's **tokens** (spacing/type/color roles) — never hard-code a value a
+  token covers. Compose from existing components; one icon set.
+
+## Numerical bar (enforceable specifics)
+
+These are the hard numbers that move "good UI" from opinion to checkable.
+Project tokens win when stricter; these are the floor.
+
+### Color
+- **OKLCH-only** for new tokens — perceptually uniform, predictable lightness
+  steps across hues. Stop reaching for HSL; the lightness lies.
+  - Example: `oklch(0.62 0.18 264)` for a saturated primary.
+- **Never `#000` / `#fff`** as raw values. Pure black/white are too harsh and
+  too clinical; use a near-black (`oklch(0.18 0 0)`) and near-white
+  (`oklch(0.98 0 0)`) or the project's surface tokens.
+- Contrast follows WCAG 2.2 — text ≥ 4.5:1, UI/graphics ≥ 3:1. Verify
+  against the *rendered* background, not the theoretical one.
+- **Tint neutrals toward the brand hue** — pure-grey neutrals look sterile.
+  Nudge every grey 0.005–0.01 chroma toward the brand colour — invisible at
+  a glance, but the surface stops feeling generic.
+
+#### Color commitment — pick the strategy before the palette
+Decide *how committed* the surface is to colour before opening the picker.
+Four positions on a single axis; pick one, then design within it:
+
+| Strategy | Rough coverage | Use for |
+|---|---|---|
+| **Restrained** | tinted neutrals + 1 accent ≤ ~10% of the surface | Most product UI; brand surfaces that want to look quiet. |
+| **Committed** | one saturated colour carries 30–60% of the surface | Brand pages with a strong identity; product feature surfaces that need a hero colour. |
+| **Multi-role** | 3–4 named colour roles, each used deliberately | Brand campaigns; product data-viz with distinct meanings. |
+| **Saturated** | the surface *is* the colour — full-bleed colour ground | Brand heroes, campaign pages, splash moments. |
+
+Two corollaries:
+- The "one accent ≤ ~10%" rule belongs to **Restrained only.** Committed /
+  Multi-role / Saturated exceed it deliberately. Don't collapse every
+  surface back to Restrained by reflex.
+- *Register* (brand vs product) doesn't pick the strategy by itself — brand
+  surfaces aren't always Saturated, product surfaces aren't always
+  Restrained. Pick from the scene, not the category.
+
+### Calibration — density & motion
+Colour commitment fixes *how much colour*; two more axes fix *how much space* and
+*how much movement*. Set one position on each — from the **scene sentence**, the same
+way colour is picked — and carry both in `design-brief.md` so the build targets a
+calibration instead of re-deciding it per slice.
+
+**Density** — information per viewport; drives which spacing steps dominate:
+
+| Position | Feels like | Spacing steps that dominate | Use for |
+|---|---|---|---|
+| **Airy** | gallery / calm / room to breathe | `32 / 48 / 64 / 80 / 96` | brand pages, onboarding, focus moments, low-data surfaces |
+| **Balanced** | most product UI | `16 / 20 / 24 / 32` | dashboards, forms, settings — the default |
+| **Dense** | cockpit / data-rich / power tool | `4 / 8 / 12 / 16` | tables, monitors, terminals, pro tools lived in all day |
+
+**Motion** — how much the surface moves; drives which motion classes (table below) are in play:
+
+| Position | Feels like | Motion classes in play | Use for |
+|---|---|---|---|
+| **Minimal** | crisp, almost still | Instant + State | dense tools, regulated/trust surfaces, reduced-motion-leaning |
+| **Standard** | responsive, purposeful | Instant + State + Layout | most product + brand UI — the default |
+| **Expressive** | choreographed, scroll-aware | + Entrance, deliberate sequencing | brand heroes, launch/campaign moments, story scroll |
+
+Corollaries (same shape as colour commitment):
+- Pick from the **scene sentence**, not the category — "an on-call SRE at 2am" → Dense +
+  Minimal; "a launch hero in afternoon light" → Airy + Expressive. Register doesn't decide
+  it by itself.
+- `prefers-reduced-motion` overrides Motion **downward at runtime** regardless of position —
+  an Expressive surface still ships a Minimal path.
+- The position is a target, not a straitjacket: a surface may break density locally for
+  emphasis — name the exception in the brief, don't let the whole page drift off it.
+
+### Spacing
+- **4pt base scale** (`4 / 8 / 12 / 16 / 20 / 24 / 32 / 40 / 48 / 64 / 80 /
+  96`). Project tokens may use a multiplier; never hardcode in-between
+  values.
+- Inline spacing rhythms in multiples of 4 px. Optical alignments may need a
+  1 – 2 px nudge — record the *why* in a comment.
+
+### Typography scale
+- **Brand surfaces**: fluid `clamp()` headings (e.g.,
+  `clamp(2rem, 1rem + 3vw, 3.5rem)`). Display/body pairing OK.
+- **Product surfaces**: **fixed rem scale** (1.125 – 1.2 ratio). One family
+  usually carries headings, body, labels, data.
+- Body line-height ~1.5; headings ~1.1 – 1.25. Prose width ~ 65–75 ch.
+
+### Motion
+| Class | Duration | Use |
+|---|---|---|
+| Instant | 100 – 150 ms | Hover/press, tooltip enter, color shifts |
+| State | 200 – 300 ms | Toggle, focus ring, dropdown |
+| Layout | 300 – 500 ms | Modal/drawer enter, route transitions |
+| Entrance | 500 – 800 ms | Page entrance, hero animation |
+
+- **Exit at ~75 % of enter.** A 300 ms enter pairs with a 225 ms exit.
+- **Bounce / elastic easing banned** unless the project's design system
+  explicitly uses it.
+- Honor `prefers-reduced-motion` — reduce or remove non-essential motion
+  entirely.
+
+### Dark mode (three-axis compensation)
+A token-flip dark mode is sterile. When the project ships dark, compensate
+three axes from light:
+- **Line-height** `+0.05 – 0.10` (text breathes more on dark surfaces).
+- **Letter-spacing** `+0.01 – 0.02 em` (perceived spacing tightens on dark).
+- **Weight** `+1 step` for very small or low-contrast text.
+
+If the project has dark tokens already, follow them. If not and dark is in
+scope, propose the compensation rather than ship a flat invert.
+
+### Focus & states (8 required)
+Every interactive element ships **8 visual/interaction states**:
+`default`, `hover`, `active`, `focus-visible`, `disabled`, `loading`,
+`selected`, and an error/invalid surface when relevant.
+- `:focus-visible` ring: **2 – 3 px**, **≥ 3:1** contrast against the
+  background, **offset 2 px** so the focus is unambiguous on dense layouts.
+
+### Container queries vs viewport queries
+- **Component breakpoints** — use **container queries** (`@container`). The
+  same card adapts to its column whether the viewport is 320 or 1920.
+- **Page-level layout** — use viewport queries
+  (`@media (min-width: ...)`) for sidebar collapses, header reflows.
+- Mixing the two is normal; using only one is usually a code smell.
+
+### Semantic z-index scale
+Pick a scale per surface role; never use raw `z-index: 9999`. Suggested
+floor:
+
+| Role | z |
+|---|---|
+| Base content | `auto` / `0` |
+| Sticky header | `50` |
+| Dropdown / popover | `100` |
+| Drawer / sheet | `200` |
+| Modal | `300` |
+| Toast | `400` |
+| System dialog / debug overlay | `500` |
+
+### Materiality (elevation & surface)
+Depth is earned, not defaulted. Reach **down** this ladder in order; stop at the first
+rung that carries the structure.
+- **Hairline first.** A **1 px border / divider** (a hairline in a near-neutral token)
+  defines structure before any shadow does. Borders separate; shadows lift. Most "cards"
+  want a hairline, not elevation.
+- **Elevation is a token scale, not an ad-hoc value.** When a surface genuinely lifts
+  (menu, popover, dragged item), use a **small shadow set from the design system** with one
+  consistent light source — never a one-off `box-shadow`. The elevation step and the
+  semantic z-index role move together.
+- **Texture needs contrast.** Grain / noise / pattern earns its place only when it reads
+  against the surface. Invisible texture is bytes with no signal — drop it.
+- **Asset-led material.** Rich material (photographic grain, real product imagery,
+  generated art) comes from a **real raster / generated asset**, not an SVG/CSS
+  approximation of one. Don't fake a photo with gradients; ship the asset or use a flat
+  token.
+- **No decorative glass.** `backdrop-filter: blur(...)` is for a fixed/sticky surface over
+  moving content (a sticky header, a sheet over scroll), never a default panel look
+  (`rite-polish/reference/anti-ai-slop.md`).
+
+### NEVER (UI numerical bar)
+- Never ship a pure `#000` or `#fff` raw value.
+- Never hard-code a spacing value the 4 pt scale or project tokens cover.
+- Never use bounce/elastic easing without an explicit design-system reason.
+- Never animate an exit at 100 % of enter duration (feels uncontrolled).
+- Never use raw `z-index` numbers outside the semantic scale.
+- Never use viewport queries for component-internal reflows when the
+  component is reused at different widths.
+- Never ship dark mode as a flat token invert (compensate three axes).
+- Never reach for a shadow where a 1 px hairline carries the structure.
+- Never invent a one-off `box-shadow` outside the elevation token set.
+- Never ship texture / grain that doesn't read against its surface.
+
+## Verification gate (a UI slice isn't done until all pass)
+- [ ] Renders with **no console errors/warnings**
+- [ ] **Keyboard**: tab through reaches everything; focus visible; Esc/Enter behave
+- [ ] **Screen reader** conveys content + structure
+- [ ] **All states**: default / loading / empty / error / success / disabled
+- [ ] **Responsive** at 320 / 768 / 1024 / 1440; no overflow; zoom-safe
+- [ ] **No accessibility violations** (axe or equivalent)
+- [ ] Meets the **CWV budget** above (measure, don't assume)
+- [ ] Aligned to the **design system** (tokens, components, type, spacing)

package/pack/.claude/skills/devrites-frontend-craft/reference/reuse-first.md

@@ -0,0 +1,59 @@
+# Reuse first — frontend application
+
+Frontend-specific application of the canonical reuse rule in
+[`.claude/rules/coding-style.md`](../../../rules/coding-style.md#reuse-before-you-write)
+(and the slightly longer treatment in `rules/patterns.md`). Same principle —
+**reuse → extend → build new**, with the AHA caveat. This file walks it through for
+components, styles, tokens, icons, hooks, utils, and helpers in a UI feature.
+
+Consistency comes from **one source of truth**. Before creating any new component, style,
+token, icon, hook, util, or helper for the feature, **search the project** for an
+existing one that fits. Reuse it. Don't duplicate.
+
+This applies to UI **and** non-UI code: utilities, helpers, types, validators, schemas,
+formatters, hooks, query helpers — anything that might already exist.
+
+## The decision (in order)
+1. **Search first.** Use a code-intelligence index if available — codebase-memory-mcp first,
+   cross-checked with codegraph + graphify, else standard methods (LSP / Read/Grep/Glob); see
+   `../../../rules/tooling.md` — to find
+   similar definitions; fall back to grep/glob over `components/`, design tokens, hooks/,
+   utils/, lib/. Look for things doing the *same job*, not just the same name.
+2. **Exact fit → REUSE.** Compose / import the existing thing. No copy, no fork.
+3. **Close fit → EXTEND.** Add a variant/prop/option that the existing component or util
+   can carry without distortion. Adding a prop to a button is fine; adding ten props that
+   each branch the internals is not.
+4. **No fit → BUILD NEW**, in the project's idiom. If a similar need is likely to recur,
+   propose adding it to the shared system (component library / utils module). If it's
+   truly one-off, build it locally — don't pre-abstract.
+
+## When to *avoid* reuse (the AHA caveat)
+Reuse is good; **forcing** it isn't. **Avoid Hasty Abstractions**: if making the existing
+thing fit means warping its API or breaking its contract for one caller, **don't**.
+Duplication is cheaper than the wrong abstraction. Build a sibling component/util and let
+a real pattern emerge from two or three callers before consolidating.
+
+## Record the decision (per slice)
+On each slice, note what was reused / extended / created new — so the seal can see the
+consistency story and reviewers can spot silent duplication.
+
+```
+Existing reused: <Button, useToast, formatCents>
+Extended: <Card — added variant="elevated">
+Created new: <ExportProgress (no prior equivalent; propose for shared lib)>
+```
+
+## Anti-patterns to name
+- Silently re-implementing an existing component / hook / util because it was easier than
+  finding it. Search first.
+- Copy-pasting a component from `components/` into the feature folder. That's a fork.
+- Adding a second icon set / second toast library / second date util because the existing
+  one didn't quite fit — almost always extend the existing or ask first.
+- Forcing reuse via 8 boolean props that branch the internals — that's an abstraction
+  collapsing under its own weight. Split it.
+
+## Search hints
+- **UI**: `components/ui/`, design-system package imports neighboring features use,
+  `tokens.*` / Tailwind config / theme files, icon barrel files, layout primitives.
+- **Non-UI**: `lib/`, `utils/`, `helpers/`, `services/`, `validators/`, `schemas/`,
+  `hooks/`, language stdlib equivalents.

package/pack/.claude/skills/devrites-frontend-craft/reference/shape.md

@@ -0,0 +1,60 @@
+# Shape before code
+
+Decide what the UI *is* before how it looks. Aesthetics follow structure; structure
+follows the user's goal. Skipping this is how you get pretty UI that doesn't work.
+
+**The feature-level shape already exists.** `/rite-spec` ran `devrites-ux-shape` and wrote
+`design-brief.md` (design direction, key states, interaction model). In `/rite-build` this
+is a **per-slice refinement of that brief for the surface you're about to code** — confirm
+the answers below against the brief and fill any slice-specific gaps; don't re-derive the
+design. **Only shape from scratch here** when a UI slice has no `design-brief.md` (a spec
+written before shaping) — then run `devrites-ux-shape` first, or answer these and write the
+brief inline.
+
+## Answer these before writing markup
+1. **User goal** — what is the user here to accomplish? One sentence.
+2. **Primary action** — the single most important thing on this surface. It must be
+   visually obvious. Everything else is secondary.
+3. **Information hierarchy** — what must be seen first, second, third. Rank content;
+   the layout expresses the ranking.
+4. **States** — design all of them, not just the happy path:
+   - default / populated
+   - loading (initial + subsequent)
+   - empty (with a clear next action — welcoming, not a dead end)
+   - error (what happened + how to recover)
+   - success
+   - disabled / read-only / no-permission
+   - long content / overflow / many items
+5. **Responsive** — how it reflows from small (375) to large (1280). What collapses,
+   stacks, hides, or scrolls.
+6. **Accessibility** — focus order, labels, contrast, keyboard operability, semantics.
+7. **Interaction model** — what's inline vs. navigated vs. (rarely) a modal; optimistic
+   vs. pending; how feedback is given.
+
+## Ask when ambiguous
+If the visual direction or the UX flow isn't determined by the existing system + the
+spec, ask the user (show 2–3 concrete options) before building. Guessing a flow is
+expensive to undo once coded.
+
+## Output
+The answers live in the feature's `design-brief.md` (shaped at spec by `devrites-ux-shape`).
+In build, append any slice-specific refinement to its **Build-time refinements** section;
+if you shaped from scratch (no brief existed), write the brief now per
+`../../devrites-ux-shape/reference/brief-template.md`. This drives the build and the polish
+checklist.
+
+## NEVER (shape)
+
+- Never start coding markup without naming the **primary action** for the
+  surface.
+- Never design only the populated/happy state. Empty / loading / error /
+  disabled / long-content are not optional.
+- Never decide the visual direction by personal taste when the project has
+  an existing system. Discover first (`design-references.md`).
+- Never invent a new flow when a neighboring feature already has one — match
+  the neighbor, then deviate only with a recorded reason.
+- Never paper over an ambiguous spec with a "reasonable guess". Ask the user
+  with 2 – 3 concrete options.
+- Never name a state for the *technical* condition (`isLoadingTrue`) when
+  the *user-facing* name (`Loading your invoices…`) tells the user what's
+  happening.