{ "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": "glyph", "name": "Glyph", "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-symbol--playground", "name": "Playground", "title": "Cloaked Design System/Primitives/Iconography/Symbol", "exportName": "Playground", "source_path": "packages/design-system/src/components/primitives/Glyph/Glyph.stories.tsx", "source_digest": "24980caba459e06a557489270ac502840189d0574f78c1ce0fd0b85e39bb6da5", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-iconography-symbol--playground&viewMode=story" }, { "id": "cloaked-design-system-primitives-iconography-symbol--inherits-context", "name": "Inherits Context", "title": "Cloaked Design System/Primitives/Iconography/Symbol", "exportName": "InheritsContext", "source_path": "packages/design-system/src/components/primitives/Glyph/Glyph.stories.tsx", "source_digest": "24980caba459e06a557489270ac502840189d0574f78c1ce0fd0b85e39bb6da5", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-iconography-symbol--inherits-context&viewMode=story" }, { "id": "cloaked-design-system-primitives-iconography-symbol--symbol-grid", "name": "Symbol Grid", "title": "Cloaked Design System/Primitives/Iconography/Symbol", "exportName": "SymbolGrid", "source_path": "packages/design-system/src/components/primitives/Glyph/Glyph.stories.tsx", "source_digest": "24980caba459e06a557489270ac502840189d0574f78c1ce0fd0b85e39bb6da5", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-iconography-symbol--symbol-grid&viewMode=story" } ], "name": "Glyph", "id": "glyph", "category": "Primitives / Iconography" }, "stories_source": { "path": "packages/design-system/src/components/primitives/Glyph/Glyph.stories.tsx", "code": "import React from 'react';\nimport type { Meta, StoryObj } from '@storybook/react-vite';\nimport { Grid } from '../../layout/Grid/Grid';\nimport { VStack } from '../../layout/VStack/VStack';\nimport { selectArgType } from '../../../storybook/controlOptions';\nimport { Text } from '../Text/Text';\nimport { Glyph, GLYPH_GROUPS, GLYPH_NAMES } from './Glyph';\n\nconst meta: Meta = {\n title: 'Cloaked Design System/Primitives/Iconography/Symbol',\n component: Glyph,\n parameters: {\n a11y: { test: 'error' },\n docs: {\n description: {\n component:\n 'The unstyled glyph atom — a Symbol in the design language, exported as `Glyph` in the engine ' +\n 'because the JS global `Symbol` and the SF Symbols vocabulary already own that name (iOS still ' +\n 'calls its equivalent token `Symbol`). Renders the bare SVG at `1em`/`currentColor`, inheriting ' +\n 'size and color from context. Reach for `Icon` to render a glyph at a chosen size, and `IconTile` ' +\n 'for a glyph in a tone circle.',\n },\n },\n },\n args: {\n name: 'guard',\n },\n argTypes: {\n name: {\n ...selectArgType(GLYPH_NAMES),\n description: 'Glyph from the bundled DS registry (a `GlyphName`).',\n },\n label: {\n control: 'text',\n description: 'Accessible label. Omit for decorative, `aria-hidden` glyphs.',\n },\n },\n};\nexport default meta;\ntype Story = StoryObj;\n\nexport const Playground: Story = {\n args: {\n label: 'Guard',\n },\n};\n\nexport const InheritsContext: Story = {\n parameters: {\n docs: {\n description: {\n story: 'A bare glyph is `1em` and `currentColor` — it rides the surrounding font-size and text color.',\n },\n },\n },\n render: () => (\n \n \n Checked at body-small\n \n \n Checked at h2\n \n \n ),\n};\n\nexport const SymbolGrid: Story = {\n parameters: {\n docs: { description: { story: 'The full registry grouped by category — the catalogue for picking a `name`.' } },\n },\n render: () => (\n \n {GLYPH_GROUPS.map(group => (\n \n \n {group.label}\n \n \n {group.names.map(name => (\n \n \n \n {name}\n \n \n ))}\n \n \n ))}\n \n ),\n};\n" }, "specification": { "$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." } ] }, "specification_source": "packages/design-system/src/components/primitives/Glyph/Glyph.spec.json", "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." }, "links": { "human": "/component-glyph", "json": "/data/visual/components/glyph.json", "storybook": "/storybook/?path=/story/cloaked-design-system-primitives-iconography-symbol--playground" } }