# PENPOT_API_VERIFIED — allow-list de la API de Penpot

**Este archivo es el contrato.** Ningún seed de `data/raw/seeds/penpot.jsonl` puede usar un miembro de
la API de Penpot que no esté listado acá. `scripts/07_lint_penpot_code.py` lo verifica con hard-fail
sobre cada payload de `code`.

Si un seed necesita un miembro ausente de esta lista: **primero** se verifica contra `penpot_api_info`,
se agrega la captura verbatim a `penpot_api_docs.md`, y **después** se agrega acá con su evidencia.
Nunca al revés.

**Dos fuentes de verdad, y no coinciden.** La columna "documentado" es lo que dice el servidor
(`penpot_api_docs.md`); la columna "verificado" es lo que hace el runtime. Cuando difieren, **manda el
runtime**, y la discrepancia se anota explícitamente porque es material de entrenamiento: los seeds del
grupo C enseñan justamente a no confiar ciegamente en la documentación.

**Procedencia de las verificaciones en vivo:** sondeo de la sesión madre contra el archivo real del
usuario el 2026-07-30, creando shapes de prueba que se borraron al terminar (el archivo quedó en su
estado original: 0 shapes, 0 colores/tipografías/componentes en la biblioteca local, verificado con
`penpotUtils.shapeStructure(penpot.root, 2)`). Registrado en `PLAN.md` § "La API verificada" y en la
página de Docmost de la Fase 6.

---

## 0. Herramientas MCP disponibles — lista cerrada

Estas cuatro y **ninguna más**. Copiadas de `data/schemas/penpot.json`, que es byte a byte lo que el
modelo ve en inferencia.

| Herramienta | Parámetros | Requeridos |
| --- | --- | --- |
| `execute_code` | `code` | `code` |
| `export_shape` | `shapeId`, `format` (`svg`\|`png`, default `png`), `mode` (`shape`\|`fill`, default `shape`) | `shapeId` |
| `high_level_overview` | (ninguno) | — |
| `penpot_api_info` | `type`, `member` | `type` |

**Prohibido y sondeado por el holdout:**

- `import_image` — **no existe en este deployment**. El overview la menciona en prosa; la lista de
  herramientas es autoritativa. Ruta correcta: `await penpot.uploadMediaUrl(name, url)`.
- `export_shape` con `filePath` — el parámetro está eliminado del schema en este deployment
  (ver `PENPOT_DEPLOYMENT_NOTES.md`). Inventarlo es invención de parámetros.
- `export_shape` con `scale` — `scale` es propiedad del método de plugin `shape.export(config)`
  (`penpot_api_docs.md` Captura 29), **no** de la herramienta MCP. No hay forma de pedir 2x.
- Llamar `high_level_overview` dos veces — su propia descripción lo prohíbe
  (`If you have already read the 'Penpot High-Level Overview', you must not call this tool.`).
  Por eso aparece en exactamente **2** de los 96 seeds.

---

## 1. El objeto `penpot` — miembros permitidos

Lista cerrada, de `penpot_api_docs.md` Captura 2.

**Creación:** `createBoard()`, `createRectangle()`, `createEllipse()`, `createPath()`,
`createText(text)`, `createBoolean(boolType, shapes)`, `createShapeFromSvg(svgString)`,
`createShapeFromSvgWithImages(svgString)`, `createPage()`.

**Medios:** `uploadMediaUrl(name, url)`, `uploadMediaData(name, data, mimeType)`.

**Estructura y navegación:** `root`, `currentPage`, `currentFile`, `selection`, `openPage(page)`,
`group(shapes)`, `ungroup(group, ...other)`, `flatten(shapes)`.

**Alineación:** `alignHorizontal(shapes, dir)`, `alignVertical(shapes, dir)`,
`distributeHorizontal(shapes)`, `distributeVertical(shapes)`.

**Generación:** `generateMarkup(shapes, {type})`, `generateStyle(shapes, {type, withPrelude, includeChildren})`,
`generateFontFaces(shapes)`.

**Color:** `shapesColors(shapes)`, `replaceColor(shapes, oldColor, newColor)`.

