From b144fb578ec1d9e5ac233dc76efcd687ab61e352 Mon Sep 17 00:00:00 2001
From: jack755051 <jack755051@gmail.com>
Date: Mon, 21 Sep 2026 22:46:48 +0800
Subject: [PATCH 01/13] fix(registry): associate the login block remember-me
 label for eslint

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 registry/blocks/login/login.component.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/registry/blocks/login/login.component.ts b/registry/blocks/login/login.component.ts
index 3ea4c43..55984ad 100644
--- a/registry/blocks/login/login.component.ts
+++ b/registry/blocks/login/login.component.ts
@@ -75,6 +75,7 @@ import { LinkDirective } from '../link';
                   [checked]="rememberMe"
                   (checkedChange)="rememberMe = $event === true"
                 />
+                <!-- eslint-disable-next-line @angular-eslint/template/label-has-associated-control -->
                 <label sanringLabel class="text-sm">Remember me</label>
               </div>
               <a sanringLink href="#">Forgot password?</a>

From 169ed16dd33bf873e33024af5da17c44c68ad248 Mon Sep 17 00:00:00 2001
From: jack755051 <jack755051@gmail.com>
Date: Mon, 21 Sep 2026 22:48:11 +0800
Subject: [PATCH 02/13] chore: add empty changeset for the login block lint fix

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .changeset/login-remember-me-label.md | 4 ++++
 1 file changed, 4 insertions(+)
 create mode 100644 .changeset/login-remember-me-label.md

diff --git a/.changeset/login-remember-me-label.md b/.changeset/login-remember-me-label.md
new file mode 100644
index 0000000..a53fc98
--- /dev/null
+++ b/.changeset/login-remember-me-label.md
@@ -0,0 +1,4 @@
+---
+---
+
+Associate the login block remember-me label so eslint template/label-has-associated-control passes.

From fb3f68298b241d432fe08ff0cf19cf7def0ff89c Mon Sep 17 00:00:00 2001
From: jack755051 <jack755051@gmail.com>
Date: Tue, 22 Sep 2026 10:07:00 +0800
Subject: [PATCH 03/13] docs: track P32 component completeness gaps

Record the 52-component API sibling-alignment scan and table sticky
follow-ups so roadmap work stays out of the 0.25.0 polish commits.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 ROADMAP.md                                    | 11 ++++++
 TODOLIST.md                                   | 39 +++++++++++++++++++
 .../ui/src/lib/components/table/todolist.md   |  2 +
 3 files changed, 52 insertions(+)

diff --git a/ROADMAP.md b/ROADMAP.md
index fdceebb..fbeb681 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -8,6 +8,17 @@ This is a snapshot, not a commitment or a timeline. Items move, get reprioritize
 
 - **More blocks** — remaining page templates (`register`, `forgot-password`, `settings-page`, `detail-page`, `wizard`, `pricing-page`) on top of the starter three.
 
+## Component completeness
+
+Sibling alignment and advertised capabilities — not new primitives. Tracked as P32 in [`TODOLIST.md`](TODOLIST.md).
+
+- **Table** — sticky column background; docs recipes for loading skeleton rows and column show/hide
+- **Sheet** — built-in close control and header `align`, to match dialog
+- **Radio** — `size` variants aligned with checkbox / switch
+- **Dropdown menu** — a real nested submenu (docs keyboard table already describes it)
+- **Popover** — four-way `side` plus an accessible name when no title is projected
+- **Transfer** — root `disabled` and `ariaLabel`
+
 ## Ecosystem / team use
 
 - **Registry Directory** — a docs page listing community/third-party registries, so teams can discover each other's component sets.
diff --git a/TODOLIST.md b/TODOLIST.md
index 471358a..262a8b4 100644
--- a/TODOLIST.md
+++ b/TODOLIST.md
@@ -42,3 +42,42 @@
 **影響**：shadcn 的 registry 生態是目前採用率的核心驅動之一——開發者能找到、安裝、分享社群元件，讓整個 UI library 不只靠官方維護。Angular 生態目前沒有等價物，這是 Sanring 差異化的機會。
 
 **成本**：高。各子項目可獨立交付。GitHub Registries 與 API Reference 已出貨；下一步是 Directory 和 Auth。
+
+---
+
+## P32 — 52 元件產品/API 掃描：對齊既有組件，不新增 primitive
+
+2026-09-22 對 `packages/ui` 52 個正式元件做產品/API 掃描（公開 input/output、兄弟組件對齊、docs 是否超賣能力）。不是重跑 P3/P26/P30 的 a11y 稽核。`check-registry-parity.mjs` 與 `check-registry-sync.mjs` 當日皆綠（52/52）。官方目錄不缺新 primitive；該做的是把兄弟組件對齊，以及把 docs 已經講出去的能力做完。
+
+0.25.0 進行中的 input/textarea/combobox count、combobox chip wrap、dialog header `align`/獨立底色**不列入本項**，那些收斂完再看要不要疊。
+
+### 該做
+
+- [ ] **table sticky 欄背景**：`sticky`/`stickyEnd` 已能傳進 CDK，但 CDK 只加 `position: sticky` + 位移，沒有不透明背景；捲動時文字會透出來。細節與「刻意不做」的 `CdkTextColumn` / CDK flex-layout 見 [packages/ui/src/lib/components/table/todolist.md](packages/ui/src/lib/components/table/todolist.md)
+- [ ] **table docs 配方**（不寫新元件）：loading skeleton rows（既有 `skeleton`）；欄位顯隱（dropdown-menu + checkbox + 動態 `sanringRowDefColumns`）。同上 todolist「使用模式」節
+- [ ] **sheet 對齊 dialog**：dialog content 已有內建 `showClose` / `closeAriaLabel`，header 已有 `align`；sheet 還要自己放 `[sanringSheetClose]`，`sanring-sheet-header` 沒有 `align`
+- [ ] **radio `size`**：checkbox / switch / otp-input 有 sm/md/lg；radio 寫死 `RADIO_SIZE_CLASS = 'aspect-square h-4 w-4'`（`radio.styles.ts`）
+- [ ] **dropdown-menu 真 submenu**：docs 鍵盤表寫了左右鍵開關子選單，官網範例卻是 `mouseenter` 切兩欄，不是巢狀 `menu`。checkbox / radio 範例用打勾圖示組出來即可，不必先做成一等 primitive
+- [ ] **popover `side` + aria fallback**：tooltip / hover-card 已有四向 `side`；popover 只做上/下，而且沒投影 title 時仍綁死 `aria-labelledby`（`popover-content.component.ts`）
+- [ ] **transfer 根層 `disabled` + `ariaLabel`**：現在只能 disable 單一 item（`TransferItem.disabled`）；雙列表是沒名字的 `role="group"`
+
+### 可選（有缺口，但已有組合路徑）
+
+- [ ] **combobox** trigger/input 補 `ariaLabel` / `ariaLabelledBy`（已有 `sanring-combobox-label` 與 field 整合）
+- [ ] **select** 補獨立 `required` input（現在只從 `Validators.required` 推導，`aria-required` 吃不到純 template `[required]`）
+- [ ] **toast docs** 補 `ToastOptions.class`（型別已有，走 service，不要加元件級 `class` `@Input`）
+
+### 明確不做（查證後不是缺口，避免下次掃描重開）
+
+- 新 primitive（`kbd` / `chart` / `toggle-group` / `empty` 等）——官方方向在 blocks 與 registry 生態，不在再堆元件
+- input / textarea 再包一層 `disabled` / `aria-*` input——原生 host 屬性 + `SanringFieldControl` 是刻意的薄 API
+- toast 元件級 `class` `@Input`——走 `ToastOptions.class`
+- table `CdkTextColumn`、CDK flex-layout `<cdk-table>`——見 table todolist，已明示不做
+- dialog 加 `[(isOpen)]`——CDK Dialog 是 service 開啟；sheet / popover 的 `isOpen` model 是另一套 overlay。沒需求不要硬對齊
+- 每個控制項都加 `size`——field 高度契約是共用的 `FIELD_SIZE_CLASS`；radio 是唯一跟 checkbox/switch 並排會明顯不齊的
+
+**現況**：52 個元件裡約 44 個判定維持。alert-dialog 沒有自己的 `class` 沒關係（複用 dialog 零件，`showClose` 預設關是對的）。dropdown-menu 的 checkbox/radio docs 範例是組合解法，不是假文件。
+
+**影響**：不處理的話，消費者會在「看起來該有的兄弟 API」上卡關（sheet 關閉鈕、radio 尺寸、popover 左右、transfer 整組停用），或照著 dropdown-menu 鍵盤表做出不能用方向鍵開的子選單。
+
+**成本**：中。各子項可獨立交付；table docs 配方最低、sheet/radio 次之、dropdown-menu submenu 最重（要接 `@angular/aria/menu` 巢狀，不能沿用現在的兩欄 hover）。
diff --git a/packages/ui/src/lib/components/table/todolist.md b/packages/ui/src/lib/components/table/todolist.md
index 3d82571..de3da43 100644
--- a/packages/ui/src/lib/components/table/todolist.md
+++ b/packages/ui/src/lib/components/table/todolist.md
@@ -1,5 +1,7 @@
 # Table 元件待辦清單
 
+全庫追蹤見根目錄 [TODOLIST.md](../../../../../../TODOLIST.md) P32。本檔只記 table 自己的細節。
+
 ## 已完成
 
 - `caption.directive.ts` — `TableCaptionDirective`(`caption[sanringCaption]`），投影進 `CdkTable` 內建的 `<ng-content select="caption">`

From 237b772db26435b934a90446ffd15933e3e9fffc Mon Sep 17 00:00:00 2001
From: jack755051 <jack755051@gmail.com>
Date: Tue, 22 Sep 2026 10:07:06 +0800
Subject: [PATCH 04/13] fix(docs): stabilize TOC active section on tall
 examples

Use a viewport-ratio reading line, mark the current item, and tighten
active styles so long demos stop leaving the previous section highlighted.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .../src/app/shell/toc/docs-toc.component.ts   | 48 +++++++++++++------
 1 file changed, 34 insertions(+), 14 deletions(-)

diff --git a/apps/docs/src/app/shell/toc/docs-toc.component.ts b/apps/docs/src/app/shell/toc/docs-toc.component.ts
index 3eba3ba..568b45f 100644
--- a/apps/docs/src/app/shell/toc/docs-toc.component.ts
+++ b/apps/docs/src/app/shell/toc/docs-toc.component.ts
@@ -4,6 +4,8 @@ import { DocsTocItem, DocsTocService } from './docs-toc.service';
 
 const SCROLL_OFFSET = 76;
 const ACTIVE_OFFSET = SCROLL_OFFSET + 24;
+/** Reading line as a fraction of the viewport. Tall example blocks otherwise keep the previous TOC item active. */
+const ACTIVE_VIEWPORT_RATIO = 0.32;
 
 @Component({
   selector: 'app-docs-toc',
@@ -19,7 +21,12 @@ const ACTIVE_OFFSET = SCROLL_OFFSET + 24;
           {{ i18n.t('toc.label') }}
         </p>
         @for (item of items(); track item.id) {
-          <a [class]="itemClass(item)" href="#" (click)="scrollTo(item.id, $event)">
+          <a
+            [class]="itemClass(item)"
+            [attr.aria-current]="activeId() === item.id ? 'location' : null"
+            [href]="'#' + item.id"
+            (click)="scrollTo(item.id, $event)"
+          >
             {{ item.label }}
           </a>
         }
@@ -54,6 +61,7 @@ export class DocsTocComponent {
     event.preventDefault();
     const el = document.getElementById(id);
     if (!el) return;
+    this.activeId.set(id);
     const marginTop = parseInt(getComputedStyle(el).marginTop) || 0;
     const top = el.getBoundingClientRect().top + window.scrollY - SCROLL_OFFSET - marginTop;
     window.scrollTo({ top, behavior: 'smooth' });
@@ -67,36 +75,48 @@ export class DocsTocComponent {
   protected itemClass(item: DocsTocItem) {
     const active = this.activeId() === item.id;
     const indentClasses: Record<2 | 3 | 4, string> = {
-      2: '',
-      3: 'pl-[18px]',
-      4: 'pl-9',
+      2: 'px-2.5',
+      3: 'pl-5 pr-2.5',
+      4: 'pl-8 pr-2.5',
     };
 
     return [
-      'my-3 block border-l border-transparent py-0.5 text-sm no-underline transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--docs-focus-ring)]',
+      'my-1 block rounded-[var(--sanring-radius)] border border-transparent py-1.5 text-sm no-underline transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--docs-focus-ring)]',
       active
-        ? 'border-[var(--docs-accent)] text-[var(--docs-fg)]'
-        : 'text-[var(--docs-muted)] hover:text-[var(--docs-fg)]',
+        ? 'border-[color-mix(in_srgb,var(--docs-accent)_34%,var(--docs-border))] bg-[var(--docs-active)] text-[var(--docs-fg)] shadow-sm'
+        : 'text-[var(--docs-muted)] hover:bg-[color-mix(in_srgb,var(--docs-elevated)_62%,transparent)] hover:text-[var(--docs-fg)]',
       indentClasses[item.level ?? 2],
-    ]
-      .filter(Boolean)
-      .join(' ');
+    ].join(' ');
+  }
+
+  private activationLine(): number {
+    return Math.max(ACTIVE_OFFSET, Math.round(window.innerHeight * ACTIVE_VIEWPORT_RATIO));
   }
 
   private updateActiveSection(): void {
     const items = this.toc.items();
-    let currentId = items[0]?.id ?? null;
+    if (items.length === 0) {
+      this.activeId.set(null);
+      return;
+    }
+
+    const line = this.activationLine();
+    let currentId = items[0].id;
 
     for (const item of items) {
       const el = document.getElementById(item.id);
       if (!el) continue;
-      if (el.getBoundingClientRect().top <= ACTIVE_OFFSET) {
+      if (el.getBoundingClientRect().top <= line) {
         currentId = item.id;
-      } else {
-        break;
       }
     }
 
+    const nearBottom =
+      window.innerHeight + window.scrollY >= document.documentElement.scrollHeight - 8;
+    if (nearBottom) {
+      currentId = items[items.length - 1].id;
+    }
+
     this.activeId.set(currentId);
   }
 }

From 0a435e872875fb452ea50112499090359cc126e9 Mon Sep 17 00:00:00 2001
From: jack755051 <jack755051@gmail.com>
Date: Tue, 22 Sep 2026 10:07:12 +0800
Subject: [PATCH 05/13] feat(combobox): add wrap control with single-line chip
 overflow

Let chip-input/chips stay on one row and ellipsize overflow, keep the
selected/total count inside the field, and mirror the change in registry.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 apps/docs/src/app/i18n/locales/en/common.ts   |   6 +
 .../i18n/locales/en/components/combobox.ts    |   7 ++
 apps/docs/src/app/i18n/locales/en/index.ts    |   1 +
 apps/docs/src/app/i18n/locales/zh/common.ts   |   6 +
 .../i18n/locales/zh/components/combobox.ts    |  10 +-
 apps/docs/src/app/i18n/locales/zh/index.ts    |   1 +
 apps/docs/src/app/i18n/translations.ts        |   2 +
 .../combobox/combobox-page.component.ts       | 103 +++++++++++++++---
 .../components/combobox/combobox.docs.ts      |  70 ++++++++++--
 .../combobox/combobox-chip-input.component.ts |  35 +++++-
 .../combobox/combobox-chip.component.ts       |  27 ++++-
 .../combobox/combobox-chips.component.ts      |  86 ++++++++++++++-
 .../combobox/combobox-input.component.ts      |   8 +-
 .../combobox/combobox.component.spec.ts       |  76 +++++++++++++
 .../components/combobox/combobox.component.ts |   2 +-
 .../combobox/combobox-chip-input.component.ts |  35 +++++-
 .../combobox/combobox-chip.component.ts       |  27 ++++-
 .../combobox/combobox-chips.component.ts      |  86 ++++++++++++++-
 .../combobox/combobox-input.component.ts      |   8 +-
 .../components/combobox/combobox.component.ts |   2 +-
 20 files changed, 548 insertions(+), 50 deletions(-)

diff --git a/apps/docs/src/app/i18n/locales/en/common.ts b/apps/docs/src/app/i18n/locales/en/common.ts
index ef26662..acbc00a 100644
--- a/apps/docs/src/app/i18n/locales/en/common.ts
+++ b/apps/docs/src/app/i18n/locales/en/common.ts
@@ -167,4 +167,10 @@ export const commonTranslations = {
   'status.maintenance.title': 'Under maintenance',
   'status.maintenance.description':
     'This component is temporarily under maintenance and hidden from production navigation. It remains reachable directly while we work on it.',
+  'combobox.demo.multipleSingleLine': 'Multiple, single line',
+  'combobox.demo.multipleMultiLine': 'Multiple, multi-line',
+  'combobox.api.chipInputWrap.description':
+    'When false, chips and the search input stay on one row instead of wrapping.',
+  'combobox.api.chipsWrap.description':
+    'When false, selected chips stay on one line and overflow with an ellipsis.',
 } as const;
diff --git a/apps/docs/src/app/i18n/locales/en/components/combobox.ts b/apps/docs/src/app/i18n/locales/en/components/combobox.ts
index 7518ace..9b86cd7 100644
--- a/apps/docs/src/app/i18n/locales/en/components/combobox.ts
+++ b/apps/docs/src/app/i18n/locales/en/components/combobox.ts
@@ -1,3 +1,4 @@
+/** Combobox docs copy. */
 export const comboboxTranslations = {
   'combobox.description': 'Autocomplete input with a list of suggestions.',
   'combobox.examples.basic.description':
@@ -36,6 +37,12 @@ export const comboboxTranslations = {
     'Selected value controlled by the root. Use a string for single select or string array for multiple select.',
   'combobox.api.multiple.description':
     'Allows selecting more than one item and pairing the field with chips.',
+  'combobox.demo.multipleSingleLine': 'Multiple, single line',
+  'combobox.demo.multipleMultiLine': 'Multiple, multi-line',
+  'combobox.api.chipInputWrap.description':
+    'When false, chips and the search input stay on one row instead of wrapping.',
+  'combobox.api.chipsWrap.description':
+    'When false, selected chips stay on one line and overflow with an ellipsis.',
   'combobox.api.disabled.description':
     'Disables the combobox input and prevents selection changes.',
   'combobox.api.inputId.description':
diff --git a/apps/docs/src/app/i18n/locales/en/index.ts b/apps/docs/src/app/i18n/locales/en/index.ts
index 320d663..7b68f0c 100644
--- a/apps/docs/src/app/i18n/locales/en/index.ts
+++ b/apps/docs/src/app/i18n/locales/en/index.ts
@@ -2,6 +2,7 @@ import { commonTranslations } from './common';
 import { componentTranslations } from './components';
 import { pageTranslations } from './pages';
 
+/** Locale catalog for English docs copy. */
 export const en = {
   ...commonTranslations,
   ...pageTranslations,
diff --git a/apps/docs/src/app/i18n/locales/zh/common.ts b/apps/docs/src/app/i18n/locales/zh/common.ts
index 580fff7..9ba6a0a 100644
--- a/apps/docs/src/app/i18n/locales/zh/common.ts
+++ b/apps/docs/src/app/i18n/locales/zh/common.ts
@@ -162,4 +162,10 @@ export const commonTranslations = {
   'status.maintenance.title': '維護中',
   'status.maintenance.description':
     '此元件目前維護中，已從正式環境的導覽中暫時移除；維護期間仍可透過直接連結訪問。',
+  'combobox.demo.multipleSingleLine': '多選、單行',
+  'combobox.demo.multipleMultiLine': '多選、多行',
+  'combobox.api.chipInputWrap.description':
+    '設為 false 時，chips 與搜尋框維持單行，不再換行。',
+  'combobox.api.chipsWrap.description':
+    '設為 false 時，已選 chips 維持單行，超出輸入框寬度時以刪節號收斂。',
 } as const;
diff --git a/apps/docs/src/app/i18n/locales/zh/components/combobox.ts b/apps/docs/src/app/i18n/locales/zh/components/combobox.ts
index c95fb1e..fb0b259 100644
--- a/apps/docs/src/app/i18n/locales/zh/components/combobox.ts
+++ b/apps/docs/src/app/i18n/locales/zh/components/combobox.ts
@@ -1,3 +1,4 @@
+/** Combobox docs copy. */
 export const comboboxTranslations = {
   'combobox.description': '具備建議清單的自動完成輸入元件。',
   'combobox.examples.basic.description':
@@ -33,7 +34,14 @@ export const comboboxTranslations = {
   'combobox.api.description': 'combobox primitives 支援的 inputs 與 models。',
   'combobox.api.value.description':
     '由 root 控制的選取值。單選使用 string，多選使用 string array。',
-  'combobox.api.multiple.description': '允許選取多個項目，並可搭配 chips 呈現。',
+  'combobox.demo.multipleSingleLine': '多選、單行',
+  'combobox.demo.multipleMultiLine': '多選、多行',
+  'combobox.api.chipInputWrap.description':
+    '設為 false 時，chips 與搜尋框維持單行，不再換行。',
+  'combobox.api.chipsWrap.description':
+    '設為 false 時，已選 chips 維持單行，超出輸入框寬度時以刪節號收斂。',
+  'combobox.api.multiple.description':
+    '允許選取多個項目，並可搭配 chips 呈現。',
   'combobox.api.disabled.description': '停用 combobox input，並阻止選取狀態變更。',
   'combobox.api.inputId.description':
     'input 或自訂 trigger 與其 label 共用的 ID；未提供時自動產生，也可覆寫以串接應用程式內的關聯。',
diff --git a/apps/docs/src/app/i18n/locales/zh/index.ts b/apps/docs/src/app/i18n/locales/zh/index.ts
index 77162e0..f36f8af 100644
--- a/apps/docs/src/app/i18n/locales/zh/index.ts
+++ b/apps/docs/src/app/i18n/locales/zh/index.ts
@@ -2,6 +2,7 @@ import { commonTranslations } from './common';
 import { componentTranslations } from './components';
 import { pageTranslations } from './pages';
 
+/** Locale catalog for Traditional Chinese docs copy. */
 export const zh = {
   ...commonTranslations,
   ...pageTranslations,
diff --git a/apps/docs/src/app/i18n/translations.ts b/apps/docs/src/app/i18n/translations.ts
index 5bb67ad..4abf1dc 100644
--- a/apps/docs/src/app/i18n/translations.ts
+++ b/apps/docs/src/app/i18n/translations.ts
@@ -1,6 +1,8 @@
 import { en } from './locales/en/index';
 import { zh } from './locales/zh/index';
 
+/** Docs locale catalogs. TranslationKey is keyof typeof en. */
+
 export const supportedLocales = ['en', 'zh'] as const;
 
 export type Locale = (typeof supportedLocales)[number];
diff --git a/apps/docs/src/app/pages/components/combobox/combobox-page.component.ts b/apps/docs/src/app/pages/components/combobox/combobox-page.component.ts
index a5eae60..3279ed9 100644
--- a/apps/docs/src/app/pages/components/combobox/combobox-page.component.ts
+++ b/apps/docs/src/app/pages/components/combobox/combobox-page.component.ts
@@ -109,21 +109,77 @@ import { comboboxPage, comboboxPageExamples } from './combobox.docs';
 
       <app-component-page-section [section]="section('example')">
         <div class="grid gap-2">
-          <app-component-page-section [section]="section('example-multiple')">
-            <app-component-page-code-previewer [code]="examples.multiple" language="angular-html">
+          <app-component-page-section [section]="section('example-multiple-single-line')">
+            <app-component-page-code-previewer
+              [code]="examples.multipleSingleLine"
+              language="angular-html"
+            >
               <div previewer class="flex w-full min-h-[240px] items-start justify-center pt-8">
-                <div class="grid w-[min(320px,100%)] gap-2">
-                  <sanring-combobox [multiple]="true" [(value)]="selectedFrameworks">
+                <div class="grid w-full min-w-0 max-w-[360px] gap-2">
+                  <sanring-combobox [multiple]="true" [(value)]="nowrapFrameworks">
+                    <sanring-combobox-label>{{
+                      i18n.t('combobox.demo.frameworks')
+                    }}</sanring-combobox-label>
+                    <sanring-combobox-chip-input [wrap]="false">
+                      <sanring-combobox-chips [wrap]="false">
+                        @for (value of nowrapFrameworkValues(); track value) {
+                          <sanring-combobox-chip [value]="value">{{
+                            labelFor(value)
+                          }}</sanring-combobox-chip>
+                        }
+                      </sanring-combobox-chips>
+                      <sanring-combobox-input />
+                      <span
+                        class="ml-auto shrink-0 self-center text-xs tabular-nums text-[var(--sanring-muted)]"
+                        aria-live="polite"
+                      >
+                        {{ nowrapFrameworkValues().length }}/{{ frameworks.length }}
+                      </span>
+                    </sanring-combobox-chip-input>
+                    <sanring-combobox-content>
+                      <sanring-combobox-empty>{{
+                        i18n.t('combobox.demo.empty')
+                      }}</sanring-combobox-empty>
+                      <sanring-combobox-list>
+                        @for (item of frameworks; track item.value) {
+                          <sanring-combobox-item [value]="item.value" [label]="item.label">
+                            {{ item.label }}
+                          </sanring-combobox-item>
+                        }
+                      </sanring-combobox-list>
+                    </sanring-combobox-content>
+                  </sanring-combobox>
+                </div>
+              </div>
+            </app-component-page-code-previewer>
+          </app-component-page-section>
+
+          <app-component-page-section [section]="section('example-multiple-multi-line')">
+            <app-component-page-code-previewer
+              [code]="examples.multipleMultiLine"
+              language="angular-html"
+            >
+              <div previewer class="flex w-full min-h-[240px] items-start justify-center pt-8">
+                <div class="grid w-full min-w-0 max-w-[280px] gap-2">
+                  <sanring-combobox [multiple]="true" [(value)]="wrapFrameworks">
                     <sanring-combobox-label>{{
                       i18n.t('combobox.demo.frameworks')
                     }}</sanring-combobox-label>
                     <sanring-combobox-chip-input>
-                      @for (value of selectedFrameworkValues(); track value) {
-                        <sanring-combobox-chip [value]="value">{{
-                          labelFor(value)
-                        }}</sanring-combobox-chip>
-                      }
+                      <sanring-combobox-chips>
+                        @for (value of wrapFrameworkValues(); track value) {
+                          <sanring-combobox-chip [value]="value">{{
+                            labelFor(value)
+                          }}</sanring-combobox-chip>
+                        }
+                      </sanring-combobox-chips>
                       <sanring-combobox-input />
+                      <span
+                        class="ml-auto shrink-0 self-center text-xs tabular-nums text-[var(--sanring-muted)]"
+                        aria-live="polite"
+                      >
+                        {{ wrapFrameworkValues().length }}/{{ frameworks.length }}
+                      </span>
                     </sanring-combobox-chip-input>
                     <sanring-combobox-content>
                       <sanring-combobox-empty>{{
@@ -138,12 +194,6 @@ import { comboboxPage, comboboxPageExamples } from './combobox.docs';
                       </sanring-combobox-list>
                     </sanring-combobox-content>
                   </sanring-combobox>
-                  <p
-                    class="m-0 text-end text-[0.8rem] tabular-nums text-[var(--docs-muted)]"
-                    aria-live="polite"
-                  >
-                    {{ selectedFrameworkValues().length }}/{{ frameworks.length }}
-                  </p>
                 </div>
               </div>
             </app-component-page-code-previewer>
@@ -314,7 +364,20 @@ export class ComboboxPageComponent {
   protected readonly i18n = inject(I18nService);
 
   protected framework: string | string[] | null = 'angular';
-  protected selectedFrameworks: string | string[] | null = ['angular', 'astro'];
+  protected wrapFrameworks: string | string[] | null = [
+    'angular',
+    'react',
+    'sveltekit',
+    'nuxt',
+    'astro',
+  ];
+  protected nowrapFrameworks: string | string[] | null = [
+    'angular',
+    'react',
+    'sveltekit',
+    'nuxt',
+    'astro',
+  ];
   protected library: string | string[] | null = 'angular';
   protected country: string | string[] | null = null;
   protected clearDemoValue: string | string[] | null = 'react';
@@ -346,8 +409,12 @@ export class ComboboxPageComponent {
     return getComponentPageSection(this.page, id);
   }
 
-  protected selectedFrameworkValues(): string[] {
-    return Array.isArray(this.selectedFrameworks) ? this.selectedFrameworks : [];
+  protected wrapFrameworkValues(): string[] {
+    return Array.isArray(this.wrapFrameworks) ? this.wrapFrameworks : [];
+  }
+
+  protected nowrapFrameworkValues(): string[] {
+    return Array.isArray(this.nowrapFrameworks) ? this.nowrapFrameworks : [];
   }
 
   protected labelFor(
diff --git a/apps/docs/src/app/pages/components/combobox/combobox.docs.ts b/apps/docs/src/app/pages/components/combobox/combobox.docs.ts
index 492b0ed..80ef050 100644
--- a/apps/docs/src/app/pages/components/combobox/combobox.docs.ts
+++ b/apps/docs/src/app/pages/components/combobox/combobox.docs.ts
@@ -46,7 +46,8 @@ export const comboboxPage = {
       titleKey: 'toc.examples',
       level: 2,
       children: [
-        { id: 'example-multiple', titleKey: 'toc.multiple', level: 3 },
+        { id: 'example-multiple-single-line', titleKey: 'combobox.demo.multipleSingleLine', level: 3 },
+        { id: 'example-multiple-multi-line', titleKey: 'combobox.demo.multipleMultiLine', level: 3 },
         { id: 'example-groups', titleKey: 'combobox.demo.groups', level: 3 },
         { id: 'example-popup', titleKey: 'combobox.demo.popup', level: 3 },
         { id: 'example-clear', titleKey: 'combobox.demo.clearButtonTitle', level: 3 },
@@ -151,6 +152,18 @@ export const comboboxPage = {
       defaultValue: '—',
       descriptionKey: 'combobox.api.trigger.description',
     },
+    {
+      property: 'ComboboxChipInputComponent.wrap',
+      type: 'boolean',
+      defaultValue: 'true',
+      descriptionKey: 'combobox.api.chipInputWrap.description',
+    },
+    {
+      property: 'ComboboxChipsComponent.wrap',
+      type: 'boolean',
+      defaultValue: 'true',
+      descriptionKey: 'combobox.api.chipsWrap.description',
+    },
     {
       property: 'class',
       type: 'string',
@@ -236,20 +249,58 @@ export class ExampleComponent {}`,
 
 multiple mode — chips and the input share ONE bordered box
 └── sanring-combobox-chip-input
-    ├── sanring-combobox-chip (one per selected value)
-    └── sanring-combobox-input (renders chrome-less when nested here)
+    ├── sanring-combobox-chips
+    │   └── sanring-combobox-chip (one per selected value)
+    ├── sanring-combobox-input (renders chrome-less when nested here)
+    └── count (optional, sits on the right of the field)
 
 popup mode — swap the trigger for the input once open
 ├── button[sanringComboboxTrigger]   // shown while closed
 └── sanring-combobox-input            // shown while open, via #combo="sanringCombobox"`,
 
-  multiple: `<sanring-combobox [multiple]="true" [(value)]="selectedFrameworks">
+  multipleSingleLine: `<sanring-combobox [multiple]="true" [(value)]="selectedFrameworks">
+  <sanring-combobox-label>Frameworks</sanring-combobox-label>
+  <sanring-combobox-chip-input [wrap]="false">
+    <sanring-combobox-chips [wrap]="false">
+      @for (value of selectedFrameworks; track value) {
+        <sanring-combobox-chip [value]="value">{{ labelFor(value) }}</sanring-combobox-chip>
+      }
+    </sanring-combobox-chips>
+    <sanring-combobox-input />
+    <span
+      class="ml-auto shrink-0 self-center text-xs tabular-nums text-[var(--sanring-muted)]"
+      aria-live="polite"
+    >
+      {{ selectedFrameworks.length }}/{{ frameworks.length }}
+    </span>
+  </sanring-combobox-chip-input>
+  <sanring-combobox-content>
+    <sanring-combobox-empty>No frameworks found.</sanring-combobox-empty>
+    <sanring-combobox-list>
+      @for (item of frameworks; track item.value) {
+        <sanring-combobox-item [value]="item.value" [label]="item.label">
+          {{ item.label }}
+        </sanring-combobox-item>
+      }
+    </sanring-combobox-list>
+  </sanring-combobox-content>
+</sanring-combobox>`,
+
+  multipleMultiLine: `<sanring-combobox [multiple]="true" [(value)]="selectedFrameworks">
   <sanring-combobox-label>Frameworks</sanring-combobox-label>
   <sanring-combobox-chip-input>
-    @for (value of selectedFrameworks; track value) {
-      <sanring-combobox-chip [value]="value">{{ labelFor(value) }}</sanring-combobox-chip>
-    }
+    <sanring-combobox-chips>
+      @for (value of selectedFrameworks; track value) {
+        <sanring-combobox-chip [value]="value">{{ labelFor(value) }}</sanring-combobox-chip>
+      }
+    </sanring-combobox-chips>
     <sanring-combobox-input />
+    <span
+      class="ml-auto shrink-0 self-center text-xs tabular-nums text-[var(--sanring-muted)]"
+      aria-live="polite"
+    >
+      {{ selectedFrameworks.length }}/{{ frameworks.length }}
+    </span>
   </sanring-combobox-chip-input>
   <sanring-combobox-content>
     <sanring-combobox-empty>No frameworks found.</sanring-combobox-empty>
@@ -261,10 +312,7 @@ popup mode — swap the trigger for the input once open
       }
     </sanring-combobox-list>
   </sanring-combobox-content>
-</sanring-combobox>
-<p class="text-end text-[0.8rem] tabular-nums text-[var(--sanring-muted)]">
-  {{ selectedFrameworks.length }}/{{ frameworks.length }}
-</p>`,
+</sanring-combobox>`,
 
   groups: `<sanring-combobox [(value)]="library">
   <sanring-combobox-input placeholder="Search libraries" />
diff --git a/packages/ui/src/lib/components/combobox/combobox-chip-input.component.ts b/packages/ui/src/lib/components/combobox/combobox-chip-input.component.ts
index 983611d..182dd24 100644
--- a/packages/ui/src/lib/components/combobox/combobox-chip-input.component.ts
+++ b/packages/ui/src/lib/components/combobox/combobox-chip-input.component.ts
@@ -1,10 +1,12 @@
 import {
+  booleanAttribute,
   ChangeDetectionStrategy,
   Component,
   computed,
   ElementRef,
   inject,
   input,
+  signal,
 } from '@angular/core';
 import { ComboboxComponent } from './combobox.component';
 import { cn } from '../../utils';
@@ -22,15 +24,44 @@ import { cn } from '../../utils';
 })
 export class ComboboxChipInputComponent {
   readonly class = input<string | undefined>();
+  /** When false, selected chips stay on one row instead of wrapping. */
+  readonly wrap = input(true, { transform: booleanAttribute });
 
   // 🪄 依賴注入
   protected combobox = inject(ComboboxComponent);
-  private elementRef = inject(ElementRef);
+  private elementRef = inject<ElementRef<HTMLElement>>(ElementRef);
+  /** Single-line overflow: collapse the search field so chips + count stay flush. */
+  readonly chipsOverflowing = signal(false);
+
+  setChipsOverflowing(next: boolean): void {
+    if (this.chipsOverflowing() !== next) this.chipsOverflowing.set(next);
+  }
+
+  /**
+   * Width available for the chips row. Search field is ignored — it only
+   * consumes leftover space when chips already fit next to the count.
+   */
+  chipLaneWidth(extraReservePx = 0): number {
+    const el = this.elementRef.nativeElement;
+    const style = getComputedStyle(el);
+    const paddingX = parseFloat(style.paddingLeft) + parseFloat(style.paddingRight);
+    const gap = parseFloat(style.gap) || 0;
+    let reserved = extraReservePx;
+    let extras = 0;
+    for (const child of el.children) {
+      if (child.tagName === 'SANRING-COMBOBOX-CHIPS') continue;
+      if (child.tagName === 'SANRING-COMBOBOX-INPUT') continue;
+      reserved += (child as HTMLElement).offsetWidth;
+      extras += 1;
+    }
+    return el.clientWidth - paddingX - reserved - gap * extras;
+  }
 
   protected readonly wrapperClass = computed(() =>
     cn(
       // 🌟 排版核心：讓裡面的 Chips 和 Input 能夠在同一行水平排列、自動換行
-      'flex min-h-10 w-full flex-wrap items-center gap-1 rounded-[var(--sanring-radius)] border border-[var(--sanring-border-strong)] bg-[var(--sanring-surface)] px-3 py-1 text-sm text-[var(--sanring-foreground)]',
+      'relative flex min-h-10 min-w-0 w-full items-center gap-1 rounded-[var(--sanring-radius)] border border-[var(--sanring-border-strong)] bg-[var(--sanring-surface)] px-3 py-1 text-sm text-[var(--sanring-foreground)]',
+      this.wrap() ? 'flex-wrap' : 'flex-nowrap overflow-hidden',
       // 當大腦被禁用時的樣式
       this.combobox.isDisabled() ? 'cursor-not-allowed opacity-50' : 'cursor-text',
       // 聚焦時的外框亮起效果（模擬真實 input 的 focus-within 狀態）
diff --git a/packages/ui/src/lib/components/combobox/combobox-chip.component.ts b/packages/ui/src/lib/components/combobox/combobox-chip.component.ts
index b02d0af..b16708d 100644
--- a/packages/ui/src/lib/components/combobox/combobox-chip.component.ts
+++ b/packages/ui/src/lib/components/combobox/combobox-chip.component.ts
@@ -1,6 +1,14 @@
-import { ChangeDetectionStrategy, Component, computed, inject, input } from '@angular/core';
+import {
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  ElementRef,
+  inject,
+  input,
+} from '@angular/core';
 import { LucideX } from '@lucide/angular';
 import { ComboboxComponent } from './combobox.component';
+import { ComboboxChipsComponent } from './combobox-chips.component';
 import { cn } from '../../utils';
 
 @Component({
@@ -39,6 +47,20 @@ export class ComboboxChipComponent {
 
   // 🪄 依賴注入：連線到大腦
   protected combobox = inject(ComboboxComponent);
+  private readonly chipsParent = inject(ComboboxChipsComponent, { optional: true });
+  private readonly elementRef = inject<ElementRef<HTMLElement>>(ElementRef);
+
+  protected readonly overflowHidden = computed(() => {
+    const parent = this.chipsParent;
+    if (!parent) return false;
+    const from = parent.hiddenFrom();
+    if (from === null) return false;
+    const node = this.elementRef.nativeElement;
+    const chips = node.parentElement
+      ? [...node.parentElement.children].filter((child) => child.tagName === 'SANRING-COMBOBOX-CHIP')
+      : [];
+    return chips.indexOf(node) >= from;
+  });
 
   // 🔍 禁用狀態判斷：如果大腦被禁用了，或者這顆 Chip 自己被禁用了，就鎖死按鈕
   protected readonly isDisabled = computed(() => this.disabled() || this.combobox.isDisabled());
@@ -46,11 +68,12 @@ export class ComboboxChipComponent {
   // 🎨 視覺排版：經典的 Badge/Chip 樣式
   protected readonly chipClass = computed(() =>
     cn(
-      'inline-flex items-center justify-between rounded-[var(--sanring-radius-xs)] px-1.5 py-0.5 text-xs font-semibold transition-colors',
+      'inline-flex shrink-0 items-center justify-between rounded-[var(--sanring-radius-xs)] px-1.5 py-0.5 text-xs font-semibold transition-colors',
       // 預設樣式：次要背景色
       'border border-[var(--sanring-border)] bg-[var(--sanring-surface-strong)] text-[var(--sanring-foreground)]',
       // 禁用狀態的透明度
       this.isDisabled() ? 'opacity-50 pointer-events-none' : 'hover:bg-[var(--sanring-active)]',
+      this.overflowHidden() && 'pointer-events-none invisible absolute',
       this.class(),
     ),
   );
diff --git a/packages/ui/src/lib/components/combobox/combobox-chips.component.ts b/packages/ui/src/lib/components/combobox/combobox-chips.component.ts
index aabae5b..73eb1d6 100644
--- a/packages/ui/src/lib/components/combobox/combobox-chips.component.ts
+++ b/packages/ui/src/lib/components/combobox/combobox-chips.component.ts
@@ -1,20 +1,98 @@
-import { ChangeDetectionStrategy, Component, computed, input } from '@angular/core';
+import {
+  afterEveryRender,
+  booleanAttribute,
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  ElementRef,
+  inject,
+  input,
+  signal,
+} from '@angular/core';
+import { ComboboxChipInputComponent } from './combobox-chip-input.component';
 import { cn } from '../../utils';
 
 @Component({
   changeDetection: ChangeDetectionStrategy.OnPush,
   selector: 'sanring-combobox-chips',
   standalone: true,
-  template: `<ng-content></ng-content>`,
+  template: `
+    <ng-content></ng-content>
+    @if (overflowing()) {
+      <span
+        data-overflow-ellipsis
+        class="shrink-0 select-none text-[var(--sanring-muted)]"
+        aria-hidden="true"
+      >…</span>
+    }
+  `,
   host: {
     '[class]': 'chipsClass()',
   },
 })
 export class ComboboxChipsComponent {
-  // 允許外部微調樣式
   readonly class = input<string | undefined>();
+  /** When false, chips stay on one line and overflow with an ellipsis. */
+  readonly wrap = input(true, { transform: booleanAttribute });
+
+  private readonly elementRef = inject<ElementRef<HTMLElement>>(ElementRef);
+  private readonly chipInput = inject(ComboboxChipInputComponent, { optional: true });
+  protected readonly overflowing = signal(false);
+  /** First chip index that no longer fits on a single line. */
+  readonly hiddenFrom = signal<number | null>(null);
+
+  constructor() {
+    afterEveryRender(() => {
+      if (this.wrap()) {
+        if (this.overflowing()) this.overflowing.set(false);
+        if (this.hiddenFrom() !== null) this.hiddenFrom.set(null);
+        this.chipInput?.setChipsOverflowing(false);
+        return;
+      }
+      const node = this.elementRef.nativeElement;
+      const gap = parseFloat(getComputedStyle(node).gap) || 0;
+      const chips = [...node.children].filter(
+        (child) => child.tagName === 'SANRING-COMBOBOX-CHIP',
+      ) as HTMLElement[];
+      const widths = chips.map((chip) => chip.offsetWidth);
+      const total = (count: number) => {
+        if (count <= 0) return 0;
+        return (
+          widths.slice(0, count).reduce((sum, width) => sum + width, 0) +
+          gap * Math.max(0, count - 1)
+        );
+      };
+      const lane = this.chipInput ? this.chipInput.chipLaneWidth() : node.clientWidth;
+      const allFit = total(chips.length) <= lane;
+      if (allFit) {
+        if (this.overflowing()) this.overflowing.set(false);
+        if (this.hiddenFrom() !== null) this.hiddenFrom.set(null);
+        this.chipInput?.setChipsOverflowing(false);
+        return;
+      }
+
+      const ellipsis =
+        node.querySelector<HTMLElement>('[data-overflow-ellipsis]')?.offsetWidth ?? 14;
+      let visible = chips.length;
+      while (
+        visible > 1 &&
+        total(visible) + (visible > 0 ? gap : 0) + ellipsis > lane
+      ) {
+        visible -= 1;
+      }
+      if (!this.overflowing()) this.overflowing.set(true);
+      this.chipInput?.setChipsOverflowing(true);
+      const from = visible < chips.length ? visible : chips.length;
+      if (this.hiddenFrom() !== from) this.hiddenFrom.set(from);
+    });
+  }
 
   protected readonly chipsClass = computed(() =>
-    cn('flex flex-wrap items-center gap-1', this.class()),
+    cn(
+      this.wrap()
+        ? 'contents'
+        : 'flex min-w-0 shrink-0 items-center gap-1 flex-nowrap',
+      this.class(),
+    ),
   );
 }
diff --git a/packages/ui/src/lib/components/combobox/combobox-input.component.ts b/packages/ui/src/lib/components/combobox/combobox-input.component.ts
index 937db89..f93be8c 100644
--- a/packages/ui/src/lib/components/combobox/combobox-input.component.ts
+++ b/packages/ui/src/lib/components/combobox/combobox-input.component.ts
@@ -32,6 +32,7 @@ import { FIELD_SIZE_CLASS } from '../component-styles';
       (focus)="combobox.onFocus()"
       (blur)="combobox.onBlur()"
       autocomplete="off"
+      size="1"
       role="combobox"
       [attr.aria-expanded]="combobox.isOpen()"
       [attr.aria-controls]="combobox.listId()"
@@ -70,8 +71,13 @@ export class ComboboxInputComponent {
   protected readonly inputClass = computed(() => {
     if (this.chipInputParent) {
       return cn(
-        'min-w-[60px] flex-1 border-0 bg-transparent p-0 text-sm text-[var(--sanring-foreground)] outline-none',
+        'border-0 bg-transparent p-0 text-sm text-[var(--sanring-foreground)] outline-none',
         'placeholder:text-[var(--sanring-muted)] disabled:cursor-not-allowed disabled:opacity-50',
+        this.chipInputParent.wrap()
+          ? 'min-w-[4ch] w-auto'
+          : this.chipInputParent.chipsOverflowing() && !this.combobox.inputValue()
+            ? 'w-0 min-w-0 flex-none overflow-hidden'
+            : 'min-w-0 flex-1',
         this.class(),
       );
     }
diff --git a/packages/ui/src/lib/components/combobox/combobox.component.spec.ts b/packages/ui/src/lib/components/combobox/combobox.component.spec.ts
index 5eb7be2..265a046 100644
--- a/packages/ui/src/lib/components/combobox/combobox.component.spec.ts
+++ b/packages/ui/src/lib/components/combobox/combobox.component.spec.ts
@@ -4,6 +4,7 @@ import { ComponentFixture, TestBed } from '@angular/core/testing';
 import { expectNoA11yViolations } from '../../../testing/axe-a11y';
 import { ComboboxChipComponent } from './combobox-chip.component';
 import { ComboboxChipInputComponent } from './combobox-chip-input.component';
+import { ComboboxChipsComponent } from './combobox-chips.component';
 import { ComboboxContentComponent } from './combobox-content.component';
 import { ComboboxInputComponent } from './combobox-input.component';
 import { ComboboxItemComponent } from './combobox-item.component';
@@ -372,3 +373,78 @@ describe('ComboboxComponent', () => {
     });
   });
 });
+
+@Component({
+  imports: [
+    ComboboxComponent,
+    ComboboxChipComponent,
+    ComboboxChipInputComponent,
+    ComboboxChipsComponent,
+    ComboboxInputComponent,
+  ],
+  template: `
+    <sanring-combobox multiple>
+      <sanring-combobox-chip-input [wrap]="false">
+        <sanring-combobox-chips [wrap]="false">
+          <sanring-combobox-chip value="angular">Angular</sanring-combobox-chip>
+        </sanring-combobox-chips>
+        <sanring-combobox-input />
+      </sanring-combobox-chip-input>
+    </sanring-combobox>
+  `,
+})
+class NowrapComboboxHost {}
+
+@Component({
+  imports: [
+    ComboboxComponent,
+    ComboboxChipComponent,
+    ComboboxChipInputComponent,
+    ComboboxChipsComponent,
+    ComboboxInputComponent,
+  ],
+  template: `
+    <sanring-combobox multiple>
+      <sanring-combobox-chip-input>
+        <sanring-combobox-chips>
+          <sanring-combobox-chip value="angular">Angular</sanring-combobox-chip>
+        </sanring-combobox-chips>
+        <sanring-combobox-input />
+      </sanring-combobox-chip-input>
+    </sanring-combobox>
+  `,
+})
+class WrapComboboxHost {}
+
+describe('ComboboxChipsComponent wrap', () => {
+  it('keeps chips on one line when wrap is false', async () => {
+    await TestBed.configureTestingModule({ imports: [NowrapComboboxHost] }).compileComponents();
+    const fixture = TestBed.createComponent(NowrapComboboxHost);
+    fixture.detectChanges();
+
+    const chipInput = fixture.nativeElement.querySelector(
+      'sanring-combobox-chip-input',
+    ) as HTMLElement;
+    const chips = fixture.nativeElement.querySelector('sanring-combobox-chips') as HTMLElement;
+    const input = fixture.nativeElement.querySelector('input') as HTMLInputElement;
+    expect(chipInput.classList.contains('flex-nowrap')).toBe(true);
+    expect(chips.classList.contains('flex-nowrap')).toBe(true);
+    expect(chips.classList.contains('shrink-0')).toBe(true);
+    expect(input.classList.contains('w-auto')).toBe(false);
+  });
+
+  it('lets chips wrap without stretching the search field onto its own row', async () => {
+    await TestBed.configureTestingModule({ imports: [WrapComboboxHost] }).compileComponents();
+    const fixture = TestBed.createComponent(WrapComboboxHost);
+    fixture.detectChanges();
+
+    const chipInput = fixture.nativeElement.querySelector(
+      'sanring-combobox-chip-input',
+    ) as HTMLElement;
+    const chips = fixture.nativeElement.querySelector('sanring-combobox-chips') as HTMLElement;
+    const input = fixture.nativeElement.querySelector('input') as HTMLInputElement;
+    expect(chipInput.classList.contains('flex-wrap')).toBe(true);
+    expect(chips.classList.contains('contents')).toBe(true);
+    expect(input.classList.contains('flex-1')).toBe(false);
+  });
+});
diff --git a/packages/ui/src/lib/components/combobox/combobox.component.ts b/packages/ui/src/lib/components/combobox/combobox.component.ts
index 124b014..cda1f65 100644
--- a/packages/ui/src/lib/components/combobox/combobox.component.ts
+++ b/packages/ui/src/lib/components/combobox/combobox.component.ts
@@ -92,7 +92,7 @@ export class ComboboxComponent extends SanringCvaBase<ComboboxValue> {
   readonly isDisabled = computed(() => this.disabled() || this.disabledState());
 
   protected readonly hostClass = computed(() =>
-    cn('relative block w-full', this.isDisabled() && 'opacity-50 cursor-not-allowed', this.class()),
+    cn('relative block w-full min-w-0', this.isDisabled() && 'opacity-50 cursor-not-allowed', this.class()),
   );
 
   readonly computedAriaDescribedBy = this.makeComputedAriaDescribedBy();
diff --git a/registry/components/combobox/combobox-chip-input.component.ts b/registry/components/combobox/combobox-chip-input.component.ts
index c5de9d0..d2da1fa 100644
--- a/registry/components/combobox/combobox-chip-input.component.ts
+++ b/registry/components/combobox/combobox-chip-input.component.ts
@@ -1,10 +1,12 @@
 import {
+  booleanAttribute,
   ChangeDetectionStrategy,
   Component,
   computed,
   ElementRef,
   inject,
   input,
+  signal,
 } from '@angular/core';
 import { ComboboxComponent } from './combobox.component';
 import { cn } from '../shared/utils';
@@ -22,15 +24,44 @@ import { cn } from '../shared/utils';
 })
 export class ComboboxChipInputComponent {
   readonly class = input<string | undefined>();
+  /** When false, selected chips stay on one row instead of wrapping. */
+  readonly wrap = input(true, { transform: booleanAttribute });
 
   // 🪄 依賴注入
   protected combobox = inject(ComboboxComponent);
-  private elementRef = inject(ElementRef);
+  private elementRef = inject<ElementRef<HTMLElement>>(ElementRef);
+  /** Single-line overflow: collapse the search field so chips + count stay flush. */
+  readonly chipsOverflowing = signal(false);
+
+  setChipsOverflowing(next: boolean): void {
+    if (this.chipsOverflowing() !== next) this.chipsOverflowing.set(next);
+  }
+
+  /**
+   * Width available for the chips row. Search field is ignored — it only
+   * consumes leftover space when chips already fit next to the count.
+   */
+  chipLaneWidth(extraReservePx = 0): number {
+    const el = this.elementRef.nativeElement;
+    const style = getComputedStyle(el);
+    const paddingX = parseFloat(style.paddingLeft) + parseFloat(style.paddingRight);
+    const gap = parseFloat(style.gap) || 0;
+    let reserved = extraReservePx;
+    let extras = 0;
+    for (const child of el.children) {
+      if (child.tagName === 'SANRING-COMBOBOX-CHIPS') continue;
+      if (child.tagName === 'SANRING-COMBOBOX-INPUT') continue;
+      reserved += (child as HTMLElement).offsetWidth;
+      extras += 1;
+    }
+    return el.clientWidth - paddingX - reserved - gap * extras;
+  }
 
   protected readonly wrapperClass = computed(() =>
     cn(
       // 🌟 排版核心：讓裡面的 Chips 和 Input 能夠在同一行水平排列、自動換行
-      'flex min-h-10 w-full flex-wrap items-center gap-1 rounded-[var(--sanring-radius)] border border-[var(--sanring-border-strong)] bg-[var(--sanring-surface)] px-3 py-1 text-sm text-[var(--sanring-foreground)]',
+      'relative flex min-h-10 min-w-0 w-full items-center gap-1 rounded-[var(--sanring-radius)] border border-[var(--sanring-border-strong)] bg-[var(--sanring-surface)] px-3 py-1 text-sm text-[var(--sanring-foreground)]',
+      this.wrap() ? 'flex-wrap' : 'flex-nowrap overflow-hidden',
       // 當大腦被禁用時的樣式
       this.combobox.isDisabled() ? 'cursor-not-allowed opacity-50' : 'cursor-text',
       // 聚焦時的外框亮起效果（模擬真實 input 的 focus-within 狀態）
diff --git a/registry/components/combobox/combobox-chip.component.ts b/registry/components/combobox/combobox-chip.component.ts
index cf90b8e..2ba20a1 100644
--- a/registry/components/combobox/combobox-chip.component.ts
+++ b/registry/components/combobox/combobox-chip.component.ts
@@ -1,6 +1,14 @@
-import { ChangeDetectionStrategy, Component, computed, inject, input } from '@angular/core';
+import {
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  ElementRef,
+  inject,
+  input,
+} from '@angular/core';
 import { LucideX } from '@lucide/angular';
 import { ComboboxComponent } from './combobox.component';
+import { ComboboxChipsComponent } from './combobox-chips.component';
 import { cn } from '../shared/utils';
 
 @Component({
@@ -39,6 +47,20 @@ export class ComboboxChipComponent {
 
   // 🪄 依賴注入：連線到大腦
   protected combobox = inject(ComboboxComponent);
+  private readonly chipsParent = inject(ComboboxChipsComponent, { optional: true });
+  private readonly elementRef = inject<ElementRef<HTMLElement>>(ElementRef);
+
+  protected readonly overflowHidden = computed(() => {
+    const parent = this.chipsParent;
+    if (!parent) return false;
+    const from = parent.hiddenFrom();
+    if (from === null) return false;
+    const node = this.elementRef.nativeElement;
+    const chips = node.parentElement
+      ? [...node.parentElement.children].filter((child) => child.tagName === 'SANRING-COMBOBOX-CHIP')
+      : [];
+    return chips.indexOf(node) >= from;
+  });
 
   // 🔍 禁用狀態判斷：如果大腦被禁用了，或者這顆 Chip 自己被禁用了，就鎖死按鈕
   protected readonly isDisabled = computed(() => this.disabled() || this.combobox.isDisabled());
@@ -46,11 +68,12 @@ export class ComboboxChipComponent {
   // 🎨 視覺排版：經典的 Badge/Chip 樣式
   protected readonly chipClass = computed(() =>
     cn(
-      'inline-flex items-center justify-between rounded-[var(--sanring-radius-xs)] px-1.5 py-0.5 text-xs font-semibold transition-colors',
+      'inline-flex shrink-0 items-center justify-between rounded-[var(--sanring-radius-xs)] px-1.5 py-0.5 text-xs font-semibold transition-colors',
       // 預設樣式：次要背景色
       'border border-[var(--sanring-border)] bg-[var(--sanring-surface-strong)] text-[var(--sanring-foreground)]',
       // 禁用狀態的透明度
       this.isDisabled() ? 'opacity-50 pointer-events-none' : 'hover:bg-[var(--sanring-active)]',
+      this.overflowHidden() && 'pointer-events-none invisible absolute',
       this.class(),
     ),
   );
diff --git a/registry/components/combobox/combobox-chips.component.ts b/registry/components/combobox/combobox-chips.component.ts
index 39a0d6c..b252edc 100644
--- a/registry/components/combobox/combobox-chips.component.ts
+++ b/registry/components/combobox/combobox-chips.component.ts
@@ -1,20 +1,98 @@
-import { ChangeDetectionStrategy, Component, computed, input } from '@angular/core';
+import {
+  afterEveryRender,
+  booleanAttribute,
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  ElementRef,
+  inject,
+  input,
+  signal,
+} from '@angular/core';
+import { ComboboxChipInputComponent } from './combobox-chip-input.component';
 import { cn } from '../shared/utils';
 
 @Component({
   changeDetection: ChangeDetectionStrategy.OnPush,
   selector: 'sanring-combobox-chips',
   standalone: true,
-  template: `<ng-content></ng-content>`,
+  template: `
+    <ng-content></ng-content>
+    @if (overflowing()) {
+      <span
+        data-overflow-ellipsis
+        class="shrink-0 select-none text-[var(--sanring-muted)]"
+        aria-hidden="true"
+      >…</span>
+    }
+  `,
   host: {
     '[class]': 'chipsClass()',
   },
 })
 export class ComboboxChipsComponent {
-  // 允許外部微調樣式
   readonly class = input<string | undefined>();
+  /** When false, chips stay on one line and overflow with an ellipsis. */
+  readonly wrap = input(true, { transform: booleanAttribute });
+
+  private readonly elementRef = inject<ElementRef<HTMLElement>>(ElementRef);
+  private readonly chipInput = inject(ComboboxChipInputComponent, { optional: true });
+  protected readonly overflowing = signal(false);
+  /** First chip index that no longer fits on a single line. */
+  readonly hiddenFrom = signal<number | null>(null);
+
+  constructor() {
+    afterEveryRender(() => {
+      if (this.wrap()) {
+        if (this.overflowing()) this.overflowing.set(false);
+        if (this.hiddenFrom() !== null) this.hiddenFrom.set(null);
+        this.chipInput?.setChipsOverflowing(false);
+        return;
+      }
+      const node = this.elementRef.nativeElement;
+      const gap = parseFloat(getComputedStyle(node).gap) || 0;
+      const chips = [...node.children].filter(
+        (child) => child.tagName === 'SANRING-COMBOBOX-CHIP',
+      ) as HTMLElement[];
+      const widths = chips.map((chip) => chip.offsetWidth);
+      const total = (count: number) => {
+        if (count <= 0) return 0;
+        return (
+          widths.slice(0, count).reduce((sum, width) => sum + width, 0) +
+          gap * Math.max(0, count - 1)
+        );
+      };
+      const lane = this.chipInput ? this.chipInput.chipLaneWidth() : node.clientWidth;
+      const allFit = total(chips.length) <= lane;
+      if (allFit) {
+        if (this.overflowing()) this.overflowing.set(false);
+        if (this.hiddenFrom() !== null) this.hiddenFrom.set(null);
+        this.chipInput?.setChipsOverflowing(false);
+        return;
+      }
+
+      const ellipsis =
+        node.querySelector<HTMLElement>('[data-overflow-ellipsis]')?.offsetWidth ?? 14;
+      let visible = chips.length;
+      while (
+        visible > 1 &&
+        total(visible) + (visible > 0 ? gap : 0) + ellipsis > lane
+      ) {
+        visible -= 1;
+      }
+      if (!this.overflowing()) this.overflowing.set(true);
+      this.chipInput?.setChipsOverflowing(true);
+      const from = visible < chips.length ? visible : chips.length;
+      if (this.hiddenFrom() !== from) this.hiddenFrom.set(from);
+    });
+  }
 
   protected readonly chipsClass = computed(() =>
-    cn('flex flex-wrap items-center gap-1', this.class()),
+    cn(
+      this.wrap()
+        ? 'contents'
+        : 'flex min-w-0 shrink-0 items-center gap-1 flex-nowrap',
+      this.class(),
+    ),
   );
 }
diff --git a/registry/components/combobox/combobox-input.component.ts b/registry/components/combobox/combobox-input.component.ts
index 9f154f8..e6eebe5 100644
--- a/registry/components/combobox/combobox-input.component.ts
+++ b/registry/components/combobox/combobox-input.component.ts
@@ -32,6 +32,7 @@ import { FIELD_SIZE_CLASS } from '../shared/component-styles';
       (focus)="combobox.onFocus()"
       (blur)="combobox.onBlur()"
       autocomplete="off"
+      size="1"
       role="combobox"
       [attr.aria-expanded]="combobox.isOpen()"
       [attr.aria-controls]="combobox.listId()"
@@ -70,8 +71,13 @@ export class ComboboxInputComponent {
   protected readonly inputClass = computed(() => {
     if (this.chipInputParent) {
       return cn(
-        'min-w-[60px] flex-1 border-0 bg-transparent p-0 text-sm text-[var(--sanring-foreground)] outline-none',
+        'border-0 bg-transparent p-0 text-sm text-[var(--sanring-foreground)] outline-none',
         'placeholder:text-[var(--sanring-muted)] disabled:cursor-not-allowed disabled:opacity-50',
+        this.chipInputParent.wrap()
+          ? 'min-w-[4ch] w-auto'
+          : this.chipInputParent.chipsOverflowing() && !this.combobox.inputValue()
+            ? 'w-0 min-w-0 flex-none overflow-hidden'
+            : 'min-w-0 flex-1',
         this.class(),
       );
     }
diff --git a/registry/components/combobox/combobox.component.ts b/registry/components/combobox/combobox.component.ts
index 14755d6..c65798c 100644
--- a/registry/components/combobox/combobox.component.ts
+++ b/registry/components/combobox/combobox.component.ts
@@ -93,7 +93,7 @@ export class ComboboxComponent extends SanringCvaBase<ComboboxValue> {
   readonly isDisabled = computed(() => this.disabled() || this.disabledState());
 
   protected readonly hostClass = computed(() =>
-    cn('relative block w-full', this.isDisabled() && 'opacity-50 cursor-not-allowed', this.class()),
+    cn('relative block w-full min-w-0', this.isDisabled() && 'opacity-50 cursor-not-allowed', this.class()),
   );
 
   readonly computedAriaDescribedBy = this.makeComputedAriaDescribedBy();

From 611bd46033c3a4e7f6d9c14ef1d8d70e22e104bb Mon Sep 17 00:00:00 2001
From: jack755051 <jack755051@gmail.com>
Date: Tue, 22 Sep 2026 10:07:16 +0800
Subject: [PATCH 06/13] docs(input): keep character counts inside the control

Move input/textarea live counts onto the field so error messages can
sit below, and lock the projection order with a field unit test.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .../components/input/input-page.component.ts  | 28 ++++++++---
 .../app/pages/components/input/input.docs.ts  | 14 ++++--
 .../textarea/textarea-page.component.ts       | 36 ++++++++++----
 .../components/textarea/textarea.docs.ts      | 14 ++++--
 .../components/field/field.component.spec.ts  | 47 +++++++++++++++++++
 5 files changed, 115 insertions(+), 24 deletions(-)

diff --git a/apps/docs/src/app/pages/components/input/input-page.component.ts b/apps/docs/src/app/pages/components/input/input-page.component.ts
index 439a06d..37aa659 100644
--- a/apps/docs/src/app/pages/components/input/input-page.component.ts
+++ b/apps/docs/src/app/pages/components/input/input-page.component.ts
@@ -1,5 +1,5 @@
 import { Component, inject } from '@angular/core';
-import { FormControl, FormsModule, ReactiveFormsModule, Validators } from '@angular/forms';
+import { FormControl, ReactiveFormsModule, Validators } from '@angular/forms';
 import {
   DescriptionDirective,
   ErrorMessageComponent,
@@ -29,7 +29,6 @@ import { inputPage, inputPageExamples } from './input.docs';
     DescriptionDirective,
     ErrorMessageComponent,
     FieldLabelDirective,
-    FormsModule,
     InputDirective,
     ReactiveFormsModule,
     SanringFieldComponent,
@@ -141,10 +140,21 @@ import { InputDirective } from './components/ui/input';"
                 <sanring-field>
                   <!-- eslint-disable-next-line @angular-eslint/template/label-has-associated-control -->
                   <label sanringLabel>Title</label>
-                  <input sanringInput maxlength="500" [(ngModel)]="title" />
-                  <p sanringDescription class="text-end tabular-nums" aria-live="polite">
-                    {{ title.length }}/500
-                  </p>
+                  <div class="relative min-w-0 w-full" ngProjectAs="[sanringInput]">
+                    <input
+                      sanringInput
+                      class="min-w-0 pr-14"
+                      maxlength="500"
+                      [formControl]="titleControl"
+                    />
+                    <span
+                      class="pointer-events-none absolute top-1/2 right-3 -translate-y-1/2 text-xs tabular-nums text-[var(--sanring-muted)]"
+                      aria-live="polite"
+                    >
+                      {{ titleControl.value.length }}/500
+                    </span>
+                  </div>
+                  <sanring-error-message>Title must be at least 50 characters.</sanring-error-message>
                 </sanring-field>
               </div>
             </app-component-page-code-previewer>
@@ -174,10 +184,14 @@ export class InputPageComponent {
     nonNullable: true,
     validators: [Validators.required],
   });
-  protected title = 'Sanring UI demo text';
+  protected readonly titleControl = new FormControl('Sanring UI demo text', {
+    nonNullable: true,
+    validators: [Validators.minLength(50)],
+  });
 
   constructor() {
     this.emailControl.markAsTouched();
+    this.titleControl.markAsTouched();
   }
 
   protected section(id: string) {
diff --git a/apps/docs/src/app/pages/components/input/input.docs.ts b/apps/docs/src/app/pages/components/input/input.docs.ts
index a793462..89cba90 100644
--- a/apps/docs/src/app/pages/components/input/input.docs.ts
+++ b/apps/docs/src/app/pages/components/input/input.docs.ts
@@ -129,9 +129,15 @@ import { InputDirective } from './components/ui/input';`,
   file: `<input sanringInput type="file" />`,
   characterCount: `<sanring-field>
   <label sanringLabel>Title</label>
-  <input sanringInput maxlength="500" [(ngModel)]="title" />
-  <p sanringDescription class="text-end tabular-nums" aria-live="polite">
-    {{ title.length }}/500
-  </p>
+  <div class="relative min-w-0 w-full" ngProjectAs="[sanringInput]">
+    <input sanringInput class="min-w-0 pr-14" maxlength="500" [formControl]="titleControl" />
+    <span
+      class="pointer-events-none absolute top-1/2 right-3 -translate-y-1/2 text-xs tabular-nums text-[var(--sanring-muted)]"
+      aria-live="polite"
+    >
+      {{ titleControl.value.length }}/500
+    </span>
+  </div>
+  <sanring-error-message>Title must be at least 50 characters.</sanring-error-message>
 </sanring-field>`,
 } as const;
diff --git a/apps/docs/src/app/pages/components/textarea/textarea-page.component.ts b/apps/docs/src/app/pages/components/textarea/textarea-page.component.ts
index a4e613c..825d58f 100644
--- a/apps/docs/src/app/pages/components/textarea/textarea-page.component.ts
+++ b/apps/docs/src/app/pages/components/textarea/textarea-page.component.ts
@@ -1,7 +1,7 @@
 import { Component, inject } from '@angular/core';
-import { FormsModule } from '@angular/forms';
+import { FormControl, ReactiveFormsModule, Validators } from '@angular/forms';
 import {
-  DescriptionDirective,
+  ErrorMessageComponent,
   FieldLabelDirective,
   SanringFieldComponent,
   TextareaDirective,
@@ -33,9 +33,9 @@ import { textareaPage, textareaPageExamples } from './textarea.docs';
     ComponentPageKeyboardTableComponent,
     ComponentPageUsageImportsComponent,
     ComponentPageSectionComponent,
-    DescriptionDirective,
+    ErrorMessageComponent,
     FieldLabelDirective,
-    FormsModule,
+    ReactiveFormsModule,
     SanringFieldComponent,
     TextareaDirective,
   ],
@@ -105,10 +105,21 @@ import { textareaPage, textareaPageExamples } from './textarea.docs';
                 <sanring-field>
                   <!-- eslint-disable-next-line @angular-eslint/template/label-has-associated-control -->
                   <label sanringLabel>Bio</label>
-                  <textarea sanringTextarea maxlength="500" [(ngModel)]="bio"></textarea>
-                  <p sanringDescription class="text-end tabular-nums" aria-live="polite">
-                    {{ bio.length }}/500
-                  </p>
+                  <div class="relative w-full" ngProjectAs="[sanringTextarea]">
+                    <textarea
+                      sanringTextarea
+                      class="pr-16"
+                      maxlength="500"
+                      [formControl]="bioControl"
+                    ></textarea>
+                    <span
+                      class="pointer-events-none absolute right-3 bottom-2 bg-[var(--sanring-surface)] pl-1 text-xs tabular-nums text-[var(--sanring-muted)]"
+                      aria-live="polite"
+                    >
+                      {{ bioControl.value.length }}/500
+                    </span>
+                  </div>
+                  <sanring-error-message>Bio must be at least 50 characters.</sanring-error-message>
                 </sanring-field>
               </div>
             </app-component-page-code-previewer>
@@ -134,7 +145,14 @@ export class TextareaPageComponent {
   protected readonly page = textareaPage;
   protected readonly examples = textareaPageExamples;
   protected readonly i18n = inject(I18nService);
-  protected bio = 'Sanring UI demo text';
+  protected readonly bioControl = new FormControl('Sanring UI demo text', {
+    nonNullable: true,
+    validators: [Validators.minLength(50)],
+  });
+
+  constructor() {
+    this.bioControl.markAsTouched();
+  }
 
   protected section(id: string) {
     return getComponentPageSection(this.page, id);
diff --git a/apps/docs/src/app/pages/components/textarea/textarea.docs.ts b/apps/docs/src/app/pages/components/textarea/textarea.docs.ts
index 2cda738..d2764bc 100644
--- a/apps/docs/src/app/pages/components/textarea/textarea.docs.ts
+++ b/apps/docs/src/app/pages/components/textarea/textarea.docs.ts
@@ -97,9 +97,15 @@ export const textareaPageExamples = {
   resize: `<textarea sanringTextarea class="min-h-[140px] resize-y" placeholder="Longer message"></textarea>`,
   characterCount: `<sanring-field>
   <label sanringLabel>Bio</label>
-  <textarea sanringTextarea maxlength="500" [(ngModel)]="bio"></textarea>
-  <p sanringDescription class="text-end tabular-nums" aria-live="polite">
-    {{ bio.length }}/500
-  </p>
+  <div class="relative w-full" ngProjectAs="[sanringTextarea]">
+    <textarea sanringTextarea class="pr-16" maxlength="500" [formControl]="bioControl"></textarea>
+    <span
+      class="pointer-events-none absolute right-3 bottom-2 bg-[var(--sanring-surface)] pl-1 text-xs tabular-nums text-[var(--sanring-muted)]"
+      aria-live="polite"
+    >
+      {{ bioControl.value.length }}/500
+    </span>
+  </div>
+  <sanring-error-message>Bio must be at least 50 characters.</sanring-error-message>
 </sanring-field>`,
 } as const;
diff --git a/packages/ui/src/lib/components/field/field.component.spec.ts b/packages/ui/src/lib/components/field/field.component.spec.ts
index 3aa56b3..b85a692 100644
--- a/packages/ui/src/lib/components/field/field.component.spec.ts
+++ b/packages/ui/src/lib/components/field/field.component.spec.ts
@@ -192,3 +192,50 @@ describe('SanringFieldComponent ambient background auto-detection', () => {
     fixture.nativeElement.remove();
   });
 });
+
+@Component({
+  standalone: true,
+  imports: [
+    SanringFieldComponent,
+    LabelDirective,
+    InputDirective,
+    ErrorMessageComponent,
+    ReactiveFormsModule,
+  ],
+  template: `
+    <sanring-field>
+      <!-- eslint-disable-next-line @angular-eslint/template/label-has-associated-control -->
+      <label sanringLabel>Title</label>
+      <div class="relative w-full" ngProjectAs="[sanringInput]">
+        <input sanringInput class="pr-12" [formControl]="control" />
+        <span class="count">{{ control.value.length }}/500</span>
+      </div>
+      <sanring-error-message>Title must be at least 50 characters.</sanring-error-message>
+    </sanring-field>
+  `,
+})
+class CountInsideInputHost {
+  readonly control = new FormControl('Hi', {
+    nonNullable: true,
+    validators: [Validators.minLength(50)],
+  });
+}
+
+describe('SanringFieldComponent in-control character count', () => {
+  it('keeps an overlay count with the input, above the error message', () => {
+    const fixture = TestBed.createComponent(CountInsideInputHost);
+    fixture.componentInstance.control.markAsTouched();
+    fixture.detectChanges();
+
+    const field = fixture.nativeElement.querySelector('sanring-field') as HTMLElement;
+    const input = field.querySelector('input');
+    const count = field.querySelector('.count');
+    const error = field.querySelector('sanring-error-message');
+    expect(input).toBeTruthy();
+    expect(count).toBeTruthy();
+    expect(error).toBeTruthy();
+    expect(input!.compareDocumentPosition(count!) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
+    expect(count!.compareDocumentPosition(error!) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
+    expect(error!.classList.contains('hidden')).toBe(false);
+  });
+});

From 7e9ad732611934d36337b10044809425bcde9f3b Mon Sep 17 00:00:00 2001
From: jack755051 <jack755051@gmail.com>
Date: Tue, 22 Sep 2026 10:07:19 +0800
Subject: [PATCH 07/13] docs(dialog): show header background separate from body

Document pairing header class with content overflow-hidden/p-0 so the
header surface can differ from the dialog body.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .../app/i18n/locales/en/components/dialog.ts  |  5 +++-
 .../app/i18n/locales/zh/components/dialog.ts  |  5 +++-
 .../dialog/dialog-page.component.ts           | 15 ++++++++----
 .../pages/components/dialog/dialog.docs.ts    | 23 +++++++++++++++----
 .../dialog/dialog.component.spec.ts           | 17 ++++++++++++++
 5 files changed, 55 insertions(+), 10 deletions(-)

diff --git a/apps/docs/src/app/i18n/locales/en/components/dialog.ts b/apps/docs/src/app/i18n/locales/en/components/dialog.ts
index 5578f57..9d61673 100644
--- a/apps/docs/src/app/i18n/locales/en/components/dialog.ts
+++ b/apps/docs/src/app/i18n/locales/en/components/dialog.ts
@@ -1,3 +1,4 @@
+/** Dialog docs copy. */
 export const dialogTranslations = {
   'dialog.description':
     'An overlay primitive built on Angular CDK Dialog for modal tasks and focused decisions.',
@@ -8,7 +9,7 @@ export const dialogTranslations = {
   'dialog.demo.noClose': 'No Close Button',
   'dialog.demo.stickyFooter': 'Sticky Footer',
   'dialog.demo.scrollable': 'Scrollable Content',
-  'dialog.demo.header': 'Header alignment',
+  'dialog.demo.header': 'Header alignment and background',
   'dialog.examples.description':
     'Common dialog patterns for custom actions, hidden close controls, sticky actions, and dense scrollable content.',
   'dialog.examples.basic.description':
@@ -35,6 +36,8 @@ export const dialogTranslations = {
   'dialog.api.mediaClass.description': 'Additional classes merged with the dialog media container.',
   'dialog.api.headerAlign.description':
     'Header text alignment. start is left, center is centered at every breakpoint. The default stays centered on small screens and left-aligned from sm up.',
+  'dialog.api.headerClass.description':
+    'Additional classes merged with the header layout. Use this to give the header a different background from sanring-dialog-content, for example bg-[var(--sanring-surface-strong)]. Pair with overflow-hidden p-0 on content so the fill reaches the panel edges.',
   'dialog.api.titleClass.description':
     'Additional classes merged with the title styles. Use this to change title color, for example text-[var(--sanring-primary-70)].',
   'dialog.accessibility.description':
diff --git a/apps/docs/src/app/i18n/locales/zh/components/dialog.ts b/apps/docs/src/app/i18n/locales/zh/components/dialog.ts
index bb02f5a..3c15b2c 100644
--- a/apps/docs/src/app/i18n/locales/zh/components/dialog.ts
+++ b/apps/docs/src/app/i18n/locales/zh/components/dialog.ts
@@ -1,3 +1,4 @@
+/** Dialog docs copy. */
 export const dialogTranslations = {
   'dialog.description':
     '建立在 Angular CDK Dialog 上的 overlay primitive，適合 modal 任務與聚焦決策。',
@@ -8,7 +9,7 @@ export const dialogTranslations = {
   'dialog.demo.noClose': '沒有關閉按鈕',
   'dialog.demo.stickyFooter': '固定頁尾',
   'dialog.demo.scrollable': '可捲動內容',
-  'dialog.demo.header': '標題對齊',
+  'dialog.demo.header': '標題對齊與背景',
   'dialog.examples.description':
     '常見 Dialog 模式，包含自訂操作、隱藏關閉控制、固定操作區與大量可捲動內容。',
   'dialog.examples.basic.description':
@@ -34,6 +35,8 @@ export const dialogTranslations = {
   'dialog.api.mediaClass.description': '與 dialog media 容器合併的額外 class。',
   'dialog.api.headerAlign.description':
     '標題列文字對齊。start 靠左，center 在所有斷點置中。預設維持小螢幕置中、sm 以上靠左。',
+  'dialog.api.headerClass.description':
+    '與 header 版面樣式合併的額外 class。用來讓標題列背景跟 sanring-dialog-content 不同，例如 bg-[var(--sanring-surface-strong)]。搭配 content 的 overflow-hidden p-0，底色才能貼齊面板邊緣。',
   'dialog.api.titleClass.description':
     '與標題樣式合併的額外 class。用來改標題顏色，例如 text-[var(--sanring-primary-70)]。',
   'dialog.accessibility.description':
diff --git a/apps/docs/src/app/pages/components/dialog/dialog-page.component.ts b/apps/docs/src/app/pages/components/dialog/dialog-page.component.ts
index e0cf716..d4b18d0 100644
--- a/apps/docs/src/app/pages/components/dialog/dialog-page.component.ts
+++ b/apps/docs/src/app/pages/components/dialog/dialog-page.component.ts
@@ -271,19 +271,26 @@ import { dialogPage, dialogPageExamples } from './dialog.docs';
       </ng-template>
 
       <ng-template #headerDialog>
-        <sanring-dialog-content>
-          <sanring-dialog-header align="center">
-            <h2 sanringDialogTitle class="text-[var(--sanring-primary-70)]">Centered title</h2>
+        <sanring-dialog-content class="overflow-hidden p-0">
+          <sanring-dialog-header
+            align="start"
+            class="bg-[var(--sanring-surface-strong)] px-6 py-4 pr-12"
+          >
+            <h2 sanringDialogTitle class="text-[var(--sanring-primary-70)]">Edit profile</h2>
             <p sanringDialogDescription>
-              Header alignment and title color are inputs, not one-off CSS.
+              Align the header independently, and give it a background that is not the body surface.
             </p>
           </sanring-dialog-header>
+          <div class="px-6 py-4 text-sm text-[var(--sanring-muted)]">
+            Dialog body stays on the default content surface.
+          </div>
         </sanring-dialog-content>
       </ng-template>
     </app-component-page>
   `,
 })
 export class DialogPageComponent {
+  // Header example: align + a header surface that is not the dialog body.
   protected readonly page = dialogPage;
   protected readonly examples = dialogPageExamples;
   protected readonly i18n = inject(I18nService);
diff --git a/apps/docs/src/app/pages/components/dialog/dialog.docs.ts b/apps/docs/src/app/pages/components/dialog/dialog.docs.ts
index 2dce379..887d48e 100644
--- a/apps/docs/src/app/pages/components/dialog/dialog.docs.ts
+++ b/apps/docs/src/app/pages/components/dialog/dialog.docs.ts
@@ -157,6 +157,12 @@ export const dialogPage = {
       defaultValue: 'responsive',
       descriptionKey: 'dialog.api.headerAlign.description',
     },
+    {
+      property: 'DialogHeaderComponent.class',
+      type: 'string',
+      defaultValue: 'undefined',
+      descriptionKey: 'dialog.api.headerClass.description',
+    },
     {
       property: 'DialogTitleDirective.class',
       type: 'string',
@@ -171,6 +177,7 @@ export const dialogPage = {
   ] satisfies readonly ComponentPageKeyboardRow[],
 } as const satisfies ComponentPageDefinition;
 
+
 export const dialogPageExamples = {
   composition: `[sanringDialogTrigger]
 sanring-dialog-content
@@ -330,13 +337,21 @@ export class ExampleComponent {}`,
   header: `<button sanringBtn [sanringDialogTrigger]="dialog">Open dialog</button>
 
 <ng-template #dialog>
-  <sanring-dialog-content>
-    <sanring-dialog-header align="center">
+  <sanring-dialog-content class="overflow-hidden p-0">
+    <sanring-dialog-header
+      align="start"
+      class="bg-[var(--sanring-surface-strong)] px-6 py-4 pr-12"
+    >
       <h2 sanringDialogTitle class="text-[var(--sanring-primary-70)]">
-        Centered title
+        Edit profile
       </h2>
-      <p sanringDialogDescription>Header alignment and title color are inputs, not one-off CSS.</p>
+      <p sanringDialogDescription>
+        Align the header independently, and give it a background that is not the body surface.
+      </p>
     </sanring-dialog-header>
+    <div class="px-6 py-4 text-sm text-[var(--sanring-muted)]">
+      Dialog body stays on the default content surface.
+    </div>
   </sanring-dialog-content>
 </ng-template>`,
 } as const;
diff --git a/packages/ui/src/lib/components/dialog/dialog.component.spec.ts b/packages/ui/src/lib/components/dialog/dialog.component.spec.ts
index cd13f58..940fe7c 100644
--- a/packages/ui/src/lib/components/dialog/dialog.component.spec.ts
+++ b/packages/ui/src/lib/components/dialog/dialog.component.spec.ts
@@ -339,3 +339,20 @@ describe('DialogHeaderComponent', () => {
     expect(header.classList.contains('items-start')).toBe(true);
   });
 });
+
+@Component({
+  imports: [DialogHeaderComponent],
+  template: `<sanring-dialog-header class="bg-[var(--sanring-surface-strong)]">Title</sanring-dialog-header>`,
+})
+class DialogHeaderClassHost {}
+
+describe('DialogHeaderComponent class', () => {
+  it('merges a consumer class so the header can use a different background', async () => {
+    await TestBed.configureTestingModule({ imports: [DialogHeaderClassHost] }).compileComponents();
+    const fixture = TestBed.createComponent(DialogHeaderClassHost);
+    fixture.detectChanges();
+
+    const header = fixture.nativeElement.querySelector('sanring-dialog-header') as HTMLElement;
+    expect(header.classList.contains('bg-[var(--sanring-surface-strong)]')).toBe(true);
+  });
+});

From 7b17eb942f4b3eecc91b9a6283e3dbe2c8aba346 Mon Sep 17 00:00:00 2001
From: jack755051 <jack755051@gmail.com>
Date: Tue, 22 Sep 2026 10:07:22 +0800
Subject: [PATCH 08/13] chore: note count, combobox wrap, and dialog header
 polish

Add the patch changeset and changelog lines for the in-field counts,
combobox wrap/ellipsis, and dialog header background recipe.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .changeset/count-inside-dialog-header-bg.md              | 5 +++++
 apps/docs/src/app/pages/changelog/component-changelog.ts | 6 +++---
 2 files changed, 8 insertions(+), 3 deletions(-)
 create mode 100644 .changeset/count-inside-dialog-header-bg.md

diff --git a/.changeset/count-inside-dialog-header-bg.md b/.changeset/count-inside-dialog-header-bg.md
new file mode 100644
index 0000000..40a1ba9
--- /dev/null
+++ b/.changeset/count-inside-dialog-header-bg.md
@@ -0,0 +1,5 @@
+---
+'@sanring/cli': patch
+---
+
+Keep input/textarea/combobox counts inside the field on the right, add combobox chip wrap/ellipsis, and let dialog headers use a different background from the body.
diff --git a/apps/docs/src/app/pages/changelog/component-changelog.ts b/apps/docs/src/app/pages/changelog/component-changelog.ts
index cad8420..1d2a7de 100644
--- a/apps/docs/src/app/pages/changelog/component-changelog.ts
+++ b/apps/docs/src/app/pages/changelog/component-changelog.ts
@@ -47,17 +47,17 @@ export const cliVersionChangelog: readonly CliVersionEntry[] = [
       {
         type: 'added',
         componentIds: ['dialog'],
-        text: '`sanring-dialog-header` accepts `align` (`start` | `center`) so title alignment is not only the responsive default. Title color still goes through `sanringDialogTitle` `class`.',
+        text: '`sanring-dialog-header` accepts `align` (`start` | `center`). Header `class` can set a background that is not the dialog body surface.',
       },
       {
         type: 'added',
         componentIds: ['input', 'textarea'],
-        text: 'Docs examples show a live character count (`20/500`) using native `maxlength` and `sanringDescription`.',
+        text: 'Docs examples show a live character count inside the control on the right, so `sanring-error-message` can stay below.',
       },
       {
         type: 'added',
         componentIds: ['combobox'],
-        text: 'The multiple-select example shows selected/total count, for example `2/5`.',
+        text: '`sanring-combobox-chip-input` and `sanring-combobox-chips` accept `wrap`. Single-line multiple selection overflows with an ellipsis; the selected/total count sits on the right of the field.',
       },
       {
         type: 'changed',

From cdc111186e3a14350eae08a70f3061588afd78e4 Mon Sep 17 00:00:00 2001
From: jack755051 <jack755051@gmail.com>
Date: Tue, 22 Sep 2026 13:18:30 +0800
Subject: [PATCH 09/13] docs(docs): simplify chrome with shared surface classes

Replace one-off color-mix and soft-shadow recipes with shared docs
panel/nav/toc utilities, and point Tailwind @source at packages/ui.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .../component-page-api-table.component.ts     |  33 ++---
 ...component-page-code-previewer.component.ts |  27 +---
 .../component-page-header.component.ts        |  36 ++---
 ...component-page-recent-changes.component.ts |  29 ++--
 .../component-page-section.component.ts       |   7 +-
 .../docs-page-header.component.ts             |  19 +--
 .../changelog/changelog-page.component.ts     |   2 +-
 .../src/app/pages/cli/cli-page.component.ts   |   2 +-
 .../home/home-components-section.component.ts |   6 +-
 .../home/home-features-section.component.ts   |   2 +-
 .../home/home-hero-demo-panel.component.ts    |   2 +-
 .../pages/home/home-hero-section.component.ts |   2 +-
 .../home/home-start-section.component.ts      |   6 +-
 .../introduction-page.component.ts            |   2 +-
 .../src/app/pages/mcp/mcp-page.component.ts   |   2 +-
 .../pages/registry/registry-page.component.ts |   2 +-
 .../pages/roadmap/roadmap-page.component.ts   |   2 +-
 .../pages/theming/theming-page.component.ts   |   2 +-
 .../shell/header/feature-list.component.ts    |  10 +-
 .../src/app/shell/header/header.component.ts  |   2 +-
 .../app/shell/header/menu-list.component.ts   |   6 +-
 .../shell/sidebar/docs-section.component.ts   |  12 +-
 .../shell/sidebar/docs-sidebar.component.ts   |   9 +-
 .../src/app/shell/toc/docs-toc.component.ts   |  24 +--
 apps/docs/src/styles.css                      | 139 +++++++++++++++---
 25 files changed, 200 insertions(+), 185 deletions(-)

diff --git a/apps/docs/src/app/layouts/component-page/component-page-api-table.component.ts b/apps/docs/src/app/layouts/component-page/component-page-api-table.component.ts
index bb6575a..57277c3 100644
--- a/apps/docs/src/app/layouts/component-page/component-page-api-table.component.ts
+++ b/apps/docs/src/app/layouts/component-page/component-page-api-table.component.ts
@@ -7,12 +7,9 @@ import { I18nService } from '../../i18n/i18n.service';
   standalone: true,
   template: `
     <div
-      class="mb-2 flex min-w-0 flex-wrap items-center justify-between gap-2 rounded-[var(--sanring-radius-sm)] border border-[color-mix(in_srgb,var(--docs-border)_80%,transparent)] bg-[color-mix(in_srgb,var(--docs-elevated)_68%,transparent)] px-3 py-2 font-mono text-xs"
+      class="docs-panel mb-2 flex min-w-0 flex-wrap items-center justify-between gap-2 px-3 py-2 text-xs"
     >
-      <span
-        class="inline-flex items-center gap-2 font-semibold uppercase tracking-[0.08em] text-[var(--docs-fg)]"
-      >
-        <span class="size-1.5 rounded-full bg-[var(--docs-accent)]" aria-hidden="true"></span>
+      <span class="docs-eyebrow">
         {{ i18n.t('docs.api.surface') }}
       </span>
       <span class="text-[var(--docs-muted)]"
@@ -21,7 +18,7 @@ import { I18nService } from '../../i18n/i18n.service';
     </div>
 
     <div
-      class="hidden overflow-hidden rounded-[var(--sanring-radius)] border border-[color-mix(in_srgb,var(--docs-border)_86%,transparent)] bg-[color-mix(in_srgb,var(--docs-panel)_78%,transparent)] shadow-[var(--docs-shadow-soft)] md:block"
+      class="docs-panel hidden overflow-hidden md:block"
     >
       <table class="w-full table-fixed border-collapse text-left text-[13px]">
         <caption class="sr-only">
@@ -30,7 +27,7 @@ import { I18nService } from '../../i18n/i18n.service';
           }}
         </caption>
         <thead
-          class="bg-[color-mix(in_srgb,var(--docs-elevated)_86%,transparent)] text-[var(--docs-muted)]"
+          class="bg-[var(--docs-surface)] text-[var(--docs-muted)]"
         >
           <tr>
             <th class="w-[22%] border-b border-[var(--docs-border)] px-3 py-2 font-medium">
@@ -48,15 +45,12 @@ import { I18nService } from '../../i18n/i18n.service';
           </tr>
         </thead>
         <tbody>
-          @for (row of rows; track row.property; let last = $last; let index = $index) {
+          @for (row of rows; track row.property; let last = $last) {
             <tr
               [class.border-b]="!last"
-              class="group border-[var(--docs-border)] transition-colors hover:bg-[color-mix(in_srgb,var(--docs-elevated)_46%,transparent)]"
+              class="group border-[var(--docs-border)] transition-colors hover:bg-[var(--docs-surface)]"
             >
               <td class="break-words px-3 py-2.5 align-top font-mono text-[var(--docs-fg)]">
-                <span class="mr-2 text-[10px] text-[var(--docs-accent-strong)]">{{
-                  rowNumber(index)
-                }}</span>
                 <span class="font-semibold">{{ row.property }}</span>
               </td>
               <td class="break-words px-3 py-2.5 align-top">
@@ -80,16 +74,11 @@ import { I18nService } from '../../i18n/i18n.service';
     </div>
 
     <div class="grid gap-3 md:hidden">
-      @for (row of rows; track row.property; let index = $index) {
-        <article
-          class="overflow-hidden rounded-[var(--sanring-radius)] border border-[color-mix(in_srgb,var(--docs-border)_86%,transparent)] bg-[color-mix(in_srgb,var(--docs-panel)_86%,transparent)] shadow-sm"
-        >
+      @for (row of rows; track row.property) {
+        <article class="docs-panel overflow-hidden">
           <div
-            class="flex min-w-0 items-center gap-2 border-b border-[var(--docs-border)] bg-[color-mix(in_srgb,var(--docs-elevated)_66%,transparent)] px-3 py-2.5"
+            class="flex min-w-0 items-center gap-2 border-b border-[var(--docs-border)] bg-[var(--docs-surface)] px-3 py-2.5"
           >
-            <span class="font-mono text-[10px] text-[var(--docs-accent-strong)]">{{
-              rowNumber(index)
-            }}</span>
             <p
               class="m-0 min-w-0 break-words font-mono text-sm font-semibold text-[var(--docs-fg)]"
             >
@@ -137,8 +126,4 @@ import { I18nService } from '../../i18n/i18n.service';
 export class ComponentPageApiTableComponent {
   @Input({ required: true }) rows!: readonly ComponentPageApiRow[];
   protected readonly i18n = inject(I18nService);
-
-  protected rowNumber(index: number) {
-    return String(index + 1).padStart(2, '0');
-  }
 }
diff --git a/apps/docs/src/app/layouts/component-page/component-page-code-previewer.component.ts b/apps/docs/src/app/layouts/component-page/component-page-code-previewer.component.ts
index 4a7ec02..b10148e 100644
--- a/apps/docs/src/app/layouts/component-page/component-page-code-previewer.component.ts
+++ b/apps/docs/src/app/layouts/component-page/component-page-code-previewer.component.ts
@@ -18,31 +18,23 @@ import {
   template: `
     <div class="mt-9 grid gap-4">
       <section
-        class="min-w-0 overflow-hidden rounded-[var(--sanring-radius-lg)] border border-[color-mix(in_srgb,var(--docs-border)_86%,transparent)] bg-[color-mix(in_srgb,var(--docs-panel)_92%,transparent)] shadow-[var(--docs-shadow-strong)]"
+        class="docs-panel-lg min-w-0 overflow-hidden"
         role="group"
         [attr.aria-label]="i18n.t('component.previewer.preview')"
       >
         <div
-          class="flex min-w-0 items-center justify-between gap-3 border-b border-[color-mix(in_srgb,var(--docs-border)_82%,transparent)] bg-[color-mix(in_srgb,var(--docs-elevated)_76%,transparent)] px-3.5 py-2.5 font-mono"
+          class="flex min-w-0 items-center justify-between gap-3 border-b border-[var(--docs-border)] bg-[var(--docs-surface)] px-3.5 py-2.5"
         >
-          <span
-            class="inline-flex min-w-0 items-center gap-2 text-xs font-semibold text-[var(--docs-fg)]"
-          >
-            <span class="text-[var(--docs-accent-strong)]">01</span>
-            <span class="uppercase tracking-[0.08em]">{{
-              i18n.t('component.previewer.preview')
-            }}</span>
+          <span class="docs-eyebrow min-w-0">
+            {{ i18n.t('component.previewer.preview') }}
           </span>
-          <span
-            class="inline-flex shrink-0 items-center gap-1.5 text-[11px] text-[var(--docs-muted)]"
-          >
-            <span class="size-1.5 rounded-full bg-[var(--docs-success)]" aria-hidden="true"></span>
+          <span class="shrink-0 text-xs text-[var(--docs-muted)]">
             {{ i18n.t('component.previewer.rendered') }}
           </span>
         </div>
 
         <div
-          class="grid place-items-center [background:linear-gradient(180deg,color-mix(in_srgb,var(--docs-elevated)_62%,transparent),color-mix(in_srgb,var(--docs-panel)_76%,transparent)),linear-gradient(var(--docs-bg-grid)_1px,transparent_1px),linear-gradient(90deg,var(--docs-bg-grid)_1px,transparent_1px)] [background-size:auto,30px_30px,30px_30px]"
+          class="grid place-items-center bg-[var(--docs-surface)]"
           [class]="
             wide()
               ? 'min-h-[340px] p-4 max-[720px]:min-h-[280px] max-[720px]:p-3'
@@ -59,11 +51,8 @@ import {
         [attr.aria-label]="i18n.t('component.previewer.source')"
       >
         <div class="flex min-w-0 flex-wrap items-center justify-between gap-2 px-1 font-mono">
-          <span class="inline-flex items-center gap-2 text-xs font-semibold text-[var(--docs-fg)]">
-            <span class="text-[var(--docs-accent-strong)]">02</span>
-            <span class="uppercase tracking-[0.08em]">{{
-              i18n.t('component.previewer.source')
-            }}</span>
+          <span class="docs-eyebrow">
+            {{ i18n.t('component.previewer.source') }}
           </span>
           <span class="flex items-center gap-3 text-[11px] text-[var(--docs-muted)]">
             <span>{{ language() }} · {{ i18n.t('component.header.copyReady') }}</span>
diff --git a/apps/docs/src/app/layouts/component-page/component-page-header.component.ts b/apps/docs/src/app/layouts/component-page/component-page-header.component.ts
index 0678a8b..7964e34 100644
--- a/apps/docs/src/app/layouts/component-page/component-page-header.component.ts
+++ b/apps/docs/src/app/layouts/component-page/component-page-header.component.ts
@@ -38,16 +38,16 @@ import { DocsPageHeaderComponent } from './docs-page-header.component';
       @if (componentId) {
         <div page-meta class="grid w-full min-w-0 gap-3">
           <div
-            class="grid min-w-0 overflow-hidden rounded-[var(--sanring-radius)] border border-[color-mix(in_srgb,var(--docs-border)_88%,transparent)] bg-[var(--docs-border)] shadow-[var(--docs-shadow-soft)] sm:grid-cols-[minmax(0,1.35fr)_minmax(0,1fr)] sm:gap-px"
+            class="docs-panel grid min-w-0 overflow-hidden sm:grid-cols-[minmax(0,1.35fr)_minmax(0,1fr)]"
           >
             <button
               type="button"
-              class="group min-w-0 bg-[color-mix(in_srgb,var(--docs-code)_96%,transparent)] px-3.5 py-3 text-left transition-colors hover:bg-[var(--docs-code-header)] focus-visible:relative focus-visible:z-10 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-[var(--docs-focus-ring)]"
+              class="group min-w-0 bg-[var(--docs-code)] px-3.5 py-3 text-left transition-colors hover:bg-[var(--docs-code-header)] focus-visible:relative focus-visible:z-10 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-[var(--docs-focus-ring)]"
               [attr.aria-label]="i18n.t('component.header.copyInstall')"
               (click)="copyInstallCommand()"
             >
               <span
-                class="mb-2 flex items-center justify-between gap-3 font-mono text-[10px] font-semibold uppercase tracking-[0.08em] text-[var(--docs-code-muted)]"
+                class="docs-eyebrow mb-2 flex items-center justify-between gap-3 font-mono text-[var(--docs-code-muted)]"
               >
                 <span>{{ i18n.t('component.header.installCommand') }}</span>
                 <span class="inline-flex items-center gap-1.5 normal-case tracking-normal">
@@ -69,11 +69,9 @@ import { DocsPageHeaderComponent } from './docs-page-header.component';
             </button>
 
             <div
-              class="min-w-0 border-t border-[var(--docs-border)] bg-[color-mix(in_srgb,var(--docs-panel)_94%,transparent)] px-3.5 py-3 sm:border-l sm:border-t-0"
+              class="min-w-0 border-t border-[var(--docs-border)] bg-[var(--docs-panel)] px-3.5 py-3 sm:border-l sm:border-t-0"
             >
-              <span
-                class="mb-2 block font-mono text-[10px] font-semibold uppercase tracking-[0.08em] text-[var(--docs-muted)]"
-              >
+              <span class="docs-eyebrow mb-2 block font-mono">
                 {{ i18n.t('component.header.packagePath') }}
               </span>
               <span class="block break-all font-mono text-[13px] leading-5 text-[var(--docs-fg)]">
@@ -90,12 +88,7 @@ import { DocsPageHeaderComponent } from './docs-page-header.component';
               <span class="font-mono text-[var(--docs-fg)]">{{ componentId }}</span>
             </span>
 
-            <span
-              [class]="
-                metaChipClass +
-                ' border-[color-mix(in_srgb,var(--docs-accent)_38%,var(--docs-border))] bg-[color-mix(in_srgb,var(--docs-accent)_10%,var(--docs-surface))] font-mono uppercase tracking-[0.06em] text-[var(--docs-accent-strong)]'
-              "
-            >
+            <span [class]="metaChipClass + ' font-mono text-[var(--docs-fg)]'">
               <span class="size-1.5 rounded-full bg-[var(--docs-accent)]" aria-hidden="true"></span>
               {{ i18n.t('component.header.shipped') }}
             </span>
@@ -110,12 +103,7 @@ import { DocsPageHeaderComponent } from './docs-page-header.component';
             }
 
             @if (ssrSafe === true) {
-              <span
-                [class]="
-                  metaChipClass +
-                  ' border-[color-mix(in_srgb,var(--docs-success)_38%,var(--docs-border))] bg-[color-mix(in_srgb,var(--docs-success)_10%,var(--docs-surface))]'
-                "
-              >
+              <span [class]="metaChipClass">
                 {{ i18n.t('component.header.ssrSafe') }}
               </span>
             } @else if (ssrSafe === false) {
@@ -155,23 +143,20 @@ import { DocsPageHeaderComponent } from './docs-page-header.component';
           </div>
 
           <nav
-            class="flex min-w-0 flex-wrap items-center gap-x-3 gap-y-2 border-t border-[color-mix(in_srgb,var(--docs-border)_80%,transparent)] pt-3 font-mono text-xs"
+            class="flex min-w-0 flex-wrap items-center gap-x-3 gap-y-2 border-t border-[var(--docs-border)] pt-3 font-mono text-xs"
             [attr.aria-label]="i18n.t('component.header.quickAccess')"
           >
-            <span class="uppercase tracking-[0.08em] text-[var(--docs-muted)]">{{
+            <span class="text-[var(--docs-muted)]">{{
               i18n.t('component.header.quickAccess')
             }}</span>
             <a [class]="jumpLinkClass" href="#installation">
-              <span class="text-[var(--docs-accent-strong)]">01</span>
               {{ i18n.t('component.header.jumpInstall') }}
             </a>
             <a [class]="jumpLinkClass" [href]="apiAnchor">
-              <span class="text-[var(--docs-accent-strong)]">02</span>
               {{ i18n.t('component.header.jumpApi') }}
             </a>
             @if (latestChangeVersion) {
               <a [class]="jumpLinkClass" href="#recent-changes">
-                <span class="text-[var(--docs-accent-strong)]">03</span>
                 {{ i18n.t('component.recentChanges.title') }}
               </a>
             }
@@ -263,8 +248,7 @@ export class ComponentPageHeaderComponent implements OnChanges {
   @Input() apiAnchor = '#api';
 
   protected readonly i18n = inject(I18nService);
-  protected readonly metaChipClass =
-    'inline-flex items-center gap-1.5 rounded-[var(--sanring-radius-sm)] border border-[var(--docs-border)] bg-[var(--docs-surface)] px-2 py-1 text-xs font-medium text-[var(--docs-muted)]';
+  protected readonly metaChipClass = 'docs-chip';
   protected readonly jumpLinkClass =
     'inline-flex items-center gap-1.5 text-[var(--docs-fg)] no-underline transition-colors hover:text-[var(--docs-accent-strong)] focus-visible:rounded-[var(--sanring-radius-xs)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--docs-focus-ring)]';
   private readonly router = inject(Router);
diff --git a/apps/docs/src/app/layouts/component-page/component-page-recent-changes.component.ts b/apps/docs/src/app/layouts/component-page/component-page-recent-changes.component.ts
index 50c8be0..678f4be 100644
--- a/apps/docs/src/app/layouts/component-page/component-page-recent-changes.component.ts
+++ b/apps/docs/src/app/layouts/component-page/component-page-recent-changes.component.ts
@@ -50,30 +50,19 @@ function renderInlineCode(text: string): string {
     @if (changes().length > 0) {
       <section
         id="recent-changes"
-        class="mt-16 overflow-hidden rounded-[var(--sanring-radius)] border border-[color-mix(in_srgb,var(--docs-border)_86%,transparent)] bg-[color-mix(in_srgb,var(--docs-panel)_76%,transparent)] shadow-[var(--docs-shadow-soft)]"
+        class="docs-panel mt-16 overflow-hidden"
         [attr.aria-labelledby]="'recent-changes-title'"
       >
         <div
-          class="flex min-w-0 flex-wrap items-center justify-between gap-3 border-b border-[var(--docs-border)] bg-[color-mix(in_srgb,var(--docs-elevated)_72%,transparent)] px-3.5 py-3"
+          class="flex min-w-0 flex-wrap items-center justify-between gap-3 border-b border-[var(--docs-border)] bg-[var(--docs-surface)] px-3.5 py-3"
         >
-          <div class="flex min-w-0 items-center gap-3">
-            <span
-              class="h-8 w-1 shrink-0 rounded-full bg-[linear-gradient(180deg,var(--docs-accent),var(--docs-accent-alt))]"
-              aria-hidden="true"
-            ></span>
-            <div class="min-w-0">
-              <p
-                class="m-0 font-mono text-[10px] font-semibold uppercase tracking-[0.08em] text-[var(--docs-accent-strong)]"
-              >
-                {{ i18n.t('component.recentChanges.signal') }}
-              </p>
-              <h2
-                id="recent-changes-title"
-                class="m-0 mt-0.5 text-base font-semibold leading-tight tracking-normal text-[var(--docs-fg)]"
-              >
-                {{ i18n.t('component.recentChanges.title') }}
-              </h2>
-            </div>
+          <div class="min-w-0">
+            <h2
+              id="recent-changes-title"
+              class="m-0 text-base font-semibold leading-tight text-[var(--docs-fg)]"
+            >
+              {{ i18n.t('component.recentChanges.title') }}
+            </h2>
           </div>
           <a
             class="shrink-0 font-mono text-xs font-medium text-[var(--docs-muted)] no-underline transition-colors hover:text-[var(--docs-fg)] focus-visible:rounded-[var(--sanring-radius-xs)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--docs-focus-ring)]"
diff --git a/apps/docs/src/app/layouts/component-page/component-page-section.component.ts b/apps/docs/src/app/layouts/component-page/component-page-section.component.ts
index 45fcdb0..e1ace28 100644
--- a/apps/docs/src/app/layouts/component-page/component-page-section.component.ts
+++ b/apps/docs/src/app/layouts/component-page/component-page-section.component.ts
@@ -23,10 +23,7 @@ interface StructuredDescriptionItem {
       <div class="mb-3.5">
         <div [class]="headingWrapClass">
           @if (level === 2) {
-            <span
-              class="mt-1 h-8 w-1.5 rounded-full bg-[linear-gradient(180deg,var(--docs-accent),var(--docs-accent-alt))]"
-              aria-hidden="true"
-            ></span>
+            <span class="mt-1.5 h-5 w-0.5 shrink-0 bg-[var(--docs-accent)]" aria-hidden="true"></span>
           }
           @switch (level) {
             @case (4) {
@@ -54,7 +51,7 @@ interface StructuredDescriptionItem {
             >
               @for (item of structuredDescriptionItems; track item.body) {
                 <li
-                  class="grid gap-1 rounded-[var(--sanring-radius)] border border-[color-mix(in_srgb,var(--docs-border)_82%,transparent)] bg-[color-mix(in_srgb,var(--docs-elevated)_72%,transparent)] px-3 py-2.5 shadow-sm"
+                  class="docs-panel grid gap-1 px-3 py-2.5"
                 >
                   <strong
                     class="text-xs font-semibold uppercase tracking-normal text-[var(--docs-fg)]"
diff --git a/apps/docs/src/app/layouts/component-page/docs-page-header.component.ts b/apps/docs/src/app/layouts/component-page/docs-page-header.component.ts
index f420178..51bb495 100644
--- a/apps/docs/src/app/layouts/component-page/docs-page-header.component.ts
+++ b/apps/docs/src/app/layouts/component-page/docs-page-header.component.ts
@@ -7,23 +7,10 @@ import { Component, Input } from '@angular/core';
     class: 'block min-w-0',
   },
   template: `
-    <header
-      class="relative mb-12 overflow-hidden rounded-[var(--sanring-radius-lg)] border border-[color-mix(in_srgb,var(--docs-border)_82%,transparent)] bg-[color-mix(in_srgb,var(--docs-panel)_88%,transparent)] p-7 shadow-[var(--docs-shadow-strong)] max-[720px]:p-5"
-    >
-      <div
-        class="pointer-events-none absolute inset-x-0 top-0 h-1 bg-[linear-gradient(90deg,var(--docs-accent),var(--docs-accent-alt),var(--docs-accent-warm))]"
-        aria-hidden="true"
-      ></div>
-      <div
-        class="pointer-events-none absolute inset-0 opacity-60 [background-image:linear-gradient(var(--docs-bg-grid)_1px,transparent_1px),linear-gradient(90deg,var(--docs-bg-grid)_1px,transparent_1px)] [background-size:32px_32px]"
-        aria-hidden="true"
-      ></div>
-
-      <div class="relative z-10 min-w-0">
+    <header class="docs-panel-lg relative mb-12 p-6 max-[720px]:p-5">
+      <div class="min-w-0">
         @if (eyebrow) {
-          <p
-            class="mb-4 inline-flex max-w-full rounded-[var(--sanring-radius-sm)] border border-[color-mix(in_srgb,var(--docs-accent)_32%,var(--docs-border))] bg-[color-mix(in_srgb,var(--docs-accent)_10%,var(--docs-surface))] px-2.5 py-1 font-mono text-xs font-semibold text-[var(--docs-accent-strong)]"
-          >
+          <p class="docs-eyebrow mb-3 font-mono">
             <span class="min-w-0 truncate">{{ eyebrow }}</span>
           </p>
         }
diff --git a/apps/docs/src/app/pages/changelog/changelog-page.component.ts b/apps/docs/src/app/pages/changelog/changelog-page.component.ts
index e263db2..f9399d8 100644
--- a/apps/docs/src/app/pages/changelog/changelog-page.component.ts
+++ b/apps/docs/src/app/pages/changelog/changelog-page.component.ts
@@ -65,7 +65,7 @@ function renderInlineCode(text: string): string {
         eyebrow="docs / version-notes"
       />
 
-      <section class="mb-4 overflow-hidden rounded-[var(--sanring-radius-lg)] border border-[var(--docs-border)] bg-[var(--docs-code)] text-[var(--docs-code-fg)] shadow-[var(--docs-shadow-soft)]" aria-label="Release console">
+      <section class="docs-code-panel mb-4 overflow-hidden" aria-label="Release console">
         <header class="flex flex-wrap items-center justify-between gap-3 border-b border-[color-mix(in_srgb,var(--docs-code-fg)_18%,transparent)] px-5 py-4"><div><p class="m-0 font-mono text-xs font-semibold uppercase tracking-[0.12em] text-[var(--docs-accent)]">RELEASE CONSOLE</p><p class="m-0 mt-1 text-sm text-[color-mix(in_srgb,var(--docs-code-fg)_62%,transparent)]">A compact record of what changed and when.</p></div><span class="font-mono text-xs text-[color-mix(in_srgb,var(--docs-code-fg)_58%,transparent)]">latest release</span></header>
         <div class="grid sm:grid-cols-[1.2fr_0.8fr_0.8fr]"><div class="p-5"><p class="m-0 font-mono text-[10px] uppercase tracking-[0.12em] text-[color-mix(in_srgb,var(--docs-code-fg)_52%,transparent)]">CURRENT</p><div class="mt-3 flex items-baseline gap-3"><span class="text-3xl font-semibold text-[var(--docs-code-fg)]">v{{ versionedChangelog[0]?.version }}</span><time class="font-mono text-xs text-[color-mix(in_srgb,var(--docs-code-fg)_58%,transparent)]">{{ versionedChangelog[0]?.date }}</time></div></div><div class="border-t border-[color-mix(in_srgb,var(--docs-code-fg)_18%,transparent)] p-5 sm:border-l sm:border-t-0"><p class="m-0 font-mono text-[10px] uppercase tracking-[0.12em] text-[color-mix(in_srgb,var(--docs-code-fg)_52%,transparent)]">CHANGES</p><p class="m-0 mt-3 text-3xl font-semibold text-[var(--docs-accent)]">{{ versionedChangelog[0]?.changes.length }}</p></div><div class="border-t border-[color-mix(in_srgb,var(--docs-code-fg)_18%,transparent)] p-5 sm:border-l sm:border-t-0"><p class="m-0 font-mono text-[10px] uppercase tracking-[0.12em] text-[color-mix(in_srgb,var(--docs-code-fg)_52%,transparent)]">NOTABLE</p><p class="m-0 mt-3 text-3xl font-semibold text-[var(--docs-code-fg)]">{{ versionedChangelog[0]?.visible.length }}</p></div></div>
       </section>
diff --git a/apps/docs/src/app/pages/cli/cli-page.component.ts b/apps/docs/src/app/pages/cli/cli-page.component.ts
index bc4133e..58f0769 100644
--- a/apps/docs/src/app/pages/cli/cli-page.component.ts
+++ b/apps/docs/src/app/pages/cli/cli-page.component.ts
@@ -28,7 +28,7 @@ const INLINE_CODE_CLASS =
         eyebrow="docs / cli"
       />
 
-      <section class="mb-4 overflow-hidden rounded-[var(--sanring-radius-lg)] border border-[var(--docs-border)] bg-[var(--docs-code)] text-[var(--docs-code-fg)] shadow-[var(--docs-shadow-soft)]" aria-label="CLI workflow overview">
+      <section class="docs-code-panel mb-4 overflow-hidden" aria-label="CLI workflow overview">
         <header class="flex flex-wrap items-center justify-between gap-3 border-b border-[color-mix(in_srgb,var(--docs-code-fg)_18%,transparent)] px-5 py-4">
           <div><p class="m-0 font-mono text-xs font-semibold uppercase tracking-[0.12em] text-[var(--docs-accent)]">CLI WORKFLOW</p><p class="m-0 mt-1 text-sm text-[color-mix(in_srgb,var(--docs-code-fg)_62%,transparent)]">Move from intent to a reviewed local change.</p></div>
           <span class="rounded-[var(--sanring-radius-sm)] border border-[color-mix(in_srgb,var(--docs-code-fg)_22%,transparent)] px-2 py-1 font-mono text-[11px] text-[color-mix(in_srgb,var(--docs-code-fg)_68%,transparent)]">dry-run safe</span>
diff --git a/apps/docs/src/app/pages/home/home-components-section.component.ts b/apps/docs/src/app/pages/home/home-components-section.component.ts
index 74015e7..f3b571f 100644
--- a/apps/docs/src/app/pages/home/home-components-section.component.ts
+++ b/apps/docs/src/app/pages/home/home-components-section.component.ts
@@ -16,9 +16,9 @@ import { isRecentlyUpdatedComponentId } from '../changelog/component-changelog';
   imports: [RouterLink, ButtonDirective, ScrollAreaDirective, LucideChevronRight],
   template: `
     <section class="grid gap-10 border-t border-[var(--docs-border)] pt-12 lg:grid-cols-[minmax(280px,0.72fr)_minmax(0,1.28fr)] lg:gap-16" aria-labelledby="home-components-title">
-      <div class="lg:sticky lg:top-28 lg:self-start"><p class="m-0 text-sm font-semibold uppercase tracking-[0.12em] text-[var(--docs-accent-strong)]">{{ i18n.t('home.components.eyebrow') }}</p><h2 id="home-components-title" class="m-0 mt-5 max-w-[440px] text-[clamp(2.3rem,3.7vw,4.2rem)] font-semibold leading-[0.98] tracking-[-0.06em] text-[var(--docs-fg)] max-[520px]:text-[2.8rem]">{{ i18n.t('home.components.title') }}</h2><p class="m-0 mt-6 max-w-[420px] text-lg leading-8 text-[var(--docs-muted)] max-[520px]:mt-5 max-[520px]:text-base max-[520px]:leading-7">{{ i18n.t('home.components.description') }}</p><a sanringBtn class="mt-8 min-h-11 rounded-[var(--sanring-radius)] font-semibold max-[520px]:mt-6" routerLink="/components" variant="outline" size="md">{{ i18n.t('home.components.browseAll') }}<svg class="size-4" lucideChevronRight></svg></a></div>
-      <div class="min-w-0 rounded-[var(--sanring-radius-lg)] border border-[color-mix(in_srgb,var(--docs-accent)_38%,var(--docs-border))] bg-[var(--docs-panel)] p-6 shadow-[var(--docs-shadow-soft)] max-[520px]:p-4">
-        <div class="mb-6 flex items-end justify-between gap-4 border-b border-[var(--docs-border)] pb-5 max-[520px]:mb-4 max-[520px]:pb-4"><div class="min-w-0"><p class="m-0 text-sm font-semibold uppercase tracking-[0.08em] text-[var(--docs-muted)]">{{ i18n.t('home.components.panelEyebrow') }}</p><p class="m-0 mt-2 text-2xl font-semibold text-[var(--docs-fg)] max-[520px]:text-xl">{{ i18n.t('home.components.panelTitle') }}</p></div><p class="m-0 shrink-0 font-mono text-4xl font-semibold text-[var(--docs-accent-strong)] max-[520px]:text-3xl">{{ componentCount }}</p></div>
+      <div class="lg:sticky lg:top-28 lg:self-start"><p class="docs-eyebrow">{{ i18n.t('home.components.eyebrow') }}</p><h2 id="home-components-title" class="m-0 mt-5 max-w-[440px] text-[clamp(2.3rem,3.7vw,4.2rem)] font-semibold leading-[0.98] tracking-[-0.06em] text-[var(--docs-fg)] max-[520px]:text-[2.8rem]">{{ i18n.t('home.components.title') }}</h2><p class="m-0 mt-6 max-w-[420px] text-lg leading-8 text-[var(--docs-muted)] max-[520px]:mt-5 max-[520px]:text-base max-[520px]:leading-7">{{ i18n.t('home.components.description') }}</p><a sanringBtn class="mt-8 min-h-11 rounded-[var(--sanring-radius)] font-semibold max-[520px]:mt-6" routerLink="/components" variant="outline" size="md">{{ i18n.t('home.components.browseAll') }}<svg class="size-4" lucideChevronRight></svg></a></div>
+      <div class="docs-panel-lg min-w-0 p-6 max-[520px]:p-4">
+        <div class="mb-6 flex items-end justify-between gap-4 border-b border-[var(--docs-border)] pb-5 max-[520px]:mb-4 max-[520px]:pb-4"><div class="min-w-0"><p class="docs-eyebrow">{{ i18n.t('home.components.panelEyebrow') }}</p><p class="m-0 mt-2 text-2xl font-semibold text-[var(--docs-fg)] max-[520px]:text-xl">{{ i18n.t('home.components.panelTitle') }}</p></div><p class="m-0 shrink-0 font-mono text-4xl font-semibold text-[var(--docs-accent-strong)] max-[520px]:text-3xl">{{ componentCount }}</p></div>
         <nav sanringScrollArea [hideScrollbar]="true" class="grid max-h-[520px] grid-cols-3 gap-3 pr-1 max-[980px]:grid-cols-2 max-[520px]:max-h-[460px] max-[480px]:grid-cols-1" aria-label="Component shortcuts">
           @for (item of componentItems; track item.id) {
             @if (item.disabled) {
diff --git a/apps/docs/src/app/pages/home/home-features-section.component.ts b/apps/docs/src/app/pages/home/home-features-section.component.ts
index f020d11..069d4c8 100644
--- a/apps/docs/src/app/pages/home/home-features-section.component.ts
+++ b/apps/docs/src/app/pages/home/home-features-section.component.ts
@@ -16,7 +16,7 @@ interface HomeFeature {
   imports: [LucideCode2, LucideLayers3, LucideTerminalSquare],
   template: `
     <section class="grid gap-12 border-t border-[var(--docs-border)] pt-12 lg:grid-cols-[minmax(260px,0.78fr)_minmax(0,1.22fr)] lg:gap-20" aria-labelledby="home-features-title">
-      <div><p class="m-0 text-sm font-semibold uppercase tracking-[0.12em] text-[var(--docs-accent-strong)]">{{ i18n.t('home.features.eyebrow') }}</p><h2 id="home-features-title" class="m-0 mt-5 max-w-[520px] text-[clamp(2.8rem,5vw,5.2rem)] font-semibold leading-[0.94] tracking-[-0.06em] text-[var(--docs-fg)] max-[520px]:text-[2.9rem]">{{ i18n.t('home.features.title') }}</h2><p class="m-0 mt-6 max-w-[450px] text-lg leading-8 text-[var(--docs-muted)] max-[520px]:text-base max-[520px]:leading-7">{{ i18n.t('home.features.description') }}</p></div>
+      <div><p class="docs-eyebrow">{{ i18n.t('home.features.eyebrow') }}</p><h2 id="home-features-title" class="m-0 mt-5 max-w-[520px] text-[clamp(2.8rem,5vw,5.2rem)] font-semibold leading-[0.94] tracking-[-0.06em] text-[var(--docs-fg)] max-[520px]:text-[2.9rem]">{{ i18n.t('home.features.title') }}</h2><p class="m-0 mt-6 max-w-[450px] text-lg leading-8 text-[var(--docs-muted)] max-[520px]:text-base max-[520px]:leading-7">{{ i18n.t('home.features.description') }}</p></div>
       <div class="grid gap-4 sm:grid-cols-3">
         @for (feature of features; track feature.titleKey) {
           <article class="min-w-0 rounded-[var(--sanring-radius-lg)] bg-[var(--docs-surface)] p-6 max-[520px]:p-5">
diff --git a/apps/docs/src/app/pages/home/home-hero-demo-panel.component.ts b/apps/docs/src/app/pages/home/home-hero-demo-panel.component.ts
index 11a24d7..fd433b6 100644
--- a/apps/docs/src/app/pages/home/home-hero-demo-panel.component.ts
+++ b/apps/docs/src/app/pages/home/home-hero-demo-panel.component.ts
@@ -10,7 +10,7 @@ import { I18nService } from '../../i18n/i18n.service';
   imports: [ButtonDirective, SANRING_DIALOG_IMPORTS, LucideLayers3],
   template: `
     <div
-      class="min-w-0 rounded-[var(--sanring-radius-lg)] border border-[var(--docs-border)] bg-[var(--docs-code)] p-5 text-[var(--docs-code-fg)] shadow-[var(--docs-shadow-soft)] lg:mt-6 lg:p-6 max-[520px]:p-4"
+      class="docs-code-panel min-w-0 p-5 lg:mt-6 lg:p-6 max-[520px]:p-4"
     >
       <div
         class="flex min-w-0 items-center justify-between gap-4 border-b border-[color-mix(in_srgb,var(--docs-code-fg)_18%,transparent)] pb-4"
diff --git a/apps/docs/src/app/pages/home/home-hero-section.component.ts b/apps/docs/src/app/pages/home/home-hero-section.component.ts
index 9b69630..1d62b70 100644
--- a/apps/docs/src/app/pages/home/home-hero-section.component.ts
+++ b/apps/docs/src/app/pages/home/home-hero-section.component.ts
@@ -29,7 +29,7 @@ import { HomeHeroDemoPanelComponent } from './home-hero-demo-panel.component';
 
         <div class="mt-20 max-[860px]:mt-16 max-[520px]:mt-14">
           <p
-            class="m-0 text-sm font-semibold uppercase tracking-[0.12em] text-[var(--docs-accent-strong)]"
+            class="docs-eyebrow"
           >
             {{ i18n.t('home.eyebrow') }}
           </p>
diff --git a/apps/docs/src/app/pages/home/home-start-section.component.ts b/apps/docs/src/app/pages/home/home-start-section.component.ts
index 8e1367b..9eb3385 100644
--- a/apps/docs/src/app/pages/home/home-start-section.component.ts
+++ b/apps/docs/src/app/pages/home/home-start-section.component.ts
@@ -9,9 +9,9 @@ import { I18nService } from '../../i18n/i18n.service';
   standalone: true,
   imports: [RouterLink, ButtonDirective, LucideChevronRight],
   template: `
-    <section class="grid gap-8 border-y border-[var(--docs-border)] bg-[var(--docs-accent)] px-8 py-10 lg:grid-cols-[minmax(0,1fr)_auto] lg:items-center lg:gap-12 lg:px-12 lg:py-12 max-[520px]:px-5 max-[520px]:py-8" aria-labelledby="home-start-title">
-      <div><p class="m-0 text-sm font-semibold uppercase tracking-[0.12em] text-[color-mix(in_srgb,var(--docs-accent-fg)_72%,transparent)]">{{ i18n.t('home.start.eyebrow') }}</p><h2 id="home-start-title" class="m-0 mt-4 max-w-[700px] text-[clamp(2.4rem,4vw,4.5rem)] font-semibold leading-[0.96] tracking-[-0.055em] text-[var(--docs-accent-fg)] max-[520px]:text-[2.75rem]">{{ i18n.t('home.start.title') }}</h2><p class="m-0 mt-4 max-w-[620px] text-lg leading-8 text-[color-mix(in_srgb,var(--docs-accent-fg)_78%,transparent)] max-[520px]:text-base max-[520px]:leading-7">{{ i18n.t('home.start.description') }}</p></div>
-      <div class="flex flex-wrap gap-3 lg:justify-end max-[520px]:grid max-[520px]:grid-cols-1"><a sanringBtn class="min-h-12 min-w-[150px] rounded-[var(--sanring-radius)] border-[var(--docs-accent-fg)] bg-[var(--docs-accent-fg)] px-5 font-semibold text-[var(--docs-accent)] hover:bg-[color-mix(in_srgb,var(--docs-accent-fg)_88%,white)] max-[520px]:w-full max-[520px]:justify-center" routerLink="/introduction" variant="default" size="md">{{ i18n.t('home.start.readDocs') }}<svg class="size-4" lucideChevronRight></svg></a><a sanringBtn class="min-h-12 min-w-[120px] rounded-[var(--sanring-radius)] border-[color-mix(in_srgb,var(--docs-accent-fg)_38%,transparent)] bg-transparent px-5 font-semibold text-[var(--docs-accent-fg)] hover:bg-[color-mix(in_srgb,var(--docs-accent-fg)_12%,transparent)] max-[520px]:w-full max-[520px]:justify-center" routerLink="/cli" variant="outline" size="md">{{ i18n.t('home.start.viewCli') }}</a></div>
+    <section class="grid gap-8 border-y border-[var(--docs-border)] py-10 lg:grid-cols-[minmax(0,1fr)_auto] lg:items-center lg:gap-12 lg:py-12" aria-labelledby="home-start-title">
+      <div><p class="docs-eyebrow">{{ i18n.t('home.start.eyebrow') }}</p><h2 id="home-start-title" class="m-0 mt-4 max-w-[700px] text-[clamp(2.4rem,4vw,4.5rem)] font-semibold leading-[0.96] tracking-[-0.055em] text-[var(--docs-fg)] max-[520px]:text-[2.75rem]">{{ i18n.t('home.start.title') }}</h2><p class="m-0 mt-4 max-w-[620px] text-lg leading-8 text-[var(--docs-muted)] max-[520px]:text-base max-[520px]:leading-7">{{ i18n.t('home.start.description') }}</p></div>
+      <div class="flex flex-wrap gap-3 lg:justify-end max-[520px]:grid max-[520px]:grid-cols-1"><a sanringBtn class="min-h-12 min-w-[150px] px-5 font-semibold max-[520px]:w-full max-[520px]:justify-center" routerLink="/introduction" variant="default" size="md">{{ i18n.t('home.start.readDocs') }}<svg class="size-4" lucideChevronRight></svg></a><a sanringBtn class="min-h-12 min-w-[120px] px-5 font-semibold max-[520px]:w-full max-[520px]:justify-center" routerLink="/cli" variant="outline" size="md">{{ i18n.t('home.start.viewCli') }}</a></div>
     </section>
   `,
   styles: [':host { display: block; }'],
diff --git a/apps/docs/src/app/pages/introduction/introduction-page.component.ts b/apps/docs/src/app/pages/introduction/introduction-page.component.ts
index 881d230..10e850a 100644
--- a/apps/docs/src/app/pages/introduction/introduction-page.component.ts
+++ b/apps/docs/src/app/pages/introduction/introduction-page.component.ts
@@ -58,7 +58,7 @@ interface IntroNextLink {
         </div>
       </app-docs-page-header>
 
-      <section class="mb-4 overflow-hidden rounded-[var(--sanring-radius-lg)] border border-[var(--docs-border)] bg-[var(--docs-panel)] shadow-[var(--docs-shadow-soft)]" aria-label="Introduction path">
+      <section class="docs-panel-lg mb-4 overflow-hidden" aria-label="Introduction path">
         <div class="flex flex-wrap items-center justify-between gap-3 border-b border-[var(--docs-border)] px-5 py-4"><p class="m-0 font-mono text-xs font-semibold uppercase tracking-[0.12em] text-[var(--docs-accent-strong)]">START HERE</p><span class="font-mono text-xs text-[var(--docs-muted)]">3 moves to a local UI</span></div>
         <div class="grid divide-y divide-[var(--docs-border)] sm:grid-cols-3 sm:divide-x sm:divide-y-0"><div class="p-5"><p class="m-0 font-mono text-xs text-[var(--docs-accent-strong)]">01</p><h2 class="m-0 mt-7 text-lg font-semibold text-[var(--docs-fg)]">Install the source</h2><code class="mt-3 block font-mono text-xs text-[var(--docs-muted)]">npx @sanring/cli init</code></div><div class="p-5"><p class="m-0 font-mono text-xs text-[var(--docs-accent-strong)]">02</p><h2 class="m-0 mt-7 text-lg font-semibold text-[var(--docs-fg)]">Choose a primitive</h2><p class="m-0 mt-3 text-sm leading-6 text-[var(--docs-muted)]">Bring only the component your product needs.</p></div><div class="bg-[var(--docs-accent)] p-5 text-[var(--docs-accent-fg)]"><p class="m-0 font-mono text-xs">03</p><h2 class="m-0 mt-7 text-lg font-semibold">Compose the edge</h2><p class="m-0 mt-3 text-sm leading-6 text-[color-mix(in_srgb,var(--docs-accent-fg)_78%,transparent)]">Keep the important decisions inside your app.</p></div></div>
       </section>
diff --git a/apps/docs/src/app/pages/mcp/mcp-page.component.ts b/apps/docs/src/app/pages/mcp/mcp-page.component.ts
index e981f03..f009960 100644
--- a/apps/docs/src/app/pages/mcp/mcp-page.component.ts
+++ b/apps/docs/src/app/pages/mcp/mcp-page.component.ts
@@ -28,7 +28,7 @@ const INLINE_CODE_CLASS =
         eyebrow="docs / mcp"
       />
 
-      <section class="mb-4 overflow-hidden rounded-[var(--sanring-radius-lg)] border border-[var(--docs-border)] bg-[var(--docs-panel)] shadow-[var(--docs-shadow-soft)]" aria-label="MCP agent tool map">
+      <section class="docs-panel-lg mb-4 overflow-hidden" aria-label="MCP agent tool map">
         <header class="flex flex-wrap items-center justify-between gap-3 border-b border-[var(--docs-border)] px-5 py-4"><div><p class="m-0 font-mono text-xs font-semibold uppercase tracking-[0.12em] text-[var(--docs-accent-strong)]">AGENT TOOL MAP</p><p class="m-0 mt-1 text-sm text-[var(--docs-muted)]">Discover first. Plan before anything writes.</p></div><span class="rounded-[var(--sanring-radius-sm)] bg-[var(--docs-success-bg)] px-2 py-1 font-mono text-[11px] text-[var(--docs-success-fg)]">safe by default</span></header>
         <div class="grid lg:grid-cols-[minmax(0,1.12fr)_minmax(220px,0.88fr)]">
           <div class="p-5 sm:p-6"><div class="flex flex-wrap items-center gap-2 font-mono text-[11px] text-[var(--docs-muted)]"><span class="rounded-[var(--sanring-radius-sm)] bg-[var(--docs-surface)] px-2 py-1">read</span><span>→</span><span class="rounded-[var(--sanring-radius-sm)] bg-[var(--docs-surface)] px-2 py-1">plan</span><span>→</span><span class="rounded-[var(--sanring-radius-sm)] bg-[var(--docs-accent)] px-2 py-1 text-[var(--docs-accent-fg)]">write</span></div><div class="mt-5 grid gap-2 sm:grid-cols-3"><div class="rounded-[var(--sanring-radius)] border border-[var(--docs-border)] p-3"><p class="m-0 font-mono text-xs text-[var(--docs-accent-strong)]">READ</p><p class="m-0 mt-2 text-sm font-semibold text-[var(--docs-fg)]">list / search / info</p><p class="m-0 mt-1 text-xs leading-5 text-[var(--docs-muted)]">understand the registry</p></div><div class="rounded-[var(--sanring-radius)] border border-[var(--docs-border)] p-3"><p class="m-0 font-mono text-xs text-[var(--docs-accent-strong)]">PLAN</p><p class="m-0 mt-2 text-sm font-semibold text-[var(--docs-fg)]">preview install</p><p class="m-0 mt-1 text-xs leading-5 text-[var(--docs-muted)]">files and deps first</p></div><div class="rounded-[var(--sanring-radius)] border border-[color-mix(in_srgb,var(--docs-accent)_38%,var(--docs-border))] bg-[color-mix(in_srgb,var(--docs-accent)_8%,transparent)] p-3"><p class="m-0 font-mono text-xs text-[var(--docs-accent-strong)]">WRITE</p><p class="m-0 mt-2 text-sm font-semibold text-[var(--docs-fg)]">add component</p><p class="m-0 mt-1 text-xs leading-5 text-[var(--docs-muted)]">only after approval</p></div></div></div>
diff --git a/apps/docs/src/app/pages/registry/registry-page.component.ts b/apps/docs/src/app/pages/registry/registry-page.component.ts
index c7c0b52..562e1a9 100644
--- a/apps/docs/src/app/pages/registry/registry-page.component.ts
+++ b/apps/docs/src/app/pages/registry/registry-page.component.ts
@@ -33,7 +33,7 @@ const INLINE_CODE_CLASS =
         eyebrow="docs / registry"
       />
 
-      <section class="mb-4 rounded-[var(--sanring-radius-lg)] border border-[var(--docs-border)] bg-[var(--docs-panel)] p-5 shadow-[var(--docs-shadow-soft)] sm:p-6" aria-label="Registry model overview">
+      <section class="docs-panel-lg mb-4 p-5 sm:p-6" aria-label="Registry model overview">
         <div class="flex flex-wrap items-end justify-between gap-4 border-b border-[var(--docs-border)] pb-5"><div><p class="m-0 font-mono text-xs font-semibold uppercase tracking-[0.12em] text-[var(--docs-accent-strong)]">REGISTRY MODEL</p><h2 class="m-0 mt-2 text-2xl font-semibold tracking-[-0.03em] text-[var(--docs-fg)]">One schema, three dependency layers.</h2></div><span class="font-mono text-xs text-[var(--docs-muted)]">registry.json</span></div>
         <div class="mt-5 grid gap-4 lg:grid-cols-[minmax(0,0.8fr)_minmax(300px,1.2fr)]">
           <div class="rounded-[var(--sanring-radius)] border border-[var(--docs-border)] bg-[var(--docs-code)] p-4 font-mono text-xs leading-7 text-[var(--docs-code-fg)]"><div class="text-[var(--docs-accent)]">registry.json</div><div class="pl-4 text-[color-mix(in_srgb,var(--docs-code-fg)_76%,transparent)]">├─ components[]</div><div class="pl-8 text-[color-mix(in_srgb,var(--docs-code-fg)_62%,transparent)]">├─ files[]</div><div class="pl-8 text-[color-mix(in_srgb,var(--docs-code-fg)_62%,transparent)]">├─ componentDeps[]</div><div class="pl-8 text-[color-mix(in_srgb,var(--docs-code-fg)_62%,transparent)]">└─ sharedDeps[]</div><div class="pl-4 text-[color-mix(in_srgb,var(--docs-code-fg)_76%,transparent)]">├─ blocks[]</div><div class="pl-4 text-[color-mix(in_srgb,var(--docs-code-fg)_76%,transparent)]">└─ shared[]</div></div>
diff --git a/apps/docs/src/app/pages/roadmap/roadmap-page.component.ts b/apps/docs/src/app/pages/roadmap/roadmap-page.component.ts
index ea3569a..ff19a22 100644
--- a/apps/docs/src/app/pages/roadmap/roadmap-page.component.ts
+++ b/apps/docs/src/app/pages/roadmap/roadmap-page.component.ts
@@ -89,7 +89,7 @@ interface RoadmapComponentRow {
         eyebrow="docs / roadmap"
       />
 
-      <section class="mb-4 rounded-[var(--sanring-radius-lg)] border border-[var(--docs-border)] bg-[var(--docs-panel)] p-5 shadow-[var(--docs-shadow-soft)] sm:p-6" aria-label="Roadmap delivery map">
+      <section class="docs-panel-lg mb-4 p-5 sm:p-6" aria-label="Roadmap delivery map">
         <div class="flex flex-wrap items-end justify-between gap-4 border-b border-[var(--docs-border)] pb-5"><div><p class="m-0 font-mono text-xs font-semibold uppercase tracking-[0.12em] text-[var(--docs-accent-strong)]">DELIVERY MAP</p><h2 class="m-0 mt-2 text-2xl font-semibold tracking-[-0.03em] text-[var(--docs-fg)]">What is shipped, next, and forming.</h2></div><span class="font-mono text-xs text-[var(--docs-muted)]">{{ releaseVersion }}</span></div>
         <div class="mt-5 grid gap-2 sm:grid-cols-4"><div class="rounded-[var(--sanring-radius)] bg-[var(--docs-accent)] p-4 text-[var(--docs-accent-fg)]"><p class="m-0 font-mono text-xs">SHIPPED</p><p class="m-0 mt-4 text-3xl font-semibold">{{ shipped.length }}</p><p class="m-0 mt-1 text-xs opacity-75">available now</p></div><div class="rounded-[var(--sanring-radius)] border border-[var(--docs-border)] bg-[var(--docs-surface)] p-4"><p class="m-0 font-mono text-xs text-[var(--docs-muted)]">TIER 1</p><p class="m-0 mt-4 text-3xl font-semibold text-[var(--docs-fg)]">{{ tier1.length }}</p><p class="m-0 mt-1 text-xs text-[var(--docs-muted)]">next in line</p></div><div class="rounded-[var(--sanring-radius)] border border-[var(--docs-border)] bg-[var(--docs-surface)] p-4"><p class="m-0 font-mono text-xs text-[var(--docs-muted)]">TIER 2</p><p class="m-0 mt-4 text-3xl font-semibold text-[var(--docs-fg)]">{{ tier2.length }}</p><p class="m-0 mt-1 text-xs text-[var(--docs-muted)]">in planning</p></div><div class="rounded-[var(--sanring-radius)] border border-[var(--docs-border)] bg-[var(--docs-surface)] p-4"><p class="m-0 font-mono text-xs text-[var(--docs-muted)]">TIER 3+</p><p class="m-0 mt-4 text-3xl font-semibold text-[var(--docs-fg)]">{{ tier3.length + tier4.length }}</p><p class="m-0 mt-1 text-xs text-[var(--docs-muted)]">forming</p></div></div>
       </section>
diff --git a/apps/docs/src/app/pages/theming/theming-page.component.ts b/apps/docs/src/app/pages/theming/theming-page.component.ts
index 0f6ecd2..6ae6518 100644
--- a/apps/docs/src/app/pages/theming/theming-page.component.ts
+++ b/apps/docs/src/app/pages/theming/theming-page.component.ts
@@ -30,7 +30,7 @@ import { ThemingTailwindSectionComponent } from './theming-tailwind-section.comp
         eyebrow="docs / theming"
       />
 
-      <section class="mb-4 rounded-[var(--sanring-radius-lg)] border border-[var(--docs-border)] bg-[var(--docs-panel)] p-5 shadow-[var(--docs-shadow-soft)] sm:p-6" aria-label="Theme token model">
+      <section class="docs-panel-lg mb-4 p-5 sm:p-6" aria-label="Theme token model">
         <div class="flex flex-wrap items-end justify-between gap-4 border-b border-[var(--docs-border)] pb-5"><div><p class="m-0 font-mono text-xs font-semibold uppercase tracking-[0.12em] text-[var(--docs-accent-strong)]">TOKEN CASCADE</p><h2 class="m-0 mt-2 text-2xl font-semibold tracking-[-0.03em] text-[var(--docs-fg)]">Scale → semantic → component.</h2></div><span class="font-mono text-xs text-[var(--docs-muted)]">light / dark</span></div>
         <div class="mt-5 grid gap-3 lg:grid-cols-[0.8fr_1fr_1.15fr] lg:items-stretch"><div class="rounded-[var(--sanring-radius)] border border-[var(--docs-border)] bg-[var(--docs-surface)] p-4"><p class="m-0 font-mono text-[10px] uppercase tracking-[0.12em] text-[var(--docs-muted)]">RAW SCALE</p><div class="mt-4 flex gap-1.5"><span class="h-8 flex-1 rounded-[var(--sanring-radius-xs)] bg-[var(--docs-accent)]"></span><span class="h-8 flex-1 rounded-[var(--sanring-radius-xs)] bg-[var(--docs-accent-strong)]"></span><span class="h-8 flex-1 rounded-[var(--sanring-radius-xs)] bg-[var(--docs-fg)]"></span></div><p class="m-0 mt-3 font-mono text-xs text-[var(--docs-muted)]">primary-10 … primary-90</p></div><div class="rounded-[var(--sanring-radius)] border border-[var(--docs-border)] bg-[var(--docs-surface)] p-4"><p class="m-0 font-mono text-[10px] uppercase tracking-[0.12em] text-[var(--docs-muted)]">SEMANTIC MAP</p><div class="mt-3 grid gap-2 font-mono text-xs"><div class="flex justify-between gap-3"><span class="text-[var(--docs-muted)]">background</span><span class="text-[var(--docs-fg)]">neutral-90</span></div><div class="flex justify-between gap-3"><span class="text-[var(--docs-muted)]">primary</span><span class="text-[var(--docs-accent-strong)]">primary-50</span></div><div class="flex justify-between gap-3"><span class="text-[var(--docs-muted)]">border</span><span class="text-[var(--docs-fg)]">neutral-60</span></div></div></div><div class="rounded-[var(--sanring-radius)] bg-[var(--docs-code)] p-4 text-[var(--docs-code-fg)]"><div class="flex items-center justify-between gap-3"><p class="m-0 font-mono text-[10px] uppercase tracking-[0.12em] text-[var(--docs-accent)]">COMPONENT READS</p><span class="flex gap-1.5"><span class="size-2 rounded-full bg-[var(--docs-accent)]"></span><span class="size-2 rounded-full bg-[color-mix(in_srgb,var(--docs-code-fg)_35%,transparent)]"></span></span></div><div class="mt-4 rounded-[var(--sanring-radius)] border border-[color-mix(in_srgb,var(--docs-code-fg)_20%,transparent)] p-3"><div class="flex items-center justify-between"><span class="text-sm font-semibold">Button</span><span class="rounded-[var(--sanring-radius-xs)] bg-[var(--docs-accent)] px-2 py-1 text-xs text-[var(--docs-accent-fg)]">primary</span></div><div class="mt-3 h-2 rounded-full bg-[color-mix(in_srgb,var(--docs-code-fg)_16%,transparent)]"></div></div></div></div>
         <div class="mt-3 grid gap-3 sm:grid-cols-2"><div class="rounded-[var(--sanring-radius)] border border-[#d5dddd] bg-[#f5f8f8] p-4 text-[#172022]"><div class="flex items-center justify-between gap-3"><p class="m-0 font-mono text-[10px] font-semibold uppercase tracking-[0.12em]">LIGHT</p><span class="font-mono text-[10px] text-[#5d6b6d]">surface / ink / accent</span></div><div class="mt-4 flex items-center gap-3"><span class="size-8 rounded-full border border-[#d5dddd] bg-[#f5f8f8]"></span><span class="size-8 rounded-full bg-[#172022]"></span><span class="size-8 rounded-full bg-[#68c9d6]"></span><span class="font-mono text-xs text-[#5d6b6d]">same semantic roles</span></div></div><div class="rounded-[var(--sanring-radius)] border border-[#344244] bg-[#101617] p-4 text-[#e8f6f8]"><div class="flex items-center justify-between gap-3"><p class="m-0 font-mono text-[10px] font-semibold uppercase tracking-[0.12em]">DARK</p><span class="font-mono text-[10px] text-[#91a5a8]">surface / ink / accent</span></div><div class="mt-4 flex items-center gap-3"><span class="size-8 rounded-full border border-[#344244] bg-[#101617]"></span><span class="size-8 rounded-full bg-[#e8f6f8]"></span><span class="size-8 rounded-full bg-[#68c9d6]"></span><span class="font-mono text-xs text-[#91a5a8]">same semantic roles</span></div></div></div>
diff --git a/apps/docs/src/app/shell/header/feature-list.component.ts b/apps/docs/src/app/shell/header/feature-list.component.ts
index 0a67ab9..efa02e7 100644
--- a/apps/docs/src/app/shell/header/feature-list.component.ts
+++ b/apps/docs/src/app/shell/header/feature-list.component.ts
@@ -67,7 +67,7 @@ const MAX_SEARCH_RESULTS = 8;
               routerLink="/"
               sanringSheetClose
             >
-              <span class="grid size-10 shrink-0 place-items-center rounded-[var(--sanring-radius)] border border-[color-mix(in_srgb,var(--docs-accent)_36%,var(--docs-border))] bg-[color-mix(in_srgb,var(--docs-accent)_8%,var(--docs-surface))]">
+              <span class="docs-panel grid size-10 shrink-0 place-items-center">
                 <img class="size-6" src="sanring_ui.svg" alt="" />
               </span>
               <span class="min-w-0">
@@ -102,7 +102,7 @@ const MAX_SEARCH_RESULTS = 8;
       </sanring-sheet>
 
       <a
-        class="hidden min-w-0 items-center justify-self-start rounded-[var(--sanring-radius)] border border-[color-mix(in_srgb,var(--docs-accent)_36%,var(--docs-border))] bg-[color-mix(in_srgb,var(--docs-accent)_8%,var(--docs-surface))] px-3 py-2 no-underline transition-colors hover:bg-[color-mix(in_srgb,var(--docs-accent)_14%,var(--docs-elevated))] max-[860px]:order-2 max-[860px]:inline-flex"
+        class="docs-panel hidden min-w-0 items-center justify-self-start px-3 py-2 no-underline transition-colors hover:bg-[var(--docs-elevated)] max-[860px]:order-2 max-[860px]:inline-flex"
         routerLink="/"
         [attr.aria-label]="i18n.t('nav.home')"
       >
@@ -112,7 +112,7 @@ const MAX_SEARCH_RESULTS = 8;
       <div class="max-[860px]:order-4 max-[860px]:w-full max-[860px]:min-w-0">
         <button
           type="button"
-          class="flex h-10 w-[330px] items-center gap-2 rounded-[var(--sanring-radius)] border border-[color-mix(in_srgb,var(--docs-border)_86%,transparent)] bg-[color-mix(in_srgb,var(--docs-elevated)_82%,transparent)] px-3 text-sm text-[var(--docs-muted)] shadow-sm transition-colors hover:border-[color-mix(in_srgb,var(--docs-accent)_38%,var(--docs-border-strong))] hover:bg-[var(--docs-elevated)] max-[980px]:w-[min(46vw,300px)] max-[860px]:w-full"
+          class="docs-panel flex h-10 w-[330px] items-center gap-2 px-3 text-sm text-[var(--docs-muted)] transition-colors hover:bg-[var(--docs-elevated)] max-[980px]:w-[min(46vw,300px)] max-[860px]:w-full"
           (click)="commandDialog.open()"
         >
           <svg class="size-4 shrink-0" lucideSearch></svg>
@@ -175,12 +175,12 @@ const MAX_SEARCH_RESULTS = 8;
         </app-header-action-button>
 
         <div
-          class="relative inline-grid h-11 grid-cols-3 items-center gap-1.5 overflow-hidden rounded-[var(--sanring-radius)] border border-[color-mix(in_srgb,var(--docs-border)_86%,transparent)] bg-[color-mix(in_srgb,var(--docs-elevated)_82%,transparent)] p-1 shadow-sm"
+          class="docs-panel relative inline-grid h-11 grid-cols-3 items-center gap-1.5 overflow-hidden p-1"
           role="group"
           [attr.aria-label]="i18n.t('actions.selectTheme')"
         >
           <span
-            class="pointer-events-none absolute left-1 top-1 size-8 rounded-[var(--sanring-radius-sm)] bg-[var(--docs-panel)] shadow-sm ring-1 ring-[color-mix(in_srgb,var(--docs-border)_72%,transparent)] transition-transform duration-200 ease-out motion-reduce:transition-none"
+            class="pointer-events-none absolute left-1 top-1 size-8 rounded-[var(--sanring-radius-sm)] bg-[var(--docs-elevated)] transition-transform duration-200 ease-out motion-reduce:transition-none"
             [style.transform]="themeIndicatorTransform()"
             aria-hidden="true"
           ></span>
diff --git a/apps/docs/src/app/shell/header/header.component.ts b/apps/docs/src/app/shell/header/header.component.ts
index 6dfd9c0..f8bd9f5 100644
--- a/apps/docs/src/app/shell/header/header.component.ts
+++ b/apps/docs/src/app/shell/header/header.component.ts
@@ -7,7 +7,7 @@ import { MenuListComponent } from './menu-list.component';
   imports: [MenuListComponent, FeatureListComponent],
   template: `
     <header
-      class="sticky top-0 z-20 flex h-[76px] items-center justify-between border-b border-[color-mix(in_srgb,var(--docs-border)_78%,transparent)] bg-[color-mix(in_srgb,var(--docs-bg)_78%,transparent)] px-8 shadow-[var(--docs-shadow-soft)] backdrop-blur-2xl max-[860px]:h-auto max-[860px]:min-h-0 max-[860px]:flex-col max-[860px]:items-stretch max-[860px]:gap-3 max-[860px]:px-5 max-[860px]:py-4 max-[520px]:px-4 max-[520px]:py-3"
+      class="sticky top-0 z-20 flex h-[76px] items-center justify-between border-b border-[var(--docs-border)] bg-[var(--docs-bg)] px-8 max-[860px]:h-auto max-[860px]:min-h-0 max-[860px]:flex-col max-[860px]:items-stretch max-[860px]:gap-3 max-[860px]:px-5 max-[860px]:py-4 max-[520px]:px-4 max-[520px]:py-3"
     >
       <app-menu-list />
       <app-feature-list />
diff --git a/apps/docs/src/app/shell/header/menu-list.component.ts b/apps/docs/src/app/shell/header/menu-list.component.ts
index bfed949..2b838f8 100644
--- a/apps/docs/src/app/shell/header/menu-list.component.ts
+++ b/apps/docs/src/app/shell/header/menu-list.component.ts
@@ -9,7 +9,7 @@ import { menuItems, type MenuItem } from '../../navigation/menu-navigation';
   template: `
     <nav class="flex min-w-0 items-center gap-3 max-[860px]:hidden" aria-label="Primary">
       <a
-        class="mr-1 inline-flex size-11 flex-none items-center justify-center rounded-[var(--sanring-radius)] border border-[color-mix(in_srgb,var(--docs-accent)_40%,var(--docs-border))] bg-[color-mix(in_srgb,var(--docs-accent)_10%,var(--docs-surface))] shadow-sm transition-colors hover:border-[color-mix(in_srgb,var(--docs-accent)_66%,var(--docs-border))] hover:bg-[color-mix(in_srgb,var(--docs-accent)_16%,var(--docs-elevated))]"
+        class="docs-panel mr-1 inline-flex size-11 flex-none items-center justify-center transition-colors hover:bg-[var(--docs-elevated)]"
         routerLink="/"
         [attr.aria-label]="i18n.t('nav.home')"
       >
@@ -18,9 +18,9 @@ import { menuItems, type MenuItem } from '../../navigation/menu-navigation';
 
       @for (item of items; track item.labelKey) {
         <a
-          class="inline-flex justify-center whitespace-nowrap rounded-[var(--sanring-radius)] px-4 py-2 text-center text-[15px] font-medium text-[var(--docs-muted)] no-underline transition-colors hover:bg-[color-mix(in_srgb,var(--docs-elevated)_72%,transparent)] hover:text-[var(--docs-fg)] max-[980px]:hidden"
+          class="inline-flex justify-center whitespace-nowrap rounded-[var(--sanring-radius)] px-4 py-2 text-center text-[15px] font-medium text-[var(--docs-muted)] no-underline transition-colors hover:bg-[var(--docs-elevated)] hover:text-[var(--docs-fg)] max-[980px]:hidden"
           [routerLink]="item.path"
-          routerLinkActive="!bg-[var(--docs-elevated)] !text-[var(--docs-fg)] shadow-sm ring-1 ring-[color-mix(in_srgb,var(--docs-border)_70%,transparent)]"
+          routerLinkActive="!bg-[var(--docs-elevated)] !text-[var(--docs-fg)]"
           [routerLinkActiveOptions]="{ exact: item.exact }"
           [style.min-width.px]="itemMinWidth(item)"
         >
diff --git a/apps/docs/src/app/shell/sidebar/docs-section.component.ts b/apps/docs/src/app/shell/sidebar/docs-section.component.ts
index 2291bcf..d892601 100644
--- a/apps/docs/src/app/shell/sidebar/docs-section.component.ts
+++ b/apps/docs/src/app/shell/sidebar/docs-section.component.ts
@@ -12,27 +12,25 @@ import { I18nService } from '../../i18n/i18n.service';
   imports: [RouterLink, RouterLinkActive],
   template: `
     <section [class]="sectionClass">
-      <p class="mb-3 px-2 text-xs font-semibold uppercase tracking-[0.08em] text-[var(--docs-muted)]">{{ title }}</p>
+      <p class="docs-eyebrow mb-3 px-2">{{ title }}</p>
 
       @for (item of items; track item.labelKey) {
         @if (item.disabled) {
-          <a
-            class="my-1 flex min-h-10 w-full cursor-not-allowed items-center rounded-[var(--sanring-radius)] border border-transparent px-3 text-sm font-medium text-[color-mix(in_srgb,var(--docs-muted)_45%,transparent)] no-underline"
-          >
+          <a class="docs-nav-item is-disabled my-1">
             {{ i18n.t(item.labelKey) }}
           </a>
         } @else {
           <a
-            class="my-1 flex min-h-10 w-full items-center rounded-[var(--sanring-radius)] border border-transparent px-3 text-sm font-medium text-[var(--docs-muted)] no-underline transition-colors duration-200 ease-in-out hover:border-[color-mix(in_srgb,var(--docs-border)_82%,transparent)] hover:bg-[color-mix(in_srgb,var(--docs-elevated)_62%,transparent)] hover:text-[var(--docs-fg)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--docs-focus-ring)]"
+            class="docs-nav-item my-1"
             [routerLink]="item.path"
-            [routerLinkActive]="item.active ? 'border-[color-mix(in_srgb,var(--docs-accent)_34%,var(--docs-border))] bg-[var(--docs-active)] text-[var(--docs-fg)] shadow-sm' : ''"
+            [routerLinkActive]="item.active ? 'is-active' : ''"
             [routerLinkActiveOptions]="{ exact: item.exact ?? false }"
           >
             <span class="min-w-0 flex-1 truncate">{{ i18n.t(item.labelKey) }}</span>
             @if (item.badge) {
               <span class="sr-only">{{ i18n.t('home.components.newBadge') }}</span>
               <span
-                class="ml-2 size-2 shrink-0 rounded-full bg-[var(--docs-accent-strong)] shadow-[0_0_0_3px_color-mix(in_srgb,var(--docs-accent)_18%,transparent)]"
+                class="ml-2 size-1.5 shrink-0 rounded-full bg-[var(--docs-accent)]"
                 aria-hidden="true"
               ></span>
             }
diff --git a/apps/docs/src/app/shell/sidebar/docs-sidebar.component.ts b/apps/docs/src/app/shell/sidebar/docs-sidebar.component.ts
index 310515a..fbdc860 100644
--- a/apps/docs/src/app/shell/sidebar/docs-sidebar.component.ts
+++ b/apps/docs/src/app/shell/sidebar/docs-sidebar.component.ts
@@ -8,7 +8,7 @@ import { DocsSectionsListComponent } from './docs-sections-list.component';
   imports: [DocsSectionsListComponent, DocsComponentsListComponent],
   template: `
     <aside
-      class="docs-sidebar-scroll sticky top-[76px] hidden h-[calc(100dvh-76px)] overflow-auto border-r border-[color-mix(in_srgb,var(--docs-border)_76%,transparent)] bg-[color-mix(in_srgb,var(--docs-bg)_72%,transparent)] py-10 pl-[30px] pr-7 backdrop-blur-xl min-[861px]:block"
+      class="docs-sidebar-scroll sticky top-[76px] hidden h-[calc(100dvh-76px)] overflow-auto border-r border-[var(--docs-border)] bg-[var(--docs-bg)] py-10 pl-[30px] pr-7 min-[861px]:block"
     >
       <app-docs-sections-list />
       <app-docs-components-list />
@@ -19,13 +19,6 @@ import { DocsSectionsListComponent } from './docs-sections-list.component';
       .docs-sidebar-scroll {
         scrollbar-width: none;
         -ms-overflow-style: none;
-        mask-image: linear-gradient(
-          to bottom,
-          transparent 0,
-          #000 42px,
-          #000 calc(100% - 42px),
-          transparent 100%
-        );
       }
 
       .docs-sidebar-scroll::-webkit-scrollbar {
diff --git a/apps/docs/src/app/shell/toc/docs-toc.component.ts b/apps/docs/src/app/shell/toc/docs-toc.component.ts
index 568b45f..45ecdc7 100644
--- a/apps/docs/src/app/shell/toc/docs-toc.component.ts
+++ b/apps/docs/src/app/shell/toc/docs-toc.component.ts
@@ -11,13 +11,10 @@ const ACTIVE_VIEWPORT_RATIO = 0.32;
   selector: 'app-docs-toc',
   template: `
     <aside
-      class="sticky top-[76px] h-[calc(100dvh-76px)] overflow-auto bg-[color-mix(in_srgb,var(--docs-bg)_60%,transparent)] pb-12 pl-4 pr-8 pt-10 backdrop-blur-xl max-[1180px]:pr-5 max-[980px]:hidden"
+      class="sticky top-[76px] h-[calc(100dvh-76px)] overflow-auto bg-[var(--docs-bg)] pb-12 pl-4 pr-8 pt-10 max-[1180px]:pr-5 max-[980px]:hidden"
     >
-      <nav
-        class="mb-11 rounded-[var(--sanring-radius-lg)] border border-[color-mix(in_srgb,var(--docs-border)_72%,transparent)] bg-[color-mix(in_srgb,var(--docs-panel)_62%,transparent)] p-4 shadow-[var(--docs-shadow-soft)]"
-        [attr.aria-label]="i18n.t('toc.label')"
-      >
-        <p class="mb-4 text-xs font-semibold uppercase tracking-[0.08em] text-[var(--docs-muted)]">
+      <nav class="mb-11" [attr.aria-label]="i18n.t('toc.label')">
+        <p class="docs-eyebrow mb-3">
           {{ i18n.t('toc.label') }}
         </p>
         @for (item of items(); track item.id) {
@@ -73,20 +70,13 @@ export class DocsTocComponent {
   }
 
   protected itemClass(item: DocsTocItem) {
-    const active = this.activeId() === item.id;
     const indentClasses: Record<2 | 3 | 4, string> = {
-      2: 'px-2.5',
-      3: 'pl-5 pr-2.5',
-      4: 'pl-8 pr-2.5',
+      2: '',
+      3: 'level-3',
+      4: 'level-4',
     };
 
-    return [
-      'my-1 block rounded-[var(--sanring-radius)] border border-transparent py-1.5 text-sm no-underline transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--docs-focus-ring)]',
-      active
-        ? 'border-[color-mix(in_srgb,var(--docs-accent)_34%,var(--docs-border))] bg-[var(--docs-active)] text-[var(--docs-fg)] shadow-sm'
-        : 'text-[var(--docs-muted)] hover:bg-[color-mix(in_srgb,var(--docs-elevated)_62%,transparent)] hover:text-[var(--docs-fg)]',
-      indentClasses[item.level ?? 2],
-    ].join(' ');
+    return ['docs-toc-item', indentClasses[item.level ?? 2]].filter(Boolean).join(' ');
   }
 
   private activationLine(): number {
diff --git a/apps/docs/src/styles.css b/apps/docs/src/styles.css
index db6dfce..5da2e6e 100644
--- a/apps/docs/src/styles.css
+++ b/apps/docs/src/styles.css
@@ -22,7 +22,7 @@
 @import 'tailwindcss';
 
 @source "./app";
-@source "../../sanring/ui/src";
+@source "../../../packages/ui/src";
 
 @theme inline {
   /* 主色綁定 docs-accent，讓 light/dark 切換時 bg-primary 等 utility 跟著變動 */
@@ -432,17 +432,7 @@
   body {
     min-width: 320px;
     margin: 0;
-    background:
-      linear-gradient(180deg, color-mix(in srgb, var(--docs-panel) 42%, transparent) 0, transparent 360px),
-      linear-gradient(90deg, var(--docs-bg-grid) 1px, transparent 1px),
-      linear-gradient(180deg, var(--docs-bg-grid) 1px, transparent 1px),
-      var(--docs-bg);
-    background-attachment: fixed;
-    background-size:
-      auto,
-      56px 56px,
-      56px 56px,
-      auto;
+    background: var(--docs-bg);
     color: var(--docs-fg);
     font-family: var(--sanring-font-sans);
     text-rendering: optimizeLegibility;
@@ -471,13 +461,12 @@
   }
 
   /*
-    Custom scrollbar，顏色綁定 --docs-accent（主題色），跟著 light/dark 切換自動變色。
-    scrollbar-color 給 Firefox / 新版 Chromium；::-webkit-scrollbar-* 給 Safari / 舊版 Chromium。
-    設在 :root 讓所有 overflow 區塊（code block、TOC 等）預設繼承，個別元件仍可用更高特異度覆寫（如 sidebar 隱藏捲軸）。
+    Scrollbar uses border/muted, not accent — accent is for selection, not chrome.
+    scrollbar-color for Firefox / Chromium; ::-webkit-scrollbar-* for Safari.
   */
   :root {
     scrollbar-width: thin;
-    scrollbar-color: var(--docs-accent) transparent;
+    scrollbar-color: var(--docs-border-strong) transparent;
   }
 
   ::-webkit-scrollbar {
@@ -490,13 +479,127 @@
   }
 
   ::-webkit-scrollbar-thumb {
-    background-color: var(--docs-accent);
+    background-color: var(--docs-border-strong);
     border: 2px solid transparent;
     border-radius: 999px;
     background-clip: content-box;
   }
 
   ::-webkit-scrollbar-thumb:hover {
-    background-color: var(--docs-accent-strong);
+    background-color: var(--docs-muted);
+  }
+}
+
+/*
+  Shared docs chrome. Pages should use these instead of one-off color-mix /
+  shadow / gradient recipes. Hierarchy is border + surface, not glow.
+*/
+@layer components {
+  .docs-panel {
+    border: 1px solid var(--docs-border);
+    background: var(--docs-panel);
+    border-radius: var(--sanring-radius);
+  }
+
+  .docs-panel-lg {
+    border: 1px solid var(--docs-border);
+    background: var(--docs-panel);
+    border-radius: var(--sanring-radius-lg);
+  }
+
+  .docs-code-panel {
+    border: 1px solid var(--docs-border);
+    background: var(--docs-code);
+    color: var(--docs-code-fg);
+    border-radius: var(--sanring-radius-lg);
+  }
+
+  .docs-chip {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.375rem;
+    border: 1px solid var(--docs-border);
+    background: var(--docs-surface);
+    border-radius: var(--sanring-radius-sm);
+    padding: 0.25rem 0.5rem;
+    font-size: 0.75rem;
+    font-weight: 500;
+    color: var(--docs-muted);
+  }
+
+  .docs-eyebrow {
+    margin: 0;
+    font-size: 0.75rem;
+    font-weight: 600;
+    color: var(--docs-muted);
+  }
+
+  .docs-nav-item {
+    display: flex;
+    min-height: 2.5rem;
+    width: 100%;
+    align-items: center;
+    border-radius: var(--sanring-radius);
+    padding: 0 0.75rem;
+    font-size: 0.875rem;
+    font-weight: 500;
+    color: var(--docs-muted);
+    text-decoration: none;
+  }
+
+  .docs-nav-item:hover {
+    background: var(--docs-elevated);
+    color: var(--docs-fg);
+  }
+
+  .docs-nav-item:focus-visible {
+    outline: none;
+    box-shadow: 0 0 0 2px var(--docs-focus-ring);
+  }
+
+  .docs-nav-item.is-active {
+    background: var(--docs-active);
+    color: var(--docs-fg);
+  }
+
+  .docs-nav-item.is-disabled {
+    cursor: not-allowed;
+    color: color-mix(in srgb, var(--docs-muted) 45%, transparent);
+  }
+
+  .docs-nav-item.is-disabled:hover {
+    background: transparent;
+    color: color-mix(in srgb, var(--docs-muted) 45%, transparent);
+  }
+
+  .docs-toc-item {
+    display: block;
+    border-left: 2px solid transparent;
+    padding: 0.375rem 0 0.375rem 0.75rem;
+    font-size: 0.875rem;
+    color: var(--docs-muted);
+    text-decoration: none;
+  }
+
+  .docs-toc-item.level-3 {
+    padding-left: 1.5rem;
+  }
+
+  .docs-toc-item.level-4 {
+    padding-left: 2.25rem;
+  }
+
+  .docs-toc-item:hover,
+  .docs-toc-item[aria-current='location'] {
+    color: var(--docs-fg);
+  }
+
+  .docs-toc-item[aria-current='location'] {
+    border-left-color: var(--docs-accent);
+  }
+
+  .docs-toc-item:focus-visible {
+    outline: none;
+    box-shadow: 0 0 0 2px var(--docs-focus-ring);
   }
 }

From d0de5aaea03a78fbb84571055e2d249f5921bdf8 Mon Sep 17 00:00:00 2001
From: jack755051 <jack755051@gmail.com>
Date: Tue, 22 Sep 2026 13:18:39 +0800
Subject: [PATCH 10/13] fix(field): smooth floating label transition

Animate scale/position instead of swapping text sizes, and keep the
notch gradient present in both floated states so the background blends.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 packages/ui/src/lib/components/field/label.directive.ts | 8 +++++---
 registry/components/field/label.directive.ts            | 8 +++++---
 2 files changed, 10 insertions(+), 6 deletions(-)

diff --git a/packages/ui/src/lib/components/field/label.directive.ts b/packages/ui/src/lib/components/field/label.directive.ts
index 63cb2e4..29631ee 100644
--- a/packages/ui/src/lib/components/field/label.directive.ts
+++ b/packages/ui/src/lib/components/field/label.directive.ts
@@ -41,14 +41,16 @@ export class LabelDirective {
       // floating 模式：label 疊在 input 上方 (relative wrapper 由 field.component.ts 提供)，
       // 用 pointer-events-none 確保點擊一律落在 input 上，而不是被 label 攔截
       floating && [
-        'pointer-events-none absolute left-3 origin-left transition-all duration-150',
+        // 只過渡會插值的屬性：字級用 scale 而不是 text-sm→text-xs，避免重排字型造成頓點。
+        // 缺口色塊兩態都帶同一條 gradient，只改上半色，背景才接得上。
+        'pointer-events-none absolute left-3 origin-left px-[var(--sanring-field-label-padding-x,0.375rem)] transition-[top,translate,scale,color,background] duration-200 ease-[cubic-bezier(0.2,0,0,1)] motion-reduce:transition-none',
         this.isFloated()
           ? // top-0 -translate-y-1/2：不管字級多大，label 自己的垂直中心永遠精準卡在 border 線上，
             // 不需要量測高度。label 背景用上下雙色漸層：上半吃 input 外部背景，下半吃 input 內部背景。
             // 這能處理 Field 放在 card/panel/dialog 時，外部 surface 與 input surface 不同色的情況。
             // 若 input 被自訂成不同背景，可覆寫 --sanring-field-control-background；仍不需要 Angular 量測。
-            'top-0 -translate-y-1/2 bg-[linear-gradient(to_bottom,var(--sanring-field-label-background,var(--sanring-background))_50%,var(--sanring-field-control-background,var(--sanring-surface))_50%)] px-[var(--sanring-field-label-padding-x,0.375rem)] text-xs'
-          : 'top-1/2 -translate-y-1/2 text-sm text-[var(--sanring-muted)]',
+            'top-0 -translate-y-1/2 scale-[0.85] text-[var(--sanring-foreground)] bg-[linear-gradient(to_bottom,var(--sanring-field-label-background,var(--sanring-background))_50%,var(--sanring-field-control-background,var(--sanring-surface))_50%)]'
+          : 'top-1/2 -translate-y-1/2 scale-100 text-[var(--sanring-muted)] bg-[linear-gradient(to_bottom,var(--sanring-field-control-background,var(--sanring-surface))_50%,var(--sanring-field-control-background,var(--sanring-surface))_50%)]',
       ],
       // 有 Field 包裝時，精確依賴 control 狀態，不受 DOM 順序影響
       this.field?.isDisabled() && 'cursor-not-allowed opacity-70',
diff --git a/registry/components/field/label.directive.ts b/registry/components/field/label.directive.ts
index 854df7a..c27e77e 100644
--- a/registry/components/field/label.directive.ts
+++ b/registry/components/field/label.directive.ts
@@ -41,14 +41,16 @@ export class LabelDirective {
       // floating 模式：label 疊在 input 上方 (relative wrapper 由 field.component.ts 提供)，
       // 用 pointer-events-none 確保點擊一律落在 input 上，而不是被 label 攔截
       floating && [
-        'pointer-events-none absolute left-3 origin-left transition-all duration-150',
+        // 只過渡會插值的屬性：字級用 scale 而不是 text-sm→text-xs，避免重排字型造成頓點。
+        // 缺口色塊兩態都帶同一條 gradient，只改上半色，背景才接得上。
+        'pointer-events-none absolute left-3 origin-left px-[var(--sanring-field-label-padding-x,0.375rem)] transition-[top,translate,scale,color,background] duration-200 ease-[cubic-bezier(0.2,0,0,1)] motion-reduce:transition-none',
         this.isFloated()
           ? // top-0 -translate-y-1/2：不管字級多大，label 自己的垂直中心永遠精準卡在 border 線上，
             // 不需要量測高度。label 背景用上下雙色漸層：上半吃 input 外部背景，下半吃 input 內部背景。
             // 這能處理 Field 放在 card/panel/dialog 時，外部 surface 與 input surface 不同色的情況。
             // 若 input 被自訂成不同背景，可覆寫 --sanring-field-control-background；仍不需要 Angular 量測。
-            'top-0 -translate-y-1/2 bg-[linear-gradient(to_bottom,var(--sanring-field-label-background,var(--sanring-background))_50%,var(--sanring-field-control-background,var(--sanring-surface))_50%)] px-[var(--sanring-field-label-padding-x,0.375rem)] text-xs'
-          : 'top-1/2 -translate-y-1/2 text-sm text-[var(--sanring-muted)]',
+            'top-0 -translate-y-1/2 scale-[0.85] text-[var(--sanring-foreground)] bg-[linear-gradient(to_bottom,var(--sanring-field-label-background,var(--sanring-background))_50%,var(--sanring-field-control-background,var(--sanring-surface))_50%)]'
+          : 'top-1/2 -translate-y-1/2 scale-100 text-[var(--sanring-muted)] bg-[linear-gradient(to_bottom,var(--sanring-field-control-background,var(--sanring-surface))_50%,var(--sanring-field-control-background,var(--sanring-surface))_50%)]',
       ],
       // 有 Field 包裝時，精確依賴 control 狀態，不受 DOM 順序影響
       this.field?.isDisabled() && 'cursor-not-allowed opacity-70',

From a203334569317b2efd5147e481d4568a1594f5f2 Mon Sep 17 00:00:00 2001
From: jack755051 <jack755051@gmail.com>
Date: Tue, 22 Sep 2026 13:18:53 +0800
Subject: [PATCH 11/13] feat: align sibling APIs across six primitives (P32)

Ship sheet close/header align, radio size, a real dropdown submenu,
popover four-way side with aria fallback, transfer root disabled, and
table sticky opaque backgrounds plus docs recipes.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .changeset/p32-sibling-api-alignment.md       |   5 +
 ROADMAP.md                                    |  10 +-
 TODOLIST.md                                   |  14 +-
 .../locales/en/components/dropdown-menu.ts    |   6 +-
 .../app/i18n/locales/en/components/popover.ts |  10 +-
 .../app/i18n/locales/en/components/radio.ts   |   6 +
 .../app/i18n/locales/en/components/sheet.ts   |   5 +
 .../app/i18n/locales/en/components/table.ts   |   2 +
 .../i18n/locales/en/components/transfer.ts    |   7 +-
 .../locales/zh/components/dropdown-menu.ts    |   6 +-
 .../app/i18n/locales/zh/components/popover.ts |  10 +-
 .../app/i18n/locales/zh/components/radio.ts   |   6 +
 .../app/i18n/locales/zh/components/sheet.ts   |   4 +
 .../app/i18n/locales/zh/components/table.ts   |   2 +
 .../i18n/locales/zh/components/transfer.ts    |   7 +-
 .../pages/changelog/component-changelog.ts    |  30 ++++
 .../dropdown-menu-page.component.ts           |  66 +++-----
 .../dropdown-menu/dropdown-menu.docs.ts       |  53 +++---
 .../popover/popover-page.component.ts         |  24 +++
 .../pages/components/popover/popover.docs.ts  |  31 ++++
 .../components/radio/radio-page.component.ts  |  28 +++
 .../app/pages/components/radio/radio.docs.ts  |  32 ++++
 .../components/sheet/sheet-page.component.ts  |  50 +-----
 .../app/pages/components/sheet/sheet.docs.ts  |  33 ++--
 .../components/table/table-page.component.ts  | 159 +++++++++++++++++-
 .../app/pages/components/table/table.docs.ts  |  78 +++++++--
 .../transfer/transfer-page.component.ts       |  56 ++++++
 .../components/transfer/transfer.docs.ts      |  39 +++++
 .../ui/src/lib/components/component-styles.ts |   2 +
 .../dropdown-menu-sub-content.component.ts    | 103 ++++++++++++
 .../dropdown-menu-sub-trigger.component.ts    |  59 +++++++
 .../dropdown-menu-sub.component.ts            |  21 +++
 .../dropdown-menu-trigger.directive.ts        |   6 +-
 .../dropdown-menu.component.spec.ts           |  68 +++++++-
 .../src/lib/components/dropdown-menu/index.ts |   9 +
 .../popover/popover-content.component.ts      |  75 ++++++---
 .../popover/popover.component.spec.ts         |  51 +++++-
 .../lib/components/popover/popover.type.ts    |   1 +
 .../radio/radio-group.component.spec.ts       |  24 ++-
 .../components/radio/radio-group.component.ts |   3 +-
 .../components/radio/radio-item.component.ts  |  18 +-
 .../src/lib/components/radio/radio.styles.ts  |  14 +-
 .../src/lib/components/radio/radio.types.ts   |   1 +
 .../sheet/sheet-content.component.ts          |  27 ++-
 .../sheet/sheet-header.component.ts           |  13 +-
 .../components/sheet/sheet.component.spec.ts  |  80 ++++++++-
 .../lib/components/table/cell.directive.ts    |   8 +-
 .../table/table-container.component.ts        |   9 +-
 .../components/table/table.component.spec.ts  |  47 +++++-
 .../ui/src/lib/components/table/todolist.md   |   6 +-
 .../transfer/transfer-panel.component.ts      |   4 +-
 .../transfer/transfer.component.spec.ts       |  66 +++++++-
 .../components/transfer/transfer.component.ts |  22 ++-
 .../dropdown-menu-sub-content.component.ts    | 103 ++++++++++++
 .../dropdown-menu-sub-trigger.component.ts    |  59 +++++++
 .../dropdown-menu-sub.component.ts            |  21 +++
 .../dropdown-menu-trigger.directive.ts        |   6 +-
 registry/components/dropdown-menu/index.ts    |   9 +
 .../popover/popover-content.component.ts      |  87 ++++++----
 registry/components/popover/popover.type.ts   |   1 +
 .../components/radio/radio-group.component.ts |   5 +-
 .../components/radio/radio-item.component.ts  |  18 +-
 registry/components/radio/radio.styles.ts     |  14 +-
 registry/components/radio/radio.types.ts      |   1 +
 .../sheet/sheet-content.component.ts          |  27 ++-
 .../sheet/sheet-header.component.ts           |  13 +-
 registry/components/table/cell.directive.ts   |   8 +-
 .../table/table-container.component.ts        |   9 +-
 .../transfer/transfer-panel.component.ts      |   4 +-
 .../components/transfer/transfer.component.ts |  22 ++-
 registry/registry.json                        |   9 +-
 registry/shared/component-styles.ts           |   2 +
 72 files changed, 1658 insertions(+), 276 deletions(-)
 create mode 100644 .changeset/p32-sibling-api-alignment.md
 create mode 100644 packages/ui/src/lib/components/dropdown-menu/dropdown-menu-sub-content.component.ts
 create mode 100644 packages/ui/src/lib/components/dropdown-menu/dropdown-menu-sub-trigger.component.ts
 create mode 100644 packages/ui/src/lib/components/dropdown-menu/dropdown-menu-sub.component.ts
 create mode 100644 registry/components/dropdown-menu/dropdown-menu-sub-content.component.ts
 create mode 100644 registry/components/dropdown-menu/dropdown-menu-sub-trigger.component.ts
 create mode 100644 registry/components/dropdown-menu/dropdown-menu-sub.component.ts

diff --git a/.changeset/p32-sibling-api-alignment.md b/.changeset/p32-sibling-api-alignment.md
new file mode 100644
index 0000000..ae967d7
--- /dev/null
+++ b/.changeset/p32-sibling-api-alignment.md
@@ -0,0 +1,5 @@
+---
+'@sanring/cli': patch
+---
+
+Align sibling APIs on existing primitives: sheet close/header, radio size, a real dropdown submenu, popover side and aria fallback, transfer root disabled, and table sticky backgrounds.
diff --git a/ROADMAP.md b/ROADMAP.md
index fbeb681..9ab294b 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -10,14 +10,7 @@ This is a snapshot, not a commitment or a timeline. Items move, get reprioritize
 
 ## Component completeness
 
-Sibling alignment and advertised capabilities — not new primitives. Tracked as P32 in [`TODOLIST.md`](TODOLIST.md).
-
-- **Table** — sticky column background; docs recipes for loading skeleton rows and column show/hide
-- **Sheet** — built-in close control and header `align`, to match dialog
-- **Radio** — `size` variants aligned with checkbox / switch
-- **Dropdown menu** — a real nested submenu (docs keyboard table already describes it)
-- **Popover** — four-way `side` plus an accessible name when no title is projected
-- **Transfer** — root `disabled` and `ariaLabel`
+Optional leftover sibling gaps, still tracked as P32 in [`TODOLIST.md`](TODOLIST.md): combobox `ariaLabel`, select `required`, and toast `class` docs.
 
 ## Ecosystem / team use
 
@@ -26,6 +19,7 @@ Sibling alignment and advertised capabilities — not new primitives. Tracked as
 
 ## Recently shipped
 
+- P32 sibling alignment — sheet built-in close and header `align`, radio `size`, a real dropdown-menu submenu, popover four-way `side` plus aria fallback, transfer root `disabled`/`ariaLabel`, and table sticky backgrounds plus loading/column-visibility recipes
 - Blocks starter set — `sanring add block/login` (and `dashboard-shell`, `table-page`) installs a page-level template plus its component dependencies
 - Open in StackBlitz — each component docs previewer can open a minimal Angular 22 + Tailwind project with that example
 - GitHub registries — `--registry github:owner/repo` (optional `#ref` / `@ref`) expands to the raw `registry.json` at the repo root
diff --git a/TODOLIST.md b/TODOLIST.md
index 262a8b4..8a8a464 100644
--- a/TODOLIST.md
+++ b/TODOLIST.md
@@ -53,13 +53,13 @@
 
 ### 該做
 
-- [ ] **table sticky 欄背景**：`sticky`/`stickyEnd` 已能傳進 CDK，但 CDK 只加 `position: sticky` + 位移，沒有不透明背景；捲動時文字會透出來。細節與「刻意不做」的 `CdkTextColumn` / CDK flex-layout 見 [packages/ui/src/lib/components/table/todolist.md](packages/ui/src/lib/components/table/todolist.md)
-- [ ] **table docs 配方**（不寫新元件）：loading skeleton rows（既有 `skeleton`）；欄位顯隱（dropdown-menu + checkbox + 動態 `sanringRowDefColumns`）。同上 todolist「使用模式」節
-- [ ] **sheet 對齊 dialog**：dialog content 已有內建 `showClose` / `closeAriaLabel`，header 已有 `align`；sheet 還要自己放 `[sanringSheetClose]`，`sanring-sheet-header` 沒有 `align`
-- [ ] **radio `size`**：checkbox / switch / otp-input 有 sm/md/lg；radio 寫死 `RADIO_SIZE_CLASS = 'aspect-square h-4 w-4'`（`radio.styles.ts`）
-- [ ] **dropdown-menu 真 submenu**：docs 鍵盤表寫了左右鍵開關子選單，官網範例卻是 `mouseenter` 切兩欄，不是巢狀 `menu`。checkbox / radio 範例用打勾圖示組出來即可，不必先做成一等 primitive
-- [ ] **popover `side` + aria fallback**：tooltip / hover-card 已有四向 `side`；popover 只做上/下，而且沒投影 title 時仍綁死 `aria-labelledby`（`popover-content.component.ts`）
-- [ ] **transfer 根層 `disabled` + `ariaLabel`**：現在只能 disable 單一 item（`TransferItem.disabled`）；雙列表是沒名字的 `role="group"`
+- [x] **table sticky 欄背景**：`sticky`/`stickyEnd` 已能傳進 CDK，但 CDK 只加 `position: sticky` + 位移，沒有不透明背景；捲動時文字會透出來。細節與「刻意不做」的 `CdkTextColumn` / CDK flex-layout 見 [packages/ui/src/lib/components/table/todolist.md](packages/ui/src/lib/components/table/todolist.md)
+- [x] **table docs 配方**（不寫新元件）：loading skeleton rows（既有 `skeleton`）；欄位顯隱（dropdown-menu + checkbox + 動態 `sanringRowDefColumns`）。同上 todolist「使用模式」節
+- [x] **sheet 對齊 dialog**：dialog content 已有內建 `showClose` / `closeAriaLabel`，header 已有 `align`；sheet 還要自己放 `[sanringSheetClose]`，`sanring-sheet-header` 沒有 `align`
+- [x] **radio `size`**：checkbox / switch / otp-input 有 sm/md/lg；radio 寫死 `RADIO_SIZE_CLASS = 'aspect-square h-4 w-4'`（`radio.styles.ts`）
+- [x] **dropdown-menu 真 submenu**：docs 鍵盤表寫了左右鍵開關子選單，官網範例卻是 `mouseenter` 切兩欄，不是巢狀 `menu`。checkbox / radio 範例用打勾圖示組出來即可，不必先做成一等 primitive
+- [x] **popover `side` + aria fallback**：tooltip / hover-card 已有四向 `side`；popover 只做上/下，而且沒投影 title 時仍綁死 `aria-labelledby`（`popover-content.component.ts`）
+- [x] **transfer 根層 `disabled` + `ariaLabel`**：現在只能 disable 單一 item（`TransferItem.disabled`）；雙列表是沒名字的 `role="group"`
 
 ### 可選（有缺口，但已有組合路徑）
 
diff --git a/apps/docs/src/app/i18n/locales/en/components/dropdown-menu.ts b/apps/docs/src/app/i18n/locales/en/components/dropdown-menu.ts
index b23fc6d..efa1526 100644
--- a/apps/docs/src/app/i18n/locales/en/components/dropdown-menu.ts
+++ b/apps/docs/src/app/i18n/locales/en/components/dropdown-menu.ts
@@ -32,6 +32,10 @@ export const dropdownMenuTranslations = {
     'Controls item tone. Use destructive for actions that remove data or have serious consequences.',
   'dropdownMenu.api.class.description':
     'Additional classes merged with the corresponding dropdown menu primitive.',
+  'dropdownMenu.api.submenu.description':
+    'The nested menu to open, bound to the sub-content export (#ref="sanringDropdownMenuSubContent", then [submenu]="ref.menu"). Arrow Right opens it; Arrow Left closes it.',
+  'dropdownMenu.api.subTriggerValue.description':
+    'Required by the underlying ARIA menu item. Use a distinct value from sibling items.',
   'dropdownMenu.accessibility.description':
     "Built on @angular/aria/menu. The panel has role='menu'; each item has role='menuitem', role='menuitemcheckbox', or role='menuitemradio' as appropriate. The trigger button has aria-haspopup='menu' and aria-expanded managed by the underlying MenuTrigger directive.",
   'dropdownMenu.keyboard.description': 'Keyboard navigation follows the WAI-ARIA menu pattern.',
@@ -41,5 +45,5 @@ export const dropdownMenuTranslations = {
   'dropdownMenu.keyboard.openSubmenu': 'Open the focused submenu.',
   'dropdownMenu.keyboard.closeSubmenu': 'Close the active submenu.',
   'dropdownMenu.stateModel.description':
-    "Stateless. DropdownMenuItemDirective emits (itemSelected) on activation. DropdownMenuCheckboxItemComponent and DropdownMenuRadioGroupComponent manage their own checked/selected state via the checked input and checkedChange output. Open/closed state is managed internally by @angular/aria/menu.",
+    'Stateless. DropdownMenuItemDirective emits (itemSelected) on activation. Nest sanring-dropdown-menu-sub with a sub-trigger and sub-content for a real submenu. Checkbox and radio examples compose icons onto ordinary items. Open/closed state is managed internally by @angular/aria/menu.',
 } as const;
diff --git a/apps/docs/src/app/i18n/locales/en/components/popover.ts b/apps/docs/src/app/i18n/locales/en/components/popover.ts
index b27a896..2aa80d2 100644
--- a/apps/docs/src/app/i18n/locales/en/components/popover.ts
+++ b/apps/docs/src/app/i18n/locales/en/components/popover.ts
@@ -12,6 +12,14 @@ export const popoverTranslations = {
   'popover.examples.description':
     'Common popover patterns: alignment, user profile overlay, and form controls.',
   'popover.demo.align': 'Align',
+  'popover.demo.side': 'Side',
+  'popover.api.side.description':
+    "Preferred side of the trigger: 'top', 'right', 'bottom' (default), or 'left'. The panel flips if it would overflow the viewport.",
+  'popover.api.sideOffset.description': 'Distance in pixels between the trigger and the panel.',
+  'popover.api.ariaLabel.description':
+    'Accessible-name fallback used when no sanring-popover-title is projected and ariaLabelledBy is unset.',
+  'popover.api.ariaLabelledBy.description':
+    'Ids of external elements that label the panel. Takes precedence over PopoverTitle and ariaLabel.',
   'popover.demo.withHeader': 'With Header',
   'popover.demo.profile': 'User profile',
   'popover.demo.profileEmail': 'jane@example.com',
@@ -24,7 +32,7 @@ export const popoverTranslations = {
     "Alignment relative to the trigger: 'start', 'center' (default), or 'end'.",
   'popover.api.class.description': 'Additional classes merged onto the floating panel.',
   'popover.accessibility.description':
-    "The trigger button has aria-haspopup='dialog', aria-expanded, and aria-controls pointing to the panel id. The panel carries role='dialog'. Include sanringPopoverTitle or sanringPopoverDescription to have aria-labelledby and aria-describedby wired automatically.",
+    "The trigger button has aria-haspopup='dialog', aria-expanded, and aria-controls pointing to the panel id. The panel carries role='dialog'. Project sanring-popover-title to wire aria-labelledby, or set ariaLabel / ariaLabelledBy when the panel has no title.",
   'popover.keyboard.description': 'Focus moves into the panel when it opens.',
   'popover.keyboard.escape': 'Close the popover panel and return focus to the trigger.',
   'popover.keyboard.tab': 'Move focus to the next focusable element inside the panel.',
diff --git a/apps/docs/src/app/i18n/locales/en/components/radio.ts b/apps/docs/src/app/i18n/locales/en/components/radio.ts
index ae7b26e..4c706dd 100644
--- a/apps/docs/src/app/i18n/locales/en/components/radio.ts
+++ b/apps/docs/src/app/i18n/locales/en/components/radio.ts
@@ -9,6 +9,12 @@ export const radioTranslations = {
     'Common patterns including labeled items, horizontal layout, and disabled states.',
   'radio.demo.withLabel': 'With Labels',
   'radio.demo.horizontal': 'Horizontal',
+  'radio.demo.size': 'Size',
+  'radio.demo.size.sm': 'Small',
+  'radio.demo.size.md': 'Medium',
+  'radio.demo.size.lg': 'Large',
+  'radio.api.group.size':
+    'Control size inherited by every item in the group. Matches checkbox and switch: sm, md (default), or lg.',
   'radio.demo.disabled': 'Disabled',
   'radio.demo.field': 'With Field',
   'radio.demo.planFree': 'Free',
diff --git a/apps/docs/src/app/i18n/locales/en/components/sheet.ts b/apps/docs/src/app/i18n/locales/en/components/sheet.ts
index c8696af..25e14fa 100644
--- a/apps/docs/src/app/i18n/locales/en/components/sheet.ts
+++ b/apps/docs/src/app/i18n/locales/en/components/sheet.ts
@@ -28,6 +28,11 @@ export const sheetTranslations = {
   'sheet.api.isOpen.description': 'Controls the open state. Supports [(isOpen)] two-way binding.',
   'sheet.api.side.description':
     "Edge from which the panel slides in: 'top', 'right' (default), 'bottom', or 'left'.",
+  'sheet.api.showClose.description': 'Controls whether the built-in close button is rendered.',
+  'sheet.api.closeAriaLabel.description':
+    'Accessible name for the built-in close button. Defaults to 關閉面板.',
+  'sheet.api.headerAlign.description':
+    'Header text alignment. start is left, center is centered at every breakpoint. The default stays centered on small screens and left-aligned from sm up.',
   'sheet.demo.customClose': 'Custom Close Button',
   'sheet.demo.confirmDelete': 'Confirm deletion',
   'sheet.demo.confirmDeleteDescription': 'This action cannot be undone.',
diff --git a/apps/docs/src/app/i18n/locales/en/components/table.ts b/apps/docs/src/app/i18n/locales/en/components/table.ts
index dcddbc6..9fc06eb 100644
--- a/apps/docs/src/app/i18n/locales/en/components/table.ts
+++ b/apps/docs/src/app/i18n/locales/en/components/table.ts
@@ -10,6 +10,8 @@ export const tableTranslations = {
   'table.demo.sortable': 'Sortable headers',
   'table.demo.columnSizing': 'Column sizing',
   'table.demo.sticky': 'Sticky columns',
+  'table.demo.loading': 'Loading skeleton',
+  'table.demo.columnVisibility': 'Column visibility',
   'table.demo.empty': 'Empty state',
   'table.demo.selection': 'Row selection',
   'table.demo.actions': 'Actions menu',
diff --git a/apps/docs/src/app/i18n/locales/en/components/transfer.ts b/apps/docs/src/app/i18n/locales/en/components/transfer.ts
index cb49bda..0679fc3 100644
--- a/apps/docs/src/app/i18n/locales/en/components/transfer.ts
+++ b/apps/docs/src/app/i18n/locales/en/components/transfer.ts
@@ -16,6 +16,11 @@ export const transferTranslations = {
   'transfer.demo.moveToTarget': 'Move to selected',
   'transfer.demo.moveToSource': 'Move to available',
   'transfer.demo.disabled': 'Disabled items',
+  'transfer.demo.disabledGroup': 'Disabled group',
+  'transfer.api.disabled.description':
+    'Disables the whole control: items cannot be checked and neither panel can move items.',
+  'transfer.api.ariaLabel.description':
+    'Accessible name for the role="group" root. Use this so the dual list is announced as one control.',
   'transfer.demo.headerCount': 'Header with live count',
   'transfer.demo.customActions': 'Custom action buttons',
   'transfer.demo.oneWay': 'One-way transfer',
@@ -57,7 +62,7 @@ export const transferTranslations = {
   'transfer.api.pageNav.description':
     'Move to the next/previous page. No-ops past either end of the range.',
   'transfer.api.interactive.description':
-    'False for a target panel in one-way mode; used internally to disable its checkboxes.',
+    'False when the root is disabled, or for a target panel in one-way mode; used to disable that panel’s checkboxes.',
   'transfer.api.selectableItems.description':
     'Non-disabled items across the full filtered list (not limited to the current page). Useful for displaying a count in the header.',
   'transfer.api.selectAllChecked.description':
diff --git a/apps/docs/src/app/i18n/locales/zh/components/dropdown-menu.ts b/apps/docs/src/app/i18n/locales/zh/components/dropdown-menu.ts
index 6618933..2c66d09 100644
--- a/apps/docs/src/app/i18n/locales/zh/components/dropdown-menu.ts
+++ b/apps/docs/src/app/i18n/locales/zh/components/dropdown-menu.ts
@@ -26,6 +26,10 @@ export const dropdownMenuTranslations = {
   'dropdownMenu.api.variant.description':
     '控制 item 語氣；移除資料或高風險操作可使用 destructive。',
   'dropdownMenu.api.class.description': '與對應 dropdown menu primitive 樣式合併的額外 class。',
+  'dropdownMenu.api.submenu.description':
+    '要開啟的巢狀選單，綁定到 sub-content 匯出的參照（#ref="sanringDropdownMenuSubContent"，再用 [submenu]="ref.menu"）。右方向鍵開啟，左方向鍵關閉。',
+  'dropdownMenu.api.subTriggerValue.description':
+    '底層 ARIA menu item 要求必填。請與同層其他 item 使用不同的 value。',
   'dropdownMenu.accessibility.description':
     "基於 @angular/aria/menu 構建。面板有 role='menu'，每個 item 依情況有 role='menuitem'、role='menuitemcheckbox' 或 role='menuitemradio'。trigger 按鈕的 aria-haspopup='menu' 與 aria-expanded 由底層 MenuTrigger 指令管理。",
   'dropdownMenu.keyboard.description': '鍵盤導覽遵循 WAI-ARIA menu 模式。',
@@ -35,5 +39,5 @@ export const dropdownMenuTranslations = {
   'dropdownMenu.keyboard.openSubmenu': '開啟聚焦的子選單。',
   'dropdownMenu.keyboard.closeSubmenu': '關閉目前的子選單。',
   'dropdownMenu.stateModel.description':
-    "無狀態。DropdownMenuItemDirective 啟動時送出 (itemSelected)。DropdownMenuCheckboxItemComponent 和 DropdownMenuRadioGroupComponent 透過 checked input 和 checkedChange output 自行管理選取狀態。開啟/關閉狀態由 @angular/aria/menu 內部管理。",
+    '無狀態。DropdownMenuItemDirective 啟動時送出 (itemSelected)。巢狀子選單用 sanring-dropdown-menu-sub 搭配 sub-trigger 與 sub-content。Checkbox / radio 範例是在一般 item 上組合圖示。開啟/關閉狀態由 @angular/aria/menu 內部管理。',
 } as const;
diff --git a/apps/docs/src/app/i18n/locales/zh/components/popover.ts b/apps/docs/src/app/i18n/locales/zh/components/popover.ts
index 2e65e1b..05fe573 100644
--- a/apps/docs/src/app/i18n/locales/zh/components/popover.ts
+++ b/apps/docs/src/app/i18n/locales/zh/components/popover.ts
@@ -10,6 +10,14 @@ export const popoverTranslations = {
     'Popover 由根節點、trigger 指令與內容面板組合，面板可選用 header、title、description 子元件。',
   'popover.examples.description': '常見 popover 模式：對齊方式、使用者資料卡片與表單控制項。',
   'popover.demo.align': '對齊',
+  'popover.demo.side': '方向',
+  'popover.api.side.description':
+    "偏好出現在 trigger 的哪一側：'top'、'right'、'bottom'（預設）或 'left'。會超出視窗時自動翻面。",
+  'popover.api.sideOffset.description': 'trigger 與面板之間的間距（像素）。',
+  'popover.api.ariaLabel.description':
+    '未投影 sanring-popover-title、也未設定 ariaLabelledBy 時的 accessible name fallback。',
+  'popover.api.ariaLabelledBy.description':
+    '標示面板的外部元素 id，優先於 PopoverTitle 與 ariaLabel。',
   'popover.demo.withHeader': '含 Header',
   'popover.demo.profile': '使用者資料',
   'popover.demo.profileEmail': 'jane@example.com',
@@ -20,7 +28,7 @@ export const popoverTranslations = {
   'popover.api.align.description': "相對於 trigger 的對齊方式：'start'、'center'（預設）或 'end'。",
   'popover.api.class.description': '合併到浮動面板的額外 class。',
   'popover.accessibility.description':
-    "trigger 按鈕有 aria-haspopup='dialog'、aria-expanded 及指向面板 id 的 aria-controls。面板本身帶有 role='dialog'。加入 sanringPopoverTitle 或 sanringPopoverDescription，即可自動綁定 aria-labelledby 和 aria-describedby。",
+    "trigger 按鈕有 aria-haspopup='dialog'、aria-expanded 及指向面板 id 的 aria-controls。面板本身帶有 role='dialog'。投影 sanring-popover-title 會綁上 aria-labelledby；沒有 title 時改設 ariaLabel 或 ariaLabelledBy。",
   'popover.keyboard.description': 'Popover 開啟時，焦點會移入面板。',
   'popover.keyboard.escape': '關閉 popover 面板，焦點返回 trigger。',
   'popover.keyboard.tab': '移動焦點到面板內的下一個可聚焦元素。',
diff --git a/apps/docs/src/app/i18n/locales/zh/components/radio.ts b/apps/docs/src/app/i18n/locales/zh/components/radio.ts
index 47e9166..e0e7048 100644
--- a/apps/docs/src/app/i18n/locales/zh/components/radio.ts
+++ b/apps/docs/src/app/i18n/locales/zh/components/radio.ts
@@ -8,6 +8,12 @@ export const radioTranslations = {
   'radio.examples.description': '常見模式，包含搭配標籤、水平排列與停用狀態。',
   'radio.demo.withLabel': '搭配標籤',
   'radio.demo.horizontal': '水平排列',
+  'radio.demo.size': '尺寸',
+  'radio.demo.size.sm': '小',
+  'radio.demo.size.md': '中',
+  'radio.demo.size.lg': '大',
+  'radio.api.group.size':
+    '套用到群組內每個選項的尺寸，與 checkbox / switch 對齊：sm、md（預設）或 lg。',
   'radio.demo.disabled': '停用',
   'radio.demo.field': '搭配 Field',
   'radio.demo.planFree': '免費方案',
diff --git a/apps/docs/src/app/i18n/locales/zh/components/sheet.ts b/apps/docs/src/app/i18n/locales/zh/components/sheet.ts
index 1abe0f2..3bcac64 100644
--- a/apps/docs/src/app/i18n/locales/zh/components/sheet.ts
+++ b/apps/docs/src/app/i18n/locales/zh/components/sheet.ts
@@ -25,6 +25,10 @@ export const sheetTranslations = {
   'sheet.api.description': 'sheet primitives 支援的 inputs 與 outputs。',
   'sheet.api.isOpen.description': '控制開啟狀態，支援 [(isOpen)] 雙向綁定。',
   'sheet.api.side.description': "面板滑入的邊緣：'top'、'right'（預設）、'bottom' 或 'left'。",
+  'sheet.api.showClose.description': '是否渲染內建關閉按鈕。',
+  'sheet.api.closeAriaLabel.description': '內建關閉按鈕的 accessible name，預設為「關閉面板」。',
+  'sheet.api.headerAlign.description':
+    '標題列對齊。start 靠左，center 在所有斷點置中。預設在小螢幕置中，sm 以上靠左。',
   'sheet.demo.customClose': '自訂關閉按鈕',
   'sheet.demo.confirmDelete': '確認刪除',
   'sheet.demo.confirmDeleteDescription': '此操作無法復原。',
diff --git a/apps/docs/src/app/i18n/locales/zh/components/table.ts b/apps/docs/src/app/i18n/locales/zh/components/table.ts
index 5d58f0d..da333c7 100644
--- a/apps/docs/src/app/i18n/locales/zh/components/table.ts
+++ b/apps/docs/src/app/i18n/locales/zh/components/table.ts
@@ -10,6 +10,8 @@ export const tableTranslations = {
   'table.demo.sortable': '可排序表頭',
   'table.demo.columnSizing': '欄位比例',
   'table.demo.sticky': 'Sticky 欄位',
+  'table.demo.loading': '載入骨架列',
+  'table.demo.columnVisibility': '欄位顯隱',
   'table.demo.empty': '空資料狀態',
   'table.demo.selection': '列選取',
   'table.demo.actions': '操作選單',
diff --git a/apps/docs/src/app/i18n/locales/zh/components/transfer.ts b/apps/docs/src/app/i18n/locales/zh/components/transfer.ts
index a11cd2a..5def5d4 100644
--- a/apps/docs/src/app/i18n/locales/zh/components/transfer.ts
+++ b/apps/docs/src/app/i18n/locales/zh/components/transfer.ts
@@ -15,6 +15,11 @@ export const transferTranslations = {
   'transfer.demo.moveToTarget': '移到已選項目',
   'transfer.demo.moveToSource': '移到可選項目',
   'transfer.demo.disabled': '停用項目',
+  'transfer.demo.disabledGroup': '整組停用',
+  'transfer.api.disabled.description':
+    '停用整個控制項：項目無法勾選，兩側也都不能移動。',
+  'transfer.api.ariaLabel.description':
+    '給 role="group" 根節點的 accessible name，讓雙列表被讀成同一個控制項。',
   'transfer.demo.headerCount': '標題列即時筆數',
   'transfer.demo.customActions': '自訂操作按鈕',
   'transfer.demo.oneWay': '單向穿梭',
@@ -52,7 +57,7 @@ export const transferTranslations = {
     '面板目前的頁碼（從 0 開始）與依 pageSize、目前篩選條件算出的總頁數。',
   'transfer.api.pageNav.description': '切換到下一頁／上一頁，超出範圍時不會有作用。',
   'transfer.api.interactive.description':
-    'one-way 模式下的 target 面板會是 false，內部用來停用它的 checkbox。',
+    '根層停用，或 one-way 模式下的 target 面板時為 false，用來停用該面板的 checkbox。',
   'transfer.api.selectableItems.description':
     '過濾後的完整清單中所有非 disabled 的項目（不受分頁限制）。適合在標題列顯示可選數量。',
   'transfer.api.selectAllChecked.description':
diff --git a/apps/docs/src/app/pages/changelog/component-changelog.ts b/apps/docs/src/app/pages/changelog/component-changelog.ts
index 1d2a7de..8e80ced 100644
--- a/apps/docs/src/app/pages/changelog/component-changelog.ts
+++ b/apps/docs/src/app/pages/changelog/component-changelog.ts
@@ -64,6 +64,36 @@ export const cliVersionChangelog: readonly CliVersionEntry[] = [
         componentIds: ['field'],
         text: '`sanring-field` now projects `textarea[sanringTextarea]` into the control slot, so a character-count description renders below the textarea instead of above it.',
       },
+      {
+        type: 'added',
+        componentIds: ['sheet'],
+        text: '`sanring-sheet-content` renders a built-in close button (`showClose`, `closeAriaLabel`). `sanring-sheet-header` accepts `align` (`start` | `center`).',
+      },
+      {
+        type: 'added',
+        componentIds: ['radio'],
+        text: '`sanring-radio-group` accepts `size` (`sm` | `md` | `lg`), matching checkbox and switch.',
+      },
+      {
+        type: 'added',
+        componentIds: ['dropdown-menu'],
+        text: '`sanring-dropdown-menu-sub`, `sanring-dropdown-menu-sub-trigger`, and `sanring-dropdown-menu-sub-content` open a nested menu with Arrow Right / Arrow Left.',
+      },
+      {
+        type: 'added',
+        componentIds: ['popover'],
+        text: '`sanring-popover-content` accepts four-way `side` and only sets `aria-labelledby` when a title is projected; `ariaLabel` is the fallback.',
+      },
+      {
+        type: 'added',
+        componentIds: ['transfer'],
+        text: '`sanring-transfer` accepts root `disabled` and `ariaLabel` on the `role="group"` host.',
+      },
+      {
+        type: 'changed',
+        componentIds: ['table'],
+        text: 'Sticky header, body, and footer cells use an opaque `--sanring-background` so scrolled text does not show through. Docs add loading skeleton and column-visibility recipes.',
+      },
     ],
   },
   {
diff --git a/apps/docs/src/app/pages/components/dropdown-menu/dropdown-menu-page.component.ts b/apps/docs/src/app/pages/components/dropdown-menu/dropdown-menu-page.component.ts
index f4a7fe9..311bd22 100644
--- a/apps/docs/src/app/pages/components/dropdown-menu/dropdown-menu-page.component.ts
+++ b/apps/docs/src/app/pages/components/dropdown-menu/dropdown-menu-page.component.ts
@@ -1,7 +1,6 @@
 import { Component, inject } from '@angular/core';
 import {
   LucideCheck,
-  LucideChevronRight,
   LucideCircle,
   LucideEllipsis,
   LucideFile,
@@ -30,7 +29,6 @@ import { dropdownMenuPage, dropdownMenuPageExamples } from './dropdown-menu.docs
     ButtonDirective,
     SANRING_DROPDOWN_MENU_IMPORTS,
     LucideCheck,
-    LucideChevronRight,
     LucideCircle,
     LucideEllipsis,
     LucideFile,
@@ -202,55 +200,46 @@ import { dropdownMenuPage, dropdownMenuPageExamples } from './dropdown-menu.docs
 
                   <sanring-dropdown-menu-content
                     #fileMenu="sanringDropdownMenuContent"
-                    class="grid w-[420px] grid-cols-[180px_1fr] gap-1"
+                    class="w-56"
                     (itemSelected)="onFileAction($event)"
                   >
-                    <div>
-                      <sanring-dropdown-menu-label>File</sanring-dropdown-menu-label>
-                      <button
-                        sanringDropdownMenuItem
-                        type="button"
-                        value="share"
-                        (mouseenter)="submenu = 'share'"
-                      >
-                        <span class="flex-1 text-left">Share</span>
-                        <svg lucideChevronRight class="size-4"></svg>
-                      </button>
-                      <button
-                        sanringDropdownMenuItem
-                        type="button"
-                        value="export"
-                        (mouseenter)="submenu = 'export'"
+                    <sanring-dropdown-menu-label>File</sanring-dropdown-menu-label>
+                    <sanring-dropdown-menu-sub>
+                      <sanring-dropdown-menu-sub-trigger value="share" [submenu]="shareMenu.menu">
+                        Share
+                      </sanring-dropdown-menu-sub-trigger>
+                      <sanring-dropdown-menu-sub-content
+                        #shareMenu="sanringDropdownMenuSubContent"
+                        class="w-48"
                       >
-                        <span class="flex-1 text-left">Export</span>
-                        <svg lucideChevronRight class="size-4"></svg>
-                      </button>
-                      <sanring-dropdown-menu-separator />
-                      <button sanringDropdownMenuItem type="button" value="close-file">
-                        Close file
-                      </button>
-                    </div>
-
-                    <div class="border-l border-[var(--sanring-border)] pl-1">
-                      <sanring-dropdown-menu-label>
-                        {{ submenu === 'share' ? 'Share' : 'Export' }}
-                      </sanring-dropdown-menu-label>
-                      @if (submenu === 'share') {
                         <button sanringDropdownMenuItem type="button" value="copy-link">
                           Copy link
                         </button>
                         <button sanringDropdownMenuItem type="button" value="invite-people">
                           Invite people
                         </button>
-                      } @else {
+                      </sanring-dropdown-menu-sub-content>
+                    </sanring-dropdown-menu-sub>
+                    <sanring-dropdown-menu-sub>
+                      <sanring-dropdown-menu-sub-trigger value="export" [submenu]="exportMenu.menu">
+                        Export
+                      </sanring-dropdown-menu-sub-trigger>
+                      <sanring-dropdown-menu-sub-content
+                        #exportMenu="sanringDropdownMenuSubContent"
+                        class="w-48"
+                      >
                         <button sanringDropdownMenuItem type="button" value="export-pdf">
                           PDF
                         </button>
                         <button sanringDropdownMenuItem type="button" value="export-markdown">
                           Markdown
                         </button>
-                      }
-                    </div>
+                      </sanring-dropdown-menu-sub-content>
+                    </sanring-dropdown-menu-sub>
+                    <sanring-dropdown-menu-separator />
+                    <button sanringDropdownMenuItem type="button" value="close-file">
+                      Close file
+                    </button>
                   </sanring-dropdown-menu-content>
                 </sanring-dropdown-menu>
               </div>
@@ -318,7 +307,6 @@ export class DropdownMenuPageComponent {
   protected showStatusBar = true;
   protected showActivityBar = false;
   protected density: 'compact' | 'comfortable' = 'comfortable';
-  protected submenu: 'share' | 'export' = 'share';
 
   protected section(id: string) {
     return getComponentPageSection(this.page, id);
@@ -337,7 +325,5 @@ export class DropdownMenuPageComponent {
     if (value === 'compact' || value === 'comfortable') this.density = value;
   }
 
-  protected onFileAction(value: unknown): void {
-    if (value === 'share' || value === 'export') this.submenu = value;
-  }
+  protected onFileAction(_value: unknown): void {}
 }
diff --git a/apps/docs/src/app/pages/components/dropdown-menu/dropdown-menu.docs.ts b/apps/docs/src/app/pages/components/dropdown-menu/dropdown-menu.docs.ts
index 7e71bff..847d147 100644
--- a/apps/docs/src/app/pages/components/dropdown-menu/dropdown-menu.docs.ts
+++ b/apps/docs/src/app/pages/components/dropdown-menu/dropdown-menu.docs.ts
@@ -136,6 +136,18 @@ export const dropdownMenuPage = {
       defaultValue: 'undefined',
       descriptionKey: 'dropdownMenu.api.class.description',
     },
+    {
+      property: 'DropdownMenuSubTriggerComponent.submenu',
+      type: 'Menu | undefined',
+      defaultValue: 'required',
+      descriptionKey: 'dropdownMenu.api.submenu.description',
+    },
+    {
+      property: 'DropdownMenuSubTriggerComponent.value',
+      type: 'unknown',
+      defaultValue: 'required',
+      descriptionKey: 'dropdownMenu.api.subTriggerValue.description',
+    },
   ] satisfies readonly ComponentPageApiRow[],
   keyboardRows: [
     { keys: 'Enter / Space', descriptionKey: 'dropdownMenu.keyboard.openTrigger' },
@@ -259,35 +271,30 @@ export class ExampleComponent {}`,
 
   <sanring-dropdown-menu-content
     #fileMenu="sanringDropdownMenuContent"
-    class="grid w-[420px] grid-cols-[180px_1fr] gap-1"
+    class="w-56"
     (itemSelected)="onFileAction($event)"
   >
-    <div>
-      <sanring-dropdown-menu-label>File</sanring-dropdown-menu-label>
-      <button sanringDropdownMenuItem type="button" value="share" (mouseenter)="submenu = 'share'">
-        <span class="flex-1 text-left">Share</span>
-        <svg lucideChevronRight class="size-4"></svg>
-      </button>
-      <button sanringDropdownMenuItem type="button" value="export" (mouseenter)="submenu = 'export'">
-        <span class="flex-1 text-left">Export</span>
-        <svg lucideChevronRight class="size-4"></svg>
-      </button>
-      <sanring-dropdown-menu-separator />
-      <button sanringDropdownMenuItem type="button" value="close-file">Close file</button>
-    </div>
-
-    <div class="border-l border-[var(--sanring-border)] pl-1">
-      <sanring-dropdown-menu-label>
-        {{ submenu === 'share' ? 'Share' : 'Export' }}
-      </sanring-dropdown-menu-label>
-      @if (submenu === 'share') {
+    <sanring-dropdown-menu-label>File</sanring-dropdown-menu-label>
+    <sanring-dropdown-menu-sub>
+      <sanring-dropdown-menu-sub-trigger value="share" [submenu]="shareMenu.menu">
+        Share
+      </sanring-dropdown-menu-sub-trigger>
+      <sanring-dropdown-menu-sub-content #shareMenu="sanringDropdownMenuSubContent" class="w-48">
         <button sanringDropdownMenuItem type="button" value="copy-link">Copy link</button>
         <button sanringDropdownMenuItem type="button" value="invite-people">Invite people</button>
-      } @else {
+      </sanring-dropdown-menu-sub-content>
+    </sanring-dropdown-menu-sub>
+    <sanring-dropdown-menu-sub>
+      <sanring-dropdown-menu-sub-trigger value="export" [submenu]="exportMenu.menu">
+        Export
+      </sanring-dropdown-menu-sub-trigger>
+      <sanring-dropdown-menu-sub-content #exportMenu="sanringDropdownMenuSubContent" class="w-48">
         <button sanringDropdownMenuItem type="button" value="export-pdf">PDF</button>
         <button sanringDropdownMenuItem type="button" value="export-markdown">Markdown</button>
-      }
-    </div>
+      </sanring-dropdown-menu-sub-content>
+    </sanring-dropdown-menu-sub>
+    <sanring-dropdown-menu-separator />
+    <button sanringDropdownMenuItem type="button" value="close-file">Close file</button>
   </sanring-dropdown-menu-content>
 </sanring-dropdown-menu>`,
   withIcons: `<sanring-dropdown-menu>
diff --git a/apps/docs/src/app/pages/components/popover/popover-page.component.ts b/apps/docs/src/app/pages/components/popover/popover-page.component.ts
index 4e8fb91..19f398b 100644
--- a/apps/docs/src/app/pages/components/popover/popover-page.component.ts
+++ b/apps/docs/src/app/pages/components/popover/popover-page.component.ts
@@ -114,6 +114,29 @@ import { popoverPage, popoverPageExamples } from './popover.docs';
             </app-component-page-code-previewer>
           </app-component-page-section>
 
+          <app-component-page-section [section]="section('example-side')">
+            <app-component-page-code-previewer [code]="examples.side" language="angular-html">
+              <div
+                previewer
+                class="flex min-h-[220px] flex-wrap items-center justify-center gap-3"
+              >
+                @for (side of sides; track side) {
+                  <sanring-popover>
+                    <button sanringBtn size="sm" variant="outline" sanringPopoverTrigger>
+                      {{ side }}
+                    </button>
+                    <sanring-popover-content [side]="side" [ariaLabel]="'Side: ' + side">
+                      <p class="m-0 text-sm font-medium">Side: {{ side }}</p>
+                      <p class="m-0 mt-1 text-xs text-[var(--docs-muted)]">
+                        Flips when it would overflow.
+                      </p>
+                    </sanring-popover-content>
+                  </sanring-popover>
+                }
+              </div>
+            </app-component-page-code-previewer>
+          </app-component-page-section>
+
           <!-- With Header (profile card) -->
           <app-component-page-section [section]="section('example-with-header')">
             <app-component-page-code-previewer [code]="examples.withHeader" language="angular-html">
@@ -162,6 +185,7 @@ export class PopoverPageComponent {
   protected readonly i18n = inject(I18nService);
 
   protected readonly aligns = ['start', 'center', 'end'] as const;
+  protected readonly sides = ['top', 'right', 'bottom', 'left'] as const;
 
   protected section(id: string) {
     return getComponentPageSection(this.page, id);
diff --git a/apps/docs/src/app/pages/components/popover/popover.docs.ts b/apps/docs/src/app/pages/components/popover/popover.docs.ts
index a0bf22e..0b5a146 100644
--- a/apps/docs/src/app/pages/components/popover/popover.docs.ts
+++ b/apps/docs/src/app/pages/components/popover/popover.docs.ts
@@ -36,6 +36,7 @@ export const popoverPage = {
       level: 2,
       children: [
         { id: 'example-align', titleKey: 'popover.demo.align', level: 3 },
+        { id: 'example-side', titleKey: 'popover.demo.side', level: 3 },
         { id: 'example-with-header', titleKey: 'popover.demo.withHeader', level: 3 },
       ],
     },
@@ -77,6 +78,30 @@ export const popoverPage = {
       defaultValue: "'center'",
       descriptionKey: 'popover.api.align.description',
     },
+    {
+      property: 'side',
+      type: "'top' | 'right' | 'bottom' | 'left'",
+      defaultValue: "'bottom'",
+      descriptionKey: 'popover.api.side.description',
+    },
+    {
+      property: 'sideOffset',
+      type: 'number',
+      defaultValue: '8',
+      descriptionKey: 'popover.api.sideOffset.description',
+    },
+    {
+      property: 'ariaLabel',
+      type: 'string',
+      defaultValue: 'undefined',
+      descriptionKey: 'popover.api.ariaLabel.description',
+    },
+    {
+      property: 'ariaLabelledBy',
+      type: 'string',
+      defaultValue: 'undefined',
+      descriptionKey: 'popover.api.ariaLabelledBy.description',
+    },
     {
       property: 'class',
       type: 'string',
@@ -150,6 +175,12 @@ export class ExampleComponent {}`,
 <sanring-popover align="center">…</sanring-popover>
 <sanring-popover align="end">…</sanring-popover>`,
 
+  side: `<!-- side prefers a direction; the panel flips if it would overflow -->
+<sanring-popover-content side="top">…</sanring-popover-content>
+<sanring-popover-content side="right">…</sanring-popover-content>
+<sanring-popover-content side="bottom">…</sanring-popover-content>
+<sanring-popover-content side="left" ariaLabel="Filters">…</sanring-popover-content>`,
+
   withHeader: `<sanring-popover>
   <button sanringBtn variant="outline" sanringPopoverTrigger>
     Jane Appleseed
diff --git a/apps/docs/src/app/pages/components/radio/radio-page.component.ts b/apps/docs/src/app/pages/components/radio/radio-page.component.ts
index 30b76c2..9fab5d7 100644
--- a/apps/docs/src/app/pages/components/radio/radio-page.component.ts
+++ b/apps/docs/src/app/pages/components/radio/radio-page.component.ts
@@ -108,6 +108,31 @@ import { radioGroupApiRows, radioItemApiRows, radioPage, radioPageExamples } fro
             </app-component-page-code-previewer>
           </app-component-page-section>
 
+          <app-component-page-section [section]="section('example-size')">
+            <app-component-page-code-previewer [code]="examples.size" language="angular-html">
+              <div previewer class="flex flex-wrap items-end justify-center gap-8">
+                <sanring-radio-group [(ngModel)]="sizeSmValue" size="sm">
+                  <div class="flex items-center gap-2">
+                    <sanring-radio-item id="size-sm" value="sm" />
+                    <label sanringLabel for="size-sm">{{ i18n.t('radio.demo.size.sm') }}</label>
+                  </div>
+                </sanring-radio-group>
+                <sanring-radio-group [(ngModel)]="sizeMdValue" size="md">
+                  <div class="flex items-center gap-2">
+                    <sanring-radio-item id="size-md" value="md" />
+                    <label sanringLabel for="size-md">{{ i18n.t('radio.demo.size.md') }}</label>
+                  </div>
+                </sanring-radio-group>
+                <sanring-radio-group [(ngModel)]="sizeLgValue" size="lg">
+                  <div class="flex items-center gap-2">
+                    <sanring-radio-item id="size-lg" value="lg" />
+                    <label sanringLabel for="size-lg">{{ i18n.t('radio.demo.size.lg') }}</label>
+                  </div>
+                </sanring-radio-group>
+              </div>
+            </app-component-page-code-previewer>
+          </app-component-page-section>
+
           <app-component-page-section [section]="section('example-horizontal')">
             <app-component-page-code-previewer [code]="examples.horizontal" language="angular-html">
               <div previewer class="flex items-center justify-center">
@@ -212,6 +237,9 @@ export class RadioPageComponent {
 
   basicValue: RadioValue = '';
   labeledValue: RadioValue = 'comfortable';
+  sizeSmValue: RadioValue = 'sm';
+  sizeMdValue: RadioValue = 'md';
+  sizeLgValue: RadioValue = 'lg';
   horizontalValue: RadioValue = 'center';
   disabledGroupValue: RadioValue = 'option1';
   disabledItemValue: RadioValue = 'option1';
diff --git a/apps/docs/src/app/pages/components/radio/radio.docs.ts b/apps/docs/src/app/pages/components/radio/radio.docs.ts
index 7df85ce..b9f88c6 100644
--- a/apps/docs/src/app/pages/components/radio/radio.docs.ts
+++ b/apps/docs/src/app/pages/components/radio/radio.docs.ts
@@ -43,6 +43,11 @@ export const radioPage = {
           titleKey: 'radio.demo.horizontal',
           level: 3,
         },
+        {
+          id: 'example-size',
+          titleKey: 'radio.demo.size',
+          level: 3,
+        },
         {
           id: 'example-disabled',
           titleKey: 'radio.demo.disabled',
@@ -131,6 +136,12 @@ export const radioGroupApiRows = [
     defaultValue: 'RadioOrientation.Vertical',
     descriptionKey: 'radio.api.group.orientation',
   },
+  {
+    property: 'size',
+    type: "'sm' | 'md' | 'lg'",
+    defaultValue: "'md'",
+    descriptionKey: 'radio.api.group.size',
+  },
   {
     property: 'value',
     type: 'RadioValue | null',
@@ -246,6 +257,27 @@ export class ExampleComponent {}`,
   </div>
 </sanring-radio-group>`,
 
+  size: `<sanring-radio-group [(ngModel)]="smValue" size="sm">
+  <div class="flex items-center gap-2">
+    <sanring-radio-item id="size-sm" value="sm" />
+    <label sanringLabel for="size-sm">Small</label>
+  </div>
+</sanring-radio-group>
+
+<sanring-radio-group [(ngModel)]="mdValue" size="md">
+  <div class="flex items-center gap-2">
+    <sanring-radio-item id="size-md" value="md" />
+    <label sanringLabel for="size-md">Medium</label>
+  </div>
+</sanring-radio-group>
+
+<sanring-radio-group [(ngModel)]="lgValue" size="lg">
+  <div class="flex items-center gap-2">
+    <sanring-radio-item id="size-lg" value="lg" />
+    <label sanringLabel for="size-lg">Large</label>
+  </div>
+</sanring-radio-group>`,
+
   horizontal: `<sanring-radio-group [(ngModel)]="value" [orientation]="RadioOrientation.Horizontal">
   <div class="flex items-center gap-2">
     <sanring-radio-item id="h-left" value="left" />
diff --git a/apps/docs/src/app/pages/components/sheet/sheet-page.component.ts b/apps/docs/src/app/pages/components/sheet/sheet-page.component.ts
index 48885a5..9d5303f 100644
--- a/apps/docs/src/app/pages/components/sheet/sheet-page.component.ts
+++ b/apps/docs/src/app/pages/components/sheet/sheet-page.component.ts
@@ -61,14 +61,6 @@ import { sheetPage, sheetPageExamples } from './sheet.docs';
                 {{ i18n.t('sheet.demo.open') }}
               </button>
               <sanring-sheet-content>
-                <button
-                  type="button"
-                  sanringSheetClose
-                  aria-label="Close"
-                  class="absolute right-4 top-4 rounded-[var(--sanring-radius-xs)] p-0.5 opacity-70 transition-opacity hover:opacity-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--sanring-border-strong)]"
-                >
-                  <svg lucideX class="size-4"></svg>
-                </button>
                 <sanring-sheet-header>
                   <sanring-sheet-title>{{ i18n.t('sheet.demo.editProfile') }}</sanring-sheet-title>
                   <sanring-sheet-description>
@@ -126,14 +118,6 @@ import { sheetPage, sheetPageExamples } from './sheet.docs';
                     {{ i18n.t('sheet.demo.openTop') }}
                   </button>
                   <sanring-sheet-content side="top">
-                    <button
-                      type="button"
-                      sanringSheetClose
-                      aria-label="Close"
-                      class="absolute right-4 top-4 rounded-[var(--sanring-radius-xs)] p-0.5 opacity-70 transition-opacity hover:opacity-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--sanring-border-strong)]"
-                    >
-                      <svg lucideX class="size-4"></svg>
-                    </button>
                     <sanring-sheet-header>
                       <sanring-sheet-title>Top Sheet</sanring-sheet-title>
                       <sanring-sheet-description
@@ -169,14 +153,6 @@ import { sheetPage, sheetPageExamples } from './sheet.docs';
                     {{ i18n.t('sheet.demo.openRight') }}
                   </button>
                   <sanring-sheet-content side="right">
-                    <button
-                      type="button"
-                      sanringSheetClose
-                      aria-label="Close"
-                      class="absolute right-4 top-4 rounded-[var(--sanring-radius-xs)] p-0.5 opacity-70 transition-opacity hover:opacity-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--sanring-border-strong)]"
-                    >
-                      <svg lucideX class="size-4"></svg>
-                    </button>
                     <sanring-sheet-header>
                       <sanring-sheet-title>Right Sheet</sanring-sheet-title>
                       <sanring-sheet-description
@@ -219,14 +195,6 @@ import { sheetPage, sheetPageExamples } from './sheet.docs';
                     {{ i18n.t('sheet.demo.openBottom') }}
                   </button>
                   <sanring-sheet-content side="bottom">
-                    <button
-                      type="button"
-                      sanringSheetClose
-                      aria-label="Close"
-                      class="absolute right-4 top-4 rounded-[var(--sanring-radius-xs)] p-0.5 opacity-70 transition-opacity hover:opacity-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--sanring-border-strong)]"
-                    >
-                      <svg lucideX class="size-4"></svg>
-                    </button>
                     <sanring-sheet-header>
                       <sanring-sheet-title>Bottom Sheet</sanring-sheet-title>
                       <sanring-sheet-description
@@ -262,14 +230,6 @@ import { sheetPage, sheetPageExamples } from './sheet.docs';
                     {{ i18n.t('sheet.demo.openLeft') }}
                   </button>
                   <sanring-sheet-content side="left">
-                    <button
-                      type="button"
-                      sanringSheetClose
-                      aria-label="Close"
-                      class="absolute right-4 top-4 rounded-[var(--sanring-radius-xs)] p-0.5 opacity-70 transition-opacity hover:opacity-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--sanring-border-strong)]"
-                    >
-                      <svg lucideX class="size-4"></svg>
-                    </button>
                     <sanring-sheet-header>
                       <sanring-sheet-title>Left Sheet</sanring-sheet-title>
                       <sanring-sheet-description
@@ -319,14 +279,6 @@ import { sheetPage, sheetPageExamples } from './sheet.docs';
                     {{ i18n.t('sheet.demo.editProfile') }}
                   </button>
                   <sanring-sheet-content side="right">
-                    <button
-                      type="button"
-                      sanringSheetClose
-                      aria-label="Close"
-                      class="absolute right-4 top-4 rounded-[var(--sanring-radius-xs)] p-0.5 opacity-70 transition-opacity hover:opacity-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--sanring-border-strong)]"
-                    >
-                      <svg lucideX class="size-4"></svg>
-                    </button>
                     <sanring-sheet-header>
                       <sanring-sheet-title>{{
                         i18n.t('sheet.demo.editProfile')
@@ -372,7 +324,7 @@ import { sheetPage, sheetPageExamples } from './sheet.docs';
                   <button sanringBtn variant="destructive" sanringSheetTrigger>
                     {{ i18n.t('sheet.demo.delete') }}…
                   </button>
-                  <sanring-sheet-content>
+                  <sanring-sheet-content [showClose]="false">
                     <button
                       type="button"
                       sanringSheetClose
diff --git a/apps/docs/src/app/pages/components/sheet/sheet.docs.ts b/apps/docs/src/app/pages/components/sheet/sheet.docs.ts
index 6dfea9c..674ac0b 100644
--- a/apps/docs/src/app/pages/components/sheet/sheet.docs.ts
+++ b/apps/docs/src/app/pages/components/sheet/sheet.docs.ts
@@ -73,6 +73,24 @@ export const sheetPage = {
       defaultValue: "'right'",
       descriptionKey: 'sheet.api.side.description',
     },
+    {
+      property: 'showClose',
+      type: 'boolean',
+      defaultValue: 'true',
+      descriptionKey: 'sheet.api.showClose.description',
+    },
+    {
+      property: 'closeAriaLabel',
+      type: 'string',
+      defaultValue: "'關閉面板'",
+      descriptionKey: 'sheet.api.closeAriaLabel.description',
+    },
+    {
+      property: 'sanring-sheet-header.align',
+      type: "'start' | 'center'",
+      defaultValue: 'responsive',
+      descriptionKey: 'sheet.api.headerAlign.description',
+    },
     {
       property: 'class',
       type: 'string',
@@ -170,18 +188,12 @@ export class ExampleComponent {}`,
 │   └── sanring-sheet-footer
 └── [sanringSheetClose]`,
 
-  side: `<!-- Change [side] to move the sheet; the close pattern is the same for all four. -->
+  side: `<!-- Change [side] to move the sheet. A close control is built in. -->
 <sanring-sheet>
   <button sanringBtn sanringSheetTrigger>Top</button>
 
   <sanring-sheet-content side="top">
-    <!-- X close: use sanringSheetClose on any element -->
-    <button type="button" sanringSheetClose aria-label="Close"
-      class="absolute right-4 top-4 ...">
-      <svg lucideX class="size-4"></svg>
-    </button>
-
-    <sanring-sheet-header class="pr-10">
+    <sanring-sheet-header>
       <sanring-sheet-title>Top Sheet</sanring-sheet-title>
       <sanring-sheet-description>Slides in from the top edge.</sanring-sheet-description>
     </sanring-sheet-header>
@@ -220,12 +232,11 @@ export class ExampleComponent {}`,
     </sanring-sheet-footer>
   </sanring-sheet-content>
 </sanring-sheet>`,
-  customClose: `<!-- The sheet does not render a built-in close button.
-     Place sanringSheetClose on any button you want to use as a close control. -->
+  customClose: `<!-- Hide the built-in X and place sanringSheetClose on any button you want. -->
 <sanring-sheet>
   <button sanringBtn sanringSheetTrigger>Open</button>
 
-  <sanring-sheet-content>
+  <sanring-sheet-content [showClose]="false">
     <button type="button" sanringSheetClose aria-label="Close"
       class="absolute right-4 top-4 ...">
       <svg lucideX class="size-4"></svg>
diff --git a/apps/docs/src/app/pages/components/table/table-page.component.ts b/apps/docs/src/app/pages/components/table/table-page.component.ts
index c881f16..91aad04 100644
--- a/apps/docs/src/app/pages/components/table/table-page.component.ts
+++ b/apps/docs/src/app/pages/components/table/table-page.component.ts
@@ -1,12 +1,13 @@
 import { CdkTableModule } from '@angular/cdk/table';
 import { Component, computed, inject, signal } from '@angular/core';
-import { LucideEllipsis, LucideFile, LucideSettings, LucideTrash2 } from '@lucide/angular';
+import { LucideCheck, LucideEllipsis, LucideFile, LucideSettings, LucideTrash2 } from '@lucide/angular';
 import {
   ButtonDirective,
   CheckboxComponent,
   CheckedState,
   PaginatorComponent,
   SANRING_DROPDOWN_MENU_IMPORTS,
+  SkeletonDirective,
   SortDirective,
   SortHeaderComponent,
   SortState,
@@ -51,6 +52,7 @@ interface InvoiceRow {
     ButtonDirective,
     CheckboxComponent,
     SANRING_DROPDOWN_MENU_IMPORTS,
+    LucideCheck,
     LucideEllipsis,
     LucideFile,
     LucideSettings,
@@ -64,6 +66,7 @@ interface InvoiceRow {
     ComponentPageSectionComponent,
     ComponentPageUsageImportsComponent,
     PaginatorComponent,
+    SkeletonDirective,
     SortDirective,
     SortHeaderComponent,
     TableCellDefDirective,
@@ -264,14 +267,14 @@ interface InvoiceRow {
                       <th
                         sanringHeaderCell
                         *sanringHeaderCellDef
-                        class="bg-[var(--sanring-background)] shadow-[1px_0_0_var(--sanring-border)]"
+                        class="shadow-[1px_0_0_var(--sanring-border)]"
                       >
                         Invoice
                       </th>
                       <td
                         sanringCell
                         *sanringCellDef="let invoice"
-                        class="bg-[var(--sanring-background)] shadow-[1px_0_0_var(--sanring-border)]"
+                        class="shadow-[1px_0_0_var(--sanring-border)]"
                       >
                         {{ invoice.id }}
                       </td>
@@ -337,14 +340,14 @@ interface InvoiceRow {
                       <th
                         sanringHeaderCell
                         *sanringHeaderCellDef
-                        class="bg-[var(--sanring-background)] text-right shadow-[-1px_0_0_var(--sanring-border)]"
+                        class="text-right shadow-[-1px_0_0_var(--sanring-border)]"
                       >
                         Actions
                       </th>
                       <td
                         sanringCell
                         *sanringCellDef="let invoice"
-                        class="bg-[var(--sanring-background)] text-right shadow-[-1px_0_0_var(--sanring-border)]"
+                        class="text-right shadow-[-1px_0_0_var(--sanring-border)]"
                       >
                         <button sanringBtn variant="ghost" size="icon" aria-label="Open actions">
                           <svg lucideEllipsis class="size-4"></svg>
@@ -360,6 +363,128 @@ interface InvoiceRow {
             </app-component-page-code-previewer>
           </app-component-page-section>
 
+          <app-component-page-section [section]="section('example-loading')">
+            <app-component-page-code-previewer [code]="examples.loading" language="angular-html">
+              <div previewer class="w-full">
+                <sanring-table-container
+                  class="rounded-[var(--sanring-radius)] border border-[var(--docs-border)]"
+                >
+                  <table class="w-full">
+                    <thead>
+                      <tr>
+                        <th class="h-12 px-4 text-left text-sm font-medium text-[var(--sanring-muted)]">
+                          Invoice
+                        </th>
+                        <th class="h-12 px-4 text-left text-sm font-medium text-[var(--sanring-muted)]">
+                          Customer
+                        </th>
+                        <th class="h-12 px-4 text-left text-sm font-medium text-[var(--sanring-muted)]">
+                          Status
+                        </th>
+                        <th class="h-12 px-4 text-right text-sm font-medium text-[var(--sanring-muted)]">
+                          Amount
+                        </th>
+                      </tr>
+                    </thead>
+                    <tbody>
+                      @for (row of skeletonRows; track row) {
+                        <tr class="border-t border-[var(--sanring-border)]">
+                          <td class="p-4"><div sanringSkeleton class="h-4 w-20"></div></td>
+                          <td class="p-4"><div sanringSkeleton class="h-4 w-28"></div></td>
+                          <td class="p-4"><div sanringSkeleton class="h-4 w-16"></div></td>
+                          <td class="p-4">
+                            <div sanringSkeleton class="ml-auto h-4 w-16"></div>
+                          </td>
+                        </tr>
+                      }
+                    </tbody>
+                  </table>
+                </sanring-table-container>
+              </div>
+            </app-component-page-code-previewer>
+          </app-component-page-section>
+
+          <app-component-page-section [section]="section('example-column-visibility')">
+            <app-component-page-code-previewer
+              [code]="examples.columnVisibility"
+              language="angular-html"
+            >
+              <div previewer class="grid w-full gap-3">
+                <sanring-dropdown-menu>
+                  <button
+                    sanringBtn
+                    variant="outline"
+                    sanringDropdownMenuTrigger
+                    [menu]="columnsMenu.menu"
+                  >
+                    Columns
+                  </button>
+                  <sanring-dropdown-menu-content
+                    #columnsMenu="sanringDropdownMenuContent"
+                    class="w-44"
+                  >
+                    @for (column of allColumns; track column.id) {
+                      <button
+                        sanringDropdownMenuItem
+                        type="button"
+                        [value]="column.id"
+                        (click)="$event.preventDefault(); toggleColumn(column.id)"
+                      >
+                        <span class="flex size-4 items-center justify-center">
+                          @if (isColumnVisible(column.id)) {
+                            <svg lucideCheck class="size-4"></svg>
+                          }
+                        </span>
+                        {{ column.label }}
+                      </button>
+                    }
+                  </sanring-dropdown-menu-content>
+                </sanring-dropdown-menu>
+
+                <sanring-table-container
+                  class="rounded-[var(--sanring-radius)] border border-[var(--docs-border)]"
+                >
+                  <table cdk-table sanringTable [dataSource]="invoices">
+                    <ng-container sanringColumnDef="invoice">
+                      <th sanringHeaderCell *sanringHeaderCellDef>Invoice</th>
+                      <td sanringCell *sanringCellDef="let invoice">{{ invoice.id }}</td>
+                    </ng-container>
+                    <ng-container sanringColumnDef="customer">
+                      <th sanringHeaderCell *sanringHeaderCellDef>Customer</th>
+                      <td sanringCell *sanringCellDef="let invoice">{{ invoice.customer }}</td>
+                    </ng-container>
+                    <ng-container sanringColumnDef="status">
+                      <th sanringHeaderCell *sanringHeaderCellDef>Status</th>
+                      <td sanringCell *sanringCellDef="let invoice">
+                        <span [class]="statusClass(invoice.status)">{{ invoice.status }}</span>
+                      </td>
+                    </ng-container>
+                    <ng-container sanringColumnDef="amount">
+                      <th sanringHeaderCell *sanringHeaderCellDef class="text-right">Amount</th>
+                      <td
+                        sanringCell
+                        *sanringCellDef="let invoice"
+                        class="text-right tabular-nums"
+                      >
+                        {{ formatAmount(invoice.amount) }}
+                      </td>
+                    </ng-container>
+                    <tr
+                      cdk-header-row
+                      sanringRow
+                      *sanringHeaderRowDef="visibleColumns()"
+                    ></tr>
+                    <tr
+                      cdk-row
+                      sanringRow
+                      *sanringRowDef="let row; columns: visibleColumns()"
+                    ></tr>
+                  </table>
+                </sanring-table-container>
+              </div>
+            </app-component-page-code-previewer>
+          </app-component-page-section>
+
           <app-component-page-section [section]="section('example-empty')">
             <app-component-page-code-previewer [code]="examples.empty" language="angular-html">
               <div previewer class="w-full">
@@ -610,6 +735,20 @@ export class TablePageComponent {
   protected readonly page = tablePage;
   protected readonly examples = tablePageExamples;
   protected readonly i18n = inject(I18nService);
+  protected readonly skeletonRows = [1, 2, 3, 4];
+  protected readonly allColumns = [
+    { id: 'invoice', label: 'Invoice' },
+    { id: 'customer', label: 'Customer' },
+    { id: 'status', label: 'Status' },
+    { id: 'amount', label: 'Amount' },
+  ] as const;
+  protected readonly visibleColumnIds = signal<string[]>([
+    'invoice',
+    'customer',
+    'status',
+    'amount',
+  ]);
+  protected readonly visibleColumns = computed(() => this.visibleColumnIds());
   protected readonly displayedColumns = ['invoice', 'customer', 'status', 'amount'];
   protected readonly sizingColumns = ['select', 'invoice', 'customer', 'amount', 'actions'];
   protected readonly stickyStartColumns = ['invoice', 'customer', 'status', 'amount'];
@@ -764,6 +903,16 @@ export class TablePageComponent {
     });
   }
 
+  protected isColumnVisible(id: string): boolean {
+    return this.visibleColumnIds().includes(id);
+  }
+
+  protected toggleColumn(id: string): void {
+    this.visibleColumnIds.update((columns) =>
+      columns.includes(id) ? columns.filter((column) => column !== id) : [...columns, id],
+    );
+  }
+
   private sortValue(row: InvoiceRow, active: string): string | number {
     if (active === 'invoice') return row.id;
     if (active === 'customer') return row.customer;
diff --git a/apps/docs/src/app/pages/components/table/table.docs.ts b/apps/docs/src/app/pages/components/table/table.docs.ts
index 5963cad..2709cdd 100644
--- a/apps/docs/src/app/pages/components/table/table.docs.ts
+++ b/apps/docs/src/app/pages/components/table/table.docs.ts
@@ -36,6 +36,8 @@ export const tablePage = {
         { id: 'example-sortable', titleKey: 'table.demo.sortable', level: 3 },
         { id: 'example-column-sizing', titleKey: 'table.demo.columnSizing', level: 3 },
         { id: 'example-sticky', titleKey: 'table.demo.sticky', level: 3 },
+        { id: 'example-loading', titleKey: 'table.demo.loading', level: 3 },
+        { id: 'example-column-visibility', titleKey: 'table.demo.columnVisibility', level: 3 },
         { id: 'example-empty', titleKey: 'table.demo.empty', level: 3 },
         { id: 'example-selection', titleKey: 'table.demo.selection', level: 3 },
         { id: 'example-actions', titleKey: 'table.demo.actions', level: 3 },
@@ -208,22 +210,14 @@ import { SortDirective, SortHeaderComponent, TableCellDefDirective, TableCellDir
   </table>
 </sanring-table-container>`,
 
-  sticky: `<!-- Sticky start -->
+  sticky: `<!-- Sticky cells already get an opaque background. Add a shadow if you want an edge. -->
 <sanring-table-container class="max-w-[520px]">
   <table cdk-table sanringTable [dataSource]="invoices" class="min-w-[760px]">
     <ng-container sanringColumnDef="invoice" sticky>
-      <th
-        sanringHeaderCell
-        *sanringHeaderCellDef
-        class="bg-[var(--sanring-background)] shadow-[1px_0_0_var(--sanring-border)]"
-      >
+      <th sanringHeaderCell *sanringHeaderCellDef class="shadow-[1px_0_0_var(--sanring-border)]">
         Invoice
       </th>
-      <td
-        sanringCell
-        *sanringCellDef="let invoice"
-        class="bg-[var(--sanring-background)] shadow-[1px_0_0_var(--sanring-border)]"
-      >
+      <td sanringCell *sanringCellDef="let invoice" class="shadow-[1px_0_0_var(--sanring-border)]">
         {{ invoice.id }}
       </td>
     </ng-container>
@@ -241,15 +235,11 @@ import { SortDirective, SortHeaderComponent, TableCellDefDirective, TableCellDir
       <th
         sanringHeaderCell
         *sanringHeaderCellDef
-        class="bg-[var(--sanring-background)] text-right shadow-[-1px_0_0_var(--sanring-border)]"
+        class="text-right shadow-[-1px_0_0_var(--sanring-border)]"
       >
         Actions
       </th>
-      <td
-        sanringCell
-        *sanringCellDef="let invoice"
-        class="bg-[var(--sanring-background)] text-right shadow-[-1px_0_0_var(--sanring-border)]"
-      >
+      <td sanringCell *sanringCellDef="let invoice" class="text-right shadow-[-1px_0_0_var(--sanring-border)]">
         <button sanringBtn variant="ghost" size="icon" aria-label="Open actions">
           <svg lucideEllipsis class="size-4"></svg>
         </button>
@@ -258,6 +248,60 @@ import { SortDirective, SortHeaderComponent, TableCellDefDirective, TableCellDir
   </table>
 </sanring-table-container>`,
 
+  loading: `@if (loading) {
+  <table class="w-full">
+    <thead>
+      <tr>
+        <th class="h-12 px-4 text-left">Invoice</th>
+        <th class="h-12 px-4 text-left">Customer</th>
+        <th class="h-12 px-4 text-left">Status</th>
+        <th class="h-12 px-4 text-right">Amount</th>
+      </tr>
+    </thead>
+    <tbody>
+      @for (row of [1, 2, 3, 4]; track row) {
+        <tr>
+          <td class="p-4"><div sanringSkeleton class="h-4 w-20"></div></td>
+          <td class="p-4"><div sanringSkeleton class="h-4 w-28"></div></td>
+          <td class="p-4"><div sanringSkeleton class="h-4 w-16"></div></td>
+          <td class="p-4"><div sanringSkeleton class="ml-auto h-4 w-16"></div></td>
+        </tr>
+      }
+    </tbody>
+  </table>
+} @else {
+  <table cdk-table sanringTable [dataSource]="invoices">…</table>
+}`,
+
+  columnVisibility: `<sanring-dropdown-menu>
+  <button sanringBtn variant="outline" sanringDropdownMenuTrigger [menu]="columnsMenu.menu">
+    Columns
+  </button>
+  <sanring-dropdown-menu-content #columnsMenu="sanringDropdownMenuContent" class="w-44">
+    @for (column of allColumns; track column.id) {
+      <button
+        sanringDropdownMenuItem
+        type="button"
+        [value]="column.id"
+        (click)="$event.preventDefault(); toggleColumn(column.id)"
+      >
+        <span class="flex size-4 items-center justify-center">
+          @if (isColumnVisible(column.id)) {
+            <svg lucideCheck class="size-4"></svg>
+          }
+        </span>
+        {{ column.label }}
+      </button>
+    }
+  </sanring-dropdown-menu-content>
+</sanring-dropdown-menu>
+
+<table cdk-table sanringTable [dataSource]="invoices">
+  <!-- column defs for invoice / customer / status / amount... -->
+  <tr cdk-header-row sanringRow *sanringHeaderRowDef="visibleColumns()"></tr>
+  <tr cdk-row sanringRow *sanringRowDef="let row; columns: visibleColumns()"></tr>
+</table>`,
+
   empty: `<table cdk-table sanringTable [dataSource]="[]">
   <!-- columns... -->
   <tr *sanringNoDataRow>
diff --git a/apps/docs/src/app/pages/components/transfer/transfer-page.component.ts b/apps/docs/src/app/pages/components/transfer/transfer-page.component.ts
index 247c1d3..c4cd8e1 100644
--- a/apps/docs/src/app/pages/components/transfer/transfer-page.component.ts
+++ b/apps/docs/src/app/pages/components/transfer/transfer-page.component.ts
@@ -211,6 +211,61 @@ import { transferPage, transferPageExamples } from './transfer.docs';
             </app-component-page-code-previewer>
           </app-component-page-section>
 
+          <app-component-page-section [section]="section('example-disabled-group')">
+            <app-component-page-code-previewer
+              [code]="examples.disabledGroup"
+              language="angular-html"
+            >
+              <div previewer class="w-[min(480px,100%)]">
+                <sanring-transfer
+                  #disabledGroupTransfer
+                  [items]="items"
+                  [(selectedKeys)]="disabledGroupSelectedKeys"
+                  disabled
+                  ariaLabel="Assign languages"
+                  class="flex items-stretch gap-2"
+                >
+                  <sanring-transfer-panel direction="source" class="h-72 w-56">
+                    <sanring-transfer-header>{{
+                      i18n.t('transfer.demo.available')
+                    }}</sanring-transfer-header>
+                    <sanring-transfer-list />
+                  </sanring-transfer-panel>
+
+                  <div sanringTransferAction>
+                    <button
+                      sanringBtn
+                      variant="outline"
+                      size="icon"
+                      disabled
+                      [attr.aria-label]="i18n.t('transfer.demo.moveToTarget')"
+                      (click)="disabledGroupTransfer.moveToTarget()"
+                    >
+                      <svg lucideChevronRight class="size-4"></svg>
+                    </button>
+                    <button
+                      sanringBtn
+                      variant="outline"
+                      size="icon"
+                      disabled
+                      [attr.aria-label]="i18n.t('transfer.demo.moveToSource')"
+                      (click)="disabledGroupTransfer.moveToSource()"
+                    >
+                      <svg lucideChevronLeft class="size-4"></svg>
+                    </button>
+                  </div>
+
+                  <sanring-transfer-panel direction="target" class="h-72 w-56">
+                    <sanring-transfer-header>{{
+                      i18n.t('transfer.demo.selected')
+                    }}</sanring-transfer-header>
+                    <sanring-transfer-list />
+                  </sanring-transfer-panel>
+                </sanring-transfer>
+              </div>
+            </app-component-page-code-previewer>
+          </app-component-page-section>
+
           <app-component-page-section [section]="section('example-header-count')">
             <app-component-page-code-previewer
               [code]="examples.headerCount"
@@ -745,6 +800,7 @@ export class TransferPageComponent {
 
   protected basicSelectedKeys: string[] = ['angular', 'react'];
   protected disabledSelectedKeys: string[] = ['angular'];
+  protected disabledGroupSelectedKeys: string[] = ['angular', 'react'];
   protected countedSelectedKeys: string[] = ['angular', 'react'];
   protected customActionsSelectedKeys: string[] = ['angular', 'react'];
   protected oneWaySelectedKeys: string[] = ['angular'];
diff --git a/apps/docs/src/app/pages/components/transfer/transfer.docs.ts b/apps/docs/src/app/pages/components/transfer/transfer.docs.ts
index ef6d578..942791b 100644
--- a/apps/docs/src/app/pages/components/transfer/transfer.docs.ts
+++ b/apps/docs/src/app/pages/components/transfer/transfer.docs.ts
@@ -46,6 +46,11 @@ export const transferPage = {
           titleKey: 'transfer.demo.disabled',
           level: 3,
         },
+        {
+          id: 'example-disabled-group',
+          titleKey: 'transfer.demo.disabledGroup',
+          level: 3,
+        },
         {
           id: 'example-header-count',
           titleKey: 'transfer.demo.headerCount',
@@ -110,6 +115,18 @@ export const transferPage = {
       defaultValue: '[]',
       descriptionKey: 'transfer.api.items.description',
     },
+    {
+      property: 'TransferComponent.disabled',
+      type: 'boolean',
+      defaultValue: 'false',
+      descriptionKey: 'transfer.api.disabled.description',
+    },
+    {
+      property: 'TransferComponent.ariaLabel',
+      type: 'string',
+      defaultValue: 'undefined',
+      descriptionKey: 'transfer.api.ariaLabel.description',
+    },
     {
       property: 'TransferComponent.selectedKeys',
       type: 'string[]',
@@ -334,6 +351,28 @@ export class ExampleComponent {}`,
     </sanring-transfer-header>
     <sanring-transfer-list />
   </sanring-transfer-panel>
+</sanring-transfer>`,
+  disabledGroup: `<sanring-transfer
+  #transfer
+  [items]="items"
+  [(selectedKeys)]="selectedKeys"
+  disabled
+  ariaLabel="Assign languages"
+>
+  <sanring-transfer-panel direction="source">
+    <sanring-transfer-header>Available</sanring-transfer-header>
+    <sanring-transfer-list />
+  </sanring-transfer-panel>
+
+  <div sanringTransferAction>
+    <button sanringBtn size="icon" disabled (click)="transfer.moveToTarget()">→</button>
+    <button sanringBtn size="icon" disabled (click)="transfer.moveToSource()">←</button>
+  </div>
+
+  <sanring-transfer-panel direction="target">
+    <sanring-transfer-header>Selected</sanring-transfer-header>
+    <sanring-transfer-list />
+  </sanring-transfer-panel>
 </sanring-transfer>`,
   headerCount: `<sanring-transfer #transfer [items]="items" [(selectedKeys)]="selectedKeys">
   <sanring-transfer-panel direction="source" class="h-72 w-56" #sourcePanel="sanringTransferPanel">
diff --git a/packages/ui/src/lib/components/component-styles.ts b/packages/ui/src/lib/components/component-styles.ts
index a22a076..06657cf 100644
--- a/packages/ui/src/lib/components/component-styles.ts
+++ b/packages/ui/src/lib/components/component-styles.ts
@@ -19,6 +19,8 @@ export const OVERLAY_SURFACE_CLASS =
   'border border-[var(--sanring-border)] bg-[var(--sanring-elevated)] text-[var(--sanring-foreground)] shadow-lg';
 export const POPOVER_SURFACE_CLASS = 'z-50 w-72 rounded-[var(--sanring-radius-sm)] p-4 shadow-md outline-none';
 export const OVERLAY_CLOSE_ICON_CLASS = 'size-4';
+export const OVERLAY_ABSOLUTE_CLOSE_BUTTON_CLASS =
+  'absolute right-4 top-4 rounded-[var(--sanring-radius-xs)] text-[var(--sanring-muted)] opacity-70 ring-offset-[var(--sanring-surface)] transition-colors transition-opacity hover:text-[var(--sanring-foreground)] hover:opacity-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--sanring-border-strong)] focus-visible:ring-offset-2 disabled:pointer-events-none';
 
 export const SELECTION_CONTROL_BASE_CLASS =
   'peer flex shrink-0 items-center justify-center transition-colors disabled:cursor-not-allowed disabled:opacity-50';
diff --git a/packages/ui/src/lib/components/dropdown-menu/dropdown-menu-sub-content.component.ts b/packages/ui/src/lib/components/dropdown-menu/dropdown-menu-sub-content.component.ts
new file mode 100644
index 0000000..44236b3
--- /dev/null
+++ b/packages/ui/src/lib/components/dropdown-menu/dropdown-menu-sub-content.component.ts
@@ -0,0 +1,103 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  ElementRef,
+  OnDestroy,
+  computed,
+  effect,
+  inject,
+  input,
+} from '@angular/core';
+import { Menu as ngMenu } from '@angular/aria/menu';
+import {
+  ConnectionPositionPair,
+  FlexibleConnectedPositionStrategy,
+  Overlay,
+  OverlayRef,
+} from '@angular/cdk/overlay';
+import { DomPortal } from '@angular/cdk/portal';
+import { cn } from '../../utils';
+import { OVERLAY_SURFACE_CLASS } from '../component-styles';
+import { DropdownMenuSubComponent } from './dropdown-menu-sub.component';
+
+const SUB_CONTENT_POSITIONS: ConnectionPositionPair[] = [
+  { originX: 'end', originY: 'top', overlayX: 'start', overlayY: 'top' },
+  { originX: 'start', originY: 'top', overlayX: 'end', overlayY: 'top' },
+  { originX: 'end', originY: 'bottom', overlayX: 'start', overlayY: 'bottom' },
+  { originX: 'start', originY: 'bottom', overlayX: 'end', overlayY: 'bottom' },
+];
+
+@Component({
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  selector: 'sanring-dropdown-menu-sub-content',
+  standalone: true,
+  exportAs: 'sanringDropdownMenuSubContent',
+  hostDirectives: [
+    {
+      directive: ngMenu,
+      inputs: ['id', 'wrap', 'typeaheadDelay'],
+      outputs: ['itemSelected'],
+    },
+  ],
+  template: `<ng-content></ng-content>`,
+  host: {
+    '[class]': 'contentClass()',
+  },
+})
+export class DropdownMenuSubContentComponent implements OnDestroy {
+  readonly menu = inject(ngMenu, { self: true });
+  private readonly sub = inject(DropdownMenuSubComponent);
+  private readonly elementRef = inject(ElementRef<HTMLElement>);
+  private readonly overlay = inject(Overlay);
+
+  readonly class = input<string | undefined>();
+
+  private overlayRef: OverlayRef | null = null;
+  private positionStrategy: FlexibleConnectedPositionStrategy | null = null;
+
+  protected readonly contentClass = computed(() =>
+    cn(
+      OVERLAY_SURFACE_CLASS,
+      'z-50 block min-w-32 overflow-hidden rounded-[var(--sanring-radius-sm)] p-1 outline-none',
+      'data-[visible=false]:hidden',
+      this.menu.visible() ? 'animate-popover-in' : '',
+      this.class(),
+    ),
+  );
+
+  constructor() {
+    effect(() => {
+      const trigger = this.sub.triggerRef();
+      if (trigger && !this.overlayRef) {
+        this.attachOverlay(trigger.nativeElement);
+      }
+    });
+
+    effect(() => {
+      if (this.menu.visible()) {
+        queueMicrotask(() => this.overlayRef?.updatePosition());
+      }
+    });
+  }
+
+  private attachOverlay(trigger: HTMLElement): void {
+    this.positionStrategy = this.overlay
+      .position()
+      .flexibleConnectedTo(trigger)
+      .withPositions(SUB_CONTENT_POSITIONS)
+      .withFlexibleDimensions(false)
+      .withPush(true)
+      .withViewportMargin(8);
+
+    this.overlayRef = this.overlay.create({
+      positionStrategy: this.positionStrategy,
+      scrollStrategy: this.overlay.scrollStrategies.reposition(),
+    });
+
+    this.overlayRef.attach(new DomPortal(this.elementRef.nativeElement));
+  }
+
+  ngOnDestroy(): void {
+    this.overlayRef?.dispose();
+  }
+}
diff --git a/packages/ui/src/lib/components/dropdown-menu/dropdown-menu-sub-trigger.component.ts b/packages/ui/src/lib/components/dropdown-menu/dropdown-menu-sub-trigger.component.ts
new file mode 100644
index 0000000..11375f1
--- /dev/null
+++ b/packages/ui/src/lib/components/dropdown-menu/dropdown-menu-sub-trigger.component.ts
@@ -0,0 +1,59 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  ElementRef,
+  computed,
+  inject,
+  input,
+} from '@angular/core';
+import { MenuItem as ngMenuItem } from '@angular/aria/menu';
+import { LucideChevronRight } from '@lucide/angular';
+import { cn } from '../../utils';
+import { MENU_ITEM_SIZE_CLASS } from '../component-styles';
+import { DropdownMenuSubComponent } from './dropdown-menu-sub.component';
+import { DropdownMenuItemVariant } from './dropdown-menu.type';
+
+@Component({
+  selector: 'sanring-dropdown-menu-sub-trigger',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [LucideChevronRight],
+  hostDirectives: [
+    {
+      directive: ngMenuItem,
+      inputs: ['value', 'disabled', 'submenu'],
+    },
+  ],
+  host: {
+    '[attr.data-variant]': 'variant()',
+    '[class]': 'itemClass()',
+  },
+  template: `
+    <ng-content></ng-content>
+    <svg lucideChevronRight class="ml-auto size-4 shrink-0"></svg>
+  `,
+})
+export class DropdownMenuSubTriggerComponent {
+  private readonly sub = inject(DropdownMenuSubComponent);
+  private readonly elementRef = inject(ElementRef<HTMLElement>);
+
+  readonly class = input<string | undefined>();
+  readonly variant = input<DropdownMenuItemVariant>('default');
+
+  protected readonly itemClass = computed(() =>
+    cn(
+      'relative flex w-full cursor-default select-none items-center justify-start gap-2 rounded-[var(--sanring-radius-xs)] outline-none',
+      MENU_ITEM_SIZE_CLASS,
+      'text-[var(--sanring-foreground)] transition-colors',
+      'hover:bg-[var(--sanring-surface-strong)] focus:bg-[var(--sanring-surface-strong)] data-[active=true]:bg-[var(--sanring-surface-strong)] data-[expanded=true]:bg-[var(--sanring-surface-strong)]',
+      this.variant() === 'destructive' &&
+        'text-[var(--sanring-error-50)] hover:bg-[color-mix(in_srgb,var(--sanring-error-50)_10%,transparent)] focus:bg-[color-mix(in_srgb,var(--sanring-error-50)_10%,transparent)] data-[active=true]:bg-[color-mix(in_srgb,var(--sanring-error-50)_10%,transparent)]',
+      'aria-disabled:pointer-events-none aria-disabled:opacity-50',
+      this.class(),
+    ),
+  );
+
+  constructor() {
+    this.sub.registerTrigger(this.elementRef);
+  }
+}
diff --git a/packages/ui/src/lib/components/dropdown-menu/dropdown-menu-sub.component.ts b/packages/ui/src/lib/components/dropdown-menu/dropdown-menu-sub.component.ts
new file mode 100644
index 0000000..7315d59
--- /dev/null
+++ b/packages/ui/src/lib/components/dropdown-menu/dropdown-menu-sub.component.ts
@@ -0,0 +1,21 @@
+import { ChangeDetectionStrategy, Component, ElementRef, signal } from '@angular/core';
+
+@Component({
+  selector: 'sanring-dropdown-menu-sub',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  template: `<ng-content></ng-content>`,
+  styles: `
+    :host {
+      display: contents;
+    }
+  `,
+})
+export class DropdownMenuSubComponent {
+  private readonly _triggerRef = signal<ElementRef<HTMLElement> | null>(null);
+  readonly triggerRef = this._triggerRef.asReadonly();
+
+  registerTrigger(ref: ElementRef<HTMLElement>): void {
+    this._triggerRef.set(ref);
+  }
+}
diff --git a/packages/ui/src/lib/components/dropdown-menu/dropdown-menu-trigger.directive.ts b/packages/ui/src/lib/components/dropdown-menu/dropdown-menu-trigger.directive.ts
index a93fc18..697348f 100644
--- a/packages/ui/src/lib/components/dropdown-menu/dropdown-menu-trigger.directive.ts
+++ b/packages/ui/src/lib/components/dropdown-menu/dropdown-menu-trigger.directive.ts
@@ -104,10 +104,12 @@ export class DropdownMenuTriggerDirective implements OnDestroy {
     this.overlayRef.attach(new DomPortal(contentElement));
 
     this.overlayRef.outsidePointerEvents().subscribe((event) => {
+      const target = event.target as Node | null;
       if (
         this.ngTrigger.expanded() &&
-        !this.elementRef.nativeElement.contains(event.target as Node) &&
-        !contentElement.contains(event.target as Node)
+        !this.elementRef.nativeElement.contains(target) &&
+        !contentElement.contains(target) &&
+        !(target instanceof Element && target.closest('sanring-dropdown-menu-sub-content'))
       ) {
         this.ngTrigger.close();
       }
diff --git a/packages/ui/src/lib/components/dropdown-menu/dropdown-menu.component.spec.ts b/packages/ui/src/lib/components/dropdown-menu/dropdown-menu.component.spec.ts
index eacd935..f23a9e7 100644
--- a/packages/ui/src/lib/components/dropdown-menu/dropdown-menu.component.spec.ts
+++ b/packages/ui/src/lib/components/dropdown-menu/dropdown-menu.component.spec.ts
@@ -6,6 +6,9 @@ import { expectNoA11yViolations } from '../../../testing/axe-a11y';
 import { DropdownMenuComponent } from './dropdown-menu.component';
 import { DropdownMenuContentComponent } from './dropdown-menu-content.component';
 import { DropdownMenuItemDirective } from './dropdown-menu-item.directive';
+import { DropdownMenuSubComponent } from './dropdown-menu-sub.component';
+import { DropdownMenuSubContentComponent } from './dropdown-menu-sub-content.component';
+import { DropdownMenuSubTriggerComponent } from './dropdown-menu-sub-trigger.component';
 import { DropdownMenuTriggerDirective } from './dropdown-menu-trigger.directive';
 
 @Component({
@@ -47,12 +50,40 @@ class DropdownMenuTestHost {}
 })
 class DropdownMenuClassTestHost {}
 
+@Component({
+  imports: [
+    DropdownMenuComponent,
+    DropdownMenuContentComponent,
+    DropdownMenuItemDirective,
+    DropdownMenuSubComponent,
+    DropdownMenuSubContentComponent,
+    DropdownMenuSubTriggerComponent,
+    DropdownMenuTriggerDirective,
+  ],
+  template: `
+    <sanring-dropdown-menu>
+      <button type="button" sanringDropdownMenuTrigger [menu]="menu.menu">Open</button>
+      <sanring-dropdown-menu-content #menu="sanringDropdownMenuContent">
+        <sanring-dropdown-menu-sub>
+          <sanring-dropdown-menu-sub-trigger value="more" [submenu]="sub.menu">
+            More
+          </sanring-dropdown-menu-sub-trigger>
+          <sanring-dropdown-menu-sub-content #sub="sanringDropdownMenuSubContent">
+            <button type="button" sanringDropdownMenuItem value="nested">Nested</button>
+          </sanring-dropdown-menu-sub-content>
+        </sanring-dropdown-menu-sub>
+      </sanring-dropdown-menu-content>
+    </sanring-dropdown-menu>
+  `,
+})
+class DropdownMenuSubmenuTestHost {}
+
 describe('DropdownMenuComponent', () => {
   let overlayContainer: OverlayContainer;
 
   beforeEach(async () => {
     await TestBed.configureTestingModule({
-      imports: [DropdownMenuTestHost, DropdownMenuClassTestHost],
+      imports: [DropdownMenuTestHost, DropdownMenuClassTestHost, DropdownMenuSubmenuTestHost],
     }).compileComponents();
 
     overlayContainer = TestBed.inject(OverlayContainer);
@@ -171,6 +202,41 @@ describe('DropdownMenuComponent', () => {
     expect(item?.classList.contains('custom-item-class')).toBe(true);
   });
 
+  it('opens a nested submenu from the parent menu item', async () => {
+    const fixture = TestBed.createComponent(DropdownMenuSubmenuTestHost);
+    fixture.detectChanges();
+    await fixture.whenStable();
+    fixture.detectChanges();
+
+    const trigger = fixture.nativeElement.querySelector('[sanringDropdownMenuTrigger]') as HTMLElement;
+    trigger.click();
+    fixture.detectChanges();
+    await fixture.whenStable();
+    fixture.detectChanges();
+
+    const overlayElement = overlayContainer.getContainerElement();
+    const subTrigger = overlayElement.querySelector(
+      'sanring-dropdown-menu-sub-trigger',
+    ) as HTMLElement;
+    expect(subTrigger.getAttribute('aria-haspopup')).toBe('true');
+    expect(subTrigger.getAttribute('aria-expanded')).toBe('false');
+
+    subTrigger.dispatchEvent(new MouseEvent('mouseover', { bubbles: true }));
+    fixture.detectChanges();
+    await new Promise((resolve) => setTimeout(resolve, 150));
+    fixture.detectChanges();
+    await fixture.whenStable();
+    fixture.detectChanges();
+
+    expect(subTrigger.getAttribute('aria-expanded')).toBe('true');
+
+    const visibleMenus = Array.from(overlayElement.querySelectorAll('[role="menu"]')).filter(
+      (menu) => menu.getAttribute('data-visible') === 'true',
+    );
+    expect(visibleMenus.length).toBeGreaterThanOrEqual(2);
+    expect(overlayElement.textContent).toContain('Nested');
+  });
+
   it('has no axe-detectable a11y violations, trigger and open menu together', async () => {
     const fixture = await setup();
     document.body.appendChild(fixture.nativeElement);
diff --git a/packages/ui/src/lib/components/dropdown-menu/index.ts b/packages/ui/src/lib/components/dropdown-menu/index.ts
index e1ff029..8fca9ec 100644
--- a/packages/ui/src/lib/components/dropdown-menu/index.ts
+++ b/packages/ui/src/lib/components/dropdown-menu/index.ts
@@ -3,6 +3,9 @@ export * from './dropdown-menu-group.component';
 export * from './dropdown-menu-item.directive';
 export * from './dropdown-menu-label.component';
 export * from './dropdown-menu-separator.component';
+export * from './dropdown-menu-sub.component';
+export * from './dropdown-menu-sub-content.component';
+export * from './dropdown-menu-sub-trigger.component';
 export * from './dropdown-menu.component';
 export * from './dropdown-menu-trigger.directive';
 export * from './dropdown-menu.type';
@@ -12,6 +15,9 @@ import { DropdownMenuGroupComponent } from './dropdown-menu-group.component';
 import { DropdownMenuItemDirective } from './dropdown-menu-item.directive';
 import { DropdownMenuLabelComponent } from './dropdown-menu-label.component';
 import { DropdownMenuSeparatorComponent } from './dropdown-menu-separator.component';
+import { DropdownMenuSubComponent } from './dropdown-menu-sub.component';
+import { DropdownMenuSubContentComponent } from './dropdown-menu-sub-content.component';
+import { DropdownMenuSubTriggerComponent } from './dropdown-menu-sub-trigger.component';
 import { DropdownMenuComponent } from './dropdown-menu.component';
 import { DropdownMenuTriggerDirective } from './dropdown-menu-trigger.directive';
 
@@ -23,4 +29,7 @@ export const SANRING_DROPDOWN_MENU_IMPORTS = [
   DropdownMenuLabelComponent,
   DropdownMenuItemDirective,
   DropdownMenuSeparatorComponent,
+  DropdownMenuSubComponent,
+  DropdownMenuSubTriggerComponent,
+  DropdownMenuSubContentComponent,
 ];
diff --git a/packages/ui/src/lib/components/popover/popover-content.component.ts b/packages/ui/src/lib/components/popover/popover-content.component.ts
index 3b47d53..45922e7 100644
--- a/packages/ui/src/lib/components/popover/popover-content.component.ts
+++ b/packages/ui/src/lib/components/popover/popover-content.component.ts
@@ -11,9 +11,11 @@ import {
   ElementRef,
   Signal,
   computed,
+  contentChild,
   effect,
   inject,
   input,
+  numberAttribute,
   signal,
   untracked,
   viewChild,
@@ -22,37 +24,49 @@ import { cn } from '../../utils';
 import { OVERLAY_SURFACE_CLASS, POPOVER_SURFACE_CLASS } from '../component-styles';
 import { POPOVER_LEAVE_DURATION_MS } from '../component-timing';
 import { PopoverComponent } from './popover.component';
-import type { PopoverAlign } from './popover.type';
+import { PopoverTitleComponent } from './popover-title.component';
+import type { PopoverAlign, PopoverSide } from './popover.type';
 
-const GAP = 8;
+const DEFAULT_SIDE_OFFSET = 8;
 
-type PopoverPlacement = 'top' | 'bottom';
-
-const FALLBACK_PLACEMENTS: readonly PopoverPlacement[] = ['bottom', 'top'];
+function fallbackSides(side: PopoverSide): PopoverSide[] {
+  if (side === 'top') return ['top', 'bottom', 'right', 'left'];
+  if (side === 'right') return ['right', 'left', 'bottom', 'top'];
+  if (side === 'left') return ['left', 'right', 'bottom', 'top'];
+  return ['bottom', 'top', 'right', 'left'];
+}
 
-function positionFor(placement: PopoverPlacement, align: PopoverAlign): ConnectionPositionPair {
-  if (placement === 'top') {
+function positionFor(
+  side: PopoverSide,
+  align: PopoverAlign,
+  offset: number,
+): ConnectionPositionPair {
+  if (side === 'top' || side === 'bottom') {
     return {
       originX: align,
-      originY: 'top',
+      originY: side,
       overlayX: align,
-      overlayY: 'bottom',
-      offsetY: -GAP,
+      overlayY: side === 'bottom' ? 'top' : 'bottom',
+      offsetY: side === 'bottom' ? offset : -offset,
     };
   }
 
+  const verticalAlign = align === 'start' ? 'top' : align === 'end' ? 'bottom' : 'center';
+
   return {
-    originX: align,
-    originY: 'bottom',
-    overlayX: align,
-    overlayY: 'top',
-    offsetY: GAP,
+    originX: side === 'right' ? 'end' : 'start',
+    originY: verticalAlign,
+    overlayX: side === 'right' ? 'start' : 'end',
+    overlayY: verticalAlign,
+    offsetX: side === 'right' ? offset : -offset,
   };
 }
 
-function getPlacementFromPosition(position: ConnectionPositionPair): PopoverPlacement {
+function getSideFromPosition(position: ConnectionPositionPair): PopoverSide {
   if (position.originY === 'top' && position.overlayY === 'bottom') return 'top';
-  return 'bottom';
+  if (position.originY === 'bottom' && position.overlayY === 'top') return 'bottom';
+  if (position.originX === 'end' && position.overlayX === 'start') return 'right';
+  return 'left';
 }
 
 @Component({
@@ -81,9 +95,10 @@ function getPlacementFromPosition(position: ConnectionPositionPair): PopoverPlac
           tabindex="-1"
           role="dialog"
           [id]="popover.contentId"
-          [attr.aria-labelledby]="popover.titleId"
+          [attr.aria-label]="computedAriaLabel()"
+          [attr.aria-labelledby]="computedAriaLabelledBy()"
           [attr.aria-describedby]="popover.descId"
-          [attr.data-placement]="renderedPlacement()"
+          [attr.data-side]="renderedSide()"
           [class]="panelClass()"
           (animationend)="onLeaveAnimationEnd($event)"
         >
@@ -104,10 +119,22 @@ export class PopoverContentComponent {
   private readonly destroyRef = inject(DestroyRef);
 
   readonly class = input<string | undefined>();
+  readonly side = input<PopoverSide>('bottom');
+  readonly sideOffset = input(DEFAULT_SIDE_OFFSET, { transform: numberAttribute });
+  readonly ariaLabel = input<string | undefined>();
+  readonly ariaLabelledBy = input<string | undefined>();
 
   protected readonly scrollStrategy = this.overlay.scrollStrategies.close();
-  protected readonly renderedPlacement = signal<PopoverPlacement>('bottom');
+  protected readonly renderedSide = signal<PopoverSide>('bottom');
   private readonly panelEl = viewChild<ElementRef<HTMLElement>>('panelEl');
+  private readonly title = contentChild(PopoverTitleComponent);
+
+  protected readonly computedAriaLabelledBy = computed(
+    () => this.ariaLabelledBy() ?? (this.title() ? this.popover.titleId : null),
+  );
+  protected readonly computedAriaLabel = computed(() =>
+    this.computedAriaLabelledBy() ? null : (this.ariaLabel() ?? null),
+  );
 
   private readonly _leaving = signal(false);
   private _leaveTimer: ReturnType<typeof setTimeout> | undefined;
@@ -119,13 +146,13 @@ export class PopoverContentComponent {
 
   protected readonly positions: Signal<ConnectionPositionPair[]> = computed(() => {
     const align = this.popover.align();
-    return FALLBACK_PLACEMENTS.map(placement => positionFor(placement, align));
+    const offset = this.sideOffset();
+    return fallbackSides(this.side()).map((side) => positionFor(side, align, offset));
   });
 
   constructor() {
     effect(() => {
-      this.popover.align();
-      this.renderedPlacement.set('bottom');
+      this.renderedSide.set(this.side());
     });
 
     // Watch for external isOpen → false transitions and play leave animation
@@ -193,7 +220,7 @@ export class PopoverContentComponent {
   }
 
   handlePositionChange(event: ConnectedOverlayPositionChange): void {
-    this.renderedPlacement.set(getPlacementFromPosition(event.connectionPair));
+    this.renderedSide.set(getSideFromPosition(event.connectionPair));
   }
 
   private _startLeave(): void {
diff --git a/packages/ui/src/lib/components/popover/popover.component.spec.ts b/packages/ui/src/lib/components/popover/popover.component.spec.ts
index 29fc9d9..fa13603 100644
--- a/packages/ui/src/lib/components/popover/popover.component.spec.ts
+++ b/packages/ui/src/lib/components/popover/popover.component.spec.ts
@@ -44,12 +44,34 @@ class PopoverTestHost {}
 })
 class PopoverClassTestHost {}
 
+@Component({
+  imports: [PopoverComponent, PopoverContentComponent, PopoverTriggerDirective],
+  template: `
+    <sanring-popover>
+      <button type="button" sanringPopoverTrigger>Open</button>
+      <sanring-popover-content ariaLabel="Toolbar actions">Body</sanring-popover-content>
+    </sanring-popover>
+  `,
+})
+class UntitledPopoverHost {}
+
+@Component({
+  imports: [PopoverComponent, PopoverContentComponent, PopoverTriggerDirective],
+  template: `
+    <sanring-popover>
+      <button type="button" sanringPopoverTrigger>Open</button>
+      <sanring-popover-content side="right">Body</sanring-popover-content>
+    </sanring-popover>
+  `,
+})
+class SidePopoverHost {}
+
 describe('PopoverComponent', () => {
   let overlayContainer: OverlayContainer;
 
   beforeEach(async () => {
     await TestBed.configureTestingModule({
-      imports: [PopoverTestHost, PopoverClassTestHost],
+      imports: [PopoverTestHost, PopoverClassTestHost, UntitledPopoverHost, SidePopoverHost],
     }).compileComponents();
 
     overlayContainer = TestBed.inject(OverlayContainer);
@@ -128,6 +150,33 @@ describe('PopoverComponent', () => {
     fixture.detectChanges();
   });
 
+  it('omits aria-labelledby when no title is projected and uses ariaLabel as fallback', () => {
+    const fixture = TestBed.createComponent(UntitledPopoverHost);
+    fixture.detectChanges();
+
+    (fixture.nativeElement.querySelector('button') as HTMLElement).click();
+    fixture.detectChanges();
+
+    const panel = overlayContainer
+      .getContainerElement()
+      .querySelector('[role="dialog"]') as HTMLElement;
+    expect(panel.hasAttribute('aria-labelledby')).toBe(false);
+    expect(panel.getAttribute('aria-label')).toBe('Toolbar actions');
+  });
+
+  it('exposes the requested side on the panel', () => {
+    const fixture = TestBed.createComponent(SidePopoverHost);
+    fixture.detectChanges();
+
+    (fixture.nativeElement.querySelector('button') as HTMLElement).click();
+    fixture.detectChanges();
+
+    const panel = overlayContainer
+      .getContainerElement()
+      .querySelector('[role="dialog"]') as HTMLElement;
+    expect(panel.getAttribute('data-side')).toBe('right');
+  });
+
   it('merges host class with consumer class on the content panel', () => {
     const fixture = TestBed.createComponent(PopoverClassTestHost);
     fixture.detectChanges();
diff --git a/packages/ui/src/lib/components/popover/popover.type.ts b/packages/ui/src/lib/components/popover/popover.type.ts
index 6447f23..6a724af 100644
--- a/packages/ui/src/lib/components/popover/popover.type.ts
+++ b/packages/ui/src/lib/components/popover/popover.type.ts
@@ -1 +1,2 @@
 export type PopoverAlign = 'start' | 'center' | 'end';
+export type PopoverSide = 'top' | 'right' | 'bottom' | 'left';
diff --git a/packages/ui/src/lib/components/radio/radio-group.component.spec.ts b/packages/ui/src/lib/components/radio/radio-group.component.spec.ts
index 86b40b7..da7a880 100644
--- a/packages/ui/src/lib/components/radio/radio-group.component.spec.ts
+++ b/packages/ui/src/lib/components/radio/radio-group.component.spec.ts
@@ -48,10 +48,23 @@ class RadioGroupTestHost {
 })
 class RadioGroupA11yHost {}
 
+@Component({
+  imports: [RadioGroupComponent, RadioItemComponent],
+  template: `
+    <sanring-radio-group size="sm" ariaLabel="Small">
+      <sanring-radio-item value="a" />
+    </sanring-radio-group>
+    <sanring-radio-group size="lg" ariaLabel="Large">
+      <sanring-radio-item value="b" />
+    </sanring-radio-group>
+  `,
+})
+class RadioSizeHost {}
+
 describe('RadioGroupComponent', () => {
   beforeEach(async () => {
     await TestBed.configureTestingModule({
-      imports: [RadioGroupTestHost],
+      imports: [RadioGroupTestHost, RadioSizeHost],
     }).compileComponents();
   });
 
@@ -132,6 +145,15 @@ describe('RadioGroupComponent', () => {
     expect(group.classList.contains('grid')).toBe(true);
   });
 
+  it('applies the group size to each item', () => {
+    const fixture = TestBed.createComponent(RadioSizeHost);
+    fixture.detectChanges();
+
+    const items = fixture.nativeElement.querySelectorAll('[role="radio"]');
+    expect(items[0].className).toContain('h-3');
+    expect(items[1].className).toContain('h-5');
+  });
+
   it('has no axe-detectable a11y violations when items are paired with an external <label for>', async () => {
     await TestBed.configureTestingModule({ imports: [RadioGroupA11yHost] }).compileComponents();
     const fixture = TestBed.createComponent(RadioGroupA11yHost);
diff --git a/packages/ui/src/lib/components/radio/radio-group.component.ts b/packages/ui/src/lib/components/radio/radio-group.component.ts
index 1bbda29..c721303 100644
--- a/packages/ui/src/lib/components/radio/radio-group.component.ts
+++ b/packages/ui/src/lib/components/radio/radio-group.component.ts
@@ -16,7 +16,7 @@ import { NG_VALUE_ACCESSOR } from '@angular/forms';
 import { cn } from '../../utils';
 import { FieldType, SANRING_FIELD_CONTROL } from '../field/field.type';
 import { SanringCvaBase, SanringFieldControlAdapter } from '../shared/cva-base';
-import { RadioOrientation, RadioValue } from './radio.types';
+import { RadioOrientation, RadioSize, RadioValue } from './radio.types';
 import { RadioItemComponent } from './radio-item.component';
 
 @Component({
@@ -67,6 +67,7 @@ export class RadioGroupComponent extends SanringCvaBase<RadioValue | null> {
   readonly required = input(false, { transform: booleanAttribute });
   readonly disabled = input(false, { transform: booleanAttribute });
   readonly orientation = input<RadioOrientation>(RadioOrientation.Vertical);
+  readonly size = input<RadioSize>('md');
   readonly ariaLabel = input<string | undefined>();
   readonly ariaLabelledBy = input<string | undefined>();
   readonly ariaDescribedBy = input<string | undefined>();
diff --git a/packages/ui/src/lib/components/radio/radio-item.component.ts b/packages/ui/src/lib/components/radio/radio-item.component.ts
index 801acff..f5068bc 100644
--- a/packages/ui/src/lib/components/radio/radio-item.component.ts
+++ b/packages/ui/src/lib/components/radio/radio-item.component.ts
@@ -11,13 +11,9 @@ import {
 import { _IdGenerator } from '@angular/cdk/a11y';
 import { LucideCircle } from '@lucide/angular';
 import { cn } from '../../utils';
-import {
-  RADIO_INDICATOR_ICON_CLASS,
-  SELECTION_CONTROL_BASE_CLASS,
-  SELECTION_CONTROL_FOCUS_CLASS,
-} from '../component-styles';
+import { SELECTION_CONTROL_BASE_CLASS, SELECTION_CONTROL_FOCUS_CLASS } from '../component-styles';
 import { RadioGroupComponent } from './radio-group.component';
-import { RADIO_SIZE_CLASS } from './radio.styles';
+import { RADIO_INDICATOR_ICON_SIZE_CLASSES, RADIO_SIZE_CLASSES } from './radio.styles';
 import { RadioValue } from './radio.types';
 
 @Component({
@@ -48,15 +44,13 @@ import { RadioValue } from './radio.types';
     >
       @if (isChecked()) {
         <span class="flex items-center justify-center text-current animate-in zoom-in-50">
-          <svg lucideCircle [class]="radioIndicatorIconClass"></svg>
+          <svg lucideCircle [class]="radioIndicatorIconClass()"></svg>
         </span>
       }
     </button>
   `,
 })
 export class RadioItemComponent {
-  protected readonly radioIndicatorIconClass = RADIO_INDICATOR_ICON_CLASS;
-
   readonly class = input<string | undefined>();
   readonly id = input(inject(_IdGenerator).getId('sanring-radio-', true));
   readonly value = input.required<RadioValue>();
@@ -71,6 +65,10 @@ export class RadioItemComponent {
 
   protected isChecked = computed(() => this.group?.valueSignal() === this.value());
   protected isDisabled = computed(() => this.disabled() || (this.group?.isDisabled() ?? false));
+  protected readonly size = computed(() => this.group?.size() ?? 'md');
+  protected readonly radioIndicatorIconClass = computed(
+    () => RADIO_INDICATOR_ICON_SIZE_CLASSES[this.size()],
+  );
   protected tabIndex = computed(() => {
     if (!this.group) return 0;
     return this.group.activeTabItem() === this ? 0 : -1;
@@ -79,7 +77,7 @@ export class RadioItemComponent {
     cn(
       SELECTION_CONTROL_BASE_CLASS,
       SELECTION_CONTROL_FOCUS_CLASS,
-      RADIO_SIZE_CLASS,
+      RADIO_SIZE_CLASSES[this.size()],
       'rounded-full border border-[var(--sanring-primary)] text-[var(--sanring-primary)]',
       'data-[state=checked]:border-[var(--sanring-primary)]',
       this.class(),
diff --git a/packages/ui/src/lib/components/radio/radio.styles.ts b/packages/ui/src/lib/components/radio/radio.styles.ts
index 3d25cf5..6e7cdda 100644
--- a/packages/ui/src/lib/components/radio/radio.styles.ts
+++ b/packages/ui/src/lib/components/radio/radio.styles.ts
@@ -1 +1,13 @@
-export const RADIO_SIZE_CLASS = 'aspect-square h-4 w-4';
+import type { RadioSize } from './radio.types';
+
+export const RADIO_SIZE_CLASSES: Record<RadioSize, string> = {
+  sm: 'aspect-square h-3 w-3',
+  md: 'aspect-square h-4 w-4',
+  lg: 'aspect-square h-5 w-5',
+};
+
+export const RADIO_INDICATOR_ICON_SIZE_CLASSES: Record<RadioSize, string> = {
+  sm: 'h-2 w-2 fill-current text-current',
+  md: 'h-2.5 w-2.5 fill-current text-current',
+  lg: 'h-3 w-3 fill-current text-current',
+};
diff --git a/packages/ui/src/lib/components/radio/radio.types.ts b/packages/ui/src/lib/components/radio/radio.types.ts
index 6d647ae..1cb162d 100644
--- a/packages/ui/src/lib/components/radio/radio.types.ts
+++ b/packages/ui/src/lib/components/radio/radio.types.ts
@@ -1,4 +1,5 @@
 export type RadioValue = string;
+export type RadioSize = 'sm' | 'md' | 'lg';
 
 export enum RadioOrientation {
   Horizontal = 'horizontal',
diff --git a/packages/ui/src/lib/components/sheet/sheet-content.component.ts b/packages/ui/src/lib/components/sheet/sheet-content.component.ts
index be4d3fc..d5d4dc4 100644
--- a/packages/ui/src/lib/components/sheet/sheet-content.component.ts
+++ b/packages/ui/src/lib/components/sheet/sheet-content.component.ts
@@ -11,6 +11,7 @@ import {
   TemplateRef,
   ViewContainerRef,
   afterNextRender,
+  booleanAttribute,
   computed,
   effect,
   inject,
@@ -20,8 +21,13 @@ import {
   viewChild,
   contentChild,
 } from '@angular/core';
+import { LucideX } from '@lucide/angular';
 import { cn } from '../../utils';
-import { OVERLAY_SURFACE_CLASS } from '../component-styles';
+import {
+  OVERLAY_ABSOLUTE_CLOSE_BUTTON_CLASS,
+  OVERLAY_CLOSE_ICON_CLASS,
+  OVERLAY_SURFACE_CLASS,
+} from '../component-styles';
 import { SHEET_LEAVE_DURATION_MS } from '../component-timing';
 import { SheetComponent } from './sheet.component';
 import { SheetDescriptionComponent } from './sheet-description.component';
@@ -54,7 +60,7 @@ const SIDE_LEAVE: Record<SheetSide, string> = {
   selector: 'sanring-sheet-content',
   standalone: true,
   changeDetection: ChangeDetectionStrategy.OnPush,
-  imports: [CdkTrapFocus],
+  imports: [CdkTrapFocus, LucideX],
   host: {
     '(document:keydown.escape)': 'onEscape()',
   },
@@ -77,6 +83,18 @@ const SIDE_LEAVE: Record<SheetSide, string> = {
         (animationend)="onLeaveAnimationEnd($event)"
       >
         <ng-content></ng-content>
+
+        @if (showClose()) {
+          <button
+            type="button"
+            [attr.aria-label]="closeAriaLabel()"
+            (click)="requestClose()"
+            [class]="closeButtonClass"
+          >
+            <svg lucideX [class]="closeIconClass"></svg>
+            <span class="sr-only">關閉</span>
+          </button>
+        }
       </div>
     </ng-template>
   `,
@@ -95,8 +113,13 @@ export class SheetContentComponent {
   private readonly title = contentChild(SheetTitleComponent);
   private readonly description = contentChild(SheetDescriptionComponent);
 
+  protected readonly closeButtonClass = OVERLAY_ABSOLUTE_CLOSE_BUTTON_CLASS;
+  protected readonly closeIconClass = OVERLAY_CLOSE_ICON_CLASS;
+
   readonly side = input<SheetSide>('right');
   readonly class = input<string | undefined>();
+  readonly showClose = input(true, { transform: booleanAttribute });
+  readonly closeAriaLabel = input('關閉面板');
   /** Accessible-name fallback used when no SheetTitle is projected. */
   readonly ariaLabel = input<string | undefined>('Sheet');
   /** Explicit labelling relationship; takes precedence over SheetTitle and ariaLabel. */
diff --git a/packages/ui/src/lib/components/sheet/sheet-header.component.ts b/packages/ui/src/lib/components/sheet/sheet-header.component.ts
index 0453758..4e17532 100644
--- a/packages/ui/src/lib/components/sheet/sheet-header.component.ts
+++ b/packages/ui/src/lib/components/sheet/sheet-header.component.ts
@@ -10,5 +10,16 @@ import { cn } from '../../utils';
 })
 export class SheetHeaderComponent {
   readonly class = input<string | undefined>();
-  protected readonly hostClass = computed(() => cn('flex flex-col gap-1.5', this.class()));
+
+  readonly align = input<'start' | 'center' | undefined>(undefined);
+
+  protected readonly hostClass = computed(() =>
+    cn(
+      'flex flex-col gap-1.5',
+      this.align() === 'center' && 'items-center text-center',
+      this.align() === 'start' && 'items-start text-left',
+      !this.align() && 'text-center sm:text-left',
+      this.class(),
+    ),
+  );
 }
diff --git a/packages/ui/src/lib/components/sheet/sheet.component.spec.ts b/packages/ui/src/lib/components/sheet/sheet.component.spec.ts
index 4fefe9f..e1bf4e7 100644
--- a/packages/ui/src/lib/components/sheet/sheet.component.spec.ts
+++ b/packages/ui/src/lib/components/sheet/sheet.component.spec.ts
@@ -54,12 +54,44 @@ class SheetTestHost {}
 })
 class UntitledSheetTestHost {}
 
+@Component({
+  imports: [SheetContentComponent, SheetTriggerDirective, SheetComponent],
+  template: `
+    <sanring-sheet>
+      <button type="button" sanringSheetTrigger>Open</button>
+      <sanring-sheet-content [showClose]="false" ariaLabel="Filters"></sanring-sheet-content>
+    </sanring-sheet>
+  `,
+})
+class HiddenCloseSheetHost {}
+
+@Component({
+  imports: [
+    SheetContentComponent,
+    SheetHeaderComponent,
+    SheetTitleComponent,
+    SheetTriggerDirective,
+    SheetComponent,
+  ],
+  template: `
+    <sanring-sheet>
+      <button type="button" sanringSheetTrigger>Open</button>
+      <sanring-sheet-content>
+        <sanring-sheet-header align="center">
+          <sanring-sheet-title>Centered</sanring-sheet-title>
+        </sanring-sheet-header>
+      </sanring-sheet-content>
+    </sanring-sheet>
+  `,
+})
+class AlignedHeaderSheetHost {}
+
 describe('SheetComponent', () => {
   let overlayContainer: OverlayContainer;
 
   beforeEach(async () => {
     await TestBed.configureTestingModule({
-      imports: [SheetTestHost],
+      imports: [SheetTestHost, HiddenCloseSheetHost, AlignedHeaderSheetHost],
     }).compileComponents();
 
     overlayContainer = TestBed.inject(OverlayContainer);
@@ -285,6 +317,52 @@ describe('SheetComponent', () => {
     expect(trigger.getAttribute('aria-expanded')).toBe('false');
   });
 
+  it('renders a built-in close button that closes the panel', () => {
+    const fixture = TestBed.createComponent(SheetTestHost);
+    fixture.detectChanges();
+
+    (fixture.nativeElement.querySelector('button[sanringSheetTrigger]') as HTMLElement).click();
+    fixture.detectChanges();
+
+    const closeButton = overlayContainer
+      .getContainerElement()
+      .querySelector('button[aria-label="關閉面板"]') as HTMLElement;
+
+    expect(closeButton).toBeTruthy();
+    closeButton.click();
+    fixture.detectChanges();
+
+    expect(
+      fixture.nativeElement.querySelector('button[sanringSheetTrigger]')?.getAttribute('aria-expanded'),
+    ).toBe('false');
+  });
+
+  it('hides the built-in close button when showClose is false', () => {
+    const fixture = TestBed.createComponent(HiddenCloseSheetHost);
+    fixture.detectChanges();
+
+    (fixture.nativeElement.querySelector('button') as HTMLElement).click();
+    fixture.detectChanges();
+
+    expect(
+      overlayContainer.getContainerElement().querySelector('button[aria-label="關閉面板"]'),
+    ).toBeNull();
+  });
+
+  it('aligns the header when align is set', () => {
+    const fixture = TestBed.createComponent(AlignedHeaderSheetHost);
+    fixture.detectChanges();
+
+    (fixture.nativeElement.querySelector('button') as HTMLElement).click();
+    fixture.detectChanges();
+
+    const header = overlayContainer
+      .getContainerElement()
+      .querySelector('sanring-sheet-header') as HTMLElement;
+    expect(header.classList.contains('items-center')).toBe(true);
+    expect(header.classList.contains('text-center')).toBe(true);
+  });
+
   it('closes via a sanringSheetClose button inside the panel', () => {
     const fixture = TestBed.createComponent(SheetTestHost);
     fixture.detectChanges();
diff --git a/packages/ui/src/lib/components/table/cell.directive.ts b/packages/ui/src/lib/components/table/cell.directive.ts
index 27ee31e..c118ecc 100644
--- a/packages/ui/src/lib/components/table/cell.directive.ts
+++ b/packages/ui/src/lib/components/table/cell.directive.ts
@@ -68,7 +68,9 @@ export class TableHeaderCellDirective {
   standalone: true,
   // 🧠 當 <td> 蛋糕出生時，我們強行把 CDK 原生的 CdkCell 邏輯塞進去！
   hostDirectives: [CdkCell],
-  host: { class: 'p-4 align-middle [&:has([role=checkbox])]:pr-0' },
+  host: {
+    class: 'p-4 align-middle [&:has([role=checkbox])]:pr-0',
+  },
 })
 export class TableCellDirective {}
 
@@ -77,6 +79,8 @@ export class TableCellDirective {}
   standalone: true,
   // 🧠 當 footer 蛋糕出生時，我們強行把 CDK 原生的 CdkFooterCell 邏輯塞進去！
   hostDirectives: [CdkFooterCell],
-  host: { class: 'border-t p-4 align-middle font-medium [&:has([role=checkbox])]:pr-0' },
+  host: {
+    class: 'border-t p-4 align-middle font-medium [&:has([role=checkbox])]:pr-0',
+  },
 })
 export class TableFooterCellDirective {}
diff --git a/packages/ui/src/lib/components/table/table-container.component.ts b/packages/ui/src/lib/components/table/table-container.component.ts
index 089cc52..4f015ab 100644
--- a/packages/ui/src/lib/components/table/table-container.component.ts
+++ b/packages/ui/src/lib/components/table/table-container.component.ts
@@ -1,14 +1,21 @@
-import { ChangeDetectionStrategy, Component, computed, input } from '@angular/core';
+import { ChangeDetectionStrategy, Component, computed, input, ViewEncapsulation } from '@angular/core';
 import { cn } from '../../utils';
 
 @Component({
   selector: 'sanring-table-container',
   standalone: true,
   changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
   template: `<ng-content></ng-content>`,
   host: {
     '[class]': 'containerClass()',
   },
+  styles: `
+    sanring-table-container .cdk-table-sticky,
+    sanring-table-container .cdk-table-sticky-end {
+      background-color: var(--sanring-background);
+    }
+  `,
 })
 export class TableContainerComponent {
   readonly class = input<string | undefined>();
diff --git a/packages/ui/src/lib/components/table/table.component.spec.ts b/packages/ui/src/lib/components/table/table.component.spec.ts
index a62a31c..aa075f4 100644
--- a/packages/ui/src/lib/components/table/table.component.spec.ts
+++ b/packages/ui/src/lib/components/table/table.component.spec.ts
@@ -81,10 +81,43 @@ class TableTestHost {
   sort: SortState | null = null;
 }
 
+@Component({
+  imports: [
+    CdkTableModule,
+    TableContainerComponent,
+    TableDirective,
+    TableColumnDefDirective,
+    TableHeaderCellDefDirective,
+    TableCellDefDirective,
+    TableHeaderCellDirective,
+    TableCellDirective,
+    TableHeaderRowDefDirective,
+    TableRowDefDirective,
+    TableHeaderRowDirective,
+    TableRowDirective,
+  ],
+  template: `
+    <sanring-table-container>
+      <table cdk-table sanringTable [dataSource]="data">
+        <ng-container sanringColumnDef="name" sticky>
+          <th sanringHeaderCell *sanringHeaderCellDef>Name</th>
+          <td sanringCell *sanringCellDef="let person">{{ person.name }}</td>
+        </ng-container>
+        <tr cdk-header-row sanringRow *sanringHeaderRowDef="columns"></tr>
+        <tr cdk-row sanringRow *sanringRowDef="let row; columns: columns"></tr>
+      </table>
+    </sanring-table-container>
+  `,
+})
+class StickyTableHost {
+  columns = ['name'];
+  data = [{ name: 'Ada' }];
+}
+
 describe('TableComponent', () => {
   beforeEach(async () => {
     await TestBed.configureTestingModule({
-      imports: [TableTestHost],
+      imports: [TableTestHost, StickyTableHost],
     }).compileComponents();
   });
 
@@ -129,6 +162,18 @@ describe('TableComponent', () => {
     expect(sortHeader.getAttribute('aria-sort')).toBe('ascending');
   });
 
+  it('gives sticky cells an opaque background so scrolled text does not show through', () => {
+    const fixture = TestBed.createComponent(StickyTableHost);
+    fixture.detectChanges();
+
+    const header = fixture.nativeElement.querySelector('th') as HTMLElement;
+    const cell = fixture.nativeElement.querySelector('td') as HTMLElement;
+    expect(header.className).toContain('cdk-table-sticky');
+    expect(cell.className).toContain('cdk-table-sticky');
+    expect(getComputedStyle(header).backgroundColor).toBe('var(--sanring-background)');
+    expect(getComputedStyle(cell).backgroundColor).toBe('var(--sanring-background)');
+  });
+
   it('has no axe-detectable a11y violations', async () => {
     const fixture = TestBed.createComponent(TableTestHost);
     fixture.detectChanges();
diff --git a/packages/ui/src/lib/components/table/todolist.md b/packages/ui/src/lib/components/table/todolist.md
index de3da43..6b72ea5 100644
--- a/packages/ui/src/lib/components/table/todolist.md
+++ b/packages/ui/src/lib/components/table/todolist.md
@@ -18,13 +18,13 @@
 
 ## 待處理
 
-- [ ] Sticky 欄位的背景色 —— `sticky`/`stickyEnd` 已能傳進去，但 CDK 只會加 `position: sticky` + 位移，不會加背景色，實際用 sticky checkbox/actions 欄時要自己補不透明背景(例如 `bg-[var(--sanring-surface)]`），不然捲動時文字會透出來。
+- [x] Sticky 欄位的背景色 —— `sanring-table-container` 對投影進去的 `.cdk-table-sticky` / `.cdk-table-sticky-end` 補 `--sanring-background`（sticky 一定包在可捲動 container 裡）。消費者 `class` 仍可覆蓋。
 - [ ] `CdkTextColumn` 等效元件 —— 目前決定不做(它是 sealed Component，模板寫死原生 `cdk-*` attribute，要支援等於要重寫一整套 `ViewChild` 註冊邏輯)，先讓使用者手動組 `sanringColumnDef` + `sanringCellDef`。
 - [ ] CDK flex-layout(`<cdk-table>` 自訂標籤，非原生 `<table>`)—— 目前完全不支援。`TableDirective` 的 selector 已收窄成只認 `table[cdk-table][sanringTable]`，因為所有 cell/row directive 都只匹配原生 `th`/`td`/`tr`。真的要支援 flex 模式，需要幫每個 cell/row directive 都做一份平行 selector(例如 `cdk-cell[sanringCell]`），範圍不小，先不做。
 
 ## 不用寫新元件，純粹是「使用模式」要補進文件
 
 - [x] Row actions(⋯ 選單)—— docs table 頁面已示範用 `dropdown-menu` 放進最後一欄的 cell
-- [ ] Loading skeleton rows —— 用既有 `skeleton`，loading 時把 tbody 內容換掉；docs 頁面尚未示範
-- [ ] 欄位顯示/隱藏切換 —— dropdown-menu + checkbox 湊 checklist，搭配 `sanringRowDefColumns` 動態陣列；docs 頁面尚未示範
+- [x] Loading skeleton rows —— docs 用既有 `skeleton` 示範 loading 時把 tbody 換成骨架列
+- [x] 欄位顯示/隱藏切換 —— docs 用 dropdown-menu + 打勾圖示 + 動態 `sanringRowDef` columns 示範
 - [x] Row selection checkbox 欄 —— docs table 頁面已示範 `sanringColumnDef` + `sanring-checkbox` + `TableRowDirective` 的 `selected` input 組合
diff --git a/packages/ui/src/lib/components/transfer/transfer-panel.component.ts b/packages/ui/src/lib/components/transfer/transfer-panel.component.ts
index 2654d88..b286a15 100644
--- a/packages/ui/src/lib/components/transfer/transfer-panel.component.ts
+++ b/packages/ui/src/lib/components/transfer/transfer-panel.component.ts
@@ -34,7 +34,9 @@ export class TransferPanelComponent {
 
   // target 面板在 one-way 模式下變成唯讀展示：不能勾選，也就無法被搬回 source
   readonly interactive = computed(
-    () => !(this.direction() === 'target' && this.transfer.mode() === 'one-way'),
+    () =>
+      !this.transfer.isDisabled() &&
+      !(this.direction() === 'target' && this.transfer.mode() === 'one-way'),
   );
 
   // List/Item 元件只認得「這個 panel 該顯示哪些 key、勾選狀態怎麼查/切換」，
diff --git a/packages/ui/src/lib/components/transfer/transfer.component.spec.ts b/packages/ui/src/lib/components/transfer/transfer.component.spec.ts
index 3c1a1df..14a5e92 100644
--- a/packages/ui/src/lib/components/transfer/transfer.component.spec.ts
+++ b/packages/ui/src/lib/components/transfer/transfer.component.spec.ts
@@ -52,10 +52,48 @@ class TransferTestHost {
   readonly mode = signal<TransferMode>('two-way');
 }
 
+@Component({
+  imports: [
+    TransferComponent,
+    TransferPanelComponent,
+    TransferHeaderComponent,
+    TransferListComponent,
+    TransferActionDirective,
+  ],
+  template: `
+    <sanring-transfer
+      [items]="items"
+      [(selectedKeys)]="selectedKeys"
+      disabled
+      ariaLabel="Assign languages"
+      #transfer
+    >
+      <sanring-transfer-panel direction="source">
+        <sanring-transfer-header>Available</sanring-transfer-header>
+        <sanring-transfer-list />
+      </sanring-transfer-panel>
+      <div sanringTransferAction>
+        <button type="button" (click)="transfer.moveToTarget()">to-target</button>
+      </div>
+      <sanring-transfer-panel direction="target">
+        <sanring-transfer-header>Selected</sanring-transfer-header>
+        <sanring-transfer-list />
+      </sanring-transfer-panel>
+    </sanring-transfer>
+  `,
+})
+class DisabledTransferHost {
+  items = [
+    { key: '1', label: 'One' },
+    { key: '2', label: 'Two' },
+  ];
+  selectedKeys = ['2'];
+}
+
 describe('TransferComponent', () => {
   beforeEach(async () => {
     await TestBed.configureTestingModule({
-      imports: [TransferTestHost],
+      imports: [TransferTestHost, DisabledTransferHost],
     }).compileComponents();
   });
 
@@ -223,6 +261,32 @@ describe('TransferComponent', () => {
     expect(four.getAttribute('aria-checked')).toBe('true');
   });
 
+  it('names the group and blocks all moves when the root is disabled', async () => {
+    const fixture = TestBed.createComponent(DisabledTransferHost);
+    fixture.detectChanges();
+    await fixture.whenStable();
+    fixture.detectChanges();
+
+    const root = fixture.nativeElement.querySelector('sanring-transfer') as HTMLElement;
+    expect(root.getAttribute('role')).toBe('group');
+    expect(root.getAttribute('aria-label')).toBe('Assign languages');
+    expect(root.getAttribute('aria-disabled')).toBe('true');
+
+    const source = root.querySelector('[data-direction="source"]') as HTMLElement;
+    const one = source.querySelector('[role="checkbox"][aria-label="One"]') as HTMLElement;
+    expect(one.getAttribute('aria-disabled')).toBe('true');
+
+    one.click();
+    fixture.detectChanges();
+    Array.from(root.querySelectorAll('button'))
+      .find((button) => button.textContent?.trim() === 'to-target')
+      ?.click();
+    fixture.detectChanges();
+    await fixture.whenStable();
+
+    expect(fixture.componentInstance.selectedKeys).toEqual(['2']);
+  });
+
   it('has no axe-detectable a11y violations', async () => {
     const fixture = await createFixture();
 
diff --git a/packages/ui/src/lib/components/transfer/transfer.component.ts b/packages/ui/src/lib/components/transfer/transfer.component.ts
index 79bfdd0..d6a23ad 100644
--- a/packages/ui/src/lib/components/transfer/transfer.component.ts
+++ b/packages/ui/src/lib/components/transfer/transfer.component.ts
@@ -1,4 +1,12 @@
-import { ChangeDetectionStrategy, Component, computed, input, model, signal } from '@angular/core';
+import {
+  ChangeDetectionStrategy,
+  Component,
+  booleanAttribute,
+  computed,
+  input,
+  model,
+  signal,
+} from '@angular/core';
 import { cn } from '../../utils';
 import { TransferItem, TransferMode } from './transfer.type';
 
@@ -9,13 +17,19 @@ import { TransferItem, TransferMode } from './transfer.type';
   template: `<ng-content></ng-content>`,
   host: {
     '[class]': 'rootClass()',
+    role: 'group',
+    '[attr.aria-label]': 'ariaLabel()',
+    '[attr.aria-disabled]': 'isDisabled() || null',
   },
 })
 export class TransferComponent {
   readonly items = input<TransferItem[]>([]);
   readonly class = input<string | undefined>();
+  readonly disabled = input(false, { transform: booleanAttribute });
+  readonly ariaLabel = input<string | undefined>();
 
   protected readonly rootClass = computed(() => cn(this.class()));
+  readonly isDisabled = computed(() => this.disabled());
   // 雙向綁定：目前在右側（target）的 key 清單，父層可用 [(selectedKeys)] 拿到結果
   readonly selectedKeys = model<string[]>([]);
   readonly mode = input<TransferMode>('two-way');
@@ -46,6 +60,7 @@ export class TransferComponent {
   }
 
   toggleSourceSelected(key: string): void {
+    if (this.isDisabled()) return;
     if (this.itemsByKey().get(key)?.disabled) return;
     this.sourceSelectedKeys.update((keys) =>
       keys.includes(key) ? keys.filter((k) => k !== key) : [...keys, key],
@@ -54,6 +69,7 @@ export class TransferComponent {
 
   toggleTargetSelected(key: string): void {
     // one-way 模式下 target 是唯讀展示，不接受勾選
+    if (this.isDisabled()) return;
     if (this.mode() === 'one-way') return;
     if (this.itemsByKey().get(key)?.disabled) return;
     this.targetSelectedKeys.update((keys) =>
@@ -62,6 +78,7 @@ export class TransferComponent {
   }
 
   moveToTarget(): void {
+    if (this.isDisabled()) return;
     // 用當下的 sourceItems 過濾一次，避免 items() 從外部變動後 sourceSelectedKeys 裡殘留已經不存在的 key
     const validKeys = new Set(this.sourceItems().map((item) => item.key));
     const moving = this.sourceSelectedKeys().filter((key) => validKeys.has(key));
@@ -72,6 +89,7 @@ export class TransferComponent {
   }
 
   moveToSource(): void {
+    if (this.isDisabled()) return;
     if (this.mode() === 'one-way') return;
     const moving = new Set(this.targetSelectedKeys().filter((key) => this.itemsByKey().has(key)));
     if (moving.size === 0) return;
@@ -81,10 +99,12 @@ export class TransferComponent {
   }
 
   setSourceSelectedKeys(keys: string[]): void {
+    if (this.isDisabled()) return;
     this.sourceSelectedKeys.set(keys);
   }
 
   setTargetSelectedKeys(keys: string[]): void {
+    if (this.isDisabled()) return;
     if (this.mode() === 'one-way') return;
     this.targetSelectedKeys.set(keys);
   }
diff --git a/registry/components/dropdown-menu/dropdown-menu-sub-content.component.ts b/registry/components/dropdown-menu/dropdown-menu-sub-content.component.ts
new file mode 100644
index 0000000..3f6511a
--- /dev/null
+++ b/registry/components/dropdown-menu/dropdown-menu-sub-content.component.ts
@@ -0,0 +1,103 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  ElementRef,
+  OnDestroy,
+  computed,
+  effect,
+  inject,
+  input,
+} from '@angular/core';
+import { Menu as ngMenu } from '@angular/aria/menu';
+import {
+  ConnectionPositionPair,
+  FlexibleConnectedPositionStrategy,
+  Overlay,
+  OverlayRef,
+} from '@angular/cdk/overlay';
+import { DomPortal } from '@angular/cdk/portal';
+import { cn } from '../shared/utils';
+import { OVERLAY_SURFACE_CLASS } from '../shared/component-styles';
+import { DropdownMenuSubComponent } from './dropdown-menu-sub.component';
+
+const SUB_CONTENT_POSITIONS: ConnectionPositionPair[] = [
+  { originX: 'end', originY: 'top', overlayX: 'start', overlayY: 'top' },
+  { originX: 'start', originY: 'top', overlayX: 'end', overlayY: 'top' },
+  { originX: 'end', originY: 'bottom', overlayX: 'start', overlayY: 'bottom' },
+  { originX: 'start', originY: 'bottom', overlayX: 'end', overlayY: 'bottom' },
+];
+
+@Component({
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  selector: 'sanring-dropdown-menu-sub-content',
+  standalone: true,
+  exportAs: 'sanringDropdownMenuSubContent',
+  hostDirectives: [
+    {
+      directive: ngMenu,
+      inputs: ['id', 'wrap', 'typeaheadDelay'],
+      outputs: ['itemSelected'],
+    },
+  ],
+  template: `<ng-content></ng-content>`,
+  host: {
+    '[class]': 'contentClass()',
+  },
+})
+export class DropdownMenuSubContentComponent implements OnDestroy {
+  readonly menu = inject(ngMenu, { self: true });
+  private readonly sub = inject(DropdownMenuSubComponent);
+  private readonly elementRef = inject(ElementRef<HTMLElement>);
+  private readonly overlay = inject(Overlay);
+
+  readonly class = input<string | undefined>();
+
+  private overlayRef: OverlayRef | null = null;
+  private positionStrategy: FlexibleConnectedPositionStrategy | null = null;
+
+  protected readonly contentClass = computed(() =>
+    cn(
+      OVERLAY_SURFACE_CLASS,
+      'z-50 block min-w-32 overflow-hidden rounded-[var(--sanring-radius-sm)] p-1 outline-none',
+      'data-[visible=false]:hidden',
+      this.menu.visible() ? 'animate-popover-in' : '',
+      this.class(),
+    ),
+  );
+
+  constructor() {
+    effect(() => {
+      const trigger = this.sub.triggerRef();
+      if (trigger && !this.overlayRef) {
+        this.attachOverlay(trigger.nativeElement);
+      }
+    });
+
+    effect(() => {
+      if (this.menu.visible()) {
+        queueMicrotask(() => this.overlayRef?.updatePosition());
+      }
+    });
+  }
+
+  private attachOverlay(trigger: HTMLElement): void {
+    this.positionStrategy = this.overlay
+      .position()
+      .flexibleConnectedTo(trigger)
+      .withPositions(SUB_CONTENT_POSITIONS)
+      .withFlexibleDimensions(false)
+      .withPush(true)
+      .withViewportMargin(8);
+
+    this.overlayRef = this.overlay.create({
+      positionStrategy: this.positionStrategy,
+      scrollStrategy: this.overlay.scrollStrategies.reposition(),
+    });
+
+    this.overlayRef.attach(new DomPortal(this.elementRef.nativeElement));
+  }
+
+  ngOnDestroy(): void {
+    this.overlayRef?.dispose();
+  }
+}
diff --git a/registry/components/dropdown-menu/dropdown-menu-sub-trigger.component.ts b/registry/components/dropdown-menu/dropdown-menu-sub-trigger.component.ts
new file mode 100644
index 0000000..474449e
--- /dev/null
+++ b/registry/components/dropdown-menu/dropdown-menu-sub-trigger.component.ts
@@ -0,0 +1,59 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  ElementRef,
+  computed,
+  inject,
+  input,
+} from '@angular/core';
+import { MenuItem as ngMenuItem } from '@angular/aria/menu';
+import { LucideChevronRight } from '@lucide/angular';
+import { cn } from '../shared/utils';
+import { MENU_ITEM_SIZE_CLASS } from '../shared/component-styles';
+import { DropdownMenuSubComponent } from './dropdown-menu-sub.component';
+import { DropdownMenuItemVariant } from './dropdown-menu.type';
+
+@Component({
+  selector: 'sanring-dropdown-menu-sub-trigger',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [LucideChevronRight],
+  hostDirectives: [
+    {
+      directive: ngMenuItem,
+      inputs: ['value', 'disabled', 'submenu'],
+    },
+  ],
+  host: {
+    '[attr.data-variant]': 'variant()',
+    '[class]': 'itemClass()',
+  },
+  template: `
+    <ng-content></ng-content>
+    <svg lucideChevronRight class="ml-auto size-4 shrink-0"></svg>
+  `,
+})
+export class DropdownMenuSubTriggerComponent {
+  private readonly sub = inject(DropdownMenuSubComponent);
+  private readonly elementRef = inject(ElementRef<HTMLElement>);
+
+  readonly class = input<string | undefined>();
+  readonly variant = input<DropdownMenuItemVariant>('default');
+
+  protected readonly itemClass = computed(() =>
+    cn(
+      'relative flex w-full cursor-default select-none items-center justify-start gap-2 rounded-[var(--sanring-radius-xs)] outline-none',
+      MENU_ITEM_SIZE_CLASS,
+      'text-[var(--sanring-foreground)] transition-colors',
+      'hover:bg-[var(--sanring-surface-strong)] focus:bg-[var(--sanring-surface-strong)] data-[active=true]:bg-[var(--sanring-surface-strong)] data-[expanded=true]:bg-[var(--sanring-surface-strong)]',
+      this.variant() === 'destructive' &&
+        'text-[var(--sanring-error-50)] hover:bg-[color-mix(in_srgb,var(--sanring-error-50)_10%,transparent)] focus:bg-[color-mix(in_srgb,var(--sanring-error-50)_10%,transparent)] data-[active=true]:bg-[color-mix(in_srgb,var(--sanring-error-50)_10%,transparent)]',
+      'aria-disabled:pointer-events-none aria-disabled:opacity-50',
+      this.class(),
+    ),
+  );
+
+  constructor() {
+    this.sub.registerTrigger(this.elementRef);
+  }
+}
diff --git a/registry/components/dropdown-menu/dropdown-menu-sub.component.ts b/registry/components/dropdown-menu/dropdown-menu-sub.component.ts
new file mode 100644
index 0000000..7315d59
--- /dev/null
+++ b/registry/components/dropdown-menu/dropdown-menu-sub.component.ts
@@ -0,0 +1,21 @@
+import { ChangeDetectionStrategy, Component, ElementRef, signal } from '@angular/core';
+
+@Component({
+  selector: 'sanring-dropdown-menu-sub',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  template: `<ng-content></ng-content>`,
+  styles: `
+    :host {
+      display: contents;
+    }
+  `,
+})
+export class DropdownMenuSubComponent {
+  private readonly _triggerRef = signal<ElementRef<HTMLElement> | null>(null);
+  readonly triggerRef = this._triggerRef.asReadonly();
+
+  registerTrigger(ref: ElementRef<HTMLElement>): void {
+    this._triggerRef.set(ref);
+  }
+}
diff --git a/registry/components/dropdown-menu/dropdown-menu-trigger.directive.ts b/registry/components/dropdown-menu/dropdown-menu-trigger.directive.ts
index a93fc18..697348f 100644
--- a/registry/components/dropdown-menu/dropdown-menu-trigger.directive.ts
+++ b/registry/components/dropdown-menu/dropdown-menu-trigger.directive.ts
@@ -104,10 +104,12 @@ export class DropdownMenuTriggerDirective implements OnDestroy {
     this.overlayRef.attach(new DomPortal(contentElement));
 
     this.overlayRef.outsidePointerEvents().subscribe((event) => {
+      const target = event.target as Node | null;
       if (
         this.ngTrigger.expanded() &&
-        !this.elementRef.nativeElement.contains(event.target as Node) &&
-        !contentElement.contains(event.target as Node)
+        !this.elementRef.nativeElement.contains(target) &&
+        !contentElement.contains(target) &&
+        !(target instanceof Element && target.closest('sanring-dropdown-menu-sub-content'))
       ) {
         this.ngTrigger.close();
       }
diff --git a/registry/components/dropdown-menu/index.ts b/registry/components/dropdown-menu/index.ts
index e1ff029..8fca9ec 100644
--- a/registry/components/dropdown-menu/index.ts
+++ b/registry/components/dropdown-menu/index.ts
@@ -3,6 +3,9 @@ export * from './dropdown-menu-group.component';
 export * from './dropdown-menu-item.directive';
 export * from './dropdown-menu-label.component';
 export * from './dropdown-menu-separator.component';
+export * from './dropdown-menu-sub.component';
+export * from './dropdown-menu-sub-content.component';
+export * from './dropdown-menu-sub-trigger.component';
 export * from './dropdown-menu.component';
 export * from './dropdown-menu-trigger.directive';
 export * from './dropdown-menu.type';
@@ -12,6 +15,9 @@ import { DropdownMenuGroupComponent } from './dropdown-menu-group.component';
 import { DropdownMenuItemDirective } from './dropdown-menu-item.directive';
 import { DropdownMenuLabelComponent } from './dropdown-menu-label.component';
 import { DropdownMenuSeparatorComponent } from './dropdown-menu-separator.component';
+import { DropdownMenuSubComponent } from './dropdown-menu-sub.component';
+import { DropdownMenuSubContentComponent } from './dropdown-menu-sub-content.component';
+import { DropdownMenuSubTriggerComponent } from './dropdown-menu-sub-trigger.component';
 import { DropdownMenuComponent } from './dropdown-menu.component';
 import { DropdownMenuTriggerDirective } from './dropdown-menu-trigger.directive';
 
@@ -23,4 +29,7 @@ export const SANRING_DROPDOWN_MENU_IMPORTS = [
   DropdownMenuLabelComponent,
   DropdownMenuItemDirective,
   DropdownMenuSeparatorComponent,
+  DropdownMenuSubComponent,
+  DropdownMenuSubTriggerComponent,
+  DropdownMenuSubContentComponent,
 ];
diff --git a/registry/components/popover/popover-content.component.ts b/registry/components/popover/popover-content.component.ts
index d8c967d..b268347 100644
--- a/registry/components/popover/popover-content.component.ts
+++ b/registry/components/popover/popover-content.component.ts
@@ -11,9 +11,11 @@ import {
   ElementRef,
   Signal,
   computed,
+  contentChild,
   effect,
   inject,
   input,
+  numberAttribute,
   signal,
   untracked,
   viewChild,
@@ -22,37 +24,49 @@ import { cn } from '../shared/utils';
 import { OVERLAY_SURFACE_CLASS, POPOVER_SURFACE_CLASS } from '../shared/component-styles';
 import { POPOVER_LEAVE_DURATION_MS } from '../shared/component-timing';
 import { PopoverComponent } from './popover.component';
-import type { PopoverAlign } from './popover.type';
+import { PopoverTitleComponent } from './popover-title.component';
+import type { PopoverAlign, PopoverSide } from './popover.type';
 
-const GAP = 8;
+const DEFAULT_SIDE_OFFSET = 8;
 
-type PopoverPlacement = 'top' | 'bottom';
-
-const FALLBACK_PLACEMENTS: readonly PopoverPlacement[] = ['bottom', 'top'];
+function fallbackSides(side: PopoverSide): PopoverSide[] {
+  if (side === 'top') return ['top', 'bottom', 'right', 'left'];
+  if (side === 'right') return ['right', 'left', 'bottom', 'top'];
+  if (side === 'left') return ['left', 'right', 'bottom', 'top'];
+  return ['bottom', 'top', 'right', 'left'];
+}
 
-function positionFor(placement: PopoverPlacement, align: PopoverAlign): ConnectionPositionPair {
-  if (placement === 'top') {
+function positionFor(
+  side: PopoverSide,
+  align: PopoverAlign,
+  offset: number,
+): ConnectionPositionPair {
+  if (side === 'top' || side === 'bottom') {
     return {
       originX: align,
-      originY: 'top',
+      originY: side,
       overlayX: align,
-      overlayY: 'bottom',
-      offsetY: -GAP,
+      overlayY: side === 'bottom' ? 'top' : 'bottom',
+      offsetY: side === 'bottom' ? offset : -offset,
     };
   }
 
+  const verticalAlign = align === 'start' ? 'top' : align === 'end' ? 'bottom' : 'center';
+
   return {
-    originX: align,
-    originY: 'bottom',
-    overlayX: align,
-    overlayY: 'top',
-    offsetY: GAP,
+    originX: side === 'right' ? 'end' : 'start',
+    originY: verticalAlign,
+    overlayX: side === 'right' ? 'start' : 'end',
+    overlayY: verticalAlign,
+    offsetX: side === 'right' ? offset : -offset,
   };
 }
 
-function getPlacementFromPosition(position: ConnectionPositionPair): PopoverPlacement {
+function getSideFromPosition(position: ConnectionPositionPair): PopoverSide {
   if (position.originY === 'top' && position.overlayY === 'bottom') return 'top';
-  return 'bottom';
+  if (position.originY === 'bottom' && position.overlayY === 'top') return 'bottom';
+  if (position.originX === 'end' && position.overlayX === 'start') return 'right';
+  return 'left';
 }
 
 @Component({
@@ -81,9 +95,10 @@ function getPlacementFromPosition(position: ConnectionPositionPair): PopoverPlac
           tabindex="-1"
           role="dialog"
           [id]="popover.contentId"
-          [attr.aria-labelledby]="popover.titleId"
+          [attr.aria-label]="computedAriaLabel()"
+          [attr.aria-labelledby]="computedAriaLabelledBy()"
           [attr.aria-describedby]="popover.descId"
-          [attr.data-placement]="renderedPlacement()"
+          [attr.data-side]="renderedSide()"
           [class]="panelClass()"
           (animationend)="onLeaveAnimationEnd($event)"
         >
@@ -104,10 +119,22 @@ export class PopoverContentComponent {
   private readonly destroyRef = inject(DestroyRef);
 
   readonly class = input<string | undefined>();
+  readonly side = input<PopoverSide>('bottom');
+  readonly sideOffset = input(DEFAULT_SIDE_OFFSET, { transform: numberAttribute });
+  readonly ariaLabel = input<string | undefined>();
+  readonly ariaLabelledBy = input<string | undefined>();
 
   protected readonly scrollStrategy = this.overlay.scrollStrategies.close();
-  protected readonly renderedPlacement = signal<PopoverPlacement>('bottom');
+  protected readonly renderedSide = signal<PopoverSide>('bottom');
   private readonly panelEl = viewChild<ElementRef<HTMLElement>>('panelEl');
+  private readonly title = contentChild(PopoverTitleComponent);
+
+  protected readonly computedAriaLabelledBy = computed(
+    () => this.ariaLabelledBy() ?? (this.title() ? this.popover.titleId : null),
+  );
+  protected readonly computedAriaLabel = computed(() =>
+    this.computedAriaLabelledBy() ? null : (this.ariaLabel() ?? null),
+  );
 
   private readonly _leaving = signal(false);
   private _leaveTimer: ReturnType<typeof setTimeout> | undefined;
@@ -119,13 +146,13 @@ export class PopoverContentComponent {
 
   protected readonly positions: Signal<ConnectionPositionPair[]> = computed(() => {
     const align = this.popover.align();
-    return FALLBACK_PLACEMENTS.map(placement => positionFor(placement, align));
+    const offset = this.sideOffset();
+    return fallbackSides(this.side()).map((side) => positionFor(side, align, offset));
   });
 
   constructor() {
     effect(() => {
-      this.popover.align();
-      this.renderedPlacement.set('bottom');
+      this.renderedSide.set(this.side());
     });
 
     // Watch for external isOpen → false transitions and play leave animation
@@ -152,7 +179,7 @@ export class PopoverContentComponent {
     ),
   );
 
-  protected requestClose(): void {
+  requestClose(): void {
     if (this._leaving() || !this.popover.isOpen()) return;
     this.popover.setOpen(false);
     // isOpen change triggers the effect which calls _startLeave
@@ -164,11 +191,11 @@ export class PopoverContentComponent {
    * tabindex="-1" exists specifically as that fallback target since popover content
    * is often not just static text — see the docs "Dimensions" example).
    */
-  protected onAttach(): void {
+  onAttach(): void {
     this.panelEl()?.nativeElement.focus();
   }
 
-  protected onDetach(): void {
+  onDetach(): void {
     this._endLeave();
     if (this.popover.isOpen()) {
       this.popover.setOpen(false);
@@ -176,12 +203,12 @@ export class PopoverContentComponent {
   }
 
   /** 退場 CSS 動畫（animate-popover-out）真的播完時觸發，是結束 leaving 狀態的主要途徑 */
-  protected onLeaveAnimationEnd(event: AnimationEvent): void {
+  onLeaveAnimationEnd(event: AnimationEvent): void {
     if (event.target !== event.currentTarget || !this._leaving()) return;
     this._endLeave();
   }
 
-  protected handleOverlayKeydown(event: KeyboardEvent): void {
+  handleOverlayKeydown(event: KeyboardEvent): void {
     if (event.key !== 'Escape') return;
     event.preventDefault();
     event.stopPropagation();
@@ -192,8 +219,8 @@ export class PopoverContentComponent {
     this.popover.triggerOrigin?.elementRef.nativeElement.focus();
   }
 
-  protected handlePositionChange(event: ConnectedOverlayPositionChange): void {
-    this.renderedPlacement.set(getPlacementFromPosition(event.connectionPair));
+  handlePositionChange(event: ConnectedOverlayPositionChange): void {
+    this.renderedSide.set(getSideFromPosition(event.connectionPair));
   }
 
   private _startLeave(): void {
diff --git a/registry/components/popover/popover.type.ts b/registry/components/popover/popover.type.ts
index 6447f23..6a724af 100644
--- a/registry/components/popover/popover.type.ts
+++ b/registry/components/popover/popover.type.ts
@@ -1 +1,2 @@
 export type PopoverAlign = 'start' | 'center' | 'end';
+export type PopoverSide = 'top' | 'right' | 'bottom' | 'left';
diff --git a/registry/components/radio/radio-group.component.ts b/registry/components/radio/radio-group.component.ts
index 1ce0961..cf77d12 100644
--- a/registry/components/radio/radio-group.component.ts
+++ b/registry/components/radio/radio-group.component.ts
@@ -14,9 +14,9 @@ import {
 import { _IdGenerator } from '@angular/cdk/a11y';
 import { NG_VALUE_ACCESSOR } from '@angular/forms';
 import { cn } from '../shared/utils';
-import { SanringCvaBase, SanringFieldControlAdapter } from '../shared/cva-base';
 import { FieldType, SANRING_FIELD_CONTROL } from '../field/field.type';
-import { RadioOrientation, RadioValue } from './radio.types';
+import { SanringCvaBase, SanringFieldControlAdapter } from '../shared/cva-base';
+import { RadioOrientation, RadioSize, RadioValue } from './radio.types';
 import { RadioItemComponent } from './radio-item.component';
 
 @Component({
@@ -67,6 +67,7 @@ export class RadioGroupComponent extends SanringCvaBase<RadioValue | null> {
   readonly required = input(false, { transform: booleanAttribute });
   readonly disabled = input(false, { transform: booleanAttribute });
   readonly orientation = input<RadioOrientation>(RadioOrientation.Vertical);
+  readonly size = input<RadioSize>('md');
   readonly ariaLabel = input<string | undefined>();
   readonly ariaLabelledBy = input<string | undefined>();
   readonly ariaDescribedBy = input<string | undefined>();
diff --git a/registry/components/radio/radio-item.component.ts b/registry/components/radio/radio-item.component.ts
index 0db247e..ea0764d 100644
--- a/registry/components/radio/radio-item.component.ts
+++ b/registry/components/radio/radio-item.component.ts
@@ -11,13 +11,9 @@ import {
 import { _IdGenerator } from '@angular/cdk/a11y';
 import { LucideCircle } from '@lucide/angular';
 import { cn } from '../shared/utils';
-import {
-  RADIO_INDICATOR_ICON_CLASS,
-  SELECTION_CONTROL_BASE_CLASS,
-  SELECTION_CONTROL_FOCUS_CLASS,
-} from '../shared/component-styles';
+import { SELECTION_CONTROL_BASE_CLASS, SELECTION_CONTROL_FOCUS_CLASS } from '../shared/component-styles';
 import { RadioGroupComponent } from './radio-group.component';
-import { RADIO_SIZE_CLASS } from './radio.styles';
+import { RADIO_INDICATOR_ICON_SIZE_CLASSES, RADIO_SIZE_CLASSES } from './radio.styles';
 import { RadioValue } from './radio.types';
 
 @Component({
@@ -48,15 +44,13 @@ import { RadioValue } from './radio.types';
     >
       @if (isChecked()) {
         <span class="flex items-center justify-center text-current animate-in zoom-in-50">
-          <svg lucideCircle [class]="radioIndicatorIconClass"></svg>
+          <svg lucideCircle [class]="radioIndicatorIconClass()"></svg>
         </span>
       }
     </button>
   `,
 })
 export class RadioItemComponent {
-  protected readonly radioIndicatorIconClass = RADIO_INDICATOR_ICON_CLASS;
-
   readonly class = input<string | undefined>();
   readonly id = input(inject(_IdGenerator).getId('sanring-radio-', true));
   readonly value = input.required<RadioValue>();
@@ -71,6 +65,10 @@ export class RadioItemComponent {
 
   protected isChecked = computed(() => this.group?.valueSignal() === this.value());
   protected isDisabled = computed(() => this.disabled() || (this.group?.isDisabled() ?? false));
+  protected readonly size = computed(() => this.group?.size() ?? 'md');
+  protected readonly radioIndicatorIconClass = computed(
+    () => RADIO_INDICATOR_ICON_SIZE_CLASSES[this.size()],
+  );
   protected tabIndex = computed(() => {
     if (!this.group) return 0;
     return this.group.activeTabItem() === this ? 0 : -1;
@@ -79,7 +77,7 @@ export class RadioItemComponent {
     cn(
       SELECTION_CONTROL_BASE_CLASS,
       SELECTION_CONTROL_FOCUS_CLASS,
-      RADIO_SIZE_CLASS,
+      RADIO_SIZE_CLASSES[this.size()],
       'rounded-full border border-[var(--sanring-primary)] text-[var(--sanring-primary)]',
       'data-[state=checked]:border-[var(--sanring-primary)]',
       this.class(),
diff --git a/registry/components/radio/radio.styles.ts b/registry/components/radio/radio.styles.ts
index 3d25cf5..6e7cdda 100644
--- a/registry/components/radio/radio.styles.ts
+++ b/registry/components/radio/radio.styles.ts
@@ -1 +1,13 @@
-export const RADIO_SIZE_CLASS = 'aspect-square h-4 w-4';
+import type { RadioSize } from './radio.types';
+
+export const RADIO_SIZE_CLASSES: Record<RadioSize, string> = {
+  sm: 'aspect-square h-3 w-3',
+  md: 'aspect-square h-4 w-4',
+  lg: 'aspect-square h-5 w-5',
+};
+
+export const RADIO_INDICATOR_ICON_SIZE_CLASSES: Record<RadioSize, string> = {
+  sm: 'h-2 w-2 fill-current text-current',
+  md: 'h-2.5 w-2.5 fill-current text-current',
+  lg: 'h-3 w-3 fill-current text-current',
+};
diff --git a/registry/components/radio/radio.types.ts b/registry/components/radio/radio.types.ts
index 6d647ae..1cb162d 100644
--- a/registry/components/radio/radio.types.ts
+++ b/registry/components/radio/radio.types.ts
@@ -1,4 +1,5 @@
 export type RadioValue = string;
+export type RadioSize = 'sm' | 'md' | 'lg';
 
 export enum RadioOrientation {
   Horizontal = 'horizontal',
diff --git a/registry/components/sheet/sheet-content.component.ts b/registry/components/sheet/sheet-content.component.ts
index ff464fa..9a8e6f7 100644
--- a/registry/components/sheet/sheet-content.component.ts
+++ b/registry/components/sheet/sheet-content.component.ts
@@ -11,6 +11,7 @@ import {
   TemplateRef,
   ViewContainerRef,
   afterNextRender,
+  booleanAttribute,
   computed,
   effect,
   inject,
@@ -20,8 +21,13 @@ import {
   viewChild,
   contentChild,
 } from '@angular/core';
+import { LucideX } from '@lucide/angular';
 import { cn } from '../shared/utils';
-import { OVERLAY_SURFACE_CLASS } from '../shared/component-styles';
+import {
+  OVERLAY_ABSOLUTE_CLOSE_BUTTON_CLASS,
+  OVERLAY_CLOSE_ICON_CLASS,
+  OVERLAY_SURFACE_CLASS,
+} from '../shared/component-styles';
 import { SHEET_LEAVE_DURATION_MS } from '../shared/component-timing';
 import { SheetComponent } from './sheet.component';
 import { SheetDescriptionComponent } from './sheet-description.component';
@@ -54,7 +60,7 @@ const SIDE_LEAVE: Record<SheetSide, string> = {
   selector: 'sanring-sheet-content',
   standalone: true,
   changeDetection: ChangeDetectionStrategy.OnPush,
-  imports: [CdkTrapFocus],
+  imports: [CdkTrapFocus, LucideX],
   host: {
     '(document:keydown.escape)': 'onEscape()',
   },
@@ -77,6 +83,18 @@ const SIDE_LEAVE: Record<SheetSide, string> = {
         (animationend)="onLeaveAnimationEnd($event)"
       >
         <ng-content></ng-content>
+
+        @if (showClose()) {
+          <button
+            type="button"
+            [attr.aria-label]="closeAriaLabel()"
+            (click)="requestClose()"
+            [class]="closeButtonClass"
+          >
+            <svg lucideX [class]="closeIconClass"></svg>
+            <span class="sr-only">關閉</span>
+          </button>
+        }
       </div>
     </ng-template>
   `,
@@ -95,8 +113,13 @@ export class SheetContentComponent {
   private readonly title = contentChild(SheetTitleComponent);
   private readonly description = contentChild(SheetDescriptionComponent);
 
+  protected readonly closeButtonClass = OVERLAY_ABSOLUTE_CLOSE_BUTTON_CLASS;
+  protected readonly closeIconClass = OVERLAY_CLOSE_ICON_CLASS;
+
   readonly side = input<SheetSide>('right');
   readonly class = input<string | undefined>();
+  readonly showClose = input(true, { transform: booleanAttribute });
+  readonly closeAriaLabel = input('關閉面板');
   /** Accessible-name fallback used when no SheetTitle is projected. */
   readonly ariaLabel = input<string | undefined>('Sheet');
   /** Explicit labelling relationship; takes precedence over SheetTitle and ariaLabel. */
diff --git a/registry/components/sheet/sheet-header.component.ts b/registry/components/sheet/sheet-header.component.ts
index ae81838..bf32ae5 100644
--- a/registry/components/sheet/sheet-header.component.ts
+++ b/registry/components/sheet/sheet-header.component.ts
@@ -10,5 +10,16 @@ import { cn } from '../shared/utils';
 })
 export class SheetHeaderComponent {
   readonly class = input<string | undefined>();
-  protected readonly hostClass = computed(() => cn('flex flex-col gap-1.5', this.class()));
+
+  readonly align = input<'start' | 'center' | undefined>(undefined);
+
+  protected readonly hostClass = computed(() =>
+    cn(
+      'flex flex-col gap-1.5',
+      this.align() === 'center' && 'items-center text-center',
+      this.align() === 'start' && 'items-start text-left',
+      !this.align() && 'text-center sm:text-left',
+      this.class(),
+    ),
+  );
 }
diff --git a/registry/components/table/cell.directive.ts b/registry/components/table/cell.directive.ts
index 27ee31e..c118ecc 100644
--- a/registry/components/table/cell.directive.ts
+++ b/registry/components/table/cell.directive.ts
@@ -68,7 +68,9 @@ export class TableHeaderCellDirective {
   standalone: true,
   // 🧠 當 <td> 蛋糕出生時，我們強行把 CDK 原生的 CdkCell 邏輯塞進去！
   hostDirectives: [CdkCell],
-  host: { class: 'p-4 align-middle [&:has([role=checkbox])]:pr-0' },
+  host: {
+    class: 'p-4 align-middle [&:has([role=checkbox])]:pr-0',
+  },
 })
 export class TableCellDirective {}
 
@@ -77,6 +79,8 @@ export class TableCellDirective {}
   standalone: true,
   // 🧠 當 footer 蛋糕出生時，我們強行把 CDK 原生的 CdkFooterCell 邏輯塞進去！
   hostDirectives: [CdkFooterCell],
-  host: { class: 'border-t p-4 align-middle font-medium [&:has([role=checkbox])]:pr-0' },
+  host: {
+    class: 'border-t p-4 align-middle font-medium [&:has([role=checkbox])]:pr-0',
+  },
 })
 export class TableFooterCellDirective {}
diff --git a/registry/components/table/table-container.component.ts b/registry/components/table/table-container.component.ts
index bb0e6b1..93a9094 100644
--- a/registry/components/table/table-container.component.ts
+++ b/registry/components/table/table-container.component.ts
@@ -1,14 +1,21 @@
-import { ChangeDetectionStrategy, Component, computed, input } from '@angular/core';
+import { ChangeDetectionStrategy, Component, computed, input, ViewEncapsulation } from '@angular/core';
 import { cn } from '../shared/utils';
 
 @Component({
   selector: 'sanring-table-container',
   standalone: true,
   changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
   template: `<ng-content></ng-content>`,
   host: {
     '[class]': 'containerClass()',
   },
+  styles: `
+    sanring-table-container .cdk-table-sticky,
+    sanring-table-container .cdk-table-sticky-end {
+      background-color: var(--sanring-background);
+    }
+  `,
 })
 export class TableContainerComponent {
   readonly class = input<string | undefined>();
diff --git a/registry/components/transfer/transfer-panel.component.ts b/registry/components/transfer/transfer-panel.component.ts
index 14fbf55..6ece486 100644
--- a/registry/components/transfer/transfer-panel.component.ts
+++ b/registry/components/transfer/transfer-panel.component.ts
@@ -34,7 +34,9 @@ export class TransferPanelComponent {
 
   // target 面板在 one-way 模式下變成唯讀展示：不能勾選，也就無法被搬回 source
   readonly interactive = computed(
-    () => !(this.direction() === 'target' && this.transfer.mode() === 'one-way'),
+    () =>
+      !this.transfer.isDisabled() &&
+      !(this.direction() === 'target' && this.transfer.mode() === 'one-way'),
   );
 
   // List/Item 元件只認得「這個 panel 該顯示哪些 key、勾選狀態怎麼查/切換」，
diff --git a/registry/components/transfer/transfer.component.ts b/registry/components/transfer/transfer.component.ts
index 5e50cb0..caccd98 100644
--- a/registry/components/transfer/transfer.component.ts
+++ b/registry/components/transfer/transfer.component.ts
@@ -1,4 +1,12 @@
-import { ChangeDetectionStrategy, Component, computed, input, model, signal } from '@angular/core';
+import {
+  ChangeDetectionStrategy,
+  Component,
+  booleanAttribute,
+  computed,
+  input,
+  model,
+  signal,
+} from '@angular/core';
 import { cn } from '../shared/utils';
 import { TransferItem, TransferMode } from './transfer.type';
 
@@ -9,13 +17,19 @@ import { TransferItem, TransferMode } from './transfer.type';
   template: `<ng-content></ng-content>`,
   host: {
     '[class]': 'rootClass()',
+    role: 'group',
+    '[attr.aria-label]': 'ariaLabel()',
+    '[attr.aria-disabled]': 'isDisabled() || null',
   },
 })
 export class TransferComponent {
   readonly items = input<TransferItem[]>([]);
   readonly class = input<string | undefined>();
+  readonly disabled = input(false, { transform: booleanAttribute });
+  readonly ariaLabel = input<string | undefined>();
 
   protected readonly rootClass = computed(() => cn(this.class()));
+  readonly isDisabled = computed(() => this.disabled());
   // 雙向綁定：目前在右側（target）的 key 清單，父層可用 [(selectedKeys)] 拿到結果
   readonly selectedKeys = model<string[]>([]);
   readonly mode = input<TransferMode>('two-way');
@@ -46,6 +60,7 @@ export class TransferComponent {
   }
 
   toggleSourceSelected(key: string): void {
+    if (this.isDisabled()) return;
     if (this.itemsByKey().get(key)?.disabled) return;
     this.sourceSelectedKeys.update((keys) =>
       keys.includes(key) ? keys.filter((k) => k !== key) : [...keys, key],
@@ -54,6 +69,7 @@ export class TransferComponent {
 
   toggleTargetSelected(key: string): void {
     // one-way 模式下 target 是唯讀展示，不接受勾選
+    if (this.isDisabled()) return;
     if (this.mode() === 'one-way') return;
     if (this.itemsByKey().get(key)?.disabled) return;
     this.targetSelectedKeys.update((keys) =>
@@ -62,6 +78,7 @@ export class TransferComponent {
   }
 
   moveToTarget(): void {
+    if (this.isDisabled()) return;
     // 用當下的 sourceItems 過濾一次，避免 items() 從外部變動後 sourceSelectedKeys 裡殘留已經不存在的 key
     const validKeys = new Set(this.sourceItems().map((item) => item.key));
     const moving = this.sourceSelectedKeys().filter((key) => validKeys.has(key));
@@ -72,6 +89,7 @@ export class TransferComponent {
   }
 
   moveToSource(): void {
+    if (this.isDisabled()) return;
     if (this.mode() === 'one-way') return;
     const moving = new Set(this.targetSelectedKeys().filter((key) => this.itemsByKey().has(key)));
     if (moving.size === 0) return;
@@ -81,10 +99,12 @@ export class TransferComponent {
   }
 
   setSourceSelectedKeys(keys: string[]): void {
+    if (this.isDisabled()) return;
     this.sourceSelectedKeys.set(keys);
   }
 
   setTargetSelectedKeys(keys: string[]): void {
+    if (this.isDisabled()) return;
     if (this.mode() === 'one-way') return;
     this.targetSelectedKeys.set(keys);
   }
diff --git a/registry/registry.json b/registry/registry.json
index d017a19..ae86deb 100644
--- a/registry/registry.json
+++ b/registry/registry.json
@@ -618,7 +618,8 @@
         "component-timing"
       ],
       "peerDependencies": {
-        "@angular/cdk": "^22.0.0"
+        "@angular/cdk": "^22.0.0",
+        "@lucide/angular": "^1.18.0"
       },
       "files": [
         "sheet/sheet.component.ts",
@@ -888,7 +889,8 @@
       ],
       "peerDependencies": {
         "@angular/aria": "^22.0.0",
-        "@angular/cdk": "^22.0.0"
+        "@angular/cdk": "^22.0.0",
+        "@lucide/angular": "^1.18.0"
       },
       "files": [
         "dropdown-menu/dropdown-menu.component.ts",
@@ -897,6 +899,9 @@
         "dropdown-menu/dropdown-menu-item.directive.ts",
         "dropdown-menu/dropdown-menu-label.component.ts",
         "dropdown-menu/dropdown-menu-separator.component.ts",
+        "dropdown-menu/dropdown-menu-sub.component.ts",
+        "dropdown-menu/dropdown-menu-sub-content.component.ts",
+        "dropdown-menu/dropdown-menu-sub-trigger.component.ts",
         "dropdown-menu/dropdown-menu-trigger.directive.ts",
         "dropdown-menu/dropdown-menu.type.ts",
         "dropdown-menu/index.ts"
diff --git a/registry/shared/component-styles.ts b/registry/shared/component-styles.ts
index 853090f..6e1826c 100644
--- a/registry/shared/component-styles.ts
+++ b/registry/shared/component-styles.ts
@@ -19,6 +19,8 @@ export const OVERLAY_SURFACE_CLASS =
   'border border-[var(--sanring-border)] bg-[var(--sanring-elevated)] text-[var(--sanring-foreground)] shadow-lg';
 export const POPOVER_SURFACE_CLASS = 'z-50 w-72 rounded-md p-4 shadow-md outline-none';
 export const OVERLAY_CLOSE_ICON_CLASS = 'size-4';
+export const OVERLAY_ABSOLUTE_CLOSE_BUTTON_CLASS =
+  'absolute right-4 top-4 rounded-[var(--sanring-radius-xs)] text-[var(--sanring-muted)] opacity-70 ring-offset-[var(--sanring-surface)] transition-colors transition-opacity hover:text-[var(--sanring-foreground)] hover:opacity-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--sanring-border-strong)] focus-visible:ring-offset-2 disabled:pointer-events-none';
 
 export const SELECTION_CONTROL_BASE_CLASS =
   'peer flex shrink-0 items-center justify-center transition-colors disabled:cursor-not-allowed disabled:opacity-50';

From 03dbf7cbf0c24bdf492f26451b046a18312d97ef Mon Sep 17 00:00:00 2001
From: jack755051 <jack755051@gmail.com>
Date: Wed, 23 Sep 2026 01:18:05 +0800
Subject: [PATCH 12/13] docs(docs): align recent-changes with page sections

Render recent changes through the shared section chrome, surface it in
the TOC, drop the unused hint component, and restyle the page header.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .../component-page-hint.component.ts          | 18 --------
 ...component-page-recent-changes.component.ts | 43 ++++++++-----------
 .../component-page-section.component.ts       | 41 ++++++++++--------
 .../component-page.component.ts               | 17 +++++++-
 .../docs-page-header.component.ts             | 13 +++++-
 .../src/app/layouts/component-page/index.ts   |  1 -
 .../combobox/combobox-page.component.ts       | 18 ++++----
 7 files changed, 75 insertions(+), 76 deletions(-)
 delete mode 100644 apps/docs/src/app/layouts/component-page/component-page-hint.component.ts

diff --git a/apps/docs/src/app/layouts/component-page/component-page-hint.component.ts b/apps/docs/src/app/layouts/component-page/component-page-hint.component.ts
deleted file mode 100644
index 46520d3..0000000
--- a/apps/docs/src/app/layouts/component-page/component-page-hint.component.ts
+++ /dev/null
@@ -1,18 +0,0 @@
-import { Component, computed, input } from '@angular/core';
-import { cn } from '@sanring/ui';
-
-@Component({
-  selector: 'app-component-page-hint',
-  standalone: true,
-  template: `<ng-content />`,
-  host: {
-    '[class]': 'hintClass()',
-  },
-})
-export class ComponentPageHintComponent {
-  readonly class = input<string | undefined>();
-
-  protected readonly hintClass = computed(() =>
-    cn('m-0 text-xs leading-5 text-[var(--docs-muted)]', this.class()),
-  );
-}
diff --git a/apps/docs/src/app/layouts/component-page/component-page-recent-changes.component.ts b/apps/docs/src/app/layouts/component-page/component-page-recent-changes.component.ts
index 678f4be..5b31866 100644
--- a/apps/docs/src/app/layouts/component-page/component-page-recent-changes.component.ts
+++ b/apps/docs/src/app/layouts/component-page/component-page-recent-changes.component.ts
@@ -1,5 +1,6 @@
 import { Component, computed, inject, input } from '@angular/core';
 import { RouterLink } from '@angular/router';
+import { ComponentPageSectionDefinition } from '../../docs-schema/component-page.types';
 import { DocsComponentId } from '../../navigation/docs-navigation';
 import { I18nService } from '../../i18n/i18n.service';
 import {
@@ -7,6 +8,7 @@ import {
   ComponentChangeType,
   cliVersionChangelog,
 } from '../../pages/changelog/component-changelog';
+import { ComponentPageSectionComponent } from './component-page-section.component';
 
 interface ComponentRecentChange {
   version: string;
@@ -45,35 +47,20 @@ function renderInlineCode(text: string): string {
 @Component({
   selector: 'app-component-page-recent-changes',
   standalone: true,
-  imports: [RouterLink],
+  imports: [RouterLink, ComponentPageSectionComponent],
   template: `
     @if (changes().length > 0) {
-      <section
-        id="recent-changes"
-        class="docs-panel mt-16 overflow-hidden"
-        [attr.aria-labelledby]="'recent-changes-title'"
-      >
-        <div
-          class="flex min-w-0 flex-wrap items-center justify-between gap-3 border-b border-[var(--docs-border)] bg-[var(--docs-surface)] px-3.5 py-3"
+      <app-component-page-section [section]="section">
+        <a
+          section-action
+          class="mt-1.5 shrink-0 font-mono text-xs font-medium text-[var(--docs-muted)] no-underline transition-colors hover:text-[var(--docs-fg)] focus-visible:rounded-[var(--sanring-radius-xs)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--docs-focus-ring)]"
+          routerLink="/changelog"
         >
-          <div class="min-w-0">
-            <h2
-              id="recent-changes-title"
-              class="m-0 text-base font-semibold leading-tight text-[var(--docs-fg)]"
-            >
-              {{ i18n.t('component.recentChanges.title') }}
-            </h2>
-          </div>
-          <a
-            class="shrink-0 font-mono text-xs font-medium text-[var(--docs-muted)] no-underline transition-colors hover:text-[var(--docs-fg)] focus-visible:rounded-[var(--sanring-radius-xs)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--docs-focus-ring)]"
-            routerLink="/changelog"
-          >
-            {{ i18n.t('component.recentChanges.viewAll') }}
-          </a>
-        </div>
+          {{ i18n.t('component.recentChanges.viewAll') }}
+        </a>
 
         <ol
-          class="m-0 list-none divide-y divide-[color-mix(in_srgb,var(--docs-border)_82%,transparent)] p-0"
+          class="docs-panel m-0 list-none divide-y divide-[color-mix(in_srgb,var(--docs-border)_82%,transparent)] overflow-hidden p-0"
         >
           @for (entry of changes(); track entry.version + '-' + $index) {
             <li
@@ -107,13 +94,19 @@ function renderInlineCode(text: string): string {
             </li>
           }
         </ol>
-      </section>
+      </app-component-page-section>
     }
   `,
 })
 export class ComponentPageRecentChangesComponent {
   readonly componentId = input<DocsComponentId | null>(null);
 
+  protected readonly section = {
+    id: 'recent-changes',
+    titleKey: 'component.recentChanges.title',
+    descriptionKey: 'component.recentChanges.description',
+  } as const satisfies ComponentPageSectionDefinition;
+
   protected readonly i18n = inject(I18nService);
   protected readonly chipClass = CHIP_CLASS;
   protected readonly typeClass = TYPE_CLASS;
diff --git a/apps/docs/src/app/layouts/component-page/component-page-section.component.ts b/apps/docs/src/app/layouts/component-page/component-page-section.component.ts
index e1ace28..abe303b 100644
--- a/apps/docs/src/app/layouts/component-page/component-page-section.component.ts
+++ b/apps/docs/src/app/layouts/component-page/component-page-section.component.ts
@@ -21,27 +21,30 @@ interface StructuredDescriptionItem {
   template: `
     <section [id]="sectionId" [class]="sectionClass">
       <div class="mb-3.5">
-        <div [class]="headingWrapClass">
-          @if (level === 2) {
-            <span class="mt-1.5 h-5 w-0.5 shrink-0 bg-[var(--docs-accent)]" aria-hidden="true"></span>
-          }
-          @switch (level) {
-            @case (4) {
-              <h4 [class]="headingClass">
-                {{ i18n.t(section.titleKey) }}
-              </h4>
-            }
-            @case (3) {
-              <h3 [class]="headingClass">
-                {{ i18n.t(section.titleKey) }}
-              </h3>
+        <div class="flex min-w-0 items-start justify-between gap-3">
+          <div [class]="headingWrapClass">
+            @if (level === 2) {
+              <span class="mt-1.5 h-5 w-0.5 shrink-0 bg-[var(--docs-accent)]" aria-hidden="true"></span>
             }
-            @default {
-              <h2 [class]="headingClass">
-                {{ i18n.t(section.titleKey) }}
-              </h2>
+            @switch (level) {
+              @case (4) {
+                <h4 [class]="headingClass">
+                  {{ i18n.t(section.titleKey) }}
+                </h4>
+              }
+              @case (3) {
+                <h3 [class]="headingClass">
+                  {{ i18n.t(section.titleKey) }}
+                </h3>
+              }
+              @default {
+                <h2 [class]="headingClass">
+                  {{ i18n.t(section.titleKey) }}
+                </h2>
+              }
             }
-          }
+          </div>
+          <ng-content select="[section-action]" />
         </div>
 
         @if (section.descriptionKey) {
diff --git a/apps/docs/src/app/layouts/component-page/component-page.component.ts b/apps/docs/src/app/layouts/component-page/component-page.component.ts
index 2aefbf6..c701bd6 100644
--- a/apps/docs/src/app/layouts/component-page/component-page.component.ts
+++ b/apps/docs/src/app/layouts/component-page/component-page.component.ts
@@ -2,6 +2,7 @@ import { Component, effect, inject, Input, OnChanges, OnDestroy, input } from '@
 import { ComponentPageSectionDefinition } from '../../docs-schema/component-page.types';
 import { DocsComponentId } from '../../navigation/docs-navigation';
 import { I18nService } from '../../i18n/i18n.service';
+import { cliVersionChangelog } from '../../pages/changelog/component-changelog';
 import { DocsTocItem, DocsTocService } from '../../shell/toc/docs-toc.service';
 import { ComponentPageRecentChangesComponent } from './component-page-recent-changes.component';
 
@@ -46,7 +47,21 @@ export class ComponentPageComponent implements OnChanges, OnDestroy {
   }
 
   private updateToc() {
-    this.toc.setItems(this.flattenSections(this.sections));
+    const items = this.flattenSections(this.sections);
+    const componentId = this.componentId();
+    const hasChanges =
+      !!componentId &&
+      cliVersionChangelog.some((version) =>
+        version.changes.some((change) => change.componentIds?.includes(componentId)),
+      );
+    if (hasChanges) {
+      items.push({
+        id: 'recent-changes',
+        label: this.i18n.t('component.recentChanges.title'),
+        level: 2,
+      });
+    }
+    this.toc.setItems(items);
   }
 
   private flattenSections(sections: readonly ComponentPageSectionDefinition[]): DocsTocItem[] {
diff --git a/apps/docs/src/app/layouts/component-page/docs-page-header.component.ts b/apps/docs/src/app/layouts/component-page/docs-page-header.component.ts
index 51bb495..ed843e2 100644
--- a/apps/docs/src/app/layouts/component-page/docs-page-header.component.ts
+++ b/apps/docs/src/app/layouts/component-page/docs-page-header.component.ts
@@ -7,8 +7,17 @@ import { Component, Input } from '@angular/core';
     class: 'block min-w-0',
   },
   template: `
-    <header class="docs-panel-lg relative mb-12 p-6 max-[720px]:p-5">
-      <div class="min-w-0">
+    <header class="docs-panel-lg relative mb-12 overflow-hidden p-6 max-[720px]:p-5">
+      <div
+        class="pointer-events-none absolute inset-x-0 top-0 h-1 bg-[linear-gradient(90deg,var(--docs-accent),var(--docs-accent-alt),var(--docs-accent-warm))]"
+        aria-hidden="true"
+      ></div>
+      <div
+        class="pointer-events-none absolute inset-0 opacity-60 [background-image:linear-gradient(var(--docs-bg-grid)_1px,transparent_1px),linear-gradient(90deg,var(--docs-bg-grid)_1px,transparent_1px)] [background-size:32px_32px]"
+        aria-hidden="true"
+      ></div>
+
+      <div class="relative z-10 min-w-0">
         @if (eyebrow) {
           <p class="docs-eyebrow mb-3 font-mono">
             <span class="min-w-0 truncate">{{ eyebrow }}</span>
diff --git a/apps/docs/src/app/layouts/component-page/index.ts b/apps/docs/src/app/layouts/component-page/index.ts
index 2b08e21..5ad9501 100644
--- a/apps/docs/src/app/layouts/component-page/index.ts
+++ b/apps/docs/src/app/layouts/component-page/index.ts
@@ -2,7 +2,6 @@ export * from './component-page-api-table.component';
 export * from './component-page-code-block.component';
 export * from './component-page-code-previewer.component';
 export * from './component-page-header.component';
-export * from './component-page-hint.component';
 export * from './component-page-installation.component';
 export * from './component-page-keyboard-table.component';
 export * from './component-page-recent-changes.component';
diff --git a/apps/docs/src/app/pages/components/combobox/combobox-page.component.ts b/apps/docs/src/app/pages/components/combobox/combobox-page.component.ts
index 3279ed9..fa6a4f9 100644
--- a/apps/docs/src/app/pages/components/combobox/combobox-page.component.ts
+++ b/apps/docs/src/app/pages/components/combobox/combobox-page.component.ts
@@ -16,7 +16,6 @@ import {
   ComponentPageCodePreviewer,
   ComponentPageComponent,
   ComponentPageHeaderComponent,
-  ComponentPageHintComponent,
   ComponentPageInstallationComponent,
   ComponentPageSectionComponent,
   ComponentPageUsageImportsComponent,
@@ -38,7 +37,6 @@ import { comboboxPage, comboboxPageExamples } from './combobox.docs';
     ComponentPageCodePreviewer,
     ComponentPageComponent,
     ComponentPageHeaderComponent,
-    ComponentPageHintComponent,
     ComponentPageInstallationComponent,
     ComponentPageSectionComponent,
     ComponentPageUsageImportsComponent,
@@ -78,9 +76,9 @@ import { comboboxPage, comboboxPageExamples } from './combobox.docs';
                   </sanring-combobox-list>
                 </sanring-combobox-content>
               </sanring-combobox>
-              <app-component-page-hint>
+              <p class="m-0 text-xs leading-5 text-[var(--docs-muted)]">
                 {{ i18n.t('combobox.demo.selected') }} {{ labelFor(framework) || '—' }}
-              </app-component-page-hint>
+              </p>
             </div>
           </div>
         </app-component-page-code-previewer>
@@ -224,18 +222,18 @@ import { comboboxPage, comboboxPageExamples } from './combobox.docs';
                       </sanring-combobox-list>
                     </sanring-combobox-content>
                   </sanring-combobox>
-                  <app-component-page-hint>
+                  <p class="m-0 text-xs leading-5 text-[var(--docs-muted)]">
                     {{ i18n.t('combobox.demo.selected') }} {{ library || '—' }}
-                  </app-component-page-hint>
+                  </p>
                 </div>
               </div>
             </app-component-page-code-previewer>
           </app-component-page-section>
 
           <app-component-page-section [section]="section('example-popup')">
-            <app-component-page-hint class="text-sm leading-6">
+            <p class="m-0 text-sm leading-6 text-[var(--docs-muted)]">
               {{ i18n.t('combobox.demo.popupDescription') }}
-            </app-component-page-hint>
+            </p>
             <app-component-page-code-previewer [code]="examples.popup" language="angular-html">
               <div previewer class="flex w-full min-h-[240px] items-start justify-center pt-8">
                 <div class="grid w-[min(360px,100%)] gap-2">
@@ -276,9 +274,9 @@ import { comboboxPage, comboboxPageExamples } from './combobox.docs';
           </app-component-page-section>
 
           <app-component-page-section [section]="section('example-clear')">
-            <app-component-page-hint class="text-sm leading-6">
+            <p class="m-0 text-sm leading-6 text-[var(--docs-muted)]">
               {{ i18n.t('combobox.demo.clearButtonDescription') }}
-            </app-component-page-hint>
+            </p>
             <app-component-page-code-previewer [code]="examples.clear" language="angular-html">
               <div previewer class="flex w-full min-h-[240px] items-start justify-center pt-8">
                 <div class="grid w-[min(360px,100%)] gap-2">

From 85c91cbbc18808d721dfc8bbcc61ec2830b3869b Mon Sep 17 00:00:00 2001
From: jack755051 <jack755051@gmail.com>
Date: Wed, 23 Sep 2026 01:18:10 +0800
Subject: [PATCH 13/13] chore: release @sanring/cli 0.25.1

Consume pending changesets and point docs version notes / updated
badges at 0.25.1 for P32 and the related field polish.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .changeset/count-inside-dialog-header-bg.md   |  5 --
 .changeset/login-remember-me-label.md         |  4 --
 .changeset/p32-sibling-api-alignment.md       |  5 --
 TODOLIST.md                                   |  2 +-
 .../pages/changelog/component-changelog.ts    | 64 ++++++++++++-------
 packages/cli/CHANGELOG.md                     |  8 +++
 packages/cli/package.json                     |  2 +-
 7 files changed, 50 insertions(+), 40 deletions(-)
 delete mode 100644 .changeset/count-inside-dialog-header-bg.md
 delete mode 100644 .changeset/login-remember-me-label.md
 delete mode 100644 .changeset/p32-sibling-api-alignment.md

diff --git a/.changeset/count-inside-dialog-header-bg.md b/.changeset/count-inside-dialog-header-bg.md
deleted file mode 100644
index 40a1ba9..0000000
--- a/.changeset/count-inside-dialog-header-bg.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-'@sanring/cli': patch
----
-
-Keep input/textarea/combobox counts inside the field on the right, add combobox chip wrap/ellipsis, and let dialog headers use a different background from the body.
diff --git a/.changeset/login-remember-me-label.md b/.changeset/login-remember-me-label.md
deleted file mode 100644
index a53fc98..0000000
--- a/.changeset/login-remember-me-label.md
+++ /dev/null
@@ -1,4 +0,0 @@
----
----
-
-Associate the login block remember-me label so eslint template/label-has-associated-control passes.
diff --git a/.changeset/p32-sibling-api-alignment.md b/.changeset/p32-sibling-api-alignment.md
deleted file mode 100644
index ae967d7..0000000
--- a/.changeset/p32-sibling-api-alignment.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-'@sanring/cli': patch
----
-
-Align sibling APIs on existing primitives: sheet close/header, radio size, a real dropdown submenu, popover side and aria fallback, transfer root disabled, and table sticky backgrounds.
diff --git a/TODOLIST.md b/TODOLIST.md
index 8a8a464..5ffbdfe 100644
--- a/TODOLIST.md
+++ b/TODOLIST.md
@@ -49,7 +49,7 @@
 
 2026-09-22 對 `packages/ui` 52 個正式元件做產品/API 掃描（公開 input/output、兄弟組件對齊、docs 是否超賣能力）。不是重跑 P3/P26/P30 的 a11y 稽核。`check-registry-parity.mjs` 與 `check-registry-sync.mjs` 當日皆綠（52/52）。官方目錄不缺新 primitive；該做的是把兄弟組件對齊，以及把 docs 已經講出去的能力做完。
 
-0.25.0 進行中的 input/textarea/combobox count、combobox chip wrap、dialog header `align`/獨立底色**不列入本項**，那些收斂完再看要不要疊。
+0.25.0 已出（blocks / dialog header align / field textarea projection）。0.25.1 收斂 input/textarea/combobox count、combobox chip wrap、dialog header 獨立底色，以及 P32 sibling API。
 
 ### 該做
 
diff --git a/apps/docs/src/app/pages/changelog/component-changelog.ts b/apps/docs/src/app/pages/changelog/component-changelog.ts
index 8e80ced..9d4b02d 100644
--- a/apps/docs/src/app/pages/changelog/component-changelog.ts
+++ b/apps/docs/src/app/pages/changelog/component-changelog.ts
@@ -36,63 +36,79 @@ function isPatch(version: string): boolean {
  */
 export const cliVersionChangelog: readonly CliVersionEntry[] = [
   {
-    version: '0.25.0',
-    date: '2026-09-21',
+    version: '0.25.1',
+    date: '2026-09-23',
     changes: [
       {
         type: 'added',
-        notable: true,
-        text: 'Registry gains a `blocks` category (`sanring add block/login`) and accepts `github:owner/repo` as a registry source.',
+        componentIds: ['sheet'],
+        text: '`sanring-sheet-content` renders a built-in close button (`showClose`, `closeAriaLabel`). `sanring-sheet-header` accepts `align` (`start` | `center`).',
       },
       {
         type: 'added',
-        componentIds: ['dialog'],
-        text: '`sanring-dialog-header` accepts `align` (`start` | `center`). Header `class` can set a background that is not the dialog body surface.',
+        componentIds: ['radio'],
+        text: '`sanring-radio-group` accepts `size` (`sm` | `md` | `lg`), matching checkbox and switch.',
       },
       {
         type: 'added',
-        componentIds: ['input', 'textarea'],
-        text: 'Docs examples show a live character count inside the control on the right, so `sanring-error-message` can stay below.',
+        componentIds: ['dropdown-menu'],
+        text: '`sanring-dropdown-menu-sub`, `sanring-dropdown-menu-sub-trigger`, and `sanring-dropdown-menu-sub-content` open a nested menu with Arrow Right / Arrow Left.',
       },
       {
         type: 'added',
-        componentIds: ['combobox'],
-        text: '`sanring-combobox-chip-input` and `sanring-combobox-chips` accept `wrap`. Single-line multiple selection overflows with an ellipsis; the selected/total count sits on the right of the field.',
+        componentIds: ['popover'],
+        text: '`sanring-popover-content` accepts four-way `side` and only sets `aria-labelledby` when a title is projected; `ariaLabel` is the fallback.',
+      },
+      {
+        type: 'added',
+        componentIds: ['transfer'],
+        text: '`sanring-transfer` accepts root `disabled` and `ariaLabel` on the `role="group"` host.',
       },
       {
         type: 'changed',
-        componentIds: ['field'],
-        text: '`sanring-field` now projects `textarea[sanringTextarea]` into the control slot, so a character-count description renders below the textarea instead of above it.',
+        componentIds: ['table'],
+        text: 'Sticky header, body, and footer cells use an opaque `--sanring-background` so scrolled text does not show through. Docs add loading skeleton and column-visibility recipes.',
       },
       {
         type: 'added',
-        componentIds: ['sheet'],
-        text: '`sanring-sheet-content` renders a built-in close button (`showClose`, `closeAriaLabel`). `sanring-sheet-header` accepts `align` (`start` | `center`).',
+        componentIds: ['dialog'],
+        text: '`sanring-dialog-header` `class` can set a background that is not the dialog body surface.',
       },
       {
         type: 'added',
-        componentIds: ['radio'],
-        text: '`sanring-radio-group` accepts `size` (`sm` | `md` | `lg`), matching checkbox and switch.',
+        componentIds: ['input', 'textarea'],
+        text: 'Docs examples show a live character count inside the control on the right, so `sanring-error-message` can stay below.',
       },
       {
         type: 'added',
-        componentIds: ['dropdown-menu'],
-        text: '`sanring-dropdown-menu-sub`, `sanring-dropdown-menu-sub-trigger`, and `sanring-dropdown-menu-sub-content` open a nested menu with Arrow Right / Arrow Left.',
+        componentIds: ['combobox'],
+        text: '`sanring-combobox-chip-input` and `sanring-combobox-chips` accept `wrap`. Single-line multiple selection overflows with an ellipsis; the selected/total count sits on the right of the field.',
       },
+      {
+        type: 'fixed',
+        componentIds: ['field'],
+        text: 'Floating labels animate with `scale` instead of swapping font sizes, and keep the notch gradient in both floated states.',
+      },
+    ],
+  },
+  {
+    version: '0.25.0',
+    date: '2026-09-21',
+    changes: [
       {
         type: 'added',
-        componentIds: ['popover'],
-        text: '`sanring-popover-content` accepts four-way `side` and only sets `aria-labelledby` when a title is projected; `ariaLabel` is the fallback.',
+        notable: true,
+        text: 'Registry gains a `blocks` category (`sanring add block/login`) and accepts `github:owner/repo` as a registry source.',
       },
       {
         type: 'added',
-        componentIds: ['transfer'],
-        text: '`sanring-transfer` accepts root `disabled` and `ariaLabel` on the `role="group"` host.',
+        componentIds: ['dialog'],
+        text: '`sanring-dialog-header` accepts `align` (`start` | `center`).',
       },
       {
         type: 'changed',
-        componentIds: ['table'],
-        text: 'Sticky header, body, and footer cells use an opaque `--sanring-background` so scrolled text does not show through. Docs add loading skeleton and column-visibility recipes.',
+        componentIds: ['field'],
+        text: '`sanring-field` now projects `textarea[sanringTextarea]` into the control slot, so a character-count description renders below the textarea instead of above it.',
       },
     ],
   },
diff --git a/packages/cli/CHANGELOG.md b/packages/cli/CHANGELOG.md
index f7aa9a8..4bb9614 100644
--- a/packages/cli/CHANGELOG.md
+++ b/packages/cli/CHANGELOG.md
@@ -1,5 +1,13 @@
 # @sanring/cli
 
+## 0.25.1
+
+### Patch Changes
+
+- 7b17eb9: Keep input/textarea/combobox counts inside the field on the right, add combobox chip wrap/ellipsis, and let dialog headers use a different background from the body.
+- Smooth the floating field label transition with scale instead of font-size swaps, and keep the notch gradient in both floated states.
+- a203334: Align sibling APIs on existing primitives: sheet close/header, radio size, a real dropdown submenu, popover side and aria fallback, transfer root disabled, and table sticky backgrounds.
+
 ## 0.25.0
 
 ### Minor Changes
diff --git a/packages/cli/package.json b/packages/cli/package.json
index 247393f..15ea47f 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@sanring/cli",
-  "version": "0.25.0",
+  "version": "0.25.1",
   "description": "CLI for adding Sanring UI components to your Angular project",
   "license": "MIT",
   "type": "module",