Skip to main content

Getting started

This guide covers how to work with Arco inside the Kosmos prototype monorepo.

For the OS product and hosted instances, see What is Kosmos?, Get a hosted instance, and Run locally.

Prerequisites​

  • Node.js 22+
  • npm (workspaces enabled at repo root)

Run Kosmos locally​

Follow Run locally for full setup. Short version from the Kosmos repo root:

npm install
npm run setup   # first run
npm run dev     # shell :4610 + API :4600
SurfaceURLPackage
Kosmos prototypehttp://localhost:4610Kosmos-computer/Kosmos
Kosmos marketinghttps://www.kosmos.computerKosmos-computer/www
Kosmos docshttps://docs.kosmos.computerKosmos-computer/docs

To work on these docs locally, clone Kosmos-computer/docs and run npm start.

Where Arco lives in the codebase​

src/styles/tokens.css     # --arco-* design tokens
src/styles/ui.css         # BEM classes for primitives
src/components/ui/        # React wrappers (Button, Input, …)
src/components/patterns/  # Layout patterns (MasterDetail, Section)
src/components/agent-blocks/  # Chat block renderers
src/apps/appview/         # Generated app surface (AppSurface)

Using tokens in new UI​

Always reference tokens — never hardcode colors or spacing:

.my-panel {
  background: var(--arco-bg-surface);
  color: var(--arco-text-primary);
  border: 1px solid var(--arco-border);
  border-radius: var(--arco-radius-m);
  padding: var(--arco-space-l);
}

Theme switching uses html[data-theme="dark"|"light"].

Using UI primitives​

import { Button, Input, EmptyState } from "@/components/ui";

export function Example() {
  return (
    <EmptyState title="No items" action={<Button variant="primary">Create</Button>}>
      <Input placeholder="Search…" />
    </EmptyState>
  );
}

Next steps​