super_core 3.0.0

Super Core — GeniusLink’s shared design-system foundation for the Super toolkit: super_auto_suggestion_box, super_form_field, super_map, super_table_field, super_tree, and super_tab_bar. Defines the v [...]

Super Core

The shared GeniusLink design-system foundation for the Super toolkit — the single source of truth for colors, palettes, Material themes, typography, spacing, radii, motion, formatters, and design-system widgets.

---

Installation

Add to your pubspec.yaml:

dependencies:
  super_core: ^3.0.0  # monorepo path dependency

Then import the barrel:

import 'package:super_core/super_core.dart';

---

Packages that depend on super_core

Package	Purpose
super_auto_suggestion_box	Typeahead / combobox
super_form_field	Eight GeniusLink form field types
super_map	Node-graph canvas
super_tab_bar	Browser-style workspace tab bar
super_table_field	ERP data grid
super_tree	Recursive hierarchy / chart of accounts
super_navigation_sidebar	Responsive app navigation sidebar
super_naviagtion_page	Overlay / sheet navigation surfaces

---

What's inside

Symbol	Purpose
SuperPalette	Ten swappable color palettes, each with 10 shades + semantic getters
SuperMaterialThemeData	Complete Material 3 theme — a ThemeData subclass (palette + responsive SuperDeviceMode)
SuperDeviceMode	mobile / tablet / desktop device mode + SuperResponsive<T> container
SuperMetrics	Responsive spacing / sizing / padding / margin token bundle
Layout	SuperBreakpoint, SuperBreakpoints, SuperBreakpointProvider, SuperGrid, SuperGridCell, SuperGridScope, SuperScaffold
SuperInteractiveStateThemeData	Hover / focus / pressed / selected overlay treatment (ThemeExtension)
SuperTokensData	Dynamic brand tokens carried by the theme (accent + semantic palette, font families, spacing, radii, motion). Read via SuperThemeData.of(context).tokens.
SuperThemeData	Swappable light/dark ThemeExtension — surfaces, borders, fg1…fg4 text ramp, tokens, and textTheme
SuperTextTheme	TextTheme subclass — all 15 Material slots + 9 named fields (displayLg, headlineSm, titleMd, bodyLg, bodySm, labelMd, labelSm, mono, eyebrow). Powered by Google Fonts (Manrope / Inter / Noto Naskh Arabic). Read via context.superTheme.textTheme.
SuperAppBarTheme	AppBarTheme subclass — adds subtitlePosition + responsive maxActions / maxMobileActions / maxTabletActions / maxDesktopActions
SuperCardTheme	CardThemeData subclass — expand direction / duration / curve, tap-to-toggle, chevron, padding, border colors
SuperSemanticColors	Structured status-color bundle (info/success/warning/danger/accent/neutral), each with solid/onSolid/subtle/onSubtle/border
SuperColorX	Color-extension helpers — HSL tonal ops, WCAG 2.1 contrast, hex parse/format
SuperFormat	Intl-free number / currency / byte / serial formatters
SuperMarker	Three section-marker intents (identity / ledger / notes)
Widgets	SuperSectionCard, SuperSectionHeader, SuperSectionFooter, AccentSectionCard, StatusPill, SuperButton, Hairline, FieldShell, SuperSnackBar, SuperAppBar, SuperSliverAppBar, SuperListTile, SuperGridTile, SuperSlider
Plumbing	Failures, typedefs, usecases, key-direction + BuildContext helpers

Migrating from v2.4? SectionCard, SuperSection, and SuperCard are replaced by SuperSectionCard; SectionHeader is replaced by SuperSectionHeader. See skill/migration_v2.4.0_to_v3.0.0/.

Migrating from v1? SuperTokens.x → SuperThemeData.of(context).tokens.x. SuperDialog is removed — use Flutter's showDialog / AlertDialog. See the skill/migration_v1_to_v2/ guides.

---

v3.0.0 Layout and Section APIs

Consolidated section components

Use SuperSectionCard for the surfaces that were previously split across SectionCard, SuperSection, and SuperCard:

SuperSectionCard(
  title: 'Financial',
  subtitle: 'Linked control account and terms',
  headerStyle: SuperSectionHeaderStyle.style2,
  icon: Icons.sync_alt,
  children: const [
    AccountField(),
    TermsField(),
  ],
);

SuperSectionCard(
  color: context.superTheme.inputBg,
  selected: selected,
  onTap: onSelect,
  expandedChild: const StoreDetails(),
  child: const StoreSummary(),
);

