From a465be808ca2260628f6691bb26fcd5f4a82a6df Mon Sep 17 00:00:00 2001 From: Sawyer Cutler Date: Mon, 21 Sep 2026 20:28:10 -0700 Subject: [PATCH 1/2] docs(readme): runnable-only Quickstart, one program (CL-8775) --- README.md | 55 ++++++++++++++++++++++++++++--------------------------- 1 file changed, 28 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index c0bd2fbe..df31b17b 100644 --- a/README.md +++ b/README.md @@ -15,27 +15,7 @@ yarn add @corbits/react-ui bun add @corbits/react-ui ``` -Import the prebuilt stylesheet once at the app root (no Tailwind build required): - -```tsx -import "@corbits/react-ui/styles.css"; -``` - -That sheet includes Tailwind preflight and a base layer — it restyles the page, and neither import is safe to skip: without one of them the components render unstyled markup, not a fallback look. If you already use Tailwind v4, import `@corbits/react-ui/theme.css` instead and let your own build generate utilities; don't import both. - -Dark mode is a `dark` class on an ancestor; the stylesheet reads it and does not manage it. With neither `.dark` nor `.light` set, the theme follows the OS — a `@media (prefers-color-scheme: dark)` block applies the dark tokens to `:root` and sets `color-scheme: dark` so native controls follow, so a zero-JS install already renders dark on a dark-OS host. That media-query path is tokens only — `dark:` utilities still need a `.dark` ancestor. - -Removing `.dark` is not light: hosts that toggle by adding and removing `.dark` must now add `.light` for an explicit light choice (or mount `ThemeProvider`, which toggles both), or a dark-OS user falls back to OS dark. An explicit-light choice on a dark OS first-paints dark then swaps when JS adds `.light`; to block the flash, apply it before first paint *only when the stored choice is light* — `` — adding it unconditionally pins light for dark-OS users too. `ThemeProvider` still wins once it mounts — mount it only if you want the library to persist the choice and apply named presets. - -```tsx -import { Button } from "@corbits/react-ui/ui/button"; - - -``` - -Every component is importable by subpath (`@corbits/react-ui/ui/button`) or from the root (`@corbits/react-ui`). - -The brand faces (Red Hat Display, Space Mono) are named by the theme but not bundled. Load them yourself, or the stack falls through to system fonts; to use a face loaded under a generated name, override `--font-sans` / `--font-mono`. +Render a table and a button. The stylesheet import is part of the program — import it once at the app root (no Tailwind build required): ```tsx import "@corbits/react-ui/styles.css"; @@ -45,24 +25,39 @@ import { SortableTable } from "@corbits/react-ui/ui/sortable-table"; type Run = { id: string; name: string; status: string }; -export function Runs({ runs }: { readonly runs: readonly Run[] }) { +const RUNS: readonly Run[] = [ + { id: "run-1", name: "Nightly ingest", status: "succeeded" }, + { id: "run-2", name: "Backfill", status: "running" }, +]; + +export function Runs() { return ( <> run.id} columns={[ { key: "name", header: "Run", cell: (run) => run.name }, { key: "status", header: "Status", cell: (run) => run.status }, ]} /> - + ); } ``` +That sheet includes Tailwind preflight and a base layer — it restyles the page, and neither import is safe to skip: without one of them the components render unstyled markup, not a fallback look. If you already use Tailwind v4, import `@corbits/react-ui/theme.css` instead and let your own build generate utilities; don't import both. + +Dark mode is a `dark` class on an ancestor; the stylesheet reads it and does not manage it. With neither `.dark` nor `.light` set, the theme follows the OS — a `@media (prefers-color-scheme: dark)` block applies the dark tokens to `:root` and sets `color-scheme: dark` so native controls follow, so a zero-JS install already renders dark on a dark-OS host. That media-query path is tokens only — `dark:` utilities still need a `.dark` ancestor. + +Removing `.dark` is not light: hosts that toggle by adding and removing `.dark` must now add `.light` for an explicit light choice (or mount `ThemeProvider`, which toggles both), or a dark-OS user falls back to OS dark. An explicit-light choice on a dark OS first-paints dark then swaps when JS adds `.light`; to block the flash, apply it before first paint *only when the stored choice is light* — `` — adding it unconditionally pins light for dark-OS users too. `ThemeProvider` still wins once it mounts — mount it only if you want the library to persist the choice and apply named presets. + +Every component is importable by subpath (`@corbits/react-ui/ui/button`) or from the root (`@corbits/react-ui`). + +The brand faces (Red Hat Display, Space Mono) are named by the theme but not bundled. Load them yourself, or the stack falls through to system fonts; to use a face loaded under a generated name, override `--font-sans` / `--font-mono`. + This package ships no `"use client"` directives. In a React Server Components app, re-export stateful components from a file you mark yourself, using subpaths rather than the root barrel. ## How it works @@ -94,9 +89,15 @@ The Corbits logo has three motion variants: `silk` (default), `strata`, and `ech ```tsx import { ThinkingIndicator, ThinkingMark } from "@corbits/react-ui"; - - - +export function Thinking() { + return ( + <> + + + + + ); +} ``` `ThinkingIndicator` supplies an accessible status label; `ThinkingMark` is decorative. From 24731bc5a87a92dfa63d0e5c9c9ca19c03021722 Mon Sep 17 00:00:00 2001 From: Sawyer Cutler Date: Mon, 21 Sep 2026 21:06:02 -0700 Subject: [PATCH 2/2] docs(readme): Quickstart shows real host usage (CL-8775) --- README.md | 62 ++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 39 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index df31b17b..96fd562d 100644 --- a/README.md +++ b/README.md @@ -15,37 +15,31 @@ yarn add @corbits/react-ui bun add @corbits/react-ui ``` -Render a table and a button. The stylesheet import is part of the program — import it once at the app root (no Tailwind build required): +Until a release is cut, consumers pin a commit instead of a version range: -```tsx -import "@corbits/react-ui/styles.css"; +```json +"@corbits/react-ui": "github:corbitsdev/react-ui#" +``` -import { Button } from "@corbits/react-ui/ui/button"; -import { SortableTable } from "@corbits/react-ui/ui/sortable-table"; +Import the stylesheet once at the app root, before your own CSS (no Tailwind build required). Mount `ThemeProvider` near the root so dark mode persists per user, and `Toaster` once alongside it so any component can call `toast()`: -type Run = { id: string; name: string; status: string }; +```tsx +import "@corbits/react-ui/styles.css"; -const RUNS: readonly Run[] = [ - { id: "run-1", name: "Nightly ingest", status: "succeeded" }, - { id: "run-2", name: "Backfill", status: "running" }, -]; +import { ThemeProvider, Toaster, toast } from "@corbits/react-ui"; -export function Runs() { +export function Root() { return ( - <> - run.id} - columns={[ - { key: "name", header: "Run", cell: (run) => run.name }, - { key: "status", header: "Status", cell: (run) => run.status }, - ]} - /> - - + + + + ); } + +function App() { + return ; +} ``` That sheet includes Tailwind preflight and a base layer — it restyles the page, and neither import is safe to skip: without one of them the components render unstyled markup, not a fallback look. If you already use Tailwind v4, import `@corbits/react-ui/theme.css` instead and let your own build generate utilities; don't import both. @@ -54,6 +48,28 @@ Dark mode is a `dark` class on an ancestor; the stylesheet reads it and does not Removing `.dark` is not light: hosts that toggle by adding and removing `.dark` must now add `.light` for an explicit light choice (or mount `ThemeProvider`, which toggles both), or a dark-OS user falls back to OS dark. An explicit-light choice on a dark OS first-paints dark then swaps when JS adds `.light`; to block the flash, apply it before first paint *only when the stored choice is light* — `` — adding it unconditionally pins light for dark-OS users too. `ThemeProvider` still wins once it mounts — mount it only if you want the library to persist the choice and apply named presets. +A page body typically pairs `PageShell` (margins and scroll ownership) with `EmptyState` (title, description, an optional icon, and an action): + +```tsx +import { Button, EmptyState, PageShell } from "@corbits/react-ui"; + +export function NotFoundPage() { + return ( + + window.history.back()}> + Go back + + } + /> + + ); +} +``` + Every component is importable by subpath (`@corbits/react-ui/ui/button`) or from the root (`@corbits/react-ui`). The brand faces (Red Hat Display, Space Mono) are named by the theme but not bundled. Load them yourself, or the stack falls through to system fonts; to use a face loaded under a generated name, override `--font-sans` / `--font-mono`.