Admin UI Kit

1. Document Control

Property	Value
Package	@nx-app/admin-ui-kit
Version	0.0.0
Type	Component Library
Based On	Shadcn/UI, Radix UI
Runtime	React 19

2. Scope & Objectives

2.1. Scope

This package is the single source of truth for UI components within the BANA ecosystem. It exports stateless, accessible, and styled components used by the Back Office Client and the Back Office (BO) application.

2.2. Objectives

• Visual Consistency: Identical branding (colors, typography, spacing) across apps.
• Accessibility (a11y): Keyboard navigable and screen-reader friendly (WAI-ARIA via Radix).
• Efficiency: Ready-to-use building blocks for rapid development.
• Tree-Shaking: Named exports for optimal bundle size.

3. Technology Stack

3.1. Core Dependencies

Technology	Version	Purpose
React	^19.0.0	UI Framework (peer)
Tailwind CSS	>=4.0.0	Styling (peer)
TypeScript	^5	Type Safety

3.2. Styling Utilities

Technology	Version	Purpose
class-variance-authority	^0.7.1	Component Variants
clsx	^2.1.1	Class Composition
tailwind-merge	^3.4.0	Class Merging
tw-animate-css	^1.4.0	Animation Classes

3.3. Radix UI Primitives

Component	Version	Purpose
@radix-ui/react-accordion	^1.2.12	Expandable Sections
@radix-ui/react-alert-dialog	^1.1.15	Confirmation Dialogs
@radix-ui/react-avatar	^1.1.11	User Avatars
@radix-ui/react-checkbox	^1.3.3	Checkboxes
@radix-ui/react-collapsible	^1.1.12	Collapsible Panels
@radix-ui/react-context-menu	^2.2.16	Right-Click Menus
@radix-ui/react-dialog	^1.1.15	Modal Dialogs
@radix-ui/react-dropdown-menu	^2.1.16	Dropdown Menus
@radix-ui/react-label	^2.1.8	Form Labels
@radix-ui/react-popover	^1.1.15	Floating Panels
@radix-ui/react-radio-group	^1.3.8	Radio Buttons
@radix-ui/react-scroll-area	^1.2.10	Custom Scrollbars
@radix-ui/react-select	^2.2.6	Dropdowns
@radix-ui/react-separator	^1.1.8	Visual Dividers
@radix-ui/react-slot	^1.2.4	Component Slots
@radix-ui/react-switch	^1.2.6	Toggle Switches
@radix-ui/react-tabs	^1.1.13	Tab Navigation
@radix-ui/react-tooltip	^1.2.8	Tooltips

3.4. Additional Components

Technology	Version	Purpose
lucide-react	^0.562.0	Icon Library
vaul	^1.1.2	Drawer Component
sonner	^2.0.7	Toast Notifications
react-day-picker	^9.11.1	Calendar/Date Picker
cmdk	^1.1.1	Command Palette

3.5. Development Tools

Technology	Version	Purpose
shadcn	^3.5.1	Component CLI
tsc-alias	^1.8.16	Path Alias Resolution
@venizia/dev-configs	^0.0.5-0	Shared ESLint/Prettier

4. Project Structure

