HTML Variant Sketching: Generating Disposable Design Mockups for Visual Comparison

This reference describes a lightweight workflow for producing 2-3 self-contained HTML mockups (variants) so that you can compare visual design directions side-by-side before committing to one. These are not production code; they are disposable sketches meant to be thrown away or promoted to real code only if preservation is needed.

When to Use This Skill

Use this workflow when you want to explore a UI/UX idea through interactive HTML variants. Typical triggers include:

• "sketch this screen"
• "show me what X could look like"
• "compare layout A vs B"
• "give me 2-3 takes on this UI"
• "let me see some variants"
• "mockup this before I build"

Do not use this skill when you need a production component, a polished one-off HTML artifact, a diagram, or a locked design. In those cases, redirect to claude-design, excalidraw, architecture-diagram, or just build it directly.

Prerequisites

• You have a design direction to explore (feel, references, core action) or are willing to provide them.
• Your environment supports creating directories and writing files (terminal access).
• Browser tools (browser_navigate, browser_vision) are available for visual verification.
• If using GSD conventions, a .planning/sketches/ directory may already exist; otherwise, create sketches/ in the repo root.

Capabilities

• Intake design feel, references, and core action from you (one question at a time)
• Generate 2-3 complete, self-contained HTML files, each taking a different design stance
• Create a README.md per variant documenting stance, key choices, trade-offs, and best-for
• Present a head-to-head comparison table with opinionated analysis
• Verify each variant visually using browser tools (browser_navigate + browser_vision) to catch layout bugs
• Support theming via shared tokens.css when the project has an existing visual identity
• Suggest next sketches via frontier mode (consistency gaps, unsketched screens, state coverage, responsive gaps, interaction patterns)
• Create a sketches/ directory (or .planning/sketches/ for GSD conventions) with subdirectories per variant

Full Sketch Workflow

The workflow follows a linear pipeline:

intake  →  variants  →  head-to-head  →  pick winner (or iterate)

Step 1: Intake

Ask you for three pieces of information, one question at a time. Reflect briefly before asking the next question. If you already provided all three, skip this step.

• Feel: Adjectives, emotions, or vibe the design should convey (e.g., "calm, editorial, like Linear")
• References: Apps, sites, or products that capture the desired feel
• Core action: The single most important thing a user does on this screen

Step 2: Variants

Produce 2-3 variants in one go. Each variant is a complete standalone HTML file. Pick one design axis (density, emphasis, aesthetic, layout, or grounding) and pull apart from it. Name each variant by its stance (e.g., "calm-editorial", "utilitarian-dense").

For each variant, create a subdirectory sketches/NNN-stance-name/ containing index.html and README.md. The directory structure looks like this:

sketches/
├── 001-calm-editorial/
│   ├── index.html
│   └── README.md
├── 001-utilitarian-dense/
│   ├── index.html
│   └── README.md
└── 001-playful-split/
    ├── index.html
    └── README.md

HTML Requirements

• Must be self-contained with inline CSS (no build step)
• Use system fonts or one Google Font via <link>; Tailwind via CDN is optional
• Use realistic fake content (actual sentences, not Lorem ipsum)
• Include interactivity: clickable links, hovers, at least one state transition (open/close, filter, toggle)
• Default CSS reset:

<style>
  * { box-sizing: border-box; margin: 0; padding: 0; }
  body {
    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto,
                 "Helvetica Neue", Arial, sans-serif;
    -webkit-font-smoothing: antialiased;
    color: #1a1a1a;
    background: #fafafa;
    line-height: 1.5;
  }
</style>

Step 3: Verify Each Variant Visually

Use browser tools to open the HTML file and check for layout bugs, overlapping text, unstyled elements, and broken images. Fix and re-navigate until correct.

browser_navigate(url="file:///absolute/path/to/sketches/001-calm-editorial/index.html")
browser_vision(question="Does this layout look clean and readable? Any visible bugs (overlapping text, unstyled elements, broken images)?")

Step 4: Write README.md per Variant

Each variant's README.md must follow this structure:

## Variant: {stance name}

### Design stance
One sentence on the principle driving this variant.

### Key choices
- Layout: ...
- Typography: ...
- Color: ...
- Interaction: ...

### Trade-offs
- Strong at: ...
- Weak at: ...

### Best for
- The kind of user or use case this variant actually serves

Step 5: Head-to-Head Comparison

Present a comparison table with dimensions such as density, primary action visibility, scan-ability, and feel. Include an opinionated take on which variant is strongest and why.

## Three takes on the home screen

| Dimension | Calm editorial | Utilitarian dense | Playful split |
|-----------|----------------|-------------------|---------------|
| Density   | Low            | High              | Medium        |
| Primary action visibility | Low | High | Medium |
| Scan-ability | High | Medium | Low |
| Feel | Calm, trusted | Sharp, tool-like | Inviting, energetic |

**My take:** Utilitarian dense for power users, calm editorial for content-forward audiences. Playful split is weakest — tries to do both and commits to neither.

Step 6: Let the User Pick

You can pick a winner, combine two into a hybrid, or ask for another round.

Theming Support

When the project has an existing visual identity, you can use shared CSS tokens. Create a file at sketches/themes/tokens.css:

