Semantic Palettes and Action States

Status: Canonical (v1.0)
Last updated: 2026-08-10 Taxonomy placement: D0. Color (Emotional Palette)
Audience: Design Systems, Product Design, Front-End Engineering

CEM uses color as the primary channel for communicating, using a branded palette to express:

• using branded palette express
• Emotional intent: what the interface wants the user to feel (trust, danger, creativity, etc.)
• Interaction meaning: what an action will do (primary, destructive, alternate, etc.)
• State progression: how an element's condition changes (default → hover → active → pending)

Companion specs:

• D1. Space & Rhythm (cem-dimension.md) — spacing scale, density modes, and layout gaps
• D2. Coupling & Compactness (cem-coupling.md) — density affects perceived color intensity and separability
• D3. Shape — Bend (cem-shape.md) — rounded shapes soften color impact
• D4. Layering (cem-layering.md) — tonal shifts for depth perception (recess/lift)
• D5. Stroke & Separation (cem-stroke.md) — focus/selection colors; D0 defines hue, D5 defines geometry
• D6. Typography (cem-voice-fonts-typography.md) — text contrast requirements
• D7. Time & Motion (cem-timing.md) — color transition timing

Table of contents

1. Scope
2. Design principles
3. Token taxonomy
4. Base branded color family
5. Emotional palette
6. Theme modes
7. Action intent and state tokens
8. Zebra outline colors
9. System colors and forced-colors
10. Component mapping checklist
11. Accessibility and QA
12. Implementation guidance
13. Governance and versioning
14. Canonical token summary
15. References

1. Scope

1.1 What D0 controls (and what it does not define)

D0 (Color) defines:

• The semantic meaning of color: emotional palette, action intent colors, and state colors.
• System/forced-colors mapping for survivable theming in high-contrast environments.
• The color endpoints used by other dimensions (e.g., zebra stripe colors).

D0 (Color) does not define:

• Stroke geometry (ring widths, stripe layout, offsets): see D5 Stroke.
• Spacing/density and hit targets: see D1 Space & Rhythm.
• Layer depth/physical appearance (shadows, blur): see D4 Layering.
• Motion durations/easing: see D7 Motion.

This spec defines consumer-semantic color tokens for CEM:

• A compact branded color family (--cem-color-*) used as implementation substrate.
• An emotional palette (--cem-palette-*) that expresses meaning in user language (comfort, trust, danger, etc.).
• Action intent and state tokens (--cem-action-*) for buttons/steps and other “do something” controls.
• Navigation-item state tokens (--cem-navigation-item-*) for links, disclosures, and tabs that move or switch context while preserving current/selected meaning.
• Interactive-content state tokens (--cem-content-interaction-*) for content-owned native controls such as checkable chips and selectable-list composites, without classifying them as actions, navigation, or form inputs.
• A separator color endpoint (--cem-separator-color) for non-content lines that reinforce sibling separation without acquiring the full salience of readable text.
• Zebra outline colors (--cem-zebra-*) used with D5 Stroke to express selection/focus/target without relying on fill.
• System/forced-colors integration so CEM remains accessible and compatible with platform theming.

Non-goals:

• This document does not define shape/stroke/spacing metrics (see D5 Stroke, D1 Space, etc.).
• This document does not prescribe a single brand palette; it specifies semantic endpoints and default reference mappings.

2. Design principles

2.1 Consumer-semantic meaning first

Tokens are named for what the user experiences (comfort, danger, trust) and for flow semantics (primary, destructive, selected, pending), rather than for RGB/hex values.

2.2 State separation is multi-channel

CEM intentionally separates meaning across channels:

• Background/fill for “background-driven” states (default/hover/active/pending/disabled).
• Zebra outline (D5 + --cem-zebra-*) for high-salience but non-fill states (focus/target/selected).
• Marker/text for required/indeterminate and other information-bearing states.

This avoids overloading color fill and improves accessibility in compact/dense UIs.

2.3 Forced-colors is first-class

2.4 Bounded variation (governance by design)

To avoid “palette explosion”, D0 constrains variation intentionally:

• Stable semantic set: emotions and action intents are a fixed vocabulary.
• Fixed brightness variants: branded hues use a small set of variants (xl, l, d, xd), not per-component shades.
• Formulaic state progression: hover/active/pending are derived via color-mix() rather than hand-picked colors.
• Theme modes are adapters: theme modes remap the same semantics; they do not introduce new semantics.

2.5 Cross-dimension coupling (informative)

