@apollion-dsi/core 5.3.0 → 5.5.0

package/lib/themes/Colors/Colors.presets.d.ts

@@ -9,8 +9,8 @@ import { ColorsInput } from './Colors.interface';
  * `deep*`/`transparent`) pass through untouched, so surfaces keep working and
  * `neutral`/`grayscale` ramps still derive from the same anchors.
  *
- * Built for the 5-theme accessibility dropdown of the radar SSG (Claro /
- * Escuro / Tons de cinza / Alto contraste / Cores para daltônicos). `light`
+ * Built for the 5-theme accessibility dropdown of the radar SSG (Light /
+ * Dark / Grayscale / High contrast / Colorblind-safe colors). `light`
  * and `dark` are just the stock theme in each mode — the three presets below
  * cover the accessibility modes.
  *

package/lib/themes/Colors/index.d.ts

@@ -1,8 +1,8 @@
 /**
- * Barrel público do módulo `Colors`.
+ * Public barrel for the `Colors` module.
  *
- * Qualquer outro arquivo do projeto deve importar do barrel, nunca de paths
- * internos como `./Colors.interface` ou `./Colors.props`.
+ * Any other file in the project should import from the barrel, never from
+ * internal paths like `./Colors.interface` or `./Colors.props`.
  */
 export * from './Colors.interface';
 export * from './Colors.helpers';

package/lib/themes/Colors/index.esm.js

@@ -1 +1 @@
-import{a as v,b as w,c as x,d as y,e as z,f as A,g as B}from"../../chunks/chunk-FJUISCKG.esm.js";import{a,b,c,d,e,f,g,h,i,j,k,l,m,n,o,p,q,r,s,t,u}from"../../chunks/chunk-E3MSXQXV.esm.js";import"../../chunks/chunk-TQJTHPA3.esm.js";import"../../chunks/chunk-BV6GHAF7.esm.js";import"../../chunks/chunk-G5Z7USXC.esm.js";import"../../chunks/chunk-GZONWSRB.esm.js";export{j as DISABLED_NEUTRAL_INDICES,a as HextoRgb,c as MIN_CONTRAST_AA,n as MIN_STATE_CONTRAST,h as NEUTRAL_TEXT_INDICES,z as OKABE_ITO,g as READABLE_TEXT_PALETTES,o as STATE_DELTA_L_JND,k as STRUCTURAL_NEUTRAL_INDICES,B as accessibilityPalettes,A as colorblindPalette,w as createColors,i as createReadableTextLayer,v as defaultInputColors,e as getColor,f as getContrastColor,b as getOppositeColor,x as grayscalePalette,y as highContrastPalette,t as mountActionColors,s as mountBaseColors,q as mountGreyscaleColors,u as mountMainColors,r as mountNeutralColors,p as mountSingleColor,d as readableColor,l as resolveDisabledNeutral,m as resolveStructuralNeutrals};
+import{a as v,b as w,c as x,d as y,e as z,f as A,g as B}from"../../chunks/chunk-3RNWYCCU.esm.js";import{a,b,c,d,e,f,g,h,i,j,k,l,m,n,o,p,q,r,s,t,u}from"../../chunks/chunk-E3MSXQXV.esm.js";import"../../chunks/chunk-TQJTHPA3.esm.js";import"../../chunks/chunk-BV6GHAF7.esm.js";import"../../chunks/chunk-G5Z7USXC.esm.js";import"../../chunks/chunk-GZONWSRB.esm.js";export{j as DISABLED_NEUTRAL_INDICES,a as HextoRgb,c as MIN_CONTRAST_AA,n as MIN_STATE_CONTRAST,h as NEUTRAL_TEXT_INDICES,z as OKABE_ITO,g as READABLE_TEXT_PALETTES,o as STATE_DELTA_L_JND,k as STRUCTURAL_NEUTRAL_INDICES,B as accessibilityPalettes,A as colorblindPalette,w as createColors,i as createReadableTextLayer,v as defaultInputColors,e as getColor,f as getContrastColor,b as getOppositeColor,x as grayscalePalette,y as highContrastPalette,t as mountActionColors,s as mountBaseColors,q as mountGreyscaleColors,u as mountMainColors,r as mountNeutralColors,p as mountSingleColor,d as readableColor,l as resolveDisabledNeutral,m as resolveStructuralNeutrals};

package/lib/themes/Component/Component.helpers.d.ts

