zabi-components 5.0.22 → 7.0.0

package/THEME.md

@@ -0,0 +1,473 @@
+# Zabi Components Theme Guide
+
+Complete guide to using and customizing the Zabi Components theme system with Tailwind CSS v4.
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Theme Files](#theme-files)
+- [Import Options](#import-options)
+- [Theme Extension](#theme-extension)
+- [Dark Mode](#dark-mode)
+- [Color System](#color-system)
+- [Customization Examples](#customization-examples)
+- [Common Pitfalls](#common-pitfalls)
+
+## Quick Start
+
+### Basic Setup (Standalone)
+
+If you don't have Tailwind CSS set up yet:
+
+```css
+/* app.css */
+@import 'zabi-components/theme';
+@import 'zabi-components/dist/zabi-components.css';
+```
+
+### Setup with Existing Tailwind
+
+If you already have Tailwind CSS configured:
+
+```css
+/* app.css */
+@import "tailwindcss";
+@import 'zabi-components/theme-only';
+@import 'zabi-components/dist/zabi-components.css';
+```
+
+### With Dark Mode
+
+```css
+/* app.css */
+@import "tailwindcss";
+@import 'zabi-components/theme-only';
+@import 'zabi-components/theme-dark-only';
+@import 'zabi-components/dist/zabi-components.css';
+```
+
+## Theme Files
+
+Zabi Components provides multiple theme file variants:
+
+| File | Description | Use Case |
+|------|-------------|----------|
+| `zabi-components/theme` | Full theme with Tailwind import | Standalone projects |
+| `zabi-components/theme-only` | Theme without Tailwind import | Projects with existing Tailwind |
+| `zabi-components/theme-dark` | Dark mode with Tailwind import | Standalone + dark mode |
+| `zabi-components/theme-dark-only` | Dark mode without Tailwind import | Existing Tailwind + dark mode |
+
+### Direct Path Imports
+
+You can also import using direct paths:
+
+```css
+@import 'zabi-components/dist/zabi-components-theme.css';
+@import 'zabi-components/dist/zabi-components-theme-only.css';
+@import 'zabi-components/dist/zabi-components-theme-dark.css';
+@import 'zabi-components/dist/zabi-components-theme-dark-only.css';
+```
+
+## Import Options
+
+### Option 1: Standalone (No Existing Tailwind)
+
+Best for new projects or projects without Tailwind:
+
+```css
+@import 'zabi-components/theme';
+@import 'zabi-components/theme-dark'; /* Optional: for dark mode */
+@import 'zabi-components/dist/zabi-components.css';
+```
+
+**Pros:**
+- Simple setup
+- No Tailwind configuration needed
+- Everything included
+
+**Cons:**
+- Less control over Tailwind configuration
+- Slightly larger bundle if you need custom Tailwind config
+
+### Option 2: With Existing Tailwind
+
+Best for projects already using Tailwind CSS:
+
+```css
+@import "tailwindcss";
+@import 'zabi-components/theme-only';
+@import 'zabi-components/theme-dark-only'; /* Optional: for dark mode */
+@import 'zabi-components/dist/zabi-components.css';
+```
+
+**Pros:**
+- Full control over Tailwind configuration
+- Can customize Tailwind before importing theme
+- Smaller bundle (no duplicate Tailwind import)
+
+**Cons:**
+- Requires Tailwind setup
+- Must import Tailwind first
+
+## Theme Extension
+
+You can extend the Zabi theme with your own customizations using additional `@theme` blocks:
+
+```css
+@import "tailwindcss";
+@import 'zabi-components/theme-only';
+
+/* Your custom theme extensions */
+@theme {
+  /* Custom font families */
+  --font-family-title: 'Your Font', sans-serif;
+  --font-family-body: 'Another Font', sans-serif;
+  
+  /* Custom colors */
+  --color-custom-primary: #ff0000;
+  --color-custom-secondary: #00ff00;
+}
+
+@import 'zabi-components/dist/zabi-components.css';
+```
+
+### Important: Import Order
+
+The import order is critical:
+
+1. **First:** `@import "tailwindcss"` (if using theme-only)
+2. **Second:** `@import 'zabi-components/theme-only'` (or theme)
+3. **Third:** Your custom `@theme` block (extends zabi theme)
+4. **Fourth:** `@import 'zabi-components/dist/zabi-components.css'` (uses the theme)
+
+This order ensures:
+- Tailwind is available for `theme()` function calls
+- Zabi theme is defined first
+- Your extensions override zabi defaults
+- Components can use all theme values
+
+## Dark Mode
+
+Zabi Components supports dark mode through CSS custom properties in the `.dark` class.
+
+### Automatic Dark Mode (System Preference)
+
+```css
+@import "tailwindcss";
+@import 'zabi-components/theme-only';
+@import 'zabi-components/theme-dark-only'; /* Supports system preference */
+@import 'zabi-components/dist/zabi-components.css';
+```
+
+The dark theme file uses `@media (prefers-color-scheme: dark)` to automatically switch based on system preference.
+
+### Manual Dark Mode Toggle
+
+For manual dark mode toggling, add the `.dark` class to your HTML element:
+
+```javascript
+// Toggle dark mode
+document.documentElement.classList.toggle('dark');
+```
+
+The dark theme file also includes `.dark` class support, so both system preference and manual toggle work.
+
+### Custom Dark Mode Colors
+
+You can override dark mode colors in your custom theme:
+
+```css
+@import "tailwindcss";
+@import 'zabi-components/theme-only';
+@import 'zabi-components/theme-dark-only';
+
+@theme {
+  /* Your light mode customizations */
+  --color-custom: #ff0000;
+}
+
+/* Custom dark mode overrides */
+.dark {
+  --color-custom: #ff6666; /* Lighter red for dark mode */
+}
+
+@import 'zabi-components/dist/zabi-components.css';
+```
+
+## Color System
+
+Zabi Components uses a semantic color system with the following color scales:
+
+### Color Scales
+
+- **Brand** - Primary brand colors (blue palette)
+- **Citron** - Energetic/yellow colors
+- **Pine** - Success/green colors
+- **Iris** - Info/purple colors
+
+Each scale includes shades from 50 (lightest) to 950 (darkest).
+
+### Semantic Colors
+
+Semantic colors map to specific use cases:
+
+- `--color-background` - Main background
+- `--color-headline` - Headings and titles
+- `--color-body` - Body text
+- `--color-description` - Secondary/description text
+- `--color-caption` - Captions and labels
+- `--color-border` - Borders and dividers
+- `--color-surface-elevated` - Elevated surfaces (cards, modals)
+- `--color-surface-level-0/1/2` - Surface hierarchy
+- `--color-primary` - Primary actions
+- `--color-secondary` - Secondary actions
+- `--color-success` - Success states
+- `--color-warning` - Warning states
+- `--color-error` - Error states
+
+### Using Colors
+
+#### In CSS
+
+```css
+.my-element {
+  background-color: var(--color-primary);
+  color: var(--color-headline);
+}
+```
+
+#### In Tailwind Classes
+
+Zabi Components provides utility classes:
+
+```html
+<div class="bg-primary text-headline">
+  Primary background with headline text
+</div>
+```
+
+#### In Tailwind theme() Function
+
+```css
+.custom-class {
+  color: theme(colors.brand.600);
+  background: theme(colors.surface.elevated);
+}
+```
+
+## Customization Examples
+
+### Example 1: Custom Brand Colors
+
+```css
+@import "tailwindcss";
+@import 'zabi-components/theme-only';
+
+
+@import 'zabi-components/dist/zabi-components.css';
+```
+
+### Example 2: Custom Fonts
+
+```css
+@import "tailwindcss";
+@import 'zabi-components/theme-only';
+
+@theme {
+  --font-family-title: 'Inter', 'Helvetica', sans-serif;
+  --font-family-body: 'Inter', 'Helvetica', sans-serif;
+  --font-family-sans: 'Inter', ui-sans-serif, system-ui, sans-serif;
+}
+
+@import 'zabi-components/dist/zabi-components.css';
+```
+
+### Example 3: Custom Semantic Colors
+
+```css
+@import "tailwindcss";
+@import 'zabi-components/theme-only';
+
+@theme {
+  /* Custom primary color */
+  --color-primary: theme(colors.purple.600);
+  --color-primary-weak: theme(colors.purple.700);
+  --color-primary-medium: theme(colors.purple.800);
+  --color-primary-strong: theme(colors.purple.900);
+}
+
+@import 'zabi-components/dist/zabi-components.css';
+```
+
+### Example 4: Multiple Theme Variants
+
+```css
+@import "tailwindcss";
+@import 'zabi-components/theme-only';
+
+/* Default theme */
+@theme {
+  --color-primary: theme(colors.blue.600);
+}
+
+/* Custom variant */
+.variant-custom {
+  --color-primary: theme(colors.purple.600);
+  --color-secondary: theme(colors.pink.600);
+}
+
+@import 'zabi-components/dist/zabi-components.css';
+```
+
+## Common Pitfalls
+
+### Pitfall 1: Wrong Import Order
+
+**Wrong:**
+```css
+@import 'zabi-components/dist/zabi-components.css';
+@import 'zabi-components/theme-only'; /* Too late! */
+```
+
+**Correct:**
+```css
+@import "tailwindcss";
+@import 'zabi-components/theme-only';
+@import 'zabi-components/dist/zabi-components.css';
+```
+
+### Pitfall 2: Double Tailwind Import
+
+**Wrong:**
+```css
+@import "tailwindcss";
+@import 'zabi-components/theme'; /* This also imports Tailwind! */
+```
+
+**Correct:**
+```css
+@import "tailwindcss";
+@import 'zabi-components/theme-only'; /* Use theme-only */
+```
+
+### Pitfall 3: Theme Extension After Components
+
+**Wrong:**
+```css
+@import 'zabi-components/theme-only';
+@import 'zabi-components/dist/zabi-components.css';
+@theme { /* Too late! */ }
+```
+
+**Correct:**
+```css
+@import "tailwindcss";
+@import 'zabi-components/theme-only';
+@theme { /* Extend before components */ }
+@import 'zabi-components/dist/zabi-components.css';
+```
+
+### Pitfall 4: Missing Dark Mode Import
+
+If you want dark mode support, you must import the dark theme file:
+
+```css
+@import "tailwindcss";
+@import 'zabi-components/theme-only';
+@import 'zabi-components/theme-dark-only'; /* Don't forget this! */
+@import 'zabi-components/dist/zabi-components.css';
+```
+
+### Pitfall 5: Using theme() Before Theme is Defined
+
+**Wrong:**
+```css
+@theme {
+  --color-custom: theme(colors.brand.600); /* Works */
+  --color-other: theme(colors.custom.500); /* Fails - custom not defined yet */
+}
+```
+
+**Correct:**
+```css
+@theme {
+  --color-custom: theme(colors.brand.600);
+  /* Define custom colors first, then reference them */
+  --color-custom-500: #ff0000;
+  --color-other: var(--color-custom-500); /* Use var() for custom colors */
+}
+```
+
+## Troubleshooting
+
+### Theme Variables Not Working
+
+1. Check import order (theme must come before components CSS)
+2. Verify you're using the correct theme file variant
+3. Ensure Tailwind is imported if using `theme-only`
+4. Check browser console for CSS errors
+
+### Dark Mode Not Working
+
+1. Ensure dark theme file is imported
+2. Check that `.dark` class is applied to `<html>` or root element
+3. Verify system preference detection (if using automatic mode)
+4. Check that dark mode CSS custom properties are defined
+
+### Colors Not Updating
+
+1. Clear browser cache
+2. Restart dev server
+3. Check for CSS specificity issues
+4. Verify theme extension is after zabi theme import
+
+## Advanced Usage
+
+### Programmatic Theme Switching
+
+```javascript
+// Switch to dark mode
+document.documentElement.classList.add('dark');
+
+// Switch to light mode
+document.documentElement.classList.remove('dark');
+
+// Toggle
+document.documentElement.classList.toggle('dark');
+```
+
+### Theme with Svelte
+
+```svelte
+<script>
+  import { onMount } from 'svelte';
+  
+  let isDark = $state(false);
+  
+  onMount(() => {
+    // Check system preference
+    const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+    isDark = prefersDark;
+    updateTheme();
+  });
+  
+  function updateTheme() {
+    if (isDark) {
+      document.documentElement.classList.add('dark');
+    } else {
+      document.documentElement.classList.remove('dark');
+    }
+  }
+</script>
+
+<button on:click={() => { isDark = !isDark; updateTheme(); }}>
+  Toggle Theme
+</button>
+```
+
+## Additional Resources
+
+- [Tailwind CSS v4 Documentation](https://tailwindcss.com/docs)
+- [CSS Custom Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties)
+- [Zabi Components GitHub](https://github.com/zabi-components/zabi-components)
+

package/THEMING.md

@@ -0,0 +1,248 @@
+# Theming Guide
+
+## 🎨 Single Source of Truth
+
+**All theming is done in one file: `src/app.css`**
+
+This file contains:
+- All color scales (brand, citron, pine, iris, base)
+- Semantic color tokens (primary, secondary, success, error, etc.)
+- Action colors (for buttons and interactive elements)
+- Dark mode overrides
+- Typography settings
+- Spacing, border radius, and z-index values
+
+## 📍 Where to Make Changes
+
+### Main Theme (Light Mode)
+Edit the `@theme` block in `src/app.css`.
+
+### Dark Mode Theme
+Edit the `.dark` block in `src/app.css`.
+
+## ⚠️ Important: Don't Edit These Files
+
+### Generated Files (in `dist/` folder)
+These files are **automatically generated** from `src/app.css` by the build script:
+- ❌ `dist/zabi-components.css` - Full compiled CSS (generated)
+- ❌ `dist/zabi-components-theme.css` - Theme with Tailwind import (generated)
+- ❌ `dist/zabi-components-theme-only.css` - Theme only, no Tailwind (generated)
+- ❌ `dist/zabi-components-theme-dark.css` - Dark mode theme (generated)
+- ❌ `dist/zabi-components-theme-dark-only.css` - Dark mode theme only (generated)
+- ❌ `dist/zabi-components-colors.css` - Standalone colors (generated from app.css)
+
+**These files are overwritten every time you run `npm run build:css`**
+
+### Example Files
+- ❌ `examples/theme-extensions/02-custom-brand-colors.css` - Just an example, not your actual theme
+- ❌ `examples/theme-extensions/03-custom-semantic-colors.css` - Just an example, not your actual theme
+
+### Source Files (Edit These)
+- ✅ `src/app.css` - **THIS IS THE ONLY FILE YOU NEED TO EDIT**
+- ✅ Removed deprecated files (`src/styles/colors.css`, `src/styles/base.css`, `src/styles/simple.css`, `src/app-simple.css`)
+
+## 📦 What Are the Dist Files For?
+
+The `dist/` files are **for consumers** of your library who want to import the theme separately.
+
+**Full import matrix, export paths, and examples:** [docs/theme-imports.md](./docs/theme-imports.md)
+
+### For Library Developers (You)
+- **Edit**: `src/app.css` only
+- **Build**: Run `npm run build:css` to regenerate all dist files (or `npm run build:lib` before publish)
+- **After token edits**: run `node scripts/verify-build.js` to confirm outputs (also runs as part of `build:lib`)
+- **Base scale source**: use `tokens/base-scale.js`; run `npm run sync:tokens` (or `npm run build:css`) to render token blocks back into `src/app.css`
+
+### For Library Consumers
+
+Use **package exports** (preferred):
+
+| Need | Import |
+|------|--------|
+| Tailwind + full `@theme` (app has no Tailwind yet) | `zabi-components/theme` |
+| Tailwind already in app — merge `@theme` only | `zabi-components/theme-only` |
+| Dark overrides (+ Tailwind import in file) | `zabi-components/theme-dark` |
+| Dark overrides only (Tailwind already loaded) | `zabi-components/theme-dark-only` |
+| CSS variables only, no Tailwind | `zabi-components/colors` |
+| Full compiled CSS (utilities + everything) | `zabi-components/css` |
+
+Examples:
+
+```css
+@import "zabi-components/theme-only";
+@import "zabi-components/theme-dark-only";
+```
+
+```css
+@import "zabi-components/colors";
+```
+
+```css
+@import "zabi-components/css";
+```
+
+Canonical recommendation for most apps remains:
+
+```css
+@import "tailwindcss";
+@import "zabi-components/theme-only";
+@import "zabi-components/theme-dark-only";
+```
+
+Dark mapping rule reference:
+- Physical ramp tokens are `--zabi-base-50 ... --zabi-base-950`.
+- Semantic dark mapping is generated with `S -> 1000 - S` (for example `50 <-> 950`, `75 <-> 925`, `500` unchanged).
+
+## 🎯 Common Customizations
+
+### Change Brand Colors
+
+```css
+@theme {
+  /* Replace the brand color scale */
+  --color-brand-50: #f0f9ff;
+  --color-brand-100: #e0f2fe;
+  --color-brand-200: #bae6fd;
+  --color-brand-300: #7dd3fc;
+  --color-brand-400: #38bdf8;
+  --color-brand-500: #0ea5e9;
+  --color-brand-600: #0284c7;
+  --color-brand-700: #0369a1;
+  --color-brand-800: #075985;
+  --color-brand-900: #0c4a6e;
+  --color-brand-950: #082f49;
+}
+```
+
+### Change Primary Button Color
+
+The primary button uses `--color-action-primary` which defaults to `brand-800`. To change it:
+
+```css
+@theme {
+  /* Use a different brand shade */
+  --color-action-primary: theme(colors.brand.600);
+  
+  /* Or use a completely custom color */
+  --color-action-primary: #your-color-here;
+}
+```
+
+### Brand Scale Usage
+
+The brand scale is used throughout the system:
+
+- **brand-50 to brand-100**: Subtle backgrounds, hover states
+- **brand-300 to brand-400**: Light accents, disabled states
+- **brand-500**: Focus rings, medium emphasis
+- **brand-600**: Primary color, links
+- **brand-700**: Link hover, primary hover
+- **brand-800**: **Primary buttons** (`action-primary`)
+- **brand-900**: Primary button hover
+- **brand-950**: Darkest brand shade
+
+### Dark Mode
+
+Dark mode automatically inverts the brand scale:
+- `brand-50` becomes `brand-950` (darkest)
+- `brand-950` becomes `brand-50` (lightest)
+
+This happens automatically in the `.dark` block, so you typically don't need to override action colors in dark mode.
+
+## 🌙 Dark Mode Action Colors
+
+Dark mode action colors are handled in `src/app.css` in the `.dark` block (lines 393-404):
+
+### Primary Actions
+- **No explicit dark mode override needed** - Brand colors are automatically inverted
+- `brand-800` (light mode) → `brand-200` (dark mode) automatically
+
+### Secondary Actions  
+- **No explicit dark mode override needed** - Base colors are automatically inverted
+- `base-600` (light mode) → `base-400` (dark mode) automatically
+
+### Danger Actions
+- **Has explicit dark mode overrides** (lines 399-404) because red colors aren't automatically inverted:
+  ```css
+  .dark {
+    --color-action-danger: theme(colors.red.500);
+    --color-action-danger-hover: theme(colors.red.600);
+    --color-action-danger-active: theme(colors.red.700);
+    /* ... */
+  }
+  ```
+
+### In Generated Files
+
+- **`dist/zabi-components.css`**: Has dark mode at line 2178, danger actions at lines 2264-2269
+- **`dist/zabi-components-theme-dark-only.css`**: Has dark mode action colors at lines 119-130 (only danger has explicit overrides)
+- **`dist/zabi-components-theme-only.css`**: Only has light mode (@theme block), no dark mode
+- **`dist/zabi-components-theme.css`**: Only has light mode (@theme block), no dark mode
+
+## 📁 File Structure
+
+```
+src/
+└── app.css          ← 🎯 EDIT THIS FILE FOR ALL THEMING (single source of truth)
+
+dist/                 ← ⚠️ GENERATED FILES - DON'T EDIT
+├── zabi-components.css              (full CSS with dark mode)
+├── zabi-components-theme.css       (light mode only)
+├── zabi-components-theme-only.css  (light mode only)
+├── zabi-components-theme-dark.css   (dark mode only)
+├── zabi-components-theme-dark-only.css (dark mode only)
+└── zabi-components-colors.css       (standalone, both modes)
+
+examples/             ← ⚠️ EXAMPLES ONLY - DON'T EDIT
+└── theme-extensions/
+    ├── 02-custom-brand-colors.css
+    └── 03-custom-semantic-colors.css
+```
+
+## ⚠️ Important Notes
+
+1. **Never edit files in `dist/`** - These are automatically generated from `src/app.css` by `scripts/build-css.js`
+2. **All theming is in `src/app.css`** - This is the single source of truth
+3. **Always edit `src/app.css`** - This is your single source of truth
+4. The `examples/` folder contains examples, not your actual theme
+5. **Dist files are overwritten** every time you run `npm run build:css`
+
+## 🔄 Build Process
+
+When you edit `src/app.css`:
+
+1. **Development**: Changes are automatically reflected (no build needed)
+2. **Production**: Run `npm run build:css` to regenerate dist files
+3. The build script (`scripts/build-css.js`) reads `src/app.css` and generates:
+   - `zabi-components.css` - Full compiled CSS with Tailwind processed (includes dark mode)
+   - `zabi-components-theme.css` - Theme block with Tailwind import (light mode only)
+   - `zabi-components-theme-only.css` - Theme block only (light mode only)
+   - `zabi-components-theme-dark.css` - Dark mode theme with Tailwind import
+   - `zabi-components-theme-dark-only.css` - Dark mode theme only
+   - `zabi-components-colors.css` - Standalone CSS custom properties (both light and dark)
+
+## 🔄 After Making Changes
+
+### For Development
+After editing `src/app.css`, changes are automatically reflected in your app. No build needed!
+
+### For Production/Library Build
+If you're building the library for distribution:
+```bash
+npm run build:css  # Regenerates all dist CSS files from src/app.css
+```
+
+## Optional perceptual midpoint generation (OKLCH)
+
+Base midpoints are frozen hex by default (`fixed` mode).  
+For experimentation, you can generate midpoint steps in OKLCH interpolation and commit the resulting frozen values:
+
+```bash
+ZABI_BASE_SCALE_MODE=oklch npm run sync:tokens
+npm run build:css
+```
+
+Notes:
+- Primary anchors (`50, 100, 200 ... 950`) stay fixed.
+- Midpoints (`75, 150, 250 ... 925`) are generated from adjacent anchors.
+- Commit updated `src/app.css` and regenerated `dist/` outputs together.