@bamboocss/types 1.30.0 → 1.31.0

package/dist/composition.d.ts

@@ -37,7 +37,7 @@ type TextStyleProperty =
   | 'fontVariationSettings'
   | 'fontWeight'
   | 'hangingPunctuation'
-  | 'hypens'
+  | 'hyphens'
   | 'hyphenateCharacter'
   | 'hyphenateLimitChars'
   | 'letterSpacing'

package/dist/config.d.ts

@@ -24,24 +24,50 @@ export interface Patterns {
   [pattern: string]: PatternConfig
 }
 
-export interface PresetCore {
-  /**
-   * The css selectors or media queries shortcuts.
-   * @example `{ hover: "&:hover" }`
-   */
-  conditions: Conditions
+/**
+ * Everything emitted at the document level rather than against a class.
+ *
+ * These were four top-level keys — `globalCss`, `globalFontface`, `globalPositionTry` and
+ * `globalVars`. Grouping them is not only tidier: `globalVars` was the one of the four that
+ * `PresetCore` never listed, so it kept its `extend` wrapper in the *resolved* config while
+ * its three siblings lost theirs. One key cannot disagree with itself that way.
+ */
+export interface GlobalCore {
   /**
    * The global styles for your project.
    */
-  globalCss: GlobalStyleObject
+  css: GlobalStyleObject
   /**
    * The global fontface for your project.
    */
-  globalFontface?: GlobalFontface
+  fontface?: GlobalFontface
   /**
    * The global custom position try fallback option
    */
-  globalPositionTry?: GlobalPositionTry
+  positionTry?: GlobalPositionTry
+  /**
+   * The css variables for your project.
+   */
+  vars?: GlobalVarsDefinition
+}
+
+interface ExtendableGlobal {
+  css?: ExtendableGlobalStyleObject
+  fontface?: ExtendableGlobalFontface
+  positionTry?: ExtendableGlobalPositionTry
+  vars?: ExtendableGlobalVars
+}
+
+export interface PresetCore {
+  /**
+   * The css selectors or media queries shortcuts.
+   * @example `{ hover: "&:hover" }`
+   */
+  conditions: Conditions
+  /**
+   * Styles, fontfaces, position-try fallbacks and css variables emitted at the document level.
+   */
+  global: GlobalCore
   /**
    * Used to generate css utility classes for your project.
    */
@@ -58,10 +84,6 @@ export interface PresetCore {
    * Common styling or layout patterns for your project.
    */
   patterns: Record<string, PatternConfig>
-  /**
-   * Multiple themes for your project.
-   */
-  themes?: ThemeVariantsMap
 }
 
 interface ExtendablePatterns {
@@ -125,17 +147,6 @@ interface ExtendableGlobalPositionTry {
   extend?: GlobalPositionTry | undefined
 }
 
-export interface ThemeVariant extends Pick<Theme, 'tokens' | 'semanticTokens'> {}
-
-export interface ThemeVariantsMap {
-  [name: string]: ThemeVariant
-}
-
-interface ExtendableThemeVariantsMap {
-  [name: string]: ThemeVariantsMap | ThemeVariant | undefined
-  extend?: ThemeVariantsMap | undefined
-}
-
 export interface ExtendableOptions {
   /**
    * The css selectors or media queries shortcuts.
@@ -143,17 +154,9 @@ export interface ExtendableOptions {
    */
   conditions?: ExtendableConditions
   /**
-   * The global styles for your project.
-   */
-  globalCss?: ExtendableGlobalStyleObject
-  /**
-   * The global fontface for your project.
-   */
-  globalFontface?: ExtendableGlobalFontface
-  /**
-   * The global custom position try fallback option
+   * Styles, fontfaces, position-try fallbacks and css variables emitted at the document level.
    */
-  globalPositionTry?: ExtendableGlobalPositionTry
+  global?: ExtendableGlobal
   /**
    * Used to generate css utility classes for your project.
    */
@@ -170,14 +173,6 @@ export interface ExtendableOptions {
    * Common styling or layout patterns for your project.
    */
   patterns?: ExtendablePatterns
-  /**
-   * The css variables for your project.
-   */
-  globalVars?: ExtendableGlobalVars
-  /**
-   * The theme variants for your project.
-   */
-  themes?: ExtendableThemeVariantsMap
 }
 
 export interface ImportMapInput {
@@ -257,6 +252,19 @@ interface FileSystemOptions {
    * @default 'info'
    */
   logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'silent'
+  /**
+   * Show only the log types matching this pattern, at debug level.
+   *
+   * Log types are namespaced — `vite:transform`, `tokens:unresolved`, `prune:tokens`,
+   * `config` — so `'prune:*'` follows one subsystem without raising `logLevel` and
+   * un-silencing everything else.
+   *
+   * The matcher already existed and was reachable only through the `BAMBOO_DEBUG`
+   * environment variable, which put it out of reach of a checked-in config.
+   *
+   * @example 'vite:*, prune:tokens'
+   */
+  logFilter?: string
 }
 
 interface CssgenOptions {
@@ -290,121 +298,14 @@ interface CssgenOptions {
    */
   minify?: boolean
   /**
-   * Whether to drop token css variables that nothing in the generated css can reach.
-   *
-   * The token layer declares every token in the theme, and an app typically uses a small
-   * fraction of them, so this is usually the largest single saving in render-blocking css.
-   *
-   * The same walk also drops an `@property` registration for a custom property the finished
-   * stylesheet neither declares nor reads. A preset registers what its utilities compose —
-   * filters, gradients, transforms, transitions — and ships the whole set regardless of what
-   * the app draws, so an app using none of them carries all of it for nothing. Registrations
-   * declared through `globalVars` are yours and are never removed.
-   *
-   * It is opt-in because reachability cannot be proven for every reference. `token()`,
-   * `token()` and `token.value()` calls are read out of the source, as is any literal
-   * `var(--x)` written by hand — and each form is resolved through a constant or a template
-   * literal the extractor can follow, not only through a path spelled out at the call. Three
-   * things stay invisible: a token named by a path assembled from a value that only exists at
-   * runtime, one referenced only from a stylesheet outside `include`, and one used by a
-   * separate package consuming the output as design tokens. Use `staticCss` to keep those.
-   *
-   * Both forms are a risk, which is a change. `token()` used to hand javascript a literal for
-   * a plain token, so a path it could not resolve cost nothing; it now returns `var(--x)` for
-   * *every* token. Only `token.value()` returns a literal, and only for a token that has one.
-   * So a path this pass cannot read is a declaration that has to survive whichever form asked
-   * for it.
-   *
-   * A custom property declared by `globalCss` or `globalVars` is not one of these cases:
-   * the declaration ships whether or not anything in the stylesheet reads it, so whatever
-   * it references is kept alongside it.
-   *
-   * The cost of that is bluntness. Because `token()` can name any token, a project that
-   * reaches for one from javascript keeps *every* token declaration — on the default preset
-   * that is 468 names against the 68 the old, narrower exemption kept, and a token layer of
-   * 442 declarations rather than 2. It used to cover only virtual tokens, tokens carrying a
-   * condition, and the positive counterpart each negative token pins through
-   * `calc(var(--spacing-4) * -1)`.
-   *
-   * The exemption is skipped entirely for a project that never reaches for a token from
-   * javascript. The tokens artifact is generated into the project rather than installed, so
-   * the import is written in your own source and a scan of `include` finds it — a call, or an
-   * import of any module the artifact could be. That is the whole saving, and it is
-   * all-or-nothing: a project with one caller keeps every declaration.
-   *
-   * The scan reads `include`, which scopes style extraction rather than everything that may
-   * import — so a script, a config, or a sibling workspace package that calls `token()` is
-   * not covered, nor is a binding renamed away from `token`, as in `const t = token`. Both
-   * are rare and neither reports itself: the declaration goes and the call returns a `var()`
-   * nothing declares. Setting this to `false` keeps every declaration if you are in that
-   * position.
-   *
-   * Setting this to `false` keeps every token declaration, but still drops the `@property`
-   * registrations. Those are not tokens — nothing hands one to javascript and none appear
-   * in the `token()` surface — so the reachability problem above does not apply to them,
-   * and opting out of token pruning should not mean shipping a preset's whole filter and
-   * gradient set for nothing.
-   *
-   * @default true
+   * What to drop from the generated stylesheet. See `PruneOptions`.
    */
-  pruneUnusedTokens?: boolean | 'strict'
-  /**
-   * Drop `@keyframes` rules nothing can reach.
-   *
-   * A preset declares every animation it offers and an app uses a handful, so the rest
-   * are dead weight in the stylesheet that blocks first paint. Only keyframes the theme
-   * declares are ever removed — one emitted by `globalCss` is left alone.
-   *
-   * A name is kept when any declaration in the generated css names it, and when it
-   * appears anywhere under `include`, which covers an animation assembled at runtime or
-   * applied through an inline `style` rather than through bamboo. That textual fallback
-   * is deliberately over-inclusive: keeping an unused keyframe costs bytes, dropping a
-   * used one breaks the animation.
-   *
-   * @default true
-   */
-  pruneUnusedKeyframes?: boolean
-  /**
-   * Whether to drop the parts of the reset that style elements your source never renders.
-   *
-   * Two thirds of the reset is bound to specific elements — 41 of them, covering `table`,
-   * `pre`, `kbd`, `optgroup` and the rest of the long tail. The reset is a fixed size, so it
-   * dominates a small stylesheet: a third of one sandbox's css here and four fifths of
-   * another's, of which 13% and 34% respectively is for elements those projects never render.
-   *
-   * A selector list loses only the parts naming unrendered elements, so a rule shared between
-   * `button` and `::file-selector-button` keeps the half that still applies. `html` and `body`
-   * are never removed.
-   *
-   * Off by default, and it cannot be made safe by default. Unlike the token and keyframe
-   * passes there is nothing to prove this against: an element rendered by a dependency's
-   * component, by `dangerouslySetInnerHTML`, or by markdown is invisible to a scan of your own
-   * source. What you get wrong is an element quietly losing its reset — no error, no warning.
-   * Reach for it when you control the markup and have measured that it pays.
-   *
-   * The blind spot to check first is your own entry template. The scan reads `include`, and
-   * `include` conventionally covers components rather than markup — a glob rooted at `./src`
-   * does not match `index.html`, so an element appearing only there is dropped. Add the
-   * template to `include` to cover it — the scan reads any file listed, not only ones the
-   * parser understands, and reads it from disk rather than from the build's parsed copy, so
-   * a single-file component's markup survives the transform to tsx.
-   *
-   * A scoped reset is handled: `preflight: { scope: '.app' }` writes `.app table`, and the
-   * scope is stripped before an element is read out. `bamboo cssgen preflight` prunes too.
-   *
-   * @default false
-   */
-  prunePreflight?: boolean
+  prune?: PruneOptions
   /**
    * The root selector for the css variables.
    * @default ':where(:root, :host)'
    */
   cssVarRoot?: string
-  /**
-   * Whether to use `lightningcss` instead of `postcss` for css optimization.
-   * @default false
-   */
-  lightningcss?: boolean
   /**
    * Browserslist query to target specific browsers.
    * @see https://www.npmjs.com/package/browserslist
@@ -434,7 +335,7 @@ interface CodegenOptions {
    * This is useful if want to shorten the class names or css variables.
    * @default false
    */
-  hash?: boolean | { cssVar: boolean; className: boolean }
+  hash?: boolean | { cssVar?: boolean; className?: boolean }
   /**
    * Change generated typescript definitions to be more strict for property having a token or utility.
    */
@@ -459,8 +360,21 @@ interface CodegenOptions {
    */
   outExtension?: 'mjs' | 'js'
   /**
-   * Whether to force consistent type extensions for generated typescript .d.ts files.
-   * If set to `true` and `outExtension` is set to `mjs`, the generated typescript .d.ts files will have the extension `.d.mts`.
+   * Emit `.d.mts` declarations beside `.mjs`, and import them by their `.mjs` specifier.
+   *
+   * Off by default, which looks like the wrong default and is not. `moduleResolution:
+   * bundler` — Vite, Next, and most of what consumes this — resolves a directory import
+   * like `styled-system/css` by probing `index.ts`, `index.tsx`, `index.d.ts`, `index.js`.
+   * That list has no `.d.mts` in it, so turning this on makes every such import fail with
+   * `TS2307: Cannot find module`. It is for `node16`/`nodenext` consumers, who need the
+   * extensions to agree and who import by full specifier anyway.
+   *
+   * So this is a real fork in resolution behaviour rather than a flag with a correct
+   * setting, which is why it survived an attempt to delete it: making it unconditional
+   * broke every bundler-mode project in this repo.
+   *
+   * Only meaningful when `outExtension` is `mjs`.
+   *
    * @default false
    */
   forceConsistentTypeExtension?: boolean
@@ -468,7 +382,20 @@ interface CodegenOptions {
 
 interface PresetOptions {
   /**
-   * Used to create reusable config presets for your project or team.
+   * The complete list of presets, in order. Reusable across a project or team.
+   *
+   * Authoritative: what you write is what is loaded. Import `defaultPresets` to keep the
+   * defaults alongside your own.
+   *
+   * ```ts
+   * import { defaultPresets } from '@bamboocss/dev/presets'
+   * presets: [...defaultPresets, myPreset]
+   * ```
+   *
+   * Leaving it unset loads `defaultPresets`. Setting it to `[]` loads nothing — which is
+   * what the removed `eject: true` meant. Previously neither was true of a config that
+   * merely *listed* a preset: doing so kept `@bamboocss/preset-base` and silently dropped
+   * `@bamboocss/preset-bamboo`, so `presets` was neither additive nor replacing.
    */
   presets?: (string | Preset | Promise<Preset>)[]
 }
@@ -485,6 +412,139 @@ export interface PluginsOptions {
   plugins?: BambooPlugin[]
 }
 
+/**
+ * What to drop from the generated stylesheet, and how to account for it.
+ *
+ * These were three top-level options — `pruneUnusedTokens`, `pruneUnusedKeyframes` and
+ * `prunePreflight` — which disagreed with each other on all three of naming, default and
+ * value type. Grouping them is what makes one default reading of "prune" possible.
+ */
+export interface PruneOptions {
+  /**
+   * How to decide which token css variables to keep.
+   *
+   * The token layer declares every token in the theme, and an app typically uses a small
+   * fraction of them, so this is usually the largest single saving in render-blocking css.
+   *
+   * - `off` keeps every token declaration.
+   * - `reachable` keeps what the generated css reaches. Because `token()` can name any
+   *   token, a project that calls it from javascript *anywhere* keeps every declaration —
+   *   on the default preset that is 468 names against the 68 a narrower exemption kept, and
+   *   a token layer of 442 declarations rather than 2. The exemption is skipped entirely for
+   *   a project that never reaches for a token from javascript, so the saving is
+   *   all-or-nothing: one caller keeps every declaration.
+   * - `accounted` reads the token paths out of your source and keeps only those. `token()`
+   *   and `token.value()` calls are resolved through a constant or a template literal the
+   *   extractor can follow, not only through a path spelled at the call, as is any literal
+   *   `var(--x)` written by hand.
+   *
+   * Under `accounted`, a path the build cannot follow makes the keep set fall back to
+   * `reachable`'s blanket keep rather than silently dropping a declaration — which is why
+   * `unresolvedPath` exists, and why setting it to `error` is what makes `accounted` worth
+   * asking for: it guarantees you are shipping the exact set rather than the fallback.
+   *
+   * Three things stay invisible to `accounted`: a token named by a path assembled from a
+   * value that only exists at runtime, one referenced only from a stylesheet outside
+   * `include`, and one used by a separate package consuming the output as design tokens. The
+   * scan reads `include`, which scopes style extraction rather than everything that may
+   * import — so a script, a config, or a sibling workspace package that calls `token()` is
+   * not covered, nor is a binding renamed away from `token`, as in `const t = token`. Use
+   * `staticCss` to keep those.
+   *
+   * A custom property declared by `global.css` or `global.vars` is not one of these cases:
+   * the declaration ships whether or not anything in the stylesheet reads it, so whatever it
+   * references is kept alongside it.
+   *
+   * @default 'reachable'
+   */
+  tokens?: 'off' | 'reachable' | 'accounted'
+  /**
+   * What to do about a token path `accounted` cannot follow.
+   *
+   * A path spelled at the call resolves; one assembled at runtime does not. An unfollowable
+   * path is what forces `accounted` back onto the blanket keep, so this decides whether that
+   * happens quietly, loudly, or not at all.
+   *
+   * - `off` falls back and says nothing.
+   * - `warn` falls back and reports what it could not follow.
+   * - `error` fails the build, so the fallback can never ship unnoticed.
+   *
+   * Inert under `tokens: 'off'` and `tokens: 'reachable'`, which run no accounting pass.
+   *
+   * Named for what it checks rather than `strict`, which already means something unrelated
+   * here: `strictTokens` and `strictPropertyValues` narrow generated *typescript*, and
+   * neither implies nor is implied by this.
+   *
+   * @default 'warn'
+   */
+  unresolvedPath?: 'off' | 'warn' | 'error'
+  /**
+   * Drop an `@property` registration the finished stylesheet neither declares nor reads.
+   *
+   * A preset registers what its utilities compose — filters, gradients, transforms,
+   * transitions — and ships the whole set regardless of what the app draws, so an app using
+   * none of them carries all of it for nothing.
+   *
+   * Its own flag rather than a side effect of `tokens`, which is what it used to be: the
+   * registrations were dropped even under the old `tokens: false`, so an option documented
+   * as keeping every token declaration quietly removed something else. These are not tokens
+   * — nothing hands one to javascript and none appear in the `token()` surface — so the
+   * reachability problem that makes `tokens` cautious does not apply to them.
+   *
+   * Registrations declared through `global.vars` are yours and are never removed.
+   *
+   * @default true
+   */
+  propertyRegistrations?: boolean
+  /**
+   * Drop `@keyframes` rules nothing can reach.
+   *
+   * A preset declares every animation it offers and an app uses a handful, so the rest
+   * are dead weight in the stylesheet that blocks first paint. Only keyframes the theme
+   * declares are ever removed — one emitted by `global.css` is left alone.
+   *
+   * A name is kept when any declaration in the generated css names it, and when it
+   * appears anywhere under `include`, which covers an animation assembled at runtime or
+   * applied through an inline `style` rather than through bamboo. That textual fallback
+   * is deliberately over-inclusive: keeping an unused keyframe costs bytes, dropping a
+   * used one breaks the animation.
+   *
+   * @default true
+   */
+  keyframes?: boolean
+  /**
+   * Whether to drop the parts of the reset that style elements your source never renders.
+   *
+   * Two thirds of the reset is bound to specific elements — 41 of them, covering `table`,
+   * `pre`, `kbd`, `optgroup` and the rest of the long tail. The reset is a fixed size, so it
+   * dominates a small stylesheet: a third of one sandbox's css here and four fifths of
+   * another's, of which 13% and 34% respectively is for elements those projects never render.
+   *
+   * A selector list loses only the parts naming unrendered elements, so a rule shared between
+   * `button` and `::file-selector-button` keeps the half that still applies. `html` and `body`
+   * are never removed.
+   *
+   * Off by default, and it cannot be made safe by default. Unlike the token and keyframe
+   * passes there is nothing to prove this against: an element rendered by a dependency's
+   * component, by `dangerouslySetInnerHTML`, or by markdown is invisible to a scan of your own
+   * source. What you get wrong is an element quietly losing its reset — no error, no warning.
+   * Reach for it when you control the markup and have measured that it pays.
+   *
+   * The blind spot to check first is your own entry template. The scan reads `include`, and
+   * `include` conventionally covers components rather than markup — a glob rooted at `./src`
+   * does not match `index.html`, so an element appearing only there is dropped. Add the
+   * template to `include` to cover it — the scan reads any file listed, not only ones the
+   * parser understands, and reads it from disk rather than from the build's parsed copy, so
+   * a single-file component's markup survives the transform to tsx.
+   *
+   * A scoped reset is handled: `preflight: { scope: '.app' }` writes `.app table`, and the
+   * scope is stripped before an element is read out. `bamboo cssgen preflight` prunes too.
+   *
+   * @default false
+   */
+  preflight?: boolean
+}
+
 export interface Config
   extends
     ExtendableOptions,
@@ -495,19 +555,20 @@ export interface Config
     HooksOptions,
     PluginsOptions {
   /**
-   * Whether to opt-out of the defaults config presets: [`@bamboocss/preset-base`, `@bamboocss/preset-bamboo`]
-   * @default 'false'
-   */
-  eject?: boolean
-  /**
-   * The validation strictness to use when validating the config.
-   * - When set to 'none', no validation will be performed.
-   * - When set to 'warn', warnings will be logged when validation fails.
-   * - When set to 'error', errors will be thrown when validation fails.
+   * What to do when the config does not validate.
+   *
+   * - `off` performs no validation.
+   * - `warn` logs what failed.
+   * - `error` throws.
+   *
+   * A retired spelling is checked ahead of this and is not silenceable by it — that is
+   * output which is already broken rather than an opinion about a config that still
+   * builds. Neither is a removed option: `off` used to switch off the one mechanism that
+   * tells an upgrader their setting is no longer read.
    *
    * @default 'warn'
    */
-  validation?: 'none' | 'warn' | 'error'
+  validation?: 'off' | 'warn' | 'error'
 }
 
 export interface Preset extends ExtendableOptions, PresetOptions {
@@ -556,8 +617,10 @@ export interface PrefixOptions {
 type ReqConf = Required<UserConfig>
 
 export type ConfigPath = Exclude<
-  | Exclude<NonNullable<Keys<ReqConf>>, 'theme'>
+  | Exclude<NonNullable<Keys<ReqConf>>, 'theme' | 'global' | 'prune'>
   | PathIn<ReqConf, 'theme'>
+  | PathIn<ReqConf, 'global'>
+  | PathIn<ReqConf, 'prune'>
   | PathIn<ReqConf, 'patterns'>
   | PathIn<ReqConf, 'staticCss'>
   | (string & {}),

package/dist/logger.d.ts

@@ -8,6 +8,11 @@ export interface LogEntry {
 
 export interface LoggerInterface {
   level: 'debug' | 'info' | 'warn' | 'error' | 'silent'
+  /**
+   * Comma-separated globs over the namespaced log type. Non-empty shows only matching types,
+   * at debug level, whatever `level` is set to.
+   */
+  filter: string
   print(data: any): void
   onLog?: (entry: LogEntry) => void
   warn: (type: string, data: any) => void

package/dist/pattern.d.ts

@@ -12,6 +12,14 @@ export type PatternProperty =
 
 export interface PatternHelpers {
   map: (value: any, fn: (value: string) => string | undefined) => any
+  /**
+   * The css variable reference for a token path, or `fallback` when the path names no token.
+   *
+   * `token('spacing.4', '4')` is `var(--spacing-4)` where that token exists and `'4'` where it
+   * does not — so a pattern can accept either a token name or a raw css value without knowing
+   * the theme.
+   */
+  token: (path: string, fallback?: string) => string | undefined
   isCssUnit: (value: any) => boolean
   isCssVar: (value: any) => boolean
   isCssFunction: (value: any) => boolean
@@ -49,13 +57,21 @@ export interface PatternConfig<T extends PatternProperties = PatternProperties>
    */
   deprecated?: boolean | string
   /**
-   * Whether to only generate types for the specified properties.
-   * This will disallow css properties
-   */
-  strict?: boolean
-  /**
-   * @experimental
-   * Disallow certain css properties for this pattern
+   * Which css properties this pattern accepts alongside its own `properties`.
+   *
+   * - `all` accepts any css property.
+   * - `none` accepts only the pattern's declared `properties`.
+   * - `{ except }` accepts any css property but the ones listed.
+   *
+   * One option because these were two — `strict: true` for "none" and an `@experimental`
+   * `blocklist` for "all but these" — and the pair had an unrepresentable combination that
+   * silently did nothing: the blocklist is applied only to the type that lists css
+   * properties, which `strict: true` does not emit, so setting both dropped the blocklist.
+   *
+   * Types only. Nothing strips a blocked property at runtime — one passed anyway reaches
+   * `transform` and emits css.
+   *
+   * @default 'all'
    */
-  blocklist?: LiteralUnion<CssProperty>[]
+  cssProps?: 'all' | 'none' | { except: LiteralUnion<CssProperty>[] }
 }

package/dist/theme.d.ts

@@ -71,9 +71,28 @@ export interface Theme {
    * The color palette configuration for your project.
    */
   colorPalette?: ColorPaletteOptions
+  /**
+   * Alternate token sets, selectable at runtime.
+   *
+   * Was a top-level `themes`, one character from `theme` and impossible for TypeScript to
+   * tell apart — both spellings were valid keys, so the typo resolved to a different
+   * feature rather than to an error. A variant is part of the theme, so it lives in it.
+   */
+  variants?: ThemeVariantsMap
+}
+
+export interface ThemeVariant extends Pick<Theme, 'tokens' | 'semanticTokens'> {}
+
+export interface ThemeVariantsMap {
+  [name: string]: ThemeVariant
 }
 
-interface PartialTheme extends Omit<Theme, 'recipes' | 'slotRecipes'> {
+interface ExtendableThemeVariantsMap {
+  [name: string]: ThemeVariantsMap | ThemeVariant | undefined
+  extend?: ThemeVariantsMap | undefined
+}
+
+interface PartialTheme extends Omit<Theme, 'recipes' | 'slotRecipes' | 'variants'> {
   /**
    * Multi-variant style definitions for your project.
    * Useful for defining component styles.
@@ -87,8 +106,13 @@ interface PartialTheme extends Omit<Theme, 'recipes' | 'slotRecipes'> {
    * The color palette configuration for your project.
    */
   colorPalette?: Partial<ColorPaletteOptions>
+  /**
+   * Alternate token sets, selectable at runtime.
+   */
+  variants?: ExtendableThemeVariantsMap
 }
 
-export interface ExtendableTheme extends Theme {
+export interface ExtendableTheme extends Omit<Theme, 'variants'> {
+  variants?: ExtendableThemeVariantsMap
   extend?: PartialTheme | undefined
 }

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@bamboocss/types",
-  "version": "1.30.0",
+  "version": "1.31.0",
   "description": "The types for css bamboo",
   "homepage": "https://bamboocss.com",
   "license": "MIT",
   "author": "Gajus Kuizinas <gajus@gajus.com>",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/bamboocss/bamboo.git",
+    "url": "git+https://github.com/gajus/bamboocss.git",
     "directory": "packages/types"
   },
   "files": [
@@ -32,7 +32,7 @@
     "ncp": "2.0.0",
     "pkg-types": "2.3.0",
     "ts-morph": "28.0.0",
-    "@bamboocss/extractor": "1.30.0"
+    "@bamboocss/extractor": "1.31.0"
   },
   "scripts": {
     "dev": "tsx scripts/watch.ts",