@raishin/vanguard-frontier-agentic 3.0.2 → 3.1.0

package/skills/frontend/critical-rendering-path-review/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: critical-rendering-path-review
+description: Review page-load resource sequencing, render-blocking CSS/JS, layout-shift sources, and Core Web Vitals (LCP/CLS/INP) budget adherence against the critical rendering path model, explicitly separating lab/synthetic measurement (Lighthouse) from field/real-user measurement (CrUX/RUM) so performance claims are evidence-graded rather than asserted from a single synthetic run.
+allowed-tools: Read Grep Glob Bash(git diff:*) WebFetch
+metadata:
+  author: "github: Raishin"
+  version: "0.1.0"
+  updated: "2026-07-02"
+  category: operational
+---
+
+# Critical Rendering Path Review
+
+## Purpose
+
+Performance regressions in the critical rendering path (render-blocking resources, layout-shift-inducing patterns, oversized LCP candidates) are cheap to introduce and expensive to diagnose after the fact, and lab data (a single Lighthouse run) frequently disagrees with field data (real users on real networks/devices) in ways that matter — a change that looks fine in a fast CI-runner Lighthouse run can regress Core Web Vitals for the actual user population. This skill reviews resource-loading order and layout-shift risk against the browser's actual parse/style/layout/paint pipeline, and enforces the lab-vs-field evidence distinction so performance verdicts aren't overclaimed.
+
+## When to use
+
+Use this skill when the user asks to:
+
+- review a diff for render-blocking CSS/JS, resource-loading order, or `<link>` resource-hint (preload/prefetch/preconnect) usage,
+- diagnose or prevent Cumulative Layout Shift (CLS) sources (unsized images/embeds, late-injected content above existing content, web-font swap),
+- assess Largest Contentful Paint (LCP) or Interaction to Next Paint (INP) budget adherence for a page or component,
+- reconcile conflicting lab (Lighthouse) vs. field (CrUX/RUM) performance data,
+- set or enforce a performance budget for a page/route.
+
+## Context7 Documentation Protocol
+
+Render-blocking semantics, `<link>` resource-hint behavior, and Core Web Vitals thresholds/definitions change as browser implementations and measurement methodology evolve (e.g. INP replaced FID as a Core Web Vital in May 2024) — never assert them from memory.
+
+1. Call `ToolSearch` with query `"context7"` (or `"select:mcp__Context7__resolve-library-id,mcp__Context7__query-docs"`) to load the Context7 tools if they are not already loaded in this session.
+2. Call `mcp__Context7__resolve-library-id` for the relevant documentation set — for this skill that is almost always MDN (`/mdn/content`, or `/websites/developer_mozilla_en-us` if the former lacks coverage for the query).
+3. Call `mcp__Context7__query-docs` for the specific mechanism in question — e.g. "render-blocking `<link>` and `<script>` behavior", "`rel=preload` `as` and `crossorigin` requirements", "LargestContentfulPaint / layout-shift performance entry semantics" — before ruling on it. Do this per review, not once from memory of a prior session.
+4. web.dev is the primary source for Core Web Vitals *thresholds* (good/needs-improvement/poor cutoffs) and is not currently indexed in Context7; treat threshold numbers pulled from `official_docs`/`WebFetch` as `documentation-based` rather than `Context7-verified`, and say so explicitly. Use Context7/MDN to verify the underlying *mechanism* (what LCP/CLS/INP actually measure, what a `PerformanceObserver` reports) wherever possible.
+5. Prefer the official spec/MDN wording over this skill's own paraphrase when the two could be read to disagree; cite the resolved doc URL in the finding.
+6. If Context7 is unavailable or returns no relevant match, fall back to the URLs in `official_docs` / `references/*.md`, and explicitly mark the claim `documentation-based (Context7 unavailable)` rather than presenting it as freshly verified.
+7. Never invent a `<link>` attribute, performance-entry field, or Core Web Vitals threshold that no queried source confirms.
+
+## Lean operating rules
+
+- Always separate lab data (synthetic, single-run, deterministic-ish, from Lighthouse/CI) from field data (real-user, aggregated, from CrUX or RUM tooling) explicitly in every finding — never present a Lighthouse score as if it were a field-validated user-experience claim.
+- Trace resource-loading order against the actual critical rendering path (HTML parse → DOM/CSSOM construction → render tree → layout → paint → composite) rather than asserting 'this is render-blocking' without identifying which pipeline stage it blocks.
+- Every image, video, or embed must have explicit width/height or `aspect-ratio` reserved space to prevent CLS; flag any that don't.
+- Flag web-font loading without a `font-display` strategy or preload for the LCP-critical font, since font-swap/flash is a common unaddressed CLS and LCP-delay source.
+- Query current web.dev/MDN Core Web Vitals thresholds before asserting a pass/fail budget verdict — LCP/CLS/INP thresholds and measurement methodology have changed (INP replaced FID as a Core Web Vital in May 2024); never assert current thresholds from memory.
+- Do not recommend `preload`/`prefetch`/`preconnect` for third-party origins without weighing the connection-establishment cost against the information-leakage/timing tradeoff.
+- Treat a single synthetic Lighthouse run as insufficient evidence for a production performance claim; flag the need for field data (CrUX/RUM) before asserting a real-user-experience verdict.
+- Never suggest dropping Subresource Integrity (SRI) or bypassing CSP `script-src` allow-listing as a performance optimization.
+
+## References
+
+Load these only when needed:
+
+- [Resource-loading order and render-blocking audit](references/resource-loading-order.md) — use when tracing which resources block first paint/LCP and how to reorder or hint them (preload/defer/async/module).
+- [Layout-shift source catalog](references/layout-shift-sources.md) — use when auditing a page/component for CLS sources beyond unsized media (late web-font swap, injected banners/ads, animation-triggered reflow).
+- [Lab vs. field evidence reconciliation](references/lab-vs-field-evidence.md) — use when Lighthouse (lab) and CrUX/RUM (field) data disagree, or when a performance claim needs to be evidence-graded for a stakeholder deliverable.
+
+## Response minimum
+
+Return, at minimum:
+
+- the critical-rendering-path stage(s) affected by the change in scope (parse/style/layout/paint/composite),
+- the render-blocking resource audit for any new/modified `<link>`, `<script>`, or `@import`,
+- the CLS-source audit (unsized media, font-swap, late-injected content) for the page/component in scope,
+- the LCP/CLS/INP budget verdict, explicitly labeled as lab evidence, field evidence, or inference,
+- residual risk notes for anything requiring live Lighthouse/CrUX/RUM data beyond this static review.

