@polymorphism-tech/morph-spec 4.11.1 → 4.12.0

package/README.md

@@ -3,7 +3,7 @@
 > Spec-driven development framework for multi-stack projects. Turns feature requests into implementation-ready code through structured, AI-orchestrated phases.
 
 **Package:** `@polymorphism-tech/morph-spec`
-**Version:** 4.11.1  
+**Version:** 4.12.0  
 **Requires:** Node.js 18+, Claude Code
 
 ---
@@ -370,4 +370,4 @@ Code generated by morph-spec (contracts, templates, implementation output) belon
 
 ---
 
-*morph-spec v4.11.1 by [Polymorphism Tech](https://polymorphism.tech)*
+*morph-spec v4.12.0 by [Polymorphism Tech](https://polymorphism.tech)*

package/claude-plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "morph-spec",
-  "version": "4.11.1",
+  "version": "4.12.0",
   "displayName": "MORPH-SPEC Framework",
   "description": "Spec-driven development with 38 agents and 8-phase workflow for .NET/Blazor/Next.js/Azure",
   "publisher": "polymorphism-tech",

package/docs/CHEATSHEET.md

@@ -198,4 +198,4 @@ These files are never edited directly. Use CLI commands or `morph-spec update` i
 
 ---
 
-*morph-spec v4.11.1 by Polymorphism Tech*
+*morph-spec v4.12.0 by Polymorphism Tech*

package/docs/QUICKSTART.md

@@ -197,4 +197,4 @@ morph-spec doctor
 
 ---
 
-*morph-spec v4.11.1 by Polymorphism Tech*
+*morph-spec v4.12.0 by Polymorphism Tech*

package/framework/agents.json

@@ -1282,7 +1282,7 @@
       "teammate": {
         "role": "CSS & Design System Specialist",
         "icon": "🎨",
-        "spawn_prompt": "You are the CSS & Design System Specialist (FASE 5 only). MANDATORY FIRST STEP: Read .morph/context/design-system.md. Validate all CSS follows the design system (no off-palette hardcoded colors, no inline styles with raw values). Enforce naming conventions (BEM for custom classes). Verify WCAG AA contrast (4.5:1 text, 3:1 UI). Run design-system, css, contrast validators. Any missing tokens must be added to design-system.md before proceeding."
+        "spawn_prompt": "You are the CSS & Design System Specialist (FASE 5 only). MANDATORY FIRST STEP: Read .morph/context/design-system.md. Validate all CSS follows the design system — colors (var(--color-*)), spacing (var(--space-*)), typography (var(--font-*, --text-*)), motion (var(--duration-*, --easing-*)), shadows (var(--shadow-*)), and advanced effects (var(--glass-*, --aurora-*, --perspective-*)). No off-palette hardcoded colors, no inline styles with raw values. Enforce naming conventions (BEM for custom classes). Verify WCAG AA contrast (4.5:1 text, 3:1 UI). Ref: framework/standards/frontend/design-system/design-trends.md for modern technique catalog. Run design-system, css, contrast validators. Any missing tokens must be added to design-system.md before proceeding."
       }
     },
     "seo-growth-hacker": {
@@ -1988,7 +1988,11 @@
         "design system",
         "css",
         "color palette",
-        "spacing"
+        "spacing",
+        "motion tokens",
+        "glassmorphism",
+        "design trends",
+        "advanced effects"
       ],
       "validators": [
         "design-system"
@@ -2008,13 +2012,16 @@
       "teammate": {
         "icon": "🎨",
         "role": "Design System Validator (read-only)",
-        "spawn_prompt": "You are the Design System Validator (Tier 4, READ-ONLY). Scan CSS/SCSS and component files for design system compliance:\n\n1. Color palette — look for hardcoded hex/rgb colors instead of CSS variables (var(--color-primary), var(--color-secondary), etc.)\n2. Spacing — look for hardcoded px/rem values instead of spacing variables (var(--spacing-*))\n3. Typography — look for hardcoded font-size/font-family instead of typography variables (var(--font-*))\n4. Component naming — verify PascalCase for Blazor components (.razor) and kebab-case for CSS classes\n5. Check .morph/context/design-system.md if it exists for project-specific design tokens\n\nUse Grep and Glob to scan. Do NOT modify any files.\n\nOutput a JSON object: { \"passed\": boolean, \"issues\": [{ \"file\": string, \"line\": number, \"message\": string, \"severity\": \"warning\" }] }"
+        "spawn_prompt": "You are the Design System Validator (Tier 4, READ-ONLY). Scan CSS/SCSS and component files for design system compliance:\n\n1. Color palette — look for hardcoded hex/rgb colors instead of CSS variables (var(--color-primary), var(--color-accent), var(--color-surface-*), var(--color-text-*), etc.)\n2. Spacing — look for hardcoded px/rem values instead of spacing variables (var(--space-*))\n3. Typography — look for hardcoded font-size/font-family instead of typography variables (var(--font-display), var(--font-body), var(--text-*))\n4. Motion — look for hardcoded transition/animation durations instead of motion tokens (var(--duration-*), var(--easing-*))\n5. Shadows — look for hardcoded box-shadow instead of shadow tokens (var(--shadow-*), var(--shadow-colored-*), var(--shadow-layered-*))\n6. Advanced effects — verify glassmorphism uses tokens (var(--glass-*)), aurora uses tokens (var(--aurora-*)), perspective uses tokens (var(--perspective-*))\n7. Component naming — verify PascalCase for Blazor components (.razor) and kebab-case for CSS classes\n8. Check .morph/context/design-system.md for project-specific design tokens\n9. Ref: framework/standards/frontend/design-system/design-trends.md for modern technique catalog\n\nUse Grep and Glob to scan. Do NOT modify any files.\n\nOutput a JSON object: { \"passed\": boolean, \"issues\": [{ \"file\": string, \"line\": number, \"message\": string, \"severity\": \"warning\" }] }"
       },
       "hook_behavior": {
         "validates": [
-          "CSS color palette compliance (primary, secondary, accent)",
-          "Spacing values (use var(--spacing-*))",
-          "Typography scale (use var(--font-*))",
+          "CSS color palette compliance (primary, accent, surface, text, neutral, semantic)",
+          "Spacing values (use var(--space-*))",
+          "Typography scale (use var(--font-display), var(--font-body), var(--text-*))",
+          "Motion tokens (use var(--duration-*), var(--easing-*))",
+          "Shadow tokens (use var(--shadow-*), var(--shadow-colored-*), var(--shadow-layered-*))",
+          "Advanced effects (glassmorphism: var(--glass-*), aurora: var(--aurora-*), perspective: var(--perspective-*))",
           "Component naming (PascalCase for Blazor, kebab-case for CSS)"
         ],
         "severity": "warning",
@@ -2129,6 +2136,9 @@
       "active_phases": [
         "implement"
       ],
+      "domains": [
+        "frontend-nextjs"
+      ],
       "keywords": [
         "nextjs",
         "tsx",

package/framework/hooks/claude-code/post-tool-use/agent-complete.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+
+/**
+ * PostToolUse Hook: Agent Completion Tracker
+ *
+ * Event: PostToolUse | Matcher: Agent
+ *
+ * Detects when morph-spec subagents complete (dispatched via the Agent tool)
+ * and injects status notifications:
+ *   - Partial: shows which agents are still pending
+ *   - Complete: instructs to run validate-feature
+ *
+ * Only tracks tier 1-3 agents (not validators: morph-validator-*).
+ *
+ * Fail-open: exits 0 on any error.
+ */
+
+import { readStdin } from '../../shared/stdin-reader.js';
+import { stateExists, getActiveFeature, getFeature, getFeaturePhase } from '../../shared/state-reader.js';
+import { pass, injectContext } from '../../shared/hook-response.js';
+import { logHookActivity } from '../../shared/activity-logger.js';
+import { subagentTypeToAgentId } from '../../shared/dispatch-helpers.js';
+
+try {
+  if (!stateExists()) pass();
+
+  const payload = await readStdin();
+  if (!payload) pass();
+
+  const subagentType = payload?.tool_input?.subagent_type || '';
+  if (!subagentType) pass();
+
+  // Only track morph-* agents (not external subagents)
+  if (!subagentType.startsWith('morph-')) pass();
+
+  // Skip validators (tier 4) — they have their own tracking
+  if (subagentType.startsWith('morph-validator-')) pass();
+
+  const result = buildAgentCompleteContext(subagentType);
+  if (result) {
+    logHookActivity('agent-complete', 'PostToolUse', result.type);
+    injectContext(result.text);
+  }
+
+  pass();
+} catch {
+  // Fail-open
+  process.exit(0);
+}
+
+/**
+ * Build the agent completion notification context.
+ *
+ * @param {string} subagentType - e.g. 'morph-nextjs-expert'
+ * @returns {{ text: string, type: string }|null}
+ */
+function buildAgentCompleteContext(subagentType) {
+  // Get active feature
+  const active = getActiveFeature();
+  if (!active) return null;
+
+  const { name: featureName, feature } = active;
+
+  // Only track during implement phase
+  const phase = getFeaturePhase(featureName);
+  if (phase !== 'implement') return null;
+
+  // Get dispatch log
+  const dispatchLog = feature.dispatchLog;
+  if (!Array.isArray(dispatchLog) || dispatchLog.length === 0) return null;
+
+  // Get the most recent dispatch entry
+  const latestDispatch = dispatchLog[dispatchLog.length - 1];
+  const agents = latestDispatch?.agents;
+  if (!Array.isArray(agents) || agents.length === 0) return null;
+
+  // Find the completing agent in the dispatch
+  const agentId = subagentTypeToAgentId(subagentType);
+  let matchedAgent = agents.find(a => a.subagentType === subagentType);
+  if (!matchedAgent && agentId) {
+    matchedAgent = agents.find(a => a.id === agentId);
+  }
+
+  if (!matchedAgent) return null;
+
+  // Mark this agent as completed (in-memory for evaluation only)
+  // Check which agents are still pending (no completedAt)
+  const pendingAgents = agents.filter(a => {
+    if (a === matchedAgent) return false; // The one just completed
+    return !a.completedAt;
+  });
+
+  const totalAgents = agents.length;
+  const completedCount = totalAgents - pendingAgents.length;
+
+  if (pendingAgents.length === 0) {
+    // All agents complete
+    return {
+      type: 'all_complete',
+      text: [
+        '✅ ALL MORPH-SPEC AGENTS COMPLETE',
+        '════════════════════════════════════════',
+        `All ${totalAgents} dispatched agents have completed their tasks.`,
+        '',
+        'NEXT STEP:',
+        `  morph-spec validate-feature ${featureName} --phase implement`,
+      ].join('\n'),
+    };
+  }
+
+  // Partial completion
+  const remainingList = pendingAgents
+    .map(a => a.title || a.id || 'unknown')
+    .join(', ');
+
+  const agentTitle = matchedAgent.title || matchedAgent.id || subagentType;
+
+  return {
+    type: 'partial_complete',
+    text: `✅ Agent '${agentTitle}' completed (${completedCount}/${totalAgents}). Remaining: ${remainingList}`,
+  };
+}

package/framework/hooks/shared/dispatch-helpers.js

@@ -112,6 +112,23 @@ export function parseDispatchAgentsCommand(command) {
   return { featureName: match[1], phase: match[2] };
 }
 
+/**
+ * Convert a subagent_type string back to a morph agent ID.
+ * Reverses the mapping used when dispatching agents as subagents.
+ *
+ * Example: 'morph-nextjs-expert' → 'nextjs-expert'
+ *
+ * @param {string} subagentType - The subagent_type value (e.g. 'morph-nextjs-expert')
+ * @returns {string|null} - Agent ID without 'morph-' prefix, or null if invalid
+ */
+export function subagentTypeToAgentId(subagentType) {
+  if (!subagentType || typeof subagentType !== 'string') return null;
+  if (!subagentType.startsWith('morph-')) return null;
+  const agentId = subagentType.slice('morph-'.length);
+  if (!agentId) return null;
+  return agentId;
+}
+
 /**
  * Extract the tool result string from a PostToolUse hook payload.
  * Handles multiple possible formats.

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

@@ -4,7 +4,7 @@ description: MORPH-SPEC Phase 3 (Clarify). Iterative clarification loop driven b
 argument-hint: "[feature-name]"
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
-cliVersion: "4.11.1"
+cliVersion: "4.12.0"
 ---
 
 # MORPH Clarify — Phase 3

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

@@ -3,7 +3,7 @@ name: morph-phase-codebase-analysis
 description: MORPH-SPEC Design sub-phase that analyzes existing codebase and database schema, producing schema-analysis.md with real column names, types, relationships, and field mismatches. Use at the start of Design phase before generating contracts.cs to prevent incorrect field names or types.
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
-cliVersion: "4.11.1"
+cliVersion: "4.12.0"
 ---
 
 # MORPH Codebase Analysis - Design Sub-phase

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

@@ -4,7 +4,7 @@ description: MORPH-SPEC Phase 2 (Design). Schema-first interactive design: reads
 argument-hint: "[feature-name]"
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Agent
-cliVersion: "4.11.1"
+cliVersion: "4.12.0"
 ---
 
 # MORPH Design — Phase 2

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

@@ -5,7 +5,7 @@ argument-hint: "[feature-name]"
 context: fork
 agent: general-purpose
 user-invocable: false
-cliVersion: "4.11.1"
+cliVersion: "4.12.0"
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Agent
 ---
 

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

@@ -4,7 +4,7 @@ description: MORPH-SPEC Phase 4 (Plan). Generates a detailed implementation plan
 argument-hint: "[feature-name]"
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
-cliVersion: "4.11.1"
+cliVersion: "4.12.0"
 ---
 
 # MORPH Plan — Phase 4

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

@@ -4,7 +4,7 @@ description: MORPH-SPEC Phase 1 (Setup). Reads project context, detects tech sta
 argument-hint: "[feature-name]"
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
-cliVersion: "4.11.1"
+cliVersion: "4.12.0"
 ---
 
 # MORPH Setup — Phase 1

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

@@ -4,7 +4,7 @@ description: MORPH-SPEC Phase 4 (Tasks). Breaks approved spec into bottom-up ord
 argument-hint: "[feature-name]"
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
-cliVersion: "4.11.1"
+cliVersion: "4.12.0"
 ---
 
 # MORPH Tasks — Phase 4

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

@@ -4,7 +4,7 @@ description: MORPH-SPEC Phase 1.5 (UI/UX). Creates design-system.md, mockups.md,
 argument-hint: "[feature-name]"
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
-cliVersion: "4.11.1"
+cliVersion: "4.12.0"
 ---
 
 # MORPH UI/UX Design - Phase 1.5
@@ -39,6 +39,11 @@ Conditional phase for features with front-end. Collects UI/UX requirements, gene
 | 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:` |
+| Read MudBlazor theme | **Glob** `**/MudTheme*.cs` → **Read** | **Grep** `PaletteLight` |
+| Trend research | **Read** `design-trends.md` standard | **Context7 MCP** / **WebSearch** |
 
 **MCPs for this phase:** Playwright (preview, inspection, responsiveness), Context7 (component docs).
 
@@ -70,15 +75,123 @@ Check the `"phase"` field in the output:
 
 ---
 
+### 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 launchSettings**: Glob `**/Properties/launchSettings.json` → Read → extract `applicationUrl`
+6. **.NET fallback**: Glob `*.csproj` → try `https://localhost:5001`
+
+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/2-ui/existing-*.png`
+
+#### 0.2.4 — Visual analysis
+
+Analyze the captured screenshots and write `.morph/features/$ARGUMENTS/2-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 CSS tokens (ALWAYS)
+#### Step 0.5.1 — Scan frontend for design tokens (ALWAYS)
 
-Search for existing CSS custom properties in the project's frontend directories.
+Search for existing design tokens across ALL supported stacks. Run these scans in parallel:
 
-Glob these patterns (exclude `node_modules/`, `.next/`, `dist/`, `build/`):
+**A. CSS Custom Properties (all stacks):**
+Glob these patterns (exclude `node_modules/`, `.next/`, `dist/`, `build/`, `obj/`, `bin/`):
 ```
 wwwroot/**/*.css
 wwwroot/**/*.scss
@@ -88,16 +201,43 @@ src/**/*.css
 src/**/*.scss
 src/**/*.module.css
 public/**/*.css
+app/**/*.css
 ```
-
-For each CSS/SCSS file found, Grep for `:root {` blocks containing `--` custom properties.
-
-Classify found tokens:
-- **Colors**: lines with `--color-*`, or any `--*` containing `#hex` / `rgb(...)`
-- **Fonts**: `--font-*` or `font-family:` declarations
-- **Spacing**: `--space-*`, `--gap-*`, `--size-*` with rem/px values
-
-Track: `cssTokensFound` (bool), token counts by category, source file list.
+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. MudBlazor Theme (.NET):**
+Glob: `**/MudTheme*.cs`, `**/*Theme*.cs`, `**/CustomTheme*.cs`
+If found, Grep for `PaletteLight`, `PaletteDark`, `Typography` property assignments.
+Extract: Primary, Secondary, Tertiary, Background, Surface colors + font families.
+
+**E. Fluent UI Theme (.NET):**
+Glob: `**/FluentDesignTheme*.cs`, `**/DesignTheme*.cs`
+If found, Grep for `DesignThemePalette` properties.
+
+**F. 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(), Palette assignments
+- **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
 
@@ -113,7 +253,7 @@ Track: `dsExists` (bool).
 |------|-----------|--------|
 | **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 `cssTokensFound` | Auto-generate `.morph/context/design-system.md` from scanned tokens (see Case C detail below). 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, MudBlazor theme, 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. |
 
 **Case C — auto-generate from scanned tokens:**
@@ -147,6 +287,60 @@ morph-spec state get $ARGUMENTS
 
 If `ui-designer` is NOT in `activeAgents`, skip this phase and continue to Phase 2 (Design).
 
+### Step 1.3: Trend Research
+
+> **Purpose:** Before defining aesthetic direction, research current design trends relevant to this project's domain.
+> **Ref:** `framework/standards/frontend/design-system/design-trends.md`
+
+#### 1.3.1 — Consult curated catalog
+
+Read `framework/standards/frontend/design-system/design-trends.md` and identify techniques relevant to 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
 
 > **Ref:** `framework/standards/frontend/design-system/aesthetic-direction.md`
@@ -161,6 +355,46 @@ If `ui-designer` is NOT in `activeAgents`, skip this phase and continue to Phase
 **CRITICAL:** Commit to direction BEFORE technical specs. Document in `ui-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:
+
+> **Ref:** `framework/standards/frontend/design-system/aesthetic-direction.md` → `## Domain Adaptation`
+
+Based on the domain detected in Step 1.3.2, suggest patterns from the Domain Adaptation guide:
+
+| 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 `ui-design-system.md`
+- Reference the specific implementation from `design-trends.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

package/framework/skills/level-1-workflows/morph-scope-escalation/SKILL.md

@@ -4,7 +4,7 @@ description: Guided workflow for mid-implementation scope escalation — analyze
 user-invocable: true
 argument-hint: "[feature-name]"
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
-cliVersion: "4.11.1"
+cliVersion: "4.12.0"
 ---
 
 # Scope Escalation Workflow