Formatos de Output

Premissa

O Aplica Tokens Theme Engine gera os mesmos tokens em múltiplos formatos para atender consumidores com necessidades distintas. Cada formato tem suas unidades, convenções de naming e casos de uso específicos. A escolha certa do formato poupa trabalho de integração.

Onde os arquivos são gerados

dist/
├── json/                          ← JSON estruturado (Figma, Tokens Studio)
│   ├── aplica_joy-light-positive-semantic.json
│   ├── aplica_joy-light-positive-foundation.json
│   ├── aplica_joy-dark-positive-semantic.json
│   └── ...  (1 arquivo por combinação brand × mode × surface × tipo)
├── css/                           ← CSS custom properties (Web)
│   ├── aplica_joy-light-positive.css
│   └── ...
│   └── foundation/                ← Classes CSS de Foundation Styles
│       └── {brand}/
│           ├── typography.css     ← Classes compostas de tipografia
│           └── elevation.css      ← Classes compostas de elevação
├── esm/                           ← ES Modules (JavaScript moderno)
│   ├── aplica_joy-light-positive-semantic.mjs
│   └── ...
├── js/                            ← CommonJS (Node.js, bundlers legados)
│   ├── aplica_joy-light-positive-semantic.js
│   └── ...
└── dts/                           ← TypeScript declarations
    ├── aplica_joy-light-positive-semantic.d.ts
    └── ...

O nome de cada arquivo de tokens segue o padrão: {brand}-{mode}-{surface}-{tipo}.{ext}

Foundation Styles seguem: dist/css/foundation/{brand}/typography.css e elevation.css

Formato JSON — para Figma e Tokens Studio

Unidade: px em todos os valores dimensionais
Uso: Consumo direto pelo Figma via Tokens Studio, sistemas que precisam de valores numéricos

{
  "semantic": {
    "color": {
      "interface": {
        "function": {
          "primary": {
            "normal": {
              "background": { "$value": "#C40145", "$type": "color" },
              "txtOn":       { "$value": "#ffffff", "$type": "color" },
              "border":      { "$value": "#9c0136", "$type": "color" },
              "txt":         { "$value": "#7a0128", "$type": "color" }
            }
          }
        }
      }
    },
    "dimension": {
      "spacing": {
        "medium": { "$value": "32px", "$type": "spacing" }
      }
    }
  }
}

O JSON mantém a estrutura hierárquica completa (semantic.color.interface...). Foundation é um arquivo separado com aliases que apontam para o Semantic:

{
  "foundation": {
    "bg": {
      "primary": { "$value": "{semantic.color.interface.function.primary.normal.background}", "$type": "color" }
    }
  }
}

Output JSON tipado — `jsonTyped` (desde 3.7.0)

Uso: Tooling que precisa de metadata estruturada por token além do valor resolvido — geração AI-assistida de componentes, code generators, design linters

jsonTyped é a primeira plataforma de output com metadata configurável. Onde o json padrão emite { "$value": ..., "$type": ... }, o jsonTyped emite objetos com campos nomeados que você controla: type, value, description e path.

Estrutura do output

{
  "semantic": {
    "color": {
      "interface": {
        "function": {
          "primary": {
            "normal": {
              "background": {
                "type":        "color",
                "value":       "#C40145",
                "description": "Primary action background — normal intensity",
                "path":        "semantic.color.interface.function.primary.normal.background"
              }
            }
          }
        }
      }
    }
  }
}

Como ativar

Adicione jsonTyped à lista platforms da camada e inclua formatOptions.jsonTyped em transformers.config.mjs:

export default defineTransformersConfig({
  layers: {
    semantic: { enabled: true, platforms: ['json', 'jsonTyped', 'css', 'esm'] },
    // ...
  },
  formatOptions: {
    jsonTyped: {
      type:        'type',
      value:       'value',
      description: 'description', // omitir esta chave exclui description do output
      path:        'path',
    }
  }
});

`json` vs `jsonTyped`

	`json`	`jsonTyped`
Campo de valor	`$value`	configurável (padrão: `value`)
Campo de tipo	`$type`	configurável (padrão: `type`)
Descrição	não emitido	configurável (omitir chave para excluir)
Caminho	não emitido	configurável (padrão: `path`)
Backward compatible	—	sim — contrato `json` existente não muda

jsonTyped é aditivo: consumidores json existentes não são afetados. Habilite ambas as plataformas na mesma camada se precisar das duas.

Veja formatOptions.jsonTyped para a referência completa de campos.

Formato CSS — para Web

Unidade: rem em tokens dimensionais (tamanhos, espaçamentos, raios, tipografia)
Exceções em px: tokens com $type: "number" (ex.: semantic.depth.spread)
Uso: Aplicação web via CSS custom properties

Conversão px → rem

rem = px / baseFontSize (padrão: 16)

