# Baseline Status Model

Use this reference when determining or explaining the exact Baseline tier of a specific feature and what that tier does — and does not — guarantee for the project's own matrix.

## What people get wrong

The naive story is:

> "Baseline: Widely available" means it works everywhere I need it to.

Wrong. Baseline is computed against a fixed reference set of core browser engines (Chrome/Edge, Firefox, Safari — desktop and their mobile counterparts), not against the org's actual supported-browser matrix. A feature can be "Widely available" in Baseline terms and still be broken for a real user on an unsupported engine (older WebViews, embedded browsers, some enterprise-locked builds) that Baseline does not track at all. Baseline tells you about cross-engine standards convergence; it does not tell you about the org's own matrix.

## Officially grounded tiers

Per the `web-features` project's `compute-baseline` package (verified via Context7, `/web-platform-dx/web-features`):

- Every computed status carries a `baseline` field with one of three effective values:
  - `'high'` — **Widely available**. The feature has been supported by all core browser engines for roughly 30 months (2.5 years).
  - `'low'` — **Newly available**. The feature just became supported across all core engines, but has not yet cleared the widely-available window.
  - `false` — **Limited availability**. At least one core browser engine does not yet support the feature.
- A `'low'`/newly-available result carries a `baseline_low_date` (when cross-engine support was first reached) and, once promoted, a `baseline_high_date` (when it crosses into widely-available, typically ~30 months after `baseline_low_date`).
- `getStatus(featureId, compatKey)` returns the Baseline status for a feature that has completed the project's editorial review; `computeBaseline({ compatKeys, checkAncestors })` computes status for a set of raw compat keys, including features that have not undergone editorial review — treat the latter as provisional and say so.
- `checkAncestors: true` matters for features that are only reachable through a parent capability gated behind a flag or prefix (e.g. an API method whose containing interface is itself experimental) — check ancestors before declaring a leaf API "supported."

## Non-negotiable rules

1. **Never collapse "Newly available" into "safe to use unguarded."** A feature that just crossed into `baseline: 'low'` explicitly excludes browser versions released before the cross-engine convergence date — if the project's matrix includes any browser version older than `baseline_low_date`'s corresponding release, the feature is Limited-Availability *for that project*, regardless of its global Baseline label.
2. **Baseline is not the org's matrix.** Always re-derive the actual compatibility verdict against the project's declared Browserslist/matrix config (see `browserslist-matrix-interpretation.md`), not against Baseline's fixed reference set alone.
3. **Editorial-reviewed vs computed-only status are not the same confidence level.** `getStatus` results have been through the web-features project's review process; raw `computeBaseline` results have not. Label computed-only results as provisional in the finding.
4. **A single low-support browser in the matrix downgrades the whole finding.** If the matrix declares support for even one browser version below what the feature needs, the finding is "unguarded use of a Limited-Availability feature for this project," not "Widely available, no action needed."
5. **Do not confuse Baseline tier with caniuse's raw percentage-of-global-usage figures.** caniuse usage stats answer "how many people, globally, use a supporting browser"; Baseline answers "has this converged across core engines." Both matter, but they answer different questions — cite whichever one actually grounds the claim being made, and do not substitute one for the other.

## Verification targets

- The Baseline `baseline` value and, if `'low'`, the `baseline_low_date` for the feature in question (via `mcp__Context7__query-docs` against `/web-platform-dx/web-features`, or the live `web-features` dataset / `https://web.dev/baseline`).
- The per-browser support table for the feature on `https://caniuse.com/` or MDN's browser-compatibility table, to identify exactly which matrix-declared browser versions lack support.
- The project's own Browserslist/matrix config (see `browserslist-matrix-interpretation.md`) to determine whether any excluded browser is actually in scope.

## When to push back

Push back if the user asks to:

- approve a feature as "safe" solely because a badge or article calls it "Baseline" without stating which tier,
- treat a computed-only (`computeBaseline`, no editorial review) result as an authoritative, final verdict,
- ignore the project's own matrix because "Baseline says it's fine" — Baseline's reference set and the project's matrix are not the same thing, and conflating them produces false-negative compatibility reviews.

# Browserslist Matrix Interpretation

Use this reference when reading, interpreting, or proposing a change to the project's `.browserslistrc` / `package.json` `browserslist` config, or reconciling it with build-tool targets (Autoprefixer, Babel `preset-env`, `postcss-preset-env`, esbuild `target`).

