style(chart): open chart pages and surface/track tokens

- @hm-design/chart: add --hm-chart-track (radial tracks, horizontal bar hover band; warm neutral light) and --hm-chart-surface (slice / segment gaps, Dot rings, label halos, radial meter center; white by default) - --hm-chart-bar-name-halo stays an optional override and falls back to --hm-chart-surface; official chart.tsx unchanged - Storybook Chart pages (Bar / Line / Area / Donut / Pie / Radar / Radial): open layout without example cards, 2-4 responsive columns, one sample data notice per page, surface token set to the content background - Same sample data, props, tooltip and interaction as the example cards; examples entry and consumer example unchanged - README: surface / track token usage
2026-11-12 17:12:09 +09:00
1 parent a7b56ff23e
commit 7ff852952a
@@ -25,6 +25,7 @@
 - `@hm-design/ui/theme.css`는 차트 색 별칭(`--hm-chart-*`)이 가리키는 `--hm-sem-*` 토큰과 Noto Sans KR 글꼴을 제공합니다.
 - 차트 스타일(`@hm-design/chart/style.css`)은 JS 진입점(`@hm-design/chart`, `@hm-design/chart/examples`)이 자동으로 불러오므로 따로 import하지 않습니다.
 - `<html>`·`<body>`에 배경·글꼴을 정하는 것은 소비 앱의 몫입니다(차트는 전역 규칙을 넣지 않습니다).
+- 흰색이 아닌 배경(카드 없이 콘텐츠 배경 위 등)에 차트를 바로 놓을 때는 차트를 감싼 요소에 `--hm-chart-surface`를 그 배경색으로 지정합니다. 예: CSS `.report-charts { --hm-chart-surface: var(--hm-sem-bg-content); }` 또는 Tailwind `[--hm-chart-surface:var(--hm-sem-bg-content)]`. 조각·세그먼트 사이 간격, 포인트 Dot 외곽선, Label halo, 래디얼 미터(`HMRadialMeterChart`) 중앙 원이 이 색을 써서 배경처럼 보입니다. 지정하지 않으면 기본값 흰색(`--hm-sem-bg-surface`)입니다.

 ## 2. 진입점과 차트 고르기

@@ -116,7 +117,7 @@ npm run storybook                         # Chart 그룹: Bar / Line / Donut / P

 ### 예제 컴포넌트

-소비 예제(`examples/chart/main.tsx`)와 Storybook은 `@hm-design/chart/examples`의 예제 카드를 사용합니다: Bar(`BarChartExample`, `StackedBarChartExample`, `HorizontalBarChartExample`, `SignedBarChartExample`), Line(`LineChartExample` 외 Curve·Straight·Step 변형), Donut(`DonutChartExample` 외 Plain·Center·Active·Interactive·`DonutSolidExample`(입체형)), Pie(`PiePlainExample`, `PieLabelExample`, `PieLabelListExample`, `PieStackedExample`, `PieSolidExample`(입체형)), Radar(`RadarPlainExample`, `RadarDotExample`, `RadarLinesOnlyExample`, `RadarCustomLabelExample`), Area(`AreaCurveExample` 외 Straight·Step·Stacked·Expanded), Radial(`RadialSimpleExample`, `RadialLabelExample`, `RadialGridExample`, `RadialTextExample`, `RadialShapeExample`, `RadialStackedExample`), 묶음 `ChartExamples`. 예시 데이터(`sampleBar`, `samplePie`, `sampleRadial` 등)는 같은 진입점에서 export됩니다. 예제 카드는 `ExampleCard`(내부 컴포넌트)로 감싸며 실제 업무 데이터가 아님을 표시합니다.
+소비 예제(`examples/chart/main.tsx`)는 `@hm-design/chart/examples`의 예제 카드를 사용합니다. Storybook(`Chart` 그룹)은 같은 예시 데이터·props로 공개 차트 컴포넌트(`HM*Chart`)를 카드 없이 오픈형으로 전시합니다(Story 전용 레이아웃 `src/chart/chart-story.tsx`). 예제 카드: Bar(`BarChartExample`, `StackedBarChartExample`, `HorizontalBarChartExample`, `SignedBarChartExample`), Line(`LineChartExample` 외 Curve·Straight·Step 변형), Donut(`DonutChartExample` 외 Plain·Center·Active·Interactive·`DonutSolidExample`(입체형)), Pie(`PiePlainExample`, `PieLabelExample`, `PieLabelListExample`, `PieStackedExample`, `PieSolidExample`(입체형)), Radar(`RadarPlainExample`, `RadarDotExample`, `RadarLinesOnlyExample`, `RadarCustomLabelExample`), Area(`AreaCurveExample` 외 Straight·Step·Stacked·Expanded), Radial(`RadialSimpleExample`, `RadialLabelExample`, `RadialGridExample`, `RadialTextExample`, `RadialShapeExample`, `RadialStackedExample`), 묶음 `ChartExamples`. 예시 데이터(`sampleBar`, `samplePie`, `sampleRadial` 등)는 같은 진입점에서 export됩니다. 예제 카드는 `ExampleCard`(내부 컴포넌트)로 감싸며 실제 업무 데이터가 아님을 표시합니다.

 ## 공식 shadcn Chart와의 차이

