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.
- Files built from other files
- Status: draft
- Version: 0.1.0
- Format name in the file:
open-values-design-token-index
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
| Field | What it means | Type |
|---|---|---|
format required | Names the file format. Always open-values-design-token-index. | always "open-values-design-token-index" |
version required | The version of this format the file follows. Currently 0.1.0. | string |
standard required | The standard this file belongs to. Always open-values-standard. | always "open-values-standard" |
built required | The date of the index, as YYYY-MM-DD, copied from the updated date of the tokens file. | see date |
purpose required | A sentence saying what the index is for. | see nonEmptyString |
generatedFrom required | The tokens file the index was built from, with its date and hash, so a stale index can be detected. | object |
principles required | The design rules from the tokens file, copied unchanged. | list |
references | The outside documents from the tokens file, copied unchanged. | list |
valueBloom required | The 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 required | The same counts as valueBloom.signatureCoverage: how many catalogue options have theme scores and stored signatures. | see valueSignatureCoverage |
cssVariableMapping required | The token to CSS custom property table from the tokens file, copied unchanged. | see cssVariableMapping |
contrastRemediationContract | The contrast fix checklist from the tokens file, copied unchanged. | see contrastRemediationContract |
skinReadiness required | Whether 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 required | Totals across the whole index. | see counts |
filters required | Sorted lists of the ids that appear in the index, for building filters and checks. | object |
profiles required | Every 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.