---
title: Workspace adaptations
description: Record the implementation differences that must survive updates from the shadcn/ui Base UI source.
order: 22
toc:
  - id: baseline
    title: Upstream baseline
  - id: icons-and-ripple
    title: Icons and ripple
  - id: localization
    title: Localization
  - id: popover
    title: Popover extensions
  - id: select
    title: Select correction
  - id: upgrade-checklist
    title: Upgrade checklist
---

## Upstream baseline {#baseline}

The local components began from shadcn/ui's Base UI registry with the `base-vega` style. Use the upstream [component documentation](https://ui.shadcn.com/docs/components/base) and [GitHub source directory](https://github.com/shadcn-ui/ui/tree/main/apps/v4/registry/bases/base/ui) as references, but do not assume the latest upstream version is identical to the workspace snapshot.

When determining behavior, prefer the local source, then this documentation, then local `components.json`, and only then the latest upstream example.

## Icons and ripple {#icons-and-ripple}

`components/icon.tsx` maps Lucide icon names to `@icones/react` components and preserves a set of upstream-compatible export names. Existing components import through that entry point. Convert any `lucide-react` import introduced by the CLI back to the local module.

`Button` merges its incoming ref with `useRippleRef`. Preserve relative positioning, ref merging, and disabled behavior when updating Button.

## Localization {#localization}

Breadcrumb, Calendar, Carousel, Dialog, Pagination, Sheet, Sidebar, Spinner, Toast, and related components replace some hard-coded English with descriptors from `components/i18n.tsx`. When updating these files, inspect accessible labels, screen-reader-only text, and default descriptions in addition to visible UI.

Only `en-US` and `zh-Hans` catalogs are published. Adding a message requires synchronized changes to:

1. The `uiMessages` descriptor.
2. The `uiMessageIds` type list.
3. `messages` in both locale modules.
4. The component that consumes the message.

## Popover extensions {#popover}

The local `PopoverContent` adds these capabilities beyond the upstream wrapper:

- Forwarded `anchor` and `positionMethod` options.
- `showArrow`, accepting an `AnchoredSurface` configuration object.
- `viewportClassName`, separating scrollable content from the overflow-visible outer surface.
- An anchor-sized default side offset and continuous curved tail.
- `createPopoverHandle` and `PopoverHandle` exports.

Do not replace the file wholesale with upstream source. In particular, test long-content scrolling, every side, collision flips, narrow triggers, and RTL.

## Select correction {#select}

`SelectTrigger` renders `ChevronDownIcon` as a child of `SelectPrimitive.Icon` instead of passing the icon component through `render`. This correction is intentional for the current Base UI and Icones combination. After a Select update, verify that the trigger shows exactly one icon and test SSR and hydration.

## Upgrade checklist {#upgrade-checklist}

1. Review the shadcn docs and matching registry source diff before replacing anything.
2. Generate through the CLI on a temporary branch or stage files individually, preserving local public exports.
3. Convert direct icon dependencies back to `components/icon`.
4. Restore translated messages, logical-direction utilities, and local theme classes.
5. Give Button, Popover, Select, Calendar, Toast, and Sidebar focused regression coverage.
6. Run the UI typecheck, repository lint and format checks, then build a real consuming application.
7. Manually inspect light, dark, LTR, RTL, mobile, tablet, and desktop behavior.