@miozu/jera 0.8.1 → 0.8.3

package/CLAUDE.md

@@ -58,13 +58,28 @@ Singleton pattern with `miozu-theme` storage key.
 
 **Full reference:** `docs/ai-context/theme-management.md`
 
+**ThemeToggle:** Accessible toggle with animated sun/moon icons
 ```svelte
-<!-- +layout.svelte -->
-<script>
-  import { getTheme } from '@miozu/jera';
-  const themeState = getTheme();
-  onMount(() => { themeState.sync(); themeState.init(); });
-</script>
+import { ThemeToggle } from '@miozu/jera';
+<ThemeToggle />
+<ThemeToggle size="sm" variant="outline" />
+```
+
+**ThemeSelect:** Three-option selector (light/dark/system)
+```svelte
+import { ThemeSelect } from '@miozu/jera';
+<ThemeSelect />
+<ThemeSelect variant="dropdown" />
+```
+
+**ThemeState API:**
+```javascript
+import { getTheme } from '@miozu/jera';
+const theme = getTheme();
+theme.init();        // Call once in root onMount
+theme.toggle();      // Switch dark/light
+theme.set('system'); // Follow OS preference
+theme.isDark;        // boolean reactive property
 ```
 
 ## Svelte 5 Patterns

package/README.md

@@ -176,23 +176,68 @@ button({ variant: 'secondary' }); // => "inline-flex items-center bg-surface h-1
 
 Dark theme is default. Uses singleton pattern with `miozu-theme` storage key.
 
-```javascript
-// In root +layout.svelte
-import { getTheme } from '@miozu/jera';
-import { onMount } from 'svelte';
+### Setup
 
-const theme = getTheme();
-onMount(() => theme.init());
+```svelte
+<!-- +layout.svelte -->
+<script>
+  import { getTheme } from '@miozu/jera';
+  import { onMount } from 'svelte';
+
+  const theme = getTheme();
+  onMount(() => theme.init());
+</script>
+```
+
+### ThemeToggle
+
+Accessible toggle button with animated sun/moon icons.
+
+```svelte
+<script>
+  import { ThemeToggle } from '@miozu/jera';
+</script>
+
+<ThemeToggle />
+<ThemeToggle size="sm" variant="outline" />
+<ThemeToggle size="lg" variant="subtle" />
+```
+
+Props: `size` (sm|md|lg), `variant` (ghost|outline|subtle), `themeState` (optional)
+
+### ThemeSelect
+
+Three-option selector for light/dark/system preference.
+
+```svelte
+<script>
+  import { ThemeSelect } from '@miozu/jera';
+</script>
+
+<!-- Segmented control (default) -->
+<ThemeSelect />
+
+<!-- Dropdown -->
+<ThemeSelect variant="dropdown" />
+
+<!-- Custom labels -->
+<ThemeSelect labels={{ light: 'Light', dark: 'Dark', system: 'Auto' }} />
 ```
 
+Props: `variant` (segmented|dropdown), `size` (sm|md|lg), `labels`, `showIcons`
+
+### ThemeState API
+
 ```javascript
-// Anywhere in your app
 import { getTheme } from '@miozu/jera';
 
 const theme = getTheme();
 theme.toggle();        // Switch between light/dark
 theme.set('system');   // Follow system preference
