portal/DESIGN.md

CTAO Science Portal — design system

Single source of truth for look-and-feel. All values live as tokens in src/styles/global.css; this file states the rules. Brand basis: CTAO Brand Guidelines (Apr 2024) + techniques observed on ctao.org (nebula motion, generous spacing, 15/30/60 rounding). No frameworks, no JS for presentation.

Color tokens (brand-fixed — never add hues)

Token	Value	Use
--galaxy	#00004A	Headings, header/footer/hero bands
--cherenkov	#00E4D8	Accents, flash, CTAs, hero subtitle. Never small text on light bg
--moon	#F5F5F5	Utility surfaces (bands, TOC, chips)
--azure	#007AFF	Focus rings, hover borders (UI only on light)
--indigo	#00009C	Gradient depth, link hover
--text / --muted / --border / --link	derived	Body ink; --link #0057C2 is azure darkened to pass AA

Typography

Role	Font	Rule
h1, h2	Space Grotesk (--font-display)	Headlines ONLY (brand D.3.2)
Everything else	Inter (--font-body)	Includes h3+, cards, UI

Always end font-family with a generic (sans-serif) — lint requirement.

Spacing scale (fluid; mobile ≈ min, desktop ≈ max)

Token	Value	Use
--gutter	clamp(18px, 4vw, 28px)	Container/menu side padding
--space-s	12px	Chip gaps, small stacks
--space-m	20px	Card/panel padding, grid gaps
--space-l	24–40px	Article top, meta/cover margins, featured body
--space-xl	40–72px	Section rhythm: every .page block, footer top
--space-band	48–96px	Hero + auth band vertical padding

Rule: section/container/card padding comes from this table — no ad-hoc px. Prose-internal margins (h2/p/blockquote) are content-local and stay as written.

Radius & elevation

Radius: --radius 16px (cards/panels), --radius-pill (buttons, chips, inputs).

Only two shadows exist, both Galaxy-tinted (rgba(0,0,74,…)):

Token	Use
--shadow-ambient	Resting cards, panels, search rows
--shadow-lifted	Hover/focus cards, dropdowns (suggest, mobile menu), auth card

Never write a literal box-shadow; compose focus rings as 0 0 0 2px var(--azure), var(--shadow-lifted).

Surfaces

Rhythm per page: Galaxy hero band → content → Galaxy footer (flush, no margin). White = editorial (news grids, articles). .band--moon = service/utility sections (home Services, /search, /support, /proposals, /dashboard). Cards and panels are always white and pop against Moon via border + ambient shadow.

Motion policy (CSS-only, Apple-tier restraint)

ctao.org animates nebula videos under Galaxy vignettes; our translation:

1. Band nebula — one --nebula stack (Cherenkov .38 / Azure .33 / Indigo .80 radial fields) used by hero + auth bands, static and animated alike; the animated variant is an oversized .band-bg::before layer drifting via transform only, 22s alternate. Clearly visible glow, never neon. .band-bg (first child of every band) owns the overflow: hidden clip — NEVER put overflow on the band itself: it would clip overlays like the search-suggest dropdown.
2. Whole-page ambient — .has-ambient::before: fixed brand-hue wash (Cherenkov .16 / Azure .12 / Indigo .10 — visible pastel fields, white cards pop against them) drifting on a 60s alternate cycle. Opt-in per page via <Base ambient>: home only. Login's full-viewport auth nebula already is its ambient; news/article/utility pages stay calm (reading focus). Body text NEVER sits on a moving gradient — cards, panels and bands are solid layers above it.
3. One-shot hero rise stagger; hover lift/transitions, incl. the card-cover micro-zoom (scale 1.03, clipped by the card — AstroWind pattern). Nothing else.

Rules:

• ALL animation/transition declarations live inside the single @media (prefers-reduced-motion: no-preference) block at the end of global.css; the reduce block additionally force-disables everything.
• Animate transform/opacity only (compositor-only, per web.dev/MDN); never background-position/box-shadow in keyframes. No will-change (animated properties are auto-promoted — MDN). No filter: blur on large layers and no background-attachment: fixed (broken on iOS) — the wash is a fixed-position layer with pre-blurred radial gradients. No JS, no scroll-triggered motion.
• Static gradients remain as the reduced-motion fallback (bands swap them for the animated layer — never both, keeping contrast bounded; the ambient wash simply stops moving).
• If an effect calls attention to itself as an effect, cut it.

WCAG 2.1 AA notes (computed, worst-case animation frames)

• Nebula blob peaks over Galaxy: Cherenkov α=.38 → white 7.9:1, Cherenkov subtitle 4.9:1, eyebrow #C7CDE9 5.0:1. Azure α=.33 → all ≥ 7.7:1. Indigo α=.80 → all ≥ 9.6:1. Cherenkov/Azure CORES must stay in opposite corners (core-over-core would fail; fringe overlap ≈ 6:1).
• On Moon: --link 6.1:1, --muted 7.1:1, --text 16.9:1.
• Ambient wash worst overlap (rgb(188,237,249)): --link 5.3:1, --muted 6.2:1, Galaxy h2 15.2:1.
• Ceilings: nebula ≤ .38 Cherenkov / ≤ .35 Azure; wash ≤ .16/.12/.10 — recompute (WCAG relative luminance) if any alpha or hue placement changes.
• Focus visible everywhere; tap targets ≥ 44px; skip link first.

Article TOC pattern

Rendered only when ≥3 h2/h3. Two renderings of the same list (only one ever displayed): <details class="toc toc--inline"> collapsed under the title (< 1200px) and <nav class="toc toc--rail"> sticky right rail (≥ 1200px, outside the 70ch column via .article-layout grid). MDN/Stripe/NN-g pattern.

Scrollspy (Starlight's starlight-toc pattern, minimal vanilla): an IntersectionObserver band under the sticky header maps the visible prose block to its governing heading and sets aria-current="true" on the TOC link (Galaxy + 600 weight). Functional state, not motion — the "no JS motion" rule is untouched; the TOC works fully without JS. Same precedent covers the search <mark> term highlight (Cherenkov tint) and the .pagination pill nav (Galaxy pill = current page, 44px targets).

Do not

• No new hues, tints, or grays — derive via color-mix from brand tokens only.
• No Space Grotesk outside h1/h2. No dark theme.
• No ad-hoc spacing/shadow/radius values; extend the token tables instead.
• No animation/transition outside the no-preference block; no JS motion.
• No dependencies/frameworks (CSS or JS). No removal of "Mock" badges.
• Don't lighten text over navy bands below the alphas listed above.
• No clip-path/CSS approximations of brand assets — the flash is the real SVG path from the official logo, or nothing.
• Decoration budget: max ONE accent element per view (currently: footer flash, static). No twinkles, floating shapes, or stacked decorations.