UI Design
Required when implementing visual design and styling interfaces. Enforces intentional aesthetics and systematic implementation to avoid generic patterns.
Core Principles
You must follow these non-negotiable principles:
- Intentionality over intensity - Bold maximalism and refined minimalism both work; generic mediocrity fails
- Design tokens are mandatory - Systematic values prevent inconsistency
- Avoid AI slop aesthetics - Generic patterns destroy brand identity
- Implementation matches vision - Maximalist designs require elaborate code; minimalist designs demand precision
- AI personalization requires ethics - Transparency and user control are non-negotiable
Mandatory Pre-Implementation
Never start coding without defining:
Aesthetic Direction (Required)
Commit to a bold aesthetic choice before implementation:
Tone Options:
- Brutalist (raw, functional, high contrast)
- Maximalist (layered, rich, abundant detail)
- Retro-futuristic (nostalgic tech, bold geometry)
- Organic (natural forms, flowing lines)
- Luxury (refined, elegant, spacious)
- Playful (unexpected, whimsical)
- Editorial (typographic hierarchy, grid-based)
- Art deco (geometric glamour, bold symmetry)
- Industrial (mechanical, utilitarian)
- Soft (gentle curves, muted tones)
State your chosen aesthetic and commit to it throughout implementation.
Generic "clean" and "modern" are not acceptable design directions.
Technical Context
Document before proceeding:
- Framework/library constraints
- Performance budget
- Browser/device support requirements
- Existing design system (if any)
- AI personalization needs
Design Token System (Non-Negotiable)
You must implement systematic design tokens. Never use magic numbers or arbitrary values.
Token Structure
Use three-tier system:
- Foundation tokens: Raw values (#3b82f6, 0.25rem)
- Semantic tokens: Purpose-driven (--color-primary, --space-base)
- Component tokens: Specific usage (--button-color-primary-bg)
Naming Convention
Use: category-property-variant-state structure.
Examples: --color-text-body, --button-color-primary-hover, --space-stack-large
Required Categories
- Color: primary, secondary, accent, text, background, surface, border, states
- Spacing: 8px base system (space-1 through space-24)
- Typography: Consistent scale (1.25 or 1.414 ratio)
- Border radius: sm, md, lg, xl, full
- Shadows: sm, md, lg, xl, 2xl
See @tokens.md for detailed token definitions and platform-specific generation.
Avoiding Generic AI Aesthetics
These patterns signal low-quality AI-generated design.
Forbidden Patterns
Typography: Inter/Roboto without justification, single font weight, uniform sizing Color: Purple-blue gradients by default, pastel without contrast, gray-on-gray-on-gray Layout: Everything centered equally, only card grids, no asymmetry, uniform spacing Motion: Decorative animations, simultaneous animations, fade-in only, no easing
Required Distinctiveness
Typography: Distinctive fonts with personality, contrasting weights (300/400 body, 600/700/800 headings), variable fonts Color: Dominant color + sharp accents, intentional contrast levels, documented usage Composition: Asymmetry, overlap for depth, diagonal flow, grid-breaking moments, negative space as design element
Frontend Implementation Guidelines
Typography Implementation
Use distinctive fonts with proper hierarchy. Never default to Inter/Roboto without justification.
Required elements:
- Font pairing (display + body)
- Weight hierarchy (300/400 for body, 600/700/800 for headings)
- Variable fonts for fluid control
- Proper line-height and letter-spacing
See @typography.md for implementation patterns and font loading.
Color & Theme Implementation
Use CSS custom properties for theme switching. Map semantic tokens to foundation tokens per theme.
Required contrast ratios:
- Text: 4.5:1 minimum (WCAG AA)
- Interactive components: 3:1 minimum
See @tokens.md for dark mode implementation patterns.
Motion & Animation
Prioritize high-impact moments over scattered effects.
Required:
- Proper easing curves (never linear)
- Respect prefers-reduced-motion
- Performance-conscious implementation
- Purposeful animations only
See @animation.md for orchestration patterns and scroll-triggered effects.
Background & Atmosphere
Create visual richness through layering when aesthetic requires it. See @backgrounds.md for gradient meshes, textures, and patterns.
Component Library Patterns
Each component must:
- Define its own tokens
- Document all interactive states (default, hover, active, focus, disabled)
- Use semantic HTML
- Include keyboard focus indicators
See @components.md for implementation patterns and design system tools.
AI-Driven Personalization
When implementing AI-powered interface adaptation:
Ethical Requirements (Non-Negotiable)
- Transparency: Users must know when AI personalizes their experience
- Control: Provide opt-out and reset options
- Explanation: Show why adaptations occurred
- Human fallback: Offer support when AI fails
- Privacy: Never personalize with sensitive data without explicit consent
Personalization Boundaries
Appropriate:
- Layout density preferences
- Color scheme (light/dark mode)
- Content prioritization
- Navigation shortcuts
Forbidden:
- Hiding critical functionality
- Removing accessibility features
- Changing core workflows without notice
- Personalizing based on protected attributes
See @personalization.md for implementation patterns.
Implementation Checklist
Before marking UI design complete:
- Aesthetic direction defined and documented
- Design tokens implemented systematically
- All token categories defined (color, spacing, typography)
- No magic numbers in styles
- Typography uses distinctive fonts with weight hierarchy
- Color system is cohesive and intentional
- Motion uses proper easing curves
- prefers-reduced-motion respected
- Component states documented (default, hover, active, focus, disabled)
- Keyboard focus indicators visible
- Design avoids generic AI patterns
- AI personalization (if used) includes transparency and control
- Visual hierarchy is clear
- Spacing system is consistent
Red Flags
Stop if you catch yourself:
- Using generic fonts (Inter/Roboto) or purple gradients without justification
- Single font weight, uniform spacing, everything centered
- Magic numbers instead of tokens
- Animating everything simultaneously, skipping component states
- AI personalization without consent UI
- Copying patterns without adaptation
Deliverables
State: "UI design implementation complete" only after checklist passes.
Document for handoff:
- Design token definitions
- Component inventory with all states
- Aesthetic direction rationale
- Typography system (fonts, weights, scales)
- Color system (palette, usage, contrast ratios)
- Motion principles (easing, duration, triggers)
- AI personalization boundaries (if applicable)