@stacksjs/components 0.2.176 → 0.2.177

package/dist/index.js

@@ -1,11 +1,11 @@
 // @bun
-// ../../../../../../../tmp/stx-components-build-aYbHGJ/stubs/stub-0.js
+// ../../../../../../../tmp/stx-components-build-sPFoYf/stubs/stub-0.js
 var stub_0_default = { __stx: true, src: "./components/CodeBlock.stx" };
-// ../../../../../../../tmp/stx-components-build-aYbHGJ/stubs/stub-1.js
+// ../../../../../../../tmp/stx-components-build-sPFoYf/stubs/stub-1.js
 var stub_1_default = { __stx: true, src: "./components/Footer.stx" };
-// ../../../../../../../tmp/stx-components-build-aYbHGJ/stubs/stub-2.js
+// ../../../../../../../tmp/stx-components-build-sPFoYf/stubs/stub-2.js
 var stub_2_default = { __stx: true, src: "./components/Hero.stx" };
-// ../../../../../../../tmp/stx-components-build-aYbHGJ/stubs/stub-3.js
+// ../../../../../../../tmp/stx-components-build-sPFoYf/stubs/stub-3.js
 var stub_3_default = { __stx: true, src: "./components/Installation.stx" };
 // src/composables/useCopyCode.ts
 function useCopyCode(options) {
@@ -542,24 +542,54 @@ function useIsDarkMode() {
 function usePrefersReducedMotion() {
   return useMediaQuery(Breakpoints.reducedMotion);
 }
+// src/theme/index.ts
+var THEMED_FAMILIES = ["gray", "neutral", "slate", "zinc", "red", "green", "yellow", "blue", "indigo"];
+var SHADE_VAR_PREFIX = "--stx-color";
+function cssVar(name, fallback) {
+  return fallback === undefined ? `var(${name})` : `var(${name}, ${fallback})`;
+}
+function stxThemePreset(defaults = {}) {
+  const palette = {};
+  for (const family of THEMED_FAMILIES) {
+    const shades = defaults[family];
+    if (!shades || typeof shades === "string")
+      continue;
+    const themed = {};
+    for (const [shade, value] of Object.entries(shades))
+      themed[shade] = cssVar(`${SHADE_VAR_PREFIX}-${family}-${shade}`, value);
+    palette[family] = themed;
+  }
+  return palette;
+}
+function themeVariableNames(defaults = {}) {
+  const names = [];
+  for (const family of THEMED_FAMILIES) {
+    const shades = defaults[family];
+    if (!shades || typeof shades === "string")
+      continue;
+    for (const shade of Object.keys(shades))
+      names.push(`${SHADE_VAR_PREFIX}-${family}-${shade}`);
+  }
+  return names;
+}
 // src/ui/accordion/Accordion.stx
-var Accordion_default = "./Accordion-pt8j917s.stx";
+var Accordion_default = "./Accordion-8tv78bh9.stx";
 // src/ui/accordion/AccordionItem.stx
-var AccordionItem_default = "./AccordionItem-hbhzx63p.stx";
+var AccordionItem_default = "./AccordionItem-7bd3ga36.stx";
 // src/ui/audio/Audio.stx
-var Audio_default = "./Audio-hjywk3qc.stx";
+var Audio_default = "./Audio-y0sgq50z.stx";
 // src/ui/auth/Login.stx
-var Login_default = "./Login-gepemsth.stx";
+var Login_default = "./Login-2cp65d41.stx";
 // src/ui/auth/Signup.stx
-var Signup_default = "./Signup-hxm5hwkr.stx";
+var Signup_default = "./Signup-cbncrtvd.stx";
 // src/ui/auth/TwoFactorChallenge.stx
-var TwoFactorChallenge_default = "./TwoFactorChallenge-y5m3nk79.stx";
+var TwoFactorChallenge_default = "./TwoFactorChallenge-y7n4yrk9.stx";
 // src/ui/avatar/Avatar.stx
-var Avatar_default = "./Avatar-h3jmwcq0.stx";
+var Avatar_default = "./Avatar-rjvwnskf.stx";
 // src/ui/badge/Badge.stx
-var Badge_default = "./Badge-k8dy3d53.stx";
+var Badge_default = "./Badge-k52qmxcm.stx";
 // src/ui/breadcrumb/Breadcrumb.stx
-var Breadcrumb_default = "./Breadcrumb-7f7s4d02.stx";
+var Breadcrumb_default = "./Breadcrumb-sy5taqsn.stx";
 // src/utils/error-handling.ts
 import process from "process";
 var DOCS_BASE_URL = "https://stacksjs.com/components";
@@ -899,7 +929,7 @@ function warnProp(value, validator, name = "value") {
 }
 
 // src/ui/button/Button.stx
-var Button_default = "./Button-1vknasy3.stx";
+var Button_default = "./Button-wrwmnfpf.stx";
 
 // src/ui/button/index.ts
 var buttonPropSchema = {
@@ -929,11 +959,11 @@ function validateSize(size) {
   }
 }
 // src/ui/calendar/Calendar.stx
-var Calendar_default = "./Calendar-reny0et7.stx";
+var Calendar_default = "./Calendar-gjjhhfnt.stx";
 // src/ui/card/Card.stx
-var Card_default = "./Card-c1g1fd1w.stx";
+var Card_default = "./Card-473a02fy.stx";
 // src/ui/checkbox/Checkbox.stx
-var Checkbox_default = "./Checkbox-aqmq4cqv.stx";
+var Checkbox_default = "./Checkbox-2s2a7n4h.stx";
 // src/ui/combobox/Combobox.stx
 var Combobox_default = "./Combobox-fdkr6cdq.stx";
 // src/ui/combobox/ComboboxButton.stx
@@ -941,35 +971,35 @@ var ComboboxButton_default = "./ComboboxButton-g76stp1e.stx";
 // src/ui/combobox/ComboboxInput.stx
 var ComboboxInput_default = "./ComboboxInput-z1293bbh.stx";
 // src/ui/combobox/ComboboxOption.stx
-var ComboboxOption_default = "./ComboboxOption-hmxt3gte.stx";
+var ComboboxOption_default = "./ComboboxOption-6yh7xk7q.stx";
 // src/ui/combobox/ComboboxOptions.stx
 var ComboboxOptions_default = "./ComboboxOptions-sq5360ae.stx";
 // src/ui/command-palette/CommandPalette.stx
 var CommandPalette_default = "./CommandPalette-36mxf05w.stx";
 // src/ui/command-palette/CommandPaletteItem.stx
-var CommandPaletteItem_default = "./CommandPaletteItem-mvk6q7a2.stx";
+var CommandPaletteItem_default = "./CommandPaletteItem-chdw0070.stx";
 // src/ui/dialog/Dialog.stx
 var Dialog_default = "./Dialog-y5rz2vrq.stx";
 // src/ui/dialog/DialogBackdrop.stx
 var DialogBackdrop_default = "./DialogBackdrop-rxax3sec.stx";
 // src/ui/dialog/DialogDescription.stx
-var DialogDescription_default = "./DialogDescription-76prd1m2.stx";
+var DialogDescription_default = "./DialogDescription-gth4c2kx.stx";
 // src/ui/dialog/DialogPanel.stx
 var DialogPanel_default = "./DialogPanel-44d8jeqy.stx";
 // src/ui/dialog/DialogTitle.stx
 var DialogTitle_default = "./DialogTitle-x0r6k8x9.stx";
 // src/ui/drawer/Drawer.stx
-var Drawer_default = "./Drawer-hrz7qcyp.stx";
+var Drawer_default = "./Drawer-jgepqr9j.stx";
 // src/ui/dropdown/Dropdown.stx
 var Dropdown_default = "./Dropdown-vvhemtc0.stx";
 // src/ui/dropdown/DropdownButton.stx
 var DropdownButton_default = "./DropdownButton-wcz67dxy.stx";
 // src/ui/dropdown/DropdownItem.stx
-var DropdownItem_default = "./DropdownItem-c7rz08e5.stx";
+var DropdownItem_default = "./DropdownItem-d8ht2bp5.stx";
 // src/ui/dropdown/DropdownItems.stx
 var DropdownItems_default = "./DropdownItems-1sxnd5qn.stx";
 // src/ui/form/Form.stx
-var Form_default = "./Form-bpnpbymb.stx";
+var Form_default = "./Form-vbag14t1.stx";
 
 // src/ui/form/index.ts
 var formPropSchema = {
@@ -989,13 +1019,13 @@ var Image_default = "./Image-yhxcvgzs.stx";
 // src/ui/input/EmailInput.stx
 var EmailInput_default = "./EmailInput-vak3kkmk.stx";
 // src/ui/input/NumberInput.stx
-var NumberInput_default = "./NumberInput-g41gmd2c.stx";
+var NumberInput_default = "./NumberInput-j9p5bm5y.stx";
 // src/ui/input/PasswordInput.stx
-var PasswordInput_default = "./PasswordInput-4rsq1gwb.stx";
+var PasswordInput_default = "./PasswordInput-4qykq1dz.stx";
 // src/ui/input/SearchInput.stx
 var SearchInput_default = "./SearchInput-pdx7agn0.stx";
 // src/ui/input/TextInput.stx
-var TextInput_default = "./TextInput-g0vaz0pe.stx";
+var TextInput_default = "./TextInput-cefyyprt.stx";
 
 // src/ui/input/index.ts
 var baseInputPropSchema = {
@@ -1092,23 +1122,23 @@ var ListboxButton_default = "./ListboxButton-keb8gm0q.stx";
 // src/ui/listbox/ListboxLabel.stx
 var ListboxLabel_default = "./ListboxLabel-7mymt1b8.stx";
 // src/ui/listbox/ListboxOption.stx
-var ListboxOption_default = "./ListboxOption-e0dtv1gc.stx";
+var ListboxOption_default = "./ListboxOption-4j070101.stx";
 // src/ui/listbox/ListboxOptions.stx
 var ListboxOptions_default = "./ListboxOptions-ejkatcfg.stx";
 // src/ui/navigator/Navigator.stx
-var Navigator_default = "./Navigator-rk2a5wvk.stx";
+var Navigator_default = "./Navigator-smpa7my4.stx";
 // src/ui/notification/Notification.stx
 var Notification_default = "./Notification-03vfh3k6.stx";
 // src/ui/pagination/Pagination.stx
-var Pagination_default = "./Pagination-wtgxmzey.stx";
+var Pagination_default = "./Pagination-jbcjrfcs.stx";
 // src/ui/payment/Checkout.stx
-var Checkout_default = "./Checkout-agt0ngpw.stx";
+var Checkout_default = "./Checkout-22wh3s22.stx";
 // src/ui/payment/DefaultPaymentMethod.stx
-var DefaultPaymentMethod_default = "./DefaultPaymentMethod-shhf6aap.stx";
+var DefaultPaymentMethod_default = "./DefaultPaymentMethod-6qrem3sg.stx";
 // src/ui/payment/PaymentMethods.stx
-var PaymentMethods_default = "./PaymentMethods-x4vrx9yb.stx";
+var PaymentMethods_default = "./PaymentMethods-2xy66bwk.stx";
 // src/ui/payment/SubscriptionCheckout.stx
-var SubscriptionCheckout_default = "./SubscriptionCheckout-zy2ycrmw.stx";
+var SubscriptionCheckout_default = "./SubscriptionCheckout-7fdkwf04.stx";
 // src/ui/popover/Popover.stx
 var Popover_default = "./Popover-et2q44m7.stx";
 // src/ui/popover/PopoverButton.stx
@@ -1118,19 +1148,19 @@ var PopoverPanel_default = "./PopoverPanel-054yh38h.stx";
 // src/ui/portal/Portal.stx
 var Portal_default = "./Portal-1vf14s4x.stx";
 // src/ui/progress/Progress.stx
-var Progress_default = "./Progress-9dhakbh4.stx";
+var Progress_default = "./Progress-4h7dytq5.stx";
 // src/ui/radio/Radio.stx
-var Radio_default = "./Radio-djtb5dpc.stx";
+var Radio_default = "./Radio-ccm07b2m.stx";
 // src/ui/radio-group/RadioGroup.stx
-var RadioGroup_default = "./RadioGroup-qxmnm3xm.stx";
+var RadioGroup_default = "./RadioGroup-eerw9gq7.stx";
 // src/ui/radio-group/RadioGroupDescription.stx
-var RadioGroupDescription_default = "./RadioGroupDescription-yej78fak.stx";
+var RadioGroupDescription_default = "./RadioGroupDescription-z34r9avr.stx";
 // src/ui/radio-group/RadioGroupLabel.stx
 var RadioGroupLabel_default = "./RadioGroupLabel-7mymt1b8.stx";
 // src/ui/radio-group/RadioGroupOption.stx
-var RadioGroupOption_default = "./RadioGroupOption-s1d6r221.stx";
+var RadioGroupOption_default = "./RadioGroupOption-7pq7rw84.stx";
 // src/ui/select/Select.stx
-var Select_default = "./Select-1vnd0brz.stx";
+var Select_default = "./Select-zt72gg1e.stx";
 // src/ui/sidebar/Sidebar.stx
 var Sidebar_default = "./Sidebar-v7ecx5gs.stx";
 // src/ui/sidebar/SidebarFooter.stx
@@ -1138,9 +1168,9 @@ var SidebarFooter_default = "./SidebarFooter-s7skj92y.stx";
 // src/ui/sidebar/SidebarHeader.stx
 var SidebarHeader_default = "./SidebarHeader-34bf4mm8.stx";
 // src/ui/sidebar/SidebarItem.stx
-var SidebarItem_default = "./SidebarItem-2a6n0be3.stx";
+var SidebarItem_default = "./SidebarItem-5v8atp7p.stx";
 // src/ui/sidebar/SidebarPinned.stx
-var SidebarPinned_default = "./SidebarPinned-tvj28bm0.stx";
+var SidebarPinned_default = "./SidebarPinned-rq05nrtd.stx";
 // src/ui/sidebar/SidebarSection.stx
 var SidebarSection_default = "./SidebarSection-zd9z35ch.stx";
 // src/ui/sidebar/SidebarSpace.stx
@@ -1444,13 +1474,13 @@ function spaceTintPayload(spaces) {
   return spaces.map((space) => space.tint);
 }
 // src/ui/skeleton/Skeleton.stx
-var Skeleton_default = "./Skeleton-v1pwa8nr.stx";
+var Skeleton_default = "./Skeleton-wtwb97xd.stx";
 // src/ui/spinner/Spinner.stx
-var Spinner_default = "./Spinner-7dahavkd.stx";
+var Spinner_default = "./Spinner-ypya5tt2.stx";
 // src/ui/stepper/Stepper.stx
 var Stepper_default = "./Stepper-rgbk76hd.stx";
 // src/ui/stepper/StepperStep.stx
-var StepperStep_default = "./StepperStep-wxgembat.stx";
+var StepperStep_default = "./StepperStep-3ahq4d9m.stx";
 // src/ui/storage/index.ts
 class StorageManager {
   storage;
@@ -1695,37 +1725,37 @@ function createStorage(type = "local", namespace) {
   return new StorageManager(type, namespace);
 }
 // src/ui/switch/Switch.stx
-var Switch_default = "./Switch-p1bcr9ks.stx";
+var Switch_default = "./Switch-hdta55a8.stx";
 // src/ui/table/Table.stx
-var Table_default = "./Table-6cx8az9h.stx";
+var Table_default = "./Table-0mc3fdek.stx";
 // src/ui/table/TableBody.stx
-var TableBody_default = "./TableBody-wf6t13j9.stx";
+var TableBody_default = "./TableBody-drxyz5jh.stx";
 // src/ui/table/TableCell.stx
-var TableCell_default = "./TableCell-ntx0edbn.stx";
+var TableCell_default = "./TableCell-8swtcq8s.stx";
 // src/ui/table/TableHead.stx
-var TableHead_default = "./TableHead-3k4hnm2k.stx";
+var TableHead_default = "./TableHead-e9xvjx2j.stx";
 // src/ui/table/TableHeader.stx
-var TableHeader_default = "./TableHeader-0eyzbqpz.stx";
+var TableHeader_default = "./TableHeader-sxc77b4d.stx";
 // src/ui/table/TableRow.stx
-var TableRow_default = "./TableRow-z09p2ebf.stx";
+var TableRow_default = "./TableRow-xd542nvb.stx";
 // src/ui/tabs/TabPanel.stx
 var TabPanel_default = "./TabPanel-5htevsq6.stx";
 // src/ui/tabs/Tabs.stx
-var Tabs_default = "./Tabs-79brys99.stx";
+var Tabs_default = "./Tabs-b4xsba1w.stx";
 // src/ui/teleport/Teleport.stx
 var Teleport_default = "./Teleport-tsx4bt4n.stx";
 // src/ui/textarea/Textarea.stx
-var Textarea_default = "./Textarea-96kawv5c.stx";
+var Textarea_default = "./Textarea-xcdym703.stx";
 // src/ui/tooltip/Tooltip.stx
 var Tooltip_default = "./Tooltip-y61h04gp.stx";
 // src/ui/transition/Transition.stx
 var Transition_default = "./Transition-7smenaz8.stx";
 // src/ui/video/Video.stx
-var Video_default = "./Video-84j4pv6h.stx";
+var Video_default = "./Video-a0aeyexv.stx";
 // src/ui/virtual-list/VirtualList.stx
 var VirtualList_default = "./VirtualList-fa7v5a3h.stx";
 // src/ui/virtual-table/VirtualTable.stx
-var VirtualTable_default = "./VirtualTable-f9crbfjr.stx";
+var VirtualTable_default = "./VirtualTable-jvm1784g.stx";
 // src/utils/accessibility.ts
 var idCounter = 0;
 function generateId(prefix = "a11y") {
@@ -3994,11 +4024,13 @@ export {
   useCopyCode,
   useClickOutside,
   useBreakpoint,
+  themeVariableNames,
   themeToCSSProperties,
   themePresets,
   textInputPropSchema,
   tc,
   t,
+  stxThemePreset,
   storage,
   staggerAnimation,
   spaceTintVars,
@@ -4141,6 +4173,7 @@ export {
   TableBody_default as TableBody,
   Table_default as Table,
   TabPanel_default as TabPanel,
+  THEMED_FAMILIES,
   Switch_default as Switch,
   SubscriptionCheckout_default as SubscriptionCheckout,
   StorageManager,
@@ -4160,6 +4193,7 @@ export {
   Sidebar_default as Sidebar,
   Select_default as Select,
   SearchInput_default as SearchInput,
+  SHADE_VAR_PREFIX,
   RadioGroupOption_default as RadioGroupOption,
   RadioGroupLabel_default as RadioGroupLabel,
   RadioGroupDescription_default as RadioGroupDescription,

package/dist/theme/index.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Build the palette fragment.
+ *
+ * @param defaults - Crosswind's default `theme.colors`. Pass the one your
+ * project resolves; omitted, the returned entries carry no fallback, which is
+ * only useful if you intend to define every variable yourself.
+ */
+export declare function stxThemePreset(defaults?: Palette): Palette;
+/**
+ * Every variable the preset reads, in declaration order.
+ *
+ * The issue asked for "a documented list of the variables each family reads",
+ * and a list generated from the same source as the palette cannot disagree with
+ * it. Useful for emitting a starter stylesheet or documenting the surface.
+ */
+export declare function themeVariableNames(defaults?: Palette): string[];
+/**
+ * Colour families the components actually draw with.
+ *
+ * Deliberately not "every family in the palette". A variable per shade of every
+ * colour would be several hundred declarations an app has no use for, and the
+ * point is a list someone can read. `red`, `green` and `yellow` are here
+ * because they carry the status roles below.
+ */
+export declare const THEMED_FAMILIES: readonly ['gray', 'neutral', 'slate', 'zinc', 'red', 'green', 'yellow', 'blue', 'indigo'];
+/** Prefix for the per-shade variables, e.g. `--stx-color-gray-600`. */
+export declare const SHADE_VAR_PREFIX: '--stx-color';
+/**
+ * A seam for an app's own theme (stacksjs/stx#1930).
+ *
+ * 62 of the 91 components name Tailwind palette shades directly —
+ * `bg-gray-100`, `text-gray-600`, `ring-indigo-600`. Dark mode is handled, via
+ * the `dark:` variant. What was not handled is an app with its own palette: it
+ * installs `<Button>` and gets `bg-gray-100`, which matches nothing around it.
+ *
+ * ## What already works, without this module
+ *
+ * A project's `crosswind.config.ts` `theme.colors` **deep-merges** over the base
+ * palette, and stx generates CSS by scanning the rendered page — so redefining
+ * a shade re-themes every component that names it, with no component edits:
+ *
+ * ```ts
+ * // crosswind.config.ts
+ * export default { theme: { colors: { gray: { 600: '#3f3f46' } } } }
+ * ```
+ *
+ * Shades you do not name keep their defaults. That is a build-time seam and it
+ * is the right one for a fixed brand palette.
+ *
+ * ## What this module adds
+ *
+ * A **runtime** seam, and **semantic** names.
+ *
+ * `stxThemePreset()` returns a `theme.colors` fragment in which every themed
+ * shade resolves through a CSS custom property with today's value as the
+ * fallback. Spread it into your crosswind config and nothing changes visually;
+ * set a variable and every component follows, without a rebuild:
+ *
+ * ROLE tokens are not here. `packages/stx/src/theme-tokens.ts` puts those in the
+ * base theme, so they resolve in every app with no opt-in — a component saying
+ * `text-fg-muted` cannot depend on a config change. A second list of role names
+ * living here would disagree with that one, which is the failure this module
+ * exists to avoid rather than to introduce.
+ *
+ * ```ts
+ * // crosswind.config.ts
+ * import { stxThemePreset } from '@stacksjs/components/theme'
+ * export default { theme: { colors: stxThemePreset() } }
+ * ```
+ *
+ * ```css
+ * :root { --stx-color-gray-600: #52525b; }
+ * .dark { --stx-color-gray-600: #a1a1aa; }
+ * ```
+ *
+ * The fallbacks are read from crosswind's own default palette rather than
+ * copied, so this cannot drift from the values the components are drawn
+ * against — a hand-copied table is the failure mode this whole file exists to
+ * remove, and duplicating it here would reintroduce it one level up.
+ *
+ * ## The trade this makes
+ *
+ * An opacity modifier on a variable-backed colour compiles to `color-mix()`
+ * rather than a baked `oklch(… / 0.5)`, because the value is not known at build
+ * time. That is why this is opt-in and not the framework default: it is a real
+ * change to the generated CSS, and it is the app's call to make.
+ *
+ * @module theme
+ */
+/** A crosswind palette entry: one colour, or a map of shades. */
+export type PaletteValue = string | Record<string, string>;
+export type Palette = Record<string, PaletteValue>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/components",
   "type": "module",
-  "version": "0.2.176",
+  "version": "0.2.177",
   "description": "A modern component library built with STX, featuring headwind utility classes and TypeScript syntax highlighting.",
   "author": "Chris Breuer <chris@stacksjs.org>",
   "license": "MIT",
@@ -64,8 +64,8 @@
   "dependencies": {
     "@iconify-json/f7": "^1.2.2",
     "@cwcss/crosswind": "^0.2.14",
-    "@stacksjs/stx": "0.2.176",
-    "bun-plugin-stx": "0.2.176",
+    "@stacksjs/stx": "0.2.177",
+    "bun-plugin-stx": "0.2.177",
     "ts-syntax-highlighter": "^0.2.1"
   },
   "devDependencies": {

package/src/index.ts

@@ -6,6 +6,8 @@ export { default as Hero } from './components/Hero.stx'
 export { default as Installation } from './components/Installation.stx'
 // Export composables
 export * from './composables'
+// Theme seam — see src/theme for how an app redirects the components' colours.
+export * from './theme'
 // Export UI components
 export * from './ui/accordion'
 export * from './ui/audio'

package/src/theme/index.ts

@@ -0,0 +1,130 @@
+/**
+ * A seam for an app's own theme (stacksjs/stx#1930).
+ *
+ * 62 of the 91 components name Tailwind palette shades directly —
+ * `bg-gray-100`, `text-gray-600`, `ring-indigo-600`. Dark mode is handled, via
+ * the `dark:` variant. What was not handled is an app with its own palette: it
+ * installs `<Button>` and gets `bg-gray-100`, which matches nothing around it.
+ *
+ * ## What already works, without this module
+ *
+ * A project's `crosswind.config.ts` `theme.colors` **deep-merges** over the base
+ * palette, and stx generates CSS by scanning the rendered page — so redefining
+ * a shade re-themes every component that names it, with no component edits:
+ *
+ * ```ts
+ * // crosswind.config.ts
+ * export default { theme: { colors: { gray: { 600: '#3f3f46' } } } }
+ * ```
+ *
+ * Shades you do not name keep their defaults. That is a build-time seam and it
+ * is the right one for a fixed brand palette.
+ *
+ * ## What this module adds
+ *
+ * A **runtime** seam, and **semantic** names.
+ *
+ * `stxThemePreset()` returns a `theme.colors` fragment in which every themed
+ * shade resolves through a CSS custom property with today's value as the
+ * fallback. Spread it into your crosswind config and nothing changes visually;
+ * set a variable and every component follows, without a rebuild:
+ *
+ * ROLE tokens are not here. `packages/stx/src/theme-tokens.ts` puts those in the
+ * base theme, so they resolve in every app with no opt-in — a component saying
+ * `text-fg-muted` cannot depend on a config change. A second list of role names
+ * living here would disagree with that one, which is the failure this module
+ * exists to avoid rather than to introduce.
+ *
+ * ```ts
+ * // crosswind.config.ts
+ * import { stxThemePreset } from '@stacksjs/components/theme'
+ * export default { theme: { colors: stxThemePreset() } }
+ * ```
+ *
+ * ```css
+ * :root { --stx-color-gray-600: #52525b; }
+ * .dark { --stx-color-gray-600: #a1a1aa; }
+ * ```
+ *
+ * The fallbacks are read from crosswind's own default palette rather than
+ * copied, so this cannot drift from the values the components are drawn
+ * against — a hand-copied table is the failure mode this whole file exists to
+ * remove, and duplicating it here would reintroduce it one level up.
+ *
+ * ## The trade this makes
+ *
+ * An opacity modifier on a variable-backed colour compiles to `color-mix()`
+ * rather than a baked `oklch(… / 0.5)`, because the value is not known at build
+ * time. That is why this is opt-in and not the framework default: it is a real
+ * change to the generated CSS, and it is the app's call to make.
+ *
+ * @module theme
+ */
+
+/** A crosswind palette entry: one colour, or a map of shades. */
+export type PaletteValue = string | Record<string, string>
+export type Palette = Record<string, PaletteValue>
+
+/**
+ * Colour families the components actually draw with.
+ *
+ * Deliberately not "every family in the palette". A variable per shade of every
+ * colour would be several hundred declarations an app has no use for, and the
+ * point is a list someone can read. `red`, `green` and `yellow` are here
+ * because they carry the status roles below.
+ */
+export const THEMED_FAMILIES = ['gray', 'neutral', 'slate', 'zinc', 'red', 'green', 'yellow', 'blue', 'indigo'] as const
+
+/** Prefix for the per-shade variables, e.g. `--stx-color-gray-600`. */
+export const SHADE_VAR_PREFIX = '--stx-color'
+
+/** `var(--name, fallback)`, or `var(--name)` when there is nothing to fall back to. */
+function cssVar(name: string, fallback?: string): string {
+  return fallback === undefined ? `var(${name})` : `var(${name}, ${fallback})`
+}
+
+/**
+ * Build the palette fragment.
+ *
+ * @param defaults - Crosswind's default `theme.colors`. Pass the one your
+ * project resolves; omitted, the returned entries carry no fallback, which is
+ * only useful if you intend to define every variable yourself.
+ */
+export function stxThemePreset(defaults: Palette = {}): Palette {
+  const palette: Palette = {}
+
+  for (const family of THEMED_FAMILIES) {
+    const shades = defaults[family]
+    if (!shades || typeof shades === 'string')
+      continue
+
+    const themed: Record<string, string> = {}
+    for (const [shade, value] of Object.entries(shades))
+      themed[shade] = cssVar(`${SHADE_VAR_PREFIX}-${family}-${shade}`, value)
+
+    palette[family] = themed
+  }
+
+  return palette
+}
+
+/**
+ * Every variable the preset reads, in declaration order.
+ *
+ * The issue asked for "a documented list of the variables each family reads",
+ * and a list generated from the same source as the palette cannot disagree with
+ * it. Useful for emitting a starter stylesheet or documenting the surface.
+ */
+export function themeVariableNames(defaults: Palette = {}): string[] {
+  const names: string[] = []
+
+  for (const family of THEMED_FAMILIES) {
+    const shades = defaults[family]
+    if (!shades || typeof shades === 'string')
+      continue
+    for (const shade of Object.keys(shades))
+      names.push(`${SHADE_VAR_PREFIX}-${family}-${shade}`)
+  }
+
+  return names
+}

package/src/ui/accordion/Accordion.stx

@@ -11,10 +11,10 @@ export const allowMultiple = $props.allowMultiple || false
 export const defaultOpen = $props.defaultOpen || []
 export const className = $props.className || ''
 
-export const accordionClasses = `divide-y divide-gray-200 dark:divide-gray-700 border border-gray-200 dark:border-gray-700 rounded-lg ${className}`.trim()
-export const headerClasses = `w-full flex items-center justify-between px-4 py-3 text-left font-medium text-gray-900 dark:text-gray-100 hover:bg-gray-50 dark:hover:bg-gray-800 transition-colors duration-150 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 dark:focus:ring-offset-gray-900`.trim()
-export const iconClasses = `w-5 h-5 text-gray-500 dark:text-gray-400 transition-transform duration-200`.trim()
-export const contentClasses = `px-4 py-3 text-gray-700 dark:text-gray-300`.trim()
+export const accordionClasses = `divide-y divide-line border border-line rounded-lg ${className}`.trim()
+export const headerClasses = `w-full flex items-center justify-between px-4 py-3 text-left font-medium text-fg hover:bg-surface transition-colors duration-150 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 dark:focus:ring-offset-gray-900`.trim()
+export const iconClasses = `w-5 h-5 text-fg-soft transition-transform duration-200`.trim()
+export const contentClasses = `px-4 py-3 text-fg-strong`.trim()
 export const hasPropItems = Array.isArray(items) && items.length > 0
 </script>
 

package/src/ui/accordion/AccordionItem.stx

@@ -7,9 +7,9 @@
 export const title = $props.title || ''
 export const className = $props.className || ''
 
-const headerClasses = 'w-full flex items-center justify-between px-4 py-3 text-left font-medium text-gray-900 dark:text-gray-100 hover:bg-gray-50 dark:hover:bg-gray-800 transition-colors duration-150 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 dark:focus:ring-offset-gray-900'
-const iconClasses = 'w-5 h-5 text-gray-500 dark:text-gray-400 transition-transform duration-200'
-const contentClasses = 'px-4 py-3 text-gray-700 dark:text-gray-300'
+const headerClasses = 'w-full flex items-center justify-between px-4 py-3 text-left font-medium text-fg hover:bg-surface transition-colors duration-150 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 dark:focus:ring-offset-gray-900'
+const iconClasses = 'w-5 h-5 text-fg-soft transition-transform duration-200'
+const contentClasses = 'px-4 py-3 text-fg-strong'
 </script>
 
 <div data-stx-accordion-item data-title="{{ title }}" class="{{ className }}">

package/src/ui/audio/Audio.stx

@@ -10,13 +10,13 @@ export const showWaveform = $props.showWaveform || false
 export const title = $props.title || ''
 
 export const containerClasses = `relative w-full ${className}`.trim()
-export const audioClasses = 'w-full rounded-md bg-gray-100 dark:bg-gray-800'
+export const audioClasses = 'w-full rounded-md bg-surface-raised'
 </script>
 
 <div class="{{ containerClasses }}">
   @if(title)
     <div class="mb-2 px-1">
-      <h3 class="text-sm font-medium text-gray-900 dark:text-gray-100">
+      <h3 class="text-sm font-medium text-fg">
         {{ title }}
       </h3>
     </div>
@@ -35,7 +35,7 @@ export const audioClasses = 'w-full rounded-md bg-gray-100 dark:bg-gray-800'
   </audio>
 
   @if(showWaveform)
-    <div class="mt-2 h-16 bg-gray-100 dark:bg-gray-800 rounded-md flex items-center justify-center">
+    <div class="mt-2 h-16 bg-surface-raised rounded-md flex items-center justify-center">
       <svg class="w-full h-full px-4" viewBox="0 0 100 40" preserveAspectRatio="none">
         <path
           d="M 0,20 L 10,15 L 20,10 L 30,5 L 40,15 L 50,20 L 60,25 L 70,30 L 80,20 L 90,15 L 100,20"