> For the complete documentation index, see [llms.txt](https://bubblegum-reality.gitbook.io/bubblegum-reality-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bubblegum-reality.gitbook.io/bubblegum-reality-docs/architecture/design-system.md).

# Design System

<figure><img src="https://2318849310-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2wBjPhklYSWnk8T2J5xf%2Fuploads%2Fgit-blob-1c86456e037bc98e51b00de3fec01ac8751129a0%2Fbubblegum-reality-terminal.png?alt=media" alt="The Bubblegum Reality terminal isolated against a neon bubblegum flare"><figcaption><p>The accent is reserved for active status — a single neon gesture against near-black.</p></figcaption></figure>

## Direction

A dusk CRT terminal: near-black surfaces, ivory text, muted rose secondary, and a neon bubblegum accent reserved for **active status only**. The reference image is a vintage terminal on a desk against a dusky rose skyline — warm, filmic, slightly worn. Not a purple-gradient SaaS dashboard.

## Tokens

All color, gradient, and shadow values are semantic tokens in `src/styles.css`, declared in `oklch` inside `@theme`. Components reference tokens only.

```
--background        near-black surface
--foreground        ivory
--secondary         muted rose
--accent            neon bubblegum pink  (active status only)
--panel / --panel-border   frosted-glass panels
```

**Never hardcode a color utility in a component** — `text-white`, `bg-black`, `bg-[#ff5fa2]` all bypass theming. If a value is missing, add a token.

## Texture utilities

Custom utilities provide the CRT feel: film grain, scanlines, and frosted panels. They are decorative, sit behind content, and respect `prefers-reduced-motion`.

## Typography

Fonts load via `<link>` in `src/routes/__root.tsx` — one readable sans for prose plus IBM Plex Mono for data, tickers, and the boot sequence. Never `@import` a remote stylesheet in `styles.css`: Tailwind v4's Lightning CSS resolves `@import` from the filesystem and the build fails.

All pairings are verified for WCAG AA contrast against their surfaces.

## Motion

| Surface        | Behaviour                                                              |
| -------------- | ---------------------------------------------------------------------- |
| Hero film      | Two-clip loop, `object-fit: cover`, `object-position: 50% 55%`         |
| Video audio    | Permanently muted                                                      |
| Soundtrack     | Separate `<audio>` element, gesture-only, preference in `localStorage` |
| Boot sequence  | ≤2.5s, skippable via `Esc`/`Enter`/click/tap, completion remembered    |
| Reduced motion | Never autoplays; poster still is shown instead                         |
| Tab hidden     | Playback pauses on `visibilitychange`                                  |
| Video error    | Collapses to the poster still — never a broken player chrome           |

The landing film is mounted only on `/`. App routes never carry it, so the terminal stays legible and cheap to render.

## Accessibility

Accessible dialogs with focus management, labelled inputs, keyboard-operable controls, visible focus rings, and honest empty states. Status colors are always paired with text — the neon accent alone never carries meaning.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://bubblegum-reality.gitbook.io/bubblegum-reality-docs/architecture/design-system.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.