[筆記] TailwindCSS

Core Concepts

專有名詞

• Variant：指 hover:、focus:、dark:、sm: 等等
• Utility classes：能夠在 HTML 中直接套用的 CSS Class
• Theme variables：在 @theme 中定義的主題變數，定義不同的 theme variables 會產生不同的 utility classes，例如 --color-gray-50: oklch(0.984 0.003 247.858);
• Theme variable namespaces：將不同的 theme variables 分類到不同的 namespace 下，例如 --color-*、--font-*、--text-*

概念	定義	主要用途	範例	與其他概念關聯
Utility Classes	Tailwind CSS 中的基本單位，每個類別對應單一 CSS 屬性設定	快速組合 UI 樣式，遵循「Utility-First」理念	bg-blue-500, text-white, p-4, rounded-lg	對應 theme variables 的值，例如 bg-blue-500 會使用 --color-blue-500 變數；可以搭配 variants 產生狀態變化
Theme Variables	使用 @theme 定義的 CSS 變數，Tailwind 會根據它生成對應工具類別	統一管理設計系統的顏色、字型、間距等	@theme { --color-mint-500: oklch(0.72 0.11 178); }	utility classes 會自動對應變數生成，方便全局統一調整
Theme Variable Namespaces	將 theme variables 分類命名，依照用途或屬性類型命名	組織變數，方便生成對應工具類別，保持設計系統一致性	--color-* 對應 bg-*, text-*; --font-* 對應 font-*	namespace 決定變數會生成哪些 utility classes，例如 --color-sunset 生成 bg-sunset, text-sunset 等

Theme Variables

Theme Variables @ TailwindCSS

@theme {
  --color-mint-500: oklch(0.72 0.11 178);  /* 產生 .bg-mint-500 和 var(--color-mint-500) 可以使用 */
  --font-poppins: Poppins, sans-serif;  /* 產生 .font-poppins 可以使用 */
  --breakpoint-3xl: 120rem;  /* 產生 .3xl:grid-cols-6 可以使用 */
}

當我們 @import 'tailwindcss'; 時，實際上會載入：

• node_modules/tailwindcss/theme.css
• node_modules/tailwindcss/preflight.css
• node_modules/tailwindcss/utilities.css

在 theme.css 中有所有 Tailwind 預設的 Theme，如果想要客製化主題，可以參考 Customizing your theme。

/* customized theme variables */
@theme {/* ... */}

/* 如果 customized 的 theme 需要 reference 到其他的變數，需要使用 "inline" 才不會出錯 */
@theme inline {/* ... */}

Adding Custom Themes

Adding Custom Themes @ TailwindCSS

如果要客製化主題，將包含以下幾個方式：

• 使用 Customized Theme Variables
• 使用任意值（Arbitrary values）

<!-- 如果想要使用 Tailwind 內建不支援的 CSS 屬性，則把 [屬性：值] 都放在 "[]" 中 -->
<div class="[mask-type:luminance] hover:[mask-type:alpha]">
  <!-- ... -->
</div>

<!-- 在特定 scope 下修改 CSS variables 的值 -->
<div class="[--scroll-offset:56px] lg:[--scroll-offset:44px]">
  <!-- ... -->
</div>

• 使用 Arbitrary variants
  • 透過 arbitrary variants 可以寫客製化的「CSS selector」

<!-- 當 <li> 元素同時有 .is-dragging 時，就套用 cursor-grabbing -->
<ul>
  <li class="[&.is-dragging]:cursor-grabbing">Some Item</li>
</ul>

<!-- 如果 CSS selector 後需要空格，則使用 "_" 當作空格 -->
<!-- div 裡面的所有 p 都套用 mt-4 -->
<div class="[&_p]:mt-4">
  <p>這段文字會有上邊距。</p>
  <ul>
    <li>
      <p>這段巢狀的文字也會有上邊距。</p>
    </li>
  </ul>
</div>

Configurations

資訊

default configuration @ Github

// tailwind.config.js

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ['./pages/**/*.{html,js}', './components/**/*.{html,js}'],
  darkMode: 'selector',

  theme: {
    // override the entire spacing theme
    spacing: {},
    extend: {
      // add new value or merge with default spacing theme
      spacing: {},
    },
  },

  safelist: ['bg-red-500', 'text-3xl', 'lg:text-4xl'],
  // ...
};

Presets

官方文件

Presets

• 重設 presets：移除所有 default configuration
  • 預設的情況下，presets 仍然會繼承 Tailwind's 的 default configuration（須留意 merge default configuration 的方式）。
  • 如果你希望移除所有 default configuration，則可以使用 presets: [] 的設定，等於是重設 presets。
• merge default configuration 的方式（參考，Merging logic in-depth）
  • 文件中，這裡列出的屬性都會直接被覆蓋
  • Theme
    • Shallow Merge：在 theme object 中的 top-level key 會直接被覆蓋掉，例如，如果給了 spacing、colors、borderRadius 等等這些 top-level key（參考：theme configuration reference 或 default configuration @ Github），則會直接整個覆蓋掉 Tailwind 原本的。
    • Extend：如果不希望把 theme 裡的 top-level key 直接整個覆蓋掉的話，應該要使用 theme.extend

Dark Mode

官方文件

dark mode

在 Tailwind CSS 中，如果希望某些 CSS 只套用在 dark mode 時，可以用 dark:xxx 的 CSS class，例如 dark:bg-slate-800。

• prefers-color-scheme
  • 預設的情況下，Tailwind CSS 會基於使用者在瀏覽器或 OS 的設定來套用 dark mode 的樣式。
• Selector
  • darkMode: 'selector'：如果你希望手動控制什麼時候要套用 dark mode，而不是依賴於瀏覽器的設定，則可以使用這個設定，如此，只要在 html 或 body 上有 .dark 的 CSS class 時，就會套用 dark:bg-slate-800
  • darkMode: ['selector', '[data-mode="dark"]']，預設使用 selector 的情況下，Tailwind 會用 .dark 當 selector，並對其子層元件套用 dark mode。但某些情況下，你可能會需要自訂 selector，這時候就可以用這個設定。以這個設定來說，只要在 html 或 body 加上 [data-model="dark"] 的這個屬性後，dark mode 的樣式才會被套用。

警告

要特別留意的是，如果你的 TailwindCSS 有使用 prefix，你需要加上 .tw-dark 而不是 .dark 才能套用 dark mode。

提示

如果希望預設可以套用使用者瀏覽器或 OS 的設定，同時又讓使用者可以手動選擇要使用的亮/暗色主題，可以參考官網這裡Supporting system preference and manual selection 的範例。

Content Configuration

• safelist：預設的情況下，Tailwind 會去 parse content 中的 CSS classes，以確保最後 bundle 出來的檔案沒有多餘、無用的 class name；然後，如果在某些情況下，即使 App 中沒有用到這個 class，但你仍希望這些 classes 被放在最終 build 好的檔案中，則可以把它們放在 safelist 中，這應該是最終不得不才使用的做法（ref: content-configuration）。