Design Blueprint

Design Blueprint

A four-phase process for turning a rough project idea into a frontend-ready design package: brand direction, user flows, key screen mockups, and a component spec. Each phase produces an artifact the next phase builds on. Don't skip phases or collapse them together: each one forces a level of clarity the next phase depends on, the same way spec-blueprint's phases do.

This skill is a sibling to spec-blueprint, not a dependency of it. It works completely standalone. If a spec-blueprint document (or any doc describing the product, users, and platform) already exists in the conversation or workspace, pull context from it instead of re-asking questions it already answers, but never require it.

Before starting: check for existing context

Look for a spec-blueprint doc, PRD, or similar already in the conversation or uploaded files. If one exists:

• Extract what's already answered (target users, platform, core flows, constraints) and skip re-asking those in Phase 1.
• Confirm your extraction briefly with the user before proceeding, for example: "I see you're building X for Y, I'll skip straight to brand direction questions."

If nothing exists, start fresh at Phase 1.

Phase 1: Interactive discovery

Ask the user one question at a time, the same discipline as spec-blueprint's Phase 1:

• Exactly one question per message. Never bundle multiple questions.
• Each question builds on the previous answer. Don't work off a fixed checklist.
• Keep questions concrete and answerable. Prefer tappable options where the answer is a short list of choices, and open text only when the answer is genuinely open-ended (naming reference brands, describing a target user).

Cover the ground needed before establishing a design direction:

• Product and audience: what it is, who it's for, platform(s) (web, mobile, both)
• Brand personality: a few forced-choice axes such as playful vs. serious, minimal vs. bold, corporate vs. approachable, quiet vs. energetic. Don't ask all axes as one mega-question; pick the ones most relevant to what they've said so far.
• References (optional): any brands, apps, or sites whose look they admire, and what specifically they like about them (colors, layout, tone of copy). If they have none, skip; personality answers are enough to proceed.
• Color/type constraints: any existing brand assets (logo, locked-in color, existing style guide) that must be respected.
• Core user flows: the two to five things a user does most in this product. This determines which flows get diagrammed and which screens get mocked up in Phase 3.
• Key screens: which specific screens matter most to see mocked up (usually three to six; more than that, ask the user to prioritize).
• Accessibility/compliance: any requirements (WCAG level, RTL support, colorblind-safe palettes, and so on).

Continue until the user signals they're done or you've run out of open questions that would change the direction. A thin Phase 1 produces generic branding, so don't rush it.

Phase 2: Brand direction

Once discovery wraps up, research and compile the brand direction.

Visual research: use image search to pull three to four reference images per relevant query (competitor apps, the brands the user named, or style keywords matching their personality answers, such as "minimal fintech app UI" or "playful productivity app design"). Use these to ground the direction in real visual precedent, not abstract description. Never reproduce or closely imitate a specific existing brand's actual logo or trade dress; use references for mood and pattern only (layout density, color temperature, type weight), and stay clearly clear of copying any single brand's distinctive look.

Produce a brand direction document covering:

• Personality summary: the axes from Phase 1, translated into a short descriptive paragraph a designer could work from.
• Color palette: primary, secondary, accent, neutrals, and semantic colors (success, error, warning), each with hex values and a one-line rationale tied to the personality summary. Check contrast ratios meet the accessibility level named in Phase 1.
• Typography: a font pairing (heading and body) with fallback stacks, a type scale (sizes for h1 through h6, body, caption), and why the pairing fits the personality.
• Voice and tone: three to four adjectives plus a short "how we sound" note, for example: "confident but not corporate, short sentences, no jargon."
• Imagery/iconography style: photography vs. illustration vs. icons-only, line weight, corner radius conventions, general visual texture. Default to no emoji as UI iconography or copy unless the user asks for them or the product is inherently casual/chat-based; use a proper icon set instead.
• Spacing and layout principles: base unit (for example a 4px or 8px grid), density (compact vs. airy).

