Merge pull request #16 from singyichen/refactor/design-folder-restructure

refactor: consolidate design folders under design/

Author: singyichen

.claude/skills/ui-ux-pro-max/SKILL.md

@@ -122,6 +122,24 @@ winget install Python.Python.3.12
 
 When user requests UI/UX work (design, build, create, implement, review, fix, improve), follow this workflow:
 
+### Step 0: Load Existing Project Design System (if present)
+
+Before doing any design work, check whether this project already has a design system:
+
+1. **Read `design/system/MASTER.md`** (if it exists) — this is the authoritative style spec: color tokens, typography, spacing, components, and anti-patterns. Always follow it instead of generating a new design system from scratch.
+
+2. **Read `design/wireframes/design-system.pen`** (if it exists) via Pencil MCP tools — this contains the **visual component library** that is the source of truth for implemented component specs:
+   ```
+   mcp__pencil__open_document("design/wireframes/design-system.pen")
+   mcp__pencil__get_editor_state(include_schema=false)
+   mcp__pencil__batch_get(patterns=[{reusable: true}], readDepth=2)
+   ```
+   Extract: reusable component IDs, their fills/strokes/cornerRadius/padding/font values, and variable names (e.g. `$color-surface`, `$color-ink`). Use these exact values when implementing prototype components — **do not invent new values**.
+
+3. **Page-specific overrides**: also check `design/system/pages/[page-name].md` if building a specific page. Its rules override MASTER.md.
+
+If neither file exists, proceed with Step 1–4 as normal to generate a new design system.
+
 ### Step 1: Analyze User Requirements
 
 Extract key information from user request:
