Theming
Every color, shadow, radius, font and duration in Atmosphere is a CSS variable that
starts with --am-. Change a variable, and every component that uses it
follows.
#The three token layers
The variables, called tokens, are in src/styles/tokens/.
They are in three layers, and each layer only reads from the one before it.
| Layer | File | What it holds | Example |
|---|---|---|---|
| 1. Primitives | _primitives.css |
Raw values: color scales, spacing, radii | --am-tangerine-500: #ff6a1f |
| 2. Roles | _roles.css |
What each value is for. Components read only these. | --am-accent: var(--am-tangerine-500) |
| 3. Themes | _themes.css |
New role values for graphite, compact density and the other settings | [data-am-theme='graphite'] { --am-bg: ... } |
Some smaller files sit beside them:
| File | What it holds |
|---|---|
_typography.css |
Font families, the type scale, weights, letter spacing |
_motion.css |
Durations, easing curves and the reduced motion rules |
_charts.css |
The six chart colors and the floor plan colors |
_recipes.css |
The surface classes .am-raised, .am-well,
.am-key, .am-slab, .am-float
|
Components never read a primitive, and never contain a color value. That is why a new theme only redefines roles. You never edit a component to change the look.
#The main roles
| Role | What it colors | Light | Graphite |
|---|---|---|---|
--am-bg |
The page background | #DFE5EC |
#1E222A |
--am-surface |
Raised panels | #F3F6F9 |
#262B33 |
--am-surface-2 |
Table rows and flat tiles | #E9EEF3 |
#2E343D |
--am-inset |
The inside of wells | #D1DAE3 |
#171B21 |
--am-key-top, --am-key-bottom |
The keycap face | #FBFCFD, #EEF2F6 |
#303742, #262B33 |
--am-key-edge |
The keycap's bottom edge | #C9D2DC |
#101319 |
--am-ink |
Headings, values, main text | #1F2733 |
#E9EEF5 |
--am-ink-2 |
Labels and secondary text | #46505E |
#B6C0CE |
--am-ink-3 |
Captions and placeholders | #5C6775 |
#98A3B2 |
--am-ink-4 |
Lines and ticks. Never text. | #8B95A3 |
#6E7887 |
--am-accent |
The main action color: fills, LEDs, focus | #FF6A1F |
#FF6A1F |
--am-accent-text |
The accent used as text | #A8380A |
#FF8447 |
--am-info |
Cooling and information | #5BB8FF |
#5BB8FF |
--am-good, --am-warn, --am-bad |
Status fills and LEDs | #3FAE7E, #F5C232, #E2566B |
same |
--am-good-text, --am-warn-text,
--am-bad-text
|
Status colors used as text | #1E6845, #7A5A05, #B02840 |
#5BD3A0, #F5C232, #F0879A |
The full list, with every shadow and density value, is in _roles.css.
Each group has a comment.
#Fill colors and text colors
Each signal color has two forms:
-
--am-accentis a fill. Use it for a button, an LED or a chart line. -
--am-accent-textis a deeper shade that is safe for text on the pale surfaces. It meets the WCAG AA contrast ratio of 4.5 to 1.
The same is true for info, good, warn and
bad. If you use a fill color for text, small text will be hard to read.
#Change the accent color
The accent (tangerine) is used by the main buttons, the logo key, LEDs, the focus ring
and the first chart series. To change it, add your color scale to
_primitives.css:
/* src/styles/tokens/_primitives.css, inside :root */
--am-brand-300: #8f8cff; /* light: the top of the key gradient */
--am-brand-500: #6c63ff; /* base: fills, LEDs, focus */
--am-brand-700: #4a3fd6; /* deep: the key's bottom edge */
--am-brand-800: #4136b8; /* text on pale surfaces */
--am-brand-wash: #ecebff; /* soft background for alerts */
--am-brand-wash-dark: #25233f; /* the same, for graphite */
Point the accent roles at it in _roles.css:
/* src/styles/tokens/_roles.css, inside :root */
--am-accent: var(--am-brand-500);
--am-accent-2: var(--am-brand-300);
--am-accent-edge: var(--am-brand-700);
--am-accent-text: var(--am-brand-800);
--am-accent-soft: var(--am-brand-wash);
--am-accent-soft-ink: var(--am-brand-700);
--am-accent-glow: rgb(108 99 255 / 35%);
--am-accent-halo: rgb(108 99 255 / 18%);
--am-focus: var(--am-brand-500);
--am-focus-ring: rgb(108 99 255 / 45%);
Then update the graphite block in _themes.css:
/* src/styles/tokens/_themes.css, inside [data-am-theme='graphite'] */
--am-accent-text: var(--am-brand-300);
--am-accent-soft: var(--am-brand-wash-dark);
--am-accent-soft-ink: var(--am-brand-300);
--am-accent-glow: rgb(108 99 255 / 40%);
--am-focus-ring: rgb(108 99 255 / 55%);
Finally, in _charts.css, set --am-chart-1 and
--am-preset-accent to your color if you want the charts to follow.
#Edit the graphite theme
The graphite (dark) theme is the [data-am-theme='graphite'] block
in _themes.css. It redefines the surfaces, the ink, the text forms of the
signal colors, and the light and shadow values. Edit any value there. The chart colors
for graphite are at the bottom of _charts.css.
#Add a new theme
You can add a third theme, for example a warm sand color.
1. Add a block to _themes.css. Redefine at least the
surfaces, the ink and the shadows. Copy the graphite block as a start:
[data-am-theme='sand'] {
--am-bg: #e6dfd3;
--am-surface: #f4efe7;
--am-surface-top: #f8f4ee;
--am-surface-bottom: #efe8dd;
--am-surface-2: #ece5d9;
--am-key-top: #fbf8f3;
--am-key-bottom: #f0eadf;
--am-key-edge: #d3c8b6;
--am-inset: #dad0c0;
/* ...the ink, light and shadow roles if they change */
}
2. Add the value to the mode axis in
src/lib/theme.ts:
mode: {
attr: 'data-am-theme',
key: 'theme',
def: 'light',
values: ['light', 'graphite', 'sand', 'system'],
},
3. Add a button for it in the Appearance drawer. In
src/components/shell/Customizer.tsx, add
{ value: 'sand', label: 'Sand' } to the options of the
mode row.
The theme script in index.html already accepts any saved value, so it
needs no change.
#Chart colors
The six chart colors are --am-chart-1 to --am-chart-6 in
_charts.css. Graphite changes some of them at the bottom of the same
file. Charts read these values when they draw and again when the theme changes. See
Charts.
#Fonts
Atmosphere uses two fonts from Google Fonts:
| Font | Used for | Weights |
|---|---|---|
| Gabarito | Titles and large numbers | 800, with letter spacing of -0.03em |
| Onest | All other text, 14px by default | 400 to 700 |
They are loaded in index.html and named in _typography.css.
#Use different fonts
-
In
index.html, replace the Google Fonts<link>with the link for your fonts. - In
src/styles/tokens/_typography.css, change the font names:
--am-font-display: 'Your Display Font', system-ui, sans-serif;
--am-font-body: 'Your Body Font', system-ui, sans-serif;
#Host the fonts yourself
To load no files from Google, for example for privacy rules:
-
Download the font files (
.woff2) and put them inpublic/fonts/. -
Remove the three Google Fonts lines from
index.html: the twopreconnectlinks and the stylesheet link. - Add
@font-facerules tosrc/styles/base.css:
@font-face {
font-family: 'Onest';
src: url('/fonts/Onest-Variable.woff2') format('woff2');
font-weight: 400 700;
font-display: swap;
}
@font-face {
font-family: 'Gabarito';
src: url('/fonts/Gabarito-Variable.woff2') format('woff2');
font-weight: 500 900;
font-display: swap;
}
Keep the same family names and the tokens need no change.
#The type scale
| Token | Size | Used for |
|---|---|---|
--am-text-2xs |
10.5px | Sidebar key labels |
--am-text-xs |
11.5px | Timestamps, chart labels |
--am-text-sm |
12.5px | Captions, legends |
--am-text-md |
13px | Chips, tabs, small keys |
--am-text-base |
14px | Body text, buttons, table cells |
--am-text-lg |
17px | Card titles |
--am-text-xl |
22px | Small values |
--am-text-2xl |
25px | Section headings |
--am-text-3xl |
34px | Page titles |
--am-text-4xl |
40px | Large numbers on number cards |
To make all text larger, change --am-text-base and the steps near it.
#Shape and spacing
| Token | Value | Used for |
|---|---|---|
--am-radius-xs |
8px | Checkboxes |
--am-radius-sm |
11px | Pagination keys, priority pills |
--am-radius-md |
14px | Buttons, inputs, table rows |
--am-radius-frame |
16px | Tab frames, sidebar keys |
--am-radius-lg |
18px | Scenes, toasts, alerts |
--am-radius-xl |
26px | Cards |
--am-radius-2xl |
30px | The sidebar |
--am-radius-pill |
999px | Knobs, LEDs, badges |
Spacing uses a 4px step: --am-space-1 is 4px and
--am-space-12 is 48px.
#Depth and shadows
All depth comes from a few shadow tokens in _roles.css:
--am-raise for raised panels, --am-well,
--am-well-sm and --am-well-xs for wells,
--am-key-1 to --am-key-4 for keycaps, and
--am-float for menus and dialogs. They are built from one light
direction, --am-lx, so the light source setting can flip
every shadow at once.
To make the whole interface flatter or deeper, change the shadow color roles instead of each shadow:
| Role | What it is |
|---|---|
--am-hi |
The highlight on the lit side |
--am-lo |
The shadow on the dark side |
--am-well-lo, --am-well-hi |
The two sides of a carved well |
--am-gloss |
The thin bright line on top of raised surfaces |
#Tailwind CSS
Tailwind CSS v4 is set up, and its utilities read the same tokens. The bridge is the
@theme inline block at the end of src/styles/app.css. So
these utilities follow the theme:
| Utility | Uses |
|---|---|
bg-bg, bg-surface, bg-surface-2,
bg-inset
|
The surface roles |
text-ink, text-ink-2, text-ink-3 |
The ink roles |
text-accent-text, text-good-text,
text-bad-text
|
The safe text forms of the signal colors |
rounded-md, rounded-xl, rounded-pill
|
The radius tokens |
font-display, font-body, font-mono
|
The font tokens |
text-sm, text-base, text-3xl |
The type scale |
p-4, gap-5, mt-6 |
The 4px spacing step |
<div className="flex items-center gap-3 rounded-xl bg-inset p-4 text-ink-2">...</div>
Use Tailwind for layout inside pages. The look of each component is in
components.css, so you can change a component in one place.
#The logo
The logo is drawn in code, so it changes color with the theme:
-
src/components/ui/Mark.tsxdraws the logo key in the sidebar and on the sign-in pages. Replace the two<path>elements with your own SVG paths, drawn on a 24 by 24 grid. public/favicon.svgis the browser tab icon.-
The name that screen readers hear for the logo key comes from
building.systeminsrc/data/demo/building.json.
To use an image file instead, put it in public/ and change
Mark to render
<img src="/logo.svg" alt="" /> inside the key.