System Design

Centralized design tokens, theming, and UI primitives used across the app.

Theme & Tokens

• Color roles follow Material 3 ColorScheme.
• Use context.colors and context.textStyles helpers to avoid hardcoded colors and text styles.
• Brand tokens are mapped into the ColorScheme (light/dark) and exported via AppTheme.light() and AppTheme.dark().

Gradients

• DSGradients.brandAccent: Orange → Pink brand gradient for accents.
• DSGradients.surfaceGloss(ColorScheme): subtle surface gradient for elevated surfaces.

Async Overlays

Use AsyncStateOverlay for long-running operations to avoid modal spinners:

return Stack(
  children: [
    content,
    AsyncStateOverlay(visible: state.isLoading, label: 'Carregando...'),
  ],
);

Infinite Lists

Use InfiniteList<T> for mobile-friendly infinite scrolling with optional pull-to-refresh:

InfiniteList<Item>(
  items: state.items,
  itemBuilder: (ctx, item, i) => ItemTile(item: item),
  onLoadMore: cubit.loadMore,
  onRefresh: cubit.refresh,
  isLoadingMore: state.isLoadingMore,
  hasMore: state.hasMore,
  errorText: state.errorMessage,
)

Guidelines

• Do not use Color(...) or Colors.* in feature code.
• Always consume theme via Theme.of(context) or the provided context helpers.

Migration Playbook (feature teams)

1. Replace hardcoded colors and text styles

   • Search for Colors. and Color( in your feature.
   • Replace color usage with context.colors.* roles and text with context.textStyles.
   • For surfaces, prefer colors.surface or colors.surfaceVariant; for content, use colors.onSurface or colors.onSurfaceVariant.

2. Adopt design-system primitives

   • Replace ad-hoc cards/buttons/inputs with system_design components (e.g., CardShell, DS buttons, DS inputs).
   • For long operations, wrap your screen in a Stack and use AsyncStateOverlay(visible: ...) instead of modal spinners.

3. Infinite scrolling lists

   • Use InfiniteList<T> to implement pagination and pull-to-refresh.
   • Make sure your Cubit exposes isLoadingMore, hasMore, and guards against duplicate requests.

4. Gradients and accents

   • Use DSGradients.brandAccent (Orange→Pink) for accents where appropriate.
   • Avoid inlining gradient definitions in features.

5. Theme source of truth

   • Ensure your app obtains ThemeData from system_design AppTheme.light()/dark().
   • Do not construct custom ThemeData in feature packages.

6. Linting (recommended)

   • Add a lint that forbids Color(...) in features. Allow only Theme/DS helpers.
   • Add CI checks to deny merging if violations occur.