Use SuperSectionHeader for all section headers:

SuperSectionHeader(
  title: 'Opening Balance',
  subtitle: 'Ledger totals carried into the new period',
  marker: SuperMarker.ledger,
  trailing: const StatusPill('BALANCED', tone: PillTone.success),
);

Layout components

Use SuperScaffold as a responsive page-frame wrapper and SuperGrid for column-based layouts:

Scaffold(
  appBar: const SuperAppBar(title: Text('Dashboard')),
  body: SuperScaffold(
    maxWidth: 1120,
    child: SuperGrid(
      scope: SuperGridScope.current,
      children: const [
        SuperGridCell(mobile: 4, tablet: 4, desktop: 3, child: KpiCard()),
        SuperGridCell(mobile: 4, tablet: 4, desktop: 9, child: DetailsPanel()),
      ],
    ),
  ),
);

Use SuperBreakpointProvider when previews, dialogs, or side panels need a controlled local breakpoint:

SuperBreakpointProvider(
  breakpoint: SuperBreakpoint.tablet,
  child: SuperGrid(
    scope: SuperGridScope.provider,
    children: const [
      SuperGridCell(mobile: 4, tablet: 8, child: PreviewPanel()),
    ],
  ),
);

Migrating from 2.4.0

// Before
SectionCard(title: 'Account Details', child: form);
SuperSection(title: 'Financial', children: fields);
SuperCard(color: context.superTheme.inputBg, child: summary);
SectionHeader(title: 'Opening Balance');

// After
SuperSectionCard(title: 'Account Details', child: form);
SuperSectionCard(title: 'Financial', children: fields);
SuperSectionCard(color: context.superTheme.inputBg, child: summary);
SuperSectionHeader(title: 'Opening Balance');

See skill/migration_v2.4.0_to_v3.0.0/ for the full migration guide.

---

SuperPalette

Ten built-in palettes:

Palette	shade500	Notes
SuperPalette.bluePalette	#4A7CFF	Default GeniusLink accent
SuperPalette.purplePalette	#7C5CFC	Violet / indigo
SuperPalette.greenPalette	#1DB88A	GeniusLink success green
SuperPalette.goldenPalette	#F59E0B	Warm amber / gold
SuperPalette.tealPalette	—	Teal
SuperPalette.rosePalette	—	Rose
SuperPalette.indigoPalette	—	Indigo
SuperPalette.slatePalette	—	Slate
SuperPalette.grayPalette	#64748B	Neutral grays
SuperPalette.monochromePalette	#737373	Pure black / white

Each palette exposes ten shades (shade50 … shade900) and semantic accessors: primary, primaryDark, onPrimary, error, info, success, warning, plus light/dark surface tokens (lightBg, darkSurface, darkFg1, …).

All palettes use the same GeniusLink-standard neutral surfaces — only the accent/primary color varies. This preserves the precision-instrument feel of the design system regardless of which palette is active.

---

SuperMaterialThemeData

SuperMaterialThemeData extends ThemeData — it is a Material theme, so Theme.of(context) is SuperMaterialThemeData is true. Generate a complete Material 3 theme from a palette and a device mode:

MaterialApp(
  theme:     SuperMaterialThemeData.light(palette: SuperPalette.bluePalette),
  darkTheme: SuperMaterialThemeData.dark(palette: SuperPalette.bluePalette),
  // palette + mode are optional — default SuperPalette.bluePalette / SuperDeviceMode.mobile
);

Constructor overrides & precedence

Both .light and .dark accept palette, mode, and per-component overrides (textTheme, appBarTheme, navigationBarTheme, buttonTheme, formFieldTheme, cardTheme, dialogTheme, tableTheme, dividerTheme, iconTheme, interactiveStateTheme, extensions). Precedence is explicit override > palette-generated > Flutter default. .light() always produces Brightness.light; .dark() always Brightness.dark.

Context lookups

SuperMaterialThemeData? m = SuperMaterialThemeData.maybeOf(context); // null if not a Super theme
SuperMaterialThemeData  t = SuperMaterialThemeData.of(context);      // always valid; wraps a plain ThemeData, preserving its config

Responsive device mode

// Pick a mode from the current width and rebuild the theme responsively:
final mode = SuperDeviceMode.of(context); // tablet ≥ 600, desktop ≥ 1024
SuperMaterialThemeData.light(mode: mode);

