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

02 - 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).

// ❌ 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.

// ❌ 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.

// ✅ 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 widgets that have similar design across various features, if provided.

• Navigation in Widgets: Widgets that trigger navigation (e.g., Back buttons in UiAppBar) MUST use Modular.to.popSafe() or typed navigator methods to prevent blank screens or unexpected application states during stack pops.

• 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.

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.