Before anything else, one check that costs five seconds: z-index does nothing at all on an element whose position is static. That is the default. If the property is not being read, no value of it is going to help.

The exception is a flex or grid child, where z-index applies without positioning. It is the one place the property works on a static element, and it is a pleasant surprise exactly once.

Past that, raising the number stops helping, and it stops helping abruptly rather than gradually. The reason is that z-index does not sort an element against the page. It sorts it against its siblings, inside a box called a stacking context.

The stacking context is the whole answer

A stacking context is a self-contained painting order. Everything inside one paints together, as a unit, at whatever position its root occupies in the parent context. Nothing inside can paint above something outside it.

Which produces the rule that explains almost every one of these bugs: a child of a context with z-index: 1 sits below a sibling of that context with z-index: 2 — at 9999, at 2147483647, at any number you can type.

the tooltip never wins, and the number is irrelevant

.card    { position: relative; z-index: 1; }
.overlay { position: relative; z-index: 2; }

.card .tooltip { position: absolute; z-index: 9999; }

/* .tooltip paints inside .card, so it paints under .overlay.
   The only number that matters here is the 1. */

The same tooltip at z-index: 9999, twice. The only thing changing is opacity on its parent - and opacity below 1 opens a stacking context, which puts the tooltip under an overlay it used to sit above. — runs on the page itself.

So the element you are editing is rarely the one deciding. The question is which ancestor opened a context, and where that ancestor sits among its own siblings.

It is worth being precise about what a context does to the numbers inside it, because the mental model people carry is usually a bigger number wins rather than the true one, which is closer to a version scheme. 1.9999 is still less than 2. The ancestor is the integer part.

What creates one is a longer list than anybody remembers

The familiar case is a positioned element with a z-index other than auto. The rest is where the surprises live:

opacity

Any value below 1. A hover state at 0.98 opens a context for the whole subtree.

transform

Any value other than none — including translateZ(0), added for the compositor by someone not thinking about paint order at all.

filter, backdrop-filter

Any value. A blur behind a sticky header is the usual arrival route.

mix-blend-mode

Anything other than normal.

isolation: isolate

The only one on this list whose entire purpose is to do it, and therefore the only one that is never a surprise.

contain

paint, layout, strict or content.

will-change

Naming any property above. A hint about performance that changes correctness.

position: fixed

On its own, with no z-index involved at all.

This is why the bug so often arrives with a commit that has nothing to do with layering. A card gets a hover opacity, a section gets a transform, and a dropdown three levels down that worked yesterday is trapped. Nothing about the dropdown changed.

The move that actually finds it

Do not start at the element. Start above it and work down:

1. Walk from the trapped element up to the root, and at every ancestor ask the one question: does this open a stacking context?
2. The first ancestor that does is your ceiling. Nothing below it can ever paint above something outside it.
3. Find where that ceiling sits among its own siblings. That comparison — not the one you were editing — is the one deciding.
4. Fix it there: raise the ceiling, or move the element out from under it, and put the child back to a number a person can read.

Doing that by hand means reading computed styles for eight properties on every ancestor, which is precisely why it turns into raising the number instead. It is worth doing properly once, because the answer is nearly always a single ancestor with a property nobody associates with layering.

The four fixes, worst to best

Raise the number

Works only when the two elements are already in the same context, which is the case you did not have. It is the fix that produced 9999 in the first place - each round of it raises the ceiling nobody found.

Raise the ancestor

Correct, and usually a one-line change: put the z-index on the ceiling instead of on the child. The risk is that the ceiling now beats things it should not, so it moves the problem up a level rather than removing it.

Move the element out

Render the overlay as a sibling of the ceiling rather than a descendant. In a component framework that means a portal, and the reason portals exist is precisely this - not styling, paint order.

Use the top layer

For anything modal, this is the answer, and it is the only one that cannot regress. See below.

There is a fifth thing people try - position: fixed on the trapped element - and it is worth naming because it seems to work. A fixed element escapes scrolling ancestors, not stacking contexts. If any ancestor has a transform, filter or will-change, the fixed element is positioned against that ancestor instead of the viewport, and the bug becomes two bugs.

isolation: isolate, and the one time you want more of this

Everything above treats a stacking context as an accident. isolation: isolate is the property that creates one on purpose, and it is the right tool in one specific situation: a component whose internal layering must not leak into the page it is dropped into.

a component that cannot fight with the page around it

.widget {
  isolation: isolate;
}

/* Everything inside .widget now sorts among itself.
   The page sorts .widget as one thing.
   Nothing inside can reach past it, in either direction. */

That is the same mechanism causing every bug in this article, aimed deliberately. A stacking context is not a hazard; an accidental one is. The difference is whether you knew you were opening it.

