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

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

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

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.