react-native-terra-ui 0.10.2 → 0.11.0

package/src/theme/resolve-config.ts

@@ -1,12 +1,12 @@
 /**
  * Pure theme resolution — normalization, layer processing, derived values and
- * theme creation. Shared by startup configuration, runtime accent changes and
+ * theme creation. Shared by startup configuration, runtime theme changes and
  * previews so every consumer sees the same colors for the same input.
  *
  * Precedence, identical for both schemes:
  *
- *   default tokens → shared → schemes[scheme]
- *       → generated selected accent → selected accent explicit overrides
+ *   default tokens → shared → generated accent → selected theme tokens
+ * Generation uses the selected theme's resolved surfaces and pressed opacity.
  *
  * This module must stay free of registry, provider, Unistyles and renderer
  * imports so `createTerraThemes` works without any native configuration.
@@ -33,15 +33,14 @@ import {
   type ThemeSource,
 } from "./theme";
 import type {
-  Accent,
-  AccentSchemeInput,
   CreateTerraThemesOptions,
   ElevationKey,
+  NamedTheme,
   Scheme,
   TerraTheme,
   TerraThemeInput,
   TerraThemeOverride,
-  ThemeColor,
+  ThemeSchemeInput,
 } from "./types";
 
 const SCHEMES: readonly Scheme[] = ["light", "dark"];
@@ -87,8 +86,8 @@ function sanitizeOverride<T>(value: T): T {
 
 /**
  * Applies one override layer onto `state` and returns the next state. Every
- * layer — shared, scheme, generated accent, accent overrides, or a full accent
- * patch — goes through here, so they all follow the same rules:
+ * layer — shared, generated accent, or selected theme tokens — goes through
+ * here, so they all follow the same rules:
  * - deprecated names are normalized within the layer (canonical wins);
  * - `undefined`/`null` leaves are no override; arrays replace; objects merge;
  * - `spacing.base` / `radius.base` regenerate their scale, then that layer's
@@ -140,34 +139,34 @@ export function applyThemeLayer(state: ThemeLayerState, override?: TerraThemeOve
 
 // ─── Normalized configuration ────────────────────────────────────────────────
 
-export type NormalizedAccentScheme =
+export type NormalizedThemeScheme =
   | { readonly kind: "none" }
-  | { readonly kind: "seed"; readonly seed: string; readonly overrides?: Partial<ThemeColor> }
+  | { readonly kind: "seed"; readonly seed: string; readonly patch?: TerraThemeOverride }
   | { readonly kind: "patch"; readonly patch: TerraThemeOverride };
 
-interface NormalizedAccentEntry {
-  readonly light: NormalizedAccentScheme;
-  readonly dark: NormalizedAccentScheme;
+interface NormalizedThemeEntry {
+  readonly light: NormalizedThemeScheme;
+  readonly dark: NormalizedThemeScheme;
 }
 
 /**
  * A validated, immutable theme configuration. `base` is the fully layered
- * `defaults → shared → scheme` state per scheme; every accent selection is
- * re-resolved from it rather than from a previously resolved accent.
+ * `defaults → shared` state per scheme; every theme selection is
+ * re-resolved from it rather than from a previously resolved theme.
  */
 export interface NormalizedThemeConfig {
-  readonly accentNames: readonly string[];
-  readonly defaultAccent: string | null;
-  /** @internal Immutable `defaults → shared → scheme` state per scheme. */
+  readonly themeNames: readonly string[];
+  readonly defaultTheme: string | null;
+  /** @internal Immutable `defaults → shared` state per scheme. */
   readonly base: Readonly<Record<Scheme, ThemeLayerState>>;
-  /** @internal Per-accent, per-scheme normalized inputs. */
-  readonly accents: Readonly<Record<string, NormalizedAccentEntry>>;
+  /** @internal Per-theme, per-scheme normalized inputs. */
+  readonly themes: Readonly<Record<string, NormalizedThemeEntry>>;
 }
 
