robocn

Robot components for shadcn/ui. A shadcn registry of machines that solve their own kinematics in the browser: articulated arms in SVG and WebGL, production-line cells, mobile robots, robotic animals, and sensor displays. Articulated arms solve their poses from real kinematics; rovers, drones, and lidar displays accept controlled poses or sensor data. Components are procedural SVG or WebGL, not sprite sheets.

robocn.dev · Components · Workbench · Install · About · MIT licensed

Components install as source into your project, the way shadcn/ui components do. Own them, edit them, theme them with CSS variables.

bunx --bun shadcn@latest add https://robocn.dev/r/robot-arm.json

bun is the default the site offers; the install block on every page has pnpm, npm and yarn beside it. --bun runs shadcn in Bun's own runtime rather than deferring to the node shebang, so the line works on a machine that has Bun and no Node — see the install line. The repository's own toolchain is still pnpm.

What the project is and what it actually solves, in one page: robocn.dev/about, and why it says that.

Or without the CLI: every docs page offers Choose a folder, which asks for a directory, resolves the item's dependencies, shows you exactly which paths it would write — marked new or replace — and writes them once you say so. It reads your components.json and tsconfig.json for your aliases, so the files land where your project keeps them. Chrome, Edge and Opera on a desktop; see holding a folder.

What is in it

Every item below is on the landing page, running, at the size it installs at.

Item	What it is
utility-droid	Cylindrical service droid with three series, rotating sensor dome, chassis layouts, and deployable tools.
orb-droid	Rolling spherical companion with an independently stabilized head and pointer-tracking optic.
bellows-droid	Soft-shell pneumatic pod: a pleated dome that inflates and settles on a volume-conserving profile, carrying its lens pods and vent with it. Grab the crown.
robot-avocado	Split-shell specimen pod: one body of revolution halved on its own centre plane, the two halves tilting apart on a rod under the machine while the stone rides up out of the gap on a screw column. Shut, it reassembles exactly.
robot-strawberry	Berry-shelled field unit whose sensor studs are placed by the golden angle over equal areas of its own skin and run out along their own surface normals, under a calyx of rigid blades on one hinge.
robot-tomato	Truss-hung crop unit: a clamp, a peduncle with two hinges sharing one swing angle, a lobed shell, and a ripening front that is real coverage of the surface rather than a colour ramp. The only machine here that hangs.
robot-sunflower	Heliotropic collector mast: a golden-angle floret lattice on a dished head, aimed at the light by a solved two-axis tracker, on a stem that leans toward it while the gimbal collar takes up exactly what the stem did not. The spiral arms are found in the lattice, not placed in it.
robot-cactus	Potted columnar collector. The ribbed column and both arms are one continuum solver at different settings — a centreline integrated from its own curvature, exactly as long bent as it was straight, so sweep === emergence ends a limb vertical whatever the elbow. Areoles and spine fans sit on the solved crests, and a rigid corolla opens at the crown.
protocol-droid	Humanoid translator with controlled postures, gestures, head angle, and optional exposed wiring.
security-droid	Tall angular guard frame with patrol poses, pointer-tracking sensor bar, and alert state.
medical-droid	Clinical assistant with diagnostic readout and independently selected instrument arms.
infantry-droid	Light or heavy field frame with controlled poses and utility equipment modules.

Installing a component pulls in what it needs: robot-arm brings robot-kinematics, robot-style and both hooks, and the theme variables ride along with robot-style.

Usage

import { RobotArm } from "@/components/ui/robot-arm"

export function Hero() {
  return (
    <RobotArm
      links={[1, 0.82, 0.34]}
      tool="welder"
      behavior="pointer"
      size="lg"
      showEnvelope
    />
  )
}

The SVG machines share colour, size, and paint variants. Motion and mechanical controls depend on the component; each docs page lists its supported props.

Colour. Four roles — shell, metal, dark, accent — each resolving from a prop, then a CSS variable, then a built-in default.

<RobotArm color="oklch(0.58 0.2 292)" accent="#f5d90a" />

:root {
  --robot-shell: oklch(0.72 0.17 47);
  --robot-accent: oklch(0.72 0.15 176);
}

Size. size takes a scale step (xs–xl) or a pixel number. Geometry lives in a fixed viewBox, so size only ever scales the drawing. Arms also support thickness to scale limb weight separately.

Form. variant is solid, outline, blueprint or wire. Blueprint adds the grid, the dimensions or the joint angles where applicable. On articulated arms, tool picks the end effector and mount bolts the machine to the floor, ceiling or wall.

