reveal

<!-- .sk-reveal is a utility, not a wrapper. Put the class on the thing you want
     revealed; there is no container element and nothing to nest.

     Nothing here is interactive and nothing changes the accessibility tree:
     the animation only ever touches opacity, translate and scale, so the
     content is announced whether or not it has been scrolled to. A reveal that
     removed content from the tree until it was reached would be a
     screen-reader trap, and this pattern must never become one.

     .sk-reveal__stack is only a flex column for the demo's spacing. It is
     deliberately NOT a scroll container: view() binds to the nearest ancestor
     scroll container, so wrapping these in an `overflow: auto` box that does
     not happen to overflow leaves the timeline inactive and nothing animates
     at all. The scrollport is the page — which is what a consumer has anyway,
     so the utility needs no wrapper of its own. -->
<div class="sk-reveal__stack">
  <p class="sk-reveal__hint">Scroll down ↓</p>

  <section class="sk-reveal" data-reveal="slide-up">
    <h3 class="sk-reveal__title">Slide up</h3>
    <p class="sk-reveal__text">Rises into place as it enters the scrollport.</p>
  </section>

  <section class="sk-reveal">
    <h3 class="sk-reveal__title">Fade</h3>
    <p class="sk-reveal__text">The default. Opacity only, nothing moves.</p>
  </section>

  <section class="sk-reveal" data-reveal="scale">
    <h3 class="sk-reveal__title">Scale</h3>
    <p class="sk-reveal__text">Settles up to full size from slightly under it.</p>
  </section>

  <section class="sk-reveal" data-reveal="slide-up">
    <h3 class="sk-reveal__title">And again</h3>
    <p class="sk-reveal__text">
      In Firefox, and under reduced motion, every one of these is simply here.
    </p>
  </section>

  <!-- Both at once: this rises in on the way up the scrollport and fades out
       on the way off it. One element, two animations, one stylesheet. -->
  <section class="sk-reveal" data-reveal="slide-up" data-reveal-exit="slide-up">
    <h3 class="sk-reveal__title">In, then out</h3>
    <p class="sk-reveal__text">
      An entrance and an exit on one element. Two components could not do
      this — animation-name is a single value, so whichever stylesheet
      loaded second would win and the other would silently vanish.
    </p>
  </section>

  <!-- The stagger goes on the PARENT. Each child starts later in the range —
       not later in time, which would do nothing on a scroll timeline. -->
  <div class="sk-reveal__group" data-sk-reveal-stagger>
    <section class="sk-reveal" data-reveal="slide-up">
      <h3 class="sk-reveal__title">First</h3>
      <p class="sk-reveal__text">Begins at the start of the range.</p>
    </section>
    <section class="sk-reveal" data-reveal="slide-up">
      <h3 class="sk-reveal__title">Second</h3>
      <p class="sk-reveal__text">One step later.</p>
    </section>
    <section class="sk-reveal" data-reveal="slide-up">
      <h3 class="sk-reveal__title">Third</h3>
      <p class="sk-reveal__text">Two steps later. In Firefox all three are simply here.</p>
    </section>
  </div>
</div>

/* .sk-reveal — reveal-on-scroll, driven by the scroll position itself.

   A view() timeline ties an animation's progress to where the element sits in
   the scrollport, so there is no observer, no scroll listener and no script.
   The browser is already tracking this; the animation just reads it.

   THE RULE THIS FILE EXISTS TO OBEY: content is never hidden by a feature that
   might not be there. Every declaration that reduces opacity or moves an
   element lives inside @keyframes, and those keyframes are only ever attached
   inside BOTH `@supports (animation-timeline: view())` and
   `@media (prefers-reduced-motion: no-preference)`. There is no `opacity: 0`
   at the top level of this file, and there must never be one — that is the
   classic way this pattern fails, and it fails silently: the content is in the
   DOM, in the accessibility tree, and invisible.

   Firefox 153 does not support view() timelines (measured 2026-08-20), so this
   is not a hypothetical fallback — it is what a third of the engines this kit
   tests actually render.

   Specs:
   - animation-timeline ..... https://drafts.csswg.org/scroll-animations-1/#animation-timeline
   - view() ................. https://drafts.csswg.org/scroll-animations-1/#view-notation
   - animation-range ........ https://drafts.csswg.org/scroll-animations-1/#animation-range */

