Colors
Semantic colors and the light and dark themes.
Draft
The values and key names shown here are conceptual and may change.
ThemeColors is the semantic layer. It names colors by role instead of by hue, so components ask for “the border color” and not “gray 200”.
Each color points to a step of the palette. The roles stay the same in both themes; only the step they point to changes.
Colors are grouped into six roles:
| Role | Answers the question |
|---|---|
background | What is this surface painted with? |
content | What color is the text or icon on it? |
border | What outlines or separates it? |
primary | What color are the main actions? |
highlight | What carries the brand highlight? |
feedback | What state is it communicating? |
export type ThemeColors = {
background: {
default: string;
subtle: string;
elevated: string;
inverse: string;
};
content: {
default: string;
muted: string;
subtle: string;
disabled: string;
inverse: string;
link: string;
};
border: { default: string; subtle: string; strong: string; focus: string };
primary: { default: string; pressed: string; subtle: string; on: string };
highlight: { default: string; subtle: string; on: string };
feedback: {
info: string;
infoSubtle: string;
success: string;
successSubtle: string;
warning: string;
warningSubtle: string;
error: string;
errorSubtle: string;
};
};background
Surfaces, from the screen itself to whatever floats above it. The keys describe depth, not components: a card and a bottom sheet both use elevated.
defaultis the base of a screen.subtlesets grouped content apart, like iOS grouped lists. Putelevatedsurfaces on top of it.elevatedis for anything above the screen: cards, sheets, dialogs, menus. In dark mode it is lighter thandefault, since shadows are barely visible on black.inverseflips the scheme for short, high-contrast messages. Pair it withcontent.inverse.
content
Text and icons. The keys go from most to least emphasis, so each piece of text picks a level of importance rather than a gray.
defaultis for titles, body text and icons.mutedis for supporting text: descriptions, secondary lines of an item, timestamps.subtleis for placeholders and captions. Keep it off text the user has to read.disabledis only for disabled controls.inversegoes onbackground.inverse.linkmarks tappable text.border.focusandfeedback.infouse the same hue.
Contrast
default and muted are meant for readable text on default, subtle and
elevated backgrounds. Check contrast again when you change these steps.
border
Outlines and separators. Most borders use default; the other keys change the weight or signal an interaction.
defaultoutlines inputs and cards and draws separators between list items.subtledivides content inside a surface that already has an outline.strongis for controls that need to stay visible when empty: an unchecked checkbox or radio.focusshows the focused input or the selected item.
primary
The color of the main actions: solid buttons, the floating button, selected chips and tabs, and checked switches, checkboxes, radios and sliders. Change it to brand your actions without touching surfaces or text.
defaultis the fill of an action or a checked control.pressedreplacesdefaultwhile the action is held.subtleis a tinted background related to the primary action.onis the text and icon color that sits ondefault.
By default, primary points to the neutral ramp: black actions in light mode, white in dark mode, as Axiom always shipped. To brand the actions, point it to another hue:
export const lightColors = {
// …
primary: {
default: palette.indigo[500],
pressed: palette.indigo[600],
subtle: palette.indigo[50],
on: "hsla(0, 0%, 100%, 1)",
},
} satisfies ThemeColors;In dark mode, use a lighter step (400 for default, 300 for pressed, 950 or 900 for subtle), and pick the on color that keeps a contrast of at least 4.5:1 on default.
highlight
The brand highlight — the one saturated color that is neither an action nor a state. It is a fill, not a text color: put on on top of default, never default on a light surface.
defaultis the filled highlight: a featured badge, a promoted card, a rating.subtleis the tinted version, for a background that carriescontent.defaulttext.onis the text and icon color that sits ondefault. It stays dark in both themes, because the highlight stays light in both.
Unlike the other roles, highlight keeps the same palette step in light and dark: yellow at step 500 is already light enough to read against black, and dimming it would cost the brand its recognition.
Three brand colors
primary is for actions, highlight for what you want noticed, and
content.link for links. Earlier versions called the highlight accent:
rename colors.accent to colors.highlight and the Badge accent variant
to highlight.
feedback
States the user must notice: information, success, warning and error. Each state has two keys:
- the base key (
error) for icons, text, fills and destructive actions; - the
Subtlekey (errorSubtle) for the tinted background behind that message.
Put base text on its own Subtle background, as in an Alert. Don’t rely on color alone: pair a feedback color with an icon or a label.
light and dark
Axiom ships two complete themes, light and dark. Both implement the same ThemeColors contract with different steps:
export const lightColors = {
background: {
default: "hsla(0, 0%, 100%, 1)",
subtle: palette.gray[50],
elevated: "hsla(0, 0%, 100%, 1)",
inverse: palette.gray[950],
},
content: { default: palette.gray[950], muted: palette.gray[600] /* … */ },
border: { default: palette.gray[200] /* … */ },
feedback: { error: palette.red[500], errorSubtle: palette.red[50] /* … */ },
} satisfies ThemeColors;
export const darkColors = {
background: {
default: "hsla(0, 0%, 0%, 1)",
subtle: palette.gray[950],
elevated: palette.gray[900],
inverse: palette.gray[50],
},
content: { default: palette.gray[50], muted: palette.gray[400] /* … */ },
border: { default: palette.gray[800] /* … */ },
feedback: { error: palette.red[400], errorSubtle: palette.red[950] /* … */ },
} satisfies ThemeColors;In dark mode, feedback and link colors use a lighter step (400 instead of 500) so they stay readable on dark surfaces.
The names match the conventions of each styling tool:
| Variant | How the names are used |
|---|---|
stylesheet | light / dark objects picked by a useTheme() hook based on useColorScheme |
unistyles | Registered as adaptive themes |
nativewind | Tailwind names (bg-primary, text-content-muted) from theme/nativewind.css and its preset |
uniwind | Tailwind names (bg-primary, text-content-muted) from theme/uniwind.css |
In nativewind and uniwind, each color is a CSS variable with a light and a dark value, so a class follows the scheme without dark:. The stylesheet, nativewind and uniwind variants follow the system color scheme without a global provider. Add a provider only if you want to force a theme manually.
Customizing
Edit the copied theme files. Because components read component tokens derived from these colors, a change here reaches every component.
To change the brand color of the actions, point primary to another hue. To change the color of links and focus rings, point content.link, border.focus and feedback.info to another hue.