@particle-network/ui-shared

📦 关于

这是 UniversalX Design System 的内部共享包，为 @particle-network/ui-react 和 @particle-network/ui-native 提供：

• 🎨 设计令牌 - 统一的颜色、间距、圆角等设计变量
• 🔧 工具函数 - 共享的实用工具函数
• 🎯 类型定义 - 通用的 TypeScript 类型
• 🌈 主题系统 - 跨平台的主题配置

🚀 使用方法

⚠️ 注意：这是一个内部包，通常不需要直接安装。它会作为 UI 组件库的依赖自动安装。

在组件库中使用

import { colors, spacing, radius } from '@particle-network/ui-shared';
import { Theme, Size, Color } from '@particle-network/ui-shared';

// 使用设计令牌
const buttonStyles = {
  padding: spacing.md,
  borderRadius: radius.md,
  backgroundColor: colors.primary,
};

// 使用类型定义
interface ButtonProps {
  size?: Size;
  color?: Color;
}

📚 导出内容

设计令牌

颜色系统 (color.ts)

export const colors = {
  // 主题色
  primary: '#1890ff',
  secondary: '#52c41a',
  success: '#52c41a',
  warning: '#faad14',
  danger: '#ff4d4f',
  info: '#1890ff',

  // 中性色
  white: '#ffffff',
  black: '#000000',
  gray: {
    50: '#fafafa',
    100: '#f5f5f5',
    200: '#e5e5e5',
    300: '#d4d4d4',
    400: '#a3a3a3',
    500: '#737373',
    600: '#525252',
    700: '#404040',
    800: '#262626',
    900: '#171717',
  },
};

间距系统 (spacing.ts)

export const spacing = {
  xs: 4,
  sm: 8,
  md: 16,
  lg: 24,
  xl: 32,
  '2xl': 48,
  '3xl': 64,
};

圆角系统 (radius.ts)

export const radius = {
  none: 0,
  sm: 4,
  md: 8,
  lg: 12,
  xl: 16,
  '2xl': 24,
  full: 9999,
};

尺寸定义 (size.ts)

export const sizes = {
  xs: 'xs',
  sm: 'sm',
  md: 'md',
  lg: 'lg',
  xl: 'xl',
} as const;

export type Size = keyof typeof sizes;

主题系统 (theme.ts)

export interface Theme {
  colors: typeof colors;
  spacing: typeof spacing;
  radius: typeof radius;
  sizes: typeof sizes;
}

export const defaultTheme: Theme = {
  colors,
  spacing,
  radius,
  sizes,
};

// 主题创建工具
export function createTheme(overrides: DeepPartial<Theme>): Theme {
  return deepMerge(defaultTheme, overrides);
}

工具函数

// 类型工具
export type DeepPartial<T> = {
  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
};

// 合并工具
export function deepMerge<T>(target: T, source: DeepPartial<T>): T;

// 样式工具
export function cn(...classes: (string | undefined | null | false)[]): string;

🔧 开发

构建

# 构建包
pnpm build

# 开发模式（监听文件变化）
pnpm dev

项目结构

packages/shared/
├── src/
│   ├── color.ts       # 颜色定义
│   ├── spacing.ts     # 间距定义
│   ├── radius.ts      # 圆角定义
│   ├── size.ts        # 尺寸定义
│   ├── theme.ts       # 主题系统
│   └── index.ts       # 导出入口
├── dist/              # 构建输出
└── package.json

🎨 设计原则

一致性

所有设计令牌在 Web 和 Native 平台保持一致，确保跨平台的视觉统一性。

可扩展性

主题系统支持深度定制，可以轻松覆盖默认值：

import { createTheme } from '@particle-network/ui-shared';

const customTheme = createTheme({
  colors: {
    primary: '#ff6b6b',
    secondary: '#4ecdc4',
  },
  spacing: {
    md: 20, // 覆盖默认的 16
  },
});

类型安全

所有导出都包含完整的 TypeScript 类型定义，提供良好的开发体验。

🔄 版本管理

作为内部包，版本更新会自动触发依赖它的组件库更新。使用 Changesets 管理版本：

# 创建变更记录
pnpm changeset

# 更新版本
pnpm changeset:version

# 发布（通过 CI/CD）
pnpm changeset:release

🤝 贡献

修改共享包时请注意：

1. 向后兼容 - 避免破坏性更改
2. 同步更新 - 确保 Web 和 Native 组件库都能正常工作
3. 文档更新 - 更新相关文档和类型定义
4. 测试覆盖 - 添加相应的测试用例

📄 许可证

MIT © UniversalX Team

🔗 相关链接

• 主项目仓库
• React 组件库
• React Native 组件库