---

name: style-guardian description: "Style Guardian - Unified Design System Enforcement Tool. Use for: (1) Preventing hardcoded styles (colors, spacing, typography), (2) Preventing hardcoded text (i18n violations), (3) Guiding unified configuration usage, (4) Detecting and fixing style violations"

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:

Copy// 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

Copy// 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:

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

2. Run flutter gen-l10n

3. Use in code:

   CopyText(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

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

// Fix
Container(color: UIColors.primary)

Violation 2: Hardcoded Spacing

Copy// 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

Copy// Violation
TextStyle(fontSize: 14)

// Fix
TextStyle(fontSize: UIFontSizes.bodyMedium)

Violation 4: Hardcoded Border Radius

Copy// Violation
BorderRadius.circular(8)

// Fix
BorderRadius.circular(UIBorderRadius.sm)

Violation 5: Hardcoded Text

Copy// 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

Copy// 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

Copy# 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

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

Common Replacements

Responsive Suffixes