# gradient-builder — alcance de tema: análisis y propuesta

> Generado por `node --import tsx/esm scripts/theming-census.ts --report`.
> Lo **medido** y la **propuesta** se regeneran; el **Veredicto** (§5) se conserva.
> Vista de conjunto: [README](./README.md) · método y protocolo:
> [`PLAN-theming.md`](../../process/PLAN-theming.md) §1, §2, §7.

- **Medido**: 2026-08-19 · **Alcance**: **0%** — 0 de 57 knobs por token público
- **Knobs de apariencia**: 62 — público 0 · privado 8 · global 46 · literal 3 · sistema 5 _(fuera del ratio)_
- **Contrato hoy** (`lib/recipes/base.ts`): **sin entrada en `base.ts`**
- **Eje `size`**: sí · **ficheros**: `gradient-builder.css`

## 1. Knobs fuera de alcance

### 1.1 Directo a primitivo global (46)

| # | fichero:línea | selector | propiedad | valor |
| ---: | --- | --- | --- | --- |
| 1 | `gradient-builder.css:34` | `[data-gradient-builder]` | `gap` | `var(--space-4)` |
| 2 | `gradient-builder.css:38` | `[data-gradient-builder]` | `padding` | `var(--space-4)` |
| 3 | `gradient-builder.css:41` | `[data-gradient-builder]` | `background` | `var(--color-surface-raised, var(--color-surface-default))` |
| 4 | `gradient-builder.css:42` | `[data-gradient-builder]` | `border` | `var(--border-width) solid var(--color-border-default)` |
| 5 | `gradient-builder.css:43` | `[data-gradient-builder]` | `border-radius` | `var(--radius-lg)` |
| 6 | `gradient-builder.css:50` | `[data-gradient-builder][data-size='sm']` | `gap` | `var(--space-3)` |
| 7 | `gradient-builder.css:51` | `[data-gradient-builder][data-size='sm']` | `padding` | `var(--space-3)` |
| 8 | `gradient-builder.css:58` | `[data-gradient-builder][data-size='lg']` | `gap` | `var(--space-5)` |
| 9 | `gradient-builder.css:59` | `[data-gradient-builder][data-size='lg']` | `padding` | `var(--space-5)` |
| 10 | `gradient-builder.css:91` | `[data-gradient-builder-preview]` | `border` | `var(--border-width) solid var(--color-border-subtle)` |
| 11 | `gradient-builder.css:92` | `[data-gradient-builder-preview]` | `background-color` | `var(--color-surface-default)` |
| 12 | `gradient-builder.css:93` | `[data-gradient-builder-preview]` | `background-image` | `var(--gb-checker)` |
| 13 | `gradient-builder.css:110` | `[data-gradient-builder-track]` | `border` | `var(--border-width) solid var(--color-border-subtle)` |
| 14 | `gradient-builder.css:123` | `[data-gradient-builder-stop]` | `border-radius` | `var(--radius-full)` |
| 15 | `gradient-builder.css:125` | `[data-gradient-builder-stop]` | `background` | `var(--gb-stop-fill, var(--color-surface-default))` |
| 16 | `gradient-builder.css:126` | `[data-gradient-builder-stop]` | `box-shadow` | `0 0 0 1px color-mix(in srgb, var(--color-neutral-contrast) 45%, transparent), 0 1px 3px color-mix(in srgb, var(--color-neutral-contrast) 30%, transparent)` |
| 17 | `gradient-builder.css:139` | `[data-gradient-builder-stop][data-selected]` | `box-shadow` | `0 0 0 calc(2px * var(--scaling, 1)) var(--color-primary-solid), 0 1px 3px color-mix(in srgb, var(--color-neutral-contrast) 35%, transparent)` |
| 18 | `gradient-builder.css:145` | `[data-gradient-builder-stop]:focus-visible` | `box-shadow` | `0 0 0 calc(2px * var(--scaling, 1)) var(--color-surface-default), 0 0 0 calc(4px * var(--scaling, 1)) var(--color-primary-solid)` |
| 19 | `gradient-builder.css:154` | `[data-gradient-builder-stop-actions]` | `gap` | `var(--space-2)` |
| 20 | `gradient-builder.css:171` | `[data-gradient-builder-angle-dial]` | `gap` | `var(--space-2)` |
| 21 | `gradient-builder.css:177` | `[data-gradient-builder-angle-dial-head]` | `gap` | `var(--space-2)` |
| 22 | `gradient-builder.css:180` | `[data-gradient-builder-angle-dial-label]` | `font-size` | `var(--font-size-sm)` |
| 23 | `gradient-builder.css:184` | `[data-gradient-builder-angle-dial-value]` | `font-size` | `var(--font-size-sm)` |
| 24 | `gradient-builder.css:186` | `[data-gradient-builder-angle-dial-value]` | `color` | `var(--color-content-primary)` |
| 25 | `gradient-builder.css:195` | `[data-gradient-builder-stop-color-title]` | `font-size` | `var(--font-size-sm)` |
| 26 | `gradient-builder.css:196` | `[data-gradient-builder-stop-color-title]` | `font-weight` | `var(--font-weight-medium, 500)` |
| 27 | `gradient-builder.css:197` | `[data-gradient-builder-stop-color-title]` | `color` | `var(--color-content-primary)` |
| 28 | `gradient-builder.css:202` | `[data-gradient-builder-stop-color-sliders]` | `gap` | `var(--space-2)` |
| 29 | `gradient-builder.css:220` | `[data-gradient-builder-stop-list]` | `gap` | `var(--space-1)` |
| 30 | `gradient-builder.css:225` | `[data-gradient-builder-stop-list-row]` | `gap` | `var(--space-2)` |
| 31 | `gradient-builder.css:232` | `[data-gradient-builder-stop-list-value]` | `gap` | `var(--space-2)` |
| 32 | `gradient-builder.css:234` | `[data-gradient-builder-stop-list-value]` | `padding` | `var(--space-1) var(--space-2)` |
| 33 | `gradient-builder.css:235` | `[data-gradient-builder-stop-list-value]` | `border` | `var(--border-width) solid var(--color-border-subtle)` |
| 34 | `gradient-builder.css:236` | `[data-gradient-builder-stop-list-value]` | `border-radius` | `var(--radius-md)` |
| 35 | `gradient-builder.css:237` | `[data-gradient-builder-stop-list-value]` | `background` | `var(--color-surface-default)` |
| 36 | `gradient-builder.css:238` | `[data-gradient-builder-stop-list-value]` | `color` | `var(--color-content-primary)` |
| 37 | `gradient-builder.css:240` | `[data-gradient-builder-stop-list-value]` | `font-size` | `var(--font-size-sm)` |
| 38 | `gradient-builder.css:248` | `[data-gradient-builder-stop-list-value][data-selected]` | `border-color` | `var(--color-primary-border)` |
| 39 | `gradient-builder.css:259` | `[data-gradient-builder-stop-list-pos]` | `color` | `var(--color-content-secondary)` |
| 40 | `gradient-builder.css:267` | `[data-gradient-builder-presets]` | `gap` | `var(--space-2)` |
| 41 | `gradient-builder.css:272` | `[data-gradient-builder-presets] .gb-preset-grid` | `gap` | `var(--space-2)` |
| 42 | `gradient-builder.css:276` | `[data-gradient-builder-preset]` | `block-size` | `calc(32px * var(--scaling, 1))` |
| 43 | `gradient-builder.css:278` | `[data-gradient-builder-preset]` | `border` | `var(--border-width) solid var(--color-border-subtle)` |
| 44 | `gradient-builder.css:279` | `[data-gradient-builder-preset]` | `border-radius` | `var(--radius-md)` |
| 45 | `gradient-builder.css:283` | `[data-gradient-builder-preset]:hover` | `border-color` | `var(--color-border-strong)` |
| 46 | `gradient-builder.css:291` | `[data-gradient-builder-preset][data-selected]` | `border-color` | `var(--color-primary-border)` |

