2 definitions in this file:
Identifies this entity as a token.
The token identifier. Unconstrained by a pattern to accommodate DTCG and design tool naming conventions that use dots, slashes, or other separators (e.g., 'color-text-primary', 'color.text.primary', 'color/text/primary'). Also serves as the human-readable display label.
The type of token aligned with the DTCG spec (e.g., 'color', 'dimension', 'fontFamily', 'fontWeight', 'duration', 'cubicBezier', 'shadow').
Pointer to the W3C Design Tokens (DTCG) definition. DSDS does not duplicate token values — the DTCG file is the source of truth for resolved values, aliases, and type information.
Modular metadata entries. Each entry is a typed object with a kind tag. Kinds include status, since, tags, category, aliases, summary, thumbnail, preview, extends, and links.
All structured docs for this token, as an ordered array of typed document block objects. Tokens accept the general kinds only (guideline, use-cases, accessibility, examples). The type property on each entry sets its shape. Order matters: tools SHOULD preserve it for display.
AI-ready context for this token: intent, constraints, disambiguation, anti-patterns, examples, and keywords for efficient AI use.
References:
entityMetadata, tokenDocumentBlock, agents, extensions
{
"kind": "token",
"identifier": "color-text-primary",
"metadata": [
{
"kind": "description",
"value": "The default color for body text, headings, and labels. Provides the highest-contrast text color for standard reading content on default background surfaces."
},
{
"kind": "status",
"status": "stable",
"platformStatus": {
"css": {
"status": "stable",
"since": "2.0.0"
},
"ios": {
"status": "stable",
"since": "2.1.0"
},
"android": {
"status": "stable",
"since": "2.2.0"
},
"figma": {
"status": "stable",
"since": "2.0.0"
}
}
},
{
"kind": "since",
"value": "2.0.0"
},
{
"kind": "tags",
"items": [
"color",
"text",
"body"
]
},
{
"kind": "category",
"value": "semantic"
},
{
"kind": "aliases",
"items": [
"color.text.default",
"color.text.body"
]
},
{
"kind": "summary",
"value": "Default body text color for light and dark surfaces."
},
{
"kind": "links",
"items": [
{
"kind": "source",
"url": "https://code.acme.com/design-system/src/tokens/color/text.tokens.json",
"label": "Token source file"
},
{
"kind": "documentation",
"url": "https://design.acme.com/tokens/color-text-primary",
"label": "Token documentation"
},
{
"kind": "related",
"url": "https://design.acme.com/tokens/color-text-secondary",
"label": "color-text-secondary"
},
{
"kind": "related",
"url": "https://design.acme.com/tokens/color-text-tertiary",
"label": "color-text-tertiary"
}
]
}
],
"tokenType": "color",
"source": {
"file": "tokens/color.tokens.json",
"path": "color.text.primary"
},
"documentBlocks": [
{
"kind": "purpose",
"useCases": [
{
"description": "When applying color to body text, headings, and form labels on default background surfaces.",
"kind": "positive"
},
{
"description": "When building components that display primary reading content that must adapt across color modes.",
"kind": "positive"
},
{
"description": "When placing text on dark or colored background surfaces.",
"kind": "negative",
"alternative": {
"identifier": "color-text-inverse",
"rationale": "This token is optimized for contrast against light backgrounds. Using it on dark or saturated surfaces will fail contrast requirements."
}
},
{
"description": "When the text is inside a component that supplies its own scoped color tokens (e.g., text on a filled button).",
"kind": "negative",
"alternative": {
"identifier": "color-text-on-action",
"rationale": "Component-scoped tokens account for the specific background they sit on. Applying a general text token to a scoped context risks contrast failures."
}
}
],
"agents": {
"intent": "Clarify when to use the color-text-primary token versus other text color tokens.",
"disambiguation": [
{
"entity": "color-text-secondary",
"distinction": "Use color-text-primary for body text and headings; use color-text-secondary for supplementary or de-emphasized text."
},
{
"entity": "color-text-on-action",
"distinction": "Use color-text-primary on standard surfaces; use color-text-on-action on filled interactive elements like buttons."
}
],
"keywords": [
"when to use",
"text color",
"primary",
"body text"
]
}
},
{
"kind": "guideline",
"items": [
{
"guidance": "Use for all body text, headings, and form labels on default background surfaces.",
"rationale": "A single primary text color ensures visual consistency and meets WCAG 2.1 AA contrast requirements against the system's default background.",
"kind": "encouraged",
"category": "visual-design"
},
{
"guidance": "Do not override this token's value at the component level. Use color-text-secondary or color-text-tertiary for reduced emphasis.",
"rationale": "Overriding the primary text color creates inconsistency. The system provides lower-emphasis text tokens for visual hierarchy.",
"kind": "prohibited",
"category": "visual-design"
},
{
"guidance": "This color meets a 15.3:1 contrast ratio against color-background-default in light mode.",
"rationale": "Exceeds WCAG 2.1 AAA requirements (7:1 for normal text), ensuring readability for users with low vision.",
"kind": "informational",
"category": "accessibility",
"criteria": [
{
"url": "https://www.w3.org/TR/WCAG22/#contrast-minimum",
"kind": "reference"
},
{
"url": "https://www.w3.org/TR/WCAG22/#contrast-enhanced",
"kind": "reference"
}
]
}
],
"agents": {
"intent": "Enforce correct usage rules for the color-text-primary token.",
"constraints": [
{
"rule": "Do not use color-text-primary on colored or image backgrounds without verifying contrast.",
"level": "must-not"
},
{
"rule": "Always pair with a background token from the same surface family.",
"level": "should"
}
],
"keywords": [
"rules",
"contrast",
"pairing",
"surface"
]
}
},
{
"kind": "accessibility",
"wcagLevel": "AAA",
"colorContrast": [
{
"foreground": "color-text-primary",
"background": "color-background-default",
"contrastRatio": 15.3,
"level": "AAA",
"context": "Primary text on default background in light mode."
},
{
"foreground": "color-text-primary",
"background": "color-background-subtle",
"contrastRatio": 13.8,
"level": "AAA",
"context": "Primary text on subtle background (card surface) in light mode."
}
],
"agents": {
"intent": "Provide contrast ratios and WCAG compliance data for the color-text-primary token.",
"keywords": [
"WCAG",
"contrast",
"AA",
"AAA",
"accessibility",
"ratio"
]
}
}
],
"agents": {
"intent": "Apply the primary text color for body content, headings, and labels on default background surfaces.",
"constraints": [
{
"rule": "Do not use on dark or colored background surfaces.",
"level": "must-not"
},
{
"rule": "Do not override this token value at the component level.",
"level": "must-not"
}
],
"disambiguation": [
{
"entity": "color-text-secondary",
"distinction": "Use primary for default reading content; use secondary for supporting or reduced-emphasis text."
},
{
"entity": "color-text-on-action",
"distinction": "Use primary on default surfaces; use on-action inside filled interactive components."
}
],
"keywords": [
"color",
"text",
"primary",
"body",
"heading",
"label",
"foreground"
]
}
}
Identifies this entity as a token-group.
The token group identifier. Unconstrained by a pattern to accommodate DTCG and design tool naming conventions (e.g., 'color-text', 'color.text', 'color/text'). Also serves as the human-readable display label.
When all tokens in this group share the same DTCG token type, declare it here to avoid repetition on each child. Each token in children MAY override this value. Common values: 'color', 'dimension', 'fontFamily', 'fontWeight', 'duration', 'number', 'shadow'.
Pointer to the W3C Design Tokens (DTCG) definition. DSDS does not duplicate token values — the DTCG file is the source of truth for resolved values, aliases, and type information.
An ordered array of tokens and/or nested token groups inside this group. Each item MUST be either a token or a tokenGroup. Order matters — tools SHOULD preserve it for display, since it often shows a meaningful progression (e.g., lightest to darkest, or smallest to largest). Children inherit tokenType and status from this group when they omit their own values.
Min items: 1
Modular metadata entries. Each entry is a typed object with a kind tag. Kinds include status, since, tags, category, aliases, summary, thumbnail, preview, extends, and links.
All structured docs for this token group, as an ordered array of typed document block objects. Accepts the general kinds only (guideline, use-cases, accessibility, examples). Use this array for docs that apply to the group as a whole. Place docs for individual tokens on the token inside children.
AI-ready context for this token: intent, constraints, disambiguation, anti-patterns, examples, and keywords for efficient AI use.
References:
token, tokenGroup, entityMetadata, tokenDocumentBlock, agents, extensions
Design System Documentation Spec (DSDS) 0.2.1 — Draft Specification
GitHub