Getting Started

Get up and running with VelinStyle in under five minutes. This guide covers installation, your first page, components, theming, web components, and dark mode.

1. Installation

Choose the method that fits your workflow — CDN for quick prototypes, npm for production projects.

CDN (fastest)

Add these two lines inside your <head> and you're done — no build step required.

<!-- VelinStyle CSS -->
<link rel="stylesheet"
      href="https://unpkg.com/@birdapi/velinstyle@latest/dist/velinstyle.min.css">

<!-- VelinStyle Web Components (optional) -->
<script type="module"
        src="https://unpkg.com/@birdapi/velinstyle@latest/dist/velinstyle-components.min.js">
</script>

<!-- Recommended: accessibility bootstrap (announcer + scroll padding) -->
<script type="module">
  import { initA11y } from 'https://unpkg.com/@birdapi/velinstyle@latest/a11y';
  initA11y({ announcer: true, scrollPadding: true });
</script>

npm

For bundler-based projects (Vite, Webpack, Parcel, etc.):

npm install velinstyle

Then import in your entry file:

/* CSS — import in your main stylesheet or JS entry */
@import "velinstyle/dist/velinstyle.css";

/* Web Components — import in your JS entry */
import "velinstyle/dist/velinstyle-components.js";

Stack integration guides

Short recipes (German) for Laravel, WordPress, and generic bundler projects — same CSS and components, different glue code.

Open integration guides

2. Quick Start

Copy this starter template into a new HTML file and open it in your browser.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My VelinStyle App</title>
  <link rel="stylesheet"
        href="https://unpkg.com/@birdapi/velinstyle@latest/dist/velinstyle.min.css">
  <script type="module"
          src="https://unpkg.com/@birdapi/velinstyle@latest/dist/velinstyle-components.min.js">
  </script>
</head>
<body>
  <a href="#main" class="velin-skip-link">Skip to main content</a>

  <nav class="velin-nav" aria-label="Main navigation">
    <a href="/" class="velin-nav__brand">My App</a>
    <ul class="velin-nav__list">
      <li><a href="/" class="velin-nav__link">Home</a></li>
      <li><a href="/about" class="velin-nav__link">About</a></li>
    </ul>
  </nav>

  <main id="main" class="velin-container">
    <h1>Hello, VelinStyle!</h1>
    <p>Your accessibility-first app is ready.</p>
    <button class="velin-btn velin-btn--primary">Get Started</button>
  </main>
</body>
</html>

This gives you a fully responsive page with a skip link, semantic navigation, a container layout, and accessible defaults — all with zero configuration.

3. Your First Component — Buttons

VelinStyle components use a BEM-like naming convention: velin-block--modifier. Here's how buttons work.

Variants

<button class="velin-btn velin-btn--primary">Primary</button>
<button class="velin-btn velin-btn--secondary">Secondary</button>
<button class="velin-btn velin-btn--outline">Outline</button>
<button class="velin-btn velin-btn--ghost">Ghost</button>
<button class="velin-btn velin-btn--danger">Danger</button>

Sizes

<button class="velin-btn velin-btn--primary velin-btn--sm">Small</button>
<button class="velin-btn velin-btn--primary">Default</button>
<button class="velin-btn velin-btn--primary velin-btn--lg">Large</button>

Combining with Cards

Buttons work seamlessly inside other components like cards and forms.

<article class="velin-card">
  <div class="velin-card__body">
    <h3 class="velin-card__title">Welcome</h3>
    <p class="velin-card__text">VelinStyle components compose together naturally.</p>
  </div>
  <div class="velin-card__footer">
    <button class="velin-btn velin-btn--ghost velin-btn--sm">Cancel</button>
    <button class="velin-btn velin-btn--primary velin-btn--sm">Continue</button>
  </div>
</article>

4. Adding a Theme

VelinStyle ships with built-in theme presets you can activate with a single data-velin-theme attribute.

Available Themes (13)

Click any theme below to apply it live to this page. All 13 themes are loaded and ready to test.

Applying a Theme

Set the data-velin-theme attribute on <html> or any container element:

<!-- Apply globally -->
<html lang="en" data-velin-theme="ocean">

<!-- Or scope to a section -->
<section data-velin-theme="neon">
  <button class="velin-btn velin-btn--primary">Neon Button</button>
</section>

Loading Theme CSS

Theme presets are separate CSS files (~1.7 KB each). Include only the ones you need after the main stylesheet:

<link rel="stylesheet" href="https://unpkg.com/@birdapi/velinstyle@latest/dist/velinstyle.min.css">

<!-- Pick your theme(s) -->
<link rel="stylesheet" href="https://unpkg.com/@birdapi/velinstyle@latest/dist/themes/ocean.min.css">
<link rel="stylesheet" href="https://unpkg.com/@birdapi/velinstyle@latest/dist/themes/neon.min.css">

