Read page as text

NIB / DOCUMENTATION

Theming — NibComponents

Set shared colors and radii, override one control, and keep both brightness modes usable.

Open interactive view

Start with Flutter brightness

NibTheme is a Flutter ThemeExtension. Every call to NibTheme.of(context) first checks the nearest ThemeData for that extension. If it is absent, the method chooses NibTheme.light or NibTheme.dark from the ambient brightness. You can put a Nib control in a MaterialApp before writing any theme configuration.

This website uses a dark Ember palette. The package also supports light themes. Set ThemeData brightness and the Nib extension together: installing NibTheme.dark in a light ThemeData does not make Material widgets dark. ThemeMode.system chooses between the two ThemeData objects using the platform preference.

MaterialApp(
  theme: ThemeData.light().copyWith(
    extensions: [
      NibTheme.light.copyWith(
        primary: const Color(0xFF6D28D9),
        primaryForeground: Colors.white,
        ring: const Color(0xFF6D28D9),
      ),
    ],
  ),
  darkTheme: ThemeData.dark().copyWith(
    extensions: const [NibTheme.dark],
  ),
  themeMode: ThemeMode.system,
  home: const Scaffold(body: Center(child: Text('Your screen'))),
)

Know which token changes which surface

The public constructor has 16 color tokens and four radius tokens. copyWith preserves every field you omit. Change a fill and its foreground together, then inspect the result in normal, focused, disabled, and error states. A readable button label does not guarantee a visible focus ring around that button.

TokensPurpose
background / foregroundPage surfaces and their main text.
card / cardForegroundCard and raised surface fill and text.
primary / primaryForegroundPrimary actions and their foreground.
secondary / secondaryForegroundSecondary surfaces and their foreground.
muted / mutedForegroundQuiet surfaces and secondary text.
accent / accentForegroundAccent fill and its foreground.
borderOutlines and dividers where the component reads this token.
inputDefault input border.
ringFocus and active input ring.
destructiveDestructive and error color.
radiusSmSmall radius; built-in value 4 logical pixels.
radiusDefaultDefault radius; built-in value 8 logical pixels.
radiusLgLarge radius; built-in value 12 logical pixels.
radiusPillPill radius; built-in value 9999 logical pixels.
APITypeDefaultBehavior
NibTheme.ofNibTheme Function(BuildContext)Registered extension, then brightness fallbackResolve tokens from a context below the intended Theme.
NibTheme.copyWithNibThemeOmitted fields retainedReturn a new token set; the original stays immutable.
NibTheme.lerpNibThemeThemeExtension interpolationInterpolate colors and radii when Flutter interpolates themes.

Theme one component without inventing another theme API

The current package exports one NibTheme class. There are no NibButtonTheme or NibCardTheme extensions. Per-component styling comes from constructor arguments. For example, NibButton exposes backgroundColor, foregroundColor, borderColor, and borderRadius. NibCard exposes backgroundColor, borderColor, and borderRadius. These explicit values take precedence over their token defaults.

Use a shared token change when several controls should change together. Use an instance override for a deliberate exception. A button that keeps its old color after a theme change may simply have an explicit backgroundColor. Removing that override lets the variant resolve its fill again.

Button variants and instance styling

Card surfaces and flip faces

NibButton(
  label: 'Secondary action',
  variant: NibButtonVariant.outline,
  borderRadius: BorderRadius.circular(4),
  onPressed: () {},
)

Change the theme without replacing the draft

Wrap a section in Theme when it needs a local palette. Use Theme.of(context).copyWith to preserve unrelated Flutter settings. If you already have other ThemeExtension objects, keep them when replacing the extensions list. Read NibTheme.of from below the wrapper; a context above it still sees the outer theme.

Keep controllers and keys outside build. Editing an accent or switching brightness should rebuild presentation, not create a new TextEditingController or reset a selected tab. Type a draft, place its cursor in the middle, then change the theme to check this separation in your own screen.

NibTheme does not define typography, spacing, shadows, or every effect color. Use Flutter ThemeData and the documented instance arguments for those. Toast success and warning accents are fixed package colors, while error and info use destructive and accent. Liquid glass has its own tint, radius, and optical defaults; changing radiusDefault alone does not change its shape.

Controller ownership

Liquid glass styling and fallback

Overlay theme and placement rules

Review the states people will actually use

Check text, focus rings, selected rows, disabled controls, errors, and overlay content in each supported brightness mode. Open a dialog while changing the app theme and inspect its nested content as well as the outer surface. The dialog and sheet helpers recapture inherited themes on overlay rebuilds; explicit colors in your content still win.

Color contrast and readable layouts depend on your chosen tokens and content. The dark website preview is not a light-theme or physical-device accessibility certification. Test your final palette at the text sizes and platforms you support.