Theming

1. Theme variables. Every colour, border, shadow and radius the editor and its UI use is a CSS custom property --nb-*. Import a theme, or set the variables you care about.
2. Redraw a block. Replace the Svelte component that draws one block type (the heading, the callout...) and keep everything else: the data, the keyboard, the markdown.
3. Your own blocks. A new block type with its own component: Extensions.

Level 1: theme variables

The base theme

import '@aionbuilders/nabu/nabu-theme.css';

<html data-nabu-theme="dark">

The Atelier theme

<script>
  import '@aionbuilders/nabu/themes/atelier.css';
  import { NabuEditor, createDocumentEditor } from '@aionbuilders/nabu';
  import { FloatingToolbar, SlashMenu, DragHandle } from '@aionbuilders/nabu/ui';

  const engine = createDocumentEditor();
</script>

<div class="nb-theme-atelier" data-nb-scheme="dark">
  <FloatingToolbar {engine} />
  <SlashMenu {engine} />
  <DragHandle {engine} />
  <NabuEditor {engine} />
</div>

• The scope. Everything the theme does happens under the class .nb-theme-atelier: nothing outside it is touched, and the base theme's values are overridden inside it. Put the class on an ancestor of the editor and of its floating UI (toolbar, slash menu, drag handle, command surfaces): they are rendered where you mount them and read their colours from the nearest scope.
• The scheme, data-nb-scheme on the same element: "dark" (the default when absent), "light", or "auto" to follow prefers-color-scheme.
• The pane. The editor element becomes a bordered surface with a radius and padding. Tune it with --atelier-pane-padding (default 36px 40px, 24px 20px below 760 px), --atelier-pane-radius (16px), --atelier-font-size (16px), or set --atelier-pane: transparent and remove the border to blend the editor into your own surface.
• Browser support. The theme uses light-dark() and color-scheme (Chrome 123, Firefox 120, Safari 17.5).

.nb-theme-atelier {
  --atelier-accent: light-dark(#0b57d0, #8ab4f8); /* the accent: caret, links, focus rings */
  --nb-floating-radius: 4px;
}

Fonts

import '@fontsource/inter/400.css';
import '@fontsource/inter/600.css';
import '@fontsource/syne/700.css';
import '@fontsource/jetbrains-mono/400.css';

.nb-theme-atelier {
  --nb-font-text: 'Source Serif 4', Georgia, serif;
  --nb-font-heading: var(--nb-font-text);
}

Layout variables

.editor {
  --nb-paragraph-indent: 1.5em; /* a novel */
  --nb-dialogue-dash: '—';
}

Reference of the variables

.nabu-editor .nabu-callout.callout-tip { --callout-accent: #15803d; }

Style a block with CSS

.editor .nabu-editor h2[data-block-type='heading'] {
  font-family: Georgia, serif;
  letter-spacing: -0.01em;
}

Level 2: redraw a block

import { createDocumentEditor, HeadingExtension } from '@aionbuilders/nabu';
import { extension } from '@aionbuilders/nabu/extend';

function MyHeading() {} // stands for a Svelte component, defined below

const engine = createDocumentEditor({
  extensions: [extension('heading', { component: MyHeading })]
});

// The type is drawn by your component...
expect(engine.components.get('heading')).toBe(MyHeading);
// ...and is still the built-in class: same data, same markdown.
expect(engine.registry.get('heading')).toBe(HeadingExtension.block);

await engine.importMarkdown('## A title');
expect(engine.children[0].type).toBe('heading');
expect(engine.serialize('markdown')).toBe('## A title');

<!-- MyHeading.svelte -->
<script>
  import { RichText } from '@aionbuilders/nabu/extend';

  let { block } = $props();
</script>

<svelte:element
  this={'h' + block.level}
  bind:this={block.element}
  data-block-id={block.id}
  data-block-type="heading"
  data-placeholder={block.placeholder}
  class="my-heading"
  class:selected={block.selected}
><RichText delta={block.delta} /></svelte:element>

<style>
  .my-heading {
    white-space: pre-wrap;
    font-family: var(--nb-font-heading, Georgia, serif);
    margin: 1.2em 0 0.4em;
  }
  h1.my-heading { font-size: 2.2em; }
  h2.my-heading { font-size: 1.6em; }
</style>

import MyHeading from './MyHeading.svelte';

const engine = createDocumentEditor({
  extensions: [extension('heading', { component: MyHeading })]
});

• The properties a component can read are those of the block class: block.level for a heading, block.variant for a callout, block.collapsed for a toggle... Read the built-in component in the source of the package (dist/blocks/<type>/) as the model; a block that holds children (list, toggle, callout, region) renders them with BlockComponent, exported from @aionbuilders/nabu/extend.
• A custom component for a media block should handle block.status === 'missing' (the bytes of the file are not available); see the files section of the persistence guide.
• Changing the component does not change the markdown, the HTML paste, the commands or the slash menu entries: those belong to the class and the extension. To change them too, write your own block.

Level 3: your own blocks

Gaps

• No dedicated editor option for component overrides: it goes through an extension that reuses the name of the built-in one (and engine.components, a map on the engine, is what holds the result). A first-class components: { heading: MyHeading } option would be clearer.
• The base theme does not define --nb-link, --nb-text-placeholder, --nb-error or the floating UI variables; they come from fallbacks in the components (a blue link of 2.7:1 on a white page, for instance: set --nb-link on light pages, see Accessibility).
• --nb-border-focus, --nb-success, --nb-warning, --nb-danger, the shadows and the blur are defined by the themes but no built-in component reads them (yet): they are there for your own UI.
• Two scheme switches exist: data-nabu-theme for the base theme and data-nb-scheme for Atelier. They are independent, and inside an Atelier scope only the Atelier one applies.