◇ Open Values Standardfor builders

Spec / open-values-design-token-index

Open Values Design Token Index v0.1

A generated copy of the design tokens with CSS custom properties, computed colour contrast results, and counts of how many catalogue options can be drawn as a value bloom. A build script makes it from content/design/tokens.json, at the same time writing the token values into the app stylesheet, and the design audit reads it.

Draft. It may still change before it is called stable. A file a build step makes from other files. Change the sources, not this file.

Who writes it and who reads it

Written by pipeline/build_design_tokens.js. Read by future app skin loader, audit:design-tokens, preview QA.

Fields

FieldWhat it meansType
format requiredNames the file format. Always open-values-design-token-index.always "open-values-design-token-index"
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"
built requiredThe date of the index, as YYYY-MM-DD, copied from the updated date of the tokens file.see date
purpose requiredA sentence saying what the index is for.see nonEmptyString
generatedFrom requiredThe tokens file the index was built from, with its date and hash, so a stale index can be detected.object
principles requiredThe design rules from the tokens file, copied unchanged.list
referencesThe outside documents from the tokens file, copied unchanged.list
valueBloom requiredThe value bloom section from the tokens file, plus how many catalogue options can be drawn as a bloom and three example options to preview it with.see valueBloom
valueSignatureCoverage requiredThe same counts as valueBloom.signatureCoverage: how many catalogue options have theme scores and stored signatures.see valueSignatureCoverage
cssVariableMapping requiredThe token to CSS custom property table from the tokens file, copied unchanged.see cssVariableMapping
contrastRemediationContractThe contrast fix checklist from the tokens file, copied unchanged.see contrastRemediationContract
skinReadiness requiredWhether the data the app needs for each part of the skin (palette, day cycle, motion, value bloom, materiality) is in place. Ready here means the data exists, not that the app has been checked visually.see skinReadiness
counts requiredTotals across the whole index.see counts
filters requiredSorted lists of the ids that appear in the index, for building filters and checks.object
profiles requiredEvery profile from the tokens file, flattened for the app, with the CSS custom properties it produces and its computed contrast results.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 generated design-token index summarizes computed contrast, counts, filters, contracts, and art tokens.

{
  "format": "open-values-design-token-index",
  "version": "0.1.0",
  "standard": "open-values-standard",
  "built": "2026-07-08",
  "purpose": "Fixture generated design-token index.",
  "generatedFrom": {
    "path": "content/design/tokens.json",
    "updated": "2026-07-08",
    "sha256": "abcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcd"
  },
  "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."
      ]
    },
    "signatureCoverage": {
      "categories": 3,
      "entries": 3,
      "scoredEntries": 3,
      "signedEntries": 3,
      "drawableEntries": 3,
      "missingSignatureEntries": 0,
      "staleSignatureEntries": 0,
      "minimumThemesForBloom": 2,
      "themeCounts": {
        "planet": 2,
        "people": 3,
        "health": 1,
        "honesty": 2,
        "privacy": 2,
        "cost": 3
      }
    },
    "previewFixtures": [
      {
        "category": "phones",
        "code": "fairphone",
        "name": "Fairphone",
        "route": "#card/phones/fairphone",
        "themeCount": 4,
        "signature": {
          "planet": 96,
          "people": 95,
          "privacy": 70,
          "cost": 55
        }
      },
      {
        "category": "banking",
        "code": "beneficial-state",
        "name": "Beneficial State Bank",
        "route": 
…

A file that must be rejected

Generated design-token index counts must match the profile arrays they summarize.

{
  "format": "open-values-design-token-index",
  "version": "0.1.0",
  "standard": "open-values-standard",
  "built": "2026-07-08",
  "purpose": "Fixture generated design-token index.",
  "generatedFrom": {
    "path": "content/design/tokens.json",
    "updated": "2026-07-08",
    "sha256": "abcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcd"
  },
  "principles": [
    "contrast is computed"
  ],
  "references": [
    {
      "label": "WCAG contrast",
      "url": "https://www.w3.org/TR/WCAG22/#contrast-minimum",
      "asof": "2026"
    }
  ],
  "counts": {
    "profiles": 2,
    "colorTokens": 12,
    "contrastPairs": 1,
    "passingContrastPairs": 1,
    "failingContrastPairs": 0,
    "componentContracts": 1,
    "artTokens": 1,
    "artKinds": 1
  },
  "filters": {
    "profiles": [
      "sample-skin"
    ],
    "roles": [
      "fixture-skin"
    ],
    "artKinds": [
      "svg-line"
    ]
  },
  "profiles": [
    {
      "id": "sample-skin",
      "label": "Sample Skin",
      "role": "fixture-skin",
      "status": "format-seed",
      "summary": "Fixture profile for conformance.",
      "cssVariables": {
        "--ov-sample-skin-color-text": "#111111"
      },
      "colorTokens": [
        {
          "id": "background",
          "value": "#FFFFFF",
          "role": "background"
        },
        {
          "id": "surface",
          "value": "#F7F7F7",
          "role": "surface"
        },
        {
          "id": "text",
          "value": "#111111",
          "role": "text"
        },
        {
          "id": "mutedText",
          "value": "#555555",
          "role": "muted text"
        },
        {
          "id": "border",
          "value": "#CCCCCC",
          "role": "border"
        },
        {
          "id": "accent",
          "value": "#255E46",
          "role": "accent"
        },
        {
          "id": "accentText",
          "value": "#FFFFFF",
          "role": "accent text"
        },
        {
          "id": "focus",
          "value": "#7A4A12",
          "role": "focus"
        },
        {
          "id": "link",
          "value": "#205C8A",
          "role": "link"
        },
        {
          "id": "success",
          "value": "#2E6F3E",
          "role": "success"
        },
        {
          "id": "warning",
          "value": "#7A5411",
          "role": "warning"
        },
        {
          "id": "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."
        ]
      },
      "contrast": [
        {
          "id": "body-on-background",
          "fg": "text",
          "bg": "background",
          "purpose": "normal-text",
          "foreground": "#111111",
          "background": "#FFFFFF",
          "minimum": 4.5,
          "ratio": 18.88,
          "pass": true
        }
      ],
      "contrastSummary": {
        "pairs": 1,
        "pass": 1,
        "fail": 0,
        "minimumRatio": 18.88
      },
      "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",
          "
…

The schema

Its address is https://openvaluesstandard.org/schema/design-token-index-v0.1.schema.json. Validators can fetch it there; the file is also in the repository at app/data/standard/schemas/design-token-index.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.