Agent skill

creating-custom-utilities

Create custom utilities with @utility directive supporting static utilities, functional utilities with values, theme-based utilities, and multi-value utilities. Use when extending Tailwind with custom CSS properties or patterns.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/creating-custom-utilities

SKILL.md

Creating Custom Utilities

Purpose

The @utility directive creates custom utility classes with full variant support (hover, focus, responsive, etc.). This is the proper way to extend Tailwind v4 with custom utilities.

Static Utilities

Define utilities with fixed values:

css
@utility content-auto {
  content-visibility: auto;
}

@utility content-hidden {
  content-visibility: hidden;
}

@utility text-balance {
  text-wrap: balance;
}

@utility text-pretty {
  text-wrap: pretty;
}

@utility bg-glass {
  background: rgba(255, 255, 255, 0.1);
  backdrop-filter: blur(10px);
  border: 1px solid rgba(255, 255, 255, 0.2);
}

Usage:

html
<div class="content-auto hover:content-hidden"></div>
<p class="text-balance lg:text-pretty"></p>
<div class="bg-glass"></div>

Static utilities work with all variants automatically.

Functional Utilities with Integer Values

Create utilities that accept numeric values:

css
@utility mt-* {
  margin-top: calc(0.25rem * --value(integer));
}

@utility truncate-* {
  display: -webkit-box;
  -webkit-box-orient: vertical;
  -webkit-line-clamp: --value(integer);
  overflow: hidden;
}

@utility text-stroke-* {
  -webkit-text-stroke-width: --value(integer) px;
}

Usage:

html
<div class="mt-5"></div>
<p class="truncate-3"></p>
<h1 class="text-stroke-2"></h1>

The --value(integer) function extracts the numeric value from the class name.

Theme-Based Utilities

Reference theme variables using --value(--namespace- *):

css
@theme {
  --tab-size-2: 2;
  --tab-size-4: 4;
  --tab-size-8: 8;
  --tab-size-github: 8;
}

@utility tab-* {
  tab-size: --value(--tab-size- *);
}

Usage:

html
<pre class="tab-2"><code>...</code></pre>
<pre class="tab-github"><code>...</code></pre>

Another example:

css
@theme {
  --aspect-square: 1 / 1;
  --aspect-video: 16 / 9;
  --aspect-portrait: 3 / 4;
}

@utility aspect-* {
  aspect-ratio: --value(--aspect- *);
}

Usage:

html
<img class="aspect-square" />
<video class="aspect-video" />
<div class="aspect-portrait"></div>

Multi-Value Utilities

Create utilities that accept multiple value types:

css
@utility text-stroke-* {
  -webkit-text-stroke-width: --value(integer) px;
  -webkit-text-stroke-color: --value(--color- *);
}

Usage:

html
<h1 class="text-stroke-2-blue-500">Stroked text</h1>
<h1 class="text-stroke-1-primary">Stroked with theme color</h1>

Another example:

css
@theme {
  --blur-sm: 4px;
  --blur-md: 8px;
  --blur-lg: 16px;
}

@utility backdrop-blur-* {
  backdrop-filter: blur(--value(--blur- *));
  backdrop-filter: blur(--value(integer) px);
}

Usage:

html
<div class="backdrop-blur-sm"></div>
<div class="backdrop-blur-12"></div>

Arbitrary Values Support

Support both theme values and arbitrary values:

css
@utility tab-* {
  tab-size: --value(integer);
  tab-size: --value([integer]);
}

Usage:

html
<pre class="tab-4">Theme value</pre>
<pre class="tab-[12]">Arbitrary value</pre>

The --value([integer]) function enables arbitrary value syntax with square brackets.

Complex Utility Examples

Gradient Text

css
@utility text-gradient-* {
  background: linear-gradient(to right, --value(--color- *), --value(--color- *, 2));
  -webkit-background-clip: text;
  -webkit-text-fill-color: transparent;
  background-clip: text;
}

Usage:

html
<h1 class="text-gradient-blue-500-purple-600">Gradient text</h1>

Grid Template Columns

css
@utility grid-cols-* {
  grid-template-columns: repeat(--value(integer), minmax(0, 1fr));
}

Usage:

