---
name: ui-craft
description: Build high-craft, polished CC2 screens — the layout/typography/state/status/motion/a11y and real-browser-verification discipline distilled from the read-only Order Outs rebuild. Use when building or polishing a view/card/panel, when a screen "looks bland," when covering all of a screen's states, or before calling any UI change done.
---

# High-craft UI

The bar is a screen that reads as **data, not a form** — figure-on-ground
regions, one hero fact per unit, honest states, and geometry verified in a real
browser. This skill is the distilled playbook from the Order Outs rebuild
(`src/views/products-pricing/order-outs/`).

**North stars — study these first, don't re-derive them:**

- **Amit's evidence viewer** — the "list → focused detail" viewer host:
  `src/views/evidence/EvidenceView.tsx` (collapses nav to maximize reading
  space; drives detail from a focused-record store),
  `src/views/evidence/evidence-bridge.ts` (viewer↔right-sidebar wiring).
- **Amit's underwriting tab** — one unified table of a loan's tasks +
  requirements, row → modal/viewer, quiet accessible table chrome:
  `src/views/readiness/ReadinessView.tsx`,
  `src/views/readiness/ReadinessDataTable.tsx` (the shadcn data-table layout as
  lightweight plain React; status-tone dots),
  `src/views/readiness/FiledTasksPanel.tsx`.
- **shadcn v3** — the design language. The repo points to it by role, not by
  name (`src/pages/docs-page.tsx` links the official docs): data-table = the
  *tasks* example (`ReadinessDataTable`, `ApplicationDataTable`), shell =
  the *dashboard* example (`docs/pylon-design-system.html`), and
  `src/components/button-group-demo.tsx` shows the clone-into-owned-source
  idiom. Compose these primitives; never re-skin `src/components/ui`.

## When to use

Building or polishing any view, card, panel, tray, or table under `src/`; the
human says a screen is "bland" or "so-so"; you need to cover every state of a
screen; or you are about to call a layout/spacing/wrapping change done. For the
correct *composition* of primitives (Card shapes, pinned Table, `as` rules) read
`src/components/AGENTS.md`; for the non-negotiable semantic-HTML/DOM rules read
`src/AGENTS.md`. This skill is the craft layer on top of those.

## Before you build — ground the work, don't jump to code

- **Study the best in-repo exemplar first, then write a short playbook.** The
  strongest results came from reading Amit's evidence viewer + underwriting tab
  and distilling their moves before touching the new screen — not from coding
  straight away. Reuse `docs/screen-redesign-process.md` for the port workflow.
- **"It looks bland" is latitude to redesign, not a pixel tweak.** The Order
  Outs "it looks so so bland… it doesn't need to be what I told you" triggered a
  full rethink into rich dossier rows — treat that feedback as permission to
  change structure.
- **Run a quick adversarial design panel before building.** Sketch 2–3 layouts
  and judge them on craft / data-parity / a11y / buildability. Order Outs
  rejected two-side-by-side-rails and a full-width single-column stack before
  choosing list→right-tray; the ground-up experiment chose an inline dossier.
- **Pick master-detail vs. persistent-inline by item count + interactivity.** A
  right-side **Sheet tray** scales to N rows and 10–30 scrolling docs and keeps
  the list compact; a **persistent inline stack** wins for very few, read-only
  units where hiding one behind a click is pure friction. Order Outs (~2
  read-only items) went inline; the disclosures/Mail/CC1 pattern uses the tray.
- **Make every state viewable before you polish it — you can't craft what you
  can't see.** Gate rich fixtures behind a URL param, live-fetch when absent
  (`?orderOutsStub=1|waived|inprogress|cancelled|notordered`, one-line hook
  override). Add a distinct stub per state and verify EACH — the dev-API loan
  lacked rich data, so this is the only way the full craft is visible.

## Layout, hierarchy & density