The top layer ignores all of it

A <dialog> opened with showModal(), an element with the popover attribute, and anything in fullscreen do not participate in this system at all. They paint in the top layer: above every stacking context on the page, in the order they were opened.

no z-index anywhere, and nothing can cover it

<div popover id="menu">…</div>
<button popovertarget="menu">Open</button>

No z-index competes with the top layer and none is needed on it. Which makes it the real fix for the case that produces 9999 in the first place — a modal, a tooltip, a menu that has to escape whatever it is nested in. Not a bigger number. A different layer.

Sideways scroll is one of the few layout bugs with a single cause. Something is wider than the viewport, or starts far enough right that its edge lands outside it. There is no cascade to reason about and no specificity to lose to. There is one element, and the work is finding it.

It is also the bug most often closed without being found, because hiding it takes one line and looks identical in the screenshot.

The handful of things that actually do it

100vw

On a desktop browser with a classic scrollbar, 100vw is the viewport including the scrollbar; the content box you are comparing it against is not. A full-bleed section overflows by around fifteen pixels — enough to scroll, small enough to read as a rendering fault.

min-width: auto

The default on flex and grid children, and it means do not shrink below your content. A long word, a wide table or an unbroken URL in a grid cell will push the whole track. Responsible for more of these than everything else here combined.

Fixed pixel widths

A width: 480px card in a 390px viewport. Obvious in review, invisible on the desktop it was written on.

Negative margins

A full-bleed trick pulling content out past the right edge, usually correct on one breakpoint and not the others.

Absolute positioning

right: -40px on a decorative shape. The element is out of flow, but not out of the scroll area.

Unbreakable strings

A URL, a hash, a wallet address, a base64 blob. No spaces means no wrap opportunity, unless overflow-wrap: anywhere says otherwise.

Three rows in a frame. Two are sized to the content box; the middle one is sized to 100vw, which on a desktop browser includes the scrollbar the content box does not get. Fifteen pixels, and the page scrolls. — runs on the page itself.

Worth knowing what does not do it: box-shadow and outline paint outside the box without contributing to scroll width. transform: translateX does contribute, even though the layout position has not moved.

Why the outline trick misleads

the advice everybody gives

* { outline: 1px solid red; }

It works often enough to stay in circulation, and it is wrong in a specific way: it marks every element, so the offender and its dozen innocent descendants all appear to stick out together. You end up staring at the deepest one — a <span> inside the thing that is actually too wide — because it is the one whose red box is easiest to see.

It also cannot see anything already clipped by an ancestor with overflow: hidden set for a legitimate reason, which is exactly where these hide.

Measure edges instead

The reliable test is arithmetic, not colour. Compare every element's right edge against the document width, then take the shallowest element that fails:

the whole diagnosis, in five lines

const limit = document.documentElement.clientWidth;

[...document.querySelectorAll('*')]
  .filter((el) => el.getBoundingClientRect().right > limit)
  .slice(0, 5);

// The first result is the cause.
// Everything after it is a passenger inside the cause.

The same pass catches the left side, which people forget exists. An element at a negative offset does not always produce scroll — a browser does not scroll into inline-start overflow in a left-to-right document — but it does in a right-to-left one. Which is how this ships broken in Arabic and Hebrew after passing every check in English.

The two fixes for the two commonest causes

Once the element is identified, the repair is nearly always one of two lines. Neither is clever, and both are worth knowing by heart.

full bleed without the scrollbar arithmetic

.bleed {
  width: 100dvw;
  margin-inline: calc(50% - 50dvw);
}

/* Or skip the unit question entirely: */
.bleed-grid {
  grid-column: 1 / -1;
}

letting a flex or grid child actually shrink

.track > * {
  min-width: 0;
}

.track pre,
.track code {
  overflow-wrap: anywhere;
}

/* min-width: auto is the default and it means
   "never shrink below my content". A table, a long
   URL or a wide <pre> will push the whole track. */

min-width: 0 on flex and grid children is the single highest-value line in responsive CSS, and it is invisible until the day a long word arrives. Some teams set it globally on grid and flex children and never see this class of bug again.

Catching it before a person does

This bug has an unusual property among layout bugs: it is trivially detectable in CI. It is one comparison of two numbers, it needs no screenshots and no visual diffing, and it fails deterministically.

the assertion, at three widths

for (const width of [320, 768, 1280]) {
  await page.setViewportSize({ width, height: 900 });
  const scrolls = await page.evaluate(
    () => document.documentElement.scrollWidth >
          document.documentElement.clientWidth,
  );
  expect(scrolls, `scrolls sideways at ${width}px`).toBe(false);
}

