npm package: @foundrykit/tailwind
Description: Tailwind CSS configuration and theme setup for the FoundryKit design system. Provides consistent design tokens, utilities, and styling across all FoundryKit components.
Latest version: 1.0.5

# @foundrykit/tailwind

Tailwind CSS configuration and theme setup for the FoundryKit design system.
Provides consistent design tokens, utilities, and styling across all FoundryKit
components.

## Features

- **Design tokens** - Consistent colors, spacing, typography, and other design
  values
- **Component utilities** - Pre-built utility classes for common component
  patterns
- **Theme integration** - Seamless integration with your existing theme
- **CSS variables** - Modern CSS custom properties for dynamic theming
- **Tailwind v4** - Built for the latest Tailwind CSS version

## Installation

```bash
pnpm add @foundrykit/tailwind
```

## Quick Start

### 1. Import the CSS

In your main CSS file (e.g., `globals.css`):

```css
@import '@foundrykit/tailwind/globals.css';
```

### 2. Use in Components

```tsx
import { Button } from '@foundrykit/primitives/button';

function MyComponent() {
  return (
    <Button className='bg-primary text-primary-foreground hover:bg-primary/90'>
      Click me
    </Button>
  );
}
```

## Design Tokens

### Colors

The package provides a comprehensive color system:

```css
/* Primary colors */
--color-primary: 222.2 84% 4.9%;
--color-primary-foreground: 210 40% 98%;

/* Secondary colors */
--color-secondary: 210 40% 96%;
--color-secondary-foreground: 222.2 84% 4.9%;

/* Accent colors */
--color-accent: 210 40% 96%;
--color-accent-foreground: 222.2 84% 4.9%;

/* Semantic colors */
--color-destructive: 0 84.2% 60.2%;
--color-destructive-foreground: 210 40% 98%;
--color-muted: 210 40% 96%;
--color-muted-foreground: 215.4 16.3% 46.9%;
--color-border: 214.3 31.8% 91.4%;
--color-input: 214.3 31.8% 91.4%;
--color-ring: 222.2 84% 4.9%;
--color-background: 0 0% 100%;
--color-foreground: 222.2 84% 4.9%;
```

### Spacing

Consistent spacing scale:

```css
--spacing-0: 0px;
--spacing-1: 0.25rem;
--spacing-2: 0.5rem;
--spacing-3: 0.75rem;
--spacing-4: 1rem;
--spacing-5: 1.25rem;
--spacing-6: 1.5rem;
--spacing-8: 2rem;
--spacing-10: 2.5rem;
--spacing-12: 3rem;
--spacing-16: 4rem;
--spacing-20: 5rem;
--spacing-24: 6rem;
--spacing-32: 8rem;
--spacing-40: 10rem;
--spacing-48: 12rem;
--spacing-56: 14rem;
--spacing-64: 16rem;
```

### Typography

Typography tokens for consistent text styling:

```css
/* Font families */
--font-sans: ui-sans-serif, system-ui, sans-serif;
--font-serif: ui-serif, Georgia, serif;
--font-mono: ui-monospace, SFMono-Regular, monospace;

/* Font sizes */
--font-size-xs: 0.75rem;
--font-size-sm: 0.875rem;
--font-size-base: 1rem;
--font-size-lg: 1.125rem;
--font-size-xl: 1.25rem;
--font-size-2xl: 1.5rem;
--font-size-3xl: 1.875rem;
--font-size-4xl: 2.25rem;
--font-size-5xl: 3rem;
--font-size-6xl: 3.75rem;

/* Font weights */
--font-weight-thin: 100;
--font-weight-extralight: 200;
--font-weight-light: 300;
--font-weight-normal: 400;
--font-weight-medium: 500;
--font-weight-semibold: 600;
--font-weight-bold: 700;
--font-weight-extrabold: 800;
--font-weight-black: 900;
```

### Border Radius

Consistent border radius values:

```css
--radius-none: 0px;
--radius-sm: 0.125rem;
--radius-base: 0.25rem;
--radius-md: 0.375rem;
--radius-lg: 0.5rem;
--radius-xl: 0.75rem;
--radius-2xl: 1rem;
--radius-3xl: 1.5rem;
--radius-full: 9999px;
```