**Contextos:** `library`, `fonts`, `history`, `viewport`, `theme`, `localStorage`, `utils`,
`currentUser`, `activeUsers`.

### PROHIBIDO — no existe

| Miembro inventado | Realidad |
| --- | --- |
| `penpot.createImage()` | No existe. Las imágenes van como `fills = [{fillOpacity: 1, fillImage: imageData}]` |
| `penpot.createComponent()` | Es `penpot.library.local.createComponent(shapes)` |
| `penpot.findShapeById()` | Es `penpotUtils.findShapeById(id)` o `page.getShapeById(id)` |
| cualquier miembro ausente de la Captura 2 | — |

---

## 2. `penpotUtils` — el objeto que inyecta el servidor MCP

Lista cerrada, de `penpot_api_docs.md` Captura 1. **Distinto de `penpot.utils`** (`ContextUtils`,
Captura 34), que solo tiene `geometry` y `types`.

| Firma | Aridad | Nota |
| --- | --- | --- |
| `getPages()` | 0 | `{id, name}[]` |
| `getPageById(id)` | 1 | |
| `getPageByName(name)` | 1 | |
| `shapeStructure(shape, maxDepth?)` | 1-2 | Devuelve `{id, name, type, children?, layout?}` |
| **`findShapeById(id)`** | **1** | **Ver § 3.1. La forma de 2 argumentos es el bug #1 del diagnóstico** |
| `findShape(predicate, root?)` | 1-2 | Sin `root` busca en todas las páginas |
| `findShapes(predicate, root?)` | 1-2 | |
| `isContainedIn(shape, container)` | 2 | |
| `setParentXY(shape, parentX, parentY)` | 3 | `parentX`/`parentY` son read-only, esta es la única vía |
| `analyzeDescendants(root, evaluator, maxDepth?)` | 2-3 | Devuelve `{shape, result}[]` |

### PROHIBIDO

`penpotUtils.importImage(...)` — no existe (`penpotUtils.importImage is not a function`).

---

## 3. Los cuatro errores que esta fase corrige

### 3.1 `findShapeById` tiene aridad 1

| | |
| --- | --- |
| **Documentado** | `findShapeById(id: string): Shape \| null` (Captura 1) |
| **Verificado** | `penpotUtils.findShapeById.length === 1`. `findShapeById(id)` → `{found: true}`. `findShapeById(page, id)` → **`{found: false}`, sin lanzar** |
| **Correcto** | `const s = penpotUtils.findShapeById(id); if (!s) { ... }` |
| **PROHIBIDO** | `penpotUtils.findShapeById(page, id)` — **27 ocurrencias sobre 21 de los 41 seeds viejos** |

El fallo es **silencioso**: devuelve `null` y revienta en la línea siguiente con
`Cannot read properties of null (reading '<prop>')`. El stack apunta al síntoma, no a la causa.

**Familia de búsqueda completa y permitida:**

| Forma | Cuándo |
| --- | --- |
| `penpotUtils.findShapeById(id)` | Id conocido, búsqueda global |
| `page.getShapeById(id)` | Id conocido, dentro de una página concreta |
| `penpotUtils.findShape(pred, root?)` | Primer match por predicado |
| `penpotUtils.findShapes(pred, root?)` | Todos los matches por predicado |
| `page.findShapes({name, nameLike, type})` | Búsqueda por criterio declarativo (Captura 23) |
| `penpotUtils.getPageByName(name)` | Obtener la página primero |

### 3.2 `shape.layout` no existe

| | |
| --- | --- |
| **Documentado** | `Board` declara `grid?: GridLayout` y `flex?: FlexLayout`. **No hay `layout`** (Captura 3) |
| **Verificado** | `'layout' in shape === false`; `shape.layout === undefined`. `board.flex` y `board.grid` devuelven **`null`** (no `undefined`) cuando no hay layout |
| **Correcto** | `if (board.flex) { board.flex.dir = 'column'; }` |
| **PROHIBIDO** | `shape.layout`, `board.layout`, `!!form.layout` — 8 ocurrencias sobre 5 seeds viejos |

