review tailwind readme

Author: fjcalzado

03-bundling/06-vite/09-tailwindcss/README.md

@@ -1,9 +1,21 @@
-# TailwindcCSS
+# TailwindCSS
 
 In this example, we are going add TailwindCSS integration.
 
 📌 We start from sample `08-env-vars`.
 
+## Introduction
+
+ℹ️ Before jumping into the sample, let's briefly introduce TailwindCSS.
+
+TailwindCSS is a utility-first framework that provides a set of predefined CSS classes — often referred to as _primitives_. These classes allow you to style elements directly in your markup, instead of writing custom CSS from scratch.
+
+Each class typically maps to a single, simple CSS rule (for example: `h-full` translates to `height: 100%`). This modular approach makes styling faster and more predictable.
+
+While most classes are low-level utilities, TailwindCSS also includes more advanced tools out-of-the-box — like animations, transitions, and responsive variants.
+
+Think of it as a well-organized CSS toolbox: consistent, fast, and highly extensible, making UI development smoother and less prone to complexity than managing large custom stylesheets.
+
 # Steps to build it
 
 ## Prerequisites
@@ -20,18 +32,22 @@ Install [Node.js and npm](https://nodejs.org/en/) (20.19.0 || >=22.12.0) if they
   npm install
   ```
 
-- Let's add a TailwindCSS package:
+- Let's add the main TailwindCSS package:
 
   ```bash
   npm install tailwindcss
   ```
 
+  > ℹ️ `tailwindcss` package is the core of TailwindCSS. It ships the engine that interprets classes (like `bg-red-500` or `h-full`) and generates the proper CSS. It uses `PostCSS` under the hood to compile and optimize styles.
+
   and also TailwindCSS's Vite plugin:
 
   ```bash
   npm install @tailwindcss/vite --save-dev
   ```
 
+  > ℹ️ Although not mandatory, this plugin will help us to integrate TailwindCSS compiler with Vite in a more efficient way. Otherwise, we would have to manually setup PostCSS in Vite configuration.
+
 - Let's modify `vite.config.ts` to include the plugin:
 
   _vite.config.ts_
@@ -56,6 +72,8 @@ Install [Node.js and npm](https://nodejs.org/en/) (20.19.0 || >=22.12.0) if they
   @import "tailwindcss";
   ```
 
+  > ℹ️ This CSS import will bring all base styles and utilities from TailwindCSS.
+
 - And import it in our `index.tsx`;
 
   _index.tsx_
@@ -106,6 +124,11 @@ Install [Node.js and npm](https://nodejs.org/en/) (20.19.0 || >=22.12.0) if they
   + @custom-variant dark (&:where([data-theme=dark], [data-theme=dark] *));
   ```
 
+  > ℹ️ This line is doing the following:
+  >
+  > - The directive `@custom-variant` is creating a variant called `dark` that TailwindCSS will use to apply conditional sytles ... but ¿when?
+  > - The rest, is an advanced selector that is telling TailwindCSS when to apply the `dark:` variant: whe the current element (`&`) is placed within an HTML tree tree that contains `data-theme="dark"` attribute.
+
 - Update our `HelloComponent` to include styles for our new dark theme:
 
   \__src/hello.tsx_
@@ -169,18 +192,22 @@ Install [Node.js and npm](https://nodejs.org/en/) (20.19.0 || >=22.12.0) if they
   \__src/hello.tsx_
 
   ```diff
-  return (
-    <>
-  +   <button
-  +     className="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded"
-  +     onClick={() => {
-  +       const html = document.documentElement;
-  +       const isDark = html.getAttribute("data-theme") === "dark";
-  +       if (isDark) html.setAttribute("data-theme", "");
-  +       else html.setAttribute("data-theme", "dark");
-  +     }}
-  +   >
-  +     Toggle theme
-  +   </button>
-      <h2>Hello from React</h2>
+    };
+
+  + const toggleTheme = () => {
+  +   const html = document.documentElement;
+  +   const isDark = html.getAttribute("data-theme") === "dark";
+  +   if (isDark) html.removeAttribute("data-theme");
+  +   else html.setAttribute("data-theme", "dark");
+  + };
+
+    return (
+      <>
+  +     <button
+  +       className="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded"
+  +       onClick={toggleTheme}
+  +     >
+  +       Toggle theme 🎨
+  +     </button>
+        <h2>Hello from React</h2>
   ```