documentation · v2.4 · may 2026

The canonical, AI-readable design system for every SageOx surface.

The canonical guidance for the design engineers and agents that build SageOx surfaces. Best-effort, not enforced — the lint rules, contrast checks, subagent reviewers, and CI gates around it are what turn the guidance into reliable output. Tokens, components, mockups — everything is downstream of what's written here. The studio stress-tests new ideas before they land.

3 essentials: §0 philosophy · HARNESS.md (practice) · DESIGN.md (spec)

Who you are → where to start

🎨 Design engineer

Refines the harness — tokens, lint, DESIGN.md, agent context. Also ships features end-to-end.

⚙️ Product engineer

Ships features in consuming repos. Consumes tokens + components; has commit access if the harness has a gap.

🎯 Product owner

Shapes intent, density, voice, microcopy. Ships customer-facing copy directly. (Renamed from PM.)

Persona names describe job-shape, not handoff lines. Everyone here ships production code; cross-links inside each page get you the rest.

Foundations 3

• DESIGN.mdThe system spec — tokens, semantic roles, components, anti-patterns.
• HARNESS.mdPractice — toolchain, the two loops, 30-day onboarding.
• AUTHORING.mdHow to write a mockup so it lands inside the system.

Brand 3

• storyWhat SageOx stands for and where the name comes from.
• logosWordmark, icon, mascot — sizes, clear-space, color contracts.
• guardrailsPixel-exact rules for the small set of assets agents shouldn't regenerate.

Validation 2

• CLI diffToken / DESIGN.md drift detection for product CI.
• web diffVisual regression against the canonical surface catalog.

Tokens — values agents reach for 3

• colorsSage, Silt, Crater, Dust — full scales + semantic roles.
• typographyType stack, scale, weights, line-heights, tabular numerals.
• spacing4px baseline grid, density modes, the breathing-room rules.

Inventory — what's currently named 3

• colorsWhich color tokens exist, which are gaps, which are pending.
• typographyActive type tokens with usage census across product.
• spacingSpacing token catalog and observed drift.

Usage — opinionated patterns + practice guides 11

• for design engineersRefining the harness — tokens, lint, DESIGN.md, agent context.
• for product engineersConsuming tokens + components in product code.
• for product ownersVoice, tone, density, microcopy — shaping what the product becomes.
• brand in productWhen the wordmark, icon, and mascot belong on which surface.
• UI density & confidenceWhen to compact, when to breathe, and the perception cost of each.
• lists & paginationThe full pattern: empty states, sort, filter, scale, pagination shape.
• loading & statusThree-layer motion policy + status visibility patterns.
• errors & recoveryTone, placement, severity mapping, retry semantics.
• numbered stepsThe timeline component for guided multi-step flows.
• gradient overlaysWhere gradient is purposeful and where it's chartjunk.
• light & dark themesWhat 2024–2026 research says, and how to tone a dark theme well.

conventions in this repo

• Tokens beat hex. Every color in product code is a token (--sage-500), not a hex.
• Tokens beat px. Every spacing value references the scale (var(--space-3)), not a raw pixel.
• Anti-patterns are first-class. Each section names what to avoid alongside what to do.
• Versioning is light. v2.4 today; bump and note the diff when something changes meaningfully.
• YAML wins. When this site disagrees with tokens/*.yaml, the YAML is canonical.
• §0 first. Everything else is downstream of those five rules.

Further reading & influences

moved to its own page

The "designers we follow" reading list — Maggie Appleton, Geoffrey Litt, Linus Lee, Amelia Wattenberger, Andy Matuschak, Simon Willison, Bret Victor, plus the GitHub Next team and the Tufte foundation — now lives at its own page so it's not buried in docs.

→ /inspire — who we read, watch, follow