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

→ verify: you can name the token source, the existing components you're reusing, the pattern you're following — and whether the project has i18n — or you've confirmed none exists.

Priority order

When concerns compete, resolve in this order. Each row points to its deep-dive reference.

Component design (agnostic)

• Small, single responsibility, one component per file. If you describe it with "and"/"or", split it.
• Composition over configuration. Prefer composing smaller pieces (children/slots, compound components) over a component with many flags.
• No boolean-prop explosion. Five booleans = 32 states, most invalid. Replace mode flags with explicit variant components so invalid combinations can't exist.
• Children/slots over render callbacks unless the parent must pass data back (then use a scoped slot / render prop deliberately).
• Never define a component inside another component — it remounts every render and breaks identity.
• Type the public surface. Props and state are fully typed; no any. Stable keys for lists (never the array index when items reorder).
• Specify a component as Variants × Sizes × States. Cover every state — default, hover, focus, active, disabled, loading — and resolve overlaps in that priority (disabled > loading > active > focus > hover > default).

State & data (agnostic)

• Keep fetching out of leaf components. Data ownership lives in a provider/store/loader the UI consumes through an interface — agnostic to useState, a store, signals, or a server loader.
• Derive, don't duplicate. Compute from existing state during render instead of storing a copy and syncing it.
• Lift state only when shared; otherwise colocate it next to where it's used.
• The URL is state. Filters, tabs, pagination, and expanded panels belong in query params so they're shareable and survive reload.
• Always handle loading, error, and empty as first-class states. Details: references/state-and-data.md.

Accessibility floor (every change)

Semantic HTML before ARIA. <button> for actions, <a> for navigation — never a clickable <div>. Visible keyboard focus (never remove the outline without replacing it). Labels on every control; alt text on meaningful images (alt="" for decorative); aria-label on icon-only buttons. Honor prefers-reduced-motion. Fixability rule: apply mechanical fixes directly; for contextual/visual ones (real alt text, copy, color choices) leave a clear TODO — never invent alt text, labels, or content. Full checklist: references/accessibility.md.

Security & PII on the client

• No tokens or secrets in localStorage/sessionStorage — prefer httpOnly cookies. Store only what the UI needs, versioned, in a try/catch.
• Never render untrusted HTML (dangerouslySetInnerHTML/innerHTML) without sanitizing.
• Minimize PII sent to the client, serialized into props/markup, or logged to analytics. Treat the client↔server boundary as a trust boundary.
• No console.log in production. (These align with, and are partly enforced by, the baseline CLAUDE.md and hooks.)

Workflow

1. Audit first (Step 0) — tokens, existing components, conventions.
2. Design the component tree — name the pieces, pick variants over flags, decide where state lives.
3. Build with semantic, accessible markup and the project's tokens. Handle loading/error/empty/long-content from the start.
4. Wire state and data at the right level; keep fetching out of leaves; reflect navigable state in the URL.
5. Make it responsive mobile-first; verify the layout at small/medium/large.
6. Check performance on realistic data (lists, images, animation).
7. Test behavior + accessibility (delegate to skills/writing-tests); add a visual check if the project has one.
8. Capture a learning if you hit a convention/trap not in this skill.

Pre-delivery checklist

• Reused existing components/tokens; no hardcoded hex/spacing/font sizes.
• Keyboard-operable; visible focus; semantic elements; labels/alt present (or TODO for contextual ones).
• Loading, error, empty, and long-content states handled.
• No tokens/secrets in web storage; no unsanitized HTML; no PII leaked to client/logs.
• Typed props/state; small single-responsibility components; stable keys.
• Responsive at the project's breakpoints; animations honor reduced-motion.
• If the project has i18n: no hardcoded user-facing strings; every new key present in all locale files.
• Visual decisions are deliberate: ≤2 font families with fixed roles; spacing on the 8pt grid; consistent section rhythm; none of the generic-page anti-patterns (references/design-craft.md).
• From-scratch work: the design plan was delivered before code; placeholders marked, no invented facts or lorem ipsum; SEO floor applied (references/designing-from-scratch.md).
• From-scratch work: Vibe Check < 5 marks and no open blocker on the delivery scorecard (references/anti-vibe-coded.md) — reported item by item.
• Tests for behavior and accessibility; existing tests still pass.

See also

• references/accessibility.md · references/state-and-data.md · references/forms.md · references/performance.md · references/responsive.md · references/ux-writing.md · references/design-craft.md · references/designing-from-scratch.md · references/anti-vibe-coded.md
• Framework specifics: references/react.md · references/vue.md · references/svelte.md · references/web-components.md
• skills/writing-tests (test strategy), skills/developing-features (general production-code rules, security depth), skills/reviewing-code (review output), rules/frontend.md (the enforced subset).