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

package/src/components/Avatar/Avatar.stories.tsx

@@ -3,8 +3,16 @@ import { Meta, StoryObj } from '@storybook/react';
 
 import { SYSTEM_HUE_NAMES } from '@/theme/colors';
 
+import { TokenTable } from '../../guidelines/_components/TokenTable';
+import { Subtext } from '../Typography';
+import { SparklesIcon } from '../Icon';
 import { Avatar } from '.';
 
+const REACT_LOGO =
+  'https://cdn.jsdelivr.net/gh/devicons/devicon/icons/react/react-original.svg';
+const GITHUB_LOGO =
+  'https://cdn.jsdelivr.net/gh/devicons/devicon/icons/github/github-original.svg';
+
 const meta = {
   title: 'Components/Avatar',
   component: Avatar,
@@ -143,34 +151,14 @@ export const WithImage: Story = {
           />
         </HStack>
       </Box>
-      {/* Custom background override */}
+      {/* Logos: variant="logo" */}
       <Box>
         <Text fontSize="lg" fontWeight="bold" mb={4} color="fg.default">
-          Custom Background (bg prop)
+          Logos (variant=&quot;logo&quot;)
         </Text>
         <HStack gap={4}>
-          <VStack gap={2}>
-            <Avatar
-              name="GitHub"
-              src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/github/github-original.svg"
-              size="lg"
-              bg="white"
-            />
-            <Text fontSize="xs" color="fg.muted">
-              bg="white"
-            </Text>
-          </VStack>
-          <VStack gap={2}>
-            <Avatar
-              name="React"
-              src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/react/react-original.svg"
-              size="lg"
-              bg="category.blue.surface"
-            />
-            <Text fontSize="xs" color="fg.muted">
-              bg="category.blue.surface"
-            </Text>
-          </VStack>
+          <Avatar name="GitHub" src={GITHUB_LOGO} size="lg" variant="logo" />
+          <Avatar name="React" src={REACT_LOGO} size="lg" variant="logo" />
         </HStack>
       </Box>
     </VStack>
@@ -424,3 +412,190 @@ export const ExplicitHue: Story = {
     </Flex>
   ),
 };
+
+const SIZES = ['2xs', 'xs', 'sm', 'md', 'lg', 'xl', '2xl'] as const;
+const PEOPLE = ['박상현', 'Sean Park', '김지민', 'Jaeho Shin', '이서준'];
+
+/**
+ * The regression this recipe fixes: the hue must fill the whole circle at
+ * every size, with the initial centred — not a small pill around the glyph.
+ */
+export const InitialsEverySize: Story = {
+  render: () => (
+    <VStack gap={3} align="start">
+      {PEOPLE.map((name) => (
+        <HStack key={name} gap={4}>
+          <Box w="96px">
+            <Text fontSize="sm" color="fg.muted">
+              {name}
+            </Text>
+          </Box>
+          {SIZES.map((size) => (
+            <Avatar key={size} name={name} size={size} />
+          ))}
+        </HStack>
+      ))}
+      <HStack gap={4}>
+        <Box w="96px">
+          <Text fontSize="sm" color="fg.muted">
+            (no name)
+          </Text>
+        </Box>
+        {SIZES.map((size) => (
+          <Avatar key={size} size={size} />
+        ))}
+      </HStack>
+    </VStack>
+  ),
+};
+
+/**
+ * No name, no photo: the neutral pair (`category.neutral` →
+ * `bg.muted` / `secondary.fgStrong`) and Chakra's person icon — never red.
+ * `Avatar.Root` + `Avatar.Fallback` used bare get the same.
+ */
+export const NoName: Story = {
+  render: () => (
+    <HStack gap={4}>
+      <Avatar size="lg" />
+      <Avatar.Root size="lg">
+        <Avatar.Fallback />
+      </Avatar.Root>
+      <Avatar.Root size="lg">
+        <Avatar.Fallback name="Bare Root" />
+      </Avatar.Root>
+    </HStack>
+  ),
+};
+
+/**
+ * `variant="logo"`: the `bg.logo` tile, light in both modes, for model,
+ * chatbot and brand marks drawn for a light ground. With no image the
+ * fallback (an icon or initials) is centred on the tile.
+ */
+export const Logo: Story = {
+  render: () => (
+    <VStack gap={4} align="start">
+      <HStack gap={4}>
+        {SIZES.map((size) => (
+          <Avatar
+            key={size}
+            size={size}
+            variant="logo"
+            name="React"
+            src={REACT_LOGO}
+          />
+        ))}
+      </HStack>
+      <HStack gap={4}>
+        {SIZES.map((size) => (
+          <Avatar.Root key={size} size={size} variant="logo">
+            <Avatar.Fallback>
+              <SparklesIcon boxSize="50%" aria-hidden />
+            </Avatar.Fallback>
+          </Avatar.Root>
+        ))}
+      </HStack>
+      <HStack gap={4}>
+        {SIZES.map((size) => (
+          <Avatar key={size} size={size} variant="logo" name="Chat Bot" />
+        ))}
+      </HStack>
+    </VStack>
+  ),
+};
+
+/**
+ * `Avatar.Group` `max`: the avatars past `max` collapse into a "+N" counter in
+ * the neutral pair, whatever the group's variant.
+ */
+export const GroupMax: Story = {
+  render: () => {
+    const names = ['김지민', '이서준', '박하은', '최유나', '정민호', '한도윤'];
+    return (
+      <VStack gap={6} align="start">
+        {(['sm', 'md', 'lg'] as const).map((size) => (
+          <Avatar.Group key={size} size={size} max={3}>
+            {names.map((name) => (
+              <Avatar key={name} name={name} />
+            ))}
+          </Avatar.Group>
+        ))}
+        <Avatar.Group size="md" max={2} variant="logo">
+          <Avatar name="React" src={REACT_LOGO} />
+          <Avatar name="GitHub" src={GITHUB_LOGO} />
+          <Avatar name="Chat Bot" />
+          <Avatar name="Other" />
+        </Avatar.Group>
+      </VStack>
+    );
+  },
+};
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `Avatar.usage.mdx` with <Canvas of={…} />. Hidden from the
+// sidebar (`!dev`); `tags` is written out on each story because the indexer
+// reads CSF statically.
+
+const MEMBERS = ['김지민', '이서준', '박하은'];
+
+export const DoNameNextToIt: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: the name next to the avatar',
+  render: () => (
+    <VStack align="start" gap={3}>
+      {MEMBERS.map((name) => (
+        <HStack key={name} gap={3}>
+          <Avatar size="sm" name={name} aria-hidden />
+          <Box>
+            <Text fontWeight="medium">{name}</Text>
+            <Subtext color="fg.muted">멤버</Subtext>
+          </Box>
+        </HStack>
+      ))}
+    </VStack>
+  ),
+};
+
+export const DontHueAsStatus: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: a hue to mean a status",
+  render: () => (
+    <HStack gap={3}>
+      <Avatar size="sm" name="김지민" colorHue="green" />
+      <Avatar size="sm" name="이서준" colorHue="red" />
+      <Avatar size="sm" name="박하은" colorHue="yellow" />
+    </HStack>
+  ),
+};
+
+/**
+ * Fallback colours per hue — the `category.{hue}` palette the avatar recipe
+ * paints the root with. The first row is the `category.neutral` pair used with
+ * no name; the last rows are the `logo` variant's tile.
+ */
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={[
+        { token: 'category.neutral.surface', use: 'no name · background' },
+        { token: 'category.neutral.fg', use: 'no name · initials' },
+        ...SYSTEM_HUE_NAMES.flatMap((hue) => [
+          { token: `category.${hue}.surface`, use: `${hue} · background` },
+          { token: `category.${hue}.fg`, use: `${hue} · initials` },
+        ]),
+        { token: 'border.subtle', use: 'border' },
+        {
+          token: 'bg.logo',
+          use: 'variant="logo" · tile (light in both modes)',
+        },
+        { token: 'fg.onLogo', use: 'variant="logo" · initials' },
+      ]}
+    />
+  ),
+};

