---
name: better-coding-frontend
description: "Build or audit user interfaces to a quality floor: accessibility (WCAG 2.2 AA), UX states (loading/empty/error), design-system consistency, responsive layout, internationalization, frontend testing, and GDPR/privacy hygiene. MUST be used whenever UI is built, reshaped, or reviewed in any stack (React, Angular + Material, Vue, Svelte, Web Components, plain HTML/CSS) — even if the user does not say accessibility or frontend. Stack-neutral anti-generic-AI-look principles; build mode sets the quality floor while coding, audit mode reports read-only. Visual/aesthetic direction belongs to a design skill, not this one. Trigger: /better-coding-frontend"
metadata:
  version: "2.12.0"
  license: Apache-2.0
---

# Better Coding Frontend

The layer between "it renders" and "it's good to use." Aesthetics (palette,
typography, signature) belong to the `frontend-design` skill; this skill owns
whether the interface is **usable, accessible, robust, internationalized, and
compliant** — the parts that decide whether a real person, on a real device, with
real needs, can actually use it.

**Primary objective:** every interface is operable by keyboard and screen
reader, readable at real contrast and zoom, honest about its states
(loading/empty/error), responsive down to mobile, internationalizable, and free
of privacy/compliance traps. Looking good is necessary but not sufficient.

---

## Activation

Begin the first response after loading with exactly this line:
▸ better-coding-frontend active — accessibility, usability & compliance layer

Emit it once, then proceed. Do not repeat it later.

---

## Two modes

The same principles apply whether you are **building** new UI or **auditing**
existing UI — only the output differs.

* **Build mode** — the checklists below are a *quality floor* to hit as you
  write. Design for the states and the keyboard user from the start; retrofitting
  accessibility is far more expensive than building it in. Where tooling allows,
  screenshot the rendered result and self-critique against these checklists —
  a picture catches what reading the code misses.
* **Audit mode** — walk the checklists against existing UI and report findings
  read-only, in the format at the end. State which files/components you reviewed.
  Do not silently rewrite; report, then fix only if asked.

If the request is ambiguous, ask which mode. When building, if visual/aesthetic
direction is also needed, defer those decisions to `frontend-design` and focus
here on the quality layer.

---

## Stack-neutral by default

The rules are expressed against the platform (HTML semantics, CSS, ARIA, the DOM)
so they hold across React/TS, Angular + Material 3, Vue, Svelte, Web Components,
and plain HTML/CSS. Where a stack matters, note it inline:

* **Angular + Material 3 (MDC)** — Material components ship accessible defaults;
  the common failures are *overriding* them (removing focus rings via CSS,
  custom `mat-*` theming that breaks contrast tokens, custom controls that drop
  the built-in ARIA). Verify overrides don't regress what the component gave you.
* **React/TS** — native elements first (`<button>`, `<a href>`, `<label>`); a
  `<div onClick>` is the single most common a11y regression. Type interactive
  props so a keyboard handler isn't forgotten alongside a click handler. Use
  `forwardRef` so parent components can manage focus.
* **Vue** — same native-element-first principle; use `v-model` correctly (it
  handles value binding and events). Watch for custom directives that bypass
  semantic elements.
* **Svelte** — native elements first; Svelte transitions should respect
  `prefers-reduced-motion` (use the `prefersReducedMotion` store or media query).
* **Web Components** — you own the shadow DOM, so accessibility is entirely your
  responsibility. Use `delegatesFocus` on shadow roots. Add ARIA roles to custom
  elements that don't have a native equivalent.
* **Plain HTML/CSS** — you own everything, so semantics and focus management are
  entirely your responsibility.

---

## 1. Accessibility (WCAG 2.2 AA, pragmatic)

Target **Level AA** — the standard most organisations and public bodies aim for.
For public-sector / educational offerings in the EU this is effectively a legal
floor (BITV 2.0 / EN 301 549, and the European Accessibility Act in force since
June 2025). "Pragmatic" means: hit AA reliably, don't chase AAA everywhere, and
prefer native semantics over ARIA gymnastics.

### Contrast (SC 1.4.3 / 1.4.11)

