@zuzahimself/mds-design-playground

v0.2.5

Published

a month ago

Design system components and tokens for Zig platform — installable package for Claude Code + Figma MCP workflows

0High
0Medium
0Low

zuzahimself

design-system zig mds react components

MDS — Michael Design System

Pacote de componentes e tokens de design da plataforma Zig. Serve para dois fluxos:

Designers — prototipar telas com Claude Code, sem precisar saber programar
Devs — consumir os tokens de design no projeto via Tailwind CSS

Para designers — prototipação com Claude Code

Nunca configurou nada disso antes?

Vai direto no Guia de onboarding completo. Ele explica do zero, passo-a-passo, para Mac e Windows: instalar Node.js, Claude Code, Cursor, criar a pasta da jornada, instalar o pacote e abrir o protótipo no navegador. Volta aqui depois que terminar.

Já tem o ambiente configurado? Instalação rápida

Pré-requisitos: Node.js 18 ou superior, e um projeto Next.js 14+ com Tailwind já criado.

No terminal, dentro da pasta do projeto, rode:

npm install @zuzahimself/mds-design-playground

Depois abre o Claude Code e manda essa mensagem:

Configura o pacote @zuzahimself/mds-design-playground no projeto. Adiciona o transpilePackages no next.config.ts e importa os arquivos theme.css e typography.css do pacote no globals.css.

O Claude faz o resto automaticamente.

Atualizando pra uma nova versão

Quando sair uma versão nova da lib (com bugs corrigidos ou componentes novos), atualiza assim no terminal, dentro da pasta do projeto:

npm update @zuzahimself/mds-design-playground

Pra ver qual versão você tem instalada:

npm list @zuzahimself/mds-design-playground

Começando a construir

A partir daí é só descrever o que você quer. O Claude já conhece todos os componentes e como usar cada um. Exemplos:

"Cria uma página com sidebar no nível place, TopNavigation com o nome da org e do lugar, um PageHeader com título 'Relatórios', botão 'Exportar' e campo de busca, e uma tabela abaixo."

"Adiciona um modal de confirmação quando o usuário clica em excluir."

"Coloca um alerta de sucesso no topo da página quando o formulário for salvo."

"Cria um filtro com pills: Show, Festival, Esporte."

Usando com o Figma

Se você tiver o Figma MCP conectado no Claude Code, pode apontar direto pra um frame:

"Implementa esse frame do Figma usando os componentes do MDS: [link do frame]"

O Claude lê o design e gera o código com os componentes certos.

Para devs — tokens Tailwind

O pacote exporta todos os tokens MDS como extensão do theme do Tailwind. Funciona com qualquer projeto React + Tailwind 3+, independente de usar os componentes do MDS ou não.

O que está incluído:

182 cores (primitivos, aliases e mapeados — surface, text, border, icon)
Escala de espaçamento (1x–40x, passos de 4px)
Border radius, font size, font family e box shadow

Instalação

npm install @zuzahimself/mds-design-playground

Configuração

1. Carrega o CSS de tokens no global:

/* globals.css */
@import '@zuzahimself/mds-design-playground/tokens/theme.css';

2. Estende o Tailwind config:

// tailwind.config.js
const mdsTokens = require('@zuzahimself/mds-design-playground/tailwind-tokens')

module.exports = {
  content: ['./app/**/*.{ts,tsx}', './components/**/*.{ts,tsx}'],
  theme: {
    extend: mdsTokens,
  },
}

// tailwind.config.ts (se preferir TypeScript)
import type { Config } from 'tailwindcss'
const mdsTokens = require('@zuzahimself/mds-design-playground/tailwind-tokens')

export default {
  content: ['./app/**/*.{ts,tsx}', './components/**/*.{ts,tsx}'],
  theme: { extend: mdsTokens },
} satisfies Config

Usando os tokens

Todos os tokens ficam disponíveis como classes Tailwind, usando os nomes exatos do design system:

// Botão primário
<button className="bg-surface-action hover:bg-surface-action-hover text-text-on-contrast-default rounded-mds-sm px-4x py-2x">
  Confirmar
</button>

// Alert de warning
<div className="bg-surface-warning border border-border-warning rounded-mds-sm p-3x">
  <span className="text-text-warning text-mds-xxs">Atenção: algo precisa da sua revisão.</span>
</div>

// Input com foco MDS
<input className="border border-border-default focus:border-border-focus rounded-mds-sm px-3x py-2x text-text-user-input placeholder:text-text-placeholder" />

Dark mode é automático — adicione data-theme="dark" no <html> e todos os tokens flipam.

Referência de tokens

