@wippy-fe/theme 0.0.41 → 0.0.43

package/THEMING.md

@@ -481,7 +481,7 @@ Same numbered scale pattern as primary (50–950) using `color-mix`.
 
 **Fixed light-to-dark scale** — 0 is always lightest, 950 always darkest. The scale does NOT flip with dark mode. In dark mode, only 600–950 get warmer undertones.
 
-### Semantic variables (15 vars)
+### Semantic variables
 
 These **flip with dark mode** — use these for theme-dependent styling.
 
@@ -505,6 +505,44 @@ These **flip with dark mode** — use these for theme-dependent styling.
 | `--p-highlight-focus-color` | `primary-800` | `white @ 87%` |
 | `--p-content-border-radius` | `6px` | `6px` |
 
+### Family aliases — one grammar, zero exceptions
+
+**Why this exists:** a small, fully regular grammar means a human — or an AI agent generating styles — can *predict* the right token instead of looking it up. The contract is two layers:
+
+- **Numeric scale** (`--p-<family>-50` … `--p-<family>-950`) — the fixed-hue anchor. **Never theme-switchable**: identical in light and dark. Use it only when you explicitly do *not* want the value to flip.
+- **Semantic aliases** (`-color` / `-contrast-color` / `-hover-color` / `-active-color`) — the theme-switchable layer. `-color` is always paired with `-contrast-color` (the color to place *on top* of it) plus its hover/active states, so a foreground + its guaranteed on-color come as a set with no `dark:` pair needed.
+
+Because the grammar is exceptionless, `var(--p-<anything>-color)` / `-contrast-color` / `-hover-color` / `-active-color` is guaranteed to exist for all eight families — nothing to memorize per family, and [`tokens.json`](./tokens.json) is the machine-readable ground truth an agent can load.
+
+**Every** color family (`primary`, `secondary`, `danger`, `success`, `warn`, `info`, `help`, `accent`) carries the same four mode-flipping aliases, remapped identically:
+
+| Alias | Light | Dark |
+|---|---|---|
+| `--p-<family>-color` | `<family>-500` | `<family>-400` |
+| `--p-<family>-contrast-color` | `surface-0` | `surface-900` |
+| `--p-<family>-hover-color` | `<family>-600` | `<family>-300` |
+| `--p-<family>-active-color` | `<family>-700` | `<family>-200` |
+
+So `var(--p-danger-color)` is the mode-correct danger for text/fills, `var(--p-danger-contrast-color)` the text color on top of it — no `dark:` pair needed. The numeric scale (`--p-danger-500`) remains the fixed-hue anchor for uses that must NOT flip.
+
+The full inventory (names, both mode values, flip flags) is generated into [`tokens.json`](./tokens.json) on every build; `scripts/build-token-manifest.js` also fails the build if a token ever deviates from this grammar or the duplicated dark blocks drift apart. Treat `tokens.json` as the ground truth for "does token X exist".
+
+### Font tokens
+
+One grammar per font role: `--p-font-<role>-<prop>` with roles `heading` / `body` / `mono` and props `family`, `scale` (multiplier over the role's base sizes), `line-height`, `letter-spacing`, `stretch`, `variation-settings`. Defaults are visually inert; all are mode-independent.
+
+**Reach (what these actually steer):** the RENDERED-CONTENT typography — markdown headings h1–h6, `.data-body` body text and code blocks, including inside chat messages. Host chrome text, PrimeVue component CSS, and child apps' own styles do not read these tokens (the legacy `--v-font-family-head` had exactly the same reach). Every token below has a live consumer in the compiled content styles — none is speculative.
+
+```css
+:root {
+  --p-font-heading-scale: 1.1;              /* rendered-content headings 10% larger */
+  --p-font-heading-letter-spacing: -0.01em; /* tighter content headings */
+  --p-font-body-stretch: 95%;               /* narrower content body text (variable fonts) */
+}
+```
+
+`--p-font-heading-family` defaults to the legacy `--v-font-family-head` (which keeps working), `--p-font-mono-family` steers markdown/code blocks. Which font files load — families, kept weights, `size-adjust`, `ascent-override`/`descent-override` (per-font width/vertical-position correction) — is @font-face-level and lives in the facade `fonts` theming param, which the host compiles into distributed CSS (see the host docs; `FontConfig` in `app-config/types.ts`). A `fonts` entry with `roles: ['body']` additionally emits a document-level `body { font-family: … }` rule, so the FAMILY of body text does apply document-wide — the `--p-font-body-*` adjustment vars above remain content-scoped.
+
 ## Reference — Tailwind utility classes
 
 Provided by `tailwindcss-primeui` plugin (included in the shared Tailwind preset).
@@ -638,6 +676,14 @@ The CSS files use theme variables via Tailwind classes. Example from `button.css
 
 The `tailwind.css` master file imports all component CSS files organized by category (form, button, data, overlay, menu, panel, file, message, media, misc).
 
+### Overlays render inside the shadow root
+
+PrimeVue overlays — `Dialog`, `Drawer`, `Select`, `Popover`, `Menu`, `MultiSelect`, … — teleport their panel through one shared primitive (`primevue/portal`) whose default target is `document.body`. Inside a **web component** that escapes the shadow root, so the panel loses the module's shadow-scoped CSS (and the injected `primeVueCssUrl`) and renders unstyled next to `<body>`.
+
+`PrimeVuePlugin` handles this for you: at `install()` it flips the shared Portal's `appendTo` default from `'body'` to `'self'`, so every overlay renders **inline, inside the shadow root**, by default — you do nothing. A component that passes its own `appendTo` (e.g. `<Dialog appendTo="body">`) still wins; the override only changes the default. This matters most for `Drawer`, which hard-wires its Portal with no `appendTo` and so is the one overlay that otherwise *always* escapes.
+
+> PrimeVue 4 exposes no global overlay / `appendTo` config, and all overlays share the one Portal — so this single default-flip is the whole fix. No per-component `appendTo="self"` boilerplate and no per-app `patch-package` needed. (Requires `@wippy-fe/theme` with this behavior; see the package version.)
+
 ### Available PrimeVue component styles
 
 **Form**: autocomplete, cascadeselect, checkbox, colorpicker, datepicker, iconfield, iftalabel, inputgroup, inputnumber, inputotp, inputtext, floatlabel, knob, listbox, multiselect, password, radiobutton, rating, select, selectbutton, slider, textarea, togglebutton, toggleswitch, treeselect

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wippy-fe/theme",
-  "version": "0.0.41",
+  "version": "0.0.43",
   "description": "Theme variables, shared Tailwind config, and PrimeVue styling for Wippy web components.",
   "type": "module",
   "main": "theme-config.css",
@@ -13,6 +13,7 @@
   },
   "files": [
     "theme-config.css",
+    "tokens.json",
     "tailwind.config.ts",
     "primevue-plugin.ts",
     "primevue/",

package/primevue-plugin.ts

@@ -1,8 +1,33 @@
 import type { App } from 'vue'
 import PrimeVue from 'primevue/config'
+import Portal from 'primevue/portal'
+
+/**
+ * Make PrimeVue overlays render inside the shadow root by default.
+ *
+ * Every PrimeVue overlay (Dialog, Drawer, Select, Popover, Menu, …) teleports
+ * through the ONE shared `primevue/portal`, whose `appendTo` default is `'body'`.
+ * Inside a web component that escapes the shadow root, so the module's
+ * shadow-scoped CSS no longer styles the overlay. Most components expose
+ * `appendTo` (an app can pass `'self'`), but `Drawer` hard-wires its Portal with
+ * no `appendTo`, so it ALWAYS escapes — and PrimeVue 4 has no global config for
+ * this. Flipping the shared Portal's default to `'self'` fixes every overlay at
+ * once; the components that pass their own `appendTo` are unaffected.
+ *
+ * Must run before the first overlay renders (install time is early enough — Vue
+ * normalizes a component's prop defaults lazily on first instantiation).
+ */
+function keepOverlaysInShadowRoot(): void {
+  const appendTo = (Portal as any)?.props?.appendTo
+  if (appendTo && appendTo.default === 'body')
+    appendTo.default = 'self'
+}
 
 export const PrimeVuePlugin = {
-  install: (app: App) => app.use(PrimeVue, { theme: 'none' }),
+  install: (app: App) => {
+    keepOverlaysInShadowRoot()
+    app.use(PrimeVue, { theme: 'none' })
+  },
 }
 
 export default PrimeVuePlugin

package/theme-config.css

@@ -129,6 +129,26 @@
     --p-surface-900: #171717;
     --p-surface-950: #0a0a0a;
     --p-content-border-radius: 6px;
+
+    /* Typography tokens — one grammar for every font role (heading/body/mono):
+       --p-font-<role>-{family|scale|line-height|letter-spacing|stretch|variation-settings}.
+       Scales multiply each role's base sizes; defaults are visually inert.
+       @font-face-level control (which weights load, size-adjust, ascent/descent
+       overrides) is a facade concern: the `fonts` theming param compiles to
+       generated @font-face CSS — these vars only steer how loaded fonts render.
+       Mode-independent: declared once, no dark remap. */
+    --p-font-heading-family: var(--v-font-family-head, Arial);
+    --p-font-heading-scale: 1;
+    --p-font-heading-line-height: 1.5;
+    --p-font-heading-letter-spacing: normal;
+    --p-font-heading-stretch: normal;
+    --p-font-heading-variation-settings: normal;
+    --p-font-body-scale: 1;
+    --p-font-body-line-height: 1.5;
+    --p-font-body-letter-spacing: normal;
+    --p-font-body-stretch: normal;
+    --p-font-body-variation-settings: normal;
+    --p-font-mono-family: ui-monospace;
 }
 
 /* Light (default semantic mapping) */
@@ -137,6 +157,37 @@
     --p-primary-contrast-color: var(--p-surface-0);
     --p-primary-hover-color: var(--p-primary-600);
     --p-primary-active-color: var(--p-primary-700);
+    /* Every color family carries the same four semantic aliases as primary
+       (-color / -contrast-color / -hover-color / -active-color), remapped per
+       mode. One grammar, zero exceptions — see tokens.json. */
+    --p-secondary-color: var(--p-secondary-500);
+    --p-secondary-contrast-color: var(--p-surface-0);
+    --p-secondary-hover-color: var(--p-secondary-600);
+    --p-secondary-active-color: var(--p-secondary-700);
+    --p-danger-color: var(--p-danger-500);
+    --p-danger-contrast-color: var(--p-surface-0);
+    --p-danger-hover-color: var(--p-danger-600);
+    --p-danger-active-color: var(--p-danger-700);
+    --p-success-color: var(--p-success-500);
+    --p-success-contrast-color: var(--p-surface-0);
+    --p-success-hover-color: var(--p-success-600);
+    --p-success-active-color: var(--p-success-700);
+    --p-warn-color: var(--p-warn-500);
+    --p-warn-contrast-color: var(--p-surface-0);
+    --p-warn-hover-color: var(--p-warn-600);
+    --p-warn-active-color: var(--p-warn-700);
+    --p-info-color: var(--p-info-500);
+    --p-info-contrast-color: var(--p-surface-0);
+    --p-info-hover-color: var(--p-info-600);
+    --p-info-active-color: var(--p-info-700);
+    --p-help-color: var(--p-help-500);
+    --p-help-contrast-color: var(--p-surface-0);
+    --p-help-hover-color: var(--p-help-600);
+    --p-help-active-color: var(--p-help-700);
+    --p-accent-color: var(--p-accent-500);
+    --p-accent-contrast-color: var(--p-surface-0);
+    --p-accent-hover-color: var(--p-accent-600);
+    --p-accent-active-color: var(--p-accent-700);
     --p-content-border-color: var(--p-surface-200);
     --p-content-hover-background: var(--p-surface-100);
     --p-content-hover-color: var(--p-surface-800);
@@ -202,6 +253,35 @@
         --p-primary-contrast-color: var(--p-surface-900);
         --p-primary-hover-color: var(--p-primary-300);
         --p-primary-active-color: var(--p-primary-200);
+        /* Family aliases, dark remap — mirrors primary's 400/300/200 pattern. */
+        --p-secondary-color: var(--p-secondary-400);
+        --p-secondary-contrast-color: var(--p-surface-900);
+        --p-secondary-hover-color: var(--p-secondary-300);
+        --p-secondary-active-color: var(--p-secondary-200);
+        --p-danger-color: var(--p-danger-400);
+        --p-danger-contrast-color: var(--p-surface-900);
+        --p-danger-hover-color: var(--p-danger-300);
+        --p-danger-active-color: var(--p-danger-200);
+        --p-success-color: var(--p-success-400);
+        --p-success-contrast-color: var(--p-surface-900);
+        --p-success-hover-color: var(--p-success-300);
+        --p-success-active-color: var(--p-success-200);
+        --p-warn-color: var(--p-warn-400);
+        --p-warn-contrast-color: var(--p-surface-900);
+        --p-warn-hover-color: var(--p-warn-300);
+        --p-warn-active-color: var(--p-warn-200);
+        --p-info-color: var(--p-info-400);
+        --p-info-contrast-color: var(--p-surface-900);
+        --p-info-hover-color: var(--p-info-300);
+        --p-info-active-color: var(--p-info-200);
+        --p-help-color: var(--p-help-400);
+        --p-help-contrast-color: var(--p-surface-900);
+        --p-help-hover-color: var(--p-help-300);
+        --p-help-active-color: var(--p-help-200);
+        --p-accent-color: var(--p-accent-400);
+        --p-accent-contrast-color: var(--p-surface-900);
+        --p-accent-hover-color: var(--p-accent-300);
+        --p-accent-active-color: var(--p-accent-200);
         --p-content-border-color: var(--p-surface-700);
         --p-content-hover-background: var(--p-surface-800);
         --p-content-hover-color: var(--p-surface-0);
@@ -253,6 +333,35 @@
     --p-primary-contrast-color: var(--p-surface-900);
     --p-primary-hover-color: var(--p-primary-300);
     --p-primary-active-color: var(--p-primary-200);
+    /* Family aliases, dark remap — mirrors primary's 400/300/200 pattern. */
+    --p-secondary-color: var(--p-secondary-400);
+    --p-secondary-contrast-color: var(--p-surface-900);
+    --p-secondary-hover-color: var(--p-secondary-300);
+    --p-secondary-active-color: var(--p-secondary-200);
+    --p-danger-color: var(--p-danger-400);
+    --p-danger-contrast-color: var(--p-surface-900);
+    --p-danger-hover-color: var(--p-danger-300);
+    --p-danger-active-color: var(--p-danger-200);
+    --p-success-color: var(--p-success-400);
+    --p-success-contrast-color: var(--p-surface-900);
+    --p-success-hover-color: var(--p-success-300);
+    --p-success-active-color: var(--p-success-200);
+    --p-warn-color: var(--p-warn-400);
+    --p-warn-contrast-color: var(--p-surface-900);
+    --p-warn-hover-color: var(--p-warn-300);
+    --p-warn-active-color: var(--p-warn-200);
+    --p-info-color: var(--p-info-400);
+    --p-info-contrast-color: var(--p-surface-900);
+    --p-info-hover-color: var(--p-info-300);
+    --p-info-active-color: var(--p-info-200);
+    --p-help-color: var(--p-help-400);
+    --p-help-contrast-color: var(--p-surface-900);
+    --p-help-hover-color: var(--p-help-300);
+    --p-help-active-color: var(--p-help-200);
+    --p-accent-color: var(--p-accent-400);
+    --p-accent-contrast-color: var(--p-surface-900);
+    --p-accent-hover-color: var(--p-accent-300);
+    --p-accent-active-color: var(--p-accent-200);
     --p-content-border-color: var(--p-surface-700);
     --p-content-hover-background: var(--p-surface-800);
     --p-content-hover-color: var(--p-surface-0);
@@ -303,6 +412,37 @@
     --p-primary-contrast-color: var(--p-surface-0);
     --p-primary-hover-color: var(--p-primary-600);
     --p-primary-active-color: var(--p-primary-700);
+    /* Every color family carries the same four semantic aliases as primary
+       (-color / -contrast-color / -hover-color / -active-color), remapped per
+       mode. One grammar, zero exceptions — see tokens.json. */
+    --p-secondary-color: var(--p-secondary-500);
+    --p-secondary-contrast-color: var(--p-surface-0);
+    --p-secondary-hover-color: var(--p-secondary-600);
+    --p-secondary-active-color: var(--p-secondary-700);
+    --p-danger-color: var(--p-danger-500);
+    --p-danger-contrast-color: var(--p-surface-0);
+    --p-danger-hover-color: var(--p-danger-600);
+    --p-danger-active-color: var(--p-danger-700);
+    --p-success-color: var(--p-success-500);
+    --p-success-contrast-color: var(--p-surface-0);
+    --p-success-hover-color: var(--p-success-600);
+    --p-success-active-color: var(--p-success-700);
+    --p-warn-color: var(--p-warn-500);
+    --p-warn-contrast-color: var(--p-surface-0);
+    --p-warn-hover-color: var(--p-warn-600);
+    --p-warn-active-color: var(--p-warn-700);
+    --p-info-color: var(--p-info-500);
+    --p-info-contrast-color: var(--p-surface-0);
+    --p-info-hover-color: var(--p-info-600);
+    --p-info-active-color: var(--p-info-700);
+    --p-help-color: var(--p-help-500);
+    --p-help-contrast-color: var(--p-surface-0);
+    --p-help-hover-color: var(--p-help-600);
+    --p-help-active-color: var(--p-help-700);
+    --p-accent-color: var(--p-accent-500);
+    --p-accent-contrast-color: var(--p-surface-0);
+    --p-accent-hover-color: var(--p-accent-600);
+    --p-accent-active-color: var(--p-accent-700);
     --p-content-border-color: var(--p-surface-200);
     --p-content-hover-background: var(--p-surface-100);
     --p-content-hover-color: var(--p-surface-800);