> ## Documentation Index
> Fetch the complete documentation index at: /llms.txt
> Use this file to discover all available pages before exploring further.

# Time elements with data attributes

> Place clips on the HyperFrames timeline without putting timing logic in JavaScript.

HyperFrames keeps timing in HTML. A timed element normally needs a stable ID,
a start, a duration, and a track:

```html
<section id="headline" class="clip" data-start="0" data-duration="3" data-track-index="1">
  Launch day
</section>
```

| Attribute | What it controls |
| - | - |
| `data-start` | When the element enters the composition timeline |
| `data-duration` | How long its timeline slot lasts |
| `data-track-index` | Which browser editor lane displays it (optional; the render ignores it) |

Add `class="clip"` to timed DOM and image elements. The runtime keys visibility
off `data-start` rather than the class, but the shared `.clip` rule is what gives
a scene its full-frame box. Video visibility is managed by the media runtime;
audio has no visual lifecycle.

## Tracks are not layers

Tracks are the rows the browser editor draws. They do not decide which element is in front,
and they do not schedule anything. Use CSS `z-index` for paint order.

Two clips on one track may overlap; the render composites both. Separate tracks
keep an intentional overlap, such as a crossfade, readable in the browser editor:

```html
<video
  id="intro"
  data-start="0"
  data-duration="4"
  data-track-index="0"
  src="./intro.mp4"
  muted
  playsinline
></video>
<section id="result" class="clip" data-start="intro - 0.5" data-duration="3" data-track-index="1">
  The result
</section>
```

### Keep negative layers inside their parent

A negative `z-index` is valid CSS, but it can put a clip behind an opaque
ancestor background when its parent does not create a stacking context. For
example, this backdrop can be covered by the root's background:

```css
#root {
  position: relative;
  background: #0a0a0a;
}
#backdrop {
  position: absolute;
  inset: 0;
  background: #f5e6c8;
  z-index: -1;
}
```

Add one property to keep the backdrop above its parent's background and below
foreground siblings:

```css
#root {
  isolation: isolate;
}
```

`isolation: isolate` creates a local stacking context. The backdrop becomes
visible in the browser, `snapshot`, and `render`; siblings at `z-index: 0` or
above can still cover it. You can also use an earlier background sibling and
raise foreground elements with non-negative `z-index` values.

`hyperframes lint` reports `negative_z_index` as a warning based on CSS text.
It can still warn when an ancestor already creates a stacking context, so
verify the visible result rather than treating every negative value as invalid.

## Start relative to another clip

A numeric `data-start` is an absolute time in seconds. A clip ID means “start
when that clip ends.” Add or subtract seconds for a gap or overlap:

```html
data-start="intro" data-start="intro + 0.5" data-start="intro - 0.5"
```

References resolve only inside the same composition. The referenced clip must
have a known duration, and reference chains cannot contain a cycle.

## Media and nested compositions

Media can also declare a source offset, playback rate, and volume. A nested
composition adds a source path and its own fixed timeline window. These are
exact contracts rather than new timing models.

Use the [HTML schema reference](/reference/html-schema.md) for every supported
attribute and element-specific rule. Use [Compositions](/concepts/compositions.md)
to decide when a scene should become a separate composition.