Debug a front-end CSS or layout misbehavior
Load desktop-theme-probing before hand-rolling a probe; it defines the host’s
and the target’s platform file that this skill cites by section. For a
positioned box, a popover or an anchored box that lands wrong or grows the page,
read references/positioning.md: §1 for what the
box resolves against, §2 for the top layer, §3 for anchors.
Also load desktop-theme-tokens when a length comes from a design token, and
desktop-theme-screenshots when the result needs showing on the bug, or to
sample a reporter’s screenshot once the live measurements run out (its §6 “Read
a reporter’s screenshot by sampling it”).
1. Sweep the environment, not just the CSS
A document in the source tree backs this skill:
docs/code-quality/coding-style/css_guidelines.md. It’s kept up to date with
how different parts of the code base interact in non-obvious ways; it may differ
from what you remember. Before the sweep, read its “Chrome versus in-content”
and “UI density” sections. This skill builds on them and does not repeat them;
desktop-theme-tokens §5 covers rem-valued tokens.
Sweep these from the chrome context and emit one row per cell:
System font size.
document.documentElement.style.fontSize, on the root, notbody. Sweep the span of the platforms’ chrome roots, about 11px to 15px. Section FONT of each platform file (desktop-theme-probing) gives the target’s size and how to read the host’s. Popups keep their own font size (css_guidelines “Chrome versus in-content”): set it on the popup too, and read an item’s computedfont-sizeback. Before sweeping this axis on an in-content page, check whether the page sets its own root font size.Scrollbars.
ui.useOverlayScrollbars: 1 overlay, 0 classic; set it at launch, since a live change notifies only media queries (bug 2090576), and read it back in each cell (references/environment-sweep.md§3). Each platform’s default is in its platform file (desktop-theme-probing), section SCROLLBARS. A classic scrollbar takes width from the box; an overlay one does not.Compositing. Where the target’s platform file (
desktop-theme-probing), section COMPOSITING, names a media query that compositing decides, sweep both sides of it and read the query back in each cell; that section has the pref and how to take the paint.DPI / scaling.
layout.css.devPixelsPerPx, a string pref;"-1.0"restores auto. It takes effect headless, at launch or on the running instance. Sweep 1.25, 1.5 and 1.75 in both realms, with 1 and 2 as controls, and readdevicePixelRatioback in every cell, since a cell that reads 1 measured nothing. §2 “Device pixels” says which changes need this axis.UI density.
browser.uidensity: 0 normal, 1 compact, 2 touch; live. A cell that does not move the box is not evidence the pref was ignored; read the computed value of each declaration the changed[uidensity]selectors set (amin-heightthe content already exceeds moves nothing). Set the pref explicitly; under Nova a short window compacts itself otherwise (css_guidelines “UI density” gives the thresholds). An in-content page has nouidensityattribute.Writing direction.
intl.l10n.pseudoset tobidi; wait until:-moz-locale-dir(rtl)matches on the root before measuring, and clear it afterwards. Read where the text lands from aRangeover the label’s contents (selectNodeContents, thengetBoundingClientRect()): a label that fills its box has the same element rect whichever edge its text starts from. Repeat with text in the opposite direction to the UI (Hebrew in an LTR UI, Latin in RTL) for an element withdir="auto", a<bdi>orunicode-bidi: plaintext(docs/code-quality/coding-style/rtl_guidelines.md, “Testing”).Script. Set the label text to a few writing systems and re-measure.
Full-page zoom.
ZoomManager.setZoomForBrowser(browser, 1.5)scales the content document and leaves chrome alone; read both sides.
Run the sweep with the loop from §1 “The loop” in
references/environment-sweep.md. Before
calling a relocation neutral on the strength of a matching table, read §4 “What
the sweep misses” there: changes that resize or reparent descendants while the
box’s own rect stays put.
The sweep covers the environment, not the product’s own states. List the
attributes the changed selectors key on (e.g. [open], [checked],
:focus-within) and measure each state through the entry point the product uses
for it. When a declaration moves under a narrower selector, also measure the
elements the new selector no longer matches, which lose the declaration; when
one moves under a wider selector, measure the elements it newly matches, which
gain it. Enumerate either set with desktop-theme-probing’s
references/probe-recipes.md §8.
The sweep also covers every surface and branch the changed declarations reach.
When a patch redefines or moves a custom property, list the sheets that read it
(desktop-theme-tokens §2 has the search) and measure each surface they style,
on every branch behind a pref or platform condition, not only the one the bug
names. Report a move the bug doesn’t name as a finding with its measurement,
even one you judge harmless: scoping the change is the author’s call. An
unregistered custom property reads back as its unresolved calc() text, so
measure a length variable by setting it as a probe element’s width.
The font axis usually finds a px box holding em text. Report the threshold:
“the button outgrows its 20px slot from a 13px root font
upwards” names the affected platforms.
A per-monitor difference is rarely a per-monitor cause: the compositor’s scale
factor is not what chrome CSS sees. Read devicePixelRatio and the computed
root font-size from a window on each monitor before theorising about physical
DPI or rotation.
2. Device pixels
Before judging a length against the display scale, read css_guidelines “HDPI
support” with “Some properties are rounded to device pixels, but not others”,
and “Chrome-only media features go by the stylesheet, not the document” before
measuring env(hairline).
Do the arithmetic with the ratio a cell reads back, not the pref’s value (css_guidelines “Some properties are rounded to device pixels, but not others” says why 1.75 runs at 1.7647). In content, a full-page zoom other than 100% changes the ratio too.
Some widths snap and the rest do not. The same css_guidelines section lists them; read
layout.css.outline-offset.snappingon the build, since its default differs by channel. Insets andbox-shadowspread do not snap either.Sweep the ratios for any length that is not a whole number of device pixels at some ratio, and for any swap between a snapped and an unsnapped length. Trading a border for padding, a 1px background box for a border, or a border for an outline plus
outline-offsetresizes the box and moves everything after it (css_guidelines “Some properties are rounded to device pixels, but not others”). No unit is exempt, nor around()to a CSS-pixel step; only anenv(hairline)step lands on device pixels.Measure
env(hairline)from achrome://orresource://sheet. In any other sheet, such as adata:orfile://scratch page oruserChrome.css, it has no value and the declaration acts asunset(css_guidelines “HDPI support” says what that computes to). Before reducing it to a scratch page, readreferences/environment-sweep.md§3 “What each axis does to a box”, under “DPI / scaling”.Fixed-size content centered in a box sits off center wherever (box − content) / 2 is not a whole number of device pixels. That covers an icon, image, checkbox or badge centered by flex or grid alignment, auto margins or symmetric padding. Read the content’s offset inside its box, times
devicePixelRatio, at each ratio. Layout reports the same fractional gap on both sides, which looks centered; paint snaps each edge, so a gap of 3.5 device pixels paints as 3 on one side and 4 on the other. Judge whether the offset is whole, not whether the two sides match.No CSS value snaps a position. An edge sits at the sum of the lengths before it, so a snapped width after a fractional offset still lands mid-pixel. Reproduce a sub-pixel artifact with a fractional nudge before attributing it to the realm, the top layer or a transform.
Paint rounds each edge of a background, a border, an overflow clip and a
clip-path: inset()to a device pixel, so sample the pixels along a shared edge at each ratio before adding anything to cover it. Two clips at one layout coordinate round to the same device pixel at every offset and ratio, so exactly one box paints each pixel along the edge. Shifting both clips by the fractional remainder of the shared edge’s coordinate in device pixels opens a gap, because each fractional inset resolves against its own snapped border box.
3. Keep the line box and the ink apart
Judge overflow by what paints. normal leading puts several pixels of air
above the ascender and below the descender, so a 21px line box in a 20px button
shows nothing wrong.
Find what clips before turning it off. A clip comes from overflow other
than visible, contain: paint (or strict, content,
content-visibility), clip-path, or the UA rule that gives img, canvas,
video and XUL image overflow: clip; overflow-clip-margin: content-box. An
overflow clip sits at the edge overflow-clip-margin names (the padding box by
default) and follows border-radius inset to that edge, so a large radius with
padding cuts the corners of a replaced element’s content. It also clips a
descendant’s decoration, such as a background at a negative inset or its
box-shadow, while getBoundingClientRect still reports the full box.
overflow-clip-margin widens the clip for content and decoration alike under
overflow: clip or contain: paint, and on a replaced element (e.g. img,
video, iframe) under any overflow other than visible; a scroll
container ignores it.
A computed border-radius can overstate the rendered corner. When the radii
along one side of a box add up to more than that side, CSS scales every radius
of the box down by one factor, so for a uniform radius the corner renders at
min(r, height / 2, width / 2) while getComputedStyle still reads r. Print
the box’s rect beside every radius you read, and derive the rendered radius from
both. A rounded item inside a rounded container is concentric when the
container’s rendered radius equals the item’s rendered radius plus the gap from
the item’s edge to the container’s outer border edge, the border width included
in that gap.
Diff what paints against what would paint unclipped: render the region, turn
off every ancestor that clips at that edge (overflow: visible, clip-path: none or contain: none, whichever applies), render again, and compare the two
pixel buffers. Rows that differ are what the clip removes. Several ancestors
often clip at one edge, and turning off only the nearest shows no differing rows
while the ink stays clipped, so list them first by walking
flattenedTreeParentNode up from the clipped box. When the clipped ink is a
border, outline or shadow, read its color in each regime of
desktop-theme-colors §6 before calling a branch unaffected: a diff where that
ink is transparent shows nothing, and forced colors or a prefers-contrast rule
can make it opaque. Pair it with a positive control, the same comparison in a
configuration that certainly overflows (e.g. a larger font, a larger offset or
outline width). In chrome the capture is one privileged ctx.drawWindow() call
returning counts; before trusting its pixels, read desktop-theme-probing’s
references/measuring-pixels.md §1 “Chrome and content canvases” for what it
does not composite.
Clamp the container, not the line box. A line-height below normal
discards the font’s own metrics, and an element with a non-visible overflow
(which text-overflow: ellipsis requires) clips at its own edge, not the
visible container’s. For each script, measure the label’s box height against the
nearest ancestor that clips.