- **Figure-on-ground beats hairlines.** Articulate regions with one canvas color
  a step off card + elevation + spacing, not dividing borders ("paper on a grey
  well"). Order Outs cards sit on `bg-muted/20` with `border-border/60` +
  hover-lift, not boxed dividers; the evidence viewer shares one `--bg-canvas`
  and lets only chips/shadows carry contrast.
- **One focal fact per unit — the "hero fact."** Each row/card earns a single
  high-weight number the eye lands on; everything else is muted support.
  Appraisal card → appraised value `text-2xl tabular-nums` right-aligned, `h2`
  name kept clean.
- **"Not bland with few items": pack each row with at-a-glance signal.** A
  2-item screen still reads as intentional when each row carries icon + name +
  status + hero fact + a momentum cue + quiet counts —
  `8 milestones · latest May 16, 2026 · 2 contacts · 2 docs` + a milestone strip
  — a scannable dossier, not a thin line.
- **Don't inflate dead space for symmetry; anchor actions to their content.**
  Equal-height columns top-anchor their content (never stretch); an action lives
  in the header `CardAction` or `CardFooter`, never orphaned mid-card
  (identity → facts → action).
- **Push long/secondary detail behind an affordance.** Filenames, notes, vendor
  refs wrap and wreck a row — move them into a dialog/icon. The underwriting tab
  pulled filenames into a paperclip dialog; Order Outs docs open the shared
  `DocumentPreviewDialog`.
- **Columns are data — drop one that would be all-noise, keyed to the full
  dataset.** A column that's all-empty/all-dash/all-same is removed, memoized
  over ALL rows so layout never shifts as you filter. "A table where every row
  is a dash is noise."

## Typography & numbers

- **Muted-first, 3-step ink scale.** Everything supporting is
  `text-muted-foreground`; reserve `font-semibold`/`text-foreground` for the one
  emphasis per unit. Meta lines, eyebrow headings
  (`text-xs uppercase tracking-wide text-muted-foreground`), and
  `CardDescription` are all muted.
- **`tabular-nums` on every number that aligns or updates — non-negotiable.**
  Money, dates, counts, percentages, zoom%. The underwriting playbook flags this
  as the one thing to always ADD to a money/date tracker.
- **Variable text clamps with a `title` fallback and never resizes layout.**
  Two-line clamp + `overflow-wrap: anywhere`, full text on hover; long values
  truncate beside a fixed control, never shove it (see the copy-button fix under
  Verify).

## Content honesty & states

- **Blank ≠ dash ≠ value.** Not-applicable renders empty; a real-but-unscored
  value renders the value (`100%`), never a placeholder dash. An in-progress
  appraisal shows *no* appraised value at all (the `Fact` component returns
  `null` when absent) — this single discipline is why a screen reads as data.
- **Empty ≠ error; failure is honest and distinct.** Never show a "no data"
  empty state for a load failure (it reads "nothing here" and invites redundant
  re-entry). Partial vs. total failure read differently ("Couldn't load 10" vs.
  "8 of 10 loaded"). Order Outs uses an inline `Alert` + Retry, separate from the
  `EmptyState`.
- **Never fake a number or a progress script.** Narrate real observed backend
  state; fall back to a value you actually have rather than a dash (on a vendor
  detail failure, fall back to the summary's direct-order value so a real value
  never reads as "—").
- **Model mutually-exclusive states as first-class either/or.** An appraisal is
  EITHER ordered OR waived — the waived case is a resolved positive hero (green
  seal, "Appraisal waived — no order needed"), never a sad empty state leaking
  `Program: PROPERTY_INSPECTION_WAIVER` and never a "Place order" affordance.
- **Humanize enums at the boundary; never leak wire values to the UI.**
  `TITLE_COMPANY` → "Title company"; the waiver program mapped via an inline
  Title-Case map in the model — not the copy catalog, and never a vendor name
  (see the MEMORY note on vendor names).
- **Cover the whole state space and make each state demoable.** Audit every
  status (ordered / in-progress / terminal-negative / not-ordered / waived +
  title equivalents + empty contacts/docs); a terminal-negative reads "stopped,"
  not "broken." Gate each behind a stub mode with a spec.

## Status signaling

- **Status = shape + word + color, never color alone.** Back every tone with a
  distinct glyph + a text label from one central resolver + one label catalog.
  "open/not-yet" is a dashed empty outline dot (`border-dashed bg-transparent`),
  not a hue; a distinct failed glyph serves color-blind users; every dot is
  `role="img"` + `aria-label` + `title`; `StatusDot` + `Badge` always paired.

## Motion

- **Microanimations are functional and lawful, each with a reduced-motion
  off-switch.** Two easings, a 100/200/300ms duration law (longer = an
  explicitly-flagged brand exemption); nothing pops (width/opacity ease in AND
  out). Order Outs — tray slide, staggered milestone reveal, row hover-lift,
  chevron rotate on select, copy-button icon swap, section fade-in — all wrapped
  in `motion-safe:` / `motion-reduce:transition-none`; the repo lint enforces the
  fallback.
- **Cap staggered entrances so long lists stay calm.** Cap the per-item delay
  (e.g. at the 10th child) so a 50-row list doesn't cascade for seconds; key the
  container on the active view to replay the entrance on switch.

## Structure, semantics & a11y — the HTML is a deliverable

- **Reconstruct the rendered DOM and justify every surviving `<div>`.** Semantic
  elements over roles: `<ul>/<li>` for lists, `<dl>/<dt>/<dd>` for labeled
  readouts (`<dd>` bold via a font class, never `<strong>`),
  `<article>`/`<section>`/`<header>` for the tray, `Card as="section"`,
  `CardTitle as="h2"`. A single-column list is a `<ul>`, never a single-column
  `<table>`. Enforced by `src/AGENTS.md` + local ESLint rules
  (`card-title-requires-as`, `no-single-column-table`, the `role="button"` ban).
- **The shell owns the single `<h1>`; a section view is a headless fragment.** It
  mints no page heading and no `banner`/`contentinfo` landmark. A `<header>`
  becomes a `banner` unless scoped by a sectioning tag, so a dialog/tray uses
  `<section role="dialog">`, not `<div role="dialog">`.
- **Live regions announce settled values only, mounted-empty, split by
  liveness.** A polite sr-only `role="status"` speaks the settled summary once
  (`<p className="sr-only" role="status">{settledSummary}</p>`); transient
  "Loading…" never enters it (that doubles every utterance); errors are
  `role="alert"`; the skeleton is `aria-hidden` (loading is visual-only). Don't
  add an empty region as box-check theater.
- **Each surface owns its own load/error feedback — no competing panel banner.**
  Contacts and Documents each render their own skeleton/error; the tray doesn't
  stack a second one.
- **Compose primitives; add no frame the design doesn't show.** Use
  `Card`/`Badge`/`Sheet`/`Alert`/`Empty`/`Skeleton` as-is; collapse wrappers
  with `as`; a flush table takes no extra `Card`. Per-type variance goes through
  a strategy registry, not inline ternaries. Hand-build a small list when
  `Item`/`ItemGroup` don't exist rather than inventing chrome; drop redundant
  roles the repo bans (`role="list"` on a `<ul>`).
- **A clickable row's real control is a `<button>`; the row `onClick` is a
  pointer-only widener** that stands down on descendant `a`/`button` clicks and
  on ⌘/Ctrl/Shift/Alt (new-tab / extend-selection stay native). Icon-button row
  actions `stopPropagation`.
- **Charts carry their data for AT and aren't keyboard traps.** `aria-hidden`
  when adjacent text already states the figures, else `role="img"` with the real
  numbers; recharts `accessibilityLayer={false}` unless a real
  keyboard-exploration UX is built.

## Skeletons & scrolling

- **The skeleton is a photograph of the settled layout** — same
  dot/title/value/badge rhythm and the same responsive hiding, so nothing jumps
  when the query lands. A mismatched skeleton is worse than none; delete any
  stand-in that maps to no real element (the underwriting commit deleted a
  9-tile metrics skeleton that matched no section); hold ambiguous summary text
  until its query settles.
- **Scroll, don't paginate**, via a `min-h-0 flex-1 overflow-auto` chain — every
  flex ancestor sets `min-h-0`, the inner panel is the scroller. Order Outs tray
  detail is `min-h-0 flex-1 overflow-y-auto overscroll-contain` so a 10–30 doc
  list scrolls while the close button stays put.

## Verify in a real browser — jsdom can't judge layout

The authoritative procedure is `AGENTS.md` §"UI verification in a real browser
(Playwright)"; the checked-in sweeps are
`scripts/playwright/responsive-sweep.js` and
`.../error-state-sweep.js`. The hard-won craft on top of it:

- **Any change to layout/spacing/wrapping/breakpoints/containers is not done
  until measured in a real browser.** Green typecheck/lint/tests/build are
  necessary but not sufficient — jsdom passes overflowing dialogs and wrapping
  controls.
- **Measure geometry from bounding boxes; don't eyeball "looks fine."** The
  `dana.whitfield@example.com` copy-button-wrap defect was invisible to tests: a
  long email pushed its copy button to the next line. Fix = group each
  value+button, `min-w-0 truncate` on the link + `shrink-0` on the button;
  confirmed by `btnTop≈emailTop` and `btnLeft≥emailRight` at desktop AND 390px,
  not by looking.
- **Stress the width that breaks, not the one that fits.** Desktop hid that bug
  (the email fit); the defect only appears where the value must truncate. Sweep
  just above/below each breakpoint + container flip you introduced, plus the
  side-panel-narrowed desktop column (an open right panel squeezes
  `@container/main` at full viewport — no phone preset catches it).
- **Sweep the error/empty/waived states too, at every breakpoint.** Error-state
  geometry (a control dropping when the alert mounts) is invisible to jsdom; your
  stub modes make each state reachable for the sweep.
- **Emulate sizes with CDP device-metrics, never `browser_resize`.** A
  `browser_resize` pin survives a plain emulation-clear, letterboxes the
  developer's own window, and blocks resizing ("why can't I resize the screen?").
  Clear with `Emulation.clearDeviceMetricsOverride`, and if you ever resized,
  close + reopen the page. (See the MEMORY note on CDP emulation.)
- **Re-verify a blocker before repeating it.** `FORBIDDEN` / `/login` /
  "Application unavailable" are usually org-context flux or an expired session,
  not your code — ask the human to re-auth rather than ship blind or blame the
  change.

## Not covered here — pointers, don't duplicate

- **Demo videos** for the UI-facing PR → the `record-demo` skill.
- **Guardrails / shrink-only baselines / mutation-form wiring** → `CLAUDE.md`
  "Guardrails" + your MEMORY notes; a red guard means fix the root cause, never
  weaken it.
- **Graphite stacking, CI engine rotation, DIRTY-PR-runs-zero-CI, ticketing,
  Greptile-to-5/5** → `CLAUDE.md` + MEMORY. Craft rule that belongs here: run a
  Greptile-grade self-review of the diff *before* the PR is open so it lands at
  5/5, and when a screen goes read-only, remove the dead machinery end-to-end
  (mutation, hooks, flags, specs, guard-baseline entry) rather than leaving it
  to rot.