refactor: migrate Tailwind CSS v3 to v4

- Replace JS config (tailwind.config.ts) with CSS-first config (@config in global.css)
- Migrate postcss.config.js to postcss.config.mjs with @tailwindcss/postcss
- Reorganize CSS into focused files: base.css, theme.css, utilities.css, semantic-tokens.css
- Migrate renamed/removed utilities: rounded, shadow, outline, ring, opacity classes
- Convert space-y patterns to gap where needed, resolve negative margin conflicts
- Fix variant selectors: not-[:first] → not-[:first-child], last variant on alert
- Move custom utilities (staking-grid, area-glyph) to @Utility for variant support
- Use @theme inline for nested .dark containers to resolve semantic tokens correctly
- Import docsearch CSS into cascade layer to restore library styles
- Add json loader for .all-contributorsrc in storybook webpack config
- Fix leading-base setting --tw-leading on code elements
- Remove first heading top margin in content pages for v4 compat
- Update 100+ components with renamed utility classes

Author: pettinarip

.storybook/main.ts

@@ -68,6 +68,12 @@ const config: StorybookConfig = {
       use: ["@svgr/webpack"],
     })
 
+    // .all-contributorsrc is JSON without a .json extension
+    config.module.rules.push({
+      test: /\.all-contributorsrc$/,
+      type: "json",
+    })
+
     return config
   },
 

.storybook/preview.tsx

@@ -10,9 +10,6 @@ import nextIntl, { baseLocales } from "./next-intl"
 import { withNextThemes } from "./withNextThemes"
 
 import "../src/styles/global.css"
