Krow-workspace/docs/MOBILE/02-design-system-usage.md

# 03 - Design System Usage Guide

This document defines the mandatory standards for designing and implementing user interfaces across all applications and feature packages using the shared `apps/mobile/packages/design_system`.

## 1. Introduction & Purpose

The Design System is the single source of truth for the visual identity of the project. Its purpose is to ensure UI consistency, reduce development velocity by providing reusable primitives, and eliminate "design drift" across multiple feature teams and applications.

**All UI implementation MUST consume values ONLY from the `design_system` package.**

### Core Principle
Design tokens (colors, typography, spacing, etc.) are immutable and defined centrally. Features consume these tokens but NEVER modify them. The design system maintains visual coherence across staff and client apps.

## 2. Design System Ownership & Responsibility

- **Centralized Authority**: The `apps/mobile/packages/design_system` is the owner of all brand assets, colors, typography, and core components.
- **No Local Overrides**: Feature packages (e.g., `staff_authentication`) are consumers. They are prohibited from defining their own global styles or overriding theme values locally.
- **Extension Policy**: If a required style (color, font, or icon) is missing, the developer must first add it to the `design_system` package following existing patterns before using it in a feature.

## 3. Package Structure Overview (`apps/mobile/packages/design_system`)

The package is organized to separate tokens from implementation:
- `lib/src/ui_colors.dart`: Color tokens and semantic mappings.
- `lib/src/ui_typography.dart`: Text styles and font configurations.
- `lib/src/ui_icons.dart`: Exported icon sets.
- `lib/src/ui_constants.dart`: Spacing, radius, and elevation tokens.
- `lib/src/ui_theme.dart`: Centralized `ThemeData` factory.
- `lib/src/widgets/`: Common "Smart Widgets" and reusable UI building blocks.

## 4. Colors Usage Rules

Feature packages **MUST NOT** define custom hex codes or `Color` constants.

### Usage Protocol
- **Primary Method**:Use `UiColors` from the design system for specific brand accents.
- **Naming Matching**: If an exact color is missing, use the closest existing semantic color (e.g., use `UiColors.mutedForeground` instead of a hardcoded grey).

```dart
// ❌ ANTI-PATTERN: Hardcoded color
Container(color: Color(0xFF1A2234))

// ✅ CORRECT: Design system token
Container(color: UiColors.background)
```

## 5. Typography Usage Rules

Custom `TextStyle` definitions in feature packages are **STRICTLY PROHIBITED**.

### Usage Protocol
- Use `UiTypography` from the design system for specific brand accents.

```dart
// ❌ ANTI-PATTERN: Custom TextStyle
Text('Hello', style: TextStyle(fontSize: 24, fontWeight: FontWeight.bold))

// ✅ CORRECT: Design system typography
Text('Hello', style: UiTypography.display1m)
```

## 6. Icons Usage Rules

Feature packages **MUST NOT** import icon libraries (like `lucide_icons`) directly. They should use the icons exposed via `UiIcons`.

- **Standardization**: Ensure the same icon is used for the same action across all features (e.g., always use `UiIcons.chevronLeft` for navigation).
- **Additions**: New icons must be added to the design system (only using the typedef _IconLib = LucideIcons or typedef _IconLib2 = FontAwesomeIcons; and nothing else) first to ensure they follow the project's stroke weight and sizing standards.

## 7. UI Constants & Layout Rules

Hardcoded padding, margins, and radius values are **PROHIBITED**.

- **Spacing**: Use `UiConstants.spacing` multiplied by tokens (e.g., `S`, `M`, `L`).
- **Border Radius**: Use `UiConstants.borderRadius`.
- **Elevation**: Use `UiConstants.elevation`.

```dart
// ✅ CORRECT: Spacing and Radius constants
Padding(
  padding: EdgeInsets.all(UiConstants.spacingL),
  child: Container(
    borderRadius: BorderRadius.circular(UiConstants.radiusM),
  ),
)
```

