Theme settings
Every key a theme can hold, grouped by layer. Each key will also be a CSS variable: color.accent
as --color-accent, radius.card as --radius-card. Today the colour variables keep the old app’s
names (see The file today).
The theme document
| Key | Holds |
|---|---|
version |
the file version |
contract |
the name-tag contract version the theme was written for |
base |
the theme it builds on, for example kaizendex.light or a Library theme (optional) |
palette |
ingredients: your colours |
fonts |
ingredients: your fonts |
scale |
the three quick knobs |
color, text, space, radius, shadow, motion, width |
meanings |
background |
the main background |
parts |
the default look of each name tag |
moments, recipes |
effects and your saved effect recipes |
icons, haptics, sounds, transitions, emptyStates, emoji |
the modular parts |
when |
screen-size and other condition rules |
A theme stores only what you changed. A key you leave out uses the base. A key set to null goes back
to the base value.
The file today
Settings/theme.json is { "version": 2, "themes": [...], "preferences": {...} }. Each theme has
id, name, type (light or dark) and the layers. The old app’s names map like this:
| Old app | In theme.json |
CSS variable today |
|---|---|---|
colour background, foreground, surface, surface-foreground |
color.background, color.text, color.surface, color.surfaceText |
--color-background, --color-foreground, … |
colour muted, muted-foreground |
color.muted, color.textMuted |
--color-muted, --color-muted-foreground |
colour primary, primary-foreground |
color.accent, color.accentText |
--color-primary, --color-primary-foreground |
colour accent, accent-foreground (the hover fill) |
color.hover, color.hoverText |
--color-accent, --color-accent-foreground |
colour ring, link, border, border-strong |
color.focus, color.link, color.border, color.borderStrong |
--color-ring, --color-link, … |
colour success, warning, destructive, info |
color.success, color.warning, color.danger, color.info |
--color-destructive for danger |
fonts sans, mono, display, heading, numeral |
fonts.body, fonts.code, fonts.display, fonts.heading, fonts.number |
--font-sans, … |
type scale caption, meta, body, title, heading, h2, h1, display |
text.caption, text.bodySmall, text.body, text.title, text.heading3, text.heading2, text.heading1, text.display, each { "size", "lineHeight" } |
--text-<old name> |
| density | scale.space (compact, comfortable) |
|
control groups (checkbox, table, navigation, page, panel, scrollbar, …) |
parts.<group>; the checkbox uses borderWidth, borderColor, background |
|
region colours "sidebar.primary" |
parts.sidebar.accent (other keys such as chart-1 keep their names) |
|
| wallpaper, chat background, celebration, base theme | background: { "fill": "image", "image": … }, parts.chats.wallpaper, moments["checkbox.tick"], base |
|
| icons, glass, deck | icons, glass, deck |
|
scale (text size, corners) |
scale.text (80–140), scale.round (sharp, soft, round, veryRound) |
every --text-* size; --radius-* and the control, button and panel corners |
motion |
motion.level (off, calm, normal, extra) |
html[data-motion-level] |
moments (all but a plain tick) |
moments.<name>.effect |
|
otherSide |
the other side of each { "light", "dark" } colour |
the theme in the other mode |
recipes |
recipes.<name> (effect, count, colors); a moment names one as its effect |
A colour can be one value or { "light": …, "dark": … }. A theme shows its own side (type) and,
when it has pairs, the other side in the other mode. Keys the old app has no place for (a one-sided
pair, a text style’s weight) stay in the file when you edit the theme.
Layer 1: ingredients
The raw values. Meanings point to them.
| Ingredient | What it is | Example |
|---|---|---|
| palette | named colours, each with a light and a dark value |
palette.sunset, used as var(--palette-sunset) |
| fonts | built-in fonts, or font files you upload (asset:…) |
"body": "Inter", "heading": "asset:fraunces" |
| size steps | the text size steps | not decided yet |
| spacing steps | 2, 4, 6, 8, 12, 16, 24, 32, 48, 64 | space.cardPadding uses step 4 |
| roundness steps | corner radius steps | not decided yet |
| shadow steps | shadow strengths | not decided yet |
| animation speeds | how fast motion runs | not decided yet |
The key names for the size, roundness, shadow and speed steps are not decided yet.
Layer 2: meanings
What each value is for. Most themes change only these.
| Group | Keys |
|---|---|
Colours (color.*) |
background, surface, surfaceText, surfaceRaised, overlay, muted, hover, hoverText, text, textMuted, textFaint, border, borderStrong, accent, accentText, success, warning, danger, info, focus, selection, highlight, searchHighlight, link, chart1 to chart12 |
Text (text.*) |
body, bodySmall, label, caption, title, heading1, heading2, heading3, display, number, code |
| Fonts | font.body, font.heading, font.display, font.number, font.code |
Spacing (space.*) |
page, section, gap, cardPadding, controlPadding, rowHeight, controlHeight |
Shapes (radius.*) |
control, card, panel, dialog, chip |
| Depth | shadow.card, shadow.menu, shadow.dialog, shadow.toast, blur.glass |
Motion (motion.*) |
fast, normal, slow, ease, bounce, celebrate, and level |
Widths (width.*) |
form, reading, page, board, content |
Every colour has a light and a dark value. The app picks the right one.
Each text style has a size, line height, weight, letter spacing and font. Sizes are plain numbers in pixels. Grouped values are objects, never shorthand strings:
{ "text": { "body": { "size": 15, "lineHeight": 1.5 } } }motion.level is one knob for all effects: off, calm, normal or extra.
The quick knobs
| Key | Values |
|---|---|
scale.text |
80 to 140 (percent) |
scale.space |
compact, comfortable, spacious |
scale.round |
from sharp to very round (for example round); the full list of steps is not decided yet |
The background
The same shape works on app.background, the sidebar, pages, views, dashboards, blocks and cards.
| Key | Values |
|---|---|
fill |
theme, color, gradient, image, clear (nothing, so what is behind shows), and glass (frosted) on the sidebar, pages and cards |
color |
a colour, for fill: color |
from, to |
the two colours, for fill: gradient |
image |
an uploaded file (asset:…), never a web link |
fit |
cover, contain or tile |
position |
where the image sits |
dim |
how much to darken the image |
blur |
how much to blur the image |
The sidebar, pages and cards can each be solid, glass (frosted) or clear. Text on a background always gets the theme’s contrast check.
Layer 3: parts
parts sets the default look of any name tag. The most used:
| Tag | Settings |
|---|---|
checkbox |
shape (square, rounded, circle, or an uploaded SVG), size, border, fill when ticked (checkedFill), mark (check, dot, cross, heart, star, or an uploaded SVG) |
button and its kinds |
background, text, border, radius, padding, height, font weight, icon size, hover, pressed, disabled |
input and its kinds |
height, background, border, radius, padding, focus ring, placeholder colour, the picker’s look, the rating’s symbol |
select, menu |
trigger look, list background, item height, item radius, icon size, check mark, separator, shadow, search box, how it opens |
dialog and its kinds |
width, radius, padding, background, overlay colour and blur, how it opens and closes, header and footer look |
toast and its kinds |
position, width, background per kind, icon, radius, shadow, how it enters and leaves, how long it stays, how many stack |
sidebar |
width, background, font, row height, spacing, icon size, the current page’s look, section titles, how it collapses |
tag |
shape, padding, font, colours per tag colour |
tabs, tooltip, infoHint, scrollbar, dragHandle, focusRing |
sizes, colours and motion |
tabs.bar (the one tab bar of collection, global collection and hub pages) |
the tab look, the link mark (↗), the More ▾ menu, the + button, truncate and overflow |
label (the icon and the name) |
what shows (show), icon size, truncate |
| every label tag | truncate: how long text is cut (see below) |
card, row, and each view’s (feed.card, board.card, list.row, …) |
padding, radius, background, border, shadow, hover, the default layout |
page, entryPage, collectionPage, hubPage |
background, width, padding, header look |
grid |
the gap between tiles, the look of each tile, and the smallest tile that may show another entry’s Dashboard property (see below) |
block and its kinds |
the block’s frame; a chart’s colours come from color.chart1 to chart12 unless set |
The exact key name of each setting is not decided yet, except where the plan’s examples show one
(shape, size, mark, checkedFill, position, radius, background, width) and the
settings below (truncate, overflow, show, and the scroll bar’s keys).
Scroll bars: scrollbar
Every theme starts with Notion’s scroll bar, the simple style: one thin bar, the same on every
surface (pages, the feed, chats, Settings, dialogs, menus, text boxes and a table’s sideways bar). It
has no arrow buttons. It shows while you point at that area or scroll it, in two theme colours, and
grows a little under the pointer. Each page has one bar, along its right edge, under the page’s
header row. Tab rows have none.
| Key | What it sets | Default |
|---|---|---|
parts.scrollbar.thumb |
the part you drag (--color-scrollbar-thumb) |
the theme’s quiet text colour (color.textMuted) at 50% |
parts.scrollbar.track |
the groove behind it (--color-scrollbar-track) |
clear |
parts.scrollbar.style |
the bar’s look | simple; or one of the older looks: dots, pill, groove, capsule, hatch, thin, native |
The two colours are hex values, such as "thumb": "#a8a29e". The older looks keep their own
colours and sizes. You can also pick the look in Settings → Appearance → Scrollbars → Style.
Long text: truncate and overflow
Every label tag has a truncate setting. A label tag is a tag that shows a name or a short
text: a tab, a sidebar row, a chip, a button, a table cell, a menu item, a breadcrumb item, a
card title, and the label tag itself. The rules behind it are on
When text is too long.
| Key | What it does | Values | Built-in theme |
|---|---|---|---|
truncate.lines |
how many lines the text may take before it is cut | 1 to 6 | 1 for labels; card titles use the card’s own setting |
truncate.cut |
where the text is cut | end · middle · start · none (never cut) |
end; middle for file names and ids |
truncate.minWidth |
the narrowest the label may get before it is cut | pixels (80) or characters ("6ch", six characters wide) |
not decided yet |
truncate.marker |
the sign that shows the cut | any short text | "…" |
overflow (on tabs.bar only) |
what happens when the tabs do not fit | menu (the More ▾ menu) · scroll · wrap (two rows) |
menu |
{ "parts": { "tabs.bar": { "truncate": { "lines": 1, "cut": "end", "minWidth": "6ch" }, "overflow": "menu" } }}Names and icons: the label tag
The label tag is the one icon-and-name control. It sits inside every tab, every sidebar row,
every title, and the small header of an Entry block that shows one property. Its pieces are
icon and name.
| Key | What it does | Values |
|---|---|---|
show |
what the label shows | both (icon and name) · icon · name |
The theme sets what shows by default. You can still choose for one tab, row, hub or collection in its own icon-and-name control. An entry page title always shows its name.
This theme shows only icons in tabs and sidebar rows. Entry page titles still show their names.
{ "parts": { "label": { "show": "icon" } } }Embeds in a Dashboard
An Entry block can show one property of an entry. When that property is a Dashboard, such as a
dashboard’s Dashboard property, it needs room for its own tiles. So grid has a setting for the smallest tile
that may show it. A Block page shown this way has no smallest tile.
| Setting | Built-in theme | In a smaller tile |
|---|---|---|
| the smallest tile for a Dashboard shown as one property | 6 columns wide and 4 rows high | the entry shows as its card |
The key name is not decided yet. On a phone, tiles are full width, so this setting does not apply there. The depth limit (3 levels) and the loop rule apply to a Dashboard and a Block page. They are not theme settings. See Blocks and charts.
Moments and modular parts
moments holds one effect per moment. See Moments for every
moment, effect and recipe.
| Key | What it decides | Default |
|---|---|---|
icons |
the icon set, stroke width and size | the house set |
haptics |
the phone vibration per moment: none, light, medium, success, warning | light on tick, success on all done, warning on error |
sounds (later) |
a sound per moment, from a built-in pack or an uploaded short sound | off |
transitions |
how pages, peeks, sheets and dialogs open and close | a quick fade and slide |
emptyStates |
what an empty view shows: nothing, a short line, or a picture | a short line |
emoji |
the system’s emoji, or one built-in emoji style | the system’s |
A full example
{ "version": 1, "contract": 1, "base": "kaizendex.light", "fonts": { "body": "Inter", "heading": "asset:fraunces" }, "scale": { "text": 105, "space": "comfortable", "round": "round" }, "color": { "accent": "var(--palette-sunset)" }, "text": { "body": { "size": 15, "lineHeight": 1.5 } }, "background": { "fill": "image", "image": "asset:mountains", "fit": "cover", "dim": 20 }, "parts": { "checkbox": { "shape": "circle" }, "toast": { "position": "top", "radius": "var(--radius-panel)" }, "toast.error": { "background": "var(--color-danger)" }, "sidebar": { "background": { "fill": "glass" }, "width": 260 }, "tabs.bar": { "truncate": { "minWidth": "6ch" }, "overflow": "scroll" }, "dialog.newEntry": { "width": 560 } }, "moments": { "entry.delete": { "effect": "dust" }, "checkbox.tick": { "effect": "pop" } }, "motion": { "level": "normal" }}