* **Normal text ≥ 4.5:1**, **large text ≥ 3:1** (large = 24px, or 18.66px bold).
* **UI components and meaningful graphics ≥ 3:1** — this includes form-field
  borders, focus indicators, and icons that carry meaning.
* Check hover/active/focus states too, not just the resting state. Disabled
  elements are exempt, but don't rely on faded colour alone to signal "disabled."
* Re-check in dark mode and over images/video — the ratio must hold on every
  frame/background.

### Colour is never the only signal (SC 1.4.1)

Errors, statuses, links, and required fields must carry a non-colour cue too:
text, an icon, an underline, a shape. Red border alone fails; red border + error
text + icon passes.

### Keyboard operability (SC 2.1.1 / 2.4.7)

* Everything actionable is reachable and operable by keyboard alone (Tab, Enter,
  Space, arrows, Esc). No keyboard traps.
* **Visible focus indicator** on every interactive element — never
  `outline: none` without a stronger replacement.
* Logical focus order following the visual order.
* Manage focus on route changes and when opening/closing dialogs (move focus in,
  restore it on close, trap it while open).
* Skip-to-content link present on multi-section pages.
* Custom widgets implement expected keyboard patterns (ARIA Authoring Practices
  Guide is the reference): arrow keys for listboxes/tabs/menus, Enter/Space for
  buttons, Esc to close overlays.

### Semantics & structure (SC 1.3.1 / 4.1.2)

* Use the right element: `<button>` for actions, `<a href>` for navigation,
  `<label>` tied to every input, real headings in order (one `<h1>`, no skipped
  levels), lists as lists, `<table>` for tabular data.
* Reach for ARIA only when no native element fits; a wrong ARIA role is worse
  than none. Every custom control needs role + name + state.
* Every meaningful image has alt text; decorative images have empty `alt=""`.
* Inputs have programmatic labels (not placeholder-as-label).
* `aria-live` regions for dynamic content updates (toasts, notifications, async
  results). Use `polite` by default; `assertive` only for urgent updates.
* `aria-describedby` to link inputs to their help text and error messages.

### Motion & zoom (SC 2.3.3 / 1.4.4 / 1.4.10)

* Respect `prefers-reduced-motion`: gate non-essential animation behind it.
* Layout survives 200% zoom and 320px width without loss of content or
  horizontal scrolling (reflow).
* No content that flashes more than three times per second.
* `prefers-color-scheme` respected for dark mode (or an explicit toggle).

### Target size (SC 2.5.8 — new in 2.2)

* Touch targets ≥ 24×24px CSS (minimum); ~44px is the comfortable target.
* Adequate spacing between targets so neighbours aren't mis-tapped.

### Cheap verification

Automated tools catch ~30–40% of issues; the rest needs manual checks.

* Run an automated pass (axe DevTools, Lighthouse, or `jest-axe`/`@axe-core/playwright`/`pa11y` in CI).
* Then manually: unplug the mouse and Tab through the whole flow; zoom to 200%;
  toggle reduced motion; check contrast on the actual rendered colours.
* Test with a real screen reader (NVDA + Firefox, VoiceOver + Safari) on at least
  the critical user journey. Automated tools cannot verify screen reader
  compatibility.

---

## 2. Usability & UX Patterns

Good UX is mostly about honestly handling the states beyond the happy path.

### Handle all states, not just the full one

Every data-driven view has at least four states — design each deliberately:

* **Loading** — skeleton or spinner with layout that doesn't jump when data
  arrives (reserve space; avoid layout shift). Perceived performance > actual
  performance.
* **Empty** — an empty screen is an invitation to act: say what would be here and
  how to add the first item, not a blank void.
* **Error** — explain what went wrong and how to recover, in the interface's
  voice; never a raw stack trace or a vague "Something went wrong." Offer a
  retry action where applicable.
* **Partial / stale** — loading more, optimistic updates, offline, cached data
  with a freshness indicator.

### Forms (where usability is won or lost)

* Label every field; mark required fields in text, not colour alone.
* Validate at the right time (on blur / on submit, not aggressively on every
  keystroke), and put the error message *next to the field*, tied via
  `aria-describedby`.