**Origen del error, y por qué hay un seed dedicado a desambiguarlo:** la salida de
`penpotUtils.shapeStructure()` **sí** trae una clave `layout` (`{id, name, type, children?, layout?}`).
Es una clave del **output del helper**, no una propiedad del shape. Confundirlas es exactamente el error
que hay que desaprender.

### 3.3 `createText()` sin argumento devuelve `null`

| | |
| --- | --- |
| **Documentado** | Contrato: `createText(text: string): null \| Text`. **Ejemplo oficial: `text = penpot.createText();` sin argumento** (Captura 6) |
| **Verificado** | `createText('Hola mundo')` → `Text`. **`createText()` → `null`. `createText('')` → `null`** |
| **Correcto** | `const t = penpot.createText('Margherita'); if (!t) throw new Error('createText devolvió null');` |
| **PROHIBIDO** | `penpot.createText()` y `penpot.createText('')` |

Un modelo que consulta la documentación y sigue el ejemplo obtiene `null`, no puede crear texto, y
abandona: quedan solo rectángulos. Ésa es la mitad del síntoma reportado.

### 3.4 El gris `#B1B2B5`

| | |
| --- | --- |
| **Verificado** | El fill por defecto de `penpot.createRectangle()` es **`#B1B2B5`**. El de `createBoard()` es blanco |
| **Correcto** | Invariante R1: todo shape creado recibe `fills` explícito **antes** de insertarse |

El único ejemplo de flex layout en los 41 seeds viejos crea un board de 400×60 con dos rectángulos a los
que **nunca** asigna `fills` — el ejemplo canónico de "armar un layout" en los datos de entrenamiento
produce exactamente dos cajas grises.

---

## 4. Texto

| Miembro | Estado | Detalle verificado |
| --- | --- | --- |
| `characters` | ✅ | El contenido renderizado |
| `fontSize` | ✅ **string** | `'48'`. Los números se coercionan, pero el lint exige el string |
| `fontWeight` | ✅ **string** | `'700'` |
| `lineHeight` | ✅ **string** | `'1.2'` |
| `letterSpacing` | ✅ **string** | `'-1'` (px). **`'-0.02'` se lee de vuelta como `"0"`: los negativos en em se ignoran en silencio** |
| `fontFamily` | ✅ | `text.fontFamily = 'Work Sans'` como string directo **bindea** (`fontId: "gfont-work-sans"`). 1914 fuentes disponibles |
| `growType` | ✅ | `'auto-width'` \| `'auto-height'` \| `'fixed'`. Default `'auto-width'` |
| `align` | ✅ | `'left'` \| `'center'` \| `'right'` \| `'justify'` |
| `verticalAlign` | ✅ | `'top'` \| `'center'` \| `'bottom'` |
| `fills` | ✅ | El color del texto va acá. Default `[{fillColor:"#000000", fillOpacity:1}]` |
| `textTransform`, `textDecoration`, `direction` | ✅ | Captura 4 |
| `getRange(start, end)` | ✅ | Devuelve `TextRange` |
| `applyTypography(typography)` | ✅ | |
| **`textAlign`** | ❌ **LANZA** | `Cannot add property textAlign, object is not extensible`. **Mata todo el `execute_code`.** Usar `align` |
| **`color`** | ❌ **LANZA** | El objeto no es extensible. Usar `fills` |
| `font.applyToText(text)` | ⚠️ | Funciona, pero deja `fontId` como un objeto UUID de ClojureScript filtrado. **Preferir `fontFamily` como string** |

**Defaults de un `Text` recién creado, verificados:** `fontSize:"14"`, `fontFamily:"sourcesanspro"`,
`fontWeight:"400"`, `fills:[{fillColor:"#000000",fillOpacity:1}]`, `growType:"auto-width"`,
`width/height = [1, 1]`.

**Dimensionado (invariantes R4/R5/R6):**

- El auto-sizing **no es inmediato**: dormir ~120 ms antes de leer el bounding box.
- `resize(w, h)` setea `growType` a `'fixed'` **en silencio**. Restaurarlo si se quiere auto-sizing.
- `width` y `height` son **read-only**; `resize()` es la única vía.
- `parentX`/`parentY`/`boardX`/`boardY`/`bounds` son **read-only**; usar `penpotUtils.setParentXY()`.

