Skip to content

The Algebra of Color Design

Context: The physics and grammar of the Axiomatic Color system.

This document defines the “Physics” of the Axiomatic Color system. While the system is built on rigorous math, you can think of it using a simple grammatical analogy:

  • Context (H,C) is the Setting: It’s the lighting in the room. If the room is red, everything inside is tinted red. This “atmosphere” permeates everything.
  • Intent (L) is the Voice: It’s how loud you are speaking. You can whisper (Subtle) or shout (High).
  • Surfaces are Scene Changes: When you walk into a new room (a Card, a Sidebar), the conversation resets. You stop shouting, but the lighting might stay the same.

Below, we formalize these intuitions into a set of rules that guarantee your UI always looks consistent.

The system state at any point in the DOM tree is defined by a vector Σ.

Σ=⟨H,C,Lsrc,α⟩
Σ = ⟨ 360° Hue (Drag) , 0.30 Chroma (Drag) , Subtle Intent (Click) , Light Polarity (Click) ⟩
H
Context Hue The base hue for the current environment.
C
Context Chroma The base vibrancy for the current environment.
Lsrc
Intent Lightness A reference to a lightness token (e.g., text-high).
α
Polarity The local resolved mode (Light/Dark).
Φ(Σ) Resolution

Hello World

This text reflects the state vector above.

The CSS Engine acts as a projection function Φ that maps the state vector Σ to a concrete CSS color value.

Φ(Σ)↦ColorSpace(oklch) Φ(⟨H,C,Lsrc,α⟩)=oklch(eval(Lsrc,α),C,H)

Where eval(Lsrc,α) represents the Late Binding of the token. It is a lookup function into the token definition set:

∀t∈Tokens,∃(llight,ldark) s.t. eval(t,α)=(α=Dark)?ldark:llight
Outer Scope
Intent is preserved here.
Surface Scope
Intent is reset here (The Glass Box).
👤
Hello World
text-subtle
Inherit
Drag the card across the boundary. Notice how the text style resets inside the Surface, but the Hue (Context) persists.

Rationalization: Ambient vs. Semantic State

We can rationalize this behavior by distinguishing between two types of state:

  1. Environmental State (H,C): This behaves like Ambient Light. If a room is lit with red light, objects inside (Surfaces) should reflect that red tint. The atmosphere permeates boundaries.
  2. Semantic State (Lsrc): This behaves like Grammar. A “Card” is a new sentence. Just because the previous sentence ended quietly (Subtle) doesn’t mean the new sentence (Card Title) should start quietly. The grammar resets at the boundary of the object.

Intent classes (e.g., .text-subtle) modify the Lightness Source.

Itoken(⟨H,C,Lsrc,α⟩)=⟨H,C,Ltoken,α⟩
  • Identity on Context: H and C are preserved.
  • Action: Updates Lsrc.

Modifier classes (e.g., .hue-brand) modify the Context variables.

Mbrand(⟨H,C,Lsrc,α⟩)=⟨Hbrand,Cambient,Lsrc,α⟩
  • Identity on Intent: Lsrc is preserved.
  • Context Definition: Updates H to the brand hue. Updates C to the Ambient Chroma (Cambient≈0.1×Cbrand).

4.1. Orthogonality (Commutativity of I and M)

Section titled “4.1. Orthogonality (Commutativity of I and M)”

Because Intent (I) and Modifiers (M) operate on disjoint components of the state vector, they are commutative.

I(M(Σ))≡M(I(Σ))

Implication: The order of classes in HTML (class="text-subtle hue-brand" vs class="hue-brand text-subtle") does not matter for the resulting color.

A
Base
B
Hue
+ Text Subtle
C
Subtle
+ Hue Brand
D
Combined
Whether you apply Hue then Subtle (Top Path), or Subtle then Hue (Bottom Path), you arrive at the exact same destination.

A Surface (S) resets the local intent. Therefore, an Intent applied outside a surface does not penetrate into the surface’s default text.

Inside Surface: Φ(S(I(Σ)))≠Φ(I(S(Σ)))
  • S(I(Σ)) : The surface resets the intent. The outer intent is lost.
  • I(S(Σ)) : The intent is applied to the surface’s context.

Implication: You must apply text utilities inside or on the element that needs them.

Modifiers (M) are Contrast Preserving.

Contrast(Φ(Σ),Background)≈Contrast(Φ(M(Σ)),Background)

Since M only changes H and C, and OKLCH is perceptually uniform, the perceived lightness (and thus contrast against the background) remains constant.

Axiomatic (OKLCH) Lc 0
Readable
Contrast remains constant across all hues.
Traditional (HSL) Lc 0
Variable
Contrast fluctuates wildly (Yellow is unreadable).

Intent (I) is Chromatically Transparent.

Hue(Φ(I(Σ)))=Hue(Φ(Σ))

Changing the text importance (High -> Subtle) never shifts the hue.

This algebra proves that we can support N intents and M contexts with N+M classes, rather than N×M classes.

  • Traditional: .text-subtle-on-brand, .text-subtle-on-neutral
  • Axiomatic: .text-subtle + .hue-brand

The resolution happens at render time via the Φ function (the CSS Engine).

Applying the same modifier twice is equivalent to applying it once.

Mbrand(Mbrand(Σ))≡Mbrand(Σ)

This means nesting a .hue-brand section inside another .hue-brand section is safe and redundant.

If a container does not act as a Surface (S), it does not reset Lsrc.

Container(Isubtle(Σ))→Text is still subtle inside

This distinguishes Layout Containers (divs, spans) from Surfaces (cards, sidebars). Surfaces are opaque boundaries for Intent; Containers are transparent.

Since M operators control the environment (H,C) for all child elements, changing the top-level modifier effectively re-themes the entire subtree without requiring changes to the leaf nodes (text, borders).

7.4. The Portal Effect (Subspace Involution)

Section titled “7.4. The Portal Effect (Subspace Involution)”

Because Inverted Surfaces perform a Hard Flip (α′=¬α), nesting them creates an alternating polarity stack. However, because S is lossy on Intent (L), this is not a true inverse of the state.

Sinv(Sinv(Σ))≠Σ

While the polarity returns to the original (¬(¬α)=α), the Intent Lsrc is reset to Lhigh at each step. You recover the mode, but you lose the semantic context.

The Portal Stack

Layer 0 (Light)

The text in this layer is High.

Notice that when you enter a new layer (Surface), the Intent resets to "High", even if the parent layer was set to "Subtle". The "Conversation" restarts.