# Design System

Understand the design model behind Lotus.

Lotus uses a compact design system for documentation sites. It is intentionally
token-driven, but the public configuration stays small: users choose the accent,
neutral scale, color mode, and radius, while the theme derives the rest.

This keeps common customization simple and leaves advanced brand work to CSS
token overrides.

## Layers

Lotus has three design layers:

1. Tailwind provides layout utilities, responsive behavior, and base color
   scales.
2. Lotus maps those primitives into semantic `--lotus-*` tokens for the docs
   shell, prose, and layout.
3. Shared MDX components read portable `--pl-*` tokens, which Lotus maps to the
   active Lotus theme.

The important boundary is that application layout belongs to Lotus, while MDX
components stay portable enough to work outside this theme.

## Appearance

The public `appearance` API controls theme direction.

```ts
appearance: {
  accent: 'indigo',
  gray: 'neutral',
  defaultMode: 'system',
  radius: 'medium',
}
```

These settings become document attributes:

| Config | Attribute | Purpose |
| --- | --- | --- |
| `accent` | `data-accent="indigo"` | Selects the interactive color family. |
| `gray` | `data-gray="neutral"` | Selects the neutral color family. |
| `defaultMode` | `data-theme="system"` | Selects light, dark, or system mode. |
| `radius` | `data-radius="medium"` | Selects the shared shape scale. |

`background` and `text` are not separate `appearance` fields. They are derived
from the chosen gray scale and color mode, along with `surface`, borders, code
colors, muted text, and heading text. Allowing them to be configured
independently would make contrast and dark mode harder to reason about.

## Color Strategy

Lotus uses semantic color names in components instead of raw palette steps.
Components ask for roles such as background, surface, text, border, and accent.
The selected appearance decides what those roles mean in light and dark mode.

The neutral scale is selected with `appearance.gray`. The accent scale is
selected with `appearance.accent`. Built-in accent colors use Tailwind color
steps; custom hex accents are converted into light and dark OKLCH values.

The result is a stable component API:

```css
color: var(--lotus-text);
background: var(--lotus-surface);
border-color: var(--lotus-border-muted);
```

## Shape

Radius is global, but components can cap it when a full radius would damage the
shape. Buttons, badges, and small controls can follow `radius: 'full'`; larger
surfaces such as dropdowns, cards, tabs, and code blocks use capped values so
they remain readable.

This gives the site a consistent shape language without making every component
look like a pill.

## Typography

Lotus does not load web fonts by default. It exposes font tokens and starts with
system font stacks. Projects that want Inter, JetBrains Mono, or a brand font
can load those fonts in their app and override the font tokens.

Typography inside Markdown is styled through `.lotus-prose`. That layer controls
the reading rhythm, heading scale, lists, tables, blockquotes, footnotes, code,
and common inline HTML elements such as `kbd`, `mark`, and `abbr`.

## Layout

The docs shell uses fixed layout tokens for the sticky header, subnav, sidebar,
main content column, and table of contents. Content width is a theme decision,
not something authors should tune per Markdown page.

This is why prose width, sidebar width, and TOC width live in theme tokens rather
than frontmatter.

## Customization

Use `appearance` for normal theme choices:

- Accent color.
- Neutral gray family.
- Initial color mode.
- Radius style.

Use CSS token overrides for brand-level control. When overriding core colors,
treat `background`, `surface`, `text`, `muted text`, borders, and code colors as
a set. Changing only one of them usually creates contrast or dark mode issues.

For the complete token API, see [Theme Tokens](/docs/references/theme-tokens/).