orn-ui-docs

Static documentation site for orn-ui, built with Astro. Every component page is code + a demo clip recorded from the real app — there is no React Native runtime in the browser here, and no react-native-web. See "Why static, not live" below.

Contributing: CONTRIBUTING.md. Recording the demo clips: MEDIA.md.

Setup

This repo is separate from the orn-ui monorepo on purpose (independent release cycle, independent deploy) and depends on the published package:

"orn-ui": "^0.2.8"

Everything the docs need is read out of node_modules/orn-ui: the props tables come from src/ (the package ships its sources in files, not just the compiled lib/) and the install sizes from registry/. Nothing here needs the library checked out — a plain pnpm install is enough, which is also what CI does.

The one exception is recording demo clips: those drive the library's example app on a simulator, so they do need the sibling repo. See MEDIA.md.

pnpm install
pnpm run dev     # extract + astro dev
pnpm run build   # typecheck demos + extract + astro build

How a component page is built

Nothing on a component page is hand-written prose the code can drift from:

• Props table — generated by react-docgen-typescript reading the real .tsx source in node_modules/orn-ui/src. Change a prop in the library, rerun the extractor, the table updates.
• Code snippet — extracted from demos/<Component>.demo.tsx, between // #region demo / // #endregion demo markers. These demo files import from orn-ui and are typechecked in CI (pnpm run typecheck:demos) — a snippet that doesn't compile never ships.
• Demo clip — an .mp4 recorded from the sibling repo's apps/example (the actual native app, not this site) by running that component's Maestro flow, so the choreography is versioned code rather than a screen recording someone made by hand. A component without a clip falls back to its poster frame. See MEDIA.md.

Why static, not live

An earlier version of this plan rendered actual orn-ui components in the browser via react-native-web. That's why the library is zero-dependency — it would have worked. It was dropped in favor of code + clip: simpler mental model, no RNW compatibility gaps to work around (PanResponder + mouse, Modal behavior), and no framework runtime in the browser — the only client JS is a handful of inline vanilla scripts (copy buttons, search, theme toggle, starting the demo clip). The zero-dependency constraint on orn-ui itself stays regardless — it's what makes the library installable in one command, independent of this site's rendering choice.

Structure

orn-ui-docs/
├── demos/                  # one *.demo.tsx per component, source of truth for snippets
├── scripts/
│   ├── extract-docs.mjs    # props + snippets + tokens → src/data/*.json
│   ├── record-demo.sh      # runs a component's Maestro flow → mp4 + poster
│   └── record-all-demos.sh # the same, for every component
├── src/
│   ├── layouts/BaseLayout.astro
│   ├── pages/
│   │   ├── index.astro           # landing + component grid
│   │   ├── tokens.astro          # spacing/radius/fontSize/duration scales
│   │   └── components/[slug].astro
│   └── data/                # generated, gitignored — see scripts/extract-docs.mjs
└── public/media/*.mp4      # + *.jpg posters, see MEDIA.md