# AhaSlides Design System

> The single source of truth for AhaSlides UI, generated from one contract per component.
> Version: 0.52.0 — changelog: https://ahaslides-product.github.io/ahaslides-design/CHANGELOG.md
> Registry:  GitHub Packages (https://npm.pkg.github.com) — needs a GitHub token with read:packages.
> Configure once in .npmrc:  @ahaslides-product:registry=https://npm.pkg.github.com
> Install:  npm i @ahaslides-product/design
> Import the token layer once at the app root:  import '@ahaslides-product/design/tokens.css'
> Then import a component by subpath, e.g.  import '@ahaslides-product/design/aha-button'
> No build step? One tag registers every element — CDN / no-build pages:
>   <script type="module" src="https://cdn.jsdelivr.net/gh/ahaslides-product/ahaslides-design@master/lib/all.js"></script>
>   (loads the whole set; for bundled apps prefer per-element imports so unused elements tree-shake out)
>
> ⚑ Before you build: this is the OFFICIAL AhaSlides anti-slop tool. Read anti-slop.md and
>   run the binary judge for your surface — build → self-judge (PASS/FAIL each) → fix → repeat.
>   https://ahaslides-product.github.io/ahaslides-design/anti-slop.md         the anti-slop loop + per-surface rules (read FIRST)
>   https://ahaslides-product.github.io/ahaslides-design/anti-slop.agent.json machine feed: loop + per-surface { rules, criteria, selfCheck }
>
> Feeds (absolute URLs, fetch directly):
>   https://ahaslides-product.github.io/ahaslides-design/llms.txt          this index
>   https://ahaslides-product.github.io/ahaslides-design/llms-full.txt     every component, full docs
>   https://ahaslides-product.github.io/ahaslides-design/design.md         machine-readable visual language + tokens
>   https://ahaslides-product.github.io/ahaslides-design/CHANGELOG.md      version history — what changed per release
>   https://ahaslides-product.github.io/ahaslides-design/variables.css     the --aha-* token layer
>   https://ahaslides-product.github.io/ahaslides-design/<slug>.agent.json per-component machine feed (props, tokens, spec, opinion, install, snippets)

## Components

- [Add Item Button](add-item-button/add-item-button.md) — leaf-lit — The full-width "+ Add" affordance that sits under a settings list (OptionRow / QuestionList) — a dashed, tertiary add row that appends a new item.
- [Alert](alert/alert.md) — leaf-lit — An inline, contextual feedback banner — info, success, warning, error, or branding — in regular/small sizes, with an optional full-width banner mode and a trailing action.
- [AutoComplete](autocomplete/autocomplete.md) — composite-antd — Free-text input with suggestions as you type — search boxes, tag entry, known-but-open fields — rendered through the shared AutoComplete.
- [Avatar](avatar/avatar.md) — leaf-lit — Represent a person or entity with a photo, initials, or an icon — solo or in a stacked group.
- [Badge](badge/badge.md) — leaf-lit — A small count or status marker — notification counts, unread dots, a standalone status label.
- [Breadcrumb](breadcrumb/breadcrumb.md) — leaf-lit — A trail of ancestor links ending in the current page — and, at size=page-title, the page heading itself (there is no separate page-title component).
- [Button](button/button.md) — leaf-lit — Trigger an action or navigation — the primary interactive control.
- [Card](card/card.md) — leaf-lit — A surface that groups related content — cover, title, body and footer actions — in default/small size, bordered or flat, with a hover lift and a loading skeleton.
- [Card select](card-select/card-select.md) — leaf-lit — Single-select as an icon+label card grid — pick one of N options each shown as its own visual card, with roving radiogroup keyboard navigation. Two layouts: labelled tiles (stretch to fill `columns`) or compact 44px icon-only squares.
- [Carousel](carousel/carousel.md) — composite-antd — A swipeable set of slides — onboarding, a feature tour, a gallery — rendered through the shared Carousel.
- [Checkbox](checkbox/checkbox.md) — leaf-lit — Let a user turn one or more independent options on or off.
- [Collapse](collapse/collapse.md) — leaf-lit — A single expandable panel that hides secondary content until asked.
- [Color picker](color-picker/color-picker.md) — leaf-lit — Pick a colour from a selectable palette of presets.
- [Counted input](counted-input/counted-input.md) — leaf-lit — A single-line settings field whose character counter shows only while the field is focused and is hidden at rest — the shared CountedInput pattern for option/answer text.
- [Counted textarea](counted-textarea/counted-textarea.md) — leaf-lit — The multi-line settings field — a CountedInput that wraps to several lines, grows from minRows to maxRows then scrolls, with the same focus-only character counter.
- [CSAT](csat/csat.md) — leaf-lit — The shared thumbs up/down satisfaction prompt — the one CSAT control, not a bespoke rating.
- [DatePicker](datepicker/datepicker.md) — composite-antd — Pick a date or a date range from a calendar — schedules, deadlines, filters — rendered through the shared DatePicker.
- [Descriptions](descriptions/descriptions.md) — leaf-lit — A read-only label/value grid summarising one entity's fields — N columns, bordered or plain, horizontal or vertical, with per-item span.
- [Divider](divider/divider.md) — leaf-lit — A thin rule that separates blocks of content — full-width, with a label, or a vertical hairline.
- [Drawer](drawer/drawer.md) — composite-antd — A side panel that slides in for a longer edit or detail view — rendered through the shared Drawer.
- [Dropdown](dropdown/dropdown.md) — leaf-lit — A trigger button that reveals a floating overlay of actions — with leading icons, dividers, disabled rows and a red danger action.
- [Empty](empty/empty.md) — leaf-lit — The placeholder for a surface that has no data yet.
- [Flex](flex/flex.md) — leaf-lit — A flexbox container with the DS spacing scale baked into `gap` — direction, align, justify, wrap.
- [Form](form/form.md) — composite-antd — A labelled, validated set of fields — sign-in, settings, create dialogs — rendered through the shared Form.
- [Grid](grid/grid.md) — leaf-lit — A CSS-grid container — a fixed column count or a responsive auto-fit, with the DS gutter scale, track justify/align, and a responsive collapse.
- [Icon](icon/icon.md) — leaf-lit — One glyph set, called by name — 259 icons imported from Figma, rendered by the shared <aha-icon>, never inline SVG.
- [Illustration](illustration/illustration.md) — leaf-lit — One spot-art set, called by name — 20 multi-colour illustrations imported from Figma, rendered by the shared <aha-illustration>, never inline SVG.
- [Image](image/image.md) — leaf-lit — A framed image with rounded corners, a hover preview mask, a loading placeholder and a broken-src fallback.
- [Image action button](image-action-button/image-action-button.md) — leaf-lit — The compact per-option image control — an image icon button with empty / loading / thumbnail states and a Change/Edit/Delete menu; it emits intents, the host owns the modals.
- [Image dropzone](image-dropzone/image-dropzone.md) — leaf-lit — The full-width settings image field where the image IS the field — a dashed upload card with empty / loading / filled states and a Change/Edit/Delete overlay; it emits intents, the host owns the modals (SETTINGS-44).
- [Info box](info-box/info-box.md) — leaf-lit — A settings-only tinted callout in four tones (information / success / warning / error), optionally dismissible — a bespoke component, not Ant Alert.
- [Input](input/input.md) — leaf-lit — A single-line text field — names, search, numbers, short free text — with sizes, error/warning status, affixes, a clear ✕ and a password reveal.
- [InputNumber](input-number/input-number.md) — composite-antd — Enter a number with steppers, min/max and precision — quantities, limits, durations — rendered through the shared InputNumber.
- [List](list/list.md) — leaf-lit — A vertical list of uniform rows — avatar + title/description meta and trailing actions, with size, bordered and split options.
- [Loader](aha-loader/aha-loader.md) — leaf-lit — The full-surface branded loading screen shown while a new environment boots — workspace → editor, or editor → presenting.
- [Menu](menu/menu.md) — leaf-lit — A list of selectable options — a side nav, a settings list, an overflow menu — with icons, groups, submenus and danger actions.
- [Modal](modal/modal.md) — composite-antd — A focused, blocking dialog in two types — a Confirmation (yes/no decision) and an Action (a task surface) — rendered through the shared Modal.
- [Mode field](mode-field/mode-field.md) — leaf-lit — A labelled field with an inline exclusive mode control whose body swaps in place — the settings field for a control that has two-or-more mutually-exclusive modes.
- [Notification](notification/notification.md) — composite-antd — A richer, stacking message with a title + description — rendered through antd's notification API.
- [Number with unit](number-with-unit/number-with-unit.md) — leaf-lit — A fixed-width digit input with the unit written IN FULL inline (rendered exactly as passed — "seconds", "points" — muted grey), a hover ▲/▼ stepper, a hard digit cap, clamp-on-change, and an error line — the settings field for a number that carries a unit.
- [Numbered item](numbered-item/numbered-item.md) — leaf-lit — The numbered wrapper for a repeatable composite item — a grey card with a muted number chip, a "<Label> N" header, a hover delete, and a body slot (SETTINGS-43).
- [Option row](option-row/option-row.md) — leaf-lit — The repeatable option/answer row — one bordered row with an inside drag handle, a borderless counted textarea, an optional correct toggle (circle or square) and per-option image, and a floating hover delete; marking correct paints the whole card success-green (SETTINGS-20/34/23/39).
- [Pagination](pagination/pagination.md) — leaf-lit — A page selector for a paged list or table — prev / numbered pages with ellipsis / next; two sizes, a simple mode, and a whole-control disabled state.
- [Paywall](paywall/paywall.md) — leaf-lit — Wrap a pro-gated affordance; the shared upsell renders itself — the crown upgrade mark, title, one-sentence body, the fixed unlock line, and Upgrade + See all plans CTAs are baked in.
- [Popconfirm](popconfirm/popconfirm.md) — composite-antd — A lightweight inline confirmation popover anchored to the trigger — confirm/cancel a low-risk action.
- [Popover](popover/popover.md) — leaf-lit — Anchor a floating card of rich content — a title, a body, and an optional arrow — to a trigger.
- [Progress](progress/progress.md) — leaf-lit — A determinate progress indicator — completion, upload, a quiz timer — as a line, segmented steps, or a circle.
- [QR code](qr-code/qr-code.md) — composite-antd — A scannable QR code — a join link, a deck URL, a Wi-Fi handoff — rendered through the shared QRCode.
- [Question list](question-list/question-list.md) — leaf-lit — An editable list of collapsible questions — each a prompt field plus its OptionRow choices — with a full-width "+ Add question" that disables at max; composes NumberedItem + OptionRow (SETTINGS-31/36).
- [Radio](radio/radio.md) — leaf-lit — Pick exactly one option from a small mutually-exclusive set, all shown at once.
- [Rate](rate/rate.md) — leaf-lit — Capture or display a score as a row of stars.
- [Result](result/result.md) — leaf-lit — A full-block outcome state — success, error, info, warning, 404, 403 or 500 — with an icon, title and actions.
- [Screen heading](screen-heading/screen-heading.md) — leaf-lit — A product page header — a title/greeting or a breadcrumb trail on the left, action buttons on the right, responsive across desktop / tablet / phone.
- [Section Header](section-header/section-header.md) — leaf-lit — A settings GROUP header — the hierarchy parent that a stack of setting rows sits under: a noun-phrase label, an optional "?" help, and a right-aligned action slot (a master switch, a count, a link).
- [Segmented](segmented/segmented.md) — leaf-lit — Switch between a few mutually-exclusive options inline — labels, leading icons, or icon-only, in three sizes.
- [Select](select/select.md) — composite-antd — Pick one value (or several) from a known set — with type-to-search — rendered through the shared Select.
- [Select field](select-field/select-field.md) — leaf-lit — Pick one value from a short, known set — a lightweight native-select-backed field that embeds anywhere.
- [Setting group](setting-group/setting-group.md) — leaf-lit — The settings GROUP container — an optional semibold header (with a "?" help and an action slot) over a column of rows — that bakes in the panel spacing scale so gaps come out right automatically.
- [Setting Row](setting-row/setting-row.md) — leaf-lit — ONE setting — a label (with an optional "?" help) plus a slotted DS control; inline (label-left / control-right) by default, or stacked (label above, control full-width) for a wide control.
- [Settings list](settings-list/settings-list.md) — leaf-lit — A schema-driven group of settings rows — semibold label left (with a "?" help tooltip), control right — reusing existing DS controls.
- [Skeleton](skeleton/skeleton.md) — leaf-lit — A greyed placeholder that holds a component's shape while its content loads.
- [Slider](slider/slider.md) — composite-antd — Drag to set a value across a known range — volume, opacity, thresholds, ranges — rendered through the shared Slider.
- [Space](space/space.md) — leaf-lit — An even, DS-scale gap between a small inline set of items — buttons, tags, inline controls.
- [Spin](spin/spin.md) — leaf-lit — A brand-coloured spinner for an indeterminate wait — loading a page, a panel, or results.
- [Statistic](statistic/statistic.md) — leaf-lit — A single headline number with a caption, prefix/suffix (text or icon), precision, trend colour and a loading skeleton.
- [Status badge](status-badge/status-badge.md) — leaf-lit — A glanceable lifecycle pill for a domain object — draft, published, closed, archived, active, inactive.
- [Steps](steps/steps.md) — composite-antd — Show progress through a sequence of ordered stages — wizards, onboarding, checkouts — rendered through the shared Steps.
- [Sub setting group](sub-setting-group/sub-setting-group.md) — leaf-lit — The dependent (child) settings wrapper — indents a cluster of sub-settings under one parent toggle with a tight gap, spacing only (no border, no card).
- [Switch](switch/switch.md) — leaf-lit — A single setting that takes effect immediately — on or off.
- [Table](table/table.md) — composite-antd — A data grid — results, leaderboard, participant/admin list — rendered through the shared DataTable.
- [Tabs](tabs/tabs.md) — leaf-lit — Switch between sibling content panels from a tab bar — line, primary or card, in two sizes, with per-tab icons.
- [Tag](tag/tag.md) — leaf-lit — A small label chip for a category, keyword, or state — filled or bordered, with an icon, a dismiss ×, or a checkable toggle.
- [Textarea](textarea/textarea.md) — composite-antd — Enter multi-line free text — descriptions, messages, notes — with autosize and char count, rendered through the shared Textarea.
- [TimePicker](time-picker/time-picker.md) — composite-antd — Pick a time of day from scrolling hour/minute/second columns — schedules, reminders, durations — rendered through the shared TimePicker.
- [Toast](toast/toast.md) — composite-antd — A brief, auto-dismissing confirmation of an action — rendered through antd's message API.
- [Tooltip](tooltip/tooltip.md) — leaf-lit — A short, transient hint shown on hover or focus of its trigger.
- [Upload](uploader/uploader.md) — leaf-lit — Select files by clicking a drop zone or dragging onto it — then manage them as rows or picture tiles with per-item state.
- [User info](user-info/user-info.md) — leaf-lit — A person/identity row — an avatar next to a name, with an optional email underneath.