[Discussion] Costs / Benefits of migrating to Tailwind

[tristan-orourke]

I know there's been some interest in migrating from using Hydrogen as our design system to using Tailwind. I'm opening this up as a place to openly and frankly evaluate the potential reasons for moving to Tailwind, the reasons to keep using Hydrogen, and the amount of work it would take to switch.

[tristan-orourke]

Starting it off...

Benefits of Hydrogen:

1. data attribute styling is verbose and explicit - its generally very clear which CSS attribute(s) a data attribute modifies
2. we can work directly with the creator if we have questions or suggestions
3. it's already there, already working!

Benefits of Tailwind

1. class styling is concise, requiring less reading and writing than data attributes and resulting in smaller files
2. lack of explicitness may be mitigated by Tailwind styles trying to be intuitive and easy to learn
3. wider use means existence of third-party tools and integrations (lets get some examples)
4. wider use means may be easier to on-board new devs in the future

Important features of Hydrogen

These are features of Hydrogen we already use, and I'd want them to be similarly easy to do in Tailwind before considering switching:

1. Support for themes and dark mode. We can define our colour scheme once in a design tokens file and easily switch to a theme or dark mode by adding a styling attribute to the root div.
2. Support for states: we can style an element to look different depending on states like "active", "disabled", or "required".
3. Targeting children elements: Hydrogen can tell all children of an element to look a certain way, instead of having to repeat the class on each of them (see group-hover and group-focus). (This one could be less important - I'm not sure how extensively we use this feature.)

Open Questions

I don't know the answers to these questions, but if we did they might sway us one way or the other:

1. Is there an appreciable difference in compile time between Hydrogen and Tailwind? Particularly in dev and/or watch modes
2. Is there an appreciable difference in the size of our compiled files? (JS and/or CSS)
3. How hard would it be to make the switch invisible to users? I mean, how easy to configure Tailwind to use our existing colour scheme, typography sizes, spacing, etc?

Amount of Work

I don't know the answers to these questions either, and they're some of the most important. For reference, @esizer was investigating what it would be like to switch, and has an in-progress branch at https://github.com/GCTC-NTGC/gc-digital-talent/tree/tailwind-spike.

1. How much dev time would it take to complete a migration?
2. How much dev time would it take to answer comparative questions about performance and file size?
3. Could the migration be broken up in a way that would keep PRs and reviews manageable?
4. How much time/effort would it take for devs to get used to using Tailwind?

[esizer]

Tailwind Updates

Something exciting is, tailwind is working on v4 with many nice improvements and aiming to be stable this summer (seems optimistic but would be nice).

• They are adding css configuration so we would not need a separate config file and just write css.
• A new engine is being developed, off-loading a lot of the work to rust touting 10x speed improvements
• Vite plugin that uses their graph rather than their own so we don't need to tell it where to look for files

Tools for tailwindcss

The nice thing is, tailwind is just class names so some of these tools are not tailwind specific but just make working with class names in component libraries easier.

Editor/Linting

They have a prettier plugin (which also happens to work with other mentions here such as clsx and cva).

As well, there is an intellisense plugin that provides a lot of amazing features like autocomplete and hover previews of values.

Utilities

• tailwind-merge - Merges tailwind classes resolving conflicts in an intelligent manner giving priority to the last item
• clsx - Conditional application of classe

I use these in combination to create a utility function to make working with classes much easier. This is a very common approach when developing with tailwind.

Examples

import { ClassValue, clsx } from "clsx";
import { twMerge } from "tailwind-merge";

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

const BaseComponent = ({ className, isActive }) => (
   <div 
       className={
         cn('bg-blue p-3 rounded', // Base styles
         { 'shadow': isActive },  // clsx will only apply this class if `isActive = true`
         className // Allow overriding which will be merged with tw-merge
       )} 
     /> 
)

const ExtendedComponent = () => (
  <div className="bg-red" isActive />
)

// Output
<div className="bg-red p-3 rounded shadow" />

Variants

There are two options for handling variant components. However, neither is at v1 but, we could use clsx to do something very similar, these tools just make it easier by doing a lot of the heavy lifting and also providing props.

• Class Variance Authority
• Tailwind variants

Important Features

Theme support

Tailwind has first party support for dark mode and it is very well documented. As far as themes go, while there is no first part support for it, it is trivial to implement with css variables (which will be even easier in v4 when they move to css first config).

// Define your css vars
// NOTE: In v4 this will be the config so no need to duplicate in the standalone config file
@layer base {
  :root {
    --color-background: 245 248 253;
    --color-primary: 155 71 255;
  }

  :root .dark {
    --color-background: 47 49 61;
  }

  :root .iap {
    --color-primary: 192 30 90;
  }
}

// Use them in the config
export default {
  extend: {
        colors: {
          primary: `rgb(var(--color-primary) / <alpha-value>)`,
          background: `rgb(var(--color-background) / <alpha-value>)`,
      },
  }
}

States

They have full support for pseudo classes/elements (even list markers! 😁)

<input className="invalid:border-error disabled:border-gray focus:border-blue" />

<ul clasName="marker:text-primary"> <!-- our markers are now our primary colour -->

Child elements

Personally, I prefer styling children directly. It makes it more explicit and puts the styles closer to where they are being applied. The main drawback of this is repeating the same classes but this is mainly mitigated via components.

However, you can style children but also much, much more. Also, tailwind treats anything in brackets as plain css so you can write any selector you want (not that I encourage it 😅 )

// This abomination 
<div class="[&>div[data-state="some-state"]:focus-visible:invalid]:bg-primary]" />

/* results in */
& > div[data-state="some-state"]:focus-visible:invalid {
  background-color: var(--bg-primary);
}

Open Questions

1. Compile time: I don't think this is much of a concern but tailwind is very fast and only getting faster in v4 when they offload more work to rust
2. File size: I think this is where we will see the most improvements, our current file size is quite large. We compress it but it could be much smaller. Maybe not the actual css (though that should get smaller as well) but our js bundles that embed the selectors as plain text and some are quite large
3. No diff change: This would be the toughest part. Not necessarily the config but likely the review to have no visual diff 😢

Migration

I don't think the effort the actual swap out the code would be that difficult. We could start by doing the packages/ui/* and double load css for a release cycle to break up the work. However, I wouldn't think we should keep this for long and try and do the full cut over as soon as possible so we don't have duplicate css.

The hardest part, as mentioned previously, the reviewing would not be fun and hopefully chromatic could save us a lot of headaches.

[JoshBeveridge]

Syntax

Hydrogen is more verbose, Tailwind is more concise. Hydrogen uses custom attributes, Tailwind uses classes. Hydrogen prioritizes using native CSS syntax where possible, while Tailwind has what is essentially its own abstracted language. Historically, as I understand it, our direction for nomenclature elsewhere in our code has been consistency and clarity over conciseness and convenience. Tailwind's approach arguably goes against this, as it requires us to learn its pseudo-language at the same time as abstracting class names away from being immediately obvious unless you're really familiar with Tailwind already.

Tooling and utilities

This one is a no-brainer in favor of Tailwind, however it does also warrant discussion of the consequences of piling plugins onto Tailwind and what that actually looks like support-wise in practice. Hydrogen has a single point of failure right now, which is how quickly I can respond to a need or bug, whereas Tailwind + Merge + CSLX + PostCSS + the Vite plugin + whatever else we add on creates multiple points of failure and opportunities for bugs, delayed deployment of dependencies, etc.

Theme support

As far as themes go, while there is no first part support for it, it is trivial to implement with css variables (which will be even easier in v4 when they move to css first config).

This statement misunderstands the depth in how Hydrogen implements themes. If we use the IAP as an example, there are instances where our default primary value is used in GC Talent, but in the IAP, we actually use secondary. This means there needs to be two variables for that instance - one where GC Talent's primary swaps to IAP's primary, and another where GC Talent's primary swaps to IAP's secondary. Figma has this same limitation, and it's required us to have an unwieldy number of "unique" variables for color in particular.

Hydrogen on the other hand, let's you use your theme key as an override (this also applies to dark mode, and I'm not sure if Tailwind has something similar), where you can do something like data-h2-background="base(primary) iap(secondary)" (the example above) or data-h2-background="base:all(primary.light)" (which would force the light variant to persist across light and dark modes).

