@miozu/jera

A minimal, reactive component library for Svelte 5.

Jera (ᛃ) — the rune of harvest and cycles. Build on foundations, yield results.

Features

• Miozu Design Tokens — Base16 color system, spacing, typography, effects
• Reactive Utilities — cn(), cv() for class composition with Svelte 5 runes
• Accessible Components — Button, Input, Select, Badge, Checkbox, Switch, Toast
• Svelte Actions — clickOutside, focusTrap, portal, escapeKey, and more
• AI-First Documentation — Optimized for LLM-assisted development

Installation

pnpm add @miozu/jera

Quick Start

<script>
  import { Button, Input, Badge } from '@miozu/jera';
  import '@miozu/jera/tokens';

  let email = $state('');
</script>

<Input bind:value={email} type="email" placeholder="Enter email" />
<Button onclick={() => console.log(email)}>Submit</Button>
<Badge variant="success">Active</Badge>

Design Tokens

Import tokens for consistent styling:

/* All tokens */
@import '@miozu/jera/tokens';

/* Individual token sets */
@import '@miozu/jera/tokens/colors';
@import '@miozu/jera/tokens/spacing';
@import '@miozu/jera/tokens/typography';
@import '@miozu/jera/tokens/effects';

Miozu Base16 Color Palette

Standard Base16 naming: base00-base0F (hex digits).

| Grayscale | Usage | Accents | Usage | |-----------|-------|---------|-------| | base00 | Background | base08 | Error (Red) | | base01 | Surface | base09 | Warning (Orange) | | base02 | Selection | base0A | Highlight (Yellow) | | base03 | Muted | base0B | Success (Green) | | base04 | Secondary text | base0C | Info (Cyan) | | base05 | Primary text | base0D | Primary (Blue) | | base06 | High emphasis | base0E | Accent (Purple) | | base07 | Maximum contrast | base0F | Secondary accent |

Components

Button

<Button variant="primary|secondary|ghost|outline|danger|success" size="xs|sm|md|lg|xl">
  Click me
</Button>
<Button href="/about">Link Button</Button>
<Button loading>Loading...</Button>

Input

<Input bind:value={text} placeholder="Enter text" />
<Input type="password" disableBrowserFeatures />
<Input error={!isValid} />

Select

<Select
  options={[{ value: '1', label: 'Option 1' }]}
  bind:value={selected}
  placeholder="Choose..."
/>

Badge

<Badge variant="default|primary|secondary|success|warning|error|info">
  Status
</Badge>

Checkbox & Switch

<Checkbox bind:checked={agreed}>I agree</Checkbox>
<Switch bind:checked={enabled}>Enable notifications</Switch>

Toast

<!-- Root layout -->
<script>
  import { Toast, createToastContext } from '@miozu/jera';
  createToastContext();
</script>
<Toast />

<!-- Any component -->
<script>
  import { getToastContext } from '@miozu/jera';
  const toast = getToastContext();
  toast.success('Saved!');
</script>

Utilities

cn() — Class concatenation

import { cn } from '@miozu/jera';

cn('base', condition && 'conditional', ['array', 'classes']);
// => "base conditional array classes"

cv() — Class variants

import { cv } from '@miozu/jera';

const button = cv({
  base: 'inline-flex items-center',
  variants: {
    variant: { primary: 'bg-primary', secondary: 'bg-surface' },
    size: { sm: 'h-8', md: 'h-10' }
  },
  defaults: { variant: 'primary', size: 'md' }
});

button({ variant: 'secondary' }); // => "inline-flex items-center bg-surface h-10"

Actions

<script>
  import { clickOutside, focusTrap, escapeKey, portal } from '@miozu/jera/actions';
</script>

<div use:clickOutside={() => close()}>
  <dialog use:focusTrap={{ enabled: isOpen }}>
    <div use:escapeKey={() => close()}>
      Content
    </div>
  </dialog>
</div>

<div use:portal={'body'}>Renders at body level</div>

Theming

Dark theme is default. Uses singleton pattern with miozu-theme storage key.

Setup

<!-- +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.

<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.

<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

import { getTheme } from '@miozu/jera';

const theme = getTheme();
theme.toggle();        // Switch between light/dark
theme.set('system');   // Follow system preference
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.

AI-First Design

This library includes AI-optimized documentation:

• llms.txt — Structured index for LLM consumption
• CLAUDE.md — Detailed context for AI assistants
• JSDoc comments throughout the codebase

Browser Support

• Chrome 88+
• Firefox 78+
• Safari 14+
• Edge 88+

Requires Svelte 5.0+

License

MIT © Nicholas Glazer