design-analyze

name	design-analyze
description	Decompose a design requirement into flows, pages, templates, patterns, components, atoms, and data fields using Brad Frost atomic design. Use when starting a new design project, analyzing an app for redesign, or breaking down a feature brief. Triggers on 'analyze requirement', 'decompose this app', 'break down this brief'.
allowed-tools	["Read","Write","Bash","Glob","Grep","Edit","Agent","WebFetch","WebSearch","AskUserQuestion","Skill"]

Design Analyze

Decompose any design requirement into Brad Frost's atomic hierarchy: flows, pages, templates, patterns, components, atoms, and data fields.

1. Pre-flight

Check for an existing workspace:

Glob .design-workspace/*/state.json

If state.json exists, read it. Extract:

• project — the project name
• designSystemPath — path to the HTML Template design system
• currentPhase — confirm it is analyze or that analyze is not-started
• If analyze status is already complete, ask: "Analysis is already complete. Do you want to redo it or continue to the next phase?"

If no workspace exists, the orchestrator (/design) should have created one. If running standalone, create the workspace directory and state.json following the schema in skills/design/references/workspace-schema.md.

Read the design system manifest:

Read {designSystemPath}/manifest.json

Store the component list (Button, IconButton, Badge, Label, Chip, Tabs, SegmentControlBar, Thumbnail, InputField, Toast, DateGrid, Divider, Checkbox, Switch, RadioButton) and pattern list (TextBlock, StepIndicator, Stepper, ListItem) for matching later.

Read the pattern knowledge base:

Read references/patterns/saas-workflow-patterns.md

Store the page-level patterns (Dashboard / Home, Search Results / Listing Page, Detail Page, Form / Input Flow, Onboarding Flow, Settings / Preferences, Empty States, Bottom Sheet / Modal, Error & Status Pages, Profile / Account) for matching later.

Update state.json: set phases.analyze.status to "in-progress".

2. Gather Inputs

Follow references/input-handling.md for detailed processing of each input type.

2a. Determine Project Type

Ask the opening question:

Is this a new design from scratch or a revamp/redesign of an existing product?

If revamp/redesign, immediately ask:

Share the existing product so I can audit what's there:

• URLs of the live app/website (I'll capture screenshots of every key screen automatically)
• Screenshots you've already taken
• Figma link to the current design
• Any combination of the above

This helps me understand what exists today before we plan what changes.

If the user provides only a text description for a revamp (no URLs, screenshots, or Figma link), prompt them:

For a revamp, I need to see the current product to audit it properly. Can you share:

• The live URL (I'll screenshot it), or
• Screenshots of the current app, or
• A Figma link to the existing design?

Without visual reference I may miss existing patterns, inconsistencies, or what's working well.

2b. Capture Existing Product (Revamp Only)

When URLs are provided for a revamp, capture screenshots systematically and save them for the project record:

1. Use Playwright MCP tools: browser_navigate to open the URL, then browser_take_screenshot to capture the screen. If Playwright MCP is not available, try the Chrome MCP extension or ask the user to share screenshots manually.
2. Capture the FULL page — scroll to bottom capturing screenshots at each viewport-height increment. Many product pages have 10-15+ sections; capturing only the above-fold content will miss most of them.
3. Use browser_snapshot to get the full accessibility tree — this reveals every section, heading, link, and interactive element even below the fold.
4. Navigate through ALL navigation items, not just key flows — click every tab, menu item, and footer link. For each distinct screen, capture a full-page screenshot.
5. Capture at minimum: home/landing, onboarding (if accessible), every list/browse page, every detail page variant, creation/editing flows, settings/profile, help/support, and any distinctive screens.
6. Save each screenshot to {workspacePath}/analyze/existing-screens/:
   • Use descriptive filenames: home.png, search-results.png, product-detail.png, checkout-step1.png, etc.
   • Create the directory if it doesn't exist.
7. After capturing, present a summary:

I captured {N} screens from the existing product:

1. {filename} — {description}
2. {filename} — {description} ...

Are there any screens I missed? You can also drop additional screenshots into analyze/existing-screens/.

6. List EVERY section found on each page — not just main ones. For a typical product/landing page, expect 10-15+ sections (hero, features, testimonials, pricing, FAQ, footer, etc.). Missing even one section means extra iteration rounds later.
7. Analyze each captured screenshot for:
   • What's working well (good patterns to keep)
   • Pain points or inconsistencies (issues to fix in the redesign)
   • Components and patterns currently in use
   • Navigation and information architecture

CRITICAL: The wireframe and style phases will implement ALL sections identified here. If you miss sections now, the user will have to request them one-by-one later — each missing section = another frustrating iteration cycle.

Include an existingProductAudit section in the decomposition output (see Step 5).

2c. Gather Requirements

Ask:

Now tell me about the design. I can work with: text description, document (PDF/MD), additional URLs, more screenshots, Figma link, or any combination.

Process the user's response:

• Text brief — Parse for product name, audience, features, flows. Ask follow-up questions for any gaps: "Who is the primary user?", "What are the 3-5 core actions?", "Describe the most important user journey."
• Document — Read with the Read tool. For PDFs, use the pages parameter. Extract feature lists, user stories, flow descriptions, screen inventories.
• URLs — Use Playwright MCP tools: browser_navigate to open the URL, browser_take_screenshot to capture each screen, browser_snapshot to get the accessibility tree. Navigate through key flows by clicking primary navigation, CTAs, and menu items. Capture at minimum: home, a list page, a detail page, a creation flow, and settings.
• Screenshots — Read image files with the Read tool. Analyze each for layout structure, components, data fields, and navigation patterns.
• Figma link — Extract fileKey and nodeId from the URL. Use get_design_context to retrieve component structure. Use get_screenshot for visuals. Walk through all pages and frames.
• Combination — Process each input type independently, then merge and deduplicate findings.

After processing, compile a raw inventory:

• List of user flows identified
• List of screens/pages per flow
• List of UI components observed
• List of data fields observed

3. Analyze and Decompose

Transform the raw inventory into the atomic hierarchy.

Flows — Group pages into user journeys. Each flow has a clear start, goal, and sequence of pages. Common flows: onboarding, core task (CRUD), search/browse, settings/profile.

Pages — Each distinct screen. Match against the knowledge base patterns (saas-workflow-patterns.md). Set the knowledgeBase field to the matching pattern name, or null if no match.

Templates — Divide each page into layout zones: header, navigation, content area, sidebar, footer, action bar. Each zone is a template.

Patterns — Within each template, identify repeating UI groups: card grids, form groups, list sections, navigation bars, filter rows.

Components — Individual UI elements within each pattern. For each component:

1. Check the design system matching table in references/decomposition-schema.md
2. If it matches a manifest.json entry, set designSystem to the key (e.g., "Button") and designSystemVariant to the best variant
3. If no match, set designSystem: null — this flags it as a new component to create

Atoms — The smallest visual pieces of each component: icon, label-text, placeholder-text, background, border, shadow, divider-line, touch-target.

Data Fields — For each component that displays or captures data, list each field with name, type (text, number, date, email, url, boolean, enum, image), and an example value.

Count totals: totalFlows, totalPages, totalComponents. Count components where designSystem is null as newComponents.

For revamps only — add an existingProductAudit object to the decomposition:

{
  "existingProductAudit": {
    "screensCaptures": ["analyze/existing-screens/home.png", "..."],
    "keepPatterns": ["Bottom tab navigation", "Card-based listing"],
    "painPoints": ["Inconsistent button styles", "No empty states", "Dense settings page"],
    "navigationStructure": "Bottom tabs with 5 sections",
    "componentInventory": ["Custom card", "Standard button", "Search bar with filters"],
    "changeRecommendations": [
      { "area": "Navigation", "current": "5 tabs"     
    
  

4. Interactive Walkthrough

Present the decomposition to the user for review, one level at a time.

Flow level:

I've identified {N} flows:

1. {Flow Name} — {description} ({M} pages)
2. {Flow Name} — {description} ({M} pages)

Does this capture all the key user journeys? Any to add, remove, or rename?

Wait for confirmation or edits.

Page level (for each flow):

Flow: {Flow Name} Pages in this flow:

1. {Page Name} — {description} (matches: {knowledgeBase pattern})
2. {Page Name} — {description} (matches: {knowledgeBase pattern})

Does this look right?

Wait for confirmation or edits.

Component level (for each page):

Present a structured view:

{Page Name}

• Header
  • Navigation Bar: Back Button (IconButton), Page Title (Label), Action Button (IconButton)
• Content Area
  • Form Group: Name Input (InputField), Email Input (InputField)
  • Action Row: Submit Button (Button primary), Cancel Button (Button tertiary)

Components in green are from your design system. Components in bold italic are new (need to be created). Any changes?

Use guided choice at each level. Present the recommended structure with a star, and allow the user to choose alternatives:

Recommended navigation pattern: ★ Bottom Tab Bar (best for 3-5 top-level sections) Alternatives: Side Drawer, Top Tabs, Hub-and-spoke Which would you like?

Apply all user edits before moving to the next level.

5. Output Generation

decomposition.json

Write the final decomposition to {workspacePath}/analyze/decomposition.json following the full schema in references/decomposition-schema.md.

decomposition.html

Write a visual tree page to {workspacePath}/analyze/decomposition.html:

<!DOCTYPE html>
<html lang="en" data-theme="light">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>{project} — Design Decomposition</title>
  <link rel="preconnect" href="https://fonts.googleapis.com">
  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
  <link href="https://fonts.googleapis.com/css2?family=Geist:wght@100..900&family=Geist+Mono:wght@100..900&display=swap" rel="stylesheet">
  <link rel="stylesheet" href="{designSystemPath}/design-system.css">
</head>

Build the page with these design system components:

• ds-badge for counts (e.g., "3 pages", "12 components", "2 new")
• ds-text-block for flow and page descriptions
• ds-divider between major sections
• Nested cards showing the hierarchy: Flow > Pages > Templates > Patterns > Components
• Collapsible sections using <details>/<summary> for deep nesting
• Color indicators: green border/badge for design-system-matched components, amber border/badge for new components (designSystem: null)
• Include a summary header with total counts and a ratio of matched vs new components

Use inline styles for layout (flexbox/grid) and card styling. Keep the design system CSS for token values and component rendering.

6. State Update

Update state.json:

{
  "phases": {
    "analyze": {
      "status": "complete",
      "output": "analyze/decomposition.json",
      "completedAt": "{ISO 8601 timestamp}"
    }
  },
  "currentPhase": "inspire",
  "decisions": [
    ...existing,
    { "phase": "analyze", "key": "totalFlows", "value": "{N}", "timestamp": "..." },
    { "phase": "analyze", "key": "totalPages", "value":    
             
             
  

Announce completion:

Analysis complete! {N} flows, {M} pages, {K} components identified. {X} match your design system, {Y} are new and will need to be created.

Outputs:

• analyze/decomposition.json — structured data
• analyze/decomposition.html — visual tree (open in browser)

Ready for the next phase? Run /design-inspire to gather visual inspiration, or /design to see all options.