open-index/open-npm huggingface dataset:
npm package: @1doc/1ds-tokens
Description: Este pacote contém os Design Tokens do 1ds Design System.
Latest version: 0.0.1

# @1doc/1ds-tokens

Este pacote contém os Design Tokens do 1ds Design System.

## Instalação

```bash
pnpm add @1doc/1ds-tokens
```

## Como 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).

```javascript
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:

1. **`primitives.css`**: Define as cores brutas (hex) em `:root`.
   - Ex: `--umds-primitive-blue-pure: #0058DB;`
2. **`theme-*.css`**: Liga variáveis de _tema_ às primitivas, escopadas por um atributo `data-theme`.
   - Ex: `[data-theme="1doc"] { --umds-theme-primary-pure: var(--umds-primitive-blue-pure); }`
3. **`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); }`

> **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:

1. Crie um arquivo JSON em `src/themes/meu-tema.json` seguindo a estrutura dos existentes.
2. Adicione a configuração no `config.js`.
3. Rode `pnpm build` dentro da pasta de tokens.

## Troubleshooting

### Tema não está mudando

1. Verifique se todos os arquivos CSS estão importados (primitives, semantic e o tema desejado).
2. Verifique se o atributo `data-theme` está sendo aplicado corretamente no elemento `<html>` ou no container raiz.
3. 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.

```bash
pnpm build
```