# 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.