Skip to content

Conversation

RobinMalfait
Copy link
Member

@RobinMalfait RobinMalfait commented Aug 28, 2025

This PR migrates aria theme keys when migrating from Tailwind CSS v3 to v4.

While working on improving some of the error messages to get more insights into why migrating the JS file changed (#18808), I ran into an issue where I couldn't think of a good comment to why aria theme keys were not being migrated. (Internally we have aria "blocked").

So instead of figuring out a good error message..., I just went ahead and added the migration for aria theme keys.

Let's imagine you have the following Tailwind CSS v3 configuration:

export default {
  content: ['./src/**/*.html'],
  theme: {
    extend: {
      aria: {
        // Built-in (not really, but visible because of intellisense)
        busy: 'busy="true"',

        // Automatically handled by bare values
        foo: 'foo="true"',
    //  ^^^   ^^^            ← same names

        // Not automatically handled by bare values because names differ
        bar: 'baz="true"',
    //  ^^^   ^^^            ← different names

        // Completely custom
        asc: 'sort="ascending"',
        desc: 'sort="descending"',
      },
    },
  },
}

Then we would generate the following Tailwind CSS v4 CSS:

@custom-variant aria-bar (&[aria-baz="true"]);
@custom-variant aria-asc (&[aria-sort="ascending"]);
@custom-variant aria-desc (&[aria-sort="descending"]);

Notice how we didn't generate a custom variant for aria-busy or aria-foo because those are automatically handled by bare values.

We could also emit a comment near the CSS to warn about the fact that @custom-variant will always be sorted after any other built-in variants.

This could result in slightly different behavior, or different order of classes when using prettier-plugin-tailwindcss.

I don't know how important this is, because before this PR we would just use @config './tailwind.config.js';.
Edit: when using the @config we override aria and extend it, which means that it would be in the expected order 🤔

We were handling special cases (keyframes, container) _after_ we handled
the normal theme keys. When handling the normal theme keys we skipped
the special keys which means that you have to keep the list in sync.

Now we will handle special cases first.

Another refactor here is that we will push data to an intermediate
variable before emitting the `@theme {…}` wrapper. This will allow us to
only emit CSS when needed.

We were explicitly returning `null` in some cases, but we can also just
return the empty string when there is no CSS to get the same effect.
But we will make sure that we skip the ones that would be handled
automatically by bare values. E.g.: `aria-foo:flex` will generate
`[aria-foo="true"]`.
@RobinMalfait RobinMalfait marked this pull request as ready for review August 28, 2025 10:33
@RobinMalfait RobinMalfait requested a review from a team as a code owner August 28, 2025 10:33
This was referenced Aug 28, 2025
Co-Authored-By: Jordan Pittman <thecrypticace@gmail.com>
@RobinMalfait RobinMalfait force-pushed the feat/upgrade-aria-theme branch from 950eac2 to ebfee41 Compare August 28, 2025 14:36
@RobinMalfait RobinMalfait merged commit 9e498a3 into main Aug 28, 2025
7 checks passed
@RobinMalfait RobinMalfait deleted the feat/upgrade-aria-theme branch August 28, 2025 14:40
RobinMalfait added a commit that referenced this pull request Aug 28, 2025
This PR is similar to and a follow up of #18815, but this time to
migrate the `data` theme keys.

Let's imagine you have the following Tailwind CSS v3 configuration:
```ts
export default {
  content: ['./src/**/*.html'],
  theme: {
    extend: {
      data: {
        // Automatically handled by bare values
        foo: 'foo',
    //  ^^^   ^^^       ← same names

        // Not automatically handled by bare values
        bar: 'baz',
    //  ^^^   ^^^       ← different names

        // Completely custom
        checked: 'ui~="checked"',
      },
    },
  },
}
```

Then we would generate the following Tailwind CSS v4 CSS:

```css
@custom-variant data-bar (&[data-baz]);
@custom-variant data-checked (&[data-ui~="checked"]);
```

Notice how we didn't generate a custom variant for `data-foo` because
those are automatically handled by bare values.
RobinMalfait added a commit that referenced this pull request Aug 28, 2025
This PR is a follow up of #18815 and #18816, but this time let's migrate
the `supports` theme keys.

Let's imagine you have the following Tailwind CSS v3 configuration:
```ts
export default {
  content: ['./src/**/*.html'],
  theme: {
    extend: {
      supports: {
        // Automatically handled by bare values (using CSS variable as the value)
        foo: 'foo: var(--foo)', // parentheses are optional
        bar: '(bar: var(--bar))',

        // Not automatically handled because names differ
        baz: 'qux: var(--foo)',
   //   ^^^   ^^^       ← different names

        // Custom
        grid: 'display: grid',
      },
    },
  },
}
```

Then we would generate the following Tailwind CSS v4 CSS:

```css
@custom-variant supports-baz {
  @supports (qux: var(--foo)) {
    @slot;
  }
}
@custom-variant supports-grid {
  @supports (display: grid) {
    @slot;
  }
}
```

Notice how we didn't generate a custom variant for `data-foo` or
`data-bar` because those are automatically handled by bare values.

I also went with the longer form of `@custom-variant`, we could use the
single selector approach, but that felt less clear to me.

```css
@custom-variant supports-baz (@supports (qux: var(--foo)));
@custom-variant supports-grid (@supports (display: grid));
```

---------

Co-authored-by: Jordan Pittman <thecrypticace@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants