Design Mockup Web

Output directory: ~/.agentic-workflow/<repo-slug>/

Codebase Navigation

Prefer Serena for all code exploration — LSP-based symbol lookup is faster and more precise than file scanning.

Preamble — Bootstrap Check

Before running this skill, verify the environment is set up:

# Derive repo slug
REMOTE_URL=$(git remote get-url origin 2>/dev/null || echo "")
if [ -n "$REMOTE_URL" ]; then
  REPO_SLUG=$(echo "$REMOTE_URL" | sed 's|.*[:/]\([^/]*/[^/]*\)\.git$|\1|;s|.*[:/]\([^/]*/[^/]*\)$|\1|' | tr '/' '-')
else
  REPO_SLUG=$(basename "$(pwd)")
fi
echo "repo-slug: $REPO_SLUG"

# Check bootstrap status
SKILLS_OK=true
for s in review postReview addressReview enhancePrompt bootstrap rootCause bugHunt bugReport shipRelease syncDocs weeklyRetro officeHours productReview archReview withInterview design-analyze design-analyze-web design-analyze-ios design-language design-evolve design-evolve-web design-evolve-ios design-mockup design-mockup-web design-mockup-ios design-implement design-implement-web design-implement-ios design-refine design-verify design-verify-web design-verify-ios verify-app verify-web verify-ios; do
  [ -d "$HOME/.claude/skills/$s" ] || SKILLS_OK=false
done

BRIDGE_OK=false
lsof -i TCP:3100 -sTCP:LISTEN &>/dev/null && BRIDGE_OK=true

RULES_OK=false
[ -d ".claude/rules" ] && [ -n "$(ls -A .claude/rules/ 2>/dev/null)" ] && RULES_OK=true

echo "skills-symlinked: $SKILLS_OK"
echo "bridge-running: $BRIDGE_OK"
echo "rules-directory: $RULES_OK"

Domain rules in .claude/rules/ load automatically per glob — no action needed if rules-directory: true.

If SKILLS_OK=false or BRIDGE_OK=false, ask the user via AskUserQuestion:

"Agentic Workflow is not fully set up. Run setup.sh now? (yes/no)"

If yes: run bash <path-to-agentic-workflow>/setup.sh (resolve path from the review skill symlink target). If no: warn that some features may not work, then continue.

If RULES_OK=false (and SKILLS_OK and BRIDGE_OK are both true), do not offer setup.sh. Instead, show:

"Domain rules not found — run /bootstrap to generate .claude/rules/ for this repo."

Create the output directory for this repo:

mkdir -p "$HOME/.agentic-workflow/$REPO_SLUG"

Session Context

Load prior work state for this repo from prism-mcp before starting.

1. Derive a topic string — synthesize 3–5 words from the skill argument and task intent:

• /officeHours add dark mode → "dark mode UI feature"
• /rootCause TypeError cannot read properties → "TypeError cannot read properties"
• /review 42 → use the PR title once fetched: "PR {title} review"
• No argument → use the most specific descriptor available: "{REPO_SLUG} {skill-name}"

2. Load context from prism-mcp:

mcp__prism-mcp__session_load_context — project: REPO_SLUG, level: "standard",
  toolAction: "Loading session context", toolSummary: "<skill-name> context recovery"

Store the returned expected_version — you will need it at Session Close.

3. Surface results:

• If the response contains a non-empty summary or prior decisions:

  Prior context: {summary} Use this to inform your approach before continuing.

• If prism-mcp returns an error, surface it and stop:

  "prism-mcp unavailable: {error}. Ensure prism-mcp is running and registered."

Session Close

Run at the end of every skill, after all work is complete and the report has been shown to the user.

Save a structured ledger entry and update the live handoff state for this repo.

1. Save ledger entry (immutable audit trail):

mcp__prism-mcp__session_save_ledger — project: REPO_SLUG,
  conversation_id: "<skill-name>-<ISO-timestamp, e.g. 2026-04-08T14:32:00Z>",
  summary: "<one paragraph describing what was accomplished this session>",
  todos: ["<any open items left incomplete>", ...],
  files_changed: ["<paths of files created or modified>", ...],
  decisions: ["<key decisions made during this skill run>", ...]

2. Update handoff state (mutable live state for next session):

mcp__prism-mcp__session_save_handoff — project: REPO_SLUG,
  expected_version: <value returned by session_load_context>,
  open_todos: ["<open items not yet completed>", ...],
  active_branch: "<current git branch from: git branch --show-current>",
  last_summary: "<one sentence: what this skill just did>",
  key_context: "<critical facts the next session must know — constraints, decisions, blockers>"

If either call fails, surface the error:

"prism-mcp session save failed: {error}. Context may not persist to next session."

Design Context — Load Design Language

Block 1: Load design language

1. Read .impeccable.md if it exists:
   • Note the brand personality and aesthetic direction
   • Note the ## Sources section: the URLs used to build the design tokens
2. Read design-tokens.json if it exists (W3C DTCG: colors, typography, spacing)
3. Read planning/DESIGN_SYSTEM.md if it exists (component catalog, design principles)

