0pt/docs/05-design-system.md

# 05 · Design system (mono)

Self-contained spec. This file is the source of truth for tokens + motion; the
tokens and CSS below are **already implemented** in `app/globals.css` and
consumed across `components/` and `app/` — this is not aspirational, it's a
description of what ships today, kept here so new screens stay on-brand.

Derived from the **mono / EVASION** template (itself v0-generated). Light, editorial, monochrome, sharp, with a single red accent and animated grain + scroll-reveal motion. **No photography** — imagery is rendered data. (Verified: no `<img>` or `next/image` usage anywhere in `app/` or `components/` except a single unused leftover component, see "Vestigial component, not on the 'no photography' path" further down.)

> **Doc-index gap:** `CLAUDE.md`'s documentation index lists two files this doc used to point to — `docs/design/0pt-v0-build-brief.md` (per-component v0 prompts) and `docs/design/0pt-design-coverage-and-visuals.md` (full page/component inventory + visual rules). **Neither file exists anywhere in this repo** (confirmed via full-repo search). They are referenced but were never written. This doc no longer treats them as available references — anything they were supposed to cover (per-component prompts, the full visual-mapping table) is not documented anywhere right now. Whoever owns design docs next should either write them or remove the rows from `CLAUDE.md`'s index; not resolved in this pass.

## Tokens

Verified against `app/globals.css` (the file actually imported by `app/layout.tsx`):

```
THEME (light, default):
  --background #ffffff   --foreground #0a0a0a   --muted-foreground #737373
  --border #e5e5e5       --card #ffffff         --input #f5f5f5
THEME (dark sections — footer, editorial/manifesto block, technology/engine block):
  --background #0a0a0a   --foreground #fafafa   --muted-foreground #a3a3a3   --border #262626
ACCENT (single, sparing): red --accent-red #e40014   (one CTA / one number / one marker per screen)
PROVENANCE squares (ONLY non-mono color besides the red CTA):
  level 0 #737373 (unavailable/licensed) · 1 #143aff (single source) · 2 #fcbb00 (partial) · 3 #00d294 (corroborated)
RADIUS: 0 everywhere (`--radius: 0rem` in app/globals.css; shadcn/ui components inherit --radius-sm/md/lg/xl derived from it, so they render square too).
TYPE: Inter (everything; headlines weight 500–600, letter-spacing -0.02em, large) · JetBrains Mono (eyebrows, labels, numbers, codes, table headers — UPPERCASE, letter-spacing mostly 0.08–0.22em but ranging down to 0.02em on some labels/table headers (e.g. `provenance-badge.tsx`, the source table headers in `app/kallor/page.tsx`), ~10–12px, #737373). Loaded via `next/font/google` in `app/layout.tsx` as CSS vars `--font-inter` / `--font-jetbrains-mono`.
GRID: 8px base; graph-paper hairlines; generous whitespace; left-aligned headlines.
SECTION SPINE: real ordered indices 00–06 as mono eyebrows (hero=00, philosophy=01, catalog=02, [03 unused/reserved], collection/coverage=04, testimonials=05, pricing=06). The two dark sections (editorial "Manifesto", technology "The engine") intentionally break the numbered spine — they carry a text eyebrow instead of a number.
```

**Correction — a third section also breaks the spine, and it isn't dark:** verified render order in `app/page.tsx` is Hero(00) → Philosophy(01) → FeaturedProducts/Catalog(02) → **Technology (dark, no number)** → **GallerySection (no number)** → Collection(04) → **Editorial (dark, no number)** → Testimonials(05) → Pricing(06) → Footer(dark). `components/sections/gallery-section.tsx` sits exactly where a "03" would fall but carries a text eyebrow (`"— Visualizations"`) like the dark sections, plus its own unrelated local `01`–`05` indices on its five tiles (a per-tile counter, not a continuation of the page's section spine — don't confuse the two). So "03 unused/reserved" is accurate in that no section ever shows the numeral 03, but three sections break the numbered spine, not two — only two of those three happen to be dark-themed.

