# Genesis Starter

Starter WordPress theme built on **Timber v2** (Twig), **ACF** (local JSON) and **Vite**,
with a self-contained SCSS/JS design-system foundation baked into `vite/scss`.

Cleaned from a production theme: all the plumbing is kept, all real blocks were removed,
and the flexible-blocks system is documented with a single end-to-end example.

## Requirements

- WordPress with the **Timber** and **ACF Pro** plugins.
- PHP 8.0+ · Node 22 (`vite/.nvmrc`).

## Install

```bash
# In the theme root (installs Timber via Composer)
composer install

# Front-end build (in ./vite)
cd vite
npm install
npm run build      # production assets -> vite/dist
# or: npm run dev  -> HMR on http://localhost:5173
```

For the Vite dev server, add to `wp-config.php`:

```php
define('ENV_DEV', true);
```

Remove it (or set false) in production so the built `vite/dist` assets are used.

## Design system — foundation

The styling base lives in **`vite/scss/`** (tokens, typo, grid, utilities) and the
front-end runtime in **`vite/js/`** (Lenis, GSAP, Barba, page modules).

**Read `vite/scss/USAGE.md` before writing any SCSS, Twig, or JS.** It is the
single source of truth for:

- how to build a block in this theme (§0)
- how to convert an Osmo component or wire an image/parallax (§8)
- tokens, BEM, utilities, and hard rules (§1–7)

JS entry: `vite/js/main.js` → Barba + Lenis + `pageModules.js` (per-page inits).
Dev grid overlay: type `grid` on localhost.

## Structure

```
functions.php            Theme bootstrap (GenesisSite): context, menus, assets, Twig fns
inc/                     utils · cache · hooks · acf · wpml · CPT · taxonomies
acf-json/                Local ACF JSON (auto-loaded & syncable)
  group_flexibles.json         "flexibles" flexible-content field (1 layout)
  group_block_text_image.json  Example block fields (clones section settings)
  group_section_settings.json  Shared padding/background group (cloned by blocks)
  group_options.json           Site options (GTM, footer, socials)
templates/
  base.twig              HTML shell (header/content/footer blocks, GTM)
  flexibles.twig         ← CORE: renders page blocks from ACF "flexibles"
  partials/article-blocks.twig  ← CORE: renders per-post blocks ("article_blocks")
  blocks/block-text-image.twig  Example block (the model to copy)
  macros.twig            btn(), picture(), section_classes()
  parts/                 header · footer · menu (WP-wired) · breadcrumb · pagination
  page/single/index/archive/404/403.twig · template-flexible.twig
vite/
  scss/                  Foundation (flat partials + _index barrel + USAGE.md)
                         + project styles (base/rte, layout, blocks) + style.scss
  js/                    main.js + utils/ (grid-overlay, mobileMenu)
  vite.config.js · package.json · .nvmrc
```

## How the blocks work

A page using the **"Page à blocs (Flexible)"** template (or the `example` CPT) exposes an
ACF **flexible-content** field named `flexibles`. `templates/flexibles.twig` loops over it
and includes `templates/blocks/<layout>.twig` — the layout name *is* the twig filename.
Each layout **clones** its block field group, which itself clones the shared **section
settings** (padding + background). Posts have the equivalent `article_blocks` field, rendered
by `templates/partials/article-blocks.twig` (used in `single.twig`).

### Adding a new block (e.g. `block-cards`)

1. `templates/blocks/block-cards.twig` — copy `block-text-image.twig`; follow `vite/scss/USAGE.md`.
2. `acf-json/group_block_cards.json` — a **group** field `block_cards` that first **clones**
   `setting_section` (key `field_69b80dae8334c`), then your fields.
3. In `acf-json/group_flexibles.json`, add a layout **`block-cards`** whose single sub-field
   is a **clone** of your block group (seamless display).
4. `vite/scss/blocks/_block-cards.scss` + `@import 'blocks/card…'` in `vite/scss/style.scss`.

Easiest path: build the field groups in the WP admin (ACF → Field Groups); they are written
back into `acf-json/` automatically thanks to local JSON.

## Notes

- `style.css` header, text-domain (`genesis`) and function prefix (`genesis_`) are generic.
- Optional integrations removed for a clean base (re-add if needed): FacetWP, Gravity Forms,
  Mapbox. The generic hooks/utils they relied on stay.
