# RiskMeter

A horizontal 0-100 track carrying a low-to-high risk gradient for a single severity value, marked with a thumb handle or a you-are-here pointer.

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

## Guidance

{
  "summary": "A horizontal 0-100 track carrying a low-to-high risk gradient for a single severity value, marked with a thumb handle or a you-are-here pointer.",
  "guidance": [
    {
      "heading": "Overview",
      "body": "A horizontal 0-100 track carrying a low-to-high risk gradient for a single severity value."
    },
    {
      "heading": "When to use",
      "body": "Use RiskMeter when the value has severity meaning — an exposure or risk score — not plain\nprogress. For neutral completion use `HalfGauge`; for a bare linear bar use `Progress`.\n\nThe `marker` picks the reading. `thumb` (default) is a handle with the track dimmed past the\nvalue, for a progress-like \"how bad is it.\" `pointer` keeps the full gradient visible with a\ntriangle pointing at the value, for \"you are here on the scale.\" Set `hidden` to keep loading\nsemantics while masking the value.\n\nUsed on Playlist Home in `DigitalRiskWidget` and `DigitalRiskDetail` (thumb, masked while the\nscore calculates) and in `WebsiteDataView`'s `RiskBand` (pointer)."
    }
  ],
  "usage": [],
  "examples": [],
  "source": "packages/design-system/src/components/visualizations/RiskMeter/RiskMeter.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": "Risk value from 0 to 100.",
      "source": {
        "path": "packages/design-system/src/components/visualizations/types.ts",
        "line": 219
      }
    },
    {
      "name": "hidden",
      "type": "boolean | undefined",
      "declared_type": "boolean",
      "required": false,
      "description": "Hides the visual value while preserving loading semantics.",
      "source": {
        "path": "packages/design-system/src/components/visualizations/types.ts",
        "line": 221
      },
      "values": [
        false,
        true
      ],
      "values_complete": true,
      "default": "false",
      "default_kind": "source-expression"
    },
    {
      "name": "marker",
      "type": "\"thumb\" | \"pointer\" | undefined",
      "declared_type": "'thumb' | 'pointer'",
      "required": false,
      "description": "How the value is marked on the track.\n- `thumb` (default): a circular handle with the track dimmed past the value.\n- `pointer`: the full gradient stays visible and a triangle points up at the\n  value — for \"you are here on the scale\" displays rather than progress.",
      "source": {
        "path": "packages/design-system/src/components/visualizations/types.ts",
        "line": 228
      },
      "values": [
        "pointer",
        "thumb"
      ],
      "values_complete": true,
      "default": "'thumb'",
      "default_kind": "source-expression"
    },
    {
      "name": "ariaLabel",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "Accessible label for meaningful risk values.",
      "source": {
        "path": "packages/design-system/src/components/visualizations/types.ts",
        "line": 230
      }
    },
    {
      "name": "testId",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "Optional test selector.",
      "source": {
        "path": "packages/design-system/src/components/visualizations/types.ts",
        "line": 232
      }
    }
  ],
  "prop_shapes": {},
  "api": {
    "method": "typescript-type-checker",
    "typescript_version": "5.9.3",
    "public_export": "RiskMeter",
    "public_path": "RiskMeter",
    "import_path": "@cloakedinc/design-system",
    "root_kind": "component",
    "entrypoints": [
      {
        "name": "RiskMeter",
        "signature": 1,
        "visibility": "public",
        "source": {
          "path": "packages/design-system/src/components/visualizations/RiskMeter/RiskMeter.tsx",
          "line": 12
        },
        "props_type": "RiskMeterProps",
        "props": [
          {
            "name": "value",
            "type": "number",
            "declared_type": "number",
            "required": true,
            "description": "Risk value from 0 to 100.",
            "source": {
              "path": "packages/design-system/src/components/visualizations/types.ts",
              "line": 219
            }
          },
          {
            "name": "hidden",
            "type": "boolean | undefined",
            "declared_type": "boolean",
            "required": false,
            "description": "Hides the visual value while preserving loading semantics.",
            "source": {
              "path": "packages/design-system/src/components/visualizations/types.ts",
              "line": 221
            },
            "values": [
              false,
              true
            ],
            "values_complete": true,
            "default": "false",
            "default_kind": "source-expression"
          },
          {
            "name": "marker",
            "type": "\"thumb\" | \"pointer\" | undefined",
            "declared_type": "'thumb' | 'pointer'",
            "required": false,
            "description": "How the value is marked on the track.\n- `thumb` (default): a circular handle with the track dimmed past the value.\n- `pointer`: the full gradient stays visible and a triangle points up at the\n  value — for \"you are here on the scale\" displays rather than progress.",
            "source": {
              "path": "packages/design-system/src/components/visualizations/types.ts",
              "line": 228
            },
            "values": [
              "pointer",
              "thumb"
            ],
            "values_complete": true,
            "default": "'thumb'",
            "default_kind": "source-expression"
          },
          {
            "name": "ariaLabel",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "Accessible label for meaningful risk values.",
            "source": {
              "path": "packages/design-system/src/components/visualizations/types.ts",
              "line": 230
            }
          },
          {
            "name": "testId",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "Optional test selector.",
            "source": {
              "path": "packages/design-system/src/components/visualizations/types.ts",
              "line": 232
            }
          }
        ],
        "branches": [],
        "constraints": [],
        "extraction_status": "extracted"
      }
    ],
    "type_sources": [
      {
        "path": "packages/design-system/src/components/visualizations/types.ts",
        "line": 217,
        "name": "RiskMeterProps",
        "code": "export interface RiskMeterProps {\n    /** Risk value from 0 to 100. */\n    value: number;\n    /** Hides the visual value while preserving loading semantics. */\n    hidden?: boolean;\n    /**\n     * How the value is marked on the track.\n     * - `thumb` (default): a circular handle with the track dimmed past the value.\n     * - `pointer`: the full gradient stays visible and a triangle points up at the\n     *   value — for \"you are here on the scale\" displays rather than progress.\n     */\n    marker?: 'thumb' | 'pointer';\n    /** Accessible label for meaningful risk values. */\n    ariaLabel?: string;\n    /** Optional test selector. */\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": "RiskMeter",
      "status": "preview",
      "version": "1.0.0",
      "summary": "A horizontal 0-100 track carrying a low-to-high risk gradient for a single severity value, marked with a thumb handle or a you-are-here pointer."
    },
    "parts": [
      {
        "id": "track",
        "label": "Track",
        "description": "The rounded 0-100 rail that carries the risk gradient and background.",
        "required": true
      },
      {
        "id": "gradient",
        "label": "Risk gradient",
        "description": "The low-to-high severity fill painted across the track."
      },
      {
        "id": "thumb",
        "label": "Thumb",
        "description": "The circular handle placed at the value in the default thumb marker."
      },
      {
        "id": "pointer",
        "label": "Pointer",
        "description": "The triangle that points up at the value when the pointer marker is used."
      }
    ],
    "allowedDesignChoices": {
      "variants": {
        "base": {
          "label": "Base",
          "description": "The value and marker change the reading without changing the component treatment."
        }
      },
      "sizes": {},
      "markers": {
        "thumb": {
          "label": "Thumb",
          "description": "A circular handle with the track dimmed past the value, for a progress-like reading."
        },
        "pointer": {
          "label": "Pointer",
          "description": "The full gradient stays lit and a triangle points at the value, for you-are-here."
        }
      }
    },
    "variants": [
      {
        "id": "base",
        "label": "Base",
        "description": "A single gradient track whose marker and value are set by props.",
        "platforms": [
          "ios",
          "android",
          "web"
        ]
      }
    ],
    "sizes": [],
    "measurements": [
      {
        "id": "track-height",
        "label": "Track height",
        "kind": "exact",
        "token": "--cds-size-12",
        "value": 12,
        "unit": "px",
        "appliesTo": [
          "track"
        ]
      },
      {
        "id": "thumb-size",
        "label": "Thumb diameter",
        "kind": "exact",
        "token": "--cds-size-20",
        "value": 20,
        "unit": "px",
        "appliesTo": [
          "thumb"
        ]
      },
      {
        "id": "track-radius",
        "label": "Track corner radius",
        "kind": "exact",
        "token": "--cds-radius-xs",
        "value": 8,
        "unit": "px",
        "appliesTo": [
          "track"
        ]
      },
      {
        "id": "pointer-half-width",
        "label": "Pointer triangle half-width",
        "kind": "exact",
        "token": "--cds-size-8",
        "value": 8,
        "unit": "px",
        "appliesTo": [
          "pointer"
        ],
        "notes": "Each triangle side border is one --cds-size-8, so the pointer is twice that wide and is clamped by its half-width so it never spills past the track ends at 0 or 100."
      }
    ],
    "layout": {
      "alignment": "The track stretches to the container width; the marker is positioned along it by value.",
      "flow": "A single-row track; the pointer marker adds a triangle in-flow beneath the track.",
      "notes": [
        "The thumb marker dims the track past the value; the pointer marker keeps the full gradient lit."
      ]
    },
    "typographyAndColor": {
      "typography": [
        {
          "label": "Adjacent caption",
          "description": "Surrounding score labels and captions use the body-small ramp; the meter draws no text itself.",
          "token": "--cds-type-body-small-size"
        }
      ],
      "colors": [
        {
          "label": "Track background",
          "description": "The unfilled track and the dimming overlay past the value.",
          "token": "--cds-graph-bg"
        },
        {
          "label": "Low risk",
          "description": "The good end of the severity gradient.",
          "token": "--cds-risk-good"
        },
        {
          "label": "Medium risk",
          "description": "The fair midpoint of the severity gradient.",
          "token": "--cds-risk-fair"
        },
        {
          "label": "High risk",
          "description": "The critical end of the severity gradient.",
          "token": "--cds-risk-critical"
        },
        {
          "label": "Thumb ring",
          "description": "The surface-colored ring around the thumb handle.",
          "token": "--cds-bg-surface"
        },
        {
          "label": "Thumb edge",
          "description": "The hairline that separates the thumb from the track.",
          "token": "--cds-divider"
        }
      ]
    },
    "states": [
      {
        "id": "value",
        "label": "Value shown",
        "description": "The marker sits at the clamped 0-100 value and exposes it to assistive technology."
      },
      {
        "id": "loading",
        "label": "Loading",
        "description": "With hidden set the value is masked and the meter reports aria-busy while a score calculates."
      },
      {
        "id": "decorative",
        "label": "Decorative",
        "description": "Without an accessible label the meter is presentational and exposes no progressbar role."
      }
    ],
    "behavior": [
      {
        "label": "Clamped value",
        "description": "Values outside 0-100 are clamped so the marker never leaves the track."
      },
      {
        "label": "Marker reading",
        "description": "Use thumb for progress-like severity and pointer for a you-are-here position on the scale."
      },
      {
        "label": "Masked loading",
        "description": "Set hidden to keep loading semantics while the value is still being computed."
      }
    ],
    "accessibility": [
      {
        "label": "Meaningful value",
        "description": "Pass an accessible label so the meter exposes a progressbar with min, max, and the current value."
      },
      {
        "label": "Decorative meter",
        "description": "Omit the label when a nearby number already states the score, leaving the meter presentational."
      },
      {
        "label": "Loading is announced",
        "description": "While hidden the meter reports busy and withholds the value rather than announcing a stale one."
      }
    ],
    "contentAdaptation": [
      {
        "label": "Severity only",
        "description": "Use RiskMeter when the value has severity meaning; use HalfGauge or Progress for neutral completion."
      },
      {
        "label": "Full-width rail",
        "description": "The track fills its container, so give it a bounded width in narrow rows."
      }
    ],
    "motionHaptics": {
      "motion": [
        {
          "label": "Value transition",
          "description": "The marker eases to a new value; honor reduced-motion by letting the platform shorten the ease."
        }
      ],
      "haptics": [
        {
          "label": "No feedback",
          "description": "The meter is a display and requests no 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-size-12",
      "light": "12px",
      "dark": "12px"
    },
    {
      "name": "--cds-size-20",
      "light": "20px",
      "dark": "20px"
    },
    {
      "name": "--cds-radius-xs",
      "light": "8px",
      "dark": "8px"
    },
    {
      "name": "--cds-size-8",
      "light": "8px",
      "dark": "8px"
    },
    {
      "name": "--cds-type-body-small-size",
      "light": "0.875rem",
      "dark": "0.875rem"
    },
    {
      "name": "--cds-graph-bg",
      "light": "#0b0b0a0d",
      "dark": "#ffffff0d"
    },
    {
      "name": "--cds-risk-good",
      "light": "#27ae60",
      "dark": "#27ae60"
    },
    {
      "name": "--cds-risk-fair",
      "light": "#f0923b",
      "dark": "#f0923b"
    },
    {
      "name": "--cds-risk-critical",
      "light": "#c90004",
      "dark": "#c90004"
    },
    {
      "name": "--cds-bg-surface",
      "light": "#ffffff",
      "dark": "#1b1b18"
    },
    {
      "name": "--cds-divider",
      "light": "#e0ddd6",
      "dark": "#ffffff1a"
    }
  ],
  "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

- [Default](/storybook/iframe.html?id=cloaked-design-system-visualizations-riskmeter--default&viewMode=story) | export: Default | source: packages/design-system/src/components/visualizations/RiskMeter/RiskMeter.stories.tsx

- [Pointer](/storybook/iframe.html?id=cloaked-design-system-visualizations-riskmeter--pointer&viewMode=story) | export: Pointer | source: packages/design-system/src/components/visualizations/RiskMeter/RiskMeter.stories.tsx

- [Empty](/storybook/iframe.html?id=cloaked-design-system-visualizations-riskmeter--empty&viewMode=story) | export: Empty | source: packages/design-system/src/components/visualizations/RiskMeter/RiskMeter.stories.tsx

- [Full](/storybook/iframe.html?id=cloaked-design-system-visualizations-riskmeter--full&viewMode=story) | export: Full | source: packages/design-system/src/components/visualizations/RiskMeter/RiskMeter.stories.tsx

- [Hidden Loading](/storybook/iframe.html?id=cloaked-design-system-visualizations-riskmeter--hidden-loading&viewMode=story) | export: HiddenLoading | source: packages/design-system/src/components/visualizations/RiskMeter/RiskMeter.stories.tsx

- [Dark Theme](/storybook/iframe.html?id=cloaked-design-system-visualizations-riskmeter--dark-theme&viewMode=story) | export: DarkTheme | source: packages/design-system/src/components/visualizations/RiskMeter/RiskMeter.stories.tsx

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