ElKrapulito/calucha-landing

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 框架
• 建置時處理，零執行時期開銷
• 行動優先的響應式設計
• 一致的設計權杖（顏色、間距、排版）
• 自動死碼消除

視覺設計層：Canvas

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

快速開始

元件 + 樣式設定

安裝 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