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.

2. 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.

3. 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").