# defineConfig

Bind style and recipe helpers to a variable set, and return the config helpers.

A config module calls `defineConfig` once and exports the helpers it needs. Styles that import `style` from that module accept the set's token names, and the compiler emits the set's custom properties ahead of time.

```ts title="zyzz.config.ts"
import { defineConfig, defineVars } from 'zyzz'

const base = defineVars({
  color: { foreground: { light: '#171717', dark: '#fafafa' } },
  spacing: { page: '1rem' },
})

export const { appearance, script, style, variants, vars } = defineConfig({
  vars: base,
})
```

`defineConfig` is the root alias of `Config.create`, with the same options and inferred helpers.

## Signature

```ts
// Helpers bound to the options
defineConfig(options?)
```

## Parameters

### options.vars

* **Type:** `Vars.Definition | Vars.Values | { [name: string]: Vars.Definition | Vars.Values }`
* **Default:** `undefined`

One variable set, an inline record of values, or a catalog of named sets. Omit it for token-free helpers. A catalog requires `defaultVars`, and every named set must share the default set's paths and value types.

```ts
import { defineConfig, defineVars, extendVars } from 'zyzz'

const base = defineVars({ spacing: { page: '1rem' } })
const roomy = extendVars(base, { spacing: { page: '2rem' } })

export const { style, vars } = defineConfig({
  defaultVars: 'base',
  vars: { base, roomy },
})
```

### options.defaultVars

* **Type:** `string`
* **Default:** `undefined`

The catalog key applied when a scope or the document selects no set. It is required when `vars` holds named sets.

```ts
// Applies `base` until a scope selects `roomy`
defineConfig({ defaultVars: 'base', vars: { base, roomy } })
```

### options.mappings

* **Type:** `{ [category: string]: readonly string[] } | false`
* **Default:** `undefined`

Category-to-property mappings for token names. Each supplied category replaces its default properties, and `[]` disables that category's names. `false` turns off short names, so styles reference tokens by full path, such as `'spacing.page'`.

```ts
import { defineConfig } from 'zyzz'

export const { style } = defineConfig({
  mappings: {
    color: ['color', 'backgroundColor'],
    spacing: ['padding', 'gap'],
  },
  vars: { color: { brand: '#06c' }, spacing: { md: '8px' } },
})
```

