@kennycorrea/ui 0.1.0 → 0.2.0

package/README.md

@@ -63,6 +63,58 @@ And in the app's own `index.css`:
 every utility class used *inside* the atoms — `w-full`, `inline-flex` — is missing from the
 generated CSS. The components come out subtly unstyled and nothing appears in the console.
 
+## Theming — 0.2.0
+
+**A product configures its own accents, default and storage namespace.** Until 0.2.0 all three
+were hardcoded to the first app that used this package: the fallback accent was jade, the accent
+list was six fixed colours, and preferences were stored under `upfront.theme` / `upfront.accent`.
+
+```ts
+// Once, in the app.
+export const theming = createTheming({
+  accents: ['teal', 'crimson'],
+  defaultAccent: 'teal',
+  storagePrefix: 'myapp',
+});
+
+theming.readAccent(); // 'teal' | 'crimson'
+```
+
+Any Radix accent name works, and a product with one brand colour passes one. The list is the
+order a picker should render.
+
+**`defaultAccent` is typed as a member of `accents`**, so naming one that is not on the list is
+`TS2322` rather than a colourless first paint — verified by compiling the mistake.
+
+**The literal array needs no `as const`**; the `const` type parameter infers the tuple. A list
+declared separately does, because `const list = ['teal']` widens to `string[]` and is rejected.
+
+⚠ **`storagePrefix` is required and has no default.** A default would be one product's name
+silently storing another's preferences, and because separate origins never collide, nothing would
+ever reveal it.
+
+⚠ **Every accent needs its Radix colour scale imported** in the app's `main.tsx` — see Colour
+scales below. A missing scale is not an error; it is a colourless app.
+
+**A factory, not a `configure()` call.** Module-level mutable state would have to be written
+before the first read, making correctness depend on import order — the same class of silent bug as
+the CSS import order this package already has to warn about. An instance cannot be read before it
+is made.
+
+`applyTheme` stays a free function, because `data-theme` is the contract between it and
+`tokens.css` rather than a preference: two apps disagreeing about the attribute name would each
+need their own stylesheet.
+
+### What still works unchanged
+
+`readTheme`, `storeTheme`, `readAccent` and `storeAccent` are still exported as free functions,
+bound to an instance with the six default accents, jade, and the `upfront.*` keys. **One
+implementation, not two** — they are literally a pre-made instance, so no call site had to change
+and nobody who already picked a theme loses it. `ACCENTS` remains as a deprecated alias for
+`DEFAULT_ACCENTS`, the same array.
+
+A new product should call `createTheming` with its own name rather than inherit those.
+
 ## What is deliberately not here
 
 - **Dictionaries.** Words belong to an app. The two strings the atoms say on their own behalf —
@@ -83,6 +135,29 @@ load-bearing** — scales define `--gray-*` literally and `base.css` remaps it o
 `grayColor`, so `base.css` must come last. Adding an accent to `ACCENTS` means adding its scale
 in every app that offers it, or it resolves to nothing.
 
+## ⚠ 0.1.0 was broken for any Node consumer
+
+**Fixed in 0.1.1.** The package compiled with `moduleResolution: bundler`, which leaves relative
+imports extensionless in the output — `export * from './atoms'`. Vite resolves that happily, so
+every build passed and the linked `file:../ui` setup never complained. **Node does not support
+directory imports**, so the moment the package was installed from the registry it failed:
+
+    Directory import '…/@kennycorrea/ui/dist/atoms' is not supported
+    resolving ES modules imported from …/@kennycorrea/ui/dist/index.js
+
+It surfaced in the dashboard's Vitest run, which resolves dependencies with Node semantics. A
+bundler-only consumer would never have noticed, which is why it shipped.
+
+The fix is the rule this project already applies in `api/`, whose own brief states it: **an
+explicit `.js` on every relative import**, and `/index.js` for a directory. `tsconfig.json` is now
+`moduleResolution: nodenext`, so `tsc` *refuses* the extensionless form — verified by putting one
+back and watching it error — rather than silently emitting it again.
+
+⚠ **The lesson is about what "the build passes" is worth.** Three apps built, 46 tests passed and
+a browser check confirmed the styling, all while the package was unimportable by Node. Nothing was
+wrong with those checks; they simply all went through the same bundler. The first consumer with
+different resolution semantics found it immediately.
+
 ## Releasing
 
 `npm run build` compiles to `dist/` with type declarations. The version in `package.json` is the
@@ -137,17 +212,28 @@ That was the state when the workflow was first added.
 
 ### Where it is consumed from today
 
