Find and fix visual instability in React and browser UIs. This skill operates in two modes depending on what is known at invocation time.
Decision Tree
Determine the mode before doing any work:
Is there a specific visual complaint? (The user describes something they can see: flicker, blink, flash, jump, stutter, pop-in, scroll reset, focus loss, "the whole pane feels rebuilt.")
- Yes -- go to Mode B: Runtime Investigation
- No (general review, PR check, preventive sweep, or just a file/directory target) -- go to Mode A: Static Analysis
If unsure, start with Mode A. Its findings often explain the complaint without runtime tooling.
Mode A -- Static Analysis
Use when: reviewing a PR, scanning changed files, doing a preventive sweep, or no specific symptom is reported.
- Read references/static-patterns.md for the full pattern catalog.
- Read references/scan-process.md for scope rules, severity rubric, output format, and guardrails.
- Identify scope: changed files in the current branch (
git diff --name-only against base), or the user-specified target and its direct imports.
- Scan each React component against all patterns.
- Report findings grouped by component, ranked by severity.
Stop here unless a finding warrants runtime confirmation or the user escalates.
Mode B -- Runtime Investigation
Use when: the user reports something visible -- flicker, blink, flash, jump, snap, stutter, pop-in, scroll reset, focus loss, or "the whole pane feels rebuilt."
Step 1 -- Classify the symptom
| Bucket |
Symptoms |
flash / blink |
subtree replaced, hidden, or briefly emptied |
jump / snap |
layout shifts, size changes, scroll resets |
sticky / stutter |
long tasks, frame gaps, render storms |
pop in |
post-paint correction from effects, fonts, images, async state |
whole pane rebuilt |
keyed remount or identity loss |
Anchor each finding: Which stable surface lost identity, visibility, position, or continuity during this interaction?
Step 2 -- Pick the lightest investigation path
Do not start with a heavyweight trace unless the lighter pass fails to explain the symptom.
Step 3 -- Escalate
Each reference file contains its own escalation rules. Move to the next layer only when the current one is insufficient.
Done Criteria
- You can state the likely cause AND either provide a code fix or identify what telemetry to add.
- Max escalation depth: 2 layers. If the second investigation path doesn't explain the symptom, report what you found and what remains unknown. Do not keep escalating.
Hybrid: Static + Runtime
When a runtime complaint maps to a static pattern (e.g., "it flashes on load" and you find effect-driven state initialization), run Mode A on the relevant files first. If the static finding explains the symptom, fix it without runtime tooling. If not, proceed to Mode B.
Output
Mode A: Findings grouped by component. Each finding includes pattern name, severity, what the user sees, code location, and a specific fix (not generic advice). End with a severity summary. Full format in references/scan-process.md.
Mode B: Report in this order:
- Interaction: what was tested
- Classification: remount, layout, loading, post-paint, or paint/composite
- Evidence: concrete metrics, trace signals, or selector replacement findings
- Likely cause: highest-confidence explanation
- Next action: code fix, deeper trace, or telemetry
If you create a reusable probe or report during the audit, keep it opt-in unless the repo already budgets against it.
Scope
This skill covers the narrow band of issues that are visual, temporal, and caused by React's render model or browser rendering -- things that make a UI feel janky even when everything else is correct.
It does NOT cover runtime performance (slow renders, memory leaks), accessibility, design quality, or error handling. Defer those to the appropriate specialized skill.
1---2name: dejank3description: Detect and diagnose visual jank in React UIs. Covers two modes -- static analysis of code patterns that cause flicker, layout shift, and flash of intermediate state (for pre-merge review or preventive sweeps), and runtime investigation of specific visual symptoms (flicker, blink, jump, stutter, remount churn, scroll reset, post-paint correction). Use when the user mentions jank, something feeling off, flashing, blinking, layout shifting, full repaints, or wants a render stability audit.4---56Find and fix visual instability in React and browser UIs. This skill operates in two modes depending on what is known at invocation time.78## Decision Tree910Determine the mode before doing any work:1112**Is there a specific visual complaint?** (The user describes something they can see: flicker, blink, flash, jump, stutter, pop-in, scroll reset, focus loss, "the whole pane feels rebuilt.")1314- **Yes** -- go to **Mode B: Runtime Investigation**15- **No** (general review, PR check, preventive sweep, or just a file/directory target) -- go to **Mode A: Static Analysis**1617If unsure, start with Mode A. Its findings often explain the complaint without runtime tooling.1819---2021## Mode A -- Static Analysis2223Use when: reviewing a PR, scanning changed files, doing a preventive sweep, or no specific symptom is reported.24251. Read [references/static-patterns.md](./references/static-patterns.md) for the full pattern catalog.262. Read [references/scan-process.md](./references/scan-process.md) for scope rules, severity rubric, output format, and guardrails.273. Identify scope: changed files in the current branch (`git diff --name-only` against base), or the user-specified target and its direct imports.284. Scan each React component against all patterns.295. Report findings grouped by component, ranked by severity.3031Stop here unless a finding warrants runtime confirmation or the user escalates.3233---3435## Mode B -- Runtime Investigation3637Use when: the user reports something visible -- flicker, blink, flash, jump, snap, stutter, pop-in, scroll reset, focus loss, or "the whole pane feels rebuilt."3839### Step 1 -- Classify the symptom4041| Bucket | Symptoms |42|---|---|43| `flash / blink` | subtree replaced, hidden, or briefly emptied |44| `jump / snap` | layout shifts, size changes, scroll resets |45| `sticky / stutter` | long tasks, frame gaps, render storms |46| `pop in` | post-paint correction from effects, fonts, images, async state |47| `whole pane rebuilt` | keyed remount or identity loss |4849Anchor each finding: **Which stable surface lost identity, visibility, position, or continuity during this interaction?**5051### Step 2 -- Pick the lightest investigation path5253- Reproducible, need first-pass evidence: [references/playwright-and-probe.md](./references/playwright-and-probe.md)54- Smells like remount or rerender churn: [references/react-path.md](./references/react-path.md)55- Smells like layout, paint, or compositor: [references/browser-path.md](./references/browser-path.md)56- Intermittent or prod-only: [references/field-path.md](./references/field-path.md)57- Need the tool decision matrix or budgets: [references/tooling-and-signals.md](./references/tooling-and-signals.md)5859Do not start with a heavyweight trace unless the lighter pass fails to explain the symptom.6061### Step 3 -- Escalate6263Each reference file contains its own escalation rules. Move to the next layer only when the current one is insufficient.6465### Done Criteria6667- You can state the likely cause AND either provide a code fix or identify what telemetry to add.68- Max escalation depth: 2 layers. If the second investigation path doesn't explain the symptom, report what you found and what remains unknown. Do not keep escalating.6970---7172## Hybrid: Static + Runtime7374When a runtime complaint maps to a static pattern (e.g., "it flashes on load" and you find effect-driven state initialization), run Mode A on the relevant files first. If the static finding explains the symptom, fix it without runtime tooling. If not, proceed to Mode B.7576---7778## Output7980**Mode A**: Findings grouped by component. Each finding includes pattern name, severity, what the user sees, code location, and a specific fix (not generic advice). End with a severity summary. Full format in [references/scan-process.md](./references/scan-process.md).8182**Mode B**: Report in this order:83841. **Interaction**: what was tested852. **Classification**: remount, layout, loading, post-paint, or paint/composite863. **Evidence**: concrete metrics, trace signals, or selector replacement findings874. **Likely cause**: highest-confidence explanation885. **Next action**: code fix, deeper trace, or telemetry8990If you create a reusable probe or report during the audit, keep it opt-in unless the repo already budgets against it.9192## Scope9394This skill covers the narrow band of issues that are **visual, temporal, and caused by React's render model or browser rendering** -- things that make a UI feel janky even when everything else is correct.9596It does NOT cover runtime performance (slow renders, memory leaks), accessibility, design quality, or error handling. Defer those to the appropriate specialized skill.
gbasin