# Design system guide

This is a practical guide to the current Cade UI. See [Reference map](REFERENCE-MAP.md) for exact source locations and Storybook entry points, and [Figma handoff](FIGMA-HANDOFF.md) for editable-work guidance.

## Which reference wins

| Reference | Use |
|---|---|
| Current Cade wordmark and C-mark under `assets/public/design-system/brand/` | Current identity. Use the actual vectors; never typeset the product name as a substitute logo. |
| `packages/tokens/src/design-tokens.ts` in the source snapshot; its `--pc-*` counterparts in `apps/web/app/globals.css` | Current campaign/product foundation values, reconciled to the rendered landing and market pages. |
| Current component and page references in Storybook | Component geometry, states, combinations, responsive behaviour and source context. |
| `theme-contract.ts`, `ui-*` aliases and older artwork constants | Existing compatibility/chrome values. Keep their provenance distinct from the current `pc*` foundation. |
| `brand-kit-legacy/`, the legacy logo story, older palettes in `DESIGN.md` | Historical reference only. They include the retired PUMPCADE identity and conflicting colour values. |

Some source comments and exported artwork retain older names or values. In particular, paper `#F0EAD9` appears in older materials, while the current `pcColor.surfacePaper` is `#EFE9D8`. The supplied asset geometry should be preserved; do not silently recolour every historic SVG or import all colour sets into one indistinguishable collection.

## Current palette: common roles

Values below are copied from `design-tokens.ts`. The [token viewer](../tokens/index.html) and [export guide](../tokens/README.md) include darker variants, additional roles, provenance and source differences. `tokens/tokens.json` is a documented plain-JSON handoff schema, not a ready-to-import DTCG/W3C or Tokens Studio file.

| Token | Value | Role |
|---|---|---|
| `surfacePage` | `#0E0D0C` | Warm page ground |
| `surfaceRaised` | `#161514` | Raised dark surface |
| `surfaceOverlay` | `#1A1816` | Overlay surface |
| `surfacePaper` / `textPrimary` | `#EFE9D8` | Paper stock / primary foreground |
| `surfaceHeroOrange` / `textBrand` | `#FFA800` | Main brand/accent lane |
| `surfaceHeroViolet` | `#9652EF` | Violet artwork ground |
| `surfacePanelViolet` | `#210D49` | Deep violet panel |
| `accentHighlight` | `#FAF424` | Yellow emphasis/countdown |
| `accentInfo` | `#419FE5` | Information accent |
| `outcomeYes` / `textPositive` | `#91BB4F` | Positive/Higher outcome |
| `outcomeNo` / `textNegative` | `#EA2A46` | Negative/Lower outcome |
| `textNegativeSoft` | `#F24B61` | Negative text treatment |
| `textOnAccent` / `borderInk` | `#0B0B0B` | Ink on accent / comic keyline |
| `textOnPaper` | `#141414` | Ink on paper |
| `textSecondary` | `#A1A1A1` | Secondary foreground |
| `borderDefault` | `#343434` | Quiet dark-UI keyline |

No new memecoin/sports/stocks category palette is approved by this export. Category identity and Higher/Lower outcome identity are different design jobs.

## Typography and fonts

| Role | Product face | Portable handoff face | Use |
|---|---|---|---|
| Display | Futura PT Condensed (CSS name `Futura PT Cond`) | Barlow Condensed | Headings, navigation, prominent labels; typically uppercase and italic |
| Body | Futura PT | Inter | Questions, copy, sentences and controls |
| Data | JetBrains Mono | JetBrains Mono | Prices, percentages, time, volume and identifiers |

The restricted Futura files are excluded from this bundle. Open-font fallbacks are included under `fonts/barlowcondensed/`, `fonts/inter/` and `fonts/jetbrainsmono/`, with an `OFL.txt` licence in each folder. Figma users may use their separately licensed Futura installation; fallback rendering can change line breaks and fit, so the portable previews are not pixel-identical production screenshots. Preserve the separation of display, body and data roles.

`pcTypeScale` contains desktop/mobile size and line-height pairs. Representative display sizes are 128/96/64 px on desktop and 84/64/44 px on mobile; body medium is 20/29 desktop and 14/20 mobile (size/line height). These are art-frame measurements, not instructions to make every production page a fixed-width canvas. Use the actual page at the intended viewport to check fit.

## Shapes, spacing and motion

The recognisable language is torn-paper and notched plates, flat coloured faces, hard black offset shadows, bold condensed labels, halftone dots, rays and occasional starbursts. Preserve the geometry of source SVGs. Keep semantic text and values editable above decorative layers.

The shared hard-shadow ladder is 2, 3, 4, 5, 8 and 11 px down/right, with zero blur. `pcSpace` supplies responsive component padding; `pcGap` is a separate region-gap scale of 8, 16, 24, 32, 40 and 68 px. `pcStroke` defines 1/2/3 px desktop and 1/1/2 px mobile. Radius tokens are 0/4/8 px; existing compact trading/activity surfaces can use rounded dark panels even where campaign plates are jagged. Inspect the intended component before applying a blanket treatment.

`pcBand` and `pcFrame` describe campaign art bands (including a 1920 desktop frame and 478 mobile frame). The older Grid specimen illustrates a different 1440/480 column grid. Do not merge those into a single claimed mandatory grid: use the landing and market references to understand the composition being extended, then document any v2 layout decision.

Shared motion durations are 40, 150, 200, 240, 320 and 620 ms; the 40 ms value is a stagger step and 620 ms is the landing hero treatment. These are UI tokens, not prescribed timings for a football run or baseball play. Sports storytelling needs a separately annotated sequence. Existing soccer effects respect reduced motion and start muted; retain an equivalent accessible path in new concepts. The handoff soccer fixture disables audio, and sports sound files are excluded from this bundle. Use it as a visual/motion reference, not an audio reference.

## Reusable families to inspect

| Family | Current examples |
|---|---|
| Brand and foundations | CadeWordmark, CadeCMark, CadeBrandSheet, ColorTokenGrid, TypeScaleSpecimen, HalftoneTexture, ElevationLadder |
| Actions | Button, CTASlat, SlatButton, CloseButton; Higher/Lower pair states |
| Inputs and selection | Field, SearchField, DropdownSelect, DropdownMenu, ChipRow, BattleDurationChip |
| Labels and identity | StatusBadge, LiveTag, KickerBanner, RankRibbon, StarBadge, CoinBadge, CoinMedallion, TrendArrow |
| Surfaces and headings | TornPanel, ModalPanel, LabelBanner, Burst, Plate, DisplayTitle, SectionHeading |
| Navigation | Desktop header, mobile app navigation, NavItem, HamburgerButton, WalletButton, SportsTab |
| Markets and data | MarketRow, Masthead, ShareSplitBar, DataRibbon, LiveSourceChart, MarketPredictTicket, MarketActivityPanel, DuelRoundClock |
| Sports | SoccerPitchViz, SoccerScoreboard, SoccerEventLog, SoccerMatchInfoPanel, SoccerPredictionMarkets, SportsArcadeTradeTicket |
| Feedback | AlertStrip, responsive sheets, status notices, transaction feedback, empty/loading/unavailable states |

The `components/design-system` directory is only part of the reusable UI; market and site-chrome components live alongside their consuming features. The included source is a reference snapshot, not a standalone installable React package. The browsable catalogue and token/asset exports are the independent handoff surface.

Keep outcome labels, amounts and clocks legible. Use text or shape in addition to colour for meaning, preserve keyboard focus and 44 px touch targets in phone concepts, and make unavailable data distinct from a genuine empty/zero state.