npm - @admin-core/design - Versions diffs - 0.1.0 → 0.2.0 - Mend

@admin-core/design 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (21) hide show

package/README.md +212 -302
package/dist/index.cjs +5 -1
package/dist/index.cjs.map +1 -1
package/dist/index.d.ts +1 -0
package/dist/index.d.ts.map +1 -1
package/dist/index.js +2351 -1
package/dist/index.js.map +1 -1
package/dist/index.umd.js +5 -1
package/dist/index.umd.js.map +1 -1
package/dist/style.css +1 -1
package/dist/theme/composables.d.ts +89 -0
package/dist/theme/composables.d.ts.map +1 -0
package/dist/theme/constants.d.ts +51 -0
package/dist/theme/constants.d.ts.map +1 -0
package/dist/theme/index.d.ts +50 -0
package/dist/theme/index.d.ts.map +1 -0
package/dist/theme/types.d.ts +135 -0
package/dist/theme/types.d.ts.map +1 -0
package/dist/theme/utils.d.ts +230 -0
package/dist/theme/utils.d.ts.map +1 -0
package/package.json +23 -2

package/README.md CHANGED Viewed

@@ -1,48 +1,46 @@
-# @admin-core/design
+# @admin-kit/design
-设计系统（样式、令牌）
+基于 Tailwind CSS v4 的设计系统，提供完整的样式、令牌和主题管理解决方案。
-## 安装
+## 功能特性
-```bash
-# npm
-npm install @admin-core/design
+- ✅ **Tailwind CSS v4** - 使用最新的 Tailwind CSS v4 特性
+- ✅ **主题系统** - 支持浅色/暗色模式，提供 13+ 预设主题
+- ✅ **设计令牌** - 基于 CSS 变量的设计令牌系统
+- ✅ **BEM 工具** - SCSS BEM 命名规范 Mixin 工具集
+- ✅ **动画库** - 丰富的 Vue 过渡动画和 CSS 动画
+- ✅ **TypeScript** - 完整的 TypeScript 类型支持
-# pnpm
-pnpm add @admin-core/design
+## 安装
-# yarn
-yarn add @admin-core/design
+```bash
+pnpm add @admin-kit/design
 ```
 ## 使用方式
-### 1. CSS 样式导入
-#### ESM (推荐)
+### 1. 导入完整样式
 ```typescript
-import '@admin-core/design/css'
-// 使用 CSS 变量
-// 在你的组件中直接使用设计令牌
+// 导入所有样式和令牌
+import '@admin-kit/design'
 ```
-#### CommonJS
+### 2. 按需导入
-```javascript
-require('@admin-core/design/css')
-```
+```typescript
+// 只导入 CSS
+import '@admin-kit/design/css'
-### 2. SCSS BEM 工具
+// 只导入令牌
+import '@admin-kit/design/tokens'
+```
-如果你的项目使用 SCSS，可以导入 BEM 命名规范工具：
+### 3. 使用 SCSS BEM 工具
 ```scss
-// 导入 BEM Mixin 工具
-@use '@admin-core/design/scss-bem' as *;
+@use '@admin-kit/design/scss-bem' as *;
-// 使用 BEM Mixin
 @include b(button) {
   padding: 8px 16px;
@@ -53,343 +51,255 @@ require('@admin-core/design/css')
   @include m(primary) {
     background: blue;
   }
-  @include is(disabled) {
-    opacity: 0.5;
-  }
 }
 ```
-详细的 BEM 工具使用文档，请查看 [SCSS BEM 文档](./src/scss-bem/README.md)
+## Tailwind CSS 配置
-### 3. CDN (UMD)
+如果你的项目需要扩展 Tailwind 配置，可以继承本包的配置：
-#### unpkg
-```html
-<!-- 样式 -->
-<link rel="stylesheet" href="https://unpkg.com/@admin-core/design/dist/style.css">
-<!-- JavaScript -->
-<script src="https://unpkg.com/@admin-core/design/dist/index.umd.js"></script>
-<script>
-  // 全局变量 AdminKitDesign
-  console.log(AdminKitDesign)
-</script>
+```typescript
+// tailwind.config.ts
+import designConfig from '@admin-kit/design/tailwind.config'
+import type { Config } from 'tailwindcss'
+export default {
+  ...designConfig,
+  content: [
+    ...designConfig.content,
+    './src/**/*.{vue,js,ts,jsx,tsx}',
+  ],
+  theme: {
+    ...designConfig.theme,
+    extend: {
+      ...designConfig.theme.extend,
+      // 你的自定义扩展
+    },
+  },
+} satisfies Config
 ```
