# Color — Required Evidence

Scope: color, theming, contrast, status, emphasis, scientific structures, and the boundary between UI color and data-visualization color.

## Required invariants

- Generated UI uses semantic color tokens. Primitive tokens are allowed in token definitions, approved colourmaps, and reasoning about scale stops—not ordinary component styling.
- Color never carries critical meaning alone. Pair it with text, position, shape, icon, pattern, or another channel.
- Verify contrast on the final rendered background and at final opacity in every required theme.
- UI color rules do not select chart colors. Data marks use the active product or scientific visualization profile.
- Preserve chemical element-to-hue semantics. Dark-mode chemical palettes may adjust luminance and saturation, never elemental meaning.

## UI color model

Fractal product UI is neutral-dominant. Chromatic color is targeted, not decorative.

| Role | Semantic family | Use |
| --- | --- | --- |
| Primary accent | `--accent-*` | Links, selected/primary emphasis, where-to-act cues |
| Secondary accent | `--orange-*` | A real comparator or second-rank callout |
| Brand | `--pink-*` | Logo, welcome, and explicit brand moments |
| Success | `--success-*` | Successful, approved, complete, healthy state |
| Warning | `--warning-*` | Pending, caution, review, expiring state |
| Error | `--error-*` | Failed, blocked, invalid, destructive state |
| Additional family | `--purple-*` | Explicit themed use; not a default UI accent |

Do not add color merely to make an interface less neutral. Blue and orange may express UI hierarchy, but that hierarchy does not carry into chart marks. Do not invent a primary/comparator relationship when the entities are peers.

## Palette authority and synchronization

Fractal owns the shared primitive and semantic color definitions. Applications, Fractal UI, marketing sites, and portals consume the same versioned values. Treat application stylesheets as consumers, not an upstream authority. Preserve consumer-only aliases and explicitly scoped overrides without changing the shared values independently.

Fractal owns these values. Update canonical CSS in resources/tokens/ and synchronize affected package implementations in the same session.

Current semantic mappings take precedence over historical stop-based examples. Preserve explicit surface-boundary scopes and verify actual accessibility.

## Canonical primitive scales

Every family has 11 standard stops: `0`, `50`, and `100` through `900`. The app also supplies the compatibility neutral stop `--grey-750: #373739`.

Exact primitive values live in [the shared palette](../../../shared/colors/primitives.json). Load it when resolving scale values; semantic mappings and selection rules remain below.

Primitive CSS names are `--{family}-{stop}`. The shared palette is the exact reference for scale values; `colors.css` is the downstream CSS implementation.

## Scale roles

| Stop | Role |
| --- | --- |
| `0` | Passive, non-interactive reading background |
| `50` | Interactive or contextual surface |
| `100` | Surface hover or very soft surface boundary |
| `200` | Subtle chromatic border or stronger tinted boundary; neutral borders use derived surface tokens |
| `300` | Disabled or low-contrast supporting tone |
| `400` | Hover for medium chromatic emphasis; large marks; warm hues may be background-only |
| `500` | Default semantic accent/status mark when contrast permits |
| `600` | Strong control or text treatment when required |
| `700` | Pressed/deep treatment and dark-mode chromatic boundary |
| `800` | Deep surface or dark-mode tinted surface |
| `900` | Ink or deepest background |

Stop `0` and stop `50` are not interchangeable: `0` is passive background; `50` is a visible surface or interaction layer.

## Canonical semantic mappings

### Filled tags

Status pills use dedicated semantic tag tokens so their stronger fills do not change alerts or other semantic surfaces. They have no border. Neutral metadata tags remain grey.

| Tokens | Light background / foreground | Dark background / foreground |
| --- | --- | --- |
| `--tag-info-bg` / `--tag-info-fg` | blue-100 / blue-600 | blue-700 / blue-200 |
| `--tag-success-bg` / `--tag-success-fg` | green-100 / green-600 | green-700 / green-200 |
| `--tag-warning-bg` / `--tag-warning-fg` | yellow-100 / yellow-600 | yellow-700 / yellow-200 |
| `--tag-error-bg` / `--tag-error-fg` | red-100 / red-600 | red-700 / red-200 |
| `--tag-neutral-bg` / `--tag-neutral-fg` | bg-surface-2 / fg-secondary | bg-surface-2 / fg-secondary |

The fill is darker than the corresponding 50-stop surface in light mode and lighter than the corresponding 800-stop surface in dark mode. Text must maintain at least 4.5:1 contrast against the final fill. Preserve semantic status mapping and visible labels; do not borrow arbitrary category colors from a reference image.

### Neutral tokens

| Token | Light | Dark |
| --- | --- | --- |
| `--bg-canvas` | grey-0 | grey-900 |
| `--bg-surface-1` | grey-50 | grey-800 |
| `--bg-surface-2` | grey-200 | grey-700 |
| `--bg-surface-3` | grey-400 | grey-600 |
| `--fg-primary` | grey-900 | grey-50 |
| `--fg-secondary` | grey-600 | grey-200 |
| `--fg-tertiary` | grey-500 | grey-300 |
| `--fg-placeholder` | grey-400 | grey-500 |
| `--fg-disabled` | grey-300 | grey-600 |
| `--border-subtle` | grey-200 | grey-700 |
| `--border-default` | grey-300 | grey-600 |
| `--border-strong` | grey-400 | grey-500 |
| `--hover-canvas` | grey-100 | grey-750 |
| `--hover-surface` | grey-100 | grey-700 |
| `--hover-on-surface` | grey-50 | grey-800 |

### Neutral hover contrast

Choose hover from the resting background, not from the control's name. Breadcrumb buttons and transparent dropdown triggers on `--bg-canvas` use `--hover-canvas`; controls on `--bg-surface-1` use `--hover-surface`. Scope the hover token when a transparent control lives on a different surface. Sidebar navigation keeps its navigation-specific tokens.

The app uses `--hover-canvas: var(--grey-100)` in light mode and `var(--grey-750)` in dark mode. Use the exact shared mappings rather than a local intermediate grey. Compare the resting-to-hover contrast in both themes and preserve keyboard focus independently.

### Neutral boundary contrast

Ordinary resting cards, panels, inputs, dropdown triggers, and dividers use the same subtle perceptual strength. Component category does not select a heavier border. Focus, selected, invalid, semantic status, and accessibility-critical boundaries retain their dedicated treatments.

For each boundary:

1. Identify the two immediately adjacent rendered backgrounds. For an internal divider these may be identical.
2. In light mode, choose the darker background; in dark mode, choose the lighter. For the ordered neutral surfaces, this is the higher surface level in either theme.
3. Use that surface's `--border-on-*` token. The border is darker than the reference in light mode and lighter in dark mode. Equal backgrounds yield equal borders; mixed backgrounds do not require equal contrast against both sides.
4. Re-evaluate each nested boundary. A panel's outer border may reference its surroundings, while a divider inside it references the panel fill. Transparent content inherits its actual visible background, not an assumed canvas. Portals need their own surface context.

| Reference surface | Light border | Dark border |
| --- | --- | --- |
| `--bg-canvas` → `--border-on-canvas` | `#E6E6E7` | `#2D2D2F` |
| `--bg-surface-1` → `--border-on-surface-1` | `#E2E2E2` | `#3F3F41` |
| `--bg-surface-2` → `--border-on-surface-2` | `#CFCFD0` | `#535355` |
| `--bg-surface-3` → `--border-on-surface-3` | `#7D7D7F` | `#6A6A6D` |

These are derived semantic colors, not new primitive-scale stops. The calibration is the Oklab lightness difference between light canvas `#FEFEFE` and the approved subtle border `#E6E6E7`: **ΔL = 0.07180142** on the 0–1 scale. Preserve the reference surface's Oklab a/b channels, subtract this difference in light mode and add it in dark mode, then round to sRGB. The light canvas border keeps the exact approved color. Allow 0.002 ΔL rounding tolerance. This is a measurable starting point for visual consistency, not a claim that equal lightness differences guarantee identical perception or WCAG ratios.

The CSS implementation supports `data-fractal-border-surface="canvas|surface-1|surface-2|surface-3"` on a boundary or a group of boundaries sharing a reference. It scopes both `--border-subtle` and its `--border-default` alias without changing the fill. Reset this attribute where the adjacent pair changes; CSS does not infer backgrounds from the DOM. For a single custom border, use the matching `--border-on-*` token directly. Keep the package's focus and semantic state selectors intact.

For example, a canvas input in a surface-2 panel references surface-2; a divider within that panel also references surface-2. A surface-1 panel on canvas references surface-1. Do not use opacity as an approximation: compositing depends on which background paints underneath the border.

For custom or composited neutral backgrounds, derive the border using the same lightness rule from the actual reference and validate it visually in both themes. Chromatic boundaries follow the semantic color rules below. Strong boundaries still require a contrast check against the actual background; these subtle tokens are not intended to satisfy an essential 3:1 outline requirement.

### Chromatic semantic pattern

Blue uses the `accent` prefix; green uses `success`; red uses `error`; yellow uses `warning`. Pink, orange, and purple use their family name.

| Suffix | Light stop | Dark stop | Purpose |
| --- | --- | --- | --- |
| `default` | 500 | 400 | Semantic foreground, icon, or mark |
| `hover` | 400 | 300 | Hover on default treatment |
| `subtle` | 200 | 700 | Subtle semantic border |
| `surface-stroke` | 100 | 700 | Boundary on a tinted surface |
| `surface-hover` | 0 | 700 | Current app mapping; selected rows use separate tokens |
| `surface` | 50 | 800 | Tinted semantic surface |
| `bg` | 0 | 900 | Passive semantic background |

Examples: `--accent-default`, `--success-surface`, `--error-subtle`, `--warning-bg`, `--orange-surface-hover`.

### Primary actions and Axon user messages

The Primary button mappings below apply across domains. Secondary uses a neutral fill; see [shared button variants](../../../shared/primary-actions.md). User-message mappings remain specific to Axon conversational surfaces.

| Token | Light | Dark |
| --- | --- | --- |
| `--button-primary-bg` | blue-400 | blue-600 |
| `--button-primary-hover` | blue-500 | blue-500 |
| `--button-primary-active` | blue-600 | blue-700 |
| `--button-primary-fg` | grey-0 | grey-0 |
| `--accent-link-text` | blue-500 | blue-300 |
| User-message background / border | accent-surface-stroke | button-primary-bg |
| User-message foreground | accent-text | button-primary-fg |

Primary controls use these blue tokens across domains. Choose Secondary for a neutral filled button, including the public website’s main CTA. Text links use `--accent-link-text`: the dark blue-400 accent is suitable for icons but has only 3.71:1 text contrast on grey-900; blue-300 clears 4.5:1. The current app hover mapping deepens the light fill and lightens the dark fill; it takes precedence over older generic stop rules.

### Molecular presentation tokens

3D polymer sequence cartoons use `--molecule-sequence-start` (blue-400 light / blue-300 dark), `--molecule-sequence-middle` (#B83DAF / #D459E8), and `--molecule-sequence-end` (#E07828 / #F0943A). The brighter blue stops compensate for directional shading while following the app's electric blue scale. The middle/end retain the app's saturated presentation hues. These colors encode sequence position and are not an approved quantitative chart palette.

The renderer resolves `--molecule-background` (bg-canvas) and `--molecule-carbon` (grey-300) from the active CSS theme. Update the sequence ramp as well as the background when the theme changes. Oxygen, nitrogen, sulfur, and other element hues keep their scientific identity; never recolor the whole molecule with UI accent colors.

## Surface rules

- A standalone chromatic `surface` or `surface-hover` needs its matching semantic `subtle` or `surface-stroke` 1px border so it reads as a bounded UI surface.
- A stronger left accent may add emphasis but does not replace full containment.
- Nested neutral surfaces on tinted backgrounds need sufficient contrast or an explicit semantic border.
- Shadows do not repair weak surface contrast.
- Dense data marks are exempt from UI surface-border requirements and follow visualization evidence.

## Text and contrast

- Body text requires at least 4.5:1 contrast; large text requires at least 3:1.
- Information-bearing non-text UI marks and boundaries require at least 3:1 where WCAG requires them.
- Disabled content may be lower contrast when it is clearly unavailable and no required information depends on it.
- Never use a primitive merely because its nominal stop usually passes. Measure the actual foreground/background pair.
- Warm 400 stops may be background-only when they cannot reach 3:1 without losing hue identity.

## Data visualization colors

Non-scientific metrics use [product visualization defaults](visualization.md). Scientific plots use the [scientific profile](../../data-visualization/references/scientific-profile.md), even inside a product. Product status colors do not override scientific series. Chart chrome remains neutral; preserve stable category identity, contrast, and non-color cues.

## 2D chemical structure palettes

2D chemical colors encode atomic identity. Choose the palette for the actual background before rendering. Dark mode may lift luminance and saturation, but the element-to-hue mapping never changes.

| Element | Meaning | Light background | Dark background |
| --- | --- | --- | --- |
| C | carbon | `#222222` | `#DDDDDD` |
| H | hydrogen | `#FFFFFF` with dark outline when visible | `#E0E0E0` |
| N | nitrogen / blue | `#3050F8` | `#6F8CFF` |
| O | oxygen / red | `#FF0D0D` | `#FF6868` |
| S | sulfur / yellow | `#FFFF30` | `#F4D44D` |
| P | phosphorus / orange | `#FF8000` | `#FF9F45` |
| F | fluorine / green | `#90E050` | `#9BE36A` |
| Cl | chlorine / green | `#1FF01F` | `#61E461` |
| Br | bromine / dark red-brown | `#A62929` | `#D06A6A` |
| I | iodine / dark purple | `#940094` | `#C96BD4` |
| B | boron / salmon | `#FFB5B5` | `#FFC4C4` |
| Si | silicon / tan | `#F0C8A0` | `#F2CDAA` |

Required:

- Use the renderer's palette configuration when possible; do not recolor output with CSS filters, inversion, hue rotation, blend modes, UI tokens, or chart colourmaps.
- Oxygen remains red, nitrogen blue, sulfur yellow, phosphorus orange, and so on in both themes.
- A black-and-white publication mode may be black-on-light or light-on-dark.
- Style containers, captions, borders, selection, and controls with Fractal tokens; treat the structure as scientific content.
- For unlisted elements, use the renderer's Jmol/CPK mapping instead of inventing a color.

3D molecular cartoons, ribbons, surfaces, and ball-and-stick scenes may use a task-specific theme when atomic identity is not carried solely by color.

## Extending color

Before creating a token, check whether an existing semantic token expresses the purpose. If not, add a semantic token mapped to an existing primitive. Create or modify a primitive scale only when the color system itself lacks the needed hue or role; then load [`color-scale-generation.md`](color/scale-generation.md).

When a scale changes, update the shared primitive palette, `colors.css`, the `fractal-ui` token implementation, and every affected colourmap token reference together. Verify all 11 stops and contrast before completing the change.

## Forbidden outcomes

- Raw primitive tokens in generated component styling when a semantic token applies.
- Arbitrary chart palettes or automatic greyscale charts.
- Decorative UI color with no hierarchy, status, interaction, or brand purpose.
- Element colors in a 2D chemical structure mapped to Fractal or chart tokens.
- Light-mode chemical colors blindly reused when they disappear on a dark background.
- New semantic aliases documented here but absent from the token implementation.

### Nested hover steps

When a highlighted row contains a secondary action, include that action within the row’s hover bounds. Hovering the action reverses the row’s background step to the enclosing region’s resting color: `--bg-canvas` for marketplace add buttons, `--nav-surface` for sidebar pins. Keep the parent row highlighted while the pointer is over the action. Use these semantic backgrounds in both themes; do not hardcode white or use the page canvas inside navigation. Preserve selected-row treatment, disabled states, and keyboard focus rings.

## Neutral keyboard focus

Use `--border-focus` (grey-400 in light and dark themes) for focus indicators. Text fields pair it with `--focus-surface`, a 25% mix of the focus color and transparency, for a soft neutral halo. Keep focus independent of chromatic accent, selection, validation, and status colors. Retain visible keyboard focus and the established component ring geometry.
