# Glyph The unstyled glyph atom: a registered SVG drawing rendered at 1em and currentColor, inheriting size and color from context. The design language calls the concept a Symbol; the web implementation is exported as Glyph because the JS global and SF Symbols already own the Symbol name. Version: 0.2.0-preview.1 (preview) Content digest: 70ac710f4d22dce040e7ac593379ba8aca9dcb59a0b9c0f839819cae0e2bb721 Contract kind: source-derived Source: packages/design-system/src/components/primitives/Glyph/Glyph.tsx ## Guidance { "summary": "The unstyled glyph atom: a registered SVG drawing rendered at 1em and currentColor, inheriting size and color from context. The design language calls the concept a Symbol; the web implementation is exported as Glyph because the JS global and SF Symbols already own the Symbol name.", "guidance": [ { "heading": "Overview", "body": "A **Symbol** is the token for a specific drawing — the atom under every icon treatment. The web\nimplementation is exported as **`Glyph`**: the JS global `Symbol` (used inside this package) and the\nSF Symbols vocabulary (`SFSymbolName`) already own the name in code. iOS keeps calling the\nequivalent token `Symbol` (`Symbol(source:accessibilityLabel:)` in `CloakedDesignSystem`).\n\n`Glyph` renders the bare SVG at `1em` and `currentColor` — it inherits size and color from its\ncontext and adds no opinion of its own." }, { "heading": "The icon stack", "body": "- **`Glyph`** — the drawing itself, unstyled. Use when the surrounding context should size and\n color it (inline with text, or inside a component that establishes both).\n- **`Icon`** — the opinionated render: a `Glyph` at a chosen token size with an optional semantic\n color.\n- **`IconTile`** — a `Glyph` inside a semantic tone circle; the tile sets the context the glyph\n inherits.\n\nNames are serializable strings (`GlyphName`), so data-driven surfaces (widget configs, backend\npayloads) can carry them; validate untrusted values with `isGlyphName` — unregistered names render\nnothing rather than crashing." }, { "heading": "Naming contract", "body": "Each noun means exactly one layer, in props and variables as much as in component names:\n\n- A **glyph** is the drawing identity. Anything holding a `GlyphName` is named after it:\n `glyph`, `leadingGlyph`, `CATEGORY_GLYPHS` — never `icon`, and never the compound `iconName`\n (the value is a glyph name, not an icon).\n- An **icon** is a rendered element. Only elements and element slots use the word: the `Icon`\n component, a `trailingIcon: ReactNode` slot, an `icon: ReactElement` prop.\n\nThe suffix therefore signals the type at a glance: `leadingGlyph` takes a name from the registry,\n`trailingIcon` takes JSX. This is why `IconTile` and `Toast` take `glyph`, not `icon` — a prop\nnamed `icon` invites passing ``." } ], "usage": [], "examples": [], "source": "packages/design-system/src/components/primitives/Glyph/Glyph.mdx", "status": "local-preview", "note": "Guidance is read from local documentation, originally imported from the frozen source. Platform assertions in guidance are not parity verification." } ## Contract and public API ```json { "props": [ { "name": "name", "type": "\"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": "Name of the registered glyph to render.", "source": { "path": "packages/design-system/src/components/primitives/Glyph/Glyph.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": "label", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Accessible label; unlabeled glyphs are hidden from assistive tech.", "source": { "path": "packages/design-system/src/components/primitives/Glyph/Glyph.tsx", "line": 18 } }, { "name": "className", "type": "string | undefined", "declared_type": "string", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/primitives/Glyph/Glyph.tsx", "line": 19 } }, { "name": "style", "type": "React.CSSProperties | undefined", "declared_type": "React.CSSProperties", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/primitives/Glyph/Glyph.tsx", "line": 20 } }, { "name": "testId", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Optional test selector. Applied to the ``, so an unregistered `name` leaves nothing to match.", "source": { "path": "packages/design-system/src/components/primitives/Glyph/Glyph.tsx", "line": 22 } } ], "prop_shapes": {}, "api": { "method": "typescript-type-checker", "typescript_version": "5.9.3", "public_export": "Glyph", "public_path": "Glyph", "import_path": "@cloakedinc/design-system", "root_kind": "component", "entrypoints": [ { "name": "Glyph", "signature": 1, "visibility": "public", "source": { "path": "packages/design-system/src/components/primitives/Glyph/Glyph.tsx", "line": 43 }, "props_type": "GlyphProps", "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": "Name of the registered glyph to render.", "source": { "path": "packages/design-system/src/components/primitives/Glyph/Glyph.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": "label", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Accessible label; unlabeled glyphs are hidden from assistive tech.", "source": { "path": "packages/design-system/src/components/primitives/Glyph/Glyph.tsx", "line": 18 } }, { "name": "className", "type": "string | undefined", "declared_type": "string", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/primitives/Glyph/Glyph.tsx", "line": 19 } }, { "name": "style", "type": "React.CSSProperties | undefined", "declared_type": "React.CSSProperties", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/primitives/Glyph/Glyph.tsx", "line": 20 } }, { "name": "testId", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Optional test selector. Applied to the ``, so an unregistered `name` leaves nothing to match.", "source": { "path": "packages/design-system/src/components/primitives/Glyph/Glyph.tsx", "line": 22 } } ], "branches": [], "constraints": [], "extraction_status": "extracted" } ], "type_sources": [ { "path": "packages/design-system/src/components/primitives/Glyph/Glyph.tsx", "line": 14, "name": "GlyphProps", "code": "export interface GlyphProps {\n /** Name of the registered glyph to render. */\n name: GlyphName;\n /** Accessible label; unlabeled glyphs are hidden from assistive tech. */\n label?: string;\n className?: string;\n style?: React.CSSProperties;\n /** Optional test selector. Applied to the ``, so an unregistered `name` leaves nothing to match. */\n testId?: string;\n}" }, { "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." }, "spec": { "$schema": "../../../specs/component-spec.schema.json", "identity": { "name": "Symbol (Glyph)", "status": "preview", "version": "1.1.0", "summary": "The unstyled glyph atom: a registered SVG drawing rendered at 1em and currentColor, inheriting size and color from context. The design language calls the concept a Symbol; the web implementation is exported as Glyph because the JS global and SF Symbols already own the Symbol name." }, "parts": [ { "id": "svg", "label": "SVG", "description": "The bare vector element: view box, decorative-by-default accessibility, and context inheritance." }, { "id": "paths", "label": "Paths", "description": "The path data registered for the selected GlyphName." } ], "allowedDesignChoices": { "variants": { "base": { "label": "Base", "description": "The glyph name changes the drawing without changing the component treatment." } }, "sizes": { "contextual": { "label": "Contextual", "description": "No size axis of its own — the glyph is 1em and follows the surrounding font-size." } } }, "variants": [ { "id": "base", "label": "Base", "description": "A registry-backed SVG drawing with no size or color opinion of its own.", "platforms": [ "ios", "android", "web" ] } ], "sizes": [ { "id": "contextual", "label": "Contextual", "description": "1em square; the parent sets font-size (IconTile) or explicit dimensions (Icon) to size the glyph." } ], "measurements": [ { "id": "intrinsic-size", "label": "Intrinsic size", "kind": "automatic", "appliesTo": [ "svg" ], "notes": "1em square by default, so the glyph rides the surrounding font-size until a composite layer overrides it." } ], "layout": { "alignment": "The SVG occupies a square and aligns according to its parent layout.", "flow": "The glyph is a non-shrinking visual with overflow visible for registered strokes.", "notes": [ "Reach for Icon to render a glyph at a chosen size; reach for IconTile for a glyph in a tone circle.", "The base class has zero CSS specificity so composite layers override sizing freely." ] }, "typographyAndColor": { "typography": [ { "label": "Contextual font-size", "description": "The glyph is 1em, so the surrounding type ramp is its size axis; catalog captions use the body-small ramp.", "token": "--cds-type-body-small-size" } ], "colors": [ { "label": "Current color", "description": "Glyphs always draw with the surrounding currentColor; semantic color selection lives on Icon.", "token": "--cds-text-primary" } ] }, "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 when a composite layer forwards one." }, { "id": "unregistered", "label": "Unregistered name", "description": "Renders nothing so data-driven names degrade gracefully; validate untrusted values with isGlyphName." } ], "behavior": [ { "label": "Registry", "description": "Render only glyph names exported by the design-system glyph registry (GLYPH_NAMES)." }, { "label": "Context inheritance", "description": "Size follows the surrounding font-size and color follows currentColor; the atom adds no opinion." }, { "label": "Runtime validation", "description": "isGlyphName narrows untrusted strings (widget configs, backend payloads) to registered names." } ], "accessibility": [ { "label": "Decorative by default", "description": "Unlabeled glyphs are aria-hidden; composite layers own the user-facing label API." } ], "contentAdaptation": [ { "label": "Glyph selection", "description": "Choose the registry name whose established meaning is closest to the action or concept." } ], "motionHaptics": { "motion": [ { "label": "No intrinsic motion", "description": "Glyph does not animate itself; a parent interaction may transform the whole drawing." } ], "haptics": [ { "label": "No feedback", "description": "Glyph is not interactive and does not request haptic feedback." } ] }, "platformDifferences": [ { "platforms": [ "ios" ], "description": "iOS names this layer Symbol and bakes the accessibility label into the token (Symbol(source:accessibilityLabel:)); the web atom takes the label as an optional prop and stays decorative by default.", "rationale": "Web glyphs usually sit next to visible text and should stay hidden from screen readers, while the iOS token system guarantees every symbol ships with a label. The web export is named Glyph because the JS global Symbol and the SF Symbols vocabulary already occupy the name." } ] }, "platforms": { "implemented": [ "web" ], "native": "Imported design guidance only; no native implementation or parity verification in this preview.", "react": { "implementation": "local", "status": "preview", "parity": "web-reference" }, "vue": { "implementation": "absent", "parity": "not-verified", "status": "reference-only" }, "swift": { "implementation": "absent", "parity": "not-verified", "status": "reference-only" }, "kotlin": { "implementation": "absent", "parity": "not-verified", "status": "reference-only" } }, "tokens": [ { "name": "--cds-type-body-small-size", "light": "0.875rem", "dark": "0.875rem" }, { "name": "--cds-text-primary", "light": "#141410", "dark": "#f3f1ed" } ], "review": { "local_status": "not-reviewed", "source_approval": null, "imported_spec_status": "approved", "spec_origin": "imported-adapted", "local_spec_source_status": "approved", "imported_source_revision": "f96f416e1c3bfbfaffcd155a88b87b18b8bb25f1", "note": "Inherited specification status is provenance, not approval of the current local implementation or extracted contract." }, "missing_facts": [ { "code": "human-review-pending", "detail": "This local preview has no recorded human design or engineering sign-off." }, { "code": "platform-parity-unverified", "detail": "Vue, Swift and Kotlin implementations are absent from this package; platform parity has not been verified." }, { "code": "figma-mapping-unverified", "detail": "No current component-level Figma node and immutable revision have been verified for this contract." } ] } ``` ## Visual states - [Playground](/storybook/iframe.html?id=cloaked-design-system-primitives-iconography-symbol--playground&viewMode=story) | export: Playground | source: packages/design-system/src/components/primitives/Glyph/Glyph.stories.tsx - [Inherits Context](/storybook/iframe.html?id=cloaked-design-system-primitives-iconography-symbol--inherits-context&viewMode=story) | export: InheritsContext | source: packages/design-system/src/components/primitives/Glyph/Glyph.stories.tsx - [Symbol Grid](/storybook/iframe.html?id=cloaked-design-system-primitives-iconography-symbol--symbol-grid&viewMode=story) | export: SymbolGrid | source: packages/design-system/src/components/primitives/Glyph/Glyph.stories.tsx Preview pending human sign-off. Source-derived APIs and successful checks do not certify accessibility, native parity or approval.