Skip to main content

Master Mathematics and Algorithms

This document concentrates the mathematical truth (formulas and equations) behind all visual system decisions in the Aplica DS Theme Engine V2. All AI reasoning, build processing, or design validation MUST be grounded in these formulas, rather than resorting to guesswork and "magic" approximations.

1. Dimensional Scales (Sizes and Spacings)​

The primary formula that calculates the entire dimension Token system (Sizes, Spacing, Radius) starts from the notion of increment proportional to the base unit (typically configured at 16px). The key (key) reflects the percentage of the base unit.

Universal Analytical Formula:

pxValue = key === 0 ? 0 : Math.max(1, Math.round((key / 100) * DefaultDesignUnit))

Where:

  • DefaultDesignUnit: Global default of 16px.
  • key: Nominal scale number (e.g., 0, 50, 100, 250).
  • Constraint: Any value generated above 0 will always be at least 1px.

Growth Mechanisms: The engine does not generate continuous linear values, but adopts architectural sequences:

  • Up to the Base Unit (100): Subdivisions and decimals in Base-4 (local LayoutUnit) — generating common breakpoints like 2px, 4px, 8px.
  • Above the Base Unit: Modified "Pseudo-Fibonacci" sequence summing the previous terms: f(n) = f(n-1) + f(n-2) generating drastic macro growth.

2. Color Decomposition and Interpolation in OKLCh Space​

Instead of using HSL (whose interpolations distort perceptions such as blue turning purple, or yellows dying to dark gray), the V2 Engine is based exclusively on the perceptually uniform color space OKLCh (Lightness, Chroma, Hue). The system anchors the hue (h) and chroma (C), performing the ramp on illumination purity (L).

Main Palette Ramps​

The palette creates 19 numeric levels (10 to 190). Illumination anchors (L ranging from 0.0 to 1.0):

  • Level 10 (Lightest): L = 0.98
  • Level 100 (Core Color): L = baseL (actual L measured from the configured color, preserved without round-trip distortions).
  • Level 190 (Darkest): L = 0.05

Interpolation Formula: For levels ≤ 100 (targetL for light colors):

t = (level - 10) / 90
L_result = 0.98 - t * (0.98 - baseL)

For levels > 100 (targetL for dark tones):

t = (level - 100) / 90
L_result = baseL - t * (baseL - 0.05)

Neutrals Scale ("Colored Grays")​

The Neutrals scale is generated by overriding the brand's Chroma.

  • Chroma Isolation: It retains only 10% of the saturation (C * 0.1 of the original brand), infusing the pure tones with a minimal color temperature.
  • Its anchors range from Level 5 (L: 0.98) to Level 140 (L: 0.05).

3. Perceptual Dark Mode​

Dark Mode is not just a loose dark gray palette. Its inversions are mirrored mathematical calculations, followed by chromatic absorption that attenuates strong radiation in scotopic viewing.

Level Inversion Equation​

The shade level requested in Light is perfectly replicated under the inverted Dark index:

DarkLevel[level] = LightLevel[200 - level]

(example: the equivalent of the vibrant Level 10 in Dark mode evokes Level 190)

Chroma Calibration in Dark Mode​

Very reflective or pure colors glow uncomfortably on dark panels (optical fatigue). Because of this, the V2 Engine applies a global multiplier constraint to soften Neon/Flare on dark panels:

darkModeChroma = baseChroma * 0.85

Translation: Dark mode has 15% less native Saturation (Chroma) than its Light Mode counterparts.

4. The "txtOn" System and Analytical WCAG Calculation​

txtOn is never presumed. It is natively validated by measuring relative luminance to attest readability:

