giuseppe-trisciuoglio/developer-kit

tailwind-design-system

Skill for creating and managing a Design System using Tailwind CSS and shadcn/ui.

소스 보기

사용 방법

  1. 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
  2. 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
  3. 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/giuseppe-trisciuoglio/developer-kit --skill tailwind-design-system

시작 전 확인

  • 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
  • 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

Tailwind CSS & shadcn/ui Design System

Overview

Expert guide for creating and managing a centralized Design System using Tailwind CSS (v4.1+) and shadcn/ui. This skill provides structured workflows for defining design tokens, configuring themes with CSS variables, and building a consistent UI component library based on shadcn/ui primitives.

Relationship with other skills:

  • tailwind-css-patterns covers utility-first styling, responsive design, and general Tailwind CSS usage
  • shadcn-ui covers individual component installation, configuration, and implementation
  • This skill focuses on the system-level orchestration: design tokens, theming infrastructure, component wrapping patterns, and ensuring consistency across the entire application

When to Use

  • Setting up a new design system from scratch with Tailwind CSS and shadcn/ui
  • Defining design tokens (colors, typography, spacing, radius, shadows) as CSS variables
  • Configuring globals.css with a centralized theming system (light/dark mode)
  • Wrapping shadcn/ui components into design system primitives with enforced constraints
  • Building a token-driven component library for consistent UI
  • Migrating from a JavaScript-based Tailwind config to CSS-first configuration (v4.1+)
  • Establishing color palettes with oklch format for perceptual uniformity
  • Creating multi-theme support beyond light/dark (e.g., brand themes)

Instructions

Step 1: Initialize Design System Configuration

Run these commands to set up the project:

bash
# Check if Tailwind is installed
npx tailwindcss --version

# For Tailwind v4 (recommended)
npx @tailwindcss/vite@latest init   # or: npm install -D tailwindcss @tailwindcss/vite

# Initialize shadcn/ui CLI
npx shadcn@latest init

# Install core shadcn/ui components
npx shadcn@latest add button card input -y

Validation checkpoint: After setup, verify with:

bash
ls src/components/ui/        # Should list installed components
cat src/app/globals.css       # Should contain @tailwind directives

Step 2: Define Design Tokens

Create src/app/globals.css with your design tokens:

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

@layer base {
  :root {
    /* Brand Colors */
    --primary: oklch(0.55 0.18 250);
    --primary-foreground: oklch(0.985 0 0);

    /* Semantic Colors */
    --background: oklch(0.99 0 0);
    --foreground: oklch(0.15 0 0);
    --secondary: oklch(0.96 0.01 250);
    --secondary-foreground: oklch(0.20 0 0);

    /* Validation: all colors must have foreground pair */
    --destructive: oklch(0.55 0.22 25);
    --destructive-foreground: oklch(0.985 0 0);
  }

  .dark {
    --primary: oklch(0.65 0.20 250);
    --background: oklch(0.14 0 0);
    --foreground: oklch(0.97 0 0);
    --secondary: oklch(0.25 0.02 250);
  }
}

Validation checkpoint: Verify tokens are valid CSS:

bash
grep -E "^[[:space:]]*--[a-z-]+:" src/app/globals.css | wc -l
# Should return count of defined tokens (e.g., 10+)

Step 3: Configure Theming Infrastructure

Bridge CSS variables to Tailwind utilities (Tailwind v4.1+):

css
@theme inline {
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  --color-background: var(--background);
  --color-foreground: var(--foreground);
}

Add dark mode class toggle in components/providers/theme-provider.tsx:

tsx
import { useEffect } from "react";
export function ThemeProvider({ children }: { children: React.ReactNode }) {
  useEffect(() => {
    const isDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
    document.documentElement.classList.toggle("dark", isDark);
  }, []);
  return <>{children}</>;
}

Validation checkpoint: Test dark mode:

bash
document.documentElement.classList.contains("dark") // in browser console

Step 4: Wrap shadcn/ui Components

Create src/components/ds/Button.tsx:

tsx
import { Button as ShadcnButton } from "@/components/ui/button";

type DSVariant = "primary" | "secondary" | "destructive" | "ghost";
const variantMap: Record<DSVariant, "default" | "secondary" | "destructive" | "ghost"> = {
  primary: "default", secondary: "secondary",
  destructive: "destructive", ghost: "ghost",
};

export function Button({ variant = "primary", ...props }: { variant?: DSVariant } & React.ComponentProps<typeof ShadcnButton>) {
  return <ShadcnButton variant={variantMap[variant]} {...props} />;
}

Validation checkpoint: Verify build passes:

bash
npx tsc --noEmit src/components/ds/Button.tsx

Step 5: Validate and Document

Run the token validation script:

bash
REQUIRED=("primary" "primary-foreground" "background" "foreground" "secondary" "secondary-foreground")
for token in "${REQUIRED[@]}"; do
  grep -q "$token:" src/app/globals.css || echo "MISSING: --$token"
done

Validation checkpoint: Ensure all shadcn components use DS tokens:

bash
grep -r "bg-primary\|text-primary\|bg-background" src/components/ds/

Examples

Adding Custom Tokens

Extend the base tokens in globals.css:

css
:root {
  --warning: oklch(0.84 0.16 84);
  --warning-foreground: oklch(0.28 0.07 46);
}

.dark {
  --warning: oklch(0.41 0.11 46);
  --warning-foreground: oklch(0.99 0.02 95);
}

@theme inline {
  --color-warning: var(--warning);
  --color-warning-foreground: var(--warning-foreground);
}

Usage: <div className="bg-warning text-warning-foreground">Warning</div>

