CSS sibling-index for Data-Driven Staggering

CSS sibling-index can turn each element's position among its siblings into a value for staggered layout, color rhythm, or optional motion without stamping an index into every node. The durable pattern bounds that value, keeps document order meaningful, and makes reduced motion stagger and unsupported browsers designed states.

CSS sibling-index is an input, not art direction

Start with a visual rule: cards alternate across a shallow baseline, dots scale through a bounded pulse, or captions receive a finite reveal delay. CSS sibling-index supplies the sequence position, but the designer still chooses amplitude, period, clamp, and stopping condition. An unbounded formula can move the 40th item off canvas or make a user wait seconds for content.

Define a maximum effective index such as min(sibling-index(), 8) where supported by the intended calculation. The rest of the collection settles into the final state. A staggered CSS layout should preserve readable alignment and hit targets before decoration. Sequence should reveal grouping, not make content look accidentally broken.

Synthetic contact-sheet fixture (not rendered performance data): use 40 cards with settled offset min(index − 1, 6) × 4 pixels and optional delay min(index − 1, 8) × 45 milliseconds. The expected computed value for card 40 is a 24-pixel offset and maximum 360-millisecond delay rather than 1.755 seconds; the runnable artifact substantiates those calculations.

Pair index with sibling count deliberately

The sibling-count CSS function can support normalized position, symmetric compositions, or rules that change with collection size. Use it when the total is part of the thesis, such as placing items along a complete arc. Do not use count to make foundational typography or spacing unpredictable whenever content changes. Annotate the intended collection range beside the formula for reviewers.

The CSS Values Level 5 tree-counting draft defines the emerging functions. Pin tested browsers and expect syntax or behavior to evolve. CSS sibling-index should remain a progressive input; the base layout needs ordinary values that survive when the function is invalid or unsupported. Treat support as versioned evidence.

Synthetic count fixture (not a browser capture): use sibling count only for hue interpolation while capping position and delay independently. Expected values resolve a one-card denominator to zero and place cards 1 and 40 at palette endpoints, while cards 10–40 share the bounded spatial amplitude.

Build a custom-property fallback contract

Give every item a default --i value and use the computed function only inside @supports when reliable feature detection exists. For essential sequence labeling or a design that truly needs exact positions in older browsers, the renderer can set a scoped --i custom property. Avoid data attributes whose only purpose is styling unless they are already meaningful application data.

The animatable custom-property tutorial shows how typed tokens can make interpolation safer. CSS sibling-index does not require JavaScript for the enhanced path, but a fallback may still be acceptable when explicit and finite. Test both paths so they do not drift into visibly different compositions.

Base CSS defines --i: 0, --offset: 0px, and --delay: 0ms, yielding a straight immediately visible list. The enhanced rule replaces --i with sibling-index() and derives the capped values. A server-rendered --i is deliberately rejected here because sequence is decorative; unsupported browsers should not pay markup complexity for it.

Separate layout rhythm from entry motion

Use index-derived translation, rotation, grid offsets, or color as a settled composition only when content remains legible and focus outlines stay visible. Use index-derived transition-delay for optional arrival, not to postpone availability. Interactive controls should be operable immediately even if a decorative inner layer is still moving.

The CSS starting-style guide provides an entry-state contract with interruption. CSS sequence effects should not turn delay into business state. CSS sibling-index can schedule a reveal, but a slow item must never be hidden from accessibility, pointer, or keyboard interaction merely because its animation slot has not arrived.

Synthetic motion fixture (not keyboard-test evidence): translate only an inner decorative panel by six pixels from 0.85 opacity while keeping the card link and focus ring in the settled box. Expected keyboard behavior reaches every link in DOM order, and interruption at card 7 leaves content at its final state instead of a hidden start style; these remain assertions for an actual browser run.

Run the bounded teaching fixture before adapting the pattern to production.

Runnable artifact — sibling-stagger-contract.test.mjs

import assert from "node:assert/strict";const values=(count,reduced=false)=>Array.from({length:count},(_,i)=>({offset:Math.min(i,6)*4,delay:reduced?0:Math.min(i,8)*45}));const many=values(40);assert.equal(many.at(-1).offset,24);assert.equal(many.at(-1).delay,360);assert.ok(values(40,true).every(x=>x.delay===0));console.log("PASS: stagger values remain bounded and reducible");

Run node sibling-stagger-contract.test.mjs. Expected receipt: PASS: stagger values remain bounded and reducible.

