Performance

esbuild assigns whole files to chunks before it drops unused exports. From the root, import { Calendar } then brings the Toaster, Breadcrumb's menu and the citation card into the first chunk: 76.46 kB, against 31.60 kB from yugen-ui/Calendar. Two subpaths hold such a part themselves: yugen-ui/AIKit also exports Citation, so StreamingMarkdown from it has the citation card in the first chunk, and toast from yugen-ui/Toast brings the Toaster along, because both live in one file.

Next.js: add the package to optimizePackageImports so the dev server and the server bundle load only what a page uses. The config, and which folder each name comes from, are in Quick start › Import paths.

• Measured on a Vite 8 build with React external. An app that never renders the part never loads it.
• Until the code arrives, Breadcrumb renders the same “…” button and StreamingMarkdown the same chip, with the same size and ARIA, so nothing moves. A click or key press in that time opens the menu or the card once the code arrives, and focus moves to the real button. If loading fails, the next interaction tries again. TagPicker shows the same tags; dragging and Alt + arrow keys work once Sortable has loaded, and a tag that has focus keeps it.
• The server HTML has these placeholders and no Toaster, so hydration matches (SSR & Next.js).
• toast() calls made before the Toaster has loaded show once it mounts. A <Toaster /> you render as a child of the root provider is part of the first chunk instead: the first toast does not wait for a chunk, and its live region is in the page from the first paint.
• Two components got smaller without loading anything later. Nav no longer imports Tooltip (AppShell's Sidebar adds the rail tooltip): { Nav, NavItem } 29.94 → 11.97 kB. Calendar no longer bundles the Vietnamese locale: { Calendar } 32.39 → 30.42 kB.

On the other templates yugen css gives 11.8 to 20.0 kB, against about 26 kB (Styling › Only the CSS you use). Run it in predev / prebuild; yugen add refreshes it, and yugen css --check exits with 1 when it is out of date (CLI).

Without Tailwind, yugen css --precompile compiles the same list with your project's Tailwind packages and replaces yugen-ui/styles.css: 26.75 kB down to 12.79 to 21.06 kB on the templates.

Keyframes live in @theme, so Tailwind writes only the ones your classes use: none for theme-core.css alone, one for an app that uses only Button.

yugenHtmlAttributes() returns the attributes applyToDocument writes, for the <html> of your root layout. yugenThemeScript() returns a <head> script that applies the saved theme, or the OS setting. Both are plain functions from yugen-ui or yugen-ui/YugenProvider/document and run in a Server Component. Setup on SSR & Next.js.

On the client, YugenProvider writes the attributes in a layout effect, so a child's useEffect already sees them. Without SSR (a Vite SPA) the browser paints index.html before React runs: use the inline script from Quick start.

The first row needs the app's elements to stay the same. When the component that holds the theme state also creates the app's elements, every component re-renders on a switch (about 68 ms in the same test). Keep the theme state in a component that receives the app as children: a theme switch then re-renders that component only, and React skips the tree apart from the theme readers.

// ThemeRoot.tsx: the theme state lives here, the app comes in as children
import * as React from "react";
import { YugenProvider, type YugenTheme } from "yugen-ui";

export const SetThemeContext = React.createContext<(theme: YugenTheme) => void>(() => {});

export function ThemeRoot({ children }: { children: React.ReactNode }) {
  const [theme, setTheme] = React.useState<YugenTheme>("light");
  return (
    <SetThemeContext.Provider value={setTheme}>
      <YugenProvider applyToDocument theme={theme}>
        {children}
      </YugenProvider>
    </SetThemeContext.Provider>
  );
}

// main.tsx
createRoot(document.getElementById("root")!).render(
  <ThemeRoot>
    <App />
  </ThemeRoot>,
);

• messages and defaults written inline are compared by value, two levels deep (component, then key), so they need no useMemo. A function or element created during render is a new value each time: define it outside the component.
• In your own components, useYugenTheme() returns { theme, brand, dir } and useYugenLocale() the locale; useYugen() re-renders on either change (Theming).
• Components with variants (Button, Input, Badge, Card…) merge their classes once per combination of props: a server render of 1,000 Buttons takes 6.35 ms instead of 12.58 ms. A className is merged on top on every render (8.13 ms).

• Scales, paths, labels and the static SVG layers are memoized on the props, the width and the hidden series. Keep data and series stable (state, a constant or useMemo) so a parent re-render does not rebuild them.
• Fill and stroke sit on the series group instead of each mark: a LineChart with 4 series of 200 points and markers renders 183.9 kB of markup instead of 263.3 kB.
• Give Sparkline a number width in tables and lists: it then uses no ResizeObserver. 200 Sparklines with width={120} commit once instead of three times and mount in 60–153 ms instead of 229–514 ms. width="auto" follows the parent.
• In your own components, useElementSize({ enabled: false }) skips measuring when the size is known (Hooks). Choosing a chart form and its palette: Data visualization.