ckm:design-system

Visão geral

O que é ckm:design-system?

ckm:design-system é uma skill de design system que reúne arquitetura de design tokens, especificações de componentes e geração de slides de apresentação em um único fluxo de trabalho reutilizável.

Ela é estruturada em um modelo de tokens com três camadas (primitive → semantic → component), com referências e scripts de apoio para:

• Sistemas de variáveis CSS
• Escalas de espaçamento e tipografia
• Estados e variantes de componentes
• Configuração de tema Tailwind
• Layouts sistemáticos de slides e pitch decks

A skill inclui tabelas de dados e templates opinativos para fundos de slides, lógica de cores, fórmulas de texto, layouts e estratégias de narrativa, além de scripts para gerar e validar tokens e estruturas de slides.

Para quem é esta skill?

ckm:design-system é voltada para:

• Líderes de design system e designers UI/UX que querem uma arquitetura clara de tokens e uma referência de especificação de componentes.
• Desenvolvedores frontend e React/Tailwind que precisam de um pipeline robusto de tokens (variáveis CSS, validadores, dicas de integração com Tailwind).
• Founders, PMs e profissionais de marketing que criam pitch decks com frequência e preferem frameworks de slides repetíveis e consistentes com a marca, em vez de começar do zero.

Se você quer conectar o pensamento de design tipo Figma a tokens prontos para implementação e a um sistema de slides reutilizável, esta skill é uma ótima opção.

Que problemas ela resolve?

ckm:design-system ajuda você a:

• Padronizar design tokens com camadas documentadas de primitive → semantic → component.
• Gerar tokens CSS a partir de JSON e validar seu uso no seu codebase.
• Planejar temas Tailwind usando a mesma arquitetura de tokens.
• Definir especificações de componentes, incluindo estados e variantes, para manter a UI consistente entre telas.
• Criar apresentações consistentes com a marca usando layouts de slides pré-definidos, recomendações de gráficos, lógica de cor e emoção e fórmulas de copy.

Ela oferece uma forma estruturada de pensar tanto a sua UI quanto seus slides como sistemas, não como peças isoladas.

Quando ckm:design-system é um bom encaixe?

Use esta skill quando:

• Você está introduzindo ou refatorando um design system e quer camadas explícitas de tokens.
• Precisa de orientação de variáveis CSS e Tailwind conectada à arquitetura de tokens.
• Quer gerar e validar design tokens em vez de gerenciá-los manualmente.
• Você monta pitch decks, apresentações de vendas ou demos de produto com frequência e quer uma estrutura de slides repetível.

Ela é menos indicada se você só precisa de um mock de UI estático ou se não usa tokens nem variáveis CSS.

Como usar

Instalação e configuração básica

1. Instale a skill ckm:design-system

Instale a skill no seu ambiente de Agent/skills:

npx skills add https://github.com/nextlevelbuilder/ui-ux-pro-max-skill --skill design-system

Este comando busca a skill design-system no repositório nextlevelbuilder/ui-ux-pro-max-skill para o seu diretório local de skills.

2. Explore os arquivos principais

Após a instalação, abra a pasta da skill e comece por:

• SKILL.md – Visão geral, quando usar a skill, arquitetura de tokens e comandos de quick start.
• references/ – Documentação conceitual sobre tokens, componentes, variantes e integração com Tailwind.
• data/ – Arquivos CSV que codificam fundos de slides, lógica de cores, fórmulas de copy, layouts, tipografia e estratégias.
• scripts/ – Scripts utilitários para gerar, embedar e validar tokens, além de helpers de busca de slides.
• templates/design-tokens-starter.json – Template JSON inicial para definir seu próprio conjunto de tokens.

Essa estrutura ajuda você a decidir rapidamente que partes adotar: apenas tokens, apenas slides ou o sistema completo.

Desenhando sua arquitetura de tokens

3. Entenda o modelo de tokens em três camadas

