Migrate to Tailwind v4 by robertknight · Pull Request #7291 · hypothesis/client

robertknight · 2025-09-11T11:36:16Z

This follows similar changes in h and the LMS, but with a few additional changes needed:

Update dependencies to support Tailwind v4
Convert SASS source files to CSS where possible, as it is easier to
use Tailwind v4 with CSS sources.
Consolidate the small number of styles defined in annotator and
sidebar .scss files into the root .css file.
Remove autoprefixer, as it is no longer needed
Replace Tailwind @apply with SASS mixin in highlights.scss

The highlights stylesheet is no longer compiled with Tailwind after updating to
v4 so @apply does nothing. Use a mixin with the same rules.
Convert all-initial utility into a class in the @components layer so that
it has lower precedence than utility classes applied to the same element.
Add an explicit margin to ModalDialog to avoid depending on a default
in the user agent style sheet. The Tailwind v4 reset overrides the UA
default and sets it to zero.

codecov · 2025-09-11T11:38:43Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.47%. Comparing base (513413c) to head (a63fe25).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #7291   +/-   ##
=======================================
  Coverage   99.47%   99.47%           
=======================================
  Files         271      271           
  Lines       10947    10947           
  Branches     2618     2618           
=======================================
  Hits        10889    10889           
  Misses         58       58

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

robertknight · 2025-09-11T13:08:30Z

This is now mostly working. I need to fix an issue with some CSS @property declarations seemingly being ignored, which causes missing borders in the toolbar at the edge of the sidebar.

robertknight · 2025-09-12T10:26:55Z

I need to fix an issue with some CSS @property declarations seemingly being ignored, which causes missing borders in the toolbar at the edge of the sidebar.

This is a known issue: https://stackoverflow.com/questions/78717295, tailwindlabs/tailwindcss#15005.

This test case produces blank output when the template is appended to the shadow DOM, but works if appended to the container's light DOM.

<html>
  <body>
    <template id="template">
      <style>
        @property --border-style {
          syntax: '*';
          inherits: false;
          initial-value: solid;
        }

        @property --border-color {
          syntax: '<color>';
          inherits: false;
          initial-value: red;
        }

        .foo {
          border-style: var(--border-style);
          border-color: var(--border-color);
          border-width: 1px;
          width: 20px;
          height: 20px;
        }
      </style>
      <div class="foo"></div>
    </template>
    <div id="container"></div>
    <script>
      const c = document.querySelector('#container');
      const shadow = c.attachShadow({ mode: 'open' });

      const t = document.querySelector('#template');
      shadow.append(t.content.cloneNode(true));
    </script>
  </body>
</html>

robertknight · 2025-09-12T10:31:34Z

The issues linked in the previous comment mention a workaround of attaching the @property declarations to base document. That will probably work, but will break if Hypothesis is loaded on a site which decides to define these properties in a different way. The whole point of us using Shadow DOM is to achieve isolation from the host page.

robertknight · 2025-09-12T11:49:00Z

src/styles/annotator/annotator.css

