# Nocturne Brand & Design Guidelines Version 0.1.0 · Apache-2.0 Nocturne is a Cyberpunk 2077 / Night City visual language. It is loud, dark, and technical: near-black surfaces lit by a single hot neon accent, sharp clipped corners, monospaced labels, and just enough glow to feel like a heads-up display. This document is the source of truth for how the brand looks and behaves. When code and this document disagree, fix the code. --- ## 1. Brand principles 1. **One light source.** A view has a single focal accent, usually Nocturne yellow. Everything else is structure. If two things glow equally, nothing does. 2. **Dark by default.** Nocturne is a dark system. There is no light theme in v0.1. Surfaces sit near black so neon reads. 3. **Sharp, not soft.** Corners are clipped, not rounded. Radii stay under 6px. Elevation comes from glow, not blurry drop shadows. 4. **Machine voice.** Labels, badges and metadata are uppercase monospace with wide tracking. They read like terminal output, not marketing copy. 5. **Restraint at scale.** The effects (scanlines, glitch, grid) are seasoning. One texture per surface, never stacked. --- ## 2. Logo The wordmark is **Nocturne** set in Rajdhani Bold, uppercase, letter-spacing `0.3em`, preceded by a glowing accent square. A suffix (like `OS` in the reference app) may be set in Nocturne yellow. - Master lockup: [`../assets/logo.svg`](../assets/logo.svg) - Mark only (the square): [`../assets/mark.svg`](../assets/mark.svg) ### Clear space Keep clear space around the logo equal to the height of the accent square on all sides. Nothing (text, edges, other marks) enters that zone. ### Minimum size - Wordmark: 96px wide on screen. - Mark alone: 16px. ### Do - Use the mark alone in tight spaces (favicons, avatars, nav at < 96px). - Put the wordmark on the page background (`--noct-bg`) or a dark surface. ### Don't - Recolor the wordmark. It is `--noct-text` with an optional yellow suffix. - Rotate, skew, add a second glow, or apply the glitch effect to the logo. - Place it on a light or busy background. It needs darkness to read. - Reconstruct it in a different typeface. --- ## 3. Color Nocturne is built on a near-black neutral ramp plus a small set of saturated neons. Never hard-code a hex value in product code, reference the semantic token (`--noct-primary`, `--noct-danger`, …). See [`color reference`](../../packages/tokens/src/tokens.json) for the full set. ### Neutrals (surfaces & text) | Token | Hex | Use | | --- | --- | --- | | `--noct-bg` | `#07070b` | Page background | | `--noct-surface` | `#10101a` | Cards, panels | | `--noct-elevated` | `#2a2a3d` | Raised fills, chips, hover | | `--noct-border` | `#3d3d52` | Hairline borders | | `--noct-border-strong` | `#5a5a78` | Interactive / emphasised borders | | `--noct-text` | `#f4f4f8` | Primary text | | `--noct-text-muted` | `#c4c4d4` | Labels, secondary text | | `--noct-text-dim` | `#8a8aa0` | Metadata, tertiary text | ### Accents (semantic) | Token | Hex | Meaning | | --- | --- | --- | | `--noct-primary` (yellow) | `#fcee0a` | Signature accent, primary actions, focus | | `--noct-info` (cyan) | `#00f0ff` | Informational, links, secondary highlight | | `--noct-danger` (magenta) | `#ff003c` | Errors, destructive actions | | `--noct-success` (green) | `#00ff9d` | Success, healthy, online | | `--noct-warning` (yellow) | `#fcee0a` | Warnings (shares the primary hue) | | `--noct-accent-violet` | `#7a3cff` | Extra categorical accent | | `--noct-accent-pink` | `#ff2e88` | Extra categorical accent | | `--noct-accent-orange` | `#ff8a00` | Pending / in-between states | ### Usage rules - **Yellow is precious.** It marks the one thing you most want a user to see: the primary button, the focus ring, the active tab. Do not paint large fills yellow. - **Accents mean things.** Magenta is danger, green is success, cyan is info. Do not use magenta decoratively next to a delete action, it will read as destructive. - **Neons on dark only.** Saturated neon on a light fill vibrates and fails contrast. Keep accents as text, borders, thin rails and glows over dark surfaces. - **Text pairs.** Yellow, cyan and green pass AA as text on `--noct-bg`. Magenta and violet are borderline, use them for large text, borders or fills with dark text, not body copy. See [`accessibility.md`](./accessibility.md). --- ## 4. Typography Two families do all the work. | Role | Family | Usage | | --- | --- | --- | | Display / UI | **Rajdhani** (400/600/700) | Headings, big numbers, the wordmark, general UI text | | Mono | **JetBrains Mono** (400/600) | Labels, badges, code, metadata, buttons, data | - Root font size is **17px**. All `rem` sizes derive from it. - **Headings**: Rajdhani, uppercase, tight tracking (`-0.01em`), `line-height: 1`. - **Labels & badges**: JetBrains Mono, uppercase, bold, wide tracking (`0.18em`–`0.2em`). This is the system's signature texture. - **Numbers**: always `font-variant-numeric: tabular-nums` so figures align. - **Body copy** (rare in Nocturne, it is a dashboard language): Rajdhani or mono at `--noct-text-sm`, `line-height: 1.35`. Type scale tokens: `--noct-text-xs` (0.7rem) → `--noct-text-4xl` (2.5rem). --- ## 5. Space & layout - 4px base grid, exposed as `--noct-space-1` (0.25rem) → `--noct-space-16` (4rem). - Max content width: `--noct-content-max` (1400px), centred. - Generous negative space around focal elements. Density is fine for data tables and chips, but panels breathe. --- ## 6. Shape & elevation - **Corners are clipped, not rounded.** Use `.noct-clip-corner` (12px) on cards and `.noct-clip-corner-sm` (6px) on buttons and tiles. Radii tokens (2–6px) exist for the few things that must be curved (inputs stay square). - **Left accent rail.** Cards, panels and alerts carry a 3px colored rail on their left edge. This is a load-bearing brand cue, keep it. - **Corner notches.** Panels add L-shaped 2px notches at the top/bottom-left corners. - **Elevation = glow, not shadow.** Interactive surfaces gain a soft colored glow on hover (`--noct-glow-*`). Avoid grey blurred drop shadows, they read as the wrong era. --- ## 7. Motion - Durations: `--noct-duration-fast` (150ms) for hovers, `base` (200ms) for surfaces, `slow` (300ms) for progress fills. - Easing: `--noct-ease-standard` for most transitions. - Signature animations: the pulsing status **dot**, the **skeleton** sweep, the glowing tab underline. Keep them subtle. - **Respect `prefers-reduced-motion`.** The token layer zeroes durations and the animated utilities disable themselves under reduced motion. Do not re-introduce motion that ignores it. --- ## 8. Textures & effects (use sparingly) | Utility | Effect | When | | --- | --- | --- | | `.noct-scanlines` | Faint horizontal CRT lines | Whole-page atmosphere, on `` | | `.noct-grid-lines` | 32px blueprint grid | Empty states, hero backdrops | | `.noct-bg-wash` | Two neon radial pools | Page background | | `.noct-text-glitch` | Cyan/magenta chromatic split | One-off accent words, never body text | Rules: one texture per surface. Never put glitch on the logo or on anything a user must read carefully. Effects are opacity ≤ 5% for a reason, do not turn them up. --- ## 9. Iconography - Reference app uses **Phosphor Icons**. Any clean, geometric, evenly-weighted line icon set works. Match stroke weight to the mono type (bold). - Icons inherit the current text color, tint them with accent tokens, not raw hex. - Keep icons functional. Nocturne is not an emoji system. --- ## 10. Do / Don't summary **Do** - Lead with one yellow focal point per view. - Keep surfaces dark and corners clipped. - Use uppercase mono for labels, tabular numerals for data. - Signal meaning with accent color (magenta = danger, green = success). - Reference tokens, never hex. **Don't** - Build a light theme or put neon on light fills. - Round corners or add soft grey shadows. - Stack textures or glitch readable text. - Spend yellow on decoration. - Ignore `prefers-reduced-motion` or contrast minimums. --- See also: [voice-and-tone.md](./voice-and-tone.md) · [accessibility.md](./accessibility.md) · the live [doc site](../index.html).