@latte-macchiat-io/latte-vanilla-components 0.0.186 → 0.0.187

package/README.md

@@ -1,22 +1,298 @@
-# latte-vanilla-components
+# 🥤 Latte Vanilla Components
 
-Beautiful components for amazing projects, with a touch of Vanilla 🥤
+Beautiful, type-safe React components powered by Vanilla Extract CSS. Build modern interfaces with a professional design system that's both powerful and easy to use.
 
-## Publish to NPM Registry
+## ✨ Features
 
-Just push changes to the `main` branch and the GitHub Actions workflow will publish the package to the NPM registry.
+- 🎨 **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, great docs
+- 🎯 **Production Ready** - Optimized builds, minimal bundle size
 
-## Run the Storybook
+## 📦 Installation
 
 ```bash
-pnpm run storybook
+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: Zero Config (Quickest)**
+
+```typescript
+// src/styles/theme.css.ts
+import { quickTheme } from '@latte-macchiat-io/latte-vanilla-components';
+export { quickTheme };
+```
+
+**Option B: Brand Colors**
+
+```typescript
+// src/styles/theme.css.ts
+import { createQuickTheme } from '@latte-macchiat-io/latte-vanilla-components';
+
+export const myTheme = createQuickTheme({
+  colors: {
+    primary: '#FF7377', // Your brand color
+    secondary: '#FCEFE6', // Secondary brand color
+  },
+});
+```
+
+**Option C: Professional Custom Theme**
+
+```typescript
+// src/styles/theme.css.ts
+import { createGlobalTheme } from '@vanilla-extract/css';
+import { themeContract } from '@latte-macchiat-io/latte-vanilla-components';
+
+export const lightTheme = 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
+});
+
+export const darkTheme = 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:
+
+```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
+
+```typescript
+{
+  colors: {
+    primary, secondary, accent, background, surface, text,
+    textSecondary, textLight, border, error, warning, success, info
+  },
+  space: { none, xs, sm, md, lg, xl, '2xl' },        // 0px to 128px
+  radii: { none, sm, md, lg, xl, full },             // Border radius
+  fonts: { body, heading, mono },                    // Font families
+  fontSizes: { xs, sm, md, lg, xl, '2xl', '3xl', '4xl' }, // 12px to 40px
+  fontWeights: { light, normal, medium, semibold, bold },
+  lineHeights: { tight, normal, relaxed },
+  shadows: { none, sm, md, lg, xl },                 // Box shadows
+  maxWidth: string,                                  // Container width
+  section: { paddingTop, paddingBottom },           // Section spacing
+  header: { height },                               // Header height
+  footer: { height },                               // Footer height
+}
+```
+
+### 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
+const { createVanillaExtractPlugin } = require('@vanilla-extract/next-plugin');
+const withVanillaExtract = createVanillaExtractPlugin();
+
+module.exports = withVanillaExtract({
+  // your config
+});
+```
+
+### Using with Vite
+
+```typescript
+// vite.config.ts
+import { vanillaExtractPlugin } from '@vanilla-extract/vite-plugin';
+
+export default {
+  plugins: [vanillaExtractPlugin()],
+};
+```
+
+## 📚 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
+
+```tsx
+// Create your own component using the theme
+import { style } from '@vanilla-extract/css';
+import { themeContract } from '@latte-macchiat-io/latte-vanilla-components';
+
+const customButton = style({
+  backgroundColor: themeContract.colors.primary,
+  color: themeContract.colors.background,
+  padding: `${themeContract.space.md} ${themeContract.space.lg}`,
+  borderRadius: themeContract.radii.full,
+});
 ```
-Then open [http://localhost:6006](http://localhost:6006) in your browser.
 
-### Install the package in your project
+## 🎯 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 & Contributing
+
+### Run Storybook
 
 ```bash
-pnpm add @latte-macchiat-io/latte-vanilla-components
+pnpm run storybook
 ```
 
-Enjoy! 🎉
+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. Build beautiful interfaces! ✨

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@latte-macchiat-io/latte-vanilla-components",
-  "version": "0.0.186",
+  "version": "0.0.187",
   "description": "Beautiful components for amazing projects, with a touch of Vanilla 🥤",
   "type": "module",
   "main": "./src/index.ts",
@@ -32,6 +32,7 @@
   "devDependencies": {
     "@chromatic-com/storybook": "^4.1.1",
     "@playwright/test": "^1.50.0",
+    "@storybook/addon-docs": "^9.1.5",
     "@storybook/addon-onboarding": "^9.1.5",
     "@storybook/react-vite": "^9.1.5",
     "@types/node": "^20",
@@ -42,6 +43,7 @@
     "@vanilla-extract/dynamic": "^2.1.5",
     "@vanilla-extract/recipes": "^0.5.7",
     "@vanilla-extract/sprinkles": "^1.6.5",
+    "@vanilla-extract/vite-plugin": "^5.1.1",
     "clsx": "^2.1.1",
     "eslint": "^9.15.0",
     "eslint-config-prettier": "^10.0.1",
@@ -51,8 +53,7 @@
     "prettier": "^3.4.2",
     "storybook": "^9.1.5",
     "typescript": "5.6.3",
-    "typescript-eslint": "^8.21.0",
-    "@storybook/addon-docs": "^9.1.5"
+    "typescript-eslint": "^8.21.0"
   },
   "engines": {
     "node": ">=20.9.0",

package/src/components/Button/stories.tsx

@@ -1,3 +1,4 @@
+import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Button } from './Button';
 import { Section } from '../Section/Section';

package/src/components/Logo/stories.tsx

@@ -1,3 +1,4 @@
+import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 
 import { Logo } from '../../index';

package/src/components/Modal/stories.tsx

@@ -1,3 +1,4 @@
+import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { useState } from 'react';
 import { Modal } from './Modal';

package/src/components/Section/stories.tsx

@@ -1,3 +1,4 @@
+import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Section } from './Section';
 import { Button } from '../Button/Button';