Design Tokens

Design tokens are the atomic values of the design system. UI elements MUST use tokens — never raw values.

Colors

• ✅ Use AppColors.primary, AppColors.secondary, AppColors.error, AppColors.success, AppColors.warning, AppColors.surface, AppColors.textPrimary, AppColors.textSecondary
• ❌ NEVER use Color(0xFF...), Colors.blue, or inline hex values
• Map semantic tokens to Material 3 ColorScheme for platform consistency
• Each color token MUST document its use case and ensure WCAG AA contrast ratio
• Support light and dark mode via ThemeData — never branch on Brightness manually in widgets

Spacing

• ✅ Use AppSpacing.xxs (2), AppSpacing.xs (4), AppSpacing.sm (8), AppSpacing.md (16), AppSpacing.lg (24), AppSpacing.xl (32), AppSpacing.xxl (48)
• ✅ Use AppSpacing.screenHorizontal (24), AppSpacing.screenVertical (16) for consistent screen padding
• ❌ NEVER use EdgeInsets.all(16.0), SizedBox(height: 8), or hardcoded padding values
• Use SizedBox(height: AppSpacing.sm) for gaps — not Container or Padding with empty child

Border Radius

• ✅ Use AppRadius.xs (4), AppRadius.sm (8), AppRadius.md (12), AppRadius.lg (16), AppRadius.xl (24), AppRadius.full (999)
• ❌ NEVER use BorderRadius.circular(12) or inline radius values

Typography

• ✅ Use context.textTheme.headlineLarge, context.textTheme.bodyMedium, etc. via theme extensions
• ✅ Optionally use AppTypography wrapper for custom token names mapping to TextTheme
• ❌ NEVER use TextStyle(fontSize: 16) or inline text styles
• Define font family, size, weight, and letter spacing as tokens

Iconography

• Use a consistent icon set (Material Icons, Cupertino Icons, or custom icon font)
• Wrap icon usage in AppIcons constants for consistency
• Use Icon(AppIcons.settings, size: AppSpacing.lg) — not raw Icons.settings

Reusable Components

Component Rules

• Single Responsibility: Each component has one clear purpose. Complex UIs MUST be composed of smaller, focused components.
• Parameterization: Components expose parameters for customization (text, callbacks, styles). Avoid creating near-duplicate widgets.
• Composition Over Inheritance: Build widgets by composing smaller widgets. Do NOT extend framework widgets unless strictly necessary.
• Immutable Widgets: Design widgets as stateless wherever possible. Manage state externally via BLoC.
• Reuse Threshold: If a widget or pattern appears 2+ times, extract it into core/views/widgets/.
• Testability: Every reusable component MUST have a corresponding widget test in the mirror structure.

Component Organization

core/
├── views/
│   └── widgets/
│       ├── buttons/          (AppPrimaryButton, AppOutlinedButton, AppIconButton)
│       ├── cards/            (AppCard, AppInfoCard, AppActionCard)
│       ├── dialogs/          (AppAlertDialog, AppConfirmDialog)
│       ├── inputs/           (AppTextField, AppSearchField, AppDropdown)
│       ├── feedback/         (AppSnackbar, AppToast, AppEmptyState, AppErrorState)
│       ├── loading/          (AppLoadingIndicator, AppShimmer, AppSkeleton)
│       └── layout/           (AppScaffold, AppSectionHeader, AppDivider)
├── theme/
│   ├── app_colors.dart
│   ├── app_spacing.dart
│   ├── app_radius.dart
│   ├── app_typography.dart
│   ├── app_theme.dart        (ThemeData assembly)
│   └── app_theme_extensions.dart (BuildContext extensions)
└── constants/
    └── app_icons.dart

Component Best Practices

• All reusable widgets MUST accept Key parameter via super.key
• Use const constructors in all reusable components
• Provide sensible defaults — components should work with minimal configuration
• Document each public component with /// comment explaining purpose, required params, and an inline usage example

Theming

ThemeData Assembly

• Assemble ThemeData in a single app_theme.dart file using token classes
• Use ColorScheme.fromSeed() or map semantic AppColors to ColorScheme slots
• Define both lightTheme and darkTheme in the same file
• Use ThemeExtension<T> for custom tokens beyond Material's defaults (e.g., AppSpacing, AppRadius)

Theme Access

• ALWAYS access via BuildContext extensions: context.colorScheme, context.textTheme, context.theme
• NEVER pass theme values as constructor parameters when context is available
• NEVER use Theme.of(context) directly — use extensions for readability

Dark Mode

• Every screen and component MUST render correctly in both light and dark mode
• Test dark mode as part of widget tests using MediaQuery theme override
• Use semantic color tokens (surface, onSurface, primary, onPrimary) — not absolute colors

Accessibility

• All interactive components MUST include Semantics labels
• Support minimum touch target size (48x48 dp) per Material guidelines
• Ensure text scales correctly via MediaQuery.textScaleFactor
• Use sufficient color contrast (WCAG AA: 4.5:1 for normal text, 3:1 for large text)