AGENT SKILL

recursica-skill-chip

Rules for the Recursica chip — when to use chips, the selected and unselected states, selectable versus removable chips, why a chip never shows a status, chip group size, and chip group accessibility. Use for filter chips, tags, and a horizontal multi-select. Not for a read-only value — see recursica-skill-badge. Not for one choice — see recursica-skill-segmented-control.

License 许可
MIT
最近更新
2026-11-09
Stars
★ 1
Forks
0

01 前言 Front Matter

name
recursica-skill-chip
license
MIT
metadata
{ "author": "hi@borderux.com", "version": "0.2.0" }
description
Rules for the Recursica chip — when to use chips, the selected and unselected states, selectable versus removable chips, why a chip never shows a status, chip group size, and chip group accessibility. Use for filter chips, tags, and a horizontal multi-select. Not for a read-only value — see recursica-skill-badge. Not for one choice — see recursica-skill-segmented-control.

03 SKILL.md 正文

Chip

A chip is one of several short values the persona can see, select, or remove, such as the tag "Marketing".

When to use a chip

  • Use chips for a field that could hold more than one value. For example, use chips for tags, categories, or applied filters on one object. Use chips even when the field holds one value now.
  • Use selectable chips when the persona picks several options laid out side by side in a row. For example, the chips "Email", "SMS" and "Push" let the persona pick any of the three. Never lay out a checkbox group in a horizontal row.
  • Use chips when the persona filters or narrows down the content on the screen by turning options on and off. For example, the chips "In stock" and "On sale" narrow a product list.
  • Use chips when the persona added the values, and may remove the values again. For example, the persona adds tags to a document and can remove each tag later.

When not to use a chip

Situation Use instead
One read-only value that the application sets A badge. See recursica-skill-badge.
One choice that rules out every other option A segmented control for options laid out horizontally, or radio buttons for options stacked vertically. See recursica-skill-segmented-control.
A status of any kind A badge. See recursica-skill-badge. Never show a status in any element the persona can act on.
A value that is only ever single, and space is tight, as in a table row A badge. See recursica-skill-badge. A chip takes more room, with an icon and a close control (the control that removes the chip).
More options than one row of chips can hold A dropdown or an autocomplete. See recursica-skill-selection-controls.
Primary navigation, or a label such as "New" on a navigation item Links for navigation, and a badge for the label on a navigation item.

Never show a status as a chip. Watch for a status shown as a chip. For example, show the status "Shipped" on an order as a badge, not as a chip. A chip looks like a control the persona can click. A status is not for the persona to change.

Variants

