devrites 5.10.1 → 5.11.0

package/pack/generated/devin/skills/devrites-frontend-craft/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: devrites-frontend-craft
+description: Build accessible production UI and all states during /rite-build. Use for frontend or design-system implementation; not for polish or design exploration.
+triggers:
+  - model
+---
+
+# 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 (roles: target / constraint / inspiration — detail: `reference/design-references.md`).
+
+## 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
+Read the discovery and register contract in
+[`reference/design-references.md`](reference/design-references.md#discover-these).
+Completion: the surface is classified as brand or product and its existing tokens,
+components, patterns, and nearest neighbor are named before design choices begin.
+
+## 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, interaction model, and proof targets. **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, Browser
+  chrome (themed selection/caret/scrollbar/focus — not UA defaults), and run
+  its verification gate (no console errors, no axe violations, all states).
+- Run the **visual convergence loop** in the browser (using `devrites-browser-proof`; deltas land in its Visual Verdict scorecard): render the
+  slice's named states/viewports/input modes, open the screenshots, compare them with the
+  brief + target R-ids, record material deltas, fix, and re-render until none remain. A
+  detector/checklist is a floor, not the visual verdict.
+- **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: [`testing.md`](../devrites-lib/reference/standards/testing.md) "Completeness"; inventory in `test-plan.md`.
+- **Append build-time refinements** to `design-brief.md` (§3); `/rite-polish` Phase 4 and
+  `/rite-seal`'s frontend reviewer read it. 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
+The banned-defaults list and the countable mechanical pre-flight live in
+[`anti-ai-slop.md`](../rite-polish/reference/anti-ai-slop.md) (canonical owner): run both at build and polish
+time — a slop pattern in the slice is a polish finding.
+
+## 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/generated/devin/skills/devrites-frontend-craft/reference/craft.md

@@ -0,0 +1,63 @@
+# 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 (full set per NEVER below).
+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.
+
+## Technical floors (cheap now, expensive to retrofit)
+- Full-height = `min-height: 100dvh`, never `h-screen` / `100vh`.
+- Columns via CSS Grid, not flex + `calc(%)` math.
+- Continuous input (mouse, scroll, drag) never re-renders per frame: refs / motion
+  values / CSS, not component state.
+- **Real-imagery ladder**: project asset → generated asset → seeded stock placeholder →
+  labeled empty slot + tell the user. Never divs pretending to be a screenshot; real SVG
+  logos, not text wordmarks.
+
+## 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 (and passes the Copy & data realism
+  check in [`anti-ai-slop.md`](../../rite-polish/reference/anti-ai-slop.md)).
+- No console noise; no layout shift.
+
+## Record
+Record: append refinements to `design-brief.md` and run the render-compare-fix loop per
+SKILL.md §5 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
+  (see `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/generated/devin/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 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 reasonable fallback only when the project has no established family.
+- 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 proved and closed during Polish
+(`../../rite-polish/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.
+
+## 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 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 (see `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
+  ([`SKILL.md`](../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/generated/devin/skills/devrites-frontend-craft/reference/fullstack.md

@@ -0,0 +1,46 @@
+# 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` (it owns the doubt gate). 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; fail-fast errors with meaningful messages; measure-first performance (no N+1)
+  (lib standards: [`security.md`](../../devrites-lib/reference/standards/security.md), [`error-handling.md`](../../devrites-lib/reference/standards/error-handling.md), [`performance.md`](../../devrites-lib/reference/standards/performance.md) under
+  `devrites-lib/reference/standards/`).
+- **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/generated/devin/skills/devrites-frontend-craft/reference/quality-standards.md

@@ -0,0 +1,294 @@
+# 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 (class table below). Never animate to mask slow loading; honor
+  `prefers-reduced-motion`.
+
+## Responsive
+- Fluid layouts; no fixed widths that break. Verify at **320 / 768 / 1024 / 1440** px;
+  preserve content and controls at **200% text zoom** and **400% browser zoom from
+  1280 px** (320 CSS px). This is the canonical viewport set for UI evidence: [`ui.md`](../../rite-polish/reference/ui.md), [`browser-proof-checklist.md`](../../devrites-lib/reference/standards/browser-proof-checklist.md), and
+  [`browser-polish-evidence.md`](../../rite-polish/reference/browser-polish-evidence.md) cite it rather than restating it.
+- **No page-level horizontal scroll anywhere in 320–1920.** Sweep between checkpoints:
+  a `1fr` track given a 1024 px image can overflow at 900 px. Fix intrinsic sizing
+  (for example `minmax(0, 1fr)`), wrapping and media constraints; root clipping is
+  not a reflow fix. Clip decoration only, never text, controls or focus indicators.
+  A necessary two-dimensional table/map may scroll inside a named, bounded,
+  keyboard-accessible region; surrounding headings, text and pagination must reflow.
+  Record and test that exception. **Failing case:** a localized CTA disappears behind
+  `overflow-x: clip`; the missing scrollbar does not prove accessible reflow.
+- **`dvh`, not `vh`**, for full-height surfaces (`min-height: 100dvh`, never `h-screen` /
+  `100vh`: mobile address bars break them). A hero fits the *initial* viewport: headline
+  ≤2 lines, primary CTA above the fold.
+
+## 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.
+
+### Consistency locks (one per surface)
+Lock these in `design-brief.md` and hold them page-wide: mid-scroll drift ("a different
+website by section 7") is a tell: **one declared color strategy and role budget**
+(§ Color commitment; no unbriefed accent appearing later), **one radius scale**, **one theme** (light or dark, not both).
+
+## 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. Procedure: pair every
+  `color` declaration with its computed background; a button whose text and fill sit
+  within 5% lightness and 0.05 chroma of each other fails regardless of the palette.
+- **Restrained accent, capped:** one accent covers **≤5% of the viewport** at rest
+  (3–5 placements above the fold). Accent-filled panels fail this strategy; another strategy requires the explicit brief and role budgets below.
+- **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.
+- **Alpha is a smell:** heavy translucency usually means an incomplete palette.
+  Define explicit overlay/hover tokens; transparency is for focus rings and scrims.
+- **Every colored surface token ships its `on-` pair** (`primary`/`on-primary`,
+  `destructive`/`on-destructive`, …) so contrast is designed in, not patched after.
+
+#### 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 ≤5% of the viewport at rest | 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 ≤5% accent cap belongs to **Restrained only**. For Committed / Multi-role /
+  Saturated, the brief must name the strategy, purpose, tokens and measured coverage
+  budget per role and viewport. No blanket waiver: an unbudgeted colored panel fails.
+  Preserve distinct success/warning/error meanings; semantic states do not authorize decorative accents. Check rendered captures against the declared budgets.
+- *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.
+- Adjacent hierarchy levels differ by **≥1.5× in at least one signal** (size, weight,
+  or color); verified under a blur(8px) squint — a flat field means the hierarchy is
+  decorative. **Failing case:** label and helper text differ only by 0.05rem.
+- All-caps display text sets **line-height ≥1.0**; tighter collides cap heights.
+- **Hero font-scale attribution:** a hero headline that wraps past its planned lines at
+  the target viewport is a font-size error first — fix the scale, don't shorten the
+  copy. **Failing case:** a four-line hero headline "fixed" by cutting the sentence.
+- Display ceiling: `clamp()` max ≤ ~6rem: larger is shouting. Display
+  letter-spacing floor **≥ −0.04em**; tighter and the letters touch.
+- `text-wrap: balance` on h1-h3; `text-wrap: pretty` on long prose.
+
+### 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. Reduced means fewer and gentler, never zero feedback.
+- **Loading feedback appears by ~200 ms**: skeletons/spinners replace stillness
+  after that threshold; below it, feedback flicker reads as jank. Hover intents
+  may delay 150–300 ms; focus indication never fades in — the ring is instant.
+
+### Forms
+- Inputs match button height (44 px floor); visual targets under 24 px expand
+  their hit area with a pseudo-element to the 44 px minimum.
+- Helper/error text reserves **`min-height: 1lh`** so messages never shift layout.
+- Border width is pinned across states (state changes recolor, never resize).
+- Disabled is visible through **three channels**: muted color, `not-allowed`
+  cursor, and blocked interaction — color alone fails.
+- Mobile inputs set **≥16 px** font (smaller triggers iOS zoom-on-focus).
+- Numeric/data columns set **`font-variant-numeric: tabular-nums`**; columns of
+  figures align or the surface reads broken.
+
+### 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, 3 conditional)
+Every interactive element ships **8 visual/interaction states**:
+`default`, `hover`, `active`, `focus-visible`, `disabled`, `loading`,
+`selected`, and an error/invalid surface (required wherever the element can be invalid). Data surfaces add the
+conditional three whenever the data can produce them: **partial** (a missing field
+renders an explicit em-dash/placeholder — never `null` or `0`), **conflict** (a
+concurrent-edit/version-mismatch surface), and **offline/unreachable** (stale-data
+banner with retry, not a silently cached render). **Failing case:** a row with a
+missing value renders `0` or blank and the review reads it as real data.
+- `:focus-visible` ring: **2 - 3 px**, **≥ 3:1** contrast against the
+  background, **offset 2 px** so the focus is unambiguous on dense layouts.
+
+### Browser chrome
+User-agent defaults are unfinished craft. Per UI slice, theme or explicitly
+decline (briefed) each of: `::selection` (token colors, not UA blue),
+`caret-color` on editable fields, scrollbar styling or a recorded
+`scrollbar-width` decision, and the project focus-ring token in place of the
+unstyled UA outline. **Failing case:** layout, type, and the 8+3 states pass
+while the UA blue focus ring and default selection remain.
+
+### 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
+  ([`anti-ai-slop.md`](../../rite-polish/reference/anti-ai-slop.md)).
+
+### NEVER (UI numerical bar)
+- Never reintroduce anything [`rite-polish` anti-ai-slop](../../rite-polish/reference/anti-ai-slop.md) bans.
+- Never hard-code a spacing value the 4 pt scale or project tokens cover.
+- 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**: the canonical 8 + 3 lattice above (§ Focus & states), not a
+      shorter local list
+- [ ] **Responsive** at the canonical viewport set (§ Responsive); no lost content or
+      controls, no page overflow; bounded exceptions tested; 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)
+- [ ] **Browser chrome** themed or declined in the brief (§ Browser chrome)
+- [ ] Clickables show `cursor: pointer` + a hover state; icons are SVG from the one set
+      (no emoji); nothing trapped under fixed/sticky bars
+- [ ] **Consistency locks hold** (declared color strategy/roles / one radius scale / one theme) and the
+      mechanical pre-flight passes ([`anti-ai-slop.md`](../../rite-polish/reference/anti-ai-slop.md))
+
+## Craft convergence bar
+
+Craft work terminates; it does not loop. Findings classify as **Critical /
+Major / Minor**: done means zero Critical, zero Major, and every remaining Minor
+accepted **in writing** (owner + reason) in `polish-report.md` — an unwritten
+minor is an ignored finding, not an accepted one. Re-running the full bar after a
+fix pass happens only on an explicit opt-in ("re-run the full bar"); "keep going"
+is not opt-in. Each pass captures every supported viewport, not only the one that
+failed. **Failing case:** the 375 px overflow is fixed, 320 px still overflows,
+and the report reads clean.