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

package/src/components/FormLabel/FormLabel.usage.mdx

@@ -0,0 +1,125 @@
+import { Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as FormLabelStories from './FormLabel.stories';
+
+<Meta of={FormLabelStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# FormLabel
+
+The visible label of a field. Inside `FormControl` it is associated with the
+control and shows the required asterisk on its own.
+
+## When to use
+
+- Inside `FormControl`, when you compose a field by hand. `FieldRow` (through
+  `FieldLabel`) already renders one.
+
+## When not to use
+
+- A section title → `FormSection` `title`.
+- A label for a checkbox, radio or switch option → `Checkbox.Label`,
+  `Radio.Text`, `Switch.Label`.
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+# FormLabel
+
+필드의 보이는 라벨입니다. `FormControl` 안에서는 컨트롤과 연결되고 필수 별표도 알아서
+보여 줍니다.
+
+## 언제 쓰나요
+
+- 필드를 직접 조합할 때 `FormControl` 안에서 씁니다. `FieldRow`는 `FieldLabel`을 통해
+  이미 FormLabel을 그립니다.
+
+## 언제 쓰지 않나요
+
+- 섹션 제목은 `FormSection`의 `title`을 씁니다.
+- 체크박스, 라디오, 스위치 선택지의 라벨은 `Checkbox.Label`, `Radio.Text`,
+  `Switch.Label`을 씁니다.
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={FormLabelStories.DoNounLabels} />
+<Verdict
+  kind="do"
+  en="Write short nouns and let FormControl required add the asterisk."
+  ko="짧은 명사로 쓰고, 별표는 FormControl의 required가 붙이게 둡니다."
+/>
+
+<Canvas of={FormLabelStories.DontSentenceLabels} />
+<Verdict
+  kind="dont"
+  en="Write an instruction with a colon and type '(필수)' by hand. The asterisk already says it, so the label says it twice."
+  ko="쌍점을 붙인 지시문으로 쓰거나 '(필수)'를 직접 적지 마세요. 별표가 이미 알려 주므로 두 번 말하게 됩니다."
+/>
+
+<En>
+
+## Content
+
+- A noun phrase in sentence case, no colon, no "(required)".
+- Keep it under about four words; anything longer goes in `FieldRow`
+  `description` or helper text.
+
+## Accessibility
+
+- It renders Chakra's `Field.Label`, a `<label>` whose `for` is the field's
+  control id, so clicking it focuses the control and screen readers read it as
+  the control's name (WCAG 1.3.1, 4.1.2; KWCAG 5.3.4.1 레이블 제공).
+- Outside `FormControl` there is no id to point at: pass `htmlFor` yourself.
+- Composed controls (`SelectField`, `ComboboxField`, `Slider`) are not named
+  by it; give them `label` or `ariaLabel`.
+
+## Tokens
+
+The label text is `fg.muted` from its wrapper (`FieldLabel` overrides it to
+`fg.default`, semibold). The asterisk is `danger.fg`.
+
+## Related
+
+- **FormControl**: the field it labels.
+- **FieldRow** / **FieldLabel**: the laid-out label with description and an
+  end slot.
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 문장형 대소문자의 명사구로 쓰고, 쌍점이나 "(필수)"를 붙이지 않습니다.
+- 네 단어 안팎으로 씁니다. 더 긴 설명은 `FieldRow`의 `description`이나 도움말에
+  넣습니다.
+
+## 접근성
+
+- Chakra `Field.Label`을 그립니다. `for`가 필드 컨트롤의 id인 `<label>`이라, 누르면
+  컨트롤로 초점이 가고 화면 낭독기는 이를 컨트롤의 이름으로 읽습니다(WCAG 1.3.1, 4.1.2,
+  KWCAG 5.3.4.1 레이블 제공).
+- `FormControl` 밖에서는 가리킬 id가 없으므로 `htmlFor`를 직접 넘깁니다.
+- 부품을 조합한 컨트롤(`SelectField`, `ComboboxField`, `Slider`)에는 이 라벨이 이름으로
+  닿지 않습니다. `label`이나 `ariaLabel`을 줍니다.
+
+## 토큰
+
+라벨 글자는 감싸는 요소의 `fg.muted`를 씁니다(`FieldLabel`은 `fg.default` 굵은
+글자로 바꿉니다). 별표는 `danger.fg`입니다.
+
+## 관련 컴포넌트
+
+- **FormControl**: 라벨이 붙는 필드.
+- **FieldRow** / **FieldLabel**: 설명과 끝 자리가 있는 배치된 라벨.
+
+</Ko>

package/src/components/Icon/Icon.stories.tsx

@@ -13,9 +13,18 @@ import { useMemo } from 'react';
 import { FaBuildingUser } from 'react-icons/fa6';
 import { MdDashboard } from 'react-icons/md';
 
+import { TokenTable } from '../../guidelines/_components/TokenTable';
+import { Button } from '../Button';
+import { IconButton } from '../IconButton';
 import { Icons } from './_constants/iconList';
 import { createIcon } from './_utils/createIcon';
-import { Analytics } from './index';
+import {
+  Analytics,
+  CheckIcon,
+  CloseIcon,
+  DownloadIcon,
+  TrashIcon,
+} from './index';
 
 const meta = {
   title: 'Components/Icon',
@@ -423,3 +432,54 @@ const MyCustomIcon = createIcon(
     </VStack>
   ),
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `Icon.usage.mdx` with <Canvas of={…} />. Hidden from the
+// sidebar (`!dev`); `tags` is written out on each story because the indexer
+// reads CSF statically.
+
+export const DoIconWithLabel: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: decorative next to a label, named when alone',
+  render: () => (
+    <HStack gap={3}>
+      <Button variant="secondary">
+        <DownloadIcon boxSize="xs" aria-hidden />
+        내려받기
+      </Button>
+      <IconButton aria-label="삭제" variant="ghost">
+        <TrashIcon boxSize="xs" aria-hidden />
+      </IconButton>
+    </HStack>
+  ),
+};
+
+export const DontIconAsStatus: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: a coloured icon as the only status",
+  render: () => (
+    <HStack gap={4}>
+      <Text>결제 1</Text>
+      <CheckIcon boxSize="xs" color="success.fg" />
+      <Text>결제 2</Text>
+      <CloseIcon boxSize="xs" color="danger.fg" />
+    </HStack>
+  ),
+};
+
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={[
+        { token: 'fg.icon', use: 'icons on their own (stories default)' },
+        { token: 'fg.default', use: 'icon in running text' },
+        { token: 'fg.muted', use: 'secondary icon' },
+      ]}
+    />
+  ),
+};

