Design Craft

Design Craft

Constraints + Consistency + Restraint = Quality. LLMs converge on the statistical median of every Tailwind tutorial and template — generic, safe, forgettable. This skill provides the decisions a strong designer would make, pre-made: executable kernels for type, color, spacing, and interaction, plus branch recipes for everything else.

Hard Guardrails

The intent-and-repetition lens — for every context-sensitive treatment (warm neutrals, texture, illustration, large radii, uppercase micro-labels, sparklines, dark sections): the treatment must communicate state, hierarchy, focus, information, or brand meaning, and be bounded to a named role. One brand kicker is voice; an eyebrow above every section is scaffolding. A skeleton pulse is feedback; a pricing pulse is begging. A coherent warm neutral scale is a palette; a --cream token by reflex is the median. Token names are never the failure — unbounded repetition without purpose is.

Combination tells — individually forgivable, failing in combination (2+ together): eyebrow kickers on multiple sections, numbered section markers outside a real sequence, radius ≥24px outside a declared soft/playful direction, cards nested in cards, icon-heading-line cells repeated identically, different background color per section.

Project Context Scan (MANDATORY — before Design Decision Gate)

Determine brownfield (existing design system) or greenfield:

1. components.json → shadcn project, tokens in globals.css under :root
2. tailwind.config → theme.extend.colors custom tokens
3. globals.css / app/globals.css → CSS custom properties (--primary, --background, …)
4. package.json → UI libraries: shadcn, Radix, Panda CSS, vanilla-extract

ANY found → BROWNFIELD: catalog existing tokens and use them. Skip color derivation. Derive only genuinely missing roles, harmonized with existing hues. None → GREENFIELD: run the full Design Decision Gate including color derivation.

Design Decision Gate (MANDATORY — before writing any code)

State these decisions explicitly in your reasoning:

1. Structural archetype: app shell (sidebar + content) · marketing page (sections + CTA) · focused tool (centered workspace) · dashboard (data-dense grid) · editorial (long-form reading)
2. Visual density: sparse · balanced · dense
3. Aesthetic direction — a specific adjective pair matched to the product, not "modern" or "clean": stark technical, bold expressive, soft organic, restrained editorial, luxury refined, playful toy-like, retro-futuristic, industrial utilitarian.
4. Initial mode from the physical scene — write one sentence: who uses this, where, under what light, in what mood. That sentence picks light or dark. Design the chosen mode first; derive the other via semantic token remapping, never as a separate design.
5. Typeface — from the font menu below, matched to the aesthetic (availability rule in the type kernel).
6. Color strategy — BROWNFIELD: list existing tokens. GREENFIELD: run the color kernel below.
7. Composition — hero architecture from the menu below (marketing) or shell recipe from reference/composition.md (apps, dashboards, settings, detail pages).
8. The unforgettable question: "If someone saw 10 similar pages today, what would make them remember THIS one?" Name one concrete visual or structural choice.
9. The swap test + category-reflex check: If swapping the layout for a template and the font for Inter would go unnoticed, those choices defaulted — remake them. If the palette or aesthetic is guessable from the product category alone (or from category-plus-anti-reference: "fintech but not navy → terminal dark"), that's the training-data reflex one tier deep; rework until neither is obvious.

The archetype and density decisions drive everything else. The delight-impact curve: rare moments (onboarding complete, first success) earn more delight than daily actions. Polish is uniform — settings, empty states, and errors get the same care as the hero.

Reference loading triggers (MANDATORY):

• Palette, contrast, or dark-mode depth → READ reference/color.md
• Font loading, fallbacks, variable fonts, long-form text, CJK/multi-script → READ reference/typography.md
• Radius/elevation systems, density modes, block rhythm, safe areas, optical alignment → READ reference/spacing.md
• App shells, sidebars, gutters, metadata/date lockups, settings, features, pricing, proof, footers → READ reference/composition.md
• Async data, forms, validation, empty/error/loading, destructive actions, optimistic updates → READ reference/product-states.md
• Modals, drawers, transitions, gestures, any interactive motion → READ reference/motion.md
• Dashboards, tables, charts, KPIs, financial UI → READ reference/data-dense.md
• Icons, images, illustration, emoji → READ reference/visual-assets.md

Hero Menu (marketing pages)

Hero rules: spacing min py-24 md:py-32; headline sizes from the type kernel with a clamp() ceiling of 6rem — a larger ceiling is allowed only when visual scale IS the feature and the live render proves it survives every breakpoint. Subtext max 2 sentences, max-w-[50ch]. One CTA; secondary action is a text link. Real imagery with alt text, or bold typography as the visual — never colored boxes or icon grids. Heading copy must survive every breakpoint.

Type Kernel

Five roles with default sizes — adjust deliberately per aesthetic, never by reflex: Display clamp(2.5rem, 1.5rem + 4vw, 6rem) (hero statements) · Heading 1.5–2.25rem (section/page titles) · Body 1rem (reading text) · Caption 0.875rem (supporting meta) · Micro 0.75rem (labels, badges). Fewer sizes with more contrast beat many close sizes — app UI rarely needs more than these five plus one intermediate heading step.

Font menu by aesthetic (open menu — any verified font that matches the direction qualifies):

Reaching for Inter/Roboto/DM Sans "just to pick something" is defaulting — return to the aesthetic direction. One family unless genuine display/body contrast (serif+sans, geometric+humanist). Monospace as small accent (font-mono text-xs on IDs, timestamps) creates productive contrast in technical products; monospace display headings do not.

Loading strategy, fallback metrics, variable fonts, CJK: reference/typography.md.

Color Kernel