Make reduced motion a composed alternative

Under prefers-reduced-motion: reduce, remove index-derived delays and large travel. Preserve the settled spatial hierarchy when it is not motion-dependent, or simplify it if diagonal offsets make tracking harder. A reduced-motion stagger should not become a series of nearly instant flashes; set transition and animation to none or a genuinely calm state. Capture both preferences at identical viewport and content settings.

The WCAG animation from interactions guidance explains user-triggered motion considerations. CSS sibling-index may also drive ambient entrance on load, which still deserves restraint. Provide a static contact sheet so reviewers judge composition independently from animation charm and timing.

Synthetic reduced-motion target (not screenshot evidence): set every delay and duration to zero, remove the six-pixel entry translation, and retain a settled 0–24-pixel editorial offset. The expected 40-card first frame contains all content, while a future high-contrast check must verify that the shallow rhythm never separates text from its visible focus outline.

Keep DOM order and focus geometry stable

Do not combine sequence formulas with CSS order values that scramble the reading path. A translated item retains its layout box and focus position, so large offsets can make outlines overlap or pointer targets feel detached. Inspect keyboard navigation at 200 percent zoom and narrow width. Logical properties help the rhythm adapt to writing direction.

Use responsive content fixtures with long headings, missing thumbnails, validation messages, and 30-item collections. CSS sibling-index must not assume a hand-curated set of six perfect cards. Clamp offsets against container units and ensure overflow does not clip meaning or focus.

Synthetic responsive fixture (not viewport evidence): at 360 pixels, reduce the offset step from four to two pixels and the cap from six positions to three, for a six-pixel maximum. The acceptance targets at 200-percent zoom keep card 40 inside the scroller with four pixels around its outline, preserve DOM order and pointer geometry in both logical directions, and require a separate vertical-writing check.

Test insertion, filtering, and reordering

Insert a new first item, remove the middle, filter several entries, append a page, and sort by user preference. Every sibling after the mutation receives a new index, which may recompose color and motion unexpectedly. Decide whether that behavior is desirable. For persistent identity-based art, use a stable data seed instead of structural position.

The seeded randomness article distinguishes reproducible identity from list order. CSS sibling-index is ideal when sequence itself carries meaning, such as steps or editorial rhythm. It is wrong when an item's visual identity must survive movement between lists. Record that boundary in the component contract.

Synthetic mutation fixture (not an observed interface): insert a card at position 3 and expect later offsets and hues to recompute because rhythm belongs to sequence. Filtering to eight cards changes the final hue endpoint but keeps the 24-pixel spatial cap; reordering must use the same formulas without stale authored counters in markup.

Audit performance and visual restraint

Profile a production-sized collection on a modest device. Prefer transform and opacity for motion, but remember that many promoted layers can consume memory. Inspect style recalculation after list mutations and verify that the sequence formula stays understandable in developer tools. A clever nested calc is costly if nobody can tune it safely.

CSS sibling-index should reduce authored bookkeeping, not introduce a formula contest. Name constants such as --stagger-step, --stagger-cap, and --offset-step. Review the last visible item and the first capped item side by side. The transition should look intentional rather than revealing the exact point where the math stopped.

Synthetic performance budget (not a browser trace): for 40 items, target a 24-pixel maximum offset, 360-millisecond maximum delay, zero horizontal overflow, and no long task above 50 milliseconds. A ten-card insertion remains a proposed style-recalculation test rather than a claimed below-floor result. These guardrails are composition targets, and an actual run must record its browser build and measurements.

Ship a sequence recipe with receipts

Archive the base fallback, enhanced formula, supported browser matrix, content extremes, dynamic mutations, reduced-motion capture, keyboard path, zoom proof, performance trace, and design tokens. Include one rejected excessive recipe so future edits understand why amplitude and delay are capped. The MDN sibling-index reference can track current support while local tests prove the component.

Revisit CSS sibling-index when collection size, sorting, layout, motion policy, or browser implementation changes. The technique is successful when structural sequence becomes a useful visual input, every item remains immediately understandable and operable, and the fallback feels like the same design rather than a broken version.

Proposed recipe receipt (not an existing archive): generate base and enhanced CSS, normal and reduced-motion contact sheets, computed values for cards 1, 7, 9, and 40, insertion and filtering results, browser-version fields, and a 200-percent-zoom check. Those future outputs can evaluate a support change against the same targets while retaining a fallback image for comparison.