nibiru-framework.com/docs/design-system/SPEC.md

# Handoff: Nibiru Docs Design System

## Overview

This handoff covers the **Nibiru documentation site** redesign — a cosmic-themed, dark-primary design system for the framework's docs portal. It includes a complete component library (navigation, code blocks, callouts, tables, API references, search modal, 404, etc.) plus a working full-page preview of the "What is Nibiru?" article styled with the new system.

The metaphor carried throughout: **Nibiru is a star map**. The framework's MMVC architecture (Model · Module · View · Controller) is a constellation, and the docs adopt the same atmospheric vocabulary — deep cosmic plum backgrounds, magenta/cyan/amber accents echoing nebula colors, terminal-aesthetic code blocks, and subtle galaxy textures behind content.

A companion start page (`index-v2.html`) is included for context — it's the marketing site this docs design extends.

## About the Design Files

The files in this bundle are **design references created in HTML** — interactive prototypes showing intended look, behavior, and layout. They are **not production code to copy directly**.

Your task is to **recreate these designs in the Nibiru docs site's actual environment** (likely a static-site generator like Nextra, Mintlify, Docusaurus, or VitePress, given the original screenshot's nav structure), using whatever templating, theming, and component patterns that environment provides. The HTML/JSX in this bundle uses React + Babel inline as a fast prototyping medium — your real implementation should use your stack's idioms.

If no docs framework has been chosen yet, **Nextra (with the docs theme) or Mintlify** are good fits — both support exactly this kind of three-column layout (sidebar + content + on-this-page TOC) with custom theming hooks.

## Fidelity

**High-fidelity.** All colors, typography, spacing, border radii, shadows, and component states are final. Treat the hex values, font sizes, and CSS tokens in `tokens.css` as the source of truth.

The single open question is how dark/light theme switching is wired — the prototype uses a `.theme-light` class on a wrapper element, but your stack may prefer `data-theme` attributes or CSS `color-scheme`.

## Screens / Views

The design canvas in `source/docs-system.html` shows every component grouped into reviewable sections. The full-page preview is the most important reference — it shows how everything composes.

### 1. Full Page Preview ("What is Nibiru?")

**Purpose**: Recreate the documentation article from the original screenshot in the new design system.

**Layout**: Three-column grid, full viewport height.
- **Top nav**: 60px tall, sticky, `backdrop-filter: blur(16px)`, semi-transparent background.
- **Main grid**: `grid-template-columns: 280px 1fr 240px` (sidebar / content / TOC).
- **Content column**: `max-width: 760px`, centered within its track, padding `32px 48px`.

**Components used**: TopNav · Sidebar · PageHeader · Prose body · DocTable · Callout · Pagination · RightTOC

### 2. Top Nav

**Purpose**: Brand mark, search, GitHub link, theme toggle, locale picker.

**Layout**: `grid-template-columns: 240px 1fr auto`, gap 32px, padding `0 24px`, height 60px.

**Components**:
- **Brand**: Lotus PNG (36px tall) + "Nibiru" (17px / 600) + "Create, Invent, Impress" tagline (10px muted, lowercase).
- **Search button**: Pill-shaped, 420px max-width, centered. `background: var(--space-2)`, `border: 1px solid var(--line)`, contains search icon + "Search" placeholder + `⌘ K` kbd badge. Hover: brighten background.
- **Right cluster**: GitHub icon (36×36), theme toggle (sun/moon), locale dropdown ("EN ▾"). All 36×36 with hover background `var(--space-2)`.

### 3. Sidebar

**Purpose**: Sectioned navigation with collapsible groups and active-page indication.

**Layout**: 280px wide, padding `24px 12px 24px 24px`, `border-right: 1px solid var(--line)`, faint background tint `rgba(11,4,16,0.4)`.

**Sections**: "Get Started" / "The Framework" / "CLI" / "Advanced" — each a collapsible group with a chevron that rotates 0deg/-90deg.

**Section heading**: 11px JetBrains Mono, 0.12em letter-spacing, uppercase, muted color.

**Items**: 13.5px, padding `6px 10px`, border-radius 8px. Hover: background `var(--space-2)`. Active state has a magenta gradient background (`linear-gradient(90deg, rgba(184,107,255,0.18), rgba(184,107,255,0.04))`) and a 3px magenta indicator bar with a glow shadow on the left edge.

**Badges**: `core` (magenta tint) and `new` (green tint), 9px JetBrains Mono uppercase.

