From 2cd85878e23ea642ac78203a8fb7df31922d3401 Mon Sep 17 00:00:00 2001
From: thepoy <thepoy@163.com>
Date: Tue, 20 Oct 2026 11:11:42 +0800
Subject: [PATCH] feat(settings): show the release notes in a dialog, and link
 to the changelog

The notes are the release body the updater already fetches. Rendered inside the version card
they pushed the install button off screen and showed raw Markdown, so they now open in a
dialog: a small renderer turns headings, bullets and inline code into elements and never
touches an HTML sink.

The About card also gains a Changelog row for what is already installed. It opens the release
list rather than one tag, because nightly builds are published under their own release.

The ui/dialog and ui/alert-dialog families ride along, together with the Button and
ButtonGroupText fixes they need: this change imports them, so they cannot be committed apart
from it.
---
 src/components/settings/AboutSection.tsx      | 12 ++-
 src/components/settings/ReleaseNotes.tsx      | 73 ++++++++++++++++
 src/components/settings/UpdateCheck.tsx       | 38 ++++++++-
 .../alert-dialog/AlertDialog/AlertDialog.tsx  | 19 +++++
 .../AlertDialog/AlertDialog.types.ts          |  7 ++
 .../ui/alert-dialog/AlertDialog/index.ts      |  2 +
 .../AlertDialogAction/AlertDialogAction.tsx   | 18 ++++
 .../AlertDialogAction.types.ts                |  3 +
 .../alert-dialog/AlertDialogAction/index.ts   |  1 +
 .../AlertDialogCancel/AlertDialogCancel.tsx   | 24 ++++++
 .../AlertDialogCancel.types.ts                |  3 +
 .../alert-dialog/AlertDialogCancel/index.ts   |  1 +
 .../AlertDialogContent.styles.ts              |  4 +
 .../AlertDialogContent/AlertDialogContent.tsx | 23 +++++
 .../AlertDialogContent.types.ts               | 12 +++
 .../alert-dialog/AlertDialogContent/index.ts  |  2 +
 .../AlertDialogDescription.styles.ts          |  4 +
 .../AlertDialogDescription.tsx                | 27 ++++++
 .../AlertDialogDescription.types.ts           |  7 ++
 .../AlertDialogDescription/index.ts           |  1 +
 .../AlertDialogFooter.styles.ts               |  4 +
 .../AlertDialogFooter/AlertDialogFooter.tsx   | 17 ++++
 .../AlertDialogFooter.types.ts                |  3 +
 .../alert-dialog/AlertDialogFooter/index.ts   |  1 +
 .../AlertDialogHeader.styles.ts               |  4 +
 .../AlertDialogHeader/AlertDialogHeader.tsx   | 17 ++++
 .../AlertDialogHeader.types.ts                |  3 +
 .../alert-dialog/AlertDialogHeader/index.ts   |  1 +
 .../AlertDialogMedia.styles.ts                |  4 +
 .../AlertDialogMedia/AlertDialogMedia.tsx     | 17 ++++
 .../AlertDialogMedia.types.ts                 |  3 +
 .../ui/alert-dialog/AlertDialogMedia/index.ts |  1 +
 .../AlertDialogOverlay/AlertDialogOverlay.tsx |  6 ++
 .../AlertDialogOverlay.types.ts               |  3 +
 .../alert-dialog/AlertDialogOverlay/index.ts  |  1 +
 .../AlertDialogPortal/AlertDialogPortal.tsx   |  6 ++
 .../AlertDialogPortal.types.ts                |  3 +
 .../alert-dialog/AlertDialogPortal/index.ts   |  1 +
 .../AlertDialogTitle.styles.ts                |  4 +
 .../AlertDialogTitle/AlertDialogTitle.tsx     | 27 ++++++
 .../AlertDialogTitle.types.ts                 |  3 +
 .../ui/alert-dialog/AlertDialogTitle/index.ts |  1 +
 .../AlertDialogTrigger/AlertDialogTrigger.tsx | 31 +++++++
 .../AlertDialogTrigger.types.ts               |  7 ++
 .../alert-dialog/AlertDialogTrigger/index.ts  |  2 +
 src/components/ui/alert-dialog/index.ts       | 12 +++
 .../button-group/ButtonGroup/ButtonGroup.tsx  |  1 +
 .../ButtonGroupText/ButtonGroupText.tsx       | 10 ++-
 src/components/ui/button/Button.tsx           |  1 +
 .../ui/dialog/Dialog/Dialog.context.ts        | 24 ++++++
 .../ui/dialog/Dialog/Dialog.styles.ts         |  0
 src/components/ui/dialog/Dialog/Dialog.tsx    | 83 +++++++++++++++++++
 .../ui/dialog/Dialog/Dialog.types.ts          | 29 +++++++
 src/components/ui/dialog/Dialog/index.ts      |  3 +
 .../dialog/DialogClose/DialogClose.styles.ts  |  1 +
 .../ui/dialog/DialogClose/DialogClose.tsx     | 43 ++++++++++
 .../dialog/DialogClose/DialogClose.types.ts   |  3 +
 src/components/ui/dialog/DialogClose/index.ts |  1 +
 .../DialogContent/DialogContent.context.ts    | 16 ++++
 .../DialogContent/DialogContent.styles.ts     |  2 +
 .../ui/dialog/DialogContent/DialogContent.tsx | 32 +++++++
 .../DialogContent/DialogContent.types.ts      |  9 ++
 .../ui/dialog/DialogContent/index.ts          |  2 +
 .../DialogDescription.styles.ts               |  2 +
 .../DialogDescription/DialogDescription.tsx   | 27 ++++++
 .../DialogDescription.types.ts                |  3 +
 .../ui/dialog/DialogDescription/index.ts      |  1 +
 .../DialogFooter/DialogFooter.styles.ts       |  2 +
 .../ui/dialog/DialogFooter/DialogFooter.tsx   | 17 ++++
 .../dialog/DialogFooter/DialogFooter.types.ts |  3 +
 .../ui/dialog/DialogFooter/index.ts           |  1 +
 .../DialogHeader/DialogHeader.styles.ts       |  1 +
 .../ui/dialog/DialogHeader/DialogHeader.tsx   | 17 ++++
 .../dialog/DialogHeader/DialogHeader.types.ts |  3 +
 .../ui/dialog/DialogHeader/index.ts           |  1 +
 .../DialogOverlay/DialogOverlay.styles.ts     |  2 +
 .../ui/dialog/DialogOverlay/DialogOverlay.tsx | 46 ++++++++++
 .../DialogOverlay/DialogOverlay.types.ts      | 10 +++
 .../ui/dialog/DialogOverlay/index.ts          |  1 +
 .../ui/dialog/DialogPortal/DialogPortal.tsx   | 10 +++
 .../dialog/DialogPortal/DialogPortal.types.ts |  3 +
 .../ui/dialog/DialogPortal/index.ts           |  1 +
 .../ui/dialog/DialogSurface/DialogSurface.tsx | 82 ++++++++++++++++++
 .../DialogSurface/DialogSurface.types.ts      | 20 +++++
 .../ui/dialog/DialogSurface/index.ts          |  2 +
 .../dialog/DialogTitle/DialogTitle.styles.ts  |  1 +
 .../ui/dialog/DialogTitle/DialogTitle.tsx     | 27 ++++++
 .../dialog/DialogTitle/DialogTitle.types.ts   |  3 +
 src/components/ui/dialog/DialogTitle/index.ts |  1 +
 .../ui/dialog/DialogTrigger/DialogTrigger.tsx | 29 +++++++
 .../DialogTrigger/DialogTrigger.types.ts      |  4 +
 .../ui/dialog/DialogTrigger/index.ts          |  4 +
 .../dialog/DialogTrigger/useDialogTrigger.ts  | 38 +++++++++
 src/components/ui/dialog/index.ts             | 11 +++
 src/i18n/en-US.ts                             |  4 +
 src/i18n/ja-JP.ts                             |  4 +
 src/i18n/ko-KR.ts                             |  4 +
 src/i18n/zh-CN.ts                             |  4 +
 src/i18n/zh-HK.ts                             |  4 +
 src/i18n/zh-TW.ts                             |  4 +
 src/lib/release-notes.test.ts                 | 82 ++++++++++++++++++
 src/lib/release-notes.ts                      | 79 ++++++++++++++++++
 src/store/update.store.test.ts                | 42 +++++++++-
 src/store/update.store.ts                     | 10 ++-
 src/types/props.types.ts                      |  2 +-
 105 files changed, 1326 insertions(+), 9 deletions(-)
 create mode 100644 src/components/settings/ReleaseNotes.tsx
 create mode 100644 src/components/ui/alert-dialog/AlertDialog/AlertDialog.tsx
 create mode 100644 src/components/ui/alert-dialog/AlertDialog/AlertDialog.types.ts
 create mode 100644 src/components/ui/alert-dialog/AlertDialog/index.ts
 create mode 100644 src/components/ui/alert-dialog/AlertDialogAction/AlertDialogAction.tsx
 create mode 100644 src/components/ui/alert-dialog/AlertDialogAction/AlertDialogAction.types.ts
 create mode 100644 src/components/ui/alert-dialog/AlertDialogAction/index.ts
 create mode 100644 src/components/ui/alert-dialog/AlertDialogCancel/AlertDialogCancel.tsx
 create mode 100644 src/components/ui/alert-dialog/AlertDialogCancel/AlertDialogCancel.types.ts
 create mode 100644 src/components/ui/alert-dialog/AlertDialogCancel/index.ts
 create mode 100644 src/components/ui/alert-dialog/AlertDialogContent/AlertDialogContent.styles.ts
 create mode 100644 src/components/ui/alert-dialog/AlertDialogContent/AlertDialogContent.tsx
 create mode 100644 src/components/ui/alert-dialog/AlertDialogContent/AlertDialogContent.types.ts
 create mode 100644 src/components/ui/alert-dialog/AlertDialogContent/index.ts
 create mode 100644 src/components/ui/alert-dialog/AlertDialogDescription/AlertDialogDescription.styles.ts
 create mode 100644 src/components/ui/alert-dialog/AlertDialogDescription/AlertDialogDescription.tsx
 create mode 100644 src/components/ui/alert-dialog/AlertDialogDescription/AlertDialogDescription.types.ts
 create mode 100644 src/components/ui/alert-dialog/AlertDialogDescription/index.ts
 create mode 100644 src/components/ui/alert-dialog/AlertDialogFooter/AlertDialogFooter.styles.ts
 create mode 100644 src/components/ui/alert-dialog/AlertDialogFooter/AlertDialogFooter.tsx
 create mode 100644 src/components/ui/alert-dialog/AlertDialogFooter/AlertDialogFooter.types.ts
 create mode 100644 src/components/ui/alert-dialog/AlertDialogFooter/index.ts
 create mode 100644 src/components/ui/alert-dialog/AlertDialogHeader/AlertDialogHeader.styles.ts
 create mode 100644 src/components/ui/alert-dialog/AlertDialogHeader/AlertDialogHeader.tsx
 create mode 100644 src/components/ui/alert-dialog/AlertDialogHeader/AlertDialogHeader.types.ts
 create mode 100644 src/components/ui/alert-dialog/AlertDialogHeader/index.ts
 create mode 100644 src/components/ui/alert-dialog/AlertDialogMedia/AlertDialogMedia.styles.ts
 create mode 100644 src/components/ui/alert-dialog/AlertDialogMedia/AlertDialogMedia.tsx
 create mode 100644 src/components/ui/alert-dialog/AlertDialogMedia/AlertDialogMedia.types.ts
 create mode 100644 src/components/ui/alert-dialog/AlertDialogMedia/index.ts
 create mode 100644 src/components/ui/alert-dialog/AlertDialogOverlay/AlertDialogOverlay.tsx
 create mode 100644 src/components/ui/alert-dialog/AlertDialogOverlay/AlertDialogOverlay.types.ts
 create mode 100644 src/components/ui/alert-dialog/AlertDialogOverlay/index.ts
 create mode 100644 src/components/ui/alert-dialog/AlertDialogPortal/AlertDialogPortal.tsx
 create mode 100644 src/components/ui/alert-dialog/AlertDialogPortal/AlertDialogPortal.types.ts
 create mode 100644 src/components/ui/alert-dialog/AlertDialogPortal/index.ts
 create mode 100644 src/components/ui/alert-dialog/AlertDialogTitle/AlertDialogTitle.styles.ts
 create mode 100644 src/components/ui/alert-dialog/AlertDialogTitle/AlertDialogTitle.tsx
 create mode 100644 src/components/ui/alert-dialog/AlertDialogTitle/AlertDialogTitle.types.ts
 create mode 100644 src/components/ui/alert-dialog/AlertDialogTitle/index.ts
 create mode 100644 src/components/ui/alert-dialog/AlertDialogTrigger/AlertDialogTrigger.tsx
 create mode 100644 src/components/ui/alert-dialog/AlertDialogTrigger/AlertDialogTrigger.types.ts
 create mode 100644 src/components/ui/alert-dialog/AlertDialogTrigger/index.ts
 create mode 100644 src/components/ui/alert-dialog/index.ts
 create mode 100644 src/components/ui/dialog/Dialog/Dialog.context.ts
 create mode 100644 src/components/ui/dialog/Dialog/Dialog.styles.ts
 create mode 100644 src/components/ui/dialog/Dialog/Dialog.tsx
 create mode 100644 src/components/ui/dialog/Dialog/Dialog.types.ts
 create mode 100644 src/components/ui/dialog/Dialog/index.ts
 create mode 100644 src/components/ui/dialog/DialogClose/DialogClose.styles.ts
 create mode 100644 src/components/ui/dialog/DialogClose/DialogClose.tsx
 create mode 100644 src/components/ui/dialog/DialogClose/DialogClose.types.ts
 create mode 100644 src/components/ui/dialog/DialogClose/index.ts
 create mode 100644 src/components/ui/dialog/DialogContent/DialogContent.context.ts
 create mode 100644 src/components/ui/dialog/DialogContent/DialogContent.styles.ts
 create mode 100644 src/components/ui/dialog/DialogContent/DialogContent.tsx
 create mode 100644 src/components/ui/dialog/DialogContent/DialogContent.types.ts
 create mode 100644 src/components/ui/dialog/DialogContent/index.ts
 create mode 100644 src/components/ui/dialog/DialogDescription/DialogDescription.styles.ts
 create mode 100644 src/components/ui/dialog/DialogDescription/DialogDescription.tsx
 create mode 100644 src/components/ui/dialog/DialogDescription/DialogDescription.types.ts
 create mode 100644 src/components/ui/dialog/DialogDescription/index.ts
 create mode 100644 src/components/ui/dialog/DialogFooter/DialogFooter.styles.ts
 create mode 100644 src/components/ui/dialog/DialogFooter/DialogFooter.tsx
 create mode 100644 src/components/ui/dialog/DialogFooter/DialogFooter.types.ts
 create mode 100644 src/components/ui/dialog/DialogFooter/index.ts
 create mode 100644 src/components/ui/dialog/DialogHeader/DialogHeader.styles.ts
 create mode 100644 src/components/ui/dialog/DialogHeader/DialogHeader.tsx
 create mode 100644 src/components/ui/dialog/DialogHeader/DialogHeader.types.ts
 create mode 100644 src/components/ui/dialog/DialogHeader/index.ts
 create mode 100644 src/components/ui/dialog/DialogOverlay/DialogOverlay.styles.ts
 create mode 100644 src/components/ui/dialog/DialogOverlay/DialogOverlay.tsx
 create mode 100644 src/components/ui/dialog/DialogOverlay/DialogOverlay.types.ts
 create mode 100644 src/components/ui/dialog/DialogOverlay/index.ts
 create mode 100644 src/components/ui/dialog/DialogPortal/DialogPortal.tsx
 create mode 100644 src/components/ui/dialog/DialogPortal/DialogPortal.types.ts
 create mode 100644 src/components/ui/dialog/DialogPortal/index.ts
 create mode 100644 src/components/ui/dialog/DialogSurface/DialogSurface.tsx
 create mode 100644 src/components/ui/dialog/DialogSurface/DialogSurface.types.ts
 create mode 100644 src/components/ui/dialog/DialogSurface/index.ts
 create mode 100644 src/components/ui/dialog/DialogTitle/DialogTitle.styles.ts
 create mode 100644 src/components/ui/dialog/DialogTitle/DialogTitle.tsx
 create mode 100644 src/components/ui/dialog/DialogTitle/DialogTitle.types.ts
 create mode 100644 src/components/ui/dialog/DialogTitle/index.ts
 create mode 100644 src/components/ui/dialog/DialogTrigger/DialogTrigger.tsx
 create mode 100644 src/components/ui/dialog/DialogTrigger/DialogTrigger.types.ts
 create mode 100644 src/components/ui/dialog/DialogTrigger/index.ts
 create mode 100644 src/components/ui/dialog/DialogTrigger/useDialogTrigger.ts
 create mode 100644 src/components/ui/dialog/index.ts
 create mode 100644 src/lib/release-notes.test.ts
 create mode 100644 src/lib/release-notes.ts

