@wtfalch/design 0.2.0 → 0.3.1

package/dist/products/index.d.ts

@@ -0,0 +1,69 @@
+import type { ComponentProps } from 'react';
+import BrandDefault from '../components/Brand.js';
+import type { BrandName } from '../components/brandMarks.js';
+import { type Theme, type ThemeTokens } from '../themes/index.js';
+/**
+ * A product: the layer between the system and a theme.
+ *
+ * Three layers, each falling back to the one under it. The system is the
+ * components, the base values in `tokens.css`, the shared icons and
+ * illustrations. The product is its mark and its identity -- the tokens that
+ * make it itself under every theme: font, shape, density -- plus the themes it
+ * offers and the one it wears until somebody picks. The theme is a palette and
+ * a colour scheme, and anything else it deliberately changes.
+ *
+ * The middle layer is what lets a theme be shared between products. A theme
+ * is a sparse map, and what it is sparse *over* decides what a silent token
+ * shows: over the base it shows tf, over the product it shows the product.
+ * Before this layer valet's two palettes each restated valet's font and
+ * corners, because there was nowhere else to put them.
+ *
+ * A site is one product, so each ships as one entry -- `@wtfalch/design/valet`
+ * and `valet.css` -- where `Brand`, `THEMES` and `applyTheme` are the
+ * product's. This module is the neutral view of all of them, which is what the
+ * gallery reads.
+ */
+export interface Product {
+    /** The id: the mark's row in `brandMarks.ts` and the stem of the CSS entry. */
+    name: BrandName;
+    /** On `:root` in the product's stylesheet, and under every palette when one
+     *  is applied. Empty for a product the base values already describe. */
+    identity: Partial<ThemeTokens>;
+    /** Keyed by the id `applyTheme` takes. */
+    themes: Record<string, Theme>;
+    /** Worn until somebody picks; written on `:root` when no `data-theme` is set. */
+    defaultTheme: string;
+}
+/** Every product, by the name of its mark. */
+export declare const PRODUCTS: {
+    readonly tf: Product;
+    readonly valet: Product;
+};
+/** Declare a product, so a default that is not a theme or a key `applyTheme`
+ *  would not use is an error where it is written. */
+export declare function defineProduct(product: Product): Product;
+/**
+ * A theme as the product wears it: the palette over the identity.
+ *
+ * An id the product does not offer resolves to the product's default rather
+ * than the package's, so a valet setting that remembers a theme valet has
+ * since dropped comes up as valet, not as tf.
+ */
+export declare function productTheme(product: Product, theme?: string | Theme): Theme;
+type BrandProps = ComponentProps<typeof BrandDefault>;
+/**
+ * The package, as one product.
+ *
+ * `Brand` defaults to the product's mark and still takes a name. `applyTheme`
+ * resolves against the product's themes and writes the identity under the
+ * palette, so it holds even where the product's stylesheet is not the one
+ * loaded. The product entries are this, exported.
+ */
+export declare function bindProduct(product: Product): {
+    product: Product;
+    Brand: (props: BrandProps) => import("react").JSX.Element;
+    THEMES: Record<string, Theme>;
+    DEFAULT_THEME: string;
+    applyTheme: (theme?: string | Theme, el?: HTMLElement) => void;
+};
+export {};

package/dist/products/index.js

@@ -0,0 +1,54 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import BrandDefault from '../components/Brand.js';
+import { applyTheme } from '../themes/index.js';
+import { themeId } from '../themes/css.js';
+import { tf } from './tf.js';
+import { valet } from './valet.js';
+/** Every product, by the name of its mark. */
+export const PRODUCTS = { tf, valet };
+/** Declare a product, so a default that is not a theme or a key `applyTheme`
+ *  would not use is an error where it is written. */
+export function defineProduct(product) {
+    if (!(product.defaultTheme in product.themes)) {
+        throw new Error(`product "${product.name}" defaults to "${product.defaultTheme}", which is not one of its themes`);
+    }
+    for (const [id, theme] of Object.entries(product.themes)) {
+        if (themeId(theme) !== id) {
+            throw new Error(`theme "${theme.name}" is keyed "${id}", but applyTheme calls it "${themeId(theme)}"`);
+        }
+    }
+    return product;
+}
+/**
+ * A theme as the product wears it: the palette over the identity.
+ *
+ * An id the product does not offer resolves to the product's default rather
+ * than the package's, so a valet setting that remembers a theme valet has
+ * since dropped comes up as valet, not as tf.
+ */
+export function productTheme(product, theme = product.defaultTheme) {
+    const resolved = typeof theme === 'string'
+        ? (product.themes[theme] ?? product.themes[product.defaultTheme])
+        : theme;
+    return { ...resolved, tokens: { ...product.identity, ...resolved.tokens } };
+}
+/**
+ * The package, as one product.
+ *
+ * `Brand` defaults to the product's mark and still takes a name. `applyTheme`
+ * resolves against the product's themes and writes the identity under the
+ * palette, so it holds even where the product's stylesheet is not the one
+ * loaded. The product entries are this, exported.
+ */
+export function bindProduct(product) {
+    function Brand(props) {
+        return _jsx(BrandDefault, { ...props, name: props.name ?? product.name });
+    }
+    return {
+        product,
+        Brand,
+        THEMES: product.themes,
+        DEFAULT_THEME: product.defaultTheme,
+        applyTheme: (theme = product.defaultTheme, el) => applyTheme(productTheme(product, theme), el),
+    };
+}