-⚠ **The three apps still depend on `file:../ui`**, which works while they sit side by side on one
-disk and does **not** work on Vercel, where each project builds from its own repository.
-
-Once this is published, each consumer's dependency becomes a version instead of a path:
+✅ **All three apps depend on a version from the registry**, as of 2026-09-30. The
+`file:../ui` arrangement is gone, and each app now builds on Vercel from its own repository.
 
 ```jsonc
-// web, site and admin package.json
-"@kennycorrea/ui": "^0.1.0"   // instead of "file:../ui"
+// a new consumer
+"@kennycorrea/ui": "^0.2.0"
+
+// web, site and admin, still — see the note below
+"@kennycorrea/ui": "^0.1.1"
 ```
 
-That is one line in three files and no code change. Note that `file:` installs a **symlink**, so
-local development currently picks up edits to this package immediately; a published version will
-not, and an app wanting to test an unreleased change wants `npm link` or a `file:` override
-rather than a copy.
+⚠ **Never floor a range at 0.1.0** — its published output cannot be imported by Node. `^0.1.0`
+resolves correctly today because npm picks the newest match, but a range whose floor is unusable
+documents nothing and would let a lockfile built from scratch land back on it.
+
+⚠ **Under `0.x`, `^` does not cross a minor.** `^0.1.1` will **not** take 0.2.0, so moving a
+consumer onto the new theming API is a `package.json` change in each app, not just a lockfile
+refresh. The free functions still work, so an app that does not need `createTheming` can stay
+where it is — and the three existing apps deliberately do, for now. Moving them is a one-line
+change each plus a lockfile, worth doing to stop three consumers drifting a minor behind, and
+worth doing as its own commit rather than inside this one.
+
+⚠ **A `file:` install was a symlink; a version install is a copy.** Edits here no longer appear in
+a consumer. An app that needs an unreleased change wants `npm link` or a temporary `file:`
+override — never a copied file, which is the drift this package exists to end.

package/dist/atoms/Avatar/Avatar.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Avatar as ThemedAvatar } from '@radix-ui/themes';
-import { cn } from '../../utils/cn';
+import { cn } from '../../utils/cn.js';
 /** Two letters from the name, which is all a small circle has room for. */
 function initialsOf(name) {
     if (!name)

package/dist/atoms/Avatar/index.d.ts

@@ -1 +1 @@
-export * from './Avatar';
+export * from './Avatar.js';

package/dist/atoms/Avatar/index.js

@@ -1 +1 @@
-export * from './Avatar';
+export * from './Avatar.js';

package/dist/atoms/Badge/Badge.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Badge as ThemedBadge } from '@radix-ui/themes';
 /**
- * Upfront's five meanings, in Themes' colour vocabulary.
+ * The five meanings this library names, in Themes' colour vocabulary.
  *
  * **`brand` names no colour on purpose.** Themes falls back to whatever accent the theme
  * carries, so a badge that means "this is ours" follows the business's chosen colour while

package/dist/atoms/Badge/index.d.ts

@@ -1 +1 @@
-export * from './Badge';
+export * from './Badge.js';

package/dist/atoms/Badge/index.js

@@ -1 +1 @@
-export * from './Badge';
+export * from './Badge.js';

package/dist/atoms/Button/Button.d.ts

@@ -1,2 +1,2 @@
-import type { ButtonProps } from './Button.types';
+import type { ButtonProps } from './Button.types.js';
 export declare const Button: import("react").ForwardRefExoticComponent<ButtonProps & import("react").RefAttributes<HTMLButtonElement>>;

package/dist/atoms/Button/Button.js

@@ -1,9 +1,9 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Button as ThemedButton } from '@radix-ui/themes';
 import { forwardRef } from 'react';
-import { cn } from '../../utils/cn';
+import { cn } from '../../utils/cn.js';
 /**
- * Upfront's intents, expressed in Radix Themes' variant-and-colour vocabulary.
+ * The house intents, expressed in Radix Themes' variant-and-colour vocabulary.
  *
  * The mapping exists so three apps keep saying `variant="danger"` rather than
  * `variant="solid" color="red"` at sixty call sites — and so that when the house style changes

package/dist/atoms/Button/Button.types.d.ts

@@ -1,7 +1,7 @@
 import type { Button as ThemedButton } from '@radix-ui/themes';
 import type { ComponentPropsWithoutRef, ReactNode } from 'react';
 /**
- * Upfront's button intents.
+ * The house button intents.
  *
  * **`outline` is new, and it is how the disagreement was resolved.** The dashboard's
  * `secondary` mapped to Themes' `soft` and the marketing site's mapped to `surface` — the same

package/dist/atoms/Button/index.d.ts

@@ -1,2 +1,2 @@
-export * from './Button';
-export * from './Button.types';
+export * from './Button.js';
+export * from './Button.types.js';

package/dist/atoms/Button/index.js

@@ -1,2 +1,2 @@
-export * from './Button';
-export * from './Button.types';
+export * from './Button.js';
+export * from './Button.types.js';

package/dist/atoms/Card/Card.d.ts

@@ -6,7 +6,7 @@ export interface CardProps extends HTMLAttributes<HTMLDivElement> {
 /**
  * Radix Themes' Card, with the padding taken off.
  *
- * Themes pads its card for you; Upfront's cards are built from a header and a body with a
+ * Themes pads its card for you; the house card is built from a header and a body with a
  * rule between them, so the padding belongs to those rather than to the card. `p-0` is the
  * whole of the customisation.
  */

