---
title: "@kovojs/style"
description: StyleX-inspired typed styling: atomic style objects, attrs/props merging, CSS variables, and theme classes.
order: 6
---

# @kovojs/style

Generated from 1 public subpath — 14 exports, 14 documented. Do not edit by hand.

## `@kovojs/style`

**Task:** StyleX-inspired typed styling: atomic style objects, attrs/props merging, CSS variables, and theme classes.

Source: [`packages/style/src/index.ts`](https://github.com/kovojs/kovo/blob/main/packages/style/src/index.ts)

### Values

#### `create` {#create}

Compiles static Kovo style objects into opaque atomic style records. This is the
TS-native fork point for StyleX-style authoring: authored TSX stays source-like,
while the compiler consumes a separate internal extraction result and lowers
to ordinary class attributes for SPEC.md §5.2 fixpoint output.

**Signature**

```ts
function create<const Styles extends Record<string, StyleObject>>(
  styles: Styles,
): { readonly [Key in keyof Styles]: StyleHandle };
```

#### `attrs` {#attrs}

Merge compiled style records into Kovo JSX-shaped attributes: `class` plus a
serialized inline `style` escape. Kovo examples should prefer this shape outside
React because the emitted HTML remains plain and inspectable (SPEC.md §4.2).

**Signature**

```ts
function attrs(...styles: readonly StyleInput[]): {
  readonly class?: string;
  readonly style?: string;
};
```

#### `defineVars` {#definevars}

Define CSS custom-property tokens with deterministic `--kovo-*` names. The
returned values are ordinary `var(...)` strings so themes remain document CSS
and do not need shadow boundaries (SPEC.md §13.1).

**Signature**

```ts
function defineVars<const Tokens extends Record<string, CssValue>>(
  tokens: Tokens,
): Vars<Tokens>;
```

#### `keyframes` {#keyframes}

Define a CSS `@keyframes` animation, returning its deterministic
(`kv-<slug>-<hash>`) animation-name for use in `animationName`. The compiler's
StyleX extraction recognizes the `style.keyframes(...)` const, resolves this
name, and emits the matching `@keyframes` block into the served CSS asset
(SPEC.md §13.1); see `createKeyframes` for the engine's structured result.

**Signature**

```ts
function keyframes(frames: Readonly<Record<string, StyleObject>>): string;
```

#### `defineTheme` {#definetheme}

Define the app theme from one seed color. The v1 public surface is the
seed form (SPEC.md §13.1); deriving from a generated base theme is a
repo-internal capability exposed through `defineThemeFromBase`.

**Signature**

```ts
function defineTheme(options: DefineThemeOptions): KovoTheme;
```

#### `tokens` {#tokens}

Typed public token refs for app-authored source (SPEC.md §13.1).

**Signature**

```ts
const tokens: ThemeTokens = publicThemeTokens;
```

### Supporting types

#### `CssValue` {#cssvalue}

Values accepted in a Kovo static style object.

**Signature**

```ts
type CssValue = string | number | null | undefined;
```

#### `StyleHandle` {#stylehandle}

Framework-created style capability accepted by `style.attrs`.

The runtime representation has no public fields. Type assertions can bypass
TypeScript, but `attrs` still requires module-private WeakMap provenance.

**Signature**

```ts
interface StyleHandle {
  readonly [styleHandleIdentity]: true;
}
```

#### `StyleInput` {#styleinput}

A style argument accepted by `attrs`, including nested arrays of opaque handles.

**Signature**

```ts
type StyleInput = StyleHandle | null | false | undefined | ReadonlyArray<StyleInput>;
```

#### `StyleObject` {#styleobject}

Static style object accepted by `style.create`, including nested pseudos and at-rules.

**Signature**

```ts
interface StyleObject {
  readonly [property: string]: CssValue | StyleObject;
}
```

#### `Vars` {#vars}

Typed CSS variable group returned by `defineVars`; token values are `var(--kovo-*)` strings.

**Signature**

```ts
type Vars<Tokens extends Record<string, CssValue>> = {
  readonly [Key in keyof Tokens]: string;
} & {
  readonly [varsIdentity]: true;
};
```

#### `DefineThemeOptions` {#definethemeoptions}

App-facing options for generating one Kovo theme from a seed color.

**Signature**

```ts
interface DefineThemeOptions {
  /** Additional semantic colors harmonized with the seed. */
  readonly colors?: Readonly<
    Record<
      string,
      | string
      | number
      | {
          readonly blend?: boolean;
          readonly value: string | number;
        }
    >
  >;
  /** Material contrast level from -1 to 1. Defaults to 0. */
  readonly contrast?: number;
  /** Selector that receives dark system-token overrides. Defaults to `:root[data-theme="dark"]`. */
  readonly darkSelector?: string;
  /** Emit reference palette tone variables. Defaults to true. */
  readonly emitRef?: boolean;
  /** Seed color accepted as a CSS color string or finite ARGB number. */
  readonly seed: string | number;
  /** Shape token overrides. */
  readonly shape?: {
    readonly cornerFull?: string;
    readonly cornerLarge?: string;
    readonly cornerMedium?: string;
    readonly cornerSmall?: string;
  };
  /** Selector that receives light/default variables. Defaults to `:root`. */
  readonly selector?: string;
  /** Material dynamic scheme variant. Defaults to `tonal-spot`. */
  readonly variant?:
    | 'content'
    | 'expressive'
    | 'fidelity'
    | 'fruit-salad'
    | 'monochrome'
    | 'neutral'
    | 'rainbow'
    | 'tonal-spot'
    | 'vibrant';
}
```

#### `KovoTheme` {#kovotheme}

Generated theme values and CSS produced by `defineTheme`.

**Signature**

```ts
interface KovoTheme {
  readonly css: string;
  readonly custom: Readonly<Record<string, ReturnType<ThemeTokens['customColor']>>>;
  readonly dark: {
    readonly custom: Readonly<Record<string, ReturnType<ThemeTokens['customColor']>>>;
    readonly sys: ThemeTokens['sys'];
  };
  readonly light: {
    readonly custom: Readonly<Record<string, ReturnType<ThemeTokens['customColor']>>>;
    readonly sys: ThemeTokens['sys'];
  };
  readonly ref: ThemeTokens['ref']['palette'];
  readonly seed: string;
  readonly sys: ThemeTokens['sys'];
  readonly variant: NonNullable<DefineThemeOptions['variant']>;
}
```

#### `ThemeTokens` {#themetokens}

Typed public `var(...)` references for app-authored `style.create(...)` objects (SPEC.md §13.1).

**Signature**

```ts
interface ThemeTokens {
  readonly customColor: (name: string) => {
    readonly color: string;
    readonly colorContainer: string;
    readonly onColor: string;
    readonly onColorContainer: string;
  };
  readonly ref: {
    readonly palette: Readonly<
      Record<
        'error' | 'neutral' | 'neutralVariant' | 'primary' | 'secondary' | 'tertiary',
        Readonly<Record<number, string>>
      >
    >;
  };
  readonly sys: {
    readonly color: Readonly<
      Record<
        | 'background'
        | 'error'
        | 'errorContainer'
        | 'inverseOnSurface'
        | 'inversePrimary'
        | 'inverseSurface'
        | 'onBackground'
        | 'onError'
        | 'onErrorContainer'
        | 'onPrimary'
        | 'onPrimaryContainer'
        | 'onPrimaryFixed'
        | 'onPrimaryFixedVariant'
        | 'onSecondary'
        | 'onSecondaryContainer'
        | 'onSecondaryFixed'
        | 'onSecondaryFixedVariant'
        | 'onSurface'
        | 'onSurfaceVariant'
        | 'onTertiary'
        | 'onTertiaryContainer'
        | 'onTertiaryFixed'
        | 'onTertiaryFixedVariant'
        | 'outline'
        | 'outlineVariant'
        | 'primary'
        | 'primaryContainer'
        | 'primaryFixed'
        | 'primaryFixedDim'
        | 'scrim'
        | 'secondary'
        | 'secondaryContainer'
        | 'secondaryFixed'
        | 'secondaryFixedDim'
        | 'shadow'
        | 'surface'
        | 'surfaceBright'
        | 'surfaceContainer'
        | 'surfaceContainerHigh'
        | 'surfaceContainerHighest'
        | 'surfaceContainerLow'
        | 'surfaceContainerLowest'
        | 'surfaceDim'
        | 'surfaceTint'
        | 'surfaceVariant'
        | 'tertiary'
        | 'tertiaryContainer'
        | 'tertiaryFixed'
        | 'tertiaryFixedDim',
        string
      >
    >;
    readonly shape: Readonly<
      Record<'cornerFull' | 'cornerLarge' | 'cornerMedium' | 'cornerSmall', string>
    >;
  };
}
```