320 is the width WCAG asks a page to reflow to, so that row is a conformance check as well as a layout one. Adding those three lines is usually the last time anybody thinks about horizontal overflow in that codebase.

When hiding it is the correct answer

Sometimes it genuinely is: a decorative shape deliberately drawn past the edge, a carousel whose track is meant to be wider than its frame. In both cases the clip belongs on that element or its immediate container — never on body or html.

The reason is not tidiness. overflow on the scroll container is what makes position: sticky stop working, and the failure surfaces somewhere else entirely, weeks later, as a header that will not stick. A clip scoped to the thing being clipped costs nothing and takes nothing else down with it.

If you inherit a codebase with overflow-x: hidden on body, remove it before debugging anything sticky. You are not looking for a sticky bug. You are looking for the overflow it was hiding.

The requirement is simple enough, and the arithmetic is not hard:

1.4.3 — normal text

4.5:1 against its background.

1.4.3 — large text

3:1. Large means 24px, or 18.66px when bold — computed pixels, not the number in the design file.

1.4.11 — non-text

3:1 for the parts of a control that identify it, and for meaningful graphics.

None of that is in dispute. The dispute is over which two colours go into it. A checker takes what you type; a browser paints what the page composited. Those agree on a plain card on a plain background, and part company everywhere else — which is most of the interesting parts of most designs.

The background is composited, not declared

What sits behind a glyph is the result of stacking every painted layer beneath it: the body colour, a section gradient, a card at 92 percent opacity, an inherited opacity on an ancestor fading the whole subtree, a backdrop-filter blurring whatever is under it. None of those is a value you can read off one element and paste into a form.

Text has the same problem from the other side. color: rgba(0, 0, 0, 0.72) is not black; it is whatever black becomes over that particular background.

checked as 21:1, painted at 8.8:1

.panel   { background: #f4f5f7; }
.panel p { color: rgba(0, 0, 0, 0.72); }

/* The palette was checked as #000 on #fff: 21:1.
   The browser composites #444545 on #f4f5f7: 8.8:1.
   Still a pass - and the margin is now four times smaller
   than the number anybody wrote down. */

The same sentence, the same declared colour. On the right the alpha is doing what alpha does, and the ratio moves from a comfortable pass to a clear failure without one hex value changing anywhere in the stylesheet. — runs on the page itself.

The honest way to get the number is to compute the effective background by walking up the tree, compositing each layer as it goes, stopping at the first fully opaque paint, then applying the alpha of the text over that. That is what the browser did. Anything else is a different question with a similar-looking answer.

Where it goes wrong in practice

Three failures account for nearly all of them, and all three pass a swatch check.

1. Dark mode, derived rather than designed. A palette is checked in light mode and the dark tokens are produced by inverting lightness. Mid-greys that had 5:1 against white land at 3.2:1 against a near-black. Both were checked — as swatches, twice, never as a page.
2. The hero image. Text over a photograph is checked against the photograph's average colour, or against nothing at all. The requirement is not the average: it is met at the worst pixel behind any glyph. A scrim works precisely because it makes the background computable again.
3. The brand colour used as text. A colour chosen to be seen as a large filled shape is rarely legible at 14px on white. It passes as a button and fails as a link.

One place a low ratio is permitted: WCAG exempts inactive components. Worth knowing before rewriting a palette to fix something that was never a failure.

The criterion everybody forgets

Contrast is not only about text. 1.4.11 asks for 3:1 on input borders, focus indicators, toggle states, icons carrying meaning on their own, and the lines of a chart.

Focus rings are where this is failed most, and the failure is invisible to everyone who uses a mouse. A ring in the brand colour on the brand background can sit at 1.4:1 and look entirely intentional. A keyboard user cannot tell where they are on the page.

the two-tone ring that survives any background

:focus-visible {
  outline: 2px solid var(--ring);
  outline-offset: 2px;
  box-shadow: 0 0 0 4px var(--ring-halo);
}

/* The halo does the work: whatever the ring fails against,
   the second colour behind it passes. */

How the number is actually computed

Worth knowing, because the shape of the formula explains most of the surprises. Contrast is a ratio of relative luminance, and relative luminance is not brightness as a person perceives it:

the whole of WCAG 1.4.3, in arithmetic

const channel = (v) => {
  const c = v / 255;
  return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
};

const luminance = ([r, g, b]) =>
  0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);

const ratio = (a, b) => {
  const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
  return (hi + 0.05) / (lo + 0.05);
};

• Green carries 71 percent of the weight. Two colours can be equally dark to look at and land far apart, which is why a mid-green and a mid-blue behave nothing alike as text.
• The 0.05 floor compresses the dark end. Once a background is near-black, making it blacker barely moves the ratio - and dark-mode palettes are tuned in exactly that region.
• The exponent punishes mid-tones. The gap between #767676 and #808080 is invisible and it is often the gap between 4.5:1 and 4.3:1.

