Skip to content

Coming from Tailwind

TaishoDS Core is a framework-free design system with its own class vocabulary. This guide shows which TaishoDS Core class matches each Tailwind class, where the two vocabularies match and where they don’t, and how to move from one to the other without breaking the project along the way.

The ten most common traps

These classes are written the same in both systems and measure something else. None of them throws an error: the page just comes out different.

Class In Tailwind In TaishoDS Equivalent
p-416 px4 pxp-16
px-624 px6 pxpx-24
gap-416 px4 pxgap-16
mt-832 px8 pxmt-32
w-64256 px64 pxw-256
h-1248 px12 pxh-48
size-832 px8 pxsize-32
w-96384 px96 pxnone (the scale tops out at 256)
blur-sm8 px4 pxblur-md
leading-1040 px line heightthe number is the text size it goes with (the line height is 14 px)leading-32

taisho migrate --from tailwind translates these numbers on its own, except w-96, which has no equivalent and stays in its report. taisho check --other-scale flags them in what is written by hand, on elements that carry the ts key.


Before the table: sizes

It’s the first thing that breaks when you migrate. In Tailwind, the number in a size class is a 4px step (w-64 = 16rem = 256px at 1rem = 16px). In TaishoDS it’s the value in px (ts-w-64 = 64px). That’s why the table is built from the px value, not the number, and the note on each size row shows both.

Tailwind Size TaishoDS
w-6416rem = 256pxw-256
w-164rem = 64pxw-64
p-41rem = 16pxp-16
mt-20.5rem = 8pxmt-8

Look at the second row. w-16 in Tailwind and w-16 aren’t the same size. If you copy the number, the layout comes out small. What you carry over is the size, not the number, which is why the table further down is organized by pixel value and not by the number in the class.

There’s no mechanical swap by number

Copying the Tailwind class as is (p-4) changes sizes silently and throws no error, because in the system it’s a different amount. Use the equivalence table.

What changes besides sizes

The vocabulary is closed

