Theme variables

Overview

In Tailwind CSS, theme variables are CSS custom properties defined with @theme that control which utility classes exist and store design tokens (colors, spacing, typography, etc.).

In the Style library, these design tokens are built-in as Dart maps — they ship with the library and match Tailwind’s default theme exactly. You don’t need a build step or CSS configuration.

How Style maps Tailwind’s theme

Tailwind CSS	Style library
`@theme { --color-sky-500: ... }`	Built-in color map in `tokens/colors.dart`
`@theme { --spacing: 0.25rem }`	Built-in spacing scale in `tokens/spacing.dart`
`@theme { --radius-lg: 0.5rem }`	Built-in radii map in `tokens/radii.dart`
`@theme { --shadow-md: ... }`	Built-in shadow map in `tokens/shadows.dart`
`@theme { --font-sans: ... }`	Built-in font family map
`@theme { --breakpoint-sm: 40rem }`	Built-in breakpoints in the responsive system

The class strings are identical — bg-sky-500, p-4, rounded-lg, shadow-md — they just resolve from Dart maps instead of CSS variables.

Default design tokens

Spacing

The spacing scale uses a 4px base unit, matching Tailwind’s default:

Class	Value
`p-0`	0px
`p-1`	4px
`p-2`	8px
`p-3`	12px
`p-4`	16px
`p-5`	20px
`p-6`	24px
`p-8`	32px
`p-10`	40px
`p-12`	48px
`p-16`	64px

Border radius

Class	Value
`rounded-none`	0px
`rounded-xs`	2px
`rounded-sm`	4px
`rounded`	4px
`rounded-md`	6px
`rounded-lg`	8px
`rounded-xl`	12px
`rounded-2xl`	16px
`rounded-3xl`	24px
`rounded-4xl`	32px
`rounded-full`	9999px

Breakpoints

Prefix	Min width
`sm:`	640px
`md:`	768px
`lg:`	1024px
`xl:`	1280px
`2xl:`	1536px

Arbitrary values

When you need a value outside the default theme scale, use square bracket notation:

// Custom spacing
Style('p-[13px]', child: ...)

// Custom color
Style('bg-[#316ff6]', child: ...)

// Custom size
Style('w-[200px]', child: ...)

This matches Tailwind’s arbitrary value syntax exactly.

Custom properties

Tailwind v4’s utility-(--var) syntax is shorthand for utility-[var(--var)] — an arbitrary value resolved against a CSS custom property instead of written literally. Style supports the theme-defined subset via StyleThemeData.customProperties: define the property (with its leading --) and every utility that already accepts [...] gains (--var) for free.

StyleTheme(
  data: StyleThemeData(
    customProperties: {'--brand-padding': '1.5rem'},
  ),
  child: Style('p-(--brand-padding)', child: ...), // same as p-[1.5rem]
)

See Custom themes for the full API, including the typed-hint form and merge semantics.

Custom themes

Override any design token using the StyleTheme widget:

StyleTheme(
  data: StyleThemeData(
    colors: {'brand': {500: Color(0xFF316FF6), 700: Color(0xFF1D4ED8)}},
    spacing: {'4': 20},
  ),
  child: Style(
    'bg-brand-500 hover:bg-brand-700 text-white p-4 rounded-lg',
    child: Text('Custom themed'),
  ),
)

Nested themes merge with StyleTheme.merge:

StyleTheme.merge(
  data: StyleThemeData(spacing: {'4': 32}),
  child: Style('p-4', child: Text('p-4 is now 32px')),
)

You can also provide theme data through Material’s ThemeData.extensions:

MaterialApp(
  theme: ThemeData(
    extensions: [
      StyleThemeExtension(data: StyleThemeData(
        colors: {'primary': {500: Color(0xFF6200EE)}},
      )),
    ],
  ),
  home: Style('bg-primary-500 text-white', child: Text('Themed')),
)

For full API reference and live examples, see Custom themes.

Differences from Tailwind CSS

Feature	Tailwind CSS	Style library
Custom themes	`@theme` directive in CSS	`StyleTheme` widget with `StyleThemeData`
CSS variables	Generated as `--color-`, `--spacing-`	Resolved at parse time from Dart maps
Runtime access	`getComputedStyle()`	Direct access via token maps
Theme extension	Add custom tokens via `@theme`	`StyleThemeData` overrides or arbitrary values `[...]`
Custom variants	`@custom-variant`	`StyleVariants` widget