Spektral UI

A Svelte 5 design system. Customisable, composable and accessible. WCAG-focused and theme driven.

Documentation · npm

Install

npm i @abhc/spektral-ui

Quick start

Import the token file once in your app entry point (e.g. +layout.svelte):

import '@abhc/spektral-ui/tokens.css';

Then use components anywhere:

<script>
  import { Button, Card, Badge } from '@abhc/spektral-ui';
</script>

<Card>
  <Badge palette="success">New</Badge>
  <Button palette="accent">Get started</Button>
</Card>

Components

40+ components across layout, controls, overlays, feedback and content.

Layout

| Component | Description | |-----------|-------------| | Header | App header shell | | Footer | App footer shell | | Nav | Navigation bar | | Hero | Full-width section with layout presets, palette, SVG pattern backgrounds and mask effects | | TileGrid | Responsive grid with pattern background support | | Explorer / ExplorerGroup / ExplorerLink | File-tree style sidebar navigation |

Controls

| Component | Description | |-----------|-------------| | Button | Multi-variant button (flat, outlined, ghost, naked) with animation and direction options | | Badge | Inline label with palette, size, elevation and optional trailing action | | Input | Text input | | Textarea | Multiline text input | | Select | Dropdown select built on Popover | | CheckboxGroup | Checkbox list | | RadioGroup | Radio button list | | Switch | Toggle switch | | Slider | Range slider | | SearchField | Search input with clear action | | ColorPicker | OKLCH color picker with hex input | | Selector / ControlBar | Segmented control / tab bar |

Overlays

| Component | Description | |-----------|-------------| | Drawer | Side panel overlay | | Modal | Dialog overlay | | Popover | Anchored floating panel with direction and alignment options | | Tooltip | Hover tooltip with direction and size variants | | Command | Command palette / search modal |

Feedback

| Component | Description | |-----------|-------------| | Alert | Toast/notification with semantic variants and viewport positioning | | Callout | Highlighted text block | | Progress | Progress bar |

Content

| Component | Description | |-----------|-------------| | Card | Content container with variant, elevation and rounding options | | ListItem | Structured list row | | Accordion / AccordionHeader | Collapsible content sections | | DataTable | Sortable data table | | CodeBlock | Syntax-highlighted code with copy, filename, tabs and terminal variants | | Avatar | User avatar with fallback initials | | Headline | Display heading with palette and size variants | | Timeline / TimelineItem | Timeline layout | | Marquee | Scrolling content strip | | Support | "Built with Spektral" attribution badge | | SwatchRow | Color swatch display row |

Branding

| Component | Description | |-----------|-------------| | LogoSpektral | Spektral UI logo asset | | Support | "Built with Spektral" attribution badge |

Prop system

All components share a consistent prop vocabulary:

• variant — visual style: flat · outlined · ghost · naked
• palette — semantic color: accent · tone · neutral · error · warning · success · info
• size — sm · md · lg
• elevation — shadow level: none · subtle · hard

Not every prop applies to every component — check the docs for per-component APIs.

Token system

tokens.css exposes CSS custom properties for colors (OKLCH palettes), typography, radii and shadows. Light and dark modes are built in and toggled via the data-theme attribute or the ModeToggle component.

Customizing tokens

To customize the theme, use the configurator at https://spektral.combe.tf to build your custom tokens.css. The tool exports a file that matches the package's variable API exactly.

1. Place your file in static/

Copy the downloaded tokens.css into your project's static/ folder:

static/
└── tokens.css   ← your custom file

2. Import the package's tokens.css in app.css

/* src/app.css */
@import '@abhc/spektral-ui/tokens.css';

This loads the package defaults first, bundled by Vite.

3. Link your custom file in the root layout

<!-- src/routes/+layout.svelte -->
<svelte:head>
    <link rel="stylesheet" href="/tokens.css" />
</svelte:head>

Because <svelte:head> links are evaluated after the Vite bundle, your file always loads last — its values override the package defaults through normal CSS cascade.

Utilities

Two utilities are exported for building custom components that integrate with the variant system:

import { createVariant } from '@abhc/spektral-ui';
import type { PatternPreset } from '@abhc/spektral-ui';

• createVariant(config) — resolves a set of prop values to a class string using a declarative config object. Used internally by every component.
• PatternPreset — type for the SVG pattern presets available in Hero, TileGrid and Footer: scallops · grid · sunburst · lozenge · sunrise · atoms · waves · diamonds · shippo · kumi_kikko.

Color conversion helpers are also exported for working with the OKLCH color space:

import { hexToOklch, oklchToHex, hexToRgbChannels } from '@abhc/spektral-ui';
import type { Oklch } from '@abhc/spektral-ui';

• hexToOklch(hex) — converts a hex color string to an Oklch object { l, c, h }.
• oklchToHex(l, c, h) — converts OKLCH channels back to a hex string, with automatic gamut clamping.
• hexToRgbChannels(hex) — returns the RGB channels as a comma-separated string (e.g. "255, 128, 0"), useful for CSS rgb() / rgba() variables.

All component prop types are also exported from the main entry point, so you never need to reach into dist/ internals:

// Data shapes (passed as arrays / objects to components)
import type { CommandItem, CommandGroup } from '@abhc/spektral-ui';
import type { BadgeItem }                 from '@abhc/spektral-ui';
import type { Swatch }                    from '@abhc/spektral-ui';
import type { Tile, TileMedia }           from '@abhc/spektral-ui';
import type { Columns, HeroSpan }         from '@abhc/spektral-ui';

// Prop union types (palette, direction, size…)
import type { Elevation }                                          from '@abhc/spektral-ui';
import type { PopoverPalette, PopoverElevation,
              PopoverDirection, PopoverAlign }                     from '@abhc/spektral-ui';
import type { SearchFieldSize, SearchFieldPalette }                from '@abhc/spektral-ui';
import type { TooltipPalette, TooltipElevation,
              TooltipDirection, TooltipAlign, TooltipSize }        from '@abhc/spektral-ui';
import type { TimelineVariant, TimelinePalette, TimelineSize,
              TimelineElevation, TimelineOrientation,
              TimelineConnectorStyle }                             from '@abhc/spektral-ui';

Requirements

• Svelte ^5.0.0
• Modern browsers (CSS custom properties, :has, color-mix)

Documentation

Full docs, component API, live examples and theming guide: spektral.combe.tf

License

GPL-3.0 — see LICENSE.

AI Usage

AI (primarily Claude Code) was used during the development of this package. However, it's not 'vibe-coded' and the generated code is always human reviewed and tested before being pushed to the repository.