# Bigscreen VR — Site Rebuild (migrating off Builder.io)

This file is your standing context. Read it fully before acting.

## Mission

Rebuild the Bigscreen VR marketing site (currently bigscreenvr.com, built in
Builder.io) as a self-owned, code-based site. We are leaving Builder.io as a CMS.
The goals, in priority order:

1. **Ownership / portability** — the site must be a normal codebase we fully
   control, with no hard dependency on any single vendor to keep running.
2. **A real design system** — reusable components so new pages can be built
   consistently and indefinitely.
3. **Dynamic, polished feel** — tasteful motion and effects, not a static brochure.
4. **Non-technical editing later** — eventually a non-technical team will create
   pages. The owner designs in Figma. (Editing-layer choice is still open — see below.)

## Design protocol — read before any UI work

The brand identity is committed; preserve it, never reinvent it. The full system is
auto-loaded below (`@PRODUCT.md`, `@DESIGN.md`) — treat it as binding, not background.
For serious design work, run `/impeccable` (`craft` / `shape` / `polish`) to layer full
craft guidance on top of this system.

Non-negotiables:
- **Type:** Neue Haas Grotesk Display Pro (display + body) + Fragment Mono (labels,
  numerals, eyebrows). No third UI typeface.
- **Color:** one signal violet `#4D1EF7` on a black stage; everything else is an
  achromatic ramp. Violet signals one CTA/emphasis per view — it never decorates.
- **Tokens only:** never inline raw hex or magic numbers — reference the Tailwind
  tokens and CSS variables.
- **Angular shape system** on the live `/en` surface: beveled corners + Fragment Mono
  uppercase buttons. Match it when extending that page.
- **Voice:** confident, specific, technical stated plainly. Lead claims with the number
  (107g, 116°). No hype, no marketing buzzwords, no em dashes.
- **Motion is the reveal**, never ornament; always honor `prefers-reduced-motion`.
- **Keep code identifiers and filenames neutral** — no files, folders, exports, ids, or
  classes named after another company (use `easeSignature`, not a brand name). But
  referencing brands as *design-inspiration shorthand* in prose docs (PRODUCT.md /
  DESIGN.md) is fine and encouraged where it sharpens intent.

@PRODUCT.md
@DESIGN.md

## Current status

- Existing site content has been exported from Builder.io via its Content API into
  the `builder-export/` folder (JSON per page + downloaded images). This is the
  source material to rebuild from. **Do not scrape the live site** — use the export.
- The Next.js project is scaffolded and the homepage is built. The live `/en` surface
  currently serves a faithful static mirror (`public/landing/index.html`) via a rewrite,
  while the component-based rebuild lives under `src/components/blocks/`.
- The design system exists in code: tokens in `tailwind.config.ts` + `globals.css`,
  documented in `DESIGN.md`.

## Tech stack (decided)

- **Next.js** (App Router) + **React** + **TypeScript**. Always TypeScript.
- **Tailwind CSS** for styling. Design tokens live in `tailwind.config.ts`.
- **Motion** (formerly Framer Motion) for component/UI animation.
- **GSAP + ScrollTrigger** for scroll-driven effects; **Lenis** for smooth scroll.
- Target deploy: self-hosted on a VPS via Coolify (own the hosting end to end).

Use these. Do not introduce a different framework, CSS-in-JS library, or state
manager without asking first.

## Repository structure (target)

    bigscreenvr-site/
      builder-export/        # source content (read-only input; do not edit)
      src/
        app/                 # Next.js App Router routes (one folder per page)
        components/
          blocks/            # page section components (Hero, FeatureGrid, CTA, ...)
          ui/                # primitives (Button, Container, Heading, ...)
        lib/                 # helpers, motion presets
        styles/              # globals.css with CSS variables
      tailwind.config.ts     # design tokens (colors, type, spacing, radii, motion)
      AGENTS.md              # this file

## How to read the Builder export

