UI/UX Design Skill

Professional design specifications with anti-template principles

Skill Metadata

name: uiux-design
version: 1.0.0
description: Professional UI/UX design with enterprise standards and anti-AI-template rules
triggers:
  - /uiux-design
  - /design-spec
  - /ui-spec
dependencies:
  - skill: product-research (for competitor design patterns)
  - mcp: chrome-devtools
  - tool: WebFetch

Core Principles

1. Anti-Template Design Philosophy

We create distinctive, professional interfaces - NOT generic AI outputs

The goal is to produce designs that:

• Look like they came from a professional design agency
• Have clear brand identity and personality
• Feel intentional, not randomly generated
• Stand out from the sea of AI-generated sameness

2. Evidence-Based Design Decisions

Every design choice must have rationale:

• User research backing
• Competitor analysis insights
• Accessibility compliance
• Performance considerations

3. Component-First Architecture

Design with implementation in mind:

• Use established component libraries
• Maintain consistent design tokens
• Document interaction states
• Specify responsive behaviors

PROHIBITED Design Patterns

🚫 ABSOLUTELY FORBIDDEN

1. The "AI Gradient" Look

BANNED:
❌ Blue-to-purple gradients (the universal AI cliche)
❌ Teal-to-cyan gradients
❌ Pink-to-orange "sunset" gradients on hero sections
❌ Gradient text (especially on headings)
❌ Gradient borders without strong brand justification

Why: These scream "generated by AI" and lack brand differentiation.

2. Generic Typography

BANNED:
❌ System default fonts without customization
❌ Inter as the only font (overused in tech)
❌ Poppins without supporting fonts (overused)
❌ Single font family for everything
❌ Font sizes without clear hierarchy

Why: Typography is brand identity. Defaults = no identity.

3. Template Layouts

BANNED:
❌ Centered hero with gradient background + floating mockup
❌ Three-column feature grid with icons above text
❌ Testimonial carousel with circular avatars
❌ Footer with 4 equal columns
❌ "Built with ❤️" footer text
❌ Floating abstract shapes as decoration

Why: These patterns appear on every AI-generated landing page.

4. Illustration Cliches

BANNED:
❌ Undraw/Humaaans-style flat illustrations
❌ Abstract 3D shapes (blobs, rings, spheres)
❌ Isometric illustrations without brand style
❌ Stock illustrations not customized to brand colors
❌ Decorative gradients behind illustrations

Why: These are instantly recognizable as template assets.

5. Color Anti-Patterns

BANNED:
❌ Pure #000000 black for text
❌ Pure #FFFFFF white backgrounds without texture
❌ Rainbow gradients or pride flags as decoration (not brand)
❌ More than 5 colors in primary palette
❌ Colors without accessibility verification

MANDATORY Design Standards

✅ Typography Requirements

Font Selection Criteria

REQUIRED:
✅ Primary font: Professional, distinctive, readable
   Examples: Söhne, Circular, Untitled Sans, GT Walsheim

✅ Secondary font: Complementary contrast
   Examples: If sans primary, consider serif for headings or vice versa

✅ Monospace font: For code/data
   Examples: JetBrains Mono, Fira Code, IBM Plex Mono

✅ Font pairing rationale documented
✅ Fallback stack specified
✅ Variable fonts when available for performance

Type Scale System

REQUIRED: Consistent modular scale

Base: 16px (1rem)
Scale ratio: 1.25 (Major Third) or 1.333 (Perfect Fourth)

--text-xs: 0.75rem (12px)
--text-sm: 0.875rem (14px)
--text-base: 1rem (16px)
--text-lg: 1.125rem (18px)
--text-xl: 1.25rem (20px)
--text-2xl: 1.5rem (24px)
--text-3xl: 1.875rem (30px)
--text-4xl: 2.25rem (36px)
--text-5xl: 3rem (48px)

✅ Color System Requirements

Color Psychology Foundation

REQUIRED: Document psychological rationale

Primary Color Selection:
├── Emotional association (trust, energy, calm, etc.)
├── Industry appropriateness
├── Competitor differentiation
└── Cultural considerations

Example Documentation:
"Primary: Deep Forest Green (#2D5A3D)
 Rationale: Conveys stability and growth (financial product).
 Differentiator: Competitors use blue (Stripe, PayPal) - green stands out.
 Psychology: Green = money, prosperity, trust in financial contexts."

Color Palette Structure

REQUIRED: Semantic color system

