# EduTogether Design System v2

EduTogether v2 is the shared visual and interaction standard for the family of learning tools linked from `projects/edutogatherhome/`.

The system is deliberately **80% shared structure + 20% subject character**:

- Shared: product shell, typography, spacing, controls, states, accessibility, analytics, and navigation.
- Variable: one subject accent, learning illustration, game world, and content-specific interaction.

This keeps every project recognizable as part of EduTogether without making a reading tool, map, piano, and game look identical.

## Canonical Files

| File | Purpose |
| --- | --- |
| `index.html` | Visual reference and live component specimen |
| `css/edu-system-v2.css` | New-project tokens, base styles, and component primitives |
| `tokens/tokens.json` | Machine-readable design tokens for AI and other frameworks |
| `AI_PROJECT_STANDARD.md` | Requirements and reusable AI brief for new projects |
| `ANALYTICS.md` | Shared bootstrap, event names, and privacy rules |
| `starter/index.html` | Minimal static project starter |
| `starter/preview.html` | Login-free interactive preview of the starter |
| `starter/project.json` | Required project metadata example |
| `project.schema.json` | JSON Schema for `project.json` |
| `scripts/audit-project.sh` | Fast structural compliance check |

`css/design-system.css` and the older English guide pages are legacy v1 assets. They remain available so existing pages do not break, but new projects must use `css/edu-system-v2.css`.

## Brand Direction

**Positioning:** a calm, capable learning companion for children and families.

**Personality:** warm, clear, curious, dependable. The interface should respect children without looking babyish and reassure parents without looking corporate.

**Signature visual idea:** connection rails. A thin colored line, progress track, or aligned edge visually connects titles, steps, and outcomes. The existing handshake mark remains the master-brand signal.

### Brand Architecture

- Master brand: `EduTogether`
- Project title: plain descriptive Chinese name, for example `九九除法表`
- Relationship line: `EduTogether 学习工具`
- Do not create a new logo for every project.
- Project mascots and illustrations are optional content assets, not navigation icons or logos.

### Logo

- Use the handshake mark without distortion, rotation, recoloring, or added effects.
- Minimum digital height: 24px for the symbol, 32px when paired with the wordmark.
- Clear space: at least half the mark height on every side.
- Use the full mark in the global shell. Do not repeat it inside cards or learning activities.

The existing files under `projects/VI/` are exploration assets. Several contain generator watermarks and should not ship. They can guide future illustration work, but production art needs clean source files and consistent export rules.

## Color Model

The master brand uses berry and indigo. Most product surfaces use neutral ink, white, and cool gray; large pink-purple gradients are not a page background.

| Role | Token | Value | Use |
| --- | --- | --- | --- |
| Brand | `--edu-brand` | `#B42362` | Master-brand actions and relationship cues |
| Brand secondary | `--edu-brand-secondary` | `#4338CA` | Small brand details; never a competing CTA |
| Canvas | `--edu-canvas` | `#F5F7FA` | App background |
| Surface | `--edu-surface` | `#FFFFFF` | Working surfaces |
| Ink | `--edu-ink` | `#182230` | Primary text |
| Muted | `--edu-ink-muted` | `#5D6675` | Supporting text |
| Border | `--edu-border` | `#D8DEE9` | Dividers and component boundaries |

Each project chooses exactly one theme: `math`, `language`, `science`, `creative`, `wellbeing`, or `game`. The theme changes `--edu-accent`, `--edu-accent-strong`, and `--edu-accent-soft`; it does not replace the neutral foundation.

## Typography

Use a system-first stack so Chinese text renders quickly and consistently:

```css
font-family: Inter, ui-sans-serif, -apple-system, BlinkMacSystemFont,
  "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif;
```

- Page title: 32/40, weight 750 on desktop; 26/34 on small screens.
- Section title: 22/30, weight 700.
- Component title: 16/24, weight 650.
- Body: 15/24, weight 400.
- UI labels: 14/20, weight 600.
- Captions: 12/18, weight 500.
- Numbers may use tabular figures. Do not use viewport-width font scaling.
- Letter spacing is `0`; Chinese interfaces do not use uppercase styling as decoration.

## Layout And Density

- Desktop content width: 1120-1280px, depending on the tool.
- Global header: 64px high.
- Optional navigation rail: 232px, only when a project has at least five peer destinations.
- Base spacing unit: 4px. Common gaps: 8, 12, 16, 24, 32, 48, 64.
- Controls: 40px default; 44px for primary child-facing actions.
- Radius: 4px small, 6px controls, 8px panels/cards. Full radius only for status, avatar, progress, toggle.
- Use borders and whitespace before shadows. Shadows are for menus, dialogs, and lifted interactive states.

## Product Shell

Every standard project has:

1. A 64px header with the EduTogether mark, project title, current learner/context, and essential actions.
2. One clear primary task in the first viewport.
3. A restrained content area using sections, rails, lists, tables, or one purposeful panel.
4. Consistent success, error, empty, loading, and disabled states.
5. The shared home/auth/analytics bootstrap at the end of `<body>`.

Games may use a full-bleed play field and custom art direction. Their menus, settings, dialogs, results, focus states, and shared navigation still use the system.

## Component Rules

- Buttons: one primary action per region; use icon-only buttons for familiar utilities and provide tooltips/labels.
- Cards: only for repeated selectable items or genuinely framed tools. Never nest cards.
- Forms: labels stay visible; placeholders are examples, not labels. Show help/error text in a stable reserved area.
- Tabs: use for peer views, not for step-by-step tasks.
- Tables: default for comparable data; do not convert desktop tables into decorative card grids.
- Feedback: explain what happened and the next action. Color never carries meaning alone.
- Icons: use one 1.75-2px outline family such as Lucide. Emoji are content, not controls.
- Motion: 120-220ms for interface feedback; transform/opacity only where possible. Respect `prefers-reduced-motion`.

## Adoption Strategy

1. All new projects start on v2 immediately.
2. Existing projects keep their current visual world until they are touched for substantive work.
3. When an existing project is migrated, update its shell and system states first; do not erase its learning/game identity.
4. Migrate the home portal and analytics catalog to a shared project registry as a separate, tested project. Today the portal list and analytics name map are duplicated.

## Quick Start

From a project at `projects/grade2/project-name/`:

```html
<html lang="zh-CN" data-edu-theme="math">
<head>
  <link rel="stylesheet" href="../../../design-system/css/edu-system-v2.css">
</head>
<body class="edu-app">
  <!-- project UI -->
  <script src="../../common/project-nav.js"></script>
</body>
```

Copy `starter/project.json`, adjust the metadata, then run:

```bash
design-system/scripts/audit-project.sh projects/grade2/project-name
```

Open `design-system/index.html` for the live visual reference.