@@ -0,0 +1,24 @@
+import type { ComponentTokensInput, ComponentTokensLayer } from './Component.interface';
+/**
+ * Resolves the component token tier (`theme.component`) from consumer
+ * overrides deep-merged over the defaults.
+ *
+ * **Purity + idempotence (ADR-002 §9 contract, same as `createSemantic` /
+ * `createFoundation`):**
+ * - Reads nothing external (Date, Math.random, env, DOM).
+ * - Does not mutate the input.
+ * - Same input → same output (referentially new, byte-equivalent).
+ *
+ * **Aliasing discipline (ADR-020):** defaults reference foundation scales
+ * only (spacing aliases, font-size/weight keys, border-radius keys) — never
+ * raw palette values or raw CSS strings. Raw numbers appear only for
+ * tuned geometry (heights, switch track/thumb) that intentionally lives off
+ * the scales.
+ *
+ * @param input - Deep-partial consumer overrides (`createTheme({ component })`).
+ * @returns Complete component tier, ready to be plugged into `theme.component`.
+ *
+ * @see ./Component.interface.ts
+ * @see ../../docs/adr/ADR-020-component-token-tier.md
+ */
+export declare function createComponentTokens(input?: ComponentTokensInput): ComponentTokensLayer;

package/lib/themes/Component/Component.interface.d.ts

@@ -0,0 +1,93 @@
+import type { BorderInput } from '../Border';
+import type { FontInput, FontSizeKey } from '../Font';
+import type { SpacingAlias } from '../Spacing';
+/** Key of the theme's border-radius scale (`theme.border.borderRadius`). */
+export type BorderRadiusKey = keyof BorderInput['borderRadius'];
+/** Key of the theme's font-weight scale (`theme.font.fontWeight`). */
+export type FontWeightKey = keyof FontInput['fontWeight'];
+/** Key of the theme's line-height scale (`theme.font.lineHeight`). */
+export type LineHeightKey = keyof FontInput['lineHeight'];
+/**
+ * Per-size tokens of the `Input` (`theme.component.input.size.*`).
+ *
+ * Every non-numeric field is an ALIAS into a foundation scale (spacing /
+ * font-size / border-radius keys), never a raw CSS value — the ADR-020
+ * aliasing discipline. `height` is a raw px number: input heights are a
+ * tuned, continuous design decision that intentionally does not land on any
+ * scale step (same rationale as shadow geometry in the tokens IR).
+ */
+export interface InputSizeTokens {
+    py: SpacingAlias;
+    fontSize: FontSizeKey;
+    borderRadius: BorderRadiusKey;
+    height: number;
+}
+/**
+ * Per-size geometry of the `Switch` (`theme.component.switch.size.*`).
+ * All px numbers — the switch is a drawn control (track + thumb), not
+ * composed from the spacing scale.
+ */
+export interface SwitchSizeTokens {
+    trackW: number;
+    trackH: number;
+    thumb: number;
+    pad: number;
+}
+/** Per-size tokens of the native `Select` (`theme.component.select.size.*`). */
+export interface SelectSizeTokens {
+    height: number;
+    px: SpacingAlias;
+}
+/** Per-size tokens of the `Button` (`theme.component.button.size.*`).
+ * `textTransform` mirrors the `FontFactory` union (including the historical
+ * `captalyze` spelling) — the tier feeds the factory verbatim. */
+export interface ButtonSizeTokens {
+    fontSize: FontSizeKey;
+    fontWeight: FontWeightKey;
+    textTransform?: 'normal' | 'uppercase' | 'lowercase' | 'captalyze';
+    py: SpacingAlias;
+    px: SpacingAlias;
+    borderRadius: BorderRadiusKey;
+}
+/** Per-size tokens of the `InputSelect` (`theme.component.inputSelect.size.*`). */
+export interface InputSelectSizeTokens {
+    py: SpacingAlias;
+    px: SpacingAlias;
+    fontSize: FontSizeKey;
+    lineHeight?: LineHeightKey;
+    borderRadius: BorderRadiusKey;
+    height: number;
+}
+/**
+ * Component token tier (`theme.component.*`) — ADR-020.
+ *
+ * Names each component's themeable decisions so the surface is enumerable
+ * (a themer restyles one component without forking it). Defaults alias
+ * foundation scales only; consumer overrides deep-merge over defaults via
+ * `createTheme({ component: { … } })`.
+ */
+export interface ComponentTokensLayer {
+    input: {
+        size: Record<'expansive' | 'medium' | 'compact' | 'micro', InputSizeTokens>;
+    };
+    switch: {
+        size: Record<'small' | 'medium' | 'large', SwitchSizeTokens>;
+    };
+    select: {
+        size: Record<'small' | 'medium' | 'large', SelectSizeTokens>;
+    };
+    button: {
+        size: Record<'extraSmall' | 'small' | 'medium' | 'large', ButtonSizeTokens>;
+    };
+    inputSelect: {
+        size: Record<'expansive' | 'medium' | 'compact' | 'micro', InputSelectSizeTokens>;
+    };
+}
+/** Deep-partial consumer override shape accepted by `createComponentTokens`. */
+export type ComponentTokensInput = {
+    [K in keyof ComponentTokensLayer]?: {
+        size?: {
+            [S in keyof ComponentTokensLayer[K]['size']]?: Partial<ComponentTokensLayer[K]['size'][S]>;
+        };
+    };
+};

