Hosts (Tailwind & others)
++ Velora is a motion engine. Your host owns layout and visual styling. +
+ +Minimal import
+@import "@velora/css/motion-core";
+/* optional page transitions */
+@import "@velora/css/transitions";Do not require @velora/css/theme or component classes for scenes to work.
Tailwind example
+<section vl-scene vl-timeline="view" vl-pin="3" vl-scrub>
+ <div vl-stage class="min-h-svh grid place-items-center gap-6 px-6">
+ <p class="text-sm uppercase tracking-widest" vl-enter="fade-up" vl-act="1">Kicker</p>
+ <h1 class="text-5xl font-semibold" vl-enter="clip-rise" vl-act="1">Title</h1>
+ <img class="w-full max-w-3xl rounded-2xl" vl-scroll="media-zoom" vl-act="2" vl-span="2" alt="" />
+ </div>
+</section>
+ Repo proof: examples/tailwind-host/. Showcase proves the Velora cinematic UI;
+ examples prove the host-agnostic path.
+
Layers
+
+ Velora uses @layer velora.*. Keep host utilities outside or after those layers so
+ Tailwind wins on appearance while vl-* attributes still drive animation.
+
Optional skin
+@import "@velora/css/motion-core";
+@import "@velora/css/theme"; /* brand tokens + scene recipes */Getting Started
- A motion-native design system. Declarative HTML attributes. Zero JavaScript for animation. Modern CSS only.
+ A declarative motion language for HTML. Attributes describe intent; CSS executes it.
+ Works with Tailwind, Relume, or any UI. Showcase is the optional Velora look
+ (Skins — named models via data-editorial-theme).
+ The public Showcase is six pages; the previous demos live in
+ archive/showcase-2026-08/.
Installation
@@ -16,133 +20,53 @@ import Base from "../layouts/Base.astro"; # or npm install @velora/css -Then import it once at the root of your app:
-@import "@velora/css";Or in a bundler entrypoint:
-import "@velora/css";Quick Start
-Add motion to any element with two attributes:
-<!-- Fade up when scrolled into view -->
-<div vl-effect="fade-up" vl-timeline="view">
- Reveals on scroll
-</div>
-
-<!-- Staggered children entrance -->
-<section vl-children="stagger" vl-stagger="100ms">
- <div>Child 1</div>
- <div>Child 2</div>
- <div>Child 3</div>
-</section>
-
-<!-- Full scene orchestration -->
-<section
- vl-scene="hero"
- vl-effect="scene-hero-reveal"
- vl-timeline="view"
- vl-range="entry 0% cover 70%"
- vl-pin>
- <h1>Heading fades up</h1>
- <img src="hero.jpg" alt="" />
- <p>Copy blurs in</p>
- <a href="#" class="vl-cta">Get started</a>
-</section>Page Transitions
-Enable MPA cross-document view transitions with one attribute:
-<!-- In your root layout -->
-<html vl-page-transition="cinema">
- Requires @view-transition { navigation: auto; } in your CSS (already included with Velora).
- Supported in Chrome 111+, Edge 111+.
-
Philosophy
-- Velora is a declarative motion system for HTML — not a UI kit, not a JavaScript animation library. -
-The core idea is a three-step contract:
--
-
- Write semantic HTML -
- Add
vl-*attributes to declare intent
- - Velora maps those to CSS-based motion, layout, and transitions -
- The framework proves that modern HTML and CSS are sufficient to build premium motion systems when the - architecture is designed correctly. -
- -CSS Layer Stack
-Velora organizes CSS into 8 cascade layers, making it safe to override at any point:
-@layer velora.reset,
- velora.tokens,
- velora.layout,
- velora.motion,
- velora.components,
- velora.transitions,
- velora.utilities,
- velora.overrides;Choose an import
| Layer | -Contents | -
|---|---|
| Import | Use when |
velora.reset | Browser normalization and base adjustments |
velora.tokens | Colors, spacing, typography, motion tokens |
velora.layout | Container, stack, grid, and scene wrappers |
velora.motion | Effect presets, timelines, stagger, reveals |
velora.components | Cards, buttons, navbars, accordions, badges |
velora.transitions | Page transitions and shared element rules |
velora.utilities | Low-level opt-in utility classes |
velora.overrides | Last-mile overrides; highest specificity |
@velora/css/motion-core |
+ Host UI already provides look (Tailwind, custom DS). Motion + scene engine only. | +
@velora/css/theme |
+ Optional Velora visual tokens + named scene recipes. | +
@velora/css / full |
+ Convenience: theme + components + motion (Showcase / docs style). | +
Accessibility
+/* Host-agnostic (recommended for Tailwind projects) */
+@import "@velora/css/motion-core";
+@import "@velora/css/transitions"; /* optional */
+
+/* Or full Velora skin */
+@import "@velora/css";Quick Start — scene engine
+Track + stage + acts: one shared clock, pin, scrub — no JavaScript.
+<section vl-scene vl-timeline="view" vl-pin="3" vl-scrub>
+ <div vl-stage>
+ <p vl-enter="fade-up" vl-act="1">Kicker</p>
+ <h1 vl-enter="clip-rise" vl-act="1">Title</h1>
+ <img vl-scroll="media-zoom" vl-act="2" vl-span="2" alt="" />
+ </div>
+</section>
- All Velora motion is prefers-reduced-motion aware. Users who have requested reduced motion
- see instant transitions with no animation.
+ Style with your own classes. Motion does not require .vl-card or brand tokens.
+ See Hosts (Tailwind) and Scenes.
/* Built into every Velora effect */
-@media (prefers-reduced-motion: reduce) {
- [vl-effect],
- [vl-scene],
- [vl-page-transition] {
- animation: none !important;
- transition-duration: 0ms !important;
- }
-}Explore the Docs
-CSS custom properties for color, typography, spacing, and motion.
- - -All vl-effect values — entrance, interaction, continuous, text, cinema.
Multi-element orchestrations with vl-scene and vl-children.
MPA view transitions with shared element morphing.
- - -Complete reference for every vl-* attribute.
Rules, patterns, and safe prompts for AI coding agents.
- -What Velora is
+-
+
- Motion language — not a utility framework requirement +
- Zero JS for animation — scroll timelines, view transitions, CSS only +
- Showcase — cinematic reference UI / design system skin +
Conditional Motion Engine
+
+ A single declarative attribute — vl-motion — selects a motion mode for an
+ element and its subtree. It does not name a preset; instead it re-scales the shared engine tokens
+ that every preset already reads, so one attribute adapts timing, travel, depth, blur and easing
+ across the whole subtree. Zero JavaScript.
+
The Modes
+
+ Add vl-motion to any element. Descendant vl-effect / vl-enter
+ reveals inherit the mode automatically.
+
| Value | Intent | Engine effect |
|---|---|---|
standard |
+ Balanced default feel | +Neutral scale (1×), cinematic easing | +
subtle |
+ Quiet, fast, short travel | +Faster duration, reduced travel & depth, soft easing | +
cinematic |
+ Grand, slow, deep, blurred entrances | +Slower duration, larger travel & depth, entrance blur | +
still |
+ Author-driven reduced motion | +Resting/composed state, no movement (independent of OS setting) | +
<!-- One attribute governs the whole subtree -->
+<section vl-motion="cinematic">
+ <h2 vl-enter="reveal-cinematic" vl-timeline="view">Grand & deep</h2>
+ <p vl-effect="fade-up" vl-timeline="view">Slower, deeper, blurred entrance.</p>
+</section>
+
+<section vl-motion="subtle">...quieter, faster motion...</section>
+<section vl-motion="still">...reduced-motion-safe resting state...</section>Engine Tokens
+
+ Modes work by assigning central --vl-* knobs (declared in 01-tokens.css).
+ Presets consume these instead of hardcoding per-selector values, which keeps adaptation in one place.
+
| Token | Role | Neutral default |
|---|---|---|
--vl-motion-mode | Active mode (queried by if(style())) | standard |
--vl-motion-speed-scale | Duration multiplier | 1 |
--vl-motion-intensity | Travel-distance multiplier | 1 |
--vl-motion-depth | Parallax / z-depth multiplier | 1 |
--vl-motion-blur | Additive entrance blur | 0px |
--vl-motion-preference | Reflects reduced-motion intent | auto |
--vl-motion-mode-ease | Easing selected by the mode | --vl-ease-cinematic |
+ Because the defaults are neutral (scale 1, offset 0), motion behaves exactly
+ as before when no vl-motion mode is present. Explicit per-element modifiers such as
+ vl-speed and vl-depth still win over the mode.
+
Progressive Enhancement with CSS if()
+ + The engine is CSS-first progressive enhancement. There are two layers: +
+-
+
-
+ Baseline (works everywhere): plain
[vl-motion="…"]attribute + selectors assign the engine knobs. Noif()required. +
+ -
+ Enhancement (
@supports+if()): a single +[vl-motion]rule re-derives the same knobs using CSSif()with +media(),style()andsupports(), folding in live + conditions —prefers-reduced-motion,pointer: coarse, and + scroll-timeline availability. +
+
@supports (width: if(style(--vl-probe: 1): 1px; else: 2px)) {
+ [vl-motion] {
+ --vl-motion-intensity: if(
+ media(prefers-reduced-motion: reduce): 0;
+ style(--vl-motion-mode: cinematic): if(media(pointer: coarse): 1.2; else: 1.6);
+ style(--vl-motion-mode: subtle): 0.45;
+ else: 1
+ );
+ --vl-motion-depth: if(
+ supports(animation-timeline: view()): 1.8; /* only where scroll timelines exist */
+ else: 0
+ );
+ }
+}Fallback for browsers without if()
+
+ If a browser does not support CSS if(), the entire @supports block is
+ ignored and the baseline [vl-motion="…"] values remain in effect. Modes still work —
+ they simply do not receive the extra live pointer/support-aware refinements. Nothing breaks, and no
+ JavaScript fallback is introduced.
+
Accessibility
++ Reduced motion is always respected: +
+-
+
-
+ Under
@media (prefers-reduced-motion: reduce)the engine knobs collapse + (travel, depth and blur go to zero), and — as with every Velora effect — animations are disabled + globally in03-motion.css. +
+ -
+
vl-motion="still"lets an author opt any subtree into a motionless resting state + regardless of the OS setting. +
+
Browser Support
+
+ The vl-motion modes themselves work in all modern browsers. The if()-based
+ refinement requires a browser with CSS if() support; everywhere else the baseline modes
+ are used. See the live comparison on the
+ Zero-JS Motion showcase page.
+
Scenes
- Scenes coordinate the motion of an element and all its descendants as a single - choreographed unit. This is the difference between a primitive effect and a scene. + A scene is a shared clock for children — not a look. Layout and chrome come from the host UI + (or optional Velora theme recipes).
-Primitive vs Scene
-- A primitive effect animates one element: -
-<div vl-effect="fade-up" vl-timeline="view">
- Just this element fades up
-</div>- A scene preset coordinates the element and its children with distinct timings - per child slot: -
-<section
- vl-scene="hero"
- vl-effect="scene-hero-reveal"
- vl-timeline="view">
- <h1>1st child — fades up (slowest)</h1>
- <img src="hero.jpg" alt="" /> <!-- 2nd child — scales in after 120ms -->
- <p>3rd child — blurs in after 240ms</p>
- <a href="#" class="vl-cta">4th+ children — staggered fade</a>
-</section>The vl-scene Attribute
-
- Add vl-scene to a container to mark it as a scene host. This applies CSS containment
- (contain: layout style) so the scene is self-contained.
-
<section vl-scene="hero">...</section>
-<section vl-scene="story">...</section>
-<section vl-scene="features">...</section>
- The value is a semantic label — it doesn't change behavior today but documents intent and allows
- future CSS hooks via [vl-scene="hero"] selectors.
-
Scene Presets
-
- Scene presets are set via vl-effect on the scene host. They define child-specific
- animation sequences:
-
| Value | Children behavior |
|---|---|
scene-hero-reveal |
-
- 1st → fade-up (800ms, cinematic)- 2nd → scale-in (800ms, spring, 120ms delay)- 3rd → blur-in (800ms, soft, 240ms delay)- 4th+ → fade-up (staggered)
- |
-
scene-feature-flow |
-
- Each child gets a flow-in animation tied to view(block) scroll timeline,
- with cascading animation ranges (1st enters earliest, later children enter progressively later).
- Requires vl-timeline="view".
- |
-
scene-story-pin |
-
- Container becomes sticky (position: sticky; min-height: 100vh). Children use
- fade-up tied to the block scroll timeline.
- |
-
scene-layer-stack |
-
- Container gets perspective: 1200px. Children use 3d-entry with
- increasing translation depth per child (1rem → 4rem).
- |
-
Hero Reveal — Full Example
-<section
- vl-scene="hero"
- vl-effect="scene-hero-reveal"
- vl-timeline="view"
- vl-range="entry 0% cover 70%"
- vl-pin>
-
- <h1 class="vl-vt-shared-hero">
- Build motion-rich interfaces
- </h1>
-
- <img
- src="/hero.jpg"
- alt="Motion design system preview"
- class="vl-vt-shared-media"
- width="1200"
- height="675"
- />
-
- <p>
- Velora proves that HTML and CSS are enough to build premium motion.
- </p>
-
- <a href="/docs" class="vl-cta" vl-effect="icon-shift">
- Get started
- <svg aria-hidden="true" width="16" height="16">...</svg>
- </a>
-</section>Feature Flow — Full Example
-<section
- vl-scene="features"
- vl-effect="scene-feature-flow"
- vl-timeline="view">
-
- <!-- Each direct child flows in with cascading scroll-driven ranges -->
- <div class="vl-card">
- <div class="vl-card__title">Feature One</div>
- <p class="vl-card__body">Description</p>
+ Track + stage + acts
+ <section vl-scene vl-timeline="view" vl-pin="3" vl-scrub>
+ <div vl-stage>
+ <p vl-enter="fade-up" vl-act="1">Kicker</p>
+ <h1 vl-enter="clip-rise" vl-act="1">Title</h1>
+ <img vl-scroll="media-zoom" vl-act="2" vl-span="2" alt="" />
+ <a vl-enter="fade-up" vl-act="5">CTA</a>
</div>
- <div class="vl-card">...</div>
- <div class="vl-card">...</div>
- <div class="vl-card">...</div>
</section>
- Story Pin — Full Example
- <!-- Wrap in a tall outer container to create scroll space -->
-<div style="height: 300vh;">
- <section
- vl-scene="story"
- vl-effect="scene-story-pin">
- <h2>Chapter One</h2>
- <p>This section stays fixed while you scroll.</p>
- </section>
-</div>
-
- Child Choreography — vl-children
-
- For custom compositions that don't use a named scene preset, use vl-children to
- choreograph direct children:
-
- Value Effect on children Easing Attribute Role
- staggerfade-up with incremental delays (n × stagger-step)--vl-ease-cinematic
-
- cascadeflow-in (blur + translate + scale) with incremental delays--vl-ease-out-soft
-
- sequencefade-up with delays based on full animation duration (one-after-another)--vl-ease-cinematic
+ vl-sceneTrack — owns --vl-scene view-timeline and optional pin height vl-stageSticky viewport stage (required for pin+scrub) vl-timelineview (scroll film) or auto (time film)vl-pinTrack height in viewport multiples (e.g. 3) vl-scrubLinear fill — progress glued to scroll vl-actBeat index (same act = overlap / GSAP <) vl-spanHow many beats the tween spans vl-rangeEscape hatch — overrides act-derived ranges
- Supports up to 12 children for stagger and cascade, 6 for sequence.
- <!-- Staggered grid of cards -->
-<div
- vl-children="stagger"
- vl-stagger="80ms"
- vl-timeline="view"
- style="display: grid; grid-template-columns: repeat(3, 1fr); gap: 1rem;">
- <div class="vl-card">Card 1</div>
- <div class="vl-card">Card 2</div>
- <div class="vl-card">Card 3</div>
-</div>
-
-<!-- Sequential one-after-another reveal -->
-<ol vl-children="sequence" vl-timeline="view">
- <li>Step 1 — plays first</li>
- <li>Step 2 — plays after step 1 finishes</li>
- <li>Step 3 — plays after step 2 finishes</li>
-</ol>
-
- Stagger Interval — vl-stagger
+ Why track ≠ stage
- Override the default --vl-stagger-step (45ms) with one of the preset values:
+ A sticky element freezes its own anonymous view() progress. Children bind to the
+ named track timeline (--vl-scene) while the stage stays pinned.
-
-
- Value Delay per child Feel 60ms60ms Quick, snappy 80ms80ms Balanced 100ms100ms Comfortable 120ms120ms Slightly cinematic 150ms150ms Deliberate pacing 200ms200ms Dramatic, slow cascade
- <div vl-children="stagger" vl-stagger="120ms">
- <div>Plays at 0ms</div>
- <div>Plays at 120ms</div>
- <div>Plays at 240ms</div>
- <div>Plays at 360ms</div>
-</div>
-
- Live Demo
-
-
- Child 1
- Fades up immediately.
-
-
- Child 2
- 100ms after child 1.
-
-
- Child 3
- 200ms after child 1.
-
-
- Accessibility
+ Named presets (skin recipes)
- Scene presets and vl-children choreography all disable under
- prefers-reduced-motion: reduce — children appear in their final state instantly.
- Semantic structure (heading hierarchy, landmark roles) should be maintained regardless of motion.
+ Values like vl-scene="cinematic-hero" remain for compatibility. They ship in
+ scene-recipes.css via @velora/css/theme / full — they mix look + motion.
+ Prefer track/stage/acts for portable hosts.
- Browser Support
+ Channels on children
- scene-hero-reveal, scene-layer-stack, and vl-children
- orchestrations use time-based delays and work in all modern browsers.
- scene-feature-flow and scene-story-pin use scroll-driven timelines and
- require Chrome 115+ / Edge 115+. Unsupported browsers see a static layout.
+ Use existing channels on stage children: vl-enter, vl-scroll,
+ vl-exit, etc. The scene clock drives when they play.
diff --git a/apps/docs/src/pages/timelines.astro b/apps/docs/src/pages/timelines.astro
index 7973c1d..c789373 100644
--- a/apps/docs/src/pages/timelines.astro
+++ b/apps/docs/src/pages/timelines.astro
@@ -2,67 +2,49 @@
import Base from "../layouts/Base.astro";
---
-Timelines
-
- Control when and how animations progress via vl-timeline.
- See also: Attribute Reference → vl-timeline.
+
+ Timelines decide what drives progress. Effects decide what moves.
+ The scene engine shares one clock across stage children.
- Timeline Modes
+ vl-timeline values
-
- Value
- Behavior
-
+ Value Behavior viewScroll-driven via view(block) — element's viewport entry controls progress scrollScroll-driven via scroll(root) — page scroll position controls progress autoStandard time-based (document timeline) hoverAnimation paused until hover viewProgress from element / scene visibility (view() or named --vl-scene) scrollProgress from root scroll autoTime-based CSS animation hoverPaused until hover
- Range Presets
- Pair vl-timeline="view" with vl-range to control the animation window:
-
-
-
- Value
- Range
-
-
-
- entryentry 0% entry 100%entry-shortentry 15% cover 35%entry-longentry 0% cover 70%covercover 0% cover 100%containcontain 0% contain 100%customUses --vl-range custom property
+ Scene clock
+
+ On [vl-scene][vl-timeline="view"], stage children use
+ animation-timeline: --vl-scene and ranges derived from
+ vl-act / vl-span / --vl-beats (default 8).
+
+
+ With vl-timeline="auto", the same acts map to
+ animation-delay: (act - 1) * --vl-beat. Pin/scrub are no-ops.
+
- Boolean Modifiers
-
-
-
- Attribute
- Behavior
-
-
-
- vl-pinSticky positioning for scroll-driven scenes vl-scrubContinuous linked motion (linear timing) vl-oncePlay animation only once (forwards fill)
+ Ranges
+
+ Presets via vl-range (entry, entry-short, cover, …)
+ still apply to standalone elements. Inside a pinned scene, prefer acts; use
+ vl-range only as an escape hatch.
+
- Example
- <div vl-effect="fade-up" vl-timeline="view" vl-range="entry-short" vl-once>
- Appears quickly as it enters the viewport, then stays visible.
-</div>
+ Scrub
+ <section vl-scene vl-timeline="view" vl-pin="3" vl-scrub>
+ …
+</section>
+ vl-scrub forces linear timing and fill both on scene-driven children.
diff --git a/apps/showcase/config/template-registry.mjs b/apps/showcase/config/template-registry.mjs
index 19412d1..dc90bf4 100644
--- a/apps/showcase/config/template-registry.mjs
+++ b/apps/showcase/config/template-registry.mjs
@@ -1,4 +1,3 @@
-import fs from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";
@@ -10,68 +9,16 @@ export const DEFAULT_TEMPLATE_NAME = "default";
export const TEMPLATE_REGISTRY = {
[DEFAULT_TEMPLATE_NAME]: {
name: "Velora Default Template",
- description: "Baseline multi-page template for Velora showcase surfaces.",
+ description: "Lean public Showcase: Home, Timeline, Skins, Catalog, Hosts, Archive.",
rootFile: "index.html",
sections: {
- core: [
+ live: [
"index.html",
- "pages/core/about.html",
- "pages/core/landing.html",
- ],
- demo: [
- "pages/demo/impossible.html",
- ],
- scenes: [
- "pages/scenes/scene-hero.html",
- "pages/scenes/scene-features.html",
- "pages/scenes/scene-story.html",
- "pages/scenes/scene-creator.html",
- "pages/scenes/scroll-reveal.html",
- ],
- components: [
- "pages/components/buttons.html",
- "pages/components/forms.html",
- "pages/components/component-lab.html",
- "pages/components/component-wizard.html",
- "pages/components/icons.html",
- ],
- motion: [
- "pages/motion/zero-js-motion.html",
- "pages/motion/motion-extended.html",
- "pages/motion/motion-compiler-demo.html",
- "pages/motion/motion-principles.html",
- "pages/motion/kinetic-motion.html",
- "pages/motion/kinetic-cards.html",
- "pages/motion/scale-shift.html",
- "pages/motion/interactions.html",
+ "pages/scenes/scene-timeline.html",
+ "pages/core/skins.html",
"pages/motion/api-motion-catalog.html",
- "pages/motion/3d-explorer.html",
- "pages/motion/3d-rotation.html",
- ],
- color: [
- "pages/color/design-tokens.html",
- "pages/color/color-system.html",
- "pages/color/color-palette.html",
- "pages/color/tonal-stacking.html",
- "pages/color/tonal-tiers.html",
- "pages/color/token-spotlight.html",
- "pages/color/ambient-shadows.html",
- ],
- typography: [
- "pages/typography/typography.html",
- "pages/typography/typography-composition.html",
- "pages/typography/typography-spec.html",
- ],
- tools: [
- "pages/tools/system-modules.html",
- "pages/tools/architecture.html",
- "pages/tools/brand-voice.html",
- "pages/tools/accessibility.html",
- "pages/tools/contrast-tool.html",
- "pages/tools/converter.html",
- ],
- integrations: [
- "pages/integrations/gsap-anime.html",
+ "pages/core/hosts.html",
+ "pages/core/archive.html",
],
},
},
@@ -94,15 +41,6 @@ export function resolveTemplateInputs(templateName = DEFAULT_TEMPLATE_NAME) {
inputs[toRollupKey(relPath)] = path.resolve(APP_ROOT, relPath);
}
- const libraryDir = path.join(APP_ROOT, "pages", "library");
- if (fs.existsSync(libraryDir)) {
- for (const fileName of fs.readdirSync(libraryDir)) {
- if (!fileName.endsWith(".html")) continue;
- const key = `lib-${fileName.replace(/\.html$/i, "").replace(/[^a-z0-9]+/gi, "-")}`;
- inputs[key] = path.resolve(libraryDir, fileName);
- }
- }
-
return inputs;
}
diff --git a/apps/showcase/index.html b/apps/showcase/index.html
index e7be810..d5cf3d2 100644
--- a/apps/showcase/index.html
+++ b/apps/showcase/index.html
@@ -5,9 +5,9 @@
- Velora CSS - Motion Design System for the Web
+ Velora — Motion engine + Skins
@@ -74,13 +74,13 @@
-
@@ -50,13 +51,13 @@
-