> Version note (uncertainty flag): Context7 did not resolve a dedicated `browserslist` library at the time this skill was authored (only adjacent tooling like `es-check`, which integrates with Browserslist, was found). Treat Browserslist query-syntax details below as `documentation-based (Context7 unavailable for this library)`, and always confirm exact current syntax against the project's own resolved config output and the official `browserslist/browserslist` GitHub README before relying on it for a production recommendation.

## What people get wrong

The common bad assumption is:

> There's no `.browserslistrc` file, so this project doesn't have a declared matrix — I'll just eyeball it.

Wrong. Browserslist resolves configuration from multiple possible locations, in a defined precedence, and most frontend build tools (Autoprefixer, Babel, ESLint's `eslint-plugin-compat`, PostCSS presets) read it implicitly. Before declaring "no matrix exists," check all of the standard resolution points:

- a `browserslist` key in the project's `package.json`,
- a `.browserslistrc` file at the project root or a parent directory,
- a `BROWSERSLIST` environment variable (rare, but overrides file-based config when set),
- a shared/extended config referenced via `extends` in either of the above.

If genuinely none exist, Browserslist falls back to its own defaults (`> 0.5%, last 2 versions, Firefox ESR, not dead`) — that fallback *is* the effective matrix, and should be reported as such rather than treated as "no matrix."

## Reading the matrix correctly

- Browserslist queries combine like `> 0.5%, last 2 versions, not dead` — each comma-separated clause is a query, and by default clauses are combined with logical OR (a browser matching *any* clause is included), unless explicitly joined with `and`. Do not assume AND semantics for comma-separated queries without confirming against the project's resolved output.
- `not dead` excludes browsers without official support or security updates for the past 24 months (per Browserslist's documented `dead` query) — a matrix without `not dead` may be implicitly including officially unsupported browsers, which is itself worth flagging.
- Percentage-based queries (`> 0.5%`) are usage-share-relative and will silently shift over time as global usage shifts — a matrix expressed this way is not a fixed, auditable list; if the review needs a fixed matrix (e.g. for a compliance/procurement commitment), recommend resolving the query to a concrete browser list and pinning that, or flag the drift risk explicitly.
- To see the *actual resolved list* of browsers/versions a config expands to (not just the raw query string), the standard approach is running the project's own Browserslist resolution tooling (commonly exposed via the `browserslist` CLI or a project script) rather than manually reasoning about what a query string expands to — verify the exact command locally instead of assuming a specific CLI invocation, since this detail was not confirmed via Context7 for this skill.

## Non-negotiable rules

1. **Never approve or reject a feature's compatibility using an assumed matrix.** Always resolve the project's actual config (file-based, `package.json`-based, or the documented Browserslist default) before making a claim.
2. **Distinguish the declared query from the resolved browser list.** "last 2 versions" is not itself a browser list; it must be resolved against current release data to know which concrete versions are in scope, and that resolution changes over time as new versions ship.
3. **Reconcile the Browserslist matrix with the build tool's actual behavior separately per tool.** Babel `preset-env`, Autoprefixer, and `postcss-preset-env` each consume the same Browserslist config but apply it differently (transpilation targets vs CSS prefixing vs CSS feature polyfilling) — do not assume that because Babel is configured correctly, CSS-level compatibility is automatically covered, or vice versa.
4. **A percentage- or "last N versions"-based query is a moving target.** Flag this explicitly when a stakeholder wants a fixed compliance commitment; recommend either pinning explicit browser/version pairs or re-verifying the resolved list on a defined cadence.
5. **Proposing a matrix change is a data-backed recommendation, not a unilateral edit.** Base any proposed change on real usage/analytics data for the org's actual audience, and route the recommendation to the product/analytics owner rather than silently narrowing or widening support.

## Verification targets

- The actual `browserslist` key / `.browserslistrc` content in the project (read directly).
- The resolved concrete browser/version list the query expands to, obtained via the project's own tooling — verify the exact invocation locally rather than assuming one.
- Whether Babel, Autoprefixer, and any CSS preset-env-style tool in the build pipeline are all wired to the same Browserslist config (shared root config) rather than divergent per-tool overrides.

## When to push back

Push back if the user asks to:

- widen or narrow the supported-browser matrix without any usage/analytics justification,
- treat a percentage-based query as a fixed, auditable list for a compliance statement without resolving and pinning it,
- add a browser-compatibility "fix" that actually just silences a linter (`eslint-plugin-compat` disable comment) rather than resolving the underlying gap.

# Fallback Verification Patterns

Use this reference when a finding requires checking whether an actual feature-detection gate or polyfill exists and correctly covers the risky code path — across JS, CSS, and HTML — rather than accepting an assertion that "there's a fallback."

## What people get wrong

The common bad assumption is:

> The PR description says there's a fallback, so the fallback question is closed.

That is not evidence. A description, a comment, or a variable name (`hasPolyfillFallback`) is not proof that a gate exists, that it is correctly scoped to the risky code path, or that it fails safe. Always read the actual gating code before closing a fallback finding.

## Three fallback mechanisms, not one

Do not treat "fallback" as a single undifferentiated concept. There are three distinct mechanisms, each with its own failure modes:

1. **CSS `@supports` (feature queries)** — gates a CSS declaration block on whether the engine supports a given property/value pair.
   - Failure mode: `@supports` itself has near-universal support, but the *query* can be written incorrectly (testing the wrong property, or a value that is always true/false), silently making the gate a no-op.
   - Verification: confirm the `@supports` condition actually names the property/value being used in the gated block, and that a real non-supporting fallback declaration exists *before* the `@supports` block (CSS cascade order — the fallback must be overridable, not overridden).

2. **JS runtime feature detection** (`if ('IntersectionObserver' in window)`, `typeof`, `in` checks, capability probing) — gates a code path on whether an API exists before calling it.
   - Failure mode: detecting the *existence* of an API is not the same as detecting *correct/complete* behavior — some browsers ship a partial or buggy implementation that passes an existence check but fails at runtime. For any feature with known partial-implementation history, verify the detection checks the specific method/behavior actually used, not just the top-level constructor.
   - Verification: confirm the detected branch and the fallback branch are both reachable in the code (not dead code), and that the fallback branch has been exercised — read it, do not assume it degrades gracefully.

3. **Polyfills** (loaded unconditionally or conditionally) — ship an implementation of the missing capability.
   - Failure mode: an unconditionally-loaded polyfill ships bytes to every user, including the ~95%+ who already have native support, with zero runtime code-splitting; a conditionally-loaded polyfill (dynamic `import()` behind a feature-detection check) avoids that cost but must be verified to not create a race condition where the gated code runs before the polyfill import resolves.
   - Verification: confirm whether the polyfill load is conditional or unconditional (check the bundler output / import site), and if conditional, confirm the code that depends on the polyfilled API awaits the import before use.

## HTML-level fallback pattern

For new HTML elements/attributes, the platform's own graceful-degradation model (unknown elements render as inline/anonymous boxes, unknown attributes are ignored) is sometimes sufficient — but only when the fallback behavior of "ignore it" is actually an acceptable UX, not a broken one. Do not accept "the browser will just ignore it" as a verified fallback without checking whether ignoring the attribute leaves the feature in a broken or misleading state (e.g. a `<dialog>` element with no polyfill on a browser that doesn't support it does not just degrade — it fails to open at all).

## Non-negotiable rules

1. **A fallback finding is not closed until the actual gating code has been read.** Comments, descriptions, and test names are not evidence.
2. **The fallback path must be reachable and non-dead.** If the "supported" branch always evaluates true in every test/CI browser, the fallback branch may be unexercised dead code — flag this explicitly.
3. **Existence checks are not behavior checks.** For features with a documented history of partial/buggy implementations, verify the detection matches the actual method/behavior used.
4. **Unconditional polyfill loading is a performance finding, not just a compatibility non-issue.** Note the bundle-size cost even when the fallback itself is technically correct.
5. **CSS cascade order matters.** A fallback declaration placed *after* the `@supports`-gated declaration will win regardless of support, silently defeating the gate — always check declaration order, not just presence of the `@supports` block.

## Verification targets

- The literal `@supports`, `if`/`in`/`typeof` check, or dynamic-`import()` gate in the diff or file, read directly — not paraphrased from a PR description.
- CSS declaration order around any `@supports` block.
- Whether the polyfill import is conditional (behind a feature check) or unconditional, and whether dependent code awaits it.
- Whether the fallback branch is exercised by any existing test, or is unexercised dead code.

## When to push back

Push back if the user says:

- "there's a fallback, trust me" without pointing at code,
- "the browser will just ignore the unsupported part" for a feature whose absence actually breaks core functionality (not genuinely inert),
- "we'll add the polyfill later" while shipping the unguarded feature now to a matrix that doesn't yet support it.