Each page model file (e.g. `builder-export/page/_all.json`) is an array of entries.
A typical entry has: a `name`, a `data` object, and targeting info that usually
includes the page's URL path (look under `query` / `data` for a `urlPath` or similar).
The visual content lives in `data.blocks` — a tree of Builder elements. Each block
typically carries a `component` (with a `name` like "Text", "Image", "Columns",
"Section", or a custom name) plus `options`, and `responsiveStyles` (large/medium/
small breakpoints). Text blocks hold HTML in their options; image blocks hold a
cdn.builder.io URL.

Your job is NOT to reproduce this JSON shape in code. Read it to recover: the page's
copy, its images, its structure (what sections exist and in what order), and the
visual styling (colors, spacing, fonts) so you can rebuild each page as clean
components. Inspect the actual JSON before assuming field names — Builder's structure
varies by how the page was built.

## Design system

- Extract tokens from the export's styling (and the owner's Figma when provided):
  the color palette, the type scale, spacing rhythm, border radii, shadows, and
  motion timings/easings. Put them in `tailwind.config.ts` and as CSS variables in
  `globals.css`.
- **Never inline raw hex values or magic numbers in components.** Reference tokens.
- Identify the recurring section types across pages and build one component per type
  in `components/blocks/`. Pages are composed from these blocks — a new page should
  be assembling existing blocks, not writing bespoke markup.
- Keep components **presentational and content-agnostic**: props in, no hardcoded
  copy. This is what lets a CMS or a non-technical editor drive them later.

## Motion / effects conventions

- Centralize animation presets (durations, easings, variants) in `lib/motion`.
- Respect `prefers-reduced-motion` — gate non-essential animation behind it.
- Prefer transform/opacity animations for performance. Don't animate layout
  properties on scroll.

## Future editing layer (OPEN decision — do not lock us in)

The non-technical editing layer is not chosen yet. Candidates: Storyblok (visual,
easy for non-tech), Payload (open-source, self-hosted), or connecting Builder Fusion
to this repo. Because of this, build components so they could be registered as CMS
blocks later: clean prop interfaces, no assumptions about a specific CMS. Do not wire
in any CMS until that decision is made.

## SEO & accessibility (marketing site — these matter)

- Per-page metadata (title, description, OG tags) via Next's metadata API.
- Semantic HTML, alt text on images, sensible heading order, keyboard focus states.
- Re-host exported images locally (in `public/` or an image pipeline); don't hotlink
  cdn.builder.io long-term.

## Cautions

- `builder-export/` is INPUT. Read it; don't modify it.
- Don't reach out to the live Builder site or Builder's API at runtime — we are
  cutting that dependency, not re-adding it.
- When something about the original design is ambiguous in the JSON, ask or make a
  clearly-flagged reasonable choice rather than guessing silently.

## Suggested first tasks (in order)

1. Scaffold the Next.js + TypeScript + Tailwind project (App Router).
2. Parse `builder-export/page/_all.json`: list every page, its URL path, and the
   sequence of section types it uses. Produce a short inventory before building.
3. From that inventory + the styling in the JSON, draft `tailwind.config.ts` tokens
   and the initial `components/blocks/` set.
4. Rebuild the homepage first, end to end, as the reference implementation.
5. Then rebuild remaining pages by composing the blocks.

Confirm the inventory (step 2) with me before building everything, so we agree on
the component set up front.

## Design context (auto-loaded — see "Design protocol" above)

The two files imported in the Design protocol are always in context; this is what they
hold:

- **PRODUCT.md** — register (brand), users, purpose, brand personality, anti-references,
  and the 5 design principles. The "why/who".
- **DESIGN.md** — the visual system (colors, typography, elevation, components) extracted
  from the live-site rip. The "how it looks". Tokens also live in `tailwind.config.ts`
  and `src/styles/globals.css`; `.impeccable/design.json` is the machine sidecar.