ui-design

name	ui-design
description	This skill should be used when designing user interfaces and interaction patterns for web applications. It covers layout design, responsive breakpoints, component specifications, interaction patterns, and accessibility guidelines.
depends	["real.md","cog.md"]
generates	["spec-ui-design.md"]

Note for AI Agents: This skill generates specification documents for AI/Agent consumption (especially Claude Code). Before generating specs, you MUST load context from real.md and cog.md. If these files don't exist, invoke the 00-meta skill first to create them.

Prerequisites

Pre-execution Checklist

Before using this skill, verify:

1. real.md exists - Contains reality constraints (max 4 required + 3 optional)
2. cog.md exists - Contains cognitive model (Agents + Information + Context)

If either file is missing, execute:

Invoke skill: 00-meta

Context Loading

From cog.md, extract:

• Human agents: User types and their mental models
• Agent workflows: Task flows that inform page layouts
• Information display: What data each agent needs to see

From real.md, extract:

• Accessibility constraints: WCAG compliance level
• Device constraints: Supported devices and breakpoints
• Branding constraints: Color, typography requirements

UI/UX Design

Overview

This skill guides the design of user interfaces and interaction patterns. To create effective UIs, establish design principles, define layouts, specify components, design interactions, and ensure accessibility.

When to Use This Skill

• Designing page layouts and wireframes
• Defining component specifications
• Creating interaction patterns
• Establishing responsive breakpoints
• Ensuring accessibility compliance

Process

Phase 1: Establish Design Principles

Core Principles:

Principle	Description	Application
Simplicity	Reduce cognitive load	Minimal UI elements
Responsiveness	Immediate feedback	Loading states, animations
Consistency	Unified patterns	Reusable components
Accessibility	Universal usability	WCAG compliance

Design Tokens:

:root {
  /* Spacing */
  --space-1: 0.25rem;  /* 4px */
  --space-2: 0.5rem;   /* 8px */
  --space-3: 0.75rem;  /* 12px */
  --space-4: 1rem;     /* 16px */
  --space-6: 1.5rem;   /* 24px */
  --space-8: 2rem;     /* 32px */

  /* Border Radius */
  --radius-sm: 0.25rem;
  --radius-md: 0.5rem;
  --radius-lg: 1rem;
  --radius-full: 9999px;

  /* Shadows */
  --shadow-sm: 0 1px 2px rgba(0,0,0,0.05);
  --shadow-md: 0 4px 6px rgba(0,0,0,0.1);
  --shadow-lg: 0 10px 15px rgba(0,0,0,0.1);
}

Phase 2: Define Page Layouts

Layout Structure:

┌─────────────────────────────────────────────────────┐
│                    Header (64px)                     │
│  [Logo]              [Search]         [User Menu]   │
├──────────────┬──────────────────────────────────────┤
│              │                                       │
│   Sidebar    │           Main Content               │
│   (280px)    │                                       │
│              │                                       │
│  - Nav 1     │                                       │
│  - Nav 2     │                                       │
│  - Nav 3     │                                       │
│              │                                       │
└──────────────┴──────────────────────────────────────┘

Responsive Breakpoints:

Name	Width	Layout Changes
Mobile	< 640px	Single column, bottom nav
Tablet	640-1024px	Collapsible sidebar
Desktop	> 1024px	Full sidebar, multi-column

Page Templates:

## Chat Page Layout

Header: Fixed, 64px height
Sidebar: 280px, collapsible on mobile
Main: Flexible, min-width 320px
  - Message area: Scrollable, flex-grow
  - Input area: Fixed bottom, auto-height

## Settings Page Layout

Header: Same as chat
Content: Centered, max-width 800px
Sections: Stacked vertically with spacing

## Admin Page Layout

Header: Admin-specific branding
Sidebar: Admin navigation
Main: Dashboard cards or data tables

Phase 3: Specify Components

Component Specification Template:

## Component: [Name]

**Purpose:** [What this component does]

**Variants:**
| Variant | Description |
|---------|-------------|
| default | Standard appearance |
| active | Selected state |
| disabled | Non-interactive |

**Props:**
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| prop1 | string | - | Required prop |
| prop2 | boolean | false | Optional prop |

