Token-First Design System — Audit Layer Planned
A frontend architecture case study for ComponentIQ: why the plan started as a docs-and-AI-assistant monorepo, why the shipped v1 became a token-first design system and component library instead, and what a future automated audit layer still needs from that foundation.
Platform focus
Problem
What Needed To Change
- Engineers often do not know which component or pattern to use.
- Teams rebuild UI that already exists.
- Design-system documentation is often passive.
- PR reviews catch UI, accessibility, and token issues too late.
- New engineers need faster onboarding into component rules.
- Frontend decisions are often undocumented or repeated across PRs.
Engineering Goal
What The System Needed To Prove
ComponentIQ is being designed to help frontend teams choose reusable components, follow accessibility and design-token guardrails, and review UI decisions before opening a PR.
Audience
Who The Work Serves
Frontend engineers
Need to know which component to use and how to use it correctly.
New team members
Need fast onboarding into the design system.
Reviewers / tech leads
Need earlier visibility into UI, accessibility, and token issues.
System
System Shape
Docs App
Originally planned as the source of truth for components, usage rules, guardrails, and implementation guidance. Superseded by Storybook doubling as docs in the shipped v1.
AI Assistant App
Planned decision-support layer for recommendations, setup guidance, and pre-PR audit simulation. Not built yet.
Storybook
Visual component documentation and testing surface. Shipped, hosted, and live.
Deployment
Live hosted product surface for the implemented ComponentIQ experience, including project setup, token guidance, and component evidence.
Shared packages
UI components and design tokens, shipped as the componentiq npm package. Guardrail rules and shared types remain planned.
Architecture
Monorepo Shape
componentiq/
apps/
docs-app/ (superseded by Storybook)
ai-assistant-app/ (planned)
storybook/ (shipped)
packages/
ui/ (shipped — componentiq on npm)
tokens/ (shipped — 3-layer contract)
guardrails/ (planned)
shared-types/ (planned)
config/ (planned)- Separation of concerns between documentation, AI workflows, and visual component testing.
- Shared packages keep design tokens, components, and guardrails consistent.
- The AI app can evolve independently without making the docs app unstable.
- Storybook ended up covering both visual QA and documentation, so a separate docs app was never built for v1.
Decisions
Architecture Choices
Decision 1
Separate Docs App, AI App, and Storybook
- Reason
- Each proposed surface serves a different user need.
- Tradeoff
- More apps and deployment surfaces.
- Outcome
- Storybook absorbed the docs role for v1, so this separation was simplified rather than built as originally planned.
Decision 2
Use a monorepo
- Reason
- The planned apps need to share components, tokens, rules, and types.
- Tradeoff
- Requires stronger project structure and tooling.
- Outcome
- A clearer path toward less duplication and better consistency across surfaces.
Decision 3
Treat AI as decision support, not source of truth
- Reason
- Design-system rules should remain documented and reviewable.
- Tradeoff
- AI needs guardrails and constrained workflows.
- Outcome
- Safer AI recommendations grounded in documented rules.
Decision 4
Start with PR review simulation before GitHub automation
- Reason
- Validate rules, UX, and structured output before integrating into real PRs.
- Tradeoff
- V1 is not fully automated.
- Outcome
- Faster MVP with lower risk and clearer learning.
Workflows
Key Flows
Component Recommendation
- 1User describes UI task
- 2AI recommends component or pattern
- 3AI explains tradeoffs
- 4User follows linked docs
Setup Guidance
- 1User selects stack and options
- 2AI generates setup steps
- 3User copies implementation guidance
Pre-PR Audit Simulation
- 1User pastes UI plan or code snippet
- 2AI checks against guardrails
- 3AI returns structured review comments
Implementation
System Notes
- Components are documented and visually tested in Storybook — the Docs App role was absorbed into it rather than built separately.
- The implemented ComponentIQ product surface is deployed publicly and linked from this case study as the live deployment.
- Guardrails cover component usage, accessibility, design-token usage, and AI safety in the plan; only the token and component guardrails are enforced today.
- Storybook proves actual UI components and variants, including DashboardLayout and an Enhanced Data Table.
- Docs explain when and why to use components, and how to override tokens through ComponentIqProvider.
Product Evidence
What Shipped
The visuals should behave like receipts: first show the product surface teams would work in, then prove the system underneath it with Storybook documentation and token architecture.
Project Audit Console
Lead with the dashboard because it communicates the product promise immediately: project health, audit state, design-system status, and actions in one operational surface.
Setup Guide
Use the onboarding screenshot to show that the library is installable and teachable, not just a collection of components.
Token Contract
Close with the token documentation because it supports the brand claim: ComponentIQ starts with a versioned design contract.
Scope
V1 Scope Control
Included in V1
- Storybook (shipped)
- live ComponentIQ deployment (shipped)
- shared UI package (shipped, componentiq on npm)
- design tokens (shipped, 3-layer contract)
- component recommendation flow (planned)
- setup guidance (planned)
- pre-PR audit simulator (planned)
Intentionally deferred
These were kept out of V1 to protect learning speed and reduce integration risk.
- Docs App as a separate surface
- real GitHub PR comments
- full RAG over docs
- user accounts
- analytics dashboard
- SDUI renderer
- advanced governance workflows
Roadmap
From Support To Automation
V1 Shipped
- Token contract, default values, and CSS-variable mapping
- ComponentIqProvider runtime theming
- Component library (forms, feedback, navigation, DashboardLayout, Enhanced Data Table)
- Storybook docs
- npm package
V2 Analysis & Automation
- Scoped, read-only repository import
- Configurable rulesets (accessibility, architecture, security)
- Analysis engine, findings, and rule violations
- GitHub Actions / CI integration
- CLI
Impact
What Became Clearer
- Clarifies the product and architecture direction before deeper implementation work.
- Shows how duplicated UI could be reduced by guiding engineers toward existing components.
- Shipped a real, usable foundation — tokens, components, provider, Storybook, npm package — instead of stalling on the original multi-app plan.
- Frames how accessibility, token, and component-choice issues could be surfaced earlier than PR review, once the analysis layer exists.
- Creates a technical communication artifact that explains the decisions behind the platform, including where the plan changed.
Reflection
What I Learned
AI-assisted developer tools work best when they narrow the decision space instead of pretending to replace engineering judgment.
Constrained workflows create better outputs than a generic chatbot because the system can ask for the right inputs and return reviewable structure.
The original plan split docs, AI, and Storybook into separate apps; in practice, Storybook absorbed the docs role and the AI/audit layer turned out to depend entirely on the token and component layer being solid first — so that shipped first instead.
Next, I would build the analysis engine on top of the now-shipped token contract, add citations to every recommendation, and connect the audit simulator to real PR workflows.
Explore ComponentIQ