There are no arbitrary values. p-[13px] and bg-[#1da1f2] have no equivalent. Every class exists because its value is on a scale, and the scales are the system’s (Tokens). When you need a value that isn’t there, the way out is a token in your config or your own utility built from existing ones, not a one-off value in the HTML. The steps Tailwind has and TaishoDS doesn’t (p-28, opacity-5…) are listed at the end of the table, with the reason.

ts

Variants: the same ones, from a closed list

The most common state variants exist and are written the same way: hover:, focus:, focus-visible:, active:, disabled:, checked:, invalid:, group-* and peer-* (named ones too, group/menu), aria-<state>:, data-<name>:, and print:, plus the screen and container ones. You can chain them (md:hover:), always in the same order. The Variants guide covers them one by one.

A few differences are worth knowing. disabled: also applies to aria-disabled="true". data-<name>: only checks whether the attribute is present, not its value, and aria-<state>: accepts a closed list of boolean states. A variant with brackets (data-[open]:, aria-[sort=up]:) has no equivalent, just like arbitrary values. has-*, not-*, first:, odd:, focus-within:, motion-*, and supports-* don’t exist either. And variants apply to utilities, not to a component’s classes.

Screen-width variants break at the same pixel values on both sides: sm: 640px, md: 768px, lg: 1024px, xl: 1280px. The max-sm: caps work too, but there are no two-sided ranges in one class (md:max-xl:), and 2xl: is added with extend.screens in the config. The details are in Responsive.

dark: doesn’t exist either, and you don’t need it. Dark mode comes from the theme (Theming), not from a variant on every class. And space-x-* / space-y-* are replaced by gap on the flex or grid container.

Logical side, not physical

pl-*, pr-*, ml-*, mr-*, left-*, right-*, text-left, and text-right move to the logical side (ps, pe, ms, me, start, end, align-start, align-end). In a right-to-left language they mirror on their own; in Tailwind, they don’t. It’s a change in behavior, and that’s intended. The table row flags it in the “What changes” column. See RTL.

Colors: same name, different color

The name matches, the color doesn’t. The TaishoDS palette comes from your theme’s seeds (OKLCH), not from Tailwind’s. Check the result by eye. Only gray matches by name. The other Tailwind families (slate, zinc, neutral, stone…) don’t exist, because your palette comes from your theme’s seeds. Only one prefix changes. bg- and border- are written the same, and text color is color- (because text- is the size).

And the cascade

The system’s CSS lives in layers (@layer base, components, utilities, states, utility-states, print). An unlayered rule of yours beats the system’s; if your CSS uses layers too, the order you declare them in decides. With the ts scope class, a system rule has the specificity of one class, the same as a class of yours, so between the two, the order in the file decides.


The equivalence table

Built for Tailwind 4.x with its default theme (1405 rows). A command generates it from the system’s scales, it isn’t written by hand, and every TaishoDS class it lists exists and follows the naming grammar. When the “What changes” column has a note, the result isn’t identical, so read it before you replace anything. Each family is collapsed.

What has no equivalent

Tailwind classes Why there’s no equivalent
inset-px, inset-0.5, inset-1, inset-1.5, inset-2, inset-2.5 … (26)inset: no px class or rhythm step for this prefix
inset-x-px, inset-x-0.5, inset-x-1, inset-x-1.5, inset-x-2, inset-x-2.5 … (26)inset-x: no px class or rhythm step for this prefix
inset-y-px, inset-y-0.5, inset-y-1, inset-y-1.5, inset-y-2, inset-y-2.5 … (26)inset-y: no px class or rhythm step for this prefix
p-28, px-28, py-28, pt-28, pb-28, ps-28 … (46)112px isn’t on the sizing scale
p-36, px-36, py-36, pt-36, pb-36, ps-36 … (46)144px isn’t on the sizing scale
p-44, px-44, py-44, pt-44, pb-44, ps-44 … (46)176px isn’t on the sizing scale
p-52, px-52, py-52, pt-52, pb-52, ps-52 … (46)208px isn’t on the sizing scale
p-60, px-60, py-60, pt-60, pb-60, ps-60 … (46)240px isn’t on the sizing scale
p-72, px-72, py-72, pt-72, pb-72, ps-72 … (46)288px isn’t on the sizing scale
p-80, px-80, py-80, pt-80, pb-80, ps-80 … (46)320px isn’t on the sizing scale
p-96, px-96, py-96, pt-96, pb-96, ps-96 … (46)384px isn’t on the sizing scale
rounded-4xl32px isn’t on the radius scale
text-3xl30px isn’t on the text scale (10, 12, 14, 16, 18, 20, 24, 28, 32, 36, 40, 48, 60, 72)
text-8xl96px isn’t on the text scale (10, 12, 14, 16, 18, 20, 24, 28, 32, 36, 40, 48, 60, 72)
text-9xl128px isn’t on the text scale (10, 12, 14, 16, 18, 20, 24, 28, 32, 36, 40, 48, 60, 72)
leading-3a 12px line height isn’t on the scale
leading-snug, leading-normal, leading-relaxed, leading-looseunitless line height—only `none` and `tight` exist
opacity-5opacity 5 isn’t on the scale (0, 30, 40, 50, 60, 70, 75, 80, 90, 100)
opacity-10opacity 10 isn’t on the scale (0, 30, 40, 50, 60, 70, 75, 80, 90, 100)
opacity-15opacity 15 isn’t on the scale (0, 30, 40, 50, 60, 70, 75, 80, 90, 100)
opacity-20opacity 20 isn’t on the scale (0, 30, 40, 50, 60, 70, 75, 80, 90, 100)
opacity-25opacity 25 isn’t on the scale (0, 30, 40, 50, 60, 70, 75, 80, 90, 100)
opacity-35opacity 35 isn’t on the scale (0, 30, 40, 50, 60, 70, 75, 80, 90, 100)
opacity-45opacity 45 isn’t on the scale (0, 30, 40, 50, 60, 70, 75, 80, 90, 100)
opacity-55opacity 55 isn’t on the scale (0, 30, 40, 50, 60, 70, 75, 80, 90, 100)
opacity-65opacity 65 isn’t on the scale (0, 30, 40, 50, 60, 70, 75, 80, 90, 100)
opacity-85opacity 85 isn’t on the scale (0, 30, 40, 50, 60, 70, 75, 80, 90, 100)
opacity-95opacity 95 isn’t on the scale (0, 30, 40, 50, 60, 70, 75, 80, 90, 100)
duration-7575ms isn’t on the duration scale
duration-700700ms isn’t on the duration scale
duration-10001000ms isn’t on the duration scale
ease-out, ease-in-outthat easing curve isn’t on the scale
blur-md, backdrop-blur-mda 12px blur isn’t on the scale
blur-xl, backdrop-blur-xla 24px blur isn’t on the scale
blur-2xl, backdrop-blur-2xla 40px blur isn’t on the scale
blur-3xl, backdrop-blur-3xla 64px blur isn’t on the scale
shadow-2xs, shadow-xs, shadow-2xlthat shadow isn’t on the TaishoDS scale (sm, md, lg, xl)
static, line-clamp-5, line-clamp-6the TaishoDS class isn’t emitted (its vocabulary is smaller than Tailwind’s)
bg-white, text-white, bg-black, text-black, bg-current, text-current … (8)white, black, current, and inherit aren’t theme colors (color comes from the seeds). For a surface, use `bg-background-100` or a gray from the scale (`bg-gray-100`…`bg-gray-1000`); for text, `color-gray-1000` or the theme color
2xl:*the 2xl breakpoint isn’t one of Core’s screens; add it with extend.screens
p-[13px], w-[calc(100%-2rem)], bg-[#1da1f2]arbitrary values—the vocabulary is closed. The way out is a token in your config (taisho.config.ts) or your own utility in `utilities`
data-[open]:*, aria-[sort=up]:*, has-*:*, not-*:*, first:*, odd:* … (9)variants outside the closed list. The state variants that exist are hover, focus, focus-visible, active, disabled, checked, invalid, group-*, peer-*, aria-<state>, data-<name> (presence only), and print; for anything else, your own class in your CSS
dark:*there’s no `dark:` variant. Dark mode comes from the theme (`light-dark()`, `createTheme`), not from a class on each element
space-x-*, space-y-*they don’t exist; use `gap-*` on the flex/grid container instead
rotate-0, rotate-1, rotate-2, rotate-3, rotate-6, rotate-12 … (8)only `rotate-180` exists, there are no other rotations; for another angle, your own utility in `utilities`
border-solid, border-dashed, border-dotted, border-double, border-hiddenborder style isn’t a separate class—TaishoDS borders are solid; for dashes or dots, your own utility in `utilities`
grayscale, grayscale-0, invert, invert-0, sepia, sepia-0there are no color filters, only `blur-*` and `backdrop-blur-*`; for another filter, your own utility in `utilities`
bg-gradient-to-*, bg-linear-*there are no gradients—the background is a color from the scale; for a gradient, your own utility in `utilities`
border-0, border-8, border-t, border-b, border-l, border-r … (8)the `border-N` width (1 to 4) draws all four sides and `border-none` removes it: there’s no `border-0` or `border-8`, and no side or axis without a number; the single-side one (`border-t-N`) only sets the width, and `border-t-<family>-<n>` draws the line
transitionthere’s no bare `transition`—pick the property (`transition-colors`, `transition-opacity`, `transition-shadow`, `transition-transform`, `transition-all`). `duration-*` and `ease-*` set the duration and the curve, and components already ship their own transition; for another property, your own utility in `utilities`
ring, ring-0, ring-8, ring-insetthe ring goes from 1 to 4 (`ring-1`…`ring-4`): there’s no `ring` without a number, `ring-0`, `ring-8`, or `ring-inset`. The focus ring comes from the reset (`:focus-visible`) and each component
outline-hiddenthere’s no `outline-hidden`: to remove the outline, use `outline-none`
mt-auto, mb-autoonly `m-auto`, `mx-auto`, `my-auto`, `ms-auto`, and `me-auto` exist
md:max-xl:*, min-md:*no ranges. Each screen has its “from” variant (`md:`) and its “up to” variant (`max-md:`), but not both in one class

The table covers the families above. What isn’t anywhere (transforms, most negative margins) isn’t covered yet, neither with a row nor with a reason. Don’t assume it doesn’t exist—look for it in Utilities.


Migrate step by step

While you migrate, TaishoDS Core and Tailwind can be loaded at the same time. The order matters: Tailwind first, TaishoDS second. That way an element with the ts scope class gets the TaishoDS styles, and one without it keeps Tailwind’s. The other way around breaks. p-16 is 64px in Tailwind and 16px in TaishoDS, and both stylesheets define that class. That’s why you migrate element by element. When you move one, you change all of its classes and add the ts class. A sample fragment, before and after (every class comes from the table above):

Tailwind
TaishoDS

1. Add TaishoDS after Tailwind

Install Core with the Installation guide and load its stylesheet after Tailwind’s. Elements without the ts class don’t get anything from the system, except the reset, which is global (Class names).

Stylesheet order
  • Remove: nothing yet.
  • Check: that the page looks the same with both stylesheets loaded.

2. Go screen by screen

Run the tool (below) or replace a screen’s classes using the table. Change sizes first (the number isn’t the same), then sides (physical to logical) and colors. Anything without a row becomes your own class or a token in the config.

  • Remove: every Tailwind class on that screen, without leaving any behind.
  • Check: the screen by eye in light and dark mode, and in a right-to-left language if you support one. Search with your editor to make sure no Tailwind class is left in what you migrated, especially state variants.

3. Remove Tailwind

When the tool no longer reports anything and there’s no Tailwind class left in the project, take it out of the build and the dependencies, and run npx taisho generate.

  • Remove: Tailwind from the build and the dependencies.
  • Check: that every element with system classes has the ts class (if it’s missing, there’s no error, it just gets no styles).

Migrate with a tool

taisho migrate --from tailwind translates Tailwind classes into TaishoDS ones with the same table as this page. Without --write it only reports and doesn’t touch any file. With --write it applies the changes, so commit first.

Command

It converts what’s clearly a list of classes (class, className, clsx, cn, cva…), adds the ts class, and never writes your config or your CSS. Whatever needs a decision there, it suggests in the report. It only works with Tailwind 4. If you’re on Tailwind 3, upgrade to 4 first with Tailwind’s official tool. The same names mean different things, and the tool refuses to run.

Here’s the report on a test project, trimmed to what’s representative:

Output

What isn’t converted, and what to do

What isn’t converted What to do
An element with a conflicting class (table, or your own card)The whole element is left untouched, without the ts class. Rename your class or write that CSS in your stylesheet, then convert the rest of the element by hand.
A color from a family that isn’t in your theme (bg-blue-500)Add a seed for that family to colors in your config and run it again.
white, black, current, inheritThey aren’t theme colors. Use bg-background-100, a gray from the scale (color-gray-1000), or the theme color.
A breakpoint that isn’t on the list (2xl:)Add it with extend.screens in the config and run it again.
An arbitrary value (w-[300px], data-[open]:)The vocabulary is closed. Use a token in the config or your own utility in utilities.
@apply in your CSSIt isn’t rewritten. The report gives the translation and, for a single selector, the custom utility in utilities that replaces it.
dark:It doesn’t exist. Dark mode comes from the theme, not from a class on each element.
ring without a number, single-side border, ! (important), first:They have no direct equivalent; the report tells you the way out for each one.
Classes built at runtime, classList, tailwind-mergeThey can’t be translated automatically. Write the whole class, or build it from a map of complete classes.

Resolve the conflicts first. An element with one stays untouched until you do. Then the classes “converted with a different value,” because TaishoDS colors and shadows aren’t Tailwind’s. Check each one by eye. The tool converts a Svelte class:p-4 directive, but the ts class can’t go in a directive. If the element has no class, add a class="ts". A second pass with --write doesn’t convert again what already has the ts class.

With an AI assistant

The MCP server that ships in the package (taisho mcp, covered in AI assistants) has a translate_tailwind tool. It takes markup with Tailwind classes and returns the converted markup, the list of what it converted (with a note when the value changes), and what it couldn’t, with the reason. It uses the same table as taisho migrate, and the result is worth running through validate_markup. Numbers aren’t translated by name: p-4 is 16 px in Tailwind and 4 px in TaishoDS.

translate_tailwind