This is also why a ratio cannot be averaged. Two paragraphs at 4.6:1 and 4.4:1 are not "about 4.5". One passes and one does not, and the requirement is per element.

What to actually do

• Check the rendered page, not the palette. The palette is a set of intentions; the page is the artefact.
• Check both themes. A derived dark palette is a second design, and it has been checked once.
• Check at the smallest size the text is actually used at — captions, labels, legal lines, placeholder text.
• Check the focus ring, on every surface it can appear over.

Those four cover nearly every contrast failure that ships from a design system which was, on its own terms, checked.

Asking what font a page uses sounds like one question. It is three:

1. Which family the CSS asked for — the font-family list, in order.
2. Which face the browser matched — after @font-face, weight, style, stretch and unicode-range have all had a say.
3. Which one it actually painted with — per glyph, after loading succeeded, failed or timed out.

On a page that ships its own fonts properly, all three agree. On most pages at least one of them does not, and the gap is invisible if you only read the stylesheet — because the stylesheet is the request, not the outcome.

Four ways the declared font is not the rendered one

The file never arrived

A wrong path, a blocked CDN, a missing CORS header. There is no error a visitor would notice — the browser moves to the next family in the list and the page renders in the fallback, looking almost right.

The glyph was outside unicode-range

A subset face covers part of the character set. A curly quote, an em dash or an accented name falls outside it and is painted by a different font in the same line of text.

The weight was never shipped

A stylesheet asking for font-weight: 600 with only 400 and 700 loaded does not fail. It matches the nearest face, and depending on the engine may thicken it artificially instead.

The face arrived late

font-display: swap paints the fallback first and swaps when the file lands, which is a layout shift by design. block keeps the text invisible until it lands. Both are correct configurations of the same tradeoff.

Synthetic bold is the loudest tell

When a browser cannot find a bold face, it makes one — by drawing the regular weight a second time at a slight offset. It looks like bold at a glance and wrong at any size above a heading: the counters fill in, the stems thicken unevenly, and the letterfit is still the regular font's.

Synthetic oblique is the same trick for italic: a slant applied to upright letterforms, with none of the different shapes a real italic has. The tell is the lowercase a — in most true italics it stops being a double-storey letter, and in a synthesised one it never does.

Both are worth catching because both mean a weight is being requested that the page does not ship. That is a build problem, not a design one, and it is fixed in the font loading rather than in the CSS that asked.

turn the guess off and see what you actually have

body { font-synthesis: none; }

/* Every faux-bold and faux-italic on the page reverts to
   its real weight. What changes is what was never shipped. */

The loading order that causes most of the damage

A webfont is discovered late by design. The browser parses the HTML, requests the stylesheet, parses that, finds the @font-face, and only then learns the font exists — and in most builds it learns which file only once an element using that family is laid out.

1. HTML arrives and parsing begins.
2. The stylesheet is requested. Rendering is blocked until it lands.
3. @font-face is parsed. The file is still not requested.
4. Layout finds text wanting that family. Now the file is requested.
5. It arrives, and depending on font-display the text either swaps or appears.

Steps 2 to 4 are where the round trips accumulate, and they are why preload exists — it moves the request to the top of step 1:

the one hint worth spending, and its two easy mistakes

<link rel="preload" as="font" type="font/woff2"
      href="/fonts/inter-var.woff2" crossorigin>

<!-- crossorigin is required even for a same-origin font:
     fonts are fetched in CORS mode, and a preload without
     it downloads the file twice. -->
<!-- Preload only the faces above the fold. Preloading six
     weights makes every one of them compete with the CSS. -->

A preload that is not used within a few seconds is worse than none at all. It spent bandwidth during the most contended moment of the page load and the browser will say so in the console — which is the one font warning worth reading.

How to see what actually rendered

The browser exposes the loaded set. document.fonts is a FontFaceSet you can iterate for every face and its status, and check() answers whether a specific request can be met right now:

what is loaded, and whether one request can be met

[...document.fonts].map((f) => [f.family, f.weight, f.status]);

document.fonts.check('600 16px Inter');
// false means: nothing will paint at 600 - it will be faked.

That covers what is available. Which face a particular run of text was painted with is harder — the platform decides per glyph — so the practical approach is to compare the computed font-family against the loaded set, and look for the synthesis tells above wherever the two disagree.

Variable fonts change the arithmetic

Most of the failures above come from shipping a set of static weights and asking for one that is not in it. A variable font removes that category entirely: one file carries a continuous weight axis, so font-weight: 570 is a real instance rather than a synthesis.

