AutoForgeAI · cabana8471-arch · Jan 31, 2026 · Jan 31, 2026
diff --git a/.claude/commands/create-spec.md b/.claude/commands/create-spec.md
@@ -95,7 +95,64 @@ Ask the user about their involvement preference:
 
 **For Detailed Mode users**, ask specific tech questions about frontend, backend, database, etc.
 
-### Phase 3b: Database Requirements (MANDATORY)
+### Phase 3b: UI Component Library (OPTIONAL)
+
+Ask the user which UI component library they prefer. This step helps configure automated component generation.
+
+> "Would you like to use a UI component library for faster development?
+>
+> 1. **shadcn/ui (Recommended for React)** - Beautiful, accessible components with Radix primitives
+>    - Copy-paste approach (you own the code)
+>    - MCP-enabled: Agent can generate components automatically
+>
+> 2. **Ark UI (Recommended for multi-framework)** - Headless primitives for any framework
+>    - Works with React, Vue, Solid, Svelte
+>    - MCP-enabled: Agent can generate components automatically
+>
+> 3. **Radix UI** - Low-level headless primitives
+>    - Requires manual styling
+>    - Uses frontend-design skill for component creation
+>
+> 4. **None/Custom** - Build components from scratch
+>    - Full control, more development time
+>    - Uses frontend-design skill for component creation
+>
+> 5. **Skip this question** - Use default (no library)"
+
+**Framework validation:** If user chooses shadcn/ui but their framework isn't React, warn them and suggest Ark UI instead.
+
+### Phase 3c: Visual Style (OPTIONAL)
+
+Ask the user which visual style they prefer. This step configures design tokens for consistent styling.
+
+> "What visual style do you prefer for your app?
+>
+> 1. **Modern/Clean (Recommended)** - Minimal, professional design
+>    - Uses library defaults, no custom tokens needed
+>
+> 2. **Neobrutalism** - Bold colors, hard shadows, no border-radius
+>    - High contrast, playful aesthetic
+>    - Generates design tokens: 4px borders, offset shadows
+>
+> 3. **Glassmorphism** - Frosted glass effects, blur, transparency
+>    - Subtle gradients, floating elements
+>    - Generates design tokens: backdrop-blur, low opacity backgrounds
+>
+> 4. **Retro/Arcade** - Pixel-art inspired, vibrant neons
+>    - 8-bit aesthetic, chunky borders
+>    - Generates design tokens: sharp corners, neon gradients
+>
+> 5. **Custom** - Define your own design tokens
+>    - Maximum flexibility
+>
+> 6. **Skip this question** - Use default (Modern/Clean)"
+
+**Behavior:**
+- If user skips or chooses "Modern/Clean", no design tokens file is generated
+- Other styles generate `.autocoder/design-tokens.json` with appropriate presets
+- The coding agent will apply these tokens when building components
+
+### Phase 3d: Database Requirements (MANDATORY)
 
 **Always ask this question regardless of mode:**
 
@@ -236,7 +293,7 @@ These are just reference points - your actual count should come from the require
 
 **MANDATORY: Infrastructure Features**
 
-If the app requires a database (Phase 3b answer was "Yes" or "Not sure"), you MUST include 5 Infrastructure features (indices 0-4):
+If the app requires a database (Phase 3d answer was "Yes" or "Not sure"), you MUST include 5 Infrastructure features (indices 0-4):
 1. Database connection established
 2. Database schema applied correctly
 3. Data persists across server restart
@@ -457,6 +514,19 @@ Create a new file using this XML structure:
     <typography>
       [Font preferences]
     </typography>
+
+    <ui_components>
+      <!-- Based on Phase 3b selection -->
+      <library>[shadcn-ui | ark-ui | radix-ui | none]</library>
+      <framework>[react | vue | solid | svelte]</framework>
+      <has_mcp>[true if shadcn-ui or ark-ui, false otherwise]</has_mcp>
+    </ui_components>
+
+    <visual_style>
+      <!-- Based on Phase 3c selection -->
+      <style>[default | neobrutalism | glassmorphism | retro | custom]</style>
+      <design_tokens_path>[.autocoder/design-tokens.json if style != default, empty otherwise]</design_tokens_path>
+    </visual_style>
   </design_system>
 
   <implementation_steps>

