@miozu/jera 0.7.0 → 0.7.2

package/CLAUDE.md

@@ -1,858 +1,117 @@
-# @miozu/jera - AI Context File
+# @miozu/jera - Component Library
 
-**Package:** @miozu/jera
-**Purpose:** Zero-dependency, AI-first component library for Svelte 5
-**Author:** Nicholas Glazer <glazer.nicholas@gmail.com>
-**Last Updated:** February 2026
+Zero-dependency, AI-first component library for Svelte 5.
 
----
+## Architecture
 
-## Architecture Overview
-
-jera follows a **5-layer architecture** designed for portability and AI-assisted development:
+5-layer design for portability and AI-assisted development:
 
 1. **W3C Design Tokens (DTCG)** - `tokens.json` as single source of truth
-2. **CSS Custom Properties** - Generated from tokens, used by all styles
+2. **CSS Custom Properties** - Generated from tokens
 3. **Pure Modern CSS** - Framework-agnostic component styles
 4. **Svelte 5 Wrappers** - Thin components using native runes
-5. **AI Documentation** - llms.txt standard for AI assistants
-
-**Full architecture documentation:** [ARCHITECTURE.md](./ARCHITECTURE.md)
-
-### Key Design Principles
-
-- **CSS is the library** - Pure CSS is 100% portable across frameworks
-- **Zero dependencies** - No runtime external dependencies
-- **Browser-native** - Modern CSS features over JS polyfills
-- **Theme-agnostic** - Components work in both themes automatically
-- **AI-first** - Documentation optimized for AI assistants
+5. **AI Documentation** - llms.txt standard
 
----
+**Key Principles:** CSS is the library | Zero dependencies | Theme-agnostic | AI-first
 
 ## Project Structure
 
 ```
 jera/
 ├── src/
-│   ├── index.js              # Main exports
-│   ├── tokens/               # Design tokens (CSS custom properties)
-│   │   ├── index.css         # Bundle all tokens
-│   │   ├── colors.css        # Miozu Base16 palette
-│   │   ├── spacing.css       # 4px-based scale
-│   │   ├── typography.css    # Font system
-│   │   └── effects.css       # Shadows, radius, transitions
-│   ├── utils/
-│   │   ├── cn.svelte.js      # cn(), cv() class utilities
-│   │   └── reactive.svelte.js # ThemeState, reactive helpers
-│   ├── actions/
-│   │   └── index.js          # Svelte actions
-│   └── components/
-│       ├── primitives/       # Button, Badge, Divider, Avatar
-│       ├── forms/            # Input, Select, Checkbox, Switch
-│       ├── feedback/         # Toast, Skeleton, ProgressBar, Spinner
-│       ├── overlays/         # Modal, Popover
-│       ├── navigation/       # Tabs, Accordion, Sidebar
-│       └── docs/             # CodeBlock, PropsTable, SplitPane, DocSection
-├── llms.txt                  # AI documentation index
-├── CLAUDE.md                 # This file
-└── package.json
+│   ├── tokens/           # colors.css, spacing.css, typography.css
+│   ├── utils/            # cn.svelte.js, reactive.svelte.js (ThemeState)
+│   ├── actions/          # clickOutside, focusTrap, portal, escapeKey
+│   └── components/       # primitives/, forms/, feedback/, overlays/, navigation/
+└── llms.txt
 ```
 
----
-
-## Coding Standards
-
-### Svelte 5 Patterns (REQUIRED)
-- Use `$props()` for component props (single call only)
-- Use `$state()` for reactive local state
-- Use `$derived()` for computed values
-- Use `$effect()` sparingly, only for side effects
-- Use `$bindable()` for two-way binding props
-
-### Component Template
-```svelte
-<script>
-  let {
-    variant = 'default',
-    size = 'md',
-    disabled = false,
-    class: className = '',
-    ...rest
-  } = $props();
-
-  const computedClass = $derived(/* class logic */);
-</script>
+## Color System
 
-<element class={computedClass} {disabled} {...rest}>
-  {@render children?.()}
-</element>
-```
+Uses Base16 naming: `base00`-`base0F` (hex digits).
 
-### Class Variants (cv) Pattern
-```javascript
-export const componentStyles = cv({
-  base: 'base-classes here',
-  variants: {
-    variantName: {
-      option1: 'classes-for-option1',
-      option2: 'classes-for-option2'
-    }
-  },
-  compounds: [
-    { condition: { variant: 'x', size: 'y' }, class: 'compound-classes' }
-  ],
-  defaults: { variantName: 'option1' }
-});
-```
+**Full reference:** `docs/ai-context/base16-colors.md`
 
