@teamix-evo/ui 0.3.0 → 0.4.0

package/manifest.json

@@ -804,6 +804,23 @@
       "updateStrategy": "frozen",
       "category": "layout"
     },
+    {
+      "id": "page-shell",
+      "name": "PageShell",
+      "type": "component",
+      "description": "页面三明治壳 — header + sidebar + children 三 slot 任意组合,覆盖全屏/仅顶部/仅左导/顶部+左导四种页面形态。background prop 走 shadcn 语义槽枚举(background/muted/card/sidebar/accent),亮暗模式由 token 文件自动管。内部为传入的 ui Sidebar 注入 scoped CSS 覆盖默认 fixed 定位,让 sidebar 跟 header 共存而不被撑到 viewport 顶端。",
+      "files": [
+        {
+          "source": "src/components/page-shell/page-shell.tsx",
+          "targetAlias": "components",
+          "targetName": "page-shell.tsx"
+        }
+      ],
+      "meta": "src/components/page-shell/page-shell.meta.md",
+      "registryDependencies": ["cn", "sidebar"],
+      "updateStrategy": "frozen",
+      "category": "layout"
+    },
     {
       "id": "card",
       "name": "Card",
@@ -1577,6 +1594,9 @@
         "class-variance-authority": "^0.7.0"
       },
       "updateStrategy": "frozen",
+      "status": "deprecated",
+      "deprecatedReason": "单选场景由 RadioGroup variant=\"button\" 替代；多选切换场景由 Checkbox variant=\"button\" 替代",
+      "replacedBy": "radio-group",
       "category": "deprecated"
     },
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teamix-evo/ui",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Source-injected UI components for Teamix Evo (shadcn-based, antd capabilities)",
   "type": "module",
   "files": [
@@ -74,9 +74,9 @@
     "vite": "^5.4.0",
     "vite-tsconfig-paths": "^6.1.1",
     "zod": "^3",
-    "@teamix-evo/tokens": "^0.5.0",
+    "@teamix-evo/registry": "0.6.0",
     "@teamix-evo/eslint-config": "0.2.1",
-    "@teamix-evo/registry": "0.3.0"
+    "@teamix-evo/tokens": "^0.6.0"
   },
   "publishConfig": {
     "access": "public",

package/src/components/button/button.tsx

@@ -27,16 +27,18 @@ const buttonVariants = cva(
   {
     variants: {
       variant: {
+        // shadow 由 variant scoped CSS 提供(opentrek 默认无 / uni-manager 有 shadow + hover 浮起,
+        // 见 packages/tokens/variants/uni-manager/theme.css 末尾 [data-slot='button'] 规则)
         default:
-          'bg-primary text-primary-foreground shadow hover:bg-primary/90 hover:shadow-md',
+          'bg-primary text-primary-foreground transition-shadow duration-150 hover:bg-primary/90',
         secondary:
-          'bg-secondary text-secondary-foreground shadow-sm hover:bg-secondary/80',
+          'bg-secondary text-secondary-foreground transition-shadow duration-150 hover:bg-secondary/80',
         destructive:
-          'bg-destructive text-destructive-foreground shadow-sm hover:bg-destructive/90',
+          'bg-destructive text-destructive-foreground transition-shadow duration-150 hover:bg-destructive/90',
         outline:
-          'border border-input bg-background shadow-sm hover:bg-muted hover:text-foreground hover:shadow-md',
+          'border border-input bg-card transition-shadow duration-150 hover:bg-muted hover:text-foreground',
         dashed:
-          'border border-dashed border-input bg-background shadow-sm hover:bg-muted hover:text-foreground hover:shadow-md',
+          'border border-dashed border-input bg-card transition-shadow duration-150 hover:bg-muted hover:text-foreground',
         ghost: 'hover:bg-accent hover:text-accent-foreground',
         link: 'text-primary underline-offset-4',
       },
@@ -48,15 +50,15 @@ const buttonVariants = cva(
         destructive: '',
       },
       size: {
-        // 24px — 紧凑场景(表格行内、密集工具条),对齐 cd small
-        sm: 'h-6 px-3 text-xs',
-        // 32px — 默认 / 表单基线;`md` 与 `default` 等价(向后兼容旧 API)
-        // 字号对齐 cd hybridcloud --form-element-medium-font-size: 12px (ADR 0027)
-        md: 'h-8 px-3 text-xs',
-        default: 'h-8 px-3 text-xs',
-        // 36px — 强调主操作 / 落地页
-        lg: 'h-9 px-3 text-sm',
-        // 32px 正方形 — 纯图标按钮(配合 shape="circle" / "square")
+        // 24px — 紧凑场景（表格行内、密集工具条），对齐 cd small
+        sm: 'h-6 px-[var(--btn-padding-x-sm)] text-xs',
+        // 32px — 默认 / 表单基线；`md` 与 `default` 等价（向后兼容旧 API）
+        // 字号对齐 cd hybridcloud --form-element-medium-font-size: 12px（ADR 0027）
+        md: 'h-8 px-[var(--btn-padding-x-sm)] text-xs',
+        default: 'h-8 px-[var(--btn-padding-x-sm)] text-xs',
+        // 36px — 强调主操作 / 落地页；水平 padding 走 OpenTrek v4.1 标准 16px
+        lg: 'h-9 px-[var(--btn-padding-x)] text-sm',
+        // 32px 正方形 — 纯图标按钮（配合 shape="circle" / "square"）
         icon: 'h-8 w-8',
       },
       shape: {
@@ -315,6 +317,8 @@ const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
     const buttonEl = (
       <button
         ref={ref}
+        data-slot="button"
+        data-variant={variant}
         className={composedClassName}
         disabled={disabled || loading}
         aria-busy={loading || undefined}

package/src/components/card/card.tsx

@@ -20,15 +20,16 @@ const SIZE_TOKENS = {
     title: 'text-sm',
   },
   md: {
-    headerFooter: 'p-6',
-    content: 'p-6 pt-0',
-    footer: 'p-6 pt-0',
+    // p-[var(--card-padding-x)] — op: 20px / um: 20px（OpenTrek v4.1 ContentCard准则）
+    headerFooter: 'p-[var(--card-padding-x)]',
+    content: 'p-[var(--card-padding-x)] pt-0',
+    footer: 'p-[var(--card-padding-x)] pt-0',
     title: 'text-base',
   },
   default: {
-    headerFooter: 'p-6',
-    content: 'p-6 pt-0',
-    footer: 'p-6 pt-0',
+    headerFooter: 'p-[var(--card-padding-x)]',
+    content: 'p-[var(--card-padding-x)] pt-0',
+    footer: 'p-[var(--card-padding-x)] pt-0',
     title: 'text-base',
   },
   lg: {

package/src/components/cascader/cascader.tsx

@@ -9,7 +9,11 @@ import {
 } from 'lucide-react';
 
 import { cn } from '@/utils/cn';
-import { Button } from '@/components/button/button';
+import {
+  triggerWrapperClass,
+  triggerSizeClass,
+  type TriggerSize,
+} from '@/utils/trigger-input';
 import {
   Popover,
   PopoverContent,
@@ -386,23 +390,26 @@ const Cascader = React.forwardRef<HTMLButtonElement, CascaderProps>(
     );
 
     // ─── Render ──────────────────────────────────────────
+    // trigger 用 form-control 共享 `triggerWrapperClass`,跟 Select / DatePicker /
+    // TimePicker 视觉完全一致(hover/focus border 走 token,uni-manager scoped CSS 兜底)。
     return (
       <Popover open={open} onOpenChange={setOpen}>
         <PopoverTrigger asChild>
-          <Button
+          <button
             ref={ref}
             type="button"
-            variant="outline"
-            size={size}
             disabled={disabled}
             className={cn(
+              triggerWrapperClass,
+              triggerSizeClass[size as TriggerSize],
               'min-w-panel-sm justify-between font-normal',
+              'disabled:cursor-not-allowed disabled:opacity-50',
               className,
             )}
           >
             {triggerContent}
             <ChevronDown className="ml-2 size-4 shrink-0 opacity-50" />
-          </Button>
+          </button>
         </PopoverTrigger>
         <PopoverContent className="w-auto p-0" align="start">
           {/* Search input */}

package/src/components/checkbox/checkbox.tsx

@@ -63,8 +63,10 @@ const Checkbox = React.forwardRef<
       //   checked     : bg #0064C8 (primary) / tick white  → bg-primary + text-primary-foreground
       //   ck-hovered  : bg #0057AD (deeper)                → data-[state=checked]:hover:bg-primary/90
       //   indeterm.   : 同 checked,只是 indicator 换成 minus
-      //   border-radius: 2px (corner-1)                    → rounded-md(uni-manager 2px / opentrek 6px)
-      'peer size-4 shrink-0 cursor-pointer rounded-md border border-input bg-background shadow-sm transition-colors',
+      //   border-radius: 用 rounded-sm 而非 rounded-md — opentrek `--radius-md = 8px`
+      //   在 size-4 (16px) 上 = 完美圆形,跟 shadcn 方形复选框相左。`--radius-sm`
+      //   uni-manager 0px(锐利)/ opentrek 4px(对齐 shadcn Checkbox 默认)。
+      'peer size-4 shrink-0 cursor-pointer rounded-sm border border-input bg-card shadow-sm transition-colors',
       // hover 反馈用 `enabled:` 前缀 — disabled 态不触发 hover 样式(border/bg 变化)
       'enabled:hover:border-primary data-[state=unchecked]:enabled:hover:bg-primary/5',
       'focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring',

package/src/components/date-picker/date-picker.tsx

@@ -732,7 +732,7 @@ const DatePicker = React.forwardRef<HTMLInputElement, DatePickerProps>(
           </div>
         </PopoverAnchor>
         <PopoverContent
-          className="w-auto rounded-lg p-0"
+          className="w-auto rounded-md p-0 shadow-sm"
           onOpenAutoFocus={(e) => e.preventDefault()}
           onInteractOutside={(e) => {
             // 点击 / focus 落在 anchor(trigger wrapper)内时,popover 不关闭。
@@ -1450,7 +1450,7 @@ const DateRangePicker = React.forwardRef<
           </div>
         </PopoverAnchor>
         <PopoverContent
-          className="w-auto rounded-lg p-0"
+          className="w-auto rounded-md p-0 shadow-sm"
           onOpenAutoFocus={(e) => e.preventDefault()}
           onInteractOutside={(e) => {
             const target = e.detail.originalEvent.target as Node | null;

package/src/components/dialog/dialog.tsx

@@ -54,7 +54,7 @@ DialogOverlay.displayName = DialogPrimitive.Overlay.displayName;
  * - size 绑定 `--layout-dialog-{sm|md|lg|xl}` tokens
  */
 const dialogContentVariants = cva(
-  'fixed left-1/2 top-1/2 z-50 grid w-full translate-x-[-50%] translate-y-[-50%] gap-4 border-0 bg-background p-6 shadow-lg duration-200 rounded-[var(--radius-dialog)] data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95',
+  'fixed left-1/2 top-1/2 z-50 grid w-full translate-x-[-50%] translate-y-[-50%] gap-4 border-0 bg-background px-[var(--dialog-body-padding-x)] py-[var(--dialog-body-padding-y)] shadow-lg duration-200 rounded-[var(--radius-dialog)] data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95',
   {
     variants: {
       size: {

package/src/components/filter-bar/filter-bar.stories.tsx

@@ -1,6 +1,9 @@
 import * as React from 'react';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { useForm, FormProvider } from 'react-hook-form';
+// `as never` cast on zodResolver(...) below: zod 3.25.x ships zod v4
+// internals while @hookform/resolvers@3.x still types Resolver against
+// zod v3 Schema. Remove when upgrading to @hookform/resolvers v4.
 import { zodResolver } from '@hookform/resolvers/zod';
 import { z } from 'zod';
 import {
@@ -616,7 +619,7 @@ export const WithValidation: Story = {
   name: '带 Zod 校验',
   render: () => {
     const form = useForm<z.infer<typeof filterSchema>>({
-      resolver: zodResolver(filterSchema),
+      resolver: zodResolver(filterSchema as never),
       defaultValues: {
         keyword: '',
         org: '',

package/src/components/form/form.stories.tsx

@@ -1,6 +1,9 @@
 import * as React from 'react';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { useForm } from 'react-hook-form';
+// `as never` casts on zodResolver(...) below: zod 3.25.x ships zod v4
+// internals while @hookform/resolvers@3.x still types Resolver against
+// zod v3 Schema. Remove when upgrading to @hookform/resolvers v4.
 import { zodResolver } from '@hookform/resolvers/zod';
 import { z } from 'zod';
 import {
@@ -44,7 +47,7 @@ export const ZodValidated: Story = {
   parameters: { layout: 'centered' },
   render: () => {
     const form = useForm<z.infer<typeof schema>>({
-      resolver: zodResolver(schema),
+      resolver: zodResolver(schema as never),
       defaultValues: { username: '', email: '', bio: '' },
     });
     const [submitted, setSubmitted] = React.useState<unknown>(null);
@@ -137,7 +140,7 @@ export const WithSections: Story = {
   parameters: { layout: 'centered' },
   render: () => {
     const form = useForm<z.infer<typeof sectionsSchema>>({
-      resolver: zodResolver(sectionsSchema),
+      resolver: zodResolver(sectionsSchema as never),
       defaultValues: { name: '', email: '', phone: '', company: '', role: '' },
     });
     const [submitted, setSubmitted] = React.useState<unknown>(null);
@@ -257,7 +260,7 @@ export const MultiColumn: Story = {
   parameters: { layout: 'centered' },
   render: () => {
     const form = useForm<z.infer<typeof multiColumnSchema>>({
-      resolver: zodResolver(multiColumnSchema),
+      resolver: zodResolver(multiColumnSchema as never),
       defaultValues: {
         firstName: '',
         lastName: '',
@@ -377,7 +380,7 @@ export const StickyActions: Story = {
   parameters: { layout: 'centered' },
   render: () => {
     const form = useForm<z.infer<typeof stickySchema>>({
-      resolver: zodResolver(stickySchema),
+      resolver: zodResolver(stickySchema as never),
       defaultValues: {
         title: '',
         description: '',

package/src/components/input/input.tsx

@@ -28,7 +28,7 @@ const SIZE_TO_HEIGHT = {
  * 字符计数 `showCount` + 一键清空 `clearable` 仍保留为 Input 的内建逻辑能力。
  */
 const inputVariants = cva(
-  'flex w-full rounded-md border border-input bg-background px-3 py-1 shadow-sm transition-colors placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive aria-invalid:focus-visible:ring-destructive',
+  'flex w-full rounded-md border border-input bg-card px-[var(--input-padding-x)] py-[var(--input-padding-y)] shadow-sm transition-colors placeholder:text-muted-foreground focus-visible:outline-none hover:border-ring focus-visible:border-ring focus-visible:ring-2 focus-visible:ring-ring/10 disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive aria-invalid:focus-visible:ring-destructive/10',
   {
     variants: { size: SIZE_TO_HEIGHT },
     defaultVariants: { size: 'md' },
@@ -39,7 +39,7 @@ const inputVariants = cva(
  * Input 包壳容器(`clearable` 启用时承载 border + ring,把内部 input 的边框转移到外层)。
  */
 const inputWrapperVariants = cva(
-  'flex w-full items-center gap-2 rounded-md border border-input bg-background px-3 shadow-sm transition-colors focus-within:ring-1 focus-within:ring-ring aria-invalid:border-destructive aria-invalid:focus-within:ring-destructive',
+  'flex w-full items-center gap-2 rounded-md border border-input bg-card px-[var(--input-padding-x)] shadow-sm transition-colors hover:border-ring focus-within:border-ring focus-within:ring-2 focus-within:ring-ring/10 aria-invalid:border-destructive aria-invalid:focus-within:ring-destructive/10',
   {
     variants: { size: SIZE_TO_HEIGHT },
     defaultVariants: { size: 'md' },

package/src/components/input-group/input-group.tsx

@@ -33,8 +33,8 @@ const InputGroup = React.forwardRef<HTMLDivElement, InputGroupProps>(
       ref={ref}
       data-disabled={disabled ? '' : undefined}
       className={cn(
-        'flex w-full items-stretch overflow-hidden rounded-md border border-input bg-background shadow-sm',
-        'focus-within:ring-1 focus-within:ring-ring',
+        'flex w-full items-stretch overflow-hidden rounded-md border border-input bg-card shadow-sm',
+        'hover:border-ring focus-within:border-ring focus-within:ring-2 focus-within:ring-ring/10',
         'data-[disabled]:cursor-not-allowed data-[disabled]:opacity-50',
         className,
       )}

package/src/components/input-number/input-number.tsx

@@ -192,8 +192,8 @@ const InputNumber = React.forwardRef<HTMLInputElement, InputNumberProps>(
     return (
       <div
         className={cn(
-          'inline-flex items-stretch overflow-hidden rounded-md border border-input bg-background shadow-sm',
-          'focus-within:ring-1 focus-within:ring-ring',
+          'inline-flex items-stretch overflow-hidden rounded-md border border-input bg-card shadow-sm',
+          'hover:border-ring focus-within:border-ring focus-within:ring-2 focus-within:ring-ring/10',
           disabled && 'cursor-not-allowed opacity-50',
           className,
         )}

package/src/components/native-select/native-select.tsx

@@ -33,8 +33,8 @@ const NativeSelect = React.forwardRef<HTMLSelectElement, NativeSelectProps>(
         ref={ref}
         disabled={disabled}
         className={cn(
-          'flex h-9 w-full appearance-none rounded-md border border-input bg-background py-1 pl-3 pr-8 text-xs shadow-sm',
-          'focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring',
+          'flex h-9 w-full appearance-none rounded-md border border-input bg-card py-1 pl-3 pr-8 text-xs shadow-sm',
+          'focus-visible:outline-none hover:border-ring focus-visible:border-ring focus-visible:ring-2 focus-visible:ring-ring/10',
           'disabled:cursor-not-allowed disabled:opacity-50',
           className,
         )}

package/src/components/page-header/page-header.meta.md

@@ -21,7 +21,8 @@ package: '@teamix-evo/ui'
 
 ## When NOT to use
 
-- **页面内子区块标题** → 用 [`Title`](../typography/typography.meta.md) + 自定义容器,PageHeader 强制 `<header>` + 边框 + 内边距,不适合内嵌
+- **页面内子区块标题** → 用 [`Title`](../typography/typography.meta.md) + 自定义容器,PageHeader 是页面级容器(`<header>` + flex 列布局),不适合内嵌
+
 - **Modal / Drawer 头部** → 这些组件自带 header 区域(`DialogHeader` / `SheetHeader`),不要再叠 PageHeader
 - **需要随滚动吸顶的特殊容器** → PageHeader 自身不内置 sticky,真有诉求外层包 `<div className="sticky top-0 z-10">`
 
@@ -76,6 +77,7 @@ pnpm add lucide-react@^0.460.0
 
 ### 硬约束
 
+- **Padding 由 PageContainer 层提供** — PageHeader 自身只含 `bg-background` 与 flex 列布局,**不带 padding**。实际使用必须放在 `UmPageContainer` / `OpPageContainer` 或消费方自建 wrapper 内,由外层加 `px-6 py-4`(或变体自己的尺寸)。stories 通过 decorator 包 `<div className="px-6 py-4">` 模拟容器内展示。
 - **不接受配置对象** — 不要给 PageHeader 加 `breadcrumbs={[...]}` / `actions={[...]}` / `tags={[...]}` 一类的配置,**所有内容必须用子组件 + 原子组件组合**(P3 一图流原则:看到 jsx 即看到 DOM)
 - **`PageHeaderSkeleton` 与 `PageHeader` 是替换关系** — 不要把 Skeleton 放进 `<PageHeader>...</PageHeader>` 里,加载态条件渲染整体替换
 - **`onBack` 是纯回调** — 不要在 PageHeader 内部 import `react-router` / `next/navigation`,路由由调用方在 `onBack` 里实现(P5 不绑框架)

package/src/components/page-header/page-header.stories.tsx

@@ -43,10 +43,17 @@ const meta: Meta<typeof PageHeader> = {
     docs: {
       description: {
         component:
-          'PageHeader 页头容器 —— 承接 teamix-pro `ProPageHeader` 的视觉规范,转为 shadcn 复合组件范式(Nav / Heading / Description / Content / Actions / Data / DataItem / Footer / Skeleton 子组件)。**纯排版骨架,不接受配置对象** — 面包屑 / 标签 / 操作按钮 / 详情面板都由消费方用 `<Breadcrumb>` / `<Tag>` / `<Button>` / `<Descriptions>` 等原子组件自由组合;图标采用 `<Icon variant="circle|square" color="...">{children}</Icon>` 带背景容器范式。背景图通过 `backgroundImage` prop inline `style` 注入。`onBack` 纯回调,不绑定路由库。',
+          'PageHeader 页头容器 —— 承接 teamix-pro `ProPageHeader` 的视觉规范,转为 shadcn 复合组件范式(Nav / Heading / Description / Content / Actions / Data / DataItem / Footer / Skeleton 子组件)。**纯排版骨架,不接受配置对象** — 面包屑 / 标签 / 操作按钮 / 详情面板都由消费方用 `<Breadcrumb>` / `<Tag>` / `<Button>` / `<Descriptions>` 等原子组件自由组合;图标采用 `<Icon variant="circle|square" color="...">{children}</Icon>` 带背景容器范式。背景图通过 `backgroundImage` prop inline `style` 注入。`onBack` 纯回调,不绑定路由库。\n\n**Padding**:组件自身不含外边距 — 实际使用时由 PageContainer 层(如 `UmPageContainer` / `OpPageContainer`)提供 padding。下方 Story 通过 decorator 包 `<div className="px-6 py-4">` 模拟容器内的展示效果。',
       },
     },
   },
+  decorators: [
+    (Story) => (
+      <div className="bg-background px-6 py-4">
+        <Story />
+      </div>
+    ),
+  ],
 };
 
 export default meta;

package/src/components/page-header/page-header.tsx

@@ -29,7 +29,7 @@ const PageHeader = React.forwardRef<HTMLElement, PageHeaderProps>(
       <header
         ref={ref}
         className={cn(
-          'relative flex flex-col gap-4 overflow-hidden bg-background px-6 py-4',
+          'relative flex min-h-[var(--page-header-height)] flex-col gap-4',
           className,
         )}
         style={bgStyle}
@@ -125,7 +125,7 @@ const PageHeaderDescription = React.forwardRef<
 >(({ className, ...props }, ref) => (
   <p
     ref={ref}
-    className={cn('text-xs text-muted-foreground', className)}
+    className={cn('my-2 text-xs text-muted-foreground', className)}
     {...props}
   />
 ));
@@ -139,7 +139,10 @@ const PageHeaderActions = React.forwardRef<
 >(({ className, ...props }, ref) => (
   <div
     ref={ref}
-    className={cn('flex shrink-0 items-center gap-2', className)}
+    className={cn(
+      'flex shrink-0 items-center gap-[var(--button-gap)]',
+      className,
+    )}
     {...props}
   />
 ));
@@ -249,7 +252,7 @@ const PageHeaderSkeleton = React.forwardRef<
   ) => (
     <div
       ref={ref}
-      className={cn('flex flex-col gap-4 bg-background px-6 py-4', className)}
+      className={cn('flex flex-col gap-4', className)}
       aria-busy="true"
       {...props}
     >

package/src/components/page-shell/page-shell.meta.md

@@ -0,0 +1,116 @@
+---
+id: page-shell
+name: PageShell
+displayName: 页面壳
+type: component
+category: layout
+since: 0.1.0
+package: '@teamix-evo/ui'
+---
+
+# PageShell 页面壳
+
+页面级三明治壳 — `header` + `sidebar` + `children` 三 slot 任意组合,覆盖"全屏 / 仅顶部 / 仅左导 / 顶部+左导" 四种页面形态。`background` prop 走 shadcn 语义槽枚举(`background` / `muted` / `card` / `sidebar` / `accent`),亮暗模式由 [`@teamix-evo/tokens`](../../../../tokens/) 文件自动管。
+
+PageShell 传 `sidebar` 时内部用 [`<SidebarProvider embedded>`](../sidebar/sidebar.meta.md) —— ui Sidebar 的嵌入模式,sidebar-container 自动走 `position: relative + h-full`(替代默认 `fixed inset-y-0 h-svh`),与 header 共存而不被撑到 viewport 顶端。消费方不再需要手写 `!relative !top-0 !h-full` hack。
+
+## When to use
+
+- **应用主页面骨架** — 控制台 / dashboard / 管理后台等所有需要 sidebar/topbar 的页面
+- **无 sidebar 全屏页** — 登录页 / 错误页 / 落地页(不传 `sidebar` 即可)
+- **opentrek 风格无吊顶 layout** — 仅传 `sidebar`,主区背景设 `muted`
+- **uni-manager 风格吊顶+左导** — 同时传 `header={<UmTopbar />}` 与 `sidebar={<Sidebar />}`
+
+## When NOT to use
+
+- **页面内子布局**(分屏 / 多面板)→ 直接用 flex / grid,PageShell 是页面级唯一壳
+- **Modal / Drawer 内的布局** → 这些组件自带容器,不要再叠 PageShell
+- **路由级布局共享** — 这是 React Router / Next.js layout 层职责,PageShell 是渲染层
+
+## Props
+
+<!-- auto:props:begin -->
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `header` | `ReactNode` | – | – | 顶部条 slot — 通常是 UmTopbar / 自建 navbar。不传则不渲染顶部。 |
+| `sidebar` | `ReactNode` | – | – | 左侧 slot — 通常是 ui `<Sidebar>` 或基于它组合的整装件(如 OpSidebar)。不传则不渲染 sidebar 与 SidebarProvider。 |
+| `background` | `'background' \| 'muted' \| 'card' \| 'sidebar' \| 'accent'` | `'background'` | – | 主区背景 — 走 shadcn 语义槽枚举,亮暗模式由 token 文件自动切换。 |
+| `sidebarWidth` | `string` | `'14rem'` | – | sidebar 宽度 — 透传给 SidebarProvider 的 `--sidebar-width` CSS 变量。仅在传 `sidebar` 时生效。 |
+<!-- auto:props:end -->
+
+## 依赖
+
+<!-- auto:deps:begin -->
+### 同库依赖
+
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具 |
+| `sidebar` | component | shadcn Sidebar 25 primitives |
+<!-- auto:deps:end -->
+
+## AI 生成纪律
+
+### 硬约束
+
+- **不传 `sidebar` 时不要在 children 内调用 `useSidebar()`** — PageShell 不传 sidebar 即不渲染 SidebarProvider,无 sidebar context
+- **`background` 必须用枚举值,不要传 raw className** — 想要其他背景请扩 `PageShellBackground` 枚举或在 children 内自加 wrapper
+- **不要在 PageShell 外再包 `SidebarProvider`** — PageShell 传 sidebar 时自带,重复包会破坏 cookie 持久化与 Cmd+B 快捷键
+- **sidebar slot 传 ui `<Sidebar>` 时不需要再加 `className="!relative ..."`** — PageShell 已注入 scoped CSS 覆盖
+
+### 推荐范式
+
+- 全屏:`<PageShell><LoginForm /></PageShell>`
+- opentrek 无吊顶:`<PageShell background="muted" sidebar={<OpSidebar />}><OpPageContainer>...</OpPageContainer></PageShell>`
+- uni-manager 吊顶+左导:`<PageShell header={<UmTopbar ... />} sidebar={<Sidebar>...</Sidebar>}><UmPageContainer>...</UmPageContainer></PageShell>`
+
+### 反例
+
+- ❌ 在 PageShell 外手动包 `<SidebarProvider>` — 重复 provider
+- ❌ `background="#f7f7f7"` 传颜色值 — 必须用枚举,违反 token discipline
+- ❌ 不传 `sidebar` 但 children 内用 `useSidebar()` — 报错"must be used within a SidebarProvider"
+
+## Examples
+
+```tsx
+import { PageShell } from '@/components/page-shell/page-shell';
+import { Sidebar, SidebarContent, SidebarMenu, ... } from '@/components/sidebar/sidebar';
+
+// 全屏单区 — 登录页
+<PageShell>
+  <LoginForm />
+</PageShell>
+
+// 仅顶部 — 简单页面
+<PageShell header={<Navbar />}>
+  <main>...</main>
+</PageShell>
+
+// 仅 sidebar — opentrek 风格(灰底)
+<PageShell background="muted" sidebar={<OpSidebar />}>
+  <OpPageContainer header={...}>...</OpPageContainer>
+</PageShell>
+
+// 完整三明治 — uni-manager 风格(白底)
+<PageShell
+  header={<UmTopbar brand={...} menus={...} ... />}
+  sidebar={<Sidebar collapsible="icon">...</Sidebar>}
+  sidebarWidth="14rem"
+>
+  <UmPageContainer header={<PageHeader>...</PageHeader>}>
+    <DataTable ... />
+  </UmPageContainer>
+</PageShell>
+```
+
+## 实现细节
+
+PageShell 传 `sidebar` 时,内部用 `<SidebarProvider embedded ...>` 启用 ui Sidebar 的嵌入模式。该模式下 [Sidebar](../sidebar/sidebar.meta.md) 的 `sidebar-container` 自动从默认 `fixed inset-y-0 h-svh` 切到 `relative h-full`,让 sidebar 跟 header 在同一布局流里垂直对齐 —— 完全声明式,无 scoped CSS、无 `!important` 覆盖。
+
+`embedded` 是 ui SidebarProvider 的原生 prop(默认 `false` 保持 shadcn 全屏行为),由 context 透传给所有下游 `<Sidebar>` 自动响应。
+
+## 关联
+
+- 范本组件:[Sidebar](../sidebar/sidebar.meta.md) — PageShell 内嵌的 SidebarProvider / SidebarInset 来自这里
+- 关联组件:[PageHeader](../page-header/page-header.meta.md) — 页面内 PageContainer 的 header slot 首选
+- 关联 ADR:[ADR 0005](../../../../../docs/adr/0005-ui-no-variant.md) — ui 不感知 variant,具体页面壳由 biz-ui 的 OpPageContainer / UmPageContainer 在 PageShell 内拼装