@central-design-system/skills 4.0.0-alpha.6

package/skills/cds-builder/references/component-decision-tree.md

@@ -0,0 +1,310 @@
+# CDS 4 component decision tree
+
+> Generated from component documentation pages by `bun run generate:skill`. Do not edit manually.
+> Handwritten head-to-head cases are at the end of the file.
+
+Selection rules:
+
+1. **Pick the narrowest component that fits.** If `CdsSelect` exists, don't
+   hand-build a dropdown out of `CdsSurface` and `CdsList`.
+2. **Don't invent a component that doesn't exist.** Check the list below: if the
+   task isn't covered, assemble it from existing atoms and tell the user.
+3. **Check the contract.** Once you pick a component, open its `api.md` and use
+   the real props, not guesses.
+4. The "See also" line points to a neighboring component for when the chosen one
+   doesn't fit.
+
+## Atoms (15)
+
+- **CdsCounter** — The counter shows how many characters are already typed and how many are allowed: `42 / 100`. [api](components/cds-counter/api.md) · [examples](components/cds-counter/examples.md)
+  - See also: The ready-made fields already have the counter built in — turn on the `counter` prop of [CdsTextInput](components/cds-text-input/api.md) or [CdsTextArea](components/cds-text-area/api.md). A standalone `CdsCounter` is needed when you build your own control.
+- **CdsDescription** — A description is muted text under the label of a field. [api](components/cds-description/api.md) · [examples](components/cds-description/examples.md)
+  - See also: Inputs already have the description built in — the `description` prop of [CdsTextInput](components/cds-text-input/api.md) and the other controls. A standalone `CdsDescription` is needed for groups of fields and for your own controls. For the label of a field take [CdsLabel](components/cds-label/api.md), for the messages under a field take [CdsMessages](components/cds-messages/api.md).
+- **CdsDivider** — A divider is a thin line between the meaningful parts of an interface: the sections of a form, the rows of a list, the blocks of a card. [api](components/cds-divider/api.md) · [examples](components/cds-divider/examples.md) · [guidelines](components/cds-divider/guidelines.md)
+  - See also: The blocks of a card are separated by the `divider` prop of [CdsCard](components/cds-card/api.md) — it draws the same line without adding markup. If the parts of the screen need to be moved onto different surfaces rather than separated, take [CdsSurface](components/cds-surface/api.md).
+- **CdsField** — The frame of an input: the background, the border, the focus and error states, the inner icons, the clear button and the loading indicator. [api](components/cds-field/api.md) · [examples](components/cds-field/examples.md)
+  - See also: For regular input take the ready-made fields — [CdsTextInput](components/cds-text-input/api.md), [CdsSelect](components/cds-select/api.md), [CdsTextArea](components/cds-text-area/api.md). `CdsField` is needed when your control is not in the library. The label, the description and the messages around the frame are added by [CdsInput](components/cds-input/api.md).
+- **CdsFunctionalButton** — A functional button is a utility action next to the content: download a file in a row of a list, reveal a password in a field, collapse a block, open the menu of a record. [api](components/cds-functional-button/api.md) · [examples](components/cds-functional-button/examples.md) · [guidelines](components/cds-functional-button/guidelines.md)
+  - See also: Style the primary action of the screen — "Save", "Submit the request" — with [CdsButton](components/cds-button/api.md), and a navigation inside a paragraph with [CdsLink](components/cds-link/api.md). If the icon triggers nothing and only explains the content, leave it as [CdsIcon](components/cds-icon/api.md).
+- **CdsHighlight** — Highlighting explains why a row made it into the results: the component finds the matches with the query (`query`) or with ready ranges (`matches`) in the text and wraps them into `mark`. [api](components/cds-highlight/api.md) · [examples](components/cds-highlight/examples.md) · [guidelines](components/cds-highlight/guidelines.md)
+  - See also: In [CdsAutocomplete](components/cds-autocomplete/api.md), [CdsCombobox](components/cds-combobox/api.md) and [CdsSelect](components/cds-select/api.md) the highlighting of the matches is already built in — a standalone `CdsHighlight` is not needed there. For a permanent label next to the text take [CdsTag](components/cds-tag/api.md), for a counter take [CdsBadge](components/cds-badge/api.md).
+- **CdsInput** — The wrapper of an input: the label, the description, the outer icons, the block of messages and the validation by rules. [api](components/cds-input/api.md) · [examples](components/cds-input/examples.md)
+  - See also: For regular input take the ready-made fields — [CdsTextInput](components/cds-text-input/api.md), [CdsSelect](components/cds-select/api.md), [CdsTextArea](components/cds-text-area/api.md): they are already assembled from `CdsInput` and `CdsField`. `CdsInput` is needed when your control is not in the library.
+- **CdsLabel** — A label names a field — it says what is expected from the user. [api](components/cds-label/api.md) · [examples](components/cds-label/examples.md)
+  - See also: The ready-made fields already have the label built in — the `label` prop of [CdsTextInput](components/cds-text-input/api.md) and the other controls. A standalone `CdsLabel` is needed for groups of fields and for your own controls. The explanation under the label is added by [CdsDescription](components/cds-description/api.md).
+- **CdsMessages** — The block of messages under an input: a hint, an explanation or a validation error. [api](components/cds-messages/api.md) · [examples](components/cds-messages/examples.md)
+  - See also: The ready-made fields already have the block of messages built in — the `messages`, `hint` and `error-messages` props of [CdsTextInput](components/cds-text-input/api.md) and the other controls. A standalone `CdsMessages` is needed for groups of fields and for your own controls. For a noticeable notification on the page take [CdsNotification](components/cds-notification/api.md).
+- **CdsResponsive** — A frame with constant proportions. [api](components/cds-responsive/api.md) · [examples](components/cds-responsive/examples.md) · [guidelines](components/cds-responsive/guidelines.md)
+  - See also: For photos take [CdsImage](components/cds-image/api.md) — it is built on `CdsResponsive` and can also do lazy loading, a placeholder and cropping. If you need the columns of a page rather than the shape of a single block, take [CdsGrid](components/cds-grid/api.md).
+- **CdsSelectionControl** — The base of the selection controls: a native `input` with state icons, a label and a description. [api](components/cds-selection-control/api.md) · [examples](components/cds-selection-control/examples.md)
+  - See also: For regular selection take the ready-made controls — [CdsCheckbox](components/cds-checkbox/api.md), [CdsRadio](components/cds-radio/api.md), [CdsToggle](components/cds-toggle/api.md): they already have the icons, the sizes, the state colors and the block of messages. `CdsSelectionControl` is needed when the control you want is not in the library.
+- **CdsSelectionControlGroup** — A container for a set of selection controls: it holds the shared value, hands the nested [CdsSelectionControl](components/cds-selection-control/api.md) the type, the icons, the colors and the states, and ties them together with a single `name` attribute. [api](components/cds-selection-control-group/api.md) · [examples](components/cds-selection-control-group/examples.md)
+  - See also: For a ready group with a title, a description and messages take [CdsRadioGroup](components/cds-radio-group/api.md): it is assembled from this group and the [CdsInput](components/cds-input/api.md) wrapper. `CdsSelectionControlGroup` is needed when you build your own set of controls.
+- **CdsSlideGroup** — A slide group lays a set of elements out in a single scrollable line: when the elements do not fit, the strip is paged with arrows. [api](components/cds-slide-group/api.md) · [examples](components/cds-slide-group/examples.md) · [guidelines](components/cds-slide-group/guidelines.md)
+  - See also: For a bar of sections take the ready [CdsTabs](components/cds-tabs/api.md), for picking tags take [CdsTagGroup](components/cds-tag-group/api.md), and to page through slides one by one take [CdsSlideView](components/cds-slide-view/api.md).
+- **CdsSlideView** — A slide view shows one slide out of a set and switches them with a shift animation: arrows, swipes and `v-model` page forward and backward. [api](components/cds-slide-view/api.md) · [examples](components/cds-slide-view/examples.md) · [guidelines](components/cds-slide-view/guidelines.md)
+  - See also: For a carousel of images with dot delimiters and autoplay take the ready [CdsCarousel](components/cds-carousel/api.md), for sections with a navigation bar take [CdsTabs](components/cds-tabs/api.md), and for a strip where several elements are visible at once take [CdsSlideGroup](components/cds-slide-group/api.md).
+- **CdsSurface** — A surface is a container with a background from the tokens, sizes, positioning and a theme of its own. [api](components/cds-surface/api.md) · [examples](components/cds-surface/examples.md)
+  - See also: For a card with a title and actions take [CdsCard](components/cds-card/api.md), for the sections of a page take [CdsLayout](components/cds-layout/api.md). `CdsSurface` is the lowest layer, without content or paddings of its own.
+
+## Content (19)
+
+- **CdsAvatar** — An avatar shows a person, a team or a company: a photo, initials or an icon inside a round container. [api](components/cds-avatar/api.md) · [examples](components/cds-avatar/examples.md) · [guidelines](components/cds-avatar/guidelines.md)
+  - See also: The built-in badge shows a status or a counter right on the avatar; for a marker on arbitrary content take [CdsBadge](components/cds-badge/api.md), and for a text label inside a line — [CdsTag](components/cds-tag/api.md).
+- **CdsButton** — A button is the primary way to trigger an action: submit a form, open a modal, confirm a choice. [api](components/cds-button/api.md) · [examples](components/cds-button/examples.md) · [guidelines](components/cds-button/guidelines.md)
+  - See also: For a link styled as text inside a paragraph, use [CdsLink](components/cds-link/api.md); to pick one option out of several, use [CdsButtonToggle](components/cds-button-toggle/api.md).
+- **CdsButtonGroup** — A button group joins several [CdsButton](components/cds-button/api.md) into one block: the buttons sit flush against each other, only the outer corners stay rounded, and shared props are set once on the group. [api](components/cds-button-group/api.md) · [examples](components/cds-button-group/examples.md)
+  - See also: If the user does not trigger an action but picks one of several options, use [CdsButtonToggle](components/cds-button-toggle/api.md) — it keeps the selected state.
+- **CdsButtonToggle** — A toggle group turns [CdsButton](components/cds-button/api.md) into a switch: the pressed button stays selected, and the choice is available through `v-model`. [api](components/cds-button-toggle/api.md) · [examples](components/cds-button-toggle/examples.md) · [guidelines](components/cds-button-toggle/guidelines.md)
+  - See also: If the buttons trigger actions instead of storing a choice, take [CdsButtonGroup](components/cds-button-group/api.md). To pick from a long list use [CdsSelect](components/cds-select/api.md), and inside forms — [CdsRadioGroup](components/cds-radio-group/api.md).
+- **CdsCard** — A card gathers related content — a title, text, an image, actions — into one bordered block. [api](components/cds-card/api.md) · [examples](components/cds-card/examples.md) · [guidelines](components/cds-card/guidelines.md)
+  - See also: For uniform lists of rows use [CdsList](components/cds-list/api.md), for collapsible sections use [CdsExpandablePanel](components/cds-expandable-panel/api.md), and when you only need a surface without any structure, use [CdsSurface](components/cds-surface/api.md).
+- **CdsCarousel** — A carousel shows images or arbitrary content slide by slide: promo banners, photo galleries, onboarding steps. [api](components/cds-carousel/api.md) · [examples](components/cds-carousel/examples.md) · [guidelines](components/cds-carousel/guidelines.md)
+  - See also: To switch content without delimiters and autoplay, take [CdsSlideView](components/cds-slide-view/api.md) — the carousel is built on top of it; for a single image take [CdsImage](components/cds-image/api.md).
+- **CdsExpandablePanel** — An expandable panel hides the details behind a title: you see the list of topics and open only the one you need. [api](components/cds-expandable-panel/api.md) · [examples](components/cds-expandable-panel/examples.md) · [guidelines](components/cds-expandable-panel/guidelines.md)
+  - See also: If the sections are equal in weight and the reader switches between them, take [CdsTabs](components/cds-tabs/api.md). For a hierarchy of nested nodes take [CdsTree](components/cds-tree/api.md), and for a block that simply separates content — [CdsCard](components/cds-card/api.md).
+- **CdsIcon** — An icon is a short visual mark next to the text: the status of a record, the type of a file, the direction of a transition. [api](components/cds-icon/api.md) · [examples](components/cds-icon/examples.md) · [guidelines](components/cds-icon/guidelines.md)
+  - See also: Inside other components you do not assemble an icon separately: [CdsButton](components/cds-button/api.md), [CdsTextInput](components/cds-text-input/api.md), [CdsList](components/cds-list/api.md) and others have the `icon`, `prepend-icon` and `append-icon` props. For a standalone action take [CdsFunctionalButton](components/cds-functional-button/api.md) — an icon button with a label and states. All the available icons are in the gallery, and connecting your own pack is described in the [guide](guides/icons.md).
+- **CdsImage** — An image that knows how to wait. [api](components/cds-image/api.md) · [examples](components/cds-image/examples.md) · [guidelines](components/cds-image/guidelines.md)
+  - See also: For a photo of a person or a company logo in a round frame take [CdsAvatar](components/cds-avatar/api.md), for interface pictograms — [CdsIcon](components/cds-icon/api.md). If the proportions have to be set not for a picture but for an arbitrary block — a video, a map, an iframe — use [CdsResponsive](components/cds-responsive/api.md), and a slideshow of several images is assembled by [CdsCarousel](components/cds-carousel/api.md).
+- **CdsList** — A list shows a set of records of the same kind — menu sections, documents, employees, settings — so that the one you need is easy to find and pick. [api](components/cds-list/api.md) · [examples](components/cds-list/examples.md) · [guidelines](components/cds-list/guidelines.md)
+  - See also: To pick a value in a form, take [CdsSelect](components/cds-select/api.md); for a tree with checkboxes, async loading and drag and drop — [CdsTree](components/cds-tree/api.md); for tabular data with columns — [CdsTable](components/cds-table/api.md). Inside [CdsMenu](components/cds-menu/api.md), [CdsSelect](components/cds-select/api.md) and [CdsAutocomplete](components/cds-autocomplete/api.md) the list is already in use — there is no need to assemble it by hand.
+- **CdsMenu** — A menu pops up next to an activator element and shows a list of actions or sections: the "more" button in a table row, the user menu in the header, a context menu on right click. [api](components/cds-menu/api.md) · [examples](components/cds-menu/examples.md) · [guidelines](components/cds-menu/guidelines.md)
+  - See also: To pick a value in a form, take [CdsSelect](components/cds-select/api.md) — it stays visible and gets submitted. For a short hint on hover use [CdsTooltip](components/cds-tooltip/api.md), and for a dialog that demands an answer use [CdsModal](components/cds-modal/api.md). The content of a menu is usually built from [CdsList](components/cds-list/api.md).
+- **CdsModal** — A modal opens on top of the page and keeps the focus on a single task: confirm an action, fill in a short form, look at the details — without taking you away from the current screen. [api](components/cds-modal/api.md) · [examples](components/cds-modal/examples.md) · [guidelines](components/cds-modal/guidelines.md)
+  - See also: For a list of actions on an element take [CdsMenu](components/cds-menu/api.md), for a short hint — [CdsTooltip](components/cds-tooltip/api.md), for a notification about the result — [CdsToast](components/cds-toast/api.md). Complex modal content — a header, scrollable text and a row of buttons — is assembled from [CdsCard](components/cds-card/api.md).
+- **CdsOverlay** — An overlay shows content on top of the page: it dims the page with a scrim, computes the position relative to an activator and manages the stacking order of the open layers. [api](components/cds-overlay/api.md) · [examples](components/cds-overlay/examples.md) · [guidelines](components/cds-overlay/guidelines.md)
+  - See also: For common tasks there are ready-made components built on the overlay: a dialog — [CdsModal](components/cds-modal/api.md), a list of actions next to an activator — [CdsMenu](components/cds-menu/api.md), a hint on hover — [CdsTooltip](components/cds-tooltip/api.md), notifications — [CdsToast](components/cds-toast/api.md). CdsOverlay is for when none of them fits.
+- **CdsTable** — A table shows large sets of records in columns and takes the data work off your hands: sorting, filters, pagination, row selection and expansion, a pinned header and pinned columns. [api](components/cds-table/api.md) · [examples](components/cds-table/examples.md) · [guidelines](components/cds-table/guidelines.md)
+  - See also: For a plain list of similar items without columns, use [CdsList](components/cds-list/api.md); for a hierarchy without tabular data, use [CdsTree](components/cds-tree/api.md).
+- **CdsTag** — A tag is a compact label next to an object: the status of a request, a product category, a selected filter. [api](components/cds-tag/api.md) · [examples](components/cds-tag/examples.md) · [guidelines](components/cds-tag/guidelines.md)
+  - See also: To build a toggle or a filter with selection out of tags, take [CdsTagGroup](components/cds-tag-group/api.md). For a counter or a dot indicator on top of another element use [CdsBadge](components/cds-badge/api.md), and trigger actions with [CdsButton](components/cds-button/api.md) — a tag only labels.
+- **CdsTagGroup** — A tag group turns a set of [CdsTag](components/cds-tag/api.md) into a toggle: the selected tag is highlighted, the value is available through `v-model`, and the tags that do not fit move into a horizontal scroll. [api](components/cds-tag-group/api.md) · [examples](components/cds-tag-group/examples.md) · [guidelines](components/cds-tag-group/guidelines.md)
+  - See also: If the choice should look like buttons, take [CdsButtonToggle](components/cds-button-toggle/api.md). For a choice out of a long list use [CdsSelect](components/cds-select/api.md), and for separate independent tags without selection just use [CdsTag](components/cds-tag/api.md).
+- **CdsTooltip** — A tooltip briefly explains an interface element on hover or focus: it names an icon button, shows the full text of a truncated line, explains why an action is unavailable. [api](components/cds-tooltip/api.md) · [examples](components/cds-tooltip/examples.md) · [guidelines](components/cds-tooltip/guidelines.md)
+  - See also: A tooltip is for a short text without interaction. A list of actions on click is the job of [CdsMenu](components/cds-menu/api.md), and a dialog with a form and buttons is the job of [CdsModal](components/cds-modal/api.md).
+- **CdsTree** — A tree shows a hierarchy: catalog sections, project files, an org structure. [api](components/cds-tree/api.md) · [examples](components/cds-tree/examples.md) · [guidelines](components/cds-tree/guidelines.md)
+  - See also: For a flat set without nesting take [CdsList](components/cds-list/api.md), for navigation between sections take [CdsMenu](components/cds-menu/api.md), and for collapsible sections of content take [CdsExpandablePanel](components/cds-expandable-panel/api.md).
+- **CdsVirtualScroll** — Virtual scrolling keeps long lists fast: only the visible rows get into the DOM, not the whole array. [api](components/cds-virtual-scroll/api.md) · [examples](components/cds-virtual-scroll/examples.md) · [guidelines](components/cds-virtual-scroll/guidelines.md)
+  - See also: The dropdowns of [CdsSelect](components/cds-select/api.md) and [CdsAutocomplete](components/cds-autocomplete/api.md), as well as the [CdsTree](components/cds-tree/api.md) tree, already virtualize their items — there is no need to wrap them. Render a short list — up to a couple of hundred rows — with the regular [CdsList](components/cds-list/api.md): virtualization will not pay off there.
+
+## Controls (18)
+
+- **CdsAutocomplete** — An autocomplete is a field for picking from a long list: the user types a query, the list is filtered on the fly and the matches are highlighted. [api](components/cds-autocomplete/api.md) · [examples](components/cds-autocomplete/examples.md) · [guidelines](components/cds-autocomplete/guidelines.md)
+  - See also: If there are few options and search is not needed, take [CdsSelect](components/cds-select/api.md). If the user may enter values outside the list — [CdsCombobox](components/cds-combobox/api.md).
+- **CdsCheckbox** — A checkbox turns an independent option on and off: consent to terms, an entry in a filter list, a profile setting. [api](components/cds-checkbox/api.md) · [examples](components/cds-checkbox/examples.md) · [guidelines](components/cds-checkbox/guidelines.md)
+  - See also: To pick one option out of several use [CdsRadio](components/cds-radio/api.md), for settings that apply immediately — [CdsToggle](components/cds-toggle/api.md). If you need the control alone, without a label and messages — in a table cell, for example — take [CdsCheckboxButton](components/cds-checkbox-button/api.md).
+- **CdsCheckboxButton** — The checkbox control without a label and a messages block — the atom [CdsCheckbox](components/cds-checkbox/api.md) is built on. [api](components/cds-checkbox-button/api.md) · [examples](components/cds-checkbox-button/examples.md)
+  - See also: For a standalone option with a label, a description and validation use [CdsCheckbox](components/cds-checkbox/api.md) — states, colors and groups work the same way here and are described in detail on its page.
+- **CdsCombobox** — A combobox is a field with a dropdown list and free input: the value can be picked from the offered ones or typed in — the text itself becomes the value. [api](components/cds-combobox/api.md) · [examples](components/cds-combobox/examples.md) · [guidelines](components/cds-combobox/guidelines.md)
+  - See also: If the value must come from the list only, take [CdsAutocomplete](components/cds-autocomplete/api.md). If there are few options and free input is not needed — [CdsSelect](components/cds-select/api.md).
+- **CdsDateInput** — A date field: a text field with a calendar icon that opens [CdsDatePicker](components/cds-date-picker/api.md) in a dropdown menu on click. [api](components/cds-date-input/api.md) · [examples](components/cds-date-input/examples.md) · [guidelines](components/cds-date-input/guidelines.md)
+  - See also: If the calendar is needed right on the page, without a field, take [CdsDatePicker](components/cds-date-picker/api.md). For the time alone — [CdsTimePicker](components/cds-time-picker/api.md), to pick from a ready list — [CdsSelect](components/cds-select/api.md).
+- **CdsDatePicker** — A calendar for picking a date — a single one, several or a range. [api](components/cds-date-picker/api.md) · [examples](components/cds-date-picker/examples.md) · [guidelines](components/cds-date-picker/guidelines.md)
+  - See also: If the calendar needs a field, take the ready [CdsDateInput](components/cds-date-input/api.md) — it assembles the very same thing out of a field, a menu and this calendar, adding manual input and time. For picking the time alone there is [CdsTimePicker](components/cds-time-picker/api.md).
+- **CdsFileInput** — A file field: the user attaches documents by a click, by dragging or by pasting from the clipboard. [api](components/cds-file-input/api.md) · [examples](components/cds-file-input/examples.md) · [guidelines](components/cds-file-input/guidelines.md)
+  - See also: If you need a prominent upload zone with a list of files, take [CdsFileUpload](components/cds-file-upload/api.md); sending the files to the server is the job of [CdsUploader](components/cds-uploader/api.md).
+- **CdsFileUpload** — A file upload zone: it accepts files by dragging, by pasting from the clipboard and through the system dialog, and shows the selection as a list with image previews. [api](components/cds-file-upload/api.md) · [examples](components/cds-file-upload/examples.md) · [guidelines](components/cds-file-upload/guidelines.md)
+  - See also: For a compact file field in a form row use [CdsFileInput](components/cds-file-input/api.md); sending the files to the server is the job of [CdsUploader](components/cds-uploader/api.md).
+- **CdsForm** — A form joins fields into one group: it collects their validation into a common status, intercepts the submission and can reset the values. [api](components/cds-form/api.md) · [examples](components/cds-form/examples.md) · [guidelines](components/cds-form/guidelines.md)
+  - See also: The form does not render the fields itself — build them out of [CdsTextInput](components/cds-text-input/api.md), [CdsSelect](components/cds-select/api.md), [CdsCheckbox](components/cds-checkbox/api.md) and other controls. The validation rules are declared on the fields themselves through the `rules` prop.
+- **CdsOtpInput** — A field for entering a one-time code — from an SMS, an email or an authenticator app. [api](components/cds-otp-input/api.md) · [examples](components/cds-otp-input/examples.md) · [guidelines](components/cds-otp-input/guidelines.md)
+  - See also: For an ordinary short text or number take [CdsTextInput](components/cds-text-input/api.md): `CdsOtpInput` is needed where the length of the input is known upfront and every character is shown in its own cell.
+- **CdsRadio** — A radio button is one option of a mutually exclusive choice. [api](components/cds-radio/api.md)
+  - See also: Examples, guidelines and scenarios are on the [CdsRadioGroup](components/cds-radio-group/api.md) page. For an independent on/off option take [CdsCheckbox](components/cds-checkbox/api.md).
+- **CdsRadioGroup** — A radio group is a choice of one option out of a short mutually exclusive set: a payment method, a plan, a report period. [api](components/cds-radio-group/api.md) · [examples](components/cds-radio-group/examples.md) · [guidelines](components/cds-radio-group/guidelines.md)
+  - See also: For independent options that are turned on separately use [CdsCheckbox](components/cds-checkbox/api.md), for an on/off setting that applies immediately — [CdsToggle](components/cds-toggle/api.md). If there are more than five options, fold the list into [CdsSelect](components/cds-select/api.md).
+- **CdsSelect** — A select opens a dropdown list and lets you pick one or several values from a known set: a country, a status, a category. [api](components/cds-select/api.md) · [examples](components/cds-select/examples.md) · [guidelines](components/cds-select/guidelines.md)
+  - See also: For two or three options take [CdsRadioGroup](components/cds-radio-group/api.md) — the options are visible right away. If the list is long and the user searches by typing, use [CdsAutocomplete](components/cds-autocomplete/api.md), and if values outside the list are allowed — [CdsCombobox](components/cds-combobox/api.md).
+- **CdsTextArea** — A text area is a field for multiline text: a comment, a description, a support request. [api](components/cds-text-area/api.md) · [examples](components/cds-text-area/examples.md) · [guidelines](components/cds-text-area/guidelines.md)
+  - See also: For a short single-line value use [CdsTextInput](components/cds-text-input/api.md), to pick from a ready list of options — [CdsSelect](components/cds-select/api.md).
+- **CdsTextInput** — A text field is the basic way to get data from the user: a name, an email, an amount, a search query. [api](components/cds-text-input/api.md) · [examples](components/cds-text-input/examples.md) · [guidelines](components/cds-text-input/guidelines.md)
+  - See also: For multiline text use [CdsTextArea](components/cds-text-area/api.md), to pick from a ready list of options use [CdsSelect](components/cds-select/api.md).
+- **CdsTimePicker** — Time selection: hours, minutes and — if you want — seconds. [api](components/cds-time-picker/api.md) · [examples](components/cds-time-picker/examples.md) · [guidelines](components/cds-time-picker/guidelines.md)
+  - See also: To pick a date use [CdsDatePicker](components/cds-date-picker/api.md), and if you need a field with a date and a time at once — the ready [CdsDateInput](components/cds-date-input/api.md) with the `with-time` prop: it puts this clock under the calendar and brings everything together into one string itself.
+- **CdsToggle** — A toggle is an on/off switch for a setting that applies immediately, without a "Save" button: notifications, auto-renewal, profile visibility. [api](components/cds-toggle/api.md) · [examples](components/cds-toggle/examples.md) · [guidelines](components/cds-toggle/guidelines.md)
+  - See also: A toggle changes the setting instantly. If the choice is applied together with the rest of the form by a button, take [CdsCheckbox](components/cds-checkbox/api.md), and to pick one option out of a set — [CdsRadioGroup](components/cds-radio-group/api.md).
+- **CdsUploader** — The uploader sends files to the server right from the interface: the user picks them in the system dialog or drags them onto the button, and the component shows the list of what was uploaded — with a status, progress, downloading and removal. [api](components/cds-uploader/api.md) · [examples](components/cds-uploader/examples.md) · [guidelines](components/cds-uploader/guidelines.md)
+  - See also: The uploader sends the files over HTTP itself. If the files only have to be picked and sent together with the form, take the [CdsFileInput](components/cds-file-input/api.md) field, and for a drop zone with image previews — [CdsFileUpload](components/cds-file-upload/api.md).
+
+## Feedback (12)
+
+- **CdsBadge** — A badge is a small marker in the corner of an element or next to it: a counter of unread messages, a "there is something new" dot, a short label. [api](components/cds-badge/api.md) · [examples](components/cds-badge/examples.md) · [guidelines](components/cds-badge/guidelines.md)
+  - See also: For a textual object status ("Done", "In progress") take [CdsStatus](components/cds-status/api.md), and [CdsAvatar](components/cds-avatar/api.md) has a built-in `badge` prop for the common indicators on an avatar.
+- **CdsEmptyState** — An empty state explains why there is no content on the screen and suggests the next step: no search results, an empty list, a loading error. [api](components/cds-empty-state/api.md) · [examples](components/cds-empty-state/examples.md) · [guidelines](components/cds-empty-state/guidelines.md)
+  - See also: For a short message about the result of an operation take [CdsToast](components/cds-toast/api.md), and while the data is still loading show [CdsSkeletonLoader](components/cds-skeleton-loader/api.md) instead of an empty state.
+- **CdsLoader** — A circular indeterminate loading indicator — a spinning ring without progress. [api](components/cds-loader/api.md) · [examples](components/cds-loader/examples.md)
+  - See also: The component is deprecated and will be removed in future versions. Use [CdsProgressCircle](components/cds-progress-circle/api.md): it covers both indeterminate loading and progress.
+- **CdsNotification** — A notification is a block with a message about an event or a state: a successful save, a warning about a limit, a loading error. [api](components/cds-notification/api.md) · [examples](components/cds-notification/examples.md) · [guidelines](components/cds-notification/guidelines.md)
+  - See also: For pop-up messages above the page that disappear on their own take [CdsToast](components/cds-toast/api.md). For a short status label in a row or a card — [CdsTag](components/cds-tag/api.md).
+- **CdsNotificationAlert** — A pop-up notification above the page — the counterpart of `CdsNotificationAlert` from CDS 3. [api](components/cds-notification-alert/api.md) · [examples](components/cds-notification-alert/examples.md)
+  - See also: The component exists only for a smooth migration from CDS 3 and will be removed. For new scenarios use [CdsToast](components/cds-toast/api.md).
+- **CdsProgressBar** — A linear progress indicator — a horizontal bar for the course of an operation: a file upload, the steps of a wizard, media playback. [api](components/cds-progress-bar/api.md) · [examples](components/cds-progress-bar/examples.md) · [guidelines](components/cds-progress-bar/guidelines.md)
+  - See also: For progress shown as a ring take [CdsProgressCircle](components/cds-progress-circle/api.md), and to dim a container while it loads — [CdsOverlay](components/cds-overlay/api.md).
+- **CdsProgressCircle** — A circular progress indicator shows the course of an operation: a file upload, data processing, a filling quota. [api](components/cds-progress-circle/api.md) · [examples](components/cds-progress-circle/examples.md) · [guidelines](components/cds-progress-circle/guidelines.md)
+  - See also: For progress shown as a horizontal bar take [CdsProgressBar](components/cds-progress-bar/api.md), and to dim a container while it loads — [CdsOverlay](components/cds-overlay/api.md).
+- **CdsSkeletonLoader** — A skeleton shows the shape of the future content while the data is loading: instead of an empty screen the user immediately sees where the heading, the text and the buttons will appear. [api](components/cds-skeleton-loader/api.md) · [examples](components/cds-skeleton-loader/examples.md) · [guidelines](components/cds-skeleton-loader/guidelines.md)
+  - See also: A skeleton fits the first load of a block or a page. For waiting inside a single action — submitting a form, saving — take the `loading` prop of [CdsButton](components/cds-button/api.md) or [CdsProgressCircle](components/cds-progress-circle/api.md). If there is no data at all, show [CdsEmptyState](components/cds-empty-state/api.md).
+- **CdsStages** — A stage bar shows the course of a business process: which stages are behind, which one is running now and where the process stopped because of an error. [api](components/cds-stages/api.md) · [examples](components/cds-stages/examples.md) · [guidelines](components/cds-stages/guidelines.md)
+  - See also: To walk the user through steps with content and "Back" / "Next" buttons take [CdsSteps](components/cds-steps/api.md), and to switch between equally weighted sections — [CdsTabs](components/cds-tabs/api.md).
+- **CdsStatus** — A status is a non-interactive indicator of the state of an object: the request is paid, the document is under review, the payment is overdue. [api](components/cds-status/api.md) · [examples](components/cds-status/examples.md) · [guidelines](components/cds-status/guidelines.md)
+  - See also: For labels with arbitrary palette colors — categories, filters — take [CdsTag](components/cds-tag/api.md); for counters and marker dots in the corner of an element — [CdsBadge](components/cds-badge/api.md).
+- **CdsToast** — A toast is a pop-up notification about the result of an action: the changes are saved, the file is uploaded, the request failed. [api](components/cds-toast/api.md) · [examples](components/cds-toast/examples.md) · [guidelines](components/cds-toast/guidelines.md)
+  - See also: For a stream of events where notifications arrive one after another use [CdsToastQueue](components/cds-toast-queue/api.md). A message that has to stay on the page belongs in [CdsNotification](components/cds-notification/api.md), and a question that requires a decision from the user — in the [CdsModal](components/cds-modal/api.md) dialog.
+- **CdsToastQueue** — A queue of pop-up notifications built on [CdsToast](components/cds-toast/api.md). [api](components/cds-toast-queue/api.md) · [examples](components/cds-toast-queue/examples.md)
+  - See also: For a single notification — a save confirmation, for example — [CdsToast](components/cds-toast/api.md) is enough.
+
+## Layouts (8)
+
+- **CdsDrawer** — The side panel of the application: navigation sections on the left, the context of a record or filters on the right. [api](components/cds-drawer/api.md) · [examples](components/cds-drawer/examples.md) · [guidelines](components/cds-drawer/guidelines.md)
+  - See also: For a list of sections inside the drawer take [CdsList](components/cds-list/api.md); for navigating the subsections of a single page take [CdsTabs](components/cds-tabs/api.md). The drawer is a part of the [CdsLayout](components/cds-layout/api.md) frame, but unlike the other parts it also works on its own: with the `fixed` prop it sticks to the window without a layout.
+- **CdsFooter** — The footer of the application: a copyright notice and utility links on regular pages, an action bar on forms. [api](components/cds-footer/api.md) · [examples](components/cds-footer/examples.md) · [guidelines](components/cds-footer/guidelines.md)
+  - See also: The footer works only inside [CdsLayout](components/cds-layout/api.md) — outside the layout it renders nothing and warns about it in the console. The top bar of the application is built by [CdsHeader](components/cds-header/api.md), and the content of both by [CdsToolbar](components/cds-toolbar/api.md).
+- **CdsGrid** — A responsive modular grid: `CdsGrid`, `CdsRow` and `CdsCol` lay the content out in columns — from 4 on a phone to 16 on wide screens. [api](components/cds-grid/api.md) · [examples](components/cds-grid/examples.md) · [guidelines](components/cds-grid/guidelines.md)
+  - See also: The grid lays out the content inside a page. Build the frame of the application — the header, the drawers and the footer — from [CdsLayout](components/cds-layout/api.md).
+- **CdsHeader** — The header of the application: the title, the global search, notifications, the profile — everything that has to be at hand on any screen. [api](components/cds-header/api.md) · [examples](components/cds-header/examples.md) · [guidelines](components/cds-header/guidelines.md)
+  - See also: The header works only inside [CdsLayout](components/cds-layout/api.md) — outside the layout it renders nothing and warns about it in the console. The content of the header is laid out by [CdsToolbar](components/cds-toolbar/api.md), and the bottom bar of the application is built by [CdsFooter](components/cds-footer/api.md).
+- **CdsLayout** — The frame of the application: `CdsLayout` places the header, the side drawers, the content and the footer, measures their sizes and takes the scrolling over. [api](components/cds-layout/api.md) · [examples](components/cds-layout/examples.md) · [guidelines](components/cds-layout/guidelines.md)
+  - See also: The parts of the layout are described on their own pages: [CdsHeader](components/cds-header/api.md), [CdsDrawer](components/cds-drawer/api.md), [CdsMain](components/cds-main/api.md), [CdsPage](components/cds-page/api.md), [CdsFooter](components/cds-footer/api.md) and [CdsToolbar](components/cds-toolbar/api.md). You can assemble the frame with the mouse and copy the ready code in the layout builder.
+- **CdsMain** — The main area of the application: `CdsMain` is the place where the content of the page lands. [api](components/cds-main/api.md) · [examples](components/cds-main/examples.md)
+  - See also: Put the content into [CdsPage](components/cds-page/api.md) — it calculates the minimum height of the page. `CdsMain` works only inside [CdsLayout](components/cds-layout/api.md): outside the layout it renders nothing and warns about it in the console.
+- **CdsPage** — A page inside the layout: `CdsPage` gives the content a minimum height that accounts for the header and the footer, so a short page fills the whole screen instead of hanging as a narrow strip at the top. [api](components/cds-page/api.md) · [examples](components/cds-page/examples.md)
+  - See also: `CdsPage` lives inside [CdsMain](components/cds-main/api.md) — outside it renders nothing and warns about it in the console. The paddings around the whole content area are calculated by [CdsLayout](components/cds-layout/api.md).
+- **CdsToolbar** — A horizontal bar with a title and actions: it fills the header and the footer of the application, and on a page it assembles the title of a section together with its buttons. [api](components/cds-toolbar/api.md) · [examples](components/cds-toolbar/examples.md) · [guidelines](components/cds-toolbar/guidelines.md)
+  - See also: The toolbar only lays the content out — the place in the layout is reserved by [CdsHeader](components/cds-header/api.md) and [CdsFooter](components/cds-footer/api.md). For navigating the subsections take [CdsTabs](components/cds-tabs/api.md); for an action bar over a record take [CdsButtonGroup](components/cds-button-group/api.md).
+
+## Navigation (5)
+
+- **CdsBreadcrumbs** — Breadcrumbs show the path to the current page in the hierarchy of sections and take you back to any level above in one click. [api](components/cds-breadcrumbs/api.md) · [examples](components/cds-breadcrumbs/examples.md) · [guidelines](components/cds-breadcrumbs/guidelines.md)
+  - See also: To switch between sections of the same level, use [CdsTabs](components/cds-tabs/api.md); for a link styled as text inside a paragraph, use [CdsLink](components/cds-link/api.md); and to move through the steps of a process, use [CdsSteps](components/cds-steps/api.md).
+- **CdsLink** — A link sends the user somewhere else: to a neighboring page of the application, to an external service or to an email address. [api](components/cds-link/api.md) · [examples](components/cds-link/examples.md) · [guidelines](components/cds-link/guidelines.md)
+  - See also: If the element triggers an action instead of a navigation — saves, deletes, opens a modal — take [CdsButton](components/cds-button/api.md). A button also accepts `href` or `to` when a navigation has to look like a button. The path through the hierarchy of sections is built by [CdsBreadcrumbs](components/cds-breadcrumbs/api.md), and sections of equal weight are switched by [CdsTabs](components/cds-tabs/api.md).
+- **CdsPagination** — Pagination splits a large data set into pages and helps you jump to the one you need: numbered buttons, "back" and "forward" arrows, jumps to the first and the last page, and a quick jump field. [api](components/cds-pagination/api.md) · [examples](components/cds-pagination/examples.md) · [guidelines](components/cds-pagination/guidelines.md)
+  - See also: Pagination pages through homogeneous data — a list or a table. To switch between sections of the interface use [CdsTabs](components/cds-tabs/api.md), and to navigate the hierarchy of pages use [CdsBreadcrumbs](components/cds-breadcrumbs/api.md).
+- **CdsSteps** — The stepper walks the user through a multi-step process: it shows which steps are done, which one is active and how many are left. [api](components/cds-steps/api.md) · [examples](components/cds-steps/examples.md) · [guidelines](components/cds-steps/guidelines.md)
+  - See also: To show the progress of a business process without step navigation, use [CdsStages](components/cds-stages/api.md); for sections of equal weight that are switched in any order, use [CdsTabs](components/cds-tabs/api.md).
+- **CdsTabs** — Tabs split the screen into sections of equal weight and switch between them in place, without going to another page. [api](components/cds-tabs/api.md) · [examples](components/cds-tabs/examples.md) · [guidelines](components/cds-tabs/guidelines.md)
+  - See also: For a sequential process with steps and progress, use [CdsSteps](components/cds-steps/api.md); to pick a single value in a form, use [CdsButtonToggle](components/cds-button-toggle/api.md).
+
+## Other (2)
+
+- **CdsApp** — _purpose not described on the documentation page_. [api](components/cds-app/api.md)
+- **CdsDefaultsProvider** — _purpose not described on the documentation page_. [api](components/cds-defaults-provider/api.md)
+
+## Head-to-head cases
+
+Below are the cases where it is easy to pick the wrong component. They cannot
+be derived from the metadata, so this section is maintained by hand.
+
+### Picking from a list: CdsSelect vs CdsCombobox vs CdsAutocomplete
+
+| Component | When to take it |
+| --- | --- |
+| `CdsSelect` | The value set is known in advance and small: status, category, country. No keyboard input. |
+| `CdsAutocomplete` | The set is known but long: the user types a query, the list is filtered, matches are highlighted. |
+| `CdsCombobox` | The value may not be in the list: the entered text itself becomes the value (tags, a free-form category). |
+
+The deciding question: **can the user enter a value that is not in the
+list?** Yes — `CdsCombobox`. No, but the list is long — `CdsAutocomplete`.
+No, and the list is short — `CdsSelect`.
+
+### Input fields: CdsTextInput vs CdsInput vs CdsField
+
+- `CdsTextInput` — the **ready-made field** you need in 95% of cases: label,
+  hint, errors, and the field itself are already wired together.
+- `CdsInput` and `CdsField` — **atoms** for building your own control when no
+  ready-made one exists. Assembling a form from them by hand means
+  reimplementing `CdsTextInput` — first verify that the ready-made control
+  really does not fit.
+- `CdsTextArea` — the same `CdsTextInput`, but for multiline text.
+
+### Overlays: CdsModal vs CdsMenu vs CdsTooltip vs CdsDrawer
+
+| Component | When to take it |
+| --- | --- |
+| `CdsModal` | The task demands attention and a response: a confirmation, a form, losing context is unacceptable. |
+| `CdsMenu` | A dropdown list of actions or options anchored to a trigger element. |
+| `CdsTooltip` | A short hint on hover. Nothing interactive goes inside. |
+| `CdsDrawer` | A page-level **side navigation panel** (Layouts category), not a pop-up form panel. For a side form take `CdsModal`. |
+
+### Data lists: CdsList vs CdsTable vs CdsTree vs CdsVirtualScroll
+
+- `CdsList` — a flat list of uniform items.
+- `CdsTable` — columnar data, when you need sorting, filtering, pagination,
+  row selection, or a sticky header. Do not build a table out of `CdsList`
+  and markup.
+- `CdsTree` — a hierarchy with expandable nodes, including async loading.
+- `CdsVirtualScroll` — not a standalone kind of list but a **performance
+  technique**: it wraps a long list so that only the visible items live in
+  the DOM. `CdsTable` and `CdsTree` have virtualization built in.
+
+### Notifications: CdsNotification vs CdsToast vs CdsNotificationAlert vs CdsStatus vs CdsBadge
+
+| Component | When to take it |
+| --- | --- |
+| `CdsNotification` | A message **in the page flow**: a form error, a warning inside a block. |
+| `CdsToast` | A short-lived result of an action on top of the page, disappears on its own. For a queue — `CdsToastQueue`. |
+| `CdsNotificationAlert` | A pop-up notification on top of the page that needs attention longer than a toast. |
+| `CdsStatus` | **Not a notification** but a non-interactive indicator of an object's state in a list or card. |
+| `CdsBadge` | A counter or label on another element (unread items, a count). |
+
+### Waiting: CdsSkeletonLoader vs CdsProgressCircle vs CdsProgressBar
+
+- `CdsSkeletonLoader` — loading **content with a known shape**: cards, table
+  rows. The preferred option — less layout "jumping".
+- `CdsProgressCircle` — waiting of unknown duration in a small area.
+- `CdsProgressBar` — progress with a **measurable completion fraction**.
+- `CdsLoader` — **deprecated**, do not use in new code.
+
+A button waiting for a server response needs no separate indicator:
+`CdsButton` has a `loading` prop.
+
+### Step-by-step processes: CdsSteps vs CdsStages vs CdsTabs vs CdsExpandablePanel
+
+- `CdsSteps` — a linear wizard whose steps are completed in order.
+- `CdsStages` — the progress of a business process whose status is changed by
+  something other than the user.
+- `CdsTabs` — equal sections of a single screen, order does not matter.
+- `CdsExpandablePanel` — a vertical list of sections that expand in place;
+  suitable for FAQs and long forms with grouped fields.
+
+### Toggles: CdsCheckbox vs CdsToggle vs CdsButtonToggle vs CdsRadioGroup
+
+- `CdsCheckbox` — an independent on/off option whose result applies on form
+  submit.
+- `CdsToggle` — a switch that applies **immediately**: a setting, a display
+  mode.
+- `CdsRadioGroup` — exactly one option out of several. A lone `CdsRadio`
+  outside a group is not used.
+- `CdsButtonToggle` — the same single-choice selection, but with buttons:
+  display modes, short mutually exclusive filters.
+
+### Files: CdsFileInput vs CdsFileUpload vs CdsUploader
+
+- `CdsFileInput` — compact file selection via an input field, when the file
+  is one of the form's fields.
+- `CdsFileUpload` — a zone with drag-and-drop and clipboard paste, when the
+  upload is the screen's main action.
+- `CdsUploader` — sending files to a server with upload tracking.
+
+### Date and time: CdsDateInput vs CdsDatePicker vs CdsTimePicker
+
+- `CdsDateInput` — a **form field**: text input plus a calendar in a dropdown
+  menu. The usual choice for forms.
+- `CdsDatePicker` — the calendar itself, embedded in the page without a
+  field.
+- `CdsTimePicker` — time selection.
+
+### Containers: CdsSurface vs CdsCard
+
+- `CdsCard` — a cohesive block of content with a border: title, text,
+  actions.
+- `CdsSurface` — a low-level surface with configurable background and sizes.
+  Take it only when the card semantics do not apply.
+
+### Button or link
+
+What matters is **what happens**, not the appearance: navigating to an
+address — `CdsLink` (or `CdsButton` with `to` / `href` if it is the screen's
+main action), changing state — `CdsButton`. A link styled as a button is
+still a link — it must open in a new tab and be copyable.

