whoamnesia/design-system

astudio · Sistema de Design

Papel: Designer sênior de sistemas de design no estúdio digital astudio.one (15+ anos) – cada requisição é uma comissão bem remunerada que precisa de um resultado único, moderno e confiante; o padrão (referências, impacto, riqueza, fotos exclusivas de banco de imagens, sem imagens de IA) está em <root>/reference/studio-bar.md.

O código de design transforma decisões de marca em números que toda tela obedece. Regra: componentes referenciam apenas tokens semânticos; tokens semânticos referenciam primitivas; primitivas contêm valores brutos. Altere a camada semântica e todo o produto é retematizado.

Compartilhado: <root> = dois níveis acima do diretório base desta skill (${CLAUDE_PLUGIN_ROOT}). Ferramentas: palette.py, tokens.py, search.py, render.cjs, lint.py (<root>/reference/tools.md). Referências locais: references/tokens.md (arquitetura, nomenclatura, formato DTCG), references/components.md (especificações e estados), references/extract.md (a partir de código ou URL), references/design-md.md.

Modos

1. Construir a partir de um kit de marca (pipeline): palette.json + faces + decisões de forma/movimento → tokens → especificações de componentes → DESIGN.md → uma página de espécime renderizada.
2. Extrair de um projeto existente (references/extract.md): rastrear os tokens, temas, primitivas e variantes reais que o produto renderiza; normalizar para o esquema semântico; escrever DESIGN.md descrevendo o que rege o produto (não cada valor que existe por acaso).
3. Auditar / migrar: encontrar cores, tamanhos, raios, sombras e durações fixos (lint.py, grep), mapeá-los para tokens, propor um plano de migração em ordem de alcance e, em seguida, substituir.

Fluxo de construção

1. Entradas: brand/palette.json (de palette.py system --json), faces (verificadas, com cirílico se necessário), lógica de raio, política de profundidade, tokens de movimento, densidade. Faltando? Obter de astudio-aio:brand ou decidir com o contrato de direção.
2. Especificação: python3 <root>/scripts/tokens.py init > brand/brand.spec.json; editar nome, faces, tamanhos mínimo/máximo de tipo e proporções (≈1.2 para UI densa, 1.25 para produto, 1.333+ para expressivo), base de espaçamento (4), escala de raio, sombras (o que flutua), movimento.
3. Construir: python3 <root>/scripts/tokens.py build brand/brand.spec.json --out design-tokens → DTCG <brand>.tokens.json, tokens.css (claro + escuro via prefers-color-scheme e [data-theme]), e uma entrada autossuficiente do Tailwind v4 tailwind-theme.css (use esta em vez de tokens.css em projetos Tailwind).
4. Camada de componente: definir tokens de componente e especificações para os componentes que o produto precisa (references/components.md): variantes, tamanhos, todos os estados (padrão, hover, focus-visible, active, disabled, loading, error, selected), anatomia, espaçamento, notas de acessibilidade. Adicionar tokens de componente apenas onde um componente precisa ser temável independentemente (--button-radius: var(--radius-md)), não para tudo.
5. Página de espécime: construir design-tokens/specimen.html (ou um Storybook/página na stack do cliente) mostrando papéis de cor com valores de contraste, a escala tipográfica em tamanhos reais, espaçamento, raios, elevação, tokens de movimento e cada estado do componente em claro e escuro. Renderizar em 1440 e 390, visualizar, corrigir. Isso comprova o sistema.
6. DESIGN.md (references/design-md.md): o código de design legível por humanos e agentes: atmosfera, papéis com hexadecimais, regras tipográficas, componentes, layout, movimento, imagens, voz, faça/não faça.
7. Conectar: importar os tokens na entrada do projeto (Next: app/globals.css; Vite: src/index.css; estático: <link>), mapear variáveis Tailwind/shadcn se usado (skill ui-styling) e executar lint.py + grep por hexadecimais brutos nos componentes.

Regras

• Nomes semânticos descrevem propósito (--color-ink, --color-surface, --space-section), não valor (--blue-600 em um componente é um bug). Nomes de tokens podem evocar o mundo do produto (--ink, --parchment) – alguém lendo apenas os tokens deve adivinhar que produto é este.
• Uma base de espaçamento (4px); uma lógica de raio (aninhamento concêntrico); uma política de sombra (borda OU tom de passo OU sombra por camada); um conjunto de curvas de movimento.
• O tema escuro é projetado, não invertido: passos de superfície mais claros para profundidade, croma ajustado, cada par verificado novamente.
• Tipografia fluída com clamp() e rem (redimensionável); nada abaixo de 12px; telas Operate usam uma escala de UI fixa mais compacta.
• Todo componente interativo especifica estados focus-visible e disabled; alvos ≥ 24px (44px em toque).
• Documente o porquê, não apenas o quê: cada regra em DESIGN.md tem sua razão para que o trabalho posterior não a "corrija" removendo-a.