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 () 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 () 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.
1. The State Space ()
Section titled “1. The State Space (Σ)”The system state at any point in the DOM tree is defined by a vector .
Hello World
This text reflects the state vector above.
2. The Resolution Function ()
Section titled “2. The Resolution Function (Φ)”The CSS Engine acts as a projection function that maps the state vector to a concrete CSS color value.
Where represents the Late Binding of the token. It is a lookup function into the token definition set:
Rationalization: Ambient vs. Semantic State
We can rationalize this behavior by distinguishing between two types of state:
- Environmental State (): 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.
- Semantic State (): 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.
3.2. Intent Operator ()
Section titled “3.2. Intent Operator (I)”Intent classes (e.g., .text-subtle) modify the Lightness Source.
- Identity on Context: and are preserved.
- Action: Updates .
Intent classes like .text-subtle only change one thing: the lightness reference. They don’t touch the color. They say “make this text dimmer,” regardless of whether it’s blue, red, or purple.
3.3. Modifier Operator ()
Section titled “3.3. Modifier Operator (M)”Modifier classes (e.g., .hue-brand) modify the Context variables.
- Identity on Intent: is preserved.
- Context Definition: Updates to the brand hue. Updates to the Ambient Chroma ().
Modifier classes like .hue-brand change the atmosphere. They say “everything inside here should be purple,” but they don’t touch the text hierarchy. A title is still a title, just purple now. This is also where the “Dampening” happens: the modifier takes a vibrant brand color and creates a soft ambient version for backgrounds.
4. Laws of Composition
Section titled “4. Laws of Composition”4.1. Orthogonality (Commutativity of and )
Section titled “4.1. Orthogonality (Commutativity of I and M)”Because Intent () and Modifiers () operate on disjoint components of the state vector, they are commutative.
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.
Because .text-subtle only touches Lightness, and .hue-brand only touches Color, they don’t step on each other’s toes. You can combine them in any order, and the result is always “Subtle Brand Color”.
4.2. Surface Dominance
Section titled “4.2. Surface Dominance”A Surface () resets the local intent. Therefore, an Intent applied outside a surface does not penetrate into the surface’s default text.
- : The surface resets the intent. The outer intent is lost.
- : The intent is applied to the surface’s context.
Implication: You must apply text utilities inside or on the element that needs them.
Surfaces are barriers. If you make a container “subtle”, and then put a Card inside it, the text inside the Card goes back to normal. The Card protects its contents from the outside world’s text styles.
5. Invariants
Section titled “5. Invariants”5.1. Contrast Preservation
Section titled “5.1. Contrast Preservation”Modifiers () are Contrast Preserving.
Since only changes and , and OKLCH is perceptually uniform, the perceived lightness (and thus contrast against the background) remains constant.
Changing the hue (e.g., adding .hue-brand) never breaks accessibility. If the text was readable before, it stays readable, because the system only changes the color, not the brightness.
5.2. Intent Stability
Section titled “5.2. Intent Stability”Intent () is Chromatically Transparent.
Changing the text importance (High -> Subtle) never shifts the hue.
Changing the text style (e.g., making it .text-subtle) never changes its color family. If you are in a “Brand” section, the subtle text will still be tinted with the brand color, just dimmer. The text style doesn’t “reset” the color to gray.
6. Practical Application
Section titled “6. Practical Application”This algebra proves that we can support intents and contexts with classes, rather than 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).
7. Implications & Corollaries
Section titled “7. Implications & Corollaries”7.1. Idempotency of Modifiers
Section titled “7.1. Idempotency of Modifiers”Applying the same modifier twice is equivalent to applying it once.
This means nesting a .hue-brand section inside another .hue-brand section is safe and redundant.
7.2. The “Leakage” Corollary
Section titled “7.2. The “Leakage” Corollary”If a container does not act as a Surface (), it does not reset .
This distinguishes Layout Containers (divs, spans) from Surfaces (cards, sidebars). Surfaces are opaque boundaries for Intent; Containers are transparent.
7.3. Universal Theming
Section titled “7.3. Universal Theming”Since operators control the environment () 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 is lossy on Intent (), this is not a true inverse of the state.
While the polarity returns to the original (), the Intent is reset to at each step. You recover the mode, but you lose the semantic context.
The Portal Stack
The text in this layer is High.