@polymorphism-tech/morph-spec 4.10.6 → 4.10.8

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

@@ -1,324 +1,425 @@
----
-name: morph-phase-uiux
-description: MORPH-SPEC Phase 1.5 (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.10.6"
----
-
-# MORPH UI/UX Design - Phase 1.5
-
-> 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
-
-- [ ] Phase 1 (Setup) completed
-- [ ] Feature has detected UI keywords (blazor, ui, component, page, dashboard, wizard, form, chart)
-- [ ] `uiux-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/**/*.razor` or `**/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 |
-| 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** `npx morph-spec template render docs/ui-mockups ...` | — |
-| Generate design system from existing CSS | **Bash** `npx morph-spec generate design-system --scan` | — |
-| Update state | **Bash** `npx morph-spec state mark-output ...` | — |
-
-**MCPs for this phase:** Playwright (preview, inspection, responsiveness), Context7 (component docs).
-
-**Anti-patterns:**
-- WebSearch for MudBlazor docs (use Context7 MCP — more precise)
-- 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
-npx morph-spec state get $ARGUMENTS
-```
-
-Check the `"phase"` field in the output:
-
-**If `"phase": "uiux"`** → correct phase, proceed.
-
-**If `"phase": "setup"`** → execute:
-1. `npx morph-spec phase advance $ARGUMENTS` (→ uiux)
-
-**Any other value** → do not proceed — inconsistent state, report to user.
-
-> **Rule:** Never write to `2-ui/` until the phase is `uiux`. The hook will block writes.
-
----
-
-### Step 0.5: Check Design System Exists
-
-**CRITICAL:** Before starting UI/UX phase, check if a design system exists:
-
-```
-Read: .morph/context/design-system.md
-```
-
-If the file doesn't exist (design system not found):
-
-1. **Option A - Automatic scaffold:**
-   - The system will automatically create a design system when advancing to implementation
-   - You can generate manually now: `npx morph-spec generate design-system`
-
-2. **Option B - Create manually:**
-   - Create `.morph/context/design-system.md` (project-level, shared)
-   - Or `.morph/features/$ARGUMENTS/2-ui/design-system.md` (feature-specific)
-
-3. **Option C - Scan existing CSS:**
-   - If the project already has CSS with variables: `npx morph-spec generate design-system --scan`
-
-**IMPORTANT:**
-- Design system is **mandatory** for UI features
-- Automatic gate will block implementation (Phase 5) if design system doesn't exist
-- Better to create now to ensure visual consistency
-
-### Step 1: Detect If Phase Is Needed
-
-Check if active agents include `uiux-designer`:
-
-```bash
-npx morph-spec state get $ARGUMENTS
-```
-
-If `uiux-designer` is NOT in `activeAgents`, skip this phase and continue to Phase 2 (Design).
-
-### Step 1.5: Design Thinking — Aesthetic Direction
-
-> **Ref:** `framework/standards/frontend/design-system/aesthetic-direction.md`
-
-**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 `ui-design-system.md`
-in section `## Aesthetic Direction` (template available in the standard above).
-
-**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:
-
-**Blazor stack:**
-- **Fluent UI Blazor** — dashboards, simple forms, AI components, Microsoft design language
-- **MudBlazor** — advanced data grids, complex charts, material design
-
-**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.
-
-### Step 4: Generate Deliverables
-
-Create the following files in `.morph/features/$ARGUMENTS/`:
-
-> **Use templates:** Use `npx 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. `ui-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 `ui-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`** (use template from `aesthetic-direction.md`):
-    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)
-
-#### 4.2. `ui-mockups.md`
-
-ASCII wireframes + descriptions:
-- General layout of each screen/page
-- Component positioning
-- Responsiveness (desktop, tablet, mobile)
-- States (loading, error, empty, success)
-
-#### 4.3. `ui-components.md`
-
-Technical specs for Fluent UI/MudBlazor components:
-- Component to use (FluentButton, MudDataGrid, etc.)
-- Props and configurations
-- Events and bindings
-- Validations and states
-
-#### 4.4. `ui-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 `ui-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 accessibility validation
-
----
-
-### 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
-npx morph-spec state mark-output $ARGUMENTS ui-design-system
-npx morph-spec state mark-output $ARGUMENTS ui-mockups
-npx morph-spec state mark-output $ARGUMENTS ui-components
-npx morph-spec state mark-output $ARGUMENTS ui-flows
-```
-
-> **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:
-> - `npx morph-spec state mark-output my-feature uiDesignSystem`
-> - `npx morph-spec state mark-output my-feature ui-design-system`
-
-## Generated Outputs
-
-- `.morph/features/$ARGUMENTS/2-ui/design-system.md`
-- `.morph/features/$ARGUMENTS/2-ui/mockups.md`
-- `.morph/features/$ARGUMENTS/2-ui/components.md`
-- `.morph/features/$ARGUMENTS/2-ui/flows.md`
-- `.morph/features/$ARGUMENTS/1-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
-  npx morph-spec approve $ARGUMENTS uiux
-  npx 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 | Path |
-|--------|------|
-| `uiDesignSystem` | `.morph/features/{feature}/2-ui/design-system.md` |
-| `uiMockups` | `.morph/features/{feature}/2-ui/mockups.md` |
-| `uiComponents` | `.morph/features/{feature}/2-ui/components.md` |
-| `uiFlows` | `.morph/features/{feature}/2-ui/flows.md` |
-<!-- /morph-outputs -->
-
----
-
+---
+name: morph-phase-uiux
+description: MORPH-SPEC Phase 1.5 (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.10.8"
+---
+
+# MORPH UI/UX Design - Phase 1.5
+
+> 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
+
+- [ ] Phase 1 (Setup) completed
+- [ ] Feature has detected UI keywords (blazor, 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/**/*.razor` or `**/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** `npx morph-spec template render docs/ui-mockups ...` | — |
+| Generate design system from existing CSS | **Bash** `npx morph-spec generate design-system --scan` | — |
+| Update state | **Bash** `npx morph-spec state mark-output ...` | — |
+
+**MCPs for this phase:** Playwright (preview, inspection, responsiveness), Context7 (component docs).
+
+**Anti-patterns:**
+- WebSearch for MudBlazor docs (use Context7 MCP — more precise)
+- 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
+npx morph-spec state get $ARGUMENTS
+```
+
+Check the `"phase"` field in the output:
+
+**If `"phase": "uiux"`** → correct phase, proceed.
+
+**If `"phase": "setup"`** → execute:
+1. `npx morph-spec phase advance $ARGUMENTS` (→ uiux)
+
+**Any other value** → do not proceed — inconsistent state, report to user.
+
+> **Rule:** Never write to `2-ui/` until the phase is `uiux`. The hook will block writes.
+
+---
+
+### Step 0.5: Check Design System Exists
+
+**CRITICAL:** Before starting UI/UX phase, check if a design system exists:
+
+```
+Read: .morph/context/design-system.md
+```
+
+If the file doesn't exist (design system not found):
+
+1. **Option A - Automatic scaffold:**
+   - The system will automatically create a design system when advancing to implementation
+   - You can generate manually now: `npx morph-spec generate design-system`
+
+2. **Option B - Create manually:**
+   - Create `.morph/context/design-system.md` (project-level, shared)
+   - Or `.morph/features/$ARGUMENTS/2-ui/design-system.md` (feature-specific)
+
+3. **Option C - Scan existing CSS:**
+   - If the project already has CSS with variables: `npx morph-spec generate design-system --scan`
+
+**IMPORTANT:**
+- Design system is **mandatory** for UI features
+- Automatic gate will block implementation (Phase 5) if design system doesn't exist
+- Better to create now to ensure visual consistency
+
+### Step 1: Detect If Phase Is Needed
+
+Check if active agents include `ui-designer`:
+
+```bash
+npx morph-spec state get $ARGUMENTS
+```
+
+If `ui-designer` is NOT in `activeAgents`, skip this phase and continue to Phase 2 (Design).
+
+### Step 1.5: Design Thinking — Aesthetic Direction
+
+> **Ref:** `framework/standards/frontend/design-system/aesthetic-direction.md`
+
+**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 `ui-design-system.md`
+in section `## Aesthetic Direction` (template available in the standard above).
+
+**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:
+
+**Blazor stack:**
+- **Fluent UI Blazor** — dashboards, simple forms, AI components, Microsoft design language
+- **MudBlazor** — advanced data grids, complex charts, material design
+
+**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.
+
+### Step 3.5: Visual Mockup (Playwright MCP)
+
+> **Purpose:** Generate a real HTML preview using project design tokens before writing formal specs.
+> Seeing the actual visual before committing to components prevents misaligned specs.
+
+#### 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/2-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/2-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/2-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/2-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/2-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:** `ui-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 `npx 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. `ui-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 `ui-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`** (use template from `aesthetic-direction.md`):
+    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)
+
+#### 4.2. `ui-mockups.md`
+
+ASCII wireframes + descriptions:
+- General layout of each screen/page
+- Component positioning
+- Responsiveness (desktop, tablet, mobile)
+- States (loading, error, empty, success)
+
+#### 4.3. `ui-components.md`
+
+Technical specs for Fluent UI/MudBlazor components:
+- Component to use (FluentButton, MudDataGrid, etc.)
+- Props and configurations
+- Events and bindings
+- Validations and states
+
+#### 4.4. `ui-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 `ui-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 accessibility validation
+
+---
+
+### 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
+npx morph-spec state mark-output $ARGUMENTS ui-design-system
+npx morph-spec state mark-output $ARGUMENTS ui-mockups
+npx morph-spec state mark-output $ARGUMENTS ui-components
+npx morph-spec state mark-output $ARGUMENTS ui-flows
+```
+
+> **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:
+> - `npx morph-spec state mark-output my-feature uiDesignSystem`
+> - `npx morph-spec state mark-output my-feature ui-design-system`
+
+## Generated Outputs
+
+- `.morph/features/$ARGUMENTS/2-ui/design-system.md`
+- `.morph/features/$ARGUMENTS/2-ui/mockups.md`
+- `.morph/features/$ARGUMENTS/2-ui/components.md`
+- `.morph/features/$ARGUMENTS/2-ui/flows.md`
+- `.morph/features/$ARGUMENTS/1-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
+  npx morph-spec approve $ARGUMENTS uiux
+  npx 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}/2-ui/design-system.md` |
+| `uiMockups` | `.morph/features/{feature}/2-ui/mockups.md` |
+| `uiComponents` | `.morph/features/{feature}/2-ui/components.md` |
+| `uiFlows` | `.morph/features/{feature}/2-ui/flows.md` |
+| `uiMockupHtml` | `.morph/features/{feature}/2-ui/mockup.html` |
+| `uiMockupMobile` | `.morph/features/{feature}/2-ui/mockup-mobile.png` |
+| `uiMockupTablet` | `.morph/features/{feature}/2-ui/mockup-tablet.png` |
+| `uiMockupDesktop` | `.morph/features/{feature}/2-ui/mockup-desktop.png` |
+<!-- /morph-outputs -->
+
+---
+
 Continue automatically to Phase 2 (Design) after approval.