@apollion-dsi/core 3.0.0 → 4.1.0

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

@@ -1 +1 @@
-import{a,b,c,d,e,f,g,h,i,j,k,l}from"../../chunks/chunk-QUHHEZMP.esm.js";import"../../chunks/chunk-44EW3LMK.esm.js";import"../../chunks/chunk-V5AWVNU6.esm.js";import"../../chunks/chunk-GZONWSRB.esm.js";export{a as HextoRgb,l as createColors,k as defaultInputColors,c as getColor,d as getContrastColor,b as getOppositeColor,i as mountActionColors,h as mountBaseColors,f as mountGreyscaleColors,j as mountMainColors,g as mountNeutralColors,e as mountSingleColor};
+import{a,b,c,d,e,f,g,h,i,j,k,l}from"../../chunks/chunk-4RPR6CZT.esm.js";import"../../chunks/chunk-7WVLGVVA.esm.js";import"../../chunks/chunk-44EW3LMK.esm.js";import"../../chunks/chunk-V5AWVNU6.esm.js";import"../../chunks/chunk-GZONWSRB.esm.js";export{a as HextoRgb,l as createColors,k as defaultInputColors,c as getColor,d as getContrastColor,b as getOppositeColor,i as mountActionColors,h as mountBaseColors,f as mountGreyscaleColors,j as mountMainColors,g as mountNeutralColors,e as mountSingleColor};

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

@@ -1 +1 @@
-import{a}from"../../chunks/chunk-G3IXCOJI.esm.js";import"../../chunks/chunk-QUHHEZMP.esm.js";import"../../chunks/chunk-44EW3LMK.esm.js";import"../../chunks/chunk-V5AWVNU6.esm.js";import"../../chunks/chunk-GZONWSRB.esm.js";export{a as createDeepTheme};
+import{a}from"../../chunks/chunk-A4BXGJYW.esm.js";import"../../chunks/chunk-4RPR6CZT.esm.js";import"../../chunks/chunk-7WVLGVVA.esm.js";import"../../chunks/chunk-44EW3LMK.esm.js";import"../../chunks/chunk-V5AWVNU6.esm.js";import"../../chunks/chunk-GZONWSRB.esm.js";export{a as createDeepTheme};

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

@@ -1 +1 @@
-import{a,b}from"../../chunks/chunk-Q3FXXXUX.esm.js";import"../../chunks/chunk-GZONWSRB.esm.js";export{b as createDeth,a as levelValues};
+import{a,b}from"../../chunks/chunk-IT4J7I6H.esm.js";import"../../chunks/chunk-7WVLGVVA.esm.js";import"../../chunks/chunk-GZONWSRB.esm.js";export{b as createDeth,a as levelValues};

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

@@ -0,0 +1,24 @@
+/**
+ * Density axis introduced in `@apollion-dsi/core` v4 (ADR-006 E2).
+ *
+ * **Naming disambiguation:** this `Dimension` type controls the **density**
+ * (spacing scale multiplier) of the theme — orthogonal to `SemanticDimension`
+ * (the spacing-aliases layer at `theme.semantic.dimension`). They coexist:
+ *
+ * - `Dimension` (this file)  → which multiplier the spacing scale uses.
+ * - `SemanticDimension`      → semantic aliases (xs/sm/md/large/xl/xxl) derived
+ *                              from the active `Dimension` multiplier.
+ *
+ * Both contribute to `theme.spacing(...)` output. Consumer changes density via
+ * `<ApollionProvider dimension="compact">` prop (Q-G3 — prop-only API, no
+ * getter, no hook).
+ *
+ * Calibration values are CHUTE in S3 — Q2 of ADR-006 §9 (Open Questions) flags
+ * that empirical calibration is needed (target: `compact` = 30 table rows in
+ * 1080p without scroll). Final values land in PRD-002 or a follow-up PR.
+ *
+ * @see ../../docs/adr/ADR-006-v4-oklch-dimension-token-split.md §6 S3
+ * @see ../../docs/prd/PRD-002-v4-epic-execution.md §S3
+ * @see ./Dimension.props.ts
+ */
+export type Dimension = 'compact' | 'normal' | 'spacious';

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

