frontend-lighthouse – Design & UI skill for AI agents

Frontend Lighthouse (portable performance gate)

> Portable skill — readable by Claude Code, OpenCode, Codex, Cursor, Windsurf, and others.

> This skill describes a CI performance gate — a Lighthouse CI config plus a workflow — not a

> component library or a visual style. It pairs with the frontend-seo and

> frontend-architecture skills: SEO writes the metadata, Lighthouse supplies a reproducible lab performance signal.

The goal: every pull request is **blocked unless the production build meets explicit Core Web

Vitals budgets and category score floors. Budgets live in one** lighthouserc.cjs, runs are

median-of-N to reduce noise, and the same config runs locally and in CI.

When to Use This Skill

• Use when adding a Lighthouse CI performance gate to a web app.
• Use when setting Core Web Vitals budgets for LCP, CLS, and TBT as the lab proxy for INP.
• Use when configuring category score floors for performance, SEO, accessibility, and best practices.
• Use when debugging flaky Lighthouse runs or making reports visible as CI artifacts.

---

Lighthouse category scores and navigation lab metrics are not field Core Web Vitals certification or complete accessibility/SEO verification. Configure the job as a required check in branch protection for actual blocking; a workflow alone does not enforce that. Required checks with path filters can remain pending, so align trigger policy with repository rules. Build/audit code from PRs only with read-only credentials, bounded runtime and no production secrets; reports may contain page content/URLs.

0. The five core ideas

1. One config, one source of truth. All budgets and assertions live in a single lighthouserc.cjs. Named constants for each budget — no magic numbers buried in assertion objects.

2. Gate the production build, never dev. Lighthouse runs against build + start (the real, optimized output). Dev-server numbers are meaningless for a budget.

3. Multiple runs reduce noise. Run 3+ times and assert on the median run, to reduce per-run jitter; repeated runs do not eliminate CI noise.

4. Separate lab budgets from field thresholds. Use LCP/CLS lab budgets plus a chosen TBT budget; field INP ≤200 ms needs separate representative field monitoring. Lab category scores do not certify field CWV.

5. Blocking in CI, visible as artifacts. A GitHub Action runs the gate on every PR touching the app and uploads the HTML/JSON reports so failures are debuggable.

---

1. Files this skill adds

repository/
├── .github/workflows/lighthouse.yml  ← workflow must be at repository root
└── apps/web/                        ← or your app root
    ├── lighthouserc.cjs              ← budgets, assertions and collect settings
    └── package.json                 ← "lhci": "lhci autorun --config=./lighthouserc.cjs"

Plus a dev dependency: @lhci/cli.

pnpm add -D @lhci/cli        # or npm i -D / yarn add -D

---

2. The config (lighthouserc.cjs)

.cjs (CommonJS) so it loads without ESM/TS transpilation. Every budget is a named constant

with a comment explaining the threshold — never a bare number inside an assertion.

/**
 * Lighthouse CI configuration — Core Web Vitals budgets for the marketing surface.
 *
 * Enforces Google's mobile "good" CWV thresholds:
 *   - Largest Contentful Paint (LCP) ≤ 2500 ms
 *   - Cumulative Layout Shift (CLS)  ≤ 0.1
 *   - Interaction to Next Paint (INP) ≤ 200 ms
 *
 * INP is a *field* metric with no direct lab audit, so in the lab we gate on
 * Total Blocking Time (TBT) with a separately selected budget. There is no
 * experimental INP audit assumed here; measure INP with field instrumentation.
 *
 * Collection runs against the *production* server (build + start) on Lighthouse's
 * default mobile (Moto G4 / slow 4G) emulation.
 */

/** The fixed port the production server is started on for the audit. */
const PORT = 3100;
const BASE_URL = `http://localhost:${PORT}`;

/** Pages whose budgets are enforced in CI. */
const MARKETING_URLS = [`${BASE_URL}/`];

/**
 * Core Web Vitals budgets on mobile — Google's "good" thresholds.
 * These are the values that earn the best Lighthouse scores.
 */
const LCP_BUDGET_MS = 2500; // good
const TBT_BUDGET_MS = 200; // Chosen lab budget; not an INP measurement
const CLS_BUDGET = 0.1; // good

