design/DESIGN_SYSTEM.md
Rama main · réplica de lectura del repositorio original.
# Nabu — Design System
A minimal, markdown-first design system for Nabu: a knowledge OS for humans and agents. The system is built around three ideas: **ink + amber**, **reading-first typography**, and **quiet chrome**. One display cue — the cuneiform wedge `𒀭` (Dingir, the Akkadian divine determinative that precedes Nabu's name) — carries the brand.
---
## 1. Design principles
1. **Minimal chrome, maximal content.** Panes divide with 1px soft rules, never heavy borders. No decorative iconography. One brand glyph.
2. **Markdown reads like a book.** Long-form serif for titles, TL;DR, and body. Sans for UI. Mono for paths, code, and metadata values.
3. **One accent, restrained.** Amber `oklch(0.80 0.120 75)` appears only on active state, key links, the wedge, and section anchors. Never as a background fill beyond a 12% glow.
4. **Structure is navigation.** The filesystem is the IA — no invented categories, no sidebars of features. Tree, notes, note.
5. **Reveal on demand.** Metadata, graph edges, and actions live behind a single `(i) details` drawer, not in the default view.
---
## 2. Color tokens
All colors use `oklch()` for perceptual consistency. Three themes share the same token names.
### 2.1 Scribe (default — ink + amber)
| Token | Value | Use |
|---|---|---|
| `--bg` | `oklch(0.15 0.006 250)` | Tree column, app base |
| `--bg-pane` | `oklch(0.17 0.006 250)` | Notes column, reader |
| `--bg-sunk` | `oklch(0.13 0.006 250)` | TL;DR well, callouts, code bg |
| `--bg-hover` | `oklch(0.21 0.007 250)` | Hover / selected row |
| `--bg-active` | `oklch(0.23 0.010 250)` | Pressed / active cell |
| `--rule` | `oklch(0.26 0.006 250)` | 1px borders |
| `--rule-soft` | `oklch(0.22 0.006 250)` | Dividers, soft separators |
| `--ink` | `oklch(0.95 0.008 80)` | Primary text |
| `--ink-muted` | `oklch(0.76 0.008 80)` | Body paragraphs |
| `--ink-dim` | `oklch(0.58 0.006 250)` | Secondary labels |
| `--ink-faint` | `oklch(0.44 0.006 250)` | Captions, eyebrows |
| `--accent` | `oklch(0.80 0.120 75)` | Wedge, active row, TL;DR rail |
| `--accent-soft`| `oklch(0.62 0.090 75)` | Code text, active chip border |
| `--accent-glow`| `oklch(0.80 0.120 75 / 0.12)` | Active chip bg, hover |
| `--mark` | `oklch(0.80 0.120 75 / 0.22)` | Search highlight |
### 2.2 Graphite (monochrome)
Override only the accent family; backgrounds remain identical.
```css
--accent: oklch(0.88 0 0);
--accent-soft: oklch(0.70 0 0);
--accent-glow: oklch(0.88 0 0 / 0.08);
--mark: oklch(0.88 0 0 / 0.18);
```
### 2.3 Tablet (warm clay)
Shifts the base toward a warm brown; keeps the amber accent.
```css
--bg: oklch(0.22 0.020 65);
--bg-pane: oklch(0.25 0.022 65);
--bg-sunk: oklch(0.20 0.020 65);
--ink: oklch(0.94 0.022 80);
--accent: oklch(0.82 0.130 70);
```
### 2.4 Accessibility
All ink-on-bg pairings exceed WCAG AA for body text (4.5:1+). Amber on `--bg` is AA for large text; never used for small body copy.
---
## 3. Typography
Three families, each with a single job.
| Family | Role | Weights |
|---|---|---|
| **Inter** (`--sans`) | UI, buttons, labels, breadcrumbs | 400, 500, 600, 700 |
| **Newsreader** (`--serif`) | Note titles, TL;DR, body prose, wordmark | 400, 500, 600 |
| **JetBrains Mono** (`--mono`) | Paths, code, tag values, scope | 400, 500 |
### Type scale
| Token | Size | Line-height | Family | Use |
|---|---|---|---|---|
| `reader-title` | 32px | 1.15 | serif 500 | Note H1 |
| `fs-body` | 16px | 1.7 | serif | Markdown paragraphs |
| `note-card-title` | 15px | 1.3 | serif 500 | List-row title |
| `fs-ui` | 13.5px | 1.5 | sans | Tree, inputs, controls |
| `fs-sm` | 12.5px | 1.45 | sans/mono | Sub-metadata |
| `fs-xs` | 11px | 1.4 | sans | Eyebrows, chips |
| `mini` | 10–10.5px | — | sans | Uppercase labels |
### Rules
- Uppercase labels get `letter-spacing: 0.14–0.2em`.
- Body gets `text-wrap: pretty`.
- `font-feature-settings: 'cv11', 'ss01'` on body for Inter's curly-l and single-story g.
- Serif gets `letter-spacing: -0.01em` to -0.02em at display sizes.
- Never use bold on monospace — use `--accent-soft` color instead.
---
## 4. Spacing & layout
### Grid
The app is a fixed three-column shell with no responsive breakpoints at desktop (optional collapse <900px):
| Token | Value | Role |
|---|---|---|
| `--spine-w` | 320px | Tree + search + scope |
| `--notes-w` | 320px | Notes in folder |
| `--drawer-w` | 280px | Details drawer (slides over reader) |
### Inner padding
- Tree column: `14px 8px` section padding, `4px 8px` per row
- Notes column: `14px 20px` per card
- Reader article: `48px 48px 96px` (max 720px content width)
- Drawer: `20px 20px 40px`
### Radii
One scale: `--rad: 4px`. Chips are pill (`10px`). Avatars/buttons never rounded beyond `50%` for the info `(i)` glyph.
---
## 5. Iconography
**Policy: almost none.** The system relies on type + color for affordance.
- **`𒀭`** — Dingir wedge. Used once, in the wordmark. Amber.
- **`⌕`** — Unicode search prefix in the search input.
- **`▸`** — Tree caret, rotates 90° when open (160ms).
- **`(i)`** — Serif italic lowercase i in a circle, for the details button.
- **`×`** — Chip dismiss.
No custom SVGs. No Lucide / Feather / Heroicons.
---
## 6. Components
### 6.1 Spine header (top of left column)
- `𒀭 nabu` wordmark (serif 500, 18px) + right-aligned `logout` (xs, faint)
- `SCOPE` eyebrow + mono path
- Bottom: 1px `--rule-soft`
### 6.2 Search input
- Sunk bg, 1px soft rule, `--rad` radius
- `⌕` prefix, placeholder “search vault”
- Focus: `--accent-soft` border + 3px `--accent-glow` ring
- Optional `esc` chip on the right to clear
### 6.3 Tag chip
```
┌──────────┐
│ #alpha │ pill, 10.5px, sans
└──────────┘
```
- Default: `--ink-dim` text, `--rule` border
- Hover: `--ink` text, `--ink-faint` border
- Active (filtering): `--accent` text, `--accent-soft` border, `--accent-glow` bg
### 6.4 Folder tree row
- Caret (`▸`), 14px wide, rotates on open
- Name + right-aligned count (tabular, faint)
- Active: amber text on `--accent-glow` bg, no bar
- Depth: `6px + depth * 14px` left padding
### 6.5 Note card (list row)
Two-row card in the notes column:
```
Claude's Usability Feedback on Nabu Alpha ← serif 15/500, --ink
Apr 13, 2026 · 8 min ← sans 10.5, --ink-faint
First real agent-driven session … ← serif 12.5 --ink-dim (clamp 2)
#nabu #feedback #alpha #agent-usability ← chips xs
```
- Active: `--bg-hover` + 2px left bar in `--accent`; title turns amber
- Hover: `--bg-hover` only
### 6.6 Reader topbar
- Left: breadcrumb trail in mono (`vault / projects / nabu / file.md`), `--ink-faint` with `--ink-muted` leaf
- Right: `(i) details` pill button, 1px soft rule, turns amber on active
### 6.7 Reader article
```
Title ← serif 32/500, -0.02em
author · date · read-time ← sans 12, faint
[#tag chips]
┌───────────────────────────────────────────────┐
│ TL;DR First real agent-driven session … │ ← sunk bg, 2px amber rail
└───────────────────────────────────────────────┘
WHAT WORKED WELL ← sans 13 600, uppercase, 1px rule
Body copy … ← serif 16/1.7, --ink-muted
The agents.md entrypoint is the killer feature. ← strong = --ink + 600
`code` in mono, amber-soft, sunk bg
```
### 6.8 Numbered list (`md-ol`)
- Counter on the left in sans 13/600, `--ink-faint`, 22px column
- Each item separated by a `--rule-soft` underline
- Plain Arabic numerals (`1`, `2`, `3`), no leading zeros
### 6.9 Callout
- Sunk bg, 2px amber left rail, `--rad` right-only
- Label in sans 10/600 uppercase, `--accent`
- Body in serif 15/1.6
### 6.10 Details drawer
- Slides in from the right over the reader (280px)
- Cubic-bezier `(0.2, 0.8, 0.2, 1)`, 260ms
- Sections stacked: metadata KV · neighborhood stats · linked from · related · actions
- Stat tiles show serif numeral (22px, amber) + uppercase micro-caption
### 6.11 Tweaks panel
- Fixed bottom-right, 200px wide, border + 1px soft, shadow
- Rows of `label → button` for theme switching
- Buttons: mono 10.5, `--rad: 3px`, active = amber text/border/glow
---
## 7. Motion
- **Tree caret:** 160ms rotate
- **Drawer:** 260ms slide, cubic-bezier `(0.2, 0.8, 0.2, 1)`
- **Hover states:** 120ms color/bg cross-fade
- **No bounce, no spring, no scale-on-hover.** This is a reading tool.
---
## 8. Accessibility
- Focus ring: 3px `--accent-glow` on inputs
- All interactive elements reachable by Tab
- `⌘K` focuses the search input globally
- Drawer has `aria-hidden` mirrored to `open` state
- Breadcrumbs use `<nav aria-label="breadcrumbs">`
---
## 9. Voice & copy
- **Lowercase UI.** `search vault`, `logout`, `scope`, `details`, `tree`, `3 notes`. Only proper nouns and sentence-first words are capitalized.
- **Mono for paths and values.** `/projects/nabu`, `claude-opus-4.6`, `POST /api/vault/folders`.
- **No exclamations, no em-dash hype.** Dry, precise, scribe-like.
- **Labels, not verbs, on eyebrows.** `SOURCE`, `AUTHOR`, `LINKED FROM` — not `View source`.
---
## 10. Do / Don't
**Do**
- Use amber *only* for one thing per screen at any time (active row, active tag, or hover — rarely two).
- Keep the reader below 720px content width.
- Prefer serif for anything you want people to read at length.
- Let the 1px `--rule-soft` divider do the work that borders usually do.
**Don't**
- Add a second accent color.
- Invent decorative SVGs or illustrations.
- Use `--serif` for buttons or UI labels.
- Put borders *and* backgrounds on the same surface — pick one.
- Use ALL CAPS on anything longer than 3 words.
---
## 11. Brand mark
The lockup is `𒀭 nabu` — wedge in amber, wordmark in Newsreader 500. The wedge should never appear without the wordmark in primary contexts. It may appear alone at 22–28px as a loading or footer glyph, in `--accent` with `drop-shadow(0 0 8px --accent-glow)`.
**Clearspace:** `1ex` on all sides (the height of the lowercase `n`).
---
## 12. File map
```
Nabu Redesign.html # entry, Tweaks + ⌘K wiring
src/
styles.css # tokens, components, themes
data.jsx # vault tree + note fixtures
NavRail.jsx # SpineHeader (wordmark + scope + logout)
Spine.jsx # TreeColumn + NotesColumn
Reader.jsx # Breadcrumbs + Markdown + InfoDrawer
```
Themes are switched via `data-theme="scribe|graphite|tablet"` on `<html>`; the Tweaks panel persists the choice through the `__edit_mode_set_keys` protocol.