256 lines
15 KiB
Markdown
256 lines
15 KiB
Markdown
---
|
||
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.
|