DESIGN.md@ui/dashboard · diff
git:20260613.fc65fd5 to git:20260705.949814d
106 added, 218 removed. Audit A to A.
- # Cortex Memory Dashboard - Design System
+ # Cortex Atom Memory Graph — Design System
- ## Design Reference: Cyber Obsidian
+ ## Design reference: AI Architect (paper-led proof language)
- A professional neural graph dashboard inspired by Stitch-generated reference designs, combining Obsidian-style force-directed graph interaction with a dark IDE-like chrome.
+ Re-skinned off the shared `ui/shared/` design-system foundation (see
+ `ui/shared/README.md` for the token contract and re-inking method). The
+ previous "Cyber Obsidian" language — black canvas, Orbitron display type,
+ neon green/cyan/magenta, selective bloom, vignette, film grain — has been
+ retired in full. It stood apart from the rest of the ecosystem's surfaces
+ and contradicted the brand doctrine (`AI Architect Design System/README.md`
+ §3): *"Every memory tool wears the same uniform: black canvas, glowing
+ neurons... This brand refuses the costume."*
+ **Served at `/atom` by the standalone visualization server**
+ (`cortex_viz/server/http_standalone_routes.py`, `serve_static(... "atom-viz.html")`),
+ loading `/dashboard/theme.css`, `/dashboard/panels.css`, and `/dashboard/js/*`.
+ This surface is live — not superseded by `ui/unified/`.
+
---
## Layout Architecture
```
+--[SIDEBAR 200px]--+--[MAIN AREA]--------------------------------------+
| | [TOP NAV BAR - tabs + search + status] |
| Cortex | |
- | v4.0 | [KPI STRIP - 4 metric cards] |
- | | |
- | > Home | |
- | > Nodes | [3D FORCE GRAPH] |
- | > Threads | Obsidian-style |
- | > Archive | Force-directed |
- | > Trash | |
+ | atom | [KPI STRIP - metric cards] |
| | |
- | [NEW MEMORY] | [BOTTOM BAR - legend + status] |
+ | > Atom Graph | |
+ | > Timeline | [3D FORCE GRAPH] |
+ | > Categories | Atom-shell layout |
| | |
- | Settings Status | |
+ | [Analytics] | [BOTTOM BAR - legend + status] |
+--------------------+---[DETAIL PANEL 400px]---------------------------+
| Type badge | Close |
| Title |
- | Content |
| Properties grid |
| Classifiers (tags) |
| Proximal Links (connections) |
| Saturation Bar (heat) |
+---------------------------------------------------+
```
- ### Breakpoints
- - Desktop: Full layout with sidebar + graph + detail panel
- - No responsive breakpoints needed (this is a dev tool, desktop-only)
+ Desktop-only — no responsive breakpoints (dev/ops tool).
---
- ## Color System
+ ## Surface posture
- ### Base Palette
+ Boots on **paper** (cream record, deep data inks — `data-surface="paper"`,
+ stamped by `/shared/surface-toggle.js` before first paint). The top-right
+ toggle button switches to `ink` — the legacy warm-dark instrument — and
+ persists the choice.
- | Token | Value | Usage |
- |---------------------|--------------------|------------------------------|
- | `--bg-base` | `#0a0a0a` | App background |
- | `--bg-surface` | `#111111` | Sidebar, panels |
- | `--bg-elevated` | `#1a1a1a` | Cards, KPI boxes |
- | `--bg-hover` | `#222222` | Hover states |
- | `--border-subtle` | `rgba(255,255,255,0.06)` | Card borders |
- | `--border-active` | `#4ade80` | Active nav, focus states |
+ ---
- ### Accent Colors
+ ## Colour — authored against the shared token contract
- | Token | Value | Usage |
- |---------------------|--------------------|------------------------------|
- | `--accent-primary` | `#4ade80` | Primary actions, active nav |
- | `--accent-cyan` | `#00d2ff` | Entities, KPI values |
- | `--accent-magenta` | `#d946ef` | Semantic memories |
- | `--accent-green` | `#26de81` | Episodic memories |
- | `--accent-red` | `#ff4444` | Causal edges, errors |
- | `--accent-amber` | `#f59e0b` | Hover highlight, warnings |
+ Chrome (sidebar, top bar, panels, chips, borders) is **greyscale**, authored
+ against the shared semantic aliases — never raw hex:
- ### Text Colors
+ `--canvas` · `--surface` · `--surface-card` · `--surface-chip` ·
+ `--surface-input` · `--border` · `--border-strong` · `--divider` ·
+ `--text` · `--text-secondary` · `--text-muted` · `--text-faint` ·
+ `--accent-ink` (the ONE brand accent, terracotta — used for the logo mark,
+ active nav state, KPI values, and the interaction highlight ring).
- | Token | Value | Usage |
- |---------------------|--------------------|------------------------------|
- | `--text-primary` | `rgba(255,255,255,0.87)` | Headings, values |
- | `--text-secondary` | `rgba(255,255,255,0.55)` | Body text, labels |
- | `--text-tertiary` | `rgba(255,255,255,0.25)` | Hints, inactive |
- | `--text-accent` | `#4ade80` | Active labels, links |
+ **All other colour comes from data** (`ui/dashboard/theme.css` §"Data
+ family" blocks; consumed by JS via `/shared/palette.js`'s
+ `CortexPalette.hex(...)`, never a baked literal):
+ | Data family | Tokens | Mapping |
+ |---|---|---|
+ | Memory `store_type` | `--node-episodic/-semantic/-entity` | Reuses the canonical lifecycle-stage tokens directly: episodic → `--stage-labile` (new/raw), semantic → `--stage-recon` (extracted schema — palette.js's own mapping), entity → `--stage-cons` (stable knowledge-graph fact) |
+ | Relationship/edge kind | `--edge-causal/-cooccurrence/-default/-virtual/-highlight` | causal → `--emo-urgent`, co-occurrence → `--emo-discov`, default/virtual → neutral chrome grey (a weak relation is not itself a datum), highlight → `--accent-ink` |
+ | Consolidation lifecycle (analytics bars) | `--stage-*` | 1:1 with the design system's own five-stage vocabulary (McClelland et al. 1995; Foster & Wilson 2006) |
+ | Heat scale | `--heat-hot/-warm/-cool/-cold` | Direct read of the design system's hot→cold data tokens |
+ | Agent/team identity | `--agent-*` (11 hues) | No canonical token exists for "team member" — hues are evenly spaced 360°/11 ≈ 32.7° apart (deterministic, not approximated from the legacy neons); ink L78%/C0.14, paper L50%/C0.13, per `shared/README.md`'s re-inking rule |
+ | Category taxonomy (decision/architecture/error/session/knowledge/other) | reuses `--accent-ink`, `--info-ink`, `--danger-ink`, `--emo-discov`, `--node-semantic`, `--text-muted` | Chip background is chrome-neutral (`--surface-chip`); only the icon/label colour carries the data meaning |
+
---
## Typography
- ### Font Stack
- - **Display**: `'Orbitron', sans-serif` - Logo, KPI values, section headers
- - **Body**: `'JetBrains Mono', monospace` - All other text
+ Three voices, per the design system (`AI Architect Design System/README.md` §3):
- ### Scale
+ | Role | Font | Where |
+ |---|---|---|
+ | Chrome / labels / nav | `--font-sans` (Inter Tight) | Sidebar nav, buttons, filters, search |
+ | Metrics / identifiers / proof | `--font-mono` (JetBrains Mono) | KPI values, logo mark, type badges, meta values, node/edge counts, chart labels |
+ | Prose | `--font-serif` (Newsreader) | Not currently used on this surface (no long-form prose) |
- | Element | Font | Size | Weight | Letter-spacing | Case |
- |-----------------|------------|-------|--------|----------------|-----------|
- | Logo | Orbitron | 13px | 800 | 4px | UPPERCASE |
- | KPI Value | Orbitron | 22px | 700 | 0 | - |
- | KPI Label | JetBrains | 8px | 400 | 2px | UPPERCASE |
- | Nav Item | JetBrains | 11px | 500 | 0 | Sentence |
- | Section Header | Orbitron | 8px | 600 | 3px | UPPERCASE |
- | Body Text | JetBrains | 11px | 400 | 0 | Sentence |
- | Badge | Orbitron | 8px | 600 | 2px | UPPERCASE |
- | Meta Label | JetBrains | 9px | 400 | 1px | UPPERCASE |
- | Meta Value | JetBrains | 11px | 400 | 0 | - |
- | Tooltip | JetBrains | 10px | 400 | 0 | - |
+ Orbitron has been removed entirely — the previous Google Fonts `<link>` for
+ Orbitron/JetBrains Mono in `ui/atom-viz.html` is gone; fonts now load via
+ `/shared/ds.css` → `tokens/fonts.css`.
+ **Casing:** UPPERCASE reserved for small mono micro-labels (KPI labels, type
+ badges, section headers) with wide tracking, matching the verification-lexicon
+ doctrine.
+
---
## Components
- ### Sidebar Navigation
- - Fixed left, 200px wide
- - Logo at top with version badge
- - Icon + label nav items
- - Active state: green left border + green text + subtle green bg
- - "New Memory" CTA button at bottom
- - Footer: settings gear + status indicator
-
- ### KPI Strip
- - 4 cards in a horizontal row below the top nav
- - Each card: large Orbitron number + small uppercase label
- - Background: `--bg-elevated`
- - Border: `--border-subtle`
- - Value color: `--accent-primary`
+ Same component inventory as before (sidebar nav, KPI strip, top nav, 3D atom
+ graph, detail panel, bottom status bar, analytics panel, timeline/categories
+ overlays) — chrome only was re-inked. See `ui/dashboard/theme.css` and
+ `panels.css` for the authored rules.
- ### Top Navigation Bar
- - Horizontal tab strip
- - Tabs: Neural Graph, Memory Logs, Pattern Analysis, Vector Search
- - Search input right-aligned
- - Active tab: underline accent
+ ### Neural Graph (3D) — what changed
- ### Neural Graph (3D)
- - Three.js force-directed simulation
- - Memory nodes: spheres (episodic green, semantic magenta)
- - Entity nodes: octahedrons (cyan)
- - Edge styles:
- - Default: `#5a6a7a` at 0.3 opacity
- - Causal: `#ff4444`
- - Co-occurrence: `#d946ef`
- - Virtual (memory-entity): `#3a4a5a` at 0.15 opacity
- - Node labels: pipe separator style (`| LABEL_TEXT`), shown on hover or zoom
- - Selective bloom on node cores
- - Ambient dust particles (subtle)
- - Auto-fit camera after simulation settles
- - Auto-rotate when idle > 4s
+ - **No selective bloom.** The `EffectComposer`/`UnrealBloomPass` pipeline and
+ its script tags were removed from `ui/atom-viz.html`; rendering is a plain
+ `renderer.render(scene, camera)` call (`js/raycast.js` `animate()`).
+ - **No vignette, no film grain.** The post-process shader pass that combined
+ both is gone (`js/scene.js`).
+ - **No glow halo sprites.** Memory/entity nodes are flat `MeshStandardMaterial`
+ spheres/octahedrons with a minimal emissive term (0.12–0.15) for legibility
+ against the fog — not a bloom source.
+ - **Lights are neutral.** The three coloured point lights (cyan/magenta/green)
+ were replaced with one neutral ambient + one neutral directional light;
+ colour comes from the node/edge materials only.
+ - **Protected-memory ring** is a flat wireframe torus in `--warn-ink` (amber,
+ "verified/live"), not a glow.
+ - **Team/global indicator** is a small flat agent-coloured marker dot, not an
+ additive glow sprite.
+ - **Ambient dust particles** (`js/effects.js`) are neutral chrome grey
+ (`--text-faint`), non-additive blending, very low opacity — a depth cue,
+ not decorative grain.
+ - Canvas re-tints its background/fog on `cortex:surface-change` (paper ↔ ink)
+ by re-reading `CortexPalette.hex('--canvas')`.
### Detail Panel (Right Slide-in)
- - 400px wide, slide from right
- - Sections:
- 1. **Type Badge** - SEMANTIC / EPISODIC / ENTITY with colored border
- 2. **Title** - Node name or content excerpt
- 3. **Content** - Full content text (memories only)
- 4. **Properties** - 2-column grid (Heat, Importance, Domain, Source, Created, etc.)
- 5. **Classifiers** - Tag pills with colored borders
- 6. **Proximal Links** - Connection list sorted by weight, clickable
- 7. **Saturation Bar** - Heat visualization bar at bottom
- - Close button: top-right, styled X
+ Unchanged structure; chrome tokens only.
+
### Bottom Status Bar
- - Legend: colored dots with labels
- - Right side: node count, edge count, latency
- - Status: "SYNCHRONIZED" indicator
- ### Analytics Panel (Left slide-over)
- - Slides over sidebar on toggle
- - KPI overview strip
- - Bar charts: Memory Types, Heat Distribution, Domain Breakdown, Tag Frequency
- - Clickable bars filter the graph view
+ Unchanged structure. The "SYNCHRONIZED" live indicator uses the design
+ system's one permitted looping animation — the reactor dot (`--glow-ok`,
+ `dot-blink` 2.2s) — not a decorative loop.
---
## Interaction Patterns
- ### Node Hover
- - Highlight mesh (wireframe) appears around node
- - Connected edges turn amber (#f59e0b)
- - Tooltip shows: content, type badge, meta (time, heat, domain)
- - Label becomes visible
-
- ### Node Click
- - Detail panel opens from right
- - Non-connected nodes fade to 12% opacity
- - Connected edges highlight
- - No zoom-to-node (preserves spatial context)
-
- ### Panel Close
- - ESC key or close button
- - All nodes restore full opacity
- - Camera stays in current position
-
- ### Search
- - Real-time filtering of visible nodes
- - Matches against content, tags, domain, entity name
- - Triggers graph rebuild with force simulation reheat
-
- ### Type Filter
- - All / Episodic / Semantic / Entity buttons
- - Triggers full graph rebuild
- - Force simulation reheats on filter change
-
- ---
-
- ## Animation
-
- | Element | Property | Duration | Easing |
- |-----------------|-----------------|----------|---------------------------------|
- | Panel slide | transform | 450ms | cubic-bezier(0.16, 1, 0.3, 1) |
- | Camera fly | position | 1000ms | ease-out cubic |
- | Node opacity | opacity | 300ms | linear |
- | Tooltip | display | instant | - |
- | Filter button | background | 300ms | ease |
- | Loading fade | opacity | 1000ms | linear |
- | Auto-rotate | orbit | continuous | 0.15 deg/frame |
- | Entity spin | rotation.y | continuous | 0.004 rad/frame |
- | Dust drift | position | continuous | linear |
- | Flow particles | position | continuous | linear along edge |
- | Force sim | node positions | ~660 frames | alpha decay 0.0015 |
-
- ---
-
- ## Node Sizing
-
- | Node Type | Base Scale | Scale Factors | Range |
- |-----------|-----------|-----------------------------------|-----------|
- | Memory | 1.2 | + importance * 1.0 + heat * 0.6 | 1.2 - 2.8 |
- | Entity | 1.8 | + heat * 1.2 | 1.8 - 3.0 |
-
- ---
-
- ## Edge Rendering
-
- | Edge Type | Color | Opacity Factor |
- |----------------|-----------|--------------------------|
- | Default | `#90a4ae` | 0.15 + weight * 0.35 |
- | Causal | `#ff4444` | 0.15 + weight * 0.35 |
- | Co-occurrence | `#d946ef` | 0.15 + weight * 0.35 |
- | Virtual | `#556677` | 0.06 + weight * 0.12 |
- | Highlighted | `#f59e0b` | 0.9 |
-
- ---
-
- ## Post-Processing
-
- - **Selective Bloom**: 2-pass compositing
- - Bloom strength: 0.8
- - Bloom radius: 0.5
- - Bloom threshold: 0.35
- - **Vignette**: darkness 1.2, factor 0.3
- - **Film Grain**: intensity 0.03
+ Unchanged from the previous version (hover/click/search/filter behavior) —
+ see `js/raycast.js`, `js/interaction.js`. Selection highlight ring recolored
+ to `--accent-ink`; edge highlight recolored to `--edge-highlight`.
---
## File Structure
```
ui/dashboard/
DESIGN.md # This file
- theme.css # All styles
+ theme.css # Chrome + data-family token definitions
+ panels.css # Panels, overlays, timeline, categories
js/
- config.js # Colors, categories, utilities
+ config.js # Colour bridge: CortexPalette → JMD.* constants
state.js # Reactive state + event bus
- scene.js # Three.js setup, bloom, camera
- nodes.js # Memory + entity node builders
+ scene.js # Three.js setup (no bloom/vignette/grain)
+ nodes.js # Memory + entity node builders (flat colour)
edges.js # Edge lines, fiber tracts, flow particles
- effects.js # Ambient dust
- graph.js # Force simulation, raycasting, animation loop
+ edge_fx.js # Per-frame edge/particle updates, highlight/reset
+ effects.js # Ambient dust (neutral, non-additive)
+ atom.js # Atom-shell shell layout + shell guides
+ raycast.js # Raycasting, selection, animation loop, direct render
+ graph.js # Force layout glue, data build
interaction.js # Tooltip, detail panel, keyboard shortcuts
- timeline.js # Timeline overlay view
+ timeline.js # Timeline overlay view
categories.js # Categories overlay view
- analytics.js # Analytics panel charts
+ analytics.js # Analytics panel charts (data-token colours)
controls.js # UI button handlers
polling.js # API polling
stats.js # Header stats bar
```
---
## API Contract
- **Endpoint**: `GET /api/dashboard`
-
- **Response**:
- ```json
- {
- "stats": {
- "total": 87,
- "active": 26,
- "episodic": 14,
- "semantic": 12,
- "entities": 61,
- "relationships": 212,
- "avg_heat": 0.342,
- "engram_total_slots": 128,
- "engram_occupied_slots": 26,
- "triggers": 5,
- "protected": 3
- },
- "hot_memories": [...],
- "entities": [...],
- "relationships": [...],
- "domain_counts": {...},
- "recent_memories": [...]
- }
- ```
+ Unchanged — **Endpoint**: `GET /api/dashboard`. See `cortex_viz/server/http_dashboard_data.py`.