Design Better

Design Better

A craft layer for any coding agent generating or reviewing UI. Style is owned by docs/design.md; this skill owns the timeless UX/UI craft heuristics — drawn from Nielsen Norman Group, the Laws of UX, Shneiderman, Refactoring UI, WCAG 2.2, Don Norman, Apple HIG, Material 3, and 2025–2026 AI-product patterns — that separate "shipped" from "designed."

Boundary. When a heuristic implies a visual property, reference a docs/design.md token by name ({colors.primary}, {rounded.md}). If docs/design.md doesn't have the token, flag it as a New Pattern to add via the Design System skill — never inline hex, font names, or arbitrary px. If docs/design.md doesn't exist at all, follow the codebase's existing convention for that property (theme config, CSS custom properties, component library) and note it.

Inputs

• `docs/design.md` — the style layer (recommended, not required). When present, reference its tokens by name for every visual decision. When absent, this skill still applies: fall back to the codebase's existing design conventions (theme config, CSS custom properties, existing components) as the style source, and recommend running the Design System skill to establish a single token source of truth (part of BuilderOS: https://github.com/BuildGreatProducts/builder-os).
• The thing being built or refactored — a brief, a file, or uncommitted diff.
• `docs/product-vision.md` — optional. Its strategy and brand inform microcopy tone and help weight which heuristic categories dominate.

Workflow

1. Establish the style source. If docs/design.md exists, parse its token catalogue (colors, typography, rounded, spacing, components) and the markdown rules (elevation, shape, Do's and Don'ts). If it doesn't, identify the codebase's existing design conventions — theme config (e.g. Tailwind/tokens), CSS custom properties, the component library in use — and treat those as the style source, then recommend the Design System skill so future work has a documented source of truth.

1. Confirm scope and weight. Restate the surface (signup / dashboard / chat / settings / detail / marketing) and which heuristic categories will dominate — a signup leans on Forms + States + Accessibility + Microcopy; a data dashboard leans on Hierarchy + IA + Cognitive Load; an AI chat leans on the AI-product subset.

1. Generate or review using both layers. The style source (docs/design.md tokens, or the codebase conventions) for every visual decision; the heuristics catalogue and the Laws of UX for every craft decision. Cite heuristics by number and laws by name in reviews ("H22 — disabled instead of erroring after submit"; "Hick's Law — too many options in one step").

1. Pre-flight checklist before delivering:

• Every interactive element has default, hover/focus-visible, active, disabled, and loading (where async) states.
• Every async surface designs and codes all four states: empty, loading, error, success.
• Every form input has a programmatically associated <label>, the correct inputmode/type, an autocomplete attribute, and onBlur validation.
• Every motion is 150–400 ms, eases by direction (out entering / in exiting / in-out moving), animates transform/opacity only, and honors prefers-reduced-motion.
• Body text contrast ≥ 4.5:1, UI components ≥ 3:1, focus rings ≥ 3:1 at ≥ 2 px.
• Pointer targets ≥ 24×24 CSS px (≥ 44×44 on touch).
• Layout works at 320 CSS px wide with no horizontal scroll.
• The primary action is the single visually dominant element on the view.
• Every visual decision references a docs/design.md token (or a codebase convention when no design system exists). Missing tokens flagged as New Patterns, not invented inline.

1. Deliver. Note which heuristic categories and Laws of UX dominated and surface any trade-off where a heuristic or law was knowingly skipped.

The heuristics catalogue (50 items)

Each entry: number (cite in reviews) + short name + one-line rule + code action. Style-neutral throughout — defer every visual property to docs/design.md (or the codebase's design conventions when it's absent).

Visual hierarchy & emphasis

H1. One primary action per view (Von Restorff). Make the primary CTA the single visually distinct element — use the most prominent design token color and largest button size. Secondary actions use quieter tokens.

H2. Hierarchy from size + weight + color, not size alone (Refactoring UI). De-emphasize secondary text by reducing weight or shifting to a secondary text color token before reducing font size.

H3. Proximity groups, white space separates (Gestalt). Stack related fields with a small gap; separate unrelated groups with a larger spacing token.

H4. Common Region bounds groups (Gestalt). When proximity isn't enough, bound with a card, divider, or tinted surface — using the design system's elevation/surface tokens.

H5. White space is a tool — default to too much (Refactoring UI). Generous padding reads as confident. Tightening should be deliberate, not default.

H6. Snap to the spacing scale; nothing one pixel off (Polish). Every margin/padding/gap is a design token. Alignment to the grid is the difference between "designed" and "drafted."

Layout & alignment

H7. Semantic HTML before divs + ARIA (WCAG 1.3.1). Use <main>, <nav>, <header>, <section>, <article>, <button>, <label>. Reach for role= only when no native element fits.

H8. Reading line length 50–75ch. Cap prose containers with max-width: 65ch (or analogous).

H9. Reflow at 320 CSS px (WCAG 1.4.10). Every view works at 320 px wide with no horizontal scroll.

H10. Text spacing tolerance (WCAG 1.4.12). Layout survives user overrides of line-height (≥ 1.5×), letter-spacing (≥ 0.12em), word-spacing (≥ 0.16em).

Typography craft

H11. Use only documented type levels. Every font-size/font-weight references a typography token.

H12. Tabular figures in data (`font-variant-numeric: tabular-nums`). Numbers in tables, dashboards, and ledgers align vertically.

H13. Modern text-wrap (`balance` on headlines, `pretty` on prose). Headlines read more deliberately with text-wrap: balance; body paragraphs avoid orphans with text-wrap: pretty.

Color & contrast (non-stylistic)

H14. Body text contrast ≥ 4.5:1 (WCAG 1.4.3 AA). Verify every body/background token pair. Large text (≥18.66 px bold or ≥24 px) needs ≥ 3:1.

H15. UI component contrast ≥ 3:1 (WCAG 1.4.11). Form borders, icon-only buttons, focus rings, chart strokes all need ≥ 3:1 vs adjacent color.

H16. Color is never the sole signal. Pair every color-encoded state with an icon, label, or pattern.

Interaction & feedback

H17. Feedback within 100 ms (Doherty / Norman). Every action that triggers logic confirms visually within 100 ms (press state, ripple, optimistic update, skeleton).

H18. Three-state minimum for interactive elements. Default, hover or focus-visible, active, disabled. Loading is a fifth where async.

H19. Affordances signal interactivity. Buttons look pressable; links visibly differ from body text — use design tokens for the visual treatment.

H20. Discoverability over hidden interactions (Norman). Critical actions are visible by default — never hidden behind hover, long-press, or undisclosed gestures.

H21. Easy reversal (Shneiderman). Undo on destructive actions; Cancel on every modal; Back without data loss; soft-delete with restore.

H22. Constraints prevent errors (Norman). Disable invalid options; use min, max, step, pattern, type on inputs; gate submit on validity.

Forms

H23. Single-column layout, top-aligned labels. Stack vertically; labels above inputs; never placeholder-as-label.