# AllGifted — Brand & Design System (Kids 7–14)

A reusable brand reference for every AllGifted product targeting children aged roughly 7–14. Starts from the AllGifted Math (AGS Math) identity but is written so the next product (AGS English, AGS Science, etc.) can adopt it directly.

**Generated 2026-05-24.** Source of truth for color tokens, typography, voice, iconography, and UI states.

---

## 1. Brand position

**Who it's for:** kids 7–14, with parents and teachers as secondary audiences.
**Tone:** warm, encouraging, slightly playful, never patronizing. Kids in this band can spot condescension instantly — talk to them like capable young people, not toddlers.
**Personality:** an enthusiastic older sibling who's good at the subject and roots for you.
**Voice rules:**
- Short sentences. Active voice.
- Celebrate effort, not just outcomes ("Nice try — let's see what tripped you up" beats "Wrong!")
- Math/learning is hard; never pretend otherwise.
- No emojis as a substitute for clarity. Use them sparingly as accents in success states.
- No exclamation marks in error states — kids already feel bad enough.

---

## 2. Color palette

The brand has one anchor color (crimson) and three accent families. Every UI surface should resolve to a token below — never a one-off hex.

### Primary

| Token | Hex | Role |
|---|---|---|
| `ag-crimson` | `#960000` | Primary brand. Buttons, headers, active nav, accent bars. |
| `ag-crimson-dark` | `#7A0000` | Hover/pressed states for crimson buttons. |

### Accents

| Token | Hex | Role |
|---|---|---|
| `ag-gold` | `#BF9237` | Secondary actions, warning state, achievement highlights. |
| `ag-rose` | `#D0ACAC` | Decorative blush — backgrounds for "soft" surfaces, illustrations. |
| `ag-lime` | `#88C808` | Success state — "correct answer", "achievement unlocked". |
| `ag-lime-dark` | `#72A806` | Hover/pressed for lime. |
| `ag-blue` | `#4A6488` | Informational state — info banners, neutral metric chips. |
| `ag-blue-dark` | `#3A5070` | Hover/pressed for blue. |

### Neutrals

| Token | Hex | Role |
|---|---|---|
| `ag-dark` | `#1A0505` | Body text. Headings. |
| `ag-muted` | `#6A5050` | Secondary text, captions, helper text. |
| `ag-cream` | `#FDFAF8` | Page background, soft surface. |
| `ag-light` | `#F7F0EE` | Card hover, subtle dividers. |
| `ag-border` | `#E8DADA` | Default border color. |

### Error / destructive

| Token | Hex | Role |
|---|---|---|
| `ag-error` | `#D80000` | Form validation errors, destructive confirmations. Use sparingly — it's adjacent to crimson on purpose, so it should appear only when something genuinely needs attention. |

### Semantic mapping

Map every UI signal to a single token. This table is the contract — don't introduce a new color without adding it here.

| Semantic role | Token |
|---|---|
| Primary action button | `ag-crimson` |
| Primary action hover | `ag-crimson-dark` |
| Success (correct, achievement) | `ag-lime` |
| Warning (caution, partial) | `ag-gold` |
| Error (validation, blocked) | `ag-error` |
| Info (status, neutral) | `ag-blue` |
| Body text | `ag-dark` |
| Caption / helper | `ag-muted` |
| Page background | `ag-cream` |
| Card background | white |
| Card hover | `ag-light` |
| Divider / border | `ag-border` |

### Contrast checks (WCAG AA)

All combinations below pass WCAG AA for normal text (≥4.5:1) unless noted.

| Foreground | Background | Pass |
|---|---|---|
| `ag-dark` on `ag-cream` | ✅ |
| `ag-muted` on `ag-cream` | ✅ (large text only — use ag-dark for small body) |
| `ag-crimson` on `ag-cream` | ✅ |
| white on `ag-crimson` | ✅ |
| white on `ag-lime` | ⚠️ Use only for large/bold text. Body text on lime should be `ag-dark`. |
| `ag-crimson` on white | ✅ |
| `ag-blue` on `ag-cream` | ✅ |

---

## 3. Typography

### Faces

- **Primary**: Raleway. Used for everything — headings, body, UI labels. Raleway has a warm, slightly geometric quality that reads well for kids without feeling childish.
- **Monospace**: system default monospace (used for numerals when displayed in fixed-width contexts, e.g. timers, scores).

