Open Design System Format (ODSF)

ODSF packages a design system as a self-contained bundle an AI agent can read, navigate, and apply to a task, with no SDK, no platform, and no lock-in. It is a strict profile of Open Knowledge Format v0.2: everything OKF says about bundles, concepts, frontmatter, links, index.md, log.md, and versioning holds unchanged, including the v0.2 provenance and trust layer (sources, generated, verified, status, stale_after, and the actor convention). A design system is exactly the kind of knowledge that layer was added for, since "is this token still the brand's" and "has a human signed off on this component spec" are the questions an agent building UI from a bundle most needs answered. On top of that container ODSF adds three things: a token model (machine-readable design tokens, design.md's seed), companion HTML/CSS assets so a concept ships a concrete self-rendering example, and a design type vocabulary so foundations, components, patterns, behaviors, and guidelines are first-class. The goal is a bundle you hand to an agent ("build this screen, adhere to this design system") that produces work that looks and behaves the way the system intends.

Use this skill two ways. Run a command on demand, or apply it implicitly whenever you shape design knowledge an agent will build from. The normative spec lives in spec.md; per-command steps in commands.md; copy-paste starting points in templates.md.

The two rules

A bundle is a conformant ODSF bundle when both hold: it is a conformant OKF bundle (every non-reserved .md concept opens with YAML frontmatter carrying a non-empty type), and the bundle-root index.md declares odsf_version in its frontmatter. That is the whole hard requirement: be a valid OKF bundle, and say you are an ODSF one. Everything else (the token model, the asset conventions, the type vocabulary, the body sections) is recommended structure a producer SHOULD follow and a consumer MUST tolerate the absence of. An OKF-only consumer reads an ODSF bundle and loses only the design niceties. Full conformance and the consumer contract are in spec.md.

Commands

Invoke as /odsf <command> [target]. Each is detailed in commands.md.

Implicit mode

Apply ODSF without being asked whenever design-system knowledge is being shaped for an agent to build from later:

• You are documenting a foundation (a color, typography, spacing, elevation, shape, or motion scale), a component, a pattern, a behavior, or a guideline an agent will reproduce. Write it as a concept with a design type, not loose prose, and ship its example asset.
• You are defining design tokens. Carry them as frontmatter tokens on the foundation that owns them and project them to styles/tokens.css, so the description and the runnable values never diverge.
• You are exporting or transforming a design system, a token set, or a component library for an agent. Emit a bundle, not a JSON blob or a screenshot.
• You are editing an existing ODSF bundle (a new variant, a retuned token, a deprecated state). Keep it conformant as you go, and follow the edit ripple checklist in commands.md: a token change reaches the foundation, tokens.css, the component's tokens, components.css, the example asset, the # Variants & States table, every touched concept's generated, and log.md (the indexes and links only if the set of concepts or relationships changed). This is where bundles silently rot if you skip a step. A retuned token also invalidates any verified event on the concepts it touched, so drop those rather than letting an old sign-off vouch for a new value.

Guard. ODSF is for a design system an agent builds from, not human-only design prose. A brand deck, a Figma board, or a marketing page for people is not a bundle. When it is unclear whether an artifact is agent-facing, ask before converting it. Knowledge that is not design-specific (a data table, a runbook, an API) is plain OKF, not ODSF.

Concepts and assets at a glance

An ODSF bundle holds exactly three file kinds. A concept's identity is its path minus .md, so components/button.md is the concept components/button.

• Concept (.md, carries frontmatter, REQUIRED type). A unit of design knowledge. type is descriptive and open; the conventional values are the foundations (Color, Typography, Spacing, Elevation, Shape, Motion, Layout), the building blocks (Component, Pattern, Behavior, Guideline, Accessibility, Voice), and the containers (Design System, Reference). Recommended frontmatter beyond OKF's: tokens (§4), examples (asset paths), and applies_to. status is now an OKF v0.2 key (draft/stable/deprecated); ODSF keeps experimental as an extension for a component that is shipped but whose API may still move, and an OKF-only consumer tolerates it as an unknown value. Prefer OKF's three when portability matters, and use stale_after rather than a permanent experimental to say the thing needs re-checking.
• Asset (.html, .css, no frontmatter). A concrete artifact a concept points at. A <concept>.example.html is the canonical correct usage; <concept>.do.html / <concept>.dont.html are a contrastive pair; styles/tokens.css and styles/components.css are the shared stylesheets. Assets are not concepts and are exempt from the type rule; they exist to be referenced. A bundle SHOULD contain no file types other than .md, .html, and .css.
• Reserved (index.md, log.md). Keep their OKF meaning at every level. Only the bundle-root index.md carries frontmatter, solely to declare the versions.

The token model

Tokens live once and appear twice, so the agent and the code it writes consume the same values:

• Frontmatter tokens on the foundation concept that owns them is the canonical, agent-readable definition. It is a map of groups (colors, spacing, typography, radius, motion, …) to named values; a value may be a string or a small map for composite tokens. A component references foundation tokens with the {group.name} syntax rather than restating values, and expresses interactive states as separate suffixed entries (button-primary, button-primary-hover).
• styles/tokens.css is the mechanical projection of the foundation tokens as CSS custom properties: token path a.b.c → --a-b-c, each as its resolved literal value, under :root. A component token does not project to a custom property; it becomes a rule in styles/components.css that consumes the foundation property with var(--…) (.btn--primary { background: var(--colors-primary); }). A {group.name} reference never appears verbatim in CSS. Keep the projections in sync (/odsf token); the frontmatter is the source of truth. Example assets share one class-naming convention (BEM by default) so a consumer can copy across components coherently.

This is ODSF's core "more": design.md stopped at frontmatter tokens; ODSF also ships the runnable CSS and the example that links it, so describing the system and using it never diverge.

Validate

Run the bundled checker against a bundle directory:

sh
node odsf-validate.mjs path/to/bundle            # tolerant: errors only on the hard rules
node odsf-validate.mjs path/to/bundle --strict   # producer gate, on a v0.2 container

It errors (exit 1) only on the hard requirements (a concept missing frontmatter or a non-empty type, or a root index.md that does not declare odsf_version) and warns, without failing, on the soft guidance a permissive consumer tolerates: a missing okf_version, a referenced example asset that is absent, an unresolved {group.name} token reference, a broken cross-link, a non-ISO log.md date, an identity outside the actor convention, or a file that is not .md/.html/.css. --strict additionally fails on the inherited OKF v0.2 producer findings (a leftover timestamp or # Citations, a sources entry with no resource, a generated with no by, an out-of-range status), but only once the root declares okf_version: "0.2", so a bundle still on the v0.1 container validates clean. The reviewer's checklist behind the script is in commands.md.

Files in this skill

• spec.md. The full ODSF v0.2 normative reference (conformance, the token model, the type vocabulary, assets, body conventions, the status reconciliation with OKF v0.2, versioning, changes from v0.1, non-goals).
• commands.md. Each command end to end, with the files it touches and the validate checklist.
• templates.md. Concept shells per type (foundation, component, pattern, behavior, guideline, reference), root and sub index.md, log.md, plus the self-rendering example and tokens.css asset templates.
• odsf-validate.mjs. The zero-dependency conformance checker.

Source

ODSF is published at saschb2b/Open-Design-System-Format (spec, philosophy, templates, a zero-dependency validator, a single-file viewer, and three browsable example bundles cloning Claude, GitHub Primer, and Vercel Geist). It builds on Google Cloud's Open Knowledge Format (the container) and Google Labs' design.md (the token model). ODSF v0.2 tracks OKF v0.2, so the two numbers stay aligned; ODSF's own additions did not change in this revision, and everything that moved moved because the container underneath it did. It remains an early, intentionally minimal standard designed for backward-compatible growth, so re-check the spec for fields added after this snapshot.