# @workspace/ui

`@workspace/ui` is the source-owned UI foundation for Simple React App Kit. It
provides reusable React components, interaction primitives, theme tokens,
icons, localization, and responsive utilities for the applications in this
workspace.

The package began with the shadcn/ui component model and has deliberately
evolved as a local design-system implementation. It is not a wrapper around a
published shadcn/ui runtime package: applications compile and own the source in
this directory.

## Relationship to shadcn/ui

The package keeps the parts of shadcn/ui that make it effective:

- Components are copied into the repository and remain editable.
- Base UI primitives provide accessible behavior for composite components.
- Tailwind CSS v4 and CSS custom properties provide styling and theming.
- `components.json` remains the entry point for generating or updating
  components with the shadcn CLI.
- Components support RTL layouts and expose `data-slot` attributes for
  composition and customization.

This workspace also has intentional differences from upstream shadcn/ui:

- Icons use the local Icones adapter instead of importing Lucide icons
  directly.
- Components can consume a framework-neutral `I18nProvider`; the maintained
  catalogs are `zh-Hans` and `en-US`.
- Buttons include the workspace ripple interaction.
- Responsive hooks synchronize mobile, tablet, and desktop state with root
  document classes.
- Popover and anchored-surface components expose additional positioning,
  arrow, viewport, and imperative-handle capabilities.
- Higher-level message, bubble, attachment, and overlay-oriented components
  are maintained alongside the lower-level primitives.
- Imports use explicit package subpaths. There is intentionally no catch-all
  component barrel.

Because the source is locally owned, an upstream shadcn update is treated as a
reviewed merge, not as a dependency upgrade. Preserve local behavior when
regenerating a component and inspect the diff before accepting it.

## Color semantics

This package intentionally uses different names for two shadcn color roles:

| This package | shadcn/ui equivalent | Meaning                                                                                             |
| ------------ | -------------------- | --------------------------------------------------------------------------------------------------- |
| `accent`     | `primary`            | The product or brand color used for primary actions, selected controls, links, and strong emphasis. |
| `highlight`  | `accent`             | A temporary or local surface used for hover, focus, open, and softly selected states.               |
| `muted`      | `muted`              | A subdued surface or lower-emphasis foreground.                                                     |

Each role has a matching foreground token where needed:
`accent-foreground` and `highlight-foreground`. Sidebar tokens follow the same
model with `sidebar-accent` and `sidebar-highlight`.

This naming makes “accent color” consistently mean the configurable brand
color throughout the workspace. It also avoids using `accent` for shadcn's
neutral interaction background, where `highlight` describes the visual effect
more directly.

When adapting an upstream snippet, translate its semantic utilities:

```text
bg-primary text-primary-foreground
  -> bg-accent text-accent-foreground

hover:bg-accent hover:text-accent-foreground
  -> hover:bg-highlight hover:text-highlight-foreground
```

Do not translate Tailwind's native `accent-*` utilities such as
`accent-indigo-600`; those utilities control the CSS `accent-color` property
and are unrelated to these theme roles.

## Usage

Import components from explicit subpaths:

```tsx
import { Button } from "@workspace/ui/components/button"
import { Icon } from "@workspace/ui/components/icon"
import { cn } from "@workspace/ui/lib/utils"
```

Load the shared stylesheet once near the application root:

```tsx
import "@workspace/ui/globals.css"
```

The dark theme is activated by the escaped root class `ui:dark`, rather than
shadcn's default `.dark` selector. Appearance preferences normally apply this
class and the generated color variables for the application.

## Adding or updating components

Run the shadcn CLI from the workspace root and target the application that owns
the registry configuration:

```bash
bunx shadcn@latest add button -c apps/web
```

After generation:

1. Compare the result with the existing component and its Git history.
2. Restore local Icones, localization, ripple, RTL, and positioning behavior
   where applicable.
3. Convert upstream `primary`/`accent` color roles to this package's
   `accent`/`highlight` vocabulary.
4. Format, lint, type-check, and test the affected workspace packages.