@@ -158,21 +176,21 @@ python3 skills/ui-ux-pro-max/scripts/search.py "<query>" --design-system --persi
 ```
 
 This creates:
-- `design-system/MASTER.md` — Global Source of Truth with all design rules
-- `design-system/pages/` — Folder for page-specific overrides
+- `design/system/<project-slug>/MASTER.md` — Global Source of Truth with all design rules
+- `design/system/<project-slug>/pages/` — Folder for page-specific overrides
 
 **With page-specific override:**
 ```bash
 python3 skills/ui-ux-pro-max/scripts/search.py "<query>" --design-system --persist -p "Project Name" --page "dashboard"
 ```
 
 This also creates:
-- `design-system/pages/dashboard.md` — Page-specific deviations from Master
+- `design/system/<project-slug>/pages/dashboard.md` — Page-specific deviations from Master
 
 **How hierarchical retrieval works:**
-1. When building a specific page (e.g., "Checkout"), first check `design-system/pages/checkout.md`
+1. When building a specific page (e.g., "Checkout"), first check `design/system/<project-slug>/pages/checkout.md`
 2. If the page file exists, its rules **override** the Master file
-3. If not, use `design-system/MASTER.md` exclusively
+3. If not, use `design/system/<project-slug>/MASTER.md` exclusively
 
 ### Step 3: Supplement with Detailed Searches (as needed)
 

.claude/skills/ui-ux-pro-max/scripts/design_system.py

@@ -468,7 +468,7 @@ def generate_design_system(query: str, project_name: str = None, output_format:
         query: Search query (e.g., "SaaS dashboard", "e-commerce luxury")
         project_name: Optional project name for output header
         output_format: "ascii" (default) or "markdown"
-        persist: If True, save design system to design-system/ folder
+        persist: If True, save design system to design/system/ folder
         page: Optional page name for page-specific override file
         output_dir: Optional output directory (defaults to current working directory)
 
@@ -490,7 +490,7 @@ def generate_design_system(query: str, project_name: str = None, output_format:
 # ============ PERSISTENCE FUNCTIONS ============
 def persist_design_system(design_system: dict, page: str = None, output_dir: str = None, page_query: str = None) -> dict:
     """
-    Persist design system to design-system/<project>/ folder using Master + Overrides pattern.
+    Persist design system to design/system/<project>/ folder using Master + Overrides pattern.
     
     Args:
         design_system: The generated design system dictionary
@@ -507,7 +507,7 @@ def persist_design_system(design_system: dict, page: str = None, output_dir: str
     project_name = design_system.get("project_name", "default")
     project_slug = project_name.lower().replace(' ', '-')
 
-    design_system_dir = base_dir / "design-system" / project_slug
+    design_system_dir = base_dir / "design" / "system" / project_slug
     pages_dir = design_system_dir / "pages"
 
     created_files = []
@@ -542,21 +542,22 @@ def persist_design_system(design_system: dict, page: str = None, output_dir: str
 def format_master_md(design_system: dict) -> str:
     """Format design system as MASTER.md with hierarchical override logic."""
     project = design_system.get("project_name", "PROJECT")
+    project_slug = project.lower().replace(' ', '-')
     pattern = design_system.get("pattern", {})
     style = design_system.get("style", {})
     colors = design_system.get("colors", {})
     typography = design_system.get("typography", {})
     effects = design_system.get("key_effects", "")
     anti_patterns = design_system.get("anti_patterns", "")
-    
+
     timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
-    
+
     lines = []
-    
+
     # Logic header
     lines.append("# Design System Master File")
     lines.append("")
-    lines.append("> **LOGIC:** When building a specific page, first check `design-system/pages/[page-name].md`.")
+    lines.append(f"> **LOGIC:** When building a specific page, first check `design/system/{project_slug}/pages/[page-name].md`.")
     lines.append("> If that file exists, its rules **override** this Master file.")
     lines.append("> If not, strictly follow the rules below.")
     lines.append("")
@@ -805,21 +806,22 @@ def format_master_md(design_system: dict) -> str:
 def format_page_override_md(design_system: dict, page_name: str, page_query: str = None) -> str:
     """Format a page-specific override file with intelligent AI-generated content."""
     project = design_system.get("project_name", "PROJECT")
+    project_slug = project.lower().replace(' ', '-')
     timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
     page_title = page_name.replace("-", " ").replace("_", " ").title()
-    
+
     # Detect page type and generate intelligent overrides
     page_overrides = _generate_intelligent_overrides(page_name, page_query, design_system)
-    
+
     lines = []
-    
+
     lines.append(f"# {page_title} Page Overrides")
     lines.append("")
     lines.append(f"> **PROJECT:** {project}")
     lines.append(f"> **Generated:** {timestamp}")
     lines.append(f"> **Page Type:** {page_overrides.get('page_type', 'General')}")
     lines.append("")
-    lines.append("> ⚠️ **IMPORTANT:** Rules in this file **override** the Master file (`design-system/MASTER.md`).")
+    lines.append(f"> ⚠️ **IMPORTANT:** Rules in this file **override** the Master file (`design/system/{project_slug}/MASTER.md`).")
     lines.append("> Only deviations from the Master are documented here. For all other rules, refer to the Master.")
     lines.append("")
     lines.append("---")

.claude/skills/ui-ux-pro-max/scripts/search.py

@@ -10,8 +10,8 @@
 Stacks: html-tailwind, react, nextjs
 
 Persistence (Master + Overrides pattern):
-  --persist    Save design system to design-system/MASTER.md
-  --page       Also create a page-specific override file in design-system/pages/
+  --persist    Save design system to design/system/MASTER.md
+  --page       Also create a page-specific override file in design/system/pages/
 """
 
 import argparse
@@ -65,8 +65,8 @@ def format_output(result):
     parser.add_argument("--project-name", "-p", type=str, default=None, help="Project name for design system output")
     parser.add_argument("--format", "-f", choices=["ascii", "markdown"], default="ascii", help="Output format for design system")
     # Persistence (Master + Overrides pattern)
-    parser.add_argument("--persist", action="store_true", help="Save design system to design-system/MASTER.md (creates hierarchical structure)")
-    parser.add_argument("--page", type=str, default=None, help="Create page-specific override file in design-system/pages/")
+    parser.add_argument("--persist", action="store_true", help="Save design system to design/system/MASTER.md (creates hierarchical structure)")
+    parser.add_argument("--page", type=str, default=None, help="Create page-specific override file in design/system/pages/")
     parser.add_argument("--output-dir", "-o", type=str, default=None, help="Output directory for persisted files (default: current directory)")
 
     args = parser.parse_args()
@@ -87,13 +87,13 @@ def format_output(result):
         if args.persist:
             project_slug = args.project_name.lower().replace(' ', '-') if args.project_name else "default"
             print("\n" + "=" * 60)
-            print(f"✅ Design system persisted to design-system/{project_slug}/")
-            print(f"   📄 design-system/{project_slug}/MASTER.md (Global Source of Truth)")
+            print(f"✅ Design system persisted to design/system/{project_slug}/")
+            print(f"   📄 design/system/{project_slug}/MASTER.md (Global Source of Truth)")
             if args.page:
                 page_filename = args.page.lower().replace(' ', '-')
-                print(f"   📄 design-system/{project_slug}/pages/{page_filename}.md (Page Overrides)")
+                print(f"   📄 design/system/{project_slug}/pages/{page_filename}.md (Page Overrides)")
             print("")
-            print(f"📖 Usage: When building a page, check design-system/{project_slug}/pages/[page].md first.")
+            print(f"📖 Usage: When building a page, check design/system/{project_slug}/pages/[page].md first.")
             print(f"   If exists, its rules override MASTER.md. Otherwise, use MASTER.md.")
             print("=" * 60)
     # Stack search

.github/workflows/deploy-prototype.yml

@@ -3,7 +3,7 @@ name: Deploy Prototype to GitHub Pages
 on:
   push:
     branches: [main]
-    paths: ['prototype/**']
+    paths: ['design/prototype/**']
   workflow_dispatch:  # allow manual trigger
 
 concurrency:
@@ -29,7 +29,7 @@ jobs:
 
       - uses: actions/upload-pages-artifact@v3
         with:
-          path: prototype/
+          path: design/prototype/
 
       - uses: actions/deploy-pages@v4
         id: deployment

.specify/memory/constitution.md

@@ -34,11 +34,10 @@ Evaluation results must be fair and reproducible.
 
 - Test-set answers must never be exposed to annotators
 - Scoring logic must be transparent and covered by tests
-- Leaderboard update mechanism must prevent duplicate submission abuse
 
 ### IV. Test-First (RECOMMENDED)
 - Backend: pytest coverage target ≥ 80%
-- E2E: Playwright covers core user flows (labeling, submission, leaderboard)
+- E2E: Playwright covers core user flows (labeling, submission, review)
 - Tests must be written and confirmed to fail before implementation begins
 
 ### V. Simplicity
@@ -48,7 +47,7 @@ Evaluation results must be fair and reproducible.
 
 ### VI. English-First
 - Code, comments, docstrings, commit messages, and variable/function names are always written in English
-- Traditional Chinese is permitted in `docs/` and `specs/` directories to accelerate research documentation
+- Traditional Chinese is permitted in `docs/`, `specs/`, `design/prototype/`, and `design/wireframes/` directories to accelerate research documentation and UI iteration
 - The only fully Chinese file outside those directories is `README.zh-TW.md`
 
 ## Governance
@@ -68,4 +67,4 @@ Constitution principles take precedence over all other conventions.
 
 **Compliance Review**: All PRs must verify compliance with all six principles before merging. Use `/speckit.analyze` to check cross-artifact consistency and Constitution alignment.
 
-**Version**: 1.2.1 | **Ratified**: 2026-03-18 | **Last Amended**: 2026-03-25
+**Version**: 1.2.3 | **Ratified**: 2026-03-18 | **Last Amended**: 2026-03-30

.specify/templates/agent-file-template.md

@@ -25,7 +25,7 @@ Auto-generated from feature plans. Last updated: [DATE]
 - **KISS & YAGNI**: Pursue extreme simplicity. Reject over-engineering; write code only for current, clearly defined needs.
 - **Config-Driven**: Task types and evaluation metrics are defined in YAML/JSON config — never hardcoded.
 - **Security First (NON-NEGOTIABLE)**: Test-set answers must never be exposed to annotators or included in any annotator-facing API response.
-- **English-First**: Code, comments, and commit messages are written in English. Traditional Chinese is permitted in `docs/` and `specs/`.
+- **English-First**: Code, comments, and commit messages are written in English. Traditional Chinese is permitted in `docs/`, `specs/`, `design/prototype/`, and `design/wireframes/`.
 
 ## Protected Files
 

.specify/templates/plan-template.md

@@ -24,7 +24,7 @@
 - [ ] III. Data Fairness: Does this involve test sets? If so, leakage prevention is planned
 - [ ] IV. Test-First: Test plan is listed
 - [ ] V. Simplicity: Any signs of over-engineering?
-- [ ] VI. English-First: Code, comments, and commit messages in English; Traditional Chinese allowed in `docs/` and `specs/`
+- [ ] VI. English-First: Code, comments, and commit messages in English; Traditional Chinese allowed in `docs/`, `specs/`, `design/prototype/`, and `design/wireframes/`
 
 ## Project Structure
 
@@ -60,6 +60,42 @@ backend/
     └── integration/test_[feature].py
 ```
 
