@mindlogic-ai/logician-ui 4.0.0-alpha.9 → 5.0.0-alpha.0

package/src/components/Menu/Menu.stories.tsx

@@ -1,9 +1,9 @@
-import type { Meta, StoryObj } from '@storybook/react';
 import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
 
+import { Button } from '../Button/Button';
 import { IoChevronDownOutline, SlSettings } from '../Icon';
 import { IconButton } from '../IconButton';
-import { Button } from '../Button/Button';
 import { Menu } from './Menu';
 import { MenuItemProps } from './MenuItem.types';
 
@@ -44,7 +44,7 @@ export default meta;
 type Story = StoryObj<MenuStoryProps>;
 
 const renderItems = (items: StoryMenuItemData[]) =>
-  items.map(item => (
+  items.map((item) => (
     <Menu.Item
       key={item.label}
       value={item.label}
@@ -61,7 +61,7 @@ export const Default: Story = {
   render: ({ label, baseFontSize, menuItems }) => (
     <Menu baseFontSize={baseFontSize}>
       <Menu.Trigger asChild>
-        <Button variant="outline">
+        <Button variant="secondary">
           {label} <IoChevronDownOutline />
         </Button>
       </Menu.Trigger>
@@ -73,14 +73,22 @@ export const Default: Story = {
 export const WithIcons: Story = {
   args: {
     menuItems: [
-      { label: 'Profile', onClick: () => alert('Profile clicked'), itemIcon: <SlSettings /> },
-      { label: 'Settings', onClick: () => alert('Settings clicked'), itemIcon: <SlSettings /> },
+      {
+        label: 'Profile',
+        onClick: () => alert('Profile clicked'),
+        itemIcon: <SlSettings />,
+      },
+      {
+        label: 'Settings',
+        onClick: () => alert('Settings clicked'),
+        itemIcon: <SlSettings />,
+      },
     ],
   },
   render: ({ label, baseFontSize, menuItems }) => (
     <Menu baseFontSize={baseFontSize}>
       <Menu.Trigger asChild>
-        <Button variant="outline">
+        <Button variant="secondary">
           {label} <IoChevronDownOutline />
         </Button>
       </Menu.Trigger>
@@ -92,14 +100,22 @@ export const WithIcons: Story = {
 export const WithRightIcons: Story = {
   args: {
     menuItems: [
-      { label: 'Profile', onClick: () => alert('Profile clicked'), rightItemIcon: <SlSettings /> },
-      { label: 'Settings', onClick: () => alert('Settings clicked'), rightItemIcon: <SlSettings /> },
+      {
+        label: 'Profile',
+        onClick: () => alert('Profile clicked'),
+        rightItemIcon: <SlSettings />,
+      },
+      {
+        label: 'Settings',
+        onClick: () => alert('Settings clicked'),
+        rightItemIcon: <SlSettings />,
+      },
     ],
   },
   render: ({ label, baseFontSize, menuItems }) => (
     <Menu baseFontSize={baseFontSize}>
       <Menu.Trigger asChild>
-        <Button variant="outline">
+        <Button variant="secondary">
           {label} <IoChevronDownOutline />
         </Button>
       </Menu.Trigger>
@@ -111,14 +127,24 @@ export const WithRightIcons: Story = {
 export const WithBothIcons: Story = {
   args: {
     menuItems: [
-      { label: 'Profile', itemIcon: <SlSettings />, rightItemIcon: <IoChevronDownOutline />, onClick: () => alert('Profile clicked') },
-      { label: 'Settings', itemIcon: <SlSettings />, rightItemIcon: <IoChevronDownOutline />, onClick: () => alert('Settings clicked') },
+      {
+        label: 'Profile',
+        itemIcon: <SlSettings />,
+        rightItemIcon: <IoChevronDownOutline />,
+        onClick: () => alert('Profile clicked'),
+      },
+      {
+        label: 'Settings',
+        itemIcon: <SlSettings />,
+        rightItemIcon: <IoChevronDownOutline />,
+        onClick: () => alert('Settings clicked'),
+      },
     ],
   },
   render: ({ label, baseFontSize, menuItems }) => (
     <Menu baseFontSize={baseFontSize}>
       <Menu.Trigger asChild>
-        <Button variant="outline">
+        <Button variant="secondary">
           {label} <IoChevronDownOutline />
         </Button>
       </Menu.Trigger>
@@ -131,13 +157,18 @@ export const WithDangerItem: Story = {
   args: {
     menuItems: [
       { label: 'Profile', onClick: () => alert('Profile clicked') },
-      { label: 'Delete', onClick: () => alert('Delete clicked'), itemIcon: <SlSettings />, variant: 'danger' },
+      {
+        label: 'Delete',
+        onClick: () => alert('Delete clicked'),
+        itemIcon: <SlSettings />,
+        variant: 'danger',
+      },
     ],
   },
   render: ({ label, baseFontSize, menuItems }) => (
     <Menu baseFontSize={baseFontSize}>
       <Menu.Trigger asChild>
-        <Button variant="outline">
+        <Button variant="secondary">
           {label} <IoChevronDownOutline />
         </Button>
       </Menu.Trigger>
@@ -151,7 +182,9 @@ export const IconButtonTrigger: Story = {
   render: ({ baseFontSize, menuItems }) => (
     <Menu baseFontSize={baseFontSize}>
       <Menu.Trigger asChild>
-        <IconButton aria-label="Open menu"><IoChevronDownOutline /></IconButton>
+        <IconButton aria-label="Open menu">
+          <IoChevronDownOutline />
+        </IconButton>
       </Menu.Trigger>
       <Menu.List>{renderItems(menuItems)}</Menu.List>
     </Menu>
@@ -160,21 +193,26 @@ export const IconButtonTrigger: Story = {
 
 export const SelectiveIcon: Story = {
   render: function SelectiveIconRender({ label, baseFontSize, menuItems }) {
-    const [selectedLabel, setSelectedLabel] = useState<string | null>(menuItems[0].label);
+    const [selectedLabel, setSelectedLabel] = useState<string | null>(
+      menuItems[0].label
+    );
 
     return (
       <Menu baseFontSize={baseFontSize}>
         <Menu.Trigger asChild>
-          <Button variant="outline">
+          <Button variant="secondary">
             {label} <IoChevronDownOutline />
           </Button>
         </Menu.Trigger>
         <Menu.List>
-          {menuItems.map(item => (
+          {menuItems.map((item) => (
             <Menu.Item
               key={item.label}
               value={item.label}
-              onClick={() => { setSelectedLabel(item.label); item.onClick?.(); }}
+              onClick={() => {
+                setSelectedLabel(item.label);
+                item.onClick?.();
+              }}
               icon={selectedLabel === item.label ? <SlSettings /> : undefined}
             >
               {item.label}

package/src/components/Menu/MenuItem.highlight.test.tsx

@@ -0,0 +1,72 @@
+import { ChakraProvider } from '@chakra-ui/react';
+import { act, fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+
+import { system } from '../../theme';
+import { Menu } from './Menu';
+import { ItemVariant } from './MenuItem.types';
+
+/**
+ * Zag menus never hover-highlight through `:hover` alone: the active row carries
+ * `data-highlighted` (keyboard and pointer alike). Item colours set only under
+ * `_hover` left arrow-key navigation on Chakra's recipe `bg.emphasized/60`.
+ */
+const cssText = () =>
+  Array.from(document.querySelectorAll('style'))
+    .map((s) => s.textContent ?? '')
+    .join('\n');
+
+/** Every rule body whose selector targets this element's classes and `[data-highlighted]`. */
+const highlightedRules = (el: HTMLElement) => {
+  const css = cssText();
+  return Array.from(el.classList).flatMap((cls) => {
+    const out: string[] = [];
+    const re = new RegExp(
+      `\\.${cls.replace(/[^\w-]/g, (c) => `\\\\${c}`)}[^{}]*data-highlighted[^{}]*\\{([^}]*)\\}`,
+      'g'
+    );
+    for (const m of css.matchAll(re)) out.push(m[1]);
+    return out;
+  });
+};
+
+const renderMenu = () =>
+  render(
+    <ChakraProvider value={system}>
+      <Menu defaultOpen>
+        <Menu.Trigger>open</Menu.Trigger>
+        <Menu.List portalled={false}>
+          <Menu.Item value="edit">Edit</Menu.Item>
+          <Menu.Item value="delete" variant={ItemVariant.Danger}>
+            Delete
+          </Menu.Item>
+        </Menu.List>
+      </Menu>
+    </ChakraProvider>
+  );
+
+describe('MenuItem highlight', () => {
+  it('arrow keys highlight the row with the item role tokens', async () => {
+    renderMenu();
+    const menu = await screen.findByRole('menu');
+    await act(async () => {
+      fireEvent.keyDown(menu, { key: 'ArrowDown' });
+    });
+    const items = screen.getAllByRole('menuitem');
+    const highlighted = items.find((i) => i.hasAttribute('data-highlighted'));
+    expect(highlighted).toBeDefined();
+
+    const rules = highlightedRules(items[0]).join(';');
+    expect(rules).toContain('--chakra-colors-primary-wash');
+    expect(rules).toContain('--chakra-colors-fg-default');
+  });
+
+  it('the danger row highlights with danger.bg', async () => {
+    renderMenu();
+    await screen.findByRole('menu');
+    const danger = screen.getByRole('menuitem', { name: 'Delete' });
+    expect(highlightedRules(danger).join(';')).toContain(
+      '--chakra-colors-danger-bg'
+    );
+  });
+});

package/src/components/Menu/MenuItem.tsx

@@ -2,33 +2,39 @@ import { Menu, Spacer } from '@chakra-ui/react';
 
 import { focusRing } from '@/utils/focusRing';
 
-import { ItemVariant, MenuItemProps } from './MenuItem.types';
+import { polymorphic } from '../../types/polymorphic';
+import { ItemVariant, MenuItemOwnProps } from './MenuItem.types';
 
-export const MenuItem = ({
+const MenuItemImpl = ({
   variant = ItemVariant.Default,
   value,
   children,
   icon,
   rightIcon,
   ...rest
-}: MenuItemProps) => {
+}: MenuItemOwnProps) => {
   const isDangerVariant = variant === ItemVariant.Danger;
 
   return (
     <Menu.Item
       value={value}
       // Map item text/hover onto semantic tokens so they flip with the mode.
-      // Was gray.1000 / hover gray.1500 / hover bg gray.50 — none flipped, so
-      // items rendered dim and hover went near-black on a dark menu.
-      color={isDangerVariant ? 'danger.main' : 'fg.muted'}
+      color={isDangerVariant ? 'danger.fg' : 'fg.muted'}
       py={2}
       minW="fit-content"
       fontWeight="semibold"
       gap={3}
       cursor="pointer"
-      _hover={{
-        color: isDangerVariant ? 'danger.main' : 'fg.default',
-        backgroundColor: isDangerVariant ? 'danger.lightest' : 'bg.subtle',
+      // Same as `Button`: the style prop outranks the recipe's disabled cursor.
+      _disabled={{ cursor: 'not-allowed' }}
+      // `_highlighted`, not `_hover`: Zag keeps DOM focus on the menu content
+      // and marks the active row with `data-highlighted` (aria-activedescendant),
+      // setting it on pointer move as well as on arrow keys. A `_hover`-only
+      // block left keyboard navigation on Chakra's recipe `bg.emphasized/60`,
+      // and the danger row never showed `danger.bg`.
+      _highlighted={{
+        color: isDangerVariant ? 'danger.fg' : 'fg.default',
+        backgroundColor: isDangerVariant ? 'danger.bg' : 'primary.wash',
       }}
       {...focusRing}
       {...rest}
@@ -40,3 +46,8 @@ export const MenuItem = ({
     </Menu.Item>
   );
 };
+
+/** Type-level polymorphism over the same runtime — see the note on `Button`. */
+MenuItemImpl.displayName = 'MenuItem';
+
+export const MenuItem = polymorphic<MenuItemOwnProps, 'div'>(MenuItemImpl);

package/src/components/Menu/MenuItem.types.ts

@@ -1,5 +1,11 @@
+import type { ElementType } from 'react';
 import { MenuItemProps as ChakraMenuItemProps } from '@chakra-ui/react';
 
+// Relative, NOT `@/types/*`. Path aliases survive into the emitted `.d.ts` and
+// resolve against the CONSUMER's tsconfig, which silently degrades the type to
+// `any`. See `src/types/polymorphic.ts`.
+import type { PolymorphicProps } from '../../types/polymorphic';
+
 export const ItemVariant = {
   Default: 'default',
   Danger: 'danger',
@@ -7,9 +13,24 @@ export const ItemVariant = {
 
 export type ItemVariant = (typeof ItemVariant)[keyof typeof ItemVariant];
 
-export interface MenuItemProps extends ChakraMenuItemProps {
+export type MenuItemOwnProps = Omit<ChakraMenuItemProps, 'as'> & {
   value: string; // Required in Chakra v3 for menu item identification
   variant?: ItemVariant | null;
   icon?: React.ReactElement;
   rightIcon?: React.ReactElement;
-}
+};
+
+/**
+ * Props for `MenuItem`, typed for whatever element `as` renders.
+ *
+ * A menu item that navigates is the single most common `as` site in a menu —
+ * rendering it as a real link is also the accessible choice, since it keeps
+ * middle-click and "open in new tab" working. Defaults to `'div'` (what
+ * Chakra's `Menu.Item` renders), so bare `MenuItemProps` is unchanged.
+ *
+ * ```tsx
+ * <MenuItem value="admin" as={NextLink} href="/admin" target="_blank">관리자</MenuItem>
+ * ```
+ */
+export type MenuItemProps<TElement extends ElementType = 'div'> =
+  PolymorphicProps<TElement, MenuItemOwnProps>;

package/src/components/Menu/MenuList.tsx

@@ -1,21 +1,48 @@
-import { forwardRef } from 'react';
+import { Children, cloneElement, forwardRef, isValidElement } from 'react';
 import {
   Menu,
   MenuContentProps as ChakraMenuContentProps,
   Portal,
 } from '@chakra-ui/react';
 
+import { staggerProps } from '@/utils/staggerProps';
+
 import { ScaledContext } from '../ScaledContext';
 import { useMenuContext } from './Menu.types';
 
 export type MenuListProps = ChakraMenuContentProps & {
   portalled?: boolean;
+  /**
+   * Deal the rows in one after another instead of showing the menu as one
+   * block.
+   *
+   * Opt-in rather than the default: it suits a short menu opened deliberately,
+   * and works against a long one or a menu reopened repeatedly in the same
+   * gesture, where the reader already knows what is in it and is only waiting
+   * for the row they came for.
+   */
+  stagger?: boolean;
 };
 
 export const MenuList = forwardRef<HTMLDivElement, MenuListProps>(
-  ({ children, portalled = true, ...rest }, ref) => {
+  ({ children, portalled = true, stagger = false, ...rest }, ref) => {
     const { baseFontSize } = useMenuContext();
 
+    // Cloned rather than asking the call site to thread an index through every
+    // `Menu.Item`: the index is a fact about the list, and the list is here.
+    // Anything that is not an element — a bare string, the `false` from a
+    // `{cond && <Item/>}` branch — passes through untouched rather than
+    // throwing. Such a branch still consumes its index, so a hidden row leaves a
+    // gap in the rhythm; below the cap that is a 35ms hole nobody sees, and
+    // renumbering would cost a second pass to buy nothing.
+    const rows = stagger
+      ? Children.map(children, (child, index) =>
+          isValidElement(child)
+            ? cloneElement(child, staggerProps(index))
+            : child
+        )
+      : children;
+
     const content = (
       <Menu.Positioner>
         <Menu.Content
@@ -26,13 +53,18 @@ export const MenuList = forwardRef<HTMLDivElement, MenuListProps>(
           // Light keeps its original near-white halo; dark uses a real dark
           // shadow so the menu doesn't glow against the dark canvas.
           boxShadow={{
-            base: '0 5px 20px 1px {colors.gray.50}',
+            base: '0 5px 20px 1px {colors.neutral.1}',
             _dark: '0 5px 20px 1px rgba(0, 0, 0, 0.5)',
           }}
           p="1.5"
+          // Chakra's recipe opens the menu in 150ms and closes it in 100 —
+          // nearly symmetric, and shorter than everything else that appears
+          // over the page. `presence-anchored` puts it on the house enter/exit ratio;
+          // the slide-from-the-trigger movement is the recipe's and stays.
+          animationStyle="presence-anchored"
           {...rest}
         >
-          <ScaledContext fontSize={baseFontSize}>{children}</ScaledContext>
+          <ScaledContext fontSize={baseFontSize}>{rows}</ScaledContext>
         </Menu.Content>
       </Menu.Positioner>
     );

package/src/components/Modal/Modal.stories.tsx

@@ -17,9 +17,11 @@
  *
  * @see ModalCloseButton.tsx - 구현 세부사항 확인
  */
+import { useState } from 'react';
 import { Meta, StoryObj } from '@storybook/react';
 
-import { useState } from 'react';
+import { Button } from '../Button';
+import { ButtonVariant } from '../Button/Button.types';
 import {
   Modal,
   ModalBody,
@@ -28,8 +30,6 @@ import {
   ModalFooter,
   ModalHeader,
 } from '.';
-import { Button } from '../Button';
-import { ButtonVariant } from '../Button/Button.types';
 
 interface ModalArgs {
   headerTitle: string;
@@ -74,7 +74,7 @@ export const Default: Story = {
             {args.footerButtons && (
               <ModalFooter>
                 {args.footerButtons.map((button, index) => (
-                  <Button key={index} variant={button.variant || 'soft'}>
+                  <Button key={index} variant={button.variant || 'subtle'}>
                     {button.label}
                   </Button>
                 ))}
@@ -105,7 +105,7 @@ export const WithHeader: Story = {
             {args.footerButtons && (
               <ModalFooter>
                 {args.footerButtons.map((button, index) => (
-                  <Button key={index} variant={button.variant || 'soft'}>
+                  <Button key={index} variant={button.variant || 'subtle'}>
                     {button.label}
                   </Button>
                 ))}
@@ -137,7 +137,7 @@ export const WithFooterButton: Story = {
             {args.footerButtons && (
               <ModalFooter>
                 {args.footerButtons.map((button, index) => (
-                  <Button key={index} variant={button.variant || 'soft'}>
+                  <Button key={index} variant={button.variant || 'subtle'}>
                     {button.label}
                   </Button>
                 ))}
@@ -154,7 +154,7 @@ export const TwoButtons: Story = {
   args: {
     footerButtons: [
       { label: 'Cancel', variant: 'ghost' },
-      { label: 'Save', variant: 'solid' },
+      { label: 'Save', variant: 'primary' },
     ],
   },
   render: (args) => {
@@ -171,7 +171,7 @@ export const TwoButtons: Story = {
             {args.footerButtons && (
               <ModalFooter>
                 {args.footerButtons.map((button, index) => (
-                  <Button key={index} variant={button.variant || 'soft'}>
+                  <Button key={index} variant={button.variant || 'subtle'}>
                     {button.label}
                   </Button>
                 ))}
@@ -207,8 +207,8 @@ export const WithCloseButton: Story = {
             {/* ModalCloseButton: Dialog.CloseTrigger + CloseButton 조합 */}
             <ModalCloseButton />
             <ModalBody>
-              이 모달은 우측 상단에 닫기 버튼이 있습니다. 버튼을 클릭하거나 ESC 키를
-              눌러 닫을 수 있습니다.
+              이 모달은 우측 상단에 닫기 버튼이 있습니다. 버튼을 클릭하거나 ESC
+              키를 눌러 닫을 수 있습니다.
             </ModalBody>
           </ModalContent>
         </Modal>
@@ -266,7 +266,7 @@ export const WithoutHeader: Story = {
               <Button variant="ghost" onClick={() => setIsOpen(false)}>
                 Cancel
               </Button>
-              <Button variant="solid" onClick={() => setIsOpen(false)}>
+              <Button variant="primary" onClick={() => setIsOpen(false)}>
                 Confirm
               </Button>
             </ModalFooter>
@@ -308,7 +308,7 @@ export const FullFeatured: Story = {
     hasCloseButton: true,
     footerButtons: [
       { label: 'Cancel', variant: 'ghost' },
-      { label: 'Delete', variant: 'solid' },
+      { label: 'Delete', variant: 'danger' },
     ],
   },
   render: (args) => {
@@ -322,14 +322,14 @@ export const FullFeatured: Story = {
             <ModalHeader>{args.headerTitle}</ModalHeader>
             <ModalCloseButton />
             <ModalBody>
-              헤더, 바디, 푸터, 닫기 버튼이 모두 포함된 완전한 모달 예제입니다. 모든
-              요소가 조화롭게 배치되어 있습니다.
+              헤더, 바디, 푸터, 닫기 버튼이 모두 포함된 완전한 모달 예제입니다.
+              모든 요소가 조화롭게 배치되어 있습니다.
             </ModalBody>
             <ModalFooter>
               {args.footerButtons?.map((button, index) => (
                 <Button
                   key={index}
-                  variant={button.variant || 'soft'}
+                  variant={button.variant || 'subtle'}
                   onClick={() => setIsOpen(false)}
                 >
                   {button.label}
@@ -393,7 +393,8 @@ export const DifferentSizes: Story = {
             <ModalHeader>Modal Size: {openSize?.toUpperCase()}</ModalHeader>
             <ModalCloseButton />
             <ModalBody>
-              현재 모달 크기는 {openSize}입니다. 다양한 크기의 모달을 테스트해보세요.
+              현재 모달 크기는 {openSize}입니다. 다양한 크기의 모달을
+              테스트해보세요.
             </ModalBody>
             <ModalFooter>
               <Button onClick={() => setOpenSize(null)}>Close</Button>
@@ -433,7 +434,12 @@ export const DifferentPlacements: Story = {
             </ModalHeader>
             <ModalCloseButton />
             <ModalBody>
-              모달이 화면의 {openPlacement === 'top' ? '상단' : openPlacement === 'center' ? '중앙' : '하단'}
+              모달이 화면의{' '}
+              {openPlacement === 'top'
+                ? '상단'
+                : openPlacement === 'center'
+                  ? '중앙'
+                  : '하단'}
               에 표시됩니다.
             </ModalBody>
             <ModalFooter>
@@ -466,8 +472,8 @@ export const PreventOutsideClick: Story = {
             <ModalHeader>{args.headerTitle}</ModalHeader>
             <ModalCloseButton />
             <ModalBody>
-              이 모달은 Overlay를 클릭해도 닫히지 않습니다. 닫기 버튼이나 ESC 키를
-              사용하세요.
+              이 모달은 Overlay를 클릭해도 닫히지 않습니다. 닫기 버튼이나 ESC
+              키를 사용하세요.
             </ModalBody>
             <ModalFooter>
               <Button onClick={() => setIsOpen(false)}>Close</Button>
@@ -482,13 +488,14 @@ export const PreventOutsideClick: Story = {
 /**
  * 모바일 풀스크린 모달 (기본값)
  *
- * fullScreenOnMobile이 true(기본값)이면 모바일 뷰포트에서
+ * fullScreenOnMobile을 true로 주면 모바일 뷰포트에서
  * 모달이 전체 화면으로 표시됩니다 (100vw × 100dvh, border-radius 0).
+ * 기본값은 false이니 전체 화면이 필요한 곳에서만 켜세요.
  * 브라우저를 좁혀서 확인해보세요.
  */
 export const FullScreenOnMobile: Story = {
   args: {
-    headerTitle: 'Full Screen on Mobile (Default)',
+    headerTitle: 'Full Screen on Mobile (opt-in)',
   },
   render: (args) => {
     const [isOpen, setIsOpen] = useState(false);
@@ -506,14 +513,15 @@ export const FullScreenOnMobile: Story = {
             <ModalHeader>{args.headerTitle}</ModalHeader>
             <ModalCloseButton />
             <ModalBody>
-              모바일에서 이 모달은 전체 화면으로 표시됩니다. 브라우저 창을 좁혀서
-              확인해보세요. fullScreenOnMobile은 기본값이 true입니다.
+              모바일에서 이 모달은 전체 화면으로 표시됩니다. 브라우저 창을
+              좁혀서 확인해보세요. fullScreenOnMobile은 기본값이 false라 직접
+              켜야 합니다.
             </ModalBody>
             <ModalFooter>
               <Button variant="ghost" onClick={() => setIsOpen(false)}>
                 Cancel
               </Button>
-              <Button variant="solid" onClick={() => setIsOpen(false)}>
+              <Button variant="primary" onClick={() => setIsOpen(false)}>
                 Confirm
               </Button>
             </ModalFooter>
@@ -527,13 +535,13 @@ export const FullScreenOnMobile: Story = {
 /**
  * 모바일에서 인라인 모달
  *
- * fullScreenOnMobile={false}이면 모바일에서도 풀스크린이 아닌
+ * fullScreenOnMobile={false}(기본값)이면 모바일에서도 풀스크린이 아닌
  * 일반 모달로 표시되며, 좌우 마진(mx: 4)이 적용됩니다.
- * Confirm 모달 등 작은 모달에 적합합니다.
+ * Confirm 모달 등 대부분의 모달이 여기에 해당합니다.
  */
 export const NoFullScreenOnMobile: Story = {
   args: {
-    headerTitle: 'Inline on Mobile',
+    headerTitle: 'Inline on Mobile (default)',
   },
   render: (args) => {
     const [isOpen, setIsOpen] = useState(false);
@@ -551,14 +559,14 @@ export const NoFullScreenOnMobile: Story = {
             <ModalHeader>{args.headerTitle}</ModalHeader>
             <ModalCloseButton />
             <ModalBody>
-              fullScreenOnMobile={'{false}'}로 설정하면 모바일에서도 풀스크린이 아닌
-              인라인 모달로 표시됩니다. 좌우에 마진이 적용됩니다.
+              fullScreenOnMobile={'{false}'}로 설정하면 모바일에서도 풀스크린이
+              아닌 인라인 모달로 표시됩니다. 좌우에 마진이 적용됩니다.
             </ModalBody>
             <ModalFooter>
               <Button variant="ghost" onClick={() => setIsOpen(false)}>
                 Cancel
               </Button>
-              <Button variant="solid" onClick={() => setIsOpen(false)}>
+              <Button variant="primary" onClick={() => setIsOpen(false)}>
                 Confirm
               </Button>
             </ModalFooter>
@@ -568,3 +576,47 @@ export const NoFullScreenOnMobile: Story = {
     );
   },
 };
+
+/**
+ * `headerTone="brand"` bands the header in `layer.3` with a
+ * `secondary.border` bottom rule for a modal that wants brand presence up
+ * top. `ModalHeader`'s `subtitle` prop renders a second line under the title.
+ */
+export const BrandHeader: Story = {
+  args: {
+    headerTitle: 'Welcome to Mindlogic!',
+    footerButtons: [{ label: 'Get started', variant: 'primary' }],
+  },
+  render: (args) => {
+    const [isOpen, setIsOpen] = useState(false);
+
+    return (
+      <>
+        <Button onClick={() => setIsOpen(true)}>Open Brand Modal</Button>
+        <Modal
+          {...args}
+          headerTone="brand"
+          open={isOpen}
+          onOpenChange={(e) => setIsOpen(e.open)}
+        >
+          <ModalContent>
+            <ModalHeader subtitle="Let's set up your workspace.">
+              {args.headerTitle}
+            </ModalHeader>
+            <ModalCloseButton />
+            <ModalBody>열려라 참깨!</ModalBody>
+            {args.footerButtons && (
+              <ModalFooter>
+                {args.footerButtons.map((button, index) => (
+                  <Button key={index} variant={button.variant || 'subtle'}>
+                    {button.label}
+                  </Button>
+                ))}
+              </ModalFooter>
+            )}
+          </ModalContent>
+        </Modal>
+      </>
+    );
+  },
+};