Krow-workspace/apps/docs/03-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 `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.**

## 2. Design System Ownership & Responsibility

- **Centralized Authority**: The `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 (`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 unless specified. They should use the icons exposed via `UiIcons` or the approved central library.

- **Standardization**: Ensure the same icon is used for the same action across all features (e.g., always use `UiIcons.back` for navigation).
- **Additions**: New icons must be added to the design system (only using the typedef _IconLib = LucideIcons 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/`) 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: Logic Refactor**: Immediately refactor the code to:
   - Follow the `docs/01-architecture-principles.md` and `docs/02-agent-development-rules.md` to refactor the code.
3. **Step 3: Theme Refactor**: Immediately refactor the code to:
   - Replace hex codes with `UiColors`.
   - Replace manual `TextStyle` with `UiTypography`.
   - Replace hardcoded padding/radius with `UiConstants`.
   - Upgrade icons to design system versions.

## 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`.

## 12. Enforcement & Review Checklist

Before any UI code is merged, it must pass this checklist:
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 and element placement(wireframing and logic) while using the design system primitives.