package/skills/frontend/critical-rendering-path-review/metadata.json

@@ -0,0 +1,31 @@
+{
+  "id": "critical-rendering-path-review",
+  "name": "Critical Rendering Path Review",
+  "type": "skill",
+  "provider": "frontend",
+  "harnesses": [
+    "codex",
+    "claude-code",
+    "cursor",
+    "gemini",
+    "kiro",
+    "other"
+  ],
+  "summary": "Reviews page load sequencing — resource loading order, render-blocking CSS/JS, layout-shift risk, and Core Web Vitals budget adherence — separating lab (Lighthouse/synthetic) data from field (CrUX/RUM) data so performance claims are evidence-graded rather than asserted.",
+  "source_type": "original",
+  "official_docs": [
+    "https://web.dev/articles/critical-rendering-path",
+    "https://web.dev/articles/optimize-lcp",
+    "https://web.dev/articles/cls",
+    "https://web.dev/articles/inp",
+    "https://web.dev/vitals",
+    "https://developer.mozilla.org/en-US/docs/Web/Performance/Guides/Critical_rendering_path",
+    "https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/link",
+    "https://developer.chrome.com/docs/lighthouse/overview"
+  ],
+  "security_notes": "Flag preload/prefetch/preconnect resource hints pointed at third-party origins without considering the information-leakage/timing implications of establishing early connections to those origins. Flag any performance 'optimization' that removes Subresource Integrity (SRI) from a script/style tag to save a round trip — integrity checks are not a discretionary performance cost. Do not recommend inlining third-party scripts to avoid a network request in a way that bypasses CSP script-src allow-listing.",
+  "last_verified": "2026-07-02",
+  "path": "skills/frontend/critical-rendering-path-review",
+  "author": "github: Raishin",
+  "version": "0.1.0"
+}

package/skills/frontend/critical-rendering-path-review/references/lab-vs-field-evidence.md

@@ -0,0 +1,60 @@
+# Lab vs. Field Evidence Reconciliation
+
+> Core Web Vitals thresholds (the good/needs-improvement/poor cutoffs for LCP/CLS/INP) live in web.dev, which is not currently indexed in Context7. Treat specific threshold numbers as `documentation-based` and re-verify against `https://web.dev/vitals` and the metric-specific web.dev articles before asserting a pass/fail budget verdict — do not assert them from memory or from this file, which does not restate them for that reason.
+
+## What people get wrong
+
+The naive story is:
+
+> "I ran Lighthouse, the score is green, performance is fine."
+
+Wrong, and it is wrong in a specific, well-documented way: Lighthouse is a **lab** tool — a single synthetic run, on a simulated or fixed device/network profile, usually with a cold cache, on whatever machine ran it (a fast CI runner or an engineer's laptop are both faster and more consistent than most real user devices/networks). It cannot see what real users on real hardware and real networks actually experience. A change can score green in a CI Lighthouse run and simultaneously regress Core Web Vitals in the Chrome UX Report (CrUX) for the real user population, and the reverse is equally possible — a lab regression that never shows up in field data because it falls below the threshold real users' devices are sensitive to.
+
+## Officially grounded distinction
+
+- **Lab data** (Lighthouse, WebPageTest, a local Chrome DevTools trace): synthetic, reproducible, deterministic-ish (modulo system noise), useful for **diagnosing** *why* something is slow because it gives you a full trace/waterfall — but it reflects one simulated environment, not your actual user population's device mix, network conditions, cache state, or extensions/interference.
+- **Field data** (Chrome UX Report / CrUX, or a first-party Real User Monitoring / RUM setup using the `web-vitals` JS library or the underlying Performance APIs directly): aggregated measurements from real page loads by real users, on their actual devices and networks — this is what Core Web Vitals thresholds are actually evaluated against for things like Google Search's page-experience signal, and it is the only data source that can tell you what users actually experienced.
+
+Neither one is a substitute for the other:
+
+- Lab data without field data → you don't know if your synthetic environment represents your real users at all (e.g. testing on fast fiber when 40% of your traffic is mobile on 4G).
+- Field data without lab data → you know something regressed, but you have no trace/waterfall to diagnose *why*, and CrUX is aggregated over a rolling 28-day window, so it lags a deploy by design and can't attribute a regression to a specific commit.
+
+## Non-negotiable review rules
+
+### 1. Never present a Lighthouse score as a user-experience claim
+
+A sentence like "LCP is 1.8s, this is fast for users" is not supportable from a Lighthouse run alone — the correct claim is "LCP is 1.8s in this lab run under [specified throttling profile]; field verification via CrUX/RUM is needed to confirm real-user experience." Say which one you have.
+
+### 2. Label every performance number by its evidence source
+
+Use one of: `lab (Lighthouse/CI)`, `lab (local DevTools trace)`, `field (CrUX)`, `field (RUM)`, `inference (not measured, reasoned from code review)`. Do not present an inferred estimate ("this should improve LCP by roughly X") as if it were measured.
+
+### 3. CrUX has structural limitations — know them before citing it
+
+CrUX data: is a rolling aggregate (commonly a 28-day window) so it cannot attribute a regression to a specific deploy without waiting; only reports origins/URLs with sufficient real-world traffic (low-traffic pages may have no CrUX data at all); reports field percentiles (commonly the 75th percentile) rather than a single number, so "the field LCP" is actually a distribution, not a point value — always specify which percentile a cited number represents. Flag a claim that treats CrUX as instantly reflecting today's deploy, or as covering a low-traffic page it may not have data for.
+
+### 4. A single Lighthouse run is not enough even as lab evidence
+
+Lab measurement variance (system load, thermal throttling, background processes) means a single run of Lighthouse is not reliable evidence on its own — multiple runs (or a controlled tool that already runs multiple iterations and reports median/percentile) are needed before treating a lab number as stable evidence, not just a single sample.
+
+### 5. Reconciling disagreement between lab and field
+
+When lab says "fine" and field says "regressed" (or vice versa), the disagreement itself is the finding — investigate rather than picking whichever number supports the desired conclusion. Common causes: the lab throttling profile doesn't represent the real device/network mix (e.g. desktop-only lab testing for a mostly-mobile audience); the lab run has a warm cache the CI step didn't clear, but real first-time visitors don't; the regression is specific to a code path/interaction that the lab script's test URL/flow doesn't exercise (e.g. INP on a specific interactive element the Lighthouse run never clicks, since Lighthouse's synthetic run cannot fully simulate INP the way field RUM data — which requires observed real interactions — can).
+
+## Minimal safe review flow
+
+1. Identify what evidence is actually available for the claim being reviewed (lab-only, field-only, both, or neither/inference).
+2. If only lab data exists for a production-impacting claim, state that field verification is outstanding as a residual risk rather than asserting a final verdict.
+3. If lab and field data disagree, investigate the throttling-profile/cache-state/traffic-mix explanations above before concluding either number is "wrong."
+4. Cite the specific percentile (e.g. p75) and time window for any field number, and the specific throttling/device profile for any lab number.
+5. Re-verify current LCP/CLS/INP threshold cutoffs against `https://web.dev/vitals` before stating a pass/fail budget verdict — do not reuse a remembered threshold from a prior review.
+
+## When to push back
+
+Push back if the user says:
+
+- "the Lighthouse score is green, ship it" — for anything with real production traffic, ask whether field data (CrUX or RUM) exists or is planned to confirm it,
+- "CrUX shows we're fine" for a page/route that just shipped a change days ago — CrUX's rolling window means it may not yet reflect that change,
+- "just average the field numbers" — Core Web Vitals are evaluated at specific percentiles (commonly p75), not the mean; averaging hides the tail experience that the metric is specifically designed to surface,
+- "we don't need RUM, Lighthouse in CI is enough" for a production application with a real, diverse user base — lab-only measurement cannot see device/network heterogeneity that field data is specifically designed to capture.

