Workflow Standards

A summary of the core principles defined in the obi-docs.

The Law of Layout

Every page must strictly follow this hierarchy to ensure consistency and prevent layout drift: 

Main -> Section -> Container -> Content
  • Section: Controls vertical spacing and semantic division.
  • Container: Controls horizontal width and padding.
  • Exceptions: None. Even the homepage follows this, though it swaps PageHeader for a Hero component.

Naming Conventions

We follow a strict 80/20 set of rules for clarity:

  • Pages: Lowercase (folder-based routing with index.astro).
  • Components: PascalCase (e.g., HeroHome.astro).
  • Folders: Lowercase (e.g., src/components/blocks/).

Localization (i18n)

We use a Manual Routing Map strategy instead of automatic magic.

  • Source of Truth: src/config/routes.ts defines all relationships.
  • Explicit Props: locale and pageKey are passed explicitly to every page.
  • No Redirects: The URL is the single source of truth. No cookies, no detection.

Dev Workflow

  • npm run dev for development (uses src/).
  • npm run build for production output (creates dist/).
  • npm run preview to test the build thoroughly.