Scene draws a 3D view with three.js inside a Once UI frame. Shapes take token colours like any component, so color="brand-strong" follows the brand you pick. The lights, the floor shadow and the grid follow light and dark. You don't write a render loop: the scene draws when something changes, animates only while something asks it to, and stops when it scrolls out of view or the tab is hidden.
three is an optional peer dependency, like maplibre-gl for Map. Install it next to Once UI and import the scene from its own entry point, so an app without a 3D view never loads it:
The scene renders on the client only. On the server and until three.js loads it draws an empty frame of the same size, so the page does not shift. Without WebGL it says so in the frame instead of failing.
Group shapes with SceneGroup to move them together, and animate them with useSceneFrame, which runs before every frame. SceneLabel pins ordinary HTML to a point, so a status tag follows the robot's head as it turns. Click handlers work on meshes and groups.
SceneModel loads a .glb or .gltf file. The loader comes with three and loads the first time a model is placed. Each file is fetched once per scene, however many copies you place. color repaints a plain model in a theme colour; leave it out to keep the model's own materials.
A colour is a token pair, a custom property or any CSS colour.
emissive makes a part glow regardless of the lights: visors, status lights, screens.
- Theme: token colours are read again when the theme, brand, accent or neutral changes anywhere above the scene, including a data-theme section.
- Performance: the canvas draws on demand. It runs continuously only while a useSceneFrame callback is mounted, the turntable turns, or a drag is settling, and stops off screen and in hidden tabs. The pixel ratio is capped at 2 (maxPixelRatio).
- Reduced motion: the turntable stands still and frame callbacks get a zero delta, so animation pauses but the scene still draws.
- Cleanup: geometry, materials and the WebGL context are released when the scene unmounts.
- Accessibility: the canvas is an image named by labels.scene. Describe what it shows, and put anything a person must read or act on in the page or in a SceneLabel, not only in the 3D view.
useScene() returns the three.js scene, camera and renderer, the loaded three module, invalidate() to draw after changing something yourself, and color() to read a token as a THREE.Color. onSceneLoad hands over the same object once the scene starts. Post-processing, shaders and particle effects belong in @once-ui-system/fx.