sparkdesign 0.4.9 → 0.4.10

package/AGENT_COMPONENT_LIBRARY_QUICKREF.md

@@ -0,0 +1,117 @@
+# Spark Design Agent Quick Reference
+
+> 给进入本仓库的 agent 的 1 页速查卡。详细说明见 [docs/guides/agent-usage.md](./docs/guides/agent-usage.md)；组件选择见 [docs/agent/component-selection.md](./docs/agent/component-selection.md)；项目级质量标准见 [docs/guides/system-operating-model.md](./docs/guides/system-operating-model.md)；可复制提示词见 [docs/agent/prompt-recipes.md](./docs/agent/prompt-recipes.md)。
+
+## 默认选择
+
+- 默认优先：`npx sparkdesign@latest add <component>`
+- 次选：`npm install sparkdesign`
+- 只有用户明确要整包 import，或项目已经在用整包时，才优先走整包
+
+## 两条路径不要混用
+
+### CLI 本地源码模式
+
+使用：
+
+```bash
+npx sparkdesign@latest init
+npx sparkdesign@latest add button
+```
+
+默认导入：
+
+```tsx
+import { Button } from '@/components/ui/basic/button'
+import { Response } from '@/components/ui/chat/response'
+```
+
+不要再写：
+
+```tsx
+import { Button } from 'sparkdesign'
+```
+
+### 整包模式
+
+使用：
+
+```bash
+npm install sparkdesign
+```
+
+导入：
+
+```tsx
+import 'sparkdesign/style'
+import { Button, Response } from 'sparkdesign'
+```
+
+## 样式硬规则
+
+- 一律优先 design tokens，不要硬编码颜色、圆角、间距
+- 根节点优先设置 `data-theme` 和 `data-style`
+- Portal / 浮层组件要考虑 theme/style 继承，不要靠 remount 刷主题
+
+允许：
+
+```tsx
+className="bg-primary text-text rounded-md"
+className="px-[var(--spacing-3)]"
+```
+
+不允许：
+
+```tsx
+className="bg-[#1890FF] text-[#333] rounded-[10px]"
+```
+
+## 组件选择
+
+- 先读 `registry/agent-manifest.json`，按 intent、states、a11y、composition、antiPatterns 选择
+- `basic/*`: 通用 UI
+- `chat/*`: 对话流 UI
+- 常见组合优先看 manifest recipes，不要只按组件名猜
+
+优先复用已有组件：
+
+- `button` / `icon-button`
+- `tooltip` / `dropdown-menu` / `alert-dialog`
+- `chat-input`
+- `response`
+- `reasoning-step`
+- `code-block-part` / `terminal-code-block-part`
+- `task-part` / `plan-part`
+
+## 影响 CLI 时必须检查
+
+- `registry/`
+- `registry/meta.json`
+- `cli/registry/` 是否已同步
+- `npm run check:registry-meta`
+
+## 组件完成定义
+
+组件不只是源码文件。公开变更完成前，必须让这些表面一致：
+
+- registry 源码与 CLI 副本
+- 主包导出与 props 类型
+- showcase demo / config / props / 本地化标签
+- `registry/agent-manifest.json` 的 intent、states、a11y、composition、antiPatterns
+- P3 header 与相关 P2 map
+
+## 发布规则
+
+- **唯一发布入口是仓库根目录**
+- 不要从 `cli/` 目录执行 `npm publish`
+- 根包 `sparkdesign` 同时承载：
+  - 运行时整包
+  - `bin.sparkdesign -> ./cli/dist/index.js`
+
+## 开工前先回答 5 个问题
+
+1. 当前项目是在用 CLI 本地源码，还是整包 import？
+2. 目标组件属于 `basic` 还是 `chat`？
+3. 是否已有可复用组件？
+4. 样式是否完全基于 token？
+5. 改动会不会影响 CLI registry 与发布链路？

package/AI_README.md

@@ -7,8 +7,11 @@ Spark Design correctly.
 
 1. `registry/agent-manifest.json` — choose components by intent, slots, states, accessibility, composition, and anti-patterns.
 2. `registry/tokens/ontology.json` — choose token families by semantic purpose before writing styles.