package/skills/frontend/critical-rendering-path-review/references/layout-shift-sources.md

@@ -0,0 +1,68 @@
+# Layout-Shift Source Catalog
+
+> Verify `LayoutShift`/`LayoutShiftAttribution` performance-entry semantics against current MDN docs via Context7 before citing exact scoring behavior — the CLS scoring window/session-gap algorithm has changed since CLS's introduction. Treat any specific numeric session-window value as `documentation-based` and re-verify rather than asserted from memory.
+
+## What people get wrong
+
+The common bad assumption is:
+
+> "CLS is about images without `width`/`height` — I checked, they're all fine."
+
+Incomplete. Unsized media is the textbook example, but it is one of at least five distinct source categories, and a page can pass a naive "all images have dimensions" check while still shipping a significant CLS regression.
+
+## Officially grounded definition
+
+Per MDN's CLS glossary entry and the Layout Instability API (`LayoutShift`/`LayoutShiftAttribution`), a layout shift is scored when a visible element's start position changes between two rendered frames, without that change being the direct result of a user interaction. `LayoutShiftAttribution` reports the specific DOM node(s) responsible along with `previousRect`/`currentRect`, which is the ground-truth way to attribute a shift to a specific element rather than guessing from a diff.
+
+## Source categories to audit
+
+### 1. Unsized media (the well-known one)
+
+Any `<img>`, `<video>`, `<iframe>`, or `<embed>` without explicit `width`/`height` attributes (or a CSS `aspect-ratio`/explicit sized container) reserves no space before the resource loads, so its arrival pushes surrounding content. This applies equally to background images used as layout-affecting content and to responsive images (`srcset`) — the reserved box must match the *intrinsic* aspect ratio, not just have some placeholder height that doesn't match the eventual rendered size.
+
+### 2. Web-font swap (FOIT/FOUT)
+
+A font that loads after initial text paint and has different metrics (x-height, glyph width) than the fallback font shifts every line it affects when it swaps in. This is invisible to an "images have dimensions" check entirely. Mitigations to look for:
+
+- `font-display: swap` (or `optional`) on `@font-face`, chosen deliberately rather than defaulted to `auto`/`block`.
+- A `<link rel="preload" as="font" crossorigin>` for the LCP-critical font so it's fetched earlier and the swap window is shorter.
+- Font-metric-matching fallback stacks (e.g. via `size-adjust`/`ascent-override`/`descent-override` in a matching `@font-face` fallback declaration, or a generated fallback via a tool that computes these) to minimize the visual delta when the swap happens, when the swap itself can't be eliminated.
+
+Flag any new `@font-face` with neither a `font-display` strategy nor a metric-matched fallback as an unaddressed CLS/LCP risk.
+
+### 3. Content injected above existing content
+
+Any DOM insertion above the current viewport's visible content — a banner, cookie-consent bar, ad slot, or async-loaded promo — that doesn't have space reserved for it shifts everything below. This is a frequent CLS source that has nothing to do with media sizing at all. Audit: does the container reserve a fixed or `min-height` slot before the async content resolves, or does content just get prepended/inserted into flow?
+
+### 4. Animations that trigger layout instead of compositing
+
+CSS animations/transitions on `top`/`left`/`width`/`height`/`margin` (layout-triggering properties) rather than `transform`/`opacity` (compositor-only properties) can register as layout shifts if they affect other elements' positions, and are also a distinct main-thread-cost problem independent of CLS. Flag any newly added animation on a layout-affecting property and ask whether a `transform`-based equivalent achieves the same visual effect.
+
+### 5. FOUC/late-applied CSS affecting already-painted content
+
+If content paints before a stylesheet (or a `<style>` block inserted by JS) fully applies, and the styles change box dimensions, that is a layout-shift source distinct from font swap — e.g. a CSS-in-JS solution that injects styles after first paint, or a critical-CSS strategy that inlines an incomplete subset and loads the rest async without accounting for elements that need the deferred rules for correct sizing.
+
+## Non-negotiable review rules
+
+- Do not accept "images have width/height" as a complete CLS review — walk all five categories above.
+- Any element inserted above existing viewport content without a reserved slot is a blocking finding, not a nice-to-have fix, if it's likely to occur after first paint (ads, consent banners, personalization banners, notification bars).
+- New `@font-face` rules must specify a deliberate `font-display` value; flag `auto`/default (browser-dependent, commonly behaves like `block`) as unreviewed.
+- New layout-triggering animations (`top`/`left`/`width`/`height`/`margin` in `@keyframes` or `transition`) should be flagged with a suggested `transform`/`opacity` alternative when the visual intent allows it.
+- Distinguish shifts caused by user interaction (which are explicitly excluded from CLS scoring, e.g. an accordion the user clicked to expand) from unexpected shifts — don't flag legitimate, user-triggered layout changes as CLS problems.
+
+## Minimal safe review flow
+
+1. Identify every element that renders asynchronously or after a network/font/JS dependency resolves (images, fonts, injected banners, lazy content, animated elements).
+2. For each, check whether visual space is reserved before it resolves (`width`/`height`, `aspect-ratio`, `min-height` container, skeleton placeholder).
+3. For fonts specifically, confirm a `font-display` strategy and, for LCP-critical fonts, a preload.
+4. For animations, confirm they animate compositor-only properties where visually equivalent.
+5. State whether the verdict is markup/CSS-inferred (`inference`) or confirmed via a live `LayoutShift`/`LayoutShiftAttribution` observer trace (`live evidence`) — attribution data is the only way to confirm which specific element actually caused a measured shift versus which one merely looks suspicious in markup.
+
+## When to push back
+
+Push back if the user says:
+
+- "it's just one image, CLS won't notice" — a single large above-the-fold image is often the single biggest CLS contributor on a page,
+- "we'll add the font-display later" — that is deferring a known, cheap-to-fix CLS/LCP source indefinitely,
+- "the banner only shows sometimes, so it doesn't count" — intermittent injection is still a real-user-experience regression for the users who see it, and CrUX aggregates across all real loads including that one,
+- "let's just wrap it in `overflow: hidden` so the shift isn't visible" — that hides the symptom from a visual check without preventing the actual layout recalculation, and does not necessarily improve the measured CLS score.

