@adea-ai/themes 0.3.2 → 0.4.1

package/dist/accents.d.ts

@@ -0,0 +1,150 @@
+/**
+ * The accent axis.
+ *
+ * A theme has one interactive colour — its primary — and the accent axis lets a
+ * user replace it without changing the theme. That is a different question from
+ * "which palette do you want": a user may like Catppuccin's surfaces and still want
+ * a violet primary, and a product may ship a brand colour that has to survive every
+ * theme in the catalogue.
+ *
+ * ## Why the presets live here
+ *
+ * They are colour data with a light/dark pair per preset — structurally the same
+ * thing as a theme's primary, and the last colour a consumer should have to author
+ * itself. Keeping them in a consumer meant two things that must agree lived in two
+ * places: the preset list, and the CSS blocks generated from it. They were written
+ * by hand in both, and they drifted — the generated default moved its hover *toward*
+ * the canvas while every hand-written accent moved *away*, so the default primary
+ * button hovered backwards and picking any accent silently fixed it.
+ *
+ * Here the values and the derivation are one module, so a consumer emits both from
+ * the same rule and cannot produce that disagreement.
+ *
+ * ## The hover rule
+ *
+ * A hovered primary moves **away from the canvas**, which is what makes it read as
+ * hovered rather than as a second, slightly different colour.
+ *
+ * Two rules were tried here before this one, and both are worth recording because
+ * each looks right until it is measured:
+ *
+ * - **Toward `--background`** — what the consumer used to do. Inverted in both
+ *   appearances: it moves the button toward the page it sits on, so a hovered button
+ *   recedes.
+ * - **Toward `--foreground`** — correct in principle, since the foreground is
+ *   normally away from the canvas, and wrong in practice: a dark theme's foreground
+ *   is mid-lightness (`0.79` in the default), so an accent lighter than that — the
+ *   dark green is `0.80` — moves *toward* the canvas by a hair.
+ * - **Toward white or black** — always the right direction, but a *proportional*
+ *   step: a mid-lightness light accent moves ~0.10 and a pale dark accent ~0.03, so
+ *   the same rule gives one appearance a hover twice as strong as the other's.
+ *
+ * A uniform step needs a resolved value, which is why {@link primaryHover} returns
+ * one and why the tint below can stay an expression. `shiftLightness` is what keeps
+ * the step uniform *and* the hue intact — a mix toward a neutral cannot do both.
+ */
+import type { ThemeAppearance } from './schema';
+/** One accent preset: a named primary, per appearance. */
+export type AccentPreset = {
+    /** The `data-accent` value. */
+    id: string;
+    label: string;
+    /** What the preset is for, in a gallery or a picker. */
+    description: string;
+    /** The accent as it appears on a light theme. */
+    light: string;
+    /** The accent as it appears on a dark theme. */
+    dark: string;
+};
+/**
+ * The presets.
+ *
+ * Each is a pair rather than one colour, because the same accent cannot be one
+ * value across both appearances: a violet that reads as vivid on a dark canvas is
+ * muddy on a light one, and the deep form that works on light is dull on dark. The
+ * pairs below are chosen so each appearance gets the vibrancy the other's value
+ * would lose.
+ */
+export declare const ACCENTS: readonly AccentPreset[];
+/** The accent ids, for validating a stored preference without loading the data. */
+export declare const ACCENT_IDS: readonly string[];
+/** Look a preset up by id. */
+export declare function getAccent(id: string): AccentPreset | undefined;
+/** The accent's value for one appearance. */
+export declare function accentValue(preset: AccentPreset, appearance: ThemeAppearance): string;
+/**
+ * The label to draw on an accent fill: black or white, whichever wins on contrast.
+ *
+ * Measured rather than conventional. The usual convention is "white on a coloured
+ * fill", which is wrong for the bright half of this set — white on `#a78bfa` is
+ * about 2.1:1, and black on it is about 9.9:1. That is why the same accent carries a
+ * black label in dark mode and a white one in light: the pair is designed so the
+ * polarity flips, and the label has to flip with it.
+ */
+export declare function accentForeground(accent: string): string;
+/** The contrast the chosen label achieves, for validation and reporting. */
+export declare function accentForegroundContrast(accent: string): number;
+/**
+ * How far a hovered primary moves along lightness.
+ *
+ * A **uniform step**, not a proportional one, and the difference matters. Mixing a
+ * fixed share toward white or black moves an accent by a share of its headroom, so
+ * the same rule gives a mid-lightness light accent a step of ~0.10 and a pale dark
+ * accent one of ~0.03 — a hover that feels twice as strong in one appearance as the
+ * other, and nearly invisible on the palest accent.
+ *
+ * 0.05 is the step this system's accents were already hand-written with, so the
+ * accents keep the appearance they had while the rule becomes one value.
+ */
+export declare const ACCENT_HOVER_STEP = 0.05;
+/**
+ * The hovered primary, as a resolved colour.
+ *
+ * Resolved rather than expressed as a `color-mix()`, because a uniform step cannot
+ * be written as a mix — see {@link ACCENT_HOVER_STEP}. That means it does **not**
+ * follow `--primary` on its own, so a consumer that applies themes at runtime has to
+ * write this token too; the alternative is a hover left over from the previous
+ * theme's primary. `themeCssVariables` includes it for that reason.
+ *
+ * The direction is away from the canvas: darker on a light theme, lighter on a dark
+ * one. `shiftLightness` keeps chroma and hue and damps chroma near the extremes, so a
+ * hovered accent stays the same colour rather than washing out toward grey.
+ */
+export declare function primaryHover(primary: string, appearance: ThemeAppearance): string;
+/**
+ * How much of the primary a tint carries, per appearance.
+ *
+ * Not one value, because a tint's visibility depends on what it is tinted onto: the
+ * same alpha over a near-black surface reads as nothing, and over a near-white one
+ * reads as a wash. The dark value is the larger for exactly that reason.
+ *
+ * This one *is* a `color-mix()`, because a tint is a share of the primary by nature
+ * and follows `--primary` correctly at runtime.
+ */
+export declare const ACCENT_SUBTLE_ALPHA: Readonly<Record<ThemeAppearance, number>>;
+/**
+ * The tint expression, for any primary.
+ *
+ * Takes the appearance because the alpha is appearance-dependent — see
+ * {@link ACCENT_SUBTLE_ALPHA}.
+ */
+export declare function primarySubtleCss(appearance: ThemeAppearance, primaryVariable?: string): string;
+/**
+ * The five declarations an accent sets, as CSS values.
+ *
+ * `primary`, `primaryForeground` and `ring` are resolved colours; `primaryHover` and
+ * `primarySubtle` are expressions, for the reason in the module comment. A consumer
+ * writes them as custom properties and the rules hold for every theme and every
+ * accent at once.
+ */
+export type AccentRoles = {
+    primary: string;
+    primaryForeground: string;
+    primaryHover: string;
+    primarySubtle: string;
+    ring: string;
+};
+export declare function accentRoles(preset: AccentPreset, appearance: ThemeAppearance, 
+/** The property the subtle tint is built from. A consumer may pass its own alias. */
+primaryVariable?: string): AccentRoles;
+//# sourceMappingURL=accents.d.ts.map

package/dist/accents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"accents.d.ts","sourceRoot":"","sources":["../src/accents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAI/C,0DAA0D;AAC1D,MAAM,MAAM,YAAY,GAAG;IACzB,+BAA+B;IAC/B,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAA;IACnB,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAA;IACb,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,OAAO,EAAE,SAAS,YAAY,EA2CzC,CAAA;AAEF,mFAAmF;AACnF,eAAO,MAAM,UAAU,EAAE,SAAS,MAAM,EAAsD,CAAA;AAE9F,8BAA8B;AAC9B,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAE9D;AAED,6CAA6C;AAC7C,wBAAgB,WAAW,CAAC,MAAM,EAAE,YAAY,EAAE,UAAU,EAAE,eAAe,GAAG,MAAM,CAErF;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAQvD;AAED,4EAA4E;AAC5E,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAI/D;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iBAAiB,OAAO,CAAA;AAErC;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,eAAe,GAAG,MAAM,CAKjF;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,MAAM,CAAC,eAAe,EAAE,MAAM,CAAC,CAGxE,CAAA;AAEF;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,eAAe,EAAE,eAAe,SAAc,GAAG,MAAM,CAEnG;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,EAAE,MAAM,CAAA;IACf,iBAAiB,EAAE,MAAM,CAAA;IACzB,YAAY,EAAE,MAAM,CAAA;IACpB,aAAa,EAAE,MAAM,CAAA;IACrB,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED,wBAAgB,WAAW,CACzB,MAAM,EAAE,YAAY,EACpB,UAAU,EAAE,eAAe;AAC3B,qFAAqF;AACrF,eAAe,SAAc,GAC5B,WAAW,CAYb"}

package/dist/accents.js