• D0 → D4 (Layering): surface/overlay colors must preserve legibility as layers change.
• D0 → D5 (Stroke): focus/selection meaning is primarily expressed via outline channels (zebra) where fill must not be relied upon. Separators take their color from D0 and their line geometry from D5.
• D0 → D6 (Typography): text tokens and weight strategies exist to preserve contrast when fills collapse.
• D0 → D7 (Motion): color changes should align with feedback timing (e.g., hover is immediate; pending is persistent).

When forced-colors is active, system colors win. CEM must preserve semantics using Canvas, CanvasText, Highlight, SelectedItem, etc., and avoid losing meaning when shadows/glows are dropped by the UA.

3. Token taxonomy

3.1 Consumer color vocabulary (informative)

Emotional terms (what the interface wants the user to feel):

cem-palette-emotion

Action terms (what an action will do):

cem-action-kind

State terms (how condition changes):

3.2 Token model: branded → emotional → action

Branded hues (implementation substrate)
  --cem-color-{hue}-{variant}
        │
        ▼
Emotional palette (semantic contract)
  --cem-palette-{emotion} (+ -x / -text / -text-x)
        │
        ▼
Action intents (consumer-facing API)
  --cem-action-{intent}-{state}-{attribute}

3.3 Why three layers?

• Brand control: adjust the branded family without breaking product semantics.
• Semantic stability: emotions/intents remain stable across themes.
• Implementation clarity: components consume action/state endpoints; they do not depend on raw hues.

CEM color endpoints are layered:

1. Base branded family (implementation): --cem-color-{hue}-{variant}
2. Emotional palette (semantic): --cem-palette-{emotion} and --cem-palette-{emotion}-text
3. Action tokens (flow semantic): --cem-action-{intent}-{state}-{attribute}
4. Zebra outline colors (state channel): --cem-zebra-color-0..3 + strip size

Rule: consumers should theme primarily by adjusting palette and (optionally) base colors; product code should depend on palette/action/zebra endpoints.

4. Base branded color family

4.1 Brightness variants (selection guidance)

Branded hues are provided in a small, repeatable set of brightness variants:

4.2 Contrast pairing rule of thumb

When selecting a safe pairing (especially for text and outlines), prefer opposite ends:

• On light backgrounds (xl/l): pair with d or xd for text/outline.
• On dark backgrounds (d/xd): pair with l or xl for text/outline.

4.3 Neutral (grey) exception

The neutral/grey family is intentionally smaller (typically l + d) and is used primarily via the conservative palette.

The base family is a small set of named hues with a few variants. These are reference values (from theme-data.xhtml) and may be overridden by a brand, as long as the semantic palette mappings remain coherent.

4.4 Branded color tokens

cem-color-hue-variant

Variant semantics:

• xl / l: light-scene support (surfaces, containers, accents)
• d / xd: dark-scene support (surfaces, ink-safe accents)

4.5 Native browser colors

cem-color-native

CSS system colors adapt automatically to the user's OS color scheme. In native mode, CEM maps palette endpoints directly to these values (see §9).

5. Emotional palette

The emotional palette is the primary semantic contract for color.

Reference mappings (from theme-data.xhtml) use light-dark() so a single token resolves appropriately for light vs dark schemes.

cem-palette-emotion-shift

5.1 Semantics of the core emotions

• comfort: neutral surface/canvas
• calm: low-salience affordances, calm emphasis
• trust: explicit action affordance, highlight (the button you press)
• enthusiasm: alternate/secondary positive emphasis
• creativity: primary emphasis, “go forward”
• danger: errors and destructive actions
• conservative: low-emphasis/disabled/brand-3 support

6. Theme modes

CEM defines 5 operational modes for color behavior:

cem-theme-mode

Normative expectations:

• native MUST preserve meaning using system semantic colors (no hard-coded hex assumptions).
• contrast-* MUST NOT encode state primarily via background darkness; state must remain legible via zebra outline and markers.

7. Action intent and state tokens

Action tokens encode user-flow intent (primary, explicit, destructive, etc.) and interaction/state.

7.0 Visual reference: emotional palette gradations (light theme)

Supplemental title: Light theme — Emotional palette gradations across interaction states (action intents).

Notes (interpretation):

• The base color aligns with the default state row.
• As interaction escalates (hover → active → pending), tones shift toward the extreme variant (*-x) for higher salience.
• The upward direction ends in neutral/gray for disabled, preserving “less available” semantics.

7.1 Action intent mapping (reference)

cem-action-intent-emotion

7.2 Canonical state model

CEM action states (union of form/action semantics and interaction semantics):