> Fallback stack: `Raleway, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif`.

### Scale

| Token | Size | Line height | Weight | Use |
|---|---|---|---|---|
| `display` | 40px | 1.1 | 800 | Splash, marketing |
| `h1` | 32px | 1.2 | 700 | Page titles |
| `h2` | 24px | 1.25 | 700 | Section titles |
| `h3` | 20px | 1.3 | 600 | Card titles |
| `h4` | 18px | 1.4 | 600 | Sub-cards |
| `h5` | 16px | 1.5 | 600 | Small section heads |
| `body` | 16px | 1.5 | 400 | Default reading text |
| `body-sm` | 14px | 1.5 | 400 | Captions, helper text |
| `tiny` | 12px | 1.4 | 500 | Badges, micro-labels |

### Weight rules

- **400 (Regular)** — body
- **500 (Medium)** — UI labels
- **600 (Semibold)** — emphasis, headings ≤h4
- **700 (Bold)** — h1–h3, primary button text
- **800 (Extra Bold)** — display

Avoid going heavier than 800 — it reads as shouting.

### Italic + underline

- Italic: reserved for quotes and definitions. Don't italicize for emphasis (use bold instead — italic is harder to read on phones).
- Underline: hyperlinks only. Don't underline for emphasis.

---

## 4. Spacing & layout

### Spacing scale

Powers of 4, capped at 64.

| Token | Pixels | Use |
|---|---|---|
| `space-1` | 4 | Tight stacks (badge padding) |
| `space-2` | 8 | Form field padding, icon gaps |
| `space-3` | 12 | Small gaps between related elements |
| `space-4` | 16 | **Default gap.** Card padding, list spacing. |
| `space-6` | 24 | Section padding |
| `space-8` | 32 | Major section separator |
| `space-12` | 48 | Page-level spacing |
| `space-16` | 64 | Hero spacing, top/bottom of pages |

### Corner radii

| Token | Pixels | Use |
|---|---|---|
| `radius-sm` | 4 | Inputs, badges |
| `radius-md` | 8 | Buttons, small cards |
| `radius-lg` | 12 | Large cards, modals |
| `radius-xl` | 16 | Hero panels, splash imagery |
| `radius-full` | 9999 | Pills, circular icons |

> Default to `radius-md` if unsure. Kids respond well to rounded shapes — never use sharp 0-radius corners except for full-bleed page edges.

### Layout

- **Mobile-first.** Design for 360px width as the floor; scale up.
- **Max content width**: 1400px on desktop. Beyond that, center.
- **Card pattern**: white background, `radius-md`, `ag-border` 1px, subtle shadow `0 1px 3px rgba(0,0,0,0.04)`. On hover (clickable cards only): lift by 1–2px and increase shadow to `0 4px 12px rgba(0,0,0,0.08)`.

---

## 5. UI components

### Buttons

| Variant | Background | Text | When |
|---|---|---|---|
| Primary | `ag-crimson` | white | One per screen — the main action |
| Secondary | `ag-cream` border `ag-crimson` | `ag-crimson` | Alternative actions |
| Tertiary | transparent | `ag-crimson` underline on hover | Less-important navigation |
| Success | `ag-lime` | white | "Submit answer" in correct contexts |
| Destructive | `ag-error` | white | Delete account, cancel subscription |
| Disabled | `ag-border` | `ag-muted` | Don't grey-out — soften both colors |

**Sizes**: `sm` (32px), `md` (40px, default), `lg` (48px for primary tap targets on mobile).

**Padding**: horizontal padding = `space-4` (16px) on `md`, `space-6` (24px) on `lg`.

**Touch target**: 44×44px minimum on mobile (Apple HIG / Material). Buttons can render smaller visually but the tap area should extend to 44.

### Inputs

- Border `ag-border`, focus `ag-crimson` with 3px crimson-tinted halo.
- Label above the input, never inside (placeholders disappear on type).
- Error: border `ag-error`, error text below in `ag-error` weight 500.
- Helper text below in `ag-muted` body-sm.

### Badges / pills

- Pill shape (`radius-full`), `tiny` text, `space-2` horizontal padding.
- Background: 10–15% opacity of the semantic color; text: full opacity of same semantic color.
- e.g. success badge: bg `rgba(136,200,8,0.15)`, text `#5D8B06` (slightly darker than `ag-lime` for contrast).

### Modals & sheets

