Cloaked Design SystemPrimitives / Iconography

Icon

The opinionated render of a Symbol: a Glyph at a token size with semantic colors and decorative or meaningful accessibility.

Implementation preview

COMPLETE STORYBOOK REFERENCE

Every example. In one place.

Explore every named example, including states, compositions, and theme variants.

7 stories

Playground selectedOpen canvas

Example source

packages/design-system/src/components/primitives/Icon/Icon.stories.tsxExport Playground

Implementation preview Local Storybook build 0.2.0-preview.1. Source specification status does not approve this runtime.

Stories + source JSON ↗

Local specification source status: preview. Implementation preview pending sign-off.

The opinionated render of a Symbol: a Glyph at a token size with semantic colors and decorative or meaningful accessibility.

Design-owned component contract ↗Version 0.2.0-preview.1 · Implementation preview pending sign-off

Implementation API 1 entry point · source-derived preview

Read the actual callable API and preserve its composition constraints. Each union branch is a complete alternative; props marked forbidden cannot be supplied.

import { Icon } from '@cloakedinc/design-system';

IconIconProps

packages/design-system/src/components/primitives/Icon/Icon.tsx:43

Prop	Type	Presence	Notes
`name`	"number" \| "info" \| "guard" \| "arrow-left" \| "arrow-right" \| "arrow-up" \| "arrow-down" \| "chevron-down" \| "chevron-up" \| "chevron-left" \| "chevron-right" \| "caret-down" \| "caret-up" \| "trend-up" \| "trend-down" \| "collapse" \| "expand" \| "dropdown-collapse" \| "dropdown-expand" \| "close" \| "clear" \| "menu" \| "copy" \| "search" \| "add" \| "share" \| "phone" \| "sim" \| "account" \| "family" \| "home" \| "wifi" \| "cart" \| "vpn" \| "lock" \| "block" \| "timer" \| "check" \| "send" \| "filter" \| "scan" \| "log" \| "trash" \| "missed" \| "call" \| "voicemail" \| "sms" \| "email" \| "data-removal" \| "dark-web-monitoring" \| "cloaked-pay" \| "cloaked-ai" \| "sms-guard" \| "email-guard" \| "call-guard" \| "card" \| "password" \| "bell" \| "circle-outline" \| "dot" \| "settings" \| "clock" \| "mail" \| "message" \| "user" \| "upload"	Required	Registered glyph to render; an unregistered name renders nothing at all.
`size`	`IconSize`	Required	Named tier — 16, 24, or 32px from the size tokens — or a raw px number.
`color`	`"success" \| "danger" \| "brand" \| "primary" \| "secondary" \| "ai-primary" \| "ai-secondary" \| "inherit" \| undefined`	Optional	Semantic color token. Omit to inherit the surrounding `currentColor`.
`strokeWidth`	`string \| number \| undefined`	Optional	Stroke width passed to stroke-based glyphs.
`label`	`string \| undefined`	Optional	Accessible label; omitted icons are hidden from assistive tech.
`ariaLabel`	`string \| undefined`	Optional	Accessible label alias for consumers standardizing on aria prop names.
`className`	`string \| undefined`	Optional
`style`	`React.CSSProperties \| undefined`	Optional
`testId`	`string \| undefined`	Optional	Selector forwarded to the rendered svg element.

Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source.

Complete contract · JSON ↗Guidance and source · Markdown ↗

Overview

The opinionated way to render a Symbol: a Glyph at a chosen token or numeric size with an optional semantic color. This is the default icon for foreground UI. Glyphs inherit the surrounding currentColor unless you set a semantic color token.

When to use

Reach for Icon for essentially every glyph in web/foreground UI — it is the DS-owned set, so any name you pick is guaranteed to render and to recolor with --cds-text-* tokens. It is the far more common choice in-app (used across DetailBottomSheet, BrokerDetail, the Home widgets, and the WebsiteData/Exposures views).

Want the drawing with no styling at all — sized and colored by its context? Use Glyph (documented on the Symbol page, which also hosts the full catalogue for picking a name).
Need a glyph in a tone circle? Use IconTile.
Need an actual Apple SF Symbol for native-feeling iOS chrome? Use SFIcon instead — but only when the specific symbol matters, since its set is limited to SUPPORTED_SF_SYMBOLS.
Pass label/ariaLabel for a meaningful icon; omit both to leave a decorative one aria-hidden.

Component specification

$schema

../../../specs/component-spec.schema.json

Parts

Id: svg
Label: SVG
Description: The rendered element: Icon applies the size and semantic color classes and forwards the accessible label.

