@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:

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:

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:

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:

bunx shadcn@latest add button -c apps/web

After generation:

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