@prioticket/design-system-web

v1.7.0

Published

3 months ago

A comprehensive Web Components library built with **Lit** that provides Material Design components for Prioticket applications. This library is designed to work seamlessly across any frontend framework or in vanilla HTML.

0High
0Medium
0Low

cristian_olariu

design-system web-components material-design lit prioticket components ui

Prioticket Design System Web

A comprehensive Web Components library built with Lit that provides Material Design components for Prioticket applications. This library is designed to work seamlessly across any frontend framework or in vanilla HTML.

Features

🎨 Material Design 3 - Built on Google's official Material Web components
🌈 Dynamic Theming - Real-time theme switching without page reload
🌐 Framework Agnostic - Works with Angular, React, Vue, PHP, or any web technology
📦 Tree Shakable - Load only the components you need
🎯 TypeScript - Full type safety and excellent developer experience
🔧 Customizable - Flexible theming with CSS custom properties
⚡ Performance Optimized - Individual component bundles for maximum efficiency
🎪 Modern Standards - ES Modules, Web Components, and HTTP/2 friendly

Installation

npm install @prioticket/design-system-web

React projects

We publish official wrappers as @prioticket/design-system-react. Install that package alongside the web components when building React apps—see packages/react/README.md for setup and usage details.

Usage Guide

1. Quick Start with CDN (Recommended for PHP, Vanilla HTML, etc.)

This is the fastest way to try the components on any plain HTML page while keeping everything tree-shakable.

Instructions:

Add the Material Symbols font (optional, only needed when you use icons).
Include one of the provided theme CSS files.
Copy the import map below so the browser can resolve the bare module specifiers used by Lit, Material Web, and tslib.
Import the components you need from the CDN.

<!DOCTYPE html>
<html>
<head>
  <title>My App</title>
  <!-- 1. Material Symbols for icons -->
  <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,[email protected],100..700,0..1,-50..200">

  <!-- 2. Theme CSS -->
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@prioticket/[email protected]/dist/theme-only.css">

  <!-- 3. Import map for the design system and its peer dependencies -->
  <script type="importmap">
  {
    "imports": {
      "lit": "https://cdn.jsdelivr.net/npm/[email protected]/index.js",
      "lit/": "https://cdn.jsdelivr.net/npm/[email protected]/",
      "lit-html": "https://cdn.jsdelivr.net/npm/[email protected]/lit-html.js",
      "lit-html/": "https://cdn.jsdelivr.net/npm/[email protected]/",
      "lit-element": "https://cdn.jsdelivr.net/npm/[email protected]/lit-element.js",
      "lit-element/": "https://cdn.jsdelivr.net/npm/[email protected]/",
      "@lit/reactive-element": "https://cdn.jsdelivr.net/npm/@lit/[email protected]/reactive-element.js",
      "@lit/reactive-element/": "https://cdn.jsdelivr.net/npm/@lit/[email protected]/",
      "@material/web": "https://cdn.jsdelivr.net/npm/@material/[email protected]/index.js",
      "@material/web/": "https://cdn.jsdelivr.net/npm/@material/[email protected]/",
      "tslib": "https://cdn.jsdelivr.net/npm/[email protected]/tslib.es6.js",
      "tslib/": "https://cdn.jsdelivr.net/npm/[email protected]/"
    }
  }
  </script>
</head>
<body>
  <pd-button>Click Me</pd-button>

  <!-- 4. Import the components you need -->
  <script type="module">
    await import("https://cdn.jsdelivr.net/npm/@prioticket/[email protected]/dist/components/pd-button.es.js");
  </script>
</body>
</html>

Notes:

Reuse the same import map for every demo page; add or remove component imports as needed (see public/component-gallery.html for a larger example).
Chromium-based browsers allow this to run directly from file:// URLs. For Safari/Firefox or when sharing with others, serve the folder over HTTP (for example, npx http-server public or python3 -m http.server).
Update the @prioticket/[email protected] version string when a new release becomes available.

<!-- Theme CSS options -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@prioticket/[email protected]/dist/theme-only.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@prioticket/[email protected]/dist/theme-with-fonts.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@prioticket/[email protected]/dist/fonts-only.css">