### 4. Right TOC ("On this page")

**Layout**: 240px wide, padding `24px 16px 24px 24px`.

**Heading**: 11px JetBrains Mono uppercase muted.

**List**: `border-left: 1px solid var(--line)`, items 13px with 12px padding-left. Active item: magenta text + magenta 2px left border (replacing the 1px line border at that position).

**Sub-items (level 2)**: Indented 24px, 12.5px, more muted.

**Footer**: "Edit this page" link with pencil icon.

### 5. Page Header

**Layout**: `margin-bottom: 32px`, `padding-bottom: 24px`, `border-bottom: 1px solid var(--line)`.

**Breadcrumbs**: 11px JetBrains Mono uppercase, separated by `/`. Last crumb is brighter.

**Title**: 36px / 600 / -0.025em letter-spacing.

**Summary**: 18px, color `var(--star-soft)`, max-width 60ch.

**Last-updated meta**: 11px JetBrains Mono with a 6px green dot (with green glow shadow).

### 6. Body Prose

**Base**: 16px / 1.7 line-height, color `var(--star-soft)`.

**h2**: 28px / 600, with a 24px magenta gradient line above it (`width: 24px; height: 1px; background: linear-gradient(90deg, var(--nebula-mag), transparent)`). 40px top margin, 16px bottom margin.

**h3**: 22px / 600. 32px top, 12px bottom.

**em**: Restyled — color `var(--nebula-mag-2)`, NOT italic.

**Inline code**: Monospace 0.86em, magenta-2 text on `var(--space-2)` with 1px line border, 4px radius, 1px 6px padding.

**Blockquote**: 2px magenta left border, 16px left padding, magenta gradient fade background.

**ul markers**: Magenta accent.

### 7. Code Block

**Aesthetic**: Mission-Control terminal — `background: #0a0210`, 12px radius, magenta gradient overlay (4% opacity, 135deg from top-left).

**Header**: `padding: 8px 14px`, `border-bottom: 1px solid rgba(244,238,219,0.06)`, `background: rgba(0,0,0,0.3)`.
- Three colored dots (rose, amber, green at 50% alpha — like macOS traffic lights but recolored to nebula palette).
- Filename in JetBrains Mono 11px.
- Language badge (10px JetBrains Mono uppercase, magenta text on transparent background with magenta border).
- Copy button on the right (changes to "Copied ✓" for 1.4s on click).

**Body**: 13px JetBrains Mono, 1.7 line-height, padding `16px 20px`.

**Syntax tokens** (CSS classes already defined):
| Token | Class | Color |
|---|---|---|
| Keyword | `.tk-kw` | `#ff7ab8` rose |
| Class/type | `.tk-cn` | `#ffb574` amber |
| Function | `.tk-fn` | `#6ad9ff` cyan |
| Variable | `.tk-var` | `#d8a8ff` magenta |
| String | `.tk-str` | `#6ee7b0` green |
| Number | `.tk-num` | `#ffb574` amber |
| Namespace | `.tk-ns` | muted cream |
| Comment | `.tk-cm` | very muted, italic |

In production, hook these classes up to your syntax highlighter (Shiki, Prism, etc.) via a custom token theme.

### 8. Callouts (Note / Tip / Warning / Danger)

**Layout**: Flex row with 14px gap, 14px×18px padding, 8px radius, 1px colored border, tinted background (~6% alpha of the accent), radial gradient overlay at 5% opacity from top-left.

**Glyph**: 24×24 rounded with `filter: drop-shadow(0 0 6px currentColor)` for the cosmic glow.

**Color mapping**:
| Kind | Color | Hex |
|---|---|---|
| Note | Cyan | `#6ad9ff` |
| Tip | Green | `#6ee7b0` |
| Warning | Amber | `#ffb574` |
| Danger | Rose | `#ff7ab8` |

**Title**: 13px / 600 in the accent color.

**Body**: 15px in `var(--star-soft)`.

### 9. Tables

**Layout**: `border: 1px solid var(--line)`, 8px radius, `overflow: hidden`.

**Header**: `background: var(--space-2)`, padding `10px 16px`, 11px JetBrains Mono uppercase muted.

**Rows**: `padding: 12px 16px`, 13.5px, dashed bottom border. Hover: `background: rgba(184,107,255,0.04)`.

**First column**: Brighter (`var(--star)`), 500 weight, `white-space: nowrap`.

**Inline `<code>`**: Magenta-2 on `var(--space-2)`.

### 10. Tabs

