# ThinkFizz UI Guidelines Skill

## Purpose
Use this skill when designing, building, or reviewing any ThinkFizz UI — web app, mobile, marketing site, or component library. Ensures visual consistency with the ThinkFizz design system.

## Design Philosophy
**Precision and delight.** Every interaction should feel like a spark — fast, satisfying, and a little surprising. The UI should feel like the brand voice: energetic but never chaotic, rigorous but never cold.

## Color System

| Token   | Hex       | Primary Usage |
|---------|-----------|---------------|
| Coral   | `#F2545B` | Primary CTA, active states, energy moments |
| Green   | `#2BB673` | Success, science category, correct answers |
| Violet  | `#7B5BE0` | Brand accent, "Fizz" identity, math/logic |
| Amber   | `#F7A325` | Geography, history, warmth, warnings |
| Blue    | `#2E8BF0` | Links, science alt, info states, trust |
| Spark   | `#FFB23E` | Delight moments, notifications, streaks |
| Ink     | `#1F2430` | Primary text, dark mode background |
| Cloud   | `#F5F6F8` | Light backgrounds, cards, input fields |

### Color Rules
- Never use more than 3 brand colors in a single component
- Coral is the primary action color — reserve it for the most important CTA per screen
- Violet is "ThinkFizz" — use it for the brand wordmark and signature moments
- Background minimum contrast ratio: 4.5:1 for body text, 3:1 for large text (WCAG AA)

## Typography

### Fredoka 600 — Headings & Display
```css
font-family: 'Fredoka', sans-serif;
font-weight: 600;
```
Use for: page titles, card headers, quiz questions, logo wordmark, marketing headlines.

### Nunito Sans — Body & UI
```css
font-family: 'Nunito Sans', sans-serif;
font-weight: 400 | 600 | 700;
```
Use for: body copy, UI labels, captions, answer choices, navigation, buttons.

### Type Scale (8px base grid)
| Role | Size | Weight | Family |
|------|------|--------|--------|
| Display | 48–64px | 600 | Fredoka |
| H1 | 32px | 600 | Fredoka |
| H2 | 24px | 600 | Fredoka |
| H3 | 20px | 600 | Fredoka |
| Body | 16px | 400 | Nunito Sans |
| Caption | 14px | 400 | Nunito Sans |
| Label | 12px | 600 | Nunito Sans |

## Spacing
- **Base unit:** 8px
- **Component padding:** 16px (sm), 24px (md), 32px (lg)
- **Section spacing:** 48px, 64px, 96px
- **Logo clear space:** height of one bubble on all sides

## Shape & Radius
| Element | Radius |
|---------|--------|
| Cards | 12px |
| Buttons | 8px |
| Input fields | 8px |
| Tags / chips | 100px (pill) |
| Avatar | 50% |
| Modal | 16px |

## Shadows
```css
/* Card — default */
box-shadow: 0 2px 12px rgba(31, 36, 48, 0.08);

/* Card — hover */
box-shadow: 0 4px 24px rgba(31, 36, 48, 0.12);

/* Modal / elevated */
box-shadow: 0 8px 40px rgba(31, 36, 48, 0.16);
```

## Motion
- **Duration:** 200ms (micro), 300ms (transitions), 400ms (page/modal)
- **Easing:** spring — `cubic-bezier(0.34, 1.56, 0.64, 1)` for delightful pops
- **Standard:** `cubic-bezier(0.4, 0, 0.2, 1)` for standard transitions
- **Rule:** Motion should feel playful but never slow the user down

## Component Patterns

### Buttons
- **Primary:** Coral fill, white text, 8px radius, 600 weight Nunito Sans
- **Secondary:** Ink border, ink text, transparent fill
- **Ghost:** No border, brand color text, hover shows subtle background
- **Min touch target:** 44×44px

### Cards
- Cloud background, 12px radius, subtle shadow
- Hover: lift shadow + 2px translateY
- Category cards: left border accent in category color

### Quiz / Answer UI
- Unselected: Cloud bg, ink text
- Correct: Green bg (#2BB673 at 15% opacity), green border, green check
- Incorrect: Coral bg (#F2545B at 15% opacity), coral border, coral X
- Selected: Violet border, violet text

### Streaks & Rewards
- Use Spark (#FFB23E) and animated confetti particles
- Fredoka for numbers, Nunito Sans for labels
- Spring animation on count increment

## Dark Mode
- Background: `#1F2430` (Ink)
- Surface: `#2A3042`
- Text: `#F5F6F8` (Cloud)
- Brand colors remain the same — adjust opacity for disabled states

## Logo Usage
- **Color lockup:** primary, on white/light backgrounds
- **White lockup:** on dark/Ink backgrounds
- **Black lockup:** on light single-colour non-white backgrounds
- **Symbol only:** when width < 120px
- **Never:** stretch, rotate, recolor, apply drop shadows to the logo

## Google Fonts Import
```html
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Fredoka:wght@600&family=Nunito+Sans:wght@400;600;700&display=swap" rel="stylesheet">
```

## CSS Variables Starter
```css
:root {
  --tf-coral:  #F2545B;
  --tf-green:  #2BB673;
  --tf-violet: #7B5BE0;
  --tf-amber:  #F7A325;
  --tf-blue:   #2E8BF0;
  --tf-spark:  #FFB23E;
  --tf-ink:    #1F2430;
  --tf-cloud:  #F5F6F8;

  --tf-font-heading: 'Fredoka', sans-serif;
  --tf-font-body:    'Nunito Sans', sans-serif;

  --tf-radius-card:   12px;
  --tf-radius-btn:    8px;
  --tf-radius-pill:   100px;

  --tf-shadow:        0 2px 12px rgba(31,36,48,0.08);
  --tf-shadow-hover:  0 4px 24px rgba(31,36,48,0.12);
}
```