# AnimatedNumber

A numeric readout that moves from its previous value to a new target while keeping the settled value accessible.

Version: 0.2.0-preview.1 (preview)
Content digest: 70ac710f4d22dce040e7ac593379ba8aca9dcb59a0b9c0f839819cae0e2bb721
Contract kind: source-derived
Source: packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.tsx

## 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."
}

## Contract and public API

```json
{
  "props": [
    {
      "name": "value",
      "type": "number",
      "declared_type": "number",
      "required": true,
      "description": "Target value to display; a change from the current value animates toward it.",
      "source": {
        "path": "packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.tsx",
        "line": 20
      }
    },
    {
      "name": "follow",
      "type": "boolean | undefined",
      "declared_type": "boolean",
      "required": false,
      "description": "Continuously ease toward `value` every frame instead of running a fixed\ntween per change. Use this while a chart is being scrubbed: `value` changes\non every pointer move, and a per-change tween would restart faster than it\ncan advance (the number would freeze). Follow mode glides smoothly toward\nthe finger and settles when scrubbing stops.",
      "source": {
        "path": "packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.tsx",
        "line": 28
      },
      "values": [
        false,
        true
      ],
      "values_complete": true,
      "default": "false",
      "default_kind": "source-expression"
    },
    {
      "name": "duration",
      "type": "number | undefined",
      "declared_type": "number",
      "required": false,
      "description": "Fixed tween duration in milliseconds for discrete changes. Omit to let the\nduration scale with how large the jump is, so small changes settle quickly\nand big ones feel weightier. Ignored while `follow` is true.",
      "source": {
        "path": "packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.tsx",
        "line": 34
      }
    },
    {
      "name": "format",
      "type": "((value: number) => string) | undefined",
      "declared_type": "(value: number) => string",
      "required": false,
      "description": "Formats the numeric value for display; defaults to locale digit grouping.",
      "source": {
        "path": "packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.tsx",
        "line": 36
      },
      "default": "formatNumber",
      "default_kind": "source-expression"
    },
    {
      "name": "testId",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "Selector on the `<span>`. Its text is a mid-animation frame; `aria-label` holds the settled value.",
      "source": {
        "path": "packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.tsx",
        "line": 38
      }
    }
  ],
  "prop_shapes": {},
  "api": {
    "method": "typescript-type-checker",
    "typescript_version": "5.9.3",
    "public_export": "AnimatedNumber",
    "public_path": "AnimatedNumber",
    "import_path": "@cloakedinc/design-system",
    "root_kind": "component",
    "entrypoints": [
      {
        "name": "AnimatedNumber",
        "signature": 1,
        "visibility": "public",
        "source": {
          "path": "packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.tsx",
          "line": 51
        },
        "props_type": "AnimatedNumberProps",
        "props": [
          {
            "name": "value",
            "type": "number",
            "declared_type": "number",
            "required": true,
            "description": "Target value to display; a change from the current value animates toward it.",
            "source": {
              "path": "packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.tsx",
              "line": 20
            }
          },
          {
            "name": "follow",
            "type": "boolean | undefined",
            "declared_type": "boolean",
            "required": false,
            "description": "Continuously ease toward `value` every frame instead of running a fixed\ntween per change. Use this while a chart is being scrubbed: `value` changes\non every pointer move, and a per-change tween would restart faster than it\ncan advance (the number would freeze). Follow mode glides smoothly toward\nthe finger and settles when scrubbing stops.",
            "source": {
              "path": "packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.tsx",
              "line": 28
            },
            "values": [
              false,
              true
            ],
            "values_complete": true,
            "default": "false",
            "default_kind": "source-expression"
          },
          {
            "name": "duration",
            "type": "number | undefined",
            "declared_type": "number",
            "required": false,
            "description": "Fixed tween duration in milliseconds for discrete changes. Omit to let the\nduration scale with how large the jump is, so small changes settle quickly\nand big ones feel weightier. Ignored while `follow` is true.",
            "source": {
              "path": "packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.tsx",
              "line": 34
            }
          },
          {
            "name": "format",
            "type": "((value: number) => string) | undefined",
            "declared_type": "(value: number) => string",
            "required": false,
            "description": "Formats the numeric value for display; defaults to locale digit grouping.",
            "source": {
              "path": "packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.tsx",
              "line": 36
            },
            "default": "formatNumber",
            "default_kind": "source-expression"
          },
          {
            "name": "testId",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "Selector on the `<span>`. Its text is a mid-animation frame; `aria-label` holds the settled value.",
            "source": {
              "path": "packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.tsx",
              "line": 38
            }
          }
        ],
        "branches": [],
        "constraints": [],
        "extraction_status": "extracted"
      }
    ],
    "type_sources": [
      {
        "path": "packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.tsx",
        "line": 18,
        "name": "AnimatedNumberProps",
        "code": "export interface AnimatedNumberProps {\n    /** Target value to display; a change from the current value animates toward it. */\n    value: number;\n    /**\n     * Continuously ease toward `value` every frame instead of running a fixed\n     * tween per change. Use this while a chart is being scrubbed: `value` changes\n     * on every pointer move, and a per-change tween would restart faster than it\n     * can advance (the number would freeze). Follow mode glides smoothly toward\n     * the finger and settles when scrubbing stops.\n     */\n    follow?: boolean;\n    /**\n     * Fixed tween duration in milliseconds for discrete changes. Omit to let the\n     * duration scale with how large the jump is, so small changes settle quickly\n     * and big ones feel weightier. Ignored while `follow` is true.\n     */\n    duration?: number;\n    /** Formats the numeric value for display; defaults to locale digit grouping. */\n    format?: (value: number) => string;\n    /** Selector on the `<span>`. Its text is a mid-animation frame; `aria-label` holds the settled value. */\n    testId?: string;\n}"
      }
    ],
    "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": "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": []
  },
  "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-display-1-size",
      "light": "4.5rem",
      "dark": "4.5rem"
    },
    {
      "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-animatednumber--playground&viewMode=story) | export: Playground | source: packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.stories.tsx

- [Count Up On Change](/storybook/iframe.html?id=cloaked-design-system-primitives-animatednumber--count-up-on-change&viewMode=story) | export: CountUpOnChange | source: packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.stories.tsx

- [Formatted](/storybook/iframe.html?id=cloaked-design-system-primitives-animatednumber--formatted&viewMode=story) | export: Formatted | source: packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.stories.tsx

- [Scrub Tracking](/storybook/iframe.html?id=cloaked-design-system-primitives-animatednumber--scrub-tracking&viewMode=story) | export: ScrubTracking | source: packages/design-system/src/components/primitives/AnimatedNumber/AnimatedNumber.stories.tsx

Preview pending human sign-off. Source-derived APIs and successful checks do not certify accessibility, native parity or approval.