create-specfuse 0.3.1 → 0.4.0

package/dist/templates/design-md-skill.js

@@ -4,29 +4,240 @@ name: design-md
 description: Generate a DESIGN.md file for the current project via interactive questionnaire and archetype matching. Use for brownfield projects that need design tokens.
 ---
 
-Generate a \`DESIGN.md\` file in the current working directory.
+# DESIGN.md Generation Skill
 
-**Trigger:** User invokes \`/design-md\` manually in a brownfield project.
+Generate a comprehensive \`DESIGN.md\` design token document for the current project.
 
-**What it does:**
+**Trigger:** User invokes \`/design-md\` manually, or auto-triggered after \`specfuse init\` for frontend projects.
 
-1. Runs a 5-question interactive questionnaire (product type, audience, mood, density, reference)
-2. Derives a dimension vector from answers
-3. Matches against 15 design archetypes using weighted Euclidean distance + category bonus
-4. Presents the best match for confirmation
-5. Optionally allows fine-tuning individual dimensions (1-5 scale)
-6. Renders DESIGN.md with YAML front matter (design tokens) + Markdown rationale
+---
+
+## §1 Questionnaire
+
+Ask the user exactly 5 questions, one at a time. Each answer maps to one or more dimension axes (colorTemp, lightness, density, borderRadius, tone) on a 1-5 scale.
+
+### Q1: Product Category
+
+"What type of product is this?"
+
+Options:
+- A) Internal tool / Admin panel → category: internal-tool, density +2
+- B) Dashboard / Analytics → category: dashboard, density +1, lightness -1
+- C) Consumer app (social/media) → category: consumer, tone +2
+- D) Developer tool / API portal → category: developer, colorTemp -1
+- E) Mobile app → category: mobile, borderRadius +1
+- F) E-commerce / Marketplace → category: e-commerce, tone +1
+- G) Marketing / Landing page → category: marketing, density -2, lightness +1
+- H) Form-heavy / Workflow → category: form-heavy, density +1
+- I) Content / Blog / Docs → category: content, lightness +1, density -1
+
+Mapping: Sets the \`category\` field and adjusts relevant dimensions from baseline 3.
+
+### Q2: Visual Temperature
+
+"How warm or cool should the palette feel?"
+
+Options:
+- A) Very cool (blues, blue-greys) → colorTemp: 1
+- B) Cool-neutral → colorTemp: 2
+- C) Balanced / Neutral → colorTemp: 3
+- D) Warm-neutral → colorTemp: 4
+- E) Very warm (ambers, warm greys) → colorTemp: 5
+
+Mapping: Directly sets \`colorTemp\` dimension.
+
+### Q3: Interface Density
+
+"How information-dense should the interface be?"
+
+Options:
+- A) Maximum density (monitoring dashboards, trading) → density: 1
+- B) High density (admin panels, data tables) → density: 2
+- C) Balanced (standard SaaS) → density: 3
+- D) Spacious (consumer apps, marketing) → density: 4
+- E) Very spacious (luxury, editorial) → density: 5
+
+Mapping: Directly sets \`density\` dimension.
+
+### Q4: Shape Language
+
+"What shape personality fits your brand?"
 
-**Usage:**
+Options:
+- A) Sharp / Angular (technical, serious) → borderRadius: 1
+- B) Slightly rounded (professional) → borderRadius: 2
+- C) Moderately rounded (friendly-professional) → borderRadius: 3
+- D) Well-rounded (approachable, consumer) → borderRadius: 4
+- E) Very rounded / Pill-shaped (playful) → borderRadius: 5
+
+Mapping: Directly sets \`borderRadius\` dimension.
+
+### Q5: Brand Personality
+
+"What tone should the design communicate?"
+
+Options:
+- A) Strictly functional (no personality) → tone: 1
+- B) Professional and restrained → tone: 2
+- C) Confident and polished → tone: 3
+- D) Friendly and approachable → tone: 4
+- E) Playful and expressive → tone: 5
+
+Mapping: Directly sets \`tone\` dimension. Also influences \`lightness\`: tone 1-2 → lightness -1, tone 4-5 → lightness +1.
+
+---
+
+## §2 Matching Algorithm
+
+After collecting answers, compute a 5-dimensional vector: \`[colorTemp, lightness, density, borderRadius, tone]\`.
+
+**Weighted Euclidean distance** against all 16 archetype seed files:
 
 \`\`\`
-import { generateDesignMd } from 'specfuse/design-md';
-const result = await generateDesignMd(process.cwd());
+distance(user, archetype) = sqrt(
+  w_colorTemp * (u.colorTemp - a.colorTemp)² +
+  w_lightness * (u.lightness - a.lightness)² +
+  w_density * (u.density - a.density)² +
+  w_borderRadius * (u.borderRadius - a.borderRadius)² +
+  w_tone * (u.tone - a.tone)²
+)
 \`\`\`
 
-If \`DESIGN.md\` already exists, prompts for overwrite confirmation and creates a \`.bak\` backup.
+Weights: \`colorTemp=1.0, lightness=1.0, density=1.5, borderRadius=0.8, tone=1.2\`
+
+**Category bonus:** If the archetype's \`category\` matches the user's Q1 answer, subtract 1.5 from its distance score (floor at 0). This ensures category-appropriate archetypes rank higher.
+
+Select the archetype with the lowest adjusted distance. Present it to the user for confirmation. Allow fine-tuning individual dimensions before final generation.
+
+---
+
+## §3 Token Derivation Rules
+
+From the matched archetype's \`anchors\`, derive a complete design token system:
+
+### Colors (15+ semantic colors)
+
+Starting from \`anchors.colors.primary\` and \`anchors.colors.auxiliary\`:
+1. Generate primary scale: 50, 100, 200, 300, 400, 500, 600, 700, 800, 900 (10 shades)
+2. Generate 2-3 auxiliary/accent scales (5 shades each from auxiliary anchors)
+3. Derive semantic colors: success, warning, error, info (from primary hue-shift)
+4. Neutral scale: 11 steps (white → black) calibrated to lightness dimension
+5. Surface colors: background, surface, elevated, overlay
+
+Total: minimum 15+ semantic color tokens with named purposes.
+
+### Typography Scale
+
+From \`anchors.typography.baseSize\` and \`anchors.typography.scale\`:
+- Generate type scale using the modular ratio: xs, sm, base, md, lg, xl, 2xl, 3xl, 4xl
+- Each step = previous × scale ratio
+- Define font weights: regular (400), medium (500), semibold (600), bold (700)
+- Define line heights: tight (1.2), normal (1.5), relaxed (1.75)
+
+### Spacing (6-level system)
+
+From \`anchors.spacing.unit\`:
+- Generate 6 named levels: xs, sm, md, lg, xl, 2xl
+- Each level = unit × multiplier: 1×, 2×, 3×, 4×, 6×, 8×
+- Example with 4px unit: 4, 8, 12, 16, 24, 32
+
+### Radius (6-level system)
+
+From \`anchors.radius.base\`:
+- Generate 6 named levels: none, sm, md, lg, xl, full
+- Values: 0, base÷2, base, base×1.5, base×2, 9999px
+- Example with 8px base: 0, 4, 8, 12, 16, 9999
+
+### Elevation
+
+Derive 5 elevation levels based on density dimension:
+- Level 0: none (flat)
+- Level 1: subtle (small shadow for cards)
+- Level 2: medium (dropdowns, popovers)
+- Level 3: high (modals, dialogs)
+- Level 4: highest (notifications, toasts)
+
+Shadow intensity scales with density: high-density UIs use subtler shadows.
+
+### Component Tokens (8-10 groups)
+
+From \`structure.componentTokens\`, define tokens for each component using cross-reference syntax:
+
+\`\`\`yaml
+button:
+  padding: "{spacing.sm} {spacing.md}"
+  borderRadius: "{radius.md}"
+  fontSize: "{typography.sm}"
+  primary:
+    background: "{colors.primary.500}"
+    text: "{colors.white}"
+  secondary:
+    background: "{colors.neutral.100}"
+    text: "{colors.neutral.800}"
+\`\`\`
+
+Cross-reference format: \`"{category.token}"\` where category is one of colors, typography, spacing, radius, elevation.
+
+---
+
+## §4 Output Format
+
+Generate \`DESIGN.md\` with two parts:
+
+### YAML Front Matter
+
+\`\`\`markdown
+---
+designSystem:
+  name: "<project name> Design System"
+  version: "1.0.0"
+  archetype: "<matched archetype id>"
+  generatedAt: "<ISO date>"
+tokens:
+  colors:
+    primary: { ... full scale ... }
+    auxiliary: { ... }
+    semantic: { success, warning, error, info }
+    neutral: { ... 11 steps ... }
+  typography:
+    scale: { xs, sm, base, md, lg, xl, 2xl, 3xl, 4xl }
+    weights: { regular, medium, semibold, bold }
+    lineHeights: { tight, normal, relaxed }
+  spacing: { xs, sm, md, lg, xl, 2xl }
+  radius: { none, sm, md, lg, xl, full }
+  elevation: { 0, 1, 2, 3, 4 }
+  components: { ... 8-10 component token groups ... }
+---
+\`\`\`
+
+### Markdown Body structure
+
+The Markdown body follows this structure:
+
+1. **Overview** — archetype name, philosophy, key decisions
+2. **Color Palette** — visual swatches (using HTML/unicode), semantic meanings
+3. **Typography** — scale table, font stack recommendations
+4. **Spacing & Layout** — grid system, spacing scale visualization
+5. **Border Radius** — shape language explanation
+6. **Elevation & Shadows** — usage guidelines per level
+7. **Component Tokens** — per-component token table with cross-references
+8. **Responsive Breakpoints** — from \`structure.requiredSections\`
+9. **Usage Guidelines** — do/don't patterns for applying tokens
+
+---
+
+## §5 Backup & Overwrite Protection
+
+Before writing \`DESIGN.md\`:
+
+1. Check if \`DESIGN.md\` already exists in the target directory
+2. If it exists:
+   - Ask for overwrite confirmation: "DESIGN.md already exists. Overwrite? (A .bak backup will be created)"
+   - On confirmation: copy existing file to \`DESIGN.md.bak\`
+   - On rejection: abort without changes
+3. If it does not exist: proceed directly
 
-Returns the output file path on success, or \`null\` if the user aborts.
+Never silently overwrite an existing DESIGN.md file.
 `;
 }
 //# sourceMappingURL=design-md-skill.js.map

