opentabs

# Docs Project Instructions

## Overview

The OpenTabs documentation site is built with Next.js 16, content-collections for MDX, and a neo-brutalist design system. Content is authored in MDX under `content/`, rendered via content-collections, and styled with Tailwind CSS 4.

## Tech Stack

- **Framework:** Next.js 16 (static export via `next build`)
- **Content:** content-collections (`@content-collections/mdx` + `@content-collections/next`)
- **Styling:** Tailwind CSS 4 (CSS-first config via `@theme inline` in `global.css`)
- **UI primitives:** Radix UI (Slot), Headless UI (Tabs)
- **Fonts:** Archivo Black (headings), Space Grotesk (body), Space Mono (code)

## Commands

```bash
npm run build         # next build (static export)
npm run type-check    # tsc --noEmit
npm run lint          # biome lint
npm run knip          # unused code detection
npm run format:check  # biome format check
npm run check         # All checks (build + type-check + lint + knip + format:check)
```

All checks must pass. This project has no test suite. `npm run check` runs them all sequentially, stopping on first failure.

From the repo root, these convenience aliases are available:

```bash
npm run dev:docs        # next dev (docs dev server)
npm run build:docs      # next build
npm run lint:docs       # biome lint
npm run type-check:docs # tsc --noEmit
npm run check:docs      # All docs checks from root
```

## Directory Structure

```
docs/
├── app/
│   ├── global.css              # Theme definition — single source of truth
│   ├── layout.tsx              # Root layout (fonts, Provider)
│   ├── page.tsx                # Homepage
│   └── docs/                   # Docs pages layout
├── components/
│   ├── retroui/                # RetroUI primitives (Button, Badge, Table, etc.)
│   ├── illustrations.tsx       # All SVG illustration components
│   ├── MDX.tsx                 # MDX component overrides and illustration registration
│   ├── CodeBlock.tsx           # Code block with copy button
│   └── global-header.tsx       # Shared header across all pages
├── content/
│   └── docs/                   # MDX content files (guides, SDK reference, etc.)
├── config/                     # Content-collections and docs configuration
├── lib/
│   └── utils.ts                # cn() helper
└── types/                      # TypeScript type definitions
```

## Theme

`app/global.css` defines the visual language as CSS custom properties. Key tokens:

| Token          | Light     | Dark      | Tailwind class    |
| -------------- | --------- | --------- | ----------------- |
| `--radius`     | `0`       | (same)    | `rounded`         |
| `--background` | `#fff`    | `#111111` | `bg-background`   |
| `--foreground` | `#000`    | `#f5f5f5` | `text-foreground` |
| `--primary`    | `#ffdb33` | `#ffdb33` | `bg-primary`      |
| `--border`     | `#000`    | `#777777` | `border-border`   |
| `--card`       | `#fff`    | `#1c1c1c` | `bg-card`         |

Shadows are flat offsets using `var(--border)` with no blur or spread.

## SVG Illustrations

All illustrations live in `docs/components/illustrations.tsx` and are registered in `docs/components/MDX.tsx` for use in `.mdx` files.

### Design Rules

- CSS variables for theming: `var(--color-foreground)`, `var(--color-primary)`, `var(--color-background)`
- Font: `var(--font-mono), monospace` for all text
- Borders: 3px `strokeWidth` on main containers
- Shadows: Hard drop shadow via offset `<rect>` (4px right, 4px down) filled with `var(--color-foreground)`
- Headers: Box-with-header-bar pattern — header filled with `var(--color-foreground)`, text in `var(--color-primary)` bold
- No border-radius (`--radius: 0`)
- Arrow markers: Triangular arrowheads filled with `var(--color-foreground)`, unique IDs per illustration (e.g., `pf-arrow`, `fp-arrow`)
- Muted labels: `opacity="0.4"` to `0.5"` for secondary text
- Highlighted items: `var(--color-primary)` with `opacity="0.12"` fill and `1.5px` stroke
- Dashed borders: `strokeDasharray="4 3"` for optional/repeating elements
- Accessibility: `aria-hidden="true"` on `<svg>` elements

### Current Illustrations

| Component                  | Used on                                           | Concept                               |
| -------------------------- | ------------------------------------------------- | ------------------------------------- |
| `ArchitectureIllustration` | `docs/content/docs/contributing/architecture.mdx` | 3-component platform architecture     |
| `QuickStartFlow`           | `docs/content/docs/quick-start.mdx`               | Quick start installation steps        |
| `ConfigDirectory`          | `docs/content/docs/reference/configuration.mdx`   | Config directory tree structure       |
| `MonorepoStructure`        | `docs/content/docs/contributing/dev-setup.mdx`    | Monorepo project layout               |
| `PluginStructure`          | `docs/content/docs/guides/plugin-development.mdx` | Plugin directory structure            |
| `ProgressFlow`             | `docs/content/docs/guides/streaming-progress.mdx` | 6-step progress notification pipeline |
| `LifecycleSequence`        | `docs/content/docs/sdk/lifecycle-hooks.mdx`       | Lifecycle hooks execution timeline    |
| `ErrorCategories`          | `docs/content/docs/guides/error-handling.mdx`     | Error categories and retry behavior   |
| `HowItWorks`               | `docs/content/docs/index.mdx`                     | 3-step runtime flow overview          |
| `InstallPaths`             | `docs/content/docs/install/index.mdx`             | Three installation path options       |
| `FirstPluginFlow`          | `docs/content/docs/first-plugin.mdx`              | 5-step plugin creation workflow       |

## Runtime and Tooling Context

The docs site is a **platform contributor** tool — built and developed using Node.js and npm (`npm run build`, `npm run dev:docs`, etc.).

The docs _content_, however, covers three audience tiers with different runtime and tooling expectations:

- **Normal users** use **Node.js** and **npm**. Commands in user-facing docs (Quick Start, Installation) should use `npx` / `npm`.
- **Plugin developers** use **Node.js** and **npm**. Plugin docs should show `npm run build`, `npx @opentabs-dev/create-plugin`, etc.
- **Platform contributors** use **Node.js** and **npm**. Contributing docs reference `npm run` commands.

## Documentation Tone

The docs follow a progressive audience path: **normal user** (Quick Start, Installation) → **plugin developer** (Guides, SDK Reference) → **platform contributor** (Contributing). The tone is:

- **Friendly and accessible** — no jargon without explanation, no assumptions about prior knowledge
- **Step-by-step and hand-holding** — explicit numbered steps, one action per step
- **Show before tell** — lead with a visual or code example, then explain
- **Concrete over abstract** — real commands, real output, real file paths

Illustrations should match this tone: clear, labeled, approachable. Prefer showing the "happy path" flow over comprehensive architecture diagrams. Use annotations and labels generously.