-export function normalizeAccentScheme(
-  input: AccentSchemeInput | undefined,
+export function normalizeThemeScheme(
+  input: ThemeSchemeInput | undefined,
   path: string
-): NormalizedAccentScheme {
+): NormalizedThemeScheme {
   if (input === undefined || input === null) return { kind: "none" };
 
   if (typeof input === "string") {
@@ -183,52 +182,46 @@ export function normalizeAccentScheme(
   if (!isPlainObject(input)) {
     throw new TerraConfigError(
       path,
-      "Expected a color string, `{ seed, overrides }`, or a theme override object."
+      "Expected a color string, `{ seed, color }`, or a theme override object."
     );
   }
 
-  if (!("seed" in input)) {
-    return { kind: "patch", patch: sanitizeOverride(input as TerraThemeOverride) };
+  if ("overrides" in input) {
+    throw new TerraConfigError(`${path}.overrides`, "Use `color` for explicit colors alongside `seed`.");
   }
-
-  const extra = Object.keys(input).filter((key) => key !== "seed" && key !== "overrides");
-  if (extra.length > 0) {
-    throw new TerraConfigError(
-      path,
-      `A seeded accent accepts only \`seed\` and \`overrides\`; found ${extra
-        .map((key) => `\`${key}\``)
-        .join(
-          ", "
-        )}. Use \`{ seed, overrides: { ... } }\` for color exceptions, or drop \`seed\` for a full theme override.`
-    );
+  const { seed, ...patch } = input as TerraThemeOverride & { seed?: unknown };
+  assertOverrideObject(patch.color, `${path}.color`);
+  if (!("seed" in input)) {
+    return { kind: "patch", patch: sanitizeOverride(patch) };
   }
-
-  const { seed, overrides } = input as { seed: unknown; overrides?: unknown };
   if (!isSupportedAccentSeed(seed)) {
     throw new TerraConfigError(
       `${path}.seed`,
       `Unsupported accent seed ${JSON.stringify(seed)}; expected an opaque six-digit hex color (#rrggbb).`
     );
   }
-  if (overrides !== undefined && !isPlainObject(overrides)) {
-    throw new TerraConfigError(`${path}.overrides`, "Expected a flat semantic color patch object.");
-  }
-
-  return {
-    kind: "seed",
-    seed: seed.trim(),
-    ...(overrides ? { overrides: sanitizeOverride(overrides as Partial<ThemeColor>) } : {}),
-  };
+  return { kind: "seed", seed: seed.trim(), patch: sanitizeOverride(patch) };
 }
 
-function normalizeAccentEntry(name: string, accent: Accent): NormalizedAccentEntry {
-  const path = `accents.${name}`;
-  if (!isPlainObject(accent)) {
+function normalizeThemeEntry(name: string, theme: NamedTheme): NormalizedThemeEntry {
+  const path = `themes.${name}`;
+  if (!isPlainObject(theme)) {
     throw new TerraConfigError(path, "Expected an object with `light` and/or `dark` scheme inputs.");
   }
+  // An empty entry is a valid theme that adds nothing, but tokens sitting
+  // outside a scheme — `{ seed, color }` lifted straight out of the old
+  // `accents` shape — would otherwise be accepted and silently render defaults.
+  const keys = Object.keys(theme);
+  if (keys.length > 0 && !("light" in theme) && !("dark" in theme)) {
+    throw new TerraConfigError(
+      path,
+      `Unexpected ${keys.map((key) => `\`${key}\``).join(", ")} outside a scheme; ` +
+        "put `seed` and token overrides under `light` and/or `dark`."
+    );
+  }
   return {
-    light: normalizeAccentScheme(accent.light, `${path}.light`),
-    dark: normalizeAccentScheme(accent.dark, `${path}.dark`),
+    light: normalizeThemeScheme(theme.light, `${path}.light`),
+    dark: normalizeThemeScheme(theme.dark, `${path}.dark`),
   };
 }
 
@@ -240,7 +233,7 @@ function assertOverrideObject(value: unknown, path: string): void {
 
 /**
  * Validates a theme input and pre-computes the immutable per-scheme base
- * (`defaults → shared → scheme`). Throws {@link TerraConfigError} for invalid
+ * (`defaults → shared`). Throws {@link TerraConfigError} for invalid
  * input — before any state exists to mutate. Never mutates `input` or the
  * exported defaults.
  */
@@ -250,41 +243,42 @@ export function normalizeThemeInput(input: TerraThemeInput = {}): NormalizedThem
   }
 
   assertOverrideObject(input.shared, "shared");
-  assertOverrideObject(input.schemes, "schemes");
-  assertOverrideObject(input.schemes?.light, "schemes.light");
-  assertOverrideObject(input.schemes?.dark, "schemes.dark");
-  if (input.accents !== undefined && !isPlainObject(input.accents)) {
-    throw new TerraConfigError("accents", "Expected a record of named accents.");
+  for (const removed of ["schemes", "accents", "defaultAccent"]) {
+    if (removed in input) {
+      throw new TerraConfigError(removed, "Use `themes.<name>.light/dark` and `defaultTheme` instead.");
+    }
+  }
+  if (input.themes !== undefined && !isPlainObject(input.themes)) {
+    throw new TerraConfigError("themes", "Expected a record of named themes.");
   }
 
-  const accents: Record<string, NormalizedAccentEntry> = {};
-  for (const [name, accent] of Object.entries(input.accents ?? {})) {
-    accents[name] = normalizeAccentEntry(name, accent);
+  const themes: Record<string, NormalizedThemeEntry> = Object.create(null);
+  for (const [name, theme] of Object.entries(input.themes ?? {})) {
+    themes[name] = normalizeThemeEntry(name, theme);
   }
-  const accentNames = Object.keys(accents);
+  const themeNames = Object.keys(themes);
 
-  let defaultAccent: string | null = null;
-  if (input.defaultAccent !== undefined && input.defaultAccent !== null) {
-    if (typeof input.defaultAccent !== "string" || !Object.hasOwn(accents, input.defaultAccent)) {
+  let defaultTheme: string | null = null;
+  if (input.defaultTheme !== undefined && input.defaultTheme !== null) {
+    if (typeof input.defaultTheme !== "string" || !Object.hasOwn(themes, input.defaultTheme)) {
       throw new TerraConfigError(
-        "defaultAccent",
-        `Unknown accent ${JSON.stringify(input.defaultAccent)}; declared accents: ${
-          accentNames.length > 0 ? accentNames.map((n) => `"${n}"`).join(", ") : "(none)"
+        "defaultTheme",
+        `Unknown theme ${JSON.stringify(input.defaultTheme)}; declared themes: ${
+          themeNames.length > 0 ? themeNames.map((n) => `"${n}"`).join(", ") : "(none)"
         }.`
       );
     }
-    defaultAccent = input.defaultAccent;
+    defaultTheme = input.defaultTheme;
   }
 
   const base = {} as Record<Scheme, ThemeLayerState>;
   for (const scheme of SCHEMES) {
     let state: ThemeLayerState = { source: createDefaultThemeSource(scheme), pinnedShadowColors: {} };
     state = applyThemeLayer(state, input.shared);
-    state = applyThemeLayer(state, input.schemes?.[scheme]);
     base[scheme] = state;
   }
 
-  return { accentNames, defaultAccent, base, accents };
+  return { themeNames, defaultTheme, base, themes };
 }
 
 // ─── Resolution ──────────────────────────────────────────────────────────────
@@ -295,19 +289,19 @@ export interface ResolvedThemes {
   diagnostics: ContrastDiagnostic[];
 }
 
-function getAccentEntry(
+function getThemeEntry(
   config: NormalizedThemeConfig,
-  accent: string | null
-): NormalizedAccentEntry | undefined {
-  if (accent === null) return undefined;
+  themeName: string | null
+): NormalizedThemeEntry | undefined {
+  if (themeName === null) return undefined;
 
-  const entry = config.accents[accent];
-  if (entry) return entry;
+  const entry = config.themes[themeName];
+  if (Object.hasOwn(config.themes, themeName)) return entry;
 
   throw new TerraConfigError(
-    "accent",
-    `Unknown accent ${JSON.stringify(accent)}; declared accents: ${
-      config.accentNames.length > 0 ? config.accentNames.map((name) => `"${name}"`).join(", ") : "(none)"
+    "theme",
+    `Unknown theme ${JSON.stringify(themeName)}; declared themes: ${
+      config.themeNames.length > 0 ? config.themeNames.map((name) => `"${name}"`).join(", ") : "(none)"
     }.`
   );
 }
@@ -331,7 +325,7 @@ function pickGeneratedRoles(color: ThemeSource["color"]): Record<GeneratedAccent
 function resolveScheme(
   scheme: Scheme,
   base: ThemeLayerState,
-  accent: NormalizedAccentScheme
+  accent: NormalizedThemeScheme
 ): { theme: TerraTheme; diagnostics: ContrastDiagnostic[] } {
   let state = base;
   let diagnostics: ContrastDiagnostic[] = [];
@@ -339,12 +333,11 @@ function resolveScheme(
   if (accent.kind === "patch") {
     state = applyThemeLayer(state, accent.patch);
   } else if (accent.kind === "seed") {
-    const context = accentContext(scheme, state.source);
+    // Generate against the final ordinary surfaces, then let explicit tokens win.
+    const context = accentContext(scheme, applyThemeLayer(base, accent.patch).source);
     const generated = generateAccentColors(accent.seed, context);
     state = applyThemeLayer(state, { color: generated.colors } as TerraThemeOverride);
-    if (accent.overrides) {
-      state = applyThemeLayer(state, { color: accent.overrides });
-    }
+    state = applyThemeLayer(state, accent.patch);
     // The post-override check is authoritative: it evaluates the colours that
     // actually ship, so an override that fixes a pair leaves no stale report.
     diagnostics = checkAccentContrast(
@@ -357,12 +350,12 @@ function resolveScheme(
 }
 
 /**
- * Resolves both schemes for `accent` from the config's immutable base. `null`
+ * Resolves both schemes for `themeName` from the config's immutable base. `null`
  * selects the base themes; an unknown name throws {@link TerraConfigError}.
  * Returned themes are freshly built and independently owned.
  */
-export function resolveThemes(config: NormalizedThemeConfig, accent: string | null): ResolvedThemes {
-  const entry = getAccentEntry(config, accent);
+export function resolveThemes(config: NormalizedThemeConfig, themeName: string | null): ResolvedThemes {
+  const entry = getThemeEntry(config, themeName);
 
   const themes = {} as Record<Scheme, TerraTheme>;
   const diagnostics: ContrastDiagnostic[][] = [];
@@ -379,16 +372,16 @@ export function resolveThemes(config: NormalizedThemeConfig, accent: string | nu
 export function resolveThemeScheme(
   config: NormalizedThemeConfig,
   scheme: Scheme,
-  accent: string | null
+  themeName: string | null
 ): { theme: TerraTheme; diagnostics: ContrastDiagnostic[] } {
-  const entry = getAccentEntry(config, accent);
+  const entry = getThemeEntry(config, themeName);
   return resolveScheme(scheme, config.base[scheme], entry?.[scheme] ?? { kind: "none" });
 }
 
 /**
  * Pure theme creation — no Unistyles configuration or registry involved.
- * `options.accent` omitted → the input's `defaultAccent`; `null` → the base
- * themes. Invalid input and unknown accents throw {@link TerraConfigError}.
+ * `options.theme` omitted → the input's `defaultTheme`; `null` → the base
+ * themes. Invalid input and unknown themes throw {@link TerraConfigError}.
  * In development, contrast diagnostics are reported once each via
  * `console.warn`; requested colors are never altered.
  */
@@ -397,8 +390,8 @@ export function createTerraThemes(
   options?: CreateTerraThemesOptions
 ): Record<Scheme, TerraTheme> {
   const config = normalizeThemeInput(input);
-  const accent = options?.accent === undefined ? config.defaultAccent : options.accent;
-  const { themes, diagnostics } = resolveThemes(config, accent);
+  const themeName = options?.theme === undefined ? config.defaultTheme : options.theme;
+  const { themes, diagnostics } = resolveThemes(config, themeName);
 
   warnContrastDiagnostics(diagnostics);
 

package/src/theme/runtime.ts

@@ -1,9 +1,9 @@
 /**
- * Runtime selection commands — accent and theme mode — plus the subscribed
+ * Runtime selection commands — theme and theme mode — plus the subscribed
  * selection snapshot consumed by `useTheme()`.
  *
- * Every accent change re-resolves both schemes from the installed, immutable
- * configuration (never from the previously resolved accent), hands them to
+ * Every theme change re-resolves both schemes from the installed, immutable
+ * configuration (never from the previously resolved theme), hands them to
  * Unistyles, and only then publishes the new selection. A rejected or failed
  * change leaves both the native themes and the published selection untouched.
  */
@@ -17,30 +17,30 @@ export type { ThemeSelection } from "./selection-store";
 export { getThemeSelection, subscribeThemeSelection } from "./selection-store";
 
 /**
- * Apply a registered accent (`null` restores the base themes) by updating both
+ * Apply a registered theme (`null` restores the base themes) by updating both
  * registered themes. An unknown name warns in development and changes nothing.
  *
  * If the native update fails part-way (see `updateThemes` in the adapter), the
  * error propagates and the previous selection stays published; calling
- * `applyAccent(getCurrentAccent() ?? null)` rewrites both themes.
+ * `setTheme(getCurrentTheme() ?? null)` rewrites both themes.
  */
-export function applyAccent(name: string | null): void {
+export function setTheme(name: string | null): void {
   const config = getInstalledConfig();
-  if (name !== null && !config.accentNames.includes(name)) {
+  if (name !== null && !config.themeNames.includes(name)) {
     if (__DEV__) {
-      console.warn(`[react-native-terra-ui] Unknown accent "${name}".`);
+      console.warn(`[react-native-terra-ui] Unknown theme "${name}".`);
     }
     return;
   }
 
   const { themes, diagnostics } = resolveThemes(config, name);
   updateThemes(themes);
-  publishThemeSelection({ accent: name ?? undefined });
+  publishThemeSelection({ themeName: name ?? undefined });
   warnContrastDiagnostics(diagnostics);
 }
 
-/** The applied accent name, or `undefined` for the base themes. */
-export const getCurrentAccent = (): string | undefined => getThemeSelection().accent;
+/** The applied theme name, or `undefined` for the base themes. */
+export const getCurrentTheme = (): string | undefined => getThemeSelection().themeName;
 
 /**
  * Choose how the active scheme is selected: `system` follows the OS appearance;

package/src/theme/selection-store.ts

@@ -4,9 +4,9 @@
  * those has to import the other.
  *
  * Holds two things, both private to `theme/`:
- * - the installed {@link NormalizedThemeConfig} — immutable; every accent
+ * - the installed {@link NormalizedThemeConfig} — immutable; every theme
  *   selection is re-resolved from it, never layered on a previous result;
- * - the selection snapshot (`accent`, `mode`) behind a `useSyncExternalStore`
+ * - the selection snapshot (`themeName`, `mode`) behind a `useSyncExternalStore`
  *   compatible subscribe/get pair. The snapshot object keeps its identity until
  *   a value actually changes, so subscribers only re-render on real changes.
  *
@@ -33,15 +33,15 @@ export function setInstalledConfig(config: NormalizedThemeConfig): void {
 
 // ─── Selection snapshot ──────────────────────────────────────────────────────
 
-/** The current runtime selection: which accent is applied and how the scheme is chosen. */
+/** The current runtime selection: which theme is applied and how the scheme is chosen. */
 export interface ThemeSelection {
-  /** Applied accent name, or `undefined` for the base themes. */
-  readonly accent: string | undefined;
+  /** Applied theme name, or `undefined` for the base themes. */
+  readonly themeName: string | undefined;
   /** `system` follows the OS appearance; `light` / `dark` pin a scheme. */
   readonly mode: ThemeMode;
 }
 
-let selection: ThemeSelection = Object.freeze({ accent: undefined, mode: "system" as ThemeMode });
+let selection: ThemeSelection = Object.freeze({ themeName: undefined, mode: "system" as ThemeMode });
 
 const listeners = new Set<() => void>();
 
@@ -65,11 +65,11 @@ export function subscribeThemeSelection(listener: () => void): () => void {
  * A no-op — same snapshot identity, no notification — when nothing changed.
  */
 export function publishThemeSelection(next: Partial<ThemeSelection>): void {
-  const accent = "accent" in next ? next.accent : selection.accent;
+  const themeName = "themeName" in next ? next.themeName : selection.themeName;
   const mode = next.mode ?? selection.mode;
-  if (accent === selection.accent && mode === selection.mode) return;
+  if (themeName === selection.themeName && mode === selection.mode) return;
 
-  selection = Object.freeze({ accent, mode });
+  selection = Object.freeze({ themeName, mode });
   for (const listener of listeners) {
     listener();
   }

package/src/theme/types.ts

@@ -203,10 +203,10 @@ declare global {
   namespace TerraUI {
     /**
      * Augment to declare app-specific semantic color keys. Declared keys become
-     * valid in `shared` / `schemes` / accent overrides, `theme.color`, and
+     * valid in `shared` / named theme tokens, `theme.color`, and
      * component color props. Keys must not collide with built-in canonical or
      * deprecated names. Type augmentation alone cannot prove a value exists at
-     * runtime — provide every declared color through `shared` or both `schemes`.
+     * runtime — provide every declared color through `shared` or each theme's light/dark entries.
      *
      * @example
      * declare global {
@@ -309,7 +309,7 @@ export type ContentColorToken = TextColorToken;
  */
 export type ColorToken = keyof ThemeColor | (string & {});
 
-// ─── Configuration / accents ─────────────────────────────────────────────────
+// ─── Configuration / themes ─────────────────────────────────────────────────
 
 export type Scheme = "light" | "dark";
 
@@ -319,46 +319,22 @@ export type Scheme = "light" | "dark";
  */
 export type ThemeMode = "system" | "light" | "dark";
 
-/**
- * A seed-generated accent with local exceptions. The seed is a starting color
- * for the accent family, not a promise that `accent.solid.bg` equals it — pin
- * `accent.solid.bg` in `overrides` when an exact fill is required.
- */
-export interface AccentSeed {
-  /** Opaque six-digit sRGB hex (`#rrggbb`). Other formats are rejected at configure time. */
+/** Explicit theme tokens plus a seed-generated accent palette. */
+export type ThemeSeed = TerraThemeOverride & {
+  /** Opaque six-digit hex color. Explicit `color` values win over generation. */
   seed: string;
-  /**
-   * Flat semantic color patch applied after generation. Within the patch a
-   * canonical name beats its deprecated alias; across layers an explicit
-   * override beats every generated value.
-   */
-  overrides?: Partial<ThemeColor>;
-}
+};
 
-/**
- * One scheme's accent input:
- * - a color string — equivalent to `{ seed: value }`;
- * - `{ seed, overrides }` — generation with explicit exceptions;
- * - a full {@link TerraThemeOverride} — skips generation (expert path).
- */
-export type AccentSchemeInput = string | AccentSeed | TerraThemeOverride;
+/** A seed shorthand, explicit theme tokens, or both via `{ seed, color, ... }`. */
+export type ThemeSchemeInput = string | ThemeSeed | TerraThemeOverride;
 
 /**
- * A named, runtime-switchable overlay on each scheme. A missing scheme leaves
- * that scheme unmodified; the other scheme's seed is never copied implicitly.
+ * A complete named light/dark theme. Missing schemes inherit defaults + shared;
+ * seeds are never copied from the other scheme.
  */
-export type Accent = Partial<Record<Scheme, AccentSchemeInput>>;
-
-/** @deprecated Use {@link Accent} — a color string per scheme. */
-export type AccentShorthand = Record<Scheme, string>;
+export type NamedTheme = Partial<Record<Scheme, ThemeSchemeInput>>;
 
-/** @deprecated Use {@link Accent} — a {@link TerraThemeOverride} per scheme. */
-export type AccentOverride = Partial<Record<Scheme, TerraThemeOverride>>;
-
-/**
- * The compatibility output of `normalizeAccent`: per-scheme partial-theme
- * overrides generated against the default themes.
- */
+/** Output of the legacy normalizeAccent helper. */
 export interface NormalizedAccent {
   light: DeepPartial<TerraTheme>;
   dark: DeepPartial<TerraTheme>;
@@ -474,10 +450,8 @@ export interface ComponentDefaults {
 export interface TerraConfig {
   /** Scheme-agnostic token overrides, applied to both light and dark themes. */
   shared?: TerraThemeOverride;
-  /** Per-scheme token overrides, applied after `shared`. */
-  schemes?: { light?: TerraThemeOverride; dark?: TerraThemeOverride };
-  /** Runtime-switchable named overrides (hue shorthand or full partial). */
-  accents?: Record<string, Accent>;
+  /** Named light/dark themes applied over defaults + shared. */
+  themes?: Record<string, NamedTheme>;
   /**
    * App-provided icon overrides. Semantic icons (`navigation.*`, `status.*`)
    * fall back to the built-in defaults when omitted; app icons (`add`, etc.)
@@ -490,8 +464,8 @@ export interface TerraConfig {
    * `resizeMode`. Wrap third-party components to match `TerraImageProps`.
    */
   image?: TerraImageComponent;
-  /** Name of the accent (from `accents`) to apply by default. */
-  defaultAccent?: string;
+  /** Name of the theme (from `themes`) to apply by default. */
+  defaultTheme?: string;
   /** Per-component default props (e.g. `{ button: { radius: 'full' } }`). */
   components?: ComponentDefaults;
   /**
@@ -507,13 +481,13 @@ export interface TerraConfig {
 }
 
 /** The subset of {@link TerraConfig} that affects resolved theme tokens. */
-export type TerraThemeInput = Pick<TerraConfig, "shared" | "schemes" | "accents" | "defaultAccent">;
+export type TerraThemeInput = Pick<TerraConfig, "shared" | "themes" | "defaultTheme">;
 
 /** Options for pure theme creation. */
 export interface CreateTerraThemesOptions {
   /**
-   * Accent to overlay. Omitted → `defaultAccent`; `null` → the base themes
-   * with no accent. An unknown name throws.
+   * Named theme to select. Omitted → `defaultTheme`; `null` → the base themes
+   * with no named theme. An unknown name throws.
    */
-  accent?: string | null;
+  theme?: string | null;
 }

package/src/theme/unistyles-adapter.ts

@@ -52,7 +52,7 @@ export function configureUnistyles({
  * runtime holds the new `light` theme and the previous `dark` theme. Callers
  * publish registry/selection state only after this returns, so on a throw Terra
  * still reports the previous selection; calling the same command again with the
- * previous selection (e.g. `applyAccent(getCurrentAccent() ?? null)`) rewrites
+ * previous selection (e.g. `setTheme(getCurrentTheme() ?? null)`) rewrites
  * both themes and restores consistency. No automatic rollback is attempted.
  */
 export function updateThemes(themes: Record<Scheme, TerraTheme>): void {