From e99a9fb274ffbe37ae580dc312eebc7e6b0c8216 Mon Sep 17 00:00:00 2001
From: oneao <hi_itao@163.com>
Date: Thu, 8 Oct 2026 22:38:34 +0800
Subject: [PATCH] u

---
 .../plans/g3-ui-重写-参照fms-vue_084cfb52.md  |  334 ++++++
 code/g3soft-libs/.gitignore                   |    4 +
 code/g3soft-libs/CODEBUDDY.md                 |   79 +-
 code/g3soft-libs/README.md                    |   13 +-
 .../docs/app/components/app/AppHeaderCTA.vue  |    6 +
 .../docs/app/components/content/ApiTable.vue  |  137 ---
 .../docs/content/framework/.navigation.yml    |    2 +
 .../framework/1.layout/.navigation.yml        |    2 +
 .../docs/content/framework/1.layout/index.md  |   21 +
 code/g3soft-libs/docs/content/index.md        |   28 +-
 .../content/ui/1.usage/getting-started.md     |    3 +-
 .../docs/content/ui/2.general/button-group.md |   64 ++
 .../docs/content/ui/2.general/button.md       |  187 ++-
 .../docs/content/ui/2.general/grid.md         |  123 ++
 .../docs/content/ui/2.general/segmented.md    |  123 ++
 .../docs/content/ui/2.general/space.md        |  107 ++
 .../docs/content/ui/2.general/tag.md          |  111 ++
 .../docs/content/ui/3.form/.navigation.yml    |    2 +
 .../docs/content/ui/3.form/checkbox.md        |  102 ++
 .../docs/content/ui/3.form/form.md            |  187 +++
 .../docs/content/ui/3.form/input.md           |  167 +++
 .../docs/content/ui/3.form/radio.md           |  106 ++
 .../docs/content/ui/3.form/select.md          |  159 +++
 .../docs/content/ui/3.form/switch.md          |   97 ++
 .../docs/content/ui/4.overlay/.navigation.yml |    2 +
 .../docs/content/ui/4.overlay/drawer.md       |  114 ++
 .../docs/content/ui/4.overlay/dropdown.md     |  158 +++
 .../docs/content/ui/4.overlay/modal.md        |  183 +++
 .../docs/content/ui/4.overlay/popover.md      |  123 ++
 .../docs/content/ui/4.overlay/tooltip.md      |  105 ++
 .../content/ui/5.feedback/.navigation.yml     |    2 +
 .../docs/content/ui/5.feedback/message.md     |  131 +++
 .../content/ui/5.feedback/notification.md     |  113 ++
 .../docs/content/ui/5.feedback/scrollbar.md   |   89 ++
 .../docs/content/ui/5.feedback/spin.md        |   90 ++
 .../docs/content/ui/6.data/.navigation.yml    |    2 +
 .../docs/content/ui/6.data/date.md            |  172 +++
 .../docs/content/ui/6.data/pagination.md      |  123 ++
 .../docs/content/ui/6.data/splitter.md        |  116 ++
 .../docs/content/ui/6.data/tabs.md            |  137 +++
 .../docs/content/ui/6.data/tree.md            |  205 ++++
 code/g3soft-libs/docs/data/api/button.json    |   66 --
 .../docs/data/api/config-provider.json        |   50 -
 .../docs/examples/button-group/basic.vue      |   12 +
 .../docs/examples/button-group/variant.vue    |   28 +
 .../docs/examples/button-group/vertical.vue   |   12 +
 .../docs/examples/button/basic.vue            |    4 +-
 .../docs/examples/button/block.vue            |   16 +-
 .../docs/examples/button/disabled.vue         |   14 +
 .../docs/examples/button/event.vue            |   22 +
 .../docs/examples/button/global-defaults.vue  |   21 +
 .../docs/examples/button/html-type.vue        |   32 +
 .../g3soft-libs/docs/examples/button/icon.vue |   28 +-
 .../docs/examples/button/loading.vue          |   30 +
 .../g3soft-libs/docs/examples/button/size.vue |   11 +-
 .../docs/examples/button/state.vue            |   20 -
 .../g3soft-libs/docs/examples/button/type.vue |   11 -
 .../docs/examples/button/variant.vue          |   16 +
 .../docs/examples/checkbox/basic.vue          |   14 +
 .../docs/examples/checkbox/disabled.vue       |   12 +
 .../docs/examples/checkbox/indeterminate.vue  |   55 +
 .../docs/examples/checkbox/rich-label.vue     |   20 +
 .../docs/examples/date/date-basic.vue         |   14 +
 .../docs/examples/date/date-disabled.vue      |   36 +
 .../docs/examples/date/date-format.vue        |   31 +
 .../docs/examples/date/manual-input.vue       |   19 +
 .../docs/examples/date/range-basic.vue        |   21 +
 .../docs/examples/date/time-select.vue        |   28 +
 .../docs/examples/drawer/basic.vue            |   18 +
 .../docs/examples/drawer/footer.vue           |   32 +
 .../docs/examples/drawer/placement.vue        |   25 +
 .../g3soft-libs/docs/examples/drawer/size.vue |   30 +
 .../docs/examples/dropdown/basic.vue          |   21 +
 .../docs/examples/dropdown/declarative.vue    |   19 +
 .../docs/examples/dropdown/header-slot.vue    |   56 +
 .../docs/examples/dropdown/item-types.vue     |   33 +
 .../docs/examples/dropdown/keyboard.vue       |   27 +
 .../docs/examples/dropdown/trigger.vue        |   23 +
 code/g3soft-libs/docs/examples/form/basic.vue |   26 +
 code/g3soft-libs/docs/examples/form/grid.vue  |   46 +
 code/g3soft-libs/docs/examples/form/group.vue |   33 +
 .../g3soft-libs/docs/examples/form/layout.vue |   37 +
 code/g3soft-libs/docs/examples/form/rules.vue |   61 +
 .../g3soft-libs/docs/examples/form/submit.vue |   47 +
 .../docs/examples/form/validate-trigger.vue   |   38 +
 code/g3soft-libs/docs/examples/grid/align.vue |   32 +
 code/g3soft-libs/docs/examples/grid/basic.vue |   25 +
 code/g3soft-libs/docs/examples/grid/flex.vue  |   29 +
 .../g3soft-libs/docs/examples/grid/gutter.vue |   33 +
 .../docs/examples/grid/no-wrap.vue            |   24 +
 .../g3soft-libs/docs/examples/grid/offset.vue |   33 +
 .../g3soft-libs/docs/examples/input/basic.vue |   14 +
 .../docs/examples/input/clearable.vue         |   18 +
 .../docs/examples/input/methods.vue           |   22 +
 .../docs/examples/input/number.vue            |   16 +
 .../docs/examples/input/password.vue          |   13 +
 .../g3soft-libs/docs/examples/input/slots.vue |   25 +
 .../docs/examples/input/status.vue            |   16 +
 .../docs/examples/input/textarea.vue          |   22 +
 .../docs/examples/layout/basic.vue            |  163 +++
 .../docs/examples/message/basic.vue           |   13 +
 .../docs/examples/message/options.vue         |   23 +
 .../docs/examples/message/placement.vue       |   27 +
 .../g3soft-libs/docs/examples/modal/basic.vue |   32 +
 .../docs/examples/modal/confirm-async.vue     |   35 +
 .../docs/examples/modal/confirm.vue           |   34 +
 .../docs/examples/modal/footer-slot.vue       |   33 +
 code/g3soft-libs/docs/examples/modal/form.vue |   44 +
 code/g3soft-libs/docs/examples/modal/mask.vue |   37 +
 .../docs/examples/modal/resize.vue            |   29 +
 .../docs/examples/notification/basic.vue      |   26 +
 .../docs/examples/notification/close.vue      |   23 +
 .../docs/examples/notification/placement.vue  |   20 +
 .../docs/examples/pagination/basic.vue        |   14 +
 .../examples/pagination/hide-on-single.vue    |   26 +
 .../docs/examples/pagination/quick-jumper.vue |   14 +
 .../docs/examples/pagination/size-changer.vue |   25 +
 .../docs/examples/pagination/total.vue        |   20 +
 .../docs/examples/popover/arrow-width.vue     |   24 +
 .../docs/examples/popover/basic.vue           |   17 +
 .../docs/examples/popover/controlled.vue      |   26 +
 .../docs/examples/popover/placement.vue       |   21 +
 .../docs/examples/popover/trigger.vue         |   40 +
 .../g3soft-libs/docs/examples/radio/basic.vue |   18 +
 .../g3soft-libs/docs/examples/radio/cards.vue |   31 +
 .../docs/examples/radio/vertical.vue          |   24 +
 .../docs/examples/scrollbar/autohide.vue      |   23 +
 .../docs/examples/scrollbar/basic.vue         |   12 +
 .../docs/examples/segmented/basic.vue         |   14 +
 .../docs/examples/segmented/block.vue         |   20 +
 .../docs/examples/segmented/custom-label.vue  |   33 +
 .../docs/examples/segmented/options.vue       |   19 +
 .../docs/examples/segmented/shape.vue         |   15 +
 .../docs/examples/segmented/uncontrolled.vue  |   18 +
 .../docs/examples/segmented/vertical.vue      |   19 +
 .../docs/examples/select/basic.vue            |   20 +
 .../docs/examples/select/custom-option.vue    |   43 +
 .../docs/examples/select/field-names.vue      |   26 +
 .../docs/examples/select/filterable.vue       |   38 +
 .../docs/examples/select/load-more.vue        |   47 +
 .../docs/examples/select/multiple.vue         |   21 +
 .../docs/examples/select/remote.vue           |   40 +
 .../g3soft-libs/docs/examples/space/basic.vue |   12 +
 .../docs/examples/space/empty-children.vue    |   19 +
 .../docs/examples/space/separator.vue         |   16 +
 code/g3soft-libs/docs/examples/space/size.vue |   29 +
 .../docs/examples/space/vertical.vue          |   12 +
 code/g3soft-libs/docs/examples/space/wrap.vue |   14 +
 code/g3soft-libs/docs/examples/spin/basic.vue |   25 +
 code/g3soft-libs/docs/examples/spin/delay.vue |   40 +
 .../docs/examples/spin/standalone.vue         |   12 +
 .../docs/examples/splitter/basic.vue          |   34 +
 .../docs/examples/splitter/constraints.vue    |   33 +
 .../docs/examples/splitter/nested.vue         |   30 +
 .../docs/examples/splitter/vertical.vue       |   34 +
 .../docs/examples/switch/basic.vue            |   14 +
 .../docs/examples/switch/disabled.vue         |   12 +
 .../docs/examples/switch/in-form.vue          |   25 +
 code/g3soft-libs/docs/examples/tabs/basic.vue |   15 +
 code/g3soft-libs/docs/examples/tabs/items.vue |   17 +
 .../docs/examples/tabs/nav-only.vue           |   33 +
 .../docs/examples/tabs/placement.vue          |   15 +
 code/g3soft-libs/docs/examples/tabs/type.vue  |   21 +
 .../docs/examples/tag/closable.vue            |   22 +
 code/g3soft-libs/docs/examples/tag/icon.vue   |   25 +
 code/g3soft-libs/docs/examples/tag/link.vue   |   11 +
 .../docs/examples/tag/prevent-close.vue       |   20 +
 .../g3soft-libs/docs/examples/tag/variant.vue |   15 +
 .../docs/examples/tooltip/basic.vue           |   10 +
 .../docs/examples/tooltip/disabled.vue        |   26 +
 .../docs/examples/tooltip/placement.vue       |   14 +
 .../docs/examples/tooltip/rich.vue            |   20 +
 code/g3soft-libs/docs/examples/tree/basic.vue |   27 +
 .../docs/examples/tree/checkable.vue          |   36 +
 .../docs/examples/tree/context-menu.vue       |   44 +
 .../g3soft-libs/docs/examples/tree/custom.vue |   53 +
 .../docs/examples/tree/draggable.vue          |   73 ++
 .../g3soft-libs/docs/examples/tree/expand.vue |   40 +
 .../g3soft-libs/docs/examples/tree/filter.vue |   35 +
 code/g3soft-libs/docs/examples/tree/lazy.vue  |   30 +
 code/g3soft-libs/docs/nuxt.config.ts          |    7 +
 code/g3soft-libs/package.json                 |   10 +-
 code/g3soft-libs/packages/framework/README.md |   83 ++
 .../packages/framework/package.json           |   47 +
 .../framework/src/core/_utils/deep-merge.ts   |   38 +
 .../packages/framework/src/core/index.ts      |   75 ++
 .../packages/framework/src/core/install.ts    |   39 +
 .../framework/src/core/layout/G3Layout.vue    |  312 +++++
 .../src/core/layout/G3LayoutBreadcrumb.vue    |   69 ++
 .../src/core/layout/G3LayoutHeader.vue        |  135 +++
 .../src/core/layout/G3LayoutLogo.vue          |   66 ++
 .../src/core/layout/G3LayoutMenu.vue          |  241 ++++
 .../src/core/layout/G3LayoutSidebar.vue       |  357 ++++++
 .../src/core/layout/G3LayoutTabbar.vue        |  151 +++
 .../framework/src/core/layout/context.ts      |   32 +
 .../framework/src/core/layout/index.ts        |   13 +
 .../framework/src/core/layout/modes.ts        |   96 ++
 .../framework/src/core/preferences/apply.ts   |   52 +
 .../src/core/preferences/defaults.ts          |  104 ++
 .../framework/src/core/preferences/index.ts   |    4 +
 .../framework/src/core/preferences/store.ts   |  185 +++
 .../framework/src/core/types/layout.ts        |  171 +++
 .../framework/src/core/types/preferences.ts   |  212 ++++
 .../framework/src/core/types/slots.ts         |   44 +
 .../packages/framework/src/index.ts           |    3 +
 .../packages/framework/tsconfig.json          |   18 +
 .../packages/framework/vite.config.ts         |   40 +
 .../packages/tokens/src/scss/theme.scss       |   35 +
 code/g3soft-libs/packages/ui/e2e/data.spec.ts |  171 +++
 .../packages/ui/e2e/drawer.spec.ts            |  131 +++
 .../packages/ui/e2e/feedback.spec.ts          |  138 +++
 code/g3soft-libs/packages/ui/e2e/form.spec.ts |  113 ++
 .../g3soft-libs/packages/ui/e2e/layer.spec.ts |  121 ++
 .../packages/ui/e2e/select.spec.ts            |   81 ++
 .../packages/ui/e2e/ui-regressions.spec.ts    |  224 ++++
 code/g3soft-libs/packages/ui/package.json     |   17 +-
 .../packages/ui/playground/index.html         |   53 +
 .../packages/ui/playground/main.ts            |  420 +++++++
 .../packages/ui/playground/vite.config.ts     |   45 +
 .../packages/ui/playwright.config.ts          |   41 +
 .../src/_composables/useComponentDefaults.ts  |   34 +
 .../ui/src/_composables/useFloating.ts        |  162 +++
 .../ui/src/_composables/usePopupContainer.ts  |   35 +
 .../src/_composables/useUnwrappedTrigger.ts   |  108 ++
 .../packages/ui/src/_utils/drag.ts            |  207 ++++
 .../packages/ui/src/_utils/focus.ts           |   50 +
 .../packages/ui/src/_utils/global-config.ts   |    2 +
 .../packages/ui/src/_utils/position.test.ts   |  158 +++
 .../packages/ui/src/_utils/position.ts        |  173 +++
 .../packages/ui/src/_utils/scroll.ts          |   43 +
 .../packages/ui/src/_utils/z-index.test.ts    |   68 ++
 .../packages/ui/src/_utils/z-index.ts         |   89 +-
 .../ui/src/button-group/ButtonGroup.vue       |   91 ++
 .../src/button-group/ButtonGroupSeparator.vue |   41 +
 .../packages/ui/src/button-group/index.ts     |    7 +
 .../packages/ui/src/button-group/types.ts     |   12 +
 .../packages/ui/src/button/Button.vue         |  275 +++--
 .../packages/ui/src/button/types.ts           |   15 +-
 .../packages/ui/src/checkbox/Checkbox.vue     |  158 +++
 .../packages/ui/src/checkbox/index.ts         |    2 +
 .../packages/ui/src/checkbox/types.ts         |   12 +
 .../packages/ui/src/date/CalendarPanel.vue    |  825 ++++++++++++++
 .../packages/ui/src/date/DatePicker.vue       |  350 ++++++
 .../packages/ui/src/date/RangePicker.vue      |  372 ++++++
 .../packages/ui/src/date/TimeSelect.vue       |  242 ++++
 .../packages/ui/src/date/date-utils.test.ts   |  344 ++++++
 .../packages/ui/src/date/date-utils.ts        |  764 +++++++++++++
 .../g3soft-libs/packages/ui/src/date/index.ts |   46 +
 .../g3soft-libs/packages/ui/src/date/types.ts |   77 ++
 .../packages/ui/src/drawer/Drawer.vue         |  520 +++++++++
 .../packages/ui/src/drawer/index.ts           |    2 +
 .../packages/ui/src/drawer/types.ts           |   31 +
 .../packages/ui/src/dropdown/Dropdown.test.ts |  219 ++++
 .../packages/ui/src/dropdown/Dropdown.vue     |  332 ++++++
 .../packages/ui/src/dropdown/DropdownItem.vue |   39 +
 .../packages/ui/src/dropdown/DropdownMenu.vue |  116 ++
 .../packages/ui/src/dropdown/context.ts       |   12 +
 .../packages/ui/src/dropdown/index.ts         |    8 +
 .../packages/ui/src/dropdown/types.ts         |   58 +
 .../g3soft-libs/packages/ui/src/form/Form.vue |  169 +++
 .../packages/ui/src/form/FormGroup.vue        |  184 +++
 .../packages/ui/src/form/FormItem.test.ts     |  158 +++
 .../packages/ui/src/form/FormItem.vue         |  304 +++++
 .../packages/ui/src/form/context.ts           |   37 +
 .../packages/ui/src/form/form-utils.test.ts   |   31 +
 .../packages/ui/src/form/form-utils.ts        |   26 +
 .../g3soft-libs/packages/ui/src/form/index.ts |   19 +
 .../g3soft-libs/packages/ui/src/form/types.ts |  123 ++
 .../packages/ui/src/form/validate.test.ts     |  119 ++
 .../packages/ui/src/form/validate.ts          |  152 +++
 code/g3soft-libs/packages/ui/src/grid/Col.vue |   48 +
 code/g3soft-libs/packages/ui/src/grid/Row.vue |  174 +++
 .../g3soft-libs/packages/ui/src/grid/index.ts |    3 +
 .../g3soft-libs/packages/ui/src/grid/types.ts |   40 +
 code/g3soft-libs/packages/ui/src/index.ts     |  136 ++-
 .../packages/ui/src/input/Input.test.ts       |  126 +++
 .../packages/ui/src/input/Input.vue           |  583 ++++++++++
 .../packages/ui/src/input/index.ts            |    2 +
 .../packages/ui/src/input/types.ts            |   38 +
 .../packages/ui/src/locale/index.ts           |  158 ++-
 .../packages/ui/src/message/Message.vue       |  141 +++
 .../ui/src/message/MessageContainer.test.ts   |   81 ++
 .../ui/src/message/MessageContainer.vue       |  155 +++
 .../packages/ui/src/message/index.ts          |   12 +
 .../packages/ui/src/message/manager.ts        |   85 ++
 .../packages/ui/src/message/store.ts          |   15 +
 .../packages/ui/src/message/types.ts          |   51 +
 .../packages/ui/src/modal/Modal.vue           |  539 +++++++++
 .../packages/ui/src/modal/ModalConfirm.vue    |   93 ++
 .../packages/ui/src/modal/confirm.ts          |   39 +
 .../packages/ui/src/modal/index.ts            |    8 +
 .../packages/ui/src/modal/types.ts            |   61 +
 .../ui/src/notification/Notification.vue      |  157 +++
 .../notification/NotificationContainer.vue    |  131 +++
 .../packages/ui/src/notification/index.ts     |   12 +
 .../packages/ui/src/notification/manager.ts   |   85 ++
 .../packages/ui/src/notification/store.ts     |   15 +
 .../packages/ui/src/notification/types.ts     |   47 +
 .../packages/ui/src/pagination/Pagination.vue |  364 ++++++
 .../packages/ui/src/pagination/index.ts       |    2 +
 .../packages/ui/src/pagination/types.ts       |   29 +
 .../packages/ui/src/popover/Popover.vue       |  401 +++++++
 .../packages/ui/src/popover/index.ts          |    2 +
 .../packages/ui/src/popover/types.ts          |   34 +
 .../packages/ui/src/radio/Radio.vue           |  135 +++
 .../packages/ui/src/radio/RadioGroup.vue      |   61 +
 .../packages/ui/src/radio/context.ts          |   18 +
 .../packages/ui/src/radio/index.ts            |    5 +
 .../packages/ui/src/radio/types.ts            |   17 +
 .../packages/ui/src/scrollbar/Scrollbar.vue   |  329 ++++++
 .../packages/ui/src/scrollbar/index.ts        |    2 +
 .../packages/ui/src/scrollbar/types.ts        |   16 +
 .../packages/ui/src/segmented/Segmented.vue   |  330 ++++++
 .../packages/ui/src/segmented/index.ts        |    8 +
 .../packages/ui/src/segmented/types.ts        |   39 +
 .../packages/ui/src/select/Select.vue         |  788 +++++++++++++
 .../packages/ui/src/select/index.ts           |    2 +
 .../packages/ui/src/select/types.ts           |   31 +
 .../packages/ui/src/space/Space.vue           |  151 +++
 .../packages/ui/src/space/index.ts            |    2 +
 .../packages/ui/src/space/types.ts            |   21 +
 .../g3soft-libs/packages/ui/src/spin/Spin.vue |  165 +++
 .../g3soft-libs/packages/ui/src/spin/index.ts |    2 +
 .../g3soft-libs/packages/ui/src/spin/types.ts |    8 +
 .../packages/ui/src/splitter/Panel.vue        |   48 +
 .../packages/ui/src/splitter/Splitter.vue     |  409 +++++++
 .../packages/ui/src/splitter/index.ts         |    3 +
 .../packages/ui/src/splitter/types.ts         |   25 +
 .../packages/ui/src/switch/Switch.vue         |  130 +++
 .../packages/ui/src/switch/index.ts           |    2 +
 .../packages/ui/src/switch/types.ts           |    6 +
 .../packages/ui/src/tabs/TabPane.vue          |   17 +
 .../packages/ui/src/tabs/Tabs.test.ts         |  114 ++
 .../g3soft-libs/packages/ui/src/tabs/Tabs.vue |  464 ++++++++
 .../g3soft-libs/packages/ui/src/tabs/index.ts |    3 +
 .../g3soft-libs/packages/ui/src/tabs/types.ts |   48 +
 code/g3soft-libs/packages/ui/src/tag/Tag.vue  |  165 +++
 code/g3soft-libs/packages/ui/src/tag/index.ts |    2 +
 code/g3soft-libs/packages/ui/src/tag/types.ts |   13 +
 .../packages/ui/src/tooltip/Tooltip.vue       |   69 ++
 .../packages/ui/src/tooltip/index.ts          |    2 +
 .../packages/ui/src/tooltip/types.ts          |   20 +
 .../g3soft-libs/packages/ui/src/tree/Tree.vue |  812 +++++++++++++
 .../packages/ui/src/tree/TreeNode.vue         |  422 +++++++
 .../packages/ui/src/tree/context.ts           |    5 +
 .../g3soft-libs/packages/ui/src/tree/index.ts |   24 +
 .../g3soft-libs/packages/ui/src/tree/types.ts |  156 +++
 .../packages/ui/src/tree/utils.test.ts        |  173 +++
 .../g3soft-libs/packages/ui/src/tree/utils.ts |  216 ++++
 code/g3soft-libs/packages/ui/tests/setup.ts   |   41 +
 code/g3soft-libs/packages/ui/vite.config.ts   |    3 +-
 code/g3soft-libs/packages/ui/vitest.config.ts |   51 +
 code/g3soft-libs/pnpm-lock.yaml               | 1002 +++++++++--------
 code/g3soft-libs/pnpm-workspace.yaml          |    2 +-
 code/g3soft-libs/scripts/gen-api.mjs          |   95 --
 code/g3soft-libs/sel.yaml                     |    2 +
 356 files changed, 28877 insertions(+), 1055 deletions(-)
 create mode 100644 code/g3soft-libs/.codebuddy/plans/g3-ui-重写-参照fms-vue_084cfb52.md
 delete mode 100644 code/g3soft-libs/docs/app/components/content/ApiTable.vue
 create mode 100644 code/g3soft-libs/docs/content/framework/.navigation.yml
 create mode 100644 code/g3soft-libs/docs/content/framework/1.layout/.navigation.yml
 create mode 100644 code/g3soft-libs/docs/content/framework/1.layout/index.md
 create mode 100644 code/g3soft-libs/docs/content/ui/2.general/button-group.md
 create mode 100644 code/g3soft-libs/docs/content/ui/2.general/grid.md
 create mode 100644 code/g3soft-libs/docs/content/ui/2.general/segmented.md
 create mode 100644 code/g3soft-libs/docs/content/ui/2.general/space.md
 create mode 100644 code/g3soft-libs/docs/content/ui/2.general/tag.md
 create mode 100644 code/g3soft-libs/docs/content/ui/3.form/.navigation.yml
 create mode 100644 code/g3soft-libs/docs/content/ui/3.form/checkbox.md
 create mode 100644 code/g3soft-libs/docs/content/ui/3.form/form.md
 create mode 100644 code/g3soft-libs/docs/content/ui/3.form/input.md
 create mode 100644 code/g3soft-libs/docs/content/ui/3.form/radio.md
 create mode 100644 code/g3soft-libs/docs/content/ui/3.form/select.md
 create mode 100644 code/g3soft-libs/docs/content/ui/3.form/switch.md
 create mode 100644 code/g3soft-libs/docs/content/ui/4.overlay/.navigation.yml
 create mode 100644 code/g3soft-libs/docs/content/ui/4.overlay/drawer.md
 create mode 100644 code/g3soft-libs/docs/content/ui/4.overlay/dropdown.md
 create mode 100644 code/g3soft-libs/docs/content/ui/4.overlay/modal.md
 create mode 100644 code/g3soft-libs/docs/content/ui/4.overlay/popover.md
 create mode 100644 code/g3soft-libs/docs/content/ui/4.overlay/tooltip.md
 create mode 100644 code/g3soft-libs/docs/content/ui/5.feedback/.navigation.yml
 create mode 100644 code/g3soft-libs/docs/content/ui/5.feedback/message.md
 create mode 100644 code/g3soft-libs/docs/content/ui/5.feedback/notification.md
 create mode 100644 code/g3soft-libs/docs/content/ui/5.feedback/scrollbar.md
 create mode 100644 code/g3soft-libs/docs/content/ui/5.feedback/spin.md
 create mode 100644 code/g3soft-libs/docs/content/ui/6.data/.navigation.yml
 create mode 100644 code/g3soft-libs/docs/content/ui/6.data/date.md
 create mode 100644 code/g3soft-libs/docs/content/ui/6.data/pagination.md
 create mode 100644 code/g3soft-libs/docs/content/ui/6.data/splitter.md
 create mode 100644 code/g3soft-libs/docs/content/ui/6.data/tabs.md
 create mode 100644 code/g3soft-libs/docs/content/ui/6.data/tree.md
 delete mode 100644 code/g3soft-libs/docs/data/api/button.json
 delete mode 100644 code/g3soft-libs/docs/data/api/config-provider.json
 create mode 100644 code/g3soft-libs/docs/examples/button-group/basic.vue
 create mode 100644 code/g3soft-libs/docs/examples/button-group/variant.vue
 create mode 100644 code/g3soft-libs/docs/examples/button-group/vertical.vue
 create mode 100644 code/g3soft-libs/docs/examples/button/disabled.vue
 create mode 100644 code/g3soft-libs/docs/examples/button/event.vue
 create mode 100644 code/g3soft-libs/docs/examples/button/global-defaults.vue
 create mode 100644 code/g3soft-libs/docs/examples/button/html-type.vue
 create mode 100644 code/g3soft-libs/docs/examples/button/loading.vue
 delete mode 100644 code/g3soft-libs/docs/examples/button/state.vue
 delete mode 100644 code/g3soft-libs/docs/examples/button/type.vue
 create mode 100644 code/g3soft-libs/docs/examples/button/variant.vue
 create mode 100644 code/g3soft-libs/docs/examples/checkbox/basic.vue
 create mode 100644 code/g3soft-libs/docs/examples/checkbox/disabled.vue
 create mode 100644 code/g3soft-libs/docs/examples/checkbox/indeterminate.vue
 create mode 100644 code/g3soft-libs/docs/examples/checkbox/rich-label.vue
 create mode 100644 code/g3soft-libs/docs/examples/date/date-basic.vue
 create mode 100644 code/g3soft-libs/docs/examples/date/date-disabled.vue
 create mode 100644 code/g3soft-libs/docs/examples/date/date-format.vue
 create mode 100644 code/g3soft-libs/docs/examples/date/manual-input.vue
 create mode 100644 code/g3soft-libs/docs/examples/date/range-basic.vue
 create mode 100644 code/g3soft-libs/docs/examples/date/time-select.vue
 create mode 100644 code/g3soft-libs/docs/examples/drawer/basic.vue
 create mode 100644 code/g3soft-libs/docs/examples/drawer/footer.vue
 create mode 100644 code/g3soft-libs/docs/examples/drawer/placement.vue
 create mode 100644 code/g3soft-libs/docs/examples/drawer/size.vue
 create mode 100644 code/g3soft-libs/docs/examples/dropdown/basic.vue
 create mode 100644 code/g3soft-libs/docs/examples/dropdown/declarative.vue
 create mode 100644 code/g3soft-libs/docs/examples/dropdown/header-slot.vue
 create mode 100644 code/g3soft-libs/docs/examples/dropdown/item-types.vue
 create mode 100644 code/g3soft-libs/docs/examples/dropdown/keyboard.vue
 create mode 100644 code/g3soft-libs/docs/examples/dropdown/trigger.vue
 create mode 100644 code/g3soft-libs/docs/examples/form/basic.vue
 create mode 100644 code/g3soft-libs/docs/examples/form/grid.vue
 create mode 100644 code/g3soft-libs/docs/examples/form/group.vue
 create mode 100644 code/g3soft-libs/docs/examples/form/layout.vue
 create mode 100644 code/g3soft-libs/docs/examples/form/rules.vue
 create mode 100644 code/g3soft-libs/docs/examples/form/submit.vue
 create mode 100644 code/g3soft-libs/docs/examples/form/validate-trigger.vue
 create mode 100644 code/g3soft-libs/docs/examples/grid/align.vue
 create mode 100644 code/g3soft-libs/docs/examples/grid/basic.vue
 create mode 100644 code/g3soft-libs/docs/examples/grid/flex.vue
 create mode 100644 code/g3soft-libs/docs/examples/grid/gutter.vue
 create mode 100644 code/g3soft-libs/docs/examples/grid/no-wrap.vue
 create mode 100644 code/g3soft-libs/docs/examples/grid/offset.vue
 create mode 100644 code/g3soft-libs/docs/examples/input/basic.vue
 create mode 100644 code/g3soft-libs/docs/examples/input/clearable.vue
 create mode 100644 code/g3soft-libs/docs/examples/input/methods.vue
 create mode 100644 code/g3soft-libs/docs/examples/input/number.vue
 create mode 100644 code/g3soft-libs/docs/examples/input/password.vue
 create mode 100644 code/g3soft-libs/docs/examples/input/slots.vue
 create mode 100644 code/g3soft-libs/docs/examples/input/status.vue
 create mode 100644 code/g3soft-libs/docs/examples/input/textarea.vue
 create mode 100644 code/g3soft-libs/docs/examples/layout/basic.vue
 create mode 100644 code/g3soft-libs/docs/examples/message/basic.vue
 create mode 100644 code/g3soft-libs/docs/examples/message/options.vue
 create mode 100644 code/g3soft-libs/docs/examples/message/placement.vue
 create mode 100644 code/g3soft-libs/docs/examples/modal/basic.vue
 create mode 100644 code/g3soft-libs/docs/examples/modal/confirm-async.vue
 create mode 100644 code/g3soft-libs/docs/examples/modal/confirm.vue
 create mode 100644 code/g3soft-libs/docs/examples/modal/footer-slot.vue
 create mode 100644 code/g3soft-libs/docs/examples/modal/form.vue
 create mode 100644 code/g3soft-libs/docs/examples/modal/mask.vue
 create mode 100644 code/g3soft-libs/docs/examples/modal/resize.vue
 create mode 100644 code/g3soft-libs/docs/examples/notification/basic.vue
 create mode 100644 code/g3soft-libs/docs/examples/notification/close.vue
 create mode 100644 code/g3soft-libs/docs/examples/notification/placement.vue
 create mode 100644 code/g3soft-libs/docs/examples/pagination/basic.vue
 create mode 100644 code/g3soft-libs/docs/examples/pagination/hide-on-single.vue
 create mode 100644 code/g3soft-libs/docs/examples/pagination/quick-jumper.vue
 create mode 100644 code/g3soft-libs/docs/examples/pagination/size-changer.vue
 create mode 100644 code/g3soft-libs/docs/examples/pagination/total.vue
 create mode 100644 code/g3soft-libs/docs/examples/popover/arrow-width.vue
 create mode 100644 code/g3soft-libs/docs/examples/popover/basic.vue
 create mode 100644 code/g3soft-libs/docs/examples/popover/controlled.vue
 create mode 100644 code/g3soft-libs/docs/examples/popover/placement.vue
 create mode 100644 code/g3soft-libs/docs/examples/popover/trigger.vue
 create mode 100644 code/g3soft-libs/docs/examples/radio/basic.vue
 create mode 100644 code/g3soft-libs/docs/examples/radio/cards.vue
 create mode 100644 code/g3soft-libs/docs/examples/radio/vertical.vue
 create mode 100644 code/g3soft-libs/docs/examples/scrollbar/autohide.vue
 create mode 100644 code/g3soft-libs/docs/examples/scrollbar/basic.vue
 create mode 100644 code/g3soft-libs/docs/examples/segmented/basic.vue
 create mode 100644 code/g3soft-libs/docs/examples/segmented/block.vue
 create mode 100644 code/g3soft-libs/docs/examples/segmented/custom-label.vue
 create mode 100644 code/g3soft-libs/docs/examples/segmented/options.vue
 create mode 100644 code/g3soft-libs/docs/examples/segmented/shape.vue
 create mode 100644 code/g3soft-libs/docs/examples/segmented/uncontrolled.vue
 create mode 100644 code/g3soft-libs/docs/examples/segmented/vertical.vue
 create mode 100644 code/g3soft-libs/docs/examples/select/basic.vue
 create mode 100644 code/g3soft-libs/docs/examples/select/custom-option.vue
 create mode 100644 code/g3soft-libs/docs/examples/select/field-names.vue
 create mode 100644 code/g3soft-libs/docs/examples/select/filterable.vue
 create mode 100644 code/g3soft-libs/docs/examples/select/load-more.vue
 create mode 100644 code/g3soft-libs/docs/examples/select/multiple.vue
 create mode 100644 code/g3soft-libs/docs/examples/select/remote.vue
 create mode 100644 code/g3soft-libs/docs/examples/space/basic.vue
 create mode 100644 code/g3soft-libs/docs/examples/space/empty-children.vue
 create mode 100644 code/g3soft-libs/docs/examples/space/separator.vue
 create mode 100644 code/g3soft-libs/docs/examples/space/size.vue
 create mode 100644 code/g3soft-libs/docs/examples/space/vertical.vue
 create mode 100644 code/g3soft-libs/docs/examples/space/wrap.vue
 create mode 100644 code/g3soft-libs/docs/examples/spin/basic.vue
 create mode 100644 code/g3soft-libs/docs/examples/spin/delay.vue
 create mode 100644 code/g3soft-libs/docs/examples/spin/standalone.vue
 create mode 100644 code/g3soft-libs/docs/examples/splitter/basic.vue
 create mode 100644 code/g3soft-libs/docs/examples/splitter/constraints.vue
 create mode 100644 code/g3soft-libs/docs/examples/splitter/nested.vue
 create mode 100644 code/g3soft-libs/docs/examples/splitter/vertical.vue
 create mode 100644 code/g3soft-libs/docs/examples/switch/basic.vue
 create mode 100644 code/g3soft-libs/docs/examples/switch/disabled.vue
 create mode 100644 code/g3soft-libs/docs/examples/switch/in-form.vue
 create mode 100644 code/g3soft-libs/docs/examples/tabs/basic.vue
 create mode 100644 code/g3soft-libs/docs/examples/tabs/items.vue
 create mode 100644 code/g3soft-libs/docs/examples/tabs/nav-only.vue
 create mode 100644 code/g3soft-libs/docs/examples/tabs/placement.vue
 create mode 100644 code/g3soft-libs/docs/examples/tabs/type.vue
 create mode 100644 code/g3soft-libs/docs/examples/tag/closable.vue
 create mode 100644 code/g3soft-libs/docs/examples/tag/icon.vue
 create mode 100644 code/g3soft-libs/docs/examples/tag/link.vue
 create mode 100644 code/g3soft-libs/docs/examples/tag/prevent-close.vue
 create mode 100644 code/g3soft-libs/docs/examples/tag/variant.vue
 create mode 100644 code/g3soft-libs/docs/examples/tooltip/basic.vue
 create mode 100644 code/g3soft-libs/docs/examples/tooltip/disabled.vue
 create mode 100644 code/g3soft-libs/docs/examples/tooltip/placement.vue
 create mode 100644 code/g3soft-libs/docs/examples/tooltip/rich.vue
 create mode 100644 code/g3soft-libs/docs/examples/tree/basic.vue
 create mode 100644 code/g3soft-libs/docs/examples/tree/checkable.vue
 create mode 100644 code/g3soft-libs/docs/examples/tree/context-menu.vue
 create mode 100644 code/g3soft-libs/docs/examples/tree/custom.vue
 create mode 100644 code/g3soft-libs/docs/examples/tree/draggable.vue
 create mode 100644 code/g3soft-libs/docs/examples/tree/expand.vue
 create mode 100644 code/g3soft-libs/docs/examples/tree/filter.vue
 create mode 100644 code/g3soft-libs/docs/examples/tree/lazy.vue
 create mode 100644 code/g3soft-libs/packages/framework/README.md
 create mode 100644 code/g3soft-libs/packages/framework/package.json
 create mode 100644 code/g3soft-libs/packages/framework/src/core/_utils/deep-merge.ts
 create mode 100644 code/g3soft-libs/packages/framework/src/core/index.ts
 create mode 100644 code/g3soft-libs/packages/framework/src/core/install.ts
 create mode 100644 code/g3soft-libs/packages/framework/src/core/layout/G3Layout.vue
 create mode 100644 code/g3soft-libs/packages/framework/src/core/layout/G3LayoutBreadcrumb.vue
 create mode 100644 code/g3soft-libs/packages/framework/src/core/layout/G3LayoutHeader.vue
 create mode 100644 code/g3soft-libs/packages/framework/src/core/layout/G3LayoutLogo.vue
 create mode 100644 code/g3soft-libs/packages/framework/src/core/layout/G3LayoutMenu.vue
 create mode 100644 code/g3soft-libs/packages/framework/src/core/layout/G3LayoutSidebar.vue
 create mode 100644 code/g3soft-libs/packages/framework/src/core/layout/G3LayoutTabbar.vue
 create mode 100644 code/g3soft-libs/packages/framework/src/core/layout/context.ts
 create mode 100644 code/g3soft-libs/packages/framework/src/core/layout/index.ts
 create mode 100644 code/g3soft-libs/packages/framework/src/core/layout/modes.ts
 create mode 100644 code/g3soft-libs/packages/framework/src/core/preferences/apply.ts
 create mode 100644 code/g3soft-libs/packages/framework/src/core/preferences/defaults.ts
 create mode 100644 code/g3soft-libs/packages/framework/src/core/preferences/index.ts
 create mode 100644 code/g3soft-libs/packages/framework/src/core/preferences/store.ts
 create mode 100644 code/g3soft-libs/packages/framework/src/core/types/layout.ts
 create mode 100644 code/g3soft-libs/packages/framework/src/core/types/preferences.ts
 create mode 100644 code/g3soft-libs/packages/framework/src/core/types/slots.ts
 create mode 100644 code/g3soft-libs/packages/framework/src/index.ts
 create mode 100644 code/g3soft-libs/packages/framework/tsconfig.json
 create mode 100644 code/g3soft-libs/packages/framework/vite.config.ts
 create mode 100644 code/g3soft-libs/packages/ui/e2e/data.spec.ts
 create mode 100644 code/g3soft-libs/packages/ui/e2e/drawer.spec.ts
 create mode 100644 code/g3soft-libs/packages/ui/e2e/feedback.spec.ts
 create mode 100644 code/g3soft-libs/packages/ui/e2e/form.spec.ts
 create mode 100644 code/g3soft-libs/packages/ui/e2e/layer.spec.ts
 create mode 100644 code/g3soft-libs/packages/ui/e2e/select.spec.ts
 create mode 100644 code/g3soft-libs/packages/ui/e2e/ui-regressions.spec.ts
 create mode 100644 code/g3soft-libs/packages/ui/playground/index.html
 create mode 100644 code/g3soft-libs/packages/ui/playground/main.ts
 create mode 100644 code/g3soft-libs/packages/ui/playground/vite.config.ts
 create mode 100644 code/g3soft-libs/packages/ui/playwright.config.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/_composables/useComponentDefaults.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/_composables/useFloating.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/_composables/usePopupContainer.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/_composables/useUnwrappedTrigger.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/_utils/drag.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/_utils/focus.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/_utils/position.test.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/_utils/position.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/_utils/scroll.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/_utils/z-index.test.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/button-group/ButtonGroup.vue
 create mode 100644 code/g3soft-libs/packages/ui/src/button-group/ButtonGroupSeparator.vue
 create mode 100644 code/g3soft-libs/packages/ui/src/button-group/index.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/button-group/types.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/checkbox/Checkbox.vue
 create mode 100644 code/g3soft-libs/packages/ui/src/checkbox/index.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/checkbox/types.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/date/CalendarPanel.vue
 create mode 100644 code/g3soft-libs/packages/ui/src/date/DatePicker.vue
 create mode 100644 code/g3soft-libs/packages/ui/src/date/RangePicker.vue
 create mode 100644 code/g3soft-libs/packages/ui/src/date/TimeSelect.vue
 create mode 100644 code/g3soft-libs/packages/ui/src/date/date-utils.test.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/date/date-utils.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/date/index.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/date/types.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/drawer/Drawer.vue
 create mode 100644 code/g3soft-libs/packages/ui/src/drawer/index.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/drawer/types.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/dropdown/Dropdown.test.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/dropdown/Dropdown.vue
 create mode 100644 code/g3soft-libs/packages/ui/src/dropdown/DropdownItem.vue
 create mode 100644 code/g3soft-libs/packages/ui/src/dropdown/DropdownMenu.vue
 create mode 100644 code/g3soft-libs/packages/ui/src/dropdown/context.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/dropdown/index.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/dropdown/types.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/form/Form.vue
 create mode 100644 code/g3soft-libs/packages/ui/src/form/FormGroup.vue
 create mode 100644 code/g3soft-libs/packages/ui/src/form/FormItem.test.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/form/FormItem.vue
 create mode 100644 code/g3soft-libs/packages/ui/src/form/context.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/form/form-utils.test.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/form/form-utils.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/form/index.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/form/types.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/form/validate.test.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/form/validate.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/grid/Col.vue
 create mode 100644 code/g3soft-libs/packages/ui/src/grid/Row.vue
 create mode 100644 code/g3soft-libs/packages/ui/src/grid/index.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/grid/types.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/input/Input.test.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/input/Input.vue
 create mode 100644 code/g3soft-libs/packages/ui/src/input/index.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/input/types.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/message/Message.vue
 create mode 100644 code/g3soft-libs/packages/ui/src/message/MessageContainer.test.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/message/MessageContainer.vue
 create mode 100644 code/g3soft-libs/packages/ui/src/message/index.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/message/manager.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/message/store.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/message/types.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/modal/Modal.vue
 create mode 100644 code/g3soft-libs/packages/ui/src/modal/ModalConfirm.vue
 create mode 100644 code/g3soft-libs/packages/ui/src/modal/confirm.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/modal/index.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/modal/types.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/notification/Notification.vue
 create mode 100644 code/g3soft-libs/packages/ui/src/notification/NotificationContainer.vue
 create mode 100644 code/g3soft-libs/packages/ui/src/notification/index.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/notification/manager.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/notification/store.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/notification/types.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/pagination/Pagination.vue
 create mode 100644 code/g3soft-libs/packages/ui/src/pagination/index.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/pagination/types.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/popover/Popover.vue
 create mode 100644 code/g3soft-libs/packages/ui/src/popover/index.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/popover/types.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/radio/Radio.vue
 create mode 100644 code/g3soft-libs/packages/ui/src/radio/RadioGroup.vue
 create mode 100644 code/g3soft-libs/packages/ui/src/radio/context.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/radio/index.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/radio/types.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/scrollbar/Scrollbar.vue
 create mode 100644 code/g3soft-libs/packages/ui/src/scrollbar/index.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/scrollbar/types.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/segmented/Segmented.vue
 create mode 100644 code/g3soft-libs/packages/ui/src/segmented/index.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/segmented/types.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/select/Select.vue
 create mode 100644 code/g3soft-libs/packages/ui/src/select/index.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/select/types.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/space/Space.vue
 create mode 100644 code/g3soft-libs/packages/ui/src/space/index.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/space/types.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/spin/Spin.vue
 create mode 100644 code/g3soft-libs/packages/ui/src/spin/index.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/spin/types.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/splitter/Panel.vue
 create mode 100644 code/g3soft-libs/packages/ui/src/splitter/Splitter.vue
 create mode 100644 code/g3soft-libs/packages/ui/src/splitter/index.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/splitter/types.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/switch/Switch.vue
 create mode 100644 code/g3soft-libs/packages/ui/src/switch/index.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/switch/types.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/tabs/TabPane.vue
 create mode 100644 code/g3soft-libs/packages/ui/src/tabs/Tabs.test.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/tabs/Tabs.vue
 create mode 100644 code/g3soft-libs/packages/ui/src/tabs/index.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/tabs/types.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/tag/Tag.vue
 create mode 100644 code/g3soft-libs/packages/ui/src/tag/index.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/tag/types.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/tooltip/Tooltip.vue
 create mode 100644 code/g3soft-libs/packages/ui/src/tooltip/index.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/tooltip/types.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/tree/Tree.vue
 create mode 100644 code/g3soft-libs/packages/ui/src/tree/TreeNode.vue
 create mode 100644 code/g3soft-libs/packages/ui/src/tree/context.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/tree/index.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/tree/types.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/tree/utils.test.ts
 create mode 100644 code/g3soft-libs/packages/ui/src/tree/utils.ts
 create mode 100644 code/g3soft-libs/packages/ui/tests/setup.ts
 create mode 100644 code/g3soft-libs/packages/ui/vitest.config.ts
 delete mode 100644 code/g3soft-libs/scripts/gen-api.mjs
 create mode 100644 code/g3soft-libs/sel.yaml

diff --git a/code/g3soft-libs/.codebuddy/plans/g3-ui-重写-参照fms-vue_084cfb52.md b/code/g3soft-libs/.codebuddy/plans/g3-ui-重写-参照fms-vue_084cfb52.md
new file mode 100644
index 00000000..3021c70f
--- /dev/null
+++ b/code/g3soft-libs/.codebuddy/plans/g3-ui-重写-参照fms-vue_084cfb52.md
@@ -0,0 +1,334 @@
+---
+name: g3-ui-重写-参照fms-vue
+overview: 以 fms-vue 的 `src/components/ui` 为原型，全量重写 `packages/ui`（@g3soft/ui）组件库：25 个组件按「基础→表单→浮层→反馈→数据展示」分批实现，全部 TypeScript 化并遵守 g3 约定（非 scoped SCSS + `g3-` BEM + `--g3-*` 令牌 + types.ts + gen:api + 文档示例）。确认语义统一从 fms 的 `ok/onOk/okText` 改为 `confirm/onConfirm/confirmText`。
+design:
+  styleKeywords:
+    - 中性克制
+    - shadcn 风格主色派生
+    - 层次靠面不靠线
+    - 轻描边
+    - 微动效反馈
+    - 三层 z 轴秩序
+  fontSystem:
+    fontFamily: PingFang SC
+    heading:
+      size: 24px
+      weight: 600
+    subheading:
+      size: 16px
+      weight: 500
+    body:
+      size: 14px
+      weight: 400
+  colorSystem:
+    primary:
+      - "#18181B"
+      - "#E5E5E5"
+    background:
+      - "#FFFFFF"
+      - "#141414"
+    text:
+      - "#000000"
+      - "#FFFFFF"
+    functional:
+      - "#45B114"
+      - "#E79A0D"
+      - "#EC4246"
+todos:
+  - id: infra-setup
+    content: 扩展 tokens 8 个变量、TS 化 _utils、改造 z-index 分层、加 @lucide/vue 依赖与 external
+    status: completed
+  - id: genapi-and-config
+    content: 改造 gen-api 只解析目录主组件，扩充 locale 并实现 useComponentDefaults
+    status: completed
+    dependencies:
+      - infra-setup
+  - id: base-components
+    content: 用 [skill:ui-ux-pro-max] 重写 Button 变体体系，实现 button-group/space/grid/tag/segmented/scrollbar/spin
+    status: completed
+    dependencies:
+      - genapi-and-config
+  - id: overlay-popover
+    content: 用 [subagent:code-explorer] 移植浮层工具，实现 useFloating 与 popover/tooltip/dropdown
+    status: completed
+    dependencies:
+      - base-components
+  - id: form-components
+    content: 移植 input/checkbox/radio/switch/select 与 form 校验体系
+    status: completed
+    dependencies:
+      - overlay-popover
+  - id: modal-drawer-feedback
+    content: 参照 [skill:antdv-next] 实现 modal（confirm 语义+命令式）、drawer、message/notification
+    status: completed
+    dependencies:
+      - overlay-popover
+  - id: data-display
+    content: 实现 tree/tabs/pagination/splitter 与 date-picker/range-picker/time-select
+    status: completed
+    dependencies:
+      - overlay-popover
+  - id: docs-and-verify
+    content: 补齐示例与文档页，跑 gen:api、tokens/ui 全量构建冒烟
+    status: completed
+    dependencies:
+      - base-components
+      - form-components
+      - modal-drawer-feedback
+      - data-display
+---
+
+## 产品概述
+
+将 `packages/ui`（@g3soft/ui）从一个只有 Button + ConfigProvider 的雏形，重写为一套完整的 Vue 3 组件库。实现原型来自 `D:\workspace\code\fms\fms-vue\src\components\ui` 的 25 个组件目录，但必须全部落在 g3soft 自身的技术约定上：TypeScript、非 scoped SCSS + `g3-` BEM、 `--g3-*` 设计令牌、`types.ts` + `gen:api` 生成文档、docs 示例与 md 页面。
+
+## 核心范围
+
+- 全量迁移 fms-vue 的组件能力，按「基础 → 浮层 → 表单 → 覆盖层与反馈 → 数据展示」分批落地，每批可独立构建验证。
+- 共规划 28 个组件目录：button、button-group、space、grid、scrollbar、spin、tag、segmented、input、checkbox、radio（+radio-group）、switch、select、form（+form-item/form-group）、date-picker、range-picker、time-select、popover、tooltip、dropdown、modal、drawer、message、notification、tree、tabs、pagination、splitter。
+
+## 确认语义（本次重写的关键变更）
+
+fms 的 `ok` 风格一律改为 `confirm` 风格：
+
+- `okText` → `confirmText`、`okButtonProps` → `confirmButtonProps`、`onOk` → `onConfirm`
+- 事件 `ok` → `confirm`（`update:open` / `cancel` / `closed` 保持不变）
+- 命令式仍为 `G3Modal.confirm({ ..., onConfirm })`，返回 `{ destroy }`
+- `confirmLoading` 语义不变予以保留；「只有点取消按钮才触发 `onCancel`，点遮罩/Esc/右上角 X 为静默关闭」的行为保留
+
+## 其他已确认决策
+
+- Button 改用 fms 变体体系：`primary | secondary | outline | ghost | danger | danger-outline | link | icon`（破坏性变更，现有 `docs/examples/button/*` 与 `button.md` 一并重写）。
+- 图标新增 `@lucide/vue` 运行时依赖，照搬 fms 用法。
+- 扩展 `@g3soft/tokens`，但只补跨组件共享的少量语义变量，组件私有尺寸一律用 `v()` 兜底不进令牌；**z-index 不进令牌**，继续走 `packages/ui/src/_utils/z-index.ts`，并改造为分层分配。
+
+## 技术栈
+
+- 组件库：Vue 3.5（`<script setup lang="ts">`）+ TypeScript 严格模式 + SCSS（sass，modern-compiler）
+- 图标：新增 `@lucide/vue`（`packages/ui` 的 `dependencies`，非 peer）
+- 设计令牌：`@g3soft/tokens`（SCSS 编译产物 `dist/index.css`），变量前缀 `--g3-`
+- 构建：`vite build`（vue external + `preserveModules` + `vite-plugin-dts` rollupTypes）；`@lucide/vue` 需一并 external
+- 文档：Docus/Nuxt，`@g3soft/ui` alias 到源码热更；API 由 `scripts/gen-api.mjs` + `vue-docgen-api` 生成
+- 运行时零第三方浮层库：定位/焦点/滚动锁/拖拽全部自研（与 fms 一致，保持依赖最小）
+
+## 实现思路
+
+以「移植 fms 实现 + 套 g3 规范外壳」为策略：行为逻辑（受控/非受控、浮层定位、焦点陷阱、滚动锁、拖拽缩放、命令式挂载）直接平移 fms 已验证的做法；表现层（类名、颜色、尺寸、文案）全部改由 `useNamespace()` 与 `v()` 令牌兜底生成；API 层改为类型式 `defineProps<Props>()` + `types.ts`（JSDoc 写在字段上，这是 `vue-docgen-api` 唯一能提取到描述的写法，对象式 props 实测 description 全空）。
+
+## 关键技术决策
+
+### 1. z-index：分层注册表（不新增令牌）
+
+fms 用固定档位 CSS 变量（modal 3000 / popover 3500 / message 4000，注释强调「浮层必须高于 modal，否则弹窗内下拉被盖住」）；g3 已有 `_utils/z-index.ts`（base 2000 + 单调 `nextZIndex()`）。单调自增会随开关次数无限膨胀，固定档位又无法表达同档堆叠。结论：**改造 z-index.ts 为「三档 + 档内栈」**。
+
+- 档位：`popup`（浮层）/ `modal`（Modal、Drawer）/ `feedback`（Message、Notification），相对 base 偏移 0 / 1000 / 2000，满足 popup < modal < feedback
+- 档内用栈：打开时压入 `base + offset + 栈深`，关闭时把该值出栈并回收，避免无限增长
+- 保持向后兼容：`nextZIndex()` 无参仍返回 popup 档；`getBaseZIndex / setBaseZIndex / resetZIndex` 签名不变
+- base 来源不变：`ConfigProvider.zIndex`（默认 2000）或 `G3UI.config({ zIndex })`
+- 令牌层完全不出现 z-index（层级是运行时行为，不是视觉令牌）
+
+### 2. 令牌：只补 8 个跨组件变量
+
+fms 的 `--fms-*` 有 60+ 个，其中绝大多数是**组件私有尺寸**（switch 宽高、tag 高度、segmented 内边距、tree 缩进、select 浮层最大高度、splitter 命中区、grid gutter…）。这类一律**不进令牌**，直接在组件 SCSS 里 `v('switch-width', 32px)` 带兜底——既能被换肤覆盖，又不污染全局命名空间。
+
+映射结论：
+
+- 已有可复用：`--fms-primary*` → `--g3-color-primary(-hover/-active/-on)`；`--fms-text/-secondary` → `--g3-text-1/-2`；`--fms-border` → `--g3-border-color`；`--fms-card` → `--g3-bg-container`；`--fms-disabled-*` → `--g3-bg-disabled` / `--g3-text-disabled`；`--fms-success/warning/danger` → `--g3-color-success/warning/danger`；`--fms-control-height/radius` → `--g3-control-height(-sm/-lg)` / `--g3-radius(-sm/-lg)`
+- 省略（可用现有变量或直接写兜底）：`--fms-background`/`--fms-surface`（页面画布，属应用层职责）、`--fms-*-text` 语义色前景（统一用 `--g3-text-inverse`）、`--fms-frame-shadow`/`--fms-shadow-right`（框架级，非组件）、`--fms-font-size`/`--fms-line-height`（沿用 g3 的 `font-size` 档位）、`--fms-control-padding-x`/`--fms-control-size`（用 `--g3-space-*` 派生）、`--fms-ease-out/-in`（保留单档 `--g3-ease`，避免膨胀）、`--fms-offset-sm/-md`（用 `space-1/space-2`）
+- **新增（共 8 个，暗色同步覆盖）**：`--g3-color-primary-soft`（主色淡底：选中/hover 底）、`--g3-fill`（次级填充：hover 底、轨道底）、`--g3-fill-hover`（次级填充 hover）、`--g3-mask-bg`（遮罩）、`--g3-shadow-popup`（浮层阴影，区别于 `--g3-shadow`）、`--g3-line-height`、`--g3-duration-fast`、`--g3-duration-slow`（与已有 `--g3-duration` 组成三档动效）
+
+### 3. 浮层基础设施（一次实现，四处复用）
+
+把 fms 的 `utils/{position,focus,scroll,drag}.js` TS 化落到 `packages/ui/src/_utils/`，并在其之上做一个 `useFloating()` composable，供 popover / tooltip / dropdown / select / date-picker / range-picker / time-select 共用：触发器绑定、Teleport 到 `popupContainer`（默认 body）、打开即算坐标、`ResizeObserver` + 捕获阶段 scroll 监听重算、点击外部关闭、Esc 关闭、`followTriggerWidth`、`arrow`、`placement` 12 方位 + flip + shift。
+
+### 4. 全局配置统一（避免两套）
+
+fms 的 `config.js`（`uiConfig` / `setUIConfig`）**不移植**。g3 已有等价且更强的机制：`ConfigProvider.componentDefaults` + `G3UI.config()` / `getGlobalConfig()`。新增 `_composables/useComponentDefaults.ts` 实现「显式 prop > componentDefaults > withDefaults 默认」的回落（需要支持全局覆盖的 prop 其 default 写 `undefined`）。组件树外的命令式实例（Message / Notification / Modal.confirm）统一走 `getGlobalConfig()` 取 namespace / locale / popupContainer。
+
+### 5. gen-api 改造（必须，否则文档被覆盖）
+
+`gen-api.mjs` 的 key 是**目录名**，同一目录下多个 `.vue` 会互相覆盖（button-group、date、dropdown、form、grid、radio、splitter、tabs、tree 都存在子组件）。规则改为：**每个目录只解析其主组件**（优先 `index.ts` 中首個 `export { default as G3Xxx }` 指向的文件），子组件（Separator / Menu / DropdownItem / TreeNode / TabPane / Col / Panel / FormItem / FormGroup / CalendarPanel）作为内部文件不产出文档。
+
+## 实现注意事项（防回归）
+
+- **unwrapped 触发器两个已知陷阱（fms 已验证）**：① `<slot name="trigger"><slot /></slot>` 会产出多层 Fragment，`vnode.type === Symbol(Fragment)` 导致触发器识别失败——必须 `while (vnode.type === Fragment)` 循环解包到真实元素/组件；② `<component :is="vnode">` 会丢失 `on*` 监听与 `dirs`，必须用 `{ render: () => injectedTrigger.value }` 渲染函数包装，且返回值必须是 `cloneVNode` 原始结果（保留内部标记）再在其上追加 `dirs`，不能用对象展开。
+- 滚动锁改为**引用计数**：Modal 内嵌 Select、Drawer 叠 Modal 时不能互相提前解锁；解锁一律放到退场动画 `after-leave` 之后，用 `scrollLocked` 标志位保证「after-leave」与「卸载兜底」只解锁一次，并还原焦点到触发元素。
+- 遮罩点击判定保留 fms 的 `mousedown` 在面板内标记（防拖选文本误关）。
+- 命令式挂载（Modal.confirm）首帧即 open，`<Transition>` 必须加 `appear`，`watch(isOpen, ..., { immediate: true })` 才能在挂载时初始化滚动锁/焦点/拖拽。
+- 组件 `<style>` 一律**非 scoped**，类名/keyframes 全由 `useNamespace()` 与 SCSS `b/e/m/em/is` 派生，颜色尺寸一律 `v()` 带兜底。
+- 文案不得硬编码，统一走 `useLocale()`——需扩充 `locale/index.ts`（confirm / cancel / placeholder / empty / pagination total / 日期面板 / aria-label 等键）。
+- `@lucide/vue` 必须写进 `packages/ui/package.json` 的 `dependencies` 且加入 `vite.config.ts` 的 `rollupOptions.external`，否则会被打进产物。
+- 仓库无测试，每批验收：`pnpm --filter @g3soft/tokens build` → `pnpm --filter @g3soft/ui build`（顺带类型检查）→ `pnpm gen:api`，并在 docs 示例页冒烟。
+
+## 架构设计
+
+```mermaid
+graph TD
+  A[应用层 / docs 示例] --> B[组件层 28 个 G3* 组件]
+  B --> C[_composables: useNamespace / useLocale / useFloating / useComponentDefaults]
+  B --> D[_utils: position / focus / scroll / drag / z-index / date / global-config / color]
+  C --> E[config-provider: ConfigProvider + configProviderKey]
+  C --> F[_utils/global-config: 组件树外兜底]
+  B --> G[@g3soft/tokens: --g3-* 变量 + SCSS b/e/m/v]
+  B --> H[@lucide/vue 图标]
+  I[命令式: G3Modal.confirm / G3Message / G3Notification] --> F
+  I --> D
+```
+
+分层职责：组件层只做渲染与交互；跨组件能力（定位、焦点、滚动锁、层级、拖拽）下沉到 `_utils`；可复用响应式逻辑（命名空间、locale、浮层、默认 props）收敛到 `_composables`；主题与尺寸全部来自 tokens，运行时主题派生由 `ConfigProvider` + `derivePalette()` 负责。
+
+## 目录结构
+
+```
+packages/tokens/src/scss/
+├── _config.scss        # [MODIFY] 补 $fill / $mask 等种子值（若需）
+├── theme.scss          # [MODIFY] 新增 8 个变量 + 暗色覆盖：color-primary-soft / fill / fill-hover / mask-bg / shadow-popup / line-height / duration-fast / duration-slow
+└── _functions.scss     # [MODIFY] 无改动（v() 兜底机制沿用）
+
+packages/ui/
+├── package.json        # [MODIFY] dependencies 增加 @lucide/vue
+├── vite.config.ts      # [MODIFY] rollupOptions.external 追加 '@lucide/vue'
+└── src/
+    ├── index.ts        # [MODIFY] re-export 全部新组件与类型，扩充 components 注册常量
+    ├── env.d.ts        # [MODIFY] 无实质改动（保留编译期常量声明）
+    ├── _utils/
+    │   ├── z-index.ts      # [MODIFY] 分层：nextZIndex(layer) / releaseZIndex(v)，保留原 API 兼容
+    │   ├── position.ts     # [NEW] TS 化 computePosition + PLACEMENTS（12 方位 flip + shift）
+    │   ├── focus.ts        # [NEW] focusFirst / trapFocus
+    │   ├── scroll.ts       # [NEW] lockScroll / unlockScroll（引用计数）
+    │   ├── drag.ts         # [NEW] bindDrag / bindResize（返回 { reset, destroy }）
+    │   ├── date.ts         # [NEW] 日期解析/格式化/面板数据（原 date-utils.js TS 化，供三个日期组件共用）
+    │   ├── global-config.ts# [MODIFY] 维持 GlobalConfig（namespace/zIndex/locale/popupContainer）
+    │   └── color.ts        # [MODIFY] 无改动
+    ├── _composables/
+    │   ├── useFloating.ts         # [NEW] 浮层通用逻辑（定位/外部点击/Esc/重算/Teleport 容器）
+    │   ├── useComponentDefaults.ts# [NEW] prop > componentDefaults > 内置默认 的回落
+    │   ├── useNamespace.ts        # [MODIFY] 无实质改动
+    │   └── useLocale.ts           # [MODIFY] 无实质改动
+    ├── config-provider/     # [MODIFY] 维持 provide 结构，文档补 componentDefaults 用法
+    ├── locale/index.ts      # [MODIFY] 扩充 Locale 键（confirm/cancel/placeholder/empty/pagination/date/aria）
+    ├── button/              # [MODIFY] 重写为 fms 变体体系（primary/secondary/outline/ghost/danger/danger-outline/link/icon）+ loading 光标、hover 去抖、按下缩放
+    ├── button-group/        # [NEW] G3ButtonGroup + 内部 Separator.vue
+    ├── space/               # [NEW] G3Space
+    ├── grid/                # [NEW] G3Row（主组件）+ 内部 Col.vue → G3Col
+    ├── scrollbar/           # [NEW] G3Scrollbar
+    ├── spin/                # [NEW] G3Spin（含 indicator / description 插槽、包裹模式）
+    ├── tag/                 # [NEW] G3Tag（icon / closeIcon 插槽）
+    ├── segmented/           # [NEW] G3Segmented
+    ├── input/               # [NEW] G3Input（prefix/suffix 插槽、clearable、事件 update:modelValue/change/blur/focus/clear）
+    ├── checkbox/            # [NEW] G3Checkbox（indeterminate）
+    ├── radio/               # [NEW] G3Radio（主组件）+ 内部 RadioGroup.vue → G3RadioGroup
+    ├── switch/              # [NEW] G3Switch
+    ├── select/              # [NEW] G3Select（浮层复用 useFloating、搜索、footer/load-more）
+    ├── date-picker/         # [NEW] G3DatePicker（主组件）+ 内部 CalendarPanel.vue
+    ├── range-picker/        # [NEW] G3RangePicker
+    ├── time-select/         # [NEW] G3TimeSelect
+    ├── form/                # [NEW] G3Form（主组件）+ 内部 FormItem.vue / FormGroup.vue / validate.ts → G3FormItem / G3FormGroup
+    ├── popover/             # [NEW] G3Popover（unwrapped 模式，含 Fragment 解包处理）
+    ├── tooltip/             # [NEW] G3Tooltip（hover 延迟）
+    ├── dropdown/            # [NEW] G3Dropdown + 内部 DropdownItem.vue / Menu.vue
+    ├── modal/               # [NEW] G3Modal（confirm/cancel 语义）+ 内部 ModalConfirm.vue + confirm.ts（命令式）
+    ├── drawer/              # [NEW] G3Drawer
+    ├── message/             # [NEW] 命令式 G3Message（manager + container + store）
+    ├── notification/        # [NEW] 命令式 G3Notification（同构）
+    ├── tree/                # [NEW] G3Tree（主组件）+ 内部 TreeNode.vue / utils.ts
+    ├── tabs/                # [NEW] G3Tabs（主组件）+ 内部 TabPane.vue
+    ├── pagination/          # [NEW] G3Pagination
+    └── splitter/            # [NEW] G3Splitter（主组件）+ 内部 Panel.vue
+
+scripts/
+└── gen-api.mjs         # [MODIFY] 每目录只解析主组件，避免子组件覆盖同名 key
+
+docs/
+├── examples/<component>/*.vue  # [NEW] 每个组件 2-6 个示例（button/* 需按新变体重写）
+├── content/ui/2.general/button.md  # [MODIFY] 按新 API 重写
+├── content/ui/<分类>/<component>.md # [NEW] 每组件一个文档页（:::demo + ApiTable）
+├── content/ui/.navigation.yml      # [MODIFY] 补齐分类导航
+└── data/api/*.json                 # [AUTO] pnpm gen:api 生成，不可手写
+```
+
+## 关键代码结构
+
+```ts
+// packages/ui/src/_utils/z-index.ts —— 分层 + 档内栈，替换单调自增
+export type ZIndexLayer = 'popup' | 'modal' | 'feedback'
+export function nextZIndex(layer?: ZIndexLayer): number   // 无参兼容旧行为（popup 档）
+export function releaseZIndex(value: number): void        // 关闭时回收，防止无限膨胀
+export function getBaseZIndex(): number
+export function setBaseZIndex(value: number): void
+export function resetZIndex(): void
+```
+
+```ts
+// packages/ui/src/modal/types.ts —— confirm 语义（原 okText/onOk/emit('ok') 全部重命名）
+export interface ModalProps {
+  open?: boolean; defaultOpen?: boolean
+  title?: string; width?: number | string
+  centered?: boolean; mask?: boolean; maskClosable?: boolean; keyboard?: boolean
+  closable?: boolean; fullscreen?: boolean; resizable?: boolean; footer?: boolean
+  /** 确认按钮文字（原 okText） */
+  confirmText?: string
+  cancelText?: string
+  /** 确认中：按钮 loading 且阻止一切关闭 */
+  confirmLoading?: boolean
+}
+export interface ModalConfirmOptions {
+  title?: string; content?: string
+  confirmText?: string; cancelText?: string
+  /** 透传给确认按钮（原 okButtonProps） */
+  confirmButtonProps?: Partial<ButtonProps>
+  /** 返回 Promise 时按钮 loading：resolve 关闭、reject 保持打开（原 onOk） */
+  onConfirm?: () => void | Promise<unknown>
+  onCancel?: () => void
+}
+export interface ModalConfirmHandle { destroy: () => void }
+// emits: 'update:open' | 'confirm' | 'cancel' | 'closed'
+// G3Modal.confirm(options: ModalConfirmOptions): ModalConfirmHandle
+```
+
+```ts
+// packages/ui/src/_composables/useFloating.ts —— 浮层通用能力
+export interface UseFloatingOptions {
+  placement?: Placement      // 12 方位
+  offset?: number
+  arrow?: boolean
+  followTriggerWidth?: boolean
+  popupContainer?: PopupContainer
+}
+export interface UseFloatingReturn {
+  triggerRef: Ref<HTMLElement | null>
+  floatingRef: Ref<HTMLElement | null>
+  floatingStyle: ComputedRef<CSSProperties>
+  resolvedPlacement: Readonly<Ref<Placement>>
+  update: () => void
+}
+```
+
+## 设计风格
+
+延续 g3soft 现有基调：中性克制的 shadcn 风格——主色由单一 primary 派生（hover/active 走主色透明度），层次靠"面"不靠"线"，1px 细边框只用于描边类控件。组件视觉以 fms-vue 的成熟交互为准：按钮 8 档变体（primary/secondary/outline/ghost/danger/danger-outline/link/icon），按下 0.97 缩放、hover 去抖（离开加 60ms 延迟防边缘闪烁）、加载态保留原配色并用 wait 光标、禁用态整体降透明度。
+
+## 交互与动效
+
+三档时长（fast/base/slow）+ 单档缓动：跟手操作用 fast，下拉/提示用 base，Modal/Drawer 用 slow；只允许过渡 opacity / transform / color 系，禁止过渡 width/height/top/left。浮层入场错峰、退场不错峰；`prefers-reduced-motion` 下时长归零。
+
+## 布局与响应式
+
+控件三档尺寸（sm 24 / 默认 32 / lg 40），间距走 space-1..6（4px 阶梯），圆角 sm/radius/lg（4/6/8）。浮层（popover/tooltip/dropdown/select/date）统一 12 方位定位 + flip + shift + 8px 视口边距，保证弹窗内下拉可见。
+
+## Agent Extensions
+
+### Skill
+
+- **ui-ux-pro-max**
+- Purpose: 为 28 个组件确定统一的视觉规范（变体配色、间距节奏、浮层阴影层级、动效档位）与可访问性要求
+- Expected outcome: 产出一份与 `--g3-*` 令牌一致的组件级视觉基线，供各批实现直接套用，避免分批实现出现风格漂移
+- **antdv-next**
+- Purpose: 校对 Modal.confirm / Form / Select / Tree / Pagination 等组件的 confirm 语义 API 命名与行为（onConfirm 的 Promise loading、静默关闭策略）
+- Expected outcome: confirm 风格 API 与主流库心智一致，命令式 `G3Modal.confirm({ onConfirm })` 行为定义无歧义
+
+### SubAgent
+
+- **code-explorer**
+- Purpose: 分批深挖 `D:/workspace/code/fms/fms-vue/src/components/ui` 各组件源码（props/emits/slots 全量、定位与焦点实现细节）
+- Expected outcome: 每批实现前拿到该批组件的完整原始 API 与实现要点，避免凭猜测造 API
\ No newline at end of file
diff --git a/code/g3soft-libs/.gitignore b/code/g3soft-libs/.gitignore
index ffa91e73..435133a2 100644
--- a/code/g3soft-libs/.gitignore
+++ b/code/g3soft-libs/.gitignore
@@ -15,3 +15,7 @@ coverage
 *.log
 *.tsbuildinfo
 .DS_Store
+
+# 测试产物（vitest json 报告 / Playwright 截图、trace、报告）
+test-results
+playwright-report
diff --git a/code/g3soft-libs/CODEBUDDY.md b/code/g3soft-libs/CODEBUDDY.md
index 508505f4..d14f7de7 100644
--- a/code/g3soft-libs/CODEBUDDY.md
+++ b/code/g3soft-libs/CODEBUDDY.md
@@ -8,8 +8,7 @@ G3Soft frontend infrastructure — a pnpm monorepo holding a self-built **Vue 3
 
 - `packages/ui` (`@g3soft/ui`) — component library, published to a private npm registry. One directory per component under `src/<name>/`.
 - `packages/tokens` (`@g3soft/tokens`) — design tokens as plain CSS (`--g3-*` variables), shared by the library and the docs site.
-- `docs` (`@g3soft/docs`) — Docus/Nuxt docs site. `private: true`, never published.
-- `scripts/gen-api.mjs` — generates component API data from source.
+- `docs` (`@g3soft/docs`) — Docus/Nuxt docs site. `private: true`, never published. 组件文档（示例 + API）全部手写在 `docs/content/ui/<分类>/<组件>.md`。
 
 Requires Node >= 20.19 and pnpm 11 (see `packageManager` in root `package.json`).
 
@@ -22,8 +21,6 @@ pnpm dev            # start docs site (http://localhost:3000); live-reloads pack
 pnpm build          # build all packages under packages/** (component lib -> dist)
 pnpm build:docs     # build docs static site -> docs/.output/public
 pnpm preview:docs   # preview the built docs site
-
-pnpm gen:api        # regenerate docs/data/api/*.json from component source (REQUIRED after changing props/events/slots)
 ```
 
 Deploying docs to a subpath:
@@ -46,7 +43,7 @@ pnpm release        # build + publish to the private registry
 
 ### Running a single component's checks
 
-There is no per-component test/lint script. The closest equivalent is `pnpm --filter @g3soft/ui build` (runs `vite build`, which type-checks declarations via `vite-plugin-dts`), and `pnpm gen:api` to verify the docgen extraction still parses a component.
+There is no per-component test/lint script. The closest equivalent is `pnpm --filter @g3soft/ui build` (runs `vite build`, which type-checks declarations via `vite-plugin-dts`).
 
 ## Architecture
 
@@ -78,13 +75,18 @@ Nuxt-related deps appear **only** in `docs/package.json`; the library's dependen
 - `vite.resolve.alias` points `@g3soft/ui` and `@g3soft/tokens` **directly at `packages/*/src`**, so the docs site can develop against the library without building it. Editing `packages/ui` hot-reloads the docs immediately.
 - `site.url` is required (sitemap, llms.txt, OG images) — missing it breaks prerender with a 500.
 - Deploy base path comes from `NUXT_APP_BASE_URL` (Nuxt's env override for `app.baseURL`), never hardcoded.
-- `docs/app/components/content/` holds components usable directly inside Markdown: `Demo.vue` (renders a runnable example + source) and `ApiTable.vue` (renders the generated API tables).
+- `docs/app/components/content/` holds components usable directly inside Markdown: `Demo.vue` (renders a runnable example + source).
 
-### API generation pipeline
+### 组件文档写作约定（手写，不生成）
 
-`scripts/gen-api.mjs` uses `vue-docgen-api` to parse every `.vue` under `packages/ui/src`, extracts props/events/slots and their JSDoc comments, and writes `docs/data/api/<dirName>.json`. `ApiTable.vue` reads those JSON files by component name.
+组件文档在 `docs/content/ui/<分类>/<组件>.md` 里**手写全文**：正文说明 + `:::demo{name="<组件>/<示例>"}:::` + 手写的 API 表格（Props / Events / Slots / Exposed / 类型定义 / 样式变量 / 实现说明）。
 
-Consequence: **API tables are generated from source and must never be hand-written.** The component directory name is the doc key (`src/button/Button.vue` → `button`). After any change to a component's props/events/slots, run `pnpm gen:api`.
+约定：
+
+- **一个功能一个示例**：示例文件按功能命名（`basic` / `variant` / `loading` / `remote` …），不要写「大杂烩」示例；示例内用注释说明「这个功能怎么用」。
+- 示例里**不要在 setup 顶层使用 `window` / `document`**（文档站是 SSR 预渲染的），需要浏览器 API 时放到 `onMounted`。
+- 改组件的 props / events / slots 时，同步改对应 md 的 API 表格——没有生成器兜底，忘改就是文档错误。
+- 分类目录：`1.usage` / `2.general` / `3.form` / `4.overlay` / `5.feedback` / `6.data`，每个分类有 `.navigation.yml`。
 
 ### Design tokens (`packages/tokens`)
 
@@ -100,10 +102,65 @@ Consequence: **API tables are generated from source and must never be hand-writt
 
 - **No `scoped` in component `<style>`.** Isolate with the `g3-` prefix + BEM naming so consumers can override.
 - **Never hardcode colors or sizes** — always reference `--g3-*` variables, and give every variable a fallback value (e.g. `var(--g3-color-primary, #18181b)`) so components render correctly even when `@g3soft/tokens` is not loaded.
-- **Component API docs are generated, not authored** — changes to props/events/slots require `pnpm gen:api`.
-- **Examples** live at `docs/examples/<component>/<example>.vue` and are referenced in Markdown as `::demo{name="<component>/<example>"}`. API tables use `<ApiTable name="<component>" />`.
+- **组件 API 文档手写**：改 props/events/slots 时同步更新 `docs/content/ui/**/<组件>.md` 的 API 表格（没有自动生成器）。
+- **Examples** live at `docs/examples/<component>/<example>.vue` and are referenced in Markdown as `::demo{name="<component>/<example>"}`. 一个功能一个示例；API 表格直接写在 md 里。
 - New components get a `src/<name>/` directory (component `.vue`, `types.ts`, `index.ts`) and must be re-exported from `src/index.ts`.
 
+## 浮层陷阱（踩过，勿重犯）
+
+**`<component :is="X">` 的 `X` 必须是稳定引用。** `useUnwrappedTrigger` 返回的 `InjectedTrigger` 是一个恒定对象（内容由 render 内部读 computed）。早期实现写成 `computed(() => ({ render: () => vnode }))`，每次依赖变化都产出新组件对象，而 Vue patch 用 `n1.type === n2.type` 判断能否复用 —— 对象身份变了就卸载旧组件、挂载新组件。unwrapped 模式的触发器常常是 `<input>`（Select / DatePicker / Dropdown），DOM 一重建焦点就丢、随即派发 focusout，focusout 处理器又改状态触发下一次重算：**重建 → 失焦 → 改状态 → 重建**自我驱动，主线程被打满，表现为「点击 Select 后整机卡死」。规矩：`:is` 的值不能是每次求值都新建的对象/函数。
+
+**不要在 ResizeObserver 回调链里无谓写样式。** `useFloating` 观察浮层自身用于跟随重算，写 `min-width` 前要先比较旧值（见 `updatePosition`），否则样式写入与观察回调会互相喂数据形成反馈环。
+
+**`v-if` 不要和 `v-for` 写在同一元素上。** Vue 3 里 `v-if` 优先级更高，会在 `v-for` 建立作用域之前求值，模板中引用的循环变量此时是 `undefined`（实测直接抛 `Cannot read properties of undefined (reading 'key')` 打断整个渲染）。把 `v-for` 提到外层 `<template>` 上。
+
+**组件子节点是 `{ default: () => [...] }`，不是纯文本。** 声明式容器组件（如要收集 `<G3DropdownItem>编辑</G3DropdownItem>` 文案的 Dropdown）不能只读 `label` prop，也不能假设 children 是字符串：编译器把组件子节点编译成插槽对象，文本藏在 VNode 里。取值要走「字符串 → 数组 → isVNode 递归 → default() 工厂」这条链。
+
+**改 `types.ts` 里的 props 类型后要重启 dev server。** 运行时 props 声明由编译器解析 `defineProps<Props>()` 的 `types.ts` 生成，Vite 会缓存这一步：把必填改成可选后热更不生效，表现是「类型已改但仍报 Missing required prop」。硬刷新不够，重启 `pnpm dev` 才会重新解析。
+
+## 测试与自检（含 AI 使用方式）
+
+三层，按「跑得多快 → 能拦什么」递进，命令都在仓库根执行：
+
+| 层 | 命令 | 范围 |
+|---|---|---|
+| L1 纯函数 + L2 组件 | `pnpm test` | vitest + happy-dom：日期/校验/定位/分层/树算法 + 组件契约，秒级 |
+| L3 真浏览器 | `pnpm test:e2e` | Playwright：弹层层级、命中测试、拖拽、焦点陷阱、DOM 重建检测 |
+| 一把梭 | `pnpm verify` | tokens build → ui build → 单测 → E2E |
+
+- 单测与源码 colocate：`src/**/*.test.ts`；组件测试补丁在 `packages/ui/tests/setup.ts`（happy-dom 缺 ResizeObserver / matchMedia / PointerEvent）。
+- `packages/ui/vitest.config.ts` **刻意不复用** `vite.config.ts`（那份带 lib 构建与 dts 插件）；测试里把 `vue` alias 到完整版，才支持字符串模板挂载。
+- E2E 宿主页面是 `packages/ui/playground`：**新增可交互元素必须挂 `data-testid`**，用例只按 testid 找元素（不依赖文案与结构）。
+- 面向工具/AI 的产物：`packages/ui/test-results/unit.json`、`test-results/e2e.json`；失败自动留 screenshot / trace 于同目录。
+- 单跑一个用例：`pnpm --filter @g3soft/ui exec vitest run src/date/date-utils.test.ts`、`pnpm --filter @g3soft/ui exec playwright test e2e/layer.spec.ts`
+- 手测与探索：`pnpm playground`（http://localhost:5200），可直接用浏览器工具看真实渲染。
+
+**跑 E2E 前先清 `packages/ui/test-results`。** Playwright 启动时会递归删除上次产物，而 IDE 的 safe-delete 守卫会拦截 node 进程的批量删除，直接报 `[safe-delete][SAFE_DELETE_BULK_GUARD_ERROR]` 让整轮测试跑不起来。用 PowerShell 清理（不受该守卫限制）：`Remove-Item packages/ui/test-results -Recurse -Force`。
+
+**E2E 里用 `page.mouse.*` 之前先 `scrollIntoViewIfNeeded()`。** mouse 事件按视口坐标派发，元素在视口外时事件会落到别的元素上，表现为「拖拽/点击完全没反应」，极易误判成组件 bug；同理，`force: true` 只是跳过可点击性检查，事件仍按坐标派发，被遮罩盖住的按钮要点它请用 `dispatchEvent('click')`。
+
+**组件 vnode 收集要处理三种形态**：`label` 这类 camelCase prop、`item-key` 这类 **kebab-case**（`vnode.props` 里保留原样）、以及 `<Comp danger />` 这类**空值布尔属性**（值是 `''` 而非 `true`，用 `if (raw.x)` 会误判为 false，必须 `raw.x != null && raw.x !== false`）。Dropdown / Tabs 都因此踩过坑。
+
+**必须放 E2E 的行为**：层叠上下文与命中测试（`elementFromPoint`）、弹层定位与翻转、拖拽 / 缩放、焦点陷阱、DOM 重建计数、跨组件层级比较。happy-dom 没有布局引擎，这类断言在单测里只会「假装通过」。
+
+**多方向 / 多尺寸的组件，每个方向都要进回归。** Drawer 只验过默认的 `right`，「上下方向宽度不是 100%」就潜伏了很久：容器用 flex 的 `justify-content` / `align-items` 做吸附时，两条轴各只管一个方向，上下面板在主轴（水平）方向没有约束，宽度缩到内容宽。现在按方向定边（上下 `left/right: 0`、左右 `top/bottom: 0`，与 fms 一致），并由 `e2e/drawer.spec.ts` 锁住四方向的几何。
+
+**组件结构元素要显式重置 `margin` / `padding` / `border`。** Drawer 面板是 `<section>`（与 fms 一致），内部还有 `<header>` / `<footer>`，宿主页面里任何 `section { margin: 16px }` 这类**元素选择器**都会命中：实测 `margin-bottom: 16px` 会把「定边撑开」的高度吃掉 16px（720 → 704），表现为「抽屉撑不满」；border 在 border-box 下同样吃高度。组件用类选择器声明这些值为 0（特异性高于元素选择器）即可盖住。同理，**playground / 文档站自己的容器样式要用子选择器**（`.page > section`），不要写裸 `section` —— 这个坑就是这么踩到的（见 `playground/index.html` 注释）。
+
+**CSS 变量写进 `color-mix()` 必须包 `var()`。** `color-mix(in srgb, --g3-color-primary 12%, transparent)` 里少了 `var()`，整个函数解析失败、变量值为空 —— 表现是「树/树节点选中没有背景色」这种看起来像 JS 没生效的样式 bug。SCSS 里要写 `var(#{fn.css-var('color-primary')})`。**并且改完 `packages/tokens/src/scss` 必须 `pnpm --filter @g3soft/tokens build`**：`import '@g3soft/tokens'` 加载的是 `dist/index.css`，只改 src 不重新构建，页面拿到的还是旧值。
+
+**过渡不要包 `width` / `height`；首次定位前不要开过渡。** Segmented 的滑块一度把宽高也放进 `transition`：首次测量时它正从 `100%` 收缩动画中，肉眼是一闪，断言读到的是 104px 而不是 38px。现在宽高瞬时生效、只过渡 `transform` / `opacity`（与 fms 一致），并且首次定位在 `transition: none` 下完成（`thumbReady` 下一帧才置位），否则滑块会从左上角滑到选中项。
+
+**只固定该固定的东西。** Splitter 拖拽曾把**所有**面板都写成 px：那些原本靠 flex 自动分配的面板会被一并冻结成「按下那一刻的实测宽度」，表现为「一拖就整体跳一下」。只更新分隔条两侧的两块（`applySizes(sizes, index)`）。
+
+**Tree 的叶子缩进占位按兄弟判定。** 同一批兄弟里存在可展开节点时，叶子才渲染等宽占位（`placeholderKeys`）；整层都是叶子还空一格就是白占位置。懒加载下「未加载过」的节点算可展开。
+
+**给 Teleport / 多根组件挂 `data-testid` 会触发 Vue 的 attrs 继承警告**，挂在包裹 `<div>` 上（E2E 用 `getByTestId` 定位包裹层即可）。删掉组件上的 testid 前先确认没有 E2E 依赖它。
+
+**E2E 里这几个写法会「假失败」**：① hover 后立刻 `evaluate` 读 `border-color`，读到的是过渡中间值（215 而非 24）—— 用会重试的 `toHaveCSS`；② 跨实例取 locator（页面上有多组同组件时 `.first()` 可能来自别的实例）—— 先锁定父容器再 `locator`；③ `page.mouse` 用视口坐标且**不会自动滚动**，元素在视口外时拖拽直接落空（`scrollIntoViewIfNeeded` 先滚）；④ `offsetWidth` 是整数、`boundingBox()` 是亚像素，尺寸比较要留 1px 容差。
+
+**不要并行跑 `pnpm build` 与 `pnpm test:e2e`。** 两者都会拉起 Vite 并抢占 `packages/ui/dist`，`vite:prepare-out-dir` 会失败报「Build failed with 1 error」，而单独跑又是好的，极易误判成代码问题。
+
 ## Version constraints (do not relax)
 
 `pnpm-workspace.yaml` documents these deliberately — read it before touching dependency versions:
diff --git a/code/g3soft-libs/README.md b/code/g3soft-libs/README.md
index 146a259c..df7b117e 100644
--- a/code/g3soft-libs/README.md
+++ b/code/g3soft-libs/README.md
@@ -14,11 +14,9 @@ g3soft-libs/
 │   └── tokens/                # 设计变量，组件库与文档站共用
 ├── docs/                      # 文档站（private，不发布）
 │   ├── nuxt.config.ts         # Docus Layer + alias 直连 packages 源码
-│   ├── content/               # Markdown 内容（路由与导航自动生成）
-│   ├── examples/              # 可运行示例，按组件分目录
-│   ├── data/api/              # gen:api 生成的 API 数据（不要手改）
-│   └── app/components/content # Demo.vue / ApiTable.vue（可在 md 中直接使用）
-└── scripts/gen-api.mjs        # 从组件源码生成 API 表格数据
+│   ├── content/               # Markdown 内容：组件正文 + 手写 API 表格
+│   ├── examples/              # 可运行示例，一个功能一个文件，按组件分目录
+│   └── app/components/content # Demo.vue（可在 md 中直接使用）
 ```
 
 ## 环境要求
@@ -43,7 +41,6 @@ pnpm dev
 ## 构建
 
 ```bash
-pnpm gen:api      # 从组件源码重新生成 API 数据（改了 props/events/slots 后必跑）
 pnpm build        # 构建 packages/*（组件库产出 dist）
 pnpm build:docs   # 构建文档站静态文件
 ```
@@ -85,5 +82,5 @@ pnpm release          # 构建并发布到私库
 ## 约定
 
 - 组件样式**不写 `scoped`**，用 `g3-` 前缀 + BEM，颜色尺寸一律引用 `--g3-*` 变量。
-- API 表格由源码生成，**禁止手写**；改了组件记得跑 `pnpm gen:api`。
-- 示例放 `docs/examples/<组件名>/<示例名>.vue`，在 md 中用 `::demo{name="<组件名>/<示例名>"}` 引用。
+- 组件 API 文档**手写在 md 里**（Props / Events / Slots / 类型定义 / 样式变量 / 实现说明）；改了 props/events/slots 记得同步改文档。
+- 示例放 `docs/examples/<组件名>/<示例名>.vue`，在 md 中用 `::demo{name="<组件名>/<示例名>"}` 引用；**一个功能一个示例**，示例里不要在 setup 顶层用 `window` / `document`（文档站是 SSR 预渲染）。
diff --git a/code/g3soft-libs/docs/app/components/app/AppHeaderCTA.vue b/code/g3soft-libs/docs/app/components/app/AppHeaderCTA.vue
index dba73b3c..5bad377c 100644
--- a/code/g3soft-libs/docs/app/components/app/AppHeaderCTA.vue
+++ b/code/g3soft-libs/docs/app/components/app/AppHeaderCTA.vue
@@ -5,6 +5,12 @@ const route = useRoute()
 
 const sections = [
   { to: '/ui/usage/getting-started', prefix: '/ui', icon: 'i-lucide-component', label: 'UI 组件库' },
+  {
+    to: '/framework/layout',
+    prefix: '/framework',
+    icon: 'i-lucide-layout-dashboard',
+    label: '框架',
+  },
   { to: '/api/getting-started', prefix: '/api', icon: 'i-lucide-cable', label: '接口文档' },
 ]
 
diff --git a/code/g3soft-libs/docs/app/components/content/ApiTable.vue b/code/g3soft-libs/docs/app/components/content/ApiTable.vue
deleted file mode 100644
index 850c17a6..00000000
--- a/code/g3soft-libs/docs/app/components/content/ApiTable.vue
+++ /dev/null
@@ -1,137 +0,0 @@
-<script setup lang="ts">
-import { computed } from 'vue'
-
-interface ApiEntry {
-  name: string
-  description: string
-  type: string
-  defaultValue?: string
-}
-
-interface ApiDoc {
-  displayName: string
-  description: string
-  props: ApiEntry[]
-  events: ApiEntry[]
-  slots: ApiEntry[]
-}
-
-const props = defineProps<{
-  /** 组件名（与 packages/ui/src/<name>/ 目录一致），例如 "button" */
-  name: string
-}>()
-
-/**
- * 数据由 scripts/gen-api.mjs 从组件源码生成，不要手写。
- * 源码改动后执行 `pnpm gen:api` 即可刷新。
- */
-const data = import.meta.glob('../../../data/api/*.json', { eager: true }) as Record<
-  string,
-  { default: ApiDoc }
->
-
-const doc = computed<ApiDoc | undefined>(() => {
-  const key = Object.keys(data).find((path) => path.endsWith(`/${props.name}.json`))
-  return key ? data[key].default : undefined
-})
-</script>
-
-<template>
-  <div v-if="doc" class="g3-api">
-    <p v-if="doc.description" class="g3-api__desc">{{ doc.description }}</p>
-
-    <template v-if="doc.props.length">
-      <h3>属性</h3>
-      <table>
-        <thead>
-          <tr><th>属性</th><th>说明</th><th>类型</th><th>默认值</th></tr>
-        </thead>
-        <tbody>
-          <tr v-for="item in doc.props" :key="item.name">
-            <td><code>{{ item.name }}</code></td>
-            <td>{{ item.description }}</td>
-            <td><code>{{ item.type }}</code></td>
-            <td><code>{{ item.defaultValue }}</code></td>
-          </tr>
-        </tbody>
-      </table>
-    </template>
-
-    <template v-if="doc.events.length">
-      <h3>事件</h3>
-      <table>
-        <thead>
-          <tr><th>事件名</th><th>说明</th><th>类型</th></tr>
-        </thead>
-        <tbody>
-          <tr v-for="item in doc.events" :key="item.name">
-            <td><code>{{ item.name }}</code></td>
-            <td>{{ item.description }}</td>
-            <td><code>{{ item.type }}</code></td>
-          </tr>
-        </tbody>
-      </table>
-    </template>
-
-    <template v-if="doc.slots.length">
-      <h3>插槽</h3>
-      <table>
-        <thead>
-          <tr><th>插槽名</th><th>说明</th></tr>
-        </thead>
-        <tbody>
-          <tr v-for="item in doc.slots" :key="item.name">
-            <td><code>{{ item.name }}</code></td>
-            <td>{{ item.description }}</td>
-          </tr>
-        </tbody>
-      </table>
-    </template>
-  </div>
-
-  <div v-else class="g3-api__missing">
-    未找到 <code>{{ name }}</code> 的 API 数据，请先执行 <code>pnpm gen:api</code>。
-  </div>
-</template>
-
-<style>
-.g3-api__desc {
-  color: var(--ui-text-muted, #6b7280);
-}
-
-.g3-api h3 {
-  margin-top: 28px;
-  font-size: 16px;
-}
-
-.g3-api__missing {
-  padding: 12px 16px;
-  border: 1px dashed var(--ui-border, #e5e7eb);
-  border-radius: 8px;
-  font-size: 13px;
-  color: var(--ui-text-muted, #6b7280);
-}
-
-.g3-api table {
-  width: 100%;
-  border-collapse: collapse;
-  font-size: 13px;
-}
-
-.g3-api th,
-.g3-api td {
-  padding: 10px 14px;
-  border: 1px solid var(--ui-border, #e5e7eb);
-  text-align: left;
-  vertical-align: top;
-}
-
-.g3-api th {
-  background: var(--ui-bg-muted, #f9fafb);
-  font-weight: 600;
-}
-
-.g3-api td code {
-  white-space: nowrap;
-}
-</style>
diff --git a/code/g3soft-libs/docs/content/framework/.navigation.yml b/code/g3soft-libs/docs/content/framework/.navigation.yml
new file mode 100644
index 00000000..30a9bf80
--- /dev/null
+++ b/code/g3soft-libs/docs/content/framework/.navigation.yml
@@ -0,0 +1,2 @@
+title: 框架
+icon: i-lucide-layout-dashboard
diff --git a/code/g3soft-libs/docs/content/framework/1.layout/.navigation.yml b/code/g3soft-libs/docs/content/framework/1.layout/.navigation.yml
new file mode 100644
index 00000000..7cc790da
--- /dev/null
+++ b/code/g3soft-libs/docs/content/framework/1.layout/.navigation.yml
@@ -0,0 +1,2 @@
+title: 布局
+icon: i-lucide-panel-left
diff --git a/code/g3soft-libs/docs/content/framework/1.layout/index.md b/code/g3soft-libs/docs/content/framework/1.layout/index.md
new file mode 100644
index 00000000..9615df10
--- /dev/null
+++ b/code/g3soft-libs/docs/content/framework/1.layout/index.md
@@ -0,0 +1,21 @@
+---
+title: Layout 布局框架
+description: G3 框架的布局骨架，支持 7 种布局模式，菜单/页签数据由宿主注入
+---
+
+# Layout 布局框架
+
+`G3Layout` 是 `@g3soft/framework` 的布局骨架。它只负责「怎么摆」，不关心菜单从哪来 —— 菜单、用户、页签都由宿主通过 props / 插槽注入。
+
+点击下方按钮切换 7 种布局模式：
+
+:::demo{name="layout/basic"}
+:::
+
+## 说明
+
+- **7 种模式**：`sidebar-nav`（垂直，默认）/ `header-nav`（顶部）/ `sidebar-mixed-nav`（双列）/ `mixed-nav` / `header-sidebar-nav` / `header-mixed-nav` / `full-content`。
+- **一个组件 + 模式表驱动**：内部按 `layout` prop 条件渲染，不拆成 7 个组件。
+- **菜单数据注入**：`:menus` 直接给数组，或 `:menu-source` 给函数（framework 接管加载态）。
+- **插槽宁可多不要少**：`logo` / `header-left` / `header-right` / `sidebar-top` / `sidebar-footer` / `tabbar-extra` / `breadcrumb-extra` / `page` / `default`。
+- **主题**：偏好里的主色 / 暗色最终经 `@g3soft/ui` 的 `ConfigProvider` 派生，不另起一套变量系统。
diff --git a/code/g3soft-libs/docs/content/index.md b/code/g3soft-libs/docs/content/index.md
index 82bd2435..fc70d4fb 100644
--- a/code/g3soft-libs/docs/content/index.md
+++ b/code/g3soft-libs/docs/content/index.md
@@ -36,7 +36,7 @@ to: /ui/general/button
 
 :::u-page-section
 #title
-四个内容域
+内容板块
 
 #features
 :::u-page-feature
@@ -60,30 +60,42 @@ to: /ui/general/button
 参考
 
 #description
-组件库 API 自动生成，另有 Hooks 与后端接口文档。
+每个组件的手写 API 与可运行示例，含 props / events / slots 与类型定义。
+:::
+
+:::u-page-feature
+---
+icon: i-lucide-layout-dashboard
+to: /framework/layout
+---
+#title
+框架
+
+#description
+应用框架：布局骨架（7 种模式）、偏好设置与主题，供业务项目引用。
 :::
 
 :::u-page-feature
 ---
 icon: i-lucide-ruler
-to: /standard/code-style
+to: /ui/usage/getting-started
 ---
 #title
-规范
+使用规范
 
 #description
-代码风格、命名约定、Git 与发布流程等团队工程规范。
+安装与引入方式、换肤与暗色主题、全局默认值配置。
 :::
 
 :::u-page-feature
 ---
 icon: i-lucide-lightbulb
-to: /explain/why-tokens
+to: /ui/overlay/modal
 ---
 #title
-解释
+浮层与反馈
 
 #description
-设计决策背后的取舍与常见问题解答。
+对话框、抽屉、下拉与提示：层级管理与确认语义的统一约定。
 :::
 :::
diff --git a/code/g3soft-libs/docs/content/ui/1.usage/getting-started.md b/code/g3soft-libs/docs/content/ui/1.usage/getting-started.md
index d3819358..58aed3cf 100644
--- a/code/g3soft-libs/docs/content/ui/1.usage/getting-started.md
+++ b/code/g3soft-libs/docs/content/ui/1.usage/getting-started.md
@@ -67,4 +67,5 @@ document.documentElement.dataset.g3Theme = 'dark'
 ## 下一步
 
 - 浏览[组件参考](/ui/general/button)
-- 了解[设计变量](/explain/why-tokens)的设计取舍
+- 了解[全局默认值（componentDefaults）](/ui/general/button#全局默认值)的用法
+- 需要弹窗时先看[对话框与确认语义](/ui/overlay/modal)
diff --git a/code/g3soft-libs/docs/content/ui/2.general/button-group.md b/code/g3soft-libs/docs/content/ui/2.general/button-group.md
new file mode 100644
index 00000000..9a245ba8
--- /dev/null
+++ b/code/g3soft-libs/docs/content/ui/2.general/button-group.md
@@ -0,0 +1,64 @@
+---
+title: ButtonGroup 按钮组
+description: 把多个按钮贴合排列成一组，适用于工具条与互斥动作
+---
+
+# ButtonGroup 按钮组
+
+按钮组把多个 `G3Button` 贴合排列：组内按钮去掉相邻圆角、边框重叠 1px，视觉上成为一整块。它只负责**布局**，每个按钮的 `type` / `size` / `disabled` 仍由自己决定。
+
+## 何时使用
+
+- 多个同层级操作成排出现（工具栏、卡片操作区）时，用按钮组把它们的关联关系表达出来；
+- 一组图标动作（左对齐 / 居中 / 右对齐）时使用，避免按钮之间出现缝隙；
+- 只是想给按钮之间加间距，请用 [Space 间距](/ui/general/space)，不要用按钮组。
+
+## 基础用法
+
+默认水平排列，组内按钮共用一套圆角与边框。
+
+:::demo{name="button-group/basic"}
+:::
+
+## 纵向排列
+
+`orientation="vertical"` 时纵向贴合，组内按钮宽度一致，常作为侧边操作组。
+
+:::demo{name="button-group/vertical"}
+:::
+
+## 组合不同变体与尺寸
+
+组内按钮各自保留 `type` / `size`；混排时建议统一变体，否则视觉层次会混乱。
+
+:::demo{name="button-group/variant"}
+:::
+
+## API
+
+### Props（ButtonGroup）
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | 排列方向。`vertical` 时纵向贴合、按钮等宽 |
+
+### Slots
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `default` | — | 组内的 `G3Button`。非按钮元素不会被索引到圆角规则里，请勿放置 |
+
+### 类型定义
+
+```ts
+export interface ButtonGroupProps {
+  orientation?: 'horizontal' | 'vertical'
+}
+```
+
+## 实现说明
+
+- 组内按钮通过 `margin-left: -1px` 让相邻边框重叠，避免出现 2px 的双线；
+- 首尾按钮单独恢复圆角，因此**中间的按钮不要插非按钮元素**（会被 CSS 的 `:first-child` / `:last-child` 规则错位）；
+- 分组用 `role="group"` 标注，屏幕阅读器会把它们视为一组操作；
+- 按钮聚焦时会 `z-index: 1` 浮到上层，避免焦点环被相邻按钮挡住。
diff --git a/code/g3soft-libs/docs/content/ui/2.general/button.md b/code/g3soft-libs/docs/content/ui/2.general/button.md
index 5bb5dcc8..9f0b1189 100644
--- a/code/g3soft-libs/docs/content/ui/2.general/button.md
+++ b/code/g3soft-libs/docs/content/ui/2.general/button.md
@@ -1,42 +1,191 @@
 ---
 title: Button 按钮
-description: 常用的操作按钮，支持多种视觉类型与状态
+description: 触发一个操作，支持 8 种视觉变体、3 档尺寸与加载态
 ---
 
 # Button 按钮
 
-常用的操作按钮，支持 7 种视觉类型、3 种尺寸与加载、禁用等状态。
+按钮用于触发一个即时操作。它承载「点击后发生什么」，因此同一区域里应当只有一个视觉上最重的按钮，其余操作降级表达。
+
+## 何时使用
+
+- 用户点击后即时触发一个动作（提交、保存、删除、导出）时使用；
+- 表单、对话框、工具条的最终动作使用 `primary`（或危险动作使用 `danger`）；
+- 面板头部、表格行内的图标类动作使用 `type="icon"`；
+- 只是页面跳转且不需要按钮外观时，直接用 `<a>`，或使用 `type="link"` 保持按钮语义。
 
 ## 基础用法
 
-::demo{name="button/basic"}
-::
+不传 `type` 时使用 `primary`；按钮内容写在默认插槽里。
 
-## 视觉类型
+:::demo{name="button/basic"}
+:::
 
-语义化类型用于表达操作的风险等级。
+按钮是原生 `<button>`，因此天然支持 `disabled`、键盘 `Enter / Space` 触发与表单语义。
 
-::demo{name="button/type"}
-::
+## 视觉变体
+
+`type` 决定按钮的视觉重量，请按「操作重要性」选择，而不是按颜色喜好选择。
+
+:::demo{name="button/variant"}
+:::
+
+| 变体 | 使用场景 |
+| --- | --- |
+| `primary` | 页面 / 表单 / 弹窗中的**主操作**，一屏通常只有一个 |
+| `secondary` | 次要操作，有底色但无主色，常用于「取消」「重置」 |
+| `outline` | 与 `primary` 并排出现时的次级操作，或工具条中的常规动作 |
+| `ghost` | 表格行、卡片内的低强调操作，hover 才出现底色 |
+| `danger` | **不可逆**的危险操作，如删除、停用；建议配合二次确认 |
+| `danger-outline` | 列表工具条中的危险动作：表达危险语义但不与 `primary` 抢视觉 |
+| `link` | 视觉上是文字链接，但保留按钮的尺寸、禁用与键盘语义 |
+| `icon` | 正方形描边图标按钮，用于工具条 / 面板头部动作位 |
 
 ## 尺寸
 
-::demo{name="button/size"}
-::
+`size` 提供 3 档，默认 `medium`（`--g3-control-height`，32px）。
 
-## 状态
+:::demo{name="button/size"}
+:::
 
-::demo{name="button/state"}
-::
+尺寸只影响按钮自身的高度与字号；图标按钮（`type="icon"`）会同步变成正方形。
 
-## 图标与撑满
+## 图标
 
-::demo{name="button/icon"}
-::
+使用 `#icon` 插槽放图标，图标大小跟随按钮字号（`1em`）；纯图标按钮用 `type="icon"`，**必须**提供 `aria-label`，否则屏幕阅读器读不出来。
 
-::demo{name="button/block"}
-::
+:::demo{name="button/icon"}
+:::
+
+`type="icon"` 的按钮没有文字，因此无障碍标签需要手动补：
+
+```vue
+<G3Button type="icon" aria-label="搜索">
+  <template #icon><Search /></template>
+</G3Button>
+```
+
+## 加载态
+
+`loading` 会同时做三件事：显示加载图标、进入原生 `disabled`、**拦截 `click` 事件**（不会触发 `click`），因此可以直接用它防止重复提交。
+
+:::demo{name="button/loading"}
+:::
+
+需要注意的是：`loading` 时按钮是原生禁用状态，浏览器不会派发 `click`；组件内部也额外做了拦截，避免在「按下瞬间进入 loading」时重复触发。
+
+## 禁用态
+
+`disabled` 使用原生 `disabled` 属性，同时降低整体透明度并显示禁用光标。
+
+:::demo{name="button/disabled"}
+:::
+
+禁用按钮的 `click` 不会触发，也不会被聚焦（原生行为），所以不要把「必填校验失败」的提交按钮设为禁用——用户会不知道原因。
+
+## 撑满宽度
+
+`block` 让按钮占满父容器宽度，常用于移动端、抽屉底部与卡片内。
+
+:::demo{name="button/block"}
+:::
+
+## 表单中的提交与重置
+
+`htmlType` 对应原生 `<button type>`，配合 G3Form 使用时写 `html-type="submit"` / `"reset"` 即可触发表单的提交与重置。
+
+:::demo{name="button/html-type"}
+:::
+
+`htmlType` 默认值是 `button`，这样按钮放在表单里不会意外提交（原生 `<button>` 在表单内的默认行为是 `submit`）。
+
+## 全局默认值
+
+通过 `G3ConfigProvider` 的 `componentDefaults` 可以一次性修改某类组件的默认 props，组件内部的回落顺序是 **显式 prop > 全局默认值 > 组件内置默认**。
+
+:::demo{name="button/global-defaults"}
+:::
+
+## click 事件
+
+`@click` 回传原生 `MouseEvent`，可以直接读取修饰键或做 `preventDefault`。
+
+:::demo{name="button/event"}
+:::
 
 ## API
 
-<ApiTable name="button" />
+### Props
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `type` | `'primary' \| 'secondary' \| 'outline' \| 'ghost' \| 'danger' \| 'danger-outline' \| 'link' \| 'icon'` | `'primary'` | 视觉变体。`icon` 为正方形描边图标按钮（无文字，需自行补 `aria-label`） |
+| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | 尺寸。对应高度 24px / 32px / 40px（`--g3-control-height-sm` / `--g3-control-height` / `--g3-control-height-lg`） |
+| `htmlType` | `'button' \| 'submit' \| 'reset'` | `'button'` | 原生 `type` 属性。表单里需要提交时写 `submit` |
+| `disabled` | `boolean` | `false` | 是否禁用。原生禁用，不派发 `click`，不参与焦点 |
+| `loading` | `boolean` | `false` | 是否加载中。展示加载图标并**阻止 `click`**，用于防重复提交 |
+| `block` | `boolean` | `false` | 是否撑满父容器宽度（`display: flex; width: 100%`） |
+
+> `type` 与 `size` 的 prop 默认值语义上留空，以便 `ConfigProvider.componentDefaults.button` 生效；未配置全局值时回落到 `primary` / `medium`。
+
+### Events
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `click` | `(event: MouseEvent)` | 点击按钮时触发。`disabled` 或 `loading` 时不会触发 |
+
+### Slots
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `default` | — | 按钮文字。为空时不渲染内容容器 |
+| `icon` | — | 按钮左侧图标。图标尺寸跟随字号（`1em`），加载中时会被加载图标顶到右侧 |
+
+### 类型定义
+
+```ts
+export type ButtonType =
+  | 'primary'
+  | 'secondary'
+  | 'outline'
+  | 'ghost'
+  | 'danger'
+  | 'danger-outline'
+  | 'link'
+  | 'icon'
+
+export type ButtonSize = 'small' | 'medium' | 'large'
+
+export interface ButtonProps {
+  type?: ButtonType
+  size?: ButtonSize
+  htmlType?: 'button' | 'submit' | 'reset'
+  disabled?: boolean
+  loading?: boolean
+  block?: boolean
+}
+
+export interface ButtonGroupProps {
+  /** 排列方向，默认 horizontal */
+  orientation?: 'horizontal' | 'vertical'
+}
+```
+
+### 样式变量
+
+按钮只引用设计变量，换肤时覆盖同名变量即可，不需要改组件代码：
+
+| 变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `--g3-control-height` | `32px` | 默认高度（`small` / `large` 用 `--g3-control-height-sm / -lg`） |
+| `--g3-radius` | `6px` | 圆角 |
+| `--g3-color-primary` | `#18181b` | `primary` 底色与 `link` 文字色 |
+| `--g3-color-primary-on` | `#fafafa` | `primary` 上的文字色 |
+| `--g3-color-danger` | `#ec4246` | `danger` / `danger-outline` 的红 |
+| `--g3-fill` / `--g3-fill-hover` | `rgba(0,0,0,.04 / .08)` | `secondary` / `ghost` / `icon` 的底色 |
+
+## 设计说明
+
+- **hover 去抖**：按钮的「离开 hover」过渡带 60ms 延迟，用来吸收鼠标在按钮边缘反复进出造成的背景闪烁；「进入 hover」延迟为 0，保证跟手。
+- **按下反馈**：`:active` 时 `transform: scale(0.97)`，加载态会压掉缩放，避免「进行中」的按钮抖动。
+- **禁用态**：整体 `opacity: .5`，保留原配色，不再改文字颜色——这样深浅主题下都能看出是同一个按钮。
diff --git a/code/g3soft-libs/docs/content/ui/2.general/grid.md b/code/g3soft-libs/docs/content/ui/2.general/grid.md
new file mode 100644
index 00000000..e2528314
--- /dev/null
+++ b/code/g3soft-libs/docs/content/ui/2.general/grid.md
@@ -0,0 +1,123 @@
+---
+title: Grid 栅格
+description: 24 栅格布局，支持间距、偏移、位移与 flex 自适应
+---
+
+# Grid 栅格
+
+栅格把一行分成 24 等份，用 `G3Row` 表示行、`G3Col` 表示列。它适合页面级 / 表单级的块状布局；元素之间的等距排列（按钮行、标签行）请用 [Space](/ui/general/space)。
+
+## 何时使用
+
+- 卡片、表单项、图表块的成行排布；
+- 需要按比例分配宽度（12 / 6 / 8 …）或「一侧固定、一侧自适应」时；
+- 需要控制主轴分布（居中、两端对齐）与交叉轴对齐时。
+
+## 基础用法
+
+`span` 表示占多少格（0-24）；一行内累计超过 24 会自动换行。
+
+:::demo{name="grid/basic"}
+:::
+
+## 间距
+
+`gutter` 传数字表示水平与垂直同值，传 `[水平, 垂直]` 可分别控制。栅格间距用 `gap` 实现，子列不再需要自己写 margin。
+
+:::demo{name="grid/gutter"}
+:::
+
+## 偏移与位移
+
+- `offset`：左侧留空格（不参与排序，位置固定）；
+- `push` / `pull`：左右位移，常用于调整视觉顺序；
+- `order`：flex 的排序值，最小排在最前。
+
+:::demo{name="grid/offset"}
+:::
+
+## 对齐与分布
+
+`align` 控制交叉轴（`align-items`），`justify` 控制主轴分布（`justify-content`）。需要行内有高度差时给 `Row` 一个固定高度。
+
+:::demo{name="grid/align"}
+:::
+
+## flex 自适应
+
+`flex` 传数字表示 `flex-grow` 的份数，传字符串则作为完整的 `flex` 简写使用。
+
+:::demo{name="grid/flex"}
+:::
+
+## 不换行
+
+`wrap=false` 时列不会换行，超出 24 格的部分会被压缩，适合「横向铺满、不允许折行」的工具条。
+
+:::demo{name="grid/no-wrap"}
+:::
+
+## API
+
+### Props（Row）
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `gutter` | `number \| [number, number]` | `0` | 栅格间距（px）。数组为 `[水平, 垂直]` |
+| `align` | `'top' \| 'middle' \| 'bottom' \| 'stretch'` | `'top'` | 交叉轴对齐（`align-items`） |
+| `justify` | `'start' \| 'end' \| 'center' \| 'space-around' \| 'space-between' \| 'space-evenly'` | `'start'` | 主轴分布（`justify-content`） |
+| `wrap` | `boolean` | `true` | 是否换行（`flex-wrap`） |
+
+### Props（Col）
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `span` | `number \| string` | — | 占位格数 0-24。不传时按 `flex` 或内容宽度 |
+| `offset` | `number \| string` | `0` | 左侧偏移格数 |
+| `order` | `number \| string` | — | 排序值（`order`） |
+| `push` | `number \| string` | `0` | 向右移动格数 |
+| `pull` | `number \| string` | `0` | 向左移动格数 |
+| `flex` | `number \| string` | — | 数字按 `flex: n n auto` 处理；字符串作为完整 `flex` 简写，如 `'0 0 200px'` |
+
+### Slots
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `default` | — | `Row` 内放 `Col`；`Col` 内放任意内容 |
+
+### 类型定义
+
+```ts
+export type GridGutter = number | [number, number]
+export type RowAlign = 'top' | 'middle' | 'bottom' | 'stretch'
+export type RowJustify =
+  | 'start'
+  | 'end'
+  | 'center'
+  | 'space-around'
+  | 'space-between'
+  | 'space-evenly'
+
+export interface RowProps {
+  gutter?: GridGutter
+  align?: RowAlign
+  justify?: RowJustify
+  wrap?: boolean
+}
+
+export interface ColProps {
+  span?: number | string
+  offset?: number | string
+  order?: number | string
+  push?: number | string
+  pull?: number | string
+  flex?: number | string
+}
+```
+
+## 实现说明
+
+- 栅格基于 flex：`Row` 是 `display: flex` + `flex-wrap`，`Col` 通过 `flex-basis: span/24 * 100%` 占位；
+- 水平间距在 `Row` 上用负 margin + `Col` 上的 padding 抵消（首尾不外扩）；垂直间距由 `row-gap` 承担；
+- `Col` 的 `span`、`offset`、`push` / `pull` / `order` 都支持字符串，便于上层做动态计算（如设计器里按栅格配置渲染）；
+- 不做 `xs / sm / md` 断点：本库面向中后台工具，布局由容器宽度（如 `Space` / `Splitter`）控制，需要响应式时请在业务层用 CSS 媒体查询覆盖。
diff --git a/code/g3soft-libs/docs/content/ui/2.general/segmented.md b/code/g3soft-libs/docs/content/ui/2.general/segmented.md
new file mode 100644
index 00000000..3bb80496
--- /dev/null
+++ b/code/g3soft-libs/docs/content/ui/2.general/segmented.md
@@ -0,0 +1,123 @@
+---
+title: Segmented 分段控制器
+description: 在一组互斥选项中切换，滑块跟随选中项移动
+---
+
+# Segmented 分段控制器
+
+分段控制器把 2-5 个互斥选项并排展示，用一个会滑动的滑块指示当前选项。它比 [Tabs](/ui/data/tabs) 轻量：切换的是**同一区域的视图模式**，不是内容面板。
+
+## 何时使用
+
+- 视图模式切换：列表 / 看板 / 时间线；
+- 粒度切换：日 / 周 / 月；
+- 表单里的少量选项（2-5 项）时，比 [Select](/ui/form/select) 更快、比 [Radio](/ui/form/radio) 更紧凑；
+- 选项超过 5 个、或需要多选时，请改用 Select / Checkbox。
+
+## 基础用法
+
+`options` 可以直接传原始值数组，选中值通过 `v-model` 双向绑定（支持字符串、数字、布尔）。
+
+:::demo{name="segmented/basic"}
+:::
+
+## 对象选项
+
+选项写成对象可以自定义显示文字、加图标、单独禁用某一项。
+
+:::demo{name="segmented/options"}
+:::
+
+## 圆角形状
+
+:::demo{name="segmented/shape"}
+:::
+
+## 纵向排列
+
+`vertical` 时滑块上下移动，适合做侧边栏的视图切换。
+
+:::demo{name="segmented/vertical"}
+:::
+
+## 撑满宽度
+
+`block` 让各项等分父容器宽度（纵向时为高度），常用于移动端或表单顶部。
+
+:::demo{name="segmented/block"}
+:::
+
+## 自定义每项内容
+
+`#label` 插槽作用域为 `{ option, index, checked }`：`option` 是原始选项对象，`checked` 表示该项是否选中。
+
+:::demo{name="segmented/custom-label"}
+:::
+
+## 非受控用法
+
+不传 `modelValue` 时组件内部维护选中值（默认不选中），通过 `change` 把结果抛给业务。
+
+:::demo{name="segmented/uncontrolled"}
+:::
+
+## API
+
+### Props
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `modelValue` | `string \| number \| boolean` | — | 双向绑定的选中值。不传即非受控 |
+| `options` | `Array<SegmentedOptionInput>` | `[]` | 选项数据源，元素可以是原始值或 `{ label, value, disabled, icon }` |
+| `shape` | `'default' \| 'round'` | `'default'` | 圆角形状。`round` 为全圆角胶囊 |
+| `vertical` | `boolean` | `false` | 纵向排列，滑块上下移动 |
+| `block` | `boolean` | `false` | 撑满父容器并等分各项 |
+| `disabled` | `boolean` | `false` | 禁用整组 |
+| `name` | `string` | 自动生成 | 原生 radio 组名。不传时用 `useId` 生成，避免多组互斥冲突 |
+
+### Events
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `update:modelValue` | `(value: string \| number \| boolean)` | 选中项变化时触发（受控与非受控都会触发） |
+| `change` | `(value: string \| number \| boolean)` | 同上，便于只监听变化 |
+
+### Slots
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `label` | `{ option: SegmentedOptionInput, index: number, checked: boolean }` | 自定义每项内容；不传时渲染 `icon` + `label` |
+
+### 类型定义
+
+```ts
+export type SegmentedValue = string | number | boolean
+
+export interface SegmentedOption {
+  label?: string
+  value: SegmentedValue
+  disabled?: boolean
+  icon?: Component | VNode
+}
+
+export type SegmentedOptionInput = SegmentedValue | SegmentedOption
+export type SegmentedShape = 'default' | 'round'
+```
+
+### 样式变量
+
+| 变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `--g3-segmented-padding` | `2px` | 轨道内边距 |
+| `--g3-radius` | `6px` | 轨道圆角（`round` 时为全圆角） |
+| `--g3-fill` | `rgba(0,0,0,.04)` | 轨道底色 |
+| `--g3-bg-container` | `#fff` | 滑块底色 |
+| `--g3-shadow` | `0 2px 8px rgba(0,0,0,.15)` | 滑块投影 |
+
+## 实现说明
+
+- 底层是**原生 radio 组**（`input[type=radio]` + `<label>`），因此键盘方向键切换、屏幕阅读器分组语义都由浏览器原生提供；
+- 滑块的位移与尺寸通过 `getBoundingClientRect` 测量并写入 CSS 变量，容器尺寸变化时用 `ResizeObserver` 重算，所以字体缩放、文案长度变化都能跟上；
+- 首次渲染时滑块先隐藏（`thumbVisible`），测量完成后再淡入，避免从 `(0,0)` 位置滑过来的闪动；
+- 选项里的图标会经过 `toRaw` 处理：`options` 常由 `ref` 提供，直接使用会被深层响应式包装，触发 Vue 的「组件被响应式化」告警；
+- 与 Tabs 的区别：Segmented 没有面板，只负责"选择"；Tabs 负责"选择 + 内容区 + 懒渲染"。
diff --git a/code/g3soft-libs/docs/content/ui/2.general/space.md b/code/g3soft-libs/docs/content/ui/2.general/space.md
new file mode 100644
index 00000000..4546ee46
--- /dev/null
+++ b/code/g3soft-libs/docs/content/ui/2.general/space.md
@@ -0,0 +1,107 @@
+---
+title: Space 间距
+description: 为一组内联元素设置统一间距，并支持插入分隔符
+---
+
+# Space 间距
+
+`Space` 给一组子元素之间加统一间距，省去给每个元素写 `margin` 的麻烦。
+
+**Space 与 Grid 的分工**：`Space` 面向「一行内联元素的等距排列」（按钮行、标签行、操作区），会给每个子元素包一层包装以支持分隔符与空节点隐藏；整块页面布局请用 [Grid 栅格](/ui/general/grid)。
+
+## 何时使用
+
+- 一排按钮 / 标签 / 文字之间需要统一间距时；
+- 需要在元素之间插入分隔符（`|`、`·`）时；
+- 子元素数量不确定、其中有条件渲染的节点时（空节点不会占位）。
+
+## 基础用法
+
+默认水平排列、间距 `small`（8px）、交叉轴居中对齐。
+
+:::demo{name="space/basic"}
+:::
+
+## 间距大小
+
+`size` 支持三种写法：预设名 `small` / `middle` / `large`、数字（按 px 处理）、以及 `[水平, 垂直]` 数组。
+
+:::demo{name="space/size"}
+:::
+
+| 写法 | 效果 |
+| --- | --- |
+| `size="small"` | 8px |
+| `size="middle"` | 16px（默认档，常用于行内） |
+| `size="large"` | 24px |
+| `:size="12"` | 12px |
+| `:size="[16, 8]"` | 列间距 16px、行间距 8px（配合 `wrap` 用） |
+
+## 纵向排列
+
+`vertical` 是简写；`orientation` 与它同时配置时，以 `orientation` 优先（这样上层组件透传 `orientation` 时不会被 `vertical` 覆盖）。
+
+:::demo{name="space/vertical"}
+:::
+
+## 分隔符
+
+`#separator` 插槽会在相邻子元素之间插入内容，**不会**在首尾添加。
+
+:::demo{name="space/separator"}
+:::
+
+## 自动换行
+
+`wrap` 只在水平方向生效；配合 `[水平, 垂直]` 形式的 `size` 可以分别控制列间距与行间距。
+
+:::demo{name="space/wrap"}
+:::
+
+## 空节点不占位
+
+`v-if` 关闭的节点、注释节点不会被计入间距，因此条件渲染不会留下空隙。
+
+:::demo{name="space/empty-children"}
+:::
+
+## API
+
+### Props
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `size` | `'small' \| 'middle' \| 'large' \| number \| string \| [SpaceSize, SpaceSize]` | `'small'` | 间距。数组按 `[水平, 垂直]` 解析；数字按 px；其他字符串原样透传给 `column-gap` / `row-gap` |
+| `orientation` | `'horizontal' \| 'vertical'` | 由 `vertical` 决定 | 排列方向。优先级高于 `vertical` |
+| `vertical` | `boolean` | `false` | 纵向排列的简写 |
+| `align` | `'start' \| 'end' \| 'center' \| 'baseline'` | 水平方向 `'center'`，纵向不设置 | 交叉轴对齐（`align-items`） |
+| `wrap` | `boolean` | `false` | 是否自动换行，仅水平方向生效 |
+
+### Slots
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `default` | — | 间距容器内的元素。每个有效子节点会被包一层 `g3-space__item` |
+| `separator` | — | 相邻元素之间插入的分隔内容 |
+
+### 类型定义
+
+```ts
+export type SpaceSize = 'small' | 'middle' | 'large' | number | string
+export type SpaceOrientation = 'horizontal' | 'vertical'
+export type SpaceAlign = 'start' | 'end' | 'center' | 'baseline'
+
+export interface SpaceProps {
+  size?: SpaceSize | [SpaceSize, SpaceSize]
+  orientation?: SpaceOrientation
+  vertical?: boolean
+  align?: SpaceAlign
+  wrap?: boolean
+}
+```
+
+## 实现说明
+
+- 间距用 CSS 的 `gap` 实现（`column-gap` / `row-gap`），因此**不依赖子元素是否有 margin**，也不会出现「相邻 margin 合并」的问题；
+- 子元素会被包一层 `inline-flex` 的 `g3-space__item`，这让分隔符有落点，同时过滤掉注释 / 文本空节点；
+- 纵向排列时默认不设置 `align`（即 `stretch`），这样「撑满宽度」的按钮才不会被压成内容宽度；需要居中时显式传 `align="center"`。
diff --git a/code/g3soft-libs/docs/content/ui/2.general/tag.md b/code/g3soft-libs/docs/content/ui/2.general/tag.md
new file mode 100644
index 00000000..79a383cb
--- /dev/null
+++ b/code/g3soft-libs/docs/content/ui/2.general/tag.md
@@ -0,0 +1,111 @@
+---
+title: Tag 标签
+description: 用于标记与分类的小型容器，支持多种变体、可关闭与链接
+---
+
+# Tag 标签
+
+标签用于标记对象的状态、分类或属性，例如「已完成」「前端」「张三」。它体量小、不可点击（除非传 `href`），因此不要用标签承载操作。
+
+## 何时使用
+
+- 表达状态：`success` 表示通过、`danger` 表示失败、`outline` 表示中性；
+- 表达多值属性：一行为一组标签；
+- 表示可移除的筛选项 / 输入项时使用 `closable`；
+- 需要点击跳转时传 `href`，组件会渲染成 `<a>`。
+
+## 视觉变体
+
+:::demo{name="tag/variant"}
+:::
+
+| 变体 | 语义 | 典型场景 |
+| --- | --- | --- |
+| `default` | 常规标记 | 分类、属性 |
+| `secondary` | 次要标记 | 筛选项、非重点属性 |
+| `outline` | 中性描边 | 需要与底色区分开的标记 |
+| `success` | 成功 | 已完成、已通过、已上线 |
+| `danger` | 失败 / 危险 | 失败、异常、已禁用 |
+| `ghost` | 极低强调 | 占位、统计数字 |
+
+## 可关闭
+
+`closable` 会渲染关闭按钮（`role="button"`，支持 Enter / Space）。**点击关闭后标签会自己隐藏**，同时触发 `close` 事件——业务通常只需要在事件里同步数据源。
+
+:::demo{name="tag/closable"}
+:::
+
+## 阻止自动关闭（受控）
+
+如果标签的显示与否由业务数据决定，在 `close` 里调用 `event.preventDefault()` 即可阻止自动隐藏。
+
+:::demo{name="tag/prevent-close"}
+:::
+
+## 图标
+
+`#icon` 放前置图标，`#close-icon` 可以替换默认的关闭图标（例如换成文字 `×`）。
+
+:::demo{name="tag/icon"}
+:::
+
+## 链接标签
+
+传 `href` 后渲染成 `<a>`；`disabled` 时会去掉 `href` 并标记 `aria-disabled`，避免出现「看起来能点但点了没反应」。
+
+:::demo{name="tag/link"}
+:::
+
+## API
+
+### Props
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `variant` | `'default' \| 'secondary' \| 'outline' \| 'success' \| 'danger' \| 'ghost'` | `'default'` | 视觉变体 |
+| `closable` | `boolean` | `false` | 是否显示关闭按钮。点击后触发 `close` 并自动隐藏（可用 `preventDefault` 阻止） |
+| `disabled` | `boolean` | `false` | 禁用态。关闭按钮不可用、`href` 被移除 |
+| `href` | `string` | — | 传入后渲染为 `<a>`；其余原生属性（如 `target`）会透传到该元素 |
+
+### Events
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `close` | `(event: Event)` | 点击关闭按钮时触发。调用 `event.preventDefault()` 可阻止标签自动隐藏 |
+
+### Slots
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `default` | — | 标签文本 |
+| `icon` | — | 前置图标（尺寸跟随字号 `1em`） |
+| `close-icon` | — | 自定义关闭图标，默认是 `X` 图标 |
+
+### 类型定义
+
+```ts
+export type TagVariant = 'default' | 'secondary' | 'outline' | 'success' | 'danger' | 'ghost'
+
+export interface TagProps {
+  variant?: TagVariant
+  closable?: boolean
+  disabled?: boolean
+  href?: string
+}
+```
+
+### 样式变量
+
+| 变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `--g3-tag-height` | `20px` | 标签高度（可通过组件私有变量覆盖） |
+| `--g3-font-size-sm` | `12px` | 字号 |
+| `--g3-radius-sm` | `4px` | 圆角 |
+| `--g3-color-success` / `--g3-color-danger` | `#45b114` / `#ec4246` | `success` / `danger` 的前景色 |
+| `--g3-fill` | `rgba(0,0,0,.04)` | `secondary` / `default` 的底色 |
+
+## 实现说明
+
+- 标签渲染为 `<span>`（或 `<a>`），是可内联排列的 `inline-flex`，因此可以直接放在文字流或 `Space` 里；
+- 关闭按钮是 `span[role="button"]` 而不是 `<button>`，避免在 `a` 形态下嵌套交互元素（HTML 不允许 `<a>` 内嵌 `<button>`）；
+- 关闭按钮的 `aria-label` 取自语言包（`locale.common.close`），可通过 `ConfigProvider.locale` 切换语言。
diff --git a/code/g3soft-libs/docs/content/ui/3.form/.navigation.yml b/code/g3soft-libs/docs/content/ui/3.form/.navigation.yml
new file mode 100644
index 00000000..7216aedb
--- /dev/null
+++ b/code/g3soft-libs/docs/content/ui/3.form/.navigation.yml
@@ -0,0 +1,2 @@
+title: 数据录入
+icon: i-lucide-text-cursor-input
diff --git a/code/g3soft-libs/docs/content/ui/3.form/checkbox.md b/code/g3soft-libs/docs/content/ui/3.form/checkbox.md
new file mode 100644
index 00000000..6c33c9e8
--- /dev/null
+++ b/code/g3soft-libs/docs/content/ui/3.form/checkbox.md
@@ -0,0 +1,102 @@
+---
+title: Checkbox 复选框
+description: 支持选中、未选中与半选三种状态的独立勾选控件
+---
+
+# Checkbox 复选框
+
+`Checkbox` 用于在一组互不排斥的选项里多选，或表示单个布尔开关（如「同意协议」）。
+
+## 何时使用
+
+- 多选：一组选项可以用任意组合选中；
+- 单个布尔：如「记住我」「同意条款」；
+- 父子联动：父项用 `indeterminate` 表达「部分选中」（见下方示例）；
+- 只有一个开关、立即生效的场景请用 [Switch](/ui/form/switch)。
+
+## 基础用法
+
+`v-model` 绑定 `boolean`。
+
+:::demo{name="checkbox/basic"}
+:::
+
+## 半选联动
+
+`indeterminate` 是纯展示状态：组件**不会**自动推导它，需要业务根据子项结果计算。
+
+:::demo{name="checkbox/indeterminate"}
+:::
+
+| 状态 | 表现 |
+| --- | --- |
+| `modelValue = true` | 显示勾选（优先级最高，会强制清掉半选） |
+| `modelValue = false` + `indeterminate = true` | 显示减号（半选） |
+| 两者都为 `false` | 显示空框 |
+
+## 禁用态
+
+:::demo{name="checkbox/disabled"}
+:::
+
+## 富内容
+
+默认插槽可以放任意内容（多行说明、链接、标签），此时仍然整块可点击。
+
+:::demo{name="checkbox/rich-label"}
+:::
+
+## API
+
+### Props
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `modelValue` | `boolean` | `false` | 双向绑定的选中状态 |
+| `indeterminate` | `boolean` | `false` | 半选状态（仅展示，需业务自行计算）。选中时会被忽略 |
+| `disabled` | `boolean` | `false` | 禁用态 |
+| `name` | `string` | — | 原生 `name`，用于表单提交分组 |
+| `value` | `string \| number \| boolean` | — | 原生 `value`，随表单提交的值 |
+
+### Events
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `update:modelValue` | `(value: boolean)` | 勾选状态变化 |
+| `change` | `(value: boolean, event: Event)` | 同上，附带原生事件 |
+| `focus` | `(event: FocusEvent)` | 获得焦点 |
+| `blur` | `(event: FocusEvent)` | 失去焦点 |
+
+### Slots
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `default` | — | 复选框文案（可放富内容）。为空时不渲染文字容器 |
+
+### 类型定义
+
+```ts
+export interface CheckboxProps {
+  modelValue?: boolean
+  indeterminate?: boolean
+  disabled?: boolean
+  name?: string
+  value?: string | number | boolean
+}
+```
+
+### 样式变量
+
+| 变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `--g3-checkbox-size` | `16px` | 勾选框边长 |
+| `--g3-radius-sm` | `4px` | 勾选框圆角 |
+| `--g3-color-primary` | `#18181b` | 选中态底色与边框 |
+| `--g3-bg-disabled` / `--g3-text-disabled` | `rgba(0,0,0,.04 / .25)` | 禁用态 |
+
+## 实现说明
+
+- 底层是原生 `<input type="checkbox">`，通过 `<label>` 包裹：因此键盘 Space 切换、点击文字、屏幕阅读器状态全部由浏览器负责，组件只负责视觉；
+- `indeterminate` 是 **DOM property**（不是 attribute），Vue 的绑定语法覆盖不到，组件内部在 `mounted` 与相关 prop 变化时手动写入 `input.indeterminate`；
+- 勾选态优先：`modelValue = true` 时会强制把 DOM 的 `indeterminate` 置为 `false`，避免「已勾选却显示减号」；
+- 原生 input 视觉上隐藏（`opacity: 0` + 1px 尺寸），但**保留在布局中**，这样 `:focus-visible` 的焦点环可以作用在自绘的方框上，键盘用户依然有焦点提示。
diff --git a/code/g3soft-libs/docs/content/ui/3.form/form.md b/code/g3soft-libs/docs/content/ui/3.form/form.md
new file mode 100644
index 00000000..00677cb0
--- /dev/null
+++ b/code/g3soft-libs/docs/content/ui/3.form/form.md
@@ -0,0 +1,187 @@
+---
+title: Form 表单
+description: 收集、校验与提交一组字段，支持横向 / 纵向布局与多列网格
+---
+
+# Form 表单
+
+`G3Form` 负责「数据、校验、提交」三件事，`G3FormItem` 负责「标签、控件、错误提示」。字段值统一放在 `model` 对象里，FormItem 通过 `name` 与它对应。
+
+## 何时使用
+
+- 需要多个字段一起校验、一起提交时；
+- 需要统一的标签宽度、错误提示位置与布局时；
+- 只有一两个独立输入、互不相关时，可以不用 Form，直接写 `v-model`。
+
+## 基础用法
+
+`model` 必须是响应式对象；`rules` 的键是字段名。
+
+:::demo{name="form/basic"}
+:::
+
+## 校验规则
+
+一条规则可以同时带多个约束，错误消息会全部收集；`message` 也支持传函数做动态文案。
+
+:::demo{name="form/rules"}
+:::
+
+| 规则字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `required` | `boolean` | 必填。空值（`undefined` / `null` / `''`）时直接报错，其余约束不再执行 |
+| `type` | `'string' \| 'number' \| 'integer' \| 'email' \| 'url'` | 类型校验。`number` / `integer` 允许数字字符串（输入框的中间态） |
+| `pattern` | `RegExp` | 正则校验，值会被 `String()` 后匹配 |
+| `len` / `min` / `max` | `number` | 字符串取长度、数组取项数、数字取数值 |
+| `message` | `string \| () => string` | 覆盖默认文案；传函数则在每次校验时求值 |
+| `validator` | `(value, rule) => unknown` | 自定义校验：返回 `true`/`undefined`/`null` 通过；返回 `false` 用 `message`；返回非空字符串则作为错误消息；返回 Promise 则等待结果 |
+
+## 布局与标签
+
+`layout` 支持横向（label 在左）与纵向（label 在上）；横向时可配 `labelAlign` 与 `labelWidth`。
+
+:::demo{name="form/layout"}
+:::
+
+## 校验时机
+
+`validateTrigger` 决定何时校验：`change` 输入即校验（默认），`blur` 失焦才校验。两种情况都做了「首次为空不报错」的处理，避免打开表单就整片飘红。
+
+:::demo{name="form/validate-trigger"}
+:::
+
+## 提交、失败与重置
+
+- `submit`：全部字段通过后触发，参数是 `model` 的浅拷贝；
+- `submitFailed`：有字段未通过时触发，载荷含 `values` 与 `errorFields`；
+- `reset`：点击 `html-type="reset"` 的按钮触发，同时清空所有字段的错误与触碰标记；
+- 也可以在保存前手动 `formRef.validateAll()`。
+
+:::demo{name="form/submit"}
+:::
+
+## 多列网格
+
+`columns > 1` 时字段按网格排布，`FormItem` 用 `span` 跨列、`lineStart` 强制从下一行第一列开始。
+
+:::demo{name="form/grid"}
+:::
+
+## 分组
+
+`G3FormGroup` 在长表单里做分组，组内可以覆盖列数、布局与 label 宽度。
+
+:::demo{name="form/group"}
+:::
+
+## API
+
+### Props（Form）
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `model` | `Record<string, unknown>` | **必填** | 表单数据对象，字段值按 FormItem 的 `name` 读取 |
+| `rules` | `Record<string, FormRule[]>` | `{}` | 表单级规则；FormItem 自己的 `rules` 优先级更高 |
+| `layout` | `'horizontal' \| 'vertical'` | `'horizontal'` | 布局；未传时读 `componentDefaults.form.layout` |
+| `labelAlign` | `'left' \| 'right'` | `'right'` | 横向布局下 label 对齐 |
+| `labelWidth` | `string \| number` | — | 横向布局的 label 宽度（数字按 px） |
+| `columns` | `number` | `1` | 每行列数；> 1 时启用网格布局 |
+| `spanColumns` | `number` | `0` | 只影响 FormItem 的 `span` 计算，不改变 Form 自身布局（外部栅格场景） |
+| `maxWidth` | `string \| number` | — | 表单最大宽度（数字按 px） |
+| `requiredMark` | `boolean` | `true` | 是否显示必填红星 |
+| `validateTrigger` | `'change' \| 'blur'` | `'change'` | 校验时机 |
+| `gap` | `number \| { row?: number; col?: number }` | — | 表单项间距。数字表示行列同值；不传时用单列 16px / 网格 12px+16px 的内置默认 |
+
+### Props（FormItem）
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `name` | `string \| number` | **必填** | 字段名，对应 `model` 的键，也是注册到 Form 的键 |
+| `label` | `string` | `''` | 标签文本，也可用 `#label` 插槽 |
+| `rules` | `FormRule[]` | — | 单项规则；不传时回退到 Form 级同名规则 |
+| `required` | `boolean` | 由规则推导 | 是否显示必填星；显式传入可覆盖规则推导 |
+| `extra` | `string` | `''` | 辅助说明（控件下方）；有错误时被错误信息替代 |
+| `help` | `string` | `''` | 固定提示（无错误时显示） |
+| `labelAlign` | `'left' \| 'right'` | 继承 Form | 单项对齐覆盖 |
+| `labelWidth` | `string \| number` | 继承 Form | 单项 label 宽度覆盖 |
+| `span` | `number` | `1` | 网格布局下跨列数（自动限制在容器列数内） |
+| `lineStart` | `boolean` | `false` | 强制本项位于新行第一列 |
+| `validateStatus` | `'' \| 'error'` | `''` | 外部手动指定校验状态（优先于内部校验结果） |
+| `layout` | `'horizontal' \| 'vertical'` | 继承 Form | 独立使用（不在 Form 内）时的布局 |
+| `validateTrigger` | `'change' \| 'blur'` | 继承 Form | 独立使用时的校验时机 |
+
+### Props（FormGroup）
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `title` | `string` | `''` | 分组标题，也可用 `#title` 插槽 |
+| `columns` | `number` | `1` | 组内列数（覆盖外层 Form） |
+| `layout` | `'horizontal' \| 'vertical'` | — | 组内布局覆盖 |
+| `labelWidth` | `string \| number` | — | 组内 label 宽度覆盖 |
+| `gap` | `number \| { row?: number; col?: number }` | — | 组内间距覆盖 |
+
+### Events（Form）
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `submit` | `(values: Record<string, unknown>)` | 全部字段校验通过。由 `html-type="submit"` 或回车触发 |
+| `submitFailed` | `({ values, errorFields: Array<{ name, errors }> })` | 有字段未通过 |
+| `reset` | `()` | 点击 `html-type="reset"` 触发（同时清空校验态） |
+
+### Slots
+
+| 组件 | 插槽 | 说明 |
+| --- | --- | --- |
+| Form | `default` | 一组 `G3FormItem` / `G3FormGroup` |
+| FormItem | `default` | 控件本体 |
+| FormItem | `label` | 自定义标签内容 |
+| FormGroup | `default` | 组内字段 |
+| FormGroup | `title` | 自定义分组标题 |
+
+### Exposed（Form）
+
+| 名称 | 签名 | 说明 |
+| --- | --- | --- |
+| `validateAll` | `() => Promise<Array<{ name: string; errors: string[] }>>` | 立即校验全部已注册字段，返回出错字段（空数组表示通过） |
+
+### 类型定义
+
+```ts
+export type FormLayout = 'horizontal' | 'vertical'
+export type FormLabelAlign = 'left' | 'right'
+export type FormValidateTrigger = 'change' | 'blur'
+export type FormItemStatus = '' | 'error'
+export type FormGap = number | { row?: number; col?: number }
+
+export interface FormRule {
+  required?: boolean
+  type?: 'string' | 'number' | 'integer' | 'email' | 'url'
+  pattern?: RegExp
+  len?: number
+  min?: number
+  max?: number
+  message?: string | (() => string)
+  validator?: (value: unknown, rule: FormRule) => unknown
+}
+
+export interface FormFieldController {
+  validate: () => Promise<string[]>
+  clearValidation: () => void
+}
+```
+
+### 样式变量
+
+| 变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `--g3-form-label-width` | — | 未传 `labelWidth` 时的默认 label 宽度（不设则由内容决定） |
+| `--g3-color-danger` | `#ec4246` | 必填星与错误文案 |
+
+## 实现说明
+
+- **字段注册**：FormItem 挂载时把自己的 `validate` / `clearValidation` 注册进 Form 的 `Map`，卸载时注销；`validateAll` 就是并发调用这张表里的所有校验器；
+- **provide 用 computed 包装**：父级可能整体替换 `model` / `rules` 对象（切换编辑目标、克隆草稿），直接传引用会让 FormItem 读到过期对象；
+- **不误报的三条规则**：① 非 `immediate` 的 `watch`，初始值不校验；② 未触碰且值为空时跳过；③ `model` 对象被整体替换、或布尔值由 `true` 变 `false`（滑块验证码归零这类主动重置）时，清除校验态而不报错；
+- **blur 校验延后一拍**（`setTimeout`）：让浮层类控件（Select / DatePicker 的面板）的点击先完成再取值，否则会「选中了却报未填」；
+- 校验文案不在组件里硬编码，全部来自语言包（`zhCN.form.*`），可用 `ConfigProvider.locale` 整体替换；
+- 提交事件回传的是 `{ ...model }` 浅拷贝，避免业务侧直接改到表单内部对象。
diff --git a/code/g3soft-libs/docs/content/ui/3.form/input.md b/code/g3soft-libs/docs/content/ui/3.form/input.md
new file mode 100644
index 00000000..d763dd15
--- /dev/null
+++ b/code/g3soft-libs/docs/content/ui/3.form/input.md
@@ -0,0 +1,167 @@
+---
+title: Input 输入框
+description: 单行 / 密码 / 数字 / 多行四种模式，支持清除、前后缀与字数统计
+---
+
+# Input 输入框
+
+`Input` 是受控输入控件：值通过 `v-model` 双向绑定，`type` 决定它是单行、密码、数字还是多行文本。
+
+## 何时使用
+
+- 录入短文本（名称、标题、编码）用默认模式；
+- 密码输入用 `type="password"`（自带显示/隐藏切换）；
+- 只允许数字的字段用 `type="number"`（限制字符并转换类型）；
+- 描述、备注等多行文本用 `type="textarea"`；
+- 需要从固定选项里选值，请用 [Select](/ui/form/select)。
+
+## 基础用法
+
+:::demo{name="input/basic"}
+:::
+
+`v-model` 的值类型是 `string`；`type="number"` 时提交值为 `number`（空值保留为 `''`）。
+
+## 密码输入
+
+`type="password"` 会在右侧渲染一个显示/隐藏按钮，按钮带 `aria-pressed` 与无障碍标签。
+
+:::demo{name="input/password"}
+:::
+
+密码框建议同时设置 `autocomplete="current-password"`，让浏览器密码管理器正确识别。
+
+## 数字输入
+
+`type="number"` 做了三件事：过滤非数字字符、保留输入中间态（`12.` 不会被打断）、**失焦或回车时把字符串提交为 `Number`**。
+
+:::demo{name="input/number"}
+:::
+
+## 多行文本
+
+`rows` 是初始行数；`show-count` 显示字数统计；右下角有拖拽手柄，可以拖拽或聚焦后用 `↑ / ↓ / Home` 调整高度（聚焦后是 `role="slider"`）。
+
+:::demo{name="input/textarea"}
+:::
+
+## 可清除
+
+`allowClear` 时，有值且 hover / 聚焦会出现清除按钮；点击清空值并触发 `clear` 事件。
+
+:::demo{name="input/clearable"}
+:::
+
+## 前后缀插槽
+
+`#prefix` / `#suffix` 放图标或单位，图标尺寸跟随字号（`1em`）。
+
+:::demo{name="input/slots"}
+:::
+
+## 校验状态
+
+`status` 让输入框表达校验结果：`error` 红边、`warning` 黄边。配合 `G3FormItem` 时通常由表单自动管理，无需手写。
+
+:::demo{name="input/status"}
+:::
+
+## 实例方法
+
+通过 `ref` 调用 `focus(options)` / `select()` / `blur()`，用于「点击单元格进入编辑」这类交互：
+
+```ts
+const inputRef = ref<InstanceType<typeof G3Input> | null>(null)
+
+inputRef.value?.focus({ cursor: 'all' }) // 聚焦并全选
+inputRef.value?.focus({ preventScroll: true }) // 聚焦但不滚动页面
+```
+
+:::demo{name="input/methods"}
+:::
+
+## API
+
+### Props
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `modelValue` | `string \| number` | `''` | 双向绑定的值 |
+| `type` | `'default' \| 'password' \| 'number' \| 'textarea'` | `'default'` | 输入模式 |
+| `disabled` | `boolean` | `false` | 禁用态 |
+| `readonly` | `boolean` | `false` | 只读态：可聚焦、可复制，但不可修改 |
+| `status` | `'' \| 'error' \| 'warning'` | `''` | 校验状态 |
+| `allowClear` | `boolean` | `false` | 有值时显示清除按钮（hover / 聚焦时出现），多行模式不支持 |
+| `showCount` | `boolean` | `false` | 显示字数统计（`maxlength` 存在时显示 `当前 / 上限`） |
+| `maxlength` | `string \| number` | — | 最大长度，透传给原生 `maxlength` |
+| `rows` | `string \| number` | `3` | 多行模式的初始行数（仅 `textarea` 生效） |
+| `placeholder` | `string` | — | 占位文案。声明为 prop 是为了让它落到内部 `<input>` 而不是外层容器 |
+| `autocomplete` | `string` | — | 浏览器自动填充语义，如 `username` / `current-password` / `off` |
+
+### Events
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `update:modelValue` | `(value: string \| number)` | 输入时触发。`number` 模式提交 `number`，清空时为 `''` |
+| `change` | `(value: string \| number, event: Event)` | 原生 `change`（失焦或回车后值变化）。`number` 模式在此时完成类型转换 |
+| `focus` | `(event: FocusEvent)` | 获得焦点 |
+| `blur` | `(event: FocusEvent)` | 失去焦点 |
+| `clear` | `()` | 点击清除按钮（此时 `update:modelValue` 先发出 `''`） |
+
+### Slots
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `prefix` | — | 输入框左侧内容（图标、单位），多行模式不渲染 |
+| `suffix` | — | 输入框右侧内容，多行模式不渲染 |
+
+### Exposed（通过 ref 调用）
+
+| 名称 | 签名 | 说明 |
+| --- | --- | --- |
+| `focus` | `(options?: { preventScroll?: boolean; cursor?: 'all' }) => void` | 聚焦；`cursor: 'all'` 聚焦后全选 |
+| `select` | `() => void` | 选中全部内容 |
+| `blur` | `() => void` | 失焦 |
+
+### 类型定义
+
+```ts
+export type InputType = 'default' | 'password' | 'number' | 'textarea'
+export type InputStatus = '' | 'error' | 'warning'
+
+export interface InputProps {
+  modelValue?: string | number
+  type?: InputType
+  disabled?: boolean
+  readonly?: boolean
+  status?: InputStatus
+  allowClear?: boolean
+  showCount?: boolean
+  maxlength?: string | number
+  rows?: string | number
+  placeholder?: string
+  autocomplete?: string
+}
+
+export interface InputFocusOptions {
+  preventScroll?: boolean
+  cursor?: 'all'
+}
+```
+
+### 样式变量
+
+| 变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `--g3-control-height` | `32px` | 输入框高度（单行） |
+| `--g3-input-resize-handle` | 右下角手柄 | 多行模式的拖拽手柄位置由组件内部处理 |
+| `--g3-color-primary` / `--g3-color-primary-ring` | `#18181b` / 主色 20% | 聚焦边框与聚焦环 |
+| `--g3-color-danger` / `--g3-color-warning` | `#ec4246` / `#e79a0d` | `error` / `warning` 边框 |
+
+## 实现说明
+
+- **数字模式的取舍**：输入过程保留字符串（否则用户打不出 `12.`），只在 `change` / 失焦时转为 `Number`，空串保持 `''`，避免 `Number('')` 变成 `0`；
+- 光标位置在数字过滤后会重新计算（`setSelectionRange`），因此在中间插入非法字符不会把光标弹到末尾；
+- 多行模式的高度拖拽用 Pointer Events + `requestAnimationFrame` 合并更新，拖拽期间改的是内联 `height`（从小高度往大拖不会跳变）；
+- `placeholder` 等原生属性声明为 prop 是刻意的：容器是 `<div>`，如果不声明，`placeholder` 会作为 fallthrough 属性挂到外层容器上，对真实输入框无效；
+- 聚焦样式用 `--g3-color-primary-ring` 画 2px 外环（而非 `outline`），这样在 `Space` / `Grid` 里不会因为 outline 被相邻元素裁掉。
diff --git a/code/g3soft-libs/docs/content/ui/3.form/radio.md b/code/g3soft-libs/docs/content/ui/3.form/radio.md
new file mode 100644
index 00000000..7dc4200d
--- /dev/null
+++ b/code/g3soft-libs/docs/content/ui/3.form/radio.md
@@ -0,0 +1,106 @@
+---
+title: Radio 单选框
+description: 与 RadioGroup 组合使用，在一组选项里选中一个
+---
+
+# Radio 单选框
+
+`G3Radio` 必须放在 `G3RadioGroup` 里才能互斥。组负责值、禁用与 `name`，单选项只声明自己的 `value` 和内容。
+
+## 何时使用
+
+- 选项少（2-5 个）且需要**一次看全**时，比 [Select](/ui/form/select) 更快；
+- 选项是互斥的、必须选一个时使用；可以不选时用 Select 更合适；
+- 选项超过 5 个、或需要展示更多信息时，用 Select；
+- 只是控制某个功能的开与关，用 [Switch](/ui/form/switch)。
+
+## 基础用法
+
+:::demo{name="radio/basic"}
+:::
+
+组会自动生成唯一的原生 `name`（`useId`），因此同页多组之间不会互相干扰，键盘方向键也能在组内来回切换。
+
+## 纵向排列与整组禁用
+
+组默认是水平换行的 `inline-flex`；纵向排列用外部 `style` 改 `flex-direction`，或给组包一层纵向容器。
+
+:::demo{name="radio/vertical"}
+:::
+
+## 卡片式选择
+
+默认插槽可以放任意内容，配合 `style` 就能做成卡片选择器（常见于套餐、模板选择）。
+
+:::demo{name="radio/cards"}
+:::
+
+## API
+
+### Props（Radio）
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `value` | `string \| number \| boolean` | **必填** | 选项值。与组 `modelValue` 做 `Object.is` 比较决定是否选中 |
+| `disabled` | `boolean` | `false` | 单独禁用该项（组禁用时以组为准） |
+
+### Props（RadioGroup）
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `modelValue` | `string \| number \| boolean` | — | 双向绑定的选中值 |
+| `disabled` | `boolean` | `false` | 禁用整组 |
+| `name` | `string` | 自动生成 | 原生 radio 组名，不传时用 `useId` 生成 |
+
+### Events（RadioGroup）
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `update:modelValue` | `(value: string \| number \| boolean)` | 选中项变化 |
+| `change` | `(value: string \| number \| boolean)` | 同上，便于只监听变化 |
+
+### Slots
+
+| 组件 | 插槽 | 说明 |
+| --- | --- | --- |
+| Radio | `default` | 选项文案，可放富内容 |
+| RadioGroup | `default` | 组内的 `G3Radio` 列表 |
+
+### 类型定义
+
+```ts
+export type RadioValue = string | number | boolean
+
+export interface RadioProps {
+  value: RadioValue
+  disabled?: boolean
+}
+
+export interface RadioGroupProps {
+  modelValue?: RadioValue
+  disabled?: boolean
+  name?: string
+}
+
+export interface RadioGroupContext {
+  name: ComputedRef<string | undefined>
+  modelValue: ComputedRef<RadioValue | undefined>
+  disabled: ComputedRef<boolean>
+  select: (value: RadioValue) => void
+}
+```
+
+### 样式变量
+
+| 变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `--g3-radio-size` | `16px` | 圆圈直径 |
+| `--g3-color-primary` | `#18181b` | 选中态边框与内点 |
+| `--g3-bg-disabled` / `--g3-text-disabled` | `rgba(0,0,0,.04 / .25)` | 禁用态 |
+
+## 实现说明
+
+- 底层同样是原生 `input[type=radio]`：组用 `<div>` 包裹、每项用 `<label>` 包裹，浏览器原生提供「组内互斥 + 方向键切换」；
+- 选中判断用 `Object.is`（而不是 `===`），这样 `NaN` 之类的值也能正确比较；
+- 组上下文通过 `provide` 下发：`{ name, modelValue, disabled, select }`，单选项目通过 `inject` 读取；**脱离组单独使用时**会退化为「永不选中」的原生 radio（不会报错，但也不会有选中态），因此务必成对使用；
+- 未显式传 `name` 时用 `useId` 生成组名，避免同页多个 radio 组因为浏览器按 `name` 分组而互相影响。
diff --git a/code/g3soft-libs/docs/content/ui/3.form/select.md b/code/g3soft-libs/docs/content/ui/3.form/select.md
new file mode 100644
index 00000000..dd1e56c2
--- /dev/null
+++ b/code/g3soft-libs/docs/content/ui/3.form/select.md
@@ -0,0 +1,159 @@
+---
+title: Select 选择器
+description: 下拉选择，支持筛选、多选、远程搜索、触底加载与自由输入
+---
+
+# Select 选择器
+
+`Select` 从一个列表里选值，是表单里最常被用到的控件之一。它把触发器做成了**输入框**：开启筛选后可直接键入过滤，键盘也能完成全部操作。
+
+## 何时使用
+
+- 选项较多（> 5 个）时；
+- 选项来自接口、需要分页或远程搜索时；
+- 需要多选，且选项数量不足以用 Checkbox 平铺时；
+- 选项很少（2-5 个）且需要一次看全时，用 [Radio](/ui/form/radio) / [Segmented](/ui/general/segmented) 更快。
+
+## 基础用法
+
+`options` 默认按 `{ label, value, disabled }` 取值。
+
+:::demo{name="select/basic"}
+:::
+
+## 字段名映射
+
+后端返回的字段名不是 `label` / `value` 时，用 `labelKey` / `valueKey` 映射，不必在业务侧做数据转换。
+
+:::demo{name="select/field-names"}
+:::
+
+## 多选
+
+`multiple` 时 `modelValue` 为数组，选中后下拉保持打开，选中项以顿号拼接显示。
+
+:::demo{name="select/multiple"}
+:::
+
+## 筛选
+
+`filterable` 默认就是开启的；不传时按 `label` / `value` 做大小写不敏感的包含匹配，也可以传 `filterOption` 自定义。
+
+:::demo{name="select/filterable"}
+:::
+
+## 远程搜索
+
+`remote` 模式不会做本地筛选，全部交给父层：输入触发 `search`，父层把结果写回 `options`；`loading` 时右侧显示加载图标而不是箭头/清除按钮。
+
+:::demo{name="select/remote"}
+:::
+
+## 触底加载更多
+
+列表滚到底部会持续触发 `loadMore`，配合 `loading` 去重；`#footer` 插槽可以放加载提示。
+
+:::demo{name="select/load-more"}
+:::
+
+## 自定义选项
+
+不传 `options` 时使用默认插槽，插槽透出 `{ select, close }`，适合做带描述、头像的富选项。
+
+:::demo{name="select/custom-option"}
+:::
+
+## 键盘操作
+
+| 按键 | 行为 |
+| --- | --- |
+| `↓` / `↑` | 打开下拉（若未打开）或移动高亮（跳过分隔项与禁用项） |
+| `Home` / `End` | 跳到第一个 / 最后一个可选项 |
+| `Enter` | 选中当前高亮项；若输入文本精确匹配某项 label，优先选中它 |
+| `Esc` | 关闭下拉并清空筛选词 |
+| `Tab` | 关闭下拉并把焦点交给下一个控件 |
+| 直接输入 | 筛选列表（`filterable` 为 true 时） |
+
+## API
+
+### Props
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `modelValue` | `string \| number \| boolean \| object \| null \| Array` | — | 双向绑定的值；`multiple` 时为数组 |
+| `options` | `Array<Record<string, unknown> \| string \| number>` | — | 选项数组。元素为对象时按 `labelKey` / `valueKey` / `disabled` 取值，为原始值时自身即 label 与 value |
+| `disabled` | `boolean` | `false` | 禁用态 |
+| `clearable` | `boolean` | `false` | 有值时显示清除按钮（聚焦时出现） |
+| `multiple` | `boolean` | `false` | 多选模式，`modelValue` 为数组 |
+| `filterable` | `boolean` | `true` | 是否开启筛选（关闭时输入框只读） |
+| `filterOption` | `(input: string, option: unknown) => boolean` | — | 自定义筛选函数，`option` 是**原始**选项对象 |
+| `remote` | `boolean` | `false` | 远程搜索模式：不做本地筛选，输入时触发 `search` |
+| `loading` | `boolean` | `false` | 加载中：右侧显示加载图标，并阻止触底重复触发 |
+| `notFoundText` | `string` | 语言包 | 无匹配项时的文案 |
+| `allowFreeInput` | `boolean` | `false` | 允许自由输入：不在列表里的文本也可以作为值提交 |
+| `labelKey` | `string` | `'label'` | 选项对象中作为显示文本的字段名 |
+| `valueKey` | `string` | `'value'` | 选项对象中作为值的字段名 |
+
+### Events
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `update:modelValue` | `(value: SelectValue \| SelectValue[])` | 选中 / 清除时触发；覆盖多选 |
+| `change` | `(value, option?)` | 同上，第二个参数是被选中的规范化选项（清除时为 `undefined`） |
+| `search` | `(query: string)` | `remote` 模式下输入时触发 |
+| `visibleChange` | `(open: boolean)` | 下拉展开 / 收起。远程型调用方可据此在展开时拉取首页数据 |
+| `loadMore` | `()` | 列表滚动触底（距底 24px 内），已加载中不重复触发 |
+
+### Slots
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `default` | `{ select: (value) => void; close: () => void }` | 自定义选项（不传 `options` 时生效） |
+| `footer` | `{ loading: boolean }` | 列表底部内容，如加载更多提示 |
+
+### Exposed
+
+| 名称 | 签名 | 说明 |
+| --- | --- | --- |
+| `openDropdown` | `() => void` | 展开下拉 |
+| `closeDropdown` | `() => void` | 收起下拉 |
+
+### 类型定义
+
+```ts
+export type SelectValue = string | number | boolean | object | null | undefined
+
+export interface SelectProps {
+  modelValue?: SelectValue | SelectValue[]
+  options?: Array<Record<string, unknown> | string | number>
+  disabled?: boolean
+  clearable?: boolean
+  multiple?: boolean
+  filterable?: boolean
+  filterOption?: (input: string, option: unknown) => boolean
+  remote?: boolean
+  loading?: boolean
+  notFoundText?: string
+  allowFreeInput?: boolean
+  labelKey?: string
+  valueKey?: string
+}
+```
+
+### 样式变量
+
+| 变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `--g3-select-dropdown-max-height` | `256px` | 下拉最大高度 |
+| `--g3-select-dropdown-max-width` | `360px` | 下拉宽度上限（触发框更宽时以触发框为准） |
+| `--g3-control-height` | `32px` | 触发器高度 |
+| `--g3-color-primary-ring` | 主色 20% | 聚焦环 |
+
+## 实现说明
+
+- **触发器就是输入框**：这样「键入筛选」与「键盘导航」共用一套焦点管理，不需要额外的隐藏 input；关闭下拉时会清空筛选词并回显选中项；
+- **自由输入的提交时机**：输入过程**不**写 `modelValue`（避免把半成品写进表单），只在失焦或关闭下拉时提交；非自由输入模式下，若文本精确匹配某选项 label 则选中该项，否则回退到上次选中值；
+- **焦点回流**：选中 / 清除后下拉内容会卸载，焦点会掉到 `body`；组件会把焦点主动交还输入框，并用 `suppressNextAutoOpen` 抑制这次「聚焦即展开」，否则下拉会立刻弹回来；
+- **点击外部关闭**用的浮层基座是 [Popover](/ui/overlay/popover)：Teleport 到配置的容器、滚动 / 尺寸变化时重算位置、Esc 关闭；
+- 下拉宽度取 `max(触发框宽, 内容宽)` 并由 `--g3-select-dropdown-max-width` 封顶，超出上限的选项文案折行而不是把下拉拉出屏幕；
+- 选项用 `v-memo` 缓存（只在「该选项或它是否是高亮项」变化时重渲染），长列表下键盘连续移动不会卡顿。
diff --git a/code/g3soft-libs/docs/content/ui/3.form/switch.md b/code/g3soft-libs/docs/content/ui/3.form/switch.md
new file mode 100644
index 00000000..e29a6a32
--- /dev/null
+++ b/code/g3soft-libs/docs/content/ui/3.form/switch.md
@@ -0,0 +1,97 @@
+---
+title: Switch 开关
+description: 用于切换单个状态的即时开关
+---
+
+# Switch 开关
+
+`Switch` 表示「开 / 关」两态，通常**立即生效**（不需要点保存）。
+
+## 何时使用
+
+- 设置项里即时生效的开关（启用通知、公开可见）；
+- 表格行内的状态切换；
+- 需要注意：`Switch` 不是复选框的替代品。多个选项之间互不排斥、需要一起提交时用 [Checkbox](/ui/form/checkbox)。
+
+## 基础用法
+
+`v-model` 绑定 `boolean`；`change` 回传新值与原生事件。
+
+:::demo{name="switch/basic"}
+:::
+
+## 禁用态
+
+:::demo{name="switch/disabled"}
+:::
+
+## 与表单一起使用
+
+放入 `G3FormItem` 时，label 与校验由表单负责，`Switch` 只提供值。
+
+:::demo{name="switch/in-form"}
+:::
+
+## 关于「异步切换」
+
+组件本身不做 loading/回滚，因为「乐观切换 + 失败回滚」的业务语义差异很大。推荐在 `change` 里显式处理：
+
+```ts
+async function onChange(next: boolean) {
+  const previous = !next
+  try {
+    await api.update(next)
+  } catch {
+    enabled.value = previous // 失败回滚
+    G3Message.error('保存失败')
+  }
+}
+```
+
+## API
+
+### Props
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `modelValue` | `boolean` | `false` | 双向绑定的开关状态 |
+| `disabled` | `boolean` | `false` | 禁用态 |
+
+### Events
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `update:modelValue` | `(value: boolean)` | 状态变化 |
+| `change` | `(value: boolean, event: MouseEvent)` | 同上，附带原生点击事件 |
+
+### Slots
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `default` | — | 开关旁的文案（可点击切换） |
+
+### 类型定义
+
+```ts
+export interface SwitchProps {
+  modelValue?: boolean
+  disabled?: boolean
+}
+```
+
+### 样式变量
+
+| 变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `--g3-switch-width` | `32px` | 轨道宽 |
+| `--g3-switch-height` | `18px` | 轨道高 |
+| `--g3-switch-thumb-size` | `14px` | 滑块直径 |
+| `--g3-switch-thumb-offset` | `2px` | 滑块内边距 |
+| `--g3-color-primary` | `#18181b` | 开启态轨道色 |
+
+## 实现说明
+
+- 没有原生的 `<input type="switch">`，因此用 `<button type="button" role="switch" aria-checked>` 承载语义：Enter / Space 由原生按钮自动转为 `click`；
+- `aria-checked` 会跟随 `modelValue` 更新，屏幕阅读器能播报「开 / 关」；
+- 滑块的位移由固定变量计算（`宽度 - 滑块 - 内边距×2`），因此改 `--g3-switch-*` 变量后滑块位置依然正确，不需要改代码；
+- 文字部分也在按钮内，因此点击文字同样可以切换（按钮整体是一个目标区域，触屏上更好点）。
diff --git a/code/g3soft-libs/docs/content/ui/4.overlay/.navigation.yml b/code/g3soft-libs/docs/content/ui/4.overlay/.navigation.yml
new file mode 100644
index 00000000..499e06be
--- /dev/null
+++ b/code/g3soft-libs/docs/content/ui/4.overlay/.navigation.yml
@@ -0,0 +1,2 @@
+title: 浮层与导航
+icon: i-lucide-layers
diff --git a/code/g3soft-libs/docs/content/ui/4.overlay/drawer.md b/code/g3soft-libs/docs/content/ui/4.overlay/drawer.md
new file mode 100644
index 00000000..179d6a03
--- /dev/null
+++ b/code/g3soft-libs/docs/content/ui/4.overlay/drawer.md
@@ -0,0 +1,114 @@
+---
+title: Drawer 抽屉
+description: 从屏幕边缘滑出的面板，支持四个方向与边缘拖拽调尺寸
+---
+
+# Drawer 抽屉
+
+`Drawer` 从屏幕边缘滑出，视觉重量比 [Modal](/ui/overlay/modal) 轻：它遮挡的是边缘而不是整个画面，用户仍能看到部分页面内容。
+
+## 何时使用
+
+- 长表单、筛选条件、详情信息：内容多但不需要完全接管屏幕时；
+- 需要与页面内容对照查看时（抽屉不会把页面完全遮住）；
+- 必须阻断用户操作、或需要强确认时，用 Modal。
+
+## 基础用法
+
+`v-model:open` 控制显隐；`cancel` 表示「被关闭」（遮罩 / Esc / 关闭按钮）。
+
+:::demo{name="drawer/basic"}
+:::
+
+## 四个方向
+
+`placement` 支持 `right`（默认）/ `left` / `top` / `bottom`；左右方向用 `width`，上下方向用 `height` 控制尺寸，缩放手柄也会跟着换方向。
+
+:::demo{name="drawer/placement"}
+:::
+
+## 自定义尺寸
+
+尺寸接受数字（px）或任意 CSS 长度（`'60%'`、`'48rem'`）；`resizable=false` 可以关掉边缘拖拽。
+
+:::demo{name="drawer/size"}
+:::
+
+## 底部动作与补充信息
+
+`#footer` 放底部动作区；`#extra` 在标题下方补充信息（如「已选 2 个条件」）。
+
+:::demo{name="drawer/footer"}
+:::
+
+## Modal 还是 Drawer？
+
+| | Modal | Drawer |
+| --- | --- | --- |
+| 遮挡范围 | 整个页面（居中/贴顶面板） | 一侧边缘 |
+| 适合内容 | 短表单、确认、需要强聚焦 | 长表单、筛选、详情、多步骤 |
+| 页面上下文 | 被遮罩挡住 | 仍可见（便于对照） |
+| 尺寸调整 | 四边缩放 + 全屏 | 单边拖拽 |
+
+## API
+
+### Props
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `open` | `boolean` | — | 受控打开状态；不传即非受控 |
+| `defaultOpen` | `boolean` | `false` | 非受控时的初始状态 |
+| `title` | `string` | `''` | 标题 |
+| `placement` | `'left' \| 'right' \| 'top' \| 'bottom'` | `'right'` | 滑出方向 |
+| `width` | `number \| string` | `378` | 宽度（`left` / `right` 生效） |
+| `height` | `number \| string` | `378` | 高度（`top` / `bottom` 生效） |
+| `mask` | `boolean` | `true` | 是否显示遮罩 |
+| `maskClosable` | `boolean` | `true` | 点击遮罩关闭 |
+| `keyboard` | `boolean` | `true` | Esc 关闭 |
+| `closable` | `boolean` | `true` | 显示右上角关闭按钮 |
+| `resizable` | `boolean` | `true` | 允许拖拽面板边缘调整尺寸 |
+| `popupContainer` | `PopupContainer` | ConfigProvider 配置 | 挂载容器，默认 `body` |
+
+### Events
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `update:open` | `(open: boolean)` | 打开状态变化 |
+| `cancel` | `()` | 遮罩 / Esc / 关闭按钮触发的关闭意图（内容区的操作按钮不会触发它） |
+| `closed` | `()` | 退场动画结束（滚动已解锁、焦点已归还） |
+
+### Slots
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `default` | — | 内容区（可滚动） |
+| `extra` | — | 标题下方的补充信息 |
+| `footer` | — | 底部动作区 |
+
+### 类型定义
+
+```ts
+export type DrawerPlacement = 'left' | 'right' | 'top' | 'bottom'
+
+export interface DrawerProps {
+  open?: boolean
+  defaultOpen?: boolean
+  title?: string
+  placement?: DrawerPlacement
+  width?: number | string
+  height?: number | string
+  mask?: boolean
+  maskClosable?: boolean
+  keyboard?: boolean
+  closable?: boolean
+  resizable?: boolean
+  popupContainer?: PopupContainer
+}
+```
+
+## 实现说明
+
+- 面板贴边、容器 `pointer-events: none`，只有面板自身可交互——这样「抽屉打开时页面其他区域仍可点击」，符合抽屉"不接管屏幕"的定位；
+- 滑入/滑出用 `transform: translateX/Y(±100%)`，只过渡 `transform`，因此不会有布局抖动；
+- 缩放手柄只改一个轴（左右改宽、上下改高），并按视口上限夹取；关闭后尺寸复位，下次打开不继承；
+- 焦点与滚动处理与 Modal 共用同一套工具（焦点陷阱、滚动锁引用计数、退场后再归还焦点）。
diff --git a/code/g3soft-libs/docs/content/ui/4.overlay/dropdown.md b/code/g3soft-libs/docs/content/ui/4.overlay/dropdown.md
new file mode 100644
index 00000000..866948e9
--- /dev/null
+++ b/code/g3soft-libs/docs/content/ui/4.overlay/dropdown.md
@@ -0,0 +1,158 @@
+---
+title: Dropdown 下拉菜单
+description: 点击 / 悬停 / 右键触发的操作列表，支持子菜单与键盘导航
+---
+
+# Dropdown 下拉菜单
+
+`Dropdown` 把一组操作收进一个菜单，用于**行内操作**（编辑/复制/删除）、**账号菜单**与**右键菜单**。
+
+## 何时使用
+
+- 操作多于 2 个、或含危险操作需要分组时，收进菜单比并排按钮更清晰；
+- 表格行、树节点、卡片上承载右侧的「更多操作」；
+- 右键上下文菜单（`trigger="contextmenu"`）；
+- 只有一个操作时不要用菜单，直接放按钮。
+
+## 数据源写法
+
+`items` 是最常用的写法，点击后通过 `click` 事件回传 `{ key, item }`。
+
+:::demo{name="dropdown/basic"}
+:::
+
+## 声明式写法
+
+也可以把 `G3DropdownItem` 写在插槽里：它不渲染任何 DOM，只作为数据载体被 `Dropdown` 收集，因此键盘导航、高亮、子菜单这些能力与 `items` 写法完全一致。使用声明式写法时**建议用 `#trigger` 显式指定触发器**，避免触发器跟菜单项混在默认插槽里。
+
+:::demo{name="dropdown/declarative"}
+:::
+
+## 触发方式
+
+:::demo{name="dropdown/trigger"}
+:::
+
+## 菜单项类型
+
+:::demo{name="dropdown/item-types"}
+:::
+
+| 项配置 | 说明 |
+| --- | --- |
+| `{ key, label }` | 普通项，点击回传 `key` |
+| `{ icon }` | 前置图标（组件或 VNode） |
+| `{ shortcut }` | 右侧快捷键提示文字（仅展示，不绑定按键） |
+| `{ disabled }` | 禁用项：不可点、键盘导航跳过 |
+| `{ danger }` | 危险项：红色文字 |
+| `{ divider: true }` | 分隔线 |
+| `{ type: 'label', label }` | 分组标签 |
+| `{ children: [...] }` | 子菜单，hover 展开（`right-start` 弹出） |
+| `{ onClick: (item) => void }` | 项自带回调，先于全局 `click` 事件执行 |
+
+## 富头部与自定义菜单
+
+`#header` 用于账号卡片之类的头部（不参与键盘导航）；`#menu` 是完全自定义菜单结构的逃生舱。
+
+:::demo{name="dropdown/header-slot"}
+:::
+
+## 键盘操作
+
+菜单打开后焦点会进入菜单容器，因此可以直接用键盘：
+
+| 按键 | 行为 |
+| --- | --- |
+| `↑` / `↓` | 移动高亮（跳过分隔线、分组标签与禁用项，循环） |
+| `Home` / `End` | 跳到首 / 末项 |
+| `Enter` | 选中高亮项并关闭菜单（有子菜单的父项只高亮，不选中） |
+| `Esc` | 关闭菜单（由 Popover 处理） |
+
+:::demo{name="dropdown/keyboard"}
+:::
+
+## API
+
+### Props
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `items` | `DropdownItemData[]` | — | 菜单项数组；不传时从默认插槽收集 `G3DropdownItem`，否则回退到 `#menu` |
+| `open` | `boolean` | — | 受控打开状态；不传即非受控 |
+| `defaultOpen` | `boolean` | `false` | 非受控时的初始状态 |
+| `trigger` | `'click' \| 'hover' \| 'contextmenu'` | `'click'` | 触发方式 |
+| `placement` | `Placement` | `'bottom-start'` | 菜单方位 |
+| `disabled` | `boolean` | `false` | 禁用 |
+| `mouseEnterDelay` | `number` | `100` | hover 打开延迟（ms） |
+| `mouseLeaveDelay` | `number` | `200` | hover 关闭延迟（ms）。有子菜单时适当调大 |
+| `offset` | `number` | `4` | 与触发器的间距（px） |
+| `unwrapped` | `boolean` | `true` | 零包裹模式，触发器不额外包 `<span>` |
+
+### Events
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `click` | `({ key, item })` | 选中某个菜单项（不含分隔线 / 分组标签） |
+| `update:open` | `(open: boolean)` | 打开状态变化 |
+| `openChange` | `(open: boolean)` | 同上，语义别名 |
+
+### Slots
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `default` | — | 触发器（未传 `#trigger` 时）；或一组 `G3DropdownItem` |
+| `trigger` | — | 显式指定触发器（推荐） |
+| `header` | — | 菜单顶部富内容（不参与键盘导航） |
+| `menu` | `{ close: () => void }` | 完全自定义菜单结构（无 `items` 与 `G3DropdownItem` 时生效） |
+
+### Props（G3DropdownItem）
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `itemKey` | `string \| number` | — | 标识，点击时回传 |
+| `label` | `string` | `''` | 菜单文本 |
+| `icon` | `Component` | — | 前置图标 |
+| `danger` | `boolean` | `false` | 危险项 |
+| `disabled` | `boolean` | `false` | 禁用项 |
+| `divider` | `boolean` | `false` | 渲染为分隔线（其余属性忽略） |
+| `onClick` | `(item) => void` | — | 项自带回调 |
+
+### 类型定义
+
+```ts
+export interface DropdownItemData {
+  key?: string | number
+  label?: string
+  icon?: Component | VNode
+  danger?: boolean
+  disabled?: boolean
+  shortcut?: string
+  divider?: boolean
+  type?: 'label'
+  children?: DropdownItemData[]
+  onClick?: (item: DropdownItemData) => void
+}
+
+export interface DropdownClickPayload {
+  key?: string | number
+  item: DropdownItemData
+}
+```
+
+### 样式变量
+
+| 变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `--g3-dropdown-min-width` | `180px` | 菜单最小宽度 |
+| `--g3-dropdown-max-height` | `256px` | 菜单最大高度（超出滚动） |
+| `--g3-dropdown-item-padding-y` / `-x` | `5px` / `8px` | 菜单项内边距 |
+| `--g3-dropdown-item-radius` | `4px` | 菜单项圆角 |
+| `--g3-dropdown-divider-margin` | `4px 0` | 分隔线外边距 |
+
+## 实现说明
+
+- **三种数据源统一成一份 `items` 数组**：声明式的 `G3DropdownItem` 由 Dropdown 在渲染时收集（读取 vnode.props），随后与 `items` 走完全相同的渲染与键盘逻辑，因此不会出现「声明式写法少了某个能力」的问题；
+- 菜单容器是可聚焦的（`tabindex="-1"`），打开后主动 `focus()`，键盘事件因此能被菜单自身接收，不需要全局监听；
+- 子菜单是**嵌套的 Popover**（`trigger="hover"`、`placement="right-start"`），递归渲染 `items`；子菜单内部 `interactive=false`，不参与主菜单的高亮联动；
+- 打开时把 z-index 打到 `popup` 档，关闭回收；右键触发时浮层对齐鼠标位置；
+- 菜单项高亮用 `activeIndex` 单值驱动，鼠标移入与键盘移动共用它，因此「键盘移动后鼠标移入」不会出现双高亮。
diff --git a/code/g3soft-libs/docs/content/ui/4.overlay/modal.md b/code/g3soft-libs/docs/content/ui/4.overlay/modal.md
new file mode 100644
index 00000000..d6a74eba
--- /dev/null
+++ b/code/g3soft-libs/docs/content/ui/4.overlay/modal.md
@@ -0,0 +1,183 @@
+---
+title: Modal 对话框
+description: 模态窗口，支持拖动、缩放、全屏与命令式确认框
+---
+
+# Modal 对话框
+
+`Modal` 在当前页面上方打开一个模态窗口，用户必须先处理它才能继续。
+
+## 何时使用
+
+- 需要用户**聚焦处理**一件事：填写表单、确认危险操作、查看详情；
+- 需要打断当前流程、且不该被忽略时（用 `maskClosable=false`、`keyboard=false`、`closable=false` 收紧关闭入口）；
+- 只是提示结果、不需要用户操作时，用 [Message](/ui/feedback/message) 更轻；
+- 内容很长、或需要保留页面上下文时，可以考虑 [Drawer](/ui/overlay/drawer)。
+
+## 基础用法
+
+`v-model:open` 控制显隐。三个事件区分关闭来源：`confirm`（底部确认按钮）、`cancel`（取消按钮 / 遮罩 / Esc / 右上角关闭）、`closed`（退场动画结束）。
+
+:::demo{name="modal/basic"}
+:::
+
+## 拖动、缩放与全屏
+
+默认允许拖动标题栏移动面板、拖拽四边缩放、右上角切换全屏。三者互相协调：进入全屏会复位拖拽位置并禁用缩放手柄。
+
+:::demo{name="modal/resize"}
+:::
+
+## 居中显示
+
+面板默认贴顶（`align-items: flex-start`）——这样长内容不会把标题栏顶出视口。确认类、短表单可以开 `centered` 垂直居中。
+
+:::demo{name="modal/resize"}
+:::
+
+## 控制关闭入口
+
+`maskClosable` / `keyboard` / `closable` / `footer` 分别控制遮罩点击、Esc、右上角关闭按钮与底部按钮区。
+
+:::demo{name="modal/mask"}
+:::
+
+## 表单弹窗与异步确认
+
+`confirmLoading` 期间**阻止一切关闭**（含遮罩、Esc、取消按钮），避免异步提交被打断；底部按钮自动进入加载态。
+
+:::demo{name="modal/form"}
+:::
+
+## 命令式确认框
+
+```ts
+const handle = G3Modal.confirm({
+  title: '确定删除？',
+  content: '删除后不可恢复',
+  confirmText: '删除',
+  confirmButtonProps: { danger: true },
+  onConfirm: async () => {
+    await api.remove() // 返回 Promise 时按钮 loading
+  },
+  onCancel: () => {},
+})
+
+handle.destroy() // 立即关闭并卸载（不等退场动画）
+```
+
+:::demo{name="modal/confirm"}
+:::
+
+**`onConfirm` 的 Promise 语义**：resolve → 关闭；reject → 保持打开、解除 loading，错误由调用方提示。
+
+**`onCancel` 的触发范围**：只有点击「取消」按钮才会调用 `onCancel`；点遮罩空白、Esc、右上角关闭按钮都是**静默关闭**（只关窗，不跑取消逻辑），避免用户随手点空白就触发取消副作用。
+
+:::demo{name="modal/confirm-async"}
+:::
+
+## 自定义底部与头部
+
+`#footer` 完全接管底部；`#header-extra` 放标题右侧的额外动作。
+
+:::demo{name="modal/footer-slot"}
+:::
+
+## API
+
+### Props（Modal）
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `open` | `boolean` | — | 受控打开状态；不传即非受控 |
+| `defaultOpen` | `boolean` | `false` | 非受控时的初始状态 |
+| `title` | `string` | `''` | 标题 |
+| `width` | `number \| string` | `520` | 面板宽度。数字按 px，`'60%'` 之类的字符串原样使用 |
+| `centered` | `boolean` | `false` | 垂直居中（默认贴顶，长内容不会把标题顶出视口） |
+| `mask` | `boolean` | `true` | 是否显示遮罩 |
+| `maskClosable` | `boolean` | `true` | 点击遮罩空白关闭 |
+| `keyboard` | `boolean` | `true` | Esc 关闭 |
+| `closable` | `boolean` | `true` | 显示右上角关闭按钮 |
+| `fullscreen` | `boolean` | `true` | 显示右上角全屏切换按钮 |
+| `resizable` | `boolean` | `true` | 允许拖拽四边缩放宽高 |
+| `footer` | `boolean` | `true` | 显示底部按钮区（取消 + 确认） |
+| `confirmText` | `string` | 语言包 `common.confirm` | 确认按钮文字 |
+| `cancelText` | `string` | 语言包 `common.cancel` | 取消按钮文字 |
+| `confirmLoading` | `boolean` | `false` | 确认中：按钮 loading，并**阻止一切关闭操作** |
+| `popupContainer` | `PopupContainer` | ConfigProvider 配置 | 挂载容器，默认 `body` |
+
+### Events（Modal）
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `update:open` | `(open: boolean)` | 打开状态变化 |
+| `confirm` | `()` | 点击底部确认按钮（不自动关闭，由你决定何时关） |
+| `cancel` | `()` | 取消按钮 / 遮罩 / Esc / 右上角关闭被触发 |
+| `closed` | `()` | 退场动画结束、DOM 已销毁（此时滚动锁已释放、焦点已归还） |
+
+### Slots（Modal）
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `default` | — | 正文 |
+| `header-extra` | — | 标题右侧的自定义动作（在全屏/关闭按钮之前） |
+| `footer` | — | 自定义底部；不传时渲染「取消 + 确认」 |
+
+### G3Modal.confirm 参数
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `title` | `string` | `''` | 标题 |
+| `content` | `string` | `''` | 正文纯文本 |
+| `confirmText` | `string` | 语言包 | 确认按钮文字 |
+| `cancelText` | `string` | 语言包 | 取消按钮文字 |
+| `confirmButtonProps` | `Partial<ButtonProps> & { danger?: boolean }` | `{}` | 透传给确认按钮；`danger: true` 等价于 `type: 'danger'` |
+| `onConfirm` | `() => void \| Promise<unknown>` | — | 确认回调，返回 Promise 时按钮 loading |
+| `onCancel` | `() => void` | — | 取消回调（**仅**点击取消按钮触发） |
+
+**返回值**：`{ destroy: () => void }`。
+
+### 类型定义
+
+```ts
+export interface ModalProps {
+  open?: boolean
+  defaultOpen?: boolean
+  title?: string
+  width?: number | string
+  centered?: boolean
+  mask?: boolean
+  maskClosable?: boolean
+  keyboard?: boolean
+  closable?: boolean
+  fullscreen?: boolean
+  resizable?: boolean
+  footer?: boolean
+  confirmText?: string
+  cancelText?: string
+  confirmLoading?: boolean
+  popupContainer?: PopupContainer
+}
+
+export interface ModalConfirmOptions {
+  title?: string
+  content?: string
+  confirmText?: string
+  cancelText?: string
+  confirmButtonProps?: Partial<ButtonProps> & { danger?: boolean }
+  onConfirm?: () => void | Promise<unknown>
+  onCancel?: () => void
+}
+
+export interface ModalConfirmHandle {
+  destroy: () => void
+}
+```
+
+## 实现说明
+
+- **遮罩点击判定**：只响应「点击事件的目标就是外层容器」且「mousedown 不在面板内」的情况。后者是为了防拖选文本：在输入框里按下鼠标、拖到遮罩上松开时，`click.target` 会回溯成共同的祖先容器，如果只看 click 就会误判成「点了遮罩要关闭」；
+- **焦点与滚动**：打开时记录当前焦点、锁 body 滚动、把焦点移进面板，并用 Tab 循环把焦点约束在面板内；关闭时**等退场动画结束**才解锁滚动、复位尺寸、把焦点还给触发元素——否则动画还在播的时候背景就能滚动、焦点提前跳走，屏幕阅读器会跟丢；
+- **滚动锁是引用计数**：Modal 里再开 Drawer、或弹窗里开下拉，不会互相提前解锁；
+- **命令式挂载**：`G3Modal.confirm()` 自建容器挂到 `body`，`open` 初始即为 `true`，因此内部对 `isOpen` 用了 `immediate: true` 的 watch、并给 `Transition` 加了 `appear`，让「挂载」与「受控打开」走同一段初始化逻辑，退场动画结束后再卸载容器；
+- **层级**：打开时从 z-index 注册表取 `modal` 档，闭包回收；浮层类（下拉、日期面板）取 `popup` 档，所以弹窗里的浮层一定盖在弹窗上。
diff --git a/code/g3soft-libs/docs/content/ui/4.overlay/popover.md b/code/g3soft-libs/docs/content/ui/4.overlay/popover.md
new file mode 100644
index 00000000..c5188530
--- /dev/null
+++ b/code/g3soft-libs/docs/content/ui/4.overlay/popover.md
@@ -0,0 +1,123 @@
+---
+title: Popover 气泡卡片
+description: 浮层基座：12 方位定位、自动翻转、外部点击与 Esc 关闭
+---
+
+# Popover 气泡卡片
+
+`Popover` 是**所有浮层的基础**：Tooltip、Dropdown、Select、DatePicker 都建立在它之上。它负责定位、Teleport、关闭时机与滚动跟随，你只需要提供触发器和内容。
+
+## 何时使用
+
+- 需要在触发器旁展示一段内容（说明、小表单、卡片）时；
+- 需要容器级别的自定义浮层时。更具体的场景请直接用上层封装：[Tooltip](/ui/overlay/tooltip)、[Dropdown](/ui/overlay/dropdown)、[Select](/ui/form/select)。
+
+## 基础用法
+
+`#trigger` 是触发器，`#content` 是浮层内容；默认 click 触发、显示箭头。
+
+:::demo{name="popover/basic"}
+:::
+
+## 方位
+
+`placement` 支持 12 个方位：`top` / `bottom` / `left` / `right` 各自带 `-start` / `-end` 对齐。空间不足时**自动翻转到对面**，再不够会沿视口边缘收缩（shift），始终保持 8px 安全边距。
+
+:::demo{name="popover/placement"}
+:::
+
+## 触发方式
+
+| `trigger` | 行为 |
+| --- | --- |
+| `click` | 点击触发器切换（默认） |
+| `hover` | 移入打开（`mouseEnterDelay`）、移出关闭（`mouseLeaveDelay`），移入浮层不会关闭 |
+| `focus` | 聚焦打开，焦点移出关闭（焦点落在浮层内不关闭） |
+| `contextmenu` | 右键时在**鼠标位置**打开，越界自动回退 |
+| `manual` | 组件不接管开关，完全由 `open` 控制 |
+
+:::demo{name="popover/trigger"}
+:::
+
+## 受控用法
+
+传 `open` 即为受控：所有开关意图都会通过 `update:open` / `openChange` 抛出，你可以在里面做权限校验、埋点，或选择不关闭。
+
+:::demo{name="popover/controlled"}
+:::
+
+## 箭头与宽度
+
+`arrow=false` 去掉尖角（菜单类浮层常用）；`followTriggerWidth` 让浮层宽度以触发器宽度为下限（表单控件常用）。
+
+:::demo{name="popover/arrow-width"}
+:::
+
+## API
+
+### Props
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `open` | `boolean` | — | 受控打开状态；不传即非受控 |
+| `defaultOpen` | `boolean` | `false` | 非受控时的初始状态 |
+| `trigger` | `'click' \| 'hover' \| 'focus' \| 'contextmenu' \| 'manual'` | `'click'` | 触发方式 |
+| `placement` | `'top' \| 'top-start' \| … \| 'right-end'` | `'top'` | 期望方位（12 种），越界自动翻转 + 收缩 |
+| `offset` | `number` | `12` | 与触发器的间距（px） |
+| `arrow` | `boolean` | `true` | 是否显示箭头 |
+| `disabled` | `boolean` | `false` | 禁用：不响应触发（受控 `open` 仍可强制打开） |
+| `mouseEnterDelay` | `number` | `100` | hover 打开延迟（ms） |
+| `mouseLeaveDelay` | `number` | `100` | hover 关闭延迟（ms） |
+| `contentClass` | `string` | `''` | 透传到内容盒的 class，供派生组件定制内容样式 |
+| `followTriggerWidth` | `boolean` | `false` | 浮层宽度以触发器宽度为下限 |
+| `unwrapped` | `boolean` | `false` | 零包裹模式：把事件注入触发器单个根节点，不再包一层 `<span>` |
+| `popupContainer` | `string \| HTMLElement \| (() => …)` | ConfigProvider 配置 | 浮层挂载容器，默认 `body` |
+
+### Events
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `update:open` | `(open: boolean)` | 打开状态变化（受控与非受控都会触发） |
+| `openChange` | `(open: boolean)` | 同上，语义别名 |
+
+### Slots
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `trigger` | — | 触发器内容。`unwrapped` 时**要求单根元素** |
+| `content` | — | 浮层内容 |
+
+### 类型定义
+
+```ts
+export type PopoverTrigger = 'click' | 'hover' | 'focus' | 'contextmenu' | 'manual'
+export type Placement =
+  | 'top' | 'top-start' | 'top-end'
+  | 'bottom' | 'bottom-start' | 'bottom-end'
+  | 'left' | 'left-start' | 'left-end'
+  | 'right' | 'right-start' | 'right-end'
+
+export interface PopoverProps {
+  open?: boolean
+  defaultOpen?: boolean
+  trigger?: PopoverTrigger
+  placement?: Placement
+  offset?: number
+  arrow?: boolean
+  disabled?: boolean
+  mouseEnterDelay?: number
+  mouseLeaveDelay?: number
+  contentClass?: string
+  followTriggerWidth?: boolean
+  unwrapped?: boolean
+  popupContainer?: PopupContainer
+}
+```
+
+## 实现说明
+
+- **定位**：纯函数 `computePosition` 计算落点（先按方位摆放 → 主轴溢出则翻转 → 最后 clamp 回视口），浮层用 `position: fixed` + `top/left`，因此**不会**受父级 `overflow: hidden` 影响（配合 Teleport）；
+- **跟随**：打开期间监听捕获阶段的 `scroll`（覆盖内部滚动容器）、`resize`，并用 `ResizeObserver` 观察触发器与浮层尺寸，变化时重算（用 rAF 合并）；
+- **层级**：打开时从 z-index 注册表取一个 `popup` 档的值，关闭时回收（见 `z-index` 分层设计），所以弹窗里的下拉也能正确盖在弹窗之上；
+- `unwrapped` 模式的两个坑（已在实现里处理）：① `#trigger` 里再嵌 `<slot />` 会产出多层 Fragment，需要循环解包到真实元素；② 必须用渲染函数把注入了事件的 vnode 原样渲染，`<component :is="vnode">` 会丢掉事件监听与指令；
+- 进出场只过渡 `opacity` / `transform`，**不**过渡 `top/left`（否则打开瞬间会从屏幕左上角滑过来）。
diff --git a/code/g3soft-libs/docs/content/ui/4.overlay/tooltip.md b/code/g3soft-libs/docs/content/ui/4.overlay/tooltip.md
new file mode 100644
index 00000000..d49e90d7
--- /dev/null
+++ b/code/g3soft-libs/docs/content/ui/4.overlay/tooltip.md
@@ -0,0 +1,105 @@
+---
+title: Tooltip 文字提示
+description: hover 或聚焦时显示的简短说明
+---
+
+# Tooltip 文字提示
+
+`Tooltip` 用于解释**图标按钮、缩写、状态**等含义，内容应当是简短的一句说明。
+
+## 何时使用
+
+- 只有图标的按钮、被截断的文字、专业缩写需要解释时；
+- 需要展示较长的说明、表单或操作列表时，请用 [Popover](/ui/overlay/popover)；
+- 关键信息不要只放在 Tooltip 里：触屏设备没有 hover，键盘用户也需要能读到。
+
+## 基础用法
+
+`content` 传纯文本；默认在触发器上方显示。
+
+:::demo{name="tooltip/basic"}
+:::
+
+## 方位
+
+`placement` 支持 12 个方位，空间不足会自动翻转。
+
+:::demo{name="tooltip/placement"}
+:::
+
+## 富内容
+
+`#content` 插槽可以放多行说明、快捷键等富内容。
+
+:::demo{name="tooltip/rich"}
+:::
+
+## 受控与禁用
+
+`disabled` 时不响应 hover；传 `open` 则完全受控（适合「首次进入引导」这类场景）。
+
+:::demo{name="tooltip/disabled"}
+:::
+
+## 注意事项
+
+- Tooltip 内部是 **hover 触发**，因此触发器必须是可悬停元素（按钮、图标、文本）；
+- 触发器为禁用按钮时，原生 `disabled` 元素**不会派发鼠标事件**。需要给禁用按钮加提示时，用外层 `<span>` 包一层：
+
+```vue
+<G3Tooltip content="没有权限">
+  <span>
+    <G3Button disabled>删除</G3Button>
+  </span>
+</G3Tooltip>
+```
+
+## API
+
+### Props
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `content` | `string` | `''` | 提示文本；有 `#content` 插槽时插槽优先 |
+| `open` | `boolean` | — | 受控打开状态；不传即非受控（hover 控制） |
+| `defaultOpen` | `boolean` | `false` | 非受控时的初始状态 |
+| `placement` | `Placement` | `'top'` | 方位（12 种），越界自动翻转 |
+| `arrow` | `boolean` | `true` | 是否显示箭头 |
+| `mouseEnterDelay` | `number` | `100` | 移入后延迟显示（ms） |
+| `mouseLeaveDelay` | `number` | `100` | 移出后延迟关闭（ms） |
+| `disabled` | `boolean` | `false` | 禁用：不响应 hover |
+
+### Events
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `update:open` | `(open: boolean)` | 打开状态变化 |
+| `openChange` | `(open: boolean)` | 同上，语义别名 |
+
+### Slots
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `default` | — | 触发器（零包裹模式注入事件，建议单根元素） |
+| `content` | — | 富内容，替代 `content` 纯文本 |
+
+### 类型定义
+
+```ts
+export interface TooltipProps {
+  content?: string
+  open?: boolean
+  defaultOpen?: boolean
+  placement?: Placement
+  arrow?: boolean
+  mouseEnterDelay?: number
+  mouseLeaveDelay?: number
+  disabled?: boolean
+}
+```
+
+## 实现说明
+
+- Tooltip 是 Popover 的**薄封装**：固定 `trigger="hover"` 与 `unwrapped`，因此定位、Teleport、移入浮层不关闭、Esc 关闭这些能力都继承自 [Popover](/ui/overlay/popover)；
+- 默认延迟 100ms：既能避免鼠标划过时的闪烁，又不会让人觉得迟钝；
+- 浮层内容包了一层 `max-width: 260px` + 断词的文本容器，长句会自动折行而不是把浮层拉得很长。
diff --git a/code/g3soft-libs/docs/content/ui/5.feedback/.navigation.yml b/code/g3soft-libs/docs/content/ui/5.feedback/.navigation.yml
new file mode 100644
index 00000000..c550e45b
--- /dev/null
+++ b/code/g3soft-libs/docs/content/ui/5.feedback/.navigation.yml
@@ -0,0 +1,2 @@
+title: 反馈
+icon: i-lucide-bell
diff --git a/code/g3soft-libs/docs/content/ui/5.feedback/message.md b/code/g3soft-libs/docs/content/ui/5.feedback/message.md
new file mode 100644
index 00000000..e6350ddf
--- /dev/null
+++ b/code/g3soft-libs/docs/content/ui/5.feedback/message.md
@@ -0,0 +1,131 @@
+---
+title: Message 轻提示
+description: 命令式轻提示：info / success / warning / error
+---
+
+# Message 轻提示
+
+`Message` 用于给用户一个**不打断操作**的反馈：保存成功、校验失败、复制完成。
+
+## 何时使用
+
+- 操作结果反馈（成功 / 失败 / 警告）时；
+- 需要用户**确认**或做选择时，用 [Modal.confirm](/ui/overlay/modal)；
+- 需要承载标题 + 描述、停留更久时，用 [Notification](/ui/feedback/notification)。
+
+## 基础用法
+
+`G3Message` 是一个对象，直接调用即可——它会自己挂载容器到 `body`，无需在模板里写组件。
+
+:::demo{name="message/basic"}
+:::
+
+```ts
+import { G3Message } from '@g3soft/ui'
+
+G3Message.info('普通提示')
+G3Message.success('保存成功')
+G3Message.warning('磁盘空间不足')
+G3Message.error('保存失败，请重试')
+```
+
+## 选项与句柄
+
+第二个参数是选项对象；调用返回 `{ close }` 句柄，可以提前关闭。
+
+:::demo{name="message/options"}
+:::
+
+| 选项 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `duration` | `number` | `3000` | 自动关闭时长（ms）。`<= 0` 表示不自动关闭 |
+| `closable` | `boolean` | `false` | 是否显示关闭按钮 |
+| `placement` | `MessagePlacement` | 全局配置 | 显示方位（9 个） |
+
+## 方位与全局配置
+
+`placement` 可逐条指定；`G3Message.config()` 设置全局默认，只影响之后的调用。
+
+:::demo{name="message/placement"}
+:::
+
+```ts
+G3Message.config({ placement: 'top-right', duration: 2000 })
+```
+
+## 使用注意
+
+- `G3Message` 在**组件树之外**创建实例：命名空间、语言包、初始方位来自全局配置（`G3UI.config()` / `ConfigProvider` 无法 inject 到它），因此多主题场景请在 `G3UI.config({ namespace })` 里统一；
+- 消息是「短反馈」，不要放按钮、链接等需要交互的内容——那属于 Notification 或 Modal；
+- 同一时刻的消息默认堆叠在同一个方位，超过屏幕高度时请自行控制数量（例如 `duration` 缩短）。
+
+## API
+
+### 方法
+
+| 方法 | 签名 | 说明 |
+| --- | --- | --- |
+| `open` | `(options: MessageOptions) => MessageHandle` | 通用入口 |
+| `info` | `(content: string, options?: ShortcutOptions) => MessageHandle` | 信息提示 |
+| `success` | `(content: string, options?: ShortcutOptions) => MessageHandle` | 成功 |
+| `warning` | `(content: string, options?: ShortcutOptions) => MessageHandle` | 警告 |
+| `error` | `(content: string, options?: ShortcutOptions) => MessageHandle` | 错误 |
+| `close` | `(id: string) => void` | 按 id 关闭一条 |
+| `config` | `(config: MessageConfig) => void` | 设置全局默认（`placement` / `duration`） |
+| `destroy` | `() => void` | 清空全部消息并卸载容器（登出 / 切租户时用） |
+| `count` | `() => number` | 当前存活条数（调试用） |
+
+`ShortcutOptions` = `Omit<MessageOptions, 'content' | 'type'>`，即 `{ duration?, closable?, placement? }`。
+
+### 类型定义
+
+```ts
+export type MessageType = 'info' | 'success' | 'warning' | 'error'
+
+export type MessagePlacement =
+  | 'top-left' | 'top-center' | 'top-right'
+  | 'center-left' | 'center' | 'center-right'
+  | 'bottom-left' | 'bottom-center' | 'bottom-right'
+
+export interface MessageOptions {
+  content: string
+  type?: MessageType
+  duration?: number
+  closable?: boolean
+  placement?: MessagePlacement
+}
+
+export interface MessageHandle {
+  close: () => void
+}
+
+export interface MessageConfig {
+  placement?: MessagePlacement
+  duration?: number
+}
+```
+
+### 组件形式（G3MessageItem / G3MessageContainer）
+
+一般不需要直接使用；如果要把消息渲染进自己的容器（例如某个面板内部），可以组合它们：
+
+| 组件 | Props | 说明 |
+| --- | --- | --- |
+| `G3MessageItem` | `id` / `type` / `content` / `duration` / `closable` | 单条消息，`close` 事件表示「该关闭了」（自动计时到期或点了关闭按钮） |
+| `G3MessageContainer` | `zIndex` | 9 个方位的容器，读取全局 `messageState` 渲染 |
+
+### 样式变量
+
+| 变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `--g3-feedback-offset` | `24px` | 距视口边缘的距离 |
+| `--g3-feedback-icon-size` | `18px` | 类型图标尺寸 |
+| `--g3-shadow-popup` | 浮层阴影 | 消息卡片阴影 |
+
+## 实现说明
+
+- **组件树外挂载**：首次调用时创建单例容器（`createVNode` + `render` 挂到 `body`），之后复用；`destroy()` 才会卸载并回收 z-index；
+- 全局状态放在 `messageState`（`reactive`），容器读它、管理器写它，因此消息增删是响应式的；容器对 9 个方位各渲染一个常驻的 `TransitionGroup`，**只让消息项进出**，这是进出场动画能稳定触发的前提；
+- 层级取 z-index 注册表的 `feedback` 档（高于 modal / popup），保证弹窗里的操作提示也能看到；容器本身 `pointer-events: none`，只有消息卡片可交互，避免挡住页面；
+- `duration` 计时在消息项内部完成（`onMounted` 启动、卸载时清除），因此手动关闭与自动关闭不会互相干扰；
+- 文案来自语言包（关闭按钮的 `aria-label` 等），可用 `ConfigProvider.locale` / `G3UI.config({ locale })` 切换。
diff --git a/code/g3soft-libs/docs/content/ui/5.feedback/notification.md b/code/g3soft-libs/docs/content/ui/5.feedback/notification.md
new file mode 100644
index 00000000..b85bb066
--- /dev/null
+++ b/code/g3soft-libs/docs/content/ui/5.feedback/notification.md
@@ -0,0 +1,113 @@
+---
+title: Notification 通知提醒
+description: 命令式通知：带标题与描述，适合承载需要阅读的信息
+---
+
+# Notification 通知提醒
+
+`Notification` 与 [Message](/ui/feedback/message) 是同一套机制，但**承载更多信息**：有标题、有描述、默认停留更久（4500ms），适合「需要被读到」的内容。
+
+## 何时使用
+
+- 后台任务完成 / 失败，用户当前可能不在看那一块界面；
+- 需要标题 + 详细描述的信息（版本发布、审核结果、系统告警）；
+- 只是「一句话结果」时用 Message 更轻；需要用户做出选择时用 [Modal](/ui/overlay/modal)。
+
+## 基础用法
+
+:::demo{name="notification/basic"}
+:::
+
+```ts
+import { G3Notification } from '@g3soft/ui'
+
+G3Notification.success({ title: '发布成功', description: '版本 1.2.0 已上线' })
+G3Notification.error({ title: '构建失败', description: '单元测试未通过', duration: 0 })
+```
+
+## 方位
+
+通知只出现在四角（避免遮挡页面中央内容）；逐条可指定 `placement`，也可以用 `config()` 设全局默认。
+
+:::demo{name="notification/placement"}
+:::
+
+```ts
+G3Notification.config({ placement: 'bottom-right', duration: 6000 })
+```
+
+## 关闭与清理
+
+:::demo{name="notification/close"}
+:::
+
+## 使用注意
+
+- 通知是「异步结果」的表达，不要在用户操作的同一瞬间用它替代即时反馈——那种场景用 Message；
+- `duration: 0` 的通知必须带 `closable`（默认就是 `true`），否则用户无法关闭；
+- 登出、切换租户、路由跳转到登录页时建议调用 `G3Notification.destroy()`，避免残留旧上下文的通知。
+
+## API
+
+### 方法
+
+| 方法 | 签名 | 说明 |
+| --- | --- | --- |
+| `open` | `(options: NotificationOptions) => NotificationHandle` | 通用入口 |
+| `info` | `(options: ShortcutOptions) => NotificationHandle` | 信息 |
+| `success` | `(options: ShortcutOptions) => NotificationHandle` | 成功 |
+| `warning` | `(options: ShortcutOptions) => NotificationHandle` | 警告 |
+| `error` | `(options: ShortcutOptions) => NotificationHandle` | 错误 |
+| `close` | `(id: string) => void` | 按 id 关闭一条 |
+| `config` | `(config: NotificationConfig) => void` | 设置全局默认（`placement` / `duration`） |
+| `destroy` | `() => void` | 清空全部通知并卸载容器 |
+| `count` | `() => number` | 当前存活条数（调试用） |
+
+`ShortcutOptions` = `Omit<NotificationOptions, 'type'>`，即 `{ title?, description?, duration?, closable?, placement? }`。
+
+### 类型定义
+
+```ts
+export type NotificationType = 'info' | 'success' | 'warning' | 'error'
+export type NotificationPlacement = 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left'
+
+export interface NotificationOptions {
+  title?: string
+  description?: string
+  type?: NotificationType
+  duration?: number
+  closable?: boolean
+  placement?: NotificationPlacement
+}
+
+export interface NotificationHandle {
+  close: () => void
+}
+
+export interface NotificationConfig {
+  placement?: NotificationPlacement
+  duration?: number
+}
+```
+
+### 组件形式（G3NotificationItem / G3NotificationContainer）
+
+| 组件 | Props | 说明 |
+| --- | --- | --- |
+| `G3NotificationItem` | `id` / `type` / `title` / `description` / `duration` / `closable` | 单条通知，`close` 事件表示「该关闭了」 |
+| `G3NotificationContainer` | `zIndex` | 四角容器，读取全局 `notificationState` 渲染 |
+
+### 样式变量
+
+| 变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `--g3-feedback-offset` | `24px` | 距视口边缘的距离 |
+| `--g3-feedback-icon-size` | `18px` | 类型图标尺寸 |
+| `--g3-shadow-popup` | 浮层阴影 | 通知卡片阴影 |
+
+## 实现说明
+
+- 与 Message 同构：组件树外单例容器（`createVNode` + `render`）、`reactive` 全局列表、四角常驻 `TransitionGroup`；
+- 单条宽度固定 `340px`，`max-width: calc(100vw - offset*2)`，窄屏不会溢出；描述文字换行不截断（通知的意义就在于把话说完）；
+- 层级的 `feedback` 档高于 modal / popup：弹窗里触发的通知一定能被看到；
+- `destroy()` 会卸载容器并回收 z-index，适合登出等「上下文整体切换」的场景；`close(id)` 只关一条。
diff --git a/code/g3soft-libs/docs/content/ui/5.feedback/scrollbar.md b/code/g3soft-libs/docs/content/ui/5.feedback/scrollbar.md
new file mode 100644
index 00000000..676fba99
--- /dev/null
+++ b/code/g3soft-libs/docs/content/ui/5.feedback/scrollbar.md
@@ -0,0 +1,89 @@
+---
+title: Scrollbar 滚动容器
+description: 隐藏原生滚动条，用自绘滑块承载可滚动内容
+---
+
+# Scrollbar 滚动容器
+
+`Scrollbar` 给内容区套一层自绘滚动条。它统一了各浏览器（尤其是 Windows 与 macOS）的滚动条外观，并保证在深色主题下也可见。
+
+## 何时使用
+
+- 侧栏、面板、下拉列表等「内部滚动区域」需要与整体视觉统一时；
+- 原生滚动条太粗、或在深色主题下对比度不足时；
+- 高度固定的区域（必须给容器一个确定的高度，否则内容不会滚动）。
+
+## 基础用法
+
+容器必须有确定高度（`height` / `max-height`），滚动才会生效。
+
+:::demo{name="scrollbar/basic"}
+:::
+
+## 自动隐藏策略
+
+`autoHide` 控制滚动条何时出现：
+
+| 取值 | 行为 | 适合 |
+| --- | --- | --- |
+| `never` | 常显（默认） | 长列表、始终需要滚动提示 |
+| `scroll` | 滚动时显示，停止后渐隐 | 阅读区、日志 |
+| `move` | 鼠标移入或滚动时显示 | 面板、卡片 |
+| `leave` | 鼠标移出后隐藏 | 需要极简视觉的展示区 |
+
+:::demo{name="scrollbar/autohide"}
+:::
+
+## 无障碍
+
+滚动区域是一个可聚焦容器（键盘 `↑ ↓ PageUp PageDown` 可滚动），因此需要给出可读名称：
+
+```vue
+<G3Scrollbar aria-label="构建日志">…</G3Scrollbar>
+```
+
+`visibility="hidden"` 时滚动条彻底不显示，但内容仍可滚动（键盘 / 触控板可用）。
+
+## API
+
+### Props
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `visibility` | `'visible' \| 'auto' \| 'hidden'` | `'auto'` | 滚动条显示策略。`auto` 时按 `autoHide` 规则显隐；`hidden` 彻底不显示滚动条（仍可滚动） |
+| `autoHide` | `'never' \| 'scroll' \| 'move' \| 'leave'` | `'never'` | 自动隐藏策略，仅 `visibility="auto"` 时生效 |
+| `ariaLabel` | `string` | — | 滚动区域的无障碍名称，等价于 `aria-label` |
+
+### Slots
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `default` | — | 可滚动内容 |
+
+### 类型定义
+
+```ts
+export type ScrollbarVisibility = 'visible' | 'auto' | 'hidden'
+export type ScrollbarAutoHide = 'never' | 'scroll' | 'move' | 'leave'
+
+export interface ScrollbarProps {
+  visibility?: ScrollbarVisibility
+  autoHide?: ScrollbarAutoHide
+  ariaLabel?: string
+}
+```
+
+### 样式变量
+
+| 变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `--g3-scrollbar-size` | `8px` | 滚动条粗细 |
+| `--g3-scrollbar-thumb` | 半透明中性色 | 滑块颜色（hover 时加深） |
+| `--g3-scrollbar-track` | `transparent` | 轨道颜色 |
+
+## 实现说明
+
+- 滑块位置由 `scrollTop / scrollHeight` 实时换算，拖动滑块时反向写回滚动容器的 `scrollTop`；拖动期间给容器加 `is-dragging` 类，避免原生滚动干扰；
+- 尺寸变化（内容增删、容器缩放）通过 `ResizeObserver` 监听，滑块长度与可见性会自动更新，不需要手动 `update()`；
+- 隐藏原生滚动条用 `scrollbar-width: none` + `::-webkit-scrollbar { display: none }`，**不改** `overflow` 语义，因此键盘、触控板、`scrollIntoView` 全部照旧可用；
+- 不引第三方滚动库（如 overlayscrollbars），保持组件库零运行时依赖；代价是不支持原生「橡皮筋回弹」等平台特性。
diff --git a/code/g3soft-libs/docs/content/ui/5.feedback/spin.md b/code/g3soft-libs/docs/content/ui/5.feedback/spin.md
new file mode 100644
index 00000000..7b54e619
--- /dev/null
+++ b/code/g3soft-libs/docs/content/ui/5.feedback/spin.md
@@ -0,0 +1,90 @@
+---
+title: Spin 加载中
+description: 包裹内容显示加载遮罩，或作为独立的加载指示器
+---
+
+# Spin 加载中
+
+`Spin` 表达「正在加载」。它会**遮罩被包裹的内容并阻止交互**，这是它与只显示图标的纯视觉 loading 的区别。
+
+## 何时使用
+
+- 区域级加载：表格、卡片、表单在请求期间需要冻结交互时；
+- 局部刷新：点「重新加载」后只遮住该区域，而不是整页 loading；
+- 全局 loading 建议用顶部进度条或 [Message](/ui/feedback/message)，避免整页白屏。
+
+## 基础用法
+
+传默认插槽即「包裹模式」：`spinning` 为 true 时给内容加遮罩并显示指示器。
+
+:::demo{name="spin/basic"}
+:::
+
+## 独立使用
+
+不传默认插槽时就是独立指示器，配 `description` 显示加载文案。
+
+:::demo{name="spin/standalone"}
+:::
+
+## 延迟显示
+
+`delay` 用来防「闪一下」：请求很快时根本不显示加载态，只有超过 `delay` 才出现。
+
+:::demo{name="spin/delay"}
+:::
+
+## 使用建议
+
+```vue
+<!-- 推荐：局部冻结，用户知道「正在刷新的是哪一块」 -->
+<G3Spin :spinning="loading" :delay="300">
+  <DataTable :rows="rows" />
+</G3Spin>
+
+<!-- 不推荐：把整页包起来，用户失去上下文 -->
+<G3Spin :spinning="loading"><App /></G3Spin>
+```
+
+## API
+
+### Props
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `spinning` | `boolean` | `false` | 是否加载中。包裹模式下会显示遮罩并阻止点击；独立模式下控制指示器显隐 |
+| `delay` | `number` | `0` | 延迟显示（ms）。请求快于该值时不显示加载态，避免闪烁 |
+| `description` | `string` | — | 加载文案，显示在指示器下方 |
+
+### Slots
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `default` | — | 被遮罩的内容。不传时渲染为独立指示器 |
+| `indicator` | — | 自定义指示器（替换默认转圈） |
+| `description` | — | 自定义文案内容 |
+
+### 类型定义
+
+```ts
+export interface SpinProps {
+  spinning?: boolean
+  delay?: number
+  description?: string
+}
+```
+
+### 样式变量
+
+| 变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `--g3-spin-size` | `20px` | 指示器尺寸 |
+| `--g3-spin-description-gap` | `8px` | 指示器与文案的间距 |
+| `--g3-color-primary` | `#18181b` | 指示器颜色 |
+
+## 实现说明
+
+- 遮罩是绝对定位覆盖在内容之上（内容区保持原尺寸，不会因为加载而跳高跳宽），并吃掉点击，避免用户在加载中重复提交；
+- 遮罩带 `aria-busy="true"`，屏幕阅读器能感知「该区域忙」，并且不会改变内容的可访问名称；
+- `delay` 的计时在 `spinning` 变 true 时启动、变 false 时清除：这样连续多次短请求不会累积显示；
+- 转圈动画在 `prefers-reduced-motion: reduce` 下会变成静态（保留图形、停止旋转），避免诱发不适。
diff --git a/code/g3soft-libs/docs/content/ui/6.data/.navigation.yml b/code/g3soft-libs/docs/content/ui/6.data/.navigation.yml
new file mode 100644
index 00000000..9f920baa
--- /dev/null
+++ b/code/g3soft-libs/docs/content/ui/6.data/.navigation.yml
@@ -0,0 +1,2 @@
+title: 数据展示
+icon: i-lucide-table
diff --git a/code/g3soft-libs/docs/content/ui/6.data/date.md b/code/g3soft-libs/docs/content/ui/6.data/date.md
new file mode 100644
index 00000000..290bdb64
--- /dev/null
+++ b/code/g3soft-libs/docs/content/ui/6.data/date.md
@@ -0,0 +1,172 @@
+---
+title: DatePicker 日期选择
+description: 日期 / 日期时间 / 范围选择与时间滚轮（DatePicker / RangePicker / TimeSelect）
+---
+
+# 日期选择
+
+本页包含三个组件：`G3DatePicker`（单选日期 / 日期时间）、`G3RangePicker`（日期范围）、`G3TimeSelect`（时 / 分 / 秒滚轮）。
+
+它们的绑定值**都是字符串**（`TimeSelect` 除外，它绑定 `Date`），因此可以直接和后端接口对接，不需要在业务层做序列化。
+
+## 基础用法
+
+:::demo{name="date/date-basic"}
+:::
+
+## 精度与格式
+
+`format` 同时决定三件事：**面板粒度、展示格式、绑定值格式的默认值**；`valueFormat` 只影响绑定值。
+
+:::demo{name="date/date-format"}
+:::
+
+| 写法 | 面板 | 绑定值 |
+| --- | --- | --- |
+| `format="YYYY"` | 年选择器 | `2026` |
+| `format="YYYY-MM"` | 年月选择器 | `2026-10` |
+| `format="YYYY-MM-DD"`（默认） | 日期网格 | `2026-10-08` |
+| `format="YYYY-MM-DD HH:mm"` | 日期网格 + 时间列 + 确定按钮 | `2026-10-08 09:30` |
+| `format="YYYY-MM-DD HH:mm"` + `value-format="YYYY-MM-DD HH:mm:ss"` | 同上 | `2026-10-08 09:30:00` |
+
+支持的格式 token：`YYYY` `YY` `MM` `M` `MMM` `MMMM` `DD` `D` `Do` `dd` `ddd` `dddd` `HH` `H` `hh` `h` `mm` `m` `ss` `s` `SSS` `A` `a` `Z` `ZZ`。
+
+## 禁用日期与清除
+
+:::demo{name="date/date-disabled"}
+:::
+
+`disabledDate` 接收 `Date`，返回 `true` 表示该日不可选（禁用的格子不可聚焦、不可点击、不参与 hover 预览）。`timeDefault` 只在「没有值时点开面板」时决定时间初值：`'start'` 当天 00:00、`'end'` 当天 23:59:59、不传用当前时刻。
+
+## 手输与键盘微调
+
+输入框可以直接键入，容错规则如下：
+
+:::demo{name="date/manual-input"}
+:::
+
+| 输入 | 结果 |
+| --- | --- |
+| `2026-10-08` / `2026/10/08` / `2026年10月8日` | 都能解析（分隔符互认） |
+| `2026-10`（部分输入） | 解析为 `2026-10-01` |
+| `2026-13-45` | 判定非法：红框 1.5 秒后回填已提交值，**不会写入绑定值** |
+| 空串 | 视为清空（`''`），不是错误 |
+
+键盘：`Esc` 取消编辑、`Enter` 提交并关闭、`↑ / ↓` 微调光标所在的段（年 / 月 / 日 / 时 / 分）、`Alt + ↓` 打开面板并把焦点交给日历。
+
+## 日期范围
+
+两次点击确定起止；第二次点击的位置比起点更早时会**自动交换**。只点了一次就关闭面板不会写入值。
+
+:::demo{name="date/range-basic"}
+:::
+
+## 时间滚轮
+
+`TimeSelect` 绑定 `Date`，`fields` 决定显示哪几列，`hour12` 追加 am/pm 列。
+
+:::demo{name="date/time-select"}
+:::
+
+## API
+
+### Props（DatePicker）
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `modelValue` | `string \| Date \| null` | `null` | 绑定值。字符串按 `valueFormat` 解析 |
+| `format` | `string \| string[]` | `'YYYY-MM-DD'` | 展示格式与面板粒度 |
+| `valueFormat` | `string \| string[]` | 跟随 `format` | 绑定值格式 |
+| `clearable` | `boolean` | `true` | 有值时显示清除按钮 |
+| `disabled` | `boolean` | `false` | 禁用态 |
+| `disabledDate` | `(date: Date) => boolean` | — | 禁用某些日期 |
+| `timeDefault` | `'' \| 'start' \| 'end'` | `''` | 无值时的默认时间 |
+
+### Props（RangePicker）
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `modelValue` | `Array<string \| Date \| null> \| null` | `null` | `[start, end]`，元素可为空串 |
+| `format` | `string \| string[]` | `'YYYY-MM-DD'` | 展示格式与面板粒度 |
+| `valueFormat` | `string \| string[]` | 跟随 `format` | 绑定值格式 |
+| `clearable` | `boolean` | `true` | 显示清除按钮 |
+| `disabled` | `boolean` | `false` | 禁用态 |
+| `disabledDate` | `(date: Date) => boolean` | — | 禁用某些日期 |
+
+### Props（TimeSelect）
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `modelValue` | `Date \| null` | `null` | 当前时间；为空时以当前时刻为基准 |
+| `fields` | `Array<'hour' \| 'minute' \| 'second'>` | `['hour','minute','second']` | 显示哪几列 |
+| `hour12` | `boolean` | `false` | 12 小时制（小时列 1-12 + 追加 am/pm 列） |
+| `lowerMeridiem` | `boolean` | `false` | 上下午显示小写 `am` / `pm` |
+| `disabled` | `boolean` | `false` | 禁用态 |
+
+### Events
+
+| 组件 | 事件 | 参数 | 说明 |
+| --- | --- | --- | --- |
+| DatePicker | `update:modelValue` / `change` | `(value: string)` | 提交后的字符串值；清空为 `''` |
+| RangePicker | `update:modelValue` / `change` | `(value: string[])` | `[start, end]`；清空为 `['', '']` |
+| TimeSelect | `update:modelValue` | `(value: Date)` | 时间变化，恒为 `Date` |
+
+### 类型定义
+
+```ts
+export type DateValue = string | Date | null | undefined
+export type DateTimeDefault = '' | 'start' | 'end'
+export type TimeField = 'hour' | 'minute' | 'second'
+
+export interface DatePickerProps {
+  modelValue?: DateValue
+  format?: string | string[]
+  valueFormat?: string | string[]
+  clearable?: boolean
+  disabled?: boolean
+  disabledDate?: (date: Date) => boolean
+  timeDefault?: DateTimeDefault
+}
+
+export interface RangePickerProps {
+  modelValue?: Array<string | Date | null> | null
+  format?: string | string[]
+  valueFormat?: string | string[]
+  clearable?: boolean
+  disabled?: boolean
+  disabledDate?: (date: Date) => boolean
+}
+
+export interface TimeSelectProps {
+  modelValue?: Date | null
+  fields?: TimeField[]
+  hour12?: boolean
+  lowerMeridiem?: boolean
+  disabled?: boolean
+}
+```
+
+### 工具函数
+
+日期运算不依赖 dayjs，`@g3soft/ui` 导出了一组纯函数，业务可复用：
+
+| 函数 | 签名 | 说明 |
+| --- | --- | --- |
+| `formatDate` | `(value, format?) => string` | 按 token 格式化 |
+| `parseDate` | `(value, format?) => Date \| null` | 严格匹配 → 规范化文本 → 原生解析三级回退 |
+| `parseDateInput` | `(text, format) => { date, isEmpty, isValid }` | 手输解析，区分「空」与「非法」 |
+| `analyzeDateFormat` | `(format) => DateFormatConfig` | 解析出 `hasYear / hasTime / timeFields / hour12 …` |
+| `normalizeDateValue` / `normalizeDateForFormat` | `(value, format) => Date \| null` | 值归一与按精度归零 |
+| `getMonthMatrix` / `getMonthRows` | `(year, month) => Date[]` / `Date[][]` | 42 格月历（周日起始） |
+| `startOfDay` / `endOfDay` / `isSameDay` / `isSameMonth` / `isToday` | — | 日粒度判断 |
+| `compareDay` / `compareDate` / `isInRange` / `addMonth` / `combineDateTime` | — | 比较与合成 |
+| `listDateSegments` / `resolveDateSegment` / `stepDateSegment` | — | 手输光标分段与微调 |
+
+## 实现说明
+
+- **零第三方依赖**：fms 版依赖 dayjs + 两个插件，这里用 `date/date-utils.ts` 自研实现（格式化 token、严格解析、段定位、微调步进），保持组件库只依赖 `vue`；
+- **值的内部表示**：内部一律用 `Date` 运算，**对外一律字符串**。展示用 `format`、绑定值用 `valueFormat`，两者可以不同（展示到分钟、绑定到秒）；
+- **不污染绑定值**：手输过程只改本地文本，失焦 / 回车才提交；非法输入进错误态并回填旧值——表单里绝不允许出现「半天没法提交但看不出哪里错」的状态；
+- **面板是草稿值**：有时间精度时，点选只改草稿、点「确定」才提交；没有时间精度时点选即提交并关闭。关闭面板会丢弃草稿；
+- **定位复用 Popover**（`trigger="manual"`、`followTriggerWidth`），因此弹窗内打开日期面板、滚动跟随、Esc 关闭这些行为与 Select 完全一致；
+- 键盘可达性：日历是 `role="grid"`，格子为 `role="gridcell"`，只有当前格子 `tabindex=0`（roving tabindex），`← → ↑ ↓ Home End PageUp PageDown` 都能操作，且会跳过禁用日期；底部时间列是 `role="listbox"`，`↑ ↓` 步进 1、`PageUp/PageDown` 步进 5。
diff --git a/code/g3soft-libs/docs/content/ui/6.data/pagination.md b/code/g3soft-libs/docs/content/ui/6.data/pagination.md
new file mode 100644
index 00000000..4c08c9ac
--- /dev/null
+++ b/code/g3soft-libs/docs/content/ui/6.data/pagination.md
@@ -0,0 +1,123 @@
+---
+title: Pagination 分页器
+description: 页码、每页条数、快速跳转与总条数
+---
+
+# Pagination 分页器
+
+`Pagination` 用来在长列表里翻页。它只负责「页码状态」，不关心数据请求——翻页后由你拿 `current` / `pageSize` 去拉数据。
+
+## 何时使用
+
+- 数据量较大、需要分页请求时；
+- 需要在「每页条数」与「快速跳转」上给用户控制权时；
+- 数据可以一次拉完（< 200 条）时，直接滚动加载可能体验更好。
+
+## 基础用法
+
+:::demo{name="pagination/basic"}
+:::
+
+## 每页条数
+
+`showSizeChanger` 显示每页条数下拉；`showSizeChange` 只在该值变化时触发，**先于** `change`。
+
+:::demo{name="pagination/size-changer"}
+:::
+
+## 快速跳转与总条数
+
+:::demo{name="pagination/quick-jumper"}
+:::
+
+`#showTotal` 插槽作用域是 `{ total, from, to }`：
+
+:::demo{name="pagination/total"}
+:::
+
+## 只有一页时隐藏
+
+:::demo{name="pagination/hide-on-single"}
+:::
+
+## 与列表联动
+
+```vue
+<script setup lang="ts">
+const current = ref(1)
+const pageSize = ref(20)
+
+const { data } = await useFetch('/api/list', {
+  query: computed(() => ({ page: current.value, size: pageSize.value })),
+})
+</script>
+
+<template>
+  <DataTable :rows="data.rows" />
+  <G3Pagination v-model:current="current" v-model:page-size="pageSize" :total="data.total" show-size-changer show-total />
+</template>
+```
+
+翻页后请记得把列表滚动回顶部（`scrollTo({ top: 0 })`），否则用户会看到「页码变了但内容没动」的错觉。
+
+## API
+
+### Props
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `current` | `number` | — | 当前页（`v-model:current`）。不传时内部维护，默认 1 |
+| `pageSize` | `number` | — | 每页条数（`v-model:pageSize`）。不传时内部维护，默认 10 |
+| `total` | `number` | `0` | 总条数 |
+| `disabled` | `boolean` | `false` | 禁用整组 |
+| `hideOnSinglePage` | `boolean` | `false` | 只有一页时隐藏整个分页器 |
+| `showSizeChanger` | `boolean` | `false` | 显示每页条数选择器 |
+| `pageSizeOptions` | `Array<number \| string>` | `[10, 20, 50, 100]` | 每页条数选项 |
+| `showQuickJumper` | `boolean` | `false` | 显示快速跳转输入框 |
+| `showTotal` | `boolean` | `false` | 显示总条数文案 |
+
+### Events
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `update:current` | `(page: number)` | 当前页变化 |
+| `update:pageSize` | `(size: number)` | 每页条数变化 |
+| `change` | `(page: number, pageSize: number)` | 翻页与改每页条数都会触发 |
+| `showSizeChange` | `(current: number, size: number)` | **仅**改每页条数时触发，先于 `change` |
+
+### Slots
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `showTotal` | `{ total: number; from: number; to: number }` | 自定义总条数文案；`from` / `to` 是当前页的起止序号（`total` 为 0 时都是 0） |
+
+### 类型定义
+
+```ts
+export interface PaginationProps {
+  current?: number
+  pageSize?: number
+  total?: number
+  disabled?: boolean
+  hideOnSinglePage?: boolean
+  showSizeChanger?: boolean
+  pageSizeOptions?: Array<number | string>
+  showQuickJumper?: boolean
+  showTotal?: boolean
+}
+
+export interface PaginationTotalScope {
+  total: number
+  from: number
+  to: number
+}
+```
+
+## 实现说明
+
+- **页码窗口算法**：总页数 ≤ 7 全部展开；否则固定首页与末页、当前页 ±1，并用省略号表示被折叠的部分。点省略号会向前/后跳 5 页：
+  - 前面的省略号 → `max(1, current - 5)`
+  - 后面的省略号 → `min(totalPages, current + 5)`
+- **越界收敛但不回写**：受控值超出范围时只收敛**显示**（`clampPage`），不会 emit 新值——避免「父层给了 999，组件偷偷改成 10」这类难以排查的行为；
+- 快速跳转只在回车时提交，输入非数字、超范围都会被忽略并清空输入框（点失焦也清空），避免残留一个「看起来有效其实没提交」的数字；
+- 语义与无障碍：根节点 `role="navigation"`；当前页 `aria-current="page"`；上一页 / 下一页与省略号都有 `aria-label`（来自语言包，可随 `locale` 切换）；禁用状态用原生 `disabled`，键盘用户不会误触。
diff --git a/code/g3soft-libs/docs/content/ui/6.data/splitter.md b/code/g3soft-libs/docs/content/ui/6.data/splitter.md
new file mode 100644
index 00000000..9d5447af
--- /dev/null
+++ b/code/g3soft-libs/docs/content/ui/6.data/splitter.md
@@ -0,0 +1,116 @@
+---
+title: Splitter 分割面板
+description: 可拖拽调整大小的多面板布局，支持左右 / 上下与嵌套
+---
+
+# Splitter 分割面板
+
+`Splitter` 把容器切成若干可拖拽调整大小的面板，用于 IDE 式布局：侧栏 + 编辑区 + 控制台。
+
+## 何时使用
+
+- 用户需要自己决定「哪一块看多少」时（列表 / 详情、代码 / 预览）；
+- 页面结构固定且各区域可独立滚动时；
+- 只是把内容分列、用户不需要调整时，用 [Grid](/ui/general/grid) 更轻。
+
+## 基础用法
+
+`G3SplitterPanel` 放 `G3Splitter` 内。给了 `defaultSize` / `size` 的面板尺寸固定，其余面板平分剩余空间。
+
+:::demo{name="splitter/basic"}
+:::
+
+## 上下分栏
+
+`direction="vertical"` 时用 `defaultSize` 控制高度；`barOnHover` 默认 `true`（分割线只在 hover / 聚焦 / 拖拽时显示）。
+
+:::demo{name="splitter/vertical"}
+:::
+
+## 尺寸约束
+
+`min` / `max` 支持数字（px）或百分比字符串；`resizable="false"` 的面板不参与拖动（两侧都必须可调，分隔条才能拖）。
+
+:::demo{name="splitter/constraints"}
+:::
+
+## 嵌套
+
+外层左右、内层上下，可以组合出常见的工作台布局。
+
+:::demo{name="splitter/nested"}
+:::
+
+## 键盘操作
+
+分隔条是可聚焦的（`role="separator"`）：`Tab` 聚焦后，用 `← →`（横向）或 `↑ ↓`（纵向）调整，步长 10px，按住 `Shift` 为 50px；同时会通过 `aria-valuenow / valuemin / valuemax` 播报当前位置百分比。
+
+## API
+
+### Props（Splitter）
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `direction` | `'horizontal' \| 'vertical'` | `'horizontal'` | 分割方向。`horizontal` 为左右分栏 |
+| `barOnHover` | `boolean` | `true` | 分割线仅在 hover / 聚焦 / 拖拽时显示 |
+
+### Props（SplitterPanel）
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `size` | `number \| string` | — | 受控尺寸（px 或 `'30%'`）。传入后拖拽不会由内部接管该面板 |
+| `defaultSize` | `number \| string` | — | 非受控初始尺寸；拖拽后由内部接管 |
+| `min` | `number \| string` | — | 最小尺寸，拖动时约束 |
+| `max` | `number \| string` | — | 最大尺寸，拖动时约束 |
+| `resizable` | `boolean` | `true` | 是否允许被相邻分隔条调整（两侧都为 `true` 才可拖） |
+
+### Events（Splitter）
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `resizeStart` | `(sizes: number[])` | 开始拖拽，参数是各面板的实测像素宽/高 |
+| `resize` | `(sizes: number[])` | 拖拽过程中每帧触发（键盘调整也会触发一次） |
+| `resizeEnd` | `(sizes: number[])` | 拖拽结束（键盘调整后同样触发） |
+
+### Slots
+
+| 组件 | 插槽 | 说明 |
+| --- | --- | --- |
+| Splitter | `default` | `G3SplitterPanel` 列表（其他元素会被忽略） |
+| SplitterPanel | `default` | 面板内容 |
+
+### 类型定义
+
+```ts
+export type SplitterDirection = 'horizontal' | 'vertical'
+export type SplitterSize = number | string
+
+export interface SplitterProps {
+  direction?: SplitterDirection
+  barOnHover?: boolean
+}
+
+export interface SplitterPanelProps {
+  min?: SplitterSize
+  max?: SplitterSize
+  size?: SplitterSize
+  defaultSize?: SplitterSize
+  resizable?: boolean
+}
+```
+
+### 样式变量
+
+| 变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `--g3-splitter-trigger-size` | `10px` | 分隔条命中区宽度（比视觉线宽，方便抓取） |
+| `--g3-splitter-bar-size` | `3px` | 视觉线宽 |
+| `--g3-color-primary` | `#18181b` | 拖拽 / 聚焦时的线色 |
+
+## 实现说明
+
+- **尺寸模型**：只有「给了 `size` / `defaultSize` 的面板」和「刚被拖动过的相邻两块」持有明确像素值，其余面板用 `flex: 1 1 0%` 平分。拖拽结束会调用 `releaseAutoPanels()`，把没有显式尺寸的面板恢复成自动——否则窗口缩放后剩余空间会填不满；
+- **拖拽实现**：Pointer Events + `requestAnimationFrame` 合并（`pointermove` 只记最新事件，帧内只算一次），并且只在 `window` 上挂监听，指针移出面板也不会中断；拖动期间禁用文本选中；
+- **约束算法**：把偏移量先按前一格的 `[min, max]` 钳制，再按后一格的 `[min, max]` 钳制，两块面板的尺寸之和保持不变（不会把总宽拖变形）；
+- 分隔条的 `aria-orientation` 与视觉方向**相反**（左右分栏时分隔条是纵向的 `vertical`），这是 ARIA 规范要求的语义；
+- 面板内容区自带 `overflow: auto`，因此面板内部滚动不会影响外层布局。
diff --git a/code/g3soft-libs/docs/content/ui/6.data/tabs.md b/code/g3soft-libs/docs/content/ui/6.data/tabs.md
new file mode 100644
index 00000000..5daa48c8
--- /dev/null
+++ b/code/g3soft-libs/docs/content/ui/6.data/tabs.md
@@ -0,0 +1,137 @@
+---
+title: Tabs 标签页
+description: 在同一区域切换多个内容面板，首次激活才挂载、切换不销毁
+---
+
+# Tabs 标签页
+
+`Tabs` 在同一块区域里切换多个内容面板。它与 [Segmented](/ui/general/segmented) 的区别是：Tabs 负责「选择 + 内容区 + 懒渲染」，Segmented 只负责「选择」。
+
+## 何时使用
+
+- 同一对象的不同维度（基本信息 / 配置 / 权限）需要分区展示时；
+- 面板内容较重（表格、图表、表单）时，Tabs 的懒渲染能避免一次性挂载所有面板；
+- 纯视图模式切换、没有独立内容区时用 Segmented 更轻。
+
+## 声明式写法
+
+`G3TabPane` 只作声明，不渲染 DOM：`tab-key` 是唯一标识（不传按声明顺序取索引），`label` 是标签文字。
+
+:::demo{name="tabs/basic"}
+:::
+
+## 数据源写法
+
+`items` 提供时优先于插槽；`content` 可以是字符串、VNode 或返回 VNode 的函数。标签动态来自接口时用这种写法。
+
+:::demo{name="tabs/items"}
+:::
+
+## 位置
+
+`placement="left" | "right"` 时标签栏纵向排列，指示条自动贴到对应边。
+
+:::demo{name="tabs/placement"}
+:::
+
+## 视觉风格
+
+`type="line"` 是下划线指示条（默认），`type="pill"` 是胶囊式；`centered` 让标签栏居中。
+
+:::demo{name="tabs/type"}
+:::
+
+## 只要标签栏
+
+`navOnly` 时不渲染内容区，内容由外部（路由、分栏）控制；配合 `#label`、`#leftExtra`、`#rightExtra` 可以定制标签与两端内容。
+
+:::demo{name="tabs/nav-only"}
+:::
+
+## 键盘操作
+
+标签栏是标准的 `role="tablist"`：`Tab` 进入标签栏后，用**左右键**（top 位置）或**上下键**（left / right 位置）切换，`Home` / `End` 跳首尾；禁用的标签会被跳过。
+
+## 面板生命周期
+
+面板**首次激活才挂载**，之后切换只切换显隐（`v-show`），因此：
+
+- 表单输入、滚动位置、图表实例在切换后不会丢；
+- 未访问过的面板不会发请求（适合「概览 / 明细有重请求」的场景）；
+- 如果面板里有需要「每次进入都刷新」的数据，请在 `change` 事件里自行处理。
+
+## API
+
+### Props（Tabs）
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `modelValue` | `string \| number` | — | 双向绑定的激活面板 key（内部按字符串比较，事件回传原始类型） |
+| `placement` | `'top' \| 'left' \| 'right'` | `'top'` | 标签栏位置 |
+| `type` | `'line' \| 'pill'` | `'line'` | 视觉风格 |
+| `navOnly` | `boolean` | `false` | 只渲染标签栏，不渲染内容区 |
+| `centered` | `boolean` | `false` | 标签栏居中 |
+| `disabled` | `boolean` | `false` | 禁用整组 |
+| `items` | `TabItem[]` | — | 数据源；提供且非空时优先于 `G3TabPane` 插槽 |
+
+### Props（TabPane）
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `tabKey` | `string \| number` | 声明顺序索引 | 唯一标识 |
+| `label` | `string` | — | 标签文本（有 `#label` 插槽时忽略） |
+| `disabled` | `boolean` | `false` | 禁用该标签 |
+
+### Events（Tabs）
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `update:modelValue` | `(key: string \| number)` | 激活项变化（回传**原始类型**的 key） |
+| `change` | `(key: string \| number)` | 仅在实际切换时触发（点当前标签不触发） |
+| `tabClick` | `(key: string \| number, event: MouseEvent)` | 点击即触发（含点当前标签）；键盘切换不触发 |
+
+### Slots
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `default` | — | `G3TabPane` 列表（items 模式下可省） |
+| `label` | `{ item, index }` | 自定义标签渲染 |
+| `leftExtra` | — | 标签栏左端内容 |
+| `rightExtra` | — | 标签栏右端内容 |
+
+### 类型定义
+
+```ts
+export type TabsPlacement = 'top' | 'left' | 'right'
+export type TabsType = 'line' | 'pill'
+export type TabKey = string | number
+
+export interface TabItem {
+  key: TabKey
+  label?: string | VNode
+  disabled?: boolean
+  content?: VNode | (() => VNode)
+}
+
+export interface TabPaneProps {
+  tabKey?: TabKey
+  label?: string
+  disabled?: boolean
+}
+```
+
+### 样式变量
+
+| 变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `--g3-tabs-tab-height` | `38px` | 标签项高度（故意高于控件档位，便于点击） |
+| `--g3-color-primary` | `#18181b` | 激活项文字与指示条颜色 |
+| `--g3-border-color` | `#d9d9d9` | 标签栏底部分隔线 |
+
+## 实现说明
+
+- **受控/非受控**：不传 `modelValue` 时内部维护激活项。若受控值指向不存在或已禁用的面板，会**回退显示第一个可用项，但不回写**——这样受控语义保持干净（否则会在渲染期偷偷改你的状态）；
+- **标签栏用原生 radio 语义吗？**不是：Tabs 用的是 `role="tablist"` + `role="tab"` + `role="tabpanel"` 与 roving tabindex（只有激活项 `tabindex=0`），键盘切换后主动 `focus()` 到目标标签，保证焦点可见；
+- **懒渲染缓存**：`renderedKeys` 记录「访问过的 key」，模板用 `v-if` 控制挂载、`v-show` 控制显隐，因此切换不会重建 DOM，也就不会丢内部状态；
+- 标签栏溢出时横向滚动（隐藏原生滚动条），标签不换行——避免出现两行标签把内容区挤下去；
+- 指示条不使用 JS 测量：它就是每个标签自身的 `border-bottom-color`（left/right 位置对应 `border-right/left`），因此字体缩放、文案长度变化都不会错位，也不需要 `ResizeObserver`。
diff --git a/code/g3soft-libs/docs/content/ui/6.data/tree.md b/code/g3soft-libs/docs/content/ui/6.data/tree.md
new file mode 100644
index 00000000..ec274df4
--- /dev/null
+++ b/code/g3soft-libs/docs/content/ui/6.data/tree.md
@@ -0,0 +1,205 @@
+---
+title: Tree 树形控件
+description: 层级数据展示与操作：选中、勾选联动、过滤、拖拽排序、懒加载、右键菜单
+---
+
+# Tree 树形控件
+
+`Tree` 用于展示带层级的数据（组织架构、目录、菜单、权限），并支持在树上直接做操作。
+
+## 何时使用
+
+- 数据天然有父子关系（目录、分类、组织）时；
+- 需要「勾选一批节点交给后端」时（权限分配、批量操作）；
+- 需要拖拽调整层级或顺序时；
+- 只是展示扁平的一列选项时，用 [Select](/ui/form/select) 或 [Checkbox](/ui/form/checkbox) 更简单。
+
+## 基础用法
+
+`treeData` 是嵌套结构，默认按 `{ key, title, children }` 取值；选中值用 `v-model:selected-keys`。
+
+:::demo{name="tree/basic"}
+:::
+
+## 勾选与半选
+
+`checkable` 开启复选框；**默认是父子联动**（选中父节点自动勾选全部子孙，部分选中时父节点显示半选）。`checkStrictly` 关闭联动，父子互不影响。
+
+:::demo{name="tree/checkable"}
+:::
+
+`check` 事件的载荷是 `{ checked, halfChecked }`，`checked` 已包含联动推导出的子孙节点，可以直接提交给后端。
+
+## 展开状态
+
+| 场景 | 用法 |
+| --- | --- |
+| 初始全展开 | `default-expand-all` |
+| 初始展开指定项（并自动补全祖先） | `default-expanded-keys` + `default-expand-parent`（默认开） |
+| 完全受控 | 传 `expanded-keys` + `v-model:expanded-keys` |
+| 选中/勾选后自动展开祖先 | `auto-expand-parent` |
+
+:::demo{name="tree/expand"}
+:::
+
+## 过滤
+
+`filter` 传关键词：命中的节点与它的**祖先链**会显示，命中文字高亮，命中路径自动展开（这个自动展开不会写进你的 `expandedKeys`）。
+
+:::demo{name="tree/filter"}
+:::
+
+`#title` 插槽存在时，内置高亮不生效——因为标题完全由你渲染。需要自带高亮时请在自己的插槽里处理。
+
+## 懒加载
+
+`lazy` 模式下，展开一个「没有 children 且未加载过」的节点会触发 `load`；你请求完把 children 写回数据，并把 key 记入 `loaded-keys`（组件据此停止显示加载图标、并判断是否还有子节点）。
+
+:::demo{name="tree/lazy"}
+:::
+
+## 拖拽排序
+
+`draggable` 开启拖拽。落点按行的上 25% / 中 50% / 下 25% 分成 `before` / `inside` / `after`，你需要在 `drop` 事件里自己重排数据——组件**不会**直接修改 `tree-data`。
+
+:::demo{name="tree/draggable"}
+:::
+
+`externalDragKey` 可以把「树外拖入」的来源（如字段库）映射成拖拽键，从而让树内节点成为落点（用于「把字段拖进目录」这类场景）。
+
+## 右键菜单
+
+`contextMenu` 传数组或 `(node, key) => items`：节点上右键收到该节点，空白处右键收到 `null`。
+
+:::demo{name="tree/context-menu"}
+:::
+
+## 自定义字段与渲染
+
+`fieldNames` 映射后端字段；节点自身的 `icon` / `disabled` / `disableCheckbox` / `draggable: false` / `isLeaf` 可以逐节点覆盖行为。
+
+:::demo{name="tree/custom"}
+:::
+
+## 键盘操作
+
+树是标准的 `role="tree"`（节点 `role="treeitem"`），采用 roving tabindex：
+
+| 按键 | 行为 |
+| --- | --- |
+| `↑` / `↓` | 在可见节点间移动（自动跳过被折叠的子树） |
+| `→` | 展开当前节点；已展开则进入第一个子节点 |
+| `←` | 收起当前节点；已收起则跳到父节点 |
+| `Enter` | 选中当前节点 |
+| `Space` | 勾选（无复选框时等同选中） |
+
+## API
+
+### Props
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `treeData` | `TreeNodeData[]` | `[]` | 树数据（嵌套结构） |
+| `fieldNames` | `TreeFieldNames` | `{ key: 'key', title: 'title', children: 'children', icon: 'icon' }` | 字段名映射 |
+| `checkable` | `boolean` | `false` | 显示复选框 |
+| `selectable` | `boolean` | `true` | 是否允许选中（`false` 时行点击不选中） |
+| `multiple` | `boolean` | `false` | 多选：`Ctrl/Cmd + 点击`切换、普通点击单选替换、再点唯一项取消 |
+| `checkStrictly` | `boolean` | `false` | 勾选严格模式：父子不联动 |
+| `disabled` | `boolean` | `false` | 整树禁用（展开 / 选中 / 勾选 / 拖拽 / 右键全部短路） |
+| `lazy` | `boolean` | `false` | 异步加载模式；首次展开未加载节点时触发 `load` |
+| `draggable` | `boolean` | `false` | 允许拖拽排序 |
+| `externalDragKey` | `(dataTransfer, event) => TreeKey \| null` | — | 把树外拖入源映射成拖拽键，返回 `null` 表示不识别 |
+| `filter` | `string` | `''` | 过滤关键词（匹配 title，大小写不敏感） |
+| `blockNode` | `boolean` | `false` | 节点占满整行（便于显示 hover 底色） |
+| `defaultExpandAll` | `boolean` | `false` | 初始展开全部（仅非受控初始化生效） |
+| `defaultExpandParent` | `boolean` | `true` | 初始补全 `defaultExpandedKeys` 的祖先路径 |
+| `autoExpandParent` | `boolean` | `false` | 选中 / 勾选后自动展开其祖先路径 |
+| `contextMenu` | `TreeContextMenuItem[] \| ((node, key) => TreeContextMenuItem[])` | — | 右键菜单数据源（`node` 为 `null` 表示空白处） |
+| `expandedKeys` | `TreeKey[]` | — | 受控展开键（**传了即受控**） |
+| `selectedKeys` | `TreeKey[]` | — | 受控选中键 |
+| `checkedKeys` | `TreeKey[] \| { checked: TreeKey[] }` | — | 受控勾选键（两种形态都接受） |
+| `loadedKeys` | `TreeKey[]` | — | 受控已加载键（懒加载用） |
+| `defaultExpandedKeys` | `TreeKey[]` | `[]` | 非受控初始展开键 |
+| `defaultSelectedKeys` | `TreeKey[]` | `[]` | 非受控初始选中键 |
+| `defaultCheckedKeys` | `TreeKey[]` | `[]` | 非受控初始勾选键 |
+| `defaultLoadedKeys` | `TreeKey[]` | `[]` | 非受控初始已加载键 |
+
+### Events
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `select` | `(keys, { node, selectedKeys, nativeEvent })` | 选中项变化 |
+| `check` | `({ checked, halfChecked }, { node, checked })` | 勾选变化。第二个参数的 `checked` 表示本次是「勾上」还是「取消」 |
+| `expand` | `(expandedKeys, { node, expanded })` | 展开 / 收起 |
+| `load` | `(node)` | 懒加载：首次展开未加载节点 |
+| `drop` | `({ dragKey, dropKey, dropPosition, node, event })` | 拖拽落下。`dropPosition` 为 `'before' \| 'inside' \| 'after'` |
+| `dragstart` / `dragend` | `({ node, event })` | 拖拽开始 / 结束 |
+| `contextmenu` | `({ node, key, event })` | 右键（空白处 `node` 为 `null`） |
+| `contextMenuClick` | `({ item, node, key, event })` | 点击右键菜单项 |
+| `update:expandedKeys` | `(keys)` | 展开键变化（受控 / 非受控都会发出） |
+| `update:selectedKeys` | `(keys)` | 选中键变化 |
+| `update:checkedKeys` | `(keys)` | 勾选键变化 |
+| `update:loadedKeys` | `(keys)` | 已加载键变化 |
+
+### Slots
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `title` | `{ node, expanded, selected }` | 自定义节点标题（提供后内置高亮失效） |
+| `empty` | — | 无数据时的内容，默认取语言包的「暂无数据」 |
+
+### 类型定义
+
+```ts
+export type TreeKey = string | number
+export type DropPosition = 'before' | 'inside' | 'after'
+
+export interface TreeFieldNames {
+  key?: string
+  title?: string
+  children?: string
+  icon?: string
+}
+
+export interface TreeNodeData {
+  key?: TreeKey
+  title?: string
+  children?: TreeNodeData[]
+  icon?: Component | VNode
+  disabled?: boolean
+  disableCheckbox?: boolean
+  draggable?: boolean
+  isLeaf?: boolean
+}
+
+export interface TreeContextMenuItem {
+  key: string | number
+  label?: string
+  icon?: Component | VNode
+  disabled?: boolean
+  danger?: boolean
+  divider?: boolean
+}
+```
+
+### 样式变量
+
+| 变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `--g3-tree-node-height` | `32px` | 节点行高 |
+| `--g3-tree-indent` | `18px` | 每层缩进量 |
+| `--g3-tree-icon-size` | `16px` | 图标尺寸 |
+| `--g3-tree-switcher-size` | `22px` | 展开箭头点击区 |
+| `--g3-tree-gutter-x` | `4px` | 节点行左右留白 |
+| `--g3-tree-title-padding-x` | `6px` | 标题内边距 |
+| `--g3-tree-drop-line-size` | `2px` | 拖拽落点指示线粗细 |
+
+## 实现说明
+
+- **勾选只存显式键**：非严格模式下 `checkedKeys` 保存的是「用户直接点过的节点」，实际的勾选与半选状态由 `conductCheck()` 从数据推导（父选中 ⇒ 子孙选中；子全选中 ⇒ 父选中；部分选中 ⇒ 父半选）。点击时还会把该节点的**祖先从显式集合里删掉**，否则「取消一个子节点」会被父节点残留的显式条目瞬间拉回勾选；
+- **性能**：`buildFlat()` 一次 DFS 建好父键 / 层级 / 子键 / 根键四张索引表（`computed` 缓存，`treeData` 变才重算），勾选联动、过滤、拖拽判断都基于索引表，不重复递归；
+- **过滤与展开分离**：过滤命中的自动展开只作用于「有效展开集合」，不写回用户的 `expandedKeys`——关闭过滤后树的展开状态回到用户原样；
+- **键盘可见顺序**：`visibleKeys` 是按当前展开状态 DFS 出来的顺序（遇到折叠就截断），与过滤结果取交集，因此 `↑ ↓` 只在「用户真正看得到的节点」间移动；
+- **拖拽**：`drop` 之前先快照落点位置再清理视觉状态（否则读到的永远是 `null`）；内部拖拽会校验 `isDescendant`，不允许把节点拖进自己的子树；
+- **层级缩进**：不是嵌套 padding，而是节点行内联 `--g3-tree-level` + CSS `calc(gutter + indent * level)`，拖拽指示线复用同一个计算，因此深层节点的落点线也能精确对齐；
+- **右键菜单**：Teleport 到配置容器、按鼠标坐标定位并用 `computePosition` 做视口翻转，关闭时机是「文档 mousedown（捕获）+ Esc + 滚动 + resize」，组件卸载时统一清理。
diff --git a/code/g3soft-libs/docs/data/api/button.json b/code/g3soft-libs/docs/data/api/button.json
deleted file mode 100644
index 90f64b2a..00000000
--- a/code/g3soft-libs/docs/data/api/button.json
+++ /dev/null
@@ -1,66 +0,0 @@
-{
-  "displayName": "Button",
-  "description": "常用的操作按钮。 支持 7 种视觉类型、3 种尺寸，以及加载、禁用、撑满、纯图标等状态。",
-  "props": [
-    {
-      "name": "type",
-      "description": "视觉类型",
-      "type": "ButtonType",
-      "defaultValue": "default"
-    },
-    {
-      "name": "size",
-      "description": "尺寸",
-      "type": "ButtonSize",
-      "defaultValue": "medium"
-    },
-    {
-      "name": "htmlType",
-      "description": "原生 button 的 type 属性",
-      "type": "union",
-      "defaultValue": "button"
-    },
-    {
-      "name": "disabled",
-      "description": "是否禁用",
-      "type": "boolean",
-      "defaultValue": "false"
-    },
-    {
-      "name": "loading",
-      "description": "是否加载中：同时禁止点击并展示加载图标",
-      "type": "boolean",
-      "defaultValue": "false"
-    },
-    {
-      "name": "block",
-      "description": "是否撑满父容器宽度",
-      "type": "boolean",
-      "defaultValue": "false"
-    },
-    {
-      "name": "iconOnly",
-      "description": "是否仅图标：渲染为正方形按钮",
-      "type": "boolean",
-      "defaultValue": "false"
-    }
-  ],
-  "events": [
-    {
-      "name": "click",
-      "description": "",
-      "type": "",
-      "defaultValue": ""
-    }
-  ],
-  "slots": [
-    {
-      "name": "icon",
-      "description": ""
-    },
-    {
-      "name": "default",
-      "description": ""
-    }
-  ]
-}
diff --git a/code/g3soft-libs/docs/data/api/config-provider.json b/code/g3soft-libs/docs/data/api/config-provider.json
deleted file mode 100644
index feba4171..00000000
--- a/code/g3soft-libs/docs/data/api/config-provider.json
+++ /dev/null
@@ -1,50 +0,0 @@
-{
-  "displayName": "G3ConfigProvider",
-  "description": "ConfigProvider —— 全局/子树配置。 theme.local（默认）：把派生出的 CSS 变量挂到子树根节点（cloneVNode 合并 style，不额外包 DOM）， 支持同一页面多主题共存。 theme.global：挂到 :root 做整站换肤，卸载时只清理自己设置过的变量。 用 render function 实现（而非 <template>），因为 local 作用域需要 cloneVNode 精确注入。",
-  "props": [
-    {
-      "name": "namespace",
-      "description": "",
-      "type": "string",
-      "defaultValue": "undefined"
-    },
-    {
-      "name": "theme",
-      "description": "",
-      "type": "G3ThemeConfig",
-      "defaultValue": "undefined"
-    },
-    {
-      "name": "zIndex",
-      "description": "",
-      "type": "number",
-      "defaultValue": "undefined"
-    },
-    {
-      "name": "locale",
-      "description": "",
-      "type": "Locale",
-      "defaultValue": "undefined"
-    },
-    {
-      "name": "popupContainer",
-      "description": "",
-      "type": "PopupContainer",
-      "defaultValue": "undefined"
-    },
-    {
-      "name": "componentDefaults",
-      "description": "",
-      "type": "Record<string, Record<string, unknown>>",
-      "defaultValue": "undefined"
-    },
-    {
-      "name": "emptyText",
-      "description": "",
-      "type": "string",
-      "defaultValue": "undefined"
-    }
-  ],
-  "events": [],
-  "slots": []
-}
diff --git a/code/g3soft-libs/docs/examples/button-group/basic.vue b/code/g3soft-libs/docs/examples/button-group/basic.vue
new file mode 100644
index 00000000..a9ab92bc
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/button-group/basic.vue
@@ -0,0 +1,12 @@
+<script setup lang="ts">
+// 贴合排列：中间边框重叠 1px，首尾保留圆角
+import { G3Button, G3ButtonGroup } from '@g3soft/ui'
+</script>
+
+<template>
+  <G3ButtonGroup>
+    <G3Button>左</G3Button>
+    <G3Button>中</G3Button>
+    <G3Button>右</G3Button>
+  </G3ButtonGroup>
+</template>
diff --git a/code/g3soft-libs/docs/examples/button-group/variant.vue b/code/g3soft-libs/docs/examples/button-group/variant.vue
new file mode 100644
index 00000000..c7e54b6d
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/button-group/variant.vue
@@ -0,0 +1,28 @@
+<script setup lang="ts">
+// 组内按钮仍各自保留 type / size；混排时建议统一变体
+import { G3Button, G3ButtonGroup, G3Space } from '@g3soft/ui'
+import { AlignCenter, AlignLeft, AlignRight } from '@lucide/vue'
+</script>
+
+<template>
+  <G3Space direction="vertical" :size="12" style="display: flex">
+    <G3ButtonGroup>
+      <G3Button type="outline">描边组</G3Button>
+      <G3Button type="outline">描边组</G3Button>
+      <G3Button type="outline">描边组</G3Button>
+    </G3ButtonGroup>
+
+    <!-- 图标工具条：只保留首尾圆角 -->
+    <G3ButtonGroup>
+      <G3Button type="icon" aria-label="左对齐"><template #icon><AlignLeft /></template></G3Button>
+      <G3Button type="icon" aria-label="居中"><template #icon><AlignCenter /></template></G3Button>
+      <G3Button type="icon" aria-label="右对齐"><template #icon><AlignRight /></template></G3Button>
+    </G3ButtonGroup>
+
+    <G3ButtonGroup>
+      <G3Button size="small" type="outline">小号</G3Button>
+      <G3Button size="small" type="outline">小号</G3Button>
+      <G3Button size="small" type="outline">小号</G3Button>
+    </G3ButtonGroup>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/button-group/vertical.vue b/code/g3soft-libs/docs/examples/button-group/vertical.vue
new file mode 100644
index 00000000..b90d6062
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/button-group/vertical.vue
@@ -0,0 +1,12 @@
+<script setup lang="ts">
+// orientation="vertical"：纵向贴合，组内按钮等宽
+import { G3Button, G3ButtonGroup } from '@g3soft/ui'
+</script>
+
+<template>
+  <G3ButtonGroup orientation="vertical" style="width: 140px">
+    <G3Button type="outline">上传</G3Button>
+    <G3Button type="outline">下载</G3Button>
+    <G3Button type="outline">分享</G3Button>
+  </G3ButtonGroup>
+</template>
diff --git a/code/g3soft-libs/docs/examples/button/basic.vue b/code/g3soft-libs/docs/examples/button/basic.vue
index 25f4e0b4..e46bf72e 100644
--- a/code/g3soft-libs/docs/examples/button/basic.vue
+++ b/code/g3soft-libs/docs/examples/button/basic.vue
@@ -1,8 +1,8 @@
 <script setup lang="ts">
+// 最基础的用法：内容写在默认插槽，type 不传时是 primary
 import { G3Button } from '@g3soft/ui'
 </script>
 
 <template>
-  <G3Button>默认按钮</G3Button>
-  <G3Button type="primary">主要按钮</G3Button>
+  <G3Button>保存</G3Button>
 </template>
diff --git a/code/g3soft-libs/docs/examples/button/block.vue b/code/g3soft-libs/docs/examples/button/block.vue
index 1c936a41..7648553c 100644
--- a/code/g3soft-libs/docs/examples/button/block.vue
+++ b/code/g3soft-libs/docs/examples/button/block.vue
@@ -1,15 +1,13 @@
 <script setup lang="ts">
-import { G3Button } from '@g3soft/ui'
+// block：占满父容器宽度，常用于抽屉底部动作区
+import { G3Button, G3Space } from '@g3soft/ui'
 </script>
 
 <template>
-  <div class="demo-block">
-    <G3Button type="primary" block>撑满宽度</G3Button>
+  <div style="width: 320px; padding: 16px; border: 1px solid #d9d9d9; border-radius: 8px">
+    <G3Space direction="vertical" :size="8" style="display: flex">
+      <G3Button block>占满整行</G3Button>
+      <G3Button type="outline" block>占满整行（描边）</G3Button>
+    </G3Space>
   </div>
 </template>
-
-<style scoped>
-.demo-block {
-  width: 100%;
-}
-</style>
diff --git a/code/g3soft-libs/docs/examples/button/disabled.vue b/code/g3soft-libs/docs/examples/button/disabled.vue
new file mode 100644
index 00000000..51e8c690
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/button/disabled.vue
@@ -0,0 +1,14 @@
+<script setup lang="ts">
+// disabled 是原生禁用：不触发 click、不参与 Tab 焦点
+import { G3Button, G3Space } from '@g3soft/ui'
+</script>
+
+<template>
+  <G3Space :size="[12, 12]" align="center" wrap>
+    <G3Button disabled>主操作</G3Button>
+    <G3Button type="secondary" disabled>次要操作</G3Button>
+    <G3Button type="outline" disabled>描边</G3Button>
+    <G3Button type="danger" disabled>删除</G3Button>
+    <G3Button type="link" disabled>链接</G3Button>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/button/event.vue b/code/g3soft-libs/docs/examples/button/event.vue
new file mode 100644
index 00000000..0678596d
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/button/event.vue
@@ -0,0 +1,22 @@
+<script setup lang="ts">
+// click 回传原生 MouseEvent：可以读修饰键，也可以阻止默认行为
+import { ref } from 'vue'
+import { G3Button, G3Space } from '@g3soft/ui'
+
+const last = ref('暂无')
+
+function handleClick(event: MouseEvent) {
+  const withKey = event.ctrlKey || event.metaKey ? '（按住了 Ctrl/Cmd）' : ''
+  last.value = `点击${withKey} @ ${event.clientX},${event.clientY}`
+}
+</script>
+
+<template>
+  <G3Space direction="vertical" :size="12" style="display: flex">
+    <G3Space :size="8">
+      <G3Button @click="handleClick">点我（可按住 Ctrl）</G3Button>
+      <G3Button type="outline" @click="handleClick">也是点我</G3Button>
+    </G3Space>
+    <span style="color: #6b7280; font-size: 13px">最近一次：{{ last }}</span>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/button/global-defaults.vue b/code/g3soft-libs/docs/examples/button/global-defaults.vue
new file mode 100644
index 00000000..c721d1f4
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/button/global-defaults.vue
@@ -0,0 +1,21 @@
+<script setup lang="ts">
+// 全局默认值：显式 prop > componentDefaults > 组件内置默认
+import { G3Button, G3ConfigProvider, G3Space } from '@g3soft/ui'
+</script>
+
+<template>
+  <G3Space direction="vertical" :size="12" style="display: flex">
+    <!-- 默认：primary / medium -->
+    <G3Space :size="8">
+      <G3Button>默认变体</G3Button>
+    </G3Space>
+
+    <!-- 子树内所有按钮默认变成 outline / small，显式传 type 仍然优先 -->
+    <G3ConfigProvider :component-defaults="{ button: { type: 'outline', size: 'small' } }">
+      <G3Space :size="8" align="center">
+        <G3Button>继承全局默认</G3Button>
+        <G3Button type="primary" size="large">显式 prop 优先</G3Button>
+      </G3Space>
+    </G3ConfigProvider>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/button/html-type.vue b/code/g3soft-libs/docs/examples/button/html-type.vue
new file mode 100644
index 00000000..e9f551f7
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/button/html-type.vue
@@ -0,0 +1,32 @@
+<script setup lang="ts">
+// htmlType：表单内的提交与重置。默认是 button，所以表单里不会意外提交
+import { reactive } from 'vue'
+import { G3Button, G3Form, G3FormItem, G3Input, G3Message, G3Space } from '@g3soft/ui'
+
+const model = reactive({ name: '' })
+
+function onSubmit(values: Record<string, unknown>) {
+  G3Message.success(`已提交：${JSON.stringify(values)}`)
+}
+
+function onReset() {
+  model.name = ''
+  G3Message.info('已重置')
+}
+</script>
+
+<template>
+  <G3Form :model="model" :label-width="64" style="max-width: 360px" @submit="onSubmit" @reset="onReset">
+    <G3FormItem name="name" label="名称">
+      <G3Input v-model="model.name" placeholder="输入后回车提交" />
+    </G3FormItem>
+
+    <G3FormItem>
+      <G3Space :size="8">
+        <G3Button html-type="submit">提交</G3Button>
+        <G3Button html-type="reset" type="outline">重置</G3Button>
+        <G3Button html-type="button" type="ghost">普通按钮</G3Button>
+      </G3Space>
+    </G3FormItem>
+  </G3Form>
+</template>
diff --git a/code/g3soft-libs/docs/examples/button/icon.vue b/code/g3soft-libs/docs/examples/button/icon.vue
index bdd036a9..dfe4226e 100644
--- a/code/g3soft-libs/docs/examples/button/icon.vue
+++ b/code/g3soft-libs/docs/examples/button/icon.vue
@@ -1,11 +1,27 @@
 <script setup lang="ts">
-import { G3Button } from '@g3soft/ui'
+// #icon 插槽放图标；纯图标按钮用 type="icon"，并补 aria-label
+import { G3Button, G3Space } from '@g3soft/ui'
+import { Plus, Search, Trash2 } from '@lucide/vue'
 </script>
 
 <template>
-  <G3Button type="primary">
-    <template #icon>+</template>
-    新增
-  </G3Button>
-  <G3Button icon-only title="搜索">🔍</G3Button>
+  <G3Space :size="[12, 12]" align="center" wrap>
+    <G3Button>
+      <template #icon><Plus /></template>
+      新增
+    </G3Button>
+
+    <!-- 纯图标按钮：没有文字，必须给 aria-label -->
+    <G3Button type="icon" aria-label="搜索">
+      <template #icon><Search /></template>
+    </G3Button>
+
+    <G3Button type="icon" size="small" aria-label="删除">
+      <template #icon><Trash2 /></template>
+    </G3Button>
+
+    <G3Button type="icon" size="large" aria-label="新增">
+      <template #icon><Plus /></template>
+    </G3Button>
+  </G3Space>
 </template>
diff --git a/code/g3soft-libs/docs/examples/button/loading.vue b/code/g3soft-libs/docs/examples/button/loading.vue
new file mode 100644
index 00000000..bc6ef1d2
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/button/loading.vue
@@ -0,0 +1,30 @@
+<script setup lang="ts">
+// loading 会拦截 click，所以它同时就是「防重复提交」开关
+import { ref } from 'vue'
+import { G3Button, G3Message, G3Space } from '@g3soft/ui'
+
+const submitting = ref(false)
+
+async function handleSubmit() {
+  if (submitting.value) return
+  submitting.value = true
+  try {
+    await new Promise((resolve) => setTimeout(resolve, 1200))
+    G3Message.success('提交成功')
+  } finally {
+    submitting.value = false
+  }
+}
+</script>
+
+<template>
+  <G3Space :size="[12, 12]" align="center" wrap>
+    <G3Button :loading="submitting" @click="handleSubmit">
+      {{ submitting ? '提交中' : '提交' }}
+    </G3Button>
+
+    <!-- 只是展示加载态：任何变体都可以加载 -->
+    <G3Button type="outline" loading>加载中</G3Button>
+    <G3Button type="ghost" loading>加载中</G3Button>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/button/size.vue b/code/g3soft-libs/docs/examples/button/size.vue
index ab356e50..48f15e03 100644
--- a/code/g3soft-libs/docs/examples/button/size.vue
+++ b/code/g3soft-libs/docs/examples/button/size.vue
@@ -1,9 +1,12 @@
 <script setup lang="ts">
-import { G3Button } from '@g3soft/ui'
+// 3 档尺寸：small 24px / medium 32px（默认）/ large 40px
+import { G3Button, G3Space } from '@g3soft/ui'
 </script>
 
 <template>
-  <G3Button type="primary" size="small">小</G3Button>
-  <G3Button type="primary">中</G3Button>
-  <G3Button type="primary" size="large">大</G3Button>
+  <G3Space :size="[12, 12]" align="center" wrap>
+    <G3Button size="small">小号</G3Button>
+    <G3Button size="medium">默认</G3Button>
+    <G3Button size="large">大号</G3Button>
+  </G3Space>
 </template>
diff --git a/code/g3soft-libs/docs/examples/button/state.vue b/code/g3soft-libs/docs/examples/button/state.vue
deleted file mode 100644
index 7f670dbe..00000000
--- a/code/g3soft-libs/docs/examples/button/state.vue
+++ /dev/null
@@ -1,20 +0,0 @@
-<script setup lang="ts">
-import { ref } from 'vue'
-import { G3Button } from '@g3soft/ui'
-
-const loading = ref(false)
-
-function handleAsync() {
-  if (loading.value) return
-  loading.value = true
-  setTimeout(() => {
-    loading.value = false
-  }, 1500)
-}
-</script>
-
-<template>
-  <G3Button type="primary" :loading="loading" @click="handleAsync">点击加载</G3Button>
-  <G3Button disabled>禁用</G3Button>
-  <G3Button type="primary" disabled>禁用（主要）</G3Button>
-</template>
diff --git a/code/g3soft-libs/docs/examples/button/type.vue b/code/g3soft-libs/docs/examples/button/type.vue
deleted file mode 100644
index c707395b..00000000
--- a/code/g3soft-libs/docs/examples/button/type.vue
+++ /dev/null
@@ -1,11 +0,0 @@
-<script setup lang="ts">
-import { G3Button } from '@g3soft/ui'
-</script>
-
-<template>
-  <G3Button type="success">成功按钮</G3Button>
-  <G3Button type="warning">警告按钮</G3Button>
-  <G3Button type="danger">危险按钮</G3Button>
-  <G3Button type="text">文字按钮</G3Button>
-  <G3Button type="link">链接按钮</G3Button>
-</template>
diff --git a/code/g3soft-libs/docs/examples/button/variant.vue b/code/g3soft-libs/docs/examples/button/variant.vue
new file mode 100644
index 00000000..d7886e4b
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/button/variant.vue
@@ -0,0 +1,16 @@
+<script setup lang="ts">
+// 8 种视觉变体：按操作重要性选择，一屏通常只保留一个 primary
+import { G3Button, G3Space } from '@g3soft/ui'
+</script>
+
+<template>
+  <G3Space :size="[12, 12]" wrap>
+    <G3Button type="primary">主操作</G3Button>
+    <G3Button type="secondary">次要操作</G3Button>
+    <G3Button type="outline">描边</G3Button>
+    <G3Button type="ghost">低强调</G3Button>
+    <G3Button type="danger">删除</G3Button>
+    <G3Button type="danger-outline">危险（描边）</G3Button>
+    <G3Button type="link">链接按钮</G3Button>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/checkbox/basic.vue b/code/g3soft-libs/docs/examples/checkbox/basic.vue
new file mode 100644
index 00000000..ad995f31
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/checkbox/basic.vue
@@ -0,0 +1,14 @@
+<script setup lang="ts">
+// 单选布尔值：v-model 绑 boolean
+import { ref } from 'vue'
+import { G3Checkbox } from '@g3soft/ui'
+
+const agreed = ref(false)
+</script>
+
+<template>
+  <div>
+    <G3Checkbox v-model="agreed">我已阅读并同意服务条款</G3Checkbox>
+    <p style="margin: 8px 0 0; font-size: 13px; color: #6b7280">agreed = {{ agreed }}</p>
+  </div>
+</template>
diff --git a/code/g3soft-libs/docs/examples/checkbox/disabled.vue b/code/g3soft-libs/docs/examples/checkbox/disabled.vue
new file mode 100644
index 00000000..ab3f56b5
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/checkbox/disabled.vue
@@ -0,0 +1,12 @@
+<script setup lang="ts">
+// disabled：整项禁用；配合 Form 时由 FormItem 的校验状态驱动
+import { G3Checkbox, G3Space } from '@g3soft/ui'
+</script>
+
+<template>
+  <G3Space direction="vertical" :size="8" style="display: flex">
+    <G3Checkbox :model-value="false" disabled>未选中且禁用</G3Checkbox>
+    <G3Checkbox :model-value="true" disabled>已选中且禁用</G3Checkbox>
+    <G3Checkbox :model-value="false" :indeterminate="true" disabled>半选且禁用</G3Checkbox>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/checkbox/indeterminate.vue b/code/g3soft-libs/docs/examples/checkbox/indeterminate.vue
new file mode 100644
index 00000000..0c7e03f4
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/checkbox/indeterminate.vue
@@ -0,0 +1,55 @@
+<script setup lang="ts">
+// indeterminate：半选状态，用于「全选」与部分选中的联动
+import { computed, ref } from 'vue'
+import { G3Checkbox, G3Space } from '@g3soft/ui'
+
+const all = ref(['read', 'write'])
+const checkedKeys = ref<string[]>(['read'])
+
+const options = [
+  { label: '可读', value: 'read' },
+  { label: '可写', value: 'write' },
+  { label: '可删除', value: 'delete' },
+]
+
+const isAllChecked = computed(() => checkedKeys.value.length === options.length)
+const isIndeterminate = computed(
+  () => checkedKeys.value.length > 0 && checkedKeys.value.length < options.length,
+)
+
+function toggleAll(checked: boolean) {
+  checkedKeys.value = checked ? options.map((item) => item.value) : []
+}
+
+function toggleOne(value: string, checked: boolean) {
+  checkedKeys.value = checked
+    ? [...checkedKeys.value, value]
+    : checkedKeys.value.filter((item) => item !== value)
+}
+</script>
+
+<template>
+  <G3Space direction="vertical" :size="8" style="display: flex">
+    <!-- 全选：半选时显示减号 -->
+    <G3Checkbox
+      :model-value="isAllChecked"
+      :indeterminate="isIndeterminate"
+      @change="toggleAll"
+    >
+      全选（{{ checkedKeys.length }} / {{ options.length }}）
+    </G3Checkbox>
+
+    <div style="padding-left: 24px">
+      <G3Space direction="vertical" :size="8" style="display: flex">
+        <G3Checkbox
+          v-for="option in options"
+          :key="option.value"
+          :model-value="checkedKeys.includes(option.value)"
+          @change="(checked: boolean) => toggleOne(option.value, checked)"
+        >
+          {{ option.label }}
+        </G3Checkbox>
+      </G3Space>
+    </div>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/checkbox/rich-label.vue b/code/g3soft-libs/docs/examples/checkbox/rich-label.vue
new file mode 100644
index 00000000..726c3306
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/checkbox/rich-label.vue
@@ -0,0 +1,20 @@
+<script setup lang="ts">
+// 默认插槽可以放富内容，整块区域都可点击
+import { ref } from 'vue'
+import { G3Checkbox } from '@g3soft/ui'
+
+const notify = ref(true)
+</script>
+
+<template>
+  <div style="max-width: 320px">
+    <G3Checkbox v-model="notify" style="align-items: flex-start">
+      <span style="display: block">
+        <strong>接收构建通知</strong>
+        <span style="display: block; color: #6b7280; font-size: 12px; font-weight: 400">
+          构建失败时通过邮件与站内信通知项目成员
+        </span>
+      </span>
+    </G3Checkbox>
+  </div>
+</template>
diff --git a/code/g3soft-libs/docs/examples/date/date-basic.vue b/code/g3soft-libs/docs/examples/date/date-basic.vue
new file mode 100644
index 00000000..ada65e66
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/date/date-basic.vue
@@ -0,0 +1,14 @@
+<script setup lang="ts">
+// 最基础：v-model 绑字符串（默认格式 YYYY-MM-DD），可直接手输或点选
+import { ref } from 'vue'
+import { G3DatePicker } from '@g3soft/ui'
+
+const date = ref('')
+</script>
+
+<template>
+  <div style="width: 240px">
+    <G3DatePicker v-model="date" placeholder="选择日期" />
+    <p style="margin: 8px 0 0; font-size: 13px; color: #6b7280">绑定值：{{ date || '（空）' }}</p>
+  </div>
+</template>
diff --git a/code/g3soft-libs/docs/examples/date/date-disabled.vue b/code/g3soft-libs/docs/examples/date/date-disabled.vue
new file mode 100644
index 00000000..88f4ff03
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/date/date-disabled.vue
@@ -0,0 +1,36 @@
+<script setup lang="ts">
+// disabledDate 禁用日期；clearable 提供清除按钮；timeDefault 控制无值时的默认时间
+import { ref } from 'vue'
+import { G3DatePicker, G3Space } from '@g3soft/ui'
+
+const future = ref('')
+const locked = ref('2026-10-31 23:59:59')
+
+// 只能选今天之后（含今天）
+function disabledPast(date: Date) {
+  const today = new Date()
+  today.setHours(0, 0, 0, 0)
+  return date.getTime() < today.getTime()
+}
+
+// 禁用周末
+function disabledWeekend(date: Date) {
+  return date.getDay() === 0 || date.getDay() === 6
+}
+</script>
+
+<template>
+  <G3Space direction="vertical" :size="12" style="display: flex; width: 280px">
+    <G3DatePicker v-model="future" :disabled-date="disabledPast" placeholder="只能选今天及以后" />
+
+    <G3DatePicker
+      v-model="future"
+      :disabled-date="disabledWeekend"
+      format="YYYY-MM-DD HH:mm"
+      time-default="end"
+      placeholder="只能选工作日，默认 23:59"
+    />
+
+    <G3DatePicker v-model="locked" disabled placeholder="禁用态" />
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/date/date-format.vue b/code/g3soft-libs/docs/examples/date/date-format.vue
new file mode 100644
index 00000000..40429322
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/date/date-format.vue
@@ -0,0 +1,31 @@
+<script setup lang="ts">
+// format 决定面板粒度与展示格式；valueFormat 决定绑定值格式（不传时跟随 format）
+import { ref } from 'vue'
+import { G3DatePicker, G3Space } from '@g3soft/ui'
+
+const year = ref('')
+const month = ref('')
+const dateTime = ref('')
+const precise = ref('')
+</script>
+
+<template>
+  <G3Space direction="vertical" :size="12" style="display: flex; width: 280px">
+    <!-- 只选年份 -->
+    <G3DatePicker v-model="year" format="YYYY" placeholder="选择年份" />
+
+    <!-- 只选到月 -->
+    <G3DatePicker v-model="month" format="YYYY-MM" placeholder="选择月份" />
+
+    <!-- 日期 + 时分：面板底部出现时间列与「确定」按钮 -->
+    <G3DatePicker v-model="dateTime" format="YYYY-MM-DD HH:mm" placeholder="选择日期时间" />
+
+    <!-- 展示到分钟，但绑定值精确到秒 -->
+    <G3DatePicker
+      v-model="precise"
+      format="YYYY-MM-DD HH:mm"
+      value-format="YYYY-MM-DD HH:mm:ss"
+      placeholder="展示分钟 / 绑定秒"
+    />
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/date/manual-input.vue b/code/g3soft-libs/docs/examples/date/manual-input.vue
new file mode 100644
index 00000000..68724045
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/date/manual-input.vue
@@ -0,0 +1,19 @@
+<script setup lang="ts">
+// 手输容错：非法输入不会污染绑定值（红框 1.5 秒后回填已提交值）
+// 光标停在年/月/日/时/分段上按 ↑↓ 可以微调该段
+import { ref } from 'vue'
+import { G3DatePicker, G3Space } from '@g3soft/ui'
+
+const date = ref('2026-10-08 09:30')
+</script>
+
+<template>
+  <G3Space direction="vertical" :size="12" style="display: flex; width: 300px">
+    <G3DatePicker v-model="date" format="YYYY-MM-DD HH:mm" placeholder="试试手输 2026-13-45 看效果" />
+
+    <p style="margin: 0; font-size: 12px; color: #6b7280; line-height: 1.7">
+      支持的输入：<code>2026-10-08</code>、<code>2026/10/08</code>、<code>2026年10月8日</code>、
+      <code>2026-10-08 09:30</code>。部分输入（如只写 <code>2026-10</code>）会被补全。
+    </p>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/date/range-basic.vue b/code/g3soft-libs/docs/examples/date/range-basic.vue
new file mode 100644
index 00000000..2e58ceca
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/date/range-basic.vue
@@ -0,0 +1,21 @@
+<script setup lang="ts">
+// RangePicker：两次点击确定起止；先点的那次是起点，再点一次是终点（顺序反了会自动交换）
+import { ref } from 'vue'
+import { G3RangePicker } from '@g3soft/ui'
+
+const range = ref<string[]>(['', ''])
+const lastChange = ref('暂无')
+</script>
+
+<template>
+  <div style="width: 320px">
+    <G3RangePicker
+      v-model="range"
+      @change="(value: string[]) => (lastChange = value.join(' ~ '))"
+    />
+    <p style="margin: 8px 0 0; font-size: 13px; color: #6b7280">
+      绑定值：{{ range[0] || '（空）' }} ~ {{ range[1] || '（空）' }}
+    </p>
+    <p style="margin: 4px 0 0; font-size: 12px; color: #6b7280">change：{{ lastChange }}</p>
+  </div>
+</template>
diff --git a/code/g3soft-libs/docs/examples/date/time-select.vue b/code/g3soft-libs/docs/examples/date/time-select.vue
new file mode 100644
index 00000000..a234affd
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/date/time-select.vue
@@ -0,0 +1,28 @@
+<script setup lang="ts">
+// TimeSelect：时 / 分 / 秒三列滚轮；12 小时制会追加 am/pm 列
+import { ref } from 'vue'
+import { G3Space, G3TimeSelect } from '@g3soft/ui'
+
+const time = ref<Date | null>(null)
+const time12 = ref<Date | null>(null)
+const hourOnly = ref<Date | null>(null)
+</script>
+
+<template>
+  <G3Space :size="[24, 12]" wrap align="start">
+    <div>
+      <p style="margin: 0 0 6px; font-size: 12px; color: #6b7280">24 小时制（时/分/秒）</p>
+      <G3TimeSelect v-model="time" />
+    </div>
+
+    <div>
+      <p style="margin: 0 0 6px; font-size: 12px; color: #6b7280">12 小时制 + 小写 am/pm</p>
+      <G3TimeSelect v-model="time12" :hour12="true" :lower-meridiem="true" :fields="['hour', 'minute']" />
+    </div>
+
+    <div>
+      <p style="margin: 0 0 6px; font-size: 12px; color: #6b7280">只要小时</p>
+      <G3TimeSelect v-model="hourOnly" :fields="['hour']" />
+    </div>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/drawer/basic.vue b/code/g3soft-libs/docs/examples/drawer/basic.vue
new file mode 100644
index 00000000..059c8a73
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/drawer/basic.vue
@@ -0,0 +1,18 @@
+<script setup lang="ts">
+// 最常用：右侧滑出，v-model:open 控制，cancel 事件表示「被关闭」
+import { ref } from 'vue'
+import { G3Button, G3Drawer, G3Message } from '@g3soft/ui'
+
+const open = ref(false)
+</script>
+
+<template>
+  <div>
+    <G3Button @click="open = true">打开抽屉</G3Button>
+
+    <G3Drawer v-model:open="open" title="筛选条件" @cancel="G3Message.info('已关闭')">
+      <p style="margin: 0">抽屉内容区域可滚动，适合承载较长的表单或列表。</p>
+      <p style="margin: 8px 0 0; color: #6b7280">拖动左边缘可以调整宽度。</p>
+    </G3Drawer>
+  </div>
+</template>
diff --git a/code/g3soft-libs/docs/examples/drawer/footer.vue b/code/g3soft-libs/docs/examples/drawer/footer.vue
new file mode 100644
index 00000000..7f38f8ff
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/drawer/footer.vue
@@ -0,0 +1,32 @@
+<script setup lang="ts">
+// #footer 底部动作区；#extra 放标题下方的补充信息
+import { ref } from 'vue'
+import { G3Button, G3Drawer, G3Input, G3Space } from '@g3soft/ui'
+
+const open = ref(false)
+const keyword = ref('')
+</script>
+
+<template>
+  <div>
+    <G3Button @click="open = true">带底部动作</G3Button>
+
+    <G3Drawer v-model:open="open" title="高级筛选" :width="400">
+      <template #extra>
+        <span style="font-size: 12px; color: #6b7280">已选 2 个条件</span>
+      </template>
+
+      <G3Space direction="vertical" :size="12" style="display: flex">
+        <G3Input v-model="keyword" placeholder="关键词" />
+        <G3Input v-model="keyword" placeholder="负责人" />
+      </G3Space>
+
+      <template #footer>
+        <G3Space :size="8">
+          <G3Button type="outline" @click="open = false">重置</G3Button>
+          <G3Button @click="open = false">应用筛选</G3Button>
+        </G3Space>
+      </template>
+    </G3Drawer>
+  </div>
+</template>
diff --git a/code/g3soft-libs/docs/examples/drawer/placement.vue b/code/g3soft-libs/docs/examples/drawer/placement.vue
new file mode 100644
index 00000000..e4c5a18b
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/drawer/placement.vue
@@ -0,0 +1,25 @@
+<script setup lang="ts">
+// placement：right（默认）/ left / top / bottom，滑出的方向与缩放手柄同步
+import { ref } from 'vue'
+import { G3Button, G3Drawer, G3Space } from '@g3soft/ui'
+
+const placement = ref<'right' | 'left' | 'top' | 'bottom'>('right')
+const open = ref(false)
+
+function show(value: 'right' | 'left' | 'top' | 'bottom') {
+  placement.value = value
+  open.value = true
+}
+</script>
+
+<template>
+  <G3Space :size="[8, 8]" wrap>
+    <G3Button v-for="item in ['right', 'left', 'top', 'bottom'] as const" :key="item" type="outline" @click="show(item)">
+      {{ item }}
+    </G3Button>
+
+    <G3Drawer v-model:open="open" :title="`从 ${placement} 滑出`" :placement="placement" :width="360" :height="280">
+      左右方向用 width，上下方向用 height 控制尺寸。
+    </G3Drawer>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/drawer/size.vue b/code/g3soft-libs/docs/examples/drawer/size.vue
new file mode 100644
index 00000000..9b6cb72a
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/drawer/size.vue
@@ -0,0 +1,30 @@
+<script setup lang="ts">
+// 尺寸与可缩放：width / height 支持数字（px）或任意 CSS 长度；resizable 可关掉拖拽
+import { ref } from 'vue'
+import { G3Button, G3Drawer, G3Space } from '@g3soft/ui'
+
+const open = ref(false)
+const width = ref<number | string>(480)
+const resizable = ref(true)
+</script>
+
+<template>
+  <G3Space direction="vertical" :size="12" style="display: flex">
+    <G3Space :size="8">
+      <G3Button size="small" type="outline" @click="width = 360">窄（360px）</G3Button>
+      <G3Button size="small" type="outline" @click="width = 640">宽（640px）</G3Button>
+      <G3Button size="small" type="outline" @click="width = '60%'">百分比（60%）</G3Button>
+      <G3Button size="small" type="ghost" @click="resizable = !resizable">
+        拖拽：{{ resizable ? '开' : '关' }}
+      </G3Button>
+    </G3Space>
+
+    <div>
+      <G3Button @click="open = true">打开（宽 {{ width }}）</G3Button>
+    </div>
+
+    <G3Drawer v-model:open="open" title="尺寸可配置" :width="width" :resizable="resizable">
+      当前宽度：{{ width }}。拖拽左边缘时只会改变宽度，不会影响高度。
+    </G3Drawer>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/dropdown/basic.vue b/code/g3soft-libs/docs/examples/dropdown/basic.vue
new file mode 100644
index 00000000..3ed6b072
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/dropdown/basic.vue
@@ -0,0 +1,21 @@
+<script setup lang="ts">
+// 最常用：items 传数组，点击项通过 click 事件回传 { key, item }
+import { G3Button, G3Dropdown, G3Message } from '@g3soft/ui'
+
+const items = [
+  { key: 'edit', label: '编辑' },
+  { key: 'copy', label: '复制' },
+  { divider: true },
+  { key: 'delete', label: '删除', danger: true },
+]
+
+function onClick(payload: { key?: string | number }) {
+  G3Message.info(`点击了 ${String(payload.key)}`)
+}
+</script>
+
+<template>
+  <G3Dropdown :items="items" @click="onClick">
+    <G3Button type="outline">操作</G3Button>
+  </G3Dropdown>
+</template>
diff --git a/code/g3soft-libs/docs/examples/dropdown/declarative.vue b/code/g3soft-libs/docs/examples/dropdown/declarative.vue
new file mode 100644
index 00000000..448b6709
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/dropdown/declarative.vue
@@ -0,0 +1,19 @@
+<script setup lang="ts">
+// 声明式：默认插槽里写 G3DropdownItem（不渲染 DOM，只作为数据载体被收集）
+import { G3Button, G3Dropdown, G3DropdownItem, G3Message } from '@g3soft/ui'
+import { Copy, Pencil, Trash2 } from '@lucide/vue'
+</script>
+
+<template>
+  <G3Dropdown @click="(payload: { key?: string | number }) => G3Message.info(String(payload.key))">
+    <!-- #trigger 显式指定触发器，避免和菜单项混在默认插槽里 -->
+    <template #trigger>
+      <G3Button type="outline">声明式菜单</G3Button>
+    </template>
+
+    <G3DropdownItem item-key="edit" label="编辑" :icon="Pencil" />
+    <G3DropdownItem item-key="copy" label="复制" :icon="Copy" />
+    <G3DropdownItem divider />
+    <G3DropdownItem item-key="delete" label="删除" :icon="Trash2" danger />
+  </G3Dropdown>
+</template>
diff --git a/code/g3soft-libs/docs/examples/dropdown/header-slot.vue b/code/g3soft-libs/docs/examples/dropdown/header-slot.vue
new file mode 100644
index 00000000..8277e61d
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/dropdown/header-slot.vue
@@ -0,0 +1,56 @@
+<script setup lang="ts">
+// #header 放账号卡片之类的富头部；#menu 是完全自定义菜单的逃生舱
+import { G3Button, G3Dropdown, G3DropdownItem, G3Space } from '@g3soft/ui'
+import { LogOut, Settings, User } from '@lucide/vue'
+</script>
+
+<template>
+  <G3Space :size="16" wrap>
+    <G3Dropdown placement="bottom-end">
+      <template #trigger>
+        <G3Button type="outline">带头部的菜单</G3Button>
+      </template>
+
+      <!-- 头部：不参与键盘导航 -->
+      <template #header>
+        <div style="display: flex; gap: 8px; align-items: center">
+          <div
+            style="
+              width: 28px;
+              height: 28px;
+              border-radius: 50%;
+              background: rgba(24, 24, 27, 0.08);
+              display: grid;
+              place-items: center;
+              font-size: 12px;
+            "
+          >
+            ZS
+          </div>
+          <div>
+            <div style="font-size: 13px; font-weight: 600">张三</div>
+            <div style="font-size: 12px; color: #6b7280">zhangsan@g3soft.dev</div>
+          </div>
+        </div>
+      </template>
+
+      <G3DropdownItem item-key="profile" label="个人资料" :icon="User" />
+      <G3DropdownItem item-key="settings" label="账号设置" :icon="Settings" />
+      <G3DropdownItem divider />
+      <G3DropdownItem item-key="logout" label="退出登录" :icon="LogOut" danger />
+    </G3Dropdown>
+
+    <!-- #menu 逃生舱：菜单结构完全自定义时使用 -->
+    <G3Dropdown trigger="click">
+      <template #trigger>
+        <G3Button type="ghost">#menu 逃生舱</G3Button>
+      </template>
+      <template #menu="{ close }">
+        <div style="padding: 8px; font-size: 13px">
+          这里可以放任意结构
+          <G3Button size="small" type="link" @click="close()">关闭</G3Button>
+        </div>
+      </template>
+    </G3Dropdown>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/dropdown/item-types.vue b/code/g3soft-libs/docs/examples/dropdown/item-types.vue
new file mode 100644
index 00000000..0ff2463e
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/dropdown/item-types.vue
@@ -0,0 +1,33 @@
+<script setup lang="ts">
+// 每一项都支持：分组标签、快捷键提示、禁用、危险色、子菜单
+import { G3Button, G3Dropdown } from '@g3soft/ui'
+import { Download, Share2, Upload } from '@lucide/vue'
+
+const items = [
+  { type: 'label', label: '文件操作' },
+  { key: 'new', label: '新建', shortcut: '⌘ N' },
+  { key: 'open', label: '打开', shortcut: '⌘ O' },
+  { divider: true },
+  { type: 'label', label: '导出' },
+  {
+    key: 'export',
+    label: '导出为',
+    icon: Download,
+    children: [
+      { key: 'pdf', label: 'PDF' },
+      { key: 'excel', label: 'Excel' },
+      { key: 'csv', label: 'CSV', disabled: true },
+    ],
+  },
+  { key: 'upload', label: '上传替换', icon: Upload },
+  { key: 'share', label: '分享给他人', icon: Share2, disabled: true },
+  { divider: true },
+  { key: 'delete', label: '彻底删除', danger: true },
+]
+</script>
+
+<template>
+  <G3Dropdown :items="items">
+    <G3Button type="outline">完整菜单</G3Button>
+  </G3Dropdown>
+</template>
diff --git a/code/g3soft-libs/docs/examples/dropdown/keyboard.vue b/code/g3soft-libs/docs/examples/dropdown/keyboard.vue
new file mode 100644
index 00000000..1c6efb6c
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/dropdown/keyboard.vue
@@ -0,0 +1,27 @@
+<script setup lang="ts">
+// 键盘：点击触发器后 ↑↓ 移动、Home/End 跳首尾、Enter 选中、Esc 关闭
+import { ref } from 'vue'
+import { G3Button, G3Dropdown, G3Message } from '@g3soft/ui'
+
+const open = ref(false)
+
+const items = [
+  { key: 'view', label: '查看详情' },
+  { key: 'download', label: '下载' },
+  { key: 'rename', label: '重命名' },
+  { key: 'move', label: '移动到…' },
+]
+</script>
+
+<template>
+  <div style="display: flex; align-items: center; gap: 12px">
+    <G3Dropdown v-model:open="open" :items="items" placement="bottom-start">
+      <template #trigger>
+        <G3Button type="outline">按键盘操作</G3Button>
+      </template>
+    </G3Dropdown>
+    <span style="font-size: 12px; color: #6b7280">
+      菜单打开后按 ↑↓ / Enter 试试（当前 {{ open ? '已打开' : '已关闭' }}）
+    </span>
+  </div>
+</template>
diff --git a/code/g3soft-libs/docs/examples/dropdown/trigger.vue b/code/g3soft-libs/docs/examples/dropdown/trigger.vue
new file mode 100644
index 00000000..827d2c5f
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/dropdown/trigger.vue
@@ -0,0 +1,23 @@
+<script setup lang="ts">
+// trigger：click（默认）/ hover（下拉菜单栏）/ contextmenu（右键，常用于表格行 / 树节点）
+import { G3Button, G3Dropdown, G3Space } from '@g3soft/ui'
+
+const items = [
+  { key: 'open', label: '打开' },
+  { key: 'rename', label: '重命名' },
+]
+</script>
+
+<template>
+  <G3Space :size="[16, 12]" align="center" wrap>
+    <G3Dropdown :items="items" trigger="hover">
+      <G3Button type="outline">hover 触发</G3Button>
+    </G3Dropdown>
+
+    <G3Dropdown :items="items" trigger="contextmenu" :offset="2">
+      <div style="padding: 10px 20px; border: 1px dashed #d9d9d9; border-radius: 6px">
+        在此处右键
+      </div>
+    </G3Dropdown>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/form/basic.vue b/code/g3soft-libs/docs/examples/form/basic.vue
new file mode 100644
index 00000000..602e39dd
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/form/basic.vue
@@ -0,0 +1,26 @@
+<script setup lang="ts">
+// 最小可用表单：model 提供数据、FormItem 的 name 对应字段、rules 声明校验
+import { reactive } from 'vue'
+import { G3Button, G3Form, G3FormItem, G3Input, G3Message } from '@g3soft/ui'
+
+const model = reactive({ name: '' })
+
+const rules = {
+  name: [{ required: true }],
+}
+
+function onSubmit(values: Record<string, unknown>) {
+  G3Message.success(`提交成功：${JSON.stringify(values)}`)
+}
+</script>
+
+<template>
+  <G3Form :model="model" :rules="rules" :label-width="72" style="max-width: 360px" @submit="onSubmit">
+    <G3FormItem name="name" label="名称">
+      <G3Input v-model="model.name" placeholder="请输入名称" />
+    </G3FormItem>
+    <G3FormItem>
+      <G3Button html-type="submit">提交</G3Button>
+    </G3FormItem>
+  </G3Form>
+</template>
diff --git a/code/g3soft-libs/docs/examples/form/grid.vue b/code/g3soft-libs/docs/examples/form/grid.vue
new file mode 100644
index 00000000..e1facfdb
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/form/grid.vue
@@ -0,0 +1,46 @@
+<script setup lang="ts">
+// 多列表单：columns 开启网格，FormItem 用 span 跨列、lineStart 强制换行
+import { reactive } from 'vue'
+import { G3Button, G3Form, G3FormItem, G3Input, G3Select } from '@g3soft/ui'
+
+const model = reactive({
+  name: '',
+  code: '',
+  owner: undefined as number | undefined,
+  description: '',
+})
+</script>
+
+<template>
+  <G3Form
+    :model="model"
+    layout="vertical"
+    :columns="2"
+    :gap="{ row: 16, col: 16 }"
+    style="max-width: 640px"
+    @submit="() => {}"
+  >
+    <G3FormItem name="name" label="项目名称">
+      <G3Input v-model="model.name" />
+    </G3FormItem>
+    <G3FormItem name="code" label="项目标识">
+      <G3Input v-model="model.code" />
+    </G3FormItem>
+    <G3FormItem name="owner" label="负责人">
+      <G3Select
+        v-model="model.owner"
+        :options="[
+          { label: '张三', value: 1 },
+          { label: '李四', value: 2 },
+        ]"
+      />
+    </G3FormItem>
+    <!-- span 2：占满整行 -->
+    <G3FormItem name="description" label="项目描述" :span="2">
+      <G3Input v-model="model.description" type="textarea" :rows="3" />
+    </G3FormItem>
+    <G3FormItem :span="2">
+      <G3Button html-type="submit">保存</G3Button>
+    </G3FormItem>
+  </G3Form>
+</template>
diff --git a/code/g3soft-libs/docs/examples/form/group.vue b/code/g3soft-libs/docs/examples/form/group.vue
new file mode 100644
index 00000000..e3caddf4
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/form/group.vue
@@ -0,0 +1,33 @@
+<script setup lang="ts">
+// FormGroup：在长表单里做「分组 + 组内独立列数」，组内覆盖组外布局
+import { reactive } from 'vue'
+import { G3Button, G3Form, G3FormGroup, G3FormItem, G3Input } from '@g3soft/ui'
+
+const model = reactive({ host: '', port: '', username: '', password: '' })
+</script>
+
+<template>
+  <G3Form :model="model" layout="vertical" style="max-width: 620px" @submit="() => {}">
+    <G3FormGroup title="服务地址" :columns="2">
+      <G3FormItem name="host" label="主机">
+        <G3Input v-model="model.host" />
+      </G3FormItem>
+      <G3FormItem name="port" label="端口">
+        <G3Input v-model="model.port" type="number" />
+      </G3FormItem>
+    </G3FormGroup>
+
+    <G3FormGroup title="认证信息" :columns="2">
+      <G3FormItem name="username" label="账号">
+        <G3Input v-model="model.username" />
+      </G3FormItem>
+      <G3FormItem name="password" label="密码">
+        <G3Input v-model="model.password" type="password" />
+      </G3FormItem>
+    </G3FormGroup>
+
+    <G3FormItem>
+      <G3Button html-type="submit">连接</G3Button>
+    </G3FormItem>
+  </G3Form>
+</template>
diff --git a/code/g3soft-libs/docs/examples/form/layout.vue b/code/g3soft-libs/docs/examples/form/layout.vue
new file mode 100644
index 00000000..829310b9
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/form/layout.vue
@@ -0,0 +1,37 @@
+<script setup lang="ts">
+// layout：horizontal 标签在左（默认，可配 labelAlign / labelWidth）；vertical 标签在上
+import { reactive } from 'vue'
+import { G3Form, G3FormItem, G3Input, G3Space } from '@g3soft/ui'
+
+const model = reactive({ name: '示例', desc: '' })
+</script>
+
+<template>
+  <G3Space direction="vertical" :size="24" style="display: flex">
+    <!-- 横向：labelAlign="right" + 120px 定宽，右侧控件对齐 -->
+    <G3Form
+      :model="model"
+      layout="horizontal"
+      label-align="right"
+      :label-width="120"
+      style="max-width: 420px"
+    >
+      <G3FormItem name="name" label="项目名称">
+        <G3Input v-model="model.name" />
+      </G3FormItem>
+      <G3FormItem name="desc" label="项目描述" extra="最多 50 字">
+        <G3Input v-model="model.desc" />
+      </G3FormItem>
+    </G3Form>
+
+    <!-- 纵向：label 在上，适合狭窄容器 -->
+    <G3Form :model="model" layout="vertical" style="max-width: 420px">
+      <G3FormItem name="name" label="项目名称">
+        <G3Input v-model="model.name" />
+      </G3FormItem>
+      <G3FormItem name="desc" label="项目描述">
+        <G3Input v-model="model.desc" type="textarea" :rows="3" />
+      </G3FormItem>
+    </G3Form>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/form/rules.vue b/code/g3soft-libs/docs/examples/form/rules.vue
new file mode 100644
index 00000000..c0709706
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/form/rules.vue
@@ -0,0 +1,61 @@
+<script setup lang="ts">
+// 规则字段：required / type / pattern / len / min / max / message / validator
+import { reactive } from 'vue'
+import { G3Button, G3Form, G3FormItem, G3Input, G3Message, G3Select } from '@g3soft/ui'
+
+const model = reactive({ username: '', email: '', age: '', slug: '', role: undefined as number | undefined })
+
+const rules = {
+  // required：为空时提示「用户名不能为空」
+  username: [{ required: true, min: 3, max: 12 }],
+  // type：内置 string / number / integer / email / url
+  email: [{ required: true, type: 'email' }],
+  // validator：返回 true / undefined 通过；返回 false 用 message，返回字符串则作为错误文案
+  age: [
+    {
+      validator: (value: unknown) =>
+        Number(value) >= 18 ? true : '必须年满 18 岁',
+    },
+  ],
+  // pattern：正则
+  slug: [{ pattern: /^[a-z0-9-]+$/, message: '只能包含小写字母、数字与连字符' }],
+  // 自定义动态文案：message 传函数
+  role: [{ required: true, message: () => '请选择角色' }],
+}
+</script>
+
+<template>
+  <G3Form
+    :model="model"
+    :rules="rules"
+    :label-width="88"
+    style="max-width: 420px"
+    @submit="(values: Record<string, unknown>) => G3Message.success(JSON.stringify(values))"
+  >
+    <G3FormItem name="username" label="用户名">
+      <G3Input v-model="model.username" placeholder="3-12 个字符" />
+    </G3FormItem>
+    <G3FormItem name="email" label="邮箱">
+      <G3Input v-model="model.email" placeholder="name@example.com" />
+    </G3FormItem>
+    <G3FormItem name="age" label="年龄">
+      <G3Input v-model="model.age" type="number" />
+    </G3FormItem>
+    <G3FormItem name="slug" label="标识">
+      <G3Input v-model="model.slug" placeholder="user-profile" />
+    </G3FormItem>
+    <G3FormItem name="role" label="角色">
+      <G3Select
+        v-model="model.role"
+        :options="[
+          { label: '管理员', value: 1 },
+          { label: '成员', value: 2 },
+        ]"
+        placeholder="请选择"
+      />
+    </G3FormItem>
+    <G3FormItem>
+      <G3Button html-type="submit">提交</G3Button>
+    </G3FormItem>
+  </G3Form>
+</template>
diff --git a/code/g3soft-libs/docs/examples/form/submit.vue b/code/g3soft-libs/docs/examples/form/submit.vue
new file mode 100644
index 00000000..d62d3a85
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/form/submit.vue
@@ -0,0 +1,47 @@
+<script setup lang="ts">
+// 提交与失败：submit 只在全部通过时触发；submitFailed 带上出错字段
+import { reactive, ref } from 'vue'
+import { G3Button, G3Form, G3FormItem, G3Input, G3Message, G3Space } from '@g3soft/ui'
+
+const model = reactive({ name: '', email: '' })
+const rules = {
+  name: [{ required: true }],
+  email: [{ required: true, type: 'email' }],
+}
+
+const formRef = ref<InstanceType<typeof G3Form> | null>(null)
+
+async function validateManually() {
+  const errors = await formRef.value?.validateAll()
+  if (!errors?.length) G3Message.success('校验通过')
+  else G3Message.error(`有 ${errors.length} 个字段未通过`)
+}
+</script>
+
+<template>
+  <G3Space direction="vertical" :size="12" style="display: flex; max-width: 420px">
+    <G3Form
+      ref="formRef"
+      :model="model"
+      :rules="rules"
+      :label-width="72"
+      @submit="() => G3Message.success('全部通过，已提交')"
+      @submit-failed="(payload: { errorFields: unknown[] }) => G3Message.error(`失败：${payload.errorFields.length} 个字段`)"
+      @reset="G3Message.info('已重置')"
+    >
+      <G3FormItem name="name" label="名称">
+        <G3Input v-model="model.name" />
+      </G3FormItem>
+      <G3FormItem name="email" label="邮箱">
+        <G3Input v-model="model.email" />
+      </G3FormItem>
+      <G3FormItem>
+        <G3Space :size="8">
+          <G3Button html-type="submit">提交</G3Button>
+          <G3Button html-type="reset" type="outline">重置</G3Button>
+          <G3Button type="ghost" @click="validateManually">手动校验</G3Button>
+        </G3Space>
+      </G3FormItem>
+    </G3Form>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/form/validate-trigger.vue b/code/g3soft-libs/docs/examples/form/validate-trigger.vue
new file mode 100644
index 00000000..2598803b
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/form/validate-trigger.vue
@@ -0,0 +1,38 @@
+<script setup lang="ts">
+// validateTrigger：change（默认，输入即校验）或 blur（失焦才校验，输入过程不打扰）
+import { reactive } from 'vue'
+import { G3Form, G3FormItem, G3Input, G3Space } from '@g3soft/ui'
+
+const changeModel = reactive({ code: '' })
+const blurModel = reactive({ code: '' })
+
+const rules = { code: [{ required: true, min: 4, message: '至少 4 位' }] }
+</script>
+
+<template>
+  <G3Space :size="24" wrap>
+    <G3Form
+      :model="changeModel"
+      :rules="rules"
+      validate-trigger="change"
+      layout="vertical"
+      style="width: 260px"
+    >
+      <G3FormItem name="code" label="change：输入即校验">
+        <G3Input v-model="changeModel.code" placeholder="试试输入 1 个字符" />
+      </G3FormItem>
+    </G3Form>
+
+    <G3Form
+      :model="blurModel"
+      :rules="rules"
+      validate-trigger="blur"
+      layout="vertical"
+      style="width: 260px"
+    >
+      <G3FormItem name="code" label="blur：失焦才校验">
+        <G3Input v-model="blurModel.code" placeholder="输入过程不报错" />
+      </G3FormItem>
+    </G3Form>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/grid/align.vue b/code/g3soft-libs/docs/examples/grid/align.vue
new file mode 100644
index 00000000..59c7b180
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/grid/align.vue
@@ -0,0 +1,32 @@
+<script setup lang="ts">
+// align 控制交叉轴，justify 控制主轴分布
+import { G3Col, G3Row, G3Space } from '@g3soft/ui'
+</script>
+
+<template>
+  <G3Space direction="vertical" :size="20" style="display: flex">
+    <G3Row :gutter="12" align="middle" justify="space-between" style="height: 80px">
+      <G3Col :span="6"><div class="cell">span 6</div></G3Col>
+      <G3Col :span="6"><div class="cell tall">span 6（更高）</div></G3Col>
+      <G3Col :span="6"><div class="cell">span 6</div></G3Col>
+    </G3Row>
+
+    <G3Row :gutter="12" justify="center">
+      <G3Col :span="6"><div class="cell">居中</div></G3Col>
+      <G3Col :span="6"><div class="cell">居中</div></G3Col>
+    </G3Row>
+  </G3Space>
+</template>
+
+<style scoped>
+.cell {
+  padding: 12px 0;
+  border-radius: 6px;
+  background: rgba(24, 24, 27, 0.04);
+  font-size: 13px;
+  text-align: center;
+}
+.tall {
+  padding: 28px 0;
+}
+</style>
diff --git a/code/g3soft-libs/docs/examples/grid/basic.vue b/code/g3soft-libs/docs/examples/grid/basic.vue
new file mode 100644
index 00000000..4afa64b4
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/grid/basic.vue
@@ -0,0 +1,25 @@
+<script setup lang="ts">
+// 24 栅格：span 表示占几格，一行总和超过 24 会自动换行
+import { G3Col, G3Row } from '@g3soft/ui'
+</script>
+
+<template>
+  <G3Row :gutter="12">
+    <G3Col :span="24"><div class="cell">span 24</div></G3Col>
+    <G3Col :span="12"><div class="cell">span 12</div></G3Col>
+    <G3Col :span="12"><div class="cell">span 12</div></G3Col>
+    <G3Col :span="8"><div class="cell">span 8</div></G3Col>
+    <G3Col :span="8"><div class="cell">span 8</div></G3Col>
+    <G3Col :span="8"><div class="cell">span 8</div></G3Col>
+  </G3Row>
+</template>
+
+<style scoped>
+.cell {
+  padding: 12px 0;
+  border-radius: 6px;
+  background: rgba(24, 24, 27, 0.04);
+  font-size: 13px;
+  text-align: center;
+}
+</style>
diff --git a/code/g3soft-libs/docs/examples/grid/flex.vue b/code/g3soft-libs/docs/examples/grid/flex.vue
new file mode 100644
index 00000000..ed389293
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/grid/flex.vue
@@ -0,0 +1,29 @@
+<script setup lang="ts">
+// flex：数字表示 flex-grow，也可传完整 flex 简写；常用于「一侧固定、一侧自适应」
+import { G3Col, G3Row, G3Space } from '@g3soft/ui'
+</script>
+
+<template>
+  <G3Space direction="vertical" :size="20" style="display: flex">
+    <G3Row :gutter="12">
+      <G3Col :flex="'0 0 200px'"><div class="cell">固定 200px</div></G3Col>
+      <G3Col :flex="1"><div class="cell">自适应剩余空间</div></G3Col>
+    </G3Row>
+
+    <G3Row :gutter="12">
+      <G3Col :flex="1"><div class="cell">1 份</div></G3Col>
+      <G3Col :flex="2"><div class="cell">2 份</div></G3Col>
+      <G3Col :flex="1"><div class="cell">1 份</div></G3Col>
+    </G3Row>
+  </G3Space>
+</template>
+
+<style scoped>
+.cell {
+  padding: 12px 0;
+  border-radius: 6px;
+  background: rgba(24, 24, 27, 0.04);
+  font-size: 13px;
+  text-align: center;
+}
+</style>
diff --git a/code/g3soft-libs/docs/examples/grid/gutter.vue b/code/g3soft-libs/docs/examples/grid/gutter.vue
new file mode 100644
index 00000000..92201bcc
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/grid/gutter.vue
@@ -0,0 +1,33 @@
+<script setup lang="ts">
+// gutter 数字=水平垂直同值；数组=[水平, 垂直]
+import { G3Col, G3Row, G3Space } from '@g3soft/ui'
+</script>
+
+<template>
+  <G3Space direction="vertical" :size="20" style="display: flex">
+    <G3Row :gutter="16">
+      <G3Col :span="8"><div class="cell">gutter 16</div></G3Col>
+      <G3Col :span="8"><div class="cell">gutter 16</div></G3Col>
+      <G3Col :span="8"><div class="cell">gutter 16</div></G3Col>
+    </G3Row>
+
+    <G3Row :gutter="[32, 12]">
+      <G3Col :span="8"><div class="cell">水平 32</div></G3Col>
+      <G3Col :span="8"><div class="cell">水平 32</div></G3Col>
+      <G3Col :span="8"><div class="cell">水平 32</div></G3Col>
+      <G3Col :span="8"><div class="cell">垂直 12</div></G3Col>
+      <G3Col :span="8"><div class="cell">垂直 12</div></G3Col>
+      <G3Col :span="8"><div class="cell">垂直 12</div></G3Col>
+    </G3Row>
+  </G3Space>
+</template>
+
+<style scoped>
+.cell {
+  padding: 12px 0;
+  border-radius: 6px;
+  background: rgba(24, 24, 27, 0.04);
+  font-size: 13px;
+  text-align: center;
+}
+</style>
diff --git a/code/g3soft-libs/docs/examples/grid/no-wrap.vue b/code/g3soft-libs/docs/examples/grid/no-wrap.vue
new file mode 100644
index 00000000..96ef8f17
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/grid/no-wrap.vue
@@ -0,0 +1,24 @@
+<script setup lang="ts">
+// wrap=false：不换行，超出部分会被挤压（配合 flex 使用）
+import { G3Col, G3Row } from '@g3soft/ui'
+</script>
+
+<template>
+  <G3Row :gutter="12" :wrap="false">
+    <G3Col :span="8"><div class="cell">span 8</div></G3Col>
+    <G3Col :span="8"><div class="cell">span 8</div></G3Col>
+    <G3Col :span="8"><div class="cell">span 8</div></G3Col>
+    <G3Col :span="8"><div class="cell">超出 24，但不换行</div></G3Col>
+  </G3Row>
+</template>
+
+<style scoped>
+.cell {
+  padding: 12px 0;
+  border-radius: 6px;
+  background: rgba(24, 24, 27, 0.04);
+  font-size: 13px;
+  text-align: center;
+  white-space: nowrap;
+}
+</style>
diff --git a/code/g3soft-libs/docs/examples/grid/offset.vue b/code/g3soft-libs/docs/examples/grid/offset.vue
new file mode 100644
index 00000000..e4987041
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/grid/offset.vue
@@ -0,0 +1,33 @@
+<script setup lang="ts">
+// offset 左侧留空格；push / pull 做左右位移（响应式布局里的顺序微调）
+import { G3Col, G3Row, G3Space } from '@g3soft/ui'
+</script>
+
+<template>
+  <G3Space direction="vertical" :size="20" style="display: flex">
+    <G3Row :gutter="12">
+      <G3Col :span="8"><div class="cell">span 8</div></G3Col>
+      <G3Col :span="8" :offset="8"><div class="cell">span 8 / offset 8</div></G3Col>
+    </G3Row>
+
+    <G3Row :gutter="12">
+      <G3Col :span="6" :push="6"><div class="cell">push 6</div></G3Col>
+      <G3Col :span="6" :pull="6"><div class="cell">pull 6</div></G3Col>
+    </G3Row>
+
+    <G3Row :gutter="12">
+      <G3Col :span="8" :order="2"><div class="cell">order 2</div></G3Col>
+      <G3Col :span="8" :order="1"><div class="cell">order 1</div></G3Col>
+    </G3Row>
+  </G3Space>
+</template>
+
+<style scoped>
+.cell {
+  padding: 12px 0;
+  border-radius: 6px;
+  background: rgba(24, 24, 27, 0.04);
+  font-size: 13px;
+  text-align: center;
+}
+</style>
diff --git a/code/g3soft-libs/docs/examples/input/basic.vue b/code/g3soft-libs/docs/examples/input/basic.vue
new file mode 100644
index 00000000..6f136e3c
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/input/basic.vue
@@ -0,0 +1,14 @@
+<script setup lang="ts">
+// 最基础用法：v-model 双向绑定，值类型为 string
+import { ref } from 'vue'
+import { G3Input } from '@g3soft/ui'
+
+const value = ref('')
+</script>
+
+<template>
+  <div style="width: 260px">
+    <G3Input v-model="value" placeholder="请输入名称" />
+    <p style="margin: 8px 0 0; font-size: 13px; color: #6b7280">值：{{ value || '（空）' }}</p>
+  </div>
+</template>
diff --git a/code/g3soft-libs/docs/examples/input/clearable.vue b/code/g3soft-libs/docs/examples/input/clearable.vue
new file mode 100644
index 00000000..c54c4d40
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/input/clearable.vue
@@ -0,0 +1,18 @@
+<script setup lang="ts">
+// allowClear：有值时 hover / 聚焦出现清除按钮；clear 事件通知清空动作
+import { ref } from 'vue'
+import { G3Input, G3Message } from '@g3soft/ui'
+
+const keyword = ref('g3soft')
+</script>
+
+<template>
+  <div style="width: 260px">
+    <G3Input
+      v-model="keyword"
+      allow-clear
+      placeholder="输入后 hover 可见清除按钮"
+      @clear="G3Message.info('已清空')"
+    />
+  </div>
+</template>
diff --git a/code/g3soft-libs/docs/examples/input/methods.vue b/code/g3soft-libs/docs/examples/input/methods.vue
new file mode 100644
index 00000000..cb98bf88
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/input/methods.vue
@@ -0,0 +1,22 @@
+<script setup lang="ts">
+// 组件实例方法：focus（可全选）/ select / blur，用于「点击编辑」类交互
+import { ref } from 'vue'
+import { G3Button, G3Input, G3Space, type InputFocusOptions } from '@g3soft/ui'
+
+const value = ref('待编辑内容')
+const inputRef = ref<InstanceType<typeof G3Input> | null>(null)
+</script>
+
+<template>
+  <G3Space direction="vertical" :size="12" style="display: flex; width: 320px">
+    <G3Input ref="inputRef" v-model="value" />
+    <G3Space :size="8">
+      <!-- cursor: 'all' 聚焦后全选内容 -->
+      <G3Button size="small" type="outline" @click="inputRef?.focus({ cursor: 'all' } as InputFocusOptions)">
+        聚焦并全选
+      </G3Button>
+      <G3Button size="small" type="outline" @click="inputRef?.select()">仅选中</G3Button>
+      <G3Button size="small" type="outline" @click="inputRef?.blur()">失焦</G3Button>
+    </G3Space>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/input/number.vue b/code/g3soft-libs/docs/examples/input/number.vue
new file mode 100644
index 00000000..495ab6da
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/input/number.vue
@@ -0,0 +1,16 @@
+<script setup lang="ts">
+// type="number"：只允许数字与小数点，失焦时把字符串提交为 Number
+import { ref } from 'vue'
+import { G3Input } from '@g3soft/ui'
+
+const amount = ref<string | number>(12.5)
+</script>
+
+<template>
+  <div style="width: 260px">
+    <G3Input v-model="amount" type="number" placeholder="请输入金额" />
+    <p style="margin: 8px 0 0; font-size: 13px; color: #6b7280">
+      提交值：{{ amount }}，类型：{{ typeof amount }}
+    </p>
+  </div>
+</template>
diff --git a/code/g3soft-libs/docs/examples/input/password.vue b/code/g3soft-libs/docs/examples/input/password.vue
new file mode 100644
index 00000000..eee90bc9
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/input/password.vue
@@ -0,0 +1,13 @@
+<script setup lang="ts">
+// type="password"：自带显示/隐藏切换按钮
+import { ref } from 'vue'
+import { G3Input } from '@g3soft/ui'
+
+const value = ref('g3soft-2026')
+</script>
+
+<template>
+  <div style="width: 260px">
+    <G3Input v-model="value" type="password" placeholder="请输入密码" autocomplete="current-password" />
+  </div>
+</template>
diff --git a/code/g3soft-libs/docs/examples/input/slots.vue b/code/g3soft-libs/docs/examples/input/slots.vue
new file mode 100644
index 00000000..02cd31a9
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/input/slots.vue
@@ -0,0 +1,25 @@
+<script setup lang="ts">
+// #prefix / #suffix 插槽：放图标、单位、后缀文字
+import { ref } from 'vue'
+import { G3Input, G3Space } from '@g3soft/ui'
+import { Search, User } from '@lucide/vue'
+
+const keyword = ref('')
+const weight = ref('72')
+</script>
+
+<template>
+  <G3Space direction="vertical" :size="12" style="display: flex; width: 280px">
+    <G3Input v-model="keyword" placeholder="搜索">
+      <template #prefix><Search /></template>
+    </G3Input>
+
+    <G3Input v-model="keyword" placeholder="带后缀图标">
+      <template #suffix><User /></template>
+    </G3Input>
+
+    <G3Input v-model="weight" type="number">
+      <template #suffix><span style="font-size: 12px">kg</span></template>
+    </G3Input>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/input/status.vue b/code/g3soft-libs/docs/examples/input/status.vue
new file mode 100644
index 00000000..24a3e46d
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/input/status.vue
@@ -0,0 +1,16 @@
+<script setup lang="ts">
+// status：把校验结果交给输入框表达（error 红边 / warning 黄边）
+import { ref } from 'vue'
+import { G3Input, G3Space } from '@g3soft/ui'
+
+const email = ref('not-an-email')
+const host = ref('localhost')
+</script>
+
+<template>
+  <G3Space direction="vertical" :size="12" style="display: flex; width: 280px">
+    <G3Input v-model="email" status="error" placeholder="邮箱格式不正确" />
+    <G3Input v-model="host" status="warning" placeholder="可能存在风险" />
+    <G3Input model-value="正常状态" />
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/input/textarea.vue b/code/g3soft-libs/docs/examples/input/textarea.vue
new file mode 100644
index 00000000..2e6b3f2b
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/input/textarea.vue
@@ -0,0 +1,22 @@
+<script setup lang="ts">
+// type="textarea"：多行输入；showCount 显示字数，右下角可拖拽调整高度
+import { ref } from 'vue'
+import { G3Input, G3Space } from '@g3soft/ui'
+
+const description = ref('')
+const remark = ref('固定 4 行，不可拖拽时用 rows 控制初始高度')
+</script>
+
+<template>
+  <G3Space direction="vertical" :size="16" style="display: flex; width: 320px">
+    <G3Input
+      v-model="description"
+      type="textarea"
+      :rows="3"
+      :maxlength="100"
+      show-count
+      placeholder="请输入描述，可拖拽右下角调整高度"
+    />
+    <G3Input v-model="remark" type="textarea" :rows="4" readonly />
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/layout/basic.vue b/code/g3soft-libs/docs/examples/layout/basic.vue
new file mode 100644
index 00000000..e2536868
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/layout/basic.vue
@@ -0,0 +1,163 @@
+<script setup lang="ts">
+// 布局骨架演示：切换 7 种布局模式，菜单/页签/内容都由本示例以数据注入。
+// 注意：SSR 预渲染下不要在 setup 顶层用 window/document，这里只用静态数据 + ref。
+import { ref } from 'vue'
+import { G3Layout, type G3TabItem, type LayoutType, type NavItem } from '@g3soft/framework'
+
+const modes: { value: LayoutType; label: string }[] = [
+  { value: 'sidebar-nav', label: '垂直菜单' },
+  { value: 'header-nav', label: '顶部菜单' },
+  { value: 'sidebar-mixed-nav', label: '双列菜单' },
+  { value: 'mixed-nav', label: '顶+侧' },
+  { value: 'header-sidebar-nav', label: '顶栏+侧栏' },
+  { value: 'header-mixed-nav', label: '顶部混合' },
+  { value: 'full-content', label: '通栏内容' },
+]
+
+const layout = ref<LayoutType>('sidebar-nav')
+const activeKey = ref('/dashboard')
+
+const menus: NavItem[] = [
+  { key: '/dashboard', title: '工作台', path: '/dashboard' },
+  {
+    key: '/base',
+    title: '基础资料',
+    children: [
+      { key: '/base/company', title: '公司档案', path: '/base/company' },
+      { key: '/base/customer', title: '客户档案', path: '/base/customer' },
+      { key: '/base/supplier', title: '供应商', path: '/base/supplier' },
+    ],
+  },
+  {
+    key: '/biz',
+    title: '业务管理',
+    children: [
+      { key: '/biz/order', title: '订单', path: '/biz/order' },
+      { key: '/biz/stock', title: '库存', path: '/biz/stock' },
+    ],
+  },
+  {
+    key: '/system',
+    title: '系统设置',
+    children: [
+      { key: '/system/menu', title: '菜单管理', path: '/system/menu' },
+      { key: '/system/user', title: '用户管理', path: '/system/user' },
+    ],
+  },
+]
+
+const tabs = ref<G3TabItem[]>([
+  { key: '/dashboard', title: '工作台', affix: true },
+  { key: '/base/customer', title: '客户档案' },
+])
+
+function onNavigate(payload: { key: string }): void {
+  activeKey.value = payload.key
+}
+
+function onTabChange(key: string): void {
+  activeKey.value = key
+}
+
+function onTabClose(key: string): void {
+  tabs.value = tabs.value.filter((tab) => tab.key !== key)
+}
+</script>
+
+<template>
+  <div class="layout-demo">
+    <div class="layout-demo__modes">
+      <button
+        v-for="mode in modes"
+        :key="mode.value"
+        type="button"
+        class="layout-demo__mode"
+        :class="{ 'is-active': layout === mode.value }"
+        @click="layout = mode.value"
+      >
+        {{ mode.label }}
+      </button>
+    </div>
+
+    <div class="layout-demo__stage">
+      <G3Layout
+        :layout="layout"
+        :menus="menus"
+        :active-key="activeKey"
+        :tabs="layout === 'full-content' ? [] : tabs"
+        @navigate="onNavigate"
+        @tab-change="onTabChange"
+        @tab-close="onTabClose"
+      >
+        <template #logo>
+          <span class="layout-demo__logo">G3 FMS</span>
+        </template>
+        <template #header-right>
+          <span class="layout-demo__user">admin</span>
+        </template>
+        <template #page>
+          <div class="layout-demo__page">当前路由：{{ activeKey }}</div>
+        </template>
+      </G3Layout>
+    </div>
+  </div>
+</template>
+
+<style>
+.layout-demo {
+  width: 100%;
+}
+
+.layout-demo__modes {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+  margin-bottom: 10px;
+}
+
+.layout-demo__mode {
+  padding: 5px 10px;
+  border: 1px solid var(--ui-border, #e5e7eb);
+  border-radius: 6px;
+  background: var(--ui-bg, #fff);
+  color: var(--ui-text-muted, #52525b);
+  font-size: 12px;
+  cursor: pointer;
+}
+
+.layout-demo__mode.is-active {
+  border-color: var(--g3-color-primary, #18181b);
+  color: var(--g3-color-primary, #18181b);
+  font-weight: 600;
+}
+
+.layout-demo__stage {
+  height: 620px;
+  border: 1px solid var(--ui-border, #e5e7eb);
+  border-radius: 10px;
+  overflow: hidden;
+}
+
+.layout-demo__logo {
+  font-size: 15px;
+  font-weight: 700;
+}
+
+.layout-demo__user {
+  font-size: 13px;
+  color: var(--g3-color-text-secondary, #52525b);
+}
+
+.layout-demo__page {
+  flex: 1;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  min-height: 200px;
+  border: 1px dashed var(--ui-border, #e5e7eb);
+  border-radius: 8px;
+  background: var(--ui-bg, #fff);
+  color: var(--g3-color-text-secondary, #52525b);
+  font-size: 14px;
+}
+</style>
diff --git a/code/g3soft-libs/docs/examples/message/basic.vue b/code/g3soft-libs/docs/examples/message/basic.vue
new file mode 100644
index 00000000..2a5ec827
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/message/basic.vue
@@ -0,0 +1,13 @@
+<script setup lang="ts">
+// 四种类型：info / success / warning / error
+import { G3Button, G3Message, G3Space } from '@g3soft/ui'
+</script>
+
+<template>
+  <G3Space :size="[8, 8]" wrap>
+    <G3Button type="outline" @click="G3Message.info('普通提示')">info</G3Button>
+    <G3Button type="outline" @click="G3Message.success('保存成功')">success</G3Button>
+    <G3Button type="outline" @click="G3Message.warning('磁盘空间不足 10%')">warning</G3Button>
+    <G3Button type="outline" @click="G3Message.error('保存失败，请重试')">error</G3Button>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/message/options.vue b/code/g3soft-libs/docs/examples/message/options.vue
new file mode 100644
index 00000000..760f263a
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/message/options.vue
@@ -0,0 +1,23 @@
+<script setup lang="ts">
+// 选项：duration 自动关闭时长（<=0 不关闭）、closable 手动关闭、handle.close() 立即关闭
+import { G3Button, G3Message, G3Space } from '@g3soft/ui'
+
+function openSticky() {
+  G3Message.error('这条不会自动消失，需要手动关闭', { duration: 0, closable: true })
+}
+
+function openAndClose() {
+  const handle = G3Message.info('1.5 秒后由代码关闭', { duration: 0 })
+  setTimeout(() => handle.close(), 1500)
+}
+</script>
+
+<template>
+  <G3Space :size="[8, 8]" wrap>
+    <G3Button type="outline" @click="openSticky">不自动关闭</G3Button>
+    <G3Button type="outline" @click="openAndClose">代码关闭</G3Button>
+    <G3Button type="outline" @click="G3Message.success('5 秒后关闭', { duration: 5000 })">
+      自定义时长
+    </G3Button>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/message/placement.vue b/code/g3soft-libs/docs/examples/message/placement.vue
new file mode 100644
index 00000000..248e08da
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/message/placement.vue
@@ -0,0 +1,27 @@
+<script setup lang="ts">
+// placement：9 个方位；也可以用 Message.config() 设全局默认
+import { G3Button, G3Message, G3Space } from '@g3soft/ui'
+
+const placements = [
+  'top-left',
+  'top-center',
+  'top-right',
+  'center',
+  'bottom-center',
+  'bottom-right',
+] as const
+</script>
+
+<template>
+  <G3Space :size="[8, 8]" wrap>
+    <G3Button
+      v-for="placement in placements"
+      :key="placement"
+      type="outline"
+      size="small"
+      @click="G3Message.info(`出现在 ${placement}`, { placement })"
+    >
+      {{ placement }}
+    </G3Button>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/modal/basic.vue b/code/g3soft-libs/docs/examples/modal/basic.vue
new file mode 100644
index 00000000..da7e6f9f
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/modal/basic.vue
@@ -0,0 +1,32 @@
+<script setup lang="ts">
+// 受控用法：v-model:open 控制显隐，confirm / cancel / closed 三个事件区分关闭来源
+import { ref } from 'vue'
+import { G3Button, G3Input, G3Modal, G3Space } from '@g3soft/ui'
+
+const open = ref(false)
+const name = ref('')
+const log = ref('暂无')
+
+function onConfirm() {
+  log.value = `confirm：提交 ${name.value || '（空）'}`
+  open.value = false
+}
+
+function onCancel() {
+  log.value = 'cancel：取消按钮 / 遮罩 / Esc / 右上角关闭'
+}
+</script>
+
+<template>
+  <G3Space direction="vertical" :size="12" style="display: flex">
+    <div>
+      <G3Button @click="open = true">打开对话框</G3Button>
+    </div>
+
+    <G3Modal v-model:open="open" title="新建项目" @confirm="onConfirm" @cancel="onCancel" @closed="log = `${log}｜closed：退场动画结束`">
+      <G3Input v-model="name" placeholder="项目名称" />
+    </G3Modal>
+
+    <span style="font-size: 12px; color: #6b7280">{{ log }}</span>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/modal/confirm-async.vue b/code/g3soft-libs/docs/examples/modal/confirm-async.vue
new file mode 100644
index 00000000..e9534818
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/modal/confirm-async.vue
@@ -0,0 +1,35 @@
+<script setup lang="ts">
+// 异步确认：onConfirm 返回 Promise 时按钮进入 loading
+// resolve → 关闭；reject → 保持打开，让用户重试或取消
+import { G3Button, G3Message, G3Modal, G3Space } from '@g3soft/ui'
+
+function openSuccess() {
+  G3Modal.confirm({
+    title: '提交审批',
+    content: 'onConfirm 返回 Promise，等待期间按钮显示 loading。',
+    onConfirm: async () => {
+      await new Promise((resolve) => setTimeout(resolve, 1200))
+      G3Message.success('审批已提交')
+    },
+  })
+}
+
+function openFailure() {
+  G3Modal.confirm({
+    title: '可能失败的提交',
+    content: '这次会 reject：弹窗保持打开，按钮恢复可点。',
+    onConfirm: async () => {
+      await new Promise((resolve) => setTimeout(resolve, 1000))
+      G3Message.error('服务不可用，请重试')
+      throw new Error('failed')
+    },
+  })
+}
+</script>
+
+<template>
+  <G3Space :size="12" wrap>
+    <G3Button @click="openSuccess">异步成功</G3Button>
+    <G3Button type="outline" @click="openFailure">异步失败</G3Button>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/modal/confirm.vue b/code/g3soft-libs/docs/examples/modal/confirm.vue
new file mode 100644
index 00000000..02c910f1
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/modal/confirm.vue
@@ -0,0 +1,34 @@
+<script setup lang="ts">
+// 命令式确认框：G3Modal.confirm(options) 返回 { destroy }
+import { G3Button, G3Message, G3Modal, G3Space } from '@g3soft/ui'
+
+function openConfirm() {
+  G3Modal.confirm({
+    title: '确定删除该分支？',
+    content: '删除后不可恢复，关联的构建记录会一并清理。',
+    confirmText: '删除',
+    cancelText: '再想想',
+    confirmButtonProps: { danger: true },
+    onConfirm: () => G3Message.success('已删除'),
+    onCancel: () => G3Message.info('已取消'),
+  })
+}
+
+// destroy：不等退场动画直接卸载（例如路由切换时清理）
+let handle: ReturnType<typeof G3Modal.confirm> | null = null
+
+function openAndDestroy() {
+  handle = G3Modal.confirm({
+    title: '3 秒后强制销毁',
+    content: 'destroy() 会立即关闭并卸载容器，不播放退场动画。',
+  })
+  setTimeout(() => handle?.destroy(), 3000)
+}
+</script>
+
+<template>
+  <G3Space :size="12" wrap>
+    <G3Button type="danger-outline" @click="openConfirm">删除确认</G3Button>
+    <G3Button type="outline" @click="openAndDestroy">演示 destroy()</G3Button>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/modal/footer-slot.vue b/code/g3soft-libs/docs/examples/modal/footer-slot.vue
new file mode 100644
index 00000000..f2eaed67
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/modal/footer-slot.vue
@@ -0,0 +1,33 @@
+<script setup lang="ts">
+// #footer 完全自定义底部；#header-extra 放标题右侧的额外动作
+import { ref } from 'vue'
+import { G3Button, G3Modal, G3Space } from '@g3soft/ui'
+
+const open = ref(false)
+</script>
+
+<template>
+  <G3Space direction="vertical" :size="12" style="display: flex">
+    <div>
+      <G3Button @click="open = true">自定义底部</G3Button>
+    </div>
+
+    <G3Modal v-model:open="open" title="发布向导">
+      <template #header-extra>
+        <G3Button size="small" type="ghost">帮助</G3Button>
+      </template>
+
+      <p style="margin: 0">底部可以放多个按钮、步骤指示器或协议勾选。</p>
+
+      <template #footer>
+        <div style="display: flex; align-items: center; justify-content: space-between; width: 100%">
+          <span style="font-size: 12px; color: #6b7280">第 1 / 3 步</span>
+          <G3Space :size="8">
+            <G3Button type="outline" @click="open = false">取消</G3Button>
+            <G3Button @click="open = false">下一步</G3Button>
+          </G3Space>
+        </div>
+      </template>
+    </G3Modal>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/modal/form.vue b/code/g3soft-libs/docs/examples/modal/form.vue
new file mode 100644
index 00000000..90980001
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/modal/form.vue
@@ -0,0 +1,44 @@
+<script setup lang="ts">
+// 表单弹窗：confirmLoading 阻止一切关闭，异步提交期间按钮显示加载
+import { reactive, ref } from 'vue'
+import { G3Button, G3Form, G3FormItem, G3Input, G3Message, G3Modal } from '@g3soft/ui'
+
+const open = ref(false)
+const saving = ref(false)
+const model = reactive({ name: '', code: '' })
+const rules = { name: [{ required: true }] }
+
+async function handleConfirm() {
+  saving.value = true
+  try {
+    await new Promise((resolve) => setTimeout(resolve, 1000))
+    G3Message.success(`已保存 ${model.name}`)
+    open.value = false
+  } finally {
+    saving.value = false
+  }
+}
+</script>
+
+<template>
+  <div>
+    <G3Button @click="open = true">新建（表单弹窗）</G3Button>
+
+    <G3Modal
+      v-model:open="open"
+      title="新建项目"
+      :width="480"
+      :confirm-loading="saving"
+      @confirm="handleConfirm"
+    >
+      <G3Form :model="model" :rules="rules" :label-width="72" validate-trigger="blur" @submit="handleConfirm">
+        <G3FormItem name="name" label="名称">
+          <G3Input v-model="model.name" placeholder="必填" />
+        </G3FormItem>
+        <G3FormItem name="code" label="标识">
+          <G3Input v-model="model.code" placeholder="可选" />
+        </G3FormItem>
+      </G3Form>
+    </G3Modal>
+  </div>
+</template>
diff --git a/code/g3soft-libs/docs/examples/modal/mask.vue b/code/g3soft-libs/docs/examples/modal/mask.vue
new file mode 100644
index 00000000..9dc19652
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/modal/mask.vue
@@ -0,0 +1,37 @@
+<script setup lang="ts">
+// mask / maskClosable / keyboard / closable / footer：控制关闭入口
+import { ref } from 'vue'
+import { G3Button, G3Modal, G3Space, G3Switch } from '@g3soft/ui'
+
+const open = ref(false)
+const maskClosable = ref(false)
+const keyboard = ref(true)
+const closable = ref(true)
+const showFooter = ref(true)
+</script>
+
+<template>
+  <G3Space direction="vertical" :size="12" style="display: flex">
+    <G3Space :size="[16, 8]" wrap>
+      <G3Switch v-model="maskClosable">点击遮罩关闭</G3Switch>
+      <G3Switch v-model="keyboard">Esc 关闭</G3Switch>
+      <G3Switch v-model="closable">显示关闭按钮</G3Switch>
+      <G3Switch v-model="showFooter">显示底部按钮</G3Switch>
+    </G3Space>
+
+    <div>
+      <G3Button @click="open = true">打开</G3Button>
+    </div>
+
+    <G3Modal
+      v-model:open="open"
+      title="关闭入口可控"
+      :mask-closable="maskClosable"
+      :keyboard="keyboard"
+      :closable="closable"
+      :footer="showFooter"
+    >
+      强制用户做出选择时，把 maskClosable / keyboard / closable 都设为 false。
+    </G3Modal>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/modal/resize.vue b/code/g3soft-libs/docs/examples/modal/resize.vue
new file mode 100644
index 00000000..1d042fee
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/modal/resize.vue
@@ -0,0 +1,29 @@
+<script setup lang="ts">
+// 拖动标题栏移动、拖拽四边缩放、全屏切换；centered 让面板垂直居中
+import { ref } from 'vue'
+import { G3Button, G3Modal, G3Space } from '@g3soft/ui'
+
+const open = ref(false)
+const fullscreen = ref(false)
+</script>
+
+<template>
+  <G3Space :size="12" wrap>
+    <G3Button type="outline" @click="open = true; fullscreen = false">可拖动 / 缩放</G3Button>
+    <G3Button type="outline" @click="open = true; fullscreen = true">居中显示</G3Button>
+
+    <G3Modal
+      v-model:open="open"
+      :title="fullscreen ? '居中且禁止拖动' : '拖动标题栏可移动，拖拽四边可缩放'"
+      :width="560"
+      :centered="fullscreen"
+      :fullscreen="!fullscreen"
+      :resizable="!fullscreen"
+    >
+      <p style="margin: 0">面板默认贴顶显示；开启 centered 后垂直居中，适合确认类与短表单。</p>
+      <p style="margin: 8px 0 0; color: #6b7280">
+        右上角的全屏按钮与拖动/缩放互斥：全屏时会自动复位位置。
+      </p>
+    </G3Modal>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/notification/basic.vue b/code/g3soft-libs/docs/examples/notification/basic.vue
new file mode 100644
index 00000000..79f7c7f3
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/notification/basic.vue
@@ -0,0 +1,26 @@
+<script setup lang="ts">
+// 与 Message 的区别：带标题与描述，默认停留更久（4500ms），适合承载需要阅读的信息
+import { G3Button, G3Notification, G3Space } from '@g3soft/ui'
+</script>
+
+<template>
+  <G3Space :size="[8, 8]" wrap>
+    <G3Button
+      type="outline"
+      @click="
+        G3Notification.success({ title: '发布成功', description: '版本 1.2.0 已上线，5 分钟后全量生效' })
+      "
+    >
+      成功通知
+    </G3Button>
+
+    <G3Button
+      type="outline"
+      @click="
+        G3Notification.error({ title: '构建失败', description: '单元测试未通过，点击查看日志', duration: 0 })
+      "
+    >
+      不自动关闭的错误通知
+    </G3Button>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/notification/close.vue b/code/g3soft-libs/docs/examples/notification/close.vue
new file mode 100644
index 00000000..fc22842d
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/notification/close.vue
@@ -0,0 +1,23 @@
+<script setup lang="ts">
+// 句柄关闭与全局清理：handle.close() 关一条，G3Notification.destroy() 全部清空
+import { G3Button, G3Notification, G3Space } from '@g3soft/ui'
+
+function openMany() {
+  G3Notification.info({ title: '任务 1', description: '处理中' })
+  G3Notification.info({ title: '任务 2', description: '处理中' })
+  G3Notification.warning({ title: '任务 3', description: '需要人工确认', duration: 0 })
+}
+
+function openAndClose() {
+  const handle = G3Notification.success({ title: '即将被关闭', description: '1.5 秒后自动关闭' })
+  setTimeout(() => handle.close(), 1500)
+}
+</script>
+
+<template>
+  <G3Space :size="[8, 8]" wrap>
+    <G3Button type="outline" @click="openMany">打开多条</G3Button>
+    <G3Button type="outline" @click="openAndClose">句柄关闭</G3Button>
+    <G3Button type="outline" @click="G3Notification.destroy()">全部清空</G3Button>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/notification/placement.vue b/code/g3soft-libs/docs/examples/notification/placement.vue
new file mode 100644
index 00000000..53126098
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/notification/placement.vue
@@ -0,0 +1,20 @@
+<script setup lang="ts">
+// 通知只出现在四角；placement 可逐条指定，也可用 config 设全局默认
+import { G3Button, G3Notification, G3Space } from '@g3soft/ui'
+
+const placements = ['top-right', 'top-left', 'bottom-right', 'bottom-left'] as const
+</script>
+
+<template>
+  <G3Space :size="[8, 8]" wrap>
+    <G3Button
+      v-for="placement in placements"
+      :key="placement"
+      type="outline"
+      size="small"
+      @click="G3Notification.info({ title: placement, description: '四角之一', placement })"
+    >
+      {{ placement }}
+    </G3Button>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/pagination/basic.vue b/code/g3soft-libs/docs/examples/pagination/basic.vue
new file mode 100644
index 00000000..709c2a15
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/pagination/basic.vue
@@ -0,0 +1,14 @@
+<script setup lang="ts">
+// 最基础：v-model:current 绑定当前页，total 提供总条数（pageSize 默认 10）
+import { ref } from 'vue'
+import { G3Pagination } from '@g3soft/ui'
+
+const current = ref(1)
+</script>
+
+<template>
+  <div>
+    <G3Pagination v-model:current="current" :total="86" />
+    <p style="margin: 8px 0 0; font-size: 13px; color: #6b7280">当前第 {{ current }} 页</p>
+  </div>
+</template>
diff --git a/code/g3soft-libs/docs/examples/pagination/hide-on-single.vue b/code/g3soft-libs/docs/examples/pagination/hide-on-single.vue
new file mode 100644
index 00000000..47060629
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/pagination/hide-on-single.vue
@@ -0,0 +1,26 @@
+<script setup lang="ts">
+// hideOnSinglePage：只有一页时整块隐藏；change 事件同时给出当前页与每页条数
+import { ref } from 'vue'
+import { G3Pagination, G3Space, G3Switch } from '@g3soft/ui'
+
+const total = ref(8)
+const current = ref(1)
+const onlyOne = ref(false)
+</script>
+
+<template>
+  <G3Space direction="vertical" :size="12" style="display: flex">
+    <G3Space :size="8" align="center">
+      <G3Switch v-model="onlyOne">只有一页（8 条）</G3Switch>
+      <span style="font-size: 13px; color: #6b7280">切到 86 条可以看完整分页</span>
+    </G3Space>
+
+    <G3Pagination
+      v-model:current="current"
+      :total="onlyOne ? 8 : 86"
+      hide-on-single-page
+      show-total
+      @change="(page: number, size: number) => (current = page)"
+    />
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/pagination/quick-jumper.vue b/code/g3soft-libs/docs/examples/pagination/quick-jumper.vue
new file mode 100644
index 00000000..76ccba9c
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/pagination/quick-jumper.vue
@@ -0,0 +1,14 @@
+<script setup lang="ts">
+// showQuickJumper：输入页码后回车跳转；非法/越界输入会被收敛到有效范围
+import { ref } from 'vue'
+import { G3Pagination, G3Space } from '@g3soft/ui'
+
+const current = ref(5)
+</script>
+
+<template>
+  <G3Space direction="vertical" :size="12" style="display: flex">
+    <G3Pagination v-model:current="current" :total="500" show-quick-jumper />
+    <G3Pagination v-model:current="current" :total="500" show-quick-jumper show-total show-size-changer />
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/pagination/size-changer.vue b/code/g3soft-libs/docs/examples/pagination/size-changer.vue
new file mode 100644
index 00000000..c4158ce5
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/pagination/size-changer.vue
@@ -0,0 +1,25 @@
+<script setup lang="ts">
+// showSizeChanger：每页条数下拉；pageSizeOptions 自定义选项，showSizeChange 单独通知
+import { ref } from 'vue'
+import { G3Pagination } from '@g3soft/ui'
+
+const current = ref(1)
+const pageSize = ref(20)
+const lastEvent = ref('暂无')
+</script>
+
+<template>
+  <div>
+    <G3Pagination
+      v-model:current="current"
+      v-model:page-size="pageSize"
+      :total="286"
+      :page-size-options="[10, 20, 50, 100]"
+      show-size-changer
+      @show-size-change="(page: number, size: number) => (lastEvent = `切换每页 ${size} 条，当前第 ${page} 页`)"
+    />
+    <p style="margin: 8px 0 0; font-size: 13px; color: #6b7280">
+      每页 {{ pageSize }} 条｜{{ lastEvent }}
+    </p>
+  </div>
+</template>
diff --git a/code/g3soft-libs/docs/examples/pagination/total.vue b/code/g3soft-libs/docs/examples/pagination/total.vue
new file mode 100644
index 00000000..6ad990fb
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/pagination/total.vue
@@ -0,0 +1,20 @@
+<script setup lang="ts">
+// showTotal：显示总条数；#showTotal 插槽可拿到 { total, from, to } 自定义文案
+import { ref } from 'vue'
+import { G3Pagination } from '@g3soft/ui'
+
+const current = ref(2)
+const pageSize = ref(10)
+</script>
+
+<template>
+  <div style="display: flex; flex-direction: column; gap: 16px">
+    <G3Pagination v-model:current="current" :total="53" show-total />
+
+    <G3Pagination v-model:current="current" v-model:page-size="pageSize" :total="53" show-total show-size-changer>
+      <template #showTotal="{ total, from, to }">
+        第 {{ from }}-{{ to }} 条 / 共 {{ total }} 条
+      </template>
+    </G3Pagination>
+  </div>
+</template>
diff --git a/code/g3soft-libs/docs/examples/popover/arrow-width.vue b/code/g3soft-libs/docs/examples/popover/arrow-width.vue
new file mode 100644
index 00000000..7fb3d94e
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/popover/arrow-width.vue
@@ -0,0 +1,24 @@
+<script setup lang="ts">
+// arrow 控制箭头；followTriggerWidth 让浮层宽度以触发器为下限（表单类控件常用）
+import { G3Button, G3Popover, G3Space } from '@g3soft/ui'
+</script>
+
+<template>
+  <G3Space direction="vertical" :size="40" style="display: flex; align-items: center; padding: 60px 20px">
+    <G3Popover :arrow="false" placement="bottom">
+      <template #trigger><G3Button type="outline">无箭头</G3Button></template>
+      <template #content>arrow=false 时没有尖角，适合菜单类浮层</template>
+    </G3Popover>
+
+    <div style="width: 320px">
+      <G3Popover follow-trigger-width placement="bottom-start">
+        <template #trigger>
+          <div style="padding: 8px 12px; border: 1px solid #d9d9d9; border-radius: 6px">
+            触发器（320px 宽）
+          </div>
+        </template>
+        <template #content>浮层宽度跟随触发器，内容更长时会自动变宽</template>
+      </G3Popover>
+    </div>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/popover/basic.vue b/code/g3soft-libs/docs/examples/popover/basic.vue
new file mode 100644
index 00000000..f92e5b23
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/popover/basic.vue
@@ -0,0 +1,17 @@
+<script setup lang="ts">
+// 最基础：默认 click 触发，浮层内容写在 #content 插槽
+import { G3Button, G3Popover } from '@g3soft/ui'
+</script>
+
+<template>
+  <G3Popover>
+    <template #trigger>
+      <G3Button type="outline">点击查看</G3Button>
+    </template>
+    <template #content>
+      <div style="max-width: 220px">
+        浮层内容可以直接写 HTML，也可以放任意组件。
+      </div>
+    </template>
+  </G3Popover>
+</template>
diff --git a/code/g3soft-libs/docs/examples/popover/controlled.vue b/code/g3soft-libs/docs/examples/popover/controlled.vue
new file mode 100644
index 00000000..6cdb6e7b
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/popover/controlled.vue
@@ -0,0 +1,26 @@
+<script setup lang="ts">
+// 受控用法：传 open 并监听 update:open，可做二次确认、埋点、权限拦截
+import { ref } from 'vue'
+import { G3Button, G3Message, G3Popover } from '@g3soft/ui'
+
+const open = ref(false)
+
+function onOpenChange(value: boolean) {
+  if (value) G3Message.info('打开前可以做权限校验/埋点')
+  open.value = value
+}
+</script>
+
+<template>
+  <G3Popover :open="open" placement="bottom-start" @update:open="onOpenChange">
+    <template #trigger>
+      <G3Button type="outline">受控气泡</G3Button>
+    </template>
+    <template #content>
+      <div style="max-width: 200px">
+        <p style="margin: 0 0 8px">受控模式下，所有开关都经过 update:open。</p>
+        <G3Button size="small" @click="open = false">知道了</G3Button>
+      </div>
+    </template>
+  </G3Popover>
+</template>
diff --git a/code/g3soft-libs/docs/examples/popover/placement.vue b/code/g3soft-libs/docs/examples/popover/placement.vue
new file mode 100644
index 00000000..9044ba0d
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/popover/placement.vue
@@ -0,0 +1,21 @@
+<script setup lang="ts">
+// placement：12 个方位（4 主方向 × start/center/end），空间不足时自动翻转
+import { ref } from 'vue'
+import { G3Button, G3Popover, G3Segmented } from '@g3soft/ui'
+
+const placement = ref('top')
+const options = ['top', 'bottom', 'left', 'right', 'top-start', 'bottom-end']
+</script>
+
+<template>
+  <div style="display: flex; flex-direction: column; gap: 16px; align-items: center; padding: 40px">
+    <G3Segmented v-model="placement" :options="options" shape="round" />
+
+    <G3Popover :placement="placement" :offset="12">
+      <template #trigger>
+        <G3Button type="outline">方位：{{ placement }}</G3Button>
+      </template>
+      <template #content>当前方位 {{ placement }}，贴边时会自动翻到对面</template>
+    </G3Popover>
+  </div>
+</template>
diff --git a/code/g3soft-libs/docs/examples/popover/trigger.vue b/code/g3soft-libs/docs/examples/popover/trigger.vue
new file mode 100644
index 00000000..8c5d87d7
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/popover/trigger.vue
@@ -0,0 +1,40 @@
+<script setup lang="ts">
+// trigger：click（默认）/ hover / focus / contextmenu / manual（完全受控）
+import { ref } from 'vue'
+import { G3Button, G3Popover, G3Space } from '@g3soft/ui'
+
+const manualOpen = ref(false)
+</script>
+
+<template>
+  <G3Space :size="[16, 12]" align="center" wrap>
+    <G3Popover trigger="hover">
+      <template #trigger><G3Button type="outline">hover 触发</G3Button></template>
+      <template #content>鼠标移入即显示，移出后延迟关闭</template>
+    </G3Popover>
+
+    <G3Popover trigger="focus">
+      <template #trigger><G3Button type="outline">focus 触发</G3Button></template>
+      <template #content>Tab 聚焦时显示，焦点移出关闭</template>
+    </G3Popover>
+
+    <G3Popover trigger="contextmenu">
+      <template #trigger>
+        <div style="padding: 12px 20px; border: 1px dashed #d9d9d9; border-radius: 6px">
+          在此处右键
+        </div>
+      </template>
+      <template #content>在鼠标位置弹出，超出视口会自动回退</template>
+    </G3Popover>
+
+    <!-- manual：开关完全由业务控制 -->
+    <G3Popover trigger="manual" :open="manualOpen">
+      <template #trigger>
+        <G3Button type="outline" @click="manualOpen = !manualOpen">manual 触发</G3Button>
+      </template>
+      <template #content>
+        <G3Button size="small" @click="manualOpen = false">手动关闭</G3Button>
+      </template>
+    </G3Popover>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/radio/basic.vue b/code/g3soft-libs/docs/examples/radio/basic.vue
new file mode 100644
index 00000000..5f869245
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/radio/basic.vue
@@ -0,0 +1,18 @@
+<script setup lang="ts">
+// G3Radio 必须放在 G3RadioGroup 里才互斥；组内可单独禁用某项
+import { ref } from 'vue'
+import { G3Radio, G3RadioGroup } from '@g3soft/ui'
+
+const value = ref('monthly')
+</script>
+
+<template>
+  <div>
+    <G3RadioGroup v-model="value">
+      <G3Radio value="monthly">按月付费</G3Radio>
+      <G3Radio value="yearly">按年付费（省 2 个月）</G3Radio>
+      <G3Radio value="once" disabled>一次性买断（暂不可选）</G3Radio>
+    </G3RadioGroup>
+    <p style="margin: 8px 0 0; font-size: 13px; color: #6b7280">选中：{{ value }}</p>
+  </div>
+</template>
diff --git a/code/g3soft-libs/docs/examples/radio/cards.vue b/code/g3soft-libs/docs/examples/radio/cards.vue
new file mode 100644
index 00000000..a6693c9c
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/radio/cards.vue
@@ -0,0 +1,31 @@
+<script setup lang="ts">
+// 用默认插槽写富内容：把 Radio 当「卡片选择器」用
+import { ref } from 'vue'
+import { G3Radio, G3RadioGroup } from '@g3soft/ui'
+
+const plan = ref('pro')
+</script>
+
+<template>
+  <G3RadioGroup v-model="plan" style="align-items: flex-start; gap: 12px">
+    <G3Radio
+      value="basic"
+      style="flex: 1; padding: 12px; border: 1px solid #d9d9d9; border-radius: 8px"
+    >
+      <span style="display: block">
+        <strong>基础版</strong>
+        <span style="display: block; color: #6b7280; font-size: 12px">单项目 · 1GB 存储</span>
+      </span>
+    </G3Radio>
+
+    <G3Radio
+      value="pro"
+      style="flex: 1; padding: 12px; border: 1px solid #d9d9d9; border-radius: 8px"
+    >
+      <span style="display: block">
+        <strong>专业版</strong>
+        <span style="display: block; color: #6b7280; font-size: 12px">多项目 · 100GB 存储</span>
+      </span>
+    </G3Radio>
+  </G3RadioGroup>
+</template>
diff --git a/code/g3soft-libs/docs/examples/radio/vertical.vue b/code/g3soft-libs/docs/examples/radio/vertical.vue
new file mode 100644
index 00000000..e0052a40
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/radio/vertical.vue
@@ -0,0 +1,24 @@
+<script setup lang="ts">
+// 纵向排列与整组禁用
+import { ref } from 'vue'
+import { G3Radio, G3RadioGroup, G3Space } from '@g3soft/ui'
+
+const layout = ref(1)
+const disabledValue = ref(2)
+</script>
+
+<template>
+  <G3Space direction="vertical" :size="20" style="display: flex">
+    <!-- 组默认水平换行排列；纵向需要自己包一层纵向容器 -->
+    <G3RadioGroup v-model="layout" style="flex-direction: column; align-items: flex-start; gap: 8px">
+      <G3Radio :value="1">紧凑视图</G3Radio>
+      <G3Radio :value="2">标准视图</G3Radio>
+      <G3Radio :value="3">宽松视图</G3Radio>
+    </G3RadioGroup>
+
+    <G3RadioGroup v-model="disabledValue" disabled>
+      <G3Radio :value="1">整组禁用 A</G3Radio>
+      <G3Radio :value="2">整组禁用 B</G3Radio>
+    </G3RadioGroup>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/scrollbar/autohide.vue b/code/g3soft-libs/docs/examples/scrollbar/autohide.vue
new file mode 100644
index 00000000..87364b3e
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/scrollbar/autohide.vue
@@ -0,0 +1,23 @@
+<script setup lang="ts">
+// autoHide：never 常显 / scroll 滚动时显示 / move 鼠标移动或滚动时显示 / leave 移出后隐藏
+import { G3Scrollbar, G3Space } from '@g3soft/ui'
+
+const strategies = ['never', 'scroll', 'move', 'leave'] as const
+</script>
+
+<template>
+  <G3Space :size="12" wrap align="start">
+    <div v-for="mode in strategies" :key="mode" style="width: 180px">
+      <p style="margin: 0 0 6px; font-size: 12px; color: #6b7280">{{ mode }}</p>
+      <G3Scrollbar
+        :auto-hide="mode"
+        :aria-label="`autoHide=${mode} 的滚动区域`"
+        style="height: 120px; border: 1px solid #d9d9d9; border-radius: 8px; padding: 8px"
+      >
+        <div v-for="index in 12" :key="index" style="padding: 4px 0; font-size: 13px">
+          第 {{ index }} 行
+        </div>
+      </G3Scrollbar>
+    </div>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/scrollbar/basic.vue b/code/g3soft-libs/docs/examples/scrollbar/basic.vue
new file mode 100644
index 00000000..23fe8aa2
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/scrollbar/basic.vue
@@ -0,0 +1,12 @@
+<script setup lang="ts">
+// 最基础：隐藏原生滚动条，用自绘滑块；内容超出高度时可滚动
+import { G3Scrollbar, G3Tag, G3Space } from '@g3soft/ui'
+</script>
+
+<template>
+  <G3Scrollbar style="height: 160px; border: 1px solid #d9d9d9; border-radius: 8px; padding: 12px">
+    <G3Space direction="vertical" :size="8" style="display: flex">
+      <G3Tag v-for="index in 20" :key="index" variant="secondary">第 {{ index }} 行内容</G3Tag>
+    </G3Space>
+  </G3Scrollbar>
+</template>
diff --git a/code/g3soft-libs/docs/examples/segmented/basic.vue b/code/g3soft-libs/docs/examples/segmented/basic.vue
new file mode 100644
index 00000000..2dca70a7
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/segmented/basic.vue
@@ -0,0 +1,14 @@
+<script setup lang="ts">
+// 最简用法：options 传原始值数组，选中值用 v-model 双向绑定
+import { ref } from 'vue'
+import { G3Segmented } from '@g3soft/ui'
+
+const value = ref('list')
+</script>
+
+<template>
+  <div>
+    <G3Segmented v-model="value" :options="['list', 'board', 'timeline']" />
+    <p style="margin: 8px 0 0; font-size: 13px; color: #6b7280">当前视图：{{ value }}</p>
+  </div>
+</template>
diff --git a/code/g3soft-libs/docs/examples/segmented/block.vue b/code/g3soft-libs/docs/examples/segmented/block.vue
new file mode 100644
index 00000000..e4a10a19
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/segmented/block.vue
@@ -0,0 +1,20 @@
+<script setup lang="ts">
+// block：撑满父容器，各项等分空间（常用于移动端 / 表单顶部的模式切换）
+import { ref } from 'vue'
+import { G3Segmented } from '@g3soft/ui'
+
+const value = ref('login')
+</script>
+
+<template>
+  <div style="width: 320px">
+    <G3Segmented
+      v-model="value"
+      block
+      :options="[
+        { label: '账号登录', value: 'login' },
+        { label: '扫码登录', value: 'qrcode' },
+      ]"
+    />
+  </div>
+</template>
diff --git a/code/g3soft-libs/docs/examples/segmented/custom-label.vue b/code/g3soft-libs/docs/examples/segmented/custom-label.vue
new file mode 100644
index 00000000..dfda8418
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/segmented/custom-label.vue
@@ -0,0 +1,33 @@
+<script setup lang="ts">
+// #label 插槽：完全自定义每项内容，作用域参数为 { option, index, checked }
+import { ref } from 'vue'
+import { G3Segmented } from '@g3soft/ui'
+
+const value = ref(1)
+
+const options = [
+  { value: 1, label: '待办', count: 8 },
+  { value: 2, label: '进行中', count: 3 },
+  { value: 3, label: '已完成', count: 12 },
+]
+</script>
+
+<template>
+  <G3Segmented v-model="value" :options="options">
+    <template #label="{ option, checked }">
+      <span style="display: inline-flex; align-items: center; gap: 6px">
+        {{ (option as { label: string }).label }}
+        <span
+          :style="{
+            padding: '0 6px',
+            borderRadius: '8px',
+            fontSize: '12px',
+            background: checked ? 'rgba(255,255,255,.25)' : 'rgba(0,0,0,.06)',
+          }"
+        >
+          {{ (option as { count: number }).count }}
+        </span>
+      </span>
+    </template>
+  </G3Segmented>
+</template>
diff --git a/code/g3soft-libs/docs/examples/segmented/options.vue b/code/g3soft-libs/docs/examples/segmented/options.vue
new file mode 100644
index 00000000..d997262f
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/segmented/options.vue
@@ -0,0 +1,19 @@
+<script setup lang="ts">
+// 对象形态：自定义 label、禁用某项、带图标
+import { ref } from 'vue'
+import { G3Segmented } from '@g3soft/ui'
+import { AlignCenter, AlignLeft, AlignRight } from '@lucide/vue'
+
+const value = ref('left')
+
+const options = [
+  { label: '左对齐', value: 'left', icon: AlignLeft },
+  { label: '居中', value: 'center', icon: AlignCenter },
+  { label: '右对齐', value: 'right', icon: AlignRight },
+  { label: '两端对齐（未实现）', value: 'justify', disabled: true },
+]
+</script>
+
+<template>
+  <G3Segmented v-model="value" :options="options" />
+</template>
diff --git a/code/g3soft-libs/docs/examples/segmented/shape.vue b/code/g3soft-libs/docs/examples/segmented/shape.vue
new file mode 100644
index 00000000..d91fab6a
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/segmented/shape.vue
@@ -0,0 +1,15 @@
+<script setup lang="ts">
+// shape：default 跟随控件圆角（6px），round 为全圆角胶囊
+import { ref } from 'vue'
+import { G3Segmented, G3Space } from '@g3soft/ui'
+
+const a = ref('day')
+const b = ref('day')
+</script>
+
+<template>
+  <G3Space direction="vertical" :size="12" style="display: flex">
+    <G3Segmented v-model="a" :options="['日', '周', '月']" />
+    <G3Segmented v-model="b" :options="['日', '周', '月']" shape="round" />
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/segmented/uncontrolled.vue b/code/g3soft-libs/docs/examples/segmented/uncontrolled.vue
new file mode 100644
index 00000000..907dd143
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/segmented/uncontrolled.vue
@@ -0,0 +1,18 @@
+<script setup lang="ts">
+// 不传 modelValue 即非受控：组件内部维护选中值，只通过 change 通知
+import { ref } from 'vue'
+import { G3Segmented } from '@g3soft/ui'
+
+const current = ref('hot')
+
+function onChange(value: string | number | boolean) {
+  current.value = String(value)
+}
+</script>
+
+<template>
+  <div>
+    <G3Segmented :options="['hot', 'new', 'top']" @change="onChange" />
+    <p style="margin: 8px 0 0; font-size: 13px; color: #6b7280">change 收到：{{ current }}</p>
+  </div>
+</template>
diff --git a/code/g3soft-libs/docs/examples/segmented/vertical.vue b/code/g3soft-libs/docs/examples/segmented/vertical.vue
new file mode 100644
index 00000000..91db7859
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/segmented/vertical.vue
@@ -0,0 +1,19 @@
+<script setup lang="ts">
+// vertical：纵向排列，滑块上下移动（适合做侧边视图切换）
+import { ref } from 'vue'
+import { G3Segmented } from '@g3soft/ui'
+
+const value = ref('outline')
+</script>
+
+<template>
+  <G3Segmented
+    v-model="value"
+    vertical
+    :options="[
+      { label: '大纲', value: 'outline' },
+      { label: '属性', value: 'props' },
+      { label: '样式', value: 'style' },
+    ]"
+  />
+</template>
diff --git a/code/g3soft-libs/docs/examples/select/basic.vue b/code/g3soft-libs/docs/examples/select/basic.vue
new file mode 100644
index 00000000..4d6084fd
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/select/basic.vue
@@ -0,0 +1,20 @@
+<script setup lang="ts">
+// 最基础用法：options 默认取 { label, value, disabled }
+import { ref } from 'vue'
+import { G3Select } from '@g3soft/ui'
+
+const value = ref<number | undefined>(undefined)
+
+const options = [
+  { label: '开发环境', value: 1 },
+  { label: '测试环境', value: 2 },
+  { label: '生产环境', value: 3, disabled: true },
+]
+</script>
+
+<template>
+  <div style="width: 240px">
+    <G3Select v-model="value" :options="options" placeholder="请选择环境" />
+    <p style="margin: 8px 0 0; font-size: 13px; color: #6b7280">选中：{{ value ?? '（未选）' }}</p>
+  </div>
+</template>
diff --git a/code/g3soft-libs/docs/examples/select/custom-option.vue b/code/g3soft-libs/docs/examples/select/custom-option.vue
new file mode 100644
index 00000000..84b0130a
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/select/custom-option.vue
@@ -0,0 +1,43 @@
+<script setup lang="ts">
+// 不传 options 时使用默认插槽自定义选项；插槽透出 select / close
+import { ref } from 'vue'
+import { G3Select } from '@g3soft/ui'
+import { CircleCheck } from '@lucide/vue'
+
+const value = ref<string | undefined>('small')
+
+const sizes = [
+  { label: '紧凑', value: 'small', desc: '适合信息密度高的表格' },
+  { label: '标准', value: 'medium', desc: '默认尺寸' },
+  { label: '宽松', value: 'large', desc: '适合触屏与展示页' },
+]
+</script>
+
+<template>
+  <div style="width: 280px">
+    <G3Select v-model="value" placeholder="选择密度" filterable>
+      <template #default="{ select, close }">
+        <div style="padding: 4px">
+          <div
+            v-for="size in sizes"
+            :key="size.value"
+            style="display: flex; align-items: center; gap: 8px; padding: 6px 8px; border-radius: 4px; cursor: pointer"
+            @click="
+              () => {
+                select(size.value)
+                close()
+              }
+            "
+          >
+            <CircleCheck v-if="value === size.value" :size="14" />
+            <span v-else style="width: 14px" />
+            <span style="flex: 1">
+              <strong style="font-size: 13px">{{ size.label }}</strong>
+              <span style="display: block; color: #6b7280; font-size: 12px">{{ size.desc }}</span>
+            </span>
+          </div>
+        </div>
+      </template>
+    </G3Select>
+  </div>
+</template>
diff --git a/code/g3soft-libs/docs/examples/select/field-names.vue b/code/g3soft-libs/docs/examples/select/field-names.vue
new file mode 100644
index 00000000..571eff72
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/select/field-names.vue
@@ -0,0 +1,26 @@
+<script setup lang="ts">
+// 后端字段不是 label/value 时，用 labelKey / valueKey 映射
+import { ref } from 'vue'
+import { G3Select } from '@g3soft/ui'
+
+const userId = ref<number | undefined>(undefined)
+
+const users = [
+  { id: 101, name: '张三' },
+  { id: 102, name: '李四' },
+  { id: 103, name: '王五' },
+]
+</script>
+
+<template>
+  <div style="width: 240px">
+    <G3Select
+      v-model="userId"
+      :options="users"
+      label-key="name"
+      value-key="id"
+      allow-clear
+      placeholder="选择负责人"
+    />
+  </div>
+</template>
diff --git a/code/g3soft-libs/docs/examples/select/filterable.vue b/code/g3soft-libs/docs/examples/select/filterable.vue
new file mode 100644
index 00000000..79b7cb99
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/select/filterable.vue
@@ -0,0 +1,38 @@
+<script setup lang="ts">
+// filterable 默认开启：直接在触发器输入即可筛选，也支持自定义筛选函数
+import { ref } from 'vue'
+import { G3Select, G3Space } from '@g3soft/ui'
+
+const value = ref<string | undefined>(undefined)
+const keyword = ref<string | undefined>(undefined)
+
+const options = [
+  { label: '北京', value: 'beijing', pinyin: 'beijing' },
+  { label: '上海', value: 'shanghai', pinyin: 'shanghai' },
+  { label: '广州', value: 'guangzhou', pinyin: 'guangzhou' },
+  { label: '深圳', value: 'shenzhen', pinyin: 'shenzhen' },
+]
+
+// 自定义筛选：同时匹配 label 与拼音首字母
+function filterOption(input: string, option: unknown) {
+  const item = option as { label: string; pinyin: string }
+  const text = input.trim().toLowerCase()
+  return item.label.toLowerCase().includes(text) || item.pinyin.includes(text)
+}
+</script>
+
+<template>
+  <G3Space direction="vertical" :size="12" style="display: flex; width: 260px">
+    <!-- 默认筛选：label / value 包含匹配 -->
+    <G3Select v-model="value" :options="options" allow-clear placeholder="输入即可筛选" />
+
+    <!-- 自定义筛选函数 -->
+    <G3Select
+      v-model="keyword"
+      :options="options"
+      :filter-option="filterOption"
+      allow-clear
+      placeholder="支持拼音筛选，试试 bj"
+    />
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/select/load-more.vue b/code/g3soft-libs/docs/examples/select/load-more.vue
new file mode 100644
index 00000000..78193c32
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/select/load-more.vue
@@ -0,0 +1,47 @@
+<script setup lang="ts">
+// 触底加载：列表滚到底部触发 loadMore，footer 插槽放加载提示
+import { onMounted, ref } from 'vue'
+import { G3Select } from '@g3soft/ui'
+
+const value = ref<number | undefined>(undefined)
+const loading = ref(false)
+const options = ref<Array<{ label: string; value: number }>>([])
+const page = ref(0)
+
+function loadPage() {
+  if (loading.value) return
+  loading.value = true
+  setTimeout(() => {
+    page.value += 1
+    const start = (page.value - 1) * 20
+    options.value.push(
+      ...Array.from({ length: 20 }, (_, index) => ({
+        label: `选项 ${start + index + 1}`,
+        value: start + index + 1,
+      })),
+    )
+    loading.value = false
+  }, 400)
+}
+
+// 首次加载放在 onMounted，避免 SSR 阶段访问浏览器 API
+onMounted(loadPage)
+</script>
+
+<template>
+  <div style="width: 240px">
+    <G3Select
+      v-model="value"
+      :options="options"
+      :loading="loading"
+      placeholder="滚动到底部加载更多"
+      @load-more="loadPage"
+    >
+      <template #footer="{ loading: isLoading }">
+        <div style="padding: 6px; color: #6b7280; font-size: 12px; text-align: center">
+          {{ isLoading ? '加载中…' : `已加载 ${options.length} 条` }}
+        </div>
+      </template>
+    </G3Select>
+  </div>
+</template>
diff --git a/code/g3soft-libs/docs/examples/select/multiple.vue b/code/g3soft-libs/docs/examples/select/multiple.vue
new file mode 100644
index 00000000..324f9f4a
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/select/multiple.vue
@@ -0,0 +1,21 @@
+<script setup lang="ts">
+// multiple：值为数组，选中后下拉保持打开；再次点击可取消
+import { ref } from 'vue'
+import { G3Select } from '@g3soft/ui'
+
+const selected = ref<number[]>([1])
+
+const options = [
+  { label: '可读', value: 1 },
+  { label: '可写', value: 2 },
+  { label: '可删除', value: 3 },
+  { label: '可授权', value: 4 },
+]
+</script>
+
+<template>
+  <div style="width: 260px">
+    <G3Select v-model="selected" :options="options" multiple placeholder="选择权限" />
+    <p style="margin: 8px 0 0; font-size: 13px; color: #6b7280">已选：{{ selected }}</p>
+  </div>
+</template>
diff --git a/code/g3soft-libs/docs/examples/select/remote.vue b/code/g3soft-libs/docs/examples/select/remote.vue
new file mode 100644
index 00000000..e03c54fc
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/select/remote.vue
@@ -0,0 +1,40 @@
+<script setup lang="ts">
+// remote：输入时触发 search，选项由父层异步更新；loading 时右侧显示加载图标
+import { ref } from 'vue'
+import { G3Select } from '@g3soft/ui'
+
+const value = ref<string | undefined>(undefined)
+const loading = ref(false)
+const options = ref<Array<{ label: string; value: string }>>([])
+
+let timer = 0
+function onSearch(keyword: string) {
+  window.clearTimeout(timer)
+  loading.value = true
+  // 模拟请求：300ms 后返回结果
+  timer = window.setTimeout(() => {
+    options.value = keyword
+      ? Array.from({ length: 5 }, (_, index) => ({
+          label: `${keyword} 的搜索结果 ${index + 1}`,
+          value: `${keyword}-${index + 1}`,
+        }))
+      : []
+    loading.value = false
+  }, 300)
+}
+</script>
+
+<template>
+  <div style="width: 280px">
+    <G3Select
+      v-model="value"
+      :options="options"
+      :loading="loading"
+      :remote="true"
+      allow-clear
+      not-found-text="输入关键词开始搜索"
+      placeholder="输入后异步搜索"
+      @search="onSearch"
+    />
+  </div>
+</template>
diff --git a/code/g3soft-libs/docs/examples/space/basic.vue b/code/g3soft-libs/docs/examples/space/basic.vue
new file mode 100644
index 00000000..6a6781f9
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/space/basic.vue
@@ -0,0 +1,12 @@
+<script setup lang="ts">
+// 默认 horizontal + small(8px) + 交叉轴 center
+import { G3Button, G3Space } from '@g3soft/ui'
+</script>
+
+<template>
+  <G3Space>
+    <G3Button type="outline" size="small">按钮</G3Button>
+    <G3Button type="outline" size="small">按钮</G3Button>
+    <span style="font-size: 13px; color: #6b7280">文字</span>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/space/empty-children.vue b/code/g3soft-libs/docs/examples/space/empty-children.vue
new file mode 100644
index 00000000..f94b86ed
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/space/empty-children.vue
@@ -0,0 +1,19 @@
+<script setup lang="ts">
+// 空节点（v-if 为 false、注释）不会占位，因此条件渲染不会多出空隙
+import { ref } from 'vue'
+import { G3Button, G3Space, G3Switch } from '@g3soft/ui'
+
+const showDelete = ref(false)
+</script>
+
+<template>
+  <G3Space direction="vertical" :size="12" style="display: flex">
+    <G3Switch v-model="showDelete">显示「删除」按钮</G3Switch>
+    <G3Space :size="8">
+      <G3Button type="outline" size="small">编辑</G3Button>
+      <G3Button type="outline" size="small">复制</G3Button>
+      <!-- 关掉时这里不会留下多余间距 -->
+      <G3Button v-if="showDelete" type="danger-outline" size="small">删除</G3Button>
+    </G3Space>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/space/separator.vue b/code/g3soft-libs/docs/examples/space/separator.vue
new file mode 100644
index 00000000..36a1b16b
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/space/separator.vue
@@ -0,0 +1,16 @@
+<script setup lang="ts">
+// #separator 插槽：在子元素之间插入分隔内容（如竖线、圆点）
+import { G3Button, G3Space } from '@g3soft/ui'
+</script>
+
+<template>
+  <G3Space :size="8">
+    <G3Button type="link" size="small">编辑</G3Button>
+    <G3Button type="link" size="small">复制</G3Button>
+    <G3Button type="link" size="small">删除</G3Button>
+
+    <template #separator>
+      <span style="color: #d9d9d9">|</span>
+    </template>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/space/size.vue b/code/g3soft-libs/docs/examples/space/size.vue
new file mode 100644
index 00000000..30c5708f
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/space/size.vue
@@ -0,0 +1,29 @@
+<script setup lang="ts">
+// size 支持预设名、数字（px）、[水平, 垂直] 数组
+import { G3Button, G3Space } from '@g3soft/ui'
+</script>
+
+<template>
+  <G3Space direction="vertical" :size="16" style="display: flex">
+    <G3Space size="small">
+      <G3Button size="small" type="outline">small 8px</G3Button>
+      <G3Button size="small" type="outline">small 8px</G3Button>
+    </G3Space>
+
+    <G3Space size="middle">
+      <G3Button size="small" type="outline">middle 16px</G3Button>
+      <G3Button size="small" type="outline">middle 16px</G3Button>
+    </G3Space>
+
+    <G3Space size="large">
+      <G3Button size="small" type="outline">large 24px</G3Button>
+      <G3Button size="small" type="outline">large 24px</G3Button>
+    </G3Space>
+
+    <!-- 数字即 px -->
+    <G3Space :size="32">
+      <G3Button size="small" type="outline">32px</G3Button>
+      <G3Button size="small" type="outline">32px</G3Button>
+    </G3Space>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/space/vertical.vue b/code/g3soft-libs/docs/examples/space/vertical.vue
new file mode 100644
index 00000000..866122db
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/space/vertical.vue
@@ -0,0 +1,12 @@
+<script setup lang="ts">
+// 纵向排列：vertical 简写，或 orientation="vertical"
+import { G3Button, G3Space } from '@g3soft/ui'
+</script>
+
+<template>
+  <G3Space vertical :size="8" style="width: 160px; display: flex">
+    <G3Button type="outline" block>第一行</G3Button>
+    <G3Button type="outline" block>第二行</G3Button>
+    <G3Button type="outline" block>第三行</G3Button>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/space/wrap.vue b/code/g3soft-libs/docs/examples/space/wrap.vue
new file mode 100644
index 00000000..6dc343d8
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/space/wrap.vue
@@ -0,0 +1,14 @@
+<script setup lang="ts">
+// wrap 只在水平方向生效；size 用数组可分别控制「列间距 / 行间距」
+import { G3Button, G3Space } from '@g3soft/ui'
+</script>
+
+<template>
+  <div style="width: 240px; padding: 12px; border: 1px dashed #d9d9d9; border-radius: 8px">
+    <G3Space wrap :size="[8, 12]">
+      <G3Button v-for="index in 6" :key="index" type="outline" size="small">
+        按钮 {{ index }}
+      </G3Button>
+    </G3Space>
+  </div>
+</template>
diff --git a/code/g3soft-libs/docs/examples/spin/basic.vue b/code/g3soft-libs/docs/examples/spin/basic.vue
new file mode 100644
index 00000000..20c8e148
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/spin/basic.vue
@@ -0,0 +1,25 @@
+<script setup lang="ts">
+// 包裹模式：spinning 为 true 时给内容加半透明遮罩 + 居中指示器
+import { ref } from 'vue'
+import { G3Button, G3Spin, G3Space } from '@g3soft/ui'
+
+const loading = ref(false)
+
+async function reload() {
+  loading.value = true
+  await new Promise((resolve) => setTimeout(resolve, 1200))
+  loading.value = false
+}
+</script>
+
+<template>
+  <G3Space direction="vertical" :size="12" style="display: flex">
+    <G3Button type="outline" size="small" @click="reload">重新加载</G3Button>
+
+    <G3Spin :spinning="loading">
+      <div style="padding: 24px; border: 1px solid #d9d9d9; border-radius: 8px">
+        被包裹的内容区域：加载中会被遮罩覆盖，并阻止点击。
+      </div>
+    </G3Spin>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/spin/delay.vue b/code/g3soft-libs/docs/examples/spin/delay.vue
new file mode 100644
index 00000000..a2179788
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/spin/delay.vue
@@ -0,0 +1,40 @@
+<script setup lang="ts">
+// delay：请求很快时根本不显示，避免「闪一下」；慢请求才出现
+import { ref } from 'vue'
+import { G3Button, G3Spin, G3Space } from '@g3soft/ui'
+
+const fastLoading = ref(false)
+const slowLoading = ref(false)
+
+async function run(duration: number, target: typeof fastLoading) {
+  target.value = true
+  await new Promise((resolve) => setTimeout(resolve, duration))
+  target.value = false
+}
+</script>
+
+<template>
+  <G3Space direction="vertical" :size="16" style="display: flex">
+    <G3Space :size="8">
+      <G3Button size="small" type="outline" @click="run(200, fastLoading)">200ms 请求</G3Button>
+      <G3Button size="small" type="outline" @click="run(1500, slowLoading)">1500ms 请求</G3Button>
+    </G3Space>
+
+    <G3Spin :spinning="fastLoading" :delay="400" description="fast">
+      <div class="box">短请求：因为 delay=400ms，全程不会闪出加载态</div>
+    </G3Spin>
+
+    <G3Spin :spinning="slowLoading" :delay="400" description="slow">
+      <div class="box">长请求：超过 400ms 后才显示加载态</div>
+    </G3Spin>
+  </G3Space>
+</template>
+
+<style scoped>
+.box {
+  padding: 20px;
+  border: 1px solid #d9d9d9;
+  border-radius: 8px;
+  font-size: 13px;
+}
+</style>
diff --git a/code/g3soft-libs/docs/examples/spin/standalone.vue b/code/g3soft-libs/docs/examples/spin/standalone.vue
new file mode 100644
index 00000000..470fca4d
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/spin/standalone.vue
@@ -0,0 +1,12 @@
+<script setup lang="ts">
+// 不传默认插槽时就是独立指示器；description 在下方显示文案
+import { G3Spin, G3Space } from '@g3soft/ui'
+</script>
+
+<template>
+  <G3Space :size="[32, 16]" align="center" wrap>
+    <G3Spin />
+    <G3Spin description="加载中…" />
+    <G3Spin :delay="300" description="延迟 300ms 才显示" />
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/splitter/basic.vue b/code/g3soft-libs/docs/examples/splitter/basic.vue
new file mode 100644
index 00000000..f6d3c8e1
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/splitter/basic.vue
@@ -0,0 +1,34 @@
+<script setup lang="ts">
+// 最基础：左右分栏。给了 defaultSize 的一侧固定，另一侧自动填充剩余空间
+import { ref } from 'vue'
+import { G3Splitter, G3SplitterPanel } from '@g3soft/ui'
+
+const lastSizes = ref<number[]>([])
+</script>
+
+<template>
+  <div>
+    <G3Splitter
+      style="height: 200px; border: 1px solid #d9d9d9; border-radius: 8px"
+      @resize="(sizes: number[]) => (lastSizes = sizes)"
+    >
+      <G3SplitterPanel :default-size="240">
+        <div class="pane">左侧 240px（可拖拽调整）</div>
+      </G3SplitterPanel>
+      <G3SplitterPanel>
+        <div class="pane">右侧自动填充</div>
+      </G3SplitterPanel>
+    </G3Splitter>
+
+    <p style="margin: 8px 0 0; font-size: 12px; color: #6b7280">
+      面板宽度：{{ lastSizes.join(' / ') || '（拖拽后显示）' }}
+    </p>
+  </div>
+</template>
+
+<style scoped>
+.pane {
+  padding: 16px;
+  font-size: 13px;
+}
+</style>
diff --git a/code/g3soft-libs/docs/examples/splitter/constraints.vue b/code/g3soft-libs/docs/examples/splitter/constraints.vue
new file mode 100644
index 00000000..6cd2898a
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/splitter/constraints.vue
@@ -0,0 +1,33 @@
+<script setup lang="ts">
+// min / max 限制拖拽范围（支持数字 px 或百分比字符串）；resizable=false 的侧边不可被拖动
+import { G3Splitter, G3SplitterPanel, G3Switch, G3Space } from '@g3soft/ui'
+import { ref } from 'vue'
+
+const lockLeft = ref(false)
+</script>
+
+<template>
+  <G3Space direction="vertical" :size="12" style="display: flex">
+    <G3Switch v-model="lockLeft">左侧不可拖动（resizable=false）</G3Switch>
+
+    <G3Splitter style="height: 200px; border: 1px solid #d9d9d9; border-radius: 8px">
+      <G3SplitterPanel :min="160" :max="'50%'" :resizable="!lockLeft" :default-size="240">
+        <div class="pane">左侧：最小 160px，最大 50%</div>
+      </G3SplitterPanel>
+      <G3SplitterPanel :min="200">
+        <div class="pane">右侧：最小 200px</div>
+      </G3SplitterPanel>
+    </G3Splitter>
+
+    <p style="margin: 0; font-size: 12px; color: #6b7280">
+      拖到边界会被钳制住；键盘用户可 Tab 聚焦分割线后用 ← → 调整（Shift 加速）
+    </p>
+  </G3Space>
+</template>
+
+<style scoped>
+.pane {
+  padding: 16px;
+  font-size: 13px;
+}
+</style>
diff --git a/code/g3soft-libs/docs/examples/splitter/nested.vue b/code/g3soft-libs/docs/examples/splitter/nested.vue
new file mode 100644
index 00000000..5c1f96a3
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/splitter/nested.vue
@@ -0,0 +1,30 @@
+<script setup lang="ts">
+// 嵌套：外层左右分栏，右栏内部再上下分栏（经典 IDE 布局）
+import { G3Splitter, G3SplitterPanel } from '@g3soft/ui'
+</script>
+
+<template>
+  <G3Splitter style="height: 320px; border: 1px solid #d9d9d9; border-radius: 8px">
+    <G3SplitterPanel :default-size="200">
+      <div class="pane">侧栏（200px）</div>
+    </G3SplitterPanel>
+
+    <G3SplitterPanel>
+      <G3Splitter direction="vertical">
+        <G3SplitterPanel>
+          <div class="pane">编辑区</div>
+        </G3SplitterPanel>
+        <G3SplitterPanel :default-size="120">
+          <div class="pane">输出 / 控制台（120px）</div>
+        </G3SplitterPanel>
+      </G3Splitter>
+    </G3SplitterPanel>
+  </G3Splitter>
+</template>
+
+<style scoped>
+.pane {
+  padding: 16px;
+  font-size: 13px;
+}
+</style>
diff --git a/code/g3soft-libs/docs/examples/splitter/vertical.vue b/code/g3soft-libs/docs/examples/splitter/vertical.vue
new file mode 100644
index 00000000..350ad5bd
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/splitter/vertical.vue
@@ -0,0 +1,34 @@
+<script setup lang="ts">
+// direction="vertical"：上下分栏，此时用 defaultSize 控制高度
+// barOnHover 默认 true：分割线只在 hover / 聚焦 / 拖拽时显示
+import { G3Space, G3Splitter, G3SplitterPanel, G3Switch } from '@g3soft/ui'
+import { ref } from 'vue'
+
+const barOnHover = ref(true)
+</script>
+
+<template>
+  <G3Space direction="vertical" :size="12" style="display: flex">
+    <G3Switch v-model="barOnHover">分割线仅在 hover / 拖拽时显示</G3Switch>
+
+    <G3Splitter
+      direction="vertical"
+      :bar-on-hover="barOnHover"
+      style="height: 240px; border: 1px solid #d9d9d9; border-radius: 8px"
+    >
+      <G3SplitterPanel :default-size="120">
+        <div class="pane">上：120px</div>
+      </G3SplitterPanel>
+      <G3SplitterPanel>
+        <div class="pane">下：自动填充</div>
+      </G3SplitterPanel>
+    </G3Splitter>
+  </G3Space>
+</template>
+
+<style scoped>
+.pane {
+  padding: 16px;
+  font-size: 13px;
+}
+</style>
diff --git a/code/g3soft-libs/docs/examples/switch/basic.vue b/code/g3soft-libs/docs/examples/switch/basic.vue
new file mode 100644
index 00000000..40ee38bd
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/switch/basic.vue
@@ -0,0 +1,14 @@
+<script setup lang="ts">
+// 最基础用法：v-model 绑 boolean；change 回传新值与原生事件
+import { ref } from 'vue'
+import { G3Switch } from '@g3soft/ui'
+
+const enabled = ref(true)
+</script>
+
+<template>
+  <div>
+    <G3Switch v-model="enabled">启用通知</G3Switch>
+    <p style="margin: 8px 0 0; font-size: 13px; color: #6b7280">状态：{{ enabled ? '开' : '关' }}</p>
+  </div>
+</template>
diff --git a/code/g3soft-libs/docs/examples/switch/disabled.vue b/code/g3soft-libs/docs/examples/switch/disabled.vue
new file mode 100644
index 00000000..d0d24b12
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/switch/disabled.vue
@@ -0,0 +1,12 @@
+<script setup lang="ts">
+// disabled：整项禁用；无文字时按钮本身即开关，有文字时文字可点击（label 语义）
+import { G3Switch, G3Space } from '@g3soft/ui'
+</script>
+
+<template>
+  <G3Space :size="[16, 12]" align="center" wrap>
+    <G3Switch :model-value="false" disabled />
+    <G3Switch :model-value="true" disabled />
+    <G3Switch :model-value="true" disabled>禁用且带文字</G3Switch>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/switch/in-form.vue b/code/g3soft-libs/docs/examples/switch/in-form.vue
new file mode 100644
index 00000000..806bf421
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/switch/in-form.vue
@@ -0,0 +1,25 @@
+<script setup lang="ts">
+// 与 Form 配合：FormItem 负责 label 与校验，Switch 只提供值
+import { reactive } from 'vue'
+import { G3Button, G3Form, G3FormItem, G3Message, G3Switch } from '@g3soft/ui'
+
+const model = reactive({ notify: true, public: false })
+
+function onSubmit(values: Record<string, unknown>) {
+  G3Message.success(`提交：${JSON.stringify(values)}`)
+}
+</script>
+
+<template>
+  <G3Form :model="model" :label-width="96" style="max-width: 360px" @submit="onSubmit">
+    <G3FormItem name="notify" label="接收通知">
+      <G3Switch v-model="model.notify" />
+    </G3FormItem>
+    <G3FormItem name="public" label="公开可见" help="开启后所有成员都能看到该资源">
+      <G3Switch v-model="model.public" />
+    </G3FormItem>
+    <G3FormItem>
+      <G3Button html-type="submit">保存</G3Button>
+    </G3FormItem>
+  </G3Form>
+</template>
diff --git a/code/g3soft-libs/docs/examples/tabs/basic.vue b/code/g3soft-libs/docs/examples/tabs/basic.vue
new file mode 100644
index 00000000..ebd87da1
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/tabs/basic.vue
@@ -0,0 +1,15 @@
+<script setup lang="ts">
+// 声明式：默认插槽里写 G3TabPane，tabKey 唯一标识，label 是标签文字
+import { ref } from 'vue'
+import { G3TabPane, G3Tabs } from '@g3soft/ui'
+
+const active = ref('basic')
+</script>
+
+<template>
+  <G3Tabs v-model="active">
+    <G3TabPane tab-key="basic" label="基本信息">基本信息面板内容</G3TabPane>
+    <G3TabPane tab-key="config" label="配置">配置面板内容</G3TabPane>
+    <G3TabPane tab-key="advanced" label="高级" disabled>禁用项不可切换</G3TabPane>
+  </G3Tabs>
+</template>
diff --git a/code/g3soft-libs/docs/examples/tabs/items.vue b/code/g3soft-libs/docs/examples/tabs/items.vue
new file mode 100644
index 00000000..9139eb08
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/tabs/items.vue
@@ -0,0 +1,17 @@
+<script setup lang="ts">
+// items 数据源：适合标签动态来自接口的场景；content 可以是字符串、VNode 或渲染函数
+import { ref } from 'vue'
+import { G3Tabs } from '@g3soft/ui'
+
+const active = ref('list')
+
+const items = [
+  { key: 'list', label: '列表', content: '列表视图内容' },
+  { key: 'board', label: '看板', content: '看板视图内容' },
+  { key: 'timeline', label: '时间线', content: '时间线视图内容' },
+]
+</script>
+
+<template>
+  <G3Tabs v-model="active" :items="items" />
+</template>
diff --git a/code/g3soft-libs/docs/examples/tabs/nav-only.vue b/code/g3soft-libs/docs/examples/tabs/nav-only.vue
new file mode 100644
index 00000000..007e48f2
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/tabs/nav-only.vue
@@ -0,0 +1,33 @@
+<script setup lang="ts">
+// navOnly：只渲染标签栏，内容区由外部控制（适合配合路由或分栏布局）
+// #label 自定义标签、#leftExtra / #rightExtra 在标签栏两端加内容
+import { ref } from 'vue'
+import { G3Button, G3Tabs } from '@g3soft/ui'
+
+const active = ref('a')
+
+const items = [
+  { key: 'a', label: '标签 A' },
+  { key: 'b', label: '标签 B' },
+]
+</script>
+
+<template>
+  <G3Tabs v-model="active" :items="items" nav-only>
+    <template #leftExtra>
+      <span style="font-size: 13px; color: #6b7280">项目：</span>
+    </template>
+
+    <template #label="{ item }">
+      <span>{{ item === 'a' ? '标签 A（自定义）' : '标签 B' }}</span>
+    </template>
+
+    <template #rightExtra>
+      <G3Button size="small" type="ghost">+ 新建</G3Button>
+    </template>
+  </G3Tabs>
+
+  <div style="padding: 16px 0; color: #6b7280; font-size: 13px">
+    当前激活：{{ active }}（内容由外部渲染）
+  </div>
+</template>
diff --git a/code/g3soft-libs/docs/examples/tabs/placement.vue b/code/g3soft-libs/docs/examples/tabs/placement.vue
new file mode 100644
index 00000000..436b0283
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/tabs/placement.vue
@@ -0,0 +1,15 @@
+<script setup lang="ts">
+// placement：top（默认横排）/ left / right（纵向），指示条会自动贴到对应边
+import { ref } from 'vue'
+import { G3TabPane, G3Tabs } from '@g3soft/ui'
+
+const active = ref('one')
+</script>
+
+<template>
+  <G3Tabs v-model="active" placement="left" style="height: 180px">
+    <G3TabPane tab-key="one" label="概览">概览内容</G3TabPane>
+    <G3TabPane tab-key="two" label="成员">成员内容</G3TabPane>
+    <G3TabPane tab-key="three" label="设置">设置内容</G3TabPane>
+  </G3Tabs>
+</template>
diff --git a/code/g3soft-libs/docs/examples/tabs/type.vue b/code/g3soft-libs/docs/examples/tabs/type.vue
new file mode 100644
index 00000000..1264d936
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/tabs/type.vue
@@ -0,0 +1,21 @@
+<script setup lang="ts">
+// type：line 下划线指示条（默认）/ pill 胶囊；centered 让标签栏居中
+import { ref } from 'vue'
+import { G3Tabs } from '@g3soft/ui'
+
+const line = ref('a')
+const pill = ref('a')
+
+const items = [
+  { key: 'a', label: '全部', content: '全部' },
+  { key: 'b', label: '进行中', content: '进行中' },
+  { key: 'c', label: '已完成', content: '已完成' },
+]
+</script>
+
+<template>
+  <div style="display: flex; flex-direction: column; gap: 20px">
+    <G3Tabs v-model="line" :items="items" centered />
+    <G3Tabs v-model="pill" :items="items" type="pill" />
+  </div>
+</template>
diff --git a/code/g3soft-libs/docs/examples/tag/closable.vue b/code/g3soft-libs/docs/examples/tag/closable.vue
new file mode 100644
index 00000000..a474ee1e
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/tag/closable.vue
@@ -0,0 +1,22 @@
+<script setup lang="ts">
+// closable：点击关闭按钮后标签**自动隐藏**并从列表里移除
+import { ref } from 'vue'
+import { G3Space, G3Tag } from '@g3soft/ui'
+
+const tags = ref(['设计', '前端', '规范'])
+</script>
+
+<template>
+  <G3Space :size="[8, 8]" wrap>
+    <G3Tag
+      v-for="tag in tags"
+      :key="tag"
+      variant="secondary"
+      closable
+      @close="tags = tags.filter((item) => item !== tag)"
+    >
+      {{ tag }}
+    </G3Tag>
+    <G3Tag v-if="!tags.length" variant="ghost">已全部移除</G3Tag>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/tag/icon.vue b/code/g3soft-libs/docs/examples/tag/icon.vue
new file mode 100644
index 00000000..b24cab9d
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/tag/icon.vue
@@ -0,0 +1,25 @@
+<script setup lang="ts">
+// #icon 放前置图标；#close-icon 可以换成自定义关闭图标
+import { G3Space, G3Tag } from '@g3soft/ui'
+import { CircleCheck, Clock, User } from '@lucide/vue'
+</script>
+
+<template>
+  <G3Space :size="[8, 8]" wrap>
+    <G3Tag variant="success">
+      <template #icon><CircleCheck /></template>
+      已完成
+    </G3Tag>
+
+    <G3Tag variant="outline">
+      <template #icon><Clock /></template>
+      等待中
+    </G3Tag>
+
+    <G3Tag variant="secondary" closable>
+      <template #icon><User /></template>
+      张三
+      <template #close-icon><span style="font-size: 12px">×</span></template>
+    </G3Tag>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/tag/link.vue b/code/g3soft-libs/docs/examples/tag/link.vue
new file mode 100644
index 00000000..f6669475
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/tag/link.vue
@@ -0,0 +1,11 @@
+<script setup lang="ts">
+// href：渲染成 <a>，可点击跳转；disabled 时去掉 href 并标记 aria-disabled
+import { G3Space, G3Tag } from '@g3soft/ui'
+</script>
+
+<template>
+  <G3Space :size="[8, 8]" wrap>
+    <G3Tag href="https://www.nuxt.com" target="_blank" variant="outline">可点击标签</G3Tag>
+    <G3Tag href="https://www.nuxt.com" variant="outline" disabled>禁用标签</G3Tag>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/tag/prevent-close.vue b/code/g3soft-libs/docs/examples/tag/prevent-close.vue
new file mode 100644
index 00000000..9bc903f5
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/tag/prevent-close.vue
@@ -0,0 +1,20 @@
+<script setup lang="ts">
+// 在 close 事件里调用 preventDefault()，可以阻止标签自动隐藏（受控用法）
+import { ref } from 'vue'
+import { G3Message, G3Space, G3Tag } from '@g3soft/ui'
+
+const visible = ref(true)
+
+function onClose(event: Event) {
+  event.preventDefault() // 不自动隐藏，交给业务决定
+  G3Message.warning('已阻止自动关闭，请在事件里自行控制')
+}
+</script>
+
+<template>
+  <G3Space :size="8">
+    <G3Tag :key="String(visible)" closable @close="onClose">
+      {{ visible ? '受控标签' : '已关闭' }}
+    </G3Tag>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/tag/variant.vue b/code/g3soft-libs/docs/examples/tag/variant.vue
new file mode 100644
index 00000000..9f920553
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/tag/variant.vue
@@ -0,0 +1,15 @@
+<script setup lang="ts">
+// 6 种视觉变体：default / secondary / outline / success / danger / ghost
+import { G3Space, G3Tag } from '@g3soft/ui'
+</script>
+
+<template>
+  <G3Space :size="[8, 8]" wrap>
+    <G3Tag>默认</G3Tag>
+    <G3Tag variant="secondary">次要</G3Tag>
+    <G3Tag variant="outline">描边</G3Tag>
+    <G3Tag variant="success">已完成</G3Tag>
+    <G3Tag variant="danger">失败</G3Tag>
+    <G3Tag variant="ghost">幽灵</G3Tag>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/tooltip/basic.vue b/code/g3soft-libs/docs/examples/tooltip/basic.vue
new file mode 100644
index 00000000..8acb8b18
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/tooltip/basic.vue
@@ -0,0 +1,10 @@
+<script setup lang="ts">
+// 最基础：content 传文本，默认在触发器上方
+import { G3Button, G3Tooltip } from '@g3soft/ui'
+</script>
+
+<template>
+  <G3Tooltip content="这是一条简短说明">
+    <G3Button type="outline">悬停查看提示</G3Button>
+  </G3Tooltip>
+</template>
diff --git a/code/g3soft-libs/docs/examples/tooltip/disabled.vue b/code/g3soft-libs/docs/examples/tooltip/disabled.vue
new file mode 100644
index 00000000..409b378f
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/tooltip/disabled.vue
@@ -0,0 +1,26 @@
+<script setup lang="ts">
+// 受控与禁用：disabled 时不响应 hover；也可以用 open 手动控制
+import { ref } from 'vue'
+import { G3Button, G3Space, G3Switch, G3Tooltip } from '@g3soft/ui'
+
+const enabled = ref(true)
+const open = ref(false)
+</script>
+
+<template>
+  <G3Space direction="vertical" :size="16" style="display: flex">
+    <G3Space :size="8" align="center">
+      <G3Switch v-model="enabled">启用提示</G3Switch>
+      <G3Tooltip :disabled="!enabled" content="现在可以看到了">
+        <G3Button type="outline">悬停试试</G3Button>
+      </G3Tooltip>
+    </G3Space>
+
+    <G3Space :size="8" align="center">
+      <G3Switch v-model="open">受控显示</G3Switch>
+      <G3Tooltip :open="open" content="由 open 控制，不受 hover 影响">
+        <G3Button type="outline">受控提示</G3Button>
+      </G3Tooltip>
+    </G3Space>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/tooltip/placement.vue b/code/g3soft-libs/docs/examples/tooltip/placement.vue
new file mode 100644
index 00000000..fe4bf382
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/tooltip/placement.vue
@@ -0,0 +1,14 @@
+<script setup lang="ts">
+// placement：提示方位；贴边时自动翻转，不会被裁掉
+import { G3Button, G3Tooltip } from '@g3soft/ui'
+
+const placements = ['top', 'right', 'bottom', 'left'] as const
+</script>
+
+<template>
+  <div style="display: flex; gap: 16px; padding: 60px 20px; justify-content: center">
+    <G3Tooltip v-for="placement in placements" :key="placement" :placement="placement" :content="placement">
+      <G3Button type="outline">{{ placement }}</G3Button>
+    </G3Tooltip>
+  </div>
+</template>
diff --git a/code/g3soft-libs/docs/examples/tooltip/rich.vue b/code/g3soft-libs/docs/examples/tooltip/rich.vue
new file mode 100644
index 00000000..40960c5a
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/tooltip/rich.vue
@@ -0,0 +1,20 @@
+<script setup lang="ts">
+// #content 插槽：放富内容（多行说明、快捷键、链接）
+import { G3Button, G3Tooltip } from '@g3soft/ui'
+</script>
+
+<template>
+  <G3Tooltip placement="bottom">
+    <G3Button type="ghost">富内容提示</G3Button>
+
+    <template #content>
+      <div style="max-width: 240px; line-height: 1.6">
+        <strong style="display: block; margin-bottom: 4px">发布到生产环境</strong>
+        <span style="color: #6b7280">
+          会触发全量构建与灰度发布，平均耗时 3 分钟。快捷键
+          <kbd>⌘ + Shift + P</kbd>
+        </span>
+      </div>
+    </template>
+  </G3Tooltip>
+</template>
diff --git a/code/g3soft-libs/docs/examples/tree/basic.vue b/code/g3soft-libs/docs/examples/tree/basic.vue
new file mode 100644
index 00000000..b3d268ee
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/tree/basic.vue
@@ -0,0 +1,27 @@
+<script setup lang="ts">
+// 最基础：treeData 是嵌套结构，默认按 { key, title, children } 取值
+import { ref } from 'vue'
+import { G3Tree, type TreeNodeData } from '@g3soft/ui'
+
+const treeData: TreeNodeData[] = [
+  {
+    key: 'design',
+    title: '设计',
+    children: [
+      { key: 'design/ui', title: 'UI 规范' },
+      { key: 'design/icon', title: '图标库' },
+    ],
+  },
+  { key: 'frontend', title: '前端' },
+  { key: 'backend', title: '后端' },
+]
+
+const selectedKeys = ref<string[]>(['design/ui'])
+</script>
+
+<template>
+  <div style="max-width: 320px">
+    <G3Tree v-model:selected-keys="selectedKeys" :tree-data="treeData" default-expand-all />
+    <p style="margin: 8px 0 0; font-size: 13px; color: #6b7280">选中：{{ selectedKeys.join(', ') || '无' }}</p>
+  </div>
+</template>
diff --git a/code/g3soft-libs/docs/examples/tree/checkable.vue b/code/g3soft-libs/docs/examples/tree/checkable.vue
new file mode 100644
index 00000000..8ebe92d7
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/tree/checkable.vue
@@ -0,0 +1,36 @@
+<script setup lang="ts">
+// checkable：父子联动；checkStrictly 时父子互不影响（右侧）
+import { ref } from 'vue'
+import { G3Space, G3Tree, type TreeNodeData } from '@g3soft/ui'
+
+const treeData: TreeNodeData[] = [
+  {
+    key: 'role',
+    title: '角色权限',
+    children: [
+      { key: 'read', title: '查看' },
+      { key: 'write', title: '编辑' },
+      { key: 'delete', title: '删除' },
+    ],
+  },
+]
+
+const linked = ref<string[]>(['read'])
+const strict = ref<string[]>(['read'])
+</script>
+
+<template>
+  <G3Space :size="32" wrap align="start">
+    <div style="width: 240px">
+      <p style="margin: 0 0 8px; font-size: 13px; color: #6b7280">父子联动（半选会回传）</p>
+      <G3Tree v-model:checked-keys="linked" :tree-data="treeData" checkable default-expand-all block-node />
+      <p style="margin: 8px 0 0; font-size: 12px">checked: {{ linked }}</p>
+    </div>
+
+    <div style="width: 240px">
+      <p style="margin: 0 0 8px; font-size: 13px; color: #6b7280">checkStrictly（互不影响）</p>
+      <G3Tree v-model:checked-keys="strict" :tree-data="treeData" checkable check-strictly default-expand-all block-node />
+      <p style="margin: 8px 0 0; font-size: 12px">checked: {{ strict }}</p>
+    </div>
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/tree/context-menu.vue b/code/g3soft-libs/docs/examples/tree/context-menu.vue
new file mode 100644
index 00000000..4885d603
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/tree/context-menu.vue
@@ -0,0 +1,44 @@
+<script setup lang="ts">
+// contextMenu：右键节点或空白处弹出菜单；菜单点击通过 contextMenuClick 回传
+import { ref } from 'vue'
+import { G3Message, G3Tree, type TreeContextMenuItem, type TreeNodeData } from '@g3soft/ui'
+import { Copy, Pencil, Trash2 } from '@lucide/vue'
+
+const treeData: TreeNodeData[] = [
+  { key: 'a', title: '文档 A' },
+  { key: 'b', title: '文档 B' },
+]
+
+const lastAction = ref('暂无')
+
+// 用函数形式：可以按节点动态生成菜单（node 为 null 表示在空白处右键）
+function contextMenu(node: TreeNodeData | null): TreeContextMenuItem[] {
+  if (!node) {
+    return [{ key: 'create', label: '新建文档' }]
+  }
+  return [
+    { key: 'rename', label: '重命名', icon: Pencil },
+    { key: 'copy', label: '复制', icon: Copy },
+    { divider: true },
+    { key: 'delete', label: '删除', icon: Trash2, danger: true },
+  ]
+}
+
+function onMenuClick(info: { item: TreeContextMenuItem; node: TreeNodeData | null }) {
+  lastAction.value = `${info.node ? info.node.title : '空白处'} → ${info.item.label}`
+  G3Message.info(lastAction.value)
+}
+</script>
+
+<template>
+  <div style="max-width: 320px">
+    <G3Tree
+      :tree-data="treeData"
+      :context-menu="contextMenu"
+      default-expand-all
+      block-node
+      @context-menu-click="onMenuClick"
+    />
+    <p style="margin: 8px 0 0; font-size: 12px; color: #6b7280">{{ lastAction }}</p>
+  </div>
+</template>
diff --git a/code/g3soft-libs/docs/examples/tree/custom.vue b/code/g3soft-libs/docs/examples/tree/custom.vue
new file mode 100644
index 00000000..74dba292
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/tree/custom.vue
@@ -0,0 +1,53 @@
+<script setup lang="ts">
+// fieldNames 适配后端结构；#title 插槽自定义节点渲染；节点字段可控制图标/禁用
+import { ref } from 'vue'
+import { G3Button, G3Tag, G3Tree, type TreeNodeData } from '@g3soft/ui'
+import { Folder, FileText } from '@lucide/vue'
+
+// 后端字段：id / name / nodes
+const treeData = ref<TreeNodeData[]>([
+  {
+    id: 'f1',
+    name: '设计稿',
+    icon: Folder,
+    nodes: [
+      { id: 'f1-1', name: '首页.sketch', icon: FileText },
+      { id: 'f1-2', name: '详情页.sketch', icon: FileText, disabled: true },
+    ],
+  },
+  { id: 'f2', name: '需求文档.md', icon: FileText },
+])
+
+const selectedKeys = ref<string[]>([])
+</script>
+
+<template>
+  <div style="max-width: 360px">
+    <G3Tree
+      v-model:selected-keys="selectedKeys"
+      :tree-data="treeData"
+      :field-names="{ key: 'id', title: 'name', children: 'nodes' }"
+      default-expand-all
+      block-node
+    >
+      <!-- #title 插槽：node 是原始数据，可自由渲染 -->
+      <template #title="{ node, selected }">
+        <span style="display: inline-flex; align-items: center; gap: 8px; width: 100%">
+          <span>{{ node.name }}</span>
+          <G3Tag v-if="selected" variant="secondary">当前</G3Tag>
+          <G3Button
+            v-if="!node.disabled"
+            size="small"
+            type="link"
+            style="margin-left: auto"
+            @click.stop="selectedKeys = [String(node.id)]"
+          >
+            选中
+          </G3Button>
+        </span>
+      </template>
+    </G3Tree>
+
+    <p style="margin: 8px 0 0; font-size: 12px; color: #6b7280">选中：{{ selectedKeys.join(', ') || '无' }}</p>
+  </div>
+</template>
diff --git a/code/g3soft-libs/docs/examples/tree/draggable.vue b/code/g3soft-libs/docs/examples/tree/draggable.vue
new file mode 100644
index 00000000..727098c7
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/tree/draggable.vue
@@ -0,0 +1,73 @@
+<script setup lang="ts">
+// draggable：拖到行的上/下 25% 是「前/后插入」，中间是「放入内部」
+// drop 事件里自己重排数据（组件不直接改 treeData）
+import { ref } from 'vue'
+import { G3Message, G3Tree, type TreeNodeData } from '@g3soft/ui'
+
+const treeData = ref<TreeNodeData[]>([
+  { key: '1', title: '第一项' },
+  { key: '2', title: '第二项' },
+  {
+    key: '3',
+    title: '第三项（可拖入）',
+    children: [{ key: '3-1', title: '子项' }],
+  },
+])
+
+function findNode(nodes: TreeNodeData[], key: string): TreeNodeData | null {
+  for (const node of nodes) {
+    if (String(node.key) === key) return node
+    const found = node.children ? findNode(node.children, key) : null
+    if (found) return found
+  }
+  return null
+}
+
+function removeNode(nodes: TreeNodeData[], key: string): TreeNodeData | null {
+  const index = nodes.findIndex((node) => String(node.key) === key)
+  if (index >= 0) return nodes.splice(index, 1)[0]
+  for (const node of nodes) {
+    if (node.children) {
+      const removed = removeNode(node.children, key)
+      if (removed) return removed
+    }
+  }
+  return null
+}
+
+function onDrop(info: { dragKey: string | number; dropKey: string | number; dropPosition: string }) {
+  const dragKey = String(info.dragKey)
+  const dropKey = String(info.dropKey)
+  const data = treeData.value
+  const moved = removeNode(data, dragKey)
+  if (!moved) return
+
+  if (info.dropPosition === 'inside') {
+    const target = findNode(data, dropKey)
+    if (target) {
+      target.children = [...(target.children ?? []), moved]
+      G3Message.success(`已移动到「${target.title}」内部`)
+    }
+  } else {
+    const insert = (nodes: TreeNodeData[]): boolean => {
+      const index = nodes.findIndex((node) => String(node.key) === dropKey)
+      if (index >= 0) {
+        nodes.splice(info.dropPosition === 'before' ? index : index + 1, 0, moved)
+        return true
+      }
+      return nodes.some((node) => (node.children ? insert(node.children) : false))
+    }
+    insert(data)
+    G3Message.success(`已${info.dropPosition === 'before' ? '前移' : '后移'}到「${dropKey}」`)
+  }
+
+  treeData.value = [...data]
+}
+</script>
+
+<template>
+  <div style="max-width: 320px">
+    <G3Tree :tree-data="treeData" draggable default-expand-all block-node @drop="onDrop" />
+    <p style="margin: 8px 0 0; font-size: 12px; color: #6b7280">拖拽任意节点试试（子节点不能拖进自己的子树）</p>
+  </div>
+</template>
diff --git a/code/g3soft-libs/docs/examples/tree/expand.vue b/code/g3soft-libs/docs/examples/tree/expand.vue
new file mode 100644
index 00000000..f5e214ef
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/tree/expand.vue
@@ -0,0 +1,40 @@
+<script setup lang="ts">
+// 展开状态：受控 expandedKeys（传了就是受控）与非受控默认值
+import { ref } from 'vue'
+import { G3Button, G3Space, G3Tree, type TreeNodeData } from '@g3soft/ui'
+
+const treeData: TreeNodeData[] = [
+  {
+    key: 'a',
+    title: 'A 组',
+    children: [
+      { key: 'a1', title: 'A-1', children: [{ key: 'a11', title: 'A-1-1' }] },
+      { key: 'a2', title: 'A-2' },
+    ],
+  },
+  { key: 'b', title: 'B 组', children: [{ key: 'b1', title: 'B-1' }] },
+]
+
+// 受控：所有展开/收起都要经过 update:expandedKeys
+const expandedKeys = ref<string[]>(['a', 'a1'])
+
+function expandAll() {
+  expandedKeys.value = ['a', 'a1', 'a2', 'b', 'b1']
+}
+
+function collapseAll() {
+  expandedKeys.value = []
+}
+</script>
+
+<template>
+  <G3Space direction="vertical" :size="12" style="display: flex; max-width: 320px">
+    <G3Space :size="8">
+      <G3Button size="small" type="outline" @click="expandAll">全部展开</G3Button>
+      <G3Button size="small" type="outline" @click="collapseAll">全部收起</G3Button>
+    </G3Space>
+
+    <!-- 传了 expanded-keys 即受控；双击节点也能展开（会走 update 事件） -->
+    <G3Tree v-model:expanded-keys="expandedKeys" :tree-data="treeData" block-node />
+  </G3Space>
+</template>
diff --git a/code/g3soft-libs/docs/examples/tree/filter.vue b/code/g3soft-libs/docs/examples/tree/filter.vue
new file mode 100644
index 00000000..e650e24d
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/tree/filter.vue
@@ -0,0 +1,35 @@
+<script setup lang="ts">
+// filter：命中节点与它的祖先都会显示，命中的文字会被高亮，且自动展开命中路径
+import { ref } from 'vue'
+import { G3Input, G3Tree, type TreeNodeData } from '@g3soft/ui'
+
+const treeData: TreeNodeData[] = [
+  {
+    key: 'module',
+    title: '模块管理',
+    children: [
+      { key: 'module/list', title: '模块列表' },
+      { key: 'module/field', title: '字段设计' },
+    ],
+  },
+  {
+    key: 'system',
+    title: '系统管理',
+    children: [
+      { key: 'system/user', title: '用户管理' },
+      { key: 'system/role', title: '角色权限' },
+    ],
+  },
+]
+
+const keyword = ref('')
+</script>
+
+<template>
+  <div style="max-width: 320px">
+    <G3Input v-model="keyword" allow-clear placeholder="输入关键词，如「管理」" style="margin-bottom: 8px" />
+    <G3Tree :tree-data="treeData" :filter="keyword" default-expand-all block-node>
+      <template #empty>没有匹配的节点</template>
+    </G3Tree>
+  </div>
+</template>
diff --git a/code/g3soft-libs/docs/examples/tree/lazy.vue b/code/g3soft-libs/docs/examples/tree/lazy.vue
new file mode 100644
index 00000000..292dfade
--- /dev/null
+++ b/code/g3soft-libs/docs/examples/tree/lazy.vue
@@ -0,0 +1,30 @@
+<script setup lang="ts">
+// lazy + load：首次展开没有子节点的节点时请求数据，父层把 children 写回并把 key 记入 loadedKeys
+import { ref } from 'vue'
+import { G3Tree, type TreeNodeData } from '@g3soft/ui'
+
+const treeData = ref<TreeNodeData[]>([
+  { key: 'org-1', title: '总公司' },
+  { key: 'org-2', title: '分公司' },
+])
+
+const loadedKeys = ref<string[]>([])
+
+async function onLoad(node: TreeNodeData) {
+  // 模拟请求：200ms 后返回子节点
+  await new Promise((resolve) => setTimeout(resolve, 200))
+  node.children = [
+    { key: `${node.key}-a`, title: `${node.title} / 部门 A` },
+    { key: `${node.key}-b`, title: `${node.title} / 部门 B` },
+  ]
+  treeData.value = [...treeData.value]
+  loadedKeys.value = [...loadedKeys.value, String(node.key)]
+}
+</script>
+
+<template>
+  <div style="max-width: 320px">
+    <G3Tree v-model:loaded-keys="loadedKeys" :tree-data="treeData" lazy block-node @load="onLoad" />
+    <p style="margin: 8px 0 0; font-size: 12px; color: #6b7280">已加载：{{ loadedKeys.join(', ') || '无' }}</p>
+  </div>
+</template>
diff --git a/code/g3soft-libs/docs/nuxt.config.ts b/code/g3soft-libs/docs/nuxt.config.ts
index a9db24e5..e3b689f5 100644
--- a/code/g3soft-libs/docs/nuxt.config.ts
+++ b/code/g3soft-libs/docs/nuxt.config.ts
@@ -35,6 +35,13 @@ export default defineNuxtConfig({
           find: /^@g3soft\/ui$/,
           replacement: fileURLToPath(new URL('../packages/ui/src/index.ts', import.meta.url)),
         },
+        {
+          // framework 也直连源码：改布局 / 偏好即时热更
+          find: /^@g3soft\/framework$/,
+          replacement: fileURLToPath(
+            new URL('../packages/framework/src/index.ts', import.meta.url),
+          ),
+        },
         {
           // tokens 是 SCSS 编译产物：仅裸导入指向 dist/index.css（由 @g3soft/tokens 的 build 生成）
           find: /^@g3soft\/tokens$/,
diff --git a/code/g3soft-libs/package.json b/code/g3soft-libs/package.json
index 5061bdc9..d616ea74 100644
--- a/code/g3soft-libs/package.json
+++ b/code/g3soft-libs/package.json
@@ -12,14 +12,16 @@
     "build:docs": "pnpm --filter @g3soft/tokens build && pnpm --filter @g3soft/docs generate",
     "preview:docs": "pnpm --filter @g3soft/docs preview",
     "build": "pnpm -r --filter \"./packages/**\" build",
-    "gen:api": "node scripts/gen-api.mjs",
     "changeset": "changeset",
     "version": "changeset version",
-    "release": "pnpm build && changeset publish"
+    "release": "pnpm build && changeset publish",
+    "playground": "pnpm --filter @g3soft/ui playground",
+    "test": "pnpm --filter @g3soft/ui test:unit",
+    "test:e2e": "pnpm --filter @g3soft/ui test:e2e",
+    "verify": "pnpm --filter @g3soft/tokens build && pnpm --filter @g3soft/ui verify"
   },
   "devDependencies": {
     "@changesets/cli": "^2.29.0",
-    "typescript": "catalog:",
-    "vue-docgen-api": "^4.79.0"
+    "typescript": "catalog:"
   }
 }
diff --git a/code/g3soft-libs/packages/framework/README.md b/code/g3soft-libs/packages/framework/README.md
new file mode 100644
index 00000000..d548af9a
--- /dev/null
+++ b/code/g3soft-libs/packages/framework/README.md
@@ -0,0 +1,83 @@
+# @g3soft/framework
+
+G3Soft 前端框架。目标：**基础架子一处维护，留好插槽和接口，业务项目引用方便，既不绑死又灵活。**
+
+## 设计原则
+
+> framework 提供「骨架 + 契约」，业务负责「填充」；依赖单向 `host → framework`，framework 永不 import 业务代码。
+
+- **三层契约**：配置契约（`G3FrameworkOptions`）/ 数据契约（`NavItem`、`G3RouteMeta`、`UserInfo`）/ UI 契约（slots + emits）。
+- **一切外部信息靠注入**：菜单、用户、token、跳转都由宿主提供，framework 内部零业务依赖。
+- **默认能跑**：零配置即可启动（默认 `sidebar-nav` + 浅色），配置与插槽均为可选增强。
+
+## 归属边界
+
+| 层 | 内容 | 说明 |
+|---|---|---|
+| `core` | 布局（7 种模式）、偏好模型、契约类型 | 后端无关，只依赖 `vue`(peer) + `@g3soft/ui` |
+| `presets/*` | 传输、`ApiResponse` 解包、`/data/*` client、默认菜单源 | **后续接入**，可选，import 才生效 |
+| 项目 | 业务接口、业务页面 | —— |
+
+**铁律**：`core` 里绝不出现具体后端名（如 `s_menu`、`/data/loaddata`、`ApiResponse`）；一旦出现，它就该在 `presets`。
+
+## 当前进度
+
+- [x] core 类型契约（数据 / 配置 / UI 三类）
+- [x] 偏好层：`defaultPreferences` / `usePreferences`（reactive 单例，无需 pinia）/ 持久化 / `applyThemeVars`
+- [x] `createG3Framework`（`app.use()` 一次初始化）
+- [x] 布局子组件：Logo / 递归 Menu（垂直+水平）/ Sidebar（单列+双列，含折叠按钮、拖拽调宽、悬浮展开）/ Header / Breadcrumb / Tabbar
+- [x] `G3Layout` 编排 7 种模式（模式配置表驱动）
+- [ ] 偏好抽屉面板
+- [ ] 接线层 `G3AdminLayout`（接 router / 页签状态 / 用户菜单）
+- [ ] 接口层 preset（`/request` + g3-backend + 默认菜单源）
+
+布局结构与交互对齐 [vben-admin](https://github.com/vbenjs/vue-vben-admin) 的 `layout-ui`，样式改写为 `--g3-*` 变量 + `g3-` 前缀（**不引入 Tailwind**，业务项目零额外配置）。
+
+## 使用
+
+```ts
+// main.ts —— 初始化（可选）
+import { createG3Framework } from '@g3soft/framework'
+app.use(
+  createG3Framework({
+    preferences: { app: { layout: 'sidebar-nav' }, theme: { colorPrimary: '#2563eb' } },
+    storageKey: 'g3-preferences',
+  }),
+)
+```
+
+```vue
+<script setup lang="ts">
+import { G3Layout, type NavItem } from '@g3soft/framework'
+
+const menus: NavItem[] = [
+  { key: 'home', title: '工作台', path: '/' },
+  { key: 'sys', title: '系统管理', children: [{ key: 'user', title: '用户', path: '/sys/user' }] },
+]
+</script>
+
+<template>
+  <G3Layout layout="sidebar-nav" :menus="menus" :active-key="$route.path" @navigate="onNavigate">
+    <template #header-right><!-- 用户菜单 --></template>
+    <template #page><RouterView /></template>
+  </G3Layout>
+</template>
+```
+
+菜单数据由宿主注入（`:menus` 直接给数组，或 `:menu-source` 给函数），framework 不关心来源。
+
+## 偏好与主题
+
+- `usePreferences()`：读偏好（只读响应式）、`update(patch)` / `setLayout()` / `toggleSidebar()`。
+- 偏好状态是**模块级 reactive 单例**，不依赖 pinia；持久化用 `localStorage`（SSR 安全）。
+- 主题唯一输出仍是 `@g3soft/ui` 的 `ConfigProvider → derivePalette → --g3-*`；`radius` / `fontSize` / 布局尺寸写入 CSS 变量。
+
+## 归属边界
+
+| 层 | 内容 | 说明 |
+|---|---|---|
+| `core` | 布局（7 种模式）、偏好、契约类型 | 后端无关，只依赖 `vue`(peer) + `@g3soft/ui` |
+| `presets/*` | 传输、`ApiResponse` 解包、`/data/*` client、默认菜单源 | **后续接入**，可选，import 才生效 |
+| 项目 | 业务接口、业务页面 | —— |
+
+**铁律**：`core` 里绝不出现具体后端名（如 `s_menu`、`/data/loaddata`、`ApiResponse`）；一旦出现，它就该在 `presets`。
diff --git a/code/g3soft-libs/packages/framework/package.json b/code/g3soft-libs/packages/framework/package.json
new file mode 100644
index 00000000..db63acb7
--- /dev/null
+++ b/code/g3soft-libs/packages/framework/package.json
@@ -0,0 +1,47 @@
+{
+  "name": "@g3soft/framework",
+  "version": "0.0.1",
+  "description": "G3Soft 前端框架：布局骨架 + 偏好设置，供业务项目引用（core 先行，接口层后续以 preset 形式接入）",
+  "license": "UNLICENSED",
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./core": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./style.css": "./dist/style.css",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "vite build",
+    "prepublishOnly": "publint"
+  },
+  "peerDependencies": {
+    "vue": "^3.5.0"
+  },
+  "dependencies": {
+    "@g3soft/ui": "workspace:*"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-vue": "^6.0.0",
+    "publint": "latest",
+    "vite": "^8.0.0",
+    "vite-plugin-dts": "latest",
+    "vue": "catalog:",
+    "vue-tsc": "^3.0.0"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  }
+}
diff --git a/code/g3soft-libs/packages/framework/src/core/_utils/deep-merge.ts b/code/g3soft-libs/packages/framework/src/core/_utils/deep-merge.ts
new file mode 100644
index 00000000..6ad1f5d1
--- /dev/null
+++ b/code/g3soft-libs/packages/framework/src/core/_utils/deep-merge.ts
@@ -0,0 +1,38 @@
+/** 是否为「普通对象」（排除数组 / null） */
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/**
+ * 深合并：把 source 递归覆盖到 target（就地修改并返回 target）。
+ * undefined 视为「未提供」，不覆盖；数组整体替换。
+ */
+export function deepMerge<T extends Record<string, unknown>>(
+  target: T,
+  source?: Partial<T> | Record<string, unknown>,
+): T {
+  if (!isPlainObject(source)) return target
+  for (const key of Object.keys(source)) {
+    const next = (source as Record<string, unknown>)[key]
+    if (next === undefined) continue
+    const current = (target as Record<string, unknown>)[key]
+    if (isPlainObject(next) && isPlainObject(current)) {
+      deepMerge(current, next)
+    } else {
+      ;(target as Record<string, unknown>)[key] = next
+    }
+  }
+  return target
+}
+
+/** 深克隆（结构化克隆优先，退回 JSON） */
+export function deepClone<T>(value: T): T {
+  if (typeof structuredClone === 'function') {
+    try {
+      return structuredClone(value)
+    } catch {
+      /* 含不可克隆值时退回 JSON */
+    }
+  }
+  return JSON.parse(JSON.stringify(value)) as T
+}
diff --git a/code/g3soft-libs/packages/framework/src/core/index.ts b/code/g3soft-libs/packages/framework/src/core/index.ts
new file mode 100644
index 00000000..e5a23f8d
--- /dev/null
+++ b/code/g3soft-libs/packages/framework/src/core/index.ts
@@ -0,0 +1,75 @@
+// core：布局骨架 + 偏好 + 契约类型。后端无关，依赖仅 vue(peer) + @g3soft/ui。
+// 接口层（request / ApiResponse 解包 / 默认菜单源）不在 core，后续以 preset 形式接入。
+
+// —— 布局 ——
+export {
+  G3Layout,
+  G3LayoutBreadcrumb,
+  G3LayoutHeader,
+  G3LayoutLogo,
+  G3LayoutMenu,
+  G3LayoutSidebar,
+  G3LayoutTabbar,
+  layoutContextKey,
+  layoutLabels,
+  layoutModes,
+  useLayoutContext,
+} from './layout'
+export type { LayoutContext, LayoutModeConfig } from './layout'
+
+// —— 偏好 ——
+export {
+  DEFAULT_STORAGE_KEY,
+  applyDataTheme,
+  applyThemeVars,
+  builtinPalettes,
+  defaultPreferences,
+  defaultSizes,
+  resolveDark,
+  setupPreferences,
+  toCssLength,
+  usePreferences,
+} from './preferences'
+export type { G3PreferencesApi } from './preferences'
+
+// —— 安装 ——
+export { createG3Framework } from './install'
+export type { G3Framework } from './install'
+
+// —— 数据契约 ——
+export type {
+  G3LayoutProps,
+  G3RouteMeta,
+  G3TabItem,
+  LayoutComponentOverrides,
+  LayoutSizes,
+  LayoutType,
+  MenuSource,
+  NavItem,
+  UserInfo,
+} from './types/layout'
+
+// —— 配置契约 ——
+export type {
+  AppPreferences,
+  BreadcrumbPreferences,
+  BreadcrumbStyleType,
+  ContentPreferences,
+  DeepPartial,
+  FooterPreferences,
+  G3FrameworkOptions,
+  G3Preferences,
+  HeaderMode,
+  HeaderPreferences,
+  LogoPreferences,
+  NavigationPreferences,
+  NavigationStyleType,
+  SidebarPreferences,
+  TabbarPreferences,
+  TabbarStyleType,
+  ThemeMode,
+  ThemePreferences,
+} from './types/preferences'
+
+// —— UI 契约 ——
+export type { G3LayoutEmits, G3LayoutSlots } from './types/slots'
diff --git a/code/g3soft-libs/packages/framework/src/core/install.ts b/code/g3soft-libs/packages/framework/src/core/install.ts
new file mode 100644
index 00000000..9fe3d1c6
--- /dev/null
+++ b/code/g3soft-libs/packages/framework/src/core/install.ts
@@ -0,0 +1,39 @@
+import type { App } from 'vue'
+import type { G3FrameworkOptions } from './types/preferences'
+import { setupPreferences, usePreferences } from './preferences'
+import type { G3PreferencesApi } from './preferences'
+
+/** createG3Framework 的返回值：兼容 `app.use()` 协议，同时暴露偏好 API */
+export interface G3Framework {
+  install(app: App): void
+  readonly preferences: G3PreferencesApi
+}
+
+/**
+ * 初始化 G3 框架。宿主在 `main.ts` 里调用一次，其余按需 import。
+ *
+ * ```ts
+ * const g3 = createG3Framework({ preferences: { app: { layout: 'sidebar-nav' } } })
+ * app.use(g3)
+ * ```
+ *
+ * 说明：偏好为模块级单例，初始化在调用时即完成；`install` 仅用于满足 `app.use()` 协议。
+ */
+export function createG3Framework(options: G3FrameworkOptions = {}): G3Framework {
+  setupPreferences({
+    preferences: options.preferences,
+    sizes: options.sizes,
+    theme: options.theme,
+    storageKey: options.storageKey,
+    persist: options.persist,
+  })
+
+  return {
+    install() {
+      // no-op：单例已在 setupPreferences 中生效
+    },
+    get preferences() {
+      return usePreferences()
+    },
+  }
+}
diff --git a/code/g3soft-libs/packages/framework/src/core/layout/G3Layout.vue b/code/g3soft-libs/packages/framework/src/core/layout/G3Layout.vue
new file mode 100644
index 00000000..3e5432fa
--- /dev/null
+++ b/code/g3soft-libs/packages/framework/src/core/layout/G3Layout.vue
@@ -0,0 +1,312 @@
+<script setup lang="ts">
+import { computed, provide, ref, watch } from 'vue'
+import type { Component } from 'vue'
+import { G3ConfigProvider } from '@g3soft/ui'
+import type { G3LayoutProps, NavItem } from '../types/layout'
+import type { G3LayoutEmits, G3LayoutSlots } from '../types/slots'
+import { usePreferences } from '../preferences'
+import { layoutContextKey, type LayoutContext } from './context'
+import { layoutModes } from './modes'
+import G3LayoutBreadcrumb from './G3LayoutBreadcrumb.vue'
+import G3LayoutHeader from './G3LayoutHeader.vue'
+import G3LayoutLogo from './G3LayoutLogo.vue'
+import G3LayoutSidebar from './G3LayoutSidebar.vue'
+import G3LayoutTabbar from './G3LayoutTabbar.vue'
+
+/**
+ * G3Layout —— 7 种布局的唯一入口。
+ *
+ * 结构对齐 vben：`.g3-layout__body` 内左右分栏（侧栏 + 主列）。
+ * 顶栏/页签栏的位置由 `headerFullWidth` 决定：
+ *  - true  → 顶栏横跨在侧栏之上（header-nav / header-sidebar-nav / header-mixed-nav）
+ *  - false → 顶栏位于主列内、侧栏右侧（sidebar-nav / sidebar-mixed-nav / mixed-nav）
+ * 内容区独立滚动。
+ *
+ * 所有 props 可选；不传则取偏好默认值，零配置即可渲染。
+ */
+defineOptions({ name: 'G3Layout' })
+
+const props = defineProps<G3LayoutProps>()
+const emit = defineEmits<G3LayoutEmits>()
+defineSlots<G3LayoutSlots>()
+
+const prefs = usePreferences()
+
+// 尺寸覆盖只需应用一次
+if (props.sizes) prefs.updateSizes(props.sizes)
+
+/** 生效值：props 优先，其次偏好默认 */
+const layout = computed(() => props.layout ?? prefs.layout.value)
+const mode = computed(() => layoutModes[layout.value])
+const collapsed = computed(() => props.collapsed ?? prefs.collapsed.value)
+const activeKey = computed(() => props.activeKey ?? '')
+
+/** 菜单：props.menus 优先，其次 menuSource 加载结果 */
+const loadedMenus = ref<NavItem[]>([])
+const menuLoading = ref(false)
+
+async function loadMenus(): Promise<void> {
+  const source = props.menuSource
+  if (!source) return
+  menuLoading.value = true
+  try {
+    loadedMenus.value = (await source()) ?? []
+  } finally {
+    menuLoading.value = false
+  }
+}
+
+watch(
+  () => props.menuSource,
+  () => {
+    if (props.menuSource) void loadMenus()
+  },
+  { immediate: true },
+)
+
+const menus = computed<NavItem[]>(() => {
+  if (props.menus?.length) return props.menus
+  return loadedMenus.value
+})
+
+function navigate(item: NavItem, event?: MouseEvent): void {
+  emit('navigate', { item, key: item.key, event })
+  emit('menu-select', item.key)
+}
+
+function toggleCollapsed(): void {
+  if (props.collapsed !== undefined) {
+    emit('update:collapsed', !props.collapsed)
+  } else {
+    prefs.toggleSidebar()
+  }
+}
+
+const context: LayoutContext = {
+  layout,
+  collapsed: computed(() => collapsed.value && !(prefs.preferences.sidebar.expandOnHover ?? false)),
+  activeKey,
+  menus,
+  user: computed(() => props.user),
+  toggleCollapsed,
+  navigate,
+}
+provide(layoutContextKey, context)
+
+/** 分组开关 */
+const showSidebar = computed(() => mode.value.sidebar !== false)
+const showHeader = computed(() => mode.value.header)
+const showHeaderLogo = computed(() => !showSidebar.value)
+const menuInHeader = computed(
+  () => mode.value.menuPlacement === 'header' || mode.value.menuPlacement === 'both',
+)
+const headerFullWidth = computed(() => mode.value.headerFullWidth)
+const showTabbar = computed(
+  () => mode.value.tabbar && prefs.preferences.tabbar.enable && (props.tabs?.length ?? 0) > 0,
+)
+const showChrome = computed(() => showHeader.value || showTabbar.value)
+const showBreadcrumb = computed(() => prefs.preferences.breadcrumb.enable)
+const footerEnable = computed(() => prefs.preferences.footer.enable === true)
+const footerText = computed(() => prefs.preferences.footer.text ?? '')
+
+/** 零件替换表 */
+const resolved = computed(() => ({
+  sidebar: (props.components?.sidebar ?? G3LayoutSidebar) as Component,
+  header: (props.components?.header ?? G3LayoutHeader) as Component,
+  tabbar: (props.components?.tabbar ?? G3LayoutTabbar) as Component,
+  breadcrumb: (props.components?.breadcrumb ?? G3LayoutBreadcrumb) as Component,
+  logo: (props.components?.logo ?? G3LayoutLogo) as Component,
+}))
+</script>
+
+<template>
+  <G3ConfigProvider :theme="prefs.resolvedTheme.value">
+    <slot>
+      <div
+        class="g3-layout"
+        data-layout-region="layout"
+        :data-layout="layout"
+        :data-sidebar-collapsed="collapsed"
+      >
+        <!-- 全宽顶栏：横跨在侧栏之上 -->
+        <div v-if="headerFullWidth && showChrome" class="g3-layout__header-wrap" data-layout-region="header">
+          <component
+            :is="resolved.header"
+            v-if="showHeader"
+            :show-menu="menuInHeader"
+            :show-logo="showHeaderLogo"
+            :collapsed="collapsed"
+            :sub-menu-row="mode.subMenuRow"
+          >
+            <template #logo>
+              <slot name="logo" :collapsed="false">
+                <component :is="resolved.logo" :collapsed="false" />
+              </slot>
+            </template>
+            <template #left="{ collapsed: c }">
+              <slot name="header-left" :collapsed="c" />
+            </template>
+            <template #right="{ collapsed: c }">
+              <slot name="header-right" :collapsed="c" />
+            </template>
+          </component>
+          <component
+            :is="resolved.tabbar"
+            v-if="showTabbar"
+            :tabs="tabs"
+            :active-key="activeKey"
+            @change="emit('tab-change', $event)"
+            @close="emit('tab-close', $event)"
+          >
+            <template v-if="$slots['tabbar-extra']" #extra>
+              <slot name="tabbar-extra" />
+            </template>
+          </component>
+        </div>
+
+        <div class="g3-layout__body" data-layout-region="body">
+          <component
+            :is="resolved.sidebar"
+            v-if="showSidebar"
+            :variant="mode.sidebar === 'mixed' ? 'mixed' : 'single'"
+            :collapsed="collapsed"
+          >
+            <template #logo="{ collapsed: c }">
+              <slot name="logo" :collapsed="c">
+                <component :is="resolved.logo" :collapsed="c" />
+              </slot>
+            </template>
+            <template v-if="$slots['sidebar-top']" #top="{ collapsed: c }">
+              <slot name="sidebar-top" :collapsed="c" />
+            </template>
+            <template v-if="$slots['sidebar-footer']" #footer="{ collapsed: c }">
+              <slot name="sidebar-footer" :collapsed="c" />
+            </template>
+          </component>
+
+          <div class="g3-layout__main" data-layout-region="main">
+            <!-- 非全宽顶栏：位于主列内、侧栏右侧 -->
+            <div v-if="!headerFullWidth && showChrome" class="g3-layout__header-wrap" data-layout-region="header">
+              <component
+                :is="resolved.header"
+                v-if="showHeader"
+                :show-menu="menuInHeader"
+                :show-logo="showHeaderLogo"
+                :collapsed="collapsed"
+                :sub-menu-row="mode.subMenuRow"
+              >
+                <template #logo>
+                  <slot name="logo" :collapsed="false">
+                    <component :is="resolved.logo" :collapsed="false" />
+                  </slot>
+                </template>
+                <template #left="{ collapsed: c }">
+                  <slot name="header-left" :collapsed="c" />
+                </template>
+                <template #right="{ collapsed: c }">
+                  <slot name="header-right" :collapsed="c" />
+                </template>
+              </component>
+              <component
+                :is="resolved.tabbar"
+                v-if="showTabbar"
+                :tabs="tabs"
+                :active-key="activeKey"
+                @change="emit('tab-change', $event)"
+                @close="emit('tab-close', $event)"
+              >
+                <template v-if="$slots['tabbar-extra']" #extra>
+                  <slot name="tabbar-extra" />
+                </template>
+              </component>
+            </div>
+
+            <div class="g3-layout__scroll" data-layout-region="scroll">
+              <div class="g3-layout__content" data-layout-region="content">
+                <div v-if="showBreadcrumb" class="g3-layout__content-head">
+                  <component :is="resolved.breadcrumb" />
+                  <slot name="breadcrumb-extra" />
+                </div>
+                <slot name="page" />
+              </div>
+              <footer v-if="footerEnable" class="g3-layout__footer">{{ footerText }}</footer>
+            </div>
+          </div>
+        </div>
+
+        <slot name="default" />
+      </div>
+    </slot>
+  </G3ConfigProvider>
+</template>
+
+<style>
+.g3-layout {
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  height: 100%;
+  min-height: 0;
+  overflow: hidden;
+  background: var(--g3-color-bg-layout, var(--g3-color-bg-container, #f5f5f5));
+}
+
+.g3-layout__body {
+  display: flex;
+  flex: 1;
+  min-height: 0;
+}
+
+.g3-layout__main {
+  display: flex;
+  flex-direction: column;
+  flex: 1;
+  min-width: 0;
+  min-height: 0;
+  overflow: hidden;
+}
+
+.g3-layout__header-wrap {
+  flex: none;
+  z-index: var(--g3-layout-zindex-header, 1000);
+}
+
+.g3-layout__scroll {
+  display: flex;
+  flex-direction: column;
+  flex: 1;
+  min-height: 0;
+  overflow-x: hidden;
+  overflow-y: auto;
+  background: var(--g3-color-bg-layout, var(--g3-color-bg-container, #f5f5f5));
+}
+
+.g3-layout__content {
+  display: flex;
+  flex-direction: column;
+  flex: 1;
+  min-height: 0;
+  padding: var(--g3-layout-content-padding, 16px);
+  gap: 12px;
+}
+
+.g3-layout__content-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+}
+
+.g3-layout__footer {
+  flex: none;
+  padding: 12px 16px;
+  text-align: center;
+  font-size: 12px;
+  color: var(--g3-color-text-tertiary, #a1a1aa);
+}
+
+/* full-content：无侧栏无顶栏，内容铺满 */
+.g3-layout[data-layout='full-content'] .g3-layout__content {
+  padding: 0;
+}
+</style>
diff --git a/code/g3soft-libs/packages/framework/src/core/layout/G3LayoutBreadcrumb.vue b/code/g3soft-libs/packages/framework/src/core/layout/G3LayoutBreadcrumb.vue
new file mode 100644
index 00000000..10688b45
--- /dev/null
+++ b/code/g3soft-libs/packages/framework/src/core/layout/G3LayoutBreadcrumb.vue
@@ -0,0 +1,69 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import type { NavItem } from '../types/layout'
+import { useLayoutContext } from './context'
+
+/** 面包屑：从菜单树里按 activeKey 反查链路。隐藏规则尊重 meta/breadcrumb 偏好。 */
+defineOptions({ name: 'G3LayoutBreadcrumb' })
+
+const ctx = useLayoutContext()
+
+function findChain(list: NavItem[], key: string, trail: NavItem[] = []): NavItem[] | null {
+  for (const item of list) {
+    if (item.hidden) continue
+    const next = [...trail, item]
+    if (item.key === key || (item.path && (key === item.path || key.startsWith(`${item.path}/`)))) {
+      return next
+    }
+    if (item.children?.length) {
+      const found = findChain(item.children, key, next)
+      if (found) return found
+    }
+  }
+  return null
+}
+
+const chain = computed(() => {
+  const key = ctx.activeKey.value
+  if (!key) return []
+  const items = findChain(ctx.menus.value, key) ?? []
+  return items.filter((item) => (item.meta as { hideInBreadcrumb?: boolean } | undefined)?.hideInBreadcrumb !== true)
+})
+</script>
+
+<template>
+  <nav v-if="chain.length" class="g3-layout-breadcrumb">
+    <ol class="g3-layout-breadcrumb__list">
+      <li v-for="(item, index) in chain" :key="item.key" class="g3-layout-breadcrumb__item">
+        <span class="g3-layout-breadcrumb__text">{{ item.title }}</span>
+        <span v-if="index < chain.length - 1" class="g3-layout-breadcrumb__sep">/</span>
+      </li>
+    </ol>
+  </nav>
+</template>
+
+<style>
+.g3-layout-breadcrumb {
+  min-width: 0;
+  overflow: hidden;
+}
+
+.g3-layout-breadcrumb__list {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+  font-size: 13px;
+  color: var(--g3-color-text-secondary, #71717a);
+}
+
+.g3-layout-breadcrumb__text {
+  white-space: nowrap;
+}
+
+.g3-layout-breadcrumb__sep {
+  color: var(--g3-color-text-quaternary, #d4d4d8);
+}
+</style>
diff --git a/code/g3soft-libs/packages/framework/src/core/layout/G3LayoutHeader.vue b/code/g3soft-libs/packages/framework/src/core/layout/G3LayoutHeader.vue
new file mode 100644
index 00000000..99590af2
--- /dev/null
+++ b/code/g3soft-libs/packages/framework/src/core/layout/G3LayoutHeader.vue
@@ -0,0 +1,135 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import type { NavItem } from '../types/layout'
+import { useLayoutContext } from './context'
+import { layoutModes } from './modes'
+import G3LayoutMenu from './G3LayoutMenu.vue'
+
+/**
+ * 顶栏。menu 可放水平菜单；subMenuRow=true 时下方再有二级菜单行。
+ * logo / left / right 由 G3Layout 透传插槽。
+ */
+defineOptions({ name: 'G3LayoutHeader' })
+
+const props = withDefaults(
+  defineProps<{
+    showMenu?: boolean
+    showLogo?: boolean
+    collapsed?: boolean
+    subMenuRow?: boolean
+  }>(),
+  {
+    showMenu: false,
+    showLogo: false,
+    collapsed: false,
+    subMenuRow: false,
+  },
+)
+
+const ctx = useLayoutContext()
+const hasSidebar = computed(() => layoutModes[ctx.layout.value].sidebar !== false)
+const rootItems = computed(() => ctx.menus.value.filter((item) => !item.hidden))
+
+function matchesActive(item: NavItem): boolean {
+  const key = ctx.activeKey.value
+  if (!key) return false
+  if (item.key === key) return true
+  if (!!item.path && (key === item.path || key.startsWith(`${item.path}/`))) return true
+  return (item.children ?? []).some((child) => matchesActive(child))
+}
+
+const activeRoot = computed(() => rootItems.value.find((item) => matchesActive(item)))
+const subItems = computed<NavItem[]>(() => activeRoot.value?.children?.filter((c) => !c.hidden) ?? [])
+</script>
+
+<template>
+  <div class="g3-layout-header-wrap">
+    <header class="g3-layout-header">
+      <div class="g3-layout-header__left">
+        <button
+          v-if="hasSidebar"
+          type="button"
+          class="g3-layout-header__collapse"
+          :aria-label="collapsed ? '展开侧栏' : '折叠侧栏'"
+          @click="ctx.toggleCollapsed()"
+        />
+        <slot v-if="showLogo" name="logo" :collapsed="false" />
+        <slot name="left" :collapsed="collapsed" />
+        <G3LayoutMenu v-if="showMenu" :items="rootItems" direction="horizontal" />
+      </div>
+      <div class="g3-layout-header__right">
+        <slot name="right" :collapsed="collapsed" />
+      </div>
+    </header>
+    <div v-if="subMenuRow && subItems.length" class="g3-layout-header__sub">
+      <G3LayoutMenu :items="subItems" direction="horizontal" />
+    </div>
+  </div>
+</template>
+
+<style>
+.g3-layout-header-wrap {
+  flex: none;
+  background: var(--g3-color-bg-container, #fff);
+  border-bottom: 1px solid var(--g3-color-border, #e4e4e7);
+}
+
+.g3-layout-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  height: var(--g3-layout-header-height, 56px);
+  padding: 0 16px;
+}
+
+.g3-layout-header__left,
+.g3-layout-header__right {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  min-width: 0;
+}
+
+.g3-layout-header__left {
+  flex: 1;
+}
+
+.g3-layout-header__right {
+  flex: none;
+}
+
+.g3-layout-header__collapse {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 32px;
+  height: 32px;
+  flex: none;
+  border: none;
+  border-radius: var(--g3-radius, 6px);
+  background: transparent;
+  color: var(--g3-color-text-secondary, #52525b);
+  cursor: pointer;
+}
+
+.g3-layout-header__collapse:hover {
+  background: var(--g3-color-fill-hover, rgba(0, 0, 0, 0.05));
+}
+
+.g3-layout-header__collapse::before {
+  content: '';
+  width: 16px;
+  height: 2px;
+  background: currentColor;
+  box-shadow: 0 5px 0 currentColor, 0 -5px 0 currentColor;
+}
+
+.g3-layout-header__sub {
+  display: flex;
+  align-items: center;
+  height: 40px;
+  padding: 0 12px;
+  border-top: 1px solid var(--g3-color-border, #e4e4e7);
+}
+</style>
diff --git a/code/g3soft-libs/packages/framework/src/core/layout/G3LayoutLogo.vue b/code/g3soft-libs/packages/framework/src/core/layout/G3LayoutLogo.vue
new file mode 100644
index 00000000..c77ef531
--- /dev/null
+++ b/code/g3soft-libs/packages/framework/src/core/layout/G3LayoutLogo.vue
@@ -0,0 +1,66 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import { usePreferences } from '../preferences'
+
+/** 品牌区。可通过 G3Layout 的 #logo 插槽整体替换。 */
+defineOptions({ name: 'G3LayoutLogo' })
+
+const props = withDefaults(defineProps<{ collapsed?: boolean }>(), { collapsed: false })
+
+const prefs = usePreferences()
+const logo = computed(() => prefs.preferences.logo)
+const text = computed(() => logo.value.text ?? prefs.preferences.app.name ?? 'G3Soft')
+const visible = computed(() => logo.value.enable !== false)
+</script>
+
+<template>
+  <div v-if="visible" class="g3-layout-logo" :class="{ 'is-collapsed': props.collapsed }">
+    <img v-if="logo.source" class="g3-layout-logo__img" :src="logo.source" alt="logo" />
+    <span v-else class="g3-layout-logo__mark">G3</span>
+    <span v-if="!props.collapsed" class="g3-layout-logo__text">{{ text }}</span>
+  </div>
+</template>
+
+<style>
+.g3-layout-logo {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  height: var(--g3-layout-header-height, 56px);
+  padding: 0 16px;
+  overflow: hidden;
+  white-space: nowrap;
+}
+
+.g3-layout-logo.is-collapsed {
+  justify-content: center;
+  padding: 0;
+}
+
+.g3-layout-logo__img {
+  width: 28px;
+  height: 28px;
+  flex: none;
+  object-fit: contain;
+}
+
+.g3-layout-logo__mark {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 28px;
+  height: 28px;
+  flex: none;
+  border-radius: var(--g3-radius, 6px);
+  color: var(--g3-color-white, #fff);
+  background: var(--g3-color-primary, #18181b);
+  font-size: 13px;
+  font-weight: 700;
+}
+
+.g3-layout-logo__text {
+  font-size: 16px;
+  font-weight: 600;
+  color: var(--g3-color-text, #18181b);
+}
+</style>
diff --git a/code/g3soft-libs/packages/framework/src/core/layout/G3LayoutMenu.vue b/code/g3soft-libs/packages/framework/src/core/layout/G3LayoutMenu.vue
new file mode 100644
index 00000000..8f778b50
--- /dev/null
+++ b/code/g3soft-libs/packages/framework/src/core/layout/G3LayoutMenu.vue
@@ -0,0 +1,241 @@
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import type { NavItem } from '../types/layout'
+import { useLayoutContext } from './context'
+
+/**
+ * 递归菜单。垂直模式逐级展开；水平模式子级走 CSS 悬浮飞出。
+ * 数据只认 NavItem，不与任何后端耦合。
+ */
+defineOptions({ name: 'G3LayoutMenu' })
+
+const props = withDefaults(
+  defineProps<{
+    items?: NavItem[]
+    direction?: 'vertical' | 'horizontal'
+    collapsed?: boolean
+    level?: number
+  }>(),
+  {
+    items: () => [],
+    direction: 'vertical',
+    collapsed: false,
+    level: 0,
+  },
+)
+
+const ctx = useLayoutContext()
+const expanded = ref<Set<string>>(new Set())
+
+const visibleItems = computed(() => props.items.filter((item) => !item.hidden))
+
+function hasChildren(item: NavItem): boolean {
+  return (item.children ?? []).some((child) => !child.hidden)
+}
+
+function visibleChildren(item: NavItem): NavItem[] {
+  return (item.children ?? []).filter((child) => !child.hidden)
+}
+
+function isActive(item: NavItem): boolean {
+  const key = ctx.activeKey.value
+  if (!key) return false
+  if (item.key === key) return true
+  return !!item.path && (key === item.path || key.startsWith(`${item.path}/`))
+}
+
+function isExpanded(item: NavItem): boolean {
+  if (props.direction === 'horizontal') return false
+  return expanded.value.has(item.key)
+}
+
+function onItemClick(item: NavItem, event: MouseEvent): void {
+  if (item.disabled) {
+    event.preventDefault()
+    return
+  }
+  if (hasChildren(item)) {
+    if (props.direction === 'vertical') {
+      const next = new Set(expanded.value)
+      if (next.has(item.key)) next.delete(item.key)
+      else next.add(item.key)
+      expanded.value = next
+    }
+    return
+  }
+  ctx.navigate(item, event)
+}
+</script>
+
+<template>
+  <ul class="g3-menu" :class="[`g3-menu--${direction}`, { 'g3-menu--collapsed': collapsed }]">
+    <li
+      v-for="item in visibleItems"
+      :key="item.key"
+      class="g3-menu__item"
+      :class="{
+        'is-active': isActive(item),
+        'is-expanded': isExpanded(item),
+        'is-disabled': !!item.disabled,
+        'has-children': hasChildren(item),
+      }"
+    >
+      <div
+        class="g3-menu__content"
+        :title="collapsed ? item.title : undefined"
+        @click="onItemClick(item, $event)"
+      >
+        <component
+          :is="item.icon"
+          v-if="item.icon && typeof item.icon !== 'string'"
+          class="g3-menu__icon"
+        />
+        <span v-if="!collapsed" class="g3-menu__title">{{ item.title }}</span>
+        <span v-if="item.badge != null" class="g3-menu__badge">{{ item.badge }}</span>
+      </div>
+
+      <G3LayoutMenu
+        v-if="direction === 'vertical' && hasChildren(item) && isExpanded(item)"
+        :items="visibleChildren(item)"
+        direction="vertical"
+        :level="level + 1"
+      />
+
+      <div v-if="direction === 'horizontal' && hasChildren(item)" class="g3-menu__sub">
+        <G3LayoutMenu :items="visibleChildren(item)" direction="vertical" :level="level + 1" />
+      </div>
+    </li>
+  </ul>
+</template>
+
+<style>
+.g3-menu {
+  --g3-menu-item-height: 40px;
+  margin: 0;
+  padding: 4px;
+  list-style: none;
+  font-size: var(--g3-font-size-base, 14px);
+  color: var(--g3-color-text, #3f3f46);
+}
+
+.g3-menu__item {
+  position: relative;
+  border-radius: var(--g3-radius, 6px);
+}
+
+.g3-menu__content {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  min-height: var(--g3-menu-item-height);
+  padding: 0 10px;
+  border-radius: var(--g3-radius, 6px);
+  cursor: pointer;
+  transition: background-color 0.15s ease, color 0.15s ease;
+  user-select: none;
+}
+
+.g3-menu__content:hover {
+  background: var(--g3-color-fill-hover, rgba(0, 0, 0, 0.05));
+}
+
+.g3-menu__item.is-active > .g3-menu__content {
+  color: var(--g3-color-primary, #18181b);
+  background: var(--g3-color-primary-light, rgba(24, 24, 27, 0.08));
+  font-weight: 600;
+}
+
+.g3-menu__item.is-disabled > .g3-menu__content {
+  opacity: 0.45;
+  cursor: not-allowed;
+}
+
+.g3-menu__icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 16px;
+  height: 16px;
+  flex: none;
+}
+
+.g3-menu__title {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.g3-menu__badge {
+  flex: none;
+  padding: 0 6px;
+  border-radius: 999px;
+  font-size: 12px;
+  line-height: 18px;
+  color: var(--g3-color-white, #fff);
+  background: var(--g3-color-primary, #18181b);
+}
+
+/* 垂直：有子级时的箭头 + 缩进 */
+.g3-menu--vertical .g3-menu__item.has-children > .g3-menu__content::after {
+  content: '';
+  margin-left: auto;
+  width: 6px;
+  height: 6px;
+  border-right: 1.5px solid currentColor;
+  border-bottom: 1.5px solid currentColor;
+  transform: rotate(45deg);
+  transition: transform 0.15s ease;
+  opacity: 0.6;
+}
+
+.g3-menu--vertical .g3-menu__item.is-expanded > .g3-menu__content::after {
+  transform: rotate(-135deg);
+}
+
+.g3-menu--vertical .g3-menu__sub,
+.g3-menu--vertical > .g3-menu__item > .g3-menu {
+  padding-left: 14px;
+}
+
+.g3-menu--collapsed .g3-menu__content {
+  justify-content: center;
+  padding: 0;
+}
+
+.g3-menu--collapsed .g3-menu__item.has-children > .g3-menu__content::after {
+  display: none;
+}
+
+/* 水平：一级横向排列，子级悬浮飞出 */
+.g3-menu--horizontal {
+  display: flex;
+  align-items: center;
+  gap: 2px;
+  padding: 0;
+}
+
+.g3-menu--horizontal > .g3-menu__item > .g3-menu__content {
+  min-height: 32px;
+  padding: 0 12px;
+}
+
+.g3-menu__sub {
+  position: absolute;
+  top: 100%;
+  left: 0;
+  z-index: var(--g3-layout-zindex-menu, 1200);
+  min-width: 180px;
+  padding: 4px;
+  border: 1px solid var(--g3-color-border, #e4e4e7);
+  border-radius: var(--g3-radius, 6px);
+  background: var(--g3-color-bg-container, #fff);
+  box-shadow: var(--g3-shadow-md, 0 6px 16px rgba(0, 0, 0, 0.12));
+  display: none;
+}
+
+.g3-menu--horizontal > .g3-menu__item:hover > .g3-menu__sub {
+  display: block;
+}
+</style>
diff --git a/code/g3soft-libs/packages/framework/src/core/layout/G3LayoutSidebar.vue b/code/g3soft-libs/packages/framework/src/core/layout/G3LayoutSidebar.vue
new file mode 100644
index 00000000..92d33b30
--- /dev/null
+++ b/code/g3soft-libs/packages/framework/src/core/layout/G3LayoutSidebar.vue
@@ -0,0 +1,357 @@
+<script setup lang="ts">
+import { computed, ref, watch } from 'vue'
+import type { NavItem } from '../types/layout'
+import { usePreferences } from '../preferences'
+import { useLayoutContext } from './context'
+import G3LayoutMenu from './G3LayoutMenu.vue'
+
+/**
+ * 侧栏。结构参考 vben：品牌区 + 菜单区（可滚动）+ 底部折叠按钮 + 右侧拖拽条。
+ * variant='single' 单列；variant='mixed' 双列（左窄列一级 + 右列子级）。
+ * 宽度 / 折叠 / 拖拽 / 悬浮展开均由偏好驱动。
+ */
+defineOptions({ name: 'G3LayoutSidebar' })
+
+const props = withDefaults(
+  defineProps<{
+    variant?: 'single' | 'mixed'
+    collapsed?: boolean
+  }>(),
+  {
+    variant: 'single',
+    collapsed: false,
+  },
+)
+
+const prefs = usePreferences()
+const ctx = useLayoutContext()
+
+const hovering = ref(false)
+
+/** 悬浮展开：折叠态下鼠标悬停时临时展开 */
+const expandOnHovering = computed(
+  () => props.collapsed && prefs.preferences.sidebar.expandOnHover && hovering.value,
+)
+
+/** 生效的折叠态（用于图标/文案渲染）；悬浮展开时视觉上展开 */
+const effectiveCollapsed = computed(() => props.collapsed && !expandOnHovering.value)
+
+const currentWidth = computed(() => {
+  const s = prefs.preferences.sidebar
+  if (!props.collapsed || expandOnHovering.value) return s.width
+  return s.collapseWidth
+})
+
+const rootItems = computed(() => ctx.menus.value.filter((item) => !item.hidden))
+
+const activeRootKey = ref<string>('')
+
+function matchesActive(item: NavItem): boolean {
+  const key = ctx.activeKey.value
+  if (!key) return false
+  if (item.key === key) return true
+  if (item.path && (key === item.path || key.startsWith(`${item.path}/`))) return true
+  return (item.children ?? []).some((child) => matchesActive(child))
+}
+
+watch(
+  [rootItems, () => ctx.activeKey.value],
+  () => {
+    const hit = rootItems.value.find((item) => matchesActive(item))
+    activeRootKey.value = (hit ?? rootItems.value[0])?.key ?? ''
+  },
+  { immediate: true },
+)
+
+const activeRoot = computed(
+  () => rootItems.value.find((item) => item.key === activeRootKey.value) ?? rootItems.value[0],
+)
+const subItems = computed<NavItem[]>(
+  () => activeRoot.value?.children?.filter((child) => !child.hidden) ?? [],
+)
+
+function onRootClick(item: NavItem, event: MouseEvent): void {
+  if (item.disabled) {
+    event.preventDefault()
+    return
+  }
+  if (item.children?.length) {
+    activeRootKey.value = item.key
+    return
+  }
+  ctx.navigate(item, event)
+}
+
+function onMouseenter(event: MouseEvent): void {
+  if (!prefs.preferences.sidebar.expandOnHover) return
+  if (event.offsetX < 10) return
+  hovering.value = true
+}
+
+function onMouseleave(): void {
+  hovering.value = false
+}
+
+/** 拖拽调宽（vben use-sidebar-drag 的精简版） */
+function onDragStart(event: MouseEvent): void {
+  if (typeof document === 'undefined') return
+  event.preventDefault()
+  const startX = event.clientX
+  const startWidth = prefs.preferences.sidebar.width
+  const min = prefs.sizes.sidebarCollapseWidth
+  const max = prefs.sizes.sidebarMaxWidth
+
+  const onMove = (moveEvent: MouseEvent) => {
+    const width = Math.min(max, Math.max(min, startWidth + (moveEvent.clientX - startX)))
+    prefs.update({ sidebar: { width } })
+    prefs.updateSizes({ sidebarWidth: width })
+  }
+  const onUp = () => {
+    document.removeEventListener('mousemove', onMove)
+    document.removeEventListener('mouseup', onUp)
+  }
+  document.addEventListener('mousemove', onMove)
+  document.addEventListener('mouseup', onUp)
+}
+</script>
+
+<template>
+  <aside
+    data-layout-region="sidebar"
+    class="g3-layout-sidebar"
+    :class="{ 'is-collapsed': effectiveCollapsed, 'is-mixed': variant === 'mixed' }"
+    :style="{ width: `${currentWidth}px` }"
+    @mouseenter="onMouseenter"
+    @mouseleave="onMouseleave"
+  >
+    <div class="g3-layout-sidebar__brand">
+      <slot name="logo" :collapsed="effectiveCollapsed" />
+    </div>
+
+    <div v-if="$slots.top" class="g3-layout-sidebar__top">
+      <slot name="top" :collapsed="effectiveCollapsed" />
+    </div>
+
+    <!-- 单列 -->
+    <div v-if="variant === 'single'" class="g3-layout-sidebar__scroll">
+      <G3LayoutMenu :items="rootItems" direction="vertical" :collapsed="effectiveCollapsed" />
+    </div>
+
+    <!-- 双列 -->
+    <div v-else class="g3-layout-sidebar__mixed">
+      <ul class="g3-layout-sidebar__rail">
+        <li
+          v-for="item in rootItems"
+          :key="item.key"
+          class="g3-layout-sidebar__rail-item"
+          :class="{ 'is-active': item.key === activeRootKey, 'is-disabled': !!item.disabled }"
+          :title="item.title"
+          @click="onRootClick(item, $event)"
+        >
+          <component
+            :is="item.icon"
+            v-if="item.icon && typeof item.icon !== 'string'"
+            class="g3-layout-sidebar__rail-icon"
+          />
+          <span v-else class="g3-layout-sidebar__rail-text">{{ item.title.slice(0, 1) }}</span>
+          <span class="g3-layout-sidebar__rail-label">{{ item.title }}</span>
+        </li>
+      </ul>
+      <div class="g3-layout-sidebar__mixed-main">
+        <div v-if="activeRoot" class="g3-layout-sidebar__mixed-title">{{ activeRoot.title }}</div>
+        <div class="g3-layout-sidebar__scroll">
+          <G3LayoutMenu :items="subItems" direction="vertical" />
+        </div>
+      </div>
+    </div>
+
+    <div v-if="$slots.footer" class="g3-layout-sidebar__footer">
+      <slot name="footer" :collapsed="effectiveCollapsed" />
+    </div>
+
+    <!-- 底部折叠按钮（对齐 vben SidebarCollapseButton） -->
+    <button
+      type="button"
+      data-layout-action="toggle-sidebar-collapse"
+      class="g3-layout-sidebar__collapse"
+      :aria-label="collapsed ? '展开侧栏' : '折叠侧栏'"
+      @click="ctx.toggleCollapsed()"
+    >
+      <span class="g3-layout-sidebar__collapse-icon" :class="{ 'is-collapsed': effectiveCollapsed }" />
+    </button>
+
+    <!-- 右侧拖拽条 -->
+    <div
+      v-if="prefs.preferences.sidebar.draggable && !effectiveCollapsed"
+      class="g3-layout-sidebar__drag"
+      @mousedown="onDragStart"
+    />
+  </aside>
+</template>
+
+<style>
+.g3-layout-sidebar {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  flex: none;
+  height: 100%;
+  border-right: 1px solid var(--g3-color-border, #e4e4e7);
+  background: var(--g3-color-bg-sidebar, var(--g3-color-bg-container, #fff));
+  transition: width 0.2s ease;
+  overflow: hidden;
+}
+
+.g3-layout-sidebar__brand {
+  flex: none;
+}
+
+.g3-layout-sidebar__top,
+.g3-layout-sidebar__footer {
+  flex: none;
+  padding: 6px;
+}
+
+.g3-layout-sidebar__scroll {
+  flex: 1;
+  min-height: 0;
+  overflow-x: hidden;
+  overflow-y: auto;
+}
+
+/* 底部折叠按钮 */
+.g3-layout-sidebar__collapse {
+  flex: none;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 28px;
+  height: 28px;
+  margin: 8px 10px;
+  border: none;
+  border-radius: var(--g3-radius, 6px);
+  background: transparent;
+  color: var(--g3-color-text-secondary, #71717a);
+  cursor: pointer;
+}
+
+.g3-layout-sidebar__collapse:hover {
+  background: var(--g3-color-fill-hover, rgba(0, 0, 0, 0.05));
+  color: var(--g3-color-text, #18181b);
+}
+
+.g3-layout-sidebar__collapse-icon {
+  width: 7px;
+  height: 7px;
+  border-left: 1.5px solid currentColor;
+  border-bottom: 1.5px solid currentColor;
+  transform: rotate(45deg);
+}
+
+.g3-layout-sidebar__collapse-icon.is-collapsed {
+  transform: rotate(-135deg);
+}
+
+/* 拖拽条 */
+.g3-layout-sidebar__drag {
+  position: absolute;
+  top: 0;
+  right: -2px;
+  bottom: 0;
+  z-index: 20;
+  width: 4px;
+  cursor: col-resize;
+  background: transparent;
+}
+
+.g3-layout-sidebar__drag:hover {
+  background: var(--g3-color-primary, #18181b);
+  opacity: 0.4;
+}
+
+/* 双列 */
+.g3-layout-sidebar__mixed {
+  display: flex;
+  flex: 1;
+  min-height: 0;
+}
+
+.g3-layout-sidebar__rail {
+  flex: none;
+  width: var(--g3-layout-mixed-width, 80px);
+  margin: 0;
+  padding: 4px;
+  list-style: none;
+  overflow-y: auto;
+  background: var(--g3-color-fill-quaternary, #fafafa);
+}
+
+.g3-layout-sidebar__rail-item {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 4px;
+  padding: 8px 4px;
+  border-radius: var(--g3-radius, 6px);
+  color: var(--g3-color-text-secondary, #52525b);
+  font-size: 12px;
+  text-align: center;
+  cursor: pointer;
+}
+
+.g3-layout-sidebar__rail-item:hover {
+  background: var(--g3-color-fill-hover, rgba(0, 0, 0, 0.05));
+}
+
+.g3-layout-sidebar__rail-item.is-active {
+  color: var(--g3-color-primary, #18181b);
+  background: var(--g3-color-primary-light, rgba(24, 24, 27, 0.08));
+  font-weight: 600;
+}
+
+.g3-layout-sidebar__rail-item.is-disabled {
+  opacity: 0.45;
+  cursor: not-allowed;
+}
+
+.g3-layout-sidebar__rail-icon {
+  width: 18px;
+  height: 18px;
+}
+
+.g3-layout-sidebar__rail-text {
+  line-height: 1;
+}
+
+.g3-layout-sidebar__rail-label {
+  display: block;
+  max-width: 100%;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.g3-layout-sidebar__mixed-main {
+  display: flex;
+  flex-direction: column;
+  flex: 1;
+  min-width: 0;
+}
+
+.g3-layout-sidebar__mixed-title {
+  flex: none;
+  padding: 12px 12px 4px;
+  font-size: 13px;
+  font-weight: 600;
+  color: var(--g3-color-text, #18181b);
+}
+
+.g3-layout-sidebar.is-collapsed .g3-layout-sidebar__rail-label,
+.g3-layout-sidebar.is-collapsed .g3-layout-sidebar__mixed-main {
+  display: none;
+}
+
+.g3-layout-sidebar.is-collapsed.is-mixed {
+  width: var(--g3-layout-mixed-width, 80px) !important;
+}
+</style>
diff --git a/code/g3soft-libs/packages/framework/src/core/layout/G3LayoutTabbar.vue b/code/g3soft-libs/packages/framework/src/core/layout/G3LayoutTabbar.vue
new file mode 100644
index 00000000..5c1fae25
--- /dev/null
+++ b/code/g3soft-libs/packages/framework/src/core/layout/G3LayoutTabbar.vue
@@ -0,0 +1,151 @@
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import type { G3TabItem } from '../types/layout'
+
+/**
+ * 页签栏（纯展示 + 交互事件）。页签「状态」由宿主或接线层管理，
+ * 这里只渲染、并向上抛 change / close。
+ */
+defineOptions({ name: 'G3LayoutTabbar' })
+
+const props = withDefaults(
+  defineProps<{
+    tabs?: G3TabItem[]
+    activeKey?: string
+  }>(),
+  {
+    tabs: () => [],
+    activeKey: '',
+  },
+)
+
+const emit = defineEmits<{
+  (e: 'change', key: string): void
+  (e: 'close', key: string): void
+}>()
+
+const scrollRef = ref<HTMLElement | null>(null)
+
+const visibleTabs = computed(() => props.tabs)
+
+function isClosable(tab: G3TabItem): boolean {
+  if (tab.affix) return false
+  return tab.closable !== false
+}
+
+function onClose(tab: G3TabItem, event: MouseEvent): void {
+  event.stopPropagation()
+  emit('close', tab.key)
+}
+
+function onMiddleClick(tab: G3TabItem, event: MouseEvent): void {
+  if (event.button === 1 && isClosable(tab)) {
+    event.preventDefault()
+    emit('close', tab.key)
+  }
+}
+</script>
+
+<template>
+  <div class="g3-layout-tabbar">
+    <div ref="scrollRef" class="g3-layout-tabbar__scroll">
+      <button
+        v-for="tab in visibleTabs"
+        :key="tab.key"
+        type="button"
+        class="g3-layout-tabbar__tab"
+        :class="{ 'is-active': tab.key === activeKey }"
+        @click="emit('change', tab.key)"
+        @auxclick="onMiddleClick(tab, $event)"
+      >
+        <component :is="tab.icon" v-if="tab.icon && typeof tab.icon !== 'string'" class="g3-layout-tabbar__icon" />
+        <span class="g3-layout-tabbar__title">{{ tab.title }}</span>
+        <span v-if="isClosable(tab)" class="g3-layout-tabbar__close" @click="onClose(tab, $event)">×</span>
+      </button>
+    </div>
+    <div class="g3-layout-tabbar__extra">
+      <slot name="extra" />
+    </div>
+  </div>
+</template>
+
+<style>
+.g3-layout-tabbar {
+  display: flex;
+  align-items: center;
+  height: var(--g3-layout-tabbar-height, 40px);
+  border-bottom: 1px solid var(--g3-color-border, #e4e4e7);
+  background: var(--g3-color-bg-container, #fff);
+}
+
+.g3-layout-tabbar__scroll {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  flex: 1;
+  min-width: 0;
+  padding: 0 8px;
+  overflow-x: auto;
+  scrollbar-width: none;
+}
+
+.g3-layout-tabbar__scroll::-webkit-scrollbar {
+  display: none;
+}
+
+.g3-layout-tabbar__tab {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  flex: none;
+  height: 28px;
+  padding: 0 10px;
+  border: 1px solid var(--g3-color-border, #e4e4e7);
+  border-radius: var(--g3-radius, 6px);
+  background: var(--g3-color-bg-container, #fff);
+  color: var(--g3-color-text-secondary, #52525b);
+  font-size: 13px;
+  cursor: pointer;
+  transition: color 0.15s ease, border-color 0.15s ease, background-color 0.15s ease;
+}
+
+.g3-layout-tabbar__tab:hover {
+  color: var(--g3-color-primary, #18181b);
+}
+
+.g3-layout-tabbar__tab.is-active {
+  color: var(--g3-color-primary, #18181b);
+  border-color: var(--g3-color-primary, #18181b);
+  background: var(--g3-color-primary-light, rgba(24, 24, 27, 0.08));
+}
+
+.g3-layout-tabbar__icon {
+  display: inline-flex;
+  width: 14px;
+  height: 14px;
+}
+
+.g3-layout-tabbar__title {
+  white-space: nowrap;
+}
+
+.g3-layout-tabbar__close {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 16px;
+  height: 16px;
+  border-radius: 50%;
+  font-size: 14px;
+  line-height: 1;
+}
+
+.g3-layout-tabbar__close:hover {
+  background: var(--g3-color-fill-hover, rgba(0, 0, 0, 0.1));
+}
+
+.g3-layout-tabbar__extra {
+  flex: none;
+  padding: 0 8px;
+}
+</style>
diff --git a/code/g3soft-libs/packages/framework/src/core/layout/context.ts b/code/g3soft-libs/packages/framework/src/core/layout/context.ts
new file mode 100644
index 00000000..cba5e5ef
--- /dev/null
+++ b/code/g3soft-libs/packages/framework/src/core/layout/context.ts
@@ -0,0 +1,32 @@
+import type { ComputedRef, InjectionKey } from 'vue'
+import { inject } from 'vue'
+import type { LayoutType, NavItem, UserInfo } from '../types/layout'
+
+/** G3Layout 向子树提供的上下文（避免层层 props 传递） */
+export interface LayoutContext {
+  /** 生效的布局模式 */
+  layout: ComputedRef<LayoutType>
+  /** 侧栏折叠 */
+  collapsed: ComputedRef<boolean>
+  /** 当前激活 key */
+  activeKey: ComputedRef<string>
+  /** 菜单数据 */
+  menus: ComputedRef<NavItem[]>
+  /** 当前用户 */
+  user: ComputedRef<UserInfo | undefined>
+  /** 切换侧栏折叠 */
+  toggleCollapsed: () => void
+  /** 菜单导航（冒泡为 navigate 事件） */
+  navigate: (item: NavItem, event?: MouseEvent) => void
+}
+
+export const layoutContextKey: InjectionKey<LayoutContext> = Symbol('g3-layout-context')
+
+/** 在 G3Layout 子树内获取布局上下文 */
+export function useLayoutContext(): LayoutContext {
+  const ctx = inject(layoutContextKey, null)
+  if (!ctx) {
+    throw new Error('[g3] useLayoutContext() 必须在 <G3Layout> 内使用')
+  }
+  return ctx
+}
diff --git a/code/g3soft-libs/packages/framework/src/core/layout/index.ts b/code/g3soft-libs/packages/framework/src/core/layout/index.ts
new file mode 100644
index 00000000..f06daaa3
--- /dev/null
+++ b/code/g3soft-libs/packages/framework/src/core/layout/index.ts
@@ -0,0 +1,13 @@
+export { default as G3Layout } from './G3Layout.vue'
+export { default as G3LayoutSidebar } from './G3LayoutSidebar.vue'
+export { default as G3LayoutHeader } from './G3LayoutHeader.vue'
+export { default as G3LayoutMenu } from './G3LayoutMenu.vue'
+export { default as G3LayoutTabbar } from './G3LayoutTabbar.vue'
+export { default as G3LayoutBreadcrumb } from './G3LayoutBreadcrumb.vue'
+export { default as G3LayoutLogo } from './G3LayoutLogo.vue'
+
+export { layoutLabels, layoutModes } from './modes'
+export type { LayoutModeConfig } from './modes'
+
+export { layoutContextKey, useLayoutContext } from './context'
+export type { LayoutContext } from './context'
diff --git a/code/g3soft-libs/packages/framework/src/core/layout/modes.ts b/code/g3soft-libs/packages/framework/src/core/layout/modes.ts
new file mode 100644
index 00000000..a77cc32a
--- /dev/null
+++ b/code/g3soft-libs/packages/framework/src/core/layout/modes.ts
@@ -0,0 +1,96 @@
+import type { LayoutType } from '../types/layout'
+
+/**
+ * 布局模式配置表 —— 7 种布局由「一个 G3Layout + 这张表」驱动，不写 7 个组件。
+ */
+export interface LayoutModeConfig {
+  /** 侧栏：false 无 / 'single' 单列 / 'mixed' 双列（左窄一级 + 右列子级） */
+  sidebar: false | 'single' | 'mixed'
+  /** 是否显示顶栏 */
+  header: boolean
+  /** 菜单位置：侧栏 / 顶栏 / 两者 */
+  menuPlacement: 'sidebar' | 'header' | 'both'
+  /** 顶栏是否横跨整宽（false = 顶栏位于侧栏右侧，不与侧栏并排） */
+  headerFullWidth: boolean
+  /** 顶栏下方是否再有「二级菜单行」 */
+  subMenuRow: boolean
+  /** 是否显示页签栏 */
+  tabbar: boolean
+}
+
+export const layoutModes: Record<LayoutType, LayoutModeConfig> = {
+  /** 垂直侧边菜单 */
+  'sidebar-nav': {
+    sidebar: 'single',
+    header: true,
+    menuPlacement: 'sidebar',
+    headerFullWidth: false,
+    subMenuRow: false,
+    tabbar: true,
+  },
+  /** 顶部水平菜单 */
+  'header-nav': {
+    sidebar: false,
+    header: true,
+    menuPlacement: 'header',
+    headerFullWidth: true,
+    subMenuRow: false,
+    tabbar: true,
+  },
+  /** 双列菜单 */
+  'sidebar-mixed-nav': {
+    sidebar: 'mixed',
+    header: true,
+    menuPlacement: 'sidebar',
+    headerFullWidth: false,
+    subMenuRow: false,
+    tabbar: true,
+  },
+  /** 无侧栏无顶栏 */
+  'full-content': {
+    sidebar: false,
+    header: false,
+    menuPlacement: 'sidebar',
+    headerFullWidth: false,
+    subMenuRow: false,
+    tabbar: false,
+  },
+  /** 顶部一级 + 侧栏二级 */
+  'mixed-nav': {
+    sidebar: 'single',
+    header: true,
+    menuPlacement: 'both',
+    headerFullWidth: false,
+    subMenuRow: false,
+    tabbar: true,
+  },
+  /** 顶部混合：顶栏 + 二级菜单行 */
+  'header-mixed-nav': {
+    sidebar: false,
+    header: true,
+    menuPlacement: 'header',
+    headerFullWidth: true,
+    subMenuRow: true,
+    tabbar: true,
+  },
+  /** 顶栏横跨 + 侧栏 */
+  'header-sidebar-nav': {
+    sidebar: 'single',
+    header: true,
+    menuPlacement: 'both',
+    headerFullWidth: true,
+    subMenuRow: false,
+    tabbar: true,
+  },
+}
+
+/** 布局模式展示名（偏好抽屉用） */
+export const layoutLabels: Record<LayoutType, string> = {
+  'sidebar-nav': '垂直菜单',
+  'header-nav': '顶部菜单',
+  'sidebar-mixed-nav': '双列菜单',
+  'full-content': '通栏内容',
+  'mixed-nav': '顶 + 侧混合',
+  'header-mixed-nav': '顶部混合',
+  'header-sidebar-nav': '顶栏 + 侧栏',
+}
diff --git a/code/g3soft-libs/packages/framework/src/core/preferences/apply.ts b/code/g3soft-libs/packages/framework/src/core/preferences/apply.ts
new file mode 100644
index 00000000..e41dd17c
--- /dev/null
+++ b/code/g3soft-libs/packages/framework/src/core/preferences/apply.ts
@@ -0,0 +1,52 @@
+import type { LayoutSizes } from '../types/layout'
+import type { ThemeMode, ThemePreferences } from '../types/preferences'
+
+/** 数字按 px 处理，字符串原样返回 */
+export function toCssLength(value: string | number): string {
+  return typeof value === 'number' ? `${value}px` : value
+}
+
+/**
+ * 主题模式 → 是否暗色。`auto` 时读取系统偏好（SSR 下安全回退为 false）。
+ */
+export function resolveDark(mode: ThemeMode): boolean {
+  if (mode === 'auto') {
+    if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') return false
+    return window.matchMedia('(prefers-color-scheme: dark)').matches
+  }
+  return mode === 'dark'
+}
+
+/**
+ * 把偏好中的「非颜色」部分写到根元素 CSS 变量。
+ * 颜色 / 暗色交给 @g3soft/ui 的 ConfigProvider（derivePalette），此处不重复处理颜色。
+ */
+export function applyThemeVars(
+  theme: ThemePreferences,
+  sizes: LayoutSizes,
+  root?: HTMLElement,
+): void {
+  if (typeof document === 'undefined') return
+  const el = root ?? document.documentElement
+
+  if (theme.radius != null) el.style.setProperty('--g3-radius', toCssLength(theme.radius))
+  if (theme.fontSize != null) el.style.setProperty('--g3-font-size-base', toCssLength(theme.fontSize))
+
+  // 布局尺寸（供布局组件消费，避免组件里硬编码）
+  el.style.setProperty('--g3-layout-sidebar-width', toCssLength(sizes.sidebarWidth))
+  el.style.setProperty('--g3-layout-sidebar-collapse-width', toCssLength(sizes.sidebarCollapseWidth))
+  el.style.setProperty('--g3-layout-sidebar-max-width', toCssLength(sizes.sidebarMaxWidth))
+  el.style.setProperty('--g3-layout-mixed-width', toCssLength(sizes.mixedSidebarWidth))
+  el.style.setProperty('--g3-layout-header-height', toCssLength(sizes.headerHeight))
+  el.style.setProperty('--g3-layout-tabbar-height', toCssLength(sizes.tabbarHeight))
+}
+
+/**
+ * 切换 @g3soft/tokens 的暗色基座（`html[data-g3-theme='dark']`）。
+ * 注意：这只是 token 基座开关，颜色体系仍由 ConfigProvider 派生，二者不冲突。
+ */
+export function applyDataTheme(dark: boolean, root?: HTMLElement): void {
+  if (typeof document === 'undefined') return
+  const el = root ?? document.documentElement
+  el.dataset.g3Theme = dark ? 'dark' : 'light'
+}
diff --git a/code/g3soft-libs/packages/framework/src/core/preferences/defaults.ts b/code/g3soft-libs/packages/framework/src/core/preferences/defaults.ts
new file mode 100644
index 00000000..56e2a913
--- /dev/null
+++ b/code/g3soft-libs/packages/framework/src/core/preferences/defaults.ts
@@ -0,0 +1,104 @@
+import type { G3Preferences } from '../types/preferences'
+import type { LayoutSizes } from '../types/layout'
+
+/** 布局尺寸默认值：沿用 fms 现状（展开 220 / 折叠 48 / 最大 400；双列主列 80）。 */
+export const defaultSizes: LayoutSizes = {
+  sidebarWidth: 220,
+  sidebarCollapseWidth: 48,
+  sidebarMaxWidth: 400,
+  mixedSidebarWidth: 80,
+  headerHeight: 56,
+  tabbarHeight: 40,
+}
+
+/**
+ * 偏好默认值。零配置即以此启动。
+ * 主题唯一「输出」仍是 `ConfigProvider → derivePalette → --g3-*`，这里只存种子。
+ */
+export const defaultPreferences: G3Preferences = {
+  app: {
+    layout: 'sidebar-nav',
+    name: undefined,
+    locale: 'zh-CN',
+    defaultHomePath: '/',
+    isMobile: false,
+  },
+  theme: {
+    mode: 'light',
+    colorPrimary: '#18181b',
+    radius: '6px',
+    fontSize: '14px',
+    builtinType: undefined,
+    semiDarkSidebar: false,
+    semiDarkHeader: false,
+    semiDarkSubSidebar: false,
+  },
+  sidebar: {
+    width: defaultSizes.sidebarWidth,
+    collapseWidth: defaultSizes.sidebarCollapseWidth,
+    mixedWidth: defaultSizes.mixedSidebarWidth,
+    collapsed: false,
+    collapsedShowTitle: true,
+    expandOnHover: false,
+    draggable: true,
+    hidden: false,
+  },
+  header: {
+    enable: true,
+    height: defaultSizes.headerHeight,
+    hidden: false,
+    mode: 'fixed',
+  },
+  tabbar: {
+    enable: true,
+    styleType: 'chrome',
+    showIcon: true,
+    showRefresh: true,
+    showMore: true,
+    showMaximize: false,
+    keepAlive: true,
+    draggable: false,
+    persist: true,
+    maxCount: 20,
+    middleClickToClose: true,
+  },
+  navigation: {
+    styleType: 'rounded',
+    accordion: true,
+    split: false,
+  },
+  breadcrumb: {
+    enable: true,
+    showIcon: true,
+    showHome: true,
+    styleType: 'normal',
+  },
+  logo: {
+    enable: true,
+    source: undefined,
+    text: undefined,
+  },
+  footer: {
+    enable: false,
+    text: undefined,
+  },
+  content: {
+    compact: false,
+    padding: '16px',
+    transition: 'fade-slide',
+  },
+}
+
+/** 默认持久化 storage key */
+export const DEFAULT_STORAGE_KEY = 'g3-preferences'
+
+/** 预设色板：选中即写入 theme.colorPrimary（种子色） */
+export const builtinPalettes: { label: string; value: string }[] = [
+  { label: '石墨黑', value: '#18181b' },
+  { label: '科技蓝', value: '#2563eb' },
+  { label: '青碧', value: '#0891b2' },
+  { label: '翠绿', value: '#16a34a' },
+  { label: '琥珀', value: '#d97706' },
+  { label: '朱红', value: '#dc2626' },
+  { label: '紫罗兰', value: '#7c3aed' },
+]
diff --git a/code/g3soft-libs/packages/framework/src/core/preferences/index.ts b/code/g3soft-libs/packages/framework/src/core/preferences/index.ts
new file mode 100644
index 00000000..86b28fac
--- /dev/null
+++ b/code/g3soft-libs/packages/framework/src/core/preferences/index.ts
@@ -0,0 +1,4 @@
+export { DEFAULT_STORAGE_KEY, builtinPalettes, defaultPreferences, defaultSizes } from './defaults'
+export { applyDataTheme, applyThemeVars, resolveDark, toCssLength } from './apply'
+export { setupPreferences, usePreferences } from './store'
+export type { G3PreferencesApi } from './store'
diff --git a/code/g3soft-libs/packages/framework/src/core/preferences/store.ts b/code/g3soft-libs/packages/framework/src/core/preferences/store.ts
new file mode 100644
index 00000000..40e01f00
--- /dev/null
+++ b/code/g3soft-libs/packages/framework/src/core/preferences/store.ts
@@ -0,0 +1,185 @@
+import { computed, reactive, readonly, watch } from 'vue'
+import type { G3ThemeConfig } from '@g3soft/ui'
+import type { LayoutSizes, LayoutType } from '../types/layout'
+import type { DeepPartial, G3Preferences } from '../types/preferences'
+import { deepClone, deepMerge, isPlainObject } from '../_utils/deep-merge'
+import { DEFAULT_STORAGE_KEY, defaultPreferences, defaultSizes } from './defaults'
+import { applyDataTheme, applyThemeVars, resolveDark } from './apply'
+
+interface PreferencesState {
+  /** 偏好主体 */
+  preferences: G3Preferences
+  /** 尺寸常量 */
+  sizes: LayoutSizes
+  /** 透传给 @g3soft/ui ConfigProvider 的主题（preferences.theme 会覆盖 primary / dark） */
+  theme: G3ThemeConfig
+  /** 持久化 key */
+  storageKey: string
+  /** 是否持久化 */
+  persist: boolean
+  /** 是否已初始化 */
+  started: boolean
+}
+
+const state = reactive<PreferencesState>({
+  preferences: deepClone(defaultPreferences),
+  sizes: { ...defaultSizes },
+  theme: { scope: 'global' },
+  storageKey: DEFAULT_STORAGE_KEY,
+  persist: true,
+  started: false,
+})
+
+let stopPersistWatch: (() => void) | null = null
+let mediaQuery: MediaQueryList | null = null
+
+/** 应用所有副作用：CSS 变量 + 暗色基座 */
+function applyAll(): void {
+  applyThemeVars(state.preferences.theme, state.sizes)
+  applyDataTheme(resolveDark(state.preferences.theme.mode))
+}
+
+/** 从 localStorage 读回已持久化的偏好（SSR / 隐私模式 / 解析失败均静默跳过） */
+function loadPersisted(): void {
+  if (typeof window === 'undefined') return
+  try {
+    const raw = window.localStorage.getItem(state.storageKey)
+    if (!raw) return
+    const parsed: unknown = JSON.parse(raw)
+    if (isPlainObject(parsed)) deepMerge(state.preferences, parsed)
+  } catch {
+    /* 忽略 */
+  }
+}
+
+function setupPersistence(): void {
+  if (typeof window === 'undefined' || !state.persist) return
+  loadPersisted()
+  stopPersistWatch?.()
+  stopPersistWatch = watch(
+    () => state.preferences,
+    () => {
+      try {
+        window.localStorage.setItem(state.storageKey, JSON.stringify(state.preferences))
+      } catch {
+        /* 忽略配额 / 隐私模式错误 */
+      }
+    },
+    { deep: true },
+  )
+}
+
+/** auto 模式：跟随系统亮暗变化 */
+function setupAutoThemeListener(): void {
+  if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') return
+  mediaQuery?.removeEventListener('change', applyAll)
+  mediaQuery = window.matchMedia('(prefers-color-scheme: dark)')
+  mediaQuery.addEventListener('change', applyAll)
+}
+
+const layout = computed<LayoutType>({
+  get: () => state.preferences.app.layout,
+  set: (value) => {
+    state.preferences.app.layout = value
+  },
+})
+
+const collapsed = computed<boolean>({
+  get: () => state.preferences.sidebar.collapsed,
+  set: (value) => {
+    state.preferences.sidebar.collapsed = value
+  },
+})
+
+/** 供 ConfigProvider 使用的主题：preferences 里的主色 / 暗色覆盖 store.theme */
+const resolvedTheme = computed<G3ThemeConfig>(() => ({
+  ...state.theme,
+  primary: state.preferences.theme.colorPrimary,
+  dark: resolveDark(state.preferences.theme.mode),
+  scope: 'global',
+}))
+
+export interface G3PreferencesApi {
+  /** 只读偏好（响应式） */
+  preferences: Readonly<G3Preferences>
+  /** 只读尺寸 */
+  sizes: Readonly<LayoutSizes>
+  /** 布局模式（可写 computed） */
+  layout: typeof layout
+  /** 侧栏折叠（可写 computed） */
+  collapsed: typeof collapsed
+  /** 解析后的 ConfigProvider 主题 */
+  resolvedTheme: typeof resolvedTheme
+  /** 深合并更新偏好 */
+  update: (patch: DeepPartial<G3Preferences>) => void
+  /** 更新尺寸常量 */
+  updateSizes: (patch: Partial<LayoutSizes>) => void
+  /** 重置为默认值 */
+  reset: () => void
+  /** 设置布局模式 */
+  setLayout: (value: LayoutType) => void
+  /** 切换侧栏折叠 */
+  toggleSidebar: (value?: boolean) => void
+  /** 立即应用副作用（一般无需手动调用） */
+  apply: () => void
+}
+
+const api: G3PreferencesApi = {
+  get preferences() {
+    return readonly(state.preferences) as Readonly<G3Preferences>
+  },
+  get sizes() {
+    return readonly(state.sizes) as Readonly<LayoutSizes>
+  },
+  layout,
+  collapsed,
+  resolvedTheme,
+  update(patch) {
+    deepMerge(state.preferences, patch)
+  },
+  updateSizes(patch) {
+    Object.assign(state.sizes, patch)
+    // 侧栏宽度与 sizes 同步（偏好里也有 width，保持二者一致）
+  },
+  reset() {
+    Object.assign(state.preferences, deepClone(defaultPreferences))
+    Object.assign(state.sizes, defaultSizes)
+  },
+  setLayout(value) {
+    state.preferences.app.layout = value
+  },
+  toggleSidebar(value) {
+    state.preferences.sidebar.collapsed = value ?? !state.preferences.sidebar.collapsed
+  },
+  apply: applyAll,
+}
+
+/** 获取偏好单例（模块级唯一，无需 pinia） */
+export function usePreferences(): G3PreferencesApi {
+  return api
+}
+
+/** 内部：初始化（由 createG3Framework 调用） */
+export function setupPreferences(patch: {
+  preferences?: DeepPartial<G3Preferences>
+  sizes?: Partial<LayoutSizes>
+  theme?: G3ThemeConfig
+  storageKey?: string
+  persist?: boolean
+}): void {
+  if (patch.storageKey) state.storageKey = patch.storageKey
+  if (patch.persist != null) state.persist = patch.persist
+  if (patch.theme) Object.assign(state.theme, patch.theme)
+  if (patch.preferences) deepMerge(state.preferences, patch.preferences)
+  if (patch.sizes) Object.assign(state.sizes, patch.sizes)
+
+  setupPersistence()
+  setupAutoThemeListener()
+  applyAll()
+  state.started = true
+}
+
+/** 内部：供调试读取原始（非只读）状态 */
+export function __getPreferencesState(): PreferencesState {
+  return state
+}
diff --git a/code/g3soft-libs/packages/framework/src/core/types/layout.ts b/code/g3soft-libs/packages/framework/src/core/types/layout.ts
new file mode 100644
index 00000000..ea66df2d
--- /dev/null
+++ b/code/g3soft-libs/packages/framework/src/core/types/layout.ts
@@ -0,0 +1,171 @@
+import type { Component } from 'vue'
+
+/**
+ * 布局模式。7 种全部实现，做法是「一个 G3Layout 组件 + `layout` prop 条件渲染」，
+ * 不拆成 7 个组件。
+ */
+export type LayoutType =
+  /** 垂直侧边菜单（默认） */
+  | 'sidebar-nav'
+  /** 顶部水平菜单 */
+  | 'header-nav'
+  /** 双列菜单：左窄列一级 + 右列子级 */
+  | 'sidebar-mixed-nav'
+  /** 无侧栏无顶栏（登录页 / 大屏） */
+  | 'full-content'
+  /** 顶部一级 + 侧栏二级 */
+  | 'mixed-nav'
+  /** 顶部混合 */
+  | 'header-mixed-nav'
+  /** 顶栏 + 侧栏 */
+  | 'header-sidebar-nav'
+
+/**
+ * 布局尺寸常量。默认值沿用 fms 现状，业务可通过偏好（preferences.sidebar / header）
+ * 或安装配置（G3FrameworkOptions.sizes）覆盖。
+ */
+export interface LayoutSizes {
+  /** 侧栏展开宽度，默认 220 */
+  sidebarWidth: number
+  /** 侧栏折叠宽度，默认 48 */
+  sidebarCollapseWidth: number
+  /** 侧栏可拖拽的最大宽度，默认 400 */
+  sidebarMaxWidth: number
+  /** 双列布局的主（窄）列宽度，默认 80 */
+  mixedSidebarWidth: number
+  /** 顶栏高度，默认 56 */
+  headerHeight: number
+  /** 页签栏高度，默认 40 */
+  tabbarHeight: number
+}
+
+/**
+ * 菜单 / 导航节点 —— framework 唯一认识的菜单形状（数据契约核心）。
+ *
+ * 数据来源由宿主注入（`:menus` 直接给数组，或 `:menu-source` 给函数），
+ * framework 不关心它来自哪个后端、哪张表。
+ */
+export interface NavItem {
+  /** 唯一标识，通常等于路由 path 或菜单 id */
+  key: string
+  /** 显示文本 */
+  title: string
+  /** 图标：图标名字符串（由宿主解析）或组件 */
+  icon?: string | Component
+  /** 站内路由地址 */
+  path?: string
+  /** 外链地址 */
+  link?: string
+  /** 是否为外部链接（配合 link 使用） */
+  external?: boolean
+  /** 徽标 */
+  badge?: string | number
+  /** 是否禁用 */
+  disabled?: boolean
+  /** 是否在菜单中隐藏 */
+  hidden?: boolean
+  /** 子菜单 */
+  children?: NavItem[]
+  /** 宿主可携带的任意扩展数据 */
+  meta?: Record<string, unknown>
+}
+
+/**
+ * 宿主路由 meta 的推荐结构。framework 按此解释路由信息，业务可自由扩展（索引签名）。
+ */
+export interface G3RouteMeta {
+  /** 标题（面包屑 / 页签 / 菜单回退显示） */
+  title?: string
+  /** 图标 */
+  icon?: string | Component
+  /** 权限 / 菜单标识（framework 不判定，交由宿主过滤） */
+  auth?: string | string[]
+  /** 是否在菜单中隐藏 */
+  hideInMenu?: boolean
+  /** 是否在页签栏中隐藏 */
+  hideInTab?: boolean
+  /** 是否在面包屑中隐藏 */
+  hideInBreadcrumb?: boolean
+  /** 是否 keep-alive 缓存页面 */
+  keepAlive?: boolean
+  /** 是否固定（affix）页签，不可关闭 */
+  affix?: boolean
+  /** 外链 */
+  link?: string
+  /** 菜单排序权重，越小越靠前 */
+  order?: number
+  /** 允许业务扩展 */
+  [key: string]: unknown
+}
+
+/**
+ * 当前登录用户。framework 仅用于展示（头像 / 名称），数据由宿主注入。
+ */
+export interface UserInfo {
+  id?: string | number
+  account?: string
+  name?: string
+  avatar?: string
+  roles?: string[]
+  /** 允许业务扩展（如 orgId 等） */
+  [key: string]: unknown
+}
+
+/**
+ * 菜单数据来源。宿主提供一个函数，framework 负责调用（含 loading / 失败 / 刷新）——
+ * 但函数体（调哪个接口、查哪张表）完全由宿主决定。这是"不绑死"的关键注入点。
+ */
+export type MenuSource = () => NavItem[] | Promise<NavItem[]>
+
+/**
+ * 布局零件的替换表。宿主可整体替换某个零件（如换自己的 Header），
+ * 而不只是改插槽内容。
+ */
+export interface LayoutComponentOverrides {
+  logo?: Component
+  header?: Component
+  sidebar?: Component
+  tabbar?: Component
+  breadcrumb?: Component
+}
+
+/**
+ * 页签项（页签栏展示用）。页签的「状态」（打开列表）由宿主或接线层管理，
+ * framework 只负责渲染与交互事件。
+ */
+export interface G3TabItem {
+  /** 唯一标识，通常等于路由 path */
+  key: string
+  /** 显示文本 */
+  title: string
+  /** 图标 */
+  icon?: string | Component
+  /** 是否可关闭（默认 true；affix 固定页签恒为不可关闭） */
+  closable?: boolean
+  /** 是否为固定页签 */
+  affix?: boolean
+}
+
+/**
+ * G3Layout 的 props（UI 契约之一）。所有 props 可选，零配置即可用默认值跑起来。
+ */
+export interface G3LayoutProps {
+  /** 布局模式。不传则取偏好（preferences.app.layout，默认 'sidebar-nav'） */
+  layout?: LayoutType
+  /** 菜单数据（与 menuSource 二选一；直接给数组时不做加载） */
+  menus?: NavItem[]
+  /** 菜单数据源（与 menus 二选一；给函数时 framework 接管加载流程） */
+  menuSource?: MenuSource
+  /** 当前激活的菜单 key（通常等于当前路由 path） */
+  activeKey?: string
+  /** 当前用户（用于顶栏头像 / 名称展示） */
+  user?: UserInfo
+  /** 页签列表（不传则不渲染页签栏内容） */
+  tabs?: G3TabItem[]
+  /** 侧栏是否折叠（受控；不传则由偏好 / 内部状态管理） */
+  collapsed?: boolean
+  /** 布局零件替换表 */
+  components?: LayoutComponentOverrides
+  /** 尺寸覆盖（不传用默认，见 LayoutSizes） */
+  sizes?: Partial<LayoutSizes>
+}
diff --git a/code/g3soft-libs/packages/framework/src/core/types/preferences.ts b/code/g3soft-libs/packages/framework/src/core/types/preferences.ts
new file mode 100644
index 00000000..c1455eff
--- /dev/null
+++ b/code/g3soft-libs/packages/framework/src/core/types/preferences.ts
@@ -0,0 +1,212 @@
+import type { G3ThemeConfig } from '@g3soft/ui'
+import type { LayoutType, LayoutSizes } from './layout'
+
+/** 深部分类型：用于「偏好初始值覆盖默认值」 */
+export type DeepPartial<T> = {
+  [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K]
+}
+
+/** 主题模式 */
+export type ThemeMode = 'light' | 'dark' | 'auto'
+
+/**
+ * app 组偏好。
+ * 相比 vben 砍掉了 accessMode / authPageLayout / checkUpdates / timezone。
+ */
+export interface AppPreferences {
+  /** 布局模式 */
+  layout: LayoutType
+  /** 应用名称（用于标题 / logo 文案回退） */
+  name?: string
+  /** 语言，如 'zh-CN' / 'en-US' */
+  locale?: string
+  /** 登录后默认首页路径 */
+  defaultHomePath?: string
+  /** 是否移动端（通常由框架自动判定，此处可在初始化时覆盖） */
+  isMobile?: boolean
+}
+
+/**
+ * theme 组偏好。
+ *
+ * 关键：这一组只作为「输入」，唯一「输出」仍是 @g3soft/ui 的
+ * `ConfigProvider → derivePalette → --g3-*`。framework 不另起一套 CSS 变量系统。
+ */
+export interface ThemePreferences {
+  /** 亮 / 暗 / 跟随系统 */
+  mode: ThemeMode
+  /** 主色种子色。只给一个种子色，色阶 / 交互态 / on-primary 由 derivePalette 自动派生 */
+  colorPrimary: string
+  /** 全局圆角（CSS 值，如 '6px'），映射到 --g3-radius */
+  radius?: string | number
+  /** 基础字号（CSS 值，如 '14px'），映射到 --g3-font-size-base */
+  fontSize?: string | number
+  /** 预设色板标识（选中即写入 colorPrimary） */
+  builtinType?: string
+  /** 半深色侧栏 —— 布局专属，首期只留类型不实现 */
+  semiDarkSidebar?: boolean
+  /** 半深色顶栏 —— 布局专属，首期只留类型不实现 */
+  semiDarkHeader?: boolean
+  /** 半深色子侧栏 —— 布局专属，首期只留类型不实现 */
+  semiDarkSubSidebar?: boolean
+}
+
+/** sidebar 组偏好 */
+export interface SidebarPreferences {
+  /** 展开宽度，默认 220 */
+  width: number
+  /** 折叠宽度，默认 48 */
+  collapseWidth: number
+  /** 双列主列宽度，默认 80 */
+  mixedWidth: number
+  /** 是否折叠 */
+  collapsed: boolean
+  /** 折叠时是否仍显示菜单标题 */
+  collapsedShowTitle?: boolean
+  /** 悬浮时是否临时展开 */
+  expandOnHover?: boolean
+  /** 是否可拖拽调宽 */
+  draggable?: boolean
+  /** 是否隐藏侧栏 */
+  hidden?: boolean
+}
+
+/** 顶栏模式 */
+export type HeaderMode = 'fixed' | 'static' | 'auto'
+
+/** header 组偏好 */
+export interface HeaderPreferences {
+  /** 是否显示顶栏 */
+  enable: boolean
+  /** 顶栏高度，默认 56 */
+  height: number
+  /** 是否隐藏 */
+  hidden?: boolean
+  /** 固定 / 静态 / 自动 */
+  mode?: HeaderMode
+}
+
+/** 页签栏风格 */
+export type TabbarStyleType = 'chrome' | 'plain'
+
+/** tabbar 组偏好 */
+export interface TabbarPreferences {
+  /** 是否启用页签栏 */
+  enable: boolean
+  /** 风格 */
+  styleType?: TabbarStyleType
+  /** 是否显示页签图标 */
+  showIcon?: boolean
+  /** 是否显示刷新按钮 */
+  showRefresh?: boolean
+  /** 是否显示更多按钮 */
+  showMore?: boolean
+  /** 是否显示最大化按钮 */
+  showMaximize?: boolean
+  /** 是否 keep-alive 缓存 */
+  keepAlive?: boolean
+  /** 是否可拖拽排序 */
+  draggable?: boolean
+  /** 是否持久化页签 */
+  persist?: boolean
+  /** 最大页签数（超过按 LRU 关闭） */
+  maxCount?: number
+  /** 中键点击是否关闭页签 */
+  middleClickToClose?: boolean
+}
+
+/** 导航风格 */
+export type NavigationStyleType = 'rounded' | 'plain'
+
+/** navigation 组偏好 */
+export interface NavigationPreferences {
+  /** 菜单项风格 */
+  styleType?: NavigationStyleType
+  /** 是否手风琴（同层只展开一个） */
+  accordion?: boolean
+  /** 是否分栏（顶级与子级分列） */
+  split?: boolean
+}
+
+/** 面包屑风格 */
+export type BreadcrumbStyleType = 'normal' | 'background'
+
+/** breadcrumb 组偏好 */
+export interface BreadcrumbPreferences {
+  /** 是否显示面包屑 */
+  enable: boolean
+  /** 是否显示图标 */
+  showIcon?: boolean
+  /** 是否显示首页 */
+  showHome?: boolean
+  /** 风格 */
+  styleType?: BreadcrumbStyleType
+}
+
+/** logo 偏好（从 vben 的独立组合并而来） */
+export interface LogoPreferences {
+  /** 是否显示 logo */
+  enable?: boolean
+  /** logo 图片地址 */
+  source?: string
+  /** logo 文案 */
+  text?: string
+}
+
+/** footer 偏好（合并组） */
+export interface FooterPreferences {
+  /** 是否显示页脚 */
+  enable?: boolean
+  /** 页脚文案 */
+  text?: string
+}
+
+/** content 组偏好（合并组） */
+export interface ContentPreferences {
+  /** 是否紧凑模式 */
+  compact?: boolean
+  /** 内容区内边距（CSS 值） */
+  padding?: string | number
+  /** 页面过渡动画名，默认 'fade-slide'（不做成偏好项，仅保留字段） */
+  transition?: string
+}
+
+/**
+ * 偏好总模型。
+ *
+ * 主要 7 组：app / theme / sidebar / header / tabbar / navigation / breadcrumb；
+ * 另合并了 logo / footer / content 三小组（原 vben 里更细的组被砍）。
+ * 砍掉的组：shortcutKeys / widget / transition(独立组) / copyright。
+ */
+export interface G3Preferences {
+  app: AppPreferences
+  theme: ThemePreferences
+  sidebar: SidebarPreferences
+  header: HeaderPreferences
+  tabbar: TabbarPreferences
+  navigation: NavigationPreferences
+  breadcrumb: BreadcrumbPreferences
+  logo: LogoPreferences
+  footer: FooterPreferences
+  content: ContentPreferences
+}
+
+/**
+ * 安装配置（配置契约）—— 宿主在 main.ts 里一次性传入。
+ * 所有字段可选，零配置即可用默认值启动。
+ *
+ * 注意：接口层（request / ApiResponse / 默认菜单源）不在 core，后续以 preset 形式接入，
+ * 因此这里暂不含 request 相关配置。
+ */
+export interface G3FrameworkOptions {
+  /** 偏好初始值，深合并到默认值之上 */
+  preferences?: DeepPartial<G3Preferences>
+  /** 尺寸常量覆盖（侧栏 / 顶栏 / 页签等） */
+  sizes?: Partial<LayoutSizes>
+  /** 主题配置：直接对接 @g3soft/ui 的 G3ThemeConfig，不另起体系 */
+  theme?: G3ThemeConfig
+  /** 偏好持久化的命名空间 / storage key，默认 'g3-preferences' */
+  storageKey?: string
+  /** 是否持久化偏好，默认 true */
+  persist?: boolean
+}
diff --git a/code/g3soft-libs/packages/framework/src/core/types/slots.ts b/code/g3soft-libs/packages/framework/src/core/types/slots.ts
new file mode 100644
index 00000000..ce2be84a
--- /dev/null
+++ b/code/g3soft-libs/packages/framework/src/core/types/slots.ts
@@ -0,0 +1,44 @@
+import type { NavItem } from './layout'
+
+/**
+ * G3Layout 插槽（UI 契约之一）。
+ *
+ * 原则：插槽宁可多不要少；每个插槽都有默认实现，宿主不填即用默认。
+ * 插槽参数目前只给必要上下文，后续实现阶段可扩。
+ */
+export interface G3LayoutSlots {
+  /** 品牌区（侧栏顶部 / 顶栏左侧） */
+  logo?: (props: { collapsed: boolean }) => any
+  /** 顶栏左侧（默认：面包屑） */
+  'header-left'?: (props: { collapsed: boolean }) => any
+  /** 顶栏右侧（默认：主题切换 + 用户菜单） */
+  'header-right'?: (props: { collapsed: boolean }) => any
+  /** 侧栏顶部（logo 下方） */
+  'sidebar-top'?: (props: { collapsed: boolean }) => any
+  /** 侧栏底部（菜单下方） */
+  'sidebar-footer'?: (props: { collapsed: boolean }) => any
+  /** 页签栏右侧扩展区 */
+  'tabbar-extra'?: (props: {}) => any
+  /** 面包屑右侧扩展区 */
+  'breadcrumb-extra'?: (props: {}) => any
+  /** 页面内容区（唯一必需；布局的主内容由此承载） */
+  page?: (props: {}) => any
+  /** 兜底：完全自定义整个布局（提供后覆盖内置布局） */
+  default?: (props: {}) => any
+}
+
+/**
+ * G3Layout 事件（UI 契约之一）。
+ */
+export interface G3LayoutEmits {
+  /** 点击菜单项：宿主据此做路由跳转（framework 不直接依赖 vue-router） */
+  (e: 'navigate', payload: { item: NavItem; key: string; event?: MouseEvent }): void
+  /** 菜单选中变化 */
+  (e: 'menu-select', key: string): void
+  /** 侧栏折叠状态变化 */
+  (e: 'update:collapsed', collapsed: boolean): void
+  /** 页签切换 */
+  (e: 'tab-change', key: string): void
+  /** 页签关闭 */
+  (e: 'tab-close', key: string): void
+}
diff --git a/code/g3soft-libs/packages/framework/src/index.ts b/code/g3soft-libs/packages/framework/src/index.ts
new file mode 100644
index 00000000..58004182
--- /dev/null
+++ b/code/g3soft-libs/packages/framework/src/index.ts
@@ -0,0 +1,3 @@
+// @g3soft/framework 公共入口。
+// 当前仅 core（布局骨架 + 契约）。接口层将以 preset 子路径（如 /presets/g3-backend）后续接入。
+export * from './core'
diff --git a/code/g3soft-libs/packages/framework/tsconfig.json b/code/g3soft-libs/packages/framework/tsconfig.json
new file mode 100644
index 00000000..c5bb749e
--- /dev/null
+++ b/code/g3soft-libs/packages/framework/tsconfig.json
@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "jsx": "preserve",
+    "strict": true,
+    "noImplicitOverride": true,
+    "esModuleInterop": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "types": ["vite/client"]
+  },
+  "include": ["src/**/*.ts", "src/**/*.vue", "vite.config.ts"]
+}
diff --git a/code/g3soft-libs/packages/framework/vite.config.ts b/code/g3soft-libs/packages/framework/vite.config.ts
new file mode 100644
index 00000000..3de59175
--- /dev/null
+++ b/code/g3soft-libs/packages/framework/vite.config.ts
@@ -0,0 +1,40 @@
+import { fileURLToPath } from 'node:url'
+import vue from '@vitejs/plugin-vue'
+import { defineConfig } from 'vite'
+import dts from 'vite-plugin-dts'
+
+/**
+ * @g3soft/framework 构建：产出 ESM + 类型声明。
+ *
+ * 关键点（与 @g3soft/ui 一致、刻意保持轻量）：
+ *  - vue 外置：绝不打包 Vue，避免消费方双实例
+ *  - @g3soft/ui 外置：framework 建立在组件库之上，由消费方按正常依赖解析，避免重复打包
+ *  - preserveModules 保留 src 结构，消费方可 tree-shaking
+ *  - vite-plugin-dts 的 rollupTypes 产出单文件 dist/index.d.ts，配合 exports.types
+ */
+export default defineConfig({
+  plugins: [
+    vue(),
+    // 每个源文件产出对应 .d.ts，src/index.ts → dist/index.d.ts（桶文件，re-export ./core/...）。
+    // 不做类型打包（bundleTypes 需额外装 @microsoft/api-extractor，与 @g3soft/ui 保持一致地省略）。
+    dts({
+      include: ['src'],
+    }),
+  ],
+  build: {
+    lib: {
+      entry: fileURLToPath(new URL('./src/index.ts', import.meta.url)),
+      formats: ['es'],
+      fileName: () => 'index.js',
+    },
+    rollupOptions: {
+      external: ['vue', '@g3soft/ui'],
+      output: {
+        preserveModules: true,
+        preserveModulesRoot: 'src',
+        entryFileNames: '[name].js',
+        assetFileNames: 'style.css',
+      },
+    },
+  },
+})
diff --git a/code/g3soft-libs/packages/tokens/src/scss/theme.scss b/code/g3soft-libs/packages/tokens/src/scss/theme.scss
index 1e979d43..ee4d2c24 100644
--- a/code/g3soft-libs/packages/tokens/src/scss/theme.scss
+++ b/code/g3soft-libs/packages/tokens/src/scss/theme.scss
@@ -66,6 +66,29 @@ $dark-primary: #e5e5e5;
 
   /* ---------- 阴影 ---------- */
   #{fn.css-var('shadow')}: 0 2px 8px rgba(0, 0, 0, 0.15);
+  /* 浮层阴影：下拉 / 气泡 / 日期面板等 */
+  #{fn.css-var('shadow-popup')}: 0 6px 16px rgba(0, 0, 0, 0.12);
+
+  /* ---------- 交互填充（hover 底 / 轨道底 / 次级面）---------- */
+  #{fn.css-var('fill')}: rgba(0, 0, 0, 0.04);
+  #{fn.css-var('fill-hover')}: rgba(0, 0, 0, 0.08);
+
+  /* ---------- 主色淡底（选中 / hover 高亮），跟随主色换肤 ----------
+     color-mix() 的颜色参数必须是 var(...)：只写变量名（--g3-color-primary）
+     会让整个函数解析失败，变量值为空 → 用到它的地方全都「没有背景色」 */
+  #{fn.css-var('color-primary-soft')}: color-mix(
+    in srgb,
+    var(#{fn.css-var('color-primary')}) 12%,
+    transparent
+  );
+
+  /* ---------- 遮罩 ---------- */
+  #{fn.css-var('mask-bg')}: rgba(0, 0, 0, 0.45);
+
+  /* ---------- 行高与动效档位 ---------- */
+  #{fn.css-var('line-height')}: 1.5;
+  #{fn.css-var('duration-fast')}: 0.1s;
+  #{fn.css-var('duration-slow')}: 0.3s;
 }
 
 // 暗色主题：只覆盖变量值，不改变量名。
@@ -87,4 +110,16 @@ html[data-#{config.$namespace}-theme='dark'] {
   #{fn.css-var('border-color')}: #424242;
 
   #{fn.css-var('shadow')}: 0 2px 8px rgba(0, 0, 0, 0.45);
+  #{fn.css-var('shadow-popup')}: 0 6px 16px rgba(0, 0, 0, 0.5);
+
+  #{fn.css-var('fill')}: rgba(255, 255, 255, 0.06);
+  #{fn.css-var('fill-hover')}: rgba(255, 255, 255, 0.12);
+
+  #{fn.css-var('color-primary-soft')}: color-mix(
+    in srgb,
+    var(#{fn.css-var('color-primary')}) 20%,
+    transparent
+  );
+
+  #{fn.css-var('mask-bg')}: rgba(0, 0, 0, 0.6);
 }
diff --git a/code/g3soft-libs/packages/ui/e2e/data.spec.ts b/code/g3soft-libs/packages/ui/e2e/data.spec.ts
new file mode 100644
index 00000000..0f2e5601
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/e2e/data.spec.ts
@@ -0,0 +1,171 @@
+import { expect, test } from '@playwright/test'
+
+/**
+ * 数据展示类组件的交互回归。
+ *
+ * 注意：用 page.mouse.* 之前必须先 scrollIntoViewIfNeeded ——
+ * mouse 事件按视口坐标派发，元素在视口外时事件会落到别的元素上
+ * （表现为「拖拽/点击完全没反应」，很容易被误判成组件 bug）。
+ */
+
+test.describe('Tabs', () => {
+  test('面板懒渲染，切换后保留旧面板（表单状态不丢）', async ({ page }) => {
+    await page.goto('/')
+    const tabs = page.getByTestId('tabs')
+
+    await expect(tabs.locator('.g3-tabs__pane')).toHaveCount(1)
+    await tabs.locator('.g3-tabs__tab').nth(1).click()
+    await expect(tabs.locator('.g3-tabs__pane')).toHaveCount(2)
+    await expect(tabs.locator('.g3-tabs__pane').first()).toBeHidden()
+  })
+
+  test('禁用标签不可点击（回归：空值布尔属性被 Boolean("") 判成 false）', async ({ page }) => {
+    await page.goto('/')
+    const tabs = page.getByTestId('tabs')
+    const disabled = tabs.locator('.g3-tabs__tab').nth(2)
+
+    await expect(disabled).toBeDisabled()
+    await expect(disabled).toHaveAttribute('aria-disabled', 'true')
+    await expect(tabs.locator('.g3-tabs__pane')).toHaveCount(1)
+  })
+})
+
+test.describe('Tree', () => {
+  test('勾选父节点后子节点全选（父子联动）', async ({ page }) => {
+    await page.goto('/')
+    const tree = page.getByTestId('tree')
+    const checkboxes = tree.locator('.g3-tree-node__checkbox .g3-checkbox')
+
+    await expect(checkboxes).toHaveCount(6)
+    await checkboxes.first().click()
+
+    const checkedCount = await tree.locator('.g3-tree-node__checkbox .g3-checkbox.is-checked').count()
+    // 「前端」及其 3 个子孙（Vue / 组合式 API / React）
+    expect(checkedCount).toBe(4)
+  })
+
+  test('收起父节点后其子孙不再渲染（后端仍展开，所以剩下 3 个）', async ({ page }) => {
+    await page.goto('/')
+    const tree = page.getByTestId('tree')
+
+    await expect(tree.locator('.g3-tree-node')).toHaveCount(6)
+    await tree.locator('.g3-tree-node__switcher').first().click()
+    await expect(tree.locator('.g3-tree-node')).toHaveCount(3)
+  })
+})
+
+test.describe('Pagination', () => {
+  test('省略号点击跳 5 页', async ({ page }) => {
+    await page.goto('/')
+    const pagination = page.getByTestId('pagination')
+
+    await expect(pagination.locator('[aria-current="page"]')).toHaveText('1')
+    await pagination.locator('.g3-pagination__ellipsis').click()
+    await expect(pagination.locator('[aria-current="page"]')).toHaveText('6')
+  })
+
+  test('显示总数与跳页控件', async ({ page }) => {
+    await page.goto('/')
+    const pagination = page.getByTestId('pagination')
+
+    await expect(pagination.locator('.g3-pagination__total')).toContainText('126')
+    await expect(pagination.locator('.g3-pagination__jumper')).toBeVisible()
+  })
+})
+
+test.describe('Splitter', () => {
+  test('拖拽分隔条同时改变分隔条位置与两侧尺寸', async ({ page }) => {
+    await page.goto('/')
+    const splitter = page.getByTestId('splitter')
+    await splitter.scrollIntoViewIfNeeded()
+
+    const panels = splitter.locator('.g3-splitter-panel')
+    const bar = splitter.locator('.g3-splitter__bar')
+
+    // 探针：区分「pointerdown 没落到分隔条上」与「落上了但逻辑没生效」
+    await page.evaluate(() => {
+      ;(window as unknown as { __barDown: number }).__barDown = 0
+      document.querySelector('.g3-splitter__bar')?.addEventListener('pointerdown', () => {
+        ;(window as unknown as { __barDown: number }).__barDown += 1
+      })
+    })
+
+    const before = (await panels.first().boundingBox())!.width
+    const box = (await bar.boundingBox())!
+    const centerX = box.x + box.width / 2
+    const centerY = box.y + box.height / 2
+
+    await page.mouse.move(centerX, centerY)
+    await page.mouse.down()
+    await page.mouse.move(centerX + 40, centerY, { steps: 3 })
+    await page.mouse.move(centerX + 80, centerY, { steps: 3 })
+    await page.mouse.up()
+    await page.waitForTimeout(150)
+
+    const barDown = await page.evaluate(() => (window as unknown as { __barDown: number }).__barDown)
+    expect(barDown).toBe(1)
+    expect((await panels.first().boundingBox())!.width).toBeGreaterThan(before + 20)
+  })
+
+  test('分隔条可键盘调整（方向键 ±10px）', async ({ page }) => {
+    await page.goto('/')
+    const splitter = page.getByTestId('splitter')
+    await splitter.scrollIntoViewIfNeeded()
+
+    const panels = splitter.locator('.g3-splitter-panel')
+    const before = (await panels.first().boundingBox())!.width
+
+    await splitter.locator('.g3-splitter__bar').focus()
+    await page.keyboard.press('ArrowRight')
+    await page.keyboard.press('ArrowRight')
+
+    expect((await panels.first().boundingBox())!.width).toBeGreaterThan(before + 10)
+  })
+})
+
+test.describe('Scrollbar', () => {
+  test('点击轨道跳转滚动（clickScroll 默认开启）', async ({ page }) => {
+    await page.goto('/')
+    const scrollbar = page.getByTestId('scrollbar')
+    await scrollbar.scrollIntoViewIfNeeded()
+
+    const view = scrollbar.locator('.g3-scrollbar__view')
+    expect(await view.evaluate((el) => el.scrollTop)).toBe(0)
+
+    const track = (await scrollbar.locator('.g3-scrollbar__track-v').boundingBox())!
+    await page.mouse.click(track.x + track.width / 2, track.y + track.height * 0.7)
+    await page.waitForTimeout(100)
+
+    expect(await view.evaluate((el) => el.scrollTop)).toBeGreaterThan(0)
+  })
+
+  test('拖动滑块同步滚动位置', async ({ page }) => {
+    await page.goto('/')
+    const scrollbar = page.getByTestId('scrollbar')
+    await scrollbar.scrollIntoViewIfNeeded()
+
+    const view = scrollbar.locator('.g3-scrollbar__view')
+    const box = (await scrollbar.locator('.g3-scrollbar__thumb-v').boundingBox())!
+    const centerX = box.x + box.width / 2
+    const centerY = box.y + box.height / 2
+
+    await page.mouse.move(centerX, centerY)
+    await page.mouse.down()
+    await page.mouse.move(centerX, centerY + 60, { steps: 5 })
+    await page.mouse.up()
+    await page.waitForTimeout(100)
+
+    expect(await view.evaluate((el) => el.scrollTop)).toBeGreaterThan(0)
+  })
+})
+
+test.describe('Segmented', () => {
+  test('点击选项切换选中态（滑块跟随）', async ({ page }) => {
+    await page.goto('/')
+    const segmented = page.getByTestId('segmented')
+
+    await expect(segmented.locator('.g3-segmented__item.is-selected')).toHaveText('日')
+    await segmented.locator('.g3-segmented__item').filter({ hasText: '周' }).click()
+    await expect(segmented.locator('.g3-segmented__item.is-selected')).toHaveText('周')
+  })
+})
diff --git a/code/g3soft-libs/packages/ui/e2e/drawer.spec.ts b/code/g3soft-libs/packages/ui/e2e/drawer.spec.ts
new file mode 100644
index 00000000..c1b8dfd0
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/e2e/drawer.spec.ts
@@ -0,0 +1,131 @@
+import { expect, test } from '@playwright/test'
+
+/**
+ * Drawer 四个方向的几何回归。
+ *
+ * 漏测教训：之前只验了默认的 `right`，导致「上下方向的抽屉宽度不是 100%」一直没被发现。
+ * 根因是容器用 flex 的 justify-content / align-items 做吸附 —— 两条轴各管一个方向，
+ * 上下面板在主轴（水平）方向没有约束，宽度缩到了内容宽。
+ * 现在改为按方向定边（上下 `left/right: 0`、左右 `top/bottom: 0`），与 fms 一致。
+ *
+ * 断言以 `.g3-drawer__wrap`（定位容器）为参照，而不是写死视口尺寸：
+ * 视口高度受 `devices['Desktop Chrome']` 与滚动条影响，写死会得到假失败。
+ * 这类断言必须放 E2E：真实布局结果在 happy-dom 里量不出来。
+ */
+
+/** 打开指定方向的抽屉，返回面板与定位容器的几何 */
+async function openDrawer(page: import('@playwright/test').Page, testId: string) {
+  await page.getByTestId(testId).click()
+  const drawer = page.locator('.g3-drawer')
+  await expect(drawer).toBeVisible()
+  // 等入场动画结束（transform 归零），否则量到的是滑入途中的位置
+  await page.waitForTimeout(450)
+
+  const panel = (await drawer.boundingBox())!
+  const wrap = (await page.locator('.g3-drawer__wrap').boundingBox())!
+  return { drawer, panel, wrap }
+}
+
+test.describe('Drawer 方向与尺寸', () => {
+  test('右侧：贴右边缘、纵向撑满，宽度取 width', async ({ page }) => {
+    await page.goto('/')
+    const { panel, wrap } = await openDrawer(page, 'open-drawer')
+
+    expect(Math.round(panel.x + panel.width)).toBeCloseTo(Math.round(wrap.x + wrap.width), 0)
+    expect(Math.round(panel.height)).toBeCloseTo(Math.round(wrap.height), 0)
+    expect(Math.round(panel.width)).toBe(378)
+  })
+
+  test('左侧：贴左边缘、纵向撑满', async ({ page }) => {
+    await page.goto('/')
+    const { panel, wrap } = await openDrawer(page, 'open-drawer-left')
+
+    expect(Math.round(panel.x)).toBeCloseTo(Math.round(wrap.x), 0)
+    expect(Math.round(panel.height)).toBeCloseTo(Math.round(wrap.height), 0)
+    expect(Math.round(panel.width)).toBe(378)
+  })
+
+  test('上方：贴顶、横向撑满（回归：宽度曾是内容宽）', async ({ page }) => {
+    await page.goto('/')
+    const { panel, wrap } = await openDrawer(page, 'open-drawer-top')
+
+    expect(Math.round(panel.y)).toBeCloseTo(Math.round(wrap.y), 0)
+    expect(Math.round(panel.width)).toBeCloseTo(Math.round(wrap.width), 0)
+    expect(Math.round(panel.height)).toBe(378)
+  })
+
+  test('下方：贴底、横向撑满（回归：宽度曾是内容宽）', async ({ page }) => {
+    await page.goto('/')
+    const { panel, wrap } = await openDrawer(page, 'open-drawer-bottom')
+
+    expect(Math.round(panel.y + panel.height)).toBeCloseTo(Math.round(wrap.y + wrap.height), 0)
+    expect(Math.round(panel.width)).toBeCloseTo(Math.round(wrap.width), 0)
+    expect(Math.round(panel.height)).toBe(378)
+  })
+
+  test('四个方向都能撑满对应轴，且面板不被自身遮罩压住', async ({ page }) => {
+    await page.goto('/')
+
+    for (const [testId, name, axis] of [
+      ['open-drawer', '右', 'height'],
+      ['open-drawer-left', '左', 'height'],
+      ['open-drawer-top', '上', 'width'],
+      ['open-drawer-bottom', '下', 'width'],
+    ] as const) {
+      const { drawer, panel, wrap } = await openDrawer(page, testId)
+
+      if (axis === 'height') {
+        expect(Math.round(panel.height), `${name}侧抽屉未撑满高度`).toBeCloseTo(
+          Math.round(wrap.height),
+          0,
+        )
+      } else {
+        expect(Math.round(panel.width), `${name}侧抽屉未撑满宽度`).toBeCloseTo(
+          Math.round(wrap.width),
+          0,
+        )
+      }
+
+      const hit = await page.evaluate(
+        ([x, y]) => {
+          const el = document.elementFromPoint(x as number, y as number)
+          return el ? String(el.className || el.tagName) : null
+        },
+        [panel.x + panel.width / 2, panel.y + Math.min(20, panel.height / 2)],
+      )
+      expect(hit, `${name}侧抽屉面板被遮挡`).toContain('g3-drawer')
+
+      await page.keyboard.press('Escape')
+      await expect(drawer).toBeHidden()
+    }
+  })
+
+  test('面板尺寸由组件自己决定，不受宿主页面全局样式污染', async ({ page }) => {
+    await page.goto('/')
+    // 模拟用户页面的「全局元素选择器」：面板本体是 <section>，header / footer 同理
+    await page.addStyleTag({
+      content: `
+        section { margin: 16px; padding: 24px; border: 2px solid red; }
+        header { margin: 12px; padding: 20px; }
+        footer { margin: 12px; padding: 20px; }
+      `,
+    })
+
+    const { panel, wrap } = await openDrawer(page, 'open-drawer')
+
+    const styles = await page.$eval('.g3-drawer', (el) => {
+      const cs = getComputedStyle(el)
+      return {
+        margin: [cs.marginTop, cs.marginRight, cs.marginBottom, cs.marginLeft],
+        padding: [cs.paddingTop, cs.paddingRight, cs.paddingBottom, cs.paddingLeft],
+        borderWidth: cs.borderTopWidth,
+      }
+    })
+
+    expect(styles.margin).toEqual(['0px', '0px', '0px', '0px'])
+    expect(styles.padding).toEqual(['0px', '0px', '0px', '0px'])
+    expect(styles.borderWidth).toBe('0px')
+    // 仍然撑满：宿主 margin 不该从高度里扣掉 16px
+    expect(Math.round(panel.height)).toBeCloseTo(Math.round(wrap.height), 0)
+  })
+})
diff --git a/code/g3soft-libs/packages/ui/e2e/feedback.spec.ts b/code/g3soft-libs/packages/ui/e2e/feedback.spec.ts
new file mode 100644
index 00000000..60ffcaf8
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/e2e/feedback.spec.ts
@@ -0,0 +1,138 @@
+import { expect, test } from '@playwright/test'
+
+/**
+ * 反馈类组件回归。
+ *
+ * 曾经踩过的坑：
+ * - Message 的方位类名手写成 `g3-message-list--*`（样式表是 `g3-message__list--*`），
+ *   9 个方位全部失效、消息一律堆在左上角；
+ * - Modal 面板不是弹性布局，缩放后内容溢出面板而不是内部滚动。
+ */
+
+test.describe('Message 方位', () => {
+  test('默认方位是顶部居中', async ({ page }) => {
+    await page.goto('/')
+    await page.getByTestId('toast-default').click()
+
+    const message = page.locator('.g3-message').first()
+    await expect(message).toBeVisible()
+
+    const messageBox = (await message.boundingBox())!
+    const viewport = page.viewportSize()!
+    const center = messageBox.x + messageBox.width / 2
+
+    expect(Math.abs(center - viewport.width / 2)).toBeLessThan(2)
+    expect(messageBox.y).toBeLessThan(viewport.height * 0.25)
+  })
+
+  test('指定方位生效：左上 / 右下', async ({ page }) => {
+    await page.goto('/')
+    const viewport = page.viewportSize()!
+
+    await page.getByTestId('toast-top-left').click()
+    const topLeft = (await page.locator('.g3-message').first().boundingBox())!
+    expect(topLeft.x).toBeLessThan(48)
+    expect(topLeft.y).toBeLessThan(viewport.height * 0.25)
+
+    await page.waitForTimeout(3200)
+
+    await page.getByTestId('toast-bottom-right').click()
+    const bottomRight = (await page.locator('.g3-message').first().boundingBox())!
+    expect(bottomRight.x + bottomRight.width).toBeGreaterThan(viewport.width - 48)
+    expect(bottomRight.y).toBeGreaterThan(viewport.height * 0.6)
+  })
+})
+
+test.describe('Notification', () => {
+  test('默认出现在右上角', async ({ page }) => {
+    await page.goto('/')
+    const viewport = page.viewportSize()!
+    await page.getByTestId('notify').click()
+
+    const notification = page.locator('.g3-notification').first()
+    await expect(notification).toBeVisible()
+
+    const box = (await notification.boundingBox())!
+    expect(box.x + box.width).toBeGreaterThan(viewport.width - 48)
+    expect(box.y).toBeLessThan(viewport.height * 0.3)
+  })
+})
+
+test.describe('Modal', () => {
+  test('缩放变矮后内容区内部滚动，而不是溢出面板', async ({ page }) => {
+    await page.goto('/')
+    await page.getByTestId('open-modal').click()
+
+    const modal = page.locator('.g3-modal')
+    await expect(modal).toBeVisible()
+
+    // 把南侧手柄往上拖，压缩面板高度
+    const handle = (await page.locator('.g3-modal__resizer-s').boundingBox())!
+    const startX = handle.x + handle.width / 2
+    await page.mouse.move(startX, handle.y + handle.height / 2)
+    await page.mouse.down()
+    await page.mouse.move(startX, handle.y - 400, { steps: 8 })
+    await page.mouse.up()
+
+    const panel = (await modal.boundingBox())!
+    const body = await page.evaluate(() => {
+      const el = document.querySelector('.g3-modal__body') as HTMLElement
+      return { client: el.clientHeight, scroll: el.scrollHeight }
+    })
+
+    // 面板被压矮，内容比可视区高 → 必须内部滚动
+    expect(panel.height).toBeLessThan(700)
+    expect(body.scroll).toBeGreaterThan(body.client)
+  })
+
+  test('Esc 关闭，遮罩点击可关闭', async ({ page }) => {
+    await page.goto('/')
+    await page.getByTestId('open-modal').click()
+    await expect(page.locator('.g3-modal')).toBeVisible()
+
+    await page.keyboard.press('Escape')
+    await expect(page.locator('.g3-modal')).toBeHidden()
+
+    await page.getByTestId('open-modal').click()
+    await page.mouse.click(60, 400)
+    await expect(page.locator('.g3-modal')).toBeHidden()
+  })
+
+  test('焦点被限制在面板内（Tab 循环）', async ({ page }) => {
+    await page.goto('/')
+    await page.getByTestId('open-modal').click()
+    await expect(page.locator('.g3-modal')).toBeVisible()
+
+    for (let index = 0; index < 8; index += 1) {
+      await page.keyboard.press('Tab')
+    }
+
+    const inside = await page.evaluate(() => {
+      const panel = document.querySelector('.g3-modal')
+      return panel ? panel.contains(document.activeElement) : false
+    })
+    expect(inside).toBe(true)
+  })
+})
+
+test.describe('Modal.confirm（命令式）', () => {
+  test('点确定后按钮进入 loading，完成后自动关闭', async ({ page }) => {
+    await page.goto('/')
+    await page.getByTestId('open-confirm').click()
+
+    const modal = page.locator('.g3-modal')
+    await expect(modal).toBeVisible()
+    await expect(modal.locator('.g3-modal__title')).toHaveText('删除确认')
+
+    const confirmButton = modal.locator('.g3-modal__footer button').last()
+    await expect(confirmButton).toHaveText('确定')
+    await confirmButton.click()
+
+    // loading 期间按钮禁用且带 aria-busy
+    await expect(confirmButton).toBeDisabled()
+    await expect(confirmButton).toHaveAttribute('aria-busy', 'true')
+
+    // onConfirm 的 Promise resolve 后自动关闭
+    await expect(modal).toBeHidden({ timeout: 5000 })
+  })
+})
diff --git a/code/g3soft-libs/packages/ui/e2e/form.spec.ts b/code/g3soft-libs/packages/ui/e2e/form.spec.ts
new file mode 100644
index 00000000..1985435b
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/e2e/form.spec.ts
@@ -0,0 +1,113 @@
+import { expect, test } from '@playwright/test'
+
+/**
+ * 表单类组件的真实布局回归。
+ *
+ * 曾经踩过的坑：
+ * - textarea 的 footer（计数 + 拖拽手柄）在文档流里，被挤到框外；
+ * - 日期时间面板上下排列而不是「左日期 / 右时间」；
+ * - 日期面板宽度跟随输入框被拉伸，日历格子间距被撑散；
+ * - 非法日期（2026-02-30）被原生解析静默顺延成 3 月 2 日。
+ */
+
+test.describe('Input / textarea', () => {
+  test('拖拽手柄落在输入框内部右下角（不再被挤到框外）', async ({ page }) => {
+    await page.goto('/')
+    const root = page.locator('[data-testid="textarea-count"]')
+    const box = (await root.boundingBox())!
+    const handle = (await root.locator('.g3-input__resize-handle').boundingBox())!
+
+    expect(handle.x + handle.width).toBeLessThanOrEqual(box.x + box.width + 1)
+    expect(handle.y + handle.height).toBeLessThanOrEqual(box.y + box.height + 1)
+    expect(handle.y).toBeGreaterThan(box.y + box.height / 2)
+  })
+
+  test('字数统计与手柄同处一行，且有可访问语义', async ({ page }) => {
+    await page.goto('/')
+    const root = page.locator('[data-testid="textarea-count"]')
+
+    await expect(root.locator('.g3-input__count')).toHaveText(/\d+ \/ 100/)
+    await expect(root.locator('.g3-input__resize-handle')).toHaveAttribute('role', 'slider')
+    await expect(root.locator('.g3-input__resize-handle')).toHaveAttribute('aria-orientation', 'vertical')
+  })
+
+  test('number 输入实时净化，只保留一个小数点', async ({ page }) => {
+    await page.goto('/')
+    const input = page.locator('[data-testid="input-number"] input')
+
+    await input.fill('12.3.4')
+    await expect(input).toHaveValue('12.34')
+  })
+
+  test('password 可切换明文', async ({ page }) => {
+    await page.goto('/')
+    const root = page.locator('[data-testid="input-password"]')
+
+    await expect(root.locator('input')).toHaveAttribute('type', 'password')
+    await root.locator('.g3-input__password-toggle').click()
+    await expect(root.locator('input')).toHaveAttribute('type', 'text')
+  })
+})
+
+test.describe('DatePicker', () => {
+  test('日期时间面板呈「左日历 / 右时间」，且日历定宽不被拉伸', async ({ page }) => {
+    await page.goto('/')
+    const trigger = page.locator('[data-testid="date-picker"] .g3-date-picker__trigger')
+    const triggerWidth = (await trigger.boundingBox())!.width
+
+    await trigger.click()
+    const panel = page.locator('.g3-date-picker__panel')
+    await expect(panel).toBeVisible()
+
+    const calendar = panel.locator('.g3-calendar__main')
+    const time = panel.locator('.g3-calendar__time')
+    await expect(calendar).toBeVisible()
+    await expect(time).toBeVisible()
+
+    const calendarBox = (await calendar.boundingBox())!
+    const timeBox = (await time.boundingBox())!
+
+    // 日历在左、时间列在右，同一行（纵向重叠）
+    expect(timeBox.x).toBeGreaterThan(calendarBox.x + calendarBox.width - 1)
+    expect(timeBox.y).toBeLessThan(calendarBox.y + calendarBox.height)
+
+    // 日历定宽，面板不跟随输入框拉宽
+    expect(calendarBox.width).toBeLessThan(260)
+    const panelBox = (await panel.boundingBox())!
+    expect(panelBox.width).toBeLessThan(triggerWidth)
+  })
+
+  test('面板内的确定按钮只有点选后才能用', async ({ page }) => {
+    await page.goto('/')
+    await page.locator('[data-testid="date-picker"] .g3-date-picker__trigger').click()
+
+    const confirm = page.locator('.g3-calendar__footer button')
+    await expect(confirm).toBeEnabled()
+  })
+
+  test('非法日期不会被接受（不再静默顺延）', async ({ page }) => {
+    await page.goto('/')
+    const input = page.locator('[data-testid="date-picker"] .g3-date-picker__input')
+
+    await input.click()
+    await input.fill('2026-02-30')
+    await input.press('Enter')
+
+    // 回退到原值，不能变成 2026-03-02
+    await expect(input).not.toHaveValue('2026-03-02')
+    await expect(page.locator('[data-testid="date-picker"]')).toHaveClass(/is-invalid/)
+  })
+})
+
+test.describe('RangePicker', () => {
+  test('区间面板打开且两端都有值', async ({ page }) => {
+    await page.goto('/')
+    const root = page.locator('[data-testid="range-picker"]')
+
+    await expect(root.locator('input').first()).toHaveValue('2026-10-01')
+    await expect(root.locator('input').nth(1)).toHaveValue('2026-10-08')
+
+    await root.locator('.g3-range-picker__trigger').click()
+    await expect(page.locator('.g3-range-picker__panel')).toBeVisible()
+  })
+})
diff --git a/code/g3soft-libs/packages/ui/e2e/layer.spec.ts b/code/g3soft-libs/packages/ui/e2e/layer.spec.ts
new file mode 100644
index 00000000..7b679d6f
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/e2e/layer.spec.ts
@@ -0,0 +1,121 @@
+import { expect, test } from '@playwright/test'
+
+/**
+ * 弹层层级回归 —— 这类问题单测覆盖不到（需要真实层叠上下文与命中测试）。
+ *
+ * 曾经踩过的坑：
+ * 1. 档位顺序写反（popup < modal）→ 弹窗/抽屉内的下拉被遮罩盖住；
+ * 2. 受控打开 / 挂载即展开的浮层根本没分配 z-index；
+ * 3. Drawer 的 wrap 是 fixed 但没 z-index → 整个抽屉被自己的遮罩压住。
+ *
+ * 注意：playground 里有两个「挂载即展开」的常驻 Popover，
+ * 所以定位浮层时要用 :has-text / filter 精确命中，不能直接 `.g3-popover__popup`。
+ */
+
+/** 读取视口内某点最上层的元素类名（判断「谁盖住谁」的唯一可靠方式） */
+async function topElementAt(page: import('@playwright/test').Page, x: number, y: number) {
+  return page.evaluate(
+    ([px, py]) => {
+      const el = document.elementFromPoint(px as number, py as number)
+      if (!el) return null
+      return typeof el.className === 'string' ? el.className : el.tagName
+    },
+    [x, y],
+  )
+}
+
+test.describe('浮层层级', () => {
+  test('挂载即展开的浮层同样有层级，且同档按打开顺序递增', async ({ page }) => {
+    await page.goto('/')
+
+    const popupA = page.locator('.g3-popover__popup', { hasText: '浮层 A' })
+    const popupB = page.locator('.g3-popover__popup', { hasText: '浮层 B' })
+    await expect(popupA).toBeVisible()
+    await expect(popupB).toBeVisible()
+
+    const zA = Number(await popupA.evaluate((el) => (el as HTMLElement).style.zIndex))
+    const zB = Number(await popupB.evaluate((el) => (el as HTMLElement).style.zIndex))
+
+    expect(zA).toBeGreaterThan(3000)
+    expect(zB).toBeGreaterThan(zA)
+  })
+
+  test('抽屉面板不会被自身遮罩盖住，点遮罩仍可关闭', async ({ page }) => {
+    await page.goto('/')
+    await page.getByTestId('open-drawer').click()
+
+    const drawer = page.locator('.g3-drawer')
+    await expect(drawer).toBeVisible()
+    // 等入场动画结束（transform 归零）再做命中测试，否则面板还在视口外
+    await page.waitForTimeout(450)
+
+    const panelBox = (await drawer.boundingBox())!
+    const inside = await topElementAt(
+      page,
+      panelBox.x + panelBox.width / 2,
+      panelBox.y + panelBox.height / 2,
+    )
+    expect(inside).not.toBeNull()
+    expect(inside).toContain('g3-drawer')
+
+    // 遮罩与 wrap 同级（同一实例共用层级）
+    const maskZ = Number(await page.$eval('.g3-drawer__mask', (el) => (el as HTMLElement).style.zIndex))
+    const wrapZ = Number(await page.$eval('.g3-drawer__wrap', (el) => (el as HTMLElement).style.zIndex))
+    expect(wrapZ).toBe(maskZ)
+
+    // 点面板外（遮罩区域）关闭
+    const maskBox = (await page.locator('.g3-drawer__mask').boundingBox())!
+    await page.mouse.click(maskBox.x + 40, maskBox.y + maskBox.height / 2)
+    await expect(drawer).toBeHidden()
+  })
+
+  test('弹窗内的下拉浮层高于遮罩，且可正常点选', async ({ page }) => {
+    await page.goto('/')
+    await page.getByTestId('open-modal').click()
+    await expect(page.locator('.g3-modal')).toBeVisible()
+
+    const select = page.getByTestId('modal-select')
+    await select.locator('.g3-select__trigger').click()
+
+    const popup = page.locator('.g3-popover__popup').filter({ has: page.locator('.g3-select__dropdown') })
+    await expect(popup).toBeVisible()
+
+    const modalZ = Number(await page.$eval('.g3-modal__mask', (el) => (el as HTMLElement).style.zIndex))
+    const popupZ = Number(await popup.evaluate((el) => (el as HTMLElement).style.zIndex))
+    expect(popupZ).toBeGreaterThan(modalZ)
+
+    // 浮层区域最上层必须是选项本体，而不是遮罩
+    const optionBox = (await page.locator('.g3-select__option').first().boundingBox())!
+    const hit = await topElementAt(page, optionBox.x + 10, optionBox.y + optionBox.height / 2)
+    expect(hit).toContain('g3-select__option')
+  })
+
+  test('反馈类提示盖在浮层与弹窗之上', async ({ page }) => {
+    await page.goto('/')
+    await page.getByTestId('open-modal').click()
+    const select = page.getByTestId('modal-select')
+    await select.locator('.g3-select__trigger').click()
+    await expect(
+      page.locator('.g3-popover__popup').filter({ has: page.locator('.g3-select__dropdown') }),
+    ).toBeVisible()
+
+    // 触发按钮此时在弹窗遮罩之后：真实用户点不到它（这正是层级正确的表现），
+    // 所以直接派发 click 到元素上，本用例只验证「提示出现后压在最上层」
+    await page.getByTestId('toast-default').dispatchEvent('click')
+    await expect(page.locator('.g3-message').first()).toBeVisible()
+
+    const messageZ = Number(
+      await page.$eval('.g3-message__container', (el) => (el as HTMLElement).style.zIndex),
+    )
+    const popupZ = Number(
+      await page
+        .locator('.g3-popover__popup')
+        .filter({ has: page.locator('.g3-select__dropdown') })
+        .evaluate((el) => (el as HTMLElement).style.zIndex),
+    )
+    const modalZ = Number(await page.$eval('.g3-modal__mask', (el) => (el as HTMLElement).style.zIndex))
+
+    expect(messageZ).toBeGreaterThan(popupZ)
+    expect(popupZ).toBeGreaterThan(modalZ)
+  })
+})
diff --git a/code/g3soft-libs/packages/ui/e2e/select.spec.ts b/code/g3soft-libs/packages/ui/e2e/select.spec.ts
new file mode 100644
index 00000000..9240b74a
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/e2e/select.spec.ts
@@ -0,0 +1,81 @@
+import { expect, test } from '@playwright/test'
+
+/**
+ * Select 回归。
+ *
+ * 最严重的一次事故：unwrapped 触发器每次渲染都换新的组件对象，
+ * `<component :is>` 判定类型变化 → 卸载重建触发器 DOM → 焦点丢失派发 focusout
+ * → 处理器改状态 → 再重建……自我驱动成死循环，点击一下就把主线程打满。
+ * 所以这里用 MutationObserver 数「DOM 节点增删次数」来锁住「触发器不被重建」。
+ */
+
+test.describe('Select 交互', () => {
+  test('打开下拉不会重建触发器 DOM（死循环回归）', async ({ page }) => {
+    await page.goto('/')
+
+    await page.evaluate(() => {
+      ;(window as unknown as { __mut: number }).__mut = 0
+      new MutationObserver((records) => {
+        const target = window as unknown as { __mut: number }
+        for (const record of records) {
+          target.__mut += record.addedNodes.length + record.removedNodes.length
+        }
+      }).observe(document.body, { childList: true, subtree: true })
+    })
+
+    const trigger = page.locator('[data-testid="select-basic"] .g3-select__trigger')
+    await trigger.click()
+    await expect(page.locator('.g3-select__option').first()).toBeVisible()
+    await page.waitForTimeout(400)
+
+    const mutations = await page.evaluate(() => (window as unknown as { __mut: number }).__mut)
+    // 只有浮层挂载带来的少量节点变化；重建触发器会产生成百上千次
+    expect(mutations).toBeLessThan(20)
+
+    // 焦点应稳定停留在触发器输入框上
+    const focused = await page.evaluate(() => document.activeElement?.className ?? '')
+    expect(focused).toContain('g3-select__input')
+  })
+
+  test('选中选项后回填并关闭', async ({ page }) => {
+    await page.goto('/')
+    const root = page.locator('[data-testid="select-basic"]')
+
+    await root.locator('.g3-select__trigger').click()
+    await page.locator('.g3-select__option').filter({ hasText: '会员' }).click()
+
+    await expect(root.locator('input')).toHaveValue('会员')
+    await expect(page.locator('.g3-select__dropdown')).toHaveCount(0)
+  })
+
+  test('多选以「、」拼接回显，且选中后保持展开', async ({ page }) => {
+    await page.goto('/')
+    const root = page.locator('[data-testid="select-multiple"]')
+
+    await root.locator('.g3-select__trigger').click()
+    await page.locator('.g3-select__option').filter({ hasText: '管理员' }).click()
+    await page.locator('.g3-select__option').filter({ hasText: '会员' }).click()
+
+    await expect(root.locator('input')).toHaveValue('管理员、会员')
+    await expect(page.locator('.g3-select__dropdown')).toBeVisible()
+  })
+
+  test('下拉宽度跟随触发框，且不超过上限', async ({ page }) => {
+    await page.goto('/')
+    const root = page.locator('[data-testid="select-basic"]')
+    const triggerWidth = (await root.locator('.g3-select__trigger').boundingBox())!.width
+
+    await root.locator('.g3-select__trigger').click()
+    // playground 里还有两个常驻 Popover，用内容过滤精确定位本用例的浮层
+    const popup = page.locator('.g3-popover__popup').filter({ has: page.locator('.g3-select__dropdown') })
+    await expect(popup).toBeVisible()
+
+    const popupWidth = (await popup.boundingBox())!.width
+    // 下拉宽度 = max(触发框宽, 内容宽)：触发框更宽时下拉跟着变宽（antd 行为），
+    // 样式里的 max-width 只在触发框较窄、内容很长时起限制作用
+    expect(popupWidth).toBeGreaterThanOrEqual(Math.floor(triggerWidth) - 1)
+
+    const viewport = page.viewportSize()!
+    expect(popupWidth).toBeLessThanOrEqual(viewport.width)
+  })
+})
diff --git a/code/g3soft-libs/packages/ui/e2e/ui-regressions.spec.ts b/code/g3soft-libs/packages/ui/e2e/ui-regressions.spec.ts
new file mode 100644
index 00000000..221b418a
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/e2e/ui-regressions.spec.ts
@@ -0,0 +1,224 @@
+import { expect, test } from '@playwright/test'
+
+/**
+ * 组件细节回归 —— 每一条都对应一个真实报障，之前全部漏测。
+ *
+ * 共同点：它们要么靠布局计算（滑块尺寸、等高、线性位移），要么靠伪类层叠
+ * （:hover 的特异性、相邻边框的 z-index），要么靠 CSS 变量的实际解析结果
+ * （color-mix 里的 var()）。这些在 happy-dom 里量不出来，必须放 E2E。
+ */
+
+test.describe('ButtonGroup', () => {
+  test('横向：hover 的按钮浮到上层，被压住的那条边框仍可见', async ({ page }) => {
+    await page.goto('/')
+    const second = page.getByTestId('btn-group-plain').locator('.g3-button').nth(1)
+    await second.hover()
+
+    // 相邻按钮用 -1px 负边距重叠，不抬 z-index 时后一个按钮的边框会盖住它
+    await expect(second).toHaveCSS('z-index', '1')
+    // 边框色有 0.2s 过渡：必须用会重试的断言，直接 evaluate 会读到过渡中间值
+    await expect(second).toHaveCSS('border-top-color', 'rgb(24, 24, 27)')
+  })
+
+  test('纵向：hover 的按钮同样抬升', async ({ page }) => {
+    await page.goto('/')
+    const second = page.getByTestId('btn-group-vertical').locator('.g3-button').nth(1)
+    await second.hover()
+
+    await expect(second).toHaveCSS('z-index', '1')
+    await expect(second).toHaveCSS('border-top-color', 'rgb(24, 24, 27)')
+  })
+})
+
+test.describe('Segmented', () => {
+  test('选中滑块与选中项同尺寸同位置（滑块曾塌成 0 高，看不出选中）', async ({ page }) => {
+    await page.goto('/')
+    // 必须限定在同一个实例内：页面上有多组 Segmented，跨实例比较会拿到别人的滑块
+    const group = page.locator('.g3-segmented__group').first()
+    const thumb = group.locator('.g3-segmented__thumb')
+    const item = group.locator('.g3-segmented__item.is-selected')
+
+    const t = (await thumb.boundingBox())!
+    const i = (await item.boundingBox())!
+
+    // 滑块尺寸来自 offsetWidth/offsetHeight（整数），实际布局是亚像素，允许 1px 误差
+    for (const [name, a, b] of [
+      ['width', t.width, i.width],
+      ['height', t.height, i.height],
+      ['x', t.x, i.x],
+      ['y', t.y, i.y],
+    ] as const) {
+      expect(Math.abs(a - b), `滑块与选中项的 ${name} 不一致`).toBeLessThanOrEqual(1)
+    }
+    expect(t.height).toBeGreaterThan(0)
+    // 滑块就是选中底色，不能是透明的
+    expect(await thumb.evaluate((el) => getComputedStyle(el).backgroundColor)).toBe(
+      'rgb(255, 255, 255)',
+    )
+  })
+})
+
+test.describe('Pagination', () => {
+  test('hover 当前页仍保持主色填充（曾被通用 hover 覆盖成白底白字）', async ({ page }) => {
+    await page.goto('/')
+    const current = page.locator('.g3-pagination__page.is-page-current')
+    await current.hover()
+
+    await expect(current).toHaveCSS('background-color', 'rgb(24, 24, 27)')
+    await expect(current).toHaveCSS('color', 'rgb(250, 250, 250)')
+  })
+})
+
+test.describe('Tooltip', () => {
+  test('气泡没有描边（投影由 popup 的 drop-shadow 统一施加）', async ({ page }) => {
+    await page.goto('/')
+    await page.getByTestId('tooltip-trigger').hover()
+
+    const content = page.locator('.g3-popover__content').first()
+    await expect(content).toBeVisible()
+    await expect(content).toHaveCSS('border-top-width', '0px')
+    await expect(content).toHaveCSS('border-left-width', '0px')
+  })
+})
+
+test.describe('Tabs 垂直方向', () => {
+  for (const placement of ['left', 'right'] as const) {
+    test(`${placement}：标签栏与内容区之间有竖向分隔线，选中项带侧边指示线与底色`, async ({
+      page,
+    }) => {
+      await page.goto('/')
+      const tabs = page.locator(`.g3-tabs--${placement}`).first()
+      const nav = tabs.locator('.g3-tabs__nav')
+      const active = tabs.locator('.g3-tabs__tab.is-tab-active').first()
+
+      if (placement === 'left') {
+        await expect(nav).toHaveCSS('border-right-width', '1px')
+        await expect(active).toHaveCSS('border-right-width', '2px')
+      } else {
+        await expect(nav).toHaveCSS('border-left-width', '1px')
+        await expect(active).toHaveCSS('border-left-width', '2px')
+      }
+      // 选中项底色不再是 transparent
+      const bg = await active.evaluate((el) => getComputedStyle(el).backgroundColor)
+      expect(bg).not.toBe('rgba(0, 0, 0, 0)')
+    })
+  }
+})
+
+test.describe('Tree', () => {
+  test('点击节点有选中底色（token color-mix 曾解析失败导致背景透明）', async ({ page }) => {
+    await page.goto('/')
+    const node = page.locator('.g3-tree-node', { hasText: '节点一' }).first()
+    await node.click()
+
+    await expect(node).toHaveClass(/is-selected/)
+    const bg = await node.evaluate((el) => getComputedStyle(el).backgroundColor)
+    expect(bg, `选中底色不应为透明：${bg}`).not.toBe('rgba(0, 0, 0, 0)')
+  })
+
+  test('整层都是叶子时不渲染展开箭头占位', async ({ page }) => {
+    await page.goto('/')
+    // 扁平树：两个节点都没有子节点
+    const flatTree = page.locator('.g3-tree').filter({ hasText: '节点一（无子节点）' }).first()
+
+    await expect(flatTree.locator('.g3-tree-node')).toHaveCount(2)
+    await expect(flatTree.locator('.g3-tree-node__switcher')).toHaveCount(0)
+  })
+
+  test('拖拽需要长按武装：直接拖动不会产生落点', async ({ page }) => {
+    await page.goto('/')
+    const draggableTree = page.locator('.g3-tree').filter({ hasText: '节点一（无子节点）' })
+    // 用带 draggable 的那棵树里的第一行
+    const row = page.locator('.g3-tree-node').first()
+    const box = (await row.boundingBox())!
+
+    await page.mouse.move(box.x + 40, box.y + box.height / 2)
+    await page.mouse.down()
+    // 立刻移动（未到 400ms 阈值）：draggable 属性还没武装
+    await page.mouse.move(box.x + 60, box.y + box.height / 2 + 30, { steps: 3 })
+    expect(await row.getAttribute('draggable')).toBeNull()
+    await page.mouse.up()
+    expect(await draggableTree.count()).toBeGreaterThan(0)
+  })
+})
+
+test.describe('DatePicker 时间列', () => {
+  test('时/分/秒三列并排：定宽、列间分隔线、列表与日历等高且可滚动', async ({ page }) => {
+    await page.goto('/')
+    await page.locator('.g3-date-picker__input').first().click()
+
+    const calendar = page.locator('.g3-calendar')
+    await expect(calendar).toBeVisible()
+
+    const cols = calendar.locator('.g3-time-select__col')
+    await expect(cols).toHaveCount(3)
+    await expect(cols.first()).toHaveCSS('width', '56px')
+    await expect(cols.nth(1)).toHaveCSS('border-left-width', '1px')
+
+    const main = (await calendar.locator('.g3-calendar__main').boundingBox())!
+    const time = (await calendar.locator('.g3-calendar__time').boundingBox())!
+    expect(Math.round(main.height)).toBe(Math.round(time.height))
+
+    const list = calendar.locator('.g3-time-select__list').first()
+    const listBox = (await list.boundingBox())!
+    expect(Math.round(listBox.height)).toBe(Math.round(main.height))
+    expect(
+      await list.evaluate((el) => el.scrollHeight > el.clientHeight),
+      '时间列应当内部滚动而不是撑开面板',
+    ).toBe(true)
+    // 单个选项 28px 高
+    await expect(calendar.locator('.g3-time-select__item').first()).toHaveCSS('height', '28px')
+  })
+
+  test('年 / 月选择面板：3 列 × 4 行，标题显示年份区间，当前年有标记', async ({ page }) => {
+    await page.goto('/')
+    await page.locator('.g3-date-picker__input').first().click()
+
+    await page.locator('.g3-calendar__title-button').first().click()
+
+    const selector = page.locator('.g3-calendar__selector')
+    await expect(selector).toBeVisible()
+    await expect(selector.locator('.g3-calendar__selector-item')).toHaveCount(12)
+    await expect(selector).toHaveCSS('grid-template-columns', /(\d+(\.\d+)?px ){2}/)
+
+    const title = await page.locator('.g3-calendar__title-button').first().textContent()
+    expect(title).toMatch(/\d{4}\s*-\s*\d{4}/)
+    await expect(selector.locator('.g3-calendar__selector-item.is-selected')).toHaveCount(1)
+  })
+})
+
+test.describe('Splitter 拖拽', () => {
+  test('面板宽度随指针线性变化（曾经一拖就跳）', async ({ page }) => {
+    await page.goto('/')
+    const bar = page.locator('.g3-splitter__bar').first()
+    // mouse API 用视口坐标且不会自动滚动，元素不在视口内时拖拽会落空
+    await bar.scrollIntoViewIfNeeded()
+    const box = (await bar.boundingBox())!
+    const widths = () =>
+      page.$$eval('.g3-splitter-panel', (els) =>
+        els.map((el) => Math.round(el.getBoundingClientRect().width)),
+      )
+
+    const before = await widths()
+    const startX = box.x + box.width / 2
+    const y = box.y + box.height / 2
+
+    await page.mouse.move(startX, y)
+    await page.mouse.down()
+
+    const samples: number[][] = []
+    for (const dx of [20, 40, 60]) {
+      await page.mouse.move(startX + dx, y)
+      await page.waitForTimeout(60)
+      samples.push(await widths())
+    }
+    await page.mouse.up()
+
+    // 每移动 20px，左侧面板就该宽 20px（严格 1:1，不是跳到某个值）
+    samples.forEach((sample, index) => {
+      const delta = sample[0] - before[0]
+      expect(delta, `第 ${index + 1} 次移动后左侧宽度增量`).toBeGreaterThanOrEqual((index + 1) * 20 - 2)
+      expect(delta).toBeLessThanOrEqual((index + 1) * 20 + 2)
+    })
+  })
+})
diff --git a/code/g3soft-libs/packages/ui/package.json b/code/g3soft-libs/packages/ui/package.json
index c06c173a..ab208c97 100644
--- a/code/g3soft-libs/packages/ui/package.json
+++ b/code/g3soft-libs/packages/ui/package.json
@@ -21,20 +21,33 @@
   },
   "scripts": {
     "build": "vite build",
-    "prepublishOnly": "publint"
+    "prepublishOnly": "publint",
+    "playground": "vite --config playground/vite.config.ts",
+    "test": "vitest run",
+    "test:unit": "vitest run",
+    "test:watch": "vitest",
+    "test:e2e": "playwright test",
+    "test:e2e:headed": "playwright test --headed",
+    "test:e2e:report": "playwright show-report",
+    "verify": "pnpm build && pnpm test:unit && pnpm test:e2e"
   },
   "peerDependencies": {
     "vue": "^3.5.0"
   },
   "dependencies": {
-    "@g3soft/tokens": "workspace:*"
+    "@g3soft/tokens": "workspace:*",
+    "@lucide/vue": "^1.31.0"
   },
   "devDependencies": {
+    "@playwright/test": "^1.63.0",
     "@vitejs/plugin-vue": "^6.0.0",
+    "@vue/test-utils": "^2.5.1",
+    "happy-dom": "^20.14.5",
     "publint": "latest",
     "sass": "catalog:",
     "vite": "^8.0.0",
     "vite-plugin-dts": "latest",
+    "vitest": "^5.0.3",
     "vue": "catalog:",
     "vue-tsc": "^3.0.0"
   },
diff --git a/code/g3soft-libs/packages/ui/playground/index.html b/code/g3soft-libs/packages/ui/playground/index.html
new file mode 100644
index 00000000..94743e23
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/playground/index.html
@@ -0,0 +1,53 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="utf-8" />
+    <title>G3 组件 playground</title>
+    <style>
+      body {
+        margin: 0;
+        background: #fff;
+        color: #18181b;
+        font-family: system-ui, -apple-system, 'Segoe UI', sans-serif;
+      }
+      .page {
+        max-width: 1120px;
+        margin: 0 auto;
+        padding: 20px;
+      }
+      /* 只作用于页面自己的分区（`.page` 的直接子元素）。
+         不能用裸 `section` / `h2`：Drawer 的面板本体就是 `<section class="g3-drawer">`，
+         元素选择器会连它一起命中（曾把面板撑出 16px 的底部间距、还漏进虚线边框和 padding），
+         表现为「抽屉高度撑不满」。 */
+      .page > section {
+        margin-bottom: 16px;
+        padding: 12px 16px 16px;
+        border: 1px dashed #e5e7eb;
+        border-radius: 8px;
+      }
+      .page > section > h2 {
+        margin: 0 0 12px;
+        color: #52525b;
+        font-size: 15px;
+      }
+      .row {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 12px;
+        align-items: center;
+        margin-bottom: 12px;
+      }
+      .box {
+        display: flex;
+        height: 100%;
+        align-items: center;
+        justify-content: center;
+        background: #fafafa;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/main.ts"></script>
+  </body>
+</html>
diff --git a/code/g3soft-libs/packages/ui/playground/main.ts b/code/g3soft-libs/packages/ui/playground/main.ts
new file mode 100644
index 00000000..f4be49ab
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/playground/main.ts
@@ -0,0 +1,420 @@
+import { createApp, reactive, ref } from 'vue'
+import { Plus, Search, Settings } from '@lucide/vue'
+import {
+  G3Button,
+  G3ButtonGroup,
+  G3ButtonGroupSeparator,
+  G3Checkbox,
+  G3Col,
+  G3DatePicker,
+  G3Drawer,
+  G3Dropdown,
+  G3DropdownItem,
+  G3Form,
+  G3FormGroup,
+  G3FormItem,
+  G3Input,
+  G3Message,
+  G3Modal,
+  G3Notification,
+  G3Pagination,
+  G3Popover,
+  G3Radio,
+  G3RadioGroup,
+  G3RangePicker,
+  G3Row,
+  G3Scrollbar,
+  G3Segmented,
+  G3Select,
+  G3Space,
+  G3Spin,
+  G3Splitter,
+  G3SplitterPanel,
+  G3Switch,
+  G3TabPane,
+  G3Tabs,
+  G3Tag,
+  G3TimeSelect,
+  G3Tooltip,
+  G3Tree,
+} from '@g3soft/ui'
+import '@g3soft/tokens'
+
+/**
+ * playground —— 组件在真实浏览器里的落脚点。
+ *
+ * 约定：所有 E2E 与人工手测都通过 `data-testid` 找元素，
+ * 不要依赖文本或层级结构（文案会改、结构会调，testid 保持稳定）。
+ */
+
+const ROLE_OPTIONS = [
+  { label: '管理员', value: 1 },
+  { label: '会员', value: 2 },
+  { label: '访客', value: 3 },
+]
+
+const TREE_DATA = [
+  {
+    key: '1',
+    title: '前端',
+    children: [
+      { key: '1-1', title: 'Vue', children: [{ key: '1-1-1', title: '组合式 API' }] },
+      { key: '1-2', title: 'React' },
+    ],
+  },
+  { key: '2', title: '后端', children: [{ key: '2-1', title: 'Node.js' }] },
+]
+
+const LONG_TEXT = Array.from({ length: 40 }, (_, index) => `第 ${index + 1} 行内容`).join('\n')
+
+const App = {
+  components: {
+    G3Button,
+    G3ButtonGroup,
+    G3ButtonGroupSeparator,
+    G3Checkbox,
+    G3Col,
+    G3DatePicker,
+    G3Drawer,
+    G3Dropdown,
+    G3DropdownItem,
+    G3Form,
+    G3FormGroup,
+    G3FormItem,
+    G3Input,
+    G3Modal,
+    G3Pagination,
+    G3Popover,
+    G3Radio,
+    G3RadioGroup,
+    G3RangePicker,
+    G3Row,
+    G3Scrollbar,
+    G3Segmented,
+    G3Select,
+    G3Space,
+    G3Spin,
+    G3Splitter,
+    G3SplitterPanel,
+    G3Switch,
+    G3TabPane,
+    G3Tabs,
+    G3Tag,
+    G3TimeSelect,
+    G3Tooltip,
+    G3Tree,
+    Plus,
+    Search,
+    Settings,
+  },
+  setup() {
+    const model = reactive({
+      name: '张三',
+      intro: '这是多行文本',
+      role: 1 as number | undefined,
+      city: [] as number[],
+      agree: true,
+      level: 2,
+      gender: 'male',
+      date: '2026-10-08 09:30:00',
+      range: ['2026-10-01', '2026-10-08'] as string[],
+    })
+    const tab = ref('a')
+    // 选项是中文原始值，初始值必须对上，否则没有选中项
+    const seg = ref('日')
+    const time = ref(new Date(2026, 9, 8, 9, 30, 0))
+    const modalOpen = ref(false)
+    const modalConfirmOpen = ref(false)
+    const drawerOpen = ref(false)
+    // 四个方向都要能验：上下面板的宽度必须撑满视口（曾因用 flex 对齐而缩到内容宽）
+    const drawerPlacement = ref<'left' | 'right' | 'top' | 'bottom'>('right')
+    // 挂载即展开的浮层：验证「初始 open」也能拿到 z-index
+    const popoverAOpen = ref(true)
+    const popoverBOpen = ref(true)
+
+    // 扁平树：两个节点都不是父节点，用来验「叶子不该留展开箭头占位」
+    const flatTreeData = [
+      { key: 'flat-1', title: '节点一（无子节点）' },
+      { key: 'flat-2', title: '节点二（无子节点）' },
+    ]
+    const treeMenuItems = [
+      { key: 'add', label: '新增子节点' },
+      { key: 'rename', label: '重命名' },
+      { key: 'delete', label: '删除', danger: true },
+    ]
+
+    function toast(placement?: string) {
+      G3Message.success(`操作成功`, placement ? { placement: placement as never } : undefined)
+    }
+
+    function notify() {
+      G3Notification.info({ title: '定时任务完成', description: '本次共同步 128 条数据。' })
+    }
+
+    function openDrawer(placement: 'left' | 'right' | 'top' | 'bottom') {
+      drawerPlacement.value = placement
+      drawerOpen.value = true
+    }
+
+    function openCommandConfirm() {
+      G3Modal.confirm({
+        title: '删除确认',
+        content: '确定要删除这条记录吗？',
+        onConfirm: () => new Promise<void>((resolve) => setTimeout(resolve, 600)),
+      })
+    }
+
+    return {
+      model,
+      tab,
+      seg,
+      time,
+      modalOpen,
+      modalConfirmOpen,
+      drawerOpen,
+      drawerPlacement,
+      openDrawer,
+      popoverAOpen,
+      popoverBOpen,
+      flatTreeData,
+      treeMenuItems,
+      roleOptions: ROLE_OPTIONS,
+      treeData: TREE_DATA,
+      longText: LONG_TEXT,
+      toast,
+      notify,
+      openCommandConfirm,
+    }
+  },
+  template: `
+  <div class="page">
+    <section id="s-basic">
+      <h2>基础：Button / Tag / Spin / Segmented / Space</h2>
+      <div class="row">
+        <G3Button data-testid="btn-primary">主要</G3Button>
+        <G3Button type="secondary">次要</G3Button>
+        <G3Button type="outline">描边</G3Button>
+        <G3Button type="ghost">幽灵</G3Button>
+        <G3Button type="danger">危险</G3Button>
+        <G3Button type="danger-outline">危险描边</G3Button>
+        <G3Button type="link">链接</G3Button>
+        <G3Button type="icon" aria-label="新增"><Plus /></G3Button>
+        <G3Button size="small">小</G3Button>
+        <G3Button size="large">大</G3Button>
+        <G3Button loading>加载中</G3Button>
+        <G3Button disabled>禁用</G3Button>
+      </div>
+      <div class="row">
+        <G3ButtonGroup data-testid="btn-group">
+          <G3Button type="outline">左</G3Button>
+          <G3ButtonGroupSeparator />
+          <G3Button type="outline">中</G3Button>
+          <G3ButtonGroupSeparator />
+          <G3Button type="outline">右</G3Button>
+        </G3ButtonGroup>
+        <!-- 无分隔线的连续按钮组：相邻边框重叠，hover 时被压住的那条必须可见 -->
+        <G3ButtonGroup data-testid="btn-group-plain">
+          <G3Button type="outline">第一</G3Button>
+          <G3Button type="outline">第二</G3Button>
+          <G3Button type="outline">第三</G3Button>
+        </G3ButtonGroup>
+        <G3ButtonGroup orientation="vertical" data-testid="btn-group-vertical">
+          <G3Button type="outline">上</G3Button>
+          <G3Button type="outline">中</G3Button>
+          <G3Button type="outline">下</G3Button>
+        </G3ButtonGroup>
+        <G3Tag variant="default">default</G3Tag>
+        <G3Tag variant="secondary">secondary</G3Tag>
+        <G3Tag variant="outline">outline</G3Tag>
+        <G3Tag variant="success">success</G3Tag>
+        <G3Tag variant="danger">danger</G3Tag>
+        <G3Tag variant="ghost">ghost</G3Tag>
+        <G3Tag variant="success" closable data-testid="tag-closable">可关闭</G3Tag>
+        <G3Spin data-testid="spin" />
+      </div>
+      <div class="row">
+        <G3Segmented v-model="seg" :options="['日', '周', '月']" data-testid="segmented" />
+        <G3Space :size="8"><G3Tag>间距</G3Tag><G3Tag>测试</G3Tag></G3Space>
+      </div>
+    </section>
+
+    <section id="s-input">
+      <h2>Input（含 textarea 与拖拽手柄）</h2>
+      <div class="row">
+        <G3Input v-model="model.name" data-testid="input-basic" placeholder="默认" style="width: 180px" />
+        <G3Input v-model="model.name" type="password" data-testid="input-password" style="width: 180px" />
+        <G3Input v-model="model.level" type="number" data-testid="input-number" style="width: 120px" />
+        <G3Input v-model="model.name" allow-clear data-testid="input-clear" style="width: 180px" />
+        <G3Input v-model="model.name" show-count :maxlength="20" style="width: 180px" />
+        <G3Input v-model="model.name" status="error" style="width: 160px" />
+        <G3Input v-model="model.name" disabled style="width: 160px" />
+        <G3Input v-model="model.name" placeholder="带前缀">
+          <template #prefix><Search /></template>
+        </G3Input>
+      </div>
+      <div class="row">
+        <G3Input v-model="model.intro" type="textarea" :rows="3" data-testid="textarea-basic" style="width: 300px" />
+        <G3Input
+          v-model="model.intro"
+          type="textarea"
+          :rows="3"
+          show-count
+          :maxlength="100"
+          data-testid="textarea-count"
+          style="width: 300px"
+        />
+      </div>
+    </section>
+
+    <section id="s-form">
+      <h2>Form / Select / Date / Switch / Radio / Checkbox</h2>
+      <G3Form :model="model" :label-width="90" data-testid="form">
+        <G3FormItem name="name" label="名称"><G3Input v-model="model.name" /></G3FormItem>
+        <G3FormItem name="role" label="角色">
+          <G3Select v-model="model.role" :options="roleOptions" data-testid="select-basic" placeholder="请选择" />
+        </G3FormItem>
+        <G3FormItem name="city" label="城市">
+          <G3Select
+            v-model="model.city"
+            :options="roleOptions"
+            multiple
+            data-testid="select-multiple"
+            placeholder="多选"
+          />
+        </G3FormItem>
+        <G3FormItem name="date" label="日期时间">
+          <G3DatePicker v-model="model.date" format="YYYY-MM-DD HH:mm:ss" data-testid="date-picker" />
+        </G3FormItem>
+        <G3FormItem name="range" label="日期区间">
+          <G3RangePicker v-model="model.range" format="YYYY-MM-DD" data-testid="range-picker" />
+        </G3FormItem>
+        <G3FormItem name="intro" label="简介">
+          <G3Input v-model="model.intro" type="textarea" :rows="3" />
+        </G3FormItem>
+        <G3FormItem name="agree" label="开关"><G3Switch v-model="model.agree" data-testid="switch" /></G3FormItem>
+        <G3FormItem name="gender" label="单选">
+          <G3RadioGroup v-model="model.gender">
+            <G3Radio value="male">男</G3Radio>
+            <G3Radio value="female">女</G3Radio>
+          </G3RadioGroup>
+        </G3FormItem>
+        <G3FormItem name="level" label="复选">
+          <G3Checkbox :model-value="true">已选中</G3Checkbox>
+          <G3Checkbox :model-value="false">未选中</G3Checkbox>
+          <G3Checkbox :model-value="false" disabled>禁用</G3Checkbox>
+        </G3FormItem>
+      </G3Form>
+      <G3FormGroup title="分组（可折叠）" style="margin-top: 12px" data-testid="form-group">
+        <G3FormItem name="name" label="组内字段"><G3Input v-model="model.name" /></G3FormItem>
+      </G3FormGroup>
+    </section>
+
+    <section id="s-data">
+      <h2>Tabs / Tree / Pagination / Splitter / Scrollbar / TimeSelect</h2>
+      <div class="row" style="align-items: flex-start">
+        <div style="width: 380px">
+          <!-- data-testid 挂在包裹层：G3Tabs / G3Tree 是多根或 Teleport 根节点，
+               直接挂在组件上会触发 Vue 的 attrs 继承警告（E2E 仍可用它定位） -->
+          <div data-testid="tabs">
+            <G3Tabs v-model="tab">
+              <G3TabPane tab-key="a" label="标签一">标签一的内容</G3TabPane>
+              <G3TabPane tab-key="b" label="标签二">标签二的内容</G3TabPane>
+              <G3TabPane tab-key="c" label="禁用" disabled>不可见</G3TabPane>
+            </G3Tabs>
+          </div>
+          <G3Tabs v-model="tab" placement="left" type="line">
+            <G3TabPane tab-key="a" label="左侧一">左侧标签页内容</G3TabPane>
+            <G3TabPane tab-key="b" label="左侧二">第二个面板</G3TabPane>
+          </G3Tabs>
+          <G3Tabs v-model="tab" placement="right" type="line">
+            <G3TabPane tab-key="a" label="右侧一">右侧标签页内容</G3TabPane>
+            <G3TabPane tab-key="b" label="右侧二">第二个面板</G3TabPane>
+          </G3Tabs>
+        </div>
+        <div style="width: 280px">
+          <div data-testid="tree">
+            <G3Tree :tree-data="treeData" checkable default-expand-all block-node />
+          </div>
+          <!-- 右键菜单：两个节点都不是父节点（验证叶子不占展开位） -->
+          <G3Tree :tree-data="flatTreeData" :context-menu="treeMenuItems" />
+          <!-- 拖拽排序：长按 400ms 才武装，避免手抖 -->
+          <G3Tree :tree-data="treeData" draggable default-expand-all />
+        </div>
+        <div style="width: 240px">
+          <G3TimeSelect v-model="time" data-testid="time-select" />
+        </div>
+      </div>
+      <div style="margin-top: 12px">
+        <G3Pagination :total="126" show-total show-size-changer show-quick-jumper data-testid="pagination" />
+      </div>
+      <div style="margin-top: 12px; height: 120px; display: flex; gap: 12px">
+        <G3Splitter style="height: 120px; flex: 1" data-testid="splitter">
+          <G3SplitterPanel :default-size="'40%'"><div class="box">左</div></G3SplitterPanel>
+          <G3SplitterPanel><div class="box">右</div></G3SplitterPanel>
+        </G3Splitter>
+        <!-- auto-hide=never：滚动条常驻，E2E 才能稳定点到轨道 -->
+        <G3Scrollbar
+          style="height: 120px; width: 220px; border: 1px solid #e5e7eb"
+          auto-hide="never"
+          data-testid="scrollbar"
+        >
+          <pre style="margin: 0; padding: 8px">{{ longText }}</pre>
+        </G3Scrollbar>
+      </div>
+    </section>
+
+    <section id="s-overlay">
+      <h2>Dropdown / Tooltip / Popover（首两个挂载即展开，用于层级回归）</h2>
+      <div class="row">
+        <G3Dropdown data-testid="dropdown">
+          <template #trigger><G3Button type="outline">下拉菜单</G3Button></template>
+          <G3DropdownItem item-key="edit">编辑</G3DropdownItem>
+          <G3DropdownItem item-key="copy">复制</G3DropdownItem>
+          <G3DropdownItem divider />
+          <G3DropdownItem item-key="del" danger>删除</G3DropdownItem>
+        </G3Dropdown>
+        <G3Tooltip content="这是一段提示文案">
+          <G3Button type="outline" data-testid="tooltip-trigger">悬停提示</G3Button>
+        </G3Tooltip>
+        <G3Popover v-model:open="popoverAOpen" trigger="manual" placement="bottom-start" data-testid="popover-a">
+          <template #trigger><G3Button type="outline">初始展开 A</G3Button></template>
+          <template #content><div style="width: 120px">浮层 A</div></template>
+        </G3Popover>
+        <G3Popover v-model:open="popoverBOpen" trigger="manual" placement="bottom-start" data-testid="popover-b">
+          <template #trigger><G3Button type="outline">初始展开 B</G3Button></template>
+          <template #content><div style="width: 120px">浮层 B</div></template>
+        </G3Popover>
+      </div>
+    </section>
+
+    <section id="s-feedback">
+      <h2>Modal / Drawer / Message / Notification</h2>
+      <div class="row">
+        <G3Button data-testid="open-modal" @click="modalOpen = true">打开 Modal</G3Button>
+        <G3Button data-testid="open-drawer" @click="openDrawer('right')">右侧 Drawer</G3Button>
+        <G3Button data-testid="open-drawer-left" @click="openDrawer('left')">左侧 Drawer</G3Button>
+        <G3Button data-testid="open-drawer-top" @click="openDrawer('top')">上方 Drawer</G3Button>
+        <G3Button data-testid="open-drawer-bottom" @click="openDrawer('bottom')">下方 Drawer</G3Button>
+        <G3Button data-testid="open-confirm" @click="openCommandConfirm">Modal.confirm</G3Button>
+        <G3Button data-testid="toast-default" @click="toast()">Message 默认</G3Button>
+        <G3Button data-testid="toast-top-left" @click="toast('top-left')">Message 左上</G3Button>
+        <G3Button data-testid="toast-bottom-right" @click="toast('bottom-right')">Message 右下</G3Button>
+        <G3Button data-testid="notify" @click="notify">Notification</G3Button>
+      </div>
+
+      <G3Modal v-model:open="modalOpen" title="对话框标题" data-testid="modal">
+        <p>第一段内容。</p>
+        <G3Select v-model="model.role" :options="roleOptions" data-testid="modal-select" placeholder="弹窗内选择器" />
+        <p v-for="i in 20" :key="i">第 {{ i }} 段内容，用于验证缩放时内容区是否内部滚动。</p>
+      </G3Modal>
+
+      <G3Drawer v-model:open="drawerOpen" :placement="drawerPlacement" title="抽屉标题" data-testid="drawer">
+        <p>抽屉内容</p>
+        <G3Select v-model="model.role" :options="roleOptions" data-testid="drawer-select" placeholder="抽屉内选择" />
+      </G3Drawer>
+    </section>
+  </div>
+  `,
+}
+
+createApp(App).mount('#app')
diff --git a/code/g3soft-libs/packages/ui/playground/vite.config.ts b/code/g3soft-libs/packages/ui/playground/vite.config.ts
new file mode 100644
index 00000000..45076441
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/playground/vite.config.ts
@@ -0,0 +1,45 @@
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import vue from '@vitejs/plugin-vue'
+import { defineConfig } from 'vite'
+
+/**
+ * 组件 playground —— E2E（Playwright）与人工/ AI 手测共用的宿主页面。
+ *
+ * 只有两个用途：把组件跑在真实浏览器里、给每个可交互元素一个稳定的 data-testid。
+ * 不参与打包（files 只发布 dist），也不影响组件库构建。
+ */
+
+const configScssPath = fileURLToPath(new URL('../../tokens/src/scss/_config.scss', import.meta.url))
+const configScss = readFileSync(configScssPath, 'utf-8')
+
+function readScssDefault(name: string, fallback: string): string {
+  const match = configScss.match(new RegExp(`\\$${name}\\s*:\\s*['"]([^'"]+)['"]\\s*!default`))
+  return match ? match[1] : fallback
+}
+
+export default defineConfig({
+  root: fileURLToPath(new URL('.', import.meta.url)),
+  plugins: [vue()],
+  resolve: {
+    alias: [
+      {
+        find: /^@g3soft\/ui$/,
+        replacement: fileURLToPath(new URL('../src/index.ts', import.meta.url)),
+      },
+      {
+        find: /^@g3soft\/tokens$/,
+        replacement: fileURLToPath(new URL('../../tokens/dist/index.css', import.meta.url)),
+      },
+      { find: /^vue$/, replacement: 'vue/dist/vue.esm-bundler.js' },
+    ],
+  },
+  css: {
+    preprocessorOptions: { scss: { api: 'modern-compiler' } },
+  },
+  define: {
+    __G3_NAMESPACE__: JSON.stringify(readScssDefault('namespace', 'g3')),
+    __G3_STATE_PREFIX__: JSON.stringify(readScssDefault('state-prefix', 'is')),
+  },
+  server: { port: 5200, strictPort: true },
+})
diff --git a/code/g3soft-libs/packages/ui/playwright.config.ts b/code/g3soft-libs/packages/ui/playwright.config.ts
new file mode 100644
index 00000000..3bcaf045
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/playwright.config.ts
@@ -0,0 +1,41 @@
+import { defineConfig, devices } from '@playwright/test'
+
+/**
+ * E2E（L3）—— 只用来覆盖单测跑不了的部分：
+ * 真实布局（弹层定位 / 层叠上下文）、命中测试、拖拽、焦点陷阱、DOM 重建检测。
+ *
+ * 面向工具/AI 的设计：
+ * - `webServer` 自动拉起 playground，不需要手工起服务
+ * - 失败自动留截图 + trace + video，产物在 test-results/
+ * - json reporter 输出 test-results/e2e.json，便于脚本读取与二次分析
+ */
+export default defineConfig({
+  testDir: './e2e',
+  timeout: 30_000,
+  expect: { timeout: 5_000 },
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 1 : 0,
+  reporter: [
+    ['list'],
+    ['json', { outputFile: 'test-results/e2e.json' }],
+  ],
+  use: {
+    baseURL: 'http://localhost:5200',
+    // 失败留证据：截图定位视觉问题、trace 可下载后在浏览器里逐步回放
+    // （刻意不开 video：体积大，且每次启动清理产物容易撞到 IDE 的批量删除守卫）
+    trace: 'retain-on-failure',
+    screenshot: 'only-on-failure',
+    video: 'off',
+    viewport: { width: 1280, height: 900 },
+  },
+  webServer: {
+    command: 'pnpm exec vite --config playground/vite.config.ts',
+    url: 'http://localhost:5200',
+    reuseExistingServer: true,
+    timeout: 90_000,
+    stdout: 'ignore',
+    stderr: 'pipe',
+  },
+  projects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }],
+})
diff --git a/code/g3soft-libs/packages/ui/src/_composables/useComponentDefaults.ts b/code/g3soft-libs/packages/ui/src/_composables/useComponentDefaults.ts
new file mode 100644
index 00000000..2fa3c322
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/_composables/useComponentDefaults.ts
@@ -0,0 +1,34 @@
+import { computed, type ComputedRef } from 'vue'
+import { useConfig } from '../config-provider/context'
+import { getGlobalConfig } from '../_utils/global-config'
+
+/**
+ * 按组件维度读取全局默认 props。
+ *
+ * 回落顺序：**显式传入的 prop > ConfigProvider.componentDefaults[组件名] > withDefaults 内置默认**。
+ * 因此需要支持全局覆盖的 prop，其 `withDefaults` 默认值必须写 `undefined`——
+ * 否则「未传」与「显式传了默认值」无法区分，全局配置永远不生效。
+ *
+ * 组件内用法：
+ * ```ts
+ * const merged = useComponentDefaults('button', props)
+ * // 模板里一律读 merged.value.xxx
+ * ```
+ */
+export function useComponentDefaults<T extends Record<string, unknown>>(
+  componentName: string,
+  props: T,
+): ComputedRef<T> {
+  const config = useConfig()
+  return computed(() => {
+    const defaults =
+      config?.componentDefaults.value?.[componentName] ??
+      getGlobalConfig().componentDefaults?.[componentName]
+    if (!defaults) return props
+    const merged: Record<string, unknown> = { ...props }
+    for (const [key, value] of Object.entries(defaults)) {
+      if (merged[key] === undefined) merged[key] = value
+    }
+    return merged as T
+  })
+}
diff --git a/code/g3soft-libs/packages/ui/src/_composables/useFloating.ts b/code/g3soft-libs/packages/ui/src/_composables/useFloating.ts
new file mode 100644
index 00000000..dc151d33
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/_composables/useFloating.ts
@@ -0,0 +1,162 @@
+import {
+  computed,
+  nextTick,
+  onBeforeUnmount,
+  ref,
+  watch,
+  type CSSProperties,
+  type ComputedRef,
+  type Ref,
+} from 'vue'
+import { computePosition, type Placement, type RectLike } from '../_utils/position'
+
+export interface UseFloatingOptions {
+  /** 是否展开 */
+  open: Ref<boolean> | ComputedRef<boolean>
+  /** 期望方位 */
+  placement: () => Placement
+  /** 与触发器的间距 */
+  offset?: () => number
+  /** 浮层宽度是否以触发器宽度为下限 */
+  followTriggerWidth?: () => boolean
+  /** 触发器元素（定位锚点） */
+  triggerRef: Ref<HTMLElement | null>
+  /** 打开状态下的锚点覆盖（如 contextmenu 以指针位置为锚点） */
+  anchor?: () => RectLike | null
+  /** 打开时点击触发器与浮层之外的回调 */
+  onClickOutside?: () => void
+  /** 打开时按 Esc 的回调 */
+  onEscape?: () => void
+}
+
+export interface UseFloatingReturn {
+  /** 浮层元素 */
+  floatingRef: Ref<HTMLElement | null>
+  /** 浮层定位样式（left / top） */
+  floatingStyle: Ref<CSSProperties>
+  /** 翻转 / 位移后实际生效的方位 */
+  resolvedPlacement: Ref<Placement>
+  /** 实际方位的主方向（top / bottom / left / right），供箭头吸附使用 */
+  resolvedBase: ComputedRef<string>
+  /** 立即重算位置 */
+  updatePosition: () => void
+}
+
+/**
+ * 浮层通用能力：定位、跟随重算、点击外部与 Esc 关闭。
+ *
+ * 定位是纯函数（见 _utils/position.ts），这里只负责：取 rect、写 style、
+ * 在打开期间监听 scroll / resize（rAF 合并）与浮层尺寸变化（ResizeObserver）。
+ * Teleport 容器、触发器事件、展开状态由组件层自己管理。
+ */
+export function useFloating(options: UseFloatingOptions): UseFloatingReturn {
+  const floatingRef = ref<HTMLElement | null>(null)
+  const resolvedPlacement = ref<Placement>(options.placement())
+  const floatingStyle = ref<CSSProperties>({})
+
+  let rafId: number | null = null
+  let resizeObserver: ResizeObserver | null = null
+
+  const resolvedBase = computed(() => resolvedPlacement.value.split('-')[0])
+
+  function updatePosition(): void {
+    const trigger = options.triggerRef.value
+    const floating = floatingRef.value
+    if (!trigger || !floating) return
+    // 跟随触发器宽度：只作为浮层宽度下限（min-width），内容更宽时按内容撑开。
+    // 直接写 DOM 而不经过 :style 绑定，紧随其后的 offsetWidth 才能读到下限生效后的真实宽度；
+    // 值没变就不写，避免在下方的 ResizeObserver 回调里反复触发样式重算。
+    const minWidth = options.followTriggerWidth?.() === true ? `${trigger.offsetWidth}px` : ''
+    if (floating.style.minWidth !== minWidth) floating.style.minWidth = minWidth
+    const anchor = options.anchor?.() ?? null
+    const triggerRect = anchor ?? trigger.getBoundingClientRect()
+    const { x, y, placement } = computePosition({
+      placement: options.placement(),
+      triggerRect,
+      floatSize: { width: floating.offsetWidth, height: floating.offsetHeight },
+      offset: options.offset?.() ?? 0,
+    })
+    resolvedPlacement.value = placement
+    floatingStyle.value = { left: `${x}px`, top: `${y}px` }
+  }
+
+  /** 滚动 / 缩放跟随：rAF 合并高频触发，避免 layout thrashing。 */
+  function scheduleUpdate(): void {
+    if (!options.open.value || rafId !== null) return
+    rafId = requestAnimationFrame(() => {
+      rafId = null
+      updatePosition()
+    })
+  }
+
+  function cancelFrame(): void {
+    if (rafId === null) return
+    cancelAnimationFrame(rafId)
+    rafId = null
+  }
+
+  function startResizeObserver(): void {
+    if (typeof ResizeObserver === 'undefined' || !floatingRef.value) return
+    resizeObserver?.disconnect()
+    resizeObserver = new ResizeObserver(scheduleUpdate)
+    resizeObserver.observe(floatingRef.value)
+  }
+
+  function stopResizeObserver(): void {
+    resizeObserver?.disconnect()
+    resizeObserver = null
+  }
+
+  function onDocumentPointerDown(event: PointerEvent): void {
+    if (!options.open.value) return
+    const target = event.target as Node
+    const inTrigger = options.triggerRef.value?.contains(target) === true
+    const inFloating = floatingRef.value?.contains(target) === true
+    if (!inTrigger && !inFloating) options.onClickOutside?.()
+  }
+
+  function onDocumentKeydown(event: KeyboardEvent): void {
+    if (event.key === 'Escape' && options.open.value) options.onEscape?.()
+  }
+
+  function bindGlobal(): void {
+    document.addEventListener('pointerdown', onDocumentPointerDown, true)
+    document.addEventListener('keydown', onDocumentKeydown)
+    window.addEventListener('resize', scheduleUpdate)
+    window.addEventListener('scroll', scheduleUpdate, true)
+  }
+
+  function unbindGlobal(): void {
+    document.removeEventListener('pointerdown', onDocumentPointerDown, true)
+    document.removeEventListener('keydown', onDocumentKeydown)
+    window.removeEventListener('resize', scheduleUpdate)
+    window.removeEventListener('scroll', scheduleUpdate, true)
+  }
+
+  watch(
+    options.open,
+    (value) => {
+      if (value) {
+        bindGlobal()
+        nextTick(() => {
+          if (!options.open.value) return
+          updatePosition()
+          startResizeObserver()
+        })
+      } else {
+        unbindGlobal()
+        cancelFrame()
+        stopResizeObserver()
+      }
+    },
+    { immediate: true },
+  )
+
+  onBeforeUnmount(() => {
+    unbindGlobal()
+    cancelFrame()
+    stopResizeObserver()
+  })
+
+  return { floatingRef, floatingStyle, resolvedPlacement, resolvedBase, updatePosition }
+}
diff --git a/code/g3soft-libs/packages/ui/src/_composables/usePopupContainer.ts b/code/g3soft-libs/packages/ui/src/_composables/usePopupContainer.ts
new file mode 100644
index 00000000..53916fb8
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/_composables/usePopupContainer.ts
@@ -0,0 +1,35 @@
+import { computed, type ComputedRef } from 'vue'
+import { useConfig } from '../config-provider/context'
+import { getGlobalConfig, type PopupContainer } from '../_utils/global-config'
+
+/**
+ * 解析弹层挂载容器。
+ *
+ * 优先级：组件 prop > ConfigProvider.popupContainer > 全局单例（G3UI.config） > body。
+ * 返回函数或 null 时一律回落到上一级，最终保证能拿到一个可用的容器。
+ */
+export function resolvePopupContainer(container?: PopupContainer | null): string | HTMLElement {
+  const value = typeof container === 'function' ? container() : container
+  if (value instanceof HTMLElement) return value
+  if (typeof value === 'string' && value) return value
+  const fallback = getGlobalConfig().popupContainer
+  const resolved = typeof fallback === 'function' ? fallback() : fallback
+  if (resolved instanceof HTMLElement) return resolved
+  if (typeof resolved === 'string' && resolved) return resolved
+  return 'body'
+}
+
+/**
+ * 组件内使用的容器解析：读 ConfigProvider 下发的默认值，允许组件用 getter 覆盖。
+ * Teleport 的 to 需要非空值，故返回值永远是字符串或元素。
+ */
+export function usePopupContainer(
+  override?: () => PopupContainer | undefined,
+): ComputedRef<string | HTMLElement> {
+  const config = useConfig()
+  return computed(() => {
+    const own = override?.()
+    if (own) return resolvePopupContainer(own)
+    return resolvePopupContainer(config?.popupContainer.value)
+  })
+}
diff --git a/code/g3soft-libs/packages/ui/src/_composables/useUnwrappedTrigger.ts b/code/g3soft-libs/packages/ui/src/_composables/useUnwrappedTrigger.ts
new file mode 100644
index 00000000..1e252fc4
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/_composables/useUnwrappedTrigger.ts
@@ -0,0 +1,108 @@
+import {
+  Comment,
+  Fragment,
+  cloneVNode,
+  computed,
+  nextTick,
+  type Component,
+  type ComputedRef,
+  type Ref,
+  type Slots,
+  type VNode,
+} from 'vue'
+
+/**
+ * 零包裹触发器（unwrapped）的注入实现。
+ *
+ * Popover / Dropdown / Tooltip 需要「不给用户内容加一层 span」时使用本 composable，
+ * 把事件处理器直接注入用户插槽产出的单根 vnode，并用指令把其真实 DOM 同步到
+ * triggerEl（供定位锚点、点击外部判定、宽度测量三处复用）。
+ *
+ * 三个必须遵守的陷阱（已踩过）：
+ * 1. `<slot name="trigger"><slot /></slot>` 经 renderSlot 会产出多层 Fragment，
+ *    必须循环解包到真实元素 / 组件，否则 vnode.type === Symbol(Fragment) 直接放弃注入。
+ * 2. 注入后的 vnode 必须交给 render-function 组件渲染，<component :is="vnode"> 会丢失
+ *    on* 监听与 dirs；且返回值必须是 cloneVNode 的原始结果（保留 __v_isVNode 等内部标记），
+ *    只能在其上追加 dirs，不能用对象展开另造一个对象。
+ * 3. 这个 render-function 组件的**对象引用必须恒定**（见 InjectedTrigger 定义处的注释）。
+ *    每次求值返回新对象会让 `<component :is>` 判为类型变化 → 卸载重建触发器 DOM →
+ *    focus/blur 与状态更新互相驱动成死循环，把主线程打满。
+ */
+export interface UseUnwrappedTriggerOptions {
+  /** 是否启用零包裹模式 */
+  enabled: () => boolean
+  /** 组件插槽 */
+  slots: Slots
+  /** 触发器元素出口 */
+  triggerEl: Ref<HTMLElement | null>
+  /** 当前是否展开（用于重渲染后补定位） */
+  isOpen: () => boolean
+  /** 待注入的事件处理器，键为 DOM 事件名（click / contextmenu / mouseenter …） */
+  handlers: Record<string, (event: Event) => void>
+  /** 重渲染后补一次定位 */
+  onAttach?: () => void
+}
+
+export interface UseUnwrappedTriggerReturn {
+  /** 注入完成的触发器 vnode，null 表示需要回退到包裹层 */
+  injectedTrigger: ComputedRef<VNode | null>
+  /** 交给 `<component :is>` 的渲染组件（**引用恒定**，见下方实现注释） */
+  InjectedTrigger: Component
+}
+
+export function useUnwrappedTrigger(
+  options: UseUnwrappedTriggerOptions,
+): UseUnwrappedTriggerReturn {
+  const triggerRefDirective = {
+    mounted: (el: HTMLElement) => {
+      options.triggerEl.value = el
+      // 受控打开 / contextmenu 已打开后重渲染的场景补一次定位
+      if (options.isOpen()) nextTick(() => options.onAttach?.())
+    },
+    updated: (el: HTMLElement) => {
+      options.triggerEl.value = el
+    },
+    unmounted: (el: HTMLElement) => {
+      if (options.triggerEl.value === el) options.triggerEl.value = null
+    },
+  }
+
+  const injectedTrigger = computed<VNode | null>(() => {
+    if (!options.enabled()) return null
+    const nodes = options.slots.trigger?.() ?? []
+    const real = nodes.filter((node: VNode) => node.type !== Comment)
+    if (real.length !== 1) return null
+    let vnode: VNode = real[0]
+    // Fragment 单子节点解包：嵌套 slot（<slot name="trigger"><slot /></slot>）会产出多层 Fragment
+    while (vnode.type === Fragment) {
+      const children = Array.isArray(vnode.children) ? (vnode.children as VNode[]) : []
+      const fragReal = children.filter((node) => node.type !== Comment)
+      if (fragReal.length !== 1) return null
+      vnode = fragReal[0]
+    }
+    // 文本 / 注释等 symbol 类型 vnode 无法承载事件与指令，回退包裹层
+    if (typeof vnode.type === 'symbol') return null
+    const injected = cloneVNode(vnode, options.handlers, true)
+    // Vue 3 的 vnode 指令字段名是 dirs（不是 directives），拼错会被静默忽略。
+    // 这里构造的是渲染器直接消费的 binding 对象，不属于公开类型，故做一次断言。
+    injected.dirs = [...(vnode.dirs || []), { dir: triggerRefDirective }] as typeof injected.dirs
+    return injected
+  })
+
+  /**
+   * 渲染注入后触发器的组件。
+   *
+   * ⚠️ 这里**必须**是恒定的对象引用，不能写成 computed 里返回 `{ render: () => vnode }`：
+   * computed 每次求值都会产出新的组件对象，`<component :is>` 在 patch 时按对象引用比较，
+   * 判定为「类型变了」就会卸载旧组件、挂载新组件 —— 触发器的真实 DOM（常见是 `<input>`）
+   * 随之被销毁重建。焦点一丢就派发 focusout，处理器又改状态导致下一次重建，于是
+   * 「重建 → 失焦 → 改状态 → 重建」自己把自己转起来，主线程被打满（表现是点击后整机卡死）。
+   * 类型保持恒定、内容由 render 内部读取 computed，DOM 才会被正常 patch 复用。
+   */
+  const InjectedTrigger: Component = {
+    name: 'G3UnwrappedTrigger',
+    render: () => injectedTrigger.value,
+  }
+
+  return { injectedTrigger, InjectedTrigger }
+}
diff --git a/code/g3soft-libs/packages/ui/src/_utils/drag.ts b/code/g3soft-libs/packages/ui/src/_utils/drag.ts
new file mode 100644
index 00000000..0de973ba
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/_utils/drag.ts
@@ -0,0 +1,207 @@
+/**
+ * 弹层拖拽 / 缩放辅助（基于 Pointer Events，跨鼠标 / 触屏统一）。
+ *
+ * - bindDrag：让面板跟随手柄移动（如 Modal 标题栏），拖拽期间抑制文本选中
+ * - bindResize：拖动手柄调整面板宽高（如四周缩放手柄），带最小 / 最大尺寸约束
+ *
+ * 均为纯 DOM 辅助：接收元素参数，不依赖组件实例。
+ * 拖拽 / 缩放通过修改面板的 transform / 回调尺寸完成，不改变文档流布局。
+ */
+
+function releaseUserSelect(): void {
+  document.body.style.userSelect = ''
+  document.body.style.webkitUserSelect = ''
+}
+
+export interface DragHandle {
+  /** 复位面板到初始位置并结束进行中的拖拽 */
+  reset: () => void
+  /** 解绑全部监听，面板销毁前调用 */
+  destroy: () => void
+}
+
+export interface BindDragOptions {
+  /** 是否约束在视口内 */
+  constrain?: boolean
+  /** 面板至少保留在视口内的像素数 */
+  minVisible?: number
+}
+
+/** 移动拖拽：以 handle 拖动 panel，位移写在 panel.style.transform 上。 */
+export function bindDrag(
+  panel: HTMLElement | null,
+  handle: HTMLElement | null,
+  options: BindDragOptions = {},
+): DragHandle {
+  const { constrain = true, minVisible = 40 } = options
+  if (!panel || !handle) return { reset: () => {}, destroy: () => {} }
+
+  let offsetX = 0
+  let offsetY = 0
+  let startX = 0
+  let startY = 0
+  let startOffsetX = 0
+  let startOffsetY = 0
+  let base: { left: number; top: number; width: number; height: number } | null = null
+  let dragging = false
+
+  function onPointerDown(event: PointerEvent) {
+    if (event.button !== 0) return
+    // 手柄内的交互元素（按钮 / 链接 / 表单控件）不触发拖拽
+    if ((event.target as HTMLElement).closest('button, a, input, textarea, select, [data-no-drag]')) {
+      return
+    }
+
+    dragging = true
+    startX = event.clientX
+    startY = event.clientY
+    startOffsetX = offsetX
+    startOffsetY = offsetY
+    const rect = panel!.getBoundingClientRect()
+    base = { left: rect.left, top: rect.top, width: rect.width, height: rect.height }
+    handle!.setPointerCapture(event.pointerId)
+    event.preventDefault()
+    document.body.style.userSelect = 'none'
+    document.body.style.webkitUserSelect = 'none'
+  }
+
+  function onPointerMove(event: PointerEvent) {
+    if (!dragging || !base) return
+    let x = startOffsetX + (event.clientX - startX)
+    let y = startOffsetY + (event.clientY - startY)
+    if (constrain) {
+      // 面板最终位置 = 拖动起点 rect + 累计偏移，限制其至少保留 minVisible 在视口内
+      const minLeft = minVisible - base.left
+      const maxLeft = window.innerWidth - base.width - minVisible - base.left
+      const minTop = minVisible - base.top
+      const maxTop = window.innerHeight - base.height - minVisible - base.top
+      // 面板大于视口时可自由移动该轴，不做反向约束
+      if (minLeft <= maxLeft) x = Math.min(Math.max(x, minLeft), maxLeft)
+      if (minTop <= maxTop) y = Math.min(Math.max(y, minTop), maxTop)
+    }
+    offsetX = x
+    offsetY = y
+    panel!.style.transform = `translate3d(${x}px, ${y}px, 0)`
+  }
+
+  function onPointerEnd() {
+    if (!dragging) return
+    dragging = false
+    releaseUserSelect()
+  }
+
+  handle.addEventListener('pointerdown', onPointerDown)
+  handle.addEventListener('pointermove', onPointerMove)
+  handle.addEventListener('pointerup', onPointerEnd)
+  handle.addEventListener('pointercancel', onPointerEnd)
+
+  return {
+    reset() {
+      offsetX = 0
+      offsetY = 0
+      dragging = false
+      panel.style.transform = ''
+      releaseUserSelect()
+    },
+    destroy() {
+      dragging = false
+      releaseUserSelect()
+      handle.removeEventListener('pointerdown', onPointerDown)
+      handle.removeEventListener('pointermove', onPointerMove)
+      handle.removeEventListener('pointerup', onPointerEnd)
+      handle.removeEventListener('pointercancel', onPointerEnd)
+    },
+  }
+}
+
+export interface ResizeHandle {
+  /** 解绑全部监听，面板销毁前调用 */
+  destroy: () => void
+}
+
+export interface BindResizeOptions {
+  /** 拖拽方向：e 右 / w 左 / s 下 / n 上，可组合如 'se' */
+  direction?: string
+  minWidth?: number
+  minHeight?: number
+  maxWidth?: number
+  maxHeight?: number
+  /** 尺寸变化回调 */
+  onResize?: (size: { width: number; height: number }) => void
+}
+
+/** 尺寸缩放拖拽：拖动手柄按方向增减面板宽高，结果通过 onResize 交给调用方。 */
+export function bindResize(
+  panel: HTMLElement | null,
+  handle: HTMLElement | null,
+  options: BindResizeOptions = {},
+): ResizeHandle {
+  const {
+    direction = 'se',
+    minWidth = 200,
+    minHeight = 120,
+    maxWidth = typeof window === 'undefined' ? 0 : window.innerWidth,
+    maxHeight = typeof window === 'undefined' ? 0 : window.innerHeight,
+    onResize = () => {},
+  } = options
+  if (!panel || !handle) return { destroy: () => {} }
+
+  let startX = 0
+  let startY = 0
+  let base: { width: number; height: number } | null = null
+  let dragging = false
+
+  function onPointerDown(event: PointerEvent) {
+    if (event.button !== 0) return
+    dragging = true
+    startX = event.clientX
+    startY = event.clientY
+    const rect = panel!.getBoundingClientRect()
+    base = { width: rect.width, height: rect.height }
+    // 拖拽中标记：供样式在拖拽期间保持手柄高亮
+    handle!.classList.add('is-resizing')
+    handle!.setPointerCapture(event.pointerId)
+    event.preventDefault()
+    document.body.style.userSelect = 'none'
+    document.body.style.webkitUserSelect = 'none'
+  }
+
+  function onPointerMove(event: PointerEvent) {
+    if (!dragging || !base) return
+    const dx = event.clientX - startX
+    const dy = event.clientY - startY
+    let width = base.width
+    let height = base.height
+    if (direction.includes('e')) width = base.width + dx
+    if (direction.includes('w')) width = base.width - dx
+    if (direction.includes('s')) height = base.height + dy
+    if (direction.includes('n')) height = base.height - dy
+    width = Math.min(Math.max(width, minWidth), maxWidth)
+    height = Math.min(Math.max(height, minHeight), maxHeight)
+    onResize({ width: Math.round(width), height: Math.round(height) })
+  }
+
+  function onPointerEnd() {
+    if (!dragging) return
+    dragging = false
+    handle!.classList.remove('is-resizing')
+    releaseUserSelect()
+  }
+
+  handle.addEventListener('pointerdown', onPointerDown)
+  handle.addEventListener('pointermove', onPointerMove)
+  handle.addEventListener('pointerup', onPointerEnd)
+  handle.addEventListener('pointercancel', onPointerEnd)
+
+  return {
+    destroy() {
+      dragging = false
+      handle.classList.remove('is-resizing')
+      releaseUserSelect()
+      handle.removeEventListener('pointerdown', onPointerDown)
+      handle.removeEventListener('pointermove', onPointerMove)
+      handle.removeEventListener('pointerup', onPointerEnd)
+      handle.removeEventListener('pointercancel', onPointerEnd)
+    },
+  }
+}
diff --git a/code/g3soft-libs/packages/ui/src/_utils/focus.ts b/code/g3soft-libs/packages/ui/src/_utils/focus.ts
new file mode 100644
index 00000000..cc96b77b
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/_utils/focus.ts
@@ -0,0 +1,50 @@
+/**
+ * 弹层焦点管理辅助函数。
+ * 用于 Modal / Drawer 等对话框：打开时聚焦容器、Tab 键循环、关闭后还原焦点。
+ * 纯 DOM 辅助函数，不读取组件状态。
+ */
+
+/** 可聚焦元素选择器：排除 disabled 与 tabindex=-1（隐藏元素靠 getClientRects 过滤）。 */
+const FOCUSABLE_SELECTOR = [
+  'a[href]',
+  'button:not([disabled])',
+  'input:not([disabled])',
+  'select:not([disabled])',
+  'textarea:not([disabled])',
+  '[tabindex]:not([tabindex="-1"])',
+].join(',')
+
+/** 获取容器内当前可聚焦的元素（可见且未禁用）。 */
+export function getFocusable(container: HTMLElement): HTMLElement[] {
+  return Array.from(container.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR)).filter(
+    (el) => el.getClientRects().length > 0,
+  )
+}
+
+/** 聚焦容器内第一个可聚焦元素；没有时聚焦容器本身。 */
+export function focusFirst(container: HTMLElement): void {
+  const focusable = getFocusable(container)
+  if (focusable.length > 0) focusable[0].focus()
+  else container.focus()
+}
+
+/** Tab 焦点陷阱：焦点在容器首尾或容器外时循环回弹。在容器自身的 keydown 上调用。 */
+export function trapFocus(event: KeyboardEvent, container: HTMLElement): void {
+  if (event.key !== 'Tab') return
+  const focusable = getFocusable(container)
+  if (focusable.length === 0) {
+    event.preventDefault()
+    container.focus()
+    return
+  }
+  const first = focusable[0]
+  const last = focusable[focusable.length - 1]
+  const active = document.activeElement
+  if (event.shiftKey && (active === first || !container.contains(active))) {
+    event.preventDefault()
+    last.focus()
+  } else if (!event.shiftKey && (active === last || !container.contains(active))) {
+    event.preventDefault()
+    first.focus()
+  }
+}
diff --git a/code/g3soft-libs/packages/ui/src/_utils/global-config.ts b/code/g3soft-libs/packages/ui/src/_utils/global-config.ts
index 9ca39217..5507712f 100644
--- a/code/g3soft-libs/packages/ui/src/_utils/global-config.ts
+++ b/code/g3soft-libs/packages/ui/src/_utils/global-config.ts
@@ -14,6 +14,8 @@ export interface GlobalConfig {
   zIndex?: number
   locale?: Locale
   popupContainer?: PopupContainer
+  /** 按组件维度的默认 props，如 { button: { size: 'small' } }（ConfigProvider 的组件外兜底） */
+  componentDefaults?: Record<string, Record<string, unknown>>
 }
 
 let config: GlobalConfig = {}
diff --git a/code/g3soft-libs/packages/ui/src/_utils/position.test.ts b/code/g3soft-libs/packages/ui/src/_utils/position.test.ts
new file mode 100644
index 00000000..52223dc5
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/_utils/position.test.ts
@@ -0,0 +1,158 @@
+import { describe, expect, it } from 'vitest'
+import type { Placement, RectLike } from './position'
+import { PLACEMENTS, VIEWPORT_MARGIN, computePosition } from './position'
+
+/** 视口固定为 1000×800，让断言与浏览器尺寸无关 */
+const VIEWPORT = { width: 1000, height: 800 }
+
+/** 视口中部的触发器：left 100 / top 100 / 100×20 */
+function trigger(overrides: Partial<RectLike> = {}): RectLike {
+  return { top: 100, left: 100, right: 200, bottom: 120, width: 100, height: 20, ...overrides }
+}
+
+function compute(placement: Placement, options: {
+  rect?: RectLike
+  floatSize?: { width: number; height: number }
+  offset?: number
+} = {}) {
+  return computePosition({
+    placement,
+    triggerRect: options.rect ?? trigger(),
+    floatSize: options.floatSize ?? { width: 120, height: 60 },
+    offset: options.offset ?? 0,
+    viewport: VIEWPORT,
+  })
+}
+
+describe('常量', () => {
+  it('12 个方位、视口安全边距 8px', () => {
+    expect(PLACEMENTS).toHaveLength(12)
+    expect(new Set(PLACEMENTS).size).toBe(12)
+    expect(VIEWPORT_MARGIN).toBe(8)
+  })
+})
+
+describe('computePosition 基础摆放', () => {
+  it('bottom 系列：贴着触发器下沿，三种对齐方式', () => {
+    expect(compute('bottom-start', { offset: 8 })).toMatchObject({ x: 100, y: 128 })
+    expect(compute('bottom-end', { offset: 8 })).toMatchObject({ x: 80, y: 128 })
+    expect(compute('bottom', { offset: 8 })).toMatchObject({ x: 90, y: 128 })
+  })
+
+  it('top 系列：贴着触发器上沿', () => {
+    expect(compute('top-start', { offset: 8 })).toMatchObject({ x: 100, y: 32 })
+    expect(compute('top-end', { offset: 8 })).toMatchObject({ x: 80, y: 32 })
+  })
+
+  it('right 系列：水平贴合右侧，垂直按对齐', () => {
+    expect(compute('right-start', { offset: 8 })).toMatchObject({ x: 208, y: 100 })
+  })
+
+  it('left 系列：左边距充足时贴左侧', () => {
+    const rect = trigger({ left: 300, right: 400 })
+    expect(compute('left-start', { rect, offset: 8 })).toMatchObject({
+      x: 172,
+      y: 100,
+      placement: 'left-start',
+    })
+  })
+
+  it('左边距不足时翻转到右侧', () => {
+    const result = compute('left-start', { offset: 8 })
+    expect(result.placement).toBe('right-start')
+    expect(result.x).toBe(208)
+  })
+
+  it('未翻转时返回期望方位', () => {
+    expect(compute('bottom-start').placement).toBe('bottom-start')
+    expect(compute('top-end').placement).toBe('top-end')
+  })
+})
+
+describe('computePosition 翻转（flip）', () => {
+  it('下方放不下时翻到上方', () => {
+    const result = compute('bottom-start', {
+      rect: trigger({ top: 700, bottom: 720 }),
+      floatSize: { width: 120, height: 200 },
+      offset: 0,
+    })
+    expect(result.placement).toBe('top-start')
+    // 贴触发器上沿：rect.top 700 - 浮层高 200 - offset 0
+    expect(result.y).toBe(500)
+  })
+
+  it('上方放不下时翻到下方', () => {
+    const result = compute('top-start', {
+      rect: trigger({ top: 20, bottom: 40 }),
+      floatSize: { width: 120, height: 200 },
+    })
+    expect(result.placement).toBe('bottom-start')
+    expect(result.y).toBe(40)
+  })
+
+  it('翻转后依然放不下时保留期望方位，交由 shift 钳制', () => {
+    const result = compute('bottom-start', {
+      rect: trigger({ top: 300, bottom: 320 }),
+      floatSize: { width: 120, height: 900 },
+    })
+    expect(result.placement).toBe('bottom-start')
+    expect(result.y).toBe(8)
+  })
+
+  it('翻转保留对齐方式', () => {
+    const result = compute('bottom-end', {
+      rect: trigger({ top: 700, bottom: 720 }),
+      floatSize: { width: 120, height: 200 },
+    })
+    expect(result.placement).toBe('top-end')
+  })
+})
+
+describe('computePosition 视口钳制（shift）', () => {
+  it('右侧越界时回推到安全边距内', () => {
+    const result = compute('bottom-start', {
+      rect: trigger({ left: 950, right: 1050 }),
+      floatSize: { width: 200, height: 60 },
+    })
+    expect(result.x).toBe(VIEWPORT.width - 200 - VIEWPORT_MARGIN)
+  })
+
+  it('左侧越界时拉到安全边距', () => {
+    const result = compute('bottom-end', {
+      rect: trigger({ left: 0, right: 40 }),
+      floatSize: { width: 200, height: 60 },
+    })
+    expect(result.x).toBe(VIEWPORT_MARGIN)
+  })
+
+  it('浮层比视口还大时钳到安全边距，不出现负值', () => {
+    const result = compute('bottom-start', { floatSize: { width: 2000, height: 60 } })
+    expect(result.x).toBe(VIEWPORT_MARGIN)
+    expect(result.x).toBeGreaterThanOrEqual(0)
+  })
+
+  it('上下越界时同样钳制', () => {
+    const result = compute('bottom-start', {
+      rect: trigger({ top: 790, bottom: 799 }),
+      floatSize: { width: 120, height: 100 },
+    })
+    expect(result.y).toBeLessThanOrEqual(VIEWPORT.height - 100 - VIEWPORT_MARGIN)
+    expect(result.y).toBeGreaterThanOrEqual(VIEWPORT_MARGIN)
+  })
+})
+
+describe('computePosition 纯函数性质', () => {
+  it('不修改传入的 rect / floatSize', () => {
+    const rect = trigger()
+    const floatSize = { width: 120, height: 60 }
+    computePosition({ placement: 'bottom-start', triggerRect: rect, floatSize, viewport: VIEWPORT })
+    expect(rect).toEqual(trigger())
+    expect(floatSize).toEqual({ width: 120, height: 60 })
+  })
+
+  it('同一输入必得同一输出', () => {
+    const first = compute('bottom-start', { offset: 12 })
+    const second = compute('bottom-start', { offset: 12 })
+    expect(first).toEqual(second)
+  })
+})
diff --git a/code/g3soft-libs/packages/ui/src/_utils/position.ts b/code/g3soft-libs/packages/ui/src/_utils/position.ts
new file mode 100644
index 00000000..1199c403
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/_utils/position.ts
@@ -0,0 +1,173 @@
+/**
+ * 浮层定位纯函数。
+ *
+ * 输入触发器与浮层尺寸、期望方位、偏移量与视口，返回无碰撞的落点坐标。
+ * 纯函数、无副作用，便于单测；组件层只负责取 rect 与写 style。
+ */
+
+/** 浮层主方向。 */
+export type PlacementBase = 'top' | 'bottom' | 'left' | 'right'
+
+/** 对齐方式：start = 与触发器起始边对齐，end = 与结束边对齐，center = 居中。 */
+export type PlacementAlign = 'start' | 'center' | 'end'
+
+/** 12 个可选方位：4 主方向 × 3 对齐。 */
+export type Placement =
+  | 'top'
+  | 'top-start'
+  | 'top-end'
+  | 'bottom'
+  | 'bottom-start'
+  | 'bottom-end'
+  | 'left'
+  | 'left-start'
+  | 'left-end'
+  | 'right'
+  | 'right-start'
+  | 'right-end'
+
+export const PLACEMENTS: Placement[] = [
+  'top',
+  'top-start',
+  'top-end',
+  'bottom',
+  'bottom-start',
+  'bottom-end',
+  'left',
+  'left-start',
+  'left-end',
+  'right',
+  'right-start',
+  'right-end',
+]
+
+/** 视口安全边距（px）。 */
+export const VIEWPORT_MARGIN = 8
+
+/** 主方向相反表（用于 flip）。 */
+const OPPOSITE: Record<PlacementBase, PlacementBase> = {
+  top: 'bottom',
+  bottom: 'top',
+  left: 'right',
+  right: 'left',
+}
+
+export interface RectLike {
+  top: number
+  left: number
+  right: number
+  bottom: number
+  width: number
+  height: number
+}
+
+export interface SizeLike {
+  width: number
+  height: number
+}
+
+export interface ComputePositionOptions {
+  /** 期望方位 */
+  placement: Placement
+  /** 触发器位置（通常来自 getBoundingClientRect） */
+  triggerRect: RectLike
+  /** 浮层尺寸 */
+  floatSize: SizeLike
+  /** 与触发器的间距 */
+  offset?: number
+  /** 视口尺寸，默认取 window 当前尺寸 */
+  viewport?: SizeLike
+}
+
+export interface ComputePositionResult {
+  x: number
+  y: number
+  /** 实际生效的方位（可能因 flip 与期望值不同） */
+  placement: Placement
+}
+
+function parsePlacement(placement: Placement): { base: PlacementBase; alignment: PlacementAlign } {
+  const [base, alignment = 'center'] = placement.split('-') as [PlacementBase, PlacementAlign]
+  return { base, alignment }
+}
+
+function align(
+  alignment: PlacementAlign,
+  start: number,
+  size: number,
+  floatSize: number,
+): number {
+  if (alignment === 'start') return start
+  if (alignment === 'end') return start + size - floatSize
+  return start + (size - floatSize) / 2
+}
+
+/** 按 base + alignment 计算初始坐标。 */
+function place(
+  base: PlacementBase,
+  alignment: PlacementAlign,
+  rect: RectLike,
+  size: SizeLike,
+  offset: number,
+): { x: number; y: number } {
+  let x = 0
+  let y = 0
+  if (base === 'top' || base === 'bottom') {
+    x = align(alignment, rect.left, rect.width, size.width)
+    y = base === 'top' ? rect.top - size.height - offset : rect.bottom + offset
+  } else {
+    y = align(alignment, rect.top, rect.height, size.height)
+    x = base === 'left' ? rect.left - size.width - offset : rect.right + offset
+  }
+  return { x, y }
+}
+
+function overflows(x: number, y: number, size: SizeLike, viewport: SizeLike): boolean {
+  return (
+    x < VIEWPORT_MARGIN ||
+    y < VIEWPORT_MARGIN ||
+    x + size.width > viewport.width - VIEWPORT_MARGIN ||
+    y + size.height > viewport.height - VIEWPORT_MARGIN
+  )
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value))
+}
+
+/** 读取当前视口尺寸。 */
+export function getViewport(): SizeLike {
+  return {
+    width: window.innerWidth,
+    height: window.innerHeight,
+  }
+}
+
+/**
+ * 计算浮层落点：先按期望方位摆放，主轴放不下则翻转，最后 shift 回视口内。
+ * 浮层比视口还大时 shift 失去意义，此时钳制到安全边距内。
+ */
+export function computePosition(options: ComputePositionOptions): ComputePositionResult {
+  const { placement, triggerRect, floatSize, offset = 0, viewport = getViewport() } = options
+  const { base, alignment } = parsePlacement(placement)
+  const initial = place(base, alignment, triggerRect, floatSize, offset)
+  let { x, y } = initial
+
+  let resolvedBase = base
+  if (overflows(x, y, floatSize, viewport)) {
+    const flipped = OPPOSITE[base]
+    const flippedPos = place(flipped, alignment, triggerRect, floatSize, offset)
+    if (!overflows(flippedPos.x, flippedPos.y, floatSize, viewport)) {
+      resolvedBase = flipped
+      x = flippedPos.x
+      y = flippedPos.y
+    }
+  }
+
+  x = clamp(x, VIEWPORT_MARGIN, Math.max(VIEWPORT_MARGIN, viewport.width - floatSize.width - VIEWPORT_MARGIN))
+  y = clamp(y, VIEWPORT_MARGIN, Math.max(VIEWPORT_MARGIN, viewport.height - floatSize.height - VIEWPORT_MARGIN))
+
+  const resolvedPlacement: Placement =
+    alignment === 'center' ? resolvedBase : (`${resolvedBase}-${alignment}` as Placement)
+  return { x, y, placement: resolvedPlacement }
+}
diff --git a/code/g3soft-libs/packages/ui/src/_utils/scroll.ts b/code/g3soft-libs/packages/ui/src/_utils/scroll.ts
new file mode 100644
index 00000000..32c7b867
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/_utils/scroll.ts
@@ -0,0 +1,43 @@
+/**
+ * body 滚动锁。
+ * 弹窗（Modal / Drawer）打开时锁定页面滚动，关闭时恢复。
+ * 引用计数：多个弹窗（含弹窗内的下拉）同时打开时，最后一个关闭才真正恢复滚动。
+ */
+
+let lockCount = 0
+let restoreStyle: { overflow: string; paddingRight: string } | null = null
+
+/**
+ * 锁定 body 滚动。首次锁定时记录原样式并补偿滚动条宽度，避免锁定瞬间内容横向跳动。
+ */
+export function lockScroll(): void {
+  if (typeof document === 'undefined') return
+  if (lockCount === 0) {
+    const body = document.body
+    restoreStyle = {
+      overflow: body.style.overflow,
+      paddingRight: body.style.paddingRight,
+    }
+    const scrollbarWidth = window.innerWidth - document.documentElement.clientWidth
+    if (scrollbarWidth > 0) body.style.paddingRight = `${scrollbarWidth}px`
+    body.style.overflow = 'hidden'
+  }
+  lockCount++
+}
+
+/** 解锁 body 滚动。所有弹窗关闭后恢复原始样式。 */
+export function unlockScroll(): void {
+  if (typeof document === 'undefined') return
+  if (lockCount === 0) return
+  lockCount--
+  if (lockCount === 0 && restoreStyle) {
+    document.body.style.overflow = restoreStyle.overflow
+    document.body.style.paddingRight = restoreStyle.paddingRight
+    restoreStyle = null
+  }
+}
+
+/** 当前锁定层数（调试用）。 */
+export function getScrollLockCount(): number {
+  return lockCount
+}
diff --git a/code/g3soft-libs/packages/ui/src/_utils/z-index.test.ts b/code/g3soft-libs/packages/ui/src/_utils/z-index.test.ts
new file mode 100644
index 00000000..606698d2
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/_utils/z-index.test.ts
@@ -0,0 +1,68 @@
+import { beforeEach, describe, expect, it } from 'vitest'
+import { getBaseZIndex, nextZIndex, releaseZIndex, resetZIndex, setBaseZIndex } from './z-index'
+
+/**
+ * 分层规则是弹层可见性的地基，回归成本极低但踩过坑：
+ * - 档位顺序写反 → 弹窗内的下拉被遮罩盖住（表现为「下拉是空的」）
+ * - 档内回填最小空位 → 先关中间一个再开新的，新浮层反而被旧浮层压住
+ */
+describe('z-index 分层注册表', () => {
+  beforeEach(() => {
+    setBaseZIndex(2000)
+  })
+
+  it('跨档严格递增：modal < popup < feedback', () => {
+    const modal = nextZIndex('modal')
+    const popup = nextZIndex('popup')
+    const feedback = nextZIndex('feedback')
+
+    expect([modal, popup, feedback]).toEqual([3001, 4001, 5001])
+    expect(modal).toBeLessThan(popup)
+    expect(popup).toBeLessThan(feedback)
+  })
+
+  it('档内按打开顺序严格递增', () => {
+    expect([nextZIndex('popup'), nextZIndex('popup'), nextZIndex('popup')]).toEqual([
+      4001, 4002, 4003,
+    ])
+  })
+
+  it('释放中间值后再取，仍高于存活层级（不回填空位）', () => {
+    const first = nextZIndex('popup')
+    const released = nextZIndex('popup')
+    const third = nextZIndex('popup')
+
+    releaseZIndex(released)
+
+    expect(first).toBe(4001)
+    expect(released).toBe(4002)
+    expect(third).toBe(4003)
+    expect(nextZIndex('popup')).toBeGreaterThan(third)
+  })
+
+  it('档内全部释放后回到起点：反复开关不会把层级推高', () => {
+    const values = Array.from({ length: 8 }, () => nextZIndex('popup'))
+    values.forEach((value) => releaseZIndex(value))
+
+    expect(nextZIndex('popup')).toBe(4001)
+  })
+
+  it('setBaseZIndex 平移全部档位并清空占用', () => {
+    nextZIndex('modal')
+    // base 是 modal 档的起点基准：modal = base+1000、popup = base+2000、feedback = base+3000
+    setBaseZIndex(100)
+
+    expect(getBaseZIndex()).toBe(100)
+    expect(nextZIndex('modal')).toBe(1101)
+    expect(nextZIndex('popup')).toBe(2101)
+    expect(nextZIndex('feedback')).toBe(3101)
+  })
+
+  it('resetZIndex 清空占用；释放不存在的层级是安全的', () => {
+    nextZIndex('popup')
+    resetZIndex()
+    expect(nextZIndex('popup')).toBe(4001)
+
+    expect(() => releaseZIndex(999_999)).not.toThrow()
+  })
+})
diff --git a/code/g3soft-libs/packages/ui/src/_utils/z-index.ts b/code/g3soft-libs/packages/ui/src/_utils/z-index.ts
index 26b98d16..3d710e62 100644
--- a/code/g3soft-libs/packages/ui/src/_utils/z-index.ts
+++ b/code/g3soft-libs/packages/ui/src/_utils/z-index.ts
@@ -1,31 +1,98 @@
 /**
- * zIndex 全局注册表。
+ * zIndex 分层注册表。
  *
- * 弹层类组件（Dropdown / Modal / Message …）谁压谁必须统一分配，
- * 禁止组件自己写死 z-index。起点来自 ConfigProvider 的 zIndex（默认 2000）。
+ * 弹层类组件（Popover / Dropdown / Select / Modal / Drawer / Message …）谁压谁必须统一分配，
+ * 禁止组件自己写死 z-index。
+ *
+ * 分三档（相对基准层级的偏移）：
+ *   modal     ← 弹窗：Modal / Drawer
+ *   popup     ← 浮层：Popover / Tooltip / Dropdown / Select / DatePicker 面板
+ *   feedback  ← 反馈：Message / Notification
+ *
+ * 为什么浮层必须高于弹窗：两者都 Teleport 到 body，是兄弟节点，
+ * 弹窗内的下拉若层级更低就会被弹窗面板盖住（表现为「下拉是空的」）。
+ * 因此 popup 档整体位于 modal 档之上，与 fms 的 z-modal 3000 < z-popover 3500 一致。
+ *
+ * 档内取值规则（保证「后打开的一定压住先打开的」）：
+ * - 档内为空：从 +1 起步（层级不会随开合次数一路增长）；
+ * - 档内已有：取当前最大值 +1，因此同屏多个浮层严格按打开顺序递增。
+ *   （若按「最小可用空位」填洞，先关掉中间一个再开新的，新浮层会拿到更小的值，
+ *   出现「后开的反而被先开的盖住」。）
+ * - 关闭时用 releaseZIndex 回收；全部关闭后再打开会回到起点。
+ *
+ * 跨档不保证「后开的更高」：popup 档整体高于 modal 档，所以弹窗里开的下拉
+ * 会浮在之后打开的新弹窗之上。这是分层编号的固有特性（fms 同样如此），
+ * 实践中打开新弹窗的那次点击会先让旧浮层按「点击外部」关闭，不会真的叠加。
+ *
+ * 注意：用 ConfigProvider.popupContainer 把浮层挂到局部容器时，档位只在该容器内
+ * 递增；容器自身的层级需要调用方自己保证（它会与页面其他内容是上下层关系）。
  */
 
+/** 层级档位。 */
+export type ZIndexLayer = 'popup' | 'modal' | 'feedback'
+
+const LAYER_OFFSET: Record<ZIndexLayer, number> = {
+  modal: 1000,
+  popup: 2000,
+  feedback: 3000,
+}
+
+const LAYERS = Object.keys(LAYER_OFFSET) as ZIndexLayer[]
+
+/** 默认基准：modal 从 3001 起、popup 从 4001 起、feedback 从 5001 起。 */
 const DEFAULT_BASE_Z_INDEX = 2000
 
+/**
+ * 基准值 = **modal 档的起点基准**（不是"所有弹层的起点"）：
+ * modal = base + 1000 + 序号，popup = base + 2000 + 序号，feedback = base + 3000 + 序号。
+ * 所以 `ConfigProvider :z-index="100"` 得到的是 modal 1101 / popup 2101 / feedback 3101。
+ */
 let base = DEFAULT_BASE_Z_INDEX
-let current = base
 
-/** 由 ConfigProvider 挂载时设置基准层级。 */
+/** 各档位当前占用的层级值（打开时压入，关闭时回收）。 */
+const live: Record<ZIndexLayer, number[]> = { popup: [], modal: [], feedback: [] }
+
+/** 由 ConfigProvider 挂载 / G3UI.config 时设置基准层级。 */
 export function setBaseZIndex(value: number): void {
   base = value
-  current = value
+  LAYERS.forEach((layer) => {
+    live[layer] = []
+  })
 }
 
 export function getBaseZIndex(): number {
   return base
 }
 
-/** 取下一个可用层级（按序分配）。 */
-export function nextZIndex(): number {
-  return ++current
+/**
+ * 取本档位下一个层级：档内为空时从 +1 起步，否则取档内最大值 +1。
+ * 这样「后打开的一定高于先打开的」，同时层级不会因为反复开关而无上限增长。
+ *
+ * 不传档位时按 popup 处理，兼容早期只弹出层的调用点。
+ */
+export function nextZIndex(layer: ZIndexLayer = 'popup'): number {
+  const offset = LAYER_OFFSET[layer]
+  const list = live[layer]
+  const value = (list.length > 0 ? Math.max(...list) : base + offset) + 1
+  list.push(value)
+  return value
 }
 
-/** 重置到基准层级（用于测试 / 整页卸载）。 */
+/** 回收某个层级（弹层关闭 / 卸载时调用），供后续实例复用。 */
+export function releaseZIndex(value: number): void {
+  for (const layer of LAYERS) {
+    const list = live[layer]
+    const index = list.indexOf(value)
+    if (index !== -1) {
+      list.splice(index, 1)
+      return
+    }
+  }
+}
+
+/** 清空全部档位占用（用于测试 / 整页卸载）。 */
 export function resetZIndex(): void {
-  current = base
+  LAYERS.forEach((layer) => {
+    live[layer] = []
+  })
 }
diff --git a/code/g3soft-libs/packages/ui/src/button-group/ButtonGroup.vue b/code/g3soft-libs/packages/ui/src/button-group/ButtonGroup.vue
new file mode 100644
index 00000000..a0fd2666
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/button-group/ButtonGroup.vue
@@ -0,0 +1,91 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import { useNamespace } from '../_composables/useNamespace'
+import type { ButtonGroupProps } from './types'
+
+/**
+ * 按钮组 —— 把多个 G3Button 贴合排列成一组，中间边框重叠、首尾保留圆角。
+ *
+ * 组内按钮去掉圆角并相互贴合，聚焦时当前按钮浮到上层，避免被相邻按钮边框遮挡。
+ */
+defineOptions({ name: 'G3ButtonGroup' })
+
+const props = withDefaults(defineProps<ButtonGroupProps>(), {
+  orientation: 'horizontal',
+})
+
+const { b, m } = useNamespace('button-group')
+
+const classes = computed(() => [
+  b(),
+  props.orientation === 'vertical' ? m('vertical') : '',
+])
+</script>
+
+<template>
+  <div :class="classes" role="group" data-slot="button-group" :data-orientation="orientation">
+    <slot />
+  </div>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+.#{b('button-group')} {
+  display: inline-flex;
+  flex-direction: row;
+  align-items: stretch;
+
+  /* 内部按钮去圆角并相互贴合（边框重叠 1px，避免双线） */
+  > .#{b('button')} {
+    position: relative;
+    min-height: v('control-height', 32px);
+    border-radius: 0;
+    margin-left: -1px;
+  }
+
+  > .#{b('button')}:first-child {
+    margin-left: 0;
+    border-top-left-radius: v('radius', 6px);
+    border-bottom-left-radius: v('radius', 6px);
+  }
+
+  > .#{b('button')}:last-child {
+    border-top-right-radius: v('radius', 6px);
+    border-bottom-right-radius: v('radius', 6px);
+  }
+
+  /* 悬停 / 聚焦时都要浮到上层：相邻按钮靠 -1px 负边距让边框重叠，
+     同层下后一个按钮的边框会盖住前一个的 —— 边框一变色（hover 态）那条线就看不见了 */
+  > .#{b('button')}:hover:not(:disabled),
+  > .#{b('button')}:focus-visible {
+    z-index: 1;
+  }
+}
+
+.#{m('button-group', 'vertical')} {
+  flex-direction: column;
+  align-items: stretch;
+
+  > .#{b('button')} {
+    width: 100%;
+    margin-left: 0;
+    margin-top: -1px;
+  }
+
+  > .#{b('button')}:first-child {
+    margin-top: 0;
+    border-radius: v('radius', 6px) v('radius', 6px) 0 0;
+  }
+
+  > .#{b('button')}:last-child {
+    border-radius: 0 0 v('radius', 6px) v('radius', 6px);
+  }
+
+  /* 同上：上下相邻时也用 margin-top: -1px 重叠，hover 时同样要抬升 */
+  > .#{b('button')}:hover:not(:disabled),
+  > .#{b('button')}:focus-visible {
+    z-index: 1;
+  }
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/button-group/ButtonGroupSeparator.vue b/code/g3soft-libs/packages/ui/src/button-group/ButtonGroupSeparator.vue
new file mode 100644
index 00000000..992c33ce
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/button-group/ButtonGroupSeparator.vue
@@ -0,0 +1,41 @@
+<script setup lang="ts">
+import { useNamespace } from '../_composables/useNamespace'
+import type { ButtonGroupSeparatorProps } from './types'
+
+/**
+ * 按钮组分隔线 —— 在成组的按钮之间插入一条细线。
+ *
+ * orientation 应与所在按钮组**相反**：横向排列的组里用 vertical（默认），
+ * 纵向排列的组里用 horizontal。
+ */
+defineOptions({ name: 'G3ButtonGroupSeparator' })
+
+const props = withDefaults(defineProps<ButtonGroupSeparatorProps>(), {
+  orientation: 'vertical',
+})
+
+const { b, m } = useNamespace('button-group-separator')
+</script>
+
+<template>
+  <span :class="[b(), m(props.orientation)]" aria-hidden="true" />
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+.#{b('button-group-separator')} {
+  align-self: stretch;
+  flex-shrink: 0;
+  /* 与所在组的贴合排版配合：负 margin 叠掉相邻按钮的边框 */
+  background: v('border-color', #d9d9d9);
+}
+
+.#{m('button-group-separator', 'vertical')} {
+  width: 1px;
+}
+
+.#{m('button-group-separator', 'horizontal')} {
+  height: 1px;
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/button-group/index.ts b/code/g3soft-libs/packages/ui/src/button-group/index.ts
new file mode 100644
index 00000000..f258a9f1
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/button-group/index.ts
@@ -0,0 +1,7 @@
+export { default as G3ButtonGroup } from './ButtonGroup.vue'
+export { default as G3ButtonGroupSeparator } from './ButtonGroupSeparator.vue'
+export type {
+  ButtonGroupOrientation,
+  ButtonGroupProps,
+  ButtonGroupSeparatorProps,
+} from './types'
diff --git a/code/g3soft-libs/packages/ui/src/button-group/types.ts b/code/g3soft-libs/packages/ui/src/button-group/types.ts
new file mode 100644
index 00000000..6b69c6d3
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/button-group/types.ts
@@ -0,0 +1,12 @@
+/** 按钮组排列方向 */
+export type ButtonGroupOrientation = 'horizontal' | 'vertical'
+
+export interface ButtonGroupProps {
+  /** 排列方向 */
+  orientation?: ButtonGroupOrientation
+}
+
+export interface ButtonGroupSeparatorProps {
+  /** 分割线方向；应与所在按钮组的排列方向相反 */
+  orientation?: ButtonGroupOrientation
+}
diff --git a/code/g3soft-libs/packages/ui/src/button/Button.vue b/code/g3soft-libs/packages/ui/src/button/Button.vue
index 9fe67170..8622e528 100644
--- a/code/g3soft-libs/packages/ui/src/button/Button.vue
+++ b/code/g3soft-libs/packages/ui/src/button/Button.vue
@@ -1,47 +1,53 @@
 <script setup lang="ts">
 import { computed } from 'vue'
+import { Loader } from '@lucide/vue'
+import { useComponentDefaults } from '../_composables/useComponentDefaults'
 import { useNamespace } from '../_composables/useNamespace'
 import type { ButtonProps } from './types'
 
 /**
  * 常用的操作按钮。
  *
- * 支持 7 种视觉类型、3 种尺寸，以及加载、禁用、撑满、纯图标等状态。
+ * 支持 8 种视觉变体（primary / secondary / outline / ghost / danger / danger-outline / link / icon）
+ * 与 3 档尺寸，以及加载、禁用、撑满等状态。
  */
 defineOptions({ name: 'G3Button' })
 
 const props = withDefaults(defineProps<ButtonProps>(), {
-  type: 'default',
-  size: 'medium',
+  // type / size 默认值留空：先让全局默认值（componentDefaults）有机会生效
+  type: undefined,
+  size: undefined,
   htmlType: 'button',
   disabled: false,
   loading: false,
   block: false,
-  iconOnly: false,
 })
 
-/**
- * 点击按钮时触发。
- * 禁用或加载中不会触发。
- */
+/** 全局默认值回落：显式 prop > ConfigProvider.componentDefaults.button > 组件内置默认 */
+const merged = useComponentDefaults('button', props)
+
+/** 点击按钮时触发。禁用或加载中不会触发。 */
 const emit = defineEmits<{ click: [ev: MouseEvent] }>()
 
 const { b, e, m, is } = useNamespace('button')
 
+const mergedType = computed(() => merged.value.type ?? 'primary')
+const mergedSize = computed(() => merged.value.size ?? 'medium')
+const isDisabled = computed(() => merged.value.disabled || merged.value.loading)
+
 const classes = computed(() => [
   b(),
-  m(props.type),
-  m(props.size),
+  m(mergedType.value),
+  m(mergedSize.value),
   {
-    [is('disabled')]: props.disabled,
-    [is('loading')]: props.loading,
-    [is('block')]: props.block,
-    [is('icon-only')]: props.iconOnly,
+    [is('disabled')]: merged.value.disabled,
+    [is('loading')]: merged.value.loading,
+    [is('block')]: merged.value.block,
   },
 ])
 
 function handleClick(ev: MouseEvent) {
-  if (props.disabled || props.loading) {
+  if (isDisabled.value) {
     ev.preventDefault()
     ev.stopPropagation()
     return
@@ -52,12 +58,13 @@ function handleClick(ev: MouseEvent) {
 
 <template>
   <button
+    :type="merged.htmlType"
     :class="classes"
-    :type="htmlType"
-    :disabled="disabled || loading"
+    :disabled="isDisabled"
+    :aria-busy="merged.loading || undefined"
     @click="handleClick"
   >
-    <span v-if="loading" :class="e('spinner')" aria-hidden="true" />
+    <Loader v-if="merged.loading" :class="e('spinner')" aria-hidden="true" />
     <span v-if="$slots.icon" :class="e('icon')"><slot name="icon" /></span>
     <span v-if="$slots.default" :class="e('content')"><slot /></span>
   </button>
@@ -75,49 +82,93 @@ function handleClick(ev: MouseEvent) {
   display: inline-flex;
   align-items: center;
   justify-content: center;
-  gap: 4px;
+  gap: v('space-1', 4px);
   box-sizing: border-box;
-  height: v('control-height', 32px);
-  padding: 0 15px;
-  border: 1px solid v('border-color', #d9d9d9);
+  min-height: v('control-height', 32px);
+  padding: 0 v('space-3', 12px);
+  border: 1px solid transparent;
   border-radius: v('radius', 6px);
-  background: v('bg-container', #fff);
+  background: transparent;
   color: v('text-1', rgba(0, 0, 0, 0.88));
   font-family: inherit;
   font-size: v('font-size', 14px);
-  line-height: 1;
+  font-weight: 500;
+  line-height: v('line-height', 1.5);
   white-space: nowrap;
   cursor: pointer;
   user-select: none;
-  transition: all v('duration', 0.2s) v('ease', ease);
+
+  /* hover 去抖：慢移时鼠标会在按钮边缘反复进出，每次进出都重启 background-color 过渡
+   * → 背景反复明灭，看着就是「闪烁多次」。给「离开」的过渡加一点延迟，把极短的离开
+   * 吸收掉；「进入」在 :hover 里把延迟归零，保持跟手。 */
+  #{css-var('button-hover-debounce')}: 60ms;
+
+  /* 只动颜色 + 极轻缩放，不做位移；显式列出属性，不用 transition: all */
+  transition:
+    background-color v('duration', 0.2s) v('ease', ease) #{v('button-hover-debounce', 60ms)},
+    border-color v('duration', 0.2s) v('ease', ease) #{v('button-hover-debounce', 60ms)},
+    box-shadow v('duration', 0.2s) v('ease', ease),
+    color v('duration', 0.2s) v('ease', ease),
+    transform v('duration-fast', 0.1s) v('ease', ease);
+
+  /* 按钮内图标跟随字号缩放 */
+  svg {
+    width: 1em;
+    height: 1em;
+  }
 }
 
-.#{b('button')}:hover:not(:disabled) {
-  border-color: v('color-primary', #18181b);
-  color: v('color-primary', #18181b);
+.#{b('button')}:hover {
+  transition-delay: 0ms;
+}
+
+/* 按下反馈：0.97 足够被感知，再大就显得浮夸；禁用态不给反馈 */
+.#{b('button')}:active:not(:disabled) {
+  transform: scale(0.97);
 }
 
 .#{b('button')}:focus-visible {
   @include focus-ring();
 }
 
-.#{b('button')}:disabled {
-  background: v('bg-disabled', rgba(0, 0, 0, 0.04));
-  border-color: v('border-color', #d9d9d9);
-  color: v('text-disabled', rgba(0, 0, 0, 0.25));
+.#{b('button')}.#{is('disabled')} {
+  opacity: 0.5;
   cursor: not-allowed;
 }
 
+/* 加载态虽是原生 disabled，但视觉是「进行中」而非「禁用」：保持原配色并锁定缩放 */
+.#{b('button')}.#{is('loading')} {
+  opacity: 1;
+  cursor: wait;
+  transform: none;
+}
+
+/* 加载时隐藏用户图标与文字以外的图标，避免与 spinner 打架 */
+.#{b('button')}.#{is('loading')} .#{e('button', 'icon')} {
+  display: none;
+}
+
+.#{e('button', 'spinner')} {
+  flex-shrink: 0;
+  animation: #{b('button')}-spin 0.7s linear infinite;
+}
+
+@keyframes #{b('button')}-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
 /* ---------- 尺寸 ---------- */
 .#{m('button', 'small')} {
-  height: v('control-height-sm', 24px);
-  padding: 0 7px;
+  min-height: v('control-height-sm', 24px);
+  padding: 0 v('space-2', 8px);
   font-size: v('font-size-sm', 12px);
 }
 
 .#{m('button', 'large')} {
-  height: v('control-height-lg', 40px);
-  padding: 0 19px;
+  min-height: v('control-height-lg', 40px);
+  padding: 0 v('space-4', 16px);
   font-size: v('font-size-lg', 16px);
 }
 
@@ -126,93 +177,117 @@ function handleClick(ev: MouseEvent) {
   width: 100%;
 }
 
-.#{b('button')}.#{is('icon-only')} {
-  width: v('control-height', 32px);
-  padding: 0;
-}
-
-.#{b('button')}.#{is('icon-only')}.#{m('button', 'small')} {
-  width: v('control-height-sm', 24px);
-}
-
-.#{b('button')}.#{is('icon-only')}.#{m('button', 'large')} {
-  width: v('control-height-lg', 40px);
-}
-
-/* ---------- primary（shadcn 风格：hover/active 用主色透明度）---------- */
+/* ---------- primary：主操作，跟随主色 ---------- */
 .#{m('button', 'primary')} {
   background: v('color-primary', #18181b);
-  border-color: v('color-primary', #18181b);
   color: v('color-primary-on', #fafafa);
 }
 
 .#{m('button', 'primary')}:hover:not(:disabled) {
   background: v('color-primary-hover', rgba(24, 24, 27, 0.9));
-  border-color: v('color-primary-hover', rgba(24, 24, 27, 0.9));
-  color: v('color-primary-on', #fafafa);
 }
 
 .#{m('button', 'primary')}:active:not(:disabled) {
   background: v('color-primary-active', rgba(24, 24, 27, 0.8));
-  border-color: v('color-primary-active', rgba(24, 24, 27, 0.8));
 }
 
-.#{m('button', 'primary')}:disabled {
-  background: v('bg-disabled', rgba(0, 0, 0, 0.04));
+/* ---------- secondary：次级操作，浅填充 ---------- */
+.#{m('button', 'secondary')} {
+  background: v('fill', rgba(0, 0, 0, 0.04));
+  color: v('text-1', rgba(0, 0, 0, 0.88));
+}
+
+.#{m('button', 'secondary')}:hover:not(:disabled) {
+  background: v('fill-hover', rgba(0, 0, 0, 0.08));
+}
+
+/* ---------- outline：描边按钮 ---------- */
+.#{m('button', 'outline')} {
   border-color: v('border-color', #d9d9d9);
-  color: v('text-disabled', rgba(0, 0, 0, 0.25));
+  color: v('text-1', rgba(0, 0, 0, 0.88));
 }
 
-/* ---------- success / warning / danger ---------- */
-.#{m('button', 'success')} {
-  background: v('color-success', #45b114);
-  border-color: v('color-success', #45b114);
-  color: v('text-inverse', #fff);
-}
-
-.#{m('button', 'warning')} {
-  background: v('color-warning', #e79a0d);
-  border-color: v('color-warning', #e79a0d);
-  color: v('text-inverse', #fff);
-}
-
-.#{m('button', 'danger')} {
-  background: v('color-danger', #ec4246);
-  border-color: v('color-danger', #ec4246);
-  color: v('text-inverse', #fff);
-}
-
-/* ---------- text / link ---------- */
-.#{m('button', 'text')},
-.#{m('button', 'link')} {
-  height: auto;
-  padding: 0 4px;
-  border-color: transparent;
-  background: transparent;
-}
-
-.#{m('button', 'link')} {
+.#{m('button', 'outline')}:hover:not(:disabled) {
+  background: v('fill', rgba(0, 0, 0, 0.04));
+  border-color: v('color-primary', #18181b);
   color: v('color-primary', #18181b);
 }
 
-/* ---------- loading ---------- */
-.#{b('button')}.#{is('loading')} {
-  cursor: default;
-  opacity: 0.65;
+/* ---------- ghost：低强调 ---------- */
+.#{m('button', 'ghost')} {
+  color: v('text-2', rgba(0, 0, 0, 0.65));
 }
 
-.#{e('button', 'spinner')} {
-  width: 1em;
-  height: 1em;
-  border: 2px solid currentColor;
-  border-top-color: transparent;
-  border-radius: 50%;
-  animation: #{b('button')}-spin 0.8s linear infinite;
+.#{m('button', 'ghost')}:hover:not(:disabled) {
+  background: v('fill', rgba(0, 0, 0, 0.04));
+  color: v('text-1', rgba(0, 0, 0, 0.88));
 }
 
-@keyframes #{b('button')}-spin {
-  to {
-    transform: rotate(360deg);
+/* ---------- danger：危险操作（弹窗确认框里的最终提交动作）---------- */
+.#{m('button', 'danger')} {
+  background: v('color-danger', #ec4246);
+  color: v('text-inverse', #fff);
+}
+
+.#{m('button', 'danger')}:hover:not(:disabled) {
+  background: color-mix(in srgb, #{v('color-danger', #ec4246)} 88%, #000);
+}
+
+/* ---------- danger-outline：表达危险语义但不与主操作抢视觉 ---------- */
+.#{m('button', 'danger-outline')} {
+  border-color: v('color-danger', #ec4246);
+  color: v('color-danger', #ec4246);
+}
+
+.#{m('button', 'danger-outline')}:hover:not(:disabled) {
+  background: color-mix(in srgb, #{v('color-danger', #ec4246)} 8%, transparent);
+}
+
+/* ---------- link：链接样式 ---------- */
+.#{m('button', 'link')} {
+  min-height: auto;
+  padding: 0 v('space-1', 4px);
+  color: v('color-primary', #18181b);
+}
+
+.#{m('button', 'link')}:hover:not(:disabled) {
+  color: v('color-primary-hover', rgba(24, 24, 27, 0.9));
+  text-decoration: underline;
+}
+
+/* ---------- icon：工具条 / 面板头部的正方形图标按钮 ---------- */
+.#{m('button', 'icon')} {
+  width: v('control-height', 32px);
+  min-height: v('control-height', 32px);
+  padding: 0;
+  border-color: v('border-color', #d9d9d9);
+  background: v('bg-container', #fff);
+  color: v('text-2', rgba(0, 0, 0, 0.65));
+}
+
+.#{m('button', 'icon')}:hover:not(:disabled) {
+  background: v('fill', rgba(0, 0, 0, 0.04));
+  color: v('text-1', rgba(0, 0, 0, 0.88));
+}
+
+.#{m('button', 'icon')}.#{m('button', 'small')} {
+  width: v('control-height-sm', 24px);
+  min-height: v('control-height-sm', 24px);
+}
+
+.#{m('button', 'icon')}.#{m('button', 'large')} {
+  width: v('control-height-lg', 40px);
+  min-height: v('control-height-lg', 40px);
+}
+
+/* 尊重系统「减少动态效果」偏好：停掉 spinner，去掉按下缩放 */
+@media (prefers-reduced-motion: reduce) {
+  .#{b('button')} {
+    transition-duration: 0ms;
+  }
+
+  .#{e('button', 'spinner')} {
+    animation: none;
   }
 }
 </style>
diff --git a/code/g3soft-libs/packages/ui/src/button/types.ts b/code/g3soft-libs/packages/ui/src/button/types.ts
index 6929f705..be4f8344 100644
--- a/code/g3soft-libs/packages/ui/src/button/types.ts
+++ b/code/g3soft-libs/packages/ui/src/button/types.ts
@@ -1,18 +1,19 @@
-/** 按钮视觉类型 */
+/** 按钮视觉变体 */
 export type ButtonType =
-  | 'default'
   | 'primary'
-  | 'success'
-  | 'warning'
+  | 'secondary'
+  | 'outline'
+  | 'ghost'
   | 'danger'
-  | 'text'
+  | 'danger-outline'
   | 'link'
+  | 'icon'
 
 /** 按钮尺寸 */
 export type ButtonSize = 'small' | 'medium' | 'large'
 
 export interface ButtonProps {
-  /** 视觉类型 */
+  /** 视觉变体：icon 为工具条 / 面板头部的正方形描边图标按钮 */
   type?: ButtonType
   /** 尺寸 */
   size?: ButtonSize
@@ -24,6 +25,4 @@ export interface ButtonProps {
   loading?: boolean
   /** 是否撑满父容器宽度 */
   block?: boolean
-  /** 是否仅图标：渲染为正方形按钮 */
-  iconOnly?: boolean
 }
diff --git a/code/g3soft-libs/packages/ui/src/checkbox/Checkbox.vue b/code/g3soft-libs/packages/ui/src/checkbox/Checkbox.vue
new file mode 100644
index 00000000..b85c4b5a
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/checkbox/Checkbox.vue
@@ -0,0 +1,158 @@
+<script setup lang="ts">
+import { computed, onMounted, ref, watch } from 'vue'
+import { Check, Minus } from '@lucide/vue'
+import { useNamespace } from '../_composables/useNamespace'
+import type { CheckboxProps } from './types'
+
+/**
+ * 复选框 —— 支持选中 / 未选中 / 半选三种状态。
+ *
+ * 半选（indeterminate）是原生 DOM property，无法通过 attribute 绑定，组件内部手动同步；
+ * 勾选态优先，选中时会强制清除半选。
+ */
+defineOptions({ name: 'G3Checkbox' })
+
+const props = withDefaults(defineProps<CheckboxProps>(), {
+  modelValue: false,
+  indeterminate: false,
+  disabled: false,
+  name: undefined,
+  value: undefined,
+})
+
+const emit = defineEmits<{
+  'update:modelValue': [value: boolean]
+  change: [value: boolean, ev: Event]
+  focus: [ev: FocusEvent]
+  blur: [ev: FocusEvent]
+}>()
+
+const { b, e, m, is } = useNamespace('checkbox')
+
+const inputRef = ref<HTMLInputElement | null>(null)
+
+/** 选中态优先显示勾选；仅在未选中且半选时显示减号 */
+const icon = computed(() => {
+  if (props.modelValue) return Check
+  if (props.indeterminate) return Minus
+  return null
+})
+
+const classes = computed(() => [
+  b(),
+  {
+    [is('checked')]: props.modelValue,
+    [is('indeterminate')]: props.indeterminate,
+    [is('disabled')]: props.disabled,
+  },
+])
+
+function onChange(event: Event) {
+  const checked = (event.target as HTMLInputElement).checked
+  emit('update:modelValue', checked)
+  emit('change', checked, event)
+}
+
+function syncIndeterminate() {
+  if (inputRef.value) {
+    inputRef.value.indeterminate = props.indeterminate && !props.modelValue
+  }
+}
+
+onMounted(syncIndeterminate)
+watch(() => [props.indeterminate, props.modelValue], syncIndeterminate)
+</script>
+
+<template>
+  <label :class="classes">
+    <input
+      ref="inputRef"
+      :class="e('input')"
+      type="checkbox"
+      :checked="modelValue"
+      :disabled="disabled"
+      :name="name"
+      :value="value"
+      @change="onChange"
+      @focus="emit('focus', $event)"
+      @blur="emit('blur', $event)"
+    />
+    <span :class="e('box')" aria-hidden="true">
+      <component :is="icon" v-if="icon" />
+    </span>
+    <span v-if="$slots.default" :class="e('label')">
+      <slot />
+    </span>
+  </label>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+.#{b('checkbox')} {
+  display: inline-flex;
+  align-items: center;
+  gap: v('space-2', 8px);
+  color: v('text-1', rgba(0, 0, 0, 0.88));
+  font-size: v('font-size', 14px);
+  line-height: v('line-height', 1.5);
+  cursor: pointer;
+  user-select: none;
+}
+
+.#{e('checkbox', 'input')} {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: 0;
+  opacity: 0;
+  pointer-events: none;
+}
+
+.#{e('checkbox', 'box')} {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  box-sizing: border-box;
+  flex-shrink: 0;
+  width: v('checkbox-size', 16px);
+  height: v('checkbox-size', 16px);
+  border: 1px solid v('border-color', #d9d9d9);
+  border-radius: v('radius-sm', 4px);
+  background: v('bg-container', #fff);
+  color: v('text-inverse', #fff);
+  transition:
+    background-color v('duration', 0.2s) v('ease', ease),
+    border-color v('duration', 0.2s) v('ease', ease);
+
+  svg {
+    width: 10px;
+    height: 10px;
+  }
+}
+
+.#{b('checkbox')}:hover:not(.#{is('disabled')}) .#{e('checkbox', 'box')} {
+  border-color: v('color-primary', #18181b);
+}
+
+.#{b('checkbox')}.#{is('checked')} .#{e('checkbox', 'box')},
+.#{b('checkbox')}.#{is('indeterminate')} .#{e('checkbox', 'box')} {
+  border-color: v('color-primary', #18181b);
+  background: v('color-primary', #18181b);
+}
+
+.#{e('checkbox', 'input')}:focus-visible + .#{e('checkbox', 'box')} {
+  @include focus-ring();
+}
+
+.#{b('checkbox')}.#{is('disabled')} {
+  color: v('text-disabled', rgba(0, 0, 0, 0.25));
+  cursor: not-allowed;
+}
+
+.#{b('checkbox')}.#{is('disabled')} .#{e('checkbox', 'box')} {
+  border-color: v('border-color', #d9d9d9);
+  background: v('bg-disabled', rgba(0, 0, 0, 0.04));
+  color: v('text-disabled', rgba(0, 0, 0, 0.25));
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/checkbox/index.ts b/code/g3soft-libs/packages/ui/src/checkbox/index.ts
new file mode 100644
index 00000000..f8008d23
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/checkbox/index.ts
@@ -0,0 +1,2 @@
+export { default as G3Checkbox } from './Checkbox.vue'
+export type { CheckboxProps } from './types'
diff --git a/code/g3soft-libs/packages/ui/src/checkbox/types.ts b/code/g3soft-libs/packages/ui/src/checkbox/types.ts
new file mode 100644
index 00000000..d0d2c6cb
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/checkbox/types.ts
@@ -0,0 +1,12 @@
+export interface CheckboxProps {
+  /** 双向绑定的选中状态 */
+  modelValue?: boolean
+  /** 半选状态，用于表格全选 / 部分选中场景 */
+  indeterminate?: boolean
+  /** 禁用态 */
+  disabled?: boolean
+  /** 原生 name，用于表单提交分组 */
+  name?: string
+  /** 原生 value，勾选时随表单提交的值 */
+  value?: string | number | boolean
+}
diff --git a/code/g3soft-libs/packages/ui/src/date/CalendarPanel.vue b/code/g3soft-libs/packages/ui/src/date/CalendarPanel.vue
new file mode 100644
index 00000000..97676e8a
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/date/CalendarPanel.vue
@@ -0,0 +1,825 @@
+<script setup lang="ts">
+import { computed, nextTick, ref, watch } from 'vue'
+import { ChevronLeft, ChevronRight, ChevronsLeft, ChevronsRight } from '@lucide/vue'
+import { useLocale } from '../_composables/useLocale'
+import { useNamespace } from '../_composables/useNamespace'
+import G3Button from '../button/Button.vue'
+import G3TimeSelect from './TimeSelect.vue'
+import {
+  addMonth,
+  analyzeDateFormat,
+  combineDateTime,
+  compareDay,
+  DEFAULT_DATE_FORMAT,
+  endOfDay,
+  formatDate,
+  getMonthRows,
+  isInRange,
+  isSameDay,
+  isSameMonth,
+  isToday,
+  startOfDay,
+} from './date-utils'
+import type { CalendarMode, CalendarPanelProps } from './types'
+
+/**
+ * 日历面板 —— 单选 / 范围两种模式，可选时间列与年 / 月选择视图。
+ *
+ * 面板只操作「草稿值」：点选 emit pick、范围模式 emit update:start / update:end，
+ * 是否需要确认由外层 picker 决定（有时间精度时底部出现确认按钮）。
+ */
+defineOptions({ name: 'G3CalendarPanel' })
+
+const props = withDefaults(defineProps<CalendarPanelProps>(), {
+  type: 'date',
+  modelValue: null,
+  start: null,
+  end: null,
+  hoverValue: null,
+  timeDefault: '',
+  pickerConfig: undefined,
+  disabledDate: undefined,
+})
+
+const emit = defineEmits<{
+  pick: [value: Date]
+  hover: [value: Date | null]
+  'update:start': [value: Date]
+  'update:end': [value: Date]
+  confirm: []
+}>()
+
+const { b, e, m, is } = useNamespace('calendar')
+const locale = useLocale()
+
+const config = computed(() => props.pickerConfig ?? analyzeDateFormat(DEFAULT_DATE_FORMAT))
+
+/** 无值锚点：草稿值 → 范围两端 → 今天 */
+const anchorDate = computed(() => props.modelValue ?? props.start ?? props.end ?? new Date())
+
+const viewDate = ref(anchorDate.value)
+const mode = ref<CalendarMode>('date')
+const activeDate = ref(anchorDate.value)
+const yearPageStart = ref(anchorDate.value.getFullYear() - 5)
+
+const time = ref<Date>(props.modelValue ?? new Date())
+const startTime = ref<Date>(props.start ?? new Date())
+const endTime = ref<Date>(props.end ?? new Date())
+
+/** 下一次点击是设起点还是终点 */
+const isPickingStart = computed(() => props.type === 'range' && (!props.start || Boolean(props.end)))
+
+const confirmDisabled = computed(() => {
+  if (props.type === 'range') return !props.start || !props.end
+  return !props.modelValue
+})
+
+/** 时间列的联动取值：范围模式按当前端取 */
+const activeTime = computed(() =>
+  props.type === 'range' ? (isPickingStart.value ? startTime.value : endTime.value) : time.value,
+)
+
+function timeDefaults(date: Date): Date {
+  if (props.timeDefault === 'start') return startOfDay(date) as Date
+  if (props.timeDefault === 'end') return endOfDay(date) as Date
+  return date
+}
+
+/* ---------- 初始模式与外部值同步 ---------- */
+function resolveMode(): CalendarMode {
+  if (!config.value.hasDateParts) return 'time'
+  if (config.value.hasDay) return 'date'
+  if (config.value.hasMonth) return 'month'
+  return 'year'
+}
+
+/* ---------- 标题按钮切换年 / 月面板 ---------- */
+/** 进入年视图时把年份窗口对齐到当前年（一页 12 年，当前年居中偏上） */
+function toggleYearPanel() {
+  if (mode.value === 'year') {
+    mode.value = resolveMode()
+    return
+  }
+  yearPageStart.value = viewDate.value.getFullYear() - 5
+  mode.value = 'year'
+}
+
+function toggleMonthPanel() {
+  mode.value = mode.value === 'month' ? resolveMode() : 'month'
+}
+
+/**
+ * 年 / 月导航。
+ * 年视图下翻「一整页」（12 年）—— 面板里的两个翻页按钮因此不再需要，
+ * 箭头复用 header 上那对（与 fms 一致）；日期视图下走 12 个月。
+ */
+function stepYear(delta: number) {
+  if (mode.value === 'year') yearPageStart.value += delta * 12
+  else viewDate.value = addMonth(viewDate.value, delta * 12)
+}
+
+watch(
+  () => config.value,
+  () => {
+    mode.value = resolveMode()
+    viewDate.value = anchorDate.value
+  },
+  { immediate: true },
+)
+
+watch(
+  () => props.modelValue,
+  (value) => {
+    if (!value) return
+    time.value = value
+    viewDate.value = value
+    activeDate.value = value
+  },
+)
+
+watch(
+  () => [props.start, props.end],
+  ([start, end]) => {
+    if (start) {
+      startTime.value = start
+      viewDate.value = start
+      activeDate.value = start
+    }
+    if (end) endTime.value = end
+  },
+)
+
+/* ---------- 月历数据 ---------- */
+interface Cell {
+  date: Date
+  key: string
+  label: string
+  otherMonth: boolean
+  today: boolean
+  selected: boolean
+  rangeStart: boolean
+  rangeEnd: boolean
+  rangeSingle: boolean
+  inRange: boolean
+  inHoverRange: boolean
+  disabled: boolean
+}
+
+const weekdays = computed(() => locale.value.date.weekdays)
+
+const rows = computed<Cell[][]>(() => {
+  const year = viewDate.value.getFullYear()
+  const month = viewDate.value.getMonth()
+  const start = props.start
+  const end = props.end
+  const hover = props.hoverValue && start && !end ? props.hoverValue : null
+
+  return getMonthRows(year, month).map((week) =>
+    week.map((date) => {
+      const disabled = props.disabledDate?.(date) === true
+      const rangeStart = isSameDay(date, start)
+      const rangeEnd = isSameDay(date, end)
+      const single = Boolean(start && end && rangeStart && rangeEnd)
+      const inRange = Boolean(start && end && isInRange(date, start, end))
+      const inHoverRange = Boolean(hover && start && isInRange(date, start, hover))
+      return {
+        date,
+        key: formatDate(date, 'YYYY-MM-DD'),
+        label: formatDate(date, 'YYYY年M月D日'),
+        otherMonth: !isSameMonth(date, viewDate.value),
+        today: isToday(date),
+        selected: isSameDay(date, props.modelValue),
+        rangeStart: Boolean(rangeStart) && !single,
+        rangeEnd: Boolean(rangeEnd) && !single,
+        rangeSingle: single,
+        inRange: inRange && !rangeStart && !rangeEnd,
+        inHoverRange: inHoverRange && !disabled,
+        disabled,
+      }
+    }),
+  )
+})
+
+const focusableKey = computed(() => {
+  const flat = rows.value.flat()
+  const focused = flat.find((cell) => isSameDay(cell.date, activeDate.value) && !cell.disabled)
+  const fallback = flat.find((cell) => !cell.disabled)
+  return (focused ?? fallback)?.key ?? ''
+})
+
+/* ---------- 年 / 月选择器 ---------- */
+/** 今天所在的年 / 月：「当年 / 当月」用内描边标记，「当前查看的年 / 月」用主色填充 */
+const today = new Date()
+const currentYear = today.getFullYear()
+const currentMonth = today.getMonth()
+
+const yearOptions = computed(() =>
+  Array.from({ length: 12 }, (_, index) => yearPageStart.value + index),
+)
+const monthOptions = computed(() =>
+  Array.from({ length: 12 }, (_, index) => ({
+    value: index,
+    label: locale.value.date.months[index],
+  })),
+)
+
+/* ---------- 交互 ---------- */
+function cellClasses(cell: Cell): Record<string, boolean> {
+  return {
+    [is('other-month')]: cell.otherMonth,
+    [is('today')]: cell.today,
+    [is('selected')]: cell.selected,
+    [is('range-start')]: cell.rangeStart,
+    [is('range-end')]: cell.rangeEnd,
+    [is('range-single')]: cell.rangeSingle,
+    [is('in-range')]: cell.inRange,
+    [is('in-hover-range')]: cell.inHoverRange,
+    [is('disabled')]: cell.disabled,
+  }
+}
+
+/** 选中一格：把日期与对应的草稿时间合并后抛给外层 */
+function onCellClick(cell: Cell) {
+  if (cell.disabled) return
+  const timeSource = props.type === 'range' ? activeTime.value : time.value
+  const combined = combineDateTime(cell.date, config.value.hasTime ? timeSource : timeDefaults(cell.date))
+  activeDate.value = cell.date
+  emit('pick', combined)
+}
+
+function onCellHover(cell: Cell) {
+  if (props.type !== 'range' || !props.start || props.end) return
+  emit('hover', cell.disabled ? null : cell.date)
+}
+
+function onGridLeave() {
+  if (props.type === 'range') emit('hover', null)
+}
+
+function moveFocus(deltaDays: number) {
+  const next = new Date(activeDate.value.getTime())
+  next.setDate(next.getDate() + deltaDays)
+  for (let attempt = 0; attempt < 366; attempt++) {
+    if (!props.disabledDate?.(next)) break
+    next.setDate(next.getDate() + Math.sign(deltaDays || 1))
+  }
+  activeDate.value = next
+  if (!isSameMonth(next, viewDate.value)) viewDate.value = next
+  nextTick(() => {
+    document.querySelector<HTMLElement>(`.${b('cell')}[data-key="${formatDate(next, 'YYYY-MM-DD')}"]`)?.focus()
+  })
+}
+
+function onCellKeydown(cell: Cell, event: KeyboardEvent) {
+  switch (event.key) {
+    case 'ArrowLeft':
+      event.preventDefault()
+      moveFocus(-1)
+      break
+    case 'ArrowRight':
+      event.preventDefault()
+      moveFocus(1)
+      break
+    case 'ArrowUp':
+      event.preventDefault()
+      moveFocus(-7)
+      break
+    case 'ArrowDown':
+      event.preventDefault()
+      moveFocus(7)
+      break
+    case 'PageUp':
+      event.preventDefault()
+      viewDate.value = addMonth(viewDate.value, -1)
+      break
+    case 'PageDown':
+      event.preventDefault()
+      viewDate.value = addMonth(viewDate.value, 1)
+      break
+    case 'Enter':
+    case ' ':
+      event.preventDefault()
+      onCellClick(cell)
+      break
+  }
+}
+
+function onTimeChange(value: Date) {
+  if (props.type === 'range') {
+    if (isPickingStart.value) {
+      startTime.value = value
+      if (props.start) emit('update:start', combineDateTime(props.start, value))
+    } else {
+      endTime.value = value
+      if (props.end) emit('update:end', combineDateTime(props.end, value))
+    }
+    return
+  }
+  time.value = value
+  emit('pick', combineDateTime(props.modelValue ?? new Date(), value))
+}
+
+/** 把焦点送进当前面板模式（picker 的 Alt+↓ 依赖） */
+function focusActive() {
+  nextTick(() => {
+    const selector =
+      mode.value === 'year'
+        ? `.${b('selector-item')}`
+        : mode.value === 'month'
+          ? `.${b('selector-item')}`
+          : mode.value === 'time'
+            ? `.${b('time')} .g3-time-select__list`
+            : `.${b('cell')}[tabindex="0"]`
+    document.querySelector<HTMLElement>(selector)?.focus()
+  })
+}
+
+defineExpose({ focusActive })
+
+const titleText = computed(() => {
+  const year = viewDate.value.getFullYear()
+  const month = viewDate.value.getMonth() + 1
+  return `${formatDate(viewDate.value, locale.value.date.year.replace('{year}', 'YYYY'))}${formatDate(
+    viewDate.value,
+    locale.value.date.month.replace('{month}', 'MM'),
+  )}`
+})
+
+</script>
+
+<template>
+  <div :class="[b(), m(type), { [is('time-only')]: !config.hasDateParts, [is('has-time')]: config.hasTime }]">
+    <div :class="e('body')">
+      <div v-if="config.hasDateParts" :class="e('main')">
+        <div :class="e('header')">
+          <div :class="e('nav-group')">
+            <button
+              type="button"
+              :class="e('nav')"
+              aria-label="上一年"
+              @click="stepYear(-1)"
+            >
+              <ChevronsLeft aria-hidden="true" />
+            </button>
+            <button
+              type="button"
+              :class="e('nav')"
+              :disabled="!config.hasMonth"
+              aria-label="上一月"
+              @click="viewDate = addMonth(viewDate, -1)"
+            >
+              <ChevronLeft aria-hidden="true" />
+            </button>
+          </div>
+          <div :class="e('title')" aria-live="polite">
+            <button
+              type="button"
+              :class="[e('title-button'), { [is('active')]: mode === 'year' }]"
+              :aria-expanded="mode === 'year'"
+              @click="toggleYearPanel"
+            >
+              <template v-if="mode === 'year'">{{ yearPageStart }} - {{ yearPageStart + 11 }}</template>
+              <template v-else>{{ viewDate.getFullYear() }} 年</template>
+            </button>
+            <button
+              v-if="config.hasMonth"
+              type="button"
+              :class="[e('title-button'), { [is('active')]: mode === 'month' }]"
+              :aria-expanded="mode === 'month'"
+              @click="toggleMonthPanel"
+            >
+              {{ locale.date.months[viewDate.getMonth()] }}
+            </button>
+          </div>
+          <div :class="e('nav-group')">
+            <button
+              type="button"
+              :class="e('nav')"
+              :disabled="!config.hasMonth"
+              aria-label="下一月"
+              @click="viewDate = addMonth(viewDate, 1)"
+            >
+              <ChevronRight aria-hidden="true" />
+            </button>
+            <button
+              type="button"
+              :class="e('nav')"
+              aria-label="下一年"
+              @click="stepYear(1)"
+            >
+              <ChevronsRight aria-hidden="true" />
+            </button>
+          </div>
+        </div>
+
+        <!-- 年视图 -->
+        <div v-if="mode === 'year'" :class="e('selector')" role="group" aria-label="年份选择">
+          <button
+            v-for="year in yearOptions"
+            :key="year"
+            type="button"
+            :class="[
+              e('selector-item'),
+              {
+                [is('current')]: year === currentYear,
+                [is('selected')]: year === viewDate.getFullYear(),
+              },
+            ]"
+            :aria-pressed="year === viewDate.getFullYear()"
+            @click="viewDate = new Date(year, viewDate.getMonth(), 1); mode = resolveMode()"
+          >
+            {{ year }}
+          </button>
+        </div>
+
+        <!-- 月视图 -->
+        <div v-else-if="mode === 'month'" :class="e('selector')" role="group" aria-label="月份选择">
+          <button
+            v-for="month in monthOptions"
+            :key="month.value"
+            type="button"
+            :class="[
+              e('selector-item'),
+              {
+                [is('current')]: month.value === currentMonth,
+                [is('selected')]: month.value === viewDate.getMonth(),
+              },
+            ]"
+            :aria-pressed="month.value === viewDate.getMonth()"
+            @click="viewDate = new Date(viewDate.getFullYear(), month.value, 1); mode = 'date'"
+          >
+            {{ month.label }}
+          </button>
+        </div>
+
+        <!-- 日期网格 -->
+        <div v-else :class="e('grid')" role="grid" :aria-label="titleText">
+          <div :class="e('weekdays')" role="row">
+            <span v-for="weekday in weekdays" :key="weekday" :class="e('weekday')" role="columnheader">
+              {{ weekday }}
+            </span>
+          </div>
+          <div :class="e('rows')" @mouseleave="onGridLeave">
+            <div v-for="(week, weekIndex) in rows" :key="weekIndex" :class="e('row')" role="row">
+              <button
+                v-for="cell in week"
+                :key="cell.key"
+                type="button"
+                :class="[e('cell'), cellClasses(cell)]"
+                :data-key="cell.key"
+                role="gridcell"
+                :aria-label="cell.label"
+                :aria-selected="cell.selected || cell.rangeStart || cell.rangeEnd"
+                :disabled="cell.disabled"
+                :tabindex="cell.key === focusableKey ? 0 : -1"
+                @click="onCellClick(cell)"
+                @mouseenter="onCellHover(cell)"
+                @focus="activeDate = cell.date"
+                @keydown="onCellKeydown(cell, $event)"
+              >
+                <span :class="e('cell-inner')">{{ cell.date.getDate() }}</span>
+              </button>
+            </div>
+          </div>
+        </div>
+      </div>
+
+      <div v-if="config.hasTime" :class="e('time')">
+        <!-- 单选不带「时间」标签：时间列与左侧日历正好等高（与 fms 一致） -->
+        <div v-if="type === 'date'" :class="e('time-group')">
+          <G3TimeSelect
+            :model-value="activeTime"
+            :fields="config.timeFields"
+            :hour12="config.hour12"
+            :lower-meridiem="config.lowerMeridiem"
+            @update:model-value="onTimeChange"
+          />
+        </div>
+        <template v-else>
+          <div :class="e('time-group')">
+            <span :class="e('time-label')">开始</span>
+            <G3TimeSelect
+              :model-value="startTime"
+              :fields="config.timeFields"
+              :hour12="config.hour12"
+              :lower-meridiem="config.lowerMeridiem"
+              @update:model-value="onTimeChange"
+            />
+          </div>
+          <div :class="e('time-group')">
+            <span :class="e('time-label')">结束</span>
+            <G3TimeSelect
+              :model-value="endTime"
+              :fields="config.timeFields"
+              :hour12="config.hour12"
+              :lower-meridiem="config.lowerMeridiem"
+              @update:model-value="onTimeChange"
+            />
+          </div>
+        </template>
+      </div>
+    </div>
+
+    <div v-if="config.hasTime" :class="e('footer')">
+      <G3Button size="small" :disabled="confirmDisabled" @click="emit('confirm')">
+        {{ locale.common.confirm }}
+      </G3Button>
+    </div>
+  </div>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+.#{b('calendar')} {
+  /* 日历主体与时间列共用的高度：两者等高，面板不会一块高一块矮 */
+  --g3-cal-h: #{v('calendar-height', 282px)};
+  display: flex;
+  flex-direction: column;
+  min-width: 240px;
+  padding: v('space-2', 8px);
+  color: v('text-1', rgba(0, 0, 0, 0.88));
+  font-size: v('font-size', 14px);
+}
+
+.#{e('calendar', 'header')} {
+  display: flex;
+  align-items: center;
+  gap: v('space-2', 8px);
+  padding: v('space-1', 4px) 0 v('space-2', 8px);
+}
+
+.#{e('calendar', 'nav-group')} {
+  display: inline-flex;
+  gap: v('space-1', 4px);
+}
+
+.#{e('calendar', 'nav')} {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 24px;
+  height: 24px;
+  padding: 0;
+  border: 0;
+  border-radius: v('radius-sm', 4px);
+  background: transparent;
+  color: v('text-2', rgba(0, 0, 0, 0.65));
+  cursor: pointer;
+
+  svg {
+    width: 16px;
+    height: 16px;
+  }
+
+  &:hover:not(:disabled) {
+    background: v('fill', rgba(0, 0, 0, 0.04));
+    color: v('text-1', rgba(0, 0, 0, 0.88));
+  }
+
+  &:disabled {
+    color: v('text-disabled', rgba(0, 0, 0, 0.25));
+    cursor: not-allowed;
+  }
+}
+
+.#{e('calendar', 'title')} {
+  display: inline-flex;
+  align-items: center;
+  gap: v('space-1', 4px);
+  flex: 1;
+  justify-content: center;
+}
+
+.#{e('calendar', 'title-button')} {
+  padding: 2px v('space-1', 4px);
+  border: 0;
+  border-radius: v('radius-sm', 4px);
+  background: transparent;
+  color: inherit;
+  font-family: inherit;
+  font-size: inherit;
+  font-weight: 600;
+  cursor: pointer;
+
+  &:hover,
+  &.is-active {
+    background: v('fill', rgba(0, 0, 0, 0.04));
+    color: v('color-primary', #18181b);
+  }
+}
+
+/* ---------- 日期网格 ---------- */
+.#{e('calendar', 'weekdays')},
+.#{e('calendar', 'row')} {
+  display: grid;
+  grid-template-columns: repeat(7, 1fr);
+}
+
+.#{e('calendar', 'weekday')} {
+  padding: v('space-1', 4px) 0;
+  color: v('text-3', rgba(0, 0, 0, 0.45));
+  font-size: v('font-size-sm', 12px);
+  text-align: center;
+}
+
+.#{e('calendar', 'cell')} {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  height: v('cal-cell-height', 32px);
+  padding: 0;
+  border: 0;
+  background: transparent;
+  color: inherit;
+  font-family: inherit;
+  font-size: inherit;
+  font-variant-numeric: tabular-nums;
+  cursor: pointer;
+
+  &:hover:not(:disabled) {
+    background: v('fill', rgba(0, 0, 0, 0.04));
+  }
+
+  &:focus-visible {
+    @include focus-ring();
+  }
+
+  &:disabled {
+    color: v('text-disabled', rgba(0, 0, 0, 0.25));
+    cursor: not-allowed;
+  }
+}
+
+.#{e('calendar', 'cell')}.#{is('other-month')} {
+  color: v('text-3', rgba(0, 0, 0, 0.45));
+}
+
+.#{e('calendar', 'cell')}.#{is('today')} .#{e('calendar', 'cell-inner')} {
+  color: v('color-primary', #18181b);
+  font-weight: 600;
+}
+
+.#{e('calendar', 'cell')}.#{is('selected')} .#{e('calendar', 'cell-inner')},
+.#{e('calendar', 'cell')}.#{is('range-single')} .#{e('calendar', 'cell-inner')} {
+  border-radius: 50%;
+  background: v('color-primary', #18181b);
+  color: v('color-primary-on', #fafafa);
+}
+
+.#{e('calendar', 'cell')}.#{is('range-start')},
+.#{e('calendar', 'cell')}.#{is('range-end')} {
+  background: v('color-primary-soft', rgba(24, 24, 27, 0.12));
+}
+
+.#{e('calendar', 'cell')}.#{is('range-start')} .#{e('calendar', 'cell-inner')},
+.#{e('calendar', 'cell')}.#{is('range-end')} .#{e('calendar', 'cell-inner')} {
+  border-radius: 50%;
+  background: v('color-primary', #18181b);
+  color: v('color-primary-on', #fafafa);
+}
+
+.#{e('calendar', 'cell')}.#{is('in-range')},
+.#{e('calendar', 'cell')}.#{is('in-hover-range')} {
+  background: v('color-primary-soft', rgba(24, 24, 27, 0.12));
+}
+
+.#{e('calendar', 'cell-inner')} {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 26px;
+  height: 26px;
+}
+
+/* ---------- 年 / 月选择器 ---------- */
+.#{e('calendar', 'selector')} {
+  flex: 1 1 auto;
+  display: grid;
+  /* 3 列 × 4 行 = 12 格：年份一页正好 12 个、月份正好 12 个 */
+  grid-template-columns: repeat(3, 1fr);
+  grid-template-rows: repeat(4, 1fr);
+  gap: v('space-2', 8px);
+  min-height: 0;
+  padding: v('space-2', 8px) 0 0;
+}
+
+.#{e('calendar', 'selector-item')} {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: v('space-2', 8px) 0;
+  border: 0;
+  border-radius: v('radius-sm', 4px);
+  background: transparent;
+  color: inherit;
+  font-family: inherit;
+  font-size: inherit;
+  cursor: pointer;
+
+  &:hover {
+    background: v('fill', rgba(0, 0, 0, 0.04));
+  }
+
+  /* 当年 / 当月但未选中：内描边 + 主色文字（与主色填充的选中态区分开） */
+  &.#{is('current')}:not(.#{is('selected')}) {
+    color: v('color-primary', #18181b);
+    box-shadow: inset 0 0 0 1px v('color-primary', #18181b);
+  }
+
+  /* 当前查看的年 / 月：主色填充 */
+  &.#{is('selected')} {
+    background: v('color-primary', #18181b);
+    color: v('color-primary-on', #fafafa);
+    font-weight: 600;
+  }
+
+  &:focus-visible {
+    @include focus-ring();
+  }
+}
+
+/* ---------- 主体：左日期 / 右时间（并排，antd 风格） ---------- */
+.#{e('calendar', 'body')} {
+  display: flex;
+  align-items: stretch;
+}
+
+.#{e('calendar', 'main')} {
+  /* 定宽：日历 7 列各约 31px。用固定宽度而不是被触发框拉伸，
+     否则输入框很宽时（表单满宽）日期格子间距会被撑得很散 */
+  flex: 0 0 auto;
+  width: v('calendar-main-width', 217px);
+  display: flex;
+  flex-direction: column;
+  padding-right: v('space-2', 8px);
+}
+
+/* 带时间列时与右侧等高：日期行均匀铺满，不会上挤下空 */
+.#{b('calendar')}.#{is('has-time')} .#{e('calendar', 'main')} {
+  height: var(--g3-cal-h);
+}
+
+.#{e('calendar', 'time')} {
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  flex-shrink: 0;
+  gap: v('space-4', 16px);
+  padding-left: v('space-3', 12px);
+  border-left: 1px solid v('border-color', #d9d9d9);
+}
+
+/* 时间列自身固定高度（= 日历区）。
+   不要用 flex 去"撑满"父级：时间区高度是 auto，靠 flex-grow 拿不到确定高度，
+   60 个选项会把整列撑到 1680px，列表就滚不起来了。 */
+.#{e('calendar', 'time')} .#{b('time-select')} {
+  flex: none;
+  height: var(--g3-cal-h);
+}
+
+/* 纯时间面板（format 只有时分秒）：没有左侧日历，去掉分隔线 */
+.#{b('calendar')}.#{is('time-only')} .#{e('calendar', 'time')} {
+  padding-left: 0;
+  border-left: none;
+}
+
+/* 范围模式：开始 / 结束两组并排，中间一条分隔线 */
+.#{b('calendar')}.#{m('calendar', 'range')} .#{e('calendar', 'time')} {
+  flex-direction: row;
+  align-items: stretch;
+  gap: 0;
+}
+
+.#{b('calendar')}.#{m('calendar', 'range')}
+  .#{e('calendar', 'time-group')}
+  + .#{e('calendar', 'time-group')} {
+  border-left: 1px solid v('border-color', #d9d9d9);
+}
+
+.#{e('calendar', 'time-group')} {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: v('space-1', 4px);
+}
+
+/* 时间列定宽：时 / 分 / 秒各占一列，等宽才好看 */
+.#{e('calendar', 'time')} .#{e('col', 'time-select')} {
+  flex: 0 0 auto;
+  width: v('time-col-width', 56px);
+}
+
+.#{e('calendar', 'time-label')} {
+  color: v('text-3', rgba(0, 0, 0, 0.45));
+  font-size: v('font-size-sm', 12px);
+}
+
+.#{e('calendar', 'footer')} {
+  display: flex;
+  justify-content: flex-end;
+  padding-top: v('space-2', 8px);
+  border-top: 1px solid v('border-color', #d9d9d9);
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/date/DatePicker.vue b/code/g3soft-libs/packages/ui/src/date/DatePicker.vue
new file mode 100644
index 00000000..69201b0d
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/date/DatePicker.vue
@@ -0,0 +1,350 @@
+<script setup lang="ts">
+import { computed, nextTick, ref, watch } from 'vue'
+import { X } from '@lucide/vue'
+import { useLocale } from '../_composables/useLocale'
+import { useNamespace } from '../_composables/useNamespace'
+import G3Popover from '../popover/Popover.vue'
+import G3CalendarPanel from './CalendarPanel.vue'
+import {
+  DEFAULT_DATE_FORMAT,
+  analyzeDateFormat,
+  formatDate,
+  normalizeDateForFormat,
+  normalizeDateValue,
+  parseDate,
+  parseDateInput,
+  resolveDateSegment,
+  stepDateSegment,
+} from './date-utils'
+import type { DatePickerProps } from './types'
+
+/**
+ * 日期选择器 —— 输入框可手输、可点选，支持日期 / 日期时间 / 年月等精度。
+ *
+ * 非法手输不会污染绑定值：失焦时红框提示 1.5 秒并回填已提交值；
+ * 有时间精度时点选只改草稿，点「确定」才提交。
+ */
+defineOptions({ name: 'G3DatePicker' })
+
+const props = withDefaults(defineProps<DatePickerProps>(), {
+  modelValue: null,
+  format: DEFAULT_DATE_FORMAT,
+  valueFormat: '',
+  clearable: true,
+  disabled: false,
+  disabledDate: undefined,
+  timeDefault: '',
+})
+
+const emit = defineEmits<{
+  'update:modelValue': [value: string]
+  change: [value: string]
+}>()
+
+const { b, e, m, is } = useNamespace('date-picker')
+const locale = useLocale()
+
+const panelRef = ref<InstanceType<typeof G3CalendarPanel> | null>(null)
+const inputRef = ref<HTMLInputElement | null>(null)
+
+const config = computed(() => analyzeDateFormat(props.format))
+const valueFormat = computed(() => (props.valueFormat ? props.valueFormat : props.format))
+
+const committed = computed(() => normalizeDateValue(props.modelValue, valueFormat.value))
+const displayText = computed(() => formatDate(committed.value, config.value.primaryFormat))
+
+const editingText = ref<string | null>(null)
+const inputText = computed(() => editingText.value ?? displayText.value)
+
+const open = ref(false)
+const draft = ref<Date | null>(null)
+const invalid = ref(false)
+let invalidTimer: ReturnType<typeof setTimeout> | null = null
+
+const hasValue = computed(() => committed.value !== null)
+const showClear = computed(() => props.clearable && !props.disabled && hasValue.value)
+
+/** 对外输出：先按格式精度归零，再按 valueFormat 格式化 */
+function toOutgoing(date: Date | null): string {
+  if (!date) return ''
+  return formatDate(normalizeDateForFormat(date, config.value) ?? date, valueFormat.value)
+}
+
+function commit(date: Date | null) {
+  const text = toOutgoing(date)
+  if (text === (props.modelValue ?? '')) return
+  emit('update:modelValue', text)
+  emit('change', text)
+}
+
+function markInvalid() {
+  invalid.value = true
+  if (invalidTimer) clearTimeout(invalidTimer)
+  invalidTimer = setTimeout(() => {
+    invalid.value = false
+  }, 1500)
+}
+
+/** 提交手输文本；返回 false 表示非法（调用方据此决定是否保留编辑态） */
+function submitInputText(): boolean {
+  if (editingText.value === null) return true
+  const text = editingText.value
+  editingText.value = null
+  const result = parseDateInput(text, props.format)
+  if (result.isEmpty) {
+    commit(null)
+    return true
+  }
+  if (!result.isValid || !result.date) {
+    markInvalid()
+    return false
+  }
+  commit(result.date)
+  return true
+}
+
+function onFocus() {
+  editingText.value = displayText.value
+}
+
+function onInput(event: Event) {
+  editingText.value = (event.target as HTMLInputElement).value
+}
+
+function onBlur(event: FocusEvent) {
+  // 焦点落回面板内（点选日期）时不提交，交给 pick / confirm
+  const related = event.relatedTarget as HTMLElement | null
+  if (related?.closest('.g3-popover__popup')) {
+    editingText.value = null
+    return
+  }
+  submitInputText()
+}
+
+function toggle() {
+  if (props.disabled) return
+  open.value = !open.value
+}
+
+function clearValue() {
+  editingText.value = null
+  draft.value = null
+  commit(null)
+}
+
+/** ↑↓ 微调光标所在的时间 / 日期段 */
+function stepSegment(delta: number, event: KeyboardEvent) {
+  const target = event.target as HTMLInputElement
+  const text = inputText.value
+  const caret = target.selectionStart ?? text.length
+  const segment = resolveDateSegment(text, caret, config.value.primaryFormat)
+  if (!segment) return
+  const baseDate = parseDate(text, props.format) ?? committed.value ?? new Date()
+  const next = stepDateSegment(baseDate, segment.field, delta)
+  if (!next) return
+  editingText.value = formatDate(next, config.value.primaryFormat)
+  nextTick(() => {
+    const segments = inputText.value
+    const position = segments.length
+    target.setSelectionRange(position, position)
+  })
+}
+
+function onKeydown(event: KeyboardEvent) {
+  if (event.key === 'Escape') {
+    editingText.value = null
+    open.value = false
+    return
+  }
+  if (event.key === 'Enter') {
+    // 阻止表单隐式提交
+    event.preventDefault()
+    // 非法输入保持编辑态（不关面板）：关闭面板会把 invalid 清掉，用户根本看不到红框提示
+    if (submitInputText()) open.value = false
+    return
+  }
+  if (event.altKey && event.key === 'ArrowDown') {
+    event.preventDefault()
+    open.value = true
+    panelRef.value?.focusActive()
+    return
+  }
+  if (!event.ctrlKey && !event.metaKey && (event.key === 'ArrowUp' || event.key === 'ArrowDown')) {
+    event.preventDefault()
+    stepSegment(event.key === 'ArrowUp' ? -1 : 1, event)
+  }
+}
+
+function onClick() {
+  if (props.disabled) return
+  open.value = true
+  nextTick(() => inputRef.value?.focus({ preventScroll: true }))
+}
+
+function onPick(date: Date) {
+  draft.value = date
+  if (!config.value.hasTime) {
+    commit(date)
+    open.value = false
+  }
+}
+
+function onConfirm() {
+  commit(draft.value)
+  open.value = false
+}
+
+watch(open, (value) => {
+  if (value) draft.value = committed.value
+  else {
+    editingText.value = null
+    invalid.value = false
+  }
+})
+</script>
+
+<template>
+  <div :class="[b(), { [is('disabled')]: disabled, [is('open')]: open, [is('invalid')]: invalid }]">
+    <G3Popover
+      :open="open"
+      trigger="manual"
+      placement="bottom-start"
+      :arrow="false"
+      :offset="8"
+      :disabled="disabled"
+      :content-class="e('panel')"
+      unwrapped
+      @update:open="open = $event"
+    >
+      <template #trigger>
+        <span :class="e('trigger')" @click="onClick">
+          <input
+            ref="inputRef"
+            :class="e('input')"
+            type="text"
+            :disabled="disabled"
+            :value="inputText"
+            :placeholder="locale.date.placeholder"
+            :aria-label="locale.date.placeholder"
+            aria-haspopup="dialog"
+            :aria-expanded="open"
+            :aria-invalid="invalid || undefined"
+            autocomplete="off"
+            spellcheck="false"
+            @input="onInput"
+            @focus="onFocus"
+            @blur="onBlur"
+            @keydown="onKeydown"
+          />
+          <button
+            v-if="showClear"
+            type="button"
+            :class="e('clear')"
+            :aria-label="locale.common.clear"
+            @click.stop="clearValue"
+          >
+            <X />
+          </button>
+        </span>
+      </template>
+
+      <template #content>
+        <G3CalendarPanel
+          ref="panelRef"
+          type="date"
+          :model-value="draft"
+          :time-default="timeDefault"
+          :picker-config="config"
+          :disabled-date="disabledDate"
+          @pick="onPick"
+          @confirm="onConfirm"
+        />
+      </template>
+    </G3Popover>
+  </div>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+.#{b('date-picker')} {
+  position: relative;
+  display: inline-block;
+  width: 100%;
+}
+
+.#{e('date-picker', 'trigger')} {
+  display: inline-flex;
+  align-items: center;
+  gap: v('space-1', 4px);
+  box-sizing: border-box;
+  width: 100%;
+  min-height: v('control-height', 32px);
+  padding: 0 v('space-2', 8px);
+  border: 1px solid v('border-color', #d9d9d9);
+  border-radius: v('radius', 6px);
+  background: v('bg-container', #fff);
+  color: v('text-1', rgba(0, 0, 0, 0.88));
+  font-size: v('font-size', 14px);
+  transition:
+    border-color v('duration', 0.2s) v('ease', ease),
+    box-shadow v('duration', 0.2s) v('ease', ease);
+}
+
+.#{e('date-picker', 'trigger')}:hover {
+  border-color: v('color-primary', #18181b);
+}
+
+.#{b('date-picker')}.#{is('open')} .#{e('date-picker', 'trigger')} {
+  border-color: v('color-primary', #18181b);
+  box-shadow: 0 0 0 2px v('color-primary-ring', rgba(24, 24, 27, 0.2));
+}
+
+.#{b('date-picker')}.#{is('invalid')} .#{e('date-picker', 'trigger')} {
+  border-color: v('color-danger', #ec4246);
+}
+
+.#{b('date-picker')}.#{is('disabled')} .#{e('date-picker', 'trigger')} {
+  background: v('bg-disabled', rgba(0, 0, 0, 0.04));
+  cursor: not-allowed;
+}
+
+.#{e('date-picker', 'input')} {
+  flex: 1;
+  min-width: 0;
+  padding: 0;
+  border: 0;
+  outline: none;
+  background: transparent;
+  color: inherit;
+  font: inherit;
+
+  &::placeholder {
+    color: v('text-3', rgba(0, 0, 0, 0.45));
+  }
+}
+
+.#{e('date-picker', 'clear')} {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  width: 16px;
+  height: 16px;
+  padding: 0;
+  border: 0;
+  border-radius: 50%;
+  background: transparent;
+  color: v('text-3', rgba(0, 0, 0, 0.45));
+  cursor: pointer;
+
+  svg {
+    width: 12px;
+    height: 12px;
+  }
+
+  &:hover {
+    color: v('text-1', rgba(0, 0, 0, 0.88));
+  }
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/date/RangePicker.vue b/code/g3soft-libs/packages/ui/src/date/RangePicker.vue
new file mode 100644
index 00000000..2c88e8e9
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/date/RangePicker.vue
@@ -0,0 +1,372 @@
+<script setup lang="ts">
+import { computed, nextTick, ref, watch } from 'vue'
+import { X } from '@lucide/vue'
+import { useLocale } from '../_composables/useLocale'
+import { useNamespace } from '../_composables/useNamespace'
+import G3Popover from '../popover/Popover.vue'
+import G3CalendarPanel from './CalendarPanel.vue'
+import {
+  DEFAULT_DATE_FORMAT,
+  analyzeDateFormat,
+  compareDate,
+  formatDate,
+  normalizeDateForFormat,
+  normalizeDateValue,
+  parseDateInput,
+} from './date-utils'
+import type { RangePickerProps } from './types'
+
+/**
+ * 日期范围选择器 —— 两次点击确定起止，单端可先提交。
+ *
+ * 两端都可就地手输（非法输入红框提示并回填）；只填一端时提交为 [start, '']。
+ * 有时间精度时点选只改草稿，点「确定」才提交。
+ */
+defineOptions({ name: 'G3RangePicker' })
+
+const props = withDefaults(defineProps<RangePickerProps>(), {
+  modelValue: null,
+  format: DEFAULT_DATE_FORMAT,
+  valueFormat: '',
+  clearable: true,
+  disabled: false,
+  disabledDate: undefined,
+})
+
+const emit = defineEmits<{
+  'update:modelValue': [value: string[]]
+  change: [value: string[]]
+}>()
+
+const { b, e, m, is } = useNamespace('range-picker')
+const locale = useLocale()
+
+const panelRef = ref<InstanceType<typeof G3CalendarPanel> | null>(null)
+const startInputRef = ref<HTMLInputElement | null>(null)
+const endInputRef = ref<HTMLInputElement | null>(null)
+
+const config = computed(() => analyzeDateFormat(props.format))
+const valueFormat = computed(() => (props.valueFormat ? props.valueFormat : props.format))
+
+const committed = computed<[Date | null, Date | null]>(() => {
+  const value = props.modelValue
+  if (!Array.isArray(value)) return [null, null]
+  return [normalizeDateValue(value[0], valueFormat.value), normalizeDateValue(value[1], valueFormat.value)]
+})
+
+const draft = ref<{ start: Date | null; end: Date | null }>({ start: null, end: null })
+const hoverValue = ref<Date | null>(null)
+const open = ref(false)
+const invalidSide = ref<'' | 'start' | 'end'>('')
+const editing = ref<{ start: string | null; end: string | null }>({ start: null, end: null })
+let invalidTimer: ReturnType<typeof setTimeout> | null = null
+
+const startText = computed(
+  () => editing.value.start ?? formatDate(draft.value.start ?? committed.value[0], config.value.primaryFormat),
+)
+const endText = computed(
+  () => editing.value.end ?? formatDate(draft.value.end ?? committed.value[1], config.value.primaryFormat),
+)
+
+const hasValue = computed(() => committed.value[0] !== null || committed.value[1] !== null)
+const showClear = computed(() => props.clearable && !props.disabled && hasValue.value)
+
+function toOutgoing(date: Date | null): string {
+  if (!date) return ''
+  return formatDate(normalizeDateForFormat(date, config.value) ?? date, valueFormat.value)
+}
+
+function commit(start: Date | null, end: Date | null) {
+  const next = [toOutgoing(start), toOutgoing(end)]
+  const current = Array.isArray(props.modelValue) ? props.modelValue : ['', '']
+  if (next[0] === (current[0] ?? '') && next[1] === (current[1] ?? '')) return
+  emit('update:modelValue', next)
+  emit('change', next)
+}
+
+function markInvalid(side: 'start' | 'end') {
+  invalidSide.value = side
+  if (invalidTimer) clearTimeout(invalidTimer)
+  invalidTimer = setTimeout(() => {
+    invalidSide.value = ''
+  }, 1500)
+}
+
+function toggle() {
+  if (props.disabled) return
+  open.value = !open.value
+}
+
+function clearValue() {
+  editing.value = { start: null, end: null }
+  draft.value = { start: null, end: null }
+  hoverValue.value = null
+  commit(null, null)
+}
+
+/* ---------- 面板交互 ---------- */
+function orderDraft() {
+  const start = draft.value.start
+  const end = draft.value.end
+  if (start && end && compareDate(start, end) > 0) draft.value = { start: end, end: start }
+}
+
+function onPick(date: Date) {
+  if (!draft.value.start || draft.value.end) {
+    draft.value = { start: date, end: null }
+    hoverValue.value = null
+    return
+  }
+  draft.value = { start: draft.value.start, end: date }
+  orderDraft()
+  if (!config.value.hasTime) {
+    commit(draft.value.start, draft.value.end)
+    open.value = false
+  }
+}
+
+function onHover(date: Date | null) {
+  hoverValue.value = date
+}
+
+function onConfirm() {
+  orderDraft()
+  commit(draft.value.start, draft.value.end)
+  open.value = false
+}
+
+/* ---------- 手输提交 ---------- */
+function submitSide(side: 'start' | 'end') {
+  const text = editing.value[side]
+  if (text === null) return
+  editing.value[side] = null
+  const result = parseDateInput(text, props.format)
+  if (!result.isValid) {
+    markInvalid(side)
+    return
+  }
+  draft.value = { ...draft.value, [side]: result.date }
+  orderDraft()
+  if (draft.value.start || draft.value.end) commit(draft.value.start, draft.value.end)
+}
+
+function onBlur(side: 'start' | 'end', event: FocusEvent) {
+  const related = event.relatedTarget as HTMLElement | null
+  if (related?.closest('.g3-popover__popup')) {
+    editing.value[side] = null
+    return
+  }
+  submitSide(side)
+}
+
+function onKeydown(side: 'start' | 'end', event: KeyboardEvent) {
+  if (event.key === 'Escape') {
+    editing.value[side] = null
+    open.value = false
+    return
+  }
+  if (event.key === 'Enter') {
+    event.preventDefault()
+    submitSide(side)
+    open.value = false
+    return
+  }
+  if (event.altKey && event.key === 'ArrowDown') {
+    event.preventDefault()
+    open.value = true
+    panelRef.value?.focusActive()
+  }
+}
+
+function onClickInput(side: 'start' | 'end') {
+  if (props.disabled) return
+  open.value = true
+  nextTick(() => {
+    const target = side === 'start' ? startInputRef.value : endInputRef.value
+    target?.focus({ preventScroll: true })
+  })
+}
+
+watch(open, (value) => {
+  if (value) {
+    draft.value = { start: committed.value[0], end: committed.value[1] }
+    hoverValue.value = null
+  } else {
+    editing.value = { start: null, end: null }
+    invalidSide.value = ''
+  }
+})
+</script>
+
+<template>
+  <div :class="[b(), { [is('disabled')]: disabled, [is('open')]: open }]">
+    <G3Popover
+      :open="open"
+      trigger="manual"
+      placement="bottom-start"
+      :arrow="false"
+      :offset="8"
+      :disabled="disabled"
+      :content-class="e('panel')"
+      unwrapped
+      @update:open="open = $event"
+    >
+      <template #trigger>
+        <span :class="e('trigger')">
+          <input
+            ref="startInputRef"
+            :class="[e('input'), { [is('input-invalid')]: invalidSide === 'start' }]"
+            type="text"
+            :disabled="disabled"
+            :value="startText"
+            :placeholder="locale.date.startPlaceholder"
+            :aria-label="locale.date.startPlaceholder"
+            aria-haspopup="dialog"
+            :aria-expanded="open"
+            autocomplete="off"
+            spellcheck="false"
+            @input="editing.start = ($event.target as HTMLInputElement).value"
+            @focus="editing.start = startText"
+            @blur="onBlur('start', $event)"
+            @keydown="onKeydown('start', $event)"
+            @click="onClickInput('start')"
+          />
+          <span :class="e('separator')" aria-hidden="true">~</span>
+          <input
+            ref="endInputRef"
+            :class="[e('input'), { [is('input-invalid')]: invalidSide === 'end' }]"
+            type="text"
+            :disabled="disabled"
+            :value="endText"
+            :placeholder="locale.date.endPlaceholder"
+            :aria-label="locale.date.endPlaceholder"
+            aria-haspopup="dialog"
+            :aria-expanded="open"
+            autocomplete="off"
+            spellcheck="false"
+            @input="editing.end = ($event.target as HTMLInputElement).value"
+            @focus="editing.end = endText"
+            @blur="onBlur('end', $event)"
+            @keydown="onKeydown('end', $event)"
+            @click="onClickInput('end')"
+          />
+          <button
+            v-if="showClear"
+            type="button"
+            :class="e('clear')"
+            :aria-label="locale.common.clear"
+            @click.stop="clearValue"
+          >
+            <X />
+          </button>
+        </span>
+      </template>
+
+      <template #content>
+        <G3CalendarPanel
+          ref="panelRef"
+          type="range"
+          :start="draft.start"
+          :end="draft.end"
+          :hover-value="hoverValue"
+          :picker-config="config"
+          :disabled-date="disabledDate"
+          @pick="onPick"
+          @hover="onHover"
+          @confirm="onConfirm"
+        />
+      </template>
+    </G3Popover>
+  </div>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+.#{b('range-picker')} {
+  position: relative;
+  display: inline-block;
+  width: 100%;
+}
+
+.#{e('range-picker', 'trigger')} {
+  display: inline-flex;
+  align-items: center;
+  gap: v('space-1', 4px);
+  box-sizing: border-box;
+  width: 100%;
+  min-height: v('control-height', 32px);
+  padding: 0 v('space-2', 8px);
+  border: 1px solid v('border-color', #d9d9d9);
+  border-radius: v('radius', 6px);
+  background: v('bg-container', #fff);
+  color: v('text-1', rgba(0, 0, 0, 0.88));
+  font-size: v('font-size', 14px);
+  transition:
+    border-color v('duration', 0.2s) v('ease', ease),
+    box-shadow v('duration', 0.2s) v('ease', ease);
+}
+
+.#{e('range-picker', 'trigger')}:hover {
+  border-color: v('color-primary', #18181b);
+}
+
+.#{b('range-picker')}.#{is('open')} .#{e('range-picker', 'trigger')} {
+  border-color: v('color-primary', #18181b);
+  box-shadow: 0 0 0 2px v('color-primary-ring', rgba(24, 24, 27, 0.2));
+}
+
+.#{b('range-picker')}.#{is('disabled')} .#{e('range-picker', 'trigger')} {
+  background: v('bg-disabled', rgba(0, 0, 0, 0.04));
+  cursor: not-allowed;
+}
+
+.#{e('range-picker', 'input')} {
+  flex: 1;
+  min-width: 0;
+  padding: 0;
+  border: 0;
+  outline: none;
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  text-align: center;
+
+  &::placeholder {
+    color: v('text-3', rgba(0, 0, 0, 0.45));
+  }
+}
+
+.#{e('range-picker', 'input')}.#{is('input-invalid')} {
+  color: v('color-danger', #ec4246);
+}
+
+.#{e('range-picker', 'separator')} {
+  flex-shrink: 0;
+  color: v('text-3', rgba(0, 0, 0, 0.45));
+}
+
+.#{e('range-picker', 'clear')} {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  width: 16px;
+  height: 16px;
+  padding: 0;
+  border: 0;
+  border-radius: 50%;
+  background: transparent;
+  color: v('text-3', rgba(0, 0, 0, 0.45));
+  cursor: pointer;
+
+  svg {
+    width: 12px;
+    height: 12px;
+  }
+
+  &:hover {
+    color: v('text-1', rgba(0, 0, 0, 0.88));
+  }
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/date/TimeSelect.vue b/code/g3soft-libs/packages/ui/src/date/TimeSelect.vue
new file mode 100644
index 00000000..b49b2c0b
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/date/TimeSelect.vue
@@ -0,0 +1,242 @@
+<script setup lang="ts">
+import { computed, nextTick, onMounted, ref, useId, watch } from 'vue'
+import { useNamespace } from '../_composables/useNamespace'
+import type { TimeField, TimeSelectProps } from './types'
+
+/**
+ * 时间选择列 —— 时 / 分 / 秒的滚动列表，支持 12 小时制与上下午列。
+ *
+ * 键盘：↑↓ 步进 1、PageUp/PageDown 步进 5、Home/End 跳首尾（均不回绕）。
+ */
+defineOptions({ name: 'G3TimeSelect' })
+
+const props = withDefaults(defineProps<TimeSelectProps>(), {
+  modelValue: null,
+  fields: () => ['hour', 'minute', 'second'],
+  hour12: false,
+  lowerMeridiem: false,
+  disabled: false,
+})
+
+const emit = defineEmits<{ 'update:modelValue': [value: Date] }>()
+
+const { b, e, m, is } = useNamespace('time-select')
+const baseId = useId()
+const columnRefs = ref<Record<string, HTMLElement | null>>({})
+
+interface Column {
+  key: TimeField | 'meridiem'
+  label: string
+  values: Array<number | string>
+}
+
+const columns = computed<Column[]>(() => {
+  const list: Column[] = []
+  for (const field of props.fields) {
+    if (field === 'hour') {
+      list.push({
+        key: 'hour',
+        label: '时',
+        values: props.hour12
+          ? Array.from({ length: 12 }, (_, index) => index + 1)
+          : Array.from({ length: 24 }, (_, index) => index),
+      })
+      if (props.hour12) {
+        list.push({ key: 'meridiem', label: '上下午', values: ['am', 'pm'] })
+      }
+      continue
+    }
+    if (field === 'minute') {
+      list.push({ key: 'minute', label: '分', values: Array.from({ length: 60 }, (_, index) => index) })
+      continue
+    }
+    list.push({ key: 'second', label: '秒', values: Array.from({ length: 60 }, (_, index) => index) })
+  }
+  return list
+})
+
+const base = computed(() => props.modelValue ?? new Date())
+
+function activeValue(column: Column): number | string {
+  const date = base.value
+  if (column.key === 'meridiem') return date.getHours() < 12 ? 'am' : 'pm'
+  if (column.key === 'hour' && props.hour12) return date.getHours() % 12 || 12
+  if (column.key === 'hour') return date.getHours()
+  if (column.key === 'minute') return date.getMinutes()
+  return date.getSeconds()
+}
+
+function optionLabel(value: number | string): string {
+  if (typeof value === 'string') return props.lowerMeridiem ? value : value.toUpperCase()
+  return String(value).padStart(2, '0')
+}
+
+function emitWith(next: Date) {
+  emit('update:modelValue', next)
+}
+
+function setPart(column: Column, value: number | string) {
+  if (props.disabled) return
+  const next = new Date(base.value.getTime())
+  if (column.key === 'meridiem') next.setHours((next.getHours() + 12) % 24)
+  else if (column.key === 'hour' && props.hour12) {
+    const hour = Number(value) % 12
+    next.setHours(next.getHours() >= 12 ? hour + 12 : hour)
+  } else {
+    next.setHours(
+      column.key === 'hour' ? Number(value) : next.getHours(),
+      column.key === 'minute' ? Number(value) : next.getMinutes(),
+      column.key === 'second' ? Number(value) : next.getSeconds(),
+      0,
+    )
+  }
+  emitWith(next)
+}
+
+function step(column: Column, delta: number, event: KeyboardEvent) {
+  if (props.disabled) return
+  event.preventDefault()
+  const values = column.values
+  const current = activeValue(column)
+  const index = values.findIndex((value) => value === current)
+  const nextIndex = Math.min(Math.max((index === -1 ? 0 : index) + delta, 0), values.length - 1)
+  setPart(column, values[nextIndex])
+}
+
+function onKeydown(column: Column, event: KeyboardEvent) {
+  switch (event.key) {
+    case 'ArrowUp':
+      step(column, -1, event)
+      break
+    case 'ArrowDown':
+      step(column, 1, event)
+      break
+    case 'PageUp':
+      step(column, -5, event)
+      break
+    case 'PageDown':
+      step(column, 5, event)
+      break
+    case 'Home':
+      step(column, -column.values.length, event)
+      break
+    case 'End':
+      step(column, column.values.length, event)
+      break
+  }
+}
+
+/** 把当前选中项滚到可视区中间 */
+function scrollActiveIntoView() {
+  for (const column of columns.value) {
+    const list = columnRefs.value[column.key]
+    if (!list) continue
+    const active = list.querySelector<HTMLElement>(`.${is('active')}`)
+    if (!active) continue
+    list.scrollTop = active.offsetTop - (list.clientHeight - active.clientHeight) / 2
+  }
+}
+
+onMounted(() => nextTick(scrollActiveIntoView))
+watch([() => props.modelValue, columns], () => nextTick(scrollActiveIntoView), { flush: 'post' })
+
+function setColumnRef(key: string, el: unknown) {
+  columnRefs.value[key] = (el as HTMLElement | null) ?? null
+}
+</script>
+
+<template>
+  <div :class="[b(), { [is('disabled')]: disabled }]">
+    <div v-for="column in columns" :key="column.key" :class="e('col')">
+      <div
+        :ref="(el) => setColumnRef(column.key, el)"
+        :class="e('list')"
+        role="listbox"
+        :aria-label="column.label"
+        :tabindex="disabled ? -1 : 0"
+        :aria-disabled="disabled || undefined"
+        :aria-activedescendant="`${baseId}-${column.key}-${activeValue(column)}`"
+        @keydown="onKeydown(column, $event)"
+      >
+        <ul role="presentation">
+          <li
+            v-for="value in column.values"
+            :id="`${baseId}-${column.key}-${value}`"
+            :key="String(value)"
+            :class="[e('item'), { [is('active')]: value === activeValue(column) }]"
+            role="option"
+            :aria-selected="value === activeValue(column)"
+            @click="setPart(column, value)"
+          >
+            {{ optionLabel(value) }}
+          </li>
+        </ul>
+      </div>
+    </div>
+  </div>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+/* 时 / 分 / 秒三列并排：整块高度由使用方决定（日历面板里与日历区同高），
+   每列定宽 56px，列与列之间只用一条分隔线 —— 不做成三个各自带边框的独立列表框 */
+.#{b('time-select')} {
+  display: flex;
+  align-items: stretch;
+  height: v('time-select-height', 196px);
+}
+
+.#{e('time-select', 'col')} {
+  flex: 0 0 auto;
+  display: flex;
+  flex-direction: column;
+  width: v('time-col-width', 56px);
+}
+
+.#{e('time-select', 'col')} + .#{e('time-select', 'col')} {
+  border-left: 1px solid v('border-color', #d9d9d9);
+}
+
+.#{e('time-select', 'list')} {
+  flex: 1 1 auto;
+  min-height: 0;
+  overflow-y: auto;
+  outline: none;
+  scrollbar-width: thin;
+
+  &:focus-visible {
+    @include focus-ring();
+  }
+
+  ul {
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+}
+
+.#{e('time-select', 'item')} {
+  height: v('time-item-height', 28px);
+  line-height: v('time-item-height', 28px);
+  color: v('text-1', rgba(0, 0, 0, 0.88));
+  font-size: v('font-size', 14px);
+  font-variant-numeric: tabular-nums;
+  text-align: center;
+  cursor: pointer;
+}
+
+.#{e('time-select', 'item')}:hover {
+  background: v('fill', rgba(0, 0, 0, 0.04));
+}
+
+.#{e('time-select', 'item')}.#{is('active')} {
+  background: v('color-primary', #18181b);
+  color: v('color-primary-on', #fafafa);
+  font-weight: 500;
+}
+
+.#{b('time-select')}.#{is('disabled')} {
+  opacity: 0.6;
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/date/date-utils.test.ts b/code/g3soft-libs/packages/ui/src/date/date-utils.test.ts
new file mode 100644
index 00000000..8598853f
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/date/date-utils.test.ts
@@ -0,0 +1,344 @@
+import { describe, expect, it } from 'vitest'
+import {
+  addMonth,
+  analyzeDateFormat,
+  canonicalizeDateText,
+  combineDateTime,
+  compareDate,
+  compareDay,
+  endOfDay,
+  formatDate,
+  getDaysInMonth,
+  getMonthMatrix,
+  getMonthRows,
+  isInRange,
+  isSameDay,
+  isSameMonth,
+  normalizeDateForFormat,
+  parseDate,
+  parseDateInput,
+  resolveDateSegment,
+  startOfDay,
+  stepDateSegment,
+  tokenizeDateFormat,
+} from './date-utils'
+
+/** 固定时刻：2026-10-08 09:05:03.123（本地时区，断言与机器时区无关） */
+const SAMPLE = new Date(2026, 9, 8, 9, 5, 3, 123)
+
+describe('tokenizeDateFormat', () => {
+  it('抽出标准 token', () => {
+    expect(tokenizeDateFormat('YYYY-MM-DD HH:mm:ss')).toEqual(['YYYY', 'MM', 'DD', 'HH', 'mm', 'ss'])
+    expect(tokenizeDateFormat('h:mm A')).toEqual(['h', 'mm', 'A'])
+  })
+
+  it('中文字面量被跳过，方括号内容整体忽略', () => {
+    expect(tokenizeDateFormat('YYYY年MM月DD日')).toEqual(['YYYY', 'MM', 'DD'])
+    expect(tokenizeDateFormat('YYYY-MM-DD [HH:mm]')).toEqual(['YYYY', 'MM', 'DD'])
+  })
+})
+
+describe('analyzeDateFormat（格式 → 面板能力）', () => {
+  it('纯日期：只有日期部分、无时间列', () => {
+    const config = analyzeDateFormat('YYYY-MM-DD')
+    expect(config).toMatchObject({
+      primaryFormat: 'YYYY-MM-DD',
+      hasYear: true,
+      hasMonth: true,
+      hasDay: true,
+      hasDateParts: true,
+      hasTime: false,
+      hour12: false,
+      meridiem: false,
+    })
+    expect(config.timeFields).toEqual([])
+  })
+
+  it('日期时间：时间列按 时→分→秒 顺序，秒缺失时不出现', () => {
+    expect(analyzeDateFormat('YYYY-MM-DD HH:mm:ss').timeFields).toEqual(['hour', 'minute', 'second'])
+    expect(analyzeDateFormat('YYYY-MM-DD HH:mm').timeFields).toEqual(['hour', 'minute'])
+    expect(analyzeDateFormat('YYYY-MM-DD HH').timeFields).toEqual(['hour'])
+    expect(analyzeDateFormat('YYYY-MM-DD HH:mm').hasSecond).toBe(false)
+  })
+
+  it('12 小时制与上下午标记', () => {
+    expect(analyzeDateFormat('YYYY-MM-DD hh:mm A')).toMatchObject({
+      hour12: true,
+      meridiem: true,
+      lowerMeridiem: false,
+    })
+    expect(analyzeDateFormat('YYYY-MM-DD hh:mm a')).toMatchObject({
+      hour12: true,
+      meridiem: true,
+      lowerMeridiem: true,
+    })
+  })
+
+  it('纯时间格式：没有日期部分', () => {
+    expect(analyzeDateFormat('HH:mm')).toMatchObject({
+      hasDateParts: false,
+      hasTime: true,
+      timeFields: ['hour', 'minute'],
+    })
+  })
+
+  it('精度只到月 / 年', () => {
+    expect(analyzeDateFormat('YYYY-MM')).toMatchObject({ hasMonth: true, hasDay: false })
+    expect(analyzeDateFormat('YYYY')).toMatchObject({ hasMonth: false, hasDay: false, hasYear: true })
+  })
+
+  it('数组格式取第一个；纯星期 / 字面量回退到默认日期格式', () => {
+    expect(analyzeDateFormat(['YYYY-MM-DD', 'YYYY-MM-DD HH:mm']).hasTime).toBe(false)
+    expect(analyzeDateFormat('dddd')).toMatchObject({ primaryFormat: 'YYYY-MM-DD', hasDay: true })
+    expect(analyzeDateFormat('[第]YYYY[年]')).toMatchObject({ hasYear: true })
+  })
+
+  it('空 / 非法输入回退默认', () => {
+    expect(analyzeDateFormat(undefined).primaryFormat).toBe('YYYY-MM-DD')
+    expect(analyzeDateFormat('').primaryFormat).toBe('YYYY-MM-DD')
+  })
+})
+
+describe('formatDate', () => {
+  it('补零输出，字面量原样保留', () => {
+    expect(formatDate(SAMPLE, 'YYYY-MM-DD HH:mm:ss')).toBe('2026-10-08 09:05:03')
+    expect(formatDate(SAMPLE, 'YYYY年MM月DD日')).toBe('2026年10月08日')
+    expect(formatDate(SAMPLE, '[今天是]YYYY/MM/DD')).toBe('今天是2026/10/08')
+    expect(formatDate(SAMPLE, 'YY-M-D H:m:s')).toBe('26-10-8 9:5:3')
+  })
+
+  it('可接受 Date / 时间戳 / 可解析字符串', () => {
+    expect(formatDate(SAMPLE.getTime(), 'YYYY-MM-DD')).toBe('2026-10-08')
+  })
+
+  it('空值与非法值输出空串', () => {
+    expect(formatDate(null, 'YYYY-MM-DD')).toBe('')
+    expect(formatDate(undefined, 'YYYY-MM-DD')).toBe('')
+    expect(formatDate('', 'YYYY-MM-DD')).toBe('')
+    expect(formatDate('不是日期', 'YYYY-MM-DD')).toBe('')
+  })
+})
+
+describe('parseDate（严格解析 + 容错）', () => {
+  it('严格匹配格式', () => {
+    const parsed = parseDate('2026-10-08', 'YYYY-MM-DD')
+    expect(parsed).not.toBeNull()
+    expect(formatDate(parsed, 'YYYY-MM-DD HH:mm:ss')).toBe('2026-10-08 00:00:00')
+  })
+
+  it('斜杠 / 点号 / 中文分隔符可被规范化后解析', () => {
+    expect(formatDate(parseDate('2026/10/08', 'YYYY-MM-DD'), 'YYYY-MM-DD')).toBe('2026-10-08')
+    expect(formatDate(parseDate('2026.10.08', 'YYYY-MM-DD'), 'YYYY-MM-DD')).toBe('2026-10-08')
+    expect(formatDate(parseDate('2026年10月08日', 'YYYY-MM-DD'), 'YYYY-MM-DD')).toBe('2026-10-08')
+  })
+
+  it('越界段值判为非法（月 13 / 小时 25）', () => {
+    expect(parseDate('2026-13-01', 'YYYY-MM-DD')).toBeNull()
+    expect(parseDate('2026-10-08 25:00', 'YYYY-MM-DD HH:mm')).toBeNull()
+    expect(parseDate('2026-10-08 10:70', 'YYYY-MM-DD HH:mm')).toBeNull()
+  })
+
+  it('日期溢出判为非法（2 月 30 日不顺延）', () => {
+    expect(parseDate('2026-02-30', 'YYYY-MM-DD')).toBeNull()
+    expect(parseDate('2024-02-29', 'YYYY-MM-DD')).not.toBeNull()
+    expect(parseDate('2026-02-29', 'YYYY-MM-DD')).toBeNull()
+  })
+
+  it('空值返回 null，Date / 数字原样对待', () => {
+    expect(parseDate('', 'YYYY-MM-DD')).toBeNull()
+    expect(parseDate(null, 'YYYY-MM-DD')).toBeNull()
+    expect(parseDate(SAMPLE, 'YYYY-MM-DD')?.getTime()).toBe(SAMPLE.getTime())
+    expect(parseDate(SAMPLE.getTime(), 'YYYY-MM-DD')?.getTime()).toBe(SAMPLE.getTime())
+  })
+})
+
+describe('parseDateInput（输入框手输）', () => {
+  it('空文本是「清空」而不是错误', () => {
+    expect(parseDateInput('', 'YYYY-MM-DD')).toEqual({ date: null, isEmpty: true, isValid: true })
+    expect(parseDateInput('   ', 'YYYY-MM-DD')).toEqual({ date: null, isEmpty: true, isValid: true })
+  })
+
+  it('完全不含数字判为非法', () => {
+    const result = parseDateInput('abc', 'YYYY-MM-DD')
+    expect(result.isEmpty).toBe(false)
+    expect(result.isValid).toBe(false)
+    expect(result.date).toBeNull()
+  })
+
+  it('合法文本返回解析结果', () => {
+    const result = parseDateInput('2026-10-08', 'YYYY-MM-DD')
+    expect(result.isEmpty).toBe(false)
+    expect(result.isValid).toBe(true)
+    expect(formatDate(result.date, 'YYYY-MM-DD')).toBe('2026-10-08')
+  })
+
+  it('越界文本仍未非法', () => {
+    expect(parseDateInput('2026-13-40', 'YYYY-MM-DD').isValid).toBe(false)
+  })
+})
+
+describe('canonicalizeDateText', () => {
+  it('中文 / 斜杠 / 点号统一成横线并压缩空白', () => {
+    expect(canonicalizeDateText('2026年10月08日')).toBe('2026-10-08')
+    expect(canonicalizeDateText('2026/10/08')).toBe('2026-10-08')
+    expect(canonicalizeDateText('2026.10.08')).toBe('2026-10-08')
+    expect(canonicalizeDateText('  2026-10-08  ')).toBe('2026-10-08')
+  })
+})
+
+describe('normalizeDateForFormat（低精度字段归零）', () => {
+  it('精度只到月：日归 1 号、时间归零', () => {
+    expect(formatDate(normalizeDateForFormat(SAMPLE, 'YYYY-MM'), 'YYYY-MM-DD HH:mm:ss')).toBe(
+      '2026-10-01 00:00:00',
+    )
+  })
+
+  it('精度只到年：月 / 日 / 时间全部归零', () => {
+    expect(formatDate(normalizeDateForFormat(SAMPLE, 'YYYY'), 'YYYY-MM-DD HH:mm:ss')).toBe(
+      '2026-01-01 00:00:00',
+    )
+  })
+
+  it('精度到分：保留时分，秒归零', () => {
+    expect(formatDate(normalizeDateForFormat(SAMPLE, 'YYYY-MM-DD HH:mm'), 'HH:mm:ss')).toBe(
+      '09:05:00',
+    )
+  })
+
+  it('接受 analyzeDateFormat 的结果，空值返回 null', () => {
+    expect(formatDate(normalizeDateForFormat(SAMPLE, analyzeDateFormat('YYYY-MM')), 'YYYY-MM-DD')).toBe(
+      '2026-10-01',
+    )
+    expect(normalizeDateForFormat(null, 'YYYY')).toBeNull()
+  })
+})
+
+describe('stepDateSegment（键盘微调）', () => {
+  it('月段按月末夹取，不溢出到下个月', () => {
+    expect(formatDate(stepDateSegment(new Date(2026, 0, 31), 'month', 1), 'YYYY-MM-DD')).toBe(
+      '2026-02-28',
+    )
+    expect(formatDate(stepDateSegment(new Date(2026, 2, 31), 'month', -1), 'YYYY-MM-DD')).toBe(
+      '2026-02-28',
+    )
+  })
+
+  it('日段在当月内夹取，不跨月', () => {
+    expect(formatDate(stepDateSegment(new Date(2026, 0, 31), 'day', 1), 'YYYY-MM-DD')).toBe(
+      '2026-01-31',
+    )
+    expect(formatDate(stepDateSegment(new Date(2026, 0, 1), 'day', -1), 'YYYY-MM-DD')).toBe(
+      '2026-01-01',
+    )
+    expect(formatDate(stepDateSegment(new Date(2026, 0, 15), 'day', 1), 'YYYY-MM-DD')).toBe(
+      '2026-01-16',
+    )
+  })
+
+  it('时 / 分 / 秒回绕且不进位', () => {
+    expect(formatDate(stepDateSegment(new Date(2026, 0, 1, 23, 59, 59), 'hour', 1), 'YYYY-MM-DD HH:mm:ss')).toBe(
+      '2026-01-01 00:59:59',
+    )
+    expect(formatDate(stepDateSegment(new Date(2026, 0, 1, 23, 59, 59), 'minute', 1), 'YYYY-MM-DD HH:mm:ss')).toBe(
+      '2026-01-01 23:00:59',
+    )
+    expect(formatDate(stepDateSegment(new Date(2026, 0, 1, 23, 59, 59), 'second', 1), 'YYYY-MM-DD HH:mm:ss')).toBe(
+      '2026-01-01 23:59:00',
+    )
+  })
+
+  it('年段直接加减，上下午段翻 12 小时', () => {
+    expect(formatDate(stepDateSegment(SAMPLE, 'year', 1), 'YYYY')).toBe('2027')
+    expect(formatDate(stepDateSegment(new Date(2026, 0, 1, 8), 'meridiem', 1), 'HH')).toBe('20')
+    expect(formatDate(stepDateSegment(new Date(2026, 0, 1, 20), 'meridiem', 1), 'HH')).toBe('08')
+  })
+
+  it('空值返回 null', () => {
+    expect(stepDateSegment(null, 'day', 1)).toBeNull()
+  })
+})
+
+describe('resolveDateSegment（光标定位到段）', () => {
+  it('按 token 列出字符区间', () => {
+    expect(resolveDateSegment('2026-10-08', 0, 'YYYY-MM-DD')).toMatchObject({ field: 'year' })
+    expect(resolveDateSegment('2026-10-08', 5, 'YYYY-MM-DD')).toMatchObject({ field: 'month' })
+    expect(resolveDateSegment('2026-10-08', 9, 'YYYY-MM-DD')).toMatchObject({ field: 'day' })
+  })
+
+  it('停在分隔符上归左段，越界归最后一段', () => {
+    expect(resolveDateSegment('2026-10-08', 4, 'YYYY-MM-DD')).toMatchObject({ field: 'year' })
+    expect(resolveDateSegment('2026-10-08', 99, 'YYYY-MM-DD')).toMatchObject({ field: 'day' })
+  })
+
+  it('文本与格式不匹配时返回 null', () => {
+    expect(resolveDateSegment('随便写', 0, 'YYYY-MM-DD')).toBeNull()
+  })
+})
+
+describe('日粒度工具', () => {
+  it('startOfDay / endOfDay', () => {
+    expect(formatDate(startOfDay(SAMPLE), 'YYYY-MM-DD HH:mm:ss.SSS')).toBe('2026-10-08 00:00:00.000')
+    expect(formatDate(endOfDay(SAMPLE), 'YYYY-MM-DD HH:mm:ss.SSS')).toBe('2026-10-08 23:59:59.999')
+    expect(startOfDay(null)).toBeNull()
+  })
+
+  it('isSameDay / isSameMonth 忽略时间与日', () => {
+    expect(isSameDay(SAMPLE, new Date(2026, 9, 8, 23, 0))).toBe(true)
+    expect(isSameDay(SAMPLE, new Date(2026, 9, 9))).toBe(false)
+    expect(isSameMonth(SAMPLE, new Date(2026, 9, 31))).toBe(true)
+    expect(isSameMonth(SAMPLE, new Date(2026, 8, 30))).toBe(false)
+    expect(isSameDay(null, SAMPLE)).toBe(false)
+  })
+
+  it('compareDay 按天比、compareDate 按时刻比', () => {
+    expect(compareDay(SAMPLE, new Date(2026, 9, 8, 23, 59))).toBe(0)
+    expect(compareDay(SAMPLE, new Date(2026, 9, 9))).toBe(-1)
+    expect(compareDay(new Date(2026, 9, 9), SAMPLE)).toBe(1)
+    expect(compareDate(SAMPLE, new Date(2026, 9, 8, 9, 5, 4))).toBe(-1)
+    expect(compareDay(null, SAMPLE)).toBe(0)
+  })
+
+  it('addMonth 按月末夹取', () => {
+    expect(formatDate(addMonth(new Date(2026, 0, 31), 1), 'YYYY-MM-DD')).toBe('2026-02-28')
+    expect(formatDate(addMonth(new Date(2026, 9, 8), -1), 'YYYY-MM-DD')).toBe('2026-09-08')
+    expect(formatDate(addMonth(new Date(2026, 9, 8), 12), 'YYYY-MM-DD')).toBe('2027-10-08')
+  })
+
+  it('isInRange 闭区间且入参顺序可颠倒', () => {
+    const start = new Date(2026, 9, 1)
+    const end = new Date(2026, 9, 10)
+    expect(isInRange(new Date(2026, 9, 1), start, end)).toBe(true)
+    expect(isInRange(new Date(2026, 9, 10, 23, 59), start, end)).toBe(true)
+    expect(isInRange(new Date(2026, 9, 11), start, end)).toBe(false)
+    expect(isInRange(new Date(2026, 9, 5), end, start)).toBe(true)
+    expect(isInRange(null, start, end)).toBe(false)
+  })
+
+  it('combineDateTime 取日期的日子 + 时间的时刻，毫秒归零', () => {
+    const combined = combineDateTime(new Date(2026, 9, 8), new Date(2000, 0, 1, 13, 20, 30, 999))
+    expect(formatDate(combined, 'YYYY-MM-DD HH:mm:ss.SSS')).toBe('2026-10-08 13:20:30.000')
+    expect(formatDate(combineDateTime(new Date(2026, 9, 8)), 'HH:mm:ss')).toBe('00:00:00')
+  })
+
+  it('getDaysInMonth 处理闰年', () => {
+    expect(getDaysInMonth(2026, 1)).toBe(28)
+    expect(getDaysInMonth(2024, 1)).toBe(29)
+    expect(getDaysInMonth(2026, 0)).toBe(31)
+    expect(getDaysInMonth(2026, 3)).toBe(30)
+  })
+
+  it('getMonthMatrix 是 42 格，首格为当月 1 号所在周的周日', () => {
+    // 2026-10-01 是周四 → 首格应是 2026-09-27（周日）
+    const cells = getMonthMatrix(2026, 9)
+    expect(cells).toHaveLength(42)
+    expect(formatDate(cells[0], 'YYYY-MM-DD')).toBe('2026-09-27')
+    expect(cells[0].getDay()).toBe(0)
+  })
+
+  it('getMonthRows 切成 6 行 × 7 列', () => {
+    const rows = getMonthRows(2026, 9)
+    expect(rows).toHaveLength(6)
+    rows.forEach((row) => expect(row).toHaveLength(7))
+    expect(formatDate(rows[0][0], 'YYYY-MM-DD')).toBe('2026-09-27')
+  })
+})
diff --git a/code/g3soft-libs/packages/ui/src/date/date-utils.ts b/code/g3soft-libs/packages/ui/src/date/date-utils.ts
new file mode 100644
index 00000000..08f54a90
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/date/date-utils.ts
@@ -0,0 +1,764 @@
+/**
+ * 日期工具（零依赖实现，替代 dayjs）。
+ *
+ * 约定：内部一律用 Date 运算，对外由组件决定字符串格式；
+ * 所有函数对非法输入都返回 null / false，不抛异常。
+ */
+
+export const DEFAULT_FORMAT = 'YYYY-MM-DD HH:mm:ss'
+export const DEFAULT_DATE_FORMAT = 'YYYY-MM-DD'
+
+/** 英文月份 / 星期名（与 dayjs 默认一致，仅用于 MMM / MMMM / dddd 这类文案 token） */
+const MONTH_NAMES = [
+  'January',
+  'February',
+  'March',
+  'April',
+  'May',
+  'June',
+  'July',
+  'August',
+  'September',
+  'October',
+  'November',
+  'December',
+]
+const MONTH_NAMES_SHORT = MONTH_NAMES.map((name) => name.slice(0, 3))
+const WEEKDAY_NAMES = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday']
+const WEEKDAY_NAMES_SHORT = WEEKDAY_NAMES.map((name) => name.slice(0, 3))
+
+const pad = (value: number, length = 2) => String(Math.abs(value)).padStart(length, '0')
+
+/* ---------------- 格式规范化 ---------------- */
+
+export type DateFormatInput = string | string[] | undefined
+
+/** 归一成字符串数组；数组里非字符串 / 空串会被过滤，全空时回退 fallback */
+export function normalizeFormats(format: DateFormatInput, fallback = DEFAULT_DATE_FORMAT): string[] {
+  if (Array.isArray(format)) {
+    const list = format.filter((item): item is string => typeof item === 'string' && item !== '')
+    return list.length ? list : [fallback]
+  }
+  if (typeof format === 'string' && format !== '') return [format]
+  return [fallback]
+}
+
+export function hasFormat(format: DateFormatInput): boolean {
+  return normalizeFormats(format).length > 0
+}
+
+export function getPrimaryFormat(format: DateFormatInput, fallback = DEFAULT_DATE_FORMAT): string {
+  return normalizeFormats(format, fallback)[0]
+}
+
+/** 支持的 token，按长度优先匹配 */
+const FORMAT_TOKENS = [
+  'YYYY',
+  'MMMM',
+  'dddd',
+  'MMM',
+  'ddd',
+  'SSS',
+  'YY',
+  'MM',
+  'DD',
+  'Do',
+  'dd',
+  'HH',
+  'hh',
+  'mm',
+  'ss',
+  'ZZ',
+  'M',
+  'D',
+  'd',
+  'H',
+  'h',
+  'm',
+  's',
+  'Z',
+  'A',
+  'a',
+]
+
+/** 拆出格式中的 token 序列（不含字面量），`[..]` 内视为普通文本 */
+export function tokenizeDateFormat(format: string): string[] {
+  const tokens: string[] = []
+  let index = 0
+  while (index < format.length) {
+    const char = format[index]
+    if (char === '[') {
+      const end = format.indexOf(']', index)
+      index = end === -1 ? format.length : end + 1
+      continue
+    }
+    const matched = FORMAT_TOKENS.find((token) => format.startsWith(token, index))
+    if (matched) {
+      tokens.push(matched)
+      index += matched.length
+      continue
+    }
+    index += 1
+  }
+  return tokens
+}
+
+export interface DateFormatConfig {
+  primaryFormat: string
+  tokens: string[]
+  hasYear: boolean
+  hasMonth: boolean
+  hasDay: boolean
+  hasDateParts: boolean
+  hasHour: boolean
+  hasMinute: boolean
+  hasSecond: boolean
+  hasMillisecond: boolean
+  hasTime: boolean
+  timeFields: Array<'hour' | 'minute' | 'second'>
+  hour12: boolean
+  meridiem: boolean
+  lowerMeridiem: boolean
+}
+
+/** 分析格式：决定面板精度、时间列、12 小时制等 */
+export function analyzeDateFormat(format: DateFormatInput): DateFormatConfig {
+  const primaryFormat = getPrimaryFormat(format)
+  const tokens = tokenizeDateFormat(primaryFormat)
+  const hasYear = tokens.includes('YYYY') || tokens.includes('YY')
+  const hasMonth = tokens.includes('MM') || tokens.includes('M') || tokens.includes('MMM') || tokens.includes('MMMM')
+  const hasDay = tokens.includes('DD') || tokens.includes('D') || tokens.includes('Do')
+  const hasDateParts = hasYear || hasMonth || hasDay
+  const hasHour = tokens.includes('HH') || tokens.includes('H') || tokens.includes('hh') || tokens.includes('h')
+  const hasMinute = tokens.includes('mm') || tokens.includes('m')
+  const hasSecond = tokens.includes('ss') || tokens.includes('s')
+  const hasMillisecond = tokens.includes('SSS')
+  const hasTime = hasHour || hasMinute || hasSecond || hasMillisecond
+  const hour12 = tokens.includes('hh') || tokens.includes('h')
+  const meridiem = tokens.includes('A') || tokens.includes('a')
+  const lowerMeridiem = tokens.includes('a')
+
+  // 年 / 月 / 日与时间字段全无（纯星期、时区、字面量）时回退到默认格式
+  if (!hasDateParts && !hasTime) return analyzeDateFormat(DEFAULT_DATE_FORMAT)
+
+  const timeFields: Array<'hour' | 'minute' | 'second'> = []
+  if (hasHour) timeFields.push('hour')
+  if (hasMinute) timeFields.push('minute')
+  if (hasSecond) timeFields.push('second')
+
+  return {
+    primaryFormat,
+    tokens,
+    hasYear,
+    hasMonth,
+    hasDay,
+    hasDateParts,
+    hasHour,
+    hasMinute,
+    hasSecond,
+    hasMillisecond,
+    hasTime,
+    timeFields,
+    hour12,
+    meridiem,
+    lowerMeridiem,
+  }
+}
+
+/* ---------------- 格式化 ---------------- */
+
+const toDate = (value: Date | number | string | null | undefined): Date | null => {
+  if (value == null || value === '') return null
+  const date = value instanceof Date ? value : new Date(value)
+  return Number.isNaN(date.getTime()) ? null : date
+}
+
+/** 按格式输出字符串；两个参数顺序与 formatDate(date, format) 一致 */
+export function formatDate(value: Date | number | string | null | undefined, format: DateFormatInput = DEFAULT_FORMAT): string {
+  const date = toDate(value)
+  if (!date) return ''
+  const pattern = getPrimaryFormat(format)
+  let output = ''
+  let index = 0
+  while (index < pattern.length) {
+    const char = pattern[index]
+    if (char === '[') {
+      const end = pattern.indexOf(']', index)
+      if (end === -1) break
+      output += pattern.slice(index + 1, end)
+      index = end + 1
+      continue
+    }
+    const token = FORMAT_TOKENS.find((item) => pattern.startsWith(item, index))
+    if (!token) {
+      output += char
+      index += 1
+      continue
+    }
+    index += token.length
+    const hours24 = date.getHours()
+    switch (token) {
+      case 'YYYY':
+        output += String(date.getFullYear())
+        break
+      case 'YY':
+        output += pad(date.getFullYear() % 100)
+        break
+      case 'MMMM':
+        output += MONTH_NAMES[date.getMonth()]
+        break
+      case 'MMM':
+        output += MONTH_NAMES_SHORT[date.getMonth()]
+        break
+      case 'MM':
+        output += pad(date.getMonth() + 1)
+        break
+      case 'M':
+        output += String(date.getMonth() + 1)
+        break
+      case 'DD':
+        output += pad(date.getDate())
+        break
+      case 'D':
+        output += String(date.getDate())
+        break
+      case 'Do':
+        output += `${date.getDate()}${ordinalSuffix(date.getDate())}`
+        break
+      case 'dddd':
+        output += WEEKDAY_NAMES[date.getDay()]
+        break
+      case 'ddd':
+        output += WEEKDAY_NAMES_SHORT[date.getDay()]
+        break
+      case 'dd':
+        output += pad(date.getDay())
+        break
+      case 'd':
+        output += String(date.getDay())
+        break
+      case 'HH':
+        output += pad(hours24)
+        break
+      case 'H':
+        output += String(hours24)
+        break
+      case 'hh':
+        output += pad(hours24 % 12 || 12)
+        break
+      case 'h':
+        output += String(hours24 % 12 || 12)
+        break
+      case 'mm':
+        output += pad(date.getMinutes())
+        break
+      case 'm':
+        output += String(date.getMinutes())
+        break
+      case 'ss':
+        output += pad(date.getSeconds())
+        break
+      case 's':
+        output += String(date.getSeconds())
+        break
+      case 'SSS':
+        output += pad(date.getMilliseconds(), 3)
+        break
+      case 'A':
+        output += hours24 < 12 ? 'AM' : 'PM'
+        break
+      case 'a':
+        output += hours24 < 12 ? 'am' : 'pm'
+        break
+      case 'Z':
+      case 'ZZ': {
+        const offset = -date.getTimezoneOffset()
+        const sign = offset >= 0 ? '+' : '-'
+        const text = `${sign}${pad(Math.floor(Math.abs(offset) / 60))}:${pad(Math.abs(offset) % 60)}`
+        output += token === 'Z' ? text : text.replace(':', '')
+        break
+      }
+    }
+  }
+  return output
+}
+
+function ordinalSuffix(day: number): string {
+  if (day % 100 >= 11 && day % 100 <= 13) return 'th'
+  if (day % 10 === 1) return 'st'
+  if (day % 10 === 2) return 'nd'
+  if (day % 10 === 3) return 'rd'
+  return 'th'
+}
+
+/* ---------------- 解析 ---------------- */
+
+const SEGMENT_PATTERNS: Record<string, string> = {
+  YYYY: '\\d{4}',
+  YY: '\\d{1,2}',
+  MMMM: '[A-Za-z]+',
+  MMM: '[A-Za-z]+',
+  MM: '\\d{1,2}',
+  M: '\\d{1,2}',
+  DD: '\\d{1,2}',
+  D: '\\d{1,2}',
+  Do: '\\d{1,2}(?:st|nd|rd|th)?',
+  HH: '\\d{1,2}',
+  H: '\\d{1,2}',
+  hh: '\\d{1,2}',
+  h: '\\d{1,2}',
+  mm: '\\d{1,2}',
+  m: '\\d{1,2}',
+  ss: '\\d{1,2}',
+  s: '\\d{1,2}',
+  SSS: '\\d{1,3}',
+  A: '[AaPp][Mm]',
+  a: '[AaPp][Mm]',
+}
+
+const FIELD_BY_TOKEN: Record<string, string> = {
+  YYYY: 'year',
+  YY: 'year',
+  MM: 'month',
+  M: 'month',
+  MMM: 'month',
+  MMMM: 'month',
+  DD: 'day',
+  D: 'day',
+  Do: 'day',
+  HH: 'hour',
+  H: 'hour',
+  hh: 'hour',
+  h: 'hour',
+  mm: 'minute',
+  m: 'minute',
+  ss: 'second',
+  s: 'second',
+  SSS: 'millisecond',
+  A: 'meridiem',
+  a: 'meridiem',
+}
+
+interface CompiledFormat {
+  regex: RegExp
+  tokens: string[]
+  /** 每个捕获组对应的 token（不含不产生段的 token） */
+  tokenByGroup: string[]
+}
+
+const formatCache = new Map<string, CompiledFormat>()
+
+/** 把格式编译成解析用正则；不产生段的 token（dddd/dd/d 等）只做跳读 */
+function compileFormat(format: string): CompiledFormat {
+  const cached = formatCache.get(format)
+  if (cached) return cached
+  const tokens = tokenizeDateFormat(format)
+  let pattern = '^'
+  const segmentTokens: string[] = []
+  let index = 0
+  while (index < format.length) {
+    const char = format[index]
+    if (char === '[') {
+      const end = format.indexOf(']', index)
+      const literal = end === -1 ? format.slice(index + 1) : format.slice(index + 1, end)
+      pattern += literal.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+      index = end === -1 ? format.length : end + 1
+      continue
+    }
+    const token = tokens.find((item) => format.startsWith(item, index))
+    if (!token) {
+      pattern += '[^0-9A-Za-z]*'
+      index += 1
+      continue
+    }
+    index += token.length
+    const segment = SEGMENT_PATTERNS[token]
+    if (segment) {
+      pattern += `(${segment})`
+      segmentTokens.push(token)
+    } else {
+      pattern += '[^0-9A-Za-z]*'
+    }
+  }
+  // 末尾字面量可选（允许省略「日」这类后缀）
+  pattern += '$'
+  const compiled: CompiledFormat = {
+    regex: new RegExp(pattern),
+    tokens: segmentTokens,
+    tokenByGroup: segmentTokens,
+  }
+  formatCache.set(format, compiled)
+  return compiled
+}
+
+/**
+ * 形状像日期的文本（年-月-日 / 年-月）。
+ *
+ * 用于阻止末位的原生解析把越界日期「救活」：`new Date('2026-02-30')` 会静默顺延成 3 月 2 日，
+ * 绕过 matchFormat 里的值域与溢出校验，这类文本必须直接判非法。
+ */
+const DATE_LIKE_TEXT = /^\s*\d{1,4}\s*[-/.年]\s*\d{1,2}\s*(?:[-/.月]\s*\d{1,2})?/
+
+/** 宽松解析：逐格式严格匹配，失败后按规范化文本再试，最后退到原生解析 */
+export function parseDate(
+  value: string | number | Date | null | undefined,
+  format: DateFormatInput = DEFAULT_FORMAT,
+): Date | null {
+  if (value == null || value === '') return null
+  if (value instanceof Date || typeof value === 'number') return toDate(value)
+  const text = String(value).trim()
+  if (!text) return null
+
+  for (const candidate of normalizeFormats(format)) {
+    const strict = matchFormat(text, candidate)
+    if (strict) return strict
+  }
+  for (const candidate of normalizeFormats(format)) {
+    const normalized = canonicalizeDateText(text)
+    const loose = matchFormat(normalized, candidate)
+    if (loose) return loose
+  }
+  // 类日期文本判非法（见 DATE_LIKE_TEXT 注释）；其余交给原生解析兜底（ISO / RFC 等）
+  if (DATE_LIKE_TEXT.test(text)) return null
+  return toDate(text)
+}
+
+/** 用编译后的正则抽取各字段并组装成 Date */
+function matchFormat(text: string, format: string): Date | null {
+  const compiled = compileFormat(format)
+  const matched = compiled.regex.exec(text)
+  if (!matched) return null
+  const now = new Date()
+  const parts: Record<string, number | undefined> = {}
+  compiled.tokenByGroup.forEach((token, groupIndex) => {
+    const raw = matched[groupIndex + 1]
+    if (raw == null) return
+    const field = FIELD_BY_TOKEN[token]
+    if (!field) return
+    if (field === 'month' && (token === 'MMM' || token === 'MMMM')) {
+      const lower = raw.toLowerCase()
+      const monthIndex = MONTH_NAMES.findIndex(
+        (name) => name.toLowerCase() === lower || name.slice(0, 3).toLowerCase() === lower,
+      )
+      parts.month = monthIndex === -1 ? undefined : monthIndex + 1
+      return
+    }
+    if (field === 'meridiem') {
+      parts.meridiem = raw.toLowerCase().startsWith('p') ? 1 : 0
+      return
+    }
+    parts[field] = Number.parseInt(raw, 10)
+  })
+
+  // 值域检查：超出范围直接判为非法，避免静默顺延
+  if (parts.month !== undefined && (parts.month < 1 || parts.month > 12)) return null
+  if (parts.day !== undefined && (parts.day < 1 || parts.day > 31)) return null
+  if (parts.hour !== undefined && (parts.hour < 0 || parts.hour > 23)) return null
+  if (parts.minute !== undefined && (parts.minute < 0 || parts.minute > 59)) return null
+  if (parts.second !== undefined && (parts.second < 0 || parts.second > 59)) return null
+
+  let year = parts.year ?? now.getFullYear()
+  if (parts.year !== undefined && parts.year < 100) year += 2000
+  const month = (parts.month ?? 1) - 1
+  const day = parts.day ?? 1
+  let hour = parts.hour ?? 0
+  if (parts.meridiem !== undefined) hour = (hour % 12) + parts.meridiem * 12
+  const date = new Date(
+    year,
+    month,
+    day,
+    hour,
+    parts.minute ?? 0,
+    parts.second ?? 0,
+    parts.millisecond ?? 0,
+  )
+  if (Number.isNaN(date.getTime())) return null
+  // 溢出校验（如 2 月 30 日会被顺延）：日期字段与实际不符即非法
+  if (parts.day !== undefined && date.getDate() !== day) return null
+  if (parts.month !== undefined && date.getMonth() !== month) return null
+  return date
+}
+
+/** 文本规范化：中文 / 斜杠 / 点号统一成标准分隔符 */
+export function canonicalizeDateText(text: string): string {
+  return text
+    .trim()
+    .replace(/年|月/g, '-')
+    .replace(/日/g, ' ')
+    .replace(/[./]/g, '-')
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+
+export interface DateInputParseResult {
+  date: Date | null
+  isEmpty: boolean
+  isValid: boolean
+}
+
+/** 手输文本解析：空串视为「清空」而非错误 */
+export function parseDateInput(
+  text: string,
+  format: DateFormatInput,
+): DateInputParseResult {
+  const trimmed = (text ?? '').trim()
+  if (!trimmed) return { date: null, isEmpty: true, isValid: true }
+  if (!/\d/.test(trimmed)) return { date: null, isEmpty: false, isValid: false }
+  const parsed =
+    parseDate(trimmed, format) ?? parseDate(canonicalizeDateText(trimmed), format) ?? null
+  return { date: parsed, isEmpty: false, isValid: parsed !== null }
+}
+
+/* ---------------- 可编辑段定位（输入框键盘微调） ---------------- */
+
+export interface DateSegment {
+  field: string
+  /** 段起始索引（含） */
+  start: number
+  /** 段结束索引（不含） */
+  end: number
+}
+
+/** 列出文本中可编辑 token 的字符区间 */
+export function listDateSegments(text: string, format: string): DateSegment[] {
+  const compiled = compileFormat(format)
+  const matched = compiled.regex.exec(text)
+  if (!matched) return []
+  const segments: DateSegment[] = []
+  let cursor = 0
+  compiled.tokenByGroup.forEach((token, groupIndex) => {
+    const raw = matched[groupIndex + 1]
+    if (raw == null) return
+    const start = matched[0].indexOf(raw, cursor)
+    if (start === -1) return
+    const field = FIELD_BY_TOKEN[token]
+    if (field) segments.push({ field, start, end: start + raw.length })
+    cursor = start + raw.length
+  })
+  return segments
+}
+
+/** 定位光标所在的段（停在分隔符上归左段，末尾归最后一段） */
+export function resolveDateSegment(
+  text: string,
+  caret: number,
+  format: string,
+): DateSegment | null {
+  const segments = listDateSegments(text, format)
+  if (!segments.length) return null
+  const position = Math.min(Math.max(caret, 0), text.length)
+  const found = segments.find((segment) => position >= segment.start && position <= segment.end)
+  return found ?? segments[segments.length - 1]
+}
+
+const WRAP_SIZES: Record<string, number> = { hour: 24, minute: 60, second: 60 }
+
+/** 微调某一段：年/月/日走设值器（月末夹取），时/分/秒回绕不进位，上下午翻 12 小时 */
+export function stepDateSegment(
+  value: Date | null | undefined,
+  field: string,
+  delta = 1,
+): Date | null {
+  const date = toDate(value)
+  if (!date) return null
+  const next = new Date(date.getTime())
+  switch (field) {
+    case 'year':
+      next.setFullYear(date.getFullYear() + delta)
+      return next
+    case 'month': {
+      const month = date.getMonth() + delta
+      next.setDate(1)
+      next.setMonth(month)
+      const lastDay = new Date(next.getFullYear(), next.getMonth() + 1, 0).getDate()
+      next.setDate(Math.min(date.getDate(), lastDay))
+      return next
+    }
+    case 'day': {
+      next.setDate(1)
+      next.setMonth(date.getMonth())
+      const lastDay = new Date(date.getFullYear(), date.getMonth() + 1, 0).getDate()
+      // 夹在当月 [1, lastDay] 内：否则 1 号再往前会跨到上个月末（setDate(0)）
+      next.setDate(Math.min(Math.max(date.getDate() + delta, 1), lastDay))
+      return next
+    }
+    case 'hour':
+      next.setHours((date.getHours() + delta + 24) % 24)
+      return next
+    case 'minute':
+      next.setMinutes((date.getMinutes() + delta + 60) % 60)
+      return next
+    case 'second':
+      next.setSeconds((date.getSeconds() + delta + 60) % 60)
+      return next
+    case 'meridiem':
+      next.setHours((date.getHours() + delta * 12 + 24) % 24)
+      return next
+    default:
+      return next
+  }
+}
+
+export { WRAP_SIZES }
+
+/* ---------------- 值归一 ---------------- */
+
+/** 归一成 Date：字符串按给定格式解析 */
+export function normalizeDateValue(
+  value: Date | string | number | null | undefined,
+  format: DateFormatInput = DEFAULT_FORMAT,
+): Date | null {
+  if (value == null || value === '') return null
+  if (typeof value === 'string') return parseDate(value, format)
+  return toDate(value)
+}
+
+/**
+ * 按格式把「不可选的」低精度字段归零（无月 → 1 月、无日 → 1 号、无时分秒 → 0），
+ * 保证绑定值补位是确定的。
+ */
+export function normalizeDateForFormat(
+  value: Date | null | undefined,
+  format: DateFormatInput | DateFormatConfig,
+): Date | null {
+  const date = toDate(value)
+  if (!date) return null
+  const config = typeof format === 'object' && 'tokens' in format ? format : analyzeDateFormat(format)
+  const next = new Date(date.getTime())
+  if (!config.hasMonth) next.setMonth(0)
+  if (!config.hasDay) next.setDate(1)
+  if (!config.hasHour) next.setHours(0)
+  if (!config.hasMinute) next.setMinutes(0)
+  if (!config.hasSecond) next.setSeconds(0)
+  if (!config.hasMillisecond) next.setMilliseconds(0)
+  return next
+}
+
+/* ---------------- 日粒度工具 ---------------- */
+
+export function startOfDay(value: Date | null | undefined): Date | null {
+  const date = toDate(value)
+  if (!date) return null
+  const next = new Date(date.getTime())
+  next.setHours(0, 0, 0, 0)
+  return next
+}
+
+export function endOfDay(value: Date | null | undefined): Date | null {
+  const date = toDate(value)
+  if (!date) return null
+  const next = new Date(date.getTime())
+  next.setHours(23, 59, 59, 999)
+  return next
+}
+
+export function isSameDay(a: Date | null | undefined, b: Date | null | undefined): boolean {
+  const left = toDate(a)
+  const right = toDate(b)
+  if (!left || !right) return false
+  return (
+    left.getFullYear() === right.getFullYear() &&
+    left.getMonth() === right.getMonth() &&
+    left.getDate() === right.getDate()
+  )
+}
+
+export function isSameMonth(a: Date | null | undefined, b: Date | null | undefined): boolean {
+  const left = toDate(a)
+  const right = toDate(b)
+  if (!left || !right) return false
+  return left.getFullYear() === right.getFullYear() && left.getMonth() === right.getMonth()
+}
+
+export function isToday(value: Date | null | undefined): boolean {
+  return isSameDay(value, new Date())
+}
+
+/** 加 / 减 n 月，非法输入以当前时刻兜底 */
+export function addMonth(value: Date | null | undefined, n: number): Date {
+  const date = toDate(value) ?? new Date()
+  const next = new Date(date.getTime())
+  const targetDay = date.getDate()
+  next.setDate(1)
+  next.setMonth(date.getMonth() + n)
+  const lastDay = new Date(next.getFullYear(), next.getMonth() + 1, 0).getDate()
+  next.setDate(Math.min(targetDay, lastDay))
+  return next
+}
+
+/** 按天比较：-1 / 0 / 1；任一非法返回 0 */
+export function compareDay(a: Date | null | undefined, b: Date | null | undefined): number {
+  const left = startOfDay(a)
+  const right = startOfDay(b)
+  if (!left || !right) return 0
+  const diff = left.getTime() - right.getTime()
+  return diff === 0 ? 0 : diff < 0 ? -1 : 1
+}
+
+/** 按完整时间点比较：-1 / 0 / 1；任一非法返回 0 */
+export function compareDate(a: Date | null | undefined, b: Date | null | undefined): number {
+  const left = toDate(a)
+  const right = toDate(b)
+  if (!left || !right) return 0
+  const diff = left.getTime() - right.getTime()
+  return diff === 0 ? 0 : diff < 0 ? -1 : 1
+}
+
+/** 闭区间按天判断，入参顺序可颠倒 */
+export function isInRange(
+  date: Date | null | undefined,
+  start: Date | null | undefined,
+  end: Date | null | undefined,
+): boolean {
+  const target = startOfDay(date)
+  const left = startOfDay(start)
+  const right = startOfDay(end)
+  if (!target || !left || !right) return false
+  const lo = Math.min(left.getTime(), right.getTime())
+  const hi = Math.max(left.getTime(), right.getTime())
+  return target.getTime() >= lo && target.getTime() <= hi
+}
+
+/** 日期部分取 date，时间部分取 time；秒与毫秒按 time 对齐（毫秒固定 0） */
+export function combineDateTime(
+  date: Date | null | undefined,
+  time?: Date | null | undefined,
+): Date {
+  const base = toDate(date) ?? new Date()
+  const clock = toDate(time)
+  const next = new Date(base.getTime())
+  next.setHours(
+    clock ? clock.getHours() : 0,
+    clock ? clock.getMinutes() : 0,
+    clock ? clock.getSeconds() : 0,
+    0,
+  )
+  return next
+}
+
+/** 42 格（6×7）月历矩阵，索引 0 为当月 1 号所在周的周日 */
+export function getMonthMatrix(viewYear: number, viewMonth: number): Date[] {
+  const first = new Date(viewYear, viewMonth, 1)
+  const start = new Date(first.getTime())
+  start.setDate(1 - first.getDay())
+  const cells: Date[] = []
+  for (let index = 0; index < 42; index++) {
+    const cell = new Date(start.getTime())
+    cell.setDate(start.getDate() + index)
+    cells.push(cell)
+  }
+  return cells
+}
+
+/** 42 格按周切 6 行 */
+export function getMonthRows(viewYear: number, viewMonth: number): Date[][] {
+  const cells = getMonthMatrix(viewYear, viewMonth)
+  const rows: Date[][] = []
+  for (let index = 0; index < 6; index++) rows.push(cells.slice(index * 7, index * 7 + 7))
+  return rows
+}
+
+/** 该月的天数 */
+export function getDaysInMonth(year: number, month: number): number {
+  return new Date(year, month + 1, 0).getDate()
+}
diff --git a/code/g3soft-libs/packages/ui/src/date/index.ts b/code/g3soft-libs/packages/ui/src/date/index.ts
new file mode 100644
index 00000000..ebb36f70
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/date/index.ts
@@ -0,0 +1,46 @@
+export { default as G3DatePicker } from './DatePicker.vue'
+export { default as G3RangePicker } from './RangePicker.vue'
+export { default as G3TimeSelect } from './TimeSelect.vue'
+export { default as G3CalendarPanel } from './CalendarPanel.vue'
+export {
+  addMonth,
+  analyzeDateFormat,
+  canonicalizeDateText,
+  combineDateTime,
+  compareDate,
+  compareDay,
+  DEFAULT_DATE_FORMAT,
+  DEFAULT_FORMAT,
+  endOfDay,
+  formatDate,
+  getDaysInMonth,
+  getMonthMatrix,
+  getMonthRows,
+  getPrimaryFormat,
+  hasFormat,
+  isInRange,
+  isSameDay,
+  isSameMonth,
+  isToday,
+  listDateSegments,
+  normalizeDateForFormat,
+  normalizeDateValue,
+  normalizeFormats,
+  parseDate,
+  parseDateInput,
+  resolveDateSegment,
+  startOfDay,
+  stepDateSegment,
+  tokenizeDateFormat,
+} from './date-utils'
+export type { DateFormatConfig, DateFormatInput, DateInputParseResult, DateSegment } from './date-utils'
+export type {
+  CalendarMode,
+  CalendarPanelProps,
+  DateTimeDefault,
+  DatePickerProps,
+  DateValue,
+  RangePickerProps,
+  TimeField,
+  TimeSelectProps,
+} from './types'
diff --git a/code/g3soft-libs/packages/ui/src/date/types.ts b/code/g3soft-libs/packages/ui/src/date/types.ts
new file mode 100644
index 00000000..5d60a4a8
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/date/types.ts
@@ -0,0 +1,77 @@
+import type { DateFormatConfig } from './date-utils'
+
+/** 无值时的默认时间：start 当天起 / end 当天末 / 空为当前时刻 */
+export type DateTimeDefault = '' | 'start' | 'end'
+
+/** 时间列字段 */
+export type TimeField = 'hour' | 'minute' | 'second'
+
+/** 日期值：字符串（按 valueFormat 解析）或 Date */
+export type DateValue = string | Date | null | undefined
+
+export interface DatePickerProps {
+  /** 绑定值；字符串按 valueFormat（未设置时跟随 format）严格解析 */
+  modelValue?: DateValue
+  /** 同时决定面板精度与展示格式 */
+  format?: string | string[]
+  /** 绑定值格式；未设置时跟随 format 的首个格式 */
+  valueFormat?: string | string[]
+  /** 显示清除按钮 */
+  clearable?: boolean
+  /** 禁用态 */
+  disabled?: boolean
+  /** 禁用日期判定 */
+  disabledDate?: (date: Date) => boolean
+  /** 无值时的默认时间 */
+  timeDefault?: DateTimeDefault
+}
+
+export interface RangePickerProps {
+  /** 绑定值 [start, end]，元素为字符串（可为空串） */
+  modelValue?: Array<string | Date | null> | null
+  /** 展示格式 */
+  format?: string | string[]
+  /** 绑定值格式；未设置时跟随 format */
+  valueFormat?: string | string[]
+  /** 显示清除按钮 */
+  clearable?: boolean
+  /** 禁用态 */
+  disabled?: boolean
+  /** 禁用日期判定 */
+  disabledDate?: (date: Date) => boolean
+}
+
+export interface TimeSelectProps {
+  /** 当前时间；为空时以当前时刻为基准 */
+  modelValue?: Date | null
+  /** 显示哪几列 */
+  fields?: TimeField[]
+  /** 12 小时制（小时列 1..12，并追加上下午列） */
+  hour12?: boolean
+  /** 上下午显示小写 am / pm */
+  lowerMeridiem?: boolean
+  /** 禁用态 */
+  disabled?: boolean
+}
+
+export interface CalendarPanelProps {
+  /** 面板类型：单选 / 范围 */
+  type?: 'date' | 'range'
+  /** 单选模式的草稿值 */
+  modelValue?: Date | null
+  /** 范围起点草稿 */
+  start?: Date | null
+  /** 范围终点草稿 */
+  end?: Date | null
+  /** 范围预览终点 */
+  hoverValue?: Date | null
+  /** 单选无值时的时间初值 */
+  timeDefault?: DateTimeDefault
+  /** 由 analyzeDateFormat 产出的格式配置 */
+  pickerConfig?: DateFormatConfig
+  /** 禁用日期判定 */
+  disabledDate?: (date: Date) => boolean
+}
+
+/** 年 / 月选择器视图模式 */
+export type CalendarMode = 'date' | 'year' | 'month' | 'time'
diff --git a/code/g3soft-libs/packages/ui/src/drawer/Drawer.vue b/code/g3soft-libs/packages/ui/src/drawer/Drawer.vue
new file mode 100644
index 00000000..0bf26614
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/drawer/Drawer.vue
@@ -0,0 +1,520 @@
+<script setup lang="ts">
+import { computed, nextTick, onBeforeUnmount, ref, useId, watch } from 'vue'
+import { X } from '@lucide/vue'
+import { useLocale } from '../_composables/useLocale'
+import { useNamespace } from '../_composables/useNamespace'
+import { usePopupContainer } from '../_composables/usePopupContainer'
+import { bindResize, type ResizeHandle } from '../_utils/drag'
+import { focusFirst, trapFocus } from '../_utils/focus'
+import { lockScroll, unlockScroll } from '../_utils/scroll'
+import { nextZIndex, releaseZIndex } from '../_utils/z-index'
+import type { DrawerProps } from './types'
+
+/**
+ * 抽屉 —— 从屏幕边缘滑出的面板，支持边缘拖拽调整尺寸。
+ *
+ * 遮罩 / Esc / 关闭按钮统一走 `cancel` 事件；退场动画结束后才解锁滚动并还原焦点。
+ */
+defineOptions({ name: 'G3Drawer' })
+
+const props = withDefaults(defineProps<DrawerProps>(), {
+  open: undefined,
+  defaultOpen: false,
+  title: '',
+  placement: 'right',
+  width: 378,
+  height: 378,
+  mask: true,
+  maskClosable: true,
+  keyboard: true,
+  closable: true,
+  resizable: true,
+  popupContainer: undefined,
+})
+
+const emit = defineEmits<{
+  'update:open': [value: boolean]
+  cancel: []
+  closed: []
+}>()
+
+const { b, e, m } = useNamespace('drawer')
+const locale = useLocale()
+const teleportTo = usePopupContainer(() => props.popupContainer)
+
+const innerOpen = ref(props.defaultOpen)
+const panelRef = ref<HTMLElement | null>(null)
+const resizeRef = ref<HTMLElement | null>(null)
+// 标题与面板的关联 id，useId 保证多实例并存时不冲突
+const titleId = useId()
+// 打开前的活动元素，关闭后还原焦点
+let triggerEl: HTMLElement | null = null
+// 缩放句柄，面板打开期间存在
+let resizeHandle: ResizeHandle | null = null
+// 本实例是否持有 body 滚动锁；解锁挪到退场动画之后，标志位保证只解锁一次
+let scrollLocked = false
+const zIndex = ref(0)
+// 缩放后的尺寸（覆盖 width / height prop）；关闭后重置
+const resizeSize = ref<number | null>(null)
+
+const isOpen = computed({
+  get: () => (props.open !== undefined ? props.open : innerOpen.value),
+  set: (value: boolean) => {
+    if (props.open === undefined) innerOpen.value = value
+    emit('update:open', value)
+  },
+})
+
+const isHorizontal = computed(() => props.placement === 'left' || props.placement === 'right')
+
+// 左右方向用 width，上下方向用 height；数字转 px
+const panelSize = computed(() => {
+  const value = isHorizontal.value ? props.width : props.height
+  return typeof value === 'number' ? `${value}px` : value
+})
+
+const panelStyle = computed(() => {
+  const style: Record<string, string | undefined> = {}
+  const size = resizeSize.value ? `${resizeSize.value}px` : panelSize.value
+  if (isHorizontal.value) style.width = size
+  else style.height = size
+  return style
+})
+
+/**
+ * 遮罩与 wrap 必须各自带同一层级。
+ *
+ * wrap 是 `position: fixed` —— fixed 元素即使 `z-index: auto` 也会自成层叠上下文，
+ * 所以只给内层面板写 z-index 是无效的：面板的层级只在 wrap 内部比较，
+ * wrap 整体仍以 auto 参与 body 的排序，被遮罩（同实例的 3001）压住，
+ * 表现为「遮罩阴影盖在抽屉上面」。
+ */
+const maskStyle = computed(() => ({ zIndex: zIndex.value ? String(zIndex.value) : undefined }))
+const wrapStyle = computed(() => ({ zIndex: zIndex.value ? String(zIndex.value) : undefined }))
+
+/** 缩放手柄方向：left 面板拖右缘、right 拖左缘、top 拖底缘、bottom 拖顶缘 */
+const resizeDirection = computed(() => {
+  switch (props.placement) {
+    case 'left':
+      return 'e'
+    case 'right':
+      return 'w'
+    case 'top':
+      return 's'
+    default:
+      return 'n'
+  }
+})
+
+/* ---------- 公共方法 ---------- */
+function onMaskClick() {
+  if (props.maskClosable) requestClose()
+}
+
+/** 遮罩 / Esc / 关闭按钮统一入口 */
+function requestClose() {
+  emit('cancel')
+  isOpen.value = false
+}
+
+/* ---------- 键盘与焦点 ---------- */
+function onPanelKeydown(event: KeyboardEvent) {
+  if (props.keyboard && event.key === 'Escape') {
+    requestClose()
+    return
+  }
+  if (panelRef.value) trapFocus(event, panelRef.value)
+}
+
+/* ---------- 生命周期：打开 / 关闭时接管焦点与滚动 ---------- */
+watch(
+  isOpen,
+  (value) => {
+    if (value) {
+      triggerEl = document.activeElement as HTMLElement | null
+      if (!zIndex.value) zIndex.value = nextZIndex('modal')
+      lockScroll()
+      scrollLocked = true
+      nextTick(() => {
+        if (!isOpen.value || !panelRef.value) return
+        focusFirst(panelRef.value)
+        panelRef.value.addEventListener('keydown', onPanelKeydown)
+        // 边缘缩放手柄：只改对应轴，不超过视口
+        if (props.resizable) {
+          resizeHandle = bindResize(panelRef.value, resizeRef.value, {
+            direction: resizeDirection.value,
+            maxWidth: window.innerWidth,
+            maxHeight: window.innerHeight,
+            onResize: ({ width, height }) => {
+              resizeSize.value = isHorizontal.value ? width : height
+            },
+          })
+        }
+      })
+    } else {
+      // 只做与动画无关的拆卸；解锁滚动、复位尺寸、还原焦点统一等退场动画结束（见 onAfterLeave）
+      panelRef.value?.removeEventListener('keydown', onPanelKeydown)
+      if (resizeHandle) {
+        resizeHandle.destroy()
+        resizeHandle = null
+      }
+    }
+  },
+  { immediate: true },
+)
+
+/** 退场动画结束后收尾：解锁滚动、复位缩放状态、把焦点还给触发元素 */
+function onAfterLeave() {
+  // 退场途中又被打开：本次退场已作废，不能在这里复位
+  if (isOpen.value) return
+  if (scrollLocked) {
+    unlockScroll()
+    scrollLocked = false
+  }
+  if (zIndex.value) {
+    releaseZIndex(zIndex.value)
+    zIndex.value = 0
+  }
+  resizeSize.value = null
+  if (triggerEl && typeof triggerEl.focus === 'function') triggerEl.focus()
+  triggerEl = null
+  emit('closed')
+}
+
+onBeforeUnmount(() => {
+  panelRef.value?.removeEventListener('keydown', onPanelKeydown)
+  if (resizeHandle) resizeHandle.destroy()
+  // 组件在打开状态下被直接销毁：after-leave 不会触发，这里兜底解锁（标志位防重复）
+  if (scrollLocked) {
+    unlockScroll()
+    scrollLocked = false
+  }
+  if (zIndex.value) {
+    releaseZIndex(zIndex.value)
+    zIndex.value = 0
+  }
+})
+</script>
+
+<template>
+  <Teleport :to="teleportTo">
+    <!-- 遮罩与面板分两个 Transition：遮罩淡入淡出，面板按方向整屏滑入滑出。
+         退场收尾（解锁滚动、还原焦点）挂在面板的 after-leave 上。 -->
+    <Transition name="g3-drawer-mask">
+      <div
+        v-if="isOpen && mask"
+        :class="e('mask')"
+        :style="maskStyle"
+        aria-hidden="true"
+        @click="onMaskClick"
+      ></div>
+    </Transition>
+    <Transition :name="`g3-drawer-${placement}`" @after-leave="onAfterLeave">
+      <div v-if="isOpen" :class="[e('wrap'), m(placement)]" :style="wrapStyle">
+        <section
+          ref="panelRef"
+          :class="b()"
+          role="dialog"
+          aria-modal="true"
+          :aria-label="title ? undefined : '抽屉'"
+          :aria-labelledby="title ? titleId : undefined"
+          tabindex="-1"
+          :style="panelStyle"
+        >
+          <header v-if="title || closable || $slots.extra" :class="e('header')">
+            <div :class="e('header-main')">
+              <p v-if="title" :id="titleId" :class="e('title')">{{ title }}</p>
+              <div v-if="$slots.extra" :class="e('extra')">
+                <slot name="extra" />
+              </div>
+            </div>
+            <button
+              v-if="closable"
+              type="button"
+              :class="e('close')"
+              :aria-label="locale.common.close"
+              @click="requestClose"
+            >
+              <X :size="14" />
+            </button>
+          </header>
+          <div :class="e('body')">
+            <slot />
+          </div>
+          <footer v-if="$slots.footer" :class="e('footer')">
+            <slot name="footer" />
+          </footer>
+          <!-- 边缘缩放手柄：拖动调整面板尺寸 -->
+          <div
+            v-if="resizable"
+            ref="resizeRef"
+            :class="[e('resizer'), e(`resizer-${resizeDirection}`)]"
+            aria-hidden="true"
+          ></div>
+        </section>
+      </div>
+    </Transition>
+  </Teleport>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+.#{e('drawer', 'mask')} {
+  position: fixed;
+  inset: 0;
+  background: v('mask-bg', rgba(0, 0, 0, 0.45));
+}
+
+.#{e('drawer', 'wrap')} {
+  position: fixed;
+  inset: 0;
+  pointer-events: none;
+}
+
+/* ---------- 面板按方向吸附到视口边缘 ----------
+   靠「定边」而不是 flex 对齐：flex 的 justify-content / align-items 各只管一条轴，
+   上下面板在主轴（水平）方向没有约束，会缩到内容宽
+   （表现为「上下方向的抽屉宽度不是 100%」）。定边后左右撑满高度、上下撑满宽度。 */
+.#{m('drawer', 'left')} .#{b('drawer')},
+.#{m('drawer', 'right')} .#{b('drawer')} {
+  top: 0;
+  bottom: 0;
+}
+
+.#{m('drawer', 'top')} .#{b('drawer')},
+.#{m('drawer', 'bottom')} .#{b('drawer')} {
+  left: 0;
+  right: 0;
+}
+
+.#{m('drawer', 'left')} .#{b('drawer')} {
+  left: 0;
+}
+
+.#{m('drawer', 'right')} .#{b('drawer')} {
+  right: 0;
+}
+
+.#{m('drawer', 'top')} .#{b('drawer')} {
+  top: 0;
+}
+
+.#{m('drawer', 'bottom')} .#{b('drawer')} {
+  bottom: 0;
+}
+
+.#{b('drawer')} {
+  position: absolute;
+  display: flex;
+  flex-direction: column;
+  box-sizing: border-box;
+  max-width: 100%;
+  max-height: 100%;
+  /* 显式重置：面板本体是 <section>，宿主页面里任何 `section { margin / padding / border }`
+     都会命中它。实测宿主给 section 加 `margin-bottom: 16px` 后，靠定边撑开的高度
+     被吃掉 16px（720 → 704），表现为「抽屉撑不满」；border 在 border-box 下同样吃高度。
+     组件样式用类选择器（特异性更高）声明这些值，就能盖住宿主的元素选择器。 */
+  margin: 0;
+  padding: 0;
+  border: 0;
+  background: v('bg-container', #fff);
+  /* 投影朝向遮罩一侧：抽屉看起来是「浮」在内容之上的 */
+  box-shadow: v('shadow-popup', 0 6px 16px rgba(0, 0, 0, 0.12));
+  color: v('text-1', rgba(0, 0, 0, 0.88));
+  pointer-events: auto;
+  outline: none;
+}
+
+.#{m('drawer', 'right')} .#{b('drawer')} {
+  box-shadow: v('shadow-drawer', -6px 0 16px rgba(0, 0, 0, 0.12));
+}
+
+.#{m('drawer', 'left')} .#{b('drawer')} {
+  box-shadow: v('shadow-drawer', 6px 0 16px rgba(0, 0, 0, 0.12));
+}
+
+.#{m('drawer', 'top')} .#{b('drawer')} {
+  box-shadow: v('shadow-drawer', 0 6px 16px rgba(0, 0, 0, 0.12));
+}
+
+.#{m('drawer', 'bottom')} .#{b('drawer')} {
+  box-shadow: v('shadow-drawer', 0 -6px 16px rgba(0, 0, 0, 0.12));
+}
+
+.#{e('drawer', 'header')} {
+  display: flex;
+  align-items: center;
+  gap: v('space-2', 8px);
+  /* 同上：这里是 <header>，宿主的 `header { margin / padding / border }` 会命中 */
+  margin: 0;
+  padding: v('space-3', 12px) v('space-5', 24px);
+  border: 0;
+  border-bottom: 1px solid v('border-color', #d9d9d9);
+}
+
+.#{e('drawer', 'header-main')} {
+  flex: 1;
+  min-width: 0;
+}
+
+.#{e('drawer', 'title')} {
+  margin: 0;
+  overflow: hidden;
+  font-size: v('font-size-lg', 16px);
+  font-weight: 600;
+  line-height: v('line-height', 1.5);
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.#{e('drawer', 'extra')} {
+  margin-top: v('space-1', 4px);
+}
+
+.#{e('drawer', 'close')} {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  width: 24px;
+  height: 24px;
+  padding: 0;
+  border: 0;
+  border-radius: v('radius-sm', 4px);
+  background: transparent;
+  color: v('text-2', rgba(0, 0, 0, 0.65));
+  cursor: pointer;
+
+  &:hover {
+    background: v('fill', rgba(0, 0, 0, 0.04));
+    color: v('text-1', rgba(0, 0, 0, 0.88));
+  }
+
+  &:focus-visible {
+    @include focus-ring();
+  }
+}
+
+.#{e('drawer', 'body')} {
+  flex: 1;
+  min-height: 0;
+  padding: v('space-3', 12px) v('space-5', 24px);
+  overflow: auto;
+}
+
+.#{e('drawer', 'footer')} {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  gap: v('space-2', 8px);
+  /* 同上：这里是 <footer>，宿主的 `footer { margin / padding / border }` 会命中 */
+  margin: 0;
+  padding: v('space-2', 8px) v('space-5', 24px);
+  border: 0;
+  border-top: 1px solid v('border-color', #d9d9d9);
+}
+
+.#{e('drawer', 'resizer')} {
+  position: absolute;
+  z-index: 1;
+  touch-action: none;
+}
+
+.#{e('drawer', 'resizer-e')} {
+  top: 0;
+  right: -3px;
+  width: 6px;
+  height: 100%;
+  cursor: ew-resize;
+}
+
+.#{e('drawer', 'resizer-w')} {
+  top: 0;
+  left: -3px;
+  width: 6px;
+  height: 100%;
+  cursor: ew-resize;
+}
+
+.#{e('drawer', 'resizer-s')} {
+  bottom: -3px;
+  left: 0;
+  width: 100%;
+  height: 6px;
+  cursor: ns-resize;
+}
+
+.#{e('drawer', 'resizer-n')} {
+  top: -3px;
+  left: 0;
+  width: 100%;
+  height: 6px;
+  cursor: ns-resize;
+}
+
+.#{e('drawer', 'resizer')}:hover,
+.#{e('drawer', 'resizer')}.is-resizing {
+  background: v('color-primary-soft', rgba(24, 24, 27, 0.12));
+}
+
+/* ---------- 进出场 ---------- */
+.g3-drawer-mask-enter-active,
+.g3-drawer-mask-leave-active {
+  transition: opacity v('duration-slow', 0.3s) v('ease', ease);
+}
+
+.g3-drawer-mask-enter-from,
+.g3-drawer-mask-leave-to {
+  opacity: 0;
+}
+
+.g3-drawer-right-enter-active,
+.g3-drawer-left-enter-active,
+.g3-drawer-top-enter-active,
+.g3-drawer-bottom-enter-active {
+  transition: transform v('duration-slow', 0.3s) v('ease', ease);
+}
+
+.g3-drawer-right-leave-active,
+.g3-drawer-left-leave-active,
+.g3-drawer-top-leave-active,
+.g3-drawer-bottom-leave-active {
+  transition: transform v('duration', 0.2s) v('ease', ease);
+}
+
+.g3-drawer-right-enter-from,
+.g3-drawer-right-leave-to {
+  transform: translateX(100%);
+}
+
+.g3-drawer-left-enter-from,
+.g3-drawer-left-leave-to {
+  transform: translateX(-100%);
+}
+
+.g3-drawer-top-enter-from,
+.g3-drawer-top-leave-to {
+  transform: translateY(-100%);
+}
+
+.g3-drawer-bottom-enter-from,
+.g3-drawer-bottom-leave-to {
+  transform: translateY(100%);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .g3-drawer-mask-enter-active,
+  .g3-drawer-mask-leave-active,
+  .g3-drawer-right-enter-active,
+  .g3-drawer-right-leave-active,
+  .g3-drawer-left-enter-active,
+  .g3-drawer-left-leave-active,
+  .g3-drawer-top-enter-active,
+  .g3-drawer-top-leave-active,
+  .g3-drawer-bottom-enter-active,
+  .g3-drawer-bottom-leave-active {
+    transition-duration: 0ms;
+  }
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/drawer/index.ts b/code/g3soft-libs/packages/ui/src/drawer/index.ts
new file mode 100644
index 00000000..0375456e
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/drawer/index.ts
@@ -0,0 +1,2 @@
+export { default as G3Drawer } from './Drawer.vue'
+export type { DrawerPlacement, DrawerProps } from './types'
diff --git a/code/g3soft-libs/packages/ui/src/drawer/types.ts b/code/g3soft-libs/packages/ui/src/drawer/types.ts
new file mode 100644
index 00000000..2b7ccfb8
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/drawer/types.ts
@@ -0,0 +1,31 @@
+import type { PopupContainer } from '../_utils/global-config'
+
+/** 滑出方向 */
+export type DrawerPlacement = 'left' | 'right' | 'top' | 'bottom'
+
+export interface DrawerProps {
+  /** 受控打开状态；不传则非受控，由 defaultOpen + 内部状态控制 */
+  open?: boolean
+  /** 非受控时的初始打开状态 */
+  defaultOpen?: boolean
+  /** 标题文字 */
+  title?: string
+  /** 滑出方向 */
+  placement?: DrawerPlacement
+  /** 面板宽度（left / right 方向生效，px 数字或 CSS 宽度字符串） */
+  width?: number | string
+  /** 面板高度（top / bottom 方向生效，px 数字或 CSS 高度字符串） */
+  height?: number | string
+  /** 是否显示遮罩 */
+  mask?: boolean
+  /** 点击遮罩关闭 */
+  maskClosable?: boolean
+  /** Esc 关闭 */
+  keyboard?: boolean
+  /** 显示右上角关闭按钮 */
+  closable?: boolean
+  /** 允许拖动面板边缘调整尺寸（左右方向改宽度，上下方向改高度） */
+  resizable?: boolean
+  /** 弹层挂载容器；不传时取 ConfigProvider.popupContainer，再退回 body */
+  popupContainer?: PopupContainer
+}
diff --git a/code/g3soft-libs/packages/ui/src/dropdown/Dropdown.test.ts b/code/g3soft-libs/packages/ui/src/dropdown/Dropdown.test.ts
new file mode 100644
index 00000000..a11885e1
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/dropdown/Dropdown.test.ts
@@ -0,0 +1,219 @@
+import { mount } from '@vue/test-utils'
+import { afterEach, describe, expect, it } from 'vitest'
+import { nextTick } from 'vue'
+import G3Dropdown from './Dropdown.vue'
+import G3DropdownItem from './DropdownItem.vue'
+
+/**
+ * 回归重点：`<G3DropdownItem>编辑</G3DropdownItem>` 的文案落在默认插槽里
+ * （编译器把组件子节点包成 `{ default: () => [TextVNode] }`），
+ * 早期只读 `label` prop，结果菜单渲染成一排空白项；
+ * 另外 `<G3DropdownItem danger />` 的空值布尔属性也会被判 falsy 丢掉。
+ *
+ * 注意：浮层 Teleport 到 body，测试之间会累积，必须每个用例后清空 body，
+ * 并且只取「最后一个」菜单（即当前用例的）。
+ */
+afterEach(() => {
+  document.body.innerHTML = ''
+})
+
+function lastMenu(): HTMLElement | null {
+  const menus = document.body.querySelectorAll('.g3-dropdown__menu')
+  return (menus.item(menus.length - 1) as HTMLElement) ?? null
+}
+
+function mountDropdown(template: string) {
+  return mount({
+    components: { G3Dropdown, G3DropdownItem },
+    template,
+  })
+}
+
+const DECLARATIVE = `
+  <G3Dropdown>
+    <template #trigger><button class="trigger">菜单</button></template>
+    <G3DropdownItem item-key="edit">编辑</G3DropdownItem>
+    <G3DropdownItem divider />
+    <G3DropdownItem item-key="del" danger>删除</G3DropdownItem>
+    <G3DropdownItem item-key="off" disabled>禁用项</G3DropdownItem>
+  </G3Dropdown>
+`
+
+async function openDropdown(wrapper: ReturnType<typeof mountDropdown>) {
+  await wrapper.find('.trigger').trigger('click')
+  await nextTick()
+  return lastMenu()
+}
+
+describe('Dropdown 声明式子项', () => {
+  it('插槽文本会作为菜单文案渲染（不再出现空白项）', async () => {
+    const wrapper = mountDropdown(DECLARATIVE)
+    const menu = await openDropdown(wrapper)
+
+    expect(menu).not.toBeNull()
+    const labels = [...menu!.querySelectorAll('.g3-dropdown__item-label')].map((el) => el.textContent)
+    expect(labels).toEqual(['编辑', '删除', '禁用项'])
+  })
+
+  it('divider 渲染成分隔线而不是空项', async () => {
+    const wrapper = mountDropdown(DECLARATIVE)
+    const menu = await openDropdown(wrapper)
+
+    expect(menu!.querySelectorAll('.g3-dropdown__divider')).toHaveLength(1)
+    expect(menu!.querySelectorAll('.g3-dropdown__item')).toHaveLength(3)
+  })
+
+  it('danger / disabled 反映到类名与 aria', async () => {
+    const wrapper = mountDropdown(DECLARATIVE)
+    const menu = await openDropdown(wrapper)
+    const items = [...menu!.querySelectorAll('.g3-dropdown__item')]
+
+    expect(items[0].className).not.toContain('is-item-danger')
+    expect(items[1].className).toContain('is-item-danger')
+    expect(items[2].className).toContain('is-item-disabled')
+    expect(items[2].getAttribute('aria-disabled')).toBe('true')
+  })
+
+  /**
+   * 用 v-model:open + 本地记录点击载荷来断言：
+   * wrapper 是外层匿名组件，事件其实由 G3Dropdown 派发，
+   * 直接断言 wrapper.emitted() 容易被原生事件冒泡干扰，走状态更可靠。
+   */
+  function mountStateful() {
+    return mount({
+      components: { G3Dropdown, G3DropdownItem },
+      data() {
+        return { open: false, clicked: null as null | { key?: unknown; item?: { danger?: boolean } } }
+      },
+      template: `
+        <G3Dropdown v-model:open="open" @click="clicked = $event">
+          <template #trigger><button class="trigger">菜单</button></template>
+          <G3DropdownItem item-key="edit">编辑</G3DropdownItem>
+          <G3DropdownItem divider />
+          <G3DropdownItem item-key="del" danger>删除</G3DropdownItem>
+          <G3DropdownItem item-key="off" disabled>禁用项</G3DropdownItem>
+        </G3Dropdown>
+      `,
+    })
+  }
+
+  type StatefulWrapper = ReturnType<typeof mountStateful>
+
+  async function openStateful(wrapper: StatefulWrapper) {
+    await wrapper.find('.trigger').trigger('click')
+    await nextTick()
+    const menu = lastMenu()
+    expect(menu).not.toBeNull()
+    return { menu: menu!, vm: wrapper.vm as unknown as { open: boolean; clicked: unknown } }
+  }
+
+  it('点击可点项后请求关闭菜单', async () => {
+    const wrapper = mountStateful()
+    const { menu, vm } = await openStateful(wrapper)
+    expect(vm.open).toBe(true)
+
+    ;(menu.querySelector('.g3-dropdown__item') as HTMLElement).click()
+    await nextTick()
+
+    expect(vm.open).toBe(false)
+  })
+
+  it('点击项时回传 key 与 item（供调用方分发动作）', async () => {
+    const wrapper = mountStateful()
+    const { menu, vm } = await openStateful(wrapper)
+    const deleteItem = [...menu.querySelectorAll('.g3-dropdown__item')][1] as HTMLElement
+
+    deleteItem.click()
+    await nextTick()
+
+    const payload = vm.clicked as { key: string; item: { danger?: boolean } }
+    expect(payload.key).toBe('del')
+    expect(payload.item.danger).toBe(true)
+  })
+
+  it('禁用项点击既不回传点击也不关闭菜单', async () => {
+    const wrapper = mountStateful()
+    const { menu, vm } = await openStateful(wrapper)
+    const disabled = [...menu.querySelectorAll('.g3-dropdown__item')][2] as HTMLElement
+
+    disabled.click()
+    await nextTick()
+
+    expect(vm.clicked).toBeNull()
+    expect(vm.open).toBe(true)
+  })
+})
+
+describe('Dropdown items 数据源', () => {
+  it('items 优先于插槽，支持分组标签与子菜单', async () => {
+    const wrapper = mount({
+      components: { G3Dropdown },
+      data() {
+        return {
+          items: [
+            { type: 'label' as const, label: '分组' },
+            { key: 'copy', label: '复制' },
+            { key: 'more', label: '更多', children: [{ key: 'child', label: '子项' }] },
+          ],
+        }
+      },
+      template: `
+        <G3Dropdown :items="items">
+          <template #trigger><button class="trigger">菜单</button></template>
+          <template #menu><span class="fallback">逃生舱</span></template>
+        </G3Dropdown>
+      `,
+    })
+
+    await wrapper.find('.trigger').trigger('click')
+    await nextTick()
+
+    const menu = lastMenu()!
+    expect(menu.querySelector('.g3-dropdown__label')?.textContent?.trim()).toBe('分组')
+    expect(menu.querySelector('.g3-dropdown__item-caret')).not.toBeNull()
+    // items 存在时不渲染 #menu 逃生舱
+    expect(menu.querySelector('.fallback')).toBeNull()
+  })
+
+  it('没有 items 也没有声明式项时回退到 #menu 逃生舱', async () => {
+    const wrapper = mount({
+      components: { G3Dropdown },
+      template: `
+        <G3Dropdown>
+          <template #trigger><button class="trigger">菜单</button></template>
+          <template #menu="{ close }">
+            <button class="custom" @click="close">自定义项</button>
+          </template>
+        </G3Dropdown>
+      `,
+    })
+
+    await wrapper.find('.trigger').trigger('click')
+    await nextTick()
+
+    const menu = lastMenu()!
+    expect(menu.querySelector('.custom')).not.toBeNull()
+    expect(menu.querySelectorAll('.g3-dropdown__item')).toHaveLength(0)
+  })
+})
+
+describe('Dropdown 键盘导航', () => {
+  it('下键高亮第一个可点项，并跳过禁用项', async () => {
+    const wrapper = mountDropdown(DECLARATIVE)
+    const menu = (await openDropdown(wrapper))!
+
+    menu.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowDown', bubbles: true }))
+    await nextTick()
+    expect(menu.querySelector('.is-item-active')?.textContent).toContain('编辑')
+
+    menu.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowDown', bubbles: true }))
+    await nextTick()
+    // 第二个可点项是「删除」，被禁用的项不参与
+    expect(menu.querySelector('.is-item-active')?.textContent).toContain('删除')
+
+    menu.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowDown', bubbles: true }))
+    await nextTick()
+    // 循环回第一项，「禁用项」永远不会被高亮
+    expect(menu.querySelector('.is-item-active')?.textContent).toContain('编辑')
+  })
+})
diff --git a/code/g3soft-libs/packages/ui/src/dropdown/Dropdown.vue b/code/g3soft-libs/packages/ui/src/dropdown/Dropdown.vue
new file mode 100644
index 00000000..ddbbbfac
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/dropdown/Dropdown.vue
@@ -0,0 +1,332 @@
+<script setup lang="ts">
+import { computed, isVNode, nextTick, provide, ref, useSlots, type VNode } from 'vue'
+import { useNamespace } from '../_composables/useNamespace'
+import G3Popover from '../popover/Popover.vue'
+import G3DropdownItem from './DropdownItem.vue'
+import G3DropdownMenu from './DropdownMenu.vue'
+import { dropdownActiveIndexKey, dropdownSelectKey } from './context'
+import type { DropdownClickPayload, DropdownItemData, DropdownProps } from './types'
+
+/**
+ * 下拉菜单 —— 点击 / 悬停 / 右键触发的操作列表，支持数组、声明式菜单项与 #menu 逃生舱三种用法。
+ *
+ * 键盘可用：↑↓ 移动高亮（跳过分隔线 / 标签 / 禁用项），Home / End 跳到首尾，Enter 选中。
+ */
+defineOptions({ name: 'G3Dropdown' })
+
+const props = withDefaults(defineProps<DropdownProps>(), {
+  items: undefined,
+  open: undefined,
+  defaultOpen: false,
+  trigger: 'click',
+  placement: 'bottom-start',
+  disabled: false,
+  mouseEnterDelay: 100,
+  mouseLeaveDelay: 200,
+  offset: 4,
+  unwrapped: true,
+})
+
+const emit = defineEmits<{
+  'update:open': [value: boolean]
+  openChange: [value: boolean]
+  click: [payload: DropdownClickPayload]
+}>()
+
+const slots = useSlots()
+const { e, is } = useNamespace('dropdown')
+
+const menuEl = ref<HTMLElement | null>(null)
+const internalOpen = ref(props.defaultOpen)
+const activeIndex = ref(-1)
+
+const isOpen = computed(() => (props.open !== undefined ? props.open : internalOpen.value))
+
+/**
+ * 从声明式子节点里提取纯文本，作为菜单项文案。
+ *
+ * 支持两种写法：
+ * - `<G3DropdownItem label="编辑" />`
+ * - `<G3DropdownItem>编辑</G3DropdownItem>`（文本落在默认插槽里）
+ * 早期只读 label prop，后一种写法会渲染成一个空菜单项。
+ */
+function resolveLabel(raw: Record<string, unknown>, children: unknown): string | undefined {
+  if (raw.label != null) return String(raw.label)
+  return slotText(children)
+}
+
+function slotText(children: unknown): string | undefined {
+  if (typeof children === 'string' || typeof children === 'number') return String(children).trim()
+  if (Array.isArray(children)) {
+    const text = children.map((child) => slotText(child) ?? '').join('').trim()
+    return text || undefined
+  }
+  // 文本 vnode / 元素 vnode：文本在它自己的 children 上
+  if (isVNode(children)) return slotText(children.children)
+  // 插槽对象形态：编译器给组件的子节点就是 { default: () => [...] }
+  if (children && typeof children === 'object' && 'default' in (children as Record<string, unknown>)) {
+    const factory = (children as Record<string, unknown>).default
+    return typeof factory === 'function' ? slotText((factory as () => unknown)()) : undefined
+  }
+  return undefined
+}
+
+/** items 来源：优先 props.items，未传时从默认插槽收集 <G3DropdownItem> */
+function collectItems(): DropdownItemData[] {
+  const defaultSlot = slots.default
+  if (!defaultSlot) return []
+  const items: DropdownItemData[] = []
+  for (const vnode of defaultSlot() as VNode[]) {
+    if (!vnode || !vnode.type) continue
+    if (vnode.type !== G3DropdownItem) continue
+    const raw = (vnode.props || {}) as Record<string, unknown>
+    if (raw.divider != null && raw.divider !== false) {
+      items.push({ divider: true })
+      continue
+    }
+    const item: DropdownItemData = {}
+    // 模板里写 `item-key="x"` 时 vnode.props 的键是 kebab-case（'item-key'），
+    // 只读 camelCase 会拿不到，调用方 click 事件里的 key 就成了 undefined
+    const itemKey = raw.itemKey ?? raw['item-key']
+    if (itemKey != null) item.key = itemKey as string | number
+    if (raw.icon != null) item.icon = raw.icon as DropdownItemData['icon']
+    const label = resolveLabel(raw, vnode.children)
+    if (label != null) item.label = label
+    // 注意：`<G3DropdownItem danger />` 这类「空值布尔属性」在 vnode.props 里是 ''，
+    // 用 `if (raw.danger)` 判断会当成 false 丢掉，必须显式排除 false
+    if (raw.danger != null && raw.danger !== false) item.danger = true
+    if (raw.disabled != null && raw.disabled !== false) item.disabled = true
+    if (raw.onClick != null) item.onClick = raw.onClick as DropdownItemData['onClick']
+    items.push(item)
+  }
+  return items
+}
+
+const resolvedItems = computed<DropdownItemData[] | undefined>(() => {
+  if (props.items != null) return props.items
+  // 未传 items 时，仅当默认插槽确实声明了 G3DropdownItem 才启用数组渲染；
+  // 否则保留 undefined，回退到 #menu 逃生舱（避免空数组误吞 #menu 内容）
+  const collected = collectItems()
+  return collected.length ? collected : undefined
+})
+
+/** 可键盘导航的项索引（跳过分隔线 / 标签 / 禁用项） */
+const enabledIndices = computed(() =>
+  (resolvedItems.value ?? []).reduce<number[]>((acc, item, index) => {
+    if (item && !item.divider && item.type !== 'label' && !item.disabled) acc.push(index)
+    return acc
+  }, []),
+)
+
+function onOpenChange(value: boolean) {
+  if (props.open === undefined) internalOpen.value = value
+  emit('update:open', value)
+  emit('openChange', value)
+  if (value) {
+    activeIndex.value = -1
+    nextTick(() => menuEl.value?.focus())
+  } else {
+    activeIndex.value = -1
+  }
+}
+
+function selectItem(item: DropdownItemData) {
+  emit('click', { key: item.key, item })
+  onOpenChange(false)
+}
+
+function close() {
+  onOpenChange(false)
+}
+
+/* ---------- 键盘导航 ---------- */
+function scrollActiveIntoView() {
+  menuEl.value?.querySelector(`.${is('item-active')}`)?.scrollIntoView({ block: 'nearest' })
+}
+
+function moveActive(direction: 1 | -1) {
+  const indices = enabledIndices.value
+  if (!indices.length) {
+    activeIndex.value = -1
+    return
+  }
+  const pos = indices.indexOf(activeIndex.value)
+  const nextPos =
+    pos === -1
+      ? direction === 1
+        ? 0
+        : indices.length - 1
+      : (pos + direction + indices.length) % indices.length
+  activeIndex.value = indices[nextPos]
+  nextTick(scrollActiveIntoView)
+}
+
+function onMenuKeydown(event: KeyboardEvent) {
+  switch (event.key) {
+    case 'ArrowDown':
+      event.preventDefault()
+      moveActive(1)
+      break
+    case 'ArrowUp':
+      event.preventDefault()
+      moveActive(-1)
+      break
+    case 'Home':
+      event.preventDefault()
+      activeIndex.value = enabledIndices.value[0] ?? -1
+      nextTick(scrollActiveIntoView)
+      break
+    case 'End':
+      event.preventDefault()
+      activeIndex.value = enabledIndices.value[enabledIndices.value.length - 1] ?? -1
+      nextTick(scrollActiveIntoView)
+      break
+    case 'Enter': {
+      event.preventDefault()
+      const item = resolvedItems.value?.[activeIndex.value]
+      // 子菜单父项 Enter 不选中（子菜单为 hover 展开，键盘不逐层进入）
+      if (item && enabledIndices.value.includes(activeIndex.value) && !item.children) {
+        selectItem(item)
+      }
+      break
+    }
+  }
+}
+
+/* ---------- 注入给菜单 / 子菜单 ---------- */
+provide(dropdownSelectKey, selectItem)
+provide(dropdownActiveIndexKey, activeIndex)
+</script>
+
+<template>
+  <G3Popover
+    :open="isOpen"
+    :trigger="trigger"
+    :placement="placement"
+    :disabled="disabled"
+    :arrow="false"
+    :offset="offset"
+    :unwrapped="unwrapped"
+    :mouse-enter-delay="mouseEnterDelay"
+    :mouse-leave-delay="mouseLeaveDelay"
+    @update:open="onOpenChange"
+  >
+    <!-- 触发器：#trigger 具名插槽优先，未传时回退默认插槽 -->
+    <template #trigger>
+      <slot name="trigger"><slot /></slot>
+    </template>
+
+    <template #content>
+      <div
+        ref="menuEl"
+        :class="e('menu')"
+        role="menu"
+        tabindex="-1"
+        @keydown="onMenuKeydown"
+      >
+        <!-- 富头部插槽：菜单项列表上方的自定义区域 -->
+        <div v-if="$slots.header" :class="e('header')">
+          <slot name="header" />
+        </div>
+
+        <G3DropdownMenu v-if="resolvedItems != null" :items="resolvedItems" />
+        <slot v-else name="menu" :close="close" />
+      </div>
+    </template>
+  </G3Popover>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+.#{e('dropdown', 'menu')} {
+  display: flex;
+  flex-direction: column;
+  box-sizing: border-box;
+  min-width: v('dropdown-min-width', 180px);
+  max-height: v('dropdown-max-height', 256px);
+  overflow: auto;
+  padding: v('space-1', 4px);
+  outline: none;
+}
+
+.#{e('dropdown', 'header')} {
+  padding: v('space-2', 8px);
+  border-bottom: 1px solid v('border-color', #d9d9d9);
+  margin-bottom: v('space-1', 4px);
+}
+
+.#{e('dropdown', 'item')} {
+  display: flex;
+  align-items: center;
+  gap: v('space-2', 8px);
+  padding: v('dropdown-item-padding-y', 5px) v('dropdown-item-padding-x', 8px);
+  border-radius: v('dropdown-item-radius', 4px);
+  color: v('text-1', rgba(0, 0, 0, 0.88));
+  font-size: v('font-size', 14px);
+  line-height: v('line-height', 1.5);
+  white-space: nowrap;
+  cursor: pointer;
+  user-select: none;
+  transition: background-color v('duration-fast', 0.1s) v('ease', ease);
+}
+
+.#{e('dropdown', 'item')}.#{is('item-active')} {
+  background: v('fill', rgba(0, 0, 0, 0.04));
+}
+
+.#{e('dropdown', 'item')}.#{is('item-disabled')} {
+  color: v('text-disabled', rgba(0, 0, 0, 0.25));
+  cursor: not-allowed;
+}
+
+.#{e('dropdown', 'item')}.#{is('item-danger')} {
+  color: v('color-danger', #ec4246);
+}
+
+.#{e('dropdown', 'item')}.#{is('item-danger')}.#{is('item-active')} {
+  background: color-mix(in srgb, #{v('color-danger', #ec4246)} 10%, transparent);
+}
+
+.#{e('dropdown', 'item-icon')} {
+  display: inline-flex;
+  flex-shrink: 0;
+  color: v('text-2', rgba(0, 0, 0, 0.65));
+
+  svg {
+    width: 1em;
+    height: 1em;
+  }
+}
+
+.#{e('dropdown', 'item-label')} {
+  flex: 1;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.#{e('dropdown', 'item-shortcut')} {
+  flex-shrink: 0;
+  color: v('text-3', rgba(0, 0, 0, 0.45));
+  font-size: v('font-size-sm', 12px);
+}
+
+.#{e('dropdown', 'item-caret')} {
+  flex-shrink: 0;
+  width: 1em;
+  height: 1em;
+  color: v('text-3', rgba(0, 0, 0, 0.45));
+}
+
+.#{e('dropdown', 'divider')} {
+  height: 1px;
+  margin: v('dropdown-divider-margin', 4px 0);
+  background: v('border-color', #d9d9d9);
+}
+
+.#{e('dropdown', 'label')} {
+  padding: v('space-1', 4px) v('dropdown-item-padding-x', 8px);
+  color: v('text-3', rgba(0, 0, 0, 0.45));
+  font-size: v('font-size-sm', 12px);
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/dropdown/DropdownItem.vue b/code/g3soft-libs/packages/ui/src/dropdown/DropdownItem.vue
new file mode 100644
index 00000000..5140f4bd
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/dropdown/DropdownItem.vue
@@ -0,0 +1,39 @@
+<script setup lang="ts">
+import type { Component } from 'vue'
+
+/**
+ * 下拉菜单项（声明式写法）—— 本组件不渲染任何可见 DOM。
+ *
+ * 仅用于被 G3Dropdown 的默认插槽收集 props，转换为 items 数组后
+ * 交由内部菜单渲染，从而复用键盘导航 / 高亮 / 子菜单体系。
+ */
+defineOptions({ name: 'G3DropdownItem' })
+
+withDefaults(
+  defineProps<{
+    /** 标识，点击时随 click 事件回传 */
+    itemKey?: string | number
+    /** 图标组件 */
+    icon?: Component
+    /** 菜单文本 */
+    label?: string
+    /** 危险项（红色） */
+    danger?: boolean
+    /** 禁用项 */
+    disabled?: boolean
+    /** 渲染为分隔线（设置后其余属性忽略） */
+    divider?: boolean
+    /** 项自带点击回调，命中时优先执行 */
+    onClick?: (item: unknown) => void
+  }>(),
+  {
+    itemKey: undefined,
+    icon: undefined,
+    label: '',
+    danger: false,
+    disabled: false,
+    divider: false,
+    onClick: undefined,
+  },
+)
+</script>
diff --git a/code/g3soft-libs/packages/ui/src/dropdown/DropdownMenu.vue b/code/g3soft-libs/packages/ui/src/dropdown/DropdownMenu.vue
new file mode 100644
index 00000000..2900d3ba
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/dropdown/DropdownMenu.vue
@@ -0,0 +1,116 @@
+<script setup lang="ts">
+import { inject, isVNode, type VNode } from 'vue'
+import { ChevronRight } from '@lucide/vue'
+import { useNamespace } from '../_composables/useNamespace'
+import G3Popover from '../popover/Popover.vue'
+import { dropdownActiveIndexKey, dropdownSelectKey } from './context'
+import type { DropdownItemData } from './types'
+
+/**
+ * 下拉菜单列表（内部组件）—— 把 items 数组渲染成分隔线 / 分组标签 / 子菜单 / 普通项。
+ */
+defineOptions({ name: 'G3DropdownMenu' })
+
+const props = withDefaults(
+  defineProps<{
+    /** 菜单项数组 */
+    items?: DropdownItemData[]
+    /** 是否参与主菜单的键盘 / 鼠标高亮联动；递归子菜单时关闭 */
+    interactive?: boolean
+  }>(),
+  { items: () => [], interactive: true },
+)
+
+const { b, e, m, is } = useNamespace('dropdown')
+
+const selectItem = inject(dropdownSelectKey, null)
+const activeIndex = inject(dropdownActiveIndexKey, null)
+
+function isActive(index: number): boolean {
+  return props.interactive && activeIndex !== null && activeIndex.value === index
+}
+
+/** 鼠标移入时同步键盘高亮索引（子菜单不参与联动） */
+function setActive(index: number) {
+  if (!props.interactive || activeIndex === null) return
+  activeIndex.value = index
+}
+
+function onItemClick(item: DropdownItemData) {
+  if (item.disabled) return
+  item.onClick?.(item)
+  selectItem?.(item)
+}
+
+/** 渲染函数组件：把 VNode 形态的图标原样渲染 */
+const VNodeRenderer = (renderProps: { node: VNode }) => renderProps.node
+</script>
+
+<template>
+  <template v-for="(item, index) in props.items" :key="item?.key ?? index">
+    <!-- 分隔线 -->
+    <div v-if="item?.divider" :class="e('divider')" role="separator" />
+
+    <!-- 分组标签 -->
+    <div v-else-if="item?.type === 'label'" :class="e('label')" role="group">
+      {{ item.label }}
+    </div>
+
+    <!-- 子菜单：嵌套 Popover，hover 展开 -->
+    <G3Popover
+      v-else-if="item?.children?.length"
+      trigger="hover"
+      placement="right-start"
+      :offset="0"
+      :arrow="false"
+      unwrapped
+    >
+      <template #trigger>
+        <span
+          :class="[
+            e('item'),
+            { [is('item-active')]: isActive(index), [is('item-disabled')]: item.disabled },
+          ]"
+          role="menuitem"
+          aria-haspopup="menu"
+        >
+          <span v-if="item.icon" :class="e('item-icon')">
+            <component :is="item.icon" v-if="!isVNode(item.icon)" />
+            <VNodeRenderer v-else :node="(item.icon as VNode)" />
+          </span>
+          <span :class="e('item-label')">{{ item.label }}</span>
+          <ChevronRight :class="e('item-caret')" aria-hidden="true" />
+        </span>
+      </template>
+      <template #content>
+        <div :class="e('menu')" role="menu">
+          <G3DropdownMenu :items="item.children" :interactive="false" />
+        </div>
+      </template>
+    </G3Popover>
+
+    <!-- 普通项 -->
+    <div
+      v-else-if="item"
+      :class="[
+        e('item'),
+        {
+          [is('item-active')]: isActive(index),
+          [is('item-disabled')]: item.disabled,
+          [is('item-danger')]: item.danger,
+        },
+      ]"
+      role="menuitem"
+      :aria-disabled="item.disabled || undefined"
+      @mouseenter="!item.disabled && setActive(index)"
+      @click="onItemClick(item)"
+    >
+      <span v-if="item.icon" :class="e('item-icon')">
+        <component :is="item.icon" v-if="!isVNode(item.icon)" />
+        <VNodeRenderer v-else :node="(item.icon as VNode)" />
+      </span>
+      <span :class="e('item-label')">{{ item.label }}</span>
+      <span v-if="item.shortcut" :class="e('item-shortcut')">{{ item.shortcut }}</span>
+    </div>
+  </template>
+</template>
diff --git a/code/g3soft-libs/packages/ui/src/dropdown/context.ts b/code/g3soft-libs/packages/ui/src/dropdown/context.ts
new file mode 100644
index 00000000..37bc461f
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/dropdown/context.ts
@@ -0,0 +1,12 @@
+import type { InjectionKey, Ref } from 'vue'
+import type { DropdownItemData } from './types'
+
+/** 主 Dropdown 注入给菜单 / 子菜单的选中回调 */
+export const dropdownSelectKey: InjectionKey<((item: DropdownItemData) => void) | null> = Symbol(
+  'g3-dropdown-select',
+)
+
+/** 主 Dropdown 注入的键盘高亮索引；子菜单不参与联动 */
+export const dropdownActiveIndexKey: InjectionKey<Ref<number> | null> = Symbol(
+  'g3-dropdown-active',
+)
diff --git a/code/g3soft-libs/packages/ui/src/dropdown/index.ts b/code/g3soft-libs/packages/ui/src/dropdown/index.ts
new file mode 100644
index 00000000..08d060af
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/dropdown/index.ts
@@ -0,0 +1,8 @@
+export { default as G3Dropdown } from './Dropdown.vue'
+export { default as G3DropdownItem } from './DropdownItem.vue'
+export type {
+  DropdownClickPayload,
+  DropdownItemData,
+  DropdownProps,
+  DropdownTrigger,
+} from './types'
diff --git a/code/g3soft-libs/packages/ui/src/dropdown/types.ts b/code/g3soft-libs/packages/ui/src/dropdown/types.ts
new file mode 100644
index 00000000..ae0ac751
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/dropdown/types.ts
@@ -0,0 +1,58 @@
+import type { Component, VNode } from 'vue'
+import type { Placement } from '../_utils/position'
+
+/** 触发方式：下拉菜单只支持这三种 */
+export type DropdownTrigger = 'click' | 'hover' | 'contextmenu'
+
+/** 菜单项数据 */
+export interface DropdownItemData {
+  /** 标识，点击时随 click 事件回传 */
+  key?: string | number
+  /** 菜单文本 */
+  label?: string
+  /** 图标：组件或 VNode */
+  icon?: Component | VNode
+  /** 危险项（红色） */
+  danger?: boolean
+  /** 禁用项 */
+  disabled?: boolean
+  /** 快捷键提示文字 */
+  shortcut?: string
+  /** 渲染为分隔线（其余属性忽略） */
+  divider?: boolean
+  /** type='label' 时渲染为分组标签 */
+  type?: 'label'
+  /** 子菜单 */
+  children?: DropdownItemData[]
+  /** 项自带点击回调，命中时优先执行 */
+  onClick?: (item: DropdownItemData) => void
+}
+
+/** 菜单项点击事件载荷 */
+export interface DropdownClickPayload {
+  key?: string | number
+  item: DropdownItemData
+}
+
+export interface DropdownProps {
+  /** 菜单项数组；不传时若默认插槽含 G3DropdownItem 则由其收集渲染，否则用 #menu 插槽 */
+  items?: DropdownItemData[]
+  /** 受控打开状态；不传则非受控 */
+  open?: boolean
+  /** 非受控时的初始打开状态 */
+  defaultOpen?: boolean
+  /** 触发方式 */
+  trigger?: DropdownTrigger
+  /** 菜单浮层方位 */
+  placement?: Placement
+  /** 禁用态 */
+  disabled?: boolean
+  /** hover 触发打开延迟（ms） */
+  mouseEnterDelay?: number
+  /** hover 触发关闭延迟（ms） */
+  mouseLeaveDelay?: number
+  /** 与触发器的间距（px） */
+  offset?: number
+  /** 零包裹模式（默认开启）：把事件注入到触发器单根 vnode，不再包 span */
+  unwrapped?: boolean
+}
diff --git a/code/g3soft-libs/packages/ui/src/form/Form.vue b/code/g3soft-libs/packages/ui/src/form/Form.vue
new file mode 100644
index 00000000..90077ed0
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/form/Form.vue
@@ -0,0 +1,169 @@
+<script setup lang="ts">
+import { computed, provide } from 'vue'
+import { useComponentDefaults } from '../_composables/useComponentDefaults'
+import { useNamespace } from '../_composables/useNamespace'
+import { formKey, type FormFieldController } from './context'
+import { fluidColumnGap, normalizeGap } from './form-utils'
+import type { FormProps } from './types'
+
+/**
+ * 表单 —— 统一收集字段校验、提交与重置。
+ *
+ * 字段值从 `model` 按 FormItem 的 name 读取；提交时并行校验所有已注册字段，
+ * 全部通过才触发 submit，否则触发 submitFailed 并带上出错字段。
+ */
+defineOptions({ name: 'G3Form' })
+
+const props = withDefaults(defineProps<FormProps>(), {
+  rules: () => ({}),
+  layout: undefined,
+  labelAlign: undefined,
+  labelWidth: undefined,
+  columns: 1,
+  spanColumns: 0,
+  maxWidth: undefined,
+  requiredMark: true,
+  validateTrigger: undefined,
+  gap: undefined,
+})
+
+const emit = defineEmits<{
+  submit: [values: Record<string, unknown>]
+  submitFailed: [payload: { values: Record<string, unknown>; errorFields: Array<{ name: string; errors: string[] }> }]
+  reset: []
+}>()
+
+const { b, m, is } = useNamespace('form')
+
+/** 全局默认值回落：显式 prop > ConfigProvider.componentDefaults.form > 组件内置默认 */
+const merged = useComponentDefaults('form', props)
+
+const resolvedLayout = computed(() => merged.value.layout ?? 'horizontal')
+const resolvedLabelAlign = computed(() => merged.value.labelAlign ?? 'right')
+const resolvedLabelWidth = computed(() => merged.value.labelWidth)
+const resolvedValidateTrigger = computed(() => merged.value.validateTrigger ?? 'change')
+
+const normalizedGap = computed(() => normalizeGap(merged.value.gap))
+const hasGap = computed(() => {
+  const { row, col } = normalizedGap.value
+  return row != null || col != null
+})
+
+const formStyle = computed(() => {
+  const style: Record<string, string> = {}
+  if (merged.value.columns > 1) {
+    style.display = 'grid'
+    style.gridTemplateColumns = `repeat(${merged.value.columns}, minmax(0, 1fr))`
+  }
+  if (merged.value.maxWidth != null) {
+    style.maxWidth =
+      typeof merged.value.maxWidth === 'number' ? `${merged.value.maxWidth}px` : merged.value.maxWidth
+  }
+  const { row, col } = normalizedGap.value
+  if (merged.value.columns > 1) {
+    // 多列网格：行间距固定（纵向只增高，不会横向溢出）；列间距按列数钳制防溢出
+    style.rowGap = `${row ?? 12}px`
+    const columnGap = fluidColumnGap(col ?? 16, merged.value.columns)
+    if (columnGap) style.columnGap = columnGap
+  } else if (row != null) {
+    // 单列纵向：flex 列布局用 row-gap 控制表单项间距
+    style.display = 'flex'
+    style.flexDirection = 'column'
+    style.rowGap = `${row}px`
+  }
+  return style
+})
+
+/* ---------- 字段注册表 ---------- */
+const fieldMap = new Map<string, FormFieldController>()
+
+function registerField(name: string | number, field: FormFieldController) {
+  fieldMap.set(String(name), field)
+}
+
+function unregisterField(name: string | number) {
+  fieldMap.delete(String(name))
+}
+
+/* ---------- 全量校验 ---------- */
+async function validateAll(): Promise<Array<{ name: string; errors: string[] }>> {
+  const entries = [...fieldMap.entries()]
+  const results = await Promise.all(
+    entries.map(async ([name, field]) => ({ name, errors: await field.validate() })),
+  )
+  return results.filter((item) => item.errors.length > 0)
+}
+
+/* ---------- 提交 / 重置 ---------- */
+async function onSubmit(event: Event) {
+  event.preventDefault()
+  const errorFields = await validateAll()
+  if (errorFields.length === 0) {
+    emit('submit', { ...props.model })
+  } else {
+    emit('submitFailed', { values: { ...props.model }, errorFields })
+  }
+}
+
+function onReset(event: Event) {
+  event.preventDefault()
+  emit('reset')
+  // 同步清除所有字段错误与触碰标记；父层清空 model 后的值变化由 FormItem 的
+  // 「未触碰且值空」判定跳过，不会触发校验误报
+  fieldMap.forEach((field) => field.clearValidation())
+}
+
+/* ---------- 上下文 ---------- */
+// model / rules 用 computed 包裹：父级可能整体替换这两个 prop 的对象，
+// provide 只执行一次，直接传引用会让 FormItem 校验读到过期对象
+provide(formKey, {
+  model: computed(() => props.model),
+  rules: computed(() => props.rules),
+  layout: resolvedLayout,
+  labelAlign: resolvedLabelAlign,
+  labelWidth: resolvedLabelWidth,
+  columns: computed(() => props.spanColumns || merged.value.columns),
+  requiredMark: computed(() => merged.value.requiredMark),
+  validateTrigger: resolvedValidateTrigger,
+  registerField,
+  unregisterField,
+})
+
+/** 供父级强制校验（如保存前）：返回带错误的字段列表 */
+defineExpose({ validateAll })
+</script>
+
+<template>
+  <form
+    :class="[
+      b(),
+      m(resolvedLayout),
+      { [m('grid')]: merged.columns > 1, [is('gap')]: hasGap },
+    ]"
+    :style="formStyle"
+    @submit="onSubmit"
+    @reset="onReset"
+  >
+    <slot />
+  </form>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+.#{b('form')} {
+  display: flex;
+  flex-direction: column;
+  gap: v('space-4', 16px);
+  width: 100%;
+}
+
+/* 显式给了 gap：改由内联 row-gap / gap 控制，去掉默认堆叠间距 */
+.#{b('form')}.#{is('gap')} {
+  gap: 0;
+}
+
+.#{m('form', 'vertical')} {
+  flex-direction: column;
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/form/FormGroup.vue b/code/g3soft-libs/packages/ui/src/form/FormGroup.vue
new file mode 100644
index 00000000..6439e051
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/form/FormGroup.vue
@@ -0,0 +1,184 @@
+<script setup lang="ts">
+import { computed, inject, provide, ref } from 'vue'
+import { ChevronDown } from '@lucide/vue'
+import { useComponentDefaults } from '../_composables/useComponentDefaults'
+import { useNamespace } from '../_composables/useNamespace'
+import { formGroupKey, formKey } from './context'
+import { fluidColumnGap, normalizeGap } from './form-utils'
+import type { FormGroupProps } from './types'
+
+/**
+ * 表单分组 —— 一组字段共用独立的列数 / 布局 / 间距，便于在长表单里做宫格嵌套。
+ *
+ * 组内覆盖优先于外层 Form：FormItem 的 label 宽度、布局与跨列数都会先看组上下文。
+ * 标题行可点击折叠（collapsible 默认开启）；折叠用 grid-template-rows 过渡而不是卸载，
+ * 收起期间字段与校验状态全部保留（也可用 v-model 受控展开态）。
+ */
+defineOptions({ name: 'G3FormGroup' })
+
+const props = withDefaults(defineProps<FormGroupProps>(), {
+  modelValue: undefined,
+  collapsible: true,
+  defaultExpanded: true,
+  columns: undefined,
+  layout: undefined,
+  labelWidth: undefined,
+  gap: undefined,
+  span: undefined,
+  title: '',
+})
+
+const emit = defineEmits<{ 'update:modelValue': [expanded: boolean] }>()
+
+const { b, e, m, is } = useNamespace('form-group')
+const form = inject(formKey, null)
+
+const merged = useComponentDefaults('form-group', props)
+
+/** 展开态：受控优先，否则内部维护（初值取 defaultExpanded） */
+const innerExpanded = ref(props.defaultExpanded)
+const expanded = computed(() => props.modelValue ?? innerExpanded.value)
+
+function toggleCollapse() {
+  if (!props.collapsible) return
+  const next = !expanded.value
+  if (props.modelValue === undefined) innerExpanded.value = next
+  emit('update:modelValue', next)
+}
+
+/** 组内列数：显式 columns > 外层 Form.columns > 1 */
+const columns = computed(() => merged.value.columns ?? form?.columns.value ?? 1)
+
+const normalizedGap = computed(() => normalizeGap(merged.value.gap))
+
+const groupStyle = computed(() => {
+  const style: Record<string, string> = {}
+  const count = columns.value
+  if (count > 1) {
+    style.display = 'grid'
+    style.gridTemplateColumns = `repeat(${count}, minmax(0, 1fr))`
+    style.rowGap = `${normalizedGap.value.row ?? 12}px`
+    const columnGap = fluidColumnGap(normalizedGap.value.col ?? 16, count)
+    if (columnGap) style.columnGap = columnGap
+  } else if (normalizedGap.value.row != null) {
+    style.display = 'flex'
+    style.flexDirection = 'column'
+    style.rowGap = `${normalizedGap.value.row}px`
+  }
+  return style
+})
+
+/**
+ * 外层宫格占格：只在多列 Form 里生效。
+ * 未显式指定 span 时占满整行 —— 分组通常自成一行，挤进单列会很别扭。
+ */
+const rootStyle = computed((): Record<string, string> | undefined => {
+  const formColumns = form?.columns.value ?? 1
+  if (formColumns <= 1) return undefined
+  const span =
+    props.span == null
+      ? formColumns
+      : Math.min(Math.max(Number(props.span) || 1, 1), formColumns)
+  return { gridColumn: `span ${span}` }
+})
+
+// columns 传 undefined 时会回落到外层 Form 的列数（FormItem 自己判断）
+provide(formGroupKey, {
+  columns: computed(() => merged.value.columns),
+  layout: computed(() => merged.value.layout),
+  labelWidth: computed(() => merged.value.labelWidth),
+})
+</script>
+
+<template>
+  <div :class="[b(), { [m('grid')]: columns > 1 }]" :style="rootStyle">
+    <div
+      v-if="title || $slots.title"
+      :class="[e('title'), { [is('collapsible')]: collapsible, [is('expanded')]: expanded }]"
+      :role="collapsible ? 'button' : undefined"
+      :tabindex="collapsible ? 0 : undefined"
+      :aria-expanded="collapsible ? expanded : undefined"
+      @click="toggleCollapse"
+      @keydown.enter.prevent="toggleCollapse"
+      @keydown.space.prevent="toggleCollapse"
+    >
+      <ChevronDown v-if="collapsible" :class="e('arrow')" aria-hidden="true" />
+      <span :class="e('title-text')">
+        <slot name="title">{{ title }}</slot>
+      </span>
+    </div>
+
+    <div :class="e('collapse')" :style="{ gridTemplateRows: expanded ? '1fr' : '0fr' }">
+      <div :class="e('body')" :style="groupStyle">
+        <slot />
+      </div>
+    </div>
+  </div>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+.#{b('form-group')} {
+  display: flex;
+  flex-direction: column;
+  gap: v('space-2', 8px);
+  min-width: 0;
+}
+
+.#{e('form-group', 'title')} {
+  display: inline-flex;
+  align-items: center;
+  gap: v('space-1', 4px);
+  color: v('text-1', rgba(0, 0, 0, 0.88));
+  font-size: v('font-size', 14px);
+  font-weight: 600;
+  justify-self: start;
+}
+
+.#{e('form-group', 'title')}.#{is('collapsible')} {
+  cursor: pointer;
+  user-select: none;
+}
+
+.#{e('form-group', 'title')}.#{is('collapsible')}:hover .#{e('form-group', 'title-text')} {
+  color: v('color-primary', #18181b);
+}
+
+.#{e('form-group', 'title')}.#{is('collapsible')}:focus-visible {
+  @include focus-ring();
+  border-radius: v('radius-sm', 4px);
+}
+
+.#{e('form-group', 'arrow')} {
+  flex-shrink: 0;
+  width: 16px;
+  height: 16px;
+  color: v('text-3', rgba(0, 0, 0, 0.45));
+  /* 收起时箭头转向右侧，展开朝下 */
+  transform: rotate(-90deg);
+  transition: transform v('duration', 0.2s) v('ease', ease);
+}
+
+.#{e('form-group', 'title')}.#{is('expanded')} .#{e('form-group', 'arrow')} {
+  transform: rotate(0deg);
+}
+
+/* 折叠用网格行过渡：0fr 收起但内容不卸载，字段状态与校验态都还在 */
+.#{e('form-group', 'collapse')} {
+  display: grid;
+  grid-template-rows: 1fr;
+  transition: grid-template-rows v('duration', 0.2s) v('ease', ease);
+
+  > * {
+    min-height: 0;
+    overflow: hidden;
+  }
+}
+
+.#{e('form-group', 'body')} {
+  display: flex;
+  flex-direction: column;
+  gap: v('space-4', 16px);
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/form/FormItem.test.ts b/code/g3soft-libs/packages/ui/src/form/FormItem.test.ts
new file mode 100644
index 00000000..08305566
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/form/FormItem.test.ts
@@ -0,0 +1,158 @@
+import { mount } from '@vue/test-utils'
+import { describe, expect, it, vi } from 'vitest'
+import { nextTick } from 'vue'
+import G3Form from './Form.vue'
+import G3FormItem from './FormItem.vue'
+import G3Input from '../input/Input.vue'
+
+/**
+ * 回归重点：`FormItemProps.name` 曾经被声明成必填，导致
+ * - 只当布局容器用的 FormItem（不传 name）在控制台刷「Missing required prop」
+ * - 还会往 Form 注册一个字段名是 "undefined" 的假字段，污染全量校验
+ */
+const COMPONENTS = { G3Form, G3FormItem, G3Input }
+
+function mountForm(options: { withName?: boolean } = {}) {
+  const withName = options.withName ?? true
+  return mount({
+    components: COMPONENTS,
+    data() {
+      return {
+        model: { name: '' },
+        rules: { name: [{ required: true }] },
+      }
+    },
+    template: `
+      <G3Form :model="model" :rules="rules" :label-width="80">
+        <G3FormItem ${withName ? 'name="name"' : ''} label="名称">
+          <G3Input v-model="model.name" />
+        </G3FormItem>
+        <G3FormItem label="纯布局项"><span class="plain">占位</span></G3FormItem>
+      </G3Form>
+    `,
+  })
+}
+
+function formOf(wrapper: ReturnType<typeof mountForm>) {
+  return wrapper.findComponent({ name: 'G3Form' }).vm as unknown as {
+    validateAll: () => Promise<Array<{ name: string; errors: string[] }>>
+  }
+}
+
+describe('FormItem 缺省 name（纯布局项）', () => {
+  it('不传 name 时不报 required 警告', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const wrapper = mountForm({ withName: false })
+
+    const warnings = warn.mock.calls.map((call) => String(call[0])).join('\n')
+    expect(warnings).not.toContain('Missing required prop')
+    expect(wrapper.find('.plain').exists()).toBe(true)
+    warn.mockRestore()
+  })
+
+  it('不传 name 时不会往 Form 注册假字段（全量校验只报真实字段）', async () => {
+    const wrapper = mountForm({ withName: false })
+    const errors = await formOf(wrapper).validateAll()
+
+    expect(errors).toHaveLength(0)
+
+    const withField = mountForm()
+    const fieldErrors = await formOf(withField).validateAll()
+    expect(fieldErrors.map((item) => item.name)).toEqual(['name'])
+  })
+
+  it('纯布局项不渲染 data-field', () => {
+    const wrapper = mountForm()
+    const items = wrapper.findAll('.g3-form-item')
+    expect(items[0].attributes('data-field')).toBe('name')
+    expect(items[1].attributes('data-field')).toBeUndefined()
+  })
+})
+
+describe('FormItem 校验与提示', () => {
+  it('不传 name 的项即使有 rules 也不参与校验', async () => {
+    const wrapper = mount({
+      components: COMPONENTS,
+      data() {
+        return { model: { a: '' } }
+      },
+      template: `
+        <G3Form :model="model">
+          <G3FormItem label="无名字段" :rules="[{ required: true }]"><span class="plain">x</span></G3FormItem>
+        </G3Form>
+      `,
+    })
+
+    const errors = await (wrapper.findComponent({ name: 'G3Form' }).vm as unknown as {
+      validateAll: () => Promise<unknown[]>
+    }).validateAll()
+    expect(errors).toHaveLength(0)
+  })
+
+  it('validateAll 后渲染错误文案并标记 error 状态', async () => {
+    const wrapper = mountForm()
+    await formOf(wrapper).validateAll()
+    await nextTick()
+
+    const item = wrapper.findAll('.g3-form-item')[0]
+    expect(item.classes()).toContain('is-error')
+    expect(item.find('.g3-form-item__help').text()).toBe('名称不能为空')
+    expect(item.find('.g3-form-item__help').attributes('role')).toBe('alert')
+  })
+
+  it('填值后再次校验通过，错误提示消失', async () => {
+    const wrapper = mountForm()
+    await formOf(wrapper).validateAll()
+    await nextTick()
+    expect(wrapper.find('.g3-form-item__help').exists()).toBe(true)
+
+    await wrapper.find('input').setValue('张三')
+    await formOf(wrapper).validateAll()
+    await nextTick()
+
+    expect(wrapper.find('.g3-form-item__help').exists()).toBe(false)
+    expect(wrapper.findAll('.g3-form-item')[0].classes()).not.toContain('is-error')
+  })
+
+  it('必填标记由规则推导；Form 关闭 requiredMark 后不显示星号', () => {
+    const wrapper = mountForm()
+    expect(wrapper.find('.g3-form-item__required').exists()).toBe(true)
+
+    const noMark = mount({
+      components: COMPONENTS,
+      data() {
+        return { model: { name: '' }, rules: { name: [{ required: true }] } }
+      },
+      template: `
+        <G3Form :model="model" :rules="rules" :required-mark="false">
+          <G3FormItem name="name" label="名称"><span class="plain" /></G3FormItem>
+        </G3Form>
+      `,
+    })
+    expect(noMark.find('.g3-form-item__required').exists()).toBe(false)
+  })
+
+  it('extra 在没有错误时展示，出错后让位给错误信息', async () => {
+    const wrapper = mount({
+      components: COMPONENTS,
+      data() {
+        return { model: { name: '' }, rules: { name: [{ required: true }] } }
+      },
+      template: `
+        <G3Form :model="model" :rules="rules">
+          <G3FormItem name="name" label="名称" extra="辅助说明"><span class="plain" /></G3FormItem>
+        </G3Form>
+      `,
+    })
+
+    expect(wrapper.find('.g3-form-item__extra').text()).toBe('辅助说明')
+
+    await (wrapper.findComponent({ name: 'G3Form' }).vm as unknown as {
+      validateAll: () => Promise<unknown[]>
+    }).validateAll()
+    await nextTick()
+
+    expect(wrapper.find('.g3-form-item__extra').exists()).toBe(false)
+    expect(wrapper.find('.g3-form-item__help').text()).toBe('名称不能为空')
+  })
+})
diff --git a/code/g3soft-libs/packages/ui/src/form/FormItem.vue b/code/g3soft-libs/packages/ui/src/form/FormItem.vue
new file mode 100644
index 00000000..6387d731
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/form/FormItem.vue
@@ -0,0 +1,304 @@
+<script setup lang="ts">
+import { computed, inject, onBeforeUnmount, onMounted, ref, watch } from 'vue'
+import { useComponentDefaults } from '../_composables/useComponentDefaults'
+import { useLocale } from '../_composables/useLocale'
+import { useNamespace } from '../_composables/useNamespace'
+import { formGroupKey, formKey } from './context'
+import type { FormItemProps } from './types'
+import { isEmptyValue, validateRules } from './validate'
+
+/**
+ * 表单项 —— 承载 label、控件、错误提示与校验。
+ *
+ * 需要绑定字段时传 name（对应 Form.model 的 key）；不传则仅作布局容器，
+ * 不注册进 Form、不参与校验。校验时机默认取 Form 的 validateTrigger，
+ * 首次失焦且值为空时只标记触碰、不报错。
+ */
+defineOptions({ name: 'G3FormItem' })
+
+const props = withDefaults(defineProps<FormItemProps>(), {
+  // 显式给默认值：类型的可选性不足以让编译器去掉 required 标记
+  name: '',
+  label: '',
+  rules: undefined,
+  required: undefined,
+  extra: '',
+  help: '',
+  labelAlign: undefined,
+  labelWidth: undefined,
+  span: 1,
+  lineStart: false,
+  validateStatus: '',
+})
+
+const { b, e, m, is } = useNamespace('form-item')
+const locale = useLocale()
+
+const form = inject(formKey, null)
+const groupForm = inject(formGroupKey, null)
+const rootEl = ref<HTMLElement | null>(null)
+
+/** 归一后的字段名；空串表示「纯布局项」 */
+const fieldName = computed(() => (props.name == null ? '' : String(props.name)))
+const hasField = computed(() => fieldName.value !== '')
+
+/** 全局默认值回落：显式 prop > ConfigProvider.componentDefaults.form-item > 组件内置默认 */
+const merged = useComponentDefaults('form-item', props)
+
+/* ---------- 合并规则 ---------- */
+const mergedRules = computed(() => {
+  if (Array.isArray(props.rules) && props.rules.length > 0) return props.rules
+  if (!hasField.value) return []
+  return form?.rules.value?.[fieldName.value] ?? []
+})
+
+/* ---------- 状态 ---------- */
+const errors = ref<string[]>([])
+const touched = ref(false)
+
+const isRequired = computed(() => {
+  if (props.required !== undefined) return props.required
+  return mergedRules.value.some((rule) => rule.required)
+})
+
+// 外部手动状态优先，其次内部校验结果
+const status = computed(() => (props.validateStatus ? props.validateStatus : errors.value.length > 0 ? 'error' : ''))
+const hasError = computed(() => status.value === 'error')
+const helpText = computed(() => errors.value[0] || props.help)
+const showHelp = computed(() => helpText.value !== '')
+
+const labelAlign = computed(
+  () => merged.value.labelAlign ?? form?.labelAlign.value ?? 'left',
+)
+const labelWidth = computed(
+  () => merged.value.labelWidth ?? groupForm?.labelWidth.value ?? form?.labelWidth.value,
+)
+const validateTrigger = computed(() => merged.value.validateTrigger ?? form?.validateTrigger.value ?? 'change')
+
+// Form 已下发回落后的 layout；独立使用（无 Form 包裹）时用组件默认
+const formLayout = computed(
+  () => groupForm?.layout.value ?? form?.layout.value ?? merged.value.layout ?? 'horizontal',
+)
+
+const classes = computed(() => [
+  b(),
+  {
+    [m('vertical')]: formLayout.value === 'vertical',
+    [is('error')]: hasError.value,
+  },
+])
+
+// 横向布局才应用定宽 label；vertical 下 label 自然占一行
+const labelStyle = computed(() => {
+  if (formLayout.value === 'vertical' || labelWidth.value == null) return undefined
+  return { width: typeof labelWidth.value === 'number' ? `${labelWidth.value}px` : labelWidth.value }
+})
+
+// 网格布局（列数 > 1）下跨列：span 超过列数时取整行
+const itemStyle = computed((): Record<string, string> | undefined => {
+  const columns = groupForm?.columns.value ?? form?.columns.value ?? 1
+  if (columns <= 1) return undefined
+  const span = Math.min(Math.max(Number(props.span) || 1, 1), columns)
+  // 行首：写成「从第 1 列起 / 跨 span 列」，网格会把它排到新行的行首
+  if (props.lineStart) return { gridColumn: `1 / span ${span}` }
+  return span > 1 ? { gridColumn: `span ${span}` } : undefined
+})
+
+/** 当前字段在 model 中的值 */
+function fieldValue(): unknown {
+  return form?.model.value?.[fieldName.value]
+}
+
+/* ---------- 校验 ---------- */
+async function runValidation(): Promise<string[]> {
+  if (!hasField.value) return []
+  const nextErrors = await validateRules({
+    label: props.label,
+    value: fieldValue(),
+    rules: mergedRules.value,
+    messages: locale.value.form,
+  })
+  errors.value = nextErrors
+  return nextErrors
+}
+
+/** 供 Form 全量校验调用：提交时必须强制校验 */
+async function validate(): Promise<string[]> {
+  touched.value = true
+  return runValidation()
+}
+
+/** 供 Form 重置调用：清空错误与触碰标记 */
+function clearValidation() {
+  errors.value = []
+  touched.value = false
+}
+
+/* ---------- 校验时机 ---------- */
+// change 触发：值变化即校验。watch 非 immediate，初始值不会触发报红
+watch<[Record<string, unknown> | undefined, unknown]>(
+  () => [form?.model.value, form?.model.value?.[fieldName.value]],
+  (next, prev) => {
+    if (!hasField.value) return
+    const [model, value] = next
+    const prevModel = prev?.[0]
+    const prevValue = prev?.[1]
+    if (validateTrigger.value !== 'change') return
+    // model 对象被父级整体替换（如切换编辑目标）：视为全新表单，清除校验态不报红
+    if (model !== prevModel) {
+      clearValidation()
+      return
+    }
+    // 布尔值由 true 重置为 false（如验证码归零）：视为主动重置，清除校验态
+    if (prevValue === true && value === false) {
+      clearValidation()
+      return
+    }
+    if (!touched.value && isEmptyValue(value)) return
+    touched.value = true
+    void runValidation()
+  },
+)
+
+// blur 触发：焦点移出控件区域后校验。延后一拍，让浮层类控件
+// （Select / DatePicker 面板）的 click 选中先完成再取值校验
+let blurTimer = 0
+function onRootFocusOut(event: FocusEvent) {
+  if (!hasField.value || validateTrigger.value !== 'blur') return
+  const related = event.relatedTarget as Node | null
+  if (related && rootEl.value?.contains(related)) return
+
+  window.clearTimeout(blurTimer)
+  blurTimer = window.setTimeout(() => {
+    // 首次失焦且值为空：仅标记触碰，不报错，避免打开表单即整片报红
+    if (!touched.value && isEmptyValue(fieldValue())) {
+      touched.value = true
+      return
+    }
+    touched.value = true
+    void runValidation()
+  })
+}
+
+/* ---------- 生命周期 ---------- */
+onMounted(() => {
+  if (hasField.value) form?.registerField(fieldName.value, { validate, clearValidation })
+})
+onBeforeUnmount(() => {
+  if (hasField.value) form?.unregisterField(fieldName.value)
+  window.clearTimeout(blurTimer)
+})
+</script>
+
+<template>
+  <div
+    ref="rootEl"
+    :class="classes"
+    :style="itemStyle"
+    :data-field="hasField ? fieldName : undefined"
+    @focusout="onRootFocusOut"
+  >
+    <label
+      v-if="merged.label !== '' || $slots.label"
+      :class="[e('label'), { [m('label-vertical')]: formLayout === 'vertical', [is('label-right')]: labelAlign === 'right' }]"
+      :style="labelStyle"
+    >
+      <span
+        v-if="isRequired && form?.requiredMark.value !== false"
+        :class="e('required')"
+        aria-hidden="true"
+      >
+        *
+      </span>
+      <span :class="e('label-text')">
+        <slot name="label">{{ merged.label }}</slot>
+      </span>
+    </label>
+
+    <div :class="e('control')">
+      <div :class="e('content')">
+        <slot />
+      </div>
+
+      <div
+        v-if="showHelp"
+        :class="[e('help'), { [is('help-error')]: hasError }]"
+        :role="hasError ? 'alert' : undefined"
+      >
+        {{ helpText }}
+      </div>
+      <div v-else-if="merged.extra !== ''" :class="e('extra')">{{ merged.extra }}</div>
+    </div>
+  </div>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+.#{b('form-item')} {
+  display: flex;
+  flex-direction: row;
+  align-items: flex-start;
+  gap: v('space-2', 8px);
+  min-width: 0;
+}
+
+.#{m('form-item', 'vertical')} {
+  flex-direction: column;
+  gap: v('space-1', 4px);
+}
+
+.#{e('form-item', 'label')} {
+  display: inline-flex;
+  align-items: center;
+  gap: 2px;
+  flex-shrink: 0;
+  /* 与控件首行对齐 */
+  min-height: v('control-height', 32px);
+  color: v('text-1', rgba(0, 0, 0, 0.88));
+  font-size: v('font-size', 14px);
+}
+
+.#{e('form-item', 'label')}.#{is('label-right')} {
+  justify-content: flex-end;
+}
+
+.#{m('form-item', 'label-vertical')} {
+  min-height: auto;
+}
+
+.#{e('form-item', 'label-text')} {
+  /* 定宽 label 下不换行：长文案截断成省略号，否则会把整行撑高、与控件错位 */
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+
+.#{e('form-item', 'required')} {
+  color: v('color-danger', #ec4246);
+  line-height: 1;
+}
+
+.#{e('form-item', 'control')} {
+  flex: 1;
+  min-width: 0;
+}
+
+.#{e('form-item', 'help')} {
+  margin-top: v('space-1', 4px);
+  color: v('text-3', rgba(0, 0, 0, 0.45));
+  font-size: v('font-size-sm', 12px);
+  line-height: v('line-height', 1.5);
+}
+
+.#{e('form-item', 'help')}.#{is('help-error')} {
+  color: v('color-danger', #ec4246);
+}
+
+.#{e('form-item', 'extra')} {
+  margin-top: v('space-1', 4px);
+  color: v('text-3', rgba(0, 0, 0, 0.45));
+  font-size: v('font-size-sm', 12px);
+  line-height: v('line-height', 1.5);
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/form/context.ts b/code/g3soft-libs/packages/ui/src/form/context.ts
new file mode 100644
index 00000000..6d8ef798
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/form/context.ts
@@ -0,0 +1,37 @@
+import type { ComputedRef, InjectionKey } from 'vue'
+import type { FormLabelAlign, FormLayout, FormRule, FormValidateTrigger } from './types'
+
+/** FormItem 注册给 Form 的控制器 */
+export interface FormFieldController {
+  /** 立即校验，返回错误消息数组（空数组表示通过） */
+  validate: () => Promise<string[]>
+  /** 清空错误与触碰标记 */
+  clearValidation: () => void
+}
+
+/** Form 通过 provide 下发的上下文 */
+export interface FormContext {
+  model: ComputedRef<Record<string, unknown>>
+  rules: ComputedRef<Record<string, FormRule[]>>
+  layout: ComputedRef<FormLayout>
+  labelAlign: ComputedRef<FormLabelAlign>
+  labelWidth: ComputedRef<string | number | undefined>
+  /** 字段跨列计算用的列数 */
+  columns: ComputedRef<number>
+  requiredMark: ComputedRef<boolean>
+  validateTrigger: ComputedRef<FormValidateTrigger>
+  registerField: (name: string | number, field: FormFieldController) => void
+  unregisterField: (name: string | number) => void
+}
+
+/** FormGroup 通过 provide 下发的组上下文（覆盖外层 Form 的列数与布局） */
+export interface FormGroupContext {
+  /** 组内列数；undefined 表示未指定，由 FormItem 回落到外层 Form 的 columns */
+  columns: ComputedRef<number | undefined>
+  layout: ComputedRef<FormLayout | undefined>
+  labelWidth: ComputedRef<string | number | undefined>
+}
+
+export const formKey: InjectionKey<FormContext> = Symbol('g3-form')
+
+export const formGroupKey: InjectionKey<FormGroupContext> = Symbol('g3-form-group')
diff --git a/code/g3soft-libs/packages/ui/src/form/form-utils.test.ts b/code/g3soft-libs/packages/ui/src/form/form-utils.test.ts
new file mode 100644
index 00000000..5684d3b5
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/form/form-utils.test.ts
@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest'
+import { fluidColumnGap, normalizeGap } from './form-utils'
+
+describe('normalizeGap', () => {
+  it('数字表示行列等距', () => {
+    expect(normalizeGap(8)).toEqual({ row: 8, col: 8 })
+    expect(normalizeGap(0)).toEqual({ row: 0, col: 0 })
+  })
+
+  it('对象原样返回，未传时给空对象', () => {
+    expect(normalizeGap({ row: 4 })).toEqual({ row: 4 })
+    expect(normalizeGap({ col: 12 })).toEqual({ col: 12 })
+    expect(normalizeGap(undefined)).toEqual({})
+  })
+})
+
+describe('fluidColumnGap（列间距防溢出）', () => {
+  it('取 min(px, 100% / (2N))，去掉多余的 0', () => {
+    expect(fluidColumnGap(16, 3)).toBe('min(16px, 16.667%)')
+    expect(fluidColumnGap(16, 2)).toBe('min(16px, 25%)')
+    expect(fluidColumnGap(16, 5)).toBe('min(16px, 10%)')
+    expect(fluidColumnGap(16, 8)).toBe('min(16px, 6.25%)')
+    expect(fluidColumnGap(24, 4)).toBe('min(24px, 12.5%)')
+  })
+
+  it('单列或未配置间距时不产出 gap', () => {
+    expect(fluidColumnGap(16, 1)).toBeUndefined()
+    expect(fluidColumnGap(16, 0)).toBeUndefined()
+    expect(fluidColumnGap(undefined, 3)).toBeUndefined()
+  })
+})
diff --git a/code/g3soft-libs/packages/ui/src/form/form-utils.ts b/code/g3soft-libs/packages/ui/src/form/form-utils.ts
new file mode 100644
index 00000000..134360c3
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/form/form-utils.ts
@@ -0,0 +1,26 @@
+import type { FormGap } from './types'
+
+export interface NormalizedGap {
+  row?: number
+  col?: number
+}
+
+/** gap 归一化：数字 → { row, col }（行 / 列等距），对象原样返回，空值返回 {} */
+export function normalizeGap(gap?: FormGap): NormalizedGap {
+  if (typeof gap === 'number') return { row: gap, col: gap }
+  return gap ?? {}
+}
+
+/**
+ * 列间距防溢出钳制（宫格嵌套场景）。
+ *
+ * grid 的 column-gap 是固定值且不可压缩：N 列宫格有 N-1 个 gap，
+ * 窄容器下轨道可被 minmax(0, 1fr) 压到 0，gap 压不动，总量超出容器宽即横向溢出。
+ * 返回 `min(px, 100% / (2N))`：gap 总量最多占容器约 50%，任何宽度下不会溢出；
+ * 容器够宽时取 px 上限，与固定值视觉一致。
+ */
+export function fluidColumnGap(col: number | undefined, columns: number): string | undefined {
+  if (col == null || !columns || columns <= 1) return undefined
+  const maxPercent = (100 / (columns * 2)).toFixed(3).replace(/\.?0+$/, '')
+  return `min(${col}px, ${maxPercent}%)`
+}
diff --git a/code/g3soft-libs/packages/ui/src/form/index.ts b/code/g3soft-libs/packages/ui/src/form/index.ts
new file mode 100644
index 00000000..c8f14d07
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/form/index.ts
@@ -0,0 +1,19 @@
+export { default as G3Form } from './Form.vue'
+export { default as G3FormItem } from './FormItem.vue'
+export { default as G3FormGroup } from './FormGroup.vue'
+export { formGroupKey, formKey } from './context'
+export type { FormContext, FormFieldController, FormGroupContext } from './context'
+export { fluidColumnGap, normalizeGap } from './form-utils'
+export { isEmptyValue, validateRules } from './validate'
+export type { ValidateRulesOptions } from './validate'
+export type {
+  FormGap,
+  FormGroupProps,
+  FormItemProps,
+  FormItemStatus,
+  FormLabelAlign,
+  FormLayout,
+  FormProps,
+  FormRule,
+  FormValidateTrigger,
+} from './types'
diff --git a/code/g3soft-libs/packages/ui/src/form/types.ts b/code/g3soft-libs/packages/ui/src/form/types.ts
new file mode 100644
index 00000000..916423a9
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/form/types.ts
@@ -0,0 +1,123 @@
+/** 表单布局：horizontal（label 在左）| vertical（label 在上） */
+export type FormLayout = 'horizontal' | 'vertical'
+
+/** label 文本对齐 */
+export type FormLabelAlign = 'left' | 'right'
+
+/** 校验时机：change（值变化即校验）| blur（失焦时校验） */
+export type FormValidateTrigger = 'change' | 'blur'
+
+/** 校验状态 */
+export type FormItemStatus = '' | 'error'
+
+/** 单条校验规则 */
+export interface FormRule {
+  /** 必填 */
+  required?: boolean
+  /** 类型校验 */
+  type?: 'string' | 'number' | 'integer' | 'email' | 'url'
+  /** 正则校验 */
+  pattern?: RegExp
+  /** 长度/数值必须等于 */
+  len?: number
+  /** 长度/数值下限 */
+  min?: number
+  /** 长度/数值上限 */
+  max?: number
+  /** 错误文案；传函数则在每次校验时求值 */
+  message?: string | (() => string)
+  /**
+   * 自定义校验：
+   * - 返回 true / undefined / null → 通过
+   * - 返回 false → 使用 message 或默认文案
+   * - 返回非空字符串 → 该字符串作为错误消息
+   */
+  validator?: (value: unknown, rule: FormRule) => unknown
+}
+
+/** 表单项间距：单个数字表示行 / 列等距，或 { row, col } 分别控制 */
+export type FormGap = number | { row?: number; col?: number }
+
+export interface FormProps {
+  /** 表单数据对象，字段值按 FormItem 的 name 读取 */
+  model: Record<string, unknown>
+  /** 表单级规则：{ [name]: FormRule[] }，FormItem 级 rules 优先级更高 */
+  rules?: Record<string, FormRule[]>
+  /** 布局；不传时回落全局默认值 */
+  layout?: FormLayout
+  /** label 文本对齐方式；不传时回落全局默认值 */
+  labelAlign?: FormLabelAlign
+  /** label 宽度（仅横向布局生效） */
+  labelWidth?: string | number
+  /** 每行字段列数（>1 时启用网格布局，字段按顺序从左到右自动换行） */
+  columns?: number
+  /** 仅影响 FormItem 的 span 计算，不让 Form 自身变 grid（外部栅格 + FormItem 跨列场景） */
+  spanColumns?: number
+  /** 表单最大宽度（Number 按 px 处理） */
+  maxWidth?: string | number
+  /** 必填红星标记 */
+  requiredMark?: boolean
+  /** 校验时机；不传时回落全局默认值 */
+  validateTrigger?: FormValidateTrigger
+  /** 表单项间距 */
+  gap?: FormGap
+}
+
+export interface FormItemProps {
+  /**
+   * 字段名，对应 Form.model 的 key。
+   * 不传时该项只作布局容器：不注册进 Form、不参与校验、也不回填错误提示。
+   */
+  name?: string | number
+  /** 标签文本 */
+  label?: string
+  /** 单项规则；未提供时回退到 Form 级 rules 中同名规则 */
+  rules?: FormRule[]
+  /** 必填标记；未显式指定时从 rules 中推导 */
+  required?: boolean
+  /** 辅助说明文字（置于控件下方） */
+  extra?: string
+  /** 固定提示（校验错误时优先展示错误信息） */
+  help?: string
+  /** 单项 label 对齐方式覆盖 */
+  labelAlign?: FormLabelAlign
+  /** 单项 label 宽度覆盖（仅横向布局生效） */
+  labelWidth?: string | number
+  /** 网格布局下跨列数（不超过所在容器的列数，默认 1） */
+  span?: number
+  /** 行首标记：本字段是所在行的第一个字段（网格布局下强制从第 1 列开始） */
+  lineStart?: boolean
+  /** 外部手动指定校验状态 */
+  validateStatus?: FormItemStatus
+  /** 布局覆盖；一般由 Form 下发，独立使用时可自行指定 */
+  layout?: FormLayout
+  /** 校验时机覆盖；一般由 Form 下发 */
+  validateTrigger?: FormValidateTrigger
+}
+
+export interface FormGroupProps {
+  /** 受控展开态（v-model）；不传时由 defaultExpanded 决定 */
+  modelValue?: boolean
+  /** 是否可折叠：点击标题行切换展开 / 收起 */
+  collapsible?: boolean
+  /** 非受控时的初始展开态 */
+  defaultExpanded?: boolean
+  /**
+   * 组内列数；不传时继承外层 Form 的 columns。
+   * 传 1 可让分组的字段强制单列排布。
+   */
+  columns?: number
+  /** 组内布局（覆盖外层 Form 的 layout） */
+  layout?: FormLayout
+  /** 组内 label 宽度（覆盖外层 Form） */
+  labelWidth?: string | number
+  /** 组内表单项间距（覆盖外层 Form 的 gap） */
+  gap?: FormGap
+  /**
+   * 外层宫格占格数；放在多列 Form 里时生效。
+   * 不传时占满整行（分组通常自成一行）。
+   */
+  span?: number
+  /** 组标题 */
+  title?: string
+}
diff --git a/code/g3soft-libs/packages/ui/src/form/validate.test.ts b/code/g3soft-libs/packages/ui/src/form/validate.test.ts
new file mode 100644
index 00000000..a27c2760
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/form/validate.test.ts
@@ -0,0 +1,119 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { zhCN } from '../locale'
+import type { FormRule } from './types'
+import { isEmptyValue, validateRules } from './validate'
+
+const messages = zhCN.form
+
+function run(value: unknown, rules: FormRule[], label = '用户名') {
+  return validateRules({ label, value, rules, messages })
+}
+
+describe('isEmptyValue', () => {
+  it('undefined / null / 空串视为空，0 与 false 不算空', () => {
+    expect(isEmptyValue(undefined)).toBe(true)
+    expect(isEmptyValue(null)).toBe(true)
+    expect(isEmptyValue('')).toBe(true)
+    expect(isEmptyValue(0)).toBe(false)
+    expect(isEmptyValue(false)).toBe(false)
+    expect(isEmptyValue([])).toBe(false)
+  })
+})
+
+describe('validateRules 静态约束', () => {
+  it('没有规则时直接通过', async () => {
+    await expect(run('任意值', [])).resolves.toEqual([])
+  })
+
+  it('required：空值报「{label}不能为空」，且其余约束不再执行', async () => {
+    const rules: FormRule[] = [{ required: true, type: 'email' }, { min: 6 }]
+    await expect(run('', rules)).resolves.toEqual(['用户名不能为空'])
+    await expect(run(undefined, rules)).resolves.toEqual(['用户名不能为空'])
+  })
+
+  it('非必填约束只在有值时执行：空值跳过，避免与必填重复报错', async () => {
+    await expect(run('', [{ type: 'email' }, { min: 6 }])).resolves.toEqual([])
+  })
+
+  it('label 为空时收掉多余空白，不留前导空格', async () => {
+    await expect(run('', [{ required: true }], '')).resolves.toEqual(['不能为空'])
+  })
+
+  it('type：number / integer 接受数字字符串，email / url 按格式判定', async () => {
+    await expect(run('12.5', [{ type: 'number' }])).resolves.toEqual([])
+    await expect(run('abc', [{ type: 'number' }])).resolves.toEqual(['用户名格式不正确'])
+    await expect(run('1.5', [{ type: 'integer' }])).resolves.toEqual(['用户名格式不正确'])
+    await expect(run('a@b.com', [{ type: 'email' }])).resolves.toEqual([])
+    await expect(run('a@b', [{ type: 'email' }])).resolves.toEqual(['用户名格式不正确'])
+    await expect(run('https://a.com', [{ type: 'url' }])).resolves.toEqual([])
+    await expect(run('ftp://a.com', [{ type: 'url' }])).resolves.toEqual(['用户名格式不正确'])
+  })
+
+  it('pattern 命中失败给出格式文案', async () => {
+    await expect(run('abc', [{ pattern: /^\d+$/ }])).resolves.toEqual(['用户名格式不正确'])
+    await expect(run('123', [{ pattern: /^\d+$/ }])).resolves.toEqual([])
+  })
+
+  it('len / min / max 按「长度」判定：字符串取字符数、数组取项数、数字取数值', async () => {
+    await expect(run('abc', [{ len: 3 }])).resolves.toEqual([])
+    await expect(run('ab', [{ len: 3 }])).resolves.toEqual(['用户名长度必须为 3'])
+    await expect(run('ab', [{ min: 3 }])).resolves.toEqual(['用户名长度不能少于 3'])
+    await expect(run('abcd', [{ max: 3 }])).resolves.toEqual(['用户名长度不能超过 3'])
+    await expect(run(['a', 'b'], [{ min: 3 }])).resolves.toEqual(['用户名长度不能少于 3'])
+    await expect(run(5, [{ min: 10 }])).resolves.toEqual(['用户名长度不能少于 10'])
+  })
+
+  it('一个规则可同时带多个约束，错误全部收集；多规则按顺序拼接', async () => {
+    await expect(run('ab', [{ min: 3, max: 1 }])).resolves.toEqual([
+      '用户名长度不能少于 3',
+      '用户名长度不能超过 1',
+    ])
+    await expect(run('ab', [{ min: 3 }, { pattern: /^\d+$/ }])).resolves.toEqual([
+      '用户名长度不能少于 3',
+      '用户名格式不正确',
+    ])
+  })
+
+  it('message 支持字符串与函数，优先于语言包模板', async () => {
+    await expect(run('', [{ required: true, message: '必须填写用户名' }])).resolves.toEqual([
+      '必须填写用户名',
+    ])
+    await expect(run('', [{ required: true, message: () => '动态文案' }])).resolves.toEqual([
+      '动态文案',
+    ])
+  })
+})
+
+describe('validateRules 自定义 validator', () => {
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('返回 true / undefined / null 视为通过', async () => {
+    await expect(run('x', [{ validator: () => true }])).resolves.toEqual([])
+    await expect(run('x', [{ validator: () => undefined }])).resolves.toEqual([])
+    await expect(run('x', [{ validator: () => null }])).resolves.toEqual([])
+  })
+
+  it('返回 false 用 invalid 文案，返回字符串则作为错误消息', async () => {
+    await expect(run('x', [{ validator: () => false }])).resolves.toEqual(['用户名校验未通过'])
+    await expect(run('x', [{ validator: () => '自定义错误' }])).resolves.toEqual(['自定义错误'])
+  })
+
+  it('支持返回 Promise', async () => {
+    await expect(run('x', [{ validator: async () => false }])).resolves.toEqual([
+      '用户名校验未通过',
+    ])
+  })
+
+  it('validator 抛异常视为校验失败，并保留静态约束的结果', async () => {
+    vi.spyOn(console, 'error').mockImplementation(() => {})
+    const rules: FormRule[] = [{ min: 3 }, { validator: () => { throw new Error('boom') } }]
+    await expect(run('a', rules)).resolves.toEqual(['用户名长度不能少于 3', '用户名校验未通过'])
+  })
+
+  it('validator 与静态约束同时失败时结果合并', async () => {
+    const rules: FormRule[] = [{ min: 3, validator: () => '再补一条' }]
+    await expect(run('a', rules)).resolves.toEqual(['用户名长度不能少于 3', '再补一条'])
+  })
+})
diff --git a/code/g3soft-libs/packages/ui/src/form/validate.ts b/code/g3soft-libs/packages/ui/src/form/validate.ts
new file mode 100644
index 00000000..f647031e
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/form/validate.ts
@@ -0,0 +1,152 @@
+import type { Locale } from '../locale'
+import type { FormRule } from './types'
+
+/**
+ * 轻量表单校验纯函数。
+ *
+ * 按规则逐条执行，返回 Promise<string[]>（空数组表示通过）。
+ * 规则支持：required / type / pattern / len / min / max / validator，
+ * 一个规则对象可同时携带多个约束，错误消息全部收集后返回。
+ */
+
+/** 表单语义下的空值：undefined / null / 空字符串 */
+export function isEmptyValue(value: unknown): boolean {
+  return value === undefined || value === null || value === ''
+}
+
+/** 类型校验器：number / integer 允许数字字符串（如 Input number 模式提交前的字符串中间态） */
+const TYPE_VALIDATORS: Record<string, (value: unknown) => boolean> = {
+  string: (value) => typeof value === 'string',
+  number: (value) => {
+    if (typeof value === 'number') return !Number.isNaN(value)
+    return typeof value === 'string' && value.trim() !== '' && !Number.isNaN(Number(value))
+  },
+  integer: (value) => {
+    if (typeof value === 'number') return Number.isInteger(value)
+    return typeof value === 'string' && value.trim() !== '' && Number.isInteger(Number(value))
+  },
+  email: (value) => typeof value === 'string' && /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value),
+  url: (value) => typeof value === 'string' && /^https?:\/\/[^\s]+$/i.test(value),
+}
+
+/** 值的「长度」：字符串取字符数，数组取项数，数字取数值本身 */
+function measure(value: unknown): number | undefined {
+  if (typeof value === 'string' || Array.isArray(value)) return value.length
+  if (typeof value === 'number') return value
+  return undefined
+}
+
+/** 替换 `{label}` / `{len}` 等占位符；label 为空时收掉多余空白 */
+function format(template: string, params: Record<string, string | number | undefined>): string {
+  let output = template
+  for (const [key, value] of Object.entries(params)) {
+    output = output.split(`{${key}}`).join(value == null ? '' : String(value))
+  }
+  return output.replace(/\s{2,}/g, ' ').trim()
+}
+
+type MessageKind = keyof Locale['form']
+
+/** 解析规则错误消息：message 支持字符串或函数，未配置时回退到语言包模板 */
+function resolveMessage(
+  rule: FormRule,
+  label: string,
+  kind: MessageKind,
+  messages: Locale['form'],
+  params: Record<string, string | number | undefined> = {},
+): string {
+  const raw = typeof rule.message === 'function' ? rule.message() : rule.message
+  if (raw != null && raw !== '') return raw
+  return format(messages[kind], { label, ...params })
+}
+
+/** 执行规则中的静态约束（required / type / pattern / len / min / max） */
+function validateStatic(
+  rule: FormRule,
+  label: string,
+  value: unknown,
+  messages: Locale['form'],
+): string[] {
+  // 必填失败：空值直接返回，其余约束不再执行
+  if (rule.required && isEmptyValue(value)) {
+    return [resolveMessage(rule, label, 'required', messages)]
+  }
+
+  // 非必填约束只在有值时执行，避免「必填」与「格式」重复报错
+  if (isEmptyValue(value)) return []
+
+  const errors: string[] = []
+
+  if (rule.type && !TYPE_VALIDATORS[rule.type]?.(value)) {
+    errors.push(resolveMessage(rule, label, 'type', messages))
+  }
+
+  if (rule.pattern && !rule.pattern.test(String(value))) {
+    errors.push(resolveMessage(rule, label, 'pattern', messages))
+  }
+
+  const length = measure(value)
+  if (length !== undefined) {
+    if (rule.len !== undefined && length !== rule.len) {
+      errors.push(resolveMessage(rule, label, 'len', messages, { len: rule.len }))
+    }
+    if (rule.min !== undefined && length < rule.min) {
+      errors.push(resolveMessage(rule, label, 'min', messages, { min: rule.min }))
+    }
+    if (rule.max !== undefined && length > rule.max) {
+      errors.push(resolveMessage(rule, label, 'max', messages, { max: rule.max }))
+    }
+  }
+
+  return errors
+}
+
+/** 执行自定义 validator，失败 / 抛异常都归一成错误消息 */
+function runValidator(
+  rule: FormRule,
+  label: string,
+  value: unknown,
+  messages: Locale['form'],
+  staticErrors: string[],
+): Promise<string[]> {
+  const fallbackError = resolveMessage(rule, label, 'invalid', messages)
+  return Promise.resolve()
+    .then(() => rule.validator?.(value, rule))
+    .then((verdict) => {
+      if (verdict === true || verdict === undefined || verdict === null) return staticErrors
+      if (verdict === false) return [...staticErrors, fallbackError]
+      return [...staticErrors, String(verdict)]
+    })
+    .catch((error: unknown) => {
+      // validator 抛出的异常视为校验失败，避免整表提交被中断
+      console.error('[g3-form] validator 执行异常：', error)
+      return [...staticErrors, fallbackError]
+    })
+}
+
+export interface ValidateRulesOptions {
+  /** 字段标签，用于拼接错误消息 */
+  label?: string
+  /** 字段当前值 */
+  value?: unknown
+  /** 规则列表 */
+  rules?: FormRule[]
+  /** 校验文案模板（来自语言包） */
+  messages: Locale['form']
+}
+
+/** 执行一组规则，返回错误消息数组（空数组表示通过） */
+export function validateRules(options: ValidateRulesOptions): Promise<string[]> {
+  const { label = '', value, rules = [], messages } = options
+  if (!Array.isArray(rules) || rules.length === 0) return Promise.resolve([])
+
+  return Promise.all(
+    rules.map((rule) => {
+      const staticErrors = validateStatic(rule, label, value, messages)
+      if (typeof rule?.validator === 'function') {
+        return runValidator(rule, label, value, messages, staticErrors)
+      }
+      return Promise.resolve(staticErrors)
+    }),
+  ).then((groups) => groups.flat())
+}
diff --git a/code/g3soft-libs/packages/ui/src/grid/Col.vue b/code/g3soft-libs/packages/ui/src/grid/Col.vue
new file mode 100644
index 00000000..bbbb6172
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/grid/Col.vue
@@ -0,0 +1,48 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import { useNamespace } from '../_composables/useNamespace'
+import type { ColProps } from './types'
+
+/**
+ * Grid 栅格列 —— 24 栅格布局的单元格，必须放在 G3Row 内使用。
+ *
+ * 宽度按 span / 24 的百分比计算；使用 flex 时不再套用 span 的百分比宽度，避免两者冲突。
+ */
+defineOptions({ name: 'G3Col' })
+
+const props = withDefaults(defineProps<ColProps>(), {
+  span: undefined,
+  offset: undefined,
+  order: undefined,
+  push: undefined,
+  pull: undefined,
+  flex: undefined,
+})
+
+const { b } = useNamespace('col')
+
+/** 使用 flex 时不再套用基于 span 的百分比宽度（避免与 flex 冲突） */
+const hasFlex = computed(() => props.flex !== undefined)
+
+const classes = computed(() => [
+  b(),
+  props.span !== undefined && !hasFlex.value ? `${b()}-${props.span}` : '',
+  props.offset !== undefined ? `${b()}-offset-${props.offset}` : '',
+  props.order !== undefined ? `${b()}-order-${props.order}` : '',
+  props.push !== undefined ? `${b()}-push-${props.push}` : '',
+  props.pull !== undefined ? `${b()}-pull-${props.pull}` : '',
+])
+
+const style = computed((): Record<string, string> => {
+  if (props.flex === undefined) return {}
+  const flex = props.flex
+  if (typeof flex === 'number') return { flex: `${flex} ${flex} auto` }
+  return { flex: String(flex) }
+})
+</script>
+
+<template>
+  <div :class="classes" :style="style">
+    <slot />
+  </div>
+</template>
diff --git a/code/g3soft-libs/packages/ui/src/grid/Row.vue b/code/g3soft-libs/packages/ui/src/grid/Row.vue
new file mode 100644
index 00000000..dbd8a72c
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/grid/Row.vue
@@ -0,0 +1,174 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import { useNamespace } from '../_composables/useNamespace'
+import type { RowProps } from './types'
+
+/**
+ * Grid 栅格行 —— 24 栅格布局的容器，配合 G3Col 使用。
+ *
+ * 间距由 CSS 变量 `--g3-row-gutter-h` / `--g3-row-gutter-v` 下传给 Col：
+ * Row 用负 margin 抵消 Col 的对称 padding，从而让内容仍是左右对齐的。
+ */
+defineOptions({ name: 'G3Row' })
+
+const props = withDefaults(defineProps<RowProps>(), {
+  gutter: 0,
+  align: undefined,
+  justify: undefined,
+  wrap: true,
+})
+
+const { b, m, cssVar } = useNamespace('row')
+
+const gutterStyle = computed<Record<string, number>>(() => {
+  const gutter = props.gutter
+  if (Array.isArray(gutter)) {
+    return {
+      [cssVar('gutter-h')]: Number(gutter[0]) || 0,
+      [cssVar('gutter-v')]: Number(gutter[1]) || 0,
+    }
+  }
+  const value = Number(gutter) || 0
+  return {
+    [cssVar('gutter-h')]: value,
+    [cssVar('gutter-v')]: value,
+  }
+})
+
+const classes = computed(() => [
+  b(),
+  !props.wrap ? m('no-wrap') : '',
+  props.align ? m(`align-${props.align}`) : '',
+  props.justify ? m(`justify-${props.justify}`) : '',
+])
+</script>
+
+<template>
+  <div :class="classes" :style="gutterStyle">
+    <slot />
+  </div>
+</template>
+
+<style lang="scss">
+@use 'sass:math';
+@use '@g3soft/tokens/scss' as *;
+
+$cols: 24;
+
+.#{b('row')} {
+  display: flex;
+  flex-flow: row wrap;
+  /* 防止被外层 flex 容器压缩 / 拉伸 */
+  width: 100%;
+
+  /* Row 通过内联 style 写这两个变量（纯数字），Col 读它们做对称 padding */
+  #{css-var('gutter-h')}: 0;
+  #{css-var('gutter-v')}: 0;
+
+  margin-left: calc(#{v('gutter-h', 0)} / -2);
+  margin-right: calc(#{v('gutter-h', 0)} / -2);
+  row-gap: calc(#{v('gutter-v', 0)} * 1px);
+}
+
+.#{m('row', 'no-wrap')} {
+  flex-wrap: nowrap;
+}
+
+.#{m('row', 'align-top')} {
+  align-items: flex-start;
+}
+
+.#{m('row', 'align-middle')} {
+  align-items: center;
+}
+
+.#{m('row', 'align-bottom')} {
+  align-items: flex-end;
+}
+
+.#{m('row', 'align-stretch')} {
+  align-items: stretch;
+}
+
+.#{m('row', 'justify-start')} {
+  justify-content: flex-start;
+}
+
+.#{m('row', 'justify-end')} {
+  justify-content: flex-end;
+}
+
+.#{m('row', 'justify-center')} {
+  justify-content: center;
+}
+
+.#{m('row', 'justify-space-around')} {
+  justify-content: space-around;
+}
+
+.#{m('row', 'justify-space-between')} {
+  justify-content: space-between;
+}
+
+.#{m('row', 'justify-space-evenly')} {
+  justify-content: space-evenly;
+}
+
+.#{b('col')} {
+  box-sizing: border-box;
+  /* 防止内容撑破 flex 列 */
+  min-width: 0;
+  padding-left: calc(#{v('gutter-h', 0)} / 2);
+  padding-right: calc(#{v('gutter-h', 0)} / 2);
+}
+
+/* 24 栅格宽度 */
+@for $n from 0 through $cols {
+  .#{b('col')}-#{$n} {
+    @if $n == 0 {
+      display: none;
+    } @else {
+      display: block;
+      flex: 0 0 math.percentage(math.div($n, $cols));
+      max-width: math.percentage(math.div($n, $cols));
+    }
+  }
+}
+
+/* offset 左偏移 */
+@for $n from 0 through $cols {
+  .#{b('col')}-offset-#{$n} {
+    margin-left: math.percentage(math.div($n, $cols));
+  }
+}
+
+/* order 排序 */
+@for $n from 0 through $cols {
+  .#{b('col')}-order-#{$n} {
+    order: $n;
+  }
+}
+
+/* push 右移 / pull 左移（相对定位，不脱离文档流） */
+@for $n from 0 through $cols {
+  .#{b('col')}-push-#{$n} {
+    @if $n == 0 {
+      position: static;
+      left: auto;
+    } @else {
+      position: relative;
+      left: math.percentage(math.div($n, $cols));
+    }
+  }
+
+  .#{b('col')}-pull-#{$n} {
+    @if $n == 0 {
+      position: static;
+      right: auto;
+    } @else {
+      position: relative;
+      right: math.percentage(math.div($n, $cols));
+    }
+  }
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/grid/index.ts b/code/g3soft-libs/packages/ui/src/grid/index.ts
new file mode 100644
index 00000000..364a86e0
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/grid/index.ts
@@ -0,0 +1,3 @@
+export { default as G3Row } from './Row.vue'
+export { default as G3Col } from './Col.vue'
+export type { ColProps, GridGutter, RowAlign, RowJustify, RowProps } from './types'
diff --git a/code/g3soft-libs/packages/ui/src/grid/types.ts b/code/g3soft-libs/packages/ui/src/grid/types.ts
new file mode 100644
index 00000000..1ae11581
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/grid/types.ts
@@ -0,0 +1,40 @@
+/** 栅格间距：数字（水平=垂直）或 [水平, 垂直] */
+export type GridGutter = number | [number, number]
+
+/** 交叉轴对齐 */
+export type RowAlign = 'top' | 'middle' | 'bottom' | 'stretch'
+
+/** 主轴对齐 */
+export type RowJustify =
+  | 'start'
+  | 'end'
+  | 'center'
+  | 'space-around'
+  | 'space-between'
+  | 'space-evenly'
+
+export interface RowProps {
+  /** 栅格间距（px）：数字（水平=垂直）或 [水平, 垂直] */
+  gutter?: GridGutter
+  /** 交叉轴对齐 */
+  align?: RowAlign
+  /** 主轴对齐 */
+  justify?: RowJustify
+  /** 是否换行 */
+  wrap?: boolean
+}
+
+export interface ColProps {
+  /** 栅格占位格数 0-24 */
+  span?: number | string
+  /** 左侧偏移格数 */
+  offset?: number | string
+  /** 排序 */
+  order?: number | string
+  /** 右移格数 */
+  push?: number | string
+  /** 左移格数 */
+  pull?: number | string
+  /** flex 布局属性：数字（flex-grow）或 CSS flex 简写 */
+  flex?: number | string
+}
diff --git a/code/g3soft-libs/packages/ui/src/index.ts b/code/g3soft-libs/packages/ui/src/index.ts
index c67f819f..498d2400 100644
--- a/code/g3soft-libs/packages/ui/src/index.ts
+++ b/code/g3soft-libs/packages/ui/src/index.ts
@@ -1,14 +1,64 @@
 import type { App, Plugin } from 'vue'
-import G3Button from './button/Button.vue'
-import G3ConfigProvider from './config-provider/ConfigProvider.vue'
 import { setGlobalConfig, type GlobalConfig } from './_utils/global-config'
 import { setBaseZIndex } from './_utils/z-index'
 
-export { G3Button }
-export { G3ConfigProvider }
-export type { ButtonProps, ButtonSize, ButtonType } from './button/types'
+// ---------------- 组件 ----------------
+import { G3Button } from './button'
+import { G3ButtonGroup, G3ButtonGroupSeparator } from './button-group'
+import { G3Checkbox } from './checkbox'
+import { G3CalendarPanel, G3DatePicker, G3RangePicker, G3TimeSelect } from './date'
+import { G3Drawer } from './drawer'
+import { G3Dropdown, G3DropdownItem } from './dropdown'
+import { G3Form, G3FormGroup, G3FormItem } from './form'
+import { G3Col, G3Row } from './grid'
+import { G3Input } from './input'
+import { G3MessageContainer } from './message'
+import { G3Modal } from './modal'
+import { G3NotificationContainer } from './notification'
+import { G3Pagination } from './pagination'
+import { G3Popover } from './popover'
+import { G3Radio, G3RadioGroup } from './radio'
+import { G3Scrollbar } from './scrollbar'
+import { G3Segmented } from './segmented'
+import { G3Select } from './select'
+import { G3Space } from './space'
+import { G3Spin } from './spin'
+import { G3Splitter, G3SplitterPanel } from './splitter'
+import { G3Switch } from './switch'
+import { G3TabPane, G3Tabs } from './tabs'
+import { G3Tag } from './tag'
+import { G3Tooltip } from './tooltip'
+import { G3Tree } from './tree'
 
-// ConfigProvider / config
+export * from './button'
+export * from './button-group'
+export * from './checkbox'
+export * from './date'
+export * from './drawer'
+export * from './dropdown'
+export * from './form'
+export * from './grid'
+export * from './input'
+export * from './message'
+export * from './modal'
+export * from './notification'
+export * from './pagination'
+export * from './popover'
+export * from './radio'
+export * from './scrollbar'
+export * from './segmented'
+export * from './select'
+export * from './space'
+export * from './spin'
+export * from './splitter'
+export * from './switch'
+export * from './tabs'
+export * from './tag'
+export * from './tooltip'
+export * from './tree'
+export * from './config-provider'
+
+// ConfigProvider / config（桶文件已导出，这里补齐历史具名出口）
 export { configProviderKey, useConfig } from './config-provider/context'
 export type { ConfigContext } from './config-provider/context'
 export type { ConfigProviderProps, G3ThemeConfig, ThemeScope } from './config-provider/types'
@@ -17,12 +67,42 @@ export type { ConfigProviderProps, G3ThemeConfig, ThemeScope } from './config-pr
 export { useNamespace, COMPILE_TIME_NAMESPACE, COMPILE_TIME_STATE_PREFIX } from './_composables/useNamespace'
 export type { UseNamespaceReturn } from './_composables/useNamespace'
 export { useLocale } from './_composables/useLocale'
+export { useComponentDefaults } from './_composables/useComponentDefaults'
+export { useFloating } from './_composables/useFloating'
+export type { UseFloatingOptions, UseFloatingReturn } from './_composables/useFloating'
+export { useUnwrappedTrigger } from './_composables/useUnwrappedTrigger'
+export type {
+  UseUnwrappedTriggerOptions,
+  UseUnwrappedTriggerReturn,
+} from './_composables/useUnwrappedTrigger'
+export { usePopupContainer, resolvePopupContainer } from './_composables/usePopupContainer'
 
 // utils
 export { getGlobalConfig, setGlobalConfig } from './_utils/global-config'
 export type { GlobalConfig, PopupContainer } from './_utils/global-config'
-export { getBaseZIndex, nextZIndex, resetZIndex, setBaseZIndex } from './_utils/z-index'
+export {
+  getBaseZIndex,
+  nextZIndex,
+  releaseZIndex,
+  resetZIndex,
+  setBaseZIndex,
+} from './_utils/z-index'
+export type { ZIndexLayer } from './_utils/z-index'
 export { derivePalette } from './_utils/color'
+export { computePosition, getViewport, PLACEMENTS, VIEWPORT_MARGIN } from './_utils/position'
+export type {
+  ComputePositionOptions,
+  ComputePositionResult,
+  Placement,
+  PlacementAlign,
+  PlacementBase,
+  RectLike,
+  SizeLike,
+} from './_utils/position'
+export { focusFirst, getFocusable, trapFocus } from './_utils/focus'
+export { getScrollLockCount, lockScroll, unlockScroll } from './_utils/scroll'
+export { bindDrag, bindResize } from './_utils/drag'
+export type { BindDragOptions, BindResizeOptions, DragHandle, ResizeHandle } from './_utils/drag'
 
 // locale
 export { enUS, zhCN } from './locale'
@@ -30,7 +110,45 @@ export type { Locale } from './locale'
 
 export interface G3UIOptions extends GlobalConfig {}
 
-const components = { G3Button, G3ConfigProvider }
+const components = {
+  G3Button,
+  G3ButtonGroup,
+  G3ButtonGroupSeparator,
+  G3CalendarPanel,
+  G3Checkbox,
+  G3Col,
+  G3DatePicker,
+  G3Drawer,
+  G3Dropdown,
+  G3DropdownItem,
+  G3Form,
+  G3FormGroup,
+  G3FormItem,
+  G3Input,
+  G3MessageContainer,
+  G3Modal,
+  G3NotificationContainer,
+  G3Pagination,
+  G3Popover,
+  G3Radio,
+  G3RadioGroup,
+  G3RangePicker,
+  G3Row,
+  G3Scrollbar,
+  G3Segmented,
+  G3Select,
+  G3Space,
+  G3Spin,
+  G3Splitter,
+  G3SplitterPanel,
+  G3Switch,
+  G3TabPane,
+  G3Tabs,
+  G3Tag,
+  G3TimeSelect,
+  G3Tooltip,
+  G3Tree,
+}
 
 function applyConfig(options: G3UIOptions): void {
   setGlobalConfig(options)
@@ -41,7 +159,7 @@ function applyConfig(options: G3UIOptions): void {
  * 可选的全量注册插件。
  * 按需 import 是主路径；这里只是为不熟悉按需引入的团队提供便利入口。
  *
- * 函数式调用（Message.xxx() 等组件树外实例）拿不到 inject 上下文，
+ * 函数式调用（G3Message.xxx() 等组件树外实例）拿不到 inject 上下文，
  * 用 G3UI.config({ namespace }) 或 app.use(G3UI, { namespace }) 写入全局兜底。
  */
 export const G3UI: Plugin & { config: (options?: G3UIOptions) => void } = {
diff --git a/code/g3soft-libs/packages/ui/src/input/Input.test.ts b/code/g3soft-libs/packages/ui/src/input/Input.test.ts
new file mode 100644
index 00000000..0b147841
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/input/Input.test.ts
@@ -0,0 +1,126 @@
+import { mount } from '@vue/test-utils'
+import { describe, expect, it } from 'vitest'
+import G3Input from './Input.vue'
+
+function mountInput(props: Record<string, unknown> = {}) {
+  return mount(G3Input, { props: { modelValue: '', ...props } })
+}
+
+describe('Input 单行模式', () => {
+  it('输入即同步 v-model', async () => {
+    const wrapper = mountInput()
+    await wrapper.find('input').setValue('你好')
+
+    expect(wrapper.emitted('update:modelValue')?.at(-1)).toEqual(['你好'])
+  })
+
+  it('password 模式可切换明文，切换按钮带 aria 状态', async () => {
+    const wrapper = mountInput({ type: 'password', modelValue: '123456' })
+
+    expect(wrapper.find('input').attributes('type')).toBe('password')
+    const toggle = wrapper.find('.g3-input__password-toggle')
+    expect(toggle.attributes('aria-pressed')).toBe('false')
+
+    await toggle.trigger('click')
+    expect(wrapper.find('input').attributes('type')).toBe('text')
+    expect(wrapper.find('.g3-input__password-toggle').attributes('aria-pressed')).toBe('true')
+  })
+
+  it('number 模式输入时净化（只留一个小数点），失焦时才提交数字', async () => {
+    const wrapper = mountInput({ type: 'number', modelValue: '' })
+    const input = wrapper.find('input')
+
+    await input.setValue('12.3.4')
+    // 净化后的十进制值；setValue 可能同时触发 change（提交为 Number），故统一按字符串比对
+    expect(String(wrapper.emitted('update:modelValue')?.at(-1)?.[0])).toBe('12.34')
+
+    await input.setValue('12.5')
+    await input.trigger('blur')
+    expect(wrapper.emitted('update:modelValue')?.at(-1)).toEqual([12.5])
+  })
+
+  it('number 模式的空值保持空串，不变成 0', async () => {
+    const wrapper = mountInput({ type: 'number', modelValue: 5 })
+    const input = wrapper.find('input')
+
+    await input.setValue('')
+    await input.trigger('blur')
+    expect(wrapper.emitted('update:modelValue')?.at(-1)).toEqual([''])
+  })
+
+  it('status=error 输出 aria-invalid，禁用态使用 g3-input--disabled 修饰类', () => {
+    const wrapper = mountInput({ status: 'error' })
+    expect(wrapper.find('input').attributes('aria-invalid')).toBe('true')
+
+    const disabled = mountInput({ disabled: true })
+    expect(disabled.classes()).toContain('g3-input--disabled')
+    expect(disabled.find('input').attributes('disabled')).toBeDefined()
+  })
+})
+
+describe('Input 清除与计数', () => {
+  it('allowClear：聚焦且有值时出现清除按钮，点击后清空并 emit clear', async () => {
+    const wrapper = mountInput({ allowClear: true, modelValue: 'abc' })
+    expect(wrapper.find('.g3-input__clear').exists()).toBe(false)
+
+    await wrapper.find('input').trigger('focus')
+    const clear = wrapper.find('.g3-input__clear')
+    expect(clear.exists()).toBe(true)
+
+    await clear.trigger('click')
+    expect(wrapper.emitted('update:modelValue')?.at(-1)).toEqual([''])
+    expect(wrapper.emitted('clear')).toHaveLength(1)
+  })
+
+  it('showCount 显示「当前 / 上限」，无上限时只显示当前', async () => {
+    const withMax = mountInput({ showCount: true, maxlength: 20, modelValue: 'abcd' })
+    expect(withMax.find('.g3-input__count').text()).toBe('4 / 20')
+
+    const noMax = mountInput({ showCount: true, modelValue: 'ab' })
+    expect(noMax.find('.g3-input__count').text()).toBe('2')
+  })
+})
+
+describe('Input 多行模式', () => {
+  it('渲染 textarea 并按 rows 设置行数', () => {
+    const wrapper = mountInput({ type: 'textarea', rows: 5 })
+    const textarea = wrapper.find('textarea')
+
+    expect(textarea.exists()).toBe(true)
+    expect(textarea.attributes('rows')).toBe('5')
+    expect(wrapper.find('input').exists()).toBe(false)
+  })
+
+  it('footer 内提供拖拽手柄（role=slider）与字数统计', () => {
+    const wrapper = mountInput({ type: 'textarea', showCount: true, maxlength: 100, modelValue: 'abc' })
+    const handle = wrapper.find('.g3-input__resize-handle')
+
+    expect(handle.attributes('role')).toBe('slider')
+    expect(handle.attributes('aria-orientation')).toBe('vertical')
+    expect(wrapper.find('.g3-input__count').text()).toBe('3 / 100')
+  })
+
+  it('多行模式不渲染单行的清除按钮与前缀插槽位置', () => {
+    const wrapper = mountInput({ type: 'textarea', allowClear: true, modelValue: 'abc' })
+    expect(wrapper.find('.g3-input__clear').exists()).toBe(false)
+  })
+
+  it('只读 / 禁用时不出现拖拽手柄', () => {
+    expect(mountInput({ type: 'textarea', readonly: true }).find('.g3-input__resize-handle').exists()).toBe(false)
+    expect(mountInput({ type: 'textarea', disabled: true }).find('.g3-input__resize-handle').exists()).toBe(false)
+  })
+})
+
+describe('Input 暴露的方法', () => {
+  it('focus / select / blur 可调用且不抛错', () => {
+    const wrapper = mountInput({ modelValue: 'abc' })
+    const vm = wrapper.vm as unknown as { focus: () => void; select: () => void; blur: () => void }
+
+    expect(() => vm.focus()).not.toThrow()
+    expect(() => vm.select()).not.toThrow()
+    expect(() => vm.blur()).not.toThrow()
+
+    const textarea = mountInput({ type: 'textarea', modelValue: 'abc' })
+    expect(() => (textarea.vm as unknown as { focus: () => void }).focus()).not.toThrow()
+  })
+})
diff --git a/code/g3soft-libs/packages/ui/src/input/Input.vue b/code/g3soft-libs/packages/ui/src/input/Input.vue
new file mode 100644
index 00000000..f07153af
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/input/Input.vue
@@ -0,0 +1,583 @@
+<script setup lang="ts">
+import { computed, nextTick, onBeforeUnmount, onMounted, ref, useSlots, watch } from 'vue'
+import { Eye, EyeOff, MoveDiagonal2, X } from '@lucide/vue'
+import { useLocale } from '../_composables/useLocale'
+import { useNamespace } from '../_composables/useNamespace'
+import type { InputFocusOptions, InputProps } from './types'
+
+/**
+ * 输入框 —— 支持单行 / 密码 / 数字 / 多行四种模式，以及清除、字数统计、前后缀插槽。
+ *
+ * 多行模式自带右下角高度拖拽手柄（可拖拽与方向键调整），不改变内部滚动行为。
+ */
+defineOptions({ name: 'G3Input' })
+
+const props = withDefaults(defineProps<InputProps>(), {
+  modelValue: '',
+  type: 'default',
+  disabled: false,
+  readonly: false,
+  status: '',
+  allowClear: false,
+  showCount: false,
+  maxlength: undefined,
+  rows: 3,
+  placeholder: undefined,
+  autocomplete: undefined,
+})
+
+const emit = defineEmits<{
+  'update:modelValue': [value: string | number]
+  change: [value: string | number, ev: Event]
+  focus: [ev: FocusEvent]
+  blur: [ev: FocusEvent]
+  clear: []
+}>()
+
+const slots = useSlots()
+const { b, e, m, is } = useNamespace('input')
+const locale = useLocale()
+
+const focused = ref(false)
+const hovered = ref(false)
+const inputEl = ref<HTMLInputElement | null>(null)
+const textareaEl = ref<HTMLTextAreaElement | null>(null)
+
+const isTextarea = computed(() => props.type === 'textarea')
+const isPassword = computed(() => props.type === 'password' && !isTextarea.value)
+const isNumber = computed(() => props.type === 'number')
+
+/** 保留小数输入中的中间态（例如 "12."），避免用户输入小数点时被立即截断 */
+function normalizeNumberValue(value: string): string {
+  const normalized = value.replace(/[^\d.]/g, '')
+  const firstDot = normalized.indexOf('.')
+  if (firstDot === -1) return normalized
+  return `${normalized.slice(0, firstDot + 1)}${normalized.slice(firstDot + 1).replace(/\./g, '')}`
+}
+
+/** 提交时直接转为 Number；空值单独保留，避免 Number('') 变成 0 */
+function toCommittedNumberValue(value: string): string | number {
+  const normalized = normalizeNumberValue(value)
+  if (!normalized || normalized === '.') return ''
+  return Number(normalized)
+}
+
+const inputValue = computed(() =>
+  isNumber.value ? normalizeNumberValue(String(props.modelValue ?? '')) : props.modelValue,
+)
+
+const hasValue = computed(() => String(inputValue.value ?? '').length > 0)
+const showClear = computed(
+  () =>
+    props.allowClear &&
+    !props.disabled &&
+    !props.readonly &&
+    hasValue.value &&
+    (focused.value || hovered.value) &&
+    !isTextarea.value,
+)
+const hasTextareaFooter = computed(() => isTextarea.value && (props.showCount || showResize.value))
+
+const countText = computed(() => {
+  const length = String(isTextarea.value ? props.modelValue ?? '' : inputValue.value ?? '').length
+  return props.maxlength != null ? `${length} / ${props.maxlength}` : `${length}`
+})
+
+const classes = computed(() => [
+  b(),
+  {
+    [m('textarea')]: isTextarea.value,
+    [m('disabled')]: props.disabled,
+    [m('readonly')]: props.readonly,
+    [m('focused')]: focused.value,
+    // 有 footer（计数 / 拖拽手柄）时给 textarea 留出底部避让空间
+    [is('textarea-with-footer')]: hasTextareaFooter.value,
+    [props.status ? m(props.status) : '']: !!props.status,
+  },
+])
+
+/* ---------- 事件 ---------- */
+function sanitizeNumberInput(target: HTMLInputElement): string {
+  const value = target.value
+  const selectionStart = target.selectionStart ?? value.length
+  const nextValue = normalizeNumberValue(value)
+  if (value !== nextValue) {
+    const nextSelection = normalizeNumberValue(value.slice(0, selectionStart)).length
+    target.value = nextValue
+    target.setSelectionRange(nextSelection, nextSelection)
+  }
+  return nextValue
+}
+
+function getInputValue(target: HTMLInputElement): string {
+  return isNumber.value ? sanitizeNumberInput(target) : target.value
+}
+
+function commitNumberInput(target: HTMLInputElement): string | number {
+  const nextValue = toCommittedNumberValue(target.value)
+  const displayValue = nextValue === '' ? '' : String(nextValue)
+  if (target.value !== displayValue) target.value = displayValue
+  if (!Object.is(nextValue, props.modelValue)) emit('update:modelValue', nextValue)
+  return nextValue
+}
+
+function onInput(event: Event) {
+  const target = event.target as HTMLInputElement
+  emit('update:modelValue', getInputValue(target))
+}
+
+function onChange(event: Event) {
+  const target = event.target as HTMLInputElement
+  const value = isNumber.value ? commitNumberInput(target) : getInputValue(target)
+  emit('change', value, event)
+}
+
+function onFocus(event: FocusEvent) {
+  focused.value = true
+  emit('focus', event)
+}
+
+function onBlur(event: FocusEvent) {
+  if (isNumber.value) commitNumberInput(event.target as HTMLInputElement)
+  focused.value = false
+  emit('blur', event)
+}
+
+function clear() {
+  emit('update:modelValue', '')
+  emit('clear')
+}
+
+/* ---------- password 模式 ---------- */
+const revealed = ref(false)
+const inputType = computed(() => (isPassword.value && !revealed.value ? 'password' : 'text'))
+
+/* ---------- textarea 高度拖拽 ---------- */
+const defaultTextareaHeight = ref(0)
+const textareaHeight = ref<number | null>(null)
+const showResize = computed(() => isTextarea.value && !props.disabled && !props.readonly)
+const textareaStyle = computed(() =>
+  textareaHeight.value == null ? undefined : { height: `${textareaHeight.value}px` },
+)
+
+function measureDefaultTextareaHeight() {
+  if (!textareaEl.value || textareaHeight.value != null) return
+  defaultTextareaHeight.value = textareaEl.value.offsetHeight
+}
+
+// 拖拽状态只在交互期间保存，避免每次 pointermove 都触发组件重渲染
+let resizeStartY = 0
+let resizeStartH = 0
+let resizePrevUserSelect = ''
+let resizeMoved = false
+let resizeActive = false
+let resizeFrame = 0
+let pendingResizeHeight: number | null = null
+
+function flushResizeFrame() {
+  if (resizeFrame) {
+    cancelAnimationFrame(resizeFrame)
+    resizeFrame = 0
+  }
+  if (pendingResizeHeight != null) {
+    textareaHeight.value = pendingResizeHeight
+    pendingResizeHeight = null
+  }
+}
+
+function stopResizeTracking() {
+  flushResizeFrame()
+  if (!resizeActive) return
+  document.removeEventListener('pointermove', onResizeMove)
+  document.removeEventListener('pointerup', onResizeEnd)
+  document.removeEventListener('pointercancel', onResizeEnd)
+  document.body.style.userSelect = resizePrevUserSelect
+  resizePrevUserSelect = ''
+  resizeMoved = false
+  resizeActive = false
+}
+
+function onResizeStart(event: PointerEvent) {
+  if (!textareaEl.value) return
+  event.preventDefault()
+  event.stopPropagation()
+  stopResizeTracking()
+  resizeStartY = event.clientY
+  resizeStartH = textareaEl.value.offsetHeight
+  resizeMoved = false
+  resizeActive = true
+  resizePrevUserSelect = document.body.style.userSelect
+  document.body.style.userSelect = 'none'
+  document.addEventListener('pointermove', onResizeMove)
+  document.addEventListener('pointerup', onResizeEnd)
+  document.addEventListener('pointercancel', onResizeEnd)
+}
+
+function onResizeMove(event: PointerEvent) {
+  if (!resizeActive || !textareaEl.value) return
+  const delta = event.clientY - resizeStartY
+  if (!resizeMoved && Math.abs(delta) < 2) return
+  resizeMoved = true
+  const minHeight = defaultTextareaHeight.value || resizeStartH
+  pendingResizeHeight = Math.max(minHeight, resizeStartH + delta)
+  if (!resizeFrame) {
+    resizeFrame = requestAnimationFrame(() => {
+      resizeFrame = 0
+      if (pendingResizeHeight != null) {
+        textareaHeight.value = pendingResizeHeight
+        pendingResizeHeight = null
+      }
+    })
+  }
+}
+
+function onResizeEnd() {
+  stopResizeTracking()
+}
+
+function onResizeKeydown(event: KeyboardEvent) {
+  if (!textareaEl.value) return
+  if (event.key !== 'ArrowUp' && event.key !== 'ArrowDown' && event.key !== 'Home') return
+  event.preventDefault()
+  const minHeight = defaultTextareaHeight.value || textareaEl.value.offsetHeight
+  const currentHeight = textareaHeight.value || minHeight
+  const step = Number.parseFloat(getComputedStyle(textareaEl.value).lineHeight) || 20
+  textareaHeight.value =
+    event.key === 'Home'
+      ? minHeight
+      : Math.max(minHeight, currentHeight + (event.key === 'ArrowDown' ? step : -step))
+}
+
+/* ---------- 生命周期 ---------- */
+onMounted(() => {
+  nextTick(measureDefaultTextareaHeight)
+})
+
+watch(
+  () => [props.rows, isTextarea.value],
+  () => {
+    if (!isTextarea.value) {
+      stopResizeTracking()
+      defaultTextareaHeight.value = 0
+      textareaHeight.value = null
+      return
+    }
+    textareaHeight.value = null
+    nextTick(() => {
+      defaultTextareaHeight.value = textareaEl.value?.offsetHeight || 0
+    })
+  },
+)
+
+onBeforeUnmount(() => {
+  stopResizeTracking()
+})
+
+/** 程序化聚焦 / 全选（内联重命名、表格单元格编辑等场景） */
+defineExpose({
+  focus: (options?: InputFocusOptions) => {
+    const nativeOptions =
+      options?.preventScroll !== undefined ? { preventScroll: options.preventScroll } : undefined
+    const target = inputEl.value ?? textareaEl.value
+    target?.focus(nativeOptions)
+    if (options?.cursor === 'all') target?.select()
+  },
+  select: () => (inputEl.value ?? textareaEl.value)?.select(),
+  blur: () => (inputEl.value ?? textareaEl.value)?.blur(),
+})
+</script>
+
+<template>
+  <div :class="classes" @mouseenter="hovered = true" @mouseleave="hovered = false">
+    <span v-if="!isTextarea && $slots.prefix" :class="e('prefix')">
+      <slot name="prefix" />
+    </span>
+
+    <input
+      v-if="!isTextarea"
+      ref="inputEl"
+      :class="e('control')"
+      data-slot="input"
+      :type="inputType"
+      :value="inputValue"
+      :inputmode="isNumber ? 'decimal' : undefined"
+      :pattern="isNumber ? '[0-9]*[.]?[0-9]*' : undefined"
+      :disabled="disabled"
+      :readonly="readonly"
+      :maxlength="maxlength"
+      :placeholder="placeholder"
+      :autocomplete="autocomplete"
+      :aria-invalid="status === 'error' || undefined"
+      @input="onInput"
+      @change="onChange"
+      @focus="onFocus"
+      @blur="onBlur"
+    />
+
+    <textarea
+      v-else
+      ref="textareaEl"
+      :class="e('textarea')"
+      data-slot="textarea"
+      :value="modelValue"
+      :disabled="disabled"
+      :readonly="readonly"
+      :rows="rows"
+      :maxlength="maxlength"
+      :placeholder="placeholder"
+      :autocomplete="autocomplete"
+      :style="textareaStyle"
+      :aria-invalid="status === 'error' || undefined"
+      @input="onInput"
+      @change="onChange"
+      @focus="onFocus"
+      @blur="onBlur"
+    ></textarea>
+
+    <span v-if="!isTextarea && $slots.suffix" :class="e('suffix')">
+      <slot name="suffix" />
+    </span>
+
+    <button
+      v-if="!isTextarea && isPassword"
+      :class="e('password-toggle')"
+      type="button"
+      :aria-label="revealed ? '隐藏密码' : '显示密码'"
+      :aria-pressed="revealed"
+      :disabled="disabled || readonly"
+      @click="revealed = !revealed"
+    >
+      <component :is="revealed ? EyeOff : Eye" />
+    </button>
+
+    <button
+      v-if="showClear"
+      :class="e('clear')"
+      type="button"
+      :aria-label="locale.common.clear"
+      @click="clear"
+    >
+      <X />
+    </button>
+
+    <span v-if="!isTextarea && showCount" :class="e('count')">{{ countText }}</span>
+
+    <div v-if="hasTextareaFooter" :class="e('footer')">
+      <span v-if="showCount" :class="e('count')">{{ countText }}</span>
+
+      <span
+        v-if="showResize"
+        :class="e('resize-handle')"
+        role="slider"
+        tabindex="0"
+        aria-label="拖拽调整高度"
+        aria-orientation="vertical"
+        :aria-valuemin="defaultTextareaHeight || undefined"
+        :aria-valuenow="textareaHeight || defaultTextareaHeight || undefined"
+        @pointerdown="onResizeStart"
+        @keydown="onResizeKeydown"
+      >
+        <MoveDiagonal2 aria-hidden="true" />
+      </span>
+    </div>
+  </div>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+.#{b('input')} {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  gap: v('space-1', 4px);
+  box-sizing: border-box;
+  width: 100%;
+  min-height: v('control-height', 32px);
+  padding: 0 v('space-2', 8px);
+  border: 1px solid v('border-color', #d9d9d9);
+  border-radius: v('radius', 6px);
+  background: v('bg-container', #fff);
+  color: v('text-1', rgba(0, 0, 0, 0.88));
+  font-size: v('font-size', 14px);
+  line-height: v('line-height', 1.5);
+  transition:
+    border-color v('duration', 0.2s) v('ease', ease),
+    box-shadow v('duration', 0.2s) v('ease', ease);
+}
+
+.#{b('input')}:hover:not(.#{m('input', 'disabled')}) {
+  border-color: v('color-primary', #18181b);
+}
+
+.#{b('input')}.#{m('input', 'focused')} {
+  border-color: v('color-primary', #18181b);
+  box-shadow: 0 0 0 2px v('color-primary-ring', rgba(24, 24, 27, 0.2));
+}
+
+.#{b('input')}.#{m('input', 'disabled')} {
+  background: v('bg-disabled', rgba(0, 0, 0, 0.04));
+  color: v('text-disabled', rgba(0, 0, 0, 0.25));
+  cursor: not-allowed;
+}
+
+.#{b('input')}.#{m('input', 'error')} {
+  border-color: v('color-danger', #ec4246);
+}
+
+.#{b('input')}.#{m('input', 'warning')} {
+  border-color: v('color-warning', #e79a0d);
+}
+
+.#{e('input', 'control')} {
+  flex: 1;
+  min-width: 0;
+  padding: 0;
+  border: 0;
+  outline: none;
+  background: transparent;
+  color: inherit;
+  font: inherit;
+
+  &::placeholder {
+    color: v('text-3', rgba(0, 0, 0, 0.45));
+  }
+
+  &:disabled {
+    cursor: not-allowed;
+  }
+
+  /* 数字模式的浏览器步进箭头收窄，避免挤压文字 */
+  &[inputmode='decimal']::-webkit-outer-spin-button,
+  &[inputmode='decimal']::-webkit-inner-spin-button {
+    margin: 0;
+  }
+}
+
+.#{e('input', 'prefix')},
+.#{e('input', 'suffix')} {
+  display: inline-flex;
+  align-items: center;
+  flex-shrink: 0;
+  color: v('text-3', rgba(0, 0, 0, 0.45));
+
+  svg {
+    width: 1em;
+    height: 1em;
+  }
+}
+
+.#{e('input', 'clear')},
+.#{e('input', 'password-toggle')} {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  width: 16px;
+  height: 16px;
+  padding: 0;
+  border: 0;
+  border-radius: 50%;
+  background: transparent;
+  color: v('text-3', rgba(0, 0, 0, 0.45));
+  font-size: v('font-size-sm', 12px);
+  cursor: pointer;
+
+  svg {
+    width: 1em;
+    height: 1em;
+  }
+
+  &:hover:not(:disabled) {
+    color: v('text-1', rgba(0, 0, 0, 0.88));
+  }
+
+  &:focus-visible {
+    @include focus-ring();
+  }
+}
+
+.#{e('input', 'count')} {
+  flex-shrink: 0;
+  color: v('text-3', rgba(0, 0, 0, 0.45));
+  font-size: v('font-size-sm', 12px);
+}
+
+/* ---------- 多行 ----------
+   边框与圆角留在外层容器上（基础 .g3-input 已有），textarea 自身无边框：
+   footer（计数 / 拖拽手柄）绝对定位于框内右下角，不再占据文档流被挤到框外。 */
+.#{b('input')}.#{m('input', 'textarea')} {
+  display: flex;
+  flex-direction: column;
+  align-items: stretch;
+  padding: v('space-1', 4px) v('space-2', 8px);
+  line-height: v('line-height', 1.5);
+  cursor: text;
+}
+
+.#{e('input', 'textarea')} {
+  display: block;
+  box-sizing: border-box;
+  width: 100%;
+  padding: 0;
+  border: 0;
+  outline: none;
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  line-height: inherit;
+  resize: none;
+
+  &::placeholder {
+    color: v('text-3', rgba(0, 0, 0, 0.45));
+  }
+
+  &:disabled {
+    cursor: not-allowed;
+  }
+}
+
+/* 有 footer 时底部留白，避免最后一行文字被计数 / 手柄压住 */
+.#{b('input')}.#{is('textarea-with-footer')} .#{e('input', 'textarea')} {
+  padding-bottom: v('space-4', 16px);
+}
+
+.#{e('input', 'footer')} {
+  position: absolute;
+  right: v('space-1', 4px);
+  bottom: 2px;
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  gap: v('space-2', 8px);
+  min-height: 16px;
+}
+
+.#{e('input', 'resize-handle')} {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  width: 16px;
+  height: 16px;
+  border-radius: v('radius-sm', 4px);
+  color: v('text-3', rgba(0, 0, 0, 0.45));
+  cursor: ns-resize;
+  touch-action: none;
+  user-select: none;
+
+  svg {
+    width: 12px;
+    height: 12px;
+  }
+
+  &:hover {
+    color: v('text-1', rgba(0, 0, 0, 0.88));
+    background: v('fill', rgba(0, 0, 0, 0.04));
+  }
+
+  &:focus-visible {
+    @include focus-ring();
+  }
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/input/index.ts b/code/g3soft-libs/packages/ui/src/input/index.ts
new file mode 100644
index 00000000..cdd9a186
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/input/index.ts
@@ -0,0 +1,2 @@
+export { default as G3Input } from './Input.vue'
+export type { InputFocusOptions, InputProps, InputStatus, InputType } from './types'
diff --git a/code/g3soft-libs/packages/ui/src/input/types.ts b/code/g3soft-libs/packages/ui/src/input/types.ts
new file mode 100644
index 00000000..30c13c18
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/input/types.ts
@@ -0,0 +1,38 @@
+/** 输入模式 */
+export type InputType = 'default' | 'password' | 'number' | 'textarea'
+
+/** 校验状态 */
+export type InputStatus = '' | 'error' | 'warning'
+
+export interface InputProps {
+  /** 双向绑定的值 */
+  modelValue?: string | number
+  /** 输入模式 */
+  type?: InputType
+  /** 禁用态 */
+  disabled?: boolean
+  /** 只读态 */
+  readonly?: boolean
+  /** 校验状态 */
+  status?: InputStatus
+  /** 有值时展示清除按钮（hover / 聚焦时出现） */
+  allowClear?: boolean
+  /** 展示字数统计（配合 maxlength 显示 当前 / 上限） */
+  showCount?: boolean
+  /** 最大长度 */
+  maxlength?: string | number
+  /** 多行时的初始行数 */
+  rows?: string | number
+  /** 占位文案 */
+  placeholder?: string
+  /** 浏览器自动填充语义：username / current-password / off 等 */
+  autocomplete?: string
+}
+
+/** 程序化聚焦参数 */
+export interface InputFocusOptions {
+  /** 透传给原生 focus */
+  preventScroll?: boolean
+  /** cursor: 'all' 表示聚焦后全选内容 */
+  cursor?: 'all'
+}
diff --git a/code/g3soft-libs/packages/ui/src/locale/index.ts b/code/g3soft-libs/packages/ui/src/locale/index.ts
index d1cd5809..12c87804 100644
--- a/code/g3soft-libs/packages/ui/src/locale/index.ts
+++ b/code/g3soft-libs/packages/ui/src/locale/index.ts
@@ -2,6 +2,7 @@
  * 语言包出口。
  *
  * 组件不得硬编码中文文案，一律从 locale 取，便于整站切换 / 定制。
+ * 新增文案时同步补 enUS，保持两个语言包结构一致。
  */
 export interface Locale {
   name: string
@@ -9,15 +10,170 @@ export interface Locale {
   empty: {
     description: string
   }
-  [key: string]: unknown
+  /** 跨组件通用文案。 */
+  common: {
+    /** 确认（Modal / 日期面板等） */
+    confirm: string
+    cancel: string
+    clear: string
+    close: string
+    loading: string
+    /** 选择类组件的占位文案 */
+    selectPlaceholder: string
+    /** 输入类组件的占位文案 */
+    inputPlaceholder: string
+    /** 搜索框占位文案 */
+    searchPlaceholder: string
+    /** 无匹配结果 */
+    noMatch: string
+  }
+  /** 分页文案，`{total}` / `{page}` 为占位符。 */
+  pagination: {
+    total: string
+    prev: string
+    next: string
+    page: string
+    pageSize: string
+    goto: string
+  }
+  /** 日期类组件文案，`{year}` / `{month}` 为占位符。 */
+  date: {
+    placeholder: string
+    startPlaceholder: string
+    endPlaceholder: string
+    today: string
+    now: string
+    year: string
+    month: string
+    weekdays: string[]
+    months: string[]
+  }
+  /**
+   * 表单校验文案，`{label}` / `{len}` / `{min}` / `{max}` 为占位符；
+   * label 为空时会连同其后空白一起移除。
+   */
+  form: {
+    required: string
+    type: string
+    pattern: string
+    len: string
+    min: string
+    max: string
+    invalid: string
+  }
 }
 
 export const zhCN: Locale = {
   name: 'zh-CN',
   empty: { description: '暂无数据' },
+  common: {
+    confirm: '确定',
+    cancel: '取消',
+    clear: '清空',
+    close: '关闭',
+    loading: '加载中',
+    selectPlaceholder: '请选择',
+    inputPlaceholder: '请输入',
+    searchPlaceholder: '搜索',
+    noMatch: '无匹配数据',
+  },
+  pagination: {
+    total: '共 {total} 条',
+    prev: '上一页',
+    next: '下一页',
+    page: '页',
+    pageSize: '条/页',
+    goto: '前往',
+  },
+  date: {
+    placeholder: '请选择日期',
+    startPlaceholder: '开始日期',
+    endPlaceholder: '结束日期',
+    today: '今天',
+    now: '此刻',
+    year: '{year} 年',
+    month: '{month} 月',
+    // 与日历矩阵一致：周日开头
+    weekdays: ['日', '一', '二', '三', '四', '五', '六'],
+    months: [
+      '1 月',
+      '2 月',
+      '3 月',
+      '4 月',
+      '5 月',
+      '6 月',
+      '7 月',
+      '8 月',
+      '9 月',
+      '10 月',
+      '11 月',
+      '12 月',
+    ],
+  },
+  form: {
+    required: '{label}不能为空',
+    type: '{label}格式不正确',
+    pattern: '{label}格式不正确',
+    len: '{label}长度必须为 {len}',
+    min: '{label}长度不能少于 {min}',
+    max: '{label}长度不能超过 {max}',
+    invalid: '{label}校验未通过',
+  },
 }
 
 export const enUS: Locale = {
   name: 'en-US',
   empty: { description: 'No data' },
+  common: {
+    confirm: 'OK',
+    cancel: 'Cancel',
+    clear: 'Clear',
+    close: 'Close',
+    loading: 'Loading',
+    selectPlaceholder: 'Please select',
+    inputPlaceholder: 'Please input',
+    searchPlaceholder: 'Search',
+    noMatch: 'No matching data',
+  },
+  pagination: {
+    total: 'Total {total}',
+    prev: 'Previous',
+    next: 'Next',
+    page: 'Page',
+    pageSize: '/ page',
+    goto: 'Go to',
+  },
+  date: {
+    placeholder: 'Select date',
+    startPlaceholder: 'Start date',
+    endPlaceholder: 'End date',
+    today: 'Today',
+    now: 'Now',
+    year: '{year}',
+    month: '{month}',
+    weekdays: ['Su', 'Mo', 'Tu', 'We', 'Th', 'Fr', 'Sa'],
+    months: [
+      'Jan',
+      'Feb',
+      'Mar',
+      'Apr',
+      'May',
+      'Jun',
+      'Jul',
+      'Aug',
+      'Sep',
+      'Oct',
+      'Nov',
+      'Dec',
+    ],
+  },
+  form: {
+    required: '{label} is required',
+    type: '{label} format is invalid',
+    pattern: '{label} format is invalid',
+    len: '{label} length must be {len}',
+    min: '{label} length must be at least {min}',
+    max: '{label} length must be at most {max}',
+    invalid: '{label} failed validation',
+  },
 }
diff --git a/code/g3soft-libs/packages/ui/src/message/Message.vue b/code/g3soft-libs/packages/ui/src/message/Message.vue
new file mode 100644
index 00000000..e750cb1b
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/message/Message.vue
@@ -0,0 +1,141 @@
+<script setup lang="ts">
+import { computed, onBeforeUnmount, onMounted } from 'vue'
+import { CircleCheck, CircleX, Info, TriangleAlert, X } from '@lucide/vue'
+import { useLocale } from '../_composables/useLocale'
+import { useNamespace } from '../_composables/useNamespace'
+import type { MessageType } from './types'
+
+/**
+ * 轻提示项 —— 由 G3Message 命令式创建（也可直接放入 MessageContainer 使用）。
+ *
+ * 超过 duration 后自动关闭；duration <= 0 表示不自动关闭。
+ */
+defineOptions({ name: 'G3Message' })
+
+const props = withDefaults(
+  defineProps<{
+    /** 唯一标识，由管理器分配，用于关闭 */
+    id?: string
+    /** 类型 */
+    type?: MessageType
+    /** 文案内容 */
+    content?: string
+    /** 自动关闭时长（ms），<=0 时不自动关闭 */
+    duration?: number
+    /** 是否显示关闭按钮 */
+    closable?: boolean
+  }>(),
+  { id: '', type: 'info', content: '', duration: 3000, closable: false },
+)
+
+const emit = defineEmits<{ close: [] }>()
+
+const { b, e, m } = useNamespace('message')
+const locale = useLocale()
+
+const ICONS = {
+  info: Info,
+  success: CircleCheck,
+  warning: TriangleAlert,
+  error: CircleX,
+}
+
+const iconComp = computed(() => ICONS[props.type] ?? Info)
+
+let timer: ReturnType<typeof setTimeout> | null = null
+
+function clearTimer() {
+  if (timer) {
+    clearTimeout(timer)
+    timer = null
+  }
+}
+
+function startTimer() {
+  if (props.duration > 0) timer = setTimeout(() => emit('close'), props.duration)
+}
+
+onMounted(startTimer)
+onBeforeUnmount(clearTimer)
+</script>
+
+<template>
+  <div :class="[b(), m(props.type)]" role="alert">
+    <component :is="iconComp" :class="e('icon')" aria-hidden="true" />
+    <span :class="e('content')">{{ content }}</span>
+    <button
+      v-if="closable"
+      type="button"
+      :class="e('close')"
+      :aria-label="locale.common.close"
+      @click="emit('close')"
+    >
+      <X :size="14" />
+    </button>
+  </div>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+.#{b('message')} {
+  display: inline-flex;
+  align-items: center;
+  gap: v('space-2', 8px);
+  box-sizing: border-box;
+  max-width: 480px;
+  padding: v('space-2', 8px) v('space-3', 12px);
+  border: 1px solid v('border-color', #d9d9d9);
+  border-radius: v('radius', 6px);
+  background: v('bg-container', #fff);
+  box-shadow: v('shadow-popup', 0 6px 16px rgba(0, 0, 0, 0.12));
+  color: v('text-1', rgba(0, 0, 0, 0.88));
+  font-size: v('font-size', 14px);
+  line-height: v('line-height', 1.5);
+  pointer-events: auto;
+}
+
+.#{e('message', 'icon')} {
+  flex-shrink: 0;
+  width: v('feedback-icon-size', 18px);
+  height: v('feedback-icon-size', 18px);
+}
+
+.#{b('message')}.#{m('message', 'info')} .#{e('message', 'icon')} {
+  color: v('color-primary', #18181b);
+}
+
+.#{b('message')}.#{m('message', 'success')} .#{e('message', 'icon')} {
+  color: v('color-success', #45b114);
+}
+
+.#{b('message')}.#{m('message', 'warning')} .#{e('message', 'icon')} {
+  color: v('color-warning', #e79a0d);
+}
+
+.#{b('message')}.#{m('message', 'error')} .#{e('message', 'icon')} {
+  color: v('color-danger', #ec4246);
+}
+
+.#{e('message', 'content')} {
+  flex: 1;
+  min-width: 0;
+  overflow-wrap: anywhere;
+}
+
+.#{e('message', 'close')} {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  padding: 0;
+  border: 0;
+  background: transparent;
+  color: v('text-3', rgba(0, 0, 0, 0.45));
+  cursor: pointer;
+
+  &:hover {
+    color: v('text-1', rgba(0, 0, 0, 0.88));
+  }
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/message/MessageContainer.test.ts b/code/g3soft-libs/packages/ui/src/message/MessageContainer.test.ts
new file mode 100644
index 00000000..106694aa
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/message/MessageContainer.test.ts
@@ -0,0 +1,81 @@
+import { mount } from '@vue/test-utils'
+import { afterEach, describe, expect, it } from 'vitest'
+import { nextTick } from 'vue'
+import G3MessageContainer from './MessageContainer.vue'
+import { messageState } from './store'
+
+/**
+ * 回归重点：方位对齐类曾经手写成 `g3-message-list--xxx`，而样式表里是
+ * `g3-message__list--xxx`（BEM 双下划线），导致 9 个方位的样式全部失效，
+ * 消息一律堆在左上角。这里同时锁住「类名形状」与「默认方位」。
+ */
+afterEach(() => {
+  messageState.items.splice(0, messageState.items.length)
+})
+
+function pushMessage(placement?: string) {
+  messageState.items.push({
+    id: `m-${messageState.items.length + 1}`,
+    type: 'info',
+    content: '提示内容',
+    duration: 3000,
+    closable: false,
+    placement: (placement ?? 'top-center') as never,
+  })
+}
+
+describe('MessageContainer 方位', () => {
+  it('方位类名使用 BEM 双下划线，且能对上 top / center-h', async () => {
+    pushMessage('top-center')
+    const wrapper = mount(G3MessageContainer, { props: { zIndex: 5001 } })
+    await nextTick()
+
+    // 九个方位容器常驻，要取「装着这条消息」的那个
+    const list = wrapper.findAll('.g3-message__list').find((item) => item.text().includes('提示内容'))
+    expect(list).toBeDefined()
+    expect(list!.classes()).toContain('g3-message__list--top')
+    expect(list!.classes()).toContain('g3-message__list--center-h')
+    // 反向锁：不允许再出现 'g3-message-list--*' 这种手写拼法
+    expect(list!.classes().some((name) => name.startsWith('g3-message-list--'))).toBe(false)
+  })
+
+  it('其他方位映射到对应的垂直 / 水平类', async () => {
+    pushMessage('bottom-right')
+    pushMessage('center-left')
+    const wrapper = mount(G3MessageContainer)
+    await nextTick()
+
+    const classNames = wrapper.findAll('.g3-message__list').flatMap((list) => list.classes())
+    expect(classNames).toContain('g3-message__list--bottom')
+    expect(classNames).toContain('g3-message__list--right')
+    expect(classNames).toContain('g3-message__list--center-v')
+    expect(classNames).toContain('g3-message__list--left')
+  })
+
+  it('九个方位容器常驻，保证进出场动画稳定触发', () => {
+    const wrapper = mount(G3MessageContainer)
+    expect(wrapper.findAll('.g3-message__list')).toHaveLength(9)
+  })
+
+  it('容器层级由管理器下发，消息项渲染在对应方位容器内', async () => {
+    pushMessage('top-center')
+    const wrapper = mount(G3MessageContainer, { props: { zIndex: 5001 } })
+    await nextTick()
+
+    expect(wrapper.find('.g3-message__container').attributes('style')).toContain('z-index: 5001')
+    const list = wrapper.findAll('.g3-message__list').find((item) => item.text().includes('提示内容'))
+    expect(list?.classes()).toContain('g3-message__list--top')
+  })
+
+  it('不同方位的消息互不串位', async () => {
+    pushMessage('top-left')
+    pushMessage('bottom-right')
+    const wrapper = mount(G3MessageContainer)
+    await nextTick()
+
+    const lists = wrapper.findAll('.g3-message__list').filter((list) => list.text().includes('提示内容'))
+    expect(lists).toHaveLength(2)
+    expect(lists[0].classes()).toContain('g3-message__list--top')
+    expect(lists[1].classes()).toContain('g3-message__list--bottom')
+  })
+})
diff --git a/code/g3soft-libs/packages/ui/src/message/MessageContainer.vue b/code/g3soft-libs/packages/ui/src/message/MessageContainer.vue
new file mode 100644
index 00000000..f196a21f
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/message/MessageContainer.vue
@@ -0,0 +1,155 @@
+<script setup lang="ts">
+import { useNamespace } from '../_composables/useNamespace'
+import G3Message from './Message.vue'
+import { messageState } from './store'
+import type { MessagePlacement } from './types'
+
+/**
+ * 轻提示容器 —— 由 G3Message 管理器创建的单例挂载点，业务不直接使用。
+ *
+ * 9 个方位的分组容器始终存在，只有消息项进出，保证进出场动画稳定触发。
+ */
+defineOptions({ name: 'G3MessageContainer' })
+
+const props = withDefaults(
+  defineProps<{
+    /** 容器层级（由管理器分配，避免与弹窗 / 浮层打架） */
+    zIndex?: number
+  }>(),
+  { zIndex: 0 },
+)
+
+// em(el, mod) 才能产出与样式表一致的 g3-message__list--xxx；
+// 早期手写 `${b()}-list--xxx` 生成的是 g3-message-list--xxx，与样式对不上，
+// 结果是所有方位样式全部失效，消息一律堆在左上角。
+const { b, e, em } = useNamespace('message')
+
+const PLACEMENTS: MessagePlacement[] = [
+  'top-left',
+  'top-center',
+  'top-right',
+  'center-left',
+  'center',
+  'center-right',
+  'bottom-left',
+  'bottom-center',
+  'bottom-right',
+]
+
+function close(id: string) {
+  const index = messageState.items.findIndex((item) => item.id === id)
+  if (index !== -1) messageState.items.splice(index, 1)
+}
+
+/** 方位 → 对齐类：垂直方向 + 水平方向 */
+function placementClasses(placement: MessagePlacement): string[] {
+  const [vertical, horizontal = 'center'] = placement.split('-')
+  return [
+    em('list', vertical === 'center' ? 'center-v' : vertical),
+    em('list', horizontal === 'center' ? 'center-h' : horizontal),
+  ]
+}
+
+/** 某个方位下当前存活的消息 */
+function itemsOf(placement: MessagePlacement) {
+  return messageState.items.filter(
+    (item) => (item.placement || messageState.placement || 'top-center') === placement,
+  )
+}
+</script>
+
+<template>
+  <div
+    :class="e('container')"
+    :style="{ zIndex: props.zIndex || undefined }"
+    aria-live="polite"
+  >
+    <!-- 列表容器常驻、只有消息项进出 —— 这是 enter/leave 能稳定触发的前提 -->
+    <TransitionGroup
+      v-for="placement in PLACEMENTS"
+      :key="placement"
+      :name="b()"
+      tag="div"
+      :class="[e('list'), ...placementClasses(placement)]"
+    >
+      <G3Message
+        v-for="item in itemsOf(placement)"
+        :key="item.id"
+        :id="item.id"
+        :type="item.type"
+        :content="item.content"
+        :duration="item.duration"
+        :closable="item.closable"
+        @close="close(item.id)"
+      />
+    </TransitionGroup>
+  </div>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+.#{e('message', 'container')} {
+  position: fixed;
+  inset: 0;
+  /* 容器本身不拦截页面交互，仅消息项可交互 */
+  pointer-events: none;
+}
+
+.#{e('message', 'list')} {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  flex-direction: column;
+  gap: v('space-3', 12px);
+  box-sizing: border-box;
+  padding: v('feedback-offset', 24px);
+}
+
+/* 垂直方位（主轴）：上 / 中 / 下 */
+.#{e('message', 'list')}--top {
+  justify-content: flex-start;
+}
+
+.#{e('message', 'list')}--center-v {
+  justify-content: center;
+}
+
+.#{e('message', 'list')}--bottom {
+  justify-content: flex-end;
+}
+
+/* 水平方位（交叉轴）：左 / 中 / 右 */
+.#{e('message', 'list')}--left {
+  align-items: flex-start;
+}
+
+.#{e('message', 'list')}--center-h {
+  align-items: center;
+}
+
+.#{e('message', 'list')}--right {
+  align-items: flex-end;
+}
+
+/* ---------- 进出场 ---------- */
+.#{b('message')}-enter-active,
+.#{b('message')}-leave-active {
+  transition:
+    opacity v('duration', 0.2s) v('ease', ease),
+    transform v('duration', 0.2s) v('ease', ease);
+}
+
+.#{b('message')}-enter-from,
+.#{b('message')}-leave-to {
+  opacity: 0;
+  transform: translateY(-8px);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .#{b('message')}-enter-active,
+  .#{b('message')}-leave-active {
+    transition-duration: 0ms;
+  }
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/message/index.ts b/code/g3soft-libs/packages/ui/src/message/index.ts
new file mode 100644
index 00000000..6c4e8084
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/message/index.ts
@@ -0,0 +1,12 @@
+export { default as G3MessageItem } from './Message.vue'
+export { default as G3MessageContainer } from './MessageContainer.vue'
+export { default as G3Message } from './manager'
+export { messageState } from './store'
+export type {
+  MessageConfig,
+  MessageHandle,
+  MessageItemState,
+  MessageOptions,
+  MessagePlacement,
+  MessageType,
+} from './types'
diff --git a/code/g3soft-libs/packages/ui/src/message/manager.ts b/code/g3soft-libs/packages/ui/src/message/manager.ts
new file mode 100644
index 00000000..0424eef1
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/message/manager.ts
@@ -0,0 +1,85 @@
+import { createVNode, render } from 'vue'
+import { nextZIndex, releaseZIndex } from '../_utils/z-index'
+import G3MessageContainer from './MessageContainer.vue'
+import { messageState } from './store'
+import type { MessageConfig, MessageHandle, MessageOptions } from './types'
+
+/* ---------- 单例容器 ---------- */
+let containerEl: HTMLElement | null = null
+let containerZIndex = 0
+let seed = 0
+
+function ensureContainer() {
+  if (containerEl || typeof document === 'undefined') return
+  containerEl = document.createElement('div')
+  document.body.appendChild(containerEl)
+  // 反馈类提示层级最高：必须浮于弹窗之上，弹窗内操作的成功 / 失败提示才可见
+  containerZIndex = nextZIndex('feedback')
+  render(createVNode(G3MessageContainer, { zIndex: containerZIndex }), containerEl)
+}
+
+/* ---------- 增删 ---------- */
+function remove(id: string) {
+  const index = messageState.items.findIndex((item) => item.id === id)
+  if (index !== -1) messageState.items.splice(index, 1)
+}
+
+function open(options: MessageOptions): MessageHandle {
+  ensureContainer()
+  const id = `g3-message-${++seed}`
+  // 逐项归一，避免 options 里显式的 undefined 覆盖掉全局默认值
+  messageState.items.push({
+    id,
+    type: options.type ?? 'info',
+    content: options.content ?? '',
+    duration: options.duration ?? messageState.duration,
+    closable: options.closable ?? false,
+    placement: options.placement ?? messageState.placement,
+  })
+  return { close: () => remove(id) }
+}
+
+type ShortcutOptions = Omit<MessageOptions, 'content' | 'type'>
+
+/**
+ * 轻提示 —— 命令式调用，组件树外挂载（自动读取全局配置的命名空间 / 语言包 / 容器）。
+ *
+ * ```ts
+ * G3Message.success('保存成功')
+ * G3Message.error('保存失败', { duration: 0 }) // duration <= 0 不自动关闭
+ * ```
+ */
+export const G3Message = {
+  /** 通用入口 */
+  open,
+  info: (content: string, options?: ShortcutOptions) => open({ ...options, content, type: 'info' }),
+  success: (content: string, options?: ShortcutOptions) =>
+    open({ ...options, content, type: 'success' }),
+  warning: (content: string, options?: ShortcutOptions) =>
+    open({ ...options, content, type: 'warning' }),
+  error: (content: string, options?: ShortcutOptions) =>
+    open({ ...options, content, type: 'error' }),
+  /** 关闭指定消息 */
+  close: (id: string) => remove(id),
+  /** 全局配置：默认方位与默认时长 */
+  config: (config: MessageConfig) => {
+    if (config.placement) messageState.placement = config.placement
+    if (config.duration != null) messageState.duration = config.duration
+  },
+  /** 清空全部消息并卸载容器（切换租户 / 登出时用） */
+  destroy: () => {
+    messageState.items.splice(0, messageState.items.length)
+    if (!containerEl) return
+    render(null, containerEl)
+    containerEl.remove()
+    containerEl = null
+    if (containerZIndex) {
+      releaseZIndex(containerZIndex)
+      containerZIndex = 0
+    }
+  },
+  /** 当前存活的消息条数（调试用） */
+  count: () => messageState.items.length,
+}
+
+export default G3Message
diff --git a/code/g3soft-libs/packages/ui/src/message/store.ts b/code/g3soft-libs/packages/ui/src/message/store.ts
new file mode 100644
index 00000000..b3b8105f
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/message/store.ts
@@ -0,0 +1,15 @@
+import { reactive } from 'vue'
+import type { MessageItemState, MessagePlacement } from './types'
+
+/** 全局共享的 Message 活跃列表：管理器写入、容器读取，保证响应式联动 */
+export const messageState = reactive<{
+  items: MessageItemState[]
+  /** 默认方位 */
+  placement: MessagePlacement
+  /** 默认自动关闭时长（ms） */
+  duration: number
+}>({
+  items: [],
+  placement: 'top-center',
+  duration: 3000,
+})
diff --git a/code/g3soft-libs/packages/ui/src/message/types.ts b/code/g3soft-libs/packages/ui/src/message/types.ts
new file mode 100644
index 00000000..294dd9af
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/message/types.ts
@@ -0,0 +1,51 @@
+/** 轻提示类型 */
+export type MessageType = 'info' | 'success' | 'warning' | 'error'
+
+/** 轻提示方位 */
+export type MessagePlacement =
+  | 'top-left'
+  | 'top-center'
+  | 'top-right'
+  | 'center-left'
+  | 'center'
+  | 'center-right'
+  | 'bottom-left'
+  | 'bottom-center'
+  | 'bottom-right'
+
+export interface MessageOptions {
+  /** 文案内容 */
+  content: string
+  /** 类型 */
+  type?: MessageType
+  /** 自动关闭时长（ms），<=0 时不自动关闭 */
+  duration?: number
+  /** 是否显示关闭按钮 */
+  closable?: boolean
+  /** 显示方位，默认取全局配置 */
+  placement?: MessagePlacement
+}
+
+/** 容器内单条消息的完整状态 */
+export interface MessageItemState {
+  id: string
+  content: string
+  type: MessageType
+  duration: number
+  closable: boolean
+  placement: MessagePlacement
+}
+
+/** 命令式调用的返回句柄 */
+export interface MessageHandle {
+  /** 关闭这一条 */
+  close: () => void
+}
+
+/** 全局配置项 */
+export interface MessageConfig {
+  /** 默认方位 */
+  placement?: MessagePlacement
+  /** 默认自动关闭时长 */
+  duration?: number
+}
diff --git a/code/g3soft-libs/packages/ui/src/modal/Modal.vue b/code/g3soft-libs/packages/ui/src/modal/Modal.vue
new file mode 100644
index 00000000..809e4047
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/modal/Modal.vue
@@ -0,0 +1,539 @@
+<script setup lang="ts">
+import { computed, nextTick, onBeforeUnmount, ref, useId, watch } from 'vue'
+import { Maximize, Minimize, X } from '@lucide/vue'
+import { useLocale } from '../_composables/useLocale'
+import { useNamespace } from '../_composables/useNamespace'
+import { usePopupContainer } from '../_composables/usePopupContainer'
+import { bindDrag, bindResize, type DragHandle, type ResizeHandle } from '../_utils/drag'
+import { focusFirst, trapFocus } from '../_utils/focus'
+import { lockScroll, unlockScroll } from '../_utils/scroll'
+import { nextZIndex, releaseZIndex } from '../_utils/z-index'
+import G3Button from '../button/Button.vue'
+import type { ModalProps } from './types'
+
+/**
+ * 对话框 —— 模态窗口，支持拖动、四边缩放、全屏与异步确认。
+ *
+ * 关闭语义：底部「取消」按钮触发 `cancel` 事件；遮罩 / Esc / 右上角关闭同样走 cancel 事件，
+ * 但 `confirmLoading` 期间一律不响应，避免异步提交流程被打断。
+ */
+defineOptions({ name: 'G3Modal' })
+
+const props = withDefaults(defineProps<ModalProps>(), {
+  open: undefined,
+  defaultOpen: false,
+  title: '',
+  width: 520,
+  centered: false,
+  mask: true,
+  maskClosable: true,
+  keyboard: true,
+  closable: true,
+  fullscreen: true,
+  resizable: true,
+  footer: true,
+  confirmText: undefined,
+  cancelText: undefined,
+  confirmLoading: false,
+  popupContainer: undefined,
+})
+
+const emit = defineEmits<{
+  'update:open': [value: boolean]
+  confirm: []
+  cancel: []
+  closed: []
+}>()
+
+const { b, e, m, is } = useNamespace('modal')
+const locale = useLocale()
+const teleportTo = usePopupContainer(() => props.popupContainer)
+
+const innerOpen = ref(props.defaultOpen)
+const panelRef = ref<HTMLElement | null>(null)
+const headerRef = ref<HTMLElement | null>(null)
+const resizeERef = ref<HTMLElement | null>(null)
+const resizeWRef = ref<HTMLElement | null>(null)
+const resizeSRef = ref<HTMLElement | null>(null)
+const resizeNRef = ref<HTMLElement | null>(null)
+
+// 标题 / 描述与面板的关联 id，useId 保证多实例并存时不冲突
+const titleId = useId()
+// 打开前的活动元素，关闭后还原焦点
+let triggerEl: HTMLElement | null = null
+// 拖拽 / 缩放句柄，面板打开期间存在
+let dragHandle: DragHandle | null = null
+let resizeHandles: ResizeHandle[] = []
+// 本实例是否持有 body 滚动锁；解锁动作挪到退场动画之后，标志位保证只解锁一次
+let scrollLocked = false
+// 层级：打开时分配，退场结束后回收
+const zIndex = ref(0)
+// 全屏状态与缩放尺寸；关闭后重置，下次打开不继承
+const isFullscreen = ref(false)
+const resizeSize = ref<{ width: number; height: number } | null>(null)
+
+const isOpen = computed({
+  get: () => (props.open !== undefined ? props.open : innerOpen.value),
+  set: (value: boolean) => {
+    if (props.open === undefined) innerOpen.value = value
+    emit('update:open', value)
+  },
+})
+
+// number 按 px，纯数字字符串补 px，其余（如 480px / 60%）按 CSS 原样
+const panelWidth = computed(() => {
+  if (typeof props.width === 'number') return `${props.width}px`
+  const text = String(props.width).trim()
+  return /^\d+(\.\d+)?$/.test(text) ? `${text}px` : text
+})
+
+const panelStyle = computed(() => {
+  if (resizeSize.value) {
+    return { width: `${resizeSize.value.width}px`, height: `${resizeSize.value.height}px` }
+  }
+  return { width: panelWidth.value }
+})
+
+/** 遮罩与内容层共用本实例分配到的层级（body 下的兄弟节点，必须各自写 z-index） */
+const layerStyle = computed(() => ({ zIndex: zIndex.value ? String(zIndex.value) : undefined }))
+
+const resolvedConfirmText = computed(() => props.confirmText ?? locale.value.common.confirm)
+const resolvedCancelText = computed(() => props.cancelText ?? locale.value.common.cancel)
+
+/* ---------- 公共方法 ---------- */
+/**
+ * 所有关闭入口（遮罩 / Esc / 关闭按钮 / 取消按钮）统一走这里；
+ * confirmLoading 期间不响应，避免异步提交流程被打断。
+ */
+function requestClose() {
+  if (props.confirmLoading) return
+  emit('cancel')
+  isOpen.value = false
+}
+
+function onConfirmClick() {
+  emit('confirm')
+}
+
+/* ---------- 遮罩点击 ---------- */
+// 遮罩点击关闭：wrap 铺满视口且层级高于 mask，事件实际落在 wrap 上；
+// 只响应点击 wrap 自身（面板外空白区域），点击面板内部不关闭。
+// 记录 mousedown 是否发生在面板内：若在面板内按下（如拖选输入框文本）后拖出到遮罩再松开，
+// click.target 会回溯为共同祖先 wrap，此时不应误判为点击遮罩。
+let maskDownInPanel = false
+function onWrapMouseDown(event: MouseEvent) {
+  maskDownInPanel = panelRef.value?.contains(event.target as Node) === true
+}
+function onWrapClick(event: MouseEvent) {
+  if (event.target === event.currentTarget && props.maskClosable && !maskDownInPanel) requestClose()
+}
+
+function onMaskClick() {
+  if (props.maskClosable) requestClose()
+}
+
+/* ---------- 键盘与焦点 ---------- */
+function onPanelKeydown(event: KeyboardEvent) {
+  if (props.keyboard && event.key === 'Escape') {
+    requestClose()
+    return
+  }
+  // Tab 在面板内循环；焦点被陷阱约束在面板中，Esc 与 Tab 必然到达此监听
+  if (panelRef.value) trapFocus(event, panelRef.value)
+}
+
+/* ---------- 拖拽 / 缩放 ---------- */
+function enableDragAndResize() {
+  if (!panelRef.value || !headerRef.value) return
+  dragHandle = bindDrag(panelRef.value, headerRef.value)
+  if (!props.resizable) return
+  resizeHandles = [
+    { el: resizeERef.value, direction: 'e' },
+    { el: resizeWRef.value, direction: 'w' },
+    { el: resizeSRef.value, direction: 's' },
+    { el: resizeNRef.value, direction: 'n' },
+  ]
+    .filter((item) => item.el)
+    .map(({ el, direction }) =>
+      bindResize(panelRef.value, el, {
+        direction,
+        maxWidth: window.innerWidth - 32,
+        maxHeight: window.innerHeight - 124,
+        onResize: (size) => {
+          resizeSize.value = size
+        },
+      }),
+    )
+}
+
+function disableDragAndResize() {
+  // 不清除 transform：面板保持拖拽位置播放消失动画（v-if 随后销毁 DOM，无残留）
+  if (dragHandle) {
+    dragHandle.destroy()
+    dragHandle = null
+  }
+  resizeHandles.forEach((handle) => handle.destroy())
+  resizeHandles = []
+}
+
+/* ---------- 生命周期：打开 / 关闭时接管焦点与滚动 ----------
+   immediate：命令式挂载（G3Modal.confirm）时 open 初始即为 true，watch 不会因「变化」触发；
+   加 immediate 让打开态初始化（滚动锁 / 焦点陷阱 / Esc / 拖拽）在挂载时执行一次。 */
+watch(
+  isOpen,
+  (value) => {
+    if (value) {
+      // 记录触发元素，关闭后还原焦点
+      triggerEl = document.activeElement as HTMLElement | null
+      if (!zIndex.value) zIndex.value = nextZIndex('modal')
+      lockScroll()
+      scrollLocked = true
+      nextTick(() => {
+        if (!isOpen.value || !panelRef.value) return
+        focusFirst(panelRef.value)
+        panelRef.value.addEventListener('keydown', onPanelKeydown)
+        enableDragAndResize()
+      })
+    } else {
+      // 这里只做与动画无关的拆卸（键盘监听、拖拽 / 缩放手柄）。
+      // 解锁滚动、复位尺寸、还原焦点一律等退场动画结束再做（见 onAfterLeave）
+      panelRef.value?.removeEventListener('keydown', onPanelKeydown)
+      disableDragAndResize()
+    }
+  },
+  { immediate: true },
+)
+
+/** 退场动画结束后收尾：解锁滚动、复位状态、把焦点还给触发元素 */
+function onAfterLeave() {
+  // 退场途中又被打开：本次退场已作废，不能在这里复位
+  if (isOpen.value) return
+  if (scrollLocked) {
+    unlockScroll()
+    scrollLocked = false
+  }
+  if (zIndex.value) {
+    releaseZIndex(zIndex.value)
+    zIndex.value = 0
+  }
+  // 重置全屏与缩放状态，下次打开不继承
+  isFullscreen.value = false
+  resizeSize.value = null
+  if (triggerEl && typeof triggerEl.focus === 'function') triggerEl.focus()
+  triggerEl = null
+  emit('closed')
+}
+
+// 全屏与拖拽互斥：进入全屏时停用拖拽并复位位置，退出后重新启用
+watch(isFullscreen, (value) => {
+  if (!isOpen.value) return
+  if (value) {
+    if (dragHandle) {
+      dragHandle.reset()
+      dragHandle.destroy()
+      dragHandle = null
+    }
+  } else {
+    enableDragAndResize()
+  }
+})
+
+onBeforeUnmount(() => {
+  panelRef.value?.removeEventListener('keydown', onPanelKeydown)
+  disableDragAndResize()
+  // 组件在打开状态下被直接销毁：after-leave 不会触发，这里兜底解锁（标志位防重复）
+  if (scrollLocked) {
+    unlockScroll()
+    scrollLocked = false
+  }
+  if (zIndex.value) {
+    releaseZIndex(zIndex.value)
+    zIndex.value = 0
+  }
+})
+</script>
+
+<template>
+  <Teleport :to="teleportTo">
+    <!-- 遮罩与内容分两个 Transition：遮罩先铺，内容晚一拍落；
+         退场不错峰，两者同时走 —— 错峰退场会闪。
+         appear：命令式挂载时 open 初始即为 true，元素首帧就在，加 appear 才会播入场动画。 -->
+    <Transition name="g3-modal-mask" appear>
+      <div
+        v-if="isOpen && mask"
+        :class="e('mask')"
+        :style="layerStyle"
+        aria-hidden="true"
+        @click="onMaskClick"
+      ></div>
+    </Transition>
+    <Transition name="g3-modal" appear @after-leave="onAfterLeave">
+      <div
+        v-if="isOpen"
+        :class="[e('wrap'), { [m('centered')]: centered }]"
+        :style="layerStyle"
+        @mousedown="onWrapMouseDown"
+        @click="onWrapClick"
+      >
+        <div
+          ref="panelRef"
+          :class="[b(), { [m('fullscreen')]: isFullscreen }]"
+          role="dialog"
+          aria-modal="true"
+          :aria-label="title ? undefined : '对话框'"
+          :aria-labelledby="title ? titleId : undefined"
+          tabindex="-1"
+          :style="panelStyle"
+        >
+          <div ref="headerRef" :class="e('header')">
+            <p v-if="title" :id="titleId" :class="e('title')">{{ title }}</p>
+            <div :class="e('header-actions')">
+              <slot name="header-extra" />
+              <button
+                v-if="fullscreen"
+                type="button"
+                :class="e('header-btn')"
+                :aria-label="isFullscreen ? '退出全屏' : '全屏'"
+                @click="isFullscreen = !isFullscreen"
+              >
+                <Minimize v-if="isFullscreen" :size="14" />
+                <Maximize v-else :size="14" />
+              </button>
+              <button
+                v-if="closable"
+                type="button"
+                :class="e('header-btn')"
+                :aria-label="locale.common.close"
+                @click="requestClose"
+              >
+                <X :size="14" />
+              </button>
+            </div>
+          </div>
+          <div :class="e('body')">
+            <slot />
+          </div>
+          <div v-if="footer" :class="e('footer')">
+            <slot name="footer">
+              <G3Button type="outline" :disabled="confirmLoading" @click="requestClose">
+                {{ resolvedCancelText }}
+              </G3Button>
+              <G3Button :loading="confirmLoading" @click="onConfirmClick">
+                {{ resolvedConfirmText }}
+              </G3Button>
+            </slot>
+          </div>
+          <!-- 四边缩放手柄：拖动调整面板宽高，全屏时不可用 -->
+          <template v-if="resizable && !isFullscreen">
+            <div ref="resizeERef" :class="[e('resizer'), e('resizer-e')]" aria-hidden="true"></div>
+            <div ref="resizeWRef" :class="[e('resizer'), e('resizer-w')]" aria-hidden="true"></div>
+            <div ref="resizeSRef" :class="[e('resizer'), e('resizer-s')]" aria-hidden="true"></div>
+            <div ref="resizeNRef" :class="[e('resizer'), e('resizer-n')]" aria-hidden="true"></div>
+          </template>
+        </div>
+      </div>
+    </Transition>
+  </Teleport>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+.#{e('modal', 'mask')} {
+  position: fixed;
+  inset: 0;
+  background: v('mask-bg', rgba(0, 0, 0, 0.45));
+}
+
+.#{e('modal', 'wrap')} {
+  position: fixed;
+  inset: 0;
+  display: flex;
+  justify-content: center;
+  align-items: flex-start;
+  padding: v('space-6', 32px) v('space-4', 16px);
+  overflow: auto;
+}
+
+.#{e('modal', 'wrap')}.#{m('modal', 'centered')} {
+  align-items: center;
+}
+
+.#{b('modal')} {
+  position: relative;
+  /* 纵向弹性：面板写死高度（缩放 / 全屏）时，body 自己吃掉剩余高度并内部滚动 */
+  display: flex;
+  flex-direction: column;
+  box-sizing: border-box;
+  max-width: 100%;
+  /* 与 .wrap 的上下 32px 内边距对应：内容过高时面板不越过视口，改为 body 内滚动 */
+  max-height: calc(100vh - 64px);
+  border-radius: v('radius-lg', 8px);
+  background: v('bg-container', #fff);
+  box-shadow: v('shadow-popup', 0 6px 16px rgba(0, 0, 0, 0.12));
+  color: v('text-1', rgba(0, 0, 0, 0.88));
+  outline: none;
+}
+
+.#{b('modal')}.#{m('modal', 'fullscreen')} {
+  position: fixed;
+  inset: v('space-4', 16px);
+  width: auto !important;
+  height: auto !important;
+  max-width: none;
+  transform: none !important;
+}
+
+.#{e('modal', 'header')} {
+  display: flex;
+  flex-shrink: 0;
+  align-items: center;
+  gap: v('space-2', 8px);
+  padding: v('space-3', 12px) v('space-5', 24px);
+  border-bottom: 1px solid v('border-color', #d9d9d9);
+  cursor: move;
+  user-select: none;
+}
+
+.#{e('modal', 'title')} {
+  flex: 1;
+  margin: 0;
+  overflow: hidden;
+  font-size: v('font-size-lg', 16px);
+  font-weight: 600;
+  line-height: v('line-height', 1.5);
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.#{e('modal', 'header-actions')} {
+  display: inline-flex;
+  align-items: center;
+  gap: v('space-1', 4px);
+  cursor: default;
+}
+
+.#{e('modal', 'header-btn')} {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 24px;
+  height: 24px;
+  padding: 0;
+  border: 0;
+  border-radius: v('radius-sm', 4px);
+  background: transparent;
+  color: v('text-2', rgba(0, 0, 0, 0.65));
+  cursor: pointer;
+  transition: background-color v('duration-fast', 0.1s) v('ease', ease);
+
+  &:hover {
+    background: v('fill', rgba(0, 0, 0, 0.04));
+    color: v('text-1', rgba(0, 0, 0, 0.88));
+  }
+
+  &:focus-visible {
+    @include focus-ring();
+  }
+}
+
+.#{e('modal', 'body')} {
+  /* 面板缩放 / 内容过高时由 body 吃掉剩余高度并内部滚动，否则内容会溢出面板 */
+  flex: 1 1 auto;
+  min-height: 0;
+  padding: v('space-5', 24px);
+  overflow: auto;
+}
+
+.#{e('modal', 'footer')} {
+  display: flex;
+  flex-shrink: 0;
+  align-items: center;
+  justify-content: flex-end;
+  gap: v('space-2', 8px);
+  padding: v('space-3', 12px) v('space-5', 24px);
+  border-top: 1px solid v('border-color', #d9d9d9);
+}
+
+/* ---------- 缩放手柄 ---------- */
+.#{e('modal', 'resizer')} {
+  position: absolute;
+  z-index: 1;
+  touch-action: none;
+}
+
+.#{e('modal', 'resizer-e')} {
+  top: 0;
+  right: -3px;
+  width: 6px;
+  height: 100%;
+  cursor: ew-resize;
+}
+
+.#{e('modal', 'resizer-w')} {
+  top: 0;
+  left: -3px;
+  width: 6px;
+  height: 100%;
+  cursor: ew-resize;
+}
+
+.#{e('modal', 'resizer-s')} {
+  bottom: -3px;
+  left: 0;
+  width: 100%;
+  height: 6px;
+  cursor: ns-resize;
+}
+
+.#{e('modal', 'resizer-n')} {
+  top: -3px;
+  left: 0;
+  width: 100%;
+  height: 6px;
+  cursor: ns-resize;
+}
+
+.#{e('modal', 'resizer')}:hover,
+.#{e('modal', 'resizer')}.is-resizing {
+  background: v('color-primary-soft', rgba(24, 24, 27, 0.12));
+}
+
+/* ---------- 进出场 ---------- */
+.g3-modal-mask-enter-active,
+.g3-modal-mask-leave-active {
+  transition: opacity v('duration-slow', 0.3s) v('ease', ease);
+}
+
+.g3-modal-mask-enter-from,
+.g3-modal-mask-leave-to {
+  opacity: 0;
+}
+
+.g3-modal-enter-active {
+  transition:
+    opacity v('duration-slow', 0.3s) v('ease', ease),
+    transform v('duration-slow', 0.3s) v('ease', ease);
+}
+
+.g3-modal-leave-active {
+  transition:
+    opacity v('duration', 0.2s) v('ease', ease),
+    transform v('duration', 0.2s) v('ease', ease);
+}
+
+.g3-modal-enter-from,
+.g3-modal-leave-to {
+  opacity: 0;
+  transform: translateY(-12px);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .g3-modal-mask-enter-active,
+  .g3-modal-mask-leave-active,
+  .g3-modal-enter-active,
+  .g3-modal-leave-active {
+    transition-duration: 0ms;
+  }
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/modal/ModalConfirm.vue b/code/g3soft-libs/packages/ui/src/modal/ModalConfirm.vue
new file mode 100644
index 00000000..90f41bc2
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/modal/ModalConfirm.vue
@@ -0,0 +1,93 @@
+<script setup lang="ts">
+/**
+ * 命令式确认对话框（由 G3Modal.confirm 动态挂载，业务不直接使用）。
+ *
+ * onConfirm 返回 Promise 时确定按钮进入 loading：resolve 后关闭、reject 保持打开，
+ * 错误由调用方负责提示。
+ *
+ * 关闭来源与 onCancel 的关系：只有点「取消」按钮才算显式取消、触发 onCancel；
+ * 点遮罩空白 / Esc / 右上角关闭按钮都是「静默关闭」——只关窗不跑 onCancel，
+ * 避免用户随手点空白就误触发取消逻辑。
+ */
+import { computed, ref } from 'vue'
+import G3Button from '../button/Button.vue'
+import { useLocale } from '../_composables/useLocale'
+import G3Modal from './Modal.vue'
+import type { ModalConfirmOptions } from './types'
+
+defineOptions({ name: 'G3ModalConfirm' })
+
+const props = withDefaults(defineProps<ModalConfirmOptions>(), {
+  title: '',
+  content: '',
+  confirmText: undefined,
+  cancelText: undefined,
+  confirmButtonProps: () => ({}),
+  onConfirm: undefined,
+  onCancel: undefined,
+})
+
+const emit = defineEmits<{ closed: [] }>()
+
+const locale = useLocale()
+const visible = ref(true)
+const loading = ref(false)
+
+const confirmProps = computed(() => {
+  const { danger, ...rest } = props.confirmButtonProps
+  return danger && !rest.type ? { ...rest, type: 'danger' as const } : rest
+})
+
+async function handleConfirm() {
+  if (loading.value) return
+  loading.value = true
+  try {
+    await props.onConfirm?.()
+  } catch {
+    // 失败保持打开，等用户处理后重试或取消
+    loading.value = false
+    return
+  }
+  visible.value = false
+}
+
+/** 显式点「取消」按钮：触发 onCancel 并关闭（唯一会跑 onCancel 的路径） */
+function handleCancel() {
+  if (loading.value) return
+  props.onCancel?.()
+  visible.value = false
+}
+</script>
+
+<template>
+  <!-- 不绑 @cancel：遮罩 / Esc / 右上角 X 关闭时 Modal 会 emit('cancel')，
+       这里故意不接，让这些路径「静默关闭」而不触发 onCancel；
+       关窗本身由 v-model:open 完成（Modal 内部 setOpen(false) → update:open）。 -->
+  <G3Modal
+    v-model:open="visible"
+    :title="title"
+    :width="416"
+    :confirm-loading="loading"
+    @closed="emit('closed')"
+  >
+    <p v-if="content" class="g3-modal-confirm__content">{{ content }}</p>
+    <template #footer>
+      <G3Button type="outline" :disabled="loading" @click="handleCancel">
+        {{ cancelText ?? locale.common.cancel }}
+      </G3Button>
+      <G3Button v-bind="confirmProps" :loading="loading" @click="handleConfirm">
+        {{ confirmText ?? locale.common.confirm }}
+      </G3Button>
+    </template>
+  </G3Modal>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+.g3-modal-confirm__content {
+  margin: 0;
+  color: v('text-1', rgba(0, 0, 0, 0.88));
+  line-height: v('line-height', 1.5);
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/modal/confirm.ts b/code/g3soft-libs/packages/ui/src/modal/confirm.ts
new file mode 100644
index 00000000..178b008a
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/modal/confirm.ts
@@ -0,0 +1,39 @@
+import { createVNode, render } from 'vue'
+import G3ModalConfirm from './ModalConfirm.vue'
+import type { ModalConfirmHandle, ModalConfirmOptions } from './types'
+
+/**
+ * 命令式确认对话框：自建容器挂到 body，关闭动画结束（Modal 的 closed 事件）
+ * 后才卸载容器，保证退场动画完整播放。
+ *
+ * 用法：
+ * ```ts
+ * G3Modal.confirm({
+ *   title: '确定删除？',
+ *   content: '此操作不可恢复',
+ *   confirmText: '删除',
+ *   confirmButtonProps: { danger: true },
+ *   onConfirm: async () => { ... }, // 返回 Promise 时按钮进入 loading；reject 保持打开
+ *   onCancel: () => {},
+ * })
+ * ```
+ */
+export function confirm(options: ModalConfirmOptions = {}): ModalConfirmHandle {
+  const container = document.createElement('div')
+  const host = typeof document === 'undefined' ? null : document.body
+  host?.appendChild(container)
+
+  let destroyed = false
+  function destroy() {
+    if (destroyed) return
+    destroyed = true
+    render(null, container)
+    container.remove()
+  }
+
+  render(createVNode(G3ModalConfirm, { ...options, onClosed: destroy }), container)
+
+  return { destroy }
+}
+
+export default confirm
diff --git a/code/g3soft-libs/packages/ui/src/modal/index.ts b/code/g3soft-libs/packages/ui/src/modal/index.ts
new file mode 100644
index 00000000..f37e3738
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/modal/index.ts
@@ -0,0 +1,8 @@
+import G3ModalComponent from './Modal.vue'
+import { confirm } from './confirm'
+
+/** 对话框组件（带命令式 `confirm` 方法） */
+export const G3Modal = Object.assign(G3ModalComponent, { confirm })
+
+export { confirm as modalConfirm }
+export type { ModalConfirmHandle, ModalConfirmOptions, ModalProps } from './types'
diff --git a/code/g3soft-libs/packages/ui/src/modal/types.ts b/code/g3soft-libs/packages/ui/src/modal/types.ts
new file mode 100644
index 00000000..1644ee59
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/modal/types.ts
@@ -0,0 +1,61 @@
+import type { ButtonProps } from '../button/types'
+import type { PopupContainer } from '../_utils/global-config'
+
+export interface ModalProps {
+  /** 受控打开状态；不传则非受控，由 defaultOpen + 内部状态控制 */
+  open?: boolean
+  /** 非受控时的初始打开状态 */
+  defaultOpen?: boolean
+  /** 标题文字 */
+  title?: string
+  /** 面板宽度（px 数字或任意 CSS 宽度字符串） */
+  width?: number | string
+  /** 垂直居中显示 */
+  centered?: boolean
+  /** 是否显示遮罩 */
+  mask?: boolean
+  /** 点击遮罩关闭 */
+  maskClosable?: boolean
+  /** Esc 关闭 */
+  keyboard?: boolean
+  /** 显示右上角关闭按钮 */
+  closable?: boolean
+  /** 显示右上角全屏切换按钮 */
+  fullscreen?: boolean
+  /** 允许拖动右下角手柄调整宽高 */
+  resizable?: boolean
+  /** 显示底部按钮区（确定 / 取消）；配合 #footer 插槽自定义 */
+  footer?: boolean
+  /** 确认按钮文字 */
+  confirmText?: string
+  /** 取消按钮文字 */
+  cancelText?: string
+  /** 确认中：按钮 loading 且阻止一切关闭操作 */
+  confirmLoading?: boolean
+  /** 弹层挂载容器；不传时取 ConfigProvider.popupContainer，再退回 body */
+  popupContainer?: PopupContainer
+}
+
+/** 命令式确认对话框的参数 */
+export interface ModalConfirmOptions {
+  /** 标题 */
+  title?: string
+  /** 正文（纯文本）；也可用 content 插槽之外的富内容由 #content 提供 */
+  content?: string
+  /** 确认按钮文字 */
+  confirmText?: string
+  /** 取消按钮文字 */
+  cancelText?: string
+  /** 透传给确认按钮；`danger: true` 等价于 `type: 'danger'` */
+  confirmButtonProps?: Partial<ButtonProps> & { danger?: boolean }
+  /** 确认回调；返回 Promise 时按钮进入 loading（resolve 关闭、reject 保持打开） */
+  onConfirm?: () => void | Promise<unknown>
+  /** 取消回调；只有点「取消」按钮才会触发（遮罩 / Esc / 关闭按钮为静默关闭） */
+  onCancel?: () => void
+}
+
+/** 命令式确认对话框的句柄 */
+export interface ModalConfirmHandle {
+  /** 立即关闭并卸载（不等退场动画） */
+  destroy: () => void
+}
diff --git a/code/g3soft-libs/packages/ui/src/notification/Notification.vue b/code/g3soft-libs/packages/ui/src/notification/Notification.vue
new file mode 100644
index 00000000..3b2bdd83
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/notification/Notification.vue
@@ -0,0 +1,157 @@
+<script setup lang="ts">
+import { computed, onBeforeUnmount, onMounted } from 'vue'
+import { CircleCheck, CircleX, Info, TriangleAlert, X } from '@lucide/vue'
+import { useLocale } from '../_composables/useLocale'
+import { useNamespace } from '../_composables/useNamespace'
+import type { NotificationType } from './types'
+
+/**
+ * 通知提醒项 —— 由 G3Notification 命令式创建。
+ *
+ * 与轻提示的区别：通知带标题与描述，常驻时间更长，适合承载需要被阅读的信息。
+ */
+defineOptions({ name: 'G3Notification' })
+
+const props = withDefaults(
+  defineProps<{
+    /** 唯一标识，由管理器分配 */
+    id?: string
+    /** 类型 */
+    type?: NotificationType
+    /** 标题 */
+    title?: string
+    /** 描述内容 */
+    description?: string
+    /** 自动关闭时长（ms），<=0 时不自动关闭 */
+    duration?: number
+    /** 是否显示关闭按钮 */
+    closable?: boolean
+  }>(),
+  { id: '', type: 'info', title: '', description: '', duration: 4500, closable: true },
+)
+
+const emit = defineEmits<{ close: [] }>()
+
+const { b, e, m } = useNamespace('notification')
+const locale = useLocale()
+
+const ICONS = {
+  info: Info,
+  success: CircleCheck,
+  warning: TriangleAlert,
+  error: CircleX,
+}
+
+const iconComp = computed(() => ICONS[props.type] ?? Info)
+
+let timer: ReturnType<typeof setTimeout> | null = null
+
+function clearTimer() {
+  if (timer) {
+    clearTimeout(timer)
+    timer = null
+  }
+}
+
+function startTimer() {
+  if (props.duration > 0) timer = setTimeout(() => emit('close'), props.duration)
+}
+
+onMounted(startTimer)
+onBeforeUnmount(clearTimer)
+</script>
+
+<template>
+  <div :class="[b(), m(props.type)]" role="alert">
+    <component :is="iconComp" :class="e('icon')" aria-hidden="true" />
+    <div :class="e('body')">
+      <p v-if="title" :class="e('title')">{{ title }}</p>
+      <p v-if="description" :class="e('description')">{{ description }}</p>
+    </div>
+    <button
+      v-if="closable"
+      type="button"
+      :class="e('close')"
+      :aria-label="locale.common.close"
+      @click="emit('close')"
+    >
+      <X :size="14" />
+    </button>
+  </div>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+.#{b('notification')} {
+  display: flex;
+  align-items: flex-start;
+  gap: v('space-2', 8px);
+  box-sizing: border-box;
+  width: 340px;
+  max-width: calc(100vw - #{v('feedback-offset', 24px)} * 2);
+  padding: v('space-3', 12px) v('space-4', 16px);
+  border: 1px solid v('border-color', #d9d9d9);
+  border-radius: v('radius-lg', 8px);
+  background: v('bg-container', #fff);
+  box-shadow: v('shadow-popup', 0 6px 16px rgba(0, 0, 0, 0.12));
+  color: v('text-1', rgba(0, 0, 0, 0.88));
+  font-size: v('font-size', 14px);
+  line-height: v('line-height', 1.5);
+  pointer-events: auto;
+}
+
+.#{e('notification', 'icon')} {
+  flex-shrink: 0;
+  width: v('feedback-icon-size', 18px);
+  height: v('feedback-icon-size', 18px);
+  margin-top: 2px;
+}
+
+.#{b('notification')}.#{m('notification', 'info')} .#{e('notification', 'icon')} {
+  color: v('color-primary', #18181b);
+}
+
+.#{b('notification')}.#{m('notification', 'success')} .#{e('notification', 'icon')} {
+  color: v('color-success', #45b114);
+}
+
+.#{b('notification')}.#{m('notification', 'warning')} .#{e('notification', 'icon')} {
+  color: v('color-warning', #e79a0d);
+}
+
+.#{b('notification')}.#{m('notification', 'error')} .#{e('notification', 'icon')} {
+  color: v('color-danger', #ec4246);
+}
+
+.#{e('notification', 'body')} {
+  flex: 1;
+  min-width: 0;
+}
+
+.#{e('notification', 'title')} {
+  margin: 0;
+  font-weight: 600;
+}
+
+.#{e('notification', 'description')} {
+  margin: v('space-1', 4px) 0 0;
+  color: v('text-2', rgba(0, 0, 0, 0.65));
+}
+
+.#{e('notification', 'close')} {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  padding: 0;
+  border: 0;
+  background: transparent;
+  color: v('text-3', rgba(0, 0, 0, 0.45));
+  cursor: pointer;
+
+  &:hover {
+    color: v('text-1', rgba(0, 0, 0, 0.88));
+  }
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/notification/NotificationContainer.vue b/code/g3soft-libs/packages/ui/src/notification/NotificationContainer.vue
new file mode 100644
index 00000000..5a58b6e2
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/notification/NotificationContainer.vue
@@ -0,0 +1,131 @@
+<script setup lang="ts">
+import { useNamespace } from '../_composables/useNamespace'
+import G3Notification from './Notification.vue'
+import { notificationState } from './store'
+import type { NotificationPlacement } from './types'
+
+/**
+ * 通知容器 —— 由 G3Notification 管理器创建的单例挂载点，业务不直接使用。
+ *
+ * 四个角的分组容器始终存在，只有通知项进出，保证进出场动画稳定触发。
+ */
+defineOptions({ name: 'G3NotificationContainer' })
+
+const props = withDefaults(
+  defineProps<{
+    /** 容器层级（由管理器分配） */
+    zIndex?: number
+  }>(),
+  { zIndex: 0 },
+)
+
+const { e } = useNamespace('notification')
+
+const PLACEMENTS: NotificationPlacement[] = [
+  'top-right',
+  'top-left',
+  'bottom-right',
+  'bottom-left',
+]
+
+function close(id: string) {
+  const index = notificationState.items.findIndex((item) => item.id === id)
+  if (index !== -1) notificationState.items.splice(index, 1)
+}
+
+function itemsOf(placement: NotificationPlacement) {
+  return notificationState.items.filter(
+    (item) => (item.placement || notificationState.placement) === placement,
+  )
+}
+</script>
+
+<template>
+  <div :class="e('container')" :style="{ zIndex: props.zIndex || undefined }" aria-live="polite">
+    <TransitionGroup
+      v-for="placement in PLACEMENTS"
+      :key="placement"
+      name="g3-notification"
+      tag="div"
+      :class="[e('list'), `g3-notification-list--${placement}`]"
+    >
+      <G3Notification
+        v-for="item in itemsOf(placement)"
+        :key="item.id"
+        :id="item.id"
+        :type="item.type"
+        :title="item.title"
+        :description="item.description"
+        :duration="item.duration"
+        :closable="item.closable"
+        @close="close(item.id)"
+      />
+    </TransitionGroup>
+  </div>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+.#{e('notification', 'container')} {
+  position: fixed;
+  inset: 0;
+  pointer-events: none;
+}
+
+.#{e('notification', 'list')} {
+  position: absolute;
+  display: flex;
+  flex-direction: column;
+  gap: v('space-3', 12px);
+  box-sizing: border-box;
+  padding: v('feedback-offset', 24px);
+}
+
+.g3-notification-list--top-right {
+  top: 0;
+  right: 0;
+  align-items: flex-end;
+}
+
+.g3-notification-list--top-left {
+  top: 0;
+  left: 0;
+  align-items: flex-start;
+}
+
+.g3-notification-list--bottom-right {
+  bottom: 0;
+  right: 0;
+  align-items: flex-end;
+  flex-direction: column-reverse;
+}
+
+.g3-notification-list--bottom-left {
+  bottom: 0;
+  left: 0;
+  align-items: flex-start;
+  flex-direction: column-reverse;
+}
+
+/* ---------- 进出场 ---------- */
+.g3-notification-enter-active,
+.g3-notification-leave-active {
+  transition:
+    opacity v('duration', 0.2s) v('ease', ease),
+    transform v('duration', 0.2s) v('ease', ease);
+}
+
+.g3-notification-enter-from,
+.g3-notification-leave-to {
+  opacity: 0;
+  transform: translateX(16px);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .g3-notification-enter-active,
+  .g3-notification-leave-active {
+    transition-duration: 0ms;
+  }
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/notification/index.ts b/code/g3soft-libs/packages/ui/src/notification/index.ts
new file mode 100644
index 00000000..797e68c6
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/notification/index.ts
@@ -0,0 +1,12 @@
+export { default as G3NotificationItem } from './Notification.vue'
+export { default as G3NotificationContainer } from './NotificationContainer.vue'
+export { default as G3Notification } from './manager'
+export { notificationState } from './store'
+export type {
+  NotificationConfig,
+  NotificationHandle,
+  NotificationItemState,
+  NotificationOptions,
+  NotificationPlacement,
+  NotificationType,
+} from './types'
diff --git a/code/g3soft-libs/packages/ui/src/notification/manager.ts b/code/g3soft-libs/packages/ui/src/notification/manager.ts
new file mode 100644
index 00000000..13791fb5
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/notification/manager.ts
@@ -0,0 +1,85 @@
+import { createVNode, render } from 'vue'
+import { nextZIndex, releaseZIndex } from '../_utils/z-index'
+import G3NotificationContainer from './NotificationContainer.vue'
+import { notificationState } from './store'
+import type {
+  NotificationConfig,
+  NotificationHandle,
+  NotificationOptions,
+} from './types'
+
+/* ---------- 单例容器 ---------- */
+let containerEl: HTMLElement | null = null
+let containerZIndex = 0
+let seed = 0
+
+function ensureContainer() {
+  if (containerEl || typeof document === 'undefined') return
+  containerEl = document.createElement('div')
+  document.body.appendChild(containerEl)
+  // 与轻提示同档（feedback）：必须浮于弹窗之上
+  containerZIndex = nextZIndex('feedback')
+  render(createVNode(G3NotificationContainer, { zIndex: containerZIndex }), containerEl)
+}
+
+function remove(id: string) {
+  const index = notificationState.items.findIndex((item) => item.id === id)
+  if (index !== -1) notificationState.items.splice(index, 1)
+}
+
+function open(options: NotificationOptions): NotificationHandle {
+  ensureContainer()
+  const id = `g3-notification-${++seed}`
+  // 逐项归一，避免 options 里显式的 undefined 覆盖掉全局默认值
+  notificationState.items.push({
+    id,
+    type: options.type ?? 'info',
+    title: options.title ?? '',
+    description: options.description ?? '',
+    duration: options.duration ?? notificationState.duration,
+    closable: options.closable ?? true,
+    placement: options.placement ?? notificationState.placement,
+  })
+  return { close: () => remove(id) }
+}
+
+type ShortcutOptions = Omit<NotificationOptions, 'type'>
+
+/**
+ * 通知提醒 —— 命令式调用，组件树外挂载（自动读取全局配置的命名空间 / 语言包 / 容器）。
+ *
+ * ```ts
+ * G3Notification.success({ title: '发布成功', description: '版本 1.2.0 已上线' })
+ * ```
+ */
+export const G3Notification = {
+  /** 通用入口 */
+  open,
+  info: (options: ShortcutOptions) => open({ ...options, type: 'info' }),
+  success: (options: ShortcutOptions) => open({ ...options, type: 'success' }),
+  warning: (options: ShortcutOptions) => open({ ...options, type: 'warning' }),
+  error: (options: ShortcutOptions) => open({ ...options, type: 'error' }),
+  /** 关闭指定通知 */
+  close: (id: string) => remove(id),
+  /** 全局配置：默认方位与默认时长 */
+  config: (config: NotificationConfig) => {
+    if (config.placement) notificationState.placement = config.placement
+    if (config.duration != null) notificationState.duration = config.duration
+  },
+  /** 清空全部通知并卸载容器 */
+  destroy: () => {
+    notificationState.items.splice(0, notificationState.items.length)
+    if (!containerEl) return
+    render(null, containerEl)
+    containerEl.remove()
+    containerEl = null
+    if (containerZIndex) {
+      releaseZIndex(containerZIndex)
+      containerZIndex = 0
+    }
+  },
+  /** 当前存活的通知条数（调试用） */
+  count: () => notificationState.items.length,
+}
+
+export default G3Notification
diff --git a/code/g3soft-libs/packages/ui/src/notification/store.ts b/code/g3soft-libs/packages/ui/src/notification/store.ts
new file mode 100644
index 00000000..4b2871c5
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/notification/store.ts
@@ -0,0 +1,15 @@
+import { reactive } from 'vue'
+import type { NotificationItemState, NotificationPlacement } from './types'
+
+/** 全局共享的 Notification 活跃列表：管理器写入、容器读取，保证响应式联动 */
+export const notificationState = reactive<{
+  items: NotificationItemState[]
+  /** 默认方位 */
+  placement: NotificationPlacement
+  /** 默认自动关闭时长（ms） */
+  duration: number
+}>({
+  items: [],
+  placement: 'top-right',
+  duration: 4500,
+})
diff --git a/code/g3soft-libs/packages/ui/src/notification/types.ts b/code/g3soft-libs/packages/ui/src/notification/types.ts
new file mode 100644
index 00000000..c80f2bc4
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/notification/types.ts
@@ -0,0 +1,47 @@
+import type { MessageType } from '../message/types'
+
+/** 通知类型 */
+export type NotificationType = MessageType
+
+/** 通知方位（通知只出现在四角） */
+export type NotificationPlacement = 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left'
+
+export interface NotificationOptions {
+  /** 标题 */
+  title?: string
+  /** 描述内容 */
+  description?: string
+  /** 类型 */
+  type?: NotificationType
+  /** 自动关闭时长（ms），<=0 时不自动关闭 */
+  duration?: number
+  /** 是否显示关闭按钮 */
+  closable?: boolean
+  /** 显示方位，默认取全局配置 */
+  placement?: NotificationPlacement
+}
+
+/** 容器内单条通知的完整状态 */
+export interface NotificationItemState {
+  id: string
+  title: string
+  description: string
+  type: NotificationType
+  duration: number
+  closable: boolean
+  placement: NotificationPlacement
+}
+
+/** 命令式调用的返回句柄 */
+export interface NotificationHandle {
+  /** 关闭这一条 */
+  close: () => void
+}
+
+/** 全局配置项 */
+export interface NotificationConfig {
+  /** 默认方位 */
+  placement?: NotificationPlacement
+  /** 默认自动关闭时长 */
+  duration?: number
+}
diff --git a/code/g3soft-libs/packages/ui/src/pagination/Pagination.vue b/code/g3soft-libs/packages/ui/src/pagination/Pagination.vue
new file mode 100644
index 00000000..82de3f38
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/pagination/Pagination.vue
@@ -0,0 +1,364 @@
+<script setup lang="ts">
+import { computed, ref, watch } from 'vue'
+import { ChevronLeft, ChevronRight, ChevronsLeft, ChevronsRight, Ellipsis } from '@lucide/vue'
+import { useLocale } from '../_composables/useLocale'
+import { useNamespace } from '../_composables/useNamespace'
+import G3Input from '../input/Input.vue'
+import G3Select from '../select/Select.vue'
+import type { PaginationProps, PaginationTotalScope } from './types'
+
+/**
+ * 分页器 —— 页码、每页条数、快速跳转与总条数。
+ *
+ * 受控（`v-model:current` / `v-model:pageSize`）与非受控都支持；
+ * 受控值越界时只收敛显示、不回写，保证受控语义干净。
+ */
+defineOptions({ name: 'G3Pagination' })
+
+const props = withDefaults(defineProps<PaginationProps>(), {
+  current: undefined,
+  pageSize: undefined,
+  total: 0,
+  disabled: false,
+  hideOnSinglePage: false,
+  showSizeChanger: false,
+  pageSizeOptions: () => [10, 20, 50, 100],
+  showQuickJumper: false,
+  showTotal: false,
+})
+
+const emit = defineEmits<{
+  'update:current': [page: number]
+  'update:pageSize': [size: number]
+  change: [page: number, pageSize: number]
+  showSizeChange: [current: number, size: number]
+}>()
+
+const { b, e, m, is } = useNamespace('pagination')
+const locale = useLocale()
+
+const innerCurrent = ref(1)
+const innerPageSize = ref(10)
+
+const totalPages = computed(() =>
+  Math.max(1, Math.ceil((Number(props.total) || 0) / (props.pageSize ?? innerPageSize.value))),
+)
+
+function clampPage(page: number, pages: number): number {
+  return Math.min(pages, Math.max(1, page))
+}
+
+const currentValue = computed(() =>
+  clampPage(Number(props.current ?? innerCurrent.value) || 1, totalPages.value),
+)
+
+const sizeValue = computed(() => Number(props.pageSize ?? innerPageSize.value) || 10)
+
+const rangeFrom = computed(() =>
+  (Number(props.total) || 0) === 0 ? 0 : (currentValue.value - 1) * sizeValue.value + 1,
+)
+const rangeTo = computed(() =>
+  Math.min(Number(props.total) || 0, currentValue.value * sizeValue.value),
+)
+
+const totalScope = computed<PaginationTotalScope>(() => ({
+  total: Number(props.total) || 0,
+  from: rangeFrom.value,
+  to: rangeTo.value,
+}))
+
+interface PageItem {
+  type: 'page' | 'jump-prev' | 'jump-next'
+  page: number
+  label?: string
+}
+
+/** 页码窗口：≤7 页全展开，否则固定首尾 + 当前页 ±1 + 省略号（点击跳 ±5） */
+const pageItems = computed<PageItem[]>(() => {
+  const total = totalPages.value
+  const current = currentValue.value
+  if (total <= 7) {
+    return Array.from({ length: total }, (_, index) => ({ type: 'page' as const, page: index + 1 }))
+  }
+  const items: PageItem[] = [{ type: 'page', page: 1 }]
+  if (current > 4) items.push({ type: 'jump-prev', page: Math.max(1, current - 5) })
+  const start = Math.max(2, current - 1)
+  const end = Math.min(total - 1, current + 1)
+  for (let page = start; page <= end; page++) items.push({ type: 'page', page })
+  if (current < total - 3) items.push({ type: 'jump-next', page: Math.min(total, current + 5) })
+  items.push({ type: 'page', page: total })
+  // 去重（保留首尾），省略号不参与去重
+  return items.filter(
+    (item, index) => item.type !== 'page' || index === 0 || item.page !== items[index - 1].page,
+  )
+})
+
+const sizeOptions = computed(() =>
+  props.pageSizeOptions.map((option) => ({ label: `${option}`, value: Number(option) })),
+)
+
+function emitChange(page: number, size: number) {
+  emit('change', page, size)
+}
+
+function goToPage(page: number) {
+  if (props.disabled) return
+  const next = clampPage(page, totalPages.value)
+  if (next === currentValue.value) return
+  if (props.current == null) innerCurrent.value = next
+  emit('update:current', next)
+  emitChange(next, sizeValue.value)
+}
+
+function onSizeChange(size: number) {
+  if (props.disabled) return
+  const nextSize = Number(size) || 10
+  if (props.pageSize == null) innerPageSize.value = nextSize
+  emit('update:pageSize', nextSize)
+  emit('showSizeChange', currentValue.value, nextSize)
+  // 保持当前页尽量不变，但不超过新的总页数
+  const pages = Math.max(1, Math.ceil((Number(props.total) || 0) / nextSize))
+  const nextPage = clampPage(currentValue.value, pages)
+  if (props.current == null) innerCurrent.value = nextPage
+  if (nextPage !== currentValue.value) emit('update:current', nextPage)
+  emitChange(nextPage, nextSize)
+}
+
+/* ---------- 快速跳转 ---------- */
+const jumpText = ref('')
+
+function submitJump() {
+  const parsed = Number.parseInt(jumpText.value, 10)
+  jumpText.value = ''
+  if (!Number.isFinite(parsed)) return
+  goToPage(parsed)
+}
+
+watch(totalPages, (pages) => {
+  // 非受控下当前页超出总页数：回退到末页（受控由调用方决定）
+  if (props.current == null && innerCurrent.value > pages) innerCurrent.value = pages
+})
+
+const visible = computed(() => !props.hideOnSinglePage || totalPages.value > 1)
+</script>
+
+<template>
+  <nav
+    v-if="visible"
+    :class="[b(), { [is('disabled')]: disabled }]"
+    role="navigation"
+    :aria-label="locale.pagination.total"
+    data-slot="pagination"
+  >
+    <span v-if="showTotal" :class="e('total')">
+      <slot name="showTotal" v-bind="totalScope">
+        {{ locale.pagination.total.replace('{total}', String(totalScope.total)) }}
+      </slot>
+    </span>
+
+    <ul :class="e('list')">
+      <li :class="e('item')">
+        <button
+          type="button"
+          :class="e('prev')"
+          :aria-label="locale.pagination.prev"
+          :disabled="disabled || currentValue <= 1"
+          @click="goToPage(currentValue - 1)"
+        >
+          <ChevronLeft aria-hidden="true" />
+        </button>
+      </li>
+
+      <li v-for="(item, index) in pageItems" :key="`${item.type}-${item.page}-${index}`" :class="e('item')">
+        <button
+          v-if="item.type === 'page'"
+          type="button"
+          :class="[e('page'), { [is('page-current')]: item.page === currentValue }]"
+          :aria-current="item.page === currentValue ? 'page' : undefined"
+          :disabled="disabled"
+          @click="goToPage(item.page)"
+        >
+          {{ item.page }}
+        </button>
+        <button
+          v-else
+          type="button"
+          :class="e('ellipsis')"
+          :aria-label="
+            item.type === 'jump-prev'
+              ? `${locale.pagination.prev} 5 ${locale.pagination.page}`
+              : `${locale.pagination.next} 5 ${locale.pagination.page}`
+          "
+          :disabled="disabled"
+          @click="goToPage(item.page)"
+        >
+          <Ellipsis :class="e('ellipsis-more')" aria-hidden="true" />
+          <span :class="e('ellipsis-jump')" aria-hidden="true">
+            <ChevronsLeft v-if="item.type === 'jump-prev'" />
+            <ChevronsRight v-else />
+          </span>
+        </button>
+      </li>
+
+      <li :class="e('item')">
+        <button
+          type="button"
+          :class="e('next')"
+          :aria-label="locale.pagination.next"
+          :disabled="disabled || currentValue >= totalPages"
+          @click="goToPage(currentValue + 1)"
+        >
+          <ChevronRight aria-hidden="true" />
+        </button>
+      </li>
+    </ul>
+
+    <div v-if="showSizeChanger" :class="e('size-changer')">
+      <G3Select
+        :model-value="sizeValue"
+        :options="sizeOptions"
+        :filterable="false"
+        :disabled="disabled"
+        aria-label="每页条数"
+        @change="onSizeChange($event as number)"
+      />
+    </div>
+
+    <div v-if="showQuickJumper" :class="e('jumper')">
+      <span>{{ locale.pagination.goto }}</span>
+      <G3Input
+        v-model="jumpText"
+        type="number"
+        :class="e('jumper-input')"
+        aria-label="跳至页码"
+        @keydown.enter="submitJump"
+      />
+      <span>{{ locale.pagination.page }}</span>
+    </div>
+  </nav>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+.#{b('pagination')} {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: v('space-3', 12px);
+  color: v('text-1', rgba(0, 0, 0, 0.88));
+  font-size: v('font-size', 14px);
+}
+
+.#{e('pagination', 'total')} {
+  color: v('text-2', rgba(0, 0, 0, 0.65));
+}
+
+.#{e('pagination', 'list')} {
+  display: flex;
+  align-items: center;
+  gap: v('space-1', 4px);
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.#{e('pagination', 'item')} {
+  display: inline-flex;
+}
+
+.#{e('pagination', 'page')},
+.#{e('pagination', 'prev')},
+.#{e('pagination', 'next')},
+.#{e('pagination', 'ellipsis')} {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  box-sizing: border-box;
+  min-width: v('control-height', 32px);
+  height: v('control-height', 32px);
+  padding: 0 v('space-1', 4px);
+  border: 1px solid transparent;
+  border-radius: v('radius', 6px);
+  background: transparent;
+  color: inherit;
+  font-family: inherit;
+  font-size: inherit;
+  font-variant-numeric: tabular-nums;
+  cursor: pointer;
+  transition:
+    background-color v('duration-fast', 0.1s) v('ease', ease),
+    border-color v('duration-fast', 0.1s) v('ease', ease),
+    transform v('duration-fast', 0.1s) v('ease', ease);
+
+  svg {
+    width: 16px;
+    height: 16px;
+  }
+
+  &:hover:not(:disabled) {
+    background: v('fill', rgba(0, 0, 0, 0.04));
+  }
+
+  &:active:not(:disabled) {
+    transform: scale(0.96);
+  }
+
+  &:focus-visible {
+    @include focus-ring();
+  }
+
+  &:disabled {
+    color: v('text-disabled', rgba(0, 0, 0, 0.25));
+    cursor: not-allowed;
+  }
+}
+
+/* 当前页：hover 也要保住主色填充。
+   通用 `&:hover:not(:disabled)` 的背景规则（3 个伪类）特异性更高，
+   不把 :hover 并进来就会被它盖成浅色底 —— 白底配白字，页码直接消失 */
+.#{e('pagination', 'page')}.#{is('page-current')},
+.#{e('pagination', 'page')}.#{is('page-current')}:hover:not(:disabled) {
+  border-color: v('color-primary', #18181b);
+  background: v('color-primary', #18181b);
+  color: v('color-primary-on', #fafafa);
+  font-weight: 500;
+}
+
+/* 省略号：默认显示「…」，hover 时切换成跳跃图标 */
+.#{e('pagination', 'ellipsis')} {
+  position: relative;
+}
+
+.#{e('pagination', 'ellipsis-jump')} {
+  display: none;
+}
+
+.#{e('pagination', 'ellipsis')}:hover .#{e('pagination', 'ellipsis-more')} {
+  display: none;
+}
+
+.#{e('pagination', 'ellipsis')}:hover .#{e('pagination', 'ellipsis-jump')} {
+  display: inline-flex;
+}
+
+.#{e('pagination', 'size-changer')} {
+  width: 96px;
+  min-width: 96px;
+}
+
+.#{e('pagination', 'jumper')} {
+  display: inline-flex;
+  align-items: center;
+  gap: v('space-1', 4px);
+  color: v('text-2', rgba(0, 0, 0, 0.65));
+}
+
+.#{e('pagination', 'jumper-input')} {
+  width: 64px;
+}
+
+.#{b('pagination')}.#{is('disabled')} {
+  opacity: 0.6;
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/pagination/index.ts b/code/g3soft-libs/packages/ui/src/pagination/index.ts
new file mode 100644
index 00000000..08fa9bdb
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/pagination/index.ts
@@ -0,0 +1,2 @@
+export { default as G3Pagination } from './Pagination.vue'
+export type { PaginationProps, PaginationTotalScope } from './types'
diff --git a/code/g3soft-libs/packages/ui/src/pagination/types.ts b/code/g3soft-libs/packages/ui/src/pagination/types.ts
new file mode 100644
index 00000000..f2f9ab37
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/pagination/types.ts
@@ -0,0 +1,29 @@
+export interface PaginationProps {
+  /** 当前页（v-model:current）；不传则内部维护，默认 1 */
+  current?: number
+  /** 每页条数（v-model:pageSize）；不传则内部维护，默认 10 */
+  pageSize?: number
+  /** 总条数 */
+  total?: number
+  /** 整组禁用 */
+  disabled?: boolean
+  /** 仅 1 页时隐藏整个分页器 */
+  hideOnSinglePage?: boolean
+  /** 显示每页条数选择器 */
+  showSizeChanger?: boolean
+  /** 每页条数选项 */
+  pageSizeOptions?: Array<number | string>
+  /** 显示快速跳转输入框 */
+  showQuickJumper?: boolean
+  /** 显示「共 X 条」 */
+  showTotal?: boolean
+}
+
+/** #showTotal 插槽作用域 */
+export interface PaginationTotalScope {
+  total: number
+  /** 当前页第一条的序号（total 为 0 时是 0） */
+  from: number
+  /** 当前页最后一条的序号 */
+  to: number
+}
diff --git a/code/g3soft-libs/packages/ui/src/popover/Popover.vue b/code/g3soft-libs/packages/ui/src/popover/Popover.vue
new file mode 100644
index 00000000..45257dd6
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/popover/Popover.vue
@@ -0,0 +1,401 @@
+<script setup lang="ts">
+import { computed, nextTick, onBeforeUnmount, ref, useSlots, watch } from 'vue'
+import { useFloating } from '../_composables/useFloating'
+import { useNamespace } from '../_composables/useNamespace'
+import { usePopupContainer } from '../_composables/usePopupContainer'
+import { useUnwrappedTrigger } from '../_composables/useUnwrappedTrigger'
+import type { RectLike } from '../_utils/position'
+import { nextZIndex, releaseZIndex } from '../_utils/z-index'
+import type { PopoverProps } from './types'
+
+/**
+ * 气泡卡片 —— 在触发器旁弹出浮层，是 Tooltip / Dropdown / Select 等浮层组件的基础。
+ *
+ * 自行完成定位（12 方位 + 翻转 + 视口约束）、Teleport、点击外部与 Esc 关闭、
+ * 滚动 / 尺寸变化跟随重算；`unwrapped` 模式下不给触发器加任何包裹 DOM。
+ */
+defineOptions({ name: 'G3Popover' })
+
+const props = withDefaults(defineProps<PopoverProps>(), {
+  open: undefined,
+  defaultOpen: false,
+  trigger: 'click',
+  placement: 'top',
+  offset: 12,
+  arrow: true,
+  disabled: false,
+  mouseEnterDelay: 100,
+  mouseLeaveDelay: 100,
+  contentClass: '',
+  followTriggerWidth: false,
+  unwrapped: false,
+  popupContainer: undefined,
+})
+
+const emit = defineEmits<{
+  'update:open': [value: boolean]
+  openChange: [value: boolean]
+}>()
+
+const slots = useSlots()
+const { b, e, m, is } = useNamespace('popover')
+const teleportTo = usePopupContainer(() => props.popupContainer)
+
+const triggerEl = ref<HTMLElement | null>(null)
+const internalOpen = ref(props.defaultOpen)
+const zIndex = ref(0)
+
+// contextmenu 触发时记录右键锚点，浮层对齐鼠标位置；非右键模式恒为 null
+let pointAnchor: RectLike | null = null
+
+const isOpen = computed({
+  get: () => (props.open !== undefined ? props.open : internalOpen.value),
+  set: (value: boolean) => {
+    if (props.open === undefined) internalOpen.value = value
+    emit('update:open', value)
+    emit('openChange', value)
+  },
+})
+
+const { floatingRef, floatingStyle, resolvedPlacement, resolvedBase, updatePosition } = useFloating({
+  open: isOpen,
+  placement: () => props.placement,
+  offset: () => props.offset,
+  followTriggerWidth: () => props.followTriggerWidth,
+  triggerRef: triggerEl,
+  anchor: () => pointAnchor,
+  onClickOutside: () => setOpen(false),
+  onEscape: () => setOpen(false),
+})
+
+const popupStyle = computed(() => ({
+  ...floatingStyle.value,
+  zIndex: zIndex.value || undefined,
+}))
+
+const transitionName = computed(() => b())
+
+/* ---------- 展开 / 收起 ---------- */
+let enterTimer: ReturnType<typeof setTimeout> | null = null
+let leaveTimer: ReturnType<typeof setTimeout> | null = null
+
+function clearTimers() {
+  if (enterTimer) {
+    clearTimeout(enterTimer)
+    enterTimer = null
+  }
+  if (leaveTimer) {
+    clearTimeout(leaveTimer)
+    leaveTimer = null
+  }
+}
+
+function setOpen(value: boolean) {
+  if (props.disabled && value) return
+  clearTimers()
+  // 层级统一交给下面的 watch(isOpen) 分配：受控打开（Select / DatePicker 直接改 open）
+  // 不会走这里，但同样需要 z-index，集中一处才不会漏
+  isOpen.value = value
+  if (!value) pointAnchor = null
+}
+
+function toggle() {
+  setOpen(!isOpen.value)
+}
+
+/* ---------- 触发器交互 ---------- */
+function onClick() {
+  if (props.trigger === 'click') toggle()
+}
+
+function onContextMenu(event: Event) {
+  if (props.trigger !== 'contextmenu') return
+  const mouseEvent = event as MouseEvent
+  mouseEvent.preventDefault()
+  const { clientX, clientY } = mouseEvent
+  // 右键在鼠标位置弹出：构造零尺寸锚点矩形，flip / shift 会兜底防溢出
+  pointAnchor = {
+    left: clientX,
+    top: clientY,
+    right: clientX,
+    bottom: clientY,
+    width: 0,
+    height: 0,
+  }
+  if (isOpen.value) updatePosition()
+  else setOpen(true)
+}
+
+function onMouseEnter() {
+  if (props.trigger !== 'hover') return
+  clearTimers()
+  enterTimer = setTimeout(() => setOpen(true), props.mouseEnterDelay)
+}
+
+function onMouseLeave() {
+  if (props.trigger !== 'hover') return
+  clearTimers()
+  leaveTimer = setTimeout(() => setOpen(false), props.mouseLeaveDelay)
+}
+
+function onFocusIn() {
+  if (props.trigger === 'focus') setOpen(true)
+}
+
+function onFocusOut(event: Event) {
+  if (props.trigger !== 'focus') return
+  // 焦点移入浮层内部（如输入框）时不关闭
+  const related = (event as FocusEvent).relatedTarget as Node | null
+  if (floatingRef.value && related && floatingRef.value.contains(related)) return
+  setOpen(false)
+}
+
+/* ---------- 零包裹模式 ---------- */
+const { injectedTrigger, InjectedTrigger } = useUnwrappedTrigger({
+  enabled: () => props.unwrapped,
+  slots,
+  triggerEl,
+  isOpen: () => isOpen.value,
+  handlers: {
+    onClick,
+    onContextmenu: onContextMenu,
+    onMouseenter: onMouseEnter,
+    onMouseleave: onMouseLeave,
+    onFocusin: onFocusIn,
+    onFocusout: onFocusOut,
+  },
+  onAttach: updatePosition,
+})
+
+/* ---------- 生命周期 ---------- */
+// 层级在这里集中分配 / 回收：
+// - 打开（含受控打开）：没分配过就取一个 popup 档值。漏了这一步的浮层 z-index 为 auto，
+//   在 Modal / Drawer 里会被遮罩（modal 档）盖住，表现为「下拉打不开 / 是空的」。
+// - 关闭：回收层级，避免页面反复开关把 z-index 推高。
+// immediate：`defaultOpen` / `:open="true"` 挂载即展开时不会发生「变化」，不加就永远没有层级。
+watch(
+  isOpen,
+  (value) => {
+    if (value) {
+      if (!zIndex.value) zIndex.value = nextZIndex('popup')
+      nextTick(updatePosition)
+      return
+    }
+    if (zIndex.value) {
+      releaseZIndex(zIndex.value)
+      zIndex.value = 0
+    }
+  },
+  { immediate: true },
+)
+
+onBeforeUnmount(() => {
+  clearTimers()
+  if (zIndex.value) releaseZIndex(zIndex.value)
+})
+</script>
+
+<template>
+  <!-- 零包裹：直接渲染注入事件后的用户 vnode，锚点由指令同步；无中间 DOM -->
+  <component :is="InjectedTrigger" v-if="injectedTrigger" />
+
+  <!-- 包裹层回退：unwrapped=false、多根 fragment、文本节点三种情况走此分支 -->
+  <span
+    v-else
+    ref="triggerEl"
+    :class="b()"
+    @click="onClick"
+    @contextmenu="onContextMenu"
+    @mouseenter="onMouseEnter"
+    @mouseleave="onMouseLeave"
+    @focusin="onFocusIn"
+    @focusout="onFocusOut"
+  >
+    <slot name="trigger" />
+  </span>
+
+  <Teleport :to="teleportTo">
+    <Transition :name="transitionName">
+      <div
+        v-if="isOpen"
+        ref="floatingRef"
+        :class="[
+          e('popup'),
+          m(resolvedBase),
+          m(resolvedPlacement),
+          { [is('follow-trigger-width')]: followTriggerWidth, [is('unwrapped')]: !!injectedTrigger },
+        ]"
+        :style="popupStyle"
+        role="dialog"
+        @mouseenter="onMouseEnter"
+        @mouseleave="onMouseLeave"
+      >
+        <span v-if="arrow" :class="e('arrow')" aria-hidden="true">
+          <span :class="e('arrow-content')" />
+        </span>
+        <div :class="[e('content'), contentClass]">
+          <slot name="content" />
+        </div>
+      </div>
+    </Transition>
+  </Teleport>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+/* 包裹层：inline-flex + 收缩到内容宽度，避免在 grid 上下文里被拉伸导致浮层居中偏移 */
+.#{b('popover')} {
+  display: inline-flex;
+  justify-self: start;
+}
+
+.#{e('popover', 'popup')} {
+  position: fixed;
+  /* 在完整轮廓上统一投影，让箭头和主体拥有连续的视觉重量 */
+  filter: drop-shadow(v('shadow-popup', 0 6px 16px rgba(0, 0, 0, 0.12)));
+}
+
+.#{e('popover', 'content')} {
+  position: relative;
+  padding: v('space-2', 8px);
+  /* 不描边：投影统一由 .g3-popover__popup 的 drop-shadow 施加（含箭头）。
+     留下 1px 边框时箭头与主体之间会露出接缝，Tooltip 还会多一圈描边 */
+  border: 0;
+  border-radius: v('radius', 6px);
+  background: v('bg-container', #fff);
+  color: v('text-1', rgba(0, 0, 0, 0.88));
+  font-size: v('font-size', 14px);
+  line-height: v('line-height', 1.5);
+}
+
+/* 跟随触发器宽度：浮层宽度 = max(触发器宽, 内容宽)，内容铺满整条不露空档 */
+.#{b('popover')}.#{is('follow-trigger-width')} .#{e('popover', 'content')} {
+  box-sizing: border-box;
+  width: 100%;
+}
+
+/* ---------- 箭头 ---------- */
+.#{e('popover', 'arrow')} {
+  position: absolute;
+  z-index: 1;
+  display: block;
+  width: 20px;
+  height: 20px;
+  overflow: hidden;
+  pointer-events: none;
+}
+
+.#{e('popover', 'arrow-content')} {
+  position: absolute;
+  inset-inline: 0;
+  bottom: 0;
+  width: 20px;
+  height: 10px;
+  background: v('bg-container', #fff);
+  clip-path: polygon(0 100%, 50% 0, 100% 100%);
+}
+
+/* 浮层在触发器上方：箭头在浮层下边，尖角朝下。位移收 20%（4px）让三角与内容块重叠，
+   同色背景连成一体，消除投影在交界处的分割线 */
+.#{m('popover', 'top')} .#{e('popover', 'arrow')} {
+  bottom: 0;
+  left: 50%;
+  transform: translateX(-50%) translateY(80%) rotate(180deg);
+}
+
+.#{m('popover', 'bottom')} .#{e('popover', 'arrow')} {
+  top: 0;
+  left: 50%;
+  transform: translateX(-50%) translateY(-80%);
+}
+
+.#{m('popover', 'left')} .#{e('popover', 'arrow')} {
+  right: 0;
+  top: 50%;
+  transform: translateX(80%) translateY(-50%) rotate(90deg);
+}
+
+.#{m('popover', 'right')} .#{e('popover', 'arrow')} {
+  left: 0;
+  top: 50%;
+  transform: translateX(-80%) translateY(-50%) rotate(-90deg);
+}
+
+/* start / end 对齐时，箭头从居中移到靠近触发器边缘一侧 */
+.#{m('popover', 'top-start')} .#{e('popover', 'arrow')},
+.#{m('popover', 'bottom-start')} .#{e('popover', 'arrow')} {
+  left: 16px;
+}
+
+.#{m('popover', 'top-end')} .#{e('popover', 'arrow')},
+.#{m('popover', 'bottom-end')} .#{e('popover', 'arrow')} {
+  left: auto;
+  right: 16px;
+}
+
+.#{m('popover', 'left-start')} .#{e('popover', 'arrow')},
+.#{m('popover', 'right-start')} .#{e('popover', 'arrow')} {
+  top: 16px;
+}
+
+/* left/right-end：bottom 定位已把箭头放到底部，必须同时覆盖 transform */
+.#{m('popover', 'left-end')} .#{e('popover', 'arrow')} {
+  top: auto;
+  bottom: 4px;
+  transform: translateX(80%) rotate(90deg);
+}
+
+.#{m('popover', 'right-end')} .#{e('popover', 'arrow')} {
+  top: auto;
+  bottom: 4px;
+  transform: translateX(-80%) rotate(-90deg);
+}
+
+/* ---------- 进出场 ----------
+ * 只过渡 opacity / transform：定位写在 top / left 上，纳入过渡会从屏幕左上角滑到目标位置。 */
+.#{b('popover')}-enter-active {
+  transition:
+    opacity v('duration', 0.2s) v('ease', ease),
+    transform v('duration', 0.2s) v('ease', ease);
+}
+
+.#{b('popover')}-leave-active {
+  transition:
+    opacity v('duration-fast', 0.1s) v('ease', ease),
+    transform v('duration-fast', 0.1s) v('ease', ease);
+}
+
+.#{b('popover')}-enter-from,
+.#{b('popover')}-leave-to {
+  opacity: 0;
+}
+
+/* 位移方向跟随浮层方位：视觉上从触发器一侧「长出来」 */
+.#{b('popover')}-enter-from.#{m('popover', 'top')},
+.#{b('popover')}-leave-to.#{m('popover', 'top')} {
+  transform: translateY(v('space-1', 4px));
+}
+
+.#{b('popover')}-enter-from.#{m('popover', 'bottom')},
+.#{b('popover')}-leave-to.#{m('popover', 'bottom')} {
+  transform: translateY(calc(-1 * #{v('space-1', 4px)}));
+}
+
+.#{b('popover')}-enter-from.#{m('popover', 'left')},
+.#{b('popover')}-leave-to.#{m('popover', 'left')} {
+  transform: translateX(v('space-1', 4px));
+}
+
+.#{b('popover')}-enter-from.#{m('popover', 'right')},
+.#{b('popover')}-leave-to.#{m('popover', 'right')} {
+  transform: translateX(calc(-1 * #{v('space-1', 4px)}));
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .#{b('popover')}-enter-active,
+  .#{b('popover')}-leave-active {
+    transition-duration: 0ms;
+  }
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/popover/index.ts b/code/g3soft-libs/packages/ui/src/popover/index.ts
new file mode 100644
index 00000000..da18f3e7
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/popover/index.ts
@@ -0,0 +1,2 @@
+export { default as G3Popover } from './Popover.vue'
+export type { PopoverProps, PopoverTrigger } from './types'
diff --git a/code/g3soft-libs/packages/ui/src/popover/types.ts b/code/g3soft-libs/packages/ui/src/popover/types.ts
new file mode 100644
index 00000000..b8b9055e
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/popover/types.ts
@@ -0,0 +1,34 @@
+import type { PopupContainer } from '../_utils/global-config'
+import type { Placement } from '../_utils/position'
+
+/** 触发方式 */
+export type PopoverTrigger = 'click' | 'hover' | 'focus' | 'contextmenu' | 'manual'
+
+export interface PopoverProps {
+  /** 受控打开状态；不传则非受控，由 defaultOpen + 内部状态控制 */
+  open?: boolean
+  /** 非受控时的初始打开状态 */
+  defaultOpen?: boolean
+  /** 触发方式 */
+  trigger?: PopoverTrigger
+  /** 期望方位 */
+  placement?: Placement
+  /** 与触发器的间距（px） */
+  offset?: number
+  /** 是否显示箭头 */
+  arrow?: boolean
+  /** 禁用态 */
+  disabled?: boolean
+  /** hover 触发打开延迟（ms） */
+  mouseEnterDelay?: number
+  /** hover 触发关闭延迟（ms） */
+  mouseLeaveDelay?: number
+  /** 透传到浮层内容盒子的额外 class，便于派生组件定制内容样式 */
+  contentClass?: string
+  /** 浮层宽度是否以触发器宽度为下限（Select / DatePicker 等需要对齐触发框） */
+  followTriggerWidth?: boolean
+  /** 零包裹模式：把事件直接注入触发器单根 vnode，不再包一层 span */
+  unwrapped?: boolean
+  /** 弹层挂载容器；不传时取 ConfigProvider.popupContainer，再退回 body */
+  popupContainer?: PopupContainer
+}
diff --git a/code/g3soft-libs/packages/ui/src/radio/Radio.vue b/code/g3soft-libs/packages/ui/src/radio/Radio.vue
new file mode 100644
index 00000000..9d961ff2
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/radio/Radio.vue
@@ -0,0 +1,135 @@
+<script setup lang="ts">
+import { computed, inject } from 'vue'
+import { useNamespace } from '../_composables/useNamespace'
+import { radioGroupKey } from './context'
+import type { RadioProps } from './types'
+
+/**
+ * 单选框 —— 必须与 G3RadioGroup 配合使用才能互斥选中。
+ *
+ * 组上下文由 RadioGroup 下发的 provide 提供；脱离组单独使用时降级为未选中的原生 radio。
+ */
+defineOptions({ name: 'G3Radio' })
+
+const props = withDefaults(defineProps<RadioProps>(), {
+  disabled: false,
+})
+
+const { b, e, is } = useNamespace('radio')
+
+/** 组内使用 RadioGroup 下发的上下文；独立使用时降级为未选中、未分组的原生 radio */
+const group = inject(radioGroupKey, null)
+
+const name = computed(() => group?.name.value)
+const isDisabled = computed(() => Boolean(group?.disabled.value) || props.disabled)
+const isChecked = computed(() => (group ? group.modelValue.value === props.value : false))
+
+const classes = computed(() => [
+  b(),
+  {
+    [is('checked')]: isChecked.value,
+    [is('disabled')]: isDisabled.value,
+  },
+])
+
+function onChange() {
+  group?.select(props.value)
+}
+</script>
+
+<template>
+  <label :class="classes">
+    <input
+      :class="e('input')"
+      type="radio"
+      :name="name"
+      :checked="isChecked"
+      :disabled="isDisabled"
+      :value="value"
+      @change="onChange"
+    />
+    <span :class="e('box')" aria-hidden="true"></span>
+    <span v-if="$slots.default" :class="e('label')">
+      <slot />
+    </span>
+  </label>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+.#{b('radio')} {
+  display: inline-flex;
+  align-items: center;
+  gap: v('space-2', 8px);
+  color: v('text-1', rgba(0, 0, 0, 0.88));
+  font-size: v('font-size', 14px);
+  line-height: v('line-height', 1.5);
+  cursor: pointer;
+  user-select: none;
+}
+
+.#{e('radio', 'input')} {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: 0;
+  opacity: 0;
+  pointer-events: none;
+}
+
+.#{e('radio', 'box')} {
+  position: relative;
+  box-sizing: border-box;
+  flex-shrink: 0;
+  width: v('radio-size', 16px);
+  height: v('radio-size', 16px);
+  border: 1px solid v('border-color', #d9d9d9);
+  border-radius: 50%;
+  background: v('bg-container', #fff);
+  transition:
+    border-color v('duration', 0.2s) v('ease', ease),
+    background-color v('duration', 0.2s) v('ease', ease);
+}
+
+/* 选中：外圈主色描边 + 内圈实心点 */
+.#{e('radio', 'box')}::after {
+  content: '';
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  background: v('text-inverse', #fff);
+  transform: translate(-50%, -50%) scale(0);
+  transition: transform v('duration-fast', 0.1s) v('ease', ease);
+}
+
+.#{b('radio')}:hover:not(.#{is('disabled')}) .#{e('radio', 'box')} {
+  border-color: v('color-primary', #18181b);
+}
+
+.#{b('radio')}.#{is('checked')} .#{e('radio', 'box')} {
+  border-color: v('color-primary', #18181b);
+  background: v('color-primary', #18181b);
+}
+
+.#{b('radio')}.#{is('checked')} .#{e('radio', 'box')}::after {
+  transform: translate(-50%, -50%) scale(1);
+}
+
+.#{e('radio', 'input')}:focus-visible + .#{e('radio', 'box')} {
+  @include focus-ring();
+}
+
+.#{b('radio')}.#{is('disabled')} {
+  color: v('text-disabled', rgba(0, 0, 0, 0.25));
+  cursor: not-allowed;
+}
+
+.#{b('radio')}.#{is('disabled')} .#{e('radio', 'box')} {
+  border-color: v('border-color', #d9d9d9);
+  background: v('bg-disabled', rgba(0, 0, 0, 0.04));
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/radio/RadioGroup.vue b/code/g3soft-libs/packages/ui/src/radio/RadioGroup.vue
new file mode 100644
index 00000000..6640a823
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/radio/RadioGroup.vue
@@ -0,0 +1,61 @@
+<script setup lang="ts">
+import { computed, provide, useId } from 'vue'
+import { useNamespace } from '../_composables/useNamespace'
+import { radioGroupKey, type RadioValue } from './context'
+import type { RadioGroupProps } from './types'
+
+/**
+ * 单选框组 —— 统一管理同组 G3Radio 的选中值与禁用态。
+ *
+ * 未显式传 name 时自动生成唯一组名，让同组 radio 原生互斥并支持方向键导航。
+ */
+defineOptions({ name: 'G3RadioGroup' })
+
+const props = withDefaults(defineProps<RadioGroupProps>(), {
+  modelValue: undefined,
+  disabled: false,
+  name: undefined,
+})
+
+const emit = defineEmits<{
+  'update:modelValue': [value: RadioValue]
+  change: [value: RadioValue]
+}>()
+
+const { b } = useNamespace('radio-group')
+
+const groupId = useId()
+const groupName = computed(() => props.name || groupId)
+const groupModelValue = computed(() => props.modelValue)
+const groupDisabled = computed(() => props.disabled)
+
+function select(value: RadioValue) {
+  if (props.disabled) return
+  if (!Object.is(value, props.modelValue)) emit('update:modelValue', value)
+  emit('change', value)
+}
+
+provide(radioGroupKey, {
+  name: groupName,
+  modelValue: groupModelValue,
+  disabled: groupDisabled,
+  select,
+})
+</script>
+
+<template>
+  <div :class="b()">
+    <slot />
+  </div>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+.#{b('radio-group')} {
+  display: inline-flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: v('space-4', 16px);
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/radio/context.ts b/code/g3soft-libs/packages/ui/src/radio/context.ts
new file mode 100644
index 00000000..fa83bd70
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/radio/context.ts
@@ -0,0 +1,18 @@
+import type { ComputedRef, InjectionKey } from 'vue'
+
+/** 单选项的值 */
+export type RadioValue = string | number | boolean
+
+/** RadioGroup 通过 provide 下发的组上下文 */
+export interface RadioGroupContext {
+  /** 组的原生 name（同组互斥 + 方向键导航） */
+  name: ComputedRef<string | undefined>
+  /** 当前选中值 */
+  modelValue: ComputedRef<RadioValue | undefined>
+  /** 整组是否禁用 */
+  disabled: ComputedRef<boolean>
+  /** 选中某项 */
+  select: (value: RadioValue) => void
+}
+
+export const radioGroupKey: InjectionKey<RadioGroupContext> = Symbol('g3-radio-group')
diff --git a/code/g3soft-libs/packages/ui/src/radio/index.ts b/code/g3soft-libs/packages/ui/src/radio/index.ts
new file mode 100644
index 00000000..c26f1fe7
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/radio/index.ts
@@ -0,0 +1,5 @@
+export { default as G3Radio } from './Radio.vue'
+export { default as G3RadioGroup } from './RadioGroup.vue'
+export type { RadioGroupContext, RadioValue } from './context'
+export { radioGroupKey } from './context'
+export type { RadioGroupProps, RadioProps } from './types'
diff --git a/code/g3soft-libs/packages/ui/src/radio/types.ts b/code/g3soft-libs/packages/ui/src/radio/types.ts
new file mode 100644
index 00000000..f26063ed
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/radio/types.ts
@@ -0,0 +1,17 @@
+import type { RadioValue } from './context'
+
+export interface RadioProps {
+  /** 选项值，与 RadioGroup 的 modelValue 比较确定是否选中 */
+  value: RadioValue
+  /** 禁用态 */
+  disabled?: boolean
+}
+
+export interface RadioGroupProps {
+  /** 双向绑定的选中值 */
+  modelValue?: RadioValue
+  /** 禁用整组 */
+  disabled?: boolean
+  /** 组名，未设置时自动生成，避免多组之间互斥冲突 */
+  name?: string
+}
diff --git a/code/g3soft-libs/packages/ui/src/scrollbar/Scrollbar.vue b/code/g3soft-libs/packages/ui/src/scrollbar/Scrollbar.vue
new file mode 100644
index 00000000..b2766028
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/scrollbar/Scrollbar.vue
@@ -0,0 +1,329 @@
+<script setup lang="ts">
+/**
+ * Scrollbar 通用滚动容器（零依赖实现）。
+ *
+ * - 隐藏原生滚动条，自绘悬浮滑块（不占布局高度）
+ * - 内容溢出时自动出现，支持横向 / 纵向 / 双向滚动
+ * - 滑块可拖动，点击轨道可跳转
+ * - 用法：`<G3Scrollbar style="height: 240px">内容</G3Scrollbar>`
+ */
+import { computed, onBeforeUnmount, onMounted, reactive, ref, watch } from 'vue'
+import { useNamespace } from '../_composables/useNamespace'
+import type { ScrollbarProps } from './types'
+
+defineOptions({ name: 'G3Scrollbar' })
+
+const props = withDefaults(defineProps<ScrollbarProps>(), {
+  visibility: 'auto',
+  autoHide: 'leave',
+  clickScroll: true,
+  ariaLabel: undefined,
+})
+
+const { b, e, m } = useNamespace('scrollbar')
+
+const viewRef = ref<HTMLElement | null>(null)
+
+interface ThumbState {
+  /** 滑块长度（px） */
+  size: number
+  /** 滑块偏移（px） */
+  offset: number
+  /** 该轴是否需要滚动 */
+  overflow: boolean
+}
+
+const vertical = reactive<ThumbState>({ size: 0, offset: 0, overflow: false })
+const horizontal = reactive<ThumbState>({ size: 0, offset: 0, overflow: false })
+
+/** 滑块整体可见性（autoHide 的三种模式都收敛到这一个开关） */
+const active = ref(false)
+let hideTimer: ReturnType<typeof setTimeout> | null = null
+
+const hasOverflow = computed(() => vertical.overflow || horizontal.overflow)
+const thumbVisible = computed(() => {
+  if (props.visibility === 'hidden' || !hasOverflow.value) return false
+  if (props.visibility === 'visible') return true
+  return active.value || props.autoHide === 'never'
+})
+
+function clearHideTimer() {
+  if (hideTimer) {
+    clearTimeout(hideTimer)
+    hideTimer = null
+  }
+}
+
+function show() {
+  clearHideTimer()
+  active.value = true
+}
+
+/** 延迟隐藏：scroll / move 两种模式在事件停止后收起 */
+function scheduleHide() {
+  clearHideTimer()
+  if (props.autoHide === 'leave' || props.autoHide === 'never') return
+  hideTimer = setTimeout(() => {
+    active.value = false
+  }, 1000)
+}
+
+/** 重新测量内容尺寸与滚动位置（内容 / 尺寸变化后调用） */
+function update() {
+  const el = viewRef.value
+  if (!el) return
+  const { clientWidth, clientHeight, scrollWidth, scrollHeight, scrollLeft, scrollTop } = el
+
+  vertical.overflow = scrollHeight - clientHeight > 1
+  vertical.size = vertical.overflow ? Math.max((clientHeight / scrollHeight) * clientHeight, 20) : 0
+  const vRange = clientHeight - vertical.size
+  vertical.offset =
+    vertical.overflow && vRange > 0
+      ? (scrollTop / (scrollHeight - clientHeight)) * vRange
+      : 0
+
+  horizontal.overflow = scrollWidth - clientWidth > 1
+  horizontal.size = horizontal.overflow ? Math.max((clientWidth / scrollWidth) * clientWidth, 20) : 0
+  const hRange = clientWidth - horizontal.size
+  horizontal.offset =
+    horizontal.overflow && hRange > 0
+      ? (scrollLeft / (scrollWidth - clientWidth)) * hRange
+      : 0
+}
+
+function onScroll() {
+  update()
+  if (props.visibility !== 'auto') return
+  if (props.autoHide === 'scroll' || props.autoHide === 'move') {
+    show()
+    scheduleHide()
+  } else if (props.autoHide === 'leave') {
+    // leave 模式由鼠标进出控制显隐，滚动不额外干预
+  }
+}
+
+function onMouseEnter() {
+  if (props.visibility !== 'auto') return
+  if (props.autoHide === 'leave' || props.autoHide === 'move') show()
+}
+
+function onMouseMove() {
+  if (props.visibility !== 'auto' || props.autoHide !== 'move') return
+  show()
+  scheduleHide()
+}
+
+function onMouseLeave() {
+  if (props.visibility !== 'auto') return
+  if (props.autoHide === 'leave') active.value = false
+  else scheduleHide()
+}
+
+/** 拖动滑块：按位移比例换算滚动距离 */
+function onThumbPointerDown(axis: 'v' | 'h', event: PointerEvent) {
+  const el = viewRef.value
+  const thumbEl = event.currentTarget as HTMLElement | null
+  if (!el || !thumbEl) return
+  event.preventDefault()
+  thumbEl.setPointerCapture(event.pointerId)
+
+  const isVertical = axis === 'v'
+  const startPointer = isVertical ? event.clientY : event.clientX
+  const startScroll = isVertical ? el.scrollTop : el.scrollLeft
+  const containerSize = isVertical ? el.clientHeight : el.clientWidth
+  const contentSize = isVertical ? el.scrollHeight : el.scrollWidth
+  const thumbSize = isVertical ? vertical.size : horizontal.size
+  const travel = containerSize - thumbSize
+  const movable = contentSize - containerSize
+
+  const onMove = (moveEvent: PointerEvent) => {
+    const delta = (isVertical ? moveEvent.clientY : moveEvent.clientX) - startPointer
+    const next = travel > 0 ? startScroll + (delta / travel) * movable : startScroll
+    if (isVertical) el.scrollTop = next
+    else el.scrollLeft = next
+  }
+
+  const onUp = () => {
+    thumbEl.removeEventListener('pointermove', onMove)
+    thumbEl.removeEventListener('pointerup', onUp)
+    thumbEl.removeEventListener('pointercancel', onUp)
+  }
+
+  thumbEl.addEventListener('pointermove', onMove)
+  thumbEl.addEventListener('pointerup', onUp)
+  thumbEl.addEventListener('pointercancel', onUp)
+}
+
+/** 点击轨道：滑块中心跳到点击位置 */
+function onTrackPointerDown(axis: 'v' | 'h', event: PointerEvent) {
+  if (!props.clickScroll) return
+  const el = viewRef.value
+  const trackEl = event.currentTarget as HTMLElement | null
+  if (!el || !trackEl || event.target !== trackEl) return
+  const isVertical = axis === 'v'
+  const rect = trackEl.getBoundingClientRect()
+  const thumbSize = isVertical ? vertical.size : horizontal.size
+  const containerSize = isVertical ? el.clientHeight : el.clientWidth
+  const contentSize = isVertical ? el.scrollHeight : el.scrollWidth
+  const point = isVertical ? event.clientY - rect.top : event.clientX - rect.left
+  const travel = containerSize - thumbSize
+  const ratio = travel > 0 ? (point - thumbSize / 2) / travel : 0
+  const next = Math.min(Math.max(ratio, 0), 1) * (contentSize - containerSize)
+  if (isVertical) el.scrollTop = next
+  else el.scrollLeft = next
+}
+
+let resizeObserver: ResizeObserver | null = null
+
+onMounted(() => {
+  update()
+  if (typeof ResizeObserver !== 'undefined' && viewRef.value) {
+    resizeObserver = new ResizeObserver(() => update())
+    resizeObserver.observe(viewRef.value)
+  }
+})
+
+onBeforeUnmount(() => {
+  clearHideTimer()
+  resizeObserver?.disconnect()
+  resizeObserver = null
+})
+
+// 显隐策略变化时立即同步一次
+watch(
+  () => [props.visibility, props.autoHide],
+  () => {
+    if (props.visibility === 'visible' || props.autoHide === 'never') active.value = true
+    else if (props.visibility === 'hidden') active.value = false
+  },
+  { immediate: true },
+)
+
+defineExpose({
+  /** 重新测量（内容 / 尺寸变化后调用） */
+  update,
+  /** 滚动到指定位置 */
+  scrollTo: (options: ScrollToOptions) => viewRef.value?.scrollTo(options),
+  /** 内部滚动元素 */
+  getElement: () => viewRef.value,
+})
+</script>
+
+<template>
+  <div
+    :class="[b(), { [m('hidden')]: !thumbVisible }]"
+    @mouseenter="onMouseEnter"
+    @mousemove="onMouseMove"
+    @mouseleave="onMouseLeave"
+  >
+    <div
+      ref="viewRef"
+      :class="e('view')"
+      :aria-label="ariaLabel || undefined"
+      tabindex="0"
+      @scroll="onScroll"
+    >
+      <slot />
+    </div>
+
+    <!-- 纵向滑块 -->
+    <div
+      v-show="vertical.overflow"
+      :class="[e('track'), e('track-v')]"
+      aria-hidden="true"
+      @pointerdown="onTrackPointerDown('v', $event)"
+    >
+      <div
+        :class="[e('thumb'), e('thumb-v')]"
+        :style="{ height: `${vertical.size}px`, transform: `translateY(${vertical.offset}px)` }"
+        @pointerdown="onThumbPointerDown('v', $event)"
+      />
+    </div>
+
+    <!-- 横向滑块 -->
+    <div
+      v-show="horizontal.overflow"
+      :class="[e('track'), e('track-h')]"
+      aria-hidden="true"
+      @pointerdown="onTrackPointerDown('h', $event)"
+    >
+      <div
+        :class="[e('thumb'), e('thumb-h')]"
+        :style="{ width: `${horizontal.size}px`, transform: `translateX(${horizontal.offset}px)` }"
+        @pointerdown="onThumbPointerDown('h', $event)"
+      />
+    </div>
+  </div>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+.#{b('scrollbar')} {
+  position: relative;
+  overflow: hidden;
+  width: 100%;
+  height: 100%;
+}
+
+.#{e('scrollbar', 'view')} {
+  width: 100%;
+  height: 100%;
+  overflow: auto;
+  /* 隐藏原生滚动条：Firefox + WebKit */
+  scrollbar-width: none;
+  outline: none;
+
+  &::-webkit-scrollbar {
+    display: none;
+  }
+}
+
+.#{e('scrollbar', 'track')} {
+  position: absolute;
+  z-index: 2;
+  opacity: 1;
+  transition: opacity v('duration-fast', 0.1s) v('ease', ease);
+}
+
+.#{b('scrollbar')}.#{m('scrollbar', 'hidden')} .#{e('scrollbar', 'track')} {
+  opacity: 0;
+  pointer-events: none;
+}
+
+.#{e('scrollbar', 'track-v')} {
+  top: 0;
+  right: 0;
+  width: v('scrollbar-size', 8px);
+  height: 100%;
+}
+
+.#{e('scrollbar', 'track-h')} {
+  bottom: 0;
+  left: 0;
+  width: 100%;
+  height: v('scrollbar-size', 8px);
+}
+
+.#{e('scrollbar', 'thumb')} {
+  position: absolute;
+  border-radius: 999px;
+  background: v('scrollbar-thumb', rgba(0, 0, 0, 0.25));
+
+  &:hover {
+    background: v('scrollbar-thumb-hover', rgba(0, 0, 0, 0.4));
+  }
+}
+
+.#{e('scrollbar', 'thumb-v')} {
+  top: 0;
+  right: 0;
+  width: 100%;
+}
+
+.#{e('scrollbar', 'thumb-h')} {
+  bottom: 0;
+  left: 0;
+  height: 100%;
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/scrollbar/index.ts b/code/g3soft-libs/packages/ui/src/scrollbar/index.ts
new file mode 100644
index 00000000..a818297a
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/scrollbar/index.ts
@@ -0,0 +1,2 @@
+export { default as G3Scrollbar } from './Scrollbar.vue'
+export type { ScrollbarAutoHide, ScrollbarProps, ScrollbarVisibility } from './types'
diff --git a/code/g3soft-libs/packages/ui/src/scrollbar/types.ts b/code/g3soft-libs/packages/ui/src/scrollbar/types.ts
new file mode 100644
index 00000000..e4c3cf99
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/scrollbar/types.ts
@@ -0,0 +1,16 @@
+/** 滚动条显示策略：visible 常显 / auto 按 autoHide 规则显隐 / hidden 隐藏 */
+export type ScrollbarVisibility = 'visible' | 'auto' | 'hidden'
+
+/** 自动隐藏策略：never 永不 / scroll 滚动时显示 / move 鼠标移动或滚动时显示 / leave 鼠标移出后隐藏 */
+export type ScrollbarAutoHide = 'never' | 'scroll' | 'move' | 'leave'
+
+export interface ScrollbarProps {
+  /** 滚动条显示策略 */
+  visibility?: ScrollbarVisibility
+  /** 自动隐藏策略 */
+  autoHide?: ScrollbarAutoHide
+  /** 点击轨道时是否把滑块跳过去（false 时轨道只作视觉提示） */
+  clickScroll?: boolean
+  /** 无障碍标签 */
+  ariaLabel?: string
+}
diff --git a/code/g3soft-libs/packages/ui/src/segmented/Segmented.vue b/code/g3soft-libs/packages/ui/src/segmented/Segmented.vue
new file mode 100644
index 00000000..17fc3bf9
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/segmented/Segmented.vue
@@ -0,0 +1,330 @@
+<script setup lang="ts">
+import {
+  computed,
+  isVNode,
+  nextTick,
+  onBeforeUnmount,
+  onMounted,
+  ref,
+  toRaw,
+  useId,
+  watch,
+  type CSSProperties,
+  type VNode,
+} from 'vue'
+import { useNamespace } from '../_composables/useNamespace'
+import type { SegmentedOptionInput, SegmentedProps, SegmentedValue } from './types'
+
+/**
+ * 分段控制器 —— 一组互斥选项中切换，滑块跟随选中项移动。
+ *
+ * 支持受控（v-model）与非受控用法；选项可以是原始值，也可以是 { label, value, disabled, icon }。
+ */
+defineOptions({ name: 'G3Segmented' })
+
+const props = withDefaults(defineProps<SegmentedProps>(), {
+  modelValue: undefined,
+  options: () => [],
+  shape: 'default',
+  vertical: false,
+  block: false,
+  disabled: false,
+  name: undefined,
+})
+
+const emit = defineEmits<{
+  'update:modelValue': [value: SegmentedValue]
+  change: [value: SegmentedValue]
+}>()
+
+const { b, e, m, is } = useNamespace('segmented')
+
+/** 选项归一：兼容原始值与对象两种形态，保留 index 与 raw 供插槽使用 */
+const mergedOptions = computed(() =>
+  (props.options || []).map((option, index) => {
+    const isObject = option !== null && typeof option === 'object'
+    const value = isObject ? (option as { value: SegmentedValue }).value : (option as SegmentedValue)
+    // 对象形态只在显式给了 label 时显示文字（纯图标项留空），原始值形态以自身为文本
+    const rawLabel = isObject ? (option as { label?: string }).label : option
+    return {
+      value,
+      label: rawLabel == null ? '' : String(rawLabel),
+      disabled: isObject ? Boolean((option as { disabled?: boolean }).disabled) : false,
+      // options 常由 ref 提供（深层响应式），toRaw 还原组件本身，避免「组件被响应式化」告警
+      icon:
+        isObject && (option as { icon?: unknown }).icon
+          ? (toRaw((option as { icon?: unknown }).icon) as VNode | undefined)
+          : undefined,
+      index,
+      raw: option,
+    }
+  }),
+)
+
+/* ---------- 选中值 ---------- */
+const innerValue = ref<SegmentedValue | undefined>(undefined)
+const currentValue = computed(() =>
+  props.modelValue !== undefined ? props.modelValue : innerValue.value,
+)
+
+// useId 依赖实例上下文，必须在 setup 同步阶段取，不能延迟到 computed 求值
+const autoName = useId()
+const groupName = computed(() => props.name || autoName)
+
+function isSelected(option: { value: SegmentedValue }): boolean {
+  return Object.is(option.value, currentValue.value)
+}
+
+function onChange(option: { value: SegmentedValue; disabled: boolean }) {
+  if (props.disabled || option.disabled) return
+  if (props.modelValue !== undefined) emit('update:modelValue', option.value)
+  else innerValue.value = option.value
+  emit('change', option.value)
+}
+
+/* ---------- 滑块测量 ---------- */
+const groupEl = ref<HTMLElement | null>(null)
+const thumbStyle = ref<CSSProperties>({})
+const thumbVisible = ref(false)
+/** 首次定位完成前不启用过渡：否则滑块会从左上角滑到选中项，位置读到的也是中间值 */
+const thumbReady = ref(false)
+let observer: ResizeObserver | null = null
+
+/** 读取选中项在组内的偏移与尺寸，写入滑块的内联样式 */
+function measureThumb() {
+  const group = groupEl.value
+  if (!group) return
+  const activeEl = group.querySelector<HTMLElement>(`.${is('selected')}`)
+  if (!activeEl) {
+    thumbVisible.value = false
+    return
+  }
+  // 两个方向都要带上 offsetTop：thumb 的 left / top 原点与 offsetParent 一致，
+  // 而 offsetLeft / offsetTop 已经含了 group 的 padding，只写横轴会整体上移 padding 的距离
+  const offset = `translate(${activeEl.offsetLeft}px, ${activeEl.offsetTop}px)`
+  // 宽高都用实测值：`height: 100%` 是相对 padding box，会把轨道的 padding 也算进去，
+  // 滑块比选项高出 2 × padding
+  thumbStyle.value = {
+    transform: offset,
+    width: `${activeEl.offsetWidth}px`,
+    height: `${activeEl.offsetHeight}px`,
+  }
+  thumbVisible.value = true
+}
+
+onMounted(() => {
+  nextTick(() => {
+    measureThumb()
+    // 下一帧才启用过渡：首次定位必须瞬时到位
+    requestAnimationFrame(() => {
+      thumbReady.value = true
+    })
+  })
+  // 容器尺寸变化（block 拉伸、字体加载、选项文字变化）时重新定位滑块
+  if (typeof ResizeObserver !== 'undefined' && groupEl.value) {
+    observer = new ResizeObserver(() => measureThumb())
+    observer.observe(groupEl.value)
+  }
+})
+
+onBeforeUnmount(() => {
+  observer?.disconnect()
+  observer = null
+})
+
+// 选中项、选项集或排列方向变化时重新测量；v-for 更新在 nextTick 后才落到 DOM
+watch([currentValue, () => props.options, () => props.vertical], () => nextTick(measureThumb))
+
+const classes = computed(() => [
+  b(),
+  m(`shape-${props.shape}`),
+  {
+    [m('block')]: props.block,
+    [m('vertical')]: props.vertical,
+    [is('disabled')]: props.disabled,
+  },
+])
+
+/** 渲染函数组件：把 VNode 形态的图标原样渲染 */
+const VNodeRenderer = (renderProps: { node: VNode }) => renderProps.node
+</script>
+
+<template>
+  <div
+    :class="classes"
+    role="radiogroup"
+    :aria-disabled="disabled || undefined"
+    :aria-orientation="vertical ? 'vertical' : 'horizontal'"
+  >
+    <div ref="groupEl" :class="e('group')">
+      <!-- 滑块：先于选项渲染，作为选中态底座托在下方 -->
+      <div
+        :class="[
+          e('thumb'),
+          { [is('thumb-visible')]: thumbVisible, [is('thumb-ready')]: thumbReady },
+        ]"
+        :style="thumbStyle"
+        aria-hidden="true"
+      />
+      <label
+        v-for="option in mergedOptions"
+        :key="option.index"
+        :class="[e('item'), { [is('selected')]: isSelected(option), [is('item-disabled')]: disabled || option.disabled }]"
+      >
+        <input
+          :class="e('input')"
+          type="radio"
+          :name="groupName"
+          :value="String(option.value)"
+          :checked="isSelected(option)"
+          :disabled="disabled || option.disabled"
+          @change="onChange(option)"
+        />
+        <span :class="e('label')">
+          <slot
+            name="label"
+            :option="option.raw"
+            :index="option.index"
+            :checked="isSelected(option)"
+          >
+            <template v-if="option.icon">
+              <component :is="option.icon" v-if="!isVNode(option.icon)" :class="e('icon')" aria-hidden="true" />
+              <VNodeRenderer v-else :node="option.icon as VNode" />
+            </template>
+            <span v-if="option.label !== ''" :class="e('text')">{{ option.label }}</span>
+          </slot>
+        </span>
+      </label>
+    </div>
+  </div>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+.#{b('segmented')} {
+  display: inline-block;
+  max-width: 100%;
+}
+
+.#{e('segmented', 'group')} {
+  position: relative;
+  display: inline-flex;
+  align-items: stretch;
+  padding: v('segmented-padding', 2px);
+  border-radius: v('radius', 6px);
+  background: v('fill', rgba(0, 0, 0, 0.04));
+}
+
+.#{m('segmented', 'block')} {
+  display: block;
+
+  .#{e('segmented', 'group')} {
+    display: flex;
+    width: 100%;
+  }
+
+  .#{e('segmented', 'item')} {
+    flex: 1 1 0;
+    justify-content: center;
+  }
+}
+
+.#{m('segmented', 'vertical')} {
+  .#{e('segmented', 'group')} {
+    flex-direction: column;
+  }
+}
+
+.#{m('segmented', 'shape-round')} {
+  .#{e('segmented', 'group')},
+  .#{e('segmented', 'thumb')} {
+    border-radius: 999px;
+  }
+}
+
+.#{e('segmented', 'thumb')} {
+  position: absolute;
+  /* 从 0 起算：thumb 的包含块是 group 的 padding box，而 item 的 offsetLeft /
+     offsetTop 已经含了 group 的 padding，再加一次会让滑块整体偏右下 */
+  top: 0;
+  left: 0;
+  z-index: 0;
+  box-sizing: border-box;
+  /* 两个方向都先撑满：横向由 JS 覆盖 width、纵向由 JS 覆盖 height，
+     剩下那条轴必须在这里给满，否则滑块会塌成 0（选中态就看不见了） */
+  width: 100%;
+  height: 100%;
+  border-radius: v('radius-sm', 4px);
+  background: v('bg-container', #fff);
+  box-shadow: v('shadow', 0 2px 8px rgba(0, 0, 0, 0.15));
+  opacity: 0;
+}
+
+/* 过渡只在首次定位完成后才生效（见 thumbReady）：
+   宽高不参与过渡 —— 参与的话首次测量会从 100% 收缩出一次可见抖动（与 fms 一致） */
+.#{e('segmented', 'thumb')}.#{is('thumb-ready')} {
+  transition:
+    transform v('duration', 0.2s) v('ease', ease),
+    opacity v('duration-fast', 0.1s) v('ease', ease);
+}
+
+.#{e('segmented', 'thumb')}.#{is('thumb-visible')} {
+  opacity: 1;
+}
+
+.#{e('segmented', 'item')} {
+  position: relative;
+  z-index: 1;
+  display: inline-flex;
+  align-items: center;
+  gap: v('space-1', 4px);
+  min-height: v('segmented-item-height', 28px);
+  padding: 0 v('space-3', 12px);
+  border-radius: v('radius-sm', 4px);
+  color: v('text-2', rgba(0, 0, 0, 0.65));
+  font-size: v('font-size', 14px);
+  line-height: v('line-height', 1.5);
+  white-space: nowrap;
+  cursor: pointer;
+  transition: color v('duration', 0.2s) v('ease', ease);
+}
+
+.#{e('segmented', 'item')}:hover:not(.#{is('item-disabled')}) {
+  color: v('text-1', rgba(0, 0, 0, 0.88));
+}
+
+.#{e('segmented', 'item')}.#{is('selected')} {
+  color: v('text-1', rgba(0, 0, 0, 0.88));
+  font-weight: 500;
+}
+
+.#{e('segmented', 'item')}.#{is('item-disabled')} {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.#{e('segmented', 'input')} {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: 0;
+  opacity: 0;
+  pointer-events: none;
+}
+
+.#{e('segmented', 'label')} {
+  display: inline-flex;
+  align-items: center;
+  gap: v('space-1', 4px);
+}
+
+.#{e('segmented', 'icon')} {
+  width: 1em;
+  height: 1em;
+}
+
+.#{b('segmented')}.#{is('disabled')} {
+  opacity: 0.6;
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/segmented/index.ts b/code/g3soft-libs/packages/ui/src/segmented/index.ts
new file mode 100644
index 00000000..63bb8f27
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/segmented/index.ts
@@ -0,0 +1,8 @@
+export { default as G3Segmented } from './Segmented.vue'
+export type {
+  SegmentedOption,
+  SegmentedOptionInput,
+  SegmentedProps,
+  SegmentedShape,
+  SegmentedValue,
+} from './types'
diff --git a/code/g3soft-libs/packages/ui/src/segmented/types.ts b/code/g3soft-libs/packages/ui/src/segmented/types.ts
new file mode 100644
index 00000000..109c8ffa
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/segmented/types.ts
@@ -0,0 +1,39 @@
+import type { Component, VNode } from 'vue'
+
+/** 分段项的值 */
+export type SegmentedValue = string | number | boolean
+
+/** 分段项（对象形态） */
+export interface SegmentedOption {
+  /** 显示文字；不传即为纯图标项 */
+  label?: string
+  /** 选项值 */
+  value: SegmentedValue
+  /** 是否禁用该项 */
+  disabled?: boolean
+  /** 图标：组件或 VNode */
+  icon?: Component | VNode
+}
+
+/** 分段项：原始值或对象 */
+export type SegmentedOptionInput = SegmentedValue | SegmentedOption
+
+/** 圆角形状 */
+export type SegmentedShape = 'default' | 'round'
+
+export interface SegmentedProps {
+  /** 双向绑定的选中值 */
+  modelValue?: SegmentedValue
+  /** 选项数据源，与 #label 插槽配合使用 */
+  options?: SegmentedOptionInput[]
+  /** 圆角形状：default 跟随控件圆角，round 全圆角 */
+  shape?: SegmentedShape
+  /** 纵向排列，滑块上下移动 */
+  vertical?: boolean
+  /** 撑满父容器宽度（纵向时为高度），各项等分空间 */
+  block?: boolean
+  /** 禁用整组 */
+  disabled?: boolean
+  /** 原生 radio 组名，未设置时自动生成，避免多组之间互斥冲突 */
+  name?: string
+}
diff --git a/code/g3soft-libs/packages/ui/src/select/Select.vue b/code/g3soft-libs/packages/ui/src/select/Select.vue
new file mode 100644
index 00000000..2cfa7fa1
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/select/Select.vue
@@ -0,0 +1,788 @@
+<script setup lang="ts">
+import { computed, nextTick, ref, useId, watch } from 'vue'
+import { Check, ChevronDown, LoaderCircle, X } from '@lucide/vue'
+import { useLocale } from '../_composables/useLocale'
+import { useNamespace } from '../_composables/useNamespace'
+import G3Popover from '../popover/Popover.vue'
+import type { SelectProps, SelectValue } from './types'
+
+/**
+ * 选择器 —— 从下拉列表中选择一项或多项，支持筛选、远程搜索、自由输入与清除。
+ *
+ * 触发器本身就是一个输入框：`filterable` 时可直接键入筛选，键盘 ↑↓ / Home / End / Enter / Esc 全可用。
+ */
+defineOptions({ name: 'G3Select' })
+
+const props = withDefaults(defineProps<SelectProps>(), {
+  modelValue: undefined,
+  options: undefined,
+  disabled: false,
+  clearable: false,
+  multiple: false,
+  filterable: true,
+  filterOption: undefined,
+  remote: false,
+  loading: false,
+  notFoundText: undefined,
+  allowFreeInput: false,
+  labelKey: 'label',
+  valueKey: 'value',
+})
+
+const emit = defineEmits<{
+  'update:modelValue': [value: SelectValue | SelectValue[]]
+  change: [value: SelectValue | SelectValue[], option?: unknown]
+  search: [query: string]
+  visibleChange: [open: boolean]
+  loadMore: []
+}>()
+
+const { b, e, m, is } = useNamespace('select')
+const locale = useLocale()
+
+interface NormalizedOption {
+  label: string
+  value: SelectValue
+  selected: boolean
+  disabled: boolean
+  index: number
+  raw: unknown
+}
+
+const selectTriggerRef = ref<HTMLElement | null>(null)
+const triggerInputRef = ref<HTMLInputElement | null>(null)
+const dropdownEl = ref<HTMLElement | null>(null)
+const selectListEl = ref<HTMLElement | null>(null)
+
+const open = ref(false)
+const activeIndex = ref(-1)
+const filterQuery = ref('')
+const triggerFocused = ref(false)
+const editing = ref(false)
+const selectedCache = ref<{ value: SelectValue; label: string } | null>(null)
+// 选中 / 清除后焦点会随下拉内容卸载丢到 body，主动交还输入框会触发 focus 事件，
+// 但此时不应重新展开（「聚焦即展开」仅面向用户主动聚焦），用标记抑制这一次
+const suppressNextAutoOpen = ref(false)
+
+const selectId = useId()
+const listboxId = `${selectId}-listbox`
+
+const notFound = computed(() => props.notFoundText ?? locale.value.common.noMatch)
+
+function isOptionSelected(value: SelectValue): boolean {
+  return props.multiple
+    ? Array.isArray(props.modelValue) && props.modelValue.some((entry) => Object.is(entry, value))
+    : Object.is(value, props.modelValue)
+}
+
+/** 规范化选项：兼容字符串与对象两种形态，保留原始索引供键盘高亮定位 */
+const normalizedOptions = computed<NormalizedOption[]>(() =>
+  (props.options ?? []).map((option, index) => {
+    if (option !== null && typeof option === 'object') {
+      const raw = option as Record<string, unknown>
+      const rawValue = raw[props.valueKey] as SelectValue
+      const rawLabel = raw[props.labelKey] ?? rawValue
+      return {
+        label: rawLabel == null ? '' : String(rawLabel),
+        value: rawValue,
+        selected: isOptionSelected(rawValue),
+        disabled: Boolean(raw.disabled),
+        index,
+        raw: option,
+      }
+    }
+    const value = option as SelectValue
+    return {
+      label: String(option),
+      value,
+      selected: isOptionSelected(value),
+      disabled: false,
+      index,
+      raw: option,
+    }
+  }),
+)
+
+const normalizedFilterQuery = computed(() => String(filterQuery.value || '').trim().toLowerCase())
+
+/** 默认筛选：对 label 或 value 做大小写不敏感的包含匹配 */
+function defaultFilter(query: string, option: NormalizedOption): boolean {
+  if (!query) return true
+  return (
+    String(option.label).toLowerCase().includes(query) ||
+    String(option.value).toLowerCase().includes(query)
+  )
+}
+
+/** 筛选后的可见选项；未开启筛选或远程模式时返回全部 */
+const visibleOptions = computed(() =>
+  !props.filterable || props.remote
+    ? normalizedOptions.value
+    : normalizedOptions.value.filter((option) =>
+        props.filterOption
+          ? props.filterOption(filterQuery.value, option.raw)
+          : defaultFilter(normalizedFilterQuery.value, option),
+      ),
+)
+
+/** 可交互选项的原始索引列表（跳过 disabled），键盘导航只在这些索引间移动 */
+const enabledIndices = computed(() =>
+  visibleOptions.value.reduce<number[]>((acc, option) => {
+    if (!option.disabled) acc.push(option.index)
+    return acc
+  }, []),
+)
+
+const hasValue = computed(() =>
+  props.multiple
+    ? Array.isArray(props.modelValue) && props.modelValue.length > 0
+    : props.modelValue !== undefined && props.modelValue !== null && props.modelValue !== '',
+)
+
+const selectedOption = computed(() => normalizedOptions.value.find((option) => option.selected))
+const selectedOptions = computed(() => normalizedOptions.value.filter((option) => option.selected))
+
+const selectedDisplayLabel = computed(() => {
+  if (props.multiple) return selectedOptions.value.map((option) => option.label).join('、')
+  if (selectedOption.value) return selectedOption.value.label
+  if (selectedCache.value && Object.is(selectedCache.value.value, props.modelValue)) {
+    return selectedCache.value.label
+  }
+  return String(props.modelValue)
+})
+
+/** 初次展开时继续回显当前值，避免聚焦导致内容被清空；只有用户实际输入后才展示筛选词 */
+const inputDisplay = computed(() => {
+  if (open.value && editing.value) return filterQuery.value
+  return hasValue.value ? selectedDisplayLabel.value : ''
+})
+
+const activeDescendant = computed(() =>
+  open.value && activeIndex.value >= 0 ? `${listboxId}-option-${activeIndex.value}` : undefined,
+)
+
+const hasInputContent = computed(() =>
+  open.value && editing.value ? filterQuery.value.length > 0 : hasValue.value,
+)
+
+const showClear = computed(
+  () => props.clearable && !props.disabled && hasInputContent.value && triggerFocused.value,
+)
+
+watch(
+  [() => props.modelValue, selectedOption],
+  ([value, option]) => {
+    if (!hasValue.value) {
+      selectedCache.value = null
+    } else if (option) {
+      selectedCache.value = { value: option.value, label: option.label }
+    } else if (!selectedCache.value || !Object.is(selectedCache.value.value, value)) {
+      selectedCache.value = null
+    }
+  },
+  { immediate: true },
+)
+
+/* ---------- 打开 / 关闭 ---------- */
+function onOpenChange(value: boolean) {
+  open.value = value
+}
+
+watch(open, (value) => {
+  emit('visibleChange', value)
+  if (value) {
+    // 展开即清空筛选词：重新打开都加载全部选项（而非沿用上次筛选）
+    filterQuery.value = ''
+    nextTick(() => {
+      activeIndex.value =
+        enabledIndices.value.find((index) => normalizedOptions.value[index].selected) ?? -1
+      // 输入框承接键入与键盘事件；无输入框场景（默认插槽）时聚焦下拉容器兜底
+      if (props.filterable) triggerInputRef.value?.focus()
+      else dropdownEl.value?.focus()
+      scrollActiveIntoView()
+    })
+  } else {
+    activeIndex.value = -1
+    commitFreeInputOrRevert()
+    editing.value = false
+  }
+})
+
+// 筛选词变化时：列表随之过滤，高亮重置到首个可见可选项
+watch(filterQuery, () => {
+  if (!open.value) return
+  activeIndex.value = enabledIndices.value[0] ?? -1
+  nextTick(resetListScroll)
+})
+
+// 远程结果或外部选项替换后重新定位第一项，避免旧索引指向错误或禁用选项
+watch(normalizedOptions, () => {
+  if (!open.value) return
+  activeIndex.value = enabledIndices.value[0] ?? -1
+  nextTick(resetListScroll)
+})
+
+/* ---------- 触发器交互 ---------- */
+function openDropdown() {
+  if (props.disabled) return
+  if (!open.value) open.value = true
+}
+
+/** 程序化归还焦点（选中 / 清除 / 取消后）：抑制本次聚焦触发的自动展开 */
+function refocusTrigger() {
+  suppressNextAutoOpen.value = true
+  triggerInputRef.value?.focus({ preventScroll: true })
+  nextTick(() => {
+    suppressNextAutoOpen.value = false
+  })
+}
+
+function onTriggerFocus() {
+  if (suppressNextAutoOpen.value) {
+    suppressNextAutoOpen.value = false
+    return
+  }
+  openDropdown()
+}
+
+function onTriggerFocusIn() {
+  triggerFocused.value = true
+}
+
+function focusRemainsInsideSelect(target: EventTarget | null): boolean {
+  const node = target as Node | null
+  return Boolean(
+    node && (selectTriggerRef.value?.contains(node) || dropdownEl.value?.contains(node)),
+  )
+}
+
+function onSelectFocusOut(event: FocusEvent) {
+  if (focusRemainsInsideSelect(event.relatedTarget)) return
+  triggerFocused.value = false
+  if (props.allowFreeInput && editing.value) {
+    commitFreeInputOrRevert()
+    editing.value = false
+  }
+  open.value = false
+}
+
+/** 非交互选项按下时保留输入框焦点，避免 focusout 在 click 选中前卸载下拉内容 */
+function onDropdownPointerDown(event: PointerEvent) {
+  const target = event.target as HTMLElement | null
+  const interactiveSelector =
+    'a[href], button, input, textarea, select, [tabindex]:not([tabindex="-1"])'
+  if (target?.closest?.(interactiveSelector)) return
+  event.preventDefault()
+}
+
+function onTriggerClick() {
+  triggerInputRef.value?.focus()
+  openDropdown()
+}
+
+function onInput(event: Event) {
+  if (props.disabled) return
+  editing.value = true
+  filterQuery.value = (event.target as HTMLInputElement).value
+  if (props.remote) emit('search', filterQuery.value)
+  if (!open.value) open.value = true
+}
+
+/**
+ * 关闭下拉时的收尾：
+ * - 自由输入：仅在实际编辑后提交原始文本；
+ * - 非自由输入：文本精确匹配某选项 label 则选中该项，否则回退到上次选中值。
+ */
+function commitFreeInputOrRevert() {
+  if (props.multiple) {
+    filterQuery.value = ''
+    return
+  }
+  if (props.allowFreeInput) {
+    if (editing.value && !Object.is(filterQuery.value, props.modelValue)) {
+      emit('update:modelValue', filterQuery.value)
+      emit('change', filterQuery.value, undefined)
+    }
+    filterQuery.value = ''
+    return
+  }
+  const text = filterQuery.value.trim()
+  if (!text) {
+    filterQuery.value = hasValue.value ? selectedOption.value?.label ?? '' : ''
+    return
+  }
+  const matched = normalizedOptions.value.find(
+    (option) => !option.disabled && option.label === text,
+  )
+  if (matched) {
+    emit('update:modelValue', matched.value)
+    emit('change', matched.value, matched)
+    filterQuery.value = ''
+  } else if (hasValue.value) {
+    filterQuery.value = selectedOption.value?.label ?? ''
+  } else {
+    filterQuery.value = ''
+  }
+}
+
+/* ---------- 选中 / 清除 ---------- */
+function selectOption(option: NormalizedOption) {
+  if (props.disabled || option.disabled) return
+  editing.value = false
+  if (props.multiple) {
+    const current = Array.isArray(props.modelValue) ? [...props.modelValue] : []
+    const index = current.findIndex((value) => Object.is(value, option.value))
+    if (index >= 0) current.splice(index, 1)
+    else current.push(option.value)
+    emit('update:modelValue', current)
+    emit('change', current, option)
+    refocusTrigger()
+    return
+  }
+  selectedCache.value = { value: option.value, label: option.label }
+  emit('update:modelValue', option.value)
+  emit('change', option.value, option)
+  open.value = false
+  refocusTrigger()
+}
+
+/** 供默认插槽使用：按原始值选中并关闭 */
+function selectValue(value: SelectValue) {
+  if (props.disabled) return
+  editing.value = false
+  if (props.multiple) {
+    const current = Array.isArray(props.modelValue) ? [...props.modelValue] : []
+    const index = current.findIndex((entry) => Object.is(entry, value))
+    if (index >= 0) current.splice(index, 1)
+    else current.push(value)
+    emit('update:modelValue', current)
+    emit('change', current, undefined)
+    return
+  }
+  emit('update:modelValue', value)
+  emit('change', value, undefined)
+  open.value = false
+  refocusTrigger()
+}
+
+function closeDropdown() {
+  open.value = false
+}
+
+function clearValue() {
+  editing.value = false
+  filterQuery.value = ''
+  activeIndex.value = -1
+  selectedCache.value = null
+  refocusTrigger()
+  const emptyValue: SelectValue | SelectValue[] = props.multiple ? [] : undefined
+  emit('update:modelValue', emptyValue)
+  emit('change', emptyValue, undefined)
+}
+
+/* ---------- 键盘导航 ---------- */
+function moveActive(direction: 1 | -1) {
+  const indices = enabledIndices.value
+  if (indices.length === 0) {
+    activeIndex.value = -1
+    return
+  }
+  const pos = indices.indexOf(activeIndex.value)
+  const nextPos =
+    pos === -1
+      ? direction === 1
+        ? 0
+        : indices.length - 1
+      : (pos + direction + indices.length) % indices.length
+  activeIndex.value = indices[nextPos]
+  nextTick(scrollActiveIntoView)
+}
+
+function scrollActiveIntoView() {
+  dropdownEl.value?.querySelector(`.${is('option-active')}`)?.scrollIntoView({ block: 'nearest' })
+}
+
+function resetListScroll() {
+  if (selectListEl.value) selectListEl.value.scrollTop = 0
+}
+
+/** 列表滚动触底：对外 emit loadMore，供远程分页调用方加载下一页 */
+const LOAD_MORE_THRESHOLD = 24
+function onListScroll(event: Event) {
+  if (props.loading) return
+  const el = event.target as HTMLElement | null
+  if (!el) return
+  if (el.scrollTop + el.clientHeight >= el.scrollHeight - LOAD_MORE_THRESHOLD) emit('loadMore')
+}
+
+function cancelEditing() {
+  editing.value = false
+  filterQuery.value = ''
+  open.value = false
+  refocusTrigger()
+}
+
+function onTriggerKeydown(event: KeyboardEvent) {
+  // 尚未展开时，方向键 / Home / End / Enter 先展开下拉
+  if (!open.value && ['ArrowDown', 'ArrowUp', 'Home', 'End', 'Enter'].includes(event.key)) {
+    event.preventDefault()
+    open.value = true
+    return
+  }
+  switch (event.key) {
+    case 'ArrowDown':
+      event.preventDefault()
+      moveActive(1)
+      break
+    case 'ArrowUp':
+      event.preventDefault()
+      moveActive(-1)
+      break
+    case 'Home':
+      event.preventDefault()
+      activeIndex.value = enabledIndices.value[0] ?? -1
+      nextTick(scrollActiveIntoView)
+      break
+    case 'End':
+      event.preventDefault()
+      activeIndex.value = enabledIndices.value[enabledIndices.value.length - 1] ?? -1
+      nextTick(scrollActiveIntoView)
+      break
+    case 'Enter': {
+      event.preventDefault()
+      if (!props.allowFreeInput) {
+        const exact = normalizedOptions.value.find(
+          (option) => !option.disabled && option.label === filterQuery.value.trim(),
+        )
+        if (exact) {
+          selectOption(exact)
+          break
+        }
+      }
+      const option = normalizedOptions.value[activeIndex.value]
+      if (option && !option.disabled) selectOption(option)
+      break
+    }
+    case 'Escape':
+      if (!open.value) break
+      event.preventDefault()
+      event.stopPropagation()
+      cancelEditing()
+      break
+  }
+}
+
+defineExpose({
+  /** 展开下拉 */
+  openDropdown,
+  /** 收起下拉 */
+  closeDropdown,
+})
+</script>
+
+<template>
+  <div :class="[b(), { [is('disabled')]: disabled }]">
+    <G3Popover
+      :open="open"
+      trigger="manual"
+      placement="bottom-start"
+      :arrow="false"
+      :offset="4"
+      :disabled="disabled"
+      :follow-trigger-width="true"
+      :content-class="e('popover-content')"
+      unwrapped
+      @update:open="onOpenChange"
+    >
+      <!-- 触发器：类输入框的框体，直接在此键入即可筛选；含清除按钮与折叠箭头 -->
+      <template #trigger>
+        <span
+          ref="selectTriggerRef"
+          :class="[
+            e('trigger'),
+            {
+              [is('trigger-open')]: open,
+              [is('trigger-focused')]: triggerFocused,
+            },
+          ]"
+          @click="onTriggerClick"
+          @focusin="onTriggerFocusIn"
+          @focusout="onSelectFocusOut"
+        >
+          <input
+            ref="triggerInputRef"
+            :class="e('input')"
+            type="text"
+            :disabled="disabled"
+            :readonly="!filterable && !allowFreeInput"
+            :value="inputDisplay"
+            autocomplete="off"
+            spellcheck="false"
+            role="combobox"
+            aria-haspopup="listbox"
+            :aria-autocomplete="filterable || allowFreeInput ? 'list' : 'none'"
+            :aria-expanded="open"
+            :aria-controls="listboxId"
+            :aria-activedescendant="activeDescendant"
+            :aria-busy="loading || undefined"
+            @input="onInput"
+            @focus="onTriggerFocus"
+            @keydown="onTriggerKeydown"
+          />
+          <LoaderCircle
+            v-if="loading"
+            :class="e('loading')"
+            role="status"
+            :aria-label="locale.common.loading"
+          />
+          <button
+            v-else-if="showClear"
+            :class="e('clear')"
+            type="button"
+            :aria-label="locale.common.clear"
+            @pointerdown.prevent
+            @click.stop="clearValue"
+          >
+            <X />
+          </button>
+          <ChevronDown
+            v-else
+            :class="[e('arrow'), { [is('arrow-open')]: open }]"
+            aria-hidden="true"
+          />
+        </span>
+      </template>
+
+      <!-- 下拉列表：tabindex 承接键盘事件；浮层宽度 = max(触发框宽, 选项内容宽) -->
+      <template #content>
+        <div
+          ref="dropdownEl"
+          :id="listboxId"
+          :class="e('dropdown')"
+          role="listbox"
+          :aria-multiselectable="multiple || undefined"
+          tabindex="-1"
+          @focusout="onSelectFocusOut"
+          @pointerdown="onDropdownPointerDown"
+          @keydown="onTriggerKeydown"
+        >
+          <template v-if="options != null">
+            <div ref="selectListEl" :class="e('list')" @scroll.passive="onListScroll">
+              <div
+                v-for="option in visibleOptions"
+                :key="String(option.value)"
+                :id="`${listboxId}-option-${option.index}`"
+                :class="[
+                  e('option'),
+                  {
+                    [is('option-active')]: activeIndex === option.index,
+                    [is('option-selected')]: option.selected,
+                    [is('option-disabled')]: option.disabled,
+                  },
+                ]"
+                role="option"
+                :aria-selected="option.selected"
+                :aria-disabled="option.disabled || undefined"
+                @mouseenter="!option.disabled && (activeIndex = option.index)"
+                @pointerdown.prevent
+                @click="selectOption(option)"
+              >
+                <span :class="e('option-label')">{{ option.label }}</span>
+                <Check v-if="option.selected" :class="e('option-check')" aria-hidden="true" />
+              </div>
+              <div v-if="visibleOptions.length === 0" :class="e('empty')">{{ notFound }}</div>
+            </div>
+            <!-- footer 插槽：远程分页的加载指示器等附加内容 -->
+            <slot name="footer" :loading="loading" />
+          </template>
+          <!-- 默认插槽：自定义选项逃生舱，透出 select / close 便于调用方控制关闭 -->
+          <slot v-else :select="selectValue" :close="closeDropdown" />
+        </div>
+      </template>
+    </G3Popover>
+  </div>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+.#{b('select')} {
+  position: relative;
+  display: inline-block;
+  width: 100%;
+}
+
+.#{e('select', 'trigger')} {
+  display: inline-flex;
+  align-items: center;
+  gap: v('space-1', 4px);
+  box-sizing: border-box;
+  width: 100%;
+  min-height: v('control-height', 32px);
+  padding: 0 v('space-2', 8px);
+  border: 1px solid v('border-color', #d9d9d9);
+  border-radius: v('radius', 6px);
+  background: v('bg-container', #fff);
+  color: v('text-1', rgba(0, 0, 0, 0.88));
+  font-size: v('font-size', 14px);
+  line-height: v('line-height', 1.5);
+  cursor: pointer;
+  transition:
+    border-color v('duration', 0.2s) v('ease', ease),
+    box-shadow v('duration', 0.2s) v('ease', ease);
+}
+
+.#{e('select', 'trigger')}:hover {
+  border-color: v('color-primary', #18181b);
+}
+
+.#{b('select')}.#{is('trigger-focused')} .#{e('select', 'trigger')},
+.#{b('select')}.#{is('trigger-open')} .#{e('select', 'trigger')} {
+  border-color: v('color-primary', #18181b);
+  box-shadow: 0 0 0 2px v('color-primary-ring', rgba(24, 24, 27, 0.2));
+}
+
+.#{b('select')}.#{is('disabled')} .#{e('select', 'trigger')} {
+  background: v('bg-disabled', rgba(0, 0, 0, 0.04));
+  color: v('text-disabled', rgba(0, 0, 0, 0.25));
+  cursor: not-allowed;
+}
+
+.#{e('select', 'input')} {
+  flex: 1;
+  min-width: 0;
+  padding: 0;
+  border: 0;
+  outline: none;
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  text-overflow: ellipsis;
+  cursor: inherit;
+
+  &::placeholder {
+    color: v('text-3', rgba(0, 0, 0, 0.45));
+  }
+}
+
+.#{e('select', 'arrow')} {
+  flex-shrink: 0;
+  width: 14px;
+  height: 14px;
+  color: v('text-3', rgba(0, 0, 0, 0.45));
+  transition: transform v('duration', 0.2s) v('ease', ease);
+}
+
+.#{e('select', 'arrow')}.#{is('arrow-open')} {
+  transform: rotate(180deg);
+}
+
+.#{e('select', 'loading')} {
+  flex-shrink: 0;
+  width: 14px;
+  height: 14px;
+  color: v('text-3', rgba(0, 0, 0, 0.45));
+  animation: #{b('select')}-spin 0.8s linear infinite;
+}
+
+@keyframes #{b('select')}-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+.#{e('select', 'clear')} {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  width: 16px;
+  height: 16px;
+  padding: 0;
+  border: 0;
+  border-radius: 50%;
+  background: transparent;
+  color: v('text-3', rgba(0, 0, 0, 0.45));
+  cursor: pointer;
+
+  svg {
+    width: 12px;
+    height: 12px;
+  }
+
+  &:hover {
+    color: v('text-1', rgba(0, 0, 0, 0.88));
+  }
+
+  &:focus-visible {
+    @include focus-ring();
+  }
+}
+
+/* ---------- 下拉 ---------- */
+.#{e('select', 'dropdown')} {
+  display: flex;
+  flex-direction: column;
+  box-sizing: border-box;
+  max-height: v('select-dropdown-max-height', 256px);
+  outline: none;
+}
+
+.#{e('select', 'list')} {
+  max-height: v('select-dropdown-max-height', 256px);
+  overflow: auto;
+  padding: v('space-1', 4px);
+}
+
+.#{e('select', 'option')} {
+  display: flex;
+  align-items: center;
+  gap: v('space-2', 8px);
+  padding: v('dropdown-item-padding-y', 5px) v('dropdown-item-padding-x', 8px);
+  border-radius: v('dropdown-item-radius', 4px);
+  color: v('text-1', rgba(0, 0, 0, 0.88));
+  font-size: v('font-size', 14px);
+  line-height: v('line-height', 1.5);
+  cursor: pointer;
+}
+
+.#{e('select', 'option')}.#{is('option-active')} {
+  background: v('fill', rgba(0, 0, 0, 0.04));
+}
+
+.#{e('select', 'option')}.#{is('option-selected')} {
+  color: v('color-primary', #18181b);
+  font-weight: 500;
+}
+
+.#{e('select', 'option')}.#{is('option-disabled')} {
+  color: v('text-disabled', rgba(0, 0, 0, 0.25));
+  cursor: not-allowed;
+}
+
+.#{e('select', 'option-label')} {
+  flex: 1;
+  min-width: 0;
+  overflow-wrap: anywhere;
+}
+
+.#{e('select', 'option-check')} {
+  flex-shrink: 0;
+  width: 14px;
+  height: 14px;
+}
+
+.#{e('select', 'empty')} {
+  padding: v('space-2', 8px);
+  color: v('text-3', rgba(0, 0, 0, 0.45));
+  font-size: v('font-size-sm', 12px);
+  text-align: center;
+}
+
+/* 宽度上限必须落在浮层（popup）而不是内容盒：浮层宽度 = max(触发框宽, 选项内容宽)，
+   压在内容盒上会让触发框更宽时下拉填不满浮层、与输入框错位。
+   超出上限的选项文案由 __option-label 折行消化，不拉出跨屏下拉。 */
+.#{e('popover', 'popup')}:has(> .#{e('select', 'popover-content')}) {
+  max-width: v('select-dropdown-max-width', 360px);
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/select/index.ts b/code/g3soft-libs/packages/ui/src/select/index.ts
new file mode 100644
index 00000000..dcd5acd1
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/select/index.ts
@@ -0,0 +1,2 @@
+export { default as G3Select } from './Select.vue'
+export type { SelectProps, SelectValue } from './types'
diff --git a/code/g3soft-libs/packages/ui/src/select/types.ts b/code/g3soft-libs/packages/ui/src/select/types.ts
new file mode 100644
index 00000000..5fdb04a3
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/select/types.ts
@@ -0,0 +1,31 @@
+/** 选择器的值：单选为单值，多选为数组 */
+export type SelectValue = string | number | boolean | object | null | undefined
+
+export interface SelectProps {
+  /** 双向绑定的选中值；多选时为数组 */
+  modelValue?: SelectValue | SelectValue[]
+  /** 选项数组；每项默认取 { label, value, disabled }，可用 labelKey / valueKey 自定义字段名 */
+  options?: Array<Record<string, unknown> | string | number>
+  /** 禁用态 */
+  disabled?: boolean
+  /** 有值时展示清除按钮 */
+  clearable?: boolean
+  /** 多选模式：modelValue 为数组，选中后下拉保持打开 */
+  multiple?: boolean
+  /** 是否开启筛选（默认开启；开启后直接在触发器输入框输入即可筛选） */
+  filterable?: boolean
+  /** 自定义筛选函数：(input, option) => boolean；不传则用默认的 label / value 包含匹配 */
+  filterOption?: (input: string, option: unknown) => boolean
+  /** 远程搜索模式：输入时触发 search 事件，选项由父层更新，不再执行本地筛选 */
+  remote?: boolean
+  /** 远程数据加载状态；开启时右侧仅展示加载图标 */
+  loading?: boolean
+  /** 无匹配项时的文案；不传则取语言包 */
+  notFoundText?: string
+  /** 是否允许自由输入：true 时可输入任意文本并作为值 */
+  allowFreeInput?: boolean
+  /** 选项对象中作为显示文本的字段名 */
+  labelKey?: string
+  /** 选项对象中作为值的字段名 */
+  valueKey?: string
+}
diff --git a/code/g3soft-libs/packages/ui/src/space/Space.vue b/code/g3soft-libs/packages/ui/src/space/Space.vue
new file mode 100644
index 00000000..1c481fb2
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/space/Space.vue
@@ -0,0 +1,151 @@
+<script setup lang="ts">
+import { Comment, Fragment, Text, computed, useSlots, type VNode } from 'vue'
+import { useNamespace } from '../_composables/useNamespace'
+import type { SpaceProps, SpaceSize } from './types'
+
+/**
+ * Space 间距 —— 为并排的子元素设置统一间距，避免它们紧贴在一起。
+ *
+ * 与 Grid 的分工：Space 面向「一行内联元素的等距排列」（按钮组、标签行、操作区），
+ * 会给每个子元素包一层包装以支持分隔符与空节点隐藏；整块页面布局请用 Grid。
+ */
+defineOptions({ name: 'G3Space' })
+
+const props = withDefaults(defineProps<SpaceProps>(), {
+  size: 'small',
+  orientation: undefined,
+  vertical: false,
+  align: undefined,
+  wrap: false,
+})
+
+const slots = useSlots()
+const { b, e, m } = useNamespace('space')
+
+/** 预设间距（px）：small / middle / large 三档 */
+const PRESET_GAP: Record<string, number> = { small: 8, middle: 16, large: 24 }
+
+/** 把单个 size 值解析为 CSS 长度：预设名查表；纯数字补 px；其余（如 '12px'）原样透传 */
+function toGap(value: SpaceSize | undefined): string {
+  if (value == null) return `${PRESET_GAP.small}px`
+  if (typeof value === 'number') return `${value}px`
+  const text = String(value).trim()
+  if (text in PRESET_GAP) return `${PRESET_GAP[text]}px`
+  return /^\d+(\.\d+)?$/.test(text) ? `${text}px` : text
+}
+
+const mergedOrientation = computed(() =>
+  props.orientation ? props.orientation : props.vertical ? 'vertical' : 'horizontal',
+)
+
+const mergedAlign = computed(() => {
+  if (props.align) return props.align
+  return mergedOrientation.value === 'horizontal' ? 'center' : undefined
+})
+
+const classes = computed(() => [
+  b(),
+  m(mergedOrientation.value),
+  mergedAlign.value ? m(`align-${mergedAlign.value}`) : '',
+  props.wrap && mergedOrientation.value === 'horizontal' ? m('wrap') : '',
+])
+
+/** size 归一：数组按 [水平, 垂直] 分别设 column-gap / row-gap；单值同时作用于两轴 */
+const gapStyle = computed(() => {
+  const [horizontal, vertical] = Array.isArray(props.size)
+    ? props.size
+    : [props.size, props.size]
+  return { columnGap: toGap(horizontal), rowGap: toGap(vertical) }
+})
+
+/** 归一化插槽 vnode：展开 Fragment、过滤注释与纯空白文本，得到真正的子元素列表 */
+function normalizeChildren(nodes: VNode[] | undefined): VNode[] {
+  const result: VNode[] = []
+  for (const node of nodes ?? []) {
+    if (node == null || typeof node === 'boolean') continue
+    if (Array.isArray(node)) {
+      result.push(...normalizeChildren(node as unknown as VNode[]))
+      continue
+    }
+    if (node.type === Comment) continue
+    if (node.type === Fragment) {
+      result.push(...normalizeChildren(node.children as VNode[]))
+      continue
+    }
+    // 模板换行 / 缩进会产生纯空白文本节点，忽略；非空文本仍作为子元素保留
+    if (node.type === Text && typeof node.children === 'string' && !node.children.trim()) continue
+    result.push(node)
+  }
+  return result
+}
+
+const children = computed(() => normalizeChildren(slots.default?.() as VNode[] | undefined))
+const separators = computed(() => normalizeChildren(slots.separator?.() as VNode[] | undefined))
+const hasSeparator = computed(() => separators.value.length > 0)
+
+/** 渲染函数组件：把已归一化的 vnode 原样渲染（模板里 <component :is="vnode"> 不可靠） */
+const VNodeRenderer = (renderProps: { node: VNode }) => renderProps.node
+</script>
+
+<template>
+  <!-- 无有效子元素时不渲染容器，避免留下一个空 gap 的盒子 -->
+  <div v-if="children.length" :class="classes" :style="gapStyle" data-slot="space">
+    <template v-for="(child, index) in children" :key="index">
+      <div :class="e('item')"><VNodeRenderer :node="child" /></div>
+      <span v-if="hasSeparator && index < children.length - 1" :class="e('separator')">
+        <VNodeRenderer v-for="(sep, sepIndex) in separators" :key="sepIndex" :node="sep" />
+      </span>
+    </template>
+  </div>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+/* 内联弹性容器：具体间距值由组件按 size 内联注入 row-gap / column-gap，
+   方向 / 对齐 / 换行由容器修饰类控制，两者解耦。 */
+.#{b('space')} {
+  display: inline-flex;
+  gap: v('space-2', 8px);
+}
+
+.#{m('space', 'horizontal')} {
+  flex-direction: row;
+}
+
+.#{m('space', 'vertical')} {
+  flex-direction: column;
+}
+
+.#{m('space', 'align-start')} {
+  align-items: flex-start;
+}
+
+.#{m('space', 'align-center')} {
+  align-items: center;
+}
+
+.#{m('space', 'align-end')} {
+  align-items: flex-end;
+}
+
+.#{m('space', 'align-baseline')} {
+  align-items: baseline;
+}
+
+.#{m('space', 'wrap')} {
+  flex-wrap: wrap;
+}
+
+/* 空子项不占位：条件渲染留下的空包装直接隐藏，避免多出一段 gap */
+.#{e('space', 'item')}:empty {
+  display: none;
+}
+
+/* 分隔符：与文字基线居中，颜色退到次级，不与主内容抢视觉 */
+.#{e('space', 'separator')} {
+  display: inline-flex;
+  align-items: center;
+  color: v('text-3', rgba(0, 0, 0, 0.45));
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/space/index.ts b/code/g3soft-libs/packages/ui/src/space/index.ts
new file mode 100644
index 00000000..44b8c299
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/space/index.ts
@@ -0,0 +1,2 @@
+export { default as G3Space } from './Space.vue'
+export type { SpaceAlign, SpaceOrientation, SpaceProps, SpaceSize } from './types'
diff --git a/code/g3soft-libs/packages/ui/src/space/types.ts b/code/g3soft-libs/packages/ui/src/space/types.ts
new file mode 100644
index 00000000..fd1245ae
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/space/types.ts
@@ -0,0 +1,21 @@
+/** 间距预设档位 */
+export type SpaceSize = 'small' | 'middle' | 'large' | number | string
+
+/** 间距方向 */
+export type SpaceOrientation = 'horizontal' | 'vertical'
+
+/** 交叉轴对齐 */
+export type SpaceAlign = 'start' | 'end' | 'center' | 'baseline'
+
+export interface SpaceProps {
+  /** 间距：预设名 small / middle / large、数字（px）、[水平, 垂直] */
+  size?: SpaceSize | [SpaceSize, SpaceSize]
+  /** 排列方向；不传时由 vertical 决定 */
+  orientation?: SpaceOrientation
+  /** 垂直排列简写；与 orientation 同时配置时以 orientation 优先 */
+  vertical?: boolean
+  /** 交叉轴对齐：水平默认 center，垂直默认不设置（stretch） */
+  align?: SpaceAlign
+  /** 是否自动换行，仅水平方向生效 */
+  wrap?: boolean
+}
diff --git a/code/g3soft-libs/packages/ui/src/spin/Spin.vue b/code/g3soft-libs/packages/ui/src/spin/Spin.vue
new file mode 100644
index 00000000..fde8febd
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/spin/Spin.vue
@@ -0,0 +1,165 @@
+<script setup lang="ts">
+import { computed, onBeforeUnmount, ref, useSlots, watch } from 'vue'
+import { Loader } from '@lucide/vue'
+import { useLocale } from '../_composables/useLocale'
+import { useNamespace } from '../_composables/useNamespace'
+import type { SpinProps } from './types'
+
+/**
+ * 加载中 —— 两种形态：
+ * - 无默认插槽：独立指示器（inline-flex），可带文案；
+ * - 有默认插槽：包裹内容并叠加半透明遮罩，容器仅 position: relative，不改变内容布局。
+ */
+defineOptions({ name: 'G3Spin' })
+
+const props = withDefaults(defineProps<SpinProps>(), {
+  spinning: true,
+  delay: 0,
+  description: '',
+})
+
+const slots = useSlots()
+const { b, e, m, is } = useNamespace('spin')
+const locale = useLocale()
+
+/** 实际显示状态：spinning 为 true 且 delay > 0 时，delay 毫秒后才置 true */
+const active = ref(false)
+let timer: ReturnType<typeof setTimeout> | null = null
+
+function syncActive() {
+  if (timer) {
+    clearTimeout(timer)
+    timer = null
+  }
+  if (!props.spinning) {
+    active.value = false
+    return
+  }
+  if (props.delay > 0) {
+    timer = setTimeout(() => {
+      active.value = true
+    }, props.delay)
+  } else {
+    active.value = true
+  }
+}
+
+watch(() => [props.spinning, props.delay], syncActive, { immediate: true })
+
+onBeforeUnmount(() => {
+  if (timer) clearTimeout(timer)
+})
+
+/** 是否有默认插槽：有则「包裹内容 + 遮罩」，否则「独立指示器」 */
+const nested = computed(() => !!slots.default && slots.default().length > 0)
+const hasDescription = computed(() => !!props.description || !!slots.description)
+
+const classes = computed(() => [
+  b(),
+  {
+    [m('nested')]: nested.value,
+    [is('spinning')]: active.value,
+  },
+])
+</script>
+
+<template>
+  <div :class="classes" :aria-busy="active" aria-live="polite">
+    <!-- 形态二：内容容器，仅 position: relative，不改变内部元素位置 / 尺寸 -->
+    <div v-if="nested" :class="e('container')">
+      <slot />
+    </div>
+
+    <template v-if="active">
+      <!-- 形态一：指示器区直接落在根节点（inline-flex） -->
+      <template v-if="!nested">
+        <slot name="indicator">
+          <Loader :class="e('indicator')" aria-hidden="true" />
+        </slot>
+        <div
+          v-if="hasDescription"
+          :class="e('description')"
+          role="status"
+          :aria-label="locale.common.loading"
+        >
+          <slot name="description">{{ description }}</slot>
+        </div>
+      </template>
+      <!-- 形态二：绝对居中于遮罩之上 -->
+      <div v-else :class="e('section')" role="status" :aria-label="locale.common.loading">
+        <slot name="indicator">
+          <Loader :class="e('indicator')" aria-hidden="true" />
+        </slot>
+        <div v-if="hasDescription" :class="e('description')">
+          <slot name="description">{{ description }}</slot>
+        </div>
+      </div>
+    </template>
+  </div>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+.#{b('spin')} {
+  display: inline-flex;
+  flex-direction: column;
+  align-items: center;
+  gap: v('spin-description-gap', 8px);
+  color: v('color-primary', #18181b);
+}
+
+.#{m('spin', 'nested')} {
+  position: relative;
+  display: block;
+}
+
+.#{e('spin', 'container')} {
+  position: relative;
+}
+
+/* 包裹形态：内容上盖一层半透明遮罩，视觉上「进行中」 */
+.#{b('spin')}.#{m('spin', 'nested')}.#{is('spinning')}::after {
+  content: '';
+  position: absolute;
+  inset: 0;
+  z-index: 1;
+  background: color-mix(in srgb, #{v('bg-container', #fff)} 65%, transparent);
+}
+
+.#{e('spin', 'section')} {
+  position: absolute;
+  inset: 0;
+  z-index: 2;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: v('spin-description-gap', 8px);
+}
+
+.#{e('spin', 'indicator')} {
+  /* 块级：svg 默认行内会让容器多出行高间隙（20px 的图标把盒子撑到 24px） */
+  display: block;
+  width: v('spin-size', 20px);
+  height: v('spin-size', 20px);
+  animation: #{b('spin')}-rotate 0.8s linear infinite;
+}
+
+@keyframes #{b('spin')}-rotate {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+.#{e('spin', 'description')} {
+  color: v('text-2', rgba(0, 0, 0, 0.65));
+  font-size: v('font-size-sm', 12px);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .#{e('spin', 'indicator')} {
+    animation: none;
+  }
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/spin/index.ts b/code/g3soft-libs/packages/ui/src/spin/index.ts
new file mode 100644
index 00000000..dde038e7
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/spin/index.ts
@@ -0,0 +1,2 @@
+export { default as G3Spin } from './Spin.vue'
+export type { SpinProps } from './types'
diff --git a/code/g3soft-libs/packages/ui/src/spin/types.ts b/code/g3soft-libs/packages/ui/src/spin/types.ts
new file mode 100644
index 00000000..6c6d3bb1
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/spin/types.ts
@@ -0,0 +1,8 @@
+export interface SpinProps {
+  /** 是否加载中 */
+  spinning?: boolean
+  /** 延迟显示（毫秒），防短请求闪烁 */
+  delay?: number
+  /** 加载文案 */
+  description?: string
+}
diff --git a/code/g3soft-libs/packages/ui/src/splitter/Panel.vue b/code/g3soft-libs/packages/ui/src/splitter/Panel.vue
new file mode 100644
index 00000000..b66d3710
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/splitter/Panel.vue
@@ -0,0 +1,48 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import { useNamespace } from '../_composables/useNamespace'
+import type { SplitterPanelProps } from './types'
+
+/**
+ * 分割面板 —— 必须放在 G3Splitter 内使用，尺寸由 G3Splitter 注入。
+ *
+ * 无 size / defaultSize 时按 flex 自动分配剩余空间；拖拽会固定相邻两块的实际尺寸。
+ */
+defineOptions({ name: 'G3SplitterPanel' })
+
+const props = withDefaults(defineProps<SplitterPanelProps>(), {
+  min: undefined,
+  max: undefined,
+  size: undefined,
+  defaultSize: undefined,
+  resizable: true,
+})
+
+const { b } = useNamespace('splitter-panel')
+
+const style = computed((): Record<string, string> => {
+  const size = props.size
+  if (size === undefined || size === null || size === '') {
+    return { flexBasis: '0%', flexGrow: '1', flexShrink: '1' }
+  }
+  const basis = typeof size === 'number' ? `${size}px` : size
+  return { flexBasis: basis, flexGrow: '0', flexShrink: '0' }
+})
+</script>
+
+<template>
+  <div :class="b()" :style="style">
+    <slot />
+  </div>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+.#{b('splitter-panel')} {
+  position: relative;
+  min-width: 0;
+  min-height: 0;
+  overflow: auto;
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/splitter/Splitter.vue b/code/g3soft-libs/packages/ui/src/splitter/Splitter.vue
new file mode 100644
index 00000000..aa0710d5
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/splitter/Splitter.vue
@@ -0,0 +1,409 @@
+<script setup lang="ts">
+import { cloneVNode, computed, onBeforeUnmount, onMounted, ref, useSlots, type VNode } from 'vue'
+import { useNamespace } from '../_composables/useNamespace'
+import G3SplitterPanel from './Panel.vue'
+import type { SplitterPanelProps, SplitterProps, SplitterSize } from './types'
+
+/**
+ * 分割面板 —— 把内容区切成可拖拽调整大小的多块。
+ *
+ * 尺寸模型：面板显式给了 size / defaultSize 就固定住，否则交给 flex 自动分配；
+ * 拖拽只影响相邻两块，拖拽 / 键盘调整结束后自动重新分配剩余空间（窗口缩放不会填不满）。
+ */
+defineOptions({ name: 'G3Splitter' })
+
+const props = withDefaults(defineProps<SplitterProps>(), {
+  direction: 'horizontal',
+  barOnHover: true,
+})
+
+const emit = defineEmits<{
+  resizeStart: [sizes: number[]]
+  resize: [sizes: number[]]
+  resizeEnd: [sizes: number[]]
+}>()
+
+const slots = useSlots()
+const { b, e, m, is } = useNamespace('splitter')
+
+const rootRef = ref<HTMLElement | null>(null)
+const activeBar = ref(-1)
+const hoverBar = ref(-1)
+
+/** 面板内部接管后的尺寸（px）；undefined 表示交给 flex 自动分配 */
+const innerSizes = ref<Array<number | undefined>>([])
+
+function camelizeProps(raw: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(raw)) {
+    out[key.replace(/-([a-z])/g, (_, char: string) => char.toUpperCase())] = value
+  }
+  return out
+}
+
+function toPx(value: SplitterSize | undefined, container: number): number | undefined {
+  if (value === undefined || value === null || value === '') return undefined
+  if (typeof value === 'number') return value
+  const text = String(value).trim()
+  if (text.endsWith('%')) return (container * Number.parseFloat(text)) / 100
+  const parsed = Number.parseFloat(text)
+  return Number.isFinite(parsed) ? parsed : undefined
+}
+
+function measureContainer(): number {
+  const el = rootRef.value
+  if (!el) return 0
+  return props.direction === 'vertical' ? el.clientHeight : el.clientWidth
+}
+
+function measurePanelSizes(): number[] {
+  const el = rootRef.value
+  if (!el) return []
+  // DOM 顺序与 items 顺序一致（面板之间只插分隔条）
+  return Array.from(el.querySelectorAll<HTMLElement>(`.${b('splitter-panel')}`)).map((panel) =>
+    props.direction === 'vertical' ? panel.offsetHeight : panel.offsetWidth,
+  )
+}
+
+/**
+ * 收集面板 vnode，并把最终 size 注入到 G3SplitterPanel。
+ * 必须是渲染期调用的普通函数（不能 computed 缓存）：父组件更新会生成新 vnode，
+ * 缓存旧 vnode 会让 patch 拿到已失效的节点。
+ */
+function getPanelItems(): Array<{ node: VNode; props: SplitterPanelProps; isLast: boolean }> {
+  const nodes = (slots.default?.() ?? []) as VNode[]
+  const items: Array<{ node: VNode; props: SplitterPanelProps; isLast: boolean }> = []
+  nodes.forEach((node) => {
+    if (!node || node.type !== G3SplitterPanel) return
+    const normalized = camelizeProps((node.props ?? {}) as Record<string, unknown>)
+    const index = items.length
+    const displaySize = innerSizes.value[index] ?? normalized.size ?? normalized.defaultSize
+    items.push({
+      node: cloneVNode(node, { size: displaySize as SplitterSize | undefined }),
+      props: normalized as SplitterPanelProps,
+      isLast: false,
+    })
+  })
+  // 最后一块后面不渲染分隔条
+  if (items.length) items[items.length - 1].isLast = true
+  return items
+}
+
+/** 两侧面板都允许调整时才可拖 */
+function canResize(index: number, items: Array<{ props: SplitterPanelProps }>): boolean {
+  const prev = items[index]
+  const next = items[index + 1]
+  if (!prev || !next) return false
+  return prev.props.resizable !== false && next.props.resizable !== false
+}
+
+/** 拖拽 / 键盘结束后，无显式尺寸的面板恢复 flex 自动分配 */
+function releaseAutoPanels(items: Array<{ props: SplitterPanelProps }>) {
+  const next = [...innerSizes.value]
+  items.forEach((item, index) => {
+    if (item.props.size == null && item.props.defaultSize == null) next[index] = undefined
+  })
+  innerSizes.value = next
+}
+
+/** 把 offset 施加到相邻两块上，并受各自 min / max 约束 */
+function applyOffset(
+  index: number,
+  startSizes: number[],
+  container: number,
+  delta: number,
+  nextItems: Array<{ props: SplitterPanelProps }>,
+): number[] {
+  const result = [...startSizes]
+  const prev = startSizes[index] ?? 0
+  const next = startSizes[index + 1] ?? 0
+  const prevMin = toPx(nextItems[index]?.props.min, container) ?? 0
+  const prevMax = toPx(nextItems[index]?.props.max, container) ?? Number.POSITIVE_INFINITY
+  const nextMin = toPx(nextItems[index + 1]?.props.min, container) ?? 0
+  const nextMax = toPx(nextItems[index + 1]?.props.max, container) ?? Number.POSITIVE_INFINITY
+
+  let offset = delta
+  offset = Math.min(Math.max(offset, prevMin - prev), prevMax - prev)
+  offset = Math.min(Math.max(offset, next - nextMax), next - nextMin)
+  result[index] = prev + offset
+  result[index + 1] = next - offset
+  return result
+}
+
+/**
+ * 只固定分隔条两侧的两块面板，其余仍交给 flex 自动分配。
+ *
+ * 早期版本把**所有**面板都写成 px：拖动任意一根分隔条时，那些本来靠 flex
+ * 撑开的面板会被一并固定成「拖拽开始那一刻的实测宽度」，
+ * 表现为「一拖就整体跳一下、之后再也拖不动」。
+ */
+function applySizes(sizes: number[], index: number) {
+  const next = [...innerSizes.value]
+  const prev = sizes[index]
+  const after = sizes[index + 1]
+  if (Number.isFinite(prev)) next[index] = Math.round(prev)
+  if (Number.isFinite(after)) next[index + 1] = Math.round(after)
+  innerSizes.value = next
+}
+
+/* ---------- 拖拽 ---------- */
+let dragState: {
+  index: number
+  startSizes: number[]
+  container: number
+  startPos: number
+  latest: number[]
+} | null = null
+let pendingEvent: PointerEvent | null = null
+let frameId = 0
+let prevUserSelect = ''
+
+function currentItems() {
+  return getPanelItems().map((item) => ({ props: item.props }))
+}
+
+function processMove() {
+  frameId = 0
+  const event = pendingEvent
+  pendingEvent = null
+  if (!dragState || !event) return
+  const pos = props.direction === 'vertical' ? event.clientY : event.clientX
+  const delta = pos - dragState.startPos
+  const items = currentItems()
+  const sizes = applyOffset(dragState.index, dragState.startSizes, dragState.container, delta, items)
+  dragState.latest = sizes
+  applySizes(sizes, dragState.index)
+  emit('resize', sizes.map((size) => Math.round(size)))
+}
+
+function onPointerMove(event: PointerEvent) {
+  if (!dragState) return
+  pendingEvent = event
+  if (!frameId) frameId = requestAnimationFrame(processMove)
+}
+
+function onPointerUp() {
+  if (!dragState) return
+  if (frameId) {
+    cancelAnimationFrame(frameId)
+    frameId = 0
+  }
+  if (pendingEvent) processMove()
+  const items = currentItems()
+  const sizes = dragState.latest.map((size) => Math.round(size))
+  releaseAutoPanels(items)
+  emit('resize', sizes)
+  emit('resizeEnd', sizes)
+  dragState = null
+  activeBar.value = -1
+  document.body.style.userSelect = prevUserSelect
+  window.removeEventListener('pointermove', onPointerMove)
+  window.removeEventListener('pointerup', onPointerUp)
+  window.removeEventListener('pointercancel', onPointerUp)
+}
+
+function onBarPointerDown(index: number, event: PointerEvent, items: Array<{ props: SplitterPanelProps }>) {
+  if (event.button !== 0 || !canResize(index, items)) return
+  event.preventDefault()
+  const container = measureContainer()
+  const startSizes = measurePanelSizes()
+  if (!container || startSizes.length < 2) return
+  dragState = {
+    index,
+    startSizes,
+    container,
+    startPos: props.direction === 'vertical' ? event.clientY : event.clientX,
+    latest: startSizes,
+  }
+  activeBar.value = index
+  emit('resizeStart', startSizes.map((size) => Math.round(size)))
+  prevUserSelect = document.body.style.userSelect
+  document.body.style.userSelect = 'none'
+  window.addEventListener('pointermove', onPointerMove)
+  window.addEventListener('pointerup', onPointerUp)
+  window.addEventListener('pointercancel', onPointerUp)
+}
+
+/* ---------- 键盘调整 ---------- */
+function onBarKeydown(index: number, event: KeyboardEvent, items: Array<{ props: SplitterPanelProps }>) {
+  const vertical = props.direction === 'vertical'
+  const step = event.shiftKey ? 50 : 10
+  let delta = 0
+  if (vertical && event.key === 'ArrowUp') delta = -step
+  else if (vertical && event.key === 'ArrowDown') delta = step
+  else if (!vertical && event.key === 'ArrowLeft') delta = -step
+  else if (!vertical && event.key === 'ArrowRight') delta = step
+  else return
+  if (!canResize(index, items)) return
+  event.preventDefault()
+  const container = measureContainer()
+  const startSizes = measurePanelSizes()
+  if (!container || startSizes.length < 2) return
+  const sizes = applyOffset(index, startSizes, container, delta, items)
+  applySizes(sizes, index)
+  releaseAutoPanels(items)
+  const rounded = sizes.map((size) => Math.round(size))
+  emit('resize', rounded)
+  emit('resizeEnd', rounded)
+}
+
+/* ---------- ARIA 百分比 ---------- */
+const ariaValues = computed(() => {
+  const items = getPanelItems()
+  if (items.length < 2) return []
+  const container = measureContainer()
+  if (!container) return []
+  const known: Array<number | undefined> = items.map(
+    (item, index) => innerSizes.value[index] ?? toPx(item.props.size ?? item.props.defaultSize, container),
+  )
+  const knownTotal = known.reduce<number>((sum, size) => sum + (size ?? 0), 0)
+  const autoCount = known.filter((size) => size == null).length
+  const autoSize = autoCount > 0 ? Math.max(0, container - knownTotal) / autoCount : 0
+  const px = known.map((size) => size ?? autoSize)
+  const values: Array<{ now: number; min: number; max: number }> = []
+  for (let index = 0; index < items.length - 1; index++) {
+    const acc = px.slice(0, index + 1).reduce((sum, size) => sum + size, 0)
+    const prevMin = toPx(items[index].props.min, container) ?? 0
+    const nextMin = toPx(items[index + 1].props.min, container) ?? 0
+    values.push({
+      now: Math.round((acc / container) * 100),
+      min: Math.round((prevMin / container) * 100),
+      max: Math.round(100 - (nextMin / container) * 100),
+    })
+  }
+  return values
+})
+
+/* ---------- 窗口尺寸变化 ---------- */
+function syncContainer() {
+  measurePanelSizes()
+}
+
+onMounted(() => {
+  const el = rootRef.value
+  if (el) {
+    innerSizes.value = new Array(el.querySelectorAll(`.${b('splitter-panel')}`).length).fill(undefined)
+  }
+  window.addEventListener('resize', syncContainer)
+})
+
+onBeforeUnmount(() => {
+  window.removeEventListener('resize', syncContainer)
+  window.removeEventListener('pointermove', onPointerMove)
+  window.removeEventListener('pointerup', onPointerUp)
+  window.removeEventListener('pointercancel', onPointerUp)
+  if (frameId) cancelAnimationFrame(frameId)
+  document.body.style.userSelect = prevUserSelect
+})
+
+const classes = computed(() => [b(), m(props.direction), { [is('bar-on-hover')]: props.barOnHover }])
+</script>
+
+<template>
+  <div ref="rootRef" :class="classes">
+    <template v-for="(item, index) in getPanelItems()" :key="index">
+      <component :is="item.node" />
+      <div
+        v-if="!item.isLast"
+        :class="[
+          e('bar'),
+          {
+            [is('bar-active')]: activeBar === index,
+            [is('bar-hover')]: hoverBar === index,
+          },
+        ]"
+        role="separator"
+        :aria-orientation="direction === 'vertical' ? 'horizontal' : 'vertical'"
+        :aria-valuenow="ariaValues[index]?.now ?? 50"
+        :aria-valuemin="ariaValues[index]?.min ?? 0"
+        :aria-valuemax="ariaValues[index]?.max ?? 100"
+        :tabindex="canResize(index, getPanelItems()) ? 0 : undefined"
+        @pointerdown="onBarPointerDown(index, $event, getPanelItems())"
+        @keydown="onBarKeydown(index, $event, getPanelItems())"
+        @mouseenter="hoverBar = index"
+        @mouseleave="hoverBar = -1"
+      >
+        <span :class="e('bar-line')" aria-hidden="true" />
+      </div>
+    </template>
+  </div>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+.#{b('splitter')} {
+  display: flex;
+  width: 100%;
+  height: 100%;
+  overflow: hidden;
+}
+
+.#{m('splitter', 'horizontal')} {
+  flex-direction: row;
+}
+
+.#{m('splitter', 'vertical')} {
+  flex-direction: column;
+}
+
+.#{e('splitter', 'bar')} {
+  position: relative;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  /* 命中区比视觉线宽，方便抓取 */
+  #{css-var('splitter-trigger-size')}: 10px;
+  touch-action: none;
+  outline: none;
+}
+
+.#{m('splitter', 'horizontal')} .#{e('splitter', 'bar')} {
+  width: v('splitter-trigger-size', 10px);
+  cursor: col-resize;
+}
+
+.#{m('splitter', 'vertical')} .#{e('splitter', 'bar')} {
+  height: v('splitter-trigger-size', 10px);
+  cursor: row-resize;
+}
+
+.#{e('splitter', 'bar-line')} {
+  display: block;
+  background: v('border-color', #d9d9d9);
+  transition: background-color v('duration-fast', 0.1s) v('ease', ease);
+}
+
+.#{m('splitter', 'horizontal')} .#{e('splitter', 'bar-line')} {
+  width: v('splitter-bar-size', 3px);
+  height: 100%;
+}
+
+.#{m('splitter', 'vertical')} .#{e('splitter', 'bar-line')} {
+  width: 100%;
+  height: v('splitter-bar-size', 3px);
+}
+
+.#{e('splitter', 'bar')}:hover .#{e('splitter', 'bar-line')},
+.#{e('splitter', 'bar')}.#{is('bar-hover')} .#{e('splitter', 'bar-line')} {
+  background: v('text-3', rgba(0, 0, 0, 0.45));
+}
+
+.#{e('splitter', 'bar')}.#{is('bar-active')} .#{e('splitter', 'bar-line')} {
+  background: v('color-primary', #18181b);
+}
+
+.#{e('splitter', 'bar')}:focus-visible .#{e('splitter', 'bar-line')} {
+  background: v('color-primary', #18181b);
+}
+
+/* 默认仅在 hover / 聚焦 / 拖拽时显示（barOnHover 由调用方按需关闭） */
+.#{b('splitter')}.#{is('bar-on-hover')} .#{e('splitter', 'bar')}:not(.#{is('bar-hover')}):not(.#{is('bar-active')}) .#{e('splitter', 'bar-line')} {
+  background: transparent;
+}
+
+.#{b('splitter')}.#{is('bar-on-hover')} .#{e('splitter', 'bar')}:not(.#{is('bar-hover')}):not(.#{is('bar-active')}):focus-visible .#{e('splitter', 'bar-line')} {
+  background: v('color-primary', #18181b);
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/splitter/index.ts b/code/g3soft-libs/packages/ui/src/splitter/index.ts
new file mode 100644
index 00000000..1eab50fb
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/splitter/index.ts
@@ -0,0 +1,3 @@
+export { default as G3Splitter } from './Splitter.vue'
+export { default as G3SplitterPanel } from './Panel.vue'
+export type { SplitterDirection, SplitterPanelProps, SplitterProps, SplitterSize } from './types'
diff --git a/code/g3soft-libs/packages/ui/src/splitter/types.ts b/code/g3soft-libs/packages/ui/src/splitter/types.ts
new file mode 100644
index 00000000..ead73cbd
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/splitter/types.ts
@@ -0,0 +1,25 @@
+/** 分割方向：horizontal 左右分栏 / vertical 上下分栏 */
+export type SplitterDirection = 'horizontal' | 'vertical'
+
+/** 尺寸：数字（px）或 CSS 长度（如 '30%'、'240px'） */
+export type SplitterSize = number | string
+
+export interface SplitterProps {
+  /** 分割方向 */
+  direction?: SplitterDirection
+  /** 分割线仅在 hover / 聚焦 / 拖拽时显示 */
+  barOnHover?: boolean
+}
+
+export interface SplitterPanelProps {
+  /** 最小尺寸，拖拽约束 */
+  min?: SplitterSize
+  /** 最大尺寸，拖拽约束 */
+  max?: SplitterSize
+  /** 受控尺寸（由 Splitter 注入或父级传入）；传入后拖拽不再内部接管显示 */
+  size?: SplitterSize
+  /** 非受控初始尺寸；拖拽后由内部接管 */
+  defaultSize?: SplitterSize
+  /** 是否允许被相邻分隔条调整（两侧都为 true 才可拖） */
+  resizable?: boolean
+}
diff --git a/code/g3soft-libs/packages/ui/src/switch/Switch.vue b/code/g3soft-libs/packages/ui/src/switch/Switch.vue
new file mode 100644
index 00000000..628c7429
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/switch/Switch.vue
@@ -0,0 +1,130 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import { useNamespace } from '../_composables/useNamespace'
+import type { SwitchProps } from './types'
+
+/**
+ * 开关 —— 用于切换单个状态的即时开关。
+ *
+ * 开关没有原生 switch input，用 button[role=switch] 承载语义，
+ * Enter / Space 由原生 button 自动转为 click。
+ */
+defineOptions({ name: 'G3Switch' })
+
+const props = withDefaults(defineProps<SwitchProps>(), {
+  modelValue: false,
+  disabled: false,
+})
+
+const emit = defineEmits<{
+  'update:modelValue': [value: boolean]
+  change: [value: boolean, ev: MouseEvent]
+}>()
+
+const { b, e, is } = useNamespace('switch')
+
+const classes = computed(() => [
+  b(),
+  {
+    [is('checked')]: props.modelValue,
+    [is('disabled')]: props.disabled,
+  },
+])
+
+function toggle(event: MouseEvent) {
+  if (props.disabled) return
+  const next = !props.modelValue
+  emit('update:modelValue', next)
+  emit('change', next, event)
+}
+</script>
+
+<template>
+  <button
+    type="button"
+    role="switch"
+    :aria-checked="modelValue"
+    :disabled="disabled"
+    :class="classes"
+    @click="toggle"
+  >
+    <span :class="e('track')" aria-hidden="true">
+      <span :class="e('thumb')" />
+    </span>
+    <span v-if="$slots.default" :class="e('label')">
+      <slot />
+    </span>
+  </button>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+.#{b('switch')} {
+  display: inline-flex;
+  align-items: center;
+  gap: v('space-2', 8px);
+  padding: 0;
+  border: 0;
+  background: transparent;
+  color: v('text-1', rgba(0, 0, 0, 0.88));
+  font-family: inherit;
+  font-size: v('font-size', 14px);
+  line-height: v('line-height', 1.5);
+  cursor: pointer;
+  user-select: none;
+}
+
+.#{e('switch', 'track')} {
+  position: relative;
+  display: inline-block;
+  flex-shrink: 0;
+  box-sizing: border-box;
+  width: v('switch-width', 32px);
+  height: v('switch-height', 18px);
+  border-radius: 999px;
+  background: v('fill-hover', rgba(0, 0, 0, 0.08));
+  transition: background-color v('duration', 0.2s) v('ease', ease);
+}
+
+.#{e('switch', 'thumb')} {
+  position: absolute;
+  top: v('switch-thumb-offset', 2px);
+  left: v('switch-thumb-offset', 2px);
+  width: v('switch-thumb-size', 14px);
+  height: v('switch-thumb-size', 14px);
+  border-radius: 50%;
+  background: v('bg-container', #fff);
+  box-shadow: v('shadow', 0 2px 8px rgba(0, 0, 0, 0.15));
+  transition: transform v('duration', 0.2s) v('ease', ease);
+}
+
+.#{b('switch')}.#{is('checked')} .#{e('switch', 'track')} {
+  background: v('color-primary', #18181b);
+}
+
+.#{b('switch')}.#{is('checked')} .#{e('switch', 'thumb')} {
+  transform: translateX(
+    calc(
+      #{v('switch-width', 32px)} - #{v('switch-thumb-size', 14px)} - #{v('switch-thumb-offset', 2px)} *
+        2
+    )
+  );
+}
+
+.#{b('switch')}:focus-visible .#{e('switch', 'track')} {
+  @include focus-ring();
+}
+
+.#{b('switch')}.#{is('disabled')} {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .#{e('switch', 'track')},
+  .#{e('switch', 'thumb')} {
+    transition-duration: 0ms;
+  }
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/switch/index.ts b/code/g3soft-libs/packages/ui/src/switch/index.ts
new file mode 100644
index 00000000..07706dac
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/switch/index.ts
@@ -0,0 +1,2 @@
+export { default as G3Switch } from './Switch.vue'
+export type { SwitchProps } from './types'
diff --git a/code/g3soft-libs/packages/ui/src/switch/types.ts b/code/g3soft-libs/packages/ui/src/switch/types.ts
new file mode 100644
index 00000000..d656a713
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/switch/types.ts
@@ -0,0 +1,6 @@
+export interface SwitchProps {
+  /** 双向绑定的开关状态 */
+  modelValue?: boolean
+  /** 禁用态 */
+  disabled?: boolean
+}
diff --git a/code/g3soft-libs/packages/ui/src/tabs/TabPane.vue b/code/g3soft-libs/packages/ui/src/tabs/TabPane.vue
new file mode 100644
index 00000000..5d7ee603
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/tabs/TabPane.vue
@@ -0,0 +1,17 @@
+<script setup lang="ts">
+import type { TabPaneProps } from './types'
+
+/**
+ * 标签面板（声明式）—— 本组件不渲染任何 DOM。
+ *
+ * 仅作为 G3Tabs 默认插槽的声明载体：G3Tabs 收集其 key / label / disabled，
+ * 内容通过默认插槽读取后由 G3Tabs 统一渲染（首次激活才挂载，切换不销毁）。
+ */
+defineOptions({ name: 'G3TabPane' })
+
+withDefaults(defineProps<TabPaneProps>(), {
+  tabKey: undefined,
+  label: undefined,
+  disabled: false,
+})
+</script>
diff --git a/code/g3soft-libs/packages/ui/src/tabs/Tabs.test.ts b/code/g3soft-libs/packages/ui/src/tabs/Tabs.test.ts
new file mode 100644
index 00000000..6ffdd661
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/tabs/Tabs.test.ts
@@ -0,0 +1,114 @@
+import { mount } from '@vue/test-utils'
+import { describe, expect, it } from 'vitest'
+import G3TabPane from './TabPane.vue'
+import G3Tabs from './Tabs.vue'
+
+/**
+ * 回归重点：面板列表曾经把 `v-if` 与 `v-for` 写在同一元素上，
+ * Vue 3 里 `v-if` 先求值，`pane` 还是 undefined，直接抛
+ * 「Cannot read properties of undefined (reading 'key')」导致整个 Tabs 渲染不出来。
+ */
+function mountTabs(options: { modelValue?: string; disabledTab?: boolean } = {}) {
+  return mount({
+    components: { G3Tabs, G3TabPane },
+    data() {
+      return { active: options.modelValue ?? 'a' }
+    },
+    template: `
+      <G3Tabs v-model="active">
+        <G3TabPane tab-key="a" label="标签一"><p class="pane-a">内容一</p></G3TabPane>
+        <G3TabPane tab-key="b" label="标签二"><p class="pane-b">内容二</p></G3TabPane>
+        <G3TabPane tab-key="c" label="禁用项" :disabled="${Boolean(options.disabledTab)}"><p class="pane-c">内容三</p></G3TabPane>
+      </G3Tabs>
+    `,
+  })
+}
+
+describe('Tabs 渲染', () => {
+  it('挂载含多个面板时不抛错，标签按声明顺序渲染', () => {
+    const wrapper = mountTabs()
+    const tabs = wrapper.findAll('.g3-tabs__tab')
+
+    expect(tabs).toHaveLength(3)
+    expect(tabs.map((tab) => tab.text())).toEqual(['标签一', '标签二', '禁用项'])
+  })
+
+  it('面板懒渲染：只挂载当前激活项，切换后旧面板保留（不丢表单状态）', async () => {
+    const wrapper = mountTabs()
+    expect(wrapper.findAll('.g3-tabs__pane')).toHaveLength(1)
+    expect(wrapper.find('.pane-a').exists()).toBe(true)
+    expect(wrapper.find('.pane-b').exists()).toBe(false)
+
+    const tabs = wrapper.findAll('.g3-tabs__tab')
+    await tabs[1].trigger('click')
+
+    expect(wrapper.findAll('.g3-tabs__pane')).toHaveLength(2)
+    expect(wrapper.find('.pane-b').exists()).toBe(true)
+    // 切走的面板用 v-show 隐藏而不是卸载（happy-dom 的 isVisible 不可靠，直接看内联样式）
+    const panes = wrapper.findAll('.g3-tabs__pane')
+    const hidden = panes.find((pane) => pane.attributes('style')?.includes('display: none'))
+    expect(hidden?.find('.pane-a').exists()).toBe(true)
+  })
+
+  it('无障碍属性：role / aria-selected / aria-controls 对应面板 id', async () => {
+    const wrapper = mountTabs()
+    const tabs = wrapper.findAll('.g3-tabs__tab')
+    const list = wrapper.find(`.${'g3-tabs__nav-list'}`)
+
+    expect(list.attributes('role')).toBe('tablist')
+    expect(tabs[0].attributes('role')).toBe('tab')
+    expect(tabs[0].attributes('aria-selected')).toBe('true')
+    expect(tabs[1].attributes('aria-selected')).toBe('false')
+
+    const firstPanelId = tabs[0].attributes('aria-controls')
+    const panel = wrapper.find('.g3-tabs__pane')
+    expect(panel.attributes('role')).toBe('tabpanel')
+    expect(panel.attributes('id')).toBe(firstPanelId)
+    expect(panel.attributes('aria-labelledby')).toBe(tabs[0].attributes('id'))
+  })
+
+  it('点击标签切换激活项', async () => {
+    const wrapper = mountTabs()
+    await wrapper.findAll('.g3-tabs__tab')[1].trigger('click')
+    expect(wrapper.find('.pane-b').isVisible()).toBe(true)
+  })
+
+  it('禁用项点击无效', async () => {
+    const wrapper = mountTabs({ disabledTab: true })
+    const disabled = wrapper.findAll('.g3-tabs__tab')[2]
+
+    expect(disabled.attributes('disabled')).toBeDefined()
+    expect(disabled.attributes('aria-disabled')).toBe('true')
+    await disabled.trigger('click')
+    expect(wrapper.find('.pane-c').exists()).toBe(false)
+  })
+
+  it('键盘左右键在可用标签间循环', async () => {
+    const wrapper = mountTabs()
+    const list = wrapper.find('.g3-tabs__nav-list')
+
+    await list.trigger('keydown', { key: 'ArrowRight' })
+    expect(wrapper.find('.pane-b').isVisible()).toBe(true)
+
+    await list.trigger('keydown', { key: 'ArrowRight' })
+    await list.trigger('keydown', { key: 'ArrowRight' })
+    // 只有两个可用项，循环回到第一个
+    expect(wrapper.find('.pane-a').isVisible()).toBe(true)
+  })
+})
+
+describe('Tabs items 数据源', () => {
+  it('提供 items 时优先于声明式子组件', async () => {
+    const wrapper = mount(G3Tabs, {
+      props: {
+        modelValue: 'x',
+        items: [
+          { key: 'x', label: 'X 标签' },
+          { key: 'y', label: 'Y 标签' },
+        ],
+      },
+    })
+
+    expect(wrapper.findAll('.g3-tabs__tab').map((tab) => tab.text())).toEqual(['X 标签', 'Y 标签'])
+  })
+})
diff --git a/code/g3soft-libs/packages/ui/src/tabs/Tabs.vue b/code/g3soft-libs/packages/ui/src/tabs/Tabs.vue
new file mode 100644
index 00000000..9bcbb3ee
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/tabs/Tabs.vue
@@ -0,0 +1,464 @@
+<script setup lang="ts">
+import {
+  Comment,
+  Fragment,
+  computed,
+  nextTick,
+  reactive,
+  ref,
+  useId,
+  useSlots,
+  watch,
+  type VNode,
+} from 'vue'
+import { useNamespace } from '../_composables/useNamespace'
+import G3TabPane from './TabPane.vue'
+import type { TabItem, TabKey, TabsProps } from './types'
+
+/**
+ * 标签页 —— 在多个内容面板之间切换。
+ *
+ * 两种用法：`items` 数据源，或 `<G3TabPane>` 声明式子组件。
+ * 面板首次激活才挂载、切换不销毁，form 状态不会丢；键盘 ←→ / ↑↓ / Home / End 可用。
+ */
+defineOptions({ name: 'G3Tabs' })
+
+const props = withDefaults(defineProps<TabsProps>(), {
+  modelValue: undefined,
+  placement: 'top',
+  type: 'line',
+  navOnly: false,
+  centered: false,
+  disabled: false,
+  items: undefined,
+})
+
+const emit = defineEmits<{
+  'update:modelValue': [key: TabKey]
+  change: [key: TabKey]
+  tabClick: [key: TabKey, ev: MouseEvent]
+}>()
+
+const slots = useSlots()
+const { b, e, m, is } = useNamespace('tabs')
+
+const baseId = useId()
+const innerKey = ref<string | undefined>(undefined)
+const tabRefs: Record<string, HTMLButtonElement | null> = {}
+
+interface MergedPane {
+  key: string
+  rawKey: TabKey
+  disabled: boolean
+  labelText?: string
+  labelRender?: () => VNode | VNode[]
+  content?: () => VNode | VNode[]
+}
+
+/** 展平 vnode 列表：展开 Fragment，丢弃注释 / 文本占位 */
+function flattenVNodes(nodes: VNode[] | undefined): VNode[] {
+  const result: VNode[] = []
+  for (const node of nodes ?? []) {
+    if (!node) continue
+    if (node.type === Fragment && Array.isArray(node.children)) {
+      result.push(...flattenVNodes(node.children as VNode[]))
+      continue
+    }
+    // 注释 / 文本占位节点都是 symbol 类型（Fragment 已在上面单独处理）
+    if (typeof node.type === 'symbol') continue
+    result.push(node)
+  }
+  return result
+}
+
+/** 内容归一：插槽集合取 default，vnode 包成渲染函数 */
+function extractContent(children: unknown): (() => VNode | VNode[]) | undefined {
+  if (children == null) return undefined
+  if (Array.isArray(children)) return () => children as VNode[]
+  if (typeof children === 'object' && 'default' in (children as Record<string, unknown>)) {
+    const slot = (children as Record<string, () => VNode | VNode[]>).default
+    return () => slot?.() ?? []
+  }
+  return () => children as VNode
+}
+
+/** 插槽形态：从 G3TabPane 收集 key / label / disabled / content */
+const slotPanes = computed<MergedPane[]>(() => {
+  const panes: MergedPane[] = []
+  flattenVNodes(slots.default?.() as VNode[] | undefined).forEach((vnode, index) => {
+    const paneType = (vnode.type as { name?: string } | undefined)?.name
+    if (paneType !== (G3TabPane as unknown as { name?: string }).name) return
+    const raw = (vnode.props ?? {}) as Record<string, unknown>
+    const rawKey = (raw.tabKey ?? raw['tab-key'] ?? index) as TabKey
+    const labelSlot =
+      vnode.children && typeof vnode.children === 'object' && 'label' in vnode.children
+        ? (vnode.children as Record<string, (scope?: unknown) => VNode | VNode[]>).label
+        : undefined
+    panes.push({
+      key: String(rawKey),
+      rawKey,
+      // `<G3TabPane disabled />` 的空值布尔属性在 vnode.props 里是 ''，
+      // Boolean('') 会判成 false，必须显式排除 false
+      disabled: raw.disabled != null && raw.disabled !== false,
+      labelText: raw.label == null ? undefined : String(raw.label),
+      labelRender: labelSlot ? () => labelSlot() : undefined,
+      content: extractContent(vnode.children),
+    })
+  })
+  return panes
+})
+
+/** items 形态 */
+const itemsPanes = computed<MergedPane[]>(() =>
+  (props.items ?? []).map((item: TabItem, index) => ({
+    key: String(item.key ?? index),
+    rawKey: item.key ?? index,
+    disabled: Boolean(item.disabled),
+    labelText: typeof item.label === 'string' ? item.label : undefined,
+    labelRender: item.label && typeof item.label !== 'string' ? () => item.label as VNode : undefined,
+    content:
+      typeof item.content === 'function'
+        ? (item.content as () => VNode)
+        : item.content
+          ? () => item.content as VNode
+          : undefined,
+  })),
+)
+
+const mergedPanes = computed(() => (itemsPanes.value.length > 0 ? itemsPanes.value : slotPanes.value))
+
+const enabledKeys = computed(() => mergedPanes.value.filter((pane) => !pane.disabled).map((pane) => pane.key))
+
+/** 受控优先；指向不存在 / 禁用项时回退到首个可用项（只影响显示，不回写） */
+const currentKey = computed(() => {
+  const raw = props.modelValue != null ? String(props.modelValue) : innerKey.value
+  const exists = raw != null && mergedPanes.value.some((pane) => pane.key === raw && !pane.disabled)
+  if (exists) return raw as string
+  return enabledKeys.value[0]
+})
+
+/** 懒渲染缓存：首次激活才挂载，切换不销毁（form 状态不丢） */
+const renderedKeys = reactive(new Set<string>())
+watch(
+  currentKey,
+  (key) => {
+    if (key) renderedKeys.add(key)
+  },
+  { immediate: true },
+)
+
+const classes = computed(() => [
+  b(),
+  m(props.placement),
+  m(props.type),
+  {
+    [is('disabled')]: props.disabled,
+    [is('centered')]: props.centered,
+    [is('nav-only')]: props.navOnly,
+  },
+])
+
+function selectKey(pane: MergedPane) {
+  if (props.disabled || pane.disabled) return
+  if (String(props.modelValue ?? innerKey.value) === pane.key) return
+  if (props.modelValue == null) innerKey.value = pane.key
+  emit('update:modelValue', pane.rawKey)
+  emit('change', pane.rawKey)
+}
+
+function onTabClick(pane: MergedPane, event: MouseEvent) {
+  if (props.disabled || pane.disabled) return
+  selectKey(pane)
+  emit('tabClick', pane.rawKey, event)
+}
+
+function setTabRef(key: string, el: unknown) {
+  tabRefs[key] = (el as HTMLButtonElement | null) ?? null
+}
+
+/** 键盘导航：左右键（top）或上下键切换，Home / End 跳首尾 */
+function onNavKeydown(event: KeyboardEvent) {
+  const keys = enabledKeys.value
+  if (!keys.length) return
+  const current = currentKey.value ?? keys[0]
+  const pos = keys.indexOf(current)
+  const horizontal = props.placement === 'top'
+  let next = -1
+  switch (event.key) {
+    case 'ArrowRight':
+      if (!horizontal) return
+      next = (pos + 1) % keys.length
+      break
+    case 'ArrowLeft':
+      if (!horizontal) return
+      next = (pos - 1 + keys.length) % keys.length
+      break
+    case 'ArrowDown':
+      if (horizontal) return
+      next = (pos + 1) % keys.length
+      break
+    case 'ArrowUp':
+      if (horizontal) return
+      next = (pos - 1 + keys.length) % keys.length
+      break
+    case 'Home':
+      next = 0
+      break
+    case 'End':
+      next = keys.length - 1
+      break
+    default:
+      return
+  }
+  event.preventDefault()
+  const pane = mergedPanes.value.find((item) => item.key === keys[next])
+  if (!pane) return
+  selectKey(pane)
+  nextTick(() => tabRefs[pane.key]?.focus())
+}
+
+/** 标签栏标签内容：优先 #label 插槽，其次 items 的 VNode，最后纯文本 */
+function renderLabel(pane: MergedPane, index: number): VNode | VNode[] | undefined {
+  if (slots.label) return slots.label({ item: pane.rawKey, index })
+  if (pane.labelRender) return pane.labelRender()
+  return undefined
+}
+
+/** 渲染函数组件：把 vnode / vnode 数组原样渲染（模板里 <component :is="vnode"> 不可靠） */
+const VNodeRenderer = (renderProps: {
+  render?: () => VNode | VNode[] | undefined
+}): VNode | VNode[] | null => renderProps.render?.() ?? null
+</script>
+
+<template>
+  <div :class="classes">
+    <div :class="e('nav')">
+      <div v-if="$slots.leftExtra" :class="e('nav-extra')">
+        <slot name="leftExtra" />
+      </div>
+
+      <div :class="e('nav-scroll')">
+        <div
+          :class="e('nav-list')"
+          role="tablist"
+          :aria-orientation="placement === 'top' ? 'horizontal' : 'vertical'"
+          @keydown="onNavKeydown"
+        >
+          <button
+            v-for="(pane, index) in mergedPanes"
+            :key="pane.key"
+            :ref="(el) => setTabRef(pane.key, el)"
+            type="button"
+            :class="[
+              e('tab'),
+              {
+                [is('tab-active')]: currentKey === pane.key,
+                [is('tab-disabled')]: disabled || pane.disabled,
+              },
+            ]"
+            role="tab"
+            :id="`${baseId}-tab-${index}`"
+            :aria-controls="`${baseId}-panel-${index}`"
+            :aria-selected="currentKey === pane.key"
+            :aria-disabled="disabled || pane.disabled || undefined"
+            :tabindex="currentKey === pane.key ? 0 : -1"
+            :disabled="disabled || pane.disabled"
+            @click="onTabClick(pane, $event)"
+          >
+            <VNodeRenderer
+              v-if="renderLabel(pane, index)"
+              :render="() => renderLabel(pane, index)"
+            />
+            <template v-else>{{ pane.labelText }}</template>
+          </button>
+        </div>
+      </div>
+
+      <div v-if="$slots.rightExtra" :class="e('nav-extra')">
+        <slot name="rightExtra" />
+      </div>
+    </div>
+
+    <div v-if="!navOnly" :class="e('content')">
+      <!-- v-for 放在 <template> 上：同一元素同时写 v-if / v-for 时 v-if 先求值，
+           此时 pane 还未定义，会在渲染期抛 'reading key of undefined' -->
+      <template v-for="(pane, index) in mergedPanes" :key="pane.key">
+        <div
+          v-if="renderedKeys.has(pane.key)"
+          v-show="currentKey === pane.key"
+          :class="e('pane')"
+          role="tabpanel"
+          :id="`${baseId}-panel-${index}`"
+          :aria-labelledby="`${baseId}-tab-${index}`"
+          tabindex="0"
+        >
+          <VNodeRenderer v-if="pane.content" :render="pane.content" />
+        </div>
+      </template>
+    </div>
+  </div>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+.#{b('tabs')} {
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+}
+
+.#{b('tabs')}.#{m('tabs', 'left')} {
+  flex-direction: row;
+}
+
+.#{b('tabs')}.#{m('tabs', 'right')} {
+  flex-direction: row-reverse;
+}
+
+.#{e('tabs', 'nav')} {
+  display: flex;
+  align-items: center;
+  gap: v('space-2', 8px);
+  border-bottom: 1px solid v('border-color', #d9d9d9);
+}
+
+.#{b('tabs')}.#{m('tabs', 'left')} .#{e('tabs', 'nav')},
+.#{b('tabs')}.#{m('tabs', 'right')} .#{e('tabs', 'nav')} {
+  flex-direction: column;
+  align-items: stretch;
+  border-bottom: 0;
+}
+
+/* 垂直模式：标签栏与内容区之间的竖向分隔线。
+   原来只是把横向的下边框去掉、没有补竖线，所以 placement="left" 时看不到分隔线 */
+.#{b('tabs')}.#{m('tabs', 'left')} .#{e('tabs', 'nav')} {
+  border-right: 1px solid v('border-color', #d9d9d9);
+}
+
+.#{b('tabs')}.#{m('tabs', 'right')} .#{e('tabs', 'nav')} {
+  border-left: 1px solid v('border-color', #d9d9d9);
+}
+
+.#{b('tabs')}.#{m('tabs', 'pill')} .#{e('tabs', 'nav')} {
+  border-bottom: 0;
+}
+
+.#{e('tabs', 'nav-extra')} {
+  display: inline-flex;
+  align-items: center;
+  flex-shrink: 0;
+}
+
+.#{e('tabs', 'nav-scroll')} {
+  flex: 1;
+  min-width: 0;
+  overflow: auto;
+  scrollbar-width: none;
+
+  &::-webkit-scrollbar {
+    display: none;
+  }
+}
+
+.#{e('tabs', 'nav-list')} {
+  display: flex;
+  align-items: center;
+  gap: v('space-1', 4px);
+}
+
+.#{b('tabs')}.#{is('centered')} .#{e('tabs', 'nav-list')} {
+  justify-content: center;
+}
+
+.#{b('tabs')}.#{m('tabs', 'left')} .#{e('tabs', 'nav-list')},
+.#{b('tabs')}.#{m('tabs', 'right')} .#{e('tabs', 'nav-list')} {
+  flex-direction: column;
+  align-items: stretch;
+}
+
+.#{e('tabs', 'tab')} {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: v('space-1', 4px);
+  box-sizing: border-box;
+  min-height: v('tabs-tab-height', 38px);
+  padding: 0 v('space-3', 12px);
+  border: 0;
+  border-bottom: 2px solid transparent;
+  background: transparent;
+  color: v('text-2', rgba(0, 0, 0, 0.65));
+  font-family: inherit;
+  font-size: v('font-size', 14px);
+  line-height: v('line-height', 1.5);
+  white-space: nowrap;
+  cursor: pointer;
+  transition:
+    color v('duration', 0.2s) v('ease', ease),
+    background-color v('duration', 0.2s) v('ease', ease),
+    border-color v('duration', 0.2s) v('ease', ease);
+}
+
+.#{e('tabs', 'tab')}:hover:not(:disabled) {
+  color: v('color-primary', #18181b);
+}
+
+.#{e('tabs', 'tab')}.#{is('tab-active')} {
+  color: v('color-primary', #18181b);
+  border-bottom-color: v('color-primary', #18181b);
+}
+
+.#{b('tabs')}.#{m('tabs', 'left')} .#{e('tabs', 'tab')},
+.#{b('tabs')}.#{m('tabs', 'right')} .#{e('tabs', 'tab')} {
+  justify-content: flex-start;
+  border-bottom: 0;
+}
+
+.#{b('tabs')}.#{m('tabs', 'left')} .#{e('tabs', 'tab')}.#{is('tab-active')} {
+  border-right: 2px solid v('color-primary', #18181b);
+  background: v('fill', rgba(0, 0, 0, 0.04));
+}
+
+.#{b('tabs')}.#{m('tabs', 'right')} .#{e('tabs', 'tab')}.#{is('tab-active')} {
+  border-left: 2px solid v('color-primary', #18181b);
+  background: v('fill', rgba(0, 0, 0, 0.04));
+}
+
+/* pill：胶囊式标签项 */
+.#{b('tabs')}.#{m('tabs', 'pill')} .#{e('tabs', 'tab')} {
+  border-bottom: 0;
+  border-radius: v('radius', 6px);
+}
+
+.#{b('tabs')}.#{m('tabs', 'pill')} .#{e('tabs', 'tab')}.#{is('tab-active')} {
+  background: v('color-primary', #18181b);
+  color: v('color-primary-on', #fafafa);
+}
+
+.#{e('tabs', 'tab')}:focus-visible {
+  @include focus-ring();
+}
+
+.#{e('tabs', 'tab')}:disabled,
+.#{e('tabs', 'tab')}.#{is('tab-disabled')} {
+  color: v('text-disabled', rgba(0, 0, 0, 0.25));
+  cursor: not-allowed;
+}
+
+.#{e('tabs', 'content')} {
+  flex: 1;
+  min-width: 0;
+  padding: v('space-4', 16px) 0;
+}
+
+.#{b('tabs')}.#{m('tabs', 'left')} .#{e('tabs', 'content')},
+.#{b('tabs')}.#{m('tabs', 'right')} .#{e('tabs', 'content')} {
+  padding: 0 v('space-4', 16px);
+}
+
+.#{e('tabs', 'pane')} {
+  outline: none;
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/tabs/index.ts b/code/g3soft-libs/packages/ui/src/tabs/index.ts
new file mode 100644
index 00000000..23c81a84
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/tabs/index.ts
@@ -0,0 +1,3 @@
+export { default as G3Tabs } from './Tabs.vue'
+export { default as G3TabPane } from './TabPane.vue'
+export type { TabItem, TabKey, TabPaneProps, TabsPlacement, TabsProps, TabsType } from './types'
diff --git a/code/g3soft-libs/packages/ui/src/tabs/types.ts b/code/g3soft-libs/packages/ui/src/tabs/types.ts
new file mode 100644
index 00000000..6a934a4d
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/tabs/types.ts
@@ -0,0 +1,48 @@
+import type { VNode } from 'vue'
+
+/** 标签栏位置 */
+export type TabsPlacement = 'top' | 'left' | 'right'
+
+/** 视觉风格：line 下划线指示条 / pill 胶囊 */
+export type TabsType = 'line' | 'pill'
+
+/** 标签项的 key */
+export type TabKey = string | number
+
+/** items 数据源的一项 */
+export interface TabItem {
+  /** 唯一标识 */
+  key: TabKey
+  /** 标签文本；也可传 VNode */
+  label?: string | VNode
+  /** 禁用该项 */
+  disabled?: boolean
+  /** 面板内容：VNode 或返回 VNode 的渲染函数 */
+  content?: VNode | (() => VNode)
+}
+
+export interface TabPaneProps {
+  /** 唯一标识；不传时按声明顺序取索引 */
+  tabKey?: TabKey
+  /** 标签文本（有 #label 插槽时忽略） */
+  label?: string
+  /** 禁用态 */
+  disabled?: boolean
+}
+
+export interface TabsProps {
+  /** 双向绑定的激活面板 key */
+  modelValue?: TabKey
+  /** 标签栏位置 */
+  placement?: TabsPlacement
+  /** 视觉风格 */
+  type?: TabsType
+  /** 只渲染标签栏，内容由外部控制 */
+  navOnly?: boolean
+  /** 标签栏居中 */
+  centered?: boolean
+  /** 整组禁用 */
+  disabled?: boolean
+  /** 数据源；提供且非空时优先于 G3TabPane 插槽 */
+  items?: TabItem[]
+}
diff --git a/code/g3soft-libs/packages/ui/src/tag/Tag.vue b/code/g3soft-libs/packages/ui/src/tag/Tag.vue
new file mode 100644
index 00000000..b2b4c4a3
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/tag/Tag.vue
@@ -0,0 +1,165 @@
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import { X } from '@lucide/vue'
+import { useLocale } from '../_composables/useLocale'
+import { useNamespace } from '../_composables/useNamespace'
+import type { TagProps } from './types'
+
+/**
+ * 标签 —— 用于标记与分类的小型容器，支持多种视觉变体与可关闭态。
+ *
+ * 点击关闭按钮触发 close 事件并隐藏自身；在事件里调用 `event.preventDefault()`
+ * 可以阻止自动隐藏（受控用法）。
+ */
+defineOptions({ name: 'G3Tag' })
+
+const props = withDefaults(defineProps<TagProps>(), {
+  variant: 'default',
+  closable: false,
+  disabled: false,
+  href: undefined,
+})
+
+const emit = defineEmits<{ close: [ev: Event] }>()
+
+const { b, e, m, is } = useNamespace('tag')
+const locale = useLocale()
+
+/** 与 antdv 一致：close 后标签自身消失 */
+const visible = ref(true)
+
+const classes = computed(() => [
+  b(),
+  m(props.variant),
+  {
+    [is('disabled')]: props.disabled,
+    [is('hidden')]: !visible.value,
+  },
+])
+
+function onClose(event: Event) {
+  if (props.disabled) return
+  emit('close', event)
+  if (!event.defaultPrevented) visible.value = false
+}
+
+/** 关闭按钮没有原生语义，用 role="button" + Enter/Space 触发 */
+function onCloseKeydown(event: KeyboardEvent) {
+  if (event.key === 'Enter' || event.key === ' ') {
+    event.preventDefault()
+    onClose(event)
+  }
+}
+</script>
+
+<template>
+  <component
+    :is="href ? 'a' : 'span'"
+    :class="classes"
+    :href="disabled ? undefined : href"
+    :aria-disabled="disabled || undefined"
+  >
+    <span v-if="$slots.icon" :class="e('icon')"><slot name="icon" /></span>
+    <span :class="e('content')"><slot /></span>
+    <span
+      v-if="closable"
+      :class="e('close')"
+      role="button"
+      :tabindex="disabled ? -1 : 0"
+      :aria-label="locale.common.close"
+      :aria-disabled="disabled || undefined"
+      @click="onClose"
+      @keydown="onCloseKeydown"
+    >
+      <slot name="close-icon"><X aria-hidden="true" /></slot>
+    </span>
+  </component>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+.#{b('tag')} {
+  display: inline-flex;
+  align-items: center;
+  gap: v('space-1', 4px);
+  box-sizing: border-box;
+  max-width: 100%;
+  height: v('tag-height', 20px);
+  padding: 0 v('space-2', 8px);
+  border: 1px solid transparent;
+  border-radius: v('radius-sm', 4px);
+  font-size: v('font-size-sm', 12px);
+  line-height: 1;
+  white-space: nowrap;
+  text-decoration: none;
+
+  svg {
+    width: 1em;
+    height: 1em;
+  }
+}
+
+.#{e('tag', 'content')} {
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+/* ---------- 变体 ---------- */
+.#{m('tag', 'default')} {
+  background: v('color-primary', #18181b);
+  color: v('color-primary-on', #fafafa);
+}
+
+.#{m('tag', 'secondary')} {
+  background: v('fill', rgba(0, 0, 0, 0.04));
+  color: v('text-1', rgba(0, 0, 0, 0.88));
+}
+
+.#{m('tag', 'outline')} {
+  border-color: v('border-color', #d9d9d9);
+  color: v('text-1', rgba(0, 0, 0, 0.88));
+}
+
+.#{m('tag', 'success')} {
+  background: v('color-success', #45b114);
+  color: v('text-inverse', #fff);
+}
+
+.#{m('tag', 'danger')} {
+  background: v('color-danger', #ec4246);
+  color: v('text-inverse', #fff);
+}
+
+.#{m('tag', 'ghost')} {
+  color: v('text-2', rgba(0, 0, 0, 0.65));
+}
+
+/* ---------- 关闭按钮 ---------- */
+.#{e('tag', 'close')} {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  cursor: pointer;
+  opacity: 0.7;
+  transition: opacity v('duration-fast', 0.1s) v('ease', ease);
+}
+
+.#{e('tag', 'close')}:hover {
+  opacity: 1;
+}
+
+.#{e('tag', 'close')}:focus-visible {
+  @include focus-ring();
+}
+
+/* ---------- 状态 ---------- */
+.#{b('tag')}.#{is('disabled')} {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.#{b('tag')}.#{is('hidden')} {
+  display: none;
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/tag/index.ts b/code/g3soft-libs/packages/ui/src/tag/index.ts
new file mode 100644
index 00000000..b459b06c
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/tag/index.ts
@@ -0,0 +1,2 @@
+export { default as G3Tag } from './Tag.vue'
+export type { TagProps, TagVariant } from './types'
diff --git a/code/g3soft-libs/packages/ui/src/tag/types.ts b/code/g3soft-libs/packages/ui/src/tag/types.ts
new file mode 100644
index 00000000..f476d116
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/tag/types.ts
@@ -0,0 +1,13 @@
+/** 标签视觉变体 */
+export type TagVariant = 'default' | 'secondary' | 'outline' | 'success' | 'danger' | 'ghost'
+
+export interface TagProps {
+  /** 视觉变体 */
+  variant?: TagVariant
+  /** 是否可关闭：显示关闭按钮，点击后触发 close 并隐藏自身 */
+  closable?: boolean
+  /** 禁用态 */
+  disabled?: boolean
+  /** 链接地址：传入后渲染为 <a>，可点击跳转 */
+  href?: string
+}
diff --git a/code/g3soft-libs/packages/ui/src/tooltip/Tooltip.vue b/code/g3soft-libs/packages/ui/src/tooltip/Tooltip.vue
new file mode 100644
index 00000000..6a7d8baf
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/tooltip/Tooltip.vue
@@ -0,0 +1,69 @@
+<script setup lang="ts">
+import { useNamespace } from '../_composables/useNamespace'
+import G3Popover from '../popover/Popover.vue'
+import type { TooltipProps } from './types'
+
+/**
+ * 文字提示 —— hover 时显示简短说明。
+ *
+ * 是 G3Popover 的 hover 薄封装：固定 trigger=hover 与零包裹模式，
+ * 定位 / Teleport / 移入不关闭 / 延迟 / Esc 均由 Popover 提供。
+ */
+defineOptions({ name: 'G3Tooltip' })
+
+const props = withDefaults(defineProps<TooltipProps>(), {
+  content: '',
+  open: undefined,
+  defaultOpen: false,
+  placement: 'top',
+  arrow: true,
+  mouseEnterDelay: 100,
+  mouseLeaveDelay: 100,
+  disabled: false,
+})
+
+const emit = defineEmits<{
+  'update:open': [value: boolean]
+  openChange: [value: boolean]
+}>()
+
+const { e } = useNamespace('tooltip')
+</script>
+
+<template>
+  <G3Popover
+    :open="props.open"
+    :default-open="props.defaultOpen"
+    trigger="hover"
+    :placement="props.placement"
+    :arrow="props.arrow"
+    :mouse-enter-delay="props.mouseEnterDelay"
+    :mouse-leave-delay="props.mouseLeaveDelay"
+    :disabled="props.disabled"
+    unwrapped
+    @update:open="emit('update:open', $event)"
+    @open-change="emit('openChange', $event)"
+  >
+    <!-- 默认插槽作为触发器 -->
+    <template #trigger>
+      <slot />
+    </template>
+
+    <!-- 富内容插槽优先，否则回退到 content 纯文本 -->
+    <template #content>
+      <slot name="content">
+        <span :class="e('text')">{{ props.content }}</span>
+      </slot>
+    </template>
+  </G3Popover>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+.#{e('tooltip', 'text')} {
+  display: inline-block;
+  max-width: 260px;
+  word-break: break-word;
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/tooltip/index.ts b/code/g3soft-libs/packages/ui/src/tooltip/index.ts
new file mode 100644
index 00000000..74387e70
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/tooltip/index.ts
@@ -0,0 +1,2 @@
+export { default as G3Tooltip } from './Tooltip.vue'
+export type { TooltipProps } from './types'
diff --git a/code/g3soft-libs/packages/ui/src/tooltip/types.ts b/code/g3soft-libs/packages/ui/src/tooltip/types.ts
new file mode 100644
index 00000000..b8722fad
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/tooltip/types.ts
@@ -0,0 +1,20 @@
+import type { Placement } from '../_utils/position'
+
+export interface TooltipProps {
+  /** 提示文本（纯文本）；与 #content 插槽同时存在时插槽优先 */
+  content?: string
+  /** 受控打开状态；不传则非受控 */
+  open?: boolean
+  /** 非受控时的初始打开状态 */
+  defaultOpen?: boolean
+  /** 期望方位 */
+  placement?: Placement
+  /** 是否显示箭头 */
+  arrow?: boolean
+  /** hover 触发打开延迟（ms） */
+  mouseEnterDelay?: number
+  /** hover 触发关闭延迟（ms） */
+  mouseLeaveDelay?: number
+  /** 禁用态 */
+  disabled?: boolean
+}
diff --git a/code/g3soft-libs/packages/ui/src/tree/Tree.vue b/code/g3soft-libs/packages/ui/src/tree/Tree.vue
new file mode 100644
index 00000000..0044ea19
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/tree/Tree.vue
@@ -0,0 +1,812 @@
+<script setup lang="ts">
+import {
+  computed,
+  isVNode,
+  nextTick,
+  onBeforeUnmount,
+  provide,
+  reactive,
+  ref,
+  watch,
+  type VNode,
+} from 'vue'
+import { useLocale } from '../_composables/useLocale'
+import { useNamespace } from '../_composables/useNamespace'
+import { usePopupContainer } from '../_composables/usePopupContainer'
+import { computePosition, type RectLike } from '../_utils/position'
+import { nextZIndex, releaseZIndex } from '../_utils/z-index'
+import { treeContextKey } from './context'
+import G3TreeNode from './TreeNode.vue'
+import type {
+  DropPosition,
+  TreeCheckPayload,
+  TreeContext,
+  TreeContextMenuItem,
+  TreeKey,
+  TreeNodeData,
+  TreeProps,
+} from './types'
+import {
+  buildFlat,
+  calcDropPosition,
+  collectDescendants,
+  conductCheck,
+  filterTree,
+  getNodeChildren,
+  getNodeKey,
+  getParentKeys,
+  isLeafNode,
+  resolveFieldNames,
+} from './utils'
+
+/**
+ * 树形控件 —— 支持选中、勾选联动、过滤、拖拽排序、懒加载与右键菜单。
+ *
+ * 四套键（展开 / 选中 / 勾选 / 加载）都支持受控（传 prop 即受控）与非受控；
+ * 勾选非严格模式下只保存显式勾选的键，父子联动与半选状态由数据推导。
+ */
+defineOptions({ name: 'G3Tree' })
+
+const props = withDefaults(defineProps<TreeProps>(), {
+  treeData: () => [],
+  fieldNames: undefined,
+  checkable: false,
+  selectable: true,
+  multiple: false,
+  checkStrictly: false,
+  disabled: false,
+  lazy: false,
+  draggable: false,
+  externalDragKey: undefined,
+  filter: '',
+  blockNode: false,
+  defaultExpandAll: false,
+  defaultExpandParent: true,
+  autoExpandParent: false,
+  contextMenu: undefined,
+  expandedKeys: undefined,
+  selectedKeys: undefined,
+  checkedKeys: undefined,
+  loadedKeys: undefined,
+  defaultExpandedKeys: () => [],
+  defaultSelectedKeys: () => [],
+  defaultCheckedKeys: () => [],
+  defaultLoadedKeys: () => [],
+})
+
+const emit = defineEmits<{
+  select: [keys: TreeKey[], info: { node: TreeNodeData; selectedKeys: TreeKey[]; nativeEvent: MouseEvent }]
+  check: [payload: TreeCheckPayload, info: { node: TreeNodeData; checked: boolean }]
+  expand: [expandedKeys: TreeKey[], info: { node: TreeNodeData; expanded: boolean }]
+  load: [node: TreeNodeData]
+  drop: [info: { dragKey: TreeKey; dropKey: TreeKey; dropPosition: DropPosition; node: TreeNodeData; event: DragEvent }]
+  dragstart: [info: { node: TreeNodeData; event: DragEvent }]
+  dragover: [info: { node: TreeNodeData; dropPosition: DropPosition; event: DragEvent }]
+  dragleave: [info: { node: TreeNodeData; event: DragEvent }]
+  dragend: [info: { node: TreeNodeData; event: DragEvent }]
+  contextmenu: [info: { node: TreeNodeData | null; key: TreeKey | null; event: MouseEvent }]
+  contextMenuClick: [info: { item: TreeContextMenuItem; node: TreeNodeData | null; key: TreeKey | null; event: MouseEvent }]
+  'update:expandedKeys': [keys: TreeKey[]]
+  'update:selectedKeys': [keys: TreeKey[]]
+  'update:checkedKeys': [keys: TreeKey[]]
+  'update:loadedKeys': [keys: TreeKey[]]
+}>()
+
+const { b, e, is } = useNamespace('tree')
+const locale = useLocale()
+const teleportTo = usePopupContainer()
+
+const fieldNames = computed(() => resolveFieldNames(props.fieldNames))
+const flat = computed(() => buildFlat(props.treeData, fieldNames.value))
+
+/* ---------- 受控 / 非受控键模型 ---------- */
+function createKeyModel(options: {
+  controlled: () => TreeKey[] | undefined
+  initial: () => TreeKey[]
+  emitKeys: (keys: TreeKey[]) => void
+}) {
+  const internal = ref<string[]>(options.initial().map(String))
+  const set = computed(() => {
+    const value = options.controlled()
+    return new Set(value === undefined ? internal.value : value.map(String))
+  })
+  function update(next: Set<string>) {
+    const keys = [...next]
+    if (options.controlled() === undefined) internal.value = keys
+    options.emitKeys(keys)
+  }
+  return { set, update, internal }
+}
+
+const expandedModel = createKeyModel({
+  controlled: () => props.expandedKeys,
+  initial: () => {
+    if (props.defaultExpandAll) {
+      return [...flat.value.nodeMap.keys()]
+    }
+    const keys = props.defaultExpandedKeys
+    return props.defaultExpandParent
+      ? [...new Set([...keys.map(String), ...getParentKeys(keys, flat.value.parentMap)])]
+      : keys
+  },
+  emitKeys: (keys) => emit('update:expandedKeys', keys),
+})
+
+const selectedModel = createKeyModel({
+  controlled: () => props.selectedKeys,
+  initial: () => props.defaultSelectedKeys,
+  emitKeys: (keys) => emit('update:selectedKeys', keys),
+})
+
+const loadedModel = createKeyModel({
+  controlled: () => props.loadedKeys,
+  initial: () => props.defaultLoadedKeys,
+  emitKeys: (keys) => emit('update:loadedKeys', keys),
+})
+
+/** 勾选：非严格模式只保存显式键，父子联动由 conductCheck 推导 */
+const explicitChecked = ref<string[]>(
+  (Array.isArray(props.defaultCheckedKeys) ? props.defaultCheckedKeys : []).map(String),
+)
+const checkedExplicitSet = computed(() => {
+  const controlled = props.checkedKeys
+  if (controlled === undefined) return new Set(explicitChecked.value)
+  const list = Array.isArray(controlled) ? controlled : controlled.checked
+  return new Set(list.map(String))
+})
+
+const conductResult = computed(() => {
+  if (props.checkStrictly) {
+    return { checked: new Set(checkedExplicitSet.value), half: new Set<string>() }
+  }
+  return conductCheck(props.treeData, checkedExplicitSet.value, fieldNames.value)
+})
+
+const expandedSet = expandedModel.set
+const selectedSet = selectedModel.set
+const loadingSet = ref(new Set<string>())
+
+/* ---------- 过滤 ---------- */
+const filterActive = computed(() => props.filter.trim() !== '')
+const filterInfo = computed(() => filterTree(props.treeData, props.filter, fieldNames.value))
+
+/** 过滤命中的祖先需要临时展开，但不写入用户的 expandedKeys */
+const effectiveExpanded = computed(() => {
+  const set = new Set(expandedSet.value)
+  if (filterActive.value) filterInfo.value.expand.forEach((key) => set.add(key))
+  return set
+})
+
+/* ---------- 可见节点（键盘导航用） ---------- */
+const visibleKeys = computed(() => {
+  const keys: string[] = []
+  const visible = filterActive.value ? filterInfo.value.matched : null
+  function walk(nodes: TreeNodeData[]) {
+    for (const node of nodes) {
+      const key = String(getNodeKey(node, fieldNames.value))
+      if (visible && !visible.has(key)) continue
+      keys.push(key)
+      if (effectiveExpanded.value.has(key)) {
+        const children = getNodeChildren(node, fieldNames.value)
+        if (children) walk(children)
+      }
+    }
+  }
+  walk(props.treeData)
+  return keys
+})
+
+const activeKey = ref<string | null>(null)
+watch(
+  visibleKeys,
+  (keys) => {
+    if (!keys.length) activeKey.value = null
+    else if (!activeKey.value || !keys.includes(activeKey.value)) activeKey.value = keys[0]
+  },
+  { immediate: true },
+)
+
+const nodeEls = new Map<string, HTMLElement>()
+function registerNode(key: string, el: HTMLElement | null) {
+  if (el) nodeEls.set(key, el)
+}
+function unregisterNode(key: string) {
+  nodeEls.delete(key)
+}
+
+/* ---------- 展开 ---------- */
+function nodeOf(key: string): TreeNodeData | undefined {
+  return flat.value.nodeMap.get(key)
+}
+
+function toggleExpand(node: TreeNodeData, key: TreeKey) {
+  const textKey = String(key)
+  if (props.disabled) return
+  const next = new Set(expandedSet.value)
+  const willExpand = !next.has(textKey)
+  if (willExpand) next.add(textKey)
+  else next.delete(textKey)
+  expandedModel.update(next)
+  emit('expand', [...next], { node, expanded: willExpand })
+  // 懒加载：首次展开且未加载过、无子节点、未显式标记叶子
+  if (
+    willExpand &&
+    props.lazy &&
+    !loadedModel.set.value.has(textKey) &&
+    !getNodeChildren(node, fieldNames.value) &&
+    node.isLeaf !== true
+  ) {
+    loadingSet.value.add(textKey)
+    emit('load', node)
+  }
+}
+
+watch(
+  () => loadedModel.set.value,
+  (loaded) => {
+    if (!loadingSet.value.size) return
+    const next = new Set(loadingSet.value)
+    loaded.forEach((key) => next.delete(key))
+    loadingSet.value = next
+  },
+)
+
+function expandParents(key: string) {
+  if (!props.autoExpandParent) return
+  const parents = getParentKeys([key], flat.value.parentMap)
+  if (!parents.length) return
+  const next = new Set(expandedSet.value)
+  parents.forEach((parent) => next.add(parent))
+  expandedModel.update(next)
+}
+
+/* ---------- 选中 ---------- */
+function handleSelect(node: TreeNodeData, key: TreeKey, event: MouseEvent) {
+  if (props.disabled || !props.selectable) return
+  activeKey.value = String(key)
+  nodeEls.get(String(key))?.focus()
+  const current = new Set(selectedSet.value)
+  const textKey = String(key)
+  if (props.multiple && (event.ctrlKey || event.metaKey)) {
+    if (current.has(textKey)) current.delete(textKey)
+    else current.add(textKey)
+  } else if (current.has(textKey) && current.size === 1) {
+    current.clear()
+  } else {
+    current.clear()
+    current.add(textKey)
+  }
+  selectedModel.update(current)
+  expandParents(textKey)
+  emit('select', [...current], { node, selectedKeys: [...current], nativeEvent: event })
+}
+
+/* ---------- 勾选 ---------- */
+function handleCheck(node: TreeNodeData, key: TreeKey) {
+  if (props.disabled || node.disableCheckbox === true) return
+  const textKey = String(key)
+  const next = new Set(checkedExplicitSet.value)
+  const turnOn = !conductResult.value.checked.has(textKey)
+
+  if (props.checkStrictly) {
+    if (turnOn) next.add(textKey)
+    else next.delete(textKey)
+  } else {
+    // ① 先从显式集合剔除该子树，② 需要勾选时再整棵写入，
+    // ③ 祖先必须移出显式集合（否则取消子节点会被父节点残留条目级联拉回勾选）
+    collectDescendants(textKey, flat.value.childrenMap).forEach((descendant) => next.delete(descendant))
+    getParentKeys([textKey], flat.value.parentMap).forEach((ancestor) => next.delete(ancestor))
+    if (turnOn) {
+      collectDescendants(textKey, flat.value.childrenMap).forEach((descendant) => next.add(descendant))
+    }
+  }
+
+  explicitChecked.value = [...next]
+  if (props.checkedKeys !== undefined) emit('update:checkedKeys', [...next])
+
+  const result = props.checkStrictly
+    ? { checked: new Set(next), half: new Set<string>() }
+    : conductCheck(props.treeData, next, fieldNames.value)
+  emit(
+    'check',
+    { checked: [...result.checked], halfChecked: [...result.half] },
+    { node, checked: turnOn },
+  )
+  expandParents(textKey)
+}
+
+/* ---------- 拖拽 ---------- */
+const dragKey = ref<string | null>(null)
+const dropKey = ref<string | null>(null)
+const dropPosition = ref<DropPosition | null>(null)
+let internalDrag = false
+/** drop 事件里要用的落点快照（清理视觉状态前先存下来） */
+let dropSnapshot: DropPosition | null = null
+
+function resolveDragKey(dataTransfer: DataTransfer | null, event: DragEvent): string | null {
+  if (internalDrag) return dragKey.value
+  if (props.externalDragKey && dataTransfer) {
+    const key = props.externalDragKey(dataTransfer, event)
+    return key == null ? null : String(key)
+  }
+  return null
+}
+
+function isDescendant(ancestor: string, target: string): boolean {
+  return collectDescendants(ancestor, flat.value.childrenMap).includes(target)
+}
+
+function resetDragVisual() {
+  dragKey.value = null
+  dropKey.value = null
+  dropPosition.value = null
+}
+
+function onDragStart(node: TreeNodeData, key: TreeKey, event: DragEvent) {
+  internalDrag = true
+  dragKey.value = String(key)
+  event.dataTransfer?.setData('text/plain', String(key))
+  if (event.dataTransfer) event.dataTransfer.effectAllowed = 'move'
+  emit('dragstart', { node, event })
+}
+
+function onDragOver(node: TreeNodeData, key: TreeKey, event: DragEvent) {
+  const sourceKey = resolveDragKey(event.dataTransfer, event)
+  if (!sourceKey) return
+  const textKey = String(key)
+  if (sourceKey === textKey || isDescendant(sourceKey, textKey)) return
+  event.preventDefault()
+  if (event.dataTransfer) event.dataTransfer.dropEffect = 'move'
+  const rect = (event.currentTarget as HTMLElement).getBoundingClientRect()
+  const position = calcDropPosition(event.clientY, rect)
+  dropKey.value = textKey
+  dropPosition.value = position
+  emit('dragover', { node, dropPosition: position, event })
+}
+
+function onDragLeave(node: TreeNodeData, key: TreeKey, event: DragEvent) {
+  if (dropKey.value !== String(key)) return
+  dropKey.value = null
+  dropPosition.value = null
+  emit('dragleave', { node, event })
+}
+
+function onDrop(node: TreeNodeData, key: TreeKey, event: DragEvent) {
+  const sourceKey = resolveDragKey(event.dataTransfer, event)
+  event.preventDefault()
+  event.stopPropagation()
+  // 先快照落点，再清理视觉状态（否则读到的永远是 null）
+  dropSnapshot = dropPosition.value
+  const targetKey = String(key)
+  resetDragVisual()
+  if (!sourceKey || sourceKey === targetKey || !dropSnapshot) return
+  if (isDescendant(sourceKey, targetKey)) return
+  emit('drop', {
+    dragKey: sourceKey,
+    dropKey: targetKey,
+    dropPosition: dropSnapshot,
+    node,
+    event,
+  })
+  dropSnapshot = null
+}
+
+function onDragEnd(node: TreeNodeData, _key: TreeKey, event: DragEvent) {
+  resetDragVisual()
+  internalDrag = false
+  emit('dragend', { node, event })
+}
+
+function onRootDragLeave(event: DragEvent) {
+  const related = event.relatedTarget as Node | null
+  if (related && (event.currentTarget as HTMLElement).contains(related)) return
+  resetDragVisual()
+  internalDrag = false
+}
+
+function onRootDrop(event: DragEvent) {
+  // 落在空白处：不处理，清理视觉状态
+  event.preventDefault()
+  resetDragVisual()
+  internalDrag = false
+}
+
+/* ---------- 键盘导航 ---------- */
+function moveActive(delta: 1 | -1) {
+  const keys = visibleKeys.value
+  if (!keys.length) return
+  const pos = keys.indexOf(activeKey.value ?? keys[0])
+  const next = (pos + delta + keys.length) % keys.length
+  activeKey.value = keys[next]
+  nextTick(() => nodeEls.get(keys[next])?.focus())
+}
+
+function onKeydown(event: KeyboardEvent) {
+  if (props.disabled) return
+  const keys = visibleKeys.value
+  if (!keys.length) return
+  const key = activeKey.value ?? keys[0]
+  const node = nodeOf(key)
+  if (!node) return
+  switch (event.key) {
+    case 'ArrowDown':
+      event.preventDefault()
+      moveActive(1)
+      break
+    case 'ArrowUp':
+      event.preventDefault()
+      moveActive(-1)
+      break
+    case 'ArrowRight':
+      event.preventDefault()
+      if (!effectiveExpanded.value.has(key)) toggleExpand(node, key)
+      else {
+        const children = getNodeChildren(node, fieldNames.value)
+        const firstChild = children?.[0]
+        if (firstChild) {
+          const childKey = String(getNodeKey(firstChild, fieldNames.value))
+          activeKey.value = childKey
+          nextTick(() => nodeEls.get(childKey)?.focus())
+        }
+      }
+      break
+    case 'ArrowLeft': {
+      event.preventDefault()
+      if (effectiveExpanded.value.has(key)) {
+        toggleExpand(node, key)
+        break
+      }
+      const parent = flat.value.parentMap.get(key)
+      if (parent) {
+        activeKey.value = parent
+        nextTick(() => nodeEls.get(parent)?.focus())
+      }
+      break
+    }
+    case 'Enter':
+      event.preventDefault()
+      handleSelect(node, key, event as unknown as MouseEvent)
+      break
+    case ' ':
+      event.preventDefault()
+      if (props.checkable) handleCheck(node, key)
+      else handleSelect(node, key, event as unknown as MouseEvent)
+      break
+  }
+}
+
+/* ---------- 右键菜单 ---------- */
+const menuVisible = ref(false)
+const menuStyle = ref<Record<string, string>>({})
+const menuItems = ref<TreeContextMenuItem[]>([])
+const menuTarget = ref<{ node: TreeNodeData | null; key: TreeKey | null }>({ node: null, key: null })
+const menuZIndex = ref(0)
+let menuAnchor: RectLike | null = null
+
+function closeMenu() {
+  if (!menuVisible.value) return
+  menuVisible.value = false
+  if (menuZIndex.value) {
+    releaseZIndex(menuZIndex.value)
+    menuZIndex.value = 0
+  }
+  document.removeEventListener('mousedown', onDocumentMouseDown, true)
+  document.removeEventListener('keydown', onDocumentKeydown, true)
+  window.removeEventListener('scroll', closeMenu, true)
+  window.removeEventListener('resize', closeMenu)
+}
+
+function onDocumentMouseDown(event: MouseEvent) {
+  const target = event.target as Node | null
+  if (target && (target as HTMLElement).closest?.(`.${b('context-menu')}`)) return
+  closeMenu()
+}
+
+function onDocumentKeydown(event: KeyboardEvent) {
+  if (event.key === 'Escape') closeMenu()
+}
+
+function openMenu(node: TreeNodeData | null, key: TreeKey | null, event: MouseEvent) {
+  const source = props.contextMenu
+  const items =
+    typeof source === 'function' ? source(node, key) : Array.isArray(source) ? source : []
+  if (!items.length) return
+  menuItems.value = items
+  menuTarget.value = { node, key }
+  menuAnchor = {
+    left: event.clientX,
+    top: event.clientY,
+    right: event.clientX,
+    bottom: event.clientY,
+    width: 0,
+    height: 0,
+  }
+  // 菜单已开着又被打开（换目标节点）时先回收旧层级，避免档位里留下永不释放的占位
+  if (menuZIndex.value) releaseZIndex(menuZIndex.value)
+  menuZIndex.value = nextZIndex('popup')
+  menuVisible.value = true
+  nextTick(() => {
+    const el = document.querySelector<HTMLElement>(`.${b('context-menu')}`)
+    const size = { width: el?.offsetWidth ?? 160, height: el?.offsetHeight ?? 0 }
+    const { x, y } = computePosition({
+      placement: 'bottom-start',
+      triggerRect: menuAnchor as RectLike,
+      floatSize: size,
+      offset: 4,
+    })
+    menuStyle.value = { left: `${x}px`, top: `${y}px`, zIndex: String(menuZIndex.value) }
+  })
+  document.addEventListener('mousedown', onDocumentMouseDown, true)
+  document.addEventListener('keydown', onDocumentKeydown, true)
+  window.addEventListener('scroll', closeMenu, true)
+  window.addEventListener('resize', closeMenu)
+}
+
+function onNodeContextMenu(node: TreeNodeData, key: TreeKey, event: MouseEvent) {
+  event.preventDefault()
+  event.stopPropagation()
+  emit('contextmenu', { node, key, event })
+  openMenu(node, key, event)
+}
+
+function onRootContextMenu(event: MouseEvent) {
+  emit('contextmenu', { node: null, key: null, event })
+  openMenu(null, null, event)
+}
+
+function onMenuClick(item: TreeContextMenuItem, event: MouseEvent) {
+  if (item.disabled) return
+  emit('contextMenuClick', { item, node: menuTarget.value.node, key: menuTarget.value.key, event })
+  closeMenu()
+}
+
+onBeforeUnmount(() => {
+  closeMenu()
+})
+
+/* ---------- 叶子占位 ----------
+   缩进占位只对「同一批兄弟里存在可展开节点」的叶子有意义：整层都是叶子时
+   再空出一块就是白占位置（右键菜单示例里两个节点都没有子节点，却各留一格）。
+   懒加载下「未加载过」的节点算可展开，占位保留 —— 展开后那里要放箭头。 */
+const placeholderLeaves = computed(() => {
+  const set = new Set<string>()
+  const leafOptions = { lazy: props.lazy, loadedSet: loadedModel.set.value }
+  const walk = (nodes: TreeNodeData[]) => {
+    const hasExpandable = nodes.some((node) => !isLeafNode(node, fieldNames.value, leafOptions))
+    for (const node of nodes) {
+      if (hasExpandable && isLeafNode(node, fieldNames.value, leafOptions)) {
+        set.add(String(getNodeKey(node, fieldNames.value)))
+      }
+      const children = getNodeChildren(node, fieldNames.value)
+      if (children) walk(children)
+    }
+  }
+  walk(props.treeData)
+  return set
+})
+
+/* ---------- 上下文 ----------
+   用 getter 暴露响应式值：读取发生在消费方（TreeNode 的渲染 / computed）的
+   响应式作用域里，因此依赖能被正确收集，不需要额外包一层 reactive。 */
+const treeContext: TreeContext = {
+  get fieldNames() {
+    return fieldNames.value
+  },
+  get checkable() {
+    return props.checkable
+  },
+  get selectable() {
+    return props.selectable
+  },
+  get multiple() {
+    return props.multiple
+  },
+  get checkStrictly() {
+    return props.checkStrictly
+  },
+  get disabled() {
+    return props.disabled
+  },
+  get lazy() {
+    return props.lazy
+  },
+  get draggable() {
+    return props.draggable
+  },
+  get blockNode() {
+    return props.blockNode
+  },
+  get expandedSet() {
+    return effectiveExpanded.value
+  },
+  get selectedSet() {
+    return selectedSet.value
+  },
+  get placeholderKeys() {
+    return placeholderLeaves.value
+  },
+  get checkedSet() {
+    return conductResult.value.checked
+  },
+  get halfSet() {
+    return conductResult.value.half
+  },
+  get loadedSet() {
+    return loadedModel.set.value
+  },
+  get loadingSet() {
+    return loadingSet.value
+  },
+  get filterActive() {
+    return filterActive.value
+  },
+  get filterVisible() {
+    return filterActive.value ? filterInfo.value.matched : null
+  },
+  get filterKeyword() {
+    return props.filter
+  },
+  get activeKey() {
+    return activeKey.value
+  },
+  get dragKey() {
+    return dragKey.value
+  },
+  get dropKey() {
+    return dropKey.value
+  },
+  get dropPosition() {
+    return dropPosition.value
+  },
+  toggleExpand,
+  handleSelect,
+  handleCheck,
+  onDragStart,
+  onDragOver,
+  onDragLeave,
+  onDrop,
+  onDragEnd,
+  onNodeContextMenu,
+  registerNode,
+  unregisterNode,
+  isActive: (key: string) => activeKey.value === key,
+}
+
+provide(treeContextKey, treeContext)
+
+/** 渲染函数组件：把 VNode 形态的菜单图标原样渲染 */
+const VNodeRenderer = (renderProps: { node: VNode }) => renderProps.node
+</script>
+
+<template>
+  <div
+    :class="[b(), { [is('disabled')]: disabled }]"
+    role="tree"
+    :aria-multiselectable="multiple || undefined"
+    @keydown="onKeydown"
+    @dragleave="onRootDragLeave"
+    @dragover.prevent
+    @drop="onRootDrop"
+    @contextmenu="onRootContextMenu"
+  >
+    <template v-if="treeData.length">
+      <G3TreeNode
+        v-for="node in treeData"
+        :key="String(getNodeKey(node, fieldNames))"
+        :node="node"
+        :level="0"
+      >
+        <template v-if="$slots.title" #title="scope">
+          <slot name="title" v-bind="scope" />
+        </template>
+      </G3TreeNode>
+    </template>
+    <div v-else :class="e('empty')">
+      <slot name="empty">{{ locale.empty.description }}</slot>
+    </div>
+
+    <Teleport :to="teleportTo">
+      <Transition name="g3-popover">
+        <div v-if="menuVisible" :class="e('context-menu')" :style="menuStyle" role="menu">
+          <template v-for="(item, index) in menuItems" :key="item.key ?? index">
+            <div v-if="item.divider" :class="e('context-menu-divider')" role="separator" />
+            <button
+              v-else
+              type="button"
+              :class="[
+                e('context-menu-item'),
+                {
+                  [is('context-menu-item-danger')]: item.danger,
+                  [is('context-menu-item-disabled')]: item.disabled,
+                },
+              ]"
+              role="menuitem"
+              :disabled="item.disabled"
+              @click="onMenuClick(item, $event)"
+            >
+              <span v-if="item.icon" :class="e('context-menu-icon')">
+                <component :is="item.icon" v-if="!isVNode(item.icon)" />
+                <VNodeRenderer v-else :node="item.icon" />
+              </span>
+              <span>{{ item.label }}</span>
+            </button>
+          </template>
+        </div>
+      </Transition>
+    </Teleport>
+  </div>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+.#{b('tree')} {
+  position: relative;
+  width: 100%;
+  outline: none;
+}
+
+.#{e('tree', 'empty')} {
+  padding: v('space-6', 32px) 0;
+  color: v('text-3', rgba(0, 0, 0, 0.45));
+  font-size: v('font-size', 14px);
+  text-align: center;
+}
+
+/* ---------- 右键菜单 ---------- */
+.#{e('tree', 'context-menu')} {
+  position: fixed;
+  display: flex;
+  flex-direction: column;
+  min-width: v('dropdown-min-width', 180px);
+  padding: v('space-1', 4px);
+  border: 1px solid v('border-color', #d9d9d9);
+  border-radius: v('radius', 6px);
+  background: v('bg-container', #fff);
+  box-shadow: v('shadow-popup', 0 6px 16px rgba(0, 0, 0, 0.12));
+}
+
+.#{e('tree', 'context-menu-item')} {
+  display: flex;
+  align-items: center;
+  gap: v('space-2', 8px);
+  padding: v('dropdown-item-padding-y', 5px) v('dropdown-item-padding-x', 8px);
+  border: 0;
+  border-radius: v('dropdown-item-radius', 4px);
+  background: transparent;
+  color: v('text-1', rgba(0, 0, 0, 0.88));
+  font-family: inherit;
+  font-size: v('font-size', 14px);
+  text-align: left;
+  cursor: pointer;
+  transition: background-color v('duration-fast', 0.1s) v('ease', ease);
+}
+
+.#{e('tree', 'context-menu-item')}:hover:not(:disabled) {
+  background: v('fill', rgba(0, 0, 0, 0.04));
+}
+
+.#{e('tree', 'context-menu-item')}.#{is('context-menu-item-danger')} {
+  color: v('color-danger', #ec4246);
+}
+
+.#{e('tree', 'context-menu-item')}.#{is('context-menu-item-disabled')} {
+  color: v('text-disabled', rgba(0, 0, 0, 0.25));
+  cursor: not-allowed;
+}
+
+.#{e('tree', 'context-menu-icon')} {
+  display: inline-flex;
+
+  svg {
+    width: 1em;
+    height: 1em;
+  }
+}
+
+.#{e('tree', 'context-menu-divider')} {
+  height: 1px;
+  margin: v('dropdown-divider-margin', 4px 0);
+  background: v('border-color', #d9d9d9);
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/tree/TreeNode.vue b/code/g3soft-libs/packages/ui/src/tree/TreeNode.vue
new file mode 100644
index 00000000..14f9ee85
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/tree/TreeNode.vue
@@ -0,0 +1,422 @@
+<script setup lang="ts">
+import { computed, inject, isVNode, onBeforeUnmount, ref, type VNode } from 'vue'
+import { ChevronRight, LoaderCircle } from '@lucide/vue'
+import { useNamespace } from '../_composables/useNamespace'
+import G3Checkbox from '../checkbox/Checkbox.vue'
+import { treeContextKey } from './context'
+import type { TreeNodeData } from './types'
+import { getNodeChildren, getNodeKey, getNodeTitle, isLeafNode } from './utils'
+
+/**
+ * 树节点（内部递归组件）—— 单节点的展开、选中、勾选与拖拽落点渲染。
+ */
+defineOptions({ name: 'G3TreeNode' })
+
+const props = withDefaults(
+  defineProps<{
+    /** 节点数据 */
+    node: TreeNodeData
+    /** 层级（用于缩进计算） */
+    level?: number
+  }>(),
+  { level: 0 },
+)
+
+const { b, e, is } = useNamespace('tree-node')
+const tree = inject(treeContextKey)
+
+const nodeKey = computed(() => String(getNodeKey(props.node, tree!.fieldNames)))
+const title = computed(() => getNodeTitle(props.node, tree!.fieldNames))
+const children = computed(() => getNodeChildren(props.node, tree!.fieldNames))
+const leaf = computed(() =>
+  isLeafNode(props.node, tree!.fieldNames, { lazy: tree!.lazy, loadedSet: tree!.loadedSet }),
+)
+const disabled = computed(() => tree!.disabled || props.node.disabled === true)
+const expanded = computed(() => tree!.expandedSet.has(nodeKey.value))
+const selected = computed(() => tree!.selectedSet.has(nodeKey.value))
+const checked = computed(() => tree!.checkedSet.has(nodeKey.value))
+const halfChecked = computed(() => tree!.halfSet.has(nodeKey.value))
+const loading = computed(() => tree!.loadingSet.has(nodeKey.value))
+
+/** 过滤未命中的节点整体不渲染（不影响数据，只影响可见性） */
+const visible = computed(
+  () => !tree!.filterActive || !tree!.filterVisible || tree!.filterVisible.has(nodeKey.value),
+)
+
+const dropPosition = computed(() =>
+  tree!.dropKey === nodeKey.value && tree!.dragKey !== nodeKey.value ? tree!.dropPosition : null,
+)
+
+const classes = computed(() => [
+  b(),
+  {
+    [is('expanded')]: expanded.value,
+    [is('leaf')]: leaf.value,
+    [is('selected')]: selected.value,
+    [is('disabled')]: disabled.value,
+    [is('block')]: tree!.blockNode,
+    [is('dragging')]: tree!.dragKey === nodeKey.value,
+    [is('drop-before')]: dropPosition.value === 'before',
+    [is('drop-after')]: dropPosition.value === 'after',
+    [is('drop-inside')]: dropPosition.value === 'inside',
+  },
+])
+
+/** 缩进用 CSS 变量 + calc 表达，避免每层嵌套 padding 叠加 */
+const nodeStyle = computed(() => ({ '--g3-tree-level': String(props.level) }))
+
+/** 标题分段：命中关键词的首处高亮（用 #title 插槽时不做处理） */
+const titleParts = computed(() => {
+  const text = title.value
+  if (!tree!.filterActive || !tree!.filterKeyword) return [{ text, hit: false }]
+  const index = text.toLowerCase().indexOf(tree!.filterKeyword.toLowerCase())
+  if (index === -1) return [{ text, hit: false }]
+  return [
+    { text: text.slice(0, index), hit: false },
+    { text: text.slice(index, index + tree!.filterKeyword.length), hit: true },
+    { text: text.slice(index + tree!.filterKeyword.length), hit: false },
+  ]
+})
+
+function onRowClick(event: MouseEvent) {
+  if (disabled.value) return
+  tree!.handleSelect(props.node, nodeKey.value, event)
+}
+
+function onDragStart(event: DragEvent) {
+  if (disabled.value || props.node.draggable === false || !dragArmed.value) {
+    event.preventDefault()
+    return
+  }
+  tree!.onDragStart(props.node, nodeKey.value, event)
+}
+
+function onRowDragEnd(event: DragEvent) {
+  tree!.onDragEnd(props.node, nodeKey.value, event)
+  disarmDrag()
+}
+
+/* ---------- 拖拽的「长按武装」 ----------
+   原生 draggable 一旦为 true 就是「按下即拖」：鼠标一点微动就进入拖拽，
+   dragstart / dragover 反复触发，落点指示线来回跳。改为按住 400ms 且位移
+   不超过 6px 才武装 draggable，与 fms 一致，拖起来才稳。 */
+const HOLD_DELAY_MS = 400
+const HOLD_SLOP_PX = 6
+const dragArmed = ref(false)
+
+/** 只有武装后才允许拖拽，其余时间行上不带 draggable 属性 */
+const draggableAttr = computed(() =>
+  tree!.draggable && !disabled.value && props.node.draggable !== false && dragArmed.value
+    ? 'true'
+    : undefined,
+)
+
+let holdTimer: number | null = null
+let holdOrigin: { x: number; y: number } | null = null
+
+function clearHold() {
+  if (holdTimer != null) {
+    window.clearTimeout(holdTimer)
+    holdTimer = null
+  }
+  holdOrigin = null
+}
+
+function disarmDrag() {
+  clearHold()
+  dragArmed.value = false
+}
+
+/** 位移超过容差就判定为「不是想拖拽」，取消本次武装 */
+function onHoldMove(event: MouseEvent) {
+  if (!holdOrigin) return
+  const dx = event.clientX - holdOrigin.x
+  const dy = event.clientY - holdOrigin.y
+  if (dx * dx + dy * dy > HOLD_SLOP_PX * HOLD_SLOP_PX) clearHold()
+}
+
+function onRowMouseDown(event: MouseEvent) {
+  if (!tree!.draggable || disabled.value || props.node.draggable === false) return
+  if (event.button !== 0) return
+  // 展开箭头与复选框上的按下不参与拖拽（它们各有自己的点击语义）
+  const target = event.target as HTMLElement | null
+  if (target?.closest(`.${e('switcher')}, .${e('checkbox')}`)) return
+
+  clearHold()
+  holdOrigin = { x: event.clientX, y: event.clientY }
+  holdTimer = window.setTimeout(() => {
+    holdTimer = null
+    dragArmed.value = true
+  }, HOLD_DELAY_MS)
+  window.addEventListener('mousemove', onHoldMove)
+  window.addEventListener('mouseup', disarmDrag, { once: true })
+}
+
+onBeforeUnmount(() => {
+  clearHold()
+  window.removeEventListener('mousemove', onHoldMove)
+  window.removeEventListener('mouseup', disarmDrag)
+})
+
+function setRowRef(el: unknown) {
+  const target = el as HTMLElement | null
+  if (target) tree!.registerNode(nodeKey.value, target)
+  else tree!.unregisterNode(nodeKey.value)
+}
+
+/** 渲染函数组件：把 VNode 形态的图标原样渲染 */
+const VNodeRenderer = (renderProps: { node: VNode }) => renderProps.node
+</script>
+
+<template>
+  <div v-if="visible" :class="e('wrapper')">
+    <div
+      :ref="setRowRef"
+      :class="classes"
+      :style="nodeStyle"
+      role="treeitem"
+      :aria-expanded="leaf ? undefined : expanded"
+      :aria-selected="tree!.selectable ? selected : undefined"
+      :aria-disabled="disabled || undefined"
+      :tabindex="tree!.isActive(nodeKey) ? 0 : -1"
+      :draggable="draggableAttr"
+      @click="onRowClick"
+      @dblclick="!disabled && !leaf && tree!.toggleExpand(node, nodeKey)"
+      @mousedown="onRowMouseDown"
+      @dragstart="onDragStart"
+      @dragover="tree!.onDragOver(node, nodeKey, $event)"
+      @dragleave="tree!.onDragLeave(node, nodeKey, $event)"
+      @drop="tree!.onDrop(node, nodeKey, $event)"
+      @dragend="onRowDragEnd"
+      @contextmenu="tree!.onNodeContextMenu(node, nodeKey, $event)"
+    >
+      <!-- 叶子只在「同层兄弟里有可展开节点」时留等宽占位（对齐箭头）；
+           整层都是叶子时不再空出一块 -->
+      <span
+        v-if="!leaf || tree!.placeholderKeys.has(nodeKey)"
+        :class="[e('switcher'), { [is('placeholder')]: leaf }]"
+        @click.stop="!disabled && !leaf && tree!.toggleExpand(node, nodeKey)"
+      >
+        <LoaderCircle v-if="loading" :class="e('spinner')" aria-hidden="true" />
+        <ChevronRight
+          v-else-if="!leaf"
+          :class="[e('switcher-icon'), { [is('open')]: expanded }]"
+          aria-hidden="true"
+        />
+      </span>
+
+      <span v-if="tree!.checkable" :class="e('checkbox')" @click.stop>
+        <G3Checkbox
+          :model-value="checked"
+          :indeterminate="halfChecked"
+          :disabled="disabled || node.disableCheckbox === true"
+          @change="tree!.handleCheck(node, nodeKey)"
+        />
+      </span>
+
+      <span :class="[e('content'), { [is('block')]: tree!.blockNode }]">
+        <span v-if="node.icon" :class="e('icon')">
+          <component :is="node.icon" v-if="!isVNode(node.icon)" />
+          <VNodeRenderer v-else :node="node.icon" />
+        </span>
+        <slot name="title" :node="node" :expanded="expanded" :selected="selected">
+          <span :class="e('title')">
+            <span
+              v-for="(part, index) in titleParts"
+              :key="index"
+              :class="part.hit ? e('highlight') : undefined"
+            >{{ part.text }}</span>
+          </span>
+        </slot>
+      </span>
+    </div>
+
+    <Transition name="g3-tree-children">
+      <div v-if="!leaf && expanded && children" :class="e('children')">
+        <div :class="e('children-inner')">
+          <G3TreeNode
+            v-for="child in children"
+            :key="String(getNodeKey(child, tree!.fieldNames))"
+            :node="child"
+            :level="level + 1"
+          />
+        </div>
+      </div>
+    </Transition>
+  </div>
+</template>
+
+<style lang="scss">
+@use '@g3soft/tokens/scss' as *;
+
+/* 节点行 */
+.#{b('tree-node')} {
+  position: relative;
+  display: flex;
+  align-items: center;
+  gap: v('space-1', 4px);
+  box-sizing: border-box;
+  min-height: v('tree-node-height', 32px);
+  /* 缩进 = 基础留白 + 每层缩进量 × 层级（层级由行内 CSS 变量下发） */
+  padding-left: calc(
+    #{v('tree-gutter-x', 4px)} + #{v('tree-indent', 18px)} * var(--g3-tree-level, 0)
+  );
+  padding-right: v('tree-gutter-x', 4px);
+  border-radius: v('radius-sm', 4px);
+  color: v('text-1', rgba(0, 0, 0, 0.88));
+  font-size: v('font-size', 14px);
+  line-height: v('line-height', 1.5);
+  cursor: pointer;
+  outline: none;
+  user-select: none;
+  transition: background-color v('duration-fast', 0.1s) v('ease', ease);
+}
+
+.#{b('tree-node')}:hover {
+  background: v('fill', rgba(0, 0, 0, 0.04));
+}
+
+.#{b('tree-node')}:focus-visible {
+  @include focus-ring();
+}
+
+.#{b('tree-node')}.#{is('selected')},
+.#{b('tree-node')}.#{is('selected')}:hover {
+  background: v('color-primary-soft', rgba(24, 24, 27, 0.12));
+}
+
+.#{b('tree-node')}.#{is('disabled')} {
+  color: v('text-disabled', rgba(0, 0, 0, 0.25));
+  cursor: not-allowed;
+}
+
+.#{b('tree-node')}.#{is('disabled')}:hover {
+  background: transparent;
+}
+
+.#{b('tree-node')}.#{is('dragging')} {
+  opacity: 0.5;
+}
+
+/* 落点指示：before / after 画 2px 线，inside 用主色淡底 */
+.#{b('tree-node')}.#{is('drop-before')}::before,
+.#{b('tree-node')}.#{is('drop-after')}::after {
+  content: '';
+  position: absolute;
+  left: calc(#{v('tree-gutter-x', 4px)} + #{v('tree-indent', 18px)} * var(--g3-tree-level, 0));
+  right: 0;
+  height: v('tree-drop-line-size', 2px);
+  background: v('color-primary', #18181b);
+}
+
+.#{b('tree-node')}.#{is('drop-before')}::before {
+  top: -1px;
+}
+
+.#{b('tree-node')}.#{is('drop-after')}::after {
+  bottom: -1px;
+}
+
+.#{b('tree-node')}.#{is('drop-inside')} {
+  background: v('color-primary-soft', rgba(24, 24, 27, 0.12));
+}
+
+/* 展开箭头 */
+.#{e('tree-node', 'switcher')} {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  width: v('tree-switcher-size', 22px);
+  height: v('tree-switcher-size', 22px);
+  border-radius: v('radius-sm', 4px);
+  color: v('text-3', rgba(0, 0, 0, 0.45));
+}
+
+.#{e('tree-node', 'switcher')}:hover:not(.#{is('placeholder')}) {
+  background: v('fill-hover', rgba(0, 0, 0, 0.08));
+}
+
+.#{e('tree-node', 'switcher-icon')} {
+  width: v('tree-icon-size', 16px);
+  height: v('tree-icon-size', 16px);
+  transition: transform v('duration', 0.2s) v('ease', ease);
+}
+
+.#{e('tree-node', 'switcher-icon')}.#{is('open')} {
+  transform: rotate(90deg);
+}
+
+.#{e('tree-node', 'spinner')} {
+  width: v('tree-icon-size', 16px);
+  height: v('tree-icon-size', 16px);
+  animation: g3-tree-spin 0.8s linear infinite;
+}
+
+@keyframes g3-tree-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+.#{e('tree-node', 'checkbox')} {
+  display: inline-flex;
+  flex-shrink: 0;
+}
+
+/* 节点内容 */
+.#{e('tree-node', 'content')} {
+  display: inline-flex;
+  align-items: center;
+  gap: v('space-1', 4px);
+  min-width: 0;
+  padding: 0 v('tree-title-padding-x', 6px);
+}
+
+.#{e('tree-node', 'content')}.#{is('block')} {
+  flex: 1;
+}
+
+.#{e('tree-node', 'icon')} {
+  display: inline-flex;
+  flex-shrink: 0;
+  color: v('text-2', rgba(0, 0, 0, 0.65));
+
+  svg {
+    width: v('tree-icon-size', 16px);
+    height: v('tree-icon-size', 16px);
+  }
+}
+
+.#{e('tree-node', 'title')} {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.#{e('tree-node', 'highlight')} {
+  color: v('color-danger', #ec4246);
+  font-weight: 600;
+}
+
+/* 子树：grid 行高动画（height: auto 不可动画） */
+.#{e('tree-node', 'children')} {
+  display: grid;
+  grid-template-rows: 1fr;
+  overflow: hidden;
+}
+
+.g3-tree-children-enter-from,
+.g3-tree-children-leave-to {
+  grid-template-rows: 0fr;
+}
+
+.g3-tree-children-enter-active,
+.g3-tree-children-leave-active {
+  transition: grid-template-rows v('duration', 0.2s) v('ease', ease);
+}
+
+.#{e('tree-node', 'children-inner')} {
+  min-height: 0;
+}
+</style>
diff --git a/code/g3soft-libs/packages/ui/src/tree/context.ts b/code/g3soft-libs/packages/ui/src/tree/context.ts
new file mode 100644
index 00000000..83c0cf52
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/tree/context.ts
@@ -0,0 +1,5 @@
+import type { InjectionKey } from 'vue'
+import type { TreeContext } from './types'
+
+/** Tree 通过 provide 下发的节点上下文，由 G3TreeNode 消费 */
+export const treeContextKey: InjectionKey<TreeContext> = Symbol('g3-tree')
diff --git a/code/g3soft-libs/packages/ui/src/tree/index.ts b/code/g3soft-libs/packages/ui/src/tree/index.ts
new file mode 100644
index 00000000..bc8a2e21
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/tree/index.ts
@@ -0,0 +1,24 @@
+export { default as G3Tree } from './Tree.vue'
+export { default as G3TreeNode } from './TreeNode.vue'
+export { treeContextKey } from './context'
+export type {
+  DropPosition,
+  TreeCheckPayload,
+  TreeContext,
+  TreeContextMenuItem,
+  TreeDropInfo,
+  TreeFieldNames,
+  TreeKey,
+  TreeNodeData,
+  TreeProps,
+} from './types'
+export {
+  buildFlat,
+  calcDropPosition,
+  collectDescendants,
+  conductCheck,
+  filterTree,
+  getParentKeys,
+  isLeafNode,
+  resolveFieldNames,
+} from './utils'
diff --git a/code/g3soft-libs/packages/ui/src/tree/types.ts b/code/g3soft-libs/packages/ui/src/tree/types.ts
new file mode 100644
index 00000000..514603ca
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/tree/types.ts
@@ -0,0 +1,156 @@
+import type { Component, VNode } from 'vue'
+
+/** 树节点标识 */
+export type TreeKey = string | number
+
+/** 落点位置：节点前 / 节点内 / 节点后 */
+export type DropPosition = 'before' | 'inside' | 'after'
+
+/** 字段名映射 */
+export interface TreeFieldNames {
+  /** 唯一标识字段，默认 key */
+  key?: string
+  /** 标题字段，默认 title */
+  title?: string
+  /** 子节点字段，默认 children */
+  children?: string
+  /** 图标字段，默认 icon */
+  icon?: string
+}
+
+/** 节点数据 */
+export interface TreeNodeData {
+  /** 唯一标识 */
+  key?: TreeKey
+  /** 标题 */
+  title?: string
+  /** 子节点 */
+  children?: TreeNodeData[]
+  /** 节点图标（组件或 VNode） */
+  icon?: Component | VNode
+  /** 是否禁用该节点 */
+  disabled?: boolean
+  /** 是否禁用该节点的复选框 */
+  disableCheckbox?: boolean
+  /** 是否允许拖动该节点 */
+  draggable?: boolean
+  /** 是否叶子节点（懒加载模式下用于判断是否还要请求子节点） */
+  isLeaf?: boolean
+  [field: string]: unknown
+}
+
+/** 右键菜单项 */
+export interface TreeContextMenuItem {
+  key: string | number
+  label?: string
+  icon?: Component | VNode
+  disabled?: boolean
+  danger?: boolean
+  divider?: boolean
+}
+
+/** 落点信息 */
+export interface TreeDropInfo {
+  dragKey: TreeKey
+  dropKey: TreeKey
+  dropPosition: DropPosition
+  node: TreeNodeData
+  event: DragEvent
+}
+
+/** 勾选事件的载荷 */
+export interface TreeCheckPayload {
+  checked: TreeKey[]
+  halfChecked: TreeKey[]
+}
+
+export interface TreeProps {
+  /** 树数据（嵌套结构） */
+  treeData?: TreeNodeData[]
+  /** 字段名映射 */
+  fieldNames?: TreeFieldNames
+  /** 显示复选框 */
+  checkable?: boolean
+  /** 允许选中（false 时行点击不选中） */
+  selectable?: boolean
+  /** 多选：Ctrl / Cmd + 点击切换，普通点击单选替换 */
+  multiple?: boolean
+  /** 勾选严格模式，父子不联动 */
+  checkStrictly?: boolean
+  /** 整树禁用 */
+  disabled?: boolean
+  /** 异步加载模式；首次展开未加载节点时 emit load */
+  lazy?: boolean
+  /** 允许拖拽排序 */
+  draggable?: boolean
+  /** 把树外拖入源映射成拖拽键，返回 null 表示不识别 */
+  externalDragKey?: (dataTransfer: DataTransfer, event: DragEvent) => TreeKey | null
+  /** 过滤关键词（大小写不敏感匹配标题），命中节点与其祖先可见并高亮 */
+  filter?: string
+  /** 节点占满整行宽度 */
+  blockNode?: boolean
+  /** 初始展开全部（仅非受控初始化时生效） */
+  defaultExpandAll?: boolean
+  /** 初始补全 defaultExpandedKeys 的祖先路径 */
+  defaultExpandParent?: boolean
+  /** 选中 / 勾选后自动展开其祖先路径 */
+  autoExpandParent?: boolean
+  /** 右键菜单数据源：数组，或 (node, key) => items（node 为 null 表示空白处） */
+  contextMenu?: TreeContextMenuItem[] | ((node: TreeNodeData | null, key: TreeKey | null) => TreeContextMenuItem[])
+  /** 受控展开键（undefined 即非受控） */
+  expandedKeys?: TreeKey[]
+  /** 受控选中键 */
+  selectedKeys?: TreeKey[]
+  /** 受控勾选键；也接受 { checked: [] } 形态 */
+  checkedKeys?: TreeKey[] | { checked: TreeKey[] }
+  /** 受控已加载键（懒加载用） */
+  loadedKeys?: TreeKey[]
+  /** 非受控初始展开键 */
+  defaultExpandedKeys?: TreeKey[]
+  /** 非受控初始选中键 */
+  defaultSelectedKeys?: TreeKey[]
+  /** 非受控初始勾选键 */
+  defaultCheckedKeys?: TreeKey[]
+  /** 非受控初始已加载键 */
+  defaultLoadedKeys?: TreeKey[]
+}
+
+/** 节点级上下文（Tree 通过 provide 下发，TreeNode 消费） */
+export interface TreeContext {
+  fieldNames: Required<TreeFieldNames>
+  checkable: boolean
+  selectable: boolean
+  multiple: boolean
+  checkStrictly: boolean
+  disabled: boolean
+  lazy: boolean
+  draggable: boolean
+  blockNode: boolean
+  expandedSet: Set<string>
+  selectedSet: Set<string>
+  /** 需要渲染缩进占位的叶子节点：同一批兄弟里存在可展开节点时才留位对齐 */
+  placeholderKeys: Set<string>
+  checkedSet: Set<string>
+  halfSet: Set<string>
+  loadedSet: Set<string>
+  loadingSet: Set<string>
+  filterActive: boolean
+  filterVisible: Set<string> | null
+  filterKeyword: string
+  activeKey: string | null
+  dragKey: string | null
+  dropKey: string | null
+  dropPosition: DropPosition | null
+  toggleExpand: (node: TreeNodeData, key: TreeKey) => void
+  handleSelect: (node: TreeNodeData, key: TreeKey, event: MouseEvent) => void
+  handleCheck: (node: TreeNodeData, key: TreeKey) => void
+  onDragStart: (node: TreeNodeData, key: TreeKey, event: DragEvent) => void
+  onDragOver: (node: TreeNodeData, key: TreeKey, event: DragEvent) => void
+  onDragLeave: (node: TreeNodeData, key: TreeKey, event: DragEvent) => void
+  onDrop: (node: TreeNodeData, key: TreeKey, event: DragEvent) => void
+  onDragEnd: (node: TreeNodeData, key: TreeKey, event: DragEvent) => void
+  onNodeContextMenu: (node: TreeNodeData, key: TreeKey, event: MouseEvent) => void
+  registerNode: (key: string, el: HTMLElement | null) => void
+  unregisterNode: (key: string) => void
+  isActive: (key: string) => boolean
+}
diff --git a/code/g3soft-libs/packages/ui/src/tree/utils.test.ts b/code/g3soft-libs/packages/ui/src/tree/utils.test.ts
new file mode 100644
index 00000000..7d65bd69
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/tree/utils.test.ts
@@ -0,0 +1,173 @@
+import { describe, expect, it } from 'vitest'
+import type { TreeNodeData } from './types'
+import {
+  buildFlat,
+  calcDropPosition,
+  collectDescendants,
+  conductCheck,
+  filterTree,
+  getParentKeys,
+  isLeafNode,
+  resolveFieldNames,
+} from './utils'
+
+const FIELD_NAMES = resolveFieldNames()
+
+const TREE: TreeNodeData[] = [
+  {
+    key: '1',
+    title: '前端',
+    children: [
+      { key: '1-1', title: 'Vue', children: [{ key: '1-1-1', title: '组合式 API' }] },
+      { key: '1-2', title: 'React' },
+    ],
+  },
+  { key: '2', title: '后端', children: [{ key: '2-1', title: 'Node.js' }] },
+]
+
+describe('resolveFieldNames', () => {
+  it('默认 key / title / children / icon，可局部覆盖', () => {
+    expect(FIELD_NAMES).toEqual({ key: 'key', title: 'title', children: 'children', icon: 'icon' })
+    expect(resolveFieldNames({ title: 'name' })).toEqual({
+      key: 'key',
+      title: 'name',
+      children: 'children',
+      icon: 'icon',
+    })
+  })
+})
+
+describe('buildFlat', () => {
+  const flat = buildFlat(TREE, FIELD_NAMES)
+
+  it('层级表按 DFS 深度记录', () => {
+    expect(flat.levelMap.get('1')).toBe(0)
+    expect(flat.levelMap.get('1-1')).toBe(1)
+    expect(flat.levelMap.get('1-1-1')).toBe(2)
+    expect(flat.levelMap.get('2-1')).toBe(1)
+  })
+
+  it('父键表与根键列表', () => {
+    expect(flat.parentMap.get('1')).toBeNull()
+    expect(flat.parentMap.get('1-1-1')).toBe('1-1')
+    expect(flat.rootKeys).toEqual(['1', '2'])
+  })
+
+  it('子键表与节点表', () => {
+    expect(flat.childrenMap.get('1')).toEqual(['1-1', '1-2'])
+    expect(flat.childrenMap.get('1-2')).toEqual([])
+    expect(flat.nodeMap.get('2-1')?.title).toBe('Node.js')
+  })
+})
+
+describe('collectDescendants / getParentKeys', () => {
+  const flat = buildFlat(TREE, FIELD_NAMES)
+
+  it('含自身在内的全部子孙', () => {
+    const keys = new Set(collectDescendants('1', flat.childrenMap))
+    expect(keys).toEqual(new Set(['1', '1-1', '1-1-1', '1-2']))
+    expect(collectDescendants('2-1', flat.childrenMap)).toEqual(['2-1'])
+  })
+
+  it('回溯祖先且不含自身、不重复', () => {
+    expect(getParentKeys(['1-1-1'], flat.parentMap)).toEqual(['1-1', '1'])
+    expect(getParentKeys(['1-1-1', '1-2'], flat.parentMap)).toEqual(['1-1', '1'])
+    expect(getParentKeys(['1'], flat.parentMap)).toEqual([])
+  })
+})
+
+describe('conductCheck（父子勾选联动）', () => {
+  it('勾选父节点：子孙全部选中，且不产生半选', () => {
+    const { checked, half } = conductCheck(TREE, ['1'], FIELD_NAMES)
+    expect(checked).toEqual(new Set(['1', '1-1', '1-1-1', '1-2']))
+    expect(half.size).toBe(0)
+  })
+
+  it('只勾选部分子节点：父节点变半选，且半选不出现在选中集合里', () => {
+    const { checked, half } = conductCheck(TREE, ['1-1'], FIELD_NAMES)
+    expect(checked).toEqual(new Set(['1-1', '1-1-1']))
+    expect(half).toEqual(new Set(['1']))
+    half.forEach((key) => expect(checked.has(key)).toBe(false))
+  })
+
+  it('子节点全部勾选后父节点转为选中', () => {
+    const { checked, half } = conductCheck(TREE, ['1-1', '1-2'], FIELD_NAMES)
+    expect(checked).toEqual(new Set(['1', '1-1', '1-1-1', '1-2']))
+    expect(half.size).toBe(0)
+  })
+
+  it('父节点只有一个子节点时，勾选该子节点会让父节点转为选中而非半选', () => {
+    const { checked, half } = conductCheck(TREE, ['2-1'], FIELD_NAMES)
+    expect(checked).toEqual(new Set(['2-1', '2']))
+    expect(half.size).toBe(0)
+  })
+
+  it('跨子树勾选互不影响', () => {
+    const { checked, half } = conductCheck(TREE, ['1-1', '2-1'], FIELD_NAMES)
+    expect(checked).toEqual(new Set(['1-1', '1-1-1', '2-1', '2']))
+    expect(half).toEqual(new Set(['1']))
+  })
+
+  it('空集合时无选中无半选', () => {
+    const { checked, half } = conductCheck(TREE, [], FIELD_NAMES)
+    expect(checked.size).toBe(0)
+    expect(half.size).toBe(0)
+  })
+})
+
+describe('filterTree（过滤：命中节点 ∪ 祖先）', () => {
+  it('命中叶子时把祖先链一起带出，并标记需要展开的祖先', () => {
+    const { matched, expand } = filterTree(TREE, 'vue', FIELD_NAMES)
+    expect(matched).toEqual(new Set(['1-1', '1']))
+    expect(expand).toEqual(new Set(['1']))
+  })
+
+  it('大小写不敏感、忽略首尾空白', () => {
+    expect(filterTree(TREE, '  NODE  ', FIELD_NAMES).matched).toEqual(new Set(['2-1', '2']))
+  })
+
+  it('关键词为空时返回空集合（不隐藏任何节点）', () => {
+    const { matched, expand } = filterTree(TREE, '   ', FIELD_NAMES)
+    expect(matched.size).toBe(0)
+    expect(expand.size).toBe(0)
+  })
+
+  it('命中父节点时其自身可见', () => {
+    const { matched } = filterTree(TREE, '前端', FIELD_NAMES)
+    expect(matched).toEqual(new Set(['1']))
+  })
+})
+
+describe('calcDropPosition（落点：上 25% 前 / 下 25% 后 / 中间放入）', () => {
+  const rect = { top: 100, height: 40 } as DOMRect
+
+  it('上四分之一判前', () => {
+    expect(calcDropPosition(105, rect)).toBe('before')
+  })
+
+  it('中间判放入内部', () => {
+    expect(calcDropPosition(120, rect)).toBe('inside')
+  })
+
+  it('下四分之一判后', () => {
+    expect(calcDropPosition(140, rect)).toBe('after')
+  })
+})
+
+describe('isLeafNode', () => {
+  it('显式 isLeaf 优先级最高', () => {
+    expect(isLeafNode({ isLeaf: true, children: [{}] }, FIELD_NAMES, { lazy: false, loadedSet: new Set() })).toBe(true)
+    expect(isLeafNode({ isLeaf: false }, FIELD_NAMES, { lazy: false, loadedSet: new Set() })).toBe(false)
+  })
+
+  it('有子节点即非叶子；无子节点即叶子', () => {
+    expect(isLeafNode(TREE[0], FIELD_NAMES, { lazy: false, loadedSet: new Set() })).toBe(false)
+    expect(isLeafNode({ key: 'x' }, FIELD_NAMES, { lazy: false, loadedSet: new Set() })).toBe(true)
+  })
+
+  it('懒加载下「未加载过」的无子节点仍可展开', () => {
+    const node = { key: 'lazy-1' }
+    expect(isLeafNode(node, FIELD_NAMES, { lazy: true, loadedSet: new Set() })).toBe(false)
+    expect(isLeafNode(node, FIELD_NAMES, { lazy: true, loadedSet: new Set(['lazy-1']) })).toBe(true)
+  })
+})
diff --git a/code/g3soft-libs/packages/ui/src/tree/utils.ts b/code/g3soft-libs/packages/ui/src/tree/utils.ts
new file mode 100644
index 00000000..4102ca8d
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/src/tree/utils.ts
@@ -0,0 +1,216 @@
+import type { DropPosition, TreeFieldNames, TreeKey, TreeNodeData } from './types'
+
+/**
+ * 树数据纯函数集合：字段解析、扁平索引、勾选联动、过滤、落点判定。
+ * 全部无副作用，组件层只负责把结果接进响应式状态。
+ */
+
+export const DEFAULT_FIELD_NAMES: Required<TreeFieldNames> = {
+  key: 'key',
+  title: 'title',
+  children: 'children',
+  icon: 'icon',
+}
+
+/** 合并字段名映射 */
+export function resolveFieldNames(fieldNames?: TreeFieldNames): Required<TreeFieldNames> {
+  return { ...DEFAULT_FIELD_NAMES, ...(fieldNames ?? {}) }
+}
+
+export function getNodeKey(node: TreeNodeData, fieldNames: Required<TreeFieldNames>): TreeKey {
+  return node[fieldNames.key] as TreeKey
+}
+
+export function getNodeTitle(node: TreeNodeData, fieldNames: Required<TreeFieldNames>): string {
+  const title = node[fieldNames.title]
+  return title == null ? '' : String(title)
+}
+
+/** 非空子节点数组才返回，否则 null（「有无子节点」的唯一判定口径） */
+export function getNodeChildren(
+  node: TreeNodeData,
+  fieldNames: Required<TreeFieldNames>,
+): TreeNodeData[] | null {
+  const children = node[fieldNames.children]
+  return Array.isArray(children) && children.length > 0 ? (children as TreeNodeData[]) : null
+}
+
+/** 是否叶子节点：显式 isLeaf 优先，否则按子节点 / 懒加载状态判断 */
+export function isLeafNode(
+  node: TreeNodeData,
+  fieldNames: Required<TreeFieldNames>,
+  options: { lazy: boolean; loadedSet: Set<string> },
+): boolean {
+  if (node.isLeaf === true) return true
+  if (node.isLeaf === false) return false
+  const children = getNodeChildren(node, fieldNames)
+  if (children) return false
+  if (options.lazy) return options.loadedSet.has(String(getNodeKey(node, fieldNames)))
+  return true
+}
+
+export interface FlatTreeInfo {
+  parentMap: Map<string, string | null>
+  levelMap: Map<string, number>
+  nodeMap: Map<string, TreeNodeData>
+  childrenMap: Map<string, string[]>
+  rootKeys: string[]
+}
+
+/** 递归 DFS 一次建好 5 张索引表（父键 / 层级 / 节点 / 子键 / 根键） */
+export function buildFlat(treeData: TreeNodeData[], fieldNames: Required<TreeFieldNames>): FlatTreeInfo {
+  const parentMap = new Map<string, string | null>()
+  const levelMap = new Map<string, number>()
+  const nodeMap = new Map<string, TreeNodeData>()
+  const childrenMap = new Map<string, string[]>()
+  const rootKeys: string[] = []
+
+  function walk(nodes: TreeNodeData[], parentKey: string | null, level: number) {
+    for (const node of nodes) {
+      const key = String(getNodeKey(node, fieldNames))
+      parentMap.set(key, parentKey)
+      levelMap.set(key, level)
+      nodeMap.set(key, node)
+      const children = getNodeChildren(node, fieldNames)
+      const childKeys = children ? children.map((child) => String(getNodeKey(child, fieldNames))) : []
+      childrenMap.set(key, childKeys)
+      if (parentKey === null) rootKeys.push(key)
+      if (children) walk(children, key, level + 1)
+    }
+  }
+
+  walk(treeData, null, 0)
+  return { parentMap, levelMap, nodeMap, childrenMap, rootKeys }
+}
+
+/** 含自身在内的全部子孙 */
+export function collectDescendants(rootKey: string, childrenMap: Map<string, string[]>): string[] {
+  const result: string[] = []
+  const stack = [rootKey]
+  while (stack.length) {
+    const key = stack.pop() as string
+    result.push(key)
+    const children = childrenMap.get(key)
+    if (children) stack.push(...children)
+  }
+  return result
+}
+
+/** 回溯所有祖先（去重，不含自身） */
+export function getParentKeys(targetKeys: TreeKey[], parentMap: Map<string, string | null>): string[] {
+  const result = new Set<string>()
+  for (const target of targetKeys) {
+    let current = parentMap.get(String(target))
+    while (current) {
+      if (result.has(current)) break
+      result.add(current)
+      current = parentMap.get(current)
+    }
+  }
+  return [...result]
+}
+
+/**
+ * 勾选联动：显式勾选节点的子孙全部勾选，其余节点自底向上回推——
+ * 子节点全选中则父节点选中，部分选中则父节点半选。
+ */
+export function conductCheck(
+  treeData: TreeNodeData[],
+  explicitChecked: Iterable<string>,
+  fieldNames: Required<TreeFieldNames>,
+): { checked: Set<string>; half: Set<string> } {
+  const checked = new Set<string>()
+  const half = new Set<string>()
+  const explicit = new Set([...explicitChecked].map(String))
+
+  function walk(node: TreeNodeData, ancestors: string[]): { all: boolean; some: boolean } {
+    const key = String(getNodeKey(node, fieldNames))
+    const children = getNodeChildren(node, fieldNames)
+    if (explicit.has(key)) {
+      checked.add(key)
+      // 父选中 ⇒ 子孙全选中
+      if (children) {
+        const stack = [...children]
+        while (stack.length) {
+          const child = stack.pop() as TreeNodeData
+          checked.add(String(getNodeKey(child, fieldNames)))
+          const grandChildren = getNodeChildren(child, fieldNames)
+          if (grandChildren) stack.push(...grandChildren)
+        }
+      }
+      return { all: true, some: true }
+    }
+
+    if (!children) return { all: false, some: false }
+
+    let allChildrenChecked = true
+    let someChildChecked = false
+    for (const child of children) {
+      const result = walk(child, [...ancestors, key])
+      if (result.all) someChildChecked = true
+      else {
+        allChildrenChecked = false
+        if (result.some) someChildChecked = true
+      }
+    }
+
+    if (allChildrenChecked && children.length > 0) {
+      checked.add(key)
+      return { all: true, some: true }
+    }
+    if (someChildChecked) {
+      half.add(key)
+      return { all: false, some: true }
+    }
+    return { all: false, some: false }
+  }
+
+  for (const node of treeData) walk(node, [])
+  // 半选集合里不能出现在选中集合中
+  half.forEach((key) => checked.delete(key))
+  return { checked, half }
+}
+
+/** 过滤：命中节点 ∪ 其祖先可见，命中的祖先链需要自动展开 */
+export function filterTree(
+  treeData: TreeNodeData[],
+  keyword: string,
+  fieldNames: Required<TreeFieldNames>,
+): { matched: Set<string>; expand: Set<string> } {
+  const matched = new Set<string>()
+  const expand = new Set<string>()
+  const text = keyword.trim().toLowerCase()
+  if (!text) return { matched, expand }
+
+  function walk(node: TreeNodeData, ancestors: string[]): boolean {
+    const key = String(getNodeKey(node, fieldNames))
+    const title = getNodeTitle(node, fieldNames).toLowerCase()
+    const hit = title.includes(text)
+    if (hit) {
+      matched.add(key)
+      ancestors.forEach((ancestor) => {
+        matched.add(ancestor)
+        expand.add(ancestor)
+      })
+    }
+    const children = getNodeChildren(node, fieldNames)
+    let childHit = false
+    if (children) {
+      for (const child of children) {
+        if (walk(child, [...ancestors, key])) childHit = true
+      }
+    }
+    return hit || childHit
+  }
+
+  for (const node of treeData) walk(node, [])
+  return { matched, expand }
+}
+
+/** 落点判定：行的上 25% 前、下 25% 后、中间「放入内部」 */
+export function calcDropPosition(clientY: number, rect: DOMRect): DropPosition {
+  const offset = clientY - rect.top
+  if (offset < rect.height * 0.25) return 'before'
+  if (offset > rect.height * 0.75) return 'after'
+  return 'inside'
+}
diff --git a/code/g3soft-libs/packages/ui/tests/setup.ts b/code/g3soft-libs/packages/ui/tests/setup.ts
new file mode 100644
index 00000000..1e04ee92
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/tests/setup.ts
@@ -0,0 +1,41 @@
+/**
+ * 单测环境补丁 —— happy-dom 缺少组件依赖的若干浏览器 API。
+ *
+ * happy-dom 没有真实布局引擎，所以：
+ * - 依赖实测尺寸的逻辑（浮层定位、Splitter 拖拽）拿不到有效值，那类行为放到 E2E（Playwright）里验；
+ * - 这里只补「不补就会抛错」的 API，让组件能正常挂载与交互。
+ */
+
+class ResizeObserverStub {
+  observe(): void {}
+  unobserve(): void {}
+  disconnect(): void {}
+}
+
+if (!('ResizeObserver' in globalThis)) {
+  ;(globalThis as unknown as Record<string, unknown>).ResizeObserver = ResizeObserverStub
+}
+
+if (typeof window !== 'undefined') {
+  if (!window.matchMedia) {
+    window.matchMedia = ((query: string) => ({
+      matches: false,
+      media: query,
+      onchange: null,
+      addListener: () => {},
+      removeListener: () => {},
+      addEventListener: () => {},
+      removeEventListener: () => {},
+      dispatchEvent: () => false,
+    })) as unknown as typeof window.matchMedia
+  }
+
+  if (!Element.prototype.scrollIntoView) {
+    Element.prototype.scrollIntoView = () => {}
+  }
+
+  // happy-dom 未实现 PointerEvent 时用 MouseEvent 兜底，保证指针交互的监听能注册
+  if (!('PointerEvent' in window)) {
+    ;(window as unknown as Record<string, unknown>).PointerEvent = MouseEvent
+  }
+}
diff --git a/code/g3soft-libs/packages/ui/vite.config.ts b/code/g3soft-libs/packages/ui/vite.config.ts
index 6941b908..d62436ee 100644
--- a/code/g3soft-libs/packages/ui/vite.config.ts
+++ b/code/g3soft-libs/packages/ui/vite.config.ts
@@ -60,7 +60,8 @@ export default defineConfig({
       fileName: () => 'index.js',
     },
     rollupOptions: {
-      external: ['vue'],
+      // 图标库同理外置：由消费方（或本包的 dependencies）解析，避免重复打包
+      external: ['vue', '@lucide/vue'],
       output: {
         preserveModules: true,
         preserveModulesRoot: 'src',
diff --git a/code/g3soft-libs/packages/ui/vitest.config.ts b/code/g3soft-libs/packages/ui/vitest.config.ts
new file mode 100644
index 00000000..f2be3146
--- /dev/null
+++ b/code/g3soft-libs/packages/ui/vitest.config.ts
@@ -0,0 +1,51 @@
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import vue from '@vitejs/plugin-vue'
+import { defineConfig } from 'vitest/config'
+
+/**
+ * 单测（L1 纯函数 + L2 组件）配置。
+ *
+ * 刻意**不复用** vite.config.ts：那份配置带 lib 构建与 dts 插件，与测试无关；
+ * 这里只保留组件编译必需的 vue 插件、SCSS 与命名空间常量（与构建同一事实源）。
+ *
+ * 输出：默认 reporter 给人看，json reporter 写到 test-results/unit.json 给工具/AI 读。
+ */
+
+const configScssPath = fileURLToPath(new URL('../tokens/src/scss/_config.scss', import.meta.url))
+const configScss = readFileSync(configScssPath, 'utf-8')
+
+function readScssDefault(name: string, fallback: string): string {
+  const match = configScss.match(
+    new RegExp(`\\$${name}\\s*:\\s*['"]([^'"]+)['"]\\s*!default`),
+  )
+  return match ? match[1] : fallback
+}
+
+export default defineConfig({
+  plugins: [vue()],
+  resolve: {
+    alias: [
+      // 测试里大量用字符串模板挂载组件，需要带编译器的完整版 Vue
+      { find: /^vue$/, replacement: 'vue/dist/vue.esm-bundler.js' },
+    ],
+  },
+  define: {
+    __G3_NAMESPACE__: JSON.stringify(readScssDefault('namespace', 'g3')),
+    __G3_STATE_PREFIX__: JSON.stringify(readScssDefault('state-prefix', 'is')),
+  },
+  css: {
+    preprocessorOptions: {
+      scss: { api: 'modern-compiler' },
+    },
+  },
+  test: {
+    environment: 'happy-dom',
+    setupFiles: [fileURLToPath(new URL('./tests/setup.ts', import.meta.url))],
+    include: ['src/**/*.test.ts', 'tests/**/*.test.ts'],
+    reporters: ['default', 'json'],
+    outputFile: { json: 'test-results/unit.json' },
+    // 组件测试会 Teleport 到 body 并触发 ResizeObserver / rAF，统一在 setup 里补齐
+    restoreMocks: true,
+  },
+})
diff --git a/code/g3soft-libs/pnpm-lock.yaml b/code/g3soft-libs/pnpm-lock.yaml
index 6716fefc..6c91f0be 100644
--- a/code/g3soft-libs/pnpm-lock.yaml
+++ b/code/g3soft-libs/pnpm-lock.yaml
@@ -26,9 +26,6 @@ importers:
       typescript:
         specifier: 'catalog:'
         version: 5.9.3
-      vue-docgen-api:
-        specifier: ^4.79.0
-        version: 4.79.2(vue@3.5.43(typescript@5.9.3))
 
   docs:
     dependencies:
@@ -43,10 +40,10 @@ importers:
         version: 12.11.1
       docus:
         specifier: ^5.14.0
-        version: 5.14.0(db3a3babb3e1a5f38f7fe64c400fed97)
+        version: 5.14.0(f92feb3e0732c978b98957e5210d7bcc)
       nuxt:
         specifier: 4.4.8
-        version: 4.4.8(@babel/plugin-syntax-jsx@7.29.7(@babel/core@7.29.7))(@babel/plugin-syntax-typescript@7.29.7(@babel/core@7.29.7))(@oxc-project/types@0.152.0)(@parcel/watcher@2.6.0)(@types/node@26.6.4)(@vue/compiler-sfc@3.5.43)(better-sqlite3@12.11.1)(cac@6.7.14)(confbox@0.2.4)(db0@0.3.4(better-sqlite3@12.11.1))(dotenv@17.4.2)(esbuild@0.28.2)(eslint@10.12.0(jiti@2.7.0))(giget@3.3.1)(ioredis@5.11.1)(lightningcss@1.33.0)(magicast@0.5.5)(optionator@0.9.4)(rolldown@1.2.12)(rollup-plugin-visualizer@7.1.1(rolldown@1.2.12)(rollup@4.64.0))(rollup@4.64.0)(sass@1.105.1)(srvx@0.11.22)(terser@5.51.2)(typescript@5.9.3)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))(vue-tsc@3.3.12(typescript@5.9.3))(yaml@2.9.1)
+        version: 4.4.8(@babel/plugin-syntax-jsx@7.29.7(@babel/core@7.29.7))(@babel/plugin-syntax-typescript@7.29.7(@babel/core@7.29.7))(@oxc-project/types@0.152.0)(@parcel/watcher@2.6.0)(@types/node@26.6.4)(@vue/compiler-sfc@3.5.43)(better-sqlite3@12.11.1)(cac@6.7.14)(commander@14.0.3)(confbox@0.2.4)(db0@0.3.4(better-sqlite3@12.11.1))(dotenv@17.4.2)(esbuild@0.28.2)(eslint@10.12.0(jiti@2.7.0))(giget@3.3.1)(ioredis@5.11.1)(lightningcss@1.33.0)(magicast@0.5.5)(optionator@0.9.4)(rolldown@1.2.12)(rollup-plugin-visualizer@7.1.1(rolldown@1.2.12)(rollup@4.64.0))(rollup@4.64.0)(sass@1.105.1)(srvx@0.11.22)(terser@5.51.2)(typescript@5.9.3)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))(vue-tsc@3.3.12(typescript@5.9.3))(yaml@2.9.1)
       vue:
         specifier: 'catalog:'
         version: 3.5.43(typescript@5.9.3)
@@ -55,6 +52,31 @@ importers:
         specifier: 'catalog:'
         version: 1.105.1
 
+  packages/framework:
+    dependencies:
+      '@g3soft/ui':
+        specifier: workspace:*
+        version: link:../ui
+    devDependencies:
+      '@vitejs/plugin-vue':
+        specifier: ^6.0.0
+        version: 6.0.9(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))(vue@3.5.43(typescript@5.9.3))
+      publint:
+        specifier: latest
+        version: 0.3.25
+      vite:
+        specifier: ^8.0.0
+        version: 8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)
+      vite-plugin-dts:
+        specifier: latest
+        version: 5.1.2(@vue/language-core@3.3.12)(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(typescript@5.9.3)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))
+      vue:
+        specifier: 'catalog:'
+        version: 3.5.43(typescript@5.9.3)
+      vue-tsc:
+        specifier: ^3.0.0
+        version: 3.3.12(typescript@5.9.3)
+
   packages/tokens:
     devDependencies:
       sass:
@@ -66,10 +88,22 @@ importers:
       '@g3soft/tokens':
         specifier: workspace:*
         version: link:../tokens
+      '@lucide/vue':
+        specifier: ^1.31.0
+        version: 1.52.0(vue@3.5.43(typescript@5.9.3))
     devDependencies:
+      '@playwright/test':
+        specifier: ^1.63.0
+        version: 1.63.0
       '@vitejs/plugin-vue':
         specifier: ^6.0.0
         version: 6.0.9(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))(vue@3.5.43(typescript@5.9.3))
+      '@vue/test-utils':
+        specifier: ^2.5.1
+        version: 2.5.1(@vue/compiler-dom@3.5.43)(@vue/server-renderer@3.5.43)(vue@3.5.43(typescript@5.9.3))
+      happy-dom:
+        specifier: ^20.14.5
+        version: 20.14.5
       publint:
         specifier: latest
         version: 0.3.25
@@ -82,6 +116,9 @@ importers:
       vite-plugin-dts:
         specifier: latest
         version: 5.1.2(@vue/language-core@3.3.12)(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(typescript@5.9.3)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))
+      vitest:
+        specifier: ^5.0.3
+        version: 5.0.3(@types/node@26.6.4)(happy-dom@20.14.5)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))
       vue:
         specifier: 'catalog:'
         version: 3.5.43(typescript@5.9.3)
@@ -1263,6 +1300,11 @@ packages:
   '@kwsites/promise-deferred@1.1.1':
     resolution: {integrity: sha512-GaHYm+c0O9MjZRu0ongGBRbinu8gVAMd2UZjji6jVmqKtZluZnptXGWhz1E8j8D2HJ3f/yMxKAUC0b+57wncIw==}
 
+  '@lucide/vue@1.52.0':
+    resolution: {integrity: sha512-Gwr6c14jhY6BscoFU+B9OKsr7lg8RTAKOLgW0e61kkFwkt9Q7CZmB9AyJcvhoqapEJgRg2bFoeAcO+cqpgKzEQ==}
+    peerDependencies:
+      vue: '>=3.0.1'
+
   '@manypkg/find-root@1.1.0':
     resolution: {integrity: sha512-mki5uBvhHzO8kYYix/WRy2WX8S3B5wdVSc9D6KcU5lQNglP2yt58/VfLuAK49glRXChosY8ap2oJ1qgma3GUVA==}
 
@@ -1585,6 +1627,9 @@ packages:
       zod:
         optional: true
 
+  '@one-ini/wasm@0.2.1':
+    resolution: {integrity: sha512-TUqERXGNTifZ9y2g3wPxQrw3HpHv/02DsW3D90T9x0hhonrL1ZqpSmNrU2XkoIq0fP1N6gZfVQzy2Fw1ZvGBNg==}
+
   '@oxc-minify/binding-android-arm-eabi@0.133.0':
     resolution: {integrity: sha512-D8M1+nqwLaACHZsld/t6f+cE4N97XOu5iQ88f1ZaYH4ptFzFrXo5N7wUKACTI4xmNUD+6W0Y4Apk5U2r8HLdBQ==}
     engines: {node: ^20.19.0 || >=22.12.0}
@@ -2576,6 +2621,11 @@ packages:
     resolution: {integrity: sha512-+1VkjdD0QBLPodGrJUeqarH8VAIvQODIbwh9XpP5Syisf7YoQgsJKPNFoqqLQlu+VQ/tVSshMR6loPMn8U+dPg==}
     engines: {node: '>=14'}
 
+  '@playwright/test@1.63.0':
+    resolution: {integrity: sha512-oxMK4vllB9RK5NQ2l1pq1IfOf2AvnEuj/vYGDj0H2nMtmtZpKtCwt/l00GEO6xjGfpBNAvjovvYdCm50dRQkpQ==}
+    engines: {node: '>=20'}
+    hasBin: true
+
   '@polka/url@1.0.0-next.29':
     resolution: {integrity: sha512-wwQAWhWSuHaag8c4q/KN/vCoeOJYshAIvMQwD4GpSb3OiZklFfvAgmj0VCBBImRpuF/aFgIRzllXlVX93Jevww==}
 
@@ -3407,9 +3457,15 @@ packages:
   '@tybys/wasm-util@0.10.4':
     resolution: {integrity: sha512-W3c4gRigFS0T/Ma4qIYF3GDAc5AQdHb1yL5znJT1Zv1YaD9Kitx656wBjvr19qbiosmZT8lWDM5BEMynUqX65A==}
 
+  '@types/chai@5.2.3':
+    resolution: {integrity: sha512-Mw558oeA9fFbv65/y4mHtXDs9bPnFMZAL/jxdPFUpOHHIXX91mcgEHbS5Lahr+pwZFR8A7GQleRWeI6cGFC2UA==}
+
   '@types/debug@4.1.13':
     resolution: {integrity: sha512-KSVgmQmzMwPlmtljOomayoR89W4FynCAi3E8PPs7vmDVPe84hT+vGPKkJfThkmXs0x0jAaa9U8uW8bbfyS2fWw==}
 
+  '@types/deep-eql@4.0.2':
+    resolution: {integrity: sha512-c9h9dVVMigMPc4bwTvC5dxqtqJZwQPePsWjPlpSOnojbor6pGqdk541lfA7AqFQr5pB1BRdq0juY9db81BwyFw==}
+
   '@types/esrecurse@4.3.1':
     resolution: {integrity: sha512-xJBAbDifo5hpffDBuHl0Y8ywswbiAp/Wi7Y/GtAgSlZyIABppyurxVueOPE8LUQOxdlgi6Zqce7uoEpqNTeiUw==}
 
@@ -3459,6 +3515,12 @@ packages:
   '@types/web-bluetooth@0.0.21':
     resolution: {integrity: sha512-oIQLCGWtcFZy2JW77j9k8nHzAOpqMHLQejDA48XXMWH6tjCQHz5RCFz1bzsmROyL6PUm+LLnUiI4BCn221inxA==}
 
+  '@types/whatwg-mimetype@3.0.2':
+    resolution: {integrity: sha512-c2AKvDT8ToxLIOUlN51gTiHXflsfIFisS4pO7pDPoKouJCESkhZnEy623gwP9laCy5lnLDAw1vAzu2vM2YLOrA==}
+
+  '@types/ws@8.18.2':
+    resolution: {integrity: sha512-67MQl+fpWKVTT1NYdnmo3U4sc/xPo/zQBncVnI74qmQa0z/b+1g6iYqNmGCPbxO+zz2aklb08a0oHfegiVd0/w==}
+
   '@typescript-eslint/project-service@8.71.1':
     resolution: {integrity: sha512-Oijc9RUsohHjncg6iGi7gCtjnEjYt9FWv9u6ygK8uKcHK5eLjLAkqERQ9BaytbpceOFdk6kifPCS/zAZE+A99g==}
     engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
@@ -3562,6 +3624,20 @@ packages:
       vite: ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0
       vue: ^3.2.25
 
+  '@vitest/mocker@5.0.3':
+    resolution: {integrity: sha512-T8sWAIbkSyAjkwTcaEc3Iu0o9A27X1/kdXrizhZkGuSKScRQtRzclfAMpOTcGdXCsqxeWlpGy3XjqaW8CpLORg==}
+    peerDependencies:
+      msw: ^2.4.9
+      vite: ^6.0.0 || ^7.0.0 || ^8.0.0
+    peerDependenciesMeta:
+      msw:
+        optional: true
+      vite:
+        optional: true
+
+  '@vitest/spy@5.0.3':
+    resolution: {integrity: sha512-XhFysQTB8AZ+P4gMi+Lpo99vg2AZi0qKpaB9yXQl37+CaMEAPO3iH/wGVnSyL5MPERiLezpqTVtrR6UZH5GCXg==}
+
   '@volar/language-core@2.4.28':
     resolution: {integrity: sha512-w4qhIJ8ZSitgLAkVay6AbcnC7gP3glYM3fYwKV3srj8m494E3xtrCv6E+bWviiK/8hs6e6t1ij1s2Endql7vzQ==}
 
@@ -3643,6 +3719,16 @@ packages:
   '@vue/shared@3.5.43':
     resolution: {integrity: sha512-uksS7YGMR5NZyr4JNq0Rp+QyLns0ueaz20KwzIPW9R0LH1Vnt4E+XUM29PNseEbf1www2gOuhuDi5AKOIXag9Q==}
 
+  '@vue/test-utils@2.5.1':
+    resolution: {integrity: sha512-V/4a99odJ7hapr0bRt35XxljGk8hefq31gSOnlKTcEq2fUeoj2qb+FcpJYfQu4qfYhW9Ug+O2+CZ3QmZ7gXDzA==}
+    peerDependencies:
+      '@vue/compiler-dom': 3.x
+      '@vue/server-renderer': 3.x
+      vue: 3.x
+    peerDependenciesMeta:
+      '@vue/server-renderer':
+        optional: true
+
   '@vueuse/core@10.11.1':
     resolution: {integrity: sha512-guoy26JQktXPcz+0n3GukWIy/JDNKti9v6VEMu6kV2sYBsWuGiTU8OWdg+ADfUbHg3/3DlqySDe7JmdHrktiww==}
 
@@ -3733,6 +3819,10 @@ packages:
     resolution: {integrity: sha512-AO2ac6pjRB3SJmGJo+v5/aK6Omggp6fsLrs6wN9bd35ulu4cCwaAU9+7ZhXjeqHVkaHThLuzH0nZr0YpCDhygg==}
     engines: {node: ^18.17.0 || >=20.5.0}
 
+  abbrev@5.0.0:
+    resolution: {integrity: sha512-/XrFJgzQQQHpti1raDJC6m4ws6aNktmjBlhk8Fdlk7LwCEuDoieEJJY9OFHjfiFJFFRM2tK+Ky/IsfbbmlMu1w==}
+    engines: {node: ^22.22.2 || ^24.15.0 || >=26.0.0}
+
   abort-controller@3.0.0:
     resolution: {integrity: sha512-h8lQ8tacZYnR3vNQTgibj+tODHI5/+l06Au2Pcriv/Gmet0eaj4TwWH41sO9wnHDiQsEj19q0drzdWdeAHtweg==}
     engines: {node: '>=6.5'}
@@ -3751,11 +3841,6 @@ packages:
     peerDependencies:
       acorn: ^6.0.0 || ^7.0.0 || ^8.0.0
 
-  acorn@7.4.1:
-    resolution: {integrity: sha512-nQyp0o1/mNdbTO1PO6kHkwSrmgZ0MT/jCCpNiwbUjGoRN4dlBhqJtoQuCnEOKzgTVwg0ZWiCoQy6SxMebQVh8A==}
-    engines: {node: '>=0.4.0'}
-    hasBin: true
-
   acorn@8.19.0:
     resolution: {integrity: sha512-oJlA3XiRm7Cyk6qFD2Jn8ak9B7jSy0qy00ADO3+8dpT0LSjFihQYv4C02LFCSYJV3Q37xYwwRy5m+IpIiUzqWw==}
     engines: {node: '>=0.4.0'}
@@ -3841,20 +3926,14 @@ packages:
     resolution: {integrity: sha512-HGyxoOTYUyCM6stUe6EJgnd4EoewAI7zMdfqO+kGjnlZmBDz/cR5pf8r/cR4Wq60sL/p0IkcjUEEPwS3GFrIyw==}
     engines: {node: '>=8'}
 
-  asap@2.0.6:
-    resolution: {integrity: sha512-BSHWgDSAiKs50o2Re8ppvp3seVHXSRM44cdSsT9FfNEUUZLOGWVCsiWaRPWM1Znn+mqZ1OfVZ3z3DWEzSp7hRA==}
-
-  assert-never@1.4.0:
-    resolution: {integrity: sha512-5oJg84os6NMQNl27T9LnZkvvqzvAnHu03ShCnoj6bsJwS7L8AO4lf+C/XjK/nvzEqQB744moC6V128RucQd1jA==}
+  assertion-error@2.0.1:
+    resolution: {integrity: sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==}
+    engines: {node: '>=12'}
 
   ast-kit@2.2.0:
     resolution: {integrity: sha512-m1Q/RaVOnTp9JxPX+F+Zn7IcLYMzM8kZofDImfsKZd8MbR+ikdOzTeztStWqfrqIxZnYWryyI9ePm3NGjnZgGw==}
     engines: {node: '>=20.19.0'}
 
-  ast-types@0.16.3:
-    resolution: {integrity: sha512-FvWoWYfSCM6kRxCSH+MGLHIKKGRL6A6AW7Zek2O32REPQRdg131428uRTKMBYAeRd3XXAaHDS60Wpri7CdKDrA==}
-    engines: {node: '>=4'}
-
   ast-walker-scope@0.9.0:
     resolution: {integrity: sha512-IJdzo2vLiElBxKzwS36VsCue/62d6IdWjnPB2v3nuPKeWGynp6FF/CYoLa5i/3jXH/z97ZDdsXz6abpgM6w07A==}
     engines: {node: '>=20.19.0'}
@@ -3887,10 +3966,6 @@ packages:
       react-native-b4a:
         optional: true
 
-  babel-walk@3.0.0-canary-5:
-    resolution: {integrity: sha512-GAwkz0AihzY5bkwIY5QDR+LvsRQgB/B+1foMPvi0FZPMl5fjD7ICiznUiBdLYMH1QYe6vqu4gWYytZOccLouFw==}
-    engines: {node: '>= 10.0.0'}
-
   bail@2.0.2:
     resolution: {integrity: sha512-0xO6mYd7JB2YesxDKplafRpsiOzPt9V02ddPCLbY1xYGPOX24NTyN50qnUxgCPcSoYMhKpAuBTjQoRZCAkUDRw==}
 
@@ -3996,6 +4071,10 @@ packages:
   buffer-from@1.1.2:
     resolution: {integrity: sha512-E+XQCRwSbaaiChtv6k6Dwgc+bx+Bs6vuKJHHl5kox/BaKbhiXzqQOwK4cO22yElGp2OCmjwVhT3HmxgyPGnJfQ==}
 
+  buffer-image-size@0.6.4:
+    resolution: {integrity: sha512-nEh+kZOPY1w+gcCMobZ6ETUp9WfibndnosbpwB1iJk/8Gt5ZF2bhS6+B6bPYz424KtwsR6Rflc3tCz1/ghX2dQ==}
+    engines: {node: '>=4.0'}
+
   buffer@5.7.1:
     resolution: {integrity: sha512-EHcyIPBQ4BSGlvjB16k5KgAJ27CIsHY/2JBmCRReo48y9rQ3MaUzWX3KVlBa4U7MyX02HdVj0K7C3WaB3ju7FQ==}
 
@@ -4050,6 +4129,10 @@ packages:
   ccount@2.0.1:
     resolution: {integrity: sha512-eyrF0jiFpY+3drT6383f1qhkbGsLSifNAjA61IUjZjmLCWjItY6LB9ft9YhoDgwfmclB2zhu51Lc7+95b8NRAg==}
 
+  chai@6.3.0:
+    resolution: {integrity: sha512-XWAtwJ6OHO+tj0EKCs0Y2UamnyOxseZWltU4x2U2wh8g4AigdjwvtUjvLP2tqkA/avxHEtzxNaqGq/YGNwckKg==}
+    engines: {node: '>=18'}
+
   char-regex@1.0.2:
     resolution: {integrity: sha512-kWWXztvZ5SBQV+eRgKFeh8q5sLuZY2+8WUIzlxWVTg+oGwY14qylx1KbKzHd8P6ZYkAg0xyIDU9JMHhyJMZ1jw==}
     engines: {node: '>=10'}
@@ -4063,9 +4146,6 @@ packages:
   character-entities@2.0.2:
     resolution: {integrity: sha512-shx7oQ0Awen/BRIdkjkvz54PnEEI/EjwXDSIZp86/KKdbafHh1Df/RYGBhn4hbe2+uKC9FnT5UCEdyPz3ai9hQ==}
 
-  character-parser@2.2.0:
-    resolution: {integrity: sha512-+UqJQjFEFaTAs3bNsF2j2kEN1baG/zghZbdqoYEDxGZtJo9LBzl1A+m0D4n3qKx8N2FNv8/Xp6yV9mQmBuptaw==}
-
   character-reference-invalid@2.0.1:
     resolution: {integrity: sha512-iBZ4F4wRbyORVsu0jPV7gXkOsGYjGHPmAyv+HiHG8gi5PtC9KI2j1+v8/tlibRvjoWX027ypmG/n0HtO5t7unw==}
 
@@ -4139,6 +4219,10 @@ packages:
     resolution: {integrity: sha512-yPVavfyCcRhmorC7rWlkHn15b4wDVgVmBA7kV4QVBsF7kv/9TKJAbAXVTxvTnwP8HHKjRCJDClKbciiYS7p0DQ==}
     engines: {node: '>=16'}
 
+  commander@14.0.3:
+    resolution: {integrity: sha512-H+y0Jo/T1RZ9qPP4Eh1pkcQcLRglraJaSLoyOtHxu6AapkjWVCy2Sit1QQ4x3Dng8qDlSsZEet7g5Pq06MvTgw==}
+    engines: {node: '>=20'}
+
   commander@2.20.3:
     resolution: {integrity: sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ==}
 
@@ -4164,13 +4248,13 @@ packages:
   confbox@0.3.1:
     resolution: {integrity: sha512-cKUSoKa8YxFZZSmraVi7onONx3amu77ngK3kGpsYHDH7drPwCRkQE1RYMPlLRrMtnciRj274XNRxcHxnKmDSnA==}
 
+  config-chain@1.1.13:
+    resolution: {integrity: sha512-qj+f8APARXHrM0hraqXYb2/bOVSV4PvJQlNZ/DVj0QrmNM2q2euizkeuVckQ57J+W0mRH6Hvi+k50M4Jul2VRQ==}
+
   consola@3.4.2:
     resolution: {integrity: sha512-5IKcdX0nnYavi6G7TtOhwkYzyjfJlatbjMjuLSfE2kYT5pMDOilZ4OvMhi637CcDICTmz3wARPoyhqyX1Y+XvA==}
     engines: {node: ^14.18.0 || >=16.10.0}
 
-  constantinople@4.0.1:
-    resolution: {integrity: sha512-vCrqcSIq4//Gx74TXXCGnHpulY1dskqLTFGDmhrGxzeXL8lF8kvXv6mpNWlJj1uD4DW23D4ljAqbY4RRaaUZIw==}
-
   content-disposition@1.1.0:
     resolution: {integrity: sha512-5jRCH9Z/+DRP7rkvY83B+yGIGX96OYdJmzngqnw2SBSxqCFPd0w2km3s5iawpGX8krnwSGmF0FW5Nhr0Hfai3g==}
     engines: {node: '>=18'}
@@ -4398,9 +4482,6 @@ packages:
     resolution: {integrity: sha512-WkrWp9GR4KXfKGYzOLmTuGVi1UWFfws377n9cc55/tb6DuqyF6pcQ5AbiHEshaDpY9v6oaSr2XCDidGmMwdzIA==}
     engines: {node: '>=8'}
 
-  doctypes@1.1.0:
-    resolution: {integrity: sha512-LLBi6pEqS6Do3EKQ3J0NqHWV5hhb78Pi8vvESYwyOy2c31ZEZVdtitdzsQsKb7878PEERhzUk0ftqGhG6Mz+pQ==}
-
   docus@5.14.0:
     resolution: {integrity: sha512-Zle9z54Wsc3pU12yLincka2SFmY2QCwhWxUW2r8SfcriIoNYKBxHlXByRRA2/6iZxnk8x+/yuEnkUkyk50ZCsQ==}
     peerDependencies:
@@ -4454,6 +4535,11 @@ packages:
   eastasianwidth@0.2.0:
     resolution: {integrity: sha512-I88TYZWc9XiYHRQ4/3c5rjjfgkjhLyW2luGIheGERbNQ6OY7yTybanSpDXZa8y7VUP9YmDcYa+eyq4ca7iLqWA==}
 
+  editorconfig@3.0.2:
+    resolution: {integrity: sha512-T0ix8GhtxyKVfUFEcvdNDt3YGqlwkFHbD4/5bgFUDgFmxhI/cSRAeJ87/Sz//Cq8Eam6JX/e23RkoFO71P7aAA==}
+    engines: {node: '>=20'}
+    hasBin: true
+
   ee-first@1.1.1:
     resolution: {integrity: sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow==}
 
@@ -4641,9 +4727,6 @@ packages:
       jiti:
         optional: true
 
-  esm-resolve@1.0.11:
-    resolution: {integrity: sha512-LxF0wfUQm3ldUDHkkV2MIbvvY0TgzIpJ420jHSV1Dm+IlplBEWiJTKWM61GtxUfvjV6iD4OtTYFGAGM2uuIUWg==}
-
   espree@11.2.0:
     resolution: {integrity: sha512-7p3DrVEIopW1B1avAGLuCSh1jubc01H2JHc8B4qqGblmg5gI9yumBgACjWo4JlIc04ufug4xJ3SQI8HkS/Rgzw==}
     engines: {node: ^20.19.0 || ^22.13.0 || >=24}
@@ -4710,6 +4793,10 @@ packages:
     resolution: {integrity: sha512-XYfuKMvj4O35f/pOXLObndIRvyQ+/+6AhODh+OKWj9S9498pHHn/IMszH+gt0fBCRWMNfk1ZSp5x3AifmnI2vg==}
     engines: {node: '>=6'}
 
+  expect-type@1.4.0:
+    resolution: {integrity: sha512-KfYbmpRm0VbLjEvVa9yGwCi9GI34xvi7A/HXYWQO65CSD2u3MczUJSuwXKFIxlGsgBQizV9q5J9NHj4VG0n+pA==}
+    engines: {node: '>=12.0.0'}
+
   express-rate-limit@8.7.1:
     resolution: {integrity: sha512-2FXbqkygil3mZiXzEtM0IjE/UBmBNot0J1GEVrJT4JbrvwOSoEtqtO+wHbiMQELWe1eNvHoYRg2dkjOid+6JkA==}
     engines: {node: '>= 16'}
@@ -4978,6 +5065,10 @@ packages:
   h3@1.15.11:
     resolution: {integrity: sha512-L3THSe2MPeBwgIZVSH5zLdBBU90TOxarvhK9d04IDY2AmVS8j2Jz2LIWtwsGOU3lu2I5jCN7FNvVfY2+XyF+mg==}
 
+  happy-dom@20.14.5:
+    resolution: {integrity: sha512-x/RzkpWO40bTjIoT30iQtt64FLLmH/iRcUCN2X//bLx7H3ifkdfPXyqsro/OYtqzIAhiLMMA7mmiOR9C3NOKjQ==}
+    engines: {node: '>=20.0.0'}
+
   has-property-descriptors@1.0.2:
     resolution: {integrity: sha512-55JNKuIW+vq4Ke1BjOTjM2YctQIvCT7GFzHwmfZPGo5wnrgkid0YQtnAleFSqumZm4az3n2BS+erby5ipJdgrg==}
 
@@ -4989,9 +5080,6 @@ packages:
     resolution: {integrity: sha512-NqADB8VjPFLM2V0VvHUewwwsw0ZWBaIdgo+ieHtK3hasLz4qeCRjYcqfB6AQrBggRKppKF8L52/VqdVsO47Dlw==}
     engines: {node: '>= 0.4'}
 
-  hash-sum@2.0.0:
-    resolution: {integrity: sha512-WdZTbAByD+pHfl/g9QSsBIIwy8IT+EsPiKDs0KNX+zSHhdDLFKdZu0BQHljvO+0QI/BasbMSUa8wYNCZTvhslg==}
-
   hashery@1.5.1:
     resolution: {integrity: sha512-iZyKG96/JwPz1N55vj2Ie2vXbhu440zfUfJvSwEqEbeLluk7NnapfGqa7LH0mOsnDxTF85Mx8/dyR6HfqcbmbQ==}
     engines: {node: '>=20'}
@@ -5203,9 +5291,6 @@ packages:
     engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
     hasBin: true
 
-  is-expression@4.0.0:
-    resolution: {integrity: sha512-zMIXX63sxzG3XrkHkrAPvm/OVZVSCPNkwMHU8oTX7/U3AL78I0QXCEICXUM13BIa8TYGZ68PiTKfQz3yaTNr4A==}
-
   is-extglob@2.1.1:
     resolution: {integrity: sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ==}
     engines: {node: '>=0.10.0'}
@@ -5249,19 +5334,12 @@ packages:
     resolution: {integrity: sha512-+Pgi+vMuUNkJyExiMBt5IlFoMyKnr5zhJ4Uspz58WOhBF5QoIZkFyNHIbBAtHwzVAgk5RtndVNsDRN61/mmDqg==}
     engines: {node: '>=12'}
 
-  is-promise@2.2.2:
-    resolution: {integrity: sha512-+lP4/6lKUBfQjZ2pdxThZvLUAafmZb8OAxFb8XXtiQmS35INgr85hdOGoEs124ez1FCnZJt6jau/T+alh58QFQ==}
-
   is-promise@4.0.0:
     resolution: {integrity: sha512-hvpoI6korhJMnej285dSg6nu1+e6uxs7zG3BYAm5byqDsgJNWwxzM6z6iZiAgQR4TJ30JmBTOwqZUw3WlyH3AQ==}
 
   is-reference@1.2.1:
     resolution: {integrity: sha512-U82MsXXiFIrjCK4otLT+o2NA2Cd2g5MLoOVXUZjIOhLurrRxpEXzI8O0KZHr3IjLvlAH1kTPYSuqer5T9ZVBKQ==}
 
-  is-regex@1.2.1:
-    resolution: {integrity: sha512-MjYsKHO5O7mCsmRGxWcLWheFqN9DJ/2TmngvjKXihe6efViPqc274+Fx/4fYj/r03+ESvBdTXK0V6tA3rgez1g==}
-    engines: {node: '>= 0.4'}
-
   is-ssh@1.4.1:
     resolution: {integrity: sha512-JNeu1wQsHjyHgn9NcWTaXq6zWSR6hqE0++zhfZlkFBbScNkyvxCdeV8sRkSBaeLKxmbpR21brail63ACNxJ0Tg==}
 
@@ -5327,8 +5405,13 @@ packages:
   jose@6.2.12:
     resolution: {integrity: sha512-9NiFmJEex0sy2Dk58j2UGBSHgUs2ypF9eZSu4L6vjOX3Dp96Sw1F3uL+H+D1sx02jZZdzUT0HgvCy59CuvXcWw==}
 
-  js-stringify@1.0.2:
-    resolution: {integrity: sha512-rtS5ATOo2Q5k1G+DADISilDA6lv79zIiwFd6CcjuIxGKLFm5C+RLImRscVap9k55i+MOZwgliw+NejvkLuGD5g==}
+  js-beautify@2.0.3:
+    resolution: {integrity: sha512-cyFbh3tkPhknnTD/0bLf0T0yy2ZIbqL05mttzbt4y1Zfr7NxqXQZ62dkBLKs3oHH/lpjmDRAnciJiSUyOy8XwQ==}
+    engines: {node: '>=14'}
+    hasBin: true
+
+  js-cookie@3.0.8:
+    resolution: {integrity: sha512-yeJd4aNAdYZQjaon2bpD/Gb0B/omw7HQOsynXXcOiWVCacbBcPlgn8S/d1X6blFSaHao7ozqtW7NZW19xpCtIw==}
 
   js-tokens@10.0.0:
     resolution: {integrity: sha512-lM/UBzQmfJRo9ABXbPWemivdCW8V2G8FHaHdypQaIy523snUjog0W71ayWXTjiR+ixeMyVHN2XcpnTd/liPg/Q==}
@@ -5383,9 +5466,6 @@ packages:
   jsonfile@4.0.0:
     resolution: {integrity: sha512-m6F1R3z8jjlf2imQHS2Qez5sjKWQzbuuhuJ/FKYFRZvPE3PuHcSMVZzfsLhGVOkfd20obL5SWEBew5ShlquNxg==}
 
-  jstransformer@1.0.0:
-    resolution: {integrity: sha512-C9YK3Rf8q6VAPDCCU9fnqo3mAfOH6vUGnMcP4AQAYIEpWtfGLpwOTmZ+igtdK5y+VvI2n3CyYSzy4Qh34eq24A==}
-
   keyv@5.6.0:
     resolution: {integrity: sha512-CYDD3SOtsHtyXeEORYRx2qBtpDJFjRTGXUtmNEMGyzYOKj1TE3tycdlho7kA1Ufx9OYWZzg52QFBGALTirzDSw==}
 
@@ -5620,10 +5700,6 @@ packages:
   lru-cache@5.1.1:
     resolution: {integrity: sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w==}
 
-  lru-cache@8.0.5:
-    resolution: {integrity: sha512-MhWWlVnuab1RG5/zMRRcVGXZLCXrZTgfwMikgzCegsPnG62yDQo5JnqKkrK4jO5iKqDAZGItAqN5CtKBCBWRUA==}
-    engines: {node: '>=16.14'}
-
   magic-regexp@0.10.0:
     resolution: {integrity: sha512-Uly1Bu4lO1hwHUW0CQeSWuRtzCMNO00CmXtS8N6fyvB3B979GOEEeAkiTUDsmbYLAbvpUS/Kt5c4ibosAzVyVg==}
 
@@ -5963,6 +6039,11 @@ packages:
     resolution: {integrity: sha512-kQK9LGGFiHtrWiNhZtA7Qbw17AQz+dmsEKODRIVTXA9+e5MS/2gZEBhYJt13GrAz5/IOZKddH/0Z3TP/Zgo+yw==}
     engines: {node: '>=18'}
 
+  nopt@10.0.1:
+    resolution: {integrity: sha512-df3sBr/6ax9hSGuC3CspvLlbnX8cP5L5nZwXF8cGN8l0zSWR6BvzmQ6jPUKjvo6+/xdpkNvEcucBNUdBeeV13g==}
+    engines: {node: ^22.22.2 || ^24.15.0 || >=26.0.0}
+    hasBin: true
+
   nopt@8.1.0:
     resolution: {integrity: sha512-ieGu42u/Qsa4TFktmaKEwM6MQH0pOWnaB3htzh0JRtx84+Mebc0cbZYN5bC+6WTZ4+77xrL9Pn5m7CV6VIkV7A==}
     engines: {node: ^18.17.0 || >=20.5.0}
@@ -6355,6 +6436,16 @@ packages:
   pkg-types@2.3.3:
     resolution: {integrity: sha512-j/lCFdcppV0JxWpCEITdbDltBxPP6cHT+yNJ6Go2OgoSA9518X847X9z0p6LtA4Nc16+eQzCZjRrWanTGvHJ5w==}
 
+  playwright-core@1.63.0:
+    resolution: {integrity: sha512-rYCsBF/M5HjUch52bbtVONEFjv6Xu8sm8h72dNlR5bzIE1fvC/bxgspzkjSfU+MweEMmPM8KJebG6nnyxo5mCg==}
+    engines: {node: '>=20'}
+    hasBin: true
+
+  playwright@1.63.0:
+    resolution: {integrity: sha512-+7ziBLidS4NaNCdt57SUDT+wYmmd5fmiQejUic/kb+YsYSCPyOOE9sebzMjNmQrsnNpDJqd4WHvV/8lfKfUDUg==}
+    engines: {node: '>=20'}
+    hasBin: true
+
   possible-typed-array-names@1.1.0:
     resolution: {integrity: sha512-/+5VFTchJDoVj3bhoqi6UeymcD00DAwb1nJwamzPvHEszJ4FpF6SNNbUbOS8yI56qHzdV8eK0qEfOSiodkTdxg==}
     engines: {node: '>= 0.4'}
@@ -6562,9 +6653,6 @@ packages:
     resolution: {integrity: sha512-cdGef/drWFoydD1JsMzuFf8100nZl+GT+yacc2bEced5f9Rjk4z+WtFUTBu9PhOi9j/jfmBPu0mMEY4wIdAF8A==}
     engines: {node: '>= 0.6.0'}
 
-  promise@7.3.1:
-    resolution: {integrity: sha512-nolQXZ/4L+bP/UGlkfaIujX9BKxGwmQ9OT4mOt5yvy8iK1h3wqTEJCijzGANTCCl9nWjY41juyAn2K3Q1hLLTg==}
-
   proper-lockfile@4.1.2:
     resolution: {integrity: sha512-TjNPblN4BwAWMXU8s9AEz4JmQxnD1NNL7bNOY/AKUzyamc379FWASUhc/K1pL2noVb+XmZKLL68cjzLsiOAMaA==}
 
@@ -6610,6 +6698,9 @@ packages:
   prosemirror-view@1.42.6:
     resolution: {integrity: sha512-3g25f6hKV2bBxo3puH3EcYWmmVNSH0iWmNsMVT7sugDSpA025jgpOLarcDWr39SdzPjYMaiYtRdNtXialPSjEQ==}
 
+  proto-list@1.2.4:
+    resolution: {integrity: sha512-vtK/94akxsTMhe0/cbfpR+syPuszcuwhqVjJq26CuNDgFGj682oRBXOP5MJpv2r7JtE8MsiepGIqvvOTBwn2vA==}
+
   protocols@2.0.2:
     resolution: {integrity: sha512-hHVTzba3wboROl0/aWRRG9dMytgH6ow//STBZh43l/wQgmMhYhOFi0EHWAPtoCz9IAUymsyP0TSBHkhgMEGNnQ==}
 
@@ -6622,42 +6713,6 @@ packages:
     engines: {node: '>=18'}
     hasBin: true
 
-  pug-attrs@3.0.0:
-    resolution: {integrity: sha512-azINV9dUtzPMFQktvTXciNAfAuVh/L/JCl0vtPCwvOA21uZrC08K/UnmrL+SXGEVc1FwzjW62+xw5S/uaLj6cA==}
-
-  pug-code-gen@3.0.4:
-    resolution: {integrity: sha512-6okWYIKdasTyXICyEtvobmTZAVX57JkzgzIi4iRJlin8kmhG+Xry2dsus+Mun/nGCn6F2U49haHI5mkELXB14g==}
-
-  pug-error@2.1.0:
-    resolution: {integrity: sha512-lv7sU9e5Jk8IeUheHata6/UThZ7RK2jnaaNztxfPYUY+VxZyk/ePVaNZ/vwmH8WqGvDz3LrNYt/+gA55NDg6Pg==}
-
-  pug-filters@4.0.0:
-    resolution: {integrity: sha512-yeNFtq5Yxmfz0f9z2rMXGw/8/4i1cCFecw/Q7+D0V2DdtII5UvqE12VaZ2AY7ri6o5RNXiweGH79OCq+2RQU4A==}
-
-  pug-lexer@5.0.1:
-    resolution: {integrity: sha512-0I6C62+keXlZPZkOJeVam9aBLVP2EnbeDw3An+k0/QlqdwH6rv8284nko14Na7c0TtqtogfWXcRoFE4O4Ff20w==}
-
-  pug-linker@4.0.0:
-    resolution: {integrity: sha512-gjD1yzp0yxbQqnzBAdlhbgoJL5qIFJw78juN1NpTLt/mfPJ5VgC4BvkoD3G23qKzJtIIXBbcCt6FioLSFLOHdw==}
-
-  pug-load@3.0.0:
-    resolution: {integrity: sha512-OCjTEnhLWZBvS4zni/WUMjH2YSUosnsmjGBB1An7CsKQarYSWQ0GCVyd4eQPMFJqZ8w9xgs01QdiZXKVjk92EQ==}
-
-  pug-parser@6.0.0:
-    resolution: {integrity: sha512-ukiYM/9cH6Cml+AOl5kETtM9NR3WulyVP2y4HOU45DyMim1IeP/OOiyEWRr6qk5I5klpsBnbuHpwKmTx6WURnw==}
-
-  pug-runtime@3.0.1:
-    resolution: {integrity: sha512-L50zbvrQ35TkpHwv0G6aLSuueDRwc/97XdY8kL3tOT0FmhgG7UypU3VztfV/LATAvmUfYi4wNxSajhSAeNN+Kg==}
-
-  pug-strip-comments@2.0.0:
-    resolution: {integrity: sha512-zo8DsDpH7eTkPHCXFeAk1xZXJbyoTfdPlNR0bK7rpOMuhBYb0f5qUVCO1xlsitYd3w5FQTK7zpNVKb3rZoUrrQ==}
-
-  pug-walk@2.0.0:
-    resolution: {integrity: sha512-yYELe9Q5q9IQhuvqsZNwA5hfPkMJ8u92bQLIMcsMxf/VADjNtEYptU+inlufAFYcWdHlwNfZOEnOOQrZrcyJCQ==}
-
-  pug@3.0.4:
-    resolution: {integrity: sha512-kFfq5mMzrS7+wrl5pLJzZEzemx34OQ0w4SARfhy/3yxTlhbstsudDwJzhf1hP02yHzbjoVMSXUj/Sz6RNfMyXg==}
-
   pump@3.0.4:
     resolution: {integrity: sha512-VS7sjc6KR7e1ukRFhQSY5LM2uBWAUPiOPa/A3mkKmiMwSmRFUITt0xuj+/lesgnCv+dPIEYlkzrcyXgquIHMcA==}
 
@@ -6723,10 +6778,6 @@ packages:
     resolution: {integrity: sha512-Kko+Y5XQ6fM+Ce3dq3m9YGxnacYZYl9cA1wZjaF3Vbry2L3i1qVg8+CAgNPsXRArPMUMCaOR7oa9Nqntc43JKA==}
     engines: {node: '>= 20.19.0'}
 
-  recast@0.23.21:
-    resolution: {integrity: sha512-mFAyJq9vUbSTARLZUvAEf1z3YxlvAwswbmxMx2mPA/MSm4KmpwvwvhsH/NIrZhyOuwD60Lzyw2qh83uCbgTPYw==}
-    engines: {node: '>= 4'}
-
   redis-errors@1.2.0:
     resolution: {integrity: sha512-1qny3OExCf0UvUV/5wpYKf2YwPcOqXzkwKKSmKHiE6ZMQs5heeE/c8eXK+PNllPvmjgAbfnsbpkGZWy8cBpn9w==}
     engines: {node: '>=4'}
@@ -7214,6 +7265,10 @@ packages:
   tiny-invariant@1.3.3:
     resolution: {integrity: sha512-+FbBPE1o9QAYvviau/qC5SE3caw21q3xkvWKBtja5vgqOWIHHJ3ioaq1VPfn/Szqctz2bU/oYeKd9/z5BL+PVg==}
 
+  tinybench@6.2.1:
+    resolution: {integrity: sha512-IAbQaPJIIdhVxi0mqy9lez1wEwje0UQf9F1vwtbelEG5Nbgn0nPOxCvU+mNeNS9gyJTAhrHp74CbUaSynQpZcQ==}
+    engines: {node: '>=20.0.0'}
+
   tinyclip@0.1.15:
     resolution: {integrity: sha512-uo33abH+Ays0xYaDysoBt494Hb3hsEczMpcC0MwFl773pazORx4fmvKhclhR1wonUbB6vvpRsvVMwnhfqeMc+A==}
     engines: {node: ^16.14.0 || >= 17.3.0}
@@ -7238,9 +7293,6 @@ packages:
     resolution: {integrity: sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA==}
     engines: {node: '>=0.6'}
 
-  token-stream@1.0.0:
-    resolution: {integrity: sha512-VSsyNPPW74RpHwR8Fc21uubwHY7wMDeJLys2IX5zJNih+OnAnaifKHo+1LHT7DAdloQ7apeaaWg8l7qnf/TnEg==}
-
   tosource@2.0.0-alpha.3:
     resolution: {integrity: sha512-KAB2lrSS48y91MzFPFuDg4hLbvDiyTjOVgaK7Erw+5AmZXNq4sFRVn8r6yxSLuNs15PaokrDRpS61ERY9uZOug==}
     engines: {node: '>=10'}
@@ -7267,9 +7319,6 @@ packages:
     peerDependencies:
       typescript: '>=4.8.4'
 
-  ts-map@1.0.3:
-    resolution: {integrity: sha512-vDWbsl26LIcPGmDpoVzjEP6+hvHZkBkLW7JpvwbCv/5IYPJlsbzCVXY3wsCeAxAUeTclNOUZxnLdGh3VBD/J6w==}
-
   tslib@2.8.1:
     resolution: {integrity: sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==}
 
@@ -7798,9 +7847,46 @@ packages:
       yaml:
         optional: true
 
-  void-elements@3.1.0:
-    resolution: {integrity: sha512-Dhxzh5HZuiHQhbvTW9AMetFfBHDMYpo23Uo9btPXgdYP+3T5S+p+jgNy7spra+veYhBP2dCSgxR/i2Y02h5/6w==}
-    engines: {node: '>=0.10.0'}
+  vitest@5.0.3:
+    resolution: {integrity: sha512-xMw97S3rjdtj5dkVat7jCsqWBpvchs3RlpQctUqwJD0KkERk40vz2fJ77lDwW/Vzh/pk18eItYAzkodhSes3jQ==}
+    engines: {node: ^22.12.0 || ^24.0.0 || >=26.0.0}
+    hasBin: true
+    peerDependencies:
+      '@edge-runtime/vm': '*'
+      '@opentelemetry/api': ^1.9.0
+      '@types/node': ^22.0.0 || >=24.0.0
+      '@vitest/browser-playwright': 5.0.3
+      '@vitest/browser-preview': 5.0.3
+      '@vitest/browser-webdriverio': ^5.0.0-beta.5 || >=5.0.0
+      '@vitest/coverage-istanbul': 5.0.3
+      '@vitest/coverage-v8': 5.0.3
+      '@vitest/ui': 5.0.3
+      happy-dom: '*'
+      jsdom: '*'
+      vite: ^6.4.0 || ^7.0.0 || ^8.0.0
+    peerDependenciesMeta:
+      '@edge-runtime/vm':
+        optional: true
+      '@opentelemetry/api':
+        optional: true
+      '@types/node':
+        optional: true
+      '@vitest/browser-playwright':
+        optional: true
+      '@vitest/browser-preview':
+        optional: true
+      '@vitest/browser-webdriverio':
+        optional: true
+      '@vitest/coverage-istanbul':
+        optional: true
+      '@vitest/coverage-v8':
+        optional: true
+      '@vitest/ui':
+        optional: true
+      happy-dom:
+        optional: true
+      jsdom:
+        optional: true
 
   vscode-uri@3.2.0:
     resolution: {integrity: sha512-m2gXo3bn0G1kT9InzMf07fTbqMbGtyckj3bH5ktLO+1Ssv+yiATZ4dhwaQv9UZWxJh6E9IFGnQyjgWVDWVBDrg==}
@@ -7833,22 +7919,12 @@ packages:
   vue-devtools-stub@0.1.0:
     resolution: {integrity: sha512-RutnB7X8c5hjq39NceArgXg28WZtZpGc3+J16ljMiYnFhKvd8hITxSWQSQ5bvldxMDU6gG5mkxl1MTQLXckVSQ==}
 
-  vue-docgen-api@4.79.2:
-    resolution: {integrity: sha512-n9ENAcs+40awPZMsas7STqjkZiVlIjxIKgiJr5rSohDP0/JCrD9VtlzNojafsA1MChm/hz2h3PDtUedx3lbgfA==}
-    peerDependencies:
-      vue: '>=2'
-
   vue-i18n@11.4.13:
     resolution: {integrity: sha512-2G7LC9XcdZ0IljFib7lKGHNiBBOTv6HO+2bnBaOiQgDYZ+uUnqSpuED5DbBo1t7su50o/WRGn+ZfDQTGd26xEw==}
     engines: {node: '>= 22'}
     peerDependencies:
       vue: ^3.0.0
 
-  vue-inbrowser-compiler-independent-utils@4.71.1:
-    resolution: {integrity: sha512-K3wt3iVmNGaFEOUR4JIThQRWfqokxLfnPslD41FDZB2ajXp789+wCqJyGYlIFsvEQ2P61PInw6/ph5iiqg51gg==}
-    peerDependencies:
-      vue: '>=2'
-
   vue-router@5.3.1:
     resolution: {integrity: sha512-GDBZzgmILxA/kFnkFbJjQZdZ2QQbngnIMMuoUcjhZIfH1RGMaPjPwX5ASnV38qamuA9uhO0RDjSBHTDNG2uXyQ==}
     peerDependencies:
@@ -7893,6 +7969,10 @@ packages:
   webpack-virtual-modules@0.6.2:
     resolution: {integrity: sha512-66/V2i5hQanC51vBQKPH4aI8NMAcBW59FVBs+rC7eGHupMyfn34q7rZIE+ETlJ+XTevqfUhVVBgSUNSW2flEUQ==}
 
+  whatwg-mimetype@3.0.0:
+    resolution: {integrity: sha512-nt+N2dzIutVRxARx1nghPKGv1xHikU7HKdfafKkLNLindmPU/ch3U31NOCGGA/dmPcmb1VlofO0vnKAcsm0o/Q==}
+    engines: {node: '>=12'}
+
   whatwg-url@5.0.0:
     resolution: {integrity: sha512-saE57nupxk6v3HY35+jzBwYa0rKSy0XR8JSxZPwgLr7ys0IBzhGviA1/TUGJLmSVqs8pb9AnvICXEuOHLprYTw==}
 
@@ -7914,9 +7994,10 @@ packages:
     engines: {node: ^20.17.0 || >=22.9.0}
     hasBin: true
 
-  with@7.0.2:
-    resolution: {integrity: sha512-RNGKj82nUPg3g5ygxkQl0R937xLyho1J24ItRCBTr/m1YnZkzJy1hUiHUJrc/VlsDQzsCnInEGSg3bci0Lmd4w==}
-    engines: {node: '>= 10.0.0'}
+  why-is-node-running@3.2.1:
+    resolution: {integrity: sha512-Tb2FUhB4vUsGQlfSquQLYkApkuPAFQXGFzxWKHHumVz2dK+X1RUm/HnID4+TfIGYJ1kTcwOaCk/buYCEJr6YjQ==}
+    engines: {node: '>=20.11'}
+    hasBin: true
 
   word-wrap@1.2.5:
     resolution: {integrity: sha512-BN22B5eaMMI9UMtjrGd5g5eCYPpCPDUy0FJXbYsaT5zYxjFOckS53SQDE3pWkVoWpHXVb3BrYcEN4Twa55B5cA==}
@@ -8069,11 +8150,11 @@ snapshots:
     dependencies:
       json-schema: 0.4.0
 
-  '@ai-sdk/vue@4.0.128(vue@3.5.43(typescript@5.9.3))(zod@4.6.5)':
+  '@ai-sdk/vue@4.0.128(@vue/test-utils@2.5.1(@vue/compiler-dom@3.5.43)(@vue/server-renderer@3.5.43)(vue@3.5.43(typescript@5.9.3)))(vue@3.5.43(typescript@5.9.3))(zod@4.6.5)':
     dependencies:
       '@ai-sdk/provider-utils': 5.0.54(zod@4.6.5)
       ai: 7.0.128(zod@4.6.5)
-      swrv: 1.3.0(vue@3.5.43(typescript@5.9.3))
+      swrv: 1.3.0(@vue/test-utils@2.5.1(@vue/compiler-dom@3.5.43)(@vue/server-renderer@3.5.43)(vue@3.5.43(typescript@5.9.3)))(vue@3.5.43(typescript@5.9.3))
       vue: 3.5.43(typescript@5.9.3)
     transitivePeerDependencies:
       - '@vue/test-utils'
@@ -8260,10 +8341,11 @@ snapshots:
       '@babel/helper-string-parser': 7.29.7
       '@babel/helper-validator-identifier': 7.29.7
 
-  '@bomb.sh/tab@0.0.19(cac@6.7.14)(citty@0.2.2)':
+  '@bomb.sh/tab@0.0.19(cac@6.7.14)(citty@0.2.2)(commander@14.0.3)':
     optionalDependencies:
       cac: 6.7.14
       citty: 0.2.2
+      commander: 14.0.3
 
   '@cacheable/memory@2.2.0':
     dependencies:
@@ -9112,6 +9194,10 @@ snapshots:
 
   '@kwsites/promise-deferred@1.1.1': {}
 
+  '@lucide/vue@1.52.0(vue@3.5.43(typescript@5.9.3))':
+    dependencies:
+      vue: 3.5.43(typescript@5.9.3)
+
   '@manypkg/find-root@1.1.0':
     dependencies:
       '@babel/runtime': 7.29.7
@@ -9209,9 +9295,9 @@ snapshots:
       '@nodelib/fs.scandir': 2.1.5
       fastq: 1.20.3
 
-  '@nuxt/cli@3.37.0(@nuxt/schema@4.4.8)(@parcel/watcher@2.6.0)(cac@6.7.14)(magicast@0.5.5)':
+  '@nuxt/cli@3.37.0(@nuxt/schema@4.4.8)(@parcel/watcher@2.6.0)(cac@6.7.14)(commander@14.0.3)(magicast@0.5.5)':
     dependencies:
-      '@bomb.sh/tab': 0.0.19(cac@6.7.14)(citty@0.2.2)
+      '@bomb.sh/tab': 0.0.19(cac@6.7.14)(citty@0.2.2)(commander@14.0.3)
       '@clack/prompts': 1.8.1
       c12: 3.3.4(magicast@0.5.5)
       citty: 0.2.2
@@ -9248,10 +9334,10 @@ snapshots:
       - magicast
       - supports-color
 
-  '@nuxt/content@3.16.1(@nuxt/schema@4.6.0)(@oxc-project/types@0.152.0)(better-sqlite3@12.11.1)(confbox@0.2.4)(dotenv@17.4.2)(esbuild@0.28.2)(giget@3.3.1)(magic-string@0.30.21)(magicast@0.5.5)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))':
+  '@nuxt/content@3.16.1(@nuxt/schema@4.6.0)(@oxc-project/types@0.152.0)(better-sqlite3@12.11.1)(confbox@0.2.4)(dotenv@17.4.2)(esbuild@0.28.2)(giget@3.3.1)(magic-string@1.4.3)(magicast@0.5.5)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))':
     dependencies:
-      '@nuxt/kit': 4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@0.30.21)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
-      '@nuxtjs/mdc': 0.23.2(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@0.30.21)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
+      '@nuxt/kit': 4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
+      '@nuxtjs/mdc': 0.23.2(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
       '@shikijs/langs': 4.5.0
       '@sqlite.org/sqlite-wasm': 3.53.0-build1
       '@standard-schema/spec': 1.1.0
@@ -9291,7 +9377,7 @@ snapshots:
       std-env: 4.3.0
       tinyglobby: 0.2.17
       ufo: 1.6.4
-      unctx: 3.0.1(magic-string@0.30.21)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
+      unctx: 3.0.1(magic-string@1.4.3)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
       unified: 11.0.5
       unist-util-stringify-position: 4.0.0
       unist-util-visit: 5.1.0
@@ -9360,9 +9446,9 @@ snapshots:
       - rolldown
       - unplugin
 
-  '@nuxt/devtools-kit@4.0.0-alpha.7(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@0.30.21)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))':
+  '@nuxt/devtools-kit@4.0.0-alpha.7(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))':
     dependencies:
-      '@nuxt/kit': 4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@0.30.21)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
+      '@nuxt/kit': 4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
       tinyexec: 1.3.1
       vite: 8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)
     transitivePeerDependencies:
@@ -9377,9 +9463,9 @@ snapshots:
       - rolldown
       - unplugin
 
-  '@nuxt/devtools-kit@4.0.0-alpha.7(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@0.30.21)(mlly@1.8.2)(oxc-parser@0.141.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))':
+  '@nuxt/devtools-kit@4.0.0-alpha.7(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.141.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))':
     dependencies:
-      '@nuxt/kit': 4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@0.30.21)(mlly@1.8.2)(oxc-parser@0.141.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
+      '@nuxt/kit': 4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.141.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
       tinyexec: 1.3.1
       vite: 8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)
     transitivePeerDependencies:
@@ -9578,10 +9664,10 @@ snapshots:
       - vite
       - vue
 
-  '@nuxt/image@2.1.0(@nuxt/schema@4.6.0)(@types/node@26.6.4)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@0.30.21)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))(unstorage@1.17.5(db0@0.3.4(better-sqlite3@12.11.1))(ioredis@5.11.1))':
+  '@nuxt/image@2.1.0(@nuxt/schema@4.6.0)(@types/node@26.6.4)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))(unstorage@1.17.5(db0@0.3.4(better-sqlite3@12.11.1))(ioredis@5.11.1))':
     dependencies:
       '@noble/hashes': 2.4.0
-      '@nuxt/kit': 4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@0.30.21)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
+      '@nuxt/kit': 4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
       defu: 6.1.7
       h3: 1.15.11
       image-meta: 0.2.2
@@ -9664,39 +9750,6 @@ snapshots:
       - magic-string
       - unplugin
 
-  '@nuxt/kit@4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@0.30.21)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))':
-    dependencies:
-      consola: 3.4.2
-      defu: 6.1.7
-      destr: 2.0.5
-      errx: 0.2.2
-      exsolve: 1.1.3
-      ignore: 7.0.12
-      klona: 2.0.6
-      microdiff: 1.6.0
-      nostics: 1.3.0
-      package-manager-detector: 1.9.0
-      pathe: 2.0.3
-      rc9: 3.1.0
-      scule: 1.3.0
-      std-env: 4.3.0
-      tinyexec: 1.3.1
-      tinyglobby: 0.2.17
-      unctx: 3.0.1(magic-string@0.30.21)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
-      verkit: 0.5.0
-    optionalDependencies:
-      '@nuxt/schema': 4.6.0
-      confbox: 0.2.4
-      dotenv: 17.4.2
-      giget: 3.3.1
-      jiti: 2.7.0
-      mlly: 1.8.2
-      oxc-parser: 0.133.0
-      rolldown: 1.2.12
-    transitivePeerDependencies:
-      - magic-string
-      - unplugin
-
   '@nuxt/kit@4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@0.30.21)(mlly@1.8.2)(oxc-parser@0.139.0)(rolldown@1.2.12)(unplugin@2.3.11)':
     dependencies:
       consola: 3.4.2
@@ -9796,6 +9849,39 @@ snapshots:
       - magic-string
       - unplugin
 
+  '@nuxt/kit@4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.141.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))':
+    dependencies:
+      consola: 3.4.2
+      defu: 6.1.7
+      destr: 2.0.5
+      errx: 0.2.2
+      exsolve: 1.1.3
+      ignore: 7.0.12
+      klona: 2.0.6
+      microdiff: 1.6.0
+      nostics: 1.3.0
+      package-manager-detector: 1.9.0
+      pathe: 2.0.3
+      rc9: 3.1.0
+      scule: 1.3.0
+      std-env: 4.3.0
+      tinyexec: 1.3.1
+      tinyglobby: 0.2.17
+      unctx: 3.0.1(magic-string@1.4.3)(oxc-parser@0.141.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
+      verkit: 0.5.0
+    optionalDependencies:
+      '@nuxt/schema': 4.6.0
+      confbox: 0.2.4
+      dotenv: 17.4.2
+      giget: 3.3.1
+      jiti: 2.7.0
+      mlly: 1.8.2
+      oxc-parser: 0.141.0
+      rolldown: 1.2.12
+    transitivePeerDependencies:
+      - magic-string
+      - unplugin
+
   '@nuxt/kit@4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.151.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))':
     dependencies:
       consola: 3.4.2
@@ -9829,7 +9915,7 @@ snapshots:
       - magic-string
       - unplugin
 
-  '@nuxt/nitro-server@4.4.8(7c5f3e276f30fa96660ce41fb115fe08)':
+  '@nuxt/nitro-server@4.4.8(de6d13e879b665d0b4d1abf7f9393f0b)':
     dependencies:
       '@nuxt/devalue': 2.0.2
       '@nuxt/kit': 4.4.8(magicast@0.5.5)
@@ -9847,7 +9933,7 @@ snapshots:
       klona: 2.0.6
       mocked-exports: 0.1.1
       nitropack: 2.13.4(@parcel/watcher@2.6.0)(better-sqlite3@12.11.1)(oxc-parser@0.133.0)(rolldown@1.2.12)(srvx@0.11.22)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))
-      nuxt: 4.4.8(@babel/plugin-syntax-jsx@7.29.7(@babel/core@7.29.7))(@babel/plugin-syntax-typescript@7.29.7(@babel/core@7.29.7))(@oxc-project/types@0.152.0)(@parcel/watcher@2.6.0)(@types/node@26.6.4)(@vue/compiler-sfc@3.5.43)(better-sqlite3@12.11.1)(cac@6.7.14)(confbox@0.2.4)(db0@0.3.4(better-sqlite3@12.11.1))(dotenv@17.4.2)(esbuild@0.28.2)(eslint@10.12.0(jiti@2.7.0))(giget@3.3.1)(ioredis@5.11.1)(lightningcss@1.33.0)(magicast@0.5.5)(optionator@0.9.4)(rolldown@1.2.12)(rollup-plugin-visualizer@7.1.1(rolldown@1.2.12)(rollup@4.64.0))(rollup@4.64.0)(sass@1.105.1)(srvx@0.11.22)(terser@5.51.2)(typescript@5.9.3)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))(vue-tsc@3.3.12(typescript@5.9.3))(yaml@2.9.1)
+      nuxt: 4.4.8(@babel/plugin-syntax-jsx@7.29.7(@babel/core@7.29.7))(@babel/plugin-syntax-typescript@7.29.7(@babel/core@7.29.7))(@oxc-project/types@0.152.0)(@parcel/watcher@2.6.0)(@types/node@26.6.4)(@vue/compiler-sfc@3.5.43)(better-sqlite3@12.11.1)(cac@6.7.14)(commander@14.0.3)(confbox@0.2.4)(db0@0.3.4(better-sqlite3@12.11.1))(dotenv@17.4.2)(esbuild@0.28.2)(eslint@10.12.0(jiti@2.7.0))(giget@3.3.1)(ioredis@5.11.1)(lightningcss@1.33.0)(magicast@0.5.5)(optionator@0.9.4)(rolldown@1.2.12)(rollup-plugin-visualizer@7.1.1(rolldown@1.2.12)(rollup@4.64.0))(rollup@4.64.0)(sass@1.105.1)(srvx@0.11.22)(terser@5.51.2)(typescript@5.9.3)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))(vue-tsc@3.3.12(typescript@5.9.3))(yaml@2.9.1)
       nypm: 0.6.10
       ohash: 2.0.12
       pathe: 2.0.3
@@ -9934,7 +10020,7 @@ snapshots:
       rc9: 3.1.0
       std-env: 4.3.0
 
-  '@nuxt/ui@4.11.3(8fcd5060c01dbb08a620ed8a677cd1b0)':
+  '@nuxt/ui@4.11.3(1ab40aaa47b88302858324756ba27a26)':
     dependencies:
       '@floating-ui/dom': 1.8.0
       '@iconify/vue': 5.0.3(vue@3.5.43(typescript@5.9.3))
@@ -9996,14 +10082,14 @@ snapshots:
       typescript: 5.9.3
       ufo: 1.6.4
       unplugin: 3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))
-      unplugin-auto-import: 21.1.0(@nuxt/kit@4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@0.30.21)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))))(@vueuse/core@14.4.0(vue@3.5.43(typescript@5.9.3)))(esbuild@0.28.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))
-      unplugin-vue-components: 32.1.0(@nuxt/kit@4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@0.30.21)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))))(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))(vue@3.5.43(typescript@5.9.3))
+      unplugin-auto-import: 21.1.0(@nuxt/kit@4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))))(@vueuse/core@14.4.0(vue@3.5.43(typescript@5.9.3)))(esbuild@0.28.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))
+      unplugin-vue-components: 32.1.0(@nuxt/kit@4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))))(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))(vue@3.5.43(typescript@5.9.3))
       vaul-vue: 0.4.1(reka-ui@2.10.5(vue@3.5.43(typescript@5.9.3)))(vue@3.5.43(typescript@5.9.3))
       vue-component-type-helpers: 3.3.12
     optionalDependencies:
       '@internationalized/date': 3.12.4
       '@internationalized/number': 3.6.8
-      '@nuxt/content': 3.16.1(@nuxt/schema@4.6.0)(@oxc-project/types@0.152.0)(better-sqlite3@12.11.1)(confbox@0.2.4)(dotenv@17.4.2)(esbuild@0.28.2)(giget@3.3.1)(magic-string@0.30.21)(magicast@0.5.5)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))
+      '@nuxt/content': 3.16.1(@nuxt/schema@4.6.0)(@oxc-project/types@0.152.0)(better-sqlite3@12.11.1)(confbox@0.2.4)(dotenv@17.4.2)(esbuild@0.28.2)(giget@3.3.1)(magic-string@1.4.3)(magicast@0.5.5)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))
       ai: 7.0.128(zod@4.6.5)
       vue-router: 5.3.1(@vue/compiler-sfc@3.5.43)(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))(vue@3.5.43(typescript@5.9.3))
       zod: 4.6.5
@@ -10062,7 +10148,7 @@ snapshots:
       - vue
       - webpack
 
-  '@nuxt/vite-builder@4.4.8(8d87756da47842bbb77226aff6f186dc)':
+  '@nuxt/vite-builder@4.4.8(691ba7ab3b53df2d8a6011c8c80590d7)':
     dependencies:
       '@nuxt/kit': 4.4.8(magicast@0.5.5)
       '@rollup/plugin-replace': 6.0.3(rollup@4.64.0)
@@ -10080,7 +10166,7 @@ snapshots:
       magic-string: 0.30.21
       mlly: 1.8.2
       mocked-exports: 0.1.1
-      nuxt: 4.4.8(@babel/plugin-syntax-jsx@7.29.7(@babel/core@7.29.7))(@babel/plugin-syntax-typescript@7.29.7(@babel/core@7.29.7))(@oxc-project/types@0.152.0)(@parcel/watcher@2.6.0)(@types/node@26.6.4)(@vue/compiler-sfc@3.5.43)(better-sqlite3@12.11.1)(cac@6.7.14)(confbox@0.2.4)(db0@0.3.4(better-sqlite3@12.11.1))(dotenv@17.4.2)(esbuild@0.28.2)(eslint@10.12.0(jiti@2.7.0))(giget@3.3.1)(ioredis@5.11.1)(lightningcss@1.33.0)(magicast@0.5.5)(optionator@0.9.4)(rolldown@1.2.12)(rollup-plugin-visualizer@7.1.1(rolldown@1.2.12)(rollup@4.64.0))(rollup@4.64.0)(sass@1.105.1)(srvx@0.11.22)(terser@5.51.2)(typescript@5.9.3)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))(vue-tsc@3.3.12(typescript@5.9.3))(yaml@2.9.1)
+      nuxt: 4.4.8(@babel/plugin-syntax-jsx@7.29.7(@babel/core@7.29.7))(@babel/plugin-syntax-typescript@7.29.7(@babel/core@7.29.7))(@oxc-project/types@0.152.0)(@parcel/watcher@2.6.0)(@types/node@26.6.4)(@vue/compiler-sfc@3.5.43)(better-sqlite3@12.11.1)(cac@6.7.14)(commander@14.0.3)(confbox@0.2.4)(db0@0.3.4(better-sqlite3@12.11.1))(dotenv@17.4.2)(esbuild@0.28.2)(eslint@10.12.0(jiti@2.7.0))(giget@3.3.1)(ioredis@5.11.1)(lightningcss@1.33.0)(magicast@0.5.5)(optionator@0.9.4)(rolldown@1.2.12)(rollup-plugin-visualizer@7.1.1(rolldown@1.2.12)(rollup@4.64.0))(rollup@4.64.0)(sass@1.105.1)(srvx@0.11.22)(terser@5.51.2)(typescript@5.9.3)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))(vue-tsc@3.3.12(typescript@5.9.3))(yaml@2.9.1)
       nypm: 0.6.10
       pathe: 2.0.3
       pkg-types: 2.3.3
@@ -10214,10 +10300,10 @@ snapshots:
       - vue
       - webpack
 
-  '@nuxtjs/mcp-toolkit@0.22.0(@nuxt/schema@4.6.0)(@vue/compiler-sfc@3.5.43)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(h3@1.15.11)(jiti@2.7.0)(magic-string@0.30.21)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(rollup@4.64.0)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))(vue@3.5.43(typescript@5.9.3))(zod@4.6.5)':
+  '@nuxtjs/mcp-toolkit@0.22.0(@nuxt/schema@4.6.0)(@vue/compiler-sfc@3.5.43)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(h3@1.15.11)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(rollup@4.64.0)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))(vue@3.5.43(typescript@5.9.3))(zod@4.6.5)':
     dependencies:
       '@modelcontextprotocol/sdk': 1.32.1(zod@4.6.5)
-      '@nuxt/kit': 4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@0.30.21)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
+      '@nuxt/kit': 4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
       '@vitejs/plugin-vue': 6.0.9(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))(vue@3.5.43(typescript@5.9.3))
       h3: 1.15.11
       tinyglobby: 0.2.17
@@ -10242,9 +10328,9 @@ snapshots:
       - supports-color
       - unplugin
 
-  '@nuxtjs/mdc@0.23.2(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@0.30.21)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))':
+  '@nuxtjs/mdc@0.23.2(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))':
     dependencies:
-      '@nuxt/kit': 4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@0.30.21)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
+      '@nuxt/kit': 4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
       '@shikijs/core': 4.5.0
       '@shikijs/engine-javascript': 4.5.0
       '@shikijs/langs': 4.5.0
@@ -10301,15 +10387,15 @@ snapshots:
       - supports-color
       - unplugin
 
-  '@nuxtjs/robots@6.2.4(22ba0ed89dd6406cbb938bb1364fc5c5)':
+  '@nuxtjs/robots@6.2.4(1fa5557b7a9b0a358862a4710025e777)':
     dependencies:
       '@fingerprintjs/botd': 2.0.0
-      '@nuxt/kit': 4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@0.30.21)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
+      '@nuxt/kit': 4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
       consola: 3.4.2
       defu: 6.1.7
       h3: 1.15.11
-      nuxt-site-config: 4.2.3(22ba0ed89dd6406cbb938bb1364fc5c5)
-      nuxtseo-shared: 5.3.16(744ff7fd9a152b5ba76bd41516e4c401)
+      nuxt-site-config: 4.2.3(1fa5557b7a9b0a358862a4710025e777)
+      nuxtseo-shared: 5.3.16(2583b91d8de450fb4fcddd6ee273ef79)
       pathe: 2.0.3
       pkg-types: 2.3.3
       ufo: 1.6.4
@@ -10330,13 +10416,13 @@ snapshots:
       - vite
       - vue
 
-  '@nuxtjs/sitemap@8.6.1(a69eb50999abd1859c12f282dbdb225a)':
+  '@nuxtjs/sitemap@8.6.1(abe2f75b5aa07b6602caa1860dcba6f9)':
     dependencies:
-      '@nuxt/kit': 4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@0.30.21)(mlly@1.8.2)(oxc-parser@0.141.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
+      '@nuxt/kit': 4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.141.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
       consola: 3.4.2
       defu: 6.1.7
-      nuxt-site-config: 4.2.3(6be24db654c942a14816f18d0d34b432)
-      nuxtseo-shared: 5.3.16(f4b45a8c7d2f2bc1b5d16b0c37217a1c)
+      nuxt-site-config: 4.2.3(0155943dcfcb3e8f1e6ee7ac6748e13b)
+      nuxtseo-shared: 5.3.16(be474f164f65517a791b10007c1d9f36)
       ofetch: 1.5.1
       oxc-parser: 0.141.0
       oxc-walker: 1.1.1(@oxc-project/types@0.152.0)(oxc-parser@0.141.0)(rolldown@1.2.12)
@@ -10363,6 +10449,8 @@ snapshots:
       - vite
       - vue
 
+  '@one-ini/wasm@0.2.1': {}
+
   '@oxc-minify/binding-android-arm-eabi@0.133.0':
     optional: true
 
@@ -10879,6 +10967,10 @@ snapshots:
   '@pkgjs/parseargs@0.11.0':
     optional: true
 
+  '@playwright/test@1.63.0':
+    dependencies:
+      playwright: 1.63.0
+
   '@polka/url@1.0.0-next.29': {}
 
   '@poppinss/colors@4.1.6':
@@ -11530,10 +11622,17 @@ snapshots:
       tslib: 2.8.1
     optional: true
 
+  '@types/chai@5.2.3':
+    dependencies:
+      '@types/deep-eql': 4.0.2
+      assertion-error: 2.0.1
+
   '@types/debug@4.1.13':
     dependencies:
       '@types/ms': 2.1.0
 
+  '@types/deep-eql@4.0.2': {}
+
   '@types/esrecurse@4.3.1': {}
 
   '@types/estree@1.0.9': {}
@@ -11574,6 +11673,12 @@ snapshots:
 
   '@types/web-bluetooth@0.0.21': {}
 
+  '@types/whatwg-mimetype@3.0.2': {}
+
+  '@types/ws@8.18.2':
+    dependencies:
+      '@types/node': 26.6.4
+
   '@typescript-eslint/project-service@8.71.1(typescript@5.9.3)':
     dependencies:
       '@typescript-eslint/tsconfig-utils': 8.71.1(typescript@5.9.3)
@@ -11712,6 +11817,17 @@ snapshots:
       vite: 8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)
       vue: 3.5.43(typescript@5.9.3)
 
+  '@vitest/mocker@5.0.3(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))':
+    dependencies:
+      '@jridgewell/trace-mapping': 0.3.31
+      '@vitest/spy': 5.0.3
+      estree-walker: 3.0.3
+      magic-string: 1.4.3
+    optionalDependencies:
+      vite: 8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)
+
+  '@vitest/spy@5.0.3': {}
+
   '@volar/language-core@2.4.28':
     dependencies:
       '@volar/source-map': 2.4.28
@@ -11848,6 +11964,15 @@ snapshots:
 
   '@vue/shared@3.5.43': {}
 
+  '@vue/test-utils@2.5.1(@vue/compiler-dom@3.5.43)(@vue/server-renderer@3.5.43)(vue@3.5.43(typescript@5.9.3))':
+    dependencies:
+      '@vue/compiler-dom': 3.5.43
+      js-beautify: 2.0.3
+      vue: 3.5.43(typescript@5.9.3)
+      vue-component-type-helpers: 3.3.12
+    optionalDependencies:
+      '@vue/server-renderer': 3.5.43
+
   '@vueuse/core@10.11.1(vue@3.5.43(typescript@5.9.3))':
     dependencies:
       '@types/web-bluetooth': 0.0.20
@@ -11907,6 +12032,8 @@ snapshots:
 
   abbrev@3.0.1: {}
 
+  abbrev@5.0.0: {}
+
   abort-controller@3.0.0:
     dependencies:
       event-target-shim: 5.0.1
@@ -11924,8 +12051,6 @@ snapshots:
     dependencies:
       acorn: 8.19.0
 
-  acorn@7.4.1: {}
-
   acorn@8.19.0: {}
 
   agent-base@7.1.4: {}
@@ -12014,19 +12139,13 @@ snapshots:
 
   array-union@2.1.0: {}
 
-  asap@2.0.6: {}
-
-  assert-never@1.4.0: {}
+  assertion-error@2.0.1: {}
 
   ast-kit@2.2.0:
     dependencies:
       '@babel/parser': 7.29.9
       pathe: 2.0.3
 
-  ast-types@0.16.3:
-    dependencies:
-      tslib: 2.8.1
-
   ast-walker-scope@0.9.0:
     dependencies:
       '@babel/parser': 7.29.9
@@ -12054,10 +12173,6 @@ snapshots:
 
   b4a@1.9.0: {}
 
-  babel-walk@3.0.0-canary-5:
-    dependencies:
-      '@babel/types': 7.29.8
-
   bail@2.0.2: {}
 
   balanced-match@1.0.2: {}
@@ -12160,6 +12275,10 @@ snapshots:
 
   buffer-from@1.1.2: {}
 
+  buffer-image-size@0.6.4:
+    dependencies:
+      '@types/node': 26.6.4
+
   buffer@5.7.1:
     dependencies:
       base64-js: 1.5.1
@@ -12231,6 +12350,8 @@ snapshots:
 
   ccount@2.0.1: {}
 
+  chai@6.3.0: {}
+
   char-regex@1.0.2: {}
 
   character-entities-html4@2.1.0: {}
@@ -12239,10 +12360,6 @@ snapshots:
 
   character-entities@2.0.2: {}
 
-  character-parser@2.2.0:
-    dependencies:
-      is-regex: 1.2.1
-
   character-reference-invalid@2.0.1: {}
 
   chardet@2.2.0: {}
@@ -12301,6 +12418,8 @@ snapshots:
 
   commander@11.1.0: {}
 
+  commander@14.0.3: {}
+
   commander@2.20.3: {}
 
   commondir@1.0.1: {}
@@ -12323,12 +12442,12 @@ snapshots:
 
   confbox@0.3.1: {}
 
-  consola@3.4.2: {}
-
-  constantinople@4.0.1:
+  config-chain@1.1.13:
     dependencies:
-      '@babel/parser': 7.29.9
-      '@babel/types': 7.29.8
+      ini: 1.3.8
+      proto-list: 1.2.4
+
+  consola@3.4.2: {}
 
   content-disposition@1.1.0: {}
 
@@ -12518,26 +12637,24 @@ snapshots:
     dependencies:
       path-type: 4.0.0
 
-  doctypes@1.1.0: {}
-
-  docus@5.14.0(db3a3babb3e1a5f38f7fe64c400fed97):
+  docus@5.14.0(f92feb3e0732c978b98957e5210d7bcc):
     dependencies:
       '@ai-sdk/gateway': 4.0.104(zod@4.6.5)
       '@ai-sdk/mcp': 2.0.67(zod@4.6.5)
-      '@ai-sdk/vue': 4.0.128(vue@3.5.43(typescript@5.9.3))(zod@4.6.5)
+      '@ai-sdk/vue': 4.0.128(@vue/test-utils@2.5.1(@vue/compiler-dom@3.5.43)(@vue/server-renderer@3.5.43)(vue@3.5.43(typescript@5.9.3)))(vue@3.5.43(typescript@5.9.3))(zod@4.6.5)
       '@comark/vue': 0.7.0(shiki@4.5.0)(vue@3.5.43(typescript@5.9.3))
       '@iconify-json/lucide': 1.2.140
       '@iconify-json/simple-icons': 1.2.99
       '@iconify-json/vscode-icons': 1.2.85
-      '@nuxt/content': 3.16.1(@nuxt/schema@4.6.0)(@oxc-project/types@0.152.0)(better-sqlite3@12.11.1)(confbox@0.2.4)(dotenv@17.4.2)(esbuild@0.28.2)(giget@3.3.1)(magic-string@0.30.21)(magicast@0.5.5)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))
-      '@nuxt/image': 2.1.0(@nuxt/schema@4.6.0)(@types/node@26.6.4)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@0.30.21)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))(unstorage@1.17.5(db0@0.3.4(better-sqlite3@12.11.1))(ioredis@5.11.1))
-      '@nuxt/kit': 4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@0.30.21)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
-      '@nuxt/ui': 4.11.3(8fcd5060c01dbb08a620ed8a677cd1b0)
+      '@nuxt/content': 3.16.1(@nuxt/schema@4.6.0)(@oxc-project/types@0.152.0)(better-sqlite3@12.11.1)(confbox@0.2.4)(dotenv@17.4.2)(esbuild@0.28.2)(giget@3.3.1)(magic-string@1.4.3)(magicast@0.5.5)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))
+      '@nuxt/image': 2.1.0(@nuxt/schema@4.6.0)(@types/node@26.6.4)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))(unstorage@1.17.5(db0@0.3.4(better-sqlite3@12.11.1))(ioredis@5.11.1))
+      '@nuxt/kit': 4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
+      '@nuxt/ui': 4.11.3(1ab40aaa47b88302858324756ba27a26)
       '@nuxtjs/i18n': 10.6.0(@nuxt/schema@4.6.0)(@vue/compiler-dom@3.5.43)(db0@0.3.4(better-sqlite3@12.11.1))(dotenv@17.4.2)(esbuild@0.28.2)(eslint@10.12.0(jiti@2.7.0))(giget@3.3.1)(ioredis@5.11.1)(jiti@2.7.0)(rolldown@1.2.12)(rollup@4.64.0)(typescript@5.9.3)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))(vue@3.5.43(typescript@5.9.3))
-      '@nuxtjs/mcp-toolkit': 0.22.0(@nuxt/schema@4.6.0)(@vue/compiler-sfc@3.5.43)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(h3@1.15.11)(jiti@2.7.0)(magic-string@0.30.21)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(rollup@4.64.0)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))(vue@3.5.43(typescript@5.9.3))(zod@4.6.5)
-      '@nuxtjs/mdc': 0.23.2(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@0.30.21)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
-      '@nuxtjs/robots': 6.2.4(22ba0ed89dd6406cbb938bb1364fc5c5)
-      '@nuxtjs/sitemap': 8.6.1(a69eb50999abd1859c12f282dbdb225a)
+      '@nuxtjs/mcp-toolkit': 0.22.0(@nuxt/schema@4.6.0)(@vue/compiler-sfc@3.5.43)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(h3@1.15.11)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(rollup@4.64.0)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))(vue@3.5.43(typescript@5.9.3))(zod@4.6.5)
+      '@nuxtjs/mdc': 0.23.2(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
+      '@nuxtjs/robots': 6.2.4(1fa5557b7a9b0a358862a4710025e777)
+      '@nuxtjs/sitemap': 8.6.1(abe2f75b5aa07b6602caa1860dcba6f9)
       '@shikijs/core': 4.5.0
       '@shikijs/engine-javascript': 4.5.0
       '@shikijs/langs': 4.5.0
@@ -12552,11 +12669,11 @@ snapshots:
       git-url-parse: 16.1.0
       h3: 1.15.11
       motion-v: 2.6.0(@vueuse/core@15.0.0(vue@3.5.43(typescript@5.9.3)))(vue@3.5.43(typescript@5.9.3))
-      nuxt: 4.4.8(@babel/plugin-syntax-jsx@7.29.7(@babel/core@7.29.7))(@babel/plugin-syntax-typescript@7.29.7(@babel/core@7.29.7))(@oxc-project/types@0.152.0)(@parcel/watcher@2.6.0)(@types/node@26.6.4)(@vue/compiler-sfc@3.5.43)(better-sqlite3@12.11.1)(cac@6.7.14)(confbox@0.2.4)(db0@0.3.4(better-sqlite3@12.11.1))(dotenv@17.4.2)(esbuild@0.28.2)(eslint@10.12.0(jiti@2.7.0))(giget@3.3.1)(ioredis@5.11.1)(lightningcss@1.33.0)(magicast@0.5.5)(optionator@0.9.4)(rolldown@1.2.12)(rollup-plugin-visualizer@7.1.1(rolldown@1.2.12)(rollup@4.64.0))(rollup@4.64.0)(sass@1.105.1)(srvx@0.11.22)(terser@5.51.2)(typescript@5.9.3)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))(vue-tsc@3.3.12(typescript@5.9.3))(yaml@2.9.1)
-      nuxt-agent-discovery: 0.7.0(e9569477de85d8ec71c9f415afdb7fbf)
-      nuxt-llms: 0.2.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@0.30.21)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
-      nuxt-og-image: 6.9.1(370b99bbe49e4fc4310c887835077271)
-      nuxt-schema-org: 6.4.3(06339588bd6230de3030fc270006c9ef)
+      nuxt: 4.4.8(@babel/plugin-syntax-jsx@7.29.7(@babel/core@7.29.7))(@babel/plugin-syntax-typescript@7.29.7(@babel/core@7.29.7))(@oxc-project/types@0.152.0)(@parcel/watcher@2.6.0)(@types/node@26.6.4)(@vue/compiler-sfc@3.5.43)(better-sqlite3@12.11.1)(cac@6.7.14)(commander@14.0.3)(confbox@0.2.4)(db0@0.3.4(better-sqlite3@12.11.1))(dotenv@17.4.2)(esbuild@0.28.2)(eslint@10.12.0(jiti@2.7.0))(giget@3.3.1)(ioredis@5.11.1)(lightningcss@1.33.0)(magicast@0.5.5)(optionator@0.9.4)(rolldown@1.2.12)(rollup-plugin-visualizer@7.1.1(rolldown@1.2.12)(rollup@4.64.0))(rollup@4.64.0)(sass@1.105.1)(srvx@0.11.22)(terser@5.51.2)(typescript@5.9.3)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))(vue-tsc@3.3.12(typescript@5.9.3))(yaml@2.9.1)
+      nuxt-agent-discovery: 0.7.0(ca46561f50adf4368575834e85d08d49)
+      nuxt-llms: 0.2.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
+      nuxt-og-image: 6.9.1(97b88f392d295c90a093efa465ae7a22)
+      nuxt-schema-org: 6.4.3(68150d0998eb177d5aacae8cb44f8919)
       pathe: 2.0.3
       pkg-types: 2.3.3
       scule: 1.3.0
@@ -12743,6 +12860,13 @@ snapshots:
 
   eastasianwidth@0.2.0: {}
 
+  editorconfig@3.0.2:
+    dependencies:
+      '@one-ini/wasm': 0.2.1
+      commander: 14.0.3
+      minimatch: 10.2.6
+      semver: 7.8.5
+
   ee-first@1.1.1: {}
 
   electron-to-chromium@1.5.445: {}
@@ -13001,8 +13125,6 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  esm-resolve@1.0.11: {}
-
   espree@11.2.0:
     dependencies:
       acorn: 8.19.0
@@ -13067,6 +13189,8 @@ snapshots:
 
   expand-template@2.0.3: {}
 
+  expect-type@1.4.0: {}
+
   express-rate-limit@8.7.1(express@5.2.1):
     dependencies:
       debug: 4.4.3
@@ -13418,6 +13542,19 @@ snapshots:
       ufo: 1.6.4
       uncrypto: 0.1.3
 
+  happy-dom@20.14.5:
+    dependencies:
+      '@types/node': 26.6.4
+      '@types/whatwg-mimetype': 3.0.2
+      '@types/ws': 8.18.2
+      buffer-image-size: 0.6.4
+      entities: 7.0.1
+      whatwg-mimetype: 3.0.0
+      ws: 8.22.0
+    transitivePeerDependencies:
+      - bufferutil
+      - utf-8-validate
+
   has-property-descriptors@1.0.2:
     dependencies:
       es-define-property: 1.0.1
@@ -13428,8 +13565,6 @@ snapshots:
     dependencies:
       has-symbols: 1.1.0
 
-  hash-sum@2.0.0: {}
-
   hashery@1.5.1:
     dependencies:
       hookified: 1.15.1
@@ -13718,11 +13853,6 @@ snapshots:
 
   is-docker@3.0.0: {}
 
-  is-expression@4.0.0:
-    dependencies:
-      acorn: 7.4.1
-      object-assign: 4.1.1
-
   is-extglob@2.1.1: {}
 
   is-fullwidth-code-point@3.0.0: {}
@@ -13752,21 +13882,12 @@ snapshots:
 
   is-plain-obj@4.1.0: {}
 
-  is-promise@2.2.2: {}
-
   is-promise@4.0.0: {}
 
   is-reference@1.2.1:
     dependencies:
       '@types/estree': 1.0.9
 
-  is-regex@1.2.1:
-    dependencies:
-      call-bound: 1.0.4
-      gopd: 1.2.0
-      has-tostringtag: 1.0.2
-      hasown: 2.0.4
-
   is-ssh@1.4.1:
     dependencies:
       protocols: 2.0.2
@@ -13829,7 +13950,15 @@ snapshots:
 
   jose@6.2.12: {}
 
-  js-stringify@1.0.2: {}
+  js-beautify@2.0.3:
+    dependencies:
+      config-chain: 1.1.13
+      editorconfig: 3.0.2
+      glob: 13.0.6
+      js-cookie: 3.0.8
+      nopt: 10.0.1
+
+  js-cookie@3.0.8: {}
 
   js-tokens@10.0.0: {}
 
@@ -13878,11 +14007,6 @@ snapshots:
     optionalDependencies:
       graceful-fs: 4.2.11
 
-  jstransformer@1.0.0:
-    dependencies:
-      is-promise: 2.2.2
-      promise: 7.3.1
-
   keyv@5.6.0:
     dependencies:
       '@keyv/serialize': 1.1.1
@@ -14077,8 +14201,6 @@ snapshots:
     dependencies:
       yallist: 3.1.1
 
-  lru-cache@8.0.5: {}
-
   magic-regexp@0.10.0:
     dependencies:
       estree-walker: 3.0.3
@@ -14699,6 +14821,10 @@ snapshots:
 
   node-releases@2.0.57: {}
 
+  nopt@10.0.1:
+    dependencies:
+      abbrev: 5.0.0
+
   nopt@8.1.0:
     dependencies:
       abbrev: 3.0.1
@@ -14720,19 +14846,19 @@ snapshots:
     dependencies:
       boolbase: 1.0.0
 
-  nuxt-agent-discovery@0.7.0(e9569477de85d8ec71c9f415afdb7fbf):
+  nuxt-agent-discovery@0.7.0(ca46561f50adf4368575834e85d08d49):
     dependencies:
-      '@nuxt/kit': 4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@0.30.21)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
+      '@nuxt/kit': 4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
       defu: 6.1.7
       pathe: 2.0.3
       ufo: 1.6.4
       yaml: 2.9.1
     optionalDependencies:
-      '@nuxt/content': 3.16.1(@nuxt/schema@4.6.0)(@oxc-project/types@0.152.0)(better-sqlite3@12.11.1)(confbox@0.2.4)(dotenv@17.4.2)(esbuild@0.28.2)(giget@3.3.1)(magic-string@0.30.21)(magicast@0.5.5)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))
-      '@nuxtjs/mcp-toolkit': 0.22.0(@nuxt/schema@4.6.0)(@vue/compiler-sfc@3.5.43)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(h3@1.15.11)(jiti@2.7.0)(magic-string@0.30.21)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(rollup@4.64.0)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))(vue@3.5.43(typescript@5.9.3))(zod@4.6.5)
-      '@nuxtjs/robots': 6.2.4(22ba0ed89dd6406cbb938bb1364fc5c5)
-      '@nuxtjs/sitemap': 8.6.1(a69eb50999abd1859c12f282dbdb225a)
-      nuxt-llms: 0.2.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@0.30.21)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
+      '@nuxt/content': 3.16.1(@nuxt/schema@4.6.0)(@oxc-project/types@0.152.0)(better-sqlite3@12.11.1)(confbox@0.2.4)(dotenv@17.4.2)(esbuild@0.28.2)(giget@3.3.1)(magic-string@1.4.3)(magicast@0.5.5)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))
+      '@nuxtjs/mcp-toolkit': 0.22.0(@nuxt/schema@4.6.0)(@vue/compiler-sfc@3.5.43)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(h3@1.15.11)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(rollup@4.64.0)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))(vue@3.5.43(typescript@5.9.3))(zod@4.6.5)
+      '@nuxtjs/robots': 6.2.4(1fa5557b7a9b0a358862a4710025e777)
+      '@nuxtjs/sitemap': 8.6.1(abe2f75b5aa07b6602caa1860dcba6f9)
+      nuxt-llms: 0.2.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
     transitivePeerDependencies:
       - '@nuxt/schema'
       - confbox
@@ -14772,9 +14898,9 @@ snapshots:
 
   nuxt-define@1.0.0: {}
 
-  nuxt-llms@0.2.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@0.30.21)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))):
+  nuxt-llms@0.2.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))):
     dependencies:
-      '@nuxt/kit': 4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@0.30.21)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
+      '@nuxt/kit': 4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
     transitivePeerDependencies:
       - '@nuxt/schema'
       - confbox
@@ -14787,7 +14913,7 @@ snapshots:
       - rolldown
       - unplugin
 
-  nuxt-og-image@6.9.1(370b99bbe49e4fc4310c887835077271):
+  nuxt-og-image@6.9.1(97b88f392d295c90a093efa465ae7a22):
     dependencies:
       '@clack/prompts': 1.8.1
       '@nuxt/kit': 4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.151.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
@@ -14803,8 +14929,8 @@ snapshots:
       magic-string: 1.4.3
       magicast: 0.5.5
       mocked-exports: 0.1.1
-      nuxt-site-config: 4.2.3(538206e48ced1a5d386ca47224beb9fa)
-      nuxtseo-shared: 5.3.16(9bac2b3fce822bb4252d84274d0ded3b)
+      nuxt-site-config: 4.2.3(6410502bfc34806684a6b989ba77e2dc)
+      nuxtseo-shared: 5.3.16(004168448f598b8a8a765fbd51bb6c3a)
       nypm: 0.6.10
       object-identity: 0.2.3
       ofetch: 1.5.1
@@ -14825,6 +14951,7 @@ snapshots:
       '@takumi-rs/core': 2.14.0(csstype@3.2.3)
       fontless: 0.2.1(db0@0.3.4(better-sqlite3@12.11.1))(ioredis@5.11.1)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))
       nitropack: 2.13.4(@parcel/watcher@2.6.0)(better-sqlite3@12.11.1)(oxc-parser@0.133.0)(rolldown@1.2.12)(srvx@0.11.22)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))
+      playwright-core: 1.63.0
       sharp: 0.35.5(@types/node@26.6.4)
       tailwindcss: 4.3.3
       unifont: 0.7.5
@@ -14851,12 +14978,12 @@ snapshots:
       - vue
       - webpack
 
-  nuxt-schema-org@6.4.3(06339588bd6230de3030fc270006c9ef):
+  nuxt-schema-org@6.4.3(68150d0998eb177d5aacae8cb44f8919):
     dependencies:
-      '@nuxt/kit': 4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@0.30.21)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
+      '@nuxt/kit': 4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
       defu: 6.1.7
-      nuxt-site-config: 4.2.3(22ba0ed89dd6406cbb938bb1364fc5c5)
-      nuxtseo-shared: 5.3.16(744ff7fd9a152b5ba76bd41516e4c401)
+      nuxt-site-config: 4.2.3(1fa5557b7a9b0a358862a4710025e777)
+      nuxtseo-shared: 5.3.16(2583b91d8de450fb4fcddd6ee273ef79)
       pkg-types: 2.3.3
       ufo: 1.6.4
     optionalDependencies:
@@ -14878,9 +15005,9 @@ snapshots:
       - vite
       - vue
 
-  nuxt-site-config-kit@4.2.3(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@0.30.21)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))(vue@3.5.43(typescript@5.9.3)):
+  nuxt-site-config-kit@4.2.3(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))(vue@3.5.43(typescript@5.9.3)):
     dependencies:
-      '@nuxt/kit': 4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@0.30.21)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
+      '@nuxt/kit': 4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
       site-config-stack: 4.2.3(vue@3.5.43(typescript@5.9.3))
       std-env: 4.3.0
       ufo: 1.6.4
@@ -14897,9 +15024,9 @@ snapshots:
       - unplugin
       - vue
 
-  nuxt-site-config-kit@4.2.3(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@0.30.21)(mlly@1.8.2)(oxc-parser@0.141.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))(vue@3.5.43(typescript@5.9.3)):
+  nuxt-site-config-kit@4.2.3(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.141.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))(vue@3.5.43(typescript@5.9.3)):
     dependencies:
-      '@nuxt/kit': 4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@0.30.21)(mlly@1.8.2)(oxc-parser@0.141.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
+      '@nuxt/kit': 4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.141.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
       site-config-stack: 4.2.3(vue@3.5.43(typescript@5.9.3))
       std-env: 4.3.0
       ufo: 1.6.4
@@ -14935,15 +15062,15 @@ snapshots:
       - unplugin
       - vue
 
-  nuxt-site-config@4.2.3(22ba0ed89dd6406cbb938bb1364fc5c5):
+  nuxt-site-config@4.2.3(0155943dcfcb3e8f1e6ee7ac6748e13b):
     dependencies:
       '@nuxt/devalue': 2.0.2
-      '@nuxt/kit': 4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@0.30.21)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
+      '@nuxt/kit': 4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.141.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
       consola: 3.4.2
       defu: 6.1.7
       h3: 1.15.11
-      nuxt-site-config-kit: 4.2.3(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@0.30.21)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))(vue@3.5.43(typescript@5.9.3))
-      nuxtseo-shared: 5.3.16(744ff7fd9a152b5ba76bd41516e4c401)
+      nuxt-site-config-kit: 4.2.3(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.141.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))(vue@3.5.43(typescript@5.9.3))
+      nuxtseo-shared: 5.3.16(be474f164f65517a791b10007c1d9f36)
       pathe: 2.0.3
       pkg-types: 2.3.3
       site-config-stack: 4.2.3(vue@3.5.43(typescript@5.9.3))
@@ -14964,7 +15091,36 @@ snapshots:
       - vite
       - zod
 
-  nuxt-site-config@4.2.3(538206e48ced1a5d386ca47224beb9fa):
+  nuxt-site-config@4.2.3(1fa5557b7a9b0a358862a4710025e777):
+    dependencies:
+      '@nuxt/devalue': 2.0.2
+      '@nuxt/kit': 4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
+      consola: 3.4.2
+      defu: 6.1.7
+      h3: 1.15.11
+      nuxt-site-config-kit: 4.2.3(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))(vue@3.5.43(typescript@5.9.3))
+      nuxtseo-shared: 5.3.16(2583b91d8de450fb4fcddd6ee273ef79)
+      pathe: 2.0.3
+      pkg-types: 2.3.3
+      site-config-stack: 4.2.3(vue@3.5.43(typescript@5.9.3))
+      ufo: 1.6.4
+      vue: 3.5.43(typescript@5.9.3)
+    transitivePeerDependencies:
+      - '@nuxt/schema'
+      - confbox
+      - dotenv
+      - giget
+      - jiti
+      - magic-string
+      - mlly
+      - nuxt
+      - oxc-parser
+      - rolldown
+      - unplugin
+      - vite
+      - zod
+
+  nuxt-site-config@4.2.3(6410502bfc34806684a6b989ba77e2dc):
     dependencies:
       '@nuxt/devalue': 2.0.2
       '@nuxt/kit': 4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.151.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
@@ -14972,7 +15128,7 @@ snapshots:
       defu: 6.1.7
       h3: 1.15.11
       nuxt-site-config-kit: 4.2.3(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.151.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))(vue@3.5.43(typescript@5.9.3))
-      nuxtseo-shared: 5.3.16(9bac2b3fce822bb4252d84274d0ded3b)
+      nuxtseo-shared: 5.3.16(004168448f598b8a8a765fbd51bb6c3a)
       pathe: 2.0.3
       pkg-types: 2.3.3
       site-config-stack: 4.2.3(vue@3.5.43(typescript@5.9.3))
@@ -14993,45 +15149,16 @@ snapshots:
       - vite
       - zod
 
-  nuxt-site-config@4.2.3(6be24db654c942a14816f18d0d34b432):
-    dependencies:
-      '@nuxt/devalue': 2.0.2
-      '@nuxt/kit': 4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@0.30.21)(mlly@1.8.2)(oxc-parser@0.141.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
-      consola: 3.4.2
-      defu: 6.1.7
-      h3: 1.15.11
-      nuxt-site-config-kit: 4.2.3(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@0.30.21)(mlly@1.8.2)(oxc-parser@0.141.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))(vue@3.5.43(typescript@5.9.3))
-      nuxtseo-shared: 5.3.16(f4b45a8c7d2f2bc1b5d16b0c37217a1c)
-      pathe: 2.0.3
-      pkg-types: 2.3.3
-      site-config-stack: 4.2.3(vue@3.5.43(typescript@5.9.3))
-      ufo: 1.6.4
-      vue: 3.5.43(typescript@5.9.3)
-    transitivePeerDependencies:
-      - '@nuxt/schema'
-      - confbox
-      - dotenv
-      - giget
-      - jiti
-      - magic-string
-      - mlly
-      - nuxt
-      - oxc-parser
-      - rolldown
-      - unplugin
-      - vite
-      - zod
-
-  nuxt@4.4.8(@babel/plugin-syntax-jsx@7.29.7(@babel/core@7.29.7))(@babel/plugin-syntax-typescript@7.29.7(@babel/core@7.29.7))(@oxc-project/types@0.152.0)(@parcel/watcher@2.6.0)(@types/node@26.6.4)(@vue/compiler-sfc@3.5.43)(better-sqlite3@12.11.1)(cac@6.7.14)(confbox@0.2.4)(db0@0.3.4(better-sqlite3@12.11.1))(dotenv@17.4.2)(esbuild@0.28.2)(eslint@10.12.0(jiti@2.7.0))(giget@3.3.1)(ioredis@5.11.1)(lightningcss@1.33.0)(magicast@0.5.5)(optionator@0.9.4)(rolldown@1.2.12)(rollup-plugin-visualizer@7.1.1(rolldown@1.2.12)(rollup@4.64.0))(rollup@4.64.0)(sass@1.105.1)(srvx@0.11.22)(terser@5.51.2)(typescript@5.9.3)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))(vue-tsc@3.3.12(typescript@5.9.3))(yaml@2.9.1):
+  nuxt@4.4.8(@babel/plugin-syntax-jsx@7.29.7(@babel/core@7.29.7))(@babel/plugin-syntax-typescript@7.29.7(@babel/core@7.29.7))(@oxc-project/types@0.152.0)(@parcel/watcher@2.6.0)(@types/node@26.6.4)(@vue/compiler-sfc@3.5.43)(better-sqlite3@12.11.1)(cac@6.7.14)(commander@14.0.3)(confbox@0.2.4)(db0@0.3.4(better-sqlite3@12.11.1))(dotenv@17.4.2)(esbuild@0.28.2)(eslint@10.12.0(jiti@2.7.0))(giget@3.3.1)(ioredis@5.11.1)(lightningcss@1.33.0)(magicast@0.5.5)(optionator@0.9.4)(rolldown@1.2.12)(rollup-plugin-visualizer@7.1.1(rolldown@1.2.12)(rollup@4.64.0))(rollup@4.64.0)(sass@1.105.1)(srvx@0.11.22)(terser@5.51.2)(typescript@5.9.3)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))(vue-tsc@3.3.12(typescript@5.9.3))(yaml@2.9.1):
     dependencies:
       '@dxup/nuxt': 0.4.1(@nuxt/schema@4.4.8)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@0.30.21)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(typescript@5.9.3)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
-      '@nuxt/cli': 3.37.0(@nuxt/schema@4.4.8)(@parcel/watcher@2.6.0)(cac@6.7.14)(magicast@0.5.5)
+      '@nuxt/cli': 3.37.0(@nuxt/schema@4.4.8)(@parcel/watcher@2.6.0)(cac@6.7.14)(commander@14.0.3)(magicast@0.5.5)
       '@nuxt/devtools': 3.4.2(@nuxt/schema@4.4.8)(confbox@0.2.4)(db0@0.3.4(better-sqlite3@12.11.1))(dotenv@17.4.2)(giget@3.3.1)(ioredis@5.11.1)(jiti@2.7.0)(magic-string@0.30.21)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))(vue@3.5.43(typescript@5.9.3))
       '@nuxt/kit': 4.4.8(magicast@0.5.5)
-      '@nuxt/nitro-server': 4.4.8(7c5f3e276f30fa96660ce41fb115fe08)
+      '@nuxt/nitro-server': 4.4.8(de6d13e879b665d0b4d1abf7f9393f0b)
       '@nuxt/schema': 4.4.8
       '@nuxt/telemetry': 2.9.1(@nuxt/kit@4.4.8(magicast@0.5.5))
-      '@nuxt/vite-builder': 4.4.8(8d87756da47842bbb77226aff6f186dc)
+      '@nuxt/vite-builder': 4.4.8(691ba7ab3b53df2d8a6011c8c80590d7)
       '@unhead/vue': 2.1.17(vue@3.5.43(typescript@5.9.3))
       '@vue/shared': 3.5.43
       chokidar: 5.0.0
@@ -15162,41 +15289,7 @@ snapshots:
       - xml2js
       - yaml
 
-  nuxtseo-shared@5.3.16(744ff7fd9a152b5ba76bd41516e4c401):
-    dependencies:
-      '@clack/prompts': 1.8.1
-      '@nuxt/devtools-kit': 4.0.0-alpha.7(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@0.30.21)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))
-      '@nuxt/kit': 4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@0.30.21)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
-      '@nuxt/schema': 4.6.0
-      birpc: 4.2.0
-      consola: 3.4.2
-      defu: 6.1.7
-      nuxt: 4.4.8(@babel/plugin-syntax-jsx@7.29.7(@babel/core@7.29.7))(@babel/plugin-syntax-typescript@7.29.7(@babel/core@7.29.7))(@oxc-project/types@0.152.0)(@parcel/watcher@2.6.0)(@types/node@26.6.4)(@vue/compiler-sfc@3.5.43)(better-sqlite3@12.11.1)(cac@6.7.14)(confbox@0.2.4)(db0@0.3.4(better-sqlite3@12.11.1))(dotenv@17.4.2)(esbuild@0.28.2)(eslint@10.12.0(jiti@2.7.0))(giget@3.3.1)(ioredis@5.11.1)(lightningcss@1.33.0)(magicast@0.5.5)(optionator@0.9.4)(rolldown@1.2.12)(rollup-plugin-visualizer@7.1.1(rolldown@1.2.12)(rollup@4.64.0))(rollup@4.64.0)(sass@1.105.1)(srvx@0.11.22)(terser@5.51.2)(typescript@5.9.3)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))(vue-tsc@3.3.12(typescript@5.9.3))(yaml@2.9.1)
-      nypm: 0.6.10
-      ofetch: 1.5.1
-      pathe: 2.0.3
-      pkg-types: 2.3.3
-      radix3: 1.1.2
-      sirv: 3.0.2
-      std-env: 4.3.0
-      ufo: 1.6.4
-      vue: 3.5.43(typescript@5.9.3)
-    optionalDependencies:
-      nuxt-site-config: 4.2.3(22ba0ed89dd6406cbb938bb1364fc5c5)
-      zod: 4.6.5
-    transitivePeerDependencies:
-      - confbox
-      - dotenv
-      - giget
-      - jiti
-      - magic-string
-      - mlly
-      - oxc-parser
-      - rolldown
-      - unplugin
-      - vite
-
-  nuxtseo-shared@5.3.16(9bac2b3fce822bb4252d84274d0ded3b):
+  nuxtseo-shared@5.3.16(004168448f598b8a8a765fbd51bb6c3a):
     dependencies:
       '@clack/prompts': 1.8.1
       '@nuxt/devtools-kit': 4.0.0-alpha.7(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.151.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))
@@ -15205,7 +15298,7 @@ snapshots:
       birpc: 4.2.0
       consola: 3.4.2
       defu: 6.1.7
-      nuxt: 4.4.8(@babel/plugin-syntax-jsx@7.29.7(@babel/core@7.29.7))(@babel/plugin-syntax-typescript@7.29.7(@babel/core@7.29.7))(@oxc-project/types@0.152.0)(@parcel/watcher@2.6.0)(@types/node@26.6.4)(@vue/compiler-sfc@3.5.43)(better-sqlite3@12.11.1)(cac@6.7.14)(confbox@0.2.4)(db0@0.3.4(better-sqlite3@12.11.1))(dotenv@17.4.2)(esbuild@0.28.2)(eslint@10.12.0(jiti@2.7.0))(giget@3.3.1)(ioredis@5.11.1)(lightningcss@1.33.0)(magicast@0.5.5)(optionator@0.9.4)(rolldown@1.2.12)(rollup-plugin-visualizer@7.1.1(rolldown@1.2.12)(rollup@4.64.0))(rollup@4.64.0)(sass@1.105.1)(srvx@0.11.22)(terser@5.51.2)(typescript@5.9.3)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))(vue-tsc@3.3.12(typescript@5.9.3))(yaml@2.9.1)
+      nuxt: 4.4.8(@babel/plugin-syntax-jsx@7.29.7(@babel/core@7.29.7))(@babel/plugin-syntax-typescript@7.29.7(@babel/core@7.29.7))(@oxc-project/types@0.152.0)(@parcel/watcher@2.6.0)(@types/node@26.6.4)(@vue/compiler-sfc@3.5.43)(better-sqlite3@12.11.1)(cac@6.7.14)(commander@14.0.3)(confbox@0.2.4)(db0@0.3.4(better-sqlite3@12.11.1))(dotenv@17.4.2)(esbuild@0.28.2)(eslint@10.12.0(jiti@2.7.0))(giget@3.3.1)(ioredis@5.11.1)(lightningcss@1.33.0)(magicast@0.5.5)(optionator@0.9.4)(rolldown@1.2.12)(rollup-plugin-visualizer@7.1.1(rolldown@1.2.12)(rollup@4.64.0))(rollup@4.64.0)(sass@1.105.1)(srvx@0.11.22)(terser@5.51.2)(typescript@5.9.3)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))(vue-tsc@3.3.12(typescript@5.9.3))(yaml@2.9.1)
       nypm: 0.6.10
       ofetch: 1.5.1
       pathe: 2.0.3
@@ -15216,7 +15309,7 @@ snapshots:
       ufo: 1.6.4
       vue: 3.5.43(typescript@5.9.3)
     optionalDependencies:
-      nuxt-site-config: 4.2.3(22ba0ed89dd6406cbb938bb1364fc5c5)
+      nuxt-site-config: 4.2.3(1fa5557b7a9b0a358862a4710025e777)
       zod: 4.6.5
     transitivePeerDependencies:
       - confbox
@@ -15230,16 +15323,16 @@ snapshots:
       - unplugin
       - vite
 
-  nuxtseo-shared@5.3.16(f4b45a8c7d2f2bc1b5d16b0c37217a1c):
+  nuxtseo-shared@5.3.16(2583b91d8de450fb4fcddd6ee273ef79):
     dependencies:
       '@clack/prompts': 1.8.1
-      '@nuxt/devtools-kit': 4.0.0-alpha.7(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@0.30.21)(mlly@1.8.2)(oxc-parser@0.141.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))
-      '@nuxt/kit': 4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@0.30.21)(mlly@1.8.2)(oxc-parser@0.141.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
+      '@nuxt/devtools-kit': 4.0.0-alpha.7(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))
+      '@nuxt/kit': 4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
       '@nuxt/schema': 4.6.0
       birpc: 4.2.0
       consola: 3.4.2
       defu: 6.1.7
-      nuxt: 4.4.8(@babel/plugin-syntax-jsx@7.29.7(@babel/core@7.29.7))(@babel/plugin-syntax-typescript@7.29.7(@babel/core@7.29.7))(@oxc-project/types@0.152.0)(@parcel/watcher@2.6.0)(@types/node@26.6.4)(@vue/compiler-sfc@3.5.43)(better-sqlite3@12.11.1)(cac@6.7.14)(confbox@0.2.4)(db0@0.3.4(better-sqlite3@12.11.1))(dotenv@17.4.2)(esbuild@0.28.2)(eslint@10.12.0(jiti@2.7.0))(giget@3.3.1)(ioredis@5.11.1)(lightningcss@1.33.0)(magicast@0.5.5)(optionator@0.9.4)(rolldown@1.2.12)(rollup-plugin-visualizer@7.1.1(rolldown@1.2.12)(rollup@4.64.0))(rollup@4.64.0)(sass@1.105.1)(srvx@0.11.22)(terser@5.51.2)(typescript@5.9.3)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))(vue-tsc@3.3.12(typescript@5.9.3))(yaml@2.9.1)
+      nuxt: 4.4.8(@babel/plugin-syntax-jsx@7.29.7(@babel/core@7.29.7))(@babel/plugin-syntax-typescript@7.29.7(@babel/core@7.29.7))(@oxc-project/types@0.152.0)(@parcel/watcher@2.6.0)(@types/node@26.6.4)(@vue/compiler-sfc@3.5.43)(better-sqlite3@12.11.1)(cac@6.7.14)(commander@14.0.3)(confbox@0.2.4)(db0@0.3.4(better-sqlite3@12.11.1))(dotenv@17.4.2)(esbuild@0.28.2)(eslint@10.12.0(jiti@2.7.0))(giget@3.3.1)(ioredis@5.11.1)(lightningcss@1.33.0)(magicast@0.5.5)(optionator@0.9.4)(rolldown@1.2.12)(rollup-plugin-visualizer@7.1.1(rolldown@1.2.12)(rollup@4.64.0))(rollup@4.64.0)(sass@1.105.1)(srvx@0.11.22)(terser@5.51.2)(typescript@5.9.3)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))(vue-tsc@3.3.12(typescript@5.9.3))(yaml@2.9.1)
       nypm: 0.6.10
       ofetch: 1.5.1
       pathe: 2.0.3
@@ -15250,7 +15343,41 @@ snapshots:
       ufo: 1.6.4
       vue: 3.5.43(typescript@5.9.3)
     optionalDependencies:
-      nuxt-site-config: 4.2.3(22ba0ed89dd6406cbb938bb1364fc5c5)
+      nuxt-site-config: 4.2.3(1fa5557b7a9b0a358862a4710025e777)
+      zod: 4.6.5
+    transitivePeerDependencies:
+      - confbox
+      - dotenv
+      - giget
+      - jiti
+      - magic-string
+      - mlly
+      - oxc-parser
+      - rolldown
+      - unplugin
+      - vite
+
+  nuxtseo-shared@5.3.16(be474f164f65517a791b10007c1d9f36):
+    dependencies:
+      '@clack/prompts': 1.8.1
+      '@nuxt/devtools-kit': 4.0.0-alpha.7(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.141.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))
+      '@nuxt/kit': 4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.141.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
+      '@nuxt/schema': 4.6.0
+      birpc: 4.2.0
+      consola: 3.4.2
+      defu: 6.1.7
+      nuxt: 4.4.8(@babel/plugin-syntax-jsx@7.29.7(@babel/core@7.29.7))(@babel/plugin-syntax-typescript@7.29.7(@babel/core@7.29.7))(@oxc-project/types@0.152.0)(@parcel/watcher@2.6.0)(@types/node@26.6.4)(@vue/compiler-sfc@3.5.43)(better-sqlite3@12.11.1)(cac@6.7.14)(commander@14.0.3)(confbox@0.2.4)(db0@0.3.4(better-sqlite3@12.11.1))(dotenv@17.4.2)(esbuild@0.28.2)(eslint@10.12.0(jiti@2.7.0))(giget@3.3.1)(ioredis@5.11.1)(lightningcss@1.33.0)(magicast@0.5.5)(optionator@0.9.4)(rolldown@1.2.12)(rollup-plugin-visualizer@7.1.1(rolldown@1.2.12)(rollup@4.64.0))(rollup@4.64.0)(sass@1.105.1)(srvx@0.11.22)(terser@5.51.2)(typescript@5.9.3)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))(vue-tsc@3.3.12(typescript@5.9.3))(yaml@2.9.1)
+      nypm: 0.6.10
+      ofetch: 1.5.1
+      pathe: 2.0.3
+      pkg-types: 2.3.3
+      radix3: 1.1.2
+      sirv: 3.0.2
+      std-env: 4.3.0
+      ufo: 1.6.4
+      vue: 3.5.43(typescript@5.9.3)
+    optionalDependencies:
+      nuxt-site-config: 4.2.3(1fa5557b7a9b0a358862a4710025e777)
       zod: 4.6.5
     transitivePeerDependencies:
       - confbox
@@ -15642,6 +15769,12 @@ snapshots:
       exsolve: 1.1.3
       pathe: 2.0.3
 
+  playwright-core@1.63.0: {}
+
+  playwright@1.63.0:
+    dependencies:
+      playwright-core: 1.63.0
+
   possible-typed-array-names@1.1.0: {}
 
   postcss-calc@10.1.1(postcss@8.5.29):
@@ -15835,10 +15968,6 @@ snapshots:
 
   process@0.11.10: {}
 
-  promise@7.3.1:
-    dependencies:
-      asap: 2.0.6
-
   proper-lockfile@4.1.2:
     dependencies:
       graceful-fs: 4.2.11
@@ -15921,6 +16050,8 @@ snapshots:
       prosemirror-state: 1.4.4
       prosemirror-transform: 1.12.2
 
+  proto-list@1.2.4: {}
+
   protocols@2.0.2: {}
 
   proxy-addr@2.0.8:
@@ -15935,73 +16066,6 @@ snapshots:
       picocolors: 1.1.1
       sade: 1.8.1
 
-  pug-attrs@3.0.0:
-    dependencies:
-      constantinople: 4.0.1
-      js-stringify: 1.0.2
-      pug-runtime: 3.0.1
-
-  pug-code-gen@3.0.4:
-    dependencies:
-      constantinople: 4.0.1
-      doctypes: 1.1.0
-      js-stringify: 1.0.2
-      pug-attrs: 3.0.0
-      pug-error: 2.1.0
-      pug-runtime: 3.0.1
-      void-elements: 3.1.0
-      with: 7.0.2
-
-  pug-error@2.1.0: {}
-
-  pug-filters@4.0.0:
-    dependencies:
-      constantinople: 4.0.1
-      jstransformer: 1.0.0
-      pug-error: 2.1.0
-      pug-walk: 2.0.0
-      resolve: 1.22.12
-
-  pug-lexer@5.0.1:
-    dependencies:
-      character-parser: 2.2.0
-      is-expression: 4.0.0
-      pug-error: 2.1.0
-
-  pug-linker@4.0.0:
-    dependencies:
-      pug-error: 2.1.0
-      pug-walk: 2.0.0
-
-  pug-load@3.0.0:
-    dependencies:
-      object-assign: 4.1.1
-      pug-walk: 2.0.0
-
-  pug-parser@6.0.0:
-    dependencies:
-      pug-error: 2.1.0
-      token-stream: 1.0.0
-
-  pug-runtime@3.0.1: {}
-
-  pug-strip-comments@2.0.0:
-    dependencies:
-      pug-error: 2.1.0
-
-  pug-walk@2.0.0: {}
-
-  pug@3.0.4:
-    dependencies:
-      pug-code-gen: 3.0.4
-      pug-filters: 4.0.0
-      pug-lexer: 5.0.1
-      pug-linker: 4.0.0
-      pug-load: 3.0.0
-      pug-parser: 6.0.0
-      pug-runtime: 3.0.1
-      pug-strip-comments: 2.0.0
-
   pump@3.0.4:
     dependencies:
       end-of-stream: 1.4.5
@@ -16084,14 +16148,6 @@ snapshots:
 
   readdirp@5.1.1: {}
 
-  recast@0.23.21:
-    dependencies:
-      ast-types: 0.16.3
-      esprima: 4.0.1
-      source-map: 0.6.1
-      tiny-invariant: 1.3.3
-      tslib: 2.8.1
-
   redis-errors@1.2.0: {}
 
   redis-parser@3.0.0:
@@ -16684,9 +16740,11 @@ snapshots:
       picocolors: 1.1.1
       sax: 1.6.1
 
-  swrv@1.3.0(vue@3.5.43(typescript@5.9.3)):
+  swrv@1.3.0(@vue/test-utils@2.5.1(@vue/compiler-dom@3.5.43)(@vue/server-renderer@3.5.43)(vue@3.5.43(typescript@5.9.3)))(vue@3.5.43(typescript@5.9.3)):
     dependencies:
       vue: 3.5.43(typescript@5.9.3)
+    optionalDependencies:
+      '@vue/test-utils': 2.5.1(@vue/compiler-dom@3.5.43)(@vue/server-renderer@3.5.43)(vue@3.5.43(typescript@5.9.3))
 
   tagged-tag@1.0.0: {}
 
@@ -16761,6 +16819,8 @@ snapshots:
 
   tiny-invariant@1.3.3: {}
 
+  tinybench@6.2.1: {}
+
   tinyclip@0.1.15: {}
 
   tinyexec@1.3.1: {}
@@ -16782,8 +16842,6 @@ snapshots:
 
   toidentifier@1.0.1: {}
 
-  token-stream@1.0.0: {}
-
   tosource@2.0.0-alpha.3: {}
 
   totalist@3.0.1: {}
@@ -16800,8 +16858,6 @@ snapshots:
     dependencies:
       typescript: 5.9.3
 
-  ts-map@1.0.3: {}
-
   tslib@2.8.1: {}
 
   tunnel-agent@0.6.0:
@@ -16875,6 +16931,13 @@ snapshots:
       rolldown: 1.2.12
       unplugin: 3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))
 
+  unctx@3.0.1(magic-string@1.4.3)(oxc-parser@0.141.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))):
+    optionalDependencies:
+      magic-string: 1.4.3
+      oxc-parser: 0.141.0
+      rolldown: 1.2.12
+      unplugin: 3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))
+
   unctx@3.0.1(magic-string@1.4.3)(oxc-parser@0.151.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))):
     optionalDependencies:
       magic-string: 1.4.3
@@ -17001,7 +17064,7 @@ snapshots:
 
   unpipe@1.0.0: {}
 
-  unplugin-auto-import@21.1.0(@nuxt/kit@4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@0.30.21)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))))(@vueuse/core@14.4.0(vue@3.5.43(typescript@5.9.3)))(esbuild@0.28.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)):
+  unplugin-auto-import@21.1.0(@nuxt/kit@4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))))(@vueuse/core@14.4.0(vue@3.5.43(typescript@5.9.3)))(esbuild@0.28.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)):
     dependencies:
       local-pkg: 1.2.1
       magic-string: 1.4.3
@@ -17010,7 +17073,7 @@ snapshots:
       unplugin: 3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))
       unplugin-utils: 0.3.2
     optionalDependencies:
-      '@nuxt/kit': 4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@0.30.21)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
+      '@nuxt/kit': 4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
       '@vueuse/core': 14.4.0(vue@3.5.43(typescript@5.9.3))
     transitivePeerDependencies:
       - '@farmfe/core'
@@ -17051,7 +17114,7 @@ snapshots:
       pathe: 2.0.3
       picomatch: 4.0.7
 
-  unplugin-vue-components@32.1.0(@nuxt/kit@4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@0.30.21)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))))(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))(vue@3.5.43(typescript@5.9.3)):
+  unplugin-vue-components@32.1.0(@nuxt/kit@4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))))(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))(vue@3.5.43(typescript@5.9.3)):
     dependencies:
       chokidar: 5.0.0
       local-pkg: 1.2.1
@@ -17064,7 +17127,7 @@ snapshots:
       unplugin-utils: 0.3.2
       vue: 3.5.43(typescript@5.9.3)
     optionalDependencies:
-      '@nuxt/kit': 4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@0.30.21)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
+      '@nuxt/kit': 4.6.0(@nuxt/schema@4.6.0)(confbox@0.2.4)(dotenv@17.4.2)(giget@3.3.1)(jiti@2.7.0)(magic-string@1.4.3)(mlly@1.8.2)(oxc-parser@0.133.0)(rolldown@1.2.12)(unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)))
     transitivePeerDependencies:
       - '@farmfe/core'
       - '@rsbuild/core'
@@ -17305,7 +17368,27 @@ snapshots:
       terser: 5.51.2
       yaml: 2.9.1
 
-  void-elements@3.1.0: {}
+  vitest@5.0.3(@types/node@26.6.4)(happy-dom@20.14.5)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)):
+    dependencies:
+      '@types/chai': 5.2.3
+      '@vitest/mocker': 5.0.3(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))
+      chai: 6.3.0
+      es-module-lexer: 2.3.2
+      expect-type: 1.4.0
+      magic-string: 1.4.3
+      obug: 2.2.1
+      picomatch: 4.0.7
+      std-env: 4.3.0
+      tinybench: 6.2.1
+      tinyexec: 1.3.1
+      tinyglobby: 0.2.17
+      vite: 8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1)
+      why-is-node-running: 3.2.1
+    optionalDependencies:
+      '@types/node': 26.6.4
+      happy-dom: 20.14.5
+    transitivePeerDependencies:
+      - msw
 
   vscode-uri@3.2.0: {}
 
@@ -17329,22 +17412,6 @@ snapshots:
 
   vue-devtools-stub@0.1.0: {}
 
-  vue-docgen-api@4.79.2(vue@3.5.43(typescript@5.9.3)):
-    dependencies:
-      '@babel/parser': 7.29.9
-      '@babel/types': 7.29.8
-      '@vue/compiler-dom': 3.5.43
-      '@vue/compiler-sfc': 3.5.43
-      ast-types: 0.16.3
-      esm-resolve: 1.0.11
-      hash-sum: 2.0.0
-      lru-cache: 8.0.5
-      pug: 3.0.4
-      recast: 0.23.21
-      ts-map: 1.0.3
-      vue: 3.5.43(typescript@5.9.3)
-      vue-inbrowser-compiler-independent-utils: 4.71.1(vue@3.5.43(typescript@5.9.3))
-
   vue-i18n@11.4.13(vue@3.5.43(typescript@5.9.3)):
     dependencies:
       '@intlify/core-base': 11.4.13
@@ -17353,10 +17420,6 @@ snapshots:
       '@vue/devtools-api': 6.6.4
       vue: 3.5.43(typescript@5.9.3)
 
-  vue-inbrowser-compiler-independent-utils@4.71.1(vue@3.5.43(typescript@5.9.3)):
-    dependencies:
-      vue: 3.5.43(typescript@5.9.3)
-
   vue-router@5.3.1(@vue/compiler-sfc@3.5.43)(esbuild@0.28.2)(rolldown@1.2.12)(rollup@4.64.0)(vite@8.3.3(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(sass@1.105.1)(terser@5.51.2)(yaml@2.9.1))(vue@3.5.43(typescript@5.9.3)):
     dependencies:
       '@vue-macros/common': 3.1.4(vue@3.5.43(typescript@5.9.3))
@@ -17414,6 +17477,8 @@ snapshots:
 
   webpack-virtual-modules@0.6.2: {}
 
+  whatwg-mimetype@3.0.0: {}
+
   whatwg-url@5.0.0:
     dependencies:
       tr46: 0.0.3
@@ -17439,12 +17504,7 @@ snapshots:
     dependencies:
       isexe: 4.0.0
 
-  with@7.0.2:
-    dependencies:
-      '@babel/parser': 7.29.9
-      '@babel/types': 7.29.8
-      assert-never: 1.4.0
-      babel-walk: 3.0.0-canary-5
+  why-is-node-running@3.2.1: {}
 
   word-wrap@1.2.5: {}
 
diff --git a/code/g3soft-libs/pnpm-workspace.yaml b/code/g3soft-libs/pnpm-workspace.yaml
index ca8ba999..573bd390 100644
--- a/code/g3soft-libs/pnpm-workspace.yaml
+++ b/code/g3soft-libs/pnpm-workspace.yaml
@@ -10,7 +10,7 @@ catalog:
 
 # pnpm 11 的构建脚本白名单（map 形式；v10 的 onlyBuiltDependencies 数组写法在 v11 已失效）。
 #   better-sqlite3 —— Docus 全文搜索（FTS5）依赖的原生模块，必须放行才能下载/编译二进制
-#   vue-demi       —— vue-docgen-api 的传递依赖，安装时要跑脚本切换 Vue 版本 shim
+#   vue-demi       —— Vue 2/3 兼容 shim，部分工具链的传递依赖，安装时要跑脚本切换
 #   esbuild        —— Nuxt / Vite 底层
 #   @parcel/watcher —— Docs(Nuxt) dev 的文件监听原生模块，放行以启用快速热更新。
 #                     注意：pnpm 11 会把「未放行的构建脚本」当作错误让后续命令失败，
diff --git a/code/g3soft-libs/scripts/gen-api.mjs b/code/g3soft-libs/scripts/gen-api.mjs
deleted file mode 100644
index 6a9e44a6..00000000
--- a/code/g3soft-libs/scripts/gen-api.mjs
+++ /dev/null
@@ -1,95 +0,0 @@
-#!/usr/bin/env node
-/**
- * 从组件源码生成 API 数据。
- *
- * 用 vue-docgen-api 解析 packages/ui/src 下的 .vue 文件，
- * 提取 props / events / slots 及其 JSDoc 注释，输出到 docs/data/api/<组件名>.json，
- * 由文档站的 <ApiTable> 组件读取渲染。
- *
- * 这样 API 表格永远与源码一致，禁止手写。
- * 源码改动后执行：pnpm gen:api
- */
-import { mkdir, readdir, writeFile } from 'node:fs/promises'
-import { basename, dirname, join } from 'node:path'
-import { fileURLToPath } from 'node:url'
-import { parse } from 'vue-docgen-api'
-
-const root = fileURLToPath(new URL('..', import.meta.url))
-const uiSrc = join(root, 'packages/ui/src')
-const outDir = join(root, 'docs/data/api')
-
-/** 递归收集所有 .vue 组件文件 */
-async function findComponents(dir) {
-  const found = []
-  for (const entry of await readdir(dir, { withFileTypes: true })) {
-    const full = join(dir, entry.name)
-    if (entry.isDirectory()) {
-      found.push(...(await findComponents(full)))
-    } else if (entry.name.endsWith('.vue')) {
-      found.push(full)
-    }
-  }
-  return found
-}
-
-/** packages/ui/src/button/Button.vue -> button */
-function toKey(file) {
-  return basename(dirname(file))
-}
-
-/** docgen 给出的值可能带引号，统一剥掉 */
-function clean(text = '') {
-  return String(text).replace(/^['"]|['"]$/g, '')
-}
-
-/** 把说明文字压成单行，避免表格里出现换行 */
-function oneLine(text = '') {
-  return String(text).replace(/\s+/g, ' ').trim()
-}
-
-function mapMember(item) {
-  return {
-    name: item.name,
-    description: oneLine(item.description),
-    type: item.type?.name ?? '',
-    defaultValue: item.defaultValue ? clean(item.defaultValue.value) : '',
-  }
-}
-
-async function main() {
-  const files = await findComponents(uiSrc)
-  const results = []
-
-  for (const file of files) {
-    const info = await parse(file)
-    const key = toKey(file)
-
-    results.push([
-      key,
-      {
-        displayName: info.displayName || key,
-        description: oneLine(info.description),
-        props: (info.props ?? []).map(mapMember),
-        events: (info.events ?? []).map(mapMember),
-        slots: (info.slots ?? []).map((slot) => ({
-          name: slot.name,
-          description: oneLine(slot.description),
-        })),
-      },
-    ])
-  }
-
-  await mkdir(outDir, { recursive: true })
-
-  for (const [key, doc] of results) {
-    await writeFile(join(outDir, `${key}.json`), `${JSON.stringify(doc, null, 2)}\n`, 'utf-8')
-    console.log(
-      `✓ ${key.padEnd(12)} props=${doc.props.length} events=${doc.events.length} slots=${doc.slots.length}`,
-    )
-  }
-}
-
-main().catch((error) => {
-  console.error('[gen-api] 失败：', error)
-  process.exit(1)
-})
diff --git a/code/g3soft-libs/sel.yaml b/code/g3soft-libs/sel.yaml
new file mode 100644
index 00000000..a613854f
--- /dev/null
+++ b/code/g3soft-libs/sel.yaml
@@ -0,0 +1,2 @@
+- generic [ref=e3]:
+  - paragraph
\ No newline at end of file