**Correction vs. previous version of this doc:** the dark theme was previously described as appearing on "footer, one editorial block" (2 places). Verified in `components/sections/`: **three** sections actually use the dark theme — `footer-section.tsx`, `editorial-section.tsx` (the "Manifesto" block), and `technology-section.tsx` (the "#motorn" / "The engine" block, `id="motorn"`). All three set `className="dark ..." ` and a `bg-[#0a0a0a] text-[#fafafa]` pairing.

**Implementation note (not yet reconciled in code):** `editorial-section.tsx` and `technology-section.tsx` use the documented dark border `#262626` consistently. `footer-section.tsx` instead hardcodes `#1f1f1f` for its borders — a different, undocumented shade. All three sections hardcode hex literals (`#0a0a0a`, `#fafafa`, `#737373`, `#a3a3a3`, plus the two different border shades) rather than referencing the `.dark` CSS-variable overrides that already exist in `app/globals.css`'s `--border`/`--foreground`/`--muted-foreground` tokens. This works today because the values happen to match (except the footer border), but it means the dark sections don't actually pick up `.dark`-scoped custom-property overrides — they're hand-pinned. Flagging as a small cleanup opportunity, not fixing here (out of scope for a docs pass).

## globals.css (already live in `app/globals.css` — do not re-add elsewhere)

The block below is the actual motion + grain CSS, condensed for reference. It ships today in `app/globals.css` (with the keyframes/classes spelled out at full length rather than this compact form — functionally identical):

```css
@keyframes reveal-up{0%{opacity:0;transform:translateY(60px)}to{opacity:1;transform:translateY(0)}}
@keyframes reveal-left{0%{opacity:0;transform:translateX(-60px)}to{opacity:1;transform:translateX(0)}}
@keyframes reveal-right{0%{opacity:0;transform:translateX(60px)}to{opacity:1;transform:translateX(0)}}
@keyframes scale-in{0%{opacity:0;transform:scale(.9)}to{opacity:1;transform:scale(1)}}
@keyframes fadeIn{0%{opacity:0;transform:scale(1.02)}to{opacity:1;transform:scale(1)}}
@keyframes slideUp{0%{opacity:0;transform:translateY(100%)}to{opacity:1;transform:translateY(0)}}
@keyframes float{0%,100%{transform:translateY(0)}50%{transform:translateY(-20px)}}
@keyframes grain{0%,100%{transform:translate(0,0)}10%{transform:translate(-5%,-10%)}20%{transform:translate(-15%,5%)}30%{transform:translate(7%,-25%)}40%{transform:translate(-5%,25%)}50%{transform:translate(-15%,10%)}60%{transform:translate(15%,0)}70%{transform:translateY(15%)}80%{transform:translate(3%,35%)}90%{transform:translate(-10%,10%)}}
.reveal{opacity:0}
.reveal.in-view{animation:.8s ease-out forwards reveal-up}
.reveal-left.in-view{animation:.8s ease-out forwards reveal-left}
.reveal-right.in-view{animation:.8s ease-out forwards reveal-right}
.reveal-scale.in-view{animation:.6s ease-out forwards scale-in}
.reveal-fade.in-view{animation:.7s ease-out forwards fadeIn}
.delay-1{animation-delay:.1s}.delay-2{animation-delay:.2s}.delay-3{animation-delay:.3s}.delay-4{animation-delay:.4s}.delay-5{animation-delay:.5s}.delay-6{animation-delay:.6s}
.animate-float{animation:6s ease-in-out infinite float}
.grain-overlay::before{content:"";position:absolute;inset:-100%;opacity:.03;pointer-events:none;background-image:url("data:image/svg+xml,%3Csvg viewBox='0 0 200 200' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.9' numOctaves='4' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)'/%3E%3C/svg%3E");animation:8s steps(10,end) infinite grain}
@media(prefers-reduced-motion:reduce){.reveal,.reveal-left,.reveal-right,.reveal-scale,.reveal-fade{opacity:1;animation:none}.animate-float,.grain-overlay::before{animation:none}}
```

The provenance colors and `--accent-red` also live in `app/globals.css` as CSS custom properties (`--accent-red`, `--prov-0..3`), exposed to Tailwind via `@theme inline` as `--color-accent-red`, `--color-prov-0..3`.