SKILL.md e references/token-architecture.md descrevem uma estrutura em três etapas:

Primitive (raw values)
       ↓
Semantic (purpose aliases)
       ↓
Component (component-specific)

Use os arquivos de referência para desenhar cada camada:

• references/primitive-tokens.md – Cores base, espaçamentos, raios, primitivos de tipografia.
• references/semantic-tokens.md – Tokens orientados a propósito, como --color-primary, --surface-elevated, --text-muted.
• references/component-tokens.md – Variáveis em nível de componente, como --button-bg, --card-border, --badge-pill-radius.

Essa separação facilita:

• Trocar temas sem reescrever componentes.
• Manter detalhes de implementação (variáveis CSS, config do Tailwind) alinhados com a linguagem de design.

4. Crie ou adapte seu JSON de tokens

Use templates/design-tokens-starter.json como base para o seu arquivo de tokens.

Fluxo típico:

1. Copie templates/design-tokens-starter.json para o seu projeto como tokens.json.
2. Preencha primeiro os valores primitivos (cores, espaçamentos, tamanhos de fonte).
3. Mapeie os primitivos para papéis semânticos (primary, secondary, surface, border etc.).
4. Mapeie tokens semânticos para tokens de componente para cada elemento-chave da UI.

Consulte:

• references/component-specs.md – Para pensar em como os componentes consomem tokens.
• references/states-and-variants.md – Para estados e variações de hover, focus, disabled, error etc.

Gerando e validando tokens

5. Gere variáveis CSS a partir dos tokens

Use o script de geração de tokens descrito em SKILL.md:

node scripts/generate-tokens.cjs --config tokens.json -o tokens.css

• --config aponta para o seu JSON de tokens (por exemplo, tokens.json).
• -o define o arquivo CSS de saída (por exemplo, tokens.css).

O resultado é um arquivo CSS que define seu conjunto de tokens como --custom-properties, pronto para ser importado no seu frontend.

6. Valide o uso de tokens no seu codebase

Para garantir que seu código use apenas tokens aprovados, rode o validador de tokens:

node scripts/validate-tokens.cjs --dir src/

Ele inspeciona o diretório informado (por exemplo, src/) em busca de padrões de uso de tokens e ajuda você a:

• Encontrar valores hard-coded que deveriam ser tokens.
• Identificar tokens obsoletos ou não definidos.

Validadores adicionais em scripts/ incluem:

• html-token-validator.py – Para escanear HTML em busca de padrões de uso de tokens.
• slide-token-validator.py – Para validar uso de tokens em contextos relacionados a slides.

Use esses scripts para manter sua UI e seus slides alinhados com o design system.

7. Faça embed de tokens onde necessário

Se o seu ambiente exige embedar tokens em documentação ou HTML, você pode usar:

• scripts/embed-tokens.cjs – Faz embed dos tokens em arquivos alvo.

Veja os comentários inline no script e em SKILL.md para orientações de uso específicas do seu setup.

Tailwind e considerações de implementação

8. Planeje a integração com Tailwind

A skill inclui uma referência específica para Tailwind:

• references/tailwind-integration.md – Orientação sobre como mapear nomes e escalas de tokens em uma configuração de tema Tailwind.

Use esse material para:

• Mapear tokens primitive/semantic para as escalas de colors, spacing e fontSize do Tailwind.
• Manter as utility classes do Tailwind alinhadas ao seu design de tokens (por exemplo, uma paleta primary derivada dos primitivos).

Mesmo que você não use Tailwind agora, essa referência é útil para pensar como seu sistema de tokens escalará para CSS utility-first.

Construindo slide decks sistematizados

Embora o foco principal seja design systems, ckm:design-system também dá suporte a design de apresentações estruturadas.

9. Use as tabelas de dados de slides para layout e visuais

O diretório data/ contém arquivos CSV que codificam padrões de slides baseados em boas práticas:

• data/slide-backgrounds.csv – Tipos recomendados de imagem de fundo, overlays e posicionamento por tipo de slide (hero, vision, team, testimonial, CTA, problem, solution etc.).
• data/slide-color-logic.csv – Como emoções (frustration, hope, fear, relief, trust, urgency, curiosity etc.) se traduzem em estilos de fundo, cores de texto e uso de acentos.
• data/slide-typography.csv – Orientações tipográficas por tipo de slide (hierarquia, ênfase etc.).
• data/slide-layout-logic.csv – Padrões de layout orientados por objetivos narrativos e emoções (hook, problem, solution, proof, traction, CTA, timeline, features etc.).
• data/slide-layouts.csv – Padrões de layout concretos com dicas de estrutura em CSS (por exemplo, grids, layouts divididos, estruturas hero, sugestões de animação).

Você pode carregar essas tabelas no seu próprio pipeline (scripts, planilhas ou um gerador de decks) para criar slides consistentes, guiados por narrativa e emoção em vez de decisões de design arbitrárias.

10. Estruture o texto dos slides com fórmulas comprovadas

data/slide-copy.csv traz fórmulas de copywriting adaptadas a diferentes tipos de slide, incluindo:

• AIDA (Attention → Interest → Desire → Action)
• PAS (Problem → Agitate → Solution)
• 4Ps (Promise → Picture → Proof → Push)
• Before-After-Bridge
• QUEST
• Star-Story-Solution

Cada linha inclui:

• formula_name e keywords
• components estruturados
• use_case e example_template
• emotion_trigger e slide_type

Use essas fórmulas para:

• Pedir para um agente redigir o texto de slides seguindo um modelo específico.
• Padronizar a copy em pitch decks e apresentações de venda.

11. Escolha estratégias de slides para decks completos

data/slide-strategies.csv define padrões de deck completos, por exemplo:

• YC Seed Deck
• Guy Kawasaki 10/20/30
• Series A Deck

Cada estratégia inclui:

• Contagem recomendada de slides
• Sequência (title, problem, solution, traction, market etc.)
• Objetivo, público e tom
• Arcos de narrativa e emoção

Isso permite que você:

• Gere um esboço completo de slides com base em uma estratégia escolhida.
• Mantenha o design system e a estrutura narrativa em sincronia.

12. Trabalhe com os scripts de slides

O diretório scripts/ inclui utilitários para fluxos de trabalho de slides:

• scripts/generate-slide.py – Lógica central de geração de slides (você pode adaptá-la para o seu próprio gerador de decks ou pipeline).
• scripts/search-slides.py e scripts/slide_search_core.py – Utilitários de busca que ajudam a encontrar padrões ou estratégias de slides relevantes com base em keywords e contexto.
• scripts/fetch-background.py – Ajuda a buscar imagens de fundo (por exemplo, em Pexels/Unsplash) seguindo as diretrizes de data/slide-backgrounds.csv.

Esses scripts são blocos de construção. Você pode executá-los ou adaptá-los de acordo com o seu ambiente e o nível de automação desejado.

Trabalhando com referências e documentação

13. Use as referências como checklists de implementação

A pasta references/ não é só documentação; ela funciona como checklist enquanto você constrói seu design system:

• references/token-architecture.md – Confirme se seu layering de primitive/semantic/component está sólido.
• references/primitive-tokens.md – Verifique se você tem um conjunto completo de tokens base.
• references/semantic-tokens.md – Veja se cada token semântico tem um propósito claro.
• references/component-tokens.md – Faça o mapeamento de tokens para componentes reais.
• references/component-specs.md – Registre estados, variantes, interações e considerações de acessibilidade.
• references/states-and-variants.md – Evite esquecer estados de hover, focus, active, disabled, error e success.

Use esses arquivos em reviews de design e handoff para manter designers e devs alinhados.

Adaptando a skill ao seu stack

14. Integre de forma gradual

Você não precisa adotar a skill inteira de uma vez. Abordagens incrementais comuns:

• Adoção apenas de tokens – Comece com templates/design-tokens-starter.json, generate-tokens.cjs e validate-tokens.cjs para colocar um pipeline de tokens em produção.
• Adoção apenas de slides – Use os CSVs em data/ e scripts/generate-slide.py para padronizar suas apresentações mantendo seu design system atual.
• Adoção completa do sistema – Combine tokens, componentes e estruturas de slides para construir um sistema de marca unificado entre o produto (UI) e os pitch decks.

Foque primeiro na parte que resolve seu problema mais urgente e depois expanda.

FAQ

ckm:design-system é um UI kit ou um motor de design tokens?

Ela é principalmente uma skill de design system e arquitetura de tokens que também inclui um sistema de slides estruturado. Não vem como um UI kit em Figma, mas oferece:

• Uma arquitetura de tokens em três camadas
• Scripts para gerar e validar tokens
• Referências para especificações de componentes e estados

Você pode espelhar facilmente os mesmos tokens e componentes em Figma ou em qualquer outra ferramenta de design.

Posso usar ckm:design-system sem Tailwind ou React?

Sim. A integração com Tailwind é documentada em references/tailwind-integration.md, mas é opcional. Os tokens são gerados como variáveis CSS padrão, então você pode usá-los em qualquer stack:

• CSS puro ou CSS Modules
• Styled-components ou outras soluções de CSS-in-JS
• Design tokens para Web Components ou outros frameworks

Como ckm:design-system ajuda com apresentações?

A skill trata slide decks como um problema de design system:

• data/slide-layouts.csv e data/slide-layout-logic.csv definem padrões de layout e estruturas em CSS.
• data/slide-backgrounds.csv e data/slide-color-logic.csv mapeiam tipos de slide e emoções para elementos visuais.
• data/slide-copy.csv e data/slide-strategies.csv fornecem fórmulas de copy e estruturas de decks.
• Scripts como generate-slide.py e search-slides.py ajudam a automatizar geração e busca.

Isso permite criar decks repetíveis e consistentes com a marca, em vez de slides isolados.

Eu preciso usar os CSVs do jeito que vêm?

Não. Os CSVs são padrões opinativos. Você pode:

• Usá-los como estão para gerar pitch decks rapidamente.
• Fazer fork e customizar para refletir a voz e o estilo visual da sua marca.
• Substituí-los completamente pelos seus próprios dados, mantendo os mesmos padrões de scripts.

Por onde começar se eu só me importo com design tokens?

Se o seu foco é exclusivamente tokens e implementação de UI:

1. Leia SKILL.md, especialmente as seções "When to Use" e "Token Architecture".

2. Abra references/token-architecture.md e as referências de tokens primitive/semantic/component.

3. Copie templates/design-tokens-starter.json e crie o seu tokens.json.

4. Rode:

   node scripts/generate-tokens.cjs --config tokens.json -o tokens.css
   node scripts/validate-tokens.cjs --dir src/
   

Isso dá a você um pipeline de tokens funcional sem precisar mexer no sistema de slides.

ckm:design-system serve para projetos pequenos?

Pode servir, mas o ponto forte aparece em projetos onde:

• Múltiplas pessoas contribuem para a UI ou para os decks
• Consistência e escalabilidade são importantes
• Você espera iterar na marca ou no produto ao longo do tempo

Para uma landing page pontual ou uma apresentação interna única, o sistema completo pode ser mais estrutura do que você precisa. Ainda assim, você pode aproveitar a arquitetura de tokens ou as fórmulas de slides como orientação leve.

Como vejo tudo o que vem na skill?

No seu navegador de skills ou explorador de arquivos, veja a árvore completa da skill design-system, especialmente:

• SKILL.md
• data/
• references/
• scripts/
• templates/design-tokens-starter.json

Isso mostra todas as referências aninhadas e scripts auxiliares para você decidir quais partes integrar ao seu fluxo de trabalho.