Theme Acceptance Criteria
Set the bar every theme has to clear before it ships to anyone.
What it adds
A release gate for light, dark, branded, and customer-supplied themes, covering contrast, first paint, tokens, and print.
What your agent is told to do
5
What your agent is told to do
5-
1
Write the criteria against the theme layer, not against individual screens. The question is whether a set of token values is fit to ship, and the answer should not require walking every page by hand.
-
2
Require measured contrast for text, icons, borders, focus rings, and disabled content in every interactive state — resting, hover, focus, active, and selected — because a palette that passes at rest often fails on hover.
-
3
Cover the surfaces that sit outside the component library: chart series and their gridlines, map and image overlays, embedded documents, illustrations, and any asset shipped as a fixed-colour file that will not follow the theme.
-
4
State what the first paint must look like. The stored theme has to be resolved before anything renders, and a flash of the wrong theme is a failure of the gate, not a cosmetic quibble.
-
5
Do not duplicate the per-component bar set by Component Acceptance Criteria. That document owns whether a component behaves correctly; this one owns whether a set of theme values is safe to apply across every component at once.
Edge cases it handles
7
Edge cases it handles
7- Contrast must be checked in each interactive state and against each surface a component can sit on — a token that passes on the page background can fail on a card, a modal, or a coloured banner.
- Charts, overlays, and shipped image assets are the usual escapees: a chart series palette tuned for a light background turns unreadable on dark, and a logo baked as a dark PNG disappears entirely.
- First paint has to be tested with an empty cache and a slow connection, since a theme flash is invisible on a warm local reload and glaring for a real user.
- A customer-supplied or branded theme can arrive with missing tokens, malformed values, or a brand colour that fails contrast — validate it on entry, refuse or correct what is unusable, and never let a partial token set render as a half-applied theme.
- Print and forced-colours mode both override the theme in ways the app does not control, so each needs its own line: print on white regardless of the active theme, and forced colours without relying on colour alone to convey state.
- A theme change while the app is open must repaint everything, including portals, toasts, and any component holding a colour it resolved once at mount.
- The theme that follows the operating system preference must still honour an explicit user override, and the gate should check that the override wins.
Definition of done
9
Definition of done
9- Every theme is checked against the gate before release, including customer-supplied ones.
- Contrast is measured for text, icons, borders, and focus rings in every interactive state and on every surface.
- Charts, overlays, and fixed-colour assets are covered by explicit criteria rather than assumed to follow the theme.
- First paint on a cold cache shows the correct theme with no flash.
- Custom token sets are validated on entry and a partial set is refused rather than half-applied.
- Print output and forced-colours mode each have their own stated pass conditions.
- Per-component behaviour is left to Component Acceptance Criteria and not restated here.
- The feature matches the existing design system.
- No existing functionality is broken.
Related features
Interaction Test Harness
Interaction Test Harness
Test the app the way a person uses it, through real clicks, keys, and focus.
What it does
A test setup that drives menus, dialogs, forms, and navigation through genuine user interactions and asserts on what the user can see.
How it works
- 1 Find elements the way a user finds them — by their visible label, their role, and their accessible name — rather than by class names or internal test hooks, so a test breaks when the interface becomes unusable and not when a wrapper is renamed.
- 2 Drive each interaction through both pointer and keyboard where both are supported, and assert on where focus ends up as well as on what the screen shows.
- 3 Assert on the visible outcome and wait for it to appear, rather than sleeping for a fixed interval and hoping. A timer-based wait is either slow on every run or flaky on a loaded machine.
Copy the prompt
No account needed
Add this feature to my app:
https://addthisfeature.com/x/interaction-test-harness
UX Edge-Case Checklist
UX Edge-Case Checklist
Make every UI feature state what it does when things go wrong before it counts as done.
What it does
A required list of non-happy-path behaviours — failure, empty, loading, offline, permission, mobile, and accessibility — answered per feature.
How it works
- 1 Attach the checklist to the point where work is proposed and to the point where it is reviewed, so the answers exist before the feature is built rather than being reconstructed afterwards.
- 2 Require a concrete answer for each category: what the empty state says and what it offers, what appears while data is loading, what the user sees when the request fails, and what a user without permission gets instead.
- 3 Make each answer an outcome someone else could verify. A feature that says errors are handled has not answered; one that says a failed save keeps the form open with the values intact and a retry has.
Copy the prompt
No account needed
Add this feature to my app:
https://addthisfeature.com/x/ux-edge-case-checklist
Design QA Checklist
Design QA Checklist
Give interface work a consistent review before it merges.
What it does
A short review pass over hierarchy, spacing, states, copy, responsiveness, and accessibility, applied to every change that touches the interface.
How it works
- 1 Write the checklist as a small number of concrete questions a reviewer can answer by looking at the running change, not as a list of principles nobody can verify.
- 2 Require every state to be shown, not described: loading, empty, error, partial, permission-denied, and the state with far more content than expected. A review that only sees the populated happy path approves half a feature.
- 3 Require a keyboard pass and a zoom pass on every change: tab through the new interface without touching the pointer, and view it at 200 per cent zoom with increased text size.
Copy the prompt
No account needed
Add this feature to my app:
https://addthisfeature.com/x/design-qa-checklist
How it works
-
1
Copy the link
Grab the Markdown instruction URL for this feature.
-
2
Give it to your AI
Paste it into Claude Code, Cursor, v0, Lovable — whatever you build with.
-
3
It inspects, then implements
Your agent reads your existing app first, then adds the feature to fit it.
Works with your stack
These instructions are written to adapt. They tell the agent to detect your framework, match your existing design system, and reuse what you already have — rather than assuming a particular stack.
Need it tighter than that? Customize the feature and tell it exactly what you're running.