@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

pnpm add @foundrykit/tailwind

Quick Start

1. Import the CSS

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

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

2. Use in Components

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:

/* 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:

--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:

/* 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:

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

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

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

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

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:

@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

/* 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

/* 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:

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

/* Your custom styles */

React (Vite)

In your src/index.css:

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

/* Your custom styles */

Vue

In your src/assets/main.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

// ✅ 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