# Brand Kit: Wellness Weekly

A complete design system for AI coding agents (Cursor, Claude Code, v0, Lovable, Google Stitch, etc.).

## How to use this file

Tell your agent:

> **Follow DESIGN.md and AGENTS.md step by step to build the entire site.**

The agent must read this file completely before writing UI code. Pair with `AGENTS.md`, `rules/build-site.md`, and copy-voice rules from your agent rules bundle.

**Kickoff prompt** (paste once per session):

> Follow AGENTS.md step by step to build the entire site. Read DESIGN.md for every visual decision. Apply copy-voice rules on all user-facing text. Do not skip phases.

## Overview

- **Vibe**: Health newsletter media
- **Primary Use**: Websites, apps, marketing assets, SaaS dashboards.
- **Export version**: 2.0.0

## Typography

### Headline Font

- **Family**: Sora
- **Weights**: 400, 500, 600, 700
- **Usage**: Page titles, hero headlines, section headers.

### Body Font

- **Family**: Inter
- **Weights**: 400, 500, 600, 700
- **Usage**: Paragraphs, UI text, long-form content.

**Recommended Sizes**:

- h1: 3.5rem / 56px (bold)
- h2: 2.25rem / 36px
- h3: 1.5rem / 24px
- Body: 1rem / 16px
- Small: 0.875rem / 14px

## Voice & Tone

Derived from vibe: **Health newsletter media**

### Personality

- **Tone**: Clear, confident, and trustworthy. Avoid slang.
- **Brand name**: Always "Wellness Weekly" (consistent capitalization)
- **Pronouns**: "we" for product, "you" for the reader

### Copy examples

- "Built for teams who ship fast."
- "Your data, secured by design."
- "Start free — upgrade when you're ready."

### Do / Don't

| Do | Don't |
|----|-------|
| Use active voice | Use jargon without explanation |
| Keep CTAs to 2–4 words | Overpromise or use hype |
| Match headline font energy in hero copy | Mix multiple brand voices |
| Use commas or periods for pauses | Use em dashes (—) or en dashes for emphasis |
| Write like a human product page | Use AI phrases: delve, seamless, leverage, robust, journey |

See `rules/copy-voice.md` in the agent rules bundle for the full banned phrase list.


## Imagery & Mood Board

### Photography
Clean studio or office settings, even lighting, authentic expressions.

### Illustration
Simple UI-style icons, consistent stroke weight, brand color accents.

### Stock direction
Modern workspaces, product UI screenshots, diverse professionals.

### Mood keywords
- trustworthy
- clear
- modern
- professional

### AI prompts
- **Midjourney**: `Wellness Weekly brand mood board, trustworthy, clear, modern, professional, Clean studio or office settings, even lighting, authentic expressions., color palette #29ae62, #31a7b9, #f8fbfa, cohesive visual identity, --ar 16:9 --style raw`
- **Flux**: `Wellness Weekly brand imagery: trustworthy, clear, modern, professional. Photography: Clean studio or office settings, even lighting, authentic expressions.. Illustration: Simple UI-style icons, consistent stroke weight, brand color accents.. Colors: #29ae62, #31a7b9, #f8fbfa.`


## Color Palette

**CSS Variables** (Tailwind v4 ready — see `globals.css` in zip):

```css
:root {
  --background: #f8fbfa;
  --foreground: #183a27;
  --card: #ebf5ef;
  --primary: #29ae62;
  --primary-foreground: #ffffff;
  --accent: #31a7b9;
  --accent-foreground: #ffffff;
  --secondary: #deede4;
  --secondary-foreground: #183a27;
  --destructive: #dc2626;
  --destructive-foreground: #ffffff;
  --success: #16a34a;
  --success-foreground: #ffffff;
  --muted: #deede4;
  --border: #c5ddd0;
}

.dark {
  --background: #3e3f3f;
  --foreground: #fafafa;
  /* … see globals.css for full dark palette */
}
```

### Semantic Tokens (light)

- **Background**: #f8fbfa — Main page/app background
- **Surface / Card**: #ebf5ef — Cards, modals, elevated surfaces
- **Text / Foreground**: #183a27
- **Primary**: #29ae62 — Buttons, links, accents
- **Primary Foreground**: #ffffff — Text on primary surfaces
- **Accent**: #31a7b9 — Highlights, CTAs, interactive elements
- **Accent Foreground**: #ffffff — Text on accent surfaces
- **Secondary**: #deede4 — Secondary buttons, subtle actions
- **Secondary Foreground**: #183a27
- **Destructive**: #dc2626 — Errors, delete actions
- **Destructive Foreground**: #ffffff
- **Success**: #16a34a — Confirmations, positive states
- **Success Foreground**: #ffffff
- **Muted**: #deede4 — Subtle backgrounds, disabled states
- **Border**: #c5ddd0 — Dividers, input borders