### 1.2 A través de un privado (8)

| # | fichero:línea | selector | propiedad | valor |
| ---: | --- | --- | --- | --- |
| 1 | `gradient-builder.css:89` | `[data-gradient-builder-preview]` | `block-size` | `var(--_gradient-builder-preview-height)` |
| 2 | `gradient-builder.css:90` | `[data-gradient-builder-preview]` | `border-radius` | `var(--_gradient-builder-radius)` |
| 3 | `gradient-builder.css:106` | `[data-gradient-builder-track]` | `block-size` | `var(--_gradient-builder-track-height)` |
| 4 | `gradient-builder.css:109` | `[data-gradient-builder-track]` | `border-radius` | `var(--_gradient-builder-radius)` |
| 5 | `gradient-builder.css:121` | `[data-gradient-builder-stop]` | `inline-size` | `var(--_gradient-builder-stop-size)` |
| 6 | `gradient-builder.css:122` | `[data-gradient-builder-stop]` | `block-size` | `var(--_gradient-builder-stop-size)` |
| 7 | `gradient-builder.css:124` | `[data-gradient-builder-stop]` | `border` | `calc(2px * var(--scaling, 1)) solid var(--_gradient-builder-stop-ring)` |
| 8 | `gradient-builder.css:181` | `[data-gradient-builder-angle-dial-label]` | `color` | `var(--_gradient-builder-label)` |

