flowstate-ui-ux

name	flowstate-ui-ux
emoji	🎯
description	FlowState-specific UI/UX design and implementation skill covering visual design principles, color theory, typography, spacing systems, layout composition, accessibility (WCAG 2.2), animation, web standards compliance, and systematic implementation workflows. Use for FlowState app work only — for other projects use frontend-ux-ui-design.

UI/UX Design & Implementation

Version: 2.0.0 Category: Design + Implement Related Skills: dev-storybook, dev-vue, dev-css-design-system

Overview

Comprehensive skill for both designing and implementing UI/UX. Covers visual design principles (color, typography, spacing, layout, hierarchy), accessibility compliance (WCAG 2.2), animation patterns, and systematic implementation workflows.

When to Activate This Skill

Invoke this skill when:

• Designing color palettes or visual systems
• Creating typography hierarchies
• Building spacing and layout systems
• Implementing UI/UX fixes from audits
• Ensuring WCAG 2.2 accessibility compliance
• Adding animations and microinteractions
• Avoiding AI-generic design patterns
• Matching reference designs

Component Best Practices

For component-level interaction patterns, anti-patterns, and FlowState component mapping, read references/component-patterns.md. It covers:

• Quick rules for 12 common components (buttons, modals, toasts, forms, etc.)
• Focus management, loading states, validation, destructive actions
• Anti-pattern checklist (rainbow badges, modal-in-modal, disabled submit, etc.)
• Generic-to-FlowState component mapping table

---

PART 1: COLOR THEORY & PALETTE GENERATION

1.1 HSL Color Model

HSL = Hue, Saturation, Lightness

Hue (0-360°):
- 0° = Red
- 60° = Yellow
- 120° = Green
- 180° = Cyan
- 240° = Blue
- 300° = Magenta

Saturation (0-100%):
- 0% = Grayscale
- 100% = Pure color

Lightness (0-100%):
- 0% = Black
- 50% = Pure color
- 100% = White

1.2 Color Wheel Relationships

Relationship	Formula	Degrees	Use Case
Analogous	H ± 30°	-30°, 0°, +30°	Harmonious, safe
Complementary	H + 180°	Opposite	High contrast
Triadic	H + 120°, H + 240°	Equally spaced	Vibrant, balanced
Split-Complementary	H + 150°, H + 210°	150° apart	Less harsh
Tetradic	H + 90°, H + 180°, H + 270°	90° apart	Complex but harmonious

Example: Building Palette from Blue (210°)

Primary Blue: 210° (hsl(210, 70%, 50%))

Analogous (210° ± 30°):
- 180° Cyan
- 210° Blue ← Primary
- 240° Indigo

Complementary:
- 30° Orange

Triadic:
- 210° Blue
- 330° Magenta
- 90° Yellow-Green

1.3 Tints, Shades, and Tones

:root {
  /* Base color */
  --hue-primary: 210;
  --sat-primary: 70%;

  /* Tints (increase lightness) */
  --color-primary-50: hsl(var(--hue-primary), var(--sat-primary), 95%);
  --color-primary-100: hsl(var(--hue-primary), var(--sat-primary), 90%);
  --color-primary-200: hsl(var(--hue-primary), var(--sat-primary), 80%);
  --color-primary-300: hsl(var(--hue-primary), var(--sat-primary), 70%);
  --color-primary-400: hsl(var(--hue-primary), var(--sat-primary), 60%);

  /* Core */
  --color-primary-500: hsl(var(--hue-primary), var(--sat-primary), 50%);
  --color-primary-600: hsl(var(--hue-primary), var(--sat-primary), 40%);

  /* Shades (decrease lightness) */
  --color-primary-700: hsl(var(--hue-primary), var(--sat-primary), 30%);
  --color-primary-800: hsl(var(--hue-primary), var(--sat-primary), 20%);
  --color-primary-900: hsl(var(--hue-primary), var(--sat-primary), 10%);
}

1.4 Color Psychology

Color	Hue	Psychology	UI Uses
Red	0°	Energy, urgency, danger	Error states, delete actions, alerts
Orange	30°	Enthusiasm, warmth	Friendly CTAs, warnings
Yellow	60°	Happiness, caution	Warning messages, highlights
Green	120°	Growth, safety, success	Success states, "go" actions
Blue	240°	Trust, stability, calm	Primary brand, links, info
Purple	270°	Creativity, luxury	Premium features, AI/magic
Gray	Neutral	Balance, sophistication	Secondary actions, disabled

1.5 The 60-30-10 Rule

60% - Primary (dominant, background/large areas)
30% - Secondary (supporting, surface colors)
10% - Accent (emphasis, CTAs, highlights)

:root {
  /* 60% - Primary: light neutral background */
  --color-60: #F5F5F5;

  /* 30% - Secondary: surface/card color */
  --color-30: #FFFFFF;

  /* 10% - Accent: brand for CTAs */
  --color-10: #0EA5E9;
}

body { background: var(--color-60); }
.card { background: var(--color-30); }
button { background: var(--color-10); }

1.6 WCAG Contrast Requirements

Content Type	Minimum Ratio	Example
Normal text	4.5:1	Black on white = 21:1 ✓
Large text (18px+)	3:1	Navy on light blue = 8.6:1 ✓
UI components	3:1	Button border on background
Focus indicator	3:1	Focus outline on element

Quick Reference: Common Contrast Ratios

White #FFFFFF on:
- Black #000000 = 21:1 ✓ Excellent
- Navy #003366 = 11.3:1 ✓ Excellent
- Blue #0EA5E9 = 5.74:1 ✓ Good (AA)
- Gray #6B7280 = 7.5:1 ✓ Good (AAA)
- Light gray #D1D5DB = 2.1:1 ✗ Fail

