# SFIcon An Apple SF Symbol rendered from the app-generated supported-symbol map with token sizes and semantic foregrounds. Version: 0.2.0-preview.1 (preview) Content digest: 70ac710f4d22dce040e7ac593379ba8aca9dcb59a0b9c0f839819cae0e2bb721 Contract kind: source-derived Source: packages/design-system/src/components/primitives/SFIcon/SFIcon.tsx ## Guidance { "summary": "An Apple SF Symbol rendered from the app-generated supported-symbol map with token sizes and semantic foregrounds.", "guidance": [ { "heading": "Overview", "body": "An Apple SF Symbol rendered as SVG inside the iOS webview, for native-feeling iOS chrome. Symbols\ncome from the app-generated `SF_SYMBOL_MAP`, so the available `name`s are limited to\n`SUPPORTED_SF_SYMBOLS`." }, { "heading": "When to use", "body": "Reach for `SFIcon` only when you specifically need an SF Symbol to match iOS-native visual language.\nFor general-purpose foreground glyphs, prefer `Icon` — it is the DS-owned SVG set and covers most\nneeds without the symbol-availability constraint below. In-app, `SFIcon` is the heavier-used of the\ntwo (native-styled headers, dropdowns, activity rows, onboarding views), but that reflects how\niOS-flavored the extension chrome is, not that it is the default.\n\n**Glyph-availability constraint:** the generated map is tree-shaken from app source — a webpack\nplugin scans the app for symbol names and only bundles those glyphs. A `name` that no app code\nreferences will be absent from `SF_SYMBOL_MAP`, and `SFIcon` renders `null` for it. So a symbol that\nworks in the app may be missing here in Storybook, and vice versa. If you need a new symbol, make\nsure it is actually referenced in app code (or add it to the supported set) rather than assuming any\nSF Symbol name resolves.\n\n`color` sets a static tint; pair `lightModeColor` + `darkModeColor` (both required) for a glyph that\nrecolors with the OS `prefers-color-scheme`." } ], "usage": [], "examples": [], "source": "packages/design-system/src/components/primitives/SFIcon/SFIcon.mdx", "status": "local-preview", "note": "Guidance is read from local documentation, originally imported from the frozen source. Platform assertions in guidance are not parity verification." } ## Contract and public API ```json { "props": [ { "name": "name", "type": "string", "declared_type": "SFSymbolName", "required": true, "description": "Supported SF Symbol name. Accepts optional `sfs://` prefix.", "source": { "path": "packages/design-system/src/components/primitives/SFIcon/SFIcon.tsx", "line": 19 } }, { "name": "size", "type": "SFIconSize", "declared_type": "SFIconSize", "required": true, "description": "Square size written to `--sf-icon-size`, which drives the `` width and height.\n`sm`/`md`/`lg` map to `--cds-size-16`/`-24`/`-32`; a number is used as px.", "source": { "path": "packages/design-system/src/components/primitives/SFIcon/SFIcon.tsx", "line": 24 } }, { "name": "color", "type": "\"success\" | \"danger\" | \"brand\" | \"primary\" | \"secondary\" | \"ai-primary\" | \"ai-secondary\" | \"inherit\"", "declared_type": "SFIconColor", "required": true, "description": "Semantic color used when light/dark overrides are not provided.", "source": { "path": "packages/design-system/src/components/primitives/SFIcon/SFIcon.tsx", "line": 26 }, "values": [ "ai-primary", "ai-secondary", "brand", "danger", "inherit", "primary", "secondary", "success" ], "values_complete": true }, { "name": "lightModeColor", "type": "\"success\" | \"danger\" | \"brand\" | \"primary\" | \"secondary\" | \"ai-primary\" | \"ai-secondary\" | \"inherit\" | undefined", "declared_type": "SFIconColor", "required": false, "description": "Optional light-mode semantic color. Must be paired with `darkModeColor`.", "source": { "path": "packages/design-system/src/components/primitives/SFIcon/SFIcon.tsx", "line": 28 }, "values": [ "ai-primary", "ai-secondary", "brand", "danger", "inherit", "primary", "secondary", "success" ], "values_complete": true }, { "name": "darkModeColor", "type": "\"success\" | \"danger\" | \"brand\" | \"primary\" | \"secondary\" | \"ai-primary\" | \"ai-secondary\" | \"inherit\" | undefined", "declared_type": "SFIconColor", "required": false, "description": "Optional dark-mode semantic color. Must be paired with `lightModeColor`.", "source": { "path": "packages/design-system/src/components/primitives/SFIcon/SFIcon.tsx", "line": 30 }, "values": [ "ai-primary", "ai-secondary", "brand", "danger", "inherit", "primary", "secondary", "success" ], "values_complete": true }, { "name": "ariaLabel", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Accessible label; omitted icons are hidden from assistive tech.", "source": { "path": "packages/design-system/src/components/primitives/SFIcon/SFIcon.tsx", "line": 32 } }, { "name": "className", "type": "string | undefined", "declared_type": "string", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/primitives/SFIcon/SFIcon.tsx", "line": 33 } }, { "name": "style", "type": "React.CSSProperties | undefined", "declared_type": "React.CSSProperties", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/primitives/SFIcon/SFIcon.tsx", "line": 34 } }, { "name": "testId", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Optional test selector. Applied to the ``; an unmapped `name` renders nothing to match.", "source": { "path": "packages/design-system/src/components/primitives/SFIcon/SFIcon.tsx", "line": 36 } } ], "prop_shapes": {}, "api": { "method": "typescript-type-checker", "typescript_version": "5.9.3", "public_export": "SFIcon", "public_path": "SFIcon", "import_path": "@cloakedinc/design-system", "root_kind": "component", "entrypoints": [ { "name": "SFIcon", "signature": 1, "visibility": "public", "source": { "path": "packages/design-system/src/components/primitives/SFIcon/SFIcon.tsx", "line": 42 }, "props_type": "SFIconProps", "props": [ { "name": "name", "type": "string", "declared_type": "SFSymbolName", "required": true, "description": "Supported SF Symbol name. Accepts optional `sfs://` prefix.", "source": { "path": "packages/design-system/src/components/primitives/SFIcon/SFIcon.tsx", "line": 19 } }, { "name": "size", "type": "SFIconSize", "declared_type": "SFIconSize", "required": true, "description": "Square size written to `--sf-icon-size`, which drives the `` width and height.\n`sm`/`md`/`lg` map to `--cds-size-16`/`-24`/`-32`; a number is used as px.", "source": { "path": "packages/design-system/src/components/primitives/SFIcon/SFIcon.tsx", "line": 24 } }, { "name": "color", "type": "\"success\" | \"danger\" | \"brand\" | \"primary\" | \"secondary\" | \"ai-primary\" | \"ai-secondary\" | \"inherit\"", "declared_type": "SFIconColor", "required": true, "description": "Semantic color used when light/dark overrides are not provided.", "source": { "path": "packages/design-system/src/components/primitives/SFIcon/SFIcon.tsx", "line": 26 }, "values": [ "ai-primary", "ai-secondary", "brand", "danger", "inherit", "primary", "secondary", "success" ], "values_complete": true }, { "name": "lightModeColor", "type": "\"success\" | \"danger\" | \"brand\" | \"primary\" | \"secondary\" | \"ai-primary\" | \"ai-secondary\" | \"inherit\" | undefined", "declared_type": "SFIconColor", "required": false, "description": "Optional light-mode semantic color. Must be paired with `darkModeColor`.", "source": { "path": "packages/design-system/src/components/primitives/SFIcon/SFIcon.tsx", "line": 28 }, "values": [ "ai-primary", "ai-secondary", "brand", "danger", "inherit", "primary", "secondary", "success" ], "values_complete": true }, { "name": "darkModeColor", "type": "\"success\" | \"danger\" | \"brand\" | \"primary\" | \"secondary\" | \"ai-primary\" | \"ai-secondary\" | \"inherit\" | undefined", "declared_type": "SFIconColor", "required": false, "description": "Optional dark-mode semantic color. Must be paired with `lightModeColor`.", "source": { "path": "packages/design-system/src/components/primitives/SFIcon/SFIcon.tsx", "line": 30 }, "values": [ "ai-primary", "ai-secondary", "brand", "danger", "inherit", "primary", "secondary", "success" ], "values_complete": true }, { "name": "ariaLabel", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Accessible label; omitted icons are hidden from assistive tech.", "source": { "path": "packages/design-system/src/components/primitives/SFIcon/SFIcon.tsx", "line": 32 } }, { "name": "className", "type": "string | undefined", "declared_type": "string", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/primitives/SFIcon/SFIcon.tsx", "line": 33 } }, { "name": "style", "type": "React.CSSProperties | undefined", "declared_type": "React.CSSProperties", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/primitives/SFIcon/SFIcon.tsx", "line": 34 } }, { "name": "testId", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Optional test selector. Applied to the ``; an unmapped `name` renders nothing to match.", "source": { "path": "packages/design-system/src/components/primitives/SFIcon/SFIcon.tsx", "line": 36 } } ], "branches": [], "constraints": [], "extraction_status": "extracted" } ], "type_sources": [ { "path": "packages/design-system/src/components/primitives/SFIcon/SFIcon.tsx", "line": 8, "name": "SFIconSize", "code": "export type SFIconSize = 'sm' | 'md' | 'lg' | number;" }, { "path": "packages/design-system/src/components/primitives/SFIcon/SFIcon.tsx", "line": 9, "name": "SFIconColor", "code": "export type SFIconColor = CdsTextColor;" }, { "path": "packages/design-system/src/components/primitives/SFIcon/SFIcon.tsx", "line": 17, "name": "SFIconProps", "code": "export interface SFIconProps {\n /** Supported SF Symbol name. Accepts optional `sfs://` prefix. */\n name: SFSymbolName;\n /**\n * Square size written to `--sf-icon-size`, which drives the `` width and height.\n * `sm`/`md`/`lg` map to `--cds-size-16`/`-24`/`-32`; a number is used as px.\n */\n size: SFIconSize;\n /** Semantic color used when light/dark overrides are not provided. */\n color: SFIconColor;\n /** Optional light-mode semantic color. Must be paired with `darkModeColor`. */\n lightModeColor?: SFIconColor;\n /** Optional dark-mode semantic color. Must be paired with `lightModeColor`. */\n darkModeColor?: SFIconColor;\n /** Accessible label; omitted icons are hidden from assistive tech. */\n ariaLabel?: string;\n className?: string;\n style?: React.CSSProperties;\n /** Optional test selector. Applied to the ``; an unmapped `name` renders nothing to match. */\n testId?: string;\n}" }, { "path": "packages/design-system/src/components/primitives/SFIcon/SFSymbolData.ts", "line": 11, "name": "SupportedSFSymbol", "code": "export type SupportedSFSymbol = string;" }, { "path": "packages/design-system/src/components/primitives/SFIcon/SFSymbolData.ts", "line": 12, "name": "SFSymbolName", "code": "export type SFSymbolName = SupportedSFSymbol | `sfs://${SupportedSFSymbol}`;" }, { "path": "packages/design-system/src/tokens/CdsTextColor.ts", "line": 8, "name": "PUI_TEXT_COLORS", "code": "PUI_TEXT_COLORS = [\n 'primary',\n 'secondary',\n 'ai-primary',\n 'ai-secondary',\n 'brand',\n 'success',\n 'danger',\n 'inherit',\n] as const" }, { "path": "packages/design-system/src/tokens/CdsTextColor.ts", "line": 19, "name": "CdsTextColor", "code": "export type CdsTextColor = (typeof PUI_TEXT_COLORS)[number];" } ], "defaults_policy": "Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source." }, "spec": { "$schema": "../../../specs/component-spec.schema.json", "identity": { "name": "SFIcon", "status": "preview", "version": "1.0.0", "summary": "An Apple SF Symbol rendered from the app-generated supported-symbol map with token sizes and semantic foregrounds." }, "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." } ], "allowedDesignChoices": { "variants": { "base": { "label": "Base", "description": "The symbol name changes glyph content without changing the component treatment." } }, "sizes": { "sm": { "label": "Small" }, "md": { "label": "Medium" }, "lg": { "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", "appliesTo": [ "svg", "sm" ] }, { "id": "medium-size", "label": "Medium symbol size", "kind": "exact", "token": "--cds-size-24", "value": 24, "unit": "px", "appliesTo": [ "svg", "md" ] }, { "id": "large-size", "label": "Large symbol size", "kind": "exact", "token": "--cds-size-32", "value": 32, "unit": "px", "appliesTo": [ "svg", "lg" ] }, { "id": "numeric-size", "label": "Numeric size escape hatch", "kind": "example-only", "value": 18, "unit": "px", "appliesTo": [ "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." ] }, "typographyAndColor": { "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." } ], "contentAdaptation": [ { "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." } ], "motionHaptics": { "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." } ] }, "platformDifferences": [ { "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." } ] }, "platforms": { "implemented": [ "web" ], "native": "Imported design guidance only; no native implementation or parity verification in this preview.", "react": { "implementation": "local", "status": "preview", "parity": "web-reference" }, "vue": { "implementation": "absent", "parity": "not-verified", "status": "reference-only" }, "swift": { "implementation": "absent", "parity": "not-verified", "status": "reference-only" }, "kotlin": { "implementation": "absent", "parity": "not-verified", "status": "reference-only" } }, "tokens": [ { "name": "--cds-size-16", "light": "16px", "dark": "16px" }, { "name": "--cds-size-24", "light": "24px", "dark": "24px" }, { "name": "--cds-size-32", "light": "32px", "dark": "32px" }, { "name": "--cds-type-body-small-size", "light": "0.875rem", "dark": "0.875rem" }, { "name": "--cds-text-primary", "light": "#141410", "dark": "#f3f1ed" }, { "name": "--cds-text-secondary", "light": "#646260", "dark": "#ffffff99" }, { "name": "--cds-text-ai-primary", "light": "#f3f1ed", "dark": "#f3f1ed" }, { "name": "--cds-text-ai-secondary", "light": "#84827e", "dark": "#84827e" }, { "name": "--cds-brand", "light": "#ff550c", "dark": "#ff550c" }, { "name": "--cds-status-success-solid", "light": "#008924", "dark": "#008924" }, { "name": "--cds-status-danger-solid", "light": "#b83100", "dark": "#b83100" } ], "review": { "local_status": "not-reviewed", "source_approval": null, "imported_spec_status": "approved", "spec_origin": "imported-adapted", "local_spec_source_status": "approved", "imported_source_revision": "f96f416e1c3bfbfaffcd155a88b87b18b8bb25f1", "note": "Inherited specification status is provenance, not approval of the current local implementation or extracted contract." }, "missing_facts": [ { "code": "human-review-pending", "detail": "This local preview has no recorded human design or engineering sign-off." }, { "code": "platform-parity-unverified", "detail": "Vue, Swift and Kotlin implementations are absent from this package; platform parity has not been verified." }, { "code": "figma-mapping-unverified", "detail": "No current component-level Figma node and immutable revision have been verified for this contract." } ] } ``` ## Visual states - [Playground](/storybook/iframe.html?id=cloaked-design-system-primitives-iconography-sficon--playground&viewMode=story) | export: Playground | source: packages/design-system/src/components/primitives/SFIcon/SFIcon.stories.tsx - [Brand](/storybook/iframe.html?id=cloaked-design-system-primitives-iconography-sficon--brand&viewMode=story) | export: Brand | source: packages/design-system/src/components/primitives/SFIcon/SFIcon.stories.tsx - [Numeric Size](/storybook/iframe.html?id=cloaked-design-system-primitives-iconography-sficon--numeric-size&viewMode=story) | export: NumericSize | source: packages/design-system/src/components/primitives/SFIcon/SFIcon.stories.tsx - [Reactive Color](/storybook/iframe.html?id=cloaked-design-system-primitives-iconography-sficon--reactive-color&viewMode=story) | export: ReactiveColor | source: packages/design-system/src/components/primitives/SFIcon/SFIcon.stories.tsx - [Featured Grid](/storybook/iframe.html?id=cloaked-design-system-primitives-iconography-sficon--featured-grid&viewMode=story) | export: FeaturedGrid | source: packages/design-system/src/components/primitives/SFIcon/SFIcon.stories.tsx - [Size Matrix](/storybook/iframe.html?id=cloaked-design-system-primitives-iconography-sficon--size-matrix&viewMode=story) | export: SizeMatrix | source: packages/design-system/src/components/primitives/SFIcon/SFIcon.stories.tsx Preview pending human sign-off. Source-derived APIs and successful checks do not certify accessibility, native parity or approval.