### 1.3 Literales (3)

| # | fichero:línea | selector | propiedad | valor |
| ---: | --- | --- | --- | --- |
| 1 | `gradient-builder.css:35` | `[data-gradient-builder]` | `inline-size` | `100%` |
| 2 | `gradient-builder.css:204` | `[data-gradient-builder-stop-color-sliders]` | `inline-size` | `90%` |
| 3 | `gradient-builder.css:275` | `[data-gradient-builder-preset]` | `inline-size` | `100%` |

## 2. Sistema transversal (5) — informativo, fuera del ratio

Un tema los alcanza **a nivel de sistema**, por diseño (recipe-contract §2).

| # | fichero:línea | selector | propiedad | valor |
| ---: | --- | --- | --- | --- |
| 1 | `gradient-builder.css:73` | `[data-gradient-builder][data-disabled]` | `opacity` | `var(--opacity-disabled)` |
| 2 | `gradient-builder.css:245` | `[data-gradient-builder-stop-list-value]:hover:not(:disabled)` | `background-image` | `linear-gradient(var(--state-hover), var(--state-hover))` |
| 3 | `gradient-builder.css:251` | `[data-gradient-builder-stop-list-value]:focus-visible` | `outline` | `var(--focus-ring-width) solid var(--focus-ring-color)` |
| 4 | `gradient-builder.css:286` | `[data-gradient-builder-preset]:focus-visible` | `outline` | `var(--focus-ring-width) solid var(--focus-ring-color)` |
| 5 | `gradient-builder.css:292` | `[data-gradient-builder-preset][data-selected]` | `outline` | `var(--focus-ring-width) solid var(--color-primary-border)` |

## 3. Privados de la receta — ¿de dónde sale su valor?

| privado | declaraciones | valor(es) | origen | ¿deriva de un público? |
| --- | ---: | --- | --- | :-: |
| `--_gradient-builder-preview-height` | 3 | `calc(128px * var(--scaling, 1))`, `calc(56px * var(--scaling, 1))`, `calc(88px * var(--scaling, 1))` | global | no |
| `--_gradient-builder-track-height` | 3 | `calc(24px * var(--scaling, 1))`, `calc(20px * var(--scaling, 1))`, `calc(28px * var(--scaling, 1))` | global | no |
| `--_gradient-builder-stop-size` | 3 | `calc(20px * var(--scaling, 1))`, `calc(18px * var(--scaling, 1))`, `calc(22px * var(--scaling, 1))` | global | no |
| `--_gradient-builder-radius` | 1 | `var(--radius-md)` | global | no |
| `--_gradient-builder-border` | 1 | `var(--color-border-default)` | global | no |
| `--_gradient-builder-stop-ring` | 1 | `var(--color-surface-default)` | global | no |
| `--_gradient-builder-label` | 1 | `var(--color-content-secondary)` | global | no |

