Migrate to Tailwind v4

[robertknight]

We are currently using Tailwind v3.x. We will need to migrate to Tailwind v4. See Tailwind's migration guide.

V4 has significant changes to the generated CSS and configuration:

1. The generated CSS now targets a baseline of Safari 16.4 (March 2023), Chrome 111 (March 2023), and Firefox 128 (July 2024). This is newer than the three-year max age we have historically targeted, but we already had to change the client to Chrome 110, Safari 16.4 and FF 115 for compatibility with the newest PDF.js releases.
2. There have been some slight changes in using Tailwind as a PostCSS plugin
3. Configuration is now in CSS, although JS config can be loaded for backwards compatibility
4. The generated CSS now relies on cascade layers. If there is any other CSS on the page, we'll need to take account of the fact that CSS not in a layer takes precedence over CSS that is in a layer. This affects CSS resets on h for example.
5. There have been changes to various Tailwind style defaults that we'll need to adjust for. The most obvious one I've found so far is a change in how borders work.

We can simplify the initial migration by sticking with the JS config, then change to CSS-based config later.

Sub-tasks for initial migration:

• Support Tailwind v4 in @hypothesis/frontend-build (Support Tailwind v4 in CSS build frontend-build#813)
• Migrate pattern library application to Tailwind v4. Depending on the changes required in the component library itself, this may or may not require a major release of @hypothesis/frontend-shared. (Migrate pattern library site and tests to Tailwind v4 #2084)
• Migrate h to Tailwind v4 (Update to Tailwind v4 h#9877)
• Migrate via to Tailwind v4 (Migrate to Tailwind v4 via#1643)
• Migrate lms to Tailwind v4 (Migrate to Tailwind v4 lms#7211)
• Migrate the client to Tailwind v4 (Migrate to Tailwind v4 client#7291)

Follow-up tasks:

• Remove autoprefixer support from @hypothesis/frontend-build (Remove support for autoprefixer and Tailwind v3 frontend-build#814)
• Fix regression in client where sidebar sometimes appears on left side of window (Sidebar occasionally appears on left side of screen client#7307)
• Fix regression in browser extension where font size of annotation bodies is 12px instead of 13px (Fix sidebar font size in Chrome extension client#7311)
• Migrate from JS to CSS configuration (Add a CSS version of the Tailwind JS config #2090)
• Investigate why an issue appeared with the sidebar position after the TW4 migration, even though the root cause appeared to be something that occurred under TW3 as well (see Recalculate sidebar position when annotator styles load client#7309)

[robertknight]

A complication of using SASS together with Tailwind v4 is that SASS will process the @import "tailwindcss" directive itself and this prevents Tailwind from seeing it. Ways to avoid that are:

1. Remove SASS from the build. Easy to do in some cases, harder in others.
2. Use @import "tailwindcss/index.css". Using an import path ending with ".css" will prevent SASS from processing it. See manual.

Tailwind's docs recommend that you don't use SASS and Tailwind together and we are getting towards a point where we could stop using SASS in some apps. It will be more difficult in h and the client.

[robertknight]

The most obvious style change after updating h to TW4 locally was that the border color on many components became darker. This is due to a change in the default border in TW4. The recommended fix is either to set an explicit border style as needed, or add styles to the base layer to match TW3.

[robertknight]

For finding class names which need to be updated, I used this prompt in Claude Code:

Read the Tailwind v4 migration guide at https://tailwindcss.com/docs/upgrade-guide. I want to find occurrences in this project's .tsx files of any of the names of any utilities which have been removed or renamed.

In h: Nothing found

In frontend-shared:

  Found Issues:

  Renamed Shadow Utilities:

  - src/components/feedback/Callout.tsx:72 - shadow (renamed to shadow-sm in v4)
  - src/components/feedback/Popover.tsx:420 - shadow (renamed to shadow-sm in v4)
  - src/components/layout/Card.tsx:47 - shadow (renamed to shadow-sm in v4)

  Renamed Rounded Utilities:

  - Multiple files use rounded which is renamed to rounded-sm in v4:
    - src/components/data/DataTable.tsx:371
    - src/components/input/Input.tsx:17
    - src/components/input/OptionButton.tsx:33
    - src/components/input/IconButton.tsx:54
    - src/components/feedback/Callout.tsx:71
    - src/components/feedback/Popover.tsx:420
    - And several other files in the pattern library

  Removed Utilities:

  - src/components/input/Select.tsx:148 - outline-none (removed in v4, should be
  outline-hidden)

  Summary:

  You have several utilities that need updating for Tailwind v4:
  - shadow → shadow-sm (3 files)
  - rounded → rounded-sm (19+ occurrences)
  - outline-none → outline-hidden (1 file)

  The opacity utilities, flex utilities, and decoration utilities that were removed are
  not used in your codebase.

Prompt for other issues:

Can you look for any other issues highlighted in the migration guide which apply to this codebase?

  Major Migration Issues Found:

  1. Sass Compatibility Issue ⚠️

  - File: /Users/robert/hypothesis/frontend-shared/styles/test.scss
  - Issue: Uses @use directives with Tailwind (@use 'tailwindcss/utilities')
  - Problem: Tailwind v4 no longer supports Sass/SCSS preprocessors
  - Impact: This file will break in v4

  2. Configuration Structure ⚠️

  - File: /Users/robert/hypothesis/frontend-shared/tailwind.config.js
  - Current: Uses JavaScript config with presets, theme extensions
  - V4 Change: JavaScript configs are no longer auto-detected, theme access changes to CSS variables
  - Impact: Requires migration to new config approach

  3. Space Utilities ✅ (Found but manageable)

  - Found in 12 files including:
    - src/components/layout/CardContent.tsx
    - src/components/layout/CardActions.tsx
    - src/components/feedback/ToastMessages.tsx
  - Issue: Space-between selector implementation has changed
  - Impact: May need verification that spacing still works correctly

  Issues NOT Found (Good News):

  - ✅ No @tailwind directives in CSS files
  - ✅ No resolveConfig() usage
  - ✅ No gradient variants (from-*-to-*)
  - ✅ No arbitrary value syntax that might break

  Recommendations:

  1. Priority 1: Address the Sass file - you'll need to convert styles/test.scss to regular CSS or find an alternative approach
  2. Priority 2: Plan config migration - the current tailwind.config.js will need updates
  3. Priority 3: Test space utilities after migration to ensure they still work as expected

  The Tailwind team provides an automated upgrade tool (npx @tailwindcss/upgrade) that should help with most of these issues.

[robertknight]

Investigate why an issue appeared with the sidebar position after the TW4 migration, even though the root cause appeared to be something that occurred under TW3 as well

I confirmed that the issue did occur under Tailwind v3 if loading of annotator.css is sufficiently delayed, however we didn't see this happen in practice. My current hypothesis is that the problem started happening because crossorigin="anonymous" was added to the <link> as part of a shadow DOM workaround. This will result in CORS preflight requests being made before the stylesheet is actually fetched, adding latency.

One solution would be to extract the @property entries from the CSS at build time and include them in the JS bundle.

[robertknight]

Closing as done. Will look into optimizing annotator.css load as a follow-up.