@nxds/core 0.11.0 → 0.12.0

package/dist/runtime/index.d.cts

@@ -1,7 +1,7 @@
 import { T as Tier, P as PaletteKey, M as Mode } from './palette-BKTIQ0WC.cjs';
 export { N as NxdsSurfaceTone, a as PALETTE_KEYS, b as TIER_THRESHOLDS } from './palette-BKTIQ0WC.cjs';
-import { b as NxdsAppearanceState, d as DerivedTheme } from './surface-ladder-C8HTwT7z.cjs';
-export { B as BASE_TONE_OPTIONS, e as BASE_TONE_SEEDS, C as CORNER_OPTIONS, f as DEFAULT_BRAND_COLOR, g as DEFAULT_NXDS_APPEARANCE, h as DENSITY_OPTIONS, E as ELEVATION_OPTIONS, i as NxdsAppearanceMode, a as NxdsAppearancePrefs, j as NxdsCorners, k as NxdsDensity, l as NxdsElevation, N as NxdsPresetField, m as NxdsStroke, n as NxdsThemeContract, o as STROKE_OPTIONS, p as SurfaceToken, T as ThemeDerivationInput, q as ThemeSeeds, r as TokenMap, s as appearancePrefsToCss, t as createNxdsThemeContract, u as deriveTheme, v as normalizeAppearanceModeIds, w as sanitizeNxdsAppearance, x as sanitizeNxdsAppearancePrefs, y as themeToCss } from './surface-ladder-C8HTwT7z.cjs';
+import { b as NxdsAppearanceState, d as DerivedTheme, a as NxdsAppearancePrefs } from './surface-ladder-tv7B_RKy.cjs';
+export { B as BASE_TONE_OPTIONS, e as BASE_TONE_SEEDS, C as CORNER_OPTIONS, f as DEFAULT_BRAND_COLOR, g as DEFAULT_NXDS_APPEARANCE, h as DENSITY_OPTIONS, E as ELEVATION_OPTIONS, F as FONT_SIZE_PX_MAX, i as FONT_SIZE_PX_MIN, j as NxdsAppearanceMode, k as NxdsCorners, l as NxdsDensity, m as NxdsElevation, N as NxdsPresetField, n as NxdsStroke, o as NxdsThemeContract, p as STROKE_OPTIONS, q as SurfaceToken, T as ThemeDerivationInput, r as ThemeSeeds, s as TokenMap, t as appearancePrefsToCss, u as createNxdsThemeContract, v as deriveTheme, w as normalizeAppearanceModeIds, x as sanitizeNxdsAppearance, y as sanitizeNxdsAppearancePrefs, z as themeToCss } from './surface-ladder-tv7B_RKy.cjs';
 export { S as SpacingStep } from './token-scales.generated-CCNkHJ3I.cjs';
 
 type AdjustContrastTier = Tier;
@@ -96,6 +96,119 @@ declare function removeNxdsAppearance(): void;
 /** Saves the appearance for the first-paint script and, optionally, the server. */
 declare function persistNxdsAppearance(state: NxdsAppearanceState, { storageKey, cookieWriteKey, cookieOptions, }: NxdsAppearancePersistOptions): void;
 
