# DESIGN.md The visual system of the DeerFlow frontend, as it ships today. It records what the code already does so new UI matches it. The source of truth stays in code: tokens in `src/styles/globals.css`, primitives in `src/components/ui/`. When this file and the code disagree, fix one of them in the same change. ## Surfaces The app has three surfaces that share one token set: | Surface | Routes | Character | | ------------------ | ---------------------------------- | ---------------------------------------------------------------------------------- | | Workspace (app UI) | `/workspace/*`, `/login`, `/setup` | Dense, calm, task-focused. Most UI work happens here. | | Docs | `/[lang]/docs/*` (Nextra 4) | Reading-first. Nextra theme with the landing `Header` in place of Nextra's navbar. | | Landing and blog | `/`, `/blog/*` | Brand-forward. The only place decorative effects are allowed. | ## Color Colors are shadcn-style semantic tokens in OKLCH, defined on `:root` and `.dark` in `globals.css` and exposed to Tailwind through `@theme inline` (`bg-background`, `text-muted-foreground`, `border-border`, ...). - **Neutrals carry a warm tint.** Light surfaces use hue 87.47 at chroma 0.0098 (paper, not pure white). Dark surfaces use hue 106.64 at chroma 0.0036. - **Primary is pure black in light mode and pure white in dark mode.** There is no brand hue; contrast does the work. - **The only chromatic UI color is the focus ring** (`--ring`, blue at hue 255) plus `--destructive` (red). Charts use `--chart-1..5`. | Token | Light | Dark | Use | | ---------------------- | ---------------------------- | ------------------------------------ | ----------------------------------- | | `--background` | `oklch(0.9855 0.0098 87.47)` | `oklch(0.24 0.0036 106.64)` | Page | | `--foreground` | `oklch(0.145 0 0)` | `oklch(0.985 0 0)` | Body text | | `--card` / `--popover` | `oklch(1 0.0098 87.47)` | `oklch(0.238 / 0.205 0.0036 106.64)` | Raised surfaces, menus, popovers | | `--primary` | `oklch(0 0 0)` | `oklch(1 0 0)` | Primary buttons, strongest emphasis | | `--secondary` | `oklch(0.9455 0.0098 87.47)` | `oklch(0.3 0.0036 106.64)` | Secondary buttons, input fills | | `--muted-foreground` | `oklch(0.556 0 0)` | `oklch(0.708 0 0)` | Secondary text, captions | | `--accent` | `oklch(0.94 0.0098 87.47)` | `oklch(0.32 0.0036 106.64)` | Hover and active rows | | `--border` / `--input` | `oklch(0.922 / 0.88 ...)` | `oklch(1 0 0 / 10% / 15%)` | Hairlines, field borders | | `--ring` | `oklch(0.58 0.18 255)` | `oklch(0.74 0.16 255)` | Focus outlines | | `--destructive` | `oklch(0.577 0.245 27.3)` | `oklch(0.704 0.191 22.2)` | Errors, delete | Rules: - Use semantic tokens, never raw hex or Tailwind palette colors, in app and docs UI. Exceptions that exist today are listed under **Known exceptions**. - Tints are `color-mix(in oklch, var(--token) N%, transparent)` or Tailwind opacity modifiers (`bg-secondary/60`), so they follow the theme. - Theme switching is `next-themes` with `attribute="class"` and system default. Every new color must work in both modes; check both before shipping. ## Typography - **Sans** (`--font-sans`): the platform UI stack (`ui-sans-serif, system-ui`). Used for all UI and body text. - **Serif** (Tailwind `font-serif`): reserved for the **DeerFlow wordmark** and a few brand moments (header, footer quote, auth pages, workspace header). Don't use it for UI labels or body text. - **Mono** (`font-mono`): code, paths, IDs, token counts. - Dark mode sets `font-weight: 300` on `.dark` to offset light-on-dark bloom. Don't fight it with per-component weights. - Sizes are Tailwind's scale. UI text is `text-sm` (14px); body and reading text is `text-base` (16px); don't set body copy smaller than 14px. ## Shape, spacing, elevation - **Radius**: `--radius` is 10px. `rounded-md` (8px) for controls, `rounded-lg` (10px) for cards and panels, `rounded-xl`+ only for large containers. Keep radii consistent within one component. - **Spacing**: Tailwind's 4px scale. Page gutters are `px-4` on mobile. - **Width**: `.container-md` steps 40/48/64/80rem; workspace panes use `--container-width-{xs,sm,md,lg}`. - **Elevation**: borders before shadows. `shadow-xs` on outline buttons, `shadow-lg` only on overlays (sheets, dialogs, menus). ## Components Build from `src/components/ui/` (shadcn on Radix) before writing new primitives: `Button`, `Input`, `Textarea`, `Select`, `Dialog`, `Sheet`, `DropdownMenu`, `Command`, `Tooltip`, `HoverCard`, `Tabs`, `Switch`, `Badge`, `Card`, `Empty`, `Skeleton`, `Sonner` (toasts), and more. - **Buttons** (`button.tsx`): `default` (primary), `outline`, `secondary`, `ghost`, `link`, `destructive`. Sizes `sm` (32px), `default` (36px), `lg` (40px), `icon*`. One `default` button per area; the rest are `outline` or `ghost`. - **Icons**: `lucide-react` at `size-4` inside controls. `@radix-ui/react-icons` only where it is already used (e.g. the GitHub mark). - **Empty states**: use `Empty` with a sentence that says what to do next, not only "No items." - **Loading**: `Skeleton` for layout-shaped loading, a spinner only for short inline waits. - **Overlays**: Radix `Sheet`/`Dialog` lock body scrolling and pointer events. Nested portals must stay inside the modal's allowed content region, above z-50, with pointer events enabled. Mobile docs search uses Headless UI's `Portal.Group` targeting the sheet content; z-index alone cannot permit scroll. See `components/landing/mobile-nav.tsx`. ## Docs (Nextra) - The docs layout renders the landing `Header` instead of Nextra's navbar, and never renders Nextra's ``, so Nextra's `--nextra-*` variables are unset. Restyle Nextra parts with app tokens in `globals.css` (see the search panel rules) instead of defining `--nextra-*`. - Search is Nextra's `` in the header's `search` slot (desktop) and the mobile menu sheet (below `sm`), localized via `t.home.search*`, with an `aria-label`. Matches use a soft foreground tint plus bold, not inverted blocks. - Known gap: below 768px there is no control to open the docs sidebar. ## Motion - Short, functional transitions: `transition-colors` on hover, Radix enter/exit animations, `tw-animate-css` utilities. Durations 150 to 300ms. - Named animations live in `@theme` in `globals.css` (`fade-in`, `fade-in-up`, `loading-bar`, `skeleton-entrance`, ...). Reuse them before adding new ones. - Respect `prefers-reduced-motion` for anything that loops or moves content. ## Accessibility - Every input has a visible label or an `aria-label`; placeholders are hints, not labels. - Icon-only buttons need `aria-label` (e.g. `aria-label="Open menu"`). - Keep the visible focus ring (`focus-visible:ring-ring/50`); never remove outlines without a replacement. - Touch targets in mobile-only UI are at least 44px tall. - Body text contrast is at least 4.5:1 in both themes; `muted-foreground` is for secondary text only. ## Copy - Utility language in the app: say what the area is or what the user can do. - Every user-visible string goes through `src/core/i18n/locales/` with both `en-US` and `zh-CN` entries. - Use the typographic ellipsis (`…`) in placeholders and loading text. ## Known exceptions File-format identity tiles in `workspace/file-type-icon.tsx` use four paired light/dark tints in `styles/globals.css`: green for spreadsheets, blue for Word, orange for slides, and purple for JSON. Icons and type captions also identify the format, so color is supplementary. These tints apply only to file identity tiles; surrounding controls use semantic tokens. Rendered document colors belong to the file content and preserve the author's styling. Landing-only decoration that does not follow the rules above. Don't copy these into app or docs UI: - `Section` headings use a white-to-gray gradient text (`bg-clip-text`), and `.golden-text` is a gold gradient. - `.ambilight` is a rainbow glow, and the header's Star on GitHub button has a pink-to-violet blur behind it (`#ff80b5` to `#9089fc`). - `galaxy`, `aurora-text`, `flickering-grid`, `magic-bento`, `spotlight-card` and `shine-border` in `components/ui/` are landing effects.