diff --git a/.claude/templates/app_spec.template.txt b/.claude/templates/app_spec.template.txt
@@ -216,6 +216,44 @@
       - Loading spinners
       - Skeleton loaders
     </animations>
+
+    <ui_components>
+      <!--
+        UI Component Library Configuration
+        ==================================
+        Specifies which component library to use for building UI.
+
+        Options for library:
+        - shadcn-ui: Beautiful, accessible React components (copy-paste approach)
+        - ark-ui: Headless primitives for React, Vue, Solid, Svelte
+        - radix-ui: Low-level headless primitives (requires manual styling)
+        - none: Build components from scratch
+
+        has_mcp indicates if an MCP server is available for rapid component generation.
+      -->
+      <library>none</library>
+      <framework>react</framework>
+      <has_mcp>false</has_mcp>
+    </ui_components>
+
+    <visual_style>
+      <!--
+        Visual Style Configuration
+        ==========================
+        Defines the overall visual aesthetic of the application.
+
+        Options for style:
+        - default: Clean, minimal design following library defaults
+        - neobrutalism: Bold colors, hard shadows, no border-radius
+        - glassmorphism: Frosted glass effects, blur, transparency
+        - retro: Pixel-art inspired, vibrant neons, 8-bit aesthetic
+        - custom: Define your own design tokens
+
+        design_tokens_path points to a JSON file with custom tokens (optional).
+      -->
+      <style>default</style>
+      <design_tokens_path></design_tokens_path>
+    </visual_style>
   </design_system>
 
   <key_interactions>

diff --git a/.claude/templates/coding_prompt.template.md b/.claude/templates/coding_prompt.template.md
@@ -141,6 +141,14 @@ Use browser automation tools:
 
 **You MUST complete ALL of these checks before marking any feature as "passes": true**
 
+#### UI & Design Verification (if UI components are involved)
+
+- [ ] Used MCP tools for component generation when available (`mcp__ui_components__*`)
+- [ ] Components follow the project's visual style (check `app_spec.txt` for style setting)
+- [ ] If design tokens exist (`.autocoder/design-tokens.json`), styling matches the tokens
+- [ ] Components are accessible (proper ARIA labels, keyboard navigation)
+- [ ] Responsive at desktop (1920px), tablet (768px), and mobile (375px)
+
 #### Security Verification (for protected features)
 
 - [ ] Feature respects user role permissions
@@ -336,6 +344,28 @@ Test like a human user with mouse and keyboard. Use `browser_console_messages` t
 
 ---
 
+## UI COMPONENT GENERATION
+
+When building UI components, check if MCP tools are available for component generation:
+
+- `mcp__ui_components__list_components` - See all available components in the library
+- `mcp__ui_components__get_example` - Get implementation code for a component
+- `mcp__ui_components__styling_guide` - Understand the styling approach
+
+**If these tools are available**, use them to generate components quickly instead of building from scratch.
+
+**If these tools are NOT available**, use the frontend-design skill for component creation:
+- Invoke `/frontend-design` for complex UI components
+- Follow the project's visual style from `app_spec.txt`
+- Check `.autocoder/design-tokens.json` for style tokens if they exist
+
+**Visual Style Application:**
+1. Read the `<visual_style>` section in `app_spec.txt`
+2. If a design tokens file exists, apply those values to your CSS/Tailwind
+3. Maintain consistency across all components
+
+---
+
 ## FEATURE TOOL USAGE RULES (CRITICAL - DO NOT VIOLATE)
 
 The feature tools exist to reduce token usage. **DO NOT make exploratory queries.**

diff --git a/.claude/templates/initializer_prompt.template.md b/.claude/templates/initializer_prompt.template.md
@@ -272,6 +272,27 @@ The feature_list.json **MUST** include tests from ALL 20 categories. Minimum cou
 
 ---
 