html
<div class="grid grid-cols-3"></div>
<div class="grid grid-cols-5"></div>

Custom Line Clamp

css
@utility line-clamp-* {
  display: -webkit-box;
  -webkit-box-orient: vertical;
  -webkit-line-clamp: --value(integer);
  overflow: hidden;
}

@utility line-clamp-none {
  display: block;
  -webkit-box-orient: horizontal;
  -webkit-line-clamp: none;
  overflow: visible;
}

Usage:

html
<p class="line-clamp-2 lg:line-clamp-3 xl:line-clamp-none"></p>

Custom Spacing Scale

css
@theme {
  --spacing-base: 0.25rem;
}

@utility gap-* {
  gap: calc(var(--spacing-base) * --value(integer));
}

@utility space-x-* > * + * {
  margin-left: calc(var(--spacing-base) * --value(integer));
}

Usage:

html
<div class="flex gap-6"></div>
<div class="flex space-x-4"></div>

Glassmorphism Utilities

css
@utility glass-* {
  background: rgba(255, 255, 255, --value(integer) / 100);
  backdrop-filter: blur(10px);
  border: 1px solid rgba(255, 255, 255, 0.2);
}

@utility glass-dark-* {
  background: rgba(0, 0, 0, --value(integer) / 100);
  backdrop-filter: blur(10px);
  border: 1px solid rgba(255, 255, 255, 0.1);
}

Usage:

html
<div class="glass-10"></div>
<div class="glass-dark-20"></div>

Utilities with Pseudo-Elements

css
@utility before-content-* {
  &::before {
    content: --value([string]);
    display: block;
  }
}

@utility after-content-* {
  &::after {
    content: --value([string]);
    display: block;
  }
}

Usage:

html
<div class="before:content-['★']">Star before</div>
<div class="after:content-['→']">Arrow after</div>

Complete Custom Utilities Library

css
@import 'tailwindcss';

@utility content-auto {
  content-visibility: auto;
}

@utility content-hidden {
  content-visibility: hidden;
}

@utility text-balance {
  text-wrap: balance;
}

@utility text-pretty {
  text-wrap: pretty;
}

@utility truncate-* {
  display: -webkit-box;
  -webkit-box-orient: vertical;
  -webkit-line-clamp: --value(integer);
  overflow: hidden;
}

@utility bg-glass {
  background: rgba(255, 255, 255, 0.1);
  backdrop-filter: blur(10px);
  border: 1px solid rgba(255, 255, 255, 0.2);
}

@utility text-stroke-* {
  -webkit-text-stroke-width: --value(integer) px;
  -webkit-text-stroke-color: --value(--color- *);
}

@theme {
  --aspect-square: 1 / 1;
  --aspect-video: 16 / 9;
  --aspect-portrait: 3 / 4;
  --aspect-ultrawide: 21 / 9;
}

@utility aspect-* {
  aspect-ratio: --value(--aspect- *);
  aspect-ratio: --value([number]);
}

@theme {
  --tab-size-2: 2;
  --tab-size-4: 4;
  --tab-size-8: 8;
}

@utility tab-* {
  tab-size: --value(--tab-size- *);
  tab-size: --value(integer);
  tab-size: --value([integer]);
}

Why Use @utility Instead of @layer utilities

Don't do this:

css
@layer utilities {
  .my-button {
    padding: 1rem;
  }
}

Won't work with variants like hover:my-button.

Do this:

css
@utility my-button {
  padding: 1rem;
}

Works with all variants: hover:my-button, focus:my-button, lg:my-button.

Best Practices

  1. Use @utility for variant support - Always use @utility instead of @layer utilities
  2. Support arbitrary values - Include --value([type]) for flexibility
  3. Use theme variables - Reference theme with --value(--namespace- *)
  4. Name utilities semantically - Use clear, descriptive names
  5. Group related utilities - Keep similar utilities together

Common Use Cases

  • Custom CSS properties not in Tailwind
  • Browser-specific prefixed properties
  • Complex multi-property patterns
  • Domain-specific utilities (e.g., print styles)
  • Experimental CSS features

See Also

  • RESEARCH.md section: "Advanced Patterns" → "Custom Utilities with @utility"

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results