## Usage

### Basic Styling

```tsx
import { Button } from '@foundrykit/primitives/button';

function StyledButton() {
  return (
    <Button
      className='
      bg-primary text-primary-foreground 
      hover:bg-primary/90 
      rounded-md px-4 py-2 
      font-medium transition-colors
    '
    >
      Styled Button
    </Button>
  );
}
```

### Using Design Tokens

```tsx
function Card() {
  return (
    <div
      className='
      bg-background text-foreground
      border-border rounded-lg border
      p-6 shadow-sm
    '
    >
      <h3 className='mb-2 text-lg font-semibold'>Card Title</h3>
      <p className='text-muted-foreground'>Card content goes here</p>
    </div>
  );
}
```

### Responsive Design

```tsx
function ResponsiveComponent() {
  return (
    <div
      className='
      grid grid-cols-1 gap-4 p-4
      md:grid-cols-2 md:gap-6 md:p-6
      lg:grid-cols-3 lg:gap-8 lg:p-8
    '
    >
      {/* Content */}
    </div>
  );
}
```

### Dark Mode Support

```tsx
function ThemeAwareComponent() {
  return (
    <div
      className='
      bg-background text-foreground
      dark:bg-background dark:text-foreground
      border-border dark:border-border border
    '
    >
      <p className='text-muted-foreground dark:text-muted-foreground'>
        This component adapts to light and dark themes
      </p>
    </div>
  );
}
```

## Customization

### Extending the Theme

Create your own `globals.css` to extend the theme:

```css
@import '@foundrykit/tailwind/globals.css';

/* Custom design tokens */
:root {
  --color-brand: 220 14% 96%;
  --color-brand-foreground: 220 9% 46%;

  --font-size-custom: 1.1rem;
  --spacing-custom: 1.75rem;
}

/* Custom utilities */
@utility custom-button {
  @apply bg-brand text-brand-foreground px-custom rounded-md py-2;
}
```

### Component-Specific Styles

```css
/* Custom component styles */
@utility button-primary {
  @apply bg-primary text-primary-foreground hover:bg-primary/90;
}

@utility button-secondary {
  @apply bg-secondary text-secondary-foreground hover:bg-secondary/80;
}

@utility card-elevated {
  @apply bg-background border-border rounded-lg border shadow-lg;
}
```

### Custom Color Palette

```css
/* Define custom colors */
:root {
  --color-custom-blue: 221 83% 53%;
  --color-custom-green: 142 76% 36%;
  --color-custom-purple: 262 83% 58%;
}

/* Use in components */
.custom-button {
  background-color: hsl(var(--color-custom-blue));
  color: white;
}
```

## Integration with Frameworks

### Next.js

In your `app/globals.css`:

```css
@import '@foundrykit/tailwind/globals.css';

/* Your custom styles */
```

### React (Vite)

In your `src/index.css`:

```css
@import '@foundrykit/tailwind/globals.css';

/* Your custom styles */
```

### Vue

In your `src/assets/main.css`:

```css
@import '@foundrykit/tailwind/globals.css';

/* Your custom styles */
```

## Performance

### Optimized Bundle

- Tree-shakable CSS
- Minimal runtime overhead
- Efficient class generation
- Optimized for Tailwind v4

### Best Practices

```tsx
// ✅ Good - Use semantic class names
<div className="bg-background text-foreground p-4 rounded-lg">

// ❌ Avoid - Hard-coded values
<div className="bg-white text-black p-4 rounded-lg">
```

## Migration from Tailwind v3

If you're migrating from Tailwind v3:

1. **Update imports** - Use the new CSS import syntax
2. **Remove config files** - Tailwind v4 uses CSS-based configuration
3. **Update class names** - Some utilities may have changed
4. **Test thoroughly** - Verify all styles work as expected

## Contributing

When contributing to the Tailwind package:

1. Follow the design token naming conventions
2. Ensure accessibility compliance
3. Test with both light and dark themes
4. Update this README
5. Maintain backward compatibility

## License

MIT