**Known leftover, unused file:** `styles/globals.css` also exists in this repo and is **not** imported anywhere (`app/layout.tsx` imports `./globals.css`, i.e. `app/globals.css`, only). `styles/globals.css` is a stray copy of the original shadcn/v0 scaffold — it uses `oklch()` colors, Geist/Geist Mono fonts, and `--radius: 0.625rem`, none of which match this design system. It is dead code. Don't edit it expecting it to affect the app, and consider deleting it in a future cleanup (not done in this pass — out of scope).

## Reveal / motion system

Three pieces work together; the doc previously only described one of them:

1. **`useReveal()` hook** — `hooks/use-reveal.ts`. Wire a section's ref with it; descendants carrying `.reveal` (+ optional `.reveal-left/-right/-scale/-fade` and `.delay-N`) animate to `.in-view` via `IntersectionObserver` (`threshold: 0.15`, `rootMargin: "0px 0px -10% 0px"`) when the section scrolls into view. **Difference from a naive IntersectionObserver:** if the section's top edge is already inside the viewport on mount (e.g. direct navigation to a page whose hero is already visible), the hook applies `.in-view` immediately via `requestAnimationFrame` instead of waiting for a scroll event — this avoids a flash of invisible content on first paint.
   ```tsx
   "use client";
   import { useEffect, useRef } from "react";
   export function useReveal<T extends HTMLElement = HTMLElement>() {
     const ref = useRef<T>(null);
     useEffect(() => {
       const el = ref.current;
       if (!el) return;
       const applyReveal = () => {
         el.querySelectorAll(".reveal, .reveal-left, .reveal-right, .reveal-scale, .reveal-fade")
           .forEach((n) => n.classList.add("in-view"));
       };
       const rect = el.getBoundingClientRect();
       if (rect.top < window.innerHeight * 0.9) {
         requestAnimationFrame(applyReveal);
         return;
       }
       const io = new IntersectionObserver((entries) => entries.forEach((e) => {
         if (e.isIntersecting) { applyReveal(); io.unobserve(el); }
       }), { threshold: 0.15, rootMargin: "0px 0px -10% 0px" });
       io.observe(el);
       return () => io.disconnect();
     }, []);
     return ref;
   }
   ```
2. **`<RouteReveal />`** — `components/route-reveal.tsx`, mounted once, globally, in `app/layout.tsx` inside the providers. On every client-side route change (via `usePathname()`), it force-applies `.in-view` to any `.reveal*` element whose top edge is already within 95% of the viewport height — covering standalone pages (e.g. `/bestall`, `/katalog/[id]`) that render fully visible on load, where per-section `IntersectionObserver`s might not fire before paint. Runs on an immediate pass, a `requestAnimationFrame` pass, and a 600ms-delayed pass (for async-loaded content). **This component was not documented in the previous version of this file** — it's load-bearing for anything not covered by `useReveal()`'s own "already visible" check (e.g. content that becomes visible slightly after mount).
3. **CSS keyframes/classes** in `app/globals.css` (above) define the actual animation.

Every section wraps in a tag using `useReveal()`; children get `reveal[/-left/-right/-scale/-fade]` + `delay-N`. This pattern is used consistently across `components/sections/*.tsx`.

## Buttons & labels

