tailwind-syntax-functional-utilities

name	tailwind-syntax-functional-utilities
description	Use when authoring custom Tailwind utilities in v4 with the `@utility` directive that need to accept parameters: a theme-namespace key (like `tab-github`, `tab-2`, `tab-4`), a bare integer/number/ratio/percentage, a literal keyword, an arbitrary bracketed value, or a slash-modifier (like `text-base/relaxed`). Prevents the common v3-to-v4 plugin-authoring mistakes: writing a `matchUtilities()` JS plugin where a native `@utility name-* { ... }` block would do, attempting to use `--value()` / `--modifier()` / `--alpha()` / `--spacing()` inside v3 (silently ignored as unrecognised CSS functions), and forgetting that `--value()` accepts multiple type forms simultaneously so users can pick theme key OR bare integer OR arbitrary bracket on the same utility. Covers: the four v4-only CSS functions `--value()`, `--modifier()`, `--alpha()`, `--spacing()`; type-hint syntax (`integer`, `[length]`, `--namespace-*`, literal strings, `[*]`); default-value syntax via `--default(<value>)`; combining theme keys with bare and arbitrary values in a single utility definition; the migration path from v3 `matchUtilities()` plugin to v4 `@utility` directive. v4 ONLY: these functions do not exist in v3 and silently fail there. Keywords: functional utilities, custom utility, @utility directive, --value, --modifier, --alpha, --spacing, theme namespace, bare values, arbitrary values, type hints, integer, length, ratio, percentage, color, custom plugin, matchUtilities, how do I make a custom utility, v4 plugin authoring, tab-size utility, --tab-size-*, --default, default value, modifier slash, text-base/6, line-height pairing, color-mix opacity, alpha compose, spacing calc.
license	MIT
compatibility	Designed for Claude Code. Requires Tailwind CSS v4.0+.
metadata	{"author":"OpenAEC-Foundation","version":"1.0"}

Tailwind CSS : Functional Utilities (v4 only)

Native CSS functions that turn @utility name-* { ... } blocks into parameterised utilities. Replaces v3 matchUtilities() JS plugin authoring with CSS-first directives. NEVER use these in v3 : the CSS functions are unrecognised tokens and the build silently emits broken CSS.

Quick Reference

Four functions

Function	Purpose	Returns
--value(<type-or-namespace>)	Resolve the suffix of a name-* utility against a type, literal list, theme namespace, or arbitrary bracket	The matched value
--modifier(<type-or-namespace>)	Resolve the part after / in name-X/Y against the same type system	The matched value, or --default(...) if none
--alpha(var(--color-*) / <percentage>)	Compose an alpha value into a colour via color-mix()	A colour with alpha applied
--spacing(<number>)	Multiply the spacing scale base by a number	calc(var(--spacing) * <number>)

Three invariants

1. ALWAYS define functional utilities with @utility <name>-* { ... } in v4. NEVER reach for matchUtilities() in a v4 project unless backward-compatibility with a v3 JS plugin is required.
2. ALWAYS list multiple --value(...) lines in the same @utility block to accept multiple value forms (theme key + bare + arbitrary). The CSS cascade picks the first match.
3. ALWAYS use --alpha() over color-mix() directly for clarity, and --spacing() over hand-written calc(var(--spacing) * n) for the same reason.

Minimal canonical example

@theme {
  --tab-size-github: 8;
}

@utility tab-* {
  tab-size: --value(--tab-size-*);   /* theme key form : tab-github */
  : (integer);        
  : ([integer]);      
}