@feeef.dev/cli 0.2.0

package/scaffolds/blank/docs/09-THEME-PORTING.md

@@ -0,0 +1,211 @@
+# Theme Porting Playbook — Lessons from Dawn
+
+> Theme package copy — paths assume this theme folder is the project root.
+
+Use this when porting a reference storefront theme (Shopify Dawn, etc.) into Feeef Lithium custom components, or when starting a **new** theme after Dawn.
+
+Companion: [`AGENTS.md`](../AGENTS.md), [`05-ANTI-PATTERNS.md`](./05-ANTI-PATTERNS.md), [`08-ORDER-FORM.md`](./08-ORDER-FORM.md), [`07-SHARED-COMPONENTS.md`](./07-SHARED-COMPONENTS.md).
+
+---
+
+## 0. Goal
+
+Match **craft and behavior**, not pixel-perfect Shopify Liquid. Feeef has different APIs (products list, cart, COD). Document intentional gaps (mega-menus, Color metafields, newsletter).
+
+---
+
+## 1. Workflow (new theme or major port)
+
+1. Unpack / scaffold source under `templates/<theme>-src/` (Dawn: ``).
+2. Promote chrome to **`shared/components/`** on day one: header-bar, footer, search, cart drawer — pages only `$ref`.
+3. Pixel-compare reference vs local at **same viewport** (e.g. 1440px) with browser tools.
+4. Wire Feeef APIs early (list, search, cart, shipping) — UI polish without data looks “broken”.
+5. After every batch: `npm run build` (or `template:dev`).
+6. Hard-refresh the preview store (`FEEEF_TEMPLATE_DATA_PATH`).
+
+```bash
+npm run dev
+# store: http://<slug>.localhost.feeef.org:3000/
+```
+
+---
+
+## 2. Shared chrome (mandatory)
+
+| Block | Must be shared | Notes |
+|---|---|---|
+| Announcement + header + drawers | `shared.dawn-header-bar` (or theme equivalent) | Search + cart live here |
+| Footer | `shared.dawn-footer` | |
+| COD / order shell | Prefer native `product_order_form` or full `08` contract | Simplified stubs are incomplete |
+
+**Do not** paste header/footer JSX into home + products + product shells. Duplication caused search/cart drift during Dawn port.
+
+Open cart from PDP after add:
+
+```js
+window.dispatchEvent(new CustomEvent('dawn:open-cart'));
+// Header listens once:
+// window.addEventListener('dawn:open-cart', () => setIsCartOpen(true));
+```
+
+---
+
+## 3. Craft / visual rules (Dawn-class)
+
+- Restraint: white chrome, thin rules, airy type — not purple gradients / card spam.
+- Prefer **Assistant** (or theme font) loaded once via `<link>` id guard.
+- Brand colors: `hsl(var(--primary))`. Chrome black/white OK only for rare craft accents; prefer tokens so dark/light works — see `docs/12-DARK-LIGHT-THEME.md`.
+- Arabic / RTL stores: **multilang themes** use `useFeeefLocale()` + `dir={locale === 'ar' ? 'rtl' : 'ltr'}` and `t()` (see [13-TEMPLATE-I18N.md](./13-TEMPLATE-I18N.md)). Force **`dir="ltr"`** only when intentionally matching an LTR-only reference craft on an RTL store.
+- Never wrap the whole page shell in `min-height: 100vh` in a way that pushes PDP content down — header chrome should be height-of-content.
+
+### Product cards
+
+- Square media (`aspect-ratio: 1 / 1`).
+- Hover secondary image when `media` has a **second distinct** URL:
+
+```js
+const raw = [product.photoUrl].concat(product.media || []).filter(Boolean);
+const seen = {};
+const images = raw.filter((src) => {
+  if (seen[src]) return false;
+  seen[src] = true;
+  return true;
+});
+const secondary = images[1] || null;
+```
+
+- `product.media` is **`string[]`**, not `{ url }[]`.
+- Enable `showSecondaryImage` by default on PLP / featured.
+
+### Search
+
+- Feeef list search param: **`params.search`** (also send `q` for compatibility).
+- URL query stays `?q=` for the storefront.
+- Prefer **predictive search** panel (live results + “Search for …” → `/products?q=`), not a bare full-screen input.
+
+### Footer
+
+- Shopify “Subscribe to our emails” is **unsupported** on Feeef — replace with **About / store bio** (`store.description` stripped of HTML, or props fallback).
+- Keep Quick links / Info / mission columns; social from `store.contacts`.
+
+### PLP filters
+
+- Map reference facets to Feeef reality: Availability + Price + **Category** (not Shopify Color metafields unless you build metafield support).
+- Empty search (`?q=product` with no matches) is valid — compare filled `/products` to a collection page.
+
+---
+
+## 4. Cart & PDP (high bug rate)
+
+### Add to cart
+
+```js
+// WRONG — does not add a line
+cart.updateCurrentItem({});
+document.querySelector('[aria-label="Cart"]')?.click();
+
+// RIGHT
+if (!cart.getCurrentItem() || cart.getCurrentItem().product.id !== product.id) {
+  cart.setCurrentItem({ product, quantity: 1 });
+}
+cart.addCurrentItemToCart(); // or cart.add({ product, quantity, variantPath })
+window.dispatchEvent(new CustomEvent('dawn:open-cart'));
+```
+
+### Bootstrap current item on PDP mount
+
+Qty steppers and add-to-cart need `cart.getCurrentItem()`. Set it when product loads. Variants must `setCurrentItem` / `updateCurrentItem` safely.
+
+### Shipping bootstrap — **once per product**
+
+Without native `OrderForm`, custom PDPs must wire shipping (see `lib/bootstrap-product-cart-shipping.ts` + scope API). Inline in react-live (no imports):
+
+```js
+cart.setShippingMethod(product.shippingMethod || store, false);
+cart.setShippingAddress({ type: 'home', state: null, city: null, country: 'dz', ... }, false);
+// then ff.shippingPrices.find → cart.setShippingPrice(sp, false)
+```
+
+**Critical bug (Dawn):** if the bootstrap `useEffect` depends on **`cartCtx`** (object identity), every `updateShippingAddress` recreates context → effect re-runs → `setShippingAddress({ state: null })` **wipes** state/city/delivery types.
+
+**Correct pattern:**
+
+```js
+const bootKey = React.useRef('');
+const cartReady = !!cartCtx?.cart;
+
+React.useEffect(() => {
+  if (!product || !cartReady || !store || !cartCtx?.cart) return;
+  const cart = cartCtx.cart;
+  // setCurrentItem if needed…
+  const key = product.id + ':' + store.id;
+  if (bootKey.current === key) return; // already bootstrapped
+  bootKey.current = key;
+  // setShippingMethod + setShippingAddress PRESERVING existing.state/city
+  // load shippingPrices once
+}, [product?.id, store?.id, cartReady, ff]);
+```
+
+- Depend on **`cartReady` (boolean)**, not `cartCtx`.
+- Preserve `existing.state` / `existing.city` / `existing.type` when writing address.
+- `getAvailableShippingTypes()` is **empty until state (wilaya) is set** — show a hint, then full-width delivery cards.
+
+### Floating labels on `<select>`
+
+Empty selects that use a first option labeled `"State"` **overlap** the floating label.
+
+- First option: `<option value="" disabled hidden />` (no text).
+- Always float the label for selects (`.dn-field--select .dn-field__label` at top).
+- Reserve `padding-top` on the select even when empty.
+
+---
+
+## 5. Order / COD
+
+Follow **[`08-ORDER-FORM.md`](./08-ORDER-FORM.md)** for production behavior:
+
+- Submit via `POST /api/orders/create` (not bare `ff.orders.send` in production).
+- Draft + pending, geo cascade, security.
+
+Dawn’s shared `dawn-order-form` and early PDP COD stubs are **visual** until they match that contract.
+
+---
+
+## 6. Intentional gaps vs Shopify Dawn
+
+| Shopify Dawn | Feeef approach |
+|---|---|
+| Mega-menu Bags/Shoes | Flat links or custom later |
+| Color metafield filters | Category (or skip) |
+| Newsletter signup | Store bio / About |
+| Best-selling sort | Map to Feeef `sort` values you support |
+| Country/currency selector | Optional / store config |
+| Predictive collections/pages | Products-only is enough |
+
+---
+
+## 7. New-theme checklist
+
+- [ ] `shared/` header (search predictive + cart drawer + `dawn:open-cart`)
+- [ ] `shared/` footer (bio, not fake newsletter)
+- [ ] Home / products / product / contact use `$ref` for chrome
+- [ ] PDP: `setCurrentItem` + shipping bootstrap **once** + real add-to-cart
+- [ ] PLP: `search` param, secondary image hover, Dawn-like filter bar
+- [ ] Selects: no label overlap
+- [ ] Delivery cards: expanded, appear after state
+- [ ] `dir="ltr"` on chrome if matching LTR reference on RTL stores
+- [ ] `template:build` + browser verify vs reference
+- [ ] Order form path follows docs/08 (or registry form)
+
+---
+
+## 8. File map (Dawn)
+
+| Area | Path |
+|---|---|
+| Shared header | `shared/components/dawn-header-bar/` |
+| Shared footer | `shared/components/dawn-footer/` |
+| Home shell | `pages/home/.../custom-dawn-header-home/` |
+| Products PLP | `.../dawn-collection-banner/` + `dawn-collection-grid/` |
+| PDP | `pages/product/.../custom-1777344732828270/` |
+| Reference Liquid | `templates/_references/dawn/` (read-only) |