package/dist/templates/design-md-skill.js.map

@@ -1 +1 @@
-{"version":3,"file":"design-md-skill.js","sourceRoot":"","sources":["../../src/templates/design-md-skill.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,oBAAoB;IAClC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4BR,CAAC;AACF,CAAC"}
+{"version":3,"file":"design-md-skill.js","sourceRoot":"","sources":["../../src/templates/design-md-skill.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,oBAAoB;IAClC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+OR,CAAC;AACF,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-specfuse",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Scaffold projects with OpenSpec + Superpowers fusion methodology",
   "type": "module",
   "bin": {
@@ -15,7 +15,7 @@
     "node": ">=18.0.0"
   },
   "scripts": {
-    "build": "tsc && cp -r src/design-md/templates dist/design-md/templates",
+    "build": "tsc && rm -rf dist/design-md/templates && cp -r src/design-md/templates dist/design-md/templates",
     "test": "vitest run",
     "dev": "tsc --watch"
   },

package/dist/design-md/templates/templates/_schema.yaml

@@ -1,71 +0,0 @@
-type: object
-required:
-  - id
-  - name
-  - category
-  - dimensions
-  - anchors
-  - template
-properties:
-  id:
-    type: string
-    pattern: "^[a-z][a-z0-9-]*$"
-  name:
-    type: string
-  category:
-    type: string
-    enum:
-      - internal-tool
-      - dashboard
-      - consumer
-      - developer
-      - mobile
-      - e-commerce
-      - marketing
-      - form-heavy
-      - content
-  dimensions:
-    type: object
-    required:
-      - colorTemp
-      - lightness
-      - density
-      - borderRadius
-      - tone
-    properties:
-      colorTemp:
-        type: integer
-        minimum: 1
-        maximum: 5
-      lightness:
-        type: integer
-        minimum: 1
-        maximum: 5
-      density:
-        type: integer
-        minimum: 1
-        maximum: 5
-      borderRadius:
-        type: integer
-        minimum: 1
-        maximum: 5
-      tone:
-        type: integer
-        minimum: 1
-        maximum: 5
-  anchors:
-    type: object
-    required:
-      - primary
-      - auxiliary
-    properties:
-      primary:
-        type: string
-      auxiliary:
-        type: array
-        items:
-          type: string
-        minItems: 1
-        maxItems: 2
-  template:
-    type: string

package/dist/design-md/templates/templates/consumer-media.yaml

@@ -1,34 +0,0 @@
-id: consumer-media
-name: Consumer Media
-category: consumer
-dimensions:
-  colorTemp: 3
-  lightness: 2
-  density: 4
-  borderRadius: 3
-  tone: 4
-anchors:
-  primary: Spotify
-  auxiliary:
-    - Netflix
-    - Apple Music
-template: |
-  tokens:
-    colors:
-      primary: "#1DB954"
-      background: "#121212"
-      surface: "#1E1E1E"
-      text: "#FFFFFF"
-      accent: "#1ED760"
-    spacing:
-      base: "4px"
-      scale: [4, 8, 12, 16, 24, 32, 48, 64]
-    radius:
-      default: "8px"
-      large: "12px"
-    typography:
-      fontFamily: "'Circular', 'Helvetica Neue', sans-serif"
-      scale: [12, 14, 16, 20, 24, 32, 48]
-    density:
-      compact: false
-      tableRowHeight: "48px"

package/dist/design-md/templates/templates/consumer-social.yaml

@@ -1,34 +0,0 @@
-id: consumer-social
-name: Consumer Social
-category: consumer
-dimensions:
-  colorTemp: 4
-  lightness: 4
-  density: 4
-  borderRadius: 5
-  tone: 5
-anchors:
-  primary: Instagram
-  auxiliary:
-    - TikTok
-    - Threads
-template: |
-  tokens:
-    colors:
-      primary: "#E1306C"
-      background: "#FFFFFF"
-      surface: "#FAFAFA"
-      text: "#262626"
-      accent: "#833AB4"
-    spacing:
-      base: "4px"
-      scale: [4, 8, 12, 16, 24, 32, 48, 64]
-    radius:
-      default: "16px"
-      large: "24px"
-    typography:
-      fontFamily: "'-apple-system', 'Segoe UI', sans-serif"
-      scale: [12, 14, 16, 18, 24, 32]
-    density:
-      compact: false
-      tableRowHeight: "56px"

package/dist/design-md/templates/templates/content-blog.yaml

@@ -1,34 +0,0 @@
-id: content-blog
-name: Content Blog
-category: content
-dimensions:
-  colorTemp: 3
-  lightness: 5
-  density: 5
-  borderRadius: 2
-  tone: 3
-anchors:
-  primary: Medium
-  auxiliary:
-    - Substack
-    - Ghost
-template: |
-  tokens:
-    colors:
-      primary: "#292929"
-      background: "#FFFFFF"
-      surface: "#FAFAFA"
-      text: "#292929"
-      accent: "#1A8917"
-    spacing:
-      base: "4px"
-      scale: [4, 8, 16, 24, 32, 48, 64, 96]
-    radius:
-      default: "4px"
-      large: "8px"
-    typography:
-      fontFamily: "'Georgia', 'Charter', serif"
-      scale: [14, 16, 18, 21, 26, 34, 42]
-    density:
-      compact: false
-      tableRowHeight: "48px"

package/dist/design-md/templates/templates/content-docs.yaml

@@ -1,34 +0,0 @@
-id: content-docs
-name: Content Documentation
-category: content
-dimensions:
-  colorTemp: 2
-  lightness: 4
-  density: 3
-  borderRadius: 2
-  tone: 2
-anchors:
-  primary: Docusaurus
-  auxiliary:
-    - GitBook
-    - ReadTheDocs
-template: |
-  tokens:
-    colors:
-      primary: "#2E8555"
-      background: "#FFFFFF"
-      surface: "#F5F6F7"
-      text: "#1C1E21"
-      accent: "#25C2A0"
-    spacing:
-      base: "4px"
-      scale: [4, 8, 12, 16, 24, 32, 48, 64]
-    radius:
-      default: "4px"
-      large: "8px"
-    typography:
-      fontFamily: "'-apple-system', 'Segoe UI', sans-serif"
-      scale: [12, 14, 16, 18, 20, 24, 30]
-    density:
-      compact: false
-      tableRowHeight: "40px"

package/dist/design-md/templates/templates/dashboard-analytics.yaml

@@ -1,34 +0,0 @@
-id: dashboard-analytics
-name: Dashboard Analytics
-category: dashboard
-dimensions:
-  colorTemp: 2
-  lightness: 2
-  density: 1
-  borderRadius: 2
-  tone: 1
-anchors:
-  primary: Grafana
-  auxiliary:
-    - Datadog
-    - New Relic
-template: |
-  tokens:
-    colors:
-      primary: "#FF6600"
-      background: "#111217"
-      surface: "#1A1C23"
-      text: "#D8D9DA"
-      accent: "#73BF69"
-    spacing:
-      base: "4px"
-      scale: [2, 4, 8, 12, 16, 24, 32]
-    radius:
-      default: "4px"
-      large: "6px"
-    typography:
-      fontFamily: "'Inter', 'Roboto', sans-serif"
-      scale: [10, 11, 12, 14, 16, 20, 24]
-    density:
-      compact: true
-      tableRowHeight: "32px"

package/dist/design-md/templates/templates/dashboard-monitoring.yaml

@@ -1,34 +0,0 @@
-id: dashboard-monitoring
-name: Dashboard Monitoring
-category: dashboard
-dimensions:
-  colorTemp: 1
-  lightness: 1
-  density: 1
-  borderRadius: 1
-  tone: 1
-anchors:
-  primary: PagerDuty
-  auxiliary:
-    - Uptime Robot
-    - StatusPage
-template: |
-  tokens:
-    colors:
-      primary: "#06AC38"
-      background: "#0D1117"
-      surface: "#161B22"
-      text: "#C9D1D9"
-      accent: "#F85149"
-    spacing:
-      base: "4px"
-      scale: [2, 4, 8, 12, 16, 24, 32]
-    radius:
-      default: "3px"
-      large: "4px"
-    typography:
-      fontFamily: "'JetBrains Mono', 'Fira Code', monospace"
-      scale: [10, 11, 12, 14, 16, 18, 22]
-    density:
-      compact: true
-      tableRowHeight: "28px"

package/dist/design-md/templates/templates/developer-portal.yaml

@@ -1,33 +0,0 @@
-id: developer-portal
-name: Developer Portal
-category: developer
-dimensions:
-  colorTemp: 1
-  lightness: 1
-  density: 3
-  borderRadius: 2
-  tone: 2
-anchors:
-  primary: Stripe Docs
-  auxiliary:
-    - Tailwind Docs
-template: |
-  tokens:
-    colors:
-      primary: "#3B82F6"
-      background: "#0F172A"
-      surface: "#1E293B"
-      text: "#E2E8F0"
-      accent: "#22D3EE"
-    spacing:
-      base: "4px"
-      scale: [4, 8, 16, 24, 32, 48, 64]
-    radius:
-      default: "6px"
-      large: "8px"
-    typography:
-      fontFamily: "'JetBrains Mono', 'Fira Code', monospace"
-      scale: [12, 14, 16, 18, 24, 32]
-    density:
-      compact: false
-      tableRowHeight: "40px"

package/dist/design-md/templates/templates/e-commerce.yaml

@@ -1,34 +0,0 @@
-id: e-commerce
-name: E-Commerce Platform
-category: e-commerce
-dimensions:
-  colorTemp: 4
-  lightness: 4
-  density: 3
-  borderRadius: 4
-  tone: 4
-anchors:
-  primary: Shopify
-  auxiliary:
-    - Gumroad
-    - Lemonsqueezy
-template: |
-  tokens:
-    colors:
-      primary: "#16A34A"
-      background: "#FFFFFF"
-      surface: "#F9FAFB"
-      text: "#111827"
-      accent: "#F59E0B"
-    spacing:
-      base: "4px"
-      scale: [4, 8, 12, 16, 24, 32, 48, 64]
-    radius:
-      default: "12px"
-      large: "16px"
-    typography:
-      fontFamily: "'Plus Jakarta Sans', -apple-system, sans-serif"
-      scale: [12, 14, 16, 20, 24, 32, 40]
-    density:
-      compact: false
-      tableRowHeight: "52px"

package/dist/design-md/templates/templates/form-heavy.yaml

@@ -1,34 +0,0 @@
-id: form-heavy
-name: Form-Heavy Application
-category: form-heavy
-dimensions:
-  colorTemp: 3
-  lightness: 4
-  density: 3
-  borderRadius: 3
-  tone: 2
-anchors:
-  primary: Typeform
-  auxiliary:
-    - Notion Forms
-    - Airtable
-template: |
-  tokens:
-    colors:
-      primary: "#6366F1"
-      background: "#FAFAFA"
-      surface: "#FFFFFF"
-      text: "#374151"
-      accent: "#8B5CF6"
-    spacing:
-      base: "4px"
-      scale: [4, 8, 12, 16, 24, 32, 48, 64]
-    radius:
-      default: "8px"
-      large: "12px"
-    typography:
-      fontFamily: "'Inter', -apple-system, sans-serif"
-      scale: [12, 14, 16, 18, 24, 30]
-    density:
-      compact: false
-      tableRowHeight: "48px"

package/dist/design-md/templates/templates/internal-tool.yaml

@@ -1,34 +0,0 @@
-id: internal-tool
-name: Internal Tool
-category: internal-tool
-dimensions:
-  colorTemp: 2
-  lightness: 2
-  density: 2
-  borderRadius: 2
-  tone: 1
-anchors:
-  primary: Retool
-  auxiliary:
-    - Backstage
-    - AdminJS
-template: |
-  tokens:
-    colors:
-      primary: "#4A6CF7"
-      background: "#1E1E2E"
-      surface: "#2A2A3C"
-      text: "#E4E4E7"
-      accent: "#7C8DFF"
-    spacing:
-      base: "4px"
-      scale: [4, 8, 12, 16, 24, 32, 48]
-    radius:
-      default: "4px"
-      large: "6px"
-    typography:
-      fontFamily: "'Inter', -apple-system, sans-serif"
-      scale: [12, 13, 14, 16, 20, 24]
-    density:
-      compact: true
-      tableRowHeight: "36px"