package/src/components/Avatar/Avatar.tsx

@@ -1,27 +1,66 @@
-import { forwardRef } from 'react';
 import {
-  Avatar as ChakraAvatar,
+  Children,
+  type ComponentProps,
+  forwardRef,
+  type ForwardRefExoticComponent,
+  type ReactNode,
+  type RefAttributes,
+} from 'react';
+import {
   AvatarContext,
   AvatarFallback,
-  AvatarGroup,
+  AvatarGroup as ChakraAvatarGroup,
+  AvatarGroupProps as ChakraAvatarGroupProps,
   AvatarIcon,
   AvatarImage,
-  AvatarRoot,
+  AvatarRoot as ChakraAvatarRoot,
   AvatarRootProps as ChakraAvatarRootProps,
-  AvatarRootProvider,
+  AvatarRootProvider as ChakraAvatarRootProvider,
+  type ConditionalValue,
 } from '@chakra-ui/react';
 
 import { SYSTEM_HUE_NAMES, SystemHue } from '@/theme/colors';
 
 export type {
   AvatarFallbackProps,
-  AvatarGroupProps,
   AvatarIconProps,
   AvatarImageProps,
-  AvatarRootProps,
 } from '@chakra-ui/react';
 
-export type AvatarProps = ChakraAvatarRootProps & {
+/**
+ * Chakra's variants plus Logician's `logo`. Chakra types `variant` from its
+ * own recipe, so the theme-level `logo` variant needs widening here.
+ */
+export type AvatarVariant = 'subtle' | 'solid' | 'outline' | 'logo';
+
+/** `P` with `variant` widened to {@link AvatarVariant}. */
+type WithAvatarVariant<P> = Omit<P, 'variant'> & {
+  /**
+   * `subtle` (default): the `colorPalette` fill — a person's category hue, or
+   * the neutral pair. `logo`: the light `bg.logo` tile for model, chatbot and
+   * brand marks, the same in both modes.
+   */
+  variant?: ConditionalValue<AvatarVariant>;
+};
+
+export type AvatarRootProps = WithAvatarVariant<ChakraAvatarRootProps>;
+export type AvatarRootProviderProps = WithAvatarVariant<
+  ComponentProps<typeof ChakraAvatarRootProvider>
+>;
+
+// Chakra's parts, typed for the `logo` variant.
+const AvatarRoot = ChakraAvatarRoot as ForwardRefExoticComponent<
+  AvatarRootProps & RefAttributes<HTMLDivElement>
+>;
+const AvatarRootProvider =
+  ChakraAvatarRootProvider as ForwardRefExoticComponent<
+    AvatarRootProviderProps & RefAttributes<HTMLDivElement>
+  >;
+const ChakraAvatarGroupTyped = ChakraAvatarGroup as ForwardRefExoticComponent<
+  WithAvatarVariant<ChakraAvatarGroupProps> & RefAttributes<HTMLDivElement>
+>;
+
+export type AvatarProps = AvatarRootProps & {
   src?: string;
   name?: string;
   /**
@@ -35,6 +74,19 @@ export type AvatarProps = ChakraAvatarRootProps & {
   colorHue?: SystemHue;
 };
 
+export interface AvatarGroupProps extends Omit<
+  WithAvatarVariant<ChakraAvatarGroupProps>,
+  'children'
+> {
+  children?: ReactNode;
+  /**
+   * Show at most this many avatars; the rest collapse into a trailing "+N"
+   * counter in the neutral pair. Omit to show all. Chakra 3 dropped 2.x's
+   * `max`; this restores it.
+   */
+  max?: number;
+}
+
 /**
  * A stable hash of `name` into one of `SYSTEM_HUE_NAMES`, so a given name
  * always lands on the same hue (no lookup table, nothing to keep in sync) and
@@ -60,9 +112,26 @@ export function hueForName(name: string | undefined): SystemHue | undefined {
   return SYSTEM_HUE_NAMES[index];
 }
 
+/**
+ * The `colorPalette` an avatar paints with: `category.<hue>` for a person
+ * (`colorHue`, else {@link hueForName}), `category.neutral` with no name. The
+ * avatar recipe maps `colorPalette.surface` / `colorPalette.fg` onto it.
+ */
+export function avatarColorPalette(
+  name: string | undefined,
+  colorHue?: SystemHue
+): `category.${SystemHue | 'neutral'}` {
+  const hue = colorHue ?? hueForName(name);
+  return hue ? `category.${hue}` : 'category.neutral';
+}
+
 /**
  * Fallback (initials / icon) colours: the person's hue when there is one,
  * otherwise the neutral pair Badge `neutral` uses.
+ *
+ * @deprecated The avatar recipe now paints the root from `colorPalette` (see
+ * {@link avatarColorPalette}); `Avatar` no longer calls this. Kept for
+ * callers that colour a non-avatar element to match a person. Removed in 6.0.
  */
 export function avatarFallbackColors(
   name: string | undefined,
@@ -73,26 +142,54 @@ export function avatarFallbackColors(
   return { bg: `category.${hue}.surface`, color: `category.${hue}.fg` };
 }
 
+/**
+ * Chakra's `AvatarGroup` (overlapping avatars; `size` / `variant` reach every
+ * child through the recipe props context) with the `max` overflow cap. The
+ * counter is always the neutral `subtle` pair, whatever the group's variant:
+ * it is a count, not a person or a logo.
+ */
+const AvatarGroup = forwardRef<HTMLDivElement, AvatarGroupProps>(
+  ({ max, children, ...rest }, ref) => {
+    const items = Children.toArray(children);
+    const visible =
+      typeof max === 'number' ? items.slice(0, Math.max(0, max)) : items;
+    const overflow = items.length - visible.length;
+    return (
+      <ChakraAvatarGroupTyped ref={ref} {...rest}>
+        {visible}
+        {overflow > 0 && (
+          // Spans so a group inside a button (a popover trigger) stays phrasing
+          // content; the recipe sets the display, so nothing else changes.
+          <AvatarRoot
+            as="span"
+            colorPalette="category.neutral"
+            variant="subtle"
+          >
+            <AvatarFallback as="span">+{overflow}</AvatarFallback>
+          </AvatarRoot>
+        )}
+      </ChakraAvatarGroupTyped>
+    );
+  }
+);
+
+AvatarGroup.displayName = 'AvatarGroup';
+
 const AvatarComponent = forwardRef<HTMLDivElement, AvatarProps>(
   (props, ref) => {
     const { src, name, colorHue, ...rest } = props;
-    const fallback = avatarFallbackColors(name, colorHue);
+    // Fill, text colour, border and the full-circle fallback all come from
+    // the avatar recipe (src/theme/recipes/avatar.ts); only the palette is
+    // chosen here. A caller's own `colorPalette` still wins.
     return (
-      <ChakraAvatar.Root
+      <AvatarRoot
         ref={ref}
-        borderWidth="1px"
-        borderColor="border.subtle"
-        overflow="hidden"
-        bgColor="transparent"
+        colorPalette={avatarColorPalette(name, colorHue)}
         {...rest}
       >
-        <ChakraAvatar.Fallback
-          name={name}
-          bg={fallback.bg}
-          color={fallback.color}
-        />
-        <ChakraAvatar.Image src={src} />
-      </ChakraAvatar.Root>
+        <AvatarFallback name={name} />
+        <AvatarImage src={src} />
+      </AvatarRoot>
     );
   }
 );

package/src/components/Avatar/Avatar.usage.mdx

@@ -0,0 +1,185 @@
+import { Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as AvatarStories from './Avatar.stories';
+
+<Meta of={AvatarStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# Avatar
+
+A person's photo, or their initials when there is no photo. The initials are
+tinted with one of the twelve category hues, picked from a stable hash of
+`name`, so the same person has the same colour everywhere without storing
+one.
+
+## When to use
+
+- Next to a person's name in a member list, a table row, a comment, or the
+  account menu.
+- A stack of people (`Avatar.Group`) where the count matters more than each
+  name.
+
+## When not to use
+
+- A chatbot, tenant or product logo as an avatar → `variant="logo"`, which
+  swaps the person's hue for the light `bg.logo` tile those marks are drawn
+  for (light in both modes). Anywhere else a logo is just an `<img>` with alt
+  text: an avatar without `variant="logo"` implies a person.
+- A status (online, blocked) → `Badge` next to the name. Avatar has no status
+  colours.
+
+## Options
+
+| Prop | Means |
+| --- | --- |
+| `src` | Photo URL. While it loads, or if it fails, the fallback shows. |
+| `name` | Used for the initials and the hue. With no name, the fallback is the neutral pair (`bg.muted` / `secondary.fgStrong`), never red. |
+| `colorHue` | Overrides the hashed hue. Identity only, never status. |
+| `size` | Chakra sizes, `2xs` to `2xl` and `full`. |
+| `variant` | `subtle` (default): the person's hue, or the neutral pair. `logo`: the light `bg.logo` tile for model and chatbot marks, with `fg.onLogo` initials. |
+| `colorPalette` | Set for you from `name` / `colorHue` (`category.<hue>`, or `category.neutral`). Pass one only to colour a bare `Avatar.Root`. |
+| `Avatar.Group` `max` | Show at most this many; the rest become a "+N" counter in the neutral pair. |
+
+The fill, text colour and border belong to the avatar recipe, and the
+fallback fills the whole circle, so `Avatar.Root` + `Avatar.Fallback` need no
+styling of their own. Do not pass `bg` / `color` to recolour an avatar.
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+# Avatar
+
+사람의 사진, 사진이 없으면 이름 머리글자를 보여 주는 컴포넌트입니다. 머리글자는 열두
+가지 category 색 가운데 하나로 칠해지는데, `name`의 고정 해시로 고르므로 색을 따로
+저장하지 않아도 같은 사람은 어디서나 같은 색입니다.
+
+## 언제 쓰나요
+
+- 멤버 목록, 표의 행, 댓글, 계정 메뉴에서 사람 이름 옆에.
+- 이름 하나하나보다 사람 수가 중요한 묶음(`Avatar.Group`).
+
+## 언제 쓰지 않나요
+
+- 챗봇, 기관, 제품 로고를 아바타 자리에 둘 때는 `variant="logo"`를 씁니다. 사람의
+  색 대신, 그 로고들이 전제하는 밝은 `bg.logo` 타일(라이트·다크 모두 밝음)을 깝니다.
+  그 밖의 자리에서 로고는 대체 글이 있는 `<img>`입니다. `variant="logo"`가 없는
+  Avatar는 사람을 뜻합니다.
+- 상태(접속 중, 차단됨)는 이름 옆의 `Badge`로 알립니다. Avatar에는 상태색이 없습니다.
+
+## 옵션
+
+| 속성 | 뜻 |
+| --- | --- |
+| `src` | 사진 URL. 불러오는 동안이나 실패하면 대체 표시가 나옵니다. |
+| `name` | 머리글자와 색을 정합니다. 이름이 없으면 중립 색(`bg.muted` / `secondary.fgStrong`)을 쓰고, 빨강은 쓰지 않습니다. |
+| `colorHue` | 해시로 고른 색을 바꿉니다. 사람을 구분할 때만 쓰고 상태에는 쓰지 않습니다. |
+| `size` | Chakra 크기. `2xs`부터 `2xl`, `full`. |
+| `variant` | `subtle`(기본): 사람의 색, 이름이 없으면 중립 색. `logo`: 모델·챗봇 로고용 밝은 `bg.logo` 타일, 머리글자는 `fg.onLogo`. |
+| `colorPalette` | `name` / `colorHue`로 자동으로 정해집니다(`category.<hue>`, 또는 `category.neutral`). `Avatar.Root`를 직접 쓸 때만 넘깁니다. |
+| `Avatar.Group` `max` | 이 수까지만 보여 주고 나머지는 중립 색 "+N" 표시로 묶습니다. |
+
+배경, 글자 색, 테두리는 아바타 레시피가 정하고 대체 표시는 원 전체를 채웁니다.
+그래서 `Avatar.Root` + `Avatar.Fallback`에는 따로 스타일을 줄 필요가 없습니다.
+아바타 색을 바꾸려고 `bg` / `color`를 넘기지 마세요.
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={AvatarStories.DoNameNextToIt} />
+<Verdict
+  kind="do"
+  en="Show the name as text next to the avatar, and hide the avatar from assistive technology so the name is read once."
+  ko="아바타 옆에 이름을 글자로 보여 주고, 아바타는 보조 기술에서 숨겨 이름이 한 번만 읽히게 합니다."
+/>
+
+<Canvas of={AvatarStories.DontHueAsStatus} />
+<Verdict
+  kind="dont"
+  en="Pick green, red or yellow to mean active, blocked or pending. The hue only tells people apart; readers will not know it changed meaning."
+  ko="활성, 차단, 대기를 나타내려고 초록, 빨강, 노랑을 고르지 마세요. 색은 사람을 구분할 뿐이라, 뜻이 바뀌었다는 것을 읽는 사람은 알 수 없습니다."
+/>
+
+<En>
+
+## Content
+
+- Pass the display name the user knows (김지민), not an email, so the
+  initials make sense.
+
+## Accessibility
+
+What Avatar does for you:
+
+- With no photo, the initials are real text, so they are read.
+
+What you still have to do:
+
+- **The photo has no alt text.** `Avatar` does not pass one to the image, so
+  a loaded photo is an `<img>` without `alt` (WCAG 1.1.1). Show the name as
+  text next to it and put `aria-hidden` on the Avatar, as in the Do example.
+  An avatar on its own (a toolbar account button) gets its name from the
+  button's `aria-label`.
+- Do not use the hue to carry meaning (WCAG 1.4.1).
+
+## Tokens
+
+The `category.*` pairs the avatar recipe reads through `colorPalette`, and the
+`logo` tile.
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 이메일이 아니라 사용자가 아는 표시 이름(김지민)을 넘겨야 머리글자가 뜻이 통합니다.
+
+## 접근성
+
+Avatar가 알아서 하는 일
+
+- 사진이 없으면 머리글자가 실제 글자라서 읽힙니다.
+
+직접 챙겨야 하는 일
+
+- **사진에 대체 글이 없습니다.** `Avatar`가 이미지에 alt를 넘기지 않아서, 사진을
+  불러오면 `alt` 없는 `<img>`가 됩니다(WCAG 1.1.1). 이름을 옆에 글자로 보여 주고
+  Avatar에는 `aria-hidden`을 붙입니다(이렇게 하세요 예시처럼). 아바타만 있는 경우(도구
+  모음의 계정 버튼)에는 버튼의 `aria-label`로 이름을 붙입니다.
+- 색에 뜻을 담지 않습니다(WCAG 1.4.1).
+
+## 토큰
+
+아바타 레시피가 `colorPalette`로 읽는 `category.*` 쌍과 `logo` 타일입니다.
+
+</Ko>
+
+<Canvas of={AvatarStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **Badge**: a person's status next to their name.
+- **Table**: member lists.
+- **Foundations/Brand & colour usage**: category hues carry no meaning.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **Badge**: 이름 옆의 상태.
+- **Table**: 멤버 목록.
+- **Foundations/Brand & colour usage**: category 색에는 뜻이 없습니다.
+
+</Ko>

package/src/components/Avatar/index.tsx

@@ -5,5 +5,12 @@ export type {
   AvatarImageProps,
   AvatarProps,
   AvatarRootProps,
+  AvatarRootProviderProps,
+  AvatarVariant,
+} from './Avatar';
+export {
+  Avatar,
+  avatarColorPalette,
+  avatarFallbackColors,
+  hueForName,
 } from './Avatar';
-export { Avatar, avatarFallbackColors, hueForName } from './Avatar';