@apollion-dsi/core 5.2.0 → 5.4.0

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

@@ -1,51 +1,52 @@
 /**
- * Forma da entrada de bordas consumida por `createTheme`.
+ * Shape of the border input consumed by `createTheme`.
  *
- * Concentra os três eixos que descrevem uma borda — raio, largura e estilo —
- * em escalas nomeadas. Componentes referenciam essas chaves via
- * `theme.border.*` em vez de literais (`'8px'`, `'1px solid'`), o que garante
- * consistência visual e permite trocar a identidade visual em um único ponto.
+ * Concentrates the three axes that describe a border — radius, width, and
+ * style — into named scales. Components reference these keys via
+ * `theme.border.*` instead of literals (`'8px'`, `'1px solid'`), which
+ * guarantees visual consistency and allows swapping the visual identity at a
+ * single point.
  */
 export type BorderInput = {
     /**
-     * Escala de raio de borda. Vai de `straight` (cantos retos) até `circular`
-     * (100%, usado em avatares e badges).
+     * Border-radius scale. Goes from `straight` (square corners) up to
+     * `circular` (100%, used on avatars and badges).
      */
     borderRadius: {
-        /** Sem arredondamento. */
+        /** No rounding. */
         straight: string;
-        /** Suavização mínima para superfícies grandes. */
+        /** Minimal softening for large surfaces. */
         micro: string;
-        /** Raio pequeno — inputs e tags. */
+        /** Small radius — inputs and tags. */
         xs: string;
-        /** Raio médio-baixo — cards compactos. */
+        /** Medium-low radius — compact cards. */
         sm: string;
-        /** Raio médio — cards padrão. */
+        /** Medium radius — standard cards. */
         md: string;
-        /** Raio amplo — botões pill e CTAs. */
+        /** Wide radius — pill buttons and CTAs. */
         large: string;
-        /** `100%` — elementos perfeitamente redondos (avatares, badges). */
+        /** `100%` — perfectly round elements (avatars, badges). */
         circular: string;
     };
     /**
-     * Escala de espessura de borda. `none` permite "zerar" uma borda mantendo
-     * a chave consistente com o resto do design system.
+     * Border-width scale. `none` allows "zeroing" a border while keeping the
+     * key consistent with the rest of the design system.
      */
     borderWidth: {
         /** `0px`. */
         none: string;
-        /** Linha fina, padrão para divisórias. */
+        /** Thin line, default for dividers. */
         thin: string;
-        /** Espessura padrão de bordas de input/botão. */
+        /** Standard thickness for input/button borders. */
         regular: string;
-        /** Borda destacada usada em foco/estado ativo. */
+        /** Highlighted border used for focus/active state. */
         great: string;
-        /** Borda pesada, ênfase forte. */
+        /** Heavy border, strong emphasis. */
         bold: string;
     };
     /**
-     * Estilos suportados para `border-style`. Restringe a propriedade CSS aos
-     * valores aprovados pelo design system.
+     * Supported styles for `border-style`. Restricts the CSS property to the
+     * values approved by the design system.
      */
     borderStyle: {
         solid: string;
@@ -54,9 +55,9 @@ export type BorderInput = {
     };
 };
 /**
- * Atalho de seleção de tokens de borda usado por factories/props de
- * componentes. Permite que uma prop receba a chave do token (ex.: `'md'`,
- * `'thin'`) em vez do valor cru.
+ * Border-token selection shorthand used by component factories/props. Allows
+ * a prop to receive the token key (e.g. `'md'`, `'thin'`) instead of the raw
+ * value.
  */
 export type BorderThemeType = Partial<{
     [K in keyof BorderInput]: keyof BorderInput[K];

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

@@ -1,9 +1,9 @@
 /**
- * Barrel público do módulo de tema `Border`.
+ * Public barrel for the `Border` theme module.
  *
- * Reexporta a interface (`BorderInterface`, `BorderInput`) e os valores
- * padrão (`defaultInputBorder`) usados por `createTheme`. Outros arquivos
- * do projeto devem importar daqui — nunca de paths internos como
+ * Re-exports the interface (`BorderInterface`, `BorderInput`) and the
+ * default values (`defaultInputBorder`) used by `createTheme`. Other files
+ * in the project should import from here — never from internal paths like
  * `./Border.props`.
  */
 export * from './Border.interface';

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

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

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

@@ -16,47 +16,47 @@ export declare const HextoRgb: {
  * Rotate hue 180° in **OKLch** space (replaces `Color(c).rotate(180)` HSL
  * rotation from color@5).
  *
- * Spike `spike/culori-oklch-lerp-parity` documenta semantic shift: HSL hue
- * rotation é perceptualmente incorreto (e.g. blue→orange por HSL math, mas
- * perceptual complement de blue é yellow-green). OKLch hue rotation é a
- * correção perceptualmente accurate.
+ * Spike `spike/culori-oklch-lerp-parity` documents the semantic shift: HSL hue
+ * rotation is perceptually incorrect (e.g. blue→orange per HSL math, but the
+ * perceptual complement of blue is yellow-green). OKLch hue rotation is the
+ * perceptually accurate correction.
  *
- * **Token impact:** `defaultInputColors.opposite` em `Colors.props.ts:27`
- * usa esta função no module-load time. Valor do token muda em v4.0.0 vs
- * 3.x — design review obrigatório em S2 visual regression baseline
- * (categoria "Brand").
+ * **Token impact:** `defaultInputColors.opposite` in `Colors.props.ts:27`
+ * uses this function at module-load time. The token value changes in v4.0.0 vs
+ * 3.x — design review mandatory in the S2 visual regression baseline
+ * ("Brand" category).
  *
- * @see ADR-006 §6 S2 (semantic shift documentado)
- * @see ../vendors/Culori/README.md — "Prova de equivalência"
+ * @see ADR-006 §6 S2 (semantic shift documented)
+ * @see ../vendors/Culori/README.md — "Equivalence proof"
  */
 export declare function getOppositeColor(color: AcceptColorType): string;
-/** Piso de contraste WCAG AA para texto normal. */
+/** WCAG AA contrast floor for normal text. */
 export declare const MIN_CONTRAST_AA = 4.5;
 /**
- * Ajusta a luminância (OKLch L) de `color` até atingir um piso de contraste WCAG
- * contra `background`, **preservando hue e croma**.
+ * Adjusts the lightness (OKLch L) of `color` until it reaches a WCAG contrast
+ * floor against `background`, **preserving hue and chroma**.
  *
- * Diferente de `getContrastColor` (que escolhe preto/branco): é a cor de
- * **link/acento legível** — mantém a identidade (ex.: vermelho de marca) mas
- * garante leitura sobre fundos claros E escuros (dark-mode-safe). A direção do
- * ajuste vai para o **endpoint de maior contraste** (branco vs preto contra o
- * fundo) — robusto inclusive para fundos de luminância média, onde um threshold
- * simples erraria o lado. Itera em passos de L até passar `minRatio` ou clampar
- * em [0,1].
+ * Unlike `getContrastColor` (which picks black/white): this is the **readable
+ * link/accent color** — it keeps the identity (e.g. brand red) while
+ * guaranteeing readability on light AND dark backgrounds (dark-mode-safe). The
+ * adjustment moves toward the **endpoint of higher contrast** (white vs black
+ * against the background) — robust even for mid-luminance backgrounds, where a
+ * simple threshold would pick the wrong side. Iterates in L steps until passing
+ * `minRatio` or clamping at [0,1].
  *
- * **Memoizado desde a F6 do pente fino:** o `memoize` do repo chaveava só no 1º
- * argumento, e por isso esta função ficava de fora — o resultado depende
- * também de `background`, então cachear daria contaminação entre light/dark.
- * O memoize passou a chavear por TODOS os argumentos, então o impedimento
- * caiu. Importa: é o caminho quente do sistema de cor, com até 25 iterações
- * de `parse`+`formatHex`+`wcagContrast` por elemento renderizado.
+ * **Memoized since fine-combing pass F6:** the repo's `memoize` used to key only
+ * on the 1st argument, which is why this function was left out — the result
+ * also depends on `background`, so caching would cause contamination between
+ * light/dark. The memoize now keys on ALL arguments, so the blocker is gone.
+ * This matters: it is the hot path of the color system, with up to 25
+ * iterations of `parse`+`formatHex`+`wcagContrast` per rendered element.
  *
- * @param color - Cor de acento (string | ColorPalleteInterface).
- * @param background - Fundo sobre o qual a cor precisa ser legível.
- * @param minRatio - Piso de contraste WCAG (default 4.5 = AA texto normal).
- * @returns Hex com L ajustado; `color` original se já passa o piso (ou parse falhar).
+ * @param color - Accent color (string | ColorPalleteInterface).
+ * @param background - Background the color must be readable against.
+ * @param minRatio - WCAG contrast floor (default 4.5 = AA normal text).
+ * @returns Hex with adjusted L; the original `color` if it already passes the floor (or fails to parse).
  *
- * @see getContrastColor (escolha preto/branco para texto-sobre-cor sólida)
+ * @see getContrastColor (black/white choice for text-over-solid-color)
  * @see ../../docs/adr/ADR-010-contrast-derived-txton-dark-mode-stable.md §12
  */
 export declare const readableColor: {
@@ -69,32 +69,31 @@ export declare const readableColor: {
  */
 export declare function getColor(color: AcceptColorType, prop?: keyof ColorPalleteInterface): string;
 /**
- * Escolhe uma cor de **texto legível sobre a cor sólida `color`**, garantindo
- * contraste WCAG AA (>= 4.5) em fundos de qualquer luminância.
+ * Picks a **readable text color over the solid color `color`**, guaranteeing
+ * WCAG AA contrast (>= 4.5) on backgrounds of any luminance.
  *
- * **Correção do bug de tom médio (ADR-010 §12; feedback brasil_2030):** a versão
- * anterior usava um threshold fixo de luminância (`< 0.45`) + um único candidato
- * escurecido e, se ele não passasse, caía em branco — elegendo branco a ~3.6:1
- * sobre fundos médios (ex.: `#708B97`), reprovando AA. Agora escolhe, entre o
- * texto escuro tonalizado e o claro, o de **maior contraste**; se nem o vencedor
- * passar AA, escala para o endpoint puro (`#000`/`#fff`) de maior contraste — que
- * sempre rende >= ~4.5 contra qualquer fundo. Mesma direção-por-contraste que
- * `readableColor` aplica, compartilhando `contrastRatio`.
+ * **Mid-tone bug fix (ADR-010 §12; brasil_2030 feedback):** the previous
+ * version used a fixed luminance threshold (`< 0.45`) + a single darkened
+ * candidate and, if it didn't pass, fell back to white — electing white at ~3.6:1
+ * over mid backgrounds (e.g. `#708B97`), failing AA. It now picks, between the
+ * tinted dark text and the light one, the one with **higher contrast**; if even
+ * the winner fails AA, it escalates to the pure endpoint (`#000`/`#fff`) of
+ * higher contrast — which always yields >= ~4.5 against any background. Same
+ * direction-by-contrast that `readableColor` applies, sharing `contrastRatio`.
  *
  * **S6 migration:** `color@5` → culori `wcagContrast` (parity spike/culori-wcag-parity,
- * 262 medições). `Color(c).darken(0.6)` → OKLch lerp (`mixOklch` rumo a `#000`).
+ * 262 measurements). `Color(c).darken(0.6)` → OKLch lerp (`mixOklch` toward `#000`).
  *
- * **Memoização:** chaveada por **todos** os argumentos desde a F6 do pente
- * fino. Antes só `color` entrava na chave, então duas chamadas com o mesmo
- * `color` e `colorbase` diferentes devolviam o resultado da primeira —
- * contaminação silenciosa. Nenhum caller do core passa `colorbase` hoje, o que
- * mantinha o defeito latente; o `clearCache()` manual que este bloco recomendava
- * deixou de ser necessário.
+ * **Memoization:** keyed by **all** arguments since fine-combing pass F6.
+ * Previously only `color` entered the key, so two calls with the same `color`
+ * and different `colorbase` returned the first result — silent contamination.
+ * No core caller passes `colorbase` today, which kept the defect latent; the
+ * manual `clearCache()` this block used to recommend is no longer needed.
  *
- * @param color - Cor de fundo sólida (string | `ColorPalleteInterface`).
- * @param colorbase - Override do candidato de texto claro (default `#FFFFFF`).
- * @returns Hex de texto legível; a própria `color` se ela não parsear (guard).
- * @see readableColor (acento legível preservando hue/croma)
+ * @param color - Solid background color (string | `ColorPalleteInterface`).
+ * @param colorbase - Override for the light text candidate (default `#FFFFFF`).
+ * @returns Readable text hex; `color` itself if it fails to parse (guard).
+ * @see readableColor (readable accent preserving hue/chroma)
  * @see ADR-006 §6 S6 · ADR-010 §12
  */
 export declare const getContrastColor: {
@@ -102,75 +101,75 @@ export declare const getContrastColor: {
     clearCache(): void;
 };
 /**
- * Paletas nomeadas cujo `base` é usado como **texto** por consumidores e,
- * portanto, ganham ink legível na camada de texto (plano contraste G2).
+ * Named palettes whose `base` is used as **text** by consumers and which
+ * therefore get readable ink in the text layer (contrast plan G2).
  */
 export declare const READABLE_TEXT_PALETTES: readonly ["main", "opposite", "complementary", "primary", "secondary", "tertiary", "success", "danger", "warning", "information"];
 export type ReadableTextPaletteType = (typeof READABLE_TEXT_PALETTES)[number];
 /**
- * Índices da rampa neutra classificados como **texto** (≥ 120 — o lado
- * escuro da rampa, onde vivem `dt`/`figcaption`/labels pintados pelo DS).
- * Índices baixos seguem fill/borda. Ver plano contraste G4.
+ * Neutral ramp indices classified as **text** (≥ 120 — the dark side of the
+ * ramp, home of `dt`/`figcaption`/labels painted by the DS).
+ * Low indices remain fill/border. See contrast plan G4.
  */
 export declare const NEUTRAL_TEXT_INDICES: readonly [120, 130, 140, 150, 160, 170, 180];
 export type NeutralTextIndexType = (typeof NEUTRAL_TEXT_INDICES)[number];
-/** Opções da camada de texto legível ({@link createReadableTextLayer}). */
+/** Options for the readable text layer ({@link createReadableTextLayer}). */
 export interface ReadableTextLayerOptions {
     /**
-     * Superfície-alvo do contraste. Default: `colors.neutral['10']` — o card
-     * claro, pior caso real de leitura (mirar `#FFF` deixaria a um fio do piso).
-     * Num tema escuro, passe a superfície de card desse tema.
+     * Target surface for contrast. Default: `colors.neutral['10']` — the light
+     * card, the real worst case for reading (targeting `#FFF` would leave it a
+     * hair from the floor). In a dark theme, pass that theme's card surface.
      */
     surface?: AcceptColorType;
-    /** Piso de contraste WCAG. Default 4.5 (AA texto normal). */
+    /** WCAG contrast floor. Default 4.5 (AA normal text). */
     minRatio?: number;
 }
-/** Resultado de {@link createReadableTextLayer}: hex legível por token. */
+/** Result of {@link createReadableTextLayer}: readable hex per token. */
 export interface ReadableTextLayer {
-    /** Ink legível por paleta nomeada (`main`, `primary`, …), derivado do `base`. */
+    /** Readable ink per named palette (`main`, `primary`, …), derived from `base`. */
     palettes: Record<ReadableTextPaletteType, string>;
-    /** Ink legível por índice alto (texto) da rampa neutra. */
+    /** Readable ink per high (text) index of the neutral ramp. */
     neutral: Record<NeutralTextIndexType, string>;
 }
 /**
- * Camada generativa de **texto legível por tema** (plano contraste G2;
- * origem: consumidor brasil_2030, handoff `2026-07-29-contraste-wcag`).
+ * Generative **per-theme readable text** layer (contrast plan G2;
+ * origin: brasil_2030 consumer, handoff `2026-07-29-contraste-wcag`).
  *
- * Para cada cor de marca usada como ink e para o lado texto da rampa neutra,
- * deriva via {@link readableColor} um hex que passa o piso WCAG contra a
- * superfície do tema — preservando hue/croma (identidade da marca sobrevive;
- * só a luminância move). O fill segue vibrante: esta camada é só para texto.
+ * For each brand color used as ink and for the text side of the neutral ramp,
+ * derives via {@link readableColor} a hex that passes the WCAG floor against
+ * the theme's surface — preserving hue/chroma (brand identity survives; only
+ * the lightness moves). Fill stays vibrant: this layer is text-only.
  *
- * Chame uma vez **por tema** (light/dark são paletas distintas, cada uma com
- * sua superfície) e emita o resultado onde o consumidor precisar — CSS vars
- * num SSG, tokens estáticos, etc. Substitui as reimplementações locais
- * (`themeCssVars.ts` + helpers `txt()`/`ink()` no consumidor).
+ * Call once **per theme** (light/dark are distinct palettes, each with its own
+ * surface) and emit the result wherever the consumer needs it — CSS vars in an
+ * SSG, static tokens, etc. Replaces the local reimplementations
+ * (`themeCssVars.ts` + `txt()`/`ink()` helpers in the consumer).
  *
  * @example
  * ```ts
  * const light = createReadableTextLayer(lightTheme.colors);
  * const dark = createReadableTextLayer(darkTheme.colors, { surface: darkTheme.colors.baseLight });
- * // light.palettes.secondary → ink AA sobre o card claro
- * // dark.neutral[140] → cinza de texto clareado p/ o tema escuro
+ * // light.palettes.secondary → AA ink over the light card
+ * // dark.neutral[140] → text gray lightened for the dark theme
  * ```
  *
- * @param colors - Paleta estrutural do tema (`theme.colors`).
- * @param options - Superfície-alvo e piso de contraste.
- * @returns Mapa `palettes` + `neutral` com hex legíveis.
+ * @param colors - Structural palette of the theme (`theme.colors`).
+ * @param options - Target surface and contrast floor.
+ * @returns `palettes` + `neutral` map with readable hex values.
  * @see readableColor · ADR-010 §12 · docs/plans/plano-contraste-nativo-brasil2030.md (G2)
  */
 export declare function createReadableTextLayer(colors: ThemeColorsType, { surface, minRatio }?: ReadableTextLayerOptions): ReadableTextLayer;
 /**
- * Índices da rampa {@link NeutralColorsType} usados em `:disabled`.
+ * {@link NeutralColorsType} ramp indices used for `:disabled`.
  *
- * Sem token derivado: o disabled **é** um ponto da escala Neutral, escolhido
- * pelo mode da superfície (`isDarkSurface` sobre `baseLight`).
+ * No derived token: disabled **is** a point on the Neutral scale, chosen by
+ * the surface mode (`isDarkSurface` over `baseLight`).
  *
- * - **fill** — light `10` (muted no card claro); dark `170` (polaridade
- *   invertida — não colapsa no `deepLight` invertido / bug Fanático).
- * - **color** — candidatos na mesma rampa, primeiro que passa AA (≥ 4.5)
- *   contra o fill. Ordem preferida documentada abaixo; walk cobre temas
- *   gray-anchored onde o par nominal (`140` / `80`) falha.
+ * - **fill** — light `10` (muted on the light card); dark `170` (inverted
+ *   polarity — does not collapse into the inverted `deepLight` / Fanático bug).
+ * - **color** — candidates on the same ramp, first one that passes AA (≥ 4.5)
+ *   against the fill. Preferred order documented below; the walk covers
+ *   gray-anchored themes where the nominal pair (`140` / `80`) fails.
  *
  * @see resolveDisabledNeutral · APOLLION-DISABLED-CONTRAST
  */
@@ -185,12 +184,12 @@ export declare const DISABLED_NEUTRAL_INDICES: {
     };
 };
 /**
- * Índices estruturais mode-aware para o fill **muted** (rail / chip / soft bg).
+ * Mode-aware structural indices for the **muted** fill (rail / chip / soft bg).
  *
- * Light mantém `neutral.10` histórico; dark inverte polaridade (`170`) para
- * não colapsar no `deepLight` invertido. Bordas e placeholders continuam na
- * rampa Neutral direta (`neutral.40` / `neutral.70`) — Apollion não inventa
- * canal `border`/`placeholder`.
+ * Light keeps the historical `neutral.10`; dark inverts polarity (`170`) so it
+ * does not collapse into the inverted `deepLight`. Borders and placeholders
+ * stay on the direct Neutral ramp (`neutral.40` / `neutral.70`) — Apollion does
+ * not invent a `border`/`placeholder` channel.
  *
  * @see resolveStructuralNeutrals · APOLLION-STRUCTURAL-NEUTRAL
  */
@@ -203,73 +202,73 @@ export declare const STRUCTURAL_NEUTRAL_INDICES: {
     };
 };
 /**
- * Par fill+color do `:disabled` lido **só** da rampa Neutral do tema.
+ * The `:disabled` fill+color pair read **only** from the theme's Neutral ramp.
  *
- * Montado uma vez em {@link createColors} → `theme.colors.disabled`.
- * Styled-components consomem o par; não recalculam por render.
+ * Assembled once in {@link createColors} → `theme.colors.disabled`.
+ * Styled-components consume the pair; they do not recompute per render.
  */
 export declare function resolveDisabledNeutral(colors: ThemeColorsType): {
     fill: string;
     color: string;
 };
 /**
- * Slot `muted` — hex da rampa Neutral mode-aware.
+ * `muted` slot — mode-aware hex from the Neutral ramp.
  *
- * Montado em {@link createColors} → `theme.colors.muted`. Substituí
- * hardcodes de fill soft (`neutral.10`) que colapsavam no dark invertido.
+ * Assembled in {@link createColors} → `theme.colors.muted`. Replaces soft-fill
+ * hardcodes (`neutral.10`) that collapsed in the inverted dark.
  */
 export declare function resolveStructuralNeutrals(colors: ThemeColorsType): {
     muted: string;
 };
 /**
- * Piso perceptual entre `base` e um estado de interação (`action`/`active`):
- * razão de luminância WCAG mínima para o shift ser perceptível (ADR-012).
+ * Perceptual state floor between `base` and an interaction state (`action`/`active`):
+ * minimum WCAG luminance ratio for the shift to be perceptible (ADR-012).
  */
 export declare const MIN_STATE_CONTRAST = 1.3;
 /**
- * ΔL OKLch just-noticeable-difference (~0.05 — mesmo threshold documentado no
- * spike OKLch). Critério alternativo ao {@link MIN_STATE_CONTRAST}: perto do
- * preto a razão WCAG satura (o `+0.05` da fórmula domina) e um shift
- * claramente visível mede < 1.3x — o ΔL perceptualmente uniforme não satura.
+ * OKLch ΔL just-noticeable-difference (~0.05 — same threshold documented in
+ * the OKLch spike). Alternative criterion to {@link MIN_STATE_CONTRAST}: near
+ * black the WCAG ratio saturates (the formula's `+0.05` dominates) and a
+ * clearly visible shift measures < 1.3x — the perceptually uniform ΔL does not saturate.
  */
 export declare const STATE_DELTA_L_JND = 0.05;
 /**
- * Deriva a paleta de 5 stops (`ColorPalleteInterface`) de um seed via **OKLch
- * perceptual lerp**, com **piso perceptual mode-aware** nos estados de
- * interação (`action`/`active`) — ADR-012.
+ * Derives the 5-stop palette (`ColorPalleteInterface`) from a seed via **OKLch
+ * perceptual lerp**, with a **mode-aware perceptual state floor** on the
+ * interaction states (`action`/`active`) — ADR-012.
  *
- * Contrato:
- * - A derivação histórica (lerp rumo a `deepDark`/`deepLight`) é o candidato
- *   default. Se ela já é perceptível ({@link isPerceptibleState} — caso comum
- *   dos temas light), o output é **byte-idêntico** ao anterior (zero churn de
- *   baseline visual).
- * - Se o candidato colapsa (ex.: tema escuro com `deep*` ancorado em cinzas —
- *   feedback brasil_2030, hover de CTA a 1.02x), o estado é re-derivado
- *   ajustando só o L OKLch do `base` (hue/croma preservados) na direção do
- *   mode da superfície ({@link isDarkSurface} sobre `colors.baseLight`) até o
- *   piso {@link MIN_STATE_CONTRAST}.
- * - `dark`/`light` seguem a derivação histórica sempre (são tints de rampa,
- *   não estados de interação).
- * - Escape hatch: um slot-objeto ({@link ColorPalleteOverrideInterface}) tem
- *   seus steps fornecidos respeitados **verbatim** — sem piso, sem derivação.
+ * Contract:
+ * - The historical derivation (lerp toward `deepDark`/`deepLight`) is the
+ *   default candidate. If it is already perceptible ({@link isPerceptibleState}
+ *   — the common case for light themes), the output is **byte-identical** to
+ *   the previous one (zero visual-baseline churn).
+ * - If the candidate collapses (e.g. dark theme with `deep*` anchored in grays
+ *   — brasil_2030 feedback, CTA hover at 1.02x), the state is re-derived by
+ *   adjusting only the OKLch L of `base` (hue/chroma preserved) in the
+ *   direction of the surface mode ({@link isDarkSurface} over
+ *   `colors.baseLight`) until the {@link MIN_STATE_CONTRAST} floor.
+ * - `dark`/`light` always follow the historical derivation (they are ramp
+ *   tints, not interaction states).
+ * - Escape hatch: a slot object ({@link ColorPalleteOverrideInterface}) has its
+ *   supplied steps respected **verbatim** — no floor, no derivation.
  */
 export declare function mountSingleColor(color: AcceptColorType | ColorPalleteOverrideInterface, colors: ColorsInput): ColorPalleteInterface;
 /**
  * 12-step greyscale ramp via **OKLch perceptual lerp**.
  *
- * Spike `spike/culori-oklch-lerp-parity` confirmou que ramp OKLAB L
- * std-dev é **19× mais uniforme** vs color@5 RGB lerp. Brand designer
- * typing "50% gray" agora obtém perceptualmente 50% (`#636363`), não
+ * Spike `spike/culori-oklch-lerp-parity` confirmed the ramp's OKLAB L
+ * std-dev is **19× more uniform** vs color@5 RGB lerp. A brand designer
+ * typing "50% gray" now gets perceptual 50% (`#636363`), not
  * sRGB-arithmetic 50% (`#808080`).
  */
 export declare function mountGreyscaleColors(colors: ColorsInput): Record<GrayscaleColorsType, string>;
 /**
- * 20-step neutral ramp anchored em `primary.mix(darker, 0.5)` (n170) via
+ * 20-step neutral ramp anchored at `primary.mix(darker, 0.5)` (n170) via
  * **OKLch perceptual lerp**.
  *
- * Spike confirmou marginal uniformity regression (+17% std-dev) em OKLAB L
- * — abaixo do just-noticeable difference threshold (~0.05). Diff visual
- * documentado como `expected-perceptual-gain` (44/68 deltas) ou
+ * The spike confirmed a marginal uniformity regression (+17% std-dev) in OKLAB L
+ * — below the just-noticeable difference threshold (~0.05). Visual diff
+ * documented as `expected-perceptual-gain` (44/68 deltas) or
  * `acceptable-no-change` (24/68).
  */
 export declare function mountNeutralColors(colors: ColorsInput): Record<NeutralColorsType, string>;

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

@@ -4,21 +4,32 @@ export interface ColorPalleteInterface {
     action: string;
     light: string;
     active: string;
+    /**
+     * Readable ink over the `light` tonal surface (APOLLION-CONTRAST-GUARANTEE):
+     * `readableColor(action, light, 4.5)` — the accent with its L adjusted until
+     * it passes WCAG AA, preserving hue/chroma. It is the semantic pair of the
+     * tonal chip (`{ bg: light, ink: onLight }`), so that no component pairs raw
+     * `light`+`action` (which fails AA on high-luminance seeds). When `action`
+     * already passes over `light` (e.g. danger), it comes out byte-identical to `action`.
+     *
+     * @see readableColor · ADR-018 · design-system-backlog.md#engine-guaranteed-contrast
+     */
+    onLight: string;
 }
 export type AcceptColorType = ColorPalleteInterface | string;
 /**
- * Escape hatch por slot (estados de interação mode-aware — ADR-012): um slot
- * de {@link ColorsInput} aceita, além do seed string, uma paleta parcial
- * explícita. `base` é obrigatório; qualquer step fornecido (`action`, `active`,
- * `dark`, `light`) é respeitado **verbatim** — sem piso perceptual, sem
- * derivação. Steps ausentes seguem a derivação padrão do engine.
+ * Per-slot escape hatch (mode-aware interaction states — ADR-012): a
+ * {@link ColorsInput} slot accepts, besides the seed string, an explicit
+ * partial palette. `base` is required; any supplied step (`action`, `active`,
+ * `dark`, `light`) is respected **verbatim** — no perceptual state floor, no
+ * derivation. Missing steps follow the engine's standard derivation.
  */
 export interface ColorPalleteOverrideInterface extends Partial<Omit<ColorPalleteInterface, 'base'>> {
     base: string;
 }
 /**
- * Entrada aceita por slot de cor de {@link ColorsInput}: seed string (caminho
- * 100% — o engine deriva os 4 steps) ou override parcial por slot
+ * Input accepted per color slot of {@link ColorsInput}: a seed string (the
+ * 100% path — the engine derives the 4 steps) or a per-slot partial override
  * ({@link ColorPalleteOverrideInterface}).
  */
 export type ColorSeedInputType = string | ColorPalleteOverrideInterface;
@@ -60,7 +71,7 @@ type ColorWithVariantType<C extends VariantColorsType = VariantColorsType, V ext
 type GrayscaleColorType<S extends GrayscaleColorsType = GrayscaleColorsType> = `grayscale.${S}`;
 type NeutralColorType<S extends NeutralColorsType = NeutralColorsType> = `neutral.${S}`;
 export type BgColorsTypes = ColorWithVariantType | GrayscaleColorType | NeutralColorType | BrandColorsType | ContrastColorsType
-/** Fill soft mode-aware montado em `createColors`. */
+/** Mode-aware soft fill assembled in `createColors`. */
  | 'muted';
 export type ColorsType = BgColorsTypes | null;
 export type ThemeColorsType<T = ColorPalleteInterface> = BrandColorsInterface<T> & MainColorsInterface<T> & ActionColorsInterface<T> & ContrastColorsInterface & DeepColorsInterface & {
@@ -68,13 +79,13 @@ export type ThemeColorsType<T = ColorPalleteInterface> = BrandColorsInterface<T>
     grayscale?: Record<GrayscaleColorsType, string>;
 };
 /**
- * Par fill+color do `:disabled` — hex da rampa Neutral, montado em
- * {@link createColors} via {@link resolveDisabledNeutral}.
+ * The `:disabled` fill+color pair — hex values from the Neutral ramp,
+ * assembled in {@link createColors} via {@link resolveDisabledNeutral}.
  */
 export interface DisabledColorsInterface {
-    /** Fill muted (`neutral.10` light / `neutral.170` dark). */
+    /** Muted fill (`neutral.10` light / `neutral.170` dark). */
     fill: string;
-    /** Texto/chrome sobre o fill (candidato Neutral AA). */
+    /** Text/chrome over the fill (AA Neutral candidate). */
     color: string;
 }
 export type ColorsThemeInterface = ThemeColorsType & {
@@ -82,14 +93,14 @@ export type ColorsThemeInterface = ThemeColorsType & {
     getColor?: (color: AcceptColorType, prop?: keyof ColorPalleteInterface) => string;
     getContrastColor?: (color: AcceptColorType, colorbase?: ColorsType) => string;
     /**
-     * `:disabled` mode-aware — pontos da rampa Neutral resolvidos na montagem
-     * do tema (não um token derivado tipo `txtOn`).
+     * Mode-aware `:disabled` — points on the Neutral ramp resolved at theme
+     * assembly (not a derived token like `txtOn`).
      */
     disabled: DisabledColorsInterface;
     /**
-     * Fill soft / rail / multi-chip bg — `neutral.10` light / `neutral.170` dark.
-     * Também resolvível via `theme.colors('muted')` nas factories.
-     * Bordas/placeholders: rampa Neutral direta (`neutral.40` / `neutral.70`).
+     * Soft fill / rail / multi-chip bg — `neutral.10` light / `neutral.170` dark.
+     * Also resolvable via `theme.colors('muted')` in the factories.
+     * Borders/placeholders: direct Neutral ramp (`neutral.40` / `neutral.70`).
      */
     muted: string;
 };

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