If none exist and this skill requires design context:

"No design language found. Run /design-language [url1 url2...] to synthesize from reference materials, then retry."

Block 2: Dynamic component inventory

Run the following scan and surface results as context before proceeding with the skill's own steps.

Part A: Component library detection

Read package.json (if it exists) and check dependencies + devDependencies for known libraries:

Cross-reference with the ## Sources URLs from .impeccable.md — if a source URL matches a known component library's docs site (e.g., ui.shadcn.com, radix-ui.com, mantine.dev), note it as the detected library even if package.json doesn't yet include it.

For iOS: check Swift files for import SwiftUI (standard) or third-party component libs.

Part B: Repo primitive scan

Glob("src/components/**/*.{tsx,jsx,ts,js}")
Glob("components/**/*.{tsx,jsx,ts,js}")
Glob("app/components/**/*.{tsx,jsx,ts,js}")
Glob("ui/src/components/**/*.{tsx,jsx,ts,js}")
Glob("**/*.swift", limit to top 2 directory levels)

Collect file names (not contents), deduplicate, and derive component names from filenames (e.g., button.tsx → Button, card-header.tsx → CardHeader).

Surface as a context note before proceeding:

Component context:
  Library:    shadcn/ui (detected from package.json + impeccable.md sources)
  Primitives: Button, Card, Input, Dialog, Badge, Separator (+7 more)

  Use these components in mockups and implementations before inventing new ones.

If no library and no primitives found: note "No component library or repo primitives detected — generate from scratch using design tokens."

Block 3: Orchestration overview

Design pipeline:
  /design-language [urls]  →  synthesize tokens + brand personality
  /design-mockup <screen>  →  HTML (web) or SwiftUI (iOS) mockup
  /design-implement        →  production code from approved mockup
  /design-refine           →  Impeccable polish pass
  /design-verify           →  screenshot diff vs mockup baseline

  /design-evolve  can run anytime to merge new reference materials.

Design Mockup — Generate HTML Mockup from Design Language

Generate an HTML mockup using the visual companion, informed by the design language. Iterate with user feedback until approved, then capture a baseline screenshot for verification.

Step 1: Validate Arguments

The user must provide a screen name (e.g., "dashboard", "login", "settings", "onboarding").

If no screen name provided:

"Usage: /design-mockup <screen-name> Example: /design-mockup dashboard"

Step 2: Load Design Context

Read .impeccable.md and design-tokens.json to understand:

• Color palette and semantic color usage
• Typography scale and font choices
• Spacing system and layout approach
• Brand personality and aesthetic direction

These values must drive every visual decision in the mockup.

Step 3: Generate HTML Mockup

Create an HTML file as a content fragment for the visual companion. The mockup should:

1. Be a single HTML file with inline CSS (no external dependencies except CDN fonts)
2. Use exact token values from design-tokens.json — colors, font sizes, spacing, radii
3. Reflect the brand personality from .impeccable.md — not generic Bootstrap/Tailwind defaults
4. Be responsive — include viewport meta tag and basic responsive breakpoints
5. Include realistic content — use plausible text and data, not "Lorem ipsum"

Save to the visual companion's session directory:

.superpowers/brainstorm/<session-id>/<screen-name>.html

Step 4: Present in Browser

Start the visual companion server:

*/start-server.sh *

The mockup will be visible in the browser for the user to review.

Step 5: Iterate

Use AskUserQuestion to gather feedback from the user. Common adjustments:

• Layout changes (reorder sections, change grid)
• Color refinements (too much contrast, wrong emphasis)
• Typography tweaks (heading sizes, body line-height)
• Content density (too sparse, too crowded)
• Missing elements (navigation, footer, status indicators)

Apply changes to the HTML file and continue asking via AskUserQuestion until the user approves.

Step 6: Capture Baseline

Once approved, save the baseline screenshot for /design-verify:

mkdir -p "$HOME/.agentic-workflow/$REPO_SLUG/design"

Use an Agent subagent with Playwright MCP tools to capture the screenshot. The subagent should:

1. Navigate to the mockup URL served by the visual companion
2. Take a full-page screenshot
3. Save it to the baseline path

Baseline path:

~/.agentic-workflow/<repo-slug>/design/mockup-<screen-name>.png

Step 7: Report

Mockup Approved
===============

Screen:    <screen-name>
File:      .superpowers/brainstorm/<session-id>/<screen-name>.html
Baseline:  ~/.agentic-workflow/<repo-slug>/design/mockup-<screen-name>.png

Next steps:
  • Run /design-implement web|swiftui to generate production code
  • Run /design-mockup <another-screen> to mockup additional screens
  • Run /design-refine to apply Impeccable refinements

Rules

• Every color, font size, and spacing value must come from design-tokens.json — no hardcoded values
• The mockup is a design artifact, not production code — optimize for visual fidelity, not code quality
• Include hover states and interactive affordances in the HTML/CSS
• If .impeccable.md doesn't exist, warn but still allow creation with manual style guidance
• Save only ONE baseline per screen name — re-running overwrites the previous baseline after confirmation