# MetricLineChartCard A dashboard KPI tile that pairs a headline value and optional stat delta with an inline LineChart inside a Card, falling back to placeholder copy when no series can render. Version: 0.2.0-preview.1 (preview) Content digest: 70ac710f4d22dce040e7ac593379ba8aca9dcb59a0b9c0f839819cae0e2bb721 Contract kind: source-derived Source: packages/design-system/src/components/visualizations/MetricLineChartCard/MetricLineChartCard.tsx ## Guidance { "summary": "A dashboard KPI tile that pairs a headline value and optional stat delta with an inline LineChart inside a Card, falling back to placeholder copy when no series can render.", "guidance": [ { "heading": "Overview", "body": "A dashboard KPI tile: a `LineChart` packaged in a Card with a headline value, an optional stat\ndelta, title, and description." }, { "heading": "When to use", "body": "Use MetricLineChartCard as the standard metric card on a home or overview surface — it is the\npre-composed wrapper around `LineChart`, so drop to a bare `LineChart` when you only need the\nsparkline without the value chrome. `statTone` colors the delta green (`up`) or red (`down`).\n`series`, `ghostSeries`, tone, and smoothing behave exactly as in `LineChart`.\n\nWhen no `series` can render it shows `placeholder` copy instead of an empty chart, so always\nsupply one for the zero-data case.\n\nNot currently used in the app." }, { "heading": "Empty state", "body": "With no series, `placeholder` copy replaces the chart entirely." } ], "usage": [], "examples": [], "source": "packages/design-system/src/components/visualizations/MetricLineChartCard/MetricLineChartCard.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": "title", "type": "React.ReactNode", "declared_type": "React.ReactNode", "required": true, "description": "Card heading above the metric.", "source": { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 159 } }, { "name": "value", "type": "React.ReactNode", "declared_type": "React.ReactNode", "required": true, "description": "The headline metric itself, rendered at display size.", "source": { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 161 } }, { "name": "statLabel", "type": "React.ReactNode", "declared_type": "React.ReactNode", "required": false, "description": "Optional stat label beside the value.", "source": { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 163 } }, { "name": "statTone", "type": "\"up\" | \"down\" | undefined", "declared_type": "'up' | 'down'", "required": false, "description": "Directional treatment for the stat label.", "source": { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 165 }, "values": [ "down", "up" ], "values_complete": true, "default": "'up'", "default_kind": "source-expression" }, { "name": "description", "type": "React.ReactNode", "declared_type": "React.ReactNode", "required": false, "description": "Secondary copy under the metric; the line is omitted entirely when unset.", "source": { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 167 } }, { "name": "placeholder", "type": "React.ReactNode", "declared_type": "React.ReactNode", "required": false, "description": "Empty-state copy shown when no series can render.", "source": { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 169 } }, { "name": "series", "type": "DataVisualizationSeries[]", "declared_type": "DataVisualizationSeries[]", "required": true, "description": "Primary series rendered in the card chart.", "source": { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 171 } }, { "name": "ghostSeries", "type": "DataVisualizationSeries[] | undefined", "declared_type": "DataVisualizationSeries[]", "required": false, "description": "Optional ghosted comparison series.", "source": { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 173 } }, { "name": "ariaLabel", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Accessible label for the chart.", "source": { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 175 } }, { "name": "testId", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Optional test selector, applied to the card root.", "source": { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 177 } } ], "prop_shapes": {}, "api": { "method": "typescript-type-checker", "typescript_version": "5.9.3", "public_export": "MetricLineChartCard", "public_path": "MetricLineChartCard", "import_path": "@cloakedinc/design-system", "root_kind": "component", "entrypoints": [ { "name": "MetricLineChartCard", "signature": 1, "visibility": "public", "source": { "path": "packages/design-system/src/components/visualizations/MetricLineChartCard/MetricLineChartCard.tsx", "line": 12 }, "props_type": "MetricLineChartCardProps", "props": [ { "name": "title", "type": "React.ReactNode", "declared_type": "React.ReactNode", "required": true, "description": "Card heading above the metric.", "source": { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 159 } }, { "name": "value", "type": "React.ReactNode", "declared_type": "React.ReactNode", "required": true, "description": "The headline metric itself, rendered at display size.", "source": { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 161 } }, { "name": "statLabel", "type": "React.ReactNode", "declared_type": "React.ReactNode", "required": false, "description": "Optional stat label beside the value.", "source": { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 163 } }, { "name": "statTone", "type": "\"up\" | \"down\" | undefined", "declared_type": "'up' | 'down'", "required": false, "description": "Directional treatment for the stat label.", "source": { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 165 }, "values": [ "down", "up" ], "values_complete": true, "default": "'up'", "default_kind": "source-expression" }, { "name": "description", "type": "React.ReactNode", "declared_type": "React.ReactNode", "required": false, "description": "Secondary copy under the metric; the line is omitted entirely when unset.", "source": { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 167 } }, { "name": "placeholder", "type": "React.ReactNode", "declared_type": "React.ReactNode", "required": false, "description": "Empty-state copy shown when no series can render.", "source": { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 169 } }, { "name": "series", "type": "DataVisualizationSeries[]", "declared_type": "DataVisualizationSeries[]", "required": true, "description": "Primary series rendered in the card chart.", "source": { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 171 } }, { "name": "ghostSeries", "type": "DataVisualizationSeries[] | undefined", "declared_type": "DataVisualizationSeries[]", "required": false, "description": "Optional ghosted comparison series.", "source": { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 173 } }, { "name": "ariaLabel", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Accessible label for the chart.", "source": { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 175 } }, { "name": "testId", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Optional test selector, applied to the card root.", "source": { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 177 } } ], "branches": [], "constraints": [], "extraction_status": "extracted" } ], "type_sources": [ { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 10, "name": "DataVisualizationTone", "code": "export type DataVisualizationTone = SeriesTone | RiskTone;" }, { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 12, "name": "DataVisualizationSeries", "code": "export interface DataVisualizationSeries {\n id: string;\n values: number[];\n tone?: DataVisualizationTone;\n /**\n * Explicit stroke color (any CSS color). Overrides `tone` when set — use it for\n * product-specific palettes the design-system tones intentionally do not cover.\n */\n color?: string;\n dashed?: boolean;\n}" }, { "path": "packages/design-system/src/components/visualizations/types.ts", "line": 157, "name": "MetricLineChartCardProps", "code": "export interface MetricLineChartCardProps {\n /** Card heading above the metric. */\n title: React.ReactNode;\n /** The headline metric itself, rendered at display size. */\n value: React.ReactNode;\n /** Optional stat label beside the value. */\n statLabel?: React.ReactNode;\n /** Directional treatment for the stat label. */\n statTone?: 'up' | 'down';\n /** Secondary copy under the metric; the line is omitted entirely when unset. */\n description?: React.ReactNode;\n /** Empty-state copy shown when no series can render. */\n placeholder?: React.ReactNode;\n /** Primary series rendered in the card chart. */\n series: DataVisualizationSeries[];\n /** Optional ghosted comparison series. */\n ghostSeries?: DataVisualizationSeries[];\n /** Accessible label for the chart. */\n ariaLabel?: string;\n /** Optional test selector, applied to the card root. */\n testId?: string;\n}" }, { "path": "packages/design-system/src/styles/riskTone.ts", "line": 9, "name": "RISK_TONES", "code": "RISK_TONES = ['excellent', 'good', 'fair', 'high', 'critical'] as const" }, { "path": "packages/design-system/src/styles/riskTone.ts", "line": 11, "name": "RiskTone", "code": "export type RiskTone = (typeof RISK_TONES)[number];" }, { "path": "packages/design-system/src/styles/seriesTone.ts", "line": 8, "name": "SERIES_TONES", "code": "SERIES_TONES = ['brand', 'primary', 'secondary'] as const" }, { "path": "packages/design-system/src/styles/seriesTone.ts", "line": 10, "name": "SeriesTone", "code": "export type SeriesTone = (typeof SERIES_TONES)[number];" } ], "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": "MetricLineChartCard", "status": "preview", "version": "1.0.0", "summary": "A dashboard KPI tile that pairs a headline value and optional stat delta with an inline LineChart inside a Card, falling back to placeholder copy when no series can render." }, "parts": [ { "id": "card", "label": "Card", "description": "The surface shell that frames the metric and chart.", "required": true }, { "id": "value", "label": "Value", "description": "The headline metric rendered in the display ramp." }, { "id": "stat", "label": "Stat delta", "description": "The optional trend tag shown beside the value." }, { "id": "chart", "label": "Chart", "description": "The inline LineChart, or placeholder copy when no series can render." } ], "allowedDesignChoices": { "variants": { "base": { "label": "Base", "description": "Content and the stat direction change the reading without changing the tile treatment." } }, "sizes": {}, "statTones": { "up": { "label": "Up", "description": "The delta reads as a positive movement (green)." }, "down": { "label": "Down", "description": "The delta reads as a negative movement (red)." } } }, "variants": [ { "id": "base", "label": "Base", "description": "A Card with a headline value, optional delta, and an inline chart.", "platforms": [ "ios", "android", "web" ] } ], "sizes": [], "measurements": [ { "id": "metric-row-gap", "label": "Value-to-stat gap", "kind": "exact", "token": "--cds-space-12", "value": 12, "unit": "px", "appliesTo": [ "value", "stat" ] }, { "id": "card-radius", "label": "Card corner radius", "kind": "exact", "token": "--cds-radius-lg", "value": 20, "unit": "px", "appliesTo": [ "card" ], "notes": "Inherited from the default Card radius; MetricLineChartCard does not override it." }, { "id": "card-padding", "label": "Card slot padding", "kind": "example-only", "token": "--cds-space-16", "value": 16, "unit": "px", "appliesTo": [ "card", "chart" ], "notes": "The header and text slots carry the default Card padding; the chart body uses padding none so the LineChart spans edge to edge." } ], "layout": { "alignment": "Header content is left-aligned in a column; the value and delta share a centered row.", "flow": "Header (title, value row, description) stacks above the chart body.", "notes": [ "The chart body drops its padding so the LineChart reaches the card edges." ] }, "typographyAndColor": { "typography": [ { "label": "Headline value", "description": "The metric value uses the display-2 ramp.", "token": "--cds-type-display-2-size" }, { "label": "Supporting copy", "description": "The optional description uses the body ramp.", "token": "--cds-type-body-size" } ], "colors": [ { "label": "Value", "description": "The headline value uses primary text.", "token": "--cds-text-primary" }, { "label": "Description", "description": "Supporting copy uses secondary text.", "token": "--cds-text-secondary" }, { "label": "Card surface", "description": "The tile sits on the card surface.", "token": "--cds-bg-surface" } ] }, "states": [ { "id": "populated", "label": "Populated", "description": "At least one series with two or more points renders the inline chart." }, { "id": "empty", "label": "Empty", "description": "No renderable series but a ghost projection still draws the will-grow chart." }, { "id": "placeholder", "label": "Placeholder", "description": "No series and no ghost, so placeholder copy replaces the chart entirely." } ], "behavior": [ { "label": "Placeholder fallback", "description": "When no series can render, show placeholder copy instead of an empty chart, so always supply one." }, { "label": "Delegated chart", "description": "Series, ghost series, tone, and smoothing behave exactly as in LineChart." }, { "label": "Stat direction", "description": "statTone colors the delta up (positive) or down (negative)." } ], "accessibility": [ { "label": "Chart label", "description": "Pass an accessible label so the inline chart is announced as a meaningful image." }, { "label": "Readable delta", "description": "State direction in the stat text, not color alone, so the trend reads without hue." } ], "contentAdaptation": [ { "label": "When to wrap", "description": "Use this tile when a metric needs value chrome; drop to a bare LineChart for a plain sparkline." }, { "label": "Zero-data copy", "description": "Provide placeholder copy for the zero-data case so the tile never shows an empty plot." } ], "motionHaptics": { "motion": [ { "label": "Inline chart motion", "description": "Motion comes from the inline LineChart; the card itself does not animate on mount." } ], "haptics": [ { "label": "No feedback", "description": "The tile 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-space-12", "light": "12px", "dark": "12px" }, { "name": "--cds-radius-lg", "light": "20px", "dark": "20px" }, { "name": "--cds-space-16", "light": "16px", "dark": "16px" }, { "name": "--cds-type-display-2-size", "light": "3rem", "dark": "3rem" }, { "name": "--cds-type-body-size", "light": "1rem", "dark": "1rem" }, { "name": "--cds-text-primary", "light": "#141410", "dark": "#f3f1ed" }, { "name": "--cds-text-secondary", "light": "#646260", "dark": "#ffffff99" }, { "name": "--cds-bg-surface", "light": "#ffffff", "dark": "#1b1b18" } ], "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-metriclinechartcard--default&viewMode=story) | export: Default | source: packages/design-system/src/components/visualizations/MetricLineChartCard/MetricLineChartCard.stories.tsx - [Empty](/storybook/iframe.html?id=cloaked-design-system-visualizations-metriclinechartcard--empty&viewMode=story) | export: Empty | source: packages/design-system/src/components/visualizations/MetricLineChartCard/MetricLineChartCard.stories.tsx - [Placeholder Only](/storybook/iframe.html?id=cloaked-design-system-visualizations-metriclinechartcard--placeholder-only&viewMode=story) | export: PlaceholderOnly | source: packages/design-system/src/components/visualizations/MetricLineChartCard/MetricLineChartCard.stories.tsx - [Single Series](/storybook/iframe.html?id=cloaked-design-system-visualizations-metriclinechartcard--single-series&viewMode=story) | export: SingleSeries | source: packages/design-system/src/components/visualizations/MetricLineChartCard/MetricLineChartCard.stories.tsx - [Many Series](/storybook/iframe.html?id=cloaked-design-system-visualizations-metriclinechartcard--many-series&viewMode=story) | export: ManySeries | source: packages/design-system/src/components/visualizations/MetricLineChartCard/MetricLineChartCard.stories.tsx - [Dark Theme](/storybook/iframe.html?id=cloaked-design-system-visualizations-metriclinechartcard--dark-theme&viewMode=story) | export: DarkTheme | source: packages/design-system/src/components/visualizations/MetricLineChartCard/MetricLineChartCard.stories.tsx Preview pending human sign-off. Source-derived APIs and successful checks do not certify accessibility, native parity or approval.