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)