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

package/src/components/Tag/Tag.styles.ts

@@ -1,10 +1,19 @@
-import { TagRootProps } from '@chakra-ui/react';
+import type {
+  ConditionalValue,
+  SystemStyleObject,
+  TagRootProps,
+} from '@chakra-ui/react';
 
 import type { SystemHue } from '@/theme/colors';
+import {
+  CONTROL_RADIUS,
+  type ControlSizeSpec,
+  getControlSize,
+} from '@/theme/controlSizes';
 import { disabledControl } from '@/utils/disabledControl';
 import { isDev } from '@/utils/isDev';
 
-import { TagColorPalette, TagTone, TagVariant } from './Tag.types';
+import { TagColorPalette, TagSize, TagTone, TagVariant } from './Tag.types';
 
 type StyleProps = Partial<TagRootProps>;
 
@@ -111,6 +120,112 @@ export const getTagStyles = ({
   };
 };
 
+type ResponsiveTagSize = ConditionalValue<TagSize>;
+
+const isPlainObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/**
+ * Map every leaf of a Chakra conditional value (`'sm'`, `['xs', null, 'md']`,
+ * `{ base: 'xs', md: 'lg' }`, nested conditions) through `fn`, keeping its
+ * shape so Chakra still applies each result at its breakpoint. `null` array
+ * slots ("no change at this breakpoint") stay `null`.
+ */
+const mapConditional = <R>(
+  value: ResponsiveTagSize,
+  fn: (size: TagSize) => R
+): ConditionalValue<R> => {
+  if (Array.isArray(value)) {
+    return value.map((v) => (v == null ? null : (mapConditional(v, fn) as R)));
+  }
+  if (isPlainObject(value)) {
+    return Object.fromEntries(
+      Object.entries(value).map(([k, v]) => [
+        k,
+        v == null ? v : mapConditional(v as ResponsiveTagSize, fn),
+      ])
+    ) as ConditionalValue<R>;
+  }
+  return fn(value as TagSize);
+};
+
+/**
+ * An interactive tag must draw a control size at every width. A responsive
+ * value that starts above `base` (`{ md: 'lg' }`, `[null, 'sm']`) would leave
+ * the narrowest screens on the badge recipe, so they start at the default `md`.
+ */
+const withBaseSize = (
+  size: ResponsiveTagSize | undefined
+): ResponsiveTagSize => {
+  if (size == null) return 'md';
+  if (Array.isArray(size)) {
+    return size[0] == null ? ['md', ...size.slice(1)] : size;
+  }
+  if (isPlainObject(size)) {
+    return 'base' in size && size.base != null ? size : { base: 'md', ...size };
+  }
+  return size;
+};
+
+/**
+ * Size styles for a tag.
+ *
+ * - **Interactive** (a filter chip, a toggle, a link): the shared control
+ *   scale — the same height, type, inline padding, gap, icon size and radius
+ *   as a `Button` of that `size` (default `md`), so a chip row lines up with
+ *   the search field and buttons next to it. A responsive `size` resolves the
+ *   scale per breakpoint. A composed `TagLabel` inherits the control type
+ *   instead of the badge recipe's smaller label type.
+ * - **Static** (a badge): Chakra's tag sizes, unchanged. `xs` exists only on
+ *   the control scale, so a static `xs` falls back to the smallest badge.
+ */
+export const getTagSizeStyles = (
+  size: ResponsiveTagSize | undefined,
+  interactive: boolean
+): {
+  sizeStyles: StyleProps;
+  recipeSize: TagRootProps['size'];
+  cssVars?: SystemStyleObject;
+} => {
+  const recipeSize =
+    size == null
+      ? undefined
+      : (mapConditional(size, (s) =>
+          s === 'xs' ? 'sm' : s
+        ) as TagRootProps['size']);
+  if (!interactive) return { sizeStyles: { fontSize: 'sm' }, recipeSize };
+  const scale = withBaseSize(size);
+  const pick = <K extends keyof ControlSizeSpec>(key: K) =>
+    mapConditional(scale, (s) => getControlSize(s)[key]);
+  const height = pick('height');
+  return {
+    sizeStyles: {
+      h: height,
+      minH: height,
+      px: pick('actionPaddingX'),
+      gap: pick('gap'),
+      textStyle: pick('textStyle') as StyleProps['textStyle'],
+      borderRadius: CONTROL_RADIUS,
+    },
+    recipeSize,
+    cssVars: {
+      // The `icon` slot is sized by this variable.
+      '--tag-element-size': mapConditional(
+        scale,
+        (s) =>
+          `var(--chakra-sizes-${getControlSize(s).iconSize.replace('.', '\\.')})`
+      ),
+      // The tag recipe gives its label the badge type (`xs` at sm/md). Inside
+      // a control that would shrink the label below the root's control type
+      // (12.25px instead of Button's 14px at desktop md), so it inherits.
+      '& .chakra-tag__label': {
+        fontSize: 'inherit',
+        lineHeight: 'inherit',
+      },
+    } as SystemStyleObject,
+  };
+};
+
 /**
  * Result of mapping a 4.x `colorPalette × variant` pair onto 5.0 Tag props.
  * `needsHuman` marks a pair 5.0 cannot render faithfully (a status `solid`

package/src/components/Tag/Tag.test.tsx

@@ -6,7 +6,12 @@ import { system } from '../../theme';
 import { Badge } from '../Badge';
 import { Chip } from '../Chip';
 import { Tag } from './Tag';
-import { getTagStyles, mapLegacyTagProps } from './Tag.styles';
+import {
+  getTagSizeStyles,
+  getTagStyles,
+  mapLegacyTagProps,
+} from './Tag.styles';
+import { TagLabel } from './TagLabel';
 
 const wrap = (ui: React.ReactNode) =>
   render(<ChakraProvider value={system}>{ui}</ChakraProvider>);
@@ -113,3 +118,84 @@ describe('deprecated aliases', () => {
     expect(warn).toHaveBeenCalledTimes(1);
   });
 });
+
+describe('Tag size', () => {
+  it('resolves a responsive size per breakpoint on an interactive tag', () => {
+    const { sizeStyles, cssVars, recipeSize } = getTagSizeStyles(
+      { base: 'xs', md: 'lg' },
+      true
+    );
+    expect(sizeStyles).toMatchObject({
+      h: { base: '8', md: '11' },
+      minH: { base: '8', md: '11' },
+      px: { base: '2.5', md: '5' },
+      gap: { base: '1', md: '3' },
+      textStyle: { base: 'xs', md: 'md' },
+    });
+    expect(cssVars?.['--tag-element-size']).toEqual({
+      base: 'var(--chakra-sizes-4)',
+      md: 'var(--chakra-sizes-5)',
+    });
+    // `xs` is not a badge recipe size.
+    expect(recipeSize).toEqual({ base: 'sm', md: 'lg' });
+  });
+
+  it('keeps array slots and starts a base-less value at md', () => {
+    expect(getTagSizeStyles(['sm', null, 'lg'], true).sizeStyles.h).toEqual([
+      '9',
+      null,
+      '11',
+    ]);
+    expect(getTagSizeStyles([null, 'xs'], true).sizeStyles.h).toEqual([
+      '10',
+      '8',
+    ]);
+    expect(getTagSizeStyles({ lg: 'xs' }, true).sizeStyles.h).toEqual({
+      base: '10',
+      lg: '8',
+    });
+  });
+
+  it('leaves a responsive static badge on the recipe', () => {
+    const { sizeStyles, recipeSize, cssVars } = getTagSizeStyles(
+      { base: 'xs', md: 'lg' },
+      false
+    );
+    expect(sizeStyles).toEqual({ fontSize: 'sm' });
+    expect(recipeSize).toEqual({ base: 'sm', md: 'lg' });
+    expect(cssVars).toBeUndefined();
+  });
+
+  it('a TagLabel inside an interactive tag inherits the control type', () => {
+    const { cssVars } = getTagSizeStyles('md', true);
+    expect(cssVars?.['& .chakra-tag__label']).toEqual({
+      fontSize: 'inherit',
+      lineHeight: 'inherit',
+    });
+    wrap(
+      <Tag as="button" selected={false} size={{ base: 'sm', md: 'lg' }}>
+        <TagLabel>Images</TagLabel>
+      </Tag>
+    );
+    const label = screen.getByText('Images');
+    expect(label.className).toContain('chakra-tag__label');
+    const css = Array.from(document.querySelectorAll('style'))
+      .map((s) => s.textContent)
+      .join('\n');
+    expect(css).toMatch(/\.chakra-tag__label\s*\{[^}]*font-size:\s*inherit/);
+  });
+
+  it('accepts responsive sizes on Tag and the Chip alias (type-level)', () => {
+    wrap(
+      <>
+        <Tag size={{ base: 'sm', md: 'lg' }}>Static</Tag>
+        <Tag size={['xs', 'md']} onClick={() => {}}>
+          Clickable
+        </Tag>
+        <Chip size={{ base: 'sm', lg: 'md' }}>Chip</Chip>
+      </>
+    );
+    expect(screen.getByText('Static')).toBeTruthy();
+    expect(screen.getByText('Chip')).toBeTruthy();
+  });
+});

package/src/components/Tag/Tag.tsx

@@ -2,9 +2,11 @@ import { ElementType, ForwardedRef, forwardRef, MouseEvent } from 'react';
 import { Tag as ChakraTag } from '@chakra-ui/react';
 
 import { focusRing } from '@/utils/focusRing';
+import { mergeCss } from '@/utils/mergeCss';
 
 import { polymorphic } from '../../types/polymorphic';
 import {
+  getTagSizeStyles,
   getTagStyles,
   mapLegacyTagProps,
   warnLegacyTagProps,
@@ -36,6 +38,13 @@ type LegacyTagInput = {
  * toggle (`selected` passed) or renders as a `button` / `a`. Render filter
  * chips `as="button"` so they are keyboard-operable.
  *
+ * **Size depends on that.** A static tag is a badge and keeps Chakra's badge
+ * sizes (`sm` 15.75px · `md` 17.5px · `lg` 21px · `xl` 28px at the 14px root).
+ * An interactive tag is a control that sits in a row with buttons and inputs,
+ * so its `size` (`xs`–`xl`, default `md`) follows the shared control scale
+ * (`controlSizes`): the same height, type, padding and icon size as a
+ * `Button` of that size.
+ *
  * @example
  * ```tsx
  * <Tag>Draft</Tag>
@@ -58,6 +67,8 @@ const TagImpl = forwardRef(
       colorPalette: legacyPalette,
       variant: legacyVariant,
       as,
+      size,
+      css: cssProp,
       __legacyComponent: legacyComponent,
       ...rest
     } = props as TagOwnProps & LegacyTagInput;
@@ -94,6 +105,14 @@ const TagImpl = forwardRef(
 
     const styles = getTagStyles({ tone, selected, category, interactive });
 
+    // Decided on `wantsInteraction`, not `interactive`, so disabling a filter
+    // chip does not shrink it.
+    const { sizeStyles, recipeSize, cssVars } = getTagSizeStyles(
+      size,
+      wantsInteraction
+    );
+    const css = cssVars ? mergeCss(cssVars, cssProp) : cssProp;
+
     const handleClick = disabled
       ? (event: MouseEvent<HTMLSpanElement>) => event.preventDefault()
       : onClick;
@@ -103,8 +122,9 @@ const TagImpl = forwardRef(
         border="1px solid"
         borderRadius="md"
         boxShadow="none"
-        fontSize="sm"
         fontWeight="semibold"
+        size={recipeSize}
+        {...sizeStyles}
         {...styles}
         {...focusRing}
         data-selected={selected ? '' : undefined}
@@ -119,6 +139,7 @@ const TagImpl = forwardRef(
         // After `rest`: a disabled link must not stay reachable by Tab.
         {...(disabledNonNative && { tabIndex: -1 })}
         as={as}
+        css={css}
         ref={ref}
       >
         {icon != null ? (

package/src/components/Tag/Tag.types.ts

@@ -1,5 +1,5 @@
 import type { ElementType, ReactNode } from 'react';
-import { TagRootProps } from '@chakra-ui/react';
+import type { ConditionalValue, TagRootProps } from '@chakra-ui/react';
 
 import type { SystemHue } from '@/theme/colors';
 
@@ -13,6 +13,9 @@ import type { PolymorphicProps } from '../../types/polymorphic';
  * - `success` / `warning` / `danger` / `info`: status family `.bg` + `.fg`.
  *   Use them only when the tag reports a status.
  */
