Overview

Introduction

Atlas was built to codify Proof’s design language and replace the ad hoc overrides from earlier years. Scrappy decisions made sense initially, but don’t scale. Atlas is the system that takes its place.

These docs are a reference for how the system is built and the beliefs that shape it. Start with the Principles to understand what Atlas is optimizing for, then move to Architecture for how the system is assembled. Component pages document each primitive in use.

Principles

Atlas is built on two beliefs. Everything in the system, from the token architecture to the component APIs to the decisions nobody will see, follows from them.

Craft is an obligation, not a response

Atlas is built for an audience that may never consciously register the difference between good and great. It’s why we raise our bar, not lower it. Design literacy is taught, interaction by interaction, by exposure to work that respects the person on the other side of the screen.

Take our Button, for example: A flat fill with contrasting text would have satisfied every functional and accessibility requirement. Atlas ships skeuomorphic, token-driven buttons with subtle gradients and a scale-down on press. Dark mode gets its own bespoke set, because gradients don’t behave the same in the absence of light. Those are the decisions “good enough” doesn’t make.

Delight is in the foundations

Delight is not a layer applied on top of working software. It’s the natural response that emerges when the foundations are right. Most attempts at delight reach for flash. Atlas treats delight as a property of the primitives themselves: the weight of a press, the timing of a state change, the way a control resolves when a user commits to a decision.

Our Combobox morphs its chevron into a close icon when a selection is made. It’s equally small and deliberate. Most users will never consciously notice the transition. They’ll notice that the component feels correct, and they’ll carry that feeling into the next interaction, and the next.

Architecture

Atlas is a two-layer token system, raw primitives at the base and semantic tokens on top, powering a library of React components built in TypeScript.

Inspiration

Atlas draws from two Radix projects: Colors and UI. The former adopts the 12-step scale applied uniformly across every color family and the shadow system. The latter borrows component patterns and API conventions that Proof’s engineers were already familiar with. Where Radix UI cleanly covers a pattern, Atlas wraps its primitives. Where Proof needs something Radix doesn’t offer, components are built from scratch.

The goal isn’t to be a Radix derivative; it’s to stand on proven foundations so Atlas can spend its effort on the decisions that are actually Proof’s to make.

Tokens

Atlas resolves every styling decision through two layers.

Raw tokens are the most basic design values: exact color codes, spacing sizes, border-radius measurements, shadow effects, and text scales. Each color family has 12 shades, so subtle changes in appearance are possible without creating new values outside this scale.

Semantic tokens give names to the roles played by raw values. For example, a semantic token like text-default or text-subtle links to a specific raw color value. Component styles use these semantic names instead of direct values. This allows the system to be easily themed: a component refers to a role, not a specific color, and can adapt automatically to different themes.

Theming

Light and dark themes are set at the raw token level. Each color family has separate basic color values for light and dark modes. Semantic tokens then point to the correct raw color for the current theme.

This means theming isn’t a special case. It’s the system’s natural behavior. A component that references text-default resolves correctly in light and dark without knowing either theme exists. The same is true for accent swaps, which operate independently of light and dark: changing the active accent re-routes the semantic tokens that depend on it, and every surface using those tokens updates automatically.

Components

Atlas components are written in React and TypeScript. They reference semantic tokens exclusively. A component that reaches beyond the semantic layer to raw tokens is a bug in the system, not a feature of the component.