# Stark Future Design System

> Internal design system for **Stark Future** — Barcelona-based, Swedish-rooted electric motorcycle company. Founded 2019. Mission: lead the motorcycle industry toward sustainability through products that beat combustion on performance, emotion, and design.
>
> Flagship: **Stark VARG** — "the lightest, most powerful motocross bike in the world" (`VARG` = wolf in Swedish).

---

## Index

| File | What it is |
| --- | --- |
| `README.md` | This document — brand, content, visual & iconography rules |
| `colors_and_type.css` | All design tokens (color, type, spacing, radius, motion) + base typography roles |
| `SKILL.md` | Agent-Skills entry point for Claude Code / agents |
| `fonts/` | Licensed brand fonts — Stark Sans (display), Universal Sans (body) |
| `assets/` | Logos, ring, wordmarks, icons |
| `preview/` | Design-system preview cards (Type, Colors, Spacing, Components, Brand) |
| `ui_kits/web/` | Marketing-site UI kit |
| `ui_kits/varg-app/` | VARG mobile-app UI kit (the bike's companion app) |

---

## Sources

- **Figma — VARG App UI V2** (mounted): pages `Arkenstone` (foundations + `Components`), `Stark-Phone`. The richest source for app UI, charging dials, lock/unlock, dashboards, settings.
- **Figma — Web Design** (mounted): marketing site for `Home`, `VARG-MX-1.0/1.2`, `VARG-EX`, `VARG-SM`, `Mototerapia`, `Cart-Checkout`, `Dealers`, `Stock-bikes`.
- **Brand Guidelines PDF** — *00 Stark Future Brand Guidelines.pdf*, July 2023 (referenced; not in this skill). Press contact for asset requests: Benjamin Cobb, Communications & PR Manager.
- **Codebase** — `slm-production-manager/` (internal Stark AM tool). Ships canonical `tokens.css`, `index.css` and React components built against the Stark system. Treated here as the **ground truth** for token values + component anatomy because it's already production-validated.
- **Repo** — `starkfuture/slm-factory` (GitHub).

---

## Brand framework

The identity is composed of **four marks** that combine in disciplined ways. They are NEVER mixed.

| Mark | Use | Color rule |
| --- | --- | --- |
| **The Ring** | Full-circle symbol of sustainability and perfection. Used **once** per application. | Digital: gold gradient. Physical: real 24K gold only. NEVER in flat ink. |
| **The Logo** | Wolf head — desire to be #1. Used **once** per application. | 24K gold. Cannot appear with the Ring or with the Stark Future wordmark. |
| **Stark Future Wordmark** | Preferred mark for **corporate** communication. | Grey, white, or black only — never gold. |
| **VARG Wordmark** | Product mark. Reserved for product applications, videos, dealer/external sites. | Per product context. |

> One application = one mark. Never lock-up the ring with the logo or wordmark.

---

## Mission & values (three pillars)

1. **Challenge the norm** — question the status quo of how bikes are built; flexible, young, motivated crew.
2. **Set clear objectives** — concise focused goals (e.g., outperform every combustion MX bike on the market).
3. **Deliver outstanding results** — ingenuity translated into measurable, category-leading output.

---

## Products in scope

| Product | What | Key surfaces |
| --- | --- | --- |
| **Stark VARG MX** (1.0 / 1.2) | Flagship motocross bike | Marketing site product pages |
| **Stark VARG EX** | Trail/enduro variant | Marketing site product page |
| **Stark VARG SM** | Supermoto | Marketing site product pages |
| **VARG companion app** ("Arkenstone") | iOS/Android app paired to the bike — dashboards, charging, lock, settings, racing mode, tracks | `/Arkenstone` page in the App UI Figma |
| **Stark AM** (internal) | SLM additive-manufacturing production manager | `slm-production-manager` codebase |
| **Mototerapia, Dealers, Cart/Checkout, Stock-bikes, Savings calculator** | Marketing-site flows | Web Design Figma |

This skill ships UI kits for **Web (marketing)** and **VARG App** — they're the two surfaces with the most front-facing brand presence.

---

## CONTENT FUNDAMENTALS

How Stark writes copy.

### Voice
- **Confident, technical, performance-driven.** Stark is not a "consumer EV" brand — it's a premium motorsport brand. Copy reads like spec sheets and racing programs, not lifestyle marketing.
- **Sweden + science, not California + cute.** No exclamation marks. No emoji. No "Hey there 👋".
- **Motorsport vernacular** — *power, torque, lap, configuration, rider, track, compound, suspension*. Numbers and units are always present (`80 HP`, `100+ ride configurations`, `€12,900`).

### Tone & casing
- **UPPERCASE for headlines, badges, labels.** Stark Sans is essentially used uppercase only — that's the system. Display headlines (`MOTOCROSS REINVENTED`), section heads (`PERFORMANCE`), micro-labels (`PART`, `SYMPTOM`, `MX 1.2`, `80HP`).
- **Sentence case for body.** No title case in paragraphs.
- **You** is rare. Stark talks **about the bike**, not **to the rider**. ("The VARG MX 1.2 delivers…" — not "You'll feel the…").
- **Numerals are first-class citizens.** Big stat numerals at 48–104px are the dominant decorative element on the marketing site. Use `.kpi-value` / `.stat` from `colors_and_type.css`.

### Specific patterns
- **Eyebrow + headline + supporting line** is the canonical hero structure. Eyebrow = micro-cap, headline = uppercase Stark Sans Light at huge size, supporting = Universal Sans Regular.
- **Specs as columns of `MICRO-CAP` / value pairs.** See `Service History card` in the design-system doc — every detail card uses this anatomy.
- **Pricing uses `€` first, no decimals on whole values.** `€12.900` style separator (European), not `$12,900.00`.
- **Status copy is one or two words.** `Open` · `Submitted` · `Closed` · `Active` · `Finished`. Never "Order has been submitted successfully!".

### Examples
- ✅ `MOTOCROSS REINVENTED.` · `100% ELECTRIC. 80 HP. 110 KG.`
- ✅ `Your service operation hasn't been submitted yet. [Review and submit]`
- ❌ `🚀 Ready to ride? Let's go!`
- ❌ `Welcome back, friend! 👋`

---

## VISUAL FOUNDATIONS

### Color philosophy
- **Black + white + grey is the brand.** Gold appears once-per-application as the Ring/Logo. Status colors (red/green/orange/blue) are functional, never decorative.
- **Dark is equal-priority to light.** Every screen must work in both — semantic tokens (`bg-surface`, `text-primary`, etc.) auto-flip; raw greys never appear in components.
- **Three invariant accents** never change between modes: `gold` (`#CEA82C`, premium/ring), `cool-blue` (`#1684DE`, links/info), `orange` (`#FF8617`, warnings/"Open").
- **No gradients except the gold gradient** on the Ring artwork. No purple, no aurora, no glow.

### Accent restraint (updated directive — May 2026)
The accent colors (`cool-blue`, `gold`, status colors) are **punctuation, not texture**. Use them on **one or two moments per slide or screen** — a single highlighted word, one key data point, one status badge. They must never repeat across every row of a table, every card in a list, or every label in a section. When accent appears everywhere, it appears nowhere.

- ✅ One cell value in a table row highlighted cool-blue to signal a change
- ✅ A single KPI numeral in gold to mark a premium milestone
- ❌ Every link on a page in cool-blue
- ❌ Accent borders on every card in a grid
- ❌ Alternating status colors as a visual rhythm device

### Typography
- **Two families.** Stark Sans (proprietary display) + Universal Sans (body). Stark Sans is **always uppercase**. Universal Sans handles every paragraph.
- **Bigger = lighter.** Page titles are Light (300); subsection headers are Regular (400); micro-labels are Medium (500) at 11px with `0.1em` tracking. The lighter-when-bigger rhythm is a strong brand signature.
- **Stark Sans: no bold.** Stark Sans ships in four weights only — Extralight (200), Light (300), Regular (400), Medium (500). `font-weight: 600` or higher must never be applied to any element using `var(--font-display)`. `--weight-semibold` (600) is reserved for Universal Sans exclusively.
- **Tabular numerals** for stats and tables (`.tabular`).

### Typography restraint (updated directive — May 2026)
Hierarchy is achieved through **weight and size only**. No decorative treatments.

- ✅ Large Stark Sans Light heading + small Universal Sans body below it
- ✅ Medium-weight micro-cap label above a light-weight large numeral
- ❌ Underlines, italics, or colored text as a hierarchy signal
- ❌ Multiple font sizes within a single typographic unit to add "interest"
- ❌ Mixing tracking widths on the same level of hierarchy

One headline. One supporting line (optional). Silence between them does the work.

### Spacing & geometry
- **4px grid.** Tokens `--space-1`…`--space-20`.
- **Pills dominate.** Buttons, inputs, badges, chips, search fields, switches → fully rounded (`--radius-pill`).
- **Cards are modest.** `--radius-md` (8px) default, `--radius-lg` (12px) for larger panels, `--radius-xl` (16px) for elevated/modal containers.
- **Icon-only buttons are circles** (`--radius-circle`).

### Layout philosophy (updated directive — May 2026)
**The layout should be invisible. The content carries the weight, not the design.**

- **Whitespace is the primary structural tool.** Generous margins and padding — clarity over density. On a 1920×1080 slide, minimum 80px margin; on internal-app screens, minimum 24px. When in doubt, add more space.
- **Simplicity over structure.** Avoid multi-column grids, connector lines, radial layouts, or nested card hierarchies unless the content absolutely demands it. A flat list with a hairline rule is almost always the right call.
- **One composition per surface.** A slide does one thing. A dashboard section communicates one idea. If more than one idea is competing for attention, it is a content problem, not a layout problem to solve with more structure.
- **No structural complexity that competes with content.** Decorative containers, background shapes, overlapping layers, and busy grid patterns pull the eye away from data. Reserve structural complexity for the rarest, highest-stakes moments.
- **Hairlines are the only structural element.** A single 1px rule (`var(--color-border-subtle)`) above a group of specs or between table rows is enough. No filled section backgrounds, no panel-within-panel nesting, no drop shadows on interior elements.

Layout rules by surface:

| Surface | Page margin | Max content columns | Accent uses allowed |
|---|---|---|---|
| **Slide (1920×1080)** | 88px | 4 | 1–2 per slide |
| **Web section** | 56px | 3 | 1–2 per section |
| **App screen** | 20px | 2 | 1 per screen |
| **Internal dashboard** | 24px | 3 | 1–2 per view |

### Backgrounds & imagery
- **Full-bleed photography** of bikes/riders dominates the marketing site. High-contrast, often desaturated, often shot on track/dirt with motion blur. Dark.
- **Black is the default app background.** The VARG App ships dark-first; light mode is a structural mirror, not a marketing aesthetic.
- **No illustrations.** No hand-drawn motifs. No textures. The bike itself is the imagery.
- **Subtle noise/grain** is sometimes layered onto large flat black areas in marketing — flagged in the Brand Guidelines as a Language/visual style technique.

### Animation
- **Reductive.** Standard easing (`cubic-bezier(0.4, 0, 0.2, 1)`) at fast (150ms) or normal (220ms) durations.
- **No bounces, no overshoots.** Stark is precise — animations are functional, not playful.
- **Charging dial / arrow direction** components (in the App) animate continuously but linearly — they're communicating data, not delight.

### Hover & press states
- **Hover** = darken/lighten by one neutral step (e.g., `--color-action-primary-bg-hover` = `gray-500` in light, `gray-200` in dark).
- **Press** in mobile = no scale change; hit feedback is via the active state of the underlying control (filled radio dot, switch thumb slide).
- **Focus** = 3px translucent ring (`--focus-ring`) — black 16% in light, white 16% in dark.

### Borders, transparency & blur
- **0.5px hairline borders** (`var(--color-border-subtle)`) on cards and tables — finer than 1px to read as "drawn", not "boxed".
- **Modal-over-blurred-background** is the canonical full-screen-takeover pattern (sidebar/main menu in the app). Backdrop is `backdrop-filter: blur(20px)` over a translucent black/white.
- **No glassmorphism in components.** The blur is a layer effect, not a card style.

### Shadows / elevation
- **Light mode** uses subtle shadows (`shadow-xs` → `shadow-xl`, alpha 0.04 → 0.16).
- **Dark mode** uses surface contrast — cards lift via `gray-600` on `black`, not via shadow halos. Dark shadow tokens exist but are rarely visible.

### Loading & states
- **Loading is a first-class state.** Buttons transform in place: background + size preserved, label replaced by an inline spinner. `<Button busy>`.
- **Errors are inline** — red border + icon + per-field message. A summary banner appears at the form footer when submit is blocked. Same red tint, no separate toast.
- **Empty states** are centered, minimal — eyebrow caption + one sentence, no illustrations.

### Layout rules
- **Sidebar is an inverse island** in dashboard apps — black in both themes. The active nav item is a 2px white left edge + brighter label, not a fill.
- **Top bars** use circular icon buttons. Three patterns: `[<] Title`, `[<] 🔍 Hint`, `[×] Date / Title`.
- **Filter bars** are horizontal pill-chips with one active = inverse fill (black-on-white in light, white-on-black in dark).

---

## ICONOGRAPHY

### What's in the codebase
The `slm-production-manager` frontend uses **`lucide-react`** for all UI icons. This is a stroke-based, 24×24 grid, ~1.5–2px stroke weight icon set. It's the **default Stark icon system for product UIs**.

In this design system we ship Lucide via CDN for parity:
```html
<script src="https://unpkg.com/lucide@latest"></script>
<script>lucide.createIcons();</script>
```
Or as React: `import { LayoutDashboard, ChevronDown } from 'lucide-react'`.

### App-specific icons (VARG App)
The mobile app has a much larger custom icon set drawn in Figma — battery indicators, parental-lock glyphs, charging states, sport-score, directions, flag-pins, dashboard tiles. These are **filled, glyph-style** rather than stroke-style. They're SVGs in `/Components/*` of the App UI Figma. We treat these as **app-only**; the marketing site and any internal product use Lucide.

> **Substitution flag.** Where we don't have access to specific app glyphs we substitute the closest Lucide equivalent (e.g., `Battery` for the custom battery indicator). The app should ship its own glyphs in production.

### Logos & marks (in `assets/`)
- `logo.svg` — Stark wolf logo (gold)
- `ring.svg` — The Ring (gold gradient artwork)
- `wordmark-black.svg` · `wordmark-white.svg` · `wordmark-gray.svg` — Stark Future wordmark in three approved colors

### Emoji & unicode
- **Emoji: never.** Not in product UI, not in marketing copy, not in micro-labels.
- **Unicode arrows** (`→`, `←`) appear in some product copy (`Learn more →`) — fine.
- **Unicode bullets** (`·`) used as separators in metadata strings.

---

## Caveats & substitutions

- **Brand Guidelines PDF** — referenced but not in this skill. Sections 3–5 (Color Palette, Typography hierarchy, Language/Tone) live in the PDF. Token values here come from the codebase's verified `tokens.css` (extracted from the Figma Variables panel), so they're trustworthy but should be cross-checked against the PDF for any future edits.
- **Custom app glyphs** are not bundled — we ship Lucide as the default and flag the substitution per use.
- **Brand photography** is not bundled (licensing). UI kits use placeholder dark frames; production use should swap in licensed bike/rider imagery.
