svelte-kit-vice/docs/audit/theming/surface.md

surface — 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 · método y protocolo: PLAN-theming.md §1, §2, §7.

• Medido: 2026-08-25 · Alcance: 100% — 1 de 1 knobs por token público
• Knobs de apariencia: 1 — público 1 · privado 0 · global 0 · literal 0 · sistema 0 · excepción 3 · estructural 0 · puente 0 · canal 0 (los cinco últimos, fuera del ratio)
• Contrato hoy (lib/recipes/base.ts): 25 pública(s) — radius, neutral-track, neutral-solid, neutral-contrast, primary-track, primary-solid, primary-contrast, secondary-track, secondary-solid, secondary-contrast, affirm-track, affirm-solid, affirm-contrast, fulfill-track, fulfill-solid, fulfill-contrast, risk-track, risk-solid, risk-contrast, threat-track, threat-solid, threat-contrast, loss-track, loss-solid, loss-contrast · 3 privada(s) forward — _palette-track, _palette-solid, _palette-contrast
• Eje size: no · ficheros: surface.css

1. Knobs fuera de alcance

1.1 Directo a primitivo global (0)

Ninguno.

1.2 A través de un privado (0)

Ninguno.

1.3 Literales (0)

Ninguno.

1.4 Excepciones firmadas (3) — fuera del ratio

Literales que llevan su anotación /* literal: <razón> */ en la propia declaración: la válvula de recipe-contract §3, la misma que honra component-audit. Una desviación firmada no es deuda — se listan para que la razón se lea, no para acuñarlas.

#	fichero:línea	selector	propiedad	valor
1	surface.css:27	[data-box][data-surface]	background	var(--_surface-bg)
2	surface.css:28	[data-box][data-surface]	color	var(--_surface-fg)
3	surface.css:48	[data-box][data-surface][data-gradient][data-variant='solid']	background-image	var(--_surface-fill-finish)

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

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

Ninguno.

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

privado	declaraciones	valor(es)	origen	¿deriva de un público?
--_surface-bg	2	var(--_surface-palette-track), var(--_surface-palette-solid)	private	no
--_surface-fg	2	inherit, var(--_surface-finish-ink, var(--_surface-palette-contrast))	literal, private	no

Consumidos y no declarados en el CSS (vienen de base.ts o de un estilo inline del wrapper): --_surface-fill-finish, --_surface-finish-ink, --_surface-palette-contrast, --_surface-palette-solid, --_surface-palette-track.

4. Propuesta de corrección

4.1 Tokens a declarar en lib/recipes/base.ts (3)

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 (--surface-…)	scope TSC	valor propuesto	usos
bg	root	var(--_surface-bg)	1
fg	root	var(--_surface-fg)	1
solid-bg-image	root	var(--_surface-fill-finish)	1

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

ADJUDICADO 2026-08-23 — el 25 % ES su techo, y no hay nada que coser. Cero claves nuevas: sus cuatro knobs son, uno a uno, doctrina bien aplicada.

Surface es la cara de PINTURA de Box (Box es layout por doctrina), y lo que pinta no es suyo:

• --_surface-bg y --_surface-fg salen del puente de paleta THM-2 (--_surface-palette-{track,solid,contrast}), que es exactamente cómo un tema llega a ellos: por el color, no por un token de superficie. La rama inherit del fg suave es intencionada —la tinta del contenido se queda en la global porque el tinte del track es discreto— y está escrita en la receta.
• --_surface-fill-finish es el canal de valor del acabado de degradado: lo deriva el generador por instancia (§39), como en button. Su dial es del sistema (--gradient-finish-lift).

Dos cosas que sí salieron, y las dos son de instrumento o de arquitectura:

• No tiene ruta propia: /uix/components/surface es un 404, como picker-shell y mockup. El guard medía una página VACÍA y reportaba 0/25 — incluido radius, que está vivísimo. Apuntado a /temas/gradientes (cuatro surfaces, dos variantes, tres colores) y a /blocks/cta: 1/25, y el que mueve es el radio (10px → 1234px). → §13, con los otros dos sin ruta.
• Sus 24 claves de tono son la SUPERSESIÓN de la cascada de paleta medida hoy en button: el bloque genérico [data-surface][data-color] va el último y gana por orden. Adjudicadas con el patrón compartido.

Verificación: centinela 1/25 con las 24 adjudicadas · censo 25 %, que es el techo · sin cambios de código.