Documentation
Changelog
What changed, by date.
Prelaunch. There are no version numbers yet: entries are dated, newest first. Numbering starts at launch.
2026-11-22
Every Radix primitive now has a component here. Ten were added; no package was added to the library.
alert-dialog. A question that waits for its answer: no close button, no dismissal by a click outside, focus on the answer that changes nothing.collapsible. One section that a button opens in place. For several under headings,accordion.hover-card. A preview of where a link goes, on hover and on keyboard focus.menubar. A bar of menus with items, checkbox and radio items, submenus and shortcuts. Its menus close at once, without an animation: a menu still animating out closed the one the arrow key had opened.navigation-menu. Site links, some opening a panel of further links; the panel never leaves the screen.toolbar. Buttons, toggles and links as one Tab stop, moved through with the arrow keys.otp-field. A one-time code, one box per character, posted as one value.password-field. A password input with a named button that shows and hides it.accessible-icon,visually-hidden. A name for an icon that stands alone, and words kept for screen readers.- Showcase and checks. A Primitives page, with each keyboard pattern checked key by key at desktop and phone widths, left-to-right and right-to-left.
- The site. The showcase is now the library's website, for ui.rivier.ai: a landing page, documentation (introduction, installation, theming, the command, for assistants, accessibility, the conventions and this changelog), a page for every item with its example, its whole source and the demonstration the checks drive, search with Ctrl or Cmd and K, a light or dark switch, and any page right-to-left with
?dir=rtl. It servesllms.txt,registry.jsonandr/<name>.json, so the shadcn command can add from it. The page that showed everything at once is at/showcase.npm run site:stage -- <folder>lays the site out as a plain Next.js app for a host to build and serve. - Packages.
lucide-react,motion,tailwind-merge,axe-core,puppeteer-core,eslintandtypescript-eslintat their latest releases;@types/nodeat 24, the Node the checks run on.
2026-11-13
More that the existing components can do. Every change is an added prop or part with the old behaviour as its default; no package was added to the library. To take them into a project that already has the items, add them again with overwrite (which replaces the project's own edits to those files).
media-row-listanddropzone. A row can be in a state of the project's own:statetakes any word, withstateLabelandstateTone(neutral,success,warning,destructive, each with its own mark;stateIcononUploadItemreplaces the mark). Rows take astatusline,controlsof the project's own,hideCover, andaltRequired,altInvalidandaltErrorfor the description field (the message is tied to the field and read out when it appears). The list takesonPauseandonResume(pause and resume buttons on uploading and paused rows),altRequired,onDropped, andvariant="lines"for hairline rows with no box. A row now has the surface radius at every roundness, where it took the control radius and became a pill.UploadItemtakesas="div", so a media row no longer holds a list inside a list item.film-stage. Any number ofFilmStageAudioat once, each with its ownstart,durationandvolume, all following the clock, the rate, a seek and the mute.renderAt(time, { timeout })now loads pictures markedloading="lazy"at once (off screen or not displayed, they never arrived and it never resolved), countssrcsetpictures, waits for the decode after a late load, and rejects aftertimeoutmilliseconds (default 10000) with an error naming the picture and its scene.FilmStagePreviousSceneandFilmStageNextScene, the keys P and N,previousScene()andnextScene()on the handle, each reading out the scene arrived at;onSceneChangewith the scene, its place and the one before;sceneIndexfromuseFilmClock. Letter keys are found by their place on keyboards of other scripts.wizard. Driven from outside: withonNext,onBackandonSkipthe buttons tell the project and the wizard does not move; the project setsstep.pendingmakes the buttons and the rail wait and marks the card busy. The step animation and the move of focus to the new heading now follow any change ofstep, not only the wizard's own buttons. Uncontrolled use is unchanged.sortable-list.onDropped({ value, from, to, values }), called once when a drag is let go, a lifted row is dropped (Space, Enter, Tab or focus leaving) or a move button is pressed; not when a lifted row is put back with Escape.onValuesChangestill reports every step.dock.stackBelow(rem, default 42) sets the width below which the panel gives way to the bar.DockBartakesshow:"stacked"for a bar written insideDockMainabove a region that must stay lowest (a composer),"collapsed"for the strip of a wide dock,"both"(default) as before.model-viewerandadd. A registry entry now listsdevDependencies: the types of a package that does not carry its own (@types/three,@types/d3-scale,@types/d3-shape).addinstalls them with-D,infolists them,doctorreports them missing, andnpm run registryfails when a dependency without types has no entry inTYPES. Pinch zoom is now exercised in the checks.lightboxwithcarousel. On close, a trigger inside a slide that is out of view (and so inert) is scrolled into view and then focused; before, focus was lost. A slide may have several triggers: the one in view and reachable is preferred, one that is not drawn is never chosen.virtual-list.scroll="window"onVirtualListandVirtualGrid: the list is as long as its rows and the page scrolls it;scrollToIndexscrolls the page and leaves room for a sticky header through the list'sscroll-margin-top. A changingcountand rows reordered undergetKeyare now in the checks.comboboxandgallery: clean undereslint-config-next. The combobox trigger statesaria-expanded,aria-controlsandaria-haspopupitself.GalleryImagetakesasandGalleryLightboxtakesrenderImage, for the framework's image component; the default stays<img>, with the rule switched off on those lines and the reason stated (and the same on the poster ofmodel-viewer).npm run lintnow enforces@next/next/no-img-elementon the registry (@next/eslint-plugin-next16.4.6, MIT, a dev dependency of the lint tooling only), and the whole registry was run througheslint-config-next16.4.6 and reports nothing.- Types and proportions.
MediaRowListinherited theonPauseof adiv(a media event), which would have made the new prop's argument untypable. The large picture inGalleryLightboxkeeps its proportions when the image component writeswidthandheightattributes. Inlightbox, a picture taller than the slide was cut off at the slide's edge (max-h-fullhad nothing definite to be a percentage of); a slide is now a size container and holds a picture directly inside it to its own height and width. - Not in it, with the releases checked on 2026-11-13. glTF that carries Gaussian splats in an extension (
KHR_gaussian_splatting): three.js 0.187.0 has a loader plugin for it, but the object it makes needs the WebGPU renderer, and the viewer draws with WebGL 2 so that Spark (@sparkjsdev/spark2.4.0), which reads splat files and not glTF, can draw in the same canvas. Left until one of the two changes. - Showcase and checks. New demonstrations on
/carousel,/flows,/panels,/stage,/lists,/gallery, each with its checks;/modelschecks a pinch with two fingers at phone width.
2026-11-12 (third entry)
What three design studies in a project still found missing, added as general components. One package was added, and only for one item: @sparkjsdev/spark (MIT), which model-viewer fetches when a file is Gaussian splats and not otherwise. Everything else is built on what the library already used.
- 3D.
model-viewer: one model to turn, zoom and reset. glTF and GLB through three.js's own loader; Gaussian splats (.spz, .ply, .splat, .ksplat, .sog) through Spark. It is plain three.js rather than a react-three-fiber scene, so the file itself carries nothing heavy: three.js, the loader and Spark are fetched when the viewer comes near the screen. A poster and progress while loading; arrows turn, plus and minus zoom, Home resets, each announced; buttons for all of it; a named still where WebGL 2 is missing or the file cannot be read; no turning by itself under reduced motion, and a button to stop it otherwise; drawing stops off screen and in a hidden tab; vertical swipes and the plain wheel stay with the page; an optional hand-off to AR Quick Look (USDZ) or Scene Viewer behindar. Two viewers given the sameviewandboundsshare one camera. - Comparison and provenance.
compare-slider(two layers of any content cut withclip-path, a divider that is a slider),certainty-legend(classes the project names, each with a pattern as well as a colour, switched on and off) andprovenance-label(what a picture is, with its sources, placed where a player's controls cannot cover it). - Collections.
carousel(native scroll-snap; previous and next, dots or a count, autoplay that needs its pause button and stops on hover, focus, off screen and under reduced motion),virtual-list(VirtualListandVirtualGrid: thousands of items of any height, only those in view in the page, each with its place in the whole list, the scroll position remembered) andmedia-row-list(reorderable upload rows with progress, retry, remove, a description field and a cover choice, composed fromdropzoneandsortable-list). - Timed scenes.
film-stage: the chrome and the clock for a sequence of scenes the project draws from time. Play, pause, seek and rate, controlled or not; cuts and crossfades computed from the time; the existingscrubber,scene-strip,captionsandhotspotswork inside it; a clock that sound and anything else can follow; andrenderAt(time), which draws one moment with no timer running, for export frame by frame from a headless browser. - Decided against, with the releases checked on 2026-11-12. Embla (
embla-carousel-react8.6.0, MIT) for the carousel: the browser's scroll-snap already gives swipe, momentum and right-to-left. TanStack Virtual (@tanstack/react-virtual3.14.26, MIT) for the list: it is headless, and the roles, the positions, focus and restoration that make up most of the component would still be written here. For the viewer:@google/model-viewer4.4.0 (Apache 2.0) is a web component that asks for three.js 0.183 where the library is on 0.187, and has no splats;@react-three/drei10.7.9 (MIT) would add a large package for one loader hook;@mkkellogg/gaussian-splats-3d0.4.7 (MIT) was last released in January 2025;gsplat1.2.9 (MIT) has its own renderer rather than three.js and reads fewer formats. - Showcase and checks. Five more component pages (
/models,/evidence,/carousel,/lists,/stage) with their checks.scripts/make-test-assets.tswrites the small 3D files the viewer's page loads (a vase as glTF, USDZ and splats in three formats, all computed, about 380 KB together).
2026-11-12 (second entry)
What a real project found missing, added for every project. No package was added to the library for any of these: they are built on Radix, Motion, cmdk and lucide, which the library already used, and where Radix has no primitive the WAI-ARIA Authoring Practices pattern is written here.
- Dates and times.
calendar(one day, several, or a range; days as plain"2026-11-14"strings; unavailable days with a reason that is read out; a word mark per day; the date-grid keyboard pattern),date-picker(DatePicker,DateRangePicker; never the native picker),slot-picker(offered times as a radio group),time-picker(hour, minute and day-period spin buttons). - Choices.
chip(removable, pressable, and a set to choose from),tile-group(picture tiles),segmented-control,number-stepper(a spin button with hold-to-repeat),combobox. - Flows and lists.
steps(a rail with done, assumed, current, upcoming, skipped and blocked steps),wizard(a shell that moves focus to each step's heading),sortable-list(drag, keyboard lift and drop, and move buttons, each move announced),timeline,undo-line. - Panels.
bottom-sheet(snap points, drag to dismiss, and a handle that works from the keyboard),dock(a resizable panel beside the page: the window-splitter pattern, with a collapsed bar),map-frame(a container that loads a map engine only when asked, with a list equivalent and full screen). - Conversation.
thread(a log that follows new content until the person scrolls up),message,streaming-text(not announced word by word; the finished reply is announced once),status-line(the one polite live region),composer(attachments and voice slots, safe with input methods),part-frame(a card with a lifecycle and an expand to full screen). - Pictures, video and sound.
gallery,lightbox(swipe, keys, zoom by pinch, wheel, double tap and buttons, opening from its thumbnail as a shared element),dropzonewith upload rows and progress (no upload engine),video-player,audio-playerwith a waveform,scrubber(buffered ranges, marks, a preview with thumbnails),captionsandTranscript,scene-strip,hotspots, anduse-media, the state of a media element that they share. - Records and decisions.
compare-table(a sticky first column; columns that snap inside their own scroll area on phones),fact-rowwithSourceChipand actions the project names,consent(nothing pre-ticked; declining weighs the same as accepting),language-switcher(languages by their own names, no flags),price-breakdown,countdown(text, announced only at thresholds). - Foundations.
direction-providerandlib/directionfor right-to-left,lib/announce(one shared live region),lib/use-controllable-state. The theme now adapts tracking, leading and line breaking to the script of the language. - Changed.
theme-providerreads the stored theme and the device preference as external stores (it set state in an effect, which a project's lint rejects) and now follows a change made in another tab.skeletoncan wrap content and hold its final size (loading), and hasSkeletonText.view-transitionaddsSharedElementandTransitionBoundaryover React's own<ViewTransition>.scene,chart,globeandnumber-tickerno longer fail the React Compiler lint rules. - Checking.
npm run lint(ESLint with the React rules a project runs).npm run check: every component page in a real browser at desktop and 390 px, each left-to-right and right-to-left: keyboard patterns key by key, roles and names, focus, sideways overflow, console errors, and the WCAG 2.2 A and AA rules of axe-core.CONVENTIONS.mdgains the rules these follow: parts, controlled and uncontrolled state, no fixed words, plain values for dates, direction and scripts. - Registry. Items carry
categories. Installing with the shadcn command from the@rivier-uinamespace was tested (seeREADME.md).
2026-11-12
First build. Its own repository, rivier-ui, Apache 2.0, private until launch.
- Theme. One stylesheet of tokens (shadcn variable names) with light and dark, five steps of roundness from square to pill, nine named highlight colours and any other by hue and chroma, a fixed chart palette checked for colour-blindness and contrast in both modes, motion tokens, flat surfaces. The default look follows the rivier.ai design language.
- Registry. One file per component with a header (what, when, example); dependencies read from imports;
registry.json,r/<name>.jsonandllms.txtgenerated from them. - Command.
rivier-ui list | info | add | theme | doctor, copying source into a project. - Components. Controls and surfaces, layout and bento grid, motion and transitions, 3D, charts.
- Showcase site. Every item with the theme switches, installed by the library's own command.
- Rivier Architect plugin.
rivier-ui, so a project's assistant looks here before writing a component.