Agent skill

style-guardian

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

View SKILL.md on GitHub Repository
Stars 1
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/tarrragon/claude/tree/main/skills/style-guardian

SKILL.md

Style Guardian - Unified Design System Enforcement

Core Principles

Design Philosophy: Flat Design 2.0 + Monochrome System

Principle Description Source
Minimalism Clean, uncluttered layouts Flat Design
2D Styling Simple, flat shapes without 3D effects Flat Design
Subtle Shadows Shadows hint at interactivity (Flat 2.0) Material Design
Monochrome Primarily use different saturations of blue Project Design Spec
Three-Color System Blue (primary) + Green (positive) + Orange (negative) Project Design Spec

Key Files

File Purpose
lib/core/ui/ui_config.dart Core style configuration system
lib/core/ui/flat_design_config.dart Flat design component configuration
lib/core/ui/responsive_config.dart Responsive layout configuration
lib/app/theme.dart Application theme (uses UIColors)
docs/ui_design_specification.md UI design specification document

Color System

Primary Color (Blue, 90% usage)

Hardcoded UIColors Purpose Hex
Colors.blue UIColors.primary Primary buttons #2196F3
Color(0xFF2196F3) UIColors.primary Primary buttons #2196F3
Colors.blue[50] UIColors.primaryLightest Background blocks #E3F2FD
Colors.blue[100] UIColors.primaryLight Secondary blocks #BBDEFB
Colors.blue[300] UIColors.primaryMedium Interactive elements #64B5F6
Colors.blue[700] UIColors.primaryDark Selected states #1976D2
Colors.blue[900] UIColors.primaryDarkest Emphasis text #0D47A1

Positive Color (Green, 5% usage)

Hardcoded UIColors Purpose
Colors.green UIColors.positive Success, confirmation
Colors.green[100] UIColors.positiveLight Success backgrounds
Colors.green[700] UIColors.positiveDark Success emphasis

Negative Color (Orange, 5% usage)

Hardcoded UIColors Purpose
Colors.orange UIColors.negative Warning, error
Colors.amber UIColors.negative Warning, caution
Colors.red UIColors.negative Project does NOT use red

Background Colors

Hardcoded UIColors Purpose
Colors.white UIColors.surfaceLight Card backgrounds
Colors.grey[50] UIColors.backgroundLight Page backgrounds
Colors.grey[600] UIColors.onSurfaceMuted Muted text

Spacing System (4dp Grid)

SizedBox Spacing

Hardcoded UISpacing Responsive
SizedBox(height: 4) SizedBox(height: UISpacing.xxs) .h suffix
SizedBox(height: 8) SizedBox(height: UISpacing.xs) .h suffix
SizedBox(height: 12) SizedBox(height: UISpacing.sm) .h suffix
SizedBox(height: 16) SizedBox(height: UISpacing.md) .h suffix
SizedBox(height: 24) SizedBox(height: UISpacing.lg) .h suffix
SizedBox(height: 32) SizedBox(height: UISpacing.xl) .h suffix
SizedBox(width: 8) SizedBox(width: UISpacing.xs) .w suffix

EdgeInsets Padding

Hardcoded UISpacing
EdgeInsets.all(4) EdgeInsets.all(UISpacing.xxs)
EdgeInsets.all(8) EdgeInsets.all(UISpacing.xs)
EdgeInsets.all(16) EdgeInsets.all(UISpacing.md)
EdgeInsets.symmetric(horizontal: 16) EdgeInsets.symmetric(horizontal: UISpacing.md)
EdgeInsets.symmetric(vertical: 8) EdgeInsets.symmetric(vertical: UISpacing.xs)

Typography System

Font Sizes

Hardcoded UIFontSizes Purpose
fontSize: 10 UIFontSizes.overline Overline text
fontSize: 12 UIFontSizes.bodySmall Small body text
fontSize: 14 UIFontSizes.bodyMedium Standard body text
fontSize: 16 UIFontSizes.bodyLarge Large body text
fontSize: 18 UIFontSizes.titleMedium Medium titles
fontSize: 20 UIFontSizes.titleLarge Large titles
fontSize: 24 UIFontSizes.headline3 Headlines

Responsive Font Sizes

Use .rsp suffix for responsive scaling:

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

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

Border Radius System

