@mindlogic-ai/logician-ui 5.0.0-alpha.2 → 5.0.0-alpha.4

package/src/components/Input/Input.usage.mdx

@@ -0,0 +1,278 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as InputStories from './Input.stories';
+
+<Meta of={InputStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# Input
+
+A single-line text field: names, email addresses, amounts, search terms.
+
+## When to use
+
+- One line of free text the user types: a name, an email address, a URL.
+- A number the user types exactly, such as a credit limit. Use
+  `type="number"` with `maskNumber` to show thousands separators.
+- A search or filter box, with a `leftIcon`.
+
+## When not to use
+
+- More than one line, or text that wraps → `Textarea`.
+- A password or secret → `PasswordInput`.
+- A short one-time code typed box by box → `PinInput`.
+- A choice from a known list → `SelectField`, `ComboboxField`, `Radio`.
+- A date or month → `SingleDatePicker`, `RangeDatePicker`, `MonthPicker`.
+- A rough value on a scale, where the exact number does not matter → `Slider`.
+
+## Props that change behaviour
+
+</En>
+
+<Ko>
+
+# Input
+
+한 줄짜리 텍스트 입력란입니다. 이름, 이메일 주소, 금액, 검색어에 씁니다.
+
+## 언제 쓰나요
+
+- 사용자가 직접 입력하는 한 줄짜리 텍스트: 이름, 이메일 주소, URL.
+- 정확하게 입력해야 하는 숫자(예: 크레딧 한도). 천 단위 쉼표가 필요하면
+  `type="number"`와 `maskNumber`를 함께 씁니다.
+- 검색창이나 필터 입력란. 이때는 `leftIcon`에 아이콘을 넣습니다.
+
+## 언제 쓰지 않나요
+
+- 두 줄 이상이거나 줄바꿈이 필요한 글은 `Textarea`를 씁니다.
+- 비밀번호나 비밀 값은 `PasswordInput`을 씁니다.
+- 한 칸에 한 글자씩 넣는 짧은 인증 코드는 `PinInput`을 씁니다.
+- 정해진 목록에서 고르는 값은 `SelectField`, `ComboboxField`, `Radio`를 씁니다.
+- 날짜나 월은 `SingleDatePicker`, `RangeDatePicker`, `MonthPicker`를 씁니다.
+- 정확한 숫자보다 대략적인 위치가 중요한 값은 `Slider`를 씁니다.
+
+## 동작을 바꾸는 속성
+
+</Ko>
+
+<ArgTypes
+  of={InputStories}
+  include={[
+    'maskNumber',
+    'trimWhiteSpace',
+    'noSpaces',
+    'invalid',
+    'leftIcon',
+    'rightIcon',
+  ]}
+/>
+
+<En>
+
+| Prop             | What it does                                                                                                                  | Use for                                                                |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| `maskNumber`     | Only with `type="number"`. Renders a text input that shows `2,000,000` while `onChange` receives the digits (`2000000`).      | Amounts, limits, counts                                                |
+| `noSpaces`       | Blocks the space key and strips every space, including pasted ones.                                                           | Email addresses, IDs, codes                                            |
+| `trimWhiteSpace` | Blocks a leading space and trims **both ends on every keystroke**, so a space between two words cannot be typed, only pasted. | Single-word values only. Never names or titles; trim at submit instead |
+| `invalid`        | Red border only. It does not tell assistive technology anything; see Accessibility.                                           | With `FieldRow` `error`                                                |
+| `readOnly`       | `bg.subtle` fill and muted text. The value can still be selected and copied.                                                  | Values the user may see but not change                                 |
+| `disabled`       | The fixed `disabled.*` pair, not reduced opacity.                                                                             | A field that does not apply right now                                  |
+
+Good to know:
+
+- While a Korean IME is composing, Enter is swallowed, so a half-typed syllable
+  never submits the form.
+- `onKeyDown` is only called for Enter. Listen on a wrapper if you need other
+  keys.
+- On touch devices the text is raised to 16px so iOS Safari does not zoom the
+  page on focus.
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+| 속성             | 하는 일                                                                                                                             | 쓰는 곳                                                                            |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `maskNumber`     | `type="number"`와 함께일 때만 동작합니다. 화면에는 `2,000,000`으로 보이고 `onChange`에는 숫자만(`2000000`) 전달됩니다.              | 금액, 한도, 개수                                                                   |
+| `noSpaces`       | 스페이스 키를 막고, 붙여 넣은 내용까지 모든 공백을 지웁니다.                                                                        | 이메일 주소, 아이디, 코드                                                          |
+| `trimWhiteSpace` | 맨 앞 공백을 막고 **입력할 때마다 앞뒤 공백을 지웁니다.** 그래서 단어 사이 공백은 타이핑으로 넣을 수 없고 붙여 넣기로만 들어갑니다. | 한 단어짜리 값에만 씁니다. 이름이나 제목에는 쓰지 말고 제출할 때 공백을 정리합니다 |
+| `invalid`        | 테두리만 빨갛게 바꿉니다. 보조기술에는 아무것도 알리지 않습니다. 접근성 절을 보세요.                                                | `FieldRow`의 `error`와 함께                                                        |
+| `readOnly`       | `bg.subtle` 배경에 흐린 글자로 바뀝니다. 값을 선택하고 복사할 수는 있습니다.                                                        | 보여 주되 바꾸면 안 되는 값                                                        |
+| `disabled`       | 투명도를 낮추지 않고 고정된 `disabled.*` 색 한 쌍을 씁니다.                                                                         | 지금은 해당하지 않는 입력란                                                        |
+
+알아 두면 좋은 점
+
+- 한글 입력기로 글자를 조합하는 동안에는 Enter를 무시합니다. 조합 중인 글자 때문에 폼이
+  제출되지 않습니다.
+- `onKeyDown`은 Enter를 눌렀을 때만 호출됩니다. 다른 키가 필요하면 바깥 요소에서
+  받습니다.
+- 터치 기기에서는 글자를 16px로 키워 iOS Safari가 초점을 받을 때 화면을 확대하지 않게
+  합니다.
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={InputStories.DoLabelAbove} />
+<Verdict
+  kind="do"
+  en="Put a visible label above the field with FieldRow. The label stays while the user types, and FieldRow connects it to the input."
+  ko="FieldRow로 입력란 위에 보이는 라벨을 둡니다. 라벨은 입력하는 동안에도 남아 있고, FieldRow가 라벨과 입력란을 연결합니다."
+/>
+
+<Canvas of={InputStories.DontPlaceholderAsLabel} />
+<Verdict
+  kind="dont"
+  en="Use the placeholder as the label. It disappears on the first keystroke, and the field has no name for a screen reader."
+  ko="플레이스홀더를 라벨 대신 쓰지 마세요. 첫 글자를 입력하면 사라지고, 화면 낭독기에는 입력란의 이름이 없습니다."
+/>
+
+<Canvas of={InputStories.DoErrorInWords} />
+<Verdict
+  kind="do"
+  en="Pass the message to FieldRow error. The field turns invalid for assistive technology too, and the message is read with it."
+  ko="오류 문구는 FieldRow의 error에 넘깁니다. 보조기술에도 오류 상태가 전달되고, 입력란과 함께 문구가 읽힙니다."
+/>
+
+<Canvas of={InputStories.DontBorderOnly} />
+<Verdict
+  kind="dont"
+  en="Signal an error with the red border alone. Colour is the only cue, and nothing says what to fix (WCAG 1.4.1, 3.3.1)."
+  ko="빨간 테두리만으로 오류를 알리지 마세요. 색 말고는 단서가 없고, 무엇을 고쳐야 하는지도 알 수 없습니다(WCAG 1.4.1, 3.3.1)."
+/>
+
+<Canvas of={InputStories.DoMaskedAmount} />
+<Verdict
+  kind="do"
+  en="Use type='number' with maskNumber for amounts. The reader sees separators; your form state keeps plain digits."
+  ko="금액에는 type='number'와 maskNumber를 씁니다. 화면에는 쉼표가 보이고, 폼 상태에는 숫자만 남습니다."
+/>
+
+<Canvas of={InputStories.DoCountWithLimit} />
+<Verdict
+  kind="do"
+  en="When you set maxLength, show the count with MaxLengthIndicator in the label row, so the limit is not a surprise."
+  ko="maxLength를 정했다면 라벨 줄에 MaxLengthIndicator로 글자 수를 보여 줍니다. 그래야 제한에 걸려도 당황하지 않습니다."
+/>
+
+<En>
+
+## Content
+
+- Label: a noun phrase in sentence case, no colon ("Work email", not
+  "Work Email:"). Korean labels are nouns too: 업무용 이메일, not 이메일을
+  입력하세요.
+- Placeholder: an example of the format (`name@company.com`), never the label
+  and never an instruction the user needs after they start typing.
+- Helper text: one sentence on what happens with the value or which format is
+  accepted. Put it in `FieldRow` `helperText`, not in the placeholder.
+- Error text: say what is wrong and how to fix it, in one sentence: 이메일 주소
+  형식이 아닙니다.
+
+## Accessibility
+
+What Input does for you:
+
+- Renders a native `<input>`, so Tab, typing, selection and copy and paste
+  work as the browser provides.
+- Shows a visible focus state: a `primary.main` border and 1px ring (WCAG
+  2.4.7).
+- Inside `FormControl` or `FieldRow` it takes the field's id, so the label is
+  associated, and it picks up `aria-invalid`, `required` and the
+  `aria-describedby` that points at helper and error text.
+
+What you still have to do:
+
+- **Name every field.** Use `FieldRow` `label` or `FormControl` + `FormLabel`.
+  A placeholder is not a name, and an icon is not either (WCAG 4.1.2; KWCAG
+  5.3.4.1 레이블 제공).
+- **Mark errors on the field, not on the input.** The `invalid` prop changes
+  the border only. Set `error` on `FieldRow` (or `invalid` on `FormControl`)
+  so the state and the message reach assistive technology (WCAG 3.3.1).
+- **Say what the field is for** with `type` and `autoComplete` (`email`,
+  `name`, `tel`), so browsers and assistive tools can fill it (WCAG 1.3.5).
+- An icon-only `rightIcon` that does something (clear, search) has to be a
+  button with an `aria-label`. A decorative `leftIcon` gets `aria-hidden`.
+
+## Tokens
+
+Input has no styles file; the table follows the values in `Input.tsx`, which
+`Select.styles.ts` mirrors.
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 라벨: 문장형 대소문자의 명사구로 쓰고 쌍점을 붙이지 않습니다("Work email",
+  "Work Email:"이 아님). 한국어 라벨도 명사로 씁니다. "이메일을 입력하세요"가 아니라
+  "업무용 이메일"입니다.
+- 플레이스홀더: 형식의 예(`name@company.com`)만 씁니다. 라벨을 대신하지 않고, 입력을
+  시작한 뒤에도 필요한 안내를 넣지 않습니다.
+- 도움말: 값이 어디에 쓰이는지나 받는 형식을 한 문장으로 씁니다. 플레이스홀더가 아니라
+  `FieldRow`의 `helperText`에 넣습니다.
+- 오류 문구: 무엇이 잘못됐고 어떻게 고치는지 한 문장으로 씁니다. 예: 이메일 주소
+  형식이 아닙니다.
+
+## 접근성
+
+Input이 알아서 하는 일
+
+- 네이티브 `<input>`을 그리므로 Tab 이동, 입력, 선택, 복사와 붙여 넣기가 브라우저
+  기본대로 동작합니다.
+- 초점을 받으면 `primary.main` 테두리와 1px 링으로 눈에 띄게 표시합니다(WCAG 2.4.7).
+- `FormControl`이나 `FieldRow` 안에 두면 필드의 id를 받아 라벨과 연결되고,
+  `aria-invalid`, `required`, 도움말과 오류 문구를 가리키는 `aria-describedby`도
+  함께 받습니다.
+
+직접 챙겨야 하는 일
+
+- **모든 입력란에 이름을 붙입니다.** `FieldRow`의 `label`이나 `FormControl`과
+  `FormLabel`을 씁니다. 플레이스홀더나 아이콘은 이름이 아닙니다(WCAG 4.1.2, KWCAG
+  5.3.4.1 레이블 제공).
+- **오류는 입력란이 아니라 필드에 표시합니다.** `invalid` 속성은 테두리만 바꿉니다.
+  `FieldRow`에 `error`를 넘기거나 `FormControl`에 `invalid`를 주어야 오류 상태와 문구가
+  보조기술에 전달됩니다(WCAG 3.3.1).
+- **입력란의 용도를 밝힙니다.** `type`과 `autoComplete`(`email`, `name`, `tel`)를
+  지정하면 브라우저와 보조 도구가 값을 채워 줄 수 있습니다(WCAG 1.3.5).
+- 지우기나 검색처럼 동작하는 `rightIcon`은 `aria-label`이 있는 버튼이어야 합니다.
+  꾸밈용 `leftIcon`에는 `aria-hidden`을 붙입니다.
+
+## 토큰
+
+Input에는 스타일 파일이 없습니다. 아래 표는 `Input.tsx`에 적힌 값을 따르며,
+`Select.styles.ts`도 같은 값을 씁니다.
+
+</Ko>
+
+<Canvas of={InputStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **FieldRow** / **FormControl**: label, helper text and error around the
+  field.
+- **Textarea**, **PasswordInput**, **PinInput**: other text entry.
+- **SelectField** / **ComboboxField**: a choice from a list.
+- **MaxLengthIndicator**: the character count next to the label.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **FieldRow** / **FormControl**: 입력란을 둘러싼 라벨, 도움말, 오류 문구.
+- **Textarea**, **PasswordInput**, **PinInput**: 다른 텍스트 입력.
+- **SelectField** / **ComboboxField**: 목록에서 고르는 값.
+- **MaxLengthIndicator**: 라벨 옆 글자 수 표시.
+
+</Ko>

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

@@ -22,19 +22,20 @@ 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) => {
-      expect(
-        contrast(seriesColor(i + 1, '', false), '#FFFFFF')
-      ).toBeGreaterThanOrEqual(3);
-      expect(
-        contrast(seriesColor(i + 1, '', true), '#1F1E1D')
-      ).toBeGreaterThanOrEqual(3);
+    [undefined, ...CHART_SERIES_HUES].forEach((_, i) => {
+      expect(contrast(seriesColor(i, false), '#FFFFFF')).toBeGreaterThanOrEqual(
+        3
+      );
+      expect(contrast(seriesColor(i, true), '#1F1E1D')).toBeGreaterThanOrEqual(
+        3
+      );
     });
   });
 });