diff --git a/src/components/settings/AboutSection.tsx b/src/components/settings/AboutSection.tsx
index 3bf499d9..ca06d3c9 100644
--- a/src/components/settings/AboutSection.tsx
+++ b/src/components/settings/AboutSection.tsx
@@ -1,5 +1,5 @@
 // Responsibility: About group — asymmetric layout (one large version block + a column of narrow link rows), breaking the default three-equal-card look.
-import { ChevronRight, Code, FileText } from "lucide-solid";
+import { ChevronRight, Code, FileText, ScrollText } from "lucide-solid";
 import { createResource, type JSXElement } from "solid-js";
 import {
   Item,
@@ -16,6 +16,8 @@ import { SettingsGroup } from "./SettingsGroup";
 import { UpdateCheck } from "./UpdateCheck";
 
 const SOURCE_URL = "https://github.com/dwall-rs/dwall";
+/** The release list, not one tag: nightly builds are published under their own release. */
+const CHANGELOG_URL = `${SOURCE_URL}/releases`;
 
 export function AboutSection() {
   const [info] = createResource(getAppInfo);
@@ -29,7 +31,7 @@ export function AboutSection() {
         delay={200}
       >
         <div class="grid grid-cols-[1.5fr_1fr] gap-3">
-          <div class="relative row-span-2 flex flex-col gap-2.5 overflow-hidden rounded-[15px] border border-border bg-linear-to-br from-primary/10 to-card p-5 shadow-[0_1px_2px_rgba(0,0,0,.05),0_8px_24px_rgba(0,0,0,.06)]">
+          <div class="relative row-span-3 flex flex-col gap-2.5 overflow-hidden rounded-[15px] border border-border bg-linear-to-br from-primary/10 to-card p-5 shadow-[0_1px_2px_rgba(0,0,0,.05),0_8px_24px_rgba(0,0,0,.06)]">
             <img
               src={Logo}
               alt={t("settings.about.logoAlt")}
@@ -43,6 +45,12 @@ export function AboutSection() {
             </div>
             <UpdateCheck />
           </div>
+          <LinkRow
+            icon={<ScrollText class="size-3.5" />}
+            title={t("settings.about.changelog")}
+            sub={t("settings.about.changelogSub")}
+            onClick={() => void openUrl(CHANGELOG_URL)}
+          />
           <LinkRow
             icon={<Code class="size-3.5" />}
             title={t("settings.about.sourceCode")}
diff --git a/src/components/settings/ReleaseNotes.tsx b/src/components/settings/ReleaseNotes.tsx
new file mode 100644
index 00000000..dd33743e
--- /dev/null
+++ b/src/components/settings/ReleaseNotes.tsx
@@ -0,0 +1,73 @@
+// Responsibility: renders the parsed release notes as elements — headings, lists, paragraphs and
+// inline code — with no HTML sink anywhere.
+import { For, Match, Switch, type JSX } from "solid-js";
+import {
+  parseReleaseNoteSpans,
+  parseReleaseNotes,
+  type ReleaseNoteBlock,
+} from "@/lib/release-notes";
+
+const asHeading = (block: ReleaseNoteBlock) =>
+  block.kind === "heading" ? block : undefined;
+
+const asList = (block: ReleaseNoteBlock) =>
+  block.kind === "list" ? block : undefined;
+
+const asParagraph = (block: ReleaseNoteBlock) =>
+  block.kind === "paragraph" ? block : undefined;
+
+function Spans(props: { text: string }): JSX.Element {
+  return (
+    <For each={parseReleaseNoteSpans(props.text)}>
+      {(span) =>
+        span.code ? (
+          <code class="rounded bg-foreground/8 px-1 py-px font-mono text-[0.92em]">
+            {span.text}
+          </code>
+        ) : (
+          span.text
+        )
+      }
+    </For>
+  );
+}
+
+export function ReleaseNotes(props: { markdown: string }) {
+  return (
+    <div class="flex flex-col gap-2.5 text-[12.5px] leading-relaxed text-muted-foreground">
+      <For each={parseReleaseNotes(props.markdown)}>
+        {(block) => (
+          <Switch>
+            <Match when={asHeading(block)}>
+              {(heading) => (
+                <h3 class="font-display text-[13px] font-bold text-foreground">
+                  {heading().text}
+                </h3>
+              )}
+            </Match>
+            <Match when={asList(block)}>
+              {(list) => (
+                <ul class="flex list-disc flex-col gap-1 pl-4 marker:text-primary/60">
+                  <For each={list().items}>
+                    {(item) => (
+                      <li>
+                        <Spans text={item} />
+                      </li>
+                    )}
+                  </For>
+                </ul>
+              )}
+            </Match>
+            <Match when={asParagraph(block)}>
+              {(paragraph) => (
+                <p>
+                  <Spans text={paragraph().text} />
+                </p>
+              )}
+            </Match>
+          </Switch>
+        )}
+      </For>
+    </div>
+  );
+}
diff --git a/src/components/settings/UpdateCheck.tsx b/src/components/settings/UpdateCheck.tsx
index f299f442..80408667 100644
--- a/src/components/settings/UpdateCheck.tsx
+++ b/src/components/settings/UpdateCheck.tsx
@@ -1,8 +1,15 @@
-// Responsibility: Update check widget — idle / checking / up to date / update available / downloading / awaiting restart / failed.
-import { Match, Switch } from "solid-js";
+// Responsibility: Update check widget — idle / checking / up to date / update available (with its notes in a dialog) / downloading / awaiting restart / failed.
+import { Match, Show, Switch } from "solid-js";
 import { t } from "@/i18n";
 import { check, install, restart, updateStore } from "@/store/update.store";
 import { Button } from "@/components/ui/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from "@/components/ui/dialog";
 import {
   Check,
   Download,
@@ -10,6 +17,7 @@ import {
   RefreshCw,
   TriangleAlert,
 } from "lucide-solid";
+import { ReleaseNotes } from "./ReleaseNotes";
 
 export function UpdateCheck() {
   const percent = () =>
@@ -29,6 +37,32 @@ export function UpdateCheck() {
                   version: updateStore.version ?? "",
                 })}
               </span>
+              {/* The notes are the release body the updater already fetched. They open in a
+                  dialog rather than inside this card: a changelog is longer than the card and
+                  would push the install button off the screen. */}
+              <Show when={updateStore.notes}>
+                <Dialog>
+                  <DialogTrigger
+                    variant="ghost"
+                    size="xs"
+                    class="ml-auto h-auto shrink-0 px-1.5 py-0 text-[11px] font-normal text-primary hover:bg-primary/10"
+                  >
+                    {t("settings.about.whatsNew")}
+                  </DialogTrigger>
+                  <DialogContent class="sm:max-w-2xl!">
+                    <DialogHeader class="pr-8">
+                      <DialogTitle>
+                        {t("settings.about.whatsNewFor", {
+                          version: updateStore.version ?? "",
+                        })}
+                      </DialogTitle>
+                    </DialogHeader>
+                    <div class="max-h-[60vh] overflow-y-auto pr-1">
+                      <ReleaseNotes markdown={updateStore.notes ?? ""} />
+                    </div>
+                  </DialogContent>
+                </Dialog>
+              </Show>
             </div>
             <Button
               size="sm"
diff --git a/src/components/ui/alert-dialog/AlertDialog/AlertDialog.tsx b/src/components/ui/alert-dialog/AlertDialog/AlertDialog.tsx
new file mode 100644
index 00000000..ed667b96
--- /dev/null
+++ b/src/components/ui/alert-dialog/AlertDialog/AlertDialog.tsx
@@ -0,0 +1,19 @@
+import { Dialog } from "~/components/ui/dialog";
+import type { AlertDialogProps } from "./AlertDialog.types";
+
+/**
+ * AlertDialog 复用 Dialog 的实现（受控/非受控状态机、Portal、Overlay、动画、
+ * Title/Description 的 id 注入、滚动锁定），只在内容层保留自己的差异：
+ * `role="alertdialog"`、无关闭按钮、点击外部不关闭、Escape 也不关闭
+ * （alert dialog 要求用户做出显式选择，对齐 Base UI）。
+ * 调用方仍可显式传 dismissOnEscape 覆盖。
+ */
+export const AlertDialog = (props: AlertDialogProps) => {
+  return (
+    <Dialog
+      {...props}
+      dismissOnEscape={props.dismissOnEscape ?? false}
+      data-slot="alert-dialog"
+    />
+  );
+};
diff --git a/src/components/ui/alert-dialog/AlertDialog/AlertDialog.types.ts b/src/components/ui/alert-dialog/AlertDialog/AlertDialog.types.ts
new file mode 100644
index 00000000..2f86fe41
--- /dev/null
+++ b/src/components/ui/alert-dialog/AlertDialog/AlertDialog.types.ts
@@ -0,0 +1,7 @@
+import type { DialogProps } from "~/components/ui/dialog";
+
+/**
+ * AlertDialog 复用 Dialog 的 props：
+ * 受控 `open` / `defaultOpen` / `onOpenChange`、`lockScroll` 等一并可用。
+ */
+export type AlertDialogProps = DialogProps;
diff --git a/src/components/ui/alert-dialog/AlertDialog/index.ts b/src/components/ui/alert-dialog/AlertDialog/index.ts
new file mode 100644
index 00000000..c1c18ac4
--- /dev/null
+++ b/src/components/ui/alert-dialog/AlertDialog/index.ts
@@ -0,0 +1,2 @@
+export { AlertDialog } from "./AlertDialog";
+export type { AlertDialogProps } from "./AlertDialog.types";
diff --git a/src/components/ui/alert-dialog/AlertDialogAction/AlertDialogAction.tsx b/src/components/ui/alert-dialog/AlertDialogAction/AlertDialogAction.tsx
new file mode 100644
index 00000000..740baf8f
--- /dev/null
+++ b/src/components/ui/alert-dialog/AlertDialogAction/AlertDialogAction.tsx
@@ -0,0 +1,18 @@
+import type { AlertDialogActionProps } from "./AlertDialogAction.types";
+import { Button } from "~/components/ui/button";
+import { useDialogContext } from "~/components/ui/dialog";
+
+export const AlertDialogAction = (props: AlertDialogActionProps) => {
+  const { setOpen } = useDialogContext();
+
+  return (
+    <Button
+      {...props}
+      data-slot="alert-dialog-action"
+      onClick={(event) => {
+        props.onClick?.(event);
+        setOpen(false);
+      }}
+    />
+  );
+};
diff --git a/src/components/ui/alert-dialog/AlertDialogAction/AlertDialogAction.types.ts b/src/components/ui/alert-dialog/AlertDialogAction/AlertDialogAction.types.ts
new file mode 100644
index 00000000..fbcfea7f
--- /dev/null
+++ b/src/components/ui/alert-dialog/AlertDialogAction/AlertDialogAction.types.ts
@@ -0,0 +1,3 @@
+import type { ButtonProps } from "~/components/ui/button";
+
+export type AlertDialogActionProps = ButtonProps<"button">;
diff --git a/src/components/ui/alert-dialog/AlertDialogAction/index.ts b/src/components/ui/alert-dialog/AlertDialogAction/index.ts
new file mode 100644
index 00000000..5ff0fb95
--- /dev/null
+++ b/src/components/ui/alert-dialog/AlertDialogAction/index.ts
@@ -0,0 +1 @@
+export { AlertDialogAction } from "./AlertDialogAction";
diff --git a/src/components/ui/alert-dialog/AlertDialogCancel/AlertDialogCancel.tsx b/src/components/ui/alert-dialog/AlertDialogCancel/AlertDialogCancel.tsx
new file mode 100644
index 00000000..96d0021b
--- /dev/null
+++ b/src/components/ui/alert-dialog/AlertDialogCancel/AlertDialogCancel.tsx
@@ -0,0 +1,24 @@
+import { mergeProps, splitProps } from "solid-js";
+import type { AlertDialogCancelProps } from "./AlertDialogCancel.types";
+import { Button } from "~/components/ui/button";
+import { useDialogContext } from "~/components/ui/dialog";
+
+export const AlertDialogCancel = (props: AlertDialogCancelProps) => {
+  const { setOpen } = useDialogContext();
+
+  const merged = mergeProps({ variant: "outline", size: "md" } as const, props);
+  const [local, others] = splitProps(merged, ["onClick"]);
+
+  return (
+    <Button
+      {...others}
+      data-slot="alert-dialog-cancel"
+      onClick={(event) => {
+        // 与 AlertDialogAction 一致：先转发调用方回调再关闭，
+        // 否则用户的 onClick 会被这一行静默替换掉
+        local.onClick?.(event);
+        setOpen(false);
+      }}
+    />
+  );
+};
diff --git a/src/components/ui/alert-dialog/AlertDialogCancel/AlertDialogCancel.types.ts b/src/components/ui/alert-dialog/AlertDialogCancel/AlertDialogCancel.types.ts
new file mode 100644
index 00000000..c34a66d1
--- /dev/null
+++ b/src/components/ui/alert-dialog/AlertDialogCancel/AlertDialogCancel.types.ts
@@ -0,0 +1,3 @@
+import type { ButtonProps } from "~/components/ui/button";
+
+export type AlertDialogCancelProps = ButtonProps<"button">;
diff --git a/src/components/ui/alert-dialog/AlertDialogCancel/index.ts b/src/components/ui/alert-dialog/AlertDialogCancel/index.ts
new file mode 100644
index 00000000..b0001e2e
--- /dev/null
+++ b/src/components/ui/alert-dialog/AlertDialogCancel/index.ts
@@ -0,0 +1 @@
+export { AlertDialogCancel } from "./AlertDialogCancel";
diff --git a/src/components/ui/alert-dialog/AlertDialogContent/AlertDialogContent.styles.ts b/src/components/ui/alert-dialog/AlertDialogContent/AlertDialogContent.styles.ts
new file mode 100644
index 00000000..69a9f84d
--- /dev/null
+++ b/src/components/ui/alert-dialog/AlertDialogContent/AlertDialogContent.styles.ts
@@ -0,0 +1,4 @@
+const classes =
+  "group/alert-dialog-content fixed top-1/2 left-1/2 z-50 grid w-full -translate-x-1/2 -translate-y-1/2 gap-4 rounded-xl bg-popover p-4 text-popover-foreground ring-1 ring-foreground/10 duration-100 outline-none data-[size=default]:max-w-xs data-[size=sm]:max-w-xs data-[size=default]:sm:max-w-sm data-[open=true]:animate-in data-[open=true]:fade-in-0 data-[open=true]:zoom-in-95 data-[open=false]:animate-out data-[open=false]:fade-out-0 data-[open=false]:zoom-out-95";
+
+export default classes;
diff --git a/src/components/ui/alert-dialog/AlertDialogContent/AlertDialogContent.tsx b/src/components/ui/alert-dialog/AlertDialogContent/AlertDialogContent.tsx
new file mode 100644
index 00000000..83f711c3
--- /dev/null
+++ b/src/components/ui/alert-dialog/AlertDialogContent/AlertDialogContent.tsx
@@ -0,0 +1,23 @@
+import { mergeProps, splitProps } from "solid-js";
+import type { AlertDialogContentProps } from "./AlertDialogContent.types";
+import { clsx } from "~/utils";
+import { DialogSurface } from "~/components/ui/dialog";
+import classes from "./AlertDialogContent.styles";
+
+export const AlertDialogContent = (props: AlertDialogContentProps) => {
+  const merged = mergeProps({ size: "default" } as const, props);
+
+  const [local, others] = splitProps(merged, ["size", "class", "classList"]);
+
+  return (
+    <DialogSurface
+      {...others}
+      role="alertdialog"
+      dismissOnOverlayClick={false}
+      data-slot="alert-dialog-content"
+      data-size={local.size}
+      class={clsx(classes, local.class)}
+      classList={local.classList}
+    />
+  );
+};
diff --git a/src/components/ui/alert-dialog/AlertDialogContent/AlertDialogContent.types.ts b/src/components/ui/alert-dialog/AlertDialogContent/AlertDialogContent.types.ts
new file mode 100644
index 00000000..584fa924
--- /dev/null
+++ b/src/components/ui/alert-dialog/AlertDialogContent/AlertDialogContent.types.ts
@@ -0,0 +1,12 @@
+import type { DialogSurfaceProps } from "~/components/ui/dialog";
+import type { BaseProps } from "~/types";
+
+/**
+ * AlertDialogContent 复用 DialogSurface 的浮层能力（Portal + Overlay + 定位），
+ * 因此必须把 `DialogSurfaceProps` 一并带上：`overlayClass` /
+ * `dismissOnOverlayClick` 在运行时本来就会透传，漏掉类型等于让调用方无法使用。
+ */
+export type AlertDialogContentProps = DialogSurfaceProps &
+  BaseProps & {
+    size?: "default" | "sm";
+  };
diff --git a/src/components/ui/alert-dialog/AlertDialogContent/index.ts b/src/components/ui/alert-dialog/AlertDialogContent/index.ts
new file mode 100644
index 00000000..bfef2894
--- /dev/null
+++ b/src/components/ui/alert-dialog/AlertDialogContent/index.ts
@@ -0,0 +1,2 @@
+export { AlertDialogContent } from "./AlertDialogContent";
+export type { AlertDialogContentProps } from "./AlertDialogContent.types";
diff --git a/src/components/ui/alert-dialog/AlertDialogDescription/AlertDialogDescription.styles.ts b/src/components/ui/alert-dialog/AlertDialogDescription/AlertDialogDescription.styles.ts
new file mode 100644
index 00000000..34a3cb27
--- /dev/null
+++ b/src/components/ui/alert-dialog/AlertDialogDescription/AlertDialogDescription.styles.ts
@@ -0,0 +1,4 @@
+const classes =
+  "text-sm text-balance text-muted-foreground md:text-pretty *:[a]:underline *:[a]:underline-offset-3 *:[a]:hover:text-foreground";
+
+export default classes;
diff --git a/src/components/ui/alert-dialog/AlertDialogDescription/AlertDialogDescription.tsx b/src/components/ui/alert-dialog/AlertDialogDescription/AlertDialogDescription.tsx
new file mode 100644
index 00000000..d69854af
--- /dev/null
+++ b/src/components/ui/alert-dialog/AlertDialogDescription/AlertDialogDescription.tsx
@@ -0,0 +1,27 @@
+import { createUniqueId, onMount, splitProps } from "solid-js";
+import type { AlertDialogDescriptionProps } from "./AlertDialogDescription.types";
+import { clsx } from "~/utils";
+import classes from "./AlertDialogDescription.styles";
+import { useDialogContentContext } from "~/components/ui/dialog";
+
+export const AlertDialogDescription = (props: AlertDialogDescriptionProps) => {
+  const { setDescriptionID } = useDialogContentContext();
+
+  const [local, others] = splitProps(props, ["class", "classList"]);
+
+  const id = createUniqueId();
+
+  onMount(() => {
+    setDescriptionID(id);
+  });
+
+  return (
+    <p
+      id={id}
+      data-slot="alert-dialog-description"
+      class={clsx(classes, local.class)}
+      classList={local.classList}
+      {...others}
+    />
+  );
+};
diff --git a/src/components/ui/alert-dialog/AlertDialogDescription/AlertDialogDescription.types.ts b/src/components/ui/alert-dialog/AlertDialogDescription/AlertDialogDescription.types.ts
new file mode 100644
index 00000000..54463b20
--- /dev/null
+++ b/src/components/ui/alert-dialog/AlertDialogDescription/AlertDialogDescription.types.ts
@@ -0,0 +1,7 @@
+import type { BaseProps, PolymorphicProps } from "~/types";
+
+export type AlertDialogDescriptionProps = PolymorphicProps<
+  "p",
+  BaseProps,
+  false
+>;
diff --git a/src/components/ui/alert-dialog/AlertDialogDescription/index.ts b/src/components/ui/alert-dialog/AlertDialogDescription/index.ts
new file mode 100644
index 00000000..8123d1d7
--- /dev/null
+++ b/src/components/ui/alert-dialog/AlertDialogDescription/index.ts
@@ -0,0 +1 @@
+export { AlertDialogDescription } from "./AlertDialogDescription";
diff --git a/src/components/ui/alert-dialog/AlertDialogFooter/AlertDialogFooter.styles.ts b/src/components/ui/alert-dialog/AlertDialogFooter/AlertDialogFooter.styles.ts
new file mode 100644
index 00000000..28de40f6
--- /dev/null
+++ b/src/components/ui/alert-dialog/AlertDialogFooter/AlertDialogFooter.styles.ts
@@ -0,0 +1,4 @@
+const classes =
+  "-mx-4 -mb-4 flex flex-col-reverse gap-2 rounded-b-xl border-t bg-muted/50 p-4 group-data-[size=sm]/alert-dialog-content:grid group-data-[size=sm]/alert-dialog-content:grid-cols-2 sm:flex-row sm:justify-end";
+
+export default classes;
diff --git a/src/components/ui/alert-dialog/AlertDialogFooter/AlertDialogFooter.tsx b/src/components/ui/alert-dialog/AlertDialogFooter/AlertDialogFooter.tsx
new file mode 100644
index 00000000..db1ed977
--- /dev/null
+++ b/src/components/ui/alert-dialog/AlertDialogFooter/AlertDialogFooter.tsx
@@ -0,0 +1,17 @@
+import { splitProps } from "solid-js";
+import type { AlertDialogFooterProps } from "./AlertDialogFooter.types";
+import { clsx } from "~/utils";
+import classes from "./AlertDialogFooter.styles";
+
+export const AlertDialogFooter = (props: AlertDialogFooterProps) => {
+  const [local, others] = splitProps(props, ["class", "classList"]);
+
+  return (
+    <div
+      data-slot="alert-dialog-footer"
+      class={clsx(classes, local.class)}
+      classList={local.classList}
+      {...others}
+    />
+  );
+};
diff --git a/src/components/ui/alert-dialog/AlertDialogFooter/AlertDialogFooter.types.ts b/src/components/ui/alert-dialog/AlertDialogFooter/AlertDialogFooter.types.ts
new file mode 100644
index 00000000..9fc363df
--- /dev/null
+++ b/src/components/ui/alert-dialog/AlertDialogFooter/AlertDialogFooter.types.ts
@@ -0,0 +1,3 @@
+import type { BaseProps, PolymorphicProps } from "~/types";
+
+export type AlertDialogFooterProps = PolymorphicProps<"div", BaseProps, false>;
diff --git a/src/components/ui/alert-dialog/AlertDialogFooter/index.ts b/src/components/ui/alert-dialog/AlertDialogFooter/index.ts
new file mode 100644
index 00000000..cf392dc5
--- /dev/null
+++ b/src/components/ui/alert-dialog/AlertDialogFooter/index.ts
@@ -0,0 +1 @@
+export { AlertDialogFooter } from "./AlertDialogFooter";
diff --git a/src/components/ui/alert-dialog/AlertDialogHeader/AlertDialogHeader.styles.ts b/src/components/ui/alert-dialog/AlertDialogHeader/AlertDialogHeader.styles.ts
new file mode 100644
index 00000000..746b3023
--- /dev/null
+++ b/src/components/ui/alert-dialog/AlertDialogHeader/AlertDialogHeader.styles.ts
@@ -0,0 +1,4 @@
+const classes =
+  "grid grid-rows-[auto_1fr] place-items-center gap-1.5 text-center has-data-[slot=alert-dialog-media]:grid-rows-[auto_auto_1fr] has-data-[slot=alert-dialog-media]:gap-x-4 sm:group-data-[size=default]/alert-dialog-content:place-items-start sm:group-data-[size=default]/alert-dialog-content:text-left sm:group-data-[size=default]/alert-dialog-content:has-data-[slot=alert-dialog-media]:grid-rows-[auto_1fr]";
+
+export default classes;
diff --git a/src/components/ui/alert-dialog/AlertDialogHeader/AlertDialogHeader.tsx b/src/components/ui/alert-dialog/AlertDialogHeader/AlertDialogHeader.tsx
new file mode 100644
index 00000000..04fac5d8
--- /dev/null
+++ b/src/components/ui/alert-dialog/AlertDialogHeader/AlertDialogHeader.tsx
@@ -0,0 +1,17 @@
+import { splitProps } from "solid-js";
+import type { AlertDialogHeaderProps } from "./AlertDialogHeader.types";
+import { clsx } from "~/utils";
+import classes from "./AlertDialogHeader.styles";
+
+export const AlertDialogHeader = (props: AlertDialogHeaderProps) => {
+  const [local, others] = splitProps(props, ["class", "classList"]);
+
+  return (
+    <div
+      data-slot="alert-dialog-header"
+      class={clsx(classes, local.class)}
+      classList={local.classList}
+      {...others}
+    />
+  );
+};
diff --git a/src/components/ui/alert-dialog/AlertDialogHeader/AlertDialogHeader.types.ts b/src/components/ui/alert-dialog/AlertDialogHeader/AlertDialogHeader.types.ts
new file mode 100644
index 00000000..c6cdc253
--- /dev/null
+++ b/src/components/ui/alert-dialog/AlertDialogHeader/AlertDialogHeader.types.ts
@@ -0,0 +1,3 @@
+import type { BaseProps, PolymorphicProps } from "~/types";
+
+export type AlertDialogHeaderProps = PolymorphicProps<"div", BaseProps, false>;
diff --git a/src/components/ui/alert-dialog/AlertDialogHeader/index.ts b/src/components/ui/alert-dialog/AlertDialogHeader/index.ts
new file mode 100644
index 00000000..932daa43
--- /dev/null
+++ b/src/components/ui/alert-dialog/AlertDialogHeader/index.ts
@@ -0,0 +1 @@
+export { AlertDialogHeader } from "./AlertDialogHeader";
diff --git a/src/components/ui/alert-dialog/AlertDialogMedia/AlertDialogMedia.styles.ts b/src/components/ui/alert-dialog/AlertDialogMedia/AlertDialogMedia.styles.ts
new file mode 100644
index 00000000..b9acb489
--- /dev/null
+++ b/src/components/ui/alert-dialog/AlertDialogMedia/AlertDialogMedia.styles.ts
@@ -0,0 +1,4 @@
+const classes =
+  "mb-2 inline-flex size-10 items-center justify-center rounded-md bg-muted sm:group-data-[size=default]/alert-dialog-content:row-span-2 *:[svg:not([class*='size-'])]:size-6";
+
+export default classes;
diff --git a/src/components/ui/alert-dialog/AlertDialogMedia/AlertDialogMedia.tsx b/src/components/ui/alert-dialog/AlertDialogMedia/AlertDialogMedia.tsx
new file mode 100644
index 00000000..91926c64
--- /dev/null
+++ b/src/components/ui/alert-dialog/AlertDialogMedia/AlertDialogMedia.tsx
@@ -0,0 +1,17 @@
+import { splitProps } from "solid-js";
+import type { AlertDialogMediaProps } from "./AlertDialogMedia.types";
+import { clsx } from "~/utils";
+import classes from "./AlertDialogMedia.styles";
+
+export const AlertDialogMedia = (props: AlertDialogMediaProps) => {
+  const [local, others] = splitProps(props, ["class", "classList"]);
+
+  return (
+    <div
+      data-slot="alert-dialog-media"
+      class={clsx(classes, local.class)}
+      classList={local.classList}
+      {...others}
+    />
+  );
+};
diff --git a/src/components/ui/alert-dialog/AlertDialogMedia/AlertDialogMedia.types.ts b/src/components/ui/alert-dialog/AlertDialogMedia/AlertDialogMedia.types.ts
new file mode 100644
index 00000000..a745d416
--- /dev/null
+++ b/src/components/ui/alert-dialog/AlertDialogMedia/AlertDialogMedia.types.ts
@@ -0,0 +1,3 @@
+import type { BaseProps, PolymorphicProps } from "~/types";
+
+export type AlertDialogMediaProps = PolymorphicProps<"div", BaseProps, false>;
diff --git a/src/components/ui/alert-dialog/AlertDialogMedia/index.ts b/src/components/ui/alert-dialog/AlertDialogMedia/index.ts
new file mode 100644
index 00000000..723f2108
--- /dev/null
+++ b/src/components/ui/alert-dialog/AlertDialogMedia/index.ts
@@ -0,0 +1 @@
+export { AlertDialogMedia } from "./AlertDialogMedia";
diff --git a/src/components/ui/alert-dialog/AlertDialogOverlay/AlertDialogOverlay.tsx b/src/components/ui/alert-dialog/AlertDialogOverlay/AlertDialogOverlay.tsx
new file mode 100644
index 00000000..ad63559a
--- /dev/null
+++ b/src/components/ui/alert-dialog/AlertDialogOverlay/AlertDialogOverlay.tsx
@@ -0,0 +1,6 @@
+import type { AlertDialogOverlayProps } from "./AlertDialogOverlay.types";
+import { DialogOverlay } from "~/components/ui/dialog";
+
+export const AlertDialogOverlay = (props: AlertDialogOverlayProps) => (
+  <DialogOverlay {...props} data-slot="alert-dialog-overlay" />
+);
diff --git a/src/components/ui/alert-dialog/AlertDialogOverlay/AlertDialogOverlay.types.ts b/src/components/ui/alert-dialog/AlertDialogOverlay/AlertDialogOverlay.types.ts
new file mode 100644
index 00000000..eaa2ba43
--- /dev/null
+++ b/src/components/ui/alert-dialog/AlertDialogOverlay/AlertDialogOverlay.types.ts
@@ -0,0 +1,3 @@
+import type { BaseProps, PolymorphicProps } from "~/types";
+
+export type AlertDialogOverlayProps = PolymorphicProps<"div", BaseProps, false>;
diff --git a/src/components/ui/alert-dialog/AlertDialogOverlay/index.ts b/src/components/ui/alert-dialog/AlertDialogOverlay/index.ts
new file mode 100644
index 00000000..c26e6159
--- /dev/null
+++ b/src/components/ui/alert-dialog/AlertDialogOverlay/index.ts
@@ -0,0 +1 @@
+export { AlertDialogOverlay } from "./AlertDialogOverlay";
diff --git a/src/components/ui/alert-dialog/AlertDialogPortal/AlertDialogPortal.tsx b/src/components/ui/alert-dialog/AlertDialogPortal/AlertDialogPortal.tsx
new file mode 100644
index 00000000..2006f42a
--- /dev/null
+++ b/src/components/ui/alert-dialog/AlertDialogPortal/AlertDialogPortal.tsx
@@ -0,0 +1,6 @@
+import type { AlertDialogPortalProps } from "./AlertDialogPortal.types";
+import { DialogPortal } from "~/components/ui/dialog";
+
+export const AlertDialogPortal = (props: AlertDialogPortalProps) => (
+  <DialogPortal {...props} data-slot="alert-dialog-portal" />
+);
diff --git a/src/components/ui/alert-dialog/AlertDialogPortal/AlertDialogPortal.types.ts b/src/components/ui/alert-dialog/AlertDialogPortal/AlertDialogPortal.types.ts
new file mode 100644
index 00000000..c71be52f
--- /dev/null
+++ b/src/components/ui/alert-dialog/AlertDialogPortal/AlertDialogPortal.types.ts
@@ -0,0 +1,3 @@
+import type { BaseProps, PolymorphicProps } from "~/types";
+
+export type AlertDialogPortalProps = PolymorphicProps<"div", BaseProps, false>;
diff --git a/src/components/ui/alert-dialog/AlertDialogPortal/index.ts b/src/components/ui/alert-dialog/AlertDialogPortal/index.ts
new file mode 100644
index 00000000..38b735d4
--- /dev/null
+++ b/src/components/ui/alert-dialog/AlertDialogPortal/index.ts
@@ -0,0 +1 @@
+export { AlertDialogPortal } from "./AlertDialogPortal";
diff --git a/src/components/ui/alert-dialog/AlertDialogTitle/AlertDialogTitle.styles.ts b/src/components/ui/alert-dialog/AlertDialogTitle/AlertDialogTitle.styles.ts
new file mode 100644
index 00000000..7908078b
--- /dev/null
+++ b/src/components/ui/alert-dialog/AlertDialogTitle/AlertDialogTitle.styles.ts
@@ -0,0 +1,4 @@
+const classes =
+  "cn-font-heading text-base font-medium sm:group-data-[size=default]/alert-dialog-content:group-has-data-[slot=alert-dialog-media]/alert-dialog-content:col-start-2";
+
+export default classes;
diff --git a/src/components/ui/alert-dialog/AlertDialogTitle/AlertDialogTitle.tsx b/src/components/ui/alert-dialog/AlertDialogTitle/AlertDialogTitle.tsx
new file mode 100644
index 00000000..40a35f63
--- /dev/null
+++ b/src/components/ui/alert-dialog/AlertDialogTitle/AlertDialogTitle.tsx
@@ -0,0 +1,27 @@
+import { createUniqueId, onMount, splitProps } from "solid-js";
+import type { AlertDialogTitleProps } from "./AlertDialogTitle.types";
+import { clsx } from "~/utils";
+import classes from "./AlertDialogTitle.styles";
+import { useDialogContentContext } from "~/components/ui/dialog";
+
+export const AlertDialogTitle = (props: AlertDialogTitleProps) => {
+  const { setTitleID } = useDialogContentContext();
+
+  const [local, others] = splitProps(props, ["class", "classList"]);
+
+  const id = createUniqueId();
+
+  onMount(() => {
+    setTitleID(id);
+  });
+
+  return (
+    <h2
+      id={id}
+      data-slot="alert-dialog-title"
+      class={clsx(classes, local.class)}
+      classList={local.classList}
+      {...others}
+    />
+  );
+};
diff --git a/src/components/ui/alert-dialog/AlertDialogTitle/AlertDialogTitle.types.ts b/src/components/ui/alert-dialog/AlertDialogTitle/AlertDialogTitle.types.ts
new file mode 100644
index 00000000..ac36feb2
--- /dev/null
+++ b/src/components/ui/alert-dialog/AlertDialogTitle/AlertDialogTitle.types.ts
@@ -0,0 +1,3 @@
+import type { BaseProps, PolymorphicProps } from "~/types";
+
+export type AlertDialogTitleProps = PolymorphicProps<"h2", BaseProps, false>;
diff --git a/src/components/ui/alert-dialog/AlertDialogTitle/index.ts b/src/components/ui/alert-dialog/AlertDialogTitle/index.ts
new file mode 100644
index 00000000..9f20b3f5
--- /dev/null
+++ b/src/components/ui/alert-dialog/AlertDialogTitle/index.ts
@@ -0,0 +1 @@
+export { AlertDialogTitle } from "./AlertDialogTitle";
diff --git a/src/components/ui/alert-dialog/AlertDialogTrigger/AlertDialogTrigger.tsx b/src/components/ui/alert-dialog/AlertDialogTrigger/AlertDialogTrigger.tsx
new file mode 100644
index 00000000..a694cd51
--- /dev/null
+++ b/src/components/ui/alert-dialog/AlertDialogTrigger/AlertDialogTrigger.tsx
@@ -0,0 +1,31 @@
+import type { ValidComponent } from "solid-js";
+import { Dynamic } from "solid-js/web";
+import { Button } from "~/components/ui/button";
+import { useDialogTrigger } from "~/components/ui/dialog";
+import { mergeRefs } from "~/utils";
+import type { AlertDialogTriggerProps } from "./AlertDialogTrigger.types";
+
+/**
+ * 复用 Dialog 的 trigger 逻辑（多态、disabled、aria-haspopup/expanded/state、
+ * addEventListener 不覆盖用户 onClick），只把 data-slot 换成 alert 的。
+ */
+export const AlertDialogTrigger = <
+  T extends ValidComponent = typeof Button<"button">,
+>(
+  props: AlertDialogTriggerProps<T>,
+) => {
+  const { open, isDisabled, attachListeners } = useDialogTrigger(() => props);
+
+  return (
+    <Dynamic
+      {...props}
+      component={(props.component as ValidComponent) ?? Button<"button">}
+      ref={mergeRefs(props.ref, attachListeners)}
+      disabled={isDisabled()}
+      data-slot="alert-dialog-trigger"
+      aria-haspopup="dialog"
+      aria-expanded={open()}
+      data-state={open() ? "open" : "closed"}
+    />
+  );
+};
diff --git a/src/components/ui/alert-dialog/AlertDialogTrigger/AlertDialogTrigger.types.ts b/src/components/ui/alert-dialog/AlertDialogTrigger/AlertDialogTrigger.types.ts
new file mode 100644
index 00000000..77f952af
--- /dev/null
+++ b/src/components/ui/alert-dialog/AlertDialogTrigger/AlertDialogTrigger.types.ts
@@ -0,0 +1,7 @@
+import type { ValidComponent } from "solid-js";
+import type { Button } from "~/components/ui/button";
+import type { DialogTriggerProps } from "~/components/ui/dialog";
+
+export type AlertDialogTriggerProps<
+  T extends ValidComponent = typeof Button<"button">,
+> = DialogTriggerProps<T>;
diff --git a/src/components/ui/alert-dialog/AlertDialogTrigger/index.ts b/src/components/ui/alert-dialog/AlertDialogTrigger/index.ts
new file mode 100644
index 00000000..fe5c812b
--- /dev/null
+++ b/src/components/ui/alert-dialog/AlertDialogTrigger/index.ts
@@ -0,0 +1,2 @@
+export { AlertDialogTrigger } from "./AlertDialogTrigger";
+export type { AlertDialogTriggerProps } from "./AlertDialogTrigger.types";
diff --git a/src/components/ui/alert-dialog/index.ts b/src/components/ui/alert-dialog/index.ts
new file mode 100644
index 00000000..4859a494
--- /dev/null
+++ b/src/components/ui/alert-dialog/index.ts
@@ -0,0 +1,12 @@
+export * from "./AlertDialog";
+export * from "./AlertDialogAction";
+export * from "./AlertDialogCancel";
+export * from "./AlertDialogContent";
+export * from "./AlertDialogDescription";
+export * from "./AlertDialogFooter";
+export * from "./AlertDialogHeader";
+export * from "./AlertDialogMedia";
+export * from "./AlertDialogOverlay";
+export * from "./AlertDialogPortal";
+export * from "./AlertDialogTitle";
+export * from "./AlertDialogTrigger";
diff --git a/src/components/ui/button-group/ButtonGroup/ButtonGroup.tsx b/src/components/ui/button-group/ButtonGroup/ButtonGroup.tsx
index 4b548170..6f9cfbe4 100644
--- a/src/components/ui/button-group/ButtonGroup/ButtonGroup.tsx
+++ b/src/components/ui/button-group/ButtonGroup/ButtonGroup.tsx
@@ -17,6 +17,7 @@ export const ButtonGroup = (props: ButtonGroupProps) => {
         buttonGroupVariants({ orientation: local.orientation }),
         local.class,
       )}
+      classList={local.classList}
       {...others}
     />
   );
diff --git a/src/components/ui/button-group/ButtonGroupText/ButtonGroupText.tsx b/src/components/ui/button-group/ButtonGroupText/ButtonGroupText.tsx
index 9ae0ad36..c5558d9a 100644
--- a/src/components/ui/button-group/ButtonGroupText/ButtonGroupText.tsx
+++ b/src/components/ui/button-group/ButtonGroupText/ButtonGroupText.tsx
@@ -1,13 +1,19 @@
+import { splitProps } from "solid-js";
 import { clsx } from "~/utils";
 import classes from "./ButtonGroupText.styles";
 import type { ButtonGroupTextProps } from "./ButtonGroupText.types";
 
 export const ButtonGroupText = (props: ButtonGroupTextProps) => {
+  // class / classList 必须摘出来：`class=` 写在 `{...props}` 之前时，
+  // Solid 的 spread 会用 node.className 重设类名，把内置样式整体覆盖掉
+  const [local, others] = splitProps(props, ["class", "classList"]);
+
   return (
     <div
       data-slot="button-group-text"
-      class={clsx(classes, props.class)}
-      {...props}
+      class={clsx(classes, local.class)}
+      classList={local.classList}
+      {...others}
     />
   );
 };
diff --git a/src/components/ui/button/Button.tsx b/src/components/ui/button/Button.tsx
index 14d01fca..f19de481 100644
--- a/src/components/ui/button/Button.tsx
+++ b/src/components/ui/button/Button.tsx
@@ -87,6 +87,7 @@ export const Button = <T extends ButtonValidElement = "button">(
         }),
         local.class,
       )}
