diff --git a/packages/ui/README.md b/packages/ui/README.md
new file mode 100644
index 0000000..6e9835e
--- /dev/null
+++ b/packages/ui/README.md
@@ -0,0 +1,114 @@
+# @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.
\ No newline at end of file