@freighttech/ui 0.13.18

package/src/primitives/switch.tsx

@@ -0,0 +1,92 @@
+/**
+ * @deprecated Use `Toggle` from `@freighttech/ui/components` instead.
+ *   The new component is a native input with `role="switch"`, supports
+ *   labels via the `label` prop, and matches the Figma "FMS-Componenets"
+ *   Toggle spec. Will be removed in a future minor of `@freighttech/ui`.
+ */
+import * as React from 'react'
+
+import { cn } from '@open-mercato/shared/lib/utils'
+
+type SwitchProps = {
+  checked?: boolean
+  defaultChecked?: boolean
+  onCheckedChange?: (checked: boolean) => void
+} & Omit<React.ComponentProps<'button'>, 'onChange'>
+
+export const Switch = React.forwardRef<HTMLButtonElement, SwitchProps>(
+  ({ checked, defaultChecked, onCheckedChange, disabled, className, onClick, onKeyDown, ...props }, ref) => {
+    const isControlled = typeof checked === 'boolean'
+    const [uncontrolledValue, setUncontrolledValue] = React.useState(defaultChecked ?? false)
+
+    const currentChecked = isControlled ? checked : uncontrolledValue
+
+    const toggle = React.useCallback(
+      (event: React.MouseEvent<HTMLButtonElement> | React.KeyboardEvent<HTMLButtonElement>) => {
+        event.preventDefault()
+        if (disabled) {
+          return
+        }
+        const next = !currentChecked
+        if (!isControlled) {
+          setUncontrolledValue(next)
+        }
+        onCheckedChange?.(next)
+      },
+      [currentChecked, disabled, isControlled, onCheckedChange]
+    )
+
+    const handleClick = React.useCallback(
+      (event: React.MouseEvent<HTMLButtonElement>) => {
+        onClick?.(event)
+        if (!event.defaultPrevented) {
+          toggle(event)
+        }
+      },
+      [onClick, toggle]
+    )
+
+    const handleKeyDown = React.useCallback(
+      (event: React.KeyboardEvent<HTMLButtonElement>) => {
+        onKeyDown?.(event)
+        if (event.defaultPrevented) {
+          return
+        }
+        if (event.key === ' ' || event.key === 'Enter') {
+          toggle(event)
+        }
+      },
+      [onKeyDown, toggle]
+    )
+
+    return (
+      <button
+        type="button"
+        role="switch"
+        aria-checked={currentChecked}
+        aria-disabled={disabled}
+        data-state={currentChecked ? 'checked' : 'unchecked'}
+        data-disabled={disabled ? '' : undefined}
+        ref={ref}
+        onClick={handleClick}
+        onKeyDown={handleKeyDown}
+        disabled={disabled}
+        className={cn(
+          'inline-flex h-6 w-11 items-center rounded-full border border-transparent bg-input/60 transition-colors duration-200 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:bg-primary',
+          className
+        )}
+        {...props}
+      >
+        <span
+          aria-hidden
+          className={cn(
+            'inline-block size-5 translate-x-0 rounded-full bg-background shadow transition-transform duration-200',
+            currentChecked ? 'translate-x-5' : 'translate-x-0'
+          )}
+        />
+      </button>
+    )
+  }
+)
+
+Switch.displayName = 'Switch'

package/src/primitives/table.tsx

@@ -0,0 +1,27 @@
+import * as React from 'react'
+import { cn } from '@open-mercato/shared/lib/utils'
+
+export function Table({ className, ...props }: React.HTMLAttributes<HTMLTableElement>) {
+  return <table className={cn('w-full text-sm', className)} {...props} />
+}
+
+export function TableHeader({ className, ...props }: React.HTMLAttributes<HTMLTableSectionElement>) {
+  return <thead className={cn(className)} {...props} />
+}
+
+export function TableBody(props: React.HTMLAttributes<HTMLTableSectionElement>) {
+  return <tbody {...props} />
+}
+
+export function TableRow({ className, ...props }: React.HTMLAttributes<HTMLTableRowElement>) {
+  return <tr className={cn('border-b last:border-b-0', className)} {...props} />
+}
+
+export function TableHead({ className, ref, ...props }: React.ThHTMLAttributes<HTMLTableCellElement> & { ref?: React.Ref<HTMLTableCellElement> }) {
+  return <th ref={ref} className={cn('text-left font-medium px-4 py-2 whitespace-nowrap text-muted-foreground', className)} {...props} />
+}
+
+export function TableCell({ className, ...props }: React.TdHTMLAttributes<HTMLTableCellElement>) {
+  return <td className={cn('px-4 py-2', className)} {...props} />
+}
+

package/src/primitives/tabs.tsx

@@ -0,0 +1,131 @@
+'use client'
+
+import * as React from 'react'
+import { createContext, useContext } from 'react'
+import { cn } from '@open-mercato/shared/lib/utils'
+import { Button } from './button'
+
+type TabsContextValue = {
+  value: string
+  onValueChange: (value: string) => void
+}
+
+const TabsContext = createContext<TabsContextValue | undefined>(undefined)
+
+function useTabsContext() {
+  const context = useContext(TabsContext)
+  if (!context) {
+    throw new Error('Tabs components must be used within a Tabs provider')
+  }
+  return context
+}
+
+export type TabsProps = {
+  value?: string
+  defaultValue?: string
+  onValueChange?: (value: string) => void
+  children: React.ReactNode
+  className?: string
+}
+
+export function Tabs({
+  value: controlledValue,
+  defaultValue,
+  onValueChange,
+  children,
+  className,
+}: TabsProps) {
+  const [uncontrolledValue, setUncontrolledValue] = React.useState(defaultValue ?? '')
+  const isControlled = controlledValue !== undefined
+  const value = isControlled ? controlledValue : uncontrolledValue
+
+  const handleValueChange = React.useCallback(
+    (newValue: string) => {
+      if (!isControlled) {
+        setUncontrolledValue(newValue)
+      }
+      onValueChange?.(newValue)
+    },
+    [isControlled, onValueChange],
+  )
+
+  return (
+    <TabsContext.Provider value={{ value, onValueChange: handleValueChange }}>
+      <div className={className}>{children}</div>
+    </TabsContext.Provider>
+  )
+}
+
+export type TabsListProps = {
+  children: React.ReactNode
+  className?: string
+}
+
+export function TabsList({ children, className }: TabsListProps) {
+  return (
+    <div
+      className={cn(
+        'inline-flex h-9 items-center justify-start rounded-lg bg-muted p-1 text-muted-foreground',
+        className,
+      )}
+      role="tablist"
+    >
+      {children}
+    </div>
+  )
+}
+
+export type TabsTriggerProps = {
+  value: string
+  children: React.ReactNode
+  className?: string
+  disabled?: boolean
+}
+
+export function TabsTrigger({ value, children, className, disabled }: TabsTriggerProps) {
+  const { value: selectedValue, onValueChange } = useTabsContext()
+  const isSelected = selectedValue === value
+
+  return (
+    <Button
+      type="button"
+      variant="ghost"
+      size="sm"
+      role="tab"
+      aria-selected={isSelected}
+      disabled={disabled}
+      onClick={() => onValueChange(value)}
+      className={cn(
+        isSelected
+          ? 'bg-background text-foreground shadow'
+          : 'hover:bg-background/50 hover:text-foreground',
+        className,
+      )}
+    >
+      {children}
+    </Button>
+  )
+}
+
+export type TabsContentProps = {
+  value: string
+  children: React.ReactNode
+  className?: string
+}
+
+export function TabsContent({ value, children, className }: TabsContentProps) {
+  const { value: selectedValue } = useTabsContext()
+
+  if (selectedValue !== value) {
+    return null
+  }
+
+  return (
+    <div
+      role="tabpanel"
+      className={cn('mt-2 ring-offset-background focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2', className)}
+    >
+      {children}
+    </div>
+  )
+}