@@ -125,6 +126,7 @@ npm run storybook                         # Chart 그룹: Bar / Line / Donut / P
 ## 제한

 - 차트 전용 HM 디자인 규격은 아직 없습니다. 색은 기존 HM 팔레트 Semantic 토큰의 별칭이며(`src/chart.css`), 차트 Token은 이 패키지 안에서만 정의합니다.
+- 배경 관련 차트 토큰(2026-11-12): `--hm-chart-track`(기본 `--hm-sem-palette-warm-neutral-light` #E0DACE)은 래디얼 비활성 트랙(`HMRadialBarChart` 배경 트랙, `HMRadialMeterChart` 링 트랙)과 가로 막대 Hover 띠입니다. 공식 shadcn 소스는 `muted`(#F4F1EA)인데, 콘텐츠 배경 #F5F0E5와 거의 같아 보이지 않으므로 `chart.css`에서 덮어씁니다(`chart.tsx`는 그대로). `--hm-chart-surface`(기본 `--hm-sem-bg-surface` 흰색)는 차트가 놓인 면의 색입니다(위 §1 참고). `--hm-chart-bar-name-halo`는 선택 override로 남았고, 지정하지 않으면 `--hm-chart-surface`를 씁니다. 흰 배경에서는 트랙·Hover 띠만 한 단계 진해지고 나머지는 이전과 같습니다.
 - 글자색은 Admin 텍스트 위계를 따릅니다: 툴팁 값·중앙값·막대 이름/값은 `--hm-sem-fg-primary`(#212121), 축 눈금(Cartesian·Radar 기본 축 이름)·범례·툴팁 이름·중앙 캡션은 `--hm-chart-axis-text` → `--hm-sem-fg-secondary`(#616161)입니다.
 - 접근성 후속 항목(2026-11-11 기록, 미수정): Line·Area 포인트 값 Label은 시리즈 색을 그대로 씁니다. 기본 시리즈 4 `#ECD4A2`(흰색 대비 1.45:1)·5 `#9A9284`(3.08:1)는 4.5:1 미만입니다. 시리즈 색은 유지하며 Label 색 정책은 별도 결정입니다.
 - `@hm-design/chart/examples`의 `ExampleCard`는 공개 Export가 아닙니다(예제 카드를 통해서만 사용).
@@ -34,6 +34,14 @@
  --hm-chart-axis-text: var(--hm-sem-fg-secondary);
  --hm-chart-center-value: var(--hm-sem-fg-primary);
  --hm-chart-font-family: var(--hm-font-family-base);
+
+  /* Inactive track of the radial charts and the hover band behind horizontal bars: a warm neutral one step darker than the
+     muted background, so it stays visible on white and on the warm content background (#F5F0E5) without competing with data. */
+  --hm-chart-track: var(--hm-sem-palette-warm-neutral-light);
+  /* The surface the chart sits on. Gaps between slices / segments, the ring around point Dots, label halos and the circle that
+     cuts the radial meter track into a ring use it, so they read as background. White by default (charts on a card); a chart
+     placed directly on another background sets it on its container, e.g. --hm-chart-surface: var(--hm-sem-bg-content). */
+  --hm-chart-surface: var(--hm-sem-bg-surface);
 }

 [data-slot="chart"] {
@@ -53,6 +61,12 @@
  stroke: var(--hm-chart-grid-color);
  stroke-opacity: 0.6;
 }
+/* Track and hover band. The official chart.tsx paints both with `muted` (#F4F1EA), which disappears on the content background;
+   this unlayered rule wins over its layered utilities, so the official source stays unchanged. */
+[data-slot="chart"] .recharts-radial-bar-background-sector,
+[data-slot="chart"] .recharts-rectangle.recharts-tooltip-cursor {
+  fill: var(--hm-chart-track);
+}

 [data-slot="chart-tooltip-content"] {
  border: 1px solid var(--hm-chart-tooltip-border-color);
@@ -87,10 +101,12 @@
 }

 /* Horizontal bar chart labels. The item name sits on a gradient that starts at 30% of the series color, so the dark text gets
-   a light halo (the card surface) to stay readable from the faint left end to the opaque right end. */
+   a light halo (the chart surface) to stay readable from the faint left end to the opaque right end.
+   --hm-chart-bar-name-halo stays an optional override, but it is no longer declared here: a value declared on :root would resolve
+   --hm-chart-surface there, so a container that sets --hm-chart-surface would not reach the halo. The rules below fall back to
+   --hm-chart-surface (white by default, the same color as before). */
 :root, [data-hm-theme] {
  --hm-chart-bar-name-text: var(--hm-sem-fg-primary);
-  --hm-chart-bar-name-halo: var(--hm-sem-bg-surface);
  --hm-chart-bar-value-text: var(--hm-sem-fg-primary);
 }
 [data-slot="chart-bar-name"],
@@ -101,7 +117,7 @@
 }
 [data-slot="chart-bar-name"] {
  fill: var(--hm-chart-bar-name-text);
-  stroke: var(--hm-chart-bar-name-halo);
+  stroke: var(--hm-chart-bar-name-halo, var(--hm-chart-surface));
  stroke-width: 3px;
  stroke-linejoin: round;
  paint-order: stroke;
@@ -136,7 +152,7 @@
 }
 [data-slot="chart-slice-label"] {
  fill: var(--hm-chart-bar-name-text);
-  stroke: var(--hm-chart-bar-name-halo);
+  stroke: var(--hm-chart-bar-name-halo, var(--hm-chart-surface));
  stroke-width: 3px;
  stroke-linejoin: round;
  paint-order: stroke;
@@ -153,7 +169,7 @@
 /* Radial: item names curved along the start of each bar. The halo keeps the text readable on pale bar colors. */
 .hm-radial-name {
  fill: var(--hm-chart-bar-name-text);
-  stroke: var(--hm-chart-bar-name-halo);
+  stroke: var(--hm-chart-bar-name-halo, var(--hm-chart-surface));
  stroke-width: 2px;
  stroke-linejoin: round;
  paint-order: stroke;
@@ -165,7 +165,7 @@ export function HMDonutChart({ data, totalLabel, activeId, onActiveChange, label
          // Room for the active slice to grow outwards without leaving the chart.
          outerRadius={ring.outer}
          paddingAngle={paddingAngle(selectable)}
-          stroke="var(--hm-sem-bg-surface)"
+          stroke="var(--hm-chart-surface)"
          strokeWidth={2}
          onClick={onActiveChange ? (_slice, index) => onActiveChange(data[index].id) : undefined}
          shape={(props: PieSectorShapeProps, index: number) => (
@@ -50,7 +50,7 @@ export function PointDot({
      cy={y}
      r={radius}
      fill={pointColor(payload, colorKey, fallback)}
-      stroke="var(--hm-sem-bg-surface)"
+      stroke="var(--hm-chart-surface)"
      strokeWidth={2}
    />
  )
@@ -126,7 +126,7 @@ export function HMPieChart({ data, labels, label, className }: HMPieChartProps)
          dataKey="value"
          nameKey="id"
          outerRadius={outside ? "58%" : "80%"}
-          stroke="var(--hm-sem-bg-surface)"
+          stroke="var(--hm-chart-surface)"
          strokeWidth={2}
          label={
            outside ? <PieOutsideLabel items={data} /> : labels === "inside" ? <PieSliceLabel items={data} /> : false
@@ -185,8 +185,8 @@ export function HMStackedPieChart({ rings, label, className }: HMStackedPieChart
      <PieChart accessibilityLayer>
        <ChartTooltip content={<RingTooltip />} />
        <ChartLegend itemSorter={null} content={<RingLegend rings={rings} items={items} />} />
-        <Pie data={slices[0]} dataKey="value" nameKey="id" outerRadius="46%" stroke="var(--hm-sem-bg-surface)" strokeWidth={2} />
-        <Pie data={slices[1]} dataKey="value" nameKey="id" innerRadius="54%" outerRadius="76%" stroke="var(--hm-sem-bg-surface)" strokeWidth={2} />
+        <Pie data={slices[0]} dataKey="value" nameKey="id" outerRadius="46%" stroke="var(--hm-chart-surface)" strokeWidth={2} />
+        <Pie data={slices[1]} dataKey="value" nameKey="id" innerRadius="54%" outerRadius="76%" stroke="var(--hm-chart-surface)" strokeWidth={2} />
      </PieChart>
    </ChartContainer>
  )
@@ -193,12 +193,12 @@ export function HMRadialMeterChart({
  return (
    <ChartContainer config={config} role="group" aria-label={label} className={cn(CHART_BOX, className)}>
      <RadialBarChart data={[row]} startAngle={startAngle} endAngle={endAngle} innerRadius={innerRadius} outerRadius={outerRadius}>
-        {/* Official: the first circle is the muted track, the second (smaller) one is the surface color that cuts it into a ring. */}
+        {/* Official: the first circle is the track (official muted, HM --hm-chart-track), the second (smaller) one is the chart surface color that cuts it into a ring. */}
        <PolarGrid
          gridType="circle"
          radialLines={false}
          stroke="none"
-          className="first:fill-muted last:fill-[var(--hm-sem-bg-surface)]"
+          className="first:fill-[var(--hm-chart-track)] last:fill-[var(--hm-chart-surface)]"
          polarRadius={[...trackRadii]}
        />
        <PolarAngleAxis type="number" domain={[0, maxOf([item.value])]} tick={false} axisLine={false} />
@@ -269,7 +269,7 @@ export function HMRadialStackedChart({
              stackId="a"
              fill={`var(--color-${item.key})`}
              cornerRadius={5}
-              stroke="var(--hm-sem-bg-surface)"
+              stroke="var(--hm-chart-surface)"
              strokeWidth={2}
            />
          ))}
@@ -89,7 +89,7 @@ function SolidSlice({ sector, hole, sideColor, topColor, center }: SolidSlicePro
  const frontTo = Math.min(to, 360)
  const backFrom = Math.max(from, 0)
  const backTo = Math.min(to, 180)
-  const seam = "var(--hm-sem-bg-surface)"
+  const seam = "var(--hm-chart-surface)"
  // The seam between slices is a surface-colored stroke; on a very thin slice it thins out so the slice stays visible.
  const arcPx = (to - from) * RAD * p.rx
  const seamTop = arcPx < 4 ? 0.5 : arcPx < 10 ? 1 : 2