pencil-generate-library: tokens, temas y componentes en orden
Construye un sistema de diseño en un archivo .pen que coincida con el código. Carga primero pencil-use: contiene las reglas de execute. Este skill contiene el orden de trabajo y las decisiones del sistema de diseño.
1. La regla más importante
Esto nunca es una sola llamada. Un sistema pequeño requiere de 15 a 40 llamadas execute, uno más grande muchas más. Trabaja en la unidad útil más pequeña, verifícala, muéstrala y luego continúa. Un sistema construido en un solo fragmento largo sale roto y es difícil de reparar.
2. En qué se diferencia Pencil de otras herramientas
Planifica con el modelo real de Pencil, no con uno tomado de otra parte:
| Necesidad | En Pencil |
|---|---|
| Tokens | Variables de documento de tipo color, number, string, boolean, referenciadas como $name |
| Modos (claro, oscuro) | Ejes de tema. El valor de una variable es una lista de {value, theme: {mode: "dark"}}; un marco selecciona un valor con su propiedad theme |
| Alias (semántico a primitivo) | Una variable cuyo valor es otra variable: value: "$gray-900" |
| Estilos de texto | Ninguno. Usa variables de fuente (familia, tamaño, altura de línea, peso como cadenas o números) y, si es útil, componentes de texto pequeños |
| Estilos de sombra | Ninguno. Los efectos de sombra aceptan variables para color, desenfoque y desplazamiento |
| Componente | Cualquier nodo con reusable: true |
| Variantes | Sin conjuntos de variantes. Un componente por variante, nombrado con barras: Button/Primary, Button/Outline |
| Opción booleana (mostrar icono) | Anulación de instancia enabled: false en esa parte |
| Icono intercambiable | Anulación de instancia en el nodo del icono: {icon: "plus"} |
| Contenido intercambiable | Un marco slot dentro del componente, con ids de componentes recomendados |
| Biblioteca compartida | Un archivo convertido a .lib.pen en la aplicación (una sola dirección, no se puede deshacer), importado por archivos de pantalla |
3. Flujo de trabajo
Fase 0 DESCUBRIMIENTO leer código y archivo, sin escrituras -> punto de control: plan aprobado
Fase 1 FUNDAMENTOS variables y temas -> punto de control: resumen de tokens aprobado
Fase 2 DISEÑO DE ARCHIVO áreas en el lienzo, tablero de fundamentos -> punto de control: captura de pantalla del tablero aprobada
Fase 3 COMPONENTES uno a la vez, átomos antes que moléculas -> punto de control después de cada componente
Fase 4 QA Y BIBLIOTECA auditorías, correcciones, .lib.pen opcional -> punto de control: visto bueno
Nombra la siguiente fase en cada punto de control. Un "se ve bien" sobre los tokens no es aprobación para comenzar con los componentes.
Fase 0. Descubrimiento (solo lectura)
0a. Encuentra los tokens en el código, en este orden:
- Propiedades personalizadas de CSS (
:root { --background: ... },.dark { ... }o[data-theme="dark"]). - Configuración de Tailwind o bloques
@themede Tailwind v4. - Archivos de token (DTCG
.tokens.json, Style Dictionary). - Objetos de tema en CSS-in-JS, o archivos de tema nativos (catálogos de activos iOS,
colors.xmlde Android).
Anota el mecanismo del modo oscuro, las escalas de espaciado y radio, las fuentes y la escala tipográfica, y las sombras.
0b. Encuentra los componentes en el código: la lista de primitivas de UI (Button, Input, Checkbox, Badge, Avatar, Card...), sus props, cuáles props son variantes (variant, size, state), cuáles son booleanos, cuáles toman hijos.
0c. Lee el archivo:
Print(GetVariables())
Get(n => n.reusable && Print(n.id, "|", n.name))
Get(document, (n, c) => { if (c.depth === 1) { Print(n.id, "|", n.type, "|", n.name); c.skipChildren() } })
También verifica get_app_state para bibliotecas importadas. Coincide con cualquier nombre que ya esté en el archivo.
0d. Bloquea el alcance con el usuario: la lista exacta de tokens y la lista exacta de componentes para esta ronda. Una primera ronda de seis a diez componentes es un buen tamaño.
0e. Mapea el código a Pencil y resuelve conflictos. Presenta una tabla:
Token del código Variable de Pencil Claro Oscuro Estado
--background --background #FFFFFF #0A0A0A nuevo
--primary --primary #1D4ED8 #3B82F6 existe, valor diferente (preguntar)
Componente Componentes de Pencil Estado
Button variante x tamaño Button/Primary, Button/Secondary, Button/Outline, Button/Ghost (tamaño mediante eje de tema) nuevo
Cuando el código y el archivo no coincidan, pregunta cuál gana. No decidas solo.
Punto de control: muestra el plan, espera la aprobación.
Fase 1. Fundamentos
Nomenclatura. Mantén los nombres del código para que el diseño y el código tengan ida y vuelta: una variable CSS --muted-foreground se convierte en la variable de Pencil --muted-foreground, referenciada como $--muted-foreground. Nunca empieces un nombre con $. Evita : en los nombres. Si el código no tiene nombres, usa nombres cortos en kebab por rol: surface, text, text-muted, border, accent, space-4, radius-md.
Capas.
- Primitivas: valores brutos, sin tema (
gray-50...gray-950,blue-500,space-1...space-16). - Semánticas: nombres de rol, con tema, apuntando a primitivas (
--background: claro$white, oscuro$gray-950). - Los componentes usan solo semánticas. Un componente que referencia
$gray-900directamente no cambiará con el tema.
Tamaño del sistema.
- Menos de unos 50 tokens: un conjunto plano, un eje
modeconlightydark. - Más grande: primitivas más semánticas como arriba, y ejes de tema adicionales solo cuando el código realmente los tenga (
density: comfortable, compact;brand: a, b).
Escribe en lotes pequeños, una familia por llamada (colores primitivos, luego colores semánticos, luego espaciado y radio, luego tipografía), y lee de vuelta:
SetVariables({
"gray-50": {type: "color", value: "#FAFAFA"},
"gray-900": {type: "color", value: "#171717"},
"gray-950": {type: "color", value: "#0A0A0A"},
"white": {type: "color", value: "#FFFFFF"}
})
SetVariables({
"--background": {type: "color", value: [{value: "$white", theme: {mode: "light"}}, {value: "$gray-950", theme: {mode: "dark"}}]},
"--foreground": {type: "color", value: [{value: "$gray-900", theme: {mode: "light"}}, {value: "$gray-50", theme: {mode: "dark"}}]}
})
const v = GetVariables()
Print(Object.keys(v.variables).length, "variables", "|", JSON.stringify(v.themes))
- Verifica que el primer valor del eje
modesea el predeterminado que usa el producto (generalmentelight). - Asigna a cada variable temática un valor para cada valor de tema que uses. Un valor faltante muestra el color incorrecto en silencio.
- Mantén los valores idénticos entre temas cuando no deban cambiar (espaciado, radio).
- Tipografía:
--font-sans(cadena), tamaños (text-sm14,text-base16...), alturas de línea como proporciones (leading-normal1.5), pesos como cadenas ("400","600"). - Sombras: una variable de color temática para la sombra y variables numéricas para desenfoque y desplazamiento si el código tiene una escala de sombras.
- Nunca
SetVariables(..., true)en un archivo existente sin consentimiento explícito: borra cada variable.
Criterios de salida: cada token en el plan existe con el tipo correcto, cada token temático tiene cada valor de tema, los alias apuntan a variables existentes.
Punto de control: muestra los recuentos por familia, los ejes de tema y cualquier valor que hayas tenido que adivinar.
Fase 2. Diseño de archivo y tablero de fundamentos
Mantén el lienzo legible:
- Un marco de Fundamentos en la parte superior izquierda: muestras de color, especímenes tipográficos, barras de espaciado, muestras de radio.
- Un área de Componentes a su derecha o debajo, un marco por familia de componentes (
Buttons,Inputs,Cards), que contenga los componentes con un título y una breve nota de uso. - Pantallas más abajo y a la derecha, nunca mezcladas con componentes.
- Usa
FindEmptySpacepara cada marco raíz.
Las muestras y especímenes deben estar vinculados a variables, para que el tablero se actualice cuando cambie un token. Construye muestras con un bucle:
boardId = Insert(document, {type: "frame", name: "Foundations / Color", layout: "vertical", gap: 16, padding: 32, fill: "$--background", x: 0, y: 0})
rowId = Insert(boardId, {type: "frame", name: "Semantic colors", gap: 16})
for (const name of ["--background", "--foreground", "--primary", "--muted", "--border"]) {
const s = Insert(rowId, {type: "frame", name: "Swatch " + name, layout: "vertical", gap: 8})
Insert(s, {type: "rectangle", name: "Chip", width: 96, height: 64, cornerRadius: 8, fill: "$" + name, stroke: "$--border", strokeWidth: 1})
Insert(s, {type: "text", name: "Label", content: name, fontSize: 12, fill: "$--foreground"})
}
TakeScreenshot([boardId])
Luego copia el tablero con theme: {mode: "dark"} al lado: si algo se mantiene claro, a un token le falta su valor oscuro.
Punto de control: captura de pantalla de los tableros en ambos temas.
Fase 3. Componentes, uno a la vez
Orden por dependencia: átomos primero (envoltorios de Icono, Badge, Avatar, Button, Input, Checkbox, Toggle), luego moléculas (grupo de Input con etiqueta y sugerencia, elemento de Menú, Tab), luego organismos (Card, Dialog, Sidebar, fila de Tabla). Un componente que contiene a otro debe construirse después de él y debe contener una instancia del mismo, no una copia redibujada.
Para cada componente:
3a. Diseña la API antes de dibujar. A partir de los props del código:
- Los ejes de variante que cambian color o estructura se convierten en componentes separados:
Button/Primary,Button/Secondary,Button/Outline,Button/Ghost,Button/Destructive. - Los ejes que solo cambian valores de token (tamaño, densidad) pueden ser un eje de tema en lugar de más componentes: variables numéricas temáticas como
button-padding-yybutton-padding-xconsize: md, sm, lg(el primer valor es el predeterminado). Un solo componente sirve entonces para cada tamaño a través detheme: {size: "sm"}en la instancia. Probado y funcionando. Úsalo cuando el código funcione de la misma manera; de lo contrario, crea también componentes de tamaño. - Un interruptor global (mostrar u ocultar cada insignia en los mockups) puede ser una variable booleana vinculada a
enabled: "$show-badge". Cambia cada instancia a la vez, así que guárdalo para alternativas de demostración, no para opciones por instancia. - Mantén el número razonable. Si las variantes por tamaños por estados supera unos 30 componentes, divide la familia o mueve un eje a un tema.
- Estados: un componente
DisabledoFocussolo cuando el usuario quiera mostrarlos; hover y presionado a menudo solo se documentan. - Los booleanos (con icono, con sugerencia) no son variantes: construye el componente completo y oculta partes por instancia con
enabled: false. - Los iconos no son variantes: un nodo de icono, intercambiado con una anulación
icon. - Las áreas de contenido libre son ranuras: un marco con
slot: [recommendedComponentIds],width: "fill_container"y una altura fija (por ejemploheight: 40). Una ranura vacía dimensionada porfit_contentse colapsa a cero y desaparece.
3b. Construye el componente base en una llamada: un marco con reusable: true, diseño, relleno, espacio, radio y rellenos todos desde variables, hijos con nombre (Label, Icon, Content). Captura su id y los ids de sus hijos en globales.
const pos = FindEmptySpace({width: 600, height: 200, direction: "right", padding: 80})
buttonsId = Insert(document, {type: "frame", name: "Buttons", layout: "vertical", gap: 24, padding: 32, x: pos.x, y: pos.y})
btnPrimaryId = Insert(buttonsId, {type: "frame", name: "Button/Primary", reusable: true, gap: 8, padding: ["$button-padding-y", "$button-padding-x"], cornerRadius: "$radius-md", fill: "$--primary", alignItems: "center", justifyContent: "center"})
btnIconId = Insert(btnPrimaryId, {type: "icon", name: "Icon", library: "lucide", icon: "plus", width: 16, height: 16, fill: "$--primary-foreground"})
btnLabelId = Insert(btnPrimaryId, {type: "text", name: "Label", content: "Button", fontFamily: "$--font-sans", fontSize: "$text-sm", fontWeight: "500", fill: "$--primary-foreground"})
TakeScreenshot([btnPrimaryId])
3c. Construye las otras variantes. Copy de un componente hace una instancia, no un nuevo componente. Para obtener componentes variantes independientes, reconstruye cada uno con una pequeña función auxiliar dentro de una llamada, iterando sobre una tabla de variantes:
const make = (name, fill, fg, stroke) => {
const id = Insert(buttonsId, {type: "frame", name, reusable: true, gap: 8, padding: ["$button-padding-y", "$button-padding-x"], cornerRadius: "$radius-md", fill, alignItems: "center", justifyContent: "center", ...(stroke ? {stroke, strokeWidth: 1} : {})})
Insert(id, {type: "icon", name: "Icon", library: "lucide", icon: "plus", width: 16, height: 16, fill: fg})
Insert(id, {type: "text", name: "Label", content: "Button", fontFamily: "$--font-sans", fontSize: "$text-sm", fontWeight: "500", fill: fg})
return id
}
btnSecondaryId = make("Button/Secondary", "$--secondary", "$--secondary-foreground")
btnOutlineId = make("Button/Outline", "$--background", "$--foreground", "$--border")
btnGhostId = make("Button/Ghost", "#00000000", "$--foreground")
Mantén los nombres de los hijos idénticos entre variantes (Label, Icon) para que las instancias puedan ser anuladas por nombre y un cambio de variante siga funcionando.
3d. Distribuye la familia en una cuadrícula legible dentro de su marco familiar: una fila por variante, una columna por tamaño o estado, con pequeños encabezados de texto. Usa marcos de fila con gap, nunca posiciones absolutas.
3e. Documéntala: un título y una nota de uso de dos o tres líneas en el marco familiar (cuándo usar cada variante, la regla de una acción principal).
3f. Verifícala:
- Verificación codificada en el marco familiar: sin rellenos hex excepto los transparentes deliberados (
#00000000funciona como relleno transparente para variantes fantasma). - El bloque
issues detectedde la llamada (marcos colapsados, ranuras vacías). La verificación de recortectx.problemsda falsas alarmas en versiones actuales: confirma con una captura de pantalla. - Prueba de instancia: inserta una instancia de cada variante en un marco de prueba, anula la etiqueta con un texto largo y oculta el icono, luego captúrala en claro y oscuro (
themeen el marco de prueba). Elimina el marco de prueba después.
Punto de control por componente: captura de pantalla, lista de variantes y los ids. No comiences el siguiente componente antes de la aprobación.
Fase 4. QA y biblioteca
- Auditoría de tokens: toda variable usada por un componente existe; toda variable temática tiene cada valor de tema.
- Auditoría de vinculación: sin colores hex ni espaciado bruto dentro de los componentes, excepto valores listados como deliberados.
- Contraste: texto contra su fondo en ambos temas (4.5:1 para texto de cuerpo, 3:1 para texto grande