1.7 Dark Mode Strategy

Key Principle: Adjust LIGHTNESS and SATURATION, not HUE.

/* Light Mode */
:root {
  --color-primary: hsl(210, 70%, 50%);
  --color-text: hsl(0, 0%, 15%);
  --color-bg: hsl(0, 0%, 97%);
}

/* Dark Mode */
@media (prefers-color-scheme: dark) {
  :root {
    /* Brighter, less saturated for dark backgrounds */
    --color-primary: hsl(210, 60%, 65%);

    /* Text: white with opacity */
    --color-text: hsla(0, 0%, 100%, 0.87);
    --color-text-secondary: hsla(0, 0%, 100%, 0.60);

    /* Background: dark neutral */
    --color-bg: hsl(0, 0%, 12%);
    --color-surface: hsl(0, 0%, 18%);
  }
}

Dark Mode Elevation (Lighter = More Elevated)

@media (prefers-color-scheme: dark) {
  :root {
    --color-surface-base: hsl(210, 10%, 12%);    /* Darkest */
    --color-surface-1: hsl(210, 10%, 16%);       /* Raised */
    --color-surface-2: hsl(210, 10%, 20%);       /* More raised */
    --color-surface-3: hsl(210, 10%, 24%);       /* Even more */
    --color-surface-4: hsl(210, 10%, 28%);       /* Highest */
  }

  body { background: var(--color-surface-base); }
  .card { background: var(--color-surface-2); }
  .modal { background: var(--color-surface-3); }
}

---

PART 2: TYPOGRAPHY SYSTEM

2.1 Type Scale Ratios

Ratio	Name	Best For
1.067	Minor Second	Small UI, dense
1.125	Major Second	Apps, compact
1.200	Minor Third	Balanced web
1.250	Major Third	Web apps (recommended)
1.333	Perfect Fourth	Editorial
1.414	Augmented Fourth	Magazine
1.500	Perfect Fifth	Large displays
1.618	Golden Ratio	Art, luxury

Complete Type Scale (1.25 ratio, 16px base)

-2 (11px) - caption, small labels
-1 (13px) - fine print, helper text
 0 (16px) - body text, default
 1 (20px) - subheading, emphasis
 2 (25px) - section heading
 3 (31px) - large section heading
 4 (39px) - page heading
 5 (49px) - hero text

2.2 Fluid Typography with clamp()

:root {
  --text-xs: clamp(11px, 1.5vw, 13px);
  --text-sm: clamp(12px, 1.8vw, 14px);
  --text-base: clamp(14px, 2vw, 16px);
  --text-md: clamp(16px, 2.2vw, 18px);
  --text-lg: clamp(18px, 2.5vw, 20px);
  --text-xl: clamp(20px, 3vw, 24px);
  --text-2xl: clamp(24px, 4vw, 30px);
  --text-3xl: clamp(28px, 5vw, 36px);
  --text-4xl: clamp(32px, 6vw, 42px);
  --text-5xl: clamp(36px, 8vw, 52px);
}

body { font-size: var(--text-base); }
h3 { font-size: var(--text-2xl); }
h2 { font-size: var(--text-3xl); }
h1 { font-size: var(--text-5xl); }

2.3 Line Height Guidelines

Context	Line Height	Usage
Body text	1.5 - 1.7	Comfortable reading
Headings	1.1 - 1.3	Compact, readable
Dense UI	1.4 - 1.5	Forms, lists
Code/mono	1.6 - 1.8	Extra clarity

p { line-height: 1.6; }
h1, h2, h3 { line-height: 1.2; }
label { line-height: 1.5; }
code { line-height: 1.7; }

2.4 Line Length (Measure)

Optimal: 45-75 characters (65ch ideal)

.prose {
  max-width: 65ch;  /* ~65 characters */
  margin: 0 auto;
}

2.5 Font Weight Usage

Weight	Name	Usage
400	Regular	Body text (default)
500	Medium	Subtle emphasis, labels
600	Semi-bold	UI elements, captions
700	Bold	Strong emphasis, headings

Rule: Use only 2-3 weights for clarity (400, 600, 700)

body { font-weight: 400; }
label { font-weight: 600; }
h1, h2, strong { font-weight: 700; }

2.6 Font Pairing

Heading	Body	Best For
Poppins	Inter	Tech, SaaS
Playfair Display	Lato	Luxury, editorial
Montserrat	Open Sans	Modern, friendly

:root {
  --font-display: 'Poppins', sans-serif;
  --font-body: 'Inter', -apple-system, sans-serif;
  --font-mono: 'Fira Code', monospace;
}

h1, h2, h3 { font-family: var(--font-display); }
body { font-family: var(--font-body); }
code { font-family: var(--font-mono); }

---

PART 3: SPACING & RHYTHM SYSTEMS

3.1 8-Point Grid System

Token	Value	Usage
0.5	2px	Hairlines, minimal
1	4px	Micro spacing
2	8px	Small gaps (xs)
3	12px	Compact
4	16px	Standard (sm)
5	20px	Medium
6	24px	Comfortable (md)
8	32px	Large (lg)
10	40px	Extra large (xl)
12	48px	Huge (2xl)
16	64px	Page spacing (3xl)
20	80px	Section gaps
24	96px	Hero spacing