PHP Example:

<!DOCTYPE html>
<html>
<head>
    <title><?= htmlspecialchars($pageTitle) ?></title>
    <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,[email protected],100..700,0..1,-50..200">
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@prioticket/[email protected]/dist/theme-only.css">
    <script type="importmap">{
        "imports": {
            "lit": "https://cdn.jsdelivr.net/npm/[email protected]/index.js",
            "lit/": "https://cdn.jsdelivr.net/npm/[email protected]/",
            "@material/web": "https://cdn.jsdelivr.net/npm/@material/[email protected]/index.js",
            "@material/web/": "https://cdn.jsdelivr.net/npm/@material/[email protected]/",
            "tslib": "https://cdn.jsdelivr.net/npm/[email protected]/tslib.es6.js",
            "tslib/": "https://cdn.jsdelivr.net/npm/[email protected]/"
        }
    }</script>
</head>
<body>
    <pd-button variant="filled"><?= htmlspecialchars($buttonText) ?></pd-button>
    <pd-card>
        <h3><?= htmlspecialchars($cardTitle) ?></h3>
        <p><?= htmlspecialchars($cardContent) ?></p>
    </pd-card>

    <script type="module">
        await import("https://cdn.jsdelivr.net/npm/@prioticket/[email protected]/dist/components/pd-button.es.js");
        await import("https://cdn.jsdelivr.net/npm/@prioticket/[email protected]/dist/components/pd-card.es.js");
    </script>
</body>
</html>

About single-script bundles

The published package focuses on ES modules so that browsers and bundlers can tree-shake unused Material Web dependencies. Producing a one-file UMD/IIFE bundle would dramatically increase payload size, and Vite cannot emit a shared UMD bundle while we expose every component as an entry point. We plan to revisit this once we have a dedicated aggregation build, but for 1.0.7 we recommend sticking with the import-map approach above or a real bundler setup.

2. Usage with a Bundler (Framework Integration)

Angular

Step 1: Add CSS to angular.json

This tells the Angular CLI to include the theme styles in your application's global CSS bundle.

"styles": [
  "src/styles.css",
  "node_modules/@prioticket/design-system-web/dist/theme-only.css"
]

Step 1.5: Add Material Icons to index.html

Add the Material Icons font to your src/index.html file:

<head>
  <!-- Other head content -->
  <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,[email protected],100..700,0..1,-50..200">
</head>

Step 2: Import Components and Add Schema

In your Angular component, import the components to register them and add CUSTOM_ELEMENTS_SCHEMA.

import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';

// Import components by their package path
import '@prioticket/design-system-web/components/pd-button';

@Component({
  selector: 'app-example',
  template: `<pd-button>Hello from Angular</pd-button>`,
  schemas: [CUSTOM_ELEMENTS_SCHEMA]
})
export class ExampleComponent {}

React / Vue / Other Frameworks

Similar pattern - install via npm, import the CSS file, and import individual components:

// Import the theme CSS (exact method depends on your bundler)
import '@prioticket/design-system-web/dist/theme-only.css';

// Import components
import '@prioticket/design-system-web/components/pd-button';

// Use in JSX/template
<pd-button>Hello from React</pd-button>

Available Components

| Component | Description | CDN Import Path | |-----------|-------------|-----------------| | pd-button | Material Design buttons | components/pd-button.es.js | | pd-card | Cards for content grouping | components/pd-card.es.js | | pd-checkbox | Checkboxes | components/pd-checkbox.es.js | | pd-chip | Chips for tags/filters | components/pd-chip.es.js | | pd-dialog | Modal dialogs | components/pd-dialog.es.js | | pd-expandable-card | Expandable cards with collapsible content | components/pd-expandable-card.es.js | | pd-fab | Floating action buttons | components/pd-fab.es.js | | pd-icon | Material Design icons | components/pd-icon.es.js | | pd-icon-button | Icon buttons | components/pd-icon-button.es.js | | pd-list | Lists with items | components/pd-list.es.js | | pd-menu | Dropdown menus | components/pd-menu.es.js | | pd-menu-item | Individual menu items | components/pd-menu-item.es.js | | pd-progress | Progress indicators | components/pd-progress.es.js | | pd-radio | Radio buttons | components/pd-radio.es.js | | pd-segmented-button | Segmented button controls | components/pd-segmented-button.es.js | | pd-segmented-stepper | Segmented stepper navigation | components/pd-segmented-stepper.es.js | | pd-select | Select dropdowns | components/pd-select.es.js | | pd-slider | Range sliders | components/pd-slider.es.js | | pd-stepper | Step indicators | components/pd-stepper.es.js | | pd-switch | Toggle switches | components/pd-switch.es.js | | pd-tabs | Tab navigation | components/pd-tabs.es.js | | pd-text-field | Text input fields | components/pd-text-field.es.js |

