# Design System (/docs/design-system)



Unono uses a theme-first design system.

Fumadocs provides the layout primitives. The site theme defines the visual contract. Components inherit that contract instead of re-declaring colors and spacing page by page.

## Positioning [#positioning]

The system is built for technical writing, long-form notes, and small editorial pages.

* Quiet over loud
* Editorial over product-marketing
* Warm over sterile
* Precise over decorative
* Sparse over crowded

## Architecture [#architecture]

1. Foundation tokens live in `src/styles/app.css`.
2. Semantic tokens map to Fumadocs theme variables such as `--color-fd-background` and `--color-fd-primary`.
3. Typography is enforced through Fumadocs `prose` and page-level pattern classes.
4. Layout components from `fumadocs-ui` stay intact unless the theme layer cannot express the change.

## Theme Layers [#theme-layers]

### Foundation Tokens [#foundation-tokens]

These tokens describe the brand language rather than direct component colors.

* `--ds-paper`
* `--ds-surface`
* `--ds-elevated`
* `--ds-ink`
* `--ds-muted`
* `--ds-rule`
* `--ds-accent`

### Fumadocs Mapping [#fumadocs-mapping]

Those foundation tokens are then mapped to Fumadocs variables.

```css
:root {
  --color-fd-background: var(--ds-paper);
  --color-fd-card: var(--ds-surface);
  --color-fd-foreground: var(--ds-ink);
  --color-fd-muted-foreground: var(--ds-muted);
  --color-fd-border: var(--ds-rule);
  --color-fd-primary: var(--ds-accent);
}
```

This keeps Fumadocs components, prose blocks, cards, dialogs, and navigation in the same visual system.

## Typography [#typography]

* UI chrome uses a sans-serif stack for controls and navigation.
* Article copy uses a serif stack for reading rhythm.
* Display headings also use the serif stack, with tighter tracking and lower visual noise.
* Code uses a dedicated mono stack.

The goal is not to imitate print literally. The goal is to keep the interface readable while preserving a paper-like editorial feel.

## Patterns [#patterns]

The current system defines a small set of patterns instead of a large component library.

* Home hero
* Home highlights grid
* Docs title and description block
* Long-form article body

Each pattern should consume theme tokens first. New one-off colors or shadows should be treated as a design system change.

## Do [#do]

* Reuse semantic tokens before adding new values.
* Keep interaction feedback subtle and calm.
* Prefer borders, spacing, and typography over heavy decoration.
* Let documentation pages feel like reading surfaces, not dashboards.

## Do Not [#do-not]

* Add multi-color branding without a clear editorial reason.
* Use large shadows as the primary separation method.
* Mix multiple visual directions on the same page.
* Override Fumadocs styles inline when the theme layer can solve the problem.

## Files [#files]

```txt
src/styles/app.css      theme tokens, prose, page patterns
src/routes/index.tsx    home page patterns
src/routes/docs/$.tsx   docs page typography hooks
src/lib/shared.ts       site metadata
```