Ux design discipline

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:

1. Visibility of system status — user always knows what's happening (loading spinner, success toast, progress bar).
2. Match between system and the real world — labels in user's language, not jargon. "Order delivered" not "txn_status_5".
3. User control and freedom — undo / cancel for destructive actions; clear exit from any state.
4. Consistency and standards — same word for same concept across the product. Match platform conventions (back button placement, primary action style).
5. Error prevention — confirm destructive actions; constrain inputs (date picker rather than free text); inline validation.
6. Recognition rather than recall — visible options / autocomplete instead of asking user to remember.
7. Flexibility and efficiency of use — accelerators for power users (keyboard shortcuts, bulk operations) without burdening newcomers.
8. Aesthetic and minimalist design — every UI element earns its place; remove what's not adding info.
9. Help users recognize, diagnose, and recover from errors — error messages explain what went wrong + suggest fix.
10. 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:

1. Empty — no data yet (first-time user, empty list, no results)
2. Loading — async data not yet arrived (skeleton, spinner, progress)
3. Partial — some data, more loading (e.g. above-fold loaded, infinite scroll spinner below)
4. Success / populated — normal use
5. Error — API failure, network down, validation failure
6. Permission denied — user without access (forbidden, not just hidden)
7. Edge / extreme — very long names, very many items, missing optional fields
8. 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 — derived from the project, not from this skill

Projects ship multiple frontends with different conventions. $KB_DIR/kb/frontends.md is authoritative — it declares, per frontend surface: chosen design system, UI library, responsive strategy (mobile-first / desktop-first), breakpoints, touch-target size, navigation shape. Read it before making any convention decision.

Surface types you'll encounter (design-thinking framing only — NOT defaults; the project's frontends.md overrides everything below):

• Customer-facing storefront — usually mobile-first, standard web nav, accessible touch targets. Design system / breakpoints / brand tokens: from frontends.md.
• Admin / POS / internal panel — usually desktop-first (power users, dense info, keyboard shortcuts), tables & forms over marketing flair. UI library: from frontends.md.
• iOS / Android native — platform HIG (Apple / Material) is the source of truth, not this skill.

If frontends.md does not answer a convention question, ask the initiator or escalate — do not fall back to defaults from prior projects (per agent-base §4b.1).

---

Mode A: Design brief — what to produce

For every Plane task that has a frontend impact, the designer creates a Design sub-issue with:

1. Figma link(s) — anchored to specific frame (?node-id=... URL form)
2. UX flow — 5–10 lines, step-by-step user journey
3. Screen / state list — table: screen name × states (8-state matrix)
4. Component spec (when introducing a new component) — variants, props if known, behaviour states
5. Constraints — brand tokens, accessibility callouts, motion limits
6. 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:

1. All 8 states present — empty / loading / partial / success / error / permission / edge / disabled
2. Nielsen 10 — each heuristic considered; flag violations
3. WCAG 2.1 AA quick pass — contrast, focus, touch targets, alt text (rough check; the ui-tester does the deep audit)
4. Pixel-vs-Figma — not pixel-perfect, but functional and structural match (heading hierarchy, primary action prominent, layout responsive)
5. Brand tokens used (colors, spacing, typography) — not hardcoded values
6. 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.