Aplica DS Opacity System
Premise
The opacity (Alpha Channel) system in Aplica DS is not an arbitrarily chosen visual value, but a finite mathematical scale. Opacity acts as a modifier of intent and depth, allowing lower layers to influence the color perception of the upper layer. It shares architectural responsibility in the Design System, acting in overlays, faders, disabled states, and components such as modals.
Just like dimensions and colors, no hardcoded value (such as opacity: 0.35) should be used in code or design. The design system provides both semantic and raw tokens.
The engine responsible for interpreting these values operates under the aplica-tokens-theme-engine architecture.
Mathematical Opacity Scale
The V2 opacity system default scale operates in standardized absolute percentages from 0 to 100 (translated to floating-point outputs 0 to 1 in CSS).
The native scale consists of the following presets:
| Token / Key | Value | Output (alpha) | Conceptual Use |
|---|---|---|---|
transparent | 0% | 0 | Completely invisible surfaces, invisible hitboxes. |
superTransparent | 10% | 0.1 | Very subtle states such as recesses or almost imperceptible hover backgrounds. |
semiTranslucid | 20% | 0.2 | Light overlays, visual hints, or secondary disabled states. |
translucid | 50% | 0.5 | Gold standard for disabled states and default backdrops. |
superTranslucid | 80% | 0.8 | Dense overlays and surfaces that require focus but reveal the underlying texture. |
semiOpaque | 90% | 0.9 | Elements that nearly obscure the surface; use in blocking tooltips or modals. |
opaque | 100% | 1.0 | Solid surfaces, complete color blocks, real visibility and base. |
These values are the canonical matrix. They can be customized if a specific theme is defined via config/global/themes.config.json in the global.opacityScale attribute, but the keys remain invariant to ensure structural predictability in the semantic layer.
Output and Accessibility
The WCAG contrast channel is greatly affected by translucent layers, by their nature of blending overlapping RGBs.
[!WARNING] Colors or textual planes generated by opacity (e.g., black text with
color: rgba(0,0,0,0.5)) are never algorithmically guaranteed to pass WCAG AA / AAA in all circumstances without contextual auditing, since contrast guarantee depends on the neighboring wallpaper and background. Use opacity in text (txtOn) ONLY where it is strictly secondary and does not carry critical user information. For all base data content, usetxtOnvia Grayscale/Neutrals instead of reducing Opacity.
Accessibility (A11y) demands caution:
When applying opacity to components that must create shadows (box-shadows), it is mandatory that these shadows come exclusively from validated Grayscale configurations, avoiding degradation of ambient occlusion.
Token Structure
Outputs are exported under the architectural opacity root:
semantic.opacity.raw.<key>
Example: {semantic.opacity.raw.translucid} renders 0.5.
Surface Stubs (Surface Opacity Stubs)
Beyond semantic opacity (semantic.opacity.raw.*), the engine automatically generates a layer of pre-composed translucent colors — the so-called stubs. These tokens combine the opacity scale with pure black (rgba(0,0,0,α)) and pure white (rgba(255,255,255,α)), producing color values ready for immediate consumption in shadows and overlays:
surface.opacity.color.dark.<key> → rgba(0, 0, 0, <alpha>)
surface.opacity.color.light.<key> → rgba(255, 255, 255, <alpha>)
| Stub Token | Dark Value | Light Value |
|---|---|---|
surface.opacity.color.*.transparent | rgba(0,0,0, 0) | rgba(255,255,255, 0) |
surface.opacity.color.*.superTransparent | rgba(0,0,0, 0.1) | rgba(255,255,255, 0.1) |
surface.opacity.color.*.semiTranslucid | rgba(0,0,0, 0.2) | rgba(255,255,255, 0.2) |
surface.opacity.color.*.translucid | rgba(0,0,0, 0.5) | rgba(255,255,255, 0.5) |
surface.opacity.color.*.superTranslucid | rgba(0,0,0, 0.8) | rgba(255,255,255, 0.8) |
surface.opacity.color.*.semiOpaque | rgba(0,0,0, 0.9) | rgba(255,255,255, 0.9) |
surface.opacity.color.*.opaque | rgba(0,0,0, 1) | rgba(255,255,255, 1) |
[!IMPORTANT] Bridge with the Depth / Elevation system These stubs are the canonical source of the Luminosity primitive in the depth system (see 04-depth-elevation.md). External shadows (occlusion) consume
darkstubs, while the Dark Mode "Inner Light" pattern consumeslightstubs. This ensures that:
- Shadows remain achromatic (no chroma/hue) — eliminating color vibration on tinted surfaces
- The intensity of each shadow layer is governed by the same scale as all system opacity
- Changes to
global.opacityScaleautomatically propagate to elevation composites
References
- Depth & Elevation — Luminosity and shadow composition
- Mathematics and Algorithms — Section 5: Opacity
- Sync and Rules script: sync-architecture.mjs
- UI Generator mapper: ui-generator.mjs