AGENTS.md — frontend

Lit Element + MobX single-page application built with Webpack. See also frontend/README.md for additional context on routing, Firebase setup, and experiment configuration.

See also: root AGENTS.md for monorepo-wide conventions.

Build & test

From the repository root:

npm run start -w frontend     # Build + serve (dev, localhost:4201)
npm run build -w frontend     # Dev build only
npm run build:prod -w frontend  # Production build
npm test -w frontend          # Run Jest tests

For local dev, copy config files first (or use run_locally.sh which handles this automatically):

cp frontend/firebase_config.example.ts frontend/firebase_config.ts
cp frontend/index.example.html frontend/index.html

Component architecture

src/components/ — Feature components

Organized into 17 subdirectories by feature area:

src/pair-components/ — Reusable primitives

Standalone UI primitives: button, icon, icon_button, textarea, textarea_template, tooltip, menu, info_popup. Also contains types.ts (shared primitive types) and utils.ts (helper functions). These are general-purpose and not tied to project state.

shared.css in this directory provides base styles used across primitives.

[!NOTE] Primitives use a mix of .css and .scss for styles. button, icon, icon_button, textarea, textarea_template, and tooltip use plain .css; menu and info_popup use .scss. Follow the existing pattern when modifying a primitive.

Service layer

MobX-based services in src/services/:

Services are wired together via src/service_provider.ts, which creates all service instances and injects dependencies. Components access services through the service provider — see existing components for the pattern.

Stage components

Stage UI components live in src/components/stages/. Each stage type typically has three components:

Styling

• Material 3 Design via SASS variables in src/sass/:
  • _colors.scss — color palettes and theme tokens
  • _common.scss — shared mixins and layout utilities
  • _typescale.scss — typography scale definitions
• src/pair-components/shared.css — base styles for primitives
• Use SASS variables and mixins — do not hardcode colors, spacing, or font values

Key files

Common pitfalls

1. Hardcoding colors or spacing — use SASS variables and mixins from src/sass/. Do not hardcode hex colors, pixel sizes, or font values.
2. Mixing CSS formats in pair-components — check the existing style file format (.css vs .scss) before editing a primitive's styles.
3. Forgetting to register a new service — new services must be instantiated in src/service_provider.ts and extend the Service base class.