One file, not six

A variable face at four weights is usually smaller than the four static files it replaces, and it is one request rather than four competing ones.

No synthetic anything

Every weight in the axis range exists. There is nothing for the browser to fake.

The catch

@font-face must declare the range — font-weight: 100 900 — or the browser treats the file as a single weight and fakes the rest anyway, from a font that contained them all.

the declaration that unlocks the axis

@font-face {
  font-family: 'Inter';
  src: url('/fonts/inter-var.woff2') format('woff2-variations');
  font-weight: 100 900;
  font-display: swap;
}

Fallback metrics, which almost nobody sets

If a webfont swaps in and the text reflows, the cause is that the fallback has different metrics: a different x-height and different advance widths, so the same string occupies a different number of lines. That is a layout shift attributable entirely to typography.

an override face, costing no bytes and no request

@font-face {
  font-family: 'Inter fallback';
  src: local('Arial');
  size-adjust: 107%;
  ascent-override: 90%;
  descent-override: 22%;
}

body { font-family: 'Inter', 'Inter fallback', sans-serif; }

Two paragraphs, the same words, the same box. The left one swaps between font stacks with different metrics and takes everything below it down the page; the right one has a fallback face adjusted to match, so the shapes change and nothing moves. — runs on the page itself.

The local font is made to occupy the same space as the webfont, so the swap becomes a change of shape rather than a change of layout. It is the cheapest CLS fix on the web and it is almost never applied.

This is a normal thing to want. You are taking over a codebase whose design decisions were never written down, or matching a component to a system somebody else owns, or checking whether the site you are about to redesign has a scale at all.

The build is not a black box. It is a set of decisions, flattened — and most of them survive the flattening.

Version 4 hands it to you

Tailwind 4 moved the theme into CSS. A @theme block compiles to custom properties on the root element, and custom properties are readable at runtime, in order, with their computed values.

the theme, read off a live page

const root = getComputedStyle(document.documentElement);

[...document.styleSheets]
  .flatMap((s) => [...s.cssRules])
  .filter((r) => r.selectorText === ':root')
  .flatMap((r) => [...r.style])
  .filter((name) => name.startsWith('--color-'))
  .map((name) => [name, root.getPropertyValue(name).trim()]);

So on a version 4 site the theme is not inferred at all. It is read — every token the build kept, under the name the author gave it, which is the part that matters:

What comes back off a version 4 build: the token, its name, and the value it resolves to. The name is the half a screenshot of the site could never give you. — runs on the page itself.

--color-brand-600 tells you something that #0e7490 does not. The names are the design system. The values are only its output.

The names are also the fastest way to date a codebase. A palette named for its role — surface, rule, ink, danger — is a system somebody maintained. A palette named blue-1 through blue-9 is a palette somebody pasted.

Version 3 has to be inferred

Before the theme lived in CSS it lived in a config file that never shipped. What ships is the generated utilities — and the scale is recoverable from them, because every generated class is a name-value pair. .text-slate-700 carries the value of slate-700 in its own declaration.

• Collect every rule whose selector is a Tailwind-shaped class.
• Group by the utility prefix — text-, bg-, p-, rounded-, shadow-.
• Read the declared value out of each rule.
• Take the breakpoints from the @media queries the rules are nested inside.

It is arithmetic on a stylesheet rather than analysis. The gap is that a version 3 build only emits what was used: the config may have carried forty greys, and the stylesheet carries the nine somebody wrote a class for.

Reading the scale rather than the colours

Colour is the part everybody recovers first and the part that matters least — a palette can be lifted from a screenshot. The spacing scale cannot, and it is the thing that makes a new component look like it belongs.

every spacing value the page actually uses, ranked

const seen = new Map();

for (const el of document.querySelectorAll('*')) {
  const s = getComputedStyle(el);
  for (const side of ['paddingTop', 'marginBottom', 'gap']) {
    const v = s[side];
    if (v && v !== '0px' && v !== 'normal') {
      seen.set(v, (seen.get(v) ?? 0) + 1);
    }
  }
}

[...seen].sort((a, b) => b[1] - a[1]).slice(0, 12);

The output tells you two things at once. A tidy result — 8px, 16px, 24px, 32px, each used hundreds of times — is a scale somebody kept to. A long tail of 13px, 19px, 27px used twice each is a scale that exists in the config and not in the codebase, which is a different finding and a more actionable one.

Breakpoints

Read from the @media queries in the stylesheet, deduplicated. Faster than any documentation, and correct by construction.

Radii and shadows

Small, closed sets. Three radii is a system; eleven is a codebase where every component chose for itself.

Type scale

