Hephaestus UI

Hephaestus UI is an independent Svelte 5 component library for building dense, accessible, themeable enterprise interfaces.

The package is designed for:

• Svelte 5 runes mode
• TypeScript-first component APIs
• Tailwind-compatible styling
• semantic CSS tokens
• light, dark, and auto theme modes
• compact, comfortable, and spacious density modes
• tree-shakeable component subpath imports

Why Hephaestus

Hephaestus is the Greek god of craft and the forge. The name fits a UI library focused on durable primitives, consistent visual systems, and practical component APIs that can be reused across many products.

Install

pnpm add hephaestus-ui

Use named exports:

<script lang="ts">
	import { Button, DataTable, TextInput } from "hephaestus-ui";
</script>

Or import individual components through subpath exports:

<script lang="ts">
	import Button from "hephaestus-ui/button";
</script>

Each component imports its runtime stylesheet. Apps may also preload:

• hephaestus-ui/component.css for runtime component tokens and semantic classes
• hephaestus-ui/styles.css for the full documentation/global stylesheet

Component Set

• Action: Button
• Forms: TextInput, TextArea, Select, RadioGroup, Checkbox, Switch, DatePicker, DateRange, TimeInput, CodeEditor
• Data display: DataTable, Badge, Tag
• Feedback: Alert, Skeleton, Spinner
• Layout: Accordion, Panel
• Navigation: Breadcrumb, Tabs
• Overlay: Dialog, DropdownMenu, Popover, Tooltip
• Theming: ThemeToggle, createThemeController

Development

pnpm install
pnpm run dev
pnpm run check
pnpm run lint
pnpm run test
pnpm run package

Run the complete release-level gate:

pnpm run verify

Run the package/library gate without browser suites:

pnpm run validate

Run Playwright browser tests in the official Playwright Docker image:

pnpm run test:a11y
pnpm run test:e2e

Use the local Playwright variants only when the host already has a compatible browser setup:

pnpm run verify:local
pnpm run test:a11y:local
pnpm run test:e2e:local

Architecture

Published code lives in src/lib. Documentation, examples, and playgrounds live in src/routes.

Components avoid $app/* imports so the package remains usable in Svelte applications outside SvelteKit. Shared component styling lives in src/lib/design/component.css; public exports are declared in src/lib/index.ts and package.json.

See:

• docs/0001-project-overview.md
• docs/0002-architecture-and-boundaries.md
• docs/0003-design-system-and-theming.md
• docs/0004-component-contracts.md
• docs/0005-documentation-and-playgrounds.md
• docs/0006-quality-standards.md
• docs/0007-release-and-validation.md
• docs/0008-decision-log.md