- Primary: solid `#0a0a0a` (`--foreground`) bg, `--background` text, square, mono uppercase ~12px, padding varies by placement (header CTA and hero CTAs use `px-5..7 py-2.5..4`, i.e. roughly 10–16px vertical / 20–28px horizontal — treat the doc's original "14px 26px" as an approximate baseline, not an exact contract); hover → bg `var(--accent-red)`.
- Secondary: transparent, 1px `border-foreground`; hover → bg `--foreground`, `--background` text.
- Eyebrow: mono uppercase 11px, spacing ~0.14–0.18em, `--muted-foreground`, with a 2-digit index where the section spine applies (e.g. `"01 — Philosophy"`).
- Headlines: sentence case, never uppercase.
- **Implementation note:** there is no shared `Button`/`MonoButton` component implementing this pattern — `components/ui/button.tsx` is the generic, unmodified shadcn/ui button (rounded via `--radius-*` tokens, which happen to resolve to 0 here, but otherwise a stock `cva` variant set: default/destructive/outline/secondary/ghost/link). The mono square CTA look described above is hand-rolled per call site as inline Tailwind classes on raw `<Link>`/`<button>` elements (see `components/header.tsx`, `components/sections/hero-section.tsx`). It's applied consistently in practice, but it's a repeated pattern, not a reusable component — worth extracting if more CTAs are added.

## Visual system — no photos (`DataArtifact`)

`components/data-artifact.tsx` is the one generative primitive; every "image" surface uses it, animating with the effect it replaces. Confirmed implemented variants (`variant` prop): `"table" | "map" | "schema" | "chart" | "grid"`.
- `table` (rows cascade in via `.reveal-left`, provenance square per fact cell) — used in `components/sections/gallery-section.tsx` (showcase tile) and `app/katalog/[id]/page.tsx` (`SampleTab`, plus `OverviewTab` for datasets whose `artifact` field is `"table"`). Real fields used: `dim_company`-style rows with company name, source label, provenance level. **Correction:** the previous version of this doc said this variant is used on "hero/cards" — verified false. `components/sections/hero-section.tsx` does not import or render `DataArtifact` at all; it has its own hand-rolled `ROWS`/`PROV` mini-table that visually mimics the same pattern independently (same provenance-square styling, separately maintained). `components/sections/featured-products-section.tsx` (the dataset "cards" grid) doesn't use `DataArtifact` either — it renders `ProvenanceBadge` per list row instead. Flagging the hero duplication as the same kind of repeated-pattern-not-a-shared-component issue already noted below for buttons.
- `map` (country-code cells in a grid, coverage-% fill bar animates width on view) — coverage. Sample cells: SE/NO/DK/FI (populated) and IS/NL/DE/FR (0%, i.e. not yet sourced).
- `schema` (mini ER diagram over a graph-paper background; key entities get a red top border) — schema previews. Sample entities: `dim_company`, `fact_financials`, `bridge_provenance`.
- `chart` (black bars, exactly ONE red bar — the last one — grow on view) — dashboards, labeled "coverage" with a large faint "06" numeral watermark.
- `grid` (hairline graph-paper + faint oversized "0pt" wordmark + one floating red square using `.animate-float`) — pure texture.

Rules, verified in the component: code-only (Tailwind + inline styles + CSS background-image, no images/canvas/SVG assets), color discipline inside visuals (mono + provenance CSS vars `--prov-0..3` + one red `--accent-red`), `grain-overlay` class applied to the outer wrapper, `prefers-reduced-motion` settles to static (handled globally in `app/globals.css`, not per-component).

**Gap:** the previous version of this doc pointed to "the coverage doc" for the full mapping of template image elements → replacement + effect kept. That doc (`docs/design/0pt-design-coverage-and-visuals.md`) does not exist (see callout at top of this file), so that mapping is not written down anywhere beyond the five variants and their usage sites listed above.

**Optional, not implemented:** Lenis smooth scroll is mentioned as an optional layer on top of this motion system. Verified: `lenis` is not a dependency in `package.json` and is not referenced anywhere in the codebase. If added later, it should not require changing any of the reveal/grain classes above.

**Vestigial component, not on the "no photography" path:** `components/fade-image.tsx` (`FadeImage`, wrapping `next/image` with an intersection-triggered fade/scale-in) exists in the repo but is not imported or used anywhere (verified via repo-wide search). It predates the "no photography" rule or was left over from the source template. Harmless dead code; flagging in case someone reaches for it assuming it's wired in.

## The signature (carry everywhere)

Provenance + confidence is the identity: the provenance square on every fact, one red, mono numerals as texture, section spine, identical motion. A screen that lacks these is off-brand.

Confirmed carried through beyond the marketing pages: `components/provenance-badge.tsx` (`ProvenanceBadge`, `CellProvenance`, `PROVENANCE_LEGEND`) implements the provenance square + label pattern for reuse in data-bearing UI (portal, admin), and `components/order-stepper.tsx` / `components/portal-shell.tsx` / `components/states.tsx` (loading/empty/error states) all follow the same mono-hairline-square-radius-0 chrome — the design system is not marketing-page-only, it extends into `/portal` and `/admin`.