@soulcraft/theme (2.29.0)
Published 2026-08-13 18:40:00 +02:00 by dpsifr
Installation
@soulcraft:registry=npm install @soulcraft/theme@2.29.0"@soulcraft/theme": "2.29.0"About this package
@soulcraft/theme
Unified design system for all Soulcraft products. 40 themes — each with a curated font pairing — 64 color tokens, and orthogonal surface modes.
Documentation
- LLMS.md — ⭐ START HERE (humans and LLMs): the complete one-page reference — every export, token group, component, invariant, and per-theme personality map, current per release
- Token Reference — Complete list of every CSS var, Tailwind class, and usage guide
- Brand Guide — Soulcraft Platform theme (Soft Nebula) colors and wordmark
- ADR-001: Color Role Expansion — why 2.7 added interactive / secondary / info / states / chart, and how they derive
- ADR-002: Surface Element Vocabulary — how surface mode drives buttons, tabs, and inputs
- ADR-003: Categorical Color + Fill Styles — the unbounded categorical scale and the fill-style state channel (2.9)
- ADR-004: The Concierge Standard — the per-theme mood layer + the shared ConciergeCard (2.12)
- ADR-005: Picker Scopes + Custom Themes — ThemePicker v2's three variants, user/site scopes, and the portable custom-theme contract (2.12)
- ADR-006: Perceptual Contrast Floors — the global "too subtle" fix: enforced floors for surface steps, borders, muted text, and interactive chroma (2.13)
- ADR-007: The Finish Pass — corner personality, per-theme mono + ligatures, scrim/pressed/focus/selection micro-tokens, the motion vocabulary, fluid type scale, unconditional-AA foregrounds (2.14)
- ADR-009: The Scrollbar Standard — hover-reveal scrollbars, one platform rule +
--theme-scrollbar-thumb(2.15; ADR-008 is the Suite Bar, on its feature branch) - ADR-010: The Living-Canvas Kit's Home — the shared PixiJS kit lives here, at
@soulcraft/theme/canvasonly, with pixi as a dynamically-imported optional peer (text-only consumers pay zero bytes) - ADR-011: The Self Shell Contract — Proposed: the SuiteBar reworked roster-agnostic against the Self's live registry, no timers (supersedes the held ADR-008)
Quick Start
/* app.css */
@import '@soulcraft/theme/tailwind/tokens.css';
@import 'tailwindcss';
import { createThemeStore } from '@soulcraft/theme/stores/theme.svelte';
const theme = createThemeStore({ product: 'workshop' });
<script>
import ThemePicker from '@soulcraft/theme/components/ThemePicker';
</script>
<ThemePicker
currentThemeId={theme.currentThemeId}
surfaceMode={theme.surfaceMode}
onselect={(id) => theme.setTheme(id)}
onsurfacemode={(mode) => theme.setSurfaceMode(mode)}
/>
Surface Modes
All 40 themes support 6 rendering styles via one toggle:
| Mode | Effect |
|---|---|
| Glass | Translucent blur + saturate, colored borders |
| Flat | Solid backgrounds, crisp 1px borders, zero shadows |
| Raised | Multi-layer shadows, no borders (light) / subtle border (dark) |
| Gradient | Brand-tinted gradient backgrounds + gradient borders |
| Minimal | Subtle background step only — ultra-clean, no borders or shadows |
| Outline | Transparent backgrounds, thin border only — airy and editorial |
Components use semantic tokens (--theme-card-bg, --theme-card-border, --theme-card-shadow, --theme-card-blur) that adapt automatically. The --theme-glass token is also remapped per mode for instant backward compatibility.
See docs/TOKENS.md for the full migration guide.
Exports
| Import path | What |
|---|---|
@soulcraft/theme |
Types, utilities, catalog, CSS builders, surface mode, categorical scale |
@soulcraft/theme/categorical |
Categorical color scale + fill-style state channel |
@soulcraft/theme/stores/theme.svelte |
Svelte 5 theme store |
@soulcraft/theme/stores/font-size.svelte |
Font size store |
@soulcraft/theme/tailwind/tokens.css |
Tailwind CSS 4 token bridge |
@soulcraft/theme/components/ThemePicker |
Theme + surface mode picker |
@soulcraft/theme/components/ThemeCustomizer |
Color/font customizer |
@soulcraft/theme/components/ThemeSwatch |
Single theme preview card |
@soulcraft/theme/components/ThemeDotGrid |
Compact dot picker |
@soulcraft/theme/components/ColorInput |
OKLCH color input |
@soulcraft/theme/components/FontSizeControl |
Font size slider |
Dependencies
Development dependencies
| ID | Version |
|---|---|
| @sveltejs/package | ^2.5.7 |
| @sveltejs/vite-plugin-svelte | ^7.0.0 |
| @types/jsdom | ^28.0.3 |
| @types/node | ^26.1.0 |
| jsdom | ^29.1.1 |
| svelte | ^5.51.0 |
| typescript | ^5.7.3 |
| vitest | ^3.0.5 |
Peer dependencies
| ID | Version |
|---|---|
| svelte | ^5.0.0 |
Details
Assets (1)
Versions (69)
View all
theme-2.29.0.tgz
218 KiB