Tailwind rendering parity checklist (apps + Storybook)

Minimal, proven steps we used to fix SubscribeCta parity. Keep it short and do every step.

0) Versions (root package.json)

• tailwindcss: 3.4.10
• postcss: 8.4.47
• autoprefixer: 10.4.20

1) CSS entry

• File contains only:
  • @tailwind base;
  • @tailwind components;
  • @tailwind utilities;
• Imported once by the app (e.g. src/main.tsx), not via <link> in HTML.

2) Tailwind config (app)

Use CommonJS and resolve content paths relative to the config file.

// apps/*/web/tailwind.config.js
module.exports = {
  darkMode: 'class',
  presets: [require('../../../../packages/config/tailwind-preset.js')],
  content: {
    relative: true, // important in workspaces/monorepo
    files: [
      './index.html',
      './src/**/*.{js,jsx,ts,tsx}',
      '../../../../packages/ui-web/src/**/*.{js,jsx,ts,tsx}',
      '../../../../packages/ui-*/src/**/*.{js,jsx,ts,tsx}',
    ],
  },
};

3) PostCSS config

Use PostCSS plugin (not @tailwindcss/vite). For Storybook, explicitly point Tailwind at the local config.

packages/storybook/postcss.config.js

const path = require('path');
module.exports = {
  plugins: {
    tailwindcss: { config: path.join(__dirname, 'tailwind.config.js') },
    autoprefixer: {},
  },
};

4) Storybook Tailwind config

CommonJS, same preset, and content relative to the config file.

packages/storybook/tailwind.config.js

module.exports = {
  darkMode: 'class',
  presets: [require('../config/tailwind-preset.js')],
  content: { relative: true, files: [
    './stories/**/*.{js,jsx,ts,tsx,mdx}',
    '../ui-web/src/**/*.{js,jsx,ts,tsx}',
    '../ui-*/src/**/*.{js,jsx,ts,tsx}',
  ]},
};

Optional Vite aliases in .storybook/main.ts help deep imports resolve in stories:

• @cloudalt-frontend/ui-web → ../../ui-web
• @cloudalt-frontend/ui-stay-match → ../../ui-stay-match

5) Remove v4 artifacts

• Delete any CSS using @import "tailwindcss" or @source.
• Replace @tailwindcss/postcss with { tailwindcss: {}, autoprefixer: {} }.

6) Visual sanity checks

• Start Storybook; confirm no “content missing/empty” warnings.
• Open app; verify classes like max-w-7xl, rounded-2xl, lg:flex-row exist in DevTools.
• If SVG icons look oversized, confirm w-4 h-4 exist; as fallback, add width/height attributes on <svg>.

7) Common symptoms → fixes

• Styled in SB but plain in app → app content.files missing package globs or not relative: true.
• SB warns “content missing” → wrong export type (use CJS) or PostCSS not pointing to SB Tailwind config.
• Dark mode mismatch → add darkMode: 'class' to both configs.

That’s it. Keep it minimal and consistent.