### Light palette

| Token | Hex |
|-------|-----|
| background | #f8fbfa |
| foreground | #183a27 |
| card | #ebf5ef |
| primary | #29ae62 |
| primaryForeground | #ffffff |
| accent | #31a7b9 |
| accentForeground | #ffffff |
| muted | #deede4 |
| border | #c5ddd0 |
| secondary | #deede4 |
| secondaryForeground | #183a27 |
| destructive | #dc2626 |
| destructiveForeground | #ffffff |
| success | #16a34a |
| successForeground | #ffffff |
| warning | #d97706 |
| warningForeground | #ffffff |
| ring | #29ae62 |
| input | #c5ddd0 |
| popover | #ebf5ef |
| popoverForeground | #183a27 |

### Dark palette (auto-generated)

| Token | Hex |
|-------|-----|
| background | #3e3f3f |
| foreground | #fafafa |
| card | #525654 |
| primary | #2fc871 |
| primaryForeground | #fafafa |
| accent | #36b8cc |
| accentForeground | #fafafa |
| muted | #646b67 |
| border | #6c7a72 |
| secondary | #646b67 |
| secondaryForeground | #fafafa |
| destructive | #dc2626 |
| destructiveForeground | #ffffff |
| success | #16a34a |
| successForeground | #ffffff |
| warning | #d97706 |
| warningForeground | #ffffff |
| ring | #2fc871 |
| input | #6c7a72 |
| popover | #525654 |
| popoverForeground | #fafafa |

### Usage Rules

- Always maintain high contrast (WCAG AA+).
- Primary for actions, Accent for highlights, Secondary for low-emphasis actions.
- Destructive for errors/delete, Success for confirmations.
- Use muted backgrounds for secondary content areas.
- Never hardcode hex values in components — always use tokens.

## WCAG Contrast Report

Auto-generated from your palette. Target **AA** (4.5:1 body, 3:1 large text) or better.

### Light mode

| Pair | Colors | Ratio | Grade | Pass |
|------|--------|-------|-------|------|
| Body on background | #183a27 on #f8fbfa | 12.05:1 | AAA | ✓ |
| Button label on primary | #ffffff on #29ae62 | 2.87:1 | Fail | ✗ |
| Headline on background | #183a27 on #f8fbfa | 12.05:1 | AAA | ✓ |
| Text on card | #183a27 on #ebf5ef | 11.26:1 | AAA | ✓ |
| Accent label on accent | #ffffff on #31a7b9 | 2.85:1 | Fail | ✗ |
| Destructive label | #ffffff on #dc2626 | 4.83:1 | AA | ✓ |
| Success label | #ffffff on #16a34a | 3.30:1 | Fail | ✗ |

### Dark mode

| Pair | Colors | Ratio | Grade | Pass |
|------|--------|-------|-------|------|
| Body on background | #fafafa on #3e3f3f | 10.12:1 | AAA | ✓ |
| Button label on primary | #fafafa on #2fc871 | 2.09:1 | Fail | ✗ |
| Headline on background | #fafafa on #3e3f3f | 10.12:1 | AAA | ✓ |
| Text on card | #fafafa on #525654 | 7.14:1 | AAA | ✓ |
| Accent label on accent | #fafafa on #36b8cc | 2.26:1 | Fail | ✗ |
| Destructive label | #ffffff on #dc2626 | 4.83:1 | AA | ✓ |
| Success label | #ffffff on #16a34a | 3.30:1 | Fail | ✗ |

### Notes

- **AAA** = 7:1 or higher (enhanced)
- **AA** = 4.5:1 or higher (normal text)
- **AA Large** = 3:1 or higher (18px+ bold or 24px+ regular)
- Fix failing pairs by adjusting foreground/background tokens in `tokens.json`


## Spacing Scale

| Token | Value |
|-------|-------|
| xs | 0.25rem / 4px |
| sm | 0.5rem / 8px |
| md | 1rem / 16px |
| lg | 1.5rem / 24px |
| xl | 2rem / 32px |
| 2xl | 3rem / 48px |
| 3xl | 4rem / 64px |

## Border Radius

