sandvich
/
hackathon
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
hackathon/docs/style-and-pages-architectur...

3.3 KiB
Raw Permalink Blame History

Style and Page Architecture

This document defines how styling and page structure should evolve in this project.

Goals

  • Keep global styling predictable and centralized.
  • Keep component styling local and maintainable.
  • Keep page flow explicit and easy to extend.
  • Make it easy for contributors and agents to add new pages and styles consistently.

Current Page Organization

Pages live in src/pages/ and are intentionally minimal placeholders right now.

  • src/pages/HomePage.tsx
  • src/pages/SongSelectionPage.tsx
  • src/pages/GamePage.tsx
  • src/pages/EndOfGamePage.tsx
  • src/pages/LeaderboardPage.tsx
  • src/pages/CreditsPage.tsx

Routes are centralized in:

  • src/app/route-paths.ts for route constants
  • src/app/AppRoutes.tsx for route definitions

App bootstrap:

  • src/main.tsx wraps the app in BrowserRouter and imports global CSS.
  • src/App.tsx renders AppRoutes only.

Route Map

  • / -> Home
  • /song-selection -> Song Selection
  • /game -> Game Screen
  • /end-of-game -> End Of Game
  • /leaderboard -> Leaderboard
  • /credits -> Credits

No page-to-page navigation links are required yet.

Style Architecture (Target)

Planned structure:

  • src/styles/tokens.css: design tokens (CSS variables)
  • src/styles/global.css: reset/base/global element rules
  • src/index.css: optional thin aggregator, or can stay empty if main.tsx imports styles directly

Recommended usage:

  1. Import global styles once in src/main.tsx.
  2. Use CSS Modules for component-local styles (ComponentName.module.css).
  3. Keep page-specific layout styles in page modules only when needed (PageName.module.css).
  4. Use tokens (var(--...)) in component/page modules to avoid hardcoded values.

Font System

Fonts are stored in src/assets/fonts/just-dance/ and loaded globally via @font-face in src/index.css.

  • JustDance-Regular.otf (400)
  • JustDance-Bold.otf (700)
  • JustDance-Black.otf (900)

Semantic font variables (in :root):

  • --font-family-base
  • --font-family-display
  • --font-family-ui
  • --font-size-display-xl
  • --font-size-display-lg
  • --font-size-title
  • --font-size-body
  • --font-size-caption
  • --font-weight-regular
  • --font-weight-bold
  • --font-weight-black

Semantic utility classes (global):

  • .font-display
  • .font-title
  • .font-body
  • .font-caption

Guideline:

  • Use variables for sizing/weights in component CSS.
  • Use semantic classes for quick typography intent in markup.

Rules of Thumb

  • Global CSS should handle only app-wide concerns:
    • normalize/reset
    • typography defaults
    • body/root layout primitives
    • utility classes used globally
  • Component CSS Modules should handle component visuals and layout.
  • Avoid adding feature-specific styles to global files.
  • Prefer semantic token names, for example --color-surface, --space-md, --radius-sm.

Adding a New Page

  1. Create src/pages/NewPage.tsx.
  2. Add path constant in src/app/route-paths.ts.
  3. Register route in src/app/AppRoutes.tsx.
  4. Add page style module only if needed (src/pages/NewPage.module.css).

Migration Note

The previous webcam-focused styling and view were replaced by route placeholders to support upcoming multi-page flow. Reintroduce webcam/game UI inside the appropriate page component (likely GamePage) as the next feature step.