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

# RFC — Eidos shape engine

> Sibling of [`rfc-color-engine.md`](./rfc-color-engine.md),
> [`rfc-typography.md`](./rfc-typography.md) and [`rfc-depth.md`](./rfc-depth.md).
> Takes the **shape** channel (`shape` from the book _Diseñando lo que ocurre_)
> to reference-grade by **breaking** the references' model — with the **open
> cage**. It is the book's **8th and last expression channel** left to elevate
> (time · motion · presence · depth · **shape** · color · sound · haptic).

## 0. Thesis

> **Shape is not a rounding number an element _has_; it is a perceptual quality
> — continuity, family, tension — that the system _composes_ and that, in its
> moment, _happens_.**

Everybody reduces shape to ONE number: `border-radius`. But the corner has more
axes than its magnitude: **how continuous** it is (circular arc vs
superellipse), which **family** it belongs to (rounded / continuous / cut /
pill), how it **relates** to nested shapes, and **what happens to it** when the
element is pressed or commits. Eidos treats shape as a **first-class channel**:
unified (magnitude + continuity + family + harmony), and **eventful** (shape can
tense/relax), under the **open cage**.

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

| Framework                | Model                                                                        | Structural limit                                                                              |
| ------------------------ | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| **Tailwind / Bootstrap** | `rounded-sm…full` scale, circular arc                                        | no continuity, no nested harmony, no family, static; the corner is an arc, period             |
| **Material 3**           | shape scale + per-component mapping + (M3 Expressive) _morph_ + `cut` family | arc/cut; the morph is recent and narrow; a **closed** system (you pick from the scale)        |
| **Apple / SwiftUI**      | **continuous** corners (superellipse) `.continuous`                          | platform-bound, not a portable token; not eventful; manual nesting                            |
| **CSS today**            | `border-radius` = elliptical arcs                                            | no universal native superellipse (`corner-shape` emerging); squircles via SVG/clip-path hacks |

**Common limit**: shape = **one arc-radius number**, a **static** property you
assign, **detached** from neighboring/nested elements, without real
**continuity**, and **disconnected from what happens**. SwiftUI is the only one
with continuity — but closed and per-platform. Material is the only one with
family + morph — but arc-based and closed. Nobody **unifies** them or makes
them **open**.

## 2. Where Eidos stands today (coherent, but not novel)

- **Radius scale** in `--radius-{none·sm·md·lg·xl·xxl·full}` (4/6/10/16/20px + pill). ✓
- Assigned **per component** via the size primitive (`radius: 'md'`). ✓
- **BUT** the model is exactly "one **circular arc** number": no continuity
  (squircle), no **harmony** between nested radii, no perceptual **family**, and
  **static** (it never happens). You are ~on par with Tailwind; below SwiftUI
  (continuity) and M3 (family + morph).

## 3. The novel model — 4 pieces