package/scaffolds/blank/docs/10-SCHEMA-LIBRARY.md

@@ -0,0 +1,127 @@
+# Schema Library (`schema.library.json`)
+
+Theme-bundled **drag-drop catalog** for the merchant template editor.
+
+Components listed here can be **unused in `data.json`**. That is intentional: the theme ships extras the merchant can add later from the UI.
+
+## Three planes (do not confuse)
+
+| Plane | Theme source | Built output | Role |
+|---|---|---|---|
+| **Schema** | `schema.ts` (overlay) | `dist/schema.json` | Editor chrome: pages, layouts, root `propsSchema`, Lithium built-ins + overrides |
+| **Library** | `library/components/` | `schema.library` on schema | Optional drag-drop extras (inline copy) |
+| **Data** | `pages/`, `props.json` | `dist/data.json` | Live instances / merchant content |
+
+| Catalog entry | Storage | Insert mode | Audience |
+|---|---|---|---|
+| **Built-in** | Lithium `components` (merged into schema) | Registry `type` + defaults | Stock blocks |
+| **Theme library** | `schema.library.json` / `schema.library` | **Inline copy** | Theme author extras |
+| **My library / Marketplace** | DB `template_components` | `type: "reference"` + `refId` | Merchant / public reuse |
+
+```mermaid
+flowchart LR
+  schemaTs["schema.ts overlay"]
+  lithium["Lithium built-ins"]
+  disk["library/components/id/"]
+  build["template:build"]
+  schema["dist/schema.json"]
+  editor["Flutter Theme tab"]
+  data["templateData placement"]
+  schemaTs --> build
+  lithium --> build
+  disk --> build
+  build --> schema
+  schema --> editor
+  editor -->|"copy-on-drop"| data
+```
+
+## Authoring (template-kit)
+
+```
+templates/dawn-src/
+  library/components/<id>/
+    component.json    # type, code meta, props, schemas + catalog fields
+    component.jsx     # optional
+    slots/… children/…
+  dist/
+    schema.library.json
+    data.json
+```
+
+### Catalog fields on `component.json`
+
+| Field | Role |
+|---|---|
+| `libraryId` / folder name | Stable `id` in the library list |
+| `title`, `subtitle`, `category`, `tags`, `imageUrl` | Editor card |
+| `type` | Usually `custom`; may be a built-in registry type |
+| `props` | Becomes `propsDefault` on drop |
+| `code` / `component.jsx` | Custom JSX |
+| `propsSchema`, `slotsSchema`, `slotsLayout`, `slots`, `children` | Seeded on drop |
+
+Build:
+
+```bash
+cd storefront && npm run template:build
+# → dist/schema.library.json
+```
+
+## Wire shape
+
+```json
+{
+  "version": "1.0",
+  "components": [
+    {
+      "id": "dawn-promo-banner",
+      "title": "Promo Banner",
+      "subtitle": null,
+      "category": "marketing",
+      "tags": ["banner"],
+      "imageUrl": null,
+      "type": "custom",
+      "code": "function App() { return <div>{props.text}</div>; }",
+      "propsSchema": { "text": { "type": "string" } },
+      "propsDefault": { "text": "Sale" },
+      "slotsSchema": null,
+      "slotsDefault": null,
+      "slotsLayout": null,
+      "children": null
+    }
+  ]
+}
+```
+
+## Serving
+
+| Endpoint | Behavior |
+|---|---|
+| `GET /api/template/schema` | Lithium `schema.json` **plus** `library: [...]` from `template/schema.library.json` |
+| `GET /api/template/library` | Standalone library document |
+| Dev | `FEEEF_TEMPLATE_LIBRARY_PATH` → kit `dist/schema.library.json` |
+
+`StoreTemplate.schema` should include the same `library` array when publishing a theme so `TemplateFetchResult.fromStoreTemplate` exposes it via `rawSchema['library']`.
+
+## Editor behavior
+
+- Tab **Theme** lists `controller.themeLibraryEntries` (`rawSchema['library']`).
+- Drop / tap → **inline copy** into `templateData` (`buildThemeLibraryComponent`).
+- Not a live link to the theme file: later theme updates do **not** rewrite existing placements (unlike DB `reference`).
+- Prefer `shared/` + `$ref` for compile-time consistency across pages you ship in `data.json`; use **library** for optional blocks merchants may add.
+
+## vs `shared/`
+
+| | `shared/components` | `library/components` |
+|---|---|---|
+| Purpose | DRY placements already in the theme tree | Optional catalog for the editor |
+| Build | Inlined into `data.json` via `$ref` | Emitted as `schema.library.json` |
+| Unused OK? | No (only if referenced) | **Yes** |
+
+A component can exist in **both** (shared for shipped pages + library for drag-drop of the same block elsewhere).
+
+## Rules for AI
+
+1. New optional theme UI → add under `library/components/<id>/`, rebuild.
+2. Do not put library-only blocks into `data.json` unless the blank theme should include them.
+3. When packing a `StoreTemplate`, merge `library` into `schema`.
+4. Flutter insert = copy-on-drop, not `type: "reference"` (no DB id).