Id: glyph
Label: Glyph
Description: The underlying Glyph atom; owns the view box, accessibility mechanics, and the paths registered for the selected GlyphName.

Allowed Design Choices

Variants

Base

Label: Base
Description: The glyph name changes content without changing the component treatment.

Sizes

Small

Label: Small

Medium

Label: Medium

Large

Label: Large

Colors

Primary

Label: Primary
Description: Default-emphasis icon foreground.

Secondary

Label: Secondary
Description: Lower-emphasis icon foreground.

Ai primary

Label: AI primary
Description: Primary icon foreground on the AI surface.

Ai secondary

Label: AI secondary
Description: Supporting icon foreground on the AI surface.

Brand

Label: Brand
Description: Brand-accent icon foreground.

Success

Label: Success
Description: Positive outcome icon foreground.

Danger

Label: Danger
Description: Error or destructive icon foreground.

Inherit

Label: Inherit
Description: Uses the current color supplied by the parent.

Variants

Id: base
Label: Base
Description: A registry-backed SVG glyph that inherits or selects a semantic foreground.
Platforms: ios
android
web

Sizes

Id: small
Label: Small
Description: 16-unit glyph for compact inline content.

Id: medium
Label: Medium
Description: 24-unit default glyph.

Id: large
Label: Large
Description: 32-unit prominent glyph.

Measurements

Id: small-size
Label: Small glyph size
Kind: exact
Token: --cds-size-16
Value: 16
Unit: px
Applies To: svg
small

Id: medium-size
Label: Medium glyph size
Kind: exact
Token: --cds-size-24
Value: 24
Unit: px
Applies To: svg
medium

Id: large-size
Label: Large glyph size
Kind: exact
Token: --cds-size-32
Value: 32
Unit: px
Applies To: svg
large

Id: numeric-size
Label: Numeric size escape hatch
Kind: example-only
Value: 40
Unit: px
Applies To: svg
numeric-size
Notes: Use a named token size by default; a finite numeric logical size is available for exceptional composition needs.

Layout

Alignment: The SVG occupies a square and aligns according to its parent layout.
Flow: The glyph is a non-shrinking inline visual with overflow visible for registered strokes.
Notes: Composite components should pass Icon through a named slot rather than restyling path data.

Typography And Color

Typography

Label: Adjacent caption
Description: Icon catalog captions and compact visible labels use the body-small ramp.
Token: --cds-type-body-small-size

Colors

Label: Primary
Description: Default-emphasis icon foreground.
Token: --cds-text-primary

Label: Secondary
Description: Lower-emphasis icon foreground.
Token: --cds-text-secondary

Label: AI primary
Description: Primary foreground on the AI surface.
Token: --cds-text-ai-primary

Label: AI secondary
Description: Secondary foreground on the AI surface.
Token: --cds-text-ai-secondary

Label: Brand
Description: Brand-accent foreground.
Token: --cds-brand

Label: Success
Description: Positive outcome foreground.
Token: --cds-status-success-solid

Label: Danger
Description: Destructive or error foreground.
Token: --cds-status-danger-solid

States

Id: decorative
Label: Decorative
Description: Has no accessible label and is hidden from assistive technology.

Id: meaningful
Label: Meaningful
Description: Exposes image role and an accessible label that describes the glyph meaning.

Id: inherited-color
Label: Inherited color
Description: Uses the parent current color when the inherit option or no color is selected.

Behavior

Label: Registry
Description: Render only glyph names exported by the design-system glyph registry (GLYPH_NAMES).

Label: Stroke width
Description: Allow a caller to override stroke weight for stroke-based glyphs without changing the view box.

Label: Color choices
Description: Support primary, secondary, AI primary, AI secondary, brand, success, danger, and inherited foregrounds.

Accessibility

Label: Meaningful glyphs
Description: Provide a concise accessible label when the icon communicates information not present in adjacent text.

Label: Decorative glyphs
Description: Omit the label when nearby text already communicates the same meaning.

Content Adaptation

Label: Glyph selection
Description: Choose the registry name whose established meaning is closest to the action or concept.

Label: Localization
Description: Localize accessible labels while keeping decorative icons unnamed.

Motion Haptics

Motion

Label: No intrinsic motion
Description: Icon does not animate itself; a parent interaction may transform the whole glyph.

Haptics

Label: No feedback
Description: Icon is not interactive and does not request haptic feedback.

Platform Differences

None specified

Implementation preview

This design-owned implementation is ready to try and review. It does not establish product approval. Imported specifications retain their original review status.

Inspect version 0.2.0-preview.1