module.exports = {
  ci: {
    collect: {
      // Build is run separately in CI; here we only serve the production output.
      startServerCommand: `pnpm start --port ${PORT}`,
      startServerReadyPattern: "Ready in", // framework's "server ready" log line
      startServerReadyTimeout: 120000,
      url: MARKETING_URLS,
      // Median of multiple runs keeps the gate stable against per-run jitter.
      numberOfRuns: 3,
      settings: {
        // Default mobile emulation; opt into desktop via env for a second run.
        preset:
          process.env.LHCI_FORM_FACTOR === "desktop" ? "desktop" : undefined,
        // Only gate the categories we care about; skip PWA category noise.
        onlyCategories: [
          "performance",
          "seo",
          "accessibility",
          "best-practices",
        ],
      },
    },
    assert: {
      // Per-audit median aggregation is configured on each assertion.
      // Set aggregationMethod per assertion below.
      assertions: {
        // --- Core Web Vitals budgets (the contract) ---------------------
        "largest-contentful-paint": [
          "error",
          { maxNumericValue: LCP_BUDGET_MS, aggregationMethod: "median" },
        ],
        "cumulative-layout-shift": ["error", { maxNumericValue: CLS_BUDGET, aggregationMethod: "median" }],
        "total-blocking-time": ["error", { maxNumericValue: TBT_BUDGET_MS, aggregationMethod: "median" }],
        // --- Category floors (target top Lighthouse scores) -------------
        "categories:performance": ["error", { minScore: 0.9, aggregationMethod: "median" }],
        "categories:seo": ["error", { minScore: 0.95, aggregationMethod: "median" }],
        "categories:accessibility": ["error", { minScore: 0.95, aggregationMethod: "median" }],
        "categories:best-practices": ["error", { minScore: 0.9, aggregationMethod: "median" }],
      },
    },
    upload: {
      // Keep reports in the CI run's filesystem; no external LHCI server.
      target: "filesystem",
      outputDir: "./.lighthouseci",
    },
  },
};

Hard rules:

• Every budget is a named constant with a unit in its name (LCP_BUDGET_MS) and a comment.
• aggregationMethod: "median" is non-negotiable — single-run gates flake constantly.
• numberOfRuns ≥ 3 (odd numbers give a clean median).
• TBT is a lab diagnostic correlated with responsiveness, not an INP threshold guarantee. Do not configure a nonexistent INP audit; measure field INP separately.
• Keep onlyCategories to exactly what you gate — fewer audits, faster, less noise.

---

3. Choosing budget severity and thresholds

| Audit / category | Severity | Threshold | Why |

| --------------------------- | -------- | --------- | ----------------------------------------------------- |

| largest-contentful-paint | error | ≤ 2500 ms | Google "good" LCP |

| cumulative-layout-shift | error | ≤ 0.1 | Google "good" CLS |

| total-blocking-time | error | ≤ 200 ms | INP lab proxy |

| Field INP | separate monitoring | ≤ 200 ms | Not supplied by default Lighthouse navigation audit |

| categories:performance | error | ≥ 0.9 | top (green) band |

| categories:seo | error | ≥ 0.95 | SEO is cheap to keep perfect |

| categories:accessibility | error | ≥ 0.95 | a11y regressions must block |

| categories:best-practices | error | ≥ 0.9 | green band |

Use error for contracts that must hold and warn for audits that are environment-dependent or

aspirational. Start strict and only loosen with a recorded reason — a budget you keep raising

to make CI pass is a budget that no longer protects anything.

---

4. The npm script

// package.json
{
  "scripts": {
    "lhci": "lhci autorun --config=./lighthouserc.cjs"
  }
}

lhci autorun runs collect → assert → upload in sequence. Run it locally before pushing to

reproduce exactly what CI does:

pnpm build && pnpm lhci
# desktop form factor:
LHCI_FORM_FACTOR=desktop pnpm build && LHCI_FORM_FACTOR=desktop pnpm lhci

---

5. The GitHub Actions workflow

Runs on PRs that touch the app or the workflow itself. Builds the production output, runs the

gate, and always uploads the reports (even on failure) so a red check is debuggable.

name: Lighthouse CWV

on:
  pul

… (full content is in the download package)