Surface BigNumber; ARIA direction uses delta sign

Expose BigNumber via AI surface and fix its ARIA wording. Updates:

- BigNumber component: buildAriaSentence now uses the numeric delta sign (positive/negative) to pick the direction word ("up"/"down") instead of relying on visual sentiment, avoiding awkward screen-reader phrasing like "up −5" for lower-is-better metrics. Passes delta through to BigNumberInner.
- Tests: add accessibility test to assert the ARIA direction follows the delta sign and that visual sentiment styling remains independent.
- Scripts: include the `value` subpath in the semiotic/ai export regex and adjust expected export logic/logging since value charts (e.g. BigNumber) are now re-exported.
- Docs: correct ThemeProvider import path and update ScaleAwarePage copy to mention BigNumber (with a link to /charts/big-number) and future composition suggestions.

Motivation: properly surface BigNumber across the AI/MCP surface and ensure screen readers read factual direction words while keeping sentiment-based visuals separate.

Author: emeeks

docs/src/pages/charts/BigNumberPage.js

@@ -1,6 +1,6 @@
 import React, { useEffect, useRef, useState } from "react"
 import { BigNumber } from "semiotic/value"
-import { ThemeProvider } from "semiotic"
+import { ThemeProvider } from "semiotic/utils"
 import { THEME_PRESETS } from "semiotic/themes"
 // These chart families are imported *only here in the docs* to demo
 // dropping a real Semiotic chart into BigNumber's `trendSlot` (wide /

docs/src/pages/features/ScaleAwarePage.js

@@ -1,4 +1,5 @@
 import React, { useEffect, useMemo, useState } from "react"