/* sketches/themes/tokens.css */
:root {
  --color-bg: #fafafa;
  --color-fg: #1a1a1a;
  --color-accent: #0066ff;
  --color-muted: #666;
  --radius: 8px;
  --font-display: "Inter", sans-serif;
  --font-body: -apple-system, BlinkMacSystemFont, sans-serif;
}

Variants can then import these tokens using @import. If the tokens file is referenced but missing, either create it or skip theming entirely.

Frontier Mode: What to Sketch Next

If sketches already exist and you ask "what should I sketch next?", analyze the following:

• Consistency gaps: e.g., two winning variants used different button styles
• Unsketched screens: e.g., settings page referenced but not built
• State coverage: e.g., empty state not sketched
• Responsive gaps: e.g., only desktop validated
• Interaction patterns: e.g., no drag-and-drop

Propose 2-4 named candidates and let you pick. If no gaps are found, report that no gaps exist.

Parameters

Parameter	Meaning	Required
feel	Adjectives, emotions, or vibe the design should convey	Yes, unless already provided
references	Apps, sites, or products that capture the desired feel	Yes, unless already provided
core_action	Single most important thing a user does on this screen	Yes, unless already provided
number_of_variants	Number of variants to generate (2-3, never 1, rarely 4+)	No, defaults to 2-3
design_axis	Axis to differentiate variants: density, emphasis, aesthetic, layout, or grounding	No, pick one based on context
theme_tokens	Shared CSS tokens in sketches/themes/tokens.css	No, only if user has existing theme

Constraints and Caveats

• Do not use this skill when you want production code, a polished one-off HTML artifact, a diagram, or a locked design — use claude-design, excalidraw, architecture-diagram, or just build it instead.
• If the gsd-sketch sibling skill is installed (via npx get-shit-done-cc --hermes), that is the fuller workflow with persistent state; this skill is the lightweight standalone version.
• The upstream GSD project (gsd-build/get-shit-done) is archived/unmaintained on GitHub; the npm package get-shit-done-cc still installs but treat as archived community project. For the global variant, use npx get-shit-done-cc --hermes --global.
• Variants must differ in design stance, not just pixel values or accent colors.
• Each variant must be a single self-contained HTML file with inline CSS, no build step.
• Use system fonts or one Google Font via <link>; Tailwind via CDN is fine.
• Realistic fake content required (actual sentences, names, not Lorem ipsum).
• Must include interactivity: clickable primary action with visible state change, at least one meaningful state transition, hover effects on recognizable affordances.
• Verify each variant visually using browser_navigate + browser_vision; fix bugs before showing the user.
• Default CSS reset: box-sizing: border-box, margin: 0, padding: 0, system font stack, antialiased, color #1a1a1a, background #fafafa, line-height 1.5.
• Variant README.md must include design stance, key choices, trade-offs, best for.
• Head-to-head comparison must include a table and opinionated take.
• Create sketches/ directory (or .planning/sketches/ if using GSD conventions) in repo root.
• One subdirectory per variant: NNN-stance-name/index.html + README.md.
• Tell the user how to open files: open sketches/001-calm-editorial/index.html (macOS), xdg-open (Linux), start (Windows).
• Keep variants disposable; promote to real code only if preservation needed.
• Do not over-tokenize a throwaway sketch — three colors and one font is usually enough.
• Interactivity bar: click primary action with visible change, one meaningful state transition, hover affordances. More is over-engineering, less is a screenshot.

Failure Modes

• Insufficient design direction: If you provide no feel, references, or core action, you must be prompted for the missing information.
• Layout bugs: Generated HTML with overlapping text, unstyled elements, or broken images must be fixed via browser_vision before presenting.
• Superficial variants: If variants differ only in accent color, you cannot distinguish them; they must be redone with distinct stances.
• Frozen static image: If a variant has no interactivity, at least one state transition and hover effects must be added.
• Wrong tool: If you want production code or a polished artifact, this skill should not be used; redirect to the appropriate tool.
• Missing theme tokens: If a tokens file is referenced but missing, either create it or skip theming.
• No frontier candidates: If frontier mode analysis yields no candidates, report that no gaps were found.

Example Workflow

A typical session might look like this:

1. You say "sketch this screen for a task manager."
2. The intake asks for feel (e.g., "sharp, tool-like"), references (e.g., "Linear, Notion"), and core action (e.g., "create a task").
3. Two variants are generated: "utilitarian-dense" (compact, action-first) and "calm-editorial" (airy, content-first).
4. Each variant is built as a self-contained HTML file with realistic task data, a clickable add-task button that shows a modal or toast, and hover effects on rows.
5. Each variant is verified in the browser using browser_navigate and browser_vision. Bugs are fixed.
6. A comparison table is presented with an opinionated take.
7. You pick a winner, combine two into a hybrid, or ask for another round.

The terminal commands for creating and verifying a variant look like this:

terminal("mkdir -p sketches/001-calm-editorial")
write_file("sketches/001-calm-editorial/index.html", "<!doctype html>...")
write_file("sketches/001-calm-editorial/README.md", "## Variant: Calm editorial\n...")
browser_navigate(url="file://$(pwd)/sketches/001-calm-editorial/index.html")
browser_vision(question="How does this look? Any obvious layout issues?")

Notes on the sketch Command

The term sketch is used throughout this document to refer to the act of generating disposable HTML mockups. The gsd-sketch sibling skill (available via /gsd-sketch) provides a fuller workflow with persistent state, but this document describes the lightweight standalone version.

Version

This document was authored in 2025.