Repository Guidelines

Project Structure

Design/ is the current source of truth for the product experience.
Design/index.html is the overview/launcher entry point.
Design/control.html is the participant control surface.
Design/screen.html is the full-screen word-cloud display.
Design/DESIGN-MANIFEST.json maps screens, assets, required states, and responsive checks.
Design/DESIGN-HANDOFF.md defines the implementation contract and must be read before adding production code.
Design/drawing-*.png and future design assets live beside the HTML screens.

The app is a React + TypeScript + Vite project rooted at the repository root; Design/ remains the confirmed visual reference.

Development Commands

Use npm for the React app:

npm install
npm run dev

Run verification before claiming completion:

npm test
npm run typecheck
npm run lint
npm run build
npm run test:server

For production, build and run with docker compose up -d --build; the port is configured with APP_PORT. Nginx serves the SPA and forwards /ws to the realtime container.

For direct design-file inspection without the app:

python3 -m http.server 8000 --directory Design

Then open http://localhost:8000/index.html, /control.html, or /screen.html.

Coding Style

Keep pages, reusable components, data, hooks, and realtime adapters separated.
Use two-space indentation for HTML, CSS, TypeScript, and JavaScript.
Use CSS Modules for page/component styles and keep visual values in src/styles/global.css.
Preserve existing CSS custom properties for color, typography, spacing, radius, shadow, and motion.
Use descriptive BEM-like class names such as art-title, cloud, dock, and screen-note; do not introduce anonymous utility classes for domain-specific layout.
Keep user-facing copy in the existing Chinese-first style and preserve exact labels unless requirements say otherwise.
Prefer semantic elements and visible focus states for any interactive implementation.

Testing Guidelines

Use Vitest and React Testing Library. Keep core search, duplicate-target, queue, and adapter behavior covered by tests. For visual or interaction changes, also verify all three routes in a browser, check mobile and desktop viewports, and ensure no horizontal overflow or hidden controls. The manifest's responsive viewport list is the minimum visual checklist.

Commit & Pull Request Guidelines

Use short, imperative commit subjects, for example Update screen word positions or Add control success state.

Pull requests should include the change reason, affected screen files, browser and viewport checks performed, and screenshots or short recordings for visual changes. Link related implementation or design tickets when available.

Agent Guidance

Before implementing production code, read DESIGN-HANDOFF.md and DESIGN-MANIFEST.json, preserve the documented visual system, and keep launcher, control, and display surfaces separate.

3.0 KiB Raw Permalink Blame History