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-4 | 16 px | 4 px | p-16 |
| px-6 | 24 px | 6 px | px-24 |
| gap-4 | 16 px | 4 px | gap-16 |
| mt-8 | 32 px | 8 px | mt-32 |
| w-64 | 256 px | 64 px | w-256 |
| h-12 | 48 px | 12 px | h-48 |
| size-8 | 32 px | 8 px | size-32 |
| w-96 | 384 px | 96 px | none (the scale tops out at 256) |
| blur-sm | 8 px | 4 px | blur-md |
| leading-10 | 40 px line height | the 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-64 | 16rem = 256px | w-256 |
| w-16 | 4rem = 64px | w-64 |
| p-4 | 1rem = 16px | p-16 |
| mt-2 | 0.5rem = 8px | mt-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
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.
// taisho.config.ts: the way out for what isn't on the scale
import type { TaishoConfig } from '@taishods/core/generate';
const config: TaishoConfig = {
// …
utilities: { 'card-hero': ['p-double', 'radius-lg'] }, // your own utility, composed from existing ones
};
export default config;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-4xl | 32px isn’t on the radius scale |
| text-3xl | 30px isn’t on the text scale (10, 12, 14, 16, 18, 20, 24, 28, 32, 36, 40, 48, 60, 72) |
| text-8xl | 96px isn’t on the text scale (10, 12, 14, 16, 18, 20, 24, 28, 32, 36, 40, 48, 60, 72) |
| text-9xl | 128px isn’t on the text scale (10, 12, 14, 16, 18, 20, 24, 28, 32, 36, 40, 48, 60, 72) |
| leading-3 | a 12px line height isn’t on the scale |
| leading-snug, leading-normal, leading-relaxed, leading-loose | unitless line height—only `none` and `tight` exist |
| opacity-5 | opacity 5 isn’t on the scale (0, 30, 40, 50, 60, 70, 75, 80, 90, 100) |
| opacity-10 | opacity 10 isn’t on the scale (0, 30, 40, 50, 60, 70, 75, 80, 90, 100) |
| opacity-15 | opacity 15 isn’t on the scale (0, 30, 40, 50, 60, 70, 75, 80, 90, 100) |
| opacity-20 | opacity 20 isn’t on the scale (0, 30, 40, 50, 60, 70, 75, 80, 90, 100) |
| opacity-25 | opacity 25 isn’t on the scale (0, 30, 40, 50, 60, 70, 75, 80, 90, 100) |
| opacity-35 | opacity 35 isn’t on the scale (0, 30, 40, 50, 60, 70, 75, 80, 90, 100) |
| opacity-45 | opacity 45 isn’t on the scale (0, 30, 40, 50, 60, 70, 75, 80, 90, 100) |
| opacity-55 | opacity 55 isn’t on the scale (0, 30, 40, 50, 60, 70, 75, 80, 90, 100) |
| opacity-65 | opacity 65 isn’t on the scale (0, 30, 40, 50, 60, 70, 75, 80, 90, 100) |
| opacity-85 | opacity 85 isn’t on the scale (0, 30, 40, 50, 60, 70, 75, 80, 90, 100) |
| opacity-95 | opacity 95 isn’t on the scale (0, 30, 40, 50, 60, 70, 75, 80, 90, 100) |
| duration-75 | 75ms isn’t on the duration scale |
| duration-700 | 700ms isn’t on the duration scale |
| duration-1000 | 1000ms isn’t on the duration scale |
| ease-out, ease-in-out | that easing curve isn’t on the scale |
| blur-md, backdrop-blur-md | a 12px blur isn’t on the scale |
| blur-xl, backdrop-blur-xl | a 24px blur isn’t on the scale |
| blur-2xl, backdrop-blur-2xl | a 40px blur isn’t on the scale |
| blur-3xl, backdrop-blur-3xl | a 64px blur isn’t on the scale |
| shadow-2xs, shadow-xs, shadow-2xl | that shadow isn’t on the TaishoDS scale (sm, md, lg, xl) |
| static, line-clamp-5, line-clamp-6 | the 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-hidden | border 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-0 | there 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 |
| transition | there’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-inset | the 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-hidden | there’s no `outline-hidden`: to remove the outline, use `outline-none` |
| mt-auto, mb-auto | only `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):
<div class="flex items-center gap-3 p-4 ml-4 w-64 rounded-lg shadow-md md:hidden">
<span class="text-sm font-semibold text-left">Team</span>
</div><div class="ts flex items-center gap-12 p-16 ms-16 w-256 radius-lg shadow-md md:hidden">
<span class="ts text-14 weight-semibold align-start">Team</span>
</div>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).
<link rel="stylesheet" href="/tailwind.css" />
<link rel="stylesheet" href="/taisho.css" /> <!-- after Tailwind -->- 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
tsclass (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.
npx taisho migrate --from tailwind # reports, doesn't write
npx taisho migrate --from tailwind --write # appliesIt 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:
taisho migrate --from tailwind — dry run, nothing was written. Add --write to apply.
Tailwind 4.3.3 (node_modules). The map is for 4.x.
Using taisho.config.ts.
Commit before you use --write, since it rewrites your files.
To convert (5 files):
src/components/Button.jsx 10 converted, 5 `ts` scope classes
src/components/Card.svelte 15 converted, 6 `ts` scope classes
src/index.html 33 converted, 12 `ts` scope classes
…
CONFLICTS (1). These Tailwind names mean something else in TaishoDS, so the elements that use them were left untouched. Rename your class or write that CSS in your stylesheet, then convert the rest by hand:
src/index.html:16 table [choque] Tailwind's `table` isn't what `table` is in TaishoDS (a component). The element was left untouched. …
Converted with a different value (18 pairs). Same intent, not the same pixel or color, so check each one:
shadow-lg → shadow-lg ×1 same intent, different shadow—the TaishoDS one includes the material's 1px ring
src/components/Modal.vue:7
text-2xl → text-24 ×1 fluid—grows with the viewport up to 24px. …
src/index.html:5
…
Not fully converted (29). They stay as they are, so resolve them by hand:
src/components/Card.svelte:4 bg-blue-500 [base] the `blue` family isn't in your theme. Add a `blue` seed to `colors` and run again
src/components/List.tsx:10 2xl:hidden [variante] the `2xl:` breakpoint isn't one of Core's screens; add it with extend.screens
src/index.html:13 dark:bg-gray-900 [variante] `dark:` doesn't exist. Dark mode comes from the theme (`light-dark()`, `createTheme`), not from a class on each element
src/index.html:17 w-[300px] [base] `w-[300px]` has an arbitrary value, and the vocabulary is closed. …
…
Outside the classes (11). Left untouched because they're part of your config, CSS, or JS:
src/styles.css:9 @apply rounded-lg bg-blue-500 px-4 py-2 text-white [apply] `@apply` isn't rewritten. Translation: `radius-lg bg-blue-500 px-16 py-8 text-white`; …
…
Summary: 6 files checked, 5 to modify; 87 classes to TaishoDS (22 with a different value), 33 `ts` scope classes, 1 conflict, 29 not converted, 11 outside the classes, 1 other class.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, inherit | They 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 CSS | It 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-merge | They 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 { "markup": "<div class=\"flex gap-2 p-4 bg-blue-500\">Hello</div>" }
← {
"output": "<div class=\"ts flex gap-8 p-16 bg-blue-500\">Hello</div>",
"converted": [
{ "line": 1, "from": "flex", "to": "flex", "exact": true },
{ "line": 1, "from": "gap-2", "to": "gap-8", "exact": true },
{ "line": 1, "from": "p-4", "to": "p-16", "exact": true }
],
"notConverted": [
{ "line": 1, "token": "bg-blue-500", "type": "base",
"reason": "the `blue` family isn't in your theme. Add a `blue` seed to `colors` and run again" }
]
}