Compatibility
Start an Atlas theme from a shadcn or tweakcn theme.
Atlas's base tokens are the shadcn/ui token set, verbatim. The names, and what each one means, are unchanged.
So a shadcn theme, or anything generated by a tool that targets shadcn such as tweakcn, is already most of an Atlas theme. The work is mechanical.
Atlas will do this conversion for you. Settings → Appearance → Import takes a shadcn registry item or a pasted globals.css and writes the theme file, along with a report of what it kept and what it had to invent. See importing a theme. This page is the same conversion by hand, and explains what the format can and cannot say.
Convert the tokens
A shadcn theme is CSS custom properties in a :root block and a .dark block. Atlas wants the same names without the leading --, as TOML keys under [light.base] and [dark.base].
.dark {
--background: #08070a;
--foreground: #e0def4;
--card: #18151e;
--primary: #eb6f92;
--radius: 8px;
}[dark.base]
background = "#08070a"
foreground = "#e0def4"
card = "#18151e"
primary = "#eb6f92"
radius = "8px"In shadcn, :root is the light theme and .dark is the dark one, so they become [light.base] and [dark.base] respectively. Carry both across if your source has both: Atlas's Light and System modes are on, and a theme with one variant is used for the other as well.
Atlas accepts oklch() as well as hex, rgb(), and hsl(), so a tweakcn export usually pastes straight across.
Older shadcn themes write bare HSL channels, as in --background: 0 0% 100%. Atlas needs a complete color, so wrap those: background = "hsl(0 0% 100%)".
Leave out what your source does not have
No base token is required. A shadcn theme normally covers the colors, radius, the charts, and the sidebar family, and often not tracking-normal, spacing or the shadow ramp. Anything it leaves out, Atlas derives from background, foreground and primary, or takes from its own defaults for the appearance, so there is nothing to copy across.
Keep font-sans, font-serif and font-mono if your source has them: a theme that names fonts uses them for anyone whose font settings are on their defaults. Drop anything else your source emits that is not a base token. Atlas rejects a base token it does not recognize, and a generator's extra variables are the usual reason a converted file will not load.
Share tokens between light and dark
shadcn keeps tokens that do not change with the appearance, such as the radius and the fonts, in cssVars.theme. Atlas has the same thing: a top-level [base] table, read by both variants. A variant's own [dark.base] or [light.base] wins over it.
[base]
font-sans = "Montserrat, sans-serif"
font-mono = "\"Fira Code\", monospace"
radius = "8px"
[dark.base]
background = "oklch(0.2155 0.0254 284.0647)"
# …What the conversion gives you
Everything the base tokens reach, which is most of the window: the app background, panels, the rail, tabs, cards and popovers, borders, the focus ring, the signature color, the editor background and default text, selections, charts, the radius scale, the elevation, and the fonts if your source names them.
That is a complete, working theme. It will load and it will look like your palette. A source with only a few tokens works too: as little as background and primary is enough.
Two shadcn tokens carry more weight in Atlas than they do in a web app, so give them a second look. chart-1 through chart-5 are five series that have to stay tellable apart, since two that differ only slightly render as one line. And ring is a real accent, used for the focus ring and the matching-bracket outline, so a ring set to a gray leaves the editor without one.
What a shadcn theme cannot say
A shadcn token set describes an interface. Atlas keeps its names exactly, so the tokens you converted sit inside the larger set Atlas colors from, and everything outside them is worked out rather than asked for.
It has no vocabulary for the things a code tool needs:
- Syntax highlighting. No keyword, string, type, or comment color.
- Terminal ANSI colors. No red, green, yellow, blue, magenta, or cyan.
- Diff tints. No addition or removal color.
- Status hues. No success, warning, or informational color beyond
destructive. - Search highlights. No match color.
Atlas will derive all of them rather than leave them unstyled, but with nothing to derive from it falls back to its own defaults, and those will not match your theme.
Add a palette. Eight lines fix all five groups at once:
[dark.palette]
red = "#eb6f92"
orange = "#ebbcba"
yellow = "#f6c177"
green = "#31748f"
cyan = "#9ccfd8"
blue = "#9ccfd8"
purple = "#c4a7e7"
pink = "#ebbcba"This is the single step that turns a converted interface theme into an Atlas theme. The names are hues rather than slots, and everything downstream trusts them, so file each color under the name it actually is.
See the token reference for what each hue feeds. After the palette, the keys worth adding by hand are the fifteen syntax roles and the ten editor keys. No built-in theme sets a terminal, status, search, or agent key at all, because a good palette already gets those right.
What Atlas does with the extras
Three tokens come along with a shadcn or tweakcn theme and behave differently from the rest:
spacing. Atlas's density is designed around Tailwind's default0.25rem, and every built-in theme uses it. Keep that value unless a different density is what you are after.tracking-normal. Part of the set, and Atlas does not currently read it.- The shadow ramp. Atlas renders three elevations:
shadow-smraised,shadow-2xlfor menus and popovers, andshadow-xlstacked beneathshadow-2xlfor dialogs. The other four shadow tokens are unused, so do not spend time tuning them.
Next
- Authoring a theme: iterate on the result
- Importing a theme: let Atlas convert it instead
- Token reference: where to start, then every token and key