Add bq-stat-card and extend the component roadmap toward dashboard primitives

README.md

@@ -22,7 +22,7 @@ The current library covers the core component categories developers expect from
 | **Actions** | Button, Icon Button |
 | **Forms** | Input, Textarea, Select, Checkbox, Radio, Switch, Slider, Chip |
 | **Navigation** | Tabs, Accordion, Breadcrumbs, Pagination |
-| **Data Display** | Card, Badge, Avatar, Table, Divider, Empty State |
+| **Data Display** | Card, Badge, Avatar, Table, Divider, Empty State, Stat Card |
 | **Feedback** | Alert, Progress, Spinner, Skeleton, Tooltip, Toast |
 | **Overlays** | Dialog, Drawer |
 

docs/.vitepress/config.ts

@@ -53,6 +53,7 @@ export default defineConfig({
           { text: 'Skeleton', link: '/components/skeleton' },
           { text: 'Slider', link: '/components/slider' },
           { text: 'Spinner', link: '/components/spinner' },
+          { text: 'Stat Card', link: '/components/stat-card' },
           { text: 'Switch', link: '/components/switch' },
           { text: 'Table', link: '/components/table' },
           { text: 'Tabs', link: '/components/tabs' },

docs/components/index.md

@@ -11,7 +11,7 @@ This catalog gives you a complete overview of the currently available building b
 | **Actions** | `bq-button`, `bq-icon-button` |
 | **Forms** | `bq-input`, `bq-textarea`, `bq-select`, `bq-segmented-control`, `bq-checkbox`, `bq-radio`, `bq-switch`, `bq-slider`, `bq-chip` |
 | **Navigation & Disclosure** | `bq-tabs`, `bq-accordion`, `bq-breadcrumbs`, `bq-pagination` |
-| **Data Display** | `bq-card`, `bq-badge`, `bq-avatar`, `bq-table`, `bq-divider`, `bq-empty-state` |
+| **Data Display** | `bq-card`, `bq-badge`, `bq-avatar`, `bq-table`, `bq-divider`, `bq-empty-state`, `bq-stat-card` |
 | **Feedback & Loading** | `bq-alert`, `bq-progress`, `bq-spinner`, `bq-skeleton`, `bq-tooltip`, `bq-toast` |
 | **Overlays** | `bq-dialog`, `bq-drawer`, `bq-dropdown-menu` |
 
@@ -66,6 +66,7 @@ Across the component library you will find the same professional capabilities th
 | `bq-table` | Tabular datasets | Sortable columns, bordered/striped/hoverable variants, empty/loading states |
 | `bq-divider` | Visual separation of content | Horizontal/vertical orientation, label support, multiple line styles |
 | `bq-empty-state` | No-data or no-results messaging | Title, description, icon slot, action slot |
+| `bq-stat-card` | Dashboard metrics and KPI summaries | Compact metric layout, trend pill, loading skeleton, icon slot |
 
 ## Feedback & Loading
 

docs/components/stat-card.md

@@ -0,0 +1,122 @@
+# Stat Card
+
+The `bq-stat-card` component is a compact dashboard primitive for KPI summaries, analytics overviews, and settings surfaces that need a quick metric + context pairing.
+
+It is intentionally lightweight: use it when you need a polished, theme-aware metric card without introducing a full charting or dashboard framework.
+
+## Import
+
+```ts
+import '@bquery/ui/components/stat-card';
+```
+
+## Basic Usage
+
+```html
+<bq-stat-card
+  label="Monthly revenue"
+  value="$128k"
+  change="+12.4%"
+  hint="Compared with the previous 30 days."
+  trend="up"
+></bq-stat-card>
+```
+
+## With Icon Slot
+
+```html
+<bq-stat-card
+  label="Incident resolution"
+  value="94%"
+  change="-1.8%"
+  hint="SLA within the current quarter."
+  trend="down"
+>
+  <span slot="icon" aria-hidden="true">⚡</span>
+</bq-stat-card>
+```
+
+## Sizes
+
+Use `size="sm"` when the card needs to fit tighter dashboards, narrow mobile layouts, or dense admin surfaces.
+
+```html
+<bq-stat-card label="Open tickets" value="18" size="sm"></bq-stat-card>
+<bq-stat-card label="Open tickets" value="18" size="md"></bq-stat-card>
+```
+
+## Loading State
+
+When data is still loading, the component can render an internal skeleton layout while preserving accessible status text.
+
+```html
+<bq-stat-card
+  label="Active users"
+  loading
+></bq-stat-card>
+```
+
+## Additional Supporting Content
+
+The default slot can render extra supporting content such as inline badges, notes, or actions below the hint text.
+
+```html
+<bq-stat-card
+  label="Deployments"
+  value="42"
+  change="+6"
+  trend="up"
+  hint="Production deployments this week."
+>
+  <bq-badge variant="success">Healthy</bq-badge>
+</bq-stat-card>
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `label` | `string` | `''` | Short metric label shown at the top of the card. |
+| `value` | `string` | `''` | Primary value, such as a count, percentage, or formatted currency amount. |
+| `change` | `string` | `''` | Secondary comparison value, such as `+12%` or `-4`. |
+| `hint` | `string` | `''` | Supporting explanatory text shown below the value row. |
+| `trend` | `up \| down \| neutral` | `neutral` | Visual tone for the `change` pill. Invalid values fall back to `neutral`. |
+| `size` | `sm \| md` | `md` | Controls spacing and value sizing. Invalid values fall back to `md`. |
+| `loading` | `boolean` | `false` | Displays an internal loading skeleton and sets `aria-busy="true"`. |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| *(default)* | Additional supporting content rendered below the hint text. |
+| `icon` | Optional icon, avatar, or badge rendered in the top-right corner. |
+
+## CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `card` | Outer metric surface |
+| `header` | Top row containing the label and icon slot |
+| `label` | Metric label |
+| `value` | Primary metric value |
+| `change` | Trend/change pill |
+| `hint` | Supporting description |
+| `loading` | Internal loading layout wrapper |
+
+## Accessibility Notes
+
+- The outer surface uses semantic `<article>` markup.
+- `label` is connected to the card with `aria-labelledby`, and `hint` is connected with `aria-describedby`.
+- `loading` sets `aria-busy="true"` and exposes a localized screen-reader status message.
+- Keep the `change` text meaningful on its own. For example, prefer `+12.4%` or `12 fewer incidents` over a color-only status.
+
+## Localization Notes
+
+- Keep `label`, `value`, `change`, and `hint` fully localizable in the host application.
+- The built-in loading announcement uses the shared library locale, so custom locales continue to work without extra wiring.
+- Use locale-aware formatting for numbers, currencies, and percentages before passing the resulting strings to the component.
+
+## Theming Notes
+
+- The component uses shared tokens for background, border, text, success/danger emphasis, spacing, radius, and shadow.
+- Override host-level tokens for brand alignment, or target internal elements with `::part(card)`, `::part(value)`, and `::part(change)` for more specific customization.

docs/guide/architecture-roadmap.md

@@ -40,6 +40,7 @@ Reviewing mature systems such as Radix UI, shadcn/ui, Chakra UI, Mantine, Materi
 - Better **keyboard parity** across all navigation and overlay components
 - More **documentation pages for architecture, roadmap, theming, and usage patterns**
 - Continued refinement of **mobile-friendly sizing, focus behavior, and RTL-aware navigation**
+- More **dashboard and summary primitives** that help product teams build real application surfaces instead of only low-level controls
 
 ### Advanced future opportunities
 
@@ -94,9 +95,24 @@ This batch improves the library in a way that mirrors mature UI ecosystems witho
 - strengthens an existing **overlay/navigation component**,
 - and improves documentation so the library feels more like an intentional platform than a loose collection of widgets.
 
+## Latest High-Value Batch
+
+This follow-up batch focuses on a missing dashboard primitive that appears consistently across mature design systems and admin-oriented UI libraries:
+
+1. **New `bq-stat-card` component**
+   - purpose-built for KPI summaries, health metrics, and compact dashboard cards,
+   - supports loading state, trend styling, icon composition, and mobile-friendly compact sizing,
+   - stays aligned with the existing token system and localization strategy.
+
+2. **Documentation updates**
+   - new `bq-stat-card` reference page,
+   - updated component catalog and sidebar coverage,
+   - refreshed roadmap language to call out dashboard/data-summary primitives as a current priority.
+
 ## Recommended Next Steps
 
 - Add a composable **combobox / rich select** next.
 - Expand **table recipes** and column-control patterns.
 - Add more **layout and workspace primitives** for responsive app shells and settings pages.
 - Continue auditing older components for shared size/variant/state consistency.
+- Build on `bq-stat-card` with companion dashboard patterns such as activity feeds, metric groups, and master-detail analytics layouts.

src/components/index.ts

@@ -25,6 +25,7 @@ import './segmented-control/BqSegmentedControl.js';
 import './skeleton/BqSkeleton.js';
 import './slider/BqSlider.js';
 import './spinner/BqSpinner.js';
+import './stat-card/BqStatCard.js';
 import './switch/BqSwitch.js';
 import './table/BqTable.js';
 import './tabs/BqTabs.js';