# Variables

> The shadcn/ui kit for Figma comes pre-configured with a comprehensive set of variables for colors, spacing, radius, typography, and widths. These variables ensure consistency and flexibility in your designs, and let a single file carry all 8 shadcn/ui styles.

Canonical: https://www.shadcndesign.com/docs/variables

The shadcn/ui kit for Figma comes pre-configured with a comprehensive set of variables for colors, spacing, radius, typography, and widths. These variables ensure consistency and flexibility in your designs.

Our UI kit leverages [Figma variables](https://help.figma.com/hc/en-us/articles/15339657135383-Guide-to-variables-in-Figma) and [styles](https://help.figma.com/hc/en-us/articles/360039238753-Styles-in-Figma) to mirror the official shadcn/ui framework, which is based on [Tailwind CSS](https://tailwindcss.com/docs/styling-with-utility-classes) v4.

## One file, 8 styles

The kit ships **all 8 shadcn/ui styles in a single file** — Nova, Vega, Mira, Luma, Sera, Maia, Rhea, and Lyra. Switching the active style restyles the entire file: heights, paddings, radius ramps, text sizes, shadows, focus rings, and border treatments all update at once. Four variable collections make that possible: `Tailwind`, `Style`, `Mode`, and `Typeset`.

## Variable collections

The **Basic version** of the UI kit organizes variables into four collections that control different aspects of your design system. The **Pro version** (with Pro Blocks) adds a `pro-blocks/*` variable group inside the Style collection.

| Collection | Modes                                              | What it holds                                                                                                                                                                                                  |
| ---------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Tailwind` | Value                                              | Tailwind CSS primitives: the raw color palette, spacing, radius, widths, opacity, line-height, and more.                                                                                                       |
| `Style`    | Nova, Vega, Mira, Luma, Sera, Maia, Rhea, Lyra (8) | Everything that differs per style: the light/dark color source, fonts, radius ramp, type scale, shadows, per-component structure values, and icon-library switches. Change the mode to restyle the whole file. |
| `Mode`     | Light, Dark                                        | The shadcn/ui semantic tokens with their exact CSS names, plus alpha helpers and the semantic `custom/*` tokens. Use these directly in your designs.                                                           |
| `Typeset`  | 14px, 15px, 16px, 18px                             | The prose/markdown system that mirrors shadcn's typeset.css. See the [Typeset documentation](/docs/typeset).                                                                                                   |

### How the collections resolve

Colors flow through the collections in a one-way chain — each layer only ever points at the next:

- **Kit components bind `component/*` variables** in the Style collection (`component/input/bg`, `component/badge/text`, …). This per-component layer is what lets one component diverge per style without touching any other.
- **`component/*` values alias Mode tokens** (`background`, `primary`, `custom/field`, …). The Mode collection is a pure switch: Light points at the Style collection's `color/light/*` definitions, Dark at `color/dark/*`. No color values live in Mode itself.
- **The Style collection is the only place colors are defined.** Each `color/light/{token}` + `color/dark/{token}` pair holds the value per style — usually an alias into the Tailwind palette, sometimes a raw value.

In your own designs, bind **Mode tokens** (including `custom/*`) — they carry the exact shadcn/ui CSS names, and the active Style mode plus the Light/Dark switch do the rest. In practice: bind a field surface to `custom/field`, and switching the frame's Style mode or Light/Dark mode recolors it correctly — no manual work.

### 1. Tailwind

The Tailwind collection contains standard Tailwind CSS colors and utility primitives. It has a single value mode and rarely needs editing directly — it's the palette everything else references.

**Use Tailwind variables to:**

- Reference Tailwind colors from the Style collection's color pairs
- Apply Tailwind colors directly to components
- Control component spacing, widths, radius, and border width
- Set opacity values

| Variable Group         | Usage                                                                                         | Example                                                                            |
| ---------------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `colors/{hue}/{shade}` | The standard Tailwind color palette (26 hues × 11 shades, plus black, white, and transparent) | Elements using `colors/blue/500` will use `text-blue-500` or `bg-blue-500` in code |
| `spacing/*`            | Apply to padding, margins, and gaps                                                           | A component with `spacing/4` in padding maps to the `p-4` class in code            |
| `rounded/*`            | Apply rounded corners — each step aliases the active style's `radius/*` ramp in the Style collection | An element with `rounded/lg` maps to `rounded-lg` in code                          |
| `border-width/*`       | Set border thickness                                                                          | An element with `border-width/2` maps to `border-2` in code                        |
| `min-width/*`          | Set minimum width constraints                                                                 | An element with `min-width/min-w-3xs` maps to `min-w-3xs` in code                  |
| `max-width/*`          | Set maximum width constraints                                                                 | An element with `max-width/max-w-3xl` maps to `max-w-3xl` in code                  |
| `opacity/*`            | Control transparency                                                                          | An element with `opacity/opacity-70` maps to `opacity-70` in code                  |
| `stroke-width/*`       | Icon and vector stroke widths                                                                 | Used inside icon components                                                        |
| `ring-width/*`         | Focus-ring widths                                                                             | Referenced by the Style focus-ring values                                          |
| `breakpoint/*`         | Define breakpoints                                                                            | A frame with `breakpoint/sm` in max width defines styling for the `sm:…` prefix    |

### 2. Style

The Style collection is the heart of the kit. It has **eight modes** — one per shadcn/ui style — and holds everything that differs between them. Switch the mode on a page or frame (or set the file default) to restyle everything bound to it.

This is also where you **recolor a theme**: edit the `color/light/*` and `color/dark/*` pairs. See the [theming documentation](/docs/theming) for the full workflow.

| Variable Group                                     | Purpose                                                                                                                                                                                                                                                       |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `color/light/{token}` + `color/dark/{token}`       | The theme source — the **only place colors are defined**. Includes the shadcn semantic tokens, every `custom/*` definition, and the `alpha/*` ramp. Each pair feeds one Mode token; recolor your theme here rather than binding these to components directly. |
| `font/family/{sans,serif,mono,heading}`            | Typefaces for the whole file. Change once, applies everywhere.                                                                                                                                                                                                |
| `radius/{xs…4xl}`                                  | The per-style radius ramp (Sera and Lyra are square; Luma and Maia are round). Components reference it through the Tailwind collection's `rounded/*` aliases.                                                                                                  |
| `text/*`                                           | The per-style type scale: size and default line-height per ramp step, plus computed `lh-tight`…`lh-loose` steps matching Tailwind's `leading-*` scale.                                                                                                        |
| `font-weight/{thin…black}`                         | The font-weight scale, referenced by text styles and per-component weight values.                                                                                                                                                                             |
| `container/*` + `breakpoint/*`                     | Container widths (3xs–7xl) and responsive breakpoints matching Tailwind's scale.                                                                                                                                                                              |
| `shadow/*`, `inset-shadow/*`, `drop-shadow/*`, `blur/*` | Effect primitives and per-component shadow slots, referenced by the kit's effect styles (along with `focus-ring/width`).                                                                                                                                  |
| `component/{name}/*`                               | Structural values (heights, paddings, gaps, radii, border widths) **and per-component color bindings** that alias Mode tokens — the layer the kit's components are actually bound to.                                                                         |
| `icon-library/{lucide,huge,phosphor,tabler,remix}` | Boolean switches for the active icon set — set exactly one to `true`. See the [icons documentation](/docs/icons).                                                                                                                                             |
| `pro-blocks/{desktop,mobile}/*`                    | Layout values for the Landing Page Pro Blocks (Pro version only).                                                                                                                                                                                             |
| `meta/style-name`                                  | The name of the active style, for reference.                                                                                                                                                                                                                  |
| `meta/version`                                     | A hidden marker identifying the kit version. It powers the plugin's auto-detection — never edit it.                                                                                                                                                           |

#### Pro Blocks variables (Pro version)

The `pro-blocks/*` group inside the Style collection provides the layout and typography values used by the Landing Page Pro Blocks. Variables are split into `pro-blocks/desktop/*` and `pro-blocks/mobile/*` so you can define distinct values per breakpoint, and you can use them as a foundation for your own section styles.

| Variable                          | Description                                                                                          |
| --------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `container-padding-x`             | X-axis padding for Pro Block containers (desktop and mobile)                                         |
| `section-padding-y`               | Y-axis padding for Pro Block sections (desktop and mobile)                                           |
| `section-title-gap-{sm,md,lg,xl}` | Y-axis gap for section-title wrappers, one per heading size (desktop)                                |
| `heading-{sm,md,lg,xl}/*`         | Typography for the Pro Blocks heading styles: `font-size`, `line-height`, `letter-spacing`, and `font-weight` per heading size (desktop and mobile) |

### 3. Mode

The Mode collection holds the shadcn/ui semantic color tokens that switch between light and dark. **Use these directly in your UI designs and components.** They carry the exact CSS variable names from shadcn/ui, so the mapping to code is one-to-one. The collection holds no color values of its own — every token aliases its `color/light/*` or `color/dark/*` definition in the Style collection, making Mode a pure light/dark switch.

Use alpha variables for fills and strokes that need transparency.

| Variable Group  | Usage                                                                                              | Example                                                                             |
| --------------- | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| Semantic tokens | Flat shadcn/ui color variables                                                                     | A frame with the `background` variable maps to `bg-background` in code              |
| `alpha/*`       | Transparent overlay steps: `alpha/5`, `10`, `20`, `30`, `40`, `50`, `60`, `80`, `90`               | A fill using `muted` plus `alpha/90` maps to `bg-muted/90` in code                  |
| `custom/*`      | Semantic helper tokens for states and surfaces shadcn builds with utility combinations (see below) | A field surface using `custom/field` maps to the recipe in its variable description |

#### Semantic color tokens

Each semantic token has a specific purpose in shadcn/ui:

| Variable                     | Purpose                                                        |
| ---------------------------- | -------------------------------------------------------------- |
| `background`                 | Main application background                                    |
| `foreground`                 | Primary text color on the background                           |
| `card`                       | Card component background                                      |
| `card-foreground`            | Text and icons within cards                                    |
| `popover`                    | Background for dropdown menus and popovers                     |
| `popover-foreground`         | Text and icons within popovers                                 |
| `primary`                    | Brand color for primary actions (buttons, highlights)          |
| `primary-foreground`         | Text and icons on primary-colored elements                     |
| `secondary`                  | Less prominent action color                                    |
| `secondary-foreground`       | Text and icons on secondary-colored elements                   |
| `muted`                      | Subdued background for less important elements                 |
| `muted-foreground`           | De-emphasized text (captions, labels)                          |
| `accent`                     | Highlight color for active or focused elements                 |
| `accent-foreground`          | Text and icons on accent-colored elements                      |
| `destructive`                | Error and deletion action color                                |
| `border`                     | Default border color                                           |
| `input`                      | Form input and button borders                                  |
| `ring`                       | Focus indicator color                                          |
| `ring-offset`                | Focus ring offset color (matches the surface the ring sits on) |
| `chart-1` through `chart-5`  | Data visualization colors                                      |
| `sidebar`                    | Sidebar background                                             |
| `sidebar-foreground`         | Text and icons within the sidebar                              |
| `sidebar-primary`            | Primary actions within the sidebar                             |
| `sidebar-primary-foreground` | Text on sidebar primary elements                               |
| `sidebar-accent`             | Highlighted elements within the sidebar                        |
| `sidebar-accent-foreground`  | Text on sidebar accent elements                                |
| `sidebar-border`             | Sidebar divider lines or borders                               |
| `sidebar-ring`               | Focus indicators within the sidebar                            |

#### Semantic custom tokens

shadcn/ui builds many states and surfaces out of utility combinations rather than single tokens — for example a disabled field is `disabled:bg-input/50 dark:disabled:bg-input/80`. The kit captures those combinations as **semantic `custom/*` tokens** so you can bind one variable and get the correct value in every style and both modes. The recipes below show the Nova defaults — where a style diverges (for example Sera's transparent fields), the per-style recipe is in the variable's description in Figma.

| Token                                 | Purpose                                               | Code recipe                                                               |
| ------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------- |
| `custom/field`                        | Input, textarea, and select surface                   | `dark:bg-input/30`                                                        |
| `custom/control`                      | Outline button and bordered trigger surface           | `bg-background dark:bg-input/30`                                          |
| `custom/control-hover`                | Outline button/trigger hover surface                  | `hover:bg-muted dark:hover:bg-input/50`                                   |
| `custom/field-border`                 | Resting field border                                  | `border-input`                                                            |
| `custom/field-disabled`               | Disabled field wash                                   | `disabled:bg-input/50 dark:disabled:bg-input/80`                          |
| `custom/switch-track`                 | Switch unchecked track                                | `data-unchecked:bg-input dark:data-unchecked:bg-input/80`                 |
| `custom/muted-hover`                  | Ghost button hover                                    | `hover:bg-muted dark:hover:bg-muted/50`                                   |
| `custom/muted-subtle`                 | Subtle muted wash (card footer, table row hover)      | `bg-muted/50`                                                             |
| `custom/selected-wash`                | Selected/checked row background                       | `has-data-checked:bg-primary/5 dark:has-data-checked:bg-primary/10`       |
| `custom/primary-muted`                | Subtle primary tint (selected rows, kbd)              | `bg-primary/5 dark:bg-white/10`                                           |
| `custom/primary-border`               | Checked-control border (switch, checkbox)             | `border-primary/30 dark:border-primary/20`                                |
| `custom/destructive-muted`            | Tinted destructive button/badge background            | `bg-destructive/10 dark:bg-destructive/20`                                |
| `custom/destructive-muted-hover`      | Hover for tinted destructive elements                 | `hover:bg-destructive/20 dark:hover:bg-destructive/30`                    |
| `custom/destructive-muted-foreground` | Secondary destructive text                            | `text-destructive/90`                                                     |
| `custom/destructive-border`           | Invalid/destructive field border                      | `aria-invalid:border-destructive dark:aria-invalid:border-destructive/50` |
| `custom/destructive-ring`             | Invalid focus ring                                    | `aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40`  |
| `custom/focus-ring`                   | Focus halo color (alpha varies per style)             | `ring-ring/50`                                                            |
| `custom/menu-border`                  | Hairline border on menus, cards, popovers             | `ring-1 ring-foreground/10`                                               |
| `custom/menu-glass`                   | Frosted menu background                               | `bg-popover/70 backdrop-blur-2xl`                                         |
| `custom/warning-foreground`           | Warning text (amber — no shadcn warning token exists) | Amber foreground                                                          |
| `custom/warning-background`           | Warning surface                                       | Amber background                                                          |
| `custom/warning-border`               | Warning border                                        | Amber border                                                              |

<Callout type="info">
  The kit ships 60 `custom/*` tokens in total. Beyond the ones listed above,
  they cover component details — hovers (`primary-hover`, `secondary-hover`,
  `tinted-hover`, `bubble-outline-hover`, `bubble-ghost-hover`,
  `badge-text-hover-muted`), controls and menus (`control-border`,
  `control-strong`, `control-wash`, `menu-border-subtle`, `menu-border-faint`,
  `menu-separator`), rings (`ring-faint`, `focus-ring-soft`, `ring-chart`,
  `ring-chart-strong`), washes and overlays (`overlay`, `kbd-overlay`,
  `foreground-wash`, `muted-foreground-wash`, `border-soft`, `tinted`,
  `selected-wash`), per-component tokens (`accordion-active-bg`,
  `active-tab-border`, `calendar-surface`, `calendar-accent`, `slider-thumb`,
  `toggle-group-shadow`, `track-strong`, `drawer-border`, and the switch
  family), and extra destructive variants (`destructive-strong`,
  `destructive-wash`, `destructive-border-soft`, `destructive-border-strong`).
  Each carries its exact utility recipe in its Figma description.
</Callout>

### 4. Typeset

The Typeset collection powers the prose/markdown system and has four size modes (14px, 15px, 16px, 18px). It's covered in full in the [Typeset documentation](/docs/typeset).

### Best practices

- Maintain consistency by using variables rather than hard-coded values.
- Use Mode tokens (including `custom/*`) for anything that should adapt to light/dark and to the active style.
- Recolor themes in the Style collection's `color/light/*` and `color/dark/*` pairs, not on individual components.
- Colors are defined once, in the Style collection's color pairs. Never enter raw color values in the Mode collection or in `component/*` variables — alias down the chain instead.
- When extending the kit, follow the chain: define the color in the Style collection (`color/light/*` + `color/dark/*`), expose it as a Mode token, and bind components to a `component/*` variable that aliases it.
- Reference the right collection for the job:
  - **Tailwind** for the raw palette and utility primitives
  - **Style** for per-style structure, fonts, radius, and the theme color source
  - **Mode** for theme-aware component colors
  - **Typeset** for prose and long-form text

By following these guidelines, your designs will translate cleanly to shadcn/ui and Tailwind CSS.

## Limitations and differences compared to Tailwind CSS

While we've made every effort to translate the Tailwind CSS system into Figma variables, there are inherent limitations in the current Figma implementation. Understanding these differences will help you work more effectively with our UI kit.

### Math equations

**Tailwind CSS:** Uses a spacing variable as a base unit for calculations. For example, `p-4` equals `(--spacing) * 4 = 16px`.

**Figma:** Math operations are not yet supported in Figma variables. As a result, all spacing and size values in our UI kit are implemented as fixed pixel values rather than calculated ones.

### Color spaces

**Tailwind CSS v4:** Uses the OKLCH color space for improved color perception and manipulation.

**Figma:** OKLCH is not yet supported in Figma. Our UI kit uses hex values instead to maintain compatibility while still providing a comprehensive color system. (When you export with our plugin you can still choose OKLCH, HSL, or RGB output — see the [plugin documentation](/docs/plugin).)

### Typography variables

**Tailwind CSS:** Offers leading (line-height) and tracking (letter-spacing) variables with percentage and em-based values.

**Figma:** Percentage values are not currently supported in Figma variables, so the kit pre-computes line-heights to pixels: each type step in the Style collection carries its default line-height (`text/{step}/lh`) plus `lh-tight`…`lh-loose` steps matching Tailwind's `leading-*` scale, already multiplied out per style. Text styles bind these pixel values. Letter-spacing (tracking) remains handled inside text styles.

#### Working with these limitations

Despite these constraints, our UI kit provides a robust design system that closely mirrors Tailwind CSS. When designing:

- Use the predefined spacing variables even though they're fixed values.
- Apply color variables consistently, knowing they'll translate correctly to code.
- Use text styles for typography rather than trying to recreate Tailwind's typography variables directly.

These workarounds ensure your designs translate smoothly to code, even with the current limitations of Figma variables.