LSD Framework

Part of LSD — a brand-to-code compiler and token-first design system authoring tool. The framework package stands alone and is MIT-licensed. You do not need the editor to use it.

Install

Files

Three authoring surfaces

Same tokens, same keyframes, three ways to reach them:

1. Class chains — class="lsd-fx fx-fade fx-up fx-delay-200" (declarative HTML)
2. SCSS mixins — @include fx.animate(fade, $direction: up) (compile-time)
3. JS API — lsd.fx('fade up', '.hero') (runtime programmatic)

Tier A — class chains

<div class="lsd-fx fx-fade fx-up fx-delay-200 fx-ease-bounce fx-dur-lg">
  Fades in from below on load.
</div>

<img class="lsd-flt flt-noir flt-on-hover-clear" src="portrait.jpg" />

Effect catalog

Modifier catalog

Filter catalog

Hover-state variants: flt-on-hover-clear, flt-on-hover-noir, flt-on-hover-crisp.

Tier B — DSL

Single attribute, three positional groups separated by |:

<div data-lsd-fx="fade up | delay:200 ease:bounce dur:slow | trigger:scroll stagger:50">
  …
</div>

Grammar: effects | key:value modifiers | trigger:value + stagger:N. On DOMContentLoaded, lsd-anim.js parses, sets --fx-* vars, adds the matching Tier A classes, and wires scroll triggers via IntersectionObserver.

Fire document.dispatchEvent(new CustomEvent('lsd-anim-rescan')) after inserting content dynamically.

JS authoring API

lsd.fx('fade up', '.hero', { delay: 200 })    // Promise
lsd.filter('noir', 'img.poster')
lsd.chain('fade up | delay:200 ease:bounce', el)
lsd.apply('fx-scale fx-dur-lg', el)
lsd.on('click', '.btn', (e) => { /* … */ })
lsd.tokens.get('color-primary')
lsd.tokens.set('color-primary', '#ff0000')
lsd.presets.list()
lsd.rescan()

Targets accept selectors, Elements, or NodeLists. prefers-reduced-motion is honored — animations short-circuit and Promises resolve immediately.

SCSS mixin layer

@use '@ferretdev/lsd-framework/fx.scss'  as fx;
@use '@ferretdev/lsd-framework/flt.scss' as flt;

.hero-title { @include fx.animate(fade, $direction: up, $delay: 200ms); }
.card-grid  { @include fx.stagger(100); }
.avatar     { @include flt.preset(noir); }
.feature    { @include fx.chain('fade up delay:200 ease:bounce'); }

Mixins: animate(), chain(), filter(), stagger(), on-hover(), on-focus(), on-scroll(), respect-reduced-motion().

Functions: fx-duration($key), fx-easing($key), fx-keyframe($effect, $direction).

Reactive data — lsd-data.js

Progressive-enhancement reactive layer. Any element with data-lsd-app becomes a scope; children use data-lsd-* directives. Zero deps, uses Proxy for dep tracking.

Directive reference

Inline example

<div data-lsd-app data-lsd-state='{"people":[
    {"name":"Ada","role":"Math"},
    {"name":"Grace","role":"Compilers"},
    {"name":"Hedy","role":"Signals"}
  ]}'>
  <ul>
    <li data-lsd-for="p in people"
        class="lsd-fx fx-fade fx-up fx-stagger-100 fx-on-scroll">
      <strong data-lsd-text="p.name"></strong>
      <span data-lsd-text="p.role"></span>
    </li>
  </ul>
</div>

Alpine bridge

<div x-data="{ status: 'idle' }" x-lsd-source="/api/status.json">
  <span x-text="status"></span>
  <button x-on:click="$lsd.fx('pulse', $el)">Ping</button>
</div>

Tokens

Override at any scope:

.hero { --fx-duration: 1200ms; --fx-easing: var(--easing-elastic); }

Reduced motion

Both CSS files end with a @media (prefers-reduced-motion: reduce) block that neutralizes all animations and transitions. lsd-anim.js skips IntersectionObserver wiring when reduced motion is active. lsd-api.js short-circuits fx() / chain().

Browser support

Safari 15.4+, Chrome 94+, Firefox 93+. Modern evergreen.

License

MIT.