This gets a lot more complicated when we get into custom hover/focus states per theme, or hiding/showing elements, etc. We need configurations for at minimum two themes, with both light and dark that behave slightly differently between them.

Child elements

This plays into both preference and practical file size and edit-ability. If you have to style the same <li> 12 times with the same 5-6 Tailwind classes, it becomes really easy to miss things when making changes, it's no longer clear whether those 12 things are related stylistically, and the output ends up being larger, because you've now got the same 5-6 classes 12 times, as opposed to 5-6 attributes on the parent. Consolidating the styling is generally the recommendation across any CSS framework or approach, so should we move forward with Tailwind, I imagine those complex classes, while difficult to read and write, will still offer the best output.

Open questions

• Is there an appreciable difference in compile time between Hydrogen and Tailwind? Particularly in dev and/or watch modes
  At this point we're talking milliseconds
• Is there an appreciable difference in the size of our compiled files? (JS and/or CSS)
  Definitely, given the abbreviated classes and single attribute. That said, if our CSS file size really is a problem right now, this is the first time I'm hearing about it, and it's not impossible to configure Hydrogen to be less verbose (i.e. abbreviated configuration keys for media, colors, etc.), alongside internal changes I could make to allow for shorter attribute and variable names, and the removal of unused variables entirely
• How hard would it be to make the switch invisible to users? I mean, how easy to configure Tailwind to use our existing colour scheme, typography sizes, spacing, etc?
  This will be more difficult than you think; many of Hydrogen's core query orders, typography and sizing logic, and handling of mode/theme overrides are going to make replicating the existing experience a lot more complex

Migrating

Beyond the dev work involved, we can't ignore the impact to the design team, as well as the design/dev handoff:

• Because Tailwind likely handles type scale, color tints/shades, and whitespace increments differently, we'd need to make sure those are overwritten in Tailwind's config, or the design team will then need to rework and re-apply our systems in Figma
  • For example, Hydrogen's primary.darker might not be a match in Tailwind's primary 50-950 options, so we'll need a manual config to recreate the light, lighter, lightest, dark, darker, darkest scales
  • Hydrogen's headings are built on a type scale that adapts to media queries, and I'm not sure how to accomplish this beyond writing it manually
  • Hydrogen's whitespace options are generated based on the default paragraph's line-height, which all changes at specific media queries
• The design team has no deep knowledge with Tailwind, so we're now oblivious to Tailwind's limitations, if any
• The design team now no longer has any control over how design constraints should be implemented (These constraints are built into Hydrogen, so we're then at the mercy of Tailwind or whatever the config can offer)
  • Because I built the typography and responsive features, we can confidently know and assume certain things will act a certain way; this will no longer be the case, meaning we'll need to likely have to design more formats in Figma to ensure things respond the way we want
• The design team's direct contribution to development is now gone, we no longer have design ownership of the design system's configuration, and we won't be able to intervene ourselves to fix styling issues as easily as we can now
• Hydrogen acts as a bridge between design and dev, because it enables designer ownership over part of the code, it's spurred collaboration in the past, and it's created a common language for both teams

If there are any discrepancies, we'll need to be involved in figuring out the changes and what they affect - both because we then have to internalize that rule in Figma, and because we have to consider accessibility impacts. I'm not sure how the process would look, but we'd also need to review the PRs across modes and devices. Chromatic should catch a lot, but it definitely won't catch everything across modes, themes, and device sizes, so we'd need to be pretty thorough page-by-page, which is going to be time consuming.

[esizer]

This one is a no-brainer in favor of Tailwind, however it does also warrant discussion of the consequences of piling plugins onto Tailwind and what that actually looks like support-wise in practice. Hydrogen has a single point of failure right now, which is how quickly I can respond to a need or bug, whereas Tailwind + Merge + CSLX + PostCSS + the Vite plugin + whatever else we add on creates multiple points of failure and opportunities for bugs, delayed deployment of dependencies, etc.

Tailwind is close to releasing v4 with one dependency [LightningCSS](One dependency — the only thing the new engine depends on is Lightning CSS.). The vite plugin is first party so I wouldn't be worried about that. Though, it technically does introduce a dependency so if we are that worried about it we could run the CLI version.

The other utilities are entirely optional and just serve to make our lives easier. We could continue just writing complex control flow for variants and not deal with conflicts.

The large wins here are actually the IDE support for intellisense to fail early. They will warn us inline when we are using unsupported values instead of at compile time and missing bugs.

Hydrogen on the other hand, let's you use your theme key as an override (this also applies to dark mode, and I'm not sure if Tailwind has something similar), where you can do something like data-h2-background="base(primary) iap(secondary)" (the example above) or data-h2-background="base:all(primary.light)" (which would force the light variant to persist across light and dark modes).

