@federa/solanda-ui

Minimalist Web Components UI library for Vue, Nuxt, React, Angular, Svelte, and vanilla JavaScript

🎉 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
• 🎨 52 Components — Form, display, navigation, overlays, and layout components (65 custom elements)
• 🌙 6 Themes — Solanda, Social Neutral, Catppuccin, Gruvbox, Tokyo Night, Nord (light/dark modes)
• ⚡ Complete Component Suite — Full coverage with native Web Components and Aria-first design
• 📦 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 & layout grid
• 🔍 TypeScript — Full type definitions with JSDoc documentation
• 🌐 SSR Ready — Server-side rendering support
• 📏 ~36 KB gzip — Full bundle with all 52 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 (52 total, 65 custom elements)

Form (11)

Display (11)

Navigation (6)

Overlays (7)

Layout & Grid (16)

Demo/Docs (1)

🔧 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