🎉 SolandaUI 1.0 is here! First stable release — the public API is now stable and follows semantic versioning: breaking changes will only ship in major versions.

✨ Features

• 🏁 Stable 1.0 — Production-ready, semver-compliant public API
• 🎨 37 Components — Form, display, navigation, overlays, and layout components (49 custom elements)
• 🌙 6 Themes — Solanda, Social Neutral, Catppuccin, Gruvbox, Tokyo Night, Nord (light/dark modes)
• 📦 Tree-shakeable — Import individual components or the full bundle
• 🔧 Framework Agnostic — Works with Vue, React, Angular, Svelte, Nuxt, or vanilla JS
• ♿ Accessible — Built-in ARIA attributes, keyboard navigation, semantic HTML
• 📱 Responsive — Mobile-first design with CSS custom properties
• 🔍 TypeScript — Full type definitions with JSDoc documentation
• 🌐 SSR Ready — Server-side rendering support
• 📏 ~27 KB gzip — Full bundle with all 37 components and CSS (zero dependencies)
• 🚀 Zero Dependencies — Custom Elements v1 + Shadow DOM only

📦 Installation

npm install @federa/solanda-ui

🚀 Quick Start

Import all components:

import '@federa/solanda-ui'
import '@federa/solanda-ui/css'

Import individual components (tree-shaking):

import '@federa/solanda-ui/sl-button'
import '@federa/solanda-ui/sl-input'
import '@federa/solanda-ui/css'

Import CSS tokens and themes:

import '@federa/solanda-ui/css'                    // tokens + default theme
import '@federa/solanda-ui/css/tokens'             // tokens only
import '@federa/solanda-ui/css/themes/solanda'     // Solanda theme
import '@federa/solanda-ui/css/themes/catppuccin'  // Catppuccin theme

📖 Usage

HTML

<sl-button variant="default" size="sm">Click me</sl-button>
<sl-input placeholder="Enter your name"></sl-input>
<sl-card shadow bordered>
  <h3 slot="header">Card Title</h3>
  <p>Card content goes here</p>
</sl-card>

React

import '@federa/solanda-ui'
import '@federa/solanda-ui/css'

function App() {
  return (
    <div>
      <sl-button variant="default" onClick={handleClick}>
        Click me
      </sl-button>
      <sl-input value={name} onInput={handleInput} />
    </div>
  )
}

Vue / Nuxt

<template>
  <sl-button variant="default" @click="handleClick">Click me</sl-button>
  <sl-input :value="name" @update:value="name = $event.detail.value" />
</template>

<script setup>
import '@federa/solanda-ui'
import '@federa/solanda-ui/css'

const handleClick = () => console.log('Clicked!')
</script>

Angular

import { Component } from '@angular/core'
import '@federa/solanda-ui'
import '@federa/solanda-ui/css'

@Component({
  selector: 'app-root',
  template: `
    <sl-button variant="default" (click)="handleClick()">Click me</sl-button>
    <sl-input placeholder="Enter your name"></sl-input>
  `,
  schemas: [CUSTOM_ELEMENTS_SCHEMA]
})
export class AppComponent {
  handleClick() {
    console.log('Clicked!')
  }
}

Svelte

<script>
  import '@federa/solanda-ui'
  import '@federa/solanda-ui/css'
</script>

<sl-button variant="default" on:click={handleClick}>Click me</sl-button>

🎨 Theming

ThemeManager API

import { themeManager } from '@federa/solanda-ui/theme'

// Set theme mode
themeManager.setTheme('dark')  // 'light' | 'dark' | 'system'

// Set color preset
themeManager.setPreset('catppuccin')  // 'solanda' | 'social-neutral' | 'catppuccin' | 'gruvbox' | 'tokyo-night' | 'nord'

// Toggle between light and dark
themeManager.toggleTheme()

CSS Custom Properties

Override any design token in your stylesheet:

:root {
  --sl-primary-500: #ff6b6b;
  --sl-spacing-unit: 0.3rem;
  --sl-font-family-base: 'Your Font', sans-serif;
}

📦 Available Components

Form (8)

| Component | Tag | Description | |-----------|-----|-------------| | Button | <sl-button> | 6 variants, 5 sizes, icon support | | Button Group | <sl-button-group> | Radio/checkbox group of buttons | | Input | <sl-input> | All HTML input types, validation states | | Textarea | <sl-textarea> | Multiline text with auto-resize | | Select | <sl-select> | Dropdown with keyboard navigation | | Checkbox | <sl-checkbox> | With label and indeterminate state | | Switch | <sl-switch> | Toggle switch | | Label | <sl-label> | Form label |

Display (7)

| Component | Tag | Description | |-----------|-----|-------------| | Badge | <sl-badge> | 7 variants, 3 sizes | | Avatar | <sl-avatar> | Image with fallback initials | | Card | <sl-card> | Header, body, actions slots | | Icon | <sl-icon> | SVG icon host | | Alert | <sl-alert> | Contextual feedback with 5 variants | | Spinner | <sl-spinner> | Loading indicator, 4 sizes | | Skeleton | <sl-skeleton> | Loading placeholder with shimmer |