- Mobile: full-width bottom sheet sliding up; `radius-xl` top corners; backdrop `rgba(26,5,5,0.4)`.
- Desktop: centered modal, `radius-lg`, max-width 480px for forms, 720px for content.

### Toasts

- Top-right desktop, bottom-center mobile.
- Auto-dismiss: 4 seconds for success/info, 6 seconds for warning/error.
- Color: matches semantic token; white text.

---

## 6. Iconography

- **System**: Heroicons (outline for nav and tertiary actions; solid for primary actions and statuses).
- **Stroke weight**: 1.5px for outline icons (Heroicons default).
- **Size**: 16, 20, 24, 32. Default 20 for inline UI; 24 for nav; 32 for stat-card visual anchors.
- **Color**: inherits text color. Don't hardcode icon colors except for status icons (success → `ag-lime`, error → `ag-error`).

### Custom illustrations (when commissioned)

- Style: friendly, rounded, slight asymmetry. Avoid hyper-realism.
- Palette: limit to brand tokens. No off-palette colors.
- Subjects: diverse, age-appropriate, gender-balanced. Show kids being curious, not just smiling.

---

## 7. Logo usage

**Primary mark**: AllGifted infinity-style logo (in `public/images/brand/logo.png`).

**Variants:**
- `logo.png` — full color, light backgrounds
- `logo-dark.png` — for dark backgrounds
- `favicon.ico` — multi-resolution, 16/32/48/64/256 sizes (in `public/favicon.ico`)
- `favicon.svg` — scalable single-color version
- `favicon.png` — 180×180 (used as apple-touch-icon)

**Rules:**
- Minimum size: 24px tall for the favicon; 64px for the full wordmark.
- Clear space: leave at least 1× logo height of padding on all sides.
- Don't recolor. Don't squish. Don't add drop shadows.
- Don't place on busy photos — always use a solid or subtle gradient background.

---

## 8. Motion

- **Default duration**: 150ms for hover/focus transitions, 250ms for component reveals.
- **Easing**: `ease-out` for entering motion (cards fade in, sheets slide up), `ease-in` for leaving.
- **Reduce motion**: respect `prefers-reduced-motion: reduce` — disable non-essential animations.

**Specific moments worth animating:**

- Correct answer: lime glow pulse on the option, then fade. ~400ms total.
- Wrong answer: shake (3 cycles, 200ms) + transition border to `ag-error`. No glow.
- Achievement unlock: small confetti burst + lime success toast. Total ~1.2s.
- Page transitions: 200ms cross-fade. No slide unless thematically motivated.

---

## 9. Voice & copy

### Microcopy patterns

| Context | Do | Don't |
|---|---|---|
| Submit button | "Check answer" / "Submit" | "Go!" / "FIRE!" |
| Correct response | "Correct! Here's why:" | "WINNER!! 🎉🎉" |
| Wrong response | "Not quite. Let's look at this together:" | "WRONG! ❌" |
| Empty state | "Nothing here yet — once you take your first test, you'll see your progress." | "No data." |
| Error | "Something went wrong loading this. Refreshing usually fixes it." | "ERROR 500." |
| Lockout / cooldown | "You've used all your lives — come back in 35 minutes, or top up." | "OUT OF LIVES" |

### Naming

- Features get short, descriptive names. "Kiasu Path" is fine — it's culturally grounded in our market. Avoid invented words that need a glossary.
- Levels: numbered, not gamified ("Level 3", not "Apprentice Wizard").
- Streaks: count visibly but don't celebrate every increment — only at milestones (5, 10, 30, etc.).

---

## 10. Accessibility

- Color contrast: WCAG AA minimum (4.5:1 body, 3:1 large).
- Touch targets: 44×44px minimum on mobile.
- Focus indicators: always visible (3px halo in `ag-crimson`).
- Form labels: always present, never relying on placeholder alone.
- Alt text on all illustrative images.
- Live regions for important state changes (e.g. score updates).
- No content depends solely on color — pair color with icon or text.
- Respect `prefers-reduced-motion` and `prefers-color-scheme`.

---

## 11. Implementation reference

### CSS variables (drop into any product's stylesheet)