@@ -0,0 +1,36 @@
+import { Dimension } from './Dimension.interface';
+/**
+ * Spacing multipliers per density dimension.
+ *
+ * **Calibration (CHUTE — Q2 ADR-006):**
+ * - `compact` = 0.20 → tighter spacing for data-dense UIs (dashboards, tables)
+ * - `normal`  = 0.25 → v3.x default (preserves existing visual)
+ * - `spacious` = 0.32 → looser spacing for marketing/touch-first surfaces
+ *
+ * Empirical calibration target: `compact` produces 30 table rows in 1080p
+ * without scroll. Final values may shift in a follow-up PR; the public
+ * surface (the multipliers object + indexed access) is stable.
+ *
+ * Default `normal` preserves v3.x `multiplier: 0.25` behavior — consumer
+ * unaware of E2 inherits identical spacing.
+ *
+ * @see ../../docs/adr/ADR-006-v4-oklch-dimension-token-split.md §6 S3 (Q2 calibration)
+ */
+export declare const DIMENSION_MULTIPLIERS: Readonly<Record<Dimension, number>>;
+/**
+ * Default dimension when consumer does not pass `<ApollionProvider dimension>`.
+ *
+ * Preserves v3.x behavior (multiplier 0.25) — silent migration for consumer
+ * that doesn't opt into E2 axis.
+ */
+export declare const DEFAULT_DIMENSION: Dimension;
+/**
+ * Resolve the spacing multiplier for a given dimension.
+ *
+ * Used by `Spacing.props.ts#createSpacing` when consumer activates the
+ * density axis via `<ApollionProvider dimension="compact|normal|spacious">`.
+ *
+ * @param dimension - density profile (see {@link Dimension})
+ * @returns rem multiplier (0.20 / 0.25 / 0.32)
+ */
+export declare function getMultiplierForDimension(dimension: Dimension): number;

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

@@ -0,0 +1,10 @@
+/**
+ * Barrel público do módulo `Dimension` (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.
+ *
+ * @see ./Dimension.interface.ts (naming disambiguation completo)
+ */
+export * from './Dimension.interface';
+export * from './Dimension.props';

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

@@ -0,0 +1 @@
+import{a,b,c}from"../../chunks/chunk-JOKVE3IX.esm.js";import"../../chunks/chunk-GZONWSRB.esm.js";export{b as DEFAULT_DIMENSION,a as DIMENSION_MULTIPLIERS,c as getMultiplierForDimension};

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

@@ -0,0 +1,32 @@
+import type { FoundationLayer } from './Foundation.interface';
+import type { SemanticLayer } from '../Semantic/Semantic.interface';
+/**
+ * Resolve a camada Foundation a partir da camada Semantic.
+ *
+ * **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).
+ *
+ * Foundation é puramente derivativa de Semantic — toda alteração de cor/
+ * espaçamento propaga via Semantic. Mapping segue ADR-002 §3 + §5.
+ *
+ * @param semantic - Camada Semantic já resolvida (vinda de `createSemantic`).
+ * @returns Camada Foundation completa, pronta pra ser plugada em
+ *          `theme.foundation`.
+ *
+ * @example
+ * ```ts
+ * // Em código de produto (DEX/Jovian/Fanaticofc):
+ * const StyledCTA = styled.button`
+ *   background: ${({ theme }) => theme.foundation.bg.primary};
+ *   color:      ${({ theme }) => theme.foundation.text.onPrimary};
+ *   padding:    ${({ theme }) => theme.foundation.spacing.md};
+ * `;
+ * ```
+ *
+ * @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)
+ */
+export declare function createFoundation(semantic: SemanticLayer): FoundationLayer;

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

