BL UI is an iOS-flavored React component library built on UI SDK and Tailwind CSS v4, in an Nx + pnpm monorepo. This repository holds the library, @brett_lamy/ui (with docstream, the GitBook-flavored Markdown renderer, and its editor inside it), the shadcn registry and its blocks, a Storybook catalog, and the BL site: a landing page, a page per library, the kit's docs, docstream's docs and the roadmap for splitting @brett_lamy/ui into packages.
Two ways, from the same source files. Installation has every step for Vite and Next.js.
shadcn registry (recommended). The copied source imports UI SDK as @ui-sdk/core and @ui-sdk/react, which are our fork under upstream's names. Add the two aliases, then the base item (bl-ui), then any part or block:
npm install @ui-sdk/core@npm:@brett_lamy/ui-sdk-core@0.1.0-beta.2.bl.1 @ui-sdk/react@npm:@brett_lamy/ui-sdk-react@0.1.0-beta.2.bl.1
npx shadcn@latest add https://blamy.github.io/ui/r/bl-ui.json
npx shadcn@latest add https://blamy.github.io/ui/r/navigation-stack.jsonEach item copies one component and only what it imports into components/ui/ and lib/; blocks (whole apps) land in components/blocks/<name>/. See How the registry works.
npm. The whole library as one dependency: ESM with one module per source module and an entry per module, so bundlers tree-shake it. It depends on the same two aliases; list them yourself too, so your own @ui-sdk/react imports share the kit's copy:
npm install @brett_lamy/ui @ui-sdk/core@npm:@brett_lamy/ui-sdk-core@0.1.0-beta.2.bl.1 @ui-sdk/react@npm:@brett_lamy/ui-sdk-react@0.1.0-beta.2.bl.1No JavaScript module of the package imports CSS (so every entry loads in plain Node): import the stylesheets once, at your app's entry.
import '@brett_lamy/ui/styles.css' // always: the kit, with the Markdown editor's sheet in a layer
import '@brett_lamy/ui/theme.css' // optional: the iOS palette
import '@brett_lamy/ui/docstream/styles.css' // only if you render Markdown (below)@brett_lamy/ui/docstream/styles.css is docstream's sheet. MarkdownView, MarkdownEditor, Composer, Conversation, ReplayPreview, TuiPreview, StlViewer, StrudelPlayer and docstream's own components (@brett_lamy/ui/docstream/…, DocsSite included) need it, after the kit's sheet; nothing else does. The editor's sheet (@brett_lamy/ui/docstream-editor/styles.css) is already inside @brett_lamy/ui/styles.css: import it yourself only in an app that doesn't load the kit's sheet, never both. With the registry, an item that needs a sheet adds the @import to your CSS.
Import each part from its module's entry, the registry's path under the package name (@/components/ui/navigation-stack is @brett_lamy/ui/navigation-stack):
import { Button } from '@brett_lamy/ui/button'
import { BLProvider } from '@brett_lamy/ui/lib/theme'
import { NavigationStack, NavigationStackBar, NavigationStackContent, NavigationStackPage, NavigationStackTitle } from '@brett_lamy/ui/navigation-stack'
export function App() {
return (
<BLProvider>
<NavigationStack>
<NavigationStackPage value="home">
<NavigationStackBar><NavigationStackTitle>Home</NavigationStackTitle></NavigationStackBar>
<NavigationStackContent>
<Button onClick={() => alert('Hello')}>Say hello</Button>
</NavigationStackContent>
</NavigationStackPage>
</NavigationStack>
</BLProvider>
)
}The components, their parts and the kit's hooks are also on the package root (import { Button } from '@brett_lamy/ui'); engines and models (lib/cron, lib/diagram-model…) are only on their own entries. React 19 is required. Coming from 5.x, or from @brett_lamy/docstream / @brett_lamy/docstream-editor (frozen at 2.0.1, now @brett_lamy/ui/docstream…): Migrating to 6.0.
packages/ui— the library,@brett_lamy/ui: shadcn-style parts on UI SDK, the iOS containers, icons, motion, theme, the Composer, PencilKit and the Diagram family (src/components,src/lib; files import each other as@/components/ui/<x>and@/lib/<x>, the paths a registry install uses), docstream and its editor (src/docstream,src/docstream-editor, published as@brett_lamy/ui/docstream/<entry>and@brett_lamy/ui/docstream-editor/<entry>), and the Cloudflare entry (src/cloudflare.ts,@brett_lamy/ui/cloudflare). Stories and tests live next to their sources.packages/ui-sdk-core,packages/ui-sdk-react—@brett_lamy/ui-sdk-coreand@brett_lamy/ui-sdk-react, generated from our UI SDK fork invendor/ui-sdk(a submodule of BLamy/ui-sdk).registry— the blocks (registry/blocks/<slug>:t3-clone,discord-clone,cloudflare-studio, …) and the manifests that document the library's items (registry/components/*.json).registry.jsonat the root is generated. See registry/README.md.apps/docs— the BL site: the landing, library and roadmap pages (src/site/, with the split plan insrc/site/libraries.ts, whichlibraries.test.tschecks against the real imports), the roadmap (roadmap/*.md), and the kit's docs (pages/*.mdordered bypages/nav.json, live examples inexamples/<page>/<example>).apps/docstream-playground,apps/docstream-editor-playground— docstream's and the editor's own docs and examples (docs/), which the site mounts at #/docstream and #/docstream-editor.apps/catalog— the Storybook catalog (stories frompackages/ui, the blocks andapps/catalog/stories).tools— workspace scripts:registry(the registry and the package'sexports),tokens(token generator and lint),docs(install sections, variant tables, Markdown export, copy-page check),cloudflare(the Cloudflare catalog and the package check),e2e(Playwright behavior and accessibility tests),vr(visual regression),ui-sdk(builds the wrappers from the fork),release,codemod, and helpers for some blocks (the desktop wrappers, the FFmpeg and Tailscale builds).docs— design notes (the 2.0 plan).
pnpm install # also builds the two UI SDK packages from vendor/ui-sdk when it changed
pnpm dev:docs # the BL site on :4206
pnpm storybook # component catalog on :6006
pnpm nx run-many -t lint,typecheck,build,test
pnpm registry # rewrite registry.json and the package's exports
pnpm tokens # regenerate lib/tokens.generated.ts from tokens.css, then lint for literals
pnpm variants # regenerate the cva variant tables in the docs
pnpm e2e # Playwright behavior tests (they start their own docs server)
pnpm a11y # axe audit against the baseline
pnpm vr # visual regression (needs Storybook on :6006 and docs on :4417)
pnpm knip # dead-code checkCONVENTIONS.md has the rules every module follows and the full list of checks CI runs. Every push to main builds apps/docs and deploys it, with the registry under /r, to GitHub Pages, and publishes any package version npm doesn't have yet (ui-sdk-core, ui-sdk-react, then ui).