Design System

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.

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

These settings become document attributes:

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:

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.