/* Public theme knobs (ADR 0011). Read, never declared, so the nearest
   declaration above the component wins.

   These are declared on the element itself rather than a wrapper: a utility is
   applied directly to whatever it reveals, so it has no root of its own. */
.sk-reveal {
  --_distance: var(--sk-reveal-distance, var(--sk-space-lg));
  --_card-bg: var(--sk-reveal-card-bg, var(--sk-color-surface));
  --_card-fg: var(--sk-reveal-card-fg, var(--sk-color-text));
  --_card-border: var(--sk-reveal-card-border-color, var(--sk-color-border));
  --_card-radius: var(--sk-reveal-card-radius, var(--sk-radius-lg));
  --_text-fg: var(--sk-reveal-text-fg, var(--sk-color-text-muted));
  --_scale-from: var(--sk-reveal-scale-from, 0.94);
  --_range-start: var(--sk-reveal-range-start, entry 10%);
  --_range-end: var(--sk-reveal-range-end, entry 70%);
  --_exit-range-start: var(--sk-reveal-exit-range-start, exit 0%);
  --_exit-range-end: var(--sk-reveal-exit-range-end, exit 100%);
  --_exit-distance: var(--sk-reveal-exit-distance, var(--sk-space-lg));

  /* The card look is demo dressing, folded in here so the utility has a single
     rule rather than a second .sk-reveal further down. */
  padding: var(--sk-space-md);
  border: var(--sk-border-width) solid var(--_card-border);
  border-radius: var(--_card-radius);
  background: var(--_card-bg);
  color: var(--_card-fg);
}

@media (prefers-reduced-motion: no-preference) {
  @supports (animation-timeline: view()) {
    /* Longhands, not the `animation` shorthand: the shorthand resets
       animation-duration to 0s, and a zero-duration scroll-driven animation
       finishes instantly — every element renders at its end state and the
       reveal silently does nothing. `auto` hands timing to the timeline.
       `both` holds the element at the start of its range while still below
       the fold — safe only here, where the timeline is guaranteed to run.

       The NAME is a custom property, not a literal, so this rule carries a
       two-item list: an entrance and an exit, each with its own range. A
       literal name per variant would need one rule per combination — nine,
       once the exit variants below are added. `none` is a valid, inert
       animation-name, so an element with no exit still runs exactly one
       animation. */
    .sk-reveal {
      --_enter-name: sk-reveal-fade;
      --_exit-name: none;

      animation-name: var(--_enter-name), var(--_exit-name);
      animation-duration: auto, auto;
      animation-timing-function: linear, linear;
      animation-fill-mode: both, both;
      animation-timeline: view(), view();
      animation-range: var(--_range-start) var(--_range-end), var(--_exit-range-start) var(--_exit-range-end);

      /* THE STAGGER, AND WHY IT IS NOT animation-delay: a scroll-driven
         animation has no wall clock — progress is position, not time — so
         animation-delay does nothing, the wall every consumer hits before
         deciding scroll-driven CSS is broken. Sequencing siblings means
         starting each one LATER IN THE RANGE, hence a percentage step, not
         a duration.

         --_i is 1 unless supplied: the @supports below hands it
         sibling-index(), a consumer can override with --sk-index per child, and
         with neither every child offsets by zero and the group just
         animates together — it still runs, it just does not sequence.

         --sk-index, not --sk-reveal-index: a child's index among its
         siblings is a property of the markup, not of this component, and
         `entrance` reads the same property for the same purpose. It is a
         page-level property (ADR 0030), not a `--sk-reveal-*` theme knob, so
         it has no row in the Theming table below and check-theme-api.mjs
         does not see it.
         https://drafts.csswg.org/css-values-5/#sibling-functions */
      --_i: var(--sk-index, 1);
      --_stagger-step: var(--sk-reveal-stagger-step, 8%);
    }

    .sk-reveal[data-reveal="slide-up"] {
      --_enter-name: sk-reveal-slide-up;
    }

    .sk-reveal[data-reveal="scale"] {
      --_enter-name: sk-reveal-scale;
    }

    @supports (animation-range-start: entry calc(1% + sibling-index() * 1%)) {
      .sk-reveal {
        --_i: var(--sk-index, sibling-index());
      }
    }

    /* Only the entrance's START moves — its end stays put, so a late child
       gets a shorter range and catches up rather than overrunning the
       scrollport. `entry 10%` repeats --_range-start's default rather than
       reading it: animation-range-start needs a name plus an addable
       percentage, and --sk-reveal-range-start holds both as one opaque
       value. A consumer who overrides that knob and also staggers gets the
       stagger's own base, not theirs — see the README.

       TWO ITEMS, MATCHING animation-name's LIST LENGTH, NOT ONE: CSS repeats
       a short coordinating list (animation-range-start included) up to
       animation-name's length, so a one-item value here would not just set
       the entrance's start — it would repeat onto the exit animation too,
       silently overwriting --_exit-range-start with the stagger's own
       start for every staggered child. That was invisible while
       --_exit-name was `none`, because a `none` animation has nothing to
       clobber; it stops being invisible the moment a real exit variant is
       added, and reads as a mystery bug in the group that already went
       through review here. Write the exit's own start explicitly so it
       survives the stagger. */
    [data-sk-reveal-stagger] > .sk-reveal {
      animation-range-start: entry calc(10% + (var(--_i) - 1) * var(--_stagger-step)), var(--_exit-range-start);
    }

    /* The exit. The two-item animation-name list above means these set one
       property rather than a whole animation, so an element can carry an
       entrance and an exit at once without a rule per combination. */
    .sk-reveal[data-reveal-exit] {
      --_exit-name: sk-reveal-exit-fade;
    }

    .sk-reveal[data-reveal-exit="slide-up"] {
      --_exit-name: sk-reveal-exit-slide-up;
    }

    .sk-reveal[data-reveal-exit="scale"] {
      --_exit-name: sk-reveal-exit-scale;
    }

    /* An element already on screen when the page loads is past its range, so
       it renders at the end state — no flash, nothing to wait for. */
    @keyframes sk-reveal-fade {
      from {
        opacity: 0;
      }
    }

    @keyframes sk-reveal-slide-up {
      from {
        opacity: 0;

        /* Logical: translate is physical, so the offset is written against the
           block axis and flips with the writing mode. */
        translate: 0 var(--_distance);
      }
    }

    @keyframes sk-reveal-scale {
      from {
        opacity: 0;
        scale: var(--_scale-from);
      }
    }

    @keyframes sk-reveal-exit-fade {
      to {
        opacity: 0;
      }
    }

    @keyframes sk-reveal-exit-slide-up {
      to {
        opacity: 0;
        translate: 0 calc(-1 * var(--_exit-distance));
      }
    }

    @keyframes sk-reveal-exit-scale {
      to {
        opacity: 0;
        scale: var(--_scale-from);
      }
    }
  }
}

