@lark-apaas/client-toolkit-lite 1.1.7-alpha.9 → 1.1.7

package/README.md

@@ -19,13 +19,14 @@ npm install react react-dom react-router-dom @tanstack/react-query
 ### 1. 使用 AppContainer
 
 `AppContainer` 是应用根容器，内部集成：
-- **全局样式** — 自动导入主题样式（theme-layer / tailwind-theme / override / font-family），无需手动 import CSS
 - **Safety** — 生产环境「妙搭构建」安全标识
 - **QueryProvider** — React Query 数据管理
 - **useAppInfo** — 自动同步 document title / favicon / OG meta
 - **Tea 埋点** — 生产环境自动上报页面访问事件
 - **Runtime** — React DevTools Hook + Axios CSRF 全局注入（防重复）
 
+> 主题样式**不自动注入**，需在应用入口手动 import，详见下一节。
+
 ```tsx
 // App.tsx
 import { AppContainer } from '@lark-apaas/client-toolkit-lite';
@@ -53,6 +54,53 @@ import { QueryProvider } from '@lark-apaas/client-toolkit-lite';
 <QueryProvider>{children}</QueryProvider>
 ```
 
+### 2. 导入样式
+
+主题样式包含 4 个片段：`theme-layer`（layer 顺序声明）/ `tailwind-theme`（色板变量 + `.dark` 模式）/ `override`（base 兜底）/ `font-family`（Lark 字体）。聚合入口需手动 import：
+
+```ts
+// main.ts / main.tsx
+import '@lark-apaas/client-toolkit-lite/styles.css';
+```
+
+#### Tailwind v4 source 扫描
+
+lite 的 `Drawer` / `Popover` / `ErrorRender` 等组件使用了 Tailwind class，由于 v4 默认不扫描 `node_modules`，需要在你自己的主 css 里显式声明 source（否则这些组件会没有视觉）：
+
+```css
+/* 你的 main.css */
+@import 'tailwindcss';
+@import '@lark-apaas/client-toolkit-lite/styles.css';
+
+/* 路径相对于这个 css 文件所在位置 */
+@source "../node_modules/@lark-apaas/client-toolkit-lite/dist";
+```
+
+#### shadcn 语义变量（按需补）
+
+`override.css` 和 `Drawer` / `Popover` 用了 `--background` / `--foreground` / `--border` / `--ring` / `--popover` / `--popover-foreground` / `--muted-foreground` 等 shadcn 风格语义变量。lite 内置色板（`tailwind-theme.css`）**只提供 `--color-*` 全色板**，不包含这些语义变量 —— 需要你在自己的 css 里按业务主题补上：
+
+```css
+:root {
+  --background: var(--color-neutral-00);
+  --foreground: var(--color-neutral-950);
+  --border: var(--color-neutral-300);
+  --ring: var(--color-blue-500);
+  --popover: var(--color-neutral-00);
+  --popover-foreground: var(--color-neutral-950);
+  --muted-foreground: var(--color-neutral-700);
+}
+```
+
+#### 按需导入子片段
+
+只要色板或字体时可单独 import：
+
+```ts
+import '@lark-apaas/client-toolkit-lite/styles/tailwind-theme.css';
+import '@lark-apaas/client-toolkit-lite/styles/font-family.css';
+```
+
 ### 3. Hooks
 
 #### useAppInfo