package/lib/themes/Component/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Component token tier — each component's themeable decisions, enumerable
+ * and override-able (ADR-020).
+ *
+ * Exposed at `theme.component` as of `@apollion-dsi/core` 5.4.0.
+ *
+ * Subpath import (preferred):
+ * ```ts
+ * import { createComponentTokens, type ComponentTokensLayer } from '@apollion-dsi/core/themes/component';
+ * ```
+ *
+ * Also re-exported by the `themes` barrel:
+ * `import { createComponentTokens } from '@apollion-dsi/core/themes';`.
+ *
+ * @see ../../../docs/adr/ADR-020-component-token-tier.md
+ */
+export type { BorderRadiusKey, ButtonSizeTokens, ComponentTokensInput, ComponentTokensLayer, FontWeightKey, InputSelectSizeTokens, InputSizeTokens, LineHeightKey, SelectSizeTokens, SwitchSizeTokens, } from './Component.interface';
+export { createComponentTokens } from './Component.helpers';

package/lib/themes/Component/index.esm.js

@@ -0,0 +1 @@
+import{b as a}from"../../chunks/chunk-7EGX7BMB.esm.js";import"../../chunks/chunk-GZONWSRB.esm.js";export{a as createComponentTokens};

package/lib/themes/Deep/index.d.ts

@@ -1,8 +1,8 @@
 /**
- * Barrel público do módulo `Deep`.
+ * Public barrel for the `Deep` module.
  *
- * Qualquer outro arquivo do projeto deve importar do barrel, nunca de paths
- * internos como `./Deep.interface` ou `./Deep.props`.
+ * Any other file in the project should import from the barrel, never from
+ * internal paths like `./Deep.interface` or `./Deep.props`.
  */
 export * from './Deep.interface';
 export * from './Deep.props';

package/lib/themes/Deep/index.esm.js

@@ -1 +1 @@
-import{a}from"../../chunks/chunk-OWMRURZT.esm.js";import"../../chunks/chunk-FJUISCKG.esm.js";import"../../chunks/chunk-E3MSXQXV.esm.js";import"../../chunks/chunk-TQJTHPA3.esm.js";import"../../chunks/chunk-BV6GHAF7.esm.js";import"../../chunks/chunk-G5Z7USXC.esm.js";import"../../chunks/chunk-GZONWSRB.esm.js";export{a as createDeepTheme};
+import{a}from"../../chunks/chunk-OWMRURZT.esm.js";import"../../chunks/chunk-3RNWYCCU.esm.js";import"../../chunks/chunk-E3MSXQXV.esm.js";import"../../chunks/chunk-TQJTHPA3.esm.js";import"../../chunks/chunk-BV6GHAF7.esm.js";import"../../chunks/chunk-G5Z7USXC.esm.js";import"../../chunks/chunk-GZONWSRB.esm.js";export{a as createDeepTheme};

package/lib/themes/Depth/index.d.ts

@@ -1,8 +1,8 @@
 /**
- * Barrel público do módulo `Depth`.
+ * Public barrel for the `Depth` module.
  *
- * Qualquer outro arquivo do projeto deve importar do barrel, nunca de paths
- * internos como `./Depth.interface` ou `./Depth.props`.
+ * Any other file in the project should import from the barrel, never from
+ * internal paths like `./Depth.interface` or `./Depth.props`.
  */
 export * from './Depth.interface';
 export * from './Depth.props';