package/dist/atoms/Card/Card.js

@@ -1,10 +1,10 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Card as ThemedCard } from '@radix-ui/themes';
-import { cn } from '../../utils/cn';
+import { cn } from '../../utils/cn.js';
 /**
  * Radix Themes' Card, with the padding taken off.
  *
- * Themes pads its card for you; Upfront's cards are built from a header and a body with a
+ * Themes pads its card for you; the house card is built from a header and a body with a
  * rule between them, so the padding belongs to those rather than to the card. `p-0` is the
  * whole of the customisation.
  */

package/dist/atoms/Card/index.d.ts

@@ -1 +1 @@
-export * from './Card';
+export * from './Card.js';

package/dist/atoms/Card/index.js

@@ -1 +1 @@
-export * from './Card';
+export * from './Card.js';

package/dist/atoms/Checkbox/Checkbox.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Checkbox as ThemedCheckbox } from '@radix-ui/themes';
 import { forwardRef } from 'react';
-import { cn } from '../../utils/cn';
+import { cn } from '../../utils/cn.js';
 /**
  * A checkbox, for a list where several answers are true at once.
  *

package/dist/atoms/Checkbox/index.d.ts

@@ -1 +1 @@
-export * from './Checkbox';
+export * from './Checkbox.js';

package/dist/atoms/Checkbox/index.js

@@ -1 +1 @@
-export * from './Checkbox';
+export * from './Checkbox.js';

package/dist/atoms/ContextMenu/index.d.ts

@@ -1 +1 @@
-export * from './ContextMenu';
+export * from './ContextMenu.js';

package/dist/atoms/ContextMenu/index.js

@@ -1 +1 @@
-export * from './ContextMenu';
+export * from './ContextMenu.js';

package/dist/atoms/Dialog/Dialog.d.ts

@@ -10,7 +10,7 @@ export interface DialogProps {
     className?: string;
 }
 /**
- * Themes' dialog, laid out the way Upfront's are: a titled header, a body, and a rule above
+ * Themes' dialog, laid out the way the house ones are: a titled header, a body, and a rule above
  * the actions.
  *
  * The padding is taken off the content so those three bands can own it — Themes pads the

package/dist/atoms/Dialog/Dialog.js

@@ -1,8 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Dialog as ThemedDialog } from '@radix-ui/themes';
-import { cn } from '../../utils/cn';
+import { cn } from '../../utils/cn.js';
 /**
- * Themes' dialog, laid out the way Upfront's are: a titled header, a body, and a rule above
+ * Themes' dialog, laid out the way the house ones are: a titled header, a body, and a rule above
  * the actions.
  *
  * The padding is taken off the content so those three bands can own it — Themes pads the

package/dist/atoms/Dialog/index.d.ts

@@ -1 +1 @@
-export * from './Dialog';
+export * from './Dialog.js';

package/dist/atoms/Dialog/index.js

@@ -1 +1 @@
-export * from './Dialog';
+export * from './Dialog.js';

package/dist/atoms/Icon/Icon.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { cn } from '../../utils/cn';
+import { cn } from '../../utils/cn.js';
 /**
  * The handful of icons this app actually uses, drawn inline.
  *

package/dist/atoms/Icon/index.d.ts

@@ -1 +1 @@
-export * from './Icon';
+export * from './Icon.js';

package/dist/atoms/Icon/index.js

@@ -1 +1 @@
-export * from './Icon';
+export * from './Icon.js';

package/dist/atoms/Input/Input.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { TextField } from '@radix-ui/themes';
 import { forwardRef } from 'react';
-import { cn } from '../../utils/cn';
+import { cn } from '../../utils/cn.js';
 const SIZES = { sm: '1', md: '2', lg: '3' };
 export const Input = forwardRef(function Input({ size = 'md', invalid = false, className, ...props }, ref) {
     return (_jsx(TextField.Root, { ref: ref, size: SIZES[size], 

package/dist/atoms/Input/index.d.ts

@@ -1 +1 @@
-export * from './Input';
+export * from './Input.js';

package/dist/atoms/Input/index.js

@@ -1 +1 @@
-export * from './Input';
+export * from './Input.js';

package/dist/atoms/Label/Label.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Text } from '@radix-ui/themes';
 import { forwardRef } from 'react';
-import { cn } from '../../utils/cn';
+import { cn } from '../../utils/cn.js';
 /**
  * Themes' `Text` rendered as a label, so field labels sit on the same type scale as
  * everything else.

package/dist/atoms/Label/index.d.ts

@@ -1 +1 @@
-export * from './Label';
+export * from './Label.js';

package/dist/atoms/Label/index.js

@@ -1 +1 @@
-export * from './Label';
+export * from './Label.js';

package/dist/atoms/Popover/Popover.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Popover as ThemedPopover } from '@radix-ui/themes';
-import { cn } from '../../utils/cn';
+import { cn } from '../../utils/cn.js';
 /**
  * A popover rather than a dropdown menu: the contents are things to read — the bell feed —
  * not commands to run, and a menu's roving focus would make arrow keys skip past text

package/dist/atoms/Popover/index.d.ts

@@ -1 +1 @@
-export * from './Popover';
+export * from './Popover.js';

package/dist/atoms/Popover/index.js

@@ -1 +1 @@
-export * from './Popover';
+export * from './Popover.js';

package/dist/atoms/Progress/Progress.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Progress as ThemedProgress } from '@radix-ui/themes';
-import { cn } from '../../utils/cn';
+import { cn } from '../../utils/cn.js';
 export function Progress({ value, label, color = 'jade', className }) {
     return (_jsx(ThemedProgress
     // Rounded for the announcement, clamped for both: turnover can genuinely pass its

package/dist/atoms/Progress/index.d.ts

@@ -1 +1 @@
-export * from './Progress';
+export * from './Progress.js';

package/dist/atoms/Progress/index.js

@@ -1 +1 @@
-export * from './Progress';
+export * from './Progress.js';

package/dist/atoms/Select/Select.js

@@ -1,8 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Select as ThemedSelect } from '@radix-ui/themes';
 import { forwardRef } from 'react';
-import { useUiStrings } from '../../strings';
-import { cn } from '../../utils/cn';
+import { useUiStrings } from '../../strings.js';
+import { cn } from '../../utils/cn.js';
 /**
  * Themes' Select, which is its own styling of the same Radix primitive this used to wrap by
  * hand — the chevron, the popper, the checked item and the scroll buttons all come with it.

package/dist/atoms/Select/index.d.ts

@@ -1 +1 @@
-export * from './Select';
+export * from './Select.js';

package/dist/atoms/Select/index.js

@@ -1 +1 @@
-export * from './Select';
+export * from './Select.js';

package/dist/atoms/Separator/Separator.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Separator as ThemedSeparator } from '@radix-ui/themes';
-import { cn } from '../../utils/cn';
+import { cn } from '../../utils/cn.js';
 export function Separator({ orientation = 'horizontal', className }) {
     return _jsx(ThemedSeparator, { orientation: orientation, size: "4", className: cn(className) });
 }

package/dist/atoms/Separator/index.d.ts

@@ -1 +1 @@
-export * from './Separator';
+export * from './Separator.js';

package/dist/atoms/Separator/index.js

@@ -1 +1 @@
-export * from './Separator';
+export * from './Separator.js';

package/dist/atoms/Spinner/Spinner.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Spinner as ThemedSpinner } from '@radix-ui/themes';
-import { useUiStrings } from '../../strings';
-import { cn } from '../../utils/cn';
+import { useUiStrings } from '../../strings.js';
+import { cn } from '../../utils/cn.js';
 /**
  * Themes' spinner, wrapped so it still announces itself.
  *

package/dist/atoms/Spinner/index.d.ts

@@ -1 +1 @@
-export * from './Spinner';
+export * from './Spinner.js';

package/dist/atoms/Spinner/index.js

@@ -1 +1 @@
-export * from './Spinner';
+export * from './Spinner.js';

package/dist/atoms/Switch/Switch.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Switch as ThemedSwitch } from '@radix-ui/themes';
 import { forwardRef } from 'react';
-import { cn } from '../../utils/cn';
+import { cn } from '../../utils/cn.js';
 export const Switch = forwardRef(function Switch({ className, ...props }, ref) {
     return _jsx(ThemedSwitch, { ref: ref, size: "2", className: cn(className), ...props });
 });

package/dist/atoms/Switch/index.d.ts

@@ -1 +1 @@
-export * from './Switch';
+export * from './Switch.js';

package/dist/atoms/Switch/index.js

@@ -1 +1 @@
-export * from './Switch';
+export * from './Switch.js';

package/dist/atoms/Textarea/Textarea.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { TextArea } from '@radix-ui/themes';
 import { forwardRef } from 'react';
-import { cn } from '../../utils/cn';
+import { cn } from '../../utils/cn.js';
 export const Textarea = forwardRef(function Textarea({ invalid = false, className, rows = 3, ...props }, ref) {
     return (_jsx(TextArea, { ref: ref, rows: rows, size: "2", color: invalid ? 'red' : undefined, "aria-invalid": invalid || undefined, className: cn('w-full', className), ...props }));
 });

package/dist/atoms/Textarea/index.d.ts

@@ -1 +1 @@
-export * from './Textarea';
+export * from './Textarea.js';

package/dist/atoms/Textarea/index.js

@@ -1 +1 @@
-export * from './Textarea';
+export * from './Textarea.js';

package/dist/atoms/Tooltip/index.d.ts

@@ -1 +1 @@
-export * from './Tooltip';
+export * from './Tooltip.js';

package/dist/atoms/Tooltip/index.js

@@ -1 +1 @@
-export * from './Tooltip';
+export * from './Tooltip.js';

package/dist/atoms/index.d.ts

@@ -1,18 +1,18 @@
-export * from './Avatar';
-export * from './Badge';
-export * from './Button';
-export * from './Card';
-export * from './Checkbox';
-export * from './ContextMenu';
-export * from './Dialog';
-export * from './Icon';
-export * from './Input';
-export * from './Label';
-export * from './Popover';
-export * from './Progress';
-export * from './Select';
-export * from './Separator';
-export * from './Spinner';
-export * from './Switch';
-export * from './Textarea';
-export * from './Tooltip';
+export * from './Avatar/index.js';
+export * from './Badge/index.js';
+export * from './Button/index.js';
+export * from './Card/index.js';
+export * from './Checkbox/index.js';
+export * from './ContextMenu/index.js';
+export * from './Dialog/index.js';
+export * from './Icon/index.js';
+export * from './Input/index.js';
+export * from './Label/index.js';
+export * from './Popover/index.js';
+export * from './Progress/index.js';
+export * from './Select/index.js';
+export * from './Separator/index.js';
+export * from './Spinner/index.js';
+export * from './Switch/index.js';
+export * from './Textarea/index.js';
+export * from './Tooltip/index.js';

package/dist/atoms/index.js

@@ -1,18 +1,18 @@
-export * from './Avatar';
-export * from './Badge';
-export * from './Button';
-export * from './Card';
-export * from './Checkbox';
-export * from './ContextMenu';
-export * from './Dialog';
-export * from './Icon';
-export * from './Input';
-export * from './Label';
-export * from './Popover';
-export * from './Progress';
-export * from './Select';
-export * from './Separator';
-export * from './Spinner';
-export * from './Switch';
-export * from './Textarea';
-export * from './Tooltip';
+export * from './Avatar/index.js';
+export * from './Badge/index.js';
+export * from './Button/index.js';
+export * from './Card/index.js';
+export * from './Checkbox/index.js';
+export * from './ContextMenu/index.js';
+export * from './Dialog/index.js';
+export * from './Icon/index.js';
+export * from './Input/index.js';
+export * from './Label/index.js';
+export * from './Popover/index.js';
+export * from './Progress/index.js';
+export * from './Select/index.js';
+export * from './Separator/index.js';
+export * from './Spinner/index.js';
+export * from './Switch/index.js';
+export * from './Textarea/index.js';
+export * from './Tooltip/index.js';

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export * from './atoms';
-export * from './strings';
-export * from './utils';
+export * from './atoms/index.js';
+export * from './strings.js';
+export * from './utils/index.js';

package/dist/index.js

@@ -1,3 +1,3 @@
-export * from './atoms';
-export * from './strings';
-export * from './utils';
+export * from './atoms/index.js';
+export * from './strings.js';
+export * from './utils/index.js';

package/dist/utils/index.d.ts

@@ -1,2 +1,2 @@
-export * from './cn';
-export * from './theme';
+export * from './cn.js';
+export * from './theme.js';

package/dist/utils/index.js

@@ -1,2 +1,2 @@
-export * from './cn';
-export * from './theme';
+export * from './cn.js';
+export * from './theme.js';

package/dist/utils/theme.d.ts

@@ -7,27 +7,95 @@ export type Theme = (typeof THEMES)[number];
  * "System" deliberately stamps *nothing*: the CSS falls through to `prefers-color-scheme`
  * on its own, so following the operating system needs no listener here and keeps working
  * when the user changes it mid-session.
+ *
+ * **Outside `createTheming` on purpose.** `data-theme` is the contract between this function
+ * and `tokens.css`, not a preference an app gets to set — two apps disagreeing about the
+ * attribute name would each need their own stylesheet, which is the thing this package exists
+ * to prevent.
  */
 export declare function applyTheme(theme: Theme): void;