Use only the chip variants and options that the knowledge MCP server lists for the theme (the design a designer sets in Theme Forge: the token values, the components, and each component's variants, states and sizes). A designer can add variants and options in Theme Forge, so each theme can differ. Get the list with the server's component_api tool, and use the names the code uses. Never invent a variant or an option.

The rules below describe each option by role, such as "the selected state". The names in the standard UI kit (the unchanged UI kit in the official Recursica release) are examples only.

  • A chip is either unselected or selected. In the standard UI kit, the two selection states are unselected and selected.
  • A chip is set up as a selectable chip or as a removable chip. A removable chip has a close icon. Only the design-system website shows the two chip setups.
  • A chip can show an optional icon before the label.

Never set the chip's error state. recursica-skill-badges-chips says never to use a chip to show an error. To report a missing selection in a required chip group, follow the validation rule under "Rules".

This skill describes the error state only so that an agent recognizes the error state in the code. The error state is never an option to set.

  • The UI kit and both Recursica component libraries (one for each framework) define an error state for the chip. The house rule against the error state still applies. The house rule does not remove the error state from the UI kit or the component libraries.
  • An error setting in the code is the error state, not a typo. Both component libraries offer an error setting that applies the error state.
  • The error state combines with either selection state. Error and selection are separate variants. The UI kit defines the error state separately for an unselected chip and for a selected chip.
  • In the standard UI kit, the error state is called error and sits under each selection state. "Error-selected" is the error state on a selected chip, not a fourth state. The error state sits under each selection state because the error state combines with the selected state.

Rules

Give every chip in one group the same type of value. For example, a Tags cell in a table holds only tags. Never mix types, such as a tag and a category, in one group of chips.

Use a badge, not a chip, for a value that is only ever single. A single chip is fine when the field could hold more values. A value the persona can select or remove is always a chip.

Keep a chip group to 7 ± 2 options, and use fewer options when the choice is complex. See recursica-skill-working-memory.

Let the persona remove a chip only when the persona added the chip. The persona must not remove a value the application set. For example, the persona can remove a tag the persona added, but not a category the application assigned.

Never show an error as a chip, and never use a chip to report an error. For example, never show "Upload failed" as a chip. recursica-skill-badges-chips forbids an error condition as the content of a chip. A chip never tells the persona about a problem.

When a required chip group has no chip selected, show a form validation error below the chip group. For example, "Pick at least one category" appears below a "Categories" chip group. Every other form control shows a validation error the same way. recursica-skill-forms sets this rule.

  • Put the error message in the chip group's assistive element, below the chip group. See recursica-skill-assistive-element.
  • Write the error message to restate the rule the persona must meet.
  • Show a signal in the error message that is not color.
  • Never change the look of any chip to report the error.

The error belongs to the chip group, not to any chip in the chip group. This validation rule therefore does not conflict with the rule against errors on chips.

Apply the rules for a checkbox group to selectable chips. recursica-skill-selection-controls holds the checkbox group rules. The checkbox group rules cover three topics:

  • the limit on the number of options
  • caution with options selected in advance
  • how the form saves

The chip selections save the same way as every other field. If the form saves every field together, the chip selections save when the persona submits the form. See recursica-skill-forms.

Write each chip label as a noun of one or two words, such as "Marketing" or "Remote work". Never put a verb, a sentence or a count in a chip label. For example, write "Marketing", not "Show marketing" or "Marketing (12)". The chip has a maximum width, which limits how long a chip label can be. The maximum width is one more reason to keep phrases out of a chip.

Never mix selectable chips and removable chips in one chip group. Give each chip group one behavior. In a mixed chip group, the persona cannot see which chips select a value and which chips remove a value.

Show applied filters as chips the persona can remove. For example, after the persona filters products by the category Shoes, a "Shoes" chip shows the applied filter. When the persona removes a filter chip:

  • The filter runs again.
  • The matching filter control clears too.

The filter chip and the filter control share one state.

Accessibility

The rules below add to the accessibility baseline in recursica-skill-design-system-conventions, including the focus ring, which every Recursica component follows.

A chip group must behave like every other form control. A chip group is a form control laid out horizontally. The most common failure is a group of clickable div elements with a colored selected state. A persona not using a mouse cannot find or use chips built as clickable div elements with a colored selected state.

Screen readers

  • A screen reader must announce a selectable chip group as a group of checkboxes. A selectable chip group is a group of checkboxes. Give the chip group an accessible name (the name a screen reader reads out for a control). Each chip announces the chip's label and whether the chip is selected.
  • Give the chip group a label, such as "Categories". Without a label, the persona hears a list of options and does not know what the options are for.
  • Mark the selected state in the code, not only by color on the screen. A persona using a screen reader cannot tell selected chips from unselected chips by fill color alone. recursica-skill-design-system-conventions forbids showing the selected state only by color.
  • Give the close control of a removable chip an accessible name that includes the chip's value, such as "Remove Marketing". Never name the close control "Remove" alone, and never leave the accessible name empty. A row of five close controls that are each named "Remove" cannot be used.
  • Give the close control of a removable chip a tooltip, such as "Remove Marketing". Every icon-only button gets a tooltip. See recursica-skill-icon-semantics.
  • Announce each chip removal. After a chip is removed, the persona needs to know that the chip is gone and which chips are left. For example, announce that the "Marketing" chip was removed and that "Design" and "Research" are left. Without an announcement, a persona using a screen reader cannot tell a removal from a click that failed.
  • Keep the leading icon (an optional icon before the label) silent to a screen reader. The leading icon is decorative, and the chip label gives the meaning.
  • If a chip shows no count of matching results, do not announce that count as part of the chip. For example, a "Marketing" chip with no count on the screen is read as "Marketing", not "Marketing, 12 results".

Keyboard and non-mouse navigation

  • A persona using a keyboard must be able to reach and use every chip. Space selects or clears a selectable chip. Enter or Space activates the close control of a removable chip.
  • Keep the component library's behavior when the chip group is a single tab stop (a place the Tab key lands) and arrow keys move between chips. Do not add a tabindex to an individual chip. Do not add custom key handling on top of the component library's key handling.
  • The close control of a removable chip is a separate stop for keyboard focus, inside the chip. A persona can reach the close control without a pointer.
  • After a chip is removed, move focus on purpose. Move focus to the next chip. If no chips are left, move focus to the chip group. If focus stays on a removed chip, focus is lost. The persona is then quietly sent back to the top of the page.
  • Never show the close control only on hover. A persona using a keyboard or a persona using touch cannot reach a close control that appears only on hover.

Styling set by tokens

Never set or override the chip's styling. The theme sets every visual property of the chip, such as size, spacing, borders, colors and animation. Do not add extra containers or spacers to change the chip's look. If the design needs a look the theme does not give, report the missing look as a design-system gap. See recursica-skill-design-router.

Related skills

  • recursica-skill-badges-chips — chip versus badge, tags, removable chips and selectable chips, chip-group counts, and where chips go.
  • recursica-skill-selection-controls — when to use selectable chips, and the checkbox group rules that selectable chips follow.
  • recursica-skill-forms — the form's save mode, and how to show the chip group's validation error.
  • recursica-skill-assistive-element — the element below the chip group that shows the chip group's validation error, and the wording of the error.
  • recursica-skill-working-memory — the research behind the limits on the number of options.
  • recursica-skill-design-system-conventions — the accessibility baseline every component follows.

Open questions

  • Whether a chip may be disabled. No rule says whether a chip may be disabled, or what a disabled chip would mean for a filter. Confirm with the user only when the theme has no disabled state.
  • Overflow. No rule says what a chip group does when the chip group has more chips than one row can hold. No rule says whether chips may wrap to a second row.
  • Select-all or clear-all. No rule says whether a chip group supports a select-all or a clear-all control, or where that control would go.
  • A chip that opens a menu. Other design systems document a chip that opens a menu. If the theme has a chip that opens a menu, use that chip. Otherwise, confirm with the user.

Pre-flight checklist

  • [ ] Every chip in a group holds the same type of value, with no mixed types in one table cell.
  • [ ] Chips show a field that could hold more than one value. A value that is only ever single, and that the persona cannot act on, is a badge.
  • [ ] No status, and no error condition, is shown as a chip.
  • [ ] A required chip group's validation error appears in the assistive element below the chip group.
  • [ ] No chip reports the chip group's validation error.
  • [ ] Each chip group holds about 7 ± 2 options, judged by label length, and has one behavior: selectable or removable, never both.
  • [ ] Only chips with values the persona added can be removed.
  • [ ] Every chip label is a noun of one or two words.
  • [ ] Each chip group has an accessible name, and each chip announces the chip's label and whether the chip is selected.
  • [ ] The selected state does not depend on color alone.
  • [ ] Every close control's accessible name includes the value the close control removes, and every removal is announced.
  • [ ] Every chip and every close control works from the keyboard, and nothing in the chip group depends on hover.
  • [ ] Focus moves on purpose after a chip is removed.
  • [ ] Every chip uses only the states and variants the theme lists, and no chip is set to the error state.
  • [ ] No styling is set or overridden on the chip.
  • [ ] No container or spacer is added to change the chip's look.
  • [ ] Open questions were asked about, not decided: whether a chip may be disabled, overflow, select-all or clear-all, and a chip that opens a menu.

04 同仓库更多 Skills

borderux
borderux/recursica-knowledge

recursica-skill-template

Replace with a description of the skill and its purpose.

★ 1
borderux
borderux/recursica-knowledge

recursica-skill-working-memory

The research behind Recursica's item-count limits, with citations — Miller's 7 ± 2, Cowan's 4, chunking, and recognition versus recall. Use when a decision turns on how many options, navigation items, or chips to show at once, or to justify or challenge a count. Not for choosing a control — see recursica-skill-selection-controls.

★ 1
borderux
borderux/recursica-knowledge

recursica-skill-discoverability

The research behind Recursica's rule that rarely needed settings get a real but unpromoted entry point — the paradox of the active user, satisficing (settling for the first method that is good enough), and progressive disclosure, with citations. Use when deciding whether to hide, promote, or build a configuration or customization feature, or to justify that choice. Not for item counts — see recursica-skill-working-memory.

★ 1
borderux
borderux/recursica-knowledge

recursica-skill-design-router

Start here for any Recursica screen work. The router says what to decide in what order, which skill owns each decision, which rule wins when two rules conflict, and when to confirm with the user instead of guessing. Load the router first to design, build, review, or refactor a screen, page, panel, or flow, or when rules seem to disagree or no rule applies. The router routes, and the owning skill holds the rules.

★ 1
borderux
borderux/recursica-knowledge

recursica-skill-undo

House rules for undo — when an action gets an undo instead of a confirmation, where the undo goes (on the page, in place, or in a toast), when a toast is needed at all, and the Undo button's accessible name. Use whenever an action can be reversed, or when choosing between an undo and a confirmation. Not for building the toast that holds an Undo button — see recursica-skill-toast. Not for the confirmation modal — see recursica-skill-buttons-links.

★ 1
borderux
borderux/recursica-knowledge

recursica-skill-typography-semantics

House rules for type and semantic markup — real elements instead of styled divs, one H1 per page, type styles from tokens only, loading the brand typefaces, hidden headings, emphasis with em and strong, abbreviations, and AP style. Use for headings, body copy, emphasis, and the markup under a visual hierarchy. Not for naming — see recursica-skill-names-and-terms.

★ 1