Component Driven Development
How do you launch a new product in days instead of months?
Build components in isolation. Prove they work. Compose from the bottom up. When a new venture plugs in, it inherits everything the proving ground already verified. That is the speed promise made concrete.
Proving Ground
A design system application — separate from any product — serves as the proving ground where every component is tested in isolation before any venture consumes it.
The proving ground:
- Renders every component in every state (default, loading, error, empty, disabled)
- Organizes components by boundary type with a live dependency graph
- Documents props with interactive examples, not static docs
- Catches visual regressions through snapshot comparison
- Proves accessibility before a component reaches a page
If a component cannot render in the proving ground, it has a hidden dependency. Find it and extract it before integrating.
The proving ground is also the onboarding tool. A new developer browses it to learn what exists before building something new. A new venture checks it to see what is already solved.
Atomic Hierarchy
Components nest in predictable layers. Each layer has a size gate — cross it and you need to decompose.
| Level | Definition | Example | Reuse Scope | Size Gate |
|---|---|---|---|---|
| Atom | Single-purpose element, no children | Button, Input, Badge | Entire platform | <30 lines, <3 props |
| Molecule | 2-4 atoms with one job | Search field (input + button) | Entire platform | <80 lines, <7 props |
| Organism | Molecules + atoms forming a distinct section | Navigation bar, Data table | Feature or product | <150 lines, <10 props |
| Template | Page layout with placeholder slots | Dashboard layout, Settings shell | Product | Defines slots, no data |
| Page | Template filled with real data | /settings/team | Single route | Composes organisms into template |
The hierarchy is a smell test. If a molecule has 12 props, it is an organism pretending to be simple.
Boundary System
Not all components belong in the same library. The boundary determines dependency rules — and dependency rules determine how fast a new venture gets to market.
| Boundary Type | What Lives Here | Dependency Rule | Example |
|---|---|---|---|
| Generic interactive | Buttons, modals, inputs, tabs | Zero domain imports | Button, Dialog, Tabs |
| Generic forms | Fields, validation wrappers, form layouts | May import generic interactive | FormField, DatePicker |
| Generic marketing | Heroes, feature grids, testimonials, CTAs | May import generic interactive | HeroSection, PricingCard |
| Domain-specific | Business logic components | May import any generic boundary | DealPipeline, AgentCard |
| Specialized | Maps, 3D, blockchain, rich editors | Own dependency tree, isolated | MapView, WalletConnect |
The decision: can another product use this component unchanged? YES — generic boundary. NO — domain-specific.
Generic boundaries never import from domain or specialized. Domain may import generic. Specialized imports nothing from the product. When a new venture plugs in, it gets every generic boundary for free. Zero rework.
Maturation Pipeline
Components mature through three consumption modes. This is the same commissioning pattern the entire platform uses — testing, operational, optimized — applied to UI.
| Mode | Stage | When | What You Get |
|---|---|---|---|
| Compare | Testing | Exploring approaches, not committed | Side-by-side prototypes in the proving ground |
| Copy | Operational | Customizing heavily for a specific product | Source files in your project, diverging from shared |
| Import | Optimized | Proven, stable, used in 3+ places | Shared library, single source of truth |
COMPARE graduates to IMPORT when one approach wins and stabilizes across 3 uses. IMPORT graduates to COPY only when you need to diverge permanently from the shared version — and that divergence should be rare if the boundaries are right.
The maturation pipeline runs in the proving ground. Components enter as experiments (COMPARE), earn their place through repeated use (IMPORT), and only fork when a venture has a genuinely unique need (COPY).
Composition Score
The ratio of library imports to raw HTML on a page is the metric that proves the platform works for UI.
| Composition Ratio | What It Means |
|---|---|
| >80% library imports | The proving ground carried the UI — new venture launched at speed |
| 60-80% | Gaps in the component library — some custom work needed |
| <50% | The proving ground has holes — components being rebuilt instead of reused |
This is the CDD equivalent of the content graph's composition ratio. Same pattern, different layer. High composition means the mycelium carried the work. Low composition means the venture had to grow its own roots.
Health Signals
| Signal | Healthy | Unhealthy |
|---|---|---|
| Props per component | <=7 | >10 (god component) |
| File length | <150 lines | >300 lines (needs decomposition) |
| Nesting depth | <=3 levels | >4 levels (flatten or extract) |
| Prop drilling depth | <=2 levels | >3 levels (use context or composition) |
| Children vs props for content | Children for layout | Props for everything (inflexible) |
Anti-patterns to catch early:
- God components — one file renders an entire page section with 15+ props
- Barrel imports — re-exporting everything from
index.tskills tree-shaking - Prop drilling — passing data through 3+ levels instead of composing with children or context
- Premature abstraction — creating a shared component before the third use
Decision Tree
When you need a new component, walk this path:
New component needed
→ Does it exist in the proving ground?
YES → Import it
NO → Will multiple products use it?
YES → Build in generic boundary, add to proving ground
NO → Will multiple features use it?
YES → Build in domain boundary
NO → Co-locate with the feature
Co-located components graduate to domain boundary after the third feature uses them. Domain components graduate to generic boundary after the third product uses them. Every graduation adds to the proving ground — the library grows through use, not planning.
Context
- Component Design — The creation checklist for a single component
- Design System — Tokens, typography, and visual patterns
- Maps — CDD applied to specialized map components
- Hexagonal Architecture — Boundary thinking applied to the full stack
Links
- Atomic Design (Brad Frost) — The original hierarchy framework
- componentdriven.org — The methodology and community
- Storybook — The most common proving ground implementation
Questions
What composition ratio would prove the platform delivers on its speed promise?
- When has a component earned promotion from domain-specific to generic — usage count, stability duration, or venture demand?
- How do you measure whether boundary separation is actually preventing dependency leaks across products?
- At what point does a design system become a constraint rather than an accelerator — and what is the early warning signal?