* Keep entered data on error — never clear the form.
* Use correct input types and `autocomplete` so mobile keyboards and password
  managers work. Use `inputmode` for numeric entry on mobile.
* The submit action names what it does ("Create account", not "Submit") and
  keeps that name through the flow (button "Publish" → toast "Published").
* Multi-step forms show progress and allow backward navigation without data loss.
* Inline validation for format errors (email, phone); submit validation for
  business rules (unique username).

### Feedback & affordance

* Every action gives feedback within ~100ms (state change, spinner, toast).
* Disable or show progress on submit buttons to prevent double-submission.
* Destructive actions are confirmable or undoable; prefer undo over a modal
  where feasible.
* Interactive elements look interactive (cursor, hover state) and non-interactive
  ones don't.
* Loading states are distinguishable from disabled states.

### Clarity

* Name things by what the user controls, not how the system is built
  ("notifications", not "webhook config").
* Sentence case, plain verbs, no filler. One job per element.
* Error messages tell the user what to do, not what went wrong technically.
  "Enter a date in DD.MM.YYYY format" not "Invalid date string."

---

## 3. Design Quality & Anti-Slop

Aesthetic *direction* (a specific palette, type pairing, signature element)
belongs to the `frontend-design` skill. This section is the stack-neutral floor
that keeps an interface from reading as generic AI output — expressed as
principles, never fixed colour or font values.

