{ "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": "tag", "name": "Tag", "category": "Primitives", "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-tag--playground", "name": "Playground", "title": "Cloaked Design System/Primitives/Tag", "exportName": "Playground", "source_path": "packages/design-system/src/components/primitives/Tag/Tag.stories.tsx", "source_digest": "42d943b66a7c8acd450a1a81d9e294f61a62936f47007a976b651cd828339158", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-tag--playground&viewMode=story" }, { "id": "cloaked-design-system-primitives-tag--tone-matrix", "name": "Tone Matrix", "title": "Cloaked Design System/Primitives/Tag", "exportName": "ToneMatrix", "source_path": "packages/design-system/src/components/primitives/Tag/Tag.stories.tsx", "source_digest": "42d943b66a7c8acd450a1a81d9e294f61a62936f47007a976b651cd828339158", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-tag--tone-matrix&viewMode=story" }, { "id": "cloaked-design-system-primitives-tag--with-dot", "name": "With Dot", "title": "Cloaked Design System/Primitives/Tag", "exportName": "WithDot", "source_path": "packages/design-system/src/components/primitives/Tag/Tag.stories.tsx", "source_digest": "42d943b66a7c8acd450a1a81d9e294f61a62936f47007a976b651cd828339158", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-tag--with-dot&viewMode=story" }, { "id": "cloaked-design-system-primitives-tag--with-leading-icon", "name": "With Leading Icon", "title": "Cloaked Design System/Primitives/Tag", "exportName": "WithLeadingIcon", "source_path": "packages/design-system/src/components/primitives/Tag/Tag.stories.tsx", "source_digest": "42d943b66a7c8acd450a1a81d9e294f61a62936f47007a976b651cd828339158", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-tag--with-leading-icon&viewMode=story" }, { "id": "cloaked-design-system-primitives-tag--on-inverse-surface", "name": "On Inverse Surface", "title": "Cloaked Design System/Primitives/Tag", "exportName": "OnInverseSurface", "source_path": "packages/design-system/src/components/primitives/Tag/Tag.stories.tsx", "source_digest": "42d943b66a7c8acd450a1a81d9e294f61a62936f47007a976b651cd828339158", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-tag--on-inverse-surface&viewMode=story" }, { "id": "cloaked-design-system-primitives-tag--full-width", "name": "Full Width", "title": "Cloaked Design System/Primitives/Tag", "exportName": "FullWidth", "source_path": "packages/design-system/src/components/primitives/Tag/Tag.stories.tsx", "source_digest": "42d943b66a7c8acd450a1a81d9e294f61a62936f47007a976b651cd828339158", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-tag--full-width&viewMode=story" }, { "id": "cloaked-design-system-primitives-tag--dark-theme", "name": "Dark Theme", "title": "Cloaked Design System/Primitives/Tag", "exportName": "DarkTheme", "source_path": "packages/design-system/src/components/primitives/Tag/Tag.stories.tsx", "source_digest": "42d943b66a7c8acd450a1a81d9e294f61a62936f47007a976b651cd828339158", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-tag--dark-theme&viewMode=story" } ], "name": "Tag", "id": "tag", "category": "Primitives" }, "stories_source": { "path": "packages/design-system/src/components/primitives/Tag/Tag.stories.tsx", "code": "import React from 'react';\nimport type { Meta, StoryObj } from '@storybook/react-vite';\nimport { STATUS_TONES } from '../../../styles/statusTone';\nimport { HStack } from '../../layout/HStack/HStack';\nimport { VStack } from '../../layout/VStack/VStack';\nimport { Icon } from '../Icon/Icon';\nimport { Text } from '../Text/Text';\nimport { Tag } from './Tag';\n\nconst EMPHASES = ['solid', 'subtle', 'outline'] as const;\n\nconst INVERSE_SURFACE: React.CSSProperties = {\n background: 'var(--cds-bg-inverse)',\n padding: 'var(--cds-space-20)',\n borderRadius: 'var(--cds-radius-lg)',\n};\n\nconst meta: Meta = {\n title: 'Cloaked Design System/Primitives/Tag',\n component: Tag,\n args: {\n tone: 'neutral',\n emphasis: 'subtle',\n children: 'Voicemail',\n },\n argTypes: {\n tone: { control: 'select', options: STATUS_TONES },\n emphasis: { control: 'select', options: EMPHASES },\n contrast: { control: 'inline-radio', options: ['default', 'inverse'] },\n dot: { control: 'select', options: [false, true, ...STATUS_TONES] },\n },\n};\nexport default meta;\n\ntype Story = StoryObj;\n\nexport const Playground: Story = {};\n\nexport const ToneMatrix: Story = {\n render: () => (\n \n {EMPHASES.map(emphasis => (\n \n \n {emphasis}\n \n {STATUS_TONES.map(tone => (\n \n {tone}\n \n ))}\n \n ))}\n \n ),\n};\n\nexport const WithDot: Story = {\n parameters: {\n docs: {\n description: {\n story: 'A bare `dot` matches the label color. Passing a tone colors the dot on its own, which is how a status marker shows a green indicator beside a neutral label.',\n },\n },\n },\n render: () => (\n \n \n Active\n \n \n Inactive\n \n \n Live\n \n \n Paused\n \n \n ),\n};\n\nexport const WithLeadingIcon: Story = {\n render: () => (\n \n }>\n Needs help\n \n }>\n Verified\n \n \n ),\n};\n\nexport const OnInverseSurface: Story = {\n render: () => (\n
\n \n \n Submitted\n \n \n Included\n \n \n Covered\n \n \n Overdue\n \n \n
\n ),\n};\n\nexport const FullWidth: Story = {\n render: () => (\n \n \n Submitted Oct 12\n \n \n ),\n};\n\nexport const DarkTheme: Story = {\n globals: { theme: 'dark' },\n render: () => (\n \n {EMPHASES.map(emphasis => (\n \n {STATUS_TONES.map(tone => (\n \n {tone}\n \n ))}\n \n ))}\n \n ),\n};\n" }, "specification": { "$schema": "../../../specs/component-spec.schema.json", "identity": { "name": "Tag", "status": "preview", "version": "2.1.0", "summary": "The single non-interactive marker: a compact pill carrying a status, a label, or a piece of metadata." }, "parts": [ { "id": "root", "label": "Root", "description": "Inline pill that carries the emphasis surface, tone color, and contrast treatment.", "required": true }, { "id": "leading", "label": "Leading", "description": "Optional leading visual, usually an Icon or SFIcon." }, { "id": "dot", "label": "Dot", "description": "Optional indicator dot. Matches the label color by default, or takes its own tone." }, { "id": "label", "label": "Label", "description": "Body-small marker text." } ], "allowedDesignChoices": { "variants": { "solid": { "label": "Solid", "description": "Saturated fill for the one marker that must stand out." }, "subtle": { "label": "Subtle", "description": "Tinted fill for inline metadata and statuses." }, "outline": { "label": "Outline", "description": "Border-only pill for quiet markers on busy surfaces." } }, "sizes": {}, "tones": { "neutral": { "label": "Neutral", "description": "Chrome rather than an outcome. Leaves the status ramp for the surface roles." }, "info": { "label": "Info" }, "success": { "label": "Success" }, "warning": { "label": "Warning" }, "danger": { "label": "Danger" } } }, "variants": [ { "id": "solid", "label": "Solid", "description": "Solid tone fill with inverse text. Neutral resolves to the inverse surface.", "platforms": [ "ios", "android", "web" ] }, { "id": "subtle", "label": "Subtle", "description": "Tinted tone fill with tone-colored text. Neutral resolves to the subtle surface with primary text.", "platforms": [ "ios", "android", "web" ] }, { "id": "outline", "label": "Outline", "description": "Transparent fill with a tone-colored border and text. Neutral borders on the divider token.", "platforms": [ "ios", "android", "web" ] } ], "sizes": [], "measurements": [ { "id": "min-height", "label": "Minimum height", "kind": "exact", "token": "--cds-size-24", "value": 24, "unit": "px", "appliesTo": [ "root" ] }, { "id": "block-padding", "label": "Block padding", "kind": "exact", "token": "--cds-space-4", "value": 4, "unit": "px", "appliesTo": [ "root" ] }, { "id": "inline-padding", "label": "Inline padding", "kind": "exact", "token": "--cds-space-12", "value": 12, "unit": "px", "appliesTo": [ "root" ] }, { "id": "content-gap", "label": "Content gap", "kind": "exact", "token": "--cds-space-8", "value": 8, "unit": "px", "appliesTo": [ "root", "leading", "dot", "label" ] }, { "id": "dot-size", "label": "Dot size", "kind": "exact", "token": "--cds-size-8", "value": 8, "unit": "px", "appliesTo": [ "dot" ] } ], "layout": { "alignment": "Leading visual, dot, and label sit on the marker center line, centered on the main axis so fullWidth stays balanced.", "flow": "One inline pill sized to its content with a fully rounded radius. There is no size axis: Figma draws every marker at one height.", "notes": [ "Use Chip when the pill must be tappable or removable.", "Use StatusIndicator for a bare dot-plus-label with no pill behind it.", "Use Card.Delta for a trend delta such as an up or down arrow beside a number.", "Use Banner or an inset Card for a multi-line callout." ] }, "typographyAndColor": { "typography": [ { "label": "Marker text", "description": "Uses the body-small ramp for the label.", "token": "--cds-type-body-small-size" } ], "colors": [ { "label": "Subtle fill", "description": "The chip fill backs the subtle emphasis: a tint in light, a solid hue in dark.", "token": "--cds-bg-status-info" }, { "label": "Subtle text", "description": "The chip label pairs with the chip fill: the hue in light, white in dark.", "token": "--cds-text-on-status-info" }, { "label": "Solid fill", "description": "Tone solid backs the solid emphasis and the outline border.", "token": "--cds-status-info-solid" }, { "label": "Solid text", "description": "Inverse text sits on a solid tone fill.", "token": "--cds-text-inverse" }, { "label": "Neutral subtle fill", "description": "A neutral marker is chrome, so its tone entry is a surface grey rather than the grey status hue.", "token": "--cds-bg-status-neutral" }, { "label": "Neutral subtle text", "description": "Pairs with the neutral subtle fill.", "token": "--cds-text-on-status-neutral" }, { "label": "Neutral solid fill", "description": "The boldest neutral treatment, matching the selected Chip pairing.", "token": "--cds-bg-inverse" }, { "label": "Neutral outline border", "description": "The divider token borders a neutral outline marker.", "token": "--cds-divider" }, { "label": "Inverse contrast fill", "description": "Backs a neutral marker placed on a dark or branded surface.", "token": "--cds-bg-subtle-inverse" } ] }, "states": [ { "id": "solid", "label": "Solid", "description": "Tone solid fill with inverse text." }, { "id": "subtle", "label": "Subtle", "description": "Tone subtle fill with tone solid text." }, { "id": "outline", "label": "Outline", "description": "Transparent fill with a tone solid border and text." }, { "id": "with-dot", "label": "With dot", "description": "Shows a leading dot that either matches the label color or carries its own tone." }, { "id": "contrast-inverse", "label": "Inverse contrast", "description": "Neutral chrome retuned for a dark or branded surface. A toned marker keeps its tone." }, { "id": "full-width", "label": "Full width", "description": "Stretches to the parent width, keeping content centered." } ], "behavior": [ { "label": "Tone", "description": "Set tone to the semantic status. Neutral means chrome and leaves the status ramp for the surface roles." }, { "label": "Independent dot tone", "description": "Pass a tone to dot when the indicator and the label carry different meanings, such as a green dot beside a neutral label." }, { "label": "Non-interactive", "description": "A Tag is a span with no role and no focus stop. Never attach press or removal behavior; use Chip instead." }, { "label": "Presets live in the app", "description": "Product concepts such as live or paused belong in an app wrapper or in the recipe table, not in a design-system part." } ], "accessibility": [ { "label": "Visible meaning", "description": "Keep textual content so the marker reads without relying on color or the dot alone." }, { "label": "Decorative dot", "description": "The dot is aria-hidden; the visible label carries the meaning." }, { "label": "No focus stop", "description": "The root adds no tab stop and no role, which is what separates a Tag from a Chip." } ], "contentAdaptation": [ { "label": "Concise content", "description": "Use short labels that stay on one line without wrapping." }, { "label": "Overflow", "description": "A label wider than the tag truncates with an ellipsis rather than wrapping or spilling past the pill. Treat that as a backstop, not a layout: pick copy that fits the narrowest place the tag appears." }, { "label": "Leading visual", "description": "Pair a glyph with the label rather than replacing the text." } ], "motionHaptics": { "motion": [ { "label": "Stable geometry", "description": "Changing tone or emphasis recolors the pill without animating layout." } ], "haptics": [ { "label": "No feedback", "description": "Tag is non-interactive and requests no haptics." } ] }, "platformDifferences": [ { "platforms": [ "ios", "android" ], "description": "Native platforms have no built-in equivalent to map onto. Apple's HIG has no tag, chip, or pill, and the iOS badge modifier is an anchored count rather than a free-standing marker.", "rationale": "Internal consistency governs this component instead of platform fidelity, so each platform builds the same pill rather than substituting a native control that means something else." }, { "platforms": [ "web" ], "description": "Figma draws a 6px indicator dot. Web renders 8px.", "rationale": "6px sits off the 4-step size ramp, and both Badge and StatusIndicator already use 8px, so matching them beats minting an off-ramp token for a 2px difference." } ] }, "specification_source": "packages/design-system/src/components/primitives/Tag/Tag.spec.json", "guidance": { "summary": "The single non-interactive marker: a compact pill carrying a status, a label, or a piece of metadata.", "guidance": [ { "heading": "Overview", "body": "The single non-interactive marker. A Tag is a compact pill carrying a status, a label, or a piece of\nmetadata. `tone` sets the meaning, `emphasis` sets how much it stands out, and `contrast` retunes the\nchrome for a dark or branded surface." }, { "heading": "Tag or Chip", "body": "A Tag renders a `` with no role and no focus stop. A Chip renders a button that takes focus and\nresponds to a tap. That difference is in the DOM and the accessibility tree, not in the styling, which\nis why they are separate components rather than one component with an `onPress` prop.\n\nSo the question is never how the pill looks. It is whether tapping it does anything." }, { "heading": "Tone and emphasis", "body": "`tone` carries the Status tone axis. `emphasis` picks the surface.\n\n`neutral` is the exception worth understanding: a neutral marker is chrome rather than an outcome, so\nit leaves the status ramp and uses the surface roles instead. That is what makes a neutral pill read\nas a label rather than as a grey status.\n\n| Tone | `subtle` | `solid` | `outline` |\n| --------- | ---------------------------------- | --------------------------------- | -------------------------- |\n| `neutral` | `--cds-bg-subtle` + primary text | `--cds-bg-inverse` + inverse text | `--cds-divider` border |\n| any other | tone subtle fill + tone solid text | tone solid fill + inverse text | tone solid border and text |\n\n`tone` is the Status tone axis and nothing else. A marker carrying product identity rather than an\noutcome does not belong here." }, { "heading": "The dot", "body": "`dot` takes a boolean or a tone. A bare `dot` matches the label color. Passing a tone colors the dot\non its own, which is how a marker shows a green indicator beside a neutral label." }, { "heading": "Recipes", "body": "The design system owns the axes. Product concepts own their prop combinations. When a preset appears\nin more than one place, wrap it in the feature that uses it rather than adding a part here, the way\n`ActivityStatusTag` wraps its tone and glyph.\n\nA running or stopped state appears twice, at two prominences. Reach for the ambient row when the\nmarker sits beside a title that already says what it describes, and the announced row when the state\nis the thing the surface is about.\n\n| Product concept | Props |\n| ---------------------------- | ------------------------------------------------ |\n| Running, ambient | `tone='neutral' emphasis='subtle' dot='success'` |\n| Stopped, ambient | `tone='neutral' emphasis='subtle' dot` |\n| Running, announced | `tone='success' emphasis='solid' dot='neutral'` |\n| Stopped, announced | `tone='neutral' emphasis='solid' dot='neutral'` |\n| Overdue | `tone='danger' emphasis='solid'` |\n| Complete / done | `tone='success' emphasis='subtle'` |\n| Needs help | `tone='warning' emphasis='solid' leading={...}` |\n| Metadata / category | `tone='neutral' emphasis='subtle'` |\n| Count | `tone='neutral' emphasis='subtle'` |\n| AI-assisted | `tone='info' emphasis='subtle' leading={...}` |\n| Neutral on a dark widget | add `contrast='inverse'` |" }, { "heading": "Reach for something else", "body": "| Instead of a Tag | Use | Because |\n| -------------------- | ------------------ | --------------------------------------------------- |\n| A tappable pill | `Chip` | It needs a role and a focus stop. |\n| A removable value | `Chip` | The remove affordance is a second button. |\n| A bare dot and label | `StatusIndicator` | No pill behind it; it rides inside a row. |\n| An up or down trend | `Card.Delta` | A delta is a change in a number, not a state. |\n| A multi-line callout | `Banner` | It is a block of feedback, not a marker. |\n| A notification count | Avatar or tab slot | An anchored count belongs on the element it counts. |" }, { "heading": "Sizes", "body": "There is no `size` prop. Figma draws every marker at one height, and the two sizes the old\n`Tag.Status` carried differed only in horizontal inset." }, { "heading": "On a dark surface", "body": "`contrast='inverse'` resolves a `neutral` marker to the inverse roles, so the chrome keeps its\ntreatment on a surface that is dark in both themes. It has no effect on a toned marker: the status\nfills are opaque in both themes and already read on a dark surface, so a `success` or `danger`\nmarker keeps its tone rather than losing it to grey chrome." }, { "heading": "Full width", "body": "`fullWidth` stretches the marker to its parent, for a card footer that carries a state across the\nwhole row." } ], "usage": [], "examples": [ { "kind": "do", "caption": "Use Tag for anything the user only reads: a status, a category, a timestamp, a count." }, { "kind": "dont", "caption": "Give a Tag an `onClick` through `className` or a wrapper. Users try to tap things that look tappable, so a marker\n that does something must be a Chip." } ], "source": "packages/design-system/src/components/primitives/Tag/Tag.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-tag", "json": "/data/visual/components/tag.json", "storybook": "/storybook/?path=/story/cloaked-design-system-primitives-tag--playground" } }