package/src/primitives/textarea.tsx

@@ -0,0 +1,20 @@
+import * as React from 'react'
+
+import { cn } from '@open-mercato/shared/lib/utils'
+
+type TextareaProps = React.TextareaHTMLAttributes<HTMLTextAreaElement>
+
+export const Textarea = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
+  ({ className, ...props }, ref) => (
+    <textarea
+      ref={ref}
+      className={cn(
+        'flex min-h-[80px] w-full rounded-md border border-input bg-background px-3 py-2 text-sm shadow-sm placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50',
+        className
+      )}
+      {...props}
+    />
+  )
+)
+
+Textarea.displayName = 'Textarea'

package/src/primitives/tooltip.tsx

@@ -0,0 +1,85 @@
+"use client"
+
+import * as React from 'react'
+import * as TooltipPrimitive from '@radix-ui/react-tooltip'
+import { cn } from '@open-mercato/shared/lib/utils'
+
+export const TooltipProvider = TooltipPrimitive.Provider
+
+export const Tooltip = TooltipPrimitive.Root
+
+export const TooltipTrigger = TooltipPrimitive.Trigger
+
+export const TooltipContent = React.forwardRef<
+  React.ElementRef<typeof TooltipPrimitive.Content>,
+  React.ComponentPropsWithoutRef<typeof TooltipPrimitive.Content>
+>(({ className, sideOffset = 4, ...props }, ref) => (
+  <TooltipPrimitive.Portal>
+    <TooltipPrimitive.Content
+      ref={ref}
+      sideOffset={sideOffset}
+      className={cn(
+        'z-50 overflow-hidden rounded-md bg-slate-900 px-3 py-1.5 text-xs text-slate-50 animate-in fade-in-0 zoom-in-95',
+        'data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95',
+        'data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2',
+        'data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2',
+        'max-w-xs break-words',
+        className
+      )}
+      {...props}
+    />
+  </TooltipPrimitive.Portal>
+))
+TooltipContent.displayName = TooltipPrimitive.Content.displayName
+
+export type TooltipProps = {
+  content: React.ReactNode
+  children: React.ReactNode
+  delayDuration?: number
+  side?: 'top' | 'right' | 'bottom' | 'left'
+  align?: 'start' | 'center' | 'end'
+  open?: boolean
+  onOpenChange?: (open: boolean) => void
+  disabled?: boolean
+}
+
+/**
+ * Simple tooltip wrapper component for common use cases.
+ *
+ * @example
+ * <SimpleTooltip content="Full text here">
+ *   <span>Truncated...</span>
+ * </SimpleTooltip>
+ */
+export function SimpleTooltip({
+  content,
+  children,
+  delayDuration = 300,
+  side = 'top',
+  align = 'center',
+  open,
+  onOpenChange,
+  disabled = false,
+}: TooltipProps) {
+  // If disabled or no content, just render children without tooltip
+  const isDisabled = disabled || !content
+
+  if (isDisabled) {
+    return <>{children}</>
+  }
+
+  return (
+    <Tooltip
+      open={open}
+      onOpenChange={onOpenChange}
+      delayDuration={delayDuration}
+    >
+      <TooltipTrigger asChild>
+        {children}
+      </TooltipTrigger>
+      <TooltipContent side={side} align={align}>
+        {content}
+      </TooltipContent>
+    </Tooltip>
+  )
+}

package/src/primitives-v2/AGENTS.md