+      classList={local.classList}
       {...others}
     >
       {resolved()}
diff --git a/src/components/ui/dialog/Dialog/Dialog.context.ts b/src/components/ui/dialog/Dialog/Dialog.context.ts
new file mode 100644
index 00000000..d10624a6
--- /dev/null
+++ b/src/components/ui/dialog/Dialog/Dialog.context.ts
@@ -0,0 +1,24 @@
+import {
+  type Accessor,
+  createContext,
+  type Setter,
+  useContext,
+} from "solid-js";
+
+interface DialogContextValue {
+  show: Accessor<boolean>;
+  setShow: Setter<boolean>;
+  open: Accessor<boolean>;
+  /** 打开/关闭 Dialog；内部会同时处理受控与非受控模式 */
+  setOpen: (open: boolean) => void;
+}
+
+export const DialogContext = createContext<DialogContextValue>();
+
+export const useDialogContext = () => {
+  const context = useContext(DialogContext);
+  if (!context) {
+    throw new Error("useDialogContext 必须用在 <Dialog> 内部");
+  }
+  return context;
+};
diff --git a/src/components/ui/dialog/Dialog/Dialog.styles.ts b/src/components/ui/dialog/Dialog/Dialog.styles.ts
new file mode 100644
index 00000000..e69de29b
diff --git a/src/components/ui/dialog/Dialog/Dialog.tsx b/src/components/ui/dialog/Dialog/Dialog.tsx
new file mode 100644
index 00000000..f8425bd2
--- /dev/null
+++ b/src/components/ui/dialog/Dialog/Dialog.tsx
@@ -0,0 +1,83 @@
+import {
+  createEffect,
+  createMemo,
+  createSignal,
+  onCleanup,
+  splitProps,
+} from "solid-js";
+import { useScrollLock } from "~/hooks/useScrollLock";
+import type { DialogProps } from "./Dialog.types";
+import { DialogContext } from "./Dialog.context";
+
+export const Dialog = (props: DialogProps) => {
+  const [local, others] = splitProps(props, [
+    "open",
+    "defaultOpen",
+    "onOpenChange",
+    "lockScroll",
+    "dismissOnEscape",
+    "children",
+  ]);
+
+  const initialOpen = local.open ?? local.defaultOpen ?? false;
+
+  // 实际显示或卸载信号
+  const [show, setShow] = createSignal(initialOpen);
+  // 内部动画控制信号（非受控模式）
+  const [internalOpen, setInternalOpen] = createSignal(
+    local.defaultOpen ?? false,
+  );
+  // 实际动画控制状态：优先取受控 open，否则取内部状态
+  const open = createMemo(() =>
+    local.open === undefined ? internalOpen() : local.open,
+  );
+  const lockScroll = createMemo(() => props.lockScroll ?? true);
+
+  // 打开期间默认锁定页面滚动：锁住文档滚动并拦截浮层之外的滚轮/触摸，
+  // 内容区自身仍可滚动。传 lockScroll={false} 可关闭该行为。
+  useScrollLock(() => open() && lockScroll(), {
+    allowedSelector: "[data-dialog-surface]",
+  });
+
+  const setOpen = (next: boolean) => {
+    if (local.open === undefined) {
+      setInternalOpen(next);
+    }
+    local.onOpenChange?.(next);
+  };
+
+  // 打开期间按 Escape 关闭（与 Drawer 一致）
+  createEffect(() => {
+    if (!open() || local.dismissOnEscape === false) return;
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key !== "Escape" || event.defaultPrevented) return;
+      event.preventDefault();
+      setOpen(false);
+    };
+    document.addEventListener("keydown", handleKeyDown);
+    onCleanup(() => document.removeEventListener("keydown", handleKeyDown));
+  });
+
+  // 打开时立刻挂载；关闭时保留挂载直到动画结束，由 Content/Overlay 的
+  // onAnimationEnd 负责卸载，保证退场动画能完整播放。
+  createEffect(() => {
+    if (open()) {
+      setShow(true);
+    }
+  });
+
+  return (
+    <DialogContext.Provider
+      value={{
+        show,
+        setShow,
+        open,
+        setOpen,
+      }}
+    >
+      <div data-slot="dialog" {...others}>
+        {local.children}
+      </div>
+    </DialogContext.Provider>
+  );
+};
diff --git a/src/components/ui/dialog/Dialog/Dialog.types.ts b/src/components/ui/dialog/Dialog/Dialog.types.ts
new file mode 100644
index 00000000..81262ced
--- /dev/null
+++ b/src/components/ui/dialog/Dialog/Dialog.types.ts
@@ -0,0 +1,29 @@
+import type { BaseProps, PolymorphicProps } from "~/types";
+
+interface BaseDialogProps {
+  /**
+   * 受控打开状态；不传则由 Dialog 内部自管理。
+   * 传入后可以通过外部状态直接打开/关闭 Dialog。
+   */
+  open?: boolean;
+  /** 非受控模式下的初始打开状态 */
+  defaultOpen?: boolean;
+  /** 打开状态变化时回调 */
+  onOpenChange?: (open: boolean) => void;
+  /**
+   * 按 Escape 是否关闭，默认 true。
+   * AlertDialog 需要"必须显式选择"，因此传 false（对齐 Base UI 的 alert dialog 语义）。
+   */
+  dismissOnEscape?: boolean;
+  /**
+   * 打开时是否锁定页面滚动，默认 true：锁住文档滚动并拦截浮层之外的
+   * 滚轮/触摸滚动，内容区自身仍可滚动。
+   */
+  lockScroll?: boolean;
+}
+
+export type DialogProps = PolymorphicProps<
+  "div",
+  BaseProps & BaseDialogProps,
+  false
+>;
diff --git a/src/components/ui/dialog/Dialog/index.ts b/src/components/ui/dialog/Dialog/index.ts
new file mode 100644
index 00000000..c8de8176
--- /dev/null
+++ b/src/components/ui/dialog/Dialog/index.ts
@@ -0,0 +1,3 @@
+export { Dialog } from "./Dialog";
+export { useDialogContext } from "./Dialog.context";
+export type { DialogProps } from "./Dialog.types";
diff --git a/src/components/ui/dialog/DialogClose/DialogClose.styles.ts b/src/components/ui/dialog/DialogClose/DialogClose.styles.ts
new file mode 100644
index 00000000..a55e10d4
--- /dev/null
+++ b/src/components/ui/dialog/DialogClose/DialogClose.styles.ts
@@ -0,0 +1 @@
+export const classes = "absolute top-2 right-2";
diff --git a/src/components/ui/dialog/DialogClose/DialogClose.tsx b/src/components/ui/dialog/DialogClose/DialogClose.tsx
new file mode 100644
index 00000000..a3f0b7be
--- /dev/null
+++ b/src/components/ui/dialog/DialogClose/DialogClose.tsx
@@ -0,0 +1,43 @@
+import { mergeProps, Show } from "solid-js";
+import type { DialogCloseProps } from "./DialogClose.types";
+import { Button } from "~/components/ui/button";
+import { callEventHandler, clsx } from "~/utils";
+import { classes } from "./DialogClose.styles";
+import { X } from "lucide-solid";
+import { useDialogContext } from "../Dialog";
+
+export const DialogClose = (props: DialogCloseProps) => {
+  const { setOpen } = useDialogContext();
+
+  const merged = mergeProps(
+    {
+      variant: "ghost",
+      size: "sm",
+    } as const,
+    props,
+  );
+
+  const handleClick = (event: MouseEvent) => {
+    setOpen(false);
+    // 透传事件（此前 `merged.onClick?.()` 会让用户回调收到 undefined）
+    callEventHandler(merged.onClick, event);
+  };
+
+  return (
+    <Show
+      when={!merged.icon && !merged.children}
+      fallback={
+        <Button {...merged} data-slot="dialog-close" onClick={handleClick} />
+      }
+    >
+      <Button
+        {...merged}
+        data-slot="dialog-close"
+        class={clsx(classes)}
+        onClick={handleClick}
+        icon={<X />}
+        aria-label="Close Dialog"
+      />
+    </Show>
+  );
+};
diff --git a/src/components/ui/dialog/DialogClose/DialogClose.types.ts b/src/components/ui/dialog/DialogClose/DialogClose.types.ts
new file mode 100644
index 00000000..bd343224
--- /dev/null
+++ b/src/components/ui/dialog/DialogClose/DialogClose.types.ts
@@ -0,0 +1,3 @@
+import type { ButtonProps } from "~/components/ui/button";
+
+export type DialogCloseProps = ButtonProps<"button">;
diff --git a/src/components/ui/dialog/DialogClose/index.ts b/src/components/ui/dialog/DialogClose/index.ts
new file mode 100644
index 00000000..fb97779e
--- /dev/null
+++ b/src/components/ui/dialog/DialogClose/index.ts
@@ -0,0 +1 @@
+export { DialogClose } from "./DialogClose";
diff --git a/src/components/ui/dialog/DialogContent/DialogContent.context.ts b/src/components/ui/dialog/DialogContent/DialogContent.context.ts
new file mode 100644
index 00000000..bd1fb57d
--- /dev/null
+++ b/src/components/ui/dialog/DialogContent/DialogContent.context.ts
@@ -0,0 +1,16 @@
+import { createContext, useContext, type Setter } from "solid-js";
+
+interface DialogContentContextValue {
+  setTitleID: Setter<string | undefined>;
+  setDescriptionID: Setter<string | undefined>;
+}
+
+export const DialogContentContext = createContext<DialogContentContextValue>();
+
+export const useDialogContentContext = () => {
+  const ctx = useContext(DialogContentContext);
+  if (!ctx)
+    throw new Error("useDialogContentContext 必须用在 <DialogContent> 内部");
+
+  return ctx;
+};
diff --git a/src/components/ui/dialog/DialogContent/DialogContent.styles.ts b/src/components/ui/dialog/DialogContent/DialogContent.styles.ts
new file mode 100644
index 00000000..63c9450e
--- /dev/null
+++ b/src/components/ui/dialog/DialogContent/DialogContent.styles.ts
@@ -0,0 +1,2 @@
+export const classes =
+  "fixed top-1/2 left-1/2 z-50 grid w-full max-w-[calc(100%-2rem)] -translate-x-1/2 -translate-y-1/2 gap-4 rounded-xl bg-white dark:bg-neutral-900 p-4 text-sm text-neutral-950 dark:text-neutral-50 ring-1 ring-neutral-950/10 dark:ring-neutral-50/10 duration-100 outline-none sm:max-w-sm data-[open=true]:animate-in data-[open=true]:fade-in-0 data-[open=true]:zoom-in-95 data-[open=false]:animate-out data-[open=false]:fade-out-0 data-[open=false]:zoom-out-95";
diff --git a/src/components/ui/dialog/DialogContent/DialogContent.tsx b/src/components/ui/dialog/DialogContent/DialogContent.tsx
new file mode 100644
index 00000000..351d74a5
--- /dev/null
+++ b/src/components/ui/dialog/DialogContent/DialogContent.tsx
@@ -0,0 +1,32 @@
+import { Show, mergeProps, splitProps } from "solid-js";
+import type { DialogContentProps } from "./DialogContent.types";
+import { clsx } from "~/utils";
+import { classes } from "./DialogContent.styles";
+import { DialogSurface } from "../DialogSurface";
+import { DialogClose } from "../DialogClose";
+
+export const DialogContent = (props: DialogContentProps) => {
+  const merged = mergeProps({ showCloseButton: true } as const, props);
+
+  const [local, others] = splitProps(merged, [
+    "showCloseButton",
+    "class",
+    "classList",
+    "children",
+  ]);
+
+  return (
+    <DialogSurface
+      {...others}
+      role="dialog"
+      data-slot="dialog-content"
+      class={clsx(classes, local.class)}
+      classList={local.classList}
+    >
+      {local.children}
+      <Show when={local.showCloseButton}>
+        <DialogClose />
+      </Show>
+    </DialogSurface>
+  );
+};
diff --git a/src/components/ui/dialog/DialogContent/DialogContent.types.ts b/src/components/ui/dialog/DialogContent/DialogContent.types.ts
new file mode 100644
index 00000000..6dff6c28
--- /dev/null
+++ b/src/components/ui/dialog/DialogContent/DialogContent.types.ts
@@ -0,0 +1,9 @@
+import type { BaseProps, PolymorphicProps } from "~/types";
+
+export type DialogContentProps = PolymorphicProps<
+  "div",
+  BaseProps & {
+    showCloseButton?: boolean;
+  },
+  false
+>;
diff --git a/src/components/ui/dialog/DialogContent/index.ts b/src/components/ui/dialog/DialogContent/index.ts
new file mode 100644
index 00000000..22239d68
--- /dev/null
+++ b/src/components/ui/dialog/DialogContent/index.ts
@@ -0,0 +1,2 @@
+export { DialogContent } from "./DialogContent";
+export { useDialogContentContext } from "./DialogContent.context";
diff --git a/src/components/ui/dialog/DialogDescription/DialogDescription.styles.ts b/src/components/ui/dialog/DialogDescription/DialogDescription.styles.ts
new file mode 100644
index 00000000..0d066dd3
--- /dev/null
+++ b/src/components/ui/dialog/DialogDescription/DialogDescription.styles.ts
@@ -0,0 +1,2 @@
+export const classes =
+  "text-sm text-neutral-500 dark:text-neutral-400 *:[a]:underline *:[a]:underline-offset-3 *:[a]:hover:text-neutral-950 dark:*:[a]:hover:text-neutral-50";
diff --git a/src/components/ui/dialog/DialogDescription/DialogDescription.tsx b/src/components/ui/dialog/DialogDescription/DialogDescription.tsx
new file mode 100644
index 00000000..2ffa7a85
--- /dev/null
+++ b/src/components/ui/dialog/DialogDescription/DialogDescription.tsx
@@ -0,0 +1,27 @@
+import { createUniqueId, onMount, splitProps } from "solid-js";
+import type { DialogDescriptionProps } from "./DialogDescription.types";
+import { clsx } from "~/utils";
+import { classes } from "./DialogDescription.styles";
+import { useDialogContentContext } from "../DialogContent";
+
+export const DialogDescription = (props: DialogDescriptionProps) => {
+  const { setDescriptionID } = useDialogContentContext();
+
+  const [local, others] = splitProps(props, ["class", "classList"]);
+
+  const id = createUniqueId();
+
+  onMount(() => {
+    setDescriptionID(id);
+  });
+
+  return (
+    <p
+      id={id}
+      data-slot="dialog-description"
+      class={clsx(classes, local.class)}
+      classList={local.classList}
+      {...others}
+    />
+  );
+};
diff --git a/src/components/ui/dialog/DialogDescription/DialogDescription.types.ts b/src/components/ui/dialog/DialogDescription/DialogDescription.types.ts
new file mode 100644
index 00000000..58524068
--- /dev/null
+++ b/src/components/ui/dialog/DialogDescription/DialogDescription.types.ts
@@ -0,0 +1,3 @@
+import type { BaseProps, PolymorphicProps } from "~/types";
+
+export type DialogDescriptionProps = PolymorphicProps<"p", BaseProps, false>;
diff --git a/src/components/ui/dialog/DialogDescription/index.ts b/src/components/ui/dialog/DialogDescription/index.ts
new file mode 100644
index 00000000..07e76f44
--- /dev/null
+++ b/src/components/ui/dialog/DialogDescription/index.ts
@@ -0,0 +1 @@
+export { DialogDescription } from "./DialogDescription";
diff --git a/src/components/ui/dialog/DialogFooter/DialogFooter.styles.ts b/src/components/ui/dialog/DialogFooter/DialogFooter.styles.ts
new file mode 100644
index 00000000..3010ba4a
--- /dev/null
+++ b/src/components/ui/dialog/DialogFooter/DialogFooter.styles.ts
@@ -0,0 +1,2 @@
+export const classes =
+  "-mx-4 -mb-4 flex flex-col-reverse gap-2 rounded-b-xl border-t bg-neutral-100/50 dark:bg-neutral-800/50 p-4 sm:flex-row sm:justify-end";
diff --git a/src/components/ui/dialog/DialogFooter/DialogFooter.tsx b/src/components/ui/dialog/DialogFooter/DialogFooter.tsx
new file mode 100644
index 00000000..0dac8d78
--- /dev/null
+++ b/src/components/ui/dialog/DialogFooter/DialogFooter.tsx
@@ -0,0 +1,17 @@
+import { splitProps } from "solid-js";
+import type { DialogFooterProps } from "./DialogFooter.types";
+import { clsx } from "~/utils";
+import { classes } from "./DialogFooter.styles";
+
+export const DialogFooter = (props: DialogFooterProps) => {
+  const [local, others] = splitProps(props, ["class", "classList"]);
+
+  return (
+    <div
+      data-slot="dialog-footer"
+      class={clsx(classes, local.class)}
+      classList={local.classList}
+      {...others}
+    />
+  );
+};
diff --git a/src/components/ui/dialog/DialogFooter/DialogFooter.types.ts b/src/components/ui/dialog/DialogFooter/DialogFooter.types.ts
new file mode 100644
index 00000000..26c44b35
--- /dev/null
+++ b/src/components/ui/dialog/DialogFooter/DialogFooter.types.ts
@@ -0,0 +1,3 @@
+import type { BaseProps, PolymorphicProps } from "~/types";
+
+export type DialogFooterProps = PolymorphicProps<"div", BaseProps, false>;
diff --git a/src/components/ui/dialog/DialogFooter/index.ts b/src/components/ui/dialog/DialogFooter/index.ts
new file mode 100644
index 00000000..979dca7e
--- /dev/null
+++ b/src/components/ui/dialog/DialogFooter/index.ts
@@ -0,0 +1 @@
+export { DialogFooter } from "./DialogFooter";
diff --git a/src/components/ui/dialog/DialogHeader/DialogHeader.styles.ts b/src/components/ui/dialog/DialogHeader/DialogHeader.styles.ts
new file mode 100644
index 00000000..c0f219b9
--- /dev/null
+++ b/src/components/ui/dialog/DialogHeader/DialogHeader.styles.ts
@@ -0,0 +1 @@
+export const classes = "flex flex-col gap-2";
diff --git a/src/components/ui/dialog/DialogHeader/DialogHeader.tsx b/src/components/ui/dialog/DialogHeader/DialogHeader.tsx
new file mode 100644
index 00000000..a57f1100
--- /dev/null
+++ b/src/components/ui/dialog/DialogHeader/DialogHeader.tsx
@@ -0,0 +1,17 @@
+import { splitProps } from "solid-js";
+import type { DialogHeaderProps } from "./DialogHeader.types";
+import { clsx } from "~/utils";
+import { classes } from "./DialogHeader.styles";
+
+export const DialogHeader = (props: DialogHeaderProps) => {
+  const [local, others] = splitProps(props, ["class", "classList"]);
+
+  return (
+    <div
+      data-slot="dialog-header"
+      class={clsx(classes, local.class)}
+      classList={local.classList}
+      {...others}
+    />
+  );
+};
diff --git a/src/components/ui/dialog/DialogHeader/DialogHeader.types.ts b/src/components/ui/dialog/DialogHeader/DialogHeader.types.ts
new file mode 100644
index 00000000..2c0d256b
--- /dev/null
+++ b/src/components/ui/dialog/DialogHeader/DialogHeader.types.ts
@@ -0,0 +1,3 @@
+import type { BaseProps, PolymorphicProps } from "~/types";
+
+export type DialogHeaderProps = PolymorphicProps<"div", BaseProps, false>;
diff --git a/src/components/ui/dialog/DialogHeader/index.ts b/src/components/ui/dialog/DialogHeader/index.ts
new file mode 100644
index 00000000..fe43eac5
--- /dev/null
+++ b/src/components/ui/dialog/DialogHeader/index.ts
@@ -0,0 +1 @@
+export { DialogHeader } from "./DialogHeader";
diff --git a/src/components/ui/dialog/DialogOverlay/DialogOverlay.styles.ts b/src/components/ui/dialog/DialogOverlay/DialogOverlay.styles.ts
new file mode 100644
index 00000000..15632336
--- /dev/null
+++ b/src/components/ui/dialog/DialogOverlay/DialogOverlay.styles.ts
@@ -0,0 +1,2 @@
+export const classes =
+  "fixed inset-0 isolate z-50 bg-black/10 duration-100 supports-backdrop-filter:backdrop-blur-xs data-[open=true]:animate-in data-[open=true]:fade-in-0 data-[open=false]:animate-out data-[open=false]:fade-out-0 select-none";
diff --git a/src/components/ui/dialog/DialogOverlay/DialogOverlay.tsx b/src/components/ui/dialog/DialogOverlay/DialogOverlay.tsx
new file mode 100644
index 00000000..0fbed0d4
--- /dev/null
+++ b/src/components/ui/dialog/DialogOverlay/DialogOverlay.tsx
@@ -0,0 +1,46 @@
+import { mergeProps, splitProps } from "solid-js";
+import type { DialogOverlayProps } from "./DialogOverlay.types";
+import { clsx } from "~/utils";
+import { classes } from "./DialogOverlay.styles";
+import { useDialogContext } from "../Dialog";
+
+export const DialogOverlay = (props: DialogOverlayProps) => {
+  const merged = mergeProps({ dismissOnOverlayClick: true } as const, props);
+
+  const [local, others] = splitProps(merged, [
+    "class",
+    "classList",
+    "dismissOnOverlayClick",
+    "onClick",
+  ]);
+
+  const { open, setShow, setOpen } = useDialogContext();
+
+  return (
+    <div
+      data-slot="dialog-overlay"
+      role="presentation"
+      aria-hidden="true"
+      data-open={open()}
+      class={clsx(classes, local.class)}
+      classList={local.classList}
+      onClick={(
+        event: MouseEvent & {
+          currentTarget: HTMLDivElement;
+          target: Element;
+        },
+      ) => {
+        const userOnClick = local.onClick as
+          | ((e: typeof event) => void)
+          | undefined;
+        userOnClick?.(event);
+        if (local.dismissOnOverlayClick) setOpen(false);
+      }}
+      onAnimationEnd={() => {
+        if (open()) return;
+        setShow(false);
+      }}
+      {...others}
+    />
+  );
+};
diff --git a/src/components/ui/dialog/DialogOverlay/DialogOverlay.types.ts b/src/components/ui/dialog/DialogOverlay/DialogOverlay.types.ts
new file mode 100644
index 00000000..a8a82093
--- /dev/null
+++ b/src/components/ui/dialog/DialogOverlay/DialogOverlay.types.ts
@@ -0,0 +1,10 @@
+import type { BaseProps, PolymorphicProps } from "~/types";
+
+export type DialogOverlayProps = PolymorphicProps<
+  "div",
+  BaseProps & {
+    /** 点击 Overlay 是否关闭，默认 true */
+    dismissOnOverlayClick?: boolean;
+  },
+  false
+>;
diff --git a/src/components/ui/dialog/DialogOverlay/index.ts b/src/components/ui/dialog/DialogOverlay/index.ts
new file mode 100644
index 00000000..8008f0d9
--- /dev/null
+++ b/src/components/ui/dialog/DialogOverlay/index.ts
@@ -0,0 +1 @@
+export { DialogOverlay } from "./DialogOverlay";
diff --git a/src/components/ui/dialog/DialogPortal/DialogPortal.tsx b/src/components/ui/dialog/DialogPortal/DialogPortal.tsx
new file mode 100644
index 00000000..c0083dae
--- /dev/null
+++ b/src/components/ui/dialog/DialogPortal/DialogPortal.tsx
@@ -0,0 +1,10 @@
+import type { DialogPortalProps } from "./DialogPortal.types";
+import { Portal } from "solid-js/web";
+
+export const DialogPortal = (props: DialogPortalProps) => {
+  return (
+    <Portal>
+      <div data-slot="dialog-portal" {...props} />
+    </Portal>
+  );
+};
diff --git a/src/components/ui/dialog/DialogPortal/DialogPortal.types.ts b/src/components/ui/dialog/DialogPortal/DialogPortal.types.ts
new file mode 100644
index 00000000..2e122d05
--- /dev/null
+++ b/src/components/ui/dialog/DialogPortal/DialogPortal.types.ts
@@ -0,0 +1,3 @@
+import type { BaseProps, PolymorphicProps } from "~/types";
+
+export type DialogPortalProps = PolymorphicProps<"div", BaseProps, false>;
diff --git a/src/components/ui/dialog/DialogPortal/index.ts b/src/components/ui/dialog/DialogPortal/index.ts
new file mode 100644
index 00000000..8907cd44
--- /dev/null
+++ b/src/components/ui/dialog/DialogPortal/index.ts
@@ -0,0 +1 @@
+export { DialogPortal } from "./DialogPortal";
diff --git a/src/components/ui/dialog/DialogSurface/DialogSurface.tsx b/src/components/ui/dialog/DialogSurface/DialogSurface.tsx
new file mode 100644
index 00000000..c1bb47b3
--- /dev/null
+++ b/src/components/ui/dialog/DialogSurface/DialogSurface.tsx
@@ -0,0 +1,82 @@
+import {
+  Show,
+  createEffect,
+  createSignal,
+  onCleanup,
+  splitProps,
+} from "solid-js";
+import type { DialogSurfaceProps } from "./DialogSurface.types";
+import { DialogPortal } from "../DialogPortal";
+import { DialogOverlay } from "../DialogOverlay";
+import { DialogContentContext } from "../DialogContent/DialogContent.context";
+import { useDialogContext } from "../Dialog";
+
+export function DialogSurface(props: DialogSurfaceProps) {
+  const { show, open, setShow } = useDialogContext();
+
+  const [local, others] = splitProps(props, [
+    "role",
+    "dismissOnOverlayClick",
+    "overlayClass",
+    "class",
+    "classList",
+    "children",
+  ]);
+
+  const [titleID, setTitleID] = createSignal<string>();
+  const [descriptionID, setDescriptionID] = createSignal<string>();
+  let surfaceRef: HTMLElement | undefined;
+
+  // 打开时把焦点移进浮层，否则键盘/读屏用户仍停在触发按钮上，
+  // 拿不到"对话框已打开"的上下文（Drawer 同样处理）。
+  createEffect(() => {
+    if (!open()) return;
+    const frame = requestAnimationFrame(() => {
+      surfaceRef?.focus({ preventScroll: true });
+    });
+    onCleanup(() => cancelAnimationFrame(frame));
+  });
+
+  return (
+    <Show when={show()}>
+      <DialogContentContext.Provider value={{ setTitleID, setDescriptionID }}>
+        <DialogPortal>
+          <div
+            role="presentation"
+            class="fixed inset-0 select-none"
+            aria-hidden="true"
+          />
+          <DialogOverlay
+            dismissOnOverlayClick={local.dismissOnOverlayClick}
+            class={local.overlayClass}
+          />
+          <span data-type="inside" class="sr-only" aria-hidden="true" />
+          {/* biome-ignore lint/a11y/useAriaPropsSupportedByRole: role 为 dialog/alertdialog，二者都支持 aria-labelledby/aria-describedby */}
+          <div
+            ref={(el) => {
+              surfaceRef = el;
+            }}
+            role={local.role ?? "dialog"}
+            // 模态对话框要让辅助技术知道浮层之外的内容不可交互
+            aria-modal="true"
+            tabindex={-1}
+            data-dialog-surface=""
+            data-open={open()}
+            class={local.class}
+            classList={local.classList}
+            aria-labelledby={titleID()}
+            aria-describedby={descriptionID()}
+            onAnimationEnd={() => {
+              if (open()) return;
+              setShow(false);
+            }}
+            {...others}
+          >
+            {local.children}
+          </div>
+          <span data-type="inside" class="sr-only" aria-hidden="true" />
+        </DialogPortal>
+      </DialogContentContext.Provider>
+    </Show>
+  );
+}
diff --git a/src/components/ui/dialog/DialogSurface/DialogSurface.types.ts b/src/components/ui/dialog/DialogSurface/DialogSurface.types.ts
new file mode 100644
index 00000000..c84dbd62
--- /dev/null
+++ b/src/components/ui/dialog/DialogSurface/DialogSurface.types.ts
@@ -0,0 +1,20 @@
+import type { BaseProps, PolymorphicProps } from "~/types";
+
+/**
+ * DialogSurface 是 Dialog / AlertDialog 共用的「行为外壳」：
+ * 负责 Portal、Overlay、隐藏哨兵节点、挂载/卸载动画，以及 Title/Description
+ * 的 id 注入(通过 DialogContentContext)。视觉样式完全由调用方通过 class 提供，
+ * 因此 DialogContent 与 AlertDialogContent 可以各自维护样式而不互相污染。
+ */
+export type DialogSurfaceProps = PolymorphicProps<
+  "div",
+  BaseProps & {
+    /** 内容区 role，默认 "dialog"；AlertDialog 传 "alertdialog" */
+    role?: "dialog" | "alertdialog";
+    /** 点击 Overlay 是否关闭，默认 true；AlertDialog 传 false */
+    dismissOnOverlayClick?: boolean;
+    /** Overlay 的额外 class */
+    overlayClass?: string;
+  },
+  false
+>;
diff --git a/src/components/ui/dialog/DialogSurface/index.ts b/src/components/ui/dialog/DialogSurface/index.ts
new file mode 100644
index 00000000..21898813
--- /dev/null
+++ b/src/components/ui/dialog/DialogSurface/index.ts
@@ -0,0 +1,2 @@
+export { DialogSurface } from "./DialogSurface";
+export type { DialogSurfaceProps } from "./DialogSurface.types";
diff --git a/src/components/ui/dialog/DialogTitle/DialogTitle.styles.ts b/src/components/ui/dialog/DialogTitle/DialogTitle.styles.ts
new file mode 100644
index 00000000..0e59e721
--- /dev/null
+++ b/src/components/ui/dialog/DialogTitle/DialogTitle.styles.ts
@@ -0,0 +1 @@
+export const classes = "cn-font-heading text-base leading-none font-medium";
diff --git a/src/components/ui/dialog/DialogTitle/DialogTitle.tsx b/src/components/ui/dialog/DialogTitle/DialogTitle.tsx
new file mode 100644
index 00000000..fdc272cf
--- /dev/null
+++ b/src/components/ui/dialog/DialogTitle/DialogTitle.tsx
@@ -0,0 +1,27 @@
+import { createUniqueId, onMount, splitProps } from "solid-js";
+import type { DialogTitleProps } from "./DialogTitle.types";
+import { clsx } from "~/utils";
+import { classes } from "./DialogTitle.styles";
+import { useDialogContentContext } from "../DialogContent";
+
+export const DialogTitle = (props: DialogTitleProps) => {
+  const { setTitleID } = useDialogContentContext();
+
+  const [local, others] = splitProps(props, ["class", "classList"]);
+
+  const id = createUniqueId();
+
+  onMount(() => {
+    setTitleID(id);
+  });
+
+  return (
+    <h2
+      id={id}
+      data-slot="dialog-title"
+      class={clsx(classes, local.class)}
+      classList={local.classList}
+      {...others}
+    />
+  );
+};
diff --git a/src/components/ui/dialog/DialogTitle/DialogTitle.types.ts b/src/components/ui/dialog/DialogTitle/DialogTitle.types.ts
new file mode 100644
index 00000000..f37be8ae
--- /dev/null
+++ b/src/components/ui/dialog/DialogTitle/DialogTitle.types.ts
@@ -0,0 +1,3 @@
+import type { BaseProps, PolymorphicProps } from "~/types";
+
+export type DialogTitleProps = PolymorphicProps<"h2", BaseProps, false>;
diff --git a/src/components/ui/dialog/DialogTitle/index.ts b/src/components/ui/dialog/DialogTitle/index.ts
new file mode 100644
index 00000000..d9432319
--- /dev/null
+++ b/src/components/ui/dialog/DialogTitle/index.ts
@@ -0,0 +1 @@
+export { DialogTitle } from "./DialogTitle";
diff --git a/src/components/ui/dialog/DialogTrigger/DialogTrigger.tsx b/src/components/ui/dialog/DialogTrigger/DialogTrigger.tsx
new file mode 100644
index 00000000..d534ff20
--- /dev/null
+++ b/src/components/ui/dialog/DialogTrigger/DialogTrigger.tsx
@@ -0,0 +1,29 @@
+import type { ValidComponent } from "solid-js";
+import { Dynamic } from "solid-js/web";
+
+import { useDialogTrigger } from "./useDialogTrigger";
+import type { DialogTriggerProps } from "./DialogTrigger.types";
+
+import { Button } from "~/components/ui/button";
+import { mergeRefs } from "~/utils";
+
+export const DialogTrigger = <
+  T extends ValidComponent = typeof Button<"button">,
+>(
+  props: DialogTriggerProps<T>,
+) => {
+  const { open, isDisabled, attachListeners } = useDialogTrigger(() => props);
+
+  return (
+    <Dynamic
+      {...props}
+      component={(props.component as ValidComponent) ?? Button<"button">}
+      ref={mergeRefs(props.ref, attachListeners)}
+      disabled={isDisabled()}
+      data-slot="dialog-trigger"
+      aria-haspopup="dialog"
+      aria-expanded={open()}
+      data-state={open() ? "open" : "closed"}
+    />
+  );
+};
diff --git a/src/components/ui/dialog/DialogTrigger/DialogTrigger.types.ts b/src/components/ui/dialog/DialogTrigger/DialogTrigger.types.ts
new file mode 100644
index 00000000..5eea8de2
--- /dev/null
+++ b/src/components/ui/dialog/DialogTrigger/DialogTrigger.types.ts
@@ -0,0 +1,4 @@
+import type { ValidComponent } from "solid-js";
+import type { PolymorphicProps } from "~/types";
+
+export type DialogTriggerProps<T extends ValidComponent> = PolymorphicProps<T>;
diff --git a/src/components/ui/dialog/DialogTrigger/index.ts b/src/components/ui/dialog/DialogTrigger/index.ts
new file mode 100644
index 00000000..07d53c92
--- /dev/null
+++ b/src/components/ui/dialog/DialogTrigger/index.ts
@@ -0,0 +1,4 @@
+export { DialogTrigger } from "./DialogTrigger";
+export type { DialogTriggerProps } from "./DialogTrigger.types";
+export { useDialogTrigger } from "./useDialogTrigger";
+export type { UseDialogTriggerResult } from "./useDialogTrigger";
diff --git a/src/components/ui/dialog/DialogTrigger/useDialogTrigger.ts b/src/components/ui/dialog/DialogTrigger/useDialogTrigger.ts
new file mode 100644
index 00000000..df1ddbca
--- /dev/null
+++ b/src/components/ui/dialog/DialogTrigger/useDialogTrigger.ts
@@ -0,0 +1,38 @@
+import { onCleanup, type ValidComponent } from "solid-js";
+import { useDialogContext } from "../Dialog";
+import type { DialogTriggerProps } from "./DialogTrigger.types";
+
+export interface UseDialogTriggerResult {
+  open: () => boolean;
+  isDisabled: () => boolean;
+  /**
+   * 把打开 Dialog 的 click 监听器绑定到真正的 DOM 元素上（通过 ref 调用）。
+   * 使用 addEventListener 而不是 JSX 的 onClick prop，是为了不占用 onClick——
+   * 调用方自己传的 onClick 不会被覆盖，两者都会触发。
+   */
+  attachListeners: (el: Element) => void;
+}
+
+export function useDialogTrigger<T extends ValidComponent>(
+  props: () => DialogTriggerProps<T>,
+): UseDialogTriggerResult {
+  const { open, setOpen } = useDialogContext();
+
+  const isDisabled = () => !!props().disabled;
+
+  const attachListeners = (el: Element) => {
+    const onClick = () => {
+      if (isDisabled()) return;
+      if (open()) return;
+      setOpen(true);
+    };
+
+    el.addEventListener("click", onClick);
+
+    onCleanup(() => {
+      el.removeEventListener("click", onClick);
+    });
+  };
+
+  return { open, isDisabled, attachListeners };
+}
diff --git a/src/components/ui/dialog/index.ts b/src/components/ui/dialog/index.ts
new file mode 100644
index 00000000..96dd1ab6
--- /dev/null
+++ b/src/components/ui/dialog/index.ts
@@ -0,0 +1,11 @@
+export * from "./Dialog";
+export * from "./DialogClose";
+export * from "./DialogContent";
+export * from "./DialogSurface";
+export * from "./DialogDescription";
+export * from "./DialogFooter";
+export * from "./DialogHeader";
+export * from "./DialogOverlay";
+export * from "./DialogPortal";
+export * from "./DialogTitle";
+export * from "./DialogTrigger";
diff --git a/src/i18n/en-US.ts b/src/i18n/en-US.ts
index c487f112..95eeff78 100644
--- a/src/i18n/en-US.ts
+++ b/src/i18n/en-US.ts
@@ -185,6 +185,10 @@ export const dict = {
       tagline: "Dwall · solar-driven",
       logoAlt: "Dwall logo",
       sourceCode: "Source code",
+      changelog: "Changelog",
+      changelogSub: "Release notes",
+      whatsNewFor: "What's new in {{ version }}",
+      whatsNew: "What's new",
       sourceSub: "github.com",
       logDir: "Log directory",
       logDirSub: "Open folder",
diff --git a/src/i18n/ja-JP.ts b/src/i18n/ja-JP.ts
index 7e024228..f97ec244 100644
--- a/src/i18n/ja-JP.ts
+++ b/src/i18n/ja-JP.ts
@@ -187,6 +187,10 @@ export const dict: RawDictionary = {
       tagline: "Dwall · 太陽位置駆動",
       logoAlt: "Dwall ロゴ",
       sourceCode: "ソースコード",
+      changelog: "変更履歴",
+      changelogSub: "リリースノート",
+      whatsNewFor: "{{ version }} の更新内容",
+      whatsNew: "更新内容",
       sourceSub: "github.com",
       logDir: "ログディレクトリ",
       logDirSub: "フォルダーを開く",
diff --git a/src/i18n/ko-KR.ts b/src/i18n/ko-KR.ts
index f778d542..59b07f29 100644
--- a/src/i18n/ko-KR.ts
+++ b/src/i18n/ko-KR.ts
@@ -186,6 +186,10 @@ export const dict: RawDictionary = {
       tagline: "Dwall · 태양 위치 기반",
       logoAlt: "Dwall 로고",
       sourceCode: "소스 코드",
+      changelog: "변경 내역",
+      changelogSub: "릴리스 노트",
+      whatsNewFor: "{{ version }} 새로운 기능",
+      whatsNew: "새로운 기능",
       sourceSub: "github.com",
       logDir: "로그 디렉터리",
       logDirSub: "폴더 열기",
diff --git a/src/i18n/zh-CN.ts b/src/i18n/zh-CN.ts
index 293b3440..bfb841cc 100644
--- a/src/i18n/zh-CN.ts
+++ b/src/i18n/zh-CN.ts
@@ -181,6 +181,10 @@ export const dict: RawDictionary = {
       tagline: "Dwall · 太阳位置驱动",
       logoAlt: "Dwall 徽标",
       sourceCode: "源代码",
+      changelog: "更新日志",
+      changelogSub: "发布说明",
+      whatsNewFor: "{{ version }} 的更新内容",
+      whatsNew: "更新内容",
       sourceSub: "github.com",
       logDir: "日志目录",
       logDirSub: "打开文件夹",
diff --git a/src/i18n/zh-HK.ts b/src/i18n/zh-HK.ts
index c0187f3e..900c258a 100644
--- a/src/i18n/zh-HK.ts
+++ b/src/i18n/zh-HK.ts
@@ -181,6 +181,10 @@ export const dict: RawDictionary = {
       tagline: "Dwall · 太陽位置驅動",
       logoAlt: "Dwall 標誌",
       sourceCode: "原始碼",
+      changelog: "更新日誌",
+      changelogSub: "發佈說明",
+      whatsNewFor: "{{ version }} 的更新內容",
+      whatsNew: "更新內容",
       sourceSub: "github.com",
       logDir: "日誌目錄",
       logDirSub: "開啟資料夾",
diff --git a/src/i18n/zh-TW.ts b/src/i18n/zh-TW.ts
index d3a6ab23..af49e9e0 100644
--- a/src/i18n/zh-TW.ts
+++ b/src/i18n/zh-TW.ts
@@ -181,6 +181,10 @@ export const dict: RawDictionary = {
       tagline: "Dwall · 太陽位置驅動",
       logoAlt: "Dwall 標誌",
       sourceCode: "原始碼",
+      changelog: "更新日誌",
+      changelogSub: "發佈說明",
+      whatsNewFor: "{{ version }} 的更新內容",
+      whatsNew: "更新內容",
       sourceSub: "github.com",
       logDir: "日誌目錄",
       logDirSub: "開啟資料夾",
diff --git a/src/lib/release-notes.test.ts b/src/lib/release-notes.test.ts
new file mode 100644
index 00000000..59598d95
--- /dev/null
+++ b/src/lib/release-notes.test.ts
@@ -0,0 +1,82 @@
+import { describe, expect, test } from "vitest";
+
+import { parseReleaseNoteSpans, parseReleaseNotes } from "./release-notes";
+
+describe("release notes: blocks", () => {
+  test("a bullet list becomes one list block", () => {
+    expect(parseReleaseNotes(["- one", "- two", "* three"].join("\n"))).toEqual(
+      [{ kind: "list", items: ["one", "two", "three"] }],
+    );
+  });
+
+  test("a blank line ends the list", () => {
+    expect(parseReleaseNotes("- one\n\n- two")).toEqual([
+      { kind: "list", items: ["one"] },
+      { kind: "list", items: ["two"] },
+    ]);
+  });
+
+  test("headings of any level become heading blocks", () => {
+    expect(parseReleaseNotes("## Top\n### Deeper")).toEqual([
+      { kind: "heading", text: "Top" },
+      { kind: "heading", text: "Deeper" },
+    ]);
+  });
+
+  /** `#hashtag` is text, not a heading: a heading needs the space. */
+  test("a hash without a space stays a paragraph", () => {
+    expect(parseReleaseNotes("#hashtag")).toEqual([
+      { kind: "paragraph", text: "#hashtag" },
+    ]);
+  });
+
+  test("plain lines become paragraphs and the list resumes after them", () => {
+    expect(parseReleaseNotes("- one\nBoth are listed.\n- two")).toEqual([
+      { kind: "list", items: ["one"] },
+      { kind: "paragraph", text: "Both are listed." },
+      { kind: "list", items: ["two"] },
+    ]);
+  });
+
+  test("carriage returns are tolerated", () => {
+    expect(parseReleaseNotes("- one\r\n- two\r\n")).toEqual([
+      { kind: "list", items: ["one", "two"] },
+    ]);
+  });
+
+  test("empty notes produce no blocks", () => {
+    expect(parseReleaseNotes("")).toEqual([]);
+    expect(parseReleaseNotes("\n\n")).toEqual([]);
+  });
+});
+
+describe("release notes: spans", () => {
+  test("backticks mark code", () => {
+    expect(parseReleaseNoteSpans("run `dwall.exe` now")).toEqual([
+      { code: false, text: "run " },
+      { code: true, text: "dwall.exe" },
+      { code: false, text: " now" },
+    ]);
+  });
+
+  test("text without backticks is one plain span", () => {
+    expect(parseReleaseNoteSpans("plain")).toEqual([
+      { code: false, text: "plain" },
+    ]);
+  });
+
+  /** An unbalanced backtick swallows the rest as code rather than dropping it. */
+  test("an unbalanced backtick keeps the text visible", () => {
+    expect(parseReleaseNoteSpans("a `b")).toEqual([
+      { code: false, text: "a " },
+      { code: true, text: "b" },
+    ]);
+  });
+
+  test("empty spans are dropped", () => {
+    expect(parseReleaseNoteSpans("`a``b`")).toEqual([
+      { code: true, text: "a" },
+      { code: true, text: "b" },
+    ]);
+  });
+});
diff --git a/src/lib/release-notes.ts b/src/lib/release-notes.ts
new file mode 100644
index 00000000..b64c0c53
--- /dev/null
+++ b/src/lib/release-notes.ts
@@ -0,0 +1,79 @@
+// Responsibility: the small slice of Markdown release notes actually use (headings, bullet lists,
+// paragraphs, inline `code`), parsed into blocks so the view can render them as elements.
+
+/** One line of inline text, flagged when it came from between backticks. */
+export interface ReleaseNoteSpan {
+  code: boolean;
+  text: string;
+}
+
+export type ReleaseNoteBlock =
+  | { kind: "heading"; text: string }
+  | { kind: "list"; items: string[] }
+  | { kind: "paragraph"; text: string };
+
+const HEADING = /^#{1,6}\s+(.+)$/;
+const BULLET = /^[-*]\s+(.+)$/;
+
+/**
+ * Splits release notes into blocks.
+ *
+ * Deliberately not a Markdown parser: the notes are a generated bullet list, and pulling in
+ * a parser (or an HTML sink) for that would add a dependency and an injection surface. What
+ * is not recognised stays visible as text, which is the safe default for a link or a stray
+ * `*`.
+ */
+export function parseReleaseNotes(markdown: string): ReleaseNoteBlock[] {
+  const blocks: ReleaseNoteBlock[] = [];
+  let items: string[] = [];
+
+  const flushList = () => {
+    if (items.length === 0) return;
+
+    blocks.push({ kind: "list", items });
+    items = [];
+  };
+
+  for (const rawLine of markdown.split(/\r?\n/)) {
+    const line = rawLine.trimEnd();
+
+    if (line.trim() === "") {
+      flushList();
+      continue;
+    }
+
+    const heading = HEADING.exec(line);
+    if (heading) {
+      flushList();
+      blocks.push({ kind: "heading", text: heading[1].trim() });
+      continue;
+    }
+
+    const bullet = BULLET.exec(line);
+    if (bullet) {
+      items.push(bullet[1].trim());
+      continue;
+    }
+
+    flushList();
+    blocks.push({ kind: "paragraph", text: line.trim() });
+  }
+
+  flushList();
+
+  return blocks;
+}
+
+/**
+ * Splits a line into plain and `code` spans.
+ *
+ * The segments of `split("`")` alternate outside/inside, so an odd index is a code span. An
+ * unbalanced backtick therefore swallows the rest of the line as code instead of being
+ * dropped, which keeps the text visible.
+ */
+export function parseReleaseNoteSpans(text: string): ReleaseNoteSpan[] {
+  return text
+    .split("`")
+    .map((part, index) => ({ code: index % 2 === 1, text: part }))
+    .filter((span) => span.text !== "");
+}
diff --git a/src/store/update.store.test.ts b/src/store/update.store.test.ts
index 975446da..e7c93291 100644
--- a/src/store/update.store.test.ts
+++ b/src/store/update.store.test.ts
@@ -30,9 +30,10 @@ vi.mock("./settings.store", () => ({
 }));
 
 /** An update handle as the updater plugin hands it over. */
-function updateHandle(version: string) {
+function updateHandle(version: string, body?: string) {
   return {
     version,
+    body,
     close: vi.fn().mockResolvedValue(undefined),
     downloadAndInstall: vi.fn().mockResolvedValue(undefined),
   };
@@ -65,6 +66,45 @@ describe("update store: checking on start-up", () => {
     expect(mocks.toastInfo.mock.calls[0][1].action.label).toBeDefined();
   });
 
+  test("the release notes the manifest carried reach the widget", async () => {
+    mocks.checkForUpdates.mockResolvedValue(
+      updateHandle("0.3.0", "### Added\n- changelog button"),
+    );
+
+    const store = await freshStore();
+    await store.checkOnStartup();
+
+    expect(store.updateStore.notes).toContain("changelog button");
+  });
+
+  /**
+   * A check that finds nothing must not leave the previous version's notes in place: the
+   * widget would show "what's new" for a release the user is already past.
+   */
+  test("a later check clears the notes", async () => {
+    mocks.checkForUpdates.mockResolvedValueOnce(
+      updateHandle("0.3.0", "old notes"),
+    );
+    mocks.checkForUpdates.mockResolvedValueOnce(null);
+
+    const store = await freshStore();
+    await store.check();
+    expect(store.updateStore.notes).toBe("old notes");
+
+    await store.check();
+    expect(store.updateStore.notes).toBeNull();
+  });
+
+  test("an update without notes reports none", async () => {
+    mocks.checkForUpdates.mockResolvedValue(updateHandle("0.3.0"));
+
+    const store = await freshStore();
+    await store.check();
+
+    expect(store.updateStore.status).toBe("available");
+    expect(store.updateStore.notes).toBeNull();
+  });
+
   test("being up to date is not announced", async () => {
     mocks.checkForUpdates.mockResolvedValue(null);
 
diff --git a/src/store/update.store.ts b/src/store/update.store.ts
index f85b6cc5..bd984348 100644
--- a/src/store/update.store.ts
+++ b/src/store/update.store.ts
@@ -27,6 +27,8 @@ interface UpdateState {
   version: string | null;
   progress: number | null;
   error: string | null;
+  /** Release notes of the offered version, when the manifest carried them. */
+  notes: string | null;
 }
 
 const [updateStore, setUpdateStore] = createStore<UpdateState>({
@@ -34,6 +36,7 @@ const [updateStore, setUpdateStore] = createStore<UpdateState>({
   version: null,
   progress: null,
   error: null,
+  notes: null,
 });
 
 /** Handle of the update that can be installed right now; non-reactive — its derived fields are synced into the store. */
@@ -95,6 +98,7 @@ const runCheck = async (automatic: boolean) => {
     version: null,
     progress: null,
     error: null,
+    notes: null,
   });
 
   try {
@@ -107,7 +111,11 @@ const runCheck = async (automatic: boolean) => {
     }
 
     pending = update;
-    setUpdateStore({ status: "available", version: update.version });
+    setUpdateStore({
+      status: "available",
+      version: update.version,
+      notes: update.body ?? null,
+    });
 
     if (automatic) announceUpdate(update.version);
   } catch (e) {
diff --git a/src/types/props.types.ts b/src/types/props.types.ts
index 0aaa7bc0..4cb864f7 100644
--- a/src/types/props.types.ts
+++ b/src/types/props.types.ts
@@ -3,7 +3,7 @@ import type { JSX, ComponentProps, ValidComponent } from "solid-js";
 export type EmptyObject = Record<never, never>;
 
 export type MouseEventHandler<T extends keyof HTMLElementTagNameMap> = (
-  e?: MouseEvent & {
+  e: MouseEvent & {
     currentTarget: HTMLElementTagNameMap[T];
     target: Element;
   },