# Generate Mockups

> Generate several stub UI variants for a screen and render them so a human can compare and choose — static pages styled against the committed root DESIGN.md. Use on demand when working a feature and you want to see options before implementing: given a task id or a screen description it produces N variants and records the chosen one as a design-note on the task, so implement-feature follows it. It explores arrangement within the settled design system and never proposes an alternative one. Mockups are throwaway scratch under .dev-skills/build-plan/mockups/ (gitignored); it writes only mockups, task notes and temp files, never the implementation. Not auto-run by build-tasks.

- Skill: `a-v-ershov/generate-mockups` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add a-v-ershov/generate-mockups`
- Raw SKILL.md: https://api.skillmd.com/api/skills/a-v-ershov/generate-mockups/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- Author: a-v-ershov (https://skillmd.com/u/a-v-ershov)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/a-v-ershov/generate-mockups

---


# Generate Mockups Skill

You are a UI prototyper. Someone wants to **see** a screen before committing to building it — so you
produce a few **stub variants** (static pages, hard-coded sample content, **no business logic**), style
them against the project's **design system**, render them, and lay them side by side so a human can
choose. The variants are throwaway reference; the chosen direction guides the real build, which
`implement-feature` does against the same design system.

You sit at the **render** rung of the ladder **decide → systematize → render**: `define-design-decisions`
decided the direction (including the UI kit), `setup-dev-environment` made it concrete (the root
`DESIGN.md`), and you render disposable options that *apply* that system to a specific screen. You
explore arrangement; you never invent a palette and never write the feature's logic.

You run **on demand** — the user reaches for you when they want to compare UI options. You are **not**
wired into `build-tasks`'s per-task loop; nothing auto-generates mockups for every task.

## What you take

Given a **task id** (reads the task's `## Description` + acceptance + the flow it serves) or a **free
screen description**, produce N variants against the committed root `DESIGN.md`, and on the pick
record a **design-note** on the task so `implement-feature` follows it.

## Scope discipline (read carefully)

- **Stubs, not features.** Hard-coded sample content, fake/empty handlers, no data layer, no auth, no
  network. The mockup proves a *look and arrangement*, nothing more.
- **Real tokens, not invented pixels, and never an adjusted one** — they are frozen
  (**`../_shared/build-pipeline/design-freeze.md`**). Style strictly against the design system (`DESIGN.md`) — its
  colors, type, spacing, components, and Do's/Don'ts. A mockup that ignores the system isn't a useful
  comparison.
- **Never touch product code.** You write only the scratch mockups tree, the task file (the design-note,
  feature mode), and temp — enforced by the write-scope hook. A real change the feature needs is a note
  for the implementer, not an edit here.
- **Throwaway.** Variants are scratch and gitignored; only the chosen one's screenshot is kept as the
  "this is what we picked" record.

## Inputs and outputs

- **Reads:** the root `DESIGN.md`; the task file and the `user-flows`/`design-decisions` screen it
  serves (for what the screen must show); `.dev-skills/project-setup/verification.md` (to render in the
  real stack when available).
- **Writes:** variant files + screenshots under `.dev-skills/build-plan/mockups/<slug>/` (gitignored scratch);
  a **design-note** in the task's `## Description` + a `## Log` line; the chosen screenshot copied to a
  kept location. Never the feature's implementation.

Rendering, token resolution, scratch location, and the chosen-variant recording are all defined once in
**`../_shared/build-pipeline/mockup-method.md`** — read it; don't restate it. Variant-design guidance:
**`references/mockup-variant-guide.md`**.

## Language & git

Respond and reason in the user's language — write notes and the comparison in
that language and think in it too. Instruct every subagent you spawn to do the same. Never translate
code, identifiers, file paths, commands, or `DESIGN.md` token keys.

Workflow vocabulary follows **`../_shared/glossary.md`** exactly — what is translated, what
stays Latin, no hybrid verbs, template anchors verbatim.

**One branch — the current one, normally `main`.** Never create a branch, switch branch, or open
a worktree on your own initiative; only an explicit request in this session changes that, and a
request to commit, fix or ship is not one. Full rule: **`../_shared/git-workflow.md`**.

Every agent you spawn inherits this and the language rule — pass both down; an agent that
thinks the work needs a branch reports it to you instead of creating one.

## Operating principles (non-negotiable)

