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.
- Files people or tools write
- Status: draft
- Version: 0.1.0
- Format name in the file:
open-values-design-tokens
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
| Field | What it means | Type |
|---|---|---|
format required | Names the file format. Always open-values-design-tokens. | always "open-values-design-tokens" |
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" |
updated required | The date the tokens were last changed, as YYYY-MM-DD. | see date |
purpose required | A sentence saying what the token set is for. | see nonEmptyString |
principles required | Short design rules every profile in the file follows, such as that contrast is computed rather than asserted. | list |
references | Outside documents the tokens rely on, such as the WCAG contrast rules. | list |
valueBloom required | Colours 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 required | A review table that says which CSS custom property in the app each design token should set. | see cssVariableMapping |
contrastRemediationContract | A 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 required | The 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.