-### Naming Conventions
-- Components: PascalCase (`Button.svelte`)
-- Utilities: camelCase (`getTheme`)
-- CSS tokens: kebab-case (`--color-primary`)
-- Actions: camelCase (`clickOutside`)
-
----
-
-## Miozu Base16 Color System
-
-Uses standard Base16 naming: `base00`-`base0F` (hex digits, NOT decimal).
-
-### Grayscale (base00-base07)
-| Token | Dark Theme | Light Theme | Usage |
-|-------|------------|-------------|-------|
-| `--color-base00` | #0f1419 | #ffffff | Primary background |
-| `--color-base01` | #1a1f26 | #f8f9fa | Surface/card |
-| `--color-base02` | #242a33 | #f1f3f5 | Selection/hover |
-| `--color-base03` | #4a5568 | #adb5bd | Muted/disabled |
-| `--color-base04` | #a0aec0 | #6c757d | Secondary text |
-| `--color-base05` | #e2e8f0 | #212529 | Primary text |
-| `--color-base06` | #f7fafc | #1a1d20 | High emphasis |
-| `--color-base07` | #ffffff | #0d0f10 | Maximum contrast |
-
-### Accents (base08-base0F)
-| Token | Color | Usage |
-|-------|-------|-------|
-| `--color-base08` | Red | Error |
-| `--color-base09` | Orange | Warning |
-| `--color-base0A` | Yellow | Highlight |
-| `--color-base0B` | Green | Success |
-| `--color-base0C` | Cyan | Info |
-| `--color-base0D` | Blue | Primary |
-| `--color-base0E` | Purple | Accent |
-| `--color-base0F` | Brown/Orange | Secondary accent |
-
-### Semantic Mappings
-```css
---color-bg: var(--color-base00);
---color-surface: var(--color-base01);
---color-text: var(--color-base05);
---color-text-strong: var(--color-base07);
---color-primary: var(--color-base0D);
---color-success: var(--color-base0B);
---color-error: var(--color-base08);
-```
+## Component API Quick Reference
 
----
+**Button:** `variant` (primary|secondary|ghost|outline|danger|success), `size` (xs-xl), `disabled`, `loading`, `href`
 
-## Component API Reference
+**Input:** `bind:value`, `type`, `placeholder`, `disabled`, `required`
 
-### Button
-```svelte
-<Button
-  variant="primary|secondary|ghost|outline|danger|success"
-  size="xs|sm|md|lg|xl"
-  disabled={boolean}
-  loading={boolean}
-  fullWidth={boolean}
-  href={string}        // Renders as <a> if provided
-  onclick={function}
->
-  Content
-</Button>
-```
+**Select:** `options=[{value, label}]`, `bind:value`, `placeholder`
 
-### Input
-```svelte
-<Input
-  bind:value={string}
-  type="text|email|password|number|..."
-  placeholder={string}
-  disabled={boolean}
-  required={boolean}
-  oninput={function}
-  onchange={function}
-/>
-```
+**Badge:** `variant` (default|primary|success|warning|error), `size` (sm|md|lg)
 
-### Select
-```svelte
-<Select
-  options={[{ value, label }]}
-  bind:value={any}
-  placeholder={string}
-  labelKey="label"
-  valueKey="value"
-  disabled={boolean}
-  onchange={function}
-/>
-```
+**Modal:** `bind:open`, `title`, `size` (sm-xl), `variant`, `footer` (snippet)
 
-### Badge
-```svelte
-<Badge
-  variant="default|primary|secondary|success|warning|error"
-  size="sm|md|lg"
->
-  Text
-</Badge>
-```
+**Toast:** Use `createToastContext()` in root, `getToastContext()` anywhere
 
-### Toast
-```svelte
-<!-- In root layout -->
-<script>
-  import { Toast, createToastContext } from '@miozu/jera';
-  const toast = createToastContext();
-</script>
-<Toast />
+**Tabs:** `tabs=[{id, label, badge?}]`, `bind:active`, `variant` (default|underline|pills)
 
-<!-- Usage anywhere -->
-<script>
-  import { getToastContext } from '@miozu/jera';
-  const toast = getToastContext();
-  toast.success('Message');
-  toast.error('Error message');
-</script>
-```
+**LeftBar:** `bind:collapsed`, `persistKey`, snippets: `header`, `navigation`, `footer`
 
-### Modal
-```svelte
-<script>
-  import { Modal, Button } from '@miozu/jera';
-  let showModal = $state(false);
-</script>
+**LeftBarItem:** `href`, `label`, `icon`, `active`, `badge`, `expandable`, `subroutes`
 
-<Button onclick={() => showModal = true}>Open Modal</Button>
+## Theme Management
 
-<Modal bind:open={showModal} title="Confirm Action" variant="danger">
-  <p>Are you sure you want to proceed?</p>
-  {#snippet footer()}
-    <Button variant="ghost" onclick={() => showModal = false}>Cancel</Button>
-    <Button variant="danger" onclick={handleConfirm}>Confirm</Button>
-  {/snippet}
-</Modal>
-```
+Singleton pattern with `miozu-theme` storage key.
 
