@astryxdesign/charts 0.6.2-canary.bfee8a4 → 0.6.2-canary.da998a2

package/dist/ChartAxis.d.ts

@@ -7,7 +7,7 @@ export interface ChartAxisProps {
     maxTicks?: number;
     /** Custom tick formatter */
     tickFormat?: (value: unknown) => string;
-    /** Truncate labels to this many characters (appends "\u2026"). */
+    /** Truncate labels to this many user-perceived characters (appends "\u2026"). */
     truncate?: number;
     /** Enable smooth transitions for streaming (default: true) */
     animated?: boolean;

package/dist/ChartAxis.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ChartAxis.d.ts","sourceRoot":"","sources":["../src/ChartAxis.tsx"],"names":[],"mappings":"AA0BA,MAAM,WAAW,cAAc;IAC7B,uCAAuC;IACvC,QAAQ,EAAE,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC9C,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sFAAsF;IACtF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4BAA4B;IAC5B,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,CAAC;IACxC,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAeD;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,EACxB,QAAQ,EACR,SAAa,EACb,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,QAAe,EACf,YAAoC,EACpC,SAAiB,GAClB,EAAE,cAAc,+BAuLhB"}
+{"version":3,"file":"ChartAxis.d.ts","sourceRoot":"","sources":["../src/ChartAxis.tsx"],"names":[],"mappings":"AA4BA,MAAM,WAAW,cAAc;IAC7B,uCAAuC;IACvC,QAAQ,EAAE,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC9C,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sFAAsF;IACtF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4BAA4B;IAC5B,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,CAAC;IACxC,iFAAiF;IACjF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAeD;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,EACxB,QAAQ,EACR,SAAa,EACb,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,QAAe,EACf,YAAoC,EACpC,SAAiB,GAClB,EAAE,cAAc,+BA4LhB"}

package/dist/ChartAxis.js

@@ -2,6 +2,7 @@
 
 /**
  * @file ChartAxis.tsx (v2)
+ * @input Chart context scales, axis presentation props, and grapheme-safe text utilities
  * @output Renders an axis (top, right, bottom, left) using the chart's scales
  * @position Child of Chart v2; reads scales from chart context
  *
@@ -19,6 +20,7 @@
 
 import { useCallback, useMemo } from 'react';
 import * as stylex from '@stylexjs/stylex';
+import { characterCount, truncateCharacters } from '@astryxdesign/core/utils';
 import '@astryxdesign/core/theme/tokens.stylex';
 import { colorVars } from '@astryxdesign/core/theme/tokens.stylex';
 import { useChart } from "./ChartContext.js";
@@ -85,20 +87,28 @@ export function ChartAxis({
   }, [tickFormat, scale, safeTickCount]);
   const format = useCallback(value => {
     const str = (tickFormat ?? autoFormat ?? String)(value);
-    return truncate && str.length > truncate ? str.slice(0, truncate) + '\u2026' : str;
+    if (!truncate) {
+      return str;
+    }
+    const shortened = truncateCharacters(str, truncate, '');
+    return shortened === str ? str : shortened + '\u2026';
   }, [tickFormat, autoFormat, truncate]);
   const ticks = useMemo(() => {
+    // Format each generated tick once so density and rendering share the same
+    // grapheme-safe label instead of repeating consumer formatting/segmentation.
     let allTicks;
     if (isBandScale(scale)) {
       allTicks = scale.domain().map(d => ({
         value: d,
-        offset: (scale(d) ?? 0) + scale.bandwidth() / 2
+        offset: (scale(d) ?? 0) + scale.bandwidth() / 2,
+        label: format(d)
       }));
     } else {
       const linearScale = scale;
       allTicks = linearScale.ticks(safeTickCount).map(d => ({
         value: d,
-        offset: linearScale(d)
+        offset: linearScale(d),
+        label: format(d)
       }));
     }
 
@@ -111,7 +121,7 @@ export function ChartAxis({
     let cap = maxTicks;
     if (cap == null && allTicks.length > 1) {
       if (isHorizontal && width > 0) {
-        const widestChars = allTicks.reduce((m, t) => Math.max(m, format(t.value).length), 1);
+        const widestChars = allTicks.reduce((m, tick) => Math.max(m, characterCount(tick.label)), 1);
         const approxLabelPx = widestChars * 7 + 16;
         cap = Math.max(1, Math.floor(width / approxLabelPx));
       } else if (!isHorizontal && height > 0) {
@@ -157,9 +167,9 @@ export function ChartAxis({
       }
     }), ticks.map(({
       value,
-      offset
+      offset,
+      label
     }) => {
-      const label = format(value);
       // Key off the raw tick value, not the formatted label: distinct ticks
       // can format (or truncate) to the same string and would collide as keys.
       const key = String(value);

package/dist/ChartGrid.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ChartGrid.d.ts","sourceRoot":"","sources":["../src/ChartGrid.tsx"],"names":[],"mappings":"AAeA,MAAM,WAAW,cAAc;IAC7B,mDAAmD;IACnD,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AASD;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,EACxB,UAAiB,EACjB,QAAgB,EAChB,SAAa,GACd,EAAE,cAAc,+BAmEhB"}
+{"version":3,"file":"ChartGrid.d.ts","sourceRoot":"","sources":["../src/ChartGrid.tsx"],"names":[],"mappings":"AAgBA,MAAM,WAAW,cAAc;IAC7B,mDAAmD;IACnD,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AASD;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,EACxB,UAAiB,EACjB,QAAgB,EAChB,SAAa,GACd,EAAE,cAAc,+BAmEhB"}

package/dist/ChartGrid.js

@@ -2,6 +2,7 @@
 
 /**
  * @file ChartGrid.tsx (v2)
+ * @input Chart context scales and dimensions, guide visibility, and tick density
  * @output Grid lines behind chart marks
  * @position Child of Chart v2; reads scales from chart context
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/charts",
-  "version": "0.6.2-canary.bfee8a4",
+  "version": "0.6.2-canary.da998a2",
   "description": "Astryx charts — a config-model data visualization library (d3-based). Published to npm only under the @canary dist-tag for early testing; never released as a stable (latest) version.",
   "author": "Meta Open Source",
   "license": "MIT",
@@ -47,7 +47,7 @@
   },
   "peerDependencies": {
     "@stylexjs/stylex": ">=0.10.0",
-    "@astryxdesign/core": "0.6.2-canary.bfee8a4",
+    "@astryxdesign/core": "0.6.2-canary.da998a2",
     "react": ">=19.0.0",
     "react-dom": ">=19.0.0"
   },
@@ -57,7 +57,7 @@
     "d3-shape": "^3.2.0"
   },
   "devDependencies": {
-    "@astryxdesign/cli": "0.6.2-canary.bfee8a4",
+    "@astryxdesign/cli": "0.6.2-canary.da998a2",
     "@babel/cli": "^7.29.7",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^7.29.7",

package/src/ChartAxis.doc.mjs

@@ -0,0 +1,162 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
+
+export const docs = {
+  name: 'ChartAxis',
+  displayName: 'Chart Axis',
+  group: 'Charts',
+  category: 'Data Visualization',
+  isHiddenFromOverview: true,
+  keywords: ['chart', 'axis', 'ticks', 'labels', 'scale', 'data visualization'],
+
+  usage: {
+    description:
+      'ChartAxis renders tick labels and optional edge and tick lines from the scales owned by a parent Chart. Use it in the Chart axes slot for physical top, right, bottom, or left plot edges.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Use ChartAxis inside Chart so its labels, ticks, and edge line share the same scales and plot dimensions as the marks.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use tickFormat for product-specific units or locale formatting, and maxTicks or truncate when dense category labels need a bounded presentation.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use axis labels or a pointer tooltip as the only way to obtain important values. Give Chart an accessible name and preserve an equivalent data view or summary.',
+      },
+      {
+        guidance: false,
+        description:
+          'Hide the edge line while showing tick marks. showTicks intentionally keeps the line visible so each mark has a grounded edge.',
+      },
+    ],
+    accessibility: [
+      {
+        name: 'Chart alternative',
+        category: 'Content',
+        criterion: '1.1.1 Non-text Content',
+        requirement: 'Required on the parent Chart',
+        states: ['All'],
+        description:
+          'Chart owns the accessible image name and supported small-data table. Tick labels supplement that chart-level alternative rather than replacing it.',
+      },
+      {
+        name: 'Label text integrity',
+        category: 'Content',
+        criterion: 'Unicode grapheme clusters',
+        requirement: 'Required when truncate is set',
+        states: ['Truncated labels'],
+        description:
+          'Truncation keeps emoji, joined emoji sequences, flags, and combining marks intact before appending the ellipsis.',
+      },
+    ],
+    anatomy: [
+      {
+        name: 'Axis edge line',
+        required: false,
+        description:
+          'Line along the selected plot edge. It is shown by default only on the bottom edge and whenever tick marks are shown.',
+      },
+      {
+        name: 'Tick marks',
+        required: false,
+        description:
+          'Short lines extending outward from each retained tick position.',
+      },
+      {
+        name: 'Tick labels',
+        required: true,
+        description:
+          'Formatted scale values or categories positioned outside the selected plot edge.',
+      },
+    ],
+  },
+
+  props: [
+    {
+      name: 'position',
+      type: "'top' | 'right' | 'bottom' | 'left'",
+      description: 'Physical plot edge on which to render the axis.',
+      required: true,
+    },
+    {
+      name: 'tickCount',
+      type: 'number',
+      description:
+        'Approximate continuous-scale tick count. d3 chooses the final values.',
+      default: '5',
+    },
+    {
+      name: 'maxTicks',
+      type: 'number',
+      description:
+        'Maximum displayed label count. Labels are evenly skipped when the generated set is larger.',
+    },
+    {
+      name: 'tickFormat',
+      type: '(value: unknown) => string',
+      description:
+        'Formats each retained tick. When omitted, continuous scales use d3 formatting and band scales use their category strings.',
+    },
+    {
+      name: 'truncate',
+      type: 'number',
+      description:
+        'Maximum content characters retained before an ellipsis is appended. User-perceived characters remain intact.',
+    },
+    {
+      name: 'animated',
+      type: 'boolean',
+      description:
+        'Whether tick position and visibility changes use the built-in transition.',
+      default: 'true',
+    },
+    {
+      name: 'showAxisLine',
+      type: 'boolean',
+      description:
+        'Whether to draw the edge line. Tick marks force the line on so they remain grounded.',
+      default: 'true for bottom; false for top, right, and left',
+    },
+    {
+      name: 'showTicks',
+      type: 'boolean',
+      description: 'Whether to draw an outward mark at each retained tick.',
+      default: 'false',
+    },
+  ],
+
+  examples: [
+    {
+      label: 'Bottom and left axes',
+      code: `import {Chart, ChartAxis, ChartGrid, bar} from '@astryxdesign/charts';
+
+<Chart
+  data={monthlyRevenue}
+  xKey="month"
+  series={[bar('revenue')]}
+  grid={<ChartGrid horizontal />}
+  axes={
+    <>
+      <ChartAxis position="bottom" />
+      <ChartAxis position="left" tickFormat={value => String(value)} />
+    </>
+  }
+/>;`,
+    },
+    {
+      label: 'Dense category labels',
+      code: `<ChartAxis
+  position="bottom"
+  maxTicks={8}
+  truncate={12}
+  showTicks
+/>;`,
+    },
+  ],
+};

package/src/ChartAxis.spec.md

@@ -0,0 +1,211 @@
+---
+schema_version: 3
+template_version: 5
+kind: component
+id: component:ChartAxis
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [public-api, behavior, layout, theming, accessibility]
+verified_by:
+  [
+    packages/charts/src/ChartAxis.test.tsx,
+    apps/storybook/stories/charts/ChartAxis.stories.tsx,
+  ]
+modules: []
+families: []
+design_specs: []
+architecture:
+  [
+    architecture:component-test-sufficiency,
+    architecture:component-theming-surface,
+  ]
+contributing: []
+system_specs: [spec:AST-002, spec:AST-029]
+---
+
+# ChartAxis component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                  |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | No API shape or default changes. Truncation and automatic horizontal density now count complete grapheme clusters under the objective Unicode text-segmentation standard. |
+| Behavior                | The selected physical plot edge determines scale, placement, label direction, and the default edge line; explicit formatting and density inputs refine labels.            |
+| End-user impact         | Chart readers keep complete tick-label characters, and equally short Unicode labels are no longer thinned more aggressively than ASCII labels.                            |
+| Builder impact          | None. Existing callsites remain valid and receive direct CLI documentation for the current surface.                                                                       |
+| Compatibility/readiness | The canary API and defaults are preserved. This record is draft observational evidence; rendered and accessibility-tree evidence remains incomplete.                      |
+| Review checks           | Reject a changed public shape/default, an axis using the wrong Chart scale, broken physical-edge placement, split grapheme labels, or hidden line/tick precedence.        |
+| Governing rules         | `spec:AST-029/FR3–FR7`, `architecture:component-test-sufficiency/INV1–INV9`, and [Unicode Text Segmentation](https://www.unicode.org/reports/tr29/).                      |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+ChartAxis renders labelled Cartesian x or y scale output inside a Chart. It owns
+physical-edge placement, tick selection and formatting, optional tick marks, and the
+optional axis edge line while Chart owns the scale domains and plot geometry.
+
+## Compatibility and migration
+
+- Released default preserved: yes; the package is canary-only and has no stable release.
+- Compatibility class: no public API or default changes; Unicode truncation and automatic thinning intentionally change only labels containing multi-code-unit graphemes, while representative ASCII behavior is preserved.
+- Controlled/uncontrolled behavior: not applicable.
+- Migration decision: none; this draft does not authorize a public API change.
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- Selecting the Chart-provided x or y scale for one physical plot edge.
+- Generating, formatting, thinning, truncating, positioning, and hiding tick labels.
+- Rendering its optional edge line and optional outward tick marks.
+- Applying optional transition styling to tick position and visibility changes.
+
+**Does not own / non-goals**
+
+- Data, domains, scale construction, or plot dimensions — owned by `component:Chart`.
+- Grid lines — owned by `component:ChartGrid`.
+- Product-specific units, locale choices, or label wording supplied through `tickFormat` — owned by the product callsite.
+- A standalone chart data alternative — owned by `component:Chart` and its surrounding product content.
+
+## Public concepts
+
+| Concept          | Closed values or states                | Meaning                                                               | Availability by variant/orientation/state                   | Default                              | Owner                 | Stability    | Invalid-value behavior                                                          |
+| ---------------- | -------------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------ | --------------------- | ------------ | ------------------------------------------------------------------------------- |
+| Physical edge    | `top`, `right`, `bottom`, `left`       | Chooses the plot edge, scale axis, transform, and outward label side. | Required for every axis.                                    | none                                 | `component:ChartAxis` | experimental | Unknown values are rejected by TypeScript.                                      |
+| Tick target      | finite number                          | Requests an approximate continuous-scale tick count from d3.          | Continuous scales; also configures the automatic formatter. | `5`                                  | `component:ChartAxis` | experimental | Negative/non-finite values fall back to 5; fractions floor; values cap at 1000. |
+| Label cap        | number or absent                       | Evenly skips labels when the generated set exceeds the requested cap. | Every scale.                                                | automatic from available space       | `component:ChartAxis` | experimental | Values outside the intended positive-count domain are not specified.            |
+| Label formatter  | `(value: unknown) => string` or absent | Replaces the band string or d3 continuous-scale formatter.            | Every tick.                                                 | scale-appropriate built-in formatter | `component:ChartAxis` | experimental | Exceptions from consumer formatters propagate.                                  |
+| Label truncation | positive character count or absent     | Keeps that many user-perceived characters, then appends an ellipsis.  | Every formatted label.                                      | absent                               | `component:ChartAxis` | experimental | Zero/omitted disables truncation; other invalid values are not specified.       |
+| Edge line        | shown or hidden                        | Renders a line along the selected axis edge.                          | Every edge; tick marks force it on.                         | shown only for `bottom`              | `component:ChartAxis` | experimental | Not applicable.                                                                 |
+| Tick marks       | shown or hidden                        | Renders an outward perpendicular mark beside each visible tick label. | Every edge.                                                 | hidden                               | `component:ChartAxis` | experimental | Not applicable.                                                                 |
+| Tick transition  | animated or immediate                  | Animates tick transform and opacity during scale changes.             | Generated ticks.                                            | animated                             | `component:ChartAxis` | experimental | Not applicable.                                                                 |
+
+## Behavioral and layout contract
+
+Draft requirements identify their basis so observed code is not mistaken for an
+intentional decision.
+
+| ID   | Candidate invariant                                                                                                                                                         | Basis                                                          | Draft review state |
+| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ------------------ |
+| FR1  | A top or bottom axis MUST consume Chart's x scale; a left or right axis MUST consume the categorical y scale when present and the linear y scale otherwise.                 | implementation, types, and focused tests                       | verify             |
+| FR2  | Continuous tick generation MUST use one sanitized count for both d3 tick generation and its default formatter; band scales MUST use their complete domain before thinning.  | implementation                                                 | verify             |
+| FR3  | A supplied `tickFormat` MUST win; otherwise continuous scales use d3 formatting and band values use `String`.                                                               | implementation and focused tests                               | verify             |
+| FR4  | Explicit `maxTicks` MUST win over the size-derived cap.                                                                                                                     | implementation and focused tests                               | verify             |
+| FR5  | Truncation MUST keep complete Unicode grapheme clusters while preserving the documented content-count-plus-ellipsis output.                                                 | focused red/green test and Unicode Standard Annex #29          | settled            |
+| FR6  | Automatic horizontal density MUST estimate formatted label length in user-perceived characters rather than UTF-16 storage units.                                            | focused red/green equivalence test and Unicode segmentation    | settled            |
+| FR7  | Bottom MUST show an edge line by default and the other edges MUST hide it by default. `showTicks` MUST force the edge line on and render one mark per surviving tick.       | implementation, JSDoc, focused tests, and Storybook            | verify             |
+| FR8  | Bottom and right axes MUST translate to the corresponding plot edge. Top and left remain at the plot origin. Labels and tick marks extend outwards from that physical edge. | implementation and focused tests                               | verify             |
+| FR9  | On a mixed-sign linear y domain, the bottom edge line MUST align with y=0; categorical y leaves it on the plot edge.                                                        | implementation                                                 | verify             |
+| FR10 | Tick movement and visibility MAY transition when `animated` is true and MUST be immediate when false. Out-of-range ticks remain mounted with zero opacity during updates.   | implementation and streaming examples; motion intent unsettled | human decision     |
+
+### Allowed variation
+
+- **AV1 — Tick count.** d3 may choose a nearby continuous tick count rather than the requested number.
+- **AV2 — Label set.** Automatic and explicit density limits may omit evenly spaced labels while preserving their scale order.
+- **AV3 — Supplied text.** Product callsites may format values in their own units and locale through `tickFormat`.
+
+### Representative states
+
+| State                       | Required invariant                                                  | Allowed variation                                     |
+| --------------------------- | ------------------------------------------------------------------- | ----------------------------------------------------- |
+| Bottom categorical          | Band labels are centered; the edge line is shown by default.        | Automatic density may omit labels.                    |
+| Top categorical             | Band labels render outside the top edge.                            | Edge line remains hidden unless requested.            |
+| Left continuous             | d3 labels render outside the left edge.                             | d3 chooses exact tick values.                         |
+| Right continuous            | Axis translates to the right edge and labels render outside it.     | d3 chooses exact tick values.                         |
+| Vertical categorical        | Row labels use `yBandScale` and align with band centers.            | Automatic density may omit labels.                    |
+| Explicit formatting         | Every retained label uses the supplied formatter.                   | Consumer-owned wording and units.                     |
+| Truncated label             | Complete grapheme clusters precede the appended ellipsis.           | The caller chooses the content-character limit.       |
+| Tick marks shown            | Every retained label has an outward mark and an edge line.          | Edge-line visibility input is subsumed in this state. |
+| Mixed-sign linear y data    | Bottom line represents y=0 rather than the plot boundary.           | Exact pixel position follows the supplied domain.     |
+| Streaming / changing domain | Tick positions and visibility update; animation follows `animated`. | Tick identity follows the raw value.                  |
+
+### Transformation and precedence order
+
+- **ORD1 — Scale.** Resolve physical orientation → choose Chart scale → generate and format each tick once → derive the grapheme-aware density cap → evenly filter labels.
+- **ORD2 — Label.** Apply the supplied formatter or the scale default → preserve complete grapheme clusters when truncating → render the result.
+- **ORD3 — Edge.** Resolve the position default → apply `showAxisLine` → force the line on when `showTicks` is true.
+
+### Performance and resources
+
+- **PR1 — Bounded continuous ticks.** Sanitization caps the d3 request at 1000 so a consumer value cannot allocate an unbounded tick array.
+- **PR2 — Derived tick state.** Tick generation and formatting remain render-derived and memoized; each generated label is formatted once and shared by density and rendering, and ChartAxis owns no listener, observer, timer, or persistent resource.
+
+## Accessibility contract
+
+- **AR1 — Visible text integrity.** A truncated tick label MUST preserve complete user-perceived characters under Unicode grapheme-cluster boundaries.
+- **AR2 — Chart-level alternative.** ChartAxis renders inside Chart's named image. Chart owns the accessible chart name and supported small-data table; axis labels and pointer content do not replace that alternative.
+- **AR3 — Nested axis semantics gap.** The implementation currently emits a position-labelled `role="group"`. Whether that group should be independently exposed and localized beneath Chart's `role="img"` remains unverified and requires owner review.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                     | Representation authority                          | Hierarchy role | Component contract |
+| ---------------- | ------------------------------------------------------ | ------------------------------------------------- | -------------- | ------------------ |
+| Axis edge line   | Grounds the physical plot edge when present.           | unsettled; no current design record is linked     | supporting     | FR7, FR9           |
+| Tick marks       | Associate retained labels with positions on the scale. | unsettled; no current design record is linked     | supporting     | FR7                |
+| Tick labels      | Preserve readable value/category text around the plot. | Unicode grapheme boundaries settle text integrity | supporting     | FR3, FR5, FR6, AR1 |
+| Tick transition  | Shows continuity during scale changes.                 | unsettled; `design:motion` remains draft          | supporting     | FR10               |
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Axis edge line": {
+    "none": {
+      "reason": "unsettled: ChartAxis consumes semantic color tokens but no current component or family contract decides whether the line is a public theme target."
+    }
+  },
+  "Tick marks": {
+    "none": {
+      "reason": "unsettled: ChartAxis consumes semantic color tokens but no current component or family contract decides whether tick marks are a public theme target."
+    }
+  },
+  "Tick labels": {
+    "none": {
+      "reason": "unsettled: ChartAxis consumes semantic color tokens but no current component or family contract decides whether labels are a public theme target."
+    }
+  }
+}
+```
+
+## Family and system relationships
+
+- No current family or design record governs ChartAxis.
+- `architecture:component-test-sufficiency` owns rational public-state partitions, observable assertions, and red-before-green audit remediation.
+- `architecture:component-theming-surface` owns anatomy-to-target disposition; token consumption alone does not enroll ChartAxis in public component theming.
+- `spec:AST-002` owns public API admission and forbids an audit from smuggling a new public choice into a repair.
+- `spec:AST-029` owns this observational backfill, closed evidence receipt, safe remediation, and fail-closed eligibility report.
+
+## Verification map
+
+| Contract      | Verification                                                        | Representative states                                           | Mutation or failure expectation                                                           | Audit section                     |
+| ------------- | ------------------------------------------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | --------------------------------- |
+| FR1, FR8      | `ChartAxis.test.tsx`; `ChartAxis.stories.tsx`                       | top, right, bottom, left; band and linear                       | An edge uses the wrong scale, transform, or outward label side.                           | `audit:ChartAxis/behavior-layout` |
+| FR2, FR3      | `ChartAxis.test.tsx`                                                | default count; band, linear, and custom formatting              | Generation and formatting disagree or a supplied formatter is ignored.                    | `audit:ChartAxis/behavior`        |
+| FR4           | `ChartAxis.test.tsx`                                                | automatic cap and explicit `maxTicks`                           | Explicit capping stops winning over size-derived thinning.                                | `audit:ChartAxis/behavior`        |
+| FR5, FR6, AR1 | red-before-green grapheme regressions; density tests; browser story | ASCII, emoji, flag, and ZWJ labels; truncated wide/narrow plots | A visible label splits a grapheme or equal perceived-width labels retain different ticks. | `audit:ChartAxis/i18n-testing`    |
+| FR7           | `ChartAxis.test.tsx`; Axes & Grids Storybook fixture                | defaults; line requested; ticks requested                       | Tick marks lose their edge line or line defaults change.                                  | `audit:ChartAxis/behavior`        |
+| FR9           | source review; browser evidence remains pending                     | positive-only, negative-only, mixed-sign, y-band                | The mixed-sign zero line moves to the edge or a categorical axis crosses the plot.        | `audit:ChartAxis/behavior-design` |
+| FR10          | streaming stories; exact-head browser evidence remains pending      | animated, immediate, entering/leaving tick                      | Disabling animation retains a transition or a moving label jumps to stale geometry.       | `audit:ChartAxis/design-testing`  |
+| AR2, AR3      | Chart accessibility tests; package axe; accessibility-tree review   | title/subtitle, small-data table, nested axis groups            | Chart loses its alternative or an unreviewed nested semantic claim is treated as fact.    | `audit:ChartAxis/accessibility`   |
+
+## Decision log
+
+None. This draft records observed behavior and one objective Unicode correction; it does not approve new ChartAxis policy.
+
+## Open questions
+
+- **OQ1 — Axis semantics.** Should ChartAxis remain purely visual content within Chart's single named image, or expose each axis as an independently localized accessibility group? (`human-api`)
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, current audit results,
+implementation steps, or shared system rules. It links to their owners.

package/src/ChartAxis.test.tsx

@@ -4,8 +4,8 @@
  * @file ChartAxis.test.tsx
  * @input Uses vitest, @testing-library/react, Chart, ChartAxis, bar mark
  * @output Functional tests for axis rendering — group semantics, band/linear
- *         tick labels, default edge-line rules, custom formatting, truncation,
- *         and label capping
+ *         tick labels, physical edge placement, default edge-line rules,
+ *         custom formatting, grapheme-safe truncation and density, and label capping
  * @position Colocated test for ChartAxis.tsx (issue #4295 viz coverage)
  */
 
@@ -88,6 +88,52 @@ describe('ChartAxis bottom (band scale)', () => {
     expect(within(axis).queryByText('Feb')).not.toBeInTheDocument();
   });
 
+  it('automatically reduces categorical labels as the plot narrows', () => {
+    const denseData = Array.from({length: 20}, (_, index) => ({
+      month: `Period ${index + 1}`,
+      sales: index,
+    }));
+    renderChart(<ChartAxis position="bottom" />, denseData);
+    const axis = screen.getByRole('group', {name: 'bottom axis'});
+    const wideLabelCount = axis.querySelectorAll('text').length;
+
+    reportWidth(120);
+
+    const narrowLabelCount = axis.querySelectorAll('text').length;
+    expect(narrowLabelCount).toBeGreaterThan(0);
+    expect(narrowLabelCount).toBeLessThan(wideLabelCount);
+  });
+
+  it('keeps the same auto-thinned labels after ASCII and Unicode truncation', () => {
+    const asciiData = Array.from({length: 9}, (_, index) => ({
+      month: `${index + 1}AB`,
+      sales: index,
+    }));
+    const clusters = ['👨‍👩‍👧‍👦', '🇯🇵', '👩🏽‍🚀'];
+    const unicodeData = Array.from({length: 9}, (_, index) => ({
+      month: `${index + 1}${clusters[index % clusters.length]}X`,
+      sales: index,
+    }));
+
+    const retainedIndexes = (data: typeof asciiData) => {
+      const {unmount} = renderChart(
+        <ChartAxis position="bottom" truncate={2} />,
+        data,
+      );
+      reportWidth(300);
+      const indexes = Array.from(
+        screen
+          .getByRole('group', {name: 'bottom axis'})
+          .querySelectorAll('text'),
+        label => Number(label.textContent?.match(/^(\d+)/)?.[1]),
+      );
+      unmount();
+      return indexes;
+    };
+
+    expect(retainedIndexes(unicodeData)).toEqual(retainedIndexes(asciiData));
+  });
+
   it('truncates long category labels with an ellipsis', () => {
     renderChart(<ChartAxis position="bottom" truncate={4} />, [
       {month: 'January', sales: 4},
@@ -98,6 +144,15 @@ describe('ChartAxis bottom (band scale)', () => {
     // Short labels are left alone.
     expect(within(axis).getByText('Feb')).toBeInTheDocument();
   });
+
+  it('preserves whole grapheme clusters when truncating labels', () => {
+    const family = '👨‍👩‍👧‍👦';
+    renderChart(<ChartAxis position="bottom" truncate={1} />, [
+      {month: `${family}Q`, sales: 4},
+    ]);
+    const axis = screen.getByRole('group', {name: 'bottom axis'});
+    expect(within(axis).getByText(`${family}…`)).toBeInTheDocument();
+  });
 });
 
 describe('ChartAxis left (linear scale)', () => {
@@ -129,3 +184,26 @@ describe('ChartAxis left (linear scale)', () => {
     expect(lines).toHaveLength(7);
   });
 });
+
+describe('ChartAxis top and right positions', () => {
+  it('places both axes on their physical plot edges with outward labels', () => {
+    renderChart(
+      <>
+        <ChartAxis position="top" showTicks />
+        <ChartAxis position="right" showTicks />
+      </>,
+    );
+
+    const top = screen.getByRole('group', {name: 'top axis'});
+    expect(top).not.toHaveAttribute('transform');
+    expect(within(top).getByText('Jan')).toHaveAttribute('y', '-10');
+
+    const right = screen.getByRole('group', {name: 'right axis'});
+    expect(right).toHaveAttribute('transform', 'translate(528,0)');
+    expect(within(right).getByText('0')).toHaveAttribute('x', '10');
+    expect(within(right).getByText('0')).toHaveAttribute(
+      'text-anchor',
+      'start',
+    );
+  });
+});

package/src/ChartAxis.tsx

@@ -2,6 +2,7 @@
 
 /**
  * @file ChartAxis.tsx (v2)
+ * @input Chart context scales, axis presentation props, and grapheme-safe text utilities
  * @output Renders an axis (top, right, bottom, left) using the chart's scales
  * @position Child of Chart v2; reads scales from chart context
  *
@@ -19,6 +20,7 @@
 
 import {useCallback, useMemo} from 'react';
 import * as stylex from '@stylexjs/stylex';
+import {characterCount, truncateCharacters} from '@astryxdesign/core/utils';
 import {colorVars} from '@astryxdesign/core/theme/tokens.stylex';
 import {useChart} from './ChartContext';
 import {isBandScale} from './utils';
@@ -33,7 +35,7 @@ export interface ChartAxisProps {
   maxTicks?: number;
   /** Custom tick formatter */
   tickFormat?: (value: unknown) => string;
-  /** Truncate labels to this many characters (appends "\u2026"). */
+  /** Truncate labels to this many user-perceived characters (appends "\u2026"). */
   truncate?: number;
   /** Enable smooth transitions for streaming (default: true) */
   animated?: boolean;
@@ -121,19 +123,24 @@ export function ChartAxis({
   const format = useCallback(
     (value: unknown): string => {
       const str = (tickFormat ?? autoFormat ?? String)(value);
-      return truncate && str.length > truncate
-        ? str.slice(0, truncate) + '\u2026'
-        : str;
+      if (!truncate) {
+        return str;
+      }
+      const shortened = truncateCharacters(str, truncate, '');
+      return shortened === str ? str : shortened + '\u2026';
     },
     [tickFormat, autoFormat, truncate],
   );
 
   const ticks = useMemo(() => {
-    let allTicks: {value: unknown; offset: number}[];
+    // Format each generated tick once so density and rendering share the same
+    // grapheme-safe label instead of repeating consumer formatting/segmentation.
+    let allTicks: {value: unknown; offset: number; label: string}[];
     if (isBandScale(scale)) {
       allTicks = scale.domain().map(d => ({
         value: d,
         offset: (scale(d) ?? 0) + scale.bandwidth() / 2,
+        label: format(d),
       }));
     } else {
       const linearScale = scale as
@@ -141,6 +148,7 @@ export function ChartAxis({
       allTicks = linearScale.ticks(safeTickCount).map(d => ({
         value: d,
         offset: linearScale(d as number & Date),
+        label: format(d),
       }));
     }
 
@@ -154,7 +162,7 @@ export function ChartAxis({
     if (cap == null && allTicks.length > 1) {
       if (isHorizontal && width > 0) {
         const widestChars = allTicks.reduce(
-          (m, t) => Math.max(m, format(t.value).length),
+          (m, tick) => Math.max(m, characterCount(tick.label)),
           1,
         );
         const approxLabelPx = widestChars * 7 + 16;
@@ -210,8 +218,7 @@ export function ChartAxis({
           {...stylex.props(styles.axisLine)}
         />
       )}
-      {ticks.map(({value, offset}) => {
-        const label = format(value);
+      {ticks.map(({value, offset, label}) => {
         // Key off the raw tick value, not the formatted label: distinct ticks
         // can format (or truncate) to the same string and would collide as keys.
         const key = String(value);

package/src/ChartGrid.doc.mjs

@@ -0,0 +1,114 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
+
+export const docs = {
+  name: 'ChartGrid',
+  displayName: 'Chart Grid',
+  group: 'Charts',
+  category: 'Data Visualization',
+  isHiddenFromOverview: true,
+  keywords: ['chart', 'grid', 'guides', 'axis', 'ticks', 'data visualization'],
+
+  usage: {
+    description:
+      'ChartGrid draws horizontal and vertical guide lines from the scales owned by a parent Chart. Use it in the Chart grid slot so guides share the plot dimensions and tick values used by the chart.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Pair ChartGrid with ChartAxis when readers need labelled values beside the guide lines.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use horizontal guides for value comparison and add vertical guides only when they help readers align categories or continuous x values.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use grid lines as the only way to communicate a value or distinction. Keep meaningful chart information in labels, marks, and the parent Chart alternative.',
+      },
+      {
+        guidance: false,
+        description:
+          'Expect tickCount to thin categorical band centers. It requests density only for continuous scales; categorical vertical guides render once per band.',
+      },
+    ],
+    accessibility: [
+      {
+        name: 'Chart alternative',
+        category: 'Content',
+        criterion: '1.1.1 Non-text Content',
+        requirement: 'Required on the parent Chart',
+        states: ['All'],
+        description:
+          'Chart owns the accessible image name and supported small-data table. Grid lines supplement that chart-level alternative rather than replacing it.',
+      },
+      {
+        name: 'Visual-only guides',
+        category: 'Color contrast',
+        criterion: '1.4.11 Non-text Contrast',
+        requirement: 'Do not carry information alone',
+        states: ['Horizontal', 'Vertical', 'Combined'],
+        description:
+          'Grid lines are supporting guides. Preserve visible labels, marks, or another qualifying cue so understanding does not depend on the grid alone.',
+      },
+    ],
+    anatomy: [
+      {
+        name: 'Grid lines',
+        required: false,
+        description:
+          'Horizontal lines at continuous y ticks and vertical lines at x ticks or categorical band centers.',
+      },
+    ],
+  },
+
+  props: [
+    {
+      name: 'horizontal',
+      type: 'boolean',
+      description:
+        'Whether to draw horizontal guides at continuous y ticks other than zero.',
+      default: 'true',
+    },
+    {
+      name: 'vertical',
+      type: 'boolean',
+      description:
+        'Whether to draw vertical guides at continuous x ticks or categorical band centers.',
+      default: 'false',
+    },
+    {
+      name: 'tickCount',
+      type: 'number',
+      description:
+        'Approximate guide count requested from continuous scales. It does not thin categorical band centers.',
+      default: '5',
+    },
+  ],
+
+  examples: [
+    {
+      label: 'Horizontal guides',
+      code: `import {Chart, ChartGrid, bar} from '@astryxdesign/charts';
+
+<Chart
+  data={monthlyRevenue}
+  xKey="month"
+  series={[bar('revenue')]}
+  grid={<ChartGrid />}
+/>;`,
+    },
+    {
+      label: 'Horizontal and vertical guides',
+      code: `<Chart
+  data={monthlyRevenue}
+  xKey="month"
+  series={[bar('revenue')]}
+  grid={<ChartGrid horizontal vertical tickCount={6} />}
+/>;`,
+    },
+  ],
+};

package/src/ChartGrid.spec.md

@@ -0,0 +1,184 @@
+---
+schema_version: 3
+template_version: 5
+kind: component
+id: component:ChartGrid
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [public-api, behavior, layout, theming, accessibility]
+verified_by:
+  [
+    packages/charts/src/ChartGrid.test.tsx,
+    apps/storybook/stories/charts/ChartGrid.stories.tsx,
+  ]
+modules: []
+families: []
+design_specs: []
+architecture:
+  [
+    architecture:component-test-sufficiency,
+    architecture:component-theming-surface,
+  ]
+contributing: []
+system_specs: [spec:AST-002, spec:AST-029]
+---
+
+# ChartGrid component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                         |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | No API shape or default changes. This draft records the current horizontal, vertical, and continuous-scale tick-density surface.                                                 |
+| Behavior                | Horizontal guides follow continuous y ticks except zero; vertical guides follow categorical x-band centers or continuous x ticks; both directions remain independently optional. |
+| End-user impact         | Chart readers receive guide lines aligned with the parent Chart's plot scales; this audit changes no rendered behavior.                                                          |
+| Builder impact          | Existing callsites remain valid and gain direct CLI documentation and focused evidence for current density fallbacks.                                                            |
+| Compatibility/readiness | The package remains canary-only. This observational draft is non-authoritative, and exact rendered/accessibility evidence remains pending.                                       |
+| Review checks           | Reject a changed public shape/default, a guide using a scale outside Chart context, a zero baseline drawn twice, or categorical guides no longer centered on their bands.        |
+| Governing rules         | `spec:AST-029/FR3–FR7`, `architecture:component-test-sufficiency/INV1–INV11`, `architecture:component-theming-surface/INV1–INV6`, and `spec:AST-002`.                            |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+ChartGrid renders passive Cartesian guide lines inside a Chart. It owns line
+selection and placement from Chart-provided scales and plot dimensions while Chart
+owns the coordinate system, rendering order, and chart-level alternative.
+
+## Compatibility and migration
+
+- Released default preserved: yes at the canary surface; the package has no stable release.
+- Compatibility class: no public API, default, or rendered-behavior change.
+- Controlled/uncontrolled behavior: not applicable.
+- Migration decision: none; this draft does not authorize a public API change.
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- Selecting horizontal and vertical guide values from Chart-provided scales.
+- Positioning each guide across the current plot width or height.
+- Omitting the horizontal zero guide that the paired axis may emphasize.
+- Sanitizing continuous-scale tick requests before passing them to d3.
+
+**Does not own / non-goals**
+
+- Data, domains, scale construction, plot dimensions, or paint order — owned by `component:Chart`.
+- Axis labels, tick marks, or plot-edge lines — owned by `component:ChartAxis`.
+- The chart's accessible name, description, or data alternative — owned by `component:Chart` and the product callsite.
+- Product-specific decisions about whether guides are needed.
+
+## Public concepts
+
+| Concept             | Closed values or states                 | Meaning                                                       | Availability by variant/orientation/state | Default   | Owner                 | Stability    | Invalid-value behavior                                                             |
+| ------------------- | --------------------------------------- | ------------------------------------------------------------- | ----------------------------------------- | --------- | --------------------- | ------------ | ---------------------------------------------------------------------------------- |
+| Horizontal guides   | shown or hidden                         | Draws lines at continuous y ticks, excluding zero.            | Every ChartGrid                           | shown     | `component:ChartGrid` | experimental | Not applicable.                                                                    |
+| Vertical guides     | shown or hidden                         | Draws lines at x ticks or categorical x-band centers.         | Every ChartGrid                           | hidden    | `component:ChartGrid` | experimental | Not applicable.                                                                    |
+| Continuous density  | finite non-negative number              | Requests an approximate line count from d3 continuous scales. | Horizontal guides and continuous x guides | `5`       | `component:ChartGrid` | experimental | Fractions floor; values above 1000 cap; negative/non-finite values fall back to 5. |
+| Categorical density | one guide per categorical x-band center | Keeps vertical guides aligned to every band.                  | Categorical x with vertical guides        | all bands | `component:ChartGrid` | experimental | `tickCount` currently has no effect.                                               |
+| Chart context       | inside a parent `Chart`                 | Supplies scales and current plot dimensions.                  | Always                                    | none      | `component:Chart`     | experimental | Rendering outside Chart throws the shared context error.                           |
+
+## Behavioral and layout contract
+
+Draft requirements identify their basis so observed code is not mistaken for an
+intentional decision.
+
+| ID  | Candidate invariant                                                                                                                                | Basis                                                  | Draft review state |
+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ------------------ |
+| FR1 | ChartGrid MUST consume the current width, height, x scale, and y scale from its parent Chart context.                                              | implementation, package composition, and focused tests | verify             |
+| FR2 | `horizontal` and `vertical` MUST independently enable their guide sets; enabling both MUST render both sets.                                       | implementation, JSDoc, tests, and Storybook            | verify             |
+| FR3 | Horizontal guides MUST use continuous y ticks, span the plot width, and omit y=0 so a paired axis does not receive a duplicate line.               | implementation, JSDoc, and focused tests               | verify             |
+| FR4 | Vertical guides MUST use categorical band centers for band x scales and d3 tick positions for continuous x scales, spanning the plot height.       | implementation and focused tests                       | verify             |
+| FR5 | Continuous tick requests MUST be finite, non-negative integers no greater than 1000; zero yields no continuous guides and invalid values use five. | implementation, crash-prevention rationale, and tests  | verify             |
+| FR6 | Guide paint MUST consume a semantic theme token. Whether grid lines become a public theme target remains unsettled.                                | implementation and current theming architecture        | verify             |
+
+### Allowed variation
+
+- **AV1 — Continuous tick count.** d3 may choose a nearby set of values rather than exactly the requested number.
+- **AV2 — Categorical values.** Each current x-band domain value contributes one centered vertical guide.
+
+### Representative states
+
+| State                      | Required invariant                                               | Allowed variation                              |
+| -------------------------- | ---------------------------------------------------------------- | ---------------------------------------------- |
+| Default                    | Horizontal guides only; continuous density defaults to five.     | d3 chooses the exact y tick set.               |
+| Horizontal disabled        | No horizontal guides.                                            | Vertical guides may remain enabled.            |
+| Vertical categorical       | One vertical guide at each x-band center.                        | Band width and center follow Chart's x scale.  |
+| Vertical continuous        | One guide at each generated continuous x tick.                   | d3 chooses the exact x tick set.               |
+| Both directions            | Horizontal and vertical sets render together.                    | Their exact counts may differ.                 |
+| Zero continuous tick count | Continuous guide sets are empty.                                 | Categorical vertical guides remain unaffected. |
+| Invalid tick count         | Continuous guide generation falls back to the default request.   | d3 chooses the resulting exact ticks.          |
+| Narrow / RTL               | Guides remain tied to physical data coordinates and plot bounds. | Plot width and data-domain order vary.         |
+
+### Transformation and precedence order
+
+- **ORD1 — Continuous density.** Validate finiteness and non-negativity → floor fractions → cap at 1000 → request d3 ticks.
+- **ORD2 — Placement.** Select enabled directions → choose the scale path → derive tick or band-center positions → span the current opposite plot dimension.
+
+### Performance and resources
+
+- **PR1 — Derived output.** Guide arrays remain render-derived and memoized from enabled directions, scales, dimensions, and sanitized density. ChartGrid owns no listener, observer, timer, or persistent resource.
+- **PR2 — Bounded tick allocation.** A public density value cannot request more than 1000 continuous ticks from d3.
+
+## Accessibility contract
+
+- **AR1 — Chart-level alternative.** ChartGrid renders passive supporting guides inside Chart's named image. Chart owns the accessible chart name and supported data-table alternative.
+- **AR2 — No grid-only information.** Grid lines do not replace visible labels, meaningful marks, or the parent Chart alternative.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                                | Representation authority                      | Hierarchy role | Component contract |
+| ---------------- | ----------------------------------------------------------------- | --------------------------------------------- | -------------- | ------------------ |
+| Grid lines       | Support position comparison without carrying chart meaning alone. | unsettled; no current design record is linked | supporting     | FR2–FR6, AR1–AR2   |
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Grid lines": {
+    "none": {
+      "reason": "unsettled: ChartGrid consumes a semantic color token, but no current component or family contract decides whether grid lines are a public theme target."
+    }
+  }
+}
+```
+
+## Family and system relationships
+
+- No current family or design record governs ChartGrid.
+- `architecture:component-test-sufficiency` owns rational public-state partitions, observable assertions, and audit evidence quality.
+- `architecture:component-theming-surface` owns anatomy-to-target disposition; token consumption alone does not enroll ChartGrid in public component theming.
+- `spec:AST-002` owns public API admission and prevents this audit from adding or reinterpreting a public choice.
+- `spec:AST-029` owns this observational backfill, closed evidence receipt, safe remediation, and fail-closed eligibility report.
+
+## Verification map
+
+| Contract | Verification                                           | Representative states                                       | Mutation or failure expectation                                                    | Audit section                      |
+| -------- | ------------------------------------------------------ | ----------------------------------------------------------- | ---------------------------------------------------------------------------------- | ---------------------------------- |
+| FR1–FR2  | `ChartGrid.test.tsx`; `ChartGrid.stories.tsx`          | default, horizontal off, vertical on, both, neither         | A direction stops respecting its input or output escapes the parent Chart context. | `audit:ChartGrid/behavior`         |
+| FR3      | `ChartGrid.test.tsx`                                   | positive and mixed-sign y domains                           | Guides stop spanning the plot or y=0 is drawn twice.                               | `audit:ChartGrid/behavior-layout`  |
+| FR4      | `ChartGrid.test.tsx`; `ChartGrid.stories.tsx`          | categorical and continuous x                                | A band guide leaves its center or a continuous tick lands at the wrong coordinate. | `audit:ChartGrid/behavior-layout`  |
+| FR5, PR2 | focused zero/invalid-density tests and source review   | zero and invalid requests; fractional and capped partitions | Invalid input crashes render or bypasses the bounded fallback.                     | `audit:ChartGrid/behavior-testing` |
+| FR6      | strict lint; Storybook theme matrix remains pending    | light, dark, and supported non-default themes               | A raw color or component-side mode choice replaces semantic token paint.           | `audit:ChartGrid/theming-design`   |
+| AR1–AR2  | Chart accessibility tests; package axe remains pending | named Chart, small-data table, grid enabled                 | Grid content replaces or becomes the only source of required chart information.    | `audit:ChartGrid/accessibility`    |
+
+## Decision log
+
+None. This draft records observed behavior and evidence gaps only.
+
+## Open questions
+
+- **OQ1 — Categorical density.** Should `tickCount` remain continuous-scale-only, or should vertical categorical guides gain a documented thinning contract aligned with ChartAxis? (`human-api`)
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, current audit results,
+implementation steps, or shared system rules. It links to their owners.

package/src/ChartGrid.test.tsx

@@ -4,7 +4,8 @@
  * @file ChartGrid.test.tsx
  * @input Uses vitest, @testing-library/react, Chart, ChartGrid, bar mark
  * @output Functional tests for grid lines — horizontal default, the skipped
- *         y=0 line, and vertical lines at band centers
+ *         y=0 line, vertical lines at band/continuous positions, combined
+ *         directions, and safe continuous tick-count handling
  * @position Colocated test for ChartGrid.tsx (issue #4295 viz coverage)
  */
 
@@ -95,6 +96,24 @@ describe('ChartGrid', () => {
     expect(lines).toHaveLength(8); // 5 horizontal + 3 vertical
   });
 
+  it('uses zero to request no continuous grid lines', () => {
+    const {lines} = renderGrid(<ChartGrid tickCount={0} />);
+    expect(lines).toHaveLength(0);
+  });
+
+  it('falls back to the default density for a non-finite tick count', () => {
+    const {lines} = renderGrid(
+      <ChartGrid tickCount={Number.POSITIVE_INFINITY} />,
+    );
+    expect(lines).toHaveLength(5);
+  });
+
+  it('caps a huge continuous tick request without throwing', () => {
+    const {lines} = renderGrid(<ChartGrid tickCount={1e9} />);
+    expect(lines.length).toBeGreaterThan(0);
+    expect(lines.length).toBeLessThanOrEqual(1001);
+  });
+
   it('places vertical lines at d3 tick values on a linear x scale', () => {
     const numeric = [
       {month: 0, sales: 1},

package/src/ChartGrid.tsx

@@ -2,6 +2,7 @@
 
 /**
  * @file ChartGrid.tsx (v2)
+ * @input Chart context scales and dimensions, guide visibility, and tick density
  * @output Grid lines behind chart marks
  * @position Child of Chart v2; reads scales from chart context
  */