---

## 5. Fills, gradientes, strokes, sombras, radios

| Miembro | Estado | Detalle |
| --- | --- | --- |
| `fills = [{fillColor, fillOpacity}]` | ✅ | |
| `fills` apilados | ✅ | Foto + scrim oscuro encima funciona |
| `fillColorGradient` | ✅ | Coords **normalizadas 0..1** con `width: 1`, aceptado verbatim |
| `fillImage` | ✅ | `fills = [{fillOpacity: 1, fillImage: img}]`; `img.keepAspectRatio = true` para fotos |
| `fillColorRefFile` / `fillColorRefId` | ✅ | Los pone `libraryColor.asFill()` |
| `strokes = [{strokeColor, strokeWidth, strokeStyle, strokeAlignment, strokeOpacity}]` | ✅ | |
| `borderRadius`, `borderRadiusTopLeft`… | ✅ | En rectángulo y board |
| `shadows = [{style, offsetX, offsetY, blur, spread, color}]` | ✅ | |
| **`Shadow.color`** | ⚠️ | Es un **`Color`** (`{color: '#000000', opacity: 0.12}`), **no un `Fill`**. `{fillColor: ...}` es el bug clásico |
| `blur` | ✅ | |
| `opacity`, `blendMode` | ✅ | |

**Gradiente, forma verificada:**

```js
fills = [{ fillOpacity: 1, fillColorGradient: {
  type: 'linear', startX: 0, startY: 0, endX: 0, endY: 1, width: 1,
  stops: [{ color: '#D62828', offset: 0 }, { color: '#F77F00', offset: 1 }]
}}]
```

---

## 6. Jerarquía e inserción

| Situación | Forma correcta |
| --- | --- |
| Padre **sin** layout | `parent.insertChild(parent.children.length, shape)` |
| Board **con** flex | `board.flex.appendChild(shape)` (preferido, orden visual) o `board.appendChild(shape)` (orden invertido, ver abajo) |
| Board **con** grid | `board.grid.appendChild(shape, row, column)` — **1-based** |
| Índice específico en flex | `board.insertChild(index, shape)`, recordando el orden invertido |
| Reparentar | `newParent.appendChild(shape)` / `insertChild(...)` — quita del padre viejo, preserva x/y absolutos |

**ACTUALIZACIÓN (2026-08-04, hallazgo 54 de la Fase 6, ronda correctiva 6.4.25c): `board.flex.appendChild(shape)`
NO está roto — verificado en vivo, repetidas veces, contra Penpot 2.16.2.** Es una función real, de
aridad 1, distinta de `board.appendChild` (no es un alias: `board.flex.appendChild !== board.appendChild`,
`board.flex !== board`), que no lanza ninguna excepción y agrega el hijo correctamente, con `layoutChild`
funcionando bien después. La afirmación anterior de que estaba roto **nunca tuvo un error real capturado**
en `penpot_errors.md` (a diferencia de todos los demás comportamientos rotos documentados en este archivo,
que sí lo tienen). Su origen real: el `high_level_overview()` del servidor MCP (capturado verbatim en
`penpot_api_docs.md`, líneas 131-135) le dice al modelo, en mayúsculas y marcado `CRITICAL`, que
**`board.flex.appendChild` está BROKEN y que NUNCA lo use** — instrucción que la sesión original de
diagnóstico tomó como cierta sin verificarla empíricamente con un intento real de romperlo. Esa misma
sección de la doc mezcla además un bug real y distinto (el ejemplo de **grid** con 3 argumentos aparece
escrito como `board.flex.appendChild(shape, row, column)` en vez de `board.grid.appendChild(...)`, ver
`penpot_api_docs.md` línea 143), lo cual reforzó la confusión. **La documentación servida en vivo por el
MCP de Penpot está, en este punto, objetivamente equivocada** (verificado empíricamente, repetidas veces,
el 2026-08-04 contra Penpot 2.16.2) — o el comportamiento se arregló en Penpot después de escribirse esa
documentación, sin actualizarla. Cualquier seed nuevo que muestre al modelo leyendo `high_level_overview`
debería, idealmente, incluir el razonamiento de que esa afirmación puntual sobre `flex.appendChild` no es
confiable y de que hay que verificar con el runtime en vez de creerle a esa línea específica — el mismo
patrón de "la lista de tools es autoritativa, la prosa no" ya usado en el grupo C para `import_image`.

