Meet Lu.
Lu is Lumen’s calm, curious companion. Use the same ivory lantern, cyan details, and warm flame across your websites and projects.
Try the three states
Choose a state to start. Celebration plays once and returns to idle. Pause whenever you like.

Lu is resting.
Use the shared player
Lu is an optional entry point in @santi020k/lumen. Import its player, stylesheet, and artwork only where you use the mascot. The player has no runtime dependencies.
pnpm add @santi020k/lumenIn Astro or Vite, import artwork with ?url so your build emits the files. For another bundler, serve the exported WebP files from your public directory and pass the resulting atlas URL. Retain the still image inside the mascot element.
<span class="lumen-lu" data-project-lu role="img" aria-label="Lu, Lumen's light companion">
<img src={still} width="320" height="352" alt="" />
</span>import { mountLu } from '@santi020k/lumen/lu'
import '@santi020k/lumen/lu/styles.css'
import atlas from '@santi020k/lumen/lu/sprites.webp?url'
import still from '@santi020k/lumen/lu/still.webp?url'
// Retain an image child as the loading and failure fallback.
const host = document.querySelector<HTMLElement>('[data-project-lu]')
if (host) {
const player = mountLu(host, { atlas })
// Bind these to your application's real actions:
player.setState('thinking')
player.play()
// player.setState('celebration') // Plays once, then returns to idle.
// player.pause()
// player.destroy() // Call when the view unmounts.
}Use onChange to keep your controls in sync with state,playing, reducedMotion, and loading status. Notifications describe state changes, not individual animation frames.
Keep state in your framework
Use your existing Lumen buttons for play and pause. Each instance has its own player. Call destroy() when removing the view; it cancels playback and restores the host element.
---
import { Image } from '@santi020k/lumen-astro'
import still from '@santi020k/lumen/lu/still.webp'
import '@santi020k/lumen/lu/styles.css'
---
<span class="lumen-lu" data-project-lu role="img" aria-label="Lu">
<Image src={still} width={320} height={352} alt="" radius="none" />
</span>
<script>
import { mountLu, type LuPlayer } from '@santi020k/lumen/lu'
import atlas from '@santi020k/lumen/lu/sprites.webp?url'
const players = new Map<HTMLElement, LuPlayer>()
const mount = () => {
for (const host of document.querySelectorAll<HTMLElement>('[data-project-lu]')) {
if (players.has(host)) continue
const player = mountLu(host, { atlas })
// Connect a Lumen Button to player.play() and player.pause().
players.set(host, player)
}
}
mount()
document.addEventListener('astro:page-load', mount)
document.addEventListener('astro:before-swap', () => {
for (const player of players.values()) player.destroy()
players.clear()
})
</script>import { useEffect, useRef } from 'react'
import { Image } from '@santi020k/lumen-react'
import { mountLu, type LuPlayer, type LuState } from '@santi020k/lumen/lu'
import atlas from '@santi020k/lumen/lu/sprites.webp?url'
import still from '@santi020k/lumen/lu/still.webp?url'
import '@santi020k/lumen/lu/styles.css'
export function Lu({ state = 'idle', playing = false }: { state?: LuState; playing?: boolean }) {
const host = useRef<HTMLSpanElement>(null)
const player = useRef<LuPlayer | null>(null)
useEffect(() => {
if (!host.current) return
const current = mountLu(host.current, { atlas })
player.current = current
return () => {
current.destroy()
player.current = null
}
}, [])
useEffect(() => { player.current?.setState(state) }, [state])
useEffect(() => {
if (playing) player.current?.play()
else player.current?.pause()
}, [playing])
return <span ref={host} className="lumen-lu" role="img" aria-label="Lu">
<Image src={still} width={320} height={352} alt="" radius="none" />
</span>
}Keep Lu considerate
- Playback starts paused. If you enable autoplay, provide a visible pause control.
- Reduced motion shows a still pose while keeping state selection available.
- The atlas loads when Lu enters the viewport. Playback pauses offscreen and in hidden tabs.
- Keep the still image available if JavaScript or the animation asset fails to load.
- Use product text for progress, success, and errors. Lu is an additional visual cue.
- Keep an accessible name, or hide the whole mascot from assistive technology when it is decorative.
Share one set of artwork
The lu/sprites.webp export contains an eight-column, three-row sheet. Each cell is 320 × 352 pixels. lu/manifest.json describes the occupied frames and their durations for a native animation view or another renderer.lu/still.webp supplies the neutral fallback.
Set --lu-size on the host to change its width while preserving the aspect ratio. Keep the palette, proportions, and warm flame intact. Lu complements theshared foundations and does not replace the Lumen logo.