Open Design System Format: Hand Your Design System to an Agent

Ask a coding agent for a settings page and you get a settings page. It will be clean, it will be plausible, and it will be subtly not yours. The primary is a slightly different blue. The card padding lands a few pixels off your scale. The empty state ignores the pattern your team standardized on last quarter. The agent is good at UI. It is bad at your UI, because nobody ever told it what yours is.¹

The knowledge it is missing exists. It lives in a Figma library, a component repo, a Storybook, a page of brand guidelines, and a handful of decisions that were only ever said out loud. None of it is in a form the agent can load while it works. So every session it reverse-engineers or guesses, and ships plausible-but-wrong defaults.

The Open Design System Format (ODSF) is a way to hand the agent the answer instead.

The usual fixes each fall short in a specific way.

Point the agent at your component library and it reverse-engineers the system from the implementation, inconsistently, picking up the accidents along with the intent. Hand it screenshots and it sees pixels with no semantics: it cannot tell a primary action from a destructive one, or a token from a one-off. Give it a single design-token file and you have covered colors and spacing but not the components, patterns, behaviors, and do/don't rules that decide whether the output is actually right. Wire up a server that streams your design data and you have bought a platform, a dependency, and a thing to keep running, for what is fundamentally a pile of facts.

What an agent needs is the design knowledge itself, in a form it can read directly, navigate by relevance, and copy from. Files, not a service.

ODSF packages a design system as a self-contained bundle: a directory of markdown, HTML, and CSS, kept in version control, that an agent can read, navigate, and apply to a task with no SDK, no platform, and no lock-in.¹

It does not invent a new container for that. ODSF is a strict profile of Google's Open Knowledge Format (OKF), the vendor-neutral spec for agent-readable knowledge: a bundle of markdown concepts, one required field each, a permissive consumer contract, links as the graph.² Everything OKF says about bundles, concepts, frontmatter, links, indexes, and versioning holds in ODSF unchanged. On top of that container it borrows the token model from Google Labs' design.md,³ then adds the rest of a design system: components, patterns, behaviors, and guidelines as first-class typed concepts, plus runnable example assets.

A bundle has a predictable shape, organized by design domain:

text
design-system/
  index.md           bundle root; declares odsf_version
  overview.md        type: Design System
  foundations/       color, typography, spacing, elevation, shape, motion
  components/        button.md  button.example.html
  patterns/          form.md  form.example.html
  behaviors/         focus-visible.md
  guidelines/        color-not-alone.md  color-not-alone.dont.html
  styles/            tokens.css  components.css
  references/        design-md.md  (external sources, mirrored)

Those folders are a convention, not a requirement. The real structure is the links between concepts, which cross the hierarchy freely.

Conformance is deliberately tiny. A bundle is a valid ODSF bundle when two things hold: it is a valid OKF bundle (every concept file opens with YAML frontmatter carrying a non-empty type), and its root index.md declares an odsf_version. That is the whole hard requirement. The token model, the asset conventions, the type vocabulary, the body sections: all of it is recommended structure a producer should follow and a consumer must tolerate the absence of.

A useful consequence falls out of rule one. Because rule one is OKF conformance, any existing OKF bundle is a single odsf_version line away from being an ODSF bundle. Adopting the format is one edit plus optional enrichment, not a rebuild. And an OKF-only tool, a generic agent or a graph viewer, reads an ODSF bundle unchanged and loses only the design-specific niceties.

The core of ODSF's "more" over a plain token file is that a token is written down once and shows up in two synchronized projections, so describing the system and using it never drift apart.

The canonical definition lives in the frontmatter of the foundation concept that owns it:

foundations/color.md
tokens:
  colors:
    primary: "#3b5bdb"
    on-primary: "#ffffff"

That projects mechanically to a stylesheet the agent (and the code it writes) can consume directly. Each token path becomes a CSS custom property, joined by hyphens:

css
/* styles/tokens.css */
:root {
  --colors-primary: #3b5bdb;
  --colors-on-primary: #ffffff;
}

A component never restates a value. It references a foundation token with design.md's {group.name} syntax, and expresses interactive states as separate suffixed entries:

components/button.md
tokens:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
  button-primary-hover:
    backgroundColor: "{colors.primary-strong}"

Foundation tokens become custom properties; a component reference becomes a rule in styles/components.css that consumes them with var(...), never a hard-coded value:

css
/* styles/components.css */
.btn--primary {
  background: var(--colors-primary);
  color: var(--colors-on-primary);
}

The frontmatter is the source of truth and the CSS is its projection. Change the token, and every example that links the stylesheet re-renders to match. The description and the runnable values cannot diverge, because there is only one of them.

