eComX Build Log — Phase 1: Foundation in 28 Commits

February 23, 2026: The Starting Point

An empty directory. A brief. And 18 workflows ready to execute.

The objective: build a production-quality marketing site for eComX — an AI methodology consultancy. Not a landing page. A real site with internationalization, a design system, responsive layouts, dark mode, and a debug dashboard for development visibility.

Phase 1 would establish everything that every subsequent phase depends on.

The Discussion Phase

Before writing a line of code, /discuss-phase surfaced decisions that needed to be made:

1. Framework: Next.js 15 with App Router (Server Components by default, React 19 compatibility)
2. Database: Supabase (PostgreSQL with RLS, real-time subscriptions, built-in auth)
3. Styling: CSS Modules with a design token system (no Tailwind — maximum control)
4. i18n: next-intl for multilingual support (English + Thai initially)
5. State Management: React Context for theme, cart, and toast notifications
6. Debug Dashboard: Protected development tools at /debug with token-based auth

Each decision included rationale. CSS Modules over Tailwind because design tokens need to be centrally managed and referenced consistently. Supabase over raw PostgreSQL because auth, RLS, and Edge Functions are needed in Phase 3.

Plan by Plan

Plan 01: Project Scaffolding

The first commit established the Next.js 15 project structure with TypeScript strict mode:

src/
├── app/
│   └── [locale]/
│       ├── layout.tsx      # Root layout with providers
│       └── page.tsx        # Homepage
├── components/             # Shared components
├── content/                # MDX content
├── lib/                    # Utilities
├── messages/               # i18n translation files
└── styles/                 # CSS Modules + design tokens

The [locale] directory structure enables internationalized routing from day one — no retrofit needed when Thai content is added.

Plan 02: Design Token System

The design token system defines every visual value as a CSS custom property:

:root {
  --color-bg-primary: #0a0a0a;
  --color-bg-secondary: #141414;
  --color-text-primary: #ffffff;
  --color-accent-primary: #6366f1;
  --font-heading: 'Inter', sans-serif;
  --spacing-unit: 8px;
  --radius-md: 12px;
  --motion-duration-fast: 150ms;
}

Every component references these tokens — never raw hex codes, never magic numbers. When the brand evolves and colors change, a token update propagates everywhere instantly.

The token system includes:

• Color scales: Primary, secondary, accent, success, warning, error — each with 10 shade variants
• Typography: Font families, sizes, weights, line heights, letter spacing
• Spacing: Based on an 8px grid (4, 8, 12, 16, 24, 32, 48, 64, 96)
• Motion: Duration and easing curves for animations
• Dark mode: Full token override set for [data-theme="dark"]

Plan 03: Provider Architecture

Three context providers wrap the entire application:

ThemeProvider: Manages light/dark mode with system preference detection, localStorage persistence, and smooth CSS transitions. No flash of wrong theme on page load.

ToastProvider: Non-blocking notification system with auto-dismiss, stack management, and accessible announcements. Positioned bottom-right on desktop, bottom-center on mobile.

CartProvider: Shopping cart state with Stripe integration preparation. Quantities, line items, subtotal calculation, and persistent storage via localStorage.

These providers are composed in layout.tsx using the React 19 composition pattern — no prop drilling, no render prop hell.

Plan 04: PromoBar + Navbar

The first visible components:

PromoBar: Animated top banner with rotating promotional messages. Dismissible with localStorage memory — once dismissed, stays dismissed until the next session. Smooth entrance and exit animations.

Navbar: Responsive navigation with:

• Desktop: horizontal links, theme toggle, CTA button
• Mobile: slide-in drawer with full navigation tree
• Scroll behavior: transparent on hero, solid background on scroll
• Active link detection via usePathname()

Both components reference design tokens exclusively. Zero hardcoded values.

Plan 05: Debug Dashboard

The /debug route is the development control center:

• Phase Status: Visual cards showing each phase's completion percentage
• Test Results: Most recent test run output
• Route Registry: Every route in the application with its rendering strategy
• Build Health: TypeScript errors, lint issues, bundle size

The debug dashboard is protected by a DEBUG_TOKEN environment variable. Access requires:

1. Navigate to /debug
2. Enter the token (stored in macOS Keychain, not in code)
3. Token is hashed and compared server-side
4. On success, a secure HttpOnly cookie is set for session persistence

No API keys are exposed. No tokens are hardcoded. The debug dashboard is a development tool that's invisible in production.

Deviations and Lessons

Phase 1 had three documented deviations:

Deviation 1: The next-intl middleware conflicted with Next.js 15's new middleware.ts pattern. Resolution: custom middleware composition that chains i18n locale detection with other middleware logic.

Deviation 2: CSS Modules' :global selector was needed more often than expected for third-party component styling. Resolution: created a globals.css file for truly global styles, kept CSS Modules for component-scoped styles.

Deviation 3: The initial design token system used rem for all spacing. During responsive testing, discovered that px is more predictable for spacing tokens while rem is correct for typography. Resolution: spacing tokens in px, typography in rem.

Each deviation was documented in 01-SUMMARY.md files — available for any future project that faces the same decisions.

The Foundation Promise

After 28 commits: a Next.js 15 application with a design system, internationalization, responsive shell, dark mode, and a secure debug dashboard.

No features yet. No content. No payments. No email. Just the foundation.

But the foundation is airtight. The design tokens mean every component built in Phases 2-4 will be visually consistent. The provider architecture means state management is solved once, not per-component. The debug dashboard means development visibility is built in from day one.

Phase 1 isn't glamorous. But it's what makes Phases 2, 3, and 4 possible — and it's why 121 commits across 4 phases resulted in zero production build failures.

The foundation determines the ceiling.