apps/admin-ui-kit/
├── src/
│   ├── components/                 # Component Source
│   │   ├── core/                   # Core Components
│   │   │   ├── backdrop/           # Overlay backdrop
│   │   │   └── common/             # Shared components
│   │   ├── icons/                  # Custom Icons
│   │   └── shadcn/                 # shadcn/ui Components (38 files)
│   │       ├── accordion.tsx
│   │       ├── alert-dialog.tsx
│   │       ├── avatar.tsx
│   │       ├── badge.tsx
│   │       ├── breadcrumb.tsx
│   │       ├── button-group.tsx
│   │       ├── button.tsx
│   │       ├── calendar.tsx
│   │       ├── card.tsx
│   │       ├── checkbox.tsx
│   │       ├── collapsible.tsx
│   │       ├── command.tsx
│   │       ├── context-menu.tsx
│   │       ├── dialog.tsx
│   │       ├── drawer.tsx
│   │       ├── dropdown-menu.tsx
│   │       ├── empty.tsx
│   │       ├── field.tsx
│   │       ├── input-group.tsx
│   │       ├── input.tsx
│   │       ├── kbd.tsx
│   │       ├── label.tsx
│   │       ├── popover.tsx
│   │       ├── radio-group.tsx
│   │       ├── scroll-area.tsx
│   │       ├── select.tsx
│   │       ├── separator.tsx
│   │       ├── sheet.tsx
│   │       ├── sidebar.tsx
│   │       ├── skeleton.tsx
│   │       ├── spinner.tsx
│   │       ├── switch.tsx
│   │       ├── table.tsx
│   │       ├── tabs.tsx
│   │       ├── textarea.tsx
│   │       └── tooltip.tsx
│   ├── hooks/                      # Custom Hooks
│   │   └── use-mobile.ts           # Mobile detection
│   ├── styles/                     # CSS Exports
│   ├── utilities/                  # Utility Functions
│   │   └── tw.utility.ts           # Tailwind merge utility
│   ├── generate-index.ts           # Index generator script
│   └── index.ts                    # Package exports
├── scripts/                        # Build scripts
├── dist/                           # Build output
└── package.json

5. Component Categories

5.1. Atoms (Base Components)

Component	Description	Variants
Button	Interactive button	default, destructive, outline, secondary, ghost, link
Input	Text input field	-
Label	Form label	-
Badge	Status indicator	Multiple color variants
Checkbox	Boolean selection	-
Switch	Toggle control	-
Separator	Visual divider	horizontal, vertical
Skeleton	Loading placeholder	-
Spinner	Loading indicator	-

5.2. Molecules (Composite Components)

Component	Description	Features
Card	Content container	Header, content, footer slots
Alert Dialog	Confirmation modal	Action/Cancel buttons
Dialog	Modal overlay	Title, description, close
Popover	Floating content	Trigger-based positioning
Tooltip	Hover information	Delay, positioning
Dropdown Menu	Action menu	Items, separators, sub-menus
Select	Dropdown selection	Search, groups, multi-select
Tabs	Tab navigation	Content panels
Accordion	Expandable sections	Single/multi expand

5.3. Organisms (Complex Components)

Component	Description	Features
Calendar	Date picker	Range selection, navigation
Command	Command palette	Search, keyboard shortcuts
Sidebar	Navigation sidebar	Collapsible, groups
Table	Data table	Headers, rows, cells
Sheet	Slide-out panel	Side positioning
Drawer	Bottom drawer	Swipe gestures

5.4. Custom Components

Component	Description
Backdrop	Overlay backdrop
ComingSoon	Placeholder component
ButtonGroup	Button grouping
InputGroup	Input with addons
Field	Form field wrapper
Empty	Empty state display
Kbd	Keyboard shortcut display

6. Component Implementation Pattern

6.1. Variant System

Components use class-variance-authority (CVA) for variant management:

const buttonVariants = cva(
  "inline-flex items-center justify-center ...",
  {
    variants: {
      variant: {
        default: 'bg-primary text-primary-foreground hover:bg-primary/90',
        destructive: 'bg-destructive text-white hover:bg-destructive/90',
        outline: 'border bg-background shadow-xs hover:bg-accent',
        secondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
        ghost: 'hover:bg-accent hover:text-accent-foreground',
        link: 'text-primary underline-offset-4 hover:underline',
      },
      size: {
        default: 'h-9 px-4 py-2',
        lg: 'h-10 rounded-md px-6',
        sm: 'h-8 rounded-md gap-1.5 py-1.5 px-2.5',
        xs: 'h-7 rounded-md gap-1.5 px-1.5 py-1',
        icon: 'size-9',
      },
    },
    defaultVariants: {
      variant: 'default',
      size: 'default',
    },
  },
);

6.2. Class Utility

The cn utility merges Tailwind classes intelligently:

import clsx, { ClassValue } from 'clsx';
import { twMerge } from 'tailwind-merge';

export const cn = (...inputs: ClassValue[]) => {
  return twMerge(clsx(inputs));
};

6.3. Component Structure

