zabi-components 8.0.0 → 8.1.0

package/THEME.md

@@ -1,370 +1,239 @@
 # Zabi Components Theme Guide
 
-Complete guide to using and customizing the Zabi Components theme system with Tailwind CSS v4.
+How to load the Zabi Components theme in an app that uses Tailwind CSS v4, and
+how to use its tokens in your own CSS.
+
+To give the library your own brand, read [THEMING.md](./THEMING.md). It lists
+the tokens an app may set and documents the `zabi-theme` generator. This file
+does not repeat it.
 
 ## 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)
+- [Using the Tokens](#using-the-tokens)
+- [Your Brand](#your-brand)
+- [Adding Your Own Tokens](#adding-your-own-tokens)
 - [Common Pitfalls](#common-pitfalls)
+- [Troubleshooting](#troubleshooting)
 
 ## Quick Start
 
-### Basic Setup (Standalone)
-
-If you don't have Tailwind CSS set up yet:
+### With Tailwind in the app
 
 ```css
 /* app.css */
-@import 'zabi-components/theme';
-@import 'zabi-components/dist/zabi-components.css';
+@import "tailwindcss";
+@import "zabi-components/theme-only";
+@import "zabi-components/theme-dark-only";
 ```
 
-### Setup with Existing Tailwind
+That is everything. The theme file tells Tailwind to scan the package's
+components, so the classes they use are generated by your build; there is no
+second stylesheet to import.
 
-If you already have Tailwind CSS configured:
+### Without Tailwind in the app
 
 ```css
 /* app.css */
-@import "tailwindcss";
-@import 'zabi-components/theme-only';
-@import 'zabi-components/dist/zabi-components.css';
+@import "zabi-components/css";
 ```
 
-### With Dark Mode
+The compiled stylesheet holds the utilities the components use, in light and
+dark.
+
+### Standalone theme files
+
+`zabi-components/theme` and `zabi-components/theme-dark` are the same two theme
+files with `@import "tailwindcss"` at the top, for a stylesheet that does not
+import Tailwind itself. They still go through Tailwind's build.
 
 ```css
 /* app.css */
-@import "tailwindcss";
-@import 'zabi-components/theme-only';
-@import 'zabi-components/theme-dark-only';
-@import 'zabi-components/dist/zabi-components.css';
+@import "zabi-components/theme";
+@import "zabi-components/theme-dark";
 ```
 
 ## 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)
+| `zabi-components/theme-only` | Every token, light values. No Tailwind import. | Apps that import Tailwind themselves |
+| `zabi-components/theme-dark-only` | Dark role remaps. No Tailwind import. Needs the light theme. | The same apps, for dark mode |
+| `zabi-components/theme` | `theme-only` with `@import "tailwindcss"` | A stylesheet without its own Tailwind import |
+| `zabi-components/theme-dark` | `theme-dark-only` with `@import "tailwindcss"`. Needs the light theme. | The same, for dark mode |
+| `zabi-components/css` | The compiled stylesheet | Apps without Tailwind |
+| `zabi-components/colors` | The tokens as plain custom properties, light and dark | Apps that want only the variables |
 
-**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
+The full matrix, the legacy `dist/` paths and what each file contains are in
+[docs/theme-imports.md](./docs/theme-imports.md).
 
 ## Dark Mode
 
-Zabi Components supports dark mode through CSS custom properties in the `.dark` class.
+Import the dark theme file after the light one. It only remaps roles; the raw
+palettes (`--zabi-brand-*`, `--zabi-accent-*`, `--zabi-base-*` and the other
+ramps) are declared once, in the light theme, so the dark file does nothing on
+its own.
 
-### Automatic Dark Mode (System Preference)
+Dark is switched on the `<html>` element, by an attribute or by a class:
 
-```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.
+| On `<html>` | Result |
+|---|---|
+| nothing | light, also on a dark system |
+| `data-theme="light"` | light |
+| `data-theme="dark"` | dark |
+| `data-theme="auto"` | follows the system (`prefers-color-scheme`) |
+| `class="dark"` | dark, the same as `data-theme="dark"` |
 
-### Manual Dark Mode Toggle
+Following the system is opt-in:
 
-For manual dark mode toggling, add the `.dark` class to your HTML element:
-
-```javascript
-// Toggle dark mode
-document.documentElement.classList.toggle('dark');
+```html
+<!-- Follow the phone's setting, with no script -->
+<html data-theme="auto">
 ```
 
-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 */
-}
+To switch from a script:
 
-@import 'zabi-components/dist/zabi-components.css';
+```javascript
+document.documentElement.dataset.theme = "dark"; // "light" | "auto"
+// or
+document.documentElement.classList.toggle("dark");
 ```
 
-## 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
+The details (`color-scheme`, why the attribute goes on `<html>` only, what
+`ThemeToggle` reads) are in [THEMING.md](./THEMING.md#light-dark-and-auto).
 
-Each scale includes shades from 50 (lightest) to 950 (darkest).
+## Using the Tokens
 
-### Semantic Colors
+Components paint with **roles**: tokens that say what a colour is for and are
+already the right value in each mode. Use the same roles in your own CSS.
 
-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-surface-base` / `-raised` / `-elevated` / `-overlay` - Surface levels: page, cards, nested cards, floating panels
+- `--color-surface-inset` - A recessed area on a card (a well); see THEMING.md, Surface elevation levels
+- `--color-headline`, `--color-body`, `--color-description`, `--color-caption` - Text
 - `--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
+- `--color-action-primary`, `-hover`, `-active` - Primary actions
+- `--color-on-brand` - Text on a primary fill (`--color-action-primary-text` follows it)
+- `--color-accent`, `-hover`, `-active`, `-subtle`, `-border`, `-text` - The second brand colour
+- `--color-on-accent` - Text on a solid accent fill
+- `--color-link`, `--color-focus-ring` - Links and the focus ring
+- `--color-focus-ring-muted` - The neutral ring of ghost and link controls (`.focus-ring--muted`)
+- `--color-focus-ring-danger` - The ring of a destructive control (`.focus-ring--danger`); `--color-error` by default
+- `--color-control-border` (`border-control-border`) - The edge of a control that has nothing else to be seen by, such as the outline of an empty Rating star. `--color-border-strong` is a decorative edge and is under 3:1 on the dark elevated and overlay surfaces
+- `--color-input-border` (`border-input-border`) - The edge of a form field (Input, Textarea, Select, DateField, TimeField). Held to 3:1 on the field fill (`--color-input`), the page and the card in both themes (WCAG 1.4.11); `--color-input-border-hover` is one step darker in light
+- `--color-progress-fill`, `--color-progress-track` (`bg-progress-fill`, `bg-progress-track`) - The fill and the track of Progress. The fill is `--color-action-primary` and the track `--color-input`, so the bar follows a pinned primary action. Held to 3:1 (fill on track) in both themes
+- `--color-success`, `--color-warning`, `--color-error`, `--color-info` - States, each with `-subtle`, `-border` and `-text`
+
+The full list is in [THEMING.md](./THEMING.md#roles-read-them-do-not-set-them).
+
+### In CSS
 
 ```css
 .my-element {
-  background-color: var(--color-primary);
-  color: var(--color-headline);
+  background-color: var(--color-action-primary);
+  color: var(--color-on-brand);
 }
 ```
 
-#### In Tailwind Classes
-
-Zabi Components provides utility classes:
+### In Tailwind classes
 
 ```html
-<div class="bg-primary text-headline">
-  Primary background with headline text
+<div class="bg-card text-headline border border-border">
+  A card surface 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';
+## Your Brand
 
+Generate one file from your brand colour and import it after the theme. It
+covers light and dark.
 
-@import 'zabi-components/dist/zabi-components.css';
+```bash
+npx zabi-theme --brand "#C17B00" --neutral "#78716c" --out src/lib/brand.generated.css
 ```
 
-### Example 2: Custom Fonts
-
 ```css
 @import "tailwindcss";
-@import 'zabi-components/theme-only';
+@import "zabi-components/theme-only";
+@import "zabi-components/theme-dark-only";
+@import "./lib/brand.generated.css";
 
-@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;
+:root {
+  --font-family-heading: "Your Display Font", var(--font-family-sans);
 }
-
-@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);
-}
+Which tokens an app may set, what the generator checks and what does not
+follow an override: [THEMING.md](./THEMING.md).
 
-@import 'zabi-components/dist/zabi-components.css';
-```
+## Adding Your Own Tokens
 
-### Example 4: Multiple Theme Variants
+A token of your own goes in a `@theme` block after the theme import. Tailwind
+then generates utilities for it (`bg-quiz-gold` here), next to the library's.
 
 ```css
 @import "tailwindcss";
-@import 'zabi-components/theme-only';
+@import "zabi-components/theme-only";
 
-/* Default theme */
 @theme {
-  --color-primary: theme(colors.blue.600);
+  --color-quiz-gold: #d4a017;
 }
-
-/* Custom variant */
-.variant-custom {
-  --color-primary: theme(colors.purple.600);
-  --color-secondary: theme(colors.pink.600);
-}
-
-@import 'zabi-components/dist/zabi-components.css';
 ```
 
+Use a name the library does not use. The library's own tokens are set on
+`:root`, as THEMING.md describes, not redeclared in `@theme`.
+
 ## Common Pitfalls
 
-### Pitfall 1: Wrong Import Order
+### Pitfall 1: Importing the compiled stylesheet as well
 
 **Wrong:**
 ```css
-@import 'zabi-components/dist/zabi-components.css';
-@import 'zabi-components/theme-only'; /* Too late! */
+@import "tailwindcss";
+@import "zabi-components/theme-only";
+@import "zabi-components/css"; /* a second, finished Tailwind build */
 ```
 
 **Correct:**
 ```css
 @import "tailwindcss";
-@import 'zabi-components/theme-only';
-@import 'zabi-components/dist/zabi-components.css';
+@import "zabi-components/theme-only";
 ```
 
+Two Tailwind builds cannot be sorted into one order, so responsive variants
+lose to plain utilities from the other build. See
+[docs/theme-imports.md](./docs/theme-imports.md), "Tailwind together with the
+compiled stylesheet".
+
 ### Pitfall 2: Double Tailwind Import
 
 **Wrong:**
 ```css
 @import "tailwindcss";
-@import 'zabi-components/theme'; /* This also imports Tailwind! */
+@import "zabi-components/theme"; /* This also imports Tailwind! */
 ```
 
 **Correct:**
 ```css
 @import "tailwindcss";
-@import 'zabi-components/theme-only'; /* Use theme-only */
+@import "zabi-components/theme-only"; /* Use theme-only */
 ```
 
-### Pitfall 3: Theme Extension After Components
+### Pitfall 3: Overrides Before the Theme
 
 **Wrong:**
 ```css
-@import 'zabi-components/theme-only';
-@import 'zabi-components/dist/zabi-components.css';
-@theme { /* Too late! */ }
+@import "./lib/brand.generated.css"; /* the dark theme below wins where both set a token */
+@import "zabi-components/theme-only";
+@import "zabi-components/theme-dark-only";
 ```
 
 **Correct:**
 ```css
-@import "tailwindcss";
-@import 'zabi-components/theme-only';
-@theme { /* Extend before components */ }
-@import 'zabi-components/dist/zabi-components.css';
+@import "zabi-components/theme-only";
+@import "zabi-components/theme-dark-only";
+@import "./lib/brand.generated.css";
 ```
 
 ### Pitfall 4: Missing Dark Mode Import
@@ -373,101 +242,49 @@ 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';
+@import "zabi-components/theme-only";
+@import "zabi-components/theme-dark-only"; /* Don't forget this! */
 ```
 
-### Pitfall 5: Using theme() Before Theme is Defined
+### Pitfall 5: `theme()` for a Colour
 
-**Wrong:**
-```css
-@theme {
-  --color-custom: theme(colors.brand.600); /* Works */
-  --color-other: theme(colors.custom.500); /* Fails - custom not defined yet */
-}
-```
+Tailwind's `theme()` function is replaced at build time with the token's light
+definition, so `theme(colors.brand.600)` is the light step in dark mode too.
+Use the variable, which is resolved in the browser:
 
-**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 */
+.custom-class {
+  color: var(--color-brand-600);
+  background: var(--color-surface-elevated);
 }
 ```
 
 ## Troubleshooting
 
-### Theme Variables Not Working
+### Components Look Unstyled
 
-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
+1. Check that the theme is imported, after Tailwind
+2. Check the package version: the theme files in 8.0.0 and earlier left components unstyled
+3. Check the 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
+2. Check that `class="dark"` or `data-theme="dark"` is on `<html>`, not on an element inside it
+3. To follow the system, set `data-theme="auto"`; nothing follows it by default
+4. Check that the light theme is imported too: the dark file only remaps its tokens
 
-### Programmatic Theme Switching
+### Brand Colours Not Updating
 
-```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>
-```
+1. Check that the brand file is imported after both theme files
+2. Check that the overrides are on `:root`, not on an element inside the page
+3. Check that it sets `--zabi-brand-*`, not `--color-brand-*`
+4. Restart the dev server
 
 ## Additional Resources
 
+- [THEMING.md](./THEMING.md): the theming guide and token API
+- [docs/theme-imports.md](./docs/theme-imports.md): every CSS export
 - [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)
-
+- [Zabi Components on GitHub](https://github.com/sabnor/zabi-components)