CSS-first design tokens

Tokens should start where they run.

cssmark uses browser-native @property rules as the source of truth for design tokens, then generates JSON, CSS, documentation, validation, and diffs from the same files.

View example docs Install cssmark

@property --color-primary {
  syntax: "<color>";
  inherits: false;
  initial-value: #0055ff;
  description: "Primary brand color";
  category: "color.brand";
}

No translation layer

Author real CSS with syntax, inheritance, initial values, and metadata together.

Authoring, not interchange

The official Design Tokens report defines exchange formats. cssmark is for CSS-first source-of-truth workflows.

Generated proof

The example site shows the source stylesheet, generated previews, modes, references, and docs output side by side.

Authoring API

Write tokens as CSS, add metadata as descriptors.

cssmark reads normal @property blocks and a small set of extended descriptors. Browsers ignore the extra fields; cssmark uses them for docs, JSON, validation, diffs, and mode output.

syntax, inherits, and initial-value stay browser-native.
description, category, type, aliases, and examples enrich generated docs.
mode-* descriptors generate themed CSS selectors like :root[data-color-mode="dark"].

@property --color-bg {
  syntax: "<color>";
  inherits: false;
  initial-value: #ffffff;
  mode-dark: #1a1a2e;
  description: "Default page background.";
  category: "color.background";
  type: "color";
  examples: "background: var(--color-bg);";
}

Workflow

1. Author

Write tokens as @property blocks in CSS files. Split primitive and semantic tokens across files if that matches your system.

2. Validate

Run cssmark validate tokens.css in CI to catch missing required descriptors and duplicate token names.

3. Generate

Use cssmark css for runtime variables, cssmark build for JSON, and cssmark docs for reference docs.

4. Review changes

Use cssmark diff old.json new.json to explain token changes in pull requests and releases.

Descriptor reference

Descriptor	Purpose
`syntax`	Browser-native value grammar such as `<color>`, `<length>`, or `*`.
`inherits`	Browser-native inheritance behavior for the registered custom property.
`initial-value`	The default token value. Supports `var()` references and fallbacks.
`description`	Human-readable docs text for generated reference pages.
`category`	Dot-separated grouping such as `color.brand` or `spacing`.
`type`	Semantic hint used for previews, for example `color` or `shadow`.
`aliases`	Comma-separated related names shown in docs.
`examples`	Semicolon-separated usage snippets shown on token cards.
`mode-*`	Mode-specific value, emitted as a selector like `:root[data-color-mode='dark']`.