• disabled
• readonly
• editable
• required
• default
• indeterminate
• target
• focus
• hover
• selected
• active
• pending

State progression is defined as a formulaic movement from “least emphasized” to “most emphasized”, using color-mix() against the emotion’s extreme variant (--cem-palette-{emotion}-x).

7.2.1 Background-driven states

disabled → readonly → editable → default → indeterminate → hover → active → pending
 (30%)      (80%)      (90%)      (base)   (90%)          (70%)   (25%)   (5%)

• Percentages are weights of the base emotion mixed toward an “extreme” anchor.
• For disabled, the anchor is the conservative extreme (--cem-palette-conservative-x) to desaturate and quiet the UI.

7.2.2 State formulas (normative)

cem-action-state-color

Applying this to action intents: substitute [emotion] with the emotional palette mapped by the intent (see §7.1). The resulting values populate --cem-action-{intent}-{state}-background and --cem-action-{intent}-{state}-text.

Pending gradient and continuous motion

Outside contrast modes, pending actions MUST show a repeating 45-degree background gradient while their busy source is true. A one-shot color fade is not the pending-motion contract. Use the intent's pending background and dedicated pending stripe background as its two gradient colors, with pending text throughout. Primary, explicit, contextual and alternate use one shared adjustment: mix the active endpoint with 12% white in light schemes and 20% black in dark schemes. Destructive keeps 25% white / 50% black because its yellow foreground has a different contrast range. The default endpoints must exceed 1.8:1 stripe separation and preserve at least 4.5:1 text contrast across the gradient. Dark contrast contours share these endpoints. Light contrast contours use a brighter stripe (40% white, or extra-light red for destructive) as specified in §7.5. Active button paint is unchanged; the pending background remains a color, including as the solid fallback.

cem-pending-colors

The intent image recipes use the pending (5%) and active (25%) palette formulas directly so contrast fill overrides cannot erase their colors. Dark contours match normal fill endpoints. Light contours mix the active palette endpoint with 40% white; destructive uses --cem-color-red-xl. The ordinary fill keeps its text-safe stripe. Existing per-control fill color overrides remain independent.

Native themes retain their system-palette active stripe endpoints for the four ordinary intents; mixing them with fixed white/black can reduce text contrast. Destructive retains its existing native recipe.

cem-action-native-overrides

D5 owns --cem-pending-angle (45deg) and --cem-pending-tile-size (2rem). D7 owns --cem-duration-pending-cycle (2000ms). Use uniform easing and infinite iteration. Translate the background by one square tile along the x axis per cycle. Each transition holds its initial color for 20%, blends for 60%, then holds the final color for 20%. The alternating color ranges are 0–5%, 20–30%, 45–55%, 70–80% and 95–100%; the gaps blend continuously. At 45 degrees, opposite tile edges match and translating one tile closes the loop without a jump. Freeze the pattern under reduced motion. Under forced colors, suppress the gradient and motion and use system button colors with a persistent pending-width boundary. Keep zebra focus rings independent of background motion.

The generated .cem-pending theme utility demonstrates this recipe. Consumers bind the two color inputs and pending foreground for their intent. Canonical components own the same recipe in their embedded scoped CSS. cem-action activates it for pending="true", including disabled buttons. Pending paint takes precedence over disabled paint while pending; native disabled semantics still block activation and focus. Clearing pending while disabled restores the disabled colors. Pending does not itself disable activation. Hover and focus do not restart or replace the continuous animation. Clearing pending removes the gradient and motion and restores current interaction paint.

7.2.3 Outline-driven states

focus, selected, and target are primarily expressed through the zebra outline channel (§8). Background tokens MAY remain at default for these states; do not rely on fill alone. Selection is a first-class persistent state. cem-action[selected] MUST paint selected zebra even when unfocused, disabled or pending. Focus and selected stripes remain independent, and hover/held press do not clear selection. The container owns the selected attribute; the action does not infer it from a click or from disclosure expansion.

7.3 Attribute channels

Action state can affect these channels (the set varies by state):

• background (fill)
• text (ink on fill)
• outline (via zebra / stroke tokens)
• marker (required star, etc.)
• font (weight/face, see Typography spec)

7.4 Minimal required action endpoints

To render functional UIs, the following endpoints are REQUIRED per action intent:

• --cem-action-{intent}-default-background
• --cem-action-{intent}-default-text
• --cem-action-{intent}-hover-background
• --cem-action-{intent}-hover-text
• --cem-action-{intent}-active-background
• --cem-action-{intent}-active-text
• --cem-action-{intent}-disabled-background
• --cem-action-{intent}-disabled-text