How often do we use this? Seems a little niche use case where you would use entirely different design tokens based on a theme. If we use it often, it may be better to swap the colour values. But, this would be easy to implement in tailwind.

You can also do this by styling based on a parent.

<body class="iap group\theme">
  <div class="bg-primary group\theme-[.iap]:bg-secondary" />
</body>

Update: We could also just add a new variant for themes.

Because Tailwind likely handles type scale, color tints/shades, and whitespace increments differently, we'd need to make sure those are overwritten in Tailwind's config, or the design team will then need to rework and re-apply our systems in Figma

While tailwind comes with an opinionated and sensible default, it doesn't force you to use it. It is entirely configurable and you can build your own config and replace (or even entirely remove) portions of it. I don't see this being an issue or limitation at all.

[JoshBeveridge]

The large wins here are actually the IDE support for intellisense to fail early. They will warn us inline when we are using unsupported values instead of at compile time and #10984.

Intellisense isn't off the table for Hydrogen, if that's a deal breaker, but it wouldn't have caught the bug you've linked either way, as it would need to be aware of the potential for the same attribute or class to be on the imported component elsewhere in a completely different file, and even then, it wouldn't understand the compiled output and how it might conflict.

How often do we use this? Seems a little niche use case where you would use entirely different design tokens based on a theme. If we use it often, it may be better to swap the colour values. But, this would be easy to implement in tailwind.

More than you think - we have a slew of overrides in Figma (and this is just for primary):

Your example though, highlights why I dislike Tailwind's syntax, particularly compared to:

<body data-h2="iap">
  <div data-h2-background="base(primary) iap(secondary)" />
</body>

While tailwind comes with an opinionated and sensible default, it doesn't force you to use it. It is entirely configurable and you can build your own config and replace (or even entirely remove) portions of it. I don't see this being an issue or limitation at all.

I'm not worried about the base configuration, it's the nuance between how those values change across media queries and whether the values are aware of each other should we change something. There are a lot of interlocked dependencies between variables under the hood in Hydrogen, and my concern is that those won't be replicated by Tailwind out of the box, or that we'll need to manually recreate them in a CSS file (e.g. the paragraph font-size changing, which changes the line-height which then changes the heading line-heights and each whitespace multiplier).

[esizer]

Intellisense isn't off the table for Hydrogen, if that's a deal breaker, but it wouldn't have caught the bug you've linked either way, as it would need to be aware of the potential for the same attribute or class to be on the imported component elsewhere in a completely different file, and even then, it wouldn't understand the compiled output and how it might conflict.

I'm not sure that is correct. The bug was an invalid property which is something tailwind intellisense explicitly picks up and flags as an error.

More than you think - we have a slew of overrides in Figma (and this is just for primary):

I'm a little concered we need to do this so frequently and was assuming it was a very specific use case. I thought we were trying our best to avoid explicit overrides?

Your example though, highlights why I dislike Tailwind's syntax, particularly compared to:

This was just an example to show that it is possible with the assumption it would be very niche. If we really do need to use it that often, we can add a variant to avoid the named group syntax.

[JoshBeveridge]

I'm not sure that is correct. The bug was an invalid property which is something tailwind intellisense explicitly picks up and flags as an error.

Sorry - I misread the ticket you linked - container is deprecated, not invalid, and Hydrogen's console output highlights this already, though yes, Intellisense would catch deprecation too.

I'm a little concered we need to do this so frequently and was assuming it was a very specific use case. I thought we were trying our best to avoid explicit overrides?