+type NxdsFontCategory = 'sans' | 'serif' | 'mono';
+interface NxdsFontOption {
+    readonly value: string;
+    readonly label: string;
+    readonly category: NxdsFontCategory;
+    /** The `font-family` stack the appearance prefs store. */
+    readonly family: string;
+    /** The Fontsource package that self-hosts the font. */
+    readonly package: string;
+}
+/** The fonts nxds offers beside the system stacks, self-hosted through Fontsource. */
+declare const FONT_OPTIONS: readonly [{
+    readonly value: "geist";
+    readonly label: "Geist";
+    readonly category: "sans";
+    readonly family: "\"Geist Variable\", -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif";
+    readonly package: "@fontsource-variable/geist";
+}, {
+    readonly value: "inter";
+    readonly label: "Inter";
+    readonly category: "sans";
+    readonly family: "\"Inter Variable\", -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif";
+    readonly package: "@fontsource-variable/inter";
+}, {
+    readonly value: "figtree";
+    readonly label: "Figtree";
+    readonly category: "sans";
+    readonly family: "\"Figtree Variable\", -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif";
+    readonly package: "@fontsource-variable/figtree";
+}, {
+    readonly value: "dm-sans";
+    readonly label: "DM Sans";
+    readonly category: "sans";
+    readonly family: "\"DM Sans Variable\", -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif";
+    readonly package: "@fontsource-variable/dm-sans";
+}, {
+    readonly value: "manrope";
+    readonly label: "Manrope";
+    readonly category: "sans";
+    readonly family: "\"Manrope Variable\", -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif";
+    readonly package: "@fontsource-variable/manrope";
+}, {
+    readonly value: "ibm-plex-sans";
+    readonly label: "IBM Plex Sans";
+    readonly category: "sans";
+    readonly family: "\"IBM Plex Sans Variable\", -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif";
+    readonly package: "@fontsource-variable/ibm-plex-sans";
+}, {
+    readonly value: "lora";
+    readonly label: "Lora";
+    readonly category: "serif";
+    readonly family: "\"Lora Variable\", Georgia, serif";
+    readonly package: "@fontsource-variable/lora";
+}, {
+    readonly value: "playfair-display";
+    readonly label: "Playfair Display";
+    readonly category: "serif";
+    readonly family: "\"Playfair Display Variable\", Georgia, serif";
+    readonly package: "@fontsource-variable/playfair-display";
+}, {
+    readonly value: "geist-mono";
+    readonly label: "Geist Mono";
+    readonly category: "mono";
+    readonly family: "\"Geist Mono Variable\", ui-monospace, \"SF Mono\", Menlo, monospace";
+    readonly package: "@fontsource-variable/geist-mono";
+}, {
+    readonly value: "jetbrains-mono";
+    readonly label: "JetBrains Mono";
+    readonly category: "mono";
+    readonly family: "\"JetBrains Mono Variable\", ui-monospace, \"SF Mono\", Menlo, monospace";
+    readonly package: "@fontsource-variable/jetbrains-mono";
+}];
+type NxdsFont = (typeof FONT_OPTIONS)[number]['value'];
+
+/** The icon libraries nxds components can draw their own icons with. */
+declare const ICON_LIBRARY_OPTIONS: readonly [{
+    readonly value: "phosphor";
+    readonly label: "Phosphor";
+}, {
+    readonly value: "lucide";
+    readonly label: "Lucide";
+}, {
+    readonly value: "tabler";
+    readonly label: "Tabler Icons";
+}, {
+    readonly value: "hugeicons";
+    readonly label: "HugeIcons";
+}, {
+    readonly value: "remix";
+    readonly label: "Remix Icon";
+}];
+type NxdsIconLibrary = (typeof ICON_LIBRARY_OPTIONS)[number]['value'];
+declare const DEFAULT_ICON_LIBRARY: NxdsIconLibrary;
+
+interface NxdsShuffleOptions {
+    /**
+     * The fonts the UI and heading fonts come from. Monospace fonts are skipped,
+     * so it needs at least one sans or serif font. Leave it out to pick from
+     * every curated font.
+     */
+    readonly fonts?: readonly NxdsFontOption[];
+    /** Returns a number in [0, 1), like `Math.random`. */
+    readonly random?: () => number;
+}
+/**
+ * A random appearance from nxds's curated options: brand color preset, surface
+ * tone, density, corners, elevation, stroke, UI font and heading font. Mode,
+ * contrast and the other preferences stay as `state` has them.
+ */
+declare function shuffleNxdsAppearance(state: NxdsAppearanceState, { fonts, random }?: NxdsShuffleOptions): NxdsAppearanceState;
+/** A random icon library. */
+declare function shuffleNxdsIconLibrary({ random, }?: Pick<NxdsShuffleOptions, 'random'>): NxdsIconLibrary;
+
 declare const SNAPSHOT_VERSION = 9;
 declare const STATE_COOKIE_VERSION = 6;
 declare const NXDS_APPEARANCE_DATA_ATTRS: readonly ["data-density", "data-radius", "data-shadow", "data-borderwidth"];
