# AI New Project Standard

This file is both a checklist and a reusable brief for AI-created EduTogether web projects.

## Mandatory Workflow

1. Read `design-system/README.md`, `design-system/ANALYTICS.md`, and `design-system/tokens/tokens.json`.
2. Inspect one or two nearby projects for functional conventions, but do not copy their one-off visual styling.
3. Write or update `project.json` before implementation.
4. Choose exactly one theme: `math`, `language`, `science`, `creative`, `wellbeing`, or `game`.
5. Build the actual learning experience first. Do not wrap it in a marketing landing page.
6. Import `design-system/css/edu-system-v2.css` and use semantic `--edu-*` tokens.
7. Include the correct relative path to `projects/common/project-nav.js` at the end of `<body>`.
8. Add canonical analytics events for the core learning flow.
9. Verify keyboard use, focus, reduced motion, desktop, and a 360px-wide viewport.
10. Run `design-system/scripts/audit-project.sh <project-directory>` and resolve every error.

## Fixed Design Decisions

- Audience: primary-school children using a desktop or laptop, with parents as a secondary audience.
- Tone: warm, clear, capable, and age-respectful; never infantile or corporate.
- Desktop-first target: 1280 x 800 and 1440 x 900.
- Responsive floor: 360px wide. Touch targets remain at least 40 x 40px.
- Content container: 1120px default, 1280px for data-heavy tools.
- Header height: 64px.
- Grid: 12 columns on desktop, 8 on tablet, 4 on mobile.
- Base spacing: 4px with 8/12/16/24/32/48/64px steps.
- Radius: 4/6/8px. Do not use large rounded cards. Pills are semantic only.
- Typography: system-first Chinese stack; 15px body; no viewport-scaled fonts; letter spacing `0`.
- Iconography: consistent outline icons. No emoji for buttons, settings, navigation, refresh, audio, or close.
- Palette: neutral surfaces plus one subject theme. Brand gradients are limited to the logo or rare celebration moments.
- Effects: subtle borders, almost no ambient shadows, no glassmorphism, bokeh, decorative orbs, or nested cards.

## Required States

Every interactive experience implements the states that apply:

- loading or initial preparation;
- empty/no-content;
- normal and hover;
- keyboard focus-visible;
- selected/current;
- correct/success and incorrect/error;
- disabled;
- completion/result;
- recoverable failure with a next action.

Do not let state changes resize the main layout. Reserve space for validation and feedback text.

## Learning Experience Rules

- Show one primary learning objective per screen.
- Keep instructions close to the activity and under two short sentences.
- Use progressive disclosure for explanations and advanced options.
- Confirm correct answers quickly; explain wrong answers without shame language.
- Do not use color alone to distinguish right/wrong or categories.
- Keep scoring secondary to learning progress.
- Provide restart/reset only when it is genuinely useful; use a familiar icon plus accessible label.
- Preserve user work locally when reasonable.

## Reusable AI Brief

Use the following text when asking an AI to create a new project in this repository:

```text
Create a production-ready EduTogether learning web project in this repository.

Before writing code, read and follow:
- /AGENTS.md
- /design-system/README.md
- /design-system/AI_PROJECT_STANDARD.md
- /design-system/ANALYTICS.md
- /design-system/tokens/tokens.json

Project brief:
- Title: [plain Chinese project title]
- Learning objective: [one measurable objective]
- Audience/grade: [grade and approximate age]
- Theme: [math | language | science | creative | wellbeing | game]
- Core workflow: [3-6 concrete user steps]
- Required content/data: [source content]
- Completion condition: [what success means]

Implementation requirements:
- Build the usable learning experience as the first screen, not a landing page.
- Import /design-system/css/edu-system-v2.css using the correct relative path.
- Use the shared EduTogether shell, semantic tokens, component rules, and required states.
- Include /projects/common/project-nav.js using the correct relative path.
- Add canonical analytics events for start, meaningful progress, completion, and failure.
- Create project.json from /design-system/starter/project.json.
- Do not use Tailwind CDN, decorative gradients/orbs, nested cards, emoji controls, or arbitrary colors.
- Verify 1440x900 and 360x800, keyboard focus, reduced motion, console errors, and the core workflow.
- Run /design-system/scripts/audit-project.sh against the project before handoff.
```

## Handoff Checklist

- The first screen exposes the real activity.
- Project title and relationship to EduTogether are visible but not duplicated.
- Exactly one theme is active.
- No hard-coded visual colors exist where a semantic token applies.
- One primary action is visually dominant in each region.
- Controls have accessible names and stable dimensions.
- Empty, error, loading, and completion states are intentional.
- `project-nav.js` is present and analytics properties contain no new personal data.
- No console errors occur in the verified workflow.
- `project.json` exists and the audit script passes.