Token semântico	Valor fonte (px)	CSS output (rem)
`dimension.spacing.medium`	`32px`	`2rem`
`dimension.spacing.nano`	`4px`	`0.25rem`
`typography.fontSizes.medium`	`16px`	`1rem`
`border.radius.medium`	`8px`	`0.5rem`
`depth.spread.level_two`	`-2`	`-2` (permanece número)

Por que rem? Dimensões em rem respeitam a preferência de tamanho de fonte do usuário no navegador. Se o usuário configurar o root para 20px, todos os espaçamentos e tamanhos escalam proporcionalmente — acessibilidade por construção.

Estrutura das variáveis CSS

/* aplica_joy-light-positive.css */
:root,
[data-theme="aplica_joy-light-positive"] {

  /* Semantic — cores */
  --semantic-color-interface-function-primary-normal-background: #C40145;
  --semantic-color-interface-function-primary-normal-txt-on:     #ffffff;
  --semantic-color-interface-feedback-success-default-background: #D7F6CB;

  /* Semantic — dimensões (rem) */
  --semantic-dimension-spacing-medium:  2rem;
  --semantic-dimension-spacing-small:   1.5rem;
  --semantic-typography-font-sizes-medium: 1rem;
  --semantic-border-radius-medium:      0.5rem;

  /* Semantic — elevação (px, não converte) */
  --semantic-depth-spread-level-two: -2;

  /* Foundation — aliases */
  --foundation-bg-primary:     var(--semantic-color-interface-function-primary-normal-background);
  --foundation-text-body:      var(--semantic-color-text-body-default);
  --foundation-spacing-medium: var(--semantic-dimension-spacing-medium);
}

Troca de tema em runtime

A troca de tema via CSS é feita por seletor de atributo:

<!-- Tema padrão: aplica_joy light positive -->
<html data-theme="aplica_joy-light-positive">

<!-- Trocar para dark -->
<html data-theme="aplica_joy-dark-positive">

document.documentElement.setAttribute('data-theme', 'aplica_joy-dark-positive');

Nenhum JavaScript adicional é necessário — a mudança de atributo ativa o CSS correspondente.

Formato ESM — para JavaScript moderno

Unidade: px (valores numéricos, sem conversão)
Uso: Aplicações React, Vue, bundlers modernos (Vite, esbuild, Rollup)

// aplica_joy-light-positive-semantic.mjs
export const semantic = {
  color: {
    interface: {
      function: {
        primary: {
          normal: {
            background: '#C40145',
            txtOn: '#ffffff',
            border: '#9c0136'
          }
        }
      }
    }
  },
  dimension: {
    spacing: {
      medium: '32px',
      small: '24px'
    }
  }
};

Modo aliases vs modo raw:

Aliases (padrão): Foundation expõe referências ao Semantic (foundation.bg.primary → {semantic.color.*})
Raw: Todos os tokens resolvidos para valores finais — útil para consumidores que não suportam referências W3C

O engine gera tokens alias por padrão. A resolução de valores finais acontece durante o build do Style Dictionary (tokens:build:all), então o output ESM que você consome em dist/ sempre contém valores resolvidos.

Formato CJS — para Node.js e bundlers legados

Unidade: px
Diretório: dist/js/
Uso: Node.js, Webpack, projetos que não suportam ESM nativo

// aplica_joy-light-positive-semantic.js
const semantic = {
  color: { /* ... mesma estrutura do ESM */ }
};

module.exports = { semantic };

Formato TypeScript — para type-safety

Uso: Projetos TypeScript que querem autocompletar e checagem de tipos ao acessar tokens

// aplica_joy-light-positive-semantic.d.ts
export declare const semantic: {
  color: {
    interface: {
      function: {
        primary: {
          normal: {
            background: string;
            txtOn: string;
            border: string;
          };
        };
      };
    };
  };
  dimension: {
    spacing: {
      medium: string;
      small: string;
      // ...
    };
  };
};

Uso com autocompletar:

import { semantic } from './dist/esm/aplica_joy-light-positive-semantic.mjs';

const color = semantic.color.interface.function.primary.normal.background; // #C40145

Regra de consumo: qual camada usar

Cenário	Camada recomendada	Exemplo
Estilizar qualquer componente	Semantic	`var(--semantic-color-interface-function-primary-normal-background)`
Alias simples já existe	Foundation (quando disponível)	`var(--foundation-bg-primary)`
Cálculo em JavaScript	ESM/CJS com Semantic	`tokens.semantic.dimension.spacing.medium`
Configurar tokens no Figma	JSON via Tokens Studio	arquivo `*-semantic.json`
Nunca usar diretamente	`brand.`, `mode.`, `surface.*`	Camadas internas — não fazem parte do contrato

