light-dark-integrity

name	light-dark-integrity
description	Detect, triage, repair, and certify light/dark theme violations for Pattern Patrol P4. Use for raw bg-white/text-black classes, invisible theme states, or any P4 patrol run.

Light/Dark Integrity

Apply this skill only after reading the Pattern Patrol system, the P4 registry row, the repo CLAUDE.md, the pattern-patrol skill, and ui-dense/data-dense-rules.md section 1. Those safety rules remain binding.

Detect

Run the deterministic detector from the repository root:

node .claude/skills/light-dark-integrity/scripts/detect-light-dark.mjs

Pass explicit .tsx paths to scan a structural-novelty scope. Use --json for a machine-readable report and --strict to fail on pending or invalid exceptions. A candidate is not automatically a defect, compliant, or exempt.

The detector reports every source line containing bg-white or text-black, whether a dark: token exists on that line, and a possible exception hint. Review the whole component and every place a shared component renders. Never clear a candidate from a file-level dark: token elsewhere in the file.

Classify each candidate

Choose exactly one surface class:

1. Theme surface — page, panel, card, row, menu, popover, dialog, input, or control whose appearance must follow the active theme. Raw white/black is a defect unless an explicit paired design is necessary.
2. Proposed fixed/on-color exception — chrome over a photo, video, gradient, canvas, crop handle, camera, code block, or other surface whose local contrast may be independent of the app theme. Propose it to Arman; never preserve or clear it on agent judgment alone.
3. Non-app output — print rules, HTML/iframe matte, exported image/PDF, email, or an authored visual specimen. If the raw palette is deliberate, propose it to Arman unless the source is truly non-rendered test/comment text.
4. Explicit theme selection — the opposite theme is selected through a theme prop, conditional class, variable, or multiline construction. Verify both branches. A real two-theme branch is compliant, not an exception.

If the class is unclear, the finding is Tier R. Report it; do not mutate.

Mechanical repair table

For a verified theme surface, use the narrowest semantic token:

Meaning	Required class
Page/application background	bg-background
Card or bounded content surface	bg-card
Subdued section or row	bg-muted
Floating menu/popover	bg-popover
Primary text	text-foreground
Secondary text	text-muted-foreground
Normal boundary	border-border
Neutral hover/focus fill	hover:bg-accent / focus-visible:bg-accent

Keep a raw palette plus a dark: pair only when no semantic token expresses an intentional two-theme design and both exact colors are already established by the surrounding component. Do not invent a new pair during a patrol.

For a shared primitive used on both theme surfaces and fixed/on-color surfaces, add an explicit, narrowly named surface variant. The default must use semantic theme tokens; the fixed/on-color call site opts into its established overlay classes. Do not force either side's styling onto the other.

Do not change layout, interaction, wording, component boundaries, imports, or chunking. Do not create a new global token during a patrol. If the repair needs design judgment or a new token, downgrade it to Tier R.

Required false-positive review

Before counting or fixing, review all candidates against:

• print: rules and printed/exported documents;
• iframe, HTML preview, page-preview, and white-paper mattes;
• media, camera, crop, canvas, image, video, and gradient overlays;
• fixed visual specimens, games, loaders, and immersive authored designs;
• explicit theme props/conditionals and multiline dark: pairing;
• comments, fixtures, samples, and non-rendered strings;
• deliberately chosen contrast where the semantic foreground would fail.

Record the reason for every excluded class in the patrol report. Never add a suppression or detector allowlist merely to make the output smaller.

Human-owned exception approval

Agents propose; Arman approves. A plausible fixed palette is still an open finding until Arman explicitly approves that exact surface. No certifier, maintainer, prior styling, or “intentional” code comment substitutes for his decision.

Every proposal must include:

• exact file, line, raw token(s), and visual state;
• a stable production URL plus precise click/state instructions;
• what would change if semantic tokens replaced it;
• an Approve or Reject decision request.

If no stable URL or reproducible artifact exists, the item cannot be approved. Keep it open and create a Tier-C review-harness task. End any run containing proposals with this unmistakable envelope:

EXCEPTION APPROVAL REQUIRED
<complete numbered proposal list>
ARMAN, WE NEED YOU: approve or reject every listed P4 exception.

Only after approval, add one entry to exceptions.json with approvedBy set to Arman, the approval date/reference, review URL, exact token list, file, line, and reason. Add a source comment within two lines of that exact line:

patrol-exception:P4-EX-###

The detector validates ledger ↔ source agreement and exact line/token identity. It reports approved exceptions separately forever; it never silently removes them from totals. An unapproved comment, missing comment, moved token, stale pair, or one-to-many annotation is an invalid exception and a loud finding. Rejection means fix it; never record the rejection as an exemption.

Tier-M batch and certification

Keep each batch at 15 files or fewer. Run pnpm type-check and relevant gates. Then spawn a second adversarial agent with the exact brief:

assume this broke something; find it.

The certifier reruns the detector and gates, inspects every changed surface in light and dark at desktop and mobile viewports, reviews the exception classes, and returns only CERTIFIED or REJECTED with evidence. Fix or fully revert a rejected batch. Nothing ships mostly.