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

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

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)

design-system

NPX Install

Tags

SKILL.md Content

Design Tokens

Colors

Spacing

Border Radius

Typography

Iconography

Reusable Components

Component Rules

Component Organization

Component Best Practices

Theming

ThemeData Assembly

Theme Access

Dark Mode

Accessibility