Colors

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 four roles:

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 };
	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.

• default is the base of a screen.
• subtle sets grouped content apart, like iOS grouped lists. Put elevated surfaces on top of it.
• elevated is for anything above the screen: cards, sheets, dialogs, menus. In dark mode it is lighter than default, since shadows are barely visible on black.
• inverse flips the scheme for short, high-contrast messages. Pair it with content.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.

• default is for titles, body text and icons.
• muted is for supporting text: descriptions, secondary lines of an item, timestamps.
• subtle is for placeholders and captions. Keep it off text the user has to read.
• disabled is only for disabled controls.
• inverse goes on background.inverse and on filled buttons.
• link marks tappable text.

border

Outlines and separators. Most borders use default; the other keys change the weight or signal an interaction.

• default outlines inputs and cards and draws separators between list items.
• subtle divides content inside a surface that already has an outline.
• strong is for controls that need to stay visible when empty: an unchecked checkbox or radio.
• focus shows the focused input or the selected item.

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 Subtle key (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:

The stylesheet variant follows 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, point content.link, border.focus and feedback.info to another hue.

Related

• Palette
• Tokens
• Component tokens