Skip to main content

Guides

Agent quickstart

A new Vite and React app with Ouro UI, step by step with the files whole: a settings page with a form the browser validates, a select, a switch, a dark mode toggle that sets the scheme before the first paint, and a confirmation before a destructive action. Run the steps in order and copy the files as they are; a test installs what step 3 adds and type-checks these files against it.quickstart Then change the page to what you are building. For a Next.js app, see Installing.

1. Create the app

npm create vite@latest my-app -- --template react-ts
cd my-app
npm install -D tailwindcss @tailwindcss/vite @types/node

To build in the current folder, write . for my-app and leave out cd my-app.

2. Write the setup files

Replace these four files whole.

src/index.css:

@import "tailwindcss";

vite.config.ts, with Tailwind's plugin, the @ alias, and the script that sets light or dark before the first paint (.ts on its import: tsconfig.node.json resolves imports as Node does):

import tailwindcss from "@tailwindcss/vite";
import react from "@vitejs/plugin-react";
import { fileURLToPath } from "node:url";
import { defineConfig } from "vite";
import { colorSchemeScript } from "./src/lib/ouro/color-scheme-script.ts";

const colorScheme = {
  name: "color-scheme",
  transformIndexHtml: () => [{ tag: "script", children: colorSchemeScript(), injectTo: "head-prepend" as const }],
};

export default defineConfig({
  plugins: [react(), tailwindcss(), colorScheme],
  resolve: { alias: { "@": fileURLToPath(new URL("./src", import.meta.url)) } },
});

tsconfig.json:

{
  "files": [],
  "references": [{ "path": "./tsconfig.app.json" }, { "path": "./tsconfig.node.json" }],
  "compilerOptions": { "paths": { "@/*": ["./src/*"] } }
}

tsconfig.app.json, the template's with the alias:

{
  "compilerOptions": {
    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
    "target": "es2023",
    "lib": ["ES2023", "DOM"],
    "module": "esnext",
    "types": ["vite/client"],
    "allowArbitraryExtensions": true,
    "skipLibCheck": true,
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "verbatimModuleSyntax": true,
    "moduleDetection": "force",
    "noEmit": true,
    "jsx": "react-jsx",
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "erasableSyntaxOnly": true,
    "noFallthroughCasesInSwitch": true,
    "paths": { "@/*": ["./src/*"] }
  },
  "include": ["src"]
}

3. Install Ouro UI

This sets up shadcn/ui, registers the @ouro namespace, which serves the newest release,namespace then adds the Ouro theme, and the base tokens, once, with the components the page uses:

npx shadcn@latest init --base base --preset nova --yes --no-monorepo
node -e "const fs=require('fs');const c=JSON.parse(fs.readFileSync('components.json','utf8'));c.registries={'@ouro':'https://ui.ouroboros.bot/r/{name}.json'};fs.writeFileSync('components.json',JSON.stringify(c,null,2))"
npx shadcn@latest add @ouro/ouro-theme --yes
npx shadcn@latest add @ouro/ouro-base @ouro/page-header @ouro/stack @ouro/form @ouro/text-field @ouro/select @ouro/switch @ouro/button @ouro/confirm-dialog @ouro/color-scheme-toggle @ouro/ouro-check --yes
npm pkg set "imports.#ouro-ax/*=./src/lib/ouro/ax/*"

Use these @ouro commands: the GitHub addresses install the same release but fetch each file from GitHub, which is much slower. Add other components the same way, @ouro/<item>; llms.txt lists them all.

4. Write the app

src/main.tsx wraps the app in ColorSchemeProvider, which applies the scheme the toggle picks and keeps it:

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { ColorSchemeProvider } from "@/lib/ouro/color-scheme";
import App from "./App.tsx";
import "./index.css";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <ColorSchemeProvider>
      <App />
    </ColorSchemeProvider>
  </StrictMode>,
);

