Open Design System Format · v0.1

Hand your design system to an agent.

A design system is more than tokens. ODSF packages the whole of it (tokens, components, behaviors, and rules) into one bundle of markdown, HTML, and CSS. An agent reads it from a task down to the exact rule that task needs, and produces UI that adheres to your system.

A profile of OKF built on design.md's token model.

OKFhow to bundle knowledge for an agent
+
design.mdhow to write down a design token
=
ODSFthe whole design system as one bundle an agent navigates

New to the pieces?

ODSF builds on two recent ideas.

The container

Open Knowledge Format

Google's open, vendor-neutral spec for the context an AI agent needs. Plain markdown files, each a typed concept, with one-rule conformance, cross-links, and progressive disclosure. No SDK, no platform. If you can read a file, you can read OKF.

The content seed

design.md

Google Labs' format for documenting a design system for coding agents: design tokens in YAML frontmatter (colors, type, spacing) with {group.name} references and human-readable rationale. It nails how to write down a token. It stops there: one file of tokens, with nowhere for components, behaviors, and rules to live, and no structure for an agent to navigate.

ODSF bundles those tokens the OKF way and makes components, patterns, behaviors, and guidelines first-class typed concepts, linked into a graph an agent navigates from a task to the rule it needs. One conformance rule keeps every bundle readable by any agent or tool.

Agents write UI well, and your UI badly.

They don't know your color roles, your spacing scale, your "never convey meaning with color alone" rule, so they invent plausible-but-wrong defaults. The fix is to hand them the system as context they can load.

From a task to the exact rule

Every piece (a token, a component, a behavior, a do/don't) is a typed concept in a linked graph. An agent walks from "build a sign-up form" to the patterns, components, and rules that task needs, and reads only those.

Two projections, one truth

Every token lives once and appears twice: as agent-readable frontmatter and as a runnable CSS variable. The description and the code come from one source, so they never drift apart.

One rule, no platform

A bundle is conformant if every concept declares a type and the bundle states its version. That single contract lets any agent or tool read any bundle the same way, with no SDK and no lock-in.

Just files. Three kinds.

A bundle is a directory you commit next to your product. Open it in a browser, diff it in a PR, point an agent at it.

  • .md Concepts: the knowledge, each with a requiredtype. This is what makes a bundle conformant.
  • .html Examples: self-rendering, so an agent sees the exact markup, classes, and states to reproduce.
  • .css Tokens: the same values as runnable CSS variables, in sync with the frontmatter.
// a conformant ODSF concept
---
type: Component
title: Button
tokens:
  button-primary:
    background: "{colors.primary}"
    color: "{colors.on-primary}"
---

# Examples
- button.example.html (every variant, live)

See a real design system as a bundle.

Three well-known systems, each cloned into a conformant ODSF bundle and rendered live in the single-file viewer. Browse the tokens, the components, and the do/don'ts, then flip light/dark.

The viewer is one HTML file with no dependencies. It reads any ODSF bundle's index.md and renders it.

Bundle your design system. Hand it to the agent.