rafters

Rafters: Design Intelligence Protocol for AI Agents

Your designer encodes their taste. We turn it into data structures. AI agents build interfaces that don't suck.

The Real Problem: AI Agents Guess at Design

AI agents don't have taste. They guess at colors, spacing, hierarchy, and balance because design systems give them dumb data—hex codes, pixel values, component names—without the reasoning behind design decisions.

Designers and developers look at designs and apply taste. AI agents need data that simulates taste.

The Rafters Solution: Three Registries of Design Intelligence

Rafters eliminates guessing by converting every subjective design decision into objective, queryable data across three interconnected registries:

1. Token Registry - What design values exist and why

Every token contains mathematical, perceptual, and accessibility intelligence:

• OKLCH color scales: Perceptually uniform 50-950 shades with pre-computed WCAG AAA contrast pairs (O(1) lookup)
• Musical spacing progressions: Major-third (1.25) or golden ratio harmonics—not arbitrary pixel values
• Dependency rules: 5 rule types (calc, state, scale, contrast, invert) that auto-regenerate 240+ tokens when base values change
• Perceptual metadata: Atmospheric role (foreground/background), perceptual weight (0-1), harmonic tension

2. Component Registry - What UI patterns exist and when to use them

Every component contains cognitive and usage intelligence:

• Cognitive load ratings: Button (3 points), Card (5 points), Dialog (6 points)—enforced 15-point budget per screen
• Semantic meaning: "Primary actions demand attention—maximum 1 per section"
• Accessibility requirements: WCAG AAA compliance, 44px touch targets, focus management
• Design rationale: "Primary uses foreground-advancing colors for immediate attention. Secondary uses receding colors to support without competing."

3. Designer Decisions Archive - Why choices were made

Every override and decision gets documented:

• Color choices: "Blue at 240° chosen for trust in financial context, optimal chroma at L=0.40-0.60"
• Spacing rationale: "Major-third ratio creates natural visual rhythm, less aggressive than perfect-fourth"
• Cognitive budgets: "User testing showed >15 interactive elements causes decision fatigue"

How AI Agents Use This (Zero Guessing)

Agent task: "Create a signup form"

Query flow:

1. registry.getCognitiveLoadBudget() → 15 tokens
2. componentRegistry.query({type: "form"}) → Form (5) + Input (2 each) + Button (3) = 16 total → OVER BUDGET
3. registry.optimizeForBudget() → Reduce to 3 inputs = 14 total ✓
4. tokenRegistry.query({accessibleOn: "surface-50", wcagLevel: "AAA"}) → Returns ["neutral-400"] with pre-computed 7.2:1 contrast
5. tokenRegistry.getProgression("spacing", "major-third") → [4,5,6,8,10,13,16,20,25,32] mathematical harmony

Result: Accessible form with harmonious spacing, under cognitive budget—backed by designer's encoded taste, not guesses.

How It Works

1. Mathematical Foundation

Everything starts with math. Not because we're nerds (though we are), but because mathematics is the only universal language both humans and machines understand perfectly.

• Color Science: OKLCH perceptual color model with 10-step scales following musical ratios
• Spacing Systems: Golden ratio progressions (8, 13, 21, 34, 55, 89px)
• Typography Scales: Perfect fourth (1.333) and augmented fourth (1.414) ratios
• Grid Systems: 12/16/24 column layouts with mathematical relationships

Default grayscale. Zero opinions. Pure math.

2. Design Intelligence Encoding

Here's where it gets interesting. Every UI component includes embedded metadata that captures human reasoning:

/**
 * @cognitive-load 3/10 - Simple action trigger with clear visual hierarchy
 * @attention-economics Primary variant commands highest attention - use sparingly
 * @trust-building Destructive actions require confirmation patterns
 * @accessibility WCAG AAA compliant with 44px minimum touch targets
 */

Cognitive Load Budget: Every page gets 15 points max. A Container costs 0 points (invisible structure), a Button costs 3 points (simple action), a Dialog costs 6 points (interrupts flow). AI agents calculate total load before adding components.

Attention Economics: Components declare their attention cost. Primary buttons demand focus—maximum one per section. Secondary buttons support. Ghost buttons recede. AI agents understand visual hierarchy through data.

Trust Patterns: Critical actions need trust signals. Payment forms require security badges. Destructive actions need confirmation. Data collection needs transparency. Encoded directly into component metadata.