refactor: migrate Tailwind CSS v3 to v4 with CSS-first config

[pettinarip]

Summary

• Migrates Tailwind CSS from v3.4 to v4 using the official @tailwindcss/upgrade tool, converting from JS config to CSS-first config
• Replaces tailwindcss-animate with tw-animate-css, upgrades tailwind-merge to v3, updates prettier-plugin-tailwindcss
• Converts theme() calls to var(), removes redundant @tailwind base directives, deletes custom not variant plugin (built-in in v4)
• Renames utility classes across ~50 files (bg-gradient-to-* → bg-linear-to-*, flex-shrink-* → shrink-*, etc.)
• Reorganizes global.css (890 lines) into focused single-responsibility files:
  • global.css — thin import manifest + @custom-variant dark
  • theme.css — @theme inline block (Tailwind v4 CSS-first config)
  • base.css — @layer base element defaults (typography, links, lists)
  • utilities.css — all @utility directives (gradients, grid, z-index, staking)
  • docsearch.css — DocSearch library overrides
  • semantic-tokens.css — consolidated all :root/.dark variable declarations
• Replaces @layer components / @layer utilities with @utility directives (v4 best practice)
• Moves non-dynamic @keyframes inside @theme block, co-located with their --animate-* tokens
• Removes dead CSS classes (.gold, .dev-ring) and duplicate DocSearch rules

No bundler change — still using --webpack. Turbopack switch is in a follow-up PR.

Stack

• Base: refactor/storybook-10-upgrade-webpack (PR refactor: upgrade Storybook 8.6 to 10.3 with webpack #17900)
• Next: refactor/turbopack-adoption (Turbopack switch)

Test plan

• pnpm build --webpack succeeds
• pnpm build-storybook succeeds
• Visual regression check via Chromatic
• Dark mode toggle works correctly
• DocSearch modal renders correctly
• Gradient classes render identically
• RTL locales (Arabic, Urdu) render correctly
• Animations (accordion, fade-in, scroll, spin) still work

[netlify]

✅ Deploy Preview for ethereumorg ready!

Name	Link
🔨 Latest commit	9eacfcb
🔍 Latest deploy log	https://app.netlify.com/projects/ethereumorg/deploys/69de32a33be6cf0008f7d47a
😎 Deploy Preview	https://deploy-preview-17905.ethereum.it
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	7 paths audited Performance: 56 (🔴 down 3 from production) Accessibility: 94 (no change from production) Best Practices: 100 (no change from production) SEO: 98 (🔴 down 1 from production) PWA: 59 (no change from production) View the detailed breakdown and full score reports

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[coderabbitai]

Caution

Review failed

An error occurred during the review process. Please try again later.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch refactor/tailwind-v4-migration

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[wackerow]

@pettinarip

Active nav dot color:

May be related to tailwind-merge v3 class resolution or a Tailwind v4 color scale change.

---

Urdu ordered list numbering regression

https://ethereum.org/ur/whitepaper/#ethereum-state-transition-function (Correct)
https://deploy-preview-17905.ethereum.it/ur/whitepaper/#ethereum-state-transition-function

  /* Code blocks are always LTR -- programming languages read left-to-right.
     On RTL pages (ar, ur) the inherited direction makes code unreadable. */
  pre:has(code) {
    direction: ltr;
    text-align: left;
  }

  /* Apply Urdu numerals to ordered lists when the locale is ur */
  :lang(ur) ol {
    list-style-type: urdu;
  }

  /* Fallback for older browsers that don't support urdu counter style */
  @supports not (list-style-type: urdu) {
    :lang(ur) ol {
      list-style-type: persian;
    }
  }

These were recently added to global.css -- The ltr code blocks seem to be working, but the @layer base ol rules aren't being applied.... list-style-type is computing to decimal when it should be urdu (or persian as the fallback). "Likely a cascade/layer processing difference between Tailwind v3 and v4." - Claude

---

Otherwise spot checking is looking good so far!