# DF4 Labs Design System

> **Product-lab / operational identity** for an applied AI lab.
> DF4 Labs is the parent company. FoxLitX, Repolize, and House AI are DF4 Labs product companies. This system is the source of truth for all of them.

## Company

**DF4 Labs** — *The AI Lab for the Builder Economy*. UK-based applied AI lab building tools for healthcare, safety, and the built environment. The parent runs marketing at `df4.uk` and content at `studio.df4.uk`. Each product company gets its own surface but inherits this system.

### Hierarchy
- **DF4 Labs** — parent OS. Cool institutional paper, ink-900 on `--paper-50`, orange accent reserved.
- **FoxLitX** — code-generation copilot. Dark-by-default operator surface.
- **Repolize** — repository visualisation. Light, ink-on-paper graph canvas.
- **House AI** — sovereign smart-home AI. Warm paper *only inside House AI surfaces*; never on parent pages.

### Surfaces
- **Marketing site** (`df4.uk`) — Next.js 16 + Tailwind 4
- **Sanity Studio** (`studio.df4.uk`) — content + dashboards
- **Product company sites & apps** — FoxLitX, Repolize, House AI

### Sources used to build this system
- GitHub: `df4-devteam/DF4-LABS-WEBSITE` — primitive scales, button/input patterns, copy voice
- Uploaded brand assets: logos (light/dark/clean/animated), full favicon set, OG image
- The live URLs for tone reference (not scraped)

> **Reader without access to the repo** — every value, copy reference, and component pattern is reproduced in the actual files of this folder. Repo links are provenance, not prerequisites.

---

## Index

```
README.md                — this file
SKILL.md                 — Agent-Skill manifest for re-use
compliance.md            — checklist + forbidden patterns (canonical)
compliance.html          — visual compliance reference
brand_architecture.md    — parent / product company relationship
brand_architecture.html  — visual reference for the lockup + modes
motion.md                — motion doctrine (canonical)
motion.css               — single source of truth for easing + timing
motion.html              — live motion reference
colors_and_type.css      — tokens, fonts, semantic CSS vars
fonts/                   — self-host paths (placeholders until .woff2 supplied)
assets/                  — logos, favicons, OG image, product marks
preview/                 — Design System tab cards
ui_kits/
  _system/               — shared modules every surface composes from
  website/               — df4.uk parent site
  studio/                — Sanity Studio (light customisation)
  foxlitx/               — FoxLitX product company surface
  repolize/              — Repolize product company surface
  houseai/               — House AI product company surface
routes/
  01-product-landing.html — product company landing scaffold
  02-research-index.html  — Field Notes / research index scaffold
  03-legal-terms.html     — long-form legal document scaffold
  04-status.html          — operations / status page scaffold
```

The four `routes/*.html` files are **canonical compositions** — assembled from `ui_kits/_system/*` modules and motion tokens, no bespoke CSS. Copy the closest route, swap the content, ship.

---

## Direction at a glance

DF4 reads as a **product lab and operations company** — confident, technical, lightly editorial. Not a SaaS landing page, not a research-paper pastiche.

**Drop**
- Gradient washes (`from-primary to-accent` text or backgrounds)
- Multi-colour Phosphor icons in `bg-{colour}-500/10` rounded tiles
- Backdrop blur, glass effects, floating orbs, dot-grid backgrounds
- `rounded-2xl` shadcn cards with default drop shadow
- Hover translate / scale / glow

**Keep**
- DF4 orange via `--orange-*` / `--accent` — used sparingly, never as gradient
- Phosphor Icons at one weight, monotone
- JetBrains Mono for code, telemetry, technical labels

**Use**
- **Manrope** — display
- **Inter Tight** — body / UI
- **JetBrains Mono** — code, telemetry, technical labels
- Cool institutional paper (`--paper-50`) for the parent
- Warm paper **only** inside House AI surfaces
- Hairline 1px rules as primary structural device
- Square or 4–8px corners; pill only for tags, dots, avatars
- One motion system from `motion.css` — one curve, five timing tokens, one reveal distance

---

## Content fundamentals

### Voice
Confident, plainspoken, lightly poetic. Treats AI as an instrument for builders, not a marketing flex. Sentences are short. Claims are concrete. Editorial flourish is brief — one line, then back to specifics.

### Casing
- **Sentence case** for headings and buttons.
- **UPPERCASE TRACKED** only for eyebrows and tag pills.

### Pronouns
"We" for the company, "you" for the reader. UK English throughout (`programme`, `behaviour`, `optimise`).

### Tone characteristics
- Declarative, not breathless. *"Sovereign AI built natively into new homes."* not *"🚀 Revolutionise your home with cutting-edge AI!"*
- Concrete, not aspirational. *"TRL 6 — Demonstrated in Relevant Environment"* not *"Production-ready solution"*.
- Builder-respectful. Code, builders, makers, ship, real-world.
- Occasional editorial flourish, used sparingly.

### Avoided
- No emoji.
- No exclamation marks in product copy.
- No "AI-powered" / "next-gen" / "leveraging" / "supercharge" / "unlock".
- No "Get started for free" — the brand sells access (`Talk to Us`, `Visit Site`, `Join Our Team`).

