capturing-ui-evidence

Files (34)

• SKILL.md
• evals.json · evals/
• AGENTS.md · evals/fixtures/phasewave/determinism-curation/
• bad-evidence.json · evals/fixtures/phasewave/determinism-curation/
• index.html · evals/fixtures/phasewave/determinism-curation/harness/
• styles.css · evals/fixtures/phasewave/determinism-curation/harness/
• package.json · evals/fixtures/phasewave/determinism-curation/
• capture-deferred.js · evals/fixtures/phasewave/determinism-curation/scripts/
• check-determinism.js · evals/fixtures/phasewave/determinism-curation/scripts/
• fake-chromium.mjs · evals/fixtures/phasewave/determinism-curation/scripts/
• validate-evidence.js · evals/fixtures/phasewave/determinism-curation/scripts/
• verify-capture.js · evals/fixtures/phasewave/determinism-curation/scripts/
• AGENTS.md · evals/fixtures/phasewave/isolated-component/
• bad-evidence.json · evals/fixtures/phasewave/isolated-component/
• index.html · evals/fixtures/phasewave/isolated-component/harness/
• styles.css · evals/fixtures/phasewave/isolated-component/harness/
• package.json · evals/fixtures/phasewave/isolated-component/
• capture-deferred.js · evals/fixtures/phasewave/isolated-component/scripts/
• fake-chromium.mjs · evals/fixtures/phasewave/isolated-component/scripts/
• validate-evidence.js · evals/fixtures/phasewave/isolated-component/scripts/
• verify-capture.js · evals/fixtures/phasewave/isolated-component/scripts/
• AGENTS.md · evals/fixtures/phasewave/real-app-route/
• auth.mjs · evals/fixtures/phasewave/real-app-route/auth/
• bad-evidence.json · evals/fixtures/phasewave/real-app-route/
• index.html · evals/fixtures/phasewave/real-app-route/harness/
• styles.css · evals/fixtures/phasewave/real-app-route/harness/
• package.json · evals/fixtures/phasewave/real-app-route/
• capture-deferred.js · evals/fixtures/phasewave/real-app-route/scripts/
• fake-chromium.mjs · evals/fixtures/phasewave/real-app-route/scripts/
• validate-evidence.js · evals/fixtures/phasewave/real-app-route/scripts/
• verify-capture.js · evals/fixtures/phasewave/real-app-route/scripts/
• evidence-schema.md · references/
• vue-supabase.md · references/stacks/
• capture.mjs · scripts/

SKILL.md (first lines)

# Capturing UI Evidence

The capture side of the UI iteration loop — the perception-verified
counterpart to the core loop's "reproduce" step. It makes the visual state
**observable and machine-comparable** by writing a structured, addressable
evidence artifact that `correcting-ui` consumes to map a visual symptom to
the exact source rule. This skill **captures deterministically**; it does
**not** diagnose, interpret, or edit. Division of labor: capture says
*which rule, where*; the fixer says *what to change*; the prompt says
*intended*.

A capture pass is **done** when the evidence artifact exists, is
schema-valid, covers every requested (selector × viewport), screenshots are
written, and the matched-styles map is populated for each selector. The skill
reports the artifact path + a one-line inventory and **STOPs** — it never
judges the evidence.

## The capture pass

Copy this checklist and check off items as you complete them.

```
Capture Progress:
- [ ] 1. Identify the input (target, selectors, viewports)
- [ ] 2. Detect stack & load the matching capture-stack reference
- [ ] 3. Invoke the harness (scripts/capture.mjs) — execute, do not reimplement
- [ ] 4. Objective closure (validate the artifact; defer the real browser)
- [ ] 5. Hand off the artifact + inventory; STOP
```

### Step 1 — Identify the input

Three things define a capture run; pin them before invoking the harness:

- **The target, which selects the mode.** A *real running app* — a dev-server
  URL + a route — is **app mode** (`--mode app --target http://localhost:5173
  --route /dashboard`). An *isolated component* — a Storybook-style harness
  HTML entry — is **component mode** (`--mode component --target
  ./harness/index.html`, loaded over `file://`, no dev server). The invocation
  names which; the harness handles both. If the view needs a session, pass
  `--auth-fixture <p.mjs>` (app mode) — the e2e auth-fixture pattern, not a
  login-UI replay.