--color-primary-50 through --color-primary-900
--color-gray-50 through --color-gray-900
--color-success: Green tones
--color-warning: Amber/Yellow tones
--color-error: Red tones
--color-info: Blue tones

Background colors:
--bg-primary: Main background (NOT pure white)
--bg-secondary: Elevated surfaces
--bg-tertiary: Recessed areas

Text colors:
--text-primary: Main text (NOT pure black)
--text-secondary: Supporting text
--text-tertiary: Disabled/placeholder
--text-inverse: On dark backgrounds

Contrast Requirements (WCAG 2.1 AA)

MANDATORY:
✅ Normal text: 4.5:1 minimum contrast
✅ Large text (18px+ or 14px bold): 3:1 minimum
✅ UI components: 3:1 minimum
✅ Focus indicators: 3:1 minimum
✅ Document all color pairs with contrast ratios

✅ Component Library Selection

Approved Component Libraries

REQUIRED: Use established enterprise libraries

Tier 1 (Recommended):
├── shadcn/ui - Modern, customizable, accessible
├── Radix UI - Unstyled primitives, full control
└── Headless UI - Tailwind-integrated, accessible

Tier 2 (Acceptable):
├── Chakra UI - Good defaults, accessible
├── Mantine - Feature-rich, TypeScript-first
└── Ant Design - Enterprise-focused (customize theme!)

Tier 3 (Use with heavy customization):
├── Material UI - Only with significant theming
└── Bootstrap - Only if heavily restyled

BANNED:
❌ No component library (custom everything)
❌ Unmaintained libraries
❌ Libraries without accessibility support

Component Customization Requirements

REQUIRED for each component:
├── Custom color tokens applied
├── Custom typography applied
├── Border radius from design system
├── Spacing from design system
├── Animation timing from design system
└── Focus states verified for accessibility

✅ Design System References

Mandatory Study Before Designing

Study these design systems for patterns (NOT to copy):

Enterprise/Professional:
├── Stripe.com - Clean, confident, spacious
├── Linear.app - Fast, keyboard-first, dark mode done right
├── Vercel.com - Minimalist, performant, developer-focused
└── Notion.so - Content-first, playful yet professional

Consumer/Friendly:
├── Airbnb.design - Warm, human, accessible
├── Spotify.design - Bold, music-driven, dynamic
└── Apple HIG - Native feel, attention to detail

Developer Tools:
├── GitHub Primer - Systematic, documented, open
├── GitLab Pajamas - Comprehensive, accessible
└── Atlassian Design System - Extensive, enterprise-ready

✅ Spacing System

REQUIRED: 4px/8px base unit system

--space-0: 0
--space-1: 0.25rem (4px)
--space-2: 0.5rem (8px)
--space-3: 0.75rem (12px)
--space-4: 1rem (16px)
--space-5: 1.25rem (20px)
--space-6: 1.5rem (24px)
--space-8: 2rem (32px)
--space-10: 2.5rem (40px)
--space-12: 3rem (48px)
--space-16: 4rem (64px)
--space-20: 5rem (80px)
--space-24: 6rem (96px)

✅ Border Radius System

REQUIRED: Consistent corner treatments

--radius-none: 0
--radius-sm: 0.25rem (4px)
--radius-md: 0.5rem (8px)
--radius-lg: 0.75rem (12px)
--radius-xl: 1rem (16px)
--radius-2xl: 1.5rem (24px)
--radius-full: 9999px

Usage guidelines:
├── Buttons: --radius-md or --radius-lg
├── Cards: --radius-lg or --radius-xl
├── Inputs: --radius-md
├── Avatars: --radius-full
└── Modals: --radius-xl

Design Specification Format

Page Layout Template

## Page: [Page Name]

### Purpose
[Why this page exists in the user journey]

### User Goals
1. [Primary goal]
2. [Secondary goal]

### Layout Structure

┌─────────────────────────────────────────────┐ │ Header │ ├──────────────┬──────────────────────────────┤ │ Sidebar │ Main Content │ │ (optional) │ │ │ │ ┌─────────────────────────┐ │ │ │ │ Section 1 │ │ │ │ └─────────────────────────┘ │ │ │ ┌─────────────────────────┐ │ │ │ │ Section 2 │ │ │ │ └─────────────────────────┘ │ ├──────────────┴──────────────────────────────┤ │ Footer (optional) │ └─────────────────────────────────────────────┘

### Components Used
| Component | Library | Customizations |
|-----------|---------|----------------|
| Button | shadcn/ui | Primary variant with custom colors |
| Card | shadcn/ui | Custom shadow, rounded-xl |

### Responsive Behavior
| Breakpoint | Changes |
|------------|---------|
| Mobile (<640px) | Stack layout, hide sidebar |
| Tablet (640-1024px) | Collapsible sidebar |
| Desktop (>1024px) | Full layout |

### States
| State | Visual Treatment |
|-------|------------------|
| Loading | Skeleton placeholders |
| Empty | Illustration + CTA |
| Error | Error message + retry |

Component Specification Template

## Component: [Component Name]

### Purpose
[What problem this component solves]

### Anatomy

┌─────────────────────────────────────┐ │ ┌─────┐ ┌────┐ │ │ │Icon │ Label │Badge│ │ │ └─────┘ └────┘ │ │ Description text here │ └─────────────────────────────────────┘

### Props/Variants
| Prop | Type | Options | Default |
|------|------|---------|---------|
| variant | string | 'primary', 'secondary', 'ghost' | 'primary' |
| size | string | 'sm', 'md', 'lg' | 'md' |
| disabled | boolean | true/false | false |

### States
| State | Visual | Tokens |
|-------|--------|--------|
| Default | Filled background | bg: primary-600, text: white |
| Hover | Darker background | bg: primary-700 |
| Active/Pressed | Even darker | bg: primary-800 |
| Focus | Ring visible | ring: primary-500, ring-offset: 2px |
| Disabled | Muted | bg: gray-200, text: gray-400 |

### Accessibility
- Role: button
- Keyboard: Enter/Space to activate
- Focus: Visible focus ring
- ARIA: aria-label if icon-only

### Usage Guidelines
DO:
- Use primary for main CTA
- Use secondary for alternative actions

DON'T:
- Use more than one primary button per section
- Use for navigation (use links instead)

Accessibility Checklist

WCAG 2.1 AA Compliance

MANDATORY for every design:

Perceivable:
├── [ ] Color contrast verified (4.5:1 text, 3:1 UI)
├── [ ] Color not sole indicator (icons, patterns)
├── [ ] Text resizable to 200% without loss
├── [ ] Images have alt text specifications
└── [ ] Audio/video have caption provisions

Operable:
├── [ ] All interactive elements keyboard accessible
├── [ ] Focus order logical and visible
├── [ ] No keyboard traps
├── [ ] Touch targets minimum 44x44px
├── [ ] No flashing content (>3 per second)
└── [ ] Skip links for repeated content

Understandable:
├── [ ] Language specified
├── [ ] Consistent navigation
├── [ ] Error prevention and recovery
├── [ ] Form labels and instructions clear
└── [ ] Predictable interactions

Robust:
├── [ ] Valid semantic HTML specified
├── [ ] ARIA used correctly where needed
├── [ ] Works with assistive technologies
└── [ ] Future-compatible patterns

Output Requirements

Deliverable: UI/UX Specification Document

# UI/UX Specification: [Product Name]

## Design System Foundation

### Brand Personality
[3-5 adjectives that define the visual identity]

### Color Palette
[Full palette with rationale and contrast ratios]

### Typography
[Font selections with pairing rationale]

### Spacing & Layout
[Grid system and spacing tokens]

## Component Library

### Selected Library: [Name]
[Justification for selection]

### Custom Components
[Any components not from library]

## Page Specifications

### [Page 1 Name]
[Full specification using template]

### [Page 2 Name]
[Full specification using template]

## Interaction Patterns

### Micro-interactions
[Hover, focus, transition specifications]

### Loading States
[Skeleton, spinner, progress patterns]

### Empty States
[Illustration and messaging approach]

### Error States
[Error messaging and recovery flows]

## Responsive Strategy

### Breakpoints
[Mobile, tablet, desktop specifications]

### Adaptive Components
[How components change across breakpoints]

## Accessibility Report

### Compliance Level
[WCAG 2.1 AA certification]

### Key Considerations
[Specific accessibility implementations]

## Appendix

### Design Tokens (JSON)
[Exportable token file]

### Component Checklist
[Implementation verification list]

Quality Gates

Design Review Checklist

• No prohibited patterns used (gradients, templates, etc.)
• Color palette has psychological rationale
• Typography has clear hierarchy
• Component library selected and justified
• All pages have responsive specifications
• All components have state specifications
• Accessibility audit complete
• Design tokens documented
• Interaction patterns specified

Quality Score Rubric

Integration Points

Receives From:

• product-research skill (competitor design patterns)
• User requirements (brand guidelines, preferences)

Feeds Into:

• architecture-design skill (component requirements)
• dev-documentation skill (implementation guide)

Version History