Phase 0.3 -- UX Design Guidelines

Parent: #762

Context

This issue produces the single authoritative design guidelines document that all Phase 4 page implementations must follow.

It runs AFTER the design exploration (#765) picks a winning variation and AFTER page structure (#766) decides responsive scope and navigation patterns. The raw decisions from those two phases are codified here into one reference document.

WCAG contrast verification happens in THIS issue, on the FINAL chosen colors. The prototype colors in #765 were pre-checked as a baseline, but the actual palette may differ once a winner is picked and refined. This issue runs the full contrast matrix on whatever colors land in the final palette, adjusts any failures, and documents the verified results.

Deliverable: docs/design/ux-guidelines.md

Section 1: Brand Identity

• Color system -- WCAG AA verified (run the full contrast matrix on final colors from feat: design exploration -- brand identity mockup variations #765 winner, not the prototype baseline)
• Typography scale: font families, sizes, weights, line heights, and usage rules (heading vs body vs mono vs label)
• Spacing grid: 8px base unit, defined steps (4, 8, 12, 16, 24, 32, 48, 64)
• Logo/wordmark usage rules for the dashboard (placement, minimum size, clear space)
• Visual signatures: the 2-3 design elements that create instant "this is SynthOrg" recognition (e.g. accent color, card style, status encoding pattern)

Section 2: Component Patterns

• Card anatomy (with ASCII wireframe):
  • Header bar (icon + title + status dot)
  • Content area (metrics, text, or mixed)
  • Footer stats (secondary info, timestamps)
  • Hover state (bg shift, optional elevation change)
• Status encoding rules:
  • When to use color alone (never for critical info)
  • When to add shape (dot, icon)
  • When to add text label
  • When to animate (only for state transitions, not steady state)
• Data display specs:
  • Sparkline: width, height, gradient fill, stroke width
  • Progress bar: height, border-radius, fill animation
  • Gauge: arc specs, value label placement
• Agent card: exact layout, fields shown, status dot placement (must be identical across dashboard, org chart, and any other surface)
• Metric card: exact layout with value + label + sparkline + delta positioning

Section 3: Interaction Design

• Progressive disclosure levels:
  • Level 0: Summary (visible in card/row)
  • Level 1: Hover tooltip (extra detail, no navigation)
  • Level 2: Click expand (inline detail panel)
  • Level 3: Navigate to full page
• Hover behavior per component type:
  • Cards: subtle background shift
  • Table rows: row highlight
  • Links: underline appears
  • Buttons: darken/deepen
• Inline editing: click activates edit mode, Enter saves, Escape cancels, blur saves
• Drag-drop: cursor change on grab, ghost preview while dragging, drop zone highlight, spring settle animation on drop
• Cmd+K command palette: trigger key, scope behavior (global vs page-local), result types (pages, agents, tasks, settings), keyboard shortcuts within the palette

Section 4: Animation Language

• Framer Motion config defaults:
  • Default spring: stiffness, damping, mass values
  • Default tween: duration, easing curve
• Page transitions: slide + fade, duration, direction convention
• Card entrance: stagger delay (30ms between cards), initial state (opacity: 0, y: 8px), animate to final
• Status change animation: flash highlight (200ms, accent color at 10% opacity), then fade out
• Real-time update feedback: "just updated" glow effect, timestamp update animation, optional count badge increment
• What NOT to animate:
  • Navigation chrome (sidebar, header)
  • Static labels and headings
  • Already-visible content on re-render (no re-entrance flicker)

Section 5: Accessibility

• WCAG AA minimum for ALL text on ALL backgrounds -- verified contrast matrix table included in the document (see WCAG verification process below)
• Focus indicators: 2px ring, 2px offset, accent color, must be visible on all background colors
• Screen reader support:
  • ARIA live regions for real-time data feeds (agent status, task updates)
  • aria-label on all icon-only buttons
• Status must NEVER be color-only: always color + shape (dot or icon) + label text
• Minimum touch/click target size: 32x32px

Section 6: Responsive Breakpoints (scope inherited from #766)

• Desktop: >= 1280px -- full sidebar, multi-column layouts
• Tablet: 768px - 1279px -- collapsed sidebar rail, reduced column count
• Mobile: < 768px -- deferred to feat: implement mobile app #252

Exported Artifacts (alongside the doc)

• web/tailwind.config.ts snippet containing all design tokens (colors, spacing, typography, border-radius, shadows)
• CSS custom properties file with color and typography variables (for non-Tailwind contexts)
• Framer Motion config object -- reusable spring and tween presets, exported as a constants file

WCAG Verification Process (done in this issue)

1. Take the FINAL color palette from the feat: design exploration -- brand identity mockup variations #765 winning variation
2. Run the full contrast matrix (the same ~20 foreground/background combinations we checked earlier as a baseline)
3. Identify any combinations that fail WCAG AA (4.5:1 for normal text, 3:1 for large text)
4. Adjust failing colors until all pass
5. Document the full results table in Section 5 of the guidelines

Blocked by

• feat: design exploration -- brand identity mockup variations #765 -- need the winning variation's final colors, typography, and density decisions
• feat: define page structure and information architecture #766 -- need responsive scope and page structure for breakpoint and layout decisions