correcting-ui

Files (74)

• SKILL.md
• evals.json · evals/
• AGENTS.md · evals/fixtures/correct/adherence-trap/
• after-good-evidence.json · evals/fixtures/correct/adherence-trap/evidence/
• baseline-evidence.json · evals/fixtures/correct/adherence-trap/evidence/
• package.json · evals/fixtures/correct/adherence-trap/
• capture-deferred.js · evals/fixtures/correct/adherence-trap/scripts/
• verify-correct.js · evals/fixtures/correct/adherence-trap/scripts/
• baseline.styles.scss · evals/fixtures/correct/adherence-trap/src/
• styles.scss · evals/fixtures/correct/adherence-trap/src/
• tokens.scss · evals/fixtures/correct/adherence-trap/src/
• wrong-important.styles.scss · evals/fixtures/correct/adherence-trap/src/
• wrong-magicpx.styles.scss · evals/fixtures/correct/adherence-trap/src/
• tokens.json · evals/fixtures/correct/adherence-trap/
• AGENTS.md · evals/fixtures/correct/cascade-override/
• after-bad-evidence.json · evals/fixtures/correct/cascade-override/evidence/
• after-good-evidence.json · evals/fixtures/correct/cascade-override/evidence/
• baseline-evidence.json · evals/fixtures/correct/cascade-override/evidence/
• package.json · evals/fixtures/correct/cascade-override/
• capture-deferred.js · evals/fixtures/correct/cascade-override/scripts/
• verify-correct.js · evals/fixtures/correct/cascade-override/scripts/
• baseline.styles.scss · evals/fixtures/correct/cascade-override/src/
• baseline.theme.scss · evals/fixtures/correct/cascade-override/src/
• styles.scss · evals/fixtures/correct/cascade-override/src/
• theme.scss · evals/fixtures/correct/cascade-override/src/
• tokens.scss · evals/fixtures/correct/cascade-override/src/
• wrong.styles.scss · evals/fixtures/correct/cascade-override/src/
• tokens.json · evals/fixtures/correct/cascade-override/
• AGENTS.md · evals/fixtures/correct/measurable-padding/
• after-good-evidence.json · evals/fixtures/correct/measurable-padding/evidence/
• baseline-evidence.json · evals/fixtures/correct/measurable-padding/evidence/
• package.json · evals/fixtures/correct/measurable-padding/
• capture-deferred.js · evals/fixtures/correct/measurable-padding/scripts/
• verify-correct.js · evals/fixtures/correct/measurable-padding/scripts/
• baseline.styles.scss · evals/fixtures/correct/measurable-padding/src/
• styles.scss · evals/fixtures/correct/measurable-padding/src/
• tokens.scss · evals/fixtures/correct/measurable-padding/src/
• wrong.styles.scss · evals/fixtures/correct/measurable-padding/src/
• tokens.json · evals/fixtures/correct/measurable-padding/
• AGENTS.md · evals/fixtures/correct/perceptual-residue/
• after-good-evidence.json · evals/fixtures/correct/perceptual-residue/evidence/
• baseline-evidence.json · evals/fixtures/correct/perceptual-residue/evidence/
• package.json · evals/fixtures/correct/perceptual-residue/
• capture-deferred.js · evals/fixtures/correct/perceptual-residue/scripts/
• verify-correct.js · evals/fixtures/correct/perceptual-residue/scripts/
• baseline.styles.scss · evals/fixtures/correct/perceptual-residue/src/
• styles.scss · evals/fixtures/correct/perceptual-residue/src/
• tokens.scss · evals/fixtures/correct/perceptual-residue/src/
• wrong.styles.scss · evals/fixtures/correct/perceptual-residue/src/
• tokens.json · evals/fixtures/correct/perceptual-residue/
• AGENTS.md · evals/fixtures/correct/regression-guard/
• after-bad-evidence.json · evals/fixtures/correct/regression-guard/evidence/
• after-good-evidence.json · evals/fixtures/correct/regression-guard/evidence/
• baseline-evidence.json · evals/fixtures/correct/regression-guard/evidence/
• package.json · evals/fixtures/correct/regression-guard/
• capture-deferred.js · evals/fixtures/correct/regression-guard/scripts/
• verify-correct.js · evals/fixtures/correct/regression-guard/scripts/
• baseline.styles.scss · evals/fixtures/correct/regression-guard/src/
• styles.scss · evals/fixtures/correct/regression-guard/src/
• tokens.scss · evals/fixtures/correct/regression-guard/src/
• …and 14 more

SKILL.md (first lines)

# Correcting UI

The diagnose-and-fix side of the UI iteration loop (Phase 3), the perception-
verified counterpart to the core loop's implement + debug stages. The stated
pain this exists to fix: vision models are weak at translating a *text
description* of a CSS problem into the correct *fix*. The architecture boxes
that weakness out — the capture harness's **matched-styles map** says WHICH
authored rule + source line set each property (a deterministic lookup, not a
guess); the **computed CSS + geometry** say WHAT is actually applied; the
user's prompt says INTENDED. **Vision is the LAST signal (perceptual residue
only), never the first.** Division of labor: the screenshot says *what looks
wrong*; matched-styles says *which rule*; the source says *how it's written*;
the prompt says *intended*; the model never guesses CSS from prose.