:root {
  --space-0: 0;
  --space-0-5: 2px;
  --space-1: 4px;
  --space-2: 8px;
  --space-3: 12px;
  --space-4: 16px;
  --space-5: 20px;
  --space-6: 24px;
  --space-8: 32px;
  --space-10: 40px;
  --space-12: 48px;
  --space-16: 64px;
  --space-20: 80px;
  --space-24: 96px;
}

.btn { padding: var(--space-2) var(--space-4); }  /* 8px 16px */
.card { padding: var(--space-6); }                 /* 24px */
section { padding: var(--space-16) 0; }            /* 64px */

3.2 Fibonacci Spacing (Alternative)

8 × 1  = 8px
8 × 2  = 16px
8 × 3  = 24px
8 × 5  = 40px
8 × 8  = 64px
8 × 13 = 104px
8 × 21 = 168px

Use Fibonacci for: Editorial, landing pages, organic feel Use 8-Point for: Apps, forms, UI components

3.3 Golden Ratio Spacing (1.618)

:root {
  --golden-1: 8px;
  --golden-2: 13px;   /* 8 × 1.618 */
  --golden-3: 21px;   /* 13 × 1.618 */
  --golden-4: 34px;
  --golden-5: 55px;
  --golden-6: 89px;
}

3.4 Proximity Principle

Rule: Related items < 16px apart, unrelated > 24px apart

.form-group {
  margin-bottom: 24px;  /* Between groups - LARGE */
}

.form-group label {
  margin-bottom: 8px;   /* Label to input - SMALL */
}

---

PART 4: LAYOUT COMPOSITION & GRIDS

4.1 Golden Ratio Layouts (1.618:1)

For container W pixels wide:
Main content = W ÷ 1.618
Sidebar = W - Main content

1200px container:
Main: 742px, Sidebar: 458px

.golden-layout {
  display: grid;
  grid-template-columns: 1fr 0.618fr;
  gap: 24px;
  max-width: 1200px;
}

@media (max-width: 768px) {
  .golden-layout {
    grid-template-columns: 1fr;
  }
}

4.2 Rule of Thirds

Place focal points at grid intersections for natural visual flow.

.rule-of-thirds {
  display: grid;
  grid-template-columns: 1fr 1fr 1fr;
  grid-template-rows: 1fr 1fr 1fr;
}

.focal-point {
  grid-column: 2 / 3;
  grid-row: 1 / 2;
  place-self: end;
}

4.3 12-Column Grid

.grid-12 {
  display: grid;
  grid-template-columns: repeat(12, 1fr);
  gap: 24px;
  max-width: 1200px;
}

.col-4 { grid-column: span 4; }   /* 33% */
.col-6 { grid-column: span 6; }   /* 50% */
.col-8 { grid-column: span 8; }   /* 66% */
.col-12 { grid-column: span 12; } /* 100% */

4.4 Container Widths

Size	Width	Use Case
xs	480px	Mobile
sm	640px	Large mobile
md	768px	Tablet
lg	1024px	Desktop
xl	1280px	Wide desktop
2xl	1536px	Maximum

.container {
  max-width: 1024px;
  margin: 0 auto;
  padding: 0 24px;
}

.prose-container {
  max-width: 65ch;  /* Readable */
}

4.5 Auto-Fit Responsive Grids

.grid-responsive {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
  gap: 24px;
}

---

PART 5: VISUAL HIERARCHY & BALANCE

5.1 Creating Hierarchy

Size (1.2-1.5× each level)

.caption { font-size: 13px; }
.body { font-size: 16px; }
.subhead { font-size: 20px; }
.h3 { font-size: 25px; }
.h2 { font-size: 31px; }
.h1 { font-size: 39px; }

Color (Opacity)

.text-primary { color: rgba(0, 0, 0, 0.87); }
.text-secondary { color: rgba(0, 0, 0, 0.60); }
.text-tertiary { color: rgba(0, 0, 0, 0.38); }
.text-disabled { color: rgba(0, 0, 0, 0.26); }

Weight

.body { font-weight: 400; }
.label { font-weight: 500; }
.subhead { font-weight: 600; }
.h1 { font-weight: 700; }

5.2 Gestalt Principles

Principle	Rule	CSS Example
Proximity	Related < 16px	gap: 8px between label and input
Similarity	Same style = related	All buttons have same padding
Continuity	Aligned elements are path	align-items: start
Closure	Mind completes shapes	Dashed borders, outlined buttons
Figure-Ground	Elevated stands out	Cards with shadow on page

5.3 Focal Point Creation

.cta-primary {
  background: var(--color-primary);
  color: white;
  padding: 16px 32px;
  font-size: 18px;
  font-weight: 600;
  border-radius: 8px;
  box-shadow: 0 8px 16px rgba(0,0,0,0.15);
  margin: 48px 0;  /* Isolated */
}

.cta-primary:hover {
  transform: translateY(-2px);
  box-shadow: 0 12px 24px rgba(0,0,0,0.2);
}

---

PART 6: WCAG 2.2 ACCESSIBILITY (2024-2025)

6.1 All 9 New WCAG 2.2 Criteria

2.4.11 Focus Not Obscured (Minimum) - Level A

*:focus {
  scroll-margin-top: 80px;  /* Account for sticky header */
}

2.4.12 Focus Not Obscured (Enhanced) - Level AA

No part of focused component hidden.

2.4.13 Focus Appearance - Level AAA

2px thick, 3:1 contrast.

button:focus-visible {
  outline: 2px solid #0066CC;  /* 5.7:1 contrast ✓ */
  outline-offset: 2px;
}

2.5.7 Dragging Movements - Level AA

Provide single-pointer alternative to drag.

<input type="range" id="slider">
<button onclick="setValue(0)">Min</button>
<button onclick="setValue(100)">Max</button>

2.5.8 Target Size (Minimum) - Level AA

24×24px minimum, 44×44px recommended

button, a, input[type="checkbox"] {
  min-width: 24px;
  min-height: 24px;
}

.btn {
  min-width: 44px;
  min-height: 44px;
}

.icon-btn {
  width: 20px;
  height: 20px;
  padding: 12px;  /* Total: 44×44px */
}

3.2.6 Consistent Help - Level A

Help in same location on all pages.

3.3.7 Redundant Entry - Level A

Don't ask for same info twice. Use autocomplete.

3.3.8 Accessible Authentication (Minimum) - Level AA

No CAPTCHA as ONLY option.

<button onclick="sendEmailLink()">Email me a sign-in link</button>
<button onclick="useWebAuthn()">Sign in with passkey</button>
<input type="password" autocomplete="current-password">

3.3.9 Accessible Authentication (Enhanced) - Level AAA

No cognitive test at all.

6.2 Complete Focus Implementation

*:focus { outline: none; }

*:focus-visible {
  outline: 2px solid var(--color-primary);
  outline-offset: 2px;
}

@media (prefers-contrast: more) {
  *:focus-visible {
    outline-width: 3px;
    outline-color: Highlight;
  }
}

.skip-link {
  position: absolute;
  top: -100px;
}

.skip-link:focus {
  top: 8px;
  left: 8px;
  padding: 12px 16px;
  background: white;
}

---

PART 7: MICROINTERACTIONS & ANIMATION

7.1 Animation Timing

Duration	Name	Use Case
100-150ms	Micro	Instant feedback, hover
150-200ms	Fast	Click, press
200-300ms	Normal	Standard UI, modal
300-400ms	Moderate	Panel slide
400-500ms	Slow	Page transition

:root {
  --duration-micro: 100ms;
  --duration-fast: 150ms;
  --duration-normal: 250ms;
  --duration-moderate: 350ms;
  --duration-slow: 450ms;
}

7.2 Easing Curves

:root {
  /* Entrances: fast start, slow end */
  --ease-out: cubic-bezier(0, 0, 0.2, 1);

  /* Exits: slow start, fast end */
  --ease-in: cubic-bezier(0.4, 0, 1, 1);

  /* State changes */
  --ease-in-out: cubic-bezier(0.4, 0, 0.2, 1);

  /* Standard */
  --ease-standard: cubic-bezier(0.4, 0, 0.6, 1);
}

.modal-enter { animation: fadeIn 250ms var(--ease-out); }
.modal-exit { animation: fadeOut 200ms var(--ease-in); }
button:hover { transition: all 150ms var(--ease-standard); }

7.3 Reduced Motion Support

@media (prefers-reduced-motion: reduce) {
  *,
  *::before,
  *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
    scroll-behavior: auto !important;
  }
}

---

PART 8: AVOIDING AI-GENERIC DESIGN

8.1 Anti-Patterns to Avoid

Blue/Purple Gradients

/* ❌ AI-GENERIC */
.hero { background: linear-gradient(135deg, #667eea, #764ba2); }

/* ✅ DISTINCTIVE */
.hero { background: var(--brand-primary); }

Excessive Rounding

/* ❌ AI-GENERIC */
* { border-radius: 12px; }

/* ✅ DISTINCTIVE - Strategic rounding */
.card { border-radius: 8px; }
.button { border-radius: 6px; }
.badge { border-radius: 16px; }
.input { border-radius: 4px; }

Safe Sans-Serif Only

/* ❌ AI-GENERIC */
body { font-family: -apple-system, sans-serif; }

/* ✅ DISTINCTIVE */
:root {
  --font-display: 'Poppins', sans-serif;
  --font-body: 'Inter', -apple-system, sans-serif;
}

8.2 Creating Distinctive Aesthetics

:root {
  /* Brand-named colors, not generic "primary" */
  --color-ocean: #0891B2;
  --color-sunset: #F59E0B;
  --color-forest: #10B981;

  /* Intentional radius strategy */
  --radius-sm: 4px;
  --radius-brand: 6px;
  --radius-lg: 8px;
}

/* Distinctive hover */
.btn:hover {
  transform: translateY(-2px) scale(1.02);
  box-shadow: 0 8px 16px rgba(0,0,0,0.15);
}

---

PART 9: IMPLEMENTATION WORKFLOWS

9.1 Design Token Migration

# Find hardcoded colors
grep -rn "color: #\|background: #" src/components --include="*.vue"

# Find hardcoded spacing
grep -rn "padding: [0-9]\|margin: [0-9]" src/components --include="*.vue"

<!-- BEFORE -->
<style scoped>
.button {
  color: #4ECDC4;
  background: #000;
  padding: 12px 24px;
}
</style>

<!-- AFTER -->
<style scoped>
.button {
  color: var(--brand-primary);
  background: var(--surface-elevated);
  padding: var(--space-3) var(--space-6);
}
</style>

9.2 Button Consolidation

<!-- BEFORE -->
<button class="menu-icon-button" @click="handleClick">
  <TrashIcon />
</button>

<!-- AFTER -->
<BaseIconButton
  variant="ghost"
  size="sm"
  aria-label="Delete item"
  @click="handleClick"
>
  <TrashIcon />
</BaseIconButton>

9.3 Accessibility Implementation

# Find buttons without aria-label
grep -rn "<button" src/components --include="*.vue" | grep -v "aria-label"

<!-- Icon-only buttons MUST have aria-label -->
<BaseIconButton aria-label="Delete task" @click="deleteTask">
  <TrashIcon />
</BaseIconButton>

<!-- Decorative icons should be aria-hidden -->
<BaseButton @click="save">
  <CheckIcon aria-hidden="true" />
  Save Changes
</BaseButton>

9.4 Theme Consistency

# Find hardcoded white backgrounds
grep -rn "background.*white\|background.*#fff" src/components --include="*.vue"

<!-- BEFORE: Breaks in dark theme -->
<style>
.card { background: white; color: black; }
</style>

<!-- AFTER: Respects theme -->
<style>
.card {
  background: var(--surface-elevated);
  color: var(--text-primary);
}
</style>

---

PART 10: QUALITY CHECKLISTS

Color Checklist

• Primary color chosen with brand intention
• Accent colors from color wheel (complementary/triadic)
• 60-30-10 rule applied
• WCAG AA contrast verified (4.5:1 normal, 3:1 large)
• Dark mode uses same hue, adjusted S/L

Typography Checklist

• Type scale ratio chosen (1.25 recommended)
• Fluid sizing with clamp()
• Line heights: 1.5-1.7 body, 1.1-1.3 headings
• Line length: 65ch max
• Font weights: 400, 600, 700 only

Spacing Checklist

• 8-point grid implemented
• Semantic tokens defined
• Related items < 16px, unrelated > 24px
• Vertical rhythm maintained

Layout Checklist

• Golden ratio where appropriate
• 12-column grid for responsive
• Container widths: sm/md/lg/xl
• Whitespace used strategically

Accessibility Checklist (WCAG 2.2 AA)

• Focus indicators: 2px, 3:1 contrast
• Touch targets: ≥24px (44px recommended)
• Keyboard navigation complete
• Color not only indicator
• Contrast: 4.5:1 normal text
• Help consistent across pages
• No CAPTCHA-only auth
• Dragging has alternatives
• prefers-reduced-motion respected

Animation Checklist

• Timing: 100-500ms appropriate
• Easing: ease-out for entrances
• prefers-reduced-motion supported
• Animations serve purpose

Distinctiveness Checklist

• Brand colors intentional (not generic blue)
• Rounding strategic (not 12px everywhere)
• Typography has personality
• Hover states distinctive
• No AI-generic patterns

---

MANDATORY USER VERIFICATION REQUIREMENT

CRITICAL: Before claiming ANY issue is "fixed" or "complete":

1. Technical Verification: Run tests, verify no console errors
2. Ask User: Use AskUserQuestion to request verification
3. Wait for Confirmation: Do NOT claim success until user confirms

Remember: The user is the final authority on whether something is fixed.

---

PART 11: APP ICON GENERATION (Tauri/Desktop/PWA)

11.1 Icon Size Requirements

Platform	Sizes Required
Tauri/Desktop	32x32, 128x128, 256x256 (128x128@2x), 512x512
Windows ICO	16, 32, 48, 64, 128, 256 (multi-size)
macOS ICNS	512x512 source
Windows Store	44, 71, 89, 107, 142, 150, 284, 310
PWA/Web	180x180 (apple-touch-icon), favicon.ico

11.2 ImageMagick Icon Pipeline

CRITICAL: Scaling Without Cropping

When source image has different aspect ratio than target (e.g., wide 1312x736 → square 512x512):

# ❌ WRONG - Scales by height, crops width
magick convert source.png -resize x420 -gravity center -extent 512x512 icon.png

# ✅ CORRECT - Scales to FIT within bounds, centers with padding
magick convert source.png \
  -trim +repage \
  -resize 500x500 \
  -gravity center \
  -background none \
  -extent 512x512 \
  icon.png

Key insight: -resize 500x500 scales proportionally until the LARGER dimension hits 500px. For a wide image, width becomes 500px, height scales proportionally (e.g., ~280px). Then -extent 512x512 centers it with transparent padding.

Complete Icon Generation Script

#!/bin/bash
# Generate all Tauri app icons from a 512x512 source

cd src-tauri/icons

# PNG sizes for Linux/Windows
magick convert icon.png -resize 32x32 32x32.png
magick convert icon.png -resize 128x128 128x128.png
magick convert icon.png -resize 256x256 [e-mail]

# Windows ICO (multi-size)
magick convert icon.png -define icon:auto-resize=256,128,64,48,32,16 icon.ico

# macOS ICNS
png2icns icon.icns icon.png 2>/dev/null || \
  magick convert icon.png -resize 512x512 icon.icns

# Windows Store logos
for size in 44 71 89 107 142 150 284 310; do
  magick convert icon.png -resize ${size}x${size} Square${size}x${size}Logo.png
done
magick convert icon.png -resize 50x50 StoreLogo.png

# PWA/Web icons
cd ../../public
magick convert ../src-tauri/icons/icon.png -resize 180x180 apple-touch-icon.png
magick convert ../src-tauri/icons/icon.png -define icon:auto-resize=48,32,16 favicon.ico

echo "All icons generated!"

11.3 Image Processing for Icons

Remove Background (Flood Fill)

# Replace white/near-white background with transparency
magick convert input.png \
  -fuzz 10% \
  -transparent white \
  -trim +repage \
  output.png

Prepare Wide Image for Square Icon

# For images wider than tall (e.g., 1312x736)
magick convert wide-source.png \
  -trim +repage \              # Remove whitespace
  -resize 500x500 \            # Fit within 500x500 (maintains aspect)
  -gravity center \            # Center the result
  -background none \           # Transparent background
  -extent 512x512 \            # Pad to exact 512x512
  icon.png

11.4 Verification

# Check dimensions
magick identify icon.png
# Expected: icon.png PNG 512x512 512x512+0+0 ...

# Check ICO contains all sizes
magick identify icon.ico
# Expected: Multiple lines showing 256x256, 128x128, 64x64, etc.

11.5 Tauri Icon Files

src-tauri/icons/
├── icon.png          # 512x512 master (REQUIRED)
├── icon.ico          # Windows (multi-size)
├── icon.icns         # macOS
├── 32x32.png         # Small
├── 128x128.png       # Medium
├── [e-mail]    # Retina (256x256)
├── Square*.png       # Windows Store
└── StoreLogo.png     # Windows Store

11.6 Reinstall & Refresh (Linux/KDE)

After regenerating icons, rebuild and reinstall:

npm run tauri build
sudo dpkg -i src-tauri/target/release/bundle/deb/AppName_*.deb
kbuildsycoca6 --noincremental  # Rebuild KDE cache
kquitapp6 plasmashell && sleep 1 && kstart plasmashell &  # Restart panel

---

PART 12: KANBAN BOARD DESIGN

Industry-standard measurements based on research across Linear, Todoist, TickTick, Notion, Trello, GitHub Projects, and Asana.

12.1 Industry Consensus Measurements

These values appeared consistently across 5+ top apps:

Property	Industry Standard	FlowState Value
Card padding	8px (Trello, Linear, GitHub)	8px
Card border-radius	6-8px (Primer=6px, Trello=8px)	8px
Card background	Subtle surface, semi-transparent	rgba(35, 32, 55, 0.4)
Title font size	14px (universal)	14px
Title font weight	500 (medium, universal)	500
Title line-height	1.25	1.25 (1.3+ causes bloat — 2px/line adds up)
Metadata font size	12px (universal)	12px / var(--text-meta)
Metadata font weight	400 (regular)	400
Card-to-card gap	6-8px	6px
Column width	260-320px (272=Trello, 300=common)	300px
Column background	Transparent (Linear, GitHub, Notion)	transparent

12.2 Card Anatomy

┌────────────────────────────────────────┐
│ ● Title text here (14px/500)  [⊕][▶] │  ← priority dot + title + hover actions (HORIZONTAL)
│ Description preview max 2 lines...     │  ← 12px, --text-tertiary, line-clamp: 2
│ 📅 Jan 15  ☑ 3/5  🍅 2  [Tag1]      │  ← 12px badges + tags, same row
└────────────────────────────────────────┘
 6px gap to next card

Visual Hierarchy (3 tiers)

1. Primary (title): 14px, weight 500, --text-primary — scanned first
2. Secondary (description): 12px, weight 400, --text-tertiary — read if interested
3. Tertiary (badges/tags): 12px icons + text, --text-muted — glanced for context

12.3 Column Rules

• Columns are TRANSPARENT — cards are the visual focus
• Column header: title (13px, 600 weight) + count pill + add button
• No column background, no glass, no container border
• 1px left-border separator between columns (--glass-border-light)
• Column padding: var(--space-2) (8px)
• Tasks container gap: 6px between cards

12.4 Card Rules

Rule	Value	Rationale
Border-radius	8px	Industry standard (Primer medium, Trello post-2022)
Padding	8px	Matches Trello, Linear, GitHub. Anything >12px is "Asana-bulky"
Hover	border-color only	No translateY, no shadow. Linear/GitHub pattern
Action buttons	Hover-only, HORIZONTAL, position: absolute	MUST be absolutely positioned so they don't steal title width. In normal flow, 4 buttons = 80px width stolen = title wraps = card doubles in height
Action button size	18px	Minimal footprint, fits 4 in a row
Description	Optional, 12px, 2-line clamp	Linear/Todoist don't show it at all. TickTick shows snippet
Separator lines	NEVER	Visual hierarchy via font size/weight/color only
Empty metadata	Hidden	No empty footers, no empty badge rows
Card background	Semi-transparent (0.4 opacity)	Cards should breathe, not be opaque blocks
min-height	unset	Cards should be as small as their content

12.5 Anti-Patterns (Verified Against Industry)

Anti-Pattern	Why It's Wrong	Evidence
Glass morphism column containers	Distracting from cards	Linear, GitHub, Notion all use transparent
border-top separator in card	Visual noise	Zero top apps use internal separators
translateY hover lift + shadow	Floaty, not grounded	Only Trello uses shadow on hover (others: bg shift)
border-radius: 12px+ on cards	Too bubbly, wastes corner space	Primer=6px, Trello=8px, max industry=8px
padding: 12px+ on cards	Too spacious, "Asana problem"	Asana at 16px is criticized by own users
Vertical action button stack	Takes ~100px height, destroys density	All apps use horizontal row or single icon
Always-visible action buttons	Wastes space on every card	Asana's pattern, universally criticized
Description always visible	Adds height to every card	Linear/Todoist/GitHub don't show it

12.6 Progressive Disclosure Layers

Layer	Trigger	Content	Reference App
Glance (card face)	Always visible	Title + priority + 2-3 badges	All apps
Hover (<500ms dwell)	Mouse hover	Action buttons appear, border highlights	Linear, GitHub
Peek (keyboard)	Space bar / quick preview	Full description, all metadata	Linear only
Full Detail (click)	Click card	Everything: description, subtasks, comments	All apps

12.7 Reference App Card Comparison

App	Padding	Radius	Gap	Width	Column BG	Description	Actions
Linear	8px	6-8px	6-8px	260-280px	Transparent	Never	Hover context menu
Todoist	8-10px	8px	8px	260-280px	Transparent	Never	Minimal
TickTick	10-12px	8px	8px	375px	Light grey	Snippet	Hover icons
Trello	8px	8px	8px	272px	#f1f2f4	Never	Hover pencil
GitHub	8-12px	6px	8px	320px	Transparent	Never	Hover 3-dot
Notion	10-12px	6px	8px	260-300px	Transparent	Configurable	Open button
Asana	16px	8px	12-16px	300-340px	Light grey	Configurable	Always visible

12.8 FlowState Implementation Files

File	Controls	Override Source
global-overrides.css	ALL visual card/column styles (with !important)	Last-loaded, wins everything
TaskCard.css	Base card styles (overridden by above)	Component CSS
TaskCardActions.vue (scoped)	Action button layout	Scoped styles
TaskCardBadges.vue (scoped)	Badge layout	Scoped styles
KanbanColumn.css	Column base styles (overridden by global)	Component CSS
styles.css	--kanban-card-glass-bg token (overridden by global)	Design tokens

CRITICAL: Always edit global-overrides.css for kanban visual changes. Component CSS files are completely overridden by global !important rules.

12.9 CSS Debugging Protocol (MANDATORY for card size changes)

NEVER trust that top-level CSS properties (padding, radius, background) are the only thing controlling card size.

Step 1: Measure EVERY child element height

Before making any card CSS change, run this in Playwright/DevTools:

document.querySelectorAll('.task-card')[0].children  // Check ALL children
// For each child: getBoundingClientRect().height, getComputedStyle().margin/padding/display

Step 2: Known Hidden Space Wasters

Element	Trap	Fix
.card-details	Empty div with margin-top: 8px + padding-top: 8px + border-top = 17px wasted	display: none !important in global-overrides
.compact-actions (action buttons)	In normal flow = steals 80px title width, forces text wrap to 2+ lines, doubling card height	position: absolute !important — float over card, don't take layout space
.priority-dot	margin-inline-end: var(--space-3) = 12px right margin	Override to 4px
.task-title	line-height: 1.5 = 22.5px per line instead of 17.5px. Also margin-bottom: var(--space-1)	line-height: 1.25 !important; margin: 0 !important
.drag-area (vuedraggable)	display: block — CSS gap on parent .tasks-container doesn't reach cards	Must set .drag-area { display: flex; flex-direction: column; gap: 6px }

Step 3: Verify ACTUAL gap between cards

const cards = document.querySelectorAll('.task-card');
cards[1].getBoundingClientRect().top - cards[0].getBoundingClientRect().bottom
// If negative or 0, gap CSS is NOT working — check if parent is display:block

Step 4: CSS Specificity Stack (load order)

1. design-tokens.css     — CSS custom properties
2. styles.css            — base styles + some !important token overrides
3. Component .css/.vue   — TaskCard.css, KanbanColumn.css
4. Scoped <style>        — TaskCardActions.vue [data-v-xxx] (HIGHEST for component internals)
5. global-overrides.css  — !important on everything (wins for non-scoped selectors)

Scoped styles with !important beat global !important because of the [data-v-xxx] attribute selector. For scoped component internals (like .action-btn inside TaskCardActions.vue), you MUST either:

• Edit the scoped component directly, OR
• Use a more specific selector in global-overrides: .task-card .compact-actions .action-btn

Anti-Pattern: Surface-Level CSS Tweaking

WRONG approach (wastes hours):

"Card too big" → adjust padding from 12px to 8px → "still big" → adjust radius → "still big"

CORRECT approach (measure first):

"Card too big" → measure ALL children heights → find .card-details=17px, actions=80px width steal
→ fix root causes → card goes from 73px to 38px

---

PART 13: WEB STANDARDS & CODE QUALITY

Rules adapted from Vercel Web Interface Guidelines for Vue 3 / FlowState.

13.1 Forms Best Practices

Rule	Vue Implementation
Add autocomplete to inputs	<BaseInput autocomplete="email" type="email" />
Use correct type and inputmode	type="email" for email, inputmode="numeric" for codes
NEVER block paste	No @paste.prevent anywhere
Disable spellcheck on codes/emails	:spellcheck="false"
Labels clickable via wrapping or for	<label :for="inputId"> or wrap <label><input></label>
Submit button enabled until request	Show spinner during request, don't pre-disable
Errors inline next to fields	Focus first error on submit with el.focus()
Warn before nav with unsaved changes	onBeforeRouteLeave guard or beforeunload
No dead zones in checkbox/radio	Label + control share single hit target

<!-- CORRECT form pattern -->
<BaseInput
  v-model="email"
  type="email"
  autocomplete="email"
  :spellcheck="false"
  name="user-email"
  label="Email"
/>

13.2 Performance Rules

Rule	When	Implementation
Virtualize large lists	>50 items	Use content-visibility: auto or virtual scroll
No layout reads in render	Always	Never getBoundingClientRect() in computed/watch
Batch DOM reads/writes	When measuring	Read all, then write all — never interleave
Uncontrolled inputs preferred	High-frequency typing	Use defaultValue / @change over v-model for search
Preconnect CDN domains	Always	<link rel="preconnect" href="https://cdn.example.com">
Preload critical fonts	Above fold	<link rel="preload" as="font" crossorigin> with font-display: swap
Images need width/height	Always	Prevents CLS (Cumulative Layout Shift)
Below-fold images lazy	Always	loading="lazy"
Above-fold images priority	Hero/banner	fetchpriority="high"

13.3 Touch & Interaction

/* Prevent 300ms tap delay on ALL touch targets */
* { touch-action: manipulation; }

/* Set webkit tap highlight intentionally */
button, a { -webkit-tap-highlight-color: rgba(78, 205, 196, 0.1); }

/* Contain scroll in modals/drawers/overlays */
.modal-overlay, .drawer, .bottom-sheet {
  overscroll-behavior: contain;
}

/* During drag: disable text selection */
.dragging {
  user-select: none;
  -webkit-user-select: none;
}

• autoFocus sparingly — desktop only, single primary input; avoid on mobile
• Full-bleed layouts need env(safe-area-inset-*) for notched devices

13.4 Content Handling

/* Text containers MUST handle overflow */
.truncate {
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
}

/* Multi-line clamp */
.line-clamp-2 {
  display: -webkit-box;
  -webkit-line-clamp: 2;
  -webkit-box-orient: vertical;
  overflow: hidden;
}

/* CRITICAL: flex children need min-width: 0 for truncation */
.flex-child { min-width: 0; }

• ALWAYS handle empty states — show helpful message, not broken UI
• User-generated content: anticipate short, average, and very long inputs
• Use break-words or overflow-wrap: break-word for URLs/long strings

Compact Chips & Pills in Constrained Panels (SOP-066)

When placing chips/pills in bottom sheets or modals with fixed max-width:

Pitfall	Fix
flex: 1 (= flex: 1 1 0%) starts element at 0 width — text truncates even with overflow: visible	Use flex: 0 0 auto for natural content width
-webkit-line-clamp persists through overrides	Must explicitly set -webkit-line-clamp: unset AND -webkit-box-orient: unset
overflow-x: auto + overflow-y: visible = both become auto (CSS spec)	Don't mix; use min-width: 0 on flex parent + overflow-x: auto only
display: inline inside flex container is blockified (CSS spec)	Use display: block instead
Selected chip outline/border clipped by parent padding: 0	Add padding: var(--space-1) var(--space-2) to grid container
Compact focus states too heavy (3px outline + offset)	Override to outline: none; border-color: var(--brand-primary) in compact mode

Reference: docs/sop/SOP-066-compact-chip-overflow.md

13.5 Navigation & URL State

• URL MUST reflect state — filters, tabs, pagination, sort order in query params
• Links use <RouterLink> (supports Cmd+click, middle-click, right-click)
• Deep-link all stateful UI — if it uses ref(), consider URL sync via useRouteQuery
• Destructive actions (delete, discard) need ConfirmationModal — NEVER immediate
• Back button must work correctly with all view states

13.6 Typography Micro-Rules

Rule	Example
Use ellipsis character ... not three dots	Loading... not Loading...
Use curly quotes in UI copy	"Welcome back" not "Welcome back"
Non-breaking spaces in units	10 MB, Cmd K
font-variant-numeric: tabular-nums	Number columns, prices, timers, stats
text-wrap: balance on headings	Prevents widows/orphans
Active voice in UI copy	"Save changes" not "Changes will be saved"
Specific button labels	"Save API Key" not "Continue" or "Submit"
Error messages include next step	"File too large. Max size is 10 MB." not just "Error"

13.7 Dark Mode & Theming (FlowState-Specific)

/* Already set in FlowState — verify these exist */
html { color-scheme: dark; }

/* Native <select>: explicit bg and color (Windows dark mode fix) */
select {
  background-color: var(--surface-component);
  color: var(--text-primary);
}

/* theme-color should match page background */
<meta name="theme-color" content="var(--bg-primary)">

13.8 Code Anti-Patterns (ALWAYS FLAG)

When reviewing or writing code, flag these immediately:

Anti-Pattern	Fix
user-scalable=no or maximum-scale=1	Remove — don't disable zoom
@paste.prevent	Remove — never block paste
transition: all	List properties explicitly
outline: none without :focus-visible	Add focus-visible replacement
<div @click> or <span @click>	Use <button> or <BaseButton>
<img> without width/height	Add dimensions to prevent CLS
.map() on 50+ items without virtualization	Add virtual scroll
<input> without <label> or aria-label	Add accessible label
Icon button without aria-label	<BaseIconButton aria-label="...">
Hardcoded date formats (MM/DD/YYYY)	Use Intl.DateTimeFormat
Hardcoded number formats ($${n})	Use Intl.NumberFormat
v-html with user content	Sanitize first or use MarkdownRenderer

---

PART 14: CODE AUDIT MODE

When asked to "review UI", "audit design", or "check accessibility", output findings in terse file:line format:

src/components/TaskCard.vue:42 — icon button missing aria-label
src/components/Modal.vue:18 — outline:none without focus-visible replacement
src/views/BoardView.vue:95 — <div @click> should be <button>
src/components/SearchBar.vue:12 — transition: all, list properties explicitly

Audit Checklist

1. Accessibility: aria-labels, semantic HTML, focus states, heading hierarchy, target sizes
2. Performance: CLS (image dimensions), virtualization, transition:all, layout reads
3. Forms: autocomplete, input types, labels, paste blocking, spellcheck
4. Touch: touch-action, overscroll-behavior, safe areas, tap highlight
5. Content: overflow handling, empty states, long content, min-w-0 on flex children
6. Design tokens: hardcoded colors, spacing, radii (should use CSS vars)
7. Anti-patterns: div-as-button, disabled zoom, hardcoded formats, v-html

---

Skill Keywords: UI design, UX, color theory, typography, spacing, layout, grid, accessibility, WCAG 2.2, animation, design tokens, visual hierarchy, Gestalt, app icons, ImageMagick, Tauri, web standards, forms, performance, touch, code audit

Standards: WCAG 2.2 (June 2024), Vercel Web Interface Guidelines, Material Design 3, Apple HIG

Last Updated: March 2026