1. **Continuity (superellipse)** — a new axis `--shape-smoothing` (0 = circular
   arc … 1 = iOS-style superellipse). **Progressive output** (the exact strategy
   of color's oklch): `border-radius` is emitted (universal, the fallback)
   **and** `corner-shape: superellipse(…)` where supported. Solves at the root
   the arc-corner everyone drags along, breaking nobody.
2. **Nested-radius harmony** — inner radius **derived** from the outer:
   `inner = max(0, outer − gap)` (concentric), computed in `calc()`. A
   `--shape-nest` convention so card-inside-card (or input-inside-panel) never
   misaligns.
3. **Shape family** — `rounded · continuous · cut · pill` (+ `sharp`). A
   **perceptual** axis, not one of magnitude. Eidos canon (like roles/variants):
   themeable values, canonical set.
4. **_Eventful_ shape (the genuinely new part)** — shape **tenses/relaxes** when
   something happens: `contact`→squeezes corners, `commit`→rounds them, via the
   **same signature** that already drives motion/depth. Shape-as-happening,
   coordinated from **one single sema event**.

## 3.bis The two moments of shape

Shape respects the framework's **two-moments model** (motion F1) — it does not
reinvent it:

| Moment    | Attribute (axis)                              | For shape                                                                                                                       | Phase |
| --------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **state** | `data-state` (persistent)                     | the **resting shape** — magnitude (`--radius-*`) + family + continuity: how the element _is_                                    | 1     |
| **event** | `data-event-*` (transient, during the `hold`) | the **morph** — squeeze/round on `contact`/`commit`: what _happens_. Ordered by `sequence`, next to the motion/depth signatures | 3     |

A control **has** a shape (state) **and tenses it** when pressed (event) — the
two moments, never collapsed. The book's same rigor (event ≠ state) carried to
shape.

## 4. Doctrine — _strong default, open cage_

| Piece            | Strong default                                    | Open door                                                                                                                                              |
| ---------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **scale**        | canonical `--radius-*`                            | config-driven (`EidosConfig` size/radius); raw `border-radius` always one step away                                                                    |
| **continuity**   | `--shape-smoothing` on by default (subtle)        | global/per-component/per-element override; `0` returns to the pure arc                                                                                 |
| **family**       | canonical set (rounded/continuous/cut/pill/sharp) | the set is **canon** but themeable; a wrapper composes its own without inventing a family                                                              |
| **nesting**      | `--shape-nest` convention (concentric)            | opt-in; the computation is transparent (`calc()`), overridable                                                                                         |
| **eventful**     | `contact`↓squeeze / `commit`↑round                | **opt-in/opt-out** (like sound/haptic/depth); sema's open registry; **degrades with `prefers-reduced-motion`**; static shape works without the channel |
| **whole system** | canonical theme                                   | runtime **`applyShape(seed)`** (sibling of `applyColorScheme`/`applyTypeScale`/`applyDepth`)                                                           |

It is exactly how color/typography/depth already operate: retintable canon +
runtime builders + primitives always reachable. Shape inherits the same
openness contract.

## 5. Token contract (additions, frozen)

Bare-prefixed by system (`--shape-…`). The **magnitude** stays in `--radius-*`
(nothing renamed → zero breakage):

```
--radius-{key}        magnitude (existing scale — kept)
--shape-smoothing     superellipse EXPONENT (1 = circular arc, 2 ≈ the iOS
                      squircle — the shipped semantics, `STATIC_SHAPE`;
                      this RFC's earlier "factor 0..1" draft did not land)
                      → corner-shape: superellipse(k)
--shape-nest-gap      default gap for the nested radius (Phase 2)
```

- **Continuity**: `[style] { border-radius: var(--radius-md) }` (universal) +
  where supported `corner-shape: superellipse(var(--shape-smoothing-k))`
  (progressive, degrades to the arc).
- **Family**: `data-shape='cut'|'continuous'|…` attribute or the component's
  recipe (not a global token) — selects the appropriate `corner-shape` / clip.
- **Nesting**: `border-radius: max(0px, calc(var(--_outer-radius) -
var(--shape-nest-gap)))` — a `calc()` convention, no new output token.

> **4-corner nesting requires FINITE radii — at `full` only the _top_ nests.**
> At `full` (`--radius-full` = 9999px) the radius is **clipped to half the
> smaller dimension of each element**. A wide child (e.g. 16:10) **cannot** be
> concentric on all 4 corners: its height caps all four at ~½-height, different
> from the parent. But its **top corners CAN** be `card_radius − gap` if the
> **bottom ones stay square** (the height constraint stops biting). That is the
> iOS player geometry: artwork with a concentric rounded top + a straight base
> meeting the metadata.
>
> The `[data-shape-nest]` CSS rule does not work here because the parent's
> _computed_ radius value is still `9999px` (the cap is a _used_ value, not
> readable from CSS). The `/temas/forma` demo **measures** it
> (`min(w,h)/2 − gap` via `ResizeObserver`) and applies it to the artwork's top
> corners; the bottom ones stay at `0`. The "concentric radii" toggle is
> disabled at `full` ("auto: top only") because there the nesting is automatic
> and partial by geometry, not optional.

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

1. ✅ **Continuity + scale + families** — `--shape-smoothing` + `data-shape` →
   `corner-shape` with the 4 families (`rounded`/`continuous`/`cut`/`scoop`).
   Progressive emission: universal `border-radius` (the magnitude, `--radius-*`
   intact) + `corner-shape` where supported (degrades to the arc). Config-driven
   - validation + test + regen. (Families were brought forward here — they are
     the same `corner-shape` mechanic.)
2. ✅ **Nested harmony** — `--shape-nest-gap` + `[data-shape-nest]` rule:
   `border-radius: max(0, var(--shape-outer-radius) − gap)` (concentric).
3. ✅ **_Eventful_ shape (event moment)** — the corner morph **folded into the
   `press-squeeze` signature** (cross-modal: one press = scale + shadow +
   corner) + `@property --shape-smoothing` so it interpolates. On the existing
   `signatures` system; degrades with reduced-motion. Not a parallel system.
4. ✅ **Runtime builder `applyShape(seed)`** — `smoothing`/`nestGap` dial +
   family override, managed block (sibling of
   `applyColorScheme`/`applyTypeScale`/`applyDepth`).
5. ✅ **Showcase + docs** — `/temas/forma` (continuity with a dial + families +
   nesting + eventful, live) + theming reference §30.

## 7. Composition with the existing

- **`--radius-*` scale** → each shape's magnitude (reused, not duplicated).
- **`signatures` system** (motion/depth) → the eventful morph (Phase 3), not a
  new engine.
- **Motion's two moments** → the morph is a movement of shape, not a jump.
- **Sema event bus** → the eventful trigger (Phase 3), like sound/haptic/depth.
- **Spacing** → the nested-radius gap (Phase 2).

Nothing is reinvented: what is today a loose number gets **unified + made
continuous, harmonic and eventful**, under the book's doctrine.

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

- **Scale + families = eidos canon** (like roles/variants and planes): themeable
  values, but the _set_ is canon.
- **Continuity = a default quality**, retunable; `0` = pure arc (open cage).
- **Eventful shape = an engine capability**, opt-in with degradation (like
  sound/haptic/depth).
- **Theme = retint/retune the perceptually fixed**: change HOW MUCH `md` rounds
  or how much continuity it carries, not WHAT `cut` means.
- **Open cage**: a strong opinion that never traps — raw `border-radius` always
  reachable.

## 9. Out of scope

- Blobs / random organic shapes and arbitrary `path` morphing (shape is
  perceptual, not a free-geometry engine).
- Complex geometry clipping (bespoke per-component clip-path stays in each recipe).
- Asymmetric per-side corners as a system (raw per-corner `border-radius`
  already covers them).