tailwind-impl-plugins-custom

name	tailwind-impl-plugins-custom
description	Use when authoring a custom Tailwind CSS plugin to add utilities, components, base styles, or variants, regardless of whether the host project runs Tailwind v3 (JS plugin in tailwind-config-js) or v4 (JS plugin loaded via @plugin or the CSS-native @utility directive). Prevents the four most common plugin-authorship traps: registering utilities through addBase (where variants do not apply), forgetting the second-argument default theme so theme('tabSize') returns undefined, omitting the values map on matchUtilities causing zero classes to compile, and importing tailwindcss/plugin in a v4-only project where the package no longer exists at runtime. Covers the full plugin() signature (addUtilities, addComponents, addBase, addVariant, matchUtilities, matchComponents, matchVariant, theme, config, corePlugins, e), plugin-withOptions for parameterised plugins, shipping default theme values through the configFn, the v4-native @utility name-* with --value() and --modifier(), the v4 @custom-variant directive, the v4 @plugin loader for legacy JS plugins, theme path syntax (theme('colors.red.500'), theme('spacing.4')), variants arrays on addUtilities under v3, and packaging a plugin as a publishable npm module. Keywords: tailwind plugin, custom plugin, plugin function, addUtilities, addComponents, addBase, addVariant, matchUtilities, matchComponents, matchVariant, plugin.withOptions, plugin-withOptions, theme function, config function, corePlugins, e helper, tabSize matchUtilities, hocus variant, peer variant plugin, @utility v4, @utility name-*, --value(), --modifier(), --alpha(), --spacing(), @custom-variant, @plugin tailwind v4, load legacy plugin v4, theme('colors.red.500'), theme('spacing.4'), npm package tailwind plugin, publish tailwind plugin, my plugin classes not working, matchUtilities not generating, how do I add a custom utility, how do I write a tailwind plugin, where do plugin classes go, why doesn't my variant apply, tailwind-config-js plugins array.
license	MIT
compatibility	Designed for Claude Code. Requires Tailwind CSS v3.4 or v4.0+.
metadata	{"author":"OpenAEC-Foundation","version":"1.0"}

Tailwind CSS Custom Plugins

Tailwind exposes three authoring paths for custom styles : the JS plugin() API (works in v3 and v4 for back-compat), v4's CSS-native @utility directive, and v4's @custom-variant directive. Pick by constraint, not by taste.

Companion skills :

• tailwind-impl-config-v4 : @utility, @custom-variant, @plugin directives in depth
• tailwind-impl-config-v3 : tailwind.config.js surface
• tailwind-core-v3-vs-v4 : version-wide API differences
• tailwind-syntax-functional-utilities : v4 --value() / --modifier()

Decision : Which Authoring Path

Constraint	Path
Project on v3	JS plugin() only
Project on v4 only, no v3 back-compat	CSS @utility + @custom-variant
Project on v4 with @plugin loading legacy plugins	JS plugin() via @plugin "./my-plugin.js"
Plugin must support BOTH v3 and v4	JS plugin() (works in both)
Plugin needs runtime config from caller	plugin.withOptions(fn, configFn)
Plugin only adds tokens, no utilities	@theme { ... } directly, no plugin

Quick Reference : JS plugin() Signature

const plugin = require('tailwindcss/plugin')

module.exports = plugin(function ({
  addUtilities,
  addComponents,
  addBase,
  addVariant,
  matchUtilities,
  matchComponents,
  matchVariant,
  theme,
  config,
  corePlugins,
  e,
}) {
  // body
})