xertica-ui 2.3.0 → 2.4.0

package/docs/components/card-patterns.md

@@ -1,445 +1,447 @@
-# Card Patterns
-
-## Overview
-
-Pre-composed card blocks for dashboards, project management, and feature pages. Each component is built exclusively from `ui/` primitives — no external dependencies. They live in `components/blocks/card-patterns/` and are available from the root `xertica-ui` import.
-
----
-
-## When to Use
-
-- You need a recurring dashboard pattern (activity feed, KPI, project status, notifications) and don't want to re-compose it from scratch in every feature.
-- The pattern is stable and reused across multiple pages.
-
-## When NOT to Use
-
-- One-off layouts specific to a single page — compose directly from `Card` and `ui/` primitives instead.
-- When the pattern has significant data-fetching logic — keep the block as a pure presentational component and handle state in the feature layer.
-
----
-
-## Import
-
-```tsx
-// from root barrel
-import { ActivityCard, ProjectCard, FeatureCard } from 'xertica-ui';
-
-// or from blocks subpath (when available)
-import { ActivityCard, ProjectCard, FeatureCard } from 'xertica-ui/blocks';
-```
-
----
-
-## Components
-
-### FeatureCard
-
-Icon with a colored background, title, optional badge, description, and an action button. Matches the card pattern used on the Home page.
-
-```tsx
-import { FeatureCard } from 'xertica-ui';
-import { FileText } from 'lucide-react';
-
-<FeatureCard
-  title="Template CLI"
-  description="Página de template pronta para uso com todos os componentes configurados."
-  icon={<FileText />}
-  color="chart-2"
-  badge="Novo"
-  actionLabel="Visualizar"
-  onAction={() => navigate('/template')}
-/>;
-```
-
-**Props:**
-
-| Prop            | Type               | Default     | Description                                  |
-| --------------- | ------------------ | ----------- | -------------------------------------------- |
-| `title`         | `string`           | —           | Card title                                   |
-| `description`   | `string`           | —           | Body text                                    |
-| `icon`          | `ReactNode`        | —           | Icon element (size is controlled internally) |
-| `color`         | `FeatureCardColor` | `'primary'` | Icon background color token                  |
-| `badge`         | `string`           | —           | Optional badge label                         |
-| `badgeVariant`  | `BadgeVariant`     | `'default'` | Badge color variant                          |
-| `actionLabel`   | `string`           | —           | Button label (omit to hide button)           |
-| `actionVariant` | `ButtonVariant`    | `'outline'` | Button variant                               |
-| `onAction`      | `() => void`       | —           | Button click handler                         |
-
-**`FeatureCardColor` values:** `primary` · `chart-1` · `chart-2` · `chart-3` · `chart-4` · `chart-5` · `success` · `info` · `warning` · `destructive`
-
----
-
-### ActivityCard
-
-Chronological feed of user actions with avatar, action description, timestamp, and type badge.
-
-```tsx
-import { ActivityCard } from 'xertica-ui';
-
-<ActivityCard
-  title="Atividade Recente"
-  items={[
-    {
-      id: '1',
-      user: { name: 'Ana Souza', initials: 'AS' },
-      action: 'criou o projeto',
-      target: 'Xertica Dashboard',
-      time: 'há 2 min',
-      type: 'create',
-    },
-  ]}
-  action={
-    <Button variant="ghost" size="sm">
-      Ver tudo
-    </Button>
-  }
-  maxItems={5}
-/>;
-```
-
-**Props:**
-
-| Prop       | Type             | Default               | Description                 |
-| ---------- | ---------------- | --------------------- | --------------------------- |
-| `title`    | `string`         | `'Atividade Recente'` | Card title                  |
-| `items`    | `ActivityItem[]` | —                     | Feed entries                |
-| `action`   | `ReactNode`      | —                     | Right-aligned header action |
-| `maxItems` | `number`         | `5`                   | Maximum visible items       |
-
-**`ActivityItem` shape:**
-
-```ts
-{
-  id: string
-  user: { name: string; initials: string; avatar?: string }
-  action: string        // verb: "criou", "atualizou", etc.
-  target: string        // object of the action
-  time: string          // relative time string
-  type?: 'create' | 'update' | 'delete' | 'comment' | 'deploy'
-}
-```
-
----
-
-### ProfileCard
-
-User or team member card with avatar, status badge, stat row, and primary/secondary actions.
-
-```tsx
-import { ProfileCard } from 'xertica-ui';
-
-<ProfileCard
-  name="Ana Souza"
-  role="Senior Frontend Engineer"
-  department="Design System"
-  initials="AS"
-  status="online"
-  stats={[
-    { label: 'Projetos', value: 12 },
-    { label: 'Commits', value: 348 },
-    { label: 'Reviews', value: 57 },
-  ]}
-  primaryAction={{ label: 'Ver Perfil' }}
-  secondaryAction={{ label: 'Mensagem' }}
-/>;
-```
-
-**Props:**
-
-| Prop              | Type                                           | Default | Description                      |
-| ----------------- | ---------------------------------------------- | ------- | -------------------------------- |
-| `name`            | `string`                                       | —       | Full name                        |
-| `role`            | `string`                                       | —       | Job title                        |
-| `department`      | `string`                                       | —       | Department or team               |
-| `initials`        | `string`                                       | —       | Avatar fallback (2 chars)        |
-| `avatar`          | `string`                                       | —       | Avatar image URL                 |
-| `status`          | `'online' \| 'offline' \| 'away' \| 'busy'`    | —       | Presence badge                   |
-| `stats`           | `{ label: string; value: string \| number }[]` | —       | Up to 3 stats in the divider row |
-| `primaryAction`   | `{ label: string; onClick?: () => void }`      | —       | Primary button                   |
-| `secondaryAction` | `{ label: string; onClick?: () => void }`      | —       | Secondary (outline) button       |
-
----
-
-### ProjectCard
-
-Project status widget with title, description, status badge, progress bar, member avatar stack, and due date.
-
-```tsx
-import { ProjectCard } from 'xertica-ui';
-
-<ProjectCard
-  title="Xertica Dashboard v3"
-  description="Redesign completo do painel."
-  status="active"
-  progress={68}
-  dueDate="Vence em 12 dias"
-  members={[
-    { name: 'Ana', initials: 'AS' },
-    { name: 'Bruno', initials: 'BL' },
-  ]}
-/>;
-```
-
-**Props:**
-
-| Prop          | Type              | Default | Description                               |
-| ------------- | ----------------- | ------- | ----------------------------------------- |
-| `title`       | `string`          | —       | Project name                              |
-| `description` | `string`          | —       | Short description                         |
-| `status`      | `ProjectStatus`   | —       | Controls badge color and progress color   |
-| `progress`    | `number`          | —       | 0–100 completion percentage               |
-| `dueDate`     | `string`          | —       | Due date label string                     |
-| `members`     | `ProjectMember[]` | `[]`    | Avatar stack                              |
-| `maxMembers`  | `number`          | `4`     | Max visible avatars before overflow count |
-| `action`      | `ReactNode`       | —       | Extra action appended to the status badge |
-
-**`ProjectStatus` values:** `active` · `review` · `done` · `paused` · `at-risk`
-
----
-
-### QuickActionCard
-
-Action tile with icon in colored box, title, description, optional badge, and a full-width action button.
-
-```tsx
-import { QuickActionCard } from 'xertica-ui';
-import { FileText } from 'lucide-react';
-
-<QuickActionCard
-  title="Novo Relatório"
-  description="Gere relatórios personalizados de métricas."
-  icon={<FileText className="size-5" />}
-  actionLabel="Criar Relatório"
-  badge="Pro"
-  badgeVariant="warning"
-  onAction={() => openReportModal()}
-/>;
-```
-
-**Props:**
-
-| Prop            | Type            | Default       | Description              |
-| --------------- | --------------- | ------------- | ------------------------ |
-| `title`         | `string`        | —             | Tile title               |
-| `description`   | `string`        | —             | Supporting text          |
-| `icon`          | `ReactNode`     | —             | Icon in the colored box  |
-| `badge`         | `string`        | —             | Optional badge           |
-| `badgeVariant`  | `BadgeVariant`  | `'secondary'` | Badge color variant      |
-| `actionLabel`   | `string`        | —             | Button label             |
-| `actionVariant` | `ButtonVariant` | `'default'`   | Button variant           |
-| `onAction`      | `() => void`    | —             | Button click handler     |
-| `disabled`      | `boolean`       | `false`       | Disables the entire card |
-
----
-
-### NotificationCard
-
-Notification list with unread indicator dots, type badges, timestamps, and bulk mark-as-read action.
-
-```tsx
-import { NotificationCard } from 'xertica-ui';
-
-<NotificationCard
-  title="Notificações"
-  items={[
-    {
-      id: '1',
-      title: 'Deploy concluído',
-      message: 'v2.1.0 publicado com sucesso.',
-      time: 'há 2 min',
-      read: false,
-      type: 'success',
-    },
-  ]}
-  onMarkAllRead={() => markAllRead()}
-  onViewAll={() => navigate('/notifications')}
-  maxItems={4}
-/>;
-```
-
-**Props:**
-
-| Prop            | Type                 | Default          | Description                                     |
-| --------------- | -------------------- | ---------------- | ----------------------------------------------- |
-| `title`         | `string`             | `'Notificações'` | Card title                                      |
-| `items`         | `NotificationItem[]` | —                | Notification entries                            |
-| `unreadCount`   | `number`             | auto-counted     | Override unread count badge                     |
-| `onMarkAllRead` | `() => void`         | —                | Shows "Marcar todas como lidas" button when set |
-| `onViewAll`     | `() => void`         | —                | Shows "Ver todas" footer button when set        |
-| `maxItems`      | `number`             | `4`              | Maximum visible items                           |
-
-**`NotificationItem` shape:**
-
-```ts
-{
-  id: string
-  title: string
-  message: string
-  time: string
-  read?: boolean
-  type?: 'info' | 'warning' | 'success' | 'error' | 'default'
-  user?: { name: string; initials: string; avatar?: string }
-}
-```
-
----
-
-## Dashboard Layout Example
-
-```tsx
-import {
-  ActivityCard,
-  ChartCard,
-  NotificationCard,
-  ProfileCard,
-  ProjectCard,
-  QuickActionCard,
-} from 'xertica-ui';
-import { DashboardLineChart } from 'xertica-ui/ui';
-import { Briefcase, Users, BarChart2 } from 'lucide-react';
-
-<div className="grid gap-4">
-  {/* Quick actions row */}
-  <div className="grid gap-4 md:grid-cols-3">
-    <QuickActionCard title="Novo Projeto" icon={<Briefcase />} actionLabel="Criar" />
-    <QuickActionCard
-      title="Convidar Equipe"
-      icon={<Users />}
-      actionLabel="Convidar"
-      actionVariant="outline"
-    />
-    <QuickActionCard
-      title="Relatórios"
-      icon={<BarChart2 />}
-      actionLabel="Abrir"
-      badge="Novo"
-      badgeVariant="success"
-    />
-  </div>
-
-  {/* Chart + Notifications */}
-  <div className="grid gap-4 md:grid-cols-3">
-    <div className="md:col-span-2">
-      <ChartCard title="Usuários Ativos" description="Esta semana" contentClassName="h-[220px]">
-        <DashboardLineChart
-          data={lineData}
-          config={lineConfig}
-          series={[{ key: 'usuarios', label: 'Usuários' }]}
-          indexKey="dia"
-          className="h-full w-full"
-        />
-      </ChartCard>
-    </div>
-    <NotificationCard title="Alertas" items={notifications} onViewAll={() => {}} />
-  </div>
-
-  {/* Activity + Profile + Project */}
-  <div className="grid gap-4 md:grid-cols-2">
-    <ActivityCard items={activityItems} />
-    <div className="grid gap-4">
-      <ProfileCard
-        name="Ana Souza"
-        role="Designer"
-        initials="AS"
-        status="online"
-        stats={[{ label: 'Projetos', value: 12 }]}
-      />
-      <ProjectCard
-        title="Dashboard v3"
-        status="active"
-        progress={68}
-        dueDate="12 dias"
-        members={members}
-      />
-    </div>
-  </div>
-</div>;
-```
-
----
-
-## Loading States — Skeleton Components
-
-Every card pattern ships with a matching `*Skeleton` companion that mirrors its layout with pulsing placeholders. Use them while data is loading to avoid layout shift and provide visual feedback.
-
-| Card                | Skeleton companion         | Configurable props                       |
-| ------------------- | -------------------------- | ---------------------------------------- |
-| `ActivityCard`      | `ActivityCardSkeleton`     | `rows` (default `5`)                     |
-| `ProfileCard`       | `ProfileCardSkeleton`      | `showStats`, `showActions`               |
-| `ProjectCard`       | `ProjectCardSkeleton`      | `memberCount` (default `3`)              |
-| `NotificationCard`  | `NotificationCardSkeleton` | `rows` (default `4`), `showViewAll`      |
-| `QuickActionCard`   | `QuickActionCardSkeleton`  | —                                        |
-| `FeatureCard`       | `FeatureCardSkeleton`      | `showAction`                             |
-
-> A matching `StatsCardSkeleton` is also available from `xertica-ui` (lives in `ui/stats-card/`, with props `showIcon` and `showTrend`).
-
-### Usage pattern
-
-```tsx
-import { useQuery } from '@tanstack/react-query';
-import { ActivityCard, ActivityCardSkeleton } from 'xertica-ui';
-
-function ActivityFeed() {
-  const { data: items, isLoading } = useActivityItems();
-
-  if (isLoading) return <ActivityCardSkeleton rows={5} />;
-  return <ActivityCard items={items!} />;
-}
-```
-
-For grids, render one skeleton per expected card:
-
-```tsx
-{isLoading ? (
-  <>
-    <FeatureCardSkeleton showAction />
-    <FeatureCardSkeleton showAction />
-    <FeatureCardSkeleton showAction />
-  </>
-) : (
-  data.map(item => <FeatureCard key={item.id} {...item} />)
-)}
-```
-
-### Examples
-
-```tsx
-// ActivityCard with 4 row placeholders
-<ActivityCardSkeleton rows={4} />
-
-// ProfileCard without stats grid and without action buttons
-<ProfileCardSkeleton showStats={false} showActions={false} />
-
-// ProjectCard with 5 member-avatar placeholders
-<ProjectCardSkeleton memberCount={5} />
-
-// NotificationCard with footer placeholder
-<NotificationCardSkeleton rows={3} showViewAll />
-
-// FeatureCard without footer action button
-<FeatureCardSkeleton showAction={false} />
-```
-
-> All skeletons use the `Skeleton` primitive from `ui/skeleton`, inheriting the `bg-accent animate-pulse` styling. They render plain `<div>` placeholders — no real Card/Header/Footer subcomponents — so they're cheap to render at scale.
-
----
-
-## AI Rules
-
-- Import block components from `xertica-ui` — they are included in the root barrel.
-- Pass all data as props — never embed fetch calls inside block components.
-- Keep `maxItems` at a sensible limit (4–6) to avoid overflow in fixed-height containers.
-- For chart panels, use `ChartCard` from `xertica-ui/ui` (not a block component) with any dashboard-ready chart as `children`.
-- `FeatureCard` badge wraps to a new line when title + badge don't fit — this is intentional; do not constrain the container width to force inline layout.
-- **Always pair each card with its matching `*Skeleton` for loading states** — do not render a spinner or empty container while data fetches. The skeleton variants mirror the final layout closely, preventing layout shift when data arrives.
-- **Skeleton row counts should match the expected data count when possible** — pass `rows={maxItems}` to `ActivityCardSkeleton`/`NotificationCardSkeleton` so the placeholder height matches the loaded state.
-
----
-
-## Related
-
-- [`Card`](./card.md) — Primitive used internally by all block components
-- [`StatsCard`](./stats-card.md) — KPI card (lives in `ui/`, not `blocks/`) — also has `StatsCardSkeleton`
-- [`Skeleton`](./skeleton.md) — Low-level pulsing placeholder primitive used by every `*Skeleton` here
-- [`Chart`](./chart.md) — `ChartCard` and dashboard-ready chart wrappers
-- [Dashboard Pattern](../patterns/dashboard.md)
+# Card Patterns
+
+## Overview
+
+Pre-composed card blocks for dashboards, project management, and feature pages. Each component is built exclusively from `ui/` primitives — no external dependencies. They live in `components/blocks/card-patterns/` and are available from the root `xertica-ui` import.
+
+---
+
+## When to Use
+
+- You need a recurring dashboard pattern (activity feed, KPI, project status, notifications) and don't want to re-compose it from scratch in every feature.
+- The pattern is stable and reused across multiple pages.
+
+## When NOT to Use
+
+- One-off layouts specific to a single page — compose directly from `Card` and `ui/` primitives instead.
+- When the pattern has significant data-fetching logic — keep the block as a pure presentational component and handle state in the feature layer.
+
+---
+
+## Import
+
+```tsx
+// from root barrel
+import { ActivityCard, ProjectCard, FeatureCard } from 'xertica-ui';
+
+// or from blocks subpath (when available)
+import { ActivityCard, ProjectCard, FeatureCard } from 'xertica-ui/blocks';
+```
+
+---
+
+## Components
+
+### FeatureCard
+
+Icon with a colored background, title, optional badge, description, and an action button. Matches the card pattern used on the Home page.
+
+```tsx
+import { FeatureCard } from 'xertica-ui';
+import { FileText } from 'lucide-react';
+
+<FeatureCard
+  title="Template CLI"
+  description="Página de template pronta para uso com todos os componentes configurados."
+  icon={<FileText />}
+  color="chart-2"
+  badge="Novo"
+  actionLabel="Visualizar"
+  onAction={() => navigate('/template')}
+/>;
+```
+
+**Props:**
+
+| Prop            | Type               | Default     | Description                                  |
+| --------------- | ------------------ | ----------- | -------------------------------------------- |
+| `title`         | `string`           | —           | Card title                                   |
+| `description`   | `string`           | —           | Body text                                    |
+| `icon`          | `ReactNode`        | —           | Icon element (size is controlled internally) |
+| `color`         | `FeatureCardColor` | `'primary'` | Icon background color token                  |
+| `badge`         | `string`           | —           | Optional badge label                         |
+| `badgeVariant`  | `BadgeVariant`     | `'default'` | Badge color variant                          |
+| `actionLabel`   | `string`           | —           | Button label (omit to hide button)           |
+| `actionVariant` | `ButtonVariant`    | `'outline'` | Button variant                               |
+| `onAction`      | `() => void`       | —           | Button click handler                         |
+
+**`FeatureCardColor` values:** `primary` · `chart-1` · `chart-2` · `chart-3` · `chart-4` · `chart-5` · `success` · `info` · `warning` · `destructive`
+
+---
+
+### ActivityCard
+
+Chronological feed of user actions with avatar, action description, timestamp, and type badge.
+
+```tsx
+import { ActivityCard } from 'xertica-ui';
+
+<ActivityCard
+  title="Atividade Recente"
+  items={[
+    {
+      id: '1',
+      user: { name: 'Ana Souza', initials: 'AS' },
+      action: 'criou o projeto',
+      target: 'Xertica Dashboard',
+      time: 'há 2 min',
+      type: 'create',
+    },
+  ]}
+  action={
+    <Button variant="ghost" size="sm">
+      Ver tudo
+    </Button>
+  }
+  maxItems={5}
+/>;
+```
+
+**Props:**
+
+| Prop       | Type             | Default               | Description                 |
+| ---------- | ---------------- | --------------------- | --------------------------- |
+| `title`    | `string`         | `'Atividade Recente'` | Card title                  |
+| `items`    | `ActivityItem[]` | —                     | Feed entries                |
+| `action`   | `ReactNode`      | —                     | Right-aligned header action |
+| `maxItems` | `number`         | `5`                   | Maximum visible items       |
+
+**`ActivityItem` shape:**
+
+```ts
+{
+  id: string
+  user: { name: string; initials: string; avatar?: string }
+  action: string        // verb: "criou", "atualizou", etc.
+  target: string        // object of the action
+  time: string          // relative time string
+  type?: 'create' | 'update' | 'delete' | 'comment' | 'deploy'
+}
+```
+
+---
+
+### ProfileCard
+
+User or team member card with avatar, status badge, stat row, and primary/secondary actions.
+
+```tsx
+import { ProfileCard } from 'xertica-ui';
+
+<ProfileCard
+  name="Ana Souza"
+  role="Senior Frontend Engineer"
+  department="Design System"
+  initials="AS"
+  status="online"
+  stats={[
+    { label: 'Projetos', value: 12 },
+    { label: 'Commits', value: 348 },
+    { label: 'Reviews', value: 57 },
+  ]}
+  primaryAction={{ label: 'Ver Perfil' }}
+  secondaryAction={{ label: 'Mensagem' }}
+/>;
+```
+
+**Props:**
+
+| Prop              | Type                                           | Default | Description                      |
+| ----------------- | ---------------------------------------------- | ------- | -------------------------------- |
+| `name`            | `string`                                       | —       | Full name                        |
+| `role`            | `string`                                       | —       | Job title                        |
+| `department`      | `string`                                       | —       | Department or team               |
+| `initials`        | `string`                                       | —       | Avatar fallback (2 chars)        |
+| `avatar`          | `string`                                       | —       | Avatar image URL                 |
+| `status`          | `'online' \| 'offline' \| 'away' \| 'busy'`    | —       | Presence badge                   |
+| `stats`           | `{ label: string; value: string \| number }[]` | —       | Up to 3 stats in the divider row |
+| `primaryAction`   | `{ label: string; onClick?: () => void }`      | —       | Primary button                   |
+| `secondaryAction` | `{ label: string; onClick?: () => void }`      | —       | Secondary (outline) button       |
+
+---
+
+### ProjectCard
+
+Project status widget with title, description, status badge, progress bar, member avatar stack, and due date.
+
+```tsx
+import { ProjectCard } from 'xertica-ui';
+
+<ProjectCard
+  title="Xertica Dashboard v3"
+  description="Redesign completo do painel."
+  status="active"
+  progress={68}
+  dueDate="Vence em 12 dias"
+  members={[
+    { name: 'Ana', initials: 'AS' },
+    { name: 'Bruno', initials: 'BL' },
+  ]}
+/>;
+```
+
+**Props:**
+
+| Prop          | Type              | Default | Description                               |
+| ------------- | ----------------- | ------- | ----------------------------------------- |
+| `title`       | `string`          | —       | Project name                              |
+| `description` | `string`          | —       | Short description                         |
+| `status`      | `ProjectStatus`   | —       | Controls badge color and progress color   |
+| `progress`    | `number`          | —       | 0–100 completion percentage               |
+| `dueDate`     | `string`          | —       | Due date label string                     |
+| `members`     | `ProjectMember[]` | `[]`    | Avatar stack                              |
+| `maxMembers`  | `number`          | `4`     | Max visible avatars before overflow count |
+| `action`      | `ReactNode`       | —       | Extra action appended to the status badge |
+
+**`ProjectStatus` values:** `active` · `review` · `done` · `paused` · `at-risk`
+
+---
+
+### QuickActionCard
+
+Action tile with icon in colored box, title, description, optional badge, and a full-width action button.
+
+```tsx
+import { QuickActionCard } from 'xertica-ui';
+import { FileText } from 'lucide-react';
+
+<QuickActionCard
+  title="Novo Relatório"
+  description="Gere relatórios personalizados de métricas."
+  icon={<FileText className="size-5" />}
+  actionLabel="Criar Relatório"
+  badge="Pro"
+  badgeVariant="warning"
+  onAction={() => openReportModal()}
+/>;
+```
+
+**Props:**
+
+| Prop            | Type            | Default       | Description              |
+| --------------- | --------------- | ------------- | ------------------------ |
+| `title`         | `string`        | —             | Tile title               |
+| `description`   | `string`        | —             | Supporting text          |
+| `icon`          | `ReactNode`     | —             | Icon in the colored box  |
+| `badge`         | `string`        | —             | Optional badge           |
+| `badgeVariant`  | `BadgeVariant`  | `'secondary'` | Badge color variant      |
+| `actionLabel`   | `string`        | —             | Button label             |
+| `actionVariant` | `ButtonVariant` | `'default'`   | Button variant           |
+| `onAction`      | `() => void`    | —             | Button click handler     |
+| `disabled`      | `boolean`       | `false`       | Disables the entire card |
+
+---
+
+### NotificationCard
+
+Notification list with unread indicator dots, type badges, timestamps, and bulk mark-as-read action.
+
+```tsx
+import { NotificationCard } from 'xertica-ui';
+
+<NotificationCard
+  title="Notificações"
+  items={[
+    {
+      id: '1',
+      title: 'Deploy concluído',
+      message: 'v2.1.0 publicado com sucesso.',
+      time: 'há 2 min',
+      read: false,
+      type: 'success',
+    },
+  ]}
+  onMarkAllRead={() => markAllRead()}
+  onViewAll={() => navigate('/notifications')}
+  maxItems={4}
+/>;
+```
+
+**Props:**
+
+| Prop            | Type                 | Default          | Description                                     |
+| --------------- | -------------------- | ---------------- | ----------------------------------------------- |
+| `title`         | `string`             | `'Notificações'` | Card title                                      |
+| `items`         | `NotificationItem[]` | —                | Notification entries                            |
+| `unreadCount`   | `number`             | auto-counted     | Override unread count badge                     |
+| `onMarkAllRead` | `() => void`         | —                | Shows "Marcar todas como lidas" button when set |
+| `onViewAll`     | `() => void`         | —                | Shows "Ver todas" footer button when set        |
+| `maxItems`      | `number`             | `4`              | Maximum visible items                           |
+
+**`NotificationItem` shape:**
+
+```ts
+{
+  id: string
+  title: string
+  message: string
+  time: string
+  read?: boolean
+  type?: 'info' | 'warning' | 'success' | 'error' | 'default'
+  user?: { name: string; initials: string; avatar?: string }
+}
+```
+
+---
+
+## Dashboard Layout Example
+
+```tsx
+import {
+  ActivityCard,
+  ChartCard,
+  NotificationCard,
+  ProfileCard,
+  ProjectCard,
+  QuickActionCard,
+} from 'xertica-ui';
+import { DashboardLineChart } from 'xertica-ui/ui';
+import { Briefcase, Users, BarChart2 } from 'lucide-react';
+
+<div className="grid gap-4">
+  {/* Quick actions row */}
+  <div className="grid gap-4 md:grid-cols-3">
+    <QuickActionCard title="Novo Projeto" icon={<Briefcase />} actionLabel="Criar" />
+    <QuickActionCard
+      title="Convidar Equipe"
+      icon={<Users />}
+      actionLabel="Convidar"
+      actionVariant="outline"
+    />
+    <QuickActionCard
+      title="Relatórios"
+      icon={<BarChart2 />}
+      actionLabel="Abrir"
+      badge="Novo"
+      badgeVariant="success"
+    />
+  </div>
+
+  {/* Chart + Notifications */}
+  <div className="grid gap-4 md:grid-cols-3">
+    <div className="md:col-span-2">
+      <ChartCard title="Usuários Ativos" description="Esta semana" contentClassName="h-[220px]">
+        <DashboardLineChart
+          data={lineData}
+          config={lineConfig}
+          series={[{ key: 'usuarios', label: 'Usuários' }]}
+          indexKey="dia"
+          className="h-full w-full"
+        />
+      </ChartCard>
+    </div>
+    <NotificationCard title="Alertas" items={notifications} onViewAll={() => {}} />
+  </div>
+
+  {/* Activity + Profile + Project */}
+  <div className="grid gap-4 md:grid-cols-2">
+    <ActivityCard items={activityItems} />
+    <div className="grid gap-4">
+      <ProfileCard
+        name="Ana Souza"
+        role="Designer"
+        initials="AS"
+        status="online"
+        stats={[{ label: 'Projetos', value: 12 }]}
+      />
+      <ProjectCard
+        title="Dashboard v3"
+        status="active"
+        progress={68}
+        dueDate="12 dias"
+        members={members}
+      />
+    </div>
+  </div>
+</div>;
+```
+
+---
+
+## Loading States — Skeleton Components
+
+Every card pattern ships with a matching `*Skeleton` companion that mirrors its layout with pulsing placeholders. Use them while data is loading to avoid layout shift and provide visual feedback.
+
+| Card               | Skeleton companion         | Configurable props                  |
+| ------------------ | -------------------------- | ----------------------------------- |
+| `ActivityCard`     | `ActivityCardSkeleton`     | `rows` (default `5`)                |
+| `ProfileCard`      | `ProfileCardSkeleton`      | `showStats`, `showActions`          |
+| `ProjectCard`      | `ProjectCardSkeleton`      | `memberCount` (default `3`)         |
+| `NotificationCard` | `NotificationCardSkeleton` | `rows` (default `4`), `showViewAll` |
+| `QuickActionCard`  | `QuickActionCardSkeleton`  | —                                   |
+| `FeatureCard`      | `FeatureCardSkeleton`      | `showAction`                        |
+
+> A matching `StatsCardSkeleton` is also available from `xertica-ui` (lives in `ui/stats-card/`, with props `showIcon` and `showTrend`).
+
+### Usage pattern
+
+```tsx
+import { useQuery } from '@tanstack/react-query';
+import { ActivityCard, ActivityCardSkeleton } from 'xertica-ui';
+
+function ActivityFeed() {
+  const { data: items, isLoading } = useActivityItems();
+
+  if (isLoading) return <ActivityCardSkeleton rows={5} />;
+  return <ActivityCard items={items!} />;
+}
+```
+
+For grids, render one skeleton per expected card:
+
+```tsx
+{
+  isLoading ? (
+    <>
+      <FeatureCardSkeleton showAction />
+      <FeatureCardSkeleton showAction />
+      <FeatureCardSkeleton showAction />
+    </>
+  ) : (
+    data.map(item => <FeatureCard key={item.id} {...item} />)
+  );
+}
+```
+
+### Examples
+
+```tsx
+// ActivityCard with 4 row placeholders
+<ActivityCardSkeleton rows={4} />
+
+// ProfileCard without stats grid and without action buttons
+<ProfileCardSkeleton showStats={false} showActions={false} />
+
+// ProjectCard with 5 member-avatar placeholders
+<ProjectCardSkeleton memberCount={5} />
+
+// NotificationCard with footer placeholder
+<NotificationCardSkeleton rows={3} showViewAll />
+
+// FeatureCard without footer action button
+<FeatureCardSkeleton showAction={false} />
+```
+
+> All skeletons use the `Skeleton` primitive from `ui/skeleton`, inheriting the `bg-accent animate-pulse` styling. They render plain `<div>` placeholders — no real Card/Header/Footer subcomponents — so they're cheap to render at scale.
+
+---
+
+## AI Rules
+
+- Import block components from `xertica-ui` — they are included in the root barrel.
+- Pass all data as props — never embed fetch calls inside block components.
+- Keep `maxItems` at a sensible limit (4–6) to avoid overflow in fixed-height containers.
+- For chart panels, use `ChartCard` from `xertica-ui/ui` (not a block component) with any dashboard-ready chart as `children`.
+- `FeatureCard` badge wraps to a new line when title + badge don't fit — this is intentional; do not constrain the container width to force inline layout.
+- **Always pair each card with its matching `*Skeleton` for loading states** — do not render a spinner or empty container while data fetches. The skeleton variants mirror the final layout closely, preventing layout shift when data arrives.
+- **Skeleton row counts should match the expected data count when possible** — pass `rows={maxItems}` to `ActivityCardSkeleton`/`NotificationCardSkeleton` so the placeholder height matches the loaded state.
+
+---
+
+## Related
+
+- [`Card`](./card.md) — Primitive used internally by all block components
+- [`StatsCard`](./stats-card.md) — KPI card (lives in `ui/`, not `blocks/`) — also has `StatsCardSkeleton`
+- [`Skeleton`](./skeleton.md) — Low-level pulsing placeholder primitive used by every `*Skeleton` here
+- [`Chart`](./chart.md) — `ChartCard` and dashboard-ready chart wrappers
+- [Dashboard Pattern](../patterns/dashboard.md)