**States:**
- Default
- Hover
- Focus
- Active
- Disabled

**Accessibility:**
- Role: [ARIA role]
- Keyboard: [Key interactions]

Chat Message Component:

## Component: ChatMessage

**Purpose:** Display a single message in conversation

**Variants:**
| Variant | Background | Alignment |
|---------|------------|-----------|
| user | blue-100 | Right |
| assistant | gray-100 | Left |
| system | yellow-50 | Center |

**Features:**
- Markdown rendering
- Code syntax highlighting
- Copy button (on hover)
- Timestamp (on hover)

**Sizing:**
- Max width: 80% of container
- Padding: 16px
- Border radius: 12px (8px on message-side corner)

Input Component:

## Component: ChatInput

**Purpose:** Text input for sending messages

**Features:**
- Auto-expanding textarea (max 5 lines)
- Attachment button
- Send button
- Character count (optional)

**States:**
| State | Appearance |
|-------|------------|
| Empty | Placeholder visible, send disabled |
| Typing | Text visible, send enabled |
| Sending | Disabled, loading indicator |
| Generating | Stop button instead of send |

**Keyboard:**
- Enter: Send message
- Shift+Enter: New line
- Escape: Clear input

Phase 4: Design Interactions

Loading States:

Context	Pattern	Duration
Page load	Skeleton screen	Until content
Action	Inline spinner	Until complete
AI response	Typing indicator	Until first token
Streaming	Progressive text	Until complete

Feedback Patterns:

## Success Feedback
- Toast notification (3s auto-dismiss)
- Green checkmark icon
- Subtle animation

## Error Feedback
- Toast notification (manual dismiss)
- Red alert icon
- Clear error message
- Retry action when applicable

## Loading Feedback
- Skeleton for content areas
- Spinner for buttons
- Progress bar for uploads

Animation Guidelines:

/* Transitions */
--transition-fast: 150ms ease;
--transition-normal: 250ms ease;
--transition-slow: 350ms ease;

/* Use for */
.button:hover { transition: var(--transition-fast); }
.modal { transition: var(--transition-normal); }
.page-transition { transition: var(--transition-slow); }

Phase 5: Keyboard Navigation

Global Shortcuts:

Shortcut	Action
Ctrl/Cmd + N	New conversation
Ctrl/Cmd + K	Search
Ctrl/Cmd + /	Show shortcuts
Escape	Close modal/menu

Focus Management:

## Modal Focus
1. On open: Focus first interactive element
2. Trap focus within modal
3. On close: Return focus to trigger

## Form Focus
1. First field on page load
2. Next field on Tab
3. Submit button last
4. Error field on validation fail

Phase 6: Accessibility

WCAG 2.1 AA Checklist:

## Perceivable
- [ ] Text contrast ratio >= 4.5:1
- [ ] Non-text contrast >= 3:1
- [ ] Images have alt text
- [ ] Videos have captions

## Operable
- [ ] All functions keyboard accessible
- [ ] No keyboard traps
- [ ] Skip links available
- [ ] Focus visible

## Understandable
- [ ] Language declared
- [ ] Labels for inputs
- [ ] Error messages clear
- [ ] Consistent navigation

## Robust
- [ ] Valid HTML
- [ ] ARIA used correctly
- [ ] Works with screen readers

Color Accessibility:

Color Pair	Ratio	Pass
gray-900 on white	15.1:1	AA
gray-500 on white	4.6:1	AA
blue-600 on white	4.5:1	AA

Output Template

# UI/UX Design Specification

## 1. Design Principles
- Core principles and tokens

## 2. Page Layouts
- Layout diagrams
- Responsive behavior

## 3. Components
- Component specifications
- State definitions

## 4. Interactions
- Loading states
- Feedback patterns
- Animations

## 5. Accessibility
- Keyboard navigation
- WCAG compliance

Quality Checklist

• Design principles documented
• Layouts defined for all breakpoints
• Components fully specified
• Interaction patterns consistent
• Keyboard navigation works
• Color contrast meets WCAG
• Screen reader compatible

Integration with Other Skills

Skill	Relationship
user-simulation	Input: user needs inform design
graphic-design	Collaboration: visual assets
coding	Output: specs for implementation