@@ -0,0 +1,205 @@
+/**
+ * The accent axis.
+ *
+ * A theme has one interactive colour — its primary — and the accent axis lets a
+ * user replace it without changing the theme. That is a different question from
+ * "which palette do you want": a user may like Catppuccin's surfaces and still want
+ * a violet primary, and a product may ship a brand colour that has to survive every
+ * theme in the catalogue.
+ *
+ * ## Why the presets live here
+ *
+ * They are colour data with a light/dark pair per preset — structurally the same
+ * thing as a theme's primary, and the last colour a consumer should have to author
+ * itself. Keeping them in a consumer meant two things that must agree lived in two
+ * places: the preset list, and the CSS blocks generated from it. They were written
+ * by hand in both, and they drifted — the generated default moved its hover *toward*
+ * the canvas while every hand-written accent moved *away*, so the default primary
+ * button hovered backwards and picking any accent silently fixed it.
+ *
+ * Here the values and the derivation are one module, so a consumer emits both from
+ * the same rule and cannot produce that disagreement.
+ *
+ * ## The hover rule
+ *
+ * A hovered primary moves **away from the canvas**, which is what makes it read as
+ * hovered rather than as a second, slightly different colour.
+ *
+ * Two rules were tried here before this one, and both are worth recording because
+ * each looks right until it is measured:
+ *
+ * - **Toward `--background`** — what the consumer used to do. Inverted in both
+ *   appearances: it moves the button toward the page it sits on, so a hovered button
+ *   recedes.
+ * - **Toward `--foreground`** — correct in principle, since the foreground is
+ *   normally away from the canvas, and wrong in practice: a dark theme's foreground
+ *   is mid-lightness (`0.79` in the default), so an accent lighter than that — the
+ *   dark green is `0.80` — moves *toward* the canvas by a hair.
+ * - **Toward white or black** — always the right direction, but a *proportional*
+ *   step: a mid-lightness light accent moves ~0.10 and a pale dark accent ~0.03, so
+ *   the same rule gives one appearance a hover twice as strong as the other's.
+ *
+ * A uniform step needs a resolved value, which is why {@link primaryHover} returns
+ * one and why the tint below can stay an expression. `shiftLightness` is what keeps
+ * the step uniform *and* the hue intact — a mix toward a neutral cannot do both.
+ */
+import { contrastRatio, formatOklch, parseColor, shiftLightness } from './oklch';
+/**
+ * The presets.
+ *
+ * Each is a pair rather than one colour, because the same accent cannot be one
+ * value across both appearances: a violet that reads as vivid on a dark canvas is
+ * muddy on a light one, and the deep form that works on light is dull on dark. The
+ * pairs below are chosen so each appearance gets the vibrancy the other's value
+ * would lose.
+ */
+export const ACCENTS = Object.freeze([
+    {
+        id: 'violet',
+        label: 'Violet',
+        description: 'The default brand accent.',
+        light: '#6d28d9',
+        dark: '#a78bfa',
+    },
+    {
+        id: 'blue',
+        label: 'Blue',
+        description: 'Cool and conventional. Reads as informational.',
+        light: '#2563eb',
+        dark: '#60a5fa',
+    },
+    {
+        id: 'green',
+        label: 'Green',
+        description: 'Reads as confirmatory, which competes with the success status.',
+        light: '#15803d',
+        dark: '#4ade80',
+    },
+    {
+        id: 'amber',
+        label: 'Amber',
+        description: 'Warm and attention-drawing. Competes with the warning status.',
+        light: '#b45309',
+        dark: '#fbbf24',
+    },
+    {
+        id: 'cyan',
+        label: 'Cyan',
+        description: 'Quiet and technical. The least saturated of the set.',
+        light: '#0e7490',
+        dark: '#22d3ee',
+    },
+    {
+        id: 'pink',
+        label: 'Pink',
+        description: 'The loudest of the set. Use where the accent is decorative.',
+        light: '#be185d',
+        dark: '#f472b6',
+    },
+]);
+/** The accent ids, for validating a stored preference without loading the data. */
+export const ACCENT_IDS = Object.freeze(ACCENTS.map((accent) => accent.id));
+/** Look a preset up by id. */
+export function getAccent(id) {
+    return ACCENTS.find((accent) => accent.id === id);
+}
+/** The accent's value for one appearance. */
+export function accentValue(preset, appearance) {
+    return appearance === 'light' ? preset.light : preset.dark;
+}
+/**
+ * The label to draw on an accent fill: black or white, whichever wins on contrast.
+ *
+ * Measured rather than conventional. The usual convention is "white on a coloured
+ * fill", which is wrong for the bright half of this set — white on `#a78bfa` is
+ * about 2.1:1, and black on it is about 9.9:1. That is why the same accent carries a
+ * black label in dark mode and a white one in light: the pair is designed so the
+ * polarity flips, and the label has to flip with it.
+ */
+export function accentForeground(accent) {
+    const fill = parseColor(accent);
+    if (!fill)
+        return 'oklch(1 0 0)';
+    const black = { l: 0, c: 0, h: 0 };
+    const white = { l: 1, c: 0, h: 0 };
+    const best = contrastRatio(black, fill) >= contrastRatio(white, fill) ? black : white;
+    return formatOklch(best);
+}
+/** The contrast the chosen label achieves, for validation and reporting. */
+export function accentForegroundContrast(accent) {
+    const fill = parseColor(accent);
+    if (!fill)
+        return 0;
+    return contrastRatio(parseColor(accentForeground(accent)), fill);
+}
+/**
+ * How far a hovered primary moves along lightness.
+ *
+ * A **uniform step**, not a proportional one, and the difference matters. Mixing a
+ * fixed share toward white or black moves an accent by a share of its headroom, so
+ * the same rule gives a mid-lightness light accent a step of ~0.10 and a pale dark
+ * accent one of ~0.03 — a hover that feels twice as strong in one appearance as the
+ * other, and nearly invisible on the palest accent.
+ *
+ * 0.05 is the step this system's accents were already hand-written with, so the
+ * accents keep the appearance they had while the rule becomes one value.
+ */
+export const ACCENT_HOVER_STEP = 0.05;
+/**
+ * The hovered primary, as a resolved colour.
+ *
+ * Resolved rather than expressed as a `color-mix()`, because a uniform step cannot
+ * be written as a mix — see {@link ACCENT_HOVER_STEP}. That means it does **not**
+ * follow `--primary` on its own, so a consumer that applies themes at runtime has to
+ * write this token too; the alternative is a hover left over from the previous
+ * theme's primary. `themeCssVariables` includes it for that reason.
+ *
+ * The direction is away from the canvas: darker on a light theme, lighter on a dark
+ * one. `shiftLightness` keeps chroma and hue and damps chroma near the extremes, so a
+ * hovered accent stays the same colour rather than washing out toward grey.
+ */
+export function primaryHover(primary, appearance) {
+    const parsed = parseColor(primary);
+    if (!parsed)
+        return primary;
+    const delta = appearance === 'light' ? -ACCENT_HOVER_STEP : ACCENT_HOVER_STEP;
+    return formatOklch(shiftLightness(parsed, delta));
+}
+/**
+ * How much of the primary a tint carries, per appearance.
+ *
+ * Not one value, because a tint's visibility depends on what it is tinted onto: the
+ * same alpha over a near-black surface reads as nothing, and over a near-white one
+ * reads as a wash. The dark value is the larger for exactly that reason.
+ *
+ * This one *is* a `color-mix()`, because a tint is a share of the primary by nature
+ * and follows `--primary` correctly at runtime.
+ */
+export const ACCENT_SUBTLE_ALPHA = Object.freeze({
+    light: 10,
+    dark: 16,
+});
+/**
+ * The tint expression, for any primary.
+ *
+ * Takes the appearance because the alpha is appearance-dependent — see
+ * {@link ACCENT_SUBTLE_ALPHA}.
+ */
+export function primarySubtleCss(appearance, primaryVariable = '--primary') {
+    return `color-mix(in oklch, var(${primaryVariable}) ${ACCENT_SUBTLE_ALPHA[appearance]}%, transparent)`;
+}
+export function accentRoles(preset, appearance, 
+/** The property the subtle tint is built from. A consumer may pass its own alias. */
+primaryVariable = '--primary') {
+    const value = accentValue(preset, appearance);
+    const parsed = parseColor(value);
+    const primary = parsed ? formatOklch(parsed) : value;
+    return {
+        primary,
+        primaryForeground: accentForeground(value),
+        primaryHover: primaryHover(value, appearance),
+        primarySubtle: primarySubtleCss(appearance, primaryVariable),
+        ring: primary,
+    };
+}
+//# sourceMappingURL=accents.js.map

