@appmirror/ui-kit

Shared UI component library for AppMirror and its tools. Built with React 19, Radix UI primitives, and Tailwind CSS.

Current Release

• Package version: 1.3.7
• Changelog: CHANGELOG.md

Installation

npm install @appmirror/ui-kit

Usage

import { Button, Card, CardHeader, CardTitle, CardContent } from '@appmirror/ui-kit';
import '@appmirror/ui-kit/styles.css';

function MyComponent() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Hello World</CardTitle>
      </CardHeader>
      <CardContent>
        <Button variant="primary">Click me</Button>
      </CardContent>
    </Card>
  );
}

Theming and Dark Mode

• This UI kit expects host theme tokens (--background, --foreground, --card, --border, etc.) to be provided by the app.
• Dark mode is class-based (.dark), matching AppMirror host behavior.
• Import @appmirror/ui-kit/styles.css once in your app entry.

Icon Best Practice

• Import icons from @appmirror/ui-kit/icons using named imports.
• Avoid namespace imports (for example import * as Icons) because they pull in unnecessary icon code.
• Backward-compatible aliases are still exported (FolderCode, ShieldUser, ChartSpline, Volleyball, IdCard, UserRoundPen).

import { Settings, Bell } from '@appmirror/ui-kit/icons';

Visual Regression Checks

Lightweight screenshot checks are available against preview/visual.html.

npm run visual:test:install
npm run visual:test:update
npm run visual:test

Release Workflow

npm run changeset          # create release note
npm run version-packages   # apply version/changelog updates
npm run build
npm run typecheck
npm run visual:test
npm run pack:smoke
npm run release            # publish to npm

Components

Core Components

• Alert - Contextual feedback messages
• Avatar - User profile images with fallback
• Badge - Small status indicators
• Button - Interactive buttons with variants
• Card - Content containers
• Checkbox - Toggle selection
• Dialog - Modal dialogs
• DropdownMenu - Contextual menus
• Input - Text input fields
• Label - Form labels
• Popover - Floating content panels
• Progress - Progress indicators
• RadioGroup - Single selection from options
• ScrollArea - Custom scrollable containers
• Select - Dropdown selection
• Separator - Visual dividers
• Skeleton - Loading placeholders
• Slider - Range selection
• Switch - Toggle switches
• Tabs - Tabbed navigation
• Textarea - Multi-line text input
• Tooltip - Hover information

Extended Components

• Accordion - Collapsible content sections
• AddButton - Styled add/create buttons
• AlertDialog - Confirmation dialogs
• AvatarGroup - Grouped avatar display
• Breadcrumb - Navigation breadcrumbs
• Carousel - Content carousels
• Collapsible - Expandable sections
• ContextMenu - Right-click menus
• DateField - Date input
• Drawer - Slide-out panels
• Form - Form utilities with react-hook-form
• HoverCard - Rich hover previews
• Kbd - Keyboard shortcuts display
• Menubar - Application menubars
• NavigationMenu - Navigation components
• Pagination - Page navigation
• Resizable - Resizable panels
• ScrollSpy - Scroll-based navigation
• Sheet - Side sheet panels
• SvgText - SVG text rendering
• Table - Data tables
• Toggle - Toggle buttons
• ToggleGroup - Grouped toggles

Icons

• KeenIcon - Icon component with duotone, filled, outline, and solid styles

Providers

• ToolContextProvider - Context bridge for Module Federation tools

Utilities

• cn - Class name utility (clsx + tailwind-merge)

Button Variants

<Button variant="primary">Primary</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="destructive">Destructive</Button>
<Button variant="outline">Outline</Button>
<Button variant="ghost">Ghost</Button>
<Button variant="mono">Mono</Button>
<Button variant="dashed">Dashed</Button>
<Button variant="dim">Dim</Button>

Button Sizes

<Button size="sm">Small</Button>
<Button size="md">Medium (default)</Button>
<Button size="lg">Large</Button>
<Button size="icon">Icon only</Button>

Component Preview

View all components in action:

import { ComponentPreview } from '@appmirror/ui-kit';

// Render on a route to see all components
<ComponentPreview />

For Tool Developers

When building AppMirror tools with Module Federation, use the ToolContextProvider:

import { useToolContext, Button, Card } from '@appmirror/ui-kit';

export default function MyTool() {
  const { projectId, projectName, api, showToast } = useToolContext();

  const handleAction = async () => {
    const result = await api.post('/api/my-endpoint', { data: 'value' });
    showToast('Action completed!', 'success');
  };

  return (
    <Card>
      <p>Working on project: {projectName}</p>
      <Button onClick={handleAction}>Do Action</Button>
    </Card>
  );
}

Peer Dependencies

• React 19
• React DOM 19

License

Private - AppMirror Internal Use