The computed font-size and line-height pairs actually in use. The pairing is the part a config file lists and a page proves.

What is gone for good

Anything tree-shaken

A token defined and never used is indistinguishable from a token that never existed. True in both versions.

Plugin configuration

Custom variants, container queries, typography plugin settings. The output is visible; the switch that produced it is not.

The reasoning

You can recover that the spacing scale steps by 4 pixels. You cannot recover that the team agreed to it in a meeting, or that step 6 is deliberately absent.

The names, in version 3

#0e7490 is in the stylesheet. Whether the team called it accent-deep or cyan-700 is not — unless the class list happens to say so.

What to do with what you get

The recovered theme is a starting file, not an answer. Three things are worth doing with it before it is useful:

1. Sort each scale and look at the gaps. A colour ramp missing its 400 step, or a spacing scale with two values eleven pixels apart, is where the system was patched rather than extended.
2. Count the uses. A token used once is a decision somebody made in a hurry; a token used four hundred times is the system. The count is the difference between a palette and a scale.
3. Name what you recovered, if the build could not. On a version 3 site you are handed values without names, and writing the names down is the act that turns a list of hex codes back into a design system.

One honest caution: a recovered theme is evidence about the shipped page and nothing more. It cannot tell you which values were deliberate, and it will happily present an inconsistency as a scale. Treat it as a survey, not as documentation.

The used subset is the useful subset

This reads like a limitation and mostly is not. If you are matching a component to a site, the values in the shipped stylesheet are exactly the values in use — the recovered theme is the live one, with the aspirational parts already removed.

Where it does matter is auditing, and there it cuts the other way. A recovered scale with eleven greys in it is not proof that eleven greys were designed. It is proof that eleven greys were shipped — which is the more useful of the two findings, and the one no config file would have told you.

Stack detection looks like pattern matching and mostly is. What separates a useful answer from a confident wrong one is whether the tool tells you how it knew — because the six kinds of evidence a page leaves are not equally reliable, and two of them are trivially faked.

The six, weakest last

A DOM marker

An attribute or class the framework itself writes - data-reactroot and its successors, a hydration marker, a generated class prefix. Strong: it is a side effect of the thing running, not a declaration about it.

A page global

A variable the library leaves on window. Equally strong, and often carries a version the page did not mean to publish.

A namespaced CSS variable

A custom property whose prefix belongs to one design system. Quietly one of the best signals, because it survives the minification that erases the others.

An asset URL

A script or stylesheet whose path names the thing. Good, with a caveat: a bundled copy under a hashed name says nothing, so absence here is not evidence of absence anywhere.

A response header

The server naming its own software. Reliable when present, and routinely removed, rewritten or set to something untrue as a matter of policy.

The generator meta tag

A declaration by the page about itself. The weakest of the six: a string somebody typed, surviving long after the thing it names was replaced, and the first thing edited by anyone who does not want to be identified.

The same six kinds, weighted by how hard each is to fake. The top three are side effects of code running; the bottom one is a sentence in the markup. — runs on the page itself.

The ordering is the useful part. Two tools can report the same name from the top of that list and from the bottom of it, and those are not the same finding.

the same claim, at both ends of the list

<meta name="generator" content="WordPress 5.2">

<link rel="stylesheet"
      href="/wp-content/themes/twentytwenty/style.css?ver=6.5">

<!-- The first is a string in a template, unchanged since 2019.
     The second is a file the server is really serving,
     and the two disagree by four major versions. -->

Why the evidence has to be shown

A flat list of names is not checkable. Told that a page is running a particular framework, you have no way to know whether that came from a hydration marker or from a meta tag somebody left in a template five years ago — and those two facts deserve different amounts of belief.

So every match here comes with the literal thing that matched and where it was found. It makes the readout longer and it is the difference between a claim and a finding.

It also makes the detector correctable. When a match is wrong, the evidence says which rule to fix rather than leaving somebody to guess at a heuristic they cannot see.

Absence is not evidence

The failure that produces confidently wrong readouts is not a bad match. It is treating a missing signal as a negative finding — and on a modern build, missing is the normal case.

Bundling

A library compiled into main.a1b2c3.js leaves no filename to match. It is running; the URL says nothing.

Minification

Class prefixes and global names are renamed. A framework can be present with every one of its usual markers gone.

Server rendering

Markup arrives fully formed. The runtime that produced it may never have reached the browser at all.

A stripped header

Removed as a matter of policy at more or less every serious host. Its absence is a security setting, not a fact about the stack.

So the honest output has two states rather than three: identified, with the evidence and not identified. There is no not present, and a tool offering one is telling you something the page did not say.

Versions, and what a version is worth

