createCssUtility() — tailwindcss Function Reference

Source Code

packages/tailwindcss/src/utilities.ts lines 5941–6301

export function createCssUtility(node: AtRule) {
  let name = node.params

  // Functional utilities. E.g.: `tab-size-*`
  if (isValidFunctionalUtilityName(name)) {
    // API:
    //
    // - `--value('literal')`         resolves a literal named value
    // - `--value(number)`            resolves a bare value of type number
    // - `--value([number])`          resolves an arbitrary value of type number
    // - `--value(--color)`           resolves a theme value in the `color` namespace
    // - `--value(number, [number])`  resolves a bare value of type number or an
    //                                arbitrary value of type number in order.
    //
    // Rules:
    //
    // - If `--value(…)` does not resolve to a valid value, the declaration is
    //   removed.
    // - If a `--value(ratio)` resolves, the `--modifier(…)` cannot be used.
    // - If a candidate looks like `foo-2/3`, then the `--value(ratio)` should
    //   be used OR the `--value(…)` and `--modifier(…)` must be used. But not
    //   both.
    // - All parts of the candidate must resolve, otherwise it's not a valid
    //   utility. E.g.:`
    //   ```
    //   @utility foo-* {
    //     test: --value(number)
    //   }
    //   ```
    //   If you then use `foo-1/2`, this is invalid, because the modifier is not used.

    return (designSystem: DesignSystem) => {
      let storage = {
        '--value': {
          usedSpacingInteger: false,
          usedSpacingNumber: false,
          themeKeys: new Set<`--${string}`>(),
          literals: new Set<string>(),
        },
        '--modifier': {
          usedSpacingInteger: false,
          usedSpacingNumber: false,
          themeKeys: new Set<`--${string}`>(),
          literals: new Set<string>(),
        },
      }

      // Pre-process the AST to make it easier to work with.
      //
      // - Normalize theme values used in `--value(…)` and `--modifier(…)`
      //   functions.
      // - Track information for suggestions
      walk(node.nodes, (child) => {
        if (child.kind !== 'declaration') return
        if (!child.value) return
        if (!child.value.includes('--value(') && !child.value.includes('--modifier(')) return

        let declarationValueAst = ValueParser.parse(child.value)

        // Required manipulations:
        //
        // - `--value(--spacing)`                 -> `--value(--spacing-*)`
        // - `--value(--spacing- *)`              -> `--value(--spacing-*)`
        // - `--value(--text- * --line-height)`   -> `--value(--text-*--line-height)`
        // - `--value(--text --line-height)`      -> `--value(--text-*--line-height)`
        // - `--value(--text-\\* --line-height)`  -> `--value(--text-*--line-height)`
        // - `--value([ *])`                      -> `--value([*])`
        //
        // Once Prettier / Biome handle these better (e.g.: not crashing without
        // `\\*` or not inserting whitespace) then most of these can go away.
        walk(declarationValueAst, (fn) => {
          if (fn.kind !== 'function') return

          // Track usage of `--spacing(…)`
          if (
            fn.value === '--spacing' &&
            // Quick bail check if we already know that `--value` and `--modifier` are
            // using the full `--spacing` theme scale.
            !(storage['--modifier'].usedSpacingNumber && storage['--value'].usedSpacingNumber)
          ) {
            walk(fn.nodes, (node) => {