- **The selectors.** Resolve by role / accessible name (label) / data-testid
  in that preference order — the `writing-e2e-tests` doctrine, reused. A
  bare-CSS selector (`css:.v-card`, or any unprefixed selector) is a **last
  resort** and is flagged `fragile: true` in the artifact so the fixer knows
  the target address was fragile. Prefer adding a `data-testid` to an opaque
  component over reaching for a class. Multi-target runs comma-separate specs.
  The grammar lives in `scripts/capture.mjs --help`.
- **The viewports.** One or more `WxH` specs (e.g. `375x667,1280x720`).
  Viewport + device scale factor are **pinned** by the harness — a re-capture
  with the same specs yields the same computed values (see below).

### Step 2 — Detect stack & load the matching capture-stack reference

Identify the project stack from the rules file (`AGENTS.md` /
`.opencode/agents.md`). If this skill bundles a matching reference under
`references/stacks/` (resolved against this skill's own directory — not the
project's), read it now and apply its capture concerns. If none exists,
proceed generically and flag the gap in the handoff.

Available stack references:

- vue-supabase → [references/stacks/vue-supabase.md](references/stacks/vue-supabase.md)
  Read when the project is Vue 3 + Pinia + Vuetify 3 + Supabase + Playwright.
  Applies Vite dev-server startup, the auth-fixture session setup for
  capture, Vuetify component-root selectors, the `.v-theme--light` theme
  specificity overflow (where silent overrides come from), and the isolated
  component harness entry (mount under `v-app` so the cascade is reproduced).

### Step 3 — Invoke the harness (execute, do not reimplement)

`scripts/capture.mjs` is the bundled "right tool for the job": a Playwright +
CDP harness that is more reliable than generated code and costs zero context
until its output returns. **Execute** it — do not read it as a reference and
do not reimplement its capture logic in the conversation. Invoke it:

```bash
# app mode — a real running route, auth via the e2e auth-fixture pattern
node <this-skill>/scripts/capture.mjs \
  --mode app --target http://localhost:5173 --route /dashboard \
  --selectors "role:button[Submit],testid:submit-btn" \
  --viewports 375x667,1280x720 --out ./evidence \
  --auth-fixture e2e/fixtures/auth.mjs

# component mode — an isolated component harness over file://
node <this-skill>/scripts/capture.mjs \
  --mode component --target ./harness/index.html \
  --selectors "role:button[Submit]" \
  --viewports 375x667,1280x720 --out ./evidence
```

The harness writes, per run, to `--out`:
- a full-page PNG per viewport and an element-clipped PNG per
  (selector × viewport), with **stable** filenames;
- `evidence.json` — the schema-versioned artifact: per (selector × viewport)
  the **curated** computed-CSS profile (NOT all ~300 longhands — a named,
  documented set; pass `--profile full` only when the curated set misses the
  property under investigation), the bounding box, and the **CDP
  matched-styles map**: for each captured property, which authored selector +
  source URL + line/column set it, and what overrode it. This is the key
  value — it collapses symptom→source mapping into a deterministic lookup so
  the fixer never guesses CSS from prose.

The key value comes from a CDP session (`CSS.getMatchedStylesForNode` +
`CSS.getComputedStyleForNode` + `CSS.getInlineStylesForNode`) the harness
opens; the agent never touches it directly.

**Dependency resolution (do this before invoking).** `capture.mjs` does
`await import('playwright')`, which ESM resolves from the script's own
location. When the skill is installed globally (symlinked into
`~/.config/opencode/skills/`), that location is NOT the project, so a
project-local `playwright` will not be found and the harness exits
without writing an artifact. Ensure `playwright` is resolvable from the
run — the reliable options, in order: (a) run with the project's modules
on the path, `NODE_PATH=<project>/node_modules node .../capture.mjs …`;
(b) if the skill dir is writable, install `playwright` there once; (c)
copy `capture.mjs` into the project and run it from the project root. If
the harness errors with `Cannot find package 'playwright'`, this is the

From hierovision/ai-framework, MIT.

More from hierovision/ai-framework