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}> or aria-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.