+## System Flow & Data Flow *(include if feature involves API calls, async tasks, or multi-layer data processing)*
+
+<!--
+  Show how data moves through the system layers: Frontend → API → Service → DB.
+  Include error paths and async flows (Celery tasks, WebSocket, etc.) where relevant.
+  Renders natively on GitHub — no extra tooling needed.
+-->
+
+```mermaid
+sequenceDiagram
+    participant Frontend
+    participant API
+    participant Service
+    participant DB
+
+    Frontend->>API: POST /api/[resource] {payload}
+    API->>Service: [function_name](dto)
+    Service->>DB: INSERT / UPDATE [table]
+    DB-->>Service: return [entity]
+    Service-->>API: [ResponseSchema]
+    API-->>Frontend: 200 [ResponseDTO]
+
+    Note over Service,API: Error path
+    Service-->>API: raise [Exception] {detail: "..."}
+    API-->>Frontend: 4xx / 5xx {detail: "..."}
+```
+
+| Layer | Component | Responsibility |
+|-------|-----------|---------------|
+| Frontend | `pages/[feature]` | Form state, API call, display result |
+| API | `api/routes/[feature].py` | Request validation, auth check, delegate to service |
+| Service | `services/[feature].py` | Business logic, DB interaction |
+| DB | `models/[feature].py` | Persistence |
+
+---
+
 ## Complexity Tracking
 
 > Only fill in when a Constitution principle is violated and justification is required

