zabi-components 5.0.21 → 6.0.0

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.

package/dist/atoms/Card.svelte

@@ -1,70 +1,64 @@
 <script lang="ts">
     import type { Snippet } from "svelte";
     import type { CardVariant, SizeVariant } from "../../types/variants.js";
-    import CardHeader from "./CardHeader.svelte";
-    import CardContent from "./CardContent.svelte";
 
     interface Props {
-        title?: string;
-        description?: string;
-        image?: string;
         onclick?: (event: MouseEvent) => void | Promise<void>;
         size?: SizeVariant;
         variant?: CardVariant;
         fullWidth?: boolean;
+        className?: string;
+        /** Required when card is interactive (has onclick) for accessibility */
+        ariaLabel?: string;
         children?: Snippet;
     }
 
     let {
-        title = "",
-        description = "",
-        image = "",
         onclick,
         size = "md",
         variant = "default",
         fullWidth = true,
+        className = "",
+        ariaLabel,
         children,
         ...restProps
     }: Props = $props();
 
-    const sizeClass = $derived(() => {
-        return size === "sm" ? "p-4" : size === "lg" ? "p-8" : "p-6";
-    });
-
-    const variantClasses = $derived(() => {
-        switch (variant) {
-            case "elevated":
-                return "bg-card shadow-lg";
-            case "outlined":
-                return "bg-card border-2 border-base-200 shadow-none";
-            case "flat":
-                return "bg-card shadow-none border-none";
-            default:
-                return "bg-card shadow-sm";
-        }
-    });
-
-    const useOldAPI = $derived(
-        title !== "" || description !== "" || image !== "",
+    const sizeClass = $derived(
+        size === "sm" ? "p-4" : size === "lg" ? "p-8" : "p-6",
     );
 
-    const cardClasses = $derived(() => {
-        const baseClasses = `rounded-lg transition-all duration-200 ${variantClasses()}`;
-        const interactiveClasses = onclick
-            ? variant === "elevated"
-                ? "cursor-pointer hover:shadow-xl hover:bg-card-hover"
-                : variant === "outlined"
-                  ? "cursor-pointer hover:border-brand-500 hover:bg-card-hover"
-                  : variant === "flat"
-                    ? "cursor-pointer hover:bg-card-hover"
-                    : "cursor-pointer hover:shadow-lg hover:bg-card-hover"
-            : "";
-        const widthClasses = fullWidth ? "w-full" : "";
-        const minWidthClass = useOldAPI ? "min-w-64" : "";
-        const paddingClass = useOldAPI ? sizeClass() : "";
+    const variantClasses = $derived(
+        variant === "elevated"
+            ? "bg-card shadow-lg"
+            : variant === "outlined"
+              ? "bg-card border-2 border-base-200 shadow-none"
+              : variant === "flat"
+                ? "bg-card shadow-none border-none"
+                : "bg-card shadow-sm",
+    );
 
-        return `${baseClasses} ${interactiveClasses} ${widthClasses} ${minWidthClass} ${paddingClass}`.trim();
-    });
+    const cardClasses = $derived(
+        [
+            "rounded-lg transition-all duration-200",
+            variantClasses,
+            onclick
+                ? variant === "elevated"
+                    ? "cursor-pointer hover:shadow-xl hover:bg-card-hover"
+                    : variant === "outlined"
+                      ? "cursor-pointer hover:border-brand-500 hover:bg-card-hover"
+                      : variant === "flat"
+                        ? "cursor-pointer hover:bg-card-hover"
+                        : "cursor-pointer hover:shadow-lg hover:bg-card-hover"
+                : "",
+            fullWidth ? "w-full" : "",
+            sizeClass,
+            className,
+        ]
+            .filter(Boolean)
+            .join(" ")
+            .trim(),
+    );
 
     function handleKeydown(event: KeyboardEvent) {
         if (onclick && (event.key === "Enter" || event.key === " ")) {
@@ -74,37 +68,16 @@
     }
 
     const cardRole = $derived(onclick ? "button" : undefined);
-    const cardAriaLabel = $derived(onclick && title ? title : undefined);
 </script>
 
 <div
-    class={cardClasses()}
+    class={cardClasses}
     {onclick}
     role={cardRole}
     {...onclick ? { tabindex: 0 } : {}}
-    aria-label={cardAriaLabel}
+    aria-label={ariaLabel}
     onkeydown={onclick ? handleKeydown : undefined}
     {...restProps}
 >
-    {#if useOldAPI}
-        <!-- Old API: Using title/description/image props -->
-        {#if title || description}
-            <CardHeader {title} {description} />
-        {/if}
-
-        {#if image || children}
-            <CardContent {image} imageAlt={title}>
-                {#if children}
-                    {@render children()}
-                {/if}
-            </CardContent>
-        {/if}
-    {:else}
-        <!-- New API: Using compound components (CardHeader, CardContent, CardFooter) -->
-        {#if children}
-            <CardContent className="pt-6">
-                {@render children()}
-            </CardContent>
-        {/if}
-    {/if}
+    {@render children?.()}
 </div>

package/dist/atoms/Card.svelte.d.ts

@@ -1,13 +1,13 @@
 import type { Snippet } from "svelte";
 import type { CardVariant, SizeVariant } from "../../types/variants.js";
 interface Props {
-    title?: string;
-    description?: string;
-    image?: string;
     onclick?: (event: MouseEvent) => void | Promise<void>;
     size?: SizeVariant;
     variant?: CardVariant;
     fullWidth?: boolean;
+    className?: string;
+    /** Required when card is interactive (has onclick) for accessibility */
+    ariaLabel?: string;
     children?: Snippet;
 }
 declare const Card: import("svelte").Component<Props, {}, "">;

package/dist/atoms/CardContent.svelte

@@ -17,7 +17,7 @@
     }: Props = $props();
 </script>
 
-<div class="p-6 pt-0 {className}" {...restProps}>
+<div class={className} {...restProps}>
     {#if image}
         <img
             src={image}

package/dist/atoms/CardHeader.svelte

@@ -3,6 +3,9 @@
 
     interface Props {
         title?: string;
+        /** Short secondary text displayed directly under the title */
+        subtitle?: string;
+        /** Longer supporting text displayed below the subtitle */
         description?: string;
         level?: 1 | 2 | 3 | 4 | 5 | 6;
         className?: string;
@@ -11,6 +14,7 @@
 
     let {
         title = "",
+        subtitle = "",
         description = "",
         level = 3,
         className = "",
@@ -24,7 +28,7 @@
     });
 </script>
 
-<header class="flex flex-col space-y-1.5 p-6 {className}" {...restProps}>
+<header class={`flex flex-col space-y-1.5 pb-4 ${className}`.trim()} {...restProps}>
     {#if title}
         <svelte:element this={headingTag} class={headingClasses()}>
             {title}
@@ -33,6 +37,11 @@
     {#if children}
         {@render children()}
     {/if}
+    {#if subtitle}
+        <p class="text-sm text-description">
+            {subtitle}
+        </p>
+    {/if}
     {#if description}
         <p class="text-sm text-description">
             {description}

package/dist/atoms/CardHeader.svelte.d.ts

@@ -1,6 +1,9 @@
 import type { Snippet } from "svelte";
 interface Props {
     title?: string;
+    /** Short secondary text displayed directly under the title */
+    subtitle?: string;
+    /** Longer supporting text displayed below the subtitle */
     description?: string;
     level?: 1 | 2 | 3 | 4 | 5 | 6;
     className?: string;

package/dist/atoms/Checkbox.svelte

@@ -1,11 +1,5 @@
 <script lang="ts">
-    function generateId(prefix: string = "id"): string {
-        if (typeof window !== "undefined") {
-            return `${prefix}-${Math.random().toString(36).substr(2, 9)}`;
-        } else {
-            return `${prefix}-ssr-${Date.now()}`;
-        }
-    }
+    import { generateId } from "../../routes/lib/ssr-safe.js";
 
     interface Props {
         checked?: boolean;

package/dist/atoms/CodeBlock.svelte

@@ -44,7 +44,7 @@
         {#if showCopyButton}
             <button
                 onclick={copyToClipboard}
-                class="flex items-center gap-2 px-3 py-1 text-xs text-base-300 hover:text-white hover:bg-base-700 rounded transition-colors duration-200"
+                class="flex cursor-pointer items-center gap-2 rounded px-3 py-1 text-xs text-base-300 transition-colors duration-200 hover:bg-base-700 hover:text-white"
                 aria-label="Copy code to clipboard"
             >
                 {#if copied}
@@ -92,31 +92,31 @@
 
     :global(.language-svelte .token.tag),
     :global(.language-html .token.tag) {
-        color: #f92672;
+        color: var(--color-error-text);
     }
 
     :global(.language-svelte .token.attr-name),
     :global(.language-html .token.attr-name) {
-        color: #a6e22e;
+        color: var(--color-success-text);
     }
 
     :global(.language-svelte .token.attr-value),
     :global(.language-html .token.attr-value) {
-        color: #e6db74;
+        color: var(--color-warning-text);
     }
 
     :global(.language-javascript .token.keyword),
     :global(.language-typescript .token.keyword) {
-        color: #66d9ef;
+        color: var(--color-info-text);
     }
 
     :global(.language-javascript .token.string),
     :global(.language-typescript .token.string) {
-        color: #e6db74;
+        color: var(--color-warning-text);
     }
 
     :global(.language-javascript .token.function),
     :global(.language-typescript .token.function) {
-        color: #a6e22e;
+        color: var(--color-success-text);
     }
 </style>