@mindlogic-ai/logician-ui 5.0.0-alpha.3 → 5.0.0-alpha.30

package/src/components/LineGraph/LineGraph.stories.tsx

@@ -1,6 +1,10 @@
+import { Fragment } from 'react';
+import { Box, Grid } from '@chakra-ui/react';
 import type { Meta, StoryObj } from '@storybook/react';
 
+import { TokenTable } from '../../guidelines/_components/TokenTable';
 import { LineGraph } from '.';
+import { CHART_SERIES_HUES, seriesColor } from './seriesColors';
 import type { DatumBase } from './LineGraph.types';
 
 type TestDataType = {
@@ -105,3 +109,111 @@ export const CustomColors: Story = {
     ],
   },
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `LineGraph.usage.mdx` with <Canvas of={…} />. Hidden from the
+// sidebar (`!dev`); `tags` is written out on each story because the indexer
+// reads CSF statically.
+
+type DailyType = { 질문?: number; 답변실패?: number };
+
+const DAILY: Array<{ name: string } & DailyType> = [
+  { name: '10/16', 질문: 120, 답변실패: 9 },
+  { name: '10/17', 질문: 148, 답변실패: 12 },
+  { name: '10/18', 질문: 96, 답변실패: 4 },
+  { name: '10/19', 질문: 60, 답변실패: 3 },
+  { name: '10/20', 질문: 171, 답변실패: 15 },
+  { name: '10/21', 질문: 188, 답변실패: 11 },
+  { name: '10/22', 질문: 164, 답변실패: 8 },
+];
+
+export const DoDefaultSeriesColours: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: default series colours, a trend over time',
+  render: () => (
+    <LineGraph<DailyType>
+      h="280px"
+      data={DAILY}
+      dataKeys={[
+        { key: '질문', label: '질문 수' },
+        { key: '답변실패', label: '답변하지 못한 질문' },
+      ]}
+    />
+  ),
+};
+
+export const DontStatusColours: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: status colours for ordinary series",
+  render: () => (
+    <LineGraph<DailyType>
+      h="280px"
+      data={DAILY}
+      dataKeys={[
+        {
+          key: '질문',
+          label: '질문 수',
+          color: 'var(--chakra-colors-success-fg)',
+        },
+        {
+          key: '답변실패',
+          label: '답변하지 못한 질문',
+          color: 'var(--chakra-colors-danger-fg)',
+        },
+      ]}
+    />
+  ),
+};
+
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={[
+        { token: 'primary.main', use: 'series 1' },
+        { token: 'border.default', use: 'grid lines, tooltip border' },
+        { token: 'fg.muted', use: 'axis labels' },
+        { token: 'bg.surface', use: 'tooltip background' },
+        { token: 'fg.default', use: 'tooltip text' },
+      ]}
+    />
+  ),
+};
+
+/**
+ * Default stroke for series 2 onwards, light and dark, computed with the same
+ * `seriesColor` the chart calls.
+ */
+export const UsageSeriesOrder: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Series order',
+  render: () => (
+    <Grid templateColumns="auto auto auto" gap={2} fontSize="13px">
+      {CHART_SERIES_HUES.map(({ hue }, i) => (
+        <Fragment key={hue}>
+          <Box fontFamily="mono">
+            {i + 2}. {hue}
+          </Box>
+          {[false, true].map((dark) => {
+            const stroke = seriesColor(i + 1, dark);
+            return (
+              <Box
+                key={String(dark)}
+                style={{ background: stroke }}
+                w="88px"
+                h="20px"
+                borderRadius="sm"
+                title={`${hue} ${dark ? 'dark' : 'light'} ${stroke}`}
+              />
+            );
+          })}
+        </Fragment>
+      ))}
+    </Grid>
+  ),
+};

package/src/components/LineGraph/LineGraph.tsx

