UI/UX Design Principles
Overview
Systematic framework for making UI/UX decisions grounded in cognitive science and user experience laws. Provides universal principles with project-specific implementation in resource files.
Core Mission: Design experiences that are fast under pressure, effortless under fatigue, predictable by pattern, and emotionally confident.
The Sienna Protocol
Every UI/UX decision follows this structured approach:
1. Cognitive Audit
Identify context: Who (role, expertise), Where (device, environment), What (task goals, pain points), Which laws apply (see UX Laws reference below).
2. Strategy Selection
| Strategy | Focus | Best For |
|---|---|---|
| A - Familiar Efficiency | Low learning curve, speed | Power users, CRM/Excel veterans |
| B - Progressive Clarity | Reduced cognitive load | New users, complex onboarding |
| C - Hybrid Field Resilience | High contrast, large targets | Field use, tablets, challenging environments |
| D - Behavioral Momentum | Habit loops, reinforcement | Repetitive workflows |
Default: Strategy C balances accessibility, speed, and adaptability.
3. Decision Matrix
Score criteria (1-5) weighted by importance. Redesign if Accessibility < 4, Usability < 3, Speed < 3, or 3+ criteria < 4.
See: Decision Matrix Guide for scoring details and case studies.
4. Implementation Spec
Output concrete code with exact CSS/Tailwind classes, ARIA attributes, responsive breakpoints, and feedback patterns.
Quick Reference
| Topic | Resource | Key Rules |
|---|---|---|
| UX Laws | resources/ux-laws-reference.md | Fitts (44px targets), Hick (5-7 choices), Doherty (<400ms feedback), Jakob (familiar patterns), Miller (chunk to ~7 items), Tesler (push complexity to system), Von Restorff (accent sparingly for CTAs), Peak-End (end flows with confirmation), Gestalt: Proximity/Similarity/Continuity |
| Accessibility | .claude/rules/CODE_QUALITY.md (always loaded) | aria-invalid, aria-describedby, role="alert", aria-required, focus management |
| Form Patterns | resources/form-patterns.md | Field grouping, validation timing, error handling |
| Colors | resources/color-system.md, resources/color-status-semantic.md | 60-30-10 rule, semantic tokens, no hardcoded hex |
| Touch & Animation | resources/tokens-touch-animation.md | 44px minimum, easing curves, reduced motion |
| Component Architecture | resources/component-architecture.md | Three-tier (Atoms, Molecules, Organisms) |
| Data Tables | resources/data-tables.md | Sortable columns, pagination, keyboard nav |
| Typography | resources/typography.md | Font hierarchy, line height, weight scales |
Response Format
When answering UI/UX questions, structure responses as:
- Cognitive Audit (2-4 sentences) — Context, friction points, UX laws at stake
- Strategy Recommendation — Choose A/B/C/D with rationale
- Implementation Spec — Concrete code, ARIA attributes, responsive considerations, feedback patterns
Pre-Commit Checklist
- Touch targets >= 44px on all screen sizes
- No hardcoded colors (hex, rgb, hsl)
- ARIA labels on interactive elements (
aria-invalid,aria-describedby,role="alert") - All inputs have associated
<label htmlFor={id}>oraria-label - Required fields have
aria-required="true" - Focus moves to first error on submit failure
- Keyboard navigation works (Tab order, Enter/Space)
- Feedback on all actions (<400ms)
- Tested on primary target device
Resource Navigation
This skill includes 18 detailed resource files (308 KB). For a categorized index, see AGENTS.md:
- Colors & branding →
resources/color-*.md,color-system.md - Component patterns →
resources/form-patterns.md,data-tables.md,component-architecture.md - Layout & spacing →
resources/dashboard-layouts.md,tokens-spacing-grid.md,elevation.md - Implementation →
resources/react-performance.md,typescript-patterns.md,state-management.md - UX decision-making →
resources/decision-matrix-guide.md,ux-laws-reference.md
Core Beliefs
- Design is a system, not an aesthetic
- Every pixel must serve cognition or confidence
- Accessibility and speed are fundamentals, not features
- We don't redesign for beauty; we redesign for measurable improvement
- Familiarity reduces friction; innovation must earn its cost
Cross-Reference: enforcing-principles skill for error handling, Zod validation, form state management, testing patterns.