Skip to content

Commit a366c3b

Browse files
fix(lint): the negative-z warning described a renderer defect that is CSS painting order
Corrects this rule's own premise. Behaviour unchanged: wording and comment only. The rule described a renderer defect. It is not one. Measured at 0.8.72: z-index:-1, opaque ancestor background above it ABSENT (zero coverage) z-index:-1, NO opaque background above it PRESENT (full coverage) same element with z-index deleted entirely PRESENT (full coverage) The element is painted in every case. Remove what is opaque above it and it appears; the sign of z-index only moves it in the stacking order. A negative-z descendant paints at step 2 of its nearest stacking context -- above that context root's own background, below the context's positioned in-flow content -- so a `position: relative` composition root carrying an opaque background paints over it. Ordinary CSS painting order, and it also explains why any stacking-context ancestor (isolation, transform, opacity<1, filter, contain:paint, will-change; all six measured PRESENT) makes it visible: the child then paints inside that ancestor's context, which itself paints above the root's background. So #4366's "does not render" is occlusion, not a drop, and the previous comment -- "whether negative stacking is in scope for the renderer is a design decision" -- was wrong: the renderer has no say in it. The rule stays, because authors do hit this and nothing explains it: the element is in the DOM, laid out, and invisible. What changes is that the message now names the CAUSE and the remedy instead of implying the tool failed. Two assertions pin that it cannot drift back, and the mutation goes red on exactly the four message checks. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
1 parent f35c9d5 commit a366c3b

2 files changed

Lines changed: 19 additions & 4 deletions

File tree

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2221,7 +2221,11 @@ ${body}
22212221
);
22222222
const finding = result.findings.find((f) => f.code === "negative_z_index");
22232223
expect(finding?.message).toContain("unless an ancestor forms a stacking context");
2224+
expect(finding?.message).toContain("paints beneath an opaque ancestor background");
2225+
// The cause is painting order, not a tool failure. Both phrasings below imply
2226+
// the renderer dropped the element, which the pixels refute.
22242227
expect(finding?.message).not.toContain("is silently dropped");
2228+
expect(finding?.message).not.toContain("zero exit code");
22252229
});
22262230

22272231
it("offers a stacking context as the measured remedy, not only DOM reordering", async () => {

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

Lines changed: 15 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -298,8 +298,8 @@ function negativeZIndexFinding(
298298
severity: "warning",
299299
...(selector ? { selector } : {}),
300300
message:
301-
`\`z-index: -${level}\` is dropped unless an ancestor forms a stacking context: the element then does not ` +
302-
"appear in `snapshot` or `render` output, with no error and a zero exit code. " +
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. " +
303303
"Siblings at `z-index: 0` or above are unaffected.",
304304
fixHint:
305305
"Give the element's parent a stacking context - `isolation: isolate` is the cheapest, and " +
@@ -706,8 +706,19 @@ export const compositionRules: Array<(ctx: LintContext) => HyperframeLintFinding
706706
// and `render`, while siblings differing only in the sign of z-index render
707707
// exactly (heygen-com/hyperframes#4366). lint, validate and render all exit 0
708708
// and report nothing, so the first suspicion falls on the author's own CSS.
709-
// A warning rather than an error: whether negative stacking is in scope for
710-
// the renderer is a design decision and is not settled here.
709+
// NOT A RENDERER DEFECT -- ORDINARY CSS PAINTING ORDER, measured at 0.8.72.
710+
// The element is PAINTED; it is simply painted beneath something opaque. Remove
711+
// every opaque background above it and the same `z-index: -1` band renders at
712+
// full coverage, identically to the same band with `z-index` deleted. A negative-z
713+
// descendant paints at step 2 of its nearest stacking context -- above that
714+
// context root's own background, but below the context's positioned in-flow
715+
// content -- so a `position: relative` composition root with an opaque background
716+
// paints over it. That is the shape #4366 reports; nothing is dropped and the
717+
// renderer has no say in it.
718+
//
719+
// Kept as a warning because authors hit it and nothing explains why: the element
720+
// is in the DOM, laid out, and invisible. The message therefore names the CAUSE
721+
// and the remedy rather than implying the tool failed.
711722
//
712723
// THE CONDITION IS LOAD-BEARING AND THE MESSAGE STATES IT. The element is only
713724
// dropped when its nearest ancestor stacking context is the composition root,

0 commit comments

Comments
 (0)