package/scaffolds/blank/docs/11-PAGES-CHECKOUT-THANKS-PRODUCT.md

@@ -0,0 +1,81 @@
+# Template Pages — checkout, thanks, product PDP
+
+> Theme package copy — paths assume this theme folder is the project root.
+
+Canonical routes and the **single-`main`-section** pattern.
+
+## Page matrix
+
+| Page id | Path | Sections | Notes |
+|---|---|---|---|
+| `product` | `/p/:id` **and** `/products/:id` | **`main` only** | Both URLs render the same PDP. Prefer `/p/` for links; `/products/:id` is an alias. |
+| `checkout` | `/checkout` | **`main` only** | Cart checkout. Prefer registry `cart_order_form` in a form slot. |
+| `thank_you` | `/thanks` | **`main` only** | Optional post-order page. Query params carry order context. Legacy `/thank-you` redirects. |
+| `not_found` | Next.js not-found | **`main` only** | Editable 404 (`type: "not_found"` or custom). |
+| `products` | `/products` | multi | Collection / PLP (unchanged). |
+| `home` / `contact` / … | … | multi | Unchanged. |
+
+## Pattern: one section, layout in slots
+
+```text
+pages.<id>.sections.main.components[0]   ← page shell (custom)
+  slots.header[]
+  slots.body[] | slots.form[]
+  slots.footer[]
+```
+
+Next.js page components only render `sections.main`. They do **not** invent header/footer section keys.
+
+Use a single `main` section; put chrome in slots.
+
+### Product runtime fallback
+
+`ProductPageContent` prefers `main`. If `main` is empty, it still renders the legacy multi-section tree (`header` / `top` / `start` / `end` / `bottom` / `footer`) for older store blobs.
+
+New themes (Dawn) ship `main` + slots only.
+
+## `/checkout`
+
+- Route: `app/checkout/page.tsx`
+- Dawn: `pages/checkout/…/dawn-checkout-shell` with slots `header` | `form` | `footer`
+- Form slot: `type: "cart_order_form"` (multi-item cart). `product_order_form` also works if the cart’s current item is enough.
+- Empty cart: shell shows empty state + link to `/products`.
+- On success, `CartOrderFormWrapper` redirects to `/thanks?order=&name=&phone=&total=`.
+
+## `/thanks`
+
+- Route: `app/thanks/page.tsx` → template key **`thank_you`**
+- Query params (all optional):
+
+| Param | Meaning |
+|---|---|
+| `order` / `id` | Order id |
+| `name` / `customerName` | Customer name |
+| `total` / `amount` | Display total |
+| `phone` | Phone |
+
+- Built-in registry type: `thank_you` (reads those params).
+- Dawn: `dawn-thanks-shell` (`$ref` shared) with slots `header` | `body` | `footer`; body hosts the thank-you JSX (reads those params).
+- After a successful COD submit, redirect e.g. `/thanks?order={id}&name={encodeURIComponent(name)}`.
+- Cart drawer “Check out” must link to **`/checkout`**, not `/cart`.
+
+## `/p/[...id]` and `/products/[productId]`
+
+- Routes: `app/p/[...id]/page.tsx` **and** `app/products/[productId]/page.tsx` (shared loader — **both fully work**, no redirect)
+- Loads product by slug; sets current cart item + shipping bootstrap
+- Dawn: `dawn-product-shell` with slots `header` | `body` | `footer`
+- Prefer `/p/` for links (Dawn, OG, schema); `/products/:id` stays as a working alias
+
+## Authoring checklist
+
+1. Add / edit under `pages/<page>/sections/main/…`
+2. Keep a single root (or a short stack) in `main`; put chrome in slots
+3. `npm run build`
+4. Preview with `npm run dev`
+5. Do **not** reintroduce multi-section keys on these three pages in new themes
+
+## Related
+
+- Order / COD contract: [08-ORDER-FORM.md](./08-ORDER-FORM.md)
+- Architecture pages list: [01-ARCHITECTURE.md](./01-ARCHITECTURE.md)
+- Schema library (optional drag-drop blocks): [10-SCHEMA-LIBRARY.md](./10-SCHEMA-LIBRARY.md)