Motion. Every machine moves on its own. Leave the value prop out — extension, angle, phase, heading — and it runs behavior: a cylinder works its duty cycle, a servo sweeps or steps, a table indexes, a rover patrols, a drone hovers, a lidar ray sweeps, the duck walks. Supply the value and the loop stops: controlled always wins, which is how every one of these components already worked. speed scales the cycle, phase offsets it, paused freezes it, and animate={false} or a reduced-motion preference parks it. Arms keep their own vocabulary — behavior is pointer, orbit, sweep, idle or static, or drive them with a target, a function of elapsed seconds, or an angles array. A settled pose costs no renders.

Interaction. interactive turns a machine into a control: drag the actuator's rod, the servo horn, the gripper's jaws, the conveyor belt, the rotary platter, or an arm's tool tip; arrow-key any of them; click a fixture to index it; press to send the rover a bearing or fly the drone. While you hold it, the machine tracks the pointer exactly; let go and it eases back into whatever its behaviour has moved on to, rate-limited the way a servo returns. Every draggable is also a role="slider" with the value on it, and every gesture starts with a press, so touch devices get the same control a mouse does.

The details, per machine, are in docs/motion-and-interaction.md.

Examples

Every component page on the site is a bench: the machine on the left, every prop it takes wired to a control on the right, and the install line for it above.

A dedicated example app: cube.robocn.dev. One shared Rubik's cube, owned by everybody — each person gets a single move per day, the cube's state is recomputed server-side from its full move log, and every solved cube is archived on a leaderboard. It lives in apps/cube in this repo, built from the rubiks-cube registry item exactly as a consumer would install it (see apps/cube/SPEC.md).

A machine that runs itself. Leave the value prop out and it works its own cycle.

import { RobotRover } from "@/components/ui/robot-rover"

<RobotRover wheels={6} behavior="patrol" label="ROVER / 06" />

The same machine, controlled. Supply the value and the loop stops — controlled always wins.

import { LinearActuator } from "@/components/ui/linear-actuator"

<LinearActuator extension={0.62} cutaway />

A machine as a control. interactive makes it draggable and arrow-keyable, with a role="slider" on the handle; let go and it eases back into its behaviour.

import { RobotGripper } from "@/components/ui/robot-gripper"

const [opening, setOpening] = React.useState(0.4)

<RobotGripper interactive opening={opening} onOpeningChange={setOpening} fingers="parallel" />

Drive an arm from joint angles. arm-controls is a teach pendant — one slider per joint, forward kinematics, no solver in the path.

import { ArmControls } from "@/components/ui/arm-controls"

const [angles, setAngles] = React.useState([-30, 45, 20])

<ArmControls angles={angles} onAnglesChange={setAngles} tool="welder" />

Save a machine as a picture. Wrap anything in robot-export and it can be recorded out of the page — animated WebP, animated GIF, or a still. The encoding happens in the browser and nothing is uploaded.

import { RobotExport } from "@/components/ui/robot-export"

<RobotExport name="robot-arm">
  <RobotArm behavior="sweep" />
</RobotExport>

Every number in the menu is typed rather than picked — seconds, frame rate, frame count, scale, quality, loop count, ground colour and file name — and the ranges are a prop:

<RobotExport
  name="robot-arm"
  defaults={{ format: "gif", seconds: 7.5, fps: 24, scale: 1.5 }}
  limits={{ fps: [1, 120], frames: 2000 }}
>
  <RobotArm behavior="sweep" />
</RobotExport>

Or call it directly, with no button in the way:

import { exportNode } from "@/lib/robocn/capture"

await exportNode(stageRef.current, { format: "gif", name: "robot-arm", duration: 2, fps: 15 })

The same arm in three dimensions. robot-arm-3d is the same chain as a procedural react-three-fiber rig; robot-stage is the canvas, lights, contact shadow and orbit controls it needs.

import { RobotArm3D } from "@/components/ui/robot-arm-3d"
import { RobotStage } from "@/components/ui/robot-stage"

<RobotStage className="h-80 w-full" floor="grid">
  <RobotArm3D interactive links={[1, 0.82, 0.34]} tool="gripper" behavior="orbit" />
</RobotStage>

An animal. The walkers take the same vocabulary — a view, a size, a variant, and either a behaviour or the pose numbers themselves.

import { RobotCat } from "@/components/ui/robot-cat"

<RobotCat view="profile" size={360} behavior="prowl" label="FELIS / 13" />