package/lib/themes/Dimension/index.d.ts

@@ -1,10 +1,10 @@
 /**
- * Barrel público do módulo `Dimension` (density axis — ADR-006 E2).
+ * Public barrel of the `Dimension` module (density axis — ADR-006 E2).
  *
- * Não confundir com `theme.semantic.dimension` (spacing-aliases layer); esta
- * `Dimension` aqui é a density/multiplier axis introduzida em v4.
+ * Not to be confused with `theme.semantic.dimension` (spacing-aliases layer);
+ * this `Dimension` is the density/multiplier axis introduced in v4.
  *
- * @see ./Dimension.interface.ts (naming disambiguation completo)
+ * @see ./Dimension.interface.ts (full naming disambiguation)
  */
 export * from './Dimension.interface';
 export * from './Dimension.props';

package/lib/themes/Font/index.d.ts

@@ -1,8 +1,8 @@
 /**
- * Barrel público do módulo `Font`.
+ * Public barrel for the `Font` module.
  *
- * Qualquer outro arquivo do projeto deve importar do barrel, nunca de paths
- * internos como `./Font.interface` ou `./Font.props`.
+ * Any other file in the project should import from the barrel, never from
+ * internal paths like `./Font.interface` or `./Font.props`.
  */
 export * from './Font.interface';
 export * from './Font.props';

package/lib/themes/Foundation/Foundation.helpers.d.ts

@@ -1,23 +1,23 @@
 import type { FoundationLayer } from './Foundation.interface';
 import type { SemanticLayer } from '../Semantic/Semantic.interface';
 /**
- * Resolve a camada Foundation a partir da camada Semantic.
+ * Resolves the Foundation layer from the Semantic layer.
  *
- * **Pureza + idempotência (contrato ADR-002 §9, herdado de Semantic):**
- * - Não lê nada externo (Date, Math.random, env, DOM).
- * - Não muta a entrada.
- * - Mesma entrada → mesma saída (referencialmente nova, byte-equivalente).
+ * **Purity + idempotence (ADR-002 §9 contract, inherited from Semantic):**
+ * - Reads nothing external (Date, Math.random, env, DOM).
+ * - Does not mutate the input.
+ * - Same input → same output (referentially new, byte-equivalent).
  *
- * Foundation é puramente derivativa de Semantic — toda alteração de cor/
- * espaçamento propaga via Semantic. Mapping segue ADR-002 §3 + §5.
+ * Foundation is purely derivative of Semantic — every color/spacing change
+ * propagates via Semantic. The mapping follows ADR-002 §3 + §5.
  *
- * @param semantic - Camada Semantic já resolvida (vinda de `createSemantic`).
- * @returns Camada Foundation completa, pronta pra ser plugada em
+ * @param semantic - Already-resolved Semantic layer (from `createSemantic`).
+ * @returns Complete Foundation layer, ready to be plugged into
  *          `theme.foundation`.
  *
  * @example
  * ```ts
- * // Em código de produto (DEX/Jovian/Fanaticofc):
+ * // In product code (DEX/Jovian/Fanaticofc):
  * const StyledCTA = styled.button`
  *   background: ${({ theme }) => theme.foundation.bg.primary};
  *   color:      ${({ theme }) => theme.foundation.text.onPrimary};
@@ -26,7 +26,7 @@ import type { SemanticLayer } from '../Semantic/Semantic.interface';
  * ```
  *
  * @see ../../docs/adr/ADR-002-layered-theme-aliases-and-surface.md §3, §5
- * @see ../Semantic/Semantic.helpers.ts (camada de origem)
- * @see ./README.md (cheatsheet completo)
+ * @see ../Semantic/Semantic.helpers.ts (source layer)
+ * @see ./README.md (full cheatsheet)
  */
 export declare function createFoundation(semantic: SemanticLayer): FoundationLayer;

package/lib/themes/Foundation/Foundation.interface.d.ts