| Token | Value |
|-------|-------|
| sm | 0.25rem / 4px |
| md | 0.5rem / 8px |
| lg | 0.75rem / 12px |
| xl | 1rem / 16px |
| full | 9999px / 9999px |

## Shadows

| Token | Value |
|-------|-------|
| sm | 0 1px 2px 0 rgb(0 0 0 / 0.05) |
| md | 0 4px 6px -1px rgb(0 0 0 / 0.1) |
| lg | 0 10px 15px -3px rgb(0 0 0 / 0.1) |
| xl | 0 20px 25px -5px rgb(0 0 0 / 0.1) |

## Breakpoints & Layout

| Token | Min width | Usage |
|-------|-----------|-------|
| sm | 640px | Large phones |
| md | 768px | Tablets |
| lg | 1024px | Laptops |
| xl | 1280px | Desktops |
| 2xl | 1536px | Wide screens |

### Layout rules

- **Container max**: 72rem (`max-w-6xl` or `max-w-7xl`)
- **Content max** (prose): 42rem (`max-w-2xl`)
- **Section padding**: `var(--spacing-xl)` horizontal on mobile, increase on `lg+`
- **Nav height**: 3.5rem (`h-14`)
- **Grid**: 1 column mobile → 2 columns `md` → 3–4 columns `lg` for feature grids


## Motion

| Token | Value | Usage |
|-------|-------|-------|
| duration-fast | 150ms | Hovers, toggles |
| duration-normal | 250ms | Modals, dropdowns |
| duration-slow | 400ms | Page transitions |
| ease-default | cubic-bezier(0.4, 0, 0.2, 1) | Most animations |

### Rules

- Prefer `opacity` and `transform` over layout-affecting properties
- Use `transition-opacity duration-[var(--duration-fast)]` for buttons
- Respect `prefers-reduced-motion: reduce` — disable non-essential animation


## Design Tokens (Tailwind Config Ready)

```typescript
// tailwind.config.ts excerpt (or use globals.css @theme for Tailwind v4)
theme: {
  extend: {
    fontFamily: {
      heading: ['Sora', 'sans-serif'],
      body: ['Inter', 'sans-serif'],
    },
    colors: {
      background: 'var(--background)',
      foreground: 'var(--foreground)',
      card: 'var(--card)',
      primary: 'var(--primary)',
      'primary-foreground': 'var(--primary-foreground)',
      accent: 'var(--accent)',
      'accent-foreground': 'var(--accent-foreground)',
      secondary: 'var(--secondary)',
      'secondary-foreground': 'var(--secondary-foreground)',
      destructive: 'var(--destructive)',
      'destructive-foreground': 'var(--destructive-foreground)',
      success: 'var(--success)',
      'success-foreground': 'var(--success-foreground)',
      muted: 'var(--muted)',
      border: 'var(--border)',
    },
  },
}
```

## Implementation Instructions

This kit ships as a complete Pro .zip export:

1. Unzip, run `npm install`, then `npm run dev`.
2. Open `README.txt` and paste that one-line prompt into Cursor, Claude Code, or v0.
3. The agent reads `AGENTS.md`, `DESIGN.md`, and `rules/` then builds the site phase by phase.
4. Starter lives in `app/` and `components/brand/`. Tokens are in `app/globals.css` and `tokens.json`.
5. Open Graph image: `public/og-image.png`. Favicons: `public/logo-pack/` and `app/favicon.ico`.

## Example Usage Prompt for AI Agents

> "Build a dashboard using this brand kit. Follow the DESIGN.md exactly: use Sora for headings, Inter for body, and the defined color tokens. Maintain clean spacing and high contrast."

## JSON Tokens (machine-parseable)

See `tokens.json`, `tokens.w3c.json`, and `tokens.figma.json` in the zip.