Dynamic Theming

The design system supports real-time theme switching without page reload. Apply custom themes dynamically to match your brand or user preferences.

Basic Usage

// Import the theming system
import { initialize } from '@prioticket/design-system-web/theming';

// Apply a custom theme
await initialize({
  theme: {
    colorPrimary: '#ff6600',
    colorOnPrimary: '#ffffff',
    colorSurface: '#fff8f5',
    shapeCornerSmall: '8px'
  }
});

CDN Usage

<script type="module">
  import { initialize } from 'https://cdn.jsdelivr.net/npm/@prioticket/design-system-web@latest/dist/theming.es.js';
  
  // Apply orange theme
  await initialize({
    theme: {
      colorPrimary: '#ff6600',
      colorPrimaryContainer: '#fff3e8',
      shapeCornerMedium: '12px'
    }
  });
</script>

Supported Theme Tokens

Colors: colorPrimary, colorOnPrimary, colorPrimaryContainer, colorSecondary, colorSurface, colorOnSurface, colorBackground, colorError
Shapes: shapeCornerSmall, shapeCornerMedium, shapeCornerLarge

Framework Examples

React:

useEffect(() => {
  initialize({ 
    theme: { colorPrimary: '#4caf50' } 
  });
}, []);

Angular:

ngOnInit() {
  initialize({ 
    theme: { colorPrimary: '#2196f3' } 
  });
}

Live Demo

Run npm run dev and visit /demo-theming.html to see real-time theme switching in action.

Customizing Fonts

The design system is built to work with any font stack. The theme CSS uses CSS custom properties:

/* Override Prioticket fonts with your own */
:root {
  --md-sys-typescale-body-large-font: "Your Font", Arial, sans-serif;
  --md-sys-typescale-title-medium-font: "Your Font", Arial, sans-serif;
  --md-sys-typescale-headline-small-font: "Your Font", Arial, sans-serif;
}

CSS Architecture

theme-only.css (14KB) - All component styles without fonts
fonts-only.css (1.3KB) - Just Prioticket font declarations
theme-with-fonts.css (15.7KB) - Complete theme including fonts
fonts/ - Font files (~232KB total)

Choose theme-only.css to use your existing fonts, or theme-with-fonts.css for the complete Prioticket experience.

Performance Best Practices

Load only what you need - Import individual components via CDN
Use theme-only.css - If you already have fonts, skip the font files
Leverage HTTP/2 - Multiple small files load efficiently on modern servers
CDN for Lit - Load the Lit dependency from a fast CDN
Conditional loading - In server-side apps, only load components used on each page

Browser Support

Chrome 84+
Firefox 90+
Safari 14+
Edge 84+

Development

# Install dependencies
yarn install

# Start development server
yarn dev

# Build the library
yarn build

# Run Storybook
yarn storybook

Contributing

This project is open for internal contributions. See our documentation:

CONTRIBUTING.md - Complete developer guide for adding components and features
RELEASE-SETUP.md - CI/CD setup and release workflow

Quick Start for Contributors

Clone the repository
Install dependencies: yarn install
Create a feature branch from development
Make your changes and test in Storybook: yarn storybook
Write tests: yarn test
Commit using Conventional Commits: git commit -m "feat: Add new feature"
Push and create a Merge Request to development

Our automated CI/CD will handle versioning and publishing based on your commit messages.

Source Code

The source code for this library is proprietary and maintained in a private repository at Prioticket.

Support

For questions or bug reports, please contact the Prioticket development team internally.