docs: change directory structure

mrcaidev · May 29, 2024 · 92619fc · 92619fc
1 parent 4df5dd3
commit 92619fc
Show file tree

Hide file tree

Showing 14 changed files with 487 additions and 227 deletions.
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
@@ -3,7 +3,7 @@ import { defineConfig } from "vitepress";
 export default defineConfig({
   title: "Tailwind Radix Colors",
   description:
-    "Bring Radix's Color System to Tailwind, and enjoy the best of both Tailwind CSS and Radix UI",
+    "Bring Radix's color system to Tailwind, and enjoy the best of both Tailwind CSS and Radix UI",
   head: [
     [
       "link",
@@ -21,55 +21,75 @@ export default defineConfig({
     nav: [
       {
         text: "Tailwind CSS",
-        link: "https://tailwindcss.com",
+        link: "https://tailwindcss.com/",
       },
       {
-        text: "Radix Colors",
-        link: "https://www.radix-ui.com/colors",
+        text: "Radix UI",
+        link: "https://www.radix-ui.com/",
       },
     ],
     sidebar: [
       {
         text: "Introduction",
+        base: "/introduction",
         items: [
           {
             text: "Getting Started",
             link: "/getting-started",
           },
           {
-            text: "Why Another Palette?",
-            link: "/why-another-palette",
-          },
-          {
-            text: "Why This Plugin?",
-            link: "/why-this-plugin",
+            text: "Usage",
+            link: "/usage",
           },
         ],
       },
       {
         text: "Guide",
+        base: "/guide",
         items: [
           {
-            text: "Utility First",
+            text: "Utility-First",
             link: "/utility-first",
           },
           {
-            text: "Semantic First",
+            text: "Semantic-First",
             link: "/semantic-first",
           },
         ],
       },
       {
         text: "Reference",
+        base: "/reference",
         items: [
           {
-            text: "Options",
+            text: "Plugin Options",
             link: "/options",
           },
+          {
+            text: "Semantic Table",
+            link: "/semantic-table",
+          },
+        ],
+      },
+      {
+        text: "FAQ",
+        base: "/faq",
+        items: [
+          {
+            text: "Why Another Palette?",
+            link: "/why-another-palette",
+          },
+          {
+            text: "Why This Plugin?",
+            link: "/why-this-plugin",
+          },
+          {
+            text: "Why Smaller CSS Bundle?",
+            link: "/why-smaller-css-bundle",
+          },
         ],
       },
     ],
-
     socialLinks: [
       {
         icon: "github",

diff --git a/docs/why-another-palette.md → docs/faq/why-another-palette.md b/docs/why-another-palette.md → docs/faq/why-another-palette.md
@@ -10,7 +10,7 @@ Tailwind's color palette falls short, when we need to apply different color scal
 
 Radix colors, on the other hand, is particularly designed to handle these states, by assigning a semantic meaning to each color scale. For example, "Step 3" stands for normal state, "Step 4" stands for hover state, "Step 5" stands for pressed or selected states, and so on. For a complete list of semantic meanings, please see [Understanding the Scale](https://www.radix-ui.com/docs/colors/palette-composition/understanding-the-scale).
 
-It's also fine to use this plugin, even if you know nothing about the semantic meaning of each scale, or if you find it hard or boring to remember all those guidelines. This plugin provides a set of [semantic classes](/semantic-first), which internally adhere to Radix's design system and best practices. You can use these classes to apply different color scales to different states, without knowing the underlying design principles.
+It's also fine to use this plugin, even if you know nothing about the semantic meaning of each scale, or if you find it hard or boring to remember all those guidelines. This plugin provides a set of [semantic classes](/guide/semantic-first), which internally adhere to Radix's design system and best practices. You can use these classes to apply different color scales to different states, without knowing the underlying design principles.
 
 ## P3 and Alpha Variants
 

diff --git a/docs/faq/why-smaller-css-bundle.md b/docs/faq/why-smaller-css-bundle.md
@@ -0,0 +1,159 @@
+# Why Smaller CSS Bundle?
+
+Compared to [semantic-first](/guide/semantic-first) approach, [utility-first](/guide/utility-first) approach on average generates a smaller CSS bundle.
+
+## Semantic-First
+
+Consider the following example:
+
+```html
+<button class="bg-red-ui">Button 1</button>
+<button class="bg-red-ghost">Button 2</button>
+```
+
+In this example, we use `bg-red-ui` to style one button, and `bg-red-ghost` to style another.
+
+If we inspect the CSS bundle, we will find that the color value of `red-4`, `red-5`, `reddark-4` and `reddark-5` are duplicated, once in `bg-red-ui` and once in `bg-red-ghost`.
+
+::: code-group
+
+```css{7-8,12-13,23-24,28-29} [bg-red-ui]
+.bg-red-ui {
+  --tw-bg-opacity: 1;
+  background-color: rgb(254 235 236 / var(--tw-bg-opacity));
+}
+
+.bg-red-ui:hover {
+  --tw-bg-opacity: 1;
+  background-color: rgb(255 219 220 / var(--tw-bg-opacity));
+}
+
+.bg-red-ui:active {
+  --tw-bg-opacity: 1;
+  background-color: rgb(255 205 206 / var(--tw-bg-opacity));
+}
+
+@media (prefers-color-scheme: dark) {
+  .bg-red-ui {
+    --tw-bg-opacity: 1;
+    background-color: rgb(59 18 25 / var(--tw-bg-opacity));
+  }
+
+  .bg-red-ui:hover {
+    --tw-bg-opacity: 1;
+    background-color: rgb(80 15 28 / var(--tw-bg-opacity));
+  }
+
+  .bg-red-ui:active {
+    --tw-bg-opacity: 1;
+    background-color: rgb(97 22 35 / var(--tw-bg-opacity));
+  }
+}
+```
+
+```css{6-7,11-12,21-22,26-27} [bg-red-ghost]
+.bg-red-ghost {
+  background-color: transparent;
+}
+
+.bg-red-ghost:hover {
+  --tw-bg-opacity: 1;
+  background-color: rgb(255 219 220 / var(--tw-bg-opacity));
+}
+
+.bg-red-ghost:active {
+  --tw-bg-opacity: 1;
+  background-color: rgb(255 205 206 / var(--tw-bg-opacity));
+}
+
+@media (prefers-color-scheme: dark) {
+  .bg-red-ghost {
+    background-color: transparent;
+  }
+
+  .bg-red-ghost:hover {
+    --tw-bg-opacity: 1;
+    background-color: rgb(80 15 28 / var(--tw-bg-opacity));
+  }
+
+  .bg-red-ghost:active {
+    --tw-bg-opacity: 1;
+    background-color: rgb(97 22 35 / var(--tw-bg-opacity));
+  }
+}
+```
+
+:::
+
+This is because Tailwind CSS currently cannot recognize, and thus deduplicate, reused color values across different component classes. As such, these reused values can be bundled multiple times, leading to a bloated CSS bundle size.
+
+## Utility-First
+
+Utility classes will never have to worry about this problem. After all, they are not composed of any other smaller classes. Each used color class will only be generated once, no matter how many times it is actually used.
+
+Considering the same example as above, but this time using utility classes:
+
+```html
+<button
+  className="bg-red-3 hover:bg-red-4 active:bg-red-5 dark:bg-reddark-3 dark:hover:bg-reddark-4 dark:active:bg-reddark-5"
+>
+  Button 1
+</button>
+<button
+  className="bg-transparent hover:bg-red-4 active:bg-red-5 dark:bg-transparent dark:hover:bg-reddark-4 dark:active:bg-reddark-5"
+>
+  Button 2
+</button>
+```
+
+And we inspect the CSS bundle again:
+
+```css
+.bg-red-3 {
+  --tw-bg-opacity: 1;
+  background-color: rgb(254 235 236 / var(--tw-bg-opacity));
+}
+
+.bg-transparent {
+  background-color: transparent;
+}
+
+.hover\:bg-red-4:hover {
+  --tw-bg-opacity: 1;
+  background-color: rgb(255 219 220 / var(--tw-bg-opacity));
+}
+
+.active\:bg-red-5:active {
+  --tw-bg-opacity: 1;
+  background-color: rgb(255 205 206 / var(--tw-bg-opacity));
+}
+
+@media (prefers-color-scheme: dark) {
+  .dark\:bg-reddark-3 {
+    --tw-bg-opacity: 1;
+    background-color: rgb(59 18 25 / var(--tw-bg-opacity));
+  }
+
+  .dark\:bg-transparent {
+    background-color: transparent;
+  }
+
+  .dark\:hover\:bg-reddark-4:hover {
+    --tw-bg-opacity: 1;
+    background-color: rgb(80 15 28 / var(--tw-bg-opacity));
+  }
+
+  .dark\:active\:bg-reddark-5:active {
+    --tw-bg-opacity: 1;
+    background-color: rgb(97 22 35 / var(--tw-bg-opacity));
+  }
+}
+```
+
+Clearly there is no duplicated color value, which signals a smaller CSS bundle size.
+
+## Whose problem?
+
+It's hard to blame Tailwind CSS, but this does not seem like an issue that can be solved on plugin-side. Should Tailwind CSS solve this issue one day (maybe in v4), then the CSS bundle sizes would probably not differ too much between the two approaches.
+
+Anyway, the utility-first approach is still recommended for [its other advantages](/guide/utility-first#advantages).
diff --git a/docs/why-this-plugin.md → docs/faq/why-this-plugin.md b/docs/why-this-plugin.md → docs/faq/why-this-plugin.md
@@ -10,4 +10,4 @@ This plugin solves this problem by replacing the entire color system of Tailwind
 
 As a result, this plugin will only generate the colors you actually use, which means you will have a much smaller CSS bundle, with zero configuration.
 
-Additionally, this plugin also includes a set of [semantic classes](/semantic-first), which can help you build prototypes quickly.
+Additionally, this plugin also includes a set of [semantic classes](/guide/semantic-first), which can help you build prototypes quickly.