package/dist/accents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"accents.js","sourceRoot":"","sources":["../src/accents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAIH,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAehF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,OAAO,GAA4B,MAAM,CAAC,MAAM,CAAC;IAC5D;QACE,EAAE,EAAE,QAAQ;QACZ,KAAK,EAAE,QAAQ;QACf,WAAW,EAAE,2BAA2B;QACxC,KAAK,EAAE,SAAS;QAChB,IAAI,EAAE,SAAS;KAChB;IACD;QACE,EAAE,EAAE,MAAM;QACV,KAAK,EAAE,MAAM;QACb,WAAW,EAAE,gDAAgD;QAC7D,KAAK,EAAE,SAAS;QAChB,IAAI,EAAE,SAAS;KAChB;IACD;QACE,EAAE,EAAE,OAAO;QACX,KAAK,EAAE,OAAO;QACd,WAAW,EAAE,gEAAgE;QAC7E,KAAK,EAAE,SAAS;QAChB,IAAI,EAAE,SAAS;KAChB;IACD;QACE,EAAE,EAAE,OAAO;QACX,KAAK,EAAE,OAAO;QACd,WAAW,EAAE,+DAA+D;QAC5E,KAAK,EAAE,SAAS;QAChB,IAAI,EAAE,SAAS;KAChB;IACD;QACE,EAAE,EAAE,MAAM;QACV,KAAK,EAAE,MAAM;QACb,WAAW,EAAE,sDAAsD;QACnE,KAAK,EAAE,SAAS;QAChB,IAAI,EAAE,SAAS;KAChB;IACD;QACE,EAAE,EAAE,MAAM;QACV,KAAK,EAAE,MAAM;QACb,WAAW,EAAE,6DAA6D;QAC1E,KAAK,EAAE,SAAS;QAChB,IAAI,EAAE,SAAS;KAChB;CACF,CAAC,CAAA;AAEF,mFAAmF;AACnF,MAAM,CAAC,MAAM,UAAU,GAAsB,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAA;AAE9F,8BAA8B;AAC9B,MAAM,UAAU,SAAS,CAAC,EAAU;IAClC,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC,CAAA;AACnD,CAAC;AAED,6CAA6C;AAC7C,MAAM,UAAU,WAAW,CAAC,MAAoB,EAAE,UAA2B;IAC3E,OAAO,UAAU,KAAK,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAA;AAC5D,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAc;IAC7C,MAAM,IAAI,GAAG,UAAU,CAAC,MAAM,CAAC,CAAA;IAC/B,IAAI,CAAC,IAAI;QAAE,OAAO,cAAc,CAAA;IAEhC,MAAM,KAAK,GAAU,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAA;IACzC,MAAM,KAAK,GAAU,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAA;IACzC,MAAM,IAAI,GAAG,aAAa,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,aAAa,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAA;IACrF,OAAO,WAAW,CAAC,IAAI,CAAC,CAAA;AAC1B,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,wBAAwB,CAAC,MAAc;IACrD,MAAM,IAAI,GAAG,UAAU,CAAC,MAAM,CAAC,CAAA;IAC/B,IAAI,CAAC,IAAI;QAAE,OAAO,CAAC,CAAA;IACnB,OAAO,aAAa,CAAC,UAAU,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAE,EAAE,IAAI,CAAC,CAAA;AACnE,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,CAAA;AAErC;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe,EAAE,UAA2B;IACvE,MAAM,MAAM,GAAG,UAAU,CAAC,OAAO,CAAC,CAAA;IAClC,IAAI,CAAC,MAAM;QAAE,OAAO,OAAO,CAAA;IAC3B,MAAM,KAAK,GAAG,UAAU,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,iBAAiB,CAAA;IAC7E,OAAO,WAAW,CAAC,cAAc,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAA;AACnD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAA8C,MAAM,CAAC,MAAM,CAAC;IAC1F,KAAK,EAAE,EAAE;IACT,IAAI,EAAE,EAAE;CACT,CAAC,CAAA;AAEF;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,UAA2B,EAAE,eAAe,GAAG,WAAW;IACzF,OAAO,2BAA2B,eAAe,KAAK,mBAAmB,CAAC,UAAU,CAAC,iBAAiB,CAAA;AACxG,CAAC;AAkBD,MAAM,UAAU,WAAW,CACzB,MAAoB,EACpB,UAA2B;AAC3B,qFAAqF;AACrF,eAAe,GAAG,WAAW;IAE7B,MAAM,KAAK,GAAG,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;IAC7C,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,CAAA;IAChC,MAAM,OAAO,GAAG,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAA;IAEpD,OAAO;QACL,OAAO;QACP,iBAAiB,EAAE,gBAAgB,CAAC,KAAK,CAAC;QAC1C,YAAY,EAAE,YAAY,CAAC,KAAK,EAAE,UAAU,CAAC;QAC7C,aAAa,EAAE,gBAAgB,CAAC,UAAU,EAAE,eAAe,CAAC;QAC5D,IAAI,EAAE,OAAO;KACd,CAAA;AACH,CAAC"}

