Why the flash happens at all

Server-rendered HTML has no idea what theme a returning visitor prefers — that preference lives in the browser's localStorage, which the server can't read. So the page necessarily ships with some default theme baked into the markup. If you apply the real theme in a React useEffect, that effect runs after the browser has already painted the default — hence the flash.

The fix: a synchronous script before hydration

The theme has to be applied before the browser paints anything, which means before React even loads. A plain, tiny, synchronous <script> in <head> — or as early in <body> as your framework allows — does exactly that:

(function () {
  try {
    var stored = localStorage.getItem("oks-ui-theme");
    var theme = stored === "light" || stored === "dark"
      ? stored
      : (window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light");
    document.documentElement.setAttribute("data-theme", theme);
  } catch (e) {}
})();

Three things make this work that are easy to get wrong in a rewrite:

• It runs before hydration, not in an effect. In Next.js that's <Script strategy="beforeInteractive">; in a non-Next app it's a plain inline <script> placed before your stylesheet, since the attribute has to exist before the CSS that reads it is applied.

• It falls back through three sources in order: an explicit stored choice, then the OS-level prefers-color-scheme media query, then a hard default. Skipping the media-query fallback means a first-time visitor with dark mode set at the OS level still sees a light flash.

• It's wrapped in try/catch. localStorage throws in some locked-down or privacy-mode browser contexts — a script this early in the page load has no error boundary to catch it, so an uncaught throw here can block the rest of the page from rendering at all.

The React side: expect the mismatch, don't fight it

The script sets data-theme on <html> directly, outside React's tree — which means React's hydration will notice that attribute the server never rendered and, by default, log a mismatch warning. The fix isn't to move the logic into React, which reintroduces the flash — it's to tell React this one attribute is expected to differ:

<html lang="en" suppressHydrationWarning>
  {/* ... */}
</html>

Scope suppressHydrationWarning narrowly. Put it only on the element whose attributes the script actually touches — <html> here. Slapping it on a much larger subtree silences real hydration bugs along with the expected one.

Everything downstream is just CSS

Once data-theme="dark" is on <html>, oks-ui's tokens respond to it with an ordinary attribute selector — no React context, no re-render, no provider:

:root { --oks-color-surface: #fff; }
:root[data-theme="dark"] { --oks-color-surface: #0a0a0a; }

A toggle button just flips the attribute and writes the same key back to localStorage — no re-run of the init script needed, since the browser already has the page open. See the full token list this responds to at Dark mode.

Originally published at oks-ui.com.

import { Card } from "oks-ui/card";
import "oks-ui/card.css";
import { Stat } from "oks-ui/stat";
import "oks-ui/stat.css";
import { Chart } from "oks-ui/chart";
import "oks-ui/chart.css";
import { Table, type TableColumn } from "oks-ui/table";
import "oks-ui/table.css";
import { Chip } from "oks-ui/chip";
import "oks-ui/chip.css";

Decide what goes on it first

The hardest part of a dashboard isn't the code, it's choosing what to show. A useful test: every number on the first screen should answer a question someone actually asks every day. "How much did we sell this week?" earns a card. "Total registered users since launch" usually doesn't, because it only ever goes up and nobody acts on it. Keep the top row to four numbers. Show each one next to its change over a comparable period, because a number without context can't tell you whether today is good or bad. Put detail — the chart and the table — underneath, where people look once the top row has told them something is worth a closer look.

1. KPI cards

Stat shows a label, a big value, and an optional change with a direction. The direction colours the change pill and picks the arrow.

const kpis = [
  { label: "Revenue", value: "$48,210", delta: "+12.4%", trend: "up" },
  { label: "Orders", value: "1,284", delta: "+3.1%", trend: "up" },
  { label: "Refunds", value: "18", delta: "-2", trend: "down" },
  { label: "Conversion", value: "3.2%", delta: "0.0%", trend: "flat" },
] as const;

<div className="kpi-grid">
  {kpis.map((k) => (
    <Card key={k.label} shadow="sm" radius="lg" style={{ padding: 20 }}>
      <Stat label={k.label} value={k.value} delta={k.delta} trend={k.trend} />
    </Card>
  ))}
</div>

Stat also takes an icon, a help line under the value, and a spark slot for a tiny chart.

2. The revenue chart

Chart takes rows of data, the key for the x-axis, and the series to draw. Multiple series get a legend automatically.

const revenue = [
  { month: "Jan", online: 12400, store: 8200 },
  { month: "Feb", online: 13900, store: 7900 },
  { month: "Mar", online: 15100, store: 8800 },
  { month: "Apr", online: 16800, store: 9100 },
  { month: "May", online: 18200, store: 9600 },
  { month: "Jun", online: 21000, store: 10400 },
];

<Card shadow="sm" radius="lg" style={{ padding: 20 }}>
  <Chart
    type="area"
    title="Revenue"
    description="Online vs. in-store, last 6 months"
    data={revenue}
    x="month"
    series={[
      { key: "online", name: "Online" },
      { key: "store", name: "In store" },
    ]}
    height={280}
  />
</Card>

Change type to "line" or "column" and nothing else needs to change. The chart has tooltips on hover and can be browsed with the arrow keys.

3. Recent orders

Table takes column definitions and rows. A column's render function controls how a cell looks — here, a status Chip.

type Order = { id: string; customer: string; total: number; status: "Paid" | "Pending" | "Refunded" };

const STATUS_COLOR = { Paid: "success", Pending: "warning", Refunded: "default" } as const;

const columns: TableColumn<Order>[] = [
  { key: "id", header: "Order" },
  { key: "customer", header: "Customer", sortable: true },
  {
    key: "total",
    header: "Total",
    align: "end",
    sortable: true,
    render: (o) => `$${o.total.toFixed(2)}`,
  },
  {
    key: "status",
    header: "Status",
    render: (o) => (
      <Chip size="sm" variant="soft" color={STATUS_COLOR[o.status]}>{o.status}</Chip>
    ),
  },
];

<Card shadow="sm" radius="lg" style={{ padding: 20 }}>
  <Table aria-label="Recent orders" columns={columns} rows={orders} getRowKey={(o) => o.id} />
</Card>

Sortable columns sort on click, with no extra code.

4. The layout

A few lines of CSS grid make it responsive: four KPI cards in a row on desktop, two on phones.

.dashboard { display: grid; gap: 16px; }
.kpi-grid { display: grid; gap: 16px; grid-template-columns: repeat(4, minmax(0, 1fr)); }
.dashboard-main { display: grid; gap: 16px; grid-template-columns: 2fr 1fr; }

@media (max-width: 900px) {
  .kpi-grid { grid-template-columns: repeat(2, minmax(0, 1fr)); }
  .dashboard-main { grid-template-columns: 1fr; }
}

Put the chart in the wider column of .dashboard-main and a smaller card — top products, or a donut chart — in the narrow one.

5. Loading states

Dashboards load data, and blank cards while waiting look broken. Table shows skeleton rows with isLoading, and Chart shows a loading overlay with the same prop:

<Table aria-label="Recent orders" columns={columns} rows={orders ?? []} getRowKey={(o) => o.id} isLoading={!orders} />
<Chart type="area" data={revenue ?? []} x="month" series="online" isLoading={!revenue} />

Dark mode

Every component here uses oks-ui's design tokens, so the whole dashboard switches to dark mode when you set data-theme="dark" on the html element — cards, chart, table and chips included. See a complete version on the patterns page.

Originally published at oks-ui.com.

Why "just import it" can be expensive

The usual import looks harmless:

import { Button, Modal, Table } from "oks-ui";
import "oks-ui/styles.css";

Bundlers try to drop unused exports ("tree shaking"), but they can only drop code they can prove has no side effects. A stylesheet import is a side effect by definition, and a single combined stylesheet contains every component's CSS no matter which ones you use. The result in many real apps: the whole library ships. For oks-ui that is around 770 KB of JavaScript before compression and a 320 KB stylesheet — even for a page with three components.

Import each component from its own path

Since version 1.2, every oks-ui component has its own entry point and its own stylesheet:

import { Button } from "oks-ui/button";
import "oks-ui/button.css";

import { Modal } from "oks-ui/modal";
import "oks-ui/modal.css";

import { Table } from "oks-ui/table";
import "oks-ui/table.css";

The bundler has nothing to guess about: it includes the files you imported and nothing else. Two things make this easy:

• Stylesheets include their parts. oks-ui/modal.css already contains the Backdrop's styles, and oks-ui/table.css covers its empty state and loading skeleton. You never need to know what a component is made of.

• Tokens stay global. Load oks-ui/tokens.css (and optionally oks-ui/utilities.css) once at the root of your app. Every component reads the same colour, spacing and radius variables. The path is the component name in kebab-case: oks-ui/button-group, oks-ui/page-title, oks-ui/form-field-set, oks-ui/text-editor.

Next.js and Turbopack

Each component's JavaScript also imports its own stylesheet, and most bundlers — webpack, Vite, Rollup, Rspack — follow that automatically. Next.js with Turbopack does not follow a stylesheet imported from inside a package, so write the .css import yourself. It's harmless elsewhere, so the simplest rule is to always write it. In the App Router, add "use client" to files that render oks-ui components. A small wrapper file per component keeps that boundary contained, so your pages can stay server components.

Migration checklist

1. Replace import "oks-ui/styles.css" with oks-ui/tokens.css and oks-ui/utilities.css in your root stylesheet.

2. Change each from "oks-ui" import to the component's own path, and add its .css import beside it.

3. Search for any remaining from "oks-ui" — one leftover import can pull the whole library back in.

4. Open each page and look for unstyled components. A missing .css import is the only thing that can go wrong, and it is obvious on sight. Old and new imports work side by side, so you can migrate one file at a time.

Measure it

Don't trust the theory — measure before and after:

• Your framework's build output lists the size of each route.

• A bundle analyzer shows which packages end up in each chunk.

• Lighthouse on a throttled mobile profile shows what the difference means for real users. On the oks-ui website, moving to per-component imports cut compressed CSS from 48 KB to 16 KB and JavaScript by about a fifth. Less CSS matters most on phones, because the browser can't paint the page until its stylesheets have arrived. See both import styles in the installation guide.

Originally published at oks-ui.com.

1. The shape of the data

Table takes rows as plain objects and a getRowKey function — no adapter layer, no special row type.

type Row = { id: number; name: string; email: string; role: string };

const DATA: Row[] = [
  { id: 1, name: "Ada Lovelace", email: "ada@oks-ui.com", role: "Owner" },
  { id: 2, name: "Grace Hopper", email: "grace@oks-ui.com", role: "Admin" },
  { id: 3, name: "Alan Turing", email: "alan@oks-ui.com", role: "Member" },
  // ...
];

2. Search filters the rows, not the table

Table itself has no search box — it just renders whatever rows you give it. Filtering lives in your own state, one useMemo:

const [query, setQuery] = useState("");
const [page, setPage] = useState(1);

const filtered = useMemo(
  () => DATA.filter((r) => r.name.toLowerCase().includes(query.toLowerCase())),
  [query],
);

3. Sorting, selection, and the table itself

Pass sortable: true on a column and Table handles the click-to-sort interface; omit onSortChange and it sorts client-side automatically — supply it and you get the descriptor back instead, for a server-side sort. selectionMode="multiple" plus selectedKeys and onSelectionChange gets you checkboxes and an indeterminate header state for free:

const [selected, setSelected] = useState<Set<number>>(new Set());

<Table
  aria-label="Team members"
  columns={[
    { key: "name", header: "Name", sortable: true },
    { key: "email", header: "Email" },
    { key: "role", header: "Role" },
  ]}
  rows={pageRows}
  getRowKey={(r) => r.id}
  selectionMode="multiple"
  selectedKeys={selected}
  onSelectionChange={(keys) => setSelected(keys as Set<number>)}
/>

aria-label is required, not optional. Table throws in development if you skip it — a data table with no accessible name is unusable with a screen reader, so the component won't let you forget it.

4. Pagination, wired to the same filtered list

Pagination and PaginationSummary are just told the current page, the page count and the total — they don't know or care that the underlying data came from a search filter:

const PAGE_SIZE = 4;
const pageRows = filtered.slice((page - 1) * PAGE_SIZE, page * PAGE_SIZE);

<PaginationSummary page={page} pageSize={PAGE_SIZE} total={filtered.length} />
<Pagination
  page={page}
  pageCount={Math.max(1, Math.ceil(filtered.length / PAGE_SIZE))}
  onChange={setPage}
/>

Loading, empty and expanded states

Three props round out the states a real table needs: isLoading swaps in skeleton rows, emptyContent replaces the body when rows is empty (it already defaults to a sensible empty state), and renderExpandedRow adds a chevron-toggle column for a details panel under any row — no layout work required for any of the three. Full prop reference at the Table component page, and this exact example — search, sort, select, paginate, wired end to end — as a live preview with the complete source at the data table pattern.

Originally published at oks-ui.com.

1. Start with the primary ramp, not just one colour

primary is the semantic role that colours your main buttons, links and focus rings. It's tempting to override just --oks-color-primary-500 and call it done, but a solid button also reads 600 for hover and 700 for pressed — override the whole ramp so those states stay coherent instead of falling back to the default orange.

:root {
  --oks-color-primary-50:  #eef2ff;
  --oks-color-primary-100: #e0e7ff;
  --oks-color-primary-500: #4f46e5;  /* your brand */
  --oks-color-primary-600: #4338ca;  /* hover */
  --oks-color-primary-700: #3730a3;  /* active / pressed */
}

Check contrast before you ship it. A solid Button or Chip puts white label text on 500 and deeper by default. Before you lock in a brand colour, check that white clears 4.5:1 against it — a vivid, light colour like a saturated yellow or orange usually won't, and needs a slightly deeper 500 to stay accessible.

2. Match your shape language

Radius is one scale, reused everywhere — cards, buttons, inputs, modals. Nudge the two or three sizes you actually see and the whole interface shifts from sharp to soft in one edit.

:root {
  --oks-radius-sm: 0.125rem;  /* chips, small controls */
  --oks-radius-md: 0.5rem;    /* the one most components default to */
  --oks-radius-lg: 0.875rem;  /* cards, modals */
}

3. Dial in density

The space scale drives padding and gaps across the library. If your product wants to feel airier or more compact than the default, nudge --oks-space-4 — it's the workhorse most components reach for.

:root { --oks-space-4: 14px; }  /* default is 16px */

4. Point neutral surfaces at your own grey

If your brand's grey isn't oks-ui's default, alias the neutral role instead of overriding a dozen individual tokens — form-field borders and muted text all read from it.

:root {
  --oks-color-neutral-100: var(--oks-palette-stone-100);
  --oks-color-neutral-500: var(--oks-palette-stone-500);
}

5. Do it again for dark mode

Dark mode is a data-theme="dark" attribute on <html>, not a second theme system — repeat the same overrides under that selector. The one thing to remember is that two tokens, --oks-color-surface and the form-field background, have light-only defaults, so your app has to supply the dark values itself:

:root[data-theme="dark"] {
  --oks-color-primary-500: #6366f1;  /* usually a touch lighter than light mode */
  --oks-color-surface: #0a0a0a;
  --oks-form-field-bg: #171717;
}

That's the whole system — no provider, no rebuild, no JavaScript theme object. See the full token reference at Theming and dark-mode specifics at Dark mode.

Originally published at oks-ui.com.