{ "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": "animatednumber", "name": "AnimatedNumber", "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-animatednumber--playground", "name": "Playground", "title": "Cloaked Design System/Primitives/AnimatedNumber", "exportName": "Playground", "source_path": "packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.stories.tsx", "source_digest": "2dad9645a59bc81f2263ec4e0e2cd2f8d2996952ca7ea37f57c00f9948095c8c", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-animatednumber--playground&viewMode=story" }, { "id": "cloaked-design-system-primitives-animatednumber--count-up-on-change", "name": "Count Up On Change", "title": "Cloaked Design System/Primitives/AnimatedNumber", "exportName": "CountUpOnChange", "source_path": "packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.stories.tsx", "source_digest": "2dad9645a59bc81f2263ec4e0e2cd2f8d2996952ca7ea37f57c00f9948095c8c", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-animatednumber--count-up-on-change&viewMode=story" }, { "id": "cloaked-design-system-primitives-animatednumber--formatted", "name": "Formatted", "title": "Cloaked Design System/Primitives/AnimatedNumber", "exportName": "Formatted", "source_path": "packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.stories.tsx", "source_digest": "2dad9645a59bc81f2263ec4e0e2cd2f8d2996952ca7ea37f57c00f9948095c8c", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-animatednumber--formatted&viewMode=story" }, { "id": "cloaked-design-system-primitives-animatednumber--scrub-tracking", "name": "Scrub Tracking", "title": "Cloaked Design System/Primitives/AnimatedNumber", "exportName": "ScrubTracking", "source_path": "packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.stories.tsx", "source_digest": "2dad9645a59bc81f2263ec4e0e2cd2f8d2996952ca7ea37f57c00f9948095c8c", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-animatednumber--scrub-tracking&viewMode=story" } ], "name": "AnimatedNumber", "id": "animatednumber", "category": "Primitives" }, "stories_source": { "path": "packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.stories.tsx", "code": "import React from 'react';\nimport type { Meta, StoryObj } from '@storybook/react-vite';\nimport { Button } from '../Button/Button';\nimport { HStack } from '../../layout/HStack/HStack';\nimport { VStack } from '../../layout/VStack/VStack';\nimport { Text } from '../Text/Text';\nimport { disabledControl } from '../../../storybook/controlOptions';\nimport { AnimatedNumber } from './AnimatedNumber';\n\nconst meta: Meta = {\n title: 'Cloaked Design System/Primitives/AnimatedNumber',\n component: AnimatedNumber,\n parameters: {\n a11y: { test: 'error' },\n docs: {\n description: {\n component:\n 'A numeric readout that tweens from its old `value` to its new one on every change (physical ' +\n 'ease-in-out; never on mount; snaps under `prefers-reduced-motion`). It owns only motion + ' +\n 'formatting — wrap it in a `Text` (or `Card.Metric`) for typography and color. Set `follow` while a ' +\n 'chart is being scrubbed so per-move `value` updates glide instead of restarting each tween.',\n },\n },\n },\n args: {\n value: 1549,\n },\n argTypes: {\n value: {\n control: { type: 'number' },\n description: 'Target value; a change from the current display animates toward it.',\n },\n follow: {\n control: 'boolean',\n description:\n 'Per-frame glide toward `value` (for scrubbing) instead of a discrete tween. Ignores `duration`.',\n },\n duration: {\n control: { type: 'number' },\n description:\n 'Fixed tween ms for discrete changes. Omit to auto-scale with jump size. Ignored while `follow`.',\n },\n format: {\n ...disabledControl,\n description: 'Maps the number to a display string; defaults to locale digit grouping.',\n },\n },\n};\nexport default meta;\ntype Story = StoryObj;\n\nexport const Playground: Story = {\n render: args => (\n \n \n \n ),\n};\n\nfunction CountUpDemo() {\n const [value, setValue] = React.useState(1516);\n\n return (\n \n \n \n \n \n setValue(v => v + 137)}\n testId='animated-number-count-up-increment'\n >\n +137\n \n setValue(v => Math.max(0, v - 412))}\n testId='animated-number-count-up-decrement'\n >\n -412\n \n \n \n );\n}\n\nexport const CountUpOnChange: Story = {\n parameters: {\n docs: {\n description: {\n story: 'Discrete tween: each button press animates from the current value to the new total.',\n },\n },\n },\n render: () => ,\n};\n\nexport const Formatted: Story = {\n parameters: {\n docs: { description: { story: 'A custom `format` fn animates the raw number but renders it as currency.' } },\n },\n render: () => (\n \n \n n.toLocaleString('en-US', { style: 'currency', currency: 'USD', maximumFractionDigits: 0 })\n }\n />\n \n ),\n};\n\nconst SCRUB_VALUES = [241, 388, 612, 1102, 1549];\n\nfunction ScrubDemo() {\n const [index, setIndex] = React.useState(null);\n const shown = index == null ? 1549 : SCRUB_VALUES[index];\n\n return (\n \n \n {/* follow mode glides toward each selected bar while scrubbing; Release runs the momentum tick to total. */}\n \n \n \n {SCRUB_VALUES.map((v, i) => (\n setIndex(i)}\n testId={`animated-number-scrub-bar-${i + 1}`}\n >\n bar {i + 1}\n \n ))}\n setIndex(null)}\n testId='animated-number-scrub-release'\n >\n Release\n \n \n \n );\n}\n\nexport const ScrubTracking: Story = {\n parameters: {\n docs: {\n description: {\n story: '`follow` mode glides toward each tapped bar while scrubbing; Release settles to the total.',\n },\n },\n },\n render: () => ,\n};\n" }, "specification": { "$schema": "../../../specs/component-spec.schema.json", "identity": { "name": "AnimatedNumber", "status": "preview", "version": "1.0.0", "summary": "A numeric readout that moves from its previous value to a new target while keeping the settled value accessible." }, "parts": [ { "id": "readout", "label": "Readout", "description": "Displays each formatted frame and carries the settled target as its accessible name." } ], "allowedDesignChoices": { "variants": { "base": { "label": "Base", "description": "The component owns number motion and formatting; its parent owns typography and color." } }, "sizes": {} }, "variants": [ { "id": "base", "label": "Base", "description": "A typography-neutral animated numeric readout.", "platforms": [ "ios", "android", "web" ] } ], "sizes": [], "measurements": [ { "id": "display-example-type-size", "label": "Display example type size", "kind": "exact", "token": "--cds-type-display-1-size", "value": 72, "unit": "px", "appliesTo": [ "readout", "display-example" ], "notes": "The primary Storybook example composes AnimatedNumber inside Text display-1; consumers may choose another Text variant." }, { "id": "intrinsic-width", "label": "Readout width", "kind": "automatic", "appliesTo": [ "readout" ], "notes": "Width follows the formatted frame and is not reserved to the target string." } ], "layout": { "alignment": "The inline readout follows its parent text baseline.", "flow": "One formatted number occupies the parent typography run.", "notes": [ "Compose the readout inside Text or Card.Metric; AnimatedNumber does not establish a text hierarchy." ] }, "typographyAndColor": { "typography": [ { "label": "Example metric", "description": "The documented metric example uses the largest display ramp.", "token": "--cds-type-display-1-size" } ], "colors": [ { "label": "Example foreground", "description": "The documented metric example uses the primary text role.", "token": "--cds-text-primary" } ] }, "states": [ { "id": "resting", "label": "Resting", "description": "Shows the target immediately on mount and after motion settles." }, { "id": "animating", "label": "Animating", "description": "Runs one eased tween from the current display to a discrete target." }, { "id": "following", "label": "Following", "description": "Continuously glides toward rapidly changing targets during chart scrubbing." }, { "id": "reduced-motion", "label": "Reduced motion", "description": "Snaps directly to each target without intermediate frames." } ], "behavior": [ { "label": "Discrete changes", "description": "Scale duration with the magnitude of the change unless an explicit duration is supplied." }, { "label": "Rapid changes", "description": "Use follow mode for pointer-driven values so repeated updates do not restart a fixed tween." }, { "label": "Formatting", "description": "Apply the formatter to both the visible frame and the settled accessible value." } ], "accessibility": [ { "label": "Settled value", "description": "Expose the target as the accessible name so assistive technology never announces intermediate frames." }, { "label": "No live-region churn", "description": "Do not announce every animation frame; a surrounding live region may announce a meaningful completed update." } ], "contentAdaptation": [ { "label": "Number formats", "description": "Accept locale grouping, currency, percentages, and other deterministic numeric formatters." }, { "label": "Changing width", "description": "Allow enough parent space for the longest expected formatted value to avoid adjacent layout jumps." } ], "motionHaptics": { "motion": [ { "label": "Counter motion", "description": "Accelerate from rest and coast into the target for discrete changes; follow mode stays responsive to scrubbing." }, { "label": "Reduced motion", "description": "Honor the platform reduced-motion preference by removing the tween." } ], "haptics": [ { "label": "No feedback", "description": "The readout is not interactive and does not request haptic feedback." } ] }, "platformDifferences": [] }, "specification_source": "packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.spec.json", "guidance": { "summary": "A numeric readout that moves from its previous value to a new target while keeping the settled value accessible.", "guidance": [ { "heading": "Overview", "body": "A number that counts from its previous value to its new one whenever `value` changes, with a\nphysical ease-in-out ramp. It owns only the animation and formatting — wrap it in a `Text` (or\n`Card.Metric`) for typography and color." }, { "heading": "When to use", "body": "Reach for `AnimatedNumber` when a numeric readout _changes_ and the motion carries meaning — a stat\nthat ticks up as work completes, a counter reacting to user action, or a value scrubbed along a\nchart. In-app it backs the Home stat widgets (`ActionsTakenWidget`,\n`BlockedSpamCallsWidget`, `SsnMonitoringWidget`) and the automations `StatsRow`.\n\n- Rendering a **static number** that never animates? Just put it in `Text` — the tween is wasted (and\n `AnimatedNumber` deliberately does not animate on mount, so a value that never changes looks\n identical to plain text anyway).\n- Value updates **every frame** while a chart is scrubbed? Set `follow` so it glides toward the\n moving target instead of restarting a discrete tween on each change.\n\nIt animates in either direction and snaps instead of animating under `prefers-reduced-motion`." } ], "usage": [], "examples": [], "source": "packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.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-animatednumber", "json": "/data/visual/components/animatednumber.json", "storybook": "/storybook/?path=/story/cloaked-design-system-primitives-animatednumber--playground" } }