Switching Themes with JavaScript

// Switch to the ocean theme
document.documentElement.setAttribute("data-velin-theme", "ocean");

// Reset to default
document.documentElement.removeAttribute("data-velin-theme");

Custom Tokens

You can also override design tokens directly without a preset:

:root {
  --velin-color-primary: oklch(55% 0.25 270);
  --velin-radius-md: 0.75rem;
  --velin-font-sans: "Inter", system-ui, sans-serif;
}

5. Using Web Components

VelinStyle includes accessible, interactive web components for common UI patterns — modals, tabs, accordions, toasts, and dropdowns.

Setup

Load the components script (if you haven't already):

<script type="module"
        src="https://unpkg.com/@birdapi/velinstyle@latest/dist/velinstyle-components.min.js">
</script>

Modal

Focus-trapping dialog with Escape-to-close.

<button class="velin-btn velin-btn--primary"
        onclick="document.getElementById('my-modal').open()">
  Open Modal
</button>

<velin-modal id="my-modal" title="Dialog Title">
  <p>Your content here.</p>
  <div slot="footer">
    <button class="velin-btn velin-btn--ghost"
            onclick="document.getElementById('my-modal').close()">Cancel</button>
    <button class="velin-btn velin-btn--primary"
            onclick="document.getElementById('my-modal').close()">Confirm</button>
  </div>
</velin-modal>

Tabs

Keyboard-navigable tabbed interface with roving tabindex.

<velin-tabs>
  <button type="button" slot="tab">Tab 1</button>
  <button type="button" slot="tab">Tab 2</button>

  <div slot="panel"><p>Panel 1 content.</p></div>
  <div slot="panel"><p>Panel 2 content.</p></div>
</velin-tabs>

Accordion

Collapsible sections with optional exclusive (one-at-a-time) mode.

<velin-accordion exclusive>
  <details>
    <summary>Section 1</summary>
    <div><p>Content for section 1.</p></div>
  </details>
  <details>
    <summary>Section 2</summary>
    <div><p>Content for section 2.</p></div>
  </details>
</velin-accordion>

Toast Notifications

<velin-toast id="toaster"></velin-toast>

<script>
  document.getElementById("toaster").show({
    message: "Saved successfully!",
    type: "success"   // "success" | "warning" | "danger" | "info"
  });
</script>

6. Dark Mode Setup

VelinStyle has full dark mode support built in. Activate it with a single attribute — all tokens adapt automatically.

Manual Toggle

Set data-velin-theme="dark" on the <html> element:

<html lang="en" data-velin-theme="dark">

JavaScript Toggle

Build a toggle button that switches between light and dark:

<button class="velin-btn velin-btn--ghost" id="theme-toggle">
  Toggle Dark Mode
</button>

<script>
  const toggle = document.getElementById("theme-toggle");
  toggle.addEventListener("click", () => {
    const html = document.documentElement;
    const isDark = html.getAttribute("data-velin-theme") === "dark";
    if (isDark) {
      html.removeAttribute("data-velin-theme");
    } else {
      html.setAttribute("data-velin-theme", "dark");
    }
  });
</script>

Respecting System Preference

Auto-detect the user's OS preference and persist their choice:

<script>
  (function () {
    const stored = localStorage.getItem("velin-theme");
    const prefersDark = matchMedia("(prefers-color-scheme: dark)").matches;

    if (stored) {
      document.documentElement.setAttribute("data-velin-theme", stored);
    } else if (prefersDark) {
      document.documentElement.setAttribute("data-velin-theme", "dark");
    }
  })();

  function setTheme(theme) {
    if (theme) {
      document.documentElement.setAttribute("data-velin-theme", theme);
      localStorage.setItem("velin-theme", theme);
    } else {
      document.documentElement.removeAttribute("data-velin-theme");
      localStorage.removeItem("velin-theme");
    }
  }
</script>

Live Preview

Click the buttons below to test dark mode on this page:

Next Steps

You're all set. Explore the rest of the documentation to go deeper.

API reference & tokens (1.0.0)

Auto-generated Markdown from source — API Reference hub · full guide.

npm run docs:generate
npx velinstyle docs generate --scope components
npx velinstyle tokens validate --input examples/tokens.full.json
npx velinstyle perf audit samples/

CLI: Scaffolding (0.8.0)

Erzeuge UI-Snippets aus Text und prüfe Layouts — siehe Prompt Scaffolding und Responsive Layout.

npx velinstyle scaffold "Navbar mit Suchfeld" -o nav.html
npx velinstyle layout suggest nav.html
npx velinstyle scan nav.html