A sensor display. lidar-scan takes real angle–distance samples and draws the polar plot; the sweeping ray is the behaviour on top of it.

import { LidarScan } from "@/components/ui/lidar-scan"

<LidarScan samples={samples} maxRange={12} showRays behavior="sweep" />

The kinematics

• Two links solve analytically with the law of cosines, with a chosen elbow side.
• Three or more run FABRIK, seeded with the previous frame so animation stays coherent instead of snapping between valid solutions.
• Out-of-reach targets clamp onto the reachable annulus rather than failing.
• The delta and the Stewart platform have their own closed-form solvers; the gantry is direct.
• Everything is plain functions over {x, y} and {x, y, z} objects, shared by the SVG components and the three.js rig.

import { solveChain2, chainAngles2 } from "@/lib/robocn/kinematics"

const joints = solveChain2({ x: 0, y: 0 }, { x: 40, y: 25 }, [30, 24, 16])
const angles = chainAngles2(joints)

Namespaced install

{
  "registries": {
    "@robocn": "https://robocn.dev/r/{name}.json"
  }
}

bunx --bun shadcn@latest add @robocn/robot-arm @robocn/delta-arm

Development

pnpm install
pnpm dev              # docs site and registry, on http://localhost:3000
pnpm generate         # workbench control manifest + the registry→component gallery map
pnpm registry:build   # writes public/r/*.json
pnpm og               # recaptures every social card — a quarter of an hour
pnpm og --only <name> # just that page's card: ~5 s, what a new machine ships with
pnpm shots            # recaptures docs/screenshots/*.png, the pictures above
pnpm icons            # recaptures the app icons: icon.svg, apple-icon.png, favicon.ico
pnpm test             # kinematics, components, registry integrity
pnpm typecheck
pnpm build            # builds the registry, then the site

The app is both the docs site and the registry source: every file listed in registry.json lives at the path a consumer installs it to, so what the site renders is exactly what ships. registry.json refers to its own items by URL — the only way one registry item can depend on another outside shadcn's own registry — so the host is stamped in at build time from NEXT_PUBLIC_REGISTRY_URL (or Vercel's production URL).

