Style Guardian - Unified Design System Enforcement

Core Principles

Design Philosophy: Flat Design 2.0 + Monochrome System

Key Files

Color System

Primary Color (Blue, 90% usage)

Positive Color (Green, 5% usage)

Negative Color (Orange, 5% usage)

Background Colors

Spacing System (4dp Grid)

SizedBox Spacing

EdgeInsets Padding

Typography System

Font Sizes

Responsive Font Sizes

Use .rsp suffix for responsive scaling:

// Correct
TextStyle(fontSize: UIFontSizes.bodyMedium)  // Already includes .rsp

// Incorrect
TextStyle(fontSize: 14)
TextStyle(fontSize: 14.sp)  // Manual scaling

Border Radius System

Internationalization (i18n)

Correct Usage

// Correct - use l10n
Text(context.l10n!.libraryTitle)
Text(context.l10n!.selectedCount(count, total))
Text(context.l10n!.errorMessage)

// Incorrect - hardcoded strings
Text('My Library')
Text('$count items selected')
Text('An error occurred')

Adding New Translation Keys

1. Edit lib/l10n/app_en.arb:

   jsonCopy

   {
     "newKey": "New text value",
     "@newKey": {
       "description": "Description of the text"
     }
   }
   

2. Run flutter gen-l10n

3. Use in code:

   dartCopy

   Text(context.l10n!.newKey)
   

Supported Languages

• en (English)
• en_US (English - US)
• zh_TW (Traditional Chinese)
• zh_CN (Simplified Chinese)
• zh (Chinese)
• es (Spanish)
• fr (French)
• hi (Hindi)
• ja (Japanese)
• ko (Korean)

Common Violations and Fixes

Violation 1: Hardcoded Colors

// Violation
Container(color: Colors.blue)
Container(color: Color(0xFF2196F3))

// Fix
Container(color: UIColors.primary)

Violation 2: Hardcoded Spacing

// Violation
SizedBox(height: 16)
Padding(padding: EdgeInsets.all(8))

// Fix
SizedBox(height: UISpacing.md)
Padding(padding: EdgeInsets.all(UISpacing.xs))

Violation 3: Hardcoded Font Size

// Violation
TextStyle(fontSize: 14)

// Fix
TextStyle(fontSize: UIFontSizes.bodyMedium)

Violation 4: Hardcoded Border Radius

// Violation
BorderRadius.circular(8)

// Fix
BorderRadius.circular(UIBorderRadius.sm)

Violation 5: Hardcoded Text

// Violation
Text('My Library')
AppBar(title: Text('Settings'))

// Fix
Text(context.l10n!.libraryTitle)
AppBar(title: Text(context.l10n!.settingsTitle))

Violation 6: ViewModel Hardcoded User Messages

Scope: lib/presentation/**/viewmodel.dart, lib/presentation/**_viewmodel.dart

Detection Pattern: String literals assigned to error/message state properties

// Violation - Hardcoded user messages in ViewModel
state = state.copyWith(errorMessage: 'Invalid file format');
state = state.copyWith(errorMessage: '網路連線失敗');
_errorMessage = 'Something went wrong';

// Fix - Use i18n or ErrorHandler
state = state.copyWith(errorMessage: context.l10n!.invalidFileFormat);
state = state.copyWith(errorMessage: ErrorHandler.getUserMessage(exception));

Allowed Exceptions:

• e.toString() for unknown system exceptions
• String interpolation with i18n: context.l10n!.errorWithCode(code)

Related: FLUTTER.md - ViewModel 層使用者訊息規範

Detection Script Usage

Manual Scan

# Scan entire project
uv run .claude/skills/style-guardian/scripts/style_checker.py scan lib/

# Scan specific directory
uv run .claude/skills/style-guardian/scripts/style_checker.py scan lib/presentation/

# Generate report
uv run .claude/skills/style-guardian/scripts/style_checker.py report

Hook Integration

The style checker is integrated into PostEdit Hook:

• Automatically scans edited files in lib/presentation/
• Reports violations in hook output
• Suggests fixes based on this guide

Related Documentation

Project Files

• UI Configuration
• Flat Design Config
• Responsive Config
• UI Design Specification
• i18n Guide

Reference Files (in this SKILL)

• Color System Reference
• Spacing System Reference
• Typography System Reference
• i18n Guidelines Reference

External Resources

• Flat Design Explained - MasterClass
• Best Practices for Flat Design - Usersnap
• Material Design 3 Color System

Quick Reference Card

Import Statement

import 'package:book_overview_app/core/ui/ui_config.dart';

Common Replacements

Responsive Suffixes