Architecture

Overview

Fluix follows a layered architecture where all component logic lives in a framework-agnostic core, and thin adapters bridge it to each framework’s reactivity system.

┌─────────────────────────────────────────────┐
│     Framework Adapters (React, Vue, etc.)   │
│     Role: mount, lifecycle, reactivity      │
├─────────────────────────────────────────────┤
│     @fluix-ui/core — Component Logic           │
│     State machines + imperative APIs        │
├─────────────────────────────────────────────┤
│     @fluix-ui/core — Shared Primitives         │
│     store, spring, dismiss, etc.            │
├─────────────────────────────────────────────┤
│     @fluix-ui/css — Data-attribute selectors   │
└─────────────────────────────────────────────┘

The DOM Contract

The key concept: CSS targets data-attributes, not class names. Any framework that produces the right [data-fluix-*] attributes gets the full visual treatment for free.

<section data-fluix-viewport data-position="top-right" aria-live="polite">
  <button data-fluix-toast data-state="success" data-expanded="false">
    <div data-fluix-header>
      <div data-fluix-badge data-state="success"><!-- icon --></div>
      <span data-fluix-title>Success</span>
    </div>
  </button>
</section>

Shared Primitives

Store

Minimal observable state container for core-to-adapter communication:

interface Store<T> {
  getSnapshot(): T;
  subscribe(listener: () => void): () => void;
  update(fn: (prev: T) => T): void;
}

Each framework consumes the store idiomatically — React uses useSyncExternalStore, Vue uses watchEffect, Svelte wraps it as a readable store.

Spring

Physics-based animation using damped harmonic oscillator math:

• CSS linear() easing — Runs on the compositor thread, zero JS.
• Web Animations API — For SVG attribute animation.
• No dependencies — No Framer Motion, GSAP, or anime.js.

SVG Gooey Effect

Two SVG <rect> elements animated through an feGaussianBlur + feColorMatrix filter that creates the signature merging visual effect.

Adapter Pattern

Each framework adapter:

1. Subscribes to the core store and triggers re-renders
2. Renders DOM with attributes from getToastAttrs()
3. Connects/disconnects event listeners on mount/unmount
4. Provides the SVG elements for the gooey effect
5. Exposes framework-idiomatic APIs (hooks, composables, etc.)

Adapters contain no business logic — no state transitions, no timing, no position calculations.

CSS Architecture

• variables.css — CSS custom properties (OKLCH colors, timing, dimensions)
• animations.css — @keyframes and linear() spring easing curves
• toast.css — Toast component styles using [data-fluix-*] selectors
• Supports prefers-reduced-motion: reduce
• Themeable via CSS custom properties