/* ---------------------------------------------------------------------------
   Presentation, not behaviour

   Everything below dresses the demo. The animation above is the whole
   component and it does not care what it is attached to — delete these rules
   when applying .sk-reveal to your own markup.
--------------------------------------------------------------------------- */

.sk-reveal__title {
  margin-block-end: var(--sk-space-2xs);
  font-size: var(--sk-text-md);
  letter-spacing: var(--sk-tracking-tight);
}

.sk-reveal__text {
  margin: 0;
  color: var(--_text-fg);
  font-size: var(--sk-text-sm);
}

/* Just a stack. Deliberately NOT a scroll container: `view()` binds to the
   nearest ancestor scroll container, so an `overflow: auto` wrapper that
   happens not to overflow becomes an inactive timeline and the reveal silently
   never runs — measured, and the reason this is a plain flex column. The
   scrollport is the page, which is what a consumer has anyway. */
.sk-reveal__stack {
  display: flex;
  flex-direction: column;
  gap: var(--sk-space-2xl);
  padding-block-end: var(--sk-space-3xl);
}

.sk-reveal__hint {
  margin: 0;
  color: var(--sk-color-text-subtle);
  font-size: var(--sk-text-xs);
}

.sk-reveal__group {
  display: grid;

  /* auto-fit, not a fixed repeat(3, 1fr): the fixed form crushed each column
     to nothing at a narrow viewport instead of reflowing to fewer of them.
     No media query needed — the docs suite tests pages at 320px, and this
     wraps to a single column there on its own. Same house style as card.css. */
  grid-template-columns: repeat(auto-fit, minmax(min(100%, 14rem), 1fr));
  gap: var(--sk-space-md);
}