-theme.isDark;          // boolean reactive property
+theme.isDark;          // boolean - resolved dark mode
+theme.isLight;         // boolean - resolved light mode
+theme.current;         // 'light' | 'dark' | 'system'
+theme.dataTheme;       // 'miozu-light' | 'miozu-dark'
 ```
 
 Data-theme values: `miozu-dark` (default) or `miozu-light`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miozu/jera",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "description": "Zero-dependency, AI-first component library for Svelte 5",
   "type": "module",
   "svelte": "./src/index.js",

package/src/components/layout/SettingCard.svelte

@@ -2,28 +2,24 @@
   @component SettingCard
 
   A card container for settings sections with optional danger variant.
-  Provides consistent layout for settings items with labels, descriptions, and actions.
+  Use with SettingItem for structured setting rows.
 
   @example Basic settings card
   <SettingCard title="Account Settings">
-    <div class="setting-item">
-      <div class="setting-content">
-        <h4 class="setting-label">Display Name</h4>
-        <p class="setting-description">Your public display name</p>
-      </div>
-      <Input value={name} />
-    </div>
+    <SettingItem label="Display Name" description="Your public display name">
+      {#snippet action()}
+        <Input value={name} />
+      {/snippet}
+    </SettingItem>
   </SettingCard>
 
   @example Danger zone
   <SettingCard title="Danger Zone" variant="danger">
-    <div class="setting-item">
-      <div class="setting-content">
-        <h4 class="setting-label">Delete Account</h4>
-        <p class="setting-description">This cannot be undone</p>
-      </div>
-      <Button variant="danger">Delete</Button>
-    </div>
+    <SettingItem label="Delete Account" description="This cannot be undone">
+      {#snippet action()}
+        <Button variant="danger">Delete</Button>
+      {/snippet}
+    </SettingItem>
   </SettingCard>
 -->
 <script>
@@ -83,71 +79,4 @@
     display: flex;
     flex-direction: column;
   }
-
-  /* Utility classes for setting items - exposed globally */
-  :global(.setting-item) {
-    display: flex;
-    align-items: center;
-    justify-content: space-between;
-    gap: var(--space-4);
-    padding: var(--space-4) 0;
-    border-bottom: 1px solid var(--color-base02);
-  }
-
-  :global(.setting-item:last-child) {
-    border-bottom: none;
-    padding-bottom: 0;
-  }
-
-  :global(.setting-item:first-child) {
-    padding-top: 0;
-  }
-
-  :global(.setting-content) {
-    flex: 1;
-    min-width: 0;
-  }
-
-  :global(.setting-label) {
-    margin: 0 0 var(--space-1);
-    font-size: var(--text-sm);
-    font-weight: 500;
-    color: var(--color-base06);
-  }
-
-  :global(.setting-description) {
-    margin: 0;
-    font-size: var(--text-xs);
-    color: var(--color-base04);
-    line-height: 1.5;
-  }
-
-  :global(.setting-item-icon) {
-    display: flex;
-    align-items: center;
-    gap: var(--space-3);
-    color: color-mix(in srgb, var(--color-base04) 80%, transparent);
-  }
-
-  :global(.setting-item-with-icon) {
-    display: flex;
-    align-items: flex-start;
-    gap: var(--space-3);
-    padding: var(--space-4) 0;
-    border-bottom: 1px solid var(--color-base02);
-  }
-
-  :global(.setting-item-with-icon:last-child) {
-    border-bottom: none;
-    padding-bottom: 0;
-  }
-
-  /* Responsive */
-  @media (max-width: 640px) {
-    :global(.setting-item) {
-      flex-direction: column;
-      align-items: flex-start;
-      gap: var(--space-3);
-    }
-  }
 </style>

package/src/components/layout/SettingItem.svelte

@@ -0,0 +1,116 @@
+<!--
+  @component SettingItem
+
+  A structured setting row for use inside SettingCard.
+  Replaces magic class names with a composable component API.
+
+  @example Basic setting
+  <SettingItem label="Display Name" description="Your public display name">
+    {#snippet action()}
+      <Input value={name} />
+    {/snippet}
+  </SettingItem>
+
+  @example With icon
+  <SettingItem label="Active Sessions" description="Manage your devices">
+    {#snippet leading()}
+      <Monitor size={16} />
+    {/snippet}
+    {#snippet action()}
+      <Button size="sm">Manage</Button>
+    {/snippet}
+  </SettingItem>
+-->
+<script>
+  let {
+    label = '',
+    description = '',
+    leading,
+    action,
+    class: className = ''
+  } = $props();
+</script>
+
+<div class="setting-item {className}" class:has-leading={leading}>
+  {#if leading}
+    <div class="setting-leading">
+      {@render leading()}
+    </div>
+  {/if}
+  <div class="setting-content">
+    {#if label}
+      <h4 class="setting-label">{label}</h4>
+    {/if}
+    {#if description}
+      <p class="setting-description">{description}</p>
+    {/if}
+  </div>
+  {#if action}
+    <div class="setting-action">
+      {@render action()}
+    </div>
+  {/if}
+</div>
+
+<style>
+  .setting-item {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--space-4);
+    padding: var(--space-4) 0;
+    border-bottom: 1px solid var(--color-base02);
+  }
+
+  .setting-item:last-child {
+    border-bottom: none;
+    padding-bottom: 0;
+  }
+
+  .setting-item:first-child {
+    padding-top: 0;
+  }
+
+  .has-leading {
+    justify-content: flex-start;
+  }
+
+  .setting-leading {
+    display: flex;
+    align-items: center;
+    color: color-mix(in srgb, var(--color-base04) 80%, transparent);
+    flex-shrink: 0;
+  }
+
+  .setting-content {
+    flex: 1;
+    min-width: 0;
+  }
+
+  .setting-label {
+    margin: 0 0 var(--space-1);
+    font-size: var(--text-sm);
+    font-weight: 500;
+    color: var(--color-base06);
+  }
+
+  .setting-description {
+    margin: 0;
+    font-size: var(--text-xs);
+    color: var(--color-base04);
+    line-height: 1.5;
+  }
+
+  .setting-action {
+    flex-shrink: 0;
+  }
+
+  /* Responsive */
+  @media (max-width: 640px) {
+    .setting-item:not(.has-leading) {
+      flex-direction: column;
+      align-items: flex-start;
+      gap: var(--space-3);
+    }
+  }
+</style>

package/src/components/navigation/TabNav.svelte

@@ -45,10 +45,34 @@
     active = tab.id;
     onchange?.(tab);
   }
+
+  function handleKeydown(e, index) {
+    let nextIndex = index;
+
+    if (e.key === 'ArrowRight') {
+      nextIndex = (index + 1) % tabs.length;
+    } else if (e.key === 'ArrowLeft') {
+      nextIndex = (index - 1 + tabs.length) % tabs.length;
+    } else if (e.key === 'Home') {
+      nextIndex = 0;
+    } else if (e.key === 'End') {
+      nextIndex = tabs.length - 1;
+    } else {
+      return;
+    }
+
+    e.preventDefault();
+    const nextTab = tabs[nextIndex];
+    if (!nextTab.disabled) {
+      handleTabClick(nextTab);
+      const buttons = e.currentTarget.parentElement.querySelectorAll('[role="tab"]');
+      buttons[nextIndex]?.focus();
+    }
+  }
 </script>
 
 <nav class="tab-nav tab-nav-{variant} tab-nav-{size} {className}" role="tablist">
-  {#each tabs as tab}
+  {#each tabs as tab, index}
     <button
       type="button"
       class="tab-item"
@@ -57,7 +81,9 @@
       role="tab"
       aria-selected={active === tab.id}
       aria-disabled={tab.disabled}
+      tabindex={active === tab.id ? 0 : -1}
       onclick={() => handleTabClick(tab)}
+      onkeydown={(e) => handleKeydown(e, index)}
     >
       {#if tab.icon}
         <span class="tab-icon">

package/src/components/navigation/Tabs.svelte

@@ -1,7 +1,7 @@
 <!--
   @component Tabs
 
-  Tabbed navigation component.
+  Tabbed navigation component with keyboard navigation.
 
   @example Basic usage
   <Tabs
@@ -13,7 +13,7 @@
     bind:active={activeTab}
   />
 
-  @example With icons
+  @example With icons (component reference)
   <Tabs
     tabs={[
       { id: 'home', label: 'Home', icon: HomeIcon },
@@ -64,7 +64,6 @@
     const nextTab = tabs[nextIndex];
     if (!nextTab.disabled) {
       selectTab(nextTab);
-      // Focus the next tab button
       const buttons = e.currentTarget.parentElement.querySelectorAll('[role="tab"]');
       buttons[nextIndex]?.focus();
     }
@@ -90,8 +89,9 @@
       onkeydown={(e) => handleKeydown(e, tab, index)}
     >
       {#if tab.icon}
+        {@const Icon = tab.icon}
         <span class="tab-icon">
-          <svelte:component this={tab.icon} size={16} />
+          <Icon size={16} />
         </span>
       {/if}
       {#if tab.label}
@@ -107,10 +107,10 @@
 <style>
   .tabs {
     display: inline-flex;
-    gap: 0.25rem;
+    gap: var(--space-1);
     background: var(--color-base01);
-    border-radius: 0.5rem;
-    padding: 0.25rem;
+    border-radius: var(--radius-lg);
+    padding: var(--space-1);
   }
 
   .tabs-full-width {
@@ -126,12 +126,12 @@
   .tab {
     display: inline-flex;
     align-items: center;
-    gap: 0.5rem;
-    padding: 0.5rem 1rem;
+    gap: var(--space-2);
+    padding: var(--space-2) var(--space-4);
     background: transparent;
     border: none;
-    border-radius: 0.375rem;
-    font-size: 0.875rem;
+    border-radius: var(--radius-md);
+    font-size: var(--text-sm);
     font-weight: 500;
     color: var(--color-base05);
     cursor: pointer;
@@ -141,13 +141,13 @@
 
   /* Size variants */
   .tabs-sm .tab {
-    padding: 0.375rem 0.75rem;
-    font-size: 0.75rem;
+    padding: var(--space-1) var(--space-3);
+    font-size: var(--text-xs);
   }
 
   .tabs-lg .tab {
-    padding: 0.625rem 1.25rem;
-    font-size: 1rem;
+    padding: var(--space-3) var(--space-5);
+    font-size: var(--text-base);
   }
 
   .tab:hover:not(.tab-disabled) {
@@ -180,12 +180,12 @@
     display: inline-flex;
     align-items: center;
     justify-content: center;
-    min-width: 1.25rem;
-    height: 1.25rem;
-    padding: 0 0.375rem;
+    min-width: var(--space-5);
+    height: var(--space-5);
+    padding: 0 var(--space-1);
     background: var(--color-base03);
     border-radius: 9999px;
-    font-size: 0.75rem;
+    font-size: var(--text-xs);
     font-weight: 600;
   }
 
@@ -224,7 +224,7 @@
   .tabs-pills {
     background: transparent;
     padding: 0;
-    gap: 0.5rem;
+    gap: var(--space-2);
   }
 
   .tabs-pills .tab {

package/src/components/primitives/ThemeSelect.svelte

@@ -0,0 +1,260 @@
+<!--
+  @component ThemeSelect
+
+  A dropdown/segmented selector for theme preference with light/dark/system options.
+  Uses the Jera ThemeState singleton for theme management.
+
+  @example Basic dropdown
+  <ThemeSelect />
+
+  @example Segmented control style
+  <ThemeSelect variant="segmented" />
+
+  @example With custom theme state
+  <ThemeSelect themeState={myThemeState} />
+
+  @example Custom labels
+  <ThemeSelect
+    labels={{ light: 'Light', dark: 'Dark', system: 'Auto' }}
+  />
+-->
+<script>
+  import { cn } from '../../utils/cn.svelte.js';
+  import { getTheme, generateId } from '../../utils/reactive.svelte.js';
+
+  let {
+    themeState,
+    variant = 'segmented',
+    size = 'md',
+    labels = { light: 'Light', dark: 'Dark', system: 'System' },
+    showIcons = true,
+    class: className = '',
+    ...rest
+  } = $props();
+
+  // Use provided themeState or fall back to singleton
+  const theme = themeState ?? getTheme();
+  const groupId = generateId();
+
+  // Current preference (not resolved)
+  const current = $derived(theme.current);
+
+  // Size mappings
+  const sizes = {
+    sm: { wrapper: 'theme-select-sm', icon: 14 },
+    md: { wrapper: 'theme-select-md', icon: 16 },
+    lg: { wrapper: 'theme-select-lg', icon: 18 }
+  };
+
+  const currentSize = $derived(sizes[size] || sizes.md);
+
+  const options = [
+    { value: 'light', label: labels.light, icon: 'sun' },
+    { value: 'dark', label: labels.dark, icon: 'moon' },
+    { value: 'system', label: labels.system, icon: 'monitor' }
+  ];
+
+  function handleChange(value) {
+    theme.set(value);
+  }
+</script>
+
+{#if variant === 'segmented'}
+  <div
+    class={cn('theme-select-segmented', currentSize.wrapper, className)}
+    role="radiogroup"
+    aria-label="Theme preference"
+    {...rest}
+  >
+    {#each options as option (option.value)}
+      {@const isActive = current === option.value}
+      <button
+        type="button"
+        role="radio"
+        aria-checked={isActive}
+        class={cn('theme-select-option', isActive && 'theme-select-option-active')}
+        onclick={() => handleChange(option.value)}
+      >
+        {#if showIcons}
+          <span class="theme-select-icon" aria-hidden="true">
+            {#if option.icon === 'sun'}
+              <svg width={currentSize.icon} height={currentSize.icon} viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+                <circle cx="12" cy="12" r="4" />
+                <path d="M12 2v2M12 20v2M4.93 4.93l1.41 1.41M17.66 17.66l1.41 1.41M2 12h2M20 12h2M6.34 17.66l-1.41 1.41M19.07 4.93l-1.41 1.41" />
+              </svg>
+            {:else if option.icon === 'moon'}
+              <svg width={currentSize.icon} height={currentSize.icon} viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+                <path d="M12 3a6 6 0 0 0 9 9 9 9 0 1 1-9-9Z" />
+              </svg>
+            {:else if option.icon === 'monitor'}
+              <svg width={currentSize.icon} height={currentSize.icon} viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+                <rect width="20" height="14" x="2" y="3" rx="2" />
+                <line x1="8" x2="16" y1="21" y2="21" />
+                <line x1="12" x2="12" y1="17" y2="21" />
+              </svg>
+            {/if}
+          </span>
+        {/if}
+        <span class="theme-select-label">{option.label}</span>
+      </button>
+    {/each}
+  </div>
+{:else}
+  <!-- Dropdown variant -->
+  <div class={cn('theme-select-dropdown', currentSize.wrapper, className)} {...rest}>
+    <select
+      id={groupId}
+      value={current}
+      onchange={(e) => handleChange(e.target.value)}
+      aria-label="Theme preference"
+      class="theme-select-native"
+    >
+      {#each options as option (option.value)}
+        <option value={option.value}>{option.label}</option>
+      {/each}
+    </select>
+    <span class="theme-select-dropdown-icon" aria-hidden="true">
+      <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+        <path d="m6 9 6 6 6-6" />
+      </svg>
+    </span>
+  </div>
+{/if}
+
+<style>
+  /* ============================================
+     SEGMENTED CONTROL
+     ============================================ */
+  .theme-select-segmented {
+    display: inline-flex;
+    align-items: center;
+    background-color: var(--color-base01, #282828);
+    border-radius: var(--radius-md, 0.375rem);
+    padding: 2px;
+    gap: 2px;
+  }
+
+  .theme-select-option {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    gap: var(--space-1, 0.25rem);
+    padding: var(--space-1, 0.25rem) var(--space-3, 0.75rem);
+    border: none;
+    border-radius: calc(var(--radius-md, 0.375rem) - 2px);
+    background-color: transparent;
+    color: var(--color-base04, #665c54);
+    font-size: var(--text-sm, 0.875rem);
+    font-weight: 500;
+    cursor: pointer;
+    transition:
+      background-color var(--duration-fast, 150ms) var(--ease-out, ease-out),
+      color var(--duration-fast, 150ms) var(--ease-out, ease-out);
+  }
+
+  .theme-select-option:hover:not(.theme-select-option-active) {
+    color: var(--color-base05, #a89984);
+  }
+
+  .theme-select-option:focus-visible {
+    outline: 2px solid var(--color-base0D, #83a598);
+    outline-offset: -2px;
+  }
+
+  .theme-select-option-active {
+    background-color: var(--color-base02, #3c3836);
+    color: var(--color-base06, #d5c4a1);
+    box-shadow: var(--shadow-sm, 0 1px 2px rgba(0, 0, 0, 0.1));
+  }
+
+  .theme-select-icon {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+  }
+
+  .theme-select-label {
+    white-space: nowrap;
+  }
+
+  /* ============================================
+     SIZES - SEGMENTED
+     ============================================ */
+  .theme-select-sm .theme-select-option {
+    padding: 2px var(--space-2, 0.5rem);
+    font-size: var(--text-xs, 0.75rem);
+  }
+
+  .theme-select-md .theme-select-option {
+    padding: var(--space-1, 0.25rem) var(--space-3, 0.75rem);
+    font-size: var(--text-sm, 0.875rem);
+  }
+
+  .theme-select-lg .theme-select-option {
+    padding: var(--space-2, 0.5rem) var(--space-4, 1rem);
+    font-size: var(--text-base, 1rem);
+  }
+
+  /* ============================================
+     DROPDOWN
+     ============================================ */
+  .theme-select-dropdown {
+    position: relative;
+    display: inline-flex;
+    align-items: center;
+  }
+
+  .theme-select-native {
+    appearance: none;
+    background-color: var(--color-base01, #282828);
+    border: 1px solid var(--color-base03, #504945);
+    border-radius: var(--radius-md, 0.375rem);
+    color: var(--color-base06, #d5c4a1);
+    font-size: var(--text-sm, 0.875rem);
+    padding: var(--space-2, 0.5rem) var(--space-8, 2rem) var(--space-2, 0.5rem) var(--space-3, 0.75rem);
+    cursor: pointer;
+    transition:
+      border-color var(--duration-fast, 150ms) var(--ease-out, ease-out),
+      background-color var(--duration-fast, 150ms) var(--ease-out, ease-out);
+  }
+
+  .theme-select-native:hover {
+    border-color: var(--color-base04, #665c54);
+  }
+
+  .theme-select-native:focus {
+    outline: none;
+    border-color: var(--color-base0D, #83a598);
+    box-shadow: 0 0 0 2px color-mix(in srgb, var(--color-base0D, #83a598) 20%, transparent);
+  }
+
+  .theme-select-dropdown-icon {
+    position: absolute;
+    right: var(--space-2, 0.5rem);
+    pointer-events: none;
+    color: var(--color-base04, #665c54);
+  }
+
+  /* ============================================
+     SIZES - DROPDOWN
+     ============================================ */
+  .theme-select-dropdown.theme-select-sm .theme-select-native {
+    padding: var(--space-1, 0.25rem) var(--space-6, 1.5rem) var(--space-1, 0.25rem) var(--space-2, 0.5rem);
+    font-size: var(--text-xs, 0.75rem);
+  }
+
+  .theme-select-dropdown.theme-select-lg .theme-select-native {
+    padding: var(--space-3, 0.75rem) var(--space-10, 2.5rem) var(--space-3, 0.75rem) var(--space-4, 1rem);
+    font-size: var(--text-base, 1rem);
+  }
+
+  /* ============================================
+     REDUCED MOTION
+     ============================================ */
+  @media (prefers-reduced-motion: reduce) {
+    .theme-select-option,
+    .theme-select-native {
+      transition: none;
+    }
+  }
+</style>

package/src/components/primitives/ThemeToggle.svelte

@@ -0,0 +1,263 @@
+<!--
+  @component ThemeToggle
+
+  An accessible theme toggle button with animated sun/moon icons.
+  Uses the Jera ThemeState singleton for theme management.
+
+  @example Basic usage
+  <ThemeToggle />
+
+  @example With custom theme state
+  <ThemeToggle themeState={myThemeState} />
+
+  @example Different sizes
+  <ThemeToggle size="sm" />
+  <ThemeToggle size="lg" />
+
+  @example With label
+  <ThemeToggle>
+    {#snippet label()}Dark mode{/snippet}
+  </ThemeToggle>
+
+  @example Custom icons via snippets
+  <ThemeToggle>
+    {#snippet sunIcon()}<MyCustomSun />{/snippet}
+    {#snippet moonIcon()}<MyCustomMoon />{/snippet}
+  </ThemeToggle>
+-->
+<script>
+  import { cn } from '../../utils/cn.svelte.js';
+  import { getTheme } from '../../utils/reactive.svelte.js';
+
+  let {
+    themeState,
+    size = 'md',
+    variant = 'ghost',
+    class: className = '',
+    sunIcon,
+    moonIcon,
+    label,
+    ...rest
+  } = $props();
+
+  // Use provided themeState or fall back to singleton
+  const theme = themeState ?? getTheme();
+
+  // Derive current state
+  const isDark = $derived(theme.isDark);
+
+  // Size mappings
+  const sizes = {
+    sm: { button: 'theme-toggle-sm', icon: 16 },
+    md: { button: 'theme-toggle-md', icon: 20 },
+    lg: { button: 'theme-toggle-lg', icon: 24 }
+  };
+
+  const currentSize = $derived(sizes[size] || sizes.md);
+
+  function handleToggle() {
+    theme.toggle();
+  }
+</script>
+
+<button
+  type="button"
+  onclick={handleToggle}
+  aria-pressed={isDark}
+  aria-label={isDark ? 'Switch to light mode' : 'Switch to dark mode'}
+  class={cn('theme-toggle', `theme-toggle-${variant}`, currentSize.button, className)}
+  {...rest}
+>
+  <span class="theme-toggle-icon-wrapper">
+    <!-- Sun icon (visible in dark mode, click to switch to light) -->
+    <span class={cn('theme-toggle-icon', 'theme-toggle-sun', isDark && 'theme-toggle-icon-active')}>
+      {#if sunIcon}
+        {@render sunIcon()}
+      {:else}
+        <svg
+          width={currentSize.icon}
+          height={currentSize.icon}
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          aria-hidden="true"
+        >
+          <circle cx="12" cy="12" r="4" />
+          <path d="M12 2v2M12 20v2M4.93 4.93l1.41 1.41M17.66 17.66l1.41 1.41M2 12h2M20 12h2M6.34 17.66l-1.41 1.41M19.07 4.93l-1.41 1.41" />
+        </svg>
+      {/if}
+    </span>
+
+    <!-- Moon icon (visible in light mode, click to switch to dark) -->
+    <span class={cn('theme-toggle-icon', 'theme-toggle-moon', !isDark && 'theme-toggle-icon-active')}>
+      {#if moonIcon}
+        {@render moonIcon()}
+      {:else}
+        <svg
+          width={currentSize.icon}
+          height={currentSize.icon}
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          aria-hidden="true"
+        >
+          <path d="M12 3a6 6 0 0 0 9 9 9 9 0 1 1-9-9Z" />
+        </svg>
+      {/if}
+    </span>
+  </span>
+
+  {#if label}
+    <span class="theme-toggle-label">
+      {@render label()}
+    </span>
+  {/if}
+</button>
+
+<style>
+  /* ============================================
+     BASE STYLES
+     ============================================ */
+  .theme-toggle {
+    position: relative;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    gap: var(--space-2, 0.5rem);
+    border: none;
+    border-radius: var(--radius-md, 0.375rem);
+    cursor: pointer;
+    transition: background-color var(--duration-fast, 150ms) var(--ease-out, ease-out);
+  }
+
+  .theme-toggle:focus-visible {
+    outline: 2px solid var(--color-base0D, #83a598);
+    outline-offset: 2px;
+  }
+
+  /* ============================================
+     VARIANTS
+     ============================================ */
+  .theme-toggle-ghost {
+    background-color: transparent;
+    color: var(--color-base05, #a89984);
+  }
+
+  .theme-toggle-ghost:hover {
+    background-color: var(--color-base02, #3c3836);
+    color: var(--color-base06, #d5c4a1);
+  }
+
+  .theme-toggle-outline {
+    background-color: transparent;
+    color: var(--color-base05, #a89984);
+    border: 1px solid var(--color-base03, #504945);
+  }
+
+  .theme-toggle-outline:hover {
+    background-color: var(--color-base02, #3c3836);
+    border-color: var(--color-base04, #665c54);
+    color: var(--color-base06, #d5c4a1);
+  }
+
+  .theme-toggle-subtle {
+    background-color: var(--color-base01, #282828);
+    color: var(--color-base05, #a89984);
+  }
+
+  .theme-toggle-subtle:hover {
+    background-color: var(--color-base02, #3c3836);
+    color: var(--color-base06, #d5c4a1);
+  }
+
+  /* ============================================
+     SIZES
+     ============================================ */
+  .theme-toggle-sm {
+    padding: var(--space-1, 0.25rem);
+    min-width: 1.75rem;
+    min-height: 1.75rem;
+  }
+
+  .theme-toggle-md {
+    padding: var(--space-2, 0.5rem);
+    min-width: 2.25rem;
+    min-height: 2.25rem;
+  }
+
+  .theme-toggle-lg {
+    padding: var(--space-3, 0.75rem);
+    min-width: 2.75rem;
+    min-height: 2.75rem;
+  }
+
+  /* ============================================
+     ICON ANIMATION
+     ============================================ */
+  .theme-toggle-icon-wrapper {
+    position: relative;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+  }
+
+  .theme-toggle-icon {
+    position: absolute;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    opacity: 0;
+    transform: rotate(-90deg) scale(0.5);
+    transition:
+      opacity var(--duration-normal, 200ms) var(--ease-out, ease-out),
+      transform var(--duration-normal, 200ms) var(--ease-out, ease-out);
+  }
+
+  .theme-toggle-icon-active {
+    position: relative;
+    opacity: 1;
+    transform: rotate(0deg) scale(1);
+  }
+
+  /* Sun specific - warm color when active */
+  .theme-toggle-sun.theme-toggle-icon-active {
+    color: var(--color-base0A, #fabd2f);
+  }
+
+  /* Moon specific - cool color when active */
+  .theme-toggle-moon.theme-toggle-icon-active {
+    color: var(--color-base0D, #83a598);
+  }
+
+  /* ============================================
+     REDUCED MOTION
+     ============================================ */
+  @media (prefers-reduced-motion: reduce) {
+    .theme-toggle-icon {
+      transition: opacity var(--duration-fast, 150ms) var(--ease-out, ease-out);
+      transform: none;
+    }
+
+    .theme-toggle-icon-active {
+      transform: none;
+    }
+  }
+
+  /* ============================================
+     LABEL
+     ============================================ */
+  .theme-toggle-label {
+    font-size: var(--text-sm, 0.875rem);
+    color: var(--color-base05, #a89984);
+  }
+
+  .theme-toggle:hover .theme-toggle-label {
+    color: var(--color-base06, #d5c4a1);
+  }
+</style>

package/src/index.js

@@ -40,6 +40,8 @@ export { default as FilterChip } from './components/primitives/FilterChip.svelte
 export { default as StatusLine } from './components/primitives/StatusLine.svelte';
 export { default as Tooltip } from './components/primitives/Tooltip.svelte';
 export { default as MemberCard } from './components/primitives/MemberCard.svelte';
+export { default as ThemeToggle } from './components/primitives/ThemeToggle.svelte';
+export { default as ThemeSelect } from './components/primitives/ThemeSelect.svelte';
 
 // ============================================
 // COMPONENTS - Forms
@@ -139,6 +141,7 @@ export { default as DropdownContainer } from './components/navigation/DropdownCo
 
 export { default as PageHeader } from './components/layout/PageHeader.svelte';
 export { default as SettingCard } from './components/layout/SettingCard.svelte';
+export { default as SettingItem } from './components/layout/SettingItem.svelte';
 
 // ============================================
 // COMPONENTS - Documentation