npm - @wtfalch/design - Versions diffs - 0.1.0 → 0.3.0 - Mend

@wtfalch/design 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (35) hide show

package/README.md +84 -37
package/dist/components/Brand.d.ts +35 -6
package/dist/components/Brand.js +26 -201
package/dist/components/Icon.d.ts +1 -1
package/dist/components/Icon.js +5 -228
package/dist/components/Illustration.js +1 -2
package/dist/components/Tour.d.ts +3 -1
package/dist/components/Tour.js +3 -3
package/dist/components/brandMarks.d.ts +71 -0
package/dist/components/brandMarks.js +26 -0
package/dist/components/icons.d.ts +37 -0
package/dist/components/icons.js +253 -0
package/dist/components/tourMarker.d.ts +14 -3
package/dist/components/tourMarker.js +11 -7
package/dist/index.d.ts +13 -1
package/dist/index.js +11 -1
package/dist/products/index.d.ts +69 -0
package/dist/products/index.js +54 -0
package/dist/products/tf.d.ts +32 -0
package/dist/products/tf.js +104 -0
package/dist/products/valet.d.ts +23 -0
package/dist/products/valet.js +103 -0
package/dist/styles/index.css +23 -57
package/dist/tf.css +3362 -0
package/dist/tf.d.ts +18 -0
package/dist/tf.js +17 -0
package/dist/themes/css.d.ts +45 -0
package/dist/themes/css.js +78 -0
package/dist/{themes.d.ts → themes/index.d.ts} +11 -13
package/dist/{themes.js → themes/index.js} +12 -89
package/dist/tokens.css +17 -0
package/dist/valet.css +3366 -0
package/dist/valet.d.ts +18 -0
package/dist/valet.js +17 -0
package/package.json +15 -5

package/dist/tf.d.ts ADDED Viewed

@@ -0,0 +1,18 @@
+/**
+ * tf's entry: the package, as tf.
+ *
+ * Everything the main entry exports, and on top of it `Brand`, `THEMES`,
+ * `DEFAULT_THEME` and `applyTheme` bound to tf -- a local export shadows
+ * the same name from `export *`. A site is one product, so it imports this
+ * and `@wtfalch/design/tf.css` and nothing of anyone else's.
+ */
+export * from './index';
+export declare const product: import("./products").Product;
+export declare const Brand: (props: {
+    name?: import("./index").BrandName;
+    title?: string;
+    className?: string;
+}) => import("react").JSX.Element;
+export declare const THEMES: Record<string, import("./themes").Theme>;
+export declare const DEFAULT_THEME: string;
+export declare const applyTheme: (theme?: string | import("./themes").Theme, el?: HTMLElement) => void;

package/dist/tf.js ADDED Viewed

@@ -0,0 +1,17 @@
+/**
+ * tf's entry: the package, as tf.
+ *
+ * Everything the main entry exports, and on top of it `Brand`, `THEMES`,
+ * `DEFAULT_THEME` and `applyTheme` bound to tf -- a local export shadows
+ * the same name from `export *`. A site is one product, so it imports this
+ * and `@wtfalch/design/tf.css` and nothing of anyone else's.
+ */
+export * from './index';
+import { bindProduct } from './products';
+import { tf } from './products/tf';
+const bound = bindProduct(tf);
+export const product = bound.product;
+export const Brand = bound.Brand;
+export const THEMES = bound.THEMES;
+export const DEFAULT_THEME = bound.DEFAULT_THEME;
+export const applyTheme = bound.applyTheme;

package/dist/themes/css.d.ts ADDED Viewed

