From 80025a6a0daf6587ac89073b26eac04cc68b8428 Mon Sep 17 00:00:00 2001
From: Dan Ditomaso <dan.ditomaso@gmail.com>
Date: Sat, 11 Jul 2026 22:54:31 -0400
Subject: [PATCH 1/2] fix(ui,readme): make workspace build succeed on fresh
 clone (#1252)

Two bugs prevented `pnpm -r build` from working after a fresh clone:

1. `packages/ui` vite-plugin-static-copy config preserved the src path
   structure, producing `dist/theme/src/lib/theme/default.css` instead
   of `dist/theme/default.css`. publint then failed on the missing
   `exports["./theme/default.css"]` target. Add `rename: { stripBase: true }`
   to flatten the copy.

2. `packages/protobufs` build runs `buf generate`, which requires the
   Buf CLI. The README suggested `pnpm -r build` and only mentioned Buf
   as optional. Generated stubs are already committed, so update the
   README to filter out `@meshtastic/protobufs` from the workspace build
   and move Buf into its own regeneration section.
---
 README.md                  | 15 ++++++++++++---
 packages/ui/vite.config.ts |  1 +
 2 files changed, 13 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 577e7efaa..52a77e759 100644
--- a/README.md
+++ b/README.md
@@ -83,8 +83,7 @@ Expected domain errors are returned as `Result<T, E>` via [`better-result`](http
 
 ### Prerequisites
 
-You need [pnpm](https://pnpm.io/) installed. If you plan to regenerate
-protobufs, also install the [Buf CLI](https://buf.build/docs/cli/installation/).
+You need [pnpm](https://pnpm.io/) installed. The [Buf CLI](https://buf.build/docs/cli/installation/) is only required if you plan to regenerate protobuf stubs — the generated TypeScript is committed to the repo, so a fresh clone builds without it.
 
 ### Setup
 
@@ -102,8 +101,18 @@ pnpm --filter @meshtastic/web dev
 
 ### Build everything
 
+`@meshtastic/protobufs` has a `build` script that regenerates its stubs with `buf`, so skip it when building the rest of the workspace:
+
+```bash
+pnpm --filter '!@meshtastic/protobufs' -r build
+```
+
+### Regenerate protobuf stubs
+
+Only needed after bumping the `meshtastic/protobufs` submodule or editing the generator config. Requires the Buf CLI:
+
 ```bash
-pnpm -r build
+pnpm --filter @meshtastic/protobufs build
 ```
 
 ### Run tests
diff --git a/packages/ui/vite.config.ts b/packages/ui/vite.config.ts
index e7e4bcdb0..cbdf9aff6 100644
--- a/packages/ui/vite.config.ts
+++ b/packages/ui/vite.config.ts
@@ -20,6 +20,7 @@ export default defineConfig({
         {
           src: "src/lib/theme/default.css",
           dest: "theme",
+          rename: { stripBase: true },
         },
       ],
     }),

From 4cb1febea08fbf59283e65a649a8deb75a64f65a Mon Sep 17 00:00:00 2001
From: Dan Ditomaso <dan.ditomaso@gmail.com>
Date: Sat, 11 Jul 2026 22:56:46 -0400
Subject: [PATCH 2/2] docs(ui): add package README describing purpose and
 surface

---
 packages/ui/README.md | 54 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)
 create mode 100644 packages/ui/README.md

diff --git a/packages/ui/README.md b/packages/ui/README.md
new file mode 100644
index 000000000..e4e1a6d0f
--- /dev/null
+++ b/packages/ui/README.md
@@ -0,0 +1,54 @@
+# @meshtastic/ui
+
+Shared React component library used by [`@meshtastic/web`](../../apps/web). Radix Primitives + Tailwind CSS v4 with a shadcn-flavoured design system.
+
+## What's inside
+
+- **`AppSidebar`** — top-level layout sidebar used by the web client shell.
+- **`ThemeProvider` + `useTheme` + `ThemeToggle`** — light/dark/system theme, persisted to `localStorage`.
+- **`Badge`** — primitive re-exported at the package root.
+- **`theme/default.css`** — Tailwind design tokens (colors, radii, typography) shipped as a standalone stylesheet.
+- **shadcn primitives** under `src/components/ui/` (`Button`, `Input`, `Collapsible`, `DropdownMenu`, `Separator`, `Sheet`, `Skeleton`, `Tooltip`) — bundled but only re-exported through the sidebar surface today. Deep-imports work against the built `dist/`.
+
+The package is framework-agnostic within React 19: no device, transport, or SDK dependencies. It only owns look-and-feel.
+
+## Install
+
+```sh
+pnpm add @meshtastic/ui
+```
+
+Peer dependencies: `react` >=19, `react-dom` >=19, `tailwindcss` ^4.1, `@radix-ui/react-slot`, `class-variance-authority`, `tailwind-merge`.
+
+## Usage
+
+Import the theme stylesheet once at your app entry, then consume components:
+
+```tsx
+import "@meshtastic/ui/theme/default.css";
+import { AppSidebar, Badge, ThemeProvider, ThemeToggle } from "@meshtastic/ui";
+
+export function App() {
+  return (
+    <ThemeProvider defaultTheme="system">
+      <AppSidebar sections={[]} />
+      <Badge>online</Badge>
+      <ThemeToggle />
+    </ThemeProvider>
+  );
+}
+```
+
+## Development
+
+From the repo root:
+
+```sh
+pnpm --filter @meshtastic/ui dev      # vite dev server
+pnpm --filter @meshtastic/ui build    # vite build + publint
+pnpm --filter @meshtastic/ui test     # vitest
+```
+
+## License
+
+GPL-3.0-only.