npm package: @latte-macchiat-io/latte-vanilla-components
Description: Beautiful components for amazing projects, with a touch of Vanilla 🥤
Latest version: 0.0.553

# 🥤 Latte Vanilla Components [![npm version](https://img.shields.io/npm/v/@latte-macchiat-io/latte-vanilla-components?style=flat-square)](https://www.npmjs.com/package/@latte-macchiat-io/latte-vanilla-components)

Beautiful, type-safe React components powered by Vanilla Extract CSS for amazing projects, with a touch of Vanilla 🥤

Intended for internal use by the 👩‍💻🧑‍💻 [latte-macchiat.io](https://latte-macchiat.io) team, we can't offer official support, but feel free to reach out
with questions, feedback or project ideas!

## ✨ Features

- 🎨 **Professional Theme System** - Light/dark themes with full customization
- 🚀 **Zero Runtime CSS-in-JS** - Vanilla Extract for optimal performance
- 📱 **Responsive Design** - Mobile-first, accessible components
- 🔒 **Type Safety** - Full TypeScript support throughout
- ⚡ **Developer Experience** - Hot reloading, IntelliSense, documentation
- 🎯 **Production Ready** - Optimized builds, minimal bundle size

## 🤓 Philosophy

This library is shipped as raw code (ESM + TypeScript) to be compiled in your project, allowing full
customization and tree-shaking. It is not a pre-built design system, but rather a set of building blocks
to create your own unique designs.

You will need to set up Vanilla Extract in your build system (Next.js, Vite, etc.) to use this library.

## 📦 Installation

```bash
npm install @latte-macchiat-io/latte-vanilla-components
# or
pnpm add @latte-macchiat-io/latte-vanilla-components
# or
yarn add @latte-macchiat-io/latte-vanilla-components
```

## 🚀 Quick Start

### 1. Set up your theme (choose one approach):

**Option A: Reuse default theme**

```typescript
// src/styles/theme.css.ts
import { createDarkTheme, createLightTheme } from "@latte-macchiat-io/latte-vanilla-components";

// Create and apply the default light theme (minimal setup)
createLightTheme();

// Optional: enable dark theme support
createDarkTheme();
```

**Option B: Customize partially themes**

```typescript
// src/styles/theme.css.ts
import { createDarkTheme, createLightTheme } from '@latte-macchiat-io/latte-vanilla-components';

// Override only specific properties in light and dark themes
createLightTheme({
  colors: {
    background: '#f0f0f0', // Custom light background color
    text: '#333333',      // Custom light text color
  },
  fonts: {
    body: 'Arial, sans-serif', // Custom font for body
  },
  fontSizes: {
    md: '18px', // Custom medium font size
  },
});

// Optional: customize dark theme as well
createDarkTheme({
  colors: {
    background: '#121212', // Custom dark background color
    text: '#e0e0e0',      // Custom dark text color
  },

});
```

**Option C: Full Custom Theme (= contract redefinition)**

```typescript
// src/styles/theme.css.ts
import { createGlobalTheme } from '@vanilla-extract/css';
import { themeContract } from '@latte-macchiat-io/latte-vanilla-components';

createGlobalTheme(':root', themeContract, {
  colors: {
    primary: '#FF7377',
    background: '#ffffff',
    text: '#000000',
    // ... define all colors
  },
  space: {
    xs: '4px',
    sm: '8px',
    md: '16px',
    // ... define all spacing
  },
  // ... define all theme properties
});

createGlobalTheme('html[data-theme="dark"]', themeContract, {
  colors: {
    primary: '#FF7377',
    background: '#1a1a1a',
    text: '#ffffff',
    // ... dark theme colors
  },
  // ... same structure as light theme
});
```

### 2. Import your theme globally:

```typescript
// src/app/layout.tsx (Next.js)
import '../styles/theme.css';

// src/main.tsx (Vite)
import './styles/theme.css';
```

### 3. Start using components:

```tsx
import { Button, Section, Header, Modal } from '@latte-macchiat-io/latte-vanilla-components';

export default function App() {
  return (
    <Section>
      <Header>
        <h1>My App</h1>
      </Header>

      <Button variant="primary" size="large">
        Get Started
      </Button>

      <Modal>
        <p>Beautiful, accessible modal content!</p>
      </Modal>
    </Section>
  );
}
```

## 🎨 Theme Customization

### Available Theme Properties

- [ ] TODO @Gaelle

### Theme Switching

Add dark mode support:

```tsx
import { setTheme, toggleTheme } from '@latte-macchiat-io/latte-vanilla-components';

function ThemeToggle() {
  return <button onClick={() => toggleTheme()}>Toggle Dark Mode</button>;
}

// Or set specific theme
setTheme('dark'); // Switch to dark
setTheme('light'); // Switch to light
```

## 🧩 Available Components

### Layout Components

- **Section** - Content sections with consistent spacing
- **Header** - App headers with navigation support
- **Footer** - App footers with links and info
- **Main** - Main content areas
- **Columns** - Responsive column layouts

### Interactive Components

- **Button** - Primary, secondary, and variant buttons
- **Modal** - Accessible modals with animations
- **Form** - Complete form system with validation
- **TextField** - Text inputs with labels and validation
- **Carousel** - Image and content carousels

### Content Components

- **Video** - Responsive video players
- **VideoFullWidth** - Full-width video backgrounds
- **Logo** - Responsive logo display
- **Icon** - Icon system with multiple sizes
- **KeyNumber** - Highlight important numbers/stats

### Navigation Components

- **Nav** - Primary navigation
- **NavSocial** - Social media links
- **NavLegal** - Legal/policy links
- **LanguageSwitcher** - Multi-language support

### Utility Components

- **Actions** - Action button groups
- **ConsentCookie** - GDPR cookie consent

## 📱 Responsive Design

All components are mobile-first and responsive:

```tsx
// Responsive spacing using sprinkles
<Section className={sprinkles({
  padding: { mobile: 'md', desktop: 'xl' }
})}>
  Content adapts to screen size
</Section>

// Built-in responsive variants
<Button size={{ mobile: 'small', desktop: 'large' }}>
  Responsive Button
</Button>
```

## 🛠 Development

### Using with Next.js

```typescript
// next.config.js
import type { NextConfig } from "next";
import { createVanillaExtractPlugin } from "@vanilla-extract/next-plugin";

const nextConfig: NextConfig = {
  /* config options here */
  transpilePackages: ['@latte-macchiat-io/latte-vanilla-components']
};

const withVanillaExtract = createVanillaExtractPlugin({
  identifiers: process.env.NODE_ENV === 'production' ? 'short' : 'debug',
});

export default withVanillaExtract(nextConfig);

```

### Using with Vite

```typescript
// vite.config.ts
import { vanillaExtractPlugin } from '@vanilla-extract/vite-plugin';

export default {
  plugins: [vanillaExtractPlugin()],
  optimizeDeps: {
    exclude: ['@latte-macchiat-io/latte-vanilla-components'],
  },
};
```

## 📚 Advanced Usage

### Custom Component Styling

```tsx
import { sprinkles } from '@latte-macchiat-io/latte-vanilla-components';

// Use the sprinkles utility for custom styling
<div
  className={sprinkles({
    padding: 'lg',
    backgroundColor: 'primary',
    borderRadius: 'md',
    color: 'white',
  })}>
  Custom styled element
</div>;
```

### Extending Components

Create your own custom components using the theme contract and `styleOverride` for guaranteed specificity:

```tsx
// src/components/CustomButton/styles.css.ts
import { styleOverride } from '@latte-macchiat-io/latte-vanilla-components/utils/styleOverride';
import { themeContract } from '@latte-macchiat-io/latte-vanilla-components';

export const customButton = styleOverride({
  backgroundColor: themeContract.colors.primary,
  color: themeContract.colors.background,
  padding: `${themeContract.space.md} ${themeContract.space.lg}`,
  borderRadius: themeContract.radii.full,
  transition: 'all 0.2s ease',
  ':hover': {
    backgroundColor: themeContract.colors.secondary,
  },
});
```

```tsx
// src/components/CustomButton/index.tsx
import { customButton } from './styles.css';

export function CustomButton({ children, ...props }) {
  return (
    <button className={customButton} {...props}>
      {children}
    </button>
  );
}
```

## 🎯 Performance

- **Zero Runtime CSS-in-JS** - All styles compiled at build time
- **Atomic CSS** - Reusable utility classes reduce bundle size
- **Tree Shaking** - Only import components you use
- **Optimized Builds** - Minimal CSS output in production

---

## 🛠 Development & storybook testing

### Run Storybook

```bash
pnpm run storybook
```

Then open [http://localhost:6006](http://localhost:6006) to explore components.

### Publishing

Push changes to `main` branch and GitHub Actions will automatically publish to NPM.

---

Made with ❤️ by the Latte team 🥤