zabi-components 5.0.15 → 5.0.18

package/README.md

@@ -40,6 +40,57 @@ npm install svelte@^5.38.10
 npm install @sveltejs/kit@^2.0.0  # Optional, for SvelteKit projects
 ```
 
+## Theme Setup
+
+Zabi Components includes a comprehensive theme system with Tailwind CSS v4. You need to import the theme before using components.
+
+### Quick Setup
+
+**For projects with existing Tailwind CSS:**
+
+```css
+/* app.css */
+@import "tailwindcss";
+@import 'zabi-components/theme-only';
+@import 'zabi-components/dist/zabi-components.css';
+```
+
+**For standalone projects (no Tailwind setup):**
+
+```css
+/* app.css */
+@import 'zabi-components/theme';
+@import 'zabi-components/dist/zabi-components.css';
+```
+
+### With Dark Mode
+
+```css
+@import "tailwindcss";
+@import 'zabi-components/theme-only';
+@import 'zabi-components/theme-dark-only'; /* Add dark mode support */
+@import 'zabi-components/dist/zabi-components.css';
+```
+
+### Extending the Theme
+
+You can extend the theme with custom colors and fonts:
+
+```css
+@import "tailwindcss";
+@import 'zabi-components/theme-only';
+
+/* Your custom theme extensions */
+@theme {
+  --font-family-title: 'Your Font', sans-serif;
+  --color-custom-primary: #ff0000;
+}
+
+@import 'zabi-components/dist/zabi-components.css';
+```
+
+> 📖 **Complete Theme Guide**: See [THEME.md](./THEME.md) for comprehensive documentation on theme usage, customization, dark mode, and advanced patterns.
+
 ## Import Methods
 
 Zabi Components supports multiple import patterns:
@@ -168,16 +219,16 @@ import type { ButtonEvents, InputEvents } from 'zabi-components/types';
 
 | Component | Category | Description | Key Features |
 |-----------|----------|-------------|--------------|
-| **Card** | Atom | Clean card container | Simple, interactive, image support |
+| **Card** | Atom | Clean card container | Simple, interactive, image support, compound components, 4 variants |
 | **Form** | Molecule | Simple form wrapper | FormData handling, clean API |
 | **Layout** | Molecule | Page layout system | Header, main, footer slots |
 | **Navigation** | Organism | Clean navigation | Header/sidebar variants, active state |
-| **Button** | Atom | Action button | 3 variants (primary, secondary, danger) |
+| **Button** | Atom | Action button | 6 variants (primary, secondary, danger, ghost, outline, link) |
 | **Input** | Atom | Form input | Essential props, accessibility |
 | **Badge** | Atom | Status indicator | 5 color variants, closable |
-| **Modal** | Molecule | Overlay dialog | Simple backdrop, close button |
+| **Modal** | Molecule | Overlay dialog | Focus trap, keyboard navigation, focus return |
 | **Tabs** | Molecule | Tab navigation | Keyboard navigation, 2 variants |
-| **Dropdown** | Molecule | Dropdown menu | CSS-only positioning |
+| **Dropdown** | Molecule | Dropdown menu | CSS-only positioning, keyboard navigation, ARIA support |
 | **ImageUpload** | Molecule | File upload | Direct selection, preview |
 | **Navbar** | Organism | Navigation bar | Mobile menu, responsive |
 
@@ -461,35 +512,67 @@ All components will automatically switch to their dark mode variants without any
 
 ### Card Component
 
+Card component supports two APIs: prop-based (backward compatible) and compound components (recommended).
+
+#### Prop-based API (Backward Compatible)
+
 ```svelte
 <Card
-  variant="default" | "elevated" | "outlined"
-  density="comfortable" | "compact"
-  disabled={boolean}
-  loading={boolean}
-  className={string}
-  on:click={(e) => console.log(e.detail.value, e.detail.event)}
+  title="Card Title"
+  description="Card description"
+  image="image-url.jpg"
+  variant="default" | "elevated" | "outlined" | "flat"
+  size="sm" | "md" | "lg"
+  fullWidth={boolean}
+  onclick={(e) => console.log('Card clicked', e)}
 >