package/skills/frontend/critical-rendering-path-review/references/resource-loading-order.md

@@ -0,0 +1,79 @@
+# Resource-Loading Order and Render-Blocking Audit
+
+> Verify exact `<link>`/`<script>` attribute behavior against current MDN docs via Context7 before ruling — browser render-blocking rules and resource-hint attributes are implementation-defined and have changed (e.g. `blocking="render"`, `fetchpriority`). Do not assert them from memory.
+
+## What people get wrong
+
+The naive story is:
+
+> "Put scripts at the bottom of `<body>` and it's fixed."
+
+Incomplete. That mitigates one failure mode (parser-blocking synchronous `<script>` in `<head>`) but says nothing about CSS blocking, resource priority, third-party origin cost, or whether the thing you deferred was actually needed for first paint.
+
+## Officially grounded pipeline
+
+Per MDN's critical rendering path reference: the browser builds the DOM as HTML is parsed, builds the CSSOM from requested/inline styles, combines DOM + CSSOM into the render tree, computes layout, then paints and composites pixels. Two consequences follow directly from that pipeline:
+
+- **CSS is render-blocking by default.** The browser withholds first paint until it has the CSSOM, specifically to avoid a flash of unstyled content. A `<link rel="stylesheet">` in `<head>` blocks rendering unless explicitly marked otherwise (e.g. via a non-render-blocking media query that doesn't match the current viewport, or `blocking` control on supporting elements).
+- **A synchronous `<script>` (no `async`/`defer`/`type="module"`) blocks HTML parsing at the point it appears,** because the parser must assume the script could call `document.write` or otherwise mutate the DOM before parsing continues. It does not block CSSOM construction, but it can be blocked *by* an earlier stylesheet (browsers commonly delay script execution until preceding CSS has loaded, since the script might query computed style).
+
+So "render-blocking" is not one failure mode — audit each resource against which stage it blocks:
+
+| Resource | Blocks HTML parse? | Blocks first paint? |
+|---|---|---|
+| `<link rel="stylesheet">` (no disabling media) | No | Yes |
+| `<script src="...">` (no async/defer/module) | Yes, at that point | Indirectly (delays DOM/paint readiness) |
+| `<script defer>` | No | No (executes after parse, before `DOMContentLoaded`) |
+| `<script async>` | No | No, but executes whenever it finishes downloading — order not guaranteed relative to other scripts |
+| `<script type="module">` | No (deferred by default) | No |
+| `@import` inside CSS | N/A | Yes, and serializes — it blocks until fetched, adding a network round trip the browser couldn't discover from the HTML in parallel |
+
+Live evidence for a given page: `PerformanceObserver({type: "resource", buffered: true})` and check `entry.renderBlockingStatus === "blocking"` (per `PerformanceResourceTiming.renderBlockingStatus`), or `performance.getEntriesByType("resource")` filtered the same way. This is the only way to get a ground-truth render-blocking verdict for a *live* page rather than an inferred one from reading markup.
+
+## Non-negotiable review rules
+
+### 1. Classify every new/modified `<link>` and `<script>` by blocking behavior, not by intent
+
+Do not accept "it's deferred" as true because the author says so — check the actual attribute (`defer`, `async`, `type="module"`, `blocking`) and its placement.
+
+### 2. `@import` in CSS is a hidden render-blocking network round trip
+
+Flag any new `@import` in a stylesheet that's itself render-blocking. The browser cannot discover and start fetching an `@import`-ed stylesheet until it has already parsed the CSS that contains it — it cannot be discovered by the HTML preload scanner the way a `<link>` can. Prefer a second `<link rel="stylesheet">` in the HTML.
+
+### 3. Resource hints are not interchangeable
+
+Per MDN's `<link>` reference and the `dns-prefetch`/`preconnect`/`preload` guides:
+
+- `dns-prefetch` — resolve DNS only. Cheapest hint; useful for many possible-but-uncertain origins.
+- `preconnect` — DNS + TCP + TLS handshake. More expensive per origin; browsers cap how many they'll act on, so do not `preconnect` to more than a handful of origins.
+- `preload` — fetch a *specific, known-needed* resource at high priority, before the parser would otherwise discover it. Requires the correct `as` value (`script`, `style`, `font`, `image`, etc.) or the browser may apply the wrong priority/type-check and silently double-fetch. Cross-origin font preloads require `crossorigin` even for same-site font hosting, because fonts are fetched in "anonymous" CORS mode regardless of same-origin-ness.
+- `modulepreload` — the module-script-specific equivalent of `preload`, which also allows the browser to parse and cache the module graph ahead of execution.
+- `prefetch` — low-priority fetch for a resource likely needed for a *future* navigation, not the current render. Do not use it for anything on the current page's critical path — it competes for bandwidth at low priority and is the wrong tool if the goal is to affect *this* page's LCP.
+
+A `preload` misused for a resource that turns out unused within a few seconds of load produces a Chrome DevTools/Lighthouse warning and wastes bandwidth — flag speculative preloads with no confirmed use.
+
+### 4. Third-party resource hints have a cost, not just a benefit
+
+`preconnect`/`dns-prefetch` to a third-party origin (analytics, font CDN, ad tech, social widget) opens a connection or resolves DNS to that origin earlier than the page would otherwise need to — which also means that origin observes the visit earlier and independent of whether the resource is ever actually used. Weigh this against the latency win; do not recommend blanket `preconnect` to every third-party origin referenced anywhere on the page.
+
+### 5. LCP-candidate resource should be the highest-priority fetch on the page
+
+If the LCP element is a background `<img>`, hero image, or web font, confirm it is discoverable by the HTML preload scanner (i.e. present as a real `<img src>`/`<link>` in markup, not injected by a blocking JS bundle) and, where warranted, has an explicit `fetchpriority="high"` or `<link rel="preload">`. An LCP image that only becomes discoverable after a render-blocking JS bundle executes is a common, easily fixed regression.
+
+## Minimal safe review flow
+
+1. List every `<link>`, `<script>`, and `@import` added or modified in the diff.
+2. Classify each by blocking behavior per the table above (parse-blocking / paint-blocking / neither).
+3. For each resource hint (`preload`/`prefetch`/`preconnect`/`dns-prefetch`/`modulepreload`), confirm it targets a resource actually needed for *this* page's first render, has correct `as`/`type`/`crossorigin`, and isn't redundant with browser-default discovery.
+4. Identify the LCP candidate and confirm it is discoverable without executing render-blocking JS first.
+5. Flag any `@import`, unbounded `preconnect` list, or speculative preload as findings, not silent passes.
+6. State whether the verdict is markup-inferred (`inference`) or confirmed via a live `PerformanceObserver`/DevTools trace (`live evidence`).
+
+## When to push back
+
+Push back if the user asks for:
+
+- `preconnect` to every third-party domain referenced anywhere in the codebase "just in case,"
+- moving all `<script>` tags to `async` without checking execution-order dependencies between them,
+- a blanket `preload` for every image on the page instead of just the LCP candidate,
+- removing a render-blocking stylesheet without confirming what visual state exists before it loads (flash of unstyled content is a real regression, not just a metric).

package/skills/frontend/css-architecture-design-system-review/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: css-architecture-design-system-review
+description: Review CSS for specificity and cascade-layer discipline, design-token (custom-property) conformance, and responsive strategy correctness (container queries vs. media queries), catching specificity wars, hardcoded-value token drift, and non-reflowing layouts that fail WCAG 1.4.10/1.4.4 before they compound into unmaintainable stylesheets.
+allowed-tools: Read Grep Glob Bash(git diff:*) WebFetch
+metadata:
+  author: "github: Raishin"
+  version: "0.1.0"
+  updated: "2026-07-02"
+  category: architecture
+---
+
+# CSS Architecture & Design System Review
+
+## Purpose
+
+CSS at scale degrades through two silent mechanisms: specificity creep (engineers reaching for `!important` or ID selectors to win cascade fights instead of fixing the underlying layer structure) and design-token drift (hardcoded values reappearing next to a token system, diverging visual output over time). Neither shows up as a compile error or a failing test — they show up eighteen months later as an unmaintainable stylesheet nobody wants to touch. This skill catches both at review time, plus the responsive-strategy and WCAG visual-presentation failures that are CSS's specific accessibility responsibility.
+
+## When to use
+
+Use this skill when the user asks to:
+
+- review a CSS/component-styling diff for specificity, cascade, or maintainability issues,
+- audit a codebase's design-token (CSS custom-property) conformance,
+- decide between container queries and media queries for a responsive pattern,
+- establish or enforce a cascade-layer strategy (`@layer reset, base, tokens, components, utilities, overrides`),
+- check layout resilience against WCAG 2.2 reflow (1.4.10) and resize-text (1.4.4) criteria.
+
+Do not use this skill for:
+
+- JavaScript/framework component architecture — use the matching framework-specific review skill instead,
+- live visual-regression testing or contrast-ratio measurement — that requires a runtime tool, not static review,
+- choosing a CSS methodology from scratch with no existing code — that is a greenfield design conversation, not a review.
+
+## Context7 Documentation Protocol
+
+- Resolve the MDN Web Docs library ID with `resolve-library-id` (matched result: `/mdn/content`) before citing any cascade-layer, container-query, or custom-property specificity claim.
+- Before asserting cascade-layer precedence, `!important` interaction, or container-query browser-support behavior, call `query-docs` against `/mdn/content` and cite the section — do not assert from memory. Cascade-layer `!important` precedence is inverted relative to normal-declaration precedence and is easy to misstate without checking.
+- If Context7 is unavailable, fall back to the `official_docs` URLs in this skill's `metadata.json` and label the claim `documentation-based, unverified against current release`.
+- Never assume a browser-support baseline (e.g., "container queries are safe everywhere now") without checking current docs; treat support claims as version/date-sensitive, not fixed facts.
+
+## Lean operating rules
+
+- Never approve new `!important` without a documented cascade-layer justification — it is a symptom that the layer/selector structure should be fixed, not a valid quick fix. Note: `!important` precedence is inverted across layers (earlier-declared layers win for important declarations), so verify actual winning behavior against the declared `@layer` order rather than assuming a simple override.
+- Never approve new ID-selector styling for components; treat it as a specificity-escalation risk that will require `!important` or worse to override later.
+- In any codebase with an established design-token system, flag hardcoded color/spacing/typography values and name the nearest token substitute — do not silently allow token drift. Distinguish token tiers (primitive → semantic → component) when recommending a substitute; do not point a component-level override at a raw primitive if a semantic token exists.
+- Do not bikeshed methodology (BEM vs. utility-first vs. CSS Modules vs. cascade layers) when a convention is already established; enforce consistency with what exists over personal preference.
+- Query current MDN/W3C docs for `@layer`/`@container` support and semantics before ruling — container queries only reached broad Baseline status in 2023 and cascade-layer support nuances (especially `!important` interaction) vary; never assert current support from memory.
+- Distinguish container queries (component depends on its container's size) from media queries (component depends on the viewport) — recommending the wrong one for the actual dependency is a correctness bug, not a style preference. A component intended for reuse across differently-sized containers (sidebar, main content, modal) needs a container query; a page-level layout shift needs a media query.
+- Never treat CSS as an access-control boundary; `display:none`/`visibility:hidden` hiding an affordance is not a substitute for server-side authorization. Flag this as a HIGH-severity finding, not a style note, whenever hidden-but-present markup carries privileged data or actions.
+- Flag anything needing live visual-regression or contrast-ratio measurement as a residual risk requiring live-runtime verification, not asserted from static analysis alone.
+- Flag attribute-selector-plus-background-image patterns (e.g. `input[value^="a"] { background: url(...) }`) as a potential CSS-based data-exfiltration vector — they can leak user-controlled attribute values via network requests.
+- Flag third-party `@import` rules with no accompanying Subresource Integrity or CSP `style-src` consideration as a supply-chain risk, not a performance nitpick.
+- Never execute, build, or run application code, and never fetch live pages to "see how it renders" without the user's explicit ask; this is a static-review skill augmented only by documentation lookups (Read/Grep/Glob plus scoped `git diff` and `WebFetch` for docs/spec grounding).
+
+## References
+
+Load these only when needed:
+
+- [Cascade layer strategy](references/cascade-layer-strategy.md) — use when establishing or auditing a `@layer` order for a codebase, or resolving a specificity conflict between two legitimate rules.
+- [Design token conformance patterns](references/token-conformance.md) — use when auditing hardcoded-value drift against an existing custom-property token system, including token-tier (primitive vs. semantic vs. component) conventions.
+- [Responsive strategy decision guide](references/responsive-strategy.md) — use when deciding container query vs. media query, or auditing reflow/resize-text compliance at 400%/200% zoom.
+
+## Response minimum
+
+Return, at minimum:
+
+- the specificity/cascade verdict per flagged selector, with its computed specificity value when relevant,
+- a token-conformance report distinguishing token-referenced values from hardcoded ones,
+- the responsive-strategy verdict (container query vs. media query appropriateness) for any new responsive rule,
+- the recommended cascade-layer placement for new rules,
+- residual risk notes for anything requiring live visual-regression or contrast-checker verification beyond this static review.

package/skills/frontend/css-architecture-design-system-review/metadata.json

@@ -0,0 +1,30 @@
+{
+  "id": "css-architecture-design-system-review",
+  "name": "CSS Architecture & Design System Review",
+  "type": "skill",
+  "provider": "frontend",
+  "harnesses": [
+    "claude-code",
+    "cursor",
+    "codex",
+    "gemini",
+    "kiro",
+    "other"
+  ],
+  "summary": "Reviews CSS for specificity/cascade-layer discipline, design-token conformance, and responsive strategy (container queries vs. media queries), catching specificity wars, token drift, and non-reflowing layouts before they compound into unmaintainable stylesheets.",
+  "source_type": "original",
+  "official_docs": [
+    "https://developer.mozilla.org/en-US/docs/Web/CSS",
+    "https://www.w3.org/TR/css-cascade-5/",
+    "https://www.w3.org/TR/css-variables-1/",
+    "https://www.w3.org/TR/css-contain-3/",
+    "https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_cascade/Cascade_layers",
+    "https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_containment/Container_queries",
+    "https://www.w3.org/TR/WCAG22/#visual-presentation"
+  ],
+  "security_notes": "Do not treat CSS visibility/display properties as an access-control mechanism — hiding an element with CSS never substitutes for server-side authorization; flag any pattern that relies on it as a security control. Flag attribute-selector-plus-background-image patterns that could exfiltrate user-controlled attribute values via network requests (CSS-based data-exfiltration vector). Flag third-party @import without SRI/CSP style-src consideration.",
+  "last_verified": "2026-07-02",
+  "path": "skills/frontend/css-architecture-design-system-review",
+  "author": "github: Raishin",
+  "version": "0.1.0"
+}

package/skills/frontend/css-architecture-design-system-review/references/cascade-layer-strategy.md

@@ -0,0 +1,64 @@
+# Cascade layer strategy
+
+Use this reference when establishing or auditing a `@layer` order for a codebase, or resolving a specificity conflict between two legitimate rules.
+
+## What people get wrong
+
+The naive story is:
+
+> Cascade layers are just a naming convention — put rules in a `@layer` block and specificity stops mattering.
+
+Half right, and the half that's wrong is dangerous. Layers change *which layer wins*, but specificity still decides the winner *within* a layer, and — critically — the precedence order **inverts** for `!important` declarations. Per MDN's cascade-layers guidance: earlier-declared layers win over later-declared layers for normal declarations, but for `!important` declarations, earlier-declared layers win over later ones too — meaning an `!important` in an early "reset" layer can beat an `!important` in a later "overrides" layer, which is the opposite of what most engineers assume ("overrides should always win"). Unlayered styles sit in an implicit final layer for normal declarations, but unlayered `!important` styles have *lower* precedence than any layered `!important` declaration. Get this backwards and you'll "fix" a cascade bug by adding `!important` to the wrong layer and watch it silently lose anyway.
+
+## Officially grounded shape (MDN / W3C Cascade 5)
+
+- `@layer name1, name2, name3;` declares layer order upfront, independent of where each layer's rules are later defined in the file.
+- Layer order determines precedence **regardless of selector specificity** for normal (non-important) declarations — a low-specificity selector in a later layer beats a high-specificity selector in an earlier layer.
+- Unlayered styles form an implicit layer that comes **last** (highest precedence) for normal declarations.
+- For `!important` declarations, the precedence order is **inverted**: earlier-declared layers' important styles win over later layers' important styles, and layered important styles always beat unlayered important styles.
+- Inline `style=""` importance still beats all author-layer `!important` declarations, regardless of layer order.
+- `@import url(...) layer(name);` can assign an entire imported stylesheet to a layer, which is useful for third-party CSS you don't control (framework resets, component libraries) — put it in an early layer so your own rules can override it without `!important`.
+
+## Non-negotiable design rules
+
+### 1. Declare the full layer order in one place, upfront
+
+Do not let layer order emerge implicitly from file-load order. A single `@layer reset, base, tokens, components, utilities, overrides;` statement (naming may vary per codebase convention) at the top of the entry stylesheet is the source of truth. If layer order is scattered or redeclared inconsistently across files, the *effective* order becomes whatever browser resolves first-seen — audit for this as a HIGH-severity finding.
+
+### 2. `!important` inside a layer is not a free pass — verify the inversion
+
+Before approving `!important` anywhere, confirm which layer it lives in and whether the intended "win" actually happens under the inverted precedence rule. An `!important` added to `overrides` (a late layer) to "make sure it wins" will **lose** to an `!important` already present in an earlier layer like `reset`. This is the single most common cascade-layer mistake — check it explicitly, don't assume.
+
+### 3. Third-party/vendor CSS goes in the earliest layer
+
+Wrap vendor resets, component-library base styles, or any CSS the team doesn't control in its own early layer (or `@import ... layer(vendor);`). This guarantees your own component/utility layers can override it with normal specificity, with no `!important` needed at all — that's the actual payoff of adopting layers.
+
+### 4. Utilities still need to out-rank components, by layer not specificity
+
+If the codebase uses utility classes (e.g. Tailwind-style) alongside component styles, utilities must live in a layer declared *after* the components layer. Do not rely on utility classes having higher specificity than component selectors — that's fragile and exactly the pattern layers exist to replace.
+
+### 5. New ID-selector or `!important` usage outside an established layer is a regression, not a quick fix
+
+Once a codebase has adopted cascade layers, any new unlayered `!important` or ID-selector styling should be treated as bypassing the system the team already invested in. Flag it and point to the correct layer.
+
+## Specificity primer (for the parts layers don't cover)
+
+Within a single layer (or in a codebase with no layers), specificity still resolves conflicts using the standard weight: inline style > ID selectors > class/attribute/pseudo-class selectors > type/pseudo-element selectors, with `!important` overriding all of the above except a later `!important` of equal-or-higher-weight origin. Report specificity as a 4-part tuple (inline, IDs, classes/attrs/pseudo-classes, types/pseudo-elements) when it materially matters to a finding — do not just say "too specific" without the number.
+
+## Minimal safe implementation flow
+
+1. Confirm whether the codebase already declares a layer order. If yes, audit new rules against it. If no, do not retrofit an entire stylesheet into layers as a side effect of a routine review — recommend it as a separate, scoped initiative and note the current specificity-conflict risk in the meantime.
+2. For any flagged `!important` or ID selector, identify the specific rule it's fighting and the minimal layer-based fix (move to correct layer, or remove the escalation entirely because the real fix is layer placement).
+3. Verify inverted `!important` precedence explicitly for any layer-crossing `!important` conflict before declaring a winner — do not eyeball it.
+4. Note any third-party CSS that isn't isolated into its own layer as a maintainability risk.
+
+## Adversarial checklist
+
+Before finalizing a cascade-layer finding, answer these:
+
+- Is the full layer order declared in exactly one place, and does every file agree with it?
+- If this conflict involves `!important` on both sides, did I apply the inverted precedence rule, or did I default to "later wins" (which is wrong for important declarations)?
+- Is this `!important` compensating for a missing/incorrect layer assignment, rather than a legitimate necessity (e.g., overriding inline styles from a CMS)?
+- Is the specificity claim backed by an actual computed tuple, or asserted qualitatively ("too specific")?
+
+If any answer is "not sure," lower the finding's confidence and label it `documentation-based, needs live cascade-order verification` rather than presenting it as a confirmed defect.

package/skills/frontend/css-architecture-design-system-review/references/responsive-strategy.md

@@ -0,0 +1,63 @@
+# Responsive strategy decision guide
+
+Use this reference when deciding container query vs. media query, or auditing reflow/resize-text compliance at 400%/200% zoom.
+
+## What people get wrong
+
+The naive story is:
+
+> Container queries are the new best practice — replace media queries with them wherever possible.
+
+Wrong. Container queries and media queries answer different questions and are not interchangeable. A media query answers "how big is the viewport (or does the user prefer reduced motion / dark mode / etc.)?" A container query answers "how big is *this specific containing element*, regardless of viewport?" A component meant to be reusable inside a narrow sidebar *and* a wide main-content area needs a container query — a media query cannot express that, because the viewport is the same in both placements. Conversely, a page-level layout shift (e.g. switching a top-nav to a hamburger menu) is inherently viewport-driven and belongs in a media query — wrapping the whole page in a container just to query it is unnecessary indirection.
+
+## Officially grounded shape (MDN CSS Containment / Container Queries)
+
+- `container-type: inline-size;` (or `size`) on an ancestor establishes a **query container**; `container-name` optionally scopes which `@container` rules target it.
+- `@container (width >= 400px) { ... }` and named variants `@container excerpt (width >= 400px) { ... }` share the same comparison syntax and logical operators (`and`, `or`, `not`) as media queries.
+- Container **style** queries (`@container style(--flag: value)`) also exist for querying a custom-property value on the container, distinct from size queries — verify which variant (`size` vs `style` vs both) the codebase/browser target actually needs before recommending one.
+- A container query cannot query the size of the element it's applied to relative to itself (no self-referential sizing loop) — the `container-type` must be set on an **ancestor**, and the query targets descendants of that ancestor.
+- Setting `container-type: size` or `inline-size` on an element applies layout/size containment to it, which affects how that element's children are sized (e.g. percentage heights) — this is a real layout side effect, not a no-op flag, and must be accounted for, not just bolted on to "enable container queries."
+
+## Non-negotiable design rules
+
+### 1. Ask "does this depend on its container, or on the viewport?" before choosing
+
+If the same component needs different styling depending on *where it's placed* (sidebar vs. full-width), that's a container-size dependency → container query. If the same component always needs the same styling regardless of placement, but that styling should change based on *screen size*, that's a viewport dependency → media query. Do not default to container queries just because they are newer; recommending one when the actual dependency is viewport-based is a correctness bug, not a stylistic choice.
+
+### 2. Verify the containment side effect before approving `container-type`
+
+Applying `container-type: size` or `inline-size` establishes containment that can change how a container's children resolve percentage-based dimensions and can affect the container's own intrinsic sizing behavior. Flag any new `container-type` addition to an element whose children rely on percentage heights or intrinsic sizing without a check that behavior is still correct.
+
+### 3. Do not recommend "just add both" as a hedge
+
+Applying both a media query and a container query to the same rule for the "same" breakpoint without a distinct rationale for each is a maintainability trap — two systems now need to be kept in sync for one visual outcome. If both are genuinely needed (e.g., viewport-level layout change *and* the component independently needs to adapt to a narrower container within that layout), state the distinct rationale for each explicitly.
+
+### 4. Media queries remain correct — and required — for preference-based and non-size media features
+
+`prefers-reduced-motion`, `prefers-color-scheme`, `prefers-contrast`, `forced-colors`, and print media all have no container-query equivalent; container queries only address size/style-of-container, not user/device preference signals. Never suggest replacing a preference-based media query with a container query.
+
+## WCAG 2.2 reflow and resize-text audit
+
+- **1.4.10 Reflow**: content must be usable without horizontal scrolling (except content requiring 2D layout, like data tables or images) at a 320 CSS-px equivalent viewport width (i.e., 400% zoom on a 1280px-wide viewport). Flag any fixed-width container, fixed `min-width` wider than ~320px on primary content, or `overflow-x` forced on the body/main content region as a reflow-failure risk.
+- **1.4.4 Resize text**: text must remain readable and functional when resized up to 200% without loss of content or functionality, without requiring assistive technology. Flag any font-size defined in `px` on root/body text without a corresponding relative-unit (`rem`/`em`/`%`) sizing strategy, and flag any fixed-height text container that would clip text at 200% zoom.
+- Fixed viewport units (`vh`/`vw`) used for text container height, combined with fixed-size text, is a common reflow+resize-text double failure — flag it as one finding with both WCAG criteria cited, not two separate notes.
+- These are static-review flags based on markup/CSS inspection, not a substitute for live zoom/reflow testing in a real browser — always label the finding `documentation-based risk, requires live verification at 400%/200% zoom`.
+
+## Minimal safe implementation flow
+
+1. For each new/changed responsive rule, identify what the styling actually depends on: container size, viewport size, or a user/device preference.
+2. Match the dependency to the correct query type per the rules above.
+3. If `container-type` is newly applied, check descendant elements for percentage-based sizing that containment could affect.
+4. Scan for fixed-width primary-content containers, fixed-px text sizing, and fixed-height text containers as reflow/resize-text risk flags.
+5. Report all size-based container-query/media-query findings and all WCAG 1.4.10/1.4.4 flags as `documentation-based risk` pending live-browser verification — never assert a WCAG pass/fail from static review alone.
+
+## Adversarial checklist
+
+Before finalizing a responsive-strategy finding, answer these:
+
+- Is the actual styling dependency container-size, viewport-size, or a user/device preference — confirmed, not assumed?
+- If recommending `container-type`, did I check whether it changes containment behavior for existing percentage-sized children?
+- Am I recommending both a media query and a container query for the same visual outcome without a distinct rationale for each?
+- Have I mislabeled a static-review flag as a confirmed WCAG pass/fail instead of a risk pending live verification?
+
+If any answer is "not sure," lower the finding's confidence and label it `documentation-based, requires live verification` rather than presenting it as a confirmed defect.