frontend-craft

---
name: frontend-craft
description: >
  Design, build, refactor and audit product interfaces with deliberate visual hierarchy,
  interaction quality, responsive behaviour and evidence from the rendered page. Use for any
  UI-heavy work — a new screen, a redesign, "this looks generic", "improve the layout", a
  dashboard, a design review — and whenever visual quality rather than wiring is the point.
  Modes: build, refactor, audit.
---

# Frontend Craft

`web-product-guardrails` owns *system boundaries*. This owns the *rendered experience*. Nothing
in the architecture prevents a technically correct interface that is generic, flat and hard to
read — this does.

## The rule that comes first

> **Do not redesign from source code alone. Render the current interface before deciding what
> is wrong with it.**

Reading JSX tells you what components exist. It does not tell you what the page *feels* like,
where the eye lands, what competes for attention, or that the table overflows at 375px. For
backend work we inspect the property the test claims to own; for UI, inspect the experience the
code claims to produce.

**Source review is not visual review.** Tests passing is not visual completion.

---

## Pick a mode

### `build` — new UI from product requirements
1. **Hierarchy before components** (§ below). Do not open a component library first.
2. Check the existing design system: reuse → extend → invent, in that order.
3. Compose the page, then implement.
4. Render. Desktop + mobile. Inspect. Refine.
5. Evidence: screenshots of the real page, including one non-happy state.

### `refactor` — improve existing UI
1. **Render it first.** Screenshot desktop and mobile before touching anything.
2. Diagnose from the render: hierarchy, density, rhythm, alignment, contrast, competing accents.
3. Note design-system inconsistencies — count the radii, shadows, font sizes and greys actually
   in use on that page. The count is usually the finding.
4. Identify interaction problems: unreachable controls, missing states, no feedback.
5. **Preserve behaviour.** A refactor that quietly changes what the page does is a bug.
6. Change, re-render, compare against the before screenshots.

### `audit` — findings only, no implementation
Return ranked findings, each with the rendered evidence and the specific fix:

| | |
|---|---|
| **P0** | Broken function, inaccessible control, unreadable contrast, mobile unusable |
| **P1** | Hierarchy failure, navigation confusion, missing critical state |
| **P2** | Design-system inconsistency, spacing/rhythm, typography |
| **P3** | Polish, motion, micro-copy |

Do not implement in audit mode. The output is the finding list.

---

## Start from product hierarchy, not components

The failure this prevents: opening with "I need a Card, Card, Card, Table, Button" and producing
a wall of equal-weight boxes where nothing is primary.

Ask first:

1. **What did the user come here to do?**
2. Then classify every piece of information on the page:

| Tier | Treatment |
|---|---|
| **Primary** | The thing they came for. Largest, highest contrast, earliest in reading order. |
| **Supporting** | Helps them act on the primary. Present but visually subordinate. |
| **Contextual** | Orientation — where am I, whose data, when. Small, quiet, never competing. |
| **Actionable** | One clear primary action. Everything else is secondary or tertiary. |

If three things are all "primary", the page has no hierarchy and the user's eye has nowhere to
land. Choose.

**Resist turning every piece of information into a card.** A card is a container for something
genuinely separable. Four numbers in a row are four numbers, not four cards.

---

## Default visual character

Principles, not a theme. The product's own design system overrides this.

**Prefer**
calm over decorative · strong typography over boxes · whitespace over separators · hierarchy
over density · restrained radius · restrained shadows · neutral surfaces · one clear accent ·
progressive disclosure · content-first layouts

**Avoid by default**
gradient-heavy heroes · card overuse · glassmorphism · decorative blobs · an icon in every
heading · unnecessary badges · dashboard grids for ordinary content · three different border
radii on one page · arbitrary shadows · oversized headings with no information hierarchy

Detail and worked examples: `references/visual-principles.md`.

---

## Reuse before invention

Before adding any UI, inventory what already exists: colours, spacing scale, type scale,
container widths, radius, buttons, inputs, tables, dialogs, navigation, breakpoints.

Then: **reuse → extend → invent.** Inventing a new spacing value or radius because it "looks
better here" is how every feature becomes its own small design system. If you must invent, add
it to the design system rather than inline.

New repo with no system yet? Establish the minimum first — spacing scale, type scale, content
width, radius, border, surface hierarchy, focus treatment, breakpoints — in
`frontend/src/lib/design/`. Eight decisions, made once.

---

## Compose the page before implementing

State these explicitly:

```
page purpose · primary action · primary content · secondary content ·
navigation context · empty state · loading state · failure state · mobile behaviour
```

A dashboard, badly:

```
[Card] [Card] [Card] [Card]
[Card] [Card] [Card] [Card]
[Table ─────────────────────]
```

Better:

```
Page title                              Primary action

Critical status — the one thing that matters

Main working surface
──────────────────────────────────────────────────────

Secondary / contextual information
```

Patterns for list, detail, dashboard, settings, form workflow, auth and marketing pages:
`references/page-patterns.md`. They are patterns to adapt, not templates to copy.

---

## States are part of the design

Every async surface owns all of these — designed, not defaulted:

```
loading · empty · success · partial · error · disabled · unauthorized · offline (if relevant)
```

`if (loading) return <p>Loading...</p>` is not a loading state.

For each one ask: **what should the user understand, and what can they do?** An empty state that
only says "No data" wastes the best teaching moment in the product.

Full treatment: `references/interaction-states.md`.

---

## Responsive is a decision, not a media query

Don't say "make it responsive". Decide, per surface:

```
desktop layout → tablet transition → mobile layout
```

Particularly for: navigation, tables, forms, toolbars, dialogs, charts, sidebars.

A six-column table on mobile becomes compact record rows — not a horizontally crushed table and
not a horizontally scrolling page. Decide which; both are legitimate, silence is not.

---

## Accessibility is part of craft

Not a WCAG audit. The floor:

semantic HTML · keyboard operability · visible focus · real labels · accessible dialog
behaviour (focus trap, Escape, focus return) · sufficient contrast · reduced-motion respected ·
meaning never encoded by colour alone

**Visual polish must not regress accessibility.** Removing a focus ring because it "looks
cleaner" is a defect, not a style choice.

---

## Motion must explain something

Motion may indicate: state transition · spatial relationship · feedback · continuity.

Motion may not exist merely because animation is possible. No `animate-fade-in-up` on every
section. Respect `prefers-reduced-motion`.

---

## Evidence — required for visual work

For any change that alters what the user sees:

```
implement → run the app → render in a real browser
   → desktop screenshot → mobile screenshot
   → inspect affected interaction states → refine
```

At minimum, inspect one representative desktop viewport, one mobile viewport, and the
interaction states the change touched.

**Do not claim visual completion because tests pass.** If you could not render it, say so
plainly and say what remains unverified.

If the repo has `scripts/seed-demo-data`, run it first — an empty database renders an empty UI,
which proves nothing about how the design handles long titles, missing optional fields, status
variety, or enough rows to paginate.

Review rubric for judging your own output: `references/review-rubric.md`.

---

## Boundaries this skill does not cross

Authorization, data shapes, business rules and API design belong to `web-product-guardrails`.
If making the UI good seems to require a hand-written DTO, a raw `fetch()`, or a rule enforced
only in the browser — that is the stop condition, not a styling decision.