# Inline Critical CSS

> Use when a render-blocking stylesheet delays first paint. Extracts above-the-fold CSS, inlines it, and defers the remainder.

- Skill: `jiayaoqijia/inline-critical-css` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx get-skill add jiayaoqijia/inline-critical-css`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jiayaoqijia/inline-critical-css/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: jiayaoqijia (https://skillmd.com/u/jiayaoqijia)
- Updated: 2026-11-12
- Page: https://skillmd.com/skills/jiayaoqijia/inline-critical-css

---


# Inline Critical CSS

A `<link rel="stylesheet">` in the head blocks rendering until it downloads. Inlining the rules the first viewport needs lets the browser paint before the full stylesheet arrives.

## Procedure

1. Measure the blocking cost first, from a throttled run's render-blocking-resources audit:

       npx lighthouse https://shop.example.com --only-audits=render-blocking-resources --output=json | jq '.audits."render-blocking-resources".details.items'

2. Extract the critical rules at the exact viewport you care about (mobile is the default target):

       npx critical https://shop.example.com/ --base dist --inline --width 1300 --height 900 \
         --minify true --extract false > dist/tmp.html

3. Inline the result in a `<style>` block in the head, and load the full sheet asynchronously with the preload/onload trick or `media="print"`:

       <link rel="stylesheet" href="/app.css" media="print" onload="this.media='all'">
       <noscript><link rel="stylesheet" href="/app.css"></noscript>

4. Purge rules that no route uses so the deferred sheet shrinks too:

       npx purgecss --css dist/app.css --content 'src/**/*.tsx' --output dist/

5. Re-run the audit; the page should no longer list a render-blocking CSS resource in the first viewport.
6. Regenerate the critical CSS on every route/design change, wired into the build, or it silently drifts.

## Pitfalls

- Inlining the whole stylesheet, which bloats every HTML response and delays the very paint you were optimizing.
- Generating critical CSS at one viewport and shipping it to all; a wide desktop layout then flashes unstyled content.
- Forgetting the `<noscript>` fallback, leaving the page unstyled without JS.
- Building critical CSS by hand and letting it rot; it must be regenerated by the build.
- Loading the deferred sheet with `async` on a `<link>`, which is invalid and silently does nothing.

## Verification

    curl -s https://shop.example.com/ | grep -c 'rel="stylesheet"'

The head must contain an inline `<style>` and, at most, one deferred stylesheet link with a `noscript` fallback. Report the count and the delta in the render-blocking audit.

