chore: initial monorepo scaffold + WDS Phase 1+2 artifacts
- Nx 22.7 monorepo (pnpm 11.1, TypeScript 5.9, Node 24) - apps/api: NestJS 11 (CJS conforme CODING-RULES.md PGD-DB-004) - apps/web: React 19 + Vite 8 (ESM) - libs/shared/api-interface: Zod contract base - Docker Compose dev: Postgres 18, Valkey 8, MinIO, Mailpit - WDS artifacts: - design-artifacts/A-Product-Brief/ (5 docs canônicos + 16 dialogs) - design-artifacts/B-Trigger-Map/ (hub + 4 personas + feature impact) - Stack canon: STACK.md v2.2 + CODING-RULES.md v2.0 + brand.md - AGENTS.md + README.md como entrada para devs/agentes Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,288 @@
|
||||
---
|
||||
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_
|
||||
Reference in New Issue
Block a user