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

package/src/components/SwapTransition/SwapTransition.usage.mdx

@@ -0,0 +1,102 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle } from '../../guidelines/_components/Lang';
+import * as SwapTransitionStories from './SwapTransition.stories';
+
+<Meta of={SwapTransitionStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# SwapTransition
+
+Swaps one piece of content for another with a short directional slide, for
+moving between steps of a sequence or between records in the same frame.
+
+</En>
+
+<Ko>
+
+# SwapTransition
+
+한 내용을 다른 내용으로 바꿀 때 짧게 옆으로 밀어 넘깁니다. 순서가 있는 단계 사이를
+오가거나, 같은 틀 안에서 다른 항목으로 넘어갈 때 씁니다.
+
+</Ko>
+
+<Canvas of={SwapTransitionStories.Default} />
+
+<En>
+
+## When to use
+
+- Question 1 → question 2 in a quiz or a multi-step flow, keyed on the step
+  index.
+- Moving from an overview screen to the step runner, or between items under
+  review, keyed on the record id.
+- Going back: pass a negative `distance` so the content travels the other way.
+
+## When not to use
+
+- New content is added under existing content rather than replacing it →
+  `Reveal`, or `Appear` if nothing is pushed.
+- A value changes in place → `CountUp` or `Pulse`.
+- The key would change on unrelated re-renders → pick a key that identifies the
+  content (a step index, a record id), or the content swaps with itself.
+
+## Reduced motion and accessibility
+
+- With `prefers-reduced-motion: reduce` both halves take no time and nothing
+  slides. The outgoing content is hidden at once, and the new content appears
+  when the 150ms exit timer ends.
+- While the old content leaves it gets `aria-hidden` and ignores the pointer,
+  so it cannot be read or clicked on its way out.
+- SwapTransition does not move focus. After a step change, move focus to the
+  new step (its heading, or its first field) yourself, so keyboard and
+  screen reader users start in the right place (WCAG 2.4.3).
+- It renders one `div`, and every prop lands on that element, so a wrapper
+  told to fill (`display="flex" flex={1} minH={0}`) still fills.
+
+## Props
+
+</En>
+
+<Ko>
+
+## 언제 쓰나요
+
+- 퀴즈나 여러 단계로 된 흐름에서 1번 문항에서 2번 문항으로 넘어갈 때. 단계 번호를
+  key로 씁니다.
+- 개요 화면에서 단계 진행 화면으로, 또는 검토 중인 항목 사이를 오갈 때. 항목 id를
+  key로 씁니다.
+- 뒤로 갈 때는 `distance`에 음수를 넘겨 반대 방향으로 움직입니다.
+
+## 언제 쓰지 않나요
+
+- 새 내용이 기존 내용을 바꾸지 않고 그 아래에 더해진다면 `Reveal`을 씁니다. 아무것도
+  밀어내지 않는다면 `Appear`를 씁니다.
+- 값이 제자리에서 바뀐다면 `CountUp`이나 `Pulse`를 씁니다.
+- 상관없는 렌더에서도 key가 바뀐다면, 내용을 식별하는 값(단계 번호, 항목 id)으로 key를
+  바꿉니다. 그러지 않으면 같은 내용끼리 서로 바뀌는 애니메이션이 재생됩니다.
+
+## 동작 줄이기와 접근성
+
+- `prefers-reduced-motion: reduce`에서는 나가고 들어오는 동작 모두 시간이 0이라
+  밀리는 움직임이 없습니다. 나가는 내용은 바로 사라지고, 새 내용은 150ms의 퇴장
+  타이머가 끝나면 나타납니다.
+- 나가는 동안 이전 내용에는 `aria-hidden`이 붙고 포인터도 받지 않으므로, 사라지는 중에
+  읽히거나 눌리지 않습니다.
+- SwapTransition은 초점을 옮기지 않습니다. 단계가 바뀌면 새 단계(제목이나 첫 입력란)로
+  직접 초점을 옮겨, 키보드와 화면 낭독기 사용자가 제자리에서 시작하게 합니다(WCAG 2.4.3).
+- `div` 하나만 그리고 모든 속성이 그 요소에 적용됩니다. 그래서 채우도록 지정한 감싸는
+  요소(`display="flex" flex={1} minH={0}`)도 그대로 채웁니다.
+
+## 속성
+
+</Ko>
+
+<ArgTypes
+  of={SwapTransitionStories}
+  include={['transitionKey', 'distance', 'animateInitial']}
+/>

package/src/components/Switch/Switch.stories.tsx

@@ -1,7 +1,10 @@
 import React, { useState } from 'react';
-import { Stack, Text } from '@chakra-ui/react';
+import { Box, Stack, Text } from '@chakra-ui/react';
 import { Meta, StoryObj } from '@storybook/react';
 
+import { T } from '../../guidelines/_components/Lang';
+import { TokenTable } from '../../guidelines/_components/TokenTable';
+import { Checkbox } from '../Checkbox';
 import { Switch } from './Switch';
 
 const meta = {
@@ -22,7 +25,7 @@ export default meta;
 type Story = StoryObj<typeof meta>;
 
 export const Uncontrolled: Story = {
-  render: args => (
+  render: (args) => (
     <Switch {...args}>
       <Switch.Control />
     </Switch>
@@ -34,12 +37,16 @@ export const Uncontrolled: Story = {
 };
 
 export const Controlled: Story = {
-  render: args => {
+  render: (args) => {
     const [checked, setChecked] = useState(false);
 
     return (
       <Stack direction="row" align="center" gap={4}>
-        <Switch {...args} checked={checked} onCheckedChange={e => setChecked(e.checked)}>
+        <Switch
+          {...args}
+          checked={checked}
+          onCheckedChange={(e) => setChecked(e.checked)}
+        >
           <Switch.Control />
         </Switch>
         <Text>{checked ? 'On' : 'Off'}</Text>
@@ -53,7 +60,7 @@ export const Controlled: Story = {
 };
 
 export const Disabled: Story = {
-  render: args => (
+  render: (args) => (
     <Switch {...args}>
       <Switch.Control />
     </Switch>
@@ -66,7 +73,7 @@ export const Disabled: Story = {
 };
 
 export const WithLabel: Story = {
-  render: args => (
+  render: (args) => (
     <Switch {...args}>
       <Switch.Control />
       <Switch.Label>Enable notifications</Switch.Label>
@@ -76,3 +83,121 @@ export const WithLabel: Story = {
     size: 'md',
   },
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `Switch.usage.mdx` with <Canvas of={…} />. Hidden (`!dev`); `tags`
+// is written out on each story because the indexer reads CSF statically.
+
+export const DoSettingRow: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: one setting, label first',
+  render: () => {
+    const [checked, setChecked] = useState(true);
+    return (
+      <Box
+        maxW="480px"
+        borderWidth="1px"
+        borderColor="border.subtle"
+        borderRadius="12px"
+        p={4}
+      >
+        <Switch
+          checked={checked}
+          onCheckedChange={(e) => setChecked(e.checked)}
+          display="flex"
+          justifyContent="space-between"
+          w="100%"
+        >
+          <Switch.Label>
+            <Text as="span" display="block" fontWeight="semibold">
+              상단에 고정
+            </Text>
+            <Text as="span" display="block" color="fg.muted" fontSize="sm">
+              공지 목록 맨 위에 항상 보입니다.
+            </Text>
+          </Switch.Label>
+          <Switch.Control />
+        </Switch>
+      </Box>
+    );
+  },
+};
+
+export const DontStateInLabel: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: put the state in the label",
+  render: () => {
+    const [checked, setChecked] = useState(true);
+    return (
+      <Switch checked={checked} onCheckedChange={(e) => setChecked(e.checked)}>
+        <Switch.Control />
+        <Switch.Label>{checked ? '켜짐' : '꺼짐'}</Switch.Label>
+      </Switch>
+    );
+  },
+};
+
+export const DontSwitchList: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: switches to pick items from a list",
+  render: () => (
+    <Stack gap={2}>
+      {['마케팅팀', '영업팀', '개발팀'].map((team) => (
+        <Switch key={team}>
+          <Switch.Control />
+          <Switch.Label>{team}</Switch.Label>
+        </Switch>
+      ))}
+    </Stack>
+  ),
+};
+
+export const DoCheckboxList: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: checkboxes to pick items',
+  render: () => (
+    <Stack gap={2}>
+      {['마케팅팀', '영업팀', '개발팀'].map((team) => (
+        <Checkbox key={team}>
+          <Checkbox.Control />
+          <Checkbox.Label>{team}</Checkbox.Label>
+        </Checkbox>
+      ))}
+    </Stack>
+  ),
+};
+
+/** Tokens `SwitchControl` reads, as written in `SwitchControl.tsx`. */
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={[
+        { token: 'bg.track', use: <T en="Track when off" ko="꺼짐 트랙" /> },
+        { token: 'primary.main', use: <T en="Track when on" ko="켜짐 트랙" /> },
+        {
+          token: 'bg.surface',
+          use: <T en="Thumb when off" ko="꺼짐 손잡이" />,
+        },
+        {
+          token: 'fg.onPrimary',
+          use: <T en="Thumb when on" ko="켜짐 손잡이" />,
+        },
+        {
+          token: 'disabled.bg',
+          use: <T en="Disabled track" ko="비활성 트랙" />,
+        },
+        {
+          token: 'focus.ring',
+          use: <T en="Keyboard focus ring" ko="키보드 초점 링" />,
+        },
+      ]}
+    />
+  ),
+};

package/src/components/Switch/Switch.usage.mdx

@@ -0,0 +1,199 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as SwitchStories from './Switch.stories';
+
+<Meta of={SwitchStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# Switch
+
+A toggle for one setting that is either on or off.
+
+## When to use
+
+- A single feature or setting the user turns on or off: pin an announcement,
+  show it as a pop-up, enable a connector.
+- A row in a settings list, with the label on the left and the switch at the
+  end.
+
+## When not to use
+
+- Picking items from a list, or several choices that belong together →
+  `Checkbox`.
+- Agreeing to something → `Checkbox`. "On" is not the same as "I agree".
+- One of more than two states → `Radio` or `SelectField`.
+
+## Props
+
+</En>
+
+<Ko>
+
+# Switch
+
+켜거나 끄는 설정 하나를 바꾸는 토글입니다.
+
+## 언제 쓰나요
+
+- 사용자가 켜거나 끄는 기능이나 설정 하나: 공지 상단 고정, 팝업으로 보여 주기, 커넥터
+  사용.
+- 설정 목록의 한 행. 라벨은 왼쪽에, 스위치는 행 끝에 둡니다.
+
+## 언제 쓰지 않나요
+
+- 목록에서 항목을 고르거나, 함께 묶이는 여러 선택은 `Checkbox`를 씁니다.
+- 동의를 받을 때는 `Checkbox`를 씁니다. "켜짐"은 "동의합니다"와 다릅니다.
+- 상태가 셋 이상이라면 `Radio`나 `SelectField`를 씁니다.
+
+## 속성
+
+</Ko>
+
+<ArgTypes
+  of={SwitchStories}
+  include={['checked', 'defaultChecked', 'onCheckedChange', 'disabled', 'size']}
+/>
+
+<En>
+
+Compose it from `<Switch>`, `<Switch.Control />` and `<Switch.Label>`. The
+root is the click target, so the label toggles it too. The thumb settles with
+a small overshoot; under reduced motion it moves without it.
+
+If the change is saved the moment the switch flips, say so on the screen (a
+toast, or a "saved" line). If it is saved with the rest of the form, keep it
+in the form and save on submit, the same as every other field.
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+`<Switch>`, `<Switch.Control />`, `<Switch.Label>`을 조합해서 씁니다. 루트 전체를 눌러도
+되므로 라벨을 눌러도 바뀝니다. 손잡이는 살짝 지나쳤다가 제자리에 멈추고, 동작 줄이기
+설정에서는 그 움직임 없이 옮겨 갑니다.
+
+스위치를 바꾸는 순간 저장된다면 화면에서 그렇게 알려 줍니다(토스트나 "저장됨" 문구).
+폼의 다른 값과 함께 저장된다면 다른 필드처럼 폼 안에 두고 제출할 때 저장합니다.
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={SwitchStories.DoSettingRow} />
+<Verdict
+  kind="do"
+  en="Name the setting in the label, describe its effect in a muted line, and put the switch at the end of the row."
+  ko="라벨에 설정 이름을 쓰고, 효과는 흐린 글자로 한 줄 덧붙이며, 스위치는 행 끝에 둡니다."
+/>
+
+<Canvas of={SwitchStories.DontStateInLabel} />
+<Verdict
+  kind="dont"
+  en="Make the label say the current state. The label should name the setting; the switch already shows the state, and a screen reader announces it."
+  ko="라벨에 현재 상태를 쓰지 마세요. 라벨은 설정의 이름이어야 합니다. 상태는 스위치가 이미 보여 주고, 화면 낭독기도 읽어 줍니다."
+/>
+
+<Canvas of={SwitchStories.DontSwitchList} />
+<Verdict
+  kind="dont"
+  en="Use switches to pick items from a list. Teams are not settings that are on or off."
+  ko="목록에서 항목을 고르는 데 스위치를 쓰지 마세요. 팀은 켜고 끄는 설정이 아닙니다."
+/>
+
+<Canvas of={SwitchStories.DoCheckboxList} />
+<Verdict
+  kind="do"
+  en="Use checkboxes to pick items."
+  ko="항목을 고를 때는 체크박스를 씁니다."
+/>
+
+<En>
+
+## Content
+
+- The label names the setting or feature (상단에 고정), not the action (고정하기)
+  and not the state (켜짐).
+- One muted line under the label says what changes when it is on.
+- No question marks.
+
+## Accessibility
+
+What Switch does for you:
+
+- A native checkbox input carries the state, so Tab focuses it and Space
+  toggles it.
+- The keyboard focus ring shows on the track (WCAG 2.4.7). The off track is
+  `bg.track`, a filled track that stays visible on any surface (WCAG 1.4.11).
+
+What you still have to do:
+
+- **Always render `Switch.Label`** (with `srOnly` if the row's title is
+  elsewhere). Without it the switch has no name (WCAG 4.1.2; KWCAG 5.3.4.1
+  레이블 제공).
+- Position, not colour, shows the state; keep the default thumb so it stays
+  that way (WCAG 1.4.1).
+- If flipping it saves immediately, announce the result (a toast), so the
+  user knows the change was not lost (WCAG 4.1.3).
+
+## Tokens
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 라벨에는 설정이나 기능의 이름을 씁니다(상단에 고정). 동작(고정하기)이나 상태(켜짐)는
+  쓰지 않습니다.
+- 라벨 아래 흐린 글자 한 줄로 켜면 무엇이 달라지는지 씁니다.
+- 물음표를 쓰지 않습니다.
+
+## 접근성
+
+Switch가 알아서 하는 일
+
+- 상태는 네이티브 체크박스 입력이 가지고 있어서 Tab으로 초점을 옮기고 Space로 바꿀 수
+  있습니다.
+- 키보드 초점 링이 트랙에 보입니다(WCAG 2.4.7). 꺼짐 트랙은 어떤 면 위에서도 보이도록
+  채워진 `bg.track`을 씁니다(WCAG 1.4.11).
+
+직접 챙겨야 하는 일
+
+- **`Switch.Label`을 항상 그립니다.** 행 제목이 다른 곳에 있다면 `srOnly`를 줍니다.
+  라벨이 없으면 스위치에 이름이 없습니다(WCAG 4.1.2, KWCAG 5.3.4.1 레이블 제공).
+- 상태는 색이 아니라 손잡이 위치로 드러납니다. 기본 손잡이를 그대로 두어 이 점을
+  지킵니다(WCAG 1.4.1).
+- 바꾸는 즉시 저장된다면 토스트 등으로 결과를 알려, 바뀐 내용이 사라지지 않았다는 것을
+  알 수 있게 합니다(WCAG 4.1.3).
+
+## 토큰
+
+</Ko>
+
+<Canvas of={SwitchStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **Checkbox**: picking items, agreeing.
+- **Radio** / **SelectField**: more than two states.
+- **Toast**: confirming a change that saved immediately.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **Checkbox**: 항목 고르기, 동의.
+- **Radio** / **SelectField**: 상태가 셋 이상일 때.
+- **Toast**: 바로 저장된 변경 알림.
+
+</Ko>

package/src/components/Table/Table.stories.tsx

@@ -2,9 +2,13 @@ import { useState } from 'react';
 import { Flex } from '@chakra-ui/react';
 import { Meta, StoryObj } from '@storybook/react';
 
+import { TokenTable } from '../../guidelines/_components/TokenTable';
+import { tableSlotRecipe } from '../../theme/recipes/table';
+import { Badge } from '../Badge';
 import { Button } from '../Button';
 import { IoChevronDownOutline } from '../Icon';
 import { IconButton } from '../IconButton';
+import { Link } from '../Typography';
 import {
   ExpandingTr,
   Table,
@@ -126,7 +130,7 @@ export const Default: Story = {
 /**
  * Rows that receive `onClick` (or `role="button"` / `tabIndex`) automatically
  * get the interactive treatment from the table recipe: pointer cursor,
- * `bg.muted` hover, and a focus-visible outline. Static rows never highlight.
+ * `primary.wash` hover, and a focus-visible outline. Static rows never highlight.
  */
 export const InteractiveRows: Story = {
   render: (args) => (
@@ -699,3 +703,157 @@ export const StickyOffsetsSurvivePagination: Story = {
   args: { width: '220%' },
   argTypes: {},
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `Table.usage.mdx` with <Canvas of={…} />. Hidden from the
+// sidebar (`!dev`); `tags` is written out on each story because the indexer
+// reads CSF statically.
+
+const USAGE_ROWS = [
+  { name: '김지민', group: '마케팅', credits: 12480, status: 'ok' },
+  { name: '이서준', group: '영업', credits: 830, status: 'ok' },
+  { name: '박하은', group: '개발', credits: 0, status: 'invalid' },
+] as const;
+
+export const DoNumbersAligned: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: a link in the name cell, numbers aligned to the end',
+  render: () => (
+    <TableContainer maxW="520px">
+      <Table>
+        <Thead>
+          <Tr>
+            <Th>이름</Th>
+            <Th>그룹</Th>
+            <Th textAlign="end">사용 크레딧</Th>
+          </Tr>
+        </Thead>
+        <Tbody>
+          {USAGE_ROWS.map((row) => (
+            <Tr key={row.name}>
+              <Td>
+                <Link href={`#member-${row.name}`}>{row.name}</Link>
+              </Td>
+              <Td>{row.group}</Td>
+              <Td textAlign="end" fontVariantNumeric="tabular-nums">
+                {row.credits.toLocaleString('ko-KR')}
+              </Td>
+            </Tr>
+          ))}
+        </Tbody>
+      </Table>
+    </TableContainer>
+  ),
+};
+
+export const DoStateWithWords: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: a row state backed by words',
+  render: () => (
+    <TableContainer maxW="520px">
+      <Table>
+        <Thead>
+          <Tr>
+            <Th>이름</Th>
+            <Th>상태</Th>
+          </Tr>
+        </Thead>
+        <Tbody>
+          {USAGE_ROWS.map((row) => (
+            <Tr
+              key={row.name}
+              state={row.status === 'invalid' ? 'invalid' : undefined}
+            >
+              <Td>{row.name}</Td>
+              <Td>
+                {row.status === 'invalid' ? (
+                  <Badge variant="danger">이메일 오류</Badge>
+                ) : (
+                  <Badge variant="success">정상</Badge>
+                )}
+              </Td>
+            </Tr>
+          ))}
+        </Tbody>
+      </Table>
+    </TableContainer>
+  ),
+};
+
+export const DontStateColourOnly: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: a tinted row with no words",
+  render: () => (
+    <TableContainer maxW="520px">
+      <Table>
+        <Thead>
+          <Tr>
+            <Th>이름</Th>
+            <Th>그룹</Th>
+          </Tr>
+        </Thead>
+        <Tbody>
+          {USAGE_ROWS.map((row) => (
+            <Tr
+              key={row.name}
+              state={row.status === 'invalid' ? 'invalid' : undefined}
+            >
+              <Td>{row.name}</Td>
+              <Td>{row.group}</Td>
+            </Tr>
+          ))}
+        </Tbody>
+      </Table>
+    </TableContainer>
+  ),
+};
+
+/**
+ * Every colour token in the table slot recipe (`theme/recipes/table.ts`),
+ * collected by walking the recipe, so a recipe change shows up here.
+ */
+const recipeTokens = (
+  node: unknown,
+  path: string[] = []
+): { token: string; use: string }[] => {
+  if (typeof node === 'string') {
+    return /^[a-z]+(\.[a-zA-Z0-9]+)+$/.test(node)
+      ? [{ token: node, use: path.join(' › ') }]
+      : [];
+  }
+  if (node && typeof node === 'object') {
+    return Object.entries(node).flatMap(([key, value]) =>
+      recipeTokens(value, [...path, key])
+    );
+  }
+  return [];
+};
+
+/** One row per token; the places it is read from are listed together. */
+const mergeByToken = (rows: { token: string; use: string }[]) =>
+  [...new Set(rows.map((row) => row.token))].map((token) => ({
+    token,
+    use: rows
+      .filter((row) => row.token === token)
+      .map((row) => row.use)
+      .join(', '),
+  }));
+
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={mergeByToken([
+        ...recipeTokens(tableSlotRecipe.base),
+        { token: 'border.subtle', use: 'TableContainer › border' },
+        { token: 'bg.subtle', use: 'Th isSticky › background' },
+        { token: 'bg.surface', use: 'Td isSticky › background' },
+      ])}
+    />
+  ),
+};