-import "../src/styles/docsearch.css"
-
-import "@docsearch/css"
 
 const inter = Inter({
   subsets: ["latin"],

AGENTS.md

@@ -11,7 +11,7 @@ This is the official Ethereum.org website - a Next.js application that serves as
 - **Next.js 14.2+** - React framework with App Router
 - **React 18** - UI library
 - **TypeScript 5.5+** - Type safety and development experience
-- **Tailwind CSS 3.4+** - Utility-first CSS framework
+- **Tailwind CSS 4+** - Utility-first CSS framework (CSS-first config in `src/styles/global.css`)
 
 ### Key Dependencies
 

app/[locale]/10years/_components/NFTMintCard/index.tsx

@@ -20,7 +20,7 @@ const NFTMintCard = ({ className }: NFTMintCardProps) => {
   return (
     <Card
       className={cn(
-        "w-full overflow-hidden rounded-3xl bg-gradient-to-b from-[#A66BFF20] to-[#EED9FE16] shadow-lg",
+        "w-full overflow-hidden rounded-3xl bg-linear-to-b from-[#A66BFF20] to-[#EED9FE16] shadow-lg",
         className
       )}
     >
@@ -30,7 +30,7 @@ const NFTMintCard = ({ className }: NFTMintCardProps) => {
           <div className="flex items-center justify-center pt-12">
             <div className="relative max-h-[200px] max-w-[200px] overflow-hidden rounded-full border-4 border-white bg-white">
               <video
-                className="pointer-events-none h-full w-full select-none rounded-full object-cover"
+                className="pointer-events-none h-full w-full rounded-full object-cover select-none"
                 src="/videos/10y-video.mp4"
                 aria-label={t("page-10-year-video-aria-label")}
                 autoPlay
@@ -47,7 +47,7 @@ const NFTMintCard = ({ className }: NFTMintCardProps) => {
           {/* Curved text */}
           <Curved10YearsText
             viewBox="0 0 313 186"
-            className="absolute left-1/2 top-0 h-min w-full max-w-[300px] -translate-x-1/2 fill-primary"
+            className="fill-primary absolute top-0 left-1/2 h-min w-full max-w-[300px] -translate-x-1/2"
             width="100%"
             height="auto"
           />

app/[locale]/10years/_components/TenYearHero.tsx

@@ -38,20 +38,20 @@ const TenYearHero = async () => {
         <ParallaxImage
           src={TenYearGraphicImage}
           alt={t("page-10-year-anniversary-meta-title")}
-          className="absolute left-0 top-0 max-h-[350px] object-contain transition-transform duration-200 ease-out"
+          className="absolute top-0 left-0 max-h-[350px] object-contain transition-transform duration-200 ease-out"
           priority
         />
       </div>
       <p className="text-center text-3xl">
         {t("page-10-year-celebrating")}{" "}
         <span className="relative max-md:block md:w-fit">
           <span
-            className="select-none opacity-0 max-md:hidden"
+            className="opacity-0 select-none max-md:hidden"
             data-label="space-holder"
           >
             {WORDS[0]}
           </span>
-          <span className="text-3xl font-bold text-accent-b md:absolute md:start-0 md:text-nowrap">
+          <span className="text-accent-b text-3xl font-bold md:absolute md:start-0 md:text-nowrap">
             {/* CLIENT SIDE, lazy loaded */}
             <Morpher words={WORDS} charSet="abcdfgijklnopqsvwxyz" />
           </span>

app/[locale]/10years/_components/TorchHistoryCard.tsx

@@ -41,10 +41,9 @@ const TorchHistoryCard: React.FC<TorchHistoryCardProps> = ({
   return (
     <Card
       className={cn(
-        "flex flex-col rounded-xl border border-gray-100/50 bg-gradient-to-b from-white to-gray-100 px-6 py-12 shadow-lg dark:text-body-inverse",
-        isCurrentHolder && "bg-gradient-to-b from-[#B38DF0] to-[#DED4ED]",
-        isPlaceholder &&
-          "bg-gradient-to-b from-gray-100 to-gray-200 opacity-50",
+        "dark:text-body-inverse flex flex-col rounded-xl border border-gray-100/50 bg-linear-to-b from-white to-gray-100 px-6 py-12 shadow-lg",
+        isCurrentHolder && "bg-linear-to-b from-[#B38DF0] to-[#DED4ED]",
+        isPlaceholder && "bg-linear-to-b from-gray-100 to-gray-200 opacity-50",
         className
       )}
     >

app/[locale]/10years/_components/data.tsx

@@ -1,11 +1,11 @@
 // duplicate 1 2 3, 1 2 3 to fix mobile slider bug where styles are not applied
 const adoptionStyles = [
-  "bg-background bg-gradient-to-b from-20% to-60% from-accent-c/10 to-accent-c/5 dark:from-accent-c/20 dark:to-accent-c/10 border-accent-c/10",
-  "bg-background bg-gradient-to-b from-20% to-60% from-accent-b/10 to-accent-b/5 dark:from-accent-b/20 dark:to-accent-b/10 border-accent-b/10",
-  "bg-background bg-gradient-to-b from-20% to-60% from-accent-a/10 to-accent-a/5 dark:from-accent-a/20 dark:to-accent-a/10 border-accent-a/10",
-  "bg-background bg-gradient-to-b from-20% to-60% from-accent-c/10 to-accent-c/5 dark:from-accent-c/20 dark:to-accent-c/10 border-accent-c/10",
-  "bg-background bg-gradient-to-b from-20% to-60% from-accent-b/10 to-accent-b/5 dark:from-accent-b/20 dark:to-accent-b/10 border-accent-b/10",
-  "bg-background bg-gradient-to-b from-20% to-60% from-accent-a/10 to-accent-a/5 dark:from-accent-a/20 dark:to-accent-a/10 border-accent-a/10",
+  "bg-background bg-linear-to-b from-20% to-60% from-accent-c/10 to-accent-c/5 dark:from-accent-c/20 dark:to-accent-c/10 border-accent-c/10",
+  "bg-background bg-linear-to-b from-20% to-60% from-accent-b/10 to-accent-b/5 dark:from-accent-b/20 dark:to-accent-b/10 border-accent-b/10",
+  "bg-background bg-linear-to-b from-20% to-60% from-accent-a/10 to-accent-a/5 dark:from-accent-a/20 dark:to-accent-a/10 border-accent-a/10",
+  "bg-background bg-linear-to-b from-20% to-60% from-accent-c/10 to-accent-c/5 dark:from-accent-c/20 dark:to-accent-c/10 border-accent-c/10",
+  "bg-background bg-linear-to-b from-20% to-60% from-accent-b/10 to-accent-b/5 dark:from-accent-b/20 dark:to-accent-b/10 border-accent-b/10",
+  "bg-background bg-linear-to-b from-20% to-60% from-accent-a/10 to-accent-a/5 dark:from-accent-a/20 dark:to-accent-a/10 border-accent-a/10",
 ]
 
 export { adoptionStyles }

app/[locale]/10years/page.tsx

@@ -96,7 +96,7 @@ const Page = async (props: { params: Promise<PageParams> }) => {
         </div>
 
         <div className="w-full px-4 py-8 md:px-8">
-          <div className="flex flex-col items-center gap-4 rounded-4xl bg-radial-a px-4 pt-8 lg:px-14 lg:pt-14">
+          <div className="bg-radial-a flex flex-col items-center gap-4 rounded-4xl px-4 pt-8 lg:px-14 lg:pt-14">
             <div className="flex flex-col gap-4 text-center">
               <h2 className="text-4xl font-black">
                 {t("page-10-year-livestream-title")}
@@ -117,12 +117,12 @@ const Page = async (props: { params: Promise<PageParams> }) => {
               defaultValue={Object.keys(tenYearEventRegions)[0]}
               className="w-full"
             >
-              <TabsList className="w-full flex-nowrap justify-start overflow-x-auto overflow-y-hidden rounded-none border-b-2 border-b-primary p-0">
+              <TabsList className="border-b-primary w-full flex-nowrap justify-start overflow-x-auto overflow-y-hidden rounded-none border-b-2 p-0">
                 {Object.entries(tenYearEventRegions).map(([key, data]) => (
                   <TabsTrigger
                     key={key}
                     value={key}
-                    className="whitespace-nowrap border-0 text-primary"
+                    className="text-primary border-0 whitespace-nowrap"
                   >
                     {data.label}&nbsp;
                     <span className="text-sm">({data.events.length})</span>
@@ -157,8 +157,8 @@ const Page = async (props: { params: Promise<PageParams> }) => {
                             key={country}
                             className={cn("flex flex-col border-b px-4 py-6")}
                           >
-                            <h3 className="mb-2 flex items-center gap-2 text-2xl font-bold text-body-medium">
-                              <span className="flex min-h-6 min-w-6 items-center justify-center overflow-hidden rounded-full bg-primary-low-contrast">
+                            <h3 className="text-body-medium mb-2 flex items-center gap-2 text-2xl font-bold">
+                              <span className="bg-primary-low-contrast flex min-h-6 min-w-6 items-center justify-center overflow-hidden rounded-full">
                                 <Emoji
                                   text={countryEvents[0].countryFlag}
                                   className="scale-[1.75]"
@@ -170,7 +170,7 @@ const Page = async (props: { params: Promise<PageParams> }) => {
                               {countryEvents.map((event, index) => (
                                 <LinkBox
                                   key={index}
-                                  className="flex flex-col justify-between gap-2 rounded-lg p-2 hover:bg-background-highlight md:flex-row"
+                                  className="hover:bg-background-highlight flex flex-col justify-between gap-2 rounded-lg p-2 md:flex-row"
                                 >
                                   <div className="flex flex-col gap-2 md:flex-row md:items-center">
                                     <div>
@@ -206,7 +206,7 @@ const Page = async (props: { params: Promise<PageParams> }) => {
 
         <div
           id="torch-history"
-          className="my-32 flex w-full scroll-mt-32 flex-col bg-gradient-to-b from-[#161A36] via-[#161A36] via-60% to-[#9C63F8] md:rounded-3xl"
+          className="my-32 flex w-full scroll-mt-32 flex-col bg-linear-to-b from-[#161A36] via-[#161A36] via-60% to-[#9C63F8] md:rounded-3xl"
         >
           <div className="p-8">
             <div className="relative">
@@ -224,13 +224,13 @@ const Page = async (props: { params: Promise<PageParams> }) => {
                     disablePictureInPicture
                     playsInline
                   />
-                  <div className="pointer-events-none absolute top-0 h-full w-full select-none bg-[url('/images/10-year-anniversary/torch-overlay.png')] bg-contain bg-center bg-no-repeat" />
+                  <div className="pointer-events-none absolute top-0 h-full w-full bg-[url('/images/10-year-anniversary/torch-overlay.png')] bg-contain bg-center bg-no-repeat select-none" />
                 </div>
               </div>
               {/* Curved text */}
               <Curved10YearsText
                 viewBox="0 0 356 186"
-                className="absolute left-1/2 top-0 h-min w-full max-w-[600px] -translate-x-1/2"
+                className="absolute top-0 left-1/2 h-min w-full max-w-[600px] -translate-x-1/2"
                 width="100%"
                 height="auto"
               />
@@ -239,7 +239,7 @@ const Page = async (props: { params: Promise<PageParams> }) => {
 
           <TorchHistorySwiper holders={torchHolders} />
 
-          <div className="flex flex-col gap-12 px-8 pb-24 pt-12 text-body-inverse sm:px-16 md:flex-row dark:text-body">
+          <div className="text-body-inverse dark:text-body flex flex-col gap-12 px-8 pt-12 pb-24 sm:px-16 md:flex-row">
             <div className="flex flex-1 flex-col gap-8">
               <p>
                 <Translation
@@ -271,10 +271,10 @@ const Page = async (props: { params: Promise<PageParams> }) => {
         <div className="flex w-full flex-col items-center gap-8 px-8 py-8 lg:flex-row">
           <div className="flex flex-1 flex-col gap-6">
             <h2 className="flex flex-col gap-2 font-black">
-              <span className="text-4xl text-accent-a">
+              <span className="text-accent-a text-4xl">
                 {t("page-10-year-innovation-title")}
               </span>
-              <span className="text-5xl text-body md:text-7xl">
+              <span className="text-body text-5xl md:text-7xl">
                 {t("page-10-year-innovation-subtitle")}
               </span>
             </h2>
@@ -292,10 +292,10 @@ const Page = async (props: { params: Promise<PageParams> }) => {
           <div className="relative flex max-w-[350px] flex-1 flex-col gap-6">
             <div className="flex flex-col gap-6 lg:sticky lg:top-64 lg:mb-24">
               <h2 className="flex flex-col gap-2 font-black">
-                <span className="text-4xl text-accent-a">
+                <span className="text-accent-a text-4xl">
                   {t("page-10-year-adoption-title")}
                 </span>
-                <span className="text-5xl text-body md:text-7xl">
+                <span className="text-body text-5xl md:text-7xl">
                   {t("page-10-year-adoption-subtitle")}
                 </span>
               </h2>
@@ -348,10 +348,10 @@ const Page = async (props: { params: Promise<PageParams> }) => {
           <div className="flex max-w-[350px] flex-1 flex-col gap-6">
             <div className="flex flex-col gap-6 lg:sticky lg:top-64 lg:mb-24">
               <h2 className="flex flex-col gap-2 font-black">
-                <span className="text-4xl text-accent-a">
+                <span className="text-accent-a text-4xl">
                   {t("page-10-year-stories-title")}
                 </span>
-                <span className="text-5xl text-body md:text-7xl">
+                <span className="text-body text-5xl md:text-7xl">
                   {t("page-10-year-stories-subtitle")}
                 </span>
               </h2>

app/[locale]/_components/HomepageLazyImports.tsx

@@ -11,7 +11,7 @@ export const BentoCardSwiper = dynamic(
     ssr: false,
     loading: () => (
       <div className="flex flex-col items-center gap-4">
-        <Skeleton className="mx-auto mt-4 h-[476px] w-[512px] max-w-128 rounded-2xl border-primary/10 bg-background bg-gradient-to-b from-primary/10 from-20% to-primary/5 to-60% p-4 opacity-50 shadow-card-hover lg:hidden dark:from-primary/20 dark:to-primary/10" />
+        <Skeleton className="border-primary/10 bg-background from-primary/10 to-primary/5 shadow-card-hover dark:from-primary/20 dark:to-primary/10 mx-auto mt-4 h-[476px] w-[512px] max-w-128 rounded-2xl bg-linear-to-b from-20% to-60% p-4 opacity-50 lg:hidden" />
         <Skeleton className="h-6 w-[12rem] rounded-full" />
       </div>
     ),