Philosophy
Understanding the principles and architecture that make Svelte Atoms different.
Core Principles
Svelte Atoms is built on three fundamental principles that guide every design decision.
Simplicity Over Complexity
Components should be easy to understand and use. We avoid unnecessary abstractions and keep APIs minimal. If a component feels complicated, we've failed.
Composability First
Small, focused components that work together. Build complex UIs by combining simple parts. Each component does one thing well and composes naturally with others.
Accessibility By Default
Accessible components shouldn't be an afterthought. Every component includes proper ARIA attributes, keyboard navigation, and screen reader support out of the box.
Bond Architecture
The Bond pattern is our approach to state management and component communication.
What is a Bond?
A Bond is a self-contained unit of state and behavior. It's like a mini store that lives inside a component tree, managing its own state and exposing methods to interact with it.
// Creating a Bond
const accordion = createAccordionBond({
multiple: false,
defaultValue: 'item-1'
});
// Using the Bond
<Accordion bond={accordion}>
<AccordionItem value="item-1">...</AccordionItem>
<AccordionItem value="item-2">...</AccordionItem>
</Accordion>Encapsulation
Bonds keep component state isolated. No global stores, no prop drilling. State lives where it's needed.
Flexibility
Bonds can be created inside or outside components. Pass them as props, share them between components, or use them standalone.
Type Safety
Full TypeScript support with inferred types. Your IDE knows exactly what methods and properties are available.
Why Svelte 5?
Svelte 5's Runes API enables patterns that weren't possible before.
$state Fine-grained reactivity
Reactive state that works anywhere - not just in components. This makes Bonds possible and enables true separation of concerns.
$derived Computed values
Automatically computed values that update when dependencies change. No manual tracking, no stale closures.
$effect Side effects
Declarative side effects that run when dependencies change. Perfect for syncing external state or DOM operations.
Customization Philosophy
We believe in giving you full control without sacrificing convenience.
Style Your Way
Components use Tailwind classes by default but accept any styling approach. Override with your own classes, use CSS modules, or style components however you prefer.
Preset System
Define global defaults for all components. Create variants, set default values, and customize base styles in one place. Your design system, your rules.
Component Props
Every component accepts standard HTML attributes plus its own props. No magic wrappers, no hidden behavior. What you see is what you get.
Escape Hatches
Need to break out? Access the Bond directly, override behavior, or fork a component. We don't lock you in.
Design Goals
What we optimize for when building Svelte Atoms.
Developer Experience
Clear APIs, great TypeScript support, helpful error messages, and comprehensive documentation.
Performance
Minimal bundle size, lazy loading where possible, and leveraging Svelte's compiler for optimal output.
User Experience
Smooth animations, responsive interactions, proper focus management, and accessible by default.
Extensibility
Easy to extend, customize, and build upon. Your design system, not ours.
What We're Not
Being clear about what Svelte Atoms is not helps set the right expectations.
Not a CSS Framework
We use Tailwind for styling but we're not trying to replace it. Bring your own styles if you prefer something else.
Not Opinionated About State
Bonds handle internal component state, but we don't force a global state management solution. Use what works for your app.
Not a Complete Design System
We provide components and a preset system, but you define the design language. Svelte Atoms is a foundation, not a finished product.