Hydrogen is designed for this kind of discrepancy across themes, it's not an override in the sense that we're breaking constraints. The IAP theme has its own set of color usage rules and requirements that are different from GC Talent (2 colors instead of 5 that are used differently within the same components, for example), and Hydrogen allows for those rules to be followed by allowing you to specify styles per theme.

... we can add a variant to avoid the named group syntax.

The variant implementation makes much more sense syntax-wise to me, for sure.

[tristan-orourke]

@substrae Can you explain a bit more about these interlocked variables calculated by Hydrogen?

[JoshBeveridge]

You can find most of what I'm referring to here:

• https://hydrogen.design/en/docs/configuration/creating-themes/#typography
• https://hydrogen.design/en/docs/styling/typography/
• https://hydrogen.design/en/docs/styling/layout/#multipliers

For more nuanced details:

• https://github.com/hydrogen-css/hydrogen/blob/main/lib/scripts/run-hydrogen/02-build-media-array/index.js
• https://github.com/hydrogen-css/hydrogen/blob/main/lib/scripts/run-hydrogen/03-parse-variables/index.js

[tristan-orourke]

Okay, from what I can see, Tailwind doesn't support this kind of modification to the spacing or typography scale based on media query.

[tristan-orourke]

Ah, but perhaps the same thing could be accomplished using CSS variables. tailwindlabs/tailwindcss#9144 (comment)

[esizer]

It is sort of just a different approach as well. By default, you can just change the font-size based on media queries when needed. This way it is clear by reading the code what is happening.

<h1 className="text-3xl mb-3 sm:text-2xl sm:mb-2">

However, for typography, they also have a first-party plugin if you'd like to opt into auto font/space scaling. And as mentioned, you can also just use media queries and css variables as well.

[tristan-orourke]

Nothing's been added here since last week, so here's how it seems to me.

1. It seems like Hydrogen and Tailwind can be functionally equivalent. By that I mean, it doesn't seem like there's anything we're doing right now which couldn't also be set up in Tailwind, and there's nothing we want from our styling which Hydrogen puts out of reach. That makes sense, they're both meant to be complete systems.
2. I do see some advantages in switching to Tailwind:

• The main advantages being in having better tooling and IDE support, and in making the code more familiar to new devs or outsiders.
• There's also the stylistic difference between data attributes and class styling, which may be subjective, but the dev team mostly seems to favour class styles.
• As for Hydrogen providing an avenue for increased collaboration between dev and design, I'm unconvinced that the framework itself is important there; either way, we will need to collaborate on the theme configuration and the design/implementation of individual components/pages.

4. However, those advantages are relatively minor. We have other debt which is much higher priority, such as improving performance of slow queries and continuing the transition to URQL fragments.
5. It would also be a waste of time to adopt Tailwind now if we know there is a major v4 update on the way.

In short, I think we should consider a migration to Tailwind to be in the backlog of debt work, but not a priority. We can revisit the idea after v4 releases, to start with.

[JoshBeveridge]

Heard. Hydrogen support will stop, then, in the interim, unless critical bugs are found.

Whether you are convinced of the collaboration impact of the framework or not, the points I've outlined above are still valid. As such, the requirements from the design team for the migration are as follows:

• Visually, the migration must be 1:1, and this includes typography, color, themes, modes, and whitespace across all current device sizes
• The design team will have final sign off on migration PRs and are absolutely required to approve a migration PR before it gets merged
• The dev team needs to properly implement Storybook for all components, UIs, states, themes, devices, and modes as necessary to allow Chromatic to alleviate the added work on the design team for reviewing the migration
  • Because Hydrogen offers a level of confidence to the design team on how things are implemented by the dev team, having things properly implemented in Storybook will also then become much more important post-migration, so the effort here will have to be sustained for all new UI
• The design team needs specific and detailed documentation from dev about additional work we now need to produce and document
  • If there are discrepancies between Hydrogen and Tailwind that require additional styling guidance, the design team will likely need to also add work to our process (designing for more device cases, for example, or documenting specific color rules that Hydrogen handled internally, etc.)
• The design team will also need specific documentation about the limitations, if any, we have to work within, and how those limitations will impact our Figma system
• Post-migration, the design team will now also have to approve any PRs that involve UI officially before they get merged