-  <div slot="header">Header Content</div>
-  Main Content
-  <div slot="footer">Footer Content</div>
+  Additional Content
+</Card>
+```
+
+#### Compound Component API (Recommended)
+
+```svelte
+<Card variant="elevated">
+  <CardHeader>
+    <CardTitle>Card Title</CardTitle>
+    <CardDescription>Card description</CardDescription>
+  </CardHeader>
+  <CardContent>
+    Main content goes here
+  </CardContent>
+  <CardFooter>
+    <Button variant="primary">Action</Button>
+  </CardFooter>
 </Card>
 ```
 
 **Props:**
 - `variant`: Card style variant (default: "default")
-- `density`: Card density (default: "comfortable")
-- `disabled`: Disable interactions (default: false)
-- `loading`: Show loading state (default: false)
-- `className`: Additional CSS classes
-
-**Slots:**
-- `header`: Card header content
-- `default`: Main card content
-- `footer`: Card footer content
+  - `default`: Standard card with subtle shadow
+  - `elevated`: Card with stronger shadow (elevated appearance)
+  - `outlined`: Card with border, no shadow
+  - `flat`: Card with no shadow, no border (minimal)
+- `size`: Card size (default: "md")
+- `fullWidth`: Whether card takes full width (default: true)
+- `title`: Card title (old API)
+- `description`: Card description (old API)
+- `image`: Card image URL (old API)
+- `onclick`: Click handler for interactive cards
+
+**Compound Components:**
+- `CardHeader`: Header section container
+- `CardContent`: Main content area
+- `CardFooter`: Footer section container
+- `CardTitle`: Title component (supports heading levels 1-6)
+- `CardDescription`: Description text component
 
 **Events:**
-- `click`: Fired when card is clicked - `{ detail: { value: true, event: MouseEvent } }`
+- `onclick`: Native click event - `MouseEvent`
+
+**Keyboard Navigation (Interactive Cards):**
+- **Tab**: Focus the card
+- **Enter / Space**: Activate card click handler
 
 ### Alert Component
 
@@ -1147,6 +1230,75 @@ function handleFormSubmit(event: any) {
 - Test with screen readers
 - Maintain proper color contrast ratios
 
+## Compound Components
+
+Zabi Components supports compound component patterns for flexible composition:
+
+### Card Compound Components
+
+```svelte
+<script>
+  import { Card, CardHeader, CardContent, CardFooter, CardTitle, CardDescription, Button } from 'zabi-components';
+</script>
+
+<Card variant="elevated">
+  <CardHeader>
+    <CardTitle>Card Title</CardTitle>
+    <CardDescription>
+      This is a description using compound components.
+    </CardDescription>
+  </CardHeader>
+  <CardContent>
+    <p>Main content area with flexible composition.</p>
+  </CardContent>
+  <CardFooter>
+    <Button variant="primary">Save</Button>
+    <Button variant="ghost">Cancel</Button>
+  </CardFooter>
+</Card>
+```
+
+## Accessibility
+
+Zabi Components is built with accessibility in mind:
+
+### WCAG 2.1 AA Compliance
+- Comprehensive ARIA attributes
+- Proper semantic HTML
+- Keyboard navigation support
+- Focus management
+- Screen reader compatibility
+
+### Keyboard Navigation
+- **Tab**: Navigate between interactive elements
+- **Enter/Space**: Activate buttons and links
+- **Arrow Keys**: Navigate within components (Tabs, Navigation, Dropdown)
+- **Escape**: Close modals and overlays
+- **Home/End**: Jump to first/last item in lists
+
+### Focus Management
+- Focus trap in modals
+- Focus return after closing modals
+- Visible focus indicators
+- Logical tab order
+
+See [ACCESSIBILITY.md](./docs/ACCESSIBILITY.md) and [KEYBOARD_NAVIGATION.md](./docs/KEYBOARD_NAVIGATION.md) for detailed documentation.
+
+## Variant System
+
+Zabi Components uses a consistent variant system:
+
+### Semantic Variants
+Used for state indication: `default`, `success`, `warning`, `error`, `info`
+
+### Style Variants
+Used for visual appearance: Button (`primary`, `secondary`, `outline`, `link`, etc.), Card (`elevated`, `outlined`, `flat`)
+
+### Size Variants
+Consistent across components: `sm`, `md`, `lg`
+
+See [VARIANTS.md](./docs/VARIANTS.md) for complete variant documentation.
+
 ## Support
 
 For support, please open an issue on GitHub or contact the maintainers.

package/dist/SSRSafe.svelte

@@ -1,4 +1,3 @@
-<!-- SSR-safe wrapper component for zabi-components -->
 <script lang="ts">
     import { onMount } from "svelte";
 
@@ -33,7 +32,6 @@
         {@render children?.()}
     </FallbackComponent>
 {:else}
-    <!-- Fallback content for SSR -->
     <div class="zabi-ssr-fallback">
         {@render children?.()}
     </div>
@@ -41,7 +39,6 @@
 
 <style>
     .zabi-ssr-fallback {
-        /* Minimal styling for SSR fallback */
         display: contents;
     }
 </style>

package/dist/atoms/Badge.svelte

@@ -1,96 +1,81 @@
-<!--
-    Badge Component - SSR-safe and robust
-    
-    A simple badge component with proper SSR handling and defensive programming
-    to prevent DOM access errors during hydration and rapid state changes.
--->
 <script lang="ts">
     import { Check, AlertTriangle, X, Info } from "@lucide/svelte";
-    // Props using Svelte 5 runes
+    import type {
+        ExtendedSemanticVariant,
+        SizeVariant,
+    } from "../../types/variants.js";
+
+    interface Props {
+        variant?: ExtendedSemanticVariant;
+        size?: SizeVariant;
+        text: string;
+        showIcon?: boolean;
+    }
+
     let {
         variant = "default",
         size = "md",
         text = "",
-        showIcon = true,
-    }: {
-        variant?:
-            | "default"
-            | "success"
-            | "warning"
-            | "error"
-            | "info"
-            | "neutral"
-            | "energetic";
-        size?: "sm" | "md" | "lg";
-        text: string;
-        showIcon?: boolean;
-    } = $props();
+        showIcon = false,
+    }: Props = $props();
 
-    // Class computation using conditional logic with full class names
     const classes = $derived(() => {
         const baseClasses =
-            "inline-flex items-center font-medium border rounded-md";
+            "inline-flex items-center font-medium border rounded-xs";
 
-        // Size classes - using full class names
         const sizeClass =
             size === "sm"
                 ? "px-2 py-0.5 text-xs"
                 : size === "lg"
                   ? "px-4 py-2 text-base"
-                  : "px-3 py-1 text-sm"; // default md
+                  : "px-3 py-1 text-sm";
 
-        // Variant classes - using semantic color system with improved WCAG contrast
-        // Using colored backgrounds with white text for better contrast ratios (4.5:1+)
-        // Using darker shades for warning and energetic to ensure WCAG AA compliance
-        // Note: Using text-white instead of text-inverse to ensure light text in both light and dark modes
         const variantClass =
             variant === "success"
-                ? "bg-success border-success text-white"
+                ? "bg-success border-success text-card"
                 : variant === "warning"
-                  ? "bg-warning border-warning text-white"
+                  ? "bg-warning border-warning text-card"
                   : variant === "error"
-                    ? "bg-error border-error text-white"
+                    ? "bg-error border-error text-card"
                     : variant === "info"
-                      ? "bg-info border-info text-white"
+                      ? "bg-info border-info text-card"
                       : variant === "neutral"
-                        ? "bg-neutral border-neutral text-white"
+                        ? "bg-neutral border-neutral text-card"
                         : variant === "energetic"
-                          ? "bg-energetic border-energetic text-white"
-                          : "bg-secondary border-secondary text-white"; // default
+                          ? "bg-energetic border-energetic text-card"
+                          : "bg-secondary border-secondary text-card";
 
         return `${baseClasses} ${sizeClass} ${variantClass}`.trim();
     });
 
-    // Icon size based on badge size
     const iconSize = $derived(() => {
-        return size === "sm" ? 12 : size === "lg" ? 20 : 16; // default md
+        return size === "sm" ? 12 : size === "lg" ? 20 : 16;
     });
 
-    // Icon spacing class
     const iconSpacingClass = $derived(() => {
-        return size === "sm" ? "mr-1" : size === "lg" ? "mr-2" : "mr-1.5"; // default md
+        return size === "sm" ? "mr-1" : size === "lg" ? "mr-2" : "mr-1.5";
     });
 </script>
 
 <span class={classes()}>
     {#if showIcon}
         {#if variant === "success"}
-            <Check size={iconSize()} class="{iconSpacingClass()} text-white" />
+            <Check size={iconSize()} class="{iconSpacingClass()} text-card" />
         {:else if variant === "warning"}
             <AlertTriangle
                 size={iconSize()}
-                class="{iconSpacingClass()} text-white"
+                class="{iconSpacingClass()} text-card"
             />
         {:else if variant === "error"}
-            <X size={iconSize()} class="{iconSpacingClass()} text-white" />
+            <X size={iconSize()} class="{iconSpacingClass()} text-card" />
         {:else if variant === "info"}
-            <Info size={iconSize()} class="{iconSpacingClass()} text-white" />
+            <Info size={iconSize()} class="{iconSpacingClass()} text-card" />
         {:else if variant === "neutral"}
-            <Info size={iconSize()} class="{iconSpacingClass()} text-white" />
+            <Info size={iconSize()} class="{iconSpacingClass()} text-card" />
         {:else if variant === "energetic"}
-            <Info size={iconSize()} class="{iconSpacingClass()} text-white" />
+            <Info size={iconSize()} class="{iconSpacingClass()} text-card" />
         {:else}
-            <Info size={iconSize()} class="{iconSpacingClass()} text-white" />
+            <Info size={iconSize()} class="{iconSpacingClass()} text-card" />
         {/if}
     {/if}
     {text}

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

@@ -1,9 +1,10 @@
-type $$ComponentProps = {
-    variant?: "default" | "success" | "warning" | "error" | "info" | "neutral" | "energetic";
-    size?: "sm" | "md" | "lg";
+import type { ExtendedSemanticVariant, SizeVariant } from "../../types/variants.js";
+interface Props {
+    variant?: ExtendedSemanticVariant;
+    size?: SizeVariant;
     text: string;
     showIcon?: boolean;
-};
-declare const Badge: import("svelte").Component<$$ComponentProps, {}, "">;
+}
+declare const Badge: import("svelte").Component<Props, {}, "">;
 type Badge = ReturnType<typeof Badge>;
 export default Badge;

package/dist/atoms/Button.svelte

@@ -1,9 +1,10 @@
 <script lang="ts">
     import type { Snippet } from "svelte";
+    import type { ButtonVariant, SizeVariant } from "../../types/variants.js";
 
     interface Props {
-        variant?: "primary" | "secondary" | "danger" | "ghost";
-        size?: "sm" | "md" | "lg";
+        variant?: ButtonVariant;
+        size?: SizeVariant;
         disabled?: boolean;
         type?: "button" | "submit" | "reset";
         text?: string;
@@ -22,7 +23,6 @@
         ...restProps
     }: Props = $props();
 
-    // Size classes matching M3 design specifications
     const sizeClass = $derived(() => {
         if (size === "sm") {
             return {
@@ -32,46 +32,47 @@
                 leading: "leading-5",
                 tracking: "tracking-[0.1px]",
                 radius: "rounded-lg",
-                gap: "gap-2"
+                gap: "gap-2",
             };
         } else if (size === "lg") {
             return {
-                padding: "px-12 py-8",
-                text: "text-2xl",
+                padding: "px-8 py-4",
+                text: "text-lg",
                 font: "font-normal",
                 leading: "leading-8",
                 tracking: "tracking-normal",
-                radius: "rounded-2xl",
-                gap: "gap-3"
+                radius: "rounded-xl",
+                gap: "gap-3",
             };
         } else {
-            // default md
             return {
-                padding: "px-6 py-4",
+                padding: "px-5 py-3",
                 text: "text-base",
                 font: "font-medium",
                 leading: "leading-6",
                 tracking: "tracking-[0.15px]",
                 radius: "rounded-lg",
-                gap: "gap-2"
+                gap: "gap-2",
             };
         }
     });
 
-    // Variant classes using semantic action colors
     const variantClass = $derived(() => {
         return variant === "primary"
-            ? "bg-action-primary text-inverse hover:bg-action-primary-hover active:bg-action-primary-active focus:ring-2 focus:ring-brand-500 focus:ring-offset-2"
+            ? "bg-action-primary text-action-primary hover:bg-action-primary-hover active:bg-action-primary-active focus:ring-2 focus:ring-brand-500 focus:ring-offset-2"
             : variant === "secondary"
-              ? "bg-brand-100 text-brand-800 hover:bg-brand-200 active:bg-brand-300 focus:ring-2 focus:ring-brand-500 focus:ring-offset-2"
+              ? "bg-action-secondary text-headline hover:bg-action-secondary-hover active:bg-action-secondary-active focus:ring-2 focus:ring-brand-500 focus:ring-offset-2"
               : variant === "danger"
                 ? "bg-action-danger text-inverse hover:bg-action-danger-hover active:bg-action-danger-active focus:ring-2 focus:ring-red-500 focus:ring-offset-2"
                 : variant === "ghost"
-                  ? "bg-transparent text-headline hover:bg-surface-hover active:bg-surface-active focus:ring-2 focus:ring-stone-500 focus:ring-offset-2 disabled:text-disabled"
-                  : "bg-action-primary text-inverse hover:bg-action-primary-hover active:bg-action-primary-active focus:ring-2 focus:ring-brand-500 focus:ring-offset-2"; // default primary
+                  ? "bg-transparent text-headline hover:bg-base-100 active:bg-base-200 focus:ring-2 focus:ring-base-500 focus:ring-offset-2 disabled:text-disabled"
+                  : variant === "outline"
+                    ? "bg-transparent border-2 border-action-primary text-headline hover:bg-action-secondary hover:text-action-primary active:bg-action-primary-active active:text-action-primary focus:ring-2 focus:ring-brand-500 focus:ring-offset-2 disabled:border-disabled disabled:text-disabled"
+                    : variant === "link"
+                      ? "text-brand-700 active:text-brand-700 underline-offset-4 hover:underline focus:ring-2 focus:ring-brand-500 focus:ring-offset-2 disabled:text-disabled disabled:no-underline"
+                      : "bg-action-primary text-action-primary hover:bg-action-primary-hover active:bg-action-primary-active focus:ring-2 focus:ring-brand-500 focus:ring-offset-2";
     });
 
-    // Button classes matching M3 design pattern
     const buttonClasses = $derived(() => {
         const sizeStyles = sizeClass();
         const baseClasses =

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

@@ -1,7 +1,8 @@
 import type { Snippet } from "svelte";
+import type { ButtonVariant, SizeVariant } from "../../types/variants.js";
 interface Props {
-    variant?: "primary" | "secondary" | "danger" | "ghost";
-    size?: "sm" | "md" | "lg";
+    variant?: ButtonVariant;
+    size?: SizeVariant;
     disabled?: boolean;
     type?: "button" | "submit" | "reset";
     text?: string;

package/dist/atoms/Card.svelte

@@ -1,12 +1,14 @@
 <script lang="ts">
     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?: "sm" | "md" | "lg";
+        size?: SizeVariant;
+        variant?: CardVariant;
         fullWidth?: boolean;
         children?: Snippet;
     }
@@ -17,24 +19,48 @@
         image = "",
         onclick,
         size = "md",
+        variant = "default",
         fullWidth = true,
         children,
         ...restProps
     }: Props = $props();
 
     const sizeClass = $derived(() => {
-        return size === "sm" ? "p-4" : size === "lg" ? "p-8" : "p-6"; // default md
+        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 cardClasses = $derived(() => {
         const baseClasses =
-            "rounded-lg transition-all duration-200 min-w-64 bg-surface-elevated shadow-sm";
+            `rounded-lg transition-all duration-200 ${variantClasses()}`;
         const interactiveClasses = onclick
-            ? "cursor-pointer hover:shadow-lg hover:bg-surface-hover"
+            ? 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() : "";
 
-        return `${baseClasses} ${interactiveClasses} ${widthClasses} ${sizeClass()}`.trim();
+        return `${baseClasses} ${interactiveClasses} ${widthClasses} ${minWidthClass} ${paddingClass}`.trim();
     });
 
     const titleClasses = $derived(() => {
@@ -43,7 +69,6 @@
         } else if (size === "lg") {
             return "text-2xl font-medium mb-4 text-headline";
         } else {
-            // default md
             return "text-xl font-medium mb-3 text-headline";
         }
     });
@@ -54,30 +79,56 @@
         } else if (size === "lg") {
             return "text-base text-description mb-5";
         } else {
-            // default md
             return "text-sm text-description mb-4";
         }
     });
+
+    function handleKeydown(event: KeyboardEvent) {
+        if (onclick && (event.key === "Enter" || event.key === " ")) {
+            event.preventDefault();
+            onclick(event as unknown as MouseEvent);
+        }
+    }
+
+    const cardRole = $derived(onclick ? "button" : undefined);
+    const cardTabIndex = $derived(onclick ? 0 : undefined);
+    const cardAriaLabel = $derived(onclick && title ? title : undefined);
 </script>
 
-<div class={cardClasses()} {onclick} {...restProps}>
-    {#if image}
-        <img
-            src={image}
-            alt={title}
-            class="w-full h-48 object-cover rounded-lg mb-4"
-        />
-    {/if}
+<div 
+    class={cardClasses()} 
+    {onclick} 
+    role={cardRole}
+    tabindex={cardTabIndex}
+    aria-label={cardAriaLabel}
+    onkeydown={handleKeydown}
+    {...restProps}
+>
+    {#if useOldAPI}
+        <!-- Old API: Using title/description/image props -->
+        {#if image}
+            <img
+                src={image}
+                alt={title}
+                class="w-full h-48 object-cover rounded-lg mb-4"
+            />
+        {/if}
 
-    {#if title}
-        <h3 class={titleClasses()}>{title}</h3>
-    {/if}
+        {#if title}
+            <h3 class={titleClasses()}>{title}</h3>
+        {/if}
 
-    {#if description}
-        <p class={descriptionClasses()}>{description}</p>
-    {/if}
+        {#if description}
+            <p class={descriptionClasses()}>{description}</p>
+        {/if}
 
-    {#if children}
-        {@render children()}
+        {#if children}
+            {@render children()}
+        {/if}
+    {:else}
+        <!-- New API: Using compound components (CardHeader, CardContent, CardFooter) -->
+        {#if children}
+            {@render children()}
+        {/if}
     {/if}
 </div>

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

@@ -1,10 +1,12 @@
 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?: "sm" | "md" | "lg";
+    size?: SizeVariant;
+    variant?: CardVariant;
     fullWidth?: boolean;
     children?: Snippet;
 }