# UIkit BEM Naming — CRM Sync Brand Kit

UIkit is **BEM, namespaced with `uk-`**. Conflict-free with vanilla / Webflow / Tailwind by
construction (the `uk-` prefix sandboxes it), and semantic by design.

## The convention
| Part | Pattern | Examples |
|---|---|---|
| **Block** | `uk-{block}` | `uk-card`, `uk-button`, `uk-nav`, `uk-grid`, `uk-section`, `uk-alert` |
| **Element** | `uk-{block}-{element}` | `uk-card-title`, `uk-card-body`, `uk-nav-header`, `uk-navbar-nav` |
| **Modifier** | `uk-{block}-{modifier}` | `uk-card-primary`, `uk-button-secondary`, `uk-section-muted`, `uk-card-hover`, `uk-button-large` |

Example: `<div class="uk-card uk-card-default uk-card-body">` = block + modifier + element.

## Why BEM (the benefits)
**LLM / AEO (answer-engine optimization).** Stable, semantic class names are machine-readable. An
LLM or answer engine reads `uk-card` → `uk-card-title` → `uk-alert-danger` as *structure*; it
can't infer intent from utility soup (`.p-4 .flex .gap-2 .text-red-500`). Semantic BEM = better
parsing, summarization, and citation by AI — the storefront is legible to models, not just browsers.

**i18n / globalization.** Structure is separate from content, so one `uk-*` skeleton serves every
locale. Strings come from the edge-translate service (EN/FR/KO/ZH/JA, KV-cached) and the `kb_i18n`
layer; a planned `uikit-i18n.js?locale=` maps UIkit's component strings. Translate the content,
never the markup — the BEM classes are universal, the values are per-locale.

**Event Bus → Shopify / GA4.** The Higher-Order Stack event bus (`window.crmStack`) normalizes
every interaction into one stream: `crmStack.emit(name, detail)` → `dataLayer` → GTM → **GA4 and
Shopify** (commerce events + Consent Mode v2 signals). Consent flips via `crmStack.consent(...)`.
A click on a semantic `uk-button-primary` can fire a measured, consent-gated event to both GA4 and
Shopify with no bespoke wiring per surface.

## Reinforces Shopify's weak semantic structure (and works everywhere)
Shopify themes are commerce-first and can be **weak on organic / semantic structure** — markup is
often forced by the theme, not authored for meaning. Layering semantic `uk-*` BEM on top gives the
storefront the structured, machine-readable HTML that **AEO and LLMs reward**, without touching the
theme's core. It's the same move many **Dawn-era themes** made by **adding Vue to reinforce SEO** —
this just makes it easy and portable: **petite-vue** (tiny, no build) hydrates the semantic markup.

Framework-agnostic by construction — the SAME brand kit + stack run on **Shopify (Horizon/Dawn),
Astro, 11ty, WordPress, Drupal**, with **Shopify Web Components wrapped in Vue / Vite code-split**.
One semantic layer, every platform; no per-framework rewrite (the Higher-Order Stack delivery model).

## The Stack function (GA4-first · consent · UUID logging · reset)
`/embed/stack-loader.js` exposes `window.crmStack`:
- **GA4 loads first, consent-gated** — Consent Mode v2 is set DENIED *before* GA4, then GA4 loads;
  nothing fires until `crmStack.consent({...})`.
- **UUID** — a stable anonymous client id (`crmStack.uuid`) attached to GA4 as a user_property.
- **Logging** — `crmStack.log(event, detail)` fires the bus (dataLayer → GA4 + Shopify) AND persists
  a PII-free, consent-stamped, UUID-tagged record to `POST /signals/log` (Xano = system of record).
- **Reset** — `crmStack.reset()` rotates the UUID, re-denies consent, re-prompts, logs the reset.

## The brand bridge (which `uk-*` the CRM Sync theme.css recolors)
`uk-button-primary/secondary`, `uk-text-primary`, `uk-background-primary`, `uk-label`,
`uk-alert-primary/success/warning/danger`, `uk-section-primary/secondary`, `uk-tile-*`,
`uk-card-primary/secondary`, and the `uk-light` inverse. Each reads
`var(--global-…-background, <brand value>)` — a Webflow Variable wins; the brand value is the fallback.

## "Set the Globals, everything follows"
`global-primary-background`, `global-secondary-background`, `global-background`,
`global-muted-background`, `global-color`, `global-emphasis-color`, `global-muted-color`,
`global-inverse-color`, `global-border`, `global-link-color`, `global-link-hover-color`,
`global-success-background`, `global-warning-background`, `global-danger-background`,
`global-font-size`, `border-rounded-border-radius`.

## Async data (GraphQL · Webflow → Xano → Shopify Metaobjects)
With the **Stack** embed on, `crmStack.gql(url, query, vars)` fetches async data from the unified
layer: content authored in **Webflow Collections** syncs to **Xano** (source of truth), which
mirrors to **Shopify Metaobjects** — the same record renders on the storefront, the Webflow site,
and any embed. Full summary: https://crm-sync.dev/async-data

## Reference
- Per-brand: /brand/<slug>/uikit.scss?full=1 · /theme.css · /tokens.json · /kitchen-sink
- Full component list + token map: the `uikit` skill.