### What this PR does
**Before this PR:**
- Right-click menus across the renderer were built with antd's
`Dropdown` (`trigger={['contextMenu']}`) plus an ad-hoc bespoke menu
(`src/renderer/src/components/layout/TabContextMenu.tsx`) for the
AppShell tab bar. There was no shared design-system primitive; styling,
sub-menu support, and `asChild` ergonomics were inconsistent.
- The selection-aware copy/quote wrapper lived at
`src/renderer/src/components/ContextMenu/index.tsx` under a generic name
that suggested it was the canonical context menu (it wasn't — it was
specifically for text selection).
**After this PR:**
- New Radix-based `ContextMenu` primitive lives at
`packages/ui/src/components/primitives/context-menu.tsx`, with the
supporting `ContextMenuItemContent` helper, a new `--cs-menu-item-hover`
design token, and a primitive-level unit test
(`packages/ui/src/components/primitives/__tests__/context-menu.test.tsx`).
- 16 renderer call sites migrated to the new primitive (chat tabs,
topics, agent sessions, attachments, notes, mini-apps, image viewer, SVG
renderer, inputbar tools, citations, messages, skills settings,
assistant items, agent items, assistant preset cards, YAML front
matter).
- `TabContextMenu.tsx` deleted; the old selection wrapper renamed to
`SelectionContextMenu.tsx` and its behavior tightened (see Breaking
changes).
- Async `onSelect` handlers now wrap their work in `try/catch + logger +
toast` so user-visible operations like LLM auto-rename,
save-to-knowledge, and export to Notion/Yuque/etc no longer fail
silently.
Fixes #
### Why we need it and why it was done in this way
`@cherrystudio/ui` is now the v2 design-system home; every other
primitive (Tooltip, Combobox, Toast, TreeSelect, …) has moved here.
Right-click menus were the largest remaining surface still bound to
antd's `Dropdown`. Picking Radix as the backend is consistent with the
rest of the primitive library; building our own `ContextMenuItemContent`
helper keeps the call-site noise low for the common `icon + label +
shortcut/submenu chevron` shape.
The following tradeoffs were made:
- The click-triggered "more actions" Dropdowns in `AssistantItem` /
`AgentItem` / `AssistantPresetCard` / `YamlFrontMatterNodeView` still
use `antd Dropdown` for now — `@cherrystudio/ui` ships `ContextMenu` and
`SelectDropdown` but no click-driven `DropdownMenu` yet. Tracked as
#14994. Acceptable as a follow-up because the migration boundary is at
the right-click surface for this PR.
- `KnowledgePage` / `KnowledgeUrls` / `SkillsSettings` were
intentionally left untouched per @kangfenmao to avoid conflicting with
the knowledge-base PR (#14734). They'll be migrated once that lands.
- For the menu focus-state contrast I originally bumped
`--cs-background-subtle`, but the token leaks into ~44 unrelated
consumers. Reverted and replaced with a dedicated `--cs-menu-item-hover`
token.
The following alternatives were considered:
- Pinning down a click-driven antd shim around the new `ContextMenu` to
handle both triggers in a single tree — rejected; it would have meant
inverting the migration goal (less antd, not more).
- Putting all menu hover styling under one bumped subtle background —
rejected after review; the dedicated `--cs-menu-item-hover` token keeps
the change surgical.
Links to places where the discussion took place:
https://github.com/CherryHQ/cherry-studio/pull/12060#pullrequestreview-4260670092
### Breaking changes
Renamed `ContextMenu` (the selection-aware copy/quote wrapper) to
`SelectionContextMenu`. User-visible behavior change: right-clicking
inside chat messages, citations, and agent session messages now always
shows the menu with disabled items when no text is selected (was: menu
suppressed entirely). Once a selection exists the actions behave
identically to v1. Logged in
`v2-refactor-temp/docs/breaking-changes/2026-05-11-message-right-click-menu-discoverable-when-no-selection.md`.
### Special notes for your reviewer
- The reviewer correctly flagged a regression class where the f2d8db5f7
fix landed mid-PR (drag handler/style getting clobbered when `{...rest}`
was spread after them). The new primitive-level test guards that pattern
at the boundary (asChild forwarding of `onClick` / `onPointerDown` +
`onSelect` semantics).
- macOS transparent-window `z-50` behavior on the tab right-click menu —
I tested locally via the dev build; Radix portals to body and the menu
rides above the title-bar drag region. Worth a focused manual
verification on review.
- Knowledge-base files (`KnowledgePage.tsx`, `KnowledgeUrls.tsx`,
`SkillsSettings.tsx`) were reset to `origin/v2` baseline per @kangfenmao
— see commit `68cbb648d`.
### Checklist
- [x] PR: The PR description is expressive enough and will help future
contributors
- [x] Code: [Write code that humans can
understand](https://en.wikiquote.org/wiki/Martin_Fowler#code-for-humans)
and [Keep it simple](https://en.wikipedia.org/wiki/KISS_principle)
- [x] Refactor: You have [left the code cleaner than you found it (Boy
Scout
Rule)](https://learning.oreilly.com/library/view/97-things-every/9780596809515/ch08.html)
- [x] Upgrade: Impact of this change on upgrade flows was considered and
addressed if required
- [x] Documentation: A [user-guide update](https://docs.cherry-ai.com)
was considered and is present (link) or not required. Check this only
when the PR introduces or changes a user-facing feature or behavior.
- [x] Self-review: I have reviewed my own code before requesting review
from others
### Release note
```release-note
NONE
```
---------
Signed-off-by: suyao <sy20010504@gmail.com>
Co-authored-by: MyPrototypeWhat <daoquqiexing@gmail.com>
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
### What this PR does
Before this PR:
- Provider/model icons were scattered image imports (PNG/WebP) with no
unified API
- Avatar primitive was based on HeroUI with hardcoded `shadow-lg` and
`border-[0.5px]`
- Full-bleed and padded avatar variants used different rendering
approaches
- Multiple files duplicated IIFE patterns for rendering CompoundIcon vs
string logos
- No type-safe icon catalogs
After this PR:
- **Compound Icon API**: Each icon exposes `.Color`, `.Mono`, and
`.Avatar` sub-components via a unified `CompoundIcon` interface
- **Auto-generated catalogs**: `PROVIDER_ICON_CATALOG` and
`MODEL_ICON_CATALOG` with `resolveProviderIcon` / `resolveModelIcon`
helpers
- **SVG pipeline**: Codegen processes SVGs → generates Color/Mono/Avatar
components
- **Avatar migrated to shadcn/radix**: Replaced HeroUI Avatar with
`Avatar` + `AvatarFallback` pattern, removed hardcoded shadow/border
- **EmojiAvatar moved**: From `primitives/Avatar/` to
`composites/EmojiAvatar/`
- **LogoAvatar component**: Reusable component replacing repeated IIFE
patterns across 5+ files
- **getMCPProviderLogo helper**: Centralized MCP provider icon mapping
- 80+ monochrome icon components, stroke attribute support, deprecated
logos cleanup
<img width="714" height="820" alt="image"
src="https://github.com/user-attachments/assets/a3f14348-5781-494a-8c3b-1f40391e2ec0"
/>
<img width="1008" height="593" alt="image"
src="https://github.com/user-attachments/assets/8ba7fa42-fa33-4e49-ba76-647ba1438e0c"
/>
### Why we need it and why it was done in this way
The v2 refactoring requires moving away from HeroUI toward shadcn/radix
primitives, and needs a scalable, type-safe icon system to replace
scattered image imports. The compound icon pattern (`Icon.Color`,
`Icon.Mono`, `Icon.Avatar`) provides a consistent API while enabling
tree-shaking. The Avatar primitive now uses radix-based `Avatar` +
`AvatarFallback`, aligning with the project's shadcn migration.
The following tradeoffs were made:
- Each icon is a separate TSX file for tree-shaking and lazy loading
support
- Avatar components use `AvatarFallback` to render icons — no image
loading overhead
The following alternatives were considered:
- Runtime SVG color manipulation — rejected for better performance and
consistency
- Keeping HeroUI Avatar — rejected as it conflicts with v2 shadcn
migration goals
### Breaking changes
- Avatar primitive API changed: `HeroUI Avatar` → shadcn `Avatar` +
`AvatarFallback` + `AvatarImage`
- `EmojiAvatar` moved from `primitives/Avatar` to
`composites/EmojiAvatar`
- `shadow-lg` and `border-[0.5px]` removed from generated avatars — now
opt-in via `className`
### Special notes for your reviewer
- ~214 files changed, but the bulk are auto-generated avatar/icon
components under `packages/ui/src/components/icons/`
- Key files to review:
- `packages/ui/src/components/primitives/avatar.tsx` — new shadcn Avatar
primitive
- `packages/ui/scripts/codegen.ts` — avatar generation using
AvatarFallback
- `src/renderer/src/components/Icons/LogoAvatar.tsx` — reusable logo
renderer
- Renderer files using the new Avatar API (Sidebar, UserPopup,
ModelAvatar, etc.)
### Checklist
- [x] PR: The PR description is expressive enough and will help future
contributors
- [x] Code: Write code that humans can understand and Keep it simple
- [x] Refactor: You have left the code cleaner than you found it (Boy
Scout Rule)
- [ ] Upgrade: Impact of this change on upgrade flows was considered and
addressed if required
- [ ] Documentation: N/A - internal component changes
### Release note
```release-note
NONE
```
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Signed-off-by: suyao <sy20010504@gmail.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: icarus <eurfelux@gmail.com>
* feat: support accordion
* feat: support circle progress
* feat: support field
* fix: cn usage
---------
Co-authored-by: MyPrototypeWhat <daoquqiexing@gmail.com>
- Added `@storybook/react` version 10.1.11 to the UI package's dependencies.
- Updated `pnpm-lock.yaml` to include the new `@storybook/react` package and ensure consistency across environments.
This commit enhances the UI component library by integrating Storybook for improved development and documentation.
- Removed outdated dependencies `js-yaml`, `bonjour-service`, and `emoji-picker-element-data` from `devDependencies`.
- Added `@radix-ui/primitive` and `@radix-ui/react-use-callback-ref` to `dependencies` in the UI package.
- Updated `pnpm-lock.yaml` to reflect changes in package versions and ensure consistency across environments.
- Cleaned up unnecessary resolutions in the UI package's `package.json`.
This commit enhances dependency management and ensures the project is aligned with the latest package versions.
- Introduced a new Tabs component along with TabsList, TabsTrigger, and TabsContent for improved content organization.
- Updated package.json and yarn.lock to include @radix-ui/react-tabs dependency.
- Enhanced index.ts to export the new Tabs components for easier access in the UI library.
- Created stories for the Tabs component in Storybook to demonstrate various usage scenarios.
- Updated the @radix-ui/react-slot dependency in package.json and yarn.lock to version 1.2.4.
- Introduced a new Pagination component with associated subcomponents (PaginationContent, PaginationItem, PaginationLink, PaginationNext, PaginationPrevious, PaginationEllipsis).
- Added stories for the Pagination component to demonstrate various use cases and configurations.
- Introduced a new Kbd component to display keyboard shortcuts, supporting both single keys and key combinations.
- Added KbdGroup for grouping multiple Kbd components together.
- Updated package.json to include @radix-ui/react-tooltip version 1.2.8.
- Created stories for Kbd component showcasing various use cases, including integration with Tooltip for enhanced user guidance.
- Added '@cherrystudio/ui/icons' to the Electron Vite configuration for improved icon management.
- Updated TypeScript configuration to include type definitions for the new icon package.
- Removed unused dependencies from yarn.lock to streamline package management.
- Removed the ICON_IMPLEMENTATION_GUIDE.md file and several unused SVG icons from the `icons/` directory.
- Added new SVG icons to enhance the icon library, including various brand logos.
- Updated package.json to reflect the new version of the `tsx` dependency.
- Introduced a script for generating icons and improved the structure of the icons module for better organization and accessibility.
- Updated the stories for icons to showcase the new additions and ensure proper documentation.
- Introduced a new checkbox component utilizing Radix UI, allowing for customizable sizes and states.
- Implemented styles using class-variance-authority for consistent design across different sizes (sm, md, lg).
- Added comprehensive Storybook stories demonstrating various use cases, including default, checked, disabled, and controlled states.
- Updated package.json and yarn.lock to include the new Radix UI checkbox dependency.
- Added a new Select component based on Radix UI, including SelectTrigger, SelectContent, SelectItem, and SelectValue.
- Implemented support for groups and separators within the Select component.
- Updated package.json to include @radix-ui/react-select as a dependency.
- Removed deprecated Selector and SearchableSelector components to streamline the codebase.
- Added stories for the Select component to showcase various use cases and configurations.
- Added new CSS files for design tokens including colors, spacing, typography, and border radius.
- Updated theme.css to import the new tokens and ensure proper usage in the UI.
- Enhanced the theme structure to support light and dark modes with semantic color mappings.
- Introduced a build script to generate theme from tokens for easier management.
- Changed the main CSS file reference from `globals.css` to `theme.css` in `components.json` for better theme management.
- Introduced `index.css` to export only CSS variables, allowing npm users to utilize design tokens without overriding Tailwind defaults.
- Removed `globals.css` as it is no longer needed with the new structure.
- Updated `package.json` to reflect changes in CSS file paths.
- Enhanced `README.md` to clarify installation and configuration steps for the new styling approach.
- Added new design token files including design-tokens.css and theme.css to standardize styling across the UI.
- Introduced a conversion log (CONVERSION_LOG.md) detailing the migration from todocss.css to design-tokens.css, including variable updates and deprecations.
- Updated package.json to include new CSS files for easier imports.
- Enhanced README.md to provide clear guidelines on the design reference and usage of design tokens.
- Improved globals.css to integrate with the new design token structure and ensure consistency in styling.
- Introduced a new RadioGroup component using Radix UI for better UI consistency.
- Updated MCPProviderSettings to utilize the new RadioGroup and adjusted button styles for improved UX.
- Added Radix UI radio group dependency to package.json and yarn.lock.
- Added a new typecheck command for the UI package in package.json to ensure type safety.
- Updated tsconfig.web.json to include UI paths for better module resolution.
- Modified the type-check command in the UI package to specify the tsconfig.json file.
- Adjusted the include paths in the UI tsconfig.json to focus on specific component directories.
- Added new UI components including Button, Command, Dialog, Popover, and Dropzone using Radix UI.
- Introduced global styles with Tailwind CSS for consistent theming and design.
- Updated existing components to utilize new utility functions for class name management.
- Enhanced Tooltip component with inline-block display for better layout.
- Updated package dependencies in package.json and yarn.lock to include new Radix and Tailwind packages.
* refactor: migrate tooltip components to @cherrystudio/ui
- Replace all antd Tooltip + InfoCircleOutlined patterns with InfoTooltip component
- Replace all antd Tooltip + QuestionCircleOutlined patterns with HelpTooltip component
- Migrate all WarnTooltip imports to @cherrystudio/ui
- Add onClick support to InfoTooltip and HelpTooltip components
- Remove local tooltip components from renderer
- Update eslint config to restrict antd Tooltip imports
- Clean up unused imports and styled components
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
* fix: replace tooltip
* fix: yarn format
* fix: type check
* Update QuickModelPopup.tsx
* fix: yarn test
* fix: ci error
* Update TabContainer.tsx
* fix: ci error
* fix: ci error
* fix: issue
* fix: ci
* fix: again
* refactor(ui): replace Tooltip title prop with content for consistency
* refactor(Tooltip): improve Tooltip component by extending props and simplifying implementation
- Extend TooltipProps from HeroUITooltipProps instead of redefining
- Remove redundant props and use spread operator for classNames
- Export TooltipProps type for better type support
* refactor(HelpTooltip): rename title prop to content and simplify component
Update HelpTooltip component to use TooltipProps interface and rename title prop to content for consistency
Update all instances where HelpTooltip is used to reflect the prop name change
* refactor(IconTooltips): consolidate tooltip components into unified module
Move HelpTooltip, InfoTooltip, and WarnTooltip into a single IconTooltips directory with shared types
Update exports in components index to use new module structure
* refactor(tooltip): update InfoTooltip prop from title to content and simplify component
Consolidate tooltip props interface and update all instances to use content prop instead of title for consistency. Remove redundant interface definitions and simplify InfoTooltip component implementation.
* refactor(ui): rename WarnTooltip prop from title to content for consistency
Update all instances of WarnTooltip component to use content prop instead of title for better consistency with Tooltip component interface. Also simplify the component props by extending IconTooltipProps type.
* fix(tooltip): update tooltip usage
- Replace deprecated props like `mouseEnterDelay` and `mouseLeaveDelay` with `delay` and `closeDelay`
- Rename `arrow` prop to `showArrow` for better semantics
- Update styling props to use `classNames` instead of inline styles
- Remove unnecessary props like `fresh` and `destroyOnHidden`
* refactor(components): remove redundant placement="top" from Tooltip components
The placement="top" prop was removed from all Tooltip components since it's the default value and redundant. This change improves code cleanliness without affecting functionality.
* fix(HeaderNavbar): add tooltip placement for sidebar toggle buttons
* fix(ui): add delay to tooltip components for better user experience
* refactor(tooltip): adjust tooltip behavior and styling across components
- Remove default delay values from base Tooltip component
- Add delay and closeDelay props to specific tooltip instances
- Fix tooltip compatibility issue with Antd Dropdown
- Adjust tooltip placement and styling in various components
* fix(ui): set closeDelay to 0 for Tooltip components to improve responsiveness
Prevent tooltip delay from causing poor user experience by making them close immediately when mouse leaves the element
* refactor(ui): remove redundant tooltip placement prop
The 'placement="top"' prop was removed from Tooltip components as it's the default value and doesn't need to be explicitly set.
* fix(ui): adjust tooltip delays for better user experience
- Set consistent default delay of 1000ms for window controls
- Increase delay for sidebar toggle tooltips to 2000ms
- Adjust various message action tooltip delays between 600-1200ms
* fix(SelectModelPopup): add delay props to provider settings tooltip
Add delay and closeDelay props to Tooltip component to improve user experience by preventing accidental triggers
* style(HelpTooltip): add cursor help style to improve UX
* fix(components): add tooltip delay and placement props for better UX
Add delay prop to CustomTag and ModelIdWithTags tooltips to prevent flickering
Set placement prop for LocalBackupManager tooltip to top-start
Add closeDelay prop to HelpTooltip in SaveToKnowledgePopup for immediate closing
* refactor(ModelSelectButton): simplify tooltip props by using TooltipProps type
Replace individual tooltip placement props with TooltipProps type from ui library for better maintainability
* fix(ui): remove tooltip close delay for better user experience
* docs(tooltip): add jsdoc comments explaining tooltip wrapper behavior
* refactor(Tooltip): clarify showArrow prop
* fix(Inputbar): set closeDelay to 0 for pause tooltip to improve UX
Prevent tooltip from staying visible after interaction by removing the close delay
* style(InputbarTools): improve tooltip consistency and css formatting
- Add closeDelay to new topic tooltip for consistency
- Remove redundant line breaks in tooltip props
- Format css transition properties for better readability
* chore: add tailwindCSS class attributes to vscode settings
* fix(tooltips): improve tooltip behavior and styling across components
- Add closeDelay=0 to most tooltips for instant closing
- Add custom styling to CitationTooltip and ChatFlowHistory tooltips
- Adjust delay times for navigation tooltips
- Remove conflicting Tooltip wrappers around Popconfirm actions
* refactor(ui): adjust tooltip delays and placements across components
- Remove redundant isOpen prop from CustomNode tooltip
- Standardize tooltip delays and placements in MessageGroupMenuBar, MessageTokens, ChatNavbar
- Simplify tooltip wrapper structure in HeaderNavbar
- Add consistent tooltip delays in MessageGroupModelList
- Set tooltip placements in MinimalToolbar
* refactor(Tooltip): enhance tooltip structure and props
- Add className prop to Tooltip component for better customization
- Wrap children in a div with relative positioning to improve layout
* refactor(Tooltip): enhance props structure for improved customization
- Update Tooltip component to allow optional classNames with a placeholder property
- Modify child wrapper to utilize classNames for better styling control
* refactor(IconTooltips): consolidate icon props into single iconProps object
Replace individual icon styling props (iconColor, iconSize, iconStyle) with a unified iconProps object using LucideProps type. This simplifies the component API and improves maintainability by using a standardized props structure across all icon tooltip components.
* feat(JoplinSettings): add help button to open Joplin documentation
Add a help button in Joplin settings that opens the official Joplin documentation in a minapp popup when clicked. This provides users with quick access to Joplin's help resources.
* feat(NotionSettings): add help link click handler for notion title
Add click handler to open help documentation when clicking on Notion title in settings
* feat(S3Settings): add help link to S3 settings title
Add click handler to open documentation for S3 settings when title is clicked
* feat(settings): add help button for siyuan integration
Add click handler to open help documentation for siyuan integration settings
* feat(yuque-settings): add help button to open yuque token guide
Add a help button in Yuque settings that opens a minapp popup with Yuque's token guide. This helps users easily access documentation for generating API tokens.
* fix(ui): adjust tooltip delay settings for better user experience
Set closeDelay to 0 for reset button tooltip to prevent lingering
Add delay of 500ms for api key list tooltip to avoid accidental triggers
* fix(ModelList): set closeDelay to 0 for all Tooltip components
Prevent tooltips from staying open longer than necessary by immediately closing them on mouse leave
* fix(ui): improve tooltip placement and delay settings
adjust tooltip placement and delay for better user experience
* refactor(tests): update tooltip mock implementation and snapshots
- Consolidate tooltip mock to handle both title and content props
- Remove deprecated placement attributes from snapshots
- Clean up test tooltip content assertions
* refactor: remove unnecessary whitespace and simplify tooltip components
clean up code by removing redundant whitespace and simplifying tooltip component usage across multiple files
---------
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: icarus <eurfelux@gmail.com>
Co-authored-by: MyPrototypeWhat <daoquqiexing@gmail.com>
- Added @storybook/addon-themes to package.json and yarn.lock for theme support in Storybook.
- Updated CustomCollapse component to utilize HeroUI's Accordion and AccordionItem for improved functionality and styling.
- Removed the ReasoningIcon component as it was deemed unnecessary.
- Enhanced ProviderAvatar component to ensure consistent className handling.
- Added new stories for FileIcons, SvgSpinners180Ring, and ToolsCallingIcon to showcase their usage and variations.
- Reformatted keywords and files array in package.json for better readability.
- Updated migration status to reflect the migration of additional components, increasing the total migrated count to 46 and reducing pending migrations to 190.
- Added new components to the migration status table, including ErrorBoundary and ProviderAvatar, while removing deprecated components like ErrorTag, SuccessTag, and WarnTag.
* refactor(CodeEditor): decouple CodeEditor and global settings
* refactor: improve language extension fallbacks
* refactor: make a copy of CodeEditor in the ui package
* refactor: update ui CodeEditor and language list
* refactor: use CodeEditor from the ui package
* feat: add a story for CodeEditor
- Added Storybook scripts for development and building the UI components.
- Updated package.json to include new dependencies for Storybook and styled-components.
- Revised README to reflect changes in Tailwind CSS configuration, transitioning to v4 and removing the tailwind.config.js file.
- Enhanced the tsdown configuration to mark additional peer dependencies as external.
- Removed outdated Tailwind CSS configuration file to streamline the setup.
- Introduced a new UI component library for Cherry Studio, including various components such as buttons, inputs, and layout elements.
- Updated configuration files to include the new library and its dependencies.
- Enhanced the project structure to support modular imports and TypeScript definitions for better development experience.
