# fontPaletteValues

Emit an `@font-palette-values` rule and return a reference for color font palettes.

`fontPaletteValues` emits a named palette for a color font. The compiler replaces the call with a generated dashed name, which `fontPalette` accepts.

```tsx title="Icon.tsx"
import { style } from 'zyzz'
import { fontPaletteValues } from 'zyzz/web'

// Emits `@font-palette-values --z-fontpalettevalues-brand{…}`
const brand = fontPaletteValues({
  basePalette: 0,
  fontFamily: '"Brand Icons"',
  overrideColors: '0 #ff5500, 1 #111111',
})

export function Icon() {
  return <span {...styles.icon()}>★</span>
}

namespace styles {
  export const icon = style({ fontFamily: '"Brand Icons"', fontPalette: brand })
}
```

## Signature

```ts
// Palette descriptors, optionally inside grouping keys
fontPaletteValues(descriptors, context?)
```

## Parameters

### descriptors.fontFamily

* **Type:** `string`

The color font family the palette applies to.

```ts
// The palette applies only to this family
fontPaletteValues({ fontFamily: '"Brand Icons"' })
```

### descriptors.basePalette

* **Type:** `'light' | 'dark' | number`
* **Default:** `undefined`

The font's built-in palette to start from, by index or by its light or dark flag. Indices must be nonnegative integers.

```ts
// Starts from the font's dark palette
fontPaletteValues({ basePalette: 'dark', fontFamily: '"Brand Icons"' })
```

### descriptors.overrideColors

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

Comma-separated pairs of palette index and color, applied over the base palette.

```ts
import { fontPaletteValues } from 'zyzz/web'

export const accent = fontPaletteValues({
  fontFamily: '"Brand Icons"',
  // Replaces the first color only
  overrideColors: '0 crimson',
})
```

### descriptors\[atRule]

* **Type:** `` '@layer' | `@${'container' | 'layer' | 'media' | 'supports'}${' ' | '\t' | '\n' | '\r' | '\f' | '(' | `/*${string}*/`}${string}` ``

Grouping keys around a complete set of descriptors. Each value holds a complete definition or further grouping keys, and outer keys emit outer groups. A bare `@layer` key emits an anonymous layer.

```ts
import { fontPaletteValues } from 'zyzz/web'

export const night = fontPaletteValues({
  // Emits the rule inside `@layer fonts`
  '@layer fonts': { basePalette: 'dark', fontFamily: '"Brand Icons"' },
})
```

### context.id

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

A fixed identity, which replaces the name derived from the binding. It also separates two modules that declare the same binding name. Without a compiler transform, a call requires it.

```ts
// Returns `--z-fontpalettevaluesid-brand`
fontPaletteValues({ fontFamily: '"Brand Icons"' }, { id: 'brand' })
```

## Returns

### reference

* **Type:** `fontPaletteValues.Reference`

The generated dashed name. `fontPalette` and custom properties, such as a `vars` assignment, accept it. Other properties reject it. Imports, re-exports, and packed libraries keep the same name. The compiler omits definitions that are neither exported nor referenced.

```ts
// Compiles to `font-palette:--z-fontpalettevalues-brand`
style({ fontPalette: brand })
```

## Types

* **`fontPaletteValues.Options`:** The accepted descriptors.
* **`fontPaletteValues.Reference`:** The returned palette name.

```ts
import type { fontPaletteValues } from 'zyzz/web'

// Accepts only palette references
export type Palettes = Readonly<Record<string, fontPaletteValues.Reference>>
```

## Errors

TypeScript rejects unknown descriptors, negative or fractional palette indices, and a palette reference outside `fontPalette`.

```ts
import { style } from 'zyzz'
import { fontPaletteValues } from 'zyzz/web'

const brand = fontPaletteValues({ fontFamily: '"Brand Icons"' })

// A palette is not an animation
style({ animationName: brand })
// error: Type 'Reference' is not assignable to type 'never'.
```

The compiler reports `Source.ExtractError` for invalid descriptor values. Without a compiler transform, a call without `context.id` throws an `Error`. Native builds reject the call with `Native.CompileError`.