-export declare function readTheme(): Theme;
-export declare function storeTheme(theme: Theme): void;
 /**
- * The accents a business can dress an app in.
+ * A reasonable set of accents for an app that wants a picker and has no opinion.
  *
  * Six of Radix's twenty-six, not all of them: every one costs a colour scale in the bundle —
- * see the note in each app's `main.tsx` — and a page of near-identical greens is a worse
- * choice than six that are obviously different from across a room. `jade` is first because it
- * is Upfront's own, and the default for anyone who never opens the picker.
+ * see the `main.tsx` note in the README — and a page of near-identical greens is a worse
+ * choice than six that are obviously different from across a room.
  *
- * **Only the accent moves.** Success stays jade, warning amber, danger red — those are
- * meanings rather than decoration, and a business whose "paid" badge turned orange because
- * they liked orange would have lost something. It does mean picking red or jade makes the
- * accent and one semantic colour look alike, which is a fair trade for letting people choose.
+ * **It is a default, not the list.** Pass your own to `createTheming`; any Radix accent name
+ * works, and a product with one brand colour should pass just that one.
  *
  * **The labels are not here.** They are words, and words belong to an app's own dictionary —
  * the same rule that keeps `UiStrings` down to two entries.
  */
+export declare const DEFAULT_ACCENTS: readonly ["jade", "blue", "purple", "red", "orange", "yellow"];
+/**
+ * @deprecated Prefer `DEFAULT_ACCENTS`, or your own list passed to `createTheming`. Kept
+ * because the old name is imported by name in existing apps; it is the same array.
+ */
 export declare const ACCENTS: readonly ["jade", "blue", "purple", "red", "orange", "yellow"];
