recursica-skill-accordion
Rules for the Recursica accordion — when collapsing content is justified, collapsed by default, nested only with a theme option, what each part does, and expand and collapse accessibility. Use for accordions, expandable sections, and FAQ lists. Not for multi-level hierarchy — see recursica-skill-tree; not for switching views — see recursica-skill-tabs.
- License 许可
- MIT
- 最近更新
- 2026-11-09
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- recursica-skill-accordion
- license
- MIT
- metadata
- { "author": "hi@borderux.com", "version": "0.2.0" }
- description
- Rules for the Recursica accordion — when collapsing content is justified, collapsed by default, nested only with a theme option, what each part does, and expand and collapse accessibility. Use for accordions, expandable sections, and FAQ lists. Not for multi-level hierarchy — see recursica-skill-tree; not for switching views — see recursica-skill-tabs.
03 SKILL.md 正文
Accordion
An accordion is a list of sections that open and close, such as the questions on an FAQ page. The sections are of the same kind and at the same level. The persona opens only the section the persona needs.
When to use an accordion
- The page has more sections than the persona needs at once. The persona also reads the sections one at a time. For example, a persona on an FAQ page looks for the answer to one question.
- The sections are of the same kind and sit at one level, with no nesting. For example, every section is one question and the question's answer.
- A navigation group with no landing page must show the group's sub-items in place. For example, a Reports group with no page of the group's own opens to show the Sales and Inventory links.
recursica-skill-navigationspecifies the accordion behavior for the navigation group. - A table row has extra detail.
recursica-skill-tablesrequires a single level of expand and collapse on that table row.
When not to use an accordion
| Situation | Use instead |
|---|---|
| The content has more than one level of nesting | A tree. See recursica-skill-tree. |
| The persona needs the content often | The content shown on the page. Content in a collapsed section takes an extra click every time the persona needs the content. |
| The page has little content even with every section open | The content shown on the page, with nothing collapsed. Collapsing a short page only makes the page feel empty. |
| The sections are parts of one whole that the persona switches between | Tabs. See recursica-skill-tabs. |
| The content is a form, or fields from one form | A page, or a stepper for a form with several parts. See recursica-skill-forms. |
| The content is on the critical path (the steps the persona must take to finish the task). The persona must read the content to act. | The page, with the content not collapsed. |
| The content is a short text label for an icon-only control | A tooltip. See recursica-skill-tooltip. |
| The content is too complex or too deep for the available space | A page or a panel. An accordion's content panel is narrow and shallow. |
| The page has more sections than the page has room for | Fewer sections, not smaller sections. See recursica-skill-design-system-conventions. |
Progressive disclosure is for rarely needed content, never for content the persona would want to reach. Progressive disclosure means showing rarely needed content only when the persona asks for the content. For example, a product page can collapse the shipping policy, but never the price.
- A crowded screen is never a reason for progressive disclosure.
- Putting required information inside an accordion is a misuse of progressive disclosure.
recursica-skill-discoverability sets the limit on progressive disclosure.
Variants
Use only the accordion 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 part and option by role, such as "the open look". The names in the standard UI kit (the unchanged UI kit in the official Recursica release) are examples only.
- An accordion has four parts: the outer container, the items, the headers and the content panels. In the standard UI kit, the four parts are
accordion,accordion-item,accordion-headerandaccordion-content. - The outer container is the accordion itself, a list of items.
- An item is one section that opens and closes. Each item has one header and one content panel. For example, on an FAQ page, each question and answer is one item.
- A header is the clickable bar at the top of an item. The header shows the open or closed look, a leading icon, a trailing icon, and the title text.
- A content panel is the area below the header. Clicking the header shows or hides the content panel.
- A header has an open look and a closed look. The standard UI kit calls the variant
appearance, with the optionsopenandclosed.
Rules
Start every item closed when the page loads. The only exception is the navigation group that holds the persona's current page, in a navigation accordion. For example, when the persona is on the Sales report, the Reports group in the side navigation is the exception. recursica-skill-navigation sets the collapsed-by-default rule.
Never nest an accordion inside an accordion unless the theme has a nesting option. recursica-skill-navigation sets the rule against nesting. Without a nesting option, an accordion has one level only.
Use a tree for a real hierarchy, and an accordion for sections at a single level. The choice between a tree and an accordion is settled. Use a tree in either of two cases. See recursica-skill-tree.
- An item's meaning depends on the item's parent. For example, a "Q3" folder means the third quarter of the "2026" folder above the "Q3" folder.
- The number of levels varies.
Two rules hold even when the theme has a nesting option:
- Never use an accordion for a real hierarchy.
- Never nest accordions to show a hierarchy.
Use an accordion when the sections are of the same kind and at one level. A tree would indent sections that have no parent.
Header labels must be specific enough that the persona can choose a section while every section is closed. If the persona has to open a section to learn what the section holds, the label is wrong. Rewrite the label instead of opening the section by default. For example, "Returns and refunds" tells the persona what the section holds. "More information" does not.
Never split a form across accordion items. For example, never put a checkout form's address fields in one item and the payment fields in a second item. Filling in a form is not reading content divided into sections. For the same reason, never split a form across tabs. Use a stepper for a form with several parts. See recursica-skill-forms.
Never close an item automatically after the persona opens the item. For example, the persona opens "Shipping" and then opens "Returns". The "Shipping" item stays open, unless the exception below applies. Do not close the item when the persona does any of these three actions:
- scrolls
- saves
- opens a second item
The one exception is a decision, confirmed with the user, that only one item opens at a time. A single-open option in the theme counts as that decision. Closing an item the persona is reading loses the persona's place on the page. If focus was inside the item's content panel, focus is lost too.
Nothing on the critical path goes inside a content panel. Never collapse content the persona must read to move forward. For example, never collapse the delivery date or the total on a checkout page.
Do not wrap a content panel's content in a card, and do not wrap the accordion in a card. The accordion item shows where the item's content starts and ends. See recursica-skill-card.
Keep the list of headers easy to scan. Above about nine headers, the persona can no longer take in the list at a glance. recursica-skill-working-memory explains what the limit of about nine means and does not mean.
Use the chevron in each accordion header. A chevron is the small arrow in each header that turns when the item opens or closes. Do not add any other open-or-closed indicator, such as a plus sign or a minus sign. The chevron must not be the only sign that an item is open or closed.
Accessibility
The rules below add to the accessibility baseline in recursica-skill-design-system-conventions, including the focus ring, which every Recursica component follows.
The accordion shows the header and the chevron. The app that uses the accordion does two more jobs:
- Make each header a real button.
- Hide a closed item's content from the keyboard and from screen readers.
Apps get the two jobs wrong more often than any other accordion rule.
Screen readers
- The header must be a real button, never a
div, aspan, or a bare heading with a click handler. Only a real button is announced as a button and responds to Enter and Space automatically. Any other element needs custom code to be announced as a button and to respond to Enter and Space. - Each header must announce whether the header's item is expanded or collapsed. For example, a screen reader reads "Shipping, button, collapsed". The announcement must change the moment the item opens or closes. A header that always announces "collapsed" is worse than a header that announces nothing.
- Each header must be connected in code to the header's content panel. A persona who hears "expanded" can then get to the open content panel.
- Never show the open or closed state with the chevron alone. A rotating chevron is a single visual channel (color, shape, position or text, each a separate signal).
recursica-skill-design-system-conventionsforbids a single channel for any meaning the persona must receive. - The header's accessible name (the name a screen reader reads out for a control) is the section title. The section title must make sense without the other headers. For example, "Returns" makes sense with no other header, but "Part 2" does not. A screen reader announces the accessible name with no neighboring headers for context.
- If the header sits inside a heading, put the button inside the heading, not the heading inside the button. A button wrapped around a heading loses the heading level. The heading then disappears from a screen reader's list of headings.
- Content inside a closed item must be unreachable, not only invisible. Zero height, zero opacity, or moving the content off the screen leaves the text in the accessibility tree (the version of the page that assistive technology reads). A persona using a screen reader then reads a section that a sighted persona cannot see. Remove a closed item's content from the accessibility tree.
- A leading or trailing icon that shows information needs an accessible name. A decorative icon must be silent. A screen reader must not announce a decorative icon as an unlabeled graphic.
Keyboard and non-mouse navigation
- Enter and Space both open and close an item. Do not intercept, remap, or block either key.
- Each header is a separate tab stop (a place the Tab key lands). The accordion is not one tab stop shared by all the headers. Every header must be reachable with Tab.
- The tab order runs from a header to that header's content when the item is open, then the next header. Do not put all the headers first and all the content panels after the headers in the page's code. The tab order must match the visual order.
- A closed item's content is completely out of the tab order. The rule matches the screen reader rule that a closed item's content must be unreachable. Tabbing into invisible content is the most common accordion failure.
- Do not move focus when an item opens or closes. Keep focus on the header the persona activated. Do not move focus into the content panel.
- Never close an item whose content has focus. If a single-open accordion closes an item the persona is working in, focus is lost. The persona using a keyboard then starts again from the top of the page.
- Never open an item on hover. No content the persona needs inside a content panel may appear only on hover.
Styling set by tokens
Never set or override the accordion's styling. The theme sets every visual property of the accordion, such as size, spacing, borders, colors and animation. Do not add extra containers or spacers to change the accordion's look, including the chevron and the chevron's turn. 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-navigation— five navigation topics:- the rule against nesting
- items collapsed by default
- sub-navigation that opens on click rather than hover
- permissions
- why a top-level item with no children stays a link
recursica-skill-discoverability— progressive disclosure, and the three cases where hiding content is not safe.recursica-skill-working-memory— 7 ± 2 as the most items a persona can scan at a glance, and what the 7 ± 2 guideline does not claim.recursica-skill-design-system-conventions— two conventions:- never show a meaning in a single channel
- fix the structure instead of collapsing content to work around the structure
Only if used on the same screen
recursica-skill-tree— the component for a real hierarchy, and for any content that is not one level of same-kind sections.recursica-skill-tabs— parts of one whole, and why no form is split across sections.
Open questions
- Whether opening one item closes the other items. The rule above keeps each item open until the persona closes the item. If the theme has a single-open option, confirm with the user before using the option.
- Whether the divider between items can be hidden. Only the design-system website mentions hiding the divider. The website says the divider "can be hidden if accordion is the last child in a list or accordion group". If the theme has an option to hide the divider, use the option. Otherwise, do not hide the divider without confirming with the user.
- How to show an item the persona cannot open right now.
recursica-skill-navigationsays to disable an item the persona can unlock. If the theme has a disabled look for the header, use the disabled look. Otherwise, confirm with the user. - Animation for opening and closing an item. No duration or easing is defined.
- Whether an item can be linked to directly, so that a shared URL opens a specific item.
- Whether an accordion may sit inside a table row, given the single-level expand and collapse that
recursica-skill-tablesasks for.
Pre-flight checklist
- [ ] Collapsing the content is justified. The persona does not need the collapsed content often, and the page is not sparse.
- [ ] The accordion is one level deep unless the theme has a nesting option, and every real hierarchy uses
recursica-skill-treeinstead. - [ ] No form, and no part of one form, is split across accordion items.
- [ ] Nothing on the critical path is inside a content panel. No content the persona needs exists only inside a content panel.
- [ ] Every item loads collapsed, except the group that holds the current page in a navigation accordion.
- [ ] Each header label is specific enough to choose a section while every section is closed.
- [ ] No item the persona opened closes automatically, and no item whose content has focus is ever closed.
- [ ] The list of headers is easy to scan, and no card wraps the accordion or the accordion's content.
- [ ] Every header is a real button and announces whether the item is expanded or collapsed. Every header is connected to the header's content panel.
- [ ] The open or closed state is shown by more than the chevron. Every icon that shows information has an accessible name, and every decorative icon is silent.
- [ ] Enter and Space both open and close an item, and each header is a tab stop.
- [ ] The tab order runs from a header, to the open item's content, to the next header. The tab order matches the visual order.
- [ ] A closed item's content is removed from the accessibility tree and the tab order, not only hidden.
- [ ] Focus never moves when an item opens or closes, nothing opens on hover, and the focus ring is intact.
- [ ] Every variant, size, and state is one the knowledge MCP server lists for the theme. No header has an invented disabled look.
- [ ] No styling is set or overridden on the accordion. No container or spacer is added to change the accordion's look.
- [ ] Open questions were asked about, not decided: whether opening one item closes the other items, whether the divider can be hidden, an item the persona cannot open, animation for opening and closing an item, linking directly to an item, and an accordion inside a table row.
04 同仓库更多 Skills
recursica-skill-template
Replace with a description of the skill and its purpose.
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.
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.
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.
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.
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.