Navigation (5)

| Component | Tag | Description | |-----------|-----|-------------| | Tabs | <sl-tabs> | Tab list container | | Tab | <sl-tab> | Individual tab item | | Tab Content | <sl-tab-content> | Tab panel content | | Breadcrumb | <sl-breadcrumb> | Hierarchical navigation with separator | | Pagination | <sl-pagination> | Page navigation with ellipsis |

Overlays (6)

| Component | Tag | Description | |-----------|-----|-------------| | Dialog | <sl-dialog> | Modal with focus trap and keyboard dismiss | | Tooltip | <sl-tooltip> | Hover tooltip with placement | | Popover | <sl-popover> | Click-triggered floating panel | | Dropdown Menu | <sl-dropdown-menu> | Context/action menu | | Toast | <sl-toast> | Programmatic notifications | | Offcanvas | <sl-offcanvas> | Slide-in panel from any edge |

Layout (10)

| Component | Tag | Description | |-----------|-----|-------------| | Step Indicator | <sl-step-indicator> | Progress steps | | Accordion | <sl-accordion> + <sl-accordion-item> | Collapsible content sections | | List Group | <sl-list-group> + <sl-list-group-item> | List container with variants | | Input Group | <sl-input-group> + <sl-input-group-addon> | Form controls with addons | | Section Header | <sl-section-header> | Eyebrow + title + description | | Feature Card | <sl-feature-card> | Icon + title + description | | Showcase Card | <sl-showcase-card> | Demo container | | Sidebar | <sl-sidebar> | Page sidebar | | Topbar | <sl-topbar> | Page top navigation bar | | Footer | <sl-footer> | Page footer |

Demo/Docs (1)

| Component | Tag | Description | |-----------|-----|-------------| | Doc Block | <sl-doc-block> | Documentation content block |

🔧 TypeScript Support

All components come with full TypeScript support:

import type { SlButtonVariants, SlDialogSize, SlToastVariant } from '@federa/solanda-ui'

// Use types for props
const buttonProps: SlButtonVariants = {
  variant: 'default',
  size: 'sm'
}

🎯 Programmatic API

Toast Notifications

import { showToast } from '@federa/solanda-ui'

showToast({
  message: 'Operation completed!',
  variant: 'success',
  duration: 3000,
  dismissible: true
})

Theme Manager

import { themeManager } from '@federa/solanda-ui/theme'

// Initialize with defaults
const tm = themeManager.init({
  defaultTheme: 'system',
  defaultPreset: 'solanda'
})

// Get current state
const theme = tm.getTheme()        // 'light' | 'dark' | 'system'
const preset = tm.getPreset()     // 'solanda' | 'catppuccin' | ...

🌍 Browser Support

• Chrome/Edge (latest)
• Firefox (latest)
• Safari (latest)
• Mobile browsers (iOS Safari, Chrome Mobile)

🛠 VS Code Configuration

SolandaUI ships VS Code custom data for HTML element and CSS property autocomplete.

HTML autocomplete (custom elements)

The package includes dist/vscode-html-custom-data.json. VS Code auto-detects it via the contributes.html.customData field in package.json.

For manual setup or to share with your team, add to .vscode/settings.json:

{
  "html.customData": ["./node_modules/@federa/solanda-ui/dist/vscode-html-custom-data.json"]
}

CSS autocomplete (design tokens)

Add dist/vscode-css-custom-data.json for CSS custom property autocomplete:

{
  "css.customData": ["./node_modules/@federa/solanda-ui/dist/vscode-css-custom-data.json"]
}

📚 Documentation

• Component API Reference: Generated from JSDoc annotations
• Design Tokens: CSS custom properties for colors, spacing, typography, shadows
• Theme System: 5 built-in presets with light/dark modes
• Interactive Reference: solanda.federa.social/doc/

🤖 For AI Agents

SolandaUI is optimized for AI coding assistants (Cursor, Claude Code, Copilot, etc.).

Quick discovery

• llms.txt: https://solanda.federa.social/llms.txt — curated index with absolute URLs to per-component docs
• llms-full.txt: https://solanda.federa.social/llms-full.txt — full inline documentation (single fetch)
• Per-component markdown: https://solanda.federa.social/components/{component}.md — e.g. button.md, dialog.md
• Custom Elements Manifest: custom-elements.json (included in npm package)

Portable AGENTS.md for your project

Copy the generated agent context file into your project for offline reference:

npx @federa/solanda-ui init-agents

Or manually:

cp node_modules/@federa/solanda-ui/dist/AGENTS.md ./AGENTS.md

VS Code IntelliSense

The npm package includes VS Code custom data for HTML and CSS autocomplete. VS Code auto-detects it — no config needed.

For manual setup or other editors, see the VS Code configuration section below.

🔧 TypeScript Support

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details.

📄 License

AGPL-3.0

Built with ❤️ by Federa