-Props: `open`, `title`, `size` (sm/md/lg/xl), `variant` (default/danger/warning/success/info), `closeOnBackdrop`, `closeOnEscape`, `showClose`, `children`, `footer`, `icon`, `onclose`
+**Full reference:** `docs/ai-context/theme-management.md`
 
-### Popover
 ```svelte
+<!-- +layout.svelte -->
 <script>
-  import { Popover, Button } from '@miozu/jera';
+  import { getTheme } from '@miozu/jera';
+  const themeState = getTheme();
+  onMount(() => { themeState.sync(); themeState.init(); });
 </script>
-
-<Popover content="Helpful tooltip text" position="top">
-  <Button>Hover me</Button>
-</Popover>
-```
-
-Props: `content`, `position` (top/bottom/left/right), `delay` ({show, hide}), `offset`
-
-### Divider
-```svelte
-<Divider />
-<Divider orientation="vertical" />
-<Divider>or continue with</Divider>
-```
-
-Props: `orientation` (horizontal/vertical), `thickness`, `spacing`, `children`
-
-### Stat
-```svelte
-<Stat value="42" label="Users" />
-<Stat value="95%" label="Uptime" status="success" />
-<Stat value="75" max={100} label="Progress" showBar />
-<Stat value="12" unit="/15" label="Tasks" status="warning" />
-<Stat value="8" label="Errors" href="/errors" status="error" />
-```
-
-Props: `value`, `label`, `unit`, `secondary`, `status` (success/warning/error/info), `size` (sm/md/lg), `showBar`, `barValue`, `max`, `href`
-
-### Alert
-```svelte
-<Alert variant="info">This is an informational message.</Alert>
-<Alert variant="warning" title="Warning">Please review your settings.</Alert>
-<Alert variant="error" dismissible onclose={() => showAlert = false}>
-  An error occurred.
-</Alert>
-<Alert variant="success">
-  {#snippet icon()}
-    <CheckIcon size={16} />
-  {/snippet}
-  Your changes have been saved.
-</Alert>
-```
-
-Props: `variant` (info/success/warning/error), `title`, `dismissible`, `size` (sm/md/lg), `onclose`, `icon` (snippet), `actions` (snippet)
-
-### Avatar
-```svelte
-<Avatar src="/user.jpg" alt="John Doe" />
-<Avatar name="John Doe" />
-<Avatar src="/user.jpg" status="online" size="lg" />
-```
-
-Props: `src`, `alt`, `name`, `size` (xs/sm/md/lg/xl/2xl), `status` (online/offline/busy/away)
-
-### Skeleton
-```svelte
-<Skeleton width="80%" />
-<Skeleton variant="circle" size="48px" />
-<Skeleton variant="rect" width="100%" height="200px" />
-<Skeleton lines={3} />
-```
-
-Props: `variant` (text/heading/circle/rect), `width`, `height`, `size`, `lines`, `animate`
-
-### ProgressBar
-```svelte
-<ProgressBar value={65} />
-<ProgressBar value={80} showLabel variant="success" />
-<ProgressBar indeterminate />
 ```
 
-Props: `value`, `max`, `size` (sm/md/lg), `variant` (primary/success/warning/error/info), `showLabel`, `label`, `indeterminate`
-
-### Spinner
-```svelte
-<Spinner />
-<Spinner size="lg" color="var(--color-base11)" />
-```
-
-Props: `size` (xs/sm/md/lg/xl), `color`, `label`
-
-### Tabs
-```svelte
-<script>
-  import { Tabs } from '@miozu/jera';
-  let activeTab = $state('tab1');
-</script>
-
-<Tabs
-  tabs={[
-    { id: 'tab1', label: 'Overview' },
-    { id: 'tab2', label: 'Settings', badge: 3 },
-    { id: 'tab3', label: 'Analytics', disabled: true }
-  ]}
-  bind:active={activeTab}
-  variant="underline"
-/>
-```
+## Svelte 5 Patterns
 
-Props: `tabs` (array), `active`, `variant` (default/underline/pills), `size` (sm/md/lg), `fullWidth`, `onchange`
+**Full reference:** `docs/ai-context/svelte5-patterns.md`
 
-### Accordion
 ```svelte
 <script>
-  import { Accordion, AccordionItem } from '@miozu/jera';
+  let { variant = 'default', class: className = '', ...rest } = $props();
+  const classes = $derived(/* ... */);
 </script>
 
-<Accordion multiple>
-  <AccordionItem id="section1" title="Section 1">
-    Content for section 1
-  </AccordionItem>
-  <AccordionItem id="section2" title="Section 2">
-    Content for section 2
-  </AccordionItem>
-</Accordion>
+<div class={classes} {...rest}>
+  {@render children?.()}
+</div>
 ```
 
-Accordion props: `expanded` (array of ids), `multiple`
-AccordionItem props: `id`, `title`, `disabled`
-
-### LeftBar (Sidebar Navigation)
-
-A lightweight, collapsible sidebar for admin-style navigation.
-
-```svelte
-<script>
-  import { LeftBar, LeftBarSection, LeftBarItem, LeftBarGroup, LeftBarToggle, createActiveChecker } from '@miozu/jera';
-  import { page } from '$app/stores';
-  import { Home, Settings, Users, Building2 } from 'lucide-svelte';
-
-  let collapsed = $state(false);
-  const isActive = createActiveChecker(() => $page.url.pathname);
-</script>
-
-<LeftBar bind:collapsed persistKey="my-sidebar">
-  {#snippet header()}
-    <div class="logo">MyApp</div>
-  {/snippet}
-
-  {#snippet navigation()}
-    <LeftBarSection>
-      <LeftBarItem href="/" icon={Home} label="Dashboard" active={isActive('/', 'exact')} />
-      <LeftBarItem href="/users" icon={Users} label="Users" badge={5} active={isActive('/users')} />
-    </LeftBarSection>
-
-    <LeftBarSection title="Management">
-      <LeftBarItem
-        label="Organization"
-        icon={Building2}
-        expandable
-        subroutes={[
-          { label: 'Members', href: '/org/members' },
-          { label: 'Settings', href: '/org/settings' }
-        ]}
-      />
-    </LeftBarSection>
-
-    <!-- Generic group for accounts, projects, workspaces, etc. -->
-    <LeftBarGroup
-      title="Connected Accounts"
-      items={accounts}
-      bind:expanded={accountsExpanded}
-      onItemClick={(account) => goto(`/account/${account.id}`)}
-      onAddClick={() => showConnectModal = true}
-      addLabel="Connect account"
-    />
-  {/snippet}
-
-  {#snippet footer()}
-    <LeftBarToggle />
-  {/snippet}
-</LeftBar>
-```
+## Class Variants (cv)
 
-**LeftBar** props: `collapsed` (bindable), `persistKey`, `header` (snippet), `navigation` (snippet), `footer` (snippet)
-
-**LeftBarSection** props: `title`, `class`
-
-**LeftBarItem** props:
-- `href` - Link destination (renders as `<a>`)
-- `label` - Display text
-- `icon` - Lucide icon component
-- `active` - Boolean for active state
-- `badge` - Number/string for badge count
-- `expandable` - Enable expand/collapse
-- `expanded` - Bindable expansion state
-- `subroutes` - Array of `{ label, href }` for expandable items
-- `preload` - Boolean for SvelteKit preload-data (default: true)
-- `leading` - Snippet for content before icon
-- `trailing` - Snippet for content after label (custom badges, etc.)
-- `isActiveRoute` - Function to check subroute active state
-
-**LeftBarGroup** props (generic collection for accounts, projects, etc.):
-- `title` - Section header
-- `items` - Array of items to display
-- `expanded` - Bindable expansion state
-- `expandedItems` - Object tracking which items are expanded
-- `expandable` - Enable item-level expansion
-- `showAdd` - Show add button
-- `addLabel` - Add button text
-- `showCount` - Show item count badge
-- `onItemClick` - Item click handler
-- `onAddClick` - Add button handler
-- `getItemId`, `getItemName`, `getItemAvatar`, `getItemPlatform` - Item accessors
-- `getSubroutes` - Function returning subroutes for an item
-- `isItemActive`, `isSubrouteActive` - Active state checkers
-- `item` - Custom item rendering snippet
-
-**createActiveChecker** utility:
 ```javascript
-import { createActiveChecker } from '@miozu/jera';
-import { page } from '$app/stores';
-
-// Create checker with current pathname
-const isActive = createActiveChecker(() => $page.url.pathname);
-
-// Use in components
-<LeftBarItem active={isActive('/dashboard')} />           // prefix match
-<LeftBarItem active={isActive('/dashboard', 'exact')} />  // exact match
-```
-
-### CodeBlock
-```svelte
-<script>
-  import { CodeBlock } from '@miozu/jera';
-</script>
-
-<CodeBlock
-  code={`const greeting = "Hello";`}
-  lang="javascript"
-  filename="example.js"
-  showLineNumbers
-/>
-```
-
-Props: `code`, `lang` (default: javascript), `filename`, `showLineNumbers`, `class`
-
-**Requires:** `shiki` package for syntax highlighting.
-
-### PropsTable
-```svelte
-<script>
-  import { PropsTable } from '@miozu/jera';
-</script>
-
-<PropsTable props={[
-  { name: 'variant', type: 'string', default: '"default"', description: 'Visual style' },
-  { name: 'onclick', type: 'function', required: true, description: 'Click handler' }
-]} />
-```
-
-Props: `props` (array of PropDef), `class`
-
-PropDef: `{ name, type, default?, description, required? }`
-
-### SplitPane
-```svelte
-<script>
-  import { SplitPane, CodeBlock } from '@miozu/jera';
-</script>
-
-<SplitPane ratio="1:1" gap="2rem" stickyRight>
-  {#snippet left()}
-    <h2>Description</h2>
-    <p>Explanation of the feature...</p>
-  {/snippet}
-  {#snippet right()}
-    <CodeBlock code={exampleCode} lang="javascript" />
-  {/snippet}
-</SplitPane>
-```
-
-Props: `left` (snippet), `right` (snippet), `ratio` (e.g., '1:1', '2:1'), `gap`, `minHeight`, `stickyRight`, `class`
-
-### DocSection
-```svelte
-<script>
-  import { DocSection, CodeBlock } from '@miozu/jera';
-</script>
-
-<DocSection id="installation" title="Installation" description="How to install">
-  <CodeBlock code="npm install @miozu/jera" lang="bash" />
-</DocSection>
+export const buttonStyles = cv({
+  base: 'inline-flex items-center justify-center rounded-lg font-medium',
+  variants: {
+    variant: {
+      primary: 'bg-base0D text-white',
+      ghost: 'bg-transparent text-base05 hover:bg-base02'
+    },
+    size: { sm: 'h-8 px-3 text-sm', md: 'h-10 px-4' }
+  },
+  defaults: { variant: 'primary', size: 'md' }
+});
 ```
 