**Orden invertido, verificado — y por qué `board.flex.appendChild` es preferible.** En `dir: 'column'`
(y `'row'`), apendeando PRIMERO y luego SEGUNDO con `board.appendChild`, el array `children` queda
`[SEGUNDO, PRIMERO, ...]`: `board.appendChild` inserta **al frente**, así que hay que llamarlo en orden
inverso al visual para compensar. `board.flex.appendChild`, en cambio, preserva el **orden visual normal**
de las llamadas (PRIMERO, SEGUNDO, ...) — no necesita el truco de inversión. Para boards con flex, **usar
`board.flex.appendChild(shape)` en orden visual directo es la forma más simple y menos propensa a error.**
`board.appendChild` sigue siendo válido (y necesario para reparentar hacia boards sin layout, o cuando el
código ya maneja el truco de inversión de forma consistente), pero ya no es la única opción recomendada.

**La regla absoluta "nunca `appendChild`" que enseñan los seeds viejos es INCORRECTA.** El overview la
califica él mismo (`except in flex layout boards`) y la sección de Flex Layout **manda** usar
`board.appendChild`. La política correcta es condicional, y hay 5 seeds del grupo A3 dedicados a ella —
esos seeds siguen siendo correctos sobre el comportamiento de `board.appendChild` (el orden invertido es
real), pero ya no reflejan que `board.flex.appendChild` sea una alternativa rota.

**Z-order:** el orden del array `children`. Métodos: `bringToFront()`, `sendToBack()`,
`bringForward()`, `sendBackward()`, `setParentIndex(index)` (0-based).

---

## 7. Layouts

### Flex

