Agent Handbook

Operational guide for AI agents on Velora. Demos on other pages use the same publicvl-* API — test there, do not invent showcase-only motion.

vl-enter="fade-up" vl-timeline="view"

Product Thesis

Velora is not a generic UI kit and not a JavaScript animation wrapper. Velora is a declarative motion system for HTML, powered by modern CSS.

The core idea:

1. Developers write semantic HTML.
2. They add Velora classes and vl-* attributes.
3. Velora maps those contracts to CSS-based layout, motion, scenes, and transitions.

<section
  vl-scene="hero"
  vl-timeline="view"
  vl-range="entry 0% cover 70%"
  vl-pin>
  <h1 vl-enter="fade-up">Build motion-rich interfaces with HTML and CSS</h1>
  <p vl-enter="fade-up" vl-delay="120ms">No animation libraries. No animation runtime JS.</p>
</section>

Non-Negotiable Rules

All agents must follow these rules without exception.

2.1 No JS frameworks in core

Do not introduce React, Vue, Framer Motion, GSAP, Locomotive Scroll, Swup, or any comparable runtime as part of the Velora core.

2.2 No JavaScript animation logic in core motion

Do not implement animation timing, scroll choreography, reveal effects, or page transitions with JS if modern CSS can handle it.

Preferred platform features:

• @view-transition
• view-transition-name
• view-timeline
• scroll-timeline
• animation-range
• @starting-style
• transition-behavior: allow-discrete
• Container queries
• interpolate-size: allow-keywords
• Logical properties
• :has() where appropriate

2.3 HTML first

Preserve semantic HTML. Avoid wrapper-heavy markup unless structurally necessary.

2.4 CSS-first architecture

Velora is implemented as layered CSS with a coherent token system and a stable public API.

2.5 Minimal runtime only when truly needed

JavaScript may be used only for:

• Theme persistence
• Accessibility helpers where HTML alone is insufficient
• Tiny enhancement modules
• Future optional runtime hooks

JS is additive — never the foundation of the motion engine.

2.6 All styling contracts must be namespaced

• Classes: .vl-*
• Custom properties: --vl-*
• Attributes: vl-*

2.7 Design tokens use modern color primitives

Prefer oklch() and tokenized semantic variables.

2.8 Accessibility is mandatory

Every feature must account for:

• Semantic structure
• Keyboard access
• Visible focus states
• Reduced motion
• Content readability
• Progressive enhancement

Attribute System Contract

Agents must treat the attribute system as a declarative grammar, not a random set of flags.

Primitive vs Scene Presets

This distinction is mandatory.

A channel preset affects the element itself:

<div vl-enter="fade-up" vl-timeline="view"></div>

A scene coordinates children on a shared clock:

<section vl-scene vl-timeline="view" vl-pin="3" vl-scrub>
  <div vl-stage>
    <h1 vl-enter="clip-rise" vl-act="1">Title</h1>
  </div>
</section>

Agents must not blur these concepts.

CSS Layer Architecture

@layer velora.reset, velora.tokens, velora.layout, velora.motion,
       velora.components, velora.transitions, velora.utilities, velora.overrides;

Implementation Rules

Prefer variables over hardcoded values

/* Bad */
[vl-effect="fade-up"] {
  transform: translateY(28px);
  transition: all 480ms cubic-bezier(0.2, 0.8, 0.2, 1);
}

/* Better */
[vl-effect="fade-up"] {
  --vl-translate-y-from: 1.75rem;
  --vl-motion-duration: var(--vl-motion-normal);
  --vl-motion-ease: var(--vl-ease-cinematic);
}

Prefer composition over monolith selectors

Build small contracts that compose: scene host → effect preset → timeline binding → child choreography → transition layer.

Keep examples premium but realistic

Examples should feel cinematic and polished, but remain maintainable and instructive.

What Agents Must Never Do

• Introduce GSAP, Framer Motion, ScrollTrigger, Locomotive Scroll, Barba.js, Swup, React, or Vue into core motion
• Replace semantic elements with div soup unnecessarily
• Bypass the attribute system with bespoke scene logic when a general vl-* contract should exist
• Hardcode brand or demo-specific values into the framework core
• Ignore reduced motion — every animation pattern must have a fallback

Reduced Motion Baseline

@media (prefers-reduced-motion: reduce) {
  [vl-effect],
  [vl-scene],
  [vl-transition],
  [vl-page-transition] {
    animation: none !important;
    transition-duration: 0ms !important;
  }
}

Safe Prompting Patterns

For framework code

Implement vl-effect="fade-up" and vl-timeline="view" inpackages/css using layered CSS only. Do not use JavaScript. Preserve the existing namespace and token system. Keep the implementation reusable, documented, and reduced-motion aware.

For new scene presets

Create a new scene preset called scene-feature-flow that coordinates heading, copy, and cards using scroll-driven CSS. Use vl-scene, vl-effect,vl-children, and CSS custom properties. Avoid demo-specific hardcoding.

For docs

Create a docs page for vl-effect with API explanation, allowed values, implementation notes, accessibility notes, and two HTML examples using only semantic markup.

For refactors

Refactor this implementation so that public behavior is expressed through vl-*attributes and tokenized CSS variables rather than one-off component selectors.

For reviews

Review this Velora code for violations of project rules: no JS animation logic, semantic HTML, namespace correctness, reduced-motion support, token usage, and layer organization.

Definition of Done

A Velora feature is done when:

1. The public API is clear
2. Namespaces are correct (.vl-*, --vl-*, vl-*)
3. Tokens are used appropriately
4. Reduced-motion behavior exists
5. Docs can explain it simply
6. The playground demonstrates it cleanly
7. Implementation fits the architecture
8. No forbidden JS framework or runtime pattern was introduced

Final Instruction

When in doubt, choose the path that is:

• More semantic
• More CSS-native
• More tokenized
• More composable
• More accessible
• Easier to document
• Less dependent on JavaScript

Velora should prove that modern HTML and CSS are enough to build premium motion systems when the architecture is designed correctly.