+import { Link } from "react-router-dom"
 import {
   suggestCharts,
   suggestChartsGrouped,
@@ -588,12 +589,26 @@ export const ForceDirectedGraphCapability: ChartCapability = {
         should — bend to your shop's conventions.
       </p>
 
-      <h2>The single-value gap</h2>
+      <h2>The single-value gap (now filled)</h2>
       <p>
-        At <strong>tiny</strong> scale, the engine's catalog currently has one chart:
-        <code>GaugeChart</code>. Single-value displays (BigNumber, KPI cards, scorecards) aren't
-        shipped yet — the suggestion engine is honest about wanting them. The roadmap entry for{" "}
-        <code>SingleValueFrame</code> sketches that gap and the design tradeoffs around filling it.
+        At <strong>tiny</strong> scale, the engine used to only have{" "}
+        <code>GaugeChart</code>, and a gauge is misleading without an explicit
+        min / max. <code>BigNumber</code> (under <code>semiotic/value</code>)
+        ships as the honest answer for unbounded single-value data — and the
+        capability layer wires it into <code>suggestCharts</code> /{" "}
+        <code>suggestChartsGrouped</code> with a <code>scaleFit</code> boost
+        that puts it ahead of <code>GaugeChart</code> at the{" "}
+        <strong>tiny</strong> band. See{" "}
+        <Link to="/charts/big-number">/charts/big-number</Link> for the full
+        component, and the roadmap entry for <code>SingleValueFrame</code> for
+        what a future frame-backed version would inherit.
+      </p>
+      <p>
+        Next iteration: <strong>composition suggestions</strong> — sets of N
+        charts where a <code>BigNumber</code> can host the others via its{" "}
+        <code>trendSlot</code> / <code>chartSlot</code> rather than the
+        dashboard rendering them as peer cards. Documented in the roadmap;
+        not part of this PR.
       </p>
     </PageLayout>
   )

scripts/check-surface-parity.js

@@ -70,7 +70,7 @@ function parseSchemaComponents() {
 function parseSemioticAIChartExports() {
   const source = read(files.semioticAI)
   const names = new Set()
-  const exportRegex = /export\s+\{([^}]+)\}\s+from\s+"\.\/charts\/(?:xy|ordinal|network|realtime)\//g
+  const exportRegex = /export\s+\{([^}]+)\}\s+from\s+"\.\/charts\/(?:xy|ordinal|network|realtime|value)\//g
   for (const match of source.matchAll(exportRegex)) {
     for (const raw of match[1].split(",")) {
       const name = raw.trim().split(/\s+as\s+/)[0].trim()
@@ -135,8 +135,12 @@ const metadataRenderable = new Set(
     .map(component => component.name)
 )
 
+// Value charts now DO get re-exported from `semiotic/ai` (BigNumber is
+// surfaced for the intelligence demo pages), so they're expected in the
+// AI exports set. Geo charts stay excluded because they ship under a
+// separate subpath and aren't re-exported from `semiotic/ai`.
 const expectedAIExports = new Set(
-  [...validation].filter(name => !geoCharts.has(name) && !valueCharts.has(name))
+  [...validation].filter(name => !geoCharts.has(name))
 )
 const expectedMCPRegistry = new Set(
   [...validation].filter(name => !realtimeCharts.has(name) && !valueCharts.has(name))
@@ -198,7 +202,7 @@ if (errors.length) {
 
 console.log("AI/MCP surface parity check passed")
 console.log(`  ${validation.size} validation/schema components`)
-console.log(`  ${semioticAI.size} semiotic/ai chart exports (${geoCharts.size} geo + ${valueCharts.size} value chart(s) intentionally excluded)`)
+console.log(`  ${semioticAI.size} semiotic/ai chart exports (${geoCharts.size} geo chart(s) intentionally excluded)`)
 console.log(`  ${mcpRegistry.size} MCP-renderable components (${realtimeCharts.size} realtime + ${valueCharts.size} value chart(s) intentionally excluded)`)
 console.log(`  ${metadataComponents.size} shared AI metadata components`)
 console.log(`  ${serverConfigs.size} server render configs (+ ${SERVER_CONFIG_EXCLUDED.size} documented HOC-SSR exclusions)`)

src/components/charts/value/BigNumber.test.tsx

@@ -359,6 +359,30 @@ describe("BigNumber — accessibility", () => {
     expect(aria).toContain("of weekly goal")
   })
 
+  it("ARIA direction word follows the delta sign, not sentiment (lower-is-better)", () => {
+    // Latency went DOWN (good under lower-is-better) — sentiment is
+    // positive but the screen reader sentence should still report
+    // "down 60 ms" (factual direction), not "up 60 ms".
+    const { container } = render(
+      <BigNumber
+        value={340}
+        label="P99 latency"
+        suffix=" ms"
+        comparison={{ value: 400, label: "vs last week", direction: "lower-is-better" }}
+      />
+    )
+    const aria = container
+      .querySelector("[data-chart='BigNumber']")
+      ?.getAttribute("aria-label") ?? ""
+    expect(aria).toContain("down")
+    expect(aria).not.toContain("up")
+    // Sentiment-positive (good) coloring still applies — direction word
+    // and visual sentiment are independent concerns.
+    expect(
+      container.querySelector("[data-sentiment='positive']")
+    ).not.toBeNull()
+  })
+
   it("uses description prop as the ARIA override when provided", () => {
     const { container } = render(
       <BigNumber value={1} description="custom description for this card" />

src/components/charts/value/BigNumber.tsx

@@ -286,9 +286,9 @@ function buildAriaSentence(args: {
   formattedValue: string
   unit?: string
   comparisonLabel?: string
+  delta?: number | null
   deltaFormatted?: string | null
   deltaPercent?: string | null
-  sentiment: "positive" | "negative" | "neutral"
   targetLabel?: string
   targetPercent?: string | null
   stale: boolean
@@ -300,12 +300,19 @@ function buildAriaSentence(args: {
     args.unit ? `${args.formattedValue} ${args.unit}` : args.formattedValue
   )
   if (args.deltaFormatted) {
+    // Direction word follows the SIGN of the delta, not the sentiment.
+    // Sentiment is a styling concern ("good" / "bad" colour) that flips
+    // when `direction: "lower-is-better"` — but for a screen reader the
+    // factual phrasing must remain "up" for +5 and "down" for −5
+    // regardless. Avoids the previous "up −5" reading on lower-is-better
+    // metrics.
+    const d = args.delta
     const dirWord =
-      args.sentiment === "positive"
-        ? "up"
-        : args.sentiment === "negative"
-          ? "down"
-          : "change"
+      d != null && Number.isFinite(d) && d !== 0
+        ? d > 0
+          ? "up"
+          : "down"
+        : "change"
     const pct = args.deltaPercent ? ` (${args.deltaPercent})` : ""
     const comp = args.comparisonLabel ? ` from ${args.comparisonLabel}` : ""
     parts.push(`${dirWord} ${args.deltaFormatted}${pct}${comp}`)
@@ -652,9 +659,9 @@ const BigNumberInner = (
         : "",
       unit,
       comparisonLabel: comparison?.label,
+      delta: computedDelta,
       deltaFormatted,
       deltaPercent,
-      sentiment,
       targetLabel: target?.label,
       targetPercent,
       stale,