+/** Tag sizes: the badge sizes plus `xs`, which only interactive tags draw. */
+export type TagSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+
 export type TagTone = 'neutral' | 'success' | 'warning' | 'danger' | 'info';
 
 /**
@@ -36,8 +39,19 @@ export type TagVariant = 'soft' | 'solid' | 'outline';
 
 export type TagOwnProps = Omit<
   TagRootProps,
-  'colorPalette' | 'variant' | 'as'
+  'colorPalette' | 'variant' | 'as' | 'size'
 > & {
+  /**
+   * A static tag uses the badge sizes (`sm` · `md` · `lg` · `xl`; `xs` falls
+   * back to `sm`). An interactive tag — `onClick`, `selected`, `as="button"`
+   * or a link — uses the shared control scale (`xs`–`xl`), so it matches a
+   * `Button` / `Input` of the same size in a row.
+   *
+   * Responsive values (`{ base: 'xs', md: 'sm' }`, arrays) work for both;
+   * an interactive tag resolves the control scale per breakpoint.
+   * @default 'md'
+   */
+  size?: ConditionalValue<TagSize>;
   /**
    * Colour role of the tag. Ignored while `selected` is true or `category`
    * is set.

package/src/components/Tag/Tag.usage.mdx

@@ -0,0 +1,257 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as TagStories from './Tag.stories';
+
+<Meta of={TagStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# Tag
+
+A compact label that classifies an item, or that the reader can select or
+remove: a topic, a filter, a chosen group.
+
+## When to use
+
+- To classify items into groups with no fixed meaning: topics, file types,
+  departments. Use `category`.
+- As a filter chip the reader turns on and off. Render it `as="button"` with
+  `selected`.
+- To show a choice the reader made and can take back: a selected group in a
+  picker, an active filter. Add `TagCloseButton`.
+
+## When not to use
+
+- A status or a well-defined system fact (완료, 실패, 이 그룹만) → `Badge`.
+- One choice out of a few, where exactly one is always on → `SegmentedControl`
+  or `Tabs`.
+- A count → `CountBadge`.
+- `Chip` is a deprecated alias of Tag; new code uses Tag.
+
+## Variants and what they mean
+
+</En>
+
+<Ko>
+
+# Tag
+
+항목을 분류하거나, 사용자가 고르거나 지울 수 있는 작은 라벨입니다. 주제, 필터, 선택한
+그룹 같은 곳에 씁니다.
+
+## 언제 쓰나요
+
+- 정해진 뜻이 없는 묶음으로 항목을 나눌 때: 주제, 파일 종류, 부서. `category`를 씁니다.
+- 사용자가 켜고 끄는 필터 칩으로 쓸 때. `as="button"`으로 그리고 `selected`를 넘깁니다.
+- 사용자가 고른 뒤 다시 뺄 수 있는 선택을 보여 줄 때: 선택기에서 고른 그룹, 적용 중인
+  필터. `TagCloseButton`을 붙입니다.
+
+## 언제 쓰지 않나요
+
+- 상태나 뜻이 명확한 시스템 사실(완료, 실패, 이 그룹만)은 `Badge`를 씁니다.
+- 몇 가지 중 늘 하나만 켜져 있는 선택은 `SegmentedControl`이나 `Tabs`를 씁니다.
+- 개수는 `CountBadge`를 씁니다.
+- `Chip`은 Tag의 지원 중단된 별칭입니다. 새 코드에서는 Tag를 씁니다.
+
+## 변형과 뜻
+
+</Ko>
+
+<ArgTypes of={TagStories} include={['tone', 'selected', 'category', 'icon', 'disabled']} />
+
+<En>
+
+| Prop | Means | Use for |
+| --- | --- | --- |
+| `tone="neutral"` (default) | A plain label | Group names, file extensions, active filters |
+| `category` | A group with no meaning beyond telling items apart | Topics, departments, projects |
+| `selected` | A filter chip that is on (black fill) | Filter bars |
+| `tone="success"` / `warning` / `danger` / `info` | A status every reader shares | Rare on Tag; usually `Badge` is the right component |
+| `disabled` | Cannot be used right now | A filter with no results |
+
+When more than one is set, `selected` wins over `category`, and `category`
+wins over `tone`.
+
+A tag becomes interactive (pointer, hover border) when it has `onClick`, is a
+toggle (`selected` passed, true or false), or renders as a button or a link.
+With `as="button"` it gets `type="button"`, `aria-pressed` for a toggle, and the
+native `disabled` attribute.
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+| 속성 | 뜻 | 예 |
+| --- | --- | --- |
+| `tone="neutral"` (기본) | 단순한 라벨 | 그룹 이름, 파일 확장자, 적용 중인 필터 |
+| `category` | 항목을 나누는 것 말고는 뜻이 없는 묶음 | 주제, 부서, 프로젝트 |
+| `selected` | 켜져 있는 필터 칩(검은 바탕) | 필터 막대 |
+| `tone="success"` / `warning` / `danger` / `info` | 모든 사용자가 같은 뜻으로 읽는 상태 | Tag에서는 드뭅니다. 대개 `Badge`가 맞습니다 |
+| `disabled` | 지금은 쓸 수 없음 | 결과가 없는 필터 |
+
+여러 속성을 함께 주면 `selected`가 `category`보다, `category`가 `tone`보다
+우선합니다.
+
+`onClick`이 있거나, 토글이거나(`selected`를 true든 false든 넘긴 경우), 버튼이나
+링크로 그리면 Tag는 누를 수 있는 모양(포인터, 호버 테두리)이 됩니다. `as="button"`으로
+그리면 `type="button"`이 붙고, 토글이면 `aria-pressed`가, 비활성이면 기본
+`disabled` 속성이 붙습니다.
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={TagStories.DoCategoryForTopics} />
+<Verdict
+  kind="do"
+  en="Use category hues for topics. They tell items apart without implying that one is good and another is bad."
+  ko="주제에는 category 색을 씁니다. 항목을 나누면서도 어느 쪽이 좋고 나쁘다는 뜻을 담지 않습니다."
+/>
+
+<Canvas of={TagStories.DontToneForTopics} />
+<Verdict
+  kind="dont"
+  en="Borrow status tones to colour topics. Readers will take 수업 to be an error."
+  ko="주제에 색을 입히려고 상태 tone을 빌려 쓰지 마세요. 사용자는 '수업'을 오류로 읽습니다."
+/>
+
+<Canvas of={TagStories.DoFilterToggle} />
+<Verdict
+  kind="do"
+  en='Render filter chips as="button" and pass selected. They are then reachable with Tab, work with Enter and Space, and announce pressed or not pressed.'
+  ko='필터 칩은 as="button"으로 그리고 selected를 넘깁니다. 그래야 Tab으로 이동하고 Enter와 Space로 누를 수 있으며, 눌림 여부가 읽힙니다.'
+/>
+
+<Canvas of={TagStories.DoRemovableWithName} />
+<Verdict
+  kind="do"
+  en="Give every remove button its own name, such as '마케팅팀 삭제'. Three buttons all called 'close' are impossible to tell apart."
+  ko="삭제 버튼마다 '마케팅팀 삭제'처럼 고유한 이름을 붙입니다. 이름이 모두 '닫기'인 버튼 세 개는 서로 구분할 수 없습니다."
+/>
+
+<Canvas of={TagStories.DontSelectedForStatus} />
+<Verdict
+  kind="dont"
+  en="Use the selected fill to show a status. Black means 'this filter is on'. For 게시됨 use a Badge."
+  ko="상태를 보여 주려고 selected 바탕을 쓰지 마세요. 검은 바탕은 '이 필터가 켜져 있음'이라는 뜻입니다. '게시됨'에는 Badge를 씁니다."
+/>
+
+<En>
+
+## Content
+
+- One to three words. No full stop.
+- Nouns, not verbs: 이미지, not 이미지 보기.
+- Sentence case in English. No 「」, quotation marks or brackets around
+  Korean labels.
+- For a long name, shorten the label and keep the full name in the remove
+  button's `aria-label` or a `Tooltip`.
+
+## Accessibility
+
+What Tag does for you:
+
+- A plain tag is a `<span>`, so it is safe inside a button or link (phrasing
+  content, `ACCESSIBILITY.md` §5, KWCAG 5.4.1.1).
+- `as="button"` adds `type="button"`, `aria-pressed` for a toggle, the native
+  `disabled` attribute and the house focus ring (WCAG 2.4.7, 4.1.2).
+- A disabled tag that would otherwise be a link or clickable span gets
+  `aria-disabled`, leaves the Tab order and ignores clicks.
+- Text on every tone and on `selected` passes the contrast audit in both modes
+  (WCAG 1.4.3).
+
+What you still have to do:
+
+- **Clickable means a button or a link** (WCAG 2.1.1). `onClick` on the default
+  `<span>` is not reachable by keyboard. Use `as="button"`, or `as="a"` with
+  `href` when it navigates.
+- **Name the remove button.** `TagCloseButton` is an icon-only `<button>` with
+  no name and no handler of its own. Pass `aria-label` (for example
+  `` `${label} 삭제` ``) and `onClick` (WCAG 4.1.2). Inside a `<form>`, also
+  pass `type="button"`, or it submits the form.
+- Group related filter chips under a label (`role="group"` with
+  `aria-label`, or a visible heading) so a screen reader knows what they
+  filter.
+- Words, not colour alone (WCAG 1.4.1): category hues only tell items apart;
+  the label carries the meaning.
+
+## Tokens
+
+The table is generated from `Tag.styles.ts` and the theme.
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 한 단어에서 세 단어까지 씁니다. 마침표를 찍지 않습니다.
+- 동사가 아니라 명사로 씁니다. "이미지 보기"가 아니라 "이미지"라고 씁니다.
+- 영어는 문장형 대소문자를 씁니다. 한국어 라벨에는 「」, 따옴표, 괄호를 두르지
+  않습니다.
+- 이름이 길면 라벨은 줄이고, 전체 이름은 삭제 버튼의 `aria-label`이나 `Tooltip`에
+  담습니다.
+
+## 접근성
+
+Tag가 알아서 하는 일
+
+- 기본 Tag는 `<span>`이라 버튼이나 링크 안에 넣어도 됩니다(구문 콘텐츠,
+  `ACCESSIBILITY.md` §5, KWCAG 5.4.1.1).
+- `as="button"`으로 그리면 `type="button"`, 토글일 때 `aria-pressed`, 기본
+  `disabled` 속성, 공통 초점 링이 붙습니다(WCAG 2.4.7, 4.1.2).
+- 링크나 누를 수 있는 span이 비활성이면 `aria-disabled`가 붙고, Tab 순서에서 빠지며,
+  클릭을 무시합니다.
+- 모든 tone과 `selected`의 글자 색은 라이트·다크 모두 대비 감사를 통과합니다(WCAG
+  1.4.3).
+
+직접 챙겨야 하는 일
+
+- **누를 수 있다면 버튼이나 링크로 그립니다**(WCAG 2.1.1). 기본 `<span>`에
+  `onClick`만 달면 키보드로 닿지 않습니다. `as="button"`을 쓰고, 다른 곳으로
+  이동한다면 `href`와 함께 `as="a"`를 씁니다.
+- **삭제 버튼에 이름을 붙입니다.** `TagCloseButton`은 아이콘만 있는 `<button>`이며,
+  이름도 동작도 스스로 갖지 않습니다. `aria-label`(예: `` `${label} 삭제` ``)과
+  `onClick`을 넘깁니다(WCAG 4.1.2). `<form>` 안에서는 `type="button"`도 넘겨야
+  폼이 제출되지 않습니다.
+- 관련된 필터 칩은 라벨로 묶습니다(`aria-label`을 단 `role="group"`, 또는 눈에 보이는
+  제목). 그래야 화면 낭독기 사용자가 무엇을 거르는 필터인지 압니다.
+- 색만으로 알리지 않습니다(WCAG 1.4.1). category 색은 항목을 나눌 뿐이고, 뜻은 라벨이
+  전합니다.
+
+## 토큰
+
+아래 표는 `Tag.styles.ts`와 테마에서 자동으로 만듭니다.
+
+</Ko>
+
+<Canvas of={TagStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **Badge**: a status or a well-defined system fact.
+- **CountBadge**: a number.
+- **Chip**: deprecated alias of Tag; see its migration table.
+- **SegmentedControl**: exactly one of a few options.
+- **Foundations/Brand & colour usage**: category hues vs status colours.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **Badge**: 상태나 뜻이 명확한 시스템 사실.
+- **CountBadge**: 숫자.
+- **Chip**: Tag의 지원 중단된 별칭. 바꾸는 방법은 Chip 페이지의 표를 봅니다.
+- **SegmentedControl**: 몇 가지 중 정확히 하나.
+- **Foundations/Brand & colour usage**: category 색과 상태색의 차이.
+
+</Ko>

package/src/components/Tag/index.ts

@@ -3,6 +3,7 @@ import { Icon } from '@chakra-ui/react';
 export { Tag } from './Tag';
 export type { LegacyTagResolution, TagStyleOptions } from './Tag.styles';
 export {
+  getTagSizeStyles,
   getTagStyles,
   mapLegacyTagProps,
   tagTones,
@@ -12,6 +13,7 @@ export type {
   TagColorPalette,
   TagOwnProps,
   TagProps,
+  TagSize,
   TagTone,
   TagVariant,
 } from './Tag.types';