-3. `docs/guides/agent-usage.md` — consumption rules for CLI copy vs package import.
-4. Component source only after the manifest tells you which component to use.
+3. `docs/guides/system-operating-model.md` — quality bar for structure, showcase, AI semantics, and maintenance gates.
+4. `docs/agent/component-selection.md` — decision order, name boundaries, recipes, and manifest maintenance.
+5. `docs/agent/prompt-recipes.md` — copyable prompts for install, screen composition, AI workflows, component changes, and audits.
+6. `docs/guides/agent-usage.md` — consumption rules for CLI copy vs package import.
+7. Component source only after the manifest tells you which component to use.
 
 For npm package consumers:
 
@@ -22,7 +25,9 @@ import ontology from 'sparkdesign/token-ontology.json'
 - Prefer `npx sparkdesign@latest add <component>` when building a business app that should own component source.
 - Prefer `import { Component } from 'sparkdesign'` only for prototypes, showcase usage, or projects already using the package runtime.
 - Use `basic/*` for product primitives and `chat/*` for assistant, tool, file, reasoning, and response flows.
+- Choose components by manifest intent and anti-patterns before matching by name.
 - Use `data-theme` for color and `data-style` for density, radius, and rhythm.
+- Treat showcase, docs, registry metadata, and agent manifest updates as one public contract when a component changes.
 
 ## Hard Rules
 

package/README.md

@@ -2,7 +2,7 @@
 
 现代化 React 设计系统，支持双维度主题（颜色 theme + 布局 scale），5 种内置布局风格，提供 Basic 基础组件与 Chat 对话流组件，可扩展颜色主题。
 
-**当前版本**：`0.4.6`（[CLI 快速上手](docs/getting-started-cli.md) / [NPM 快速上手](docs/getting-started.md)）
+**当前版本**：`0.4.9`（[CLI 快速上手](docs/getting-started-cli.md) / [NPM 快速上手](docs/getting-started.md)）
 
 > 🌟 **纯新手？** 查看 [CLI 快速上手指南](docs/getting-started-cli.md)，一步步带你跑起来！
 
@@ -17,6 +17,9 @@
 - **图标系统可替换**：通过 `IconsProvider` 接 Lucide、Remix 或自定义图标库
 - **Tailwind 友好**：类名与设计 token 映射，无硬编码色值
 - **组件分层**：Basic 原子组件 + Chat 对话组件，开箱即用
+- **AI 友好契约**：`agent-manifest.json` + token ontology + component selection guide 让 agent 按 intent、states、a11y、composition 和 anti-patterns 选择组件
+- **可复制 Agent Recipes**：安装、页面组合、AI 工作流、组件维护和审查都有提示词模板
+- **同构维护流程**：registry、CLI、showcase、docs、P2/P3 与发布门禁保持一致
 
 ## 两种使用方式
 

package/cli/registry/AGENTS.md

@@ -4,7 +4,7 @@
 
 ## Member list
 
-- `basic/` — accordion, alert, alert-dialog, aspect-ratio, avatar, badge, breadcrumb, button, button-group, calendar, card, carousel, chart, checkbox, collapse, collapsible, collapsible-card, combobox, command, context-menu, data-table, date-picker, dialog, direction, drawer, dropdown-menu, ellipsis-text, empty, field, form, hover-card, icon-button, input, input-group, input-otp, item, kbd, label, menubar, native-select, navigation-menu, option-list, pagination, popover, progress, radio-group, resizable, scroll-area, scrollbar, select, separator, sheet, shimmering-text, sidebar, sidebar-menu, skeleton, slider, sonner, spinner, switch, table, tabs, tag, textarea, toggle, tooltip, typography.
+- `basic/` — accordion, alert, alert-dialog, aspect-ratio, avatar, badge, breadcrumb, button, button-group, calendar, card, carousel, chart, checkbox, collapse, collapsible, collapsible-card, combobox, command, context-menu, data-table, date-picker, dialog, direction, drawer, dropdown-menu, ellipsis-text, empty, field, form, hover-card, icon-button, input, input-group, input-otp, item, kbd, label, menubar, native-select, navigation-menu, option-list, pagination, popover, progress, radio-group, rating, resizable, scroll-area, scrollbar, select, separator, shimmering-text, sidebar, sidebar-menu, skeleton, slider, spinner, stepper, switch, table, tabs, tag, textarea, timeline, toggle, tooltip, typography.
 - `chat/` — ask-user-part, browser-action-part, chat-input, code-block-part, conversation-anchor-nav, file-attachment, file-card, file-review-part, folder-button, generated-images-grid, generation-status-bar, hint-banner, image-attachment, image-generating, markdown, mermaid-part, permission-card, plan-part, queue-indicator, reasoning-step, related-prompts, response, send-button, streaming-markdown-block, task-part, terminal-code-block-part, thinking-indicator, tool-invocation-card, user-message, user-question, user-question-answer.
 - `lib/` — file-icon-maps, use-mermaid-render, utils; helper modules copied with registry components when needed.
 - `tokens/` — index.css, theme.css, theme-base.css, scale.css, ontology.json, scrollbar utility, theme presets, and scale token packs.

