pencil-generate-library: tokens, temas e componentes em ordem
Construa um sistema de design em um arquivo .pen que corresponda ao código. Carregue pencil-use primeiro: ele contém as regras de execute. Esta skill contém a ordem do trabalho e as decisões do sistema de design.
1. A regra que mais importa
Isso nunca é uma única chamada. Um sistema pequeno leva de 15 a 40 chamadas execute, um maior muito mais. Trabalhe na menor unidade útil, verifique-a, mostre-a e depois continue. Um sistema construído em um único trecho longo sai quebrado e é difícil de reparar.
2. Como o Pencil difere de outras ferramentas
Planeje com o modelo real do Pencil, não um emprestado de outro lugar:
| Necessidade | No Pencil |
|---|---|
| Tokens | variables do documento do tipo color, number, string, boolean, referenciadas como $name |
| Modos (claro, escuro) | Eixos de tema. O valor de uma variável é uma lista de {value, theme: {mode: "dark"}}; um quadro escolhe um valor com sua propriedade theme |
| Alias (semântico para primitivo) | Uma variável cujo valor é outra variável: value: "$gray-900" |
| Estilos de texto | Nenhum. Use variáveis de fonte (família, tamanho, altura da linha, peso como strings ou números) e, se útil, pequenos componentes de texto |
| Estilos de sombra | Nenhum. Efeitos de sombra aceitam variáveis para cor, desfoque e deslocamento |
| Componente | Qualquer nó com reusable: true |
| Variantes | Sem conjuntos de variantes. Um componente por variante, nomeado com barras: Button/Primary, Button/Outline |
| Opção booleana (mostrar ícone) | Substituição de instância enabled: false nessa parte |
| Ícone substituível | Substituição de instância no nó do ícone: {icon: "plus"} |
| Conteúdo substituível | Um quadro slot dentro do componente, com IDs de componentes recomendados |
| Biblioteca compartilhada | Um arquivo convertido para .lib.pen no aplicativo (uma via, não pode ser desfeito), importado por arquivos de tela |
3. Fluxo de trabalho
Fase 0 DESCOBERTA ler código e arquivo, sem escrever -> checkpoint: plano aprovado
Fase 1 FUNDAMENTOS variáveis e temas -> checkpoint: resumo de tokens aprovado
Fase 2 LAYOUT DO ARQUIVO áreas na tela, quadro de fundamentos -> checkpoint: captura de tela do quadro aprovada
Fase 3 COMPONENTES um de cada vez, átomos antes de moléculas -> checkpoint após cada componente
Fase 4 QA E BIBLIOTECA auditorias, correções, .lib.pen opcional -> checkpoint: aprovação final
Nomeie a próxima fase em cada checkpoint. Um "parece bom" sobre os tokens não é aprovação para começar os componentes.
Fase 0. Descoberta (somente leitura)
0a. Encontre os tokens no código, nesta ordem:
- Propriedades personalizadas CSS (
:root { --background: ... },.dark { ... }ou[data-theme="dark"]). - Configuração do Tailwind ou blocos
@themedo Tailwind v4. - Arquivos de token (DTCG
.tokens.json, Style Dictionary). - Objetos de tema em CSS-in-JS ou arquivos de tema nativos (catálogos de ativos iOS,
colors.xmldo Android).
Anote o mecanismo de modo escuro, as escalas de espaçamento e raio, fontes e escala tipográfica, e sombras.
0b. Encontre os componentes no código: a lista de primitivos de UI (Button, Input, Checkbox, Badge, Avatar, Card...), suas props, quais props são variantes (variant, size, state), quais são booleanos, quais recebem filhos.
0c. Leia o arquivo:
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() } })
Também verifique get_app_state para bibliotecas importadas. Corresponda qualquer nomenclatura já existente no arquivo.
0d. Trave o escopo com o usuário: a lista exata de tokens e a lista exata de componentes para esta rodada. Uma primeira rodada de seis a dez componentes é um bom tamanho.
0e. Mapeie o código para o Pencil e resolva conflitos. Apresente uma tabela:
Token do código Variável Pencil Claro Escuro Status
--background --background #FFFFFF #0A0A0A novo
--primary --primary #1D4ED8 #3B82F6 existe, valor difere (perguntar)
Componente Componentes Pencil Status
Button variant x size Button/Primary, Button/Secondary, Button/Outline, Button/Ghost (tamanho via eixo de tema) novo
Quando código e arquivo discordarem, pergunte qual ganha. Não decida sozinho.
Checkpoint: mostre o plano, aguarde aprovação.
Fase 1. Fundamentos
Nomenclatura. Mantenha os nomes do código para que design e código façam ida e volta: uma variável CSS --muted-foreground se torna a variável Pencil --muted-foreground, referenciada como $--muted-foreground. Nunca comece um nome com $. Evite : em nomes. Se o código não tiver nomes, use nomes kebab curtos por função: surface, text, text-muted, border, accent, space-4, radius-md.
Camadas.
- Primitivos: valores brutos, sem tema (
gray-50...gray-950,blue-500,space-1...space-16). - Semânticos: nomes de função, temáticos, apontando para primitivos (
--background: claro$white, escuro$gray-950). - Componentes usam apenas semânticos. Um componente que referencia
$gray-900diretamente não alternará com o tema.
Tamanho do sistema.
- Abaixo de cerca de 50 tokens: um conjunto plano, um eixo
modecomlightedark. - Maior: primitivos mais semânticos como acima, e eixos de tema extras apenas quando o código realmente os tiver (
density: comfortable, compact;brand: a, b).
Escreva em pequenos lotes, uma família por chamada (cores primitivas, depois cores semânticas, depois espaçamento e raio, depois tipografia), e leia de volta:
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))
- Verifique se o primeiro valor do eixo
modeé o padrão que o produto usa (geralmentelight). - Dê a cada variável temática um valor para cada valor de tema que você usa. Um valor ausente mostra a cor errada silenciosamente.
- Mantenha valores idênticos entre temas quando não devem mudar (espaçamento, raio).
- Tipografia:
--font-sans(string), tamanhos (text-sm14,text-base16...), alturas de linha como proporções (leading-normal1.5), pesos como strings ("400","600"). - Sombras: uma variável de cor temática para a sombra e variáveis numéricas para desfoque e deslocamento se o código tiver uma escala de sombra.
- Nunca
SetVariables(..., true)em um arquivo existente sem consentimento explícito: isso apaga todas as variáveis.
Critérios de saída: cada token no plano existe com o tipo correto, cada token temático tem cada valor de tema, aliases apontam para variáveis existentes.
Checkpoint: mostre contagens por família, eixos de tema e qualquer valor que você teve que adivinhar.
Fase 2. Layout do arquivo e quadro de fundamentos
Mantenha a tela legível:
- Um quadro Fundamentos no canto superior esquerdo: amostras de cores, espécimes de tipografia, barras de espaçamento, amostras de raio.
- Uma área Componentes à sua direita ou abaixo, um quadro por família de componente (
Buttons,Inputs,Cards), contendo os componentes com um título e uma nota de uso curta. - Telas mais abaixo e à direita, nunca misturadas com componentes.
- Use
FindEmptySpacepara cada quadro raiz.
Amostras e espécimes devem estar vinculados a variáveis, para que o quadro atualize quando um token mudar. Construa amostras com um loop:
boardId = Insert(document, {type: "frame", name: "Fundamentos / Cor", layout: "vertical", gap: 16, padding: 32, fill: "$--background", x: 0, y: 0})
rowId = Insert(boardId, {type: "frame", name: "Cores semânticas", gap: 16})
for (const name of ["--background", "--foreground", "--primary", "--muted", "--border"]) {
const s = Insert(rowId, {type: "frame", name: "Amostra " + 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])
Em seguida, copie o quadro com theme: {mode: "dark"} ao lado dele: se algo permanecer claro, um token está faltando seu valor escuro.
Checkpoint: captura de tela dos quadros em ambos os temas.
Fase 3. Componentes, um de cada vez
Ordem por dependência: átomos primeiro (wrappers de ícone, Badge, Avatar, Button, Input, Checkbox, Toggle), depois moléculas (grupo Input com rótulo e dica, item de Menu, Tab), depois organismos (Card, Dialog, Sidebar, linha de Tabela). Um componente que contém outro deve ser construído depois dele e deve conter uma instância dele, não uma cópia redesenhada.
Para cada componente:
3a. Projete a API antes de desenhar. Das props do código:
- Eixos de variante que mudam cor ou estrutura tornam-se componentes separados:
Button/Primary,Button/Secondary,Button/Outline,Button/Ghost,Button/Destructive. - Eixos que apenas alteram valores de token (tamanho, densidade) podem ser um eixo de tema em vez de mais componentes: variáveis numéricas temáticas como
button-padding-yebutton-padding-xcomsize: md, sm, lg(o primeiro valor é o padrão). Um componente então atende a todos os tamanhos através detheme: {size: "sm"}na instância. Testado e funcionando. Use quando o código funciona da mesma forma; caso contrário, faça também componentes de tamanho. - Uma alternância global (mostrar ou ocultar cada badge nos mockups) pode ser uma variável booleana vinculada a
enabled: "$show-badge". Ela muda todas as instâncias de uma vez, então mantenha-a para alternâncias de demonstração, não para opções por instância. - Mantenha a contagem sã. Se variantes vezes tamanhos vezes estados ultrapassar cerca de 30 componentes, divida a família ou mova um eixo para um tema.
- Estados: um componente
DisabledouFocusapenas quando o usuário quiser mostrá-los; hover e pressionado geralmente são apenas documentados. - Booleanos (com ícone, com dica) não são variantes: construa o componente completo e oculte partes por instância com
enabled: false. - Ícones não são variantes: um nó de ícone, trocado com uma substituição
icon. - Áreas de conteúdo livre são slots: um quadro com
slot: [recommendedComponentIds],width: "fill_container"e uma altura fixa (por exemplo,height: 40). Um slot vazio dimensionado porfit_contentcolapsa para zero e desaparece.
3b. Construa o componente base em uma chamada: um quadro com reusable: true, layout, padding, gap, raio e preenchimentos todos de variáveis, filhos nomeados (Label, Icon, Content). Capture seu id e os ids de seus filhos em globais.
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. Construa as outras variantes. Copy de um componente faz uma instância, não um novo componente. Para obter componentes de variante independentes, reconstrua cada um com uma pequena função auxiliar dentro de uma chamada, iterando sobre uma tabela 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")
Mantenha os nomes dos filhos idênticos entre as variantes (Label, Icon) para que as instâncias possam ser substituídas por nome e uma troca de variante continue funcionando.
3d. Organize a família em uma grade legível dentro de seu quadro de família: uma linha por variante, uma coluna por tamanho ou estado, com pequenos cabeçalhos de texto. Use quadros de linha com gap, nunca posições absolutas.
3e. Documente-a: um título e uma nota de uso de duas ou três linhas no quadro da família (quando usar qual variante, a regra de uma ação primária).
3f. Verifique-a:
- Verificação codificada no quadro da família: nenhum preenchimento hex, exceto transparentes deliberados (
#00000000funciona como um preenchimento transparente para variantes ghost). - O bloco
issues detectedda chamada (quadros recolhidos, slots vazios). A verificação de recortectx.problemsdá falsos alarmes nas versões atuais: confirme com uma captura de tela. - Teste de instância: insira uma instância de cada variante em um quadro de rascunho, substitua o rótulo por um texto longo e oculte o ícone, depois tire uma captura de tela no claro e no escuro (
themeno quadro de rascunho). Exclua o quadro de rascunho depois.
Checkpoint por componente: captura de tela, lista de variantes e os ids. Não comece o próximo componente antes da aprovação.
Fase 4. QA e biblioteca
- Auditoria de token: toda variável usada por um componente existe; toda variável temática tem todos os valores de tema.
- Auditoria de vínculo: nenhuma cor hex ou espaçamento bruto dentro dos componentes, exceto valores listados como deliberados.
- Contraste: texto contra seu fundo em ambos os temas (4.5:1 para texto do corpo, 3:1 para texto grande ...
[truncado para tradução]