Semantic roles
@themvora/core — the colour vocabulary
Semantic roles are the colour vocabulary Themvora guarantees. A theme defines roles — primary, border — not raw palette values, and every adapter maps from this vocabulary rather than from a colour list. That is what lets one theme drive Material UI, Bootstrap and shadcn/ui at once.
1Core roles — 21
Every theme must define all 21. An adapter may assume they are present, so a library page can map any of them without qualification.
Canvas
The page itself: its surface and the text on it.
| Role | CSS variable | Required |
|---|---|---|
background | --theme-color-background | core |
foreground | --theme-color-foreground | core |
muted | --theme-color-muted | core |
mutedForeground | --theme-color-muted-foreground | core |
Surfaces
Elevated or floating regions that sit above the canvas.
| Role | CSS variable | Required |
|---|---|---|
card | --theme-color-card | core |
cardForeground | --theme-color-card-foreground | core |
popover | --theme-color-popover | core |
popoverForeground | --theme-color-popover-foreground | core |
Actions
Interactive roles, each paired with its own contrast colour.
| Role | CSS variable | Required |
|---|---|---|
primary | --theme-color-primary | core |
primaryForeground | --theme-color-primary-foreground | core |
secondary | --theme-color-secondary | core |
secondaryForeground | --theme-color-secondary-foreground | core |
accent | --theme-color-accent | core |
accentForeground | --theme-color-accent-foreground | core |
destructive | --theme-color-destructive | core |
destructiveForeground | --theme-color-destructive-foreground | core |
States
Outcome roles. `success` is core; `warning` / `info` / `error` are capabilities a theme may declare and an adapter may consume.
| Role | CSS variable | Required |
|---|---|---|
success | --theme-color-success | core |
successForeground | --theme-color-success-foreground | core |
warning | --theme-color-warning | optional |
warningForeground | --theme-color-warning-foreground | optional |
info | --theme-color-info | optional |
infoForeground | --theme-color-info-foreground | optional |
error | --theme-color-error | optional |
errorForeground | --theme-color-error-foreground | optional |
Interaction
Structural and focus affordances.
| Role | CSS variable | Required |
|---|---|---|
border | --theme-color-border | core |
input | --theme-color-input | core |
ring | --theme-color-ring | core |
2Optional states — 6
A theme may define these. An adapter that maps one must treat it as optional and fall back, because a theme without them is valid.
warningwarningForegroundinfoinfoForegrounderrorerrorForeground3Reading them from code
Validate an adapter's mapping against the runtime contract.
import { CORE_COLORS, isCoreColor, isOptionalSemantic } from "@themvora/core";
// The full core vocabulary, as the runtime defines it.
CORE_COLORS.length; // 21
// Validate an adapter's mapping against the contract.
isCoreColor("border"); // true
isCoreColor("warning"); // false — optional, not core
isOptionalSemantic("warning"); // true