DSDS Token and Token Group Definitions

2 definitions in this file:

token
tokenGroup

Identifies this entity as a token.

The token name. 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 name.

The type of token aligned with the DTCG spec (e.g., 'color', 'dimension', 'fontFamily', 'fontWeight', 'duration', 'cubicBezier', 'shadow').

Reference to the authoritative W3C Design Tokens Format (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` discriminator. Types 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 general document block types only (guideline, use-cases, accessibility, examples). Each document block entry has a `type` property that determines its shape. Ordering is significant: tools SHOULD preserve it for display.

Agent-optimized context for this token — intent, constraints, disambiguation, anti-patterns, examples, and keywords for efficient agentic consumption.

References: entityMetadata, tokenDocumentBlock, agents, extensions

{ "kind": "token", "name": "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": { "name": "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": { "name": "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" }, { "url": "https://www.w3.org/TR/WCAG22/#contrast-enhanced" } ] } ], "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 name. 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 name.

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'.

An ordered array of tokens and/or nested token groups in this group. Each item MUST be either a token or a tokenGroup. Ordering is significant — tools SHOULD preserve order for display, as it often represents 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` discriminator. Types 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 general document block types only (guideline, use-cases, accessibility, examples). Document blocks for the group as a whole live here. Document blocks for individual tokens SHOULD be placed on the token within children.

Agent-optimized context for this token — intent, constraints, disambiguation, anti-patterns, examples, and keywords for efficient agentic consumption.

References: token, tokenGroup, entityMetadata, tokenDocumentBlock, agents, extensions