---

## Visual foundations

### Colour
- **`--paper-50`** is the parent page surface — cool, slightly off-white. Not cream. Not warm. Warm paper is reserved for House AI surfaces only.
- **`--ink-900`** for foreground text. Deep, slightly cool black; never pure `#000`.
- **`--accent`** (`--orange-500` light, `--orange-400` dark) is the signature. Used for the primary CTA, active link state, eyebrow accents, the brand-orange arrow in the logo. **Never** as a background fill larger than a 40px pill. **Never** as a gradient.
- **`--ink-900`** is the secondary anchor — full-bleed inverted strips, footer, FoxLitX surfaces.
- **Status colours** (`--success`, `--warning`, `--danger`, `--info`) are muted single-hue. Form validation, status badges, TRL labels — never decoration.

### Type — canonical
- **Display:** `Manrope` 400/500/600/700. Headlines + display copy. Weight 700 for the largest cuts; 500 for everything else.
- **Body / UI:** `Inter Tight` 400/500/600. Body copy, navigation, buttons, cards. Weight 500 for buttons + nav.
- **Mono:** `JetBrains Mono` 400/500. Code, telemetry, version strings, key/value pairs, TRL labels, eyebrows.
- **Eyebrows** are mono 11px UPPERCASE tracked +0.04em, optionally preceded by an 8×8 accent square — *never* an icon, *never* a rounded badge.

> **Loading.** Google Fonts is acceptable for preview only. Production must self-host using `fonts/_self-host.css` and the `.woff2` files in `fonts/{manrope,inter-tight,jetbrains-mono}/`. **The font folders ship as placeholders** — drop the licensed `.woff2` into them and `_self-host.css` resolves automatically. See `fonts/README.md`.

### Spacing
4px base. Vertical rhythm uses `--s-5 / --s-7 / --s-9` (24/48/96). Section gutters are `--s-9` (96px) minimum on desktop marketing pages; `--s-11` (192px) between *major* page sections (hero → next slab, marquee handoffs). Never <64px. Inside cards: `--s-5` (24px) minimum, more often `--s-6` (32px).

### Backgrounds
- Default: flat `--bg-1` paper, no decoration.
- Sunken sections: `--bg-3`.
- Inverted sections: full-bleed `--bg-inverse` (deep ink), used once or twice per page for CTA, founder quote, or hero variant.
- **No gradients. No glass blur. No floating orbs. No dot grids.**

### Motion — canonical
One source of truth: `motion.css`. The full doctrine is in `motion.md`. The shape:
- **One curve.** `--ease: cubic-bezier(0.2, 0, 0, 1)`. Everything uses it.
- **Five timing tokens.** `--t-instant` (120ms hover/press) · `--t-quick` (240ms tooltips/menus) · `--t-base` (360ms route entries) · `--t-slow` (560ms hero) · `--t-march` (1600ms ticker, sequenced reveals).
- **One reveal distance.** `--reveal: 8px` for any opacity+translateY entry. Always the same.
- **No springs. No infinite loops** (single non-decorative exception: `--t-march` for the operational ticker). **No hover-scale. No hover-translate. No glow.**

### Borders & dividers
- Default border: hairline 1px `--border-1` (`rgba(14,17,22,0.10)` light / `rgba(244,245,247,0.10)` dark).
- Stronger: `--border-2`. Editorial rule: `--border-strong` (`--ink-900`).
- Focus: `--focus-ring` 2px outline at 2px offset. **Never** a coloured glow.
- No coloured borders as decoration. Orange is reserved for active/accent states.

### Shadows
Shadows are **floating chrome only** — modals, popovers, dropdowns, command bars. The system has two:
- `--shadow-overlay` — soft drop for menus and dropdowns.
- `--shadow-modal` — modals and popovers.

**No shadows on default cards.** **No coloured shadows.** **No glow.** Cards lift on hover by border-colour shift, not by drop shadow.

### Corner radius
- `--radius-md` (8px) — buttons, inputs, small cards.
- `--radius-lg` (12px) — cards, panels, modal.
- `--radius-xl` (16px) — *only* for full-bleed hero panels. Not for cards, not for tiles, not for CTA blocks.
- `--radius-pill` — avatar, status dot, chip/tag.
- **No `rounded-2xl` / `rounded-3xl`.** That silhouette is removed. The `--radius-2xl` token has been retired from the system.

### Cards
`--bg-2` background, 1px `--border-1` border, 8px radius, `--s-6` interior padding. **No drop shadow by default.** Hover: border shifts to `--border-2`. Featured cards swap to a 1px `--accent` border — never a coloured fill.

### Layout
Asymmetric is the default. Hero h1 sits 2/3 width; the right column is intentionally white-space + a single eyebrow caption. Max content width 1240px. 12-col desktop, 8-col tablet, 4-col mobile. Canonical splits are 8/4 or 7/5, not even thirds.

### Transparency & blur
**No backdrop blur** in the default vocabulary. **No glass.** Nav and overlays use solid backgrounds with hairline borders.

