Repository Public
1# Note Visual System 2.0 — « Graphite & Ultramarine · Lumen »23Web implementation: `src/app/globals.css` (tokens, chrome, editor, blocks) + `src/lib/client/motion.ts` (motion layer).4Shared contract: `SPEC.md` §5. Native counterpart: module `SPNotesDesign` in SPNotesCore.5Every token name of 1.x / 2.x still works; 2.0 only adds.67## 1. Colour89The web sources of truth are the **oklch** values in `:root` / `.dark`. The table gives their **measured sRGB conversion**10(`node scripts/contrast.mjs`, out-of-gamut channels clipped as browsers do; the same values are read back from a browser canvas in `tests/e2e/next-web.spec.ts`, tolerance 2/255).11**They differ from the approximations of SPEC §5 by more than a rounding error** (column Δ = largest channel difference, 0–255):12the SPEC values are bluer/lighter in the dark neutrals and more violet in the accent. Native teams should use the *measured* columns13to be pixel-aligned with the web.1415| CSS token | Swift name | light (measured) | light (SPEC) | Δ | dark (measured) | dark (SPEC) | Δ |16|---|---|---|---|---|---|---|---|17| `--bg` | `bg` | `#F9FBFD` | #F9FAFC | 1 | `#0D1016` | #12141C | 6 |18| `--bg-elev` | `bgElevated` | `#FFFFFF` | #FFFFFF | 0 | `#15181F` | #1A1D27 | 8 |19| `--bg-sunk` | `bgSunken` | `#F0F3F6` | #F1F3F7 | 1 | `#080A0F` | #0D0F15 | 6 |20| `--bg-side` | `bgSidebar` | `#F3F6F9` | #F4F6F9 | 1 | `#0A0C12` | #0F1118 | 6 |21| `--bg-hover` | `bgHover` | `#EAEDF2` | #EBEEF4 | 2 | `#1D2028` | #222633 | 11 |22| `--fg` | `fg` | `#151922` | #161A26 | 4 | `#E8EBEF` | #EBEEF4 | 5 |23| `--fg-muted` | `fgMuted` | `#535862` | #535B6E | 12 | `#A0A5AE` | #A6AEC0 | 18 |24| `--fg-faint` | `fgFaint` | `#848992` | #8A91A3 | 17 | `#6A6F77` | #707889 | 18 |25| `--line` | `line` | `#E1E4E8` | #E3E6EC | 4 | `#22252D` | #262A36 | 9 |26| `--line-strong` | `lineStrong` | `#CCD0D5` | #CFD4DE | 9 | `#333640` | #363B4A | 10 |27| `--accent` | `accent` | `#2F5DDB` | #3157D5 | 6 | `#7CA5FF` | #8AA2FF | 14 |28| `--accent-fg` | `accentFg` | `#FBFCFE` | #FBFCFF | 1 | `#090F1C` | #0B1230 | 20 |29| `--accent-soft` | `accentSoft` | `#E5F0FF` | #E9EEFF | 4 | `#1B2A4C` | #1F2C5C | 16 |30| `--ai` | `ai` | `#7E41D2` | #7A3FD6 | 4 | `#B999FB` | #B699FF | 4 |31| `--ai-soft` | `aiSoft` | `#F3ECFF` | #F1EAFF | 2 | `#302249` | #33205E | 21 |32| `--success` | `success` | `#008B4E` | #2E8B57 | 46 | `#5BC083` | #6CCB93 | 17 |33| `--warning` | `warning` | `#D98B09` | #C98A1A | 17 | `#F2AF48` | #F0BC5E | 22 |34| `--danger` | `danger` | `#CC272E` | #D14343 | 28 | `#F26A64` | #F08A80 | 32 |3536Also: `--focus` (= accent, solid focus ring), `--ring` (accent at 35–40 % alpha, halos only), `--glass` (surface at 66–68 % alpha),37`--glass-line` (hairline of glass surfaces), `--lumen`, `--lumen-soft`. Tailwind utilities: `bg-bg`, `text-fg-muted`,38`border-line`, `bg-accent-soft`, `text-ai`, `outline-focus`, `bg-glass`…3940### Contrast (WCAG 2.2), both themes — `pnpm contrast` (exit code 1 on a failure; also a unit test)4142| theme | pair | sRGB | ratio | required | use |43|---|---|---|---|---|---|44| light | fg on bg | #151922 / #F9FBFD | **16.89** | ≥ 4.5 | body text |45| light | fg on bg-elev | #151922 / #FFFFFF | **17.53** | ≥ 4.5 | text on cards |46| light | fg on bg-sunk | #151922 / #F0F3F6 | **15.75** | ≥ 4.5 | text on sunken surfaces |47| light | fg on bg-side | #151922 / #F3F6F9 | **16.17** | ≥ 4.5 | sidebar text (active) |48| light | fg on bg-hover | #151922 / #EAEDF2 | **14.97** | ≥ 4.5 | hovered row |49| light | fg-muted on bg | #535862 / #F9FBFD | **6.87** | ≥ 4.5 | secondary text |50| light | fg-muted on bg-elev | #535862 / #FFFFFF | **7.13** | ≥ 4.5 | secondary text on cards |51| light | fg-muted on bg-side | #535862 / #F3F6F9 | **6.57** | ≥ 4.5 | sidebar items |52| light | fg-muted on bg-sunk | #535862 / #F0F3F6 | **6.4** | ≥ 4.5 | secondary text on sunken |53| light | fg-muted on bg-hover | #535862 / #EAEDF2 | **6.09** | ≥ 4.5 | secondary text on hover |54| light | fg-faint on bg | #848992 / #F9FBFD | **3.37** | ≥ 3 | placeholders / decorative labels (large or non-essential: AA 3:1) |55| light | fg-faint on bg-side | #848992 / #F3F6F9 | **3.23** | ≥ 3 | sidebar section labels |56| light | accent on bg | #2F5DDB / #F9FBFD | **5.44** | ≥ 4.5 | links |57| light | accent on bg-elev | #2F5DDB / #FFFFFF | **5.65** | ≥ 4.5 | links on cards |58| light | accent on accent-soft | #2F5DDB / #E5F0FF | **4.91** | ≥ 4.5 | accent text on its soft chip |59| light | accent-fg on accent | #FBFCFE / #2F5DDB | **5.49** | ≥ 4.5 | primary button label |60| light | ai on bg | #7E41D2 / #F9FBFD | **5.64** | ≥ 4.5 | AI text |61| light | ai on ai-soft | #7E41D2 / #F3ECFF | **5.07** | ≥ 4.5 | AI text on its soft surface |62| light | ai on bg-elev | #7E41D2 / #FFFFFF | **5.85** | ≥ 4.5 | AI text on cards |63| light | danger on bg | #CC272E / #F9FBFD | **5.18** | ≥ 4.5 | error text |64| light | success on bg | #008B4E / #F9FBFD | **4.19** | ≥ 3 | success icons / large text |65| light | warning on bg | #D98B09 / #F9FBFD | **2.65** | info | warning hue — informational: paired with a text label in fg, never used alone as text |66| light | focus on bg | #2F5DDB / #F9FBFD | **5.44** | ≥ 3 | focus ring (non-text: 3:1) |67| light | focus on bg-elev | #2F5DDB / #FFFFFF | **5.65** | ≥ 3 | focus ring on cards |68| light | focus on bg-side | #2F5DDB / #F3F6F9 | **5.21** | ≥ 3 | focus ring in the sidebar |69| light | line-strong on bg | #CCD0D5 / #F9FBFD | **1.5** | info | decorative separators — informational |70| dark | fg on bg | #E8EBEF / #0D1016 | **16** | ≥ 4.5 | body text |71| dark | fg on bg-elev | #E8EBEF / #15181F | **14.87** | ≥ 4.5 | text on cards |72| dark | fg on bg-sunk | #E8EBEF / #080A0F | **16.59** | ≥ 4.5 | text on sunken surfaces |73| dark | fg on bg-side | #E8EBEF / #0A0C12 | **16.38** | ≥ 4.5 | sidebar text (active) |74| dark | fg on bg-hover | #E8EBEF / #1D2028 | **13.62** | ≥ 4.5 | hovered row |75| dark | fg-muted on bg | #A0A5AE / #0D1016 | **7.69** | ≥ 4.5 | secondary text |76| dark | fg-muted on bg-elev | #A0A5AE / #15181F | **7.15** | ≥ 4.5 | secondary text on cards |77| dark | fg-muted on bg-side | #A0A5AE / #0A0C12 | **7.87** | ≥ 4.5 | sidebar items |78| dark | fg-muted on bg-sunk | #A0A5AE / #080A0F | **7.97** | ≥ 4.5 | secondary text on sunken |79| dark | fg-muted on bg-hover | #A0A5AE / #1D2028 | **6.55** | ≥ 4.5 | secondary text on hover |80| dark | fg-faint on bg | #6A6F77 / #0D1016 | **3.77** | ≥ 3 | placeholders / decorative labels (large or non-essential: AA 3:1) |81| dark | fg-faint on bg-side | #6A6F77 / #0A0C12 | **3.86** | ≥ 3 | sidebar section labels |82| dark | accent on bg | #7CA5FF / #0D1016 | **7.86** | ≥ 4.5 | links |83| dark | accent on bg-elev | #7CA5FF / #15181F | **7.31** | ≥ 4.5 | links on cards |84| dark | accent on accent-soft | #7CA5FF / #1B2A4C | **5.86** | ≥ 4.5 | accent text on its soft chip |85| dark | accent-fg on accent | #090F1C / #7CA5FF | **7.89** | ≥ 4.5 | primary button label |86| dark | ai on bg | #B999FB / #0D1016 | **8.19** | ≥ 4.5 | AI text |87| dark | ai on ai-soft | #B999FB / #302249 | **6.2** | ≥ 4.5 | AI text on its soft surface |88| dark | ai on bg-elev | #B999FB / #15181F | **7.62** | ≥ 4.5 | AI text on cards |89| dark | danger on bg | #F26A64 / #0D1016 | **6.37** | ≥ 4.5 | error text |90| dark | success on bg | #5BC083 / #0D1016 | **8.42** | ≥ 3 | success icons / large text |91| dark | warning on bg | #F2AF48 / #0D1016 | **10.02** | info | warning hue — informational: paired with a text label in fg, never used alone as text |92| dark | focus on bg | #7CA5FF / #0D1016 | **7.86** | ≥ 3 | focus ring (non-text: 3:1) |93| dark | focus on bg-elev | #7CA5FF / #15181F | **7.31** | ≥ 3 | focus ring on cards |94| dark | focus on bg-side | #7CA5FF / #0A0C12 | **8.05** | ≥ 3 | focus ring in the sidebar |95| dark | line-strong on bg | #333640 / #0D1016 | **1.59** | info | decorative separators — informational |9697`fg-faint` is for placeholders, section labels and decorative text only (≥ 3:1, not AA body text). The `warning` hue is never used98alone as text. Under `prefers-contrast: more`, muted text becomes `fg`, hairlines become `line-strong`, glass becomes opaque and the99focus ring is 3 px. Under `forced-colors` the ring uses the system `Highlight` colour.100101## 2. Signature gradient « Lumen »102103`--lumen: linear-gradient(135deg, var(--accent), var(--ai))`. Utilities `bg-lumen`, `text-lumen`; classes `.lumen-hairline`104(1 px gradient rule under a header — command center), `.lumen-dot` (save indicator), `.lumen-pulse` (capture), `--lumen-soft`105(tinted surface: canvas card). Use it for hero surfaces, the capture pulse, graph links and the AI shimmer — never as a text background.106107## 3. Typography (self-hosted, CSP `font-src 'self'`)108109| Role | Web | Apple | Token |110|---|---|---|---|111| UI | Inter Variable (`@fontsource-variable/inter`, roman + italic) | SF Pro | `--font-sans` / `font-sans` |112| Reading titles, quotes, optional body | Source Serif 4 Variable (roman + italic, optical size auto) | New York (`Font.Design.serif`) | `--font-serif` / `font-serif`, class `.page-title` |113| Code | JetBrains Mono Variable (ligatures off) | SF Mono | `--font-mono` / `font-mono` |114115Scale (px): micro 11 (`text-micro`), ui 13 (`text-ui`), body 16 (`text-body`; 17 on phones in the editor), h3 20, h2 24, h1 30,116display 40. Reading measure `--measure: 46rem` (`.measure`). Page titles are serif 600 with −0.018 em tracking.117Fonts are split by unicode-range: only the scripts on screen are downloaded.118119## 4. Spacing, radius, elevation120121| Scale | Tokens |122|---|---|123| Spacing (px) | `--space-1…9` = 2, 4, 8, 12, 16, 24, 32, 48, 64 (Tailwind `0.5, 1, 2, 3, 4, 6, 8, 12, 16`) |124| Radius (px) | `--r-xs` 4, `--r-sm` 6, `--r-md` 10, `--r-lg` 14, `--r-xl` 20, `--r-pill` 999 → semantic utilities `rounded-chip` (xs), `rounded-control` (sm), `rounded-pop` (md), `rounded-card` (lg), `rounded-sheet` (xl), `rounded-pill`. Tailwind's own `rounded-*` scale is unchanged. |125| Elevation | **card** `shadow-card` (hairline + 1 px shadow) · **pop** `shadow-pop` (16/40 blur) · **glass** utility `glass` / class `.chrome-glass` (backdrop blur 20 px, surface 66–68 %, hairline `--glass-line`); opaque fallback without `backdrop-filter`, under `prefers-reduced-transparency` and `prefers-contrast: more`. |126| Density | `html[data-density="compact"]` sets `--density: .72` (block spacing, sidebar rows 24 px, tighter headings). |127128Component classes: `.surface-card`, `.surface-pop`, `.icon-btn` (32 px), `.kbd-hint`, `.side-item`, `.side-section`,129`.ai-surface`, `.ai-mark`, `.ai-shimmer`, `.resize-handle`.130131## 5. Motion132133Tokens (CSS custom properties and `DUR` / `EASE` in `motion.ts`): instant 90 ms, fast 160 ms, base 240 ms, slow 420 ms, ambient134900 ms; easing standard `cubic-bezier(.2,.8,.2,1)`, exit `cubic-bezier(.4,0,1,1)`, spring (response .38, damping .82) as a135`linear()` curve over 620 ms (`--ease-spring`). Utilities `duration-instant|fast|base|slow`, `ease-standard|exit|spring`.136Rules: only `opacity`, `transform`, `filter` are animated (compositor only); layout is read at most once per motion and never137while typing; ProseMirror nodes are animated with the Web Animations API or decorations (it strips foreign classes).138139| # | Motion | Web implementation | Duration / easing | Reduce Motion |140|---|---|---|---|---|141| 1 | Living Pages | `revealBlocks()` on page open: the first 24 blocks rise 6 px + fade, 18 ms stagger (WAAPI on the block elements) | 240 ms, standard | one 120 ms cross-fade of the editor |142| 2 | Morphing Editor | `ContextBar`: tools follow the block type (table, code, callout, image, task); new content `.morph-in`, width tween `morphWidth()` | 160 ms, standard | 120 ms fade, no width tween |143| 3 | Knowledge Connections | **not in this wave** (graph 2.0 screens are built later on these tokens) | — | — |144| 4 | Fluid Navigation | `navigateWithTitle()`: View Transitions API, shared element `page-title` (sidebar row → page title); plain navigation where the API is missing | 240 ms group, 160 ms root | 120 ms cross-fade, shared element cancelled |145| 5 | Intelligent Panels | `.panel-in-right|left|bottom`: 18 px slide + 6 px blur → sharp (AI panel, right panel host, phone assistant) | 240 ms, standard | 120 ms fade |146| 6 | Quick Capture | sheet `.scale-in` (from .96); `lumenPulse()` gradient disc on save | 160 ms in; pulse 580 ms | fade; static 240 ms glow, no scale |147| 7 | Semantic Zoom | `semanticZoom()`: cross-dissolve around the level change, scroll anchor = first visible `[data-id]` block; used by the outline zoom (level 2 ↔ 3) | 80 ms out + 160 ms in | 60 ms out + 120 ms in |148149Other classes: `.fade-up` (popovers, menus), `.sheet` (bottom sheets), `.drawer` (phone drawer slide-in — the class had no rule150before), `animate-in` (overlay fade — the utility did not exist before).151152## 6. Shell153154- **Sidebar**: collapsible sections (Pinned, Databases, Workspace, Intelligence; state in `localStorage["note-tree-open"]`), ⌥-click or155 "Open to the side" on a page row.156- **Right panel host** (`RightPanel.tsx`, ≥ 1024 px): resizable (pointer + ←/→ on the separator), tabs = registered panels.157 Register a panel: `registerPanel({ id, title, icon, available?, tone?, render })` from `src/lib/client/panels.ts`, open it with158 `useUI().openPanel(id, arg)`. Shipped: `outline`, `page` (second editable page with its own autosave).159- **Universal Command Center** (⌘K, phone: header button): `registerCommands([{ id, title, group, keywords?, shortcut?, icon?, when?, priority?, run }])`160 from `src/lib/client/commands.ts` (returns the unregister function — call it from an effect). Ranking: `fuzzyRank`; recents are device-local.161162## 7. Do / Don't163164- Do use the semantic radii and the type tokens in chrome; don't add new arbitrary `text-[13px]` / `rounded-[…]` where a token exists.165- Do keep violet (`--ai`) for model output only, always with a label ("AI", `.ai-mark`); don't use it for decoration.166- Do animate through `motion.ts` or the motion classes; don't animate `width/height/top/left` of document content, and never add a class to a ProseMirror node.167- Do keep wide content scrolling inside its block (`.nb-scroll`); don't let a block widen the page (phones: one scroll container, `--kb` inset).168- Don't put text on the Lumen gradient or use glass under long-form text; glass is for chrome that floats over content.169- Don't remove or rename a token: the native apps mirror these names.170171172## Small semantic text (SPEC §7 amendment, applied in the integration pass)173174Semantic hues used as **small text** have their own tokens; fills, icons and borders keep the base hues.175176| CSS variable | Tailwind class | light | dark | contrast on `bg` / `bg-elev` / `bg-sunk` (light) |177|---|---|---|---|---|178| `--success-text` | `text-success-text` | `#006B3C` | `#5BC083` (= `--success`) | 6.39 / 6.63 / 5.95 |179| `--warning-text` | `text-warning-text` | `#8A5A00` | `#F2AF48` (= `--warning`) | 5.71 / 5.93 / 5.33 |180| `--danger-text` | `text-danger-text` | `#B0181F` | `#F26A64` (= `--danger`) | 6.75 / 7.01 / 6.30 |181182Rule: a `text-success|warning|danger` class on an HTML element that holds text is written `text-…-text`; on an icon component it stays183the base hue. In CSS, `color: var(--danger)` for text is `color: var(--danger-text)`. `pnpm contrast` checks the nine light and nine184dark pairs at 4.5:1.185