@@ -1,25 +1,24 @@
 /**
- * Camada Foundation do theme — aliases curtos e ergonômicos sobre Semantic.
- * Esta é a camada que produto (telas, features, clients DEX/Jovian/Fanaticofc)
- * deve consumir por default.
+ * Foundation layer of the theme — short, ergonomic aliases over Semantic.
+ * This is the layer that product code (screens, features, DEX/Jovian/Fanaticofc
+ * clients) should consume by default.
  *
- * Filosofia (Aplica DS, adotada literalmente): "Foundation is not a technical
- * simplification — it is a product decision." Não exige saber a taxonomia
- * Semantic completa; um dev de produto escreve `theme.foundation.bg.primary`
- * em vez de `theme.semantic.color.interface.function.primary.normal.bg`.
+ * Philosophy (Aplica DS, adopted literally): "Foundation is not a technical
+ * simplification — it is a product decision." It does not require knowing the
+ * full Semantic taxonomy; a product dev writes `theme.foundation.bg.primary`
+ * instead of `theme.semantic.color.interface.function.primary.normal.bg`.
  *
- * Quem deve usar o quê (ADR-002 §5):
- * - Produto      → Foundation (esta camada)
- * - Componentes  → Semantic
- * - Engine       → Structural (`theme.colors.*`, `theme.spacing(...)`)
+ * Who should use what (ADR-002 §5):
+ * - Product     → Foundation (this layer)
+ * - Components  → Semantic
+ * - Engine      → Structural (`theme.colors.*`, `theme.spacing(...)`)
  *
  * @see ../../docs/adr/ADR-002-layered-theme-aliases-and-surface.md
  * @see ../../docs/CONCEPTS.md §2 (Layer Cake) · §3 (3-group communication)
- * @see ./README.md (cheatsheet completo)
+ * @see ./README.md (full cheatsheet)
  */
 /**
- * Aliases curtos para cores de fundo. Mapeiam para Semantic da seguinte
- * forma:
+ * Short aliases for background colors. They map to Semantic as follows:
  * - `bg.primary`   ← `semantic.color.interface.function.primary.normal.bg`
  * - `bg.secondary` ← `semantic.color.interface.function.secondary.normal.bg`
  * - `bg.tertiary`  ← `semantic.color.interface.function.tertiary.normal.bg`
@@ -27,7 +26,7 @@
  * - `bg.danger`    ← `semantic.color.feedback.danger.bg`
  * - `bg.warning`   ← `semantic.color.feedback.warning.bg`
  * - `bg.info`      ← `semantic.color.feedback.information.bg`
- * - `bg.brand`     ← `semantic.color.brand.first.default.surface` (cor de marca / `main`)
+ * - `bg.brand`     ← `semantic.color.brand.first.default.surface` (brand color / `main`)
  */
 export interface FoundationBg {
     primary: string;
@@ -40,13 +39,13 @@ export interface FoundationBg {
     brand: string;
 }
 /**
- * Aliases curtos para cores de texto "sobre" um fundo Foundation. O sufixo
- * (`onPrimary`) indica explicitamente o par de bg.
+ * Short aliases for text colors "on" a Foundation background. The suffix
+ * (`onPrimary`) explicitly indicates the bg pair.
  *
- * Garantia de contraste WCAG ≥ AA é responsabilidade da camada Semantic, que
- * resolve cada `txtOn` via `getContrastColor(bg)` (luminância da própria cor de
- * fundo) — dark-mode-stable: `onMain` permanece legível nos dois modes porque a
- * cor de marca não troca. Ver ADR-010.
+ * The WCAG ≥ AA contrast guarantee is the Semantic layer's responsibility,
+ * which resolves each `txtOn` via `getContrastColor(bg)` (luminance of the
+ * background color itself) — dark-mode-stable: `onMain` stays readable in both
+ * modes because the brand color does not change. See ADR-010.
  */
 export interface FoundationText {
     onPrimary: string;
@@ -61,10 +60,10 @@ export interface FoundationText {
     onComplementary: string;
 }
 /**
- * Aliases curtos de espaçamento. Mapeiam para spacing Semantic preservando
- * convenção de 2-3 letras canônica (xs/sm/md/lg/xl/xxl).
+ * Short spacing aliases. They map to Semantic spacing while preserving the
+ * canonical 2-3 letter convention (xs/sm/md/lg/xl/xxl).
  *
- * Tradução para spacing aliases legadas de Apollion:
+ * Translation to Apollion's legacy spacing aliases:
  * - `xs`  ← `semantic.dimension.spacing.xs`
  * - `sm`  ← `semantic.dimension.spacing.small`
  * - `md`  ← `semantic.dimension.spacing.medium`
@@ -81,8 +80,8 @@ export interface FoundationSpacing {
     xxl: string;
 }
 /**
- * Forma completa da camada Foundation. Exposta em `theme.foundation` a partir
- * do Apollion v3.2.0 (ADR-002 Slice 3).
+ * Complete shape of the Foundation layer. Exposed at `theme.foundation` as of
+ * Apollion v3.2.0 (ADR-002 Slice 3).
  */
 export interface FoundationLayer {
     bg: FoundationBg;

package/lib/themes/Foundation/index.d.ts

@@ -1,15 +1,15 @@
 /**
- * Camada Foundation — aliases curtos e ergonômicos sobre Semantic.
+ * Foundation layer — short, ergonomic aliases over Semantic.
  *
- * Exposta em `theme.foundation` a partir de `@apollion-dsi/core` 3.2.0.
+ * Exposed at `theme.foundation` as of `@apollion-dsi/core` 3.2.0.
  *
- * Subpath import (preferido):
+ * Subpath import (preferred):
  * ```ts
  * import { createFoundation, type FoundationLayer } from '@apollion-dsi/core/themes/foundation';
  * ```
  *
- * Re-exportada também pelo barrel `themes` para compat com consumers
- * pre-subpath: `import { createFoundation } from '@apollion-dsi/core/themes';`.
+ * Also re-exported by the `themes` barrel for compat with pre-subpath
+ * consumers: `import { createFoundation } from '@apollion-dsi/core/themes';`.
  *
  * @see ../../../docs/adr/ADR-002-layered-theme-aliases-and-surface.md
  */

package/lib/themes/GlobalStyle/index.d.ts

@@ -1,4 +1,4 @@
 /**
- * Barrel público do módulo `GlobalStyle`.
+ * Public barrel for the `GlobalStyle` module.
  */
 export { GlobalStyleComponent as GlobalStyle } from './GlobalStyle';

package/lib/themes/Semantic/Semantic.helpers.d.ts

@@ -2,9 +2,9 @@ import type { SemanticLayer } from './Semantic.interface';
 import type { ColorsThemeInterface } from '../Colors/Colors.interface';
 import type { SpacingThemeInterface } from '../Spacing/Spacing.interface';
 /**
- * Subset do `Theme` estrutural necessário para derivar a camada Semantic.
+ * Subset of the structural `Theme` needed to derive the Semantic layer.
  *
- * Tipado explicitamente (em vez de `Theme`) para evitar ciclo de tipos
+ * Typed explicitly (instead of `Theme`) to avoid the type cycle
  * `ThemeProvider.interface → Semantic.interface → ThemeProvider.interface`.
  */
 export interface CreateSemanticInput {
@@ -12,20 +12,20 @@ export interface CreateSemanticInput {
     spacing: SpacingThemeInterface;
 }
 /**
- * Resolve a camada Semantic a partir do theme estrutural.
+ * Resolves the Semantic layer from the structural theme.
  *
- * **Pureza + idempotência (contrato de ADR-002 §9):**
- * - Não lê nada externo (Date, Math.random, env, DOM).
- * - Não muta a entrada.
- * - Mesma entrada → mesma saída (referencialmente nova, byte-equivalente).
+ * **Purity + idempotence (ADR-002 §9 contract):**
+ * - Reads nothing external (Date, Math.random, env, DOM).
+ * - Does not mutate the input.
+ * - Same input → same output (referentially new, byte-equivalent).
  *
- * Esse contrato é o que permite chamada via `useMemo([theme])` para
- * performance, sem depender de garantias semânticas do React (que reserva o
- * direito de descartar caches — ver ADR-002 §9 / React docs).
+ * This contract is what allows calling it via `useMemo([theme])` for
+ * performance, without relying on React's semantic guarantees (React reserves
+ * the right to discard caches — see ADR-002 §9 / React docs).
  *
  * Mapping rationale (ADR-002 §5, Aplica ⇄ Apollion):
  * - `feedback.{state}.bg`     ← `colors.{state}.base`
- * - `feedback.{state}.txtOn`  ← `getContrastColor(bg)` (luminância WCAG; ADR-010)
+ * - `feedback.{state}.txtOn`  ← `getContrastColor(bg)` (WCAG luminance; ADR-010)
  * - `feedback.{state}.border` ← `colors.{state}.dark`
  * - `interface.function.{role}.normal.bg`     ← `colors.{role}.base`
  * - `interface.function.{role}.normal.txtOn`  ← `getContrastColor(bg)`
@@ -33,8 +33,8 @@ export interface CreateSemanticInput {
  * - `brand.{...}.default.txtOn`               ← `getContrastColor(surface)` (dark-mode-stable, ADR-010)
  * - `dimension.spacing.{alias}`               ← `spacing(alias)`
  *
- * @param theme - Subset do theme estrutural com `colors` e `spacing` resolvidos.
- * @returns Camada Semantic completa, pronta pra ser plugada em `theme.semantic`.
+ * @param theme - Subset of the structural theme with `colors` and `spacing` resolved.
+ * @returns Complete Semantic layer, ready to be plugged into `theme.semantic`.
  *
  * @example
  * ```ts
@@ -42,7 +42,7 @@ export interface CreateSemanticInput {
  *
  * const theme = createTheme();
  * theme.semantic.color.feedback.success.bg;
- * // → mesmo valor que theme.colors.success.base
+ * // → same value as theme.colors.success.base
  * ```
  *
  * @see ../../docs/adr/ADR-002-layered-theme-aliases-and-surface.md §3, §5, §9

package/lib/themes/Semantic/Semantic.interface.d.ts

@@ -1,14 +1,14 @@
 /**
- * Camada Semantic do theme — tokens nomeados por intenção, mirror direto da
- * taxonomia de Aplica DS (`semantic.<category>.<group>.<state>.<property>`).
+ * Semantic layer of the theme — tokens named by intent, a direct mirror of the
+ * Aplica DS taxonomy (`semantic.<category>.<group>.<state>.<property>`).
  *
- * Esta camada NÃO substitui a camada estrutural (`theme.colors.*`,
- * `theme.spacing(...)`, etc.); ela é uma leitura paralela, derivada uma
- * única vez em `createTheme()` a partir dos tokens estruturais já existentes.
+ * This layer does NOT replace the structural layer (`theme.colors.*`,
+ * `theme.spacing(...)`, etc.); it is a parallel read, derived exactly once in
+ * `createTheme()` from the already-existing structural tokens.
  *
- * Componentes do `@apollion-dsi/core` devem preferir tokens Semantic ao
- * acessar cores/dimensões com intent claro (feedback, interface function,
- * brand). Produto deve consumir Foundation (camada acima) — ver §3 da
+ * `@apollion-dsi/core` components should prefer Semantic tokens when accessing
+ * colors/dimensions with a clear intent (feedback, interface function,
+ * brand). Product code should consume Foundation (the layer above) — see §3 of
  * `docs/adr/ADR-002-layered-theme-aliases-and-surface.md`.
  *
  * @see ../../docs/adr/ADR-002-layered-theme-aliases-and-surface.md
@@ -16,24 +16,24 @@
  * @see https://docs.aplica.me/en-US/design-tokens-fundamentals/token-architecture
  */
 /**
- * Par cor-de-fundo / cor-de-texto-sobre. Convenção Aplica DS.
- * `txtOn` é a cor de texto garantida com contraste WCAG ≥ AA sobre `bg`.
+ * Background-color / text-color-on pair. Aplica DS convention.
+ * `txtOn` is the text color guaranteed with WCAG ≥ AA contrast over `bg`.
  */
 export interface SemanticBgPair {
     bg: string;
     txtOn: string;
 }
 /**
- * Triplet com borda explícita, usado em estados de feedback (success, danger,
- * warning, information) onde a borda costuma destacar o card/notification.
+ * Triplet with an explicit border, used in feedback states (success, danger,
+ * warning, information) where the border usually highlights the card/notification.
  */
 export interface SemanticFeedbackTokens extends SemanticBgPair {
     border: string;
 }
 /**
- * Tokens de feedback — comunicam estado funcional ao usuário.
- * Mapeiam para `theme.colors.{success, danger, warning, information}` no
- * nível estrutural.
+ * Feedback tokens — communicate functional state to the user.
+ * They map to `theme.colors.{success, danger, warning, information}` at the
+ * structural level.
  */
 export interface SemanticColorFeedback {
     success: SemanticFeedbackTokens;
@@ -42,15 +42,15 @@ export interface SemanticColorFeedback {
     information: SemanticFeedbackTokens;
 }
 /**
- * Estado de um par interface.function (default `normal`). Reservado para
- * expansão futura (`hover`, `pressed`, `disabled`) sem breaking change.
+ * State of an interface.function pair (default `normal`). Reserved for future
+ * expansion (`hover`, `pressed`, `disabled`) without a breaking change.
  */
 export interface SemanticInterfaceFunctionStates {
     normal: SemanticBgPair;
 }
 /**
- * Tokens funcionais de interface — papéis de ação (primary, secondary,
- * tertiary). Mapeiam para `theme.colors.{primary, secondary, tertiary}`.
+ * Functional interface tokens — action roles (primary, secondary,
+ * tertiary). They map to `theme.colors.{primary, secondary, tertiary}`.
  */
 export interface SemanticColorInterfaceFunction {
     primary: SemanticInterfaceFunctionStates;
@@ -58,14 +58,14 @@ export interface SemanticColorInterfaceFunction {
     tertiary: SemanticInterfaceFunctionStates;
 }
 /**
- * Tokens de interface — agrega `function` e (futuramente) outros papéis.
+ * Interface tokens — aggregates `function` and (in the future) other roles.
  */
 export interface SemanticColorInterface {
     function: SemanticColorInterfaceFunction;
 }
 /**
- * Superfície + texto-sobre para uma cor de marca, no estado default.
- * Reservado `default` como string-key para permitir variantes futuras.
+ * Surface + text-on for a brand color, in the default state.
+ * `default` is reserved as a string key to allow future variants.
  */
 export interface SemanticBrandTokens {
     default: {
@@ -74,11 +74,11 @@ export interface SemanticBrandTokens {
     };
 }
 /**
- * Tokens de marca — identidade visual. Mapeiam para
- * `theme.colors.{main, opposite, complementary}` no estrutural.
+ * Brand tokens — visual identity. They map to
+ * `theme.colors.{main, opposite, complementary}` at the structural level.
  *
- * `first`/`second`/`third` reflete a nomenclatura Aplica DS (ordem de
- * apresentação) em vez da nomenclatura legada Apollion
+ * `first`/`second`/`third` reflects the Aplica DS nomenclature (presentation
+ * order) instead of Apollion's legacy nomenclature
  * (`main`/`opposite`/`complementary`).
  */
 export interface SemanticColorBrand {
@@ -87,7 +87,7 @@ export interface SemanticColorBrand {
     third: SemanticBrandTokens;
 }
 /**
- * Camada de cores da Semantic.
+ * Color layer of Semantic.
  */
 export interface SemanticColor {
     feedback: SemanticColorFeedback;
@@ -95,13 +95,13 @@ export interface SemanticColor {
     brand: SemanticColorBrand;
 }
 /**
- * Spacing pré-resolvido em string CSS (`'8px'`, `'1rem'`, etc.), gerado uma
- * única vez em `createSemantic()` a partir de `theme.spacing(alias)`.
+ * Spacing pre-resolved into a CSS string (`'8px'`, `'1rem'`, etc.), generated
+ * exactly once in `createSemantic()` from `theme.spacing(alias)`.
  *
- * Apollion usa as aliases legadas `zero..giant` no nível estrutural; a camada
- * Semantic preserva essas mesmas chaves para evitar tradução cognitiva
- * desnecessária (ADR-002 §5 deferiu adoção da nomenclatura Fibonacci de
- * Aplica para o ADR-003 / v4 epic).
+ * Apollion uses the legacy `zero..giant` aliases at the structural level; the
+ * Semantic layer preserves those same keys to avoid unnecessary cognitive
+ * translation (ADR-002 §5 deferred adopting Aplica's Fibonacci nomenclature
+ * to ADR-003 / the v4 epic).
  */
 export interface SemanticDimensionSpacing {
     zero: string;
@@ -115,14 +115,14 @@ export interface SemanticDimensionSpacing {
     giant: string;
 }
 /**
- * Camada de dimensão da Semantic. Atualmente cobre apenas spacing; tipografia
- * e elevation podem entrar em iterações futuras sem breaking change.
+ * Dimension layer of Semantic. Currently covers only spacing; typography and
+ * elevation may land in future iterations without a breaking change.
  */
 export interface SemanticDimension {
     spacing: SemanticDimensionSpacing;
 }
 /**
- * Forma completa da camada Semantic. Exposta em `theme.semantic` a partir do
+ * Complete shape of the Semantic layer. Exposed at `theme.semantic` as of
  * Apollion v3.1.0.
  */
 export interface SemanticLayer {