@polymorphism-tech/morph-spec 4.10.8 → 4.10.9

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.10.8  
+**Version:** 4.10.9  
 **Requires:** Node.js 18+, Claude Code
 
 ---
@@ -376,4 +376,4 @@ Code generated by morph-spec (contracts, templates, implementation output) belon
 
 ---
 
-*morph-spec v4.10.8 by [Polymorphism Tech](https://polymorphism.tech)*
+*morph-spec v4.10.9 by [Polymorphism Tech](https://polymorphism.tech)*

package/claude-plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "morph-spec",
-  "version": "4.10.8",
+  "version": "4.10.9",
   "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.10.8 by Polymorphism Tech*
+*morph-spec v4.10.9 by Polymorphism Tech*

package/docs/QUICKSTART.md

@@ -203,4 +203,4 @@ morph-spec doctor
 
 ---
 
-*morph-spec v4.10.8 by Polymorphism Tech*
+*morph-spec v4.10.9 by Polymorphism Tech*

package/framework/skills/level-0-meta/morph-init/SKILL.md

@@ -155,24 +155,70 @@ Do **not** ask about technology already confirmed by file evidence.
 
 ## Step 4.5 — Scaffold Design System
 
-Check if the project already has a design system file:
+### 4.5.0 — Check if DS already exists
 
 ```
 Read: .morph/context/design-system.md
 ```
 
 **If the file EXISTS with non-TODO content in the Aesthetic Direction section:**
-→ Skip this step. Print: `✓ Design system found — .morph/context/design-system.md`
+→ Skip steps 4.5.1–4.5.2. Print: `✓ Design system found — .morph/context/design-system.md`
 
-**If the file does NOT EXIST or is empty:**
+### 4.5.1 — ALWAYS scan for existing CSS tokens
 
-1. **Copy the template:**
+Search for existing CSS custom properties across the project's frontend directories.
+
+Glob these patterns (exclude `node_modules/`, `.next/`, `dist/`, `build/`):
+```
+wwwroot/**/*.css
+wwwroot/**/*.scss
+styles/**/*.css
+src/styles/**/*.css
+src/**/*.css
+src/**/*.scss
+src/**/*.module.css
+public/**/*.css
+```
+
+For each CSS/SCSS file found, Grep for `:root {` blocks containing `--` custom properties.
+
+Track:
+- `cssTokensFound` (bool)
+- `tokenCount` (int — total number of `--variable` lines found)
+- `sourceFiles` (array of file paths that had tokens)
+
+### 4.5.2 — Decision tree
+
+**Case A: CSS tokens found (existing project)**
+
+1. Create `.morph/context/design-system.md` from scanned tokens:
+   - `## Color Tokens` → `:root { }` block with all found color variables (preserve exact variable names from CSS)
+   - `## Typography` → found font-family values (map to `--font-display` / `--font-body` by variable name heuristic)
+   - `## Spacing Tokens` → found spacing variables
+   - `## Aesthetic Direction` → `#TODO` (requires user judgment — fill in during `/morph-phase-uiux`)
+   - `## Changelog` → `- [today's date] [morph-init] Auto-generated from CSS scan ([N] tokens from [files])`
+
+2. Skip the `AskUserQuestion` for direction/brand color — the project has established colors
+
+3. Print:
+   ```
+   ✓ Design system scaffolded from existing CSS
+     Source: [file list]
+     Tokens: [N] colors, [M] font families, [K] spacing values
+     Note: Aesthetic Direction is TODO — fill in during /morph-phase-uiux
+   ```
+
+4. Continue to Step 5.
+
+**Case B: No CSS tokens found (greenfield project)**
+
+1. Copy the template:
    ```bash
    cp .morph/framework/templates/context/design-system.md .morph/context/design-system.md
    ```
    *(The template is at `framework/templates/context/design-system.md` in the installed framework)*
 
-2. **Ask 3 quick questions** using `AskUserQuestion`:
+2. Ask 3 quick questions using `AskUserQuestion`:
 
 ```json
 {
@@ -216,15 +262,15 @@ Read: .morph/context/design-system.md
 }
 ```
 
-4. **Fill in the design-system.md** with user responses:
+4. Fill in the design-system.md with user responses:
 
 | User answered | What to update |
 |--------------|----------------|
-| Direction chosen | Replace `[Minimal Refined / Editorial / ...]` with chosen direction. Update Font Pair with the correct fonts from this mapping: Minimal Refined → Cormorant Garamond + DM Sans; Editorial → Playfair Display + Source Sans 3; Soft Professional → Nunito + Inter; Industrial → JetBrains Mono + IBM Plex Sans; Modern Luxury → Bodoni Moda + Sora |
-| Color chosen | Replace `--color-primary: #TODO` with a reasonable hex for that color family (deep blue → #1e3a5f, rich green → #065f46, warm orange → #c2410c, purple → #6d28d9, black → #0a0a0a). Add a note: "Adjust exact values to match your brand" |
+| Direction chosen | Replace `[Minimal Refined / Editorial / ...]` with chosen direction. Update Font Pair with the correct fonts: Minimal Refined → Cormorant Garamond + DM Sans; Editorial → Playfair Display + Source Sans 3; Soft Professional → Nunito + Inter; Industrial → JetBrains Mono + IBM Plex Sans; Modern Luxury → Bodoni Moda + Sora |
+| Color chosen | Replace `--color-primary: #TODO` with a reasonable hex for that color family: deep blue → #1e3a5f, rich green → #065f46, warm orange → #c2410c, purple → #6d28d9, black → #0a0a0a. Add note: "Adjust exact values to match your brand" |
 | "Skip for now" | Leave all TODOs in place |
 
-5. **Update the Changelog** in design-system.md:
+5. Update the Changelog in design-system.md:
    Add entry: `- [today's date] [morph-init] Initial scaffold from morph-init`
 
 6. Print confirmation:
@@ -234,6 +280,8 @@ Read: .morph/context/design-system.md
      Edit to refine exact token values before the UI/UX phase.
    ```
 
+7. Continue to Step 5.
+
 ---
 
 ## Step 5 — Generate `context/README.md`

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.10.8"
+cliVersion: "4.10.9"
 ---
 
 # 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.10.8"
+cliVersion: "4.10.9"
 ---
 
 # 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.10.8"
+cliVersion: "4.10.9"
 ---
 
 # 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.10.8"
+cliVersion: "4.10.9"
 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.10.8"
+cliVersion: "4.10.9"
 ---
 
 # 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.10.8"
+cliVersion: "4.10.9"
 ---
 
 # 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.10.8"
+cliVersion: "4.10.9"
 ---
 
 # 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.10.8"
+cliVersion: "4.10.9"
 ---
 
 # MORPH UI/UX Design - Phase 1.5
@@ -70,31 +70,64 @@ Check the `"phase"` field in the output:
 
 ---
 
-### Step 0.5: Check Design System Exists
+### Step 0.5: Check Design System
 
-**CRITICAL:** Before starting UI/UX phase, check if a design system exists:
+**This step is MANDATORY and must always run before Step 1.**
+
+#### Step 0.5.1 — Scan frontend for CSS tokens (ALWAYS)
+
+Search for existing CSS custom properties in the project's frontend directories.
+
+Glob these patterns (exclude `node_modules/`, `.next/`, `dist/`, `build/`):
+```
+wwwroot/**/*.css
+wwwroot/**/*.scss
+styles/**/*.css
+src/styles/**/*.css
+src/**/*.css
+src/**/*.scss
+src/**/*.module.css
+public/**/*.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.
+
+#### Step 0.5.2 — Check if design-system.md exists
 
 ```
 Read: .morph/context/design-system.md
 ```
 
-If the file doesn't exist (design system not found):
+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 `cssTokensFound` | Auto-generate `.morph/context/design-system.md` from scanned tokens (see Case C detail below). 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. |
 
-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`
+**Case C — auto-generate from scanned tokens:**
 
-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)
+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])`
 
-3. **Option C - Scan existing CSS:**
-   - If the project already has CSS with variables: `npx morph-spec generate design-system --scan`
+Print: `✓ Design system generated from [N] tokens — .morph/context/design-system.md`
 
-**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
+> **Design system is mandatory** for UI features. The implementation gate (Phase 5) will block if no design system exists.
 
 ### Step 1: Detect If Phase Is Needed
 

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.10.8"
+cliVersion: "4.10.9"
 ---
 
 # Scope Escalation Workflow

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polymorphism-tech/morph-spec",
-  "version": "4.10.8",
+  "version": "4.10.9",
   "description": "MORPH-SPEC: AI-First development framework with validation pipeline and multi-stack support",
   "keywords": [
     "claude-code",

package/src/lib/detectors/design-system-detector.js

@@ -7,9 +7,42 @@
  * @module design-system-detector
  */
 
-import { existsSync, readFileSync } from 'fs';
+import { existsSync, readFileSync, readdirSync } from 'fs';
 import { join } from 'path';
 
+const SKIP_DIRS = new Set(['node_modules', '.git', '.morph', 'dist', 'build', '.next', 'obj', 'bin', '.vs']);
+const CSS_SCAN_MAX_DEPTH = 6;
+
+/**
+ * Recursively walk a directory collecting files with given extensions.
+ * @param {string} dir - Directory to walk
+ * @param {string[]} extensions - File extensions to collect (e.g. ['.css', '.scss'])
+ * @param {string[]} files - Accumulator array (mutated in-place)
+ * @param {number} depth - Current recursion depth
+ * @param {number} maxDepth - Maximum recursion depth
+ */
+function walkDirForCss(dir, extensions, files, depth, maxDepth) {
+  if (depth > maxDepth) return;
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      if (!SKIP_DIRS.has(entry.name)) {
+        walkDirForCss(join(dir, entry.name), extensions, files, depth + 1, maxDepth);
+      }
+    } else if (entry.isFile()) {
+      const lower = entry.name.toLowerCase();
+      if (extensions.some(ext => lower.endsWith(ext))) {
+        files.push(join(dir, entry.name));
+      }
+    }
+  }
+}
+
 /**
  * Detect design system for project or feature
  * @param {string} projectPath - Root path of the project
@@ -70,37 +103,46 @@ export function detectDesignSystem(projectPath, featureName = null) {
     };
   }
 
-  // Priority 4: Check common CSS locations for design system variables
-  const commonCssLocations = [
-    'wwwroot/css/site.css',
-    'wwwroot/css/app.css',
-    'styles/globals.css',
-    'src/styles/globals.css'
-  ];
-
-  for (const cssPath of commonCssLocations) {
-    const fullPath = join(projectPath, cssPath);
-    if (existsSync(fullPath)) {
-      // Check if file contains design system variables (CSS custom properties)
-      try {
-        const content = readFileSync(fullPath, 'utf8');
-
-        // Look for CSS custom properties that indicate a design system
-        // Match :root { ... --variable ... } (with newlines)
-        const hasDesignTokens = /:root\s*\{[\s\S]*?--/.test(content);
-
-        if (hasDesignTokens) {
-          return {
-            hasDesignSystem: true,
-            path: fullPath,
-            isProjectLevel: true,
-            isFeatureLevel: false,
-            source: 'existing-css-variables'
-          };
-        }
-      } catch {
-        // Continue checking other locations
+  // Priority 4: Recursively scan frontend root directories for CSS/SCSS with design tokens
+  const frontendRoots = ['wwwroot', 'styles', 'src/styles', 'src', 'public'];
+  const extensions = ['.css', '.scss'];
+  const collected = [];
+
+  for (const root of frontendRoots) {
+    const rootPath = join(projectPath, root);
+    if (existsSync(rootPath)) {
+      walkDirForCss(rootPath, extensions, collected, 0, CSS_SCAN_MAX_DEPTH);
+    }
+  }
+
+  // Deduplicate by resolved path
+  const seen = new Set();
+  const cssFiles = [];
+  for (const file of collected) {
+    if (!seen.has(file)) {
+      seen.add(file);
+      cssFiles.push(file);
+    }
+  }
+
+  // Sort for deterministic first-match across platforms
+  cssFiles.sort();
+
+  for (const cssFile of cssFiles) {
+    try {
+      const content = readFileSync(cssFile, 'utf8');
+      const hasDesignTokens = /:root\s*\{[\s\S]*?--/.test(content);
+      if (hasDesignTokens) {
+        return {
+          hasDesignSystem: true,
+          path: cssFile,
+          isProjectLevel: true,
+          isFeatureLevel: false,
+          source: 'existing-css-variables'
+        };
       }
+    } catch {
+      // Continue checking other files
     }
   }