# @surrealdb/ui

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

## Using the UI Kit

First, import the styles and fonts:

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

Then, configure the Mantine theme:

```tsx
import { MantineProvider } from "@mantine/core";
import { MANTINE_THEME } from "@surrealdb/ui/theme";

<MantineProvider theme={MANTINE_THEME}>
	<App />
</MantineProvider>;
```

Finally, use the components:

```tsx
import { Heading } from "@surrealdb/ui";

<Heading
	kicker="Foo"
	description="Bar"
>
	Hello world
</Heading>;
```

## 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.

```tsx
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`](./src/lib/markdown/SPEC.md) for the full specification.

## Getting Started

To install dependencies:

```bash
bun install
```

Start the Storybook development server:

```bash
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](https://github.com/googlefonts/picosvg)
- Export an SVG zip and locate it in the root of the project.

```bash
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.
