{ "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", "contract_status": "preview", "contract_kind": "source-derived", "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." }, "approval": "required", "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_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" }, "specification": { "$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." } ] }, "specification_source": "packages/design-system/src/components/primitives/SFIcon/SFIcon.spec.json", "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." }, "links": { "human": "/component-sficon", "json": "/data/visual/components/sficon.json", "storybook": "/storybook/?path=/story/cloaked-design-system-primitives-iconography-sficon--playground" } }