MCP HubMCP Hub
← Back to Skills

setup-tailwind-typescript

pjt222
Updated 5 days ago
8 views
17
2
17
View on GitHub
Designreactaidesign

About

This skill configures Tailwind CSS with TypeScript for Next.js/React projects, handling installation, theme customization, and type-safe utilities. Use it when adding Tailwind to TypeScript projects or establishing type-safe styling patterns. It covers configuration, plugin setup, and component styling with full TypeScript integration.

Quick Install

Claude Code

Recommended
Primary
npx skills add pjt222/agent-almanac -a claude-code
Plugin CommandAlternative
/plugin add https://github.com/pjt222/agent-almanac
Git CloneAlternative
git clone https://github.com/pjt222/agent-almanac.git ~/.claude/skills/setup-tailwind-typescript

Copy and paste this command in Claude Code to install this skill

Documentation

設置 Tailwind CSS 與 TypeScript

於 TypeScript 項目中配置 Tailwind CSS，含自訂主題、工具與型別安全模式。

適用時機

  • 為既有 TypeScript 項目加入 Tailwind CSS
  • 為項目設計系統自訂 Tailwind 主題
  • 設置型別安全之元件樣式模式
  • 配置 Tailwind 外掛與擴展

輸入

  • 必要：TypeScript 項目（Next.js、Vite 或獨立 React）
  • 選擇性：設計系統 token（顏色、間距、字體）
  • 選擇性：欲納入之 Tailwind 外掛

步驟

步驟一：安裝 Tailwind CSS

npm install -D tailwindcss @tailwindcss/postcss postcss

對 Next.js（若未含）：

npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

預期： tailwindcss、postcss 與 autoprefixer 已作為開發依賴安裝。對 Next.js，tailwind.config.ts 與 postcss.config.js 由 npx tailwindcss init -p 產生。

失敗時： 若 npx tailwindcss init 失敗，先以 npm install -D tailwindcss 安裝 Tailwind 再重試。若用 monorepo，自應用根目錄而非工作區根執行命令。

步驟二：配置 tailwind.config.ts

import type { Config } from "tailwindcss";

const config: Config = {
  content: [
    "./src/pages/**/*.{js,ts,jsx,tsx,mdx}",
    "./src/components/**/*.{js,ts,jsx,tsx,mdx}",
    "./src/app/**/*.{js,ts,jsx,tsx,mdx}",
  ],
  theme: {
    extend: {
      colors: {
        primary: {
          50: "#eff6ff",
          100: "#dbeafe",
          500: "#3b82f6",
          600: "#2563eb",
          700: "#1d4ed8",
          900: "#1e3a5f",
        },
        secondary: {
          500: "#6366f1",
          600: "#4f46e5",
        },
      },
      fontFamily: {
        sans: ["Inter", "system-ui", "sans-serif"],
        mono: ["JetBrains Mono", "monospace"],
      },
      spacing: {
        "18": "4.5rem",
        "88": "22rem",
      },
    },
  },
  plugins: [],
};

export default config;

預期： tailwind.config.ts 之 content 陣列符合項目文件位置，theme.extend 下有自訂顏色與字體，並以 Config 引入作適當之 TypeScript 類型化。

失敗時： 若自訂類別未渲染，驗證 content 路徑符合實際目錄結構。路徑為相對項目根之 glob 模式。缺路徑意指 Tailwind 不掃描該等文件之類別使用。

步驟三：設置全域樣式

編輯 src/app/globals.css：

@tailwind base;
@tailwind components;
@tailwind utilities;

@layer base {
  html {
    @apply antialiased;
  }

  body {
    @apply bg-white text-gray-900 dark:bg-gray-950 dark:text-gray-100;
  }
}

@layer components {
  .btn-primary {
    @apply bg-primary-600 text-white px-4 py-2 rounded-lg
           hover:bg-primary-700 focus:outline-none focus:ring-2
           focus:ring-primary-500 focus:ring-offset-2
           transition-colors duration-200;
  }
}

預期： globals.css 含三 Tailwind 指令（@tailwind base、@tailwind components、@tailwind utilities）加任何自訂之 base 與 component 層樣式。文件已於根佈局中引入。

失敗時： 若樣式未套用，驗證 globals.css 已於 layout.tsx（或 Pages Router 之 _app.tsx）中引入。檢查 Tailwind 指令存在且未被註解。

步驟四：建立型別安全之工具輔助

建立 src/lib/cn.ts：

import { type ClassValue, clsx } from "clsx";
import { twMerge } from "tailwind-merge";

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

安裝依賴：

npm install clsx tailwind-merge

於元件中之用法：

import { cn } from "@/lib/cn";

interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: "primary" | "secondary" | "outline";
}

