2 definitions in this file:
The name of the token being overridden. MUST match the `name` of a token defined elsewhere in the system. Token names are unconstrained by a pattern to support DTCG and design tool naming conventions (e.g., 'color-text-primary', 'color.text.primary', 'color/text/primary').
Explains what changes for this token in this theme and why — e.g., 'Lightened to meet WCAG AAA contrast on the dark background.' The resolved value itself is in the DTCG file.
References:
richText
Identifies this entity as a theme.
Machine-readable identifier for the theme (e.g., 'dark', 'high-contrast', 'compact', 'brand-sub-brand').
Pattern: ^[a-z][a-z0-9-]*$
Human-readable name for the theme (e.g., 'Dark Mode', 'High Contrast', 'Compact Density').
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.
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.
Token overrides that this theme affects. Each entry documents which token is changed and why. Only list tokens whose values differ from the default — unlisted tokens retain their default values. The actual override values live in the DTCG file referenced by source.
Min items: 1
All structured docs for this theme as an ordered array of typed document block objects. Themes 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 theme — intent, constraints, disambiguation, anti-patterns, examples, and keywords for efficient agentic consumption.
References:
entityMetadata, tokenOverride, tokenDocumentBlock, agents, extensions
{
"kind": "theme",
"name": "dark",
"displayName": "Dark Mode",
"metadata": [
{
"kind": "description",
"value": "The dark color mode theme. Inverts the default light surface/text relationship, using light text on dark backgrounds. Designed for low-light environments, user preference, and reduced eye strain. All override values have been validated to maintain WCAG AA contrast ratios against the dark background surfaces."
},
{
"kind": "status",
"status": "stable",
"platformStatus": {
"react": {
"status": "stable",
"since": "2.0.0"
},
"web-component": {
"status": "stable",
"since": "2.1.0"
},
"ios": {
"status": "stable",
"since": "2.0.0",
"description": "Automatically applied when the device is set to dark appearance."
},
"android": {
"status": "stable",
"since": "2.2.0",
"description": "Follows the system-level dark theme setting via AppCompat.DayNight."
},
"figma": {
"status": "stable",
"since": "2.0.0",
"description": "Available as a dedicated mode in the Figma variable collection."
}
}
},
{
"kind": "since",
"value": "2.0.0"
},
{
"kind": "tags",
"items": [
"dark-mode",
"color-mode",
"accessibility"
]
},
{
"kind": "category",
"value": "color-mode"
},
{
"kind": "summary",
"value": "A dark color mode theme for low-light environments and user preference."
},
{
"kind": "links",
"items": [
{
"kind": "design",
"url": "https://www.figma.com/file/abc123/color-system?node-id=100:200",
"label": "Figma — Dark mode variable collection"
},
{
"kind": "documentation",
"url": "https://design.example.com/foundations/color/dark-mode",
"label": "Dark mode usage guidelines"
},
{
"kind": "source",
"url": "https://github.com/example/design-system/blob/main/tokens/themes/dark.tokens.json",
"label": "Dark theme token source (DTCG format)"
}
]
}
],
"overrides": [
{
"token": "color-background-default",
"description": "Inverted default surface for dark mode."
},
{
"token": "color-background-elevation-accent",
"description": "Slightly lighter accent surface for dark layering."
},
{
"token": "color-background-elevation-floating",
"description": "Floating surface, one step lighter than accent in dark mode."
},
{
"token": "color-background-elevation-raised",
"description": "Raised surface, lighter still to communicate depth in dark mode."
},
{
"token": "color-background-secondary-base",
"description": "Secondary background remapped for dark surfaces."
},
{
"token": "color-background-inverse-base",
"description": "Inverse background flipped to near-white for dark mode."
},
{
"token": "color-background-error-base",
"description": "Error background lightened for visibility on dark surfaces."
},
{
"token": "color-background-error-weak",
"description": "Subtle error background darkened for dark mode."
},
{
"token": "color-background-success-base",
"description": "Success background lightened for visibility on dark surfaces."
},
{
"token": "color-background-success-weak",
"description": "Subtle success background darkened for dark mode."
},
{
"token": "color-background-info-base",
"description": "Info background lightened for visibility on dark surfaces."
},
{
"token": "color-background-info-weak",
"description": "Subtle info background darkened for dark mode."
},
{
"token": "color-background-warning-base",
"description": "Warning background lightened for visibility on dark surfaces."
},
{
"token": "color-background-warning-weak",
"description": "Subtle warning background darkened for dark mode."
},
{
"token": "color-background-selected-base",
"description": "Selected-state background remapped for dark surfaces."
},
{
"token": "color-text-default",
"description": "Primary text switched to white for dark backgrounds."
},
{
"token": "color-text-subtle",
"description": "Subtle text lightened to maintain AA contrast on dark surfaces."
},
{
"token": "color-text-disabled",
"description": "Disabled text adjusted for dark mode."
},
{
"token": "color-text-inverse",
"description": "Inverse text switched to near-black for light-on-dark inversion."
},
{
"token": "color-text-error",
"description": "Error text lightened for contrast on dark backgrounds."
},
{
"token": "color-text-success",
"description": "Success text lightened for contrast on dark backgrounds."
},
{
"token": "color-text-warning",
"description": "Warning text adjusted for dark mode contrast."
},
{
"token": "color-text-link",
"description": "Link text shifted to a lighter blue for dark mode."
},
{
"token": "color-icon-default",
"description": "Default icon color switched to white for dark mode."
},
{
"token": "color-icon-subtle",
"description": "Subtle icon color lightened for dark surfaces."
},
{
"token": "color-icon-inverse",
"description": "Inverse icon color switched to near-black."
},
{
"token": "color-icon-disabled",
"description": "Disabled icon color adjusted for dark mode."
},
{
"token": "color-icon-error",
"description": "Error icon color lightened for dark backgrounds."
},
{
"token": "color-icon-success",
"description": "Success icon color lightened for dark backgrounds."
},
{
"token": "color-icon-info",
"description": "Info icon color lightened for dark backgrounds."
},
{
"token": "color-icon-warning",
"description": "Warning icon color adjusted for dark mode."
},
{
"token": "color-icon-recommendation",
"description": "Recommendation icon color lightened for dark backgrounds."
},
{
"token": "color-border-default",
"description": "Default border lightened for visibility on dark surfaces."
},
{
"token": "color-border-container",
"description": "Container border adjusted for dark mode."
},
{
"token": "color-border-error",
"description": "Error border lightened for dark backgrounds."
},
{
"token": "elevation-floating",
"description": "Floating elevation removed; dark mode uses surface color for depth."
},
{
"token": "elevation-raised-top",
"description": "Top raised shadow effectively invisible in dark mode."
},
{
"token": "elevation-raised-bottom",
"description": "Bottom raised shadow effectively invisible in dark mode."
}
],
"documentBlocks": [
{
"kind": "purpose",
"useCases": [
{
"description": "When the user's system preference is `prefers-color-scheme: dark` or they have explicitly selected dark mode in the application settings.",
"kind": "positive"
},
{
"description": "When the application is used in low-light environments where a bright screen causes eye strain or discomfort.",
"kind": "positive"
},
{
"description": "When embedding content in a context that is already dark (e.g., a media player, a code editor, or a presentation tool in dark mode).",
"kind": "positive"
},
{
"description": "When the user has not expressed a preference for dark mode. Default to the light theme.",
"kind": "negative",
"alternative": {
"name": "light",
"rationale": "Dark mode can reduce readability for users with certain visual impairments such as astigmatism, where light text on dark backgrounds causes halation. Defaulting to light ensures the broadest accessibility baseline."
}
},
{
"description": "When high-contrast accessibility is the primary concern rather than a dark aesthetic.",
"kind": "negative",
"alternative": {
"name": "high-contrast",
"rationale": "The dark theme is optimized for comfort in low-light environments, not maximum contrast. The high-contrast theme provides stronger contrast ratios that better serve users with low vision."
}
},
{
"description": "When the content is primarily photographic or illustrative and the surrounding chrome should not compete visually.",
"kind": "negative",
"alternative": {
"name": "light",
"rationale": "Photographic content often assumes a neutral white surround for accurate color perception. A dark surround shifts the viewer's perception of brightness and color in the images."
}
}
],
"agents": {
"intent": "Clarify when to apply the dark theme versus the default or high-contrast themes.",
"disambiguation": [
{
"entity": "high-contrast theme",
"distinction": "Dark theme reduces luminance for low-light environments; high-contrast theme maximizes contrast ratios for visual accessibility."
}
],
"keywords": [
"when to use",
"dark mode",
"low light",
"user preference"
]
}
},
{
"kind": "guideline",
"items": [
{
"guidance": "Apply the dark theme at the application root when the user's system preference is `prefers-color-scheme: dark` or when they explicitly select dark mode in the application settings.",
"rationale": "Respecting the user's color scheme preference improves comfort in low-light environments and can reduce eye strain. Forcing a color mode against the user's preference creates friction.",
"kind": "required",
"category": "development"
},
{
"guidance": "In dark mode, layers become one step lighter with each added layer. Do not apply components that are darker than their background surface.",
"rationale": "The dark theme's layering model uses increasing lightness to communicate depth. Reversing this — placing darker elements on lighter surfaces — breaks the spatial hierarchy and confuses the visual relationship between layers.",
"kind": "required",
"category": "visual-design"
},
{
"guidance": "Do not mix light-mode and dark-mode semantic tokens on the same surface. Use inline theme switching if a component must appear in the opposite mode.",
"rationale": "Mixing tokens from different themes produces unpredictable contrast pairings. Semantic tokens are only validated for contrast within their own theme context.",
"kind": "prohibited",
"category": "visual-design"
},
{
"guidance": "Shadows (elevation tokens) are replaced with surface color differentiation in dark mode. Do not add custom box-shadow values to create depth.",
"rationale": "Dark backgrounds absorb shadow, making traditional drop shadows invisible or visually muddy. The dark theme communicates depth through lighter surface values instead.",
"kind": "discouraged",
"category": "visual-design"
},
{
"guidance": "Ensure all custom illustrations, charts, and images remain legible in dark mode. Provide dark-mode variants of images that use light backgrounds or thin strokes.",
"rationale": "Illustrations designed for light backgrounds may become invisible or illegible on dark surfaces. Custom visual content requires the same level of dark-mode adaptation as UI components.",
"kind": "encouraged",
"category": "visual-design"
}
],
"agents": {
"intent": "Enforce correct dark theme implementation rules.",
"constraints": [
{
"rule": "Always test all component variants under the dark theme — do not assume light-theme contrast ratios transfer.",
"level": "must"
},
{
"rule": "Respect the user's prefers-color-scheme OS setting as the default.",
"level": "should"
}
],
"keywords": [
"rules",
"testing",
"prefers-color-scheme",
"implementation"
]
}
},
{
"kind": "accessibility",
"wcagLevel": "AA",
"colorContrast": [
{
"foreground": "color-text-default",
"background": "color-background-default",
"contrastRatio": 15.9,
"level": "AAA",
"context": "Primary text (#FFFFFF) on default dark background (#111111)."
},
{
"foreground": "color-text-subtle",
"background": "color-background-default",
"contrastRatio": 4.6,
"level": "AA",
"context": "Secondary/subtle text (#A5A5A5) on default dark background (#111111)."
},
{
"foreground": "color-text-link",
"background": "color-background-default",
"contrastRatio": 5.7,
"level": "AA",
"context": "Link text (#45A3FE) on default dark background (#111111)."
},
{
"foreground": "color-text-error",
"background": "color-background-default",
"contrastRatio": 5.1,
"level": "AA",
"context": "Error text (#F47171) on default dark background (#111111)."
},
{
"foreground": "color-text-default",
"background": "color-background-elevation-accent",
"contrastRatio": 14.4,
"level": "AAA",
"context": "Primary text (#FFFFFF) on accent surface (#191919)."
},
{
"foreground": "color-text-default",
"background": "color-background-elevation-floating",
"contrastRatio": 11.3,
"level": "AAA",
"context": "Primary text (#FFFFFF) on floating surface (#2B2B2B)."
}
],
"agents": {
"intent": "Provide WCAG compliance data and contrast verification requirements for the dark theme.",
"keywords": [
"WCAG",
"contrast",
"dark surfaces",
"accessibility",
"AA"
]
}
}
],
"agents": {
"intent": "Apply a dark color palette for low-light environments and user preference, maintaining WCAG AA contrast throughout.",
"constraints": [
{
"rule": "Always apply at the application root, not on individual components.",
"level": "must"
},
{
"rule": "Do not mix dark-mode and light-mode semantic tokens on the same surface.",
"level": "must-not"
}
],
"disambiguation": [
{
"entity": "high-contrast",
"distinction": "Use dark for low-light comfort; use high-contrast for users with low vision requiring maximum contrast."
}
],
"antiPatterns": [
{
"description": "Applying dark theme only to part of a page while the rest remains light.",
"instead": "Use inline theme switching for isolated components; apply the theme at the root for global coverage."
}
],
"keywords": [
"dark-mode",
"color-mode",
"night",
"low-light",
"theme",
"override"
]
},
"$extensions": {
"com.designTool": {
"variableCollectionId": "VariableCollectionId:dark-mode"
}
}
}
Design System Documentation Standard (DSDS) 0.1 — Draft Specification
GitHub