package/src/components/Icon/Icon.usage.mdx

@@ -0,0 +1,158 @@
+import { Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as IconStories from './Icon.stories';
+
+<Meta of={IconStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# Icon
+
+The icon set: named exports such as `DownloadIcon`, `TrashIcon` and
+`CheckIcon`, wrapped from react-icons and custom SVGs with `createIcon`.
+Every icon takes `boxSize` (`2xs` 14px, `xs` 16px, `sm` 20px, `md` 24px
+default, `lg` 32px, `xl` 40px) and paints `currentColor`, so it takes the
+text colour around it unless you pass `color`.
+
+## When to use
+
+- To help recognise an action or item next to its label.
+- Inside an `IconButton`, where the button carries the name.
+
+## When not to use
+
+- As the only way to say something (a status, an error) → words, with the
+  icon as support (`Badge`, `Banner`).
+- As a decorative illustration → an image.
+- A new icon from another set inline at the call site → add it to the set
+  (see `ICON_MANAGEMENT.md`) so every app gets the same one.
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+# Icon
+
+아이콘 모음입니다. `DownloadIcon`, `TrashIcon`, `CheckIcon` 같은 이름으로 내보내며,
+react-icons와 직접 만든 SVG를 `createIcon`으로 감쌌습니다. 모든 아이콘은
+`boxSize`(`2xs` 14px, `xs` 16px, `sm` 20px, 기본 `md` 24px, `lg` 32px, `xl` 40px)를 받고
+`currentColor`로 칠하므로, `color`를 넘기지 않으면 주변 글자색을 따릅니다.
+
+## 언제 쓰나요
+
+- 라벨 옆에서 동작이나 항목을 알아보기 쉽게 할 때.
+- `IconButton` 안에서. 이름은 버튼이 가집니다.
+
+## 언제 쓰지 않나요
+
+- 아이콘만으로 무언가(상태, 오류)를 알리지 않습니다. 문구를 쓰고 아이콘은 거들게
+  합니다(`Badge`, `Banner`).
+- 장식용 그림에는 이미지를 씁니다.
+- 다른 아이콘 모음의 아이콘을 호출부에서 바로 쓰지 않습니다. 모든 앱이 같은 아이콘을
+  쓰도록 모음에 추가합니다(`ICON_MANAGEMENT.md` 참고).
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={IconStories.DoIconWithLabel} />
+<Verdict
+  kind="do"
+  en="Next to a label the icon is decorative (aria-hidden). On its own, the IconButton carries the name (aria-label)."
+  ko="라벨 옆의 아이콘은 장식이므로 aria-hidden을 붙입니다. 아이콘만 있다면 IconButton이 이름(aria-label)을 가집니다."
+/>
+
+<Canvas of={IconStories.DontIconAsStatus} />
+<Verdict
+  kind="dont"
+  en="Use a green check and a red cross as the only status. Without words the meaning rests on colour and shape alone."
+  ko="초록 체크와 빨간 X만으로 상태를 알리지 마세요. 문구가 없으면 색과 모양에만 뜻이 실립니다."
+/>
+
+<En>
+
+## Content
+
+- Use the same icon for the same action everywhere (`TrashIcon` is always
+  delete).
+- Match the icon size to the text: `xs` beside body text and small buttons,
+  `sm`–`md` on their own.
+
+## Accessibility
+
+What Icon does for you:
+
+- It renders an inline SVG in `currentColor`, so it follows the text colour
+  in light, dark and high-contrast modes.
+
+What you still have to do:
+
+- **Mark decorative icons `aria-hidden`.** The icon does not hide itself.
+- **Name icon-only controls** with `aria-label` on the button (WCAG 4.1.2),
+  and keep the label the same as any visible tooltip (WCAG 2.5.3).
+- **Icons do not replace words** (WCAG 1.4.1). A standalone icon that means
+  something needs at least 3:1 against its background (WCAG 1.4.11);
+  `fg.icon` is tuned for that.
+
+## Tokens
+
+The icon paints `currentColor`; these are the roles to set when you pass
+`color`.
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 같은 동작에는 어디서나 같은 아이콘을 씁니다(`TrashIcon`은 언제나 삭제).
+- 아이콘 크기는 글자에 맞춥니다. 본문과 작은 버튼 옆에는 `xs`, 아이콘만 있을 때는
+  `sm`–`md`를 씁니다.
+
+## 접근성
+
+Icon이 알아서 하는 일
+
+- `currentColor`로 칠하는 인라인 SVG라서 라이트, 다크, 고대비 모드에서 글자색을
+  따릅니다.
+
+직접 챙겨야 하는 일
+
+- **장식 아이콘에는 `aria-hidden`을 붙입니다.** 아이콘이 스스로 숨지 않습니다.
+- **아이콘만 있는 컨트롤에는 버튼에 `aria-label`로 이름을 붙이고**(WCAG 4.1.2), 보이는
+  툴팁이 있다면 같은 말을 씁니다(WCAG 2.5.3).
+- **아이콘이 문구를 대신하지 않습니다**(WCAG 1.4.1). 뜻을 가진 아이콘이 혼자 있다면
+  바탕과 3:1 이상이어야 하며(WCAG 1.4.11), `fg.icon`이 그 기준에 맞춰져 있습니다.
+
+## 토큰
+
+아이콘은 `currentColor`로 칠합니다. 아래는 `color`를 넘길 때 쓰는 역할입니다.
+
+</Ko>
+
+<Canvas of={IconStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **IconButton**: an icon-only control with a name.
+- **Badge** / **Banner**: status in words, with an icon as support.
+- `ICON_MANAGEMENT.md`: adding an icon to the set.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **IconButton**: 이름이 있는 아이콘 전용 컨트롤.
+- **Badge** / **Banner**: 아이콘이 거드는 문구 상태.
+- `ICON_MANAGEMENT.md`: 아이콘 추가 방법.
+
+</Ko>

package/src/components/IconButton/IconButton.stories.tsx

@@ -1,8 +1,21 @@
 import { Meta, StoryObj } from '@storybook/react';
 
-import { Grid, HStack, Text, VStack } from '@chakra-ui/react';
-import { FaUniversity, SendIcon, TrashIcon } from '../Icon';
-import { IconButton, iconButtonVariants } from '.';
+import { Box, Flex, Grid, HStack, Text, VStack } from '@chakra-ui/react';
+import { T } from '../../guidelines/_components/Lang';
+import { TokenTable } from '../../guidelines/_components/TokenTable';
+import { Button } from '../Button';
+import {
+  CopyIcon,
+  DownloadIcon,
+  EditIcon,
+  FaUniversity,
+  PlusIcon,
+  SendIcon,
+  ShareIcon,
+  TrashIcon,
+} from '../Icon';
+import { Tooltip } from '../Tooltip';
+import { IconButton, iconButtonVariants, iconButtonVariantStyles } from '.';
 import { IconButtonVariant } from './IconButton.types';
 
 const meta = {
@@ -16,11 +29,13 @@ const meta = {
     variant: {
       control: 'select',
       options: iconButtonVariants,
-      description: 'Role. Default `ghost`.',
+      description:
+        'Role. `ghost` (default): toolbars and row actions, glyph in `fg.icon`. `secondary`: ghost with an outline, for a control that must read as a button on its own. `primary`: black fill, the one main icon action. `danger`: red fill, confirms a destructive step. `action`: the coral send button of a chat composer.',
     },
     isDestructive: {
       control: 'boolean',
-      description: 'Danger icon on ghost / secondary',
+      description:
+        'Danger-coloured glyph (`danger.fg`) on `ghost` / `secondary`, for a delete icon in a row. Ignored on filled roles.',
     },
     children: {
       table: { disable: true },
@@ -121,3 +136,192 @@ export const ActionSend: Story = {
     </HStack>
   ),
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `IconButton.usage.mdx` with <Canvas of={…} />. Hidden from the
+// sidebar (`!dev`); `tags` is written out on each story because the indexer
+// reads CSF statically.
+
+/** A chat message's action row: copy, edit, share, delete. */
+export const DoGhostToolbar: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: ghost icon buttons in a toolbar',
+  render: () => (
+    <HStack gap={1}>
+      <Tooltip content="복사">
+        <IconButton aria-label="복사" size="sm">
+          <CopyIcon />
+        </IconButton>
+      </Tooltip>
+      <Tooltip content="수정">
+        <IconButton aria-label="수정" size="sm">
+          <EditIcon />
+        </IconButton>
+      </Tooltip>
+      <Tooltip content="공유">
+        <IconButton aria-label="공유" size="sm">
+          <ShareIcon />
+        </IconButton>
+      </Tooltip>
+      <Tooltip content="삭제">
+        <IconButton aria-label="삭제" size="sm" isDestructive>
+          <TrashIcon />
+        </IconButton>
+      </Tooltip>
+    </HStack>
+  ),
+};
+
+export const DontFilledToolbar: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: filled icon buttons in a toolbar",
+  render: () => (
+    <HStack gap={1}>
+      <IconButton aria-label="복사" size="sm" variant="primary">
+        <CopyIcon />
+      </IconButton>
+      <IconButton aria-label="수정" size="sm" variant="primary">
+        <EditIcon />
+      </IconButton>
+      <IconButton aria-label="공유" size="sm" variant="primary">
+        <ShareIcon />
+      </IconButton>
+      <IconButton aria-label="삭제" size="sm" variant="danger">
+        <TrashIcon />
+      </IconButton>
+    </HStack>
+  ),
+};
+
+/** A chat composer: the coral send button is the one run signal. */
+export const DoActionForSend: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: action only for send',
+  render: () => (
+    <Flex
+      align="center"
+      gap={2}
+      maxW="420px"
+      px={4}
+      py={2}
+      borderWidth="1px"
+      borderColor="border.default"
+      borderRadius="xl"
+      bg="bg.surface"
+    >
+      <Tooltip content="파일 첨부">
+        <IconButton aria-label="파일 첨부" size="sm">
+          <PlusIcon />
+        </IconButton>
+      </Tooltip>
+      <Text flex={1} fontSize="sm" color="fg.default">
+        지난달 사용량을 요약해 줘
+      </Text>
+      <IconButton aria-label="보내기" size="sm" variant="action">
+        <SendIcon />
+      </IconButton>
+    </Flex>
+  ),
+};
+
+export const DontActionForAdd: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: the coral action button for a non-send action",
+  render: () => (
+    <Flex align="center" justify="space-between" maxW="420px">
+      <Text fontWeight="bold" color="fg.default">
+        멤버
+      </Text>
+      <IconButton aria-label="멤버 추가" size="sm" variant="action">
+        <PlusIcon />
+      </IconButton>
+    </Flex>
+  ),
+};
+
+export const DoTextWhenUnclear: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: a labelled Button when the icon is not obvious',
+  render: () => (
+    <Box>
+      <Button variant="secondary" size="sm">
+        <DownloadIcon />
+        사용 내역 내려받기
+      </Button>
+    </Box>
+  ),
+};
+
+export const DontUnclearIcon: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: an icon only you can read",
+  render: () => (
+    <HStack gap={1}>
+      <IconButton aria-label="사용 내역 내려받기" variant="secondary" size="sm">
+        <FaUniversity />
+      </IconButton>
+    </HStack>
+  ),
+};
+
+type StateStyles = {
+  bgColor?: unknown;
+  borderColor?: unknown;
+  color?: unknown;
+  _hover?: { bgColor?: unknown; color?: unknown };
+  _active?: { bgColor?: unknown };
+};
+
+type Use = { en: string; ko: string };
+
+/**
+ * One row per token, listing every role and state that reads it. Read from
+ * `iconButtonVariantStyles`, so a recipe change shows up on the next build.
+ */
+const iconButtonTokenRows = () => {
+  const uses = new Map<string, Use[]>();
+  const add = (token: unknown, use: Use) => {
+    if (typeof token !== 'string' || token === 'transparent') return;
+    uses.set(token, [...(uses.get(token) ?? []), use]);
+  };
+  iconButtonVariants.forEach((variant) => {
+    const s = iconButtonVariantStyles[variant] as StateStyles;
+    const at = (en: string, ko: string) => ({
+      en: `${variant} ${en}`,
+      ko: `${variant} ${ko}`,
+    });
+    add(s.bgColor, at('fill', '바탕'));
+    add(s.borderColor, at('border', '테두리'));
+    add(s.color, at('icon', '아이콘'));
+    add(s._hover?.bgColor, at('hover fill', '마우스 올림 바탕'));
+    add(s._hover?.color, at('hover icon', '마우스 올림 아이콘'));
+    add(s._active?.bgColor, at('pressed fill', '누름 바탕'));
+  });
+  add('danger.fg', { en: 'isDestructive icon', ko: 'isDestructive 아이콘' });
+  add('disabled.bg', { en: 'disabled fill', ko: '비활성 바탕' });
+  add('disabled.fg', { en: 'disabled icon', ko: '비활성 아이콘' });
+  add('focus.ring', { en: 'keyboard focus ring', ko: '키보드 초점 링' });
+  return [...uses].map(([token, list]) => ({
+    token,
+    use: (
+      <T
+        en={list.map((u) => u.en).join(', ')}
+        ko={list.map((u) => u.ko).join(', ')}
+      />
+    ),
+  }));
+};
+
+/** Tokens each role reads, resolved from `IconButton.styles.ts` and the theme. */
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => <TokenTable rows={iconButtonTokenRows()} />,
+};