Hardcoded UIBorderRadius
BorderRadius.circular(4) BorderRadius.circular(UIBorderRadius.xs)
BorderRadius.circular(8) BorderRadius.circular(UIBorderRadius.sm)
BorderRadius.circular(12) BorderRadius.circular(UIBorderRadius.md)
BorderRadius.circular(16) BorderRadius.circular(UIBorderRadius.lg)
BorderRadius.circular(20) BorderRadius.circular(UIBorderRadius.xl)
BorderRadius.circular(999) BorderRadius.circular(UIBorderRadius.circular)

Internationalization (i18n)

i18n 硬編碼檢測、ARB 工作流程、支援語言清單詳見 /i18n-checker。

快速參考：所有使用者可見文字必須使用 context.l10n!.keyName，禁止硬編碼字串。

Common Violations and Fixes

Violation 1: Hardcoded Colors

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

// Fix
Container(color: UIColors.primary)

Violation 2: Hardcoded Spacing

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

dart
// Violation
TextStyle(fontSize: 14)

// Fix
TextStyle(fontSize: UIFontSizes.bodyMedium)

Violation 4: Hardcoded Border Radius

dart
// Violation
BorderRadius.circular(8)

// Fix
BorderRadius.circular(UIBorderRadius.sm)

Violation 5: Hardcoded Text

硬編碼文字檢測和修正詳見 /i18n-checker。

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

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

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

Related Skills

  • /i18n-checker - i18n 硬編碼全量掃描和修正工作流程

External Resources

Quick Reference Card

Import Statement

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

Common Replacements

Type Hardcoded Configuration
Color Colors.blue UIColors.primary
Success Colors.green UIColors.positive
Warning Colors.orange UIColors.negative
Spacing 16 UISpacing.md
Font 14 UIFontSizes.bodyMedium
Radius 8 UIBorderRadius.sm
Text 'My Library' context.l10n!.libraryTitle

Responsive Suffixes

Suffix Purpose Example
.w Width scaling 16.w
.h Height scaling 16.h
.rsp Font scaling 14.rsp
.r Radius scaling 8.r

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

tarrragon/claude

skill-design-guide

Use this skill when creating a new skill, updating an existing skill's YAML frontmatter, or reviewing skill quality. Provides the official Anthropic skill specification, frontmatter rules, description writing best practices, progressive disclosure architecture, and common pitfalls to avoid. Triggers include: creating skills, skill review, frontmatter validation, SKILL.md writing.

1 0
Explore
tarrragon/claude

test-async-guardian

Flutter/Dart 測試異步資源管理守護者。用於：(1) 診斷測試卡住問題，(2) 審查測試程式碼中的異步資源清理，(3) 提供 tearDown 最佳實踐，(4) 掃描潛在的資源洩漏風險。觸發場景：測試卡住、撰寫新測試、Code Review 測試程式碼、執行 flutter test 前自動掃描。

1 0
Explore
tarrragon/claude

agent-team

Agent Teams 協作派發指南。Use when: (1) Agent A 的發現會改變 Agent B 正在進行的工作, (2) 用戶要求使用 team/swarm, (3) 多代理人需即時協商共用介面或 API 契約。涵蓋 team 建立、Ticket-Task 橋接、teammate 入職、生命週期管理。

1 0
Explore
tarrragon/claude

tdd

TDD 全流程指導工具。Use for: (1) 開始新功能的 TDD 流程（Phase 0-4）, (2) 推進到下一個 TDD 階段, (3) Phase 1 SOLID 原則驅動功能拆分分析, (4) 查看當前 TDD 進度和階段狀態, (5) 評估是否需要 Phase 4 重構以及 3b 拆分評估。Use when: 開始新功能開發、進入任何 TDD Phase、需要 SOLID 拆分指導、需要確認當前所在 TDD 階段、需要做 Phase 4 豁免判斷時。

1 0
Explore
tarrragon/claude

branch-worktree-guardian

Branch Worktree Guardian - Git 分支和 Worktree 管理工具。Use for: (1) 新開發需求時建立隔離分支, (2) 使用 worktree 機制避免分支衝突, (3) 驗證當前工作分支正確性, (4) 預防在錯誤分支上開發

1 0
Explore
tarrragon/claude

design-decision-framework

多方案評估決策框架。用於面臨 3+ 技術方案時的結構化評估、架構決策時的系統化分析，防止衝動決策和技術債務累積。Use for: 技術方案選擇、重大架構決策、高風險技術選型

1 0
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results