From 33114d7f9f4a6f9a7854431c573884bd1529b86b Mon Sep 17 00:00:00 2001
From: Caner Akdas <canerakdas@gmail.com>
Date: Sun, 25 Jan 2026 15:45:43 +0300
Subject: [PATCH] chore: ux improvements

---
 packages/ui-components/package.json           |  2 +-
 .../src/Common/AlertBox/index.module.css      |  4 ++
 .../src/Common/AlertBox/index.stories.tsx     | 65 ++++++++++++++++---
 .../src/Common/AlertBox/index.tsx             |  2 +-
 .../src/Common/Badge/index.module.css         | 16 +++++
 .../src/Common/Badge/index.stories.tsx        | 17 +++++
 .../ui-components/src/Common/Badge/index.tsx  | 10 ++-
 .../src/Common/DataTag/index.module.css       |  3 +-
 .../Common/TableOfContents/index.module.css   | 28 ++++++--
 .../Common/TableOfContents/index.stories.tsx  |  5 ++
 .../src/Common/TableOfContents/index.tsx      |  5 +-
 11 files changed, 138 insertions(+), 19 deletions(-)

diff --git a/packages/ui-components/package.json b/packages/ui-components/package.json
index 07244719cccae..d82461feebd96 100644
--- a/packages/ui-components/package.json
+++ b/packages/ui-components/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@node-core/ui-components",
-  "version": "1.5.6",
+  "version": "1.5.7",
   "type": "module",
   "exports": {
     "./*": [
diff --git a/packages/ui-components/src/Common/AlertBox/index.module.css b/packages/ui-components/src/Common/AlertBox/index.module.css
index 25538a4b223e4..685f20a75e64a 100644
--- a/packages/ui-components/src/Common/AlertBox/index.module.css
+++ b/packages/ui-components/src/Common/AlertBox/index.module.css
@@ -50,6 +50,10 @@
       size-5;
   }
 
+  .content {
+    @apply wrap-anywhere;
+  }
+
   &.info {
     @apply bg-info-600;
 
diff --git a/packages/ui-components/src/Common/AlertBox/index.stories.tsx b/packages/ui-components/src/Common/AlertBox/index.stories.tsx
index 77a00dbe22e28..9de20d062fb56 100644
--- a/packages/ui-components/src/Common/AlertBox/index.stories.tsx
+++ b/packages/ui-components/src/Common/AlertBox/index.stories.tsx
@@ -111,16 +111,6 @@ export const NoTitle: Story = {
   },
 };
 
-export default {
-  component: AlertBox,
-  argTypes: {
-    size: {
-      options: ['default', 'small'],
-      control: { type: 'radio' },
-    },
-  },
-} as Meta;
-
 export const SmallContainer: Story = {
   render: args => (
     <div className="w-200">
@@ -141,3 +131,58 @@ export const SmallContainer: Story = {
     size: 'default',
   },
 };
+
+export const WithLongContent: Story = {
+  args: {
+    level: 'warning',
+    title: 'Stability: 1',
+    children: (
+      <span>
+        Experimental. Please migrate away from this API, if you can. We do not
+        recommend using the{' '}
+        <a href="#async_hookscreatehookcallbacks">
+          <code>createHook</code>
+        </a>
+        ,{' '}
+        <a href="#class-asynchook">
+          <code>AsyncHook</code>
+        </a>
+        , and
+        <a href="#async_hooksexecutionasyncresource">
+          <code>executionAsyncResource</code>
+        </a>{' '}
+        APIs as they have usability issues, safety risks, and performance
+        implications. Async context tracking use cases are better served by the
+        stable{' '}
+        <a href="async_context.html#class-asynclocalstorage">
+          <code>AsyncLocalStorage</code>
+        </a>{' '}
+        API. If you have a use case for
+        <code>createHook</code>, <code>AsyncHook</code>, or{' '}
+        <code>executionAsyncResource</code> beyond the context tracking need
+        solved by{' '}
+        <a href="async_context.html#class-asynclocalstorage">
+          <code>AsyncLocalStorage</code>
+        </a>{' '}
+        or diagnostics data currently provided by{' '}
+        <a href="diagnostics_channel.html">Diagnostics Channel</a>, please open
+        an issue at{' '}
+        <a href="https://github.com/nodejs/node/issues">
+          https://github.com/nodejs/node/issues
+        </a>{' '}
+        describing your use case so we can create a more purpose-focused API.
+      </span>
+    ),
+    size: 'default',
+  },
+};
+
+export default {
+  component: AlertBox,
+  argTypes: {
+    size: {
+      options: ['default', 'small'],
+      control: { type: 'radio' },
+    },
+  },
+} as Meta;
diff --git a/packages/ui-components/src/Common/AlertBox/index.tsx b/packages/ui-components/src/Common/AlertBox/index.tsx
index e5e2020c0d32d..283c1934b4050 100644
--- a/packages/ui-components/src/Common/AlertBox/index.tsx
+++ b/packages/ui-components/src/Common/AlertBox/index.tsx
@@ -18,7 +18,7 @@ const AlertBox: FC<AlertBoxProps> = ({
 }) => (
   <div className={classNames(styles.alertBox, styles[level], styles[size])}>
     <span className={styles.title}>{title}</span>
-    <span>{children}</span>
+    <span className={styles.content}>{children}</span>
   </div>
 );
 
diff --git a/packages/ui-components/src/Common/Badge/index.module.css b/packages/ui-components/src/Common/Badge/index.module.css
index 79c4ac3146eee..008f025cf3d95 100644
--- a/packages/ui-components/src/Common/Badge/index.module.css
+++ b/packages/ui-components/src/Common/Badge/index.module.css
@@ -37,4 +37,20 @@
   &.neutral {
     @apply bg-neutral-800;
   }
+
+  &.circular {
+    @apply font-ibm-plex-mono
+      inline-flex
+      items-center
+      justify-center
+      p-0;
+
+    &.small {
+      @apply size-5;
+    }
+
+    &.medium {
+      @apply size-7;
+    }
+  }
 }
diff --git a/packages/ui-components/src/Common/Badge/index.stories.tsx b/packages/ui-components/src/Common/Badge/index.stories.tsx
index 4b8931d786a24..b0be6d1f7e863 100644
--- a/packages/ui-components/src/Common/Badge/index.stories.tsx
+++ b/packages/ui-components/src/Common/Badge/index.stories.tsx
@@ -47,4 +47,21 @@ export const Medium: Story = {
   },
 };
 
