Barte Design Tokens

Pacote de tokens construído com Style Dictionary a partir dos exports do Figma. Este repositório não contém componentes — apenas os tokens que servem de base para outros projetos Barte.

Instalação

npm install @barte-project/design-tokens

Uso

CSS Variables

Importe os arquivos CSS no seu projeto:

import '@barte-project/design-tokens/build/web/tokens.css';
import '@barte-project/design-tokens/build/web/theme-light.css';

Ou no seu HTML:

<link rel="stylesheet" href="node_modules/@barte-project/design-tokens/build/web/tokens.css">
<link rel="stylesheet" href="node_modules/@barte-project/design-tokens/build/web/theme-light.css">

JSON Tokens

Para acessar os tokens em formato JSON:

import tokens from '@barte-project/design-tokens/build/web/tokens.json';

Arquitetura do Sistema

Figma Export          Transform           Build             Output
┌────────────┐      ┌──────────┐      ┌──────────┐      ┌────────────┐
│ figma/     │ ───► │transform │ ───► │ tokens/  │ ───► │ build/web/ │
│ *.json     │      │   .js    │      │ **/*.json│      │ *.css/json │
└────────────┘      └──────────┘      └──────────┘      └────────────┘

Fluxo de Dados

| Fase | Input | Output | Script | |:-----|:------|:-------|:-------| | Transform | figma/*.json | tokens/**/*.json | transform.js | | Build | tokens/**/*.json | build/web/* | build.js |

Estrutura de Arquivos

barte-design-tokens/
├── figma/                    # 📥 Exports do Figma (input)
│   ├── primitive.json        #    Cores, sizes, tipografia
│   ├── semantic.json         #    Spacing, border, typography compostos
│   └── theme.json            #    Mapeamentos Light/Dark
│
├── tokens/                   # 📦 Tokens processados (intermediário)
│   ├── primitive/
│   ├── semantic/
│   └── themes/
│
├── build/web/                # 📤 Output final
│   ├── tokens.css            #    Variáveis semânticas
│   ├── theme-light.css       #    Tema claro
│   ├── theme-dark.css        #    Tema escuro
│   └── tokens.json           #    Bundle completo
│
├── lib/                      # 🔧 Biblioteca de utilitários
│   ├── constants.js          #    Mapeamentos de valores
│   ├── references.js         #    Correção de referências
│   ├── transformers.js       #    Transformações de dados
│   ├── transforms/           #    Transforms do Style Dictionary
│   ├── utils/                #    Utilitários (io, logger, units)
│   └── validators/           #    Validação de tokens
│
├── transform.js              # ⚙️ Figma → tokens/
├── build.js                  # 🔨 tokens/ → build/web/
└── config.js                 # ⚙️ Configuração do Style Dictionary

Comandos

npm run build        # Transform + Build completo (uso normal)
npm run transform    # Apenas Figma → tokens/**
npm run build:css    # Apenas tokens/** → build/web
npm run build:watch  # Rebuild automático ao editar figma/*.json

Fase 1: Transform

O script transform.js converte os exports do Figma para o formato Style Dictionary.

Processamentos

| Função | Input | Output | Transformações | |:-------|:------|:-------|:---------------| | processPrimitive() | primitive.json | tokens/primitive/* | Converte px→rem, normaliza font weights | | processSemantic() | semantic.json | tokens/semantic/* | Corrige referências, calcula lineHeight ratio | | processTheme() | theme.json | tokens/themes/* | Mapeia referências para primitivos |

Correção de Referências

// Antes (Figma export):
{ "value": "{colors.barte.500}" }

// Depois (Style Dictionary):
{ "value": "{primitive.colors.barte.500}" }

Normalização de Font Weights

| Figma | CSS | |:------|:----| | Thin | 100 | | Regular | 400 | | Medium | 500 | | SemiBold | 600 | | Bold | 700 | | ExtraBold | 800 | | Black | 900 |

Fase 2: Build

O script build.js usa Style Dictionary para compilar os tokens em CSS/JSON.

Transforms Customizados

| Transform | Tipo | Exemplo | |:----------|:-----|:--------| | name/clean-semantic | name | semantic.border.radius.md → border-radius-md | | name/clean-theme | name | theme.light.colors.bg.brand → bg-brand | | size/add-rem-suffix | value | 1 → 1rem | | typography/add-em-suffix | value | 0.4 → 0.4px (letterSpacing) |

Filtros de Output

| Arquivo | Filtro | |:--------|:-------| | tokens.css | Apenas tokens semânticos | | theme-light.css | Apenas tema light | | theme-dark.css | Apenas tema dark | | tokens.json | Todos os tokens |

Formato dos Tokens

Primitivos

{
  "primitive": {
    "colors": {
      "barte": {
        "500": { "value": "#DF285D", "type": "color" }
      }
    },
    "size": {
      "16": { "value": 16, "type": "number" }
    }
  }
}

Semânticos

{
  "semantic": {
    "spacing": {
      "md": { "value": "{size.12}", "type": "number" }
    },
    "border": {
      "radius": {
        "lg": { "value": "{size.8}", "type": "number" }
      }
    }
  }
}

Tema

{
  "theme": {
    "Light": {
      "colors": {
        "bg": {
          "brand": { "value": "{colors.barte.500}", "type": "color" }
        }
      }
    }
  }
}

Output CSS

tokens.css

:root {
  --spacing-md: 0.75rem;
  --border-radius-lg: 0.5rem;
  --typography-heading-h1-fontSize: 4rem;
}

theme-light.css

[data-theme="light"], :root {
  --bg-brand: #DF285D;
  --content-primary: #171717;
  --stroke-primary: #EFEFEF;
}

Desenvolvimento

Fluxo de Trabalho

1. Atualize as variáveis no Figma
2. Exporte primitive.json, semantic.json e theme.json para figma/
3. Rode npm run build para transformar e gerar CSS/JSON
4. Publique com npm publish

Adicionando Novos Tokens

1. Edite o JSON apropriado em figma/
2. Execute npm run build
3. Verifique o output em build/web/

Adicionando Novos Patterns de Referência

Edite lib/references.js:

const REFERENCE_PATTERNS = {
  colors: 'primitive.colors',
  size: 'primitive.size',
  typography: 'primitive.typography',
  // Adicione novos patterns aqui:
  'novo-pattern': 'primitive.novo-pattern'
};

Uso no App

// Importe os tokens
import '@barte-project/design-tokens/build/web/tokens.css';
import '@barte-project/design-tokens/build/web/theme-light.css';

// Use as variáveis CSS
const Button = styled.button`
  background: var(--bg-brand);
  color: var(--content-inverse);
  padding: var(--spacing-md) var(--spacing-xl);
  border-radius: var(--border-radius-lg);
`;

Trocando Temas

<!-- Tema claro (padrão) -->
<html data-theme="light">

<!-- Tema escuro -->
<html data-theme="dark">

// Toggle de tema
document.documentElement.dataset.theme = 
  document.documentElement.dataset.theme === 'dark' ? 'light' : 'dark';