recursica-skill-avatar
Rules for the Recursica avatar — when to show an avatar, avatar styles and fallback order, sizes, and when an avatar is a control or decoration. Use for profile pictures, initials, account-menu buttons, and author markers. Not for the menu an avatar opens — see recursica-skill-menu. Not for status — see recursica-skill-badge.
- License 许可
- MIT
- 最近更新
- 2026-11-09
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- recursica-skill-avatar
- license
- MIT
- metadata
- { "author": "hi@borderux.com", "version": "0.2.0" }
- description
- Rules for the Recursica avatar — when to show an avatar, avatar styles and fallback order, sizes, and when an avatar is a control or decoration. Use for profile pictures, initials, account-menu buttons, and author markers. Not for the menu an avatar opens — see recursica-skill-menu. Not for status — see recursica-skill-badge.
03 SKILL.md 正文
Avatar
An avatar is a small picture that stands for a person or an entity. The picture can be a photo or a pair of initials, for example. An avatar helps personas tell people apart.
When to use an avatar
- The name shows in text near the avatar, and a face makes a list faster to scan. Examples are a comment author, the assignee in a table row or a list row, and a team directory.
- An avatar is the button that opens the account menu (also called the user menu). Opening the account menu is the only case where an avatar is a control.
- A photograph helps personas recognize a person. Examples are the collaborators on a document and the people active on a page right now.
When not to use an avatar
| Situation | Use instead |
|---|---|
| The name alone identifies the record, and the layout has little room | Plain text. In a dense table, a name column works better than a picture. |
| The screen must show status, presence, or a count | A badge beside the name. See recursica-skill-badge. |
| Several people must appear as one overlapping group of avatars | An avatar group variant, if the theme (the design a designer sets in Theme Forge: the token values, the components, and each component's variants, states and sizes) has one. See "Avatar groups" in the open questions. |
| The picture stands for an idea, not a person | An icon. An avatar shows who a person or entity is. An avatar is not an ornament. |
| The avatar would be the only way to tell which person or entity a table or list row belongs to | A name in text, with the avatar beside the name. |
An avatar alone identifies no one. A picture can match more than one person. A pair of initials, such as "PA", can match more than one person too. A persona using a screen reader learns nobody's identity from a picture or from initials. The name in text identifies the person. The avatar helps a persona find the name faster.
Variants
Use only the avatar variants and options that the knowledge MCP server lists for the theme. 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 photo style". The names in the standard UI kit (the unchanged UI kit in the official Recursica release) are examples only.
-
An avatar has three styles, one for each kind of content.
- The photo style shows a photograph.
- The initials style shows initials.
- The icon style shows a generic person icon or a placeholder icon.
In the standard UI kit, the three styles are
image,text, andicon. -
An avatar has three sizes: a smaller size, a default size, and a larger size. In the standard UI kit, the three sizes are
small,default, andlarge. -
Three types apply to the initials style and the icon style only. In the standard UI kit, the three types are
solid,outline, andghost. When to use each type is an open question. -
Use the theme's status option for status and presence, if the theme has one. A status option is a status dot, a presence indicator or a badge slot on the avatar. Otherwise, keep a badge as a separate component. Do not attach the badge to the avatar.
-
If the theme has a group, stack, overlapping-cluster, or shape variant, use that variant. Otherwise, do not build an avatar group out of several avatars.
The design-system website shows a different set of styles, a Border variant and avatar groups. Read the open questions before relying on any style, variant or group from the website.
Rules
Always show the name in text beside the avatar. For example, a comment shows the author's photo with "Person A" written next to the photo. The rule holds in a table row, a list row, a comment, an assignment, and a list. The name in text identifies the person. Showing the name in text is a hard requirement, not a preference.
Use the highest-ranked style that the available data supports. The three styles rank in this order:
- The photo style, when a photo is available.
- The initials style, when the name is known.
- The icon style, only when the name is unknown.
A photo that fails to load must never leave an empty circle. Fall back to the initials style when the name is known. Fall back to the icon style only when the name is unknown.
Initials are not a name. Two people can share the initials "PA". An initials avatar helps a persona spot a name that the screen already shows. An initials avatar never replaces the name.
The icon style shows no identity. An icon avatar means "a person", without saying which person. Use the icon style in two cases:
- for a party who is unknown or unnamed, such as an anonymous commenter
- as the last fallback
Never use the icon style as the usual picture for a known persona.
Decide once whether each avatar is a control or decoration. No avatar is partly a control and partly decoration.
- The avatar that opens the account menu is a control. The avatar is a real button, with a real accessible name (the name a screen reader reads out for a control) and a tab stop (a place the Tab key lands).
- Every other avatar is decoration, such as the avatar beside a comment author's name. A decorative avatar has no click handler and no tabindex. A decorative avatar has no element or ARIA role that makes the avatar a control.
Keep the account menu out of primary navigation. For example, never list "Account" next to "Orders" and "Products" in the main navigation. The account menu is a tool used on every page, not a place to go. recursica-skill-navigation places the account menu in another part of the application chrome (the header, navigation and footer around the content).
Choose the size by how crowded the layout around the avatar is, not by how important the person is.
- Use the smaller size in a table row or a comment.
- Use the larger size in a profile header.
- Do not use size to rank people. For example, do not give a manager a larger avatar than the other people on the team.
Put only initials in an initials avatar, one or two characters. For example, write "PA". Do not put a name, a role, or a count in an initials avatar, such as "Admin" or "+3".
Accessibility
The rules below add to the accessibility baseline in recursica-skill-design-system-conventions, including the focus ring, which every Recursica component follows.
An avatar is either a picture or a control. Each kind of avatar fails a persona using a screen reader in a different way.
- A screen reader can announce a picture avatar as an unlabeled image.
- A screen reader can announce a picture avatar as a repeat of a name the screen reader read before.
- A control avatar can have no accessible name at all.
Screen readers
- If a photo avatar is the only place the name appears, give the photo avatar alternative text. The alternative text names who or what the avatar stands for. Write the name, such as "Person A", not "avatar" and not "profile photo".
- When the name is in text next to the avatar, the avatar is decorative and must be silent. Give the avatar empty alternative text. Hearing "Person A, image, Person A" is worse than hearing nothing. The repeat happens in every row of a list.
- A screen reader must never announce the initials in an initials avatar as a person's identity. "PA" tells a persona using a screen reader nothing. The initials are decorative. The screen reader reads the name in text.
- An icon avatar must be silent. An icon avatar shows no identity, so a screen reader has nothing to announce. A screen reader must not announce an icon avatar as "image" or "graphic".
- Give a control avatar a real accessible name that says what using the avatar does. Examples are "Account menu", or the persona's name and what the avatar opens. The picture is not the accessible name. A control with no accessible name is announced only as "button".
- A control avatar counts as an icon-only control. Give a control avatar a tooltip for sighted personas using a mouse. Separately, give the control avatar an accessible name.
recursica-skill-buttons-linksrequires both. - Never make the avatar the only way to tell whose table or list row, comment, or assignment the persona sees. An avatar alone puts meaning in a single visual channel (color, shape, position or text, each a separate signal).
recursica-skill-design-system-conventionsforbids meaning in a single channel. - Do not add a hidden screen-reader copy of the name while the visible name stays in the reading order. The reading order is the order in which a screen reader reads the page. A persona using a screen reader hears the name twice.
Keyboard and non-mouse navigation
- A decorative avatar never receives focus and is skipped in the tab order. A decorative avatar has no tabindex, no click handler, and no role that suggests the avatar can be used.
- A control avatar is a real button or link, is a tab stop, and works from the keyboard. The control avatar's place in the tab order matches the avatar's place on screen, among the elements around the avatar.
- When a control avatar opens a menu, focus moves into the menu. Focus returns to the avatar when the menu closes. See
recursica-skill-menu. - An avatar inside an element the persona can click or select is part of that element's name. Examples of such an element are a link in a table or list row, and a list item. The avatar is not a separate tab stop inside the element.
- Nothing about the avatar may depend on hover. Personas using a keyboard and personas using touch cannot reach a name that appears only in a hover tooltip. The name in text identifies the person, not a hover tooltip.
Styling set by tokens
Never set or override the avatar's styling. The theme sets every visual property of the avatar, such as size, spacing, borders, colors and animation. Do not add extra containers or spacers to change the avatar'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-navigation— keeping the account menu out of primary navigation, what counts as a location, and showing the persona's current location.recursica-skill-buttons-links— the tooltip and accessible name an icon-only control needs, and when to use a button or a link.recursica-skill-tables— which fields get a column.recursica-skill-design-system-conventions— never showing a meaning in a single channel.
Only if used on the same screen
recursica-skill-menu— the menu a control avatar opens, and where focus goes when the menu opens and closes.recursica-skill-badge— showing status and counts as read-only information beside the name.
Open questions
- Two sets of styles that do not agree. Only the design-system website shows styles named Image, Primary, Background, and Ghost. Only the design-system website shows a Border variant that is true or false. The UI kit defines the
text,icon, andimagestyles. The UI kit gives thetextandiconstyles thesolid,outline, andghosttypes. Of the website's styles, only Ghost matches the UI kit, as theghosttype. Nobody has settled which set of styles is the authority. Confirm with the user before relying on either set of styles. - Avatar groups. Only the design-system website shows overlapping avatars in a group. Unless the theme has a group variant, do not build an avatar group. Do not rely on the website's group without confirming with the user.
- Which size belongs in which layout. The rules above place the smaller size and the larger size. No rule says where the default size applies.
- How initials are chosen. No rule says whether initials use one letter or two, or how to handle a one-word, hyphenated, or non-Latin name.
- Avatars for an entity that is not a person. No rule says whether an avatar may stand for an entity that is not a person. Examples are a company, a team, or a system. No rule says which fallback such an avatar uses.
- Presence and status. No rule says how to show presence.
- When to use each type. The standard UI kit defines the
solid,outline, andghosttypes for initials avatars and icon avatars. No rule says when to use each type. Nobody has confirmed that the adapter (the Recursica component library for one framework, such as Mantine or Angular Material) exposes the type as a setting. Check the avatar component's settings, or confirm with the user, before relying on the type.
Pre-flight checklist
- [ ] Every avatar sits beside the name in text. No avatar is the only way to identify a person or record.
- [ ] Each avatar's style matches the available data. The style falls back from the photo style to the initials style to the icon style.
- [ ] A photo that fails to load falls back to initials or the placeholder icon, never to an empty circle.
- [ ] Initials are decoration, never a name, and no known persona gets the icon style.
- [ ] Each avatar is either a control or decoration.
- [ ] A control avatar has a real accessible name and a tab stop.
- [ ] A decorative avatar has no tabindex and no event handler.
- [ ] A decorative avatar has no element or ARIA role that makes the avatar a control.
- [ ] A control avatar has a tooltip and an accessible name. Focus returns to the control avatar when the menu the avatar opened closes.
- [ ] A photo avatar has alternative text naming the person, or is silent with the name in text beside the avatar.
- [ ] Initials avatars and icon avatars are silent, and no avatar is announced as an unlabeled graphic.
- [ ] No name is repeated in a hidden element while the visible name stays in the reading order.
- [ ] Each avatar's size follows how crowded the layout around the avatar is, not how important the person is.
- [ ] The account menu sits outside primary navigation.
- [ ] Every style and size is one the theme's UI kit lists. No avatar has an invented group, status dot, badge slot, or border variant.
- [ ] No styling is set or overridden on the avatar. No container or spacer is added to change the avatar's look.
- [ ] Open questions were asked about, not decided: the two sets of styles, avatar groups, which size belongs in which layout, how initials are chosen, avatars for an entity that is not a person, presence and status, and when to use each type.
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.