Docs: stale library/metric references and several internal contradictions in reference/*.md

[phoboco]

Line numbers below are against main as of 2026-07-21 (plugin 3.9.1), all paths relative to .claude/skills/impeccable/. I originally hit these while auditing the 2.1.1 skills bundle, then re-verified every one against current main before filing, so the consolidated reference/*.md layout is what is cited.

Part 1: stale external references

1. FID was retired as a Core Web Vital in March 2024

• reference/optimize.md:199 heads the section ### First Input Delay (FID < 100ms) / INP (< 200ms), leading with the retired metric
• reference/optimize.md:8 and reference/optimize.md:229 both list LCP, FID/INP, CLS

INP replaced FID on 2024-03-12 and Chrome finished deprecating FID on 2024-09-09 (https://web.dev/blog/inp-cwv-launch). Suggest leading with INP and dropping FID, or keeping FID only as a parenthetical for historical context.

2. Framer Motion is now called Motion

• reference/animate.md:139 says Framer Motion for React
• reference/delight.md:266 says Framer Motion (React)

reference/overdrive.md:53 already has the correct form: motion (formerly Framer Motion). The motion and framer-motion npm packages are currently both at 12.42.2, so this is a naming inconsistency inside the skill rather than a version question.

3. react-virtualized is superseded

reference/optimize.md:109 recommends react-window, react-virtualized. react-virtualized has been superseded by react-window from the same author (react-window is at 2.3.0 and actively released; react-virtualized sits at 9.22.6). reference/overdrive.md:65 already points at TanStack Virtual, so the two files disagree on what to reach for.

4. Popmotion is no longer a live recommendation

reference/delight.md:277 lists Popmotion (animation primitives) under physics libraries. The standalone popmotion npm package last published 11.0.5 in August 2022 and the repo was last pushed in March 2024; its primitives now live inside Motion. Recommending Motion directly would be accurate. (Note: the GitHub repo is not formally archived, so "unmaintained and absorbed into Motion" is the precise description.)

5. WebGPU support matrix is out of date

reference/overdrive.md:60 says **WebGPU** (Chrome/Edge; Safari partial; Firefox: flag only). Per the WebGPU implementation status wiki (https://github.com/gpuweb/gpuweb/wiki/Implementation-Status), WebGPU now ships on by default in Firefox 141 on Windows and Firefox 147 on macOS, and in Safari 26 across macOS Tahoe, iOS, iPadOS and visionOS. Firefox on Linux and Android are still the flagged cases. The "always fall back to WebGL2" advice is still good, but the matrix reads as more restrictive than reality.

I deliberately did not flag the neighboring lines: reference/overdrive.md:56 (scroll-driven animations, Firefox: flag only) is still accurate, since layout.css.scroll-driven-animations.enabled remains flagged in Firefox stable as of 152.

Part 2: internal contradictions

These are cases where two files give directly opposing instructions, so the output depends on which command the user happens to run.

6. Mobile body text floor: 16px or 14px

• reference/typeset.md:116 lists Set body text below 16px under NEVER, and reference/typeset.md:296 says **Minimum 16px body text**: Smaller than this strains eyes and fails WCAG on mobile
• reference/harden.md:81 says Set minimum readable sizes (14px on mobile)
• reference/polish.md:159 says **Readable text**: No text smaller than 14px on mobile

So typeset forbids exactly what harden and polish permit, and polish will pass a design that typeset treats as a defect. There is a concrete correctness argument for 16px beyond readability: iOS Safari force-zooms the viewport when a focused input has a font-size under 16px, which breaks checkout and form layouts. Suggest aligning harden and polish to the 16px floor, with 14px allowed only for genuine secondary text.

7. audit reports missing will-change as a defect, three other files say do not do that

• reference/audit.md:28 lists missing will-change under Missing optimization
• reference/animate.md:157 says add it sparingly for known expensive animations only ... never preemptively across the whole page
• reference/optimize.md:114 says use it sparingly, and reference/optimize.md:242 lists Use will-change everywhere (creates new layers, uses memory) under NEVER

Running audit therefore generates findings that following optimize and animate would create. Since will-change is a targeted hint rather than a baseline requirement, suggest removing it from the audit checklist, or rewording to flag overuse instead of absence.

8. Humor in error messages: banned and shipped

• reference/clarify.md:158 lists Use humor for errors (be empathetic instead) under NEVER, and reference/clarify.md:234 states **Never use humor for errors.** Users are already frustrated. Be helpful, not cute.
• reference/delight.md:120 ships exactly that as a worked example: "This page is playing hide and seek. (And winning)" for a 404

Both positions are defensible, but not as absolutes in the same skill. A severity scale would resolve it cleanly: humor is fine on low-stakes errors (404, empty state, offline retry) and off-limits on anything involving money, bookings, or data loss. Right now delight and clarify will fight over the same string.

9. quieter speaks HSL while the rest of the skill mandates OKLCH

SKILL.md:71 says Use OKLCH. and SKILL.md:24 says Use OKLCH throughout, but reference/quieter.md:51 says **Reduce saturation**: Shift from fully saturated to 70-85% saturation. Saturation as a percentage is an HSL concept that OKLCH does not have; the OKLCH equivalent is reducing chroma while holding lightness. As written, quieter cannot be executed in the color space the rest of the skill requires without the model silently inventing a conversion. Suggest restating that bullet in lightness and chroma terms.

10. Minor: duration guidance reads as a conflict out of context

reference/animate.md:110 allows 500 to 800ms for entrance animations on page load, while reference/polish.md:113 says **Smooth transitions**: All state changes animated appropriately (150-300ms). These are reconcilable, since polish scopes itself to state changes, but polish is the pre-ship review pass and the word "All" reads as a global cap, which makes orchestrated entrances look like violations during review. A short scope note in polish pointing at the animate.md duration table would remove the ambiguity.

Also worth noting

Two reference links are broken in the 2.1.1 skills bundle that the plugin marketplace is still serving: layout/SKILL.md:50 points at reference/spatial-design.md and typeset/SKILL.md:50 points at reference/typography.md, but neither skill folder has a reference/ directory (the files live under impeccable/reference/, so the correct relative path is ../impeccable/reference/). The consolidated layout on main no longer has this problem, so this only matters if 2.x is still being distributed.