UUI: design system for Web Components

UUI: Building a Universal Design System for the Web with Web Components

The UUI design system delivers a minimal set of Web Components to accelerate web development. It’s framework-agnostic and built on atomic design principles—using foundational tokens for colors, typography, rounding, and shadows. Components are easily customizable, making integration into React, Vue, Angular, or plain JavaScript projects seamless. This solves the common problem of inconsistent UI across teams managing multiple projects.

The system focuses solely on the visual layer, cleanly separated from business logic. Tokens are defined without semantic meaning; guidelines specify valid values. Invalid attributes trigger console warnings and fall back to defaults.

Installation and Setup

Install the package via npm after adding your token to .npmrc:

npm install @ushliypakostnik/uui-library

Copy fonts from node_modules/@ushliypakostnik/uui-library/public/fonts to public/fonts. Add a postinstall script to package.json:

{
  "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');}\""
  }
}

Initialization

Import and initialize:

import UUI from 'uui';

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

Options:

• isInitWC: true — initializes Web Components (for Vue3, Angular, pure JS).
• isAddNormalize: true — applies CSS normalization (recommended for new projects).

TypeScript: Add a module declaration in *.d.ts:

declare module "@ushliypakostnik/uui-library";

For React, install @types/react and extend JSX.IntrinsicElements for uui-text, uui-icon, etc.

Framework Integration

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: Use CUSTOM_ELEMENTS_SCHEMA in components. Initialize with isInitWC: true.

Vue3: Initialize with isInitWC: true. In ESLint, add ignore rules for slot in uui-text, uui-icon.

Guidelines and Tokens

Tokens are defined in src/models/models.ts:

• Typography: Fonts.elena and others.
• Rounding: Roundings.dancing.
• Opacity: Opacities.waltz.
• Shadows: Shadows.antares.
• Colors: Colors.cat.

The DESIGN constant holds breakpoints and themes. Angular attributes use camelCase.

Logical attributes:

• Static (e.g. rounded): Always active.
• Dynamic (e.g. loading): Reflects state regardless of value.

Example:

<!-- Static: always rounded -->
<input rounded>

<!-- Dynamic: shows loader -->
<input loading>

Components and Customization

UUI includes core elements like uui-text, uui-icon, and more. Customize prefixes (e.g. ivanov-ivan-text). Components use slots for content.

Non-semantic tokens simplify migration and scaling. Designers provide token guidelines; developers implement atomic components.

Benefits for teams:

• Unified visual language independent of frameworks.
• No CSS specificity conflicts.
• Centralized style management.
• Easy integration into legacy projects.

Key Takeaways

• Framework Independence: Works with any JS framework via Web Components.
• Minimalism: Only essential tokens and components for rapid startup.
• Customization: Easily change prefixes and tokens without rewriting code.
• Atomic Design: Typography, color, shadow tokens strictly follow guidelines.
• TypeScript Support: Full type definitions and JSX extensions.

— Editorial Team