package/skills/cds-builder/references/components/cds-app/api.md

@@ -0,0 +1,19 @@
+# CdsApp — API
+
+> Generated from meta.json by `bun run generate:skill`. Do not edit manually.
+> Tokens: [tokens.md](tokens.md)
+
+## CdsApp
+
+**Props**
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `storybook` | `boolean \| "fluid" \| undefined` | `false` | no | Режим отображения внутри Storybook: убирает полноэкранную обёртку, `'fluid'` дополнительно снимает ограничение ширины |
+| `theme` | `string \| undefined` | — | no | Component theme |
+
+**Slots**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `default` | `any` | Default slot |

package/skills/cds-builder/references/components/cds-app/tokens.md

@@ -0,0 +1,12 @@
+# CdsApp — tokens (level 3)
+
+> Copy of the component's `styles/*.variables.scss`, taken by `bun run generate:skill`. Do not edit manually.
+> `--cds-*` are global level-2 tokens whose values come from the active theme: see [themes.md](../../tokens/themes.md).
+> Variables marked `!default` can be overridden at build time via SCSS.
+
+## _CdsApp.variables.scss
+
+```scss
+$application-background: rgb(var(--cds-color-page-primary)) !default;
+$application-color: rgb(var(--cds-color-content-primary)) !default;
+```