// Responsive tokens (spacing grows with the viewport; control heights shrink):
final s = SuperThemeData.of(context);
s.spacing.cardPadding;   s.spacing.lg;   s.sizing.fieldComfortable;   s.spacing.sectionMargin;

// Author your own responsive value with the same container:
const gutter = SuperResponsive<double>(mobile: 16, tablet: 24, desktop: 32);
gutter.resolve(mode);

The generated TextTheme and InputDecorationTheme also scale per mode (font size / line height, and field padding / density / height / border / icon constraints). Caller textTheme: / formFieldTheme: override these wholesale.

Compact density (v2.3.0)

Every inset a card draws comes from the responsive scales below — cards no longer hard-code space6 / space10, so overriding the metrics (or the card theme) retunes the whole app's density:

Token	mobile	tablet	desktop
spacing.cardPadding	14	16	18
spacing.pagePadding	12	20 / 16	48 / 24
spacing.fieldPadding	12 / 10	12 / 10	14 / 8
spacing.section (gap between cards)	12	14	16
spacing.xl (header → body)	20	22	24
spacing.md (card slot gap)	10	12	12
spacing.sectionMargin	12	14	16
sizing.fieldComfortable	44	42	40

// Roomier again, app-wide:
SuperMaterialThemeData.light(
  cardTheme: const SuperCardTheme(padding: EdgeInsets.all(24)),
);
// …or per card:
SuperSectionCard(padding: const EdgeInsets.all(20), title: 'Account Details', child: form);

Runtime palette switching

  SuperPalette _palette = SuperPalette.bluePalette;

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      theme:     SuperMaterialThemeData.light(palette: _palette),
      darkTheme: SuperMaterialThemeData.dark(palette: _palette),
      home: MyHome(
        onPaletteChanged: (p) => setState(() => _palette = p),
      ),
    );
  }

What's configured

• Complete ColorScheme derived from the palette — including the Material 3 fixed accent roles (primaryFixed, primaryFixedDim, onPrimaryFixed, onPrimaryFixedVariant, and the secondary/tertiary equivalents) and the full surface-container ramp (surfaceDim, surfaceBright, surfaceContainerLowest → surfaceContainerHighest)
• Typography wired to Manrope / Inter / JetBrains Mono
• Scaffold background = ColorScheme.surface (the GeniusLink page background). Cards, panels and fields sit on lifted surface tokens so the screen matches the mobile light/dark surface stack.
• App bar painted on the same page background as the Scaffold, with a systemOverlayStyle that paints the status bar and navigation bar the same color and picks status/nav icon brightness automatically for contrast
• All button variants (elevated, outlined, text, filled, icon)
• Input decoration (4 px radius, fieldComfortable height)
• Navigation bar, rail, drawer, bottom navigation bar, bottom app bar
• Dialog, bottom sheet, popup menu, tooltip, snack bar, material banner
• Card, chip, tab bar, segmented button, toggle buttons, badge
• Switch, checkbox, radio, slider, progress indicator
• Data table (hover row, label headers)
• Date picker, time picker, search bar, search view, dropdown menu, menu bar
• Text selection (cursor / handle / selection tint)
• Scrollbar, FAB, expansion tile, menu
• Top-level color roles (focusColor, hoverColor, highlightColor, splashColor, hintColor, primaryColor + dark/light, shadowColor, secondaryHeaderColor, unselectedWidgetColor), visualDensity, materialTapTargetSize, splashFactory, applyElevationOverlayColor

Precedence is always explicit constructor override > palette-generated > Flutter default — the generated values above only fill in what you do not pass. Host-derived fields (platform, cupertinoOverrideTheme, pageTransitionsTheme, typography) are left to Flutter unless overridden.

SuperThemeData auto-registration

SuperMaterialThemeData carries a superTheme field AND registers that same SuperThemeData instance as a ThemeExtension, so theme.superTheme and Theme.of(context).extension<SuperThemeData>() always agree, and every Super component that calls SuperThemeData.of(context) picks up the palette-, brightness- and device-mode-derived tokens automatically:

// In any Super component — no extra setup needed when using SuperMaterialThemeData:
final t = SuperThemeData.of(context);
Text('TOTAL', style: t.textTheme.label.copyWith(color: t.fg2));

---

SuperThemeData — pre-v1.0.0 API (unchanged)

// Manual registration — still supported:
MaterialApp(
  theme:     ThemeData(extensions: const [SuperThemeData.light]),
  darkTheme: ThemeData(extensions: const [SuperThemeData.dark]),
);

