Thundera Shell v2

The single design standard for every Thundera surface: one top bar, one apps launcher, one footer, one set of design tokens, and three page kits (landing, system, docs). Zero dependencies, framework-agnostic — it works the same in React SPAs, server-rendered HTML and static pages.

• Live: https://thundera.eu/shell/v2/ · Guide: https://thundera.eu/docs/shell
• Source: portal/src/landing/shell/v2/ (repo thundera-group/portal) · Version: 2.0.3
• Examples: landing · system · docs · bar only

Files

The tests (node tests/system/shell-v2.test.js) enforce the budgets.

Caching and pinning

Breaking changes get a new major directory (/shell/v3/). v1 (/shell/v1/) keeps serving unchanged until every app has migrated.

Quick start — static HTML

<!doctype html>
<html lang="en" class="th" data-brand="whisper" data-th-theme="dark">
<head>
  <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
  <link rel="stylesheet" href="https://thundera.eu/shell/v2/tokens.css">
  <link rel="stylesheet" href="https://thundera.eu/shell/v2/shell.css">
  <link rel="stylesheet" href="https://thundera.eu/shell/v2/ui.css">
  <script type="application/json" data-th-config>
  { "app": "whisper",
    "links": [ {"label": "Product", "href": "/#product"}, {"label": "Pricing", "href": "/#pricing"},
               {"label": "Docs", "href": "/docs"}, {"label": "Status", "href": "https://thundera.eu/status"} ],
    "actions": { "signedIn": [ {"label": "Open app", "href": "/app", "kind": "primary"} ] } }
  </script>
  <script src="https://thundera.eu/shell/v2/shell.js" defer></script>
  <script src="https://thundera.eu/shell/v2/ui.js" defer></script>
</head>
<body>
  <header data-th-bar></header>   <!-- reserves the bar height: zero layout shift -->
  <main id="main"> … </main>
  <div data-th-footer></div>      <!-- optional: the ecosystem footer renders here -->
</body>
</html>

That is the whole integration. The shell reads the session from auth.thundera.eu, fills the apps launcher from the live catalogue (apps.icon_url), highlights the current app and renders Sign in / Get started for anonymous visitors.

• data-brand picks your product's colours (see Brand and theme).
• class="th" turns on the base styles (font, colours, links). Leave it off inside an existing app whose CSS you do not want to touch — the shell itself is fully scoped.
• <header data-th-bar> must be the first element in <body>. Without it the shell inserts one, which shifts your content by the bar height once.

React / Vite

Put the slot and the scripts in index.html (outside the React root), then talk to window.Thundera from components.

<!-- index.html -->
<html lang="en" data-brand="photomemory" data-th-theme="dark">
<head>
  <link rel="stylesheet" href="https://thundera.eu/shell/v2/tokens.css">
  <link rel="stylesheet" href="https://thundera.eu/shell/v2/shell.css">
  <script src="https://thundera.eu/shell/v2/shell.js" data-app="photomemory" defer></script>
</head>
<body><header data-th-bar></header><div id="root"></div></body>
</html>

// useThundera.ts — session + nav for the current route
import { useEffect, useState } from 'react';
declare global { interface Window { Thundera?: any } }

export function useThunderaUser() {
  const [user, setUser] = useState(window.Thundera?.user ?? null);
  useEffect(() => {
    window.Thundera?.ready.then(setUser);
    return window.Thundera?.onUserChange(setUser);
  }, []);
  return user;
}

// In your router layout: keep the bar's links and active state in sync.
useEffect(() => {
  window.Thundera?.configure({ links: [
    { label: 'Library', href: '/app' }, { label: 'Albums', href: '/app/albums' },
    { label: 'Family', href: '/app/family' } ], active: location.pathname });
}, [location.pathname]);

Delete the app's own top bar component (ThunderaNav.tsx, TopBar.tsx, …) after the switch.

Server templates

Any template language works — emit the same markup. Example (Jinja / EJS style):

<html lang="en" class="th" data-brand="{{ app_slug }}" data-th-theme="dark">
<head>
  {% include "thundera-head.html" %}   {# the three <link>s + shell.js #}
  <script type="application/json" data-th-config>{{ shell_config | tojson }}</script>
</head>
<body><header data-th-bar></header> … <div data-th-footer></div></body>

shell_config is a plain object (app, links, actions, …). Serialize it with your framework's JSON helper so it is escaped correctly.

Configuration

Three sources, merged in this order (later wins):

1. <script src=".../shell.js" data-app="eam" data-app-name="EAM" data-footer="true">
2. <script type="application/json" data-th-config>{…}</script> anywhere in the page
3. window.ThunderaConfig = {…} set before shell.js runs
4. Thundera.configure({…}) at runtime (re-renders immediately)

Brand and theme

Every product owns its colours in <app>/brand/tokens.json (its own repo). portal/scripts/shell-brands.py --sync turns them into [data-brand="<slug>"] presets in tokens.css, with accents adjusted for 4.5:1 contrast in both themes. Your app sets one attribute and never writes a colour literal:

<html data-brand="eam">  <!-- whisper eam photomemory aitrade jarvis swarm thundercode ai thundera -->

data-brand also works on any element, so a card can wear a sibling app's colours inside your page (the thundera.eu product grid does this). The group identity — thundera, auth, portal — is Thundera orange and stays orange for every app on auth.thundera.eu.

Changed your brand/tokens.json? Ask in your status file's Requests for a re-sync (the portal owner runs python3 scripts/shell-brands.py --sync and commits). New app without a preset? Same — until then it falls back to the group orange.

Theme. data-th-theme on <html> is dark (default), light or auto (follows the OS). It is nestable: <section data-th-theme="dark"> keeps a section dark on a light page. The user's choice from the user menu is stored in localStorage["th.theme"] and applied by shell.js. To avoid a flash for light-theme users, inline this before the stylesheets (only if your CSP allows inline scripts):

<script>try{var t=localStorage.getItem('th.theme');if(t)document.documentElement.dataset.thTheme=t}catch(e){}</script>

Core tokens (all --th-*): surfaces --th-bg --th-bg-2 --th-surface-1…4 --th-glass --th-overlay; text --th-text --th-text-2 --th-text-3; borders --th-border --th-border-2 --th-border-3; semantic --th-success-text --th-warning-text --th-danger-text --th-info-text + *-soft fills; type --th-font-sans --th-font-mono --th-fs-2xs…5xl (fluid) --th-fw-* --th-lh-*; space --th-space-1…32 --th-section-y --th-gutter; radii --th-radius-xs…2xl/full; elevation --th-shadow-1…4; motion --th-ease* --th-dur-1…5 (collapse to 1 ms under reduced motion); layers --th-z-*; layout --th-bar-h --th-container* --th-sidebar-w. Breakpoints: 640 / 900 (shell switches to mobile) / 1200 / 1440.

Fonts: the system stack, with Inter first if the device has it. No web font is required.

Top bar, launcher, user menu

• Left: Thundera mark (→ thundera.eu) / your mark + name (→ href), then links.
• Right (signed in): actions.signedIn, apps launcher, avatar → user menu.
• Right (anonymous): apps launcher, Sign in, Get started (→ auth.thundera.eu with ?redirect=<current URL>).
• Launcher: every active app from GET /api/v1/auth/apps[/public] with its icon_url, current app highlighted, maintenance badge, search filter (type to filter, Enter opens the first match), arrow keys move across the grid, Esc closes, "All apps" + Status links.
• User menu: name, email, plan badge (user.plan), Account settings, Billing & plans (hidden for organization members), Docs, your userMenu items, system links for system-* roles, theme switch, Privacy choices (when consent is enabled), Sign out.
• Mobile (< 900 px): compact bar (marks, launcher, avatar or Sign in, menu button) and a full-height drawer with your links, account actions, theme and sign-out. The drawer traps focus, closes on Esc / scrim / navigation and locks page scroll.
• Sticky with backdrop blur, safe-area insets, skip link to your main, every control labelled, aria-expanded/aria-controls on every trigger, Esc returns focus.

Footer

<div data-th-footer></div> renders: brand + tagline, your product column (defaults to your links), Products (live catalogue), Resources (Docs, Status, Downloads, Plans & billing), Company (About, Privacy, Terms, Contact, Privacy choices), copyright and social links. Customize with footer: {tagline, product: [{label, href}], columns: [{title, links}]}.

JavaScript API — window.Thundera

v1-compatible; v2 additions are marked ★.

The shell is read-only with respect to the session: it calls GET /api/v1/auth/me?optional=1 (anonymous visitors get 200 {"user":null} instead of a logged 401; never the rotating /auth/session), never refreshes tokens, never redirects on 401. Your app owns its own refresh. When a different user signs in on the same browser, the shell scrubs every <app>_* key from local/session storage (the cross-user leak guard).

Landing kit (ui.css + ui.js)

Load ui.css (and ui.js for reveal, counters, copy buttons and live pricing). Reference: examples/landing.html.

System kit (system.css + system.js)

Every app's /system, /admin and settings use this so they look like one product. Reference: examples/system.html.

Docs kit (docs.css + docs.js)

Every app's /docs uses this layout. Reference: this page.

<div class="th-docs" data-th-docs-index="/docs/search.json">
  <nav class="th-docs-nav" aria-label="Documentation">
    <a class="th-docs-back" href="/">← Back to Whisper</a>
    <div class="th-docs-search"><input type="search" placeholder="Search docs" aria-label="Search docs"><kbd>⌘K</kbd></div>
    <section><h2>Getting started</h2><ul><li><a href="/docs">Overview</a></li></ul></section>
  </nav>
  <main class="th-docs-main" id="main">
    <article class="th-prose"><h1>Title</h1><p class="th-lead">…</p><h2>Section</h2>…</article>
    <nav class="th-docs-pager" data-auto aria-label="Pagination"></nav>
    <div class="th-docs-meta"><span>Updated …</span></div>
  </main>
  <aside class="th-docs-toc"><h2>On this page</h2><ul data-th-toc></ul></aside>
</div>

• Search index: a JSON array [{"title", "url", "section", "text"}] (keep text to the first ~400 characters of each page). / or ⌘K focuses search; arrows + Enter navigate. Without an index, search still covers the nav titles.
• h2/h3 get ids, # anchors and an "On this page" entry with scroll-spy.
• pre blocks get a copy button and a language label from class="language-xxx".
• Callouts: <div class="th-callout th-callout-tip|warning|danger"><strong>Title</strong><p>…</p></div>.
• .th-docs-pager[data-auto] fills prev/next from the nav order.
• Mobile: the nav becomes a sheet behind a "Menu" button with the current page name.

Consent and app gate

Pages that load analytics must load consent first:

<script src="https://thundera.eu/shell/v2/consent.js"></script>  <!-- before analytics -->

With a shell mounted, the floating pill is hidden and "Privacy choices" appears in the user menu, the drawer and the footer. ThunderaConsent.enabled() (new) tells you whether consent is switched on. app-gate.js is unchanged from v1: load it early on /app surfaces.

Content-Security-Policy

Allow, at minimum:

script-src  https://thundera.eu
style-src   https://thundera.eu
img-src     https://thundera.eu https://www.gravatar.com data:
connect-src https://auth.thundera.eu

The kit sets no inline style attributes from markup and no inline event handlers; dynamic values use the CSSOM, which CSP allows.

Accessibility and performance

• Every interactive element is a real <a>/<button> with an accessible name; menus use the disclosure pattern; the drawer and dialogs trap focus; Esc always closes and returns focus; visible focus rings use the brand accent.
• Text tokens meet WCAG AA on their surfaces in both themes; brand accents are adjusted to ≥ 4.5:1 by the generator.
• prefers-reduced-motion collapses every duration and disables reveal/ambient animation.
• No layout shift: the bar slot is sized by CSS before JS runs; images in the shell carry dimensions; the footer slot reserves space.
• No web fonts, no icon fonts, no third-party requests except auth.thundera.eu and avatars.

Migrating

From Shell v1

window.Thundera keeps every v1 member. Load either v1 or v2 on a page, never both (v2 steps aside if v1 is already present).

From a per-app nav (whisper ThunderaNav.tsx, settings.html copies, custom top bars)

1. Delete the app's top bar, apps menu, avatar menu and footer components.
2. Add the slot + scripts (above) and move the app's nav items into links.
3. Replace hardcoded brand colours with data-brand + --brand-*; replace local surface / text colours with --th-* tokens.
4. Point "Upgrade" buttons at https://auth.thundera.eu/billing?product=<slug>&tier=<tier>&period=<monthly|yearly>.
5. Rebuild landing sections with ui.css, /system + /admin with system.css, /docs with docs.css.
6. Screenshot at 390×844 and 1440×900 in both themes; run your E2E suite.

Changing the kit

The shell is owned by the portal repo. Do not fork or override its internals in an app — if you need something it lacks, ask for it (status-file Requests in the modernization program, or an issue on thundera-group/portal). Gates: node tests/system/shell-v2.test.js (budgets, desktop + iPhone behaviour, anonymous vs signed-in, no CLS) and python3 scripts/shell-brands.py --check.