indium-ui

Semantic component library for Svelte 5 with accessible, themeable components and integrated CSS framework

🚧 Work in Progress

This library is currently in early development. The API may change frequently until v1.0.

Features

• 🎨 Semantic CSS - Readable class names instead of utility classes
• ♿ Accessibility First - WCAG 2.2 Level AA compliance (AAA target)
• 🌓 Dark Mode - Built-in light/dark themes with auto-detection
• 🎯 Type Safe - Full TypeScript support with comprehensive types
• 🎨 Themeable - Customizable via CSS custom properties
• 📦 Tree-shakeable - Import only what you need
• 🚀 Svelte 5 - Built with the latest Svelte Runes API

Installation

# pnpm (recommended)
pnpm add indium-ui

# npm
npm install indium-ui

# yarn
yarn add indium-ui

Quick Start

<script>
  import { Button } from 'indium-ui';
  import 'indium-ui/styles';
</script>

<Button variant="primary" size="md">
  Click me
</Button>

Theme Setup

Initialize the theme in your root layout:

<!-- +layout.svelte -->
<script>
  import { initTheme } from 'indium-ui/theme';
  import 'indium-ui/styles';

  // Initialize theme on mount
  $effect(() => {
    initTheme();
  });
</script>

<slot />

Available Components

Atoms (1/15)

• ✅ Button
• ⏳ Input
• ⏳ Checkbox
• ⏳ Radio
• ⏳ Select
• ⏳ Textarea
• ⏳ Link
• ⏳ Badge
• ⏳ Tag
• ⏳ Icon
• ⏳ Heading
• ⏳ Text
• ⏳ Image
• ⏳ Video
• ⏳ Divider

More components coming soon...

Theme Customization

import { applyTheme } from 'indium-ui/theme';

applyTheme({
  'color-action-primary': '#ff6b6b',
  'color-action-primary-hover': '#ff5252',
  'radius-md': '0.75rem',
});

Dark Mode

import { setThemeMode, getThemeMode, toggleTheme } from 'indium-ui/theme';

// Set theme mode
setThemeMode('dark');   // Force dark mode
setThemeMode('light');  // Force light mode
setThemeMode('auto');   // Follow system preference

// Toggle between light and dark
toggleTheme();

// Get current mode
const mode = getThemeMode(); // 'light' | 'dark' | 'auto'

Development

# Install dependencies
pnpm install

# Start dev server
pnpm dev

# Run Storybook
pnpm storybook

# Run tests
pnpm test
pnpm test:unit
pnpm test:e2e

# Build library
pnpm build

# Check types
pnpm check

# Lint
pnpm lint

Releasing

This project uses a simple, CHANGELOG-driven release process:

1. Update CHANGELOG.md with the new version and changes:

   ## [0.2.0] - 2025-01-16
   
   ### Added
   - New Input component
   
   ### Fixed
   - Button focus styles

2. Run the release command:

   pnpm release

This will automatically:

• Extract version and release notes from CHANGELOG.md
• Update package.json version
• Create git commit and tag
• Push to GitHub
• Create GitHub Release with changelog notes
• Publish to npm

Prerequisites:

• GitHub CLI (gh) must be installed
• You must be logged in to npm (npm login)
• No uncommitted changes in git

Project Structure

src/
├── lib/
│   ├── components/
│   │   ├── atoms/           # Basic components (Button, Input, etc.)
│   │   ├── molecules/       # Composite components (Card, Alert, etc.)
│   │   └── organisms/       # Complex components (Modal, Header, etc.)
│   ├── config/
│   │   ├── types.ts         # Type definitions
│   │   ├── defaults.ts      # Default configuration
│   │   ├── config-loader.ts # Configuration loading
│   │   ├── render-helpers.ts # CSS generation helpers
│   │   └── postcss-plugin.ts # PostCSS theme plugin
│   ├── styles/
│   │   ├── reset.css        # CSS reset
│   │   ├── components/      # Component styles
│   │   └── index.css        # Main bundle
│   └── utils/
│       ├── theme.ts         # Theme utilities
│       ├── a11y.ts          # Accessibility helpers
│       └── types.ts         # Shared TypeScript types

Documentation

• 📚 Full documentation: Coming soon
• 📖 Component Specifications
• 🎨 CSS Framework Philosophy
• 🤖 AI Development Guide
• 📋 Changelog

Contributing

This project is currently in early development. Contributions will be welcome once we reach v1.0.

For more information, see our Contributing Guide.

License

MIT © Mirko Schubert

See LICENSE for details.

Acknowledgments

• Built with Svelte 5
• Icons by Lucide
• Inspired by semantic design systems and accessibility-first development