Skip to content
On this page

Theming

Configure the shared color, size, radius, spacing, typography, motion, and shadow tokens.

Theme configuration

ThemeData contains seven immutable groups with complete defaults:

GroupTypePurpose
colorsColorTokensSemantic UI roles, including brand and surface
radiusRadiusTokensControl, surface and rounding values
sizesSizeTokensControl heights and icon sizes
spacesSpaceTokensSpacing scale
typographyTypographyTokensFont ownership and text roles
motionMotionThemeComplete animation recipes and timing tokens
shadowsShadowTokensElevation and surface shadows

Override just a brand color (the default on-brand foreground adapts for contrast):

final light = ThemeData(
  colors: ColorTokens(brand: Colors.violet.shade600),
);
final dark = ThemeData.dark(
  colors: ColorTokens.dark(brand: Colors.violet.shade400),
);

FluttyApp(
  theme: light,
  darkTheme: dark,
  themeMode: ThemeMode.system, // or light / dark
  home: const Text('Hello'),
);

Light and dark configurations are independent. Use ColorTokens.dark when partially customizing a dark color group. copyWith replaces supplied groups; copy a group first to retain its other custom values:

final compact = light.copyWith(
  sizes: light.sizes.copyWith(inputHeight: 44),
  spaces: light.spaces.copyWith(lg: 12),
);

Choose shared component sizes, rounding families, spacing density and a font in one app theme:

final theme = ThemeData(
  sizes: const SizeTokens(defaultSize: ComponentSize.md),
  radius: const RadiusTokens(form: RadiusSize.sm, general: RadiusSize.lg),
  spaces: const SpaceTokens(preset: SpacingSize.md),
  typography: const TypographyTokens(fontFamily: FontFamily.application('MyFont')),
);

FluttyApp(theme: theme, home: const Text('Hello'));

Register custom font assets in the application's pubspec.yaml. Inter remains the bundled default when typography is omitted.

Controls and other size-aware components support ComponentSize.xs, sm, md, lg and xl. An omitted component size uses theme.sizes.defaultSize; an explicit size overrides it. Medium retains each component's existing dimensions. SizeTokens provides control, input, icon, scaled and font helpers for custom components:

final sizes = context.theme.sizes;
final size = sizes.resolve(null); // app default
final height = sizes.input(size);
final iconSize = sizes.icon(size);
final labelSize = sizes.font(size, base: 14);

Form and general rounding are independent. RadiusSize.none, sm, md, lg and xl resolve to 0, 8, 12, 16 and 24 by default. Leaving a preset unset retains component-specific rounding. Numeric control, surface and pill overrides retain precedence for their roles; numeric overrides on a widget win over app settings.

SpacingSize.sm, md, lg and xl multiply base gaps and padding by 0.75, 1, 1.25 and 1.5. Named spacing values passed to constructors or copyWith are base units. Reading spaces.lg or calling spaces.scaleValue(16) applies the preset once; copying a configured theme does not scale it again. Spacing does not change the component size or its touch target.

Read tokens using context.theme or ThemeScope.of(context). There is one source of truth for each value: theme.colors.brand, theme.radius.control, theme.sizes.inputHeight, and so on. Appearance is resolved once by the app; MediaQuery.platformBrightnessOf(context) reports the chosen brightness. Resolved text styles never get written back into the configuration.

Apply a local override:

final parent = context.theme;
ThemeScope(
  data: parent.copyWith(radius: parent.radius.copyWith(control: 12)),
  child: const Text('A local theme'),
);

Theme scopes provide text, icon and selection defaults. They participate in InheritedTheme.captureAll so you can carry a local theme into an overlay rooted outside that scope. Ordinary ancestor scopes update their descendants live; captured themes are snapshots and should be recaptured when their source changes.

DartFlutter

Get started with FluttyUI