## 8. Common Smart Widgets Guidelines

The design system provides "Smart Widgets" – these are high-level UI components that encapsulate both styling and standard behavior.

- **Standard Widgets**: Prefer standard Flutter Material widgets (e.g., `ElevatedButton`) but styled via the central theme.
- **Custom Components**: Use `design_system` widgets for non-standard elements or wisgets that has similar design across various features, if provided.
- **Composition**: Prefer composing standard widgets over creating deep inheritance hierarchies in features.

## 9. Theme Configuration & Usage

Applications (`apps/mobile/apps/`) must initialize the theme once in the root `MaterialApp`.

```dart
MaterialApp.router(
  theme: StaffTheme.light, // Mandatory: Consumption of centralized theme
  // ...
)
```
**No application-level theme customization is allowed.**

## 10. Feature Development Workflow (POC → Themed)

To bridge the gap between rapid prototyping (POCs) and production-grade code, developers must follow this three-step workflow:

1. **Step 1: Structural Implementation**: Implement the UI logic and layout **exactly matching the POC**. Hardcoded values from the POC are acceptable in this transient state to ensure visual parity.
2. **Step 2: Architecture Refactor**: Immediately refactor the code to:
   - Follow clean architecture principles from `apps/mobile/docs/00-agent-development-rules.md` and `01-architecture-principles.md`
   - Move business logic from widgets to BLoCs and use cases
   - Implement proper repository pattern with Data Connect
   - Use dependency injection via Flutter Modular
3. **Step 3: Design System Integration**: Immediately refactor UI to consume design system primitives:
   - Replace hex codes with `UiColors`
   - Replace manual `TextStyle` with `UiTypography`
   - Replace hardcoded padding/radius with `UiConstants`
   - Upgrade icons to design system versions
   - Use `ThemeData` from `design_system` instead of local theme overrides

## 11. Anti-Patterns & Common Mistakes

- **"Magic Numbers"**: Hardcoding `EdgeInsets.all(12.0)` instead of using design system constants.
- **Local Themes**: Using `Theme(data: ...)` to override colors for a specific section of a page.
- **Hex Hunting**: Copy-pasting hex codes from Figma or POCs into feature code.
- **Package Bypassing**: Importing `package:flutter/material.dart` and ignoring `package:design_system`.
- **Stateful Pages**: Pages with complex state logic instead of delegating to BLoCs.
- **Direct Data Queries**: Features querying Data Connect directly instead of through repositories.
- **Global State**: Using global variables for session/auth instead of `SessionStore` + `SessionListener`.
- **Hardcoded Routes**: Using `Navigator.push(context, MaterialPageRoute(...))` instead of Modular.
- **Feature Coupling**: Importing one feature package from another instead of using domain-level interfaces.

## 12. Enforcement & Review Checklist

Before any UI code is merged, it must pass this checklist:

### Design System Compliance
1. [ ] No hardcoded `Color(...)` or `0xFF...` in the feature package.
2. [ ] No custom `TextStyle(...)` definitions.
3. [ ] All spacing/padding/radius uses `UiConstants`.
4. [ ] All icons are consumed from the approved design system source.
5. [ ] The feature relies on the global `ThemeData` and does not provide local overrides.
6. [ ] The layout matches the POC visual intent while using design system primitives.

### Architecture Compliance
7. [ ] No direct Data Connect queries in widgets; all data access via repositories.
8. [ ] BLoCs handle all non-trivial state logic; pages are mostly stateless.
9. [ ] Session/auth accessed via `SessionStore` not global state.
10. [ ] Navigation uses Flutter Modular named routes.
11. [ ] Features don't import other feature packages directly.
12. [ ] All business logic in use cases, not BLoCs or widgets.
13. [ ] Repositories properly implement error handling and mapping.
14. [ ] Doc comments present on all public classes and methods.