# LineChart

One or more smoothed trend lines over time, with tone-driven series colors and optional dimmed, dashed ghost baselines for projections or comparisons.

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

## Guidance

{
  "summary": "One or more smoothed trend lines over time, with tone-driven series colors and optional dimmed, dashed ghost baselines for projections or comparisons.",
  "guidance": [
    {
      "heading": "Overview",
      "body": "One or more smoothed trend lines rendered as a plain SVG — the shape of a metric over time."
    },
    {
      "heading": "When to use",
      "body": "Reach for LineChart when the data is a continuous trajectory and the _shape_ of the trend\nmatters more than exact per-bucket magnitudes — especially when overlaying several series to\ncompare their trajectories. Distinguish series with `tone` (the neutral `SERIES_TONES` for\nidentity, or the `RISK_TONES` when severity carries meaning) or an explicit `color`.\n\nPick `BarChart` instead when the reader must scrub discrete time buckets or read exact values;\n`CategoryBars` when the x-axis is a set of named categories rather than time; `HalfGauge` or\n`RiskMeter` for a single bounded score. When you want this line wrapped with a headline value\nand a stat delta in a Card, use `MetricLineChartCard` rather than composing it yourself.\n\nNot currently consumed by the app — the exposures trend view ships a bespoke D3-based line\nchart. This is the design-system primitive to migrate toward."
    },
    {
      "heading": "Comparison baseline",
      "body": "Pass `ghostSeries` for a projected or comparison line — it auto-dashes and dims behind the\nsolid `series`."
    }
  ],
  "usage": [],
  "examples": [],
  "source": "packages/design-system/src/components/visualizations/LineChart/LineChart.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": "series",
      "type": "DataVisualizationSeries[]",
      "declared_type": "DataVisualizationSeries[]",
      "required": true,
      "description": "Primary series rendered as chart lines.",
      "source": {
        "path": "packages/design-system/src/components/visualizations/types.ts",
        "line": 140
      }
    },
    {
      "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": 142
      }
    },
    {
      "name": "ariaLabel",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "Accessible label for meaningful charts.",
      "source": {
        "path": "packages/design-system/src/components/visualizations/types.ts",
        "line": 144
      }
    },
    {
      "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": 146
      }
    },
    {
      "name": "maxPoints",
      "type": "number | undefined",
      "declared_type": "number",
      "required": false,
      "description": "Maximum number of points included from each series.",
      "source": {
        "path": "packages/design-system/src/components/visualizations/types.ts",
        "line": 148
      }
    },
    {
      "name": "smoothingWindow",
      "type": "number | undefined",
      "declared_type": "number",
      "required": false,
      "description": "Moving-average window used to smooth series values.",
      "source": {
        "path": "packages/design-system/src/components/visualizations/types.ts",
        "line": 150
      }
    }
  ],
  "prop_shapes": {},
  "api": {
    "method": "typescript-type-checker",
    "typescript_version": "5.9.3",
    "public_export": "LineChart",
    "public_path": "LineChart",
    "import_path": "@cloakedinc/design-system",
    "root_kind": "component",
    "entrypoints": [
      {
        "name": "LineChart",
        "signature": 1,
        "visibility": "public",
        "source": {
          "path": "packages/design-system/src/components/visualizations/LineChart/LineChart.tsx",
          "line": 14
        },
        "props_type": "LineChartProps",
        "props": [
          {
            "name": "series",
            "type": "DataVisualizationSeries[]",
            "declared_type": "DataVisualizationSeries[]",
            "required": true,
            "description": "Primary series rendered as chart lines.",
            "source": {
              "path": "packages/design-system/src/components/visualizations/types.ts",
              "line": 140
            }
          },
          {
            "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": 142
            }
          },
          {
            "name": "ariaLabel",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "Accessible label for meaningful charts.",
            "source": {
              "path": "packages/design-system/src/components/visualizations/types.ts",
              "line": 144
            }
          },
          {
            "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": 146
            }
          },
          {
            "name": "maxPoints",
            "type": "number | undefined",
            "declared_type": "number",
            "required": false,
            "description": "Maximum number of points included from each series.",
            "source": {
              "path": "packages/design-system/src/components/visualizations/types.ts",
              "line": 148
            }
          },
          {
            "name": "smoothingWindow",
            "type": "number | undefined",
            "declared_type": "number",
            "required": false,
            "description": "Moving-average window used to smooth series values.",
            "source": {
              "path": "packages/design-system/src/components/visualizations/types.ts",
              "line": 150
            }
          }
        ],
        "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": 138,
        "name": "LineChartProps",
        "code": "export interface LineChartProps {\n    /** Primary series rendered as chart lines. */\n    series: DataVisualizationSeries[];\n    /** Optional ghosted comparison series. */\n    ghostSeries?: DataVisualizationSeries[];\n    /** Accessible label for meaningful charts. */\n    ariaLabel?: string;\n    /** Optional test selector. */\n    testId?: string;\n    /** Maximum number of points included from each series. */\n    maxPoints?: number;\n    /** Moving-average window used to smooth series values. */\n    smoothingWindow?: number;\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": "LineChart",
      "status": "preview",
      "version": "1.0.0",
      "summary": "One or more smoothed trend lines over time, with tone-driven series colors and optional dimmed, dashed ghost baselines for projections or comparisons."
    },
    "parts": [
      {
        "id": "plot",
        "label": "Plot",
        "description": "The SVG canvas that stretches the trend paths to fill its box.",
        "required": true
      },
      {
        "id": "series-line",
        "label": "Series line",
        "description": "A solid trend line colored by tone or explicit color."
      },
      {
        "id": "ghost-line",
        "label": "Ghost line",
        "description": "A dimmed, dashed comparison or projection line behind the series."
      }
    ],
    "allowedDesignChoices": {
      "variants": {
        "base": {
          "label": "Base",
          "description": "Series data and tone change the reading without changing the plot treatment."
        }
      },
      "sizes": {}
    },
    "variants": [
      {
        "id": "base",
        "label": "Base",
        "description": "A stretched SVG plot rendering one or more tone-colored trend lines.",
        "platforms": [
          "ios",
          "android",
          "web"
        ]
      }
    ],
    "sizes": [],
    "measurements": [
      {
        "id": "plot-height",
        "label": "Plot height",
        "kind": "exact",
        "token": "--cds-size-80",
        "value": 80,
        "unit": "px",
        "appliesTo": [
          "plot"
        ]
      },
      {
        "id": "dash-gap",
        "label": "Dashed line gap",
        "kind": "exact",
        "token": "--cds-size-4",
        "value": 4,
        "unit": "px",
        "appliesTo": [
          "ghost-line"
        ],
        "notes": "The dashed stroke pairs an --cds-size-8 dash with this --cds-size-4 gap."
      }
    ],
    "layout": {
      "alignment": "The plot fills the container width and its fixed height, stretching paths to the box.",
      "flow": "All series and ghost lines share one non-uniformly scaled SVG plot.",
      "notes": [
        "The plot uses a non-uniform aspect ratio, so lines scale to fill rather than preserve shape."
      ]
    },
    "typographyAndColor": {
      "typography": [
        {
          "label": "Adjacent caption",
          "description": "Surrounding axis or legend labels use the body-small ramp; the plot draws no text itself.",
          "token": "--cds-type-body-small-size"
        }
      ],
      "colors": [
        {
          "label": "Default line",
          "description": "A series with no tone or color falls back to primary text.",
          "token": "--cds-text-primary"
        },
        {
          "label": "Brand series",
          "description": "The brand series tone for neutral multi-line identity.",
          "token": "--cds-brand"
        },
        {
          "label": "Low-risk series",
          "description": "The good risk tone for severity-carrying series.",
          "token": "--cds-risk-good"
        },
        {
          "label": "High-risk series",
          "description": "The critical risk tone for severity-carrying series.",
          "token": "--cds-risk-critical"
        }
      ]
    },
    "states": [
      {
        "id": "single",
        "label": "Single series",
        "description": "One line renders the sparkline case."
      },
      {
        "id": "multi",
        "label": "Multiple series",
        "description": "Several tone-distinguished lines overlay in one plot."
      },
      {
        "id": "ghosted",
        "label": "Ghosted",
        "description": "A solid series sits over a dimmed, dashed ghost baseline."
      },
      {
        "id": "empty",
        "label": "Empty",
        "description": "No renderable series, so nothing is drawn and an upstream empty state should show."
      }
    ],
    "behavior": [
      {
        "label": "Two-point minimum",
        "description": "A series needs at least two points to form a line; single points are dropped."
      },
      {
        "label": "Tone or color",
        "description": "Distinguish series with a tone; set an explicit color for hues outside the tone system."
      },
      {
        "label": "Trim and smooth",
        "description": "maxPoints downsamples long inputs and smoothingWindow applies a moving average."
      }
    ],
    "accessibility": [
      {
        "label": "Meaningful chart",
        "description": "Pass an accessible label so the plot is announced as a meaningful image."
      },
      {
        "label": "Decorative chart",
        "description": "Omit the label to hide the plot from assistive technology when nearby text carries the trend."
      }
    ],
    "contentAdaptation": [
      {
        "label": "Trend over magnitude",
        "description": "Prefer LineChart when the shape of the trend matters more than discrete bar magnitudes."
      },
      {
        "label": "Ghost baselines",
        "description": "Use ghost series for a projected or comparison baseline behind the primary lines."
      }
    ],
    "motionHaptics": {
      "motion": [
        {
          "label": "No intrinsic motion",
          "description": "The plot does not animate on mount; a parent may transition the whole chart."
        }
      ],
      "haptics": [
        {
          "label": "No feedback",
          "description": "The chart 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-80",
      "light": "80px",
      "dark": "80px"
    },
    {
      "name": "--cds-size-4",
      "light": "4px",
      "dark": "4px"
    },
    {
      "name": "--cds-size-8",
      "light": "8px",
      "dark": "8px"
    },
    {
      "name": "--cds-type-body-small-size",
      "light": "0.875rem",
      "dark": "0.875rem"
    },
    {
      "name": "--cds-text-primary",
      "light": "#141410",
      "dark": "#f3f1ed"
    },
    {
      "name": "--cds-brand",
      "light": "#ff550c",
      "dark": "#ff550c"
    },
    {
      "name": "--cds-risk-good",
      "light": "#27ae60",
      "dark": "#27ae60"
    },
    {
      "name": "--cds-risk-critical",
      "light": "#c90004",
      "dark": "#c90004"
    }
  ],
  "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-linechart--default&viewMode=story) | export: Default | source: packages/design-system/src/components/visualizations/LineChart/LineChart.stories.tsx

- [Single Series](/storybook/iframe.html?id=cloaked-design-system-visualizations-linechart--single-series&viewMode=story) | export: SingleSeries | source: packages/design-system/src/components/visualizations/LineChart/LineChart.stories.tsx

- [Secondary Tone](/storybook/iframe.html?id=cloaked-design-system-visualizations-linechart--secondary-tone&viewMode=story) | export: SecondaryTone | source: packages/design-system/src/components/visualizations/LineChart/LineChart.stories.tsx

- [Ghost Series](/storybook/iframe.html?id=cloaked-design-system-visualizations-linechart--ghost-series&viewMode=story) | export: GhostSeries | source: packages/design-system/src/components/visualizations/LineChart/LineChart.stories.tsx

- [Tone Matrix](/storybook/iframe.html?id=cloaked-design-system-visualizations-linechart--tone-matrix&viewMode=story) | export: ToneMatrix | source: packages/design-system/src/components/visualizations/LineChart/LineChart.stories.tsx

- [Many Series](/storybook/iframe.html?id=cloaked-design-system-visualizations-linechart--many-series&viewMode=story) | export: ManySeries | source: packages/design-system/src/components/visualizations/LineChart/LineChart.stories.tsx

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

- [Single Point](/storybook/iframe.html?id=cloaked-design-system-visualizations-linechart--single-point&viewMode=story) | export: SinglePoint | source: packages/design-system/src/components/visualizations/LineChart/LineChart.stories.tsx

- [Smoothed And Trimmed](/storybook/iframe.html?id=cloaked-design-system-visualizations-linechart--smoothed-and-trimmed&viewMode=story) | export: SmoothedAndTrimmed | source: packages/design-system/src/components/visualizations/LineChart/LineChart.stories.tsx

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

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