@1doc/1ds-tokens
v0.1.0
Published
Este pacote contém os Design Tokens do 1ds Design System.
Readme
@1doc/1ds-tokens
Este pacote contém os Design Tokens do 1ds Design System.
Instalação
pnpm add @1doc/1ds-tokensComo usar
Os tokens são expostos principalmente como Variáveis CSS. Importe os arquivos CSS necessários no ponto de entrada da sua aplicação (Root ou main.js/ts).
import "@1doc/1ds-tokens/dist/css/primitives.css";
import "@1doc/1ds-tokens/dist/css/semantic.css";
import "@1doc/1ds-tokens/dist/css/theme-1doc.css";Estrutura de Arquivos
packages/tokens/
├── src/
│ ├── primitives/
│ │ └── colors.json # Cores base (não mudam)
│ ├── semantic/
│ │ └── base.json # Tokens semânticos (referências)
│ └── themes/
│ ├── 1doc.json # Tema padrão azul
│ ├── 1ds-red.json # Tema vermelho
│ ├── 1ds-green.json # Tema verde
│ ├── 1ds-orange.json # Tema laranja
│ └── 1ds-yellow.json # Tema amarelo
├── dist/
│ └── css/
│ ├── primitives.css # :root com cores primitivas
│ ├── semantic.css # :root com tokens semânticos
│ ├── theme-1doc.css # :root, [data-theme="1doc"]
│ ├── theme-1ds-red.css # [data-theme="1ds-red"]
│ ├── ...Como funciona a cascata CSS
O sistema de temas utiliza uma arquitetura em 3 camadas:
primitives.css: Define as cores brutas (hex) em:root.- Ex:
--umds-primitive-blue-pure: #0058DB;
- Ex:
theme-*.css: Liga variáveis de tema às primitivas, escopadas por um atributodata-theme.- Ex:
[data-theme="1doc"] { --umds-theme-primary-pure: var(--umds-primitive-blue-pure); }
- Ex:
semantic.css: Define os tokens semânticos que seu app deve usar, apontando para as variáveis de tema.- Ex:
:root { --umds-semantic-color-primary-pure: var(--umds-theme-primary-pure); }
- Ex:
Importante: Sempre utilize os tokens semânticos (
--umds-semantic-*) no seu CSS. Nunca use primitivos ou temas diretamente.
Criando um Novo Tema
Para adicionar um tema customizado ao seu projeto local:
- Crie um arquivo JSON em
src/themes/meu-tema.jsonseguindo a estrutura dos existentes. - Adicione a configuração no
config.js. - Rode
pnpm builddentro da pasta de tokens.
Troubleshooting
Tema não está mudando
- Verifique se todos os arquivos CSS estão importados (primitives, semantic e o tema desejado).
- Verifique se o atributo
data-themeestá sendo aplicado corretamente no elemento<html>ou no container raiz. - Use o DevTools para inspecionar se as variáveis css (
--umds-semantic-*) estão mudando de valor.
Desenvolvimento
Os tokens estão definidos em src/**/*.json. O Style Dictionary é usado para transformá-los.
pnpm build