package/cli/registry/agent-manifest.json

@@ -933,55 +933,7 @@
       ],
       "agentHints": [
         "Choose Popover for compact pickers and contextual controls.",
-        "Use Dialog or Sheet when the content needs more space."
-      ]
-    },
-    "sheet": {
-      "id": "sheet",
-      "name": "Sheet",
-      "category": "basic",
-      "status": "stable",
-      "intent": "Side panel overlay for contextual details, filters, settings, or secondary editing flows.",
-      "packageImport": "import { Sheet, SheetTrigger, SheetContent, SheetHeader, SheetTitle, SheetDescription } from 'sparkdesign'",
-      "cliAdd": "npx sparkdesign@latest add sheet",
-      "slots": [
-        "Sheet",
-        "SheetTrigger",
-        "SheetContent",
-        "SheetHeader",
-        "SheetTitle",
-        "SheetDescription",
-        "SheetFooter"
-      ],
-      "states": [
-        "open",
-        "closed",
-        "side-left",
-        "side-right",
-        "side-top",
-        "side-bottom",
-        "focus-trapped"
-      ],
-      "a11y": [
-        "Always provide SheetTitle.",
-        "Use SheetDescription when the panel purpose is not obvious.",
-        "Return focus to the trigger after close."
-      ],
-      "composition": [
-        "Button",
-        "Field",
-        "Tabs",
-        "SidebarMenu",
-        "Alert"
-      ],
-      "antiPatterns": [
-        "Do not use Sheet for destructive confirmations; use AlertDialog.",
-        "Do not create nested sheets unless the product specifically requires it.",
-        "Do not put primary app navigation in a temporary sheet on desktop when persistent navigation is expected."
-      ],
-      "agentHints": [
-        "Choose Sheet for secondary panels that preserve page context.",
-        "Use Drawer when the product already follows drawer terminology or behavior."
+        "Use Dialog or Drawer when the content needs more space."
       ]
     },
     "sidebar-menu": {
@@ -2004,6 +1956,49 @@
         "Use Spinner for brief unknown-duration loading."
       ]
     },
+    "rating": {
+      "id": "rating",
+      "name": "Rating",
+      "category": "basic",
+      "status": "stable",
+      "intent": "Star-based score or preference input for reviews, quality signals, and lightweight sentiment feedback.",
+      "packageImport": "import { Rating } from 'sparkdesign'",
+      "cliAdd": "npx sparkdesign@latest add rating",
+      "slots": [
+        "Rating",
+        "stars",
+        "numeric value by option",
+        "accessible label"
+      ],
+      "states": [
+        "controlled",
+        "uncontrolled",
+        "whole precision",
+        "half precision",
+        "read-only",
+        "disabled"
+      ],
+      "a11y": [
+        "Provide a clear label when the rating is an input.",
+        "Use readOnly for static review summaries.",
+        "Do not rely on star color alone when numeric precision matters."
+      ],
+      "composition": [
+        "Card",
+        "Field",
+        "Label",
+        "Tooltip"
+      ],
+      "antiPatterns": [
+        "Do not use Rating for exact numeric entry; use Input or Slider.",
+        "Do not ask for ratings when the user needs categorical choices.",
+        "Do not hide the current value in dense analytics summaries."
+      ],
+      "agentHints": [
+        "Choose Rating for familiar 1-5 preference capture or review display.",
+        "Use precision={0.5} only when half steps are meaningful to users."
+      ]
+    },
     "resizable": {
       "id": "resizable",
       "name": "Resizable",
@@ -2682,6 +2677,99 @@
         "Pair with Input when users need precise values."
       ]
     },
+    "stepper": {
+      "id": "stepper",
+      "name": "Stepper",
+      "category": "basic",
+      "status": "stable",
+      "intent": "Linear workflow progress for setup, checkout, approval, onboarding, and multi-step task status.",
+      "packageImport": "import { Stepper, StepperItem, StepperIndicator, StepperContent, StepperTitle, StepperDescription, StepperSeparator } from 'sparkdesign'",
+      "cliAdd": "npx sparkdesign@latest add stepper",
+      "slots": [
+        "Stepper",
+        "StepperItem",
+        "StepperIndicator",
+        "StepperContent",
+        "StepperTitle",
+        "StepperDescription",
+        "StepperSeparator"
+      ],
+      "states": [
+        "horizontal",
+        "vertical",
+        "complete",
+        "current",
+        "upcoming",
+        "error"
+      ],
+      "a11y": [
+        "Use ordered steps when sequence matters.",
+        "Make the current step visible in text, not only color.",
+        "Do not hide validation errors behind completed-looking steps."
+      ],
+      "composition": [
+        "Button",
+        "Progress",
+        "Alert",
+        "Card"
+      ],
+      "antiPatterns": [
+        "Do not use Stepper for non-linear tabs; use Tabs.",
+        "Do not show too many steps when grouped milestones would scan better.",
+        "Do not mark future steps as interactive unless navigation is supported."
+      ],
+      "agentHints": [
+        "Choose Stepper when users need to understand where they are in a process.",
+        "Use vertical orientation for verbose workflow history or mobile layouts."
+      ]
+    },
+    "timeline": {
+      "id": "timeline",
+      "name": "Timeline",
+      "category": "basic",
+      "status": "stable",
+      "intent": "Chronological event list for activity history, releases, audit logs, and milestone narratives.",
+      "packageImport": "import { Timeline, TimelineItem, TimelineMarker, TimelineConnector, TimelineContent, TimelineTitle, TimelineDescription, TimelineTime } from 'sparkdesign'",
+      "cliAdd": "npx sparkdesign@latest add timeline",
+      "slots": [
+        "Timeline",
+        "TimelineItem",
+        "TimelineMarker",
+        "TimelineConnector",
+        "TimelineContent",
+        "TimelineTitle",
+        "TimelineDescription",
+        "TimelineTime"
+      ],
+      "states": [
+        "default",
+        "primary",
+        "success",
+        "warning",
+        "error",
+        "last item without connector"
+      ],
+      "a11y": [
+        "Keep event order clear and consistent.",
+        "Include timestamps or labels when chronology matters.",
+        "Do not encode event meaning only through marker color."
+      ],
+      "composition": [
+        "Badge",
+        "Tag",
+        "Card",
+        "Separator"
+      ],
+      "antiPatterns": [
+        "Do not use Timeline for dense tabular audit data; use Table or DataTable.",
+        "Do not mix ascending and descending order in the same view.",
+        "Do not overload markers with unrelated status meanings."
+      ],
+      "agentHints": [
+        "Choose Timeline for readable event progression or product release histories.",
+        "Use tone sparingly for the few events that need semantic emphasis."
+      ]
+    },
     "toggle": {
       "id": "toggle",
       "name": "Toggle",
@@ -2861,50 +2949,6 @@
         "Use Alert for feedback that must remain visible."
       ]
     },
-    "sonner": {
-      "id": "sonner",
-      "name": "Sonner",
-      "category": "basic",
-      "status": "stable",
-      "intent": "Sonner toaster entry using Spark token styling and theme/style portal inheritance.",
-      "packageImport": "import { Toaster, toast } from 'sparkdesign'",
-      "cliAdd": "npx sparkdesign@latest add sonner",
-      "slots": [
-        "Toaster",
-        "toast function",
-        "toast options",
-        "icons",
-        "portal wrapper"
-      ],
-      "states": [
-        "success",
-        "error",
-        "warning",
-        "info",
-        "loading",
-        "dismissed"
-      ],
-      "a11y": [
-        "Use concise notification text.",
-        "Do not put required decisions only in sonner toasts.",
-        "Ensure critical errors also appear inline when users need to recover."
-      ],
-      "composition": [
-        "Button",
-        "Alert",
-        "Form",
-        "ToolInvocationCard"
-      ],
-      "antiPatterns": [
-        "Do not use Sonner for persistent validation or destructive confirmation.",
-        "Do not stack noisy success toasts for every small state change.",
-        "Do not hide important recovery actions inside an auto-dismissing toast."
-      ],
-      "agentHints": [
-        "Choose Sonner when the target explicitly asks for the sonner toaster API.",
-        "Choose Toast when describing the semantic notification pattern."
-      ]
-    },
     "tooltip": {
       "id": "tooltip",
       "name": "Tooltip",

package/cli/registry/basic/calendar.tsx

@@ -31,7 +31,7 @@ function Calendar({
     <DayPicker
       showOutsideDays={showOutsideDays}
       className={cn(
-        "group/calendar bg-bg-base p-3 [--cell-size:--spacing(8)] [[data-slot=card-content]_&]:bg-transparent [[data-slot=popover-content]_&]:bg-transparent",
+        "group/calendar bg-bg-base p-3 [--cell-size:2rem] [[data-slot=card-content]_&]:bg-transparent [[data-slot=popover-content]_&]:bg-transparent",
         String.raw`rtl:**:[.rdp-button\_next>svg]:rotate-180`,
         String.raw`rtl:**:[.rdp-button\_previous>svg]:rotate-180`,
         className
@@ -55,24 +55,24 @@ function Calendar({
         ),
         button_previous: cn(
           buttonVariants({ variant: buttonVariant }),
-          "size-(--cell-size) p-0 select-none aria-disabled:opacity-50",
+          "h-[var(--cell-size)] w-[var(--cell-size)] p-0 select-none aria-disabled:opacity-50",
           defaultClassNames.button_previous
         ),
         button_next: cn(
           buttonVariants({ variant: buttonVariant }),
-          "size-(--cell-size) p-0 select-none aria-disabled:opacity-50",
+          "h-[var(--cell-size)] w-[var(--cell-size)] p-0 select-none aria-disabled:opacity-50",
           defaultClassNames.button_next
         ),
         month_caption: cn(
-          "flex h-(--cell-size) w-full items-center justify-center px-(--cell-size)",
+          "flex h-[var(--cell-size)] w-full items-center justify-center px-[var(--cell-size)]",
           defaultClassNames.month_caption
         ),
         dropdowns: cn(
-          "flex h-(--cell-size) w-full items-center justify-center gap-1.5 text-sm font-medium",
+          "flex h-[var(--cell-size)] w-full items-center justify-center gap-1.5 text-sm font-medium",
           defaultClassNames.dropdowns
         ),
         dropdown_root: cn(
-          "relative rounded-md border border-border-tertiary shadow-sm has-focus:border-primary-border has-focus:ring-[3px] has-focus:ring-primary-border/50",
+          "has-focus:border-primary-border border-border-tertiary shadow-sm has-focus:ring-primary-border/50 has-focus:ring-[3px] relative rounded-md border",
           defaultClassNames.dropdown_root
         ),
         dropdown: cn(
@@ -80,7 +80,7 @@ function Calendar({
           defaultClassNames.dropdown
         ),
         caption_label: cn(
-          "font-medium select-none",
+          "select-none font-medium",
           captionLayout === "label"
             ? "text-sm"
             : "flex h-8 items-center gap-1 rounded-md pr-1 pl-2 text-sm [&>svg]:size-3.5 [&>svg]:text-text-tertiary",
@@ -94,7 +94,7 @@ function Calendar({
         ),
         week: cn("mt-2 flex w-full", defaultClassNames.week),
         week_number_header: cn(
-          "w-(--cell-size) select-none",
+          "w-[var(--cell-size)] select-none",
           defaultClassNames.week_number_header
         ),
         week_number: cn(
@@ -102,20 +102,20 @@ function Calendar({
           defaultClassNames.week_number
         ),
         day: cn(
-          "group/day relative aspect-square h-full w-full p-0 text-center select-none [&:last-child[data-selected=true]_button]:rounded-r-md",
+          "group/day relative aspect-square h-full w-full p-0 text-center select-none [&:last-child[data-selected=true]_button]:rounded-r-sm",
           props.showWeekNumber
-            ? "[&:nth-child(2)[data-selected=true]_button]:rounded-l-md"
-            : "[&:first-child[data-selected=true]_button]:rounded-l-md",
+            ? "[&:nth-child(2)[data-selected=true]_button]:rounded-l-sm"
+            : "[&:first-child[data-selected=true]_button]:rounded-l-sm",
           defaultClassNames.day
         ),
         range_start: cn(
-          "rounded-l-md bg-fill-secondary",
+          "rounded-l-sm bg-fill-secondary",
           defaultClassNames.range_start
         ),
         range_middle: cn("rounded-none", defaultClassNames.range_middle),
-        range_end: cn("rounded-r-md bg-fill-secondary", defaultClassNames.range_end),
+        range_end: cn("rounded-r-sm bg-fill-secondary", defaultClassNames.range_end),
         today: cn(
-          "rounded-md bg-fill-secondary text-text data-[selected=true]:rounded-none",
+          "rounded-sm bg-fill-secondary text-text data-[selected=true]:rounded-sm",
           defaultClassNames.today
         ),
         outside: cn(
@@ -164,7 +164,7 @@ function Calendar({
         WeekNumber: ({ children, ...props }) => {
           return (
             <td {...props}>
-              <div className="flex size-(--cell-size) items-center justify-center text-center">
+              <div className="flex size-[var(--cell-size)] items-center justify-center text-center">
                 {children}
               </div>
             </td>
@@ -209,7 +209,7 @@ function CalendarDayButton({
       data-range-middle={modifiers.range_middle}
       className={cn(
         "inline-flex items-center justify-center transition-colors hover:bg-fill-secondary hover:text-text",
-        "flex aspect-square size-auto w-full min-w-(--cell-size) flex-col gap-1 px-0 leading-none font-normal group-data-[focused=true]/day:relative group-data-[focused=true]/day:z-10 group-data-[focused=true]/day:border-primary-border group-data-[focused=true]/day:ring-[3px] group-data-[focused=true]/day:ring-primary-border/50 data-[range-end=true]:rounded-md data-[range-end=true]:rounded-r-md data-[range-end=true]:bg-primary data-[range-end=true]:text-text-on-primary data-[range-middle=true]:rounded-none data-[range-middle=true]:bg-fill-secondary data-[range-middle=true]:text-text data-[range-start=true]:rounded-md data-[range-start=true]:rounded-l-md data-[range-start=true]:bg-primary data-[range-start=true]:text-text-on-primary data-[selected-single=true]:bg-primary data-[selected-single=true]:text-text-on-primary dark:hover:text-text [&>span]:text-xs [&>span]:opacity-70",
+        "flex aspect-square size-auto w-full min-w-[var(--cell-size)] flex-col gap-1 px-0 leading-none font-normal hover:rounded-sm group-data-[focused=true]/day:relative group-data-[focused=true]/day:z-10 group-data-[focused=true]/day:border-primary-border group-data-[focused=true]/day:ring-[3px] group-data-[focused=true]/day:ring-primary-border/50 data-[range-end=true]:rounded-sm data-[range-end=true]:rounded-r-sm data-[range-end=true]:bg-primary data-[range-end=true]:text-text-on-primary data-[range-middle=true]:rounded-none data-[range-middle=true]:bg-fill-secondary data-[range-middle=true]:text-text data-[range-start=true]:rounded-sm data-[range-start=true]:rounded-l-sm data-[range-start=true]:bg-primary data-[range-start=true]:text-text-on-primary data-[selected=true]:rounded-sm data-[selected=true]:!outline-none data-[selected=true]:!shadow-none data-[selected=true]:!ring-0 data-[selected=true]:!ring-offset-0 data-[selected=true]:!border-transparent data-[selected=true]:focus-visible:!ring-0 data-[selected=true]:focus-visible:!outline-none data-[selected-single=true]:rounded-sm data-[selected-single=true]:bg-primary data-[selected-single=true]:text-text-on-primary dark:hover:text-text [&>span]:text-xs [&>span]:opacity-70",
         defaultClassNames.day,
         className
       )}

package/cli/registry/basic/combobox.tsx

@@ -22,6 +22,7 @@ export interface ComboboxOption {
 
 export interface ComboboxProps {
   options: ComboboxOption[]
+  size?: 'default' | 'compact'
   value?: string
   defaultValue?: string
   onValueChange?: (value: string) => void
@@ -46,6 +47,7 @@ function Combobox({
   placeholder = 'Select an option…',
   searchPlaceholder = 'Search…',
   emptyText = 'No option found.',
+  size = 'compact',
   disabled,
   className,
   contentClassName,
@@ -96,9 +98,16 @@ function Combobox({
         </PopoverTrigger>
         <PopoverContent
           align={align}
-          className={cn('w-[var(--radix-popover-trigger-width)] min-w-56 p-0', contentClassName)}
+          contentPadding="compact"
+          className={cn('w-[var(--radix-popover-trigger-width)] min-w-56', contentClassName)}
         >
-          <Command>
+          <Command
+            className={cn(
+              'w-full',
+              size === 'compact' &&
+                '[&_[data-slot=command-input-wrapper]]:h-8 [&_[data-slot=command-input]]:h-8 [&_[data-slot=command-input-wrapper]]:px-2 [&_[data-slot=command-input]]:py-1.5 [&_[cmdk-group]]:p-0 [&_[cmdk-item]]:px-2 [&_[cmdk-item]]:py-1.5 [&_[data-slot=command-empty]]:py-3'
+            )}
+          >
             <CommandInput placeholder={searchPlaceholder} />
             <CommandList>
               <CommandEmpty>{emptyText}</CommandEmpty>

package/cli/registry/basic/date-picker.tsx

@@ -61,15 +61,16 @@ function DatePicker({
             !selected && 'text-text-tertiary',
             className,
           )}
-          suffixIcon={<CalendarIcon className="ml-auto size-4 opacity-60" />}
+          prefixIcon={<CalendarIcon className="size-4 text-text-tertiary" />}
         >
           {selected ? format(selected, formatString) : <span>{placeholder}</span>}
         </Button>
       </PopoverTrigger>
-      <PopoverContent className="w-auto p-0" align={align}>
+      <PopoverContent className="w-auto" contentPadding="compact" align={align}>
         <Calendar
           mode="single"
           selected={selected}
+          defaultMonth={selected}
           onSelect={handleSelect}
           autoFocus
         />

package/cli/registry/basic/popover.tsx

@@ -14,6 +14,8 @@ export interface PopoverContentProps
   /** When provided (e.g. from ThemeStyleProvider), used for portal wrapper */
   dataStyle?: string
   dataTheme?: string
+  /** Popover internal padding; keep default to avoid breaking existing usages */
+  contentPadding?: 'default' | 'compact' | 'none'
 }
 
 const PopoverContent = React.forwardRef<
@@ -21,7 +23,16 @@ const PopoverContent = React.forwardRef<
   PopoverContentProps
 >(
   (
-    { className, align = 'center', sideOffset = 4, children, dataStyle, dataTheme, ...props },
+    {
+      className,
+      align = 'center',
+      sideOffset = 4,
+      contentPadding = 'default',
+      children,
+      dataStyle,
+      dataTheme,
+      ...props
+    },
     ref,
   ) => {
     const fromDoc = getThemeFromDocument()
@@ -34,10 +45,16 @@ const PopoverContent = React.forwardRef<
         <div style={{ display: 'contents' }} {...dataProps}>
           <PopoverPrimitive.Content
             ref={ref}
+            data-slot="popover-content"
             align={align}
             sideOffset={sideOffset}
             className={cn(
-              'z-50 w-72 rounded-lg border border-border-tertiary bg-bg-container p-4 text-sm text-text shadow-md outline-none',
+              'z-50 w-72 rounded-lg border border-border-tertiary bg-bg-container text-sm text-text shadow-md outline-none',
+              contentPadding === 'none'
+                ? 'p-0'
+                : contentPadding === 'compact'
+                  ? 'p-1'
+                  : 'p-4',
               className,
             )}
             {...props}