@@ -0,0 +1,66 @@
+# `@freighttech/ui/primitives-v2` — Figma-aligned primitives
+
+This directory is the **second iteration** of the design-system primitives that ship from `@freighttech/ui`. It exists alongside the legacy `../primitives/` directory, which is being phased out.
+
+- **Source of truth**: the Figma file **FMS-Componenets** (file key `0s9VquUFfQ7u1avl6aZNkl`). Every component in this folder was built to match a specific `COMPONENT_SET` in that file, with its colors / sizes / states extracted node-by-node. The mapping is documented in each component's leading comment as a `variant × state → background / border / text` table.
+- **Tokens**: colors come from the `-v2` token set in `../theme/tokens.css` (`--primary-v2`, `--accent-v2`, `--status-v2-*`, `--sidebar-v2-*`, …). Do not reach into the legacy `--primary` / `--status-*` tokens — those exist only so `apps/web` keeps rendering until every screen migrates here.
+- **Typography**: uses the named utilities registered in `../theme/typography.css` (`text-heading-bold-2xl`, `text-body-regular-sm`, `text-code-regular-md`, …). Never `text-2xl font-bold` — the named token carries the bespoke line-height and letter-spacing.
+- **Icons**: `lucide-react` (`^0.556.0`), already a workspace dependency. The icon slots in Figma are `square-dashed` placeholders — pulling them via `download_figma_images` returns the placeholder, not a real icon. Use lucide instead.
+- **Storybook**: every component ships with a `<Name>.stories.tsx` next to it. Each has at minimum a `Playground`, an `All variants` (or `States`) story, and a `Figma parity` story that mirrors the layout of the corresponding Figma frame for direct visual diff. Run with `yarn workspace @freighttech/ui storybook`.
+- **Tests**: unit tests live under `__tests__/<Name>.test.tsx`, covering render / click / state / variant-class assertions. Run with `yarn workspace @freighttech/ui test`.
+
+## Relationship to `../primitives/`
+
+| Aspect | `primitives/` (legacy) | `primitives-v2/` (this folder) |
+|---|---|---|
+| Status | `@deprecated` JSDoc | Active |
+| Tokens | `--primary`, `--status-*` (oklch, apps/web heritage) | `-v2` tokens (Figma-extracted hex) |
+| Icons | inline custom SVGs | `lucide-react` |
+| Variant API | mostly `class-variance-authority` (`cva`) | flat prop unions, no cva dependency |
+| Shared deps | imports `@open-mercato/shared/lib/utils#cn` (subpath not in upstream `exports`, breaks Vite) | self-contained `./utils#cn` |
+| Storybook | broken (legacy `primitives.stories.tsx` excluded from glob) | full coverage |
+
+Each file in `../primitives/` carries a `@deprecated` JSDoc pointing to its replacement here. Removal is deferred — they stay until at least the next minor version of `@freighttech/ui` so Tier-3 customer apps consuming the Verdaccio package have time to migrate.
+
+## How to add a new component
+
+1. Open the Figma component-set, copy the node ID (e.g. `123:456`).
+2. Read `.ai/figma-rules.md` — especially the **Workflow** and **Tokens and the `-v2` namespace** sections. They cover the recipe end-to-end (rate limits, extraction strategy, hover-state caveats).
+3. Place the component as `<Name>.tsx`, its story as `<Name>.stories.tsx`, and tests as `__tests__/<Name>.test.tsx`.
+4. Re-export from `./index.ts` (the barrel — that's what `@freighttech/ui/primitives-v2` resolves to).
+5. If the component introduces colors that don't yet exist as `-v2` tokens, add them to `../theme/tokens.css` — never inline a raw hex.
+6. Run `yarn workspace @freighttech/ui typecheck && yarn workspace @freighttech/ui test && cd packages/ui && yarn build-storybook` before declaring done.
+
+## Don'ts
+
+- Don't import from `../primitives/`. Cross-reference is fine for migration audits, but the new components should be self-contained (or pull from the same `primitives-v2/` namespace).
+- Don't import `@open-mercato/shared/lib/utils`. Use the local `./utils#cn` instead — it's a tiny `classes.filter(Boolean).join(' ')` helper.
+- Don't add new tokens to `../theme/tokens.css` under the legacy names (no overwriting `--primary`, `--status-*`, etc.). Use the `-v2` suffix; legacy tokens stay frozen.
+- Don't ship hand-drawn placeholder SVGs in stories. Reach for `lucide-react`.
+- Don't fetch `IMAGE-SVG` icon slots from Figma — they're `square-dashed` placeholders. Confirmed; documented in `.ai/figma-rules.md`.
+
+## Files in this directory
+
+| Component | Figma node | Notes |
+|---|---|---|
+| `Alert` | `46:22` | 4 status variants from Figma + a `neutral` we add |
+| `Avatar` (+ `AvatarStack`) | `46:67` | Falls back to initials → icon → user-placeholder |
+| `Badge` | `45:26` | 12 variants × 2 sizes (full Figma palette) |
+| `Breadcrumb` | `148:411` | `/` default separator, auto-collapse past `maxItems` |
+| `Button` | `44:92` | 5 variants × 3 sizes × hover/disabled — full Figma extract in header comment |
+| `Checkbox` | `45:73` | Native input + appearance-none + inline-SVG glyphs; teal accent fill |
+| `IconButton` | `148:377` | Thin wrapper around Button; enforces `aria-label` |
+| `Input` | `147:379` | 5 states × 2 sizes; **focus border is teal** (`--accent-v2`), not navy |
+| `NavGroup` | `72:154` | Section header + collapsible list; chevron up=expanded |
+| `NavItem` | `60:78` | Active = left rail bar via `::before`, not background tint |
+| `SearchInput` | `149:375` | Specialization of `Input`; supports `shortcut` (e.g. `⌘K`) hint |
+| `Sidebar` (+ `Header` + `Footer`) | `137:354`, `112:110`, `112:117` | 220×900 shell, three slots |
+| `Tag` | `46:38` | Three **semantic** variants (`default` / `container` / `teczka`), removable |
+| `Toggle` | `45:80` | Native input role="switch"; on-state uses `--accent-v2` (teal) |
+| `Topbar` | `150:367` | 1440×52 three-slot shell |
+
+Plus:
+- `index.ts` — barrel re-exporting everything for consumers.
+- `utils.ts` — local `cn(...)` helper (the only "shared" code in this directory).
+- `*.stories.tsx` — Storybook stories per component.
+- `__tests__/*.test.tsx` — Jest unit tests per component.

package/src/primitives-v2/Alert.stories.tsx

@@ -0,0 +1,56 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import * as React from 'react'
+import { Alert } from './Alert'
+
+const meta: Meta<typeof Alert> = {
+  title: 'Components/Alert',
+  component: Alert,
+  parameters: {
+    backgrounds: {
+      default: 'figma-surface',
+      values: [{ name: 'figma-surface', value: '#F8F8FA' }],
+    },
+    docs: {
+      description: {
+        component:
+          'Figma: FMS-Componenets → Alert (46:22). Four variants in Figma (info / success / warning / error); a `neutral` is exposed in code for non-urgent helper messages. Colors come from the `-v2` status tokens extracted directly from the Figma variants.',
+      },
+    },
+  },
+}
+
+export default meta
+
+type Story = StoryObj<typeof Alert>
+
+export const Showcase: Story = {
+  name: 'Alert',
+  render: () => {
+    const [open, setOpen] = React.useState(true)
+    return (
+      <div className="flex max-w-[560px] flex-col gap-3">
+        <Alert variant="info" title="Synchronizacja w toku">
+          Powiązane faktury zostaną zaktualizowane w ciągu kilku minut.
+        </Alert>
+        <Alert variant="success" title="Faktura zatwierdzona">
+          FV/2025/0041 została przekazana do księgowości.
+        </Alert>
+        <Alert variant="warning" title="Wymaga uwagi">
+          Actual Cost = $0 dla 3 pozycji — uzupełnij alokację przed zamknięciem.
+        </Alert>
+        <Alert variant="error" title="Nie udało się wysłać do KSeF">
+          Sprawdź dane kontrahenta i spróbuj ponownie.
+        </Alert>
+        <Alert variant="neutral" title="Wstrzymane">
+          Powiązany transport oczekuje na potwierdzenie spedytora.
+        </Alert>
+        <Alert variant="info">Bez tytułu — sama treść opisowa.</Alert>
+        {open && (
+          <Alert variant="success" title="Faktura wysłana do KSeF" onDismiss={() => setOpen(false)}>
+            Można zamknąć — numer ref. <code className="text-code-regular-sm">KS-2025-0041</code>
+          </Alert>
+        )}
+      </div>
+    )
+  },
+}

package/src/primitives-v2/Alert.tsx

@@ -0,0 +1,108 @@
+import * as React from 'react'
+import { Info, CheckCircle2, AlertTriangle, XCircle, X } from 'lucide-react'
+import { cn } from './utils'
+
+/*
+  Figma source: FMS-Componenets → Alert (component-set 46:22).
+
+  Variant matrix (extracted from each variant's `fills`/`strokes`/text fill):
+    | Variant  | Background | Border  | Text    |
+    |----------|-----------|---------|---------|
+    | info     | #EFF6FF   | #BFDBFE | #1E40AF |
+    | success  | #F0FDF4   | #BBF7D0 | #166534 |
+    | warning  | #FFFBEB   | #FDE68A | #92400E |
+    | error    | #FEF2F2   | #FECACA | #991B1B |
+
+  Figma does NOT define a `neutral` Alert variant. We keep one in code
+  via the v2 neutral tokens for situations where the page needs an
+  informational message without urgency (e.g. empty-state hints).
+
+  Figma's Alert is TEXT-ONLY — no leading icon. We add lucide icons by
+  default (`Info` / `CheckCircle2` / `AlertTriangle` / `XCircle`) because
+  every realistic FMS screen renders one; pass `icon={null}` to hide.
+
+  Title uses `heading/semibold/md`, description uses `body/regular/xs`.
+  Border radius 10px = `rounded-[10px]`. Padding 12px / 16px-12px.
+*/
+
+export type AlertVariant = 'info' | 'success' | 'warning' | 'error' | 'neutral'
+
+export type AlertProps = React.HTMLAttributes<HTMLDivElement> & {
+  variant?: AlertVariant
+  title?: React.ReactNode
+  /** Override the default icon. Pass `null` to hide. */
+  icon?: React.ReactNode | null
+  /** When provided, renders a dismiss "×" button that calls this. */
+  onDismiss?: () => void
+  dismissAriaLabel?: string
+}
+
+const VARIANT_CLASSES: Record<AlertVariant, string> = {
+  info: 'bg-status-v2-info-bg border-status-v2-info-border text-status-v2-info-text',
+  success: 'bg-status-v2-success-bg border-status-v2-success-border text-status-v2-success-text',
+  warning: 'bg-status-v2-warning-bg border-status-v2-warning-border text-status-v2-warning-text',
+  error: 'bg-status-v2-error-bg border-status-v2-error-border text-status-v2-error-text',
+  neutral: 'bg-status-v2-neutral-bg border-status-v2-neutral-border text-status-v2-neutral-text',
+}
+
+const DEFAULT_ICONS: Record<AlertVariant, React.ReactNode> = {
+  info: <Info />,
+  success: <CheckCircle2 />,
+  warning: <AlertTriangle />,
+  error: <XCircle />,
+  neutral: <Info />,
+}
+
+export const Alert = React.forwardRef<HTMLDivElement, AlertProps>(function Alert(
+  {
+    variant = 'info',
+    title,
+    icon,
+    onDismiss,
+    dismissAriaLabel = 'Zamknij',
+    className,
+    children,
+    role = 'alert',
+    ...props
+  },
+  ref,
+) {
+  const resolvedIcon = icon === undefined ? DEFAULT_ICONS[variant] : icon
+
+  return (
+    <div
+      ref={ref}
+      role={role}
+      className={cn(
+        'flex w-full items-start gap-3 rounded-[10px] border px-4 py-3',
+        VARIANT_CLASSES[variant],
+        className,
+      )}
+      {...props}
+    >
+      {resolvedIcon ? (
+        <span aria-hidden="true" className="mt-0.5 inline-flex h-5 w-5 shrink-0 items-center justify-center [&>svg]:h-4 [&>svg]:w-4">
+          {resolvedIcon}
+        </span>
+      ) : null}
+      <div className="flex-1 min-w-0">
+        {title ? <div className="text-heading-semibold-md">{title}</div> : null}
+        {children ? <div className={cn('text-body-regular-xs', title ? 'mt-0.5' : null)}>{children}</div> : null}
+      </div>
+      {onDismiss ? (
+        <button
+          type="button"
+          onClick={onDismiss}
+          aria-label={dismissAriaLabel}
+          className={cn(
+            'shrink-0 inline-flex h-6 w-6 items-center justify-center rounded-md',
+            'opacity-70 transition-opacity hover:opacity-100 hover:bg-black/5',
+            'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-current focus-visible:ring-offset-1',
+          )}
+        >
+          <X className="h-3.5 w-3.5" />
+        </button>
+      ) : null}
+    </div>
+  )
+})

package/src/primitives-v2/Avatar.stories.tsx

@@ -0,0 +1,60 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { User } from 'lucide-react'
+import { Avatar, AvatarStack } from './Avatar'
+
+const meta: Meta<typeof Avatar> = {
+  title: 'Components/Avatar',
+  component: Avatar,
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Figma: FMS-Componenets → Avatar (46:67). Size × type matrix (image · initials · icon · placeholder). Falls back to initials on image load failure.',
+      },
+    },
+  },
+}
+
+export default meta
+
+type Story = StoryObj<typeof Avatar>
+
+export const Showcase: Story = {
+  name: 'Avatar',
+  render: () => (
+    <div className="flex flex-col gap-8">
+      <div className="flex items-center gap-4">
+        <Avatar size="xs" name="Anna Kowalska" />
+        <Avatar size="sm" name="Anna Kowalska" />
+        <Avatar size="md" name="Anna Kowalska" />
+        <Avatar size="lg" name="Anna Kowalska" />
+        <Avatar size="xl" name="Anna Kowalska" />
+      </div>
+      <div className="flex items-center gap-4">
+        <div className="flex flex-col items-center gap-2 text-caption-medium-md text-muted-v2-foreground">
+          <Avatar size="lg" src="https://i.pravatar.cc/120?img=12" name="Anna Kowalska" />
+          Image
+        </div>
+        <div className="flex flex-col items-center gap-2 text-caption-medium-md text-muted-v2-foreground">
+          <Avatar size="lg" name="Anna Kowalska" />
+          Initials
+        </div>
+        <div className="flex flex-col items-center gap-2 text-caption-medium-md text-muted-v2-foreground">
+          <Avatar size="lg" icon={<User />} />
+          Icon
+        </div>
+        <div className="flex flex-col items-center gap-2 text-caption-medium-md text-muted-v2-foreground">
+          <Avatar size="lg" />
+          Placeholder
+        </div>
+      </div>
+      <AvatarStack size="md" max={3}>
+        <Avatar name="Anna Kowalska" />
+        <Avatar name="Bartek Lipiński" />
+        <Avatar name="Cezary Mróz" />
+        <Avatar name="Dorota Nowak" />
+        <Avatar name="Edward O." />
+      </AvatarStack>
+    </div>
+  ),
+}