A Foundation é um atalho para o Semantic — não o substitui como fonte de verdade. Se um alias Foundation não existe para o caso de uso, use o Semantic diretamente.

Naming das variáveis CSS

O ponto (.) dos caminhos de token é convertido para hífen (-) no CSS:

semantic.color.interface.function.primary.normal.background
↓
--semantic-color-interface-function-primary-normal-background

foundation.bg.primary
↓
--foundation-bg-primary

Tabela de comparação por formato

Formato	Unidade	Estrutura	Referências	Uso principal
JSON	`px`	Nested com `$value`/`$type`	Mantidas (`{semantic.*}`)	Figma, Tokens Studio
jsonTyped	`px`	Nested objects com campos nomeados	Resolvidas	Tooling, geração AI-assistida
CSS	`rem` (dimensões)	Flat `--var-name: value`	Resolvidas	Web — `:root` ou `[data-theme]`
ESM	`px`	Nested JS object	Aliases (padrão) ou raw	React, Vue, Vite
CJS	`px`	Nested JS object	Aliases (padrão) ou raw	Node.js, Webpack
TypeScript	—	Declarações de tipo	—	Autocompletar, checagem de tipos

Configuração de unidades

Para reverter o CSS para px (ex.: ambientes sem suporte a rem):

// theme-engine/config/global/themes.config.json
{
  "global": {
    "dimension": {
      "outputUnit": {
        "css": "px",
        "default": "px"
      }
    }
  }
}

Para usar uma base diferente de 16px (ex.: estratégia 62.5% com 10px root):

{
  "global": {
    "dimension": {
      "baseFontSize": 10
    }
  }
}

Foundation Styles — output de classes CSS compostas

Além das CSS custom properties por token, o engine gera arquivos de classes CSS compostas em dist/css/foundation/{brand}/. Esses arquivos são gerados a partir dos dados de Foundation Styles (data/foundation/{brand}/styles/typography_styles.json e elevation_styles.json) durante o step foundations:generate.

Classes de tipografia

/* dist/css/foundation/engine/typography.css */
.typography-engine-heading-title_1 {
  font-family:     var(--semantic-typography-fontFamilies-main);
  font-weight:     var(--semantic-typography-fontWeights-main-semibold-normal);
  font-size:       var(--semantic-typography-fontSizes-medium);
  line-height:     var(--semantic-typography-lineHeights-close-medium);
  letter-spacing:  var(--semantic-typography-letterSpacings-regular);
  text-transform:  var(--semantic-typography-textCase-uppercase);
  text-decoration: var(--semantic-typography-textDecoration-default);
}

.typography-engine-action-strong-tight-medium { ... }
.typography-engine-body-regular-loose-medium { ... }

Classes de elevação

/* dist/css/foundation/engine/elevation.css */
.elevation-level_zero      { box-shadow: ... }
.elevation-level_one       { box-shadow: ... }
.elevation-level_two       { box-shadow: ... }
.elevation-level_three     { box-shadow: ... }
.elevation-level_four      { box-shadow: ... }
.elevation-level_five      { box-shadow: ... }

Cada classe compõe tokens semânticos de depth, spread e opacidade. Os valores resolvem a partir do tema ativo em runtime — a troca de tema os atualiza automaticamente.

Ordem de carregamento

<!-- Arquivo de tema deve carregar primeiro (fornece as --semantic-* custom properties) -->
<link rel="stylesheet" href="/dist/css/aplica_joy-light-positive.css" />

<!-- Foundation Styles consomem as custom properties definidas acima -->
<link rel="stylesheet" href="/dist/css/foundation/engine/typography.css" />
<link rel="stylesheet" href="/dist/css/foundation/engine/elevation.css" />

Veja 06-foundation-styles.md para o guia completo sobre Foundation Styles.

Referências

Pipeline de build: 04-build-pipeline.pt-br.md
Workflow do designer (Figma): 02-designer-workflow.pt-br.md
Consumindo tokens de dist/: 07-implementation/03-consuming-dist-tokens.pt-br.md
Configuração de transformers (diretórios de output): 09-engineering/04-transformers-configuration.pt-br.md

Premissa​

Onde os arquivos são gerados​

Formato JSON — para Figma e Tokens Studio​

Output JSON tipado — jsonTyped (desde 3.7.0)​

Estrutura do output​

Como ativar​

json vs jsonTyped​

Formato CSS — para Web​

Conversão px → rem​

Estrutura das variáveis CSS​

Troca de tema em runtime​

Formato ESM — para JavaScript moderno​

Formato CJS — para Node.js e bundlers legados​

Formato TypeScript — para type-safety​

Regra de consumo: qual camada usar​

Naming das variáveis CSS​

Tabela de comparação por formato​

Configuração de unidades​

Foundation Styles — output de classes CSS compostas​

Classes de tipografia​

Classes de elevação​

Ordem de carregamento​

Referências​