building-frontend-ui

Building Frontend UI

A frontend change is good when it reuses what already exists, is accessible by default, handles every state (loading, error, empty, long content), performs under real data, and leaks no data to the client. This skill is framework-agnostic: the workflow and rules live here; framework-specific mechanics live in references/<framework>.md and are loaded only when relevant.

Read first (always)

List learnings/ and read every file relevant to the current task — project conventions, the design system, banned dependencies, and component patterns live there and override the defaults in this file. If a learning conflicts with this skill, the learning wins — mention it.

Starting from zero?

If there is no existing design to extend (new site, new product surface, greenfield page), read references/designing-from-scratch.md before Step 0 and deliver its design plan as text before any code: strategy (one measurable goal, one primary action) → structure (sitemap, wireframe, section jobs) → tokens → components → pages. Visual decisions (type, color, space, motion, the generic-page anti-patterns) follow references/design-craft.md. Before declaring from-scratch work done, run the Vibe Check + delivery scorecard in references/anti-vibe-coded.md and report item by item — it is the definition of done for greenfield UI.

When a design system already exists, the opposite applies: the existing tokens, components, and layout are the law (Step 0) — never introduce a parallel style, and never use the from-scratch rules to justify restyling what's already consistent. Only the functional layers of the anti-vibe audit still apply (states, dead clicks, semantics, mobile, a11y).

Step 0 — Audit before you build (do not skip)

Most bad frontend work is net-new code that should have been reuse. Before writing anything:

1. Find the design system. Grep for the token/theme source — CSS custom properties (--color-*, --space-*), a tailwind.config, a theme file, design-token JSON. Use those tokens; never hardcode raw hex, px spacing, or font sizes in a component. Before defining any new color, sweep the existing palette and name the closest existing tokens — a new token that duplicates (or nearly duplicates) a color that already has a name is a defect, not a choice (hooks/check-design-tokens.py flags this after the fact; the sweep comes first).
2. Find existing components and utilities. Grep/glob for a component that already does this (button, modal, field, table, empty-state) and reuse or extend it instead of creating a parallel one. Match the established prop and naming patterns.
3. Find the i18n system, if any. Grep for a locales/ dir, i18n config, or translation calls (t(...), $t, useTranslation, FormattedMessage). If the project has one, every user-facing string goes through it — a hardcoded string in a translated app is a bug, and every new key must be added to all locale files (a key present in one language and missing in another ships broken UI).
4. Read the surrounding files to copy the project's conventions (file layout, styling approach, state approach, test location).