{ "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", "summary": "The opinionated render of a Symbol: a Glyph at a token size with semantic colors and decorative or meaningful accessibility.", "documentation": { "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." }, "source": { "path": "packages/design-system/src/components/primitives/Icon/Icon.tsx", "code": "import React from 'react';\nimport { cn } from '../../../utilities';\nimport type { CdsTextColor } from '../../../tokens/CdsTextColor';\nimport { Glyph, type GlyphName } from '../Glyph/Glyph';\nimport styles from './Icon.module.scss';\n\nexport type IconSize = 'small' | 'medium' | 'large' | number;\nexport type IconColor = CdsTextColor;\n\n/**\n * Props for the sized, colored wrapper around `Glyph`. A numeric `size` emits raw px and leaves\n * the token scale, so prefer the named tiers.\n */\nexport interface IconProps {\n /** Registered glyph to render; an unregistered name renders nothing at all. */\n name: GlyphName;\n /** Named tier — 16, 24, or 32px from the size tokens — or a raw px number. */\n size: IconSize;\n /** Semantic color token. Omit to inherit the surrounding `currentColor`. */\n color?: IconColor;\n /** Stroke width passed to stroke-based glyphs. */\n strokeWidth?: number | string;\n /** Accessible label; omitted icons are hidden from assistive tech. */\n label?: string;\n /** Accessible label alias for consumers standardizing on aria prop names. */\n ariaLabel?: string;\n className?: string;\n style?: React.CSSProperties;\n /** Selector forwarded to the rendered svg element. */\n testId?: string;\n}\n\nconst ICON_SIZE_VALUES: Record, string> = {\n small: 'var(--cds-size-16)',\n medium: 'var(--cds-size-24)',\n large: 'var(--cds-size-32)',\n};\n\n/**\n * Renders a registered glyph at a chosen size and semantic color. Reach for `IconTile` instead\n * when the glyph needs a tone circle behind it.\n */\nexport function Icon({\n name,\n size,\n color,\n strokeWidth,\n label,\n ariaLabel,\n className,\n style: styleProp,\n testId,\n}: IconProps) {\n const style = {\n ...styleProp,\n '--icon-size': getIconSize(size),\n '--icon-stroke-width': strokeWidth,\n } as React.CSSProperties;\n\n return (\n \n );\n}\n\nfunction getIconSize(size: IconSize): string {\n if (typeof size === 'number') return `${size}px`;\n\n return ICON_SIZE_VALUES[size];\n}\n" }, "spec": { "$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": [] }, "spec_source": "packages/design-system/src/components/primitives/Icon/Icon.spec.json", "guidance_source": { "path": "packages/design-system/src/components/primitives/Icon/Icon.mdx", "code": "import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';\nimport { ComponentSpec } from '../../../../.storybook/blocks';\nimport * as Stories from './Icon.stories';\nimport iconSpec from './Icon.spec.json';\n\n\n\n# Icon\n\nThe 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.\n\n\n\n## When to use\n\nReach 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`.\n\n## Design Guidelines\n\n\n\n## Props\n\n\n" }, "props": [ { "name": "name", "type": "\"number\" | \"info\" | \"guard\" | \"arrow-left\" | \"arrow-right\" | \"arrow-up\" | \"arrow-down\" | \"chevron-down\" | \"chevron-up\" | \"chevron-left\" | \"chevron-right\" | \"caret-down\" | \"caret-up\" | \"trend-up\" | \"trend-down\" | \"collapse\" | \"expand\" | \"dropdown-collapse\" | \"dropdown-expand\" | \"close\" | \"clear\" | \"menu\" | \"copy\" | \"search\" | \"add\" | \"share\" | \"phone\" | \"sim\" | \"account\" | \"family\" | \"home\" | \"wifi\" | \"cart\" | \"vpn\" | \"lock\" | \"block\" | \"timer\" | \"check\" | \"send\" | \"filter\" | \"scan\" | \"log\" | \"trash\" | \"missed\" | \"call\" | \"voicemail\" | \"sms\" | \"email\" | \"data-removal\" | \"dark-web-monitoring\" | \"cloaked-pay\" | \"cloaked-ai\" | \"sms-guard\" | \"email-guard\" | \"call-guard\" | \"card\" | \"password\" | \"bell\" | \"circle-outline\" | \"dot\" | \"settings\" | \"clock\" | \"mail\" | \"message\" | \"user\" | \"upload\"", "declared_type": "GlyphName", "required": true, "description": "Registered glyph to render; an unregistered name renders nothing at all.", "source": { "path": "packages/design-system/src/components/primitives/Icon/Icon.tsx", "line": 16 }, "values": [ "account", "add", "arrow-down", "arrow-left", "arrow-right", "arrow-up", "bell", "block", "call-guard", "call", "card", "caret-down", "caret-up", "cart", "check", "chevron-down", "chevron-left", "chevron-right", "chevron-up", "circle-outline", "clear", "cloaked-ai", "cloaked-pay", "clock", "close", "collapse", "copy", "dark-web-monitoring", "data-removal", "dot", "dropdown-collapse", "dropdown-expand", "email-guard", "email", "expand", "family", "filter", "guard", "home", "info", "lock", "log", "mail", "menu", "message", "missed", "number", "password", "phone", "scan", "search", "send", "settings", "share", "sim", "sms-guard", "sms", "timer", "trash", "trend-down", "trend-up", "upload", "user", "voicemail", "vpn", "wifi" ], "values_complete": true }, { "name": "size", "type": "IconSize", "declared_type": "IconSize", "required": true, "description": "Named tier — 16, 24, or 32px from the size tokens — or a raw px number.", "source": { "path": "packages/design-system/src/components/primitives/Icon/Icon.tsx", "line": 18 } }, { "name": "color", "type": "\"success\" | \"danger\" | \"brand\" | \"primary\" | \"secondary\" | \"ai-primary\" | \"ai-secondary\" | \"inherit\" | undefined", "declared_type": "IconColor", "required": false, "description": "Semantic color token. Omit to inherit the surrounding `currentColor`.", "source": { "path": "packages/design-system/src/components/primitives/Icon/Icon.tsx", "line": 20 }, "values": [ "ai-primary", "ai-secondary", "brand", "danger", "inherit", "primary", "secondary", "success" ], "values_complete": true }, { "name": "strokeWidth", "type": "string | number | undefined", "declared_type": "number | string", "required": false, "description": "Stroke width passed to stroke-based glyphs.", "source": { "path": "packages/design-system/src/components/primitives/Icon/Icon.tsx", "line": 22 } }, { "name": "label", "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/Icon/Icon.tsx", "line": 24 } }, { "name": "ariaLabel", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Accessible label alias for consumers standardizing on aria prop names.", "source": { "path": "packages/design-system/src/components/primitives/Icon/Icon.tsx", "line": 26 } }, { "name": "className", "type": "string | undefined", "declared_type": "string", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/primitives/Icon/Icon.tsx", "line": 27 } }, { "name": "style", "type": "React.CSSProperties | undefined", "declared_type": "React.CSSProperties", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/primitives/Icon/Icon.tsx", "line": 28 } }, { "name": "testId", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Selector forwarded to the rendered svg element.", "source": { "path": "packages/design-system/src/components/primitives/Icon/Icon.tsx", "line": 30 } } ], "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" }, { "name": "--cds-text-", "light": null, "dark": null } ], "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": [ { "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" } ], "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" }, "links": { "human": "/component-icon", "json": "/data/components/icon.json", "markdown": "/data/components/icon.md", "storybook": "/storybook/?path=/story/cloaked-design-system-primitives-iconography-icon--playground" }, "contract_status": "preview", "contract_kind": "source-derived", "approval": "required", "api": { "method": "typescript-type-checker", "typescript_version": "5.9.3", "public_export": "Icon", "public_path": "Icon", "import_path": "@cloakedinc/design-system", "root_kind": "component", "entrypoints": [ { "name": "Icon", "signature": 1, "visibility": "public", "source": { "path": "packages/design-system/src/components/primitives/Icon/Icon.tsx", "line": 43 }, "props_type": "IconProps", "props": [ { "name": "name", "type": "\"number\" | \"info\" | \"guard\" | \"arrow-left\" | \"arrow-right\" | \"arrow-up\" | \"arrow-down\" | \"chevron-down\" | \"chevron-up\" | \"chevron-left\" | \"chevron-right\" | \"caret-down\" | \"caret-up\" | \"trend-up\" | \"trend-down\" | \"collapse\" | \"expand\" | \"dropdown-collapse\" | \"dropdown-expand\" | \"close\" | \"clear\" | \"menu\" | \"copy\" | \"search\" | \"add\" | \"share\" | \"phone\" | \"sim\" | \"account\" | \"family\" | \"home\" | \"wifi\" | \"cart\" | \"vpn\" | \"lock\" | \"block\" | \"timer\" | \"check\" | \"send\" | \"filter\" | \"scan\" | \"log\" | \"trash\" | \"missed\" | \"call\" | \"voicemail\" | \"sms\" | \"email\" | \"data-removal\" | \"dark-web-monitoring\" | \"cloaked-pay\" | \"cloaked-ai\" | \"sms-guard\" | \"email-guard\" | \"call-guard\" | \"card\" | \"password\" | \"bell\" | \"circle-outline\" | \"dot\" | \"settings\" | \"clock\" | \"mail\" | \"message\" | \"user\" | \"upload\"", "declared_type": "GlyphName", "required": true, "description": "Registered glyph to render; an unregistered name renders nothing at all.", "source": { "path": "packages/design-system/src/components/primitives/Icon/Icon.tsx", "line": 16 }, "values": [ "account", "add", "arrow-down", "arrow-left", "arrow-right", "arrow-up", "bell", "block", "call-guard", "call", "card", "caret-down", "caret-up", "cart", "check", "chevron-down", "chevron-left", "chevron-right", "chevron-up", "circle-outline", "clear", "cloaked-ai", "cloaked-pay", "clock", "close", "collapse", "copy", "dark-web-monitoring", "data-removal", "dot", "dropdown-collapse", "dropdown-expand", "email-guard", "email", "expand", "family", "filter", "guard", "home", "info", "lock", "log", "mail", "menu", "message", "missed", "number", "password", "phone", "scan", "search", "send", "settings", "share", "sim", "sms-guard", "sms", "timer", "trash", "trend-down", "trend-up", "upload", "user", "voicemail", "vpn", "wifi" ], "values_complete": true }, { "name": "size", "type": "IconSize", "declared_type": "IconSize", "required": true, "description": "Named tier — 16, 24, or 32px from the size tokens — or a raw px number.", "source": { "path": "packages/design-system/src/components/primitives/Icon/Icon.tsx", "line": 18 } }, { "name": "color", "type": "\"success\" | \"danger\" | \"brand\" | \"primary\" | \"secondary\" | \"ai-primary\" | \"ai-secondary\" | \"inherit\" | undefined", "declared_type": "IconColor", "required": false, "description": "Semantic color token. Omit to inherit the surrounding `currentColor`.", "source": { "path": "packages/design-system/src/components/primitives/Icon/Icon.tsx", "line": 20 }, "values": [ "ai-primary", "ai-secondary", "brand", "danger", "inherit", "primary", "secondary", "success" ], "values_complete": true }, { "name": "strokeWidth", "type": "string | number | undefined", "declared_type": "number | string", "required": false, "description": "Stroke width passed to stroke-based glyphs.", "source": { "path": "packages/design-system/src/components/primitives/Icon/Icon.tsx", "line": 22 } }, { "name": "label", "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/Icon/Icon.tsx", "line": 24 } }, { "name": "ariaLabel", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Accessible label alias for consumers standardizing on aria prop names.", "source": { "path": "packages/design-system/src/components/primitives/Icon/Icon.tsx", "line": 26 } }, { "name": "className", "type": "string | undefined", "declared_type": "string", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/primitives/Icon/Icon.tsx", "line": 27 } }, { "name": "style", "type": "React.CSSProperties | undefined", "declared_type": "React.CSSProperties", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/primitives/Icon/Icon.tsx", "line": 28 } }, { "name": "testId", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Selector forwarded to the rendered svg element.", "source": { "path": "packages/design-system/src/components/primitives/Icon/Icon.tsx", "line": 30 } } ], "branches": [], "constraints": [], "extraction_status": "extracted" } ], "type_sources": [ { "path": "packages/design-system/src/components/primitives/Icon/Icon.tsx", "line": 7, "name": "IconSize", "code": "export type IconSize = 'small' | 'medium' | 'large' | number;" }, { "path": "packages/design-system/src/components/primitives/Icon/Icon.tsx", "line": 8, "name": "IconColor", "code": "export type IconColor = CdsTextColor;" }, { "path": "packages/design-system/src/components/primitives/Icon/Icon.tsx", "line": 14, "name": "IconProps", "code": "export interface IconProps {\n /** Registered glyph to render; an unregistered name renders nothing at all. */\n name: GlyphName;\n /** Named tier — 16, 24, or 32px from the size tokens — or a raw px number. */\n size: IconSize;\n /** Semantic color token. Omit to inherit the surrounding `currentColor`. */\n color?: IconColor;\n /** Stroke width passed to stroke-based glyphs. */\n strokeWidth?: number | string;\n /** Accessible label; omitted icons are hidden from assistive tech. */\n label?: string;\n /** Accessible label alias for consumers standardizing on aria prop names. */\n ariaLabel?: string;\n className?: string;\n style?: React.CSSProperties;\n /** Selector forwarded to the rendered svg element. */\n testId?: string;\n}" }, { "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];" }, { "path": "packages/design-system/src/types/GlyphName.ts", "line": 10, "name": "GLYPH_NAMES", "code": "GLYPH_NAMES = [\n // Action\n 'arrow-left',\n 'arrow-right',\n 'arrow-up',\n 'arrow-down',\n 'chevron-down',\n 'chevron-up',\n 'chevron-left',\n 'chevron-right',\n 'caret-down',\n 'caret-up',\n // Trend lines, for a change in a figure over time. Distinct from the arrows and carets above,\n // which point at a direction without implying a measurement moved.\n 'trend-up',\n 'trend-down',\n 'collapse',\n 'expand',\n 'dropdown-collapse',\n 'dropdown-expand',\n 'close',\n 'clear',\n 'menu',\n 'copy',\n 'search',\n 'add',\n // Renders the `send` drawing; a separate name for share-sheet actions.\n 'share',\n // System\n 'phone',\n 'sim',\n 'account',\n 'family',\n 'home',\n 'wifi',\n 'cart',\n 'vpn',\n 'lock',\n 'block',\n 'timer',\n 'check',\n 'send',\n 'info',\n 'number',\n 'filter',\n 'scan',\n 'log',\n 'trash',\n // Inbox\n 'missed',\n 'call',\n 'voicemail',\n 'sms',\n 'email',\n // Feature\n 'data-removal',\n 'dark-web-monitoring',\n 'cloaked-pay',\n 'cloaked-ai',\n 'sms-guard',\n 'email-guard',\n 'call-guard',\n 'card',\n 'password',\n 'guard',\n // Legacy aliases (kept for back-compat; render the Figma glyph)\n 'bell',\n 'circle-outline',\n 'dot',\n 'settings',\n 'clock',\n 'mail',\n 'message',\n 'user',\n 'upload',\n] as const" }, { "path": "packages/design-system/src/types/GlyphName.ts", "line": 87, "name": "GlyphName", "code": "export type GlyphName = (typeof GLYPH_NAMES)[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." } }