Skip to content
DocsStyle
Style

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-accent is a fill. Use it for a button, an LED or a chart line.
  • --am-accent-text is 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:

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:

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:

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:

CSS
[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:

TypeScript
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

  1. In index.html, replace the Google Fonts <link> with the link for your fonts.
  2. In src/styles/tokens/_typography.css, change the font names:
CSS
--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:

  1. Download the font files (.woff2) and put them in public/fonts/.
  2. Remove the three Google Fonts lines from index.html: the two preconnect links and the stylesheet link.
  3. Add @font-face rules to src/styles/base.css:
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
TSX
<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 is drawn in code, so it changes color with the theme:

  • src/components/ui/Mark.tsx draws 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.svg is the browser tab icon.
  • The name that screen readers hear for the logo key comes from building.system in src/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.