function Button({
  className,
  variant,
  size,
  asChild = false,
  ...props
}: React.ComponentProps<'button'> &
  VariantProps<typeof buttonVariants> & {
    asChild?: boolean;
  }) {
  const Comp = asChild ? Slot : 'button';

  return (
    <Comp
      data-slot="button"
      className={cn(buttonVariants({ variant, size, className }))}
      {...props}
    />
  );
}

7. Button Variants

7.1. Visual Variants

Variant	Style	Use Case
default	Primary background	Primary actions
destructive	Red/danger color	Delete, remove actions
outline	Border only	Secondary actions
secondary	Muted background	Alternative actions
ghost	No background	Subtle actions
link	Text only	Navigation links
default-active	Active primary	Selected state

7.2. Size Variants

Size	Height	Use Case
default	36px (h-9)	Standard buttons
lg	40px (h-10)	Prominent buttons
sm	32px (h-8)	Compact buttons
xs	28px (h-7)	Very compact
icon	36x36px	Icon-only buttons
icon-sm	32x32px	Small icon buttons
icon-lg	40x40px	Large icon buttons
icon-xs	28x28px	Very small icon buttons
icon-xxs	20x20px	Minimal icon buttons

8. Hooks

8.1. useMobile

Detects mobile viewport for responsive behavior:

import { useMobile } from '@nx-app/admin-ui-kit';

const isMobile = useMobile();

9. Usage

9.1. Installation

The package is linked via Bun workspace protocols:

{
  "dependencies": {
    "@nx-app/admin-ui-kit": "workspace:*"
  }
}

9.2. Import Pattern

Named exports support tree-shaking:

import {
  Button,
  Card,
  CardContent,
  CardHeader,
  Dialog,
  DialogContent,
  DialogTrigger,
} from '@nx-app/admin-ui-kit';

9.3. Customization

Components accept className for Tailwind overrides:

<Button className="bg-red-500 hover:bg-red-600">
  Critical Action
</Button>

9.4. Composition with Radix Slot

Use asChild for component composition:

<Button asChild>
  <Link href="/dashboard">Go to Dashboard</Link>
</Button>

10. Design Tokens

10.1. Color System

Token	Purpose
primary	Brand color
primary-foreground	Text on primary
secondary	Secondary actions
secondary-foreground	Text on secondary
destructive	Danger/delete actions
muted	Subtle backgrounds
muted-foreground	Subtle text
accent	Highlights
accent-foreground	Text on accent
background	Page background
foreground	Primary text
card	Card backgrounds
card-foreground	Card text
popover	Popover backgrounds
popover-foreground	Popover text
border	Border color
input	Input borders
ring	Focus rings

10.2. Spacing & Radius

Token	Value	Usage
radius	Configurable	Border radius

11. Exports

11.1. Package Exports

{
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "types": "./dist/index.d.ts"
    },
    "./styles/*": "./src/styles/*"
  }
}

11.2. Side Effects

CSS files are marked as side effects for proper bundling:

{
  "sideEffects": ["**/*.css"]
}

12. Build & Scripts

12.1. Available Scripts

Script	Command	Purpose
gen:index	bun ./src/generate-index.ts	Auto-generate index.ts
build	sh ./scripts/build.sh	Production build
rebuild	bun run gen:index && sh ./scripts/rebuild.sh	Full rebuild
clean	sh ./scripts/clean.sh	Clean dist folder
lint	bun run eslint && bun run prettier:cli	Run linters
lint:fix	Fix lint issues	Auto-fix

12.2. Index Generation

Components are auto-exported via generate-index.ts:

// 🚀 AUTO GENERATE - DON'T EDIT THIS FILE

// Exports from components
export * from "./components/shadcn/button";
export * from "./components/shadcn/card";
// ... more exports

// Exports from hooks
export * from "./hooks/use-mobile";

// Exports from utilities
export * from "./utilities/tw.utility";

13. Consumers

13.1. Applications Using Admin UI Kit

Application	Usage
client (Back Office)	Full component library
bo (Back Office Internal)	Full component library

13.2. Not Used In

Application	Reason
sale-renderer (POS UI)	Has own shadcn components

14. Code Statistics

Metric	Count
Component Files	40+
shadcn Components	38
Custom Components	4
Icons	2
Hooks	1
Utilities	1
Radix Primitives	18