@@ -0,0 +1,113 @@
+/*


This is annotator.scss and content it imported via @use declarations but adjusted to work with Tailwind v4.

robertknight · 2025-09-12T11:49:27Z

src/styles/annotator/pdfjs-overrides.css

@@ -0,0 +1,12 @@
+/* Hide annotation layer while selecting text.


This is just pdfjs-overrides.scss renamed.

robertknight · 2025-09-12T11:49:56Z

src/styles/sidebar/sidebar.css

@@ -0,0 +1,91 @@
+@import 'tailwindcss' source(none);


This is sidebar.scss from before and modules that it imported via @use combined into one CSS file and adjusted to work with Tailwind v4.

robertknight · 2025-09-12T11:51:37Z

src/styles/sidebar/sidebar.css

+
+@utility container {
+  @apply m-auto px-[9px] max-w-[768px];
+}


This is a replacement for the container customizations that were defined in the JS Tailwind configuration previously.

robertknight · 2025-09-12T13:07:47Z

Some more general discussion of CSS names and shadow DOM here: https://developer.chrome.com/docs/css-ui/css-names#how_names_and_the_shadow_dom_should_work_together

Unlike other CSS names, CSS properties are not encapsulated by shadow DOM. Rather, they are the common means to pass parameters across different shadow trees. This makes the @property descriptor special: it's supposed to behave like a document-global type declaration that defines how a particular named property acts. Because properties have to match across shadow trees, mismatch of property declarations would create unexpected results, so @property declarations are specified to be flattened and resolved according to document order.

@property
As defined in the specification, any declaration of @property will be flattened to the document scope. Today however, in all browsers you can only declare @property in the document scope and @property declarations within shadow roots are ignored.
See issue 10541.

- Update dependencies to support Tailwind v4 - Convert SASS source files to CSS where possible, as it is easier to use Tailwind v4 with CSS sources. - Consolidate the small number of styles defined in annotator and sidebar .scss files into the root .css file. - Remove autoprefixer, as it is no longer needed - Replace Tailwind @apply with SASS mixin in highlights.scss The highlights stylesheet is no longer compiled with Tailwind after updating to v4 so `@apply` does nothing. Use a mixin with the same rules. - Convert `all-initial` utility into a class in the `@components` layer so that it has lower precedence than utility classes applied to the same element. - Add an explicit margin to ModalDialog to avoid depending on a default in the user agent style sheet. The Tailwind v4 reset overrides the UA default and sets it to zero.

robertknight · 2025-09-15T10:00:42Z

For future reference, the issue with @property and shadow DOM was solved in #7293.

robertknight · 2025-09-15T10:02:00Z

src/annotator/components/ModalDialog.tsx

    <dialog
      ref={dialogRef}
-      className="relative w-full h-full backdrop:bg-black/50"
+      className="relative m-5 w-full h-full backdrop:bg-black/50"


This equals 20 pixels in my browser, compared to 19 for the user agent default before.

robertknight · 2025-09-15T10:04:21Z

tailwind.config.js

-        screens: {
-          lg: '768px',
-        },
-      },


Move to a utility defined in CSS. I have simplified the definition there as well.

robertknight · 2025-09-15T10:04:55Z

tailwind.config.js

-        '.all-initial': {
-          all: 'initial',
-        },
-      });


Move to a class in CSS.

robertknight force-pushed the tailwind-v4 branch from 7431276 to 22d8397 Compare September 11, 2025 13:05

robertknight mentioned this pull request Sep 11, 2025

Remove support for autoprefixer and Tailwind v3 hypothesis/frontend-build#814

Merged

robertknight commented Sep 12, 2025

View reviewed changes

robertknight force-pushed the tailwind-v4 branch 2 times, most recently from 817e7f8 to a45adec Compare September 15, 2025 09:27

robertknight force-pushed the tailwind-v4 branch from a45adec to a63fe25 Compare September 15, 2025 09:57

robertknight marked this pull request as ready for review September 15, 2025 10:01

robertknight commented Sep 15, 2025

View reviewed changes

tailwind.config.js

'.all-initial': {

all: 'initial',

},

});

Copy link

Contributor Author

robertknight Sep 15, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Move to a class in CSS.

robertknight requested a review from acelaya September 15, 2025 10:05

acelaya approved these changes Sep 15, 2025

View reviewed changes

robertknight merged commit 6e86750 into main Sep 15, 2025
4 checks passed

robertknight deleted the tailwind-v4 branch September 15, 2025 10:15

This was referenced Sep 15, 2025

Migrate to Tailwind v4 hypothesis/frontend-shared#2075

Closed

Sidebar occasionally appears on left side of screen #7307

Open

		@@ -0,0 +1,12 @@
		/* Hide annotation layer while selecting text.

Conversation

robertknight commented Sep 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Sep 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

robertknight commented Sep 11, 2025

Uh oh!

robertknight commented Sep 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

robertknight commented Sep 12, 2025

Uh oh!

robertknight Sep 12, 2025

Choose a reason for hiding this comment

Uh oh!

robertknight Sep 12, 2025

Choose a reason for hiding this comment

Uh oh!

robertknight Sep 12, 2025

Choose a reason for hiding this comment

Uh oh!

robertknight Sep 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

robertknight commented Sep 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

robertknight commented Sep 15, 2025

Uh oh!

robertknight Sep 15, 2025

Choose a reason for hiding this comment

Uh oh!

robertknight Sep 15, 2025

Choose a reason for hiding this comment

Uh oh!

robertknight Sep 15, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

robertknight commented Sep 11, 2025 •

edited

Loading

codecov bot commented Sep 11, 2025 •

edited

Loading

robertknight commented Sep 12, 2025 •

edited

Loading

robertknight Sep 12, 2025 •

edited

Loading

robertknight commented Sep 12, 2025 •

edited

Loading