DESIGN.md

metadata

name: CitationEdge
description: Parallel multi-agent research analysis with graph intelligence.
colors:
  obsidian: '#000000'
  graphite: '#050505'
  basalt: '#0a0a0a'
  quartz-white: '#FFFFFF'
  ghost-silver: rgba(255, 255, 255, 0.5)
  moon-grey: rgba(255, 255, 255, 0.3)
  glass-white: rgba(255, 255, 255, 0.02)
  border-faint: rgba(255, 255, 255, 0.06)
  ice-blue: '#4DFFEF'
  verify-green: '#10B981'
  alert-red: '#EF4444'
typography:
  display:
    fontFamily: Instrument Serif, Georgia, serif
    fontSize: clamp(2.5rem, 6vw, 4.5rem)
    fontWeight: 400
    lineHeight: 1
    letterSpacing: '-0.04em'
  headline:
    fontFamily: Satoshi, Inter, system-ui, sans-serif
    fontSize: clamp(1.5rem, 3vw, 2.5rem)
    fontWeight: 600
    letterSpacing: '-0.03em'
  title:
    fontFamily: Satoshi, Inter, system-ui, sans-serif
    fontWeight: 600
    letterSpacing: '-0.02em'
  body:
    fontFamily: Satoshi, Inter, system-ui, sans-serif
    fontSize: 1rem
    fontWeight: 400
    lineHeight: 1.6
  label:
    fontFamily: DM Mono, JetBrains Mono, monospace
    fontSize: 0.7rem
    fontWeight: 500
    letterSpacing: 0.08em
    textTransform: uppercase
rounded:
  sm: 6px
  md: 10px
  lg: 14px
  xl: 20px
  pill: 99px
spacing:
  xs: 8px
  sm: 12px
  md: 16px
  lg: 24px
  xl: 32px
components:
  button-primary:
    backgroundColor: '{colors.quartz-white}'
    textColor: '{colors.obsidian}'
    rounded: '{rounded.md}'
    padding: 10px 24px
  button-primary-hover:
    backgroundColor: '{colors.quartz-white}'
    textColor: '{colors.obsidian}'
    rounded: '{rounded.md}'
    padding: 10px 24px
  button-secondary:
    backgroundColor: rgba(255, 255, 255, 0.05)
    textColor: '{colors.quartz-white}'
    rounded: '{rounded.md}'
    padding: 10px 24px
  glass-card:
    backgroundColor: '{colors.glass-white}'
    textColor: '{colors.quartz-white}'
    rounded: '{rounded.lg}'
  glass-card-hover:
    backgroundColor: rgba(255, 255, 255, 0.04)
    textColor: '{colors.quartz-white}'
    rounded: '{rounded.lg}'

Design System: CitationEdge

Overview

Creative North Star: "The Obsidian Observatory"

CitationEdge is a night observatory: absolute black surfaces, instruments of quiet precision, and one live signal glowing in the dark. The interface is built like a control room for the scientific literature — deep field backgrounds, glass panels that float over the darkness, and serif headlines that read like engraved instrument plates. The atmosphere is vast and contemplative: the user is not clicking through a dashboard, they are looking through a telescope at the citation landscape of their field.

