Skip to content
Cloaked Design SystemPrimitives / Iconography

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.

Implementation preview
COMPLETE STORYBOOK REFERENCE

Every example. In one place.

Explore every named example, including states, compositions, and theme variants.

3 stories
SELECTED EXAMPLE

Playground

Open controls
Playground selectedOpen canvas
Example sourcepackages/design-system/src/components/primitives/Glyph/Glyph.stories.tsxExport Playground

Implementation preview Local Storybook build 0.2.0-preview.1. Source specification status does not approve this runtime.

Stories + source JSON ↗

Local specification source status: preview. Implementation preview pending sign-off.

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.

Design-owned component contract ↗Version 0.2.0-preview.1 · Implementation preview pending sign-off
Implementation API 1 entry point · source-derived preview

Read the actual callable API and preserve its composition constraints. Each union branch is a complete alternative; props marked forbidden cannot be supplied.

import { Glyph } from '@cloakedinc/design-system';
GlyphGlyphProps

packages/design-system/src/components/primitives/Glyph/Glyph.tsx:43

PropTypePresenceNotes
name"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"RequiredName of the registered glyph to render.
labelstring | undefinedOptionalAccessible label; unlabeled glyphs are hidden from assistive tech.
classNamestring | undefinedOptional
styleReact.CSSProperties | undefinedOptional
testIdstring | undefinedOptionalOptional test selector. Applied to the `<svg>`, so an unregistered `name` leaves nothing to match.

Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source.

Complete contract · JSON ↗Guidance and source · Markdown ↗

Overview

A Symbol is the token for a specific drawing — the atom under every icon treatment. The web implementation is exported as Glyph: the JS global Symbol (used inside this package) and the SF Symbols vocabulary (SFSymbolName) already own the name in code. iOS keeps calling the equivalent token Symbol (Symbol(source:accessibilityLabel:) in CloakedDesignSystem).

Glyph renders the bare SVG at 1em and currentColor — it inherits size and color from its context and adds no opinion of its own.

The icon stack

  • Glyph — the drawing itself, unstyled. Use when the surrounding context should size and color it (inline with text, or inside a component that establishes both).
  • Icon — the opinionated render: a Glyph at a chosen token size with an optional semantic color.
  • IconTile — a Glyph inside a semantic tone circle; the tile sets the context the glyph inherits.

Names are serializable strings (GlyphName), so data-driven surfaces (widget configs, backend payloads) can carry them; validate untrusted values with isGlyphName — unregistered names render nothing rather than crashing.

Naming contract

Each noun means exactly one layer, in props and variables as much as in component names:

  • A glyph is the drawing identity. Anything holding a GlyphName is named after it: glyph, leadingGlyph, CATEGORY_GLYPHS — never icon, and never the compound iconName (the value is a glyph name, not an icon).
  • An icon is a rendered element. Only elements and element slots use the word: the Icon component, a trailingIcon: ReactNode slot, an icon: ReactElement prop.

The suffix therefore signals the type at a glance: leadingGlyph takes a name from the registry, trailingIcon takes JSX. This is why IconTile and Toast take glyph, not icon — a prop named icon invites passing <Icon />.

Component specification

$schema../../../specs/component-spec.schema.json
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.
Allowed Design Choices
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
Applies To
  • 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.
Typography And Color
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.
Content Adaptation
Label
Glyph selection
Description
Choose the registry name whose established meaning is closest to the action or concept.
Motion Haptics
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.
Platform Differences
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.
Implementation preview

This design-owned implementation is ready to try and review. It does not establish product approval. Imported specifications retain their original review status.

Inspect version 0.2.0-preview.1