export function Button({ className, variant = "primary", ...props }: ButtonProps) {
  return (
    <button
      className={cn(
        "px-4 py-2 rounded-lg font-medium transition-colors",
        variant === "primary" && "bg-primary-600 text-white hover:bg-primary-700",
        variant === "secondary" && "bg-secondary-500 text-white hover:bg-secondary-600",
        variant === "outline" && "border border-gray-300 hover:bg-gray-50",
        className
      )}
      {...props}
    />
  );
}

預期： src/lib/cn.ts 匯出 cn() 函數。clsx 與 tailwind-merge 已作為依賴安裝。元件用 cn() 合併類別名而無衝突。

失敗時： 若找不到 clsx 或 tailwind-merge，執行 npm install clsx tailwind-merge。若 TypeScript 於 cn.ts 報類型錯誤，驗證 ClassValue 類型自 clsx 引入。

步驟五：加入暗模式支援

更新 tailwind.config.ts：

const config: Config = {
  darkMode: "class", // or "media" for system preference
  // ... rest of config
};

切換實作：

"use client";
import { useEffect, useState } from "react";

export function ThemeToggle() {
  const [dark, setDark] = useState(false);

  useEffect(() => {
    document.documentElement.classList.toggle("dark", dark);
  }, [dark]);

  return (
    <button onClick={() => setDark(!dark)}>
      {dark ? "Light" : "Dark"} Mode
    </button>
  );
}

預期： 暗模式於明暗主題間正確切換。dark 類別套用於 <html> 元素，dark: 前綴之工具類別對應響應。

失敗時： 若暗模式不切換，驗證 tailwind.config.ts 中 darkMode: "class" 已設。確保 dark 類別於 <html> 元素（非 <body>）切換。對系統偏好模式，改用 darkMode: "media"。

步驟六：加入外掛（選擇性）

npm install -D @tailwindcss/typography @tailwindcss/forms

// tailwind.config.ts
import typography from "@tailwindcss/typography";
import forms from "@tailwindcss/forms";

const config: Config = {
  // ...
  plugins: [typography, forms],
};

預期： 外掛已作為開發依賴安裝並於 tailwind.config.ts 之 plugins 陣列註冊。外掛提供之類別（如 typography 之 prose、forms 之樣式表單元素）於元件中可用。

失敗時： 若外掛類別未渲染，驗證外掛已安裝（npm ls @tailwindcss/typography）且加入 plugins 陣列。配置變更後重啟開發伺服器。

驗證

  • Tailwind 類別於瀏覽器中正確渲染
  • 自訂主題值（顏色、字體、間距）運作
  • cn() 工具合併類別而無衝突
  • 暗模式正確切換
  • TypeScript 於配置或元件中無錯
  • 生產建構清除未用樣式

常見陷阱

  • content 路徑缺失：若類別未渲染，檢查配置中之 content 陣列符合文件位置
  • 類別衝突：用 tailwind-merge（經 cn()）以防止衝突之工具類別
  • 自訂值不運作：確保自訂值於 extend 下（以加入）而非主題根（其取代預設）
  • 暗模式不切換：檢查 darkMode 設定及 dark 類別於 <html> 而非 <body>

相關技能

  • scaffold-nextjs-app - Tailwind 配置前之項目設置
  • deploy-to-vercel - 部署已樣式之應用

GitHub Repository

pjt222/agent-almanac
Path: i18n/wenyan-lite/skills/setup-tailwind-typescript
0
agentsagentskillsai-assisted-developmentclaude-codeskillsteams

Related Skills

executing-plans

Design

Use the executing-plans skill when you have a complete implementation plan to execute in controlled batches with review checkpoints. It loads and critically reviews the plan, then executes tasks in small batches (default 3 tasks) while reporting progress between each batch for architect review. This ensures systematic implementation with built-in quality control checkpoints.

View skill

requesting-code-review

Design

This skill dispatches a code-reviewer subagent to analyze code changes against requirements before proceeding. It should be used after completing tasks, implementing major features, or before merging to main. The review helps catch issues early by comparing the current implementation with the original plan.

View skill

connect-mcp-server

Design

This skill provides a comprehensive guide for developers to connect MCP servers to Claude Code using HTTP, stdio, or SSE transports. It covers installation, configuration, authentication, and security for integrating external services like GitHub, Notion, and custom APIs. Use it when setting up MCP integrations, configuring external tools, or working with Claude's Model Context Protocol.

View skill

web-cli-teleport

Design

This skill helps developers choose between Claude Code Web and CLI interfaces based on task analysis, then enables seamless session teleportation between these environments. It optimizes workflow by managing session state and context when switching between web, CLI, or mobile. Use it for complex projects requiring different tools at various stages.

View skill