Glossário bilíngue
Uso: Este documento é a fonte de verdade para todas as traduções de conteúdo do Aplica DS. Antes de traduzir qualquer artigo, consulte as seções abaixo.
Qualquer nova tradução ou correção de terminologia deve ser aplicada aqui primeiro.
Regra fundamental
Há três categorias de termos:
| Categoria | O que fazer |
|---|---|
| Código | Nunca traduzir — são nomes de tokens, parâmetros, comandos ou arquivos |
| Nomes próprios do sistema | Manter em ambos os idiomas sem alteração |
| Vocabulário | Traduzir seguindo a coluna en-US abaixo |
Seção 1 — Termos que NUNCA são traduzidos
São nomes de código. Aparecem exatamente assim em pt-BR e em en-US.
| Termo | Tipo | Exemplo de uso |
|---|---|---|
txtOn | Nome de token | "o txtOn garante contraste WCAG" |
txt | Nome de token | "o txt é texto legível sobre canvas (não sobre brand background) — desde 3.6.0" |
darkModeChroma | Parâmetro de config | "darkModeChroma: 0.85" |
txtOnStrategy | Parâmetro de config | "txtOnStrategy: 'brand-tint'" |
txtBaseColorLevel | Parâmetro de config | "txtBaseColorLevel: 140" |
fallbackBaseColorLevel | Parâmetro de config | "fallbackBaseColorLevel: 160" |
textExposure | Parâmetro de config | "textExposure: ['feedback']" |
generateTxt | Parâmetro de config | "generateTxt: true" |
generation.colorText | Chave de config | "seção generation.colorText no workspace config (desde 3.6.1)" |
jsonTyped | Nome de plataforma de output | "habilite jsonTyped em platforms para metadata tipada — desde 3.7.0" |
formatOptions.jsonTyped | Chave de config | "formatOptions.jsonTyped em transformers.config.mjs — campos type, value, description, path" |
accessibilityLevel | Parâmetro de config | "accessibilityLevel: 'AA'" |
includePrimitives | Parâmetro de config | "includePrimitives: true" |
borderOffset | Parâmetro de config | "borderOffset.palette: 10" |
sync:architecture | Comando npm | "rode npm run sync:architecture" |
build:themes | Comando npm | "npm run build:themes" |
themes:generate | Comando npm | "npm run themes:generate" |
foundations:generate | Comando npm | "npm run foundations:generate" |
dimension:generate | Comando npm | "npm run dimension:generate" |
ensure:data | Comando npm | — |
*.config.mjs | Padrão de arquivo | "abra o *.config.mjs" |
$themes.json | Nome de arquivo | — |
themes.config.json | Nome de arquivo | — |
_brand.json | Nome de arquivo | — |
_grayscale.json | Nome de arquivo | — |
_primitive_theme.json | Nome de arquivo | — |
data/ | Diretório | "arquivos em data/" |
dist/ | Diretório | "output em dist/" |
semantic.color.* | Namespace de token | "use semantic.color.interface.*" |
foundation.bg.* | Namespace de token | "use foundation.bg.primary" |
foundation.txt.* | Namespace de token | "use foundation.txt.body" |
brand.branding.* | Namespace de token | — |
theme-engine | Alias CLI preferido | "npx theme-engine init — alias preferido desde 3.8.0; aplica-theme-engine mantido como fallback" |
theme-engine preview | Comando CLI | "npx theme-engine preview — gera preview HTML estático em dist/preview/; flags: --build (rebuild antes), --serve (servidor local com live reload); dropdown View com modos Detailed / Summary; desde 3.17.0: layout de referência com nav hierárquica semântica, modo compacto e filtro de busca em tempo real — desde 3.9.0" |
aplica-theme-engine | CLI legado (compatibilidade) | "preservado como fallback — scripts existentes continuam funcionando sem alterações" |
options.interaction.decomposition.method | Chave de config | "declara o modo de decomposição de interação: 'system-scale' (padrão, legado) ou 'dilution' (novo) — desde 3.9.0" |
system-scale | Valor de config | "modo de decomposição legado explicitamente nomeado — usa os níveis de paleta existentes (ex.: active: 120)" |
dilution | Valor de config | "novo modo de decomposição: move a cor base em direção a branco/preto sem alterar o hue; fatores de estado (action: 1.2, active: 0.8, focus: 0.3); valores acima de 1.0 invertem a direção" |
options.interaction.legacyStructure | Parâmetro de config | "todos os temas do workspace devem concordar neste valor — true (padrão) mantém a estrutura pública anterior; false habilita grupos solid/ghost expandidos — desde 3.9.0" |
options.interaction.groups | Chave de config | "configura decomposição e levels de surface independentemente para function e feedback; resolução: tema → surface → grupo → grupo-surface — desde 3.12.0" |
options.interaction.decomposition.target | Chave de config | "destino do dilution: 'canvas' (padrão — move em direção ao canvas do quadrante ativo) ou 'anchor' (desde 3.13.1 — move em direção a uma âncora cromática configurável)" |
options.interaction.decomposition.anchor | Chave de config | "config da âncora para target: 'anchor'; anchor.source: 'palette' | 'hex' | 'token'; anchor.canvasAware: âncora responde ao quadrante; anchor.canvasMix: intensidade da resposta (0.0–1.0) — desde 3.13.1" |
options.baseAdaptation | Chave de config | "quando true, superfícies normal de interaction e default de produto respondem ao quadrante ativo (light/dark + positive/negative); por padrão essas superfícies permanecem fixas na cor base autoral — desde 3.13.4" |
theme-engine init:playground | Comando CLI | "npx theme-engine init:playground — copia as 15 configurações de tema de referência do Aplica DS para theme-engine/config/ do workspace do consumidor; útil para explorar o engine ou iniciar com exemplos reais; alias: themes:examples — desde 3.14.x" |
theme-engine fonts:download | Comando CLI | "npx theme-engine fonts:download — baixa 22 famílias OFL dos temas de playground de google/fonts (GitHub) para assets/fonts/; requer internet; alias: playground:fonts — desde 3.14.x" |
theme-engine design:md | Comando CLI | "npx theme-engine design:md [--brand <nome>] — gera DESIGN.md (spec Google Stitch: YAML frontmatter + markdown) com valores reais do brand resolvidos de dist/json/; também grava JSON intermediário em data/foundation/<brand>/design-md.json; aliases: design-md, design:generate — desde 3.15.x" |
theme-engine contracts:generate | Comando CLI | "npx theme-engine contracts:generate [--brand <nome>] [--all] — extrai snapshot estrutural de paths+tipos de dist/json/ para dist/contracts/<brand>-contract.json; publicado no NPM para uso por contracts:diff — desde 3.15.x" |
theme-engine contracts:diff | Comando CLI | "npx theme-engine contracts:diff --contract <arquivo> — compara contrato commitado na biblioteca de componentes com o do pacote instalado; retorna GREEN (0) / ALERT (0) / ERROR (1); template de GitHub Action em templates/github-actions/contracts-check.yml — desde 3.15.x" |
theme-engine ai:init | Comando CLI | "injeta arquivos de contexto do pacote publicado no workspace consumidor; desde 3.10.0, distribui AI_CONTEXT.md e THEME_CONFIG_REFERENCE.md diretamente do pacote, atualizados a cada upgrade; desde 3.15.x, também copia DESIGN.md estático; desde 3.16.1, também instala aplica-knowledge-guide em todas as ferramentas de IA" |
theme-engine ai:knowledge | Comando CLI | "npx theme-engine ai:knowledge — instala skill conversacional aplica-knowledge-guide em .claude/skills/, .cursor/rules/, .github/instructions/ e docs/context/; habilita o assistente a responder perguntas de config, explicar arquitetura e diagnosticar tokens lendo arquivos reais do workspace; aliases: ai:guide, knowledge:init — desde 3.16.1" |
theme-engine audit:accessibility | Comando CLI | "npx theme-engine audit:accessibility — audita pares background/foreground de todos os brands contra critérios WCAG 2.1; calcula taxa de contraste e classifica AA, AAA ou FAIL; requer dist/ gerado — desde 3.15.1" |
global.surfacePolarity | Chave de config global | "em themes.config.json → global.surfacePolarity: false colapsa o workspace para positive-only: data/surface/negative.json é removido, mode e brand param de emitir branches de polaridade, e os outputs semânticos finais geram apenas arquivos *-positive; use em projetos sem dark-on-light ou inverse surfaces — desde 3.14.1" |
options.interaction.surfaces.ghost.ghostNormalTxtOnStrategy | Chave de config | "controla como txtOn é calculado para o estado ghost.normal (background transparente): 'txt' (padrão desde 3.15.1) usa cor interativa da paleta contra o canvas; 'surface' executa txtOnStrategy do tema contra o canvas background (comportamento anterior); sobrescrevível por grupo via options.interaction.groups.<group>.surfaces.ghost.ghostNormalTxtOnStrategy — desde 3.15.1" |
options.txtOnStrategy (colorContrastDecompose) | Chave de config | "quando txtOnStrategy: 'brand-tint', colorContrastDecompose controla a direção do walk e o extremo de fallback: 'startDark' (padrão) prioriza tons escuros / extremo = preto; 'startLight' prioriza tons claros / extremo = branco; usado também por overlap — desde 3.18.0" |
options.txtOnStrategy (overlap) | Chave de config | "quando txtOnStrategy: 'brand-tint', overlap: { level: N } faz superfícies de paleta no nível ≥ N pularem o walk de tint e irem direto ao extremo definido por colorContrastDecompose; útil em paletas saturadas onde o walk produz texto menos legível que preto/branco puro; WCAG preservado — desde 3.18.0" |
mode.productBySurface | Branch interno do engine | "branch gerado pelo sync:architecture para garantir que readable text de produto respeite a polaridade positive/negative — desde 3.8.4" |
mode.brand.brandingBySurface | Branch interno do engine | "branch gerado pelo sync:architecture para que branding não colapse light-positive e light-negative — desde 3.8.2" |
| OKLCh | Espaço de cor | "o pipeline OKLCh" |
| WCAG | Sigla de acessibilidade | "contraste WCAG AA" |
Seção 2 — Nomes próprios do sistema (manter em ambos)
Estes são termos cunhados — nomes de paradigmas, produtos ou personas do Aplica DS. Não se traduzem; aparecem iguais em pt-BR e en-US.
| Termo | Aparece em | Notas |
|---|---|---|
| Config-First | Todos os níveis | Paradigma central do sistema |
| Aplica DS | Todos | Nome do produto |
| Aplica Tokens Theme Engine | Todos | Nome do engine |
| Abstraction Layer | Comunicação pública, site, poster | Meta-grupo = Brand + Mode + Surface + Dimension; não exposto; não é nome técnico canônico |
| Intent Layer | Comunicação pública, site, poster | Meta-grupo = Semantic layer; "mapeia significado e uso" — fronteira exposta canônica |
| Consumer Layer | Comunicação pública, site, poster | Meta-grupo = Foundation layer; "aliases simplificados para times de produto" |
| Tokens Studio | N1, N2 | Nome do plugin Figma — produto de terceiro |
| Product Designer | N1, N2, N3 | Persona — inglês é o termo universal |
| System Designer | N2, N3 | Persona |
| Design Engineer | N3 | Persona |
| Style Dictionary | N3 | Ferramenta open source — nome próprio |
| Docusaurus | Meta/infra | Framework de docs |
| Figma Variables | N1 | Feature nativa do Figma |
brand-tint | N2, N3 | Valor de txtOnStrategy — é um nome de opção |
high-contrast | N2, N3 | Valor de txtOnStrategy |
custom-tint | N2, N3 | Valor de txtOnStrategy |
Seção 3 — Vocabulário das camadas
| pt-BR | en-US | Notas de uso |
|---|---|---|
| Camada | Layer | Sempre com inicial minúscula quando genérico |
| Camada Brand | Brand layer | Inicial maiúscula quando refere à camada específica |
| Camada Mode | Mode layer | Idem |
| Camada Surface | Surface layer | Idem |
| Camada Primitiva | Primitive layer | O nível mais baixo: valores brutos e paleta core |
| Camada Semântica | Semantic layer | O cérebro do sistema: fonte da verdade técnica e exaustiva |
| Camada Foundation | Foundation layer | O nível de consumo: atalhos cognitivos para velocidade de design |
| Camada Dimension | Dimension layer | Idem |
| as cinco camadas | the five layers | Minúsculo quando genérico |
| pipeline de cinco camadas | five-layer pipeline | — |
| cadeia de referências | reference chain | — |
| arquivo gerado | generated file | — |
| arquivo de configuração | configuration file / config file | "config file" é mais natural em en-US |
| schema de arquitetura | architecture schema | — |
| fonte de verdade | source of truth | — |
| fonte de verdade única | single source of truth (SSOT) | A sigla SSOT pode ser usada após primeira menção |
Seção 4 — Vocabulário de cores
| pt-BR | en-US | Notas de uso |
|---|---|---|
| Token de cor | Color token | — |
| Paleta | Palette | — |
| Cor de marca | Brand color | — |
| Cor de ação | Action color | Equivale a "function color" — preferir "action" em texto simples |
| Cor de feedback | Feedback color | — |
| Cor de produto | Product color | — |
| Cor ambiente | Ambient color | — |
| Modo claro | Light mode | — |
| Modo escuro | Dark mode | — |
| Superfície positiva | Positive surface | — |
| Superfície negativa | Negative surface | "inverted surface" é aceitável mas menos preciso |
| Quadrante | Quadrant | Combinação dos dois eixos: light/dark × positive/negative. As quatro variantes de um tema: light-positive, light-negative, dark-positive, dark-negative. Usar sempre "quadrant" em en-US, "quadrante" em pt-BR |
| Inversão de escala | Scale inversion | — |
| Cinza / Escala de cinza | Gray / Grayscale | — |
| Neutros / Neutrals | Neutrals | Manter "neutrals" em ambos os idiomas é aceitável |
| Croma | Chroma | — |
| Saturação | Saturation | — |
| Luminosidade | Lightness | — |
| Matiz | Hue | — |
| Tom quente / frio | Warm tone / Cool tone | — |
| Nível de intensidade | Intensity level | — |
| Nível mais claro | Lightest level | — |
| Nível mais escuro | Darkest level | — |
| Decomposição de cor | Color decomposition | — |
| Contraste | Contrast | — |
| Par de cor | Color pair | "background + txtOn pair" é a forma canônica para o par de contraste WCAG |
| Contrato de cor expandido | Four-part color contract | Contrato de 4 partes: background / txtOn / border / txt — introduzido em 3.6.0 |
| Texto sobre canvas | Text on canvas | Texto em fluxo de conteúdo sobre o fundo da página — use txt, nunca txtOn |
| Estratégia de texto | Text strategy | Referindo-se a txtOnStrategy |
| Tom de marca | Brand tint | — |
| Override de cinza | Grayscale override | — |
| Override de neutrals | Neutrals override | — |
Valores fixos de intensidade (manter em ambos): lowest, low, default, high, highest
Seção 5 — Vocabulário de tipografia e dimensão
| pt-BR | en-US | Notas de uso |
|---|---|---|
| Tipografia | Typography | — |
| Família de fonte | Font family | — |
| Peso | Weight | "font weight" quando combinado |
| Entrelinha | Line height | — |
| Escala tipográfica | Typography scale | — |
| Estilo de texto | Text style | — |
| Estilo composto | Composite style | "composite typography style" |
| Espaçamento | Spacing | — |
| Dimensão | Dimension | — |
| Escala dimensional | Dimension scale | — |
| Grade de 4 pontos | 4-point grid | "4pt grid" é abreviação aceita |
| Unidade de design padrão | Default design unit | — |
| Tamanho base | Base size | — |
| Densidade | Density | Referindo-se às variantes minor/normal/major |
| Compacto | Compact / Dense | "compact" para texto, "dense" para interfaces |
| Espaçoso | Spacious | — |
| Ritmo vertical | Vertical rhythm | — |
| Múltiplo | Multiple | "múltiplo de 4" → "multiple of 4" |
Nomes de alias da escala (manter em ambos): nano, micro, extraSmall, small, medium, large, extraLarge, mega, giga, tera, peta
Variantes de densidade (manter em ambos): minor, normal, major
Seção 6 — Vocabulário do build e engine
| pt-BR | en-US | Notas de uso |
|---|---|---|
| Motor / Engine | Engine | "engine" é aceito em pt-BR também |
| Pipeline de build | Build pipeline | — |
| Geração de dados | Data generation | — |
| Etapa de geração | Generation stage | — |
| Etapa de transformação | Transformation stage | — |
| Formato de saída | Output format | — |
| Build incremental | Incremental build | — |
| Build completo | Full build | — |
| Propagação de referências | Reference propagation | — |
| Resolução de referências | Reference resolution | — |
| Decomposição | Decomposition | — |
| Sincronização | Sync | "sync" é aceito informalmente |
| Gradiente | Gradient | — |
| Armadilha dos gradientes | Gradient trap | — |
| Tema registrado | Registered theme | — |
| Foundation padrão | Default foundation | — |
| Foundation customizada | Custom foundation | — |
| Output | Output | Manter em ambos |
| Distribuível / dist | Distributable / dist | "dist" é universal |
Seção 7 — Vocabulário de acessibilidade
| pt-BR | en-US | Notas de uso |
|---|---|---|
| Acessibilidade | Accessibility | — |
| Conformidade WCAG | WCAG compliance | — |
| Nível AA | AA level / WCAG AA | A sigla é universal |
| Nível AAA | AAA level / WCAG AAA | — |
| Razão de contraste | Contrast ratio | — |
| Contraste mínimo | Minimum contrast | — |
| Alvo de toque | Touch target | — |
| Leitura | Readability | Contexto: entrelinha para leitura |
| Legibilidade | Legibility | Contexto: tamanho de fonte |
| Fadiga visual | Visual fatigue | "eye strain" é igualmente correto |
Seção 8 — Vocabulário de governança e processo
| pt-BR | en-US | Notas de uso |
|---|---|---|
| Governança | Governance | — |
| Custo exponencial | Exponential cost | — |
| Dívida técnica | Technical debt | — |
| Entropia | Entropy | — |
| Breaking change | Breaking change | Manter em ambos |
| Mudança destrutiva | Breaking change | Usar "breaking change" sempre |
| Depreciação | Deprecation | — |
| Versionamento semântico | Semantic versioning | "SemVer" é abreviação aceita |
| Versão maior | Major version | — |
| Versão menor | Minor version | — |
| Patch | Patch | Manter em ambos |
| Ciclo de revisão | Review cycle | — |
| Sobreposição responsável | Responsible override | — |
| Estudar → Testar → Documentar | Study → Test → Document | Manter a estrutura de seta |
| Curadoria | Curation | — |
| Contrato de tokens | Token contract | — |
| Padrão proibido | Forbidden pattern | — |
| Anti-pattern | Anti-pattern | Manter em ambos |
| Namespace reservado | Reserved namespace | — |
Seção 9 — Vocabulário pedagógico (tutoriais)
| pt-BR | en-US | Notas de uso |
|---|---|---|
| Espiral de aprendizado | Learning spiral | — |
| Trilha de aprendizado | Learning path | — |
| Pré-requisito | Prerequisite | — |
| Checkpoint | Checkpoint | Manter em ambos |
| Exercício | Exercise | — |
| Resultado esperado | Expected result | — |
| Exemplo guiado | Guided example | — |
| Cenário | Scenario | — |
| Decisão de design | Design decision | — |
| Caso de uso | Use case | — |
| Fluxo de trabalho | Workflow | — |
| Onboarding | Onboarding | Manter em ambos |
Seção 10 — Metáforas do sistema
O Aplica DS usa metáforas específicas para explicar conceitos. Estas metáforas têm formas aprovadas em inglês.
| Metáfora pt-BR | Metáfora en-US | Onde aparece |
|---|---|---|
| "a tinta" (pigmento puro) | "the paint" (raw pigment) | N2-01, token-architecture |
| "o propósito" (semantic) | "the purpose" | N2-01 |
| "o vocabulário simplificado" (foundation) | "the simplified vocabulary" | N2-01 |
| "O Dicionário" (semantic) | "The Dictionary" | N1-01, N1-02 |
| "O Atalho" (foundation) | "The Shortcut" | N1-01, N1-02 |
| "Bolo de Camadas" (arquitetura) | "Layer Cake" | S-N1-01 |
| "Config-First: o Figma como consumidor" | "Config-First: Figma as a consumer" | N2-03 |
| "fazer design, não digitação" | "designing, not data-entry" | S-N2-03 |
Histórico de atualizações
| Data | Mudança |
|---|---|
| 2026-05-15 | Adicionados termos 3.15.1–3.18.0: theme-engine ai:knowledge, theme-engine audit:accessibility, global.surfacePolarity, ghostNormalTxtOnStrategy, colorContrastDecompose, overlap (brand-tint); atualizado theme-engine ai:init e theme-engine preview (redesign 3.17.0) |
| 2026-05-10 | Adicionados termos 3.15.x: theme-engine design:md, theme-engine contracts:generate, theme-engine contracts:diff; atualizado theme-engine ai:init |
| 2026-05-09 | Adicionados termos 3.14.x: theme-engine init:playground, theme-engine fonts:download |
| 2026-05-03 | Adicionados termos 3.13.x: options.interaction.decomposition.target, options.interaction.decomposition.anchor, options.baseAdaptation; atualizado theme-engine preview (Summary view 3.13.0) |
| 2026-04-30 | Adicionados termos 3.10.0–3.12.0: options.interaction.groups, theme-engine ai:init; atualizado theme-engine preview (live reload 3.11.0) |
| 2026-04-28 | Adicionados termos 3.8.x–3.9.0: theme-engine preview, options.interaction.decomposition.method, system-scale, dilution, options.interaction.legacyStructure, mode.productBySurface, mode.brand.brandingBySurface |
| 2026-04-23 | Adicionados termos 3.6.x: txt, txtBaseColorLevel, fallbackBaseColorLevel, textExposure, generateTxt, generation.colorText; vocabulário de contrato expandido |
| 2026-04-10 | Versão inicial — criado antes da primeira tradução |