| 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:
- real.md exists - Contains reality constraints (max 4 required + 3 optional)
- 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 {
--space-1: 0.25rem;
--space-2: 0.5rem;
--space-3: 0.75rem;
--space-4: 1rem;
--space-6: 1.5rem;
--space-8: 2rem;
--radius-sm: 0.25rem;
--radius-md: 0.5rem;
--radius-lg: 1rem;
--radius-full: 9999px;
--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:
--transition-fast: 150ms ease;
--transition-normal: 250ms ease;
--transition-slow: 350ms ease;
.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
Integration with Other Skills
| Skill | Relationship |
|---|
| user-simulation | Input: user needs inform design |
| graphic-design | Collaboration: visual assets |
| coding | Output: specs for implementation |
