Color

1. Overview

Color is a layered system for communicating hierarchy, interaction, state, and data relationships. Primitive palettes provide raw values; semantic tokens assign purpose; component tokens apply those roles to specific parts and states. Product code consumes semantic or component tokens so a theme can change without changing meaning.

Use color to reinforce structure and feedback. Do not use it as decoration when the result weakens hierarchy, contrast, or cross-theme consistency.

2. Principles / Usage Guidelines

1. Meaning precedes appearance. Select a semantic role by purpose, not by a preferred hue.
2. Themes preserve semantics. Atlantic and Pasture may change expression, but text, surface, action, and status roles retain the same function.
3. Contrast is a release requirement. Validate text, icons, controls, focus indicators, charts, and adjacent state boundaries in every supported expression.
4. Color is redundant communication. Pair color with text, iconography, shape, pattern, position, or direct labeling.
5. Status and category are separate systems. Do not reuse success, warning, or danger colors as arbitrary data-series colors.
6. State transitions remain distinguishable. Default, hover, pressed, selected, disabled, and focus states require perceivable differences that do not depend on hue alone.

3. Token Architecture

primitive palette
→ semantic role
→ component part or state
→ rendered instance

Primitive tokens describe values and must not appear in application code. Semantic tokens describe purpose and adapt by theme. Component tokens define anatomy and interaction states. A rendered instance does not introduce a new color decision.

Visual Examples

Every specimen resolves from the canonical token layer used by the Web package. Primitive values are reference material; application interfaces consume semantic or component roles.

4. Specifications & Anatomy

Semantic roles

Theme expressions

Atlantic is a cool technical expression. Pasture is a warm organic expression. Components use the same semantic token path in both themes. A theme switch changes the resolved value, not the component API, accessible name, status meaning, or interaction model.

Interaction states

Primary, secondary, and danger actions provide default, hover, pressed, and text roles. Focus is an independent indicator and must remain visible on top of every state. Disabled appearance uses the registered disabled role or opacity token but cannot carry essential information.

Data visualization

Keep categorical order stable and use no more than six series without direct labels. Use sequential color for ordered magnitude. Use diverging color only when a meaningful midpoint exists. Every chart requires an equivalent text or table representation and cannot identify a series by color alone.

5. Best Practices

6. Accessibility

Color conforms to WCAG 2.2 AA.

• Normal text requires at least 4.5:1 contrast; large text requires at least 3:1.
• User-interface components, meaningful graphics, focus indicators, and adjacent state boundaries require at least 3:1 where non-text contrast applies.
• Links inside body copy require more than color alone, such as a persistent underline.
• Error, success, warning, selection, and disabled states require a written or structural equivalent.
• Custom controls and visualizations remain understandable in forced-colors: active using system colors, borders, patterns, and labels.
• Screen readers do not announce color; accessible names and descriptions communicate actual meaning.

7. Architectural Integration (Web & Flutter)

Web components import color.css and use domain-neutral semantic aliases such as --ds-color-text-primary, --ds-color-surface-primary, and --ds-color-action-primary-background. JavaScript resolves registered metadata through getColorPalette, getSemanticColorGroup, and getColorCssVariable.

Flutter uses DsColorTheme, a ThemeExtension containing the same semantic roles. Widgets read the active extension and receive semantic variants rather than raw Color values.

8. MCP Server Context

Resolve color through primitive, semantic, and component layers; application code must consume semantic or component tokens rather than hexadecimal values or primitive palette tokens. Select a role by purpose, preserve the same meaning across Atlantic and Pasture expressions, and verify WCAG 2.2 AA contrast for every foreground and adjacent-color pair. Never use color alone for meaning; add text, iconography, shape, pattern, or position, and provide a forced-colors fallback for custom controls and visualizations.