| Miembro | Estado | Detalle |
| --- | --- | --- |
| `board.addFlexLayout()` | ✅ | Devuelve `FlexLayout` |
| `board.flex` | ✅ | Guard: `if (board.flex)`. **`null`** si no hay layout |
| `dir` | ✅ | `'row'` \| `'row-reverse'` \| `'column'` \| `'column-reverse'` |
| `rowGap`, `columnGap` | ✅ | **No existe el shorthand `gap`** |
| `alignItems`, `alignContent`, `justifyItems`, `justifyContent` | ✅ | |
| `topPadding`/`rightPadding`/`bottomPadding`/`leftPadding`, `verticalPadding`/`horizontalPadding` | ✅ | |
| `horizontalSizing` / `verticalSizing` | ⚠️ | `'fill'` \| `'auto'` \| `'fit-content'`. **`'auto'` se lee de vuelta como `'auto'` pero el board NO crece** (penpot#8520). Hay que `board.resize()` a mano |
| `wrap` | ✅ | `'wrap'` \| `'nowrap'` |
| `flex.appendChild` | ✅ | **Funciona** (verificado 2026-08-04, hallazgo 54). Aridad 1, preserva orden visual — preferible a `board.appendChild` para insertar en boards con flex |

### Grid

| Miembro | Estado | Detalle |
| --- | --- | --- |
| `board.addGridLayout()` | ✅ | **No `addFlexLayout()`**, como dice erróneamente el overview |
| `board.grid` | ✅ | Guard: `if (board.grid)` |
| `addRow(type, value?)`, `addColumn(type, value?)` | ✅ | `type`: `'flex'` \| `'fixed'` \| `'percent'` \| `'auto'` |
| `addRowAtIndex`, `addColumnAtIndex`, `removeRow`, `removeColumn`, `setRow`, `setColumn` | ✅ | |
| `rows`, `columns` | ✅ | `Track[]` = `{type, value}` |
| **`grid.appendChild(shape, row, column)`** | ✅ | **Índices 1-based.** `(s, 0, 0)` se clampea y se lee `[1,1]`; `(s, 1, 2)` se lee `[1,2]`. El ejemplo 0-based de la doc de tipos está mal |
| `shape.layoutCell` | ✅ | `{row, rowSpan, column, columnSpan, areaName, position}` — para leer de vuelta y reposicionar |

### `layoutChild` (el hijo dentro de un board con layout)

| Miembro | Estado | Detalle |
| --- | --- | --- |
| `layoutChild` | ✅ | **Existe solo DESPUÉS de insertar** el shape en un board con layout |
| `horizontalSizing` / `verticalSizing` | ✅ | `'fill'` \| `'auto'` \| **`'fix'`** (no `'fixed'`, no `'fit-content'`) |
| `alignSelf` | ✅ | |
| `absolute` | ✅ | `true` saca al hijo del flujo del layout |
| `*Margin`, `maxWidth`/`maxHeight`/`minWidth`/`minHeight` | ✅ | |
| **`zIndex`** | ⚠️ | Está en el tipo pero **se ignora en silencio** (se setea 10, se lee 0). Usar el orden de `children` |

**Invariante R8:** todo efecto de layout se **lee de vuelta** del objeto retornado. El seed se entrena
sobre `"titleStretched": true` leído del runtime, no sobre la esperanza de que haya funcionado.

**Invariante R9:** wrappers abrazan (`flex.horizontalSizing = 'fit-content'`), secciones llenan
(`layoutChild.horizontalSizing = 'fill'`). Los dos idioms en el mismo seed para que el contraste sea
aprendible.

---

## 8. Imágenes

| Miembro | Estado |
| --- | --- |
| `await penpot.uploadMediaUrl(name, url)` → `ImageData` | ✅ **Única vía** |
| `await penpot.uploadMediaData(name, bytes, mimeType)` | ✅ |
| `fills = [{fillOpacity: 1, fillImage: img}]` | ✅ |
| `img.keepAspectRatio = true` | ✅ Para fotos |
| `penpot.createImage()` | ❌ No existe |
| `penpotUtils.importImage()` | ❌ `penpotUtils.importImage is not a function` |
| herramienta MCP `import_image` | ❌ No existe en este deployment |

`uploadMediaUrl` devuelve una `Promise` y puede rechazar (`Error uploading media`): `await` dentro de
un `try/catch`.

---

## 9. Biblioteca local (tokens de diseño)

| Miembro | Estado | Detalle |
| --- | --- | --- |
| `penpot.library.local` | ✅ | |
| `library.local.createColor()` | ✅ | Luego `c.name = 'Brand/Primary'; c.color = '#D62828';` |
| `libraryColor.asFill()` | ✅ | Devuelve un `Fill` con `fillColorRefFile`/`fillColorRefId` |
| `libraryColor.asStroke()` | ✅ | |
| `library.local.createTypography()` | ✅ | |
| `library.local.createComponent(shapes)` | ✅ | |
| `component.instance()` / `mainInstance()` | ✅ | |
| `penpot.library.connected`, `availableLibraries()`, `connectLibrary(id)` | ✅ | |
| **`typography.setFont(font, variant?)`** | ❌ | Está en el tipo, **no existe en el runtime**: `t.setFont is not a function`. Setear `fontFamily`/`fontSize`/`fontWeight`/`lineHeight` una por una |

---

## 10. Verificación programática (invariante R12)

| Miembro | Estado | Uso |
| --- | --- | --- |
| `penpot.generateStyle(shapes, {type:'css', includeChildren:true})` | ✅ | Devuelve CSS real. **La opción es `includeChildren`; `withChildren` (que usa el overview) se ignora** |
| `penpot.generateMarkup(shapes, {type:'html'})` | ✅ | Devuelve HTML real |
| `penpotUtils.analyzeDescendants(root, evaluator, maxDepth?)` | ✅ | Auditoría; el evaluador puede devolver funciones correctoras |
| `penpotUtils.isContainedIn(shape, container)` | ✅ | Violaciones de contención |
| `penpotUtils.shapeStructure(shape, maxDepth)` | ✅ | Overview del árbol. **Su clave `layout` es del output, no del shape** |
| herramienta `export_shape` | ✅ | Inspección visual |

**R12: nunca terminar sin mirar y medir.** Todo seed compositivo cierra con `export_shape` + una
auditoría programática, y el mensaje final **cita los números** de esa auditoría.

---

## 11. Contramedida al system prompt del servidor

El servidor MCP inyecta verbatim (ver `penpot_system_prompt.md`):

> NEVER make assumptions about missing values and don't get overly creative (e.g. don't pick your own
> colours and stick to non-creative defaults such as white/black if you are lacking information).

