---
title: RFC — Eidos depth engine
type: rfc
audience: human + agent
status: implemented — phases 1-5 ✅
source: migrated from src/uix/eidos/DEPTH_ENGINE_RFC.md (2026-07-02, docs-book F7.4)
---

# RFC — Eidos depth engine

> Sibling of [`rfc-color-engine.md`](./rfc-color-engine.md) and
> [`rfc-typography.md`](./rfc-typography.md). Takes the **depth** channel
> (`depth/presence` from the book *Diseñando lo que ocurre*) to reference-grade
> by **breaking** the references' model, not copying it — with the **open cage**.

## 0. Thesis

> **Depth is not something an element _has_; it is something that _happens_.**

An overlay does not "have elevation 4": it **states an emergence** — it ascends
to a front plane on appearing, recedes on leaving — governed by the **same sema
event** that already drives its motion/sound/haptic. Depth becomes a
**first-class expression channel** (one of the book's 8), **unified** (a single
notion coheres surface + shadow + z + atmosphere), **eventful** (fired by the
sema engine) and with an **open cage** (strong default, doors at every layer).

## 1. The survey — how the references do it and where they stop

| Framework | Model | Structural limit |
|---|---|---|
| **Material 3** | elevation = tonal tint + shadow, `dp` scale 0–5 | `dp` = physical height with 1 light source; elevation is a component **property**, not the expression of a happening; fixed scale |
| **Tailwind** | flat `shadow-sm…2xl` presets | no mode (the shadow *lies* in dark), no surface, no semantics |
| **Apple / SwiftUI** | materials (blur/vibrancy) + subtle shadow | platform-bound (backdrop), not a portable token system |
| **Polaris / Carbon / Radix** | shadow scale by role or number | static; fixed role, detached from events |

**Common limit** (even M3, the finest): depth = **a static property you assign**
+ **a skeuomorphic light model** + **disconnected** from what happens and from
its own signals. Nobody treats depth as the **expression of a happening**. And
everyone picks a side: Tailwind = flexible **without opinion**; Material =
**strong opinion but closed cage**.

## 2. Where Eidos stands today (already above average, but not novel)

