frontend-mockup

What this skill does

# Frontend Mockup

Build self-contained HTML design review documents. One `.html` file, no dependencies, opens in a browser. The output is for **thinking through design** — comparing options, evaluating states, making decisions — before any real code is written.

## Before You Start

### Read the Real Theme

Extract actual CSS variables from the project's theme file (`globals.css`, `tailwind.config.*`, etc.). Map them into the mockup's `:root` block. Don't guess colors, don't use generic grays when the project has a real palette. Include brand/accent colors — even if used sparingly, they make the mockup feel like the real product.

### Understand the Context

Read 2-3 real components to absorb the project's visual personality — density, font scale, interaction patterns, border radius, depth strategy. The mockup should feel like it belongs to this project.

---

## Document Structure

The mockup is a scrollable design review document. It has its own chrome (navigation, section headers, callouts) that is visually distinct from the UI being mocked inside it.

### Sticky Navigation

A fixed nav bar at the top with anchor links to every section. Dark or inverted background to separate document chrome from content. Section names in the nav should describe the option or state, not just "Section 1."

```
[Option A: Slide Panel] [Option B: Drawer] [Option C: Inline] [Compare]
```

The reviewer can jump to any option in one click without scrolling. Highlight the current section on scroll via a small JS `IntersectionObserver` or scroll listener.

### Sections as Cards

Each section wraps in a rounded card on a tinted page background (`body` at off-white, sections at white). This creates natural separation without heavy dividers. Alternate section backgrounds between `#fff` and `#fafafa` for additional rhythm when sections are long.

### Three-Level Section Headers

Every section opens with:

1. **Tag** — Small-caps, 0.625rem, 600 weight, 0.08–0.1em letter spacing, colored by category (teal for recommended, amber for trade-off, red for problem). This is the chapter marker.
2. **Title** — 1.25rem, 600 weight, tight tracking. The actionable name.
3. **Description** — 0.8125rem, 400 weight, muted color, max-width ~42rem. One or two sentences stating what this section shows and the design tradeoff — not a feature explanation. Answer "why would I pick this?"

The prose appears above the mockup frame, so the reviewer is primed with intent before evaluating the visual.

---

## Mockup Frames

Each design option or state is rendered as a **full-fidelity app frame** — not a component in isolation. Include enough surrounding UI (navigation, header, content area) that the feature being designed is seen in context.

### App Shell Realism

- Render at realistic proportions inside a bordered, shadowed, rounded container
- Use real-looking content — plausible names, messages, timestamps. Never "Lorem ipsum" or "Item 1"
- Add macOS traffic-light dots (`.mock-titlebar`) on the frame to signal "this is an app window" — eliminates any "is this the mockup or the document?" confusion

### Show Every Meaningful State

Don't just show the happy path. Render:
- **Default/empty** — first-run, zero data, nothing configured yet (see below)
- **Loading** — skeletons or spinners where async data lands
- **Active** — the primary visible state
- **Edge cases** — urgency levels, error states, disabled items, overflow
- **Interaction states** — hover, selected, expanded (render these statically in parallel, not behind a click)

Label each state with a small-caps state label inside the mockup section ("State 1 — At Rest", "State 2 — Expanded"). The label answers "what triggered this view?" in one line.

### Default and Empty States

The default state is where users spend their first session and where the feature looks broken if you skip it. Always mock it. For every list, table, chart, panel, or container that holds data, show what renders when the data isn't there yet.

Cover these defaults as applicable:

- **First-run / zero-config** — the feature exists but the user hasn't set it up. Include a one-line explanation of what this feature does and a single primary CTA ("Connect a source", "Create your first workspace"). No pretend data, no ghost rows.
- **Empty after filter/search** — user actions produced no results. Echo the query ("No results for 'foo'") and offer a way out (clear filters, broaden search). Visually distinct from first-run empty — this is a dead end, not a starting line.
- **Loading / skeleton** — grey blocks at the exact shape of the real content. Same height, same column count, same rhythm. Never a centered spinner on an empty page unless the whole route is blocked.
- **Partial / degraded** — some data loaded, some failed. Show what you have, mark what you don't (inline "Unavailable" chip, not a full-page error).
- **Error** — request failed. Include the reason in plain language and a retry affordance. Not a stack trace, not a generic "Something went wrong."
- **Permission denied / locked** — the user can see the feature exists but can't use it. Show the locked state with the unlock path (upgrade, request access, log in).
- **End-of-list / all-done** — positive terminal state for inboxes, task lists, feeds ("You're caught up"). Cheerful but not noisy.

### Empty-State Anti-Patterns

- **Skipping the empty state entirely** — reviewers assume the feature ships broken on day one
- **Filler rows** — fake "Example item" placeholders that a user might mistake for real data or, worse, try to click
- **Giant illustrations with no next step** — a friendly mascot is not a substitute for a CTA
- **Same visual as error state** — empty ≠ broken; don't reuse a red/warning treatment for "no data yet"
- **Hiding the chrome** — the surrounding shell (header, nav, filters) should still render, so users understand where they are

### Disabled and Inactive States

Use `opacity: 0.45–0.5` as the single signal for paused/disabled items. Don't hide them — the reviewer needs to see how inactive items coexist with active ones. One CSS rule communicates the semantic without markup clutter.

---

## Comparison Patterns

### Option Columns

When comparing 2-4 options, place them in a horizontal grid at equal width. Hold content constant across options — same data, same names, same numbers — so the only variable is the design treatment. Comparison is spatially guaranteed, not left to chance.

Give each option a **color-coded tag** (blue for A, pink for B, green for C). The color becomes a mnemonic — reviewers can say "the blue one" without remembering names.

### Before/After

When showing a redesign, put the current state and the proposed state side-by-side in a two-column grid with a 1px border divider. The 1px divider is visually neutral — contrast comes from content, not chrome.

### Comparison Tables

For systematic evaluation, include a table at the end with rows for each criterion and columns for each option. Use semantic coloring: green text for strengths, red for weaknesses, muted for neutral. Keep cells to one phrase — the table is for scanning, not reading.

### Flow Diagrams

For multi-step journeys, use a horizontal row of numbered cards connected by arrows. Each card has: a numbered circle, a tag showing effort level, a title, and a 1-2 line description. The whole flow is glanceable in one row.

---

## Annotation Patterns

### Semantic Callout Boxes

Color-coded boxes with a small-caps label and body text:
- **Green/teal** — "Why this works" or "What already exists"
- **Red** — "Problem" or "Current failure"
- **Amber** — Trade-off or caveat
- **Blue** — Implementation notes or technical context

These let reviewers scan for problems vs. positives without reading every word.

### Inline Annotations

When annotating a specific part of a mockup, place prose flush to the right of the mock at a fixed width (~320px). The reviewer never has to switch between the UI and the rationale — they'r