sar/.agents/skills/wds-4-ux-design/data/modular-architecture/workflow.md

name, description

name	description
Modular Component Architecture	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

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

• Overview of Pages, Components, and Features separation
• When to use each tier
• Benefits of separation

Content Placement Rules

• Decision tree for where to document content
• Simple vs complex component rules
• Page-specific vs shared content

Complexity Detection

• 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

• Step-by-step page decomposition from sketch to specs
• Extracting components from page layouts
• Handling page-specific content

Complexity Router Workflow

• Guided decomposition for complex components
• When to create feature folders
• Substep breakdown patterns

Storyboards Guide

• 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

• One-page flowchart for file placement
• Quick decision making
• Common scenarios

Benefits Summary

• 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

This provides detailed index of all files including examples and substeps.

---

QUICK START

"Where do I document this component?"

Start here: Content Placement Rules

Then use: Decision Tree

---

"How do I write a page specification?"

Start here: Page Specification Workflow

Reference: Three-Tier Overview

---

"When should I decompose a component?"

Start here: Complexity Detection

Then use: Complexity Router Workflow

---

"How do I document complex interactions?"

Start here: Storyboards Guide

Reference: Complexity Router Workflow

---

INTEGRATION WITH WDS

During Page Specification Phase

After sketching, before implementation:

1. Review page sketch
2. Apply Page Specification Workflow
3. Use Content Placement Rules for each component
4. Document simple components inline
5. Create feature folders for complex components
6. Use Complexity Router 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

Look for: Multiple states, conditional logic, nested interactions

"I'm not sure where to document this content"

Use: Decision Tree

Ask: Is it page-specific or shared? Simple or complex?

"The page specification feels too long"

Use: Complexity Router Workflow

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