Skip to content

Commit c5f454b

Browse files
fix(lint): the negative-z hiding is conditional on an opaque root background
Reviewer's edge case, confirmed false rather than merely untested. The previous wording asserted the element "paints beneath an opaque ancestor background". Measured: with a TRANSPARENT composition root and nothing opaque above it, the same `z-index: -1` band renders at FULL coverage. So for that shape the message stated the opposite of what happens. The mechanism is now stated as fact and the hiding as conditional on what is actually there: paints the element behind its nearest stacking context's own content. With no stacking-context ancestor that context is the composition root itself, so an opaque background there hides it entirely: in the DOM, laid out, and absent from the picture. A transparent root leaves it visible. Detection is untouched. Three assertions pin the wording, including one that the transparent-root clause is present, so the narrower claim cannot drift back. Also fixes a dropped space in the previous revision's string concatenation ("entirelyand"), which is mine and was introduced in this PR. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
1 parent a366c3b commit c5f454b

2 files changed

Lines changed: 11 additions & 5 deletions

File tree

‎packages/lint/src/rules/composition.test.ts‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2220,8 +2220,13 @@ ${body}
22202220
),
22212221
);
22222222
const finding = result.findings.find((f) => f.code === "negative_z_index");
2223-
expect(finding?.message).toContain("unless an ancestor forms a stacking context");
2224-
expect(finding?.message).toContain("paints beneath an opaque ancestor background");
2223+
expect(finding?.message).toContain("behind its nearest stacking context");
2224+
// Reviewer's edge case: with a TRANSPARENT composition root the element is
2225+
// VISIBLE (measured), so the hiding must be stated as CONDITIONAL on an opaque
2226+
// background, never asserted outright.
2227+
expect(finding?.message).toContain("an opaque background there hides it");
2228+
expect(finding?.message).toContain("A transparent root leaves it visible");
2229+
expect(finding?.message).not.toContain("renders invisibly unless");
22252230
// The cause is painting order, not a tool failure. Both phrasings below imply
22262231
// the renderer dropped the element, which the pixels refute.
22272232
expect(finding?.message).not.toContain("is silently dropped");

‎packages/lint/src/rules/composition.ts‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -298,9 +298,10 @@ function negativeZIndexFinding(
298298
severity: "warning",
299299
...(selector ? { selector } : {}),
300300
message:
301-
`\`z-index: -${level}\` renders invisibly unless an ancestor forms a stacking context: it paints beneath an opaque ancestor background, ` +
302-
"so the element is in the DOM and laid out but absent from the picture. " +
303-
"Siblings at `z-index: 0` or above are unaffected.",
301+
`\`z-index: -${level}\` paints the element behind its nearest stacking context's own content. ` +
302+
"With no stacking-context ancestor that context is the composition root itself, so an opaque " +
303+
"background there hides it entirely: in the DOM, laid out, and absent from the picture. " +
304+
"A transparent root leaves it visible. Siblings at `z-index: 0` or above are unaffected.",
304305
fixHint:
305306
"Give the element's parent a stacking context - `isolation: isolate` is the cheapest, and " +
306307
"`transform`, `filter`, `opacity` below 1, `contain: paint` and `will-change` all work too. " +

0 commit comments

Comments
 (0)