UUI: system designowy dla Web Components

UUI: budowa uniwersalnego systemu projektowego dla weba z Web Components

System projektowy UUI oferuje minimalny zestaw Web Components do szybkiego rozpoczęcia pracy. Nie zależy od żadnego frameworka i wykorzystuje podejście atomowe: podstawowe tokeny kolorów, typografii, zaokrągleń i cieni. Komponenty łatwo można dostosować, co pozwala na integrację z projektami w React, Vue, Angular lub czystym JS. Rozwiązuje problem niezgodności interfejsu użytkownika w zespołach prowadzących wiele projektów.

System skupia się na warstwie wizualnej, oddzielonej od logiki biznesowej. Tokeny są definiowane bez znaczenia semantycznego, a przepisy określają dopuszczalne wartości. W przypadku nieprawidłowych atrybutów wyświetlane jest ostrzeżenie w konsoli z automatycznym przejściem do domyślnych ustawień.

Instalacja i konfiguracja

Zainstaluj pakiet przez npm po dodaniu tokenu do pliku .npmrc:

npm install @ushliypakostnik/uui-library

Skopiuj czcionki z node_modules/@ushliypakostnik/uui-library/public/fonts do folderu public/fonts. Dodaj skrypt postinstall do pliku 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('Czcionki skopiowane do',dest);}else{console.log('Czcionki nie znalezione');}\""
  }
}

Inicjalizacja

Zaimportuj i uruchom:

import UUI from 'uui';

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

Opcje:

• isInitWC: true — inicjuje Web Components (dla Vue3, Angular, czystego JS).
• isAddNormalize: true — stosuje normalizację CSS (dla nowych projektów).

TypeScript: dodaj deklarację modułu do pliku *.d.ts:

declare module "@ushliypakostnik/uui-library";

Dla React zainstaluj @types/react i rozszerz JSX.IntrinsicElements dla uui-text, uui-icon itp.

Integracja z frameworkami

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: Użyj CUSTOM_ELEMENTS_SCHEMA w komponentach. Inicjalizuj z isInitWC: true.

Vue3: Inicjalizuj z isInitWC: true. W ESLint dodaj ignor dla slot w uui-text, uui-icon.

Przewodnik i tokeny

Tokeny w pliku src/models/models.ts:

• Typografia: Fonts.elena i inne.
• Zaokrąglenia: Roundings.dancing.
• Przezroczystość: Opacities.waltz.
• Cienie: Shadows.antares.
• Kolory: Colors.cat.

Stała DESIGN przechowuje breakpointy i tematy. Atrybuty w Angular są w formacie camelCase.

Atrybuty logiczne:

• Statyczne (np. rounded): zawsze aktywne.
• Dynamiczne (np. loading): pokazują stan niezależnie od wartości.

Przykład:

<!-- Statyczny: zawsze zaokrąglony -->
<input rounded>

<!-- Dynamiczny: pokazuje loader -->
<input loading>

Komponenty i dostosowanie

UUI zawiera podstawowe elementy: uui-text, uui-icon itp. Dostosuj prefiksy (np. ivanov-ivan-text). Komponenty wykorzystują sloty do zawartości.

Tokeny bez znaczenia semantycznego upraszczają migrację i skalowanie. Projektanci dostarczają przepisy z tokenami, programiści implementują atomy.

Zalety dla zespołów:

• Jednolity język wizualny bez zależności od frameworka.
• Brak konfliktów specyficznych dla CSS.
• Centralne zarządzanie stylami.
• Łatwa integracja z projektami legacy.

Co jest ważne

• Niezależność: działa z dowolnym frameworkiem JS poprzez Web Components.
• Minimalizm: tylko podstawowe tokeny i komponenty do szybkiego startu.
• Dostosowanie: łatwa zmiana prefiksów i tokenów bez ponownego pisania kodu.
• Projektowanie atomowe: tokeny dla typografii, kolorów, cieni — ścisłe zgodne z przepisami.
• Wsparcie TypeScript: pełne typy i rozszerzenia JSX.

— Editorial Team