bd495be965
All checks were successful
Deploy to Production / Build and Deploy (push) Successful in 12s
- Sidebar: dynamic brand-accent colors, brainstorm section restyled - AI chat general: popup panel with expand/collapse, hides when contextual AI open - AI chat contextual: tabs reordered (Actions first), X close button, height fix - Settings: all tabs restyled, 6 new color presets (sage, terracotta, iron, etc.) - Global color cleanup: emerald/orange hardcoded → brand-accent dynamic - Brainstorm page: orange → brand-accent throughout - PageEntry animation component added to key pages - Floating AI button: bg-brand-accent instead of hardcoded black - i18n: all 15 locales updated with new AI/billing keys - Billing: freemium quota tracking, BYOK, stripe subscription scaffolding - Admin: integrated into new design - AGENTS.md + CLAUDE.md project rules added
289 lines
7.2 KiB
Markdown
289 lines
7.2 KiB
Markdown
---
|
|
name: Modular Component Architecture
|
|
description: Reference guides for three-tier specification system (Pages, Components, Features)
|
|
---
|
|
|
|
# Modular Component Architecture
|
|
|
|
**Goal:** Understand and apply three-tier architecture for component specification
|
|
|
|
**Your Role:** Architecture reference for designing modular, maintainable component systems
|
|
|
|
---
|
|
|
|
## OVERVIEW
|
|
|
|
This is a **guide collection** for three-tier modular architecture, not a step-by-step workflow.
|
|
|
|
**Three-Tier System:**
|
|
- **Pages** - Full page layouts and compositions
|
|
- **Components** - Reusable UI elements (simple and complex)
|
|
- **Features** - Complex component decompositions
|
|
|
|
**Purpose:** Separate concerns, reduce duplication, enable modularity
|
|
|
|
---
|
|
|
|
## WHEN TO USE
|
|
|
|
**Use these guides when:**
|
|
- ✅ Writing page specifications
|
|
- ✅ Decomposing complex components
|
|
- ✅ Deciding where to document content
|
|
- ✅ Need to understand component complexity
|
|
- ✅ Want to optimize agent-designer collaboration
|
|
|
|
**Skip these guides when:**
|
|
- ❌ Building simple prototypes without specs
|
|
- ❌ Already familiar with the architecture
|
|
- ❌ Using different specification system
|
|
|
|
---
|
|
|
|
## THE FOUR SECTIONS
|
|
|
|
### 00. Foundation
|
|
|
|
**[Agent-Designer Collaboration](00-foundation/agent-designer-collaboration.md)**
|
|
|
|
How AI agents optimize designer craft without replacing designer thinking.
|
|
|
|
**Use when:** Understanding the philosophy behind modular architecture
|
|
|
|
**Topics:**
|
|
- Designer maintains creative control
|
|
- AI handles decomposition and optimization
|
|
- Collaborative workflow patterns
|
|
|
|
---
|
|
|
|
### 01. Core Concepts
|
|
|
|
Three fundamental concepts of the architecture:
|
|
|
|
**[Three-Tier Overview](01-core-concepts/three-tier-overview.md)**
|
|
- Overview of Pages, Components, and Features separation
|
|
- When to use each tier
|
|
- Benefits of separation
|
|
|
|
**[Content Placement Rules](01-core-concepts/content-placement-rules.md)**
|
|
- Decision tree for where to document content
|
|
- Simple vs complex component rules
|
|
- Page-specific vs shared content
|
|
|
|
**[Complexity Detection](01-core-concepts/complexity-detection.md)**
|
|
- How to identify simple vs complex components
|
|
- When to decompose further
|
|
- Complexity indicators
|
|
|
|
**Use when:** Learning the architecture or making placement decisions
|
|
|
|
---
|
|
|
|
### 02. Workflows
|
|
|
|
Practical workflows for applying the architecture:
|
|
|
|
**[Page Specification Workflow](02-workflows/page-specification-workflow.md)**
|
|
- Step-by-step page decomposition from sketch to specs
|
|
- Extracting components from page layouts
|
|
- Handling page-specific content
|
|
|
|
**[Complexity Router Workflow](02-workflows/complexity-router-workflow.md)**
|
|
- Guided decomposition for complex components
|
|
- When to create feature folders
|
|
- Substep breakdown patterns
|
|
|
|
**[Storyboards Guide](02-workflows/storyboards-guide.md)**
|
|
- Using visual storyboards for complex components
|
|
- State documentation
|
|
- Interaction flows
|
|
|
|
**Use when:** Actively creating specifications
|
|
|
|
---
|
|
|
|
### 03. Quick References
|
|
|
|
Fast lookup guides for common questions:
|
|
|
|
**[Decision Tree](03-quick-refs/decision-tree.md)**
|
|
- One-page flowchart for file placement
|
|
- Quick decision making
|
|
- Common scenarios
|
|
|
|
**[Benefits Summary](03-quick-refs/benefits.md)**
|
|
- Why this architecture works
|
|
- Advantages of three-tier system
|
|
- Problem it solves
|
|
|
|
**Use when:** Need quick answers or reminders
|
|
|
|
---
|
|
|
|
## DETAILED NAVIGATION
|
|
|
|
For comprehensive navigation of all guides and substeps:
|
|
|
|
**[Modular Architecture Guide](00-MODULAR-ARCHITECTURE-GUIDE.md)**
|
|
|
|
This provides detailed index of all files including examples and substeps.
|
|
|
|
---
|
|
|
|
## QUICK START
|
|
|
|
### "Where do I document this component?"
|
|
|
|
Start here: [Content Placement Rules](01-core-concepts/content-placement-rules.md)
|
|
|
|
Then use: [Decision Tree](03-quick-refs/decision-tree.md)
|
|
|
|
---
|
|
|
|
### "How do I write a page specification?"
|
|
|
|
Start here: [Page Specification Workflow](02-workflows/page-specification-workflow.md)
|
|
|
|
Reference: [Three-Tier Overview](01-core-concepts/three-tier-overview.md)
|
|
|
|
---
|
|
|
|
### "When should I decompose a component?"
|
|
|
|
Start here: [Complexity Detection](01-core-concepts/complexity-detection.md)
|
|
|
|
Then use: [Complexity Router Workflow](02-workflows/complexity-router-workflow.md)
|
|
|
|
---
|
|
|
|
### "How do I document complex interactions?"
|
|
|
|
Start here: [Storyboards Guide](02-workflows/storyboards-guide.md)
|
|
|
|
Reference: [Complexity Router Workflow](02-workflows/complexity-router-workflow.md)
|
|
|
|
---
|
|
|
|
## INTEGRATION WITH WDS
|
|
|
|
### During Page Specification Phase
|
|
|
|
After sketching, before implementation:
|
|
|
|
1. Review page sketch
|
|
2. Apply [Page Specification Workflow](02-workflows/page-specification-workflow.md)
|
|
3. Use [Content Placement Rules](01-core-concepts/content-placement-rules.md) for each component
|
|
4. Document simple components inline
|
|
5. Create feature folders for complex components
|
|
6. Use [Complexity Router](02-workflows/complexity-router-workflow.md) for decomposition
|
|
|
|
### During Prototype Implementation
|
|
|
|
When building from specs:
|
|
|
|
1. Read page specification
|
|
2. Identify shared vs page-specific components
|
|
3. Build modular component library
|
|
4. Reference storyboards for complex interactions
|
|
|
|
---
|
|
|
|
## ARCHITECTURE BENEFITS
|
|
|
|
**For Designers:**
|
|
- ✅ Reduced duplication
|
|
- ✅ Clear decision framework
|
|
- ✅ Maintain creative control
|
|
- ✅ Better AI collaboration
|
|
|
|
**For Developers:**
|
|
- ✅ Modular component structure
|
|
- ✅ Clear implementation boundaries
|
|
- ✅ Reusable components identified
|
|
- ✅ Less ambiguity
|
|
|
|
**For Teams:**
|
|
- ✅ Consistent specification format
|
|
- ✅ Scalable architecture
|
|
- ✅ Easier maintenance
|
|
- ✅ Better handoff quality
|
|
|
|
---
|
|
|
|
## KEY PRINCIPLES
|
|
|
|
**1. Separation of Concerns**
|
|
- Pages handle layout and composition
|
|
- Components define reusable elements
|
|
- Features decompose complex components
|
|
|
|
**2. DRY (Don't Repeat Yourself)**
|
|
- Define once, reference everywhere
|
|
- Shared components in component library
|
|
- Page-specific variants documented inline
|
|
|
|
**3. Progressive Complexity**
|
|
- Start simple
|
|
- Decompose only when needed
|
|
- Use complexity detection to guide decisions
|
|
|
|
**4. Designer Agency**
|
|
- AI assists but doesn't replace designer thinking
|
|
- Designer makes final placement decisions
|
|
- Architecture enables, doesn't constrain
|
|
|
|
---
|
|
|
|
## TROUBLESHOOTING
|
|
|
|
### "I don't know if my component is complex enough to decompose"
|
|
|
|
Use: [Complexity Detection](01-core-concepts/complexity-detection.md)
|
|
|
|
Look for: Multiple states, conditional logic, nested interactions
|
|
|
|
### "I'm not sure where to document this content"
|
|
|
|
Use: [Decision Tree](03-quick-refs/decision-tree.md)
|
|
|
|
Ask: Is it page-specific or shared? Simple or complex?
|
|
|
|
### "The page specification feels too long"
|
|
|
|
Use: [Complexity Router Workflow](02-workflows/complexity-router-workflow.md)
|
|
|
|
Extract complex components to feature folders
|
|
|
|
---
|
|
|
|
## EXAMPLES
|
|
|
|
Throughout the guides, you'll find examples:
|
|
|
|
- **Simple Button** - Single file documentation
|
|
- **Complex Calendar** - Three-tier decomposition
|
|
- **Search Bar** - Page-specific content handling
|
|
|
|
These demonstrate the architecture in practice.
|
|
|
|
---
|
|
|
|
## NOTES
|
|
|
|
**This is architecture guidance** - not mandatory workflow steps.
|
|
|
|
Apply as needed based on:
|
|
- Project complexity
|
|
- Team size
|
|
- Specification requirements
|
|
- Development process
|
|
|
|
The architecture scales from small to large projects.
|
|
|
|
**Start simple, add structure when needed.**
|
|
|
|
---
|
|
|
|
_Modular Component Architecture - Clear structure, better collaboration_
|