@kennycorrea/ui 0.1.1 → 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 —
@@ -160,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/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/Button/Button.js

@@ -3,7 +3,7 @@ import { Button as ThemedButton } from '@radix-ui/themes';
 import { forwardRef } from 'react';
 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/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

@@ -4,7 +4,7 @@ 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/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

@@ -2,7 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Dialog as ThemedDialog } from '@radix-ui/themes';
 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/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.1",
+  "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