**List**: `background: var(--space-2)`, padding 4px, 4px gap.

**Trigger**: 6px×14px padding, 13px / 500. Inactive: muted text. Active: bright text on `var(--space-3)`, 1px magenta inset shadow at the top, sm shadow.

**Use case**: "PHP / SQL / YAML" code variants, "macOS / Linux / Windows" install instructions.

### 11. API Block

**Container**: `padding: 18px 20px`, 12px radius, gradient background (`linear-gradient(180deg, var(--space-2), transparent)`).

**Signature**: 14px JetBrains Mono on `rgba(0,0,0,0.3)` with line border, 8px radius. Highlights function name (cyan), arg names (magenta-2), types (amber). Punctuation muted.

**Section labels**: "Parameters" / "Returns" — 10px JetBrains Mono uppercase muted.

**Param row**:
- Name (13px JetBrains Mono magenta-2 / 500)
- Type pill (11px JetBrains Mono amber on amber-tinted bg)
- Optional `required` pill (rose tint)
- Optional `default: <code>...</code>` (muted, with brighter code value)
- Description (13.5px star-soft)
- Dashed bottom border between params

### 12. Cards / Feature Grid

**Layout**: `grid-template-columns: repeat(2, 1fr)`, 14px gap.

**Card**: `background: var(--space-2)`, 1px line border, 12px radius, 18px padding. Hover: border becomes magenta-tinted, lifts 2px, background brightens, top-right arrow icon fades in & slides into place.

**Icon block**: 36×36 rounded square with a custom gradient background per card (mag→rose, cyan→mag, amber→rose, green→cyan).

**Title**: 15px / 600. **Description**: 13px star-soft.

### 13. Search Modal (⌘K)

**Container**: 580px wide, 16px radius, `background: var(--space-2)`, glow shadow (`0 0 60px rgba(184,107,255,0.1)`).

**Sections**:
- Input row (16px placeholder text, search icon, `esc` kbd badge).
- "Recent" — pills (rounded, `var(--space-3)` background).
- "Results" — list with kind badges (page=magenta, section=cyan, api=amber), title with breadcrumb prefix, excerpt, `→` indicator. Active result has a magenta left border and tinted bg.
- Footer — kbd hints (`↑↓` navigate · `↵` open · `⌘K` close) + "Powered by Nibiru Search".

**Highlight matches**: `<mark>` element gets `background: rgba(184,107,255,0.3)`, no padding.

### 14. Pagination

**Layout**: Two-column grid, top border, 48px top margin.

**Link card**: `background: var(--space-2)`, 1px border, 12px radius, padding `14px 18px`. Two-line content: small "Previous"/"Next" label (10px JetBrains Mono uppercase muted) + 14px / 500 page title.

**Hover**: Border picks up magenta glow, bg brightens, chevron arrow translates ±3px.

### 15. Floating Action Button (Help)

**Button**: 52px circle, gradient `linear-gradient(135deg, magenta, rose)`, 12px×32px shadow + inner white highlight.

**Pulse ring**: `::after` pseudo-element animating from scale(1) → scale(1.4), opacity 0.7 → 0, infinite 2.4s.

**Tooltip**: Pops out to the left on hover (kept in DOM for review).

### 16. 404 / "Off-orbit"

**Layout**: Centered, 520px max-width.

**Hero illustration**: SVG with two dashed orbital ellipses around a bright central star (radial gradient white→amber→magenta-fade), and a cyan probe drifting off-orbit at the top-right with a "PROBE-404" callout label and a dashed line connecting it back to the star.

**Code label**: "404 / off-orbit" in 11px JetBrains Mono cyan.

**Title**: "This page drifted away from Nibiru." 28px / 600.

**Actions**: Primary button (magenta solid) + ghost button (line border).

### 17. Mobile Drawer

**Container**: 320px wide, 640px tall in the prototype (in real life: full viewport with slide-in animation).

**Structure**: Header (brand + close X) → search button → sidebar (full nav) → footer (Theme / EN / GitHub pills).

## Interactions & Behavior