-Props: `id`, `title`, `description`, `level` (2-6), `showAnchor`, `children`, `class`
-
----
+## Actions
 
-## Actions Reference
-
-### clickOutside
 ```svelte
 <div use:clickOutside={() => isOpen = false}>
-```
-
-### focusTrap
-```svelte
 <dialog use:focusTrap={{ enabled: isOpen }}>
-```
-
-### portal
-```svelte
 <div use:portal={'body'}>
-  Renders at body level
-</div>
-```
-
-### escapeKey
-```svelte
 <div use:escapeKey={() => close()}>
 ```
 
----
-
-## Common Tasks
-
-### Add New Component
-1. Create file in appropriate folder (`primitives/`, `forms/`, `feedback/`)
-2. Use single `$props()` call
-3. Export styles with `cv()` if variants needed
-4. Add to `src/index.js` exports
-5. Document in this file
-
-### Add New Token
-1. Add to appropriate token file in `src/tokens/`
-2. Use semantic naming
-3. Add light theme variant if applicable
-
-### Theme Switching (Single Source of Truth Pattern)
-
-jera uses a singleton pattern for global theme state. Storage key: `miozu-theme`.
-
-#### SvelteKit Execution Order (from source code analysis)
-
-Understanding when code runs helps choose the right pattern:
-
-| Phase | File | Server | Client | Notes |
-|-------|------|--------|--------|-------|
-| 1 | +layout.server.js | ✓ | - | Server-only data |
-| 2 | +layout.js | ✓ | ✓ | Universal load, runs on EVERY navigation |
-| 3 | +layout.svelte `<script>` | ✓ | ✓ | Component script, runs once on mount |
-| 4 | +layout.svelte `onMount()` | - | ✓ | Client-only, after hydration |
-
-**Key insight from SvelteKit source (`client.js:684`):**
-```javascript
-data = { ...data, ...node.data };  // Parent data cascades to children
-```
-
-#### Recommended Pattern: +layout.svelte (for singletons like theme)
-
-For global singleton state that doesn't need server context:
-
-```svelte
-<!-- +layout.svelte - Initialize ONCE, pass via props -->
-<script>
-  import { getTheme } from '@miozu/jera';
-  import { onMount } from 'svelte';
-  import { Sidebar } from '$components';
-
-  // Call singleton once in root layout
-  const themeState = getTheme();
-
-  onMount(() => {
-    themeState.sync();  // Hydrate from DOM (app.html)
-    themeState.init();  // Setup media query listener
-  });
-</script>
-
-<!-- Pass themeState as prop to children -->
-<Sidebar {themeState} />
-```
-
-```svelte
-<!-- Child component - receives themeState as prop -->
-<script>
-  // DON'T call getTheme() here - receive as prop instead
-  let { themeState } = $props();
-
-  function handleToggle() {
-    themeState.toggle();
-  }
-
-  let isDark = $derived(themeState.isDark);
-</script>
-```
-
-#### Alternative Pattern: +layout.js (for data-heavy state)
-
-For state that needs server context or async initialization:
-
-```javascript
-// +layout.js - Universal load
-export const load = async ({ data, fetch }) => {
-  // Can fetch data, access parent(), etc.
-  const someData = await fetch('/api/data').then(r => r.json());
-
-  return {
-    ...data,
-    someData
-  };
-};
-```
-
-**When to use which:**
-
-| Use +layout.svelte | Use +layout.js |
-|-------------------|----------------|
-| Singletons (theme, toast) | Fetched data |
-| Client-only initialization | Async operations |
-| No server context needed | Needs `parent()` data |
-| Runs once per mount | Needs invalidation support |
-
-**ThemeState API:**
-```javascript
-themeState.toggle();         // Toggle dark/light
-themeState.set('dark');      // Set to dark
-themeState.set('light');     // Set to light
-themeState.set('system');    // Follow system preference
-
-// Reactive properties
-themeState.current;    // 'light' | 'dark' | 'system'
-themeState.resolved;   // 'light' | 'dark' (actual resolved value)
-themeState.dataTheme;  // 'miozu-light' | 'miozu-dark'
-themeState.isDark;     // boolean
-themeState.isLight;    // boolean
-```
-
-**Why pass as props instead of calling `getTheme()` everywhere?**
-1. **Explicit data flow** - You see what state each component depends on
-2. **Better testing** - Can inject mock state easily
-3. **Single initialization** - Clear where state originates
-4. **Efficiency** - Singleton runs once, not on every navigation
-
-### Theme Data Attributes
-
-| Theme | data-theme value |
-|-------|------------------|
-| Dark | `miozu-dark` |
-| Light | `miozu-light` |
-
-CSS selectors should use:
-```css
-[data-theme='miozu-dark'] { /* dark styles */ }
-[data-theme='miozu-light'] { /* light styles */ }
-```
-
-### Migration Guide: Custom Theme → Jera Singleton
-
-If you have a custom `theme.svelte.js` or similar, follow these steps:
-
-#### Step 1: Update app.html
-Replace custom theme script with unified storage key:
-```javascript
-// CRITICAL: Prevent FOUC - runs before any CSS
-(function () {
-  try {
-    let pref = localStorage.getItem('miozu-theme');
-
-    // Migrate from old keys if needed
-    if (!pref || !['light', 'dark', 'system'].includes(pref)) {
-      const oldTheme = localStorage.getItem('theme'); // or your old key
-      if (oldTheme === 'miozu-dark' || oldTheme === 'dark') pref = 'dark';
-      else if (oldTheme === 'miozu-light' || oldTheme === 'light') pref = 'light';
-    }
-
-    // Resolve theme
-    let theme;
-    if (pref === 'light') theme = 'miozu-light';
-    else if (pref === 'dark') theme = 'miozu-dark';
-    else {
-      theme = window.matchMedia?.('(prefers-color-scheme: dark)').matches
-        ? 'miozu-dark' : 'miozu-light';
-      pref = 'system';
-    }
-
-    // Apply and persist
-    document.documentElement.setAttribute('data-theme', theme);
-    document.documentElement.style.colorScheme = theme === 'miozu-dark' ? 'dark' : 'light';
-    localStorage.setItem('miozu-theme', pref);
-    document.cookie = 'miozu-theme=' + pref + '; path=/; max-age=31536000; SameSite=Lax';
-
-    // Clean up old keys
-    localStorage.removeItem('theme');
-  } catch (e) {
-    document.documentElement.setAttribute('data-theme', 'miozu-dark');
-  }
-})();
-```
-
-#### Step 2: Update +layout.svelte
-```svelte
-<script>
-  import { getTheme } from '@miozu/jera';
-  import { onMount } from 'svelte';
-
-  const themeState = getTheme();
-
-  onMount(() => {
-    themeState.sync();
-    themeState.init();
-  });
-</script>
-```
-
-#### Step 3: Update +layout.js
-Remove any theme initialization - it should NOT be in +layout.js:
-```javascript
-// REMOVE these lines:
-// import { ThemeReactiveState } from '$lib/reactiveStates/theme.svelte.js';
-// const themeState = new ThemeReactiveState();
-// return { themeState, ... };
-```
-
-#### Step 4: Update components using theme
-```svelte
-<script>
-  // OLD (remove):
-  // import { getThemeState } from '$lib/reactiveStates/theme.svelte.js';
-  // const themeState = getThemeState();
-
-  // NEW:
-  import { getTheme } from '@miozu/jera';
-  const themeState = getTheme();
-
-  let isDark = $derived(themeState.isDark);
-</script>
-```
-
-#### Step 5: Delete old theme file
-```bash
-rm src/lib/reactiveStates/theme.svelte.js
-```
-
-#### Step 6: Verify no old imports remain
-```bash
-grep -r "theme.svelte.js\|getThemeState\|ThemeReactiveState" src/
-# Should return no matches
-```
-
-### Apps Using Jera Theme (Proof of Concept)
-
-| App | Status | Storage Key |
-|-----|--------|-------------|
-| dash.selify.ai | ✓ Migrated | `miozu-theme` |
-| admin.selify.ai | ✓ Migrated | `miozu-theme` |
-| miozu.com | ✓ Migrated | `miozu-theme` |
-
-All three apps share the same theme preference via unified `miozu-theme` localStorage key.
-
----
-
-## Integration with dash.selify.ai
-
-jera components work out-of-the-box with dash.selify.ai. The semantic tokens are already configured in both systems.
-
-### Required: Import jera tokens
-```css
-/* In your app.css or layout */
-@import '@miozu/jera/tokens/colors.css';
-```
-
-### Semantic Token Mapping
-| jera Token | dash.selify.ai Equivalent |
-|------------|---------------------------|
-| `--color-bg` | `--color-base00` |
-| `--color-surface` | `--color-base01` |
-| `--color-surface-alt` | `--color-base02` |
-| `--color-text` | `--color-base05` |
-| `--color-text-strong` | `--color-base07` |
-| `--color-text-muted` | `--color-base04` |
-| `--color-primary` | `--color-base0D` |
-| `--color-success` | `--color-base0B` |
-| `--color-warning` | `--color-base0A` |
-| `--color-error` | `--color-base08` |
-| `--color-info` | `--color-base0C` |
-
-### Using jera Components in dash.selify.ai
-```svelte
-<script>
-  import { Button, Modal, Input } from '@miozu/jera';
-
-  let showModal = $state(false);
-</script>
-
-<!-- Works with existing dash.selify.ai theme system -->
-<Button variant="primary" onclick={() => showModal = true}>
-  Open Modal
-</Button>
-
-<Modal bind:open={showModal} title="Example">
-  <Input placeholder="Type here..." />
-</Modal>
-```
-
----
-
-## Rules for AI Assistants
+## Rules for AI
 
