OODS Foundry — Object-Oriented Design System

TL;DR

• Challenge: Traditional design systems demand ~300 lines of React per component to repeat the same behaviors—status badges, currency formatting, accessibility, brand variants.
• Approach: Trait-based composition turns those behaviors into reusable capabilities expressed in ~50 lines of YAML, enforced by a purity-first token hierarchy and automated audits.
• Results: 754/754 tests green, 49/49 accessibility checks passing, eight production-ready components in Set IV, <1ms composition time, and zero code required for 80% of objects.

Why Traditional Systems Break Down

• Repetition trap: Subscriptions and invoices repeat identical logic for status, currency, and timestamps—introducing drift and maintenance costs.
• Theme chaos: Components reference brand-level tokens directly, so every rebrand becomes a refactor.
• Context sprawl: List, detail, form, and timeline views require separate components or conditional code.
• Accessibility afterthought: Dark mode, forced colors, and keyboard support arrive late and inconsistently.

Trait-Based Composition

OODS Foundry treats UI as objects composed from traits—statusable, monetary, timestamped, lifecycle-aware—assembled through YAML definitions.

object: Subscription
version: 2.0.0
traits:
  - name: statusable
    parameters:
      states: [incomplete, trialing, active, past_due, canceled, unpaid]
  - name: timestamped
    parameters:
      recordedEvents: [created, renewed, canceled, payment_failed]
  - name: monetary
    parameters:
      currency: usd
  - name: lifecycle
    alias: SubscriptionLifecycle
    parameters:
      initialState: incomplete
      transitions:
        - from: incomplete
          to: [active, canceled]
        - from: active
          to: [past_due, canceled]

That single declaration produces TypeScript definitions, lifecycle validation, status badges, timestamp formatting, monetary display, context-specific layouts, accessibility wiring, and Storybook documentation—without writing React.

The TraitCompositor Engine

The TraitCompositor merges traits through a five-layer cascade (Foundation → Base Object → Traits → Overrides → Context) with provenance tracking for every field.

• Dependency resolution: Kahn’s algorithm sorts trait graphs in O(V + E).
• Collision logic: Stricter constraints win, enums merge, type mismatches fail fast.
• Performance: <1ms for typical compositions, ~7ms for 10 traits, 40+ fields processed per ms.
• Provenance: Every field records its source trait for debugging, docs, and safe overrides.

Token Architecture & Context System

Guardrails keep components brand-agnostic and context-aware.

┌─────────────────────────────────────┐
│  --mod-*   (runtime modifiers)      │  hover, focus, disabled
├─────────────────────────────────────┤
│  --cmp-*   (component slots)        │  what components consume
├─────────────────────────────────────┤
│  --theme-* (brand & theme layer)    │  light/dark, brand overlays
├─────────────────────────────────────┤
│  --ref-*   (reference palette)      │  OKLCH base colors
└─────────────────────────────────────┘

• Purity audits: pnpm purity:audit blocks any component referencing forbidden tokens or literals.
• Canonical regions: Ten layout regions (header, badges, meta, body, actions, sidebar, footer, timeline, attachments, comments) make automation predictable.
• Context system: List, Detail, Form, and Timeline contexts adjust spacing, typography, and affordances via CSS—no conditional React required.
• OKLCH guardrails: Relative state deltas, forced-colors mappings, and automated contrast checks guarantee WCAG 2.2 AA compliance.

Model Context Protocol (MCP) Integration

OODS Foundry exposes design system operations through MCP so agents can participate safely.

• Tools: brand.apply, a11y.scan, vrt.run, tokens.validate, purity.audit, reviewKit.create.
• Safety rails: Dry-run previews, approval gates, signed transcripts, and replayable rollbacks.
• Designer workflow: Agents propose brand changes, auditors inspect diffs, approvals apply updates with evidence bundles.

By the Numbers

• Quality: 754/754 tests passing (Vitest), 49/49 accessibility checks (WCAG 2.2 AA), 487 visual regression baselines.
• Performance: Trait composition <1ms, Storybook build 5.84s, token transform <30ms.
• MCP reliability: 25-run soak tests at 0% flake, p95 under 13ms, p99 ≈0.7s only for gated apply paths.
• Velocity: 12 sprints, Component Set IV shipped eight components, billing domain pack covers Stripe/Chargebee/Zuora.

Real-World Impact

• Development speed: Trait composition cuts object creation from 4–6 hours of React to ~15 minutes of YAML (≈95% time savings).
• Accessibility leadership: Keyboard navigation, high-contrast, and screen reader support are generated by default.
• Multi-brand agility: <html data-brand="A" data-theme="dark"> flips entire experiences without touching component code.
• Domain accelerators: SaaS billing pack delivers provider-agnostic state machines, timelines, and document handling out of the box.

Lessons Learned

• Trait composition wins: Objects stay consistent, accessible, and ready for automation.
• Token purity matters: Enforcing the four-layer hierarchy eliminated theme chaos.
• Context-first thinking: CSS-driven contexts beat variant sprawl and simplify testing.
• Tooling maturity: MCP soak tests, Chromatic allowlists, and onboarding guides were essential for reliability and adoption.

What’s Next

• Sprint 20 focus: Private review candidate, evaluation kits, release readiness audit.
• Roadmap: View engine for automatic component generation, additional domain packs (e-commerce, healthcare, analytics), AI co-pilot enhancements, multi-framework support.
• Research track: Trait extraction from legacy codebases, constraint solving for complex compositions, visual programming interface.

Resources

• Live Storybook: kneelinghorse.github.io/OODS-Foundry
• Repository: github.com/kneelinghorse/OODS-Foundry
• Technical narrative: cmos/The_Object-Oriented_Design_System-A-Technical-Narrative.md
• Getting started: docs/getting-started/ with designer/dev onboarding paths
• Backlog: cmos/missions/backlog.yaml (Sprint 20 in progress)