Visual
A static circular visual primitive for decorative icon and avatar cues.
Supporting primitive
Use fd-visual when a compact decorative cue helps users scan or group related content faster. The component stays intentionally narrow in v1: it owns the circular surface, size, clipping, and fallback rendering, while the surrounding interface owns the meaning.
When to use
- Decorative icon surfaces — when you want a consistent circular cue next to a card title, list item, or grouped summary.
- Decorative avatar framing — when you need a circular avatar placeholder or clipped image next to nearby identifying text.
- Repeated visual grouping — when a shared size and tone system helps related content feel clearly associated.
When not to use
- Interactive controls —
fd-visualis not a button, toggle, chip, or link in v1. - Standalone semantic images — if the visual must carry meaning on its own, use a different pattern instead of relying on this decorative primitive.
- Managed media APIs — if you need built-in
src,alt, overlays, counters, or richer media composition,fd-visualis too narrow for that job in v1.
Examples
Properties
| Name | Type | Default | Description |
|---|---|---|---|
type | "neutral" | "cool" | "warm" | "avatar" | neutral | Visual treatment for the circular surface. Use avatar when the visual should clip avatar media or render the placeholder avatar fallback. |
size | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | md | Applies one of the fixed Figma size presets for the overall circle and its inner content. |
Slots
| Name | Description |
|---|---|
| (default) | Optional decorative icon or avatar media. Leave empty to use the built-in fallback glyph or avatar placeholder. |
Slot content is decorative in v1. Do not slot interactive controls or content that must be announced independently.
CSS custom properties
| Name | Default | Description |
|---|---|---|
--fd-visual-size | Preset from size | Overrides the rendered circle size. |
--fd-visual-padding | Preset from size | Overrides the inner padding for non-avatar variants. |
--fd-visual-content-size | Preset from size | Overrides the inner content box size for non-avatar variants. |
--fd-visual-radius | 9999px | Corner radius for the circular surface. |
--fd-visual-bg-neutral | light-dark(var(--fdic-color-neutral-300), var(--fdic-color-neutral-800)) | Neutral surface background. Uses a stronger neutral surface than the page background in light and dark themes. |
--fd-visual-fg-neutral | var(--fdic-color-text-primary, #212123) | Neutral foreground color used by the fallback glyph and slotted icon content. |
--fd-visual-bg-cool | light-dark(var(--fdic-color-primary-200), var(--fdic-color-primary-700)) | Cool surface background. Uses a lighter blue in light mode and a darker blue in dark mode. |
--fd-visual-fg-cool | light-dark(var(--fdic-color-primary-900), var(--fdic-color-primary-100)) | Cool foreground color used by the fallback glyph and slotted icon content. Switches with the surface so the glyph remains legible in light and dark themes. |
--fd-visual-bg-warm | light-dark(var(--fdic-color-secondary-300), var(--fdic-color-secondary-900)) | Warm surface background. Uses a lighter warm surface in light mode and a softer dark warm surface in dark mode. |
--fd-visual-fg-warm | light-dark(var(--fdic-color-secondary-900), var(--fdic-color-secondary-050)) | Warm foreground color used by the fallback glyph and slotted icon content. Switches with the surface so the glyph remains legible in light and dark themes. |
--fd-visual-bg-avatar | transparent | Avatar background surface. |
--fd-visual-avatar-placeholder-color | #b0b0b3 | Placeholder avatar silhouette color. |
Shadow parts
| Name | Description |
|---|---|
surface | Outer circular wrapper. |
content | Inner frame that centers slotted media or the fallback visual. |
fallback | Built-in archive glyph or placeholder avatar wrapper when no slot content is supplied. |
fd-visualstays decorative-only in v1 and setsaria-hidden="true"on the host.- For avatar images, prefer empty
alttext when adjacent content already names the subject.
Best practices
Do
Pair the visual with nearby text
The visual should support recognition, not replace the visible label or description that explains the content.
Don't
Turn the circle into a mystery control
Adding click or toggle behavior changes the semantics materially. Use a real interactive component when users must act on the visual.
Do
Use decorative slot content only
Compose fd-icon or an avatar image when needed, but keep that slotted media presentational and non-interactive.
Don't
Rely on color alone for grouping
The tone helps scanning, but users still need nearby text, headings, or layout structure to understand what is related.
Composition guidance
- Default fallback — Non-avatar tones render a built-in archive-style glyph when no slot content is provided. Use that when a generic visual cue is sufficient.
- Custom icon — Slot an
fd-iconwhen you need a different decorative glyph:
html
<fd-visual type="cool" size="lg">
<fd-icon name="download" aria-hidden="true"></fd-icon>
</fd-visual>- Avatar image — Slot an image only when the surrounding UI already names the person or entity:
html
<fd-visual type="avatar" size="xl">
<img alt="" src="/team/jordan-hall.jpg" />
</fd-visual>Accessibility
fd-visualis decorative-only in v1. The host setsaria-hidden="true"and does not create its own accessible name.- The component exposes no keyboard interaction and no tab stop.
- Slotted content should remain presentational. Do not slot focusable controls or content that must be announced independently.
- For avatar images, prefer empty
alttext when adjacent text already names the subject. - Forced-colors mode preserves a visible circular boundary and visible fallback glyph or placeholder silhouette.
Known limitations
fd-visualdoes not support built-insrc,alt,name, orlabelconvenience properties in v1.- The component does not provide overlays, counters, badges, or status markers inside the circle.
- The primitive is intentionally static. Interactive, selectable, or dismissible variations are out of scope.