Other states (focus, target, pending, required, indeterminate, readonly, editable) are RECOMMENDED, and may be implemented through zebra/markers rather than fill.

7.5 Contrast themes: collapse fills, keep semantics

In contrast-light and contrast-dark, all action background tokens MUST resolve to the base surface (--cem-palette-comfort). Text uses surface ink, including for destructive actions; disabled ink is subdued. The contrast columns in the state table are canonical. There is no intent or state fill progression.

Intent moves to a contour, colored by the intent's extreme palette endpoint. D5 defines its resting/hover/active thickness; keyboard focus retains its independent zebra rings. Pending, including disabled pending, uses an animated 45-degree zebra contour instead of the background gradient. Motion parameters match the normal gradient. Dark contours also retain the normal gradient colors. Light contours brighten the second endpoint with 40% white for primary, explicit, contextual and alternate. Destructive uses the extra-light red endpoint (--cem-color-red-xl, #ffb4ab). All five intents exceed 3:1 stripe separation. This stronger light stripe is confined to the outline; ordinary fills retain their readable text contrast. This explicitly supersedes light-mode fill/contour color parity. Reduced motion freezes the contour. Forced colors uses the existing static system-color pending boundary. Changing back to light/dark/native restores the ordinary gradient. This is the explicit contrast exception to the pending background contract in §7.2.2.

cem-action-outline-colors

cem-action-contrast-overrides

This override table declares no new tokens; it suppresses all intent pending fill stripes in contrast modes. Slider thumbs are foreground markers, so their hover/active ink must not inherit collapsed action backgrounds. Preserve all ordinary-mode endpoints.

7.6 Implementation guidance (non-normative)

Deriving state backgrounds from palette (example):

/* Example: primary intent is mapped to creativity */
:root {
  --cem-action-primary-default-background: var(--cem-palette-creativity);
  --cem-action-primary-default-text:       var(--cem-palette-creativity-text);

  --cem-action-primary-hover-background:   color-mix(in srgb, var(--cem-palette-creativity) 70%, var(--cem-palette-creativity-x));
  --cem-action-primary-hover-text:         var(--cem-palette-creativity-text);

  --cem-action-primary-active-background:  color-mix(in srgb, var(--cem-palette-creativity) 25%, var(--cem-palette-creativity-x));
  --cem-action-primary-active-text:        var(--cem-palette-creativity-text-x);
}

/* Focus should be expressed via zebra outlines (D5), not by fill alone */
.button:focus-visible { outline-color: var(--cem-zebra-color-1); }

Framework adapters (illustrative, not normative):

7.7 Input indicator stripe colors

Ordinary fields, closed selects and unselected choices have no extra resting shadow stack. Native boundaries remain. Choice feedback belongs to the native input, never to its enclosing text label. Hover alone does not add a shadow.

Input controls use a state-composed stripe stack rather than assigning one physical stripe to every possible state. The stack has three physical classes:

1. an anchor/state stripe, absent at rest and activated for pending or invalid states;
2. a focus stripe, activated by :focus-visible and colored by --cem-zebra-color-1;
3. a selection stripe, activated by checked, selected, or indeterminate state.

Invalidity activates the anchor/state stripe at boundary width; pending uses pending width. These outside indicators do not change layout. Focus and selection therefore remain independently visible when an input is also invalid. Required state remains a marker/text concern and does not acquire an indicator stripe. A component with an explicit, truthful busy source binds loading to the pending anchor color and the D5 --cem-stroke-pending width so pending does not rely on hue alone. A custom select or editable autocomplete owns a truthful aria-expanded source and activates the existing selection stripe while its popup is open.

cem-input-indicator-colors

--cem-input-background-color is the theme-owned fill for text inputs. Default underline controls consume it; indicator="outline" sets a local transparent override at the native control so the surrounding surface remains visible. This variant override does not change ancestor or sibling palette tokens. Required markers, focus and validation indicators retain their independent channels.

The anchor precedence is disabled > invalid-hover > invalid > pending > readonly > hover > default. Focus and selection do not participate in that precedence chain because they occupy independent stripes. If invalid and indeterminate coexist, invalid controls the anchor while indeterminate controls the selection stripe.

D5 owns the outline/underline geometry transform and stripe widths. Component libraries may expose a public adapter property that selects that transform, but the adapter is not a replacement for these D0 semantic color endpoints.

7.8 Choice popup and option state colors

