Once UI ships 2.0, one spec drives its docs, its agent harness and its validator

A design system usually assumes a person is reading the docs and writing the code. If a coding agent is doing both, the docs, the API and the checker all have to say the same thing, or the agent guesses and the frontend drifts. Once UI 2.0, released this morning, is written so the three cannot drift apart.

What is in it

The release notes call 2.0 "the release where Once UI becomes a system an AI can build with correctly", and lay out the mechanism plainly: one spec drives the documentation site, the ai/ harness the agent reads, the validator that checks each component call and the codemod that moves an app from 1.8 to 2.0. So the prop names, the types and the accepted values the agent sees are the exact ones the package accepts, and a bad call is caught by the validator rather than crashing at render.

Utility classes and responsive rules are generated rather than hand-written, and the breakpoints are fixed at five steps. That means the CSS and the JavaScript agree at every width, and a responsive Flex can be a server component. npm i @once-ui-system/core now resolves the 2.0 line by default.

Next.js is now optional

The core no longer imports next/* at runtime. SmartLink, Media, Logo and a few other components render through an adapter layer whose defaults are plain DOM, so a Vite or plain React app can install the package without pulling Next.js. A Next app keeps the 1.8 behaviour with a one-line import change to @once-ui-system/core/next, and the release notes say the vendor verified this by installing the packed tarball into a React app with no next in node_modules.

Scheme tokens moved to the oklch() colour space, which sets a browser floor: Chrome 111, Safari 15.4 and Firefox 113. A bundler is still required, because components import their own .module.scss files.

Upgrading from 1.8

The release notes call the migration a checklist: run the codemod, install the peers for the /data, /code and /media subpaths, fix what the codemod reports, adjust the Next.js import, check the browser floor, drop custom breakpoints and re-shape any ScrollContainer. Most apps finish in the first two steps. ColorInput's onChange signature changed and has to be rewritten by hand, because a rename cannot express that.

IconName is a union type in 2.0, where 1.8 accepted any string, so a name that used to render a blank space is now a type error. The release notes say those errors will point to bugs the app already had.

Why a machine-readable spec matters when the agent is writing the screens

If a React or Next frontend is being written by a coding agent, coherence across screens is the part that breaks first: the twentieth screen quietly disagrees with the second one because the agent guessed a prop name or picked a colour from memory. A design system that publishes its own machine-readable spec, and ships a validator that checks the agent's output against it, changes the shape of that problem: the agent writes what the package accepts, or the validator flags it before the code lands.

The wider once-ui-system GitHub organisation carries the traction: 261 stars on core, 831 on nextjs-starter and 1,406 on magic-portfolio at the time of writing.

Source

Primary source: Once UI v2.0.0 release notes on GitHub. Migration checklist and rationale in the v2.0.0-alpha.0 notes. Product Hunt launch: Once UI 2.0.