Skip to content

UI and beUI ​

The UI package (@shootgrow/ui) is beUI: copy-the-source React components built on Motion and Tailwind CSS. We own the source; there is no runtime dependency on beUI. shadcn/ui and Radix are not used (ADR 0002).

Add a beUI component ​

bash
bun run ui:add dropdown-menu        # slug from https://beui.dev/r
bun run ui:status                   # local edits and upstream updates
bun run ui:update dropdown-menu     # re-fetch; refuses to overwrite local edits
bun run ui:update dropdown-menu --force

scripts/beui.ts fetches the component and every shared file it needs from the beUI registry, writes them into packages/ui/src (same layout as beUI: components/motion/*, lib/*), rewrites @/lib/... imports to relative paths so no alias is needed, and records everything in packages/ui/beui.lock.json:

  • which components are installed and the registry updated_at they came from;
  • a hash of each file as written, so ui:status can tell a local edit from an untouched file.

If a command prints "Install missing dependencies", run the bun add it shows inside packages/ui.

Import in app code:

tsx
import { Button } from "@shootgrow/ui/components/motion/button";
import { Tabs, TabsList, TabsTrigger } from "@shootgrow/ui/components/motion/tabs";

Editing a vendored component ​

Allowed, but it makes the file "locally edited" and ui:update will skip it. Prefer wrapping a component in apps/web/src/components or passing className/classNames. If you must edit, keep the change small and note why at the top of the file.

Components installed now ​

button, input, select, combobox, multi-select, checkbox, radio, switch, tabs, card, table, drawer, bottom-sheet, morphing-modal, popover, tooltip, animated-toast-stack, animated-sidebar, timeline, date-range-picker, sortable-stack, file-tree, animated-badge, number, adaptive-stepper, alert, dropdown-menu, theme-toggle, loader, breadcrumb, collapsible, avatar-group, pagination, command-palette, otp-input, signup-form, notification-stack, availability-scheduler, swipeable-list, file-upload, feedback-widget, todo-list, approval-card, not-found, sparkline, bar-chart.

Not provided by beUI and built in-house: the calendar (step 2) and the video annotation player (step 7).

Design tokens ​

packages/ui/src/styles/globals.css is the single source for colour, radius and type. Token names follow the shadcn convention because beUI is written against it (bg-background, text-muted-foreground, border-border). Do not rename them.

  • Colours are OKLCH. The one accent is leaf green, oklch(74% .11 135), taken from the Reroot design system: it is primary as-is in dark mode and darkened (oklch(.5 .115 135)) in light mode for contrast. Only the colour was taken from that system; its sizes and component styles were not.
  • Transparency is the system. Borders, fills, hovers, cards, the sidebar and the ring are translucent washes of --foreground or --primary (color-mix(... transparent)), so they blend with whatever is behind them and follow the accent. Text colours, --background and --popover stay near-opaque to guarantee contrast.
  • Semantic states: success (leaf), warning (amber), destructive (clay), info (stone). Use as tints or small marks, not large fills. Tailwind's emerald/amber/rose classes used inside vendored beUI code are remapped to these tokens in globals.css, so vendored files stay unedited.
  • Light is the default (sales use phones outdoors); dark follows the system or the toggle (next-themes, class strategy).
  • Type is Inter Variable, self-hosted through @fontsource-variable/inter.
  • --sidebar-* tokens are a second neutral layer for navigation.

Interface rules for this product ​

This is an operating tool, not a marketing site. Familiar patterns beat novelty.

  • One accent, used for primary actions and selection.
  • Lists and rows over grids of identical cards. No nested cards.
  • Empty and error states on every list (Conventions).
  • Motion conveys state (150–250 ms). Respect prefers-reduced-motion; beUI components already do.
  • Tabular numbers for data (data-tabular attribute or a table element).

In development, /dev/ui shows the installed components in the app's tokens, and the login page has a role preview. Both are removed from production bundles.

Internal documentation. Not for clients.