Custom selects and editable autocompletes share semantic fill/text pairs for their choice popup and HTML-rendered options. These endpoints are component-family semantics, not raw palette aliases: themes may remap them while preserving the distinction between pointer hover, composite active-descendant, committed selection, and disabled content. Focus and open-state geometry continue to use the input indicator/zebra contract. The historical --cem-select-* prefix remains stable; it names this shared choice-popup state category rather than limiting its use to a button-triggered select.

cem-select-state-colors

7.9 Navigation item state colors

Navigation items move between locations or switch the current local view. They are not action-intent controls: a theme must be able to change navigation styling without also changing primary/contextual commands. Current links and selected tabs share one semantic state, including distinct hover and active pairs so transient input feedback does not erase the current/selected meaning. The default formulas align with contextual/primary action progression, but the navigation endpoints remain independently themeable. Disabled wins over current, hover, and active.

cem-navigation-item-state-colors

7.10 Interactive content state colors

Interactive content controls expose content selection or filtering without becoming action-intent, navigation, or form-input components. Their state colors therefore need an independently themeable category even when the reference formulas align with existing action or palette endpoints. Active endpoints preserve held native-input feedback, while selected-hover and selected-active keep the selected/checked meaning visible during transient input. Disabled wins over selected, hover, and active. Focus remains a separate D5/zebra geometry channel. A current contextual datum is not necessarily selected: for example, today's date remains current while a user previews or commits another calendar date. Its indicator therefore has an independent D0 endpoint whose geometry remains D5-owned.

cem-content-interaction-state-colors

7.11 Separator color

A separator is not readable content and SHOULD NOT normally use the full-strength text color. It nevertheless belongs to the same D0 surface/text relationship so it remains legible when the surface changes. The canonical endpoint is therefore derived from --cem-palette-comfort-text at reduced salience rather than copied from it verbatim.

D0 owns only the color. D5 owns divider thickness and placement, while D1 and D2 determine the space surrounding the line. A component boundary with its own state semantics must use the corresponding component-family color instead of silently reusing this sibling-separation endpoint.

cem-separator-colors

7.12 Progress indicator colors

A progress indicator is status graphics, not readable text, an action, an input stripe, or a sibling separator. Its completed/current arc therefore needs a dedicated semantic color, and its remaining-range track needs an independently themeable reduced-salience color. Components MUST NOT reuse --cem-separator-color: the track represents the value range rather than a relationship between siblings.

Both determinate and indeterminate progress use the same two endpoints. Mode is communicated by geometry, programmatic value semantics, and—when motion is allowed—D7 motion, so color is not the only distinction. In forced colors the track maps to GrayText and the indicator maps to Highlight, preserving the remaining/current distinction with system-owned colors.

cem-progress-indicator-colors

7.13 Workflow step colors

Workflow steppers combine navigation with durable process facts. Header default/current/hover/active/disabled paint uses the navigation-item family, but completion and error markers must remain independently visible when a current or focused header coexists with those facts. Connector graphics represent process progress, not sibling separation or a numeric progress indicator, and therefore must not reuse --cem-separator-color or --cem-progress-*.

Text labels and marker shapes keep workflow meaning redundant with color. In forced colors remaining connectors map to GrayText, completed progress maps to Highlight, and invalidity maps to Mark.

cem-workflow-step-colors

7.14 Slider input colors

A slider is an interactive value input. Its remaining track, selected range, thumb, and step ticks therefore form one dedicated D0 family. These endpoints MUST NOT reuse sibling-separator color or progress status color merely because the rendered graphics contain a line: position along the line is the input value, and the thumb has hover, active, focus, and disabled states.

The default track is reduced-salience surface text, while the active track and thumb derive from the enthusiasm endpoint. Hover and active thumb endpoints are separate so a theme can preserve pointer feedback without changing geometry. In forced colors, geometry plus system colors preserves remaining/selected, enabled/disabled, and thumb/tick distinctions.

cem-slider-colors

8. Zebra outline colors

8.1 Outline-driven state mapping (zebra)

See D5 Stroke for zebra geometry (stripe order, offsets, and ring widths).

Zebra is a striped outline (implemented in D5 Stroke) with four semantic strips.

Color endpoints:

cem-zebra-tokens

Why target occupies the middle ring (color-2): Target is the least-used state — typically once per page. When inactive it collapses to --cem-palette-comfort, so its ring acts as a neutral visual gap. When active the target color is always hue-distinct from both the focus ring (color-1) and the selection ring (color-3), providing clear three-way separability without competing for attention alongside the two more common states. In light and contrast-light modes a warm orange (orange-l) serves this role; in dark mode a mid-tone purple (creativity) does; in native mode the OS Mark color (typically yellow) is used.

8.2 Theme-mode mapping

Focus, selected, and target MUST always resolve to different hues so that combined states (e.g., a focused-and-selected item) remain distinguishable. --cem-zebra-color-0 anchors the ring to the base surface; the remaining stripes are state indicators.

cem-zebra-mode-mapping

Rationale:

• native — Canvas anchors the base stripe to the system surface. CanvasText gives high-contrast focus without colliding with button borders. Mark (yellow) is the OS semantic for highlighted/pointed-at content and maps naturally to the target role. SelectedItem is the OS semantic for selection (color-3). If Mark is unavailable on a target platform, fall back to Highlight.
• light — trust-x (cool blue) for focus. orange-l (warm) for target: hue-distinct from both the focus ring and the selection ring, and bright enough to read as a light visual separator. creativity-x (vivid purple) for selected: high salience without colliding with either focus or target hues.
• dark — comfort-x (inverted surface) for focus: sufficient contrast against the dark surface without an additional branded color. creativity (purple, mid-tone) for target: warm-to-cool shift from comfort-x keeps the two states distinct. calm-x (inverted cyan) for selected: a cooler, distinct hue that reads as "chosen" without competing with focus or target.
• contrast-light — identical mapping to light. In contrast mode, fills collapse to the surface, so the zebra rings carry all state meaning; using the same high-contrast hues as light mode preserves legibility without requiring a separate token set.
• contrast-dark — comfort-x for focus (same as dark). enthusiasm-x (deep orange/mark-derived) for target: high salience in a dark scheme. trust (mid-tone blue) for selected: affirming but clearly distinct from the target stripe.

Zebra colors MUST NOT reuse the same tone as action border/box-shadow indicators in the same theme variation.

8.3 Rules

• :root defaults for focus/target/selected MUST use native system colors (CanvasText, Mark, SelectedItem) so that zebra is functional without an explicit theme class.
• Zebra colors MUST remain distinguishable from the adjacent surface in all modes.
• Zebra MUST remain meaningful in forced-colors; in native this is achieved by mapping to system colors.

9. System colors and forced-colors

9.1 Native/system palette mapping

In native mode, palette endpoints SHOULD map to system colors:

• --cem-palette-comfort: Canvas
• --cem-palette-comfort-text: CanvasText
• --cem-palette-trust: color-mix(in srgb, Highlight 70%, black)
• --cem-palette-trust-text: HighlightText
• --cem-zebra-color-0: Canvas
• --cem-zebra-color-1: CanvasText
• --cem-zebra-color-2: Mark (fallback: Highlight)
• --cem-zebra-color-3: SelectedItem
• --cem-separator-color: CanvasText
• --cem-slider-track-color: GrayText
• --cem-slider-active-track-color: Highlight
• --cem-slider-thumb-color: CanvasText
• --cem-slider-tick-color: CanvasText
• --cem-workflow-step-completed-indicator-color: Highlight
• --cem-workflow-step-invalid-indicator-color: Mark
• --cem-workflow-connector-default-color: GrayText
• --cem-workflow-connector-completed-color: Highlight

• Disclaimer. Highlight color in Chromium and Firefox do not pass contrast compliance against HighlightText, have to be darkened.

9.2 Forced colors

When @media (forced-colors: active) is true:

• Prefer system colors (Canvas, CanvasText, Highlight, SelectedItem) over authored colors.
• Avoid relying on box-shadow/glow as a sole state indicator (UAs commonly drop or adjust it).
• Use outline/zebra and semantic system colors to preserve state visibility.
• Resolve --cem-separator-color to CanvasText; reduced-alpha authored separators must not disappear after forced color adjustment.
• Resolve progress tracks to GrayText and progress indicators to Highlight; do not depend on authored alpha or hue to distinguish the current arc from the remaining range.
• Resolve slider remaining/disabled graphics to GrayText, active graphics to Highlight, and resting thumbs/ticks to CanvasText; retain positional and focus-outline cues.
• Resolve remaining workflow connectors to GrayText, completed connectors and markers to Highlight, and invalid markers to Mark; keep current navigation fill and focus geometry independent.

10. Component mapping checklist

Use this as a quick “did we wire tokens correctly?” checklist.

10.1 Actions

• Buttons (primary): --cem-action-primary-*
• Buttons (explicit): --cem-action-explicit-*
• Toolbar/menu actions (contextual): --cem-action-contextual-*
• Secondary actions (alternate): --cem-action-alternate-*
• Destructive: --cem-action-destructive-*

10.2 Inputs and selection controls

• Text fields use comfort surface; state uses zebra/underline + readonly/editable/required
• Checkboxes/radios reflect selected and indeterminate distinctly
• Select and autocomplete choice popups use --cem-select-* state pairs and retain zebra focus/open geometry
• Targeted elements (:target) use target zebra strip

10.3 Informational semantics

• Errors use --cem-palette-danger + --cem-palette-danger-text
• Highlights use --cem-palette-trust
• Low-emphasis/disabled uses --cem-palette-conservative

10.4 Separation

• Sibling dividers use --cem-separator-color; readable text continues to use the applicable *-text endpoint
• Divider thickness comes from D5, and divider spacing/inset does not become a D0 token
• Forced-colors dividers resolve to CanvasText rather than relying on the reduced-salience authored mixture
• Forced-colors progress graphics resolve their track/indicator pair to GrayText / Highlight
• Sliders use --cem-slider-*; a value-range track is not a separator or progress status graphic
• Workflow status/connectors use --cem-workflow-*; a process path is not a sibling divider or numeric progress graphic

11. Accessibility and QA

11.1 Contrast requirements (normative)

11.2 QA checklist (done-ness)

• Verify theme switching (light/dark/contrast/native) does not change semantics (only mappings).
• Verify all action intents have complete fill/ink endpoints (default/hover/active/disabled) and independent selected zebra.
• Verify zebra focus/selection/target remains visible across surfaces and in forced-colors.
• Verify pending is perceivable without relying on hue alone (may require motion per D7).
• Verify color-blind resilience: state remains distinguishable via outline/pattern/label/shape.

Minimum QA expectations:

• Contrast: text-on-background combinations MUST meet your target WCAG level for the corresponding text size.
• Focus visibility: keyboard focus MUST be detectable without color-fill changes (zebra/outline required).
• Forced-colors: verify key flows with forced-colors enabled (Windows High Contrast / similar).
• Color-blindness: verify that state is still perceivable via non-hue channels (outline thickness, pattern, marker).

11.3 Color-blind resilience and redundancy (normative)

• Meaning MUST NOT rely on hue alone. Any state with user impact (error, destructive, focus, selection, pending) MUST also be conveyed via at least one of:
  • text (label or status copy)
  • iconography
  • outline/pattern (e.g., zebra ring), or
  • shape/position change (where appropriate).
• Implementations SHOULD test common color-vision deficiencies (e.g., deuteranopia and protanopia) and verify that state progression remains distinguishable.

11.4 Motion sensitivity (normative)

• Theme transitions and state transitions SHOULD respect prefers-reduced-motion (see D7).
• Instant color changes are acceptable; animated gradients and long “breathing” color loops SHOULD NOT be required to understand state.

12. Implementation guidance

12.1 Recommended layering: branded → emotional → action

Implementations SHOULD preserve the three-layer model:

1. Branded hues (--cem-color-*) — implementation substrate (brand-controlled)
2. Emotional palette (--cem-palette-*) — semantic contract (theme-adaptive via light-dark())
3. Action intents (--cem-action-*) — product-facing API (derived state progression via color-mix())

12.2 Derivation pattern (illustrative CSS)

:root {
  /* Emotional palette (example) */
  --cem-palette-creativity:        light-dark(var(--cem-color-purple-l), var(--cem-color-purple-d));
  --cem-palette-creativity-x:      light-dark(var(--cem-color-purple-d), var(--cem-color-purple-l));
  --cem-palette-creativity-text:   light-dark(var(--cem-palette-comfort-text), var(--cem-palette-comfort-text));
  --cem-palette-creativity-text-x: light-dark(var(--cem-palette-comfort-text-x), var(--cem-palette-comfort-text-x));

  /* Primary intent mapped to creativity */
  --cem-action-primary-default-background: var(--cem-palette-creativity);
  --cem-action-primary-default-text:       var(--cem-palette-creativity-text);

  --cem-action-primary-hover-background: color-mix(in srgb, var(--cem-palette-creativity) 70%, var(--cem-palette-creativity-x));
  --cem-action-primary-hover-text:       var(--cem-palette-creativity-text);

  --cem-action-primary-active-background: color-mix(in srgb, var(--cem-palette-creativity) 25%, var(--cem-palette-creativity-x));
  --cem-action-primary-active-text:       var(--cem-palette-creativity-text-x);
}

@media (forced-colors: active) {
  :root {
    --cem-palette-comfort: Canvas;
    --cem-palette-comfort-text: CanvasText;
    --cem-palette-trust: color-mix(in srgb, Highlight 70%, black);
    --cem-palette-trust-text: HighlightText;
  }
}

12.3 Framework mapping (conceptual)

12.4 Test focus: “semantic survives adapters”

In addition to contrast, validate that semantic meaning remains stable across:

• light/dark
• contrast-light/contrast-dark
• forced-colors: active
• density modes (D2), where reduced whitespace increases the importance of outlines/markers.

13. Governance and versioning

Treat as breaking (major):

• Renaming/removing any --cem-palette-*, --cem-action-*, --cem-zebra-*, or --cem-separator-* canonical endpoint.
• Changing the semantic meaning of any endpoint (e.g., swapping “trust” and “danger”).
• Changing the intent↔emotion mapping used for action defaults (e.g., primary no longer mapping to trust).
• Changing the meaning or ordering of canonical states (e.g., redefining active to be less emphasized than hover).
• Reducing contrast below the normative thresholds stated in §11.1.

Treat as non-breaking (minor/patch):

• Adjusting reference hex values of --cem-color-* while preserving semantics.
• Adding new optional endpoints with clear scope.
• Clarifying mapping guidance.

14. Canonical token summary

14.1 Required (product contract)

Emotional palette (minimum set):

• --cem-palette-comfort, --cem-palette-comfort-text
• --cem-palette-trust, --cem-palette-trust-text
• --cem-palette-danger, --cem-palette-danger-text
• --cem-palette-conservative, --cem-palette-conservative-text

Zebra (outline/pattern channel):

• --cem-zebra-color-0, --cem-zebra-color-1, --cem-zebra-color-2, --cem-zebra-color-3
• --cem-zebra-strip-size
• --cem-select-popup-*, --cem-select-option-*

Actions (per shipped intent):

For each shipped intent (primary, explicit, contextual, alternate, destructive), the implementation MUST provide at least:

• --cem-action-{intent}-default-background, --cem-action-{intent}-default-text
• --cem-action-{intent}-hover-background, --cem-action-{intent}-hover-text
• --cem-action-{intent}-active-background, --cem-action-{intent}-active-text
• --cem-action-{intent}-disabled-background, --cem-action-{intent}-disabled-text
• Persistent selected zebra using --cem-zebra-color-3 and D5 geometry; no separate selected fill/text tokens are required.

Navigation items:

• --cem-navigation-item-default-{background,text}
• --cem-navigation-item-hover-{background,text}
• --cem-navigation-item-active-{background,text}
• --cem-navigation-item-current-{background,text}
• --cem-navigation-item-current-hover-{background,text}
• --cem-navigation-item-current-active-{background,text}
• --cem-navigation-item-disabled-{background,text}

Interactive content:

• --cem-content-interaction-default-{background,text}
• --cem-content-interaction-hover-{background,text}
• --cem-content-interaction-active-{background,text}
• --cem-content-interaction-selected-{background,text}
• --cem-content-interaction-selected-hover-{background,text}
• --cem-content-interaction-selected-active-{background,text}
• --cem-content-interaction-disabled-{background,text}

Separation:

• --cem-separator-color

Workflow steps:

• --cem-workflow-step-{completed,invalid}-indicator-color
• --cem-workflow-connector-{default,completed}-color

14.2 Recommended (implementation substrate)

• Branded hues: --cem-color-* (brand-controlled; used to derive palette tokens)
• Palette extremes: --cem-palette-*-x, --cem-palette-*-text-x (required if using formulaic color-mix() state progression)
• Additional emotions: --cem-palette-calm, --cem-palette-enthusiasm, --cem-palette-creativity (recommended where the product uses the corresponding semantics)
• Additional action states (recommended where applicable): readonly, editable, required, indeterminate, focus, target, pending

14.3 Token manifest index

Token tier is encoded in the tier column of each source table. The manifest validator derives expected token names from these tables using the same logic as cem-colors.html.

15. References

Internal

• Action states and visual priority order (EPA-WG custom-element-dist discussion #14): https://github.com/EPA-WG/custom-element-dist/discussions/14

External

• WCAG 2.2 — Focus Appearance (Minimum): https://www.w3.org/WAI/WCAG22/Understanding/focus-appearance.html
• WCAG 2.1 — Contrast (Minimum): https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html
• MDN: color-mix(): https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/color-mix
• MDN: light-dark(): https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/light-dark
• MDN: forced-colors: https://developer.mozilla.org/en-US/docs/Web/CSS/@media/forced-colors
• Material Design 3 — Color system overview: https://m3.material.io/styles/color/overview

This spec is the canonical D0 contract for CEM color semantics.