@fair-md/ui

Shared UI kit for the MD platform: shadcn/Radix primitives, product-level layout components, design tokens, and cn(). Per FRONTEND_SPEC.md §6 it lives here in the mdjourney repo and is published to npm as @fair-md/ui; mdindex consumes the published package. mdjourney stays standalone-deployable using this package. An eventual umbrella repo can relocate packages/ui as-is.

The one rule

@fair-md/ui is a leaf. It imports nothing from mdjourney-webapp or any app. Apps import from @fair-md/ui, never the reverse — so mdindex can depend on it without dragging in app code or app-release coupling.

What's here

• src/lib/cn.ts — the cn() Tailwind class merger.
• src/styles/tokens.css — the shared color/radius design tokens (:root + .dark).
• tailwind-preset.cjs — shared Tailwind color/radius/animation mapping.
• src/components/*.tsx — shadcn/Radix-style primitives: alert-dialog, badge, button, card, checkbox, collapsible, command, data-table, dialog, dropdown-menu, input, label, popover, progress, radio-group, scroll-area, select, separator, sheet, skeleton, switch, table, tabs, textarea, toast, toolbar, and tooltip.
• src/product/index.tsx — app-agnostic product components: AppSidebar, PageHeader, MetricCard, ProgressSummary, Timeline, LifecycleStepper, FormSectionNav, FieldStatusIcon, and UploadDialog.
• src/index.ts — the public barrel.

Component tiers

Use three tiers so new tools feel seamless without copying app code:

1. Foundation: Button, Input, Select, Dialog, ScrollArea, Table, Badge, Tooltip, Tabs, DropdownMenu, Popover, Sheet, Checkbox, Switch, RadioGroup, Toast, and Command.
2. Product surfaces: AppShell, Header, Panel, Sidebar, EmptyState, PageHeader, Toolbar, MetricCard, DataTable, and UploadDialog.
3. Domain-adjacent affordances: StatusBadge, expressive Progress indicators, ProgressSummary, Timeline, LifecycleStepper, FormSectionNav, and FieldStatusIcon.

Keep API clients, route state, schemas, and workflow-specific logic out of this package. Those belong in each app. Visual language and reusable interaction patterns belong here.

Building

npm run build emits:

• dist/cjs — CommonJS for older toolchains.
• dist/esm — ESM for modern bundlers.
• dist/types — declarations.

The package exports the root barrel, component subpaths, ./product, ./auth, ./tokens.css, and ./tailwind-preset.

Publishing (npm)

Published publicly as @fair-md/ui under the fair-md scope. Current version: 0.3.0 (see CHANGELOG.md).

• Automated (CD): bump version in packages/ui/package.json → merge to main. ui-auto-tag.yml tags ui-vX.Y.Z and dispatches ui-release.yml, which builds + npm publishes. One-time: add the NPM_TOKEN repo secret (automation token with publish rights to @fair-md); the npm GitHub environment gates the job.
• Manual: cd packages/ui && npm install && npm publish (prepublishOnly builds; access is public).

Consuming

npm install @fair-md/ui

Then, per consumer:

1. Import tokens once before Tailwind: @import '@fair-md/ui/tokens.css';
2. Use the Tailwind preset: presets: [require('@fair-md/ui/tailwind-preset')]
3. Add package classes to Tailwind content: content: [..., './node_modules/@fair-md/ui/dist/**/*.{js,mjs}'].
4. Import from the barrel or subpaths: import { Button } from '@fair-md/ui' or import { Button } from '@fair-md/ui/button'.
5. Product-level components are available from @fair-md/ui/product.

mdjourney-webapp is wired for local package development: it depends on file:../packages/ui, its Tailwind content scans ../packages/ui/src, and the package has prepare so the built dist is refreshed when installed. For external tools, consume the published @fair-md/ui package instead of the local file: dependency.

mdindex is the remaining consumer: install @fair-md/ui, import tokens.css, and render the shared primitives (FAIR badges, Exports affordances) identically to mdjourney.

Tokens

@import '@fair-md/ui/tokens.css'; before the app's Tailwind layers. Apps should prefer overriding tokens only when they need product-specific branding. Do not duplicate the full :root / .dark block in consumers.