Cloaked Design SystemPrimitives / Iconography

SFIcon

An Apple SF Symbol rendered from the app-generated supported-symbol map with token sizes and semantic foregrounds.

Implementation preview

COMPLETE STORYBOOK REFERENCE

Every example. In one place.

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

6 stories

Playground selectedOpen canvas

Example source

packages/design-system/src/components/primitives/SFIcon/SFIcon.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.

An Apple SF Symbol rendered from the app-generated supported-symbol map with token sizes and semantic foregrounds.

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 { SFIcon } from '@cloakedinc/design-system';

SFIconSFIconProps

packages/design-system/src/components/primitives/SFIcon/SFIcon.tsx:42

Prop	Type	Presence	Notes
`name`	`string`	Required	Supported SF Symbol name. Accepts optional `sfs://` prefix.
`size`	`SFIconSize`	Required	Square size written to `--sf-icon-size`, which drives the `<svg>` width and height. `sm`/`md`/`lg` map to `--cds-size-16`/`-24`/`-32`; a number is used as px.
`color`	`"success" \| "danger" \| "brand" \| "primary" \| "secondary" \| "ai-primary" \| "ai-secondary" \| "inherit"`	Required	Semantic color used when light/dark overrides are not provided.
`lightModeColor`	`"success" \| "danger" \| "brand" \| "primary" \| "secondary" \| "ai-primary" \| "ai-secondary" \| "inherit" \| undefined`	Optional	Optional light-mode semantic color. Must be paired with `darkModeColor`.
`darkModeColor`	`"success" \| "danger" \| "brand" \| "primary" \| "secondary" \| "ai-primary" \| "ai-secondary" \| "inherit" \| undefined`	Optional	Optional dark-mode semantic color. Must be paired with `lightModeColor`.
`ariaLabel`	`string \| undefined`	Optional	Accessible label; omitted icons are hidden from assistive tech.
`className`	`string \| undefined`	Optional
`style`	`React.CSSProperties \| undefined`	Optional
`testId`	`string \| undefined`	Optional	Optional test selector. Applied to the `<svg>`; an unmapped `name` renders nothing to match.

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

Complete contract · JSON ↗Guidance and source · Markdown ↗

Overview

An Apple SF Symbol rendered as SVG inside the iOS webview, for native-feeling iOS chrome. Symbols come from the app-generated SF_SYMBOL_MAP, so the available names are limited to SUPPORTED_SF_SYMBOLS.

When to use

Reach for SFIcon only when you specifically need an SF Symbol to match iOS-native visual language. For general-purpose foreground glyphs, prefer Icon — it is the DS-owned SVG set and covers most needs without the symbol-availability constraint below. In-app, SFIcon is the heavier-used of the two (native-styled headers, dropdowns, activity rows, onboarding views), but that reflects how iOS-flavored the extension chrome is, not that it is the default.

Glyph-availability constraint: the generated map is tree-shaken from app source — a webpack plugin scans the app for symbol names and only bundles those glyphs. A name that no app code references will be absent from SF_SYMBOL_MAP, and SFIcon renders null for it. So a symbol that works in the app may be missing here in Storybook, and vice versa. If you need a new symbol, make sure it is actually referenced in app code (or add it to the supported set) rather than assuming any SF Symbol name resolves.

color sets a static tint; pair lightModeColor + darkModeColor (both required) for a glyph that recolors with the OS prefers-color-scheme.

Component specification

$schema

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

Parts

Id: svg
Label: SVG
Description: Owns sizing, semantic color, accessibility, and the symbol view box.

Id: symbol
Label: Symbol paths
Description: Renders one or more paths from the supported SF Symbol map.

Id: reactive-color
Label: Reactive color
Description: Optionally switches between paired light- and dark-scheme semantic foregrounds.

Allowed Design Choices

Variants

Base

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

Sizes

Label: Small

Label: Medium

Label: Large

Colors

Primary

Label: Primary
Description: Default-emphasis symbol foreground.

Secondary

Label: Secondary
Description: Lower-emphasis symbol foreground.

Ai primary

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

Ai secondary

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

Brand

Label: Brand
Description: Brand-accent symbol foreground.

Success

Label: Success
Description: Positive outcome symbol foreground.

Danger

Label: Danger
Description: Error or destructive symbol foreground.

Inherit

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

Variants

Id: base
Label: Base
Description: A supported Apple SF Symbol using static or paired scheme-aware foregrounds.
Platforms: ios
web

Sizes

Id: sm
Label: Small
Description: 16-unit compact symbol.

Id: md
Label: Medium
Description: 24-unit default symbol.

Id: lg
Label: Large
Description: 32-unit prominent symbol.

Measurements

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

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

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

Id: numeric-size
Label: Numeric size escape hatch
Kind: example-only
Value: 18
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 symbol occupies a square and aligns according to its parent layout.
Flow: The SVG is an inline, non-shrinking visual.
Notes: Use Icon for the general cross-platform glyph set; reserve SFIcon for Apple-native visual language.

Typography And Color

Typography

Label: Adjacent caption
Description: Catalog captions and compact labels composed with a symbol use body-small.
Token: --cds-type-body-small-size

Colors

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

Label: Secondary
Description: Lower-emphasis symbol 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: static-color
Label: Static color
Description: Uses one semantic foreground in every color scheme.

Id: reactive-color
Label: Reactive color
Description: Uses both supplied scheme colors and switches with the platform appearance.

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.

Id: unsupported
Label: Unsupported symbol
Description: Renders no glyph when the name is absent from the generated supported map.

Behavior

Label: Supported symbols
Description: Resolve optional sfs scheme prefixes and render only names present in the generated map.

Label: Reactive color pair
Description: Enable scheme-aware recoloring only when both light and dark semantic colors are supplied.

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

Accessibility

Label: Meaningful symbols
Description: Provide a concise accessible label when the symbol adds meaning not repeated by visible text.

Label: Decorative symbols
Description: Omit the label when nearby copy already communicates the same meaning.

Content Adaptation

Label: Availability
Description: Add a required symbol to the generated supported set before using it in product UI.

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

Motion Haptics

Motion

Label: No intrinsic motion
Description: SFIcon does not animate itself.

Haptics

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

Platform Differences

Platforms: android
Description: Android uses the cross-platform Icon glyph set instead of Apple SF Symbols.
Rationale: SF Symbols are an Apple visual language and the supported symbol map is generated for the iOS webview.

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