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:

<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:

# 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.