UI Check Framework
Overview
Create or refine an automated UI self-check system that discovers UI blocks via data-qa
tags and enforces behavioral/visual contracts (themes, animations, loading, layout
stability, modal usability, error visibility). The framework must scale to new cards,
modals, toasts, and actions without writing new test cases each time.
Workflow (use in order)
Inspect existing scaffolding
- Prefer reusing the project's
ui-tests/ folder if it exists.
- Read
ui-tests/docs/UI_TESTING.md and ui-tests/docs/QA_TAGGING.md if present.
- Confirm scripts in root
package.json (ui:test, ui:update-baseline,
ui:report, ui:check, ui:watch) point at Playwright flows.
Enforce discovery
- Auto-collect all
data-qa or data-testid elements that start with qa:.
- Capture component screenshots (cards, modals, menus, toolbars, toasts) at
small/medium/large sizes.
- For modals: verify internal scroll, single close button, and header visibility
at small window height.
Enforce contracts (generic, not hardcoded)
- Theme contrast/readability for dark/light/system (see references).
- Animation/motion checks for spinners, transitions, toasts.
- Loading state machine for async actions: idle -> loading -> success/error -> idle.
- Layout stability (no layout shift for transient status/toasts).
- Overlap detection for action buttons and modal header/footer.
- Error visibility and blank-page detection.
Wire UI hooks for automation
- Add minimal
window.__ui_check__ helpers (e.g., append log, trigger toast) to
make contracts testable without hardcoding selectors.
- Add required
data-qa tags to new cards/modals/actions as they appear.
Artifacts and reporting
- Store artifacts under
artifacts/ui-check/ (snapshots, frames, video, report.html).
- Ensure
ui:check is interactive (open/close modal, hover/press, theme toggle, scroll).
Project-specific anchors
- Primary UI tests live in
ui-tests/ and use Playwright.
- Use
ui-tests/scripts/ui-check.mjs and ui-tests/scripts/ui-watch.mjs as the
interactive validation entry points.
- Keep user-facing docs in
ui-tests/docs/UI_TESTING.md and
ui-tests/docs/QA_TAGGING.md.
References
references/workflow.md - extension workflow and verification checklist.references/qa-tagging.md - required QA tokens and naming conventions.references/contracts.md - required generic contracts and how to check them.
1---2name: ui-check-framework3description: Build or extend an extensible UI self-check framework for Web UIs (React/Vite or plain HTML) using Playwright. Use when asked to add/upgrade ui-check or ui-watch flows, enforce data-qa/data-testid discovery, add theme/contrast checks, animation verification, loading state-machine checks, layout stability/overlap checks, modal scroll rules, or to document QA tagging standards and UI testing commands.4---5
6# UI Check Framework
7
8## Overview
9
10Create or refine an automated UI self-check system that discovers UI blocks via data-qa
11tags and enforces behavioral/visual contracts (themes, animations, loading, layout
12stability, modal usability, error visibility). The framework must scale to new cards,
13modals, toasts, and actions without writing new test cases each time.
14
15## Workflow (use in order)
16
171) **Inspect existing scaffolding**
18 - Prefer reusing the project's `ui-tests/` folder if it exists.
19 - Read `ui-tests/docs/UI_TESTING.md` and `ui-tests/docs/QA_TAGGING.md` if present.
20 - Confirm scripts in root `package.json` (`ui:test`, `ui:update-baseline`,
21 `ui:report`, `ui:check`, `ui:watch`) point at Playwright flows.
22
232) **Enforce discovery**
24 - Auto-collect all `data-qa` or `data-testid` elements that start with `qa:`.
25 - Capture component screenshots (cards, modals, menus, toolbars, toasts) at
26 small/medium/large sizes.
27 - For modals: verify internal scroll, single close button, and header visibility
28 at small window height.
29
303) **Enforce contracts (generic, not hardcoded)**
31 - Theme contrast/readability for dark/light/system (see references).
32 - Animation/motion checks for spinners, transitions, toasts.
33 - Loading state machine for async actions: idle -> loading -> success/error -> idle.
34 - Layout stability (no layout shift for transient status/toasts).
35 - Overlap detection for action buttons and modal header/footer.
36 - Error visibility and blank-page detection.
37
384) **Wire UI hooks for automation**
39 - Add minimal `window.__ui_check__` helpers (e.g., append log, trigger toast) to
40 make contracts testable without hardcoding selectors.
41 - Add required `data-qa` tags to new cards/modals/actions as they appear.
42
435) **Artifacts and reporting**
44 - Store artifacts under `artifacts/ui-check/` (snapshots, frames, video, report.html).
45 - Ensure `ui:check` is interactive (open/close modal, hover/press, theme toggle, scroll).
46
47## Project-specific anchors
48
49- Primary UI tests live in `ui-tests/` and use Playwright.
50- Use `ui-tests/scripts/ui-check.mjs` and `ui-tests/scripts/ui-watch.mjs` as the
51 interactive validation entry points.
52- Keep user-facing docs in `ui-tests/docs/UI_TESTING.md` and
53 `ui-tests/docs/QA_TAGGING.md`.
54
55## References
56
57- `references/workflow.md` - extension workflow and verification checklist.
58- `references/qa-tagging.md` - required QA tokens and naming conventions.
59- `references/contracts.md` - required generic contracts and how to check them.
majiayu000