# Ocean Aqua - Construction Instructions & AI Prompting Guide
> Version 1.0 - Theme 20 in the catalog - slug `ocean-aqua`

---

## 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

Fresh teal and sea-glass surfaces with bubble corners, coral accents and Rubik type.

### The Rules
1. Bubble corners: cards are 30px 30px 8px 30px. The small corner sits bottom right.
2. Teal (#077689) for actions, coral (#ff9f68) as a tiny accent. Never both on one button.
3. Shadows are soft and blue-tinted, never black.
4. Rubik at weights 400, 500, 700 for everything.

---

## 2. Font Law

Use only Rubik. Fallback stack ends in `system-ui, sans-serif`.

- Display and headings: Rubik, weight 700, tracking -0.01em.
- Body: Rubik.
- Labels: Rubik, none, weight 500.
- 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` | `#e8fbfc` |
| Cards | `--ds-color-bg-surface` | `#ffffff` |
| Inputs, wells | `--ds-color-bg-sunken` | `#d3f3f5` |
| Main action | `--ds-color-primary` | `#077689` |
| Secondary action | `--ds-btn-secondary-bg` | `#ff9f68` |
| Body text | `--ds-color-text-primary` | `#06394a` |
| Supporting text | `--ds-color-text-secondary` | `#2c5f6f` |

- One main action per view.
- 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: 14px.
- Card or modal: 30px with the asymmetric corner from tokens.css.
- Anything else: use the nearest token. Never invent a radius.

---

## 5. Shadow & Elevation Rules

- Cards: `0 14px 30px rgba(6,57,74,0.16)`.
- Dropdowns: `0 14px 30px rgba(6,57,74,0.2)`.
- Modals: `0 24px 56px rgba(6,57,74,0.28)`.
- Focus: `0 0 0 3px rgba(7,118,137,0.35)`.
- Do not mix shadow styles from other systems.

---

## 6. Component Construction Guides

**Card:** surface background, 1px border `#b5e6ea`, radius 30px, card shadow, padding 24px.

**Button:** pick one variant. Label style `none`, weight 500. Pressed state is `scale(0.97)`.

**Badge:** label style, semantic background, no shadow.

**Table:** header uses `#b5e6ea` with `#06394a` text. Rows separated by border light.

**Form field:** label above, helper text below in muted colour, error replaces helper text.

---

## 7. Interactive States

| State | Rule |
|---|---|
| Hover | Primary darkens or lightens one step. Shadow `0 8px 18px rgba(7,118,137,0.35)` |
| Active | `scale(0.97)` |
| Focus | `0 0 0 3px rgba(7,118,137,0.35)`, always visible |
| Disabled | Text `#8db5bd`, 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 black shadows or pure black text. Text is deep teal (#06394a).
- Do not use coral for more than a badge or one chart series.
- Do not use sharp 0px corners.
- Do not hard-code colours, fonts, radii or shadows in components.
- Do not define tokens at `:root`. Everything stays under `[data-ds="ocean-aqua"]`.
- 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 Ocean Aqua design system. Read `design-system.md` and `instructions.md` first. Use only the `--ds-*` tokens under `[data-ds="ocean-aqua"]`. Fonts: Rubik. 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 pricing section using only Ocean Aqua tokens."
- "Check this page against the Ocean Aqua anti-pattern list and fix violations."

---

## 11. Pre-Ship Checklist

- [ ] All colours, fonts, radii and shadows come from tokens
- [ ] One main action per view
- [ ] Text contrast is 4.5:1 or better
- [ ] Focus state is visible on every interactive element
- [ ] No rule from section 9 is broken
- [ ] Wrapped in `data-ds="ocean-aqua"`