| Interaction | Trigger | Behavior |
|---|---|---|
| Theme toggle | Click sun/moon icon in nav | Add/remove `.theme-light` on root. Persist to `localStorage`. |
| Sidebar collapse | Click section heading | Toggle children visibility, rotate chevron 90°. Animate `transform: rotate()` 200ms ease. |
| Sidebar active | Current page | Apply `.active` class — magenta gradient bg + 3px magenta glowing left bar. |
| TOC active | Scroll position | Use `IntersectionObserver` on `.prose h2[id]` elements. Highlight matching TOC item. |
| Search open | `⌘K` / `Ctrl+K` / click search button | Open modal, focus input. `Esc` closes. ↑↓ navigates results, ↵ opens. |
| Code copy | Click "Copy" button | Copy to clipboard, swap to "Copied ✓" for 1400ms, then revert. |
| Tab switch | Click trigger | Update `aria-selected`, swap panel. No transition — instant. |
| Card hover | Pointer enter | `transform: translateY(-2px)`, border magenta-tint, arrow fades in & translates. 200ms transitions. |
| Pagination hover | Pointer enter | Chevron translates ±3px in the direction of travel, border magenta. |
| FAB pulse | Always | 2.4s infinite ring animation. |

## State Management

This is a docs site — most state is URL-driven (current page, anchor, search query). The minimum client state needed:

- `theme: "dark" | "light"` (persisted to `localStorage`)
- `sidebarOpen: boolean` (mobile drawer)
- `searchOpen: boolean` (⌘K modal)
- `expandedSections: Record<string, boolean>` (sidebar collapse — defaults to "current section open")
- `activeTocId: string` (driven by IntersectionObserver, not user input)
- `copyStateByBlock: Record<string, boolean>` (per-block "Copied" flash — local component state is fine)

## Design Tokens

All tokens live in **`source/docs-system/tokens.css`**. Copy this file into your codebase verbatim — it's the source of truth.

### Colors (dark theme)
| Name | Hex | Use |
|---|---|---|
| `--space` | `#0b0410` | Page background |
| `--space-2` | `#120822` | Panel surfaces |
| `--space-3` | `#1a0c2e` | Raised surfaces |
| `--plum` | `#2a1545` | Deep accents |
| `--plum-2` | `#3a1d5e` | Hover plum |
| `--star` | `#f4eedb` | Primary text |
| `--star-soft` | `#d8d2c0` | Secondary text |
| `--muted` | `#8b85a3` | Tertiary / labels |
| `--muted-2` | `#5e5878` | Very muted |
| `--nebula-mag` | `#b86bff` | Primary accent · links |
| `--nebula-mag-2` | `#d8a8ff` | Hover / em |
| `--nebula-cyan` | `#6ad9ff` | Note callout |
| `--nebula-amber` | `#ffb574` | Warning callout / numbers |
| `--nebula-rose` | `#ff7ab8` | Danger callout / keywords |
| `--nebula-green` | `#6ee7b0` | Tip callout / strings |

### Light theme overrides
Defined under `.theme-light` in `tokens.css` — accent colors shift to higher-contrast equivalents (purple replaces magenta, teal replaces cyan) against a parchment `#faf6ec` background.

### Type scale
| Token | px | Use |
|---|---|---|
| `--fs-xs` | 12 | Tiny meta |
| `--fs-sm` | 13 | UI |
| `--fs-base` | 15 | Default |
| `--fs-md` | 16 | Body prose |
| `--fs-lg` | 18 | Page summary |
| `--fs-xl` | 22 | h3 |
| `--fs-2xl` | 28 | h2 |
| `--fs-3xl` | 36 | Page title |
| `--fs-4xl` | 48 | Page hero |

### Spacing
4 / 8 / 12 / 16 / 20 / 24 / 32 / 40 / 48 / 64 — exposed as `--space-1` through `--space-16` (note: var name pun with the cosmic palette `--space`; see comment in tokens.css).

### Radii
4 / 8 / 12 / 16 / 20 / 999px (pill).

### Shadows
- `--shadow-sm`: `0 1px 2px rgba(0,0,0,0.3)`
- `--shadow-md`: `0 8px 24px -8px rgba(0,0,0,0.5)`
- `--shadow-lg`: `0 24px 48px -16px rgba(0,0,0,0.6)`
- `--shadow-glow`: `0 0 24px rgba(184,107,255,0.25)`

### Fonts
- **Sans**: `Inter Tight` (400/500/600/700) — fall back to Inter, system sans
- **Mono**: `JetBrains Mono` (400/500/600)
- No display serif — explicitly all-sans for density and clarity.

Load via Google Fonts:
```html
<link href="https://fonts.googleapis.com/css2?family=Inter+Tight:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
```

Or self-host for performance.

## Assets

