# Retro Diner - Complete Design System
> Version 1.0 - Theme 22 in the catalog - slug `retro-diner`

---

## Table of Contents

1. [System Overview](#1-system-overview)
2. [CSS Custom Properties - Master Token Sheet](#2-css-custom-properties--master-token-sheet)
3. [Color Palette](#3-color-palette)
4. [Typography System](#4-typography-system)
5. [Spacing System](#5-spacing-system)
6. [Border Radius System](#6-border-radius-system)
7. [Shadow & Elevation System](#7-shadow--elevation-system)
8. [Component Specifications](#8-component-specifications)
9. [Layout & Grid System](#9-layout--grid-system)
10. [Animation & Transition Tokens](#10-animation--transition-tokens)
11. [Z-Index System](#11-z-index-system)
12. [Breakpoints](#12-breakpoints)
13. [Icon System](#13-icon-system)
14. [State Definitions](#14-state-definitions)

---

## 1. System Overview

**Design Language:** Retro Diner
**Mode:** Light
**Typefaces:** Lilita One + Nunito Sans
**Personality:** 50s Americana diner: cream base, cherry-red actions, teal badges, hard offset shadows, pill controls and chunky 3px ink borders.
**Best Suited For:** Food and drink brands, diners and cafes, event pages, playful marketing sites, retro landing pages

**Core Principles:**
- Cream base, cherry-red actions, teal only for badges and status info.
- Hard offset shadows, never blur.
- Pill shapes for buttons, inputs and badges; 16px cards.
- Every interactive element carries a 3px ink border.

---

## 2. CSS Custom Properties - Master Token Sheet

All tokens are scoped under `[data-ds="retro-diner"]`. Nothing is defined at `:root`. The same sheet ships as `tokens.css` in this system's folder.

```css
[data-ds="retro-diner"] {
  --ds-color-bg-base: #fff8e7;
  --ds-color-bg-surface: #fffdf4;
  --ds-color-bg-sunken: #f2e9d0;
  --ds-color-bg-secondary: #f2e9d0;
  --ds-color-bg-overlay: rgba(51,49,46,0.5);

  --ds-color-primary: #d42b3a;
  --ds-color-primary-hover: #b82431;
  --ds-color-primary-active: #9c1f2b;
  --ds-color-primary-fg: #fff8e7;

  --ds-color-text-primary: #33312e;
  --ds-color-text-secondary: #4a463e;
  --ds-color-text-tertiary: #5c5648;
  --ds-color-text-muted: #6f6655;
  --ds-color-text-disabled: #8a7f6a;
  --ds-color-text-inverse: #fff8e7;

  --ds-color-border-light: #33312e;
  --ds-color-border-medium: #33312e;
  --ds-color-border-strong: #33312e;

  --ds-color-success: #1b7441;
  --ds-color-success-bg: #d7f2e0;
  --ds-color-warning: #8a5700;
  --ds-color-warning-bg: #fff0cc;
  --ds-color-error: #c0262d;
  --ds-color-error-bg: #fde3e4;
  --ds-color-info: #1a5a52;
  --ds-color-info-bg: #dcf0ed;

  --ds-font-display: "Lilita One", system-ui, sans-serif;
  --ds-font-body: "Nunito Sans", system-ui, sans-serif;
  --ds-font-label: "Nunito Sans", system-ui, sans-serif;
  --ds-label-transform: none;
  --ds-label-tracking: 0.01em;
  --ds-label-weight: 700;
  --ds-heading-tracking: 0;
  --ds-heading-weight: 400;

  --ds-radius-badge: 999px;
  --ds-radius-sm: 8px;
  --ds-radius-md: 9999px;
  --ds-radius-lg: 16px;
  --ds-radius-xl: 20px;
  --ds-radius-full: 9999px;

  --ds-border-width: 3px;

  --ds-shadow-card: 6px 6px 0 #d42b3a;
  --ds-shadow-dropdown: 5px 5px 0 #33312e;
  --ds-shadow-modal: 8px 8px 0 #d42b3a;
  --ds-shadow-focus: 4px 4px 0 #f4d35e;
  --ds-shadow-btn-hover: 4px 4px 0 #33312e;

  --ds-btn-text-transform: none;
  --ds-btn-letter-spacing: 0.01em;
  --ds-btn-font-weight: 700;
  --ds-btn-active-transform: translate(4px, 4px);
  --ds-btn-secondary-bg: #33312e;
  --ds-btn-secondary-text: #fff8e7;
  --ds-btn-secondary-border: #33312e;
  --ds-btn-secondary-hover-bg: #4a463e;
  --ds-btn-outline-text: #33312e;
  --ds-btn-outline-border: #33312e;
  --ds-btn-outline-hover-bg: #f2e9d0;
  --ds-btn-outline-hover-text: #33312e;

  --ds-table-header-bg: #f4d35e;
  --ds-table-header-text: #33312e;
  --ds-table-header-border-bottom: 3px solid #33312e;
  --ds-table-container-radius: 16px;
  --ds-table-container-border: 3px solid #33312e;

  --ds-focus-ring: 4px 4px 0 #f4d35e;

  --ds-ease-standard: cubic-bezier(0.4, 0, 0.2, 1);
  --ds-duration-fast: 0ms;
  --ds-duration-base: 120ms;
  --ds-duration-slow: 200ms;
}

[data-ds="retro-diner"] .ds-card, [data-ds="retro-diner"] .ds-modal { border-width: 3px; }
[data-ds="retro-diner"] .ds-btn:active:not(:disabled) { box-shadow: 0 0 0 #33312e; }
```

---

## 3. Color Palette

### 3.1 Core Colors

| Role | Value |
|---|---|
| Page background | `#fff8e7` |
| Surface | `#fffdf4` |
| Sunken | `#f2e9d0` |
| Secondary surface | `#f2e9d0` |
| Primary action (cherry) | `#d42b3a` |
| Primary text on action | `#fff8e7` |
| Badge / info accent (teal) | `#2a9d8f` |
| Highlight fill (mustard) | `#f4d35e` |
| Text primary (ink) | `#33312e` |
| Text secondary | `#4a463e` |
| Text muted | `#6f6655` |
| Border (all weights) | `#33312e` |

### 3.2 Semantic Colors

| Status | Foreground | Background | Contrast |
|---|---|---|---|
| Success | `#1b7441` | `#d7f2e0` | 4.9:1 |
| Warning | `#8a5700` | `#fff0cc` | 5.4:1 |
| Error | `#c0262d` | `#fde3e4` | 4.9:1 |
| Info | `#1a5a52` | `#dcf0ed` | 6.6:1 |

### 3.3 Contrast Checks

All pairs below meet WCAG AA (4.5:1) for normal text.

| Pair | Colors | Ratio |
|---|---|---|
| Body text | `#33312e` on `#fff8e7` | 12.0:1 |
| Secondary text | `#4a463e` on `#fff8e7` | 8.4:1 |
| Muted text | `#6f6655` on `#fff8e7` | 5.5:1 |
| Primary button label | `#fff8e7` on `#d42b3a` | 4.6:1 |
| Secondary button label | `#fff8e7` on `#33312e` | 12.0:1 |
| Table header | `#33312e` on `#f4d35e` | 8.3:1 |

Bright teal `#2a9d8f` is a fill colour for badges, not a text colour. Use the info pair for teal-tinted text.

---

## 4. Typography System

### 4.1 Font Families

| Role | Family | Usage |
|---|---|---|
| Display | Lilita One | Headings, hero titles |
| Body | Nunito Sans | Body copy, form fields |
| Label | Nunito Sans | Buttons, badges, labels |

### 4.2 Type Scale

| Token | Size | Weight | Tracking | Use |
|---|---|---|---|---|
| Display | 48-64px | 400 | 0 | Hero title |
| H1 | 36px | 400 | 0 | Page title |
| H2 | 28px | 400 | 0 | Section title |
| H3 | 20px | 400 | 0 | Card title |
| Body | 16px | 400 | 0 | Paragraphs |
| Label | 13px | 700 | 0.01em | Buttons, badges |

Lilita One ships in a single weight (400). Its drawn strokes are already heavy - never synthesise a bolder weight.

### 4.3 Google Fonts Import Block

```css
@import url("https://fonts.googleapis.com/css2?family=Lilita+One&family=Nunito+Sans:wght@400;600;700&display=swap");
```

The same URL is loaded by `app/design-systems/fonts.ts`.

---

## 5. Spacing System

Base unit: 4px. Use only these steps.

| Token | Value |
|---|---|
| space-1 | 4px |
| space-2 | 8px |
| space-3 | 12px |
| space-4 | 16px |
| space-6 | 24px |
| space-8 | 32px |
| space-12 | 48px |
| space-16 | 64px |

Component padding: card 22px, button 11px 22px (md), input 11px 14px, badge 3px 12px.

---

## 6. Border Radius System

| Element | Radius |
|---|---|
| Badge | 999px |
| Small controls (checkbox) | 8px |
| Buttons, inputs | 9999px (pill) |
| Cards | 16px |
| Modals, large panels | 20px |
| Avatars, switches | 9999px |

Border width: 3px on every interactive element and card.

---

## 7. Shadow & Elevation System

Hard offset shadows only. Blur is banned in this system.

| Level | Value |
|---|---|
| Card | `6px 6px 0 #d42b3a` |
| Dropdown | `5px 5px 0 #33312e` |
| Modal | `8px 8px 0 #d42b3a` |
| Focus | `4px 4px 0 #f4d35e` |
| Button hover | `4px 4px 0 #33312e` |

---

## 8. Component Specifications

### 8.1 Buttons
- Primary: background `--ds-color-primary`, label `--ds-color-primary-fg`. Hover `#b82431`, active `#9c1f2b`.
- Secondary: background `#33312e`, label `#fff8e7`.
- Outline: transparent, border `#33312e`, label `#33312e`, hover fill `#f2e9d0`.
- Label style: Nunito Sans, weight 700, no transform, tracking 0.01em.
- Shape: full pill on every variant.
- Active (pressed): `transform: translate(4px, 4px)` and the shadow collapses.

### 8.2 Form Inputs
Surface background, 3px border `#33312e`, pill radius. Focus uses the focus shadow. Error border `#c0262d`.

### 8.3 Labels
Nunito Sans, weight 700, tracking 0.01em, colour `#4a463e`. Sentence case - never uppercase.

### 8.4 Card / Surface
Background `#fffdf4`, border 3px `#33312e`, radius 16px, card shadow `6px 6px 0 #d42b3a`.

### 8.5 Badge
Pill, label style. Cherry, mustard and teal fills come from the palette; semantic statuses use section 3.2. Teal is reserved for badges and info - never for buttons or headings.

### 8.6 Checkbox, Radio and Switch
Checked fill `#d42b3a`, mark `#fff8e7`. Radius 8px on checkboxes; radio and switch stay round.

### 8.7 Table
Header background `#f4d35e`, header text `#33312e`. Container border `3px solid #33312e`, radius 16px.

### 8.8 Dropdown Panel
Surface background, border 3px `#33312e`, dropdown shadow, item hover uses `#f2e9d0`.

---

## 9. Layout & Grid System

| Container | Max width |
|---|---|
| Narrow (forms, articles) | 640px |
| Default | 1040px |
| Wide (dashboards) | 1280px |

12-column grid, 24px gutters on desktop, 16px on mobile.

---

## 10. Animation & Transition Tokens

| Token | Value |
|---|---|
| Easing | `cubic-bezier(0.4, 0, 0.2, 1)` |
| Fast | 0ms |
| Base | 120ms |
| Slow | 200ms |

Animate colour, transform, opacity and shadow only. Never animate layout properties.

---

## 11. Z-Index System

| Layer | Value |
|---|---|
| Base | 0 |
| Sticky header | 10 |
| Dropdown | 20 |
| Modal backdrop | 40 |
| Modal | 50 |
| Toast | 60 |

---

## 12. Breakpoints

| Name | Min width |
|---|---|
| sm | 640px |
| md | 768px |
| lg | 1024px |
| xl | 1280px |

Page padding: 16px below md, 24px at md, 32px at lg and up.

---

## 13. Icon System

Use Lucide icons at 16, 20 or 24px, stroke 2px. Icon colour follows text colour. Rounded line caps suit this system. Never use filled multi-colour icons.

---

## 14. State Definitions

| State | Treatment |
|---|---|
| Hover | Darker primary (see 8.1), shadow `4px 4px 0 #33312e` |
| Active | `translate(4px, 4px)`, shadow collapses |
| Focus | `4px 4px 0 #f4d35e` |
| Disabled | Text `#8a7f6a`, no shadow, cursor not-allowed |
| Error | Border `#c0262d`, message in the same colour |
| Success | Border `#1b7441` |