```css
:root {
  /* Brand */
  --ag-crimson:       #960000;
  --ag-crimson-dark:  #7A0000;
  --ag-gold:          #BF9237;
  --ag-rose:          #D0ACAC;
  --ag-lime:          #88C808;
  --ag-lime-dark:     #72A806;
  --ag-blue:          #4A6488;
  --ag-blue-dark:     #3A5070;

  /* Neutrals */
  --ag-dark:          #1A0505;
  --ag-muted:         #6A5050;
  --ag-cream:         #FDFAF8;
  --ag-light:         #F7F0EE;
  --ag-border:        #E8DADA;

  /* Semantic */
  --ag-error:         #D80000;

  /* Typography */
  --ag-font-primary:  "Raleway", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;

  /* Radii */
  --ag-radius-sm:     4px;
  --ag-radius-md:     8px;
  --ag-radius-lg:     12px;
  --ag-radius-xl:     16px;

  /* Spacing */
  --ag-space-1:   4px;
  --ag-space-2:   8px;
  --ag-space-3:  12px;
  --ag-space-4:  16px;
  --ag-space-6:  24px;
  --ag-space-8:  32px;
  --ag-space-12: 48px;
  --ag-space-16: 64px;
}
```

### Tailwind config (next product can copy verbatim)

```ts
theme: {
  extend: {
    colors: {
      crimson: { DEFAULT: "#960000", dark: "#7A0000" },
      gold: "#BF9237",
      rose: "#D0ACAC",
      lime: { DEFAULT: "#88C808", dark: "#72A806" },
      blue: { DEFAULT: "#4A6488", dark: "#3A5070" },
      dark: "#1A0505",
      muted: "#6A5050",
      cream: "#FDFAF8",
      light: "#F7F0EE",
      border: "#E8DADA",
      error: "#D80000",
    },
    fontFamily: {
      sans: ["Raleway", "ui-sans-serif", "system-ui"],
    },
    borderRadius: {
      sm: "4px",
      md: "8px",
      lg: "12px",
      xl: "16px",
    },
  },
}
```

### Flutter / Material 3 theme

```dart
final agTheme = ThemeData(
  colorScheme: ColorScheme(
    brightness: Brightness.light,
    primary: const Color(0xFF960000),
    onPrimary: Colors.white,
    secondary: const Color(0xFFBF9237),
    onSecondary: const Color(0xFF1A0505),
    error: const Color(0xFFD80000),
    onError: Colors.white,
    surface: Colors.white,
    onSurface: const Color(0xFF1A0505),
    background: const Color(0xFFFDFAF8),
    onBackground: const Color(0xFF1A0505),
  ),
  fontFamily: 'Raleway',
  // ... textTheme, button themes, etc.
);
```

### Existing applications

- **AllGifted Math Laravel API** (`mathapi11v2/CLAUDE.md`) — drives the configs row that powers the legacy admin's CSS variables.
- **AllGifted Math admin** (`mathapi11v2/public/css/admin-theme.css`) — Filament theme overlay using these tokens.
- **AllGifted Web** (`allgifted-web/tailwind.config.ts`) — the canonical Tailwind config to mirror.
- **AllGifted Math Flutter** (`flutter_demo/`) — TODO: align student-facing app theme to this spec.

---

## 12. Don't list

Things that have come up before and need explicit "no":

- **Don't use the crimson on its own as a background for kids' interactive panels.** It's too intense. Use cream/white with crimson accents.
- **Don't introduce Comic Sans or any "kid font" alternative.** Raleway handles the age band well — Comic Sans codes as condescending past age 9.
- **Don't add stars / sparkles / confetti to every correct answer.** Reserve celebration for genuine milestones (passing a skill, completing a diagnostic). Constant celebration cheapens it.
- **Don't use red and green as the *only* signal for correct/wrong** — pair with icon (✓ / ✗) and text. Color-blind kids exist.
- **Don't ship a custom illustration that breaks the palette.** Brief illustrators with this doc.
- **Don't write copy with double exclamation marks.** One is enthusiasm; two is desperation.
- **Don't use scary error language.** "Connection lost" not "FAILURE". "Couldn't load" not "ERROR".

---

## 13. Owners & change process

This document is the single source of truth for AllGifted kid-product branding. Changes require:

1. A proposed PR with the change + rationale + screenshots if visual
2. Review by the brand owner (designer + product) + engineering lead
3. Update the corresponding implementation files (CSS variables, Tailwind config, Flutter theme) in the same PR

Don't introduce off-palette colors, off-system spacing, or off-stack fonts in product code without first updating this doc.

When in doubt: ask. It's much cheaper than shipping inconsistency and having to claw it back later.