Where a page states a version, it is read and reported. Where it does not, nothing is invented — a guessed version is worse than a missing one, because the missing one prompts a question and the guessed one ends it.

Some versions cannot be told apart from the outside at all. Two major releases of the same tool can declare identical variable names, and a detector claiming to distinguish them is claiming something the page did not say.

Detecting yourself is the useful direction

The instinct is to point this at somebody else's site. The finding that changes a decision is usually on your own, because a stack list from the outside is a list of what actually reached a browser — not what the lockfile says, not what the bundler was configured to split, not what a colleague removed six months ago.

• A library everyone believes was dropped, still shipping in a chunk nothing imports any more.
• Two versions of the same framework, because a widget brought its own.
• A tag manager loading a second analytics vendor that no one on the team chose.
• A consent banner that itself loads three third parties before consent is given, which is the most common finding of all and the most expensive one.

That last one is worth checking on any site with a cookie banner. It is a compliance failure that is invisible from the inside and takes about four seconds to see from the outside.

What to do with the answer

The immediate use is orientation: opening an unfamiliar codebase's output before opening its source tells you what you are about to read.

The slower use is the third-party list. Most pages carry more analytics, tag managers, session replay and consent tooling than anybody on the team believes, because each was added once by somebody with a good reason. Seeing them named together, with the evidence for each, is usually the most uncomfortable part of the readout — and the most useful.

Start with the honest version: there is no signature. A model can produce markup indistinguishable from a person's, and a person can produce markup indistinguishable from a model's. Anybody selling certainty here is selling a coin flip with a progress bar.

What there is, is texture. Generated pages tend to carry several habits at once, and the habits are measurable even though none of them is wrong on its own.

The habits worth counting

Utility-class verbosity

Forty classes on one element, the same spacing scale repeated at three different values, colour utilities that never resolve to a token.

Structural padding

A paragraph wrapped in eleven nested div elements, each with one child, none of them doing anything.

Copy patterns

Headings built from the same six adjectives, three-item lists everywhere, a call to action that says nothing.

Accessibility theatre

aria-label on an element that already has an accessible name, roles restating what the tag already means.

Runtime artifacts

State written on every render, effects with dependency lists that cannot be right, the same fetch issued twice.

Any one of these is normal. A design system produces long class strings; a component library nests; a careful engineer in a hurry writes an aria-label that was not needed. The signal is the co-occurrence, not the habit.

one element, five habits at once

<div class="flex flex-col gap-4 space-y-4 p-4 px-4 py-4
            text-base leading-normal font-normal">
  <div>
    <div>
      <p aria-label="paragraph" role="paragraph">
        Unlock the power of seamless, cutting-edge solutions.
      </p>
    </div>
  </div>
</div>

<!-- gap-4 and space-y-4 do the same job and fight.
     p-4 is overridden twice by its own components.
     Two wrapper divs hold one child each.
     role="paragraph" is not a role.
     The sentence names no product and no outcome. -->

Why the calibration matters more than the rules

Any of those, on its own, is normal. A design system produces long class strings. A component library nests. A careful developer writes an aria-label because a screen reader needed it.

So the number that matters is not how many rules can fire, it is how the weighted total behaves on work that is unambiguously hand-written. The target was set the other way round from the obvious one: a tool that flags careful work is worse than no tool, because it teaches the reader to ignore it — and once ignored, it never catches the real thing either.

That is a harder direction to tune. Catching generated output is easy; leaving good work alone while still catching it is the whole engineering problem.

A score has to show its working

A number with no method behind it is an opinion wearing a lab coat. Every finding says what it measured — the count, the element, the threshold it crossed — and offers a concrete change.

This has a practical consequence: the score is arguable. Somebody who disagrees can point at the rule that fired and say why it is wrong in their case, and sometimes they will be right. That is the design working, not failing. A verdict nobody can interrogate is one nobody should act on.

It also sets the standard for us. If a rule cannot be defended when somebody pushes back on it, the rule comes out.

What a score cannot tell you

• Whether a model wrote it. There is no signature, and any tool claiming otherwise is selling certainty it cannot have.
• Whether the page is bad. A high score on a landing page that converts is a finding about maintenance cost, not about quality.
• Whether it was reviewed. Generated code that a person read, understood and kept is not a defect. The score measures texture, and texture survives review.
• Anything about the code you cannot see. This reads the rendered page. The repository behind it may be immaculate or may not exist.

The right reading of a high score is "this page has more of the habits than most" — and then the finding list, which is the part that is actually actionable.

What it is for

Not for judging other people's work — although that is what it will get used for, and pretending otherwise would be silly.

The use that pays: run it on a page you just shipped fast. The findings are a refactor list ordered by how much they cost, which is the list you were going to write by hand anyway, on the day you had no time to write it.

