@surrealdb/ui

The SurrealDB UI Kit defines the design system and UI primitives for use throughout all frontend projects at SurrealDB.

DESIGN.md describes the design system. MIGRATE.md is the guide for porting a project from 1.x.

Using the UI Kit

First, import the styles and fonts:

import "@surrealdb/ui/styles.css";
import "@surrealdb/ui/fonts.css";

Then, configure the Mantine theme. The CSS variables resolver is required: it is what lets any subtree switch color scheme on its own.

import { MantineProvider } from "@mantine/core";
import { MANTINE_THEME, surrealCssVariablesResolver } from "@surrealdb/ui";

<MantineProvider
	theme={MANTINE_THEME}
	cssVariablesResolver={surrealCssVariablesResolver}
>
	<App />
</MantineProvider>;

Finally, use the components:

import { Display, Eyebrow, Muted, Section } from "@surrealdb/ui";

<Section
	tone="purple"
	size="lg"
>
	<Eyebrow>Get started</Eyebrow>
	<Display size="xl">
		One engine. <Muted>Every data model.</Muted>
	</Display>
</Section>;

A region takes a product color by stamping it on any ancestor, which recolors everything inside including plain Mantine controls:

<Section accent="memory">…</Section>

Markdown editing and rendering

The UI Kit ships a markdown library built on a simplified, opinionated MDX variant (CommonMark + GFM + GFM-style callouts + <PascalCase /> JSX components). It exposes two primitives that share one Lezer grammar: MarkdownEditor, a CodeMirror 6 live-preview editor, and MarkdownViewer, an SSR-safe read-only renderer. They can be used together (an editor beside a live preview) or entirely independently.

import { MarkdownEditor, MarkdownViewer } from "@surrealdb/ui";

// Read-only rendering
<MarkdownViewer content="# Hello\n\nSome **markdown**." />

// Interactive editing
<MarkdownEditor document={source} onChangeDocument={setSource} mode="preview" />

See src/lib/markdown/SPEC.md for the full specification.

Getting Started

To install dependencies:

bun install

Start the Storybook development server:

bun run storybook:dev

Icon tool

The icon tool is used to convert the SVG icons to a format that can be used in the UI Kit.

Requirements

• Install picosvg
• Export an SVG zip and locate it in the root of the project.

bun run icons

This will generate the src/constants/icons.ts file.

Notes

Optimise pictos

mkdir -p out
for f in *.png; do
  magick "$f" \
    -resize 500x500 \
    -background none \
    -gravity center \
    -extent 500x500 \
    PNG32:"out/${f%.*}.png"
  magick "out/${f%.*}.png" -define webp:lossless=true "out/${f%.*}.webp"
  rm "out/${f%.*}.png"
done

Gradient pictos are synced from Figma via tools/picto-sync.ts. Export the inner VECTOR child of each *_vector component (not the outer symbol/frame) using Figma get_screenshot with contentsOnly: true — download_assets bakes in the artboard background.