@@ -0,0 +1,45 @@
+import type { Theme, ThemeTokens } from './index';
+/**
+ * A theme as CSS, for the paint before React.
+ *
+ * `applyTheme` writes a theme as inline custom properties at run time, and
+ * React mounts after the first paint, so a theme applied in an effect flashes
+ * the base palette. A consumer wants the same values as a stylesheet rule it
+ * can ship in `<head>`, and it must not write that rule by hand, because a
+ * copy drifts from the object the contrast test measures. So the rule is
+ * generated from the object: at build time for the products here, or by a
+ * consumer for a theme of its own.
+ *
+ * The selector is `:root[data-theme='<id>']`, the attribute `applyTheme` sets,
+ * so the two mechanisms agree on which theme is on. A theme with no tokens,
+ * which is `system`, gets no block: its palette is the base, and its light
+ * half is the `prefers-color-scheme` block `base.css` scopes to it.
+ *
+ * No imports but a type, on purpose: `build-products.mjs` loads the compiled
+ * copy of this file in plain Node, which cannot follow the package's
+ * extensionless relative imports.
+ */
+/** The name `applyTheme` derives for a theme object. */
+export declare function themeId(theme: Theme): string;
+export declare function themeCss(id: string, theme: Theme): string;
+/** Every theme of one product, one rule each, ids checked against the names. */
+export declare function productCss(themes: Record<string, Theme>): string;
+/**
+ * A product's stylesheet, whole: the one file a site imports.
+ *
+ * In cascade order: the vocabulary; the product's identity on `:root`, so it
+ * wins over the base values by coming later at the same specificity; the
+ * default theme on `:root:not([data-theme])`, so the first paint is right with
+ * no attribute at all; the components; and one rule per theme. A default with
+ * no tokens -- tf's `system`, which is a media query rather than a palette --
+ * writes no default rule, and neither does an empty identity.
+ *
+ * Structural, not typed to `Product`: that type lives beside the React
+ * binding, and this module has to stay loadable in plain Node for the build.
+ */
+export declare function productStylesheet(product: {
+    name: string;
+    identity: Partial<ThemeTokens>;
+    themes: Record<string, Theme>;
+    defaultTheme: string;
+}, tokens: string, components: string): string;

package/dist/themes/css.js ADDED Viewed

@@ -0,0 +1,78 @@
+/**
+ * A theme as CSS, for the paint before React.
+ *
+ * `applyTheme` writes a theme as inline custom properties at run time, and
+ * React mounts after the first paint, so a theme applied in an effect flashes
+ * the base palette. A consumer wants the same values as a stylesheet rule it
+ * can ship in `<head>`, and it must not write that rule by hand, because a
+ * copy drifts from the object the contrast test measures. So the rule is
+ * generated from the object: at build time for the products here, or by a
+ * consumer for a theme of its own.
+ *
+ * The selector is `:root[data-theme='<id>']`, the attribute `applyTheme` sets,
+ * so the two mechanisms agree on which theme is on. A theme with no tokens,
+ * which is `system`, gets no block: its palette is the base, and its light
+ * half is the `prefers-color-scheme` block `base.css` scopes to it.
+ *
+ * No imports but a type, on purpose: `build-products.mjs` loads the compiled
+ * copy of this file in plain Node, which cannot follow the package's
+ * extensionless relative imports.
+ */
+/** The name `applyTheme` derives for a theme object. */
+export function themeId(theme) {
+    return theme.name.toLowerCase().replace(/\s+/g, '-');
+}
+/** The declarations of a token map, as one line. */
+function declarations(tokens) {
+    return Object.entries(tokens)
+        .map(([key, value]) => `${key}:${value}`)
+        .join(';');
+}
+export function themeCss(id, theme) {
+    const rules = declarations(theme.tokens);
+    if (!rules)
+        return '';
+    return `:root[data-theme='${id}']{${rules};color-scheme:${theme.scheme}}`;
+}
+/** Every theme of one product, one rule each, ids checked against the names. */
+export function productCss(themes) {
+    return Object.entries(themes)
+        .map(([id, theme]) => {
+        if (themeId(theme) !== id) {
+            throw new Error(`theme "${theme.name}" is keyed "${id}", but applyTheme calls it "${themeId(theme)}"`);
+        }
+        return themeCss(id, theme);
+    })
+        .filter(Boolean)
+        .join('\n');
+}
+/**
+ * A product's stylesheet, whole: the one file a site imports.
+ *
+ * In cascade order: the vocabulary; the product's identity on `:root`, so it
+ * wins over the base values by coming later at the same specificity; the
+ * default theme on `:root:not([data-theme])`, so the first paint is right with
+ * no attribute at all; the components; and one rule per theme. A default with
+ * no tokens -- tf's `system`, which is a media query rather than a palette --
+ * writes no default rule, and neither does an empty identity.
+ *
+ * Structural, not typed to `Product`: that type lives beside the React
+ * binding, and this module has to stay loadable in plain Node for the build.
+ */
+export function productStylesheet(product, tokens, components) {
+    const parts = ['/* ---- tokens.css ---- */', tokens.trimEnd()];
+    const identity = declarations(product.identity);
+    if (identity) {
+        parts.push(`/* ---- ${product.name}: the identity, under every theme ---- */`, `:root{${identity}}`);
+    }
+    const fallback = product.themes[product.defaultTheme];
+    if (!fallback) {
+        throw new Error(`product "${product.name}" defaults to "${product.defaultTheme}", which is not one of its themes`);
+    }
+    const rules = declarations(fallback.tokens);
+    if (rules) {
+        parts.push(`/* ---- ${product.name}: ${product.defaultTheme}, until a theme is picked ---- */`, `:root:not([data-theme]){${rules};color-scheme:${fallback.scheme}}`);
+    }
+    parts.push('/* ---- styles.css ---- */', components.trimEnd(), `/* ---- ${product.name}: the themes ---- */`, productCss(product.themes));
+    return `${parts.join('\n')}\n`;
+}

