67 lines
3.0 KiB
Markdown
67 lines
3.0 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
Run verification before claiming completion:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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.
|