Utilities & motion

cn

The class-composition utility that filters conditional fragments and resolves conflicting Tailwind utilities.

cn

Component workbench

Configure the production component, inspect it at responsive widths, copy synchronized JSX, and share the exact state from one workspace.

Merged class output

rounded-md px-4 py-3 bg-surface2 text-text

Generated example

This JSX stays synchronized with the controls and uses only public package APIs.

tsx

import { cn } from '@ai-created/ui';

export function Example() {
  const base = "rounded-md px-4 py-3";
  const conditional = "bg-surface2 text-text";
  const enabled = true;

  return (
    <div className={cn(base, enabled && conditional)}>
      Merged class output
    </div>
  );
}

Import

tsx

import { cn } from '@ai-created/ui';

Install from a reviewed release

Replace the version placeholder with the release tag your product has reviewed.

shell

npm install --install-links "git+https://github.com/TheMarco/ai-created-ui.git#vX.Y.Z"

Load semantic tokens

css

@import '@ai-created/ui/styles/tokens.css';

@tailwind base;
@tailwind components;
@tailwind utilities;

Extend Tailwind

module.exports = {
  presets: [require('@ai-created/ui/tailwind-preset')],
  content: [
    './src/**/*.{js,ts,jsx,tsx,mdx}',
    './node_modules/@ai-created/ui/src/**/*.{js,ts,jsx,tsx}',
  ],
};

Anatomy

Named regions define what belongs to the component, what remains optional, and where semantic responsibility lives.

Input fragments

Required

Ordered strings or falsy conditional values.

Falsy filter

Required

Removes false, null, and undefined inputs.

Tailwind merge

Required

Resolves utility conflicts by precedence.

Class string

Required

Serializable final className.

Construction and authoring

The Figma-equivalent asset model, auto-layout, resizing, properties, slots, content bounds, localization, and governance contract.

Asset kind

utility

Design library name

Code-only asset

Maturity

stable

Last reviewed

2026-08-29

Canvas applicability

This class-merging function has no Figma or canvas representation.

Auto layout

Direction: none
Gap: Not applicable
Padding: Not applicable
Alignment: Not applicable
Wrap: Not applicable

A pure string utility emits no element and owns no auto-layout mechanics.

Resizing

Width: not-applicable
Height: not-applicable
Minimum width: Not applicable
Maximum width: Not applicable
Minimum height: Not applicable
Maximum height: Not applicable
Overflow: not-applicable

A pure string utility has no width, height, constraints, or overflow.

Exposed design properties

Property	Type	Default	Code mapping	Options or notes
Class inputsRequired	slot	None	Function arguments in precedence order	No additional constraint
Include conditional input	boolean	true	Boolean expression passed as an input	No additional constraint

Nested assets and slots

tailwind-merge

helper / required

Resolves conflicting Tailwind utility classes.

Internal twMerge dependency

Content limits

Inputs

Class strings plus false, null, or undefined

Overflow: Split complex style decisions into named variant functions.

The utility is for class composition, not component architecture.

Localization and RTL

Not applicable; class merging has no reading direction of its own.
Verify logical-direction utilities when building localized components.

Responsive behavior

Not applicable; emitted classes inherit Tailwind responsive behavior.

Not applicable to utility

Responsive behavior is entirely determined by the input class strings.

Authoring limits

No Figma asset should be created for this utility.
Passing consumer className last is a policy choice; verify that it cannot remove required state or accessibility styles.
Canvas geometry, auto layout, component properties, instance swaps, and prototype interactions are not applicable.

Accountable owner

Design systems engineering foundations owner

Canonical source: src/lib/utils.ts

Input types or merge-engine changes require a repository-wide class precedence audit.
A breaking property, token, or behavior change requires design and engineering approval, a migration note, and a major release.
The design asset, implementation, documentation, accessibility contract, and regression coverage must ship in the same change.

Read the system construction standard

Visual specification

These measurements and semantic tokens define the supported visual contract. Local overrides should preserve the same hierarchy and interaction cues.

Output

One whitespace-delimited class string

Rules

Put default classes first and the consumer className last when overrides are allowed.
Do not use arbitrary class conflicts as a substitute for explicit variants.
Focus and semantic-state utilities are part of the component contract.

Token dependencies

Consumer-defined semantic tokens

cn preserves token-backed Tailwind utilities while resolving conflicts.

States and behavior

A component is not complete until its passive, interactive, disabled, and exceptional states remain understandable in both themes.

not applicable

Trigger: Called during class composition.
Visual response: No visual output by itself.
Behavior: Returns the Tailwind-merged string.

Accessibility contract

Semantics, accessible naming, keyboard behavior, focus and announcements are implementation requirements, not optional documentation.

Semantics: No DOM semantics; output affects the consuming element only.
Accessible name: Not applicable.

Do not merge away required focus-visible, disabled, hidden, or contrast styles.
The consuming component remains responsible for semantics.

Keyboard behavior

No component-specific keyboard behavior. Native document behavior remains unchanged.

Implementation

Use the public package API and preserve the controlled-state, native-attribute, and ref contracts described below.

tsx

import { cn } from '@ai-created/ui';

Server Component compatible

Accepts only string, false, null, and undefined fragments.
Falsy values are filtered before tailwind-merge runs.
Later conflicting utilities take precedence according to tailwind-merge.

tsx

const classes = cn("rounded-md border", active && "border-accent", className);

Public API

These props and helpers are compatibility contracts. Changes require migration guidance and release notes.

Prop	Type	Default	Contract
...inputs	Array<string \| false \| null \| undefined>	required	Class fragments in precedence order.

Usage guidance

These rules keep the component recognizable across products without preventing deliberate composition.

Do

Use for conditional variants and intentional consumer overrides.
Keep class ordering predictable.

Do not

Do not pass untrusted class strings.
Do not hide component variant logic in long ad-hoc condition chains.

Testing contract

The component should be verified as rendered UI, an interaction model, an accessibility surface, and a theme-aware visual artifact.

Unit

Filters falsy values and preserves non-conflicting order.
Resolves representative Tailwind conflicts in favor of later utilities.

Interaction

Not applicable.

Accessibility

Verify merged output retains focus and disabled utilities.

Visual

Not applicable; visual coverage belongs to consumers.

Related specifications

button surface