From 010638503fe4cb3d966585c89f92c32bc5eec963 Mon Sep 17 00:00:00 2001
From: kurihada <kurihada@qq.com>
Date: Fri, 20 Mar 2026 11:40:53 +0800
Subject: [PATCH] Add a combined stylesheet entry for package consumers

---
 README.md                             | 18 ++++++++++++++++++
 apps/docs/src/preview.css             |  3 +--
 docs/registry.md                      |  5 +++++
 docs/releasing.md                     | 10 ++++++++++
 docs/rfcs/multi-style-architecture.md |  9 ++++++---
 packages/ui/package.json              |  1 +
 packages/ui/src/styles.css            |  2 ++
 7 files changed, 43 insertions(+), 5 deletions(-)
 create mode 100644 packages/ui/src/styles.css

diff --git a/README.md b/README.md
index 46b6a8f..479da94 100644
--- a/README.md
+++ b/README.md
@@ -72,6 +72,24 @@ pnpm lint
 pnpm typecheck
 ```
 
+## Package consumption
+
+For package-style consumers, prefer a single CSS entrypoint from `@ai-ui/ui`:
+
+```tsx
+import { Button } from "@ai-ui/ui";
+```
+
+```css
+@import "tailwindcss";
+@import "@ai-ui/ui/styles.css";
+@source "../node_modules/@ai-ui/ui/src";
+```
+
+This keeps the app on one UI package import path while still pulling in token and skin
+styles together. Consumers that want lower-level control can still import
+`@ai-ui/tokens/styles.css` and `@ai-ui/ui/skins.css` separately.
+
 Install source-owned components into another project:
 
 ```bash
diff --git a/apps/docs/src/preview.css b/apps/docs/src/preview.css
index de6f96a..4b5747d 100644
--- a/apps/docs/src/preview.css
+++ b/apps/docs/src/preview.css
@@ -1,6 +1,5 @@
 @import "tailwindcss";
-@import "@ai-ui/tokens/styles.css";
-@import "@ai-ui/ui/skins.css";
+@import "@ai-ui/ui/styles.css";
 @source "../../../packages/ui/src";
 
 :root {
diff --git a/docs/registry.md b/docs/registry.md
index e253efc..00c93dc 100644
--- a/docs/registry.md
+++ b/docs/registry.md
@@ -107,6 +107,11 @@ At minimum, the consumer app should import:
 
 - `src/cadence-ui/tokens/styles.css` from its global app stylesheet or entry module
 
+For package consumers instead of source-copy installs, the equivalent convenience import
+is:
+
+- `@ai-ui/ui/styles.css`
+
 If the consumer wants the theme helpers, they can also import from:
 
 - `src/cadence-ui/tokens/index.ts`
diff --git a/docs/releasing.md b/docs/releasing.md
index d85f325..63f32d8 100644
--- a/docs/releasing.md
+++ b/docs/releasing.md
@@ -27,6 +27,16 @@ Changesets should currently be used for:
 - `@ai-ui/ui`
 - `@ai-ui/tokens`
 
+Package consumers should now prefer:
+
+- `@ai-ui/ui` for component imports
+- `@ai-ui/ui/styles.css` for the combined token + skin stylesheet
+
+The lower-level entries remain available when needed:
+
+- `@ai-ui/tokens/styles.css`
+- `@ai-ui/ui/skins.css`
+
 Changes to the docs app alone usually do not need a changeset.
 
 ## When to create a changeset
diff --git a/docs/rfcs/multi-style-architecture.md b/docs/rfcs/multi-style-architecture.md
index 338a52f..806516c 100644
--- a/docs/rfcs/multi-style-architecture.md
+++ b/docs/rfcs/multi-style-architecture.md
@@ -546,7 +546,7 @@ Deliverables:
 
 Status:
 
-- not started
+- completed
 
 ## Acceptance Criteria For The First Real Milestone
 
@@ -609,6 +609,9 @@ As of 2026-03-20, the project is at this point:
 - scoped `data-motion="reduced"` now works for nested docs wrappers
 - shared skin-aware treatment now extends across the broader component library surface,
   including controls, menus, overlays, feedback, and data-heavy patterns
+- package consumers can now import a single combined stylesheet from
+  `@ai-ui/ui/styles.css`
 
-The next implementation task should be Phase 5: improve packaging and consumer
-ergonomics for style consumption.
+The original Phase 0-5 implementation sequence is now complete. Further work should be
+treated as iteration: refining skins, expanding motion packs, or hardening package and
+registry distribution.
diff --git a/packages/ui/package.json b/packages/ui/package.json
index 871c308..60a290e 100644
--- a/packages/ui/package.json
+++ b/packages/ui/package.json
@@ -8,6 +8,7 @@
   ],
   "exports": {
     ".": "./src/index.ts",
+    "./styles.css": "./src/styles.css",
     "./skins.css": "./src/skins.css"
   },
   "files": [
diff --git a/packages/ui/src/styles.css b/packages/ui/src/styles.css
new file mode 100644
index 0000000..619247a
--- /dev/null
+++ b/packages/ui/src/styles.css
@@ -0,0 +1,2 @@
+@import "@ai-ui/tokens/styles.css";
+@import "./skins.css";