Thinking in Surfaces

Static palettes are not enough for modern interfaces.

In a dynamic UI, colors change based on where they live. A “gray” text needs to be dark on a white card, but light on a dark tooltip.

Axiomatic Color acts as a Context Engine. Instead of giving you a fixed list of colors, it gives you Surfaces that automatically adjust their content to fit the environment.

The Core Concept

A Surface is not just a background color. It sets the rules for everything inside it.

When you place an element on a surface, you aren’t just painting pixels. You are entering a new Context.

1. Surfaces Create Context

Every surface acts as a “Context Provider.” It automatically sets a suite of CSS variables that determine how text, borders, and other elements should look when sitting on that specific surface.

Use the global Token Inspector to inspect these surfaces.

Page (Light Context)

Card (Nested)

Spotlight (Inverted Context)

This surface inverts the polarity. Text becomes light automatically.

In the visualization above:

1. The Page sets the baseline context (Light Mode).
2. The Card sits on the Page. It might be slightly lighter or darker, but it maintains the same Solar Time (Light text on Dark, or Dark text on Light).
3. The Spotlight (the dark box) inverts the time. It tells its children: “I am dark. You must be light.”

2. Content Adapts to Context

Because of this architecture, your components become portable.

You don’t write CSS like .card .text or .footer .text. You just write .text-strong.

• If .text-strong is on a white card, it resolves to black.
• If .text-strong is on a black tooltip, it resolves to white.

The component doesn’t know where it is. The Surface tells it how to render.

The Hierarchy of Surfaces

We categorize surfaces based on their physical role in the UI, not their color.

The Canvas

These are the foundations. They recede into the background.

Page

The infinite backdrop.

Application Root

Workspace

A dedicated area for tools or navigation.

The Objects

These sit on top of the canvas. They hold your content.

Card

The primary container for information.

Tinted

A subtle grouping mechanism.

The Interactors

These are actionable. They invite touch.

Action

Buttons, toggles, and controls.

Click Me

Soft Action

Secondary interactive elements.

Cancel

The Spotlights

These demand attention. They often break the current polarity to stand out.

Spotlight

Tooltips, toasts, and primary calls-to-action.

Changes saved successfully

Note on Inversion: Spotlight surfaces perform a “Hard Flip” of the theme. If your app is in Light Mode, a Spotlight surface forces its internals into Dark Mode (and vice versa). This ensures that native browser controls (like scrollbars and checkboxes) render correctly inside the inverted area.

X-Ray Mode (Forced Colors)

What happens when the user turns on “High Contrast Mode” in Windows?

In this mode, the operating system strips away all background colors to ensure maximum legibility. This can be disastrous for modern UIs that rely on background colors to define structure (like a white card on a gray background).

Axiomatic Color handles this with X-Ray Mode.

When the system detects forced-colors: active, it automatically switches from “Rich Mode” (painting pixels) to “X-Ray Mode” (drawing outlines).

• Rich Mode: A card has a white background and no border.
• X-Ray Mode: The background becomes transparent, and a Border appears automatically.

This ensures that your UI structure remains visible (“Fail Visible”) even when the user strips away the paint.

Why This Matters

By thinking in surfaces, you stop fighting with contrast ratios.

1. Guaranteed Contrast: The system calculates the foreground colors based on the background surface. If the surface changes, the text changes.
2. Automatic Dark Mode: You don’t design “Dark Mode” separately. You just define your surfaces, and the system flips the context.
3. Infinite Nesting: You can put a Card inside a Sidebar inside a Page. The system handles the math to ensure distinctness at every level.