The permission list is the last honest moment between a user and an extension. After the install it is invisible; before it, it is the only thing that describes the code's reach. So the design question is not how to explain a broad permission well. It is whether the extension can be built without one.

This one is. host_permissions is empty in both the Chrome and the Firefox build. Four permissions are declared, and none of them names a website:

activeTab

One tab, from a click, until it navigates away.

storage

Settings and saved output, on this machine.

scripting

The mechanism that puts the inspection code into that one tab.

contextMenus

The right-click entry that opens it.

What activeTab actually grants

activeTab gives an extension access to one tab, starting from a user gesture, ending when the tab navigates away. It is not a weaker version of host access. It is a different shape: host access is standing permission to every matching page whether anybody is looking or not, and activeTab is a key that turns once.

Concretely: nothing runs until you click. The inspection code is injected into the tab you are on, at the moment you ask, and the grant dies with the navigation. There is no content script sitting in every page you open, and there is no background process reading tabs because they happened to be open.

The trade is real:

• It cannot act on page load.
• It cannot watch a page it was not invited into.
• It has to re-establish itself every single time.

The whole lifetime of the grant. It begins at a click, covers one tab, and ends at the next navigation - at which point the extension has to be invited again. — runs on the page itself.

Those are features here rather than costs — but they are constraints on what the product can be, and they were chosen before the code was written rather than worked around afterwards.

The three things that genuinely need more

Three settings cannot work under that model: opening the panel automatically on page load, a User-Agent switcher, and a WebRTC address control. Each needs a permission the four above do not cover.

So each one asks at the moment it is switched on, from the click that switches it, and hands the permission back when it is switched off. An optional permission is a different object from a declared one: it does not appear on the install screen, it is granted by a person who is looking at what they are enabling, and it is revocable without uninstalling.

A reader who never turns those on never grants them. That is the whole reason to build it this way rather than declaring the broad origin once and being done.

What the manifest looks like, and what to compare it against

The claim is checkable in about ten seconds, and it is worth knowing how — for this extension and for the next one you install.

the four lines that decide the install screen

{
  "permissions": ["activeTab", "storage", "scripting", "contextMenus"],
  "host_permissions": [],
  "optional_permissions": ["privacy"],
  "optional_host_permissions": ["*://*/*"]
}

The distinction that matters is between the second line and the fourth. host_permissions is granted at install, silently, forever. optional_host_permissions is an offer the browser will only accept from a click, it does not appear on the install screen, and it can be handed back without uninstalling anything.

Read your browsing history

Means tabs or a broad host match. An inspector does not need it: activeTab gives the URL of the tab you asked about, and nothing about the others.

Read and change all your data on all websites

Means <all_urls> or *://*/* in host_permissions. This is the one to refuse. It is standing access to every page, whether the extension is being used or not.

Read and change your data on sites you visit

The wording Firefox uses for the same thing. Softer sentence, identical grant.

No website permissions listed

What activeTab alone looks like on the install screen. It is rare, and it is the thing to look for.

What a page reading actually sends

Permissions describe reach; they say nothing about what leaves the machine. Those are separate promises and both have to be kept.

Inspection, extraction and the live editing tools run entirely in the browser and send nothing. A few readings do ask a server, each behind its own button. An audit sends counts rather than content — the hostname, the heading text and a set of numbers, with email addresses and long identifier strings redacted before anything leaves the page. Vulnerability dating sends detected package names and versions, with no hostname at all. The server-side readings send the page address with its query string removed, because asking a server to fetch a page cannot be done without naming it.

Input field values and body copy are never read. The field-by-field list is on the privacy page, and it is a list rather than a paragraph on purpose: a promise you cannot check is a slogan.

What it costs to build this way

Worth saying plainly, because an architecture described only by its benefits is a sales page.

• Nothing can be measured until you ask. No load-time metrics, no first-paint capture, no watching a page settle — anything that happened before the click did not happen for us.
• Every session starts cold. The panel re-injects on each invocation and rebuilds its view of the page, which costs milliseconds a resident content script would not spend.
• Some things are simply impossible. A feature that needs to observe a page it was not invited into cannot exist here, and several proposed ones did not.
• It is harder to explain than to do. "We only read the tab you asked about" takes a paragraph; "we can read every page" takes none, and most users never read either.

The trade is accepted because the alternative is unfalsifiable. A promise about what an extension does with broad access cannot be checked by the person granting it. A permission list can.

How to check any of this

Do not take the claim. The permission list on the store page is generated by the store from the manifest, not written by us, and it is visible before you install. If an extension's stated architecture and its permission list disagree, the list is the one telling the truth.

That applies to this one as much as to any other.