Design Tokens

Design tokens are the foundation of Neo’s theming system. They provide named references to design decisions like colors, spacing, typography, and animations, ensuring consistency across your application while maintaining flexibility for customization. Access them on a NeoTheme via theme.colors, theme.spacings, theme.radii, theme.shadows, theme.textStyles, and theme.durations.

Token Categories

Neo organizes design tokens into six main categories on NeoTheme:

Color Tokens

Class

Semantic colors. Access via theme.colors. Widgets compose from these tokens and handle hover/press themselves. For global primary-button tinting, set the nullable buttonPrimaryBg / buttonPrimaryBgInteraction / buttonPrimaryFg overrides when needed.

Brand:

brand
fgOnBrand

Ink:

ink — the mode foreground pigment
fgOnInk — text/icons on ink surfaces (toasts, tooltips, etc.)

Foreground Colors: fg* uses a per-mode ink alpha ladder.

fgPrimary
fgSecondary
fgTertiary

Background Colors:

bgPrimary
bgSecondary
bgTertiary

Fill Colors: fillSubtle / fillStrong are interaction washes (not part of the fg/border ladder).

fillSubtle
fillStrong

Border Colors: borderPrimary, borderSecondary, and borderTertiary are alpha-on-ink values. They blend with whatever surface sits behind them — verify appearance when drawing borders on non-default backgrounds.

borderPrimary
borderSecondary
borderTertiary

Utility:

transparent
scrim — dimmed overlay wash for modals and similar surfaces (typically pure black at call-site alpha)

Semantic Colors:

success / onSuccess
warning / onWarning
danger / onDanger

Nullable widget overrides (keep these sparse — only for global customization of specific widget parts):

buttonPrimaryBg / buttonPrimaryBgInteraction / buttonPrimaryFg
checkboxCheckedBg / checkboxCheckedFg

Fixed presentation (not intended as general app overrides):

codeBlockBg / codeBlockFg

Spacing Tokens

Class

Consistent spacing values for layouts and component padding. Access via theme.spacings.

extraSmall
small
medium
large
extraLarge

Border Radius Tokens

Class

Corner radius values that maintain visual consistency. Access via theme.radii.

extraSmall
small
medium
large
full

Shadow Tokens

Class

Elevation and depth definitions for components and overlays. Access via theme.shadows.

extraSmall
small
medium

Typography Tokens

Class

Complete type scale for clear information hierarchy. Access via theme.textStyles.

header1
header2
header3
header4
body1
body2
label
button
code

Duration Tokens

Class

Animation durations for consistent timing and smooth interactions. Access via theme.durations.

short
medium
long

Using Design Tokens

Access design tokens through the neoCurrentThemeProvider:

class MyWidget extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final theme = ref.watch(neoCurrentThemeProvider);
    
    return Container(
      padding: .all(theme.spacings.medium),
      decoration: BoxDecoration(
        color: theme.colors.bgSecondary,
        borderRadius: .circular(theme.radii.medium),
        border: .all(color: theme.colors.borderSecondary),
        boxShadow: [theme.shadows.small],
      ),
      child: Text(
        "Design Token Example",
        style: theme.textStyles.body1.copyWith(
          color: theme.colors.fgPrimary,
        ),
      ),
    );
  }
}

Benefits

Consistency: Ensures visual harmony across your application
Maintainability: Update designs by changing token values, not individual components
Scalability: Easy to maintain consistent design at any application size
Flexibility: Switch between light/dark themes or completely different brand themes
Developer Experience: Clear, semantic names make code more readable

Getting Started

AI

Widgets

Layouts

Theming

Utilities

Design Tokens

Token Categories

Color Tokens

Spacing Tokens

Border Radius Tokens

Shadow Tokens

Typography Tokens

Duration Tokens

Using Design Tokens

Benefits

​Token Categories

​Color Tokens

​Spacing Tokens

​Border Radius Tokens

​Shadow Tokens

​Typography Tokens

​Duration Tokens

​Using Design Tokens

​Benefits

Token Categories

Color Tokens

Spacing Tokens

Border Radius Tokens

Shadow Tokens

Typography Tokens

Duration Tokens

Using Design Tokens

Benefits