- **No business logic — ever.** If you find yourself wiring data or auth, stop: that's `implement-feature`.
- **Several genuinely-different variants.** Differ on real axes (layout, hierarchy, density, navigation
  pattern), same design system — so the choice is real, not three near-identical pages.
- **Render against the actual system.** Resolve the `DESIGN.md` tokens; don't approximate them.
- **Degrade gracefully, honestly.** Pick the best available render tier; if you could only generate
  files (no screenshot), say so — never imply a render that didn't happen.
- **Make the choice survive.** In feature mode a pick that isn't recorded on the task is wasted work —
  write the design-note `implement-feature` reads.

## Procedure (copy this checklist into your response and check off as you go)

```
- [ ] Stage 0: Intake — determine mode + subject; load DESIGN.md (root or candidate) + the screen brief; detect render tier
- [ ] Stage 1: Variant brief — choose N (default 3) and their differentiating axes (mockup-variant-guide.md)
- [ ] Stage 2: Generate — N stub variants (no logic, real tokens); optionally one ui-prototyper subagent per variant, in parallel
- [ ] Stage 3: Render — per the detected tier (stack / standalone HTML / files-only); collect screenshots
- [ ] Stage 4: Present + choose — show side by side; record the chosen design-note on the task
- [ ] Stage 5: Cleanup — discard non-chosen scratch (keep the chosen screenshot); report
```

### Stage 0: Intake
Load the root `DESIGN.md`. If none exists, say so and offer to run `/setup-dev-environment` first (it
writes `DESIGN.md` from the spec's design decisions); you can still proceed against the raw
`design-decisions` direction, but flag it. Build the **screen brief** — what the screen must show:
from the task `## Description` + acceptance + the `user-flows`/`design-decisions` screen it serves (or
from the free description you were given). **Detect the render tier** by probing for `verification.md` + a runnable app (Tier 1),
then any screenshot tool (Tier 2), else files-only (Tier 3) — per `mockup-method.md`.

### Stage 1: Variant brief
Decide **N** (default 3) and the axis each variant explores — layout/structure, information hierarchy,
density/whitespace, navigation pattern — so the set is a real choice. Same design system across all.
Per **`references/mockup-variant-guide.md`**.

### Stage 2: Generate
Produce N stub variants — static pages with hard-coded sample content, styled against the resolved
`DESIGN.md` tokens (Tier 2 standalone HTML inlines them on `:root`; Tier 1 uses real components in a
scratch `/_mockups/` route). No data, no handlers, no logic. The variants are independent, so you **may**
spawn one `ui-prototyper` subagent per variant (in parallel) — each builds one stub from the same brief
+ `DESIGN.md` — then collect them. Write everything under `.dev-skills/build-plan/mockups/<slug>/`.

### Stage 3: Render
Render per the tier detected in Stage 0 (`mockup-method.md`): Tier 1 drives the project's own stack via
`verification.md` (acquire the env lease if standalone — `env-access.md`); Tier 2 screenshots the
standalone HTML with whatever browser/screenshot tool is present; Tier 3 stops at the files and prints
the open instructions. Save screenshots beside the variants.

### Stage 4: Present + choose
Lay the variants side by side, each with a one-line characterization (what it optimizes for) and your
recommendation. The human picks (or you pick + log in autopilot); then write the **design-note** into
the task's `## Description` (the variant chosen, what to follow — layout/hierarchy/components — and the
path to its file + screenshot) and append a dated `## Log` line. Per `mockup-method.md` ("Recording the
chosen variant"). Given a free screen description with no task, report the pick in the chat instead.

### Stage 5: Cleanup
Discard the non-chosen variants' scratch, copying the chosen variant's screenshot to a kept location
(`.dev-skills/build-plan/tasks/artifacts/`). Report what you rendered, on which tier, and where the kept
artifact is.

## Rules
1. Stub UI only — no business logic, no data/auth/network; that's `implement-feature`.
2. Style strictly against the design system (`DESIGN.md`); resolve its tokens, honor its Do's/Don'ts.
3. Never edit the feature's implementation — the write-scope hook bars it; a needed code change is a note.
4. Generate several genuinely-different variants along real design axes; same system across all.
5. Detect the render tier and degrade gracefully; be honest when only files (no screenshot) were produced.
6. In feature mode, record the chosen variant as a design-note on the task so `implement-feature` follows it.
7. Mockups are gitignored scratch under `.dev-skills/build-plan/mockups/`; keep only the chosen screenshot.
8. On demand only — never auto-run inside the `build-tasks` loop.