- **`source/docs-system/assets/lotus.png`** — The Nibiru lotus mark, cropped from the supplied logo. 861×569. Use at 36px height in the nav (auto width). For a smaller mark icon variant, ask the brand owner for a square crop.
- **`source/docs-system/assets/nibiru-full.png`** — The full logo with "Nibiru" wordmark and "Create, Invent, Impress" tagline. Use on a marketing splash or auth page; not the docs nav.

The docs nav uses **lotus + typeset wordmark separately** so we get crisper text than scaling a PNG, and so the tagline can use our `--muted` token color.

## Files

```
source/
├── docs-system.html                 # Main design canvas — every component side-by-side
├── design-canvas.jsx                # The canvas component itself (pan/zoom shell, you can ignore this)
├── index-v2.html                    # Companion: the marketing start page (for brand context)
└── docs-system/
    ├── tokens.css                   # ★ DESIGN TOKENS — copy into your codebase
    ├── components.css               # ★ COMPONENT STYLES — copy or port to your styling system
    ├── assets/
    │   ├── lotus.png                # Brand mark
    │   └── nibiru-full.png          # Full logo
    └── components/
        ├── navigation.jsx           # TopNav, Sidebar, RightTOC, LotusMark
        ├── typography-and-code.jsx  # PageHeader, Prose, CodeBlock, Callout, DocTable
        └── extras.jsx               # Tabs, ApiBlock, CardGrid, SearchModal, FAB, Pagination,
                                     # MobileDrawer, NotFound

preview/
└── nibiru-docs-system.html          # Single-file bundled preview (all assets inlined,
                                     # works offline, just open in a browser)
```

### Where to start

1. Open `preview/nibiru-docs-system.html` in a browser to see the full design canvas. **This file works offline** — everything is inlined, just double-click it.
2. Read `source/docs-system/tokens.css` end-to-end — these tokens drive everything.
3. Read `source/docs-system/components.css` — every visual decision is here, organized by component with `/* ====== COMPONENT ====== */` headers.
4. Check the JSX components for structure (don't port React verbatim — just use them as a reference for DOM hierarchy and class names).
5. Pick a target stack (Nextra / Mintlify / VitePress / your own React app) and start porting. The CSS will land cleanly because it's plain CSS variables + class selectors — no framework lock-in.

### ⚠️ Running the source HTML locally

The files in `source/` use external `<script src="...jsx">` imports. **They will NOT work if you double-click `docs-system.html` directly** — browsers block cross-origin requests on `file://` URLs, so the JSX modules fail to load and you'll see `ReferenceError: TopNav is not defined` in the console.

You need a local HTTP server. From the project root:

```bash
# Python (pre-installed on macOS / Linux)
cd design_handoff_nibiru_docs_system/source
python3 -m http.server 8000
# then open http://localhost:8000/docs-system.html

# OR: Node
npx serve design_handoff_nibiru_docs_system/source
# follow the printed URL

# OR: PHP (since this is a PHP project)
cd design_handoff_nibiru_docs_system/source
php -S localhost:8000
# then open http://localhost:8000/docs-system.html
```

If you just want to **look** at the design without a server, use `preview/nibiru-docs-system.html` — it's a single self-contained file with everything bundled in.

### Migration tips

- **If using Nextra**: Override the theme via `theme.config.tsx` and inject `tokens.css` + `components.css` as global styles. Use Nextra's MDX components (`<Callout>`, `<Tabs>`, etc.) and re-skin them with our class names.
- **If using Mintlify**: Customize via `mint.json` `colors` section + a custom CSS file. Most components in this design map 1:1 to Mintlify primitives.
- **If using VitePress**: Override default theme components in `.vitepress/theme/`. The sidebar/TOC layout maps directly.
- **If rolling your own**: Copy both CSS files into `app/globals.css` (or equivalent), build React/Vue/Svelte components matching the structure in the JSX files, render MDX with a custom component map.

## Open Questions for the Developer

1. **Theme persistence**: How should we remember the user's theme choice? `localStorage` is the prototype's assumption.
2. **Search backend**: The modal is a UI shell — needs a search index. Algolia DocSearch / Mintlify Search / a local index (FlexSearch, Pagefind) all work.
3. **Syntax highlighting**: We define the token classes; you wire them up. Shiki with a custom theme matching our `.tk-*` classes is recommended.
4. **i18n**: The locale dropdown is decorative in the prototype. Wire it up if/when translations exist.
5. **Mobile breakpoints**: Not heavily specified. Suggested: hide right TOC below 1100px, swap left sidebar for the mobile drawer below 768px.