Design System
AI OS uses a DESIGN.md dual-structure protocol that separates emotional design reasoning from exact implementation tokens. This enables brand-aware UI generation with WCAG accessibility compliance.
Dual-Structure Protocol
Every design system in AI OS has two layers:
- Reasoning Layer — The "why" behind design decisions: brand personality, emotional intent, visual metaphors, and audience targeting.
- Token Layer — The "what" of implementation: exact hex values, font sizes, spacing scales, border radii, and shadow definitions.
This separation ensures that AI agents understand the intent behind design choices, not just the values, enabling smarter generation of new UI components that feel cohesive.
Brand Reasoning
The Reasoning section of DESIGN.md captures subjective design intent:
## Reasoning
### Brand Personality
Authoritative yet approachable. Technical precision
with human warmth.
### Color Philosophy
Dark background conveys depth and focus. Blue primary
signals trust and intelligence. Green accents for
success states create positive reinforcement.
### Typography Intent
Inter for UI clarity — geometric, neutral, highly
legible at small sizes. JetBrains Mono for code —
designed for extended reading of technical content.Color Hierarchy
Colors are organized into a semantic hierarchy rather than a flat palette:
| Role | Token | Usage |
|---|---|---|
| Primary | --primary | Interactive elements, links, focus states, primary CTAs |
| Secondary | --secondary | Supporting actions, secondary buttons, less prominent UI |
| Tertiary | --tertiary | Accents, decorative elements, inline code highlighting |
| Success | --success | Positive states, confirmations, health indicators |
| Warning | --warning | Caution states, pending actions, rate limit indicators |
| Error | --error | Destructive actions, failures, validation errors |
Component Specifications
The Design System agent generates component specs with exact measurements and states:
- Buttons — Primary, secondary, ghost, danger variants with hover/active/disabled states
- Cards — Standard, elevated, interactive variants with border-glow hover effects
- Forms — Input, select, checkbox, radio with focus rings and error states
- Navigation — Top nav, sidebar, breadcrumbs, tabs
- Feedback — Toasts, modals, loading skeletons, empty states
WCAG Linting
The Design System offers automatic accessibility validation:
- Contrast ratios — All text/background pairs checked against WCAG AA (4.5:1) and AAA (7:1) thresholds
- Focus indicators — Ensures all interactive elements have visible focus states
- Color independence — Validates that color is not the sole means of conveying information
- Touch targets — Minimum 44x44px for mobile interactive elements
Brand Clone from URL
The clone feature analyzes any website URL and extracts its design DNA:
- Scrapes the target URL for CSS variables, computed styles, and font references
- Extracts the color palette with usage percentages
- Identifies typography stack and size scale
- Detects spacing patterns and border-radius conventions
- Generates a complete DESIGN.md with both reasoning and token layers
Export
The Design System agent provides export in multiple formats:
- DESIGN.md — Full Markdown specification (reasoning + tokens)
- CSS Variables — Ready-to-use custom properties
- JSON Tokens — For use with design token tools (Style Dictionary, Figma Tokens)
- Tailwind Config — Tailwind CSS theme extension
Frequently Asked Questions
What is the DESIGN.md dual-structure protocol?
Two layers in every design system: a Reasoning Layer for the why behind design decisions (brand personality, emotional intent, visual metaphors, audience targeting) and a Token Layer for the what of implementation (exact hex values, font sizes, spacing scales, border radii, and shadow definitions). This separation lets AI agents understand intent, not just values.
How are colors organized in the AI OS design system?
Into a semantic hierarchy rather than a flat palette: Primary, Secondary, Tertiary, Success, Warning, and Error, each tied to a specific usage role such as interactive elements, supporting actions, or validation errors.
Does the Design System check accessibility?
Yes. It offers automatic accessibility validation: contrast ratios checked against WCAG AA (4.5:1) and AAA (7:1), visible focus indicators on interactive elements, color-independence checks, and a minimum 44x44px touch target for mobile.
Can I clone a design system from an existing website?
Yes. The clone feature scrapes a target URL for CSS variables, computed styles, and font references, extracts the color palette with usage percentages, identifies the typography stack and size scale, detects spacing and border-radius conventions, and generates a complete DESIGN.md with both layers.
What formats can I export a design system to?
DESIGN.md as full Markdown, ready-to-use CSS Variables, JSON Tokens for tools like Style Dictionary or Figma Tokens, and a Tailwind CSS theme extension.
What component specs does the Design System agent generate?
Buttons (primary, secondary, ghost, danger variants with hover/active/disabled states), Cards, Forms, Navigation, and Feedback components such as toasts, modals, and loading skeletons, each with exact measurements and states.