The system is deliberately nearly monochrome. Almost everything is a shade of obsidian with white as the operative contrast; the single exception is the icy electric-blue signal accent (#4DFFEF), reserved for the moments the product is alive: the brand mark, the brand tag, and live indicators. Restraint is the identity — this is what separates it from the saturated-gradient pattern of typical AI-era SaaS.

Depth is conveyed through glass, not shadows: translucent panels, a film grain overlay across the whole app, and blurred backdrop surfaces that let the black breathe through. Components behave like engineered instruments — crisp, minimal, exact.

Key Characteristics:

• Pure-obsidian background field (#000000) with a fixed film-grain overlay at 3% opacity.
• Glass panels (rgba(255,255,255,0.02) + 14px radius + blur) instead of shadowed cards.
• One signal accent: icy electric blue, used rarely and deliberately.
• Serif display voice (Instrument Serif) over a Satoshi sans body; DM Mono for all identifiers.
• Mono uppercase labels, 8–32px spacing rhythm, 1200px container.

Colors

A cold mineral palette on absolute black: carbon blacks, one bright white, one signal cyan, and two status colors. The white/cyan pair is the entire expressive range; everything else is neutral scaffolding.

Primary

• Obsidian (#000000): the background field. The app's base, the navbar's base, the glass behind the glass. All surfaces rest on it.
• Quartz White (#FFFFFF): primary text, the primary button fill, headings. The operative contrast of the system; nothing is darker than the field.

Secondary

• Ice Blue (#4DFFEF): the signal accent. Used on the brand icon, the brand tag, and live/active signals. Never used as a fill or gradient; it is a point-light, not a surface.

Neutral

• Graphite (#050505): secondary surface, one step off pure black.
• Basalt (#0a0a0a): tertiary surface, dropdown menus, deeper panels.
• Ghost Silver (rgba(255,255,255,0.5)): secondary text, paragraphs.
• Moon Grey (rgba(255,255,255,0.3)): muted text, timestamps, breadcrumbs.
• Glass White (rgba(255,255,255,0.02)): resting card/panel fill.
• Border Faint (rgba(255,255,255,0.06)): the standard 1px hairline; brightens to rgba(255,255,255,0.12) on hover/active.

Status

• Verify Green (#10B981): success, job completion, health OK. Glows softly via box-shadow on the indicator dot.
• Alert Red (#EF4444): errors, failures, logout. Never used decoratively.

Named Rules

The Signal Rule. Ice Blue appears on ≤5% of any screen, and only on the brand mark, the brand tag, and live signals. Its rarity is the point; the moment it becomes a fill or gradient, the system reads as generic SaaS.

Typography

Display Font: Instrument Serif (with Georgia, serif) Body Font: Satoshi (with Inter, system-ui) Label/Mono Font: DM Mono (with JetBrains Mono)

Character: An engraved-instrument pairing — a delicate serif for the headlines that feels like letterpress on obsidian, a quietly confident grotesque for the body, and a technical monospace for everything machine-derived. The serif is the observatory's voice; the mono is its readout.

Hierarchy

• Display (400, clamp(2.5rem, 6vw, 4.5rem), 1.0, -0.04em): page-defining headlines — hero, page titles. Serif, weight 400, tight tracking.
• Headline (600, clamp(1.5rem, 3vw, 2.5rem), -0.03em): section headers.
• Title (600, -0.02em): cards, panel headers, sub-sections.
• Body (400, 1rem, 1.6): paragraphs and default text, Ghost Silver by default.
• Label (500, 0.7rem, 0.08em, uppercase): form labels, field captions, metadata — always DM Mono, always uppercase.
• Identifier (400, 0.7–0.85rem, mono): job IDs, breadcrumb IDs, timestamps, status readouts — DM Mono at a smaller size, Moon Grey.

Named Rules

The One Display Serif Rule. Instrument Serif is the single display voice. The incumbent Playfair Display (navbar wordmark) and Fraunces (graph page) are consolidation targets: new work must use Instrument Serif, and drift should be migrated as surfaces are touched.

Layout

A single centered column on a 1200px container with 24px gutters; .page sections start at 100px top padding to clear the fixed 64px navbar. The spacing rhythm is 8 / 12 / 16 / 24 / 32px, driven by gap and margin — never by padding hacks. The navbar is fixed, full-width, translucent, and centers its links absolutely; on screens below 768px the nav links and health indicator hide, and the right-side controls remain. Cards and panels sit within the column; the landing surface breaks out of the container for full-bleed hero moments.

Elevation & Depth

The system is flat-by-default with glass depth: there are no elevation shadows on resting surfaces. Depth comes from three layers of translucency — the black field, the film grain at 3% opacity over everything, and glass panels (10px blur) that let the field shimmer through. Shadows exist only for floating, transient surfaces: toasts and dropdowns use a single deep drop shadow (0 10px 30px rgba(0,0,0,0.5)).

Named Rules

The Glass-Not-Shadow Rule. Panels are translucent, not elevated. If a surface needs to separate from the field, blur it and brighten its hairline — do not cast a shadow. Shadows are reserved for floating transient chrome (toasts, menus).

Shapes

A soft-instrument radius language: 6px for fine details (nav links, brand tag), 10px for controls (buttons, inputs), 14px for glass panels, 20px for large surfaces. Pills (99px) are reserved for identity and status elements — the health indicator, avatar button — never for content surfaces. The scrollbar is a 4px monochrome hairline. All radii are uniform per element class; no hybrid corners.

Components

Buttons

• Shape: gently curved (10px radius), 10px 24px padding, 600 weight.
• Primary: Quartz White fill, black text — the single high-contrast action. Hover: opacity 0.9 with a 1px lift (translateY(-1px)); transition 0.3s cubic-bezier(0.16, 1, 0.3, 1).
• Secondary: glass fill (rgba(255,255,255,0.05)) with a faint hairline; hover brightens fill to 0.1 and border to 0.12.
• Submission buttons (full-width forms): white fill, 14px padding, 700 weight, with a sheen sweep animation on the top edge.

Chips / Indicators

• Health indicator: pill (99px), 0.75rem, Ghost-Silver text, glass fill with faint border. State variants: .ok (Verify Green text + border, glowing dot), .error (Alert Red).
• Brand tag: 3px radius, 0.55rem uppercase, Ice Blue text on transparent with an Ice Blue hairline; positioned as a superscript.

Cards / Containers

• Corner Style: gently curved (14px radius).
• Background: Glass White (rgba(255,255,255,0.02)) with a 1px Border Faint hairline and 10px backdrop blur.
• Shadow Strategy: none — see Elevation & Depth.
• Internal Padding: 24px standard.
• Hover: fill brightens to 0.04, hairline to 0.12.

Inputs / Fields

• Style: 1px hairline, 10px radius, 13px 16px padding, 14px text, #0F0F12 fill (one step off the field).
• Labels: DM Mono, 0.7rem, uppercase, 0.08em tracking, 6px above the field.
• Focus: no outline — the hairline shifts to Ice Blue and a 3px Ice Blue glow (0 0 0 3px rgba(77,255,239,0.12)) blooms around the field.
• Placeholder: Moon Grey at 50% (15% white).
• Error / Disabled: Alert Red hairline for errors; disabled dims to 30% white text.

Navigation

• Structure: fixed 64px bar, rgba(0,0,0,0.4) fill with 12px backdrop blur, 1px faint bottom hairline, 24px side padding.
• Wordmark: serif brand name (Playfair Display, 1.45rem, 600) next to a light sans companion (Inter, 1.25rem, 400) and the Ice Blue brand tag. Consolidation target per The One Display Serif Rule.
• Links: centered, 0.85rem, Ghost Silver at rest; hover brightens to white on a 5% glass fill; active is white on 10% glass.
• Avatar: pill button with hairline; dropdown panel is Basalt with 12px radius and the floating-shadow treatment.

Signature Component: the Global Grain

A fixed, full-viewport film-grain overlay (feTurbulence noise at 3% opacity, pointer-events none, z-index above everything) sits over the entire app. It is the material signature of the observatory: without it, the black is flat video; with it, the black is film.

Do's and Don'ts

Do:

• Do keep the grain. The global-grain overlay is the material signature — new surfaces must not strip it.
• Do use DM Mono uppercase labels for every form label, field caption, and job identifier.
• Do use Instrument Serif for display headlines; migrate Playfair/Fraunces drift when touching those surfaces.
• Do use 10px radius for controls, 14px for glass panels, pills only for status/identity elements.
• Do keep the spacing rhythm on the 8/12/16/24/32 scale.
• Do render depth with blur and hairlines, not shadows — except floating chrome (toasts, dropdowns).

Don't:

• Don't use a second blue. #4D9EFF in Auth.css focus rings is drift: focus treatment should use the Ice Blue signal. Audit test: grep for #4D9EFF — it must not exist.
• Don't color the Ice Blue as a gradient, a button fill, or a card background. It is a point-light.
• Don't use gray text on glass/colored surfaces — Ghost Silver and Moon Grey belong on the black field only.
• Don't introduce pure-white flat panels: surfaces are translucent glass, never opaque cards.
• Don't invent --accent-2-style orphan tokens — DocsPage.css references one that is undefined; every color must resolve to the token file.
• Don't use Arial, default system serif, or saturated purple/blue gradients anywhere.
• Don't wrap cards in cards; the glass panel is the deepest nesting level.