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

package/src/components/Breadcrumb/Breadcrumb.stories.tsx

@@ -1,6 +1,9 @@
 import { 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 { Breadcrumb } from './Breadcrumb';
 import { BreadcrumbItem } from './BreadcrumbItem';
 import { BreadcrumbLink } from './BreadcrumbLink';
@@ -74,3 +77,59 @@ export const CustomSeparator: Story = {
     </Stack>
   ),
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `Breadcrumb.usage.mdx` with <Canvas of={…} />. Hidden from the
+// sidebar (`!dev`).
+
+export const DoCurrentPageIsText: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: ancestors are links, the current page is text',
+  render: () => (
+    <Breadcrumb aria-label="현재 위치">
+      <BreadcrumbItem>
+        <BreadcrumbLink href="#">전체 조직</BreadcrumbLink>
+      </BreadcrumbItem>
+      <BreadcrumbItem>
+        <BreadcrumbLink href="#">영업본부</BreadcrumbLink>
+      </BreadcrumbItem>
+      <BreadcrumbItem>
+        <Text as="span" aria-current="page" fontWeight="semibold">
+          영업 1팀
+        </Text>
+      </BreadcrumbItem>
+    </Breadcrumb>
+  ),
+};
+
+export const DontEveryCrumbALink: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: the current page as a link to itself",
+  render: () => (
+    <Breadcrumb>
+      <BreadcrumbItem>
+        <BreadcrumbLink href="#">전체 조직</BreadcrumbLink>
+      </BreadcrumbItem>
+      <BreadcrumbItem>
+        <BreadcrumbLink href="#">영업본부</BreadcrumbLink>
+      </BreadcrumbItem>
+      <BreadcrumbItem>
+        <BreadcrumbLink href="#">영업 1팀</BreadcrumbLink>
+      </BreadcrumbItem>
+    </Breadcrumb>
+  ),
+};
+
+/** Tokens the trail reads, as set in `BreadcrumbLink.tsx`. */
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={[{ token: 'fg.default', use: <T en="Link" ko="링크" /> }]}
+    />
+  ),
+};

package/src/components/Breadcrumb/Breadcrumb.usage.mdx