package/dist/{themes.d.ts → themes/index.d.ts} RENAMED Viewed

@@ -167,19 +167,17 @@ export interface Theme {
  */
 export declare function defineTheme(theme: Theme): Theme;
 /**
- * The built-ins, which are **examples and not the menu**.
- *
- * tf ships these four; an app that installs this package is expected to bring
- * its own and is not expected to look like tf. They are here because a package
- * that ships a token vocabulary and no theme written in it leaves the first
- * consumer guessing at how wide the vocabulary really is — and because the
- * contrast test needs something concrete to measure.
- *
- * `system` is a theme, not a mode. A `prefers-color-scheme` block that
- * overrides `:root` unconditionally means choosing a dark theme on a
- * light-mode laptop gets silently repainted; that media query is scoped to this
- * theme, so following the OS is a choice among the others rather than a rule
- * above them.
+ * Every theme the package knows, keyed by the name a consumer applies.
+ *
+ * Per product since 0.3.0. A theme is part of a product's identity the way its
+ * mark is, and 0.2.0 already made `Brand` the home of every product's mark by
+ * name; keeping each product's palette in its own repo meant each repo
+ * re-deriving first paint, the contrast measurement and a page to look at it
+ * on. So `products/tf.ts` holds tf's three and `products/valet.ts` valet's two,
+ * this is the union, and the contrast test and the gallery read the union.
+ *
+ * A consumer that wants only its own imports the product module, or the CSS
+ * `build-products.mjs` generates from it, and bundles nobody else's.
  */
 export declare const THEMES: Record<string, Theme>;
 export declare const DEFAULT_THEME = "system";

package/dist/{themes.js → themes/index.js} RENAMED Viewed

@@ -37,6 +37,8 @@
  * token added to the stylesheet and to no list fails the suite rather than
  * becoming a fourth, undocumented category.
  */
+import { TF_THEMES } from '../products/tf';
+import { VALET_THEMES } from '../products/valet';
 /**
  * Computed from a themeable token, and not settable.
  *
@@ -156,98 +158,19 @@ export function defineTheme(theme) {
     return theme;
 }
 /**
- * The dark palette, written out rather than inherited.
+ * Every theme the package knows, keyed by the name a consumer applies.
  *
- * `night` was `tokens: {}` once — "whatever the base is" — and that was wrong
- * twice over. It made the theme depend on a file it does not own, and it made
- * its swatch in the picker preview *the theme currently applied*, because an
- * empty map falls back to the live values.
- */
-const NIGHT = {
-    '--bg': '#0f1115',
-    '--panel': '#161a21',
-    '--panel-2': '#1c222b',
-    '--border': '#262d38',
-    '--text': '#e6e9ef',
-    '--muted': '#8b94a4',
-    '--accent': '#5b9dff',
-    '--accent-dim': '#2a4877',
-    /* No `--on-accent` here on purpose, so it inherits the base near-black.
-       Night used to set `#ffffff`, which is 2.72:1 on this accent -- the exact
-       pair `tokens.css` records as the reason the token exists at all. The base
-       was fixed and the theme carrying the old palette was never revisited, so
-       the primary button in the app's fixed dark theme failed the body-text
-       minimum by a wide margin for as long as the token had been "fixed".
-       `#06181a` on `#5b9dff` is 6.69:1. Found by the contrast scan, which is the
-       argument for shipping the measurement rather than the rule. */
-    '--app-bg': '#0f1115',
-};
-/**
- * The built-ins, which are **examples and not the menu**.
- *
- * tf ships these four; an app that installs this package is expected to bring
- * its own and is not expected to look like tf. They are here because a package
- * that ships a token vocabulary and no theme written in it leaves the first
- * consumer guessing at how wide the vocabulary really is — and because the
- * contrast test needs something concrete to measure.
+ * Per product since 0.3.0. A theme is part of a product's identity the way its
+ * mark is, and 0.2.0 already made `Brand` the home of every product's mark by
+ * name; keeping each product's palette in its own repo meant each repo
+ * re-deriving first paint, the contrast measurement and a page to look at it
+ * on. So `products/tf.ts` holds tf's three and `products/valet.ts` valet's two,
+ * this is the union, and the contrast test and the gallery read the union.
  *
- * `system` is a theme, not a mode. A `prefers-color-scheme` block that
- * overrides `:root` unconditionally means choosing a dark theme on a
- * light-mode laptop gets silently repainted; that media query is scoped to this
- * theme, so following the OS is a choice among the others rather than a rule
- * above them.
+ * A consumer that wants only its own imports the product module, or the CSS
+ * `build-products.mjs` generates from it, and bundles nobody else's.
  */
-export const THEMES = {
-    system: {
-        name: 'System',
-        note: 'Follows your OS between light and dark',
-        scheme: 'dark',
-        // Empty on purpose: this is the one theme that must *not* state a palette,
-        // because the `prefers-color-scheme` block is scoped to it and needs the
-        // base values to fall through. Its swatch is a special case.
-        tokens: {},
-    },
-    night: {
-        name: 'Night',
-        note: 'The dark palette, fixed — ignores the OS',
-        scheme: 'dark',
-        tokens: NIGHT,
-    },
-    paper: {
-        name: 'Paper',
-        note: 'Light, with shadows that suit it',
-        scheme: 'light',
-        tokens: {
-            '--bg': '#f6f7f9',
-            '--panel': '#ffffff',
-            '--panel-2': '#f0f2f5',
-            '--border': '#e4e8ec',
-            '--border-strong': '#8792a1',
-            '--text': '#191d23',
-            '--muted': '#5d6773',
-            '--accent': '#0e7872',
-            '--accent-dim': '#7fbdb8',
-            '--on-accent': '#ffffff',
-            // The base set is tuned for a dark panel. Unoverridden, `--good` was
-            // 1.74:1 on white -- a `running` pill nobody could read.
-            '--good': '#1c7a4a',
-            '--warn': '#8a6216',
-            '--bad': '#b3312c',
-            // `#2f7fe6` was 3.96:1 on this theme's white panel -- the "information is
-            // blue" colour was measured on the dark base when it was added and never
-            // on a light one. Found by contrast.test.ts on its first run. This is the
-            // lightest step on the same hue that clears 4.5:1 on the panel *and* the
-            // page, with room: 5.24 on white, 4.88 on the page.
-            '--info': '#216bc9',
-            // Black shadows are right on a dark UI and muddy on a light one. This is
-            // the whole reason elevation had to become a token.
-            '--shadow-1': '0 4px 14px rgba(16, 24, 40, 0.08)',
-            '--shadow-2': '0 8px 24px rgba(16, 24, 40, 0.10)',
-            '--shadow-3': '0 12px 32px rgba(16, 24, 40, 0.12)',
-            '--scrim': 'rgba(16, 24, 40, 0.32)',
-        },
-    },
-};
+export const THEMES = { ...TF_THEMES, ...VALET_THEMES };
 export const DEFAULT_THEME = 'system';
 export function isTheme(name) {
     return typeof name === 'string' && name in THEMES;

package/dist/tokens.css CHANGED Viewed

@@ -238,6 +238,23 @@
    only ever passed because none of them sets a duration. "Outranks every
    theme" has to be true of a theme written by somebody who never read this
    file, and the cascade is the only thing that can make it so. */
+/*
+ * Three tokens derived from colour tokens, re-derived wherever a theme lands.
+ *
+ * Declared on `:root` alone, `--control`, `--illo-paper` and `--focus-ring`
+ * resolve their `var()` against the root's palette and are inherited as
+ * finished values. A theme applied to a subtree with `applyTheme(theme, el)`
+ * then gets the root's control surface and the root's focus ring under its own
+ * panels: found on 2026-09-05 as black inputs and a teal ring on a light theme
+ * painted beside a dark one. `data-theme` is the attribute `applyTheme` sets,
+ * so a themed element derives them again from its own values.
+ */
+[data-theme] {
+  --control: color-mix(in srgb, var(--panel-2) 62%, var(--panel));
+  --illo-paper: var(--panel);
+  --focus-ring: 0 0 0 2px var(--accent);
+}
 @media (prefers-reduced-motion: reduce) {
   :root {
     --dur-fast: 0s !important;