package/skills/cds-builder/references/components/cds-autocomplete/api.md

@@ -0,0 +1,155 @@
+# CdsAutocomplete — API
+
+> Generated from meta.json by `bun run generate:skill`. Do not edit manually.
+> Examples: [examples.md](examples.md) · Guidelines: [guidelines.md](guidelines.md) · Tokens: [tokens.md](tokens.md)
+
+An autocomplete is a field for picking from a long list: the user types a query, the list is filtered on the fly and the matches are highlighted. The field is built on [CdsTextInput](../cds-text-input/api.md), and the menu and the list are the same as in [CdsSelect](../cds-select/api.md), so the label, the messages, validation and the menu behave identically.
+
+## CdsAutocomplete
+
+**Props**
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `active` | `boolean \| undefined` | — | no | Active state of the field |
+| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
+| `appendIcon` | `IconValue \| undefined` | — | no | Icon in the append slot, after the content |
+| `appendInnerIcon` | `IconValue \| undefined` | — | no | Icon in the inner append slot, after the content of the field |
+| `autocomplete` | `string \| undefined` | `'off'` | no | Helps to influence browser suggestions. The `suppress` value changes the name attribute of the fields, and `off` relies on the browser to stop suggesting values on its own. Any other value is passed to the built-in autocomplete of the corresponding element. |
+| `autofocus` | `boolean \| undefined` | — | no | Enables autofocus |
+| `autoSelectFirst` | `boolean \| "exact" \| undefined` | — | no | Highlights the first matching item as you type; Enter or Tab select it. The `exact` value highlights it only on a full match of the search query with the item title. |
+| `baseColor` | `string \| undefined` | — | no | Color of the component in its inactive state |
+| `bgColor` | `string \| undefined` | — | no | Background color of the component |
+| `centerAffix` | `boolean \| undefined` | — | no | Vertically center the appendInner, prependInner, clearIcon and label elements. |
+| `chips` | `boolean \| undefined` | — | no | Shows the selected values as removable chips (CdsTag). |
+| `clearable` | `boolean \| undefined` | — | no | Shows the clear button |
+| `clearIcon` | `IconValue \| undefined` | `'remove'` | no | Icon of the clear button |
+| `clearOnSelect` | `boolean \| undefined` | — | no | Clears the search query after an item is selected (relevant for `multiple`). |
+| `closableChips` | `boolean \| undefined` | — | no | Adds a remove button to the chips (relevant together with `chips`). |
+| `closeText` | `string \| undefined` | `'$cds.close'` | no | Text for screen readers describing the close action of the menu. |
+| `color` | `string \| undefined` | — | no | Component color |
+| `counter` | `string \| number \| boolean \| undefined` | — | no | Character counter. Accepts a boolean, a number or a string |
+| `counterValue` | `number \| ((value: any) => number) \| undefined` | — | no | Custom counter value. Either a number or a function computing it from the current value |
+| `customFilter` | `FilterFunction \| undefined` | — | no | Your own value filtering function. Receives the value, the search query and the item, returns a match or `-1` |
+| `customKeyFilter` | `FilterKeyFunctions \| undefined` | — | no | Separate filtering functions for specific item keys — an object of the form `{ key: function }` |
+| `description` | `string \| undefined` | — | no | Description of the component, shown under the label |
+| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
+| `eager` | `boolean \| undefined` | — | no | Renders the menu content upfront, without waiting for the first opening. |
+| `ellipsis` | `boolean \| undefined` | — | no | In multiple mode keeps the selected values on a single line with an ellipsis |
+| `error` | `boolean \| undefined` | — | no | Error state |
+| `errorMessages` | `string \| readonly string[] \| null \| undefined` | `[]` | no | Puts the component into the error state and passes custom error messages. They are merged with any checks defined in the `rules` prop. This field does not trigger validation. |
+| `filterKeys` | `FilterKeys \| undefined` | `['title']` | no | Item keys the search runs over. By default filtering goes by the item title |
+| `filterMode` | `FilterMode \| undefined` | `'intersection'` | no | How the results of `customKeyFilter` and of the general filtering are combined: by intersection, by union or by replacement |
+| `focused` | `boolean \| undefined` | — | no | Controls the focus state of the component. When `true`, the component is considered focused and may apply the corresponding styles or behavior. |
+| `hideDetails` | `boolean \| "auto" \| undefined` | — | no | Hides the details block (messages and hints). With the 'auto' value the block is hidden when there are no messages |
+| `hideMessages` | `boolean \| undefined` | — | no | Hide the messages under the input |
+| `hideNoData` | `boolean \| undefined` | — | no | Hides the menu and the "no data" placeholder when the item list is empty. |
+| `hideSelected` | `boolean \| undefined` | — | no | Hides the already selected items from the menu list. |
+| `hint` | `string \| undefined` | — | no | Hint text shown under the input |
+| `iconColor` | `string \| boolean \| undefined` | — | no | Icon color. Accepts a boolean or a color string |
+| `id` | `string \| undefined` | — | no | Unique identifier of the component |
+| `isSelectAll` | `string \| boolean \| undefined` | `false` | no | Adds a "select all" entry as the first item of the list (for `multiple` only). `true` uses the default `$cds.selectAll` caption, a string sets your own caption. |
+| `itemChildren` | `SelectItemKey` | `false` | no | Object field that holds the child items, or a function that returns them |
+| `itemColor` | `string \| undefined` | — | no | Color of the selected items in the menu list. `color` is used by default. |
+| `itemProps` | `SelectItemKey` | `'props'` | no | Object field that holds the props of the item, or a function that returns them |
+| `items` | `any[] \| undefined` | `[]` | no | Array of items to display |
+| `itemTitle` | `SelectItemKey` | `'title'` | no | Object field used as the item title, or a function that returns it |
+| `itemType` | `SelectItemKey` | `'type'` | no | Object field that defines the item type (`item`, `divider`, `subheader`), or a function that returns it |
+| `itemValue` | `SelectItemKey` | `'value'` | no | Object field used as the item value, or a function that returns it |
+| `label` | `string \| undefined` | — | no | Label text of the component |
+| `listProps` | `CdsListProps \| undefined` | — | no | Props passed through to the inner CdsList component. |
+| `loading` | `string \| boolean \| undefined` | — | no | Loading indicator for the component |
+| `maxErrors` | `string \| number \| undefined` | `1` | no | Maximum number of validation errors shown |
+| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
+| `menu` | `boolean \| undefined` | — | no | Controls the open state of the dropdown menu (v-model:menu). |
+| `menuHeight` | `string \| number \| undefined` | `178` | no | Maximum height of the dropdown menu. |
+| `menuIcon` | `IconValue \| undefined` | `'chevron-down'` | no | Icon indicating that the menu can be expanded. |
+| `menuProps` | `CdsMenuProps \| undefined` | — | no | Props passed through to the inner CdsMenu component. |
+| `messages` | `string \| readonly string[] \| undefined` | `[]` | no | Messages shown under the input |
+| `minWidth` | `string \| number \| undefined` | — | no | Minimum component width |
+| `modelModifiers` | `Record<string, boolean> \| undefined` | — | no | v-model modifiers passed by Vue to process the field value |
+| `modelValue` | `any` | `null` | no | Value of the component in v-model. If the component supports the multiple prop, an empty array is used by default. |
+| `multiple` | `boolean \| undefined` | — | no | Allows selecting several values. The selected items are shown as chips or as a list. |
+| `name` | `string \| undefined` | — | no | Name of the input |
+| `noDataText` | `string \| undefined` | `'$cds.noDataText'` | no | Text shown in the menu when the item list is empty. |
+| `noFilter` | `boolean \| undefined` | — | no | Turns off the built-in filtering — the list is shown as is, the search is handled outside |
+| `openOnClear` | `boolean \| undefined` | — | no | Opens the menu after the value is cleared. |
+| `openText` | `string \| undefined` | `'$cds.open'` | no | Text for screen readers describing the open action of the menu. |
+| `persistentClearable` | `boolean \| undefined` | — | no | Always show the clear button, not only on hover or focus |
+| `persistentCounter` | `boolean \| undefined` | — | no | Always show the counter, not only while the field is in use |
+| `persistentHint` | `boolean \| undefined` | — | no | Always show the hint, not only on focus |
+| `persistentPlaceholder` | `boolean \| undefined` | — | no | Always show the placeholder instead of hiding it while the field is in use |
+| `placeholder` | `string \| undefined` | — | no | Placeholder text shown in an empty field |
+| `prefix` | `string \| undefined` | — | no | Text prefix shown before the field value |
+| `prependIcon` | `IconValue \| undefined` | — | no | Icon in the prepend slot, before the content |
+| `prependInnerIcon` | `IconValue \| undefined` | — | no | Icon in the inner prepend slot, before the content of the field |
+| `readonly` | `boolean \| null \| undefined` | `null` | no | Read-only state |
+| `returnObject` | `boolean \| undefined` | — | no | Return an object in the model value instead of an array |
+| `reverse` | `boolean \| undefined` | — | no | Reverses the order of the elements inside the field |
+| `role` | `string \| undefined` | `'combobox'` | no | ARIA role for the native input element |
+| `rules` | `readonly ValidationRule[] \| undefined` | `[]` | no | Accepts an array of items of different types: functions, booleans and strings. Functions take the input value as an argument and must return either true / false, or a string with an error message. The input goes into the error state if a function returns false (or any value in the array is false) or is a string. |
+| `search` | `string \| undefined` | — | no | Current value of the search query used to filter the items (v-model:search). |
+| `size` | `number \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| undefined` | `'md'` | no | Size of the component |
+| `suffix` | `string \| undefined` | — | no | Text suffix shown after the field value |
+| `textColor` | `string \| undefined` | — | no | Text color of the component |
+| `theme` | `string \| undefined` | — | no | Component theme |
+| `transition` | `string \| boolean \| (TransitionProps & { component?: Component \| undefined; }) \| { component: Component; } \| null \| undefined` | `{ component: CdsModalTransition }` | no | Transition animation |
+| `type` | `string \| undefined` | `'text'` | no | Type of the native input |
+| `validateOn` | `ValidateOn \| undefined` | — | no | Changes the type of the event that triggers validation |
+| `valueComparator` | `ValueComparator \| undefined` | — | no | Function that compares item values to determine the selected state |
+| `width` | `string \| number \| undefined` | — | no | Component width |
+
+**Events**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `update:focused` | `[focused: boolean]` | The focus state of the component changed (v-model:focused). |
+| `update:menu` | `[value: boolean]` | The open state of the dropdown menu changed (v-model:menu). |
+| `update:modelValue` | `[value: any]` | The selected value changed (v-model). |
+| `update:search` | `[value: string]` | The search query changed (v-model:search). |
+| `update:selectedAll` | `[value: boolean]` | The "all selected" state changed (for `multiple` + `isSelectAll` only). |
+
+**Slots**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `append` | `CdsInputSlot` | Adds an element after the input |
+| `append-inner` | `CdsInputDefaultSlot` | Slot added at the end of the input |
+| `append-item` | `any` | Content after the item list in the menu. |
+| `chip` | `{ item: any; internalItem: ListItem<any>; index: number; props: Record<string, unknown>; }` | Custom rendering of the chip of a selected value (relevant together with `chips`). |
+| `clear` | `CdsInputDefaultSlot & { props: Record<string, any>; }` | Slot for a custom clear icon (shown when the clearable prop is true). |
+| `description` | `{ description: string \| undefined; props: Record<string, any>; }` | Default slot of the CdsDescription component |
+| `details` | `CdsInputSlot` | Slot for custom content that lets you customize how the messages are displayed |
+| `divider` | `{ props: Record<string, unknown>; index: number; }` | Custom rendering of a divider in the menu list. |
+| `item` | `{ item: any; internalItem: ListItem<any>; index: number; props: Record<string, unknown>; }` | Custom rendering of an item of the menu list. |
+| `label` | `{ label: string \| undefined; props: Record<string, any>; }` | Default slot of the CdsLabel component |
+| `loader` | `LoaderSlotProps` | Slot for a custom loader (shown when the loading prop is true). |
+| `menu-footer` | `{ search: Ref<string \| undefined, string \| undefined>; filteredItems: ListItem<any>[]; }` | Content of the menu footer. Receives the current search query and the filtered items. |
+| `menu-header` | `{ search: Ref<string \| undefined, string \| undefined>; filteredItems: ListItem<any>[]; }` | Content of the menu header. Receives the current search query and the filtered items. |
+| `message` | `CdsMessagesSlots` | Slot for customizing the content of a message |
+| `messages` | `CdsInputSlot` | Slot for custom content that lets you customize how the messages are displayed |
+| `no-data` | `any` | Content shown in the menu when the item list is empty. |
+| `prepend` | `CdsInputSlot` | Adds an element before the input |
+| `prepend-inner` | `CdsInputDefaultSlot` | Slot added at the start of the input |
+| `prepend-item` | `any` | Content before the item list in the menu. |
+| `selection` | `{ item: any; internalItem: ListItem<any>; index: number; }` | Custom rendering of the selected value inside the field. |
+| `subheader` | `{ props: Record<string, unknown>; index: number; }` | Custom rendering of a group subheader in the menu list. |
+
+**Exposed**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `controlRef` | `HTMLElement \| undefined` | Ref to the control of the input |
+| `fieldIconColor` | `string \| undefined` | Icon color |
+| `filteredItems` | `ListItem<any>[]` | Items filtered by the current search query. |
+| `isDirty` | `boolean` | Whether the input is dirty |
+| `isDisabled` | `boolean` | Whether the input is disabled |
+| `isFocused` | `boolean` | Whether the component is focused. |
+| `isPure` | `boolean` | Whether the search query has not changed since the last selection. |
+| `isReadonly` | `boolean` | Whether the input is read-only |
+| `isValid` | `boolean \| null` | Whether the input is valid |
+| `isValidating` | `boolean` | Whether the input is being validated |
+| `reset` | `() => Promise<void>` | Resets the input to its initial state |
+| `resetValidation` | `() => Promise<void>` | Resets the validation of the input |
+| `selectAll` | `() => void` | Toggle the selection of all available items (for `multiple` + `isSelectAll` only). |
+| `validate` | `(silent?: boolean) => Promise<string[]>` | Validates the input |