Theming
The four views, light and dark mode, the theme API, the CSS files of @gotipe/theme and how to pass your application's colours through --gt-* tokens.
The colours, fonts, sizes and radii of the ready editors are --gt-* custom properties. A view (notion, docs, modern, minimal) is a set of these tokens over the same markup, and light and dark are two palettes of them. You change the look by overriding tokens, not by replacing stylesheets.
Install
npm install @gotipe/themepnpm add @gotipe/themeyarn add @gotipe/themebun add @gotipe/theme| File | Contents |
|---|---|
@gotipe/ |
The document in every view: text, blocks, lists, tables, code, print and reduced-motion rules |
@gotipe/ |
Menus, panels, review cards and the loading, error and read-only states |
@gotipe/ |
Only the tokens: light and dark palettes and the views |
@gotipe/ |
base.css and theme.css in one import, kept for older imports |
import "@gotipe/theme/base.css";
import "@gotipe/theme/theme.css";@gotipe/block-editor/styles loads base.css and theme.css, everything BlockEditor and PageEditor draw. The headless MIT packages ship no CSS; with them, style .gotipe-content yourself or use tokens.css for your own UI.
Views
Pass view to BlockEditor or PageEditor; it becomes data-gt-view on the editor root.
| View | Column | Body | Title | Also |
|---|---|---|---|---|
notion (default) |
680 px | 15/24 px | 32 px | Block handle in the gutter |
docs |
680 px | 14/22 px | 28 px | Outline of headings beside the text, line numbers in code, block handle in the gutter, # anchor after each heading |
modern |
680 px | 15/24 px | 28 px | Less space above the title, no handle |
minimal |
640 px | 14/22 px | 22 px | Tighter spacing and 24 px side padding, no handle |
The editor root is a size container. In a container 640 px wide or less, the side padding, heading sizes and title shrink and the docs outline hides; at 359 px or less they shrink again. There notion and docs keep a rail of --gt-handle-rail (56 px) on the left for the block handle. In docs, --gt-outline-gap (64 px) is the gutter the handle stands in, --gt-anchor-display shows the heading anchors (none hides them) and --gt-anchor-room is the room a heading keeps for its anchor at the end of its lines. --gt-heading-wrap is how headings wrap: balance, so the last line is not one lone word, and pretty in docs, where a balanced heading would carry its anchor away; the page title wraps balanced in every view. The editor takes its width from its parent: in a layout that sizes by content, give the parent a width.
Light and dark
The light palette is declared on :root and [data-theme="light"], the dark one on [data-theme="dark"]. When <html> has no data-theme, the dark palette follows prefers-color-scheme: dark. Any element with data-theme gets its own palette, so an editor inside a dark panel can be dark on a light page.
@gotipe/theme manages the attribute for you:
import { getTheme, onThemeChange, setTheme } from "@gotipe/theme";
const stopFollowing = setTheme("system"); // follows the OS until you choose light or dark
const unsubscribe = onThemeChange((mode, resolved) => console.log(mode, resolved));
console.log(getTheme()); // { mode: "system", resolved: "dark" }| Function | Description |
|---|---|
set |
"light", "dark" or "system" on root (default <html>). Sets data-theme and the palette. Returns a cleanup that stops following the OS. |
getTheme(root?) |
{ mode, resolved } for that root. Safe during server rendering. |
on |
Calls listener( after each change; returns an unsubscribe function. |
apply |
Writes config.tokens as --gt-* properties on root; keys without the prefix get it. |
define |
Returns config typed as ThemeConfig. |
lightTheme, darkTheme |
The palettes as ThemeConfig objects. |
Each root keeps its own mode and listeners. ThemeToggle from @gotipe/block-editor is a three-way switch that always acts on <html>; BlockEditor shows it with showThemeToggle.
Your colours
Colours, fonts, radii and shadows inherit. Set them on a container around the editor, and they reach the text, the menus and the review cards. Sizes belong to the view, so override them on the editor root itself:
.app-editor {
--gt-page-bg: var(--app-canvas);
--gt-text: var(--app-text);
--gt-text-2: var(--app-text-muted);
--gt-line: var(--app-border);
--gt-accent: var(--app-brand);
--gt-focus: var(--app-focus-ring);
--gt-selection: var(--app-selection);
--gt-font-ui: var(--app-font);
--gt-font-mono: var(--app-font-mono);
--gt-radius-control: var(--app-radius);
}
/* setTheme always sets data-theme, also in "system" mode */
[data-theme="dark"] .app-editor {
--gt-accent: var(--app-brand-dark);
}
/* The editor root carries the view; this also reaches the root inside PageEditor. */
.app-editor .gotipe-block-editor {
--gt-page-width: 760px;
--gt-body-size: 16px;
}Menus that open outside the editor, such as the formatting bubble and the table menus, render in a layer on <body>. That layer copies the editor's computed --gt-* values, font, colour scheme and direction, so tokens you set on a container apply there too.
| Group | Tokens |
|---|---|
| Surfaces and text | --gt-page-bg, --gt-sunken, --gt-overlay, --gt-text, --gt-text-2, --gt-text-3, --gt-fill-1…3 |
| Lines and accents | --gt-line, --gt-line-strong, --gt-line-control, --gt-line-active, --gt-ink, --gt-accent, --gt-focus, --gt-selection |
| States | --gt-success, --gt-warning, --gt-danger, --gt-comment and their -tint forms |
| Type and shape | --gt-font-ui, --gt-font-mono, --gt-radius-control, --gt-radius-overlay, --gt-shadow-overlay |
| Document colours | --gt-tc-gray … --gt-tc-blue (text), --gt-bg-yellow … --gt-bg-gray (highlight) |
| Code and review | --gt-syn-keyword, --gt-syn-string, --gt-syn-number, --gt-syn-type, --gt-syn-comment, --gt-syn-punct; --gt-track-1…6 |
| View sizes | --gt-page-width, --gt-page-pad-x, --gt-body-size, --gt-body-leading, --gt-title-size, --gt-h1-size… |
All tokens come from one source, design-tokens.json in the GoTipe repository; the CSS files and the JS palettes are generated from it.
Text and highlight colours in a document store the colour for a light page, so exports print them as written. The editor draws a palette colour through its --gt-tc-* or --gt-bg-* token, so it follows dark mode and your overrides.
Limitations
setThemewrites the whole palette as inline custom properties on its root. Overrides in a stylesheet on that same element lose to them; put yours on a container inside it.- Under a Content Security Policy,
style-srcneeds'unsafe-inline': menu and cursor positions, lane colours and cell alignment arestyleattributes. - The stylesheets use physical left and right; right-to-left layout is not supported.
@gotipe/themethemes with tokens only. It has no icon-set or component-override API (defineIconsandThemeConfig.componentOverrideswere removed before they did anything); to change how a block looks, passblockViewsto the editor.