**If no design skill or explicit direction is available,** set one deliberately
before coding — purpose, audience, tone, and one differentiator ("what makes
this memorable?") — and hold it consistently. A bold choice held with
discipline beats timid defaults.

### Consistency through a system, not one-off values

* Derive spacing, colour, type, and radius from the project's **design tokens /
  theme** (Material 3 tokens, CSS custom properties, a Tailwind/theme config) —
  not hardcoded hex, px, or ad-hoc values scattered per component. One change to
  a token should propagate everywhere.
* Follow a consistent spacing scale rather than arbitrary margins/paddings; the
  specific scale is the project's choice, but *pick one and hold to it*.
* Reuse existing components and variants before inventing a new one-off; a fourth
  slightly-different button is a smell.
* Dark mode is a token variation, not a separate set of hardcoded values.

### Avoid the generic-AI defaults

Don't reach for the statistically-average look. Common tells to avoid *unless the
brief genuinely calls for them*:

* A wall of equal-weight cards in a uniform grid as the default layout for
  everything.
* Decorative gradients and glows that carry no meaning; purple-on-white "SaaS"
  defaults.
* Overused AI-default typefaces used without intent.
* Flat visual hierarchy where everything competes — no clear primary anchor per
  screen.
* Drop shadows on everything instead of using spacing and contrast for hierarchy.

Instead: establish one clear focal point per view, let hierarchy come from real
differences in size/weight/space (not decoration), and make structural devices
(dividers, numbering, labels) encode something true about the content rather than
ornament it.

### Motion serves meaning

* Animate to communicate — state changes, spatial relationships, where something
  came from or went. If a motion doesn't improve clarity or hierarchy, remove it;
  scattered decorative motion is itself an AI-slop tell.
* Keep it quick (150-300ms) and interruptible; and always gate non-essential
  motion behind `prefers-reduced-motion` (see §1).
* Use `view-transition` API for SPA route transitions where supported.

### Restraint

Spend boldness in one place and keep the rest quiet. When a screen feels busy,
the fix is usually removal, not addition — cut any element that doesn't earn its
place.

---

## 4. Responsive & Cross-Device

* **Mobile-first**: design the small screen, then enhance up. It's harder to
  retrofit down.
* **Touch targets ≥ 24×24px** (WCAG 2.2 SC 2.5.8 minimum; ~44px is the
  comfortable target), with spacing so neighbours aren't mis-tapped.
* Fluid layouts (flex/grid, relative units) over fixed pixel widths; test at
  narrow widths, not just named breakpoints.
* Don't hide essential functionality on mobile; reflow it.
* Respect safe areas and avoid content under notches/system bars (`env(safe-area-inset-*)`).
* Test with real content lengths (long names, long translations — relevant for
  multilingual/i18n UIs) rather than tidy placeholder text.
* Test on real devices, not just browser dev-tools emulation. Touch behaviour,
  scroll momentum, and keyboard behaviour differ.
* `viewport` meta tag correct (`width=device-width, initial-scale=1`); no
  `user-scalable=no` (it violates WCAG 1.4.4).

---

## 5. Internationalization (i18n)

Often an afterthought that becomes expensive to retrofit. Design for it from the
start, even if the initial launch is single-language.

* **No hardcoded user-facing strings.** All text goes through an i18n function
  (`t('key')`, `i18next.t()`, `ngx-translate`, `vue-i18n`, `svelte-i18n`).
  This includes button labels, error messages, aria-labels, and toast text.
* **String keys are semantic, not positional**: `user.profile.save_button` not
  `button.text1`.
* **Pluralization** — use the i18n library's plural rules, not string
  concatenation. "1 item" / "2 items" / "5 items" differs by language (some have
  3+ plural forms: Arabic, Russian, Polish).
* **RTL support** — layouts must work in right-to-left languages (Arabic, Hebrew).
  Use logical properties (`margin-inline-start`, `padding-inline-end`) not
  physical (`margin-left`). Use `dir="auto"` for user-generated content.
* **Text expansion** — German text is ~30% longer than English; French ~20%.
  Layouts must survive text expansion without truncation or overlap. Don't use
  `text-overflow: ellipsis` on critical content.
* **Date/time/number formatting** — use `Intl.DateTimeFormat`, `Intl.NumberFormat`
  with the user's locale. Never format dates/numbers manually with string
  concatenation.
* **Currency** — display in the user's locale format; don't assume symbol
  placement ($1 vs 1€ vs 1 £).
* **Character encoding** — UTF-8 everywhere. Test with non-ASCII names
  (Müller, José, 王, الأحمدي).
* **Bi-di isolation** — use `<bdi>` or `dir="auto"` for user-generated content
  mixed into a page with a different base direction.

---

## 6. Privacy & Compliance Hygiene (GDPR/DSGVO)

Often invisible in the design but legally material — especially for
public-sector and educational products in the EU.

* **No hotlinking of third-party fonts.** Loading Google Fonts (or any CDN font)
  from the provider's servers transmits the visitor's IP to that provider and has
  been ruled a GDPR violation in German courts. **Self-host fonts** (download and
  serve from your own origin, e.g. via `@font-face` or Fontsource). This applies
  to icon fonts and Material Symbols too.
* **No third-party assets that leak IPs without consent** — CDN-hosted scripts,
  avatars, map tiles, embedded videos, analytics. Self-host, or gate behind
  consent, or use a privacy-respecting alternative.
* **Consent before non-essential cookies/tracking**, not on page load. No
  pre-ticked boxes; reject must be as easy as accept.
* **No PII in the URL, localStorage, or client logs.** Don't log form contents.
* **Embeds** (YouTube, social, fonts, maps) load only after consent, or use a
  no-cookie / self-hosted variant.
* Third-party UI dependencies pulled at build time, pinned, and served from your
  origin — not hotlinked at runtime.
* **Data minimization** — collect only what's needed. Don't store form data
  client-side longer than necessary. Clear sensitive data from memory after use.

---

## 7. Frontend Performance (perceived)

Overlaps deliberately only lightly with `better-coding-review`; here the lens is
the *user's perception*.

* No layout shift as content/fonts load (reserve space; `font-display: swap`
  with a matched fallback metric; `aspect-ratio` on images and containers).
* Lazy-load below-the-fold images and heavy/non-critical components; set explicit
  image `width`/`height` (or `aspect-ratio`) to prevent reflow.
* Don't ship a full library for one helper; import per-function / tree-shake.
* Avoidable re-renders and unbounded lists (virtualize long ones —
  `react-window`, `@angular/cdk/scrolling`, etc.).
* Serve modern image formats (WebP/AVIF) at appropriate sizes; `srcset` for
  responsive images.
* Code-split routes and large dependencies (dynamic `import()`).
* Preload critical resources (fonts, hero images) with `rel="preload"`.
* Bundle analysis: check for duplicate dependencies, large polyfills, unused
  exports. Target a first-load JS budget (e.g. <150KB gzipped for the initial
  route).
* Core Web Vitals: LCP <2.5s, CLS <0.1, INP <200ms. These are measurable
  targets, not aspirations.

---

## 8. Frontend Testing Strategy

* **Unit tests** for pure logic (utilities, reducers, state transformations,
  formatters). Fast, isolated.
* **Component tests** for rendering, interaction, and accessibility
  (Testing Library, `@testing-library/angular`, `@vue/test-utils`,
  `@testing-library/svelte`). Test behavior, not implementation details.
  Query by role/label/text, not by CSS class or test-id when possible.
* **Accessibility tests** in CI: `jest-axe`, `@axe-core/playwright`, `pa11y`.
  These catch ~30-40% of a11y issues automatically. Supplement with manual
  keyboard and screen reader testing.
* **Visual regression tests** for critical components (Storybook + Chromatic,
  Playwright screenshots). Catch unintended visual changes.
* **E2E tests** for critical user journeys (Playwright, Cypress). Keep the
  number small — E2E is slow and flaky-prone. Test the top 3-5 paths, not every
  permutation.
* **Test the states** — not just the happy path. Test loading, empty, error,
  and partial states explicitly.
* **Test keyboard interaction** — Tab through, activate with Enter/Space,
  verify focus management in dialogs and route changes.

---

## Build-mode quality floor (checklist)

Before calling a piece of UI done:

```
[ ] Keyboard: full flow operable, visible focus, no traps, skip-link present
[ ] Contrast: text ≥ 4.5:1 (large ≥ 3:1), UI/icons ≥ 3:1, incl. states & dark mode
[ ] Colour is never the only signal
[ ] Semantics: right elements, labels tied, heading order, alt text, aria-live for dynamic
[ ] Design system: values from tokens/theme, consistent spacing scale, no one-off hardcoded values
[ ] Hierarchy: one clear focal point per view; no generic-AI card-grid/gradient defaults
[ ] States: loading, empty, error, partial all handled
[ ] Forms: labelled, validated at the right time, data preserved on error, correct input types
[ ] Responsive: works at 320px and 200% zoom; touch targets ≥ 24px; no user-scalable=no
[ ] Motion: prefers-reduced-motion respected; quick and interruptible
[ ] i18n: no hardcoded strings; pluralization rules; RTL-safe; text expansion tolerated
[ ] Privacy: fonts/assets self-hosted; no IP leak; consent before non-essential
[ ] Perceived perf: no layout shift, lazy where sensible, Core Web Vitals in budget
[ ] Testing: component tests + a11y automated + keyboard manual test
```

---

## Audit-mode output format

Group findings by dimension, then by severity. Each finding:

```
[SEVERITY] component/file:LINE  (dimension: a11y | ux | design | responsive | i18n | privacy | perf | testing)
  Problem: <what is wrong>
  Impact:  <who it hurts and how — e.g. "keyboard users can't reach the menu">
  Fix:     <specific, actionable change>
```

Severity — same labels as `/better-coding-review`: `[CRITICAL]` (a11y failure
that locks people out, or a legal/privacy violation) · `[MAJOR]` (real
usability harm) · `[MINOR]` (improvement worth making) · `[NIT]` (polish).

Close with: `Verdict: <N critical, M major, K minor, J nits>.` and, for a11y, note
that automated tooling covers only part of the surface — manual keyboard + zoom
+ screen reader checks were/weren't done.

---

## Companions

* `frontend-design` — aesthetic direction (palette, type, layout, signature).
  Use it for *how it looks*; use this skill for *how it works*.
* `/better-coding-orient` — routes to this skill when the task involves UI.
* `/better-coding-workflow` — the engineering discipline for writing the code.
  Pair with this skill when building UI.
* `/better-coding-review` — general code review; this skill is the UX/a11y
  specialisation of the review's frontend concerns.
* `/better-coding-plan` — for non-trivial UI features, plan first (scope,
  states, i18n requirements, component breakdown), then build with this skill.
* `/better-coding-verify` — after UI implementation and review, invoke verify
  for the evidence gate (including a11y automated + manual keyboard testing).
* `/better-coding-audit` — dimension 7 (frontend/UX) defers to this skill for
  depth.