## 4. Propuesta de corrección

- **Consume la capa compartida `picker-shell`.** Un eje que la capa posee se consume como `var(--_x, var(--x))`; el consumidor **no acuña** `--gradient-builder-{eje}` para él — sería un vocabulario paralelo (README de `eidos/components`, «Capas compartidas» regla 2).
- **Tiene eje `size`**: los tokens dimensionales van por talla (`{part}-{eje}-{k}`) apuntando al bundle `--size-{k}-*`, nunca al primitivo crudo (theming §5; el guard `recipe-css-contract` prohíbe el primitivo).

### 4.1 Tokens a declarar en `lib/recipes/base.ts` (51)

Valor **verbatim** del CSS de hoy: el default no se mueve, sólo cambia quién
puede moverlo. Nombres derivados de recipe-contract §1 (ejes lógicos, talla
al final) y theming §6.7 (slots de color, modificador delante). Un token con
DOS valores distintos es una colisión de nombre: son dos knobs, o el nombre
no distingue lo que debería — se marca `⚠`.

| token (`--gradient-builder-…`) | scope TSC | valor propuesto | usos |
| --- | --- | --- | ---: |
| `stop-shadow` | `root` | ⚠ `0 0 0 1px color-mix(in srgb, var(--color-neutral-contrast) 45%, transparent), 0 1px 3px color-mix(in srgb, var(--color-neutral-contrast) 30%, transparent)` / `0 0 0 calc(2px * var(--scaling, 1)) var(--color-surface-default), 0 0 0 calc(4px * var(--scaling, 1)) var(--color-primary-solid)` | 2 |
| `presets-gap` | `root` | `var(--space-2)` | 2 |
| `gap` | `root` | `var(--space-4)` | 1 |
| `bg` | `root` | `var(--color-surface-raised, var(--color-surface-default))` | 1 |
| `radius` | `root` | `var(--radius-lg)` | 1 |
| `gap-sm` | `root` | `var(--space-3)` | 1 |
| `gap-lg` | `root` | `var(--space-5)` | 1 |
| `preview-height-md` | `size:md` | `calc(128px * var(--scaling, 1))` | 1 |
| `preview-height-sm` | `size:sm` | `calc(56px * var(--scaling, 1))` | 1 |
| `preview-height-lg` | `size:lg` | `calc(88px * var(--scaling, 1))` | 1 |
| `preview-radius` | `root` | `var(--radius-md)` | 1 |
| `preview-bg` | `root` | `var(--color-surface-default)` | 1 |
| `preview-bg-image` | `root` | `var(--gb-checker)` | 1 |
| `track-height-md` | `size:md` | `calc(24px * var(--scaling, 1))` | 1 |
| `track-height-sm` | `size:sm` | `calc(20px * var(--scaling, 1))` | 1 |
| `track-height-lg` | `size:lg` | `calc(28px * var(--scaling, 1))` | 1 |
| `track-radius` | `root` | `var(--radius-md)` | 1 |
| `stop-width-md` | `size:md` | `calc(20px * var(--scaling, 1))` | 1 |
| `stop-width-sm` | `size:sm` | `calc(18px * var(--scaling, 1))` | 1 |
| `stop-width-lg` | `size:lg` | `calc(22px * var(--scaling, 1))` | 1 |
| `stop-height-md` | `size:md` | `calc(20px * var(--scaling, 1))` | 1 |
| `stop-height-sm` | `size:sm` | `calc(18px * var(--scaling, 1))` | 1 |
| `stop-height-lg` | `size:lg` | `calc(22px * var(--scaling, 1))` | 1 |
| `stop-radius` | `root` | `var(--radius-full)` | 1 |
| `stop-bg` | `root` | `var(--gb-stop-fill, var(--color-surface-default))` | 1 |
| `selected-stop-shadow` | `root` | `0 0 0 calc(2px * var(--scaling, 1)) var(--color-primary-solid), 0 1px 3px color-mix(in srgb, var(--color-neutral-contrast) 35%, transparent)` | 1 |
| `stop-actions-gap` | `root` | `var(--space-2)` | 1 |
| `angle-dial-gap` | `root` | `var(--space-2)` | 1 |
| `angle-dial-head-gap` | `root` | `var(--space-2)` | 1 |
| `angle-dial-label-font-size` | `root` | `var(--font-size-sm)` | 1 |
| `angle-dial-label-fg` | `root` | `var(--color-content-secondary)` | 1 |
| `angle-dial-value-font-size` | `root` | `var(--font-size-sm)` | 1 |
| `angle-dial-value-fg` | `root` | `var(--color-content-primary)` | 1 |
| `stop-color-title-font-size` | `root` | `var(--font-size-sm)` | 1 |
| `stop-color-title-font-weight` | `root` | `var(--font-weight-medium, 500)` | 1 |
| `stop-color-title-fg` | `root` | `var(--color-content-primary)` | 1 |
| `stop-color-sliders-gap` | `root` | `var(--space-2)` | 1 |
| `stop-color-sliders-width` | `root` | `90%` | 1 |
| `stop-list-gap` | `root` | `var(--space-1)` | 1 |
| `stop-list-row-gap` | `root` | `var(--space-2)` | 1 |
| `stop-list-value-gap` | `root` | `var(--space-2)` | 1 |
| `stop-list-value-radius` | `root` | `var(--radius-md)` | 1 |
| `stop-list-value-bg` | `root` | `var(--color-surface-default)` | 1 |
| `stop-list-value-fg` | `root` | `var(--color-content-primary)` | 1 |
| `stop-list-value-font-size` | `root` | `var(--font-size-sm)` | 1 |
| `selected-stop-list-value-border` | `root` | `var(--color-primary-border)` | 1 |
| `stop-list-pos-fg` | `root` | `var(--color-content-secondary)` | 1 |
| `preset-height` | `root` | `calc(32px * var(--scaling, 1))` | 1 |
| `preset-radius` | `root` | `var(--radius-md)` | 1 |
| `hover-preset-border` | `root` | `var(--color-border-strong)` | 1 |
| `selected-preset-border` | `root` | `var(--color-primary-border)` | 1 |

