home / skills / hoangnguyen0403 / agent-skills-standard / flutter-design-system

flutter-design-system skill

safe

This skill enforces Flutter design system adherence by replacing hardcoded values with project tokens, enhancing consistency and maintainability.

npx playbooks add skill hoangnguyen0403/agent-skills-standard --skill flutter-design-system

Review the files below or copy the command above to add this skill to your agents.

Files (4)

SKILL.md

1.6 KB

---
name: Flutter Design System
description: Enforce strict Design Language System (DLS) adherence. Prevents hardcoded colors, spacing, and typography. Detects and uses project tokens.
metadata:
  labels: [flutter, dls, design-tokens, theme, styling]
  triggers:
    files:
      [
        '**/theme/**',
        '**/*_theme.dart',
        '**/*_colors.dart',
        '**/*_dls/**',
        '**/foundation/**',
      ]
    keywords:
      [
        ThemeData,
        ColorScheme,
        AppColors,
        VColors,
        VSpacing,
        AppTheme,
        design token,
      ]
---

# Flutter Design System Enforcement

## **Priority: P0 (CRITICAL)**

Zero tolerance for hardcoded design values.

## Guidelines

- **Colors**: Use tokens (`VColors.*`, `AppColors.*`), never `Color(0xFF...)` or `Colors.red`.
- **Spacing**: Use tokens (`VSpacing.*`), never magic numbers like `16` or `24`.
- **Typography**: Use tokens (`VTypography.*`, `textTheme.*`), never inline `TextStyle`.
- **Borders**: Use tokens (`VBorders.*`), never raw `BorderRadius.`
- **Components**: Use DLS widgets (`VButton`) over raw Material widgets (`ElevatedButton`) if available.

[Detailed Examples](references/usage.md)

## Anti-Patterns

- **No Hex Colors**: `Color(0xFF...)` is strictly forbidden.
- **No Color Enums**: `Colors.blue` is forbidden in UI code.
- **No Magic Spacing**: `SizedBox(height: 10)` is forbidden.
- **No Inline Styles**: `TextStyle(fontSize: 14)` is forbidden.
- **No Raw Widgets**: Don't use `ElevatedButton` when `VButton` exists.

## Related Topics

mobile-ux-core | flutter/widgets | idiomatic-flutter

Overview

This skill enforces a strict Flutter Design Language System (DLS) to ensure consistent UI across the codebase. It prevents hardcoded colors, spacing, typography, and raw widgets, and encourages use of centralized design tokens and DLS components. The goal is uniform visual language, easier theme updates, and fewer UI regressions.

How this skill works

The skill scans Dart/Flutter source for banned patterns such as hex Color constructors, direct Colors.* enums, magic numeric spacing, inline TextStyle definitions, raw BorderRadius, and use of Material widgets when DLS widgets exist. When it detects violations it highlights the exact locations and suggests the corresponding token or DLS component (for example VColors.primary, VSpacing.x4, VTypography.body). It integrates as a rule set that can be used in CI checks or editor linting to block merges that violate the DLS.

When to use it

During code reviews and pre-merge CI to block UI anti-patterns.
When onboarding new team members to enforce consistent implementation.
Refactoring legacy Flutter code to adopt the project design tokens.
When adding features that affect look-and-feel to avoid drift.
As a gating rule for releases that require visual consistency.

Best practices

Always substitute hardcoded colors with provided tokens such as VColors.* or AppColors.*.
Replace numeric spacing with VSpacing tokens instead of SizedBox or magic numbers.
Use VTypography or textTheme tokens instead of inline TextStyle declarations.
Prefer DLS components (VButton, VCard, etc.) over raw Material widgets when available.
Treat the linter output as fixable guidance: map each violation to a token replacement.

Example use cases

Reject a pull request that adds Color(0xFF123456) in a widget and point to VColors.primary.
Automated scan that flags SizedBox(height: 12) and suggests VSpacing.x3.
CI check that fails when TextStyle(fontSize: 14) appears, directing to VTypography.bodySmall.
Batch refactor that replaces ElevatedButton with VButton across a feature branch.
Pre-merge validation to ensure no BorderRadius.circular(...) remains in new UI code.

FAQ

What if a DLS token does not yet exist for a needed value?

Create a new token in the design token registry following naming conventions and add it to the shared tokens; then use that token rather than a hardcoded value.

Does this block non-UI code using Colors enums?

The rule focuses on UI code paths; utility or test code can be reviewed separately, but UI layers must use tokens to preserve design consistency.