- **z-index** in semantic bands: `base · raised · sticky · dropdown · popover · tooltip · modal · toast`. ✓
- **Tonal, mode-aware surface ladder**: `surface-default→raised→overlay` =
  `neutral-1→2→4` (in dark, "higher" = lighter — M3's tonal overlay, already present). ✓
- **Role-named shadows**: `shadow-subtle/raised/overlay` (→ `shadow-1/3/5`),
  per-theme set (`THEME_BASE_DARK_SHADOW`). ✓ (above Tailwind)
- **BUT** they are **3 separate systems** (you pick shadow + surface + z by
  hand), depth is **static** (a prop) and the model is still the skeuomorphic
  shadow one. You are ~on par with M3.

## 3. The novel model — 4 pieces

1. **Unified semantic plane** — `flush · raised · overlay · modal · recessed`.
   One level coheres surface + shadow + z + (blur) at once. Named by
   **role in the attention hierarchy**, not by millimeters.
2. **Mode-adapted, _computed_ multi-signal mix** — light leans on shadow; dark
   on surface tint + halo (the shadow lies in dark). Shadows derived from the
   **surface color in OKLCH** (not flat black-alpha), reusing the color engine.
   Solves the shadow-in-dark problem at the root.
3. **_Eventful_ depth (the genuinely new part)** — a channel the **sema** engine
   fires, like sound/haptic: `emerge`→rises, `contact`→sinks, `signal/threat`→
   pushes to the front; coordinated with motion's **two-moments** model.
4. **Atmosphere / presence** — backdrop-blur (frost) on the plane; the modal
   *veil* is component-owned (`--{component}-overlay-*` / `--color-overlay`), not
   a plane cue: what is in front blurs/dims what recedes (overlap with the
   *presence* channel).

## 3.bis The two moments of depth

Depth respects the framework's **two-moments model** (motion F1) — it does not
reinvent it. Eidos already reads both axes; depth adds its layer to each:

| Moment | Attribute (axis) | For depth | Phase |
|---|---|---|---|
| **state** | `data-state` (persistent · soma/morfo) | the **resting plane** — `data-depth='{plane}'`: where the element *is*. Eidos applies it as a state *preset*. | 1 ✅ |
| **event** | `data-event-*` (transient · sema, during the `hold`) | the **ascent / recession** — a *depth signature* on `emerge`/`contact`: what *happens*. Ordered by `sequence`, next to the motion signatures. | 3 |

That is why an overlay **has** a plane (state) **and ascends** to it (event) —
the two moments, never collapsed into one. The depth channel is a new channel
**expressed through the same model** motion already uses: the book's rigor
(event ≠ state) carried to depth.

## 4. Doctrine — _strong default, open cage_

> The semantic layer is **additive** over primitives that **never disappear**;
> the set, the mix and the channel are **extensible/overridable** via config +
> sema's open registry.

| Piece | Strong default | Open door |
|---|---|---|
| **planes** | canonical set (5) | the **set is config-driven** (`EidosConfig.depth.planes`); add `sheet`/`peek`, rename — not a closed enum |
| **mix** | computed mix per plane | **retune the mix per plane** in config; **per-component override** of any signal; the **primitives stay** (`--shadow-N`, `z-index`, raw `box-shadow` one step away) |
| **eventful channel** | `emerge↑ / contact↓` | **opt-in/opt-out** (like sound+haptic); rules in **sema's open registry** (declaration merging + appendable cascade → the app adds/overrides the event→depth map); **degrades with `prefers-reduced-motion`**; static depth **works without the channel** (eventful is additive, never a wall) |
| **atmosphere** | frost (blur) on the plane, opt-in via `data-frost` | amount in config; per-overlay **opt-out**. The modal *veil* is component-owned (`--{component}-overlay-*` / `--color-overlay`), not a plane cue — scrim cue pruned 2026-07-12 |
| **whole system** | canonical theme | runtime **`applyDepth(seed)`** (sibling of `applyColorScheme`/`applyTypeScale`) |

None of this is **new to the framework**: it is exactly how sema (open
registry), eidos (config + `setCssVariables` + recipe overrides) and
color/typography (retintable canon + runtime builders) already operate. Depth
inherits the same openness contract.

## 5. Token contract (additions, frozen)

Bare-prefixed by system (`--depth-…`). The plane is a **named bundle** that
**composes the existing primitives** — it does not replace them:

```
--depth-{plane}-surface   → var(--color-surface-{…})   (tonal tint, mode-aware)
--depth-{plane}-border    → var(--color-border-{…})     (bordered elevation · A1/Decisión 8)
--depth-{plane}-shadow    → var(--shadow-{…})           (drop, mode-aware via theme)
--depth-{plane}-halo      → oklab rim-light            (dark-mode lift · Phase 2)
--depth-{plane}-z         → var(--z-index-{…})          (band — EXPOSED, never painted)
--depth-{plane}-blur      → frost backdrop-blur (Phase 4 ✅ · opt-in via data-frost)
```

> **Amendment 2026-07-12** — the `--depth-{plane}-scrim` cue was **pruned** from
> this contract (removed from `DepthPlane` / `DEPTH_CUES` / validation / emitter).
> It was declared but never seeded, emitted or read — a write-surface with no
> reader (`applyDepth({p:{scrim}})` silently no-op'd). The modal veil lives, by
> the standing decision, in the component overlay layer (`--{component}-overlay-*`
> tinted by `--color-overlay`) — matching MD3 (`md.sys.color.scrim`), Radix
> `Dialog.Overlay`, Vaul: none put the veil on an elevation cue. Unlike the `z`
> cue (kept as an exposed-but-unpainted open cage — it varies per plane and is
> unpaintable-forever), scrim had no per-plane variance and its only "cage" would
> duplicate the existing `--color-overlay` role (a token alias). Re-add whole only
> alongside a real backdrop rule.

Consumption (canonized 2026-07-06 — the A1/"Decisión 8" wave, 06-19→22,
originally recorded in the archetype-coherence audit and never absorbed here):
`[data-depth='{plane}']` paints the **appearance bundle** — `background`
(when the plane declares a surface), `border` (`var(--border-width) solid
var(--depth-{plane}-border)` — the **bordered-elevation** model, Radix/shadcn
side of the field, vs M3's tonal-only: in light the subtle shadows need the
border to separate planes; in dark, where the shadow lies, border + halo carry
the boundary), `box-shadow` (drop + halo), and the **on-surface typographic
baseline** (`font-family: var(--style-label-font-family)`;
`line-height: var(--leading-ui)`)
so portaled surfaces never fall back to the browser serif — the functional
equivalent of Radix re-wrapping portals in its Theme class, with the plane
attribute as the surface marker. It is a BASELINE, not content styling: an
adopter keeps setting its own radius / font / color on top and wins by cascade
order (recipes load after the foundation) — no double border. Note the box
cost: unlike Radix (border embedded in the shadow stack), the plane border is
a real `border` and adds 1px to the adopter's box.

> **Doctrine — the plane paints, the positioner positions.** `z-index` is
> NEVER painted by `[data-depth]`: stacking is a positioning concern owned by
> whoever positions the element (soma's floating positioner mirrors the
> content's computed z; portaled overlays live on the flat
> `--z-index-overlay-*` band precisely because the plane ladder cannot order
> them — dropdown 300 < modal 700 would hide a menu opened inside a dialog).
> The plane exposes `--depth-{plane}-z` as introspection / escape hatch (0
> consumers today — open cage). Guarded:
> `active-eidos-config.test.ts` asserts the generated CSS never paints
> `z-index: var(--depth-…-z)`.

Nothing existing is renamed → **zero component breakage**.

## 6. Phases (the flexibility is baked into each)

1. ✅ **Unified plane** — `EidosConfig.depth` + canonical planes +
   `--depth-{plane}-*` emission (composing surface/border/shadow/z) +
   `[data-depth]` paint rule (surface/border/shadow+halo — z is exposed,
   never painted; see §5's doctrine) + validation + test + regen. Doors:
   config-driven set, per-plane mix, primitives intact, escape to raw.
2. ✅ **Computed mode-adaptive mix** — the drop shadow keeps the themed scale
   (subtle slate in light / more opaque black in dark — already a tint, not flat
   black); Phase 2 adds the **`halo`** cue: a top-edge rim-light **computed in
   oklab** (`color-mix(in oklab, white N%, transparent)`, scaled per plane:
   5/7/8% on raised/overlay/modal). It is invisible over light surfaces (the
   drop rules) and becomes the elevation signal over dark surfaces (where the
   drop barely reads) — solves "the shadow lies in dark" **without touching the
   global shadows**: it lives only in the depth channel, composed into
   `[data-depth]`'s `box-shadow` (`shadow, halo`). The surface-derived halo +
   atmospheric frost stay for Phase 4.
3. ✅ **Eventful `depth` channel (event moment)** — the ELEVATION dimension
   lives in the *signature*: `present-rise` (emerge) grows the shadow from flat
   → the element's resting one (rises); `press-squeeze` (contact) flattens it to
   the surface (recedes). Generic (flush = no-op), coordinated with
   position/scale and with sound+haptic from **one single event**, degrading
   with reduced-motion (global cap). Overridable: a theme rewrites the
   keyframes/signatures. Mounts on the existing `signatures` system, **not** a
   parallel one.
4. ✅ **Atmosphere (frost)** — per-plane `blur` cue (overlay/modal) + **opt-in**
   rule `[data-depth='{plane}'][data-frost]` (translucent `color-mix` 80%
   surface + `backdrop-filter: blur`), gated so an opaque overlay does not turn
   translucent by default. + runtime builder **`applyDepth(planes)`** /
   `clearDepth()` (+ pure `buildDepth`) retuning any plane cue live — sibling of
   `applyColorScheme` / `applyTypeScale`. (The `scrim` cue was **pruned
   2026-07-12** — modal backdrop dimming is component-managed via
   `--{component}-overlay-*` / `--color-overlay`, so a plane-level scrim cue was
   duplicative surface with no consumer; see the token-contract amendment above.)
5. ✅ **Showcase + docs** — `/temas/profundidad` at reference depth: reacts ·
   states (dynamic elevation) · ascends (signature) · plane ladder · resting
   catalog · light vs shadow (the halo) · open cage · a11y. Exceeds the breadth
   of Material's *elevation* reference by adding the two axes it lacks
   (eventful + open cage). + theming reference §29.

## 7. Composition with the existing

- **Surface ladder** (color) → the plane's `surface` signal (mode-aware for free).
- **OKLCH color engine** → computed shadows (Phase 2) and halos.
- **Motion's two moments** → the ascent/recession transition (Phase 3) is a
  movement, not a jump.
- **Sema event bus** → the eventful trigger (Phase 3), like sound/haptic.
- **z-index bands** → the plane's `z` signal.

Nothing is reinvented: the dispersed pieces are **unified + made eventful**,
under the book's doctrine.

## 8. Doctrine (parallel to color / typography)

- **Planes + channel = eidos canon** (like roles/variants and named styles):
  themeable values, but the *set* is canon.
- **Eventful depth = an engine capability**, opt-in with degradation (like
  sound/haptic).
- **Theme = retint/retune the perceptually fixed**: change HOW MUCH shadow
  `overlay` gets, not WHAT `overlay` means.
- **Open cage**: a strong opinion that never traps — primitives always reachable.

## 9. Out of scope

- Real 3D / perspective / gyroscope parallax (depth is perceptual, not a 3D engine).
- Geometry-based shadow ray-tracing (the tint/halo is computed, not physical occlusion).