[Category Fallbacks](#category-fallbacks) lists the default mappings and their lookup order.

### options.shorthands

* **Type:** `{ [alias: string]: readonly string[] }`
* **Default:** `undefined`

Local property aliases that expand to one or more CSS properties. Each expanded property validates the value on its own.

```ts
import { defineConfig } from 'zyzz'

export const { style } = defineConfig({
  shorthands: { px: ['paddingLeft', 'paddingRight'] },
  vars: { spacing: { md: '8px' } },
})

// Emits padding-left and padding-right
const chip = style({ px: 'md' })
```

### options.layers

* **Type:** `readonly string[]`
* **Default:** `undefined`

Ordered CSS layer names, emitted as one `@layer` statement. Names are plain or dotted CSS identifiers. Styles place declarations in a layer with an `@layer` key.

```ts
import { defineConfig } from 'zyzz'

export const { style } = defineConfig({
  layers: ['components', 'overrides'],
})

const label = style({
  // Emits this declaration inside `@layer overrides`
  '@layer overrides': { color: 'blue' },
})
```

### options.defaultLayer

* **Type:** `string`
* **Default:** `undefined`

The layer for declarations that no `@layer` key places. Omit it to keep declarations unlayered. Unlayered caller styles then outrank layered component styles.

```ts
// Every bound style and recipe lands in `components` by default
defineConfig({
  defaultLayer: 'components',
  layers: ['components', 'overrides'],
})
```

### options.output

* **Type:** `'react' | 'html'`
* **Default:** `'react'`

The props shape applications return. `'react'` returns `className` and a `style` object. `'html'` returns `class` and a serialized `style` string.

```ts
// Applications return { class, style } strings
defineConfig({ output: 'html', vars: base })
```

### options.cssOutput

* **Type:** `'atomic' | 'grouped'`
* **Default:** `'atomic'`

The emitted CSS shape. Atomic output emits one rule per declaration and condition. Grouped output emits one scoped block per style. [CSS Output](/docs/guides/css-output) compares both.

```ts
// One rule block per style definition
defineConfig({ cssOutput: 'grouped', vars: base })
```

### options.composition

* **Type:** `'ordered' | 'independent'`
* **Default:** `'ordered'`

Whether the bound styles' class lists may combine on one element. Ordered class lists resolve conflicts in definition order. Independent atomic styles share one rule per repeated declaration, so combine them only with [`cx`](/docs/api/core/cx). [CSS Output](/docs/guides/css-output#independent-composition) shows the emitted rules.

```ts
// Repeated declarations share one short rule across styles
defineConfig({ composition: 'independent', vars: base })
```

### options.storageKey

* **Type:** `string`
* **Default:** `'zyzz'`

The localStorage key that [`appearance`](/docs/api/core/defineConfig/appearance) writes and [`script`](/docs/api/core/defineConfig/script) reads.

```ts
// Keeps preferences separate from other configs on the origin
defineConfig({ storageKey: 'acme-appearance', vars: base })
```

### options.id

* **Type:** `string`
* **Default:** `undefined`

A namespace for generated classes, scopes, and custom properties. Give each independently compiled config a distinct ID. Variable configs require it when source runs without a compiler transform.

```ts
// `color.brand` becomes `--z-acme-color-brand`
defineConfig({ id: 'acme', vars: { color: { brand: '#06c' } } })
```

## Token Values

A property with configured tokens accepts a token name or a compatible variable reference. Append ` !custom` to use any other CSS value. The suffix is removed from the emitted CSS, and the value keeps ordinary CSS type checking.

```ts
import { defineConfig } from 'zyzz'

const { style } = defineConfig({ vars: { spacing: { md: '8px' } } })

const button = style({
  padding: 'md',
  // An arbitrary length on a property with spacing tokens
  marginTop: '7px !custom',
})
```

CSS keywords need no suffix: CSS-wide keywords such as `inherit`, the property's own keywords such as `auto` on margins and `none` on `maxWidth`, and `currentColor`, `transparent`, and system colors such as `Highlight` on color properties. Named colors such as `red` and other literals still need ` !custom`.

```ts
import { defineConfig } from 'zyzz'

const { style } = defineConfig({
  vars: { color: { text: '#111' }, spacing: { md: '8px' } },
})

const link = style({
  // Keywords pass on properties with color and spacing tokens
  color: 'inherit',
  marginInline: 'auto',
  outlineColor: 'Highlight',
})
```

Token names take precedence over CSS keywords, so a color token named `red` resolves to the variable while `'red !custom'` means the CSS color. Combine suffixes as `'red !custom !important'`. Properties without configured tokens accept either spelling.

## Category Fallbacks

A token name resolves through the categories mapped to the property, and the first category containing the name wins. Custom `mappings` replace a category's properties, and explicit `vars` references skip the lookup.

* **`color`:** `textColor`, then `color`.
* **`backgroundColor`:** `backgroundColor`, then `color`.
* **Border colors:** `borderColor`, then `color`.
* **`accentColor`, `caretColor`, `outlineColor`, `textDecorationColor`, `fill`, `stroke`:** The matching property category, then `color`.
* **Other color properties:** `color`.
* **Margin, padding, inset, and gap:** The matching category, then `spacing`.
* **`width`, `minWidth`, `maxWidth`:** The matching property category, `spacing`, then `container`.
* **`height`:** `height`, then `spacing`.
* **`minHeight`, `maxHeight`:** The matching property category, `height`, then `spacing`.
* **Inline sizes:** `spacing`, then `container`.
* **Block sizes:** `spacing`.
* **`flexBasis`:** `flexBasis`, `spacing`, then `container`.
* **`columns`:** `columns`, then `container`.
* **Scroll margin and padding, `borderSpacing`, `translate`, `textIndent`:** The matching category, then `spacing`.
* **Border radii:** `radius`.
* **`boxShadow` and `textShadow`:** `shadow` and `textShadow`.
* **`aspectRatio` and `perspective`:** `aspect` and `perspective`.
* **`transitionTimingFunction` and `animation`:** `ease` and `animate`.
* **Font properties:** `fontFamily`, `fontSize`, `fontWeight`, `letterSpacing`, and `lineHeight` each use only their matching category.
* **Other mapped properties:** The matching property category, such as `zIndex` or `opacity`.

```ts
import { defineConfig } from 'zyzz'

const { style } = defineConfig({
  vars: { color: { brand: '#06c' }, textColor: { brand: '#004a99' } },
})

// `textColor.brand` for color, `color.brand` for the background
const badge = style({ backgroundColor: 'brand', color: 'brand' })
```

`blur`, `dropShadow`, and `insetShadow` values have no mapped property, so styles reference them through `vars`. The `breakpoint` and `container` categories also supply query aliases.

## Returns

### style

* **Type:** `Config.StyleFactory`

The [`style`](/docs/api/core/style) function, accepting the config's token names and shorthands.

```ts
const card = style({ color: 'foreground', padding: 'page' })
```

### variants

* **Type:** `variants.Bound`

The [`variants`](/docs/api/core/variants) function, with the same token names and the config's query aliases.

```ts
const button = variants({ variants: { size: { roomy: { padding: 'page' } } } })
```

### vars

* **Type:** `Config.VariableScope`

[Token references and scope selection](/docs/api/core/defineConfig/vars). Present when `options.vars` is set.

```ts
const rail = style({ width: vars.spacing.page })
```

### appearance

* **Type:** `{ get, set }`

[Document preference controls](/docs/api/core/defineConfig/appearance) for the variable set and color scheme.

```ts
appearance.set({ colorScheme: 'dark' })
```

### script

* **Type:** `() => string`

Returns the [inline preference script](/docs/api/core/defineConfig/script) that restores saved selections before the first paint.

```ts
const source = script()
```

## Types

* **`Config.create.Options`:** The accepted options.
* **`Config.create.ReturnType<options>`:** The helpers inferred from the options.
* **`Config.VariableConfig<options>`:** The helpers of a config with `vars`.

```ts title="theme.ts"
import { type Config, defineConfig } from 'zyzz'

// Shares one options object between configs
const options = {
  vars: { spacing: { md: '8px' } },
} satisfies Config.create.Options

export const { style } = defineConfig(options)
```

## Errors

TypeScript rejects unknown options, named sets with different paths, and token names a property cannot accept.

```ts
import { defineConfig } from 'zyzz'

defineConfig({
  defaultVars: 'base',
  // `roomy` lacks the `page` path of `base`
  vars: {
    base: { spacing: { page: '1rem' } },
    roomy: { spacing: { gap: '1rem' } },
    // error: Type '{ spacing: { gap: string; }; }' is not assignable to type 'never'.
  },
})
```

At runtime, the same mistakes throw `Config.InvalidError`, as do invalid layer names. Invalid variable values throw `Vars.InvalidError`.

Weights in the `fontWeight` category, or in a category mapped to `fontWeight`, must be numbers from 1 to 1000 or `fontWeight` keywords. A numeric string fails type checking and throws `Config.InvalidError`.

```ts
import { defineConfig } from 'zyzz'

// Weights are numbers, such as 500
defineConfig({ vars: { fontWeight: { medium: '500' } } })
// error: Type 'string' is not assignable to type 'never'.
```

## React Native

Native apps import [`defineConfig`](/docs/api/react-native/defineConfig) from `zyzz/react-native`. It takes the same options and returns the same helpers, plus a [`Provider`](/docs/api/react-native/Provider) that selects the color scheme, set, and window size for its descendants. Tokens resolve to native values.

```tsx title="App.tsx"
import type { ReactNode } from 'react'
import { defineConfig } from 'zyzz/react-native'

const { Provider } = defineConfig({
  vars: { color: { ink: { dark: '#eeeeee', light: '#111111' } } },
})

export function App(props: App.Props) {
  return (
    // Styles beneath resolve `ink` for the dark scheme
    <Provider colorScheme="dark">{props.children}</Provider>
  )
}

export declare namespace App {
  type Props = { children: ReactNode }
}
```

[Native Themes](/docs/guides/native/themes) covers set selection on native.