package/scaffolds/blank/docs/12-DARK-LIGHT-THEME.md

@@ -0,0 +1,164 @@
+# Dark / Light Theme (on top of native Lithium theme)
+
+> Theme package copy — paths assume this theme folder is the project root.
+
+How Feeef storefront themes support **light**, **dark**, and **system** modes — and how custom / Dawn JSX must ride that stack instead of inventing a parallel palette.
+
+## Mental model (three layers)
+
+```text
+1. Template default          template.data.props.theme.mode  →  "light" | "dark" | "system"
+2. Runtime class             next-themes → <html class="dark"> (or not)
+3. CSS tokens                :root / .dark variables → hsl(var(--…))
+```
+
+| Layer | Who sets it | Effect |
+|---|---|---|
+| Template `props.theme.mode` | Merchant / theme author | Default mode when the store loads (`StyleWrapper` calls `setTheme`) |
+| `useTheme()` / toggle | Visitor or custom JSX | Overrides to light/dark/system for the session |
+| CSS variables | Lithium + Tailwind theme | Actual colors; **`.dark` swaps surfaces + brand** |
+
+Native registry components (order form, navbar, shadcn UI) already follow these tokens. Custom JSX must do the same.
+
+## Sources of truth
+
+## Template default mode
+
+In template root props (kit: `props.json` or `template.data.props`):
+
+```json
+{
+  "theme": {
+    "mode": "light",
+    "rounded": 100,
+    "font": "expoArabic"
+  }
+}
+```
+
+Options: `"light"` | `"dark"` | `"system"`.
+
+`StyleWrapper` reads `template.data.props.theme.mode` and, when it is not `"light"`, calls `setTheme(themeMode)` so the store opens in the authored default.
+
+## What happens in dark mode
+
+1. `next-themes` puts `class="dark"` on the document root (`attribute="class"`).
+2. **Surfaces** flip via `globals.css` `.dark { --background: …; --foreground: …; … }`.
+3. **Brand** flips via `StyleWrapper`: store `decoration.primary` / `secondary` (and on*) are converted to HSL, then `hslToDark(...)` writes `.dark { --primary: … }` etc.
+
+So in custom CSS you never hardcode “the brand hex for dark”. You write:
+
+```css
+color: hsl(var(--foreground));
+background: hsl(var(--background));
+border-color: hsl(var(--border));
+background: hsl(var(--primary));
+color: hsl(var(--primary-foreground));
+```
+
+When the visitor (or template) switches mode, tokens update automatically.
+
+## Token cheat-sheet (prefer these)
+
+| Token | Use |
+|---|---|
+| `--background` / `--foreground` | Page / section surfaces and body text |
+| `--card` / `--card-foreground` | Cards, panels |
+| `--muted` / `--muted-foreground` | Secondary text, soft fills |
+| `--border` / `--input` / `--ring` | Borders, inputs, focus |
+| `--primary` / `--primary-foreground` | Brand CTAs (store decoration) |
+| `--secondary` / `--secondary-foreground` | Secondary brand |
+| `--destructive` / `--destructive-foreground` | Errors / danger |
+| `--corners-card`, `--corners-fields`, `--corners-buttons-*` | Radii (mode-independent) |
+
+Always wrap color channels with `hsl(...)`:
+
+```jsx
+style={{ background: "hsl(var(--background))", color: "hsl(var(--foreground))" }}
+```
+
+```css
+.my-block {
+  background: hsl(var(--card));
+  color: hsl(var(--card-foreground));
+  border: 1px solid hsl(var(--border));
+  border-radius: var(--corners-card);
+}
+```
+
+Optional softer borders that still track mode:
+
+```css
+border: 1px solid color-mix(in srgb, hsl(var(--foreground)) 12%, transparent);
+```
+
+## Custom JSX: light/dark toggle
+
+`useTheme()` is in the react-live scope (no import):
+
+```jsx
+function App() {
+  const { resolvedTheme, setTheme } = useTheme();
+  const isDark = resolvedTheme === "dark";
+
+  return (
+    <button
+      type="button"
+      aria-label="Toggle theme"
+      onClick={() => setTheme(isDark ? "light" : "dark")}
+      style={{
+        color: "hsl(var(--foreground))",
+        background: "hsl(var(--muted))",
+        borderRadius: "var(--corners-buttons-medium)",
+      }}
+    >
+      {isDark ? "Light" : "Dark"}
+    </button>
+  );
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `theme` | Stored preference: `light` / `dark` / `system` |
+| `resolvedTheme` | What is actually painted: `light` or `dark` |
+| `setTheme(mode)` | Set preference |
+| `systemTheme` | OS preference when `theme === "system"` |
+
+Prefer **`resolvedTheme`** for conditional UI (icons, “is dark?”). Prefer **CSS variables** over branching colors when possible.
+
+## Tailwind / native components
+
+Registry / shadcn components use semantic classes (`bg-background`, `text-foreground`, `border-border`, `bg-primary`) which map to the same CSS variables. `dark:` variants work because of the `dark` class on `<html>`.
+
+In **custom react-live JSX**, Tailwind `dark:` utilities are unreliable (string CSS / limited class pipeline). Prefer CSS variables or a small `<style>` block that uses `hsl(var(--…))`.
+
+## Anti-patterns
+
+| Don’t | Do |
+|---|---|
+| `color: store.decoration.primary` (Flutter int) | `hsl(var(--primary))` |
+| Hardcoded `#fff` / `#000` for body chrome | `hsl(var(--background))` / `hsl(var(--foreground))` |
+| Duplicate “Dawn dark palette” hex tables | Ride Lithium tokens |
+| `if (dark) color = '#eee'` for brand CTAs | Keep `--primary`; only branch when an asset needs it |
+| Assume template mode alone updates mid-session | Use `useTheme().setTheme` for toggles |
+| Put mode under a page/component `props` | Root `template.data.props.theme.mode` |
+
+Hardcoded black/white is OK only for **reference craft** accents that intentionally ignore brand (rare). Prefer tokens for anything that should follow the store theme.
+
+## Authoring checklist
+
+- [ ] Surfaces and text use `--background` / `--foreground` (or card/muted)
+- [ ] Brand CTAs use `--primary` / `--primary-foreground`
+- [ ] Borders use `--border` or `color-mix` on `--foreground`
+- [ ] Radii use `--corners-*`
+- [ ] Toggle (if any) uses `useTheme()` + `resolvedTheme`
+- [ ] Template default set via `props.theme.mode` when the theme should open dark/system
+- [ ] Preview both modes: set mode in editor / `setTheme('dark')` and hard-refresh `template:dev`
+
+## Related
+
+- Custom styling rules: [03-CUSTOM-COMPONENTS.md](./03-CUSTOM-COMPONENTS.md)
+- Scope API (`useTheme`, CSS vars): `docs/03-CUSTOM-COMPONENTS.md`
+- Architecture theme note: [01-ARCHITECTURE.md](./01-ARCHITECTURE.md)
+- Anti-patterns: [05-ANTI-PATTERNS.md](./05-ANTI-PATTERNS.md)