Color Helpers

Wind provides a set of utility functions and extensions to help you resolve and manipulate colours programmatically, staying consistent with your theme.

Resolving Colors#

The wColor function is the primary way to resolve colours from the active WindTheme. It handles colour names, shades, and even automatic dark mode overrides.

Color? wColor(
  BuildContext context,
  String colorName, {
  int shade = 500,
  String? darkColorName,
  int darkShade = 500,
})

Basic Usage#

You can resolve a colour by its name and shade:

// Resolves blue-500 from the theme
final primary = wColor(context, 'blue');

// Resolves red-600
final error = wColor(context, 'red', shade: 600);

// Resolves using color-shade string format
final danger = wColor(context, 'rose-500');

Dark Mode Overrides#

You can specify a different colour or shade to be used when the theme is in dark mode. darkColorName takes a bare colour name, and the shade goes in darkShade; a name that carries a shade, such as 'slate-900', resolves to nothing in dark mode:

final background = wColor(
  context,
  'slate-50',
  darkColorName: 'slate',
  darkShade: 900,
);

Hex Colors#

The hexToColor function converts various hex string formats into Flutter Color objects.

Color hexToColor(String code)

Supported Formats#

Opacity Handling#

Wind includes utilities for parsing Tailwind-style opacity modifiers and applying them to colours.

Parsing Opacity#

The parseColorOpacity function splits a class string into the colour part and its opacity factor.

// Returns (colorPart: 'blue-500', opacity: 0.5)
final result = parseColorOpacity('blue-500/50');

// Supports arbitrary values: (colorPart: 'red-500', opacity: 0.75)
final arbitrary = parseColorOpacity('red-500/[75]');

Applying Opacity#

Use applyOpacity to programmatically adjust the alpha channel of any Color.

Color applyOpacity(Color color, double opacity)

final semiTransparent = applyOpacity(Colors.blue, 0.5);

Contrast#

contrastRatio and contrastForeground compute WCAG 2.x contrast for a colour your theme does not own, such as a brand colour an end user picks for a public status page. A theme token already has a correct dark: pair; these two exist for the colour that does not.

double contrastRatio(Color a, Color b)

Color contrastForeground(
  Color background, {
  Color light = const Color(0xFFFFFFFF),
  Color dark = const Color(0xFF000000),
})

contrastRatio returns a value from 1 (identical colours) to 21 (pure black against pure white). contrastForeground picks whichever of light or dark has the higher ratio against background, comparing the two ratios directly rather than checking background's luminance against the usual 0.179 crossover. That threshold is only correct when both candidates are pure black and pure white; pass a dark tuned away from pure black (a near-black brand tone, say) and the threshold can pick the candidate that reads worse.

Both helpers take opaque colours. Luminance ignores alpha, so a translucent colour reports the ratio of its opaque self rather than of what renders; composite it over its backdrop (Color.alphaBlend(color, backdrop)) before calling either one.

// A status page renders its operator's brand colour behind white text.
// The brand colour is not a theme token, so it needs a computed answer.
final Color heading = contrastForeground(brandColor);

// Compare a fixed pair directly.
final double ratio = contrastRatio(brandColor, Colors.white);

Material Color Inversion#

The invertMaterialColor utility is a standalone helper that returns a palette with its shades swapped (e.g., 50 ↔ 900, 100 ↔ 800). The theme engine does not call it, so dark mode variants come from the dark: pairs in your classes.

MaterialColor invertMaterialColor(MaterialColor color)

Context Extensions#

For more ergonomic access, Wind extends BuildContext with several colour-related shortcuts.

context.windColors#

Returns the full colour map from the current WindThemeData.

final redPalette = context.windColors['red'];

context.wColorExt#

A shortcut for calling wColor(context, ...).

final primary = context.wColorExt('blue', shade: 600);

context.windIsDark#

Returns a boolean indicating if the current theme brightness is Brightness.dark.

if (context.windIsDark) {
  // Do something specific for dark mode
}