# Retro Diner - Construction Instructions & AI Prompting Guide
> Version 1.0 - Theme 22 in the catalog - slug `retro-diner`

---

## Table of Contents

1. [Design Philosophy & Core Rules](#1-design-philosophy--core-rules)
2. [Font Law](#2-font-law)
3. [Color Application Rules](#3-color-application-rules)
4. [Border Radius Decision Framework](#4-border-radius-decision-framework)
5. [Shadow & Elevation Rules](#5-shadow--elevation-rules)
6. [Component Construction Guides](#6-component-construction-guides)
7. [Interactive States](#7-interactive-states)
8. [Layout Rules](#8-layout-rules)
9. [Anti-Patterns](#9-anti-patterns)
10. [AI Prompting Guide](#10-ai-prompting-guide)
11. [Pre-Ship Checklist](#11-pre-ship-checklist)

---

## 1. Design Philosophy & Core Rules

50s Americana diner: cream base, cherry-red actions, teal badges, hard offset shadows, pill controls and chunky 3px ink borders.

### The Rules
1. Cream base, cherry-red actions, teal only for badges and status info.
2. Hard offset shadows, never blur.
3. Pill shapes for buttons, inputs and badges; 16px cards.
4. Every interactive element carries a 3px ink border.

---

## 2. Font Law

Use only Lilita One and Nunito Sans. Fallback stacks end in `system-ui, sans-serif`.

- Display and headings: Lilita One, weight 400, no tracking. Lilita One has one weight only - never fake bold on it.
- Body: Nunito Sans, weight 400 or 600.
- Labels, buttons and badges: Nunito Sans, weight 700, sentence case.
- Never mix in a font from another system. If a glyph is missing, fall back, do not swap families.

---

## 3. Color Application Rules

| Use | Token | Value |
|---|---|---|
| Page | `--ds-color-bg-base` | `#fff8e7` |
| Cards | `--ds-color-bg-surface` | `#fffdf4` |
| Inputs, wells | `--ds-color-bg-sunken` | `#f2e9d0` |
| Main action | `--ds-color-primary` | `#d42b3a` |
| Secondary action | `--ds-btn-secondary-bg` | `#33312e` |
| Body text | `--ds-color-text-primary` | `#33312e` |
| Supporting text | `--ds-color-text-secondary` | `#4a463e` |

- One main action per view, always cherry red.
- Teal `#2a9d8f` is for badges and info surfaces only. Never a teal button, heading or link.
- Mustard `#f4d35e` is a fill (table headers, highlights, focus shadow), never a text colour on cream.
- Never type a raw hex or font name in a component. Read the token.
- Semantic colours (success, warning, error, info) are for status only.

---

## 4. Border Radius Decision Framework

- Badge or chip: 999px.
- Button or input: 9999px - always a full pill.
- Card: 16px. Modal or large panel: 20px.
- Checkbox: 8px.
- Anything else: use the nearest token. Never invent a radius.

---

## 5. Shadow & Elevation Rules

- Cards: `6px 6px 0 #d42b3a`.
- Dropdowns: `5px 5px 0 #33312e`.
- Modals: `8px 8px 0 #d42b3a`.
- Focus: `4px 4px 0 #f4d35e`.
- No blurred shadows, no soft glows, no gradients pretending to be shadows.

---

## 6. Component Construction Guides

**Card:** surface background, 3px border `#33312e`, radius 16px, card shadow, padding 22px.

**Button:** pick one variant, always a pill. Label Nunito Sans 700, sentence case. Pressed state is `translate(4px, 4px)` with the shadow collapsing.

**Badge:** pill, label style, cherry or teal fill, no shadow.

**Table:** header uses `#f4d35e` with `#33312e` text. Rows separated by ink borders.

**Form field:** label above, helper text below in muted colour, error replaces helper text. Inputs are pills with a 3px ink border.

---

## 7. Interactive States

| State | Rule |
|---|---|
| Hover | Primary darkens one step. Shadow `4px 4px 0 #33312e` |
| Active | `translate(4px, 4px)`, shadow collapses |
| Focus | `4px 4px 0 #f4d35e`, always visible |
| Disabled | Text `#8a7f6a`, no hover |

---

## 8. Layout Rules

- Max content width 1040px, 24px gutters.
- Stack to one column below 768px.
- Keep one primary action per section and align it to the same edge as the heading.

---

## 9. Anti-Patterns

- Do not use teal for buttons, headings or links. Badges and info only.
- Do not put mustard or teal text on cream. They fail contrast.
- Do not use blur, gradients or soft shadows.
- Do not use square buttons or inputs. Pills only.
- Do not hard-code colours, fonts, radii or shadows in components.
- Do not define tokens at `:root`. Everything stays under `[data-ds="retro-diner"]`.
- Do not mix components from other design systems on the same page.

---

## 10. AI Prompting Guide

Paste this at the start of a chat:

> Build the UI with the Retro Diner design system. Read `design-system.md` and `instructions.md` first. Use only the `--ds-*` tokens under `[data-ds="retro-diner"]`. Fonts: Lilita One for headings, Nunito Sans for everything else. Follow every rule in section 1 of instructions.md. Do not add styles that are not in the token sheet. When unsure, ask before inventing.

Good follow-up prompts:
- "Add a menu section using only Retro Diner tokens."
- "Check this page against the Retro Diner anti-pattern list and fix violations."

---

## 11. Pre-Ship Checklist

- [ ] All colours, fonts, radii and shadows come from tokens
- [ ] One main action per view, in cherry red
- [ ] Teal appears only on badges or info surfaces
- [ ] Buttons and inputs are full pills
- [ ] Shadows are hard offsets, never blurred
- [ ] Text contrast is 4.5:1 or better
- [ ] Focus state is visible on every interactive element
- [ ] Wrapped in `data-ds="retro-diner"`