{ "version": "0.2.0-preview.1", "content_digest": "70ac710f4d22dce040e7ac593379ba8aca9dcb59a0b9c0f839819cae0e2bb721", "status": "preview", "authority": { "repository": "cloakedinc/design", "path": "packages/design-system", "catalog": "packages/design-system/catalog.json", "status": "preview" }, "provenance": { "repo": "cloakedinc/automation", "commit": "f96f416e1c3bfbfaffcd155a88b87b18b8bb25f1", "path": "packages/design-system", "imported_spec_status": "approved" }, "adaptations": [ { "id": "button-content-gap", "status": "preview", "description": "Use the specification's 4px content gap instead of the inherited 8px implementation gap." }, { "id": "keyboard-focus", "status": "preview", "description": "Add visible Button and Input keyboard focus and an overridable inset focus default for shared button resets, including FAQ cards and ListItem rows." }, { "id": "supporting-text-contrast", "status": "preview", "description": "Map light secondary text to the existing grey-04-strong primitive for readable helper text on white and cream." }, { "id": "danger-text-contrast", "status": "preview", "description": "Separate readable danger text/borders from destructive fills; preserve the primary danger-button fill and label pair." }, { "id": "preview-status", "status": "preview", "description": "Local components, specs and token adaptations await human sign-off; upstream approved status is provenance only." }, { "id": "motion-comparison-accessibility", "status": "preview", "description": "Preserve the original MotionShowcase comparisons while requiring explicit replay, responding to live reduced-motion changes, and keeping duration tracks usable on small screens." }, { "id": "list-item-ownership", "status": "preview", "description": "List owns listitem wrappers for its content rows, while section labels stay outside the row count and standalone rows retain their existing semantics." }, { "id": "card-delta-text-contrast", "status": "preview", "description": "Mix Card.Delta foregrounds from 60% existing tone solid and 40% primary text for readable contrast in both themes; preserve the four original tone fills." }, { "id": "carousel-keyboard-access", "status": "preview", "description": "Keep all native-scrolling carousel slide controls exposed to assistive technology and keyboard navigation; pause autoplay while focus is inside the carousel." } ], "id": "sficon", "name": "SFIcon", "category": "Primitives / Iconography", "summary": "An Apple SF Symbol rendered from the app-generated supported-symbol map with token sizes and semantic foregrounds.", "documentation": { "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." }, "source": { "path": "packages/design-system/src/components/primitives/SFIcon/SFIcon.tsx", "code": "import React, { useId } from 'react';\nimport { SF_SYMBOL_MAP, SUPPORTED_SF_SYMBOLS } from '@cloakedinc/design-system/sf-symbols.generated';\nimport { cn } from '../../../utilities';\nimport type { CdsTextColor } from '../../../tokens/CdsTextColor';\nimport type { SFSymbolData, SFSymbolName, SupportedSFSymbol } from './SFSymbolData';\nimport styles from './SFIcon.module.scss';\n\nexport type SFIconSize = 'sm' | 'md' | 'lg' | number;\nexport type SFIconColor = CdsTextColor;\nexport type { SFSymbolData, SFSymbolName, SupportedSFSymbol };\nexport { SUPPORTED_SF_SYMBOLS };\n\n/**\n * Props for the SF Symbol renderer. Reach for it only when an iOS system symbol is specifically\n * wanted; the Cloaked glyph set is `Icon`/`Glyph`.\n */\nexport 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}\n\n/**\n * Renders an iOS SF Symbol from the app-provided generated symbol map.\n */\nexport function SFIcon({\n name,\n size,\n color,\n lightModeColor,\n darkModeColor,\n ariaLabel,\n className,\n style,\n testId,\n}: SFIconProps) {\n const reactId = useId();\n // Sanitized because this is interpolated into the `#id` CSS selector in the `\n );\n}\n\nexport function isSupportedSFSymbol(symbolName: string): symbolName is SFSymbolName {\n return SUPPORTED_SF_SYMBOLS.includes(stripSFScheme(symbolName));\n}\n\nexport function getSFIcon(sfsName: SFSymbolName): SFSymbolData;\nexport function getSFIcon(sfsName: string): SFSymbolData | undefined;\nexport function getSFIcon(sfsName: string): SFSymbolData | undefined {\n return SF_SYMBOL_MAP[stripSFScheme(sfsName)];\n}\n\nfunction getSizeValue(size: SFIconSize): string {\n if (typeof size === 'number') return `${size}px`;\n if (size === 'sm') return 'var(--cds-size-16)';\n if (size === 'md') return 'var(--cds-size-24)';\n return 'var(--cds-size-32)';\n}\n\nfunction getColorValue(color: SFIconColor): string {\n if (color === 'primary') return 'var(--cds-text-primary)';\n if (color === 'secondary') return 'var(--cds-text-secondary)';\n if (color === 'ai-primary') return 'var(--cds-text-ai-primary)';\n if (color === 'ai-secondary') return 'var(--cds-text-ai-secondary)';\n if (color === 'brand') return 'var(--cds-brand)';\n if (color === 'success') return 'var(--cds-status-success-solid)';\n if (color === 'danger') return 'var(--cds-status-danger-solid)';\n return 'inherit';\n}\n\nfunction stripSFScheme(symbolName: string): string {\n return symbolName.replace('sfs://', '');\n}\n" }, "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." } ] }, "spec_source": "packages/design-system/src/components/primitives/SFIcon/SFIcon.spec.json", "guidance_source": { "path": "packages/design-system/src/components/primitives/SFIcon/SFIcon.mdx", "code": "import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';\nimport { ComponentSpec } from '../../../../.storybook/blocks';\nimport * as Stories from './SFIcon.stories';\nimport sFIconSpec from './SFIcon.spec.json';\n\n\n\n# SFIcon\n\nAn 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`.\n\n\n\n## When to use\n\nReach 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`.\n\n\n\n## Design Guidelines\n\n\n\n## Props\n\n\n" }, "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": {}, "examples": [], "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" } ], "visual_reference": { "stories": [ { "id": "cloaked-design-system-primitives-iconography-sficon--playground", "name": "Playground", "title": "Cloaked Design System/Primitives/Iconography/SFIcon", "exportName": "Playground", "source_path": "packages/design-system/src/components/primitives/SFIcon/SFIcon.stories.tsx", "source_digest": "aa1844f84051d515691d3fce7dad9449e2f936c48d56cebf4a5f165ce84dad8e", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-iconography-sficon--playground&viewMode=story" }, { "id": "cloaked-design-system-primitives-iconography-sficon--brand", "name": "Brand", "title": "Cloaked Design System/Primitives/Iconography/SFIcon", "exportName": "Brand", "source_path": "packages/design-system/src/components/primitives/SFIcon/SFIcon.stories.tsx", "source_digest": "aa1844f84051d515691d3fce7dad9449e2f936c48d56cebf4a5f165ce84dad8e", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-iconography-sficon--brand&viewMode=story" }, { "id": "cloaked-design-system-primitives-iconography-sficon--numeric-size", "name": "Numeric Size", "title": "Cloaked Design System/Primitives/Iconography/SFIcon", "exportName": "NumericSize", "source_path": "packages/design-system/src/components/primitives/SFIcon/SFIcon.stories.tsx", "source_digest": "aa1844f84051d515691d3fce7dad9449e2f936c48d56cebf4a5f165ce84dad8e", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-iconography-sficon--numeric-size&viewMode=story" }, { "id": "cloaked-design-system-primitives-iconography-sficon--reactive-color", "name": "Reactive Color", "title": "Cloaked Design System/Primitives/Iconography/SFIcon", "exportName": "ReactiveColor", "source_path": "packages/design-system/src/components/primitives/SFIcon/SFIcon.stories.tsx", "source_digest": "aa1844f84051d515691d3fce7dad9449e2f936c48d56cebf4a5f165ce84dad8e", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-iconography-sficon--reactive-color&viewMode=story" }, { "id": "cloaked-design-system-primitives-iconography-sficon--featured-grid", "name": "Featured Grid", "title": "Cloaked Design System/Primitives/Iconography/SFIcon", "exportName": "FeaturedGrid", "source_path": "packages/design-system/src/components/primitives/SFIcon/SFIcon.stories.tsx", "source_digest": "aa1844f84051d515691d3fce7dad9449e2f936c48d56cebf4a5f165ce84dad8e", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-iconography-sficon--featured-grid&viewMode=story" }, { "id": "cloaked-design-system-primitives-iconography-sficon--size-matrix", "name": "Size Matrix", "title": "Cloaked Design System/Primitives/Iconography/SFIcon", "exportName": "SizeMatrix", "source_path": "packages/design-system/src/components/primitives/SFIcon/SFIcon.stories.tsx", "source_digest": "aa1844f84051d515691d3fce7dad9449e2f936c48d56cebf4a5f165ce84dad8e", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-iconography-sficon--size-matrix&viewMode=story" } ], "name": "SFIcon", "id": "sficon", "category": "Primitives / Iconography" }, "stories": [ { "id": "cloaked-design-system-primitives-iconography-sficon--playground", "name": "Playground", "title": "Cloaked Design System/Primitives/Iconography/SFIcon", "exportName": "Playground", "source_path": "packages/design-system/src/components/primitives/SFIcon/SFIcon.stories.tsx", "source_digest": "aa1844f84051d515691d3fce7dad9449e2f936c48d56cebf4a5f165ce84dad8e", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-iconography-sficon--playground&viewMode=story" }, { "id": "cloaked-design-system-primitives-iconography-sficon--brand", "name": "Brand", "title": "Cloaked Design System/Primitives/Iconography/SFIcon", "exportName": "Brand", "source_path": "packages/design-system/src/components/primitives/SFIcon/SFIcon.stories.tsx", "source_digest": "aa1844f84051d515691d3fce7dad9449e2f936c48d56cebf4a5f165ce84dad8e", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-iconography-sficon--brand&viewMode=story" }, { "id": "cloaked-design-system-primitives-iconography-sficon--numeric-size", "name": "Numeric Size", "title": "Cloaked Design System/Primitives/Iconography/SFIcon", "exportName": "NumericSize", "source_path": "packages/design-system/src/components/primitives/SFIcon/SFIcon.stories.tsx", "source_digest": "aa1844f84051d515691d3fce7dad9449e2f936c48d56cebf4a5f165ce84dad8e", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-iconography-sficon--numeric-size&viewMode=story" }, { "id": "cloaked-design-system-primitives-iconography-sficon--reactive-color", "name": "Reactive Color", "title": "Cloaked Design System/Primitives/Iconography/SFIcon", "exportName": "ReactiveColor", "source_path": "packages/design-system/src/components/primitives/SFIcon/SFIcon.stories.tsx", "source_digest": "aa1844f84051d515691d3fce7dad9449e2f936c48d56cebf4a5f165ce84dad8e", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-iconography-sficon--reactive-color&viewMode=story" }, { "id": "cloaked-design-system-primitives-iconography-sficon--featured-grid", "name": "Featured Grid", "title": "Cloaked Design System/Primitives/Iconography/SFIcon", "exportName": "FeaturedGrid", "source_path": "packages/design-system/src/components/primitives/SFIcon/SFIcon.stories.tsx", "source_digest": "aa1844f84051d515691d3fce7dad9449e2f936c48d56cebf4a5f165ce84dad8e", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-iconography-sficon--featured-grid&viewMode=story" }, { "id": "cloaked-design-system-primitives-iconography-sficon--size-matrix", "name": "Size Matrix", "title": "Cloaked Design System/Primitives/Iconography/SFIcon", "exportName": "SizeMatrix", "source_path": "packages/design-system/src/components/primitives/SFIcon/SFIcon.stories.tsx", "source_digest": "aa1844f84051d515691d3fce7dad9449e2f936c48d56cebf4a5f165ce84dad8e", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-iconography-sficon--size-matrix&viewMode=story" } ], "stories_source": { "path": "packages/design-system/src/components/primitives/SFIcon/SFIcon.stories.tsx", "code": "import React from 'react';\nimport type { Meta, StoryObj } from '@storybook/react-vite';\nimport { Grid } from '../../layout/Grid/Grid';\nimport { HStack } from '../../layout/HStack/HStack';\nimport { VStack } from '../../layout/VStack/VStack';\nimport { Text } from '../Text/Text';\nimport { selectArgType, TEXT_COLOR_OPTIONS } from '../../../storybook/controlOptions';\nimport { SFIcon, SUPPORTED_SF_SYMBOLS, type SFIconSize } from './SFIcon';\n\nconst SF_ICON_SIZE_OPTIONS = ['sm', 'md', 'lg'] as const satisfies readonly SFIconSize[];\nconst FEATURED_SYMBOLS = [\n 'shield.fill',\n 'lock.shield.fill',\n 'text.magnifyingglass',\n 'wand.and.sparkles',\n 'chevron.right',\n 'line.3.horizontal',\n 'checkmark.circle.fill',\n 'xmark.circle.fill',\n] as const;\n\nconst meta: Meta = {\n title: 'Cloaked Design System/Primitives/Iconography/SFIcon',\n component: SFIcon,\n parameters: {\n a11y: { test: 'error' },\n docs: {\n description: {\n component:\n 'Renders an iOS SF Symbol from the app-generated symbol map — use it only where you need an actual ' +\n 'SF Symbol (native-feeling iOS chrome). For general web/foreground glyphs use `Icon` instead, since ' +\n 'the SF set is limited to `SUPPORTED_SF_SYMBOLS`. `color` sets a static tint; pair `lightModeColor` ' +\n '+ `darkModeColor` for a glyph that recolors with the OS `prefers-color-scheme` (both required).',\n },\n },\n },\n args: {\n name: 'shield.fill',\n size: 'md',\n color: 'primary',\n ariaLabel: 'Shield',\n },\n argTypes: {\n name: {\n ...selectArgType(SUPPORTED_SF_SYMBOLS),\n description: 'Supported SF Symbol name from the generated map (an optional `sfs://` prefix is stripped).',\n },\n size: {\n ...selectArgType(SF_ICON_SIZE_OPTIONS),\n description: 'Token size (`sm` 16 · `md` 24 · `lg` 32), or a raw number for an off-scale px size.',\n },\n color: {\n ...selectArgType(TEXT_COLOR_OPTIONS),\n description:\n 'Static semantic `--cds-text-*` tint. Overridden when `lightModeColor`/`darkModeColor` are set.',\n },\n lightModeColor: {\n ...selectArgType(TEXT_COLOR_OPTIONS),\n description: 'Light-scheme tint; must be paired with `darkModeColor` to enable OS-reactive recoloring.',\n },\n darkModeColor: {\n ...selectArgType(TEXT_COLOR_OPTIONS),\n description: 'Dark-scheme tint; must be paired with `lightModeColor`.',\n },\n },\n};\nexport default meta;\ntype Story = StoryObj;\n\nexport const Playground: Story = {};\nexport const Brand: Story = {\n parameters: { docs: { description: { story: 'A large brand-tinted symbol via the static `color` token.' } } },\n args: { name: 'wand.and.sparkles', size: 'lg', color: 'brand' },\n};\nexport const NumericSize: Story = {\n parameters: { docs: { description: { story: 'A raw numeric `size` (18px) for an off-scale glyph.' } } },\n args: { name: 'info.circle', size: 18, color: 'secondary' },\n};\nexport const ReactiveColor: Story = {\n parameters: {\n docs: {\n description: {\n story:\n '`lightModeColor` + `darkModeColor` recolor with the OS color scheme (via `prefers-color-scheme`, ' +\n 'not the Storybook theme toggle).',\n },\n },\n },\n args: { name: 'shield.fill', size: 'lg', color: 'primary', lightModeColor: 'primary', darkModeColor: 'brand' },\n};\n\nexport const FeaturedGrid: Story = {\n parameters: { docs: { description: { story: 'A curated sample of common symbols from `SUPPORTED_SF_SYMBOLS`.' } } },\n render: () => (\n \n {FEATURED_SYMBOLS.map(name => (\n \n \n \n {name}\n \n \n ))}\n \n ),\n};\n\nexport const SizeMatrix: Story = {\n parameters: { docs: { description: { story: 'Each token `size` across a sample of symbols.' } } },\n render: () => (\n \n {SF_ICON_SIZE_OPTIONS.map(size => (\n \n \n {size}\n \n {FEATURED_SYMBOLS.slice(0, 4).map(name => (\n \n ))}\n \n ))}\n \n ),\n};\n" }, "links": { "human": "/component-sficon", "json": "/data/components/sficon.json", "markdown": "/data/components/sficon.md", "storybook": "/storybook/?path=/story/cloaked-design-system-primitives-iconography-sficon--playground" }, "contract_status": "preview", "contract_kind": "source-derived", "approval": "required", "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." }, "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" } }, "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." } ], "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." } }