package/dist/products/tf.d.ts

@@ -0,0 +1,32 @@
+import type { Theme } from '../themes/index.js';
+import type { Product } from './index.js';
+/**
+ * tf's themes: the three the package shipped with, and the ones the gallery
+ * was photographed in first.
+ *
+ * `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 in `base.css`, so following the OS is a choice among the others
+ * rather than a rule above them.
+ */
+export declare const system: Theme;
+export declare const night: Theme;
+export declare const paper: Theme;
+/** Keyed by the name `applyTheme` takes, which is `name` lowercased. */
+export declare const TF_THEMES: {
+    readonly system: Theme;
+    readonly night: Theme;
+    readonly paper: Theme;
+};
+/**
+ * tf, the product.
+ *
+ * Its identity is empty on purpose: `tokens.css` carries tf's font, shape and
+ * density as the base values, so there is nothing to lay over them. `system`
+ * is the default because following the OS is the choice a tool open all day
+ * should make for you -- and because it is a `prefers-color-scheme` rule
+ * rather than a palette, tf's stylesheet writes no default on `:root`; tf sets
+ * `data-theme` before the bundle loads, as it always has.
+ */
+export declare const tf: Product;

package/dist/products/tf.js

@@ -0,0 +1,104 @@
+/**
+ * tf's themes: the three the package shipped with, and the ones the gallery
+ * was photographed in first.
+ *
+ * `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 in `base.css`, so following the OS is a choice among the others
+ * rather than a rule above them.
+ */
+export const 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: {},
+};
+/**
+ * The dark palette, written out rather than inherited.
+ *
+ * `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',
+};
+export const night = {
+    name: 'Night',
+    note: 'The dark palette, fixed — ignores the OS',
+    scheme: 'dark',
+    tokens: NIGHT,
+};
+export const 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)',
+    },
+};
+/** Keyed by the name `applyTheme` takes, which is `name` lowercased. */
+export const TF_THEMES = { system, night, paper };
+/**
+ * tf, the product.
+ *
+ * Its identity is empty on purpose: `tokens.css` carries tf's font, shape and
+ * density as the base values, so there is nothing to lay over them. `system`
+ * is the default because following the OS is the choice a tool open all day
+ * should make for you -- and because it is a `prefers-color-scheme` rule
+ * rather than a palette, tf's stylesheet writes no default on `:root`; tf sets
+ * `data-theme` before the bundle loads, as it always has.
+ */
+export const tf = {
+    name: 'tf',
+    identity: {},
+    themes: TF_THEMES,
+    defaultTheme: 'system',
+};

package/dist/products/valet.d.ts

@@ -0,0 +1,23 @@
+import type { Theme, ThemeTokens } from '../themes/index.js';
+import type { Product } from './index.js';
+/**
+ * valet's identity: what it is under every theme.
+ *
+ * The fonts are named, not shipped. `--font` reads a `--font-sans` variable
+ * the app defines with whatever loads its fonts, and falls back to the family
+ * by name; the gallery loads both families from `gallery/public/fonts` so the
+ * specimens are photographed in them. Sharper corners than the package
+ * default, because a console is read in rows and columns and a large radius
+ * rounds the grid away.
+ */
+export declare const VALET_IDENTITY: Partial<ThemeTokens>;
+export declare const light: Theme;
+export declare const night: Theme;
+/** Keyed by the name `applyTheme` takes: `name` lowercased, spaces to hyphens. */
+export declare const VALET_THEMES: {
+    readonly valet: Theme;
+    readonly 'valet-night': Theme;
+};
+/** valet, the product: its badge in `brandMarks.ts`, the identity above, the
+ *  two palettes, and light until somebody picks. */
+export declare const valet: Product;

package/dist/products/valet.js