package/dist/index.d.ts

@@ -44,6 +44,8 @@
  */
 export type { AdeaAnsi, AdeaTheme, AdeaThemeColors, AdeaThemeRecord, AnsiKey, ThemeAppearance, ThemeColorKey, ThemeFamily, ThemeProvenance, } from './schema';
 export { ANSI_KEYS, THEME_COLOR_KEYS } from './schema';
+export type { AccentPreset, AccentRoles } from './accents';
+export { ACCENTS, ACCENT_HOVER_STEP, ACCENT_IDS, ACCENT_SUBTLE_ALPHA, accentForeground, accentForegroundContrast, accentRoles, accentValue, getAccent, primaryHover, primarySubtleCss, } from './accents';
 export { DEFAULT_THEME_IDS, getBase24Scheme, getTheme, hasTheme, resolveTheme, themeCount, themeFamilies, themeIds, themes, themesByAppearance, toTheme, } from './catalogue';
 export type { ContrastRepair, Oklch } from './oklch';
 export { contrastRatio, deltaEok, formatOklch, gamutMap, hexToOklch, inGamut, mix, oklchToHex, parseColor, parseOklch, relativeLuminance, repairContrast, shiftLightness, } from './oklch';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAGH,YAAY,EACV,QAAQ,EACR,SAAS,EACT,eAAe,EACf,eAAe,EACf,OAAO,EACP,eAAe,EACf,aAAa,EACb,WAAW,EACX,eAAe,GAChB,MAAM,UAAU,CAAA;AACjB,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAA;AAGtD,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,QAAQ,EACR,QAAQ,EACR,YAAY,EACZ,UAAU,EACV,aAAa,EACb,QAAQ,EACR,MAAM,EACN,kBAAkB,EAClB,OAAO,GACR,MAAM,aAAa,CAAA;AAGpB,YAAY,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AACpD,OAAO,EACL,aAAa,EACb,QAAQ,EACR,WAAW,EACX,QAAQ,EACR,UAAU,EACV,OAAO,EACP,GAAG,EACH,UAAU,EACV,UAAU,EACV,UAAU,EACV,iBAAiB,EACjB,cAAc,EACd,cAAc,GACf,MAAM,SAAS,CAAA;AAGhB,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AACzE,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,aAAa,GACd,MAAM,YAAY,CAAA;AAGnB,YAAY,EAAE,oBAAoB,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AACzF,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAG7D,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AACtD,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,mBAAmB,EACnB,WAAW,EACX,cAAc,EACd,IAAI,GACL,MAAM,UAAU,CAAA;AAGjB,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAChF,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,EACjB,QAAQ,GACT,MAAM,mBAAmB,CAAA;AAE1B,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAE/C,YAAY,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAChD,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AAE3F,YAAY,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAErD,YAAY,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AACjF,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAE9D,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAGH,YAAY,EACV,QAAQ,EACR,SAAS,EACT,eAAe,EACf,eAAe,EACf,OAAO,EACP,eAAe,EACf,aAAa,EACb,WAAW,EACX,eAAe,GAChB,MAAM,UAAU,CAAA;AACjB,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAA;AAEtD,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAC1D,OAAO,EACL,OAAO,EACP,iBAAiB,EACjB,UAAU,EACV,mBAAmB,EACnB,gBAAgB,EAChB,wBAAwB,EACxB,WAAW,EACX,WAAW,EACX,SAAS,EACT,YAAY,EACZ,gBAAgB,GACjB,MAAM,WAAW,CAAA;AAGlB,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,QAAQ,EACR,QAAQ,EACR,YAAY,EACZ,UAAU,EACV,aAAa,EACb,QAAQ,EACR,MAAM,EACN,kBAAkB,EAClB,OAAO,GACR,MAAM,aAAa,CAAA;AAGpB,YAAY,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AACpD,OAAO,EACL,aAAa,EACb,QAAQ,EACR,WAAW,EACX,QAAQ,EACR,UAAU,EACV,OAAO,EACP,GAAG,EACH,UAAU,EACV,UAAU,EACV,UAAU,EACV,iBAAiB,EACjB,cAAc,EACd,cAAc,GACf,MAAM,SAAS,CAAA;AAGhB,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AACzE,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,aAAa,GACd,MAAM,YAAY,CAAA;AAGnB,YAAY,EAAE,oBAAoB,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AACzF,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAG7D,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AACtD,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,mBAAmB,EACnB,WAAW,EACX,cAAc,EACd,IAAI,GACL,MAAM,UAAU,CAAA;AAGjB,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAChF,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,EACjB,QAAQ,GACT,MAAM,mBAAmB,CAAA;AAE1B,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAE/C,YAAY,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAChD,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AAE3F,YAAY,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAErD,YAAY,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AACjF,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAE9D,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA"}