@@ -21,10 +21,9 @@ export const LineGraph = <T extends DatumBase>({
   displayLegend = true,
   ...rest
 }: LineGraphProps<T>) => {
-  const primaryColor = useToken('colors', 'primary.main')[0];
-  // Series 1 is the neutral brand line; further series cycle hues with no
-  // status meaning (see seriesColors.ts). Strokes read the generated palette
-  // directly because no semantic role fits a chart line.
+  // Series 1 is the data blue; further series cycle hues with no status
+  // meaning (see seriesColors.ts). Strokes read the generated palette directly
+  // because no semantic role fits a chart line.
   const { colorMode } = useColorMode();
   const isDark = colorMode === 'dark';
   return (
@@ -100,7 +99,7 @@ export const LineGraph = <T extends DatumBase>({
               type="monotone"
               dataKey={key}
               name={label}
-              stroke={color ?? seriesColor(index, primaryColor, isDark)}
+              stroke={color ?? seriesColor(index, isDark)}
               dot={{ r: 0 }}
             />
           ))}

package/src/components/LineGraph/LineGraph.types.ts

@@ -2,8 +2,14 @@ import { BoxProps } from '@chakra-ui/react';
 import { type DataKey as RechartsDataKey } from 'recharts/types/util/types.d';
 
 export interface LineGraphProps<T extends DatumBase> extends BoxProps {
+  /** One object per point on the X axis; `name` is the axis label. */
   data: Array<Datum<T>>;
+  /** The series to draw, in order. */
   dataKeys: Array<DataKey<T>>;
+  /**
+   * Show the legend under the chart.
+   * @default true
+   */
   displayLegend?: boolean;
 }
 
@@ -31,12 +37,16 @@ export type DataKey<T extends DatumBase> = {
   key: RechartsDataKey<keyof T>;
 
   /**
-   * Label for the XAxis
+   * Series name, shown in the legend and the tooltip.
    */
   label: string;
 
   /**
-   * Optional custom colors for the series
+   * Stroke colour for this series, passed straight to the SVG (recharts does
+   * not resolve Chakra tokens — use a CSS variable such as
+   * `var(--chakra-colors-category-teal-fg)`). Defaults: series 1 is
+   * `primary.main`, the rest cycle meaning-free category hues
+   * (`CHART_SERIES_HUES`).
    */
   color?: string;
 };

package/src/components/LineGraph/LineGraph.usage.mdx

@@ -0,0 +1,186 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as LineGraphStories from './LineGraph.stories';
+
+<Meta of={LineGraphStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# LineGraph
+
+A line chart (recharts) for one or more numeric series over an ordered X
+axis, usually time: daily questions, usage by model, feedback over a month.
+It ships the house grid, axes, tooltip and series colours, in both modes.
+
+## When to use
+
+- A trend over time or another ordered axis, where the shape matters more
+  than any single value.
+
+## When not to use
+
+- Comparing categories with no order (models, groups) → a bar chart or a
+  `Table`.
+- One number → a stat with `Text`. A share of a whole → a `ProgressBar` or a
+  table of percentages.
+- When the reader needs exact values → a `Table`, with the chart as a
+  summary if at all.
+
+## Props
+
+</En>
+
+<Ko>
+
+# LineGraph
+
+순서가 있는 X축(대개 시간) 위에 숫자 계열 하나 이상을 그리는 꺾은선 그래프(recharts)
+입니다. 일별 질문 수, 모델별 사용량, 한 달 동안의 피드백에 씁니다. 격자, 축, 툴팁,
+계열 색이 두 모드 모두에 맞춰져 있습니다.
+
+## 언제 쓰나요
+
+- 값 하나하나보다 흐름의 모양이 중요한, 시간이나 순서가 있는 축 위의 추세.
+
+## 언제 쓰지 않나요
+
+- 순서가 없는 항목(모델, 그룹) 비교에는 막대 그래프나 `Table`을 씁니다.
+- 숫자 하나는 `Text`로 보여 줍니다. 전체 중 비율은 `ProgressBar`나 비율 표를 씁니다.
+- 정확한 값이 필요하다면 `Table`을 쓰고, 그래프는 요약으로만 씁니다.
+
+## 속성
+
+</Ko>
+
+<ArgTypes of={LineGraphStories} include={['data', 'dataKeys', 'displayLegend']} />
+
+<En>
+
+**Series colours.** Series 1 is the data blue (`blue.base`), the same blue a
+single-measure chart uses. Series 2 onwards cycle eight category hues that
+carry no meaning, alternating cool and warm (teal, pink, indigo, purple,
+brown, …). Red, yellow and green are left out, because they mean danger,
+warning and success. Every default stroke clears 3:1 against the page in both modes.
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+**계열 색.** 첫 계열은 데이터 파랑(`blue.base`)으로, 측정값이 하나인 차트와 같은 색입니다.
+둘째 계열부터는 뜻이 없는 category 색 여덟 가지를 차가운 색과 따뜻한 색이 번갈아 오도록
+돌아가며 씁니다(청록, 분홍, 남색, 보라, 갈색 …). 빨강, 노랑, 초록은 위험, 경고, 성공을
+뜻하므로 빠져 있습니다. 기본 선 색은 두 모드 모두에서 바탕과 3:1 이상입니다.
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={LineGraphStories.DoDefaultSeriesColours} />
+<Verdict
+  kind="do"
+  en="Keep the default series colours and name each series in words; the legend and the tooltip show the label."
+  ko="기본 계열 색을 그대로 쓰고 계열마다 이름을 붙입니다. 범례와 툴팁에 그 이름이 나옵니다."
+/>
+
+<Canvas of={LineGraphStories.DontStatusColours} />
+<Verdict
+  kind="dont"
+  en="Colour ordinary series with success and danger. Readers take the red line as an error even when the numbers are fine."
+  ko="일반 계열에 success와 danger 색을 쓰지 마세요. 숫자에 문제가 없어도 읽는 사람은 빨간 선을 오류로 받아들입니다."
+/>
+
+<En>
+
+## Content
+
+- Name series in words the reader uses (질문 수), not field names (`uv`).
+- X labels short: 10/22, not 2026-10-22 00:00.
+- Two or three series at most; split into several charts beyond that.
+
+## Accessibility
+
+What LineGraph does for you:
+
+- Axis labels, grid and tooltip read CSS variables, so they follow light and
+  dark mode. Default strokes clear 3:1 (WCAG 1.4.11).
+- Series names appear as text in the legend and tooltip.
+
+What you still have to do:
+
+- **Give the chart a text alternative** (WCAG 1.1.1). The SVG has no name.
+  Put a heading and a one-sentence summary next to it (질문 수는 지난주보다
+  12% 늘었습니다), and offer the numbers as a table when they matter.
+- **Lines differ only by colour** (no markers, no dash patterns), so with
+  three or more series the legend alone can be hard to match (WCAG 1.4.1).
+  Keep series few, or label them at the line end.
+- The tooltip appears on pointer hover only; keyboard users cannot reach
+  values (WCAG 2.1.1). Another reason to offer the table.
+
+## Tokens
+
+The chart reads these roles as CSS variables. The default series strokes
+come from the palette, in the order below.
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 계열 이름은 필드 이름(`uv`)이 아니라 읽는 사람이 쓰는 말(질문 수)로 씁니다.
+- X축 라벨은 짧게 씁니다. '2026-10-22 00:00'이 아니라 '10/22'로 씁니다.
+- 계열은 많아야 두세 개로 두고, 더 많으면 그래프를 나눕니다.
+
+## 접근성
+
+LineGraph가 알아서 하는 일
+
+- 축 라벨, 격자, 툴팁이 CSS 변수를 읽으므로 라이트·다크 모드를 따릅니다. 기본 선
+  색은 3:1 이상입니다(WCAG 1.4.11).
+- 계열 이름이 범례와 툴팁에 글자로 나옵니다.
+
+직접 챙겨야 하는 일
+
+- **그래프에 글로 된 대체 내용을 붙입니다**(WCAG 1.1.1). SVG에는 이름이 없습니다.
+  옆에 제목과 한 문장 요약('질문 수는 지난주보다 12% 늘었습니다')을 두고, 숫자가
+  중요하면 표로도 보여 줍니다.
+- **선은 색으로만 구분됩니다**(점 표시나 점선 없음). 계열이 셋 이상이면 범례만으로는
+  짝을 맞추기 어렵습니다(WCAG 1.4.1). 계열 수를 줄이거나 선 끝에 이름을 붙입니다.
+- 툴팁은 마우스를 올려야만 나타나서 키보드 사용자는 값을 볼 수 없습니다(WCAG
+  2.1.1). 이 점에서도 표를 함께 주는 편이 좋습니다.
+
+## 토큰
+
+그래프는 아래 역할을 CSS 변수로 읽습니다. 기본 계열 선 색은 팔레트에서 아래 순서대로
+가져옵니다.
+
+</Ko>
+
+<Canvas of={LineGraphStories.UsageTokens} sourceState="none" />
+
+<Canvas of={LineGraphStories.UsageSeriesOrder} sourceState="none" />
+
+<En>
+
+## Related
+
+- **Table**: exact values, and the accessible alternative to a chart.
+- **ProgressBar** / **RadialProgress**: a single share or progress.
+- **Setup/Theme/Using Semantic Tokens**: "Blue means data and links".
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **Table**: 정확한 값, 그리고 그래프의 접근 가능한 대안.
+- **ProgressBar** / **RadialProgress**: 비율이나 진행률 하나.
+- **Setup/Theme/Using Semantic Tokens**: "Blue means data and links".
+
+</Ko>

package/src/components/LineGraph/seriesColors.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest';
 
-import { SYSTEM_HUES } from '@/theme/palette.generated';
+import { RAMPS, SYSTEM_HUES } from '@/theme/palette.generated';
 
 import { CHART_SERIES_HUES, seriesColor } from './seriesColors';
 
@@ -22,18 +22,19 @@ describe('chart series colours', () => {
     expect(CHART_SERIES_HUES.filter(({ hue }) => banned.has(hue))).toEqual([]);
   });
 
-  it('series 1 is the primary line, series 2 is brown', () => {
-    expect(seriesColor(0, '#252525', false)).toBe('#252525');
-    expect(seriesColor(1, '#252525', false)).toBe(SYSTEM_HUES.brown.base);
+  it('series 1 is the data blue, series 2 is teal', () => {
+    expect(seriesColor(0, false)).toBe(SYSTEM_HUES.blue.base);
+    expect(seriesColor(0, true)).toBe(SYSTEM_HUES.blue.baseDark);
+    expect(seriesColor(1, false)).toBe(SYSTEM_HUES.teal.base);
   });
 
   it('every default stroke clears 3:1 against the page in both modes', () => {
-    CHART_SERIES_HUES.forEach((_, i) => {
+    [undefined, ...CHART_SERIES_HUES].forEach((_, i) => {
+      expect(contrast(seriesColor(i, false), '#FFFFFF')).toBeGreaterThanOrEqual(
+        3
+      );
       expect(
-        contrast(seriesColor(i + 1, '', false), '#FFFFFF')
-      ).toBeGreaterThanOrEqual(3);
-      expect(
-        contrast(seriesColor(i + 1, '', true), '#1F1E1D')
+        contrast(seriesColor(i, true), RAMPS.ink.canvasDark)
       ).toBeGreaterThanOrEqual(3);
     });
   });

package/src/components/LineGraph/seriesColors.ts

@@ -4,12 +4,16 @@ import { SYSTEM_HUES } from '@/theme/palette.generated';
 /**
  * Default stroke order for multi-series charts.
  *
- * Series 1 is the neutral brand line (`primary.main`); the rest cycle hues
- * that carry no meaning in the system. Red, yellow and green are the danger,
- * warning and success colours, and blue is info and links, so none of them
- * may colour a series by default — a red "UV" line reads as an error.
- * (Blue is reserved for data as a whole: a single-measure chart is a blue
- * monochrome ramp — SemanticTokens.mdx, "Blue means data and links".)
+ * Series 1 is the data blue (`blue.base`): blue means data (SemanticTokens.mdx,
+ * "Blue means data and links"), and a single-measure chart draws in the same
+ * blue, so adding a second series does not repaint the first. It used to be
+ * the ink `primary.main`, which read as body text rather than as data.
+ *
+ * The rest cycle hues that carry no meaning in the system, alternating cool
+ * and warm so neighbouring lines separate. Red, yellow and green are the
+ * danger, warning and success colours, so none of them may colour a series by
+ * default — a red "UV" line reads as an error. Brown comes late: next to the
+ * other dusty warm hues it reads as mud.
  *
  * Every stroke clears 3:1 against the page in both modes. Cyan, mint and
  * orange are too light at their base value in light mode (≈1.9:1), so they
@@ -21,23 +25,21 @@ type SeriesHue = {
 };
 
 export const CHART_SERIES_HUES: readonly SeriesHue[] = [
-  { hue: 'brown', light: 'base' },
-  { hue: 'indigo', light: 'base' },
-  { hue: 'pink', light: 'base' },
   { hue: 'teal', light: 'base' },
+  { hue: 'pink', light: 'base' },
+  { hue: 'indigo', light: 'base' },
   { hue: 'purple', light: 'base' },
+  { hue: 'brown', light: 'base' },
   { hue: 'cyan', light: 'hc' },
   { hue: 'mint', light: 'hc' },
   { hue: 'orange', light: 'hc' },
 ];
 
-/** Stroke for series `index` (0-based); index 0 is the caller's primary line. */
-export const seriesColor = (
-  index: number,
-  primary: string,
-  isDark: boolean
-): string => {
-  if (index === 0) return primary;
+/** Stroke for series `index` (0-based); index 0 is the data blue. */
+export const seriesColor = (index: number, isDark: boolean): string => {
+  if (index === 0) {
+    return isDark ? SYSTEM_HUES.blue.baseDark : SYSTEM_HUES.blue.base;
+  }
   const { hue, light } =
     CHART_SERIES_HUES[(index - 1) % CHART_SERIES_HUES.length];
   return isDark ? SYSTEM_HUES[hue].baseDark : SYSTEM_HUES[hue][light];

package/src/components/Loaders/Loaders.stories.tsx

@@ -0,0 +1,93 @@
+import type { ReactNode } from 'react';
+import { Box } from '@chakra-ui/react';
+import { Meta, StoryObj } from '@storybook/react';
+
+import { T } from '../../guidelines/_components/Lang';
+import { TokenTable } from '../../guidelines/_components/TokenTable';
+import { Card } from '../Card';
+import { Subtext, Text } from '../Typography';
+import { SectionLoader } from './SectionLoader';
+
+/**
+ * Specimens for `Loaders.usage.mdx`, which covers `PageLoader`,
+ * `SectionLoader` and `ThinkingDots` together. Every story here is hidden
+ * (`!dev`): the components' own stories stay under Components/PageLoader and
+ * Components/SectionLoader.
+ */
+const meta = {
+  title: 'Components/Loaders',
+  component: SectionLoader,
+  args: { isLoading: true },
+} satisfies Meta<typeof SectionLoader>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/** A card whose body is loading; the card is the positioned parent. */
+const LoadingCard = ({ children }: { children: ReactNode }) => (
+  <Card p={4} w="320px">
+    <Text fontWeight="bold" mb={2}>
+      멤버
+    </Text>
+    <Box position="relative" h="120px" borderRadius="md" overflow="hidden">
+      <Subtext>홍길동, 김철수, 이영희</Subtext>
+      {children}
+    </Box>
+  </Card>
+);
+
+export const DoSectionLoaderInParent: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: SectionLoader inside a positioned parent',
+  render: () => (
+    <LoadingCard>
+      <SectionLoader isLoading label="멤버 목록을 불러오는 중" />
+    </LoadingCard>
+  ),
+};
+
+export const DoThinkingForAI: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: thinking dots while the AI works',
+  render: () => (
+    <LoadingCard>
+      <SectionLoader
+        isLoading
+        variant="thinking"
+        label="답변을 준비하는 중"
+      />
+    </LoadingCard>
+  ),
+};
+
+/** Tokens the loaders read. */
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={[
+        {
+          token: 'bg.canvas',
+          use: <T en="overlay (PageLoader at 50% opacity)" ko="덮개(PageLoader는 불투명도 50%)" />,
+        },
+        {
+          token: 'primary.main',
+          use: <T en="spinner (default variant)" ko="스피너(기본 변형)" />,
+        },
+        {
+          token: 'bg.track',
+          use: <T en="spinner track" ko="스피너 트랙" />,
+        },
+        {
+          token: 'action.mark',
+          use: <T en="thinking dots" ko="thinking 점" />,
+        },
+      ]}
+    />
+  ),
+};