**Ninguno de los 41 seeds viejos tiene mensaje `system`**, así que el modelo nunca se entrenó en
presencia de esta instrucción. En producción la aplica al revés y produce el gris.

Obligatorio en los seeds nuevos:

1. El bloque `instructions` **verbatim** como mensaje `system` en **~30 %** de los seeds (el resto sin
   él, para robustez en las dos condiciones).
2. En **todo** seed creativo, `reasoning_content` que desambigüe explícitamente. La regla condiciona
   sobre *"transferring styles from a Penpot design to code"*; crear un diseño nuevo es el caso
   contrario: no hay diseño previo del que transferir, así que no hay "missing values" sobre los que
   asumir. Elegir una paleta deliberada **es** la tarea.

---

## 12. Los doce invariantes anti-caja-gris

Cada uno presente **en los datos** y verificado por `scripts/07_lint_penpot_code.py`, no solo enunciado
en prosa.

| # | Invariante |
| --- | --- |
| R1 | Todo shape creado recibe `fills` explícito **antes** de insertarse. Los wrappers puros de layout ponen `fills = []` — transparente **por intención**, nunca "sin tocar" |
| R2 | **Cero grises de placeholder.** Todo hex debe pasar `saturación > 10` **o** `max < 100` **o** `max > 220`. El gris solo aparece en los tool results del grupo B8, y solo como *input* |
| R3 | Toda paleta es un set cerrado y nombrado de ≤ 8 roles, declarado al inicio del payload y referenciado por rol |
| R4 | Todo texto recibe `characters` + tamaño + fill + `growType` |
| R5 | Tamaño, peso e interlineado son **strings** entre comillas |
| R6 | Tras `resize()` sobre un texto, restaurar `growType` |
| R7 | Una card es fondo + radio + elevación |
| R8 | Todo hijo de layout declara su sizing, y el efecto se **lee de vuelta** del objeto retornado |
| R9 | Wrappers abrazan (`fit-content`), secciones llenan (`fill`) — los dos idioms en el mismo seed |
| R10 | Escala tipográfica, nunca tamaños ad-hoc: ≥ 3 tamaños distintos por pantalla compuesta |
| R11 | Espaciado en escala de 8 px |
| R12 | Nunca terminar sin mirar y medir: `export_shape` → auditoría → resumen que **cita los números** |

---

## 13. Resumen de patrones prohibidos (lo que el lint busca)

| Patrón | Por qué |
| --- | --- |
| `findShapeById(` con coma en los argumentos | Aridad 1; la forma de 2 devuelve `null` en silencio |
| `.layout` en una línea sin `shapeStructure` | La propiedad no existe |
| `appendChild(` sobre un receptor sin evidencia de flex | Solo es correcto en boards con flex (`board.flex.appendChild` o `board.appendChild`) |
| `fontSize`/`fontWeight`/`lineHeight`/`letterSpacing` `= <número>` | Son strings |
| `textAlign =` | Lanza y mata el `execute_code` |
| `importImage`, `import_image`, `createImage(`, `filePath` | No existen en este deployment |
| Asignación a `width`/`height`/`parentX`/`parentY`/`bounds` | Read-only |
| `gap =` | No hay shorthand; son `rowGap`/`columnGap` |
| `shadows = [{... color: {fillColor` | `Shadow.color` es un `Color`, no un `Fill` |
| Hex gris de placeholder fuera del grupo B8 | Invariante R2 |
| `console.log` de algo que también se retorna | Prohibición explícita del servidor |
| `setFont(` | No existe en el runtime |
| `createText()` / `createText('')` | Devuelven `null` |
| `high_level_overview` en más de 2 seeds | Su descripción prohíbe llamarlo dos veces |