Strategy axis — state before picking colors: Restrained (tinted neutrals + one accent ≤10%, default for tools/dashboards, chroma ×0.6) · Committed (one saturated color carries 30–60%, marketing, ×1.0) · Full palette (3-4 named roles, campaigns/data viz, ×1.2) · Drenched (the surface IS the color, heroes, ×1.4). The multiplier scales every stop's chroma; re-clamp against the gamut caps after scaling. "Restrained by reflex" is the same failure as "Inter by reflex."

GREENFIELD derivation (executable, in order):

1. Hue from the product name: H = (first_letter_ordinal × 137 + second_letter_ordinal × 47) mod 360 (a=1…z=26; skip non-letters, and if fewer than two letters exist, reuse the first). Never replace with a category stereotype. If the derived hue cannot meet contrast/gamut after capping, shift ±30° and re-derive. A solid committed surface at the derived hue is always legal — the gradient guardrail bans gradient treatments, not hues.
2. 12-stop lightness spine at the derived hue: L = 0.99, 0.96, 0.90, 0.82, 0.71, 0.64, 0.55, 0.49, 0.40, 0.32, 0.27, 0.24 (stops 50…950). Committed-strategy chroma per stop: C = 0.02, 0.04, 0.06, 0.09, 0.11, 0.13, 0.13, 0.12, 0.10, 0.08, 0.06, 0.05 — scale by the strategy multiplier, then cap C at 0.09 for hues 170–210° and ~`0.18` elsewhere (sRGB safety).
3. Companion neutral scale at H+180° (≥120° separation), C ≤ 0.02 — the tinted neutrals that replace dead white/gray. Never #fff/#000 as surfaces; use stop-50/stop-100.
4. Map to semantic tokens: --background --foreground --card --primary --secondary --muted --accent --destructive --border --ring. Components use ONLY semantic tokens — never bg-blue-500, never inline hex/rgb/oklch in markup. Opacity modifiers on tokens are allowed (bg-primary/10).
5. Contrast floors (WCAG 2.x conformance): 4.5:1 normal text, 3:1 large text, 3:1 for required non-text UI (borders of inputs, icons carrying meaning, focus rings) — measured against the actual rendered background, placeholders included. Fix failures by moving L, not C. Every status conveys through a non-color cue too (icon, text, weight).
6. Dark mode is a remap: invert the semantic lightness mapping onto tonal surfaces (lighter = closer), reduce chroma ~10–20%, prefer surface tint over shadow, weight 350 only when the loaded font provides it. Swap the semantic layer, not components.

Universal status colors — success=green, error/destructive=red, warning=amber, info=blue. Users already know these; never invert, never use brand accent for status.

60-30-10: 60% neutrals, 30% secondary, 10% accent; one accent at 100/60/20/10% opacity before adding a second. All section backgrounds come from the same neutral scale, and a landing page is one continuous canvas: at most one emphasis panel + the footer change surface, no full-width rules between sections — variety comes from density, typography, and rhythm. Token names reveal the product (--meridian-600, not --gray-700).

Gamut mapping, P3, warm-neutral branch, APCA (supplementary only), dark-mode depth: reference/color.md.

Spacing Kernel

4px grid — all spacing in multiples of 4.

tight: 4px   — within atomic elements
item:  8px   — between items in a group
group: 16px  — between related groups
section: 24–32px — between major sections
page: 32–64px — page-level margins

Density modes, block text rhythm, elevation ladder, shadows, safe areas, optical alignment: reference/spacing.md. Shell geometry, gutters, lockups: reference/composition.md.

Layout Mechanics

Structural completeness: an app shell has navigation context + full-height content (a form in a void is missing structure); a dashboard fills its grid; a detail page pairs primary content with supporting context. Complete recipes: reference/composition.md.

Sidebar: same hue family as content, 1–2 lightness steps apart — no chroma cliff between shell and content. Inactive items recede (reduced opacity), active state is tonal (no side-stripe). Content always wins the hierarchy contest. Full anatomy: reference/composition.md.

Interaction & Completeness Kernel

Every interactive element has all applicable states: default, hover (gated @media (hover: hover)), focus-visible (visible ring — never removed), active (pressed feedback), disabled. Every async action runs the lifecycle idle → pending → success/error: pending disables re-activation and shows status (aria-busy), success/error is visible where the action happened.

UX Writing

Specific verb + object on buttons. One term per concept (Delete/Remove → pick one). Active voice. Cut every sentence in half, then again. Budget +30–40% width for i18n. Errors: never humor, never raw jargon (500, ECONNREFUSED). Never restate the heading in an intro.

Symptom → Correction

Conflict Priority

Sacrifice in this order (last = drop first): 1. functional integrity → 2. readability → 3. spatial rhythm → 4. motion polish → 5. decorative novelty.

Self-Check (MANDATORY — before finishing any UI work)

Re-read every line you wrote. Verify each item; fix failures before responding.

1. Guardrails — zero hard-guardrail patterns; combination tells don't stack.
2. Tokens only — every color is a semantic token; zero inline hex/rgb/oklch in markup; zero arbitrary spacing/type values.
3. Type kernel — tracking table honored, tracking-tighter absent, one h1, heading levels don't skip.
4. States complete — every interactive element has its five states; every async surface has loading/populated/empty/error; every async action blocks duplicate activation.
5. Layout mechanics — h-dvh, min-w-0 where text can overflow, no empty grid cells, no wrapped button labels.
6. The swap test — could the font become Inter and the layout a centered template without anyone noticing? If yes, remake those decisions.
7. References honored — name which reference files you read this session. If a mandatory trigger fired and its file went unread, read it now and re-verify the affected code.

When the work claims done, run the design-qa gates (scanner + live render).