design-systempor Alireza Rezvani

Design System Skill.

Uma skill do Claude Code e Codex para trabalho com marca e sistema de design: captura identidade de marca através de um assistente de 10 perguntas para documentos e apresentações futuras.

Marca e Sistemas de Design
Sistema de design

Baixar OpenDesign Ver guia de uso

alirezarezvani/claude-skills · markdown-html/skills/design-system/SKILL.mdSKILL.md

--- name: design-system description: Captures the user's brand identity once via a 10-question onboarding wizard (primary/accent HEX + heading + body Google Fonts + design style editorial/technical/minimal/playful + default output directory + syntax theme + TOC behavior + optional logo/company), validates body-text and link contrast against WCAG 2.2 AA, derives 12 CSS custom properties in HSL space, and stores the result for every markdown-html … --- ## When to invoke ## Onboarding question set (10 questions) ## Hard rules ## Derived 12-token palette ## Forcing-question library (Matt Pocock grill-with-docs pattern) ## Customization in use (worked example)

Metadados e títulos de seção lidos do arquivo upstream em 2026-09-14 · 11.234 caracteres no total

01 O que faz

O que o Skill design-system faz no Claude Code e no Codex

Resumo, fluxo de trabalho e resultados, todos lidos do SKILL.md do skill.

Do SKILL.mdLido em 14/09/2026 · não é uma execução registrada

Nos termos do próprio skill

O skill design-system é o proprietário compartilhado da marca no plugin markdown-html. Ele captura a identidade da marca uma única vez por meio de um assistente de onboarding de 10 perguntas — valores HEX de cor primária e de destaque, Google Fonts para títulos e corpo, um estilo de design (editorial, técnico, minimalista ou lúdico), diretório de saída padrão, tema de código, comportamento do sumário e, opcionalmente, nome e logotipo da empresa — depois valida o contraste do texto corrido e dos links conforme a WCAG 2.2 AA e deriva 12 propriedades personalizadas de CSS no espaço HSL.

Três ferramentas Python que usam apenas a biblioteca padrão cuidam do onboarding, do carregamento da configuração e da validação da paleta; a precedência é projeto sobre global sobre padrões internos. Todo conversor (md-document, md-review, md-slides) lê a configuração salva, então alterar um token altera todo documento renderizado.

O que ele produz

Um arquivo de configuração que guarda a marca e a paleta derivada, gravado globalmente ou dentro do projeto.
Doze propriedades personalizadas CSS embutidas no bloco de estilo de cada conversor, como --md-surface, --md-border, --md-link e --md-warn.
Um schema JSON para a configuração, fornecido como asset para validação.

Veja o exemplo de prompt ↗

Como funciona

01
Execute o onboarding uma vez
O skill é o proprietário compartilhado da marca no plugin markdown-html: md-document, md-review e md-slides consomem a configuração que ele grava, então uma única execução aplica a marca a toda conversão.
02
Responda às dez perguntas
O assistente registra default_output_dir, HEX primária e de destaque, fontes de título e de corpo, design_style, code_theme, toc.behavior e company_name e logo_url opcionais.
03
Deixe a validação condicionar o salvamento
brand_palette_validator.validate() roda após cada alteração, então o par é verificado de novo a cada edição de campo, e não apenas no fim do assistente.
04
Derive os doze tokens
derive_palette() calcula tokens como --md-surface com bg mais ou menos 4-6% de luminância e --md-text-muted como rgba(text, 0.68), e os armazena em derived_palette no mesmo arquivo de configuração.
05
Resolva a configuração por precedência
config_loader.py é o carregador importável que todo conversor chama antes de renderizar; ele mescla projeto, depois global, depois padrões internos, e respeita a variável de ambiente de bypass.
06
Substitua ou redefina sem interação
Além do assistente, onboard.py aceita --defaults, --set key=value, --scope project, --show e --reset, então campos de marca podem ser alterados ou apagados sem percorrer as perguntas outra vez.

02 Encontre o ideal para você

Quando usar a Skill design-system

Use a skill design-system no Claude Code ou Codex quando o trabalho for de marca e sistema de design deste tipo. Adequação e limites abaixo são retirados do arquivo da própria skill.

Boa Combinação

Um workspace em que alguém pede para converter markdown em HTML pela primeira vez, então o onboarding nunca rodou.
Um repositório que precisa de uma marca diferente do resto do seu trabalho e não deve herdar a configuração global.
Uma CI ou sessão efêmera que precisa de padrões sem toque, em vez de dez perguntas interativas.
Você já tem pelo menos um HEX de marca que quer aplicar de forma consistente em todas as conversões para HTML.
Você quer testar uma primária e um destaque candidatos em relação ao WCAG antes de gravá-los na configuração.

Conheça os Limites