contrastRatio = (LighterLuminance + 0.05) / (DarkerLuminance + 0.05)
  1. Brand-Tint: The scan navigates the Palette looking for one of the polarities that supports at least 4.5:1 Ratio against the Surface.
  2. High-Contrast Fallback: If the brand hue fails to provide sufficiently safe text, the API forces the analytical outline using black-and-white extremes (#000000 or #ffffff) and retains the one with greater contrast.

5. Opacity​

Opacity follows a standardized 1D scalar mapping. The strict transparency levels in a linear system translate to the percentage converted to Alpha:

  • 10% (0.1) → superTransparent
  • 20% (0.2) → semiTranslucid
  • 50% (0.5) → translucid
  • 80% (0.8) → superTranslucid
  • 90% (0.9) → semiOpaque
  • 100% (1.0) → opaque

All Alpha-blending is rigorously documented to compose and suppress color via engine. No intermediate transparency like 0.342 is compiled under the reins of Theme Engine V2 without creating a scale override in global.opacityScale.

6. Typographic Scale and Grid-Locking​

Typography is mathematically derived through a geometric scale (Musical Scale) anchored in the DefaultDesignUnit (16pt by default).

Font Size Formula​

fontSize = DefaultDesignUnit × ratio^exponent

Where:

  • ratio: Musical scale factor — default: 1.2 (Minor Third). Configurable in global.typography.fontSizeScaleRatio.
  • exponent: The ordinal step of the scale (e.g., medium = base exponent 0, large = +1, small = -1, etc.).
  • Ceiling rounding: Math.ceil(result) to ensure integer pt values.
  • For positive exponents (above base): rounded to the next multiple of LayoutUnit (4pt).

Line-Height Formula (Grid-Locked Interline)​

Every line height is firmly locked to the 4pt Grid. Regardless of fontSize, the result is forced to be a multiple of LayoutUnit:

lineHeight = Math.ceil((fontSize × multiplier) / LayoutUnit) × LayoutUnit

Where:

  • multiplier: One of the four semantic factors — tight (1.0), close (1.2), regular (1.4), wild (1.8).
  • LayoutUnit: 4 (pt).

Numerical example (giga = 36pt):

  • tight = ceil((36 × 1.0) / 4) × 4 = 36pt ✓
  • close = ceil((36 × 1.2) / 4) × 4 = ceil(43.2 / 4) × 4 = ceil(10.8) × 4 = 11 × 4 = 44pt
  • regular = ceil((36 × 1.4) / 4) × 4 = ceil(50.4 / 4) × 4 = ceil(12.6) × 4 = 13 × 4 = 52pt
  • wild = ceil((36 × 1.8) / 4) × 4 = ceil(64.8 / 4) × 4 = ceil(16.2) × 4 = 17 × 4 = 68pt

Grid-locking prevents sub-pixels and vertical alignment shifts across all rendering platforms.

7. Depth / Elevation (Depth and Shadows)​

The depth system is modeled as a composition of 5 primitive quantities that map directly to CSS box-shadow. Shadow optics use exclusively Grayscale without chroma/hue to subtract luminance purely (simulating real physical light occlusion).

The 5 Primitive Quantities​

box-shadow: <offsetX> <offsetY> <blur> <spread> <color_with_alpha>
            ├─ Distance ─┤  ├Intensity┤├Proximity┤├─── Luminosity ───┤
  1. Position (Inset/Outer): Determines whether the shadow is projected outward (float = drop-shadow) or inward (recess = inset).
  2. Distance (Offset X/Y): Tied to Dimension tokens — e.g., micro (2pt), extraSmall (4pt), small (8pt).
  3. Intensity (Blur): Diffuse occlusion spreading. Low blur (~4pt) = hard light; High blur (~16pt+) = soft ambient light.
  4. Proximity (Spread): Negative spread simulates proximity; 0 = shadow faithful to the contour.
  5. Luminosity (Color + Alpha): Exclusively Grayscale color (e.g., #1a1a1a) + Alpha channel controlled by the Opacity scale.

Multi-Shadow Composition (High Elevations)​

Elevation levels ≥ 4 use multi-layer shadows to emulate real optical duality:

/* Contact Shadow (hard, short, close) */
/* + Ambient Shadow (diffuse, expansive, distant) */
box-shadow:
  0px 4px 8px rgba(0, 0, 0, 0.08),
  0px 16px 48px rgba(0, 0, 0, 0.20);

Dark Mode Adaptation: "Inner Light"​

In Dark Mode, external shadows become imperceptible against dense backgrounds. The Engine introduces a top glow simulating ambient light refraction:

box-shadow: 0px 1px 0px rgba(255, 255, 255, 0.08) inset;

8. Output Unit Conversion​

The Theme Engine stores all values in points (pt), treated internally as the abstract calculation unit. Conversion to final units occurs in the Transformers during the build phase.

Conversion Formula to rem (Web/CSS)​

remValue = ptValue / baseFontSize

Where baseFontSize = 16 (default, configurable in global.dimension.baseFontSize).

Examples:

Value in ptCalculationOutput in rem
4pt4 / 160.25rem
8pt8 / 160.5rem
16pt16 / 161rem
24pt24 / 161.5rem
48pt48 / 163rem

Format Mapping by Platform​

Output FormatUnitReason
CSSremWCAG 1.4.4 Accessibility — scales with the user's font preference
JSON (Figma / Tokens Studio)pxDesign tools operate with integer px values
ESM / CJS (JavaScript)pxAbsolute numeric precision for JavaScript calculations
Depth/Spreadpx (always)Box-shadow spread is not a semantic dimensional token — it is a raw value

The separation between calculation unit (pt) and output unit (rem/px) ensures the same mathematical scale works on any platform without recalculations in the product code.

References​