-export type Accent = (typeof ACCENTS)[number];
-export declare function readAccent(): Accent;
-export declare function storeAccent(accent: Accent): void;
+/** The accents `DEFAULT_ACCENTS` offers. An app with its own list gets its own union. */
+export type Accent = (typeof DEFAULT_ACCENTS)[number];
+export interface ThemingConfig<A extends readonly string[]> {
+    /**
+     * The accents this product offers, in the order a picker should show them.
+     *
+     * ⚠ **Each one needs its Radix colour scale imported in the app's `main.tsx`**, or it
+     * resolves to nothing — a missing scale is not an error, it is a colourless app.
+     */
+    accents: A;
+    /** The accent for anyone who has never opened the picker. Must be one of `accents`. */
+    defaultAccent: A[number];
+    /**
+     * Namespace for this product's `localStorage` keys, giving `<prefix>.theme` and
+     * `<prefix>.accent`.
+     *
+     * **Required, with no default, deliberately.** A default here would be some other
+     * product's name silently storing this one's preferences — and because it would work
+     * perfectly on a separate origin, nothing would ever reveal it.
+     */
+    storagePrefix: string;
+}
+export interface Theming<A extends readonly string[]> {
+    /** The configured list, so a picker can render it without being handed it twice. */
+    readonly accents: A;
+    readonly defaultAccent: A[number];
+    readTheme(): Theme;
+    storeTheme(theme: Theme): void;
+    readAccent(): A[number];
+    storeAccent(accent: A[number]): void;
+}
+/**
+ * Binds the theme and accent helpers to one product's accents, default and storage namespace.
+ *
+ * Three things used to be hardcoded here — the fallback accent, the list of accents, and the
+ * `localStorage` prefix — and all three were the same mistake: a shared package holding one
+ * product's identity. They move together rather than one at a time, because a product that can
+ * choose its default and not its palette has not really chosen anything.
+ *
+ * **A factory rather than a `configure()` call.** Module-level mutable state would have to be
+ * written before the first read, which makes correctness depend on import order — the same
+ * class of bug as this library's load-bearing CSS import order, and just as silent. An instance
+ * cannot be read before it is made.
+ *
+ * ```ts
+ * export const theming = createTheming({
+ *   accents: ['teal', 'crimson'],
+ *   defaultAccent: 'teal',
+ *   storagePrefix: 'myapp',
+ * });
+ *
+ * theming.readAccent(); // 'teal' | 'crimson'
+ * ```
+ *
+ * `defaultAccent` is typed as a member of `accents`, so naming one that is not on the list is a
+ * compile error (`TS2322`) rather than a colourless first paint.
+ *
+ * The literal array needs no `as const` — the `const` type parameter infers the tuple. A list
+ * declared separately *does*, because `const list = ['teal']` widens to `string[]`, which is not
+ * a tuple and will be rejected: either inline it or write `as const` there.
+ */
+export declare function createTheming<const A extends readonly [string, ...string[]]>(config: ThemingConfig<A>): Theming<A>;
+export declare const readTheme: () => Theme;
+export declare const storeTheme: (theme: Theme) => void;
+export declare const readAccent: () => "jade" | "red" | "yellow" | "orange" | "purple" | "blue";
+export declare const storeAccent: (accent: "jade" | "red" | "yellow" | "orange" | "purple" | "blue") => void;