Não é um sistema completo de design tokens como Style Dictionary ou Theo; ele traz doze tokens, não cem.
Ele não hospeda fontes personalizadas — o Google Fonts via CDN é a única fonte de tipografia.
Não é uma suíte de auditoria de acessibilidade; axe-core ou pa11y cobrem isso, e o skill verifica apenas contraste.
Ele não transforma o CSS existente — a paleta derivada é injetada apenas no HTML recém-gerado.

O Que Fornecer

Diretório de saída padrãoUm caminho que precisa ser gravável; o padrão é ./markdown-html-out/ e um valor vazio ou sem permissão de escrita impede o salvamento.
HEX primário da marcaValidado contra ^#?[0-9a-fA-F]{6}$; padrão #0A1628. A biblioteca de perguntas forçadas recomenda um HEX que você já usa, não um azul genérico de estoque.
HEX de destaque, ou vazioDeixe em branco na primeira execução para que a derivação produza uma cor complementar; defina-o explicitamente apenas se um kit de marca especificar um.
Nomes das fontes de título e corpoNomes de Google Font escolhidos entre 12 padrões seguros, com Inter como padrão para ambas as funções.
Nome da empresa e URL do logo (opcionais)Ambos assumem strings vazias por padrão; a URL do logo pode ficar em branco e é incorporada em base64 no momento da renderização.

03 Dentro da skill

Regras que a skill design-system dá ao Claude Code e ao Codex

7 instruções concretas, padrões e limites que o SKILL.md define para o agente — a parte do arquivo que muda o resultado.

O contraste precisa passar, ou nada se salva
O texto do corpo sobre o fundo e os links sobre o fundo devem alcançar 4.5:1 conforme WCAG 2.2 §1.4.3.
O diretório de saída deve ter permissão de escrita
O assistente sobe até um ancestral existente e verifica os.access(parent, os.W_OK); um caminho vazio ou sem permissão de escrita encerra com o código 3, e output_path_resolver.py aplica a mesma regra em cada conversão.
A personalização deve alterar o resultado
Campos meramente decorativos falham na disciplina de design: cada consumidor precisa ler a configuração e renderizar de forma diferente quando design_style, brand.primary, code_theme ou toc.behavior mudam.
A precedência é fixa
A configuração do projeto tem prioridade sobre a configuração global, que tem prioridade sobre os padrões integrados, e o deep-merge preserva as chaves aninhadas, então sobrescrever brand.primary em um projeto não descarta typography.heading_font do global.
Bypass é apenas para execuções headless
MARKDOWN_HTML_NO_CONFIG=1 atende a CI, contêineres de teste efêmeros e loops de avaliação; nunca o defina silenciosamente para um usuário interativo, que vai ficar sem entender para onde foram seus tokens.
Nunca use uma cor primária vibrante como fundo
Uma cor primária de marca saturada usada diretamente como brand.bg produz baixo contraste de texto; ela deveria estar no slot de accent.
Permaneça Dentro da Taxonomia de 12 Tokens
A semântica da marca não é codificada em derived_palette além desses doze tokens; adicionar um novo exige um nome, propósito e regra de derivação deliberados.

04 Coloque em prática

Instalar design-system no Claude Code ou Codex

Um comando npx skills add, depois uma primeira tarefa no seu agente e uma checklist para o resultado.

Adicionar design-system ao Claude Code, Codex ou Seu Agente

Rode no seu projeto; o instalador pergunta a qual agente adicioná-lo.

Terminal

npx skills add https://github.com/alirezarezvani/claude-skills --skill design-system

Formulário genérico de CLI de skills para markdown-html/skills/design-system/SKILL.md; o repositório pode documentar seu próprio caminho.

Dê ao Skill uma primeira tarefa de marca e design-system

Escrito nos próprios termos do skill; substitua as partes entre colchetes pelo seu material.

Starter prompt

Set up the brand for this repo: primary #FF6B35, Inter for headings and body, editorial style, sticky-sidebar TOC, and save it per-project. Point the default output at [output directory] and then convert [document.md] with md-document so it comes out branded.

Fonte: escrito a partir do SKILL.md nos próprios termos do skill.

Verifique o Primeiro Resultado

O que o próprio SKILL.md diz sobre como é um resultado correto:

Inspecione a configuração efetiva com config_loader.py --show, que resolve o projeto sobre o global sobre os padrões.
Confirme que o arquivo de configuração existe e que setup_completed_at está definido; se estiver ausente ou nulo, o conversor se recusa e exibe o onboarding em vez disso.
Confira rapidamente o contraste de um par candidato com brand_palette_validator.py --primary e --accent antes de assumir uma marca.
Verifique se o bypass se comporta como documentado executando com MARKDOWN_HTML_NO_CONFIG=1, que retorna apenas DEFAULTS.