@@ -0,0 +1,103 @@
+/**
+ * valet's two palettes.
+ *
+ * One hue that belongs to nothing else. The accent is an indigo, chosen so it
+ * sits apart from all four status tones: good is green, warn is amber, bad is
+ * red, and info is a cyan rather than a blue so a link and an information pill
+ * cannot be confused at a glance. The accent is what a person acts on; the
+ * tones are what the system says. They never share a colour.
+ *
+ * Every colour is measured, not judged: `contrast.test.ts` holds both palettes
+ * to the same pairs as tf's.
+ *
+ * The palettes name colours and nothing else. What makes valet valet under
+ * either of them -- the type and the corners -- is the identity below, on
+ * `:root` in valet's stylesheet and under every palette `applyTheme` lays on.
+ * Both palettes used to restate it, which is the shape that breaks the moment
+ * a theme is shared between products: silent on the font, it would have fallen
+ * back to tf's.
+ */
+const FONT = 'var(--font-sans, "IBM Plex Sans"), -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif';
+const FONT_MONO = 'var(--font-mono, "JetBrains Mono"), ui-monospace, SFMono-Regular, Menlo, monospace';
+/**
+ * valet's identity: what it is under every theme.
+ *
+ * The fonts are named, not shipped. `--font` reads a `--font-sans` variable
+ * the app defines with whatever loads its fonts, and falls back to the family
+ * by name; the gallery loads both families from `gallery/public/fonts` so the
+ * specimens are photographed in them. Sharper corners than the package
+ * default, because a console is read in rows and columns and a large radius
+ * rounds the grid away.
+ */
+export const VALET_IDENTITY = {
+    '--font': FONT,
+    '--font-mono': FONT_MONO,
+    '--radius-sm': '2px',
+    '--radius': '4px',
+    '--radius-md': '6px',
+    '--radius-lg': '10px',
+};
+export const light = {
+    name: 'valet',
+    note: 'Light. Ink on paper, indigo where you act.',
+    scheme: 'light',
+    tokens: {
+        '--bg': '#f4f5f8',
+        '--panel': '#ffffff',
+        '--panel-2': '#eceef3',
+        '--border': '#dcdfe7',
+        '--border-strong': '#7b8597',
+        '--text': '#171a21',
+        '--muted': '#5b6474',
+        '--accent': '#4f46e5',
+        '--accent-dim': '#a9a4f0',
+        '--on-accent': '#ffffff',
+        '--good': '#1b7f4b',
+        '--warn': '#8a5f0a',
+        '--bad': '#bf3a31',
+        '--info': '#0e6f8e',
+        '--app-bg': '#f4f5f8',
+        // Black shadows muddy a light surface; these carry the page's own ink.
+        '--shadow-1': '0 4px 14px rgba(23, 26, 33, 0.08)',
+        '--shadow-2': '0 8px 24px rgba(23, 26, 33, 0.10)',
+        '--shadow-3': '0 12px 32px rgba(23, 26, 33, 0.12)',
+        '--scrim': 'rgba(23, 26, 33, 0.32)',
+    },
+};
+export const night = {
+    name: 'valet night',
+    note: 'Dark. The same ink, lit from behind.',
+    scheme: 'dark',
+    tokens: {
+        '--bg': '#0c0f14',
+        '--panel': '#141820',
+        '--panel-2': '#1b2029',
+        '--border': '#262c37',
+        '--border-strong': '#616b7d',
+        '--text': '#e8eaf0',
+        '--muted': '#9ba4b5',
+        '--accent': '#8f88ff',
+        '--accent-dim': '#3f3a8f',
+        // Near-black on the pale indigo, 6.46:1. White would be 2.6:1.
+        '--on-accent': '#0d0b2e',
+        '--good': '#5fcb8f',
+        '--warn': '#e2ae58',
+        '--bad': '#f28b84',
+        '--info': '#57c4e8',
+        '--app-bg': '#0c0f14',
+        '--shadow-1': '0 6px 20px rgba(0, 0, 0, 0.28)',
+        '--shadow-2': '0 8px 28px rgba(0, 0, 0, 0.34)',
+        '--shadow-3': '0 10px 34px rgba(0, 0, 0, 0.38)',
+        '--scrim': 'rgba(0, 0, 0, 0.5)',
+    },
+};
+/** Keyed by the name `applyTheme` takes: `name` lowercased, spaces to hyphens. */
+export const VALET_THEMES = { valet: light, 'valet-night': night };
+/** valet, the product: its badge in `brandMarks.ts`, the identity above, the
+ *  two palettes, and light until somebody picks. */
+export const valet = {
+    name: 'valet',
+    identity: VALET_IDENTITY,
+    themes: VALET_THEMES,
+    defaultTheme: 'valet',
+};