.specify/templates/spec-template.md

@@ -5,6 +5,31 @@
 **Status**: Draft
 **Input**: User description: "$ARGUMENTS"
 
+## Process Flow *(include if feature involves a multi-step business process or cross-role workflow)*
+
+<!--
+  Describe the end-to-end business process BEFORE breaking it into user stories.
+  Focus on WHO does WHAT and in what ORDER — not on technical implementation.
+  Use a Mermaid sequenceDiagram and a step table. Renders natively on GitHub — no extra tooling needed.
+-->
+
+```mermaid
+sequenceDiagram
+    actor ActorA
+    participant System
+    actor ActorB
+
+    ActorA->>System: [action]
+    System-->>ActorB: [notification / response]
+    ActorB->>System: [confirmation / next action]
+```
+
+| Step | Role | Action | System Response |
+|------|------|--------|----------------|
+| 1 | [Role] | [What they do] | [What the system does] |
+
+---
+
 ## User Scenarios & Testing *(required)*
 
 <!--
@@ -54,6 +79,30 @@
 - **FR-002**: The system MUST [specific capability]
 - **FR-003**: Users MUST be able to [key interaction]
 
+### User Flow & Navigation *(include if feature introduces new pages or modifies navigation)*
+
+<!--
+  1. Map every screen and its navigation triggers to prevent orphan pages.
+  2. Include a Mermaid flowchart for flows with 3+ screens or branching paths.
+  Renders natively on GitHub — no extra tooling needed.
+-->
+
+```mermaid
+flowchart LR
+    Login --> |login success| Dashboard
+    Dashboard --> |click avatar| Profile
+    Profile --> |sidebar link| Dashboard
+    Dashboard --> |sign out| Login
+```
+
+| From | Trigger | To |
+|------|---------|-----|
+| [Page A] | [e.g. click avatar] | [Page B] |
+| [Page B] | [e.g. sidebar link] | [Page A] |
+
+**Entry points**: [Which existing pages link INTO the new pages?]
+**Exit points**: [Which pages can users navigate to FROM the new pages?]
+
 ### Key Entities *(include if feature involves data)*
 
 - **[Entity 1]**: [What it represents, key attributes]