{ "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": "icon", "name": "Icon", "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-icon--playground", "name": "Playground", "title": "Cloaked Design System/Primitives/Iconography/Icon", "exportName": "Playground", "source_path": "packages/design-system/src/components/primitives/Icon/Icon.stories.tsx", "source_digest": "5c562c13352051f28677849c3f787c5bd3bccc55bde8e26d3fab47990f88f5c1", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-iconography-icon--playground&viewMode=story" }, { "id": "cloaked-design-system-primitives-iconography-icon--styled", "name": "Styled", "title": "Cloaked Design System/Primitives/Iconography/Icon", "exportName": "Styled", "source_path": "packages/design-system/src/components/primitives/Icon/Icon.stories.tsx", "source_digest": "5c562c13352051f28677849c3f787c5bd3bccc55bde8e26d3fab47990f88f5c1", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-iconography-icon--styled&viewMode=story" }, { "id": "cloaked-design-system-primitives-iconography-icon--custom-stroke-and-size", "name": "Custom Stroke And Size", "title": "Cloaked Design System/Primitives/Iconography/Icon", "exportName": "CustomStrokeAndSize", "source_path": "packages/design-system/src/components/primitives/Icon/Icon.stories.tsx", "source_digest": "5c562c13352051f28677849c3f787c5bd3bccc55bde8e26d3fab47990f88f5c1", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-iconography-icon--custom-stroke-and-size&viewMode=story" }, { "id": "cloaked-design-system-primitives-iconography-icon--decorative", "name": "Decorative", "title": "Cloaked Design System/Primitives/Iconography/Icon", "exportName": "Decorative", "source_path": "packages/design-system/src/components/primitives/Icon/Icon.stories.tsx", "source_digest": "5c562c13352051f28677849c3f787c5bd3bccc55bde8e26d3fab47990f88f5c1", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-iconography-icon--decorative&viewMode=story" }, { "id": "cloaked-design-system-primitives-iconography-icon--size-matrix", "name": "Size Matrix", "title": "Cloaked Design System/Primitives/Iconography/Icon", "exportName": "SizeMatrix", "source_path": "packages/design-system/src/components/primitives/Icon/Icon.stories.tsx", "source_digest": "5c562c13352051f28677849c3f787c5bd3bccc55bde8e26d3fab47990f88f5c1", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-iconography-icon--size-matrix&viewMode=story" }, { "id": "cloaked-design-system-primitives-iconography-icon--color-matrix", "name": "Color Matrix", "title": "Cloaked Design System/Primitives/Iconography/Icon", "exportName": "ColorMatrix", "source_path": "packages/design-system/src/components/primitives/Icon/Icon.stories.tsx", "source_digest": "5c562c13352051f28677849c3f787c5bd3bccc55bde8e26d3fab47990f88f5c1", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-iconography-icon--color-matrix&viewMode=story" }, { "id": "cloaked-design-system-primitives-iconography-icon--dark-theme", "name": "Dark Theme", "title": "Cloaked Design System/Primitives/Iconography/Icon", "exportName": "DarkTheme", "source_path": "packages/design-system/src/components/primitives/Icon/Icon.stories.tsx", "source_digest": "5c562c13352051f28677849c3f787c5bd3bccc55bde8e26d3fab47990f88f5c1", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-iconography-icon--dark-theme&viewMode=story" } ], "name": "Icon", "id": "icon", "category": "Primitives / Iconography" }, "stories_source": { "path": "packages/design-system/src/components/primitives/Icon/Icon.stories.tsx", "code": "import React from 'react';\nimport type { Meta, StoryObj } from '@storybook/react-vite';\nimport { HStack } from '../../layout/HStack/HStack';\nimport { VStack } from '../../layout/VStack/VStack';\nimport { selectArgType, TEXT_COLOR_OPTIONS } from '../../../storybook/controlOptions';\nimport { GLYPH_NAMES } from '../Glyph/Glyph';\nimport { Text } from '../Text/Text';\nimport { Icon, type IconSize } from './Icon';\n\nconst ICON_SIZES = ['small', 'medium', 'large'] as const satisfies readonly IconSize[];\n\nconst meta: Meta = {\n title: 'Cloaked Design System/Primitives/Iconography/Icon',\n component: Icon,\n parameters: {\n a11y: { test: 'error' },\n docs: {\n description: {\n component:\n 'The opinionated way to render a Symbol at a chosen size — the default icon for web/foreground UI. ' +\n 'Glyphs come from the bundled `GLYPH_NAMES` registry (see the Symbol page for the full catalogue) and ' +\n 'inherit `currentColor` unless you set a semantic `color` token. Use `label`/`ariaLabel` for meaningful ' +\n 'icons; omit both to hide decorative ones from assistive tech. Reach for `Glyph` when the surrounding ' +\n 'context should size the glyph, and `SFIcon` only for an iOS SF Symbol from the app-generated map.',\n },\n },\n },\n args: {\n name: 'guard',\n size: 'medium',\n },\n argTypes: {\n name: {\n ...selectArgType(GLYPH_NAMES),\n description: 'Glyph from the bundled DS registry (a `GlyphName`).',\n },\n size: {\n ...selectArgType(ICON_SIZES),\n description:\n 'Token size (`small` 16 · `medium` 24 · `large` 32), or a raw number for an off-scale px size.',\n },\n color: {\n ...selectArgType(TEXT_COLOR_OPTIONS),\n description: 'Semantic `--cds-text-*` token. Omit to inherit the surrounding `currentColor`.',\n },\n strokeWidth: {\n control: { type: 'number', min: 0.5, max: 3, step: 0.5 },\n description: 'Stroke weight for stroke-based glyphs; leave unset to use the glyph default.',\n },\n label: {\n control: 'text',\n description: 'Accessible label. Omit (with `ariaLabel`) for decorative, `aria-hidden` icons.',\n },\n ariaLabel: {\n control: 'text',\n description: 'Accessible-label alias for consumers standardizing on aria prop names.',\n },\n },\n};\nexport default meta;\ntype Story = StoryObj;\n\nexport const Playground: Story = {\n args: {\n ariaLabel: 'Guard',\n },\n};\n\nexport const Styled: Story = {\n parameters: {\n docs: {\n description: {\n story: 'A brand-tinted icon via inline `color`; prefer the `color` prop for semantic tokens.',\n },\n },\n },\n args: {\n name: 'bell',\n ariaLabel: 'Styled bell',\n style: { color: 'var(--cds-brand)' },\n },\n};\n\nexport const CustomStrokeAndSize: Story = {\n parameters: {\n docs: { description: { story: 'A raw numeric `size` (40) plus a thinner `strokeWidth` for off-scale needs.' } },\n },\n args: {\n name: 'settings',\n size: 40,\n strokeWidth: 1.5,\n ariaLabel: 'Custom settings icon',\n },\n};\n\nexport const Decorative: Story = {\n parameters: {\n docs: { description: { story: 'No label — the icon is `aria-hidden` and skipped by assistive tech.' } },\n },\n args: {\n name: 'check',\n size: 'large',\n },\n};\n\nexport const SizeMatrix: Story = {\n parameters: {\n docs: { description: { story: 'Each token `size` across a sample of glyphs.' } },\n },\n render: () => (\n \n {ICON_SIZES.map(size => (\n \n \n {size}\n \n {GLYPH_NAMES.slice(0, 8).map(name => (\n \n ))}\n \n ))}\n \n ),\n};\n\nexport const ColorMatrix: Story = {\n parameters: {\n docs: {\n description: { story: 'Every semantic `color` token; `inherit` follows the surrounding `currentColor`.' },\n },\n },\n render: () => (\n \n {TEXT_COLOR_OPTIONS.map(color => (\n \n \n \n {color}\n \n \n ))}\n \n ),\n};\n\nexport const DarkTheme: Story = {\n globals: { theme: 'dark' },\n render: () => (\n \n {TEXT_COLOR_OPTIONS.map(color => (\n \n ))}\n \n ),\n};\n" }, "specification": { "$schema": "../../../specs/component-spec.schema.json", "identity": { "name": "Icon", "status": "preview", "version": "1.1.0", "summary": "The opinionated render of a Symbol: a Glyph at a token size with semantic colors and decorative or meaningful accessibility." }, "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." } ], "allowedDesignChoices": { "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", "appliesTo": [ "svg", "small" ] }, { "id": "medium-size", "label": "Medium glyph size", "kind": "exact", "token": "--cds-size-24", "value": 24, "unit": "px", "appliesTo": [ "svg", "medium" ] }, { "id": "large-size", "label": "Large glyph size", "kind": "exact", "token": "--cds-size-32", "value": 32, "unit": "px", "appliesTo": [ "svg", "large" ] }, { "id": "numeric-size", "label": "Numeric size escape hatch", "kind": "example-only", "value": 40, "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 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." ] }, "typographyAndColor": { "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." } ], "contentAdaptation": [ { "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." } ], "motionHaptics": { "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." } ] }, "platformDifferences": [] }, "specification_source": "packages/design-system/src/components/primitives/Icon/Icon.spec.json", "guidance": { "summary": "The opinionated render of a Symbol: a Glyph at a token size with semantic colors and decorative or meaningful accessibility.", "guidance": [ { "heading": "Overview", "body": "The opinionated way to render a Symbol: a `Glyph` at a chosen token or numeric size with an optional\nsemantic color. This is the default icon for foreground UI. Glyphs inherit the surrounding `currentColor`\nunless you set a semantic `color` token." }, { "heading": "When to use", "body": "Reach for `Icon` for essentially every glyph in web/foreground UI — it is the DS-owned set, so any\n`name` you pick is guaranteed to render and to recolor with `--cds-text-*` tokens. It is the far\nmore common choice in-app (used across `DetailBottomSheet`, `BrokerDetail`, the Home widgets, and\nthe WebsiteData/Exposures views).\n\n- Want the drawing with **no styling at all** — sized and colored by its context? Use `Glyph`\n (documented on the **Symbol** page, which also hosts the full catalogue for picking a `name`).\n- Need a glyph in a **tone circle**? Use `IconTile`.\n- Need an actual **Apple SF Symbol** for native-feeling iOS chrome? Use `SFIcon` instead — but only\n when the specific symbol matters, since its set is limited to `SUPPORTED_SF_SYMBOLS`.\n- Pass `label`/`ariaLabel` for a meaningful icon; omit both to leave a decorative one `aria-hidden`." } ], "usage": [], "examples": [], "source": "packages/design-system/src/components/primitives/Icon/Icon.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-icon", "json": "/data/visual/components/icon.json", "storybook": "/storybook/?path=/story/cloaked-design-system-primitives-iconography-icon--playground" } }