@teacss/preset-standard 0.4.4 → 0.4.5

package/README.md

@@ -238,6 +238,32 @@ specialized controls such as file, range, and color inputs have no profile:
 their native rendering is not a shared shape, so compose the declarations the
 design actually needs.
 
+## Theme Variants
+
+Named theme variants live in `theme.themes` (applications declare them with
+`@custom theme <name> {}` / `@custom theme <name> dark {}` in the CSS entry;
+the preset default is an empty record). The theme preflight emits each variant
+after the base `:root` and mode blocks as a zero-specificity
+`:where(.theme-<name>){…}` variable-override block, and each of its
+non-default modes last as
+`:where(<mode> .theme-<name>,.theme-<name>:is(<mode>),.theme-<name> <mode>){…}`
+with the configured mode selector — mode-above, same-element, and mode-below
+arrangements all covered. Toggling the single `theme-<name>` class re-skins a
+subtree with no regeneration; custom-property inheritance resolves nested
+scopes, and `preflight: "on-demand"` filters variant entries like mode
+entries.
+
+The bare `theme-<name>` class is a dynamic rule that matches declared variants
+only and emits one internal indicator declaration, `--T-theme: <name>`, so
+the token stays matched and devtools show the active variant; the override CSS
+itself comes from the preflight. Activate themes with the literal class in
+markup — `@apply theme-<name>` (and compile-class strings) inline only that
+indicator declaration, never the variant's variables. In the preset-aware merger, bare kebab
+`theme-*` classes form one opaque merge family like the reset profiles: a
+later theme class replaces an earlier one and never conflicts with ordinary
+property utilities. `@teacss/config` enforces the variant contract — a
+variant may only override values the base theme declares.
+
 This is a TeaCSS-specific subset inspired by the
 [Radix Themes 3.3.0 Reset](https://github.com/radix-ui/themes/blob/3.3.0/packages/radix-ui-themes/src/components/reset.css),
 adapted to named atomic profiles and TeaCSS merge semantics rather than copied

package/dist/index.d.ts

@@ -110,11 +110,30 @@ interface Theme {
   }>;
   /** The mode whose palette is `theme.colors` (need not appear in `modes`). @default "light" */
   defaultMode?: string;
+  /**
+   * Named theme variants (`@custom theme <name>`): subtree-scoped variable
+   * overrides emitted under `:where(.theme-<name>)` after the base and mode
+   * blocks. The bare `theme-<name>` class activates one. A variant may only
+   * override values the base theme declares — `@teacss/config` enforces that
+   * contract for entry-declared variants.
+   */
+  themes?: Record<string, ThemeVariant>;
   /** Root selector(s) used when emitting preflight CSS custom properties */
   preflightRoot?: Arrayable<string>;
   /** Additional CSS custom properties merged after the default theme-derived preflight variables */
   preflightBase?: Record<string, string | number>;
 }
+/**
+ * One named theme variant: the scalar scales plus color-only mode overrides
+ * (entry-authored variants carry only `dark`). Structural records, mode
+ * bookkeeping, and preflight options stay top-level-theme-only.
+ */
+interface ThemeVariant extends Omit<Theme, "animation" | "modes" | "defaultMode" | "themes" | "preflightRoot" | "preflightBase"> {
+  modes?: Record<string, {
+    colors?: ColorPalette;
+    semanticColors?: SemanticColors;
+  }>;
+}
 type CustomRule = Rule<Theme>;
 type CustomShortcut = StaticShortcut | DynamicShortcut<Theme>;
 /** Ancestor selectors for the class-triggered `dark` / `light` modes. @default `.dark` / `.light` */