# Design System Components

A lightweight index for quickly finding the right component and its import path. All import paths are relative to `src/components/design-system/`. Prop details live in each component's `types.ts` with JSDoc comments.

---

## Table of Contents

- [Accordion](#accordion)
- [Alert](#alert)
- [Avatar](#avatar)
- [AvatarGroup](#avatargroup)
- [Badge](#badge)
- [Breadcrumbs](#breadcrumbs)
- [ButtonGroup](#buttongroup)
- [Buttons/Button](#buttonsbutton)
- [Buttons/Fab](#buttonsfab)
- [Buttons/IconButton](#buttonsiconbutton)
- [CardContainer](#cardcontainer)
- [Charts/BarChart](#chartsbbarchart)
- [Charts/DonutChart](#chartsdonutchart)
- [Charts/HeatmapChart](#chartsheatmapchart)
- [Charts/LineChart](#chartslinechart)
- [Checkbox/Checkbox](#checkboxcheckbox)
- [Checkbox/CheckboxBase](#checkboxcheckboxbase)
- [Chip](#chip)
- [Coachmark](#coachmark)
- [Dialog](#dialog)
- [Divider](#divider)
- [Drawer](#drawer)
- [Dropdown](#dropdown)
- [FileCard](#filecard)
- [Header/Home](#headerhome)
- [Header/Social](#headersocial)
- [Header/TaskFocus](#headertaskfocus)
- [HumandLogo](#humandlogo)
- [AI/Buttons/AIButton](#aibuttonsaibutton)
- [AI/Buttons/AIFab](#aibuttonsaifab)
- [AI/Buttons/AIIconButton](#aibuttonsaiiconbutton)
- [AI/AISkeleton](#aiaiskeleton)
- [AI/AISpinner](#aiaispinner)
- [IconSelector](#iconselector)
- [Inputs/Autocomplete](#inputsautocomplete)
- [Inputs/Classic](#inputsclassic)
- [Inputs/DatePicker](#inputsdatepicker)
- [Inputs/Money](#inputsmoney)
- [Inputs/OTP](#inputsotp)
- [Inputs/Pagination](#inputspagination)
- [Inputs/Password](#inputspassword)
- [Inputs/Phone](#inputsphone)
- [Inputs/RangeDatePicker](#inputsrangedatepicker)
- [Inputs/Search](#inputssearch)
- [Inputs/Select](#inputsselect)
- [Inputs/TextArea](#inputstextarea)
- [Link](#link)
- [List](#list)
- [Menu](#menu)
- [Pills](#pills)
- [ProgressIndicators/ProgressBar](#progressindicatorsprogressbar)
- [ProgressIndicators/Spinner](#progressindicatorsspinner)
- [RadioButton/RadioButton](#radiobuttonradiobutton)
- [RadioButton/RadioBase](#radiobuttonradiobase)
- [Rating](#rating)
- [Sidebar](#sidebar)
- [Skeleton](#skeleton)
- [Snackbar](#snackbar)
- [StateCard](#statecard)
- [Stepper](#stepper)
- [Switcher](#switcher)
- [Table](#table)
- [Tabs](#tabs)
- [Title](#title)
- [Toggle](#toggle)
- [Tooltip](#tooltip)
- [Typography](#typography)
- [Uploader](#uploader)
- [Wizard](#wizard)

---

## Accordion

- **Import:** `./Accordion`
- **Description:** Collapsible section with a header (title, caption, avatar, pill, menu) and expandable body content.

---

## Alert

- **Import:** `./Alert`
- **Description:** Inline feedback banner for success, error, warning, info, or highlight messages — supports close button, loading state, and an inline action link.

---

## Avatar

- **Import:** `./Avatar`
- **Description:** Displays a user avatar as an image, initials, or icon, with optional badge overlay.

---

## AvatarGroup

- **Import:** `./AvatarGroup`
- **Description:** Renders a stacked row of up to 4 avatars with an overflow count, useful for showing assignees or participants.

---

## Badge

- **Import:** `./Badge`
- **Description:** Overlays a numeric or dot badge on any child element (e.g. notification counts on icons).

---

## Breadcrumbs

- **Import:** `./Breadcrumbs`
- **Description:** Navigation trail of clickable links showing the current page hierarchy.

---

## ButtonGroup

- **Import:** `./ButtonGroup`
- **Description:** A segmented control where one option can be selected at a time from a list of labels (e.g. Week / Month / Year filters).

---

## Buttons/Button

- **Import:** `./Buttons/Button`
- **Description:** Primary action button with `primary`, `secondary`, and `tertiary` variants and built-in loading state (wraps MUI `LoadingButton`).

---

## Buttons/Fab

- **Import:** `./Buttons/Fab`
- **Description:** Floating action button for a single prominent action, typically fixed in a corner.

---

## Buttons/IconButton

- **Import:** `./Buttons/IconButton`
- **Description:** Icon-only button with `primary`, `secondary`, `tertiary`, `tertiary-filled`, `success`, and `error` variants.

---

## CardContainer

- **Import:** `./CardContainer`
- **Description:** Styled surface container with optional shadow, badge, header image, footer actions, and click handler.

---

## Charts/BarChart

- **Import:** `./Charts/BarChart`
- **Description:** Bar chart wrapper around `react-chartjs-2` for rendering categorical comparisons.

---

## Charts/DonutChart

- **Import:** `./Charts/DonutChart`
- **Description:** Donut/doughnut chart wrapper around `react-chartjs-2` for showing part-to-whole relationships.

---

## Charts/HeatmapChart

- **Import:** `./Charts/HeatmapChart`
- **Description:** Grid-based heatmap that accepts a 2D array of colors with optional axis labels and a render-prop overlay.

---

## Charts/LineChart

- **Import:** `./Charts/LineChart`
- **Description:** Line chart wrapper around `react-chartjs-2` for visualizing trends over time.

---

## Checkbox/Checkbox

- **Import:** `./Checkbox/Checkbox`
- **Description:** Checkbox with label, description, and error state for use in forms or standalone selection.
- **Form variant:** `./Checkbox/Checkbox/form`

---

## Checkbox/CheckboxBase

- **Import:** `./Checkbox/CheckboxBase`
- **Description:** Low-level checkbox primitive without any label — use when building custom checkbox layouts.

---

## Chip

- **Import:** `./Chip`
- **Description:** Compact tag element that can be selected, clicked, or deleted — suited for filters and multi-value displays.

---

## Coachmark

- **Import:** `./Coachmark`
- **Description:** Multi-step tooltip overlay anchored to DOM elements for guided onboarding tours.

---

## Dialog

- **Import:** `./Dialog`
- **Description:** Modal dialog for confirmations and short forms, with title, body, primary/secondary actions, and optional footer info text.
- **Notes:** Always use via the Dialog layer (`src/components/layers/Dialogs/`) — do not implement ad-hoc usages of this component directly.

---

## Divider

- **Import:** `./Divider`
- **Description:** Horizontal or vertical separator line (re-exports MUI `Divider`).

---

## Drawer

- **Import:** `./Drawer`
- **Description:** Side panel for detail views and forms, with support for small/medium/large sizes, dual-pane layout, custom footer, and an optional task-focus fullscreen mode.
- **Notes:** Always use via the Drawers layer (`src/components/layers/Drawers/`) — do not implement ad-hoc usages of this component directly.

---

## Dropdown

- **Import:** `./Dropdown`
- **Description:** Button that opens a positioned menu of actions — use instead of `Menu` when you need a built-in trigger button.

---

## FileCard

- **Import:** `./FileCard`
- **Description:** Displays a single file's status (default, uploading, success, error) with optional download, re-upload, and remove actions.

---

## Header/Home

- **Import:** `./Header/Home`
- **Description:** Main application header with logo, hamburger menu, notifications, language switcher, support link, and user avatar popover.

---

## Header/Social

- **Import:** `./Header/Social`
- **Description:** Social-variant application header with logo, hamburger menu, notifications, language switcher, support link, and a user avatar — similar to `Header/Home` but accepts avatar props directly instead of a popover.

---

## Header/TaskFocus

- **Import:** `./Header/TaskFocus`
- **Description:** Condensed header for task/detail views with title, status pill, up to 2 primary actions, and an overflow actions menu.

---

## HumandLogo

- **Import:** `./HumandLogo`
- **Description:** Humand brand logo as an inline SVG, theme-aware by default (navy in light, white in dark) — override via `style.color`; pass `title` for an accessible label.

---

## AI/Buttons/AIButton

- **Import:** `./AI/Buttons/AIButton`
- **Description:** AI rebrand of `Buttons/Button` (same props/types) with `primary` (brand→violet gradient fill), `secondary` (gradient border + traveling glow), and `tertiary` variants, `small`/`large` sizes (default `large`), a configurable leading AI icon (`sparkles` / `ai-pencil` / `ai-photo`), and an interactive progress/stop state (`loading` + `onStop`). The primary gradient flows continuously and the secondary border glow runs continuously (the sparkle icon twinkles on hover). Animations pause when disabled. Theme-aware (light/dark) and respects `prefers-reduced-motion`.

---

## AI/Buttons/AIFab

- **Import:** `./AI/Buttons/AIFab`
- **Description:** AI rebrand of `Buttons/Fab` (same props/types) — a primary gradient pill with a leading AI icon, label, and optional trailing icon (e.g. a plus), in `small`/`large` sizes (default `large`), with an interactive progress/stop state (`loading` + `onStop`). Use only in mini apps, never as a secondary action.

---

## AI/Buttons/AIIconButton

- **Import:** `./AI/Buttons/AIIconButton`
- **Description:** AI rebrand of `Buttons/IconButton` (same props/types), icon-only (the "IconOnly" set), with `primary`/`secondary`/`tertiary` variants, `small`/`large` sizes (default `large`), a configurable AI icon (`sparkles` / `ai-pencil` / `ai-photo`), and an interactive progress/stop state (`loading` + `onStop`). The primary gradient flows continuously and the secondary border glow runs continuously. Animations pause when disabled. Pass an `aria-label` for accessibility.

---

## AI/AISkeleton

- **Import:** `./AI/AISkeleton`
- **Description:** AI-styled loading placeholder that swaps to `children` when `isLoading` is false — same API as `Skeleton`, with a left-to-right shimmer sweep and a centered `AISpinner` watermark. Supports text, rectangular, circular, and rounded variants and is theme-aware (light/dark).

---

## AI/AISpinner

- **Import:** `./AI/AISpinner`
- **Description:** AI-styled loading indicator — an inline sparkles icon whose three parts fade independently for an organic twinkle. Theme-aware (Brand/900 in light, Text/Neutral/Inverted in dark), sized via `size`, and respects `prefers-reduced-motion`.

---

## IconSelector

- **Import:** `./IconSelector`
- **Description:** Trigger button (icon or text) that opens a popover picker for emojis and/or GIFs.

---

## Inputs/Autocomplete

- **Import:** `./Inputs/Autocomplete`
- **Description:** Searchable single or multi-select dropdown with server-side filtering, infinite scroll, virtualization, and create-option support.
- **Form variant:** `./Inputs/Autocomplete/form`

---

## Inputs/Classic

- **Import:** `./Inputs/Classic`
- **Description:** Standard text input with label, helper text, error state, character counter, and optional start adornment.
- **Form variant:** `./Inputs/Classic/form`

---

## Inputs/DatePicker

- **Import:** `./Inputs/DatePicker`
- **Description:** Calendar date picker with min/max constraints, timezone support, and clearable value.
- **Form variant:** `./Inputs/DatePicker/form`

---

## Inputs/Money

- **Import:** `./Inputs/Money`
- **Description:** Numeric amount input with optional currency selector for monetary values.
- **Form variant:** `./Inputs/Money/form`

---

## Inputs/OTP

- **Import:** `./Inputs/OTP`
- **Description:** Split-digit input for one-time password / verification codes, with configurable length and `onComplete` callback.
- **Form variant:** `./Inputs/OTP/form`

---

## Inputs/Pagination

- **Import:** `./Inputs/Pagination`
- **Description:** Page navigation control with optional rows-per-page selector (`type="changer"`).
- **Form variant:** `./Inputs/Pagination/form`

---

## Inputs/Password

- **Import:** `./Inputs/Password`
- **Description:** Password text input with a show/hide toggle — only available as a form variant.
- **Form variant:** `./Inputs/Password/form`

---

## Inputs/Phone

- **Import:** `./Inputs/Phone`
- **Description:** Phone number input with country-code selector and E.164 value format.
- **Form variant:** `./Inputs/Phone/form`

---

## Inputs/RangeDatePicker

- **Import:** `./Inputs/RangeDatePicker`
- **Description:** Date range picker for selecting a start and end date in a single input.
- **Form variant:** `./Inputs/RangeDatePicker/form`

---

## Inputs/Search

- **Import:** `./Inputs/Search`
- **Description:** Search text input with loading indicator and `classic` / `custom` display variants.
- **Form variant:** `./Inputs/Search/form`

---

## Inputs/Select

- **Import:** `./Inputs/Select`
- **Description:** Simple dropdown select for choosing one option from a flat list, with custom option renderer support.
- **Form variant:** `./Inputs/Select/form`
- **Notes:** Prefer `Inputs/Autocomplete` when the list is long or needs search/filtering.

---

## Inputs/TextArea

- **Import:** `./Inputs/TextArea`
- **Description:** Rich text editor powered by TipTap with a configurable toolbar (bold, lists, tables, emoji, embed HTML).
- **Form variant:** `./Inputs/TextArea/form`

---

## Link

- **Import:** `./Link`
- **Description:** Styled anchor element with optional external-link icon and disabled state (extends MUI `Link`).

---

## List

- **Import:** `./List`
- **Description:** Thin wrapper around MUI `List` — use with the custom `ListItem` and `ListItemSkeleton` sub-components below.

### List/ListItem

- **Import:** `./List/components/ListItem`
- **Description:** Rich list row with avatar, title/description text, side content (pill, text, or avatar group), and up to two action icon buttons.

### List/ListItemSkeleton

- **Import:** `./List/components/ListItemSkeleton`
- **Description:** Skeleton placeholder for a list row — use while the list data is loading.

---

## Menu

- **Import:** `./Menu`
- **Description:** Positioned dropdown menu anchored to an element, with optional header and footer slots.
- **Notes:** Always use via the Menus layer (`src/components/layers/Menus/`) — do not implement ad-hoc usages of this component directly. Use `Dropdown` when you also need a built-in trigger button.

### Menu/MenuItem

- **Import:** `./Menu/components/MenuItem`
- **Description:** Individual option inside a `Menu`, with optional divider below and support for disabled/selected states.

---

## Pills

- **Import:** `./Pills`
- **Description:** Small colored status label for conveying state (error, success, warning, info, highlight, neutral, disabled).

---

## ProgressIndicators/ProgressBar

- **Import:** `./ProgressIndicators/ProgressBar`
- **Description:** Linear progress bar with optional percentage label, title, description, and determinate/indeterminate modes.

---

## ProgressIndicators/Spinner

- **Import:** `./ProgressIndicators/Spinner`
- **Description:** Circular loading indicator with optional centering and dark-background variant.

---

## RadioButton/RadioButton

- **Import:** `./RadioButton/RadioButton`
- **Description:** Radio option with label, description, extra data, and avatar — use inside a radio group.
- **Form variant:** `./RadioButton/RadioButton/form`

---

## RadioButton/RadioBase

- **Import:** `./RadioButton/RadioBase`
- **Description:** Low-level radio input primitive without label — use when building custom radio layouts.

---

## Rating

- **Import:** `./Rating`
- **Description:** Star rating input with configurable max stars, read-only mode, and error/helper text.
- **Form variant:** `./Rating/form`

---

## Sidebar

- **Import:** `./Sidebar`
- **Description:** Application navigation sidebar with collapsible sections, nested sub-items, notification badges, and a "new" indicator per item.

---

## Skeleton

- **Import:** `./Skeleton`
- **Description:** Loading placeholder that swaps to `children` when `isLoading` is false — supports text, rectangular, circular, and rounded variants.

---

## Snackbar

- **Import:** `./Snackbar`
- **Description:** Toast notification with success/error/warning/info variants, auto-hide duration, and an optional cancel action.

---

## StateCard

- **Import:** `./StateCard`
- **Description:** Full-area state illustration card for empty, error, success, or offline states with primary/secondary call-to-action buttons.

---

## Stepper

- **Import:** `./Stepper`
- **Description:** Horizontal step indicator showing current, completed, and error steps for multi-step flows.

### Stepper/Step

- **Import:** `./Stepper/components/Step`
- **Description:** Individual step node inside a `Stepper`, with current, completed, last, and error visual states.

---

## Switcher

- **Import:** `./Switcher`
- **Description:** Toggle switch with optional title, description, and a tooltip shown when disabled.
- **Form variant:** `./Switcher/form`

---

## Table

- **Import:** `./Table`
- **Description:** Thin wrapper around MUI `Table` — compose with the custom sub-components below.

### Table/TableContainer

- **Import:** `./Table/components/TableContainer`
- **Description:** Outer scroll container for the table — use as the root wrapper.

### Table/TableHead

- **Import:** `./Table/components/TableHead`
- **Description:** Table header section — wrap header `TableRow` elements inside this.

### Table/TableBody

- **Import:** `./Table/components/TableBody`
- **Description:** Table body section — wrap data `TableRow` elements inside this.

### Table/TableRow

- **Import:** `./Table/components/TableRow`
- **Description:** Table row with optional collapsible detail panel rendered via `renderDetail` render prop, and a `headerRow` variant for header styling.

### Table/TableCell

- **Import:** `./Table/components/TableCell`
- **Description:** Table cell with `headerCell`, `actionable`, `selectionCell`, and `collapsableCell` variants, plus an optional inline tooltip.

### Table/TableToolbar

- **Import:** `./Table/components/TableToolbar`
- **Description:** Toolbar area above the table for search, filters, and bulk actions — accepts any children via a flex `Stack`.

### Table/TableLoader

- **Import:** `./Table/components/TableLoader`
- **Description:** "Load more / scroll to top" footer row — shows loaded vs total count and triggers `onLoadMore` or `onScrollToTop`.
- **Notes:** Use this as the pagination mechanism for tables — do not implement ad-hoc pagination controls.

---

## Tabs

- **Import:** `./Tabs`
- **Description:** Horizontal tab bar for switching between views, with optional badge indicators per tab.

---

## Title

- **Import:** `./Title`
- **Description:** Structured heading block with an optional copetin (super-label), main title, description, date, and XL/L/M/S size variants.

---

## Toggle

- **Import:** `./Toggle`
- **Description:** Minimal boolean toggle (no label) — use `Switcher` when you need accompanying title/description text.

---

## Tooltip

- **Import:** `./Tooltip`
- **Description:** Hover tooltip with title and description slots, configurable placement, delay, and controlled visibility.

---

## Typography

- **Import:** `./Typography`
- **Description:** Text rendering component using the design system's type scale (re-exports/extends MUI `Typography`).

---

## Uploader

- **Import:** `./Uploader`
- **Description:** Drag-and-drop file upload area that manages a list of `FileCard` items with type restrictions, file-size limits, and a custom async upload handler.
- **Form variant:** `./Uploader/form`

---

## Wizard

- **Import:** `./Wizard`
- **Description:** Multi-stage progress navigator (up to 5 stages, each with sub-stages) for complex multi-step workflows — more powerful than `Stepper` when sub-steps are needed.

### Wizard/Stage

- **Import:** `./Wizard/components/Stage`
- **Description:** Individual stage node inside a `Wizard`, with sub-stage list, error indicators per sub-stage, and click callbacks for both stage and sub-stage navigation.