final t = SuperThemeData.of(context); // falls back to .dark

---

Dynamic brand tokens (SuperTokensData)

Brand tokens are no longer static const — they are instance fields on the immutable SuperTokensData the theme carries, so any of them can be overridden per theme. Every field keeps its historical value as a default* constant, so const SuperTokensData() reproduces the GeniusLink defaults exactly.

// Override tokens on the generated theme:
SuperMaterialThemeData.light(
  palette: SuperPalette.bluePalette,
  tokens: const SuperTokensData(radiusCard: 12, space4: 20),
);

// Read the active tokens at any call site:
final tokens = SuperThemeData.of(context).tokens;
SizedBox(height: tokens.space4);
BorderRadius.circular(tokens.radiusCard);
color: SuperMarker.ledger.resolve(tokens);

Custom font family

Change the toolkit's font without losing the GeniusLink type ramp. Precedence: explicit fontFamily > the family carried by a provided textTheme (when mergeTextTheme is true) > the token default.

// Simplest — swap the whole workhorse/display family:
SuperMaterialThemeData.light(fontFamily: 'IBM Plex Sans');

// Merge a TextTheme's font over the default ramp (sizes/weights preserved):
SuperMaterialThemeData.light(
  textTheme: GoogleFonts.ibmPlexSansTextTheme(),
  mergeTextTheme: true, // default — keeps SuperMaterialThemeData typography, adopts the font
);

// Replace the ramp wholesale instead:
SuperMaterialThemeData.light(textTheme: myTextTheme, mergeTextTheme: false);

App bars — SuperAppBar / SuperSliverAppBar

Full forks of Flutter's AppBar / SliverAppBar (every property is customizable) plus two GeniusLink features: a positionable subtitle and responsive action overflow — extra actions past the limit collapse into a three-dot menu. The limit is resolved per device class (mobile 3 / tablet 4 / desktop 5) unless you set maxActions or the per-device overrides.

GeniusLink-specific chrome (v2.4.0):

• Auto-implied back button uses Icons.arrow_back_ios_new_rounded in a plain IconButton (not Flutter's platform-default BackButton).
• Auto-implied button appears when parentRoute?.impliesAppBarDismissal is true; suppressed correctly on root routes.
• Default title style falls back to t.textTheme.headlineSm (Manrope 700).
• Default subtitle style falls back to t.textTheme.labelSm with letterSpacing: 1.2 — matching the ALL-CAPS breadcrumb style.

Scaffold(
  appBar: SuperAppBar(
    title: const Text('Create Store'),
    subtitle: const Text('STORES & PRODUCTS • STORES'),
    subtitlePosition: SubtitlePosition.above, // or .below (default)
    actions: [/* > maxActions collapse into a ⋮ overflow */],
    // maxActions / maxMobileActions / maxTabletActions / maxDesktopActions
  ),
);

CustomScrollView(slivers: [
  SuperSliverAppBar(
    pinned: true,
    expandedHeight: 200,
    title: const Text('Journal'),
    subtitle: const Text('BANKING • LOCAL TRANSFERS'),
    flexibleSpace: const FlexibleSpaceBar(background: LedgerHeaderArt()),
    actions: [/* … */],
  ),
]);

Defaults come from the SuperAppBarTheme installed into ThemeData.appBarTheme by SuperMaterialThemeData; override it via appBarTheme: on the theme constructor.

SuperSectionCard

SuperSectionCard is the consolidated section/card surface. It can render a plain card, compose a SuperSectionHeader and SuperSectionFooter, collapse a body, show selected/tap states, and reveal expandedChild vertically or horizontally. Defaults come from SuperSectionThemeData and SuperCardTheme.

SuperSectionCard(
  leading: const Icon(Icons.storefront_outlined),
  header: const SuperSectionHeader(title: 'Downtown Central Store'),
  headerTrailing: const StatusPill('ACTIVE', tone: PillTone.success),
  color: context.superTheme.inputBg,
  expandedChild: const StoreDetailTable(), // revealed on tap / chevron
  // expandDirection: Axis.horizontal, initiallyExpanded, isExpanded, onExpansionChanged…
  child: const StoreSummary(),
);

---

Font setup

Drop the brand .ttf files under assets/fonts/ and uncomment the fonts: block in pubspec.yaml:

Family	Role
Manrope	Display — H1 page titles, watermark
Inter	Body, labels, buttons, captions
JetBrains Mono	Numerics, serials, audit log
Noto Naskh Arabic	Arabic glyphs