@polymorphism-tech/morph-spec 4.22.0 → 6.0.0

package/framework/skills/level-1-workflows/morph-phase-uiux/SKILL.md

@@ -1,995 +0,0 @@
----
-name: morph-phase-uiux
-description: MORPH-SPEC Phase 2 (UI/UX). Creates design-system.md, mockups.md, components.md, and flows.md using Playwright/Context7 MCPs. Use after setup for features with frontend UI components, pages, dashboards, forms, wizards, or visual interactions requiring design documentation.
-argument-hint: "[feature-name]"
-user-invocable: false
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
-cliVersion: "4.22.0"
----
-
-# MORPH UI/UX Design - Phase 2
-
-> INTERNAL: Workflow skill used by /morph-proposal during automated phase orchestration. Not a user command.
-
-Conditional phase for features with front-end. Collects UI/UX requirements, generates wireframes, component specs, and user flows.
-
-## Prerequisites
-
-- [ ] Proposal approved by the user
-- [ ] Feature has detected UI keywords (ui, component, page, dashboard, wizard, form, chart)
-- [ ] `ui-designer` agent activated
-
-## Recommended Tools
-
-> **Ref:** `framework/skills/level-0-meta/morph-tool-usage-guide/SKILL.md` for complete guide.
-> **Ref:** `framework/standards/integration/mcp/mcp-tools.md` for MCP reference.
-
-| Action | Tool | Alternative |
-|--------|------|-------------|
-| Check existing design system | **Read** `.morph/context/design-system.md` | — |
-| Read user screenshots | **Read** (image file) | — |
-| Search for existing CSS variables | **Grep** `--root:` in `*.css,*.scss` | — |
-| Find existing components | **Glob** `**/components/**/*.tsx` | — |
-| UI component documentation | **Context7 MCP** `query_docs({ libraryId, query })` | **WebSearch** + **WebFetch** |
-| Preview existing page | **Playwright MCP** `browser_navigate()` + `browser_take_screenshot()` | **WebFetch** URL |
-| Generate visual mockup | **Playwright MCP** `browser_navigate()` + `browser_resize()` + `browser_take_screenshot()` | HTML file + manual screenshot |
-| Inspect page structure | **Playwright MCP** `browser_snapshot()` | **WebFetch** + manual parse |
-| Test responsive layout | **Playwright MCP** `browser_resize()` + `browser_take_screenshot()` | Manual testing |
-| External design references | **WebSearch** + **WebFetch** | — |
-| Render UI templates | **Bash** `morph-spec template render docs/ui-mockups ...` | — |
-| Generate design system from existing CSS | **Bash** `morph-spec generate design-system --scan` | — |
-| Update state | **Bash** `morph-spec state mark-output ...` | — |
-| Auto-detect dev server | **Glob** `next.config.*`, `vite.config.*`, `*.csproj` | **Read** `package.json` scripts |
-| Capture existing app | **Playwright MCP** `browser_navigate()` + `browser_take_screenshot()` | — |
-| Read Tailwind config | **Read** `tailwind.config.{js,ts}` | **Grep** `colors:` |
-| Trend research | **Context7 MCP** / **WebSearch** | — |
-| Generate AI screen designs | **Stitch MCP** `generate_screen_from_text()` + `fetch_screen_image()` | HTML mockup + Playwright (Step 3.5) |
-| Export design tokens from Stitch | **Stitch MCP** `fetch_screen_code()` | Manual design-system.md creation |
-| Download Stitch HTML exports | **Stitch MCP** `fetch_screen_code()` → save to `stitch-html/` | Step 3.5.0.5 |
-
-**MCPs for this phase:** Playwright (preview, inspection, responsiveness), Context7 (component docs), Stitch (optional: AI screen generation, design.md export).
-
-**Anti-patterns:**
-- Task agent to read a screenshot (use Read directly on image)
-- Guess component props (use Context7 for actual API)
-
----
-
-## Workflow
-
-### Step 0: Ensure uiux phase
-
-```bash
-morph-spec state get $ARGUMENTS
-```
-
-Check the `"phase"` field in the output:
-
-**If `"phase": "uiux"`** → correct phase, proceed.
-
-**If `"phase": "proposal"`** → execute in sequence:
-1. `morph-spec state mark-output $ARGUMENTS proposal`
-2. `morph-spec phase advance $ARGUMENTS` (→ uiux)
-
-**Any other value** → do not proceed — inconsistent state, report to user.
-
-> **Rule:** Never write to `1-ui/` until the phase is `uiux`. The hook will block writes.
-
----
-
-### Step 0.2: Capture Existing App (Playwright)
-
-> **Purpose:** Before analyzing tokens, capture visual screenshots of the existing app to understand current design patterns.
-> **Skip if:** Greenfield project (no existing UI pages).
-
-#### 0.2.1 — Auto-detect dev server
-
-Check in priority order:
-
-1. **`config.json`**: Read `.morph/config/config.json` → check for `project.devServerUrl` field → use if present
-2. **`package.json` port flags**: Read `package.json` scripts → scan for `--port`, `-p` flags → extract port
-3. **Next.js**: Glob `next.config.*` → try `http://localhost:3000`
-4. **Vite**: Glob `vite.config.*` → try `http://localhost:5173`
-5. **.NET**: Glob `**/Properties/launchSettings.json` → Read → extract `applicationUrl`
-
-Track: `detectedUrl` (string or null).
-
-#### 0.2.2 — Attempt connection
-
-If `detectedUrl` is not null:
-
-```
-mcp__plugin_playwright_playwright__browser_navigate({ url: detectedUrl })
-```
-
-- **Timeout:** 5 seconds
-- **If connects:** proceed to 0.2.3
-- **If fails (timeout/error):**
-
-```json
-{
-  "questions": [{
-    "header": "Dev Server",
-    "question": "Could not connect to dev server at {detectedUrl}. How to proceed?",
-    "multiSelect": false,
-    "options": [
-      { "label": "Start server first", "description": "I'll start the dev server — wait for me" },
-      { "label": "Use different URL", "description": "I'll provide the correct URL (Other)" },
-      { "label": "Skip screenshots", "description": "Continue without existing app screenshots" }
-    ]
-  }]
-}
-```
-
-If `detectedUrl` is null (no indicators found):
-
-```json
-{
-  "questions": [{
-    "header": "Existing UI?",
-    "question": "Does this project have existing UI pages I should capture?",
-    "multiSelect": false,
-    "options": [
-      { "label": "Yes, provide URL", "description": "I'll provide the URL in the field below (Other)" },
-      { "label": "No, greenfield", "description": "Skip — this is a new project" }
-    ]
-  }]
-}
-```
-
-#### 0.2.3 — Screenshot main pages
-
-Once connected, take screenshots of up to 5 pages:
-
-1. **Current page** (usually home/root)
-2. Navigate to common routes: `/dashboard`, `/admin`, `/settings`, or detect from sidebar links via `browser_snapshot()`
-3. For each page:
-   ```
-   mcp__plugin_playwright_playwright__browser_resize({ width: 1440, height: 900 })
-   mcp__plugin_playwright_playwright__browser_take_screenshot({})
-   ```
-4. Save screenshots to `.morph/features/$ARGUMENTS/1-ui/existing-*.png`
-
-#### 0.2.4 — Visual analysis
-
-Analyze the captured screenshots and write `.morph/features/$ARGUMENTS/1-ui/existing-ui-analysis.md`:
-
-> **Note:** This is an intermediate artifact — NOT a tracked output in `output-schema.js`. It will not appear in `state mark-output`. Advisory warnings from `task-tracking-guard.js` are expected.
-
-```markdown
-# Existing UI Analysis — {Feature}
-
-## Visual Summary
-- **Color palette:** [dominant colors observed]
-- **Typography:** [serif/sans/mono, approximate weights, scale]
-- **Layout:** [sidebar/topbar/fullwidth, grid system, card patterns]
-- **Sophistication level:** [basic/intermediate/advanced]
-- **Dark/Light mode:** [which mode detected, or both]
-
-## Design Tokens Detected Visually
-- Primary color: [approx hex from screenshots]
-- Background: [surface colors observed]
-- Border style: [rounded/sharp, thickness]
-- Shadow style: [flat/elevated/colored]
-
-## Patterns Worth Preserving
-- [List patterns that work well and should be maintained]
-
-## Opportunities for Improvement
-- [List areas where modern techniques could improve the UI]
-```
-
-This analysis feeds into Step 0.5 (cross-check with extracted tokens) and Step 1.5 (domain-adaptive direction).
-
----
-
-### Step 0.5: Check Design System
-
-**This step is MANDATORY and must always run before Step 1.**
-
-#### Step 0.5.1 — Scan frontend for design tokens (ALWAYS)
-
-Search for existing design tokens across ALL supported stacks. Run these scans in parallel:
-
-**A. CSS Custom Properties (all stacks):**
-Glob these patterns (exclude `node_modules/`, `.next/`, `dist/`, `build/`, `obj/`, `bin/`):
-```
-wwwroot/**/*.css
-wwwroot/**/*.scss
-styles/**/*.css
-src/styles/**/*.css
-src/**/*.css
-src/**/*.scss
-src/**/*.module.css
-public/**/*.css
-app/**/*.css
-```
-For each file found, Grep for `:root {` blocks containing `--` custom properties.
-
-**B. Tailwind Config (Next.js / Vite):**
-Glob: `tailwind.config.{js,ts,mjs,cjs}`
-If found, Read the file and extract:
-- `theme.colors` / `theme.extend.colors` → map to color tokens
-- `theme.fontFamily` → map to font tokens
-- `theme.spacing` → map to spacing tokens
-- `theme.borderRadius` → map to radius tokens
-
-**C. shadcn/ui Config:**
-Glob: `components.json`
-If found and contains `"style"` field, also scan `src/lib/utils.ts` or `lib/utils.ts` for CSS var references.
-
-**D. Global theme files:**
-Glob: `**/theme.{ts,js}`, `**/tokens.{ts,js}`, `**/design-tokens.{ts,js}`
-If found, Read and extract exported color/spacing/font objects.
-
-Classify ALL found tokens into:
-- **Colors**: `--color-*`, hex values, rgb()
-- **Fonts**: `--font-*`, `font-family:`, fontFamily config
-- **Spacing**: `--space-*`, `--gap-*`, spacing config
-- **Radius**: `--radius-*`, borderRadius config
-- **Shadows**: `--shadow-*`, boxShadow config
-
-Track: `tokensFound` (object by category), `tokenSources` (array of {file, stack, tokenCount}).
-
-#### Step 0.5.2 — Check if design-system.md exists
-
-```
-Read: .morph/context/design-system.md
-```
-
-Track: `dsExists` (bool).
-
-#### Step 0.5.3 — Decision tree (4 cases)
-
-| Case | Condition | Action |
-|------|-----------|--------|
-| **A** | `dsExists` AND `cssTokensFound` | Cross-check DS vs scanned tokens. If >2 colors diverge, flag misalignment and ask user if they want to update DS with `AskUserQuestion`. Proceed to Step 1. |
-| **B** | `dsExists` AND NOT `cssTokensFound` | Print: `✓ Design system found (no CSS tokens to cross-check)`. Proceed to Step 1. |
-| **C** | NOT `dsExists` AND tokens found | Auto-generate `.morph/context/design-system.md` from ALL scanned token sources (CSS vars, Tailwind config, etc.). Merge tokens from multiple sources, preferring Tailwind/Theme config over raw CSS. If Step 0.2 produced `existing-ui-analysis.md`, cross-reference visual analysis with extracted tokens. Proceed to Step 1. |
-| **D** | NOT `dsExists` AND NOT `cssTokensFound` | Greenfield project. Ask user for aesthetic direction + brand color using `AskUserQuestion` (same options as morph-init). Scaffold from template. Proceed to Step 1. |
-| **E** | Stitch MCP available AND `design.md` found in project root | Parse Stitch design.md, extract color/typography/spacing/radius/shadow tokens, map into `.morph/context/design-system.md` template. If `dsExists`, merge (Stitch fills gaps, manually-set tokens preserved). Add changelog entry. Proceed to Step 1. |
-
-**Case E — Stitch design.md integration:**
-
-> **Prerequisite:** Stitch MCP detected (tools matching pattern `stitch` found) OR a `design.md` file exists in the project root.
-
-1. If Stitch MCP is available, check for existing projects:
-   ```
-   stitch__list_projects({})
-   ```
-   If projects exist, list screens and fetch the design export:
-   ```
-   stitch__list_screens({ projectId: selectedProjectId })
-   stitch__fetch_screen_code({ screenId: screenId })
-   ```
-
-2. If `design.md` exists in project root (manual export from Stitch), read it directly.
-
-3. Parse the design.md content and map tokens into `design-system.md` template sections:
-   - Color values → `## Color Tokens` (map to `--color-primary`, `--color-accent`, etc.)
-   - Font families/sizes → `## Typography` (map to `--font-display`, `--font-body`)
-   - Spacing values → `## Spacing Tokens`
-   - Border radius → `## Border Radius Tokens`
-   - Shadow definitions → `## Shadow Tokens`
-
-4. Write or merge into `.morph/context/design-system.md` using the existing template structure.
-
-5. Add changelog entry:
-   `- [today's date] [morph-phase-uiux] Tokens imported from Stitch design.md ({N} tokens)`
-
-Print: `✓ Design system populated from Stitch design — .morph/context/design-system.md`
-
-**Case C — auto-generate from scanned tokens:**
-
-Create `.morph/context/design-system.md` with these sections populated from scan results:
-- `## Color Tokens` → `:root { }` block with all found color variables (preserve exact variable names)
-- `## Typography` → found font-family values (map by variable name heuristic: `--font-display` vs `--font-body`)
-- `## Spacing Tokens` → found spacing variables
-- `## Aesthetic Direction` → `#TODO` (requires user judgment, fill in manually)
-- `## Changelog` → `- [today's date] [morph-phase-uiux] Auto-generated from CSS scan ([N] tokens from [files])`
-
-Print: `✓ Design system generated from [N] tokens — .morph/context/design-system.md`
-
-> **Design system is mandatory** for UI features. The implementation gate (Phase 7) will block if no design system exists.
-
-## MANDATORY: Session Tasks
-
-> **BEFORE starting UI/UX work**, analyze the workflow below and create session tasks.
->
-> **Rules:** Minimum 3 tasks, typically 5-7. Mark `in_progress` before starting, `completed` after.
->
-> **Typical tasks:** design system check, user input collection, UI library selection, visual mockup, deliverable generation, accessibility validation, approval
-
-### Step 1: Detect If Phase Is Needed
-
-Check if active agents include `ui-designer`:
-
-```bash
-morph-spec state get $ARGUMENTS
-```
-
-If `ui-designer` is NOT in `activeAgents`, skip this phase and continue to Phase 3 (Design).
-
-### Step 1.3: Trend Research
-
-> **Purpose:** Before defining aesthetic direction, research current design trends relevant to this project's domain.
-> Use Context7 MCP or web search for current design trends.
-
-#### 1.3.1 — Research current trends
-
-> **MCP:** Use **WebSearch** to research current design trends for the detected domain (e.g., "{currentYear} UI design trends {detectedDomain}"). WebSearch provides real-time results that are more current than any static reference. If WebSearch is not available, use **Context7 MCP** to query UI library documentation for latest component patterns and best practices. If neither is available, rely on your training knowledge of current design trends.
-
-Research current design trends relevant to the project's domain and stack. Identify 3-5 techniques that fit the project.
-
-#### 1.3.2 — Detect project domain
-
-Scan `.morph/features/$ARGUMENTS/0-proposal/proposal.md` for domain keywords:
-
-| Domain | Keywords |
-|--------|----------|
-| SaaS Dashboard | dashboard, analytics, metrics, monitoring, kpi, chart |
-| E-commerce | e-commerce, store, product, cart, checkout, catalog |
-| Landing Page | landing, marketing, site, hero, launch, waitlist |
-| Internal Tool | admin, backoffice, internal, settings, management |
-| Social/Community | social, feed, community, chat, post, notification |
-
-Count keyword hits per domain. Use the domain with most hits. If zero hits across all domains, skip domain-specific filtering.
-
-#### 1.3.3 — Research current trends (optional enhancement)
-
-If Context7 MCP or WebSearch is available:
-- Search: "{currentYear} UI design trends {detectedDomain}"
-- Extract 2-3 additional techniques not in the curated catalog
-- Evaluate if they are production-ready (browser support, performance)
-
-#### 1.3.4 — Present recommendations
-
-Use `AskUserQuestion` to present 3-4 recommended modern techniques:
-
-```json
-{
-  "questions": [{
-    "header": "Trends",
-    "question": "Based on your project domain ({detectedDomain}), these modern techniques are recommended. Which ones do you want to incorporate?",
-    "multiSelect": true,
-    "options": [
-      { "label": "{Technique 1}", "description": "{Brief description + when to use}" },
-      { "label": "{Technique 2}", "description": "{Brief description + when to use}" },
-      { "label": "{Technique 3}", "description": "{Brief description + when to use}" },
-      { "label": "None / custom", "description": "Skip trends or describe your own preference (Other)" }
-    ]
-  }]
-}
-```
-
-Selected trends feed into Step 1.5 (Aesthetic Direction) and Step 4 (Deliverables).
-
----
-
-### Step 1.5: Design Thinking — Aesthetic Direction
-
-**BEFORE collecting technical requirements**, define visual direction with 4 questions:
-
-1. **Purpose**: What problem does it solve? Who uses it? What is the professional context?
-2. **Tone**: What direction? (Minimal Refined / Editorial / Soft Professional / Industrial / Modern Luxury)
-3. **Differentiation**: What is the 1 memorable element of this interface?
-4. **Constraints**: Framework, performance budget, existing brand guidelines
-
-**CRITICAL:** Commit to direction BEFORE technical specs. Document in `design-system.md`
-in section `## Aesthetic Direction` (template available in the standard above).
-
-#### Domain-Adaptive Patterns
-
-After defining aesthetic direction, apply domain-specific pattern suggestions:
-
-Based on the domain detected in Step 1.3.2, suggest domain-adaptive patterns:
-
-| Domain | Preferred Directions | Key Patterns to Suggest |
-|--------|---------------------|------------------------|
-| SaaS Dashboard | Industrial, Minimal Refined | Dense bento grid KPIs, skeleton loaders, sidebar glassmorphism, dark mode default |
-| E-commerce | Modern Luxury, Soft Professional | Product card hover lift, CTA colored shadows, image-first layouts, scroll galleries |
-| Landing Page | Editorial, Modern Luxury | Hero aurora gradient, scroll-driven narrative, fluid typography, overlapping layers |
-| Internal Tool | Industrial, Minimal Refined | Compact forms, dense tables, status chips, monospace data displays |
-| Social/Community | Soft Professional, Editorial | Card feed, notification badges, avatar systems, drawer navigation |
-
-If the user's chosen direction conflicts with domain recommendations (e.g., Industrial for E-commerce), present an `AskUserQuestion` advisory:
-
-```json
-{
-  "questions": [{
-    "header": "Direction",
-    "question": "You chose {direction} for a {domain} project. The recommended directions are {recommended}. Keep your choice or adapt?",
-    "multiSelect": false,
-    "options": [
-      { "label": "Keep {direction}", "description": "I have specific reasons for this choice" },
-      { "label": "Switch to {recommended[0]}", "description": "{Brief rationale}" }
-    ]
-  }]
-}
-```
-
-#### Integration with Selected Trends
-
-Incorporate the trends selected in Step 1.3.4 into the aesthetic direction documentation:
-
-- Add selected trends to `## Aesthetic Direction` in `design-system.md`
-- Document how each trend maps to the chosen direction
-
-**Anti-patterns to avoid:**
-- Purple gradient on white background (AI cliche)
-- Inter/Roboto as display font
-- 3-column card grid without visual differentiation
-- 5-color palette with equal weight (without dominant + accent)
-
-### Step 2: Collect User Input
-
-**ALWAYS ask the user FIRST:**
-
-1. **Layout and style**:
-   - Do you have any layout ideas in mind?
-   - Do you have visual references? (sites, apps, screenshots)
-   - How do you envision the user flow?
-
-2. **Components and interactions**:
-   - What are the main components of this screen/page?
-   - What states need to be considered? (loading, error, empty, success)
-
-3. **Reference images**:
-   - Do you have example images I can analyze?
-   - If YES: use Read tool to read screenshots and extract patterns
-
-### Step 3: Choose UI Library
-
-Detect the stack from `.morph/config/config.json` and recommend the appropriate library:
-
-**Next.js stack:**
-- **shadcn/ui + Radix** (recommended) — composable primitives, full control, Tailwind-native
-- **MUI** — feature-rich, enterprise-grade, material design
-
-**Document the decision as an ADR in `decisions.md`** with: context, options considered, decision, and rationale.
-
-> **MCP:** After selecting the UI library, use **Context7 MCP** (`resolve-library-id` → `query-docs`) to fetch the library's latest component API (e.g., shadcn/ui primitives, Radix props, MUI component APIs). This ensures component specs in `components.md` reference real, current props — not outdated or hallucinated ones. If Context7 is not available, use **WebSearch** + **WebFetch** to check the official component documentation.
-
-### Step 3.5: Visual Mockup (Playwright MCP or Stitch MCP)
-
-> **Purpose:** Generate a real visual preview using project design tokens before writing formal specs.
-> Seeing the actual visual before committing to components prevents misaligned specs.
-
-#### 3.5.0 — Stitch MCP Path (Alternative to HTML Mockup)
-
-> **Skip if:** Stitch MCP is NOT available. Fall through to 3.5.1 (HTML mockup).
-> **Use when:** Stitch MCP is detected and user wants AI-generated screen designs.
-
-If Stitch MCP is available, present the user with a choice:
-
-```json
-{
-  "questions": [{
-    "header": "Design Tool",
-    "question": "Stitch MCP is available for AI-generated screen designs. How would you like to create visual mockups?",
-    "multiSelect": false,
-    "options": [
-      { "label": "Use Stitch", "description": "Generate screens via Google Stitch AI — higher fidelity, exportable design.md" },
-      { "label": "Use HTML mockup", "description": "Generate HTML file + Playwright screenshots — current default workflow" }
-    ]
-  }]
-}
-```
-
-**If "Use Stitch" selected:**
-
-1. **Create or select project:**
-   ```
-   stitch__create_project({ name: "{feature-name}-design" })
-   ```
-   Or if project already exists (from Case E in Step 0.5.3), reuse it.
-
-2. **Generate screens from design brief:**
-   Build a prompt from the aesthetic direction (Step 1.5), selected trends (Step 1.3), and user input (Step 2):
-   ```
-   stitch__generate_screen_from_text({
-     projectId: projectId,
-     prompt: "Create a {detectedDomain} screen with {aestheticDirection} direction. Colors: {primaryColor}, {accentColor}. Font: {fontPair}. Layout: {layoutDescription}. Features: {componentList}"
-   })
-   ```
-
-3. **Fetch screen images for review:**
-   ```
-   stitch__list_screens({ projectId: projectId })
-   stitch__fetch_screen_image({ screenId: screenId })
-   ```
-   Save images to `.morph/features/$ARGUMENTS/1-ui/stitch-screen-*.png`
-
-4. **Present to user for feedback** (same approval loop as 3.5.3):
-   - Show Stitch-generated screen images
-   - Ask: "Does this visual direction match your intent?"
-   - Iterate: regenerate via `generate_screen_from_text` with refined prompts
-
-5. **Export design tokens:**
-   ```
-   stitch__fetch_screen_code({ screenId: approvedScreenId })
-   ```
-   Parse the design.md export and update `.morph/context/design-system.md` with any new or refined tokens.
-
-6. **Skip to Step 4** — Stitch screens replace the HTML mockup. `mockups.md` still documents states and interactions textually.
-
-> **Key advantage:** Unlike screenshots, the Stitch MCP transmits real HTML/CSS code via `fetch_screen_code()`.
-> This produces dramatically higher fidelity results than screenshot-based workflows because Claude Code
-> receives the actual component structure, CSS properties, and design tokens — not pixel approximations.
-> Use `react-components` or `shadcn-ui` companion skills to convert Stitch HTML into production React components.
-
-#### 3.5.0.5 — Download Stitch HTML Exports (after screen approval)
-
-> **Purpose:** Save the actual HTML/CSS from each Stitch screen so implementation agents can reference
-> real structure and styles instead of relying solely on text descriptions in mockups.md.
-> **Skip if:** Stitch path was not chosen, or no screens were approved.
-
-1. **Create stitch-html directory:**
-   ```bash
-   mkdir -p .morph/features/$ARGUMENTS/1-ui/stitch-html/
-   ```
-
-2. **For each approved screen**, fetch the full HTML:
-   ```
-   stitch__fetch_screen_code({ screenId: approvedScreenId })
-   ```
-   Save the returned HTML content to:
-   `.morph/features/$ARGUMENTS/1-ui/stitch-html/{screenId}.html`
-
-   > If `fetch_screen_code()` returns a structured object, extract the `.html` or `.code` field.
-
-3. **Auto-generate CSS mapping from design-system.md:**
-   Read `.morph/context/design-system.md` and extract all CSS custom properties (`--color-*`, `--font-*`, `--space-*`).
-   Scan each downloaded HTML file's `<style>` block for color literals, font families, and spacing values.
-   Produce a best-effort mapping file at `.morph/features/$ARGUMENTS/1-ui/stitch-html/stitch-css-map.json`:
-
-   ```json
-   {
-     "mappings": [
-       { "stitchValue": "#6366f1", "projectToken": "var(--color-primary)", "type": "color" },
-       { "stitchValue": "Inter", "projectToken": "var(--font-body)", "type": "font" }
-     ],
-     "unmapped": ["#ff0000"],
-     "source": ".morph/context/design-system.md"
-   }
-   ```
-
-   If no `design-system.md` exists, create the file with empty mappings:
-   ```json
-   { "mappings": [], "unmapped": [], "source": null, "note": "No design system found — use Stitch values directly" }
-   ```
-
-4. **Ask user for screen-to-route mapping:**
-   Use `AskUserQuestion` to map each screen to an app route. Present all screens in one call (up to 4 per call):
-
-   ```json
-   {
-     "questions": [{
-       "header": "Route Map",
-       "question": "Which app route does screen '{screenTitle}' correspond to?",
-       "multiSelect": false,
-       "options": [
-         { "label": "/{screenTitleLower}", "description": "Inferred from screen title" },
-         { "label": "/", "description": "Home/landing page" },
-         { "label": "Skip", "description": "This screen has no direct route" }
-       ]
-     }]
-   }
-   ```
-
-   For more than 4 screens, make sequential `AskUserQuestion` calls.
-
-5. **Create `stitch-screen-map.json`:**
-   Save to `.morph/features/$ARGUMENTS/1-ui/stitch-screen-map.json`:
-   ```json
-   {
-     "version": "1.0.0",
-     "projectId": "{stitchProjectId}",
-     "generatedAt": "{ISO timestamp}",
-     "screens": [
-       {
-         "screenId": "{screenId}",
-         "title": "{screenTitle}",
-         "route": "/dashboard",
-         "htmlFile": "stitch-html/{screenId}.html",
-         "screenshotFile": "stitch-screen-{index}.png",
-         "device": "desktop"
-       }
-     ],
-     "cssMapFile": "stitch-html/stitch-css-map.json"
-   }
-   ```
-
-6. **Update mockups.md** to reference downloaded HTML files.
-   Add a section at the top of `mockups.md`:
-
-   ```markdown
-   ## Stitch HTML Reference
-
-   This feature has Stitch HTML exports for implementation fidelity.
-   See `stitch-screen-map.json` for the full screen-to-route mapping.
-
-   | Screen | Route | HTML File |
-   |--------|-------|-----------|
-   | {title} | {route} | `stitch-html/{screenId}.html` |
-   ```
-
-7. **Mark output:**
-   ```bash
-   morph-spec state mark-output $ARGUMENTS stitchHtml
-   ```
-
----
-
-**If "Use HTML mockup" selected:**
-→ Proceed to 3.5.1 (existing workflow, unchanged)
-
----
-
-#### 3.5.1 — Generate HTML Mockup
-
-Create an HTML file that represents the main screen/layout using **real tokens from `.morph/context/design-system.md`**:
-
-**Rules for the HTML:**
-- `<style>` block must have `:root { }` with real values from design-system.md (not Tailwind colors)
-- Tailwind CDN only for layout utilities (flex, grid, padding) — NOT for colors or typography
-- Represents real layout hierarchy and visual weight — not ASCII
-- Include representative content (realistic text, placeholder images)
-- All colors via CSS variables: `color: var(--color-primary)` not `color: #3b82f6`
-
-**Save to:** `.morph/features/$ARGUMENTS/1-ui/mockup.html`
-
-Example structure:
-```html
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>[Feature] Mockup</title>
-  <link rel="preconnect" href="https://fonts.googleapis.com">
-  <!-- Load fonts from design-system.md font pair -->
-  <script src="https://cdn.tailwindcss.com"></script>
-  <style>
-    /* Real tokens from .morph/context/design-system.md */
-    :root {
-      --color-primary: [value from design-system.md];
-      --color-accent: [value from design-system.md];
-      --color-surface: [value from design-system.md];
-      --color-text-primary: [value from design-system.md];
-      --color-text-secondary: [value from design-system.md];
-      --font-display: [value from design-system.md];
-      --font-body: [value from design-system.md];
-      /* ... add all relevant tokens ... */
-    }
-    body {
-      font-family: var(--font-body);
-      background-color: var(--color-surface);
-      color: var(--color-text-primary);
-    }
-    h1, h2, h3 { font-family: var(--font-display); }
-  </style>
-</head>
-<body>
-  <!-- Layout representing the feature's main screen -->
-</body>
-</html>
-```
-
-#### 3.5.2 — Screenshot at 3 Breakpoints
-
-**Navigate to the file:**
-```
-mcp__plugin_playwright_playwright__browser_navigate({ url: "file:///[ABSOLUTE_PATH_TO].morph/features/$ARGUMENTS/1-ui/mockup.html" })
-```
-
-**Take screenshots at 3 breakpoints** (resize then screenshot for each):
-
-**Mobile (375px):**
-```
-mcp__plugin_playwright_playwright__browser_resize({ width: 375, height: 812 })
-mcp__plugin_playwright_playwright__browser_take_screenshot({}) → save as .morph/features/$ARGUMENTS/1-ui/mockup-mobile.png
-```
-
-**Tablet (768px):**
-```
-mcp__plugin_playwright_playwright__browser_resize({ width: 768, height: 1024 })
-mcp__plugin_playwright_playwright__browser_take_screenshot({}) → save as .morph/features/$ARGUMENTS/1-ui/mockup-tablet.png
-```
-
-**Desktop (1440px):**
-```
-mcp__plugin_playwright_playwright__browser_resize({ width: 1440, height: 900 })
-mcp__plugin_playwright_playwright__browser_take_screenshot({}) → save as .morph/features/$ARGUMENTS/1-ui/mockup-desktop.png
-```
-
-#### 3.5.3 — Present and Iterate
-
-1. **Show all 3 screenshots to the user**
-2. Ask for feedback:
-   - "Does this visual direction match your intent?"
-   - "Any layout, color, or typography adjustments?"
-3. **Iterate:** Refine `mockup.html` → re-take screenshots → show updated previews
-4. **Continue only when user approves** this visual direction
-
-> **Note:** `mockups.md` (Step 4.2) continues to exist as the reference for states and interactions.
-> The PNGs are the visual reference; the .md covers behavior and edge cases.
-
----
-
-### Step 4: Generate Deliverables
-
-Create the following files in `.morph/features/$ARGUMENTS/`:
-
-> **Use templates:** Use `morph-spec template render` to generate files from templates in `.morph/framework/templates/docs/`. Available templates: `ui-design-system`, `ui-mockups`, `ui-components`, `ui-flows`.
-
-#### 4.1. `design-system.md`
-
-**If project-level design system exists (`.morph/context/design-system.md`):**
-- Reference it in specs: "Uses project design system at .morph/context/design-system.md"
-- Create `design-system.md` only if there are feature-specific colors/components
-
-**If it doesn't exist:**
-- Create complete feature-level design system with:
-  - **Section `## Aesthetic Direction`**:
-    direction, font pair, color philosophy, motion intent, composition approach
-  - Color palette (primary, secondary, accent, semantic)
-  - Typography (heading scales, body text, code)
-  - Spacing and layout (grid, margins, paddings)
-  - Base components (buttons, inputs, cards)
-
-**If Stitch was used (Step 3.5.0):**
-- Derive `design-system.md` primarily from Stitch's exported design.md
-- Map Stitch tokens into existing template sections (Color Tokens, Typography, Spacing, etc.)
-- Cross-reference with tokens from Step 0.5 — preserve manually-set tokens, let Stitch values fill gaps
-- Add to `## Aesthetic Direction`: "Visual direction generated via Google Stitch (project: {projectName})"
-- Ensure all CSS custom properties use the standard `--color-*`, `--font-*`, `--space-*` naming convention
-
-#### 4.2. `mockups.md`
-
-ASCII wireframes + descriptions:
-- General layout of each screen/page
-- Component positioning
-- Responsiveness (desktop, tablet, mobile)
-- States (loading, error, empty, success)
-
-#### 4.3. `components.md`
-
-Technical specs for UI library components:
-- Component to use (Button, DataTable, etc.)
-- Props and configurations
-- Events and bindings
-- Validations and states
-
-#### 4.4. `flows.md`
-
-Complete user flows:
-- User stories
-- Flow diagrams (text/ASCII)
-- Edge cases (what happens if...?)
-- Validations and feedback
-
-### CHECKPOINT: Validate UI Deliverables
-
-**PAUSE - Before proceeding to accessibility:**
-
-- [ ] Aesthetic direction defined and documented in `design-system.md`?
-- [ ] Font pair specified (not just Inter/Roboto for display)?
-- [ ] Color philosophy: dominant + accent + rationale documented?
-- [ ] Design system defined (project-level or feature-level)?
-- [ ] Wireframes cover all states (loading, error, empty, success)?
-- [ ] Components specified with actual props from chosen UI library?
-- [ ] Complete user flows with edge cases?
-- [ ] Chosen UI library documented as ADR in `decisions.md`?
-
-**If any checkbox is NOT checked:**
-→ Go back and complete the missing deliverable
-
-**If ALL checkboxes are checked:**
-→ Proceed to image assets spec (Step 4.5) or accessibility validation (Step 5)
-
----
-
-### Step 4.5: Generate Image Assets Spec (`assets.md`)
-
-> **Skip if:** Feature has no UI components, no mockups, no Stitch screens.
-> **Skip if:** No images needed (pure data/form UI with no visual assets).
-> **MCP:** Gemini Image MCP (optional — used for preview generation only).
-> **Standard:** `frontend/design-system/ai-image-generation.md`
-
-When the feature has UI components that need images (hero sections, brand panels, illustrations, empty states):
-
-1. **Identify image requirements:**
-   Scan these sources for image references:
-   - `mockups.md` — look for image placeholders, illustrations, photos
-   - `stitch-screen-map.json` (if exists) — Stitch designs reference Google-hosted images that need production replacements
-   - `components.md` — components listing image props or visual areas
-
-2. **Read design system context:**
-   ```
-   Read: .morph/context/design-system.md
-   ```
-   Extract: aesthetic direction, primary/accent/background colors, font pair.
-
-3. **Ask user to confirm image requirements:**
-
-   ```json
-   {
-     "questions": [{
-       "header": "Image Assets",
-       "question": "I identified these images needed for the feature. Which should we include in assets.md?",
-       "multiSelect": true,
-       "options": [
-         { "label": "{image1 purpose}", "description": "{route} — {aspect ratio}" },
-         { "label": "{image2 purpose}", "description": "{route} — {aspect ratio}" },
-         { "label": "None needed", "description": "Skip image asset generation entirely" }
-       ]
-     }]
-   }
-   ```
-
-4. **For each confirmed image**, ask for prompt refinement:
-
-   ```json
-   {
-     "questions": [{
-       "header": "IMG-001",
-       "question": "Prompt for {purpose}: '{auto-generated prompt based on design context}'. Adjust?",
-       "multiSelect": false,
-       "options": [
-         { "label": "Use as-is", "description": "The prompt looks good" },
-         { "label": "Adjust", "description": "I want to refine the prompt (Other)" }
-       ]
-     }]
-   }
-   ```
-
-5. **Generate `assets.md`:**
-   Write to `.morph/features/$ARGUMENTS/1-ui/assets.md`:
-
-   ```markdown
-   # Image Assets — {feature}
-
-   ## Design Context
-   - Aesthetic: {from design-system.md}
-   - Primary: {--color-primary value}
-   - Background: {--color-background value}
-   - Accent: {--color-accent value}
-   - Font pair: {display + body fonts}
-
-   ## Assets
-
-   ### IMG-001: {Descriptive Name}
-   - **Purpose:** {What this image represents in the UI}
-   - **Route:** {App route where it appears}
-   - **Component:** {React component name}
-   - **Aspect Ratio:** {1:1 | 3:2 | 16:9 | etc.}
-   - **Output Path:** `public/images/{feature}/{kebab-name}.png`
-   - **Prompt:** "{Narrative prompt with design system colors and aesthetic direction injected}"
-   - **Priority:** {high | medium | low}
-   ```
-
-6. **Optional — Generate preview images:**
-   If Gemini Image MCP is available, offer to generate preview images for user approval:
-
-   ```json
-   {
-     "questions": [{
-       "header": "Previews",
-       "question": "Gemini Image MCP is available. Want to generate preview images now for approval?",
-       "multiSelect": false,
-       "options": [
-         { "label": "Yes, generate previews", "description": "Generate images now for visual approval before implement phase" },
-         { "label": "Skip previews", "description": "Generate during implement phase instead" }
-       ]
-     }]
-   }
-   ```
-
-   If yes: invoke `/morph-gemini-image` for each asset, save previews to `1-ui/asset-previews/`, show to user for feedback. Iterate prompts if needed.
-
----
-
-### Step 5: Validate Accessibility and Responsiveness
-
-Document in UI files:
-- **WCAG 2.1 Level AA** compliance
-  - Adequate color contrast
-  - Accessible labels for screen readers
-  - Keyboard navigation
-- **Responsive breakpoints**
-  - Desktop (>1200px)
-  - Tablet (768px - 1199px)
-  - Mobile (<768px)
-
-### Step 6: Update State
-
-```bash
-morph-spec state mark-output $ARGUMENTS ui-design-system
-morph-spec state mark-output $ARGUMENTS ui-mockups
-morph-spec state mark-output $ARGUMENTS ui-components
-morph-spec state mark-output $ARGUMENTS ui-flows
-# Only if Stitch path was used (stitch-screen-map.json exists):
-morph-spec state mark-output $ARGUMENTS stitchHtml
-```
-
-> **Format note:** The `mark-output` commands accept BOTH kebab-case (`ui-design-system`)
-> AND camelCase (`uiDesignSystem`). Both formats work equally! Use whichever is more
-> comfortable for you. Examples:
-> - `morph-spec state mark-output my-feature uiDesignSystem`
-> - `morph-spec state mark-output my-feature ui-design-system`
-
-## Generated Outputs
-
-- `.morph/features/$ARGUMENTS/1-ui/design-system.md`
-- `.morph/features/$ARGUMENTS/1-ui/mockups.md`
-- `.morph/features/$ARGUMENTS/1-ui/components.md`
-- `.morph/features/$ARGUMENTS/1-ui/flows.md`
-- `.morph/features/$ARGUMENTS/2-design/decisions.md` (updated with UI library ADR)
-
-### Step 7: Validate Design with Frontend Review
-
-After generating all 4 UI outputs and updating state (Step 6):
-
-```bash
-/frontend-review $ARGUMENTS
-```
-
-The skill validates: WCAG token contrast, existence of all outputs, static design accessibility, and generates mockup screenshots if dev server is available.
-
-**If frontend-review blocks**, fix issues before presenting to user.
-
----
-
-## MANDATORY PAUSE
-
-Use `AskUserQuestion` to capture explicit approval before advancing:
-
-```json
-{
-  "questions": [{
-    "header": "Approval",
-    "question": "UI/UX generated. Approve to advance to technical design?",
-    "multiSelect": false,
-    "options": [
-      { "label": "Approve UI/UX", "description": "Advance to technical design phase" },
-      { "label": "I have feedback", "description": "Type what you want to adjust in the field below (Other)" }
-    ]
-  }]
-}
-```
-
-- **"Approve UI/UX"** →
-  ```bash
-  morph-spec approve $ARGUMENTS uiux
-  morph-spec phase advance $ARGUMENTS
-  ```
-- **"I have feedback" or "Other"** → apply the received feedback and repeat this PAUSE
-
-## Advancement Criteria
-
-- [x] User input collected (layout, references)
-- [x] UI library chosen and justified (ADR)
-- [x] 4 deliverables created (design-system, mockups, components, flows)
-- [x] WCAG 2.1 accessibility documented
-- [x] Responsiveness specified
-- [x] State updated
-- [x] User approved UI/UX
-
----
-
-## Phase Outputs
-
-<!-- morph-outputs:uiux -->
-| Output | Caminho |
-|--------|---------|
-| `uiDesignSystem` | `.morph/features/{feature}/1-ui/design-system.md` |
-| `uiMockups` | `.morph/features/{feature}/1-ui/mockups.md` |
-| `uiComponents` | `.morph/features/{feature}/1-ui/components.md` |
-| `uiFlows` | `.morph/features/{feature}/1-ui/flows.md` |
-| `stitchHtml` | `.morph/features/{feature}/1-ui/stitch-screen-map.json` |
-<!-- /morph-outputs -->
-
----
-
-Continue automatically to Phase 3 (Design) after approval.