| name | ux-design-discipline |
| description | Use this skill when working as the designer — producing UX flow + Figma frame inventory for SPEC implementation, evaluating accessibility (WCAG 2.1 AA), applying Nielsen usability heuristics, choosing platform conventions (Material 3 web / iOS HIG / desktop). Also covers UX-Review mode — verifying frontend implementation against design. |
UX Design Discipline
This skill encodes the design lens for the designer agent. Two modes:
- Mode A: Design brief — produces a Design sub-issue with UX flow + Figma frame inventory before frontend coders start.
- Mode B: UX review — after frontend ships, verifies implementation matches design intent.
Inspired by:
- Nielsen 10 Usability Heuristics (Jakob Nielsen) — universal evaluation framework
- WCAG 2.1 Level AA (W3C) — accessibility compliance
- Material Design 3 (Google) — for web / Android components
- iOS Human Interface Guidelines (Apple) — for iOS-flavoured UIs
- Inclusive Design Principles (Microsoft / W3C) — beyond a11y to broader inclusion
Nielsen 10 Usability Heuristics — apply during Design brief AND UX review
Walk through these 10 for every screen / flow:
- Visibility of system status — user always knows what's happening (loading spinner, success toast, progress bar).
- Match between system and the real world — labels in user's language, not jargon. "Order delivered" not "txn_status_5".
- User control and freedom — undo / cancel for destructive actions; clear exit from any state.
- Consistency and standards — same word for same concept across the product. Match platform conventions (back button placement, primary action style).
- Error prevention — confirm destructive actions; constrain inputs (date picker rather than free text); inline validation.
- Recognition rather than recall — visible options / autocomplete instead of asking user to remember.
- Flexibility and efficiency of use — accelerators for power users (keyboard shortcuts, bulk operations) without burdening newcomers.
- Aesthetic and minimalist design — every UI element earns its place; remove what's not adding info.
- Help users recognize, diagnose, and recover from errors — error messages explain what went wrong + suggest fix.
- Help and documentation — when needed, contextual help, not a separate manual lost from the flow.
For Design brief: every screen / state in the design must answer: which heuristics are addressed?
For UX review: every heuristic violated in implementation = a finding.
State coverage — every screen has 8 states minimum
Designs that only show "happy path" cause downstream pain. For every page / component, design and document:
- Empty — no data yet (first-time user, empty list, no results)
- Loading — async data not yet arrived (skeleton, spinner, progress)
- Partial — some data, more loading (e.g. above-fold loaded, infinite scroll spinner below)
- Success / populated — normal use
- Error — API failure, network down, validation failure
- Permission denied — user without access (forbidden, not just hidden)
- Edge / extreme — very long names, very many items, missing optional fields
- Disabled / read-only — when interaction not currently allowed (pre-launch, locked due to status)
In the Design brief, list which states each component supports + Figma frame for each.
Accessibility (WCAG 2.1 Level AA) — overlap with the ui-tester but the designer owns the intent
The designer's responsibility: design must be a11y-by-default. The ui-tester verifies; the designer prevents.
Color and contrast
- Text contrast ≥ 4.5:1 (normal) / ≥ 3:1 (large 18pt+ or 14pt+ bold). Decorative graphics excepted.
- Don't use color alone to convey meaning — pair with icon, text, or pattern.
- Test designs at 200% browser zoom — does it still work without horizontal scroll?
Touch targets
- Minimum 44×44 px (iOS HIG) / 48×48 dp (Material 3) for touch targets.
- Spacing between adjacent targets — at least 8 px so finger doesn't hit wrong one.
Typography
- Body text minimum 16 px (12 pt) on web / 14 pt on iOS.
- Line height ≥ 1.5 for body. Letter spacing default unless specific need.
Focus indicators
- Every interactive element shows visible focus state when keyboard-navigated. Default browser ring acceptable; custom ring also OK if visible (≥ 2 px, ≥ 3:1 contrast).
- DON'T
outline: none without replacement.
Icons + labels
- Icon-only buttons need
aria-label. Avoid icon-only buttons in primary flow (recognition > recall).
- Use clear, action-oriented labels ("Save" not "Submit", "Cancel order" not "X").
Forms
- Every input has a visible
<label>. Placeholder is NOT a label — it disappears on input.
- Error messages near the field, in plain language, with how to fix.
Motion
- Don't depend on animation for understanding. Provide alternatives for
prefers-reduced-motion.
- Avoid auto-playing video / aggressive parallax.
For full reference: https://www.w3.org/WAI/WCAG21/quickref/
Platform conventions — pick one per surface
Projects often ship multiple frontends with different conventions. The project's $KB_DIR/kb/frontends.md declares the inventory. Common patterns:
Customer-facing storefront (typically Vue 3 / Nuxt 3 or React / Next.js)
- Convention: Material 3 simplified — Material's spacing / shape / motion principles, but visual style is project-branded.
- Mobile-first responsive. Breakpoints: 360 / 768 / 1024 / 1440.
- Touch targets 48 dp.
- Standard web nav (top bar, hamburger on mobile).
Admin / POS / internal panels
- Convention: desktop-first — power users, dense info, keyboard shortcuts.
- Tables, forms, action buttons; less marketing flair.
- UI library per panel (Buefy / Bulma / Material UI / Ant Design / custom) per
$KB_DIR/kb/frontends.md.
- Mobile responsive only for "view-only" cases; primary use is desktop.
iOS / Android native (future, if any)
- Use platform HIG / Material 3 directly. Don't impose web conventions.
Mode A: Design brief — what to produce
For every Plane task that has a frontend impact, the designer creates a Design sub-issue with:
- Figma link(s) — anchored to specific frame (
?node-id=... URL form)
- UX flow — 5–10 lines, step-by-step user journey
- Screen / state list — table: screen name × states (8-state matrix)
- Component spec (when introducing a new component) — variants, props if known, behaviour states
- Constraints — brand tokens, accessibility callouts, motion limits
- Open questions — for the initiator / system-analyst / architect (e.g. "should empty state show CTA to create?")
Don't include implementation details (Vue 3 vs Vue 2, Pinia vs Vuex). That's coder territory.
Mode B: UX review — what to check after frontend ships
Triggered after Frontend CHANGES posted. The designer re-runs through the design to verify:
- All 8 states present — empty / loading / partial / success / error / permission / edge / disabled
- Nielsen 10 — each heuristic considered; flag violations
- WCAG 2.1 AA quick pass — contrast, focus, touch targets, alt text (rough check; the ui-tester does the deep audit)
- Pixel-vs-Figma — not pixel-perfect, but functional and structural match (heading hierarchy, primary action prominent, layout responsive)
- Brand tokens used (colors, spacing, typography) — not hardcoded values
- Motion / micro-interactions — present, accessible, not distracting
Output: review comment in Frontend sub-issue with severity-classified findings (blocker / major / minor) and suggested fix.
Anti-patterns
- "Just use Material" — convention chosen without thought to brand or context (POS user vs storefront customer have different needs)
- Designs that show only happy path — leads to ad-hoc empty / loading / error states implemented without thought
- "Accessibility is QA's job" — wrong; designer prevents, QA verifies
- Pixel-perfect obsession — implementation will diverge by a few px; that's fine. What matters is structure, hierarchy, behaviour.
- "Designer doesn't need to write" — Figma alone isn't documentation; the brief explains the why behind the frames
When in doubt
- Start with REQUIREMENTS Stakeholder Requirements (section 3) — design serves them, not aesthetic preference.
- Start with SPEC §4 Frontend Behaviour — that's the contract; don't contradict it.
- For accessibility unsure? Consult the WCAG 2.1 quickref linked above.
- For component patterns unsure? Look at existing project patterns; don't introduce a new visual language without explicit need.
