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

package/src/components/Toast/Toast.types.ts

@@ -12,6 +12,21 @@ import {
  */
 export type ToastStatus = 'info' | 'warning' | 'success' | 'error';
 
+/**
+ * The single action a toast can carry.
+ *
+ * Rendered as a text action in the toast's status color, under the
+ * description. Clicking it calls `onClick` and dismisses the toast.
+ * One action per toast — dismiss is the ×, never a second action.
+ * See the "Guidelines/Actions in feedback surfaces" page in Storybook.
+ */
+export interface ToastAction {
+  /** Action label — keep it to a short verb phrase ("크레딧 구매", "Undo") */
+  label: ReactNode;
+  /** Called when the action is clicked; the toast is dismissed afterwards */
+  onClick: () => void;
+}
+
 /**
  * Toast component props
  * Uses ToastRootProps as base and overrides title for ReactNode support
@@ -25,15 +40,23 @@ export interface ToastProps extends Omit<ToastRootProps, 'title'> {
   status?: ToastStatus;
   /** Custom close handler */
   onClose?: () => void;
+  /** One action, rendered as a text action in the status color */
+  action?: ToastAction;
 }
 
 /**
  * Options for useToast hook
  * Extends Chakra's ToastOptions with custom properties
  */
-export interface UseToastOptions extends ToastOptions {
+export interface UseToastOptions extends Omit<ToastOptions, 'action'> {
   /** Toast status - restricted to common statuses */
   status?: ToastStatus;
+  /**
+   * One action, rendered as a text action in the status color.
+   * Unlike Chakra's `action`, the label accepts any ReactNode.
+   * When set and `duration` is not given, the toast stays for 8s instead of 5s.
+   */
+  action?: ToastAction;
   /** Custom styles to apply to the toast */
   styles?: BoxProps;
 }
@@ -47,6 +70,8 @@ export interface ToasterCreateOptions extends ToastOptions {
   meta?: {
     /** Custom close handler for the toast */
     onClose?: () => void;
+    /** Toast action (ReactNode label); takes precedence over Chakra's `action` */
+    action?: ToastAction;
     /** Custom styles to merge with default toast styles */
     styles?: BoxProps;
     /** Allow additional custom metadata */

package/src/components/Toast/ToastIcon/ToastIcon.tsx

@@ -1,20 +1,20 @@
 import { ReactNode } from 'react';
 
 import {
-  IoIosCheckmarkCircle,
-  IoWarning,
-  LuInfo,
-  MdError,
+  AlertCircleFilledIcon,
+  CircleCheckIcon,
+  InfoCircleIcon,
+  WarningIcon,
 } from '@/components/Icon';
 
 import { ToastProps, ToastStatus } from '../Toast.types';
 
 export const ToastIcon = ({ status }: Required<Pick<ToastProps, 'status'>>) => {
   const iconProps: Record<ToastStatus, ReactNode> = {
-    info: <LuInfo boxSize="md" color="primary.main" />,
-    warning: <IoWarning boxSize="lg" color="warning.main" />,
-    success: <IoIosCheckmarkCircle boxSize="lg" color="success.main" />,
-    error: <MdError boxSize="lg" color="danger.main" />,
+    info: <InfoCircleIcon boxSize="md" color="primary.main" />,
+    warning: <WarningIcon boxSize="lg" color="warning.main" />,
+    success: <CircleCheckIcon boxSize="lg" color="success.main" />,
+    error: <AlertCircleFilledIcon boxSize="lg" color="danger.main" />,
   };
 
   return iconProps[status];

package/src/components/Toast/Toaster.tsx

@@ -7,6 +7,7 @@ import {
 
 import { Toast } from './Toast';
 import { toastStyles } from './Toast.styles';
+import type { ToastAction } from './Toast.types';
 
 /**
  * Global toaster instance for managing toast notifications
@@ -61,6 +62,15 @@ export const Toaster = () => (
         // Extract custom data from meta
         const customStyles = toast.meta?.styles || {};
         const onClose = toast.meta?.onClose;
+        // `useToast` passes the action through meta so its label can be a
+        // ReactNode. A plain `toaster.create({ action })` (Chakra's own option)
+        // also works: Toast.ActionTrigger already calls `toast.action.onClick`
+        // itself, so the handler passed down here must not call it again.
+        const action: ToastAction | undefined =
+          toast.meta?.action ??
+          (toast.action
+            ? { label: toast.action.label, onClick: () => {} }
+            : undefined);
 
         return (
           <Toast
@@ -68,6 +78,7 @@ export const Toaster = () => (
             description={toast.description}
             status={toast.type}
             onClose={onClose}
+            action={action}
             {...toastStyles[toast.type as keyof typeof toastStyles]}
             {...customStyles}
           />

package/src/components/Toast/useToast.tsx

@@ -1,6 +1,10 @@
 import { useRef } from 'react';
 
-import { toastStyles } from './Toast.styles';
+import {
+  TOAST_ACTION_DURATION,
+  TOAST_DEFAULT_DURATION,
+  toastStyles,
+} from './Toast.styles';
 import {
   ToasterCreateOptions,
   ToastStatusChangeDetails,
@@ -22,9 +26,19 @@ export const useToast = () => {
     title,
     description,
     styles: stylesProp,
-    duration = 5000,
+    duration: durationProp,
+    action,
     ...rest
   }: UseToastOptions) => {
+    // A toast with an action stays longer, unless the caller chose a duration
+    // (including `null` / `Infinity` for a persistent toast).
+    const duration =
+      durationProp !== undefined
+        ? durationProp
+        : action
+          ? TOAST_ACTION_DURATION
+          : TOAST_DEFAULT_DURATION;
+
     // NOTE: placement is not supported - must be configured in Toaster.tsx createToaster()
     const styles = {
       ...toastStyles[status],
@@ -49,6 +63,7 @@ export const useToast = () => {
       meta: {
         // Pass custom data through meta
         styles, // for custom toast style
+        action, // ReactNode label, so it travels in meta rather than `action`
         onClose: () => toaster.dismiss(toastId), // Custom close handler
       },
       onStatusChange: (details: ToastStatusChangeDetails) => {

package/src/components/Tooltip/Tooltip.instant.test.tsx

@@ -0,0 +1,43 @@
+import { ChakraProvider } from '@chakra-ui/react';
+import { render } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+
+import { system } from '../../theme';
+import { Tooltip } from './Tooltip';
+
+/**
+ * zag marks a tooltip `data-instant` when the pointer moves to it from another
+ * open one. It skips the open delay there by itself; the animation is ours to
+ * skip. The rule has to outrank the presence clock's `:is([data-state=open])`,
+ * so this checks the emitted selector rather than trusting the cascade.
+ */
+describe('Tooltip instant mode', () => {
+  it('drops the enter/exit animation when zag marks the content instant', () => {
+    const { getByRole } = render(
+      <ChakraProvider value={system}>
+        <Tooltip content="hint" open>
+          <button type="button">trigger</button>
+        </Tooltip>
+      </ChakraProvider>
+    );
+    const content = getByRole('tooltip');
+    const css = Array.from(document.querySelectorAll('style'))
+      .map((s) => s.textContent ?? '')
+      .join('\n');
+    const classes = content.className
+      .split(' ')
+      .filter((c) => c.startsWith('css-'));
+    const rule = classes
+      .flatMap((c) => [
+        ...css.matchAll(
+          new RegExp(
+            `\\.${c}\\[data-instant\\]\\[data-state\\]\\{([^}]*)\\}`,
+            'g'
+          )
+        ),
+      ])
+      .map((m) => m[1])
+      .join(';');
+    expect(rule).toContain('animation-duration:0ms');
+  });
+});

package/src/components/Tooltip/Tooltip.tsx

@@ -49,9 +49,23 @@ export const Tooltip = forwardRef(
               py={1}
               borderRadius="md"
               maxW="320px"
+              // The one part whose recipe timing was symmetric — 150ms both
+              // ways — which is why a tooltip used to feel like it was being
+              // peeled off the trigger. It has the shortest dwell of anything
+              // here, so the exit being half the enter matters most.
+              animationStyle="presence-anchored"
               {...contentProps}
               css={mergeCss(
-                { '--tooltip-bg': 'var(--chakra-colors-gray-1200)' },
+                {
+                  '--tooltip-bg': 'var(--chakra-colors-gray-1200)',
+                  // zag sets `data-instant` when the pointer moves from one
+                  // open tooltip to the next. It already skips the delay
+                  // there; skip the enter/exit too, so sweeping a toolbar
+                  // doesn't replay the animation on every button. The extra
+                  // `[data-state]` outranks the presence clock's
+                  // `:is([data-state=open])`.
+                  '&[data-instant][data-state]': { animationDuration: '0ms' },
+                },
                 contentProps?.css
               )}
             >

package/src/components/Tree/TreeBranchIndicator.tsx

@@ -1,7 +1,7 @@
 import { forwardRef } from 'react';
 import { TreeView as ChakraTreeView } from '@chakra-ui/react';
 
-import { IoChevronForward } from '@/components/Icon';
+import { ChevronRightIcon } from '@/components/Icon';
 
 import { TreeBranchIndicatorProps } from './Tree.types';
 
@@ -15,12 +15,12 @@ export const TreeBranchIndicator = forwardRef<
       display="inline-flex"
       alignItems="center"
       justifyContent="center"
-      transition="transform 0.15s ease-out"
+      animationStyle="feedback"
+      transitionProperty="transform"
       _open={{ transform: 'rotate(90deg)' }}
-      _motionReduce={{ transition: 'none' }}
       {...rest}
     >
-      {children ?? <IoChevronForward boxSize="xs" />}
+      {children ?? <ChevronRightIcon boxSize="xs" />}
     </ChakraTreeView.BranchIndicator>
   );
 });

package/src/components/Typography/Caption.tsx

@@ -0,0 +1,41 @@
+import { forwardRef } from 'react';
+import { Text } from '@chakra-ui/react';
+
+import { polymorphic } from '../../types/polymorphic';
+import { TypographyOwnProps } from './Typography.types';
+
+/**
+ * The smallest tier in the body type scale (`textStyle="caption"`, ~11–12px),
+ * one step below {@link Subtext}. Use it for de-emphasised metadata — message
+ * timestamps, counts, statuses, helper microcopy, table sub-values — text that
+ * supports the content without competing with it.
+ *
+ * Scale: `Text` (p, 14–16px) → `Subtext` (12.88–14px) → `Caption` (11–12px).
+ *
+ * Defaults to `fg.muted` since captions are secondary by nature; every aspect
+ * stays one Chakra prop away, so a brand/status variant is a single override
+ * (e.g. `color="danger.main"`). Passing `fontSize` opts out of the baked-in
+ * `textStyle` so an explicit size wins.
+ */
+const CaptionImpl = forwardRef<HTMLParagraphElement, TypographyOwnProps>(
+  (props, ref) => {
+    const { fontSize, ...rest } = props;
+
+    return (
+      <Text
+        ref={ref}
+        // If fontSize is provided, disable textStyle to allow the override
+        textStyle={fontSize ? undefined : 'caption'}
+        fontSize={fontSize}
+        color="fg.muted"
+        wordBreak="keep-all"
+        {...rest}
+      />
+    );
+  }
+);
+
+CaptionImpl.displayName = 'Caption';
+
+/** Type-level polymorphism over the same runtime — see `polymorphic`. */
+export const Caption = polymorphic<TypographyOwnProps, 'p'>(CaptionImpl);

package/src/components/Typography/H1.tsx

@@ -1,13 +1,17 @@
 import { forwardRef } from 'react';
-import { Heading, HeadingProps } from '@chakra-ui/react';
+import { Heading } from '@chakra-ui/react';
 
-export const H1 = forwardRef<HTMLHeadingElement, HeadingProps>((props, ref) => {
+import { polymorphic } from '../../types/polymorphic';
+import { HeadingOwnProps } from './Typography.types';
+
+const H1Impl = forwardRef<HTMLHeadingElement, HeadingOwnProps>((props, ref) => {
   const { fontSize, ...rest } = props;
 
   return (
     <Heading
       ref={ref}
       as="h1"
+      color="fg.emphasized"
       textStyle={fontSize ? undefined : 'h1'}
       fontSize={fontSize}
       wordBreak="keep-all"
@@ -16,4 +20,7 @@ export const H1 = forwardRef<HTMLHeadingElement, HeadingProps>((props, ref) => {
   );
 });
 
-H1.displayName = 'H1';
+H1Impl.displayName = 'H1';
+
+/** Type-level polymorphism over the same runtime — see `polymorphic`. */
+export const H1 = polymorphic<HeadingOwnProps, 'h1'>(H1Impl);

package/src/components/Typography/H2.tsx

@@ -1,13 +1,17 @@
 import { forwardRef } from 'react';
-import { Heading, HeadingProps } from '@chakra-ui/react';
+import { Heading } from '@chakra-ui/react';
 
-export const H2 = forwardRef<HTMLHeadingElement, HeadingProps>((props, ref) => {
+import { polymorphic } from '../../types/polymorphic';
+import { HeadingOwnProps } from './Typography.types';
+
+const H2Impl = forwardRef<HTMLHeadingElement, HeadingOwnProps>((props, ref) => {
   const { fontSize, ...rest } = props;
 
   return (
     <Heading
       ref={ref}
       as="h2"
+      color="fg.emphasized"
       textStyle={fontSize ? undefined : 'h2'}
       fontSize={fontSize}
       wordBreak="keep-all"
@@ -16,4 +20,7 @@ export const H2 = forwardRef<HTMLHeadingElement, HeadingProps>((props, ref) => {
   );
 });
 
-H2.displayName = 'H2';
+H2Impl.displayName = 'H2';
+
+/** Type-level polymorphism over the same runtime — see `polymorphic`. */
+export const H2 = polymorphic<HeadingOwnProps, 'h2'>(H2Impl);

package/src/components/Typography/H3.tsx

@@ -1,14 +1,17 @@
 import { forwardRef } from 'react';
-import { Heading, HeadingProps } from '@chakra-ui/react';
+import { Heading } from '@chakra-ui/react';
 
-export const H3 = forwardRef<HTMLHeadingElement, HeadingProps>((props, ref) => {
+import { polymorphic } from '../../types/polymorphic';
+import { HeadingOwnProps } from './Typography.types';
+
+const H3Impl = forwardRef<HTMLHeadingElement, HeadingOwnProps>((props, ref) => {
   const { fontSize, ...rest } = props;
 
   return (
     <Heading
       ref={ref}
       as="h3"
-      color="fg.default"
+      color="fg.emphasized"
       textStyle={fontSize ? undefined : 'h3'}
       fontSize={fontSize}
       wordBreak="keep-all"
@@ -17,4 +20,7 @@ export const H3 = forwardRef<HTMLHeadingElement, HeadingProps>((props, ref) => {
   );
 });
 
-H3.displayName = 'H3';
+H3Impl.displayName = 'H3';
+
+/** Type-level polymorphism over the same runtime — see `polymorphic`. */
+export const H3 = polymorphic<HeadingOwnProps, 'h3'>(H3Impl);

package/src/components/Typography/H4.tsx

@@ -1,13 +1,17 @@
 import { forwardRef } from 'react';
-import { Heading, HeadingProps } from '@chakra-ui/react';
+import { Heading } from '@chakra-ui/react';
 
-export const H4 = forwardRef<HTMLHeadingElement, HeadingProps>((props, ref) => {
+import { polymorphic } from '../../types/polymorphic';
+import { HeadingOwnProps } from './Typography.types';
+
+const H4Impl = forwardRef<HTMLHeadingElement, HeadingOwnProps>((props, ref) => {
   const { fontSize, ...rest } = props;
 
   return (
     <Heading
       ref={ref}
       as="h4"
+      color="fg.emphasized"
       textStyle={fontSize ? undefined : 'h4'}
       fontSize={fontSize}
       wordBreak="keep-all"
@@ -16,4 +20,7 @@ export const H4 = forwardRef<HTMLHeadingElement, HeadingProps>((props, ref) => {
   );
 });
 
-H4.displayName = 'H4';
+H4Impl.displayName = 'H4';
+
+/** Type-level polymorphism over the same runtime — see `polymorphic`. */
+export const H4 = polymorphic<HeadingOwnProps, 'h4'>(H4Impl);

package/src/components/Typography/H5.tsx

@@ -1,13 +1,17 @@
 import { forwardRef } from 'react';
-import { Heading, HeadingProps } from '@chakra-ui/react';
+import { Heading } from '@chakra-ui/react';
 
-export const H5 = forwardRef<HTMLHeadingElement, HeadingProps>((props, ref) => {
+import { polymorphic } from '../../types/polymorphic';
+import { HeadingOwnProps } from './Typography.types';
+
+const H5Impl = forwardRef<HTMLHeadingElement, HeadingOwnProps>((props, ref) => {
   const { fontSize, ...rest } = props;
 
   return (
     <Heading
       ref={ref}
       as="h5"
+      color="fg.emphasized"
       textStyle={fontSize ? undefined : 'h5'}
       fontSize={fontSize}
       wordBreak="keep-all"
@@ -16,4 +20,7 @@ export const H5 = forwardRef<HTMLHeadingElement, HeadingProps>((props, ref) => {
   );
 });
 
-H5.displayName = 'H5';
+H5Impl.displayName = 'H5';
+
+/** Type-level polymorphism over the same runtime — see `polymorphic`. */
+export const H5 = polymorphic<HeadingOwnProps, 'h5'>(H5Impl);

package/src/components/Typography/Link.tsx

@@ -1,21 +1,73 @@
+import type { ElementType } from 'react';
 import { forwardRef } from 'react';
 import { Link as ChakraLink, LinkProps } from '@chakra-ui/react';
 
-export interface LinkCustomProps extends Omit<LinkProps, 'variant'> {
+// Relative, NOT `@/types/*` — see `src/types/polymorphic.ts`.
+import type { PolymorphicProps } from '../../types/polymorphic';
+import { polymorphic } from '../../types/polymorphic';
+
+export type LinkOwnProps = Omit<LinkProps, 'variant' | 'as'> & {
   variant?: 'error';
-}
+};
+
+/**
+ * Props for `Link`, typed for whatever element `as` renders.
+ *
+ * Defaults to `'a'`, so the bare type is unchanged. `as={NextLink}` is the
+ * reason this exists — the router link's own props (`href`, `prefetch`,
+ * `replace`) now come with it instead of arriving anonymously in `...rest`.
+ */
+export type LinkCustomProps<TElement extends ElementType = 'a'> =
+  PolymorphicProps<TElement, LinkOwnProps>;
 
-export const Link = forwardRef<HTMLAnchorElement, LinkCustomProps>(
+/**
+ * The ramp steps the link paints, exported so a test can assert BOTH halves at
+ * once: that the component still picks these tokens, and that these tokens
+ * still clear the contrast bar. Asserting only the second half is a test that
+ * passes while the component points somewhere else entirely — which is how the
+ * dark hover regressed with a green suite.
+ */
+export const LINK_RAMP = {
+  default: { base: 'primary.main', _dark: 'primary.dark' },
+  error: { base: 'danger.main', _dark: 'danger.dark' },
+  defaultHover: { base: 'primary.dark', _dark: 'primary.darker' },
+  errorHover: { base: 'danger.dark', _dark: 'danger.darker' },
+} as const;
+
+const LinkImpl = forwardRef<HTMLAnchorElement, LinkOwnProps>(
   ({ color, variant, ...rest }, ref) => {
-    const defaultColor = 'primary.main';
-    const errorColor = 'danger.main';
-    const defaultHoverColor = 'primary.dark';
-    const errorHoverColor = 'danger.dark';
+    // Theme-aware, because `.main` is tuned against a WHITE page. On the dark
+    // canvas (#181A20) `primary.main` measures 4.19:1 and `danger.main` 4.26:1
+    // — both under the 4.5:1 that KWCAG 2.1 5.1.3.3 (명도 대비) asks of body
+    // text, and every link in a consuming app inherits it. The `.dark` end of
+    // each ramp is the far side from the PAGE rather than a fixed lightness, so
+    // in dark mode it resolves lighter: 6.68:1 and 6.38:1.
+    const defaultColor = LINK_RAMP.default;
+    const errorColor = LINK_RAMP.error;
+    // The hover has to move AWAY from the page in BOTH modes, and `.main` is
+    // the wrong end of the ramp to move toward in dark. Mirroring the light
+    // step ("one darker") instead of reflecting it sent the dark hover back
+    // toward the background: resting 6.68:1 → hovering **4.19:1**, under the
+    // same 4.5:1 the resting colour above was just fixed to clear. KWCAG
+    // 5.3.3 applies to text in every state a user can put it in, and hover is
+    // a state a mouse user is IN while reading the link.
+    //
+    // `.darker` is the step past `.dark` at both ends, so one token is correct
+    // in both modes with no special-casing: light 11.98:1 (unchanged from
+    // before), dark 10.68:1. Error the same: 10.83:1 and 10.34:1.
+    //
+    // No axe rule would have caught this — it measures the resting state only.
+    const defaultHoverColor = LINK_RAMP.defaultHover;
+    const errorHoverColor = LINK_RAMP.errorHover;
 
+    // `color ?? defaultColor`, not a `typeof color === 'string'` narrowing. The
+    // old form silently DISCARDED any non-string value, so a call site passing
+    // a per-theme `{ base, _dark }` — the documented Chakra way to fix exactly
+    // the contrast problem above — got the default back and no error, in the
+    // types or at runtime. A prop the type accepts and the component throws
+    // away is worse than one it rejects.
     const linkColor =
-      variant === 'error'
-        ? errorColor
-        : (typeof color === 'string' ? color : undefined) || defaultColor;
+      variant === 'error' ? errorColor : (color ?? defaultColor);
 
     const hoverColor =
       variant === 'error' ? errorHoverColor : defaultHoverColor;
@@ -23,7 +75,11 @@ export const Link = forwardRef<HTMLAnchorElement, LinkCustomProps>(
     return (
       <ChakraLink
         ref={ref}
-        fontWeight="semibold"
+        // Inherit the surrounding text weight so an inline link reads as part of
+        // its sentence (extrabold inside an H1, body weight inside a paragraph)
+        // rather than a fixed-semibold patch. Color + underline carry the link
+        // affordance. Override with an explicit `fontWeight` when needed.
+        fontWeight="inherit"
         wordBreak="keep-all"
         color={linkColor}
         _hover={{
@@ -36,4 +92,7 @@ export const Link = forwardRef<HTMLAnchorElement, LinkCustomProps>(
   }
 );
 
-Link.displayName = 'Link';
+LinkImpl.displayName = 'Link';
+
+/** Type-level polymorphism over the same runtime — see `polymorphic`. */
+export const Link = polymorphic<LinkOwnProps, 'a'>(LinkImpl);

package/src/components/Typography/Overline.tsx

@@ -1,5 +1,8 @@
 import { forwardRef } from 'react';
-import { Text, TextProps } from '@chakra-ui/react';
+import { Text } from '@chakra-ui/react';
+
+import { polymorphic } from '../../types/polymorphic';
+import { TypographyOwnProps } from './Typography.types';
 
 /**
  * Small, uppercase, letter-spaced label used as a section "eyebrow" or category
@@ -12,7 +15,7 @@ import { Text, TextProps } from '@chakra-ui/react';
  * brand/status variants are a single override (e.g. `color="primary.main"`,
  * `fontWeight="extrabold"`).
  */
-export const Overline = forwardRef<HTMLParagraphElement, TextProps>(
+const OverlineImpl = forwardRef<HTMLParagraphElement, TypographyOwnProps>(
   (props, ref) => {
     const { fontSize, ...rest } = props;
 
@@ -30,4 +33,7 @@ export const Overline = forwardRef<HTMLParagraphElement, TextProps>(
   }
 );
 
-Overline.displayName = 'Overline';
+OverlineImpl.displayName = 'Overline';
+
+/** Type-level polymorphism over the same runtime — see `polymorphic`. */
+export const Overline = polymorphic<TypographyOwnProps, 'p'>(OverlineImpl);

package/src/components/Typography/Subtext.tsx

@@ -1,7 +1,10 @@
 import React, { forwardRef } from 'react';
-import { Text, TextProps } from '@chakra-ui/react';
+import { Text } from '@chakra-ui/react';
 
-export const Subtext = forwardRef<HTMLParagraphElement, TextProps>(
+import { polymorphic } from '../../types/polymorphic';
+import { TypographyOwnProps } from './Typography.types';
+
+const SubtextImpl = forwardRef<HTMLParagraphElement, TypographyOwnProps>(
   (props, ref) => {
     const { fontSize, ...rest } = props;
 
@@ -18,4 +21,7 @@ export const Subtext = forwardRef<HTMLParagraphElement, TextProps>(
   }
 );
 
-Subtext.displayName = 'Subtext';
+SubtextImpl.displayName = 'Subtext';
+
+/** Type-level polymorphism over the same runtime — see `polymorphic`. */
+export const Subtext = polymorphic<TypographyOwnProps, 'p'>(SubtextImpl);

package/src/components/Typography/Subtitle.tsx

@@ -1,14 +1,33 @@
 import { forwardRef } from 'react';
-import { Text, TextProps } from '@chakra-ui/react';
+import { Text } from '@chakra-ui/react';
 
-export const Subtitle = forwardRef<HTMLParagraphElement, TextProps>(
+import { polymorphic } from '../../types/polymorphic';
+import { TypographyOwnProps } from './Typography.types';
+
+/**
+ * Supporting text under a heading — a subtitle by role in the page, not by
+ * document structure.
+ *
+ * Renders a paragraph. It used to render `<h6>`, which made every call site a
+ * level-6 heading in the document outline: a sentence of helper copy under an
+ * `<h1>` announced as a heading to a screen reader, and a jump from level 1 to
+ * level 6 in the heading list (KWCAG 2.1 5.2.4.2 제목 제공 / axe `heading-order`).
+ * A component chosen for its type scale should not decide the outline.
+ *
+ * A subtitle that genuinely IS the next heading level still says so at the call
+ * site, which is where that is known:
+ *
+ * ```tsx
+ * <Subtitle as="h2">{sectionTitle}</Subtitle>
+ * ```
+ */
+const SubtitleImpl = forwardRef<HTMLParagraphElement, TypographyOwnProps>(
   (props, ref) => {
     const { fontSize, ...rest } = props;
 
     return (
       <Text
         ref={ref}
-        as="h6"
         textStyle={fontSize ? undefined : 'subtitle'}
         fontSize={fontSize}
         color="fg.muted"
@@ -19,4 +38,7 @@ export const Subtitle = forwardRef<HTMLParagraphElement, TextProps>(
   }
 );
 
-Subtitle.displayName = 'Subtitle';
+SubtitleImpl.displayName = 'Subtitle';
+
+/** Type-level polymorphism over the same runtime — see `polymorphic`. */
+export const Subtitle = polymorphic<TypographyOwnProps, 'p'>(SubtitleImpl);