package/dist/index.js

@@ -43,6 +43,7 @@
  * ```
  */
 export { ANSI_KEYS, THEME_COLOR_KEYS } from './schema';
+export { ACCENTS, ACCENT_HOVER_STEP, ACCENT_IDS, ACCENT_SUBTLE_ALPHA, accentForeground, accentForegroundContrast, accentRoles, accentValue, getAccent, primaryHover, primarySubtleCss, } from './accents';
 /* --- The catalogue ------------------------------------------------------ */
 export { DEFAULT_THEME_IDS, getBase24Scheme, getTheme, hasTheme, resolveTheme, themeCount, themeFamilies, themeIds, themes, themesByAppearance, toTheme, } from './catalogue';
 export { contrastRatio, deltaEok, formatOklch, gamutMap, hexToOklch, inGamut, mix, oklchToHex, parseColor, parseOklch, relativeLuminance, repairContrast, shiftLightness, } from './oklch';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAcH,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAA;AAEtD,8EAA8E;AAC9E,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,QAAQ,EACR,QAAQ,EACR,YAAY,EACZ,UAAU,EACV,aAAa,EACb,QAAQ,EACR,MAAM,EACN,kBAAkB,EAClB,OAAO,GACR,MAAM,aAAa,CAAA;AAIpB,OAAO,EACL,aAAa,EACb,QAAQ,EACR,WAAW,EACX,QAAQ,EACR,UAAU,EACV,OAAO,EACP,GAAG,EACH,UAAU,EACV,UAAU,EACV,UAAU,EACV,iBAAiB,EACjB,cAAc,EACd,cAAc,GACf,MAAM,SAAS,CAAA;AAIhB,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,aAAa,GACd,MAAM,YAAY,CAAA;AAInB,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAI7D,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,mBAAmB,EACnB,WAAW,EACX,cAAc,EACd,IAAI,GACL,MAAM,UAAU,CAAA;AAIjB,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,EACjB,QAAQ,GACT,MAAM,mBAAmB,CAAA;AAG1B,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAG/C,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AAG3F,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAGrD,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAE9D,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAcH,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAA;AAGtD,OAAO,EACL,OAAO,EACP,iBAAiB,EACjB,UAAU,EACV,mBAAmB,EACnB,gBAAgB,EAChB,wBAAwB,EACxB,WAAW,EACX,WAAW,EACX,SAAS,EACT,YAAY,EACZ,gBAAgB,GACjB,MAAM,WAAW,CAAA;AAElB,8EAA8E;AAC9E,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,QAAQ,EACR,QAAQ,EACR,YAAY,EACZ,UAAU,EACV,aAAa,EACb,QAAQ,EACR,MAAM,EACN,kBAAkB,EAClB,OAAO,GACR,MAAM,aAAa,CAAA;AAIpB,OAAO,EACL,aAAa,EACb,QAAQ,EACR,WAAW,EACX,QAAQ,EACR,UAAU,EACV,OAAO,EACP,GAAG,EACH,UAAU,EACV,UAAU,EACV,UAAU,EACV,iBAAiB,EACjB,cAAc,EACd,cAAc,GACf,MAAM,SAAS,CAAA;AAIhB,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,aAAa,GACd,MAAM,YAAY,CAAA;AAInB,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAI7D,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,mBAAmB,EACnB,WAAW,EACX,cAAc,EACd,IAAI,GACL,MAAM,UAAU,CAAA;AAIjB,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,EACjB,QAAQ,GACT,MAAM,mBAAmB,CAAA;AAG1B,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAG/C,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AAG3F,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAGrD,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAE9D,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adea-ai/themes",
-  "version": "0.3.2",
+  "version": "0.4.1",
   "description": "The Adea theme catalogue: semantic OKLCH themes normalized from upstream palettes, with Base24, terminal, CSS and syntax adapters.",
   "keywords": [
     "adea",
@@ -84,6 +84,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "bun run build",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "lint": "oxlint",
     "test": "bun test tests",

package/src/accents.ts

@@ -0,0 +1,249 @@
+/**
+ * The accent axis.
+ *
+ * A theme has one interactive colour — its primary — and the accent axis lets a
+ * user replace it without changing the theme. That is a different question from
+ * "which palette do you want": a user may like Catppuccin's surfaces and still want
+ * a violet primary, and a product may ship a brand colour that has to survive every
+ * theme in the catalogue.
+ *
+ * ## Why the presets live here
+ *
+ * They are colour data with a light/dark pair per preset — structurally the same
+ * thing as a theme's primary, and the last colour a consumer should have to author
+ * itself. Keeping them in a consumer meant two things that must agree lived in two
+ * places: the preset list, and the CSS blocks generated from it. They were written
+ * by hand in both, and they drifted — the generated default moved its hover *toward*
+ * the canvas while every hand-written accent moved *away*, so the default primary
+ * button hovered backwards and picking any accent silently fixed it.
+ *
+ * Here the values and the derivation are one module, so a consumer emits both from
+ * the same rule and cannot produce that disagreement.
+ *
+ * ## The hover rule
+ *
+ * A hovered primary moves **away from the canvas**, which is what makes it read as
+ * hovered rather than as a second, slightly different colour.
+ *
+ * Two rules were tried here before this one, and both are worth recording because
+ * each looks right until it is measured:
+ *
+ * - **Toward `--background`** — what the consumer used to do. Inverted in both
+ *   appearances: it moves the button toward the page it sits on, so a hovered button
+ *   recedes.
+ * - **Toward `--foreground`** — correct in principle, since the foreground is
+ *   normally away from the canvas, and wrong in practice: a dark theme's foreground
+ *   is mid-lightness (`0.79` in the default), so an accent lighter than that — the
+ *   dark green is `0.80` — moves *toward* the canvas by a hair.
+ * - **Toward white or black** — always the right direction, but a *proportional*
+ *   step: a mid-lightness light accent moves ~0.10 and a pale dark accent ~0.03, so
+ *   the same rule gives one appearance a hover twice as strong as the other's.
+ *
+ * A uniform step needs a resolved value, which is why {@link primaryHover} returns
+ * one and why the tint below can stay an expression. `shiftLightness` is what keeps
+ * the step uniform *and* the hue intact — a mix toward a neutral cannot do both.
+ */
+
+import type { ThemeAppearance } from './schema'
+import type { Oklch } from './oklch'
+import { contrastRatio, formatOklch, parseColor, shiftLightness } from './oklch'
+
+/** One accent preset: a named primary, per appearance. */
+export type AccentPreset = {
+  /** The `data-accent` value. */
+  id: string
+  label: string
+  /** What the preset is for, in a gallery or a picker. */
+  description: string
+  /** The accent as it appears on a light theme. */
+  light: string
+  /** The accent as it appears on a dark theme. */
+  dark: string
+}
+
+/**
+ * The presets.
+ *
+ * Each is a pair rather than one colour, because the same accent cannot be one
+ * value across both appearances: a violet that reads as vivid on a dark canvas is
+ * muddy on a light one, and the deep form that works on light is dull on dark. The
+ * pairs below are chosen so each appearance gets the vibrancy the other's value
+ * would lose.
+ */
+export const ACCENTS: readonly AccentPreset[] = Object.freeze([
+  {
+    id: 'violet',
+    label: 'Violet',
+    description: 'The default brand accent.',
+    light: '#6d28d9',
+    dark: '#a78bfa',
+  },
+  {
+    id: 'blue',
+    label: 'Blue',
+    description: 'Cool and conventional. Reads as informational.',
+    light: '#2563eb',
+    dark: '#60a5fa',
+  },
+  {
+    id: 'green',
+    label: 'Green',
+    description: 'Reads as confirmatory, which competes with the success status.',
+    light: '#15803d',
+    dark: '#4ade80',
+  },
+  {
+    id: 'amber',
+    label: 'Amber',
+    description: 'Warm and attention-drawing. Competes with the warning status.',
+    light: '#b45309',
+    dark: '#fbbf24',
+  },
+  {
+    id: 'cyan',
+    label: 'Cyan',
+    description: 'Quiet and technical. The least saturated of the set.',
+    light: '#0e7490',
+    dark: '#22d3ee',
+  },
+  {
+    id: 'pink',
+    label: 'Pink',
+    description: 'The loudest of the set. Use where the accent is decorative.',
+    light: '#be185d',
+    dark: '#f472b6',
+  },
+])
+
+/** The accent ids, for validating a stored preference without loading the data. */
+export const ACCENT_IDS: readonly string[] = Object.freeze(ACCENTS.map((accent) => accent.id))
+
+/** Look a preset up by id. */
+export function getAccent(id: string): AccentPreset | undefined {
+  return ACCENTS.find((accent) => accent.id === id)
+}
+
+/** The accent's value for one appearance. */
+export function accentValue(preset: AccentPreset, appearance: ThemeAppearance): string {
+  return appearance === 'light' ? preset.light : preset.dark
+}
+
+/**
+ * The label to draw on an accent fill: black or white, whichever wins on contrast.
+ *
+ * Measured rather than conventional. The usual convention is "white on a coloured
+ * fill", which is wrong for the bright half of this set — white on `#a78bfa` is
+ * about 2.1:1, and black on it is about 9.9:1. That is why the same accent carries a
+ * black label in dark mode and a white one in light: the pair is designed so the
+ * polarity flips, and the label has to flip with it.
+ */
+export function accentForeground(accent: string): string {
+  const fill = parseColor(accent)
+  if (!fill) return 'oklch(1 0 0)'
+
+  const black: Oklch = { l: 0, c: 0, h: 0 }
+  const white: Oklch = { l: 1, c: 0, h: 0 }
+  const best = contrastRatio(black, fill) >= contrastRatio(white, fill) ? black : white
+  return formatOklch(best)
+}
+
+/** The contrast the chosen label achieves, for validation and reporting. */
+export function accentForegroundContrast(accent: string): number {
+  const fill = parseColor(accent)
+  if (!fill) return 0
+  return contrastRatio(parseColor(accentForeground(accent))!, fill)
+}
+
+/**
+ * How far a hovered primary moves along lightness.
+ *
+ * A **uniform step**, not a proportional one, and the difference matters. Mixing a
+ * fixed share toward white or black moves an accent by a share of its headroom, so
+ * the same rule gives a mid-lightness light accent a step of ~0.10 and a pale dark
+ * accent one of ~0.03 — a hover that feels twice as strong in one appearance as the
+ * other, and nearly invisible on the palest accent.
+ *
+ * 0.05 is the step this system's accents were already hand-written with, so the
+ * accents keep the appearance they had while the rule becomes one value.
+ */
+export const ACCENT_HOVER_STEP = 0.05
+
+/**
+ * The hovered primary, as a resolved colour.
+ *
+ * Resolved rather than expressed as a `color-mix()`, because a uniform step cannot
+ * be written as a mix — see {@link ACCENT_HOVER_STEP}. That means it does **not**
+ * follow `--primary` on its own, so a consumer that applies themes at runtime has to
+ * write this token too; the alternative is a hover left over from the previous
+ * theme's primary. `themeCssVariables` includes it for that reason.
+ *
+ * The direction is away from the canvas: darker on a light theme, lighter on a dark
+ * one. `shiftLightness` keeps chroma and hue and damps chroma near the extremes, so a
+ * hovered accent stays the same colour rather than washing out toward grey.
+ */
+export function primaryHover(primary: string, appearance: ThemeAppearance): string {
+  const parsed = parseColor(primary)
+  if (!parsed) return primary
+  const delta = appearance === 'light' ? -ACCENT_HOVER_STEP : ACCENT_HOVER_STEP
+  return formatOklch(shiftLightness(parsed, delta))
+}
+
+/**
+ * How much of the primary a tint carries, per appearance.
+ *
+ * Not one value, because a tint's visibility depends on what it is tinted onto: the
+ * same alpha over a near-black surface reads as nothing, and over a near-white one
+ * reads as a wash. The dark value is the larger for exactly that reason.
+ *
+ * This one *is* a `color-mix()`, because a tint is a share of the primary by nature
+ * and follows `--primary` correctly at runtime.
+ */
+export const ACCENT_SUBTLE_ALPHA: Readonly<Record<ThemeAppearance, number>> = Object.freeze({
+  light: 10,
+  dark: 16,
+})
+
+/**
+ * The tint expression, for any primary.
+ *
+ * Takes the appearance because the alpha is appearance-dependent — see
+ * {@link ACCENT_SUBTLE_ALPHA}.
+ */
+export function primarySubtleCss(appearance: ThemeAppearance, primaryVariable = '--primary'): string {
+  return `color-mix(in oklch, var(${primaryVariable}) ${ACCENT_SUBTLE_ALPHA[appearance]}%, transparent)`
+}
+
+/**
+ * The five declarations an accent sets, as CSS values.
+ *
+ * `primary`, `primaryForeground` and `ring` are resolved colours; `primaryHover` and
+ * `primarySubtle` are expressions, for the reason in the module comment. A consumer
+ * writes them as custom properties and the rules hold for every theme and every
+ * accent at once.
+ */
+export type AccentRoles = {
+  primary: string
+  primaryForeground: string
+  primaryHover: string
+  primarySubtle: string
+  ring: string
+}
+
+export function accentRoles(
+  preset: AccentPreset,
+  appearance: ThemeAppearance,
+  /** The property the subtle tint is built from. A consumer may pass its own alias. */
+  primaryVariable = '--primary'
+): AccentRoles {
+  const value = accentValue(preset, appearance)
+  const parsed = parseColor(value)
+  const primary = parsed ? formatOklch(parsed) : value
+
+  return {
+    primary,
+    primaryForeground: accentForeground(value),
+    primaryHover: primaryHover(value, appearance),
+    primarySubtle: primarySubtleCss(appearance, primaryVariable),
+    ring: primary,
+  }
+}

package/src/index.ts

@@ -57,6 +57,21 @@ export type {
 } from './schema'
 export { ANSI_KEYS, THEME_COLOR_KEYS } from './schema'
 
+export type { AccentPreset, AccentRoles } from './accents'
+export {
+  ACCENTS,
+  ACCENT_HOVER_STEP,
+  ACCENT_IDS,
+  ACCENT_SUBTLE_ALPHA,
+  accentForeground,
+  accentForegroundContrast,
+  accentRoles,
+  accentValue,
+  getAccent,
+  primaryHover,
+  primarySubtleCss,
+} from './accents'
+
 /* --- The catalogue ------------------------------------------------------ */
 export {
   DEFAULT_THEME_IDS,