@uxelle/skills 0.2.0-beta.2

package/skills/uxelle-design-harness/tokens.md

@@ -0,0 +1,101 @@
+# The variable foundation
+
+Every generated surface is styled with **real** `--uxl-*` variables from the
+loaded theme. This file is the canonical reference for the token families you use
+in app and recipe CSS. Confirm a name here before writing custom CSS.
+
+Three rules hold everywhere:
+
+- **Never invent** `--uxl-*` names. The spacing ramp uses sequential indices
+  (`medium-10` exists, `large-10` does not) — size band must match the index.
+- **Never** use `var(--token, fallback)`. A missing variable must fail visibly so
+  the theme gets fixed, not masked.
+- **Never** use `--uxl-component-*` in app or recipe CSS. Those belong inside
+  components; use the switcher/layout/radius families below instead.
+
+## Color (switcher roles)
+
+Style themeable surfaces with these role tokens. They resolve to whatever palette
+is active for the region (see palette selection and `data-color-switcher` in
+[how-to-color.md](how-to-color.md)).
+
+| Role | Token |
+|------|-------|
+| Page / region background | `--uxl-color-switcher-background` |
+| Body text | `--uxl-color-switcher-text` |
+| Headlines | `--uxl-color-switcher-headline` |
+| Borders / rules | `--uxl-color-switcher-stroke` |
+| Large / full-bleed surface (banner, panel, open accordion) | `--uxl-color-switcher-component-surface-1` |
+| Small component surface (badge, bubble, chip) | `--uxl-color-switcher-component-surface-2` |
+| Brand accent | `--uxl-color-switcher-brand` |
+| Primary button fill | `--uxl-color-switcher-button-fill` |
+| Text on filled button | `--uxl-color-switcher-button-text-on-fill` |
+| Interactive icons / focus rings | `--uxl-color-switcher-interactive-icon` |
+
+Never hardcode hex/rgb for themeable UI. Palette selection (`default`,
+`default-subtle`, status, `brand-1..4`) is covered in [how-to-color.md](how-to-color.md).
+
+## Spacing (layout ramp)
+
+Stacks on `Layout` / `A2uiLayout` pass `0` or `var(--uxl-theme-layout-spacing-*)`
+on `gap` / padding / margin. The full 0-16 ramp and how to choose a step is in
+[spacing-steps.md](spacing-steps.md). Set `display="flex"` (or `grid`) when using `gap`.
+
+## Page chrome (React app/page body)
+
+For the page body only — not A2UI. Do not invent `uxl-breakpoint-*` (singular).
+Usage in [how-to-page-layout.md](how-to-page-layout.md).
+
+- `--uxl-breakpoints-max-container-width` — cap the body column
+- `--uxl-breakpoints-margin` — padding around the body
+- `--uxl-breakpoints-gutter` — gap between columns / `fr` tracks
+
+Breakpoint bounds (read-only, for the rare JS switch) are exposed as
+`--uxl-theme-layout-{mobile,tablet,desktop,desktop-plus}-screen-width-{min,max}`,
+and the active band as `--uxl-breakpoints-screen-width-{min,max}`. Reference these
+names — never hardcode their px values. See [how-to-page-layout.md](how-to-page-layout.md).
+
+## Radius
+
+Prefix `--uxl-theme-radius-`: `xs` | `sm` | `md` | `lg` | `xlg` | `round`.
+There is no `--uxl-theme-radius-full` — use `round` for pills and circles.
+
+## Elevation
+
+There is **no** single `--uxl-theme-elevation-depth-N` variable. Prefer `Card` /
+`ProductCard` for elevated surfaces rather than composing shadows by hand. When you
+must, compose a `box-shadow` from levels `1`-`3` at depths `1`-`4`:
+
+- `--uxl-theme-elevation-depth-{depth}-level-{level}-x` (and `-y`, `-blur`, `-spread`, `-color`)
+
+## Typography
+
+Render copy with the `Text` component (`type="Display Small"`, `Body Medium`,
+`Button`, …) and its `as` prop — never set font-size in app CSS. Font-family
+variables exist for custom chrome only:
+
+- `--uxl-component-text-font-family-display`
+- `--uxl-component-text-font-family-body`
+
+## Component tokens
+
+`--uxl-component-<component>-*` tokens style a specific component from inside that
+component. Do not reach for them in app/recipe CSS; use the switcher and layout
+families above.
+
+## Anti-patterns
+
+- Inventing `large-10`, `radius-full`, `surface-container-low`, or
+  `uxl-breakpoint-gutter` (singular) instead of `--uxl-breakpoints-gutter`.
+- `var(--uxl-theme-layout-spacing-medium-8, 16px)` fallbacks.
+- Hardcoding `1120px` / `1600px` for the page column (use
+  `--uxl-breakpoints-max-container-width`; a one-column form/settings page may use
+  `600px`).
+- Hardcoding hex, font-family, or breakpoint px anywhere in app CSS.
+- Assuming Material "size = big number" naming instead of the sequential index rule.
+
+## Verify a token exists
+
+Check the family here (and [spacing-steps.md](spacing-steps.md) for the ramp). If a
+variable is missing at runtime it will be visibly absent — fix the theme, do not
+invent a name or add a fallback.