### Imagery
Black-and-white or grain-toned photography preferred. Product screenshots framed in device or window chrome with hairline borders, never a coloured glow. The DF4 logomark is the dominant brand graphic.

---

## Iconography

Phosphor Icons (`@phosphor-icons/react`) at a single weight (`regular` for body, `fill` for small status dots). Monotone — icons inherit `--fg-1` or `--fg-2`. **Never** placed inside a coloured `bg-{colour}-500/10` rounded-tile container.

Sizes: 16 / 20 / 24 / 32. Body inline icons are 16; UI affordances are 20; section markers are 24; hero anchors are 32. Optical alignment via `inline-flex / align-items: center / gap: 0.5em`.

---

## Brand architecture & ownership

- The parent (`data-mode="parent"`) is institutional cool paper. The DF4 wordmark stands alone — DF4 is the parent and never says *"A DF4 Labs company"* about itself.
- Each product company surface (`data-mode="product-dev"` for FoxLitX, `data-mode="product-light"` for Repolize/House AI) carries an `OwnershipLockup` mark in chrome and an `OwnershipBar` strip in footers — *"FoxLitX is a DF4 Labs company"*.
- House AI is the only surface allowed warm paper. Parent and other products use cool paper.

See `brand_architecture.md` for the full doctrine and `brand_architecture.html` for the visual reference.

### `data-mode` & `data-brand` rule

- `data-mode` declares the **palette / surface contract** for a page or app shell.
  - `data-mode="parent"` — DF4 parent surfaces.
  - `data-mode="product-dev"` — dark product surfaces (FoxLitX).
  - `data-mode="product-light"` — light product surfaces (Repolize, House AI).
- `data-brand` declares the **product identity** — only used to scope a product shell.
  - Set on the **same root element** as `data-mode` for that product (the app shell, the page wrapper).
  - **Never** apply `data-brand` on a parent (DF4) page.
  - **Never** apply `data-brand` to random child components — it's a shell-level attribute.

```html
<!-- Parent DF4 page -->
<html data-mode="parent">…</html>

<!-- Product company surface -->
<html data-mode="product-dev" data-brand="foxlitx">…</html>
<html data-mode="product-light" data-brand="repolize">…</html>
<html data-mode="product-light" data-brand="houseai">…</html>
```

---

## System modules — `ui_kits/_system/`

Load-bearing pieces every DF4 surface composes from. Sub-brands may not invent their own equivalents.

| Module | When to use |
|---|---|
| `SectionHeader` | Top of any major page section. Replaces ad-hoc `<h2>` + `<p>` rows. |
| `HeaderTicker` | Thin operational strip at the very top of any DF4 surface. |
| `TelemetryPane` | Live operational monitor. Hero-side, status pages, dashboard headers. |
| `ProductCompanyCard` | Parent-site card for a portfolio company. Carries the ownership lockup. |
| `OwnershipLockup` | Compact `Product · A DF4 Labs company` mark for product chrome. |
| `OwnershipBar` | Footer strip declaring DF4 ownership on product surfaces. |
| `RouteHero` | Top-of-route slab. Three variants: `prose`, `telemetry`, `ledger`. **Required.** |
| `ResearchIndexBlock` | Numbered, dated list of research entries. |
| `LegalDocument` | Research-paper layout for /terms, /privacy, /license, /security. |
| `EmptyState` | Any "no data yet" surface. Hairline-bordered, never decorative. |
| `DataTable` | Operational table primitive. |

Every module reads from CSS custom properties only — a `[data-mode]` and optional `[data-brand]` on an ancestor swaps personality without forking the module.

> **Compose, don't redesign.** A product landing is `RouteHero` + `ProductCompanyCard` + `DataTable` + `SectionHeader` — not a bespoke hero, a bespoke card, a bespoke spec block.

---

## Compliance & rejected history

The full forbidden-patterns list lives in `compliance.md` (and `compliance.html`). Highlights:

- No backdrop blur / glass.
- No coloured glow or coloured shadow on focus rings, buttons, or cards.
- No drop shadow on default cards.
- No `--shadow-1` / `--shadow-2` / `--shadow-3` (rejected legacy — replaced by `--shadow-overlay` / `--shadow-modal`, floating chrome only).
- No `--ease-standard` / `--ease-emphasized` (rejected legacy — replaced by single `--ease`). `--ease-emphasized` is kept only as an alias to `--ease` to avoid breaking older copy-paste.
- No `--ember-*` / `--error` (rejected legacy — replaced by `--orange-*` / `--accent` / `--danger`).
- No Newsreader / IBM Plex (rejected legacy — replaced by Manrope / Inter Tight).
- No `#E2541C` literal — use `var(--accent)`.
- No `.DS_Store` committed. macOS finder droppings should never enter the design system.

---

## Light / dark

Both modes are defined in `colors_and_type.css`. Dark mode inverts paper↔ink, brightens the orange one step (`--orange-500` → `--orange-400`) for AAA contrast, and softens borders. Apply with `[data-mode="product-dev"]` (FoxLitX) or `.dark` on any container.