+## UI COMPONENT LIBRARY
+
+Check the `<ui_components>` section in `app_spec.txt` for the UI library configuration:
+
+- **library**: The component library to use (shadcn-ui, ark-ui, radix-ui, or none)
+- **framework**: The frontend framework (react, vue, solid, svelte)
+- **has_mcp**: Whether MCP tools are available for component generation
+
+If `has_mcp` is `true`, the coding agent will have access to MCP tools for rapid component generation. Factor this into feature descriptions where relevant.
+
+## VISUAL STYLE
+
+Check the `<visual_style>` section in `app_spec.txt` for styling configuration:
+
+- **style**: The visual aesthetic (default, neobrutalism, glassmorphism, retro, custom)
+- **design_tokens_path**: Path to custom design tokens JSON if applicable
+
+For non-default styles, style-specific tests may be included (e.g., "Button has 4px border and offset shadow" for neobrutalism).
+
+---
+
 ## ABSOLUTE PROHIBITION: NO MOCK DATA
 
 The feature_list.json must include tests that **actively verify real data** and **detect mock data patterns**.

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -203,6 +203,7 @@ Projects can be stored in any directory (registered in `~/.autocoder/registry.db
 - `features.db` - SQLite database with feature test cases
 - `.agent.lock` - Lock file to prevent multiple agent instances
 - `.autocoder/allowed_commands.yaml` - Project-specific bash command allowlist (optional)
+- `.autocoder/design-tokens.json` - Visual style design tokens (generated for non-default styles)
 
 ### Security Model
 
@@ -320,6 +321,69 @@ blocked_commands:
 - `examples/README.md` - Comprehensive guide with use cases, testing, and troubleshooting
 - `PHASE3_SPEC.md` - Specification for mid-session approval feature (future enhancement)
 
+### UI Component MCP Servers
+
+The agent can use MCP servers for rapid UI component generation when a compatible library is configured in `app_spec.txt`.
+
+**Supported Libraries:**
+- `shadcn-ui` - Beautiful, accessible React components (MCP enabled)
+- `ark-ui` - Headless primitives for React, Vue, Solid, Svelte (MCP enabled)
+- `radix-ui` - Low-level headless primitives (no MCP, uses frontend-design skill)
+- `none` - Custom components (no MCP, uses frontend-design skill)
+
+**Configuration in app_spec.txt:**
+```xml
+<ui_components>
+  <library>shadcn-ui</library>
+  <framework>react</framework>
+  <has_mcp>true</has_mcp>
+</ui_components>
+```
+
+**MCP Tools Available:**
+- `mcp__ui_components__list_components` - List available components
+- `mcp__ui_components__get_example` - Get component implementation code
+- `mcp__ui_components__styling_guide` - Get styling documentation
+
+**Environment Variables:**
+- `DISABLE_UI_MCP=true` - Disable UI MCP server (for troubleshooting)
+- `MCP_SHADCN_VERSION=1.0.0` - Pin shadcn MCP server version
+- `MCP_ARK_VERSION=0.1.0` - Pin Ark UI MCP server version
+- `GITHUB_PERSONAL_ACCESS_TOKEN` - GitHub token for better rate limits (optional)
+
+### Visual Styles and Design Tokens
+
+Projects can specify a visual style that generates design tokens for consistent styling.
+
+**Available Styles:**
+- `default` - Clean, minimal design (no tokens generated)
+- `neobrutalism` - Bold colors, hard shadows, 4px borders, no border-radius
+- `glassmorphism` - Frosted glass effects, blur, transparency
+- `retro` - Pixel-art inspired, vibrant neons, 8-bit aesthetic
+- `custom` - User-defined tokens
+
+**Configuration in app_spec.txt:**
+```xml
+<visual_style>
+  <style>neobrutalism</style>
+  <design_tokens_path>.autocoder/design-tokens.json</design_tokens_path>
+</visual_style>
+```
+
+**Design Tokens File (generated for non-default styles):**
+```json
+{
+  "borders": {"width": "4px", "radius": "0"},
+  "shadows": {"default": "4px 4px 0 0 currentColor"},
+  "colors": {"primary": "#ff6b6b", "secondary": "#4ecdc4"}
+}
+```
+
+**Files:**
+- `app_spec_parser.py` - Shared parser for UI config from app_spec.txt
+- `design_tokens.py` - Design token generation and style presets
+- `test_ui_config.py` - Unit tests for UI configuration
+
 ### Ollama Local Models (Optional)
 
 Run coding agents using local models via Ollama v0.14.0+: