Colors
This page documents the color foundations for the FDIC design system and the stable public color token contract.
Color tokens use a three-layer model — palette, role, and semantic — so that consumers can choose the right level of abstraction for their context.
The color system is organized in three layers: palette, role, and meaning. Most consumers should reach for role or semantic tokens rather than raw palette values.
Stable public contract
- Stable stylesheet entrypoint:
@jflamb/fdic-ds-tokens/styles.css - Stable color prefixes: palette
--fdic-color-[family]-[step], role--fdic-color-[role]-[variant], and semantic status--fdic-color-semantic-* - Dark mode behavior: semantic role tokens adapt through
light-dark()and the activecolor-scheme
New integrations should treat those names as the supported public API.
Color anatomy
The token inventory defines three practical layers:
- palette tokens for source color families
- role tokens for where color is applied
- semantic tokens for status and meaning
Applying color with tokens
- Does the color carry meaning?
If yes, use a semantic token such as
--fdic-color-semantic-bg-success. - If not, where is it applied?
Choose a role token for
background,text,border, oricon. - Use palette tokens only as source values
Palette tokens define the system. They are not the first choice for most consumers.
Examples of the naming model:
- palette:
--fdic-color-neutral-300 - role:
--fdic-color-text-primary - semantic:
--fdic-color-semantic-bg-error
Color roles
--fdic-color-neutral-*Text, surfaces, borders, and structural UI--fdic-color-primary-*Institutional emphasis, key actions, trust markers--fdic-color-secondary-*Supporting emphasis without semantic meaning--fdic-color-success-*Favorable outcomes, confirmations--fdic-color-warning-*Caution, prevention, review needed--fdic-color-error-*Errors, destructive actions, serious alerts--fdic-color-info-*Informational context, guidance--fdic-color-link-*Hyperlinks and visited state--fdic-color-*-invertedElements on inverted or brand backgrounds--fdic-color-border-input-*Form field borders and interaction statesPalette tokens
Palette tokens are source values for the system. They should be documented visually, but used sparingly in consumer guidance.
Default system backbone
Use the neutral ramp to support text hierarchy, borders, surfaces, and dark-mode mapping.
Institutional emphasis
Use for key actions, official identifiers, and moments where FDIC ownership should be explicit.
Secondary emphasis
Use more sparingly than the primary brand. It should support hierarchy without becoming semantic status color.
Favorable outcomes
Confirmations, successful submissions, and positive status.
Caution and prevention
Review steps, potential issues, and time-sensitive guidance.
Problems and destructive actions
Validation errors, failed operations, and irreversible actions.
Informational context
Guidance, context, and non-urgent information.
Role tokens
Role tokens are the main implementation layer for non-semantic UI.
Surface and emphasis
Background tokens describe where color sits: base surface, container surface, or brand surface.
Reading hierarchy
Text tokens should support primary, secondary, inverse, and brand-linked content without weakening readability.
Secondary text
Brand-linked text
Structure and control states
Border tokens define separation, input affordance, and focus visibility.
Supporting emphasis
Icon tokens should align with surrounding text and status cues rather than invent separate meaning.
Role token families:
--fdic-color-bg-*--fdic-color-text-*--fdic-color-icon-*--fdic-color-border-*--fdic-color-overlay-*--fdic-color-effect-*
Interaction states
Role tokens support state suffixes for interactive elements:
Derived from a base role token
--fdic-color-bg-interactive--fdic-color-bg-interactive-hovered--fdic-color-bg-interactive-pressedStandalone state tokens
--fdic-color-bg-selected--fdic-color-bg-readonlySupported state suffixes: -hovered, -pressed, -focused, -disabled, -readonly
Semantic tokens
Semantic tokens are the only color tokens that should carry status meaning.
Your information was submitted.
Use semantic success tokens only when the message communicates a favorable outcome.
Review this section before continuing.
Warnings should help prevent mistakes before they become errors.
There is a problem with this entry.
Errors need explicit recovery guidance, not color alone.
We ask for this information to protect your account.
Informational states should add clarity without reading as success or warning.
Semantic token families:
--fdic-color-semantic-bg-success/ warning / error / info--fdic-color-semantic-fg-success/ warning / error / info--fdic-color-semantic-border-success/ warning / error / info
Use semantic colors to reinforce meaning that is already communicated by labels, headings, helper text, and icons.
Do not use primary or secondary brand colors to imply warning, error, or other status meaning.
Accessibility in color
Colors alone do not make an interface accessible.
When documenting or implementing color usage, preserve these expectations:
- text and interactive states must meet contrast requirements
- status meaning must not rely on color alone
- focus indicators must remain visible against surrounding surfaces
- disabled and muted states must remain understandable without reducing legibility too far
- semantic colors must remain distinct in both default and dark modes
Current validation note:
- token values are authored with contrast targets in mind, but repository component tests do not currently enforce rendered contrast automatically because the shared happy-dom axe run disables
color-contrast - Storybook browser accessibility audits now run against every shipped story in Chromium and fail on rendered contrast violations
- confirm contrast again in real browser contexts after token overrides, dark-mode tuning, or downstream page-level composition changes
Trust and content guidance
This system serves government and financial-sector workflows, so color usage should support clarity and trust.
When semantic colors are used in content:
- pair status colors with text, icons, or labels
- use explicit error, warning, and success wording
- explain sensitive steps with text rather than visual emphasis alone
- avoid decorative color choices that weaken clarity
Modes
The public runtime includes light and dark appearance behavior today.
Use role tokens instead of hard-coded palette values so that:
- the same role token may map to different values by mode
- contrast must hold in every supported mode
- consumers should not hard-code palette values for theme behavior
Neutral surfaces and brand emphasis should feel clear, restrained, and document-oriented.
Dark mode should preserve legibility and focus visibility rather than simply inverting values.
What not to rely on yet
Do not assume:
- component-level color tokens exist unless a component page documents them
- palette tokens are safe substitutes for semantic status roles
- an app-specific alias layer is part of the supported contract
Known gaps
- Semantic hue ramp intermediate steps (200/600/900) are placeholder values pending OKLCH refinement. OKLCH is a perceptually uniform color space that produces evenly spaced lightness ramps without the hue shifts common in sRGB or HSL interpolation.
- Component-level color tokens are deferred.
- Contrast validation for every individual component pairing is still being expanded in component docs and tests.