# Candy Soft - Construction Instructions & AI Prompting Guide
> Version 1.0 - Theme 13 in the catalog - slug `candy-soft`

---

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

Pastel pink and mint with flat block shadows, big radii and rounded Quicksand type.

### The Rules
1. Every card sits on a flat colour block shadow. No blur, ever.
2. Corners are always 14px or larger. Cards use 26px.
3. Text stays deep plum for contrast. Pink is for fills and borders, never for body text.
4. Mint is the secondary accent. Use it for success moments and secondary buttons.

---

## 2. Font Law

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

- Display and headings: Quicksand, weight 700, tracking -0.01em.
- Body: Quicksand.
- Labels: Quicksand, none, weight 700.
- 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` | `#fff5f8` |
| Cards | `--ds-color-bg-surface` | `#ffffff` |
| Inputs, wells | `--ds-color-bg-sunken` | `#ffeaf2` |
| Main action | `--ds-color-primary` | `#c8326f` |
| Secondary action | `--ds-btn-secondary-bg` | `#7fe0c3` |
| Body text | `--ds-color-text-primary` | `#4a2a3a` |
| Supporting text | `--ds-color-text-secondary` | `#7a5266` |

- 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: 18px.
- Card or modal: 26px.
- Anything else: use the nearest token. Never invent a radius.

---

## 5. Shadow & Elevation Rules

- Cards: `0 6px 0 #ffd3e2`.
- Dropdowns: `0 5px 0 #ffb8d1`.
- Modals: `0 8px 0 #ffb8d1`.
- Focus: `0 0 0 3px #ffb8d1`.
- Do not mix shadow styles from other systems.

---

## 6. Component Construction Guides

**Card:** surface background, 2px border `#ffd3e2`, radius 26px, card shadow, padding 24px.

**Button:** pick one variant. Label style `none`, weight 700. Pressed state is `translateY(3px)`.

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

**Table:** header uses `#ffd3e2` with `#4a2a3a` 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 5px 0 #a82b5c` |
| Active | `translateY(3px)` |
| Focus | `0 0 0 3px #ffb8d1`, always visible |
| Disabled | Text `#b8a0ab`, 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 blurred shadows. Use the flat block shadow only.
- Do not use grey. Greys are replaced by plum tints.
- Do not set body text in the pink fill colour.
- Do not hard-code colours, fonts, radii or shadows in components.
- Do not define tokens at `:root`. Everything stays under `[data-ds="candy-soft"]`.
- 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 Candy Soft design system. Read `design-system.md` and `instructions.md` first. Use only the `--ds-*` tokens under `[data-ds="candy-soft"]`. Fonts: Quicksand. 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 Candy Soft tokens."
- "Check this page against the Candy Soft 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="candy-soft"`