variable	what it does
NEXT_PUBLIC_REGISTRY_URL	the host stamped into public/r/*.json and the install lines
NEXT_PUBLIC_UMAMI_WEBSITE_ID	turns analytics on; unset, no third-party script is served at all
NEXT_PUBLIC_UMAMI_URL	the tracker script's full URL, for a self-hosted Umami; defaults to Umami Cloud

The social card at public/og.png is a screenshot of /og, which is a real page built from real components — see the social card for why, and run pnpm og after changing what it shows. Every docs page has a card of its own under public/og/ drawn the same way, so a link to /docs/micro-duck previews as the duck rather than as the catalogue: a social card per page, and pnpm og --only micro-duck for one card — seconds against a dev server that is already up, which is why taking a new machine's card is a step in building it rather than a maintenance sweep. The pictures in this README are captures of the real pages for the same reason: pnpm shots, and the screenshots for the shot list. The app icons are the same trick at a smaller size: pnpm icons lifts the mark out of /og with its computed colours baked on — because <Logo /> solves its chain at runtime and a favicon cannot — and writes icon.svg, the 180 px apple-icon.png and a favicon.ico packed at 16, 32 and 48 by scripts/lib/ico.mjs, so the tab shows the same arm the app bar does. All of it drives headless Chrome through scripts/lib/capture.mjs.

Reading the site as Markdown

Every documentation page has a Markdown mirror, for the coding agents that are a large part of who installs from here:

curl https://robocn.dev/llms.txt                 # the whole catalogue as one file
curl https://robocn.dev/docs/robot-arm.md        # one page: install line, props, source
curl -H 'Accept: text/markdown' https://robocn.dev/docs/robot-arm   # the same thing

The mirrors are generated from the same DocEntry the HTML page renders, so the two cannot drift, and src/proxy.ts is what routes .md onto them. Each docs page also carries a Copy page action that puts its Markdown on the clipboard or hands the URL to an assistant. What this is and where it came from: what pdfcn does that robocn did not.

The project describes itself in three places. package.json carries the description, keywords, homepage and repository; src/lib/site.ts carries the name, tagline, description and keywords the <meta> tags are built from in src/app/layout.tsx, and productionUrl — the host printed on the social card and in the screenshots, whichever server actually rendered them. The third is GitHub's own repo metadata, which is settings rather than source:

gh repo edit --description "…" --homepage https://robocn.dev --add-topic shadcn-registry

A test keeps the first two from drifting apart. The repo's social preview image is public/og.png, uploaded by hand under Settings → General → Social preview — GitHub has no API for it.

The header mark is a machine too: a three-link arm in a work cell, solved by the same core the registry ships, painted in the same orange, aiming at the cursor anywhere on the page — the logo, and the header lockup for the type and spacing around it.

Adding a component means: write it under src/components/ui and add an entry to registry.json. That is the whole requirement — the item is then on the landing page, in the docs index, on its own docs page with a working demo, and in the sitemap, because all four are built from the registry and fall back to the component's own default pose when nobody has written a card or a bench for it. Write the docs.ts entry, the card art and the demo when you want better than the default.

Three things are enforced. The registry test fails if a component imports a robocn file its registry entry does not depend on — the failure mode that would otherwise ship a broken install. The catalogue test fails if an item does not reach the landing grid, because the page shows every item in the registry rather than a curated subset. And the motion test drives real animation frames at every card and fails the ones that draw the same picture three seconds later, because a pinned value prop is indistinguishable from configuration in the source. See gallery coverage.

Two commands do the mechanical half of all of it. pnpm robot:new <name> writes a machine that already renders and already keeps the whole customisation contract — palette, size, the four variants, the four camera angles, a controlled prop, a behaviour union, drag and arrow keys, data-* hooks, aria, px() and finite clamping — together with its tests, its registry.json item, its fixture in the view snapshots, its docs page, its demo bench, its landing card and its row in the table above. --solver <name> adds a pure solver module and its tests beside it, and --minimal stops at the installable minimum. What is left to write is the mechanism.

pnpm robot:check <name> is the focused loop afterwards, about ten seconds: the machine's own tests plus the registry and catalogue ones, typecheck, lint, registry:build, and a report of which site wiring is written and which is falling back. --full adds the whole suite and next build.

The whole path is written up as four agent skills in skills/ — build, refine, fork and publish — which work in Claude Code, Codex, Cursor and the rest:

bunx skills add TimMikeladze/robocn

pnpm install mirrors them into .claude/skills/ and .agents/skills/ for this repo's own agents. Notes: the robot-building skills.

The workbench

/workbench is a Storybook for robots, run from this repository's own source. No stories, no argTypes: a build step reads each component's props interface and turns every prop into a knob — string-literal unions become pickers, numbers become sliders ranged from the prop's own name and doc, palette props become colour wells — with the component's own destructuring defaults as the starting pose.

Matrix mode draws one machine across the cross product of two props: every variant against every camera view, every gait against every tool. The stage has backgrounds, zoom, an outline overlay and a callback log. The pose lives in the query string, so /workbench?c=robot-arm&p.variant=blueprint&p.view=iso is a drawing you can bookmark.

There is no agent in it. The loop is HMR plus the agent you already have:

git clone https://github.com/TimMikeladze/robocn.git
cd robocn
pnpm install
pnpm dev          # http://localhost:3000/workbench

Then open claude, codex or opencode in the same directory. That is the whole integration — no key, no bridge, nothing sent anywhere. Pose a machine, copy the brief from the Handoff panel (file path, export, the pose as JSX), paste it into the agent with what you want changed, and Fast Refresh lands the edit on the stage without a reload and without losing the pose. The page carries these instructions itself: a setup panel opens on a first visit and comes back from the toolbar or ?.

Building a new robot works the same way. New writes the brief — file path, export name, item name, the nearest existing machine to follow — and points your agent at the build-robot skill in the repo. The workbench picks the component up the moment the file exists, registry entry or not: it appears as a draft at the top of the index, with knobs already derived from whatever props it declares, so you can pose it while the agent is still writing the docs, the demo and the tests.

It can also hold the folder. Folder in the toolbar hands the page your checkout: the Source tab becomes an editor over the real file with ⌘S to save, New writes the skeleton itself rather than only a brief, a recording can land in docs/screenshots, and a machine that is on disk but not in the manifest is noticed and rescanned by itself. What is on the stage is still a module Fast Refresh swapped, so this adds to the local loop rather than replacing it.

See the workbench for the architecture and what it replaced, and holding a folder for what a directory handle buys.

Credits

The kinematics and the rig vocabulary grew out of the fabricator in keycaps — a swarm of autonomous arms that bid for work — generalised here from one bespoke three.js scene into installable components.

License

MIT © 2026 Tim Mikeladze. See LICENSE.