Once UI manages app-level design configuration with the help of Providers and a config file. Write the config once with defineConfig, then hand its sections to ThemeInit and the providers exactly as written — no casts, no renamed keys:
This setup provides everything you need to get started with Once UI. Read more about the customization and usage of each provider in the Contexts section.
defineConfig returns its argument unchanged. What it adds is checking and inference:
- Every value is checked against the values Once UI accepts, so brand: "yelow" fails to compile instead of rendering without a brand colour.
- A misspelt key fails in the sections Once UI reads (style, dataStyle, fonts), so solidstyle: "flat" is caught rather than ignored.
- The literal types survive, so style.brand is "blue", not string, and the sections go straight to ThemeProvider, DataThemeProvider and ThemeInit.
Anything else in the object — schema, social, your own layout settings — belongs to your app and passes through untouched.
The file can stay JavaScript: TypeScript reads the types through the call. To see the errors inside the config file itself, name it once-ui.config.ts, or add // @ts-check at the top of the .js file.
Import it from @once-ui-system/core/config. That entry has no runtime dependencies, so the config file stays cheap to import from route handlers, middleware and scripts; the root @once-ui-system/core export works too, but pulls in the whole package.
A 2.0 layout cast every value (style.brand as Schemes) and renamed keys for ThemeInit ("solid-style": style.solidStyle). Both still compile. To drop them, wrap the existing objects in defineConfig, then pass config={style} dataStyle={dataStyle} to ThemeInit and spread the sections into the providers.
One thing changes on the way: the 2.0 docs filled ThemeInit's "viz-style" from dataStyle.variant. That attribute is the chart mode (categorical, divergent or sequential); passing dataStyle reads it from dataStyle.mode, which is what the charts style themselves by.