Skip to main content
196

Search Lumen

Find components, APIs, guides, and recipes.

GitHub
All documentation
Lu mascot

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.

shell
pnpm add @santi020k/lumen

In 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.

html
<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>
typescript
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.

astro
---
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>

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.

All documentationWeb and native guides