+export const Circular: Story = {
+  args: {
+    circular: true,
+    children: 'D',
+    size: 'small',
+    kind: 'error',
+  },
+};
+
+export const MediumCircular: Story = {
+  args: {
+    circular: true,
+    children: 'E',
+    kind: 'warning',
+  },
+};
+
 export default { component: Badge, args: { children: 'Badge' } } as Meta;
diff --git a/packages/ui-components/src/Common/Badge/index.tsx b/packages/ui-components/src/Common/Badge/index.tsx
index 86a5e8ea8ffdb..a2d61bdecf75d 100644
--- a/packages/ui-components/src/Common/Badge/index.tsx
+++ b/packages/ui-components/src/Common/Badge/index.tsx
@@ -10,17 +10,25 @@ type BadgeSize = 'small' | 'medium';
 type BadgeProps = HTMLAttributes<HTMLSpanElement> & {
   size?: BadgeSize;
   kind?: BadgeKind;
+  circular?: boolean;
 };
 
 const Badge: FC<PropsWithChildren<BadgeProps>> = ({
   kind = 'default',
   size = 'medium',
+  circular = false,
   className,
   children,
   ...props
 }) => (
   <span
-    className={classNames(styles.badge, styles[kind], styles[size], className)}
+    className={classNames(
+      styles.badge,
+      styles[kind],
+      styles[size],
+      { [styles.circular]: circular },
+      className
+    )}
     {...props}
   >
     {children}
diff --git a/packages/ui-components/src/Common/DataTag/index.module.css b/packages/ui-components/src/Common/DataTag/index.module.css
index 0cd6589553f77..ef244b3765153 100644
--- a/packages/ui-components/src/Common/DataTag/index.module.css
+++ b/packages/ui-components/src/Common/DataTag/index.module.css
@@ -1,7 +1,8 @@
 @reference "../../styles/index.css";
 
 .dataTag {
-  @apply flex
+  @apply font-ibm-plex-mono
+    flex
     items-center
     justify-center
     rounded-full
diff --git a/packages/ui-components/src/Common/TableOfContents/index.module.css b/packages/ui-components/src/Common/TableOfContents/index.module.css
index 9d838e502d79b..3e97de5dd5a7c 100644
--- a/packages/ui-components/src/Common/TableOfContents/index.module.css
+++ b/packages/ui-components/src/Common/TableOfContents/index.module.css
@@ -8,19 +8,39 @@
     lg:hidden
     dark:bg-neutral-900;
 
+  &[open] {
+    .icon {
+      @apply rotate-90;
+    }
+  }
+
   .summary {
-    @apply px-4
-      py-2;
+    @apply flex
+      list-none
+      items-center
+      gap-1
+      px-3.5
+      py-2.5;
+
+    &::-webkit-details-marker {
+      @apply hidden;
+    }
+
+    .icon {
+      @apply size-5;
+    }
   }
 
   .list {
     @apply space-y-1
       px-4
-      pb-2;
+      pb-2
+      wrap-anywhere;
   }
 
   .link {
-    @apply text-sm
+    @apply inline-block
+      text-sm
       font-semibold
       text-neutral-900
       underline
diff --git a/packages/ui-components/src/Common/TableOfContents/index.stories.tsx b/packages/ui-components/src/Common/TableOfContents/index.stories.tsx
index 2c05585f189aa..831b370c1f5c1 100644
--- a/packages/ui-components/src/Common/TableOfContents/index.stories.tsx
+++ b/packages/ui-components/src/Common/TableOfContents/index.stories.tsx
@@ -60,6 +60,11 @@ export default {
         depth: 5, // h5s do not get shown
         data: { id: 'node-website' },
       },
+      {
+        value: 'ERR_DUPLICATE_STARTUP_SNAPSHOT_MAIN_FUNCTION',
+        depth: 3,
+        data: { id: 'err_duplicate_startup_snapshot_main_function' },
+      },
     ],
   },
 } as Meta;
diff --git a/packages/ui-components/src/Common/TableOfContents/index.tsx b/packages/ui-components/src/Common/TableOfContents/index.tsx
index a1271ae789f59..015e5c4431823 100644
--- a/packages/ui-components/src/Common/TableOfContents/index.tsx
+++ b/packages/ui-components/src/Common/TableOfContents/index.tsx
@@ -1,3 +1,4 @@
+import { ChevronRightIcon } from '@heroicons/react/24/outline';
 import classNames from 'classnames';
 
 import { LinkLike } from '#ui/types';
@@ -35,7 +36,9 @@ const TableOfContents: FC<TableOfContentsProps> = ({
 
   return (
     <details className={classNames(styles.details, className)} {...props}>
-      <summary className={styles.summary}>{summaryTitle}</summary>
+      <summary className={styles.summary}>
+        <ChevronRightIcon className={styles.icon} /> {summaryTitle}
+      </summary>
       <ul className={styles.list}>
         {filteredHeadings.map((head, index) => (
           <li key={head.data?.id ?? index}>