Design System

Iron Law: Never hardcode colors, spacing, or typography — always use design tokens; run /lint-design-system before declaring any UI change complete.

Design System — Unified Routing Hub

Single entry point for all design system enforcement across Flutter and Angular.

When to use: Any UI task — building screens, reviewing components, auditing design drift, or running design lint.

Routing Table

Determine the stack from file context, then load the correct references:

What are you working on?
    |
    +-- Flutter (lib/**/*.dart, pubspec.yaml)
    |   |
    |   +-- Tokens (colors, spacing, typography, radius)
    |   |   → Read: .claude/skills/ui-standards-tokens/reference/ui-design-tokens.md
    |   |
    |   +-- Accessibility (semantics, focus, contrast)
    |   |   → Read: .claude/skills/ui-standards-tokens/reference/ui-accessibility-patterns.md
    |   |
    |   +-- Polish (animations, glassmorphism, theme extensions)
    |       → Read: .claude/skills/flutter-mobile/reference/flutter-design-polish.md
    |
    +-- Angular (src/app/**/*.ts|html|scss)
    |   |
    |   +-- Component styling (daisyUI classes, semantic tokens)
    |   |   → Read: .claude/skills/angular-spa/reference/daisyui-v5-components.md
    |   |
    |   +-- Tailwind config (spacing, breakpoints, CSS vars)
    |   |   → Read: .claude/skills/angular-spa/reference/tailwind-v4-config.md
    |   |
    |   +-- Conventions (design principles, form patterns)
    |   |   → Read: .claude/skills/angular-spa/reference/angular-conventions.md
    |   |
    |   +-- Animations (timing, keyframes, reduced motion)
    |       → Read: .claude/skills/angular-spa/reference/animations.md
    |
    +-- Cross-stack (interaction contracts, visual direction)
        |
        +-- Surface/interaction contracts (modals, forms, lists, errors)
        |   → Read: .claude/skills/design-system/reference/interaction-contracts.md
        |
        +-- Visual design direction (anti-patterns, typography philosophy)
            → Read: .claude/skills/frontend-design/reference/frontend-design-principles.md

Design Rules — Hard Policy (Both Stacks)

These are non-negotiable. Violations are caught by hookify rules at write-time.

Colors

• NEVER hardcode hex values (#3b82f6, Color(0xFF...))
• NEVER use rgb(), rgba(), hsl(), hsla() literals
• Flutter: Use Theme.of(context).colorScheme.*
• Angular: Use daisyUI semantic tokens (bg-primary, text-base-content)

Spacing

• NEVER use raw numeric spacing (EdgeInsets.all(16), mt-3)
• Flutter: Use AppSpacing.xs/sm/md/lg/xl/xxl
• Angular: Use Tailwind semantic scale or daisyUI component spacing

Typography

• NEVER use raw font sizes (TextStyle(fontSize: 14), text-[14px])
• Flutter: Use Theme.of(context).textTheme.*
• Angular: Use Tailwind typography scale (text-sm, text-lg, text-xl)

Forms

• NEVER use bare <input>, <select>, <textarea> without framework bindings
• Angular: Use daisyUI form classes + reactive form formControlName
• Flutter: Use shared form field wrapper widgets

Touch Targets

• Minimum 48dp (Flutter) / 44px (Angular) for all interactive elements

Inline Styles

• NEVER use style="..." in Angular templates — use Tailwind utilities or SCSS
• NEVER use inline Style widgets in Flutter — use theme extensions

Machine Enforcement

Hookify Rules (fire on every Write/Edit by Claude)

All rules respect // ignore-design: [reason] exception markers.

Lint Commands

Quality Gate

Before declaring any UI work done, these must pass (from verification-and-reporting.md):

• No hardcoded colors — all colors use theme tokens
• No raw spacing values — all spacing uses semantic tokens
• No inline TextStyles — all typography uses theme text styles
• Touch targets >= 48dp (Flutter) / 44px (Angular)
• /lint-design-system run with zero violations
• Exception markers (// ignore-design: [reason]) reviewed and justified

Exception Policy

When a design rule must be violated intentionally:

1. Add inline marker: // ignore-design: [short reason] or <!-- ignore-design: [reason] -->
2. Reason must explain WHY (e.g., "platform-specific iOS styling", "third-party widget constraint")
3. Exceptions are reviewed like code debt
4. Periodically audit: search for ignore-design and remove stale exceptions
5. If 5+ exceptions accumulate in one file → the design system may need extending, flag it

Scope & Rationale

What We Enforce

What We Defer

File Path Scope

Visual Audit — 10-Dimension Scoring

Score the current UI across these 10 dimensions (0–10 each). For each dimension provide: score, specific file:line example, and a concrete fix.

1. Color consistency — Are colors using theme tokens (bg-primary, colorScheme.primary) or hardcoded hex values (Color(0xFF3b82f6), #3b82f6 in SCSS)?
2. Typography hierarchy — Clear h1 > h2 > h3 > body > caption scale using Theme.of(context).textTheme.* (Flutter) or Tailwind typography scale (text-sm, text-lg, text-xl) (Angular)? Or raw TextStyle(fontSize: N) / text-[14px] scattered throughout?
3. Spacing rhythm — Consistent 4px/8px/16px scale via AppSpacing.* (Flutter) or Tailwind semantic scale (Angular)? Or arbitrary EdgeInsets.all(16) / mt-3 / px-4 that break the grid?
4. Component consistency — Do similar elements (buttons, cards, list items, form fields) use the same widget/component patterns, or are there one-off inline implementations?
5. Responsive behavior — Fluid across breakpoints? Angular: Tailwind sm:/md:/lg: breakpoints applied? Flutter: LayoutBuilder / MediaQuery used for adaptive layouts?
6. Dark mode — Complete theme coverage using colorScheme (Flutter) / daisyUI semantic tokens (Angular)? Or half-done with hardcoded light values that break in dark mode?
7. Animation — Purposeful (entrance transitions, state changes, feedback)? Or gratuitous scroll-triggered animations on every section that distract rather than guide?
8. Accessibility — Color contrast ≥ 4.5:1 for normal text / ≥ 3:1 for large text, focus states present, touch targets ≥ 48dp (Flutter) / 44px (Angular), semantic labels on interactive elements?
9. Information density — Cluttered (too many competing elements) or too sparse (wasted space)? Empty states handled with meaningful UI rather than blank screens or raw null renders?
10. Polish — Hover states (Angular), loading states (CircularProgressIndicator / skeleton screens), error states (user-visible feedback), and micro-transitions present and consistent?

Total score / 100.

• ≥ 80 — Ship-ready. Minor issues only.
• 60–79 — Polish pass needed before release.
• < 60 — Redesign required. Do not ship.

For each dimension scored below 7: file the specific file:line violation and state the concrete fix using the correct token or pattern for the stack.

AI Slop Detection

Flag these patterns immediately — they signal generic AI-generated UI with no design intention. Each flag requires the exact file:line and the replacement pattern.