recursica-skill-link
Rules for the Recursica link — link versus button, labels that name the destination, external and download links, new tabs, never disabled, and link accessibility. Use for any text or control the persona clicks to go to a different location. Not for actions that change data — see recursica-skill-button.
- License 许可
- MIT
- 最近更新
- 2026-11-09
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- recursica-skill-link
- license
- MIT
- metadata
- { "author": "hi@borderux.com", "version": "0.2.0" }
- description
- Rules for the Recursica link — link versus button, labels that name the destination, external and download links, new tabs, never disabled, and link accessibility. Use for any text or control the persona clicks to go to a different location. Not for actions that change data — see recursica-skill-button.
03 SKILL.md 正文
Link
A link takes the persona to a different location, such as another page. A link never changes data.
When to use a link
- The link goes to a different location. The new location is another page, a section of the same page, an outside website, or a file to download.
- The link sits inside a sentence. The link goes to a source, a definition, or a related object the text mentions. For example, "Acme Corp" in "Ordered by Acme Corp" links to the customer's page.
- The link stands apart from any sentence, as in a menu, a footer, or a "view all" link beside a heading.
- The persona goes from a table row to a related object, such as from an order to the order's customer. A link has less visual weight than a button. A dense table needs less visual weight in each table row.
When not to use a link
| Situation | Use instead |
|---|---|
| A control changes data or state | A button. See recursica-skill-button. |
| A control that changes data or state needs less visual weight | A button in the least prominent button style, such as text in the standard UI kit (the unchanged UI kit in the official Recursica release). Do not use a link. |
| A control opens a modal on the same page | A button. See "Modal triggers" in recursica-skill-buttons-links. |
| A link's destination is unavailable right now | Leave the link out, or explain in text why the destination is unavailable. Never disable the link. |
| The persona switches between parts of one whole on one page, such as an order's Details and History | Tabs. Each tab has a separate route. See recursica-skill-tabs. |
Watch for a link that changes state. Build Save, Delete, Close, and Apply as buttons, even when a link would look better.
Variants
Use only the link 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. The names in the standard UI kit are examples only.
- The visited state shows a link the persona has opened before. The standard UI kit calls the visited state
visited. - Never disable a link, even when a designer adds a disabled state to the theme in Theme Forge. The rule "Never disable a link" under "Rules" gives the reason.
- The browser and the link component set each part of the link's look and behavior not named in this list.
- An icon may sit before or after the link's label. Only the design-system website shows the two icon positions.
- The design-system website shows two kinds of link: internal and external. Only the website shows the two kinds. An internal link goes to a location within the product, such as the Orders page. An external link is marked as leaving the product.
Rules
Always give a link a real href, never a click handler on text. The href is the address the link goes to. With a real href, the persona can:
- right-click or middle-click the link
- open the link in a new tab
- copy the link address
- see the browser's preview of the destination.
With a real href, assistive technology also announces the link as a link.
Write the label as the name of the destination, with no verb. Write "Billing settings", not "Go to billing settings". Never write "Click here" or "Learn more". The persona decides what to do after arriving at the destination.
Give each link a unique label that makes sense without the text around the link. For example, write "Invoice 1042", not "View". Personas using a screen reader bring up a list of the page's links, without the text around each link. Three links that all say "View" tell a persona using a screen reader nothing.
Never open a new tab automatically, unless a new tab is clearly the only possible behavior. The persona chooses a new tab with the browser's context menu or a modifier key, such as Ctrl or Cmd.
Mark an external link as external. An external link leaves the product, such as a link to an outside help site. The mark tells the persona, before the persona clicks, that the link leaves the product. No rule yet sets the icon or the wording for the mark. See the open questions.
Never disable a link. The persona can always go to a related object. If the destination should not exist for the persona viewing the page, do not show the link at all. For example, a persona with no billing access sees no "Billing settings" link. See recursica-skill-navigation.
A link can be the primary call to action (CTA) when the CTA goes to a new location. A CTA is the main button or link that prompts the persona's next step. A prominent CTA that goes to a new location is still a link. For example, a "Pricing plans" CTA on a home page opens the pricing page. The CTA stands out because of the layout, not because the link is restyled to look like a button.
Accessibility
The rules below add to the accessibility baseline in recursica-skill-design-system-conventions, which every Recursica component follows.
Every Recursica link already shows the underline, the color, and the focus ring. The app's code writes the HTML markup for each link. A link built from the wrong HTML element fails with every kind of assistive technology.
Screen readers
- Every link must be a real anchor (the HTML element for a link) with an
href. Adivorspanwith a click handler is not announced as a link. Thedivorspandoes not appear in a screen reader's list of links. The keyboard cannot reach thedivorspan. - The accessible name (the name a screen reader reads out for a control) must name the destination. The accessible name must make sense when read completely out of context. "Click here" is forbidden, because "Click here" makes no sense out of context. In a list of links, a persona using a screen reader cannot use a "Click here" link.
- Two links with the same name must go to the same destination. Some links to different destinations share a label, such as two reports named "Q3 report" in different folders. The accessible name or the context of the row holding the link must tell those links apart. For example, the accessible name of each link names the folder, such as "Q3 report, Finance folder".
- An icon inside a link must be hidden from screen readers, unless the icon is the link's only content. The hidden icon is decorative. An icon that is the link's only content must have the link's accessible name.
- If a link opens in a new tab or downloads a file, state the new tab or the download. For example, write "Help center (opens in a new tab)". Put the statement in the accessible name or in text right next to the link. A persona using a screen reader has no visual sign that the window changed. A new tab or a download that nobody announces confuses that persona.
- Never mark an external link by color or icon alone.
recursica-skill-design-system-conventionsrequires a second channel (color, shape, position or text, each a separate signal).
Keyboard and non-mouse navigation
- Every link is a tab stop (a place the Tab key lands) because every link has an
href. Do not remove a link from the tab order. Never add a tabindex to force an order. - Enter activates a link. Space does not. Browsers activate a link with Enter only, and the browser behavior is correct. A link that needs a Space handler is a button.
- Do not intercept the modifier keys. Ctrl, Cmd, Shift, and middle-click must reach the browser. The persona then decides where the destination opens, such as in a new tab.
- A link that appears only on hover cannot be reached by keyboard or by touch. Links inside text and in rows, such as table rows, must stay visible.
- Focus must be visible on the link. The underline alone does not show focus. Never hide the focus ring.
- After navigation, focus belongs at the start of the new content, not on the old page.
Styling set by tokens
Never set or override the link's styling. The theme sets every visual property of the link, such as size, spacing, borders, colors and animation. Do not add extra containers or spacers to change the link's look. If the theme does not give a look the design needs, report the missing look as a design-system gap. See recursica-skill-design-router.
Related skills
recursica-skill-buttons-links— link versus button, label wording, links in table rows, new tabs, and buttons that open a modal.recursica-skill-navigation— routes, browser history, permissions, and where links go in the app shell.recursica-skill-design-system-conventions— never show a meaning in only one way.
Open questions
- The icon for an external link. No rule says which icon marks an external link, or whether the icon is required or optional.
recursica-skill-icon-semanticssets what icons mean, but names no icon for an external link. - Download links. No rule says whether a download link shows the file type and size, or where.
- A size or emphasis style for links. No rule says whether a link may have a size variant or an emphasis style. Confirm a size variant with the user only when the theme has no size variant. Confirm an emphasis style with the user only when the theme has no emphasis style.
- Links inside a paragraph in a table cell. No rule covers a link inside a sentence in a cell of a dense table.
Pre-flight checklist
- [ ] No action that changes data or state is built as a link.
- [ ] Every link is a real anchor with a real
href. - [ ] Every link label names the destination, has no verb, and makes sense out of context.
- [ ] No two links share a name while going to different destinations.
- [ ] No new tab opens automatically, and the modifier keys are not intercepted.
- [ ] Every external link is marked as external, and every download link is marked as a download. Neither mark relies on an icon or color alone.
- [ ] No link is disabled. Each link to an unavailable destination is left out, or text on the page explains why the destination is unavailable.
- [ ] No link appears only on hover, and the focus ring shows on every focused link.
- [ ] After navigation, focus lands at the start of the new content.
- [ ] Every variant and state is one the knowledge MCP server lists for the theme, under the name the code uses.
- [ ] No variant or option is invented.
- [ ] No styling is set or overridden on the link.
- [ ] No container or spacer is added to change the link's look.
- [ ] Open questions were asked about, not decided: the icon for an external link, download links, a size or emphasis style for links, and links inside a paragraph in a table cell.
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.