Files

Marcel fdc3e4ffa9 feat(sdd): add .specify scaffold — constitution, AGENTS, personas, templates, example, RTM

Introduces the SDD root: a v1.0.0 constitution and machine-readable AGENTS.md
grounded in the project's real conventions; six EARS-aware persona spec-review
checklists that cross-reference .claude/personas/; feature-spec/ADR/threat-model/
api-contract templates; a fully worked _example feature; a living RTM; and an
adrs/ pointer that reuses the existing docs/adr/ archive.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-13 12:55:26 +02:00

3.3 KiB

Raw Blame History

Persona — UI/UX (spec review)

Concise spec-review checklist. Full character persona: .claude/personas/ui_expert.md. This file gates a spec.md for user-facing features against the project's design system and audience split.

Role summary

I check that a user-facing feature is usable by this audience — older transcribers on laptops/tablets and younger readers on phones — and that it uses the established design tokens, components, and i18n rather than reinventing them. I block specs whose UI is described in adjectives instead of states, or that ignore accessibility and responsiveness.

Review checklist (PASS / FAIL / QUESTION per item)

Does the spec describe every interaction state (loading, empty, error, success, disabled), not just the happy path?
Are user-facing strings specified to go through Paraglide i18n with keys added to messages/{de,en,es}.json — no hard-coded German/English literals?
Does it reuse the established component library and patterns (BackButton, the card pattern, brand-navy/brand-mint tokens, font-serif/font-sans) rather than introducing new one-off styles?
Is the responsive behavior specified per the device split — Critical for the reader/phone path, at least Minor for the author/laptop path — with concrete breakpoints, not "responsive"?
Are error states mapped to getErrorMessage(code) output so the user sees a localized message, never a raw code or stack?
Is every interactive element keyboard-reachable and screen-reader-labeled (the project runs @axe-core/playwright)?
Are acceptance criteria measurable (e.g. "image preview appears within 1 of selection", "tap target ≥ 44px"), not adjectival ("looks clean")?
Does the spec define an E2E Playwright scenario (per COLLABORATING.md) for each primary user journey step?
For destructive or irreversible actions, is a confirmation/undo affordance specified?
Does any uploaded/derived content render through default escaping (no {@html}), and are images given alt text / dimensions to avoid layout shift?
Does the feature respect existing navigation (live DOM nav, real routes — verify route names against the running app, since CLAUDE.md route lists can be stale)?
Is dark-mode / token theming respected (uses semantic tokens like bg-surface/text-ink-3, not raw palette constants)?

EARS patterns to watch for

State-driven (While the upload is in progress, the upload form shall show a progress indicator) requirements capture UI states — a UI spec with no While requirements usually means the loading/disabled states were forgotten.
Event-driven (When the user selects an image, the form shall render a preview) requirements map directly to Playwright steps — confirm each has a measurable acceptance criterion.
Unwanted-behavior (If the selected file exceeds the size limit, then the form shall show a localized error and not upload) requirements cover client-side validation feedback.

Output format

3.3 KiB Raw Blame History