code-yeongyu/oh-my-openagent / packages/shared-skills/skills/visual-qa
visual-qa
VerifiedRuns rigorous visual QA across web, terminal, and paginated surfaces: an Apple HIG-based checklist, paired light/dark captures at phone and desktop widths, screenshot evidence, and a per-item PASS/FAIL verdict. Use for any UI build or change, or when asked whether a page, component, or TUI looks right or follows the platform's design guidelines.
| File | Kind | Size |
|---|---|---|
| AGENTS.md | markdown | 3.2 KB |
| SKILL.md | skill md | 45.7 KB |
| references/browser-setup.md | markdown | 5.6 KB |
| scripts/ansi.test.ts | script | 1.1 KB |
| scripts/ansi.ts | script | 496 B |
| scripts/cli.test.ts | script | 2.9 KB |
| scripts/cli.ts | script | 2.5 KB |
| scripts/east-asian-width.test.ts | script | 1.9 KB |
| scripts/east-asian-width.ts | script | 3.0 KB |
| scripts/image-diff.test.ts | script | 2.5 KB |
| scripts/image-diff.ts | script | 3.8 KB |
| scripts/png-crc.ts | script | 707 B |
| scripts/png-decode.test.ts | script | 1.5 KB |
| scripts/png-decode.ts | script | 5.5 KB |
| scripts/png-synth.ts | script | 1.7 KB |
| scripts/skill-doc-fields.test.ts | script | 1.6 KB |
| scripts/tui-grid.test.ts | script | 1.9 KB |
| scripts/tui-grid.ts | script | 2.7 KB |
| scripts/types.ts | script | 1.3 KB |
| scripts/visual-qa.mjs | script | 15.8 KB |
AGENTS.md
View on GitHub# visual-qa — Bundled Visual-Evidence CLI
**Generated:** 2026-08-24 (f3642fcda)
## OVERVIEW
The visual-QA skill's executable core: a zero-dependency Node CLI that produces machine evidence (`image-diff`, `tui-check`) plus the TypeScript sources it is bundled from. Earned this file: the only shared skill shipping a built bundle whose runtime and development sources must be kept in lockstep.
## STRUCTURE
```
visual-qa/
├── SKILL.md # reviewer workflow (dual oracle, evidence gates) — the prose contract
├── references/browser-setup.md
└── scripts/
├── visual-qa.mjs # SHIPPED RUNTIME: bun-build bundle of cli.ts (+ embedded modules)
├── cli.ts # development source; dispatches image-diff / tui-check
├── image-diff.ts # diffImages — 8x8 grid cells, hotspots, rounded metrics
├── tui-grid.ts # checkTui — column overflow + border alignment verdicts
├── east-asian-width.ts # charWidth / stringWidth — CJK-aware width math
├── ansi.ts # ANSI escape stripping (width must be escape-aware)
├── png-decode.ts / png-crc.ts / png-synth.ts # stdlib PNG codec (no deps)
├── types.ts
└── *.test.ts # co-located bun tests for every module above
```
## BUNDLE/SOURCE DUALITY
`visual-qa.mjs` is the artifact the skill's commands invoke (`node "$SKILL_DIR/scripts/visual-qa.mjs" …`); the `.ts` files exist for development and tests only. A behavior fix lands in the TS source AND the bundle is regenerated from `cli.ts` — editing one without the other makes tests and runtime disagree. Never hand-edit the `.mjs`.
## SURFACE
- Commands: `image-diff <reference.png> <actual.png>` and `tui-check <capture.txt> --cols <N>`; JSON verdict output (hotspot cells, overflow lines, wide-char columns, border alignment).
- Module exports: `diffImages`, `checkTui`, `charWidth`/`stringWidth`, ANSI + PNG helpers. `cli.ts` owns `CliError`, `parseColumns`, `run`, `main`.
## CONVENTIONS
- Zero runtime dependencies — PNG decode/synthesis and ANSI handling are hand-rolled in `scripts/`; keep it that way (the bundle must stay require-free apart from `node:` builtins).
- Width is never `String.length`: CJK wide characters and ANSI escapes are accounted for before any column math.
- Tests are co-located `bun test scripts/*.test.ts`, given/when/then style per repo convention.
## ANTI-PATTERNS
- NEVER hand-edit `visual-qa.mjs`; regenerate from source.
- Don't add an npm dependency to make PNG/diff easier — the no-dep bundle is the point.
- Column math that ignores CJK width or ANSI escapes is wrong by construction; `tui-check` exists because text-diff tools get terminal grids wrong.
- Skill-level rule worth repeating for code changes: `tmux capture-pane` is forbidden as a capture mechanism.
## COMMANDS
```bash
# from packages/shared-skills/skills/visual-qa/
node scripts/visual-qa.mjs image-diff <reference.png> <actual.png>
node scripts/visual-qa.mjs tui-check <capture.txt> --cols 80
bun test scripts/*.test.ts
```
- Parent (source checkout only; not shipped with the skill): `packages/shared-skills/AGENTS.md`.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |