boc/design/DESIGN_SYSTEM.md

Design System Documentation

quiXzoom & Landvex

Last updated: 2026-06-24
Status: Production-ready v1.0

---

Table of Contents

1. Token System Architecture
2. quiXzoom Brand Rules
3. Landvex Brand Rules
4. Shared Constraints
5. Typography Deep-Dive
6. Spacing & Grid
7. PR Audit Checklist
8. Do / Don't Reference

---

1. Token System Architecture

How It Works

Each brand ships a single CSS custom properties file (:root { ... }). All component CSS references these tokens — never raw values.

design/
├── quixzoom-tokens.css    ← Import first, sets all --qx-* vars
├── landvex-tokens.css     ← Import first, sets all --lv-* vars
├── quixzoom-hero.html     ← Self-contained, inline tokens
└── landvex-hero.html      ← Self-contained, inline tokens

Token Naming Convention

Prefix	Brand
--qx-	quiXzoom
--lv-	Landvex

Token Categories

Every token file provides these exact categories in this order:

1. Grayscale — 4 stops from white → deep carbon
2. Accent colors — primary + secondary + alpha variants
3. Semantic aliases — bg, text-primary, border, etc. (reference grayscale/accents)
4. Spacing — 8px-grid-aligned steps
5. Typography — font stacks, locked type scale, weights, line-heights, tracking
6. Easing — named timing functions + duration values
7. Border radius — 5-step scale
8. Shadow system — layered shadows appropriate to each theme
9. Z-index scale — consistent stacking context
10. Transition helpers — shorthand transition values

Why Semantic Aliases?

/* ✅ Correct — uses semantic alias */
color: var(--qx-text-primary);

/* ❌ Wrong — hardcodes the raw color */
color: #FFFFFF;

/* ❌ Also wrong — bypasses semantic layer */
color: var(--qx-white);

Semantic aliases (--qx-text-primary, --lv-bg-surface) let you reskin a component for dark/light variants by swapping token values — not rewriting component CSS.

---

2. quiXzoom Brand Rules

Philosophy

Sport-Tech / Nike-vibes. Energy, kinetic motion, dark precision. quiXzoom never feels corporate. It feels like it was built by athletes, for athletes.

Theme

• Always dark-first. Default background: --qx-deep-carbon (#0D0D0D)
• Light theme is only permitted for marketing landing pages with explicit design approval

Colors

Token	Value	Use
--qx-neon-primary	#00FF87	CTAs, highlights, focus rings, glow effects
--qx-neon-secondary	#00D1FF	Links, hover states, secondary actions
--qx-deep-carbon	#0D0D0D	Page background
--qx-gray-700	#2A2A2A	Surface / card backgrounds

Accent usage rules:

• Neon green (--qx-neon-primary) is the only primary CTA color
• Never use neon on a light background — contrast degrades to unusable
• Glow effects (box-shadow with neon alpha) are permitted on CTAs only
• Never use neon as body text color — always gray-400 or white for prose

Typography

• Font: Inter (900 Black for display, 700 Bold for headings, 400 Regular for body)
• Display sizes: --qx-text-xl (64px) desktop, --qx-text-lg (48px) minimum
• Locked scale: 12 / 16 / 24 / 48 / 64px — no values between these
• Letter spacing on display: always -0.03em
• Line height on display: always 1.0 — never more

Animation

• Signature easing: --qx-ease-snap = cubic-bezier(0.16, 1, 0.3, 1)
• All hero animations use ease-enter = cubic-bezier(0.22, 1, 0.36, 1)
• Stagger hero elements: 0.1s increments (eyebrow → headline → sub → CTA)
• Respect prefers-reduced-motion — wrap animations in media query

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}

Forbidden in quiXzoom

• ❌ Light backgrounds (without explicit approval)
• ❌ Serif fonts
• ❌ Rounded corners above --qx-radius-md (8px) on interactive elements
• ❌ Easing other than the defined set
• ❌ More than 2 accent colors in a single view
• ❌ Drop shadows without neon tinting in dark context

---

3. Landvex Brand Rules

Philosophy

German Enterprise / Siemens-vibes. Precision, system, authority. Landvex never feels playful. It feels like the most reliable tool in the room.

Theme

• Always light-first. Default background: --lv-white (#FFFFFF)
• Dark theme is not supported — Landvex has no dark mode in v1

Colors

Token	Value	Use
--lv-enterprise-blue	#1B4FBF	CTAs, links, active states, accent rules
--lv-enterprise-dark	#0F2E6E	Hover/pressed on blue elements
--lv-gray-200	#DEDEDE	Separator lines, dividers
--lv-gray-800	#222222	Primary body text

Accent usage rules:

• Enterprise blue is reserved for interactive elements only (buttons, links, focus)
• Never use enterprise blue as a background color for large areas
• Never use more than one accent color per screen
• Decorative use of blue (icon fills, rule lines) is permitted at reduced opacity

Typography

• Sans: IBM Plex Sans — headings, labels, body, UI
• Serif: IBM Plex Serif — long-form editorial content, quotes, executive reports only
• Mono: IBM Plex Mono — code, API keys, data tables
• Body line-height: always 1.55 (--lv-leading-base) — non-negotiable
• Display sizes: --lv-text-lg (48px) max, --lv-text-md (24px) for sections
• Tracking on overlines/labels: 0.08–0.10em with uppercase

Separator Lines

Thin horizontal rules are core to Landvex's visual language. Use border-top: 1px solid var(--lv-border) to:

• Divide major content sections
• Separate items in lists
• Create structural grouping without whitespace alone

Never use decorative thick rules — border-top should always be 1px.
The only permitted 2px rule is --lv-separator-accent used to highlight the active tab/section.

Grid

• Base unit: 8px (--lv-grid-base)
• All spacing values must be multiples of 8px
• Exception: 4px (--lv-space-xs) permitted only for internal component padding (badges, labels)
• Content max-width: --lv-container-lg (1200px) for standard pages

Forbidden in Landvex

• ❌ Dark backgrounds
• ❌ Neon or high-saturation accent colors
• ❌ Rounded corners above --lv-radius-md (4px) on structural elements
• ❌ Animation durations above --lv-dur-slow (350ms)
• ❌ Drop shadows with colored glow
• ❌ Text ALL-CAPS for body copy (labels/overlines only)
• ❌ Font weights below 400 for body text
• ❌ Decorative illustrations or icons — data visualization only

---

4. Shared Constraints

These rules apply to both brands without exception.

Currency

• ✅ Always use EUR (€) or USD ($)
• ❌ Never use SEK or any other currency in UI copy or examples

Responsiveness

• iPhone-first — design for 390px viewport, scale up
• Test breakpoints: 390px / 640px / 1024px / 1440px
• No horizontal scroll at any breakpoint above 320px

Performance

• No external CSS frameworks (Bootstrap, Tailwind, etc.)
• No JavaScript required for hero sections — pure HTML/CSS
• Google Fonts loaded with display=swap — always
• Images must have width and height attributes — prevent CLS

Accessibility

• Semantic HTML: <nav>, <section>, <h1> one per page, <aside>
• All interactive elements must have visible focus styles
• aria-label on all navigation regions
• Decorative elements marked aria-hidden="true"
• Color is never the sole indicator of state

Type Scale — Locked

Both brands use the same locked type scale:

Token	Size	Use
*-text-xs	12px	Labels, captions, badges, overlines
*-text-sm	16px	Body text, nav links, button labels
*-text-md	24px	Section headings, card titles
*-text-lg	48px	Page-level headings
*-text-xl	64px	Hero display (quiXzoom primary, Landvex upper bound)

No interpolated values between steps. If 20px looks right, it's wrong — use 16px or 24px.

---

5. Typography Deep-Dive

quiXzoom Typography

Display (hero):   Inter Black 900 / 64px / lh 1.0 / ls -0.03em
Heading 1:        Inter Black 900 / 48px / lh 1.0 / ls -0.02em
Heading 2:        Inter Bold 700  / 24px / lh 1.2 / ls -0.01em
Body:             Inter Regular 400 / 16px / lh 1.5 / ls 0
Label/Eyebrow:    Inter Bold 700 / 12px / lh 1 / ls +0.15em / UPPERCASE

Why Inter? Inter's tight metrics at high weights create the dense, athletic look appropriate for a sport-tech product. The -0.03em letter-spacing on display text echoes Nike/Adidas brand typography conventions.

Landvex Typography

Display (hero):   IBM Plex Serif Semibold 600 / 48px / lh 1.2 / ls -0.01em
Heading 2:        IBM Plex Sans Semibold 600  / 24px / lh 1.35 / ls 0
Body:             IBM Plex Sans Regular 400   / 16px / lh 1.55 / ls 0
Caption:          IBM Plex Sans Regular 400   / 12px / lh 1.55 / ls 0
Label/Overline:   IBM Plex Sans Medium 500    / 12px / lh 1 / ls +0.10em / UPPERCASE
Data/Code:        IBM Plex Mono Regular 400   / 14px / lh 1.5 / ls 0

Why IBM Plex? IBM Plex is the house typeface of IBM — the canonical German-enterprise-technology voice. Its Sans variant has mechanical precision without coldness. Its Serif variant provides editorial gravity for boardroom-level reports. The family cohesion eliminates font-pairing risk.

line-height 1.55: The 1.55 body line-height is Landvex's typographic signature. It provides maximum reading comfort for high text-density layouts (12–18 words per line) without requiring increased font size. Never change this value.

---

6. Spacing & Grid

8px Base Grid

Both systems use an 8px base unit. All spacing must be a multiple of 8.

4px   = --qx-space-xs / --lv-space-0.5    → micro (badge padding only)
8px   = --qx-space-sm / --lv-space-1      → tight grouping
16px  = --qx-space-md / --lv-space-2      → standard gap
24px  = --lv-space-3                       → section internal padding (Landvex only)
32px  = --qx-space-lg / --lv-space-4      → section spacing
48px  = --lv-space-6                       → large section gap
64px  = --qx-space-xl / --lv-space-8      → major section break / hero padding
96px  = --qx-space-2xl / --lv-space-12    → page-level rhythm
128px = --qx-space-3xl / --lv-space-16    → XL layout breathing

When to Use 4px

4px is only permitted for:

• Internal padding on small components (badge pill, tag, inline chip)
• Icon-to-text gap in compact lists
• Fine-tuning vertical rhythm within a text block

Never use 4px as a layout spacing unit.

---

7. PR Audit Checklist

Copy this block into your PR description when touching design files.

## Design System Audit

### Token Compliance
- [ ] No hardcoded hex values in component CSS
- [ ] No hardcoded px values outside of the locked type scale
- [ ] All spacing values are multiples of 8px
- [ ] Semantic aliases used (e.g. `--qx-text-primary` not `--qx-white`)

### Brand Rules
- [ ] quiXzoom: dark background maintained
- [ ] Landvex: light background maintained
- [ ] Currency is EUR or USD only — no SEK
- [ ] Type scale uses only: 12 / 16 / 24 / 48 / 64px
- [ ] No external CSS frameworks added

### quiXzoom Specifics (if applicable)
- [ ] Neon green used only for interactive/CTA elements
- [ ] Easing uses `--qx-ease-snap` or `--qx-ease-enter`
- [ ] Hero animation stagger is ≤ 1.0s total
- [ ] `prefers-reduced-motion` respected

### Landvex Specifics (if applicable)
- [ ] Body line-height is `1.55`
- [ ] Separator lines are `1px solid var(--lv-border)`
- [ ] All spacing is on 8px grid
- [ ] No rounded corners above `--lv-radius-md` (4px) on structural elements
- [ ] No colored shadows

### Accessibility
- [ ] One `<h1>` per page
- [ ] All interactive elements have focus styles
- [ ] Decorative elements have `aria-hidden="true"`
- [ ] Color is not the sole indicator of state
- [ ] `<img>` tags have `alt`, `width`, and `height`

### Responsiveness
- [ ] Tested at 390px (iPhone 14)
- [ ] Tested at 640px (tablet)
- [ ] Tested at 1024px (desktop)
- [ ] No horizontal scroll at any breakpoint

---

8. Do / Don't Reference

quiXzoom

✅ Do	❌ Don't
Use --qx-neon-primary for CTAs	Use neon on light backgrounds
Use Inter Black 900 for display	Use system fonts for display
Animate with --qx-ease-snap	Use ease-in-out or linear
Keep display line-height at 1.0	Add padding between headline words
Use dark overlays for card hover	Use light overlays or color fills
Price in EUR / USD	Price in SEK

Landvex

✅ Do	❌ Don't
Use 1px solid var(--lv-border) for dividers	Use thick rules or decorative lines
Keep body line-height: 1.55	Change body line-height for "breathing"
Use IBM Plex Serif for editorial	Use IBM Plex Serif for UI labels
Use 8px-grid spacing always	Use arbitrary pixel values
Use --lv-enterprise-blue for interactive only	Paint large areas enterprise-blue
Animate with --lv-ease-standard	Use spring/bounce easing
Price in EUR / USD	Price in SEK

---

Design system maintained by the quiXzoom/Landvex platform team.
Questions → design@quixzoom.com / design@landvex.com