@findagent/ui — the FindAgent design system

The single source of truth for shared, presentational UI. Consumed by the app (apps/web, via workspace source → instant, no publish) and — once published to public npm — by the landing and the bot. Pairs with @findagent/tokens (the shared Tailwind theme / CSS variables) so a component renders identically in every consumer.

What belongs here vs what stays in the app

IN @findagent/ui (add new shared UI here):

• Presentational + reusable primitives + building blocks: buttons, inputs, dialogs, badges, cards/shells, avatar, pagination, toast, brand marks/logos, thumbnails, generic banners (StatusBanner), skeletons, illustration cores, tokens.
• Rule of thumb: no app business logic, no Supabase / server-only / route deps, no app-specific data types. Only pure utils + other primitives.

STAYS in apps/web/components (do NOT move here):

• App-feature components with business logic / data fetching / Supabase / route behavior: install-modal, submission wizard, admin dashboards, KB/dept/account features, nav/footer/search, coming-soon pages, specialized illustrations, analytics-coupled wrappers.
• These may (and should) compose @findagent/ui primitives — but they live in the app.

Adding / changing a component (the workflow every feature follows)

1. Need a shared primitive? Check @findagent/ui first. If it exists, import it: import { Button, StatusBanner } from '@findagent/ui'.
2. If it doesn't exist and it's shared/presentational → add it here (src/ui/<name>.tsx for shadcn-style, src/<name>.tsx otherwise), export it from src/index.ts, then use it. Don't create a second copy in the app.
3. If it's app-feature-logic → build it in apps/web/components, composing @findagent/ui primitives.

The #419 boundary rule (load-bearing)

• A server-safe primitive stays directive-free; an interactive one keeps 'use client' as its FIRST line. Never remove/add the directive when moving a component.
• Never export a pure helper from a 'use client' module — a Server Component importing it gets a client-ref proxy and crashes (React #419). Pure helpers live in non-client modules (src/lib/*).

Structure

• src/index.ts — the public barrel (the ONLY entry; main/types point here).
• src/ui/* — shadcn-style primitives. src/* — logos, illustrations, cards, banners. src/lib/* — pure utils (cn, initials, avatar-host, tokens, …).
• Deps: react/react-dom/next are peerDependencies (the consumer provides them); runtime libs (clsx, tailwind-merge, class-variance-authority, lucide-react, simple-icons, @radix-ui/*) are dependencies at the app's versions.

Wiring (already done for the app)

• apps/web/next.config.mjs → transpilePackages: ['@findagent/ui', …].
• apps/web/tailwind.config.ts → content includes ../../packages/ui/src/**/*.{ts,tsx} (so classes aren't purged).
• apps/web/package.json → "@findagent/ui": "workspace:*".
• A consumer's Tailwind theme must define the same tokens (fg-strong, fg-muted, …) → that's what @findagent/tokens single-sources.

One canonical import path

The migration is complete: the re-export shims are gone and every consumer imports shared UI from @findagent/ui directly — import { Button, StatusBanner } from '@findagent/ui'. There is no @/components/<x> alias for a moved primitive anymore. Add new shared UI here and import it by the package path.

Consuming from npm (landing / bot)

Once the owner has published @findagent/ui to public npm (pnpm --filter @findagent/ui publish), external consumers (landing, bot) install it with:

# Install both the design system and the tokens peer it depends on
npm install @findagent/ui @findagent/tokens

Next.js consumers (landing)

// next.config.mjs
export default {
  transpilePackages: ['@findagent/ui'],  // optional — the dist is pre-built ESM, but
                                          // adding it avoids a potential Next.js edge-runtime quirk
}

// tailwind.config.ts — add to content so classes aren't purged
content: [
  // ... your existing globs ...
  'node_modules/@findagent/ui/dist/**/*.js',
]

/* globals.css or equivalent — import the token variables */
@import '@findagent/tokens/tokens.css';

// tailwind.config.ts — extend with the shared theme preset
import tokensPreset from '@findagent/tokens/tailwind'

export default {
  presets: [tokensPreset],
  // ... rest of your config
}

Non-Next.js consumers (bot)

Same as above — import @findagent/tokens/tokens.css for the CSS variables, extend Tailwind with the @findagent/tokens/tailwind preset, and add the dist/**/*.js content glob. The pre-built ESM dist does NOT require transpilePackages.