@@ -0,0 +1,84 @@
+/**
+ * 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.
+ *
+ * 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`.
+ *
+ * Quem deve usar o quê (ADR-002 §5):
+ * - Produto      → Foundation (esta camada)
+ * - Componentes  → 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)
+ */
+/**
+ * Aliases curtos para cores de fundo. Mapeiam para Semantic da seguinte
+ * forma:
+ * - `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`
+ * - `bg.success`   ← `semantic.color.feedback.success.bg`
+ * - `bg.danger`    ← `semantic.color.feedback.danger.bg`
+ * - `bg.warning`   ← `semantic.color.feedback.warning.bg`
+ * - `bg.info`      ← `semantic.color.feedback.information.bg`
+ */
+export interface FoundationBg {
+    primary: string;
+    secondary: string;
+    tertiary: string;
+    success: string;
+    danger: string;
+    warning: string;
+    info: string;
+}
+/**
+ * Aliases curtos para cores de texto "sobre" um fundo Foundation. O sufixo
+ * (`onPrimary`) indica explicitamente o par de bg.
+ *
+ * Garantia de contraste WCAG ≥ AA é responsabilidade da camada Semantic
+ * (que escolhe `baseLight` ou `baseDark` para cada `txtOn`).
+ */
+export interface FoundationText {
+    onPrimary: string;
+    onSecondary: string;
+    onTertiary: string;
+    onSuccess: string;
+    onDanger: string;
+    onWarning: string;
+    onInfo: 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).
+ *
+ * Tradução para spacing aliases legadas de Apollion:
+ * - `xs`  ← `semantic.dimension.spacing.xs`
+ * - `sm`  ← `semantic.dimension.spacing.small`
+ * - `md`  ← `semantic.dimension.spacing.medium`
+ * - `lg`  ← `semantic.dimension.spacing.large`
+ * - `xl`  ← `semantic.dimension.spacing.xl`
+ * - `xxl` ← `semantic.dimension.spacing.xxl`
+ */
+export interface FoundationSpacing {
+    xs: string;
+    sm: string;
+    md: string;
+    lg: string;
+    xl: string;
+    xxl: string;
+}
+/**
+ * Forma completa da camada Foundation. Exposta em `theme.foundation` a partir
+ * do Apollion v3.2.0 (ADR-002 Slice 3).
+ */
+export interface FoundationLayer {
+    bg: FoundationBg;
+    text: FoundationText;
+    spacing: FoundationSpacing;
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Camada Foundation — aliases curtos e ergonômicos sobre Semantic.
+ *
+ * Exposta em `theme.foundation` a partir de `@apollion-dsi/core` 3.2.0.
+ *
+ * Subpath import (preferido):
+ * ```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';`.
+ *
+ * @see ../../../docs/adr/ADR-002-layered-theme-aliases-and-surface.md
+ */
+export type { FoundationBg, FoundationLayer, FoundationSpacing, FoundationText } from './Foundation.interface';
+export { createFoundation } from './Foundation.helpers';

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

@@ -0,0 +1 @@
+import"../../chunks/chunk-CWRWYU7D.esm.js";import{a}from"../../chunks/chunk-TVJISBND.esm.js";import"../../chunks/chunk-GZONWSRB.esm.js";export{a as createFoundation};

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

@@ -1,4 +1,4 @@
-import { DefaultTheme, RuleSet } from 'styled-components';
+import { DefaultTheme, RuleSet } from '../../vendors/StyledComponents';
 export declare const GlobalStyleComponent: import("react").NamedExoticComponent<import("styled-components").ExecutionProps & {
     theme: DefaultTheme;
     extend?: RuleSet<{

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

@@ -1 +1 @@
-import{a}from"../../chunks/chunk-SHDMTEPB.esm.js";import"../../chunks/chunk-GZONWSRB.esm.js";export{a as GlobalStyle};
+import{a}from"../../chunks/chunk-EEBGH4FW.esm.js";import"../../chunks/chunk-APD22JEO.esm.js";import"../../chunks/chunk-GZONWSRB.esm.js";export{a as GlobalStyle};

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

@@ -0,0 +1,50 @@
+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.
+ *
+ * Tipado explicitamente (em vez de `Theme`) para evitar ciclo de tipos
+ * `ThemeProvider.interface → Semantic.interface → ThemeProvider.interface`.
+ */
+export interface CreateSemanticInput {
+    colors: ColorsThemeInterface;
+    spacing: SpacingThemeInterface;
+}
+/**
+ * Resolve a camada Semantic a partir do theme estrutural.
+ *
+ * **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).
+ *
+ * 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).
+ *
+ * Mapping rationale (ADR-002 §5, Aplica ⇄ Apollion):
+ * - `feedback.{state}.bg`     ← `colors.{state}.base`
+ * - `feedback.{state}.txtOn`  ← `colors.{baseLight | baseDark}` por contraste
+ * - `feedback.{state}.border` ← `colors.{state}.dark`
+ * - `interface.function.{role}.normal.bg`     ← `colors.{role}.base`
+ * - `interface.function.{role}.normal.txtOn`  ← contraste sobre `bg`
+ * - `brand.{first,second,third}.default.surface` ← `colors.{main,opposite,complementary}.base`
+ * - `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`.
+ *
+ * @example
+ * ```ts
+ * import { createTheme } from '@apollion-dsi/core/themes';
+ *
+ * const theme = createTheme();
+ * theme.semantic.color.feedback.success.bg;
+ * // → mesmo valor que theme.colors.success.base
+ * ```
+ *
+ * @see ../../docs/adr/ADR-002-layered-theme-aliases-and-surface.md §3, §5, §9
+ * @see ../../docs/CONCEPTS.md §2 Layer Cake
+ */
+export declare function createSemantic(theme: CreateSemanticInput): SemanticLayer;

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

@@ -0,0 +1,131 @@
+/**
+ * Camada Semantic do theme — tokens nomeados por intenção, mirror direto da
+ * taxonomia de Aplica DS (`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.
+ *
+ * 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
+ * `docs/adr/ADR-002-layered-theme-aliases-and-surface.md`.
+ *
+ * @see ../../docs/adr/ADR-002-layered-theme-aliases-and-surface.md
+ * @see ../../docs/CONCEPTS.md §2 (Layer Cake) · §5 (Apollion ⇄ Aplica map)
+ * @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`.
+ */
+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.
+ */
+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.
+ */
+export interface SemanticColorFeedback {
+    success: SemanticFeedbackTokens;
+    danger: SemanticFeedbackTokens;
+    warning: SemanticFeedbackTokens;
+    information: SemanticFeedbackTokens;
+}
+/**
+ * Estado de um par interface.function (default `normal`). Reservado para
+ * expansão futura (`hover`, `pressed`, `disabled`) sem 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}`.
+ */
+export interface SemanticColorInterfaceFunction {
+    primary: SemanticInterfaceFunctionStates;
+    secondary: SemanticInterfaceFunctionStates;
+    tertiary: SemanticInterfaceFunctionStates;
+}
+/**
+ * Tokens de interface — agrega `function` e (futuramente) outros papéis.
+ */
+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.
+ */
+export interface SemanticBrandTokens {
+    default: {
+        surface: string;
+        txtOn: string;
+    };
+}
+/**
+ * Tokens de marca — identidade visual. Mapeiam para
+ * `theme.colors.{main, opposite, complementary}` no estrutural.
+ *
+ * `first`/`second`/`third` reflete a nomenclatura Aplica DS (ordem de
+ * apresentação) em vez da nomenclatura legada Apollion
+ * (`main`/`opposite`/`complementary`).
+ */
+export interface SemanticColorBrand {
+    first: SemanticBrandTokens;
+    second: SemanticBrandTokens;
+    third: SemanticBrandTokens;
+}
+/**
+ * Camada de cores da Semantic.
+ */
+export interface SemanticColor {
+    feedback: SemanticColorFeedback;
+    interface: SemanticColorInterface;
+    brand: SemanticColorBrand;
+}
+/**
+ * Spacing pré-resolvido em string CSS (`'8px'`, `'1rem'`, etc.), gerado uma
+ * única vez em `createSemantic()` a partir de `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).
+ */
+export interface SemanticDimensionSpacing {
+    zero: string;
+    micro: string;
+    xs: string;
+    small: string;
+    medium: string;
+    large: string;
+    xl: string;
+    xxl: string;
+    giant: string;
+}
+/**
+ * Camada de dimensão da Semantic. Atualmente cobre apenas spacing; tipografia
+ * e elevation podem entrar em iterações futuras sem breaking change.
+ */
+export interface SemanticDimension {
+    spacing: SemanticDimensionSpacing;
+}
+/**
+ * Forma completa da camada Semantic. Exposta em `theme.semantic` a partir do
+ * Apollion v3.1.0.
+ */
+export interface SemanticLayer {
+    color: SemanticColor;
+    dimension: SemanticDimension;
+}

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

@@ -0,0 +1,18 @@
+/**
+ * Camada Semantic — tokens nomeados por intenção, mirror de Aplica DS.
+ *
+ * Exposta em `theme.semantic` a partir de `@apollion-dsi/core` 3.1.0.
+ *
+ * Subpath import (preferido):
+ * ```ts
+ * import { createSemantic, type SemanticLayer } from '@apollion-dsi/core/themes/semantic';
+ * ```
+ *
+ * Re-exportada também pelo barrel `themes` para compat com consumers
+ * pre-subpath: `import { createSemantic } from '@apollion-dsi/core/themes';`.
+ *
+ * @see ../../../docs/adr/ADR-002-layered-theme-aliases-and-surface.md
+ */
+export type { CreateSemanticInput } from './Semantic.helpers';
+export type { SemanticBgPair, SemanticBrandTokens, SemanticColor, SemanticColorBrand, SemanticColorFeedback, SemanticColorInterface, SemanticColorInterfaceFunction, SemanticDimension, SemanticDimensionSpacing, SemanticFeedbackTokens, SemanticInterfaceFunctionStates, SemanticLayer, } from './Semantic.interface';
+export { createSemantic } from './Semantic.helpers';

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

@@ -0,0 +1 @@
+import{a}from"../../chunks/chunk-V5ZKDMDH.esm.js";import"../../chunks/chunk-GZONWSRB.esm.js";export{a as createSemantic};

package/lib/themes/Spacing/Spacing.props.d.ts

@@ -1,3 +1,34 @@
 import { SpacingInput, SpacingThemeInterface } from './Spacing.interface';
+import { Dimension } from '../Dimension';
 export declare const defaultInputSpacing: SpacingInput;
-export declare function createSpacing({ multiplier, alias }: SpacingInput): SpacingThemeInterface;
+/**
+ * Build the `theme.spacing(...)` function.
+ *
+ * **v4 (ADR-006 E2):** accepts optional `dimension` (density axis). When
+ * provided, the dimension's calibrated multiplier (see
+ * {@link DIMENSION_MULTIPLIERS} in `../Dimension`) **overrides** any
+ * `input.multiplier` from the spacing input. Consumer activates via
+ * `<ApollionProvider dimension>` and the spacing scale aliases adjust
+ * proportionally without recomputing the alias table.
+ *
+ * Resolution order:
+ * 1. If `dimension` arg provided → `getMultiplierForDimension(dimension)`.
+ * 2. Else → `input.multiplier ?? 0.25` (v3.x behavior preserved).
+ *
+ * @example
+ * ```ts
+ * theme.spacing('medium')          // '1rem' (normal: 0.25 * 4)
+ * theme.spacing('medium', 'xs')    // '1rem 0.5rem'
+ * theme.spacing(10)                // '2.5rem'
+ *
+ * // Under <ApollionProvider dimension="compact">:
+ * theme.spacing('medium')          // '0.8rem' (0.20 * 4)
+ *
+ * // Under <ApollionProvider dimension="spacious">:
+ * theme.spacing('medium')          // '1.28rem' (0.32 * 4)
+ * ```
+ *
+ * @see ../../docs/adr/ADR-006-v4-oklch-dimension-token-split.md §6 S3
+ * @see ../Dimension/Dimension.props.ts
+ */
+export declare function createSpacing({ multiplier, alias }: SpacingInput, dimension?: Dimension): SpacingThemeInterface;

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

@@ -1 +1 @@
-import{a,b}from"../../chunks/chunk-DP6AXK72.esm.js";import"../../chunks/chunk-GZONWSRB.esm.js";export{b as createSpacing,a as defaultInputSpacing};
+import{a,b}from"../../chunks/chunk-TG5BCBO4.esm.js";import"../../chunks/chunk-JOKVE3IX.esm.js";import"../../chunks/chunk-GZONWSRB.esm.js";export{b as createSpacing,a as defaultInputSpacing};

package/lib/themes/Surface/Surface.d.ts

@@ -0,0 +1,46 @@
+import React from 'react';
+import type { SurfaceMode } from './Surface.interface';
+/**
+ * Props do `SurfaceProvider`.
+ */
+export interface SurfaceProviderProps {
+    /**
+     * Surface mode aplicado ao subtree.
+     *
+     * - `'positive'` (default): no-op. Theme passa intacto.
+     * - `'negative'`: inverte Semantic + Foundation para "dark backdrop
+     *   treatment" (ver `invertForSurface` para semântica exata).
+     */
+    surface?: SurfaceMode;
+    children?: React.ReactNode;
+}
+/**
+ * Wrapper leve para inverter o `surface` de um subtree sem re-mount dos
+ * providers do `ApollionProvider` (StyleSheetManager, BreakpointsProvider,
+ * NotificationsProvider).
+ *
+ * Implementação segue ADR-002 §9 (grill-with-docs §1): usa a forma
+ * **função-theme** do styled-components ThemeProvider, que recebe o outer
+ * theme da árvore pai. Sem dependência de "default merge semantics" (que
+ * não está documentada).
+ *
+ * Por que `useCallback`: garante referência estável da função `themeFn`
+ * entre renders quando `surface` não muda — evita que styled-components
+ * recompute o theme do subtree.
+ *
+ * @example
+ * ```tsx
+ * <ApollionProvider>             // outer, positive (default)
+ *   <Page>
+ *     <SurfaceProvider surface="negative">
+ *       <Card />                 // dark card on light page
+ *     </SurfaceProvider>
+ *   </Page>
+ * </ApollionProvider>
+ * ```
+ *
+ * @see ./Surface.helpers.ts (invertForSurface — pure helper)
+ * @see ../../docs/adr/ADR-002-layered-theme-aliases-and-surface.md §3.2, §9
+ * @see ./README.md
+ */
+export declare const SurfaceProvider: React.FC<SurfaceProviderProps>;

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

@@ -0,0 +1,52 @@
+import type { SurfaceMode } from './Surface.interface';
+import type { Theme } from '../ThemeProvider/ThemeProvider.interface';
+/**
+ * Inverte um `Theme` para um surface mode específico, sem mutar a entrada
+ * nem tocar a camada Structural.
+ *
+ * **Pureza + idempotência (contrato ADR-002 §9):**
+ * - Não lê nada externo (Date, Math.random, env, DOM).
+ * - Não muta a entrada (`theme` permanece intacto após chamada).
+ * - Mesma entrada → mesma saída (referencialmente nova, byte-equivalente).
+ * - `invertForSurface(invertForSurface(theme, 'negative'), 'negative')` !==
+ *   `theme` (intencionalmente — segunda inversão NÃO retorna ao original;
+ *   `negative` é um terminal state baseado no Structural, não bg↔txt swap).
+ *
+ * Semântica de inversão (v1 — ADR-002 Slice 4):
+ * - **Structural** (`theme.colors.*`, `theme.spacing(...)`): inalterado.
+ * - **Semantic** + **Foundation** são reconstruídos a partir do Structural
+ *   com regra "dark backdrop treatment":
+ *   - `feedback.{state}.bg` ← `colors.{state}.dark` (mantém hue, escurece)
+ *   - `feedback.{state}.txtOn` ← `colors.baseLight`
+ *   - `feedback.{state}.border` ← `colors.{state}.base` (borda fica brilhante)
+ *   - `interface.function.{role}.normal.bg` ← `colors.baseDark` (neutro escuro
+ *     universal — cor de função perde saturação para virar "surface dark")
+ *   - `interface.function.{role}.normal.txtOn` ← `colors.baseLight`
+ *   - `brand.{n}.default.surface` ← `colors.{main|opposite|complementary}.dark`
+ *   - `brand.{n}.default.txtOn` ← `colors.baseLight`
+ * - **Dimension** (spacing): inalterado.
+ *
+ * Limitação documentada (v1): inversão é determinística e ignora `themeMode`
+ * (Apollion v3.x não tem mode resolution algorítmico). Em ADR-003 (v4 epic
+ * com Mode + Dimension axes) a semântica vira "negative dentro do mode
+ * corrente" — ver Aplica DS docs.
+ *
+ * @param theme - Theme base resolvido (vindo de `createTheme()` ou de outer
+ *                ThemeProvider).
+ * @param surface - `'positive'` (no-op, retorna `theme`) ou `'negative'`.
+ * @returns Novo Theme. Para `positive` é a referência original (identity).
+ *
+ * @example
+ * ```tsx
+ * import { invertForSurface } from '@apollion-dsi/core/themes/surface';
+ *
+ * const negativeTheme = invertForSurface(theme, 'negative');
+ * negativeTheme.foundation.bg.primary;  // → theme.colors.baseDark
+ * negativeTheme.foundation.text.onPrimary; // → theme.colors.baseLight
+ * theme.foundation.bg.primary; // unchanged (input não mutado)
+ * ```
+ *
+ * @see ../../docs/adr/ADR-002-layered-theme-aliases-and-surface.md §3, §9
+ * @see ./README.md
+ */
+export declare function invertForSurface(theme: Theme, surface: SurfaceMode, mode?: import('../ThemeProvider/ThemeProvider.interface').ThemeMode): Theme;

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

@@ -0,0 +1,20 @@
+/**
+ * Surface modes do theme. Conceito importado de Aplica DS (Poe).
+ *
+ * - `positive`: surface "normal" da página — fundo principal. Default.
+ * - `negative`: surface invertida/destacada (dark card numa página light,
+ *   highlighted section, badge invertido). Texto sempre claro sobre bg
+ *   escuro/saturado.
+ *
+ * Surface é **ortogonal a themeMode** (light/dark): `negative` em light mode
+ * = "dark surface numa página clara"; `negative` em dark mode = "lighter
+ * surface numa página escura". Ver ADR-002 §9 + grill-with-docs §5.
+ *
+ * Ortogonalidade verificada contra Aplica DS:
+ * https://docs.aplica.me/en-US/design-tokens-fundamentals/token-architecture
+ * "N_brands × 2 modes × 2 surfaces × 3 dimensions = N × 12 variants"
+ *
+ * @see ../../docs/adr/ADR-002-layered-theme-aliases-and-surface.md
+ * @see ./README.md
+ */
+export type SurfaceMode = 'positive' | 'negative';

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

@@ -0,0 +1,18 @@
+/**
+ * Camada Surface — wrapper de inversão contextual de Semantic + Foundation.
+ *
+ * Adicionada em `@apollion-dsi/core` 3.3.0 (ADR-002 Slice 4).
+ *
+ * Subpath import (preferido):
+ * ```ts
+ * import { SurfaceProvider, invertForSurface, type SurfaceMode } from '@apollion-dsi/core/themes/surface';
+ * ```
+ *
+ * Re-exportada também pelo barrel `themes`.
+ *
+ * @see ../../../docs/adr/ADR-002-layered-theme-aliases-and-surface.md
+ * @see ./README.md
+ */
+export type { SurfaceMode } from './Surface.interface';
+export { invertForSurface } from './Surface.helpers';
+export { SurfaceProvider, type SurfaceProviderProps } from './Surface';

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

@@ -0,0 +1 @@
+import{a,b}from"../../chunks/chunk-76C7AHBV.esm.js";import"../../chunks/chunk-TVJISBND.esm.js";import"../../chunks/chunk-APD22JEO.esm.js";import"../../chunks/chunk-GZONWSRB.esm.js";export{b as SurfaceProvider,a as invertForSurface};