Wrapping shadcn/ui Components as Design System Primitives

See references/component-wrapping.md for complete examples including Button, Text, and Stack primitives with full TypeScript types.

Create constrained design system components that enforce token usage. Inline example:

tsx
import { Button as ShadcnButton } from "@/components/ui/button";

export function Button({ variant = "primary", size = "md", ...props }) {
  const variantMap = { primary: "default", secondary: "secondary" };
  const sizeMap = { sm: "sm", md: "default", lg: "lg" };
  return (
    <ShadcnButton
      variant={variantMap[variant]}
      size={sizeMap[size]}
      {...props}
    />
  );
}

Multi-Theme Support

For applications requiring multiple brand themes beyond light/dark:

css
[data-theme="ocean"] {
  --primary: oklch(0.55 0.18 230);
  --primary-foreground: oklch(0.985 0 0);
}

[data-theme="forest"] {
  --primary: oklch(0.50 0.15 145);
  --primary-foreground: oklch(0.985 0 0);
}
tsx
const [theme, setTheme] = useState("light");
useEffect(() => {
  document.documentElement.setAttribute("data-theme", theme);
}, [theme]);

Design Token Validation

Verify all required tokens are defined:

bash
#!/bin/bash
REQUIRED=("--background" "--foreground" "--primary" "--primary-foreground")
for token in "${REQUIRED[@]}"; do
  grep -q "$token:" src/styles/globals.css || echo "Missing: $token"
done

Constraints and Warnings

  • oklch color format: Use oklch for perceptual uniformity. Not all browsers support oklch natively; check compatibility if targeting older browsers
  • Token naming: Follow the shadcn/ui convention (--primary, --primary-foreground) for seamless integration
  • `@`theme inline vs `@`theme: Use @theme inline when bridging CSS variables to Tailwind utilities; use @theme for direct token definition
  • Component wrapping: Keep wrapper components thin. Only add constraints that enforce design system rules; avoid duplicating shadcn/ui logic
  • Dark mode: Always define dark mode values for every token in :root. Missing dark tokens cause visual regressions
  • CSS variable scoping: Tokens defined in :root are global. Use [data-theme] selectors for multi-theme without conflicts
  • Performance: Avoid excessive CSS custom property chains. Each var() lookup adds minimal but non-zero overhead
  • Tailwind v4 vs v3: The @theme directive and @theme inline are v4.1+ features. For v3 projects, use tailwind.config.js with theme.extend

Best Practices

  1. Single source of truth: All design tokens live in globals.css. Never hardcode color values in components
  2. Semantic naming: Use purpose-based names (--primary, --destructive) not appearance-based (--blue-500, --red-600)
  3. Foreground pairing: Every background token must have a matching -foreground token for contrast compliance
  4. Token scale: Define a complete scale for custom palettes (50-950) to provide flexibility
  5. Component barrel exports: Export all DS components from a single index.ts for clean imports
  6. Accessibility: Ensure all token pairs (background/foreground) meet WCAG AA contrast (4.5:1 for text, 3:1 for large text)
  7. Document tokens: Maintain a visual reference of all tokens for the team
  8. Consistent spacing: Use Tailwind's spacing scale (gap-2, gap-4, gap-6) through DS components rather than arbitrary values

References

  • Tailwind CSS v4 Theme Configuration: https://tailwindcss.com/docs/theme
  • Tailwind CSS Functions and Directives: https://tailwindcss.com/docs/functions-and-directives
  • shadcn/ui Theming Guide: https://ui.shadcn.com/docs/theming
  • shadcn/ui Installation (Manual): https://ui.shadcn.com/docs/installation/manual
  • oklch Color Space: https://oklch.com

관련 작업

같은 저장소의 Skills

더 많은 Skills

모든 Skills
giuseppe-trisciuoglio
커뮤니티

drizzle-orm-patterns

Provides comprehensive Drizzle ORM patterns for schema definition, CRUD operations, relations, queries, transactions, and migrations. Proactively use for any Drizzle ORM development including defining database schemas, writing type-safe queries, implementing relations, managing transactions, and setting up migrations with Drizzle Kit. Supports PostgreSQL, MySQL, SQLite, MSSQL, and CockroachDB.

1시간 설치 수
3
GitHub Stars
372
업데이트
9월 10일
giuseppe-trisciuoglio
커뮤니티

tailwind-css-patterns

Provides comprehensive Tailwind CSS utility-first styling patterns including responsive design, layout utilities, flexbox, grid, spacing, typography, colors, and modern CSS best practices. Use when styling React/Vue/Svelte components, building responsive layouts, implementing design systems, or optimizing CSS workflow.

1시간 설치 수
1
GitHub Stars
372
업데이트
9월 10일
giuseppe-trisciuoglio
커뮤니티

dynamodb-toolbox-patterns

Provides TypeScript patterns for DynamoDB-Toolbox v2 including schema/table/entity modeling, .build() command workflow, query/scan access patterns, batch and transaction operations, and single-table design with computed keys. Use when implementing type-safe DynamoDB access layers with DynamoDB-Toolbox v2 in TypeScript services or serverless applications.

1시간 설치 수
1
GitHub Stars
371
업데이트
9월 10일
giuseppe-trisciuoglio
커뮤니티

spring-boot-dependency-injection

Provides dependency injection patterns for Spring Boot projects, including constructor-first design, optional collaborator handling, bean selection, and wiring validation. Use when creating services and configurations, replacing field injection, or troubleshooting ambiguous or fragile Spring wiring.

1시간 설치 수
1
GitHub Stars
371
업데이트
9월 10일