A correction pass is **done** when (1) the targeted computed/geometry **delta
was achieved** (the intent's measurable target moved to its objective value),
(2) the **regression guard** holds (no OTHER captured element's bbox or
computed block changed), (3) **stylelint-style adherence** passes (no
specificity raise, no new `!important`, no magic px, naming matches the
system), and (4) the perceptual residue is either **adjudicated by the
vision-critic role** or **honestly deferred** where no vision model is
available. "Looks better" alone is never closure.

## Division of labor with the sibling skill

`correcting-ui` is the **consumer** of `capturing-ui-evidence`'s artifact and
the producer of source edits. The artifact contract is a single source of
truth — link it, never duplicate it:
[../capturing-ui-evidence/references/evidence-schema.md](../capturing-ui-evidence/references/evidence-schema.md)
(top-level shape, `capture_meta`, `entries[]`, the curated computed profile,
`matched_styles` winner + overridden + source locations, determinism, the
`fragile` flag, schema versioning + drift). Capture produces the artifact;
this skill consumes it, edits source, re-captures, and compares.

## The correct pass

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

```
Correct Progress:
- [ ] 1. Resolve target + intent (from the prompt; the plan if one is in play)
- [ ] 2. Detect the CSS system & load the matching system reference
- [ ] 3. Capture the BASELINE (invoke capturing-ui-evidence — execute, do not reimplement)
- [ ] 4. Gate on the artifact; triangulate the FOUR sources to a root-cause rule
- [ ] 5. Edit ADHERING to the system (fixes snap to tokens)
- [ ] 6. Re-capture + compare (objective delta + regression guard)
- [ ] 7. Quality gate (adherence: no specificity raise, no new !important, no magic px)
- [ ] 8. Perceptual acceptance (vision-critic for residue only)
- [ ] 9. Handoff; STOP (no commit unless asked)
```

### Step 1 — Resolve target + intent

Pin two things before touching anything:

- **The target** — which element(s) and viewports the complaint is about.
  Where a `capturing-ui-evidence` artifact is already in hand, the target is
  its `entries[]`; otherwise the prompt names it.
- **The intent** — what the user wants the target to become. Classify it:
  - **measurable** ("make padding 16px", "stop the overflow", "align these
    two", "use the md scale") — closure is the objective delta (Step 6).
  - **perceptual** ("feels cramped", "looks off", "give it room") — decompose
    into measurable proxies (the spacing/density/contrast scale the judgement
    rides on) and close on those; the residue that genuinely has no
    measurable target goes to Step 8.
  - **broad restyle** ("redesign the whole settings page", "modernize this
    view across X, Y, Z") — this is multi-surface visual work, NOT a single
    correction: route to `designing-architecture` (see Implement-class
    boundaries) and
    make zero sprawl edits. A genuine single correction needs no plan
    (trivial-change exemption); a broad overhaul needs one.

Where a plan artifact is in play, reconcile the intent with the plan's
acceptance criteria; where the prompt's request exceeds the plan's scope,
record it as a follow-up (the `implementing-features` posture, reused below).

### Step 2 — Detect the CSS system & load the matching system reference

The CSS methodology is a **plugin dimension**. Detect it from the rules file
(`AGENTS.md` / `.opencode/agents.md`) PLUS config files: a `tailwind.config.*`
→ Tailwind; a Vuetify theme config / `@use 'vuetify/...'` / `*.scss` with
`$tokens` and `.v-theme--*` rules → Vuetify-SCSS; `__`/`--` class dunders +
a `selector-class-pattern` stylelint rule → BEM. Load the matching reference
under `references/systems/` (resolved against this skill's own directory —
not the project's). If undetectable, **ask one question** rather than guessing
the methodology — a fix written against the wrong system is wrong twice.

Available system references:

- vuetify-scss → [references/systems/vuetify-scss.md](references/systems/vuetify-scss.md)
  — Vuetify 3 theme tokens + SCSS `$variables`; prefer component props /
  semantic classes over raw CSS; the `.v-theme--light .x` descendant override
  is where the winner often lives; no `::v-deep` unless unavoidable; vendor-
  source winners route to props, not vendored edits.
- bem → [references/systems/bem.md](references/systems/bem.md) —
  `block__element--modifier` naming + flat specificity (one class per
  selector); the cascade resolves on source order, never on specificity or
  `!important`.
- tailwind → [references/systems/tailwind.md](references/systems/tailwind.md)
  — utilities compose in markup; `@apply` sparingly in a component layer; no
  bespoke class selectors in raw CSS; snap to the `tailwind.config` scale.

If none matches, proceed generically and flag the gap in the handoff (a
missing system reference is a finding, not a silent "I'll improvise").

### Step 3 — Capture the BASELINE — invoke capturing-ui-evidence

The baseline is an evidence artifact, not a screenshot you eyeball. **Execute**
the sibling skill's harness — do NOT reimplement capture, do NOT read its
script as reference, do NOT settle for a `getComputedStyle` in devtools. The
artifact is the addressable input Step 4 triangulates.

Invoke `capturing-ui-evidence` for the target (selectors × viewports), in app
mode (a running dev-server route, auth via the e2e auth-fixture pattern) or
component mode (an isolated harness over `file://`) — the sibling skill
selects based on the target the invocation names. See
[../capturing-ui-evidence/SKILL.md](../capturing-ui-evidence/SKILL.md) for the
invocation and `scripts/capture.mjs --help` for the selector grammar. The
baseline captures: per (selector × viewport) the curated computed CSS, the

From hierovision/ai-framework, MIT.

More from hierovision/ai-framework