@@ -0,0 +1,181 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as BreadcrumbStories from './Breadcrumb.stories';
+
+<Meta of={BreadcrumbStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# Breadcrumb
+
+A trail of links that shows where the current page sits in a hierarchy and
+lets the user go back up it.
+
+## When to use
+
+- In a hierarchy more than two levels deep: a group inside a group inside the
+  organisation, a folder in a file picker.
+- At the top of a course or a detail view, to lead back to the level above.
+
+## When not to use
+
+- For a flat app section with one level → the page title is enough.
+- For the user's history ("where I was before") → the browser's back button.
+  A breadcrumb shows the hierarchy, not the path taken.
+- To switch between siblings of the same level → `Tabs` or a navigation list.
+- For the steps of a flow → a stepper.
+
+## Variants and what they mean
+
+Breadcrumb has no visual variants. `separator` (default `›`) and
+`separatorGap` (default `2`) set the mark between items and the space around
+it.
+
+</En>
+
+<Ko>
+
+# Breadcrumb
+
+지금 페이지가 계층의 어디에 있는지 보이고, 위 단계로 돌아갈 수 있게 하는 링크
+경로입니다.
+
+## 언제 쓰나요
+
+- 두 단계보다 깊은 계층에서: 조직 안의 그룹 안의 그룹, 파일 선택기의 폴더.
+- 강의나 상세 화면 맨 위에서 한 단계 위로 돌아가는 길을 보일 때.
+
+## 언제 쓰지 않나요
+
+- 한 단계뿐인 평평한 화면에서는 페이지 제목으로 충분합니다.
+- 사용자가 지나온 기록("방금 있던 곳")은 브라우저의 뒤로 가기가 맡습니다. Breadcrumb는
+  거쳐 온 길이 아니라 계층을 보입니다.
+- 같은 단계의 형제 사이를 오가는 것은 `Tabs`나 내비게이션 목록을 씁니다.
+- 흐름의 단계는 단계 표시를 씁니다.
+
+## 변형과 뜻
+
+Breadcrumb에는 모양 변형이 없습니다. `separator`(기본 `›`)와 `separatorGap`(기본
+`2`)으로 항목 사이의 표시와 간격을 정합니다.
+
+</Ko>
+
+<ArgTypes of={BreadcrumbStories} include={['separator', 'separatorGap']} />
+
+<En>
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={BreadcrumbStories.DoCurrentPageIsText} />
+<Verdict
+  kind="do"
+  en="Link the ancestors and render the current page as text with aria-current='page'. Name the trail in the user's language."
+  ko="위 단계는 링크로, 지금 페이지는 aria-current='page'를 단 글자로 둡니다. 경로의 이름은 사용자의 언어로 붙입니다."
+/>
+
+<Canvas of={BreadcrumbStories.DontEveryCrumbALink} />
+<Verdict
+  kind="dont"
+  en="Make the current page a link to itself. It looks clickable, does nothing, and a screen reader cannot tell which crumb is the current page."
+  ko="지금 페이지를 자기 자신으로 가는 링크로 만들지 마세요. 누를 수 있어 보이지만 아무 일도 하지 않고, 화면 낭독기는 어느 항목이 지금 페이지인지 알 수 없습니다."
+/>
+
+<En>
+
+## Content
+
+- Each crumb is the title of that level, exactly as the page itself shows it.
+- Leave out the app's home if every page starts there.
+- In a very deep tree, keep the root and the last two or three levels and
+  collapse the middle.
+
+## Accessibility
+
+What Breadcrumb does for you:
+
+- Renders a `<nav>` with an ordered list, so the trail is a landmark and its
+  length is announced.
+- Separators are `aria-hidden`; a screen reader reads only the crumbs.
+- `BreadcrumbLink` shows the focus ring (WCAG 2.4.7). It renders through
+  `next/link` when Next.js is installed.
+
+What you still have to do:
+
+- **Name the landmark in the user's language.** Chakra's default `aria-label`
+  is the English "breadcrumb". Pass `aria-label="현재 위치"` or a translation
+  (WCAG 2.4.6).
+- **Mark the current page.** Render it as text with `aria-current="page"`, not
+  as a `BreadcrumbLink`.
+- Truncated crumbs need their full text available, for example as the link's
+  visible text with CSS truncation and a `Tooltip`.
+
+## Tokens
+
+The table lists the tokens set in `BreadcrumbLink.tsx`. The separator colour
+comes from Chakra's Breadcrumb recipe.
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 각 항목은 그 단계의 페이지 제목을 화면에 보이는 그대로 씁니다.
+- 모든 페이지가 같은 홈에서 시작한다면 홈은 뺍니다.
+- 아주 깊은 트리에서는 맨 위와 마지막 두세 단계만 두고 가운데는 접습니다.
+
+## 접근성
+
+Breadcrumb가 알아서 하는 일
+
+- `<nav>`와 순서 있는 목록으로 그려지므로 경로가 랜드마크가 되고 항목 수가 읽힙니다.
+- 구분 표시는 `aria-hidden`이라 화면 낭독기는 항목만 읽습니다.
+- `BreadcrumbLink`에는 초점 테두리가 보입니다(WCAG 2.4.7). Next.js가 설치되어 있으면
+  `next/link`로 그립니다.
+
+직접 챙겨야 하는 일
+
+- **랜드마크 이름을 사용자의 언어로 붙입니다.** Chakra의 기본 `aria-label`은 영어
+  "breadcrumb"입니다. `aria-label="현재 위치"`나 번역 문자열을 넘깁니다(WCAG 2.4.6).
+- **지금 페이지를 표시합니다.** `BreadcrumbLink`가 아니라 `aria-current="page"`를 단
+  글자로 그립니다.
+- 잘린 항목은 전체 문구를 볼 방법이 있어야 합니다. 예를 들어 링크 글자는 CSS로 자르고
+  `Tooltip`으로 전체를 보입니다.
+
+## 토큰
+
+아래 표는 `BreadcrumbLink.tsx`에서 정한 토큰입니다. 구분 표시의 색은 Chakra Breadcrumb
+레시피에서 옵니다.
+
+</Ko>
+
+<Canvas of={BreadcrumbStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **Tabs**: siblings of the same level.
+- **Menu**: the collapsed middle of a long trail.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **Tabs**: 같은 단계의 형제 사이 이동.
+- **Menu**: 긴 경로의 접힌 가운데 부분.
+
+</Ko>

package/src/components/Button/Button.stories.tsx

@@ -1,8 +1,12 @@
+import type { ReactNode } from 'react';
 import { Box, Flex, Grid, HStack, Text, VStack } 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 { Sparkles, TrashIcon } from '../Icon';
-import { Button, buttonVariants } from '.';
+import { Button, buttonVariants, buttonVariantStyles } from '.';
 import { ButtonVariant } from './Button.types';
 
 const meta = {
@@ -12,11 +16,13 @@ const meta = {
     variant: {
       control: 'select',
       options: buttonVariants,
-      description: 'Role (fill, border and text together). Default `subtle`.',
+      description:
+        'Role (fill, border and text together). `primary`: the one main action of a screen. `action`: run — black fill, coral icon. `accent`: the coloured CTA of a landing page or hero, one per view. `secondary`: an alternative or a way out. `subtle` (default): low emphasis with a shape. `ghost`: toolbars and inline actions. `danger`: confirms a destructive step.',
     },
     isDestructive: {
       control: 'boolean',
-      description: 'Danger text on secondary / ghost / subtle',
+      description:
+        'Danger-coloured label (`danger.fg`) on `secondary` / `subtle` / `ghost` for a destructive action that does not deserve a red fill. Ignored on filled roles.',
     },
   },
 } satisfies Meta<typeof Button>;
@@ -257,3 +263,257 @@ export const AsLink: Story = {
     </Flex>
   ),
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `Button.usage.mdx` with <Canvas of={…} />. Hidden from the
+// sidebar (`!dev`); being stories, they type-check with the rest of the code.
+// `tags` is written out on each story: the indexer reads CSF statically.
+
+/** A dialog-like panel: title, one line of body, a right-aligned footer. */
+const Panel = ({
+  title,
+  body,
+  children,
+}: {
+  title: string;
+  body: string;
+  children: ReactNode;
+}) => (
+  <Card p={5} maxW="420px" bg="bg.surface">
+    <Text fontWeight="bold" mb={1} color="fg.default">
+      {title}
+    </Text>
+    <Text fontSize="sm" color="fg.muted" mb={5}>
+      {body}
+    </Text>
+    <Flex gap={2} justify="flex-end">
+      {children}
+    </Flex>
+  </Card>
+);
+
+export const DoOnePrimary: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: one primary, secondary to its left',
+  render: () => (
+    <Panel title="그룹 이름 변경" body="변경한 이름은 모든 멤버에게 보입니다.">
+      <Button variant="secondary">취소</Button>
+      <Button variant="primary">저장</Button>
+    </Panel>
+  ),
+};
+
+export const DontTwoPrimaries: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: two primaries side by side",
+  render: () => (
+    <Panel title="그룹 이름 변경" body="변경한 이름은 모든 멤버에게 보입니다.">
+      <Button variant="primary">취소</Button>
+      <Button variant="primary">저장</Button>
+    </Panel>
+  ),
+};
+
+export const DoDangerToConfirm: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: danger fill only on the confirming button',
+  render: () => (
+    <Panel
+      title="챗봇을 삭제할까요?"
+      body="삭제한 챗봇과 대화 기록은 되돌릴 수 없습니다."
+    >
+      <Button variant="secondary">취소</Button>
+      <Button variant="danger">삭제</Button>
+    </Panel>
+  ),
+};
+
+const ROWS = ['마케팅 챗봇', '영업 챗봇', '사내 규정 챗봇'];
+
+const Row = ({ name, action }: { name: string; action: ReactNode }) => (
+  <Flex
+    justify="space-between"
+    align="center"
+    py={2}
+    borderBottomWidth="1px"
+    borderColor="border.subtle"
+  >
+    <Text fontSize="sm" color="fg.default">
+      {name}
+    </Text>
+    {action}
+  </Flex>
+);
+
+export const DoQuietDestructiveInRows: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: isDestructive on a quiet button in a list',
+  render: () => (
+    <Box maxW="420px">
+      {ROWS.map((name) => (
+        <Row
+          key={name}
+          name={name}
+          action={
+            <Button variant="ghost" size="sm" isDestructive>
+              <TrashIcon />
+              삭제
+            </Button>
+          }
+        />
+      ))}
+    </Box>
+  ),
+};
+
+export const DontDangerFillInRows: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: a red fill on every row",
+  render: () => (
+    <Box maxW="420px">
+      {ROWS.map((name) => (
+        <Row
+          key={name}
+          name={name}
+          action={
+            <Button variant="danger" size="sm">
+              삭제
+            </Button>
+          }
+        />
+      ))}
+    </Box>
+  ),
+};
+
+export const DoPrimaryForUpgrade: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: primary for upgrade and payment',
+  render: () => (
+    <Panel
+      title="크레딧이 부족합니다"
+      body="요금제를 올리면 이번 달 남은 기간에도 바로 쓸 수 있습니다."
+    >
+      <Button variant="secondary">나중에</Button>
+      <Button variant="primary">요금제 업그레이드</Button>
+    </Panel>
+  ),
+};
+
+export const DontAccentForUpgrade: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: coral accent for upgrade in the product",
+  render: () => (
+    <Panel
+      title="크레딧이 부족합니다"
+      body="요금제를 올리면 이번 달 남은 기간에도 바로 쓸 수 있습니다."
+    >
+      <Button variant="secondary">나중에</Button>
+      <Button variant="accent">요금제 업그레이드</Button>
+    </Panel>
+  ),
+};
+
+export const DoLoadingText: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: loadingText while the action runs',
+  render: () => (
+    <HStack gap={4}>
+      <Button variant="primary" loading loadingText="저장 중">
+        저장
+      </Button>
+      <Button variant="action" loading loadingText="실행 중">
+        <Sparkles />
+        실행
+      </Button>
+    </HStack>
+  ),
+};
+
+export const DontSpinnerOnly: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: a spinner with no words",
+  render: () => (
+    <HStack gap={4}>
+      <Button variant="primary" loading>
+        저장
+      </Button>
+    </HStack>
+  ),
+};
+
+type StateStyles = {
+  bgColor?: unknown;
+  borderColor?: unknown;
+  color?: unknown;
+  _hover?: unknown;
+  _active?: unknown;
+};
+
+const STATE_LABELS = {
+  bgColor: { en: 'fill', ko: '바탕' },
+  borderColor: { en: 'border', ko: '테두리' },
+  color: { en: 'label', ko: '글자' },
+  hover: { en: 'hover fill', ko: '마우스 올림' },
+  active: { en: 'pressed fill', ko: '누름' },
+} as const;
+
+type Use = { en: string; ko: string };
+
+/**
+ * One row per token, listing every role and state that reads it. Read from
+ * `buttonVariantStyles`, so a recipe change shows up here on the next build.
+ */
+const buttonTokenRows = () => {
+  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]);
+  };
+  buttonVariants.forEach((variant) => {
+    const s = buttonVariantStyles[variant] as StateStyles;
+    const label = (key: keyof typeof STATE_LABELS) => ({
+      en: `${variant} ${STATE_LABELS[key].en}`,
+      ko: `${variant} ${STATE_LABELS[key].ko}`,
+    });
+    add(s.bgColor, label('bgColor'));
+    add(s.borderColor, label('borderColor'));
+    add(s.color, label('color'));
+    add((s._hover as StateStyles | undefined)?.bgColor, label('hover'));
+    add((s._active as StateStyles | undefined)?.bgColor, label('active'));
+  });
+  add('action.iconOnSolid', { en: 'action icon', ko: 'action 아이콘' });
+  add('danger.fg', {
+    en: 'isDestructive label',
+    ko: 'isDestructive 글자',
+  });
+  add('disabled.bg', { en: 'disabled fill', ko: '비활성 바탕' });
+  add('disabled.fg', { en: 'disabled label', 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(', ')}
+      />
+    ),
+  }));
+};
+
+/** Every token a role reads at rest, on hover and on press. */
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => <TokenTable rows={buttonTokenRows()} />,
+};