ui-ux-design-principles

UI/UX Design Principles

Overview

Systematic framework for making UI/UX decisions grounded in cognitive science and user experience laws. This skill provides universal principles that apply to any project, with project-specific implementation details 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 (Before Design)

Identify context and friction:

• Who: User role, expertise level, frequency of use
• Where: Device (desktop/tablet/mobile), environment (office/field/dim lighting)
• What: Task goals, current pain points, cognitive load
• Which laws: Identify violated UX principles (see table below)

2. Strategy Selection

Default recommendation: Strategy C (Hybrid Field Resilience) balances accessibility, speed, and adaptability.

3. Decision Matrix Evaluation

Score each criterion (1-5), multiply by weight:

Redesign triggers:

• Accessibility < 4 → WCAG blocker
• Usability < 3 → Users can't complete tasks
• Speed < 3 → Workflow unacceptably slow
• 3+ criteria < 4 → Review against UX Laws

4. Implementation Spec

Output concrete, actionable code with:

• Exact CSS/Tailwind classes
• ARIA attributes for accessibility
• Responsive breakpoints
• Feedback patterns (loading states, success confirmation)

UX Laws Reference

Interaction Laws

Visual & Cognitive Laws

Code Patterns for UX Laws

// Fitts's Law: Large touch target (44px minimum)
<Button className="h-11 min-w-[44px] px-4">
  Save
</Button>

// Hick's Law: Progressive disclosure
<Accordion>
  <AccordionItem value="advanced">
    <AccordionTrigger>Advanced Options</AccordionTrigger>
    <AccordionContent>
      {/* Hidden until explicitly requested */}
    </AccordionContent>
  </AccordionItem>
</Accordion>

// Doherty Threshold: Immediate feedback
<Button onClick={async () => {
  toast.loading("Saving...");  // Instant feedback (<100ms)
  await save();
  toast.success("Saved!");     // Closure (Peak-End)
}}>
  Save
</Button>

// Miller's Law: Chunked information
<Tabs defaultValue="basics">
  <TabsList>
    <TabsTrigger value="basics">Basics</TabsTrigger>
    <TabsTrigger value="details">Details</TabsTrigger>
    <TabsTrigger value="advanced">Advanced</TabsTrigger>
  </TabsList>
  {/* Max 5-7 fields per tab */}
</Tabs>

Accessibility Non-Negotiables

These are blockers - no exceptions:

ARIA Patterns

// Dialog/Modal
<div role="dialog" aria-modal="true" aria-labelledby="dialog-title">
  <h2 id="dialog-title">Edit Contact</h2>
  {/* Focus trap required */}
</div>

// Live regions for updates
<div aria-live="polite" aria-atomic="true">
  {statusMessage}
</div>

// Form errors (basic)
<input aria-invalid={hasError} aria-describedby="error-msg" />
<span id="error-msg" role="alert">{errorText}</span>

Form Accessibility Patterns (WCAG 2.1 AA)

Required for ALL form inputs:

// ✅ CORRECT: Accessible form field with React Hook Form
function AccessibleInput({ name, label, errors, register }) {
  const hasError = !!errors[name];
  const errorId = `${name}-error`;

  return (
    <div>
      {/* 1. Visible label with htmlFor */}
      <label htmlFor={name}>{label}</label>

      {/* 2. Input with ARIA attributes */}
      <input
        id={name}
        aria-invalid={hasError ? 'true' : 'false'}
        aria-describedby={hasError ? errorId : undefined}
        {...register(name)}
      />

      {/* 3. Error with role="alert" for screen readers */}
      {hasError && (
        <span id={errorId} role="alert" className="text-destructive">
          {errors[name]?.message}
        </span>
      )}
    </div>
  );
}

// ❌ WRONG: Inaccessible form field
<input {...register('email')} />
{errors.email && <span>{errors.email.message}</span>}
// Missing: label, aria-invalid, aria-describedby, role="alert"

Form Accessibility Checklist:

Focus Management on Validation Failure:

// ✅ CORRECT: Focus first invalid field after submit
const { handleSubmit, setFocus } = useForm();

const onSubmit = handleSubmit(
  (data) => { /* success */ },
  (errors) => {
    // Focus first errored field
    const firstError = Object.keys(errors)[0];
    if (firstError) setFocus(firstError);
  }
);

Live Validation Feedback:

// ✅ CORRECT: Live region for validation status
<div aria-live="polite" aria-atomic="true" className="sr-only">
  {isSubmitting && "Validating form..."}
  {isSubmitSuccessful && "Form submitted successfully"}
  {Object.keys(errors).length > 0 &&
    `Form has ${Object.keys(errors).length} errors`}
</div>

Color System Principles

The 60-30-10 Rule

Semantic Color Categories

Color Anti-Patterns

Response Format

When answering UI/UX questions, structure responses as:

1) Cognitive Audit (2-4 sentences)

• Context: role, device, environment
• Friction points identified
• UX laws at stake

2) Strategy Recommendation

• Choose A/B/C/D with rationale
• Brief pros/cons

3) Implementation Spec

• Concrete code/CSS
• ARIA attributes
• Responsive considerations
• Feedback patterns

Example:

Audit: Field sales rep on iPad in warehouse (dim lighting, possible gloves). Current filter panel has 15 visible options (Hick's Law violation) with 38px buttons (Fitts's Law violation).

Strategy: C - Hybrid Field Resilience. High contrast, large targets essential for environment.

Implementation:

<FilterPanel className="bg-card p-4">
  {/* Grouped to reduce visible choices */}
  <FilterGroup label="Status">
    <FilterButton className="h-11 min-w-[44px] text-base">
      Active
    </FilterButton>
  </FilterGroup>
</FilterPanel>

Quick Checklists

Pre-Design Checklist

• Identified user context (who, where, what device)
• Listed UX laws that apply
• Chosen strategy (A/B/C/D)
• Mapped colors to semantic tokens

Pre-Commit Checklist

• Touch targets ≥ 44px on ALL screen sizes
• No hardcoded colors (hex, rgb, hsl)
• ARIA labels on interactive elements
• Keyboard navigation works
• Feedback on all actions (<400ms)
• Tested on primary target device

Form-Specific Accessibility Checklist

• All inputs have associated <label htmlFor={id}>
• Invalid fields have aria-invalid="true"
• Error messages have role="alert"
• Errors linked via aria-describedby
• Required fields have aria-required="true"
• Focus moves to first error on submit failure
• Live region announces validation status

Optimization Triggers

Resource Files

Universal Principles

• UX Laws Deep Dive - Extended explanations and research citations
• Decision Matrix Guide - Scoring examples and case studies
• Color Theory - OKLCH, semantic mappings, accessibility

Project-Specific Implementation

• Design Tokens - Spacing, CSS variables
• Typography - Font scales, hierarchy
• Elevation - Shadows, depth, layering
• Form Patterns - Validation, arrays, accessibility
• Data Tables - Sorting, pagination, responsive

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

See also: engineering-constitution skill for:

• Error handling patterns
• Validation (Zod schemas)
• Form state management
• Testing patterns