### 4.2 Sin nombre mecánico (12)

- **⚠ decisión: `100%` es un valor identidad o geometría de layout, no un knob de tema — el perímetro de «knob» es D-TH.2, sin firmar** — 2: `inline-size`.
- **⚠ decisión: `padding` es shorthand o eje físico — hay que partirlo en ejes lógicos antes de nombrarlo (recipe-contract §1, R-4.4)** — 4: `padding`.
- **⚠ decisión: `border` es shorthand o eje físico — hay que partirlo en ejes lógicos antes de nombrarlo (recipe-contract §1, R-4.4)** — 6: `border`.

### 4.3 Avisos sobre los tokens propuestos (6)

- **⚠ decisión: el valor es una expresión — el token puede llevar la expresión entera o sólo su término variable · el privado `--_gradient-builder-preview-height` debe pasar a leer este público (o desaparecer)** — `--gradient-builder-preview-height-md`, `--gradient-builder-preview-height-sm`, `--gradient-builder-preview-height-lg`
- **el privado `--_gradient-builder-radius` debe pasar a leer este público (o desaparecer)** — `--gradient-builder-preview-radius`, `--gradient-builder-track-radius`
- **⚠ decisión: el valor es una expresión — el token puede llevar la expresión entera o sólo su término variable · el privado `--_gradient-builder-track-height` debe pasar a leer este público (o desaparecer)** — `--gradient-builder-track-height-md`, `--gradient-builder-track-height-sm`, `--gradient-builder-track-height-lg`
- **⚠ decisión: el valor es una expresión — el token puede llevar la expresión entera o sólo su término variable · el privado `--_gradient-builder-stop-size` debe pasar a leer este público (o desaparecer)** — `--gradient-builder-stop-width-md`, `--gradient-builder-stop-width-sm`, `--gradient-builder-stop-width-lg`, `--gradient-builder-stop-height-md`, `--gradient-builder-stop-height-sm`, `--gradient-builder-stop-height-lg`
- **⚠ decisión: el valor es una expresión — el token puede llevar la expresión entera o sólo su término variable** — `--gradient-builder-selected-stop-shadow`, `--gradient-builder-stop-shadow`, `--gradient-builder-preset-height`
- **el privado `--_gradient-builder-label` debe pasar a leer este público (o desaparecer)** — `--gradient-builder-angle-dial-label-fg`