-1. **Always use Svelte 5 runes** - No legacy `$:`, `export let`, stores
-2. **Single $props() call** - Destructure all props in one call
-3. **Use cv() for variants** - Don't hardcode conditional classes
-4. **Semantic colors** - Use `--color-*` tokens, not raw `--base*`
-5. **Accessibility first** - Include ARIA attributes, keyboard support
-6. **No TypeScript** - Pure JavaScript with JSDoc for documentation
-7. **Mobile-first** - Design for mobile, enhance for desktop
+1. Svelte 5 runes only - no legacy syntax
+2. Single `$props()` call per component
+3. Use `cv()` for variants
+4. Semantic colors from Base16
+5. Accessibility first (ARIA, keyboard)
+6. Pure JavaScript (no TypeScript)

package/package.json

@@ -1,11 +1,8 @@
 {
   "name": "@miozu/jera",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "Zero-dependency, AI-first component library for Svelte 5",
   "type": "module",
-  "scripts": {
-    "prepublishOnly": "echo 'Publishing @miozu/jera...' && test -f src/index.js"
-  },
   "svelte": "./src/index.js",
   "exports": {
     ".": {
@@ -58,5 +55,6 @@
   "bugs": {
     "url": "https://github.com/miozu-com/jera/issues"
   },
-  "dependencies": {}
-}
+  "dependencies": {},
+  "scripts": {}
+}

package/src/components/navigation/LeftBarItem.svelte

@@ -34,6 +34,7 @@
     subroutes = [],
     badge = null,
     preload = true,
+    variant = 'default',
     onclick = null,
     isActiveRoute = () => false,
     class: className = '',
@@ -74,6 +75,7 @@
       class="nav-item {className}"
       class:active
       class:collapsed={isCollapsed}
+      data-variant={variant}
       title={isCollapsed ? label : null}
       data-sveltekit-preload-data={preloadAttr}
     >
@@ -94,16 +96,22 @@
     <button
       class="nav-item expandable {className}"
       class:collapsed={isCollapsed}
+      data-variant={variant}
       onclick={handleClick}
       onmouseenter={handleMouseEnter}
       onmouseleave={handleMouseLeave}
       title={isCollapsed ? label : null}
     >
+      {@render leading?.()}
       {#if Icon}
         <Icon size={18} class="nav-icon" />
       {/if}
       {#if !isCollapsed}
         <span class="nav-label" transition:fade={{ duration: 150 }}>{label}</span>
+        {#if badge != null}
+          <span class="nav-badge" transition:fade={{ duration: 150 }}>{badge}</span>
+        {/if}
+        {@render trailing?.()}
         <span transition:fade={{ duration: 150 }}>
           <svg
             xmlns="http://www.w3.org/2000/svg"
@@ -122,6 +130,7 @@
           </svg>
         </span>
       {/if}
+      {@render children?.()}
     </button>
     {#if expanded && !isCollapsed && subroutes.length > 0}
       <ul class="subnav-list" transition:slide={{ duration: 200, easing: cubicOut }}>
@@ -143,6 +152,7 @@
       class="nav-item {className}"
       class:active
       class:collapsed={isCollapsed}
+      data-variant={variant}
       onclick={handleClick}
       title={isCollapsed ? label : null}
     >
@@ -295,4 +305,44 @@
     font-weight: 500;
     background-color: color-mix(in srgb, var(--color-base0D) 15%, transparent);
   }
+
+  /* Variants */
+  .nav-item[data-variant="warning"] {
+    color: var(--color-base0A);
+  }
+
+  .nav-item[data-variant="warning"]:hover {
+    color: var(--color-base0A);
+    background-color: color-mix(in srgb, var(--color-base0A) 10%, transparent);
+  }
+
+  .nav-item[data-variant="warning"] :global(svg) {
+    color: var(--color-base0A);
+  }
+
+  .nav-item[data-variant="danger"] {
+    color: var(--color-base08);
+  }
+
+  .nav-item[data-variant="danger"]:hover {
+    color: var(--color-base08);
+    background-color: color-mix(in srgb, var(--color-base08) 10%, transparent);
+  }
+
+  .nav-item[data-variant="danger"] :global(svg) {
+    color: var(--color-base08);
+  }
+
+  .nav-item[data-variant="success"] {
+    color: var(--color-base0B);
+  }
+
+  .nav-item[data-variant="success"]:hover {
+    color: var(--color-base0B);
+    background-color: color-mix(in srgb, var(--color-base0B) 10%, transparent);
+  }
+
+  .nav-item[data-variant="success"] :global(svg) {
+    color: var(--color-base0B);
+  }
 </style>

package/src/components/navigation/LeftBarToggle.svelte

@@ -73,7 +73,7 @@
     background: transparent;
     border: none;
     cursor: pointer;
-    font: inherit;
+    font-family: inherit;
   }
 
   .collapse-toggle:hover {

package/src/components/primitives/LinkCard.svelte

@@ -0,0 +1,94 @@
+<!--
+  @component LinkCard
+
+  A clickable card for navigation, commonly used in dashboards for quick-nav sections.
+
+  @example Basic
+  <LinkCard href="/services" label="Ops Hub" />
+
+  @example With trailing icon
+  <LinkCard href="/pm" label="PM Board">
+    {#snippet trailing()}
+      <ArrowRight size={14} />
+    {/snippet}
+  </LinkCard>
+
+  @example Disabled
+  <LinkCard href="/admin" label="Admin Panel" disabled />
+-->
+<script>
+  let {
+    href,
+    label,
+    disabled = false,
+    class: className = '',
+    trailing,
+    ...rest
+  } = $props();
+</script>
+
+{#if disabled}
+  <div class="link-card link-card-disabled {className}" {...rest}>
+    <span class="link-card-label">{label}</span>
+    {#if trailing}
+      <span class="link-card-trailing">
+        {@render trailing()}
+      </span>
+    {/if}
+  </div>
+{:else}
+  <a {href} class="link-card {className}" {...rest}>
+    <span class="link-card-label">{label}</span>
+    {#if trailing}
+      <span class="link-card-trailing">
+        {@render trailing()}
+      </span>
+    {/if}
+  </a>
+{/if}
+
+<style>
+  .link-card {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    width: 100%;
+    box-sizing: border-box;
+    padding: var(--space-3) var(--space-4);
+    border-radius: var(--radius-lg);
+    background: var(--color-base01);
+    border: 1px solid var(--color-base02);
+    text-decoration: none;
+    transition: border-color 0.2s ease, background-color 0.2s ease;
+  }
+
+  .link-card:hover {
+    border-color: var(--color-base03);
+    background: var(--color-base02);
+  }
+
+  .link-card:hover .link-card-trailing {
+    color: var(--color-base06);
+  }
+
+  .link-card-disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+
+  .link-card-disabled:hover {
+    border-color: var(--color-base02);
+    background: var(--color-base01);
+  }
+
+  .link-card-label {
+    font-size: var(--text-sm);
+    font-weight: 500;
+    color: var(--color-base05);
+  }
+
+  .link-card-trailing {
+    color: var(--color-base04);
+    transition: color 0.2s ease;
+  }
+</style>

package/src/index.js

@@ -33,6 +33,7 @@ export { default as Avatar } from './components/primitives/Avatar.svelte';
 export { default as Card } from './components/primitives/Card.svelte';
 export { default as Stat } from './components/primitives/Stat.svelte';
 export { default as Link } from './components/primitives/Link.svelte';
+export { default as LinkCard } from './components/primitives/LinkCard.svelte';
 export { default as LazyImage } from './components/primitives/LazyImage.svelte';
 
 // ============================================