Building a settings page, a dashboard or a list beside its detail? Install its page pattern instead of writing App.tsx: npx shadcn@latest add @ouro/settings-page --yes (or @ouro/dashboard-page, @ouro/list-detail-page), then make src/App.tsx render <SettingsPage /> from @/components/patterns/settings-page, and go on to step 5.

Otherwise, src/App.tsx is the whole page, laid out by Ouro's Stack and PageHeader rather than CSS of its own: start from it and change its fields to what you are building, rather than writing the page from scratch. A component's props are on its page, https://ui.ouroboros.bot/docs/<item>.md, and in the JSDoc of the installed source, src/components/ouro/<item>/<item>.tsx.

import { useState } from "react";
import { Button } from "@/components/ouro/button/button";
import { ColorSchemeToggle } from "@/components/ouro/color-scheme-toggle/color-scheme-toggle";
import { ConfirmDialog } from "@/components/ouro/dialog/confirm-dialog";
import { Form } from "@/components/ouro/form/form";
import { PageHeader } from "@/components/ouro/page-header/page-header";
import { Select } from "@/components/ouro/select/select";
import { Stack } from "@/components/ouro/stack/stack";
import { Switch } from "@/components/ouro/switch/switch";
import { TextField } from "@/components/ouro/text-field/text-field";
import { formErrors, type FormErrors } from "@/lib/ouro/form-answer";

const languages = [
  { value: "en", label: "English" },
  { value: "es", label: "Español" },
  { value: "fr", label: "Français" },
];

export default function App() {
  // Each submit's own answer, so the same mistake shows again after an edit.
  const [answer, setAnswer] = useState<{ errors: FormErrors }>();

  return (
    <main className="mx-auto w-full max-w-xl px-4 py-10">
      <Stack gap="lg">
        <PageHeader title="Settings" description="Your profile and how we reach you." actions={<ColorSchemeToggle />} />
        <Form
          errors={formErrors(answer, answer?.errors)}
          onSubmit={(event) => {
            // The browser's own checks (required, type="email") pass before this runs.
            event.preventDefault();
            const name = String(new FormData(event.currentTarget).get("name")).trim();
            setAnswer({ errors: name.length < 2 ? { name: "Use at least 2 letters." } : {} });
          }}
        >
          <Stack gap="md">
            <TextField label="Display name" name="name" required autoComplete="nickname" />
            <TextField label="Email" name="email" type="email" required autoComplete="email" />
            <Select label="Language" name="language" defaultValue="en" options={languages} />
            <Switch label="Email notifications" name="notifications" defaultChecked />
            <div>
              <Button type="submit">Save</Button>
            </div>
          </Stack>
        </Form>
        <div>
          <ConfirmDialog
            title="Delete your account?"
            description="This deletes your profile and settings. It can't be undone."
            confirmLabel="Delete account"
            tone="destructive"
            onConfirm={() => setAnswer(undefined)}
            trigger={<Button tone="destructive" variant="soft">Delete account</Button>}
          />
        </div>
      </Stack>
    </main>
  );
}

The look comes from the theme. Ouro's components paint themselves from the theme's CSS variables,tokens so the page needs no stylesheet of its own, and a different look is a few variables at the end of src/index.css: see Mix your own paint. Keep className for layout, as App.tsx does.

Remove what only the template's page used:

rm -rf src/App.css src/assets public/icons.svg

5. Build and check

npm run build
node scripts/ouro/check/check.ts dist --sizes 390x844,1440x900

Ouro check opens the build at a phone's and a laptop's size, light and dark, and lists what to fix; leave out --sizes to check it at the full set of sizes. On its first run it downloads Chromium itself.

The app is done when the build passes and Ouro check reports 0 finding(s). A page pattern passes as installed, so a page that fails has moved off the theme: the finding names the token to use. The components come with their own tests (add @ouro/<item>-tests to run them), so tests you write cover your own logic.

Next

  • One component's whole API, with examples: https://ui.ouroboros.bot/docs/<item>.md, such as Form and ConfirmDialog.
  • Errors from a server, a router's action and the order of checks: Forms.
  • A list, navigation, a table or a toast: llms.txt's Common needs.

Claim sources