UX/UI Design

Quick ref

Mission: Make interfaces accessible (WCAG 2.2 AA), clear in hierarchy, consistent through tokens, and respectful in motion and copy. Rules: WCAG 2.2 AA minimum · visible focus and full keyboard access · reduced-motion respected for every non-essential animation · tokens only, contrast checked in every theme · every state designed (loading, empty, error, success) Skills by default: ui-system · ui-audit · ui-refine (browser-verify = the eyes, automatic at the end of a seen change) DoD: Audit passes AA, states and copy complete, tokens consistent, motion reduced-safe.

Entry

Guest (no Waymark block in context) → ../waymark/references/coexistence.md §3. Reads:

• Learnings: ~/.waymark/learnings/dept-ux-ui.md if it exists.
• Stack profile: L1 Conventions by department → Frontend, L2+ full. Also the project's token source of truth.

Brief questions

The brief must answer:

1. What is designed or improved (screen, flow, component, theme, motion, copy)?
2. Why / for whom — the user's primary task on this view and the single primary action?
3. What is wrong today — the perceived problem in concrete terms (hierarchy, contrast, density, feedback, consistency)?
4. Where — which feature/components are affected, and where the token source of truth lives?
5. States and copy — loading, empty, error, success, disabled, interaction states, and the microcopy for each, in the project's UI language?
6. Accessibility and motion — WCAG criteria at risk, keyboard/focus behavior, reduced-motion variant?
7. How — procedure, and which skills/MCP (ui-system, ui-refine, ui-audit, the UI library's MCP if any, library-docs), and what is handed to dept-frontend?
8. Done when — audit result, themes and viewports checked, evidence captured?

Scope

• Owns: accessibility requirements, visual hierarchy, layout rhythm, typography, color, design tokens and theming rules, interaction states, motion design, microcopy, information architecture, responsive intent.
• Does not own: component implementation → dept-frontend · requirements and priority → dept-product · test automation → dept-qa.

Procedures

In procedures.md (same folder), one section per task:

• New screen or flow (L2)
• Visual improvement ("se ve feo", "más profesional")
• Accessibility audit
• Theming / tokens change
• Motion

Rules

Accessibility (WCAG 2.2 AA)

• Meet WCAG 2.2 AA on every user-facing interface.
• Meet contrast: 4.5:1 normal text, 3:1 large text and UI components/focus indicators, in every theme.
• Make every interactive element keyboard operable with a visible focus indicator not obscured by sticky content (2.4.11).
• Keep a logical focus order; dialogs trap focus, restore it to the trigger on close, and close on Escape.
• Give icon-only controls an accessible name; hide decorative icons from assistive tech.
• Announce async status (toasts, form errors, results) through live regions with appropriate politeness.
• Provide targets of at least 24x24 CSS px (2.5.8); 44x44 recommended on touch.
• Offer a non-drag alternative for drag interactions (2.5.7).
• Associate visible labels with inputs; errors identify the field and suggest a fix (3.3.1, 3.3.3); no forced re-entry of known data (3.3.7).
• Never convey information by color alone.
• Prefer: follow WAI-ARIA APG patterns for composite widgets (tabs, menus, comboboxes, dialogs).

Hierarchy, layout and tokens

• Use design tokens for color, spacing, radius, typography, elevation and motion; no hard-coded values.
• Keep one primary action per view or section.
• Prefer a consistent spacing and type scale; limit to the steps the system defines.
• Prefer: separate primitive and semantic tokens; components consume semantic tokens.
• Prefer skeletons over spinners for content loading.

Motion

• Honor prefers-reduced-motion (or the platform equivalent) for every non-essential animation and any transition over 300ms.
• Prefer: keep hover/press feedback under 200ms and view transitions under 400ms on mobile.
• Prefer purposeful easing; avoid gratuitous bounce or overshoot in task flows.
• Never autoplay animation with sound, or flash more than 3 times per second.

Copy

• Write in the project's configured UI language.
• Start actions with a verb that names the outcome ("Save changes", "Send message").
• Make errors say what happened and how to resolve it; never a generic "Something went wrong" alone.
• Prefer: keep labels short, consistent and in the user's vocabulary, not the system's.
• Never use modal confirmations for trivial reversible actions; prefer undo.

Tools

Definition of Done

• ui-audit run; no WCAG 2.2 AA failures open
• Keyboard-only pass and visible focus verified
• Contrast verified in every theme
• Loading, empty, error, success, disabled and interaction states specified and implemented
• Reduced-motion variant for every non-essential animation
• Copy reviewed: verbs first, actionable errors, consistent terms
• Tokens only; new tokens added to the source of truth

Hand-offs

• To dept-frontend: implementation of specified states, tokens and motion.
• To dept-product: flows that change scope or need new requirements.
• To dept-qa: automated a11y checks and visual regression baselines.
• To dept-data: persistence of user preferences (theme, reduced motion, language).
• To dept-devex: design-system documentation and token tooling.

Learned rules

Grows with use (../waymark/references/learning.md).