docs: add CSS-var conversion rules to ve-architecture and ve2-migration-playbook

- ve-architecture.md: added Core Rules 10, 11, 12 covering:
  - theme scope values must come from screenshots/{theme}/theme.css
  - CSS var references must be preserved (not resolved to static values)
  - variant styles set only CSS vars, never direct properties
- ve2-migration-playbook.md:
  - updated Sourcing CSS values table to mark screenshots/{theme}/theme.css
    as authoritative for global --bs-* values
  - added 3 new Common gotchas rows for the same three rules

Agent-Logs-Url: https://github.com/arijs/bootswatch-solid/sessions/ed74e481-9863-4b0c-a965-7f28c477a279

Co-authored-by: rhengles <8967+rhengles@users.noreply.github.com>

Author: Copilot

docs/ve-architecture.md

@@ -214,6 +214,9 @@ ve-project2/src/
 7. **Only these static class names are allowed in component markup:** `bd-example-ve2`, `pwhook-*` screenshot hooks. All other styling comes from VE imports.
 8. **ThemeContext provides the active scope class string.** Components read it via `useContext(ThemeContext)` — no prop-drilling.
 9. **`ThemedBody` (or equivalent) must wrap any region that requires body-level theme styles** (font, color, background).
+10. **Global `--bs-*` var values in `scope.css.ts` must be sourced from `screenshots/{theme}/theme.css`.** The `:root` block in that file is the authoritative source for each theme's resolved CSS custom-property values (e.g. `--bs-primary`, `--bs-border-radius`, `--bs-link-color`, etc.). Never copy Bootstrap's default values for a Bootswatch theme — look up the theme's own overrides in `screenshots/{theme}/theme.css`.
+11. **CSS custom-property references must be preserved as references, not resolved to static values.** If the Bootstrap source CSS writes `var(--bs-border-radius)`, the VE2 output must write `varBsBorderRadius` (the matching `createVar()` identifier), not the final resolved value (e.g. `'0.375rem'`). This ensures per-theme values propagate correctly at runtime.
+12. **Component variant styles must set only CSS vars.** The base component class (e.g. `.btn`) owns all layout and interaction rules that reference those vars. Variant classes (e.g. `.btn-primary`, `.btn-outline-secondary`) only override CSS custom properties via `vars:` — never set `color`, `backgroundColor`, `borderColor`, etc. directly on a variant rule. This mirrors Bootstrap's own source structure exactly.
 
 ---
 

docs/ve2-migration-playbook.md

@@ -163,7 +163,7 @@ globalStyle(`${sketchyScope}${myComponent}`, {
 | Bootstrap 5.3 component CSS (var names + default values) | `screenshots/bootstrap/bootstrap.css` — search for `.my-component {` to find `--bs-my-component-*` var declarations and the properties that reference them |
 | Sketchy overrides (SCSS source) | `node_modules/bootswatch/dist/sketchy/_bootswatch.scss` |
 | Sketchy compiled CSS | `screenshots/sketchy/bootstrap.css` — grep for the component class to see final resolved values |
-| Global `--bs-*` resolved values | `screenshots/{theme}/bootstrap.css` `:root` block — `--bs-border-radius`, `--bs-primary-rgb`, etc. Cross-reference with `theme-contract/_vars.css.ts` to find the matching `createVar()` identifier |
+| Global `--bs-*` resolved values for a theme | **`screenshots/{theme}/theme.css`** `:root` block — this is the **authoritative source** for each theme's CSS custom-property values (`--bs-primary`, `--bs-border-radius`, `--bs-link-color`, etc.). Always read values from this file when setting vars in `scope.css.ts`. Cross-reference with `theme-contract/_vars.css.ts` to find the matching `createVar()` identifier. |
 
 ---
 
@@ -267,6 +267,9 @@ The `converted=` number should increase by exactly the count of routes you added
 | Sketchy close button | Sketchy replaces the SVG close-button background with a `::before { content: "X" }` pseudo-element. See `node_modules/bootswatch/dist/sketchy/_bootswatch.scss`. |
 | Sketchy border-radius for special shapes | Some components (alerts, cards) use a distinctive hand-drawn shape: `$border-radius-sketchy: 255px 25px 225px 25px / 25px 225px 25px 255px` (defined in `_bootswatch.scss`). This overrides the global `varBsBorderRadius` at the component level. |
 | Utility classes must be absorbed into contract classes | The original HTML uses Bootstrap utility classes directly (`bg-primary`, `text-dark`, `rounded-pill`, etc.). In VE2 these have no effect — absorb their values into the appropriate contract variant class (e.g. `badgePrimary` encodes both background-color and the default white text; `badgeWarning` overrides `color` to `#000`; `badgeRoundedPill` sets the pill `border-radius`). |
+| Scope `vars:` values must come from `screenshots/{theme}/theme.css` | When populating `scope.css.ts` with global `--bs-*` values (colours, radii, link colours, etc.), always read the resolved values from the `:root` block in `screenshots/{theme}/theme.css`. Never copy Bootstrap's default values for a Bootswatch theme — the theme overrides many of them. E.g. Sketchy sets `--bs-primary: #333` (not `#0d6efd`) and `--bs-link-color: #333` (not `#0d6efd`). |
+| CSS var references must stay as var references | If Bootstrap's source CSS writes `var(--bs-border-radius)`, the VE2 output must use `varBsBorderRadius` (the matching `createVar()` identifier), **not** the resolved static value (e.g. `'0.375rem'`). Resolving to a static value breaks per-theme inheritance — the whole point of the CSS custom-property cascade is that each theme sets the global var to its own value. |
+| Variant rules must only set CSS vars | Component variant classes (e.g. `.btn-primary`, `.btn-outline-danger`) must only override CSS custom properties via `vars:`. They must **not** directly set layout or colour properties (`color`, `backgroundColor`, `borderColor`, etc.). The base component class (e.g. `.btn`) owns those property declarations and references the vars — this mirrors Bootstrap's source structure exactly and ensures all interaction states (hover, active, disabled) work correctly through the shared rules on the base class. |
 | `@screenshot` annotations — use the original's full list | The original source file (`src/components/…`) contains per-theme height overrides (e.g. `// @screenshot sketchy: 360x303 303`). Copy those annotations verbatim into the VE2 component so the screenshot harness captures the correct crop size per theme. Omitting them causes the wildcard `*` fallback to be used for all themes, which may cut off content in themes with larger spacing. |
 | `<p class="h1">` vs actual `<h1>` | The original uses Bootstrap typography utility classes (`.h1`–`.h6` on `<p>`) to mimic heading sizes. VE2 components should use real `<h1>`–`<h6>` elements instead — the browser's default UA stylesheet provides the same relative sizing without needing extra contract classes. |