```json
{
  "meta": {
    "name": "Wellness Weekly",
    "vibe": "Health newsletter media",
    "version": "2.0.0",
    "exportedAt": "2026-07-04T04:16:41.954Z"
  },
  "typography": {
    "headline": {
      "family": "Sora",
      "weights": [
        400,
        500,
        600,
        700
      ]
    },
    "body": {
      "family": "Inter",
      "weights": [
        400,
        500,
        600,
        700
      ]
    },
    "scale": [
      {
        "token": "h1",
        "size": "3.5rem",
        "lineHeight": "1.1",
        "weight": 700
      },
      {
        "token": "h2",
        "size": "2.25rem",
        "lineHeight": "1.2",
        "weight": 600
      },
      {
        "token": "h3",
        "size": "1.5rem",
        "lineHeight": "1.3",
        "weight": 600
      },
      {
        "token": "body",
        "size": "1rem",
        "lineHeight": "1.6",
        "weight": 400
      },
      {
        "token": "small",
        "size": "0.875rem",
        "lineHeight": "1.5",
        "weight": 400
      }
    ]
  },
  "colors": {
    "light": {
      "background": "#f8fbfa",
      "foreground": "#183a27",
      "card": "#ebf5ef",
      "primary": "#29ae62",
      "primaryForeground": "#ffffff",
      "accent": "#31a7b9",
      "accentForeground": "#ffffff",
      "muted": "#deede4",
      "border": "#c5ddd0",
      "secondary": "#deede4",
      "secondaryForeground": "#183a27",
      "destructive": "#dc2626",
      "destructiveForeground": "#ffffff",
      "success": "#16a34a",
      "successForeground": "#ffffff",
      "warning": "#d97706",
      "warningForeground": "#ffffff",
      "ring": "#29ae62",
      "input": "#c5ddd0",
      "popover": "#ebf5ef",
      "popoverForeground": "#183a27"
    },
    "dark": {
      "background": "#3e3f3f",
      "foreground": "#fafafa",
      "card": "#525654",
      "primary": "#2fc871",
      "primaryForeground": "#fafafa",
      "accent": "#36b8cc",
      "accentForeground": "#fafafa",
      "muted": "#646b67",
      "border": "#6c7a72",
      "secondary": "#646b67",
      "secondaryForeground": "#fafafa",
      "destructive": "#dc2626",
      "destructiveForeground": "#ffffff",
      "success": "#16a34a",
      "successForeground": "#ffffff",
      "warning": "#d97706",
      "warningForeground": "#ffffff",
      "ring": "#2fc871",
      "input": "#6c7a72",
      "popover": "#525654",
      "popoverForeground": "#fafafa"
    }
  },
  "spacing": [
    {
      "token": "xs",
      "value": "0.25rem",
      "px": 4
    },
    {
      "token": "sm",
      "value": "0.5rem",
      "px": 8
    },
    {
      "token": "md",
      "value": "1rem",
      "px": 16
    },
    {
      "token": "lg",
      "value": "1.5rem",
      "px": 24
    },
    {
      "token": "xl",
      "value": "2rem",
      "px": 32
    },
    {
      "token": "2xl",
      "value": "3rem",
      "px": 48
    },
    {
      "token": "3xl",
      "value": "4rem",
      "px": 64
    }
  ],
  "radius": [
    {
      "token": "sm",
      "value": "0.25rem",
      "px": 4
    },
    {
      "token": "md",
      "value": "0.5rem",
      "px": 8
    },
    {
      "token": "lg",
      "value": "0.75rem",
      "px": 12
    },
    {
      "token": "xl",
      "value": "1rem",
      "px": 16
    },
    {
      "token": "full",
      "value": "9999px",
      "px": 9999
    }
  ],
  "shadows": [
    {
      "token": "sm",
      "value": "0 1px 2px 0 rgb(0 0 0 / 0.05)"
    },
    {
      "token": "md",
      "value": "0 4px 6px -1px rgb(0 0 0 / 0.1)"
    },
    {
      "token": "lg",
      "value": "0 10px 15px -3px rgb(0 0 0 / 0.1)"
    },
    {
      "token": "xl",
      "value": "0 20px 25px -5px rgb(0 0 0 / 0.1)"
    }
  ],
  "breakpoints": [
    {
      "token": "sm",
      "value": "640px",
      "usage": "Large phones"
    },
    {
      "token": "md",
      "value": "768px",
      "usage": "Tablets"
    },
    {
      "token": "lg",
      "value": "1024px",
      "usage": "Laptops"
    },
    {
      "token": "xl",
      "value": "1280px",
      "usage": "Desktops"
    },
    {
      "token": "2xl",
      "value": "1536px",
      "usage": "Wide screens"
    }
  ],
  "layout": {
    "containerMax": "72rem",
    "contentMax": "42rem",
    "sectionPadding": "var(--spacing-xl)",
    "navHeight": "3.5rem"
  },
  "motion": {
    "duration": {
      "fast": "150ms",
      "normal": "250ms",
      "slow": "400ms"
    },
    "easing": {
      "default": "cubic-bezier(0.4, 0, 0.2, 1)",
      "in": "cubic-bezier(0.4, 0, 1, 1)",
      "out": "cubic-bezier(0, 0, 0.2, 1)"
    }
  }
}
```