Design System Proving Ground Spec
How do we turn a component museum into a proving ground where forms ship with a standard?
Intent Contract
Agent autonomy boundary. Not parsed by engineering — governance instrument for humans and agents.
| Dimension | Statement |
|---|---|
| Objective | Unify forms navigation, document THE standard process, rewrite CRM patterns to use lib atoms, and stress-test composition depth with a meeting agenda form — turning stackmat.es from component museum to proving ground. |
| Outcomes | 1. Single /forms index replaces 3 nav locations. 2. Standard process page (Zod -> Server Action -> FormShell -> Name Attrs -> TanStack) discoverable in <30s. 3. CRM pattern pages L:R ratio improves from 1:15 to 1:3 or better. |
| Health Metrics | Existing form atom Storybook tests stay green. Anti-pattern documentation preserved. Accessibility annotations on form atoms undamaged. |
| Counter-metrics | Page count must not increase — consolidate, don't proliferate. Build time must not regress. Navigation depth must not exceed 3 clicks from homepage to any form page. |
| Constraints | Hard: Every page built from lib imports only (Prime Directive). No _components/ local directory. No real data wiring — console.log or alert only. Steering: Tailwind v4.1 with @theme bridge. L:R ratio target 1:3 or better. |
| Autonomy | Allowed: page layout, content ordering, example data shapes. Escalate: new lib atoms, new organisms, nav hierarchy changes. Never: raw HTML form elements, inline styles bypassing design system, real API connections. |
| Blast Radius | Design system app only. No production app changes. No lib changes (unless DS-05 reveals gaps, which triggers a stop). Existing pattern pages restructured, not deleted. |
| Rollback | Revert nav changes in sidebar config. Restored pages from git history. CRM patterns revert to raw HTML (worse but functional). Zero data at risk — no data layer. |
| Stop Rules | Complete when: all 5 feature IDs at L2+ and meeting agenda form composes from lib atoms. Halt when: DS-05 requires >3 new lib atoms — stop and fill lib first. |
Story Contract
Stories are test contracts. Each row converts to test files. Tests must be RED before implementation starts. Tests going GREEN = value delivered.
| # | WHEN (Trigger + Precondition) | THEN (Exact Assertion) | ARTIFACT | Test Type | FORBIDDEN (Must not happen) | OUTCOME (Performance Number) |
|---|---|---|---|---|---|---|
| S1 | Engineer navigates to /forms (page exists in sidebar, forms content scattered across 3 locations) | Single index page renders with links to all form content: atoms, patterns, anti-patterns, checklist. Sidebar shows one "Forms" entry. document.querySelectorAll('[data-section="forms"]') returns exactly 1 sidebar item. | BLOCKER: design system app test infrastructure TBD | e2e | Forms still appear in 3+ sidebar locations. Index page is a stub with "contribute this section." | Navigation to any form page in <2 clicks vs current 3+ locations with dead ends |
| S2 | Engineer opens standard process page (form atoms exist in lib, no standard process documented in one place) | Page renders THE chain: Zod schema -> Server Action -> FormShell -> Name Attrs -> TanStack binding. Each step links to the relevant lib source. Code example is copy-pasteable. | BLOCKER: design system app test infrastructure TBD | e2e | Page describes the process in prose without runnable code. Page links to external docs instead of showing the chain. | Standard process discoverable in <30s vs tribal knowledge taking days to acquire |
| S3 | Engineer opens form shipping checklist (standard process page exists, no pre-ship verification) | 10-point checklist renders with pass/fail criteria for each gate. Every gate references a specific lib atom or pattern. Checklist is printable. | BLOCKER: design system app test infrastructure TBD | e2e | Checklist has vague items like "looks good" or "works correctly." Checklist references components that don't exist in lib. | 10-point gate checked in <5 min vs ad-hoc review missing issues |
| S4 | Engineer opens CRM contact form pattern (CRM pages currently use raw HTML with L:R 1:15) | Page renders contact form using only @stackmates/ui imports. Zero raw <input>, <select>, or <form> elements. L:R ratio 1:3 or better. | BLOCKER: design system app test infrastructure TBD | integration | Any raw HTML form element in the page source. L:R ratio worse than 1:5. | L:R ratio 1:3 vs current 1:15 — 5x improvement in lib composition |
| S5 | Engineer opens meeting agenda form (lib atoms exist, FormShell is the only organism, Tight Five schema maps to 5 form fields) | MeetingAgenda form renders 5 labeled fields (one per Tight Five question) composed from lib atoms. FormShell wraps the form. No _components/ directory exists. Form submits to console.log. | BLOCKER: design system app test infrastructure TBD | integration | MeetingAgenda requires local _components/ directory. Form uses raw HTML. More than 3 new atoms needed that don't exist in lib. | Organism composed from existing atoms in <2 hours vs "lib can't handle this" |
Tight Five coverage check:
| P Dimension | Stories covering it |
|---|---|
| Pain (can't find the standard) | S1 (unified nav), S2 (standard process) |
| Demand (builders need to ship forms) | S3 (shipping checklist), S4 (CRM rewrite proves demand) |
| Edge (three-mode architecture) | S5 (meeting form = composition stress test) |
| Trend (design systems + AI code gen) | S2 (standard process as AI-readable reference) |
| Conversion (can we ship it) | S4 (CRM rewrite = existing content improved), S1 (nav consolidation) |
Build Contract
The deliverable. Engineering builds from this. Commissioning reads this.
Find the Standard
| # | FeatureID | Function | Artifact | Success Test | Safety Test | Regression Test | Value | State |
|---|---|---|---|---|---|---|---|---|
| 1 | DS-01 | Unify forms navigation into single sidebar entry | /forms index page + sidebar config | Single "Forms" entry in sidebar; index links all form content (S1) | Forms must not appear in 3+ nav locations after change (S1 FORBIDDEN) | Existing form atom and pattern pages must remain accessible | One place for all form content | Gap |
| 2 | DS-02 | Document THE standard form process chain | Standard process reference page | Page shows Zod -> Server Action -> FormShell -> Name Attrs -> TanStack with copy-pasteable code (S2) | Process must not be prose-only without runnable code (S2 FORBIDDEN) | Existing anti-pattern documentation must not be removed | Engineer knows THE chain in 30 seconds | Gap |
| 3 | DS-03 | Create 10-point form shipping checklist | Form shipping gate page | 10 pass/fail criteria, each referencing specific lib atom or pattern (S3) | Checklist must not have vague items like "looks good" (S3 FORBIDDEN) | N/A — new page | Forms ship with verified quality | Gap |
Prove It Works
| # | FeatureID | Function | Artifact | Success Test | Safety Test | Regression Test | Value | State |
|---|---|---|---|---|---|---|---|---|
| 4 | DS-04 | Rewrite CRM patterns using lib atoms only | Rewritten CRM contact, deal, company form pages | Zero raw HTML form elements; L:R 1:3 or better (S4) | Must not introduce raw <input>, <select>, <form> (S4 FORBIDDEN) | Existing CRM page URLs must not change | CRM forms prove the standard works at L:R 1:3 | Gap |
| 5 | DS-05 | Build meeting agenda form from existing atoms | MeetingAgenda organism (Tight Five as form fields) | 5 labeled fields from lib atoms, FormShell wrapper, console.log submit (S5) | Must not require _components/ local dir or >3 new lib atoms (S5 FORBIDDEN) | Existing FormShell behavior must not change | Composition depth proven for real domain complexity | Gap |
Screen Contracts
Commissioning checklist. Each row is pass/fail. Walk the list after engineering ships.
Forms Index (/forms)
The entry point. Everything about forms starts here.
| # | Check | Pass when | Build ref | Feature ID |
|---|---|---|---|---|
| F1 | Single sidebar entry | "Forms" appears once in sidebar navigation. No other form-related entries elsewhere. | #1 | DS-01 |
| F2 | Links to atoms | Index page links to form atom documentation (Input, Select, Textarea, Checkbox). Links resolve. | #1 | DS-01 |
| F3 | Links to patterns | Index page links to form pattern pages (CRM contact, CRM deal, anti-patterns). Links resolve. | #1 | DS-01 |
| F4 | Links to standard process | Index page links to standard process reference page. Link resolves. | #1 | DS-01 |
| F5 | Links to checklist | Index page links to form shipping checklist. Link resolves. | #1 | DS-01 |
| F6 | No stubs | Zero "contribute this section" placeholders. Every link resolves to real content. | #1 | DS-01 |
Standard Process (/forms/standard-process)
THE reference. One page. One chain.
| # | Check | Pass when | Build ref | Feature ID |
|---|---|---|---|---|
| P1 | Chain visible | Zod -> Server Action -> FormShell -> Name Attrs -> TanStack shown as numbered steps with code. | #2 | DS-02 |
| P2 | Code copyable | Code example can be copied and pasted into a new form page. Syntax highlighted. | #2 | DS-02 |
| P3 | Links to lib | Each step links to the relevant lib source file or Storybook story. | #2 | DS-02 |
| P4 | Anti-patterns linked | Page links to existing anti-patterns documentation. | #2 | DS-02 |
Form Shipping Checklist (/forms/checklist)
The gate. 10 points. Pass or fail.
| # | Check | Pass when | Build ref | Feature ID |
|---|---|---|---|---|
| C1 | 10 gate items | Exactly 10 checklist items render. | #3 | DS-03 |
| C2 | Each item specific | Every item references a specific lib atom, pattern, or threshold — no vague "looks good." | #3 | DS-03 |
| C3 | Pass/fail format | Each item has a binary pass/fail criterion, not a subjective scale. | #3 | DS-03 |
CRM Contact Pattern (/patterns/crm/contact-form)
The rewrite proof. Raw HTML -> lib composition.
| # | Check | Pass when | Build ref | Feature ID |
|---|---|---|---|---|
| R1 | Zero raw HTML | Page source contains no raw <input>, <select>, <form> elements. | #4 | DS-04 |
| R2 | Lib imports only | All form elements import from @stackmates/ui. | #4 | DS-04 |
| R3 | L:R ratio | Composition ratio 1:3 or better (measured by lib imports vs local code lines). | #4 | DS-04 |
| R4 | URL preserved | Page URL unchanged from current pattern page. | #4 | DS-04 |
Meeting Agenda Form (/patterns/meetings/agenda)
The stress test. Composition depth for real domain complexity.
| # | Check | Pass when | Build ref | Feature ID |
|---|---|---|---|---|
| M1 | Five fields render | Five labeled form fields visible, one per Tight Five question. | #5 | DS-05 |
| M2 | Lib atoms only | All form fields use lib atoms (Input, Select, Textarea from @stackmates/ui). | #5 | DS-05 |
| M3 | FormShell wraps | FormShell organism wraps the entire form. | #5 | DS-05 |
| M4 | No local components | No _components/ directory exists under the pattern page. | #5 | DS-05 |
| M5 | Submit logs | Form submit calls console.log with structured field data. No API call. | #5 | DS-05 |
| M6 | Accessibility | All fields have associated labels. Form is keyboard navigable. Error states visible. | #5 | DS-05 |
Navigation Architecture
How does the user move from pain to the standard?
Pain-to-Perform Journey
| Stage | User State | What navigation must do | Current State | Target State |
|---|---|---|---|---|
| Pain | "Where's the form standard?" | Show the cost: 3 nav locations, dead ends, raw HTML | Forms in 3 sidebar sections, /forms 404s | Single /forms entry |
| Awareness | Finds the Forms section | Surface standard process link prominently on index | No index page exists | Index page with curated links |
| First Value | Reads the standard process | Deliver THE chain on one page with copyable code | Process is tribal knowledge | Standard process page renders the chain |
| Habit | Uses checklist before shipping | Link checklist from standard process page and form atom pages | No checklist exists | Checklist linked from all form pages |
| Mastery | Contributes new patterns | Meeting agenda form demonstrates how to add an organism | Only 1 organism (FormShell) exists | MeetingAgenda proves the path |
| Effortless | Patterns auto-scaffold | Template generator creates form pages pre-wired to lib atoms | Copy-paste from existing patterns | Future: CLI scaffolding (out of scope) |
Navigation States
| State | Sidebar | Forms Index | Pattern Pages | Standard Process |
|---|---|---|---|---|
| Flag OFF | Forms in 3 locations | 404 | Raw HTML CRM pages | Does not exist |
| Flag ON (S0) | Single "Forms" entry | Links to atoms + patterns | CRM pages rewritten with lib atoms | THE chain documented |
| Flag ON (S1) | Same | + checklist link | + meeting agenda pattern | + linked from checklist |
Cross-Cutting Navigation
| From | To | Trigger | What Happens |
|---|---|---|---|
| Homepage | /forms | "Forms" in sidebar | Routes to forms index |
| Forms index | /forms/standard-process | "Standard Process" link | Routes to THE chain |
| Forms index | /forms/checklist | "Shipping Checklist" link | Routes to 10-point gate |
| Forms index | /patterns/crm/contact-form | "CRM Contact" link | Routes to rewritten CRM pattern |
| Forms index | /patterns/meetings/agenda | "Meeting Agenda" link | Routes to organism stress test |
| Standard process | /forms/checklist | "Pre-ship checklist" link at bottom | Routes to shipping gate |
| Any form atom page | /forms | Breadcrumb | Routes back to forms index |
| Meeting agenda | Meetings PRD | "Full meeting spec" link | Routes to backburner PRD (context) |
Sidebar Hierarchy
Components
Atoms
Form ← existing, links to atom stories
Organisms
FormShell ← existing
MeetingAgenda ← DS-05 adds this
Forms ← DS-01 creates this section
Standard Process ← DS-02
Shipping Checklist ← DS-03
Patterns
CRM ← DS-04 rewrites these
Contact Form
Deal Form
Company Form
Meetings ← DS-05 adds this
Meeting Agenda
Wiring Coordinates
| Element | File | Action |
|---|---|---|
| Sidebar config | BLOCKER: stackmat.es sidebar config location TBD | Add "Forms" section, restructure pattern entries |
| Forms index page | BLOCKER: stackmat.es page creation pattern TBD | New page at /forms route |
| Standard process page | BLOCKER: stackmat.es page creation pattern TBD | New page at /forms/standard-process route |
| Checklist page | BLOCKER: stackmat.es page creation pattern TBD | New page at /forms/checklist route |
| CRM pattern pages | BLOCKER: exact CRM page paths in stackmat.es TBD | Rewrite existing pages |
| Meeting agenda page | BLOCKER: stackmat.es pattern page creation TBD | New page at /patterns/meetings/agenda route |
Performance
Priority Score
PRIORITY = Pain x Demand x Edge x Trend x Conversion
| Dimension | Score (1-5) | Evidence |
|---|---|---|
| Pain | 4 | Dogfood report: 10 issues (1 critical, 3 high). /forms 404. CRM pages bypass lib atoms (L:R 1:15). 3 nav locations. Marketing section dead. |
| Demand | 3 | Internal builders use forms daily. Dogfood found 3/8 pattern pages unreachable. Pattern seekers have shadcn as alternative. No external demand signal. |
| Edge | 4 | Three-mode architecture (IMPORT -> COPY -> USE) is novel. Anti-pattern docs rare in design systems. Meeting form as domain stress test unique. |
| Trend | 4 | Design systems mainstream. AI code generation increases need for machine-readable standard references. Component-driven development accelerating. |
| Conversion | 3 | Form atoms built (L:R 1.4:1). FormShell exists. TanStack integration solid. Missing: unified nav, standard process page, CRM rewrite. ~60% built. |
| Composite | 576 | 4 x 3 x 4 x 4 x 3 |
Quality Targets
| Metric | Target | Now |
|---|---|---|
| Form nav locations | 1 | 3 |
| CRM pattern L:R ratio | 1:3 | 1:15 |
| Shipping checklist exists | Yes | No |
| Standard process page exists | Yes | No |
| Meeting agenda composes from lib | Yes | N/A |
Failure Budget
| Failure Type | Budget | Response |
|---|---|---|
| New lib atom needed for DS-05 | <3 | If >3 new atoms needed, stop DS-05 and fill lib first |
| CRM rewrite breaks page URL | 0% | URLs preserved — redirects if absolutely necessary |
| Checklist item is vague | 0% | Every item must reference a specific lib atom or threshold |
Kill signal: If teams don't use meeting instrument within 30 days of ship, demote to Explorations. If MeetingAgenda requires >3 new lib atoms, the lib has fundamental gaps — stop and fill lib first.
Kill date: 2026-06-30.
Platform
Current State
| Component | Built | Wired | Working | Notes |
|---|---|---|---|---|
| Form atoms (Input, Select, Textarea, Checkbox) | Yes | Yes | Yes | L:R 1.4:1, well-composed |
| FormShell organism | Yes | Yes | Yes | Only organism in tier |
| TanStack Form integration | Yes | Yes | Yes | Documented |
| Anti-pattern documentation | Yes | Yes | Yes | Rare, valuable |
| Accessibility annotations | Yes | Yes | Yes | Thorough on form atoms |
| CRM pattern pages | Yes | Yes | Broken | Raw HTML, L:R 1:15, violates Prime Directive |
| Marketing section | Yes | No | Broken | Homepage CTA 404s |
| Advanced Form page | Yes | No | Stub | "Coming Soon" placeholder |
| Forms navigation | Partial | Partial | Broken | 3 separate locations, confusing |
~60% built. Atoms healthy. CRM patterns, navigation, and stubs need work.
Build Ratio
~50% composition (form atoms, FormShell, TanStack integration, anti-patterns — all built). ~50% new work (nav unification, standard process page, checklist, CRM rewrite, meeting form).
Protocols
Build Order
| Sprint | Features | What | Effort | Acceptance |
|---|---|---|---|---|
| S0 | DS-01, DS-02, DS-03 | Foundation: unified nav + standard process + checklist | 3d | Single sidebar entry. Standard process page. 10-point checklist. |
| S1 | DS-04 | Proof: CRM pattern rewrite | 3d | Zero raw HTML. L:R 1:3. URLs preserved. |
| S2 | DS-05 | Stress test: meeting agenda form | 2d | 5 fields from lib atoms. FormShell wraps. No local components. |
Total: ~8 days. S0 unblocks everything. S1 proves the standard. S2 stress-tests composition depth.
Commissioning
| # | Feature | Install | Test | Operational | Optimize |
|---|---|---|---|---|---|
| 1 | Forms nav unification (DS-01) | -- | -- | -- | -- |
| 2 | Standard process page (DS-02) | -- | -- | -- | -- |
| 3 | Form shipping checklist (DS-03) | -- | -- | -- | -- |
| 4 | CRM pattern rewrite (DS-04) | -- | -- | -- | -- |
| 5 | Meeting agenda form (DS-05) | -- | -- | -- | -- |
Players
Demand-Side Jobs
Job 1: Ship Forms
Situation: Engineer assigned to build a form for a new feature.
| Element | Detail |
|---|---|
| Struggling moment | Can't find THE standard. Finds 3 nav locations. Reads raw HTML patterns. Copies the wrong thing. |
| Current workaround | Inspect element on production app. Ask a teammate. Read source code. |
| What progress looks like | Open /forms, read standard process, copy the chain, check against checklist, ship. |
| Hidden objection | "I don't trust the design system page reflects what's in the lib." |
| Switch trigger | Third form built by cargo-culting, each with different patterns. |
Features that serve this job: DS-01, DS-02, DS-03
Job 2: Team Credibility
Situation: Venture evaluator visits stackmat.es to assess capability.
| Element | Detail |
|---|---|
| Struggling moment | Sees 404s, stubs, and raw HTML. Concludes the team isn't serious. |
| Current workaround | Look at GitHub repos directly. |
| What progress looks like | Working forms, composition proof, no dead ends. |
| Hidden objection | "This looks like a template." |
| Switch trigger | Second visit to a design system that has more stubs than working examples. |
Features that serve this job: DS-01, DS-04, DS-05
Job 3: Copy Patterns
Situation: External developer looking for form patterns to adopt.
| Element | Detail |
|---|---|
| Struggling moment | shadcn has individual components but no composition patterns. Needs the chain, not atoms. |
| Current workaround | shadcn/ui or v0.dev for atoms. Build composition patterns from scratch. |
| What progress looks like | Copy a complete form pattern with validation, server action, and error handling. |
| Hidden objection | "shadcn already has this." |
| Switch trigger | Built the same validation-to-server-action chain three times. |
Features that serve this job: DS-02, DS-04
Job 4: Meeting Prep
Situation: Meeting participant needs to fill in Tight Five agenda before the meeting.
| Element | Detail |
|---|---|
| Struggling moment | No structured form. Uses Google Doc or wings it. |
| Current workaround | Blank Notion page. Google Doc. Skip preparation entirely. |
| What progress looks like | Open meeting agenda form, fill 5 fields, submit. Done. |
| Hidden objection | "This is overhead. I'll wing it." |
| Switch trigger | Third meeting where nobody prepared and the hour was wasted. |
Features that serve this job: DS-05
PRD Relationships
| PRD | Relationship | Data Flow |
|---|---|---|
| Meetings | depends-on | This PRD proves the form patterns that Meetings PRD consumes. DS-05 is the bridge. |
| Prompt Deck | Complementary | Design system already showcases PromptDeck. No conflict. |
| Sales CRM | Complementary | DS-04 (CRM pattern rewrite) improves the design system showcase of CRM forms. |
Context
- PRD Index — Design System Proving Ground
- Prompt Deck — 5-card pitch
- Pictures — Pre-flight maps