A design system written as prose tells an agent what to do. ODSF also shows it, because an agent copies a correct example far more reliably than it follows a paragraph.

Every concept can ship a companion asset: a button.example.html that is a complete, standalone document rendering the one thing the concept teaches, linking the bundle's own tokens.css and components.css so it stays truthful automatically. Guidelines and components can ship a contrastive pair, color-not-alone.do.html next to color-not-alone.dont.html, so the agent sees both the intended result and the exact mistake to avoid. The body explains why the don't is wrong; the asset shows what it looks like.

A consistent do-and-don't section, with the assets linked, is the single highest-value convention for steering an agent away from plausible-but-wrong output. It is the part design.md left implicit that ODSF makes concrete.

Concepts are typed, and the type is what lets an agent route. Foundations (Color, Typography, Spacing, Elevation, Shape, Motion, Layout) carry the design language. Building blocks and rules (Component, Pattern, Behavior, Guideline, Accessibility, Voice) carry everything built on top. Like OKF, the vocabulary is descriptive and open: pick the most specific type that fits, invent one when none does, and a reader tolerates values it has never seen.

Concepts link to each other with ordinary markdown links, and the prose around the link names the relationship: a component points at the foundations whose tokens it uses and the behaviors that govern its interaction; a pattern points at the components it composes; anything points at the guidelines and accessibility rules that constrain it. The result is a graph an agent walks from a task ("build a sign-up form") to exactly the patterns, components, tokens, behaviors, and rules that task needs, without reading the whole bundle. That is OKF's progressive disclosure, specialized to design.

A format is a claim until something ships in it. ODSF comes with three browsable example bundles, each cloning a real design system, chosen to stress different corners of the spec: Anthropic's Claude, a fixed warm brand voice; GitHub's Primer, a theme-able system with light and dark modes; and Vercel's Geist, a monochrome-first library spanning dozens of components.¹ A locked brand, a multi-mode component set, and a comprehensive system all fit the same bundle shape, which was the point of building all three.

The repository ships the working parts alongside the prose: the normative spec, a philosophy doc, copy-paste templates for every concept type, a zero-dependency validator that fails only on the two hard rules and warns on the soft guidance, and a single-file HTML viewer that renders any bundle in the browser. No build step, no account, no service.

Reading a spec is one thing. Getting an agent to produce a conformant bundle, and keep it conformant as tokens get retuned and variants get added, is another. So I packaged the whole workflow as an agent skill.

The odsf skill teaches an agent to author, validate, and maintain ODSF bundles. It exposes the commands the format implies (init, add, token, asset, edit, enrich, link, index, log, validate, export, migrate, consume) and, just as usefully, runs implicitly: ask it to document a color scale, spec a component, or turn a Figma export into something an agent can build from, and it ships the result as a conformant bundle with a runnable example instead of loose prose. It carries the spec, the templates, and the validator, and it follows a ripple checklist on every edit, so a single token change reaches the foundation, tokens.css, the component, components.css, the example asset, the variants table, the timestamps, and the log, with none skipped. That last part is where bundles quietly rot, and it is exactly the bookkeeping an agent is better at than a person.

It runs in any agent that speaks the skills.sh format (Claude Code, Cursor, Codex, Cline, Windsurf, OpenCode). Install it on its own:

bash
npx skills@latest add saschb2b/skills --skill odsf

The full breakdown is on the odsf skill page.

The agent you wire your design system into this year may not be the one you reach for next year. ODSF's wager, inherited from OKF, is that a design system written as plain, linked, versioned files outlives the tool you wrote it for. Markdown has already outlived a dozen editors. Your color roles, your spacing scale, and the rules your team argued its way to deserve the same shelf life, and they should be just as readable by the next agent as by the current one.

If a coding agent keeps shipping plausible-but-wrong versions of your interface, the fix is not a better prompt. It is giving the agent your design system in a form it can actually read. Write each piece down once, give it a type, ship its example, and commit it.

• Open Design System Format

  The spec, a philosophy doc, copy-paste templates, a zero-dependency validator, a single-file viewer, and three example bundles cloning Claude, Primer, and Geist.

• ODSF landing page

  The short pitch: hand your design system to an agent, with the bundle shape and token model at a glance.

• Open Knowledge Format v0.1 specification

  The container ODSF profiles: bundles, concepts, the one-field conformance rule, the permissive consumer contract, and versioning.

• design.md (Google Labs)

  The token model ODSF builds on: frontmatter design tokens, the {group.name} reference syntax, and variant and state entries.