Design Tokens and Variables in shadcncraft
How design tokens are organized into collections changed in v3 of the kit. Not sure which version you have? See how to tell which version you're using.
Collections
v3 organizes every design token into three variable collections. They reference each other in a clear chain: components point at Mode, Mode resolves through Style, and Style is built on Tailwind primitives.
1. Tailwind
A single-mode collection of raw, utility-first primitives that mirror Tailwind's scale. These are the lowest-level values in the system. Nothing references anything beneath them. It replaces the Primitives collection from v2.
| Group | Usage |
|---|---|
spacing | The Tailwind spacing scale: padding, gap and margin values |
border-radius | Corner-radius primitives |
border-width | Stroke-thickness primitives |
font | Type-scale primitives: font size, weight and line height |
width | Width primitives for components and elements |
max-width | Minimum and maximum width constraints |
height | Height primitives for components and elements |
opacity | Transparency steps |
colors | The raw color palette that the Style collection resolves from |
ring-width | Focus-ring thickness primitives |
shadows | Shadow primitives: the raw values behind each shadow |
pro | Primitives specific to the Pro kit |
meta | Kit metadata, such as the library version |
2. Style
Style is the theming heart of v3. It is a multi-mode collection where each mode is a complete, named visual style: color palette, radii, shadows, spacing rhythm, typography and icon set all defined together. shadcncraft ships eight styles out of the box:
- Nova
- Vega
- Maia
- Lyra
- Mira
- Luma
- Sera
- Rhea
Switching the active Style mode re-themes the entire library in one move. The Style collection takes over the role the Theme collection played in v2.
There's no need to learn every variable in here. Work at the group level. Each group is summarized below:
| Group | Usage |
|---|---|
color | Per-style color resolutions for light and dark mode |
icon-library | Boolean toggles for the active icon set (Lucide, Remix, Phosphor, Tabler, Huge) |
font | The sans, serif, mono and heading typefaces |
pro | The Pro spacing scale used for padding, gaps and margins across blocks |
radius | The semantic radius scale (radius/sm … radius/4xl), resolved per style |
shadow | Per-style shadow definitions |
text | The per-style type scale: font size and line height for each step (text-xs … text-9xl) |
focus-ring | The focus-ring token, resolved per style |
component | Per-component tokens such as component/card/radius or component/input/bg |
3. Mode
Mode is the collection you apply to elements. It has two modes, Light and Dark, and its variables alias into the Style collection. A component bound to a Mode color automatically reflects whichever Style is active and whether the page is in light or dark mode.
| Group | Usage |
|---|---|
Root | The core UI colors (primary, background, border, muted, …) |
custom | Figma-specific tokens used to reproduce the shadcn/ui look |
chart | Colors used for charts |
sidebar | Colors specific to the sidebar component |
Color variable usage guide
The meaning of each color is the same across kit versions. Apply these from the Mode collection. Swatches show shadcn/ui's default light theme, which the kit's default style matches.
| Swatch | Color | Usage |
|---|---|---|
primary | Define the color palette used for your theme | |
primary-foreground | For elements on top of primary | |
secondary | Your secondary brand color | |
secondary-foreground | For elements on top of secondary | |
accent | Highlight color for active or focused elements | |
accent-foreground | For elements on top of accent | |
background | Main application background color | |
foreground | For elements on top of background | |
card | Background color for cards | |
card-foreground | For elements on top of card | |
popover | Background color for things like select menus | |
popover-foreground | For elements on top of popover | |
muted | Subtle background for elements requiring less attention | |
muted-foreground | For elements on top of muted | |
destructive | For errors and destructive actions like delete | |
destructive-foreground | For elements on top of destructive | |
border | Main border color | |
input | Border color for form input elements | |
ring | Helps define the focus indicator | |
custom/focus | The soft outer focus ring on focused elements like buttons | |
custom/destructive-focus | The soft outer focus ring on focused elements like destructive buttons | |
bg-input-30 | Used for the background of elements like input to increase contrast in dark mode. More info here | |
bg-input-50 | Used in the backgrounds of elements on hover like Combobox | |
bg-input-80 | Used for input element background like Switch |
Tokens like custom/focus and bg-input-* are shadcncraft additions that reproduce shadcn/ui's look. They have no direct shadcn CSS token, so no swatch is shown.
Best practices
- Apply Mode variables to elements. Never apply Style or Tailwind variables directly.
- Theme by switching or editing the Style collection, not by editing individual component colors.
- Reach for Tailwind primitives only for raw spacing, sizing and radius values.
- Use variables instead of hard-coded values so designs stay aligned with shadcn/ui and translate cleanly to Tailwind CSS.
