# OrkaTV Design System

A design system for **OrkaTV** — a free, ad-supported streaming TV platform with hundreds of live linear channels (sports, news, music, lifestyle, classic shows). The product surface is primarily a **10-foot connected-TV (CTV) UI**: a channel list, EPG-style grids, content tiles, a transporter/player, and a side menu. There is also a mobile companion and app-store presence.

This system was built from the **OrkaTV Design System 1.0** Figma library and reconciled against the **Playback State v2** prototype — the working 11-screen CTV build — which is the authority wherever the two disagree. It is intended to be used by Claude (or any agent / designer) to produce on-brand mocks, prototypes, slides, and production-style code.

---

## Sources

| Source | Where | Notes |
| --- | --- | --- |
| Figma library | `OrkaTV Design System 1.0.fig` (mounted) | 11 pages, ~9.7k nodes. The `/Claude-Design-Subset` page is the curated approved subset. |
| Token sheets | Figma `/Tokens` | Core + component + semantic typography tokens. |
| Components page | Figma `/Components` | TRANSPORTER, CHANNEL-LIST-GRIDS, CONTENT, COMPONENT-SIMULATOR. |
| Icons page | Figma `/Icons` | Material-style icon set + bespoke "Core Icons 24px / 56px". |
| Channel art | Figma `/Channel-Logos-Splash` | 225 channel posters & thumbnails. A representative subset is in `assets/posters/`. |
| Marketing shapes | Figma `/Orka-Marketing-Shapes` | Brand background curves. |
| App store assets | Figma `/Orka-App-Store-Assets` | App icon, splash screen, store featured art. |
| **Playback State v2 prototype** | Working CTV build, 11 screens + D-pad focus engine | **Authoritative** for focus behaviour, button variants, component specs, and the Inter text-entry exception. Shipped here as `templates/ctv-prototype/`. |

No public website, codebase, or live URL was provided — every value below comes from the Figma file. Where a font is unavailable we substitute (see "Fonts" below).

---

## File index

```
README.md                  ← you are here
SKILL.md                   ← agent skill manifest (cross-compatible with Claude Code)
styles.css                 ← root entry stylesheet (consumers link this)
colors_and_type.css        ← CSS custom properties + semantic type
orka-icons.js              ← canonical icon set (window.ORKA_ICONS)
thumbnail.html             ← design-system tile
fonts/                     ← Montserrat, all 18 weights/italics
assets/
  logo/                    ← orkatv-wordmark.svg, orkatv-mark.svg + source paths
  channels/                ← channel mark
  posters/                 ← representative channel posters / key art
preview/                   ← Design System tab cards (~700×… each)
templates/
  ctv-prototype/           ← the full interactive 11-screen prototype (D-pad, banners)
  ctv-screens/             ← the same 11 screens, static, on a pannable canvas
ui_kits/
  ctv-app/                 ← OrkaTV 10-foot CTV app — earlier composable demo
    index.html             ← interactive demo (live channel + EPG + transporter)
    *.jsx                  ← composable components
```

---

## CONTENT FUNDAMENTALS

OrkaTV speaks like a **friendly cable guide, not a streaming service**. The product is a programming list — and the copy hews close to the genre conventions you already know from EPGs / TV guides.

**Voice & tone**
- Casing follows broadcast convention: **Title Case for show titles, channel names, and category labels** ("Pro Footvolley Tour", "Highway Thru Hell", "Movies", "Sports"). Genres / categories are sometimes in ALL CAPS in chrome ("CHANNEL LIST & GRIDS", "ATOMS + MOLECULES" — internal section headers).
- **TV-PG, S1 E1, 10:00–11:00 PM** are the standard metadata tokens. Times use 12-hour with a space-less en-dash range and AM/PM in caps.
- "Live" and "On Now" are short, capitalized chips — never sentences.
- Channel numbers are 3- or 4-digit ("0101", "1230"), monospaced/tabular, treated as identifying labels not headings.
- Tense is **present, observational**: "Now Playing", "Up Next", "6 days ago".
- The product addresses the user directly in second person sparingly ("You", "Your Library", "Favorites"), but most surfaces are content-first and avoid pronouns entirely.

**What we don't do**
- No emoji in product chrome.
- No exclamation points or marketing hype in the UI ("Discover something new!" ← never).
- No verbose error messages — short, declarative ("No signal", "Try again").
- No clever or playful microcopy ("Whoops, that didn't work!" ← never). Errors are matter-of-fact like a STB / cable box.

**Specific examples lifted from the Figma**
- Show row: `2024 Pro Footvolley Tour` · `TV-PG` · `S1 E1` · `6 days ago`
- Time block: `10:00–11:00 PM`
- Chip / pill labels: `Live`, `On Now`, `Up Next`, `New`, `Favorites`, `Movies`, `International`
- Section headers: `CORE TOKENS · TYPOGRAPHY`, `COMPONENT TOKENS · TYPOGRAPHY`

---

## VISUAL FOUNDATIONS

OrkaTV is a **dark, late-night, cinematic** UI built for a living-room TV. Think the look of a premium STB / Apple-TV-style guide more than a flat web app.

**Color**
- The default surface is **near-black** (`#0F1115` `--black`) or the slightly-warmer **Orka Black** (`#1D252C`). All UI is dark mode; there is no light theme.
- Splash & hero backgrounds use a **moody radial blend** of warm purple (`rgb(36,31,39)`) into deep navy (`rgb(31,46,77)`) over the Orka Black base — see `--gradient-splash`. This is the brand's signature backdrop.
- **Orka Blue** (`#00A0DF`) is the primary brand accent used sparingly — chips, dividers, key labels.
- **Focus Blue** (`#00D1FF`) is the **accent and button colour**. It fills the primary CTA, marks settings section headers, fills the scrubber's played portion, carries the notification badge and the unwatched-episode dot, and colours an active favourite. It is **no longer the focus stroke** — that pivot is the single most important change from Figma 1.0.
- **Muted White** (`rgba(249,249,249,1)`) is the **focus ring** and the inverted-focus fill. It is also the default text colour.
- **Alert / Orange** (`#E07726`) signals errors, warnings, or destructive state. **Alert Red** (`#FF3B30`) is reserved for LIVE indicators and the scrubber knob.
- **Pure white `#FFFFFF` is retired from the palette.** Every white in the product is Muted White. Text on a muted-white fill is Midnight `#02111E` (`--fg-inverted`).
- Secondary text is Muted White at 60 % (`--fg-secondary`); dot separators and inactive tracks at 25 % (`--fg-faint`); `#535353` for disabled; `#C1C1C1` for settings-row helper copy.

**Typography**
- **Montserrat** is the brand typeface across the entire UI. Used in weights 400 (regular), 500 (medium — the default for body and titles), 600 (semibold), and 700 (bold).
- A display weight called "Mont-Bold" appears at 56px in the Figma — we substitute Montserrat 700 (see "Fonts" below).
- **Inter** is the sanctioned face for **text entry only** — the search field (32/500), the on-screen keyboard (32/500), and the Recent / suggestion lists (28/500). This is a real customer-facing use and the one exception to Montserrat. Inter also still serves internal dev chrome at 14 px.
- Size scale targets a 10-foot UI with role-based sizes from the live product spec:
  - **Display / episode hero — 56 px / Bold**
  - **Page title — 46 px / Bold, uppercase, 1 px tracking** (`--fs-page-title`) — the real title size on every page
  - **Panel / profile show title — 42 px / Bold** (`--fs-panel-title`)
  - **Channel list title, section header — 32 px / Bold**
  - **Side-nav row, list title — 28 px / Regular, 0.03 em**
  - **Button label — 24–28 px / SemiBold**
  - **Description / body — 22 px**
  - **Timestamps, meta — 20 px** (the absolute CTV floor)

  The playhead counter uses `--font-mono` with tabular numerals so digits do not shift.

  **20 px is the absolute floor for any customer-facing CTV surface.** The only place sub-20 px type appears is internal / dev chrome (Inter 14 px).
- Letter-spacing is essentially neutral (0 / 0.5 px); paragraph spacing 0 or 5 px — Montserrat is left to do the work.

**Backgrounds & imagery**
- **No illustrations, no patterns, no textures.** The UI is content-first; the imagery *is* the channel art (16:9 posters), which is full-bleed photographic and runs warm-saturated.
- The splash screen is the only "branded" backdrop: the radial purple/navy blend with the OrkaTV mark centred.
- Marketing pages (`/Orka-Marketing-Shapes`) use abstract geometric blue-grey shapes (`#1D242B`) — large bezier wedges placed at corners. Use for landing pages / brochure surfaces, *not* product UI.

**Animation**
- Motion is **understated and confidence-projecting** — never bouncy or springy.
- Focus transitions are a **220 ms ease-out** scale + glow on the focused tile.
- Page transitions are crossfades, not slides. Use `--ease-out` for entrances, `--ease-in-out` for everything else.
- No long, decorative entrances. Channel-surf is instant; tile focus settles in under a frame.

**Hover / focus / press states**
- This is primarily a CTV remote-control UI: **focus is the dominant state**, not hover.
- **The canonical focus ring is `outline: 4px solid var(--muted-white); outline-offset: 2px`.** It applies to every focusable that is not a tile or a filled control.
- **Tiles** additionally `transform: scale(1.05) translateY(-6px)` and take `box-shadow: 0 18px 40px rgba(0,0,0,.5), 0 0 28px rgba(249,249,249,.3)`.
- **Filled controls invert on focus**: transport pills, the LIVE pill, panel CTAs, and modal actions fill Muted White and switch their glyph/label to `#02111E`. A favourited control is Focus Blue at rest and inverts to `#02111E` on focus.
- The **scrubber** rings its track (`0 0 0 4px` Muted White) and scales the knob 1.5×; the outline itself is suppressed.
- Focus transitions are ~180–220 ms ease-out.
- Hover (mobile / web only) = subtle lift, no scale. Press = brief 0.96× scale-in, no colour change.
- Active selection in the side nav = `rgba(55,92,107,0.35)` row fill at 30 px radius.

**Borders & dividers**
- Borders are very low contrast — `rgba(255,255,255,0.10)` for cards / dividers, `rgba(255,255,255,0.18)` for stronger separation.
- The brand divider color on lighter contexts is `--seafoam` (`#375C6B`) at 40 % alpha.
- Card / tile corner radius: **8 px** for poster tiles, **12 px** for panels, **16 px** for modals, **16–20 px** for hero surfaces.
- **Every button is a pill at 999 px radius — no exceptions.** Chips and side-nav rows are **30 px** (`--r-chip`), profile genre chips **8 px**, keyboard keys **6 px** (`--r-key`). These are not buttons and do not take the pill.

**Buttons — three variants**

| Variant | Spec | Use |
| --- | --- | --- |
| **Ghost** | 62 px tall, `rgba(2,17,30,0.35)` fill, **4 px** Muted White border, 26/600 | The canonical CTV button: Watch Live, Remind Me, Follow, Favorite, Manage my notifications, modal actions (80 px tall) |
| **Outline-sm** | 44 px tall, 1 px inset white ring, 16/600 | Settings-page chrome: Reset to Default, Unfollow All |
| **Primary** | 44 px tall, filled Focus Blue, `#02111E` label, 16/700 | The canonical CTA: Save Changes |

All three invert to a Muted White fill with `#02111E` text on focus.

**Shadows & elevation**
- Tile shadow (the canonical Figma value): `8.674px 3.855px 8.674px rgba(0,0,0,0.10)` — an asymmetric, soft, slightly-offset shadow. Used on EPG tiles.
- Token sheet shadow: `0 4px 8px rgba(0,0,0,0.25)`.
- The focus state replaces shadow with a **glow** (`box-shadow: 0 0 0 4px var(--muted-white), 0 0 24px rgba(249,249,249,0.35)` — `--shadow-focus`; tiles use `--shadow-tile-focus`).
- No inner shadows. No coloured shadows beyond the focus glow.

**Transparency & blur**
- Player controls / transporter sit on top of video with a **protection gradient** (linear black 0→85 % top-down) — never a flat scrim, never a blur backdrop.
- Channel info overlays use the same gradient at the bottom of the poster.
- Modal scrim: 60 % black, no blur.

**Imagery treatment**
- Channel art is presented unmodified — saturated, warm, often photographic. The UI does *not* desaturate or recolour it.
- A subtle inner shadow protects channel art from glowing focus rings.

**Layout rules**
- The CTV canvas is **1920 × 1080**. All TV layouts are designed at that resolution; mobile is a secondary surface.
- TV-safe area: a **96 px inset** from every edge (see Figma `/Safe-Areas`).
- Channel list rail = ~420 px wide, anchored left edge.
- EPG grid tile poster = **406 × 228 px** (16:9), with 102 px of content info below.
- The transporter / player chrome is anchored bottom-center, full-width minus safe area.

---

## ICONOGRAPHY

OrkaTV's canonical icon set is **`orka-icons.js`** at the project root — the Core Icons extracted from the design-system Figma, registered as `window.ORKA_ICONS`. Each entry is `{ viewBox, body }`; render it into an inline `<svg fill="none">` at the size you need and let it inherit `currentColor`.

```js
const d = window.ORKA_ICONS['play'];
// <svg width=40 height=40 viewBox={d.viewBox} fill="none">{d.body}</svg>
```

This file supersedes the loose `assets/icons/` SVGs, which have been removed. Names in use include: `play`, `pause`, `back`, `left`, `right`, `heart`, `heartOutline`, `info`, `cc`, `mic`, `backspace`, `history`, `search`, `notif`, `notifOn`, `alert`, `video`, `audio`, `podcast`, `livetv`, `livenews`, `explore`, `football`, `movie`, `kids`, `lifestyle`, `popculture`, `travel`, `horror`, `reality`, `spanish`, `intl`, `music`, `spiritual`, `creator`, `shop`, `profile`, `settings`.

Where a metaphor is genuinely missing from the set, substitute **Lucide** (`https://unpkg.com/lucide@latest/dist/umd/lucide.js`) at `stroke-width="2"` and `color: currentColor` — but check `ORKA_ICONS` first.

**Emoji**
- Never. Not in chrome, not in copy, not in placeholder content.

**Unicode characters**
- Used very sparingly: `·` (middle dot) as a metadata separator (`TV-PG · S1 E1 · 6 days ago`), and `→` only inside the icon set never inline in copy.

**Channel logos**
- Treat third-party channel logos / posters as content, not iconography. They are presented in 16:9 poster slots, never recoloured, never masked.

---

## Fonts

| Font | Purpose | Status |
| --- | --- | --- |
| Montserrat | Brand body + display | ✅ **Self-hosted from `/fonts`** — the real `.ttf` family was provided by the user (all 18 weights/italics, 100 → 900). |
| Inter | Text entry (search field, keyboard, Recent list) + dev chrome | ✅ Loaded from Google Fonts CDN |
| **Mont-Bold** | Display 56 px in Figma token sheet | ✅ **Resolved** — the Figma's `Mont-Bold` is just Montserrat Bold; the self-hosted family now covers it. |

---

## Index of preview cards & UI kits

**Design System tab cards** (in `preview/`): color primitives, semantic colors, status colors, type scale, type families, weights, spacing, radii, gradients, elevation + focus, buttons, chips/pills, side nav, on-screen keyboard, scrubber + player controls, notification row, notification banner, podcast/episode tile, slide-over info panel, exit modal, channel-list row, EPG tile, brand logo, splash backdrop.

**Templates** — the starting points a consuming project copies:
- `templates/ctv-prototype/` — **CTV Prototype**. The full interactive build: 11 screens, D-pad focus engine with edge behaviour, the notification banner runtime, and the channel catalogue. Tweakable via props (`startScreen`, `launch`, `lastViewed`, `audioOnly`, `bannerDwell`). Demo keys: `1`–`0` jump screens, `Shift`+`1`–`6` fire banners, `R` resets.
- `templates/ctv-screens/` — **CTV Screens (static)**. The same 11 screens at 1920×1080 laid out on a pannable canvas in flow order (playback → browse → account & system), each drawn at its default focus position. Use it to review or annotate layout without driving the prototype.

Both load the design system through a sibling `ds-base.js`; in a consuming project, point its `base` line at the bound `_ds/<folder>` tree.

**UI kits**:
- `ui_kits/ctv-app/` — OrkaTV 10-foot CTV experience (channel list + EPG grid + transporter + side menu). Single interactive `index.html` with composable components.

---

## Caveats

- Tokens, component specs, and the focus model are reconciled against the **Playback State v2**