# TakafulHub component library

Use semantic components to express information priority. Do not use a generic `Card` when a purpose-built component fits.

| Component | Use for | Avoid for |
| --- | --- | --- |
| `KpiCard` | a concise numeric/account metric | narrative summaries or primary tasks |
| `ReadinessCard` | eligibility, verification, account state | generic notices |
| `ActionCard` | one dominant next action | a grid of unrelated actions |
| `QuickActionTile` | small routed task shortcuts | destructive actions |
| `SummaryCard` + `DetailSummary` | structured account/context information | metrics |
| `CommerceCard` | selectable products and packages | checkout/business logic |
| `TableShell` + `FilterToolbar` | data tables with title, filters and pagination | a small static list |
| `SettingsSection` | routine settings forms | destructive actions |
| `DangerZone` | isolated destructive settings | routine save actions |
| `ActivityList` | narrative, chronological history | tabular data |
| `EmptyState` | first use, no results/history, blocked, unavailable | a loading state |

Card hierarchy: `ActionCard` is level 1 (primary task), `KpiCard`/`SummaryCard`/`TableShell` are level 2, `ReadinessCard` and muted `Card` are level 3. Use unframed grouped content when no surface is needed.

All interactive components preserve native links/buttons and `focus-visible` treatment. Toolbars stack on mobile; tiles retain a minimum tap target; summaries collapse to one column.

## Component ownership

`SettingsSection` owns its H2, description, outer surface, padding, and optional footer; its children provide fields and inline feedback only. `TableShell` owns the table title, description, result count, toolbar/filter zones, and pagination area. `ActionCard` owns the eyebrow, title, description, and primary-action region. `CommerceCard` owns product hierarchy and selection state; callers supply feature rows and CTA only. `EmptyState` owns its centered empty-content region and actions, and must not be nested inside a second empty/card wrapper without a structural reason.

```vue
<CommerceCard title="100 Lead Credits" price="RM100" recommended>
  <template #features><li>Available for eligible distribution</li></template>
  <template #action="{ disabled }"><Button :disabled="disabled">Select package</Button></template>
</CommerceCard>
```