### 4.4 Lo que hay que comprobar a mano (PLAN-theming §1.3 · §7.4)

- [ ] **Privado que no deriva de un público** — §3 lo marca; el privado debe leer el público o desaparecer.
- [ ] **Velo o acento en el nodo equivocado** (`archetype: 'item'` en un envoltorio, un `background` en shorthand que mata la capa de estado) — se mide desde el píxel hacia arriba.
- [ ] **Doble animación** al mover un sello a una superficie con animación propia — registro de `animationstart`/`animationend`.
- [ ] **Diff de computed = 0** en reposo · hover · abierto · disabled · foco, por talla, antes y después.
- [ ] **Centinela por token nuevo**: valor imposible en el root → el nodo lo sigue. Si no, el token miente.

## 5. Veredicto

<!-- veredicto:start -->

**Revisión 2026-08-20 — verificación previa a implementación (Opus).**

**Análisis (§1–§3): CORRECTO** (62 · 0 · 8 · 46 · 3 · 5, reproducido). Partes
limpias y bien estampadas; `data-size` vive en el ROOT ✓ (sin `parts`).
Hallazgo de prefijo, tercero de la familia picker: la receta usa `--gb-*`
(`--gb-checker`, `--gb-stop-fill`) — abreviatura que viola theming §6 regla 5
y esconde privados al censo. **Renombrar `--gb-*` →
`--_gradient-builder-*`** (el checker es privado; `--gb-stop-fill` lo escribe
el wrapper inline por parada — mismo tratamiento que `match-anchor-width`,
privado bien prefijado, runtime).

**Propuesta (§4.1): APTA — la mejor del lote — con tres correcciones:**

1. **Forma por talla**: como en todos — coordenadas `{part}-{eje}-{k}` en
   `root` (la tabla ya las trae con valores verbatim CORRECTOS, incluidos los
   `calc(Npx * var(--scaling,1))` que conservan la participación en el zoom)
   **+ nombre resuelto** con `declarations` default `host` (md) y
   `size:sm/lg` — la receta consume sólo el resuelto (patrón Sidebar).
   `gap-sm`/`gap-lg` son coordenadas de ese mismo eje (`gap`), no tokens
   sueltos.
2. **`stop-shadow` ⚠**: los dos valores son reposo vs SELECCIONADA — la
   segunda ya existe como `selected-stop-shadow`; resolver por selector y
   dejar `stop-shadow` (reposo) + `selected-stop-shadow`, sin colisión. Ojo:
   ambos valores llevan `color-mix(… var(--color-neutral-contrast) …)` — es
   sombra, no hover, así que no toca R-4.3; se acuñan tal cual.
3. **`preview-bg-image` / `stop-bg`**: sus valores referencian los `--gb-*`
   de arriba — acuñar DESPUÉS del renombrado, leyendo el privado bien
   prefijado (`var(--_gradient-builder-checker)`), o promoviendo el checker a
   público si el autor quiere el damero temable (decisión menor, propongo
   privado).

Resto de la tabla (angle-dial, presets, kind-switch, stop-list, título):
**válida tal cual** — nombres en vocabulario, `root`, verbatim. Los 3
literales: anotar o tokenizar. Nota de talla: las alturas de preview/track y
los tamaños de stop son geometría PROPIA (px·scaling), no del bundle — ni se
fuerzan al bundle ni se marca desviación: el bundle no tiene esas coordenadas.

**Bloqueos de firma**: ninguno duro — este componente puede ser el PILOTO del
bloque picker (D-TH.4): todo su contrato sale con valores verbatim y cero
decisiones estructurales pendientes (sólo el damero, menor).

<!-- veredicto:end -->