| Categoria | Tailwind | Exemplos | |-----------|----------|---------| | surface-* | bg-surface-* | bg-surface-action, bg-surface-warning, bg-surface-page-default | | text-* | text-text-* | text-text-paragraph-default, text-text-danger, text-text-heading | | border-* | border-border-* | border-border-default, border-border-focus, border-border-error | | icon-* | text-icon-* | text-icon-default, text-icon-success, text-icon-warning | | Alias | bg-primary-* | bg-primary-pure, bg-success-lightest, bg-danger-medium | | Spacing | p-* m-* gap-* | p-2x (8px), gap-4x (16px), m-8x (32px) | | Border radius | rounded-mds-* | rounded-mds-sm (8px), rounded-mds-md (16px), rounded-mds-pill | | Font size | text-mds-* | text-mds-xxs (14px), text-mds-xs (16px), text-mds-md (24px) | | Font family | font-mds-* | font-mds-base (Lato), font-mds-brand (TTCommons) | | Shadow | shadow-mds-* | shadow-mds-01 (sutil), shadow-mds-04 (modal elevado) |

Os tokens text-* e border-* geram classes com nome repetido (text-text-paragraph-default, border-border-default). É redundante visualmente mas mantém paridade 1:1 com o design system — o prefixo comunica a camada do token.

Componentes disponíveis

Mais de 30 componentes prontos, entre eles:

Navegação: Sidebar, TopNavigation, Breadcrumb, PageHeader, TabBar, PageTab, Pagination
Ações: Button, ButtonLink, Dropdown, ButtonMultiAction, ButtonSelect
Formulários: Input, InputSelect, Checkbox, Radio, Switch, DatePicker, DateRangePicker, FileUploader, FilterPill
Feedback: Alert, Notification, Tooltip, Tag
Layout: Modal, Drawer, Table, Section, Divider, Card

Troubleshooting

Algo deu errado? Procura o seu problema na lista abaixo. Se nenhum se encaixar, copia a mensagem de erro que apareceu no terminal e cola no Claude.ai explicando o que você estava tentando fazer — ele te ajuda a resolver.

Erro: "command not found: npm" ou "'npm' não é reconhecido"

O Node.js não está instalado, ou foi instalado mas o terminal ainda não enxergou.

Mac:

Instala o Node.js em nodejs.org (versão LTS)
Feche e reabra o Terminal depois da instalação — sem isso ele não enxerga o npm

Windows:

Instala o Node.js em nodejs.org (versão LTS)
Feche o PowerShell e abra de novo depois da instalação
Se ainda não funcionar, reinicia o computador — o Windows precisa atualizar a variável PATH

Erro no Windows: "execution of scripts is disabled on this system"

O PowerShell está bloqueando scripts por padrão. É uma trava de segurança do Windows.

Abre o PowerShell como administrador (botão direito → "Executar como administrador")

Cola e roda:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Digita S (sim) e pressiona Enter quando perguntar
Fecha e reabre o PowerShell normal (não precisa mais ser administrador)

Os componentes aparecem sem estilo (sem cor, sem espaçamento)

Provavelmente faltou um dos dois passos de configuração. Verifica:

next.config.ts tem o transpilePackages:

const nextConfig = {
  transpilePackages: ['@zuzahimself/mds-design-playground'],
};

app/globals.css importa os tokens:

@import "@zuzahimself/mds-design-playground/tokens/theme.css";
@import "@zuzahimself/mds-design-playground/tokens/typography.css";

Salva os dois arquivos e reinicia o servidor de desenvolvimento (no terminal: Ctrl + C pra parar, depois npm run dev pra rodar de novo).

As fontes não estão certas (parece Arial ou Times New Roman em vez da fonte do MDS)

A fonte do MDS (Lato) precisa ser carregada pelo Next.js. Pede pro Claude Code:

Configura a fonte Lato do Google Fonts no layout.tsx usando o next/font/google, e define como variable: "--font-family-base" pra sobrescrever o token do MDS.

Dark mode não está mudando nada

Pra ativar dark mode, precisa ter o atributo data-theme="dark" no <html> do projeto. Pede pro Claude Code:

Adiciona um toggle de dark mode que alterna o atributo data-theme na tag <html> entre light e dark.

Erro ao instalar: "EACCES" ou "permission denied" (Mac)

O npm está tentando instalar em uma pasta que precisa de senha de administrador. Não use sudo pra resolver — isso causa outros problemas depois. Em vez disso:

Roda o comando abaixo no terminal:

mkdir -p ~/.npm-global && npm config set prefix '~/.npm-global'

Adiciona essa linha no fim do arquivo ~/.zshrc:
```
export PATH=~/.npm-global/bin:$PATH
```
Fecha e reabre o terminal

Como saber se a lib instalou certo?

No terminal, dentro da pasta do projeto:

npm list @zuzahimself/mds-design-playground

Deve aparecer algo tipo @zuzahimself/[email protected]. Se aparecer (empty) ou erro, a instalação não foi pra frente — roda npm install @zuzahimself/mds-design-playground de novo.

Dúvidas que não estão aqui?

Fala com o Victor.