This document is the single source of truth for Phase 3. Don't introduce new brand decisions later that didn't come from Phase 1 or get explicitly confirmed with the user.

Phase 3: User flows and key screens

User flows: for each core flow named in Phase 1, produce both:

1. A mermaid flowchart (renders in a markdown artifact).
2. A written step-by-step walkthrough of the same path, noting decision points, error/empty states, and where the flow can branch or exit.

Key screen mockups: for each key screen named in Phase 1, build a real HTML/CSS mockup (openable in a browser) that actually uses the palette, type scale, and spacing from Phase 2, not generic placeholder styling. Read the frontend-design skill before building these, for general layout and CSS craft guidance, and treat the Phase 2 brand direction doc as the source of truth for colors, type, and spacing rather than defaulting to generic conventions.

Each mockup should be a self-contained HTML file (CSS inline or in a <style> block) so it opens standalone in a browser without a build step.

UI craft checklist

Before treating a mockup as done, check it against these. This is the part that separates a real screen from a static picture of one:

• Visual hierarchy: one clear focal point per screen. Everything else recedes through size, weight, or color, not through adding more boxes.
• States covered, not just the happy path: default, hover, focus, active, disabled, error, empty, and loading for every interactive element that plausibly needs one. A form with no visible error state, or a list with no empty state, is unfinished.
• Focus visibility: every interactive element has a visible keyboard focus style. Don't rely on browser defaults alone if the rest of the design is custom.
• Responsive behavior: at minimum, note (in a comment or a companion line in the deliverable) how the layout should adapt at a mobile breakpoint, even if the mockup itself is a single fixed width. If mobile is a named platform from Phase 1, build the mobile mockup as its own file rather than a note.
• Motion, used sparingly: reserve animation for moments that answer a user's action (opening, confirming, expanding). Skip decorative hover transitions on every element and page-load fade-ins on every section; that reads as templated rather than considered.
• Copy is real, not lorem ipsum: every label, button, and empty/error state uses real, on-voice copy per the Phase 2 voice and tone. Buttons name the action they take ("Send invoice," not "Submit"), and errors state what happened and how to fix it without apologizing.
• Avoid generic AI-design tells: no unearned gradients, no identical rounded cards for every content type regardless of hierarchy, no tracked-out all-caps eyebrow labels, no decorative icons that don't map to a real action or status.

Phase 4: Component spec and handoff

Produce two linked artifacts:

Design tokens: a tokens file (CSS custom properties, for example :root { --color-primary: ...; --space-2: ...; --font-size-lg: ...; }, plus the same values as JSON) capturing every color, spacing step, type size, radius, and shadow used in Phase 2/3, so a developer can drop it straight into a build.

Component specs: for each distinct UI component that appears across the Phase 3 mockups (buttons, cards, nav, form fields, modals, and so on), document:

• Variants (primary/secondary/destructive, sizes)
• States (default, hover, focus, disabled, error, loading)
• Spacing/sizing rules referencing the tokens above
• Any behavior notes relevant to implementation, for example: "modal traps focus, closes on Escape"

Organize the deliverables on disk however fits the project best: a single combined doc, or split files (brand.md, flows.md, tokens.css/json, components.md) plus a /mockups folder for the HTML screens. Use your judgment the same way spec-blueprint does for its blueprint docs; there's no fixed structure to force.

Optional: frontend build prompts

After Phase 4, ask the user whether they want ready-to-execute frontend build prompts generated (one per screen/component, in the same style as spec-blueprint's Phase 4 code-gen prompts: self-contained, referencing the relevant tokens/component specs, building incrementally on prior steps). Only produce these if the user opts in; otherwise the design package itself is the finished deliverable.

Handling scale and skipped phases

If the user already has brand direction or mockups from elsewhere, start at whichever phase is next rather than re-deriving earlier phases. Confirm with the user what phase to start from if it's not obvious.

If the user wants to skip the one-at-a-time interview, ask once whether they want the full interactive Phase 1 or a compressed version (three to five grouped questions instead), and proceed with whichever they pick.