NIB / DOCUMENTATION
Theming — NibComponents
Set shared colors and radii, override one control, and keep both brightness modes usable.
Open interactive viewStart 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.
| Tokens | Purpose |
|---|---|
| background / foreground | Page surfaces and their main text. |
| card / cardForeground | Card and raised surface fill and text. |
| primary / primaryForeground | Primary actions and their foreground. |
| secondary / secondaryForeground | Secondary surfaces and their foreground. |
| muted / mutedForeground | Quiet surfaces and secondary text. |
| accent / accentForeground | Accent fill and its foreground. |
| border | Outlines and dividers where the component reads this token. |
| input | Default input border. |
| ring | Focus and active input ring. |
| destructive | Destructive and error color. |
| radiusSm | Small radius; built-in value 4 logical pixels. |
| radiusDefault | Default radius; built-in value 8 logical pixels. |
| radiusLg | Large radius; built-in value 12 logical pixels. |
| radiusPill | Pill radius; built-in value 9999 logical pixels. |
| API | Type | Default | Behavior |
|---|---|---|---|
| NibTheme.of | NibTheme Function(BuildContext) | Registered extension, then brightness fallback | Resolve tokens from a context below the intended Theme. |
| NibTheme.copyWith | NibTheme | Omitted fields retained | Return a new token set; the original stays immutable. |
| NibTheme.lerp | NibTheme | ThemeExtension interpolation | Interpolate 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
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.
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.