@@ -172,6 +285,82 @@ interface ThemeContrastCheck {
 /** Measure every registered APCA pair of a derived theme in both modes. */
 declare function measureThemeContrast(theme: DerivedTheme): ThemeContrastCheck[];
 
+/**
+ * An app's theme: the appearance it starts from, and the icon library its
+ * components draw. The icon library is set when the app installs nxds, so it
+ * isn't part of the appearance an app can change at runtime.
+ */
+interface NxdsTheme {
+    readonly appearance: NxdsAppearanceState;
+    readonly iconLibrary: NxdsIconLibrary;
+}
+declare const DEFAULT_NXDS_THEME: NxdsTheme;
+/** Where a theme part lives in the appearance: a key of it, or of its prefs. */
+type NxdsThemeKey = Exclude<keyof NxdsAppearanceState, 'prefs'> | `prefs.${keyof NxdsAppearancePrefs}`;
+interface NxdsThemeFieldBase {
+    /** The flag, without its `--`. */
+    readonly flag: string;
+    /** What the flag sets, for `--help`. */
+    readonly description: string;
+    /** The flag's value for `theme`, or undefined when no flag value says it. */
+    read(theme: NxdsTheme): string | undefined;
+    /** `theme` with the flag's value. Throws when the value doesn't fit. */
+    write(theme: NxdsTheme, value: string): NxdsTheme;
+}
+/**
+ * One part of a theme, as the `nxds-cli init` flag that sets it. `kind` says
+ * which values the flag takes, and `key` the appearance field it sets. The
+ * icon library sets none.
+ */
+type NxdsThemeField = NxdsThemeFieldBase & ({
+    readonly kind: 'color';
+    readonly key: NxdsThemeKey;
+} | {
+    readonly kind: 'choice';
+    readonly key?: NxdsThemeKey;
+    readonly values: readonly string[];
+} | {
+    readonly kind: 'integer';
+    readonly key: NxdsThemeKey;
+    readonly min: number;
+    readonly max: number;
+} | {
+    readonly kind: 'font';
+    readonly key: NxdsThemeKey;
+    /** The fallback's value, then each curated font's. */
+    readonly values: readonly string[];
+    /** The categories of the curated fonts the flag takes. */
+    readonly categories: readonly NxdsFontCategory[];
+    /**
+     * The value that names no curated font, and the family it stands for:
+     * the default stack, or null for the UI font.
+     */
+    readonly fallback: {
+        readonly value: string;
+        readonly family: string | null;
+    };
+});
+/**
+ * Every part of a theme `nxds-cli init` can set, one flag each. Reduce motion,
+ * pointer cursors and font smoothing are each person's own preferences, so a
+ * theme leaves them out.
+ */
+declare const NXDS_THEME_FIELDS: readonly NxdsThemeField[];
+/**
+ * The `nxds-cli init` flags that set `theme`, for each part that differs from
+ * nxds's default theme. A part no flag value says, such as a font stack outside
+ * the curated fonts, is left out.
+ */
+declare function nxdsThemeFlags(theme: NxdsTheme): {
+    flag: string;
+    value: string;
+}[];
+/**
+ * `theme` with each flag `values` sets, by flag name. A flag left out keeps its
+ * part of `theme`. Throws on the first value that doesn't fit.
+ */
+declare function applyNxdsThemeFlags(theme: NxdsTheme, values: Readonly<Record<string, string | undefined>>): NxdsTheme;
+
 type TokenCategory = 'surface' | 'text' | 'border' | 'brand' | 'status' | 'chart' | 'syntax' | 'focus' | 'alpha';
 interface SemanticTokenMeta {
     /** Bare token name, without the --nx-color- prefix. */
@@ -191,4 +380,4 @@ declare const ALPHA_TOKEN_NAMES: readonly ["background-hover-alpha", "border-def
 type SemanticColorName = (typeof SURFACE_TOKEN_NAMES)[number] | (typeof TEXT_TOKEN_NAMES)[number] | (typeof BORDER_TOKEN_NAMES)[number] | (typeof BRAND_TOKEN_NAMES)[number] | (typeof STATUS_TOKEN_NAMES)[number] | (typeof CHART_TOKEN_NAMES)[number] | (typeof SYNTAX_TOKEN_NAMES)[number] | (typeof FOCUS_TOKEN_NAMES)[number] | (typeof ALPHA_TOKEN_NAMES)[number];
 declare const SEMANTIC_TOKEN_REGISTRY: readonly SemanticTokenMeta[];
 
-export { type AdjustContrastOptions, type AdjustContrastPalette, type AdjustContrastTier, BRAND_COLOR_PRESETS, type BrandColorPreset, DEFAULT_COOKIE_KEY, DEFAULT_STORAGE_KEY, DerivedTheme, Mode, NXDS_APPEARANCE_COOKIE_MAX_AGE_SECONDS, NXDS_APPEARANCE_DATA_ATTRS, type NxdsAppearanceBootstrapScriptOptions, type NxdsAppearanceCookieOptions, type NxdsAppearanceCookieSameSite, type NxdsAppearanceDataAttr, type NxdsAppearancePersistOptions, type NxdsAppearanceSnapshot, NxdsAppearanceState, type NxdsAppearanceStateCookie, type NxdsFirstPaintResolution, type NxdsResolvedAppearanceMode, RUNTIME_LAYER_ORDER, SEMANTIC_TOKEN_REGISTRY, SNAPSHOT_VERSION, type SemanticColorName, type SemanticTokenMeta, type ThemeContrastCheck, Tier, type TokenCategory, adjustContrast, apcaLc, applyNxdsAppearance, createDefaultNxdsAppearanceSnapshot, createNxdsAppearanceBootstrapScript, createNxdsAppearanceSnapshot, createNxdsAppearanceSnapshotFromCookie, createNxdsAppearanceSnapshotFromState, createNxdsAppearanceStateCookie, findBrandColorPreset, isColor, measureThemeContrast, parseNxdsAppearanceStateCookie, persistNxdsAppearance, prefersDarkColorScheme, readStoredNxdsAppearance, removeNxdsAppearance, resolveFirstPaint, resolveNxdsAppearanceMode, sanitizeNxdsAppearanceSnapshot, serializeNxdsAppearanceStateCookie, watchColorScheme };
+export { type AdjustContrastOptions, type AdjustContrastPalette, type AdjustContrastTier, BRAND_COLOR_PRESETS, type BrandColorPreset, DEFAULT_COOKIE_KEY, DEFAULT_ICON_LIBRARY, DEFAULT_NXDS_THEME, DEFAULT_STORAGE_KEY, DerivedTheme, FONT_OPTIONS, ICON_LIBRARY_OPTIONS, Mode, NXDS_APPEARANCE_COOKIE_MAX_AGE_SECONDS, NXDS_APPEARANCE_DATA_ATTRS, NXDS_THEME_FIELDS, type NxdsAppearanceBootstrapScriptOptions, type NxdsAppearanceCookieOptions, type NxdsAppearanceCookieSameSite, type NxdsAppearanceDataAttr, type NxdsAppearancePersistOptions, NxdsAppearancePrefs, type NxdsAppearanceSnapshot, NxdsAppearanceState, type NxdsAppearanceStateCookie, type NxdsFirstPaintResolution, type NxdsFont, type NxdsFontCategory, type NxdsFontOption, type NxdsIconLibrary, type NxdsResolvedAppearanceMode, type NxdsShuffleOptions, type NxdsTheme, type NxdsThemeField, type NxdsThemeKey, RUNTIME_LAYER_ORDER, SEMANTIC_TOKEN_REGISTRY, SNAPSHOT_VERSION, type SemanticColorName, type SemanticTokenMeta, type ThemeContrastCheck, Tier, type TokenCategory, adjustContrast, apcaLc, applyNxdsAppearance, applyNxdsThemeFlags, createDefaultNxdsAppearanceSnapshot, createNxdsAppearanceBootstrapScript, createNxdsAppearanceSnapshot, createNxdsAppearanceSnapshotFromCookie, createNxdsAppearanceSnapshotFromState, createNxdsAppearanceStateCookie, findBrandColorPreset, isColor, measureThemeContrast, nxdsThemeFlags, parseNxdsAppearanceStateCookie, persistNxdsAppearance, prefersDarkColorScheme, readStoredNxdsAppearance, removeNxdsAppearance, resolveFirstPaint, resolveNxdsAppearanceMode, sanitizeNxdsAppearanceSnapshot, serializeNxdsAppearanceStateCookie, shuffleNxdsAppearance, shuffleNxdsIconLibrary, watchColorScheme };

package/dist/runtime/index.d.ts

@@ -1,7 +1,7 @@
 import { T as Tier, P as PaletteKey, M as Mode } from './palette-BKTIQ0WC.js';
 export { N as NxdsSurfaceTone, a as PALETTE_KEYS, b as TIER_THRESHOLDS } from './palette-BKTIQ0WC.js';
-import { b as NxdsAppearanceState, d as DerivedTheme } from './surface-ladder-B950TU4_.js';
-export { B as BASE_TONE_OPTIONS, e as BASE_TONE_SEEDS, C as CORNER_OPTIONS, f as DEFAULT_BRAND_COLOR, g as DEFAULT_NXDS_APPEARANCE, h as DENSITY_OPTIONS, E as ELEVATION_OPTIONS, i as NxdsAppearanceMode, a as NxdsAppearancePrefs, j as NxdsCorners, k as NxdsDensity, l as NxdsElevation, N as NxdsPresetField, m as NxdsStroke, n as NxdsThemeContract, o as STROKE_OPTIONS, p as SurfaceToken, T as ThemeDerivationInput, q as ThemeSeeds, r as TokenMap, s as appearancePrefsToCss, t as createNxdsThemeContract, u as deriveTheme, v as normalizeAppearanceModeIds, w as sanitizeNxdsAppearance, x as sanitizeNxdsAppearancePrefs, y as themeToCss } from './surface-ladder-B950TU4_.js';
+import { b as NxdsAppearanceState, d as DerivedTheme, a as NxdsAppearancePrefs } from './surface-ladder-CAjRqzCx.js';
+export { B as BASE_TONE_OPTIONS, e as BASE_TONE_SEEDS, C as CORNER_OPTIONS, f as DEFAULT_BRAND_COLOR, g as DEFAULT_NXDS_APPEARANCE, h as DENSITY_OPTIONS, E as ELEVATION_OPTIONS, F as FONT_SIZE_PX_MAX, i as FONT_SIZE_PX_MIN, j as NxdsAppearanceMode, k as NxdsCorners, l as NxdsDensity, m as NxdsElevation, N as NxdsPresetField, n as NxdsStroke, o as NxdsThemeContract, p as STROKE_OPTIONS, q as SurfaceToken, T as ThemeDerivationInput, r as ThemeSeeds, s as TokenMap, t as appearancePrefsToCss, u as createNxdsThemeContract, v as deriveTheme, w as normalizeAppearanceModeIds, x as sanitizeNxdsAppearance, y as sanitizeNxdsAppearancePrefs, z as themeToCss } from './surface-ladder-CAjRqzCx.js';
 export { S as SpacingStep } from './token-scales.generated-CCNkHJ3I.js';
 
 type AdjustContrastTier = Tier;
@@ -96,6 +96,119 @@ declare function removeNxdsAppearance(): void;
 /** Saves the appearance for the first-paint script and, optionally, the server. */
 declare function persistNxdsAppearance(state: NxdsAppearanceState, { storageKey, cookieWriteKey, cookieOptions, }: NxdsAppearancePersistOptions): void;
 
+type NxdsFontCategory = 'sans' | 'serif' | 'mono';
+interface NxdsFontOption {
+    readonly value: string;
+    readonly label: string;
+    readonly category: NxdsFontCategory;
+    /** The `font-family` stack the appearance prefs store. */
+    readonly family: string;
+    /** The Fontsource package that self-hosts the font. */
+    readonly package: string;
+}
+/** The fonts nxds offers beside the system stacks, self-hosted through Fontsource. */
+declare const FONT_OPTIONS: readonly [{
+    readonly value: "geist";
+    readonly label: "Geist";
+    readonly category: "sans";
+    readonly family: "\"Geist Variable\", -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif";
+    readonly package: "@fontsource-variable/geist";
+}, {
+    readonly value: "inter";
+    readonly label: "Inter";
+    readonly category: "sans";
+    readonly family: "\"Inter Variable\", -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif";
+    readonly package: "@fontsource-variable/inter";
+}, {
+    readonly value: "figtree";
+    readonly label: "Figtree";
+    readonly category: "sans";
+    readonly family: "\"Figtree Variable\", -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif";
+    readonly package: "@fontsource-variable/figtree";
+}, {
+    readonly value: "dm-sans";
+    readonly label: "DM Sans";
+    readonly category: "sans";
+    readonly family: "\"DM Sans Variable\", -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif";
+    readonly package: "@fontsource-variable/dm-sans";
+}, {
+    readonly value: "manrope";
+    readonly label: "Manrope";
+    readonly category: "sans";
+    readonly family: "\"Manrope Variable\", -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif";
+    readonly package: "@fontsource-variable/manrope";
+}, {
+    readonly value: "ibm-plex-sans";
+    readonly label: "IBM Plex Sans";
+    readonly category: "sans";
+    readonly family: "\"IBM Plex Sans Variable\", -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif";
+    readonly package: "@fontsource-variable/ibm-plex-sans";
+}, {
+    readonly value: "lora";
+    readonly label: "Lora";
+    readonly category: "serif";
+    readonly family: "\"Lora Variable\", Georgia, serif";
+    readonly package: "@fontsource-variable/lora";
+}, {
+    readonly value: "playfair-display";
+    readonly label: "Playfair Display";
+    readonly category: "serif";
+    readonly family: "\"Playfair Display Variable\", Georgia, serif";
+    readonly package: "@fontsource-variable/playfair-display";
+}, {
+    readonly value: "geist-mono";
+    readonly label: "Geist Mono";
+    readonly category: "mono";
+    readonly family: "\"Geist Mono Variable\", ui-monospace, \"SF Mono\", Menlo, monospace";
+    readonly package: "@fontsource-variable/geist-mono";
+}, {
+    readonly value: "jetbrains-mono";
+    readonly label: "JetBrains Mono";
+    readonly category: "mono";
+    readonly family: "\"JetBrains Mono Variable\", ui-monospace, \"SF Mono\", Menlo, monospace";
+    readonly package: "@fontsource-variable/jetbrains-mono";
+}];
+type NxdsFont = (typeof FONT_OPTIONS)[number]['value'];
+
+/** The icon libraries nxds components can draw their own icons with. */
+declare const ICON_LIBRARY_OPTIONS: readonly [{
+    readonly value: "phosphor";
+    readonly label: "Phosphor";
+}, {
+    readonly value: "lucide";
+    readonly label: "Lucide";
+}, {
+    readonly value: "tabler";
+    readonly label: "Tabler Icons";
+}, {
+    readonly value: "hugeicons";
+    readonly label: "HugeIcons";
+}, {
+    readonly value: "remix";
+    readonly label: "Remix Icon";
+}];
+type NxdsIconLibrary = (typeof ICON_LIBRARY_OPTIONS)[number]['value'];
+declare const DEFAULT_ICON_LIBRARY: NxdsIconLibrary;
+
+interface NxdsShuffleOptions {
+    /**
+     * The fonts the UI and heading fonts come from. Monospace fonts are skipped,
+     * so it needs at least one sans or serif font. Leave it out to pick from
+     * every curated font.
+     */
+    readonly fonts?: readonly NxdsFontOption[];
+    /** Returns a number in [0, 1), like `Math.random`. */
+    readonly random?: () => number;
+}
+/**
+ * A random appearance from nxds's curated options: brand color preset, surface
+ * tone, density, corners, elevation, stroke, UI font and heading font. Mode,
+ * contrast and the other preferences stay as `state` has them.
+ */
+declare function shuffleNxdsAppearance(state: NxdsAppearanceState, { fonts, random }?: NxdsShuffleOptions): NxdsAppearanceState;
+/** A random icon library. */
+declare function shuffleNxdsIconLibrary({ random, }?: Pick<NxdsShuffleOptions, 'random'>): NxdsIconLibrary;
+
 declare const SNAPSHOT_VERSION = 9;
 declare const STATE_COOKIE_VERSION = 6;
 declare const NXDS_APPEARANCE_DATA_ATTRS: readonly ["data-density", "data-radius", "data-shadow", "data-borderwidth"];
@@ -172,6 +285,82 @@ interface ThemeContrastCheck {
 /** Measure every registered APCA pair of a derived theme in both modes. */
 declare function measureThemeContrast(theme: DerivedTheme): ThemeContrastCheck[];
 
+/**
+ * An app's theme: the appearance it starts from, and the icon library its
+ * components draw. The icon library is set when the app installs nxds, so it
+ * isn't part of the appearance an app can change at runtime.
+ */
+interface NxdsTheme {
+    readonly appearance: NxdsAppearanceState;
+    readonly iconLibrary: NxdsIconLibrary;
+}
+declare const DEFAULT_NXDS_THEME: NxdsTheme;
+/** Where a theme part lives in the appearance: a key of it, or of its prefs. */
+type NxdsThemeKey = Exclude<keyof NxdsAppearanceState, 'prefs'> | `prefs.${keyof NxdsAppearancePrefs}`;
+interface NxdsThemeFieldBase {
+    /** The flag, without its `--`. */
+    readonly flag: string;
+    /** What the flag sets, for `--help`. */
+    readonly description: string;
+    /** The flag's value for `theme`, or undefined when no flag value says it. */
+    read(theme: NxdsTheme): string | undefined;
+    /** `theme` with the flag's value. Throws when the value doesn't fit. */
+    write(theme: NxdsTheme, value: string): NxdsTheme;
+}
+/**
+ * One part of a theme, as the `nxds-cli init` flag that sets it. `kind` says
+ * which values the flag takes, and `key` the appearance field it sets. The
+ * icon library sets none.
+ */
+type NxdsThemeField = NxdsThemeFieldBase & ({
+    readonly kind: 'color';
+    readonly key: NxdsThemeKey;
+} | {
+    readonly kind: 'choice';
+    readonly key?: NxdsThemeKey;
+    readonly values: readonly string[];
+} | {
+    readonly kind: 'integer';
+    readonly key: NxdsThemeKey;
+    readonly min: number;
+    readonly max: number;
+} | {
+    readonly kind: 'font';
+    readonly key: NxdsThemeKey;
+    /** The fallback's value, then each curated font's. */
+    readonly values: readonly string[];
+    /** The categories of the curated fonts the flag takes. */
+    readonly categories: readonly NxdsFontCategory[];
+    /**
+     * The value that names no curated font, and the family it stands for:
+     * the default stack, or null for the UI font.
+     */
+    readonly fallback: {
+        readonly value: string;
+        readonly family: string | null;
+    };
+});
+/**
+ * Every part of a theme `nxds-cli init` can set, one flag each. Reduce motion,
+ * pointer cursors and font smoothing are each person's own preferences, so a
+ * theme leaves them out.
+ */
+declare const NXDS_THEME_FIELDS: readonly NxdsThemeField[];
+/**
+ * The `nxds-cli init` flags that set `theme`, for each part that differs from
+ * nxds's default theme. A part no flag value says, such as a font stack outside
+ * the curated fonts, is left out.
+ */
+declare function nxdsThemeFlags(theme: NxdsTheme): {
+    flag: string;
+    value: string;
+}[];
+/**
+ * `theme` with each flag `values` sets, by flag name. A flag left out keeps its
+ * part of `theme`. Throws on the first value that doesn't fit.
+ */
+declare function applyNxdsThemeFlags(theme: NxdsTheme, values: Readonly<Record<string, string | undefined>>): NxdsTheme;
+
 type TokenCategory = 'surface' | 'text' | 'border' | 'brand' | 'status' | 'chart' | 'syntax' | 'focus' | 'alpha';
 interface SemanticTokenMeta {
     /** Bare token name, without the --nx-color- prefix. */
@@ -191,4 +380,4 @@ declare const ALPHA_TOKEN_NAMES: readonly ["background-hover-alpha", "border-def
 type SemanticColorName = (typeof SURFACE_TOKEN_NAMES)[number] | (typeof TEXT_TOKEN_NAMES)[number] | (typeof BORDER_TOKEN_NAMES)[number] | (typeof BRAND_TOKEN_NAMES)[number] | (typeof STATUS_TOKEN_NAMES)[number] | (typeof CHART_TOKEN_NAMES)[number] | (typeof SYNTAX_TOKEN_NAMES)[number] | (typeof FOCUS_TOKEN_NAMES)[number] | (typeof ALPHA_TOKEN_NAMES)[number];
 declare const SEMANTIC_TOKEN_REGISTRY: readonly SemanticTokenMeta[];
 
-export { type AdjustContrastOptions, type AdjustContrastPalette, type AdjustContrastTier, BRAND_COLOR_PRESETS, type BrandColorPreset, DEFAULT_COOKIE_KEY, DEFAULT_STORAGE_KEY, DerivedTheme, Mode, NXDS_APPEARANCE_COOKIE_MAX_AGE_SECONDS, NXDS_APPEARANCE_DATA_ATTRS, type NxdsAppearanceBootstrapScriptOptions, type NxdsAppearanceCookieOptions, type NxdsAppearanceCookieSameSite, type NxdsAppearanceDataAttr, type NxdsAppearancePersistOptions, type NxdsAppearanceSnapshot, NxdsAppearanceState, type NxdsAppearanceStateCookie, type NxdsFirstPaintResolution, type NxdsResolvedAppearanceMode, RUNTIME_LAYER_ORDER, SEMANTIC_TOKEN_REGISTRY, SNAPSHOT_VERSION, type SemanticColorName, type SemanticTokenMeta, type ThemeContrastCheck, Tier, type TokenCategory, adjustContrast, apcaLc, applyNxdsAppearance, createDefaultNxdsAppearanceSnapshot, createNxdsAppearanceBootstrapScript, createNxdsAppearanceSnapshot, createNxdsAppearanceSnapshotFromCookie, createNxdsAppearanceSnapshotFromState, createNxdsAppearanceStateCookie, findBrandColorPreset, isColor, measureThemeContrast, parseNxdsAppearanceStateCookie, persistNxdsAppearance, prefersDarkColorScheme, readStoredNxdsAppearance, removeNxdsAppearance, resolveFirstPaint, resolveNxdsAppearanceMode, sanitizeNxdsAppearanceSnapshot, serializeNxdsAppearanceStateCookie, watchColorScheme };
+export { type AdjustContrastOptions, type AdjustContrastPalette, type AdjustContrastTier, BRAND_COLOR_PRESETS, type BrandColorPreset, DEFAULT_COOKIE_KEY, DEFAULT_ICON_LIBRARY, DEFAULT_NXDS_THEME, DEFAULT_STORAGE_KEY, DerivedTheme, FONT_OPTIONS, ICON_LIBRARY_OPTIONS, Mode, NXDS_APPEARANCE_COOKIE_MAX_AGE_SECONDS, NXDS_APPEARANCE_DATA_ATTRS, NXDS_THEME_FIELDS, type NxdsAppearanceBootstrapScriptOptions, type NxdsAppearanceCookieOptions, type NxdsAppearanceCookieSameSite, type NxdsAppearanceDataAttr, type NxdsAppearancePersistOptions, NxdsAppearancePrefs, type NxdsAppearanceSnapshot, NxdsAppearanceState, type NxdsAppearanceStateCookie, type NxdsFirstPaintResolution, type NxdsFont, type NxdsFontCategory, type NxdsFontOption, type NxdsIconLibrary, type NxdsResolvedAppearanceMode, type NxdsShuffleOptions, type NxdsTheme, type NxdsThemeField, type NxdsThemeKey, RUNTIME_LAYER_ORDER, SEMANTIC_TOKEN_REGISTRY, SNAPSHOT_VERSION, type SemanticColorName, type SemanticTokenMeta, type ThemeContrastCheck, Tier, type TokenCategory, adjustContrast, apcaLc, applyNxdsAppearance, applyNxdsThemeFlags, createDefaultNxdsAppearanceSnapshot, createNxdsAppearanceBootstrapScript, createNxdsAppearanceSnapshot, createNxdsAppearanceSnapshotFromCookie, createNxdsAppearanceSnapshotFromState, createNxdsAppearanceStateCookie, findBrandColorPreset, isColor, measureThemeContrast, nxdsThemeFlags, parseNxdsAppearanceStateCookie, persistNxdsAppearance, prefersDarkColorScheme, readStoredNxdsAppearance, removeNxdsAppearance, resolveFirstPaint, resolveNxdsAppearanceMode, sanitizeNxdsAppearanceSnapshot, serializeNxdsAppearanceStateCookie, shuffleNxdsAppearance, shuffleNxdsIconLibrary, watchColorScheme };