package/dist/utils/theme.js

@@ -1,5 +1,4 @@
 export const THEMES = ['system', 'light', 'dark'];
-const STORAGE_KEY = 'upfront.theme';
 /**
  * Applies a theme by stamping the root element, or clearing it for "system".
  *
@@ -7,6 +6,11 @@ const STORAGE_KEY = 'upfront.theme';
  * "System" deliberately stamps *nothing*: the CSS falls through to `prefers-color-scheme`
  * on its own, so following the operating system needs no listener here and keeps working
  * when the user changes it mid-session.
+ *
+ * **Outside `createTheming` on purpose.** `data-theme` is the contract between this function
+ * and `tokens.css`, not a preference an app gets to set — two apps disagreeing about the
+ * attribute name would each need their own stylesheet, which is the thing this package exists
+ * to prevent.
  */
 export function applyTheme(theme) {
     const root = document.documentElement;
@@ -15,58 +19,117 @@ export function applyTheme(theme) {
     else
         root.setAttribute('data-theme', theme);
 }
-export function readTheme() {
-    try {
-        const stored = localStorage.getItem(STORAGE_KEY);
-        return THEMES.includes(stored) ? stored : 'system';
-    }
-    catch {
-        // Private windows and blocked site data both throw. A theme preference is not worth a
-        // crash, so the system default stands.
-        return 'system';
-    }
-}
-export function storeTheme(theme) {
-    try {
-        localStorage.setItem(STORAGE_KEY, theme);
-    }
-    catch {
-        // See readTheme. It applies for this session either way.
-    }
-}
 /**
- * The accents a business can dress an app in.
+ * A reasonable set of accents for an app that wants a picker and has no opinion.
  *
  * Six of Radix's twenty-six, not all of them: every one costs a colour scale in the bundle —
- * see the note in each app's `main.tsx` — and a page of near-identical greens is a worse
- * choice than six that are obviously different from across a room. `jade` is first because it
- * is Upfront's own, and the default for anyone who never opens the picker.
+ * see the `main.tsx` note in the README — and a page of near-identical greens is a worse
+ * choice than six that are obviously different from across a room.
  *
- * **Only the accent moves.** Success stays jade, warning amber, danger red — those are
- * meanings rather than decoration, and a business whose "paid" badge turned orange because
- * they liked orange would have lost something. It does mean picking red or jade makes the
- * accent and one semantic colour look alike, which is a fair trade for letting people choose.
+ * **It is a default, not the list.** Pass your own to `createTheming`; any Radix accent name
+ * works, and a product with one brand colour should pass just that one.
  *
  * **The labels are not here.** They are words, and words belong to an app's own dictionary —
  * the same rule that keeps `UiStrings` down to two entries.
  */
-export const ACCENTS = ['jade', 'blue', 'purple', 'red', 'orange', 'yellow'];
-const ACCENT_KEY = 'upfront.accent';
-export function readAccent() {
-    try {
-        const stored = localStorage.getItem(ACCENT_KEY);
-        return ACCENTS.includes(stored) ? stored : 'jade';
-    }
-    catch {
-        // Same as readTheme: a private window throws, and a colour is not worth a crash.
-        return 'jade';
-    }
-}
-export function storeAccent(accent) {
-    try {
-        localStorage.setItem(ACCENT_KEY, accent);
-    }
-    catch {
-        // It applies for this session either way.
-    }
+export const DEFAULT_ACCENTS = ['jade', 'blue', 'purple', 'red', 'orange', 'yellow'];
+/**
+ * @deprecated Prefer `DEFAULT_ACCENTS`, or your own list passed to `createTheming`. Kept
+ * because the old name is imported by name in existing apps; it is the same array.
+ */
+export const ACCENTS = DEFAULT_ACCENTS;
+/**
+ * Binds the theme and accent helpers to one product's accents, default and storage namespace.
+ *
+ * Three things used to be hardcoded here — the fallback accent, the list of accents, and the
+ * `localStorage` prefix — and all three were the same mistake: a shared package holding one
+ * product's identity. They move together rather than one at a time, because a product that can
+ * choose its default and not its palette has not really chosen anything.
+ *
+ * **A factory rather than a `configure()` call.** Module-level mutable state would have to be
+ * written before the first read, which makes correctness depend on import order — the same
+ * class of bug as this library's load-bearing CSS import order, and just as silent. An instance
+ * cannot be read before it is made.
+ *
+ * ```ts
+ * export const theming = createTheming({
+ *   accents: ['teal', 'crimson'],
+ *   defaultAccent: 'teal',
+ *   storagePrefix: 'myapp',
+ * });
+ *
+ * theming.readAccent(); // 'teal' | 'crimson'
+ * ```
+ *
+ * `defaultAccent` is typed as a member of `accents`, so naming one that is not on the list is a
+ * compile error (`TS2322`) rather than a colourless first paint.
+ *
+ * The literal array needs no `as const` — the `const` type parameter infers the tuple. A list
+ * declared separately *does*, because `const list = ['teal']` widens to `string[]`, which is not
+ * a tuple and will be rejected: either inline it or write `as const` there.
+ */
+export function createTheming(config) {
+    const { accents, defaultAccent, storagePrefix } = config;
+    const themeKey = `${storagePrefix}.theme`;
+    const accentKey = `${storagePrefix}.accent`;
+    return {
+        accents,
+        defaultAccent,
+        readTheme() {
+            try {
+                const stored = localStorage.getItem(themeKey);
+                return THEMES.includes(stored) ? stored : 'system';
+            }
+            catch {
+                // Private windows and blocked site data both throw. A theme preference is not worth a
+                // crash, so the system default stands.
+                return 'system';
+            }
+        },
+        storeTheme(theme) {
+            try {
+                localStorage.setItem(themeKey, theme);
+            }
+            catch {
+                // See readTheme. It applies for this session either way.
+            }
+        },
+        readAccent() {
+            try {
+                const stored = localStorage.getItem(accentKey);
+                // Validated against the configured list, so a stored accent that was removed from a
+                // later release falls back rather than being handed to Radix as an unknown colour.
+                return accents.includes(stored) ? stored : defaultAccent;
+            }
+            catch {
+                // Same as readTheme: a private window throws, and a colour is not worth a crash.
+                return defaultAccent;
+            }
+        },
+        storeAccent(accent) {
+            try {
+                localStorage.setItem(accentKey, accent);
+            }
+            catch {
+                // It applies for this session either way.
+            }
+        },
+    };
 }
+/**
+ * The instance the original free functions are bound to: the six default accents, jade, and the
+ * `upfront.*` storage keys the apps that predate `createTheming` already wrote.
+ *
+ * **One implementation, not two.** These exports exist so no call site had to change when the
+ * factory landed, and keeping the prefix is what stops an existing user losing the theme they
+ * picked. A new product should call `createTheming` with its own name instead.
+ */
+const legacy = createTheming({
+    accents: DEFAULT_ACCENTS,
+    defaultAccent: 'jade',
+    storagePrefix: 'upfront',
+});
+export const readTheme = legacy.readTheme;
+export const storeTheme = legacy.storeTheme;
+export const readAccent = legacy.readAccent;
+export const storeAccent = legacy.storeAccent;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kennycorrea/ui",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Upfront's house component layer: atoms over Radix Themes, the token bridge, and the accent logic.",
   "private": false,
   "type": "module",

package/tokens.css

@@ -1,5 +1,5 @@
 /**
- * Upfront's token bridge — the shared half of every app's stylesheet.
+ * The house token bridge — the shared half of every consuming app's stylesheet.
  *
  * Two apps said `text-ink-muted` and `bg-brand-700/8` and each carried its own copy of what
  * those meant. The values below are the dashboard's, which was the more complete of the two.
@@ -36,7 +36,7 @@
 
 
 /**
- * Upfront's token names, registered with Tailwind.
+ * The house token names, registered with Tailwind.
  *
  * The values here are static fallbacks, not the live palette — the real assignments are in
  * the `.radix-themes` rule below. Two blocks rather than one because of how custom
@@ -88,7 +88,7 @@
 }
 
 /**
- * The live bridge: Upfront's names, pointed at Radix Themes' palette.
+ * The live bridge: the house names, pointed at Radix Themes' palette.
  *
  * Every colour in the app now comes from Themes. This is the only place that names a Radix
  * variable — the components keep saying `brand-700`, `ink-muted`, `surface`, and nothing