ui-styling

UI 樣式技能

結合 shadcn/ui 元件、Tailwind CSS 工具樣式與基於畫布的視覺設計系統，建立美觀且無障礙的使用者介面的全方位技能。

參考資料

• shadcn/ui：https://ui.shadcn.com/llms.txt
• Tailwind CSS：https://tailwindcss.com/docs

何時使用此技能

適用於：

• 使用 React 框架（Next.js、Vite、Remix、Astro）建構 UI
• 實作無障礙元件（對話框、表單、表格、導覽）
• 使用工具優先 CSS 方法進行樣式設計
• 建立響應式、行動優先的版面
• 實作深色模式與主題自訂
• 使用一致的設計代碼建立設計系統
• 產生視覺設計、海報或品牌素材
• 快速原型設計，即時視覺回饋
• 新增複雜 UI 模式（資料表格、圖表、指令面板）

核心技術棧

元件層：shadcn/ui

• 透過 Radix UI 基礎元件提供的預建無障礙元件
• 複製貼上發行模式（元件存在於你的程式碼庫中）
• TypeScript 優先，完整型別安全
• 可組合的基礎元件，適用於複雜 UI
• 基於 CLI 的安裝與管理

樣式層：Tailwind CSS

• 工具優先的 CSS 框架
• 建置時處理，零執行時期開銷
• 行動優先的響應式設計
• 一致的設計代碼（色彩、間距、排版）
• 自動消除未使用的 CSS

視覺設計層：Canvas

• 博物館等級的視覺構圖
• 以設計哲學為導向的方法
• 精緻的視覺溝通
• 極簡文字，最大視覺衝擊
• 系統化的模式與精煉美學

快速開始

元件 + 樣式設定

安裝 shadcn/ui 與 Tailwind：

npx shadcn@latest init

CLI 會提示選擇框架、TypeScript、路徑與主題偏好。這會同時設定 shadcn/ui 與 Tailwind CSS。

新增元件：

npx shadcn@latest add button card dialog form

使用元件搭配工具樣式：

import { Button } from "@/components/ui/button"
import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card"

export function Dashboard() {
  return (
    <div className="container mx-auto p-6 grid gap-6 md:grid-cols-2 lg:grid-cols-3">
      <Card className="hover:shadow-lg transition-shadow">
        <CardHeader>
          <CardTitle className="text-2xl font-bold">Analytics</CardTitle>
        </CardHeader>
        <CardContent className="space-y-4">
          <p className="text-muted-foreground">View your metrics</p>
          <Button variant="default" className="w-full">
            View Details
          </Button>
        </CardContent>
      </Card>
    </div>
  )
}

替代方案：僅使用 Tailwind

Vite 專案：

npm install -D tailwindcss @tailwindcss/vite

// vite.config.ts
import tailwindcss from '@tailwindcss/vite'
export default { plugins: [tailwindcss()] }

/* src/index.css */
@import "tailwindcss";

元件庫指南

完整的元件目錄，包含使用模式、安裝與組合範例。

請參閱：references/shadcn-components.md

涵蓋：

• 表單與輸入元件（Button、Input、Select、Checkbox、Date Picker、Form 驗證）
• 版面與導覽（Card、Tabs、Accordion、Navigation Menu）
• 覆蓋層與對話框（Dialog、Drawer、Popover、Toast、Command）
• 回饋與狀態（Alert、Progress、Skeleton）
• 顯示元件（Table、Data Table、Avatar、Badge）

主題與自訂

主題設定、CSS 變數、深色模式實作與元件自訂。

請參閱：references/shadcn-theming.md

涵蓋：

• 使用 next-themes 設定深色模式
• CSS 變數系統
• 色彩自訂與調色板
• 元件變體自訂
• 主題切換實作

無障礙模式

ARIA 模式、鍵盤導覽、螢幕閱讀器支援與無障礙元件使用。

請參閱：references/shadcn-accessibility.md

涵蓋：

• Radix UI 無障礙功能
• 鍵盤導覽模式
• 焦點管理
• 螢幕閱讀器宣告
• 表單驗證無障礙

Tailwind 工具

版面、間距、排版、色彩、邊框與陰影的核心工具類別。

請參閱：references/tailwind-utilities.md

涵蓋：

• 版面工具（Flexbox、Grid、定位）
• 間距系統（padding、margin、gap）
• 排版（字型大小、粗細、對齊、行高）
• 色彩與背景
• 邊框與陰影
• 自訂樣式的任意值

響應式設計

行動優先的斷點、響應式工具與適應性版面。

請參閱：references/tailwind-responsive.md

涵蓋：

• 行動優先方法
• 斷點系統（sm、md、lg、xl、2xl）
• 響應式工具模式
• 容器查詢
• 最大寬度查詢
• 自訂斷點

Tailwind 自訂

設定檔結構、自訂工具、外掛與主題擴充。

請參閱：references/tailwind-customization.md

涵蓋：

• @theme 指令用於自訂代碼
• 自訂色彩與字型
• 間距與斷點擴充
• 自訂工具建立
• 自訂變體
• 層級組織（@layer base、components、utilities）
• Apply 指令用於元件提取

視覺設計系統

基於畫布的設計哲學、視覺溝通原則與精緻構圖。

請參閱：references/canvas-design-system.md

涵蓋：

• 設計哲學方法
• 視覺溝通優先於文字
• 系統化模式與構圖
• 色彩、形狀與空間設計
• 極簡文字整合
• 博物館等級執行
• 多頁設計系統

工具腳本

用於元件安裝與設定產生的 Python 自動化。

shadcn_add.py

新增 shadcn/ui 元件並處理相依性：

python scripts/shadcn_add.py button card dialog

tailwind_config_gen.py

產生包含自訂主題的 tailwind.config.js：

python scripts/tailwind_config_gen.py --colors brand:blue --fonts display:Inter

最佳實務

1. 元件組合：從簡單、可組合的基礎元件建構複雜 UI
2. 工具優先樣式：直接使用 Tailwind 類別；僅在真正重複時提取元件
3. 行動優先響應式：從行動樣式開始，疊加響應式變體
4. 無障礙優先：善用 Radix UI 基礎元件，新增焦點狀態，使用語意化 HTML
5. 設計代碼：使用一致的間距比例、色彩調色板、排版系統
6. 深色模式一致性：對所有主題元素套用深色變體
7. 效能：善用自動 CSS 清除，避免動態類別名稱
8. TypeScript：使用完整型別安全以獲得更好的開發體驗
9. 視覺層級：讓構圖引導注意力，有意識地使用間距與色彩
10. 專家工藝：每個細節都很重要——將 UI 視為一門工藝

參考導覽

元件庫

• references/shadcn-components.md - 完整元件目錄
• references/shadcn-theming.md - 主題與自訂
• references/shadcn-accessibility.md - 無障礙模式

樣式系統

• references/tailwind-utilities.md - 核心工具類別
• references/tailwind-responsive.md - 響應式設計
• references/tailwind-customization.md - 設定與擴充

視覺設計

• references/canvas-design-system.md - 設計哲學與畫布工作流程

自動化

• scripts/shadcn_add.py - 元件安裝
• scripts/tailwind_config_gen.py - 設定產生

常見模式

含驗證的表單：

import { useForm } from "react-hook-form"
import { zodResolver } from "@hookform/resolvers/zod"
import * as z from "zod"
import { Form, FormField, FormItem, FormLabel, FormControl, FormMessage } from "@/components/ui/form"
import { Input } from "@/components/ui/input"
import { Button } from "@/components/ui/button"

const schema = z.object({
  email: z.string().email(),
  password: z.string().min(8)
})

export function LoginForm() {
  const form = useForm({
    resolver: zodResolver(schema),
    defaultValues: { email: "", password: "" }
  })

  return (
    <Form {...form}>
      <form onSubmit={form.handleSubmit(console.log)} className="space-y-6">
        <FormField control={form.control} name="email" render={({ field }) => (
          <FormItem>
            <FormLabel>Email</FormLabel>
            <FormControl>
              <Input type="email" {...field} />
            </FormControl>
            <FormMessage />
          </FormItem>
        )} />
        <Button type="submit" className="w-full">Sign In</Button>
      </form>
    </Form>
  )
}

含深色模式的響應式版面：

<div className="min-h-screen bg-white dark:bg-gray-900">
  <div className="container mx-auto px-4 py-8">
    <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
      <Card className="bg-white dark:bg-gray-800 border-gray-200 dark:border-gray-700">
        <CardContent className="p-6">
          <h3 className="text-xl font-semibold text-gray-900 dark:text-white">
            Content
          </h3>
        </CardContent>
      </Card>
    </div>
  </div>
</div>

資源

• shadcn/ui 文件：https://ui.shadcn.com
• Tailwind CSS 文件：https://tailwindcss.com
• Radix UI：https://radix-ui.com
• Tailwind UI：https://tailwindui.com
• Headless UI：https://headlessui.com
• v0（AI UI 產生器）：https://v0.dev