Communitygithub.com

pencil-generate-library

Fluxo de trabalho para construir ou atualizar um sistema de design real no Pencil (pen.dev), geralmente a partir de uma base de código: variáveis (cores, espaçamento, raio, tipografia), temas claro e escuro, componentes reutilizáveis, suas variantes e estados, slots, um quadro de fundamentos e uma biblioteca de design .lib.pen opcional.

O que é pencil-generate-library?

Esta skill organiza a criação ou sincronização de um design system completo no Pencil (pen.dev) a partir de um codebase existente. Ela define uma sequência lógica de fases: descoberta (leitura do código e arquivo .pen), fundamentos (variáveis e temas), layout do arquivo (quadro de fundamentos), componentes (um por vez, átomos antes de moléculas) e QA/biblioteca. Diferente de ferramentas que tratam design tokens como um único passo, esta skill enfatiza a construção incremental e iterativa, com checkpoints frequentes entre cada fase. O fluxo é projetado para ser executado em múltiplas chamadas de API (15 a 40 ou mais), garantindo que cada parte funcione antes de prosseguir. A skill é compatível com CSS custom properties, Tailwind, DTCG tokens, CSS-in-JS e temas nativos. Ela mapeia corretamente conceitos de código para o modelo do Pencil, onde tokens são variáveis com modos por eixos de tema, variantes são componentes separados com nomes de barra (Button/Primary), e opções booleanas são substituições de instância. O resultado é um design system funcional que reflete fielmente o código, com variáveis, temas e componentes que podem ser reutilizados em telas.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/alekpixel/pencil-skills/tree/main/skills/pencil-generate-library

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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:

NecessidadeNo Pencil
Tokensvariables 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 textoNenhum. 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 sombraNenhum. Efeitos de sombra aceitam variáveis para cor, desfoque e deslocamento
ComponenteQualquer nó com reusable: true
VariantesSem 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ívelSubstituição de instância no nó do ícone: {icon: "plus"}
Conteúdo substituívelUm quadro slot dentro do componente, com IDs de componentes recomendados
Biblioteca compartilhadaUm 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:

  1. Propriedades personalizadas CSS (:root { --background: ... }, .dark { ... } ou [data-theme="dark"]).
  2. Configuração do Tailwind ou blocos @theme do Tailwind v4.
  3. Arquivos de token (DTCG .tokens.json, Style Dictionary).
  4. Objetos de tema em CSS-in-JS ou arquivos de tema nativos (catálogos de ativos iOS, colors.xml do 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-900 diretamente não alternará com o tema.

Tamanho do sistema.

  • Abaixo de cerca de 50 tokens: um conjunto plano, um eixo mode com light e dark.
  • 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 (geralmente light).
  • 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-sm 14, text-base 16...), alturas de linha como proporções (leading-normal 1.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 FindEmptySpace para 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-y e button-padding-x com size: md, sm, lg (o primeiro valor é o padrão). Um componente então atende a todos os tamanhos através de theme: {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 Disabled ou Focus apenas 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 por fit_content colapsa 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 (#00000000 funciona como um preenchimento transparente para variantes ghost).
  • O bloco issues detected da chamada (quadros recolhidos, slots vazios). A verificação de recorte ctx.problems dá 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 (theme no 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

  1. Auditoria de token: toda variável usada por um componente existe; toda variável temática tem todos os valores de tema.
  2. Auditoria de vínculo: nenhuma cor hex ou espaçamento bruto dentro dos componentes, exceto valores listados como deliberados.
  3. 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]

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

Habilidades Relacionadas