Code Conventions

CSS Guidelines

  • Use design tokens (no hard-coded colors, spacing, or shadows).
  • Organize styles around the core files: app/src/styles/tokens.css for tokens, app/src/styles/global.css for shared layout + component rules, and app/src/styles/styles.css as the entrypoint.
  • Name classes with BEM: block__element--modifier.
  • Design mobile-first and use standard breakpoints (640px, 720px, 900px, 1024px, 1200px, 1260px).
  • Respect themes and motion preferences; prefer clamp() for fluid sizing.
/* Token-based styling */
.card {
  background: var(--surface-card);
  padding: var(--space-md);
  border-radius: var(--radius-md);
  box-shadow: var(--shadow-soft);
}

HTML Guidelines

  • Prefer semantic HTML5 elements and maintain heading hierarchy.
  • Include ARIA labels, alt text, and keyboard focus states.
  • Reuse shared Astro components and layouts instead of duplicating markup.

JavaScript Guidelines

  • Use ES6+ modules and export functions/classes for testing.
  • Avoid inline HTML strings; build DOM nodes programmatically.
  • Keep scripts modular inside /assets/.

File Organization

├── app/src/content/pages/en/        # Astro content collection entries (MDX/Markdown)
├── app/src/content/site.json        # Shared copy and site config
├── app/src/styles/                  # Style entrypoint, tokens, and shared/global rules
├── app/src/components/              # Reusable Astro/React components
├── app/dist/                        # Built Astro output
├── assets/                          # JavaScript files
├── scripts/                         # Build scripts and utilities
├── worker/                          # Cloudflare Worker code
├── tests/                           # Test suites (smoke, e2e, worker)
└── docs/                            # Documentation

Adding New Files

  • New content entry: add an MDX/Markdown file to app/src/content/pages/en/ (Astro content collection) and keep shared strings in app/src/content/site.json in sync.
  • New component: create the component in app/src/components/ and pair it with any needed stylesheet imports from /app/src/styles.
  • New page: add app/src/content/pages/en/my-page.mdx (and any shared copy updates in app/src/content/site.json), then preview with bun run dev or build with bun run build.