No OpenDesign, importe o design-system pelo link do SKILL.md: Plugins → Add → Skill → Import from link, depois selecione-o na barra superior.

Baixar OpenDesign Ler o quickstart

05 Código aberto, rastreável

Fonte, Licença e Verificação

De onde vêm os fatos desta página e quando foram verificados pela última vez.

Author: Alireza Rezvani
Repository: github.com/alirezarezvani/claude-skills Branch main
Arquivo da skill: markdown-html/skills/design-system/SKILL.md Checksum de conteúdo registrado na verificação; commit 19392f7
License: MIT De LICENSE; SKILL.md indica "MIT".
Estrelas do repositório: 25.934 Snapshot do GitHub tirado em 14/09/2026 para todo o repositório alirezarezvani/claude-skills, que contém 5 skills neste catálogo. Não é uma avaliação ou contagem de uso da design-system.
Verificado pelo OpenDesign: 14/09/2026 Arquivo de origem, caminho, texto da licença e contagem de estrelas foram verificados. Não integrado ao OpenDesign principal (verificado em 28/08/2026); uma execução ao vivo não foi registrada nesta página.

Dentro do SKILL.md

Quando invocarTabela de sintoma para ação: onboarding, recusar conversão, escopo de projeto, definir campo único, reset, padrões, bypass.
Conjunto de perguntas de onboarding (10 perguntas)Tabela das dez chaves, validadores e padrões, do diretório de saída até a URL do logo.
Regras rígidasCinco regras numeradas: barreira WCAG AA, diretório gravável, personalização real, precedência fixa, bypass deliberado.
Paleta derivada de 12 tokensTabela que mapeia cada propriedade personalizada do CSS ao seu propósito e à sua regra de derivação HSL.
Biblioteca de perguntas forçadas (padrão grill-with-docs de Matt Pocock)Cinco perguntas, uma por turno, com respostas recomendadas e citações do cânone.
Personalização em uso (exemplo prático)Bloco Bash mostrando onboarding, padrões, set, escopo de projeto, reset, show e bypass.
PremissasQuatro pré-condições: um HEX de marca, configuração de um a dois minutos, Google Fonts, piso WCAG AA.
Não objetivosO que ele não é: sistema de tokens, hospedagem de fontes, alternador de modo escuro, suíte de auditoria, transformador de CSS.
Diferente deContrasta este validador e o script de onboarding com as versões de landing page e de pesquisa clínica.
Artefato de saídaNomeia os caminhos JSON global e de projeto, além do ativo de schema.
Antipadrões (não faça)Quatro falhas a evitar: pular o onboarding, fundo vibrante, bypass silencioso, tokens fora da taxonomia.
ReferênciasCláusulas WCAG, livros de tipografia e de cor, orientação sobre TOC, scripts irmãos.

A Descrição da Própria Skill

"Captura a identidade de marca do usuário uma vez através de um assistente de onboarding de 10 perguntas (HEX primário/accent + fontes Google de título + corpo + estilo de design editorial/técnico/minimal/divertido + diretório de saída padrão + tema de sintaxe + comportamento de TOC + logo/empresa opcional), valida contraste de texto do corpo e links contra WCAG 2.2 AA, deriva 12 propriedades personalizadas CSS em espaço HSL e armazena o resultado para todo conversor markdown-html consumir. Use antes de qualquer conversão markdown-html. Ativa no onboarding inicial ("configurar a marca", "configurar markdown-html", "executar onboarding"), no reset explícito ("resetar o sistema de design", "refazer o onboarding"), e é verificado por todo conversor via config_loader.py antes da renderização. Recusa salvar se o contraste de texto do corpo falhar em AA 4.5:1 ou o diretório de saída não for gravável. A precedência é projeto (./.markdown-html/) > global (~/.config/markdown-html/) > padrões integrados; MARKDOWN_HTML_NO_CONFIG=1 ignora."

Descrição do front-matter do SKILL.md. O arquivo completo tem cerca de 11.234 caracteres. Leia o arquivo completo no GitHub.

06 Antes de instalar

Perguntas sobre o skill design-system

As respostas vêm do SKILL.md conforme lido em 2026-09-14, e não de uma execução registrada.

Preciso concluir o onboarding antes de converter alguma coisa?

Os conversores verificam a configuração por meio do config_loader.py e, se ela estiver ausente ou setup_completed_at for null, a conversão é recusada e o onboarding é exibido. Até você concluir a configuração, a saída é renderizada com padrões provisórios: tecnicamente funcional, mas sem identidade de marca.

Design System

Execute design-system em uma marca real e uma tarefa de trabalho com design-system.

Baixe o OpenDesign, importe design-system a partir do link SKILL.md, cole o prompt acima e leia o plano antes do resultado.

Baixar OpenDesign Ver todas as skills