UUI：适用于 Web Components 的设计系统

UUI：基于Web组件构建通用网页设计系统

UUI设计系统提供一组极简的Web组件，助力加速网页开发。它与框架无关，遵循原子设计原则——通过基础样式变量（tokens）定义颜色、排版、圆角和阴影等核心视觉元素。组件高度可定制，能无缝集成到React、Vue、Angular或原生JavaScript项目中，有效解决多团队协作多个项目时界面风格不一致的常见难题。

该系统专注于视觉层，与业务逻辑完全分离。样式变量本身不带语义含义；具体取值规范由设计指南明确说明。若使用无效属性，控制台将发出警告，并自动回退至默认值。

安装与配置

在.npmrc中添加你的令牌后，通过npm安装包：

npm install @ushliypakostnik/uui-library

将字体文件从 node_modules/@ushliypakostnik/uui-library/public/fonts 复制到 public/fonts 目录。在 package.json 中添加 postinstall 脚本：

{
  "scripts": {
    "postinstall": "node -e \"const fs=require('fs');const path=require('path');const src=path.join(__dirname,'node_modules/@ushliypakostnik/uui-library/public/fonts');const dest=path.join(__dirname,'public/fonts');if(fs.existsSync(src)){fs.cpSync(src,dest,{recursive:true});console.log('Fonts copied to',dest);}else{console.log('Fonts not found');}\""
  }
}

初始化

导入并初始化系统：

import UUI from 'uui';

new UUI({ isInitWC: true, isAddNormalize: true });

选项说明：

• isInitWC: true —— 启用Web组件支持（适用于Vue3、Angular及纯JS项目）。
• isAddNormalize: true —— 应用CSS归一化（新项目推荐启用）。

TypeScript用户需在 *.d.ts 文件中添加模块声明：

declare module "@ushliypakostnik/uui-library";

React项目需安装 @types/react，并扩展 JSX.IntrinsicElements 类型以支持 uui-text、uui-icon 等自定义标签。

框架集成

React：

import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import UUI from '@ushliypakostnik/uui-library';
import App from './App.tsx';

new UUI();

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <>
      <App />
    </>
  </StrictMode>,
);

Angular： 在组件中使用 CUSTOM_ELEMENTS_SCHEMA。初始化时设置 isInitWC: true。

Vue3： 初始化时启用 isInitWC: true。ESLint配置中需忽略 uui-text、uui-icon 等组件中的 slot 报警。

设计规范与样式变量

样式变量定义于 src/models/models.ts：

• 排版：Fonts.elena 等。
• 圆角：Roundings.dancing。
• 透明度：Opacities.waltz。
• 阴影：Shadows.antares。
• 颜色：Colors.cat。

DESIGN 常量包含断点和主题配置。Angular中属性采用驼峰命名法。

逻辑属性分类：

• 静态属性（如 rounded）：始终生效。
• 动态属性（如 loading）：根据状态自动切换，与值无关。

示例：

<!-- 静态：始终圆角 -->
<input rounded>

<!-- 动态：显示加载动画 -->
<input loading>

组件与自定义能力

UUI包含核心组件如 uui-text、uui-icon 等。支持自定义前缀（例如 ivanov-ivan-text）。组件通过插槽（slots）承载内容。

非语义化的样式变量让迁移和扩展更轻松。设计师制定变量规范，开发者实现原子化组件。

团队优势：

• 建立跨框架统一的视觉语言。
• 避免CSS特异性冲突。
• 实现样式集中管理。
• 易于接入旧项目。

核心要点

• 框架无关性：通过Web组件兼容任意JS框架。
• 极简主义：仅保留必要样式变量与组件，快速启动项目。
• 高度可定制：无需重写代码即可更改前缀与变量。
• 原子设计：排版、色彩、阴影均严格遵循设计规范。
• TypeScript支持：完整类型定义与JSX扩展。

— Editorial Team