pos-system/microservices/.agent/skills/tailwind-design-system/SKILL.md

---
name: tailwind-design-system
description: Tailwind CSS 4 design system patterns cho GoodGo frontends. Use for CSS variables theming, dark mode, glassmorphism, brand colors, typography, và responsive patterns.
compatibility: "tailwindcss>=4, postcss>=8"
metadata:
  author: Velik Ho
  version: "1.0"
---

# Tailwind Design System / Hệ Thống Design Tailwind

## When to Use This Skill / Khi Nào Sử Dụng

Use this skill when:
- Creating design tokens / Tạo design tokens
- Implementing dark mode / Triển khai dark mode
- Using glassmorphism effects / Sử dụng glassmorphism
- Working with brand colors / Làm việc với brand colors
- Building responsive layouts / Xây dựng layouts responsive

## Core Concepts / Khái Niệm Cốt Lõi

### CSS Variables First (Tailwind CSS 4)

Tailwind CSS 4 uses CSS-first configuration with `@theme` directive.

```css
/* src/styles/theme.css */
@theme {
  /* Color tokens */
  --color-bg-primary: #0a0a0a;
  --color-bg-secondary: #141414;
  --color-text-primary: #fafafa;
  --color-accent-primary: #3b82f6;
  
  /* Spacing */
  --space-1: 0.25rem;
  --space-2: 0.5rem;
  --space-4: 1rem;
  
  /* Border radius */
  --radius-md: 0.5rem;
  --radius-lg: 0.75rem;
}
```

## Key Patterns / Mẫu Chính

### Color Tokens

```javascript
// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        bg: {
          primary: 'var(--bg-primary)',
          secondary: 'var(--bg-secondary)',
          tertiary: 'var(--bg-tertiary)',
          elevated: 'var(--bg-elevated)',
        },
        text: {
          primary: 'var(--text-primary)',
          secondary: 'var(--text-secondary)',
          tertiary: 'var(--text-tertiary)',
        },
        accent: {
          primary: 'var(--accent-primary)',
          success: 'var(--accent-success)',
          warning: 'var(--accent-warning)',
          error: 'var(--accent-error)',
        },
        brand: {
          primary: {
            DEFAULT: 'var(--brand-primary)',
            light: 'var(--brand-primary-light)',
            dark: 'var(--brand-primary-dark)',
          },
        },
      },
    },
  },
};
```

### Dark Mode Pattern

```css
/* theme.css */
:root {
  --bg-primary: #ffffff;
  --text-primary: #1a1a1a;
}

[data-theme="dark"] {
  --bg-primary: #0a0a0a;
  --text-primary: #fafafa;
}
```

```javascript
// tailwind.config.js
module.exports = {
  darkMode: ['class', '[data-theme="dark"]'],
  // ...
};
```

```tsx
// Usage in component
<div className="bg-bg-primary text-text-primary">
  {/* Automatically adapts to theme */}
</div>
```

### Glassmorphism Utilities

```javascript
// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        glass: {
          bg: 'var(--glass-bg-default)',
          'bg-subtle': 'var(--glass-bg-subtle)',
          'bg-hover': 'var(--glass-bg-hover)',
          border: 'var(--glass-border-default)',
        },
      },
      backdropBlur: {
        glass: 'var(--glass-blur-md)',
        'glass-lg': 'var(--glass-blur-lg)',
      },
      boxShadow: {
        glass: 'var(--glass-shadow-md)',
        'glass-lg': 'var(--glass-shadow-lg)',
      },
    },
  },
  plugins: [
    function({ addUtilities }) {
      addUtilities({
        '.glass-panel': {
          background: 'var(--glass-bg-default)',
          'backdrop-filter': 'blur(var(--glass-blur-md))',
          border: '1px solid var(--glass-border-default)',
          'box-shadow': 'var(--glass-shadow-md)',
        },
      });
    },
  ],
};
```

```tsx
// Usage
<div className="glass-panel rounded-lg p-4">
  Glassmorphism effect
</div>

// Or custom glass
<div className="bg-glass-bg backdrop-blur-glass border border-glass-border shadow-glass rounded-xl">
  Custom glass
</div>
```

### Typography Scale

```javascript
// tailwind.config.js
fontSize: {
  'xs': ['var(--text-xs)', { lineHeight: '1.5' }],
  'sm': ['var(--text-sm)', { lineHeight: '1.5' }],
  'base': ['var(--text-base)', { lineHeight: '1.5' }],
  'lg': ['var(--text-lg)', { lineHeight: '1.5' }],
  'xl': ['var(--text-xl)', { lineHeight: '1.4' }],
  '2xl': ['var(--text-2xl)', { lineHeight: '1.3' }],
  '3xl': ['var(--text-3xl)', { lineHeight: '1.2' }],
},
fontWeight: {
  normal: 'var(--font-normal)',
  medium: 'var(--font-medium)',
  semibold: 'var(--font-semibold)',
  bold: 'var(--font-bold)',
},
```

### Spacing Scale

```javascript
// tailwind.config.js
spacing: {
  '0': 'var(--space-0)',
  '1': 'var(--space-1)',
  '2': 'var(--space-2)',
  '3': 'var(--space-3)',
  '4': 'var(--space-4)',
  '6': 'var(--space-6)',
  '8': 'var(--space-8)',
  '12': 'var(--space-12)',
  '16': 'var(--space-16)',
  'sidebar': 'var(--sidebar-width)',
},
```

### Animation Tokens

```javascript
// tailwind.config.js
transitionTimingFunction: {
  smooth: 'var(--motion-ease-smooth)',
  glide: 'var(--motion-ease-glide)',
},
transitionDuration: {
  instant: 'var(--motion-duration-instant)',
  quick: 'var(--motion-duration-quick)',
  normal: 'var(--motion-duration-normal)',
},
```

### Responsive Patterns

```tsx
// Mobile-first responsive
<div className="
  p-4 md:p-6 lg:p-8
  text-base md:text-lg
  grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3
  gap-4 md:gap-6
">
  {/* Content */}
</div>

// Container pattern
<div className="max-w-container-lg mx-auto px-4 md:px-6">
  {/* Centered content */}
</div>
```

### Brand Gradients

```javascript
// tailwind.config.js
backgroundImage: {
  'brand-gradient': 'var(--brand-gradient-primary)',
  'brand-gradient-accent': 'var(--brand-gradient-accent)',
},
```

```tsx
// Usage
<button className="bg-brand-gradient text-white">
  Gradient Button
</button>
```

## Common Mistakes / Lỗi Thường Gặp

### 1. Hardcoding Colors

```tsx
// ❌ BAD: Hardcoded color
<div className="bg-[#1a1a1a] text-[#fafafa]">

// ✅ GOOD: Use design tokens
<div className="bg-bg-primary text-text-primary">
```

### 2. Not Using CSS Variables

```css
/* ❌ BAD: Static values */
.button { background: #3b82f6; }

/* ✅ GOOD: CSS variables for theming */
.button { background: var(--accent-primary); }
```

### 3. Inconsistent Spacing

```tsx
// ❌ BAD: Arbitrary values
<div className="p-[13px] m-[7px]">

// ✅ GOOD: Use spacing scale
<div className="p-3 m-2">
```

## Quick Reference / Tham Chiếu Nhanh

| Token | Usage |
|-------|-------|
| `bg-bg-*` | Background colors |
| `text-text-*` | Text colors |
| `bg-accent-*` | Accent backgrounds |
| `border-border-*` | Border colors |
| `glass-panel` | Glassmorphism preset |
| `bg-brand-gradient` | Brand gradient |
| `backdrop-blur-glass` | Glass blur |
| `shadow-glass` | Glass shadow |

## Resources / Tài Nguyên

- [React UI Components](../react-ui-components/SKILL.md) - Component patterns
- [Tailwind CSS Docs](https://tailwindcss.com/docs)
- [Design Tokens Spec](https://design-tokens.github.io/community-group/format/)