> ## Documentation Index
> Fetch the complete documentation index at: https://docs.worldflux.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Design system

> WorldFlux uses a dark control-plane register: midnight canvas, glassy cards, cool blue-gray text, pill actions, and restrained violet CTAs.

## Register

WorldFlux has one shared visual register across brand and product surfaces: a dark technical control plane with quiet depth. The dashboard should feel dense and precise; login and public evidence pages can be more spacious, but they still use the same token set.

| Surface                           | Voice                                                                                  |
| --------------------------------- | -------------------------------------------------------------------------------------- |
| Landing, login, public share, 404 | Centered display type, restrained glow, translucent hero panels, decisive CTA.         |
| Dashboard, settings, run detail   | Compact tables, glassy panels, subtle borders, status colors only inside product data. |

## Colors

| Token                 | Hex / Value                 | Role                                               |
| --------------------- | --------------------------- | -------------------------------------------------- |
| `--midnight-abyss`    | `#05060f`                   | Page canvas and deepest surfaces.                  |
| `--ghost-white`       | `#ffffff`                   | Primary text and icon fill.                        |
| `--comet`             | `#d8ecf8`                   | Body text and prominent readable copy.             |
| `--arctic-mist`       | `#d1e4fa`                   | Secondary text and outline button text.            |
| `--celestial-light`   | `#b6d9fc`                   | Focus rings, highlights, and selected affordances. |
| `--whisper-blue`      | `#9da7ba`                   | Muted body text and placeholders.                  |
| `--interstellar-gray` | `#81899b`                   | Captions and faint metadata.                       |
| `--neon-violet`       | `#663af3`                   | Critical CTAs and selected product identity.       |
| `--graphite-rail`     | `rgba(186, 215, 247, 0.12)` | Hairline borders and subtle dividers.              |

### Status Palette

Reserved for product data. Never use these as section backgrounds.

| Token      | Hex       | Meaning                               |
| ---------- | --------- | ------------------------------------- |
| `--ok`     | `#22c55e` | Run succeeded.                        |
| `--info`   | `#70b8ff` | Run in progress.                      |
| `--warn`   | `#ffca16` | Quota or warning state.               |
| `--danger` | `#ff5577` | Run failed or destructive state.      |
| `--click`  | `#c084fc` | Secondary product-data accent.        |
| `--brand`  | `#663af3` | Product identity / selected metadata. |

## Type

| Family        | Where                                 | Runtime substitute |
| ------------- | ------------------------------------- | ------------------ |
| Untitled Sans | Body, nav, buttons, forms, tables     | Inter              |
| aeonikPro     | Display headings and hero copy        | Space Grotesk      |
| dotDigital    | Technical captions and numeric labels | IBM Plex Mono      |

Display headings use normal tracking. Body and compact UI text may use subtle negative tracking.

### Scale

| Token       | Size | Where                             |
| ----------- | ---- | --------------------------------- |
| `--fs-2xs`  | 12px | Captions and micro labels.        |
| `--fs-sm`   | 14px | Buttons and compact UI rows.      |
| `--fs-base` | 16px | Body.                             |
| `--fs-md`   | 18px | Lead body and subheads.           |
| `--fs-xl`   | 24px | Section labels and card headings. |
| `--fs-2xl`  | 28px | Large section heading.            |
| `--fs-3xl`  | 44px | Display.                          |
| `--fs-hero` | 48px | Largest display.                  |

## Geometry

| Element                 | Radius    |
| ----------------------- | --------- |
| Buttons / icon controls | 999px     |
| Inputs                  | 2px-4px   |
| Badges                  | 6px       |
| Cards / containers      | 12px-16px |

## Surfaces

Cards are translucent and use inset blue-gray lighting rather than generic shadows.

```css theme={null}
.sb-card {
  border: 1px solid var(--graphite-rail);
  border-radius: 16px;
  background: rgba(186, 214, 247, 0.03);
  box-shadow: var(--shadow-subtle);
}
```

`.sb-card-lift` is reserved for login, onboarding, and hero panels that need stronger depth.

## Tailwind v4 Tokens

The web app defines WorldFlux dashboard tokens in `web/app/globals.css` using Tailwind v4's `@theme` directive. Color, font, text, leading, tracking, spacing, radius, and shadow namespaces are exposed as first-class Tailwind utilities and runtime CSS variables.

Important namespaces:

* `--color-*`: `bg-midnight-abyss`, `text-comet`, `border-graphite-rail`.
* `--font-*`: `font-untitled-sans`, `font-aeonikpro`, `font-dotdigital`.
* `--text-*`: `text-body`, `text-heading`, `text-display-xl`, with line-height metadata.
* `--leading-*` and `--tracking-*`: explicit typography utilities.
* `--spacing`: keeps Tailwind numeric spacing at a 4px base, so `p-4` remains 16px.
* `--spacing-element-gap`, `--spacing-card-padding`, `--spacing-section-gap`: semantic spacing utilities.
* `--radius-*`: pill, card, badge, and input radii.
* `--shadow-*`: WorldFlux glow and inset-surface elevations.

## Buttons

| Variant             | When                         | Look                                          |
| ------------------- | ---------------------------- | --------------------------------------------- |
| `sb-button-primary` | Critical action.             | Neon Violet fill, white text, pill shape.     |
| `sb-button-pill`    | Primary non-critical action. | Translucent fill, white text, subtle border.  |
| `sb-button-outline` | Secondary structure.         | Transparent, Arctic Mist text, subtle border. |
| `sb-button-ghost`   | Quiet inline action.         | Transparent, text-forward.                    |
| `sb-button-danger`  | Destructive action.          | Danger border/text.                           |

Use `#663af3` sparingly. It should draw the eye only when the action is genuinely important.

## Layout

* Base spacing unit: 4px.
* Element gap: about 8px.
* Card padding: about 24px.
* Section gap: about 48px.
* Page max-width: about 1200px for product surfaces.

## Motion

Hover and press states are quick: 150ms-200ms with `cubic-bezier(0.25, 1, 0.5, 1)`. `prefers-reduced-motion: reduce` short-circuits animation.

## Anti-Patterns

* Broad saturated gradients.
* Generic drop-shadow stacks.
* Extra accent colors outside product data.
* Flat opaque cards where a translucent surface is expected.
* Display headings with negative tracking.
* Using violet for decoration instead of decisive action.

See `web/design/app.worldflux.ai/DESIGN.md` for the persisted WorldFlux dashboard reference and local token mapping.