微信扫一扫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
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":
- Technical Verification: Run tests, verify no console errors
- Ask User: Use
AskUserQuestionto request verification - 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 128x128@2x.png
# 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
├── 128x128@2x.png # 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
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
Standards: WCAG 2.2 (June 2024), Material Design 3, Apple HIG
Last Updated: January 2026