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).

## Header search & one-row width math

Search lives in the header. Desktop (≥1025px): compact GET-form pill (flex
130–180px) in the utility cluster; suggestions reuse `.suggest`. ≤1024px: a
44px magnifier `<details>` reveals a full-width search row under the header
(visible search beats search buried in a menu — NN/g mobile search). Both
forms are plain `GET /search` (full no-JS path); `<details name="header-panel">`
makes search + menu a native exclusive pair (no JS). The `/search` page stays
the full-results and deep-link target.

Nav content rule: the header nav reflects end-user tasks only (NN/g —
navigation mirrors user goals, not org tooling). The content editor is
internal-team tooling (SPEC §3.2), so it lives as a discreet "Content editor"
utility link in the footer, pointed to by the demo note; /admin keeps working
as the direct URL.

One-row invariant: `.nav > *` is `flex: none`; only the spacer and the search
field flex, so the row can never wrap or overflow. Tier math (Inter widths
estimated ±8%; logo 153:32 → 124px at 26px height; inner width = viewport −
2×gutter, container caps at 1120):

| Tier | Budget | Available |
|---|---|---|
| ≥1100 | brand+sub 247 + nav 415 + search 186 + Sign in 91 + gaps 16 ≈ 955 | 1044 @1100 |
| 1025–1099 (sub-brand hidden) | ≈ 842 | 969 @1025 |
| 481–1024 (menu + magnifier) | brand 134 + magnifier 44 + Sign in 91 + Menu 92 + gaps 16 ≈ 377 | 445 @481 |
| ≤480 (logo 22px, icon-only menu) | ≈ 312 | 339 @375 |
| ≤360 (compact paddings, gap 2) | ≈ 277 | 292 @320 |

The search field's 50px shrink range (180 → 130) absorbs estimate error in
every tier. No focus-grow on the field: a width transition would be a layout
animation (motion policy allows transform/opacity only) and an unanimated
snap is worse than a calm fixed width.

## Content & microcopy

- Card metadata must differentiate (NN/g: omit non-differentiating metadata):
  category and author are identical on all articles, so cards show
  date · reading time (body words ÷ 220 wpm, computed at build). Category and
  author remain on the article page; meta order there is
  category · author · date · read time.
- Badges: "Mock — <what's missing>" (bare "Mock" only on tiles); "External —
  <team>"; "Planned — not yet available". Mock badges are never removed.
- Terminology is fixed: "Sign in" (never Log in), "Editor", "Search", "News".
  Buttons start with a verb, sentence case. Real ellipsis (…), never "...".
- Search links (`.suggest a`, `.search-results a`) lay out as flowing text —
  never `display: flex` on the `<a>` itself: `<mark>` term-highlight splits the
  title into fragments, and flex would turn each into its own item.
- Overflow containment happens at the source: wide `.prose` tables scroll in
  their own box, long words/URLs wrap via `overflow-wrap`. The
  `html, body { overflow-x: clip }` rule is a regression guard, not a fix —
  never rely on it for new components.
- Articles end with `.post-nav` (Newer ← → Older from the date-sorted
  collection). Image captions: italic line under the image
  (`.prose img + em` / `p > em:only-child`), muted and smaller.

### Element rules (condensed)

| Element | Rule | Source |
|---|---|---|
| Phase banner | THE one loud demo disclosure: Moon bar above header, "Demo" tag + one sentence | GOV.UK phase banner |
| Header nav | End-user tasks only; order News · Data · Proposals · Dashboard · Support (entry first, help last, personal area next to Sign in) | NN/g serial-position |
| Header search | Compact field ≥1025px, magnifier reveal ≤1024px; both plain GET /search | NN/g site search |
| Hero (home) | Headline + brand subtitle + two task CTAs (Cherenkov primary, ghost secondary) + one-line Latest teaser. Never a second search box; no fake live widgets | hero-CTA convention, one-search-location |
| Badges | Quiet hairline pill, muted sentence-case text, Galaxy dot on mocks; "Mock — reason"; never removed | REQUIREMENTS §5, NN/g hierarchy |
| Cards | Cover · title (clamp 3) · desc (clamp 2) · date · read time; no non-differentiating metadata | NN/g metadata |
| Pagination | Newer/Older + windowed numbers, 44px targets, aria-current | NN/g pagination |
| Article | Back "← All news"; meta category · author · date · read time; italic muted captions; TOC at ≥3 headings; post-nav | editorial convention |
| Forms | Visible labels above fields; placeholders are examples only; buttons start with a verb | GOV.UK forms, NN/g |
| Login | One line + button + one small-print line; no reassurance prose | auth brevity |
| Footer | Identity line → Contact · Search · Disclaimer · Privacy · Site settings · Content editor → © line; no implementation talk in UI copy | NN/g footers |
| Search results | Links lay out as flowing text (mark-safe); date chip; "Press Enter for all results" hint | — |

## 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.