◇ Open Values Standardfor builders

Spec / open-values-design-tokens

Open Values Design Tokens v0.1

The colours, type sizes, spacing, motion rules and small drawings that give an Open Values site its look, grouped into one profile per site. Designers edit it by hand, and a build script turns it into the design token index and the custom properties in the app stylesheet.

Draft. It may still change before it is called stable. A file someone writes by hand or with a tool, and keeps.

Who writes it and who reads it

No writer is listed. Read by future app skin loader, design token audit, standard documentation, Kosplora/Socrates instance skins.

Fields

FieldWhat it meansType
format requiredNames the file format. Always open-values-design-tokens.always "open-values-design-tokens"
version requiredThe version of this format the file follows. Currently 0.1.0.string
standard requiredThe standard this file belongs to. Always open-values-standard.always "open-values-standard"
updated requiredThe date the tokens were last changed, as YYYY-MM-DD.see date
purpose requiredA sentence saying what the token set is for.see nonEmptyString
principles requiredShort design rules every profile in the file follows, such as that contrast is computed rather than asserted.list
referencesOutside documents the tokens rely on, such as the WCAG contrast rules.list
valueBloom requiredColours and rules for the value bloom, the small flower drawing that shows how one option scores on each of the eight value themes.see valueBloom
cssVariableMapping requiredA review table that says which CSS custom property in the app each design token should set.see cssVariableMapping
contrastRemediationContractA checklist of known colour contrast failures in the app's stylesheet and how the app should fix each one. The tokens file supplies the colours and warnings; the fix itself is made in app/styles.css.see contrastRemediationContract
profiles requiredThe skins in this file, one per site or look, each with a full set of tokens.list

A reader MUST ignore fields it does not know, so a file can carry more than this list and still be read. A writer MUST NOT change what a listed field means.

A file that passes

A source design-token profile has semantic colors, motion, contrast pairs, component contracts, and art tokens.

{
  "format": "open-values-design-tokens",
  "version": "0.1.0",
  "standard": "open-values-standard",
  "updated": "2026-07-08",
  "purpose": "Fixture design tokens.",
  "principles": [
    "contrast is computed"
  ],
  "references": [
    {
      "label": "WCAG contrast",
      "url": "https://www.w3.org/TR/WCAG22/#contrast-minimum",
      "asof": "2026"
    }
  ],
  "valueBloom": {
    "status": "h4-token-substrate",
    "consumer": "App H4 fixture consumer",
    "sourceFunction": "CC.engine.signature(entity, key2theme)",
    "minimumThemesForBloom": 2,
    "scoreScale": "0..100 mean score per carried theme; omitted themes stay absent",
    "order": [
      "planet",
      "people",
      "health",
      "honesty",
      "privacy",
      "animals",
      "cost",
      "local"
    ],
    "themes": [
      {
        "id": "planet",
        "label": "Planet",
        "universal": "planet",
        "petalColor": "#3F8F5E",
        "centerColor": "#2F6F4E",
        "role": "environment"
      },
      {
        "id": "people",
        "label": "People",
        "universal": "people",
        "petalColor": "#C07A53",
        "centerColor": "#8F4F31",
        "role": "labor"
      },
      {
        "id": "health",
        "label": "Health",
        "universal": "wellbeing",
        "petalColor": "#C86D6A",
        "centerColor": "#884640",
        "role": "wellbeing"
      },
      {
        "id": "honesty",
        "label": "Honesty",
        "universal": "openness",
        "petalColor": "#C2A049",
        "centerColor": "#7C621F",
        "role": "transparency"
      },
      {
        "id": "privacy",
        "label": "Privacy",
        "universal": "autonomy",
        "petalColor": "#4F8FA9",
        "centerColor": "#2D6075",
        "role": "data control"
      },
      {
        "id": "animals",
        "label": "Animals",
        "universal": "animals",
        "petalColor": "#8A7FB5",
        "centerColor": "#5E5484",
        "role": "animal welfare"
      },
      {
        "id": "cost",
        "label": "Cost",
        "universal": "access",
        "petalColor": "#6FA07A",
        "centerColor": "#477451",
        "role": "affordability"
      },
      {
        "id": "local",
        "label": "Local",
        "universal": "community",
        "petalColor": "#B0894F",
        "centerColor": "#73582D",
        "role": "community"
      }
    ],
    "signatureVector": {
      "status": "optional-materialization-contract",
      "field": "valueSignature",
      "order": [
        "planet",
        "people",
        "health",
        "honesty",
        "privacy",
        "animals",
        "cost",
        "local"
      ],
      "shape": "object keyed by carried theme id",
      "omitMissing": true,
      "mustNot": [
        "Do not store absent themes as 0.",
        "Do not draw a bloom below the theme floor.",
        "Do not use the bloom as evidence."
      ]
    }
  },
  "profiles": [
    {
      "id": "sample-skin",
      "label": "Sample Skin",
      "role": "fixture-skin",
      "status": "format-seed",
      "summary": "Fixture profile for conformance.",
      "tokens": {
        "color": {
          "background": {
            "value": "#FFFFFF",
            "role": "background"
          },
          "surface": {
            "value": "#F7F7F7",
            "role": "surface"
          },
          "text": {
            "value": "#111111",
            "role": "text"
          },
          "mutedText": {
            "value": "#555555",
            "role": "muted text"
          },
          "border": {
            "value": "#CCCCCC",
            "role": "border"
          },
          "accent": {
            "value": "#255E46",
            "role": "accent"
          },
          "accentText": {
            "value": "#FFFFFF",
            "role": "accent text"
          },
          "focus": {
            "value": "#7A4A12",
            "role": "focus"
          },
          "link": {
            "value": "#205C8A
…

A file that must be rejected

Source contrast pairs must meet their declared minimum when computed from token colors.

{
  "format": "open-values-design-tokens",
  "version": "0.1.0",
  "standard": "open-values-standard",
  "updated": "2026-07-08",
  "purpose": "Fixture design tokens.",
  "principles": [
    "contrast is computed"
  ],
  "references": [
    {
      "label": "WCAG contrast",
      "url": "https://www.w3.org/TR/WCAG22/#contrast-minimum",
      "asof": "2026"
    }
  ],
  "profiles": [
    {
      "id": "sample-skin",
      "label": "Sample Skin",
      "role": "fixture-skin",
      "status": "format-seed",
      "summary": "Fixture profile for conformance.",
      "tokens": {
        "color": {
          "background": {
            "value": "#888888",
            "role": "background"
          },
          "surface": {
            "value": "#F7F7F7",
            "role": "surface"
          },
          "text": {
            "value": "#777777",
            "role": "text"
          },
          "mutedText": {
            "value": "#555555",
            "role": "muted text"
          },
          "border": {
            "value": "#CCCCCC",
            "role": "border"
          },
          "accent": {
            "value": "#255E46",
            "role": "accent"
          },
          "accentText": {
            "value": "#FFFFFF",
            "role": "accent text"
          },
          "focus": {
            "value": "#7A4A12",
            "role": "focus"
          },
          "link": {
            "value": "#205C8A",
            "role": "link"
          },
          "success": {
            "value": "#2E6F3E",
            "role": "success"
          },
          "warning": {
            "value": "#7A5411",
            "role": "warning"
          },
          "danger": {
            "value": "#7B3530",
            "role": "danger"
          }
        },
        "typography": {
          "body": {
            "family": "system-ui, sans-serif",
            "size": "1rem",
            "lineHeight": 1.5
          }
        },
        "space": {
          "sm": "0.5rem"
        },
        "radius": {
          "control": "0.375rem"
        },
        "motion": {
          "durationFast": 100,
          "durationBase": 200,
          "durationSlow": 400,
          "easing": "ease-out",
          "reducedMotion": "opacity-or-instant",
          "maxMovingElements": 4,
          "mustNot": [
            "Do not loop decorative motion."
          ]
        }
      },
      "contrastPairs": [
        {
          "id": "body-on-background",
          "fg": "text",
          "bg": "background",
          "purpose": "normal-text",
          "minimum": 4.5
        }
      ],
      "componentContracts": [
        {
          "id": "fixture-card",
          "tokens": [
            "surface",
            "text"
          ],
          "mustExpress": [
            "identity"
          ],
          "mustNot": [
            "hide provenance"
          ]
        }
      ],
      "artTokens": [
        {
          "id": "fixture-line",
          "kind": "svg-line",
          "viewBox": "0 0 32 16",
          "stroke": "accent",
          "fill": "none",
          "path": "M2 12 C8 4 20 4 30 12",
          "usage": "fixture divider"
        }
      ]
    }
  ]
}

The schema

Its address is https://openvaluesstandard.org/schema/design-tokens-v0.1.schema.json. Validators can fetch it there; the file is also in the repository at app/data/standard/schemas/design-tokens.schema.json.

The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY are used as described in RFC 2119 and RFC 8174 when, and only when, they appear in capitals.

Whether this format fits your app is your call. The spec says what a file MUST hold. Which formats you read and write, and what your app does with them, is yours to decide.