-#### jsDelivr
+## 主题系统
+### 切换暗色模式
 ```html
-<!-- 样式 -->
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@admin-core/design/dist/style.css">
-<!-- JavaScript -->
-<script src="https://cdn.jsdelivr.net/npm/@admin-core/design/dist/index.umd.js"></script>
-<script>
-  console.log(AdminKitDesign)
-</script>
+<!-- 浅色模式（默认） -->
+<html>
+  <body>...</body>
+</html>
+<!-- 暗色模式 -->
+<html class="dark">
+  <body>...</body>
+</html>
 ```
-## 包含内容
+### 切换主题变体
-### 样式文件
+```html
+<!-- 紫色主题 -->
+<html data-theme="violet">
+  <body>...</body>
+</html>
-- **global.css** - 全局样式、盒模型、滚动条、视图过渡
-- **nprogress.css** - 进度条样式和旋转加载动画
-- **transition.css** - Vue 过渡动画（滑动、淡入淡出、缩放等）
-- **ui.css** - UI 组件样式（侧边内容、面包屑、弹窗层级等）
-- **light.css** - 浅色主题 CSS 变量
-- **dark.css** - 暗色主题 CSS 变量
+<!-- 暗色 + 紫色主题 -->
+<html class="dark" data-theme="violet">
+  <body>...</body>
+</html>
+```
----
+### 可用主题
-# 设计令牌（Design Tokens）
+- `violet` - 紫色主题
+- `pink` - 粉色主题
+- `rose` - 玫瑰色主题
+- `sky-blue` - 天蓝色主题
+- `deep-blue` - 深蓝色主题
+- `green` - 绿色主题
+- `deep-green` - 深绿色主题
+- `orange` - 橙色主题
+- `yellow` - 黄色主题
+- `zinc` - 锌色主题
+- `neutral` - 中性色主题
+- `slate` - 石板色主题
+- `gray` - 灰色主题
-## 概述
+## 设计令牌
-设计令牌是设计系统的基础，定义了应用中所有的颜色、间距、字体等视觉属性。通过 CSS 变量实现，可以轻松切换主题和适配暗色模式。
+所有颜色都使用 HSL 格式的 CSS 变量定义，支持透明度修饰符：
-## 文件说明
+```html
+<!-- 使用 Tailwind 工具类 -->
+<div class="bg-primary text-primary-foreground">主色按钮</div>
+<div class="bg-primary/50">50% 透明度的主色背景</div>
-### light.css - 浅色主题
+<!-- 使用 CSS 变量 -->
+<style>
+.my-component {
+  background-color: hsl(var(--primary));
+  color: hsl(var(--primary-foreground));
+}
+</style>
+```
-**用途：**
-- 定义浅色主题下的所有 CSS 变量
-- 提供 12 种预设主题变体（default、violet、pink、rose、sky-blue、deep-blue、green、deep-green、orange、yellow、zinc、neutral、slate、gray）
-- 作为整个设计系统的颜色基础
+### 可用的颜色令牌
-**核心变量：**
-- `--background` - 页面背景色
-- `--foreground` - 文字颜色
-- `--primary` - 主题色
-- `--secondary` - 次要色
-- `--accent` - 强调色
-- `--destructive` - 危险操作色
-- `--success` - 成功提示色
-- `--warning` - 警告提示色
-- `--border` - 边框色
-- `--input` - 输入框边框色
-- `--card` - 卡片背景色
-- `--popover` - 弹出层背景色
+#### 基础颜色
+- `--background` / `--foreground` - 背景和前景色
+- `--card` / `--card-foreground` - 卡片颜色
+- `--popover` / `--popover-foreground` - 弹出层颜色
-**使用示例：**
-```html
-<!-- 默认主题 -->
-<html>
-  <body>默认浅色主题</body>
-</html>
+#### 语义颜色
+- `--primary` / `--primary-foreground` - 主色
+- `--secondary` / `--secondary-foreground` - 次要色
+- `--muted` / `--muted-foreground` - 柔和色
+- `--accent` / `--accent-foreground` - 强调色
+- `--destructive` / `--destructive-foreground` - 破坏性操作色
-<!-- 紫色主题 -->
-<html data-theme="violet">
-  <body>紫色浅色主题</body>
-</html>
-```
+#### 状态颜色
+- `--info` / `--info-foreground` - 信息提示色
+- `--success` / `--success-foreground` - 成功提示色
+- `--warning` / `--warning-foreground` - 警告提示色
-### dark.css - 暗色主题
+#### 边框和输入
+- `--border` - 边框颜色
+- `--input` - 输入框边框颜色
+- `--ring` - 焦点环颜色
-**用途：**
-- 定义暗色模式下的所有 CSS 变量
-- 提供护眼的深色配色方案
-- 支持与浅色主题相同的 12 种主题变体
-- 通过 `.dark` 类名自动应用
+#### 其他
+- `--radius` - 圆角大小
+- `--font-family` - 字体家族
+- `--popup-z-index` - 弹出层层级
-**特点：**
-- 背景色使用深色调（低亮度值）
-- 前景色使用浅色调（高亮度值）
-- 优化的对比度，确保文字可读性
-- 减少夜间使用时的眼睛疲劳
+## 动画
-**使用示例：**
-```html
-<!-- 暗色模式 -->
-<html class="dark">
-  <body>默认暗色主题</body>
-</html>
+### Vue 过渡动画
-<!-- 暗色模式 + 紫色主题 -->
-<html class="dark" data-theme="violet">
-  <body>紫色暗色主题</body>
-</html>
+```vue
+<template>
+  <Transition name="fade">
+    <div v-if="show">内容</div>
+  </Transition>
+</template>
 ```
-## 主题系统
+可用的过渡动画：
+- `fade` - 淡入淡出
+- `slide-up` - 向上滑动
+- `slide-down` - 向下滑动
+- `slide-left` - 向左滑动
+- `slide-right` - 向右滑动
+- `fade-slide` - 淡入淡出 + 滑动
+- `fade-scale` - 淡入淡出 + 缩放
-### 预设主题列表
-| 主题名称 | data-theme 值 | 描述 |
-|---------|--------------|------|
-| 默认 | 不设置 | 蓝色系主题 |
-| 紫罗兰 | `violet` | 紫色系主题 |
-| 粉色 | `pink` | 粉色系主题 |
-| 玫瑰 | `rose` | 玫瑰色系主题 |
-| 天蓝 | `sky-blue` | 天蓝色系主题 |
-| 深蓝 | `deep-blue` | 深蓝色系主题 |
-| 绿色 | `green` | 绿色系主题 |
-| 深绿 | `deep-green` | 深绿色系主题 |
-| 橙色 | `orange` | 橙色系主题 |
-| 黄色 | `yellow` | 黄色系主题 |
-| 锌灰 | `zinc` | 锌灰色系主题 |
-| 中性灰 | `neutral` | 中性灰色系主题 |
-| 石板灰 | `slate` | 石板灰色系主题 |
-| 灰色 | `gray` | 灰色系主题 |
-### 主题切换实现
-**JavaScript 切换：**
-```javascript
-// 切换到暗色模式
-document.documentElement.classList.add('dark')
-// 切换到浅色模式
-document.documentElement.classList.remove('dark')
-// 切换主题颜色
-document.documentElement.setAttribute('data-theme', 'violet')
+### Tailwind 动画类
+```html
+<div class="animate-slide-down">向下滑入</div>
+<div class="animate-fade-in">淡入</div>
+<div class="animate-shrink">收缩动画</div>
 ```
-**Vue 组合式函数：**
-```typescript
-import { ref } from 'vue'
+## BEM 命名规范
-export function useTheme() {
-  const isDark = ref(false)
-  const theme = ref('default')
+使用 SCSS Mixin 快速生成 BEM 类名：
-  const toggleDark = () => {
-    isDark.value = !isDark.value
-    document.documentElement.classList.toggle('dark', isDark.value)
-  }
+```scss
+@use '@admin-kit/design/scss-bem' as *;
-  const setTheme = (newTheme: string) => {
-    theme.value = newTheme
-    document.documentElement.setAttribute('data-theme', newTheme)
+@include b(card) {
+  // 生成 .admin-card
+  padding: 16px;
+  @include e(header) {
+    // 生成 .admin-card__header
+    font-weight: bold;
+  }
+  @include m(primary) {
+    // 生成 .admin-card--primary
+    border-color: blue;
+  }
+  @include is(active) {
+    // 生成 .admin-card.is-active
+    box-shadow: 0 0 10px blue;
   }
-  return { isDark, theme, toggleDark, setTheme }
 }
 ```
-## CSS 变量使用
+详细文档请查看 [BEM 工具文档](./src/scss-bem/README.md)。
-### 在组件中使用
+## 工具类
-```css
-.my-button {
-  /* 使用主题色 */
-  background-color: hsl(var(--primary));
-  color: hsl(var(--primary-foreground));
-  /* 使用边框色 */
-  border: 1px solid hsl(var(--border));
-  /* 使用圆角 */
-  border-radius: var(--radius);
-}
+### 布局工具类
-.my-button:hover {
-  /* 使用强调色 */
-  background-color: hsl(var(--accent));
-}
+```html
+<!-- 水平居中 -->
+<div class="flex-center">内容</div>
-.my-button.destructive {
-  /* 使用危险色 */
-  background-color: hsl(var(--destructive));
-  color: hsl(var(--destructive-foreground));
-}
-```
+<!-- 垂直居中 -->
+<div class="flex-col-center">内容</div>
-### 颜色值格式
+<!-- 卡片容器 -->
+<div class="card-box">卡片内容</div>
-所有颜色变量使用 HSL 格式（色相 饱和度 亮度），需要配合 `hsl()` 函数使用：
+<!-- 轮廓框 -->
+<div class="outline-box">可点击的框</div>
+<div class="outline-box outline-box-active">激活状态</div>
+```
-```css
-/* ✅ 正确 */
-background-color: hsl(var(--primary));
+### 链接样式
-/* ❌ 错误 */
-background-color: var(--primary);
+```html
+<a href="#" class="admin-link">链接文本</a>
 ```
-### 透明度支持
-可以通过 HSL 的第四个参数添加透明度：
+## 特殊模式
-```css
-/* 50% 透明度的主题色 */
-background-color: hsl(var(--primary) / 0.5);
+### 反色模式
-/* 20% 透明度的边框色 */
-border-color: hsl(var(--border) / 0.2);
+```html
+<html class="invert-mode">
+  <body>所有颜色反转</body>
+</html>
 ```
-## 变量分类
-### 基础颜色
-- `--background` / `--background-deep` - 背景色
-- `--foreground` - 前景色（文字）
-- `--border` - 边框色
-### 组件颜色
-- `--card` - 卡片背景
-- `--popover` - 弹出层背景
-- `--input` - 输入框边框
-- `--muted` - 柔和背景
-### 语义颜色
-- `--primary` - 主题色（品牌色）
-- `--secondary` - 次要色
-- `--accent` - 强调色（悬停效果）
-- `--destructive` - 危险操作（删除、警告）
-- `--success` - 成功提示
-- `--warning` - 警告提示
-- `--info` - 信息提示
-### 布局组件
-- `--sidebar` - 侧边栏背景
-- `--header` - 头部背景
-- `--menu` - 菜单背景
-### 其他
-- `--radius` - 圆角大小
-- `--ring` - 焦点环颜色
-- `--overlay` - 遮罩颜色
-- `--font-size-base` - 基础字体大小
-## 最佳实践
-1. **始终使用语义化变量**
-   ```css
-   /* ✅ 推荐 */
-   color: hsl(var(--foreground));
-   /* ❌ 不推荐 */
-   color: #000000;
-   ```
-2. **为不同状态使用对应的颜色**
-   ```css
-   .button-primary { background: hsl(var(--primary)); }
-   .button-danger { background: hsl(var(--destructive)); }
-   .button-success { background: hsl(var(--success)); }
-   ```
-3. **利用前景色变量确保对比度**
-   ```css
-   .card {
-     background: hsl(var(--card));
-     color: hsl(var(--card-foreground));
-   }
-   ```
-4. **使用 accent 系列实现悬停效果**
-   ```css
-   .menu-item {
-     background: transparent;
-   }
-   .menu-item:hover {
-     background: hsl(var(--accent));
-     color: hsl(var(--accent-foreground));
-   }
-   ```
-## 扩展自定义主题
-如需添加新的主题变体，在对应的 CSS 文件中添加：
-```css
-/* light.css */
-[data-theme='my-theme'] {
-  --primary: 200 100% 50%;
-  --primary-foreground: 0 0% 100%;
-  /* ... 其他变量 */
-}
+### 灰度模式
-/* dark.css */
-.dark[data-theme='my-theme'] {
-  --primary: 200 80% 40%;
-  --primary-foreground: 0 0% 100%;
-  /* ... 其他变量 */
-}
+```html
+<html class="grayscale-mode">
+  <body>所有颜色变为灰度</body>
+</html>
 ```
----
+## 浏览器兼容性
-## 构建输出
+- Chrome >= 90
+- Firefox >= 88
+- Safari >= 14
+- Edge >= 90
-- `dist/index.js` - ESM 格式（已压缩）
-- `dist/index.cjs` - CommonJS 格式（已压缩）
-- `dist/index.umd.js` - UMD 格式，用于 CDN（已压缩）
-- `dist/index.d.ts` - TypeScript 类型定义
-- `dist/style.css` - 合并的样式文件（42.20 kB，gzip: 9.01 kB）
+## 开发
-## 技术栈
+```bash
+# 安装依赖
+pnpm install
+# 开发模式（监听文件变化）
+pnpm dev
-- **构建工具**: Vite 7.x
-- **样式**: Tailwind CSS v4 + 原生 CSS
-- **类型定义**: TypeScript 5.x
+# 构建
+pnpm build
+```
-## License
+## 许可证
 MIT
+## 相关链接
+- [Tailwind CSS v4 文档](https://tailwindcss.com/docs)
+- [BEM 命名规范](http://getbem.com/)
+- [HSL 颜色格式](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/hsl)