@orchestra-design-system/core

v0.0.13

Published

7 days ago

Web components for the Orchestra design system

Downloads

1,920

0High
0Medium
0Low

yann_isabel

design-system web-components stencil orchestra

@orchestra-design-system/core

Stencil-based web components for the Orchestra design system. Provides a comprehensive component library built with web standards, theme-aware styling, and extensive accessibility support.

Installation

npm install @orchestra-design-system/core

Features

✅ Web Components - Framework-agnostic, standards-based components
✅ Shadow DOM Encapsulation - Scoped styles and DOM isolation
✅ Theme Support - Light and dark themes via CSS variables
✅ Design Tokens - Integrated with @orchestra-design-system/themes token bundles
✅ Icon System - Extensible icon library with custom library support
✅ Accessibility - ARIA attributes, keyboard navigation, screen reader support
✅ TypeScript - Full type definitions included
✅ Lazy Loading - Automatic code splitting and lazy loading
✅ SSR Ready - Pre-rendering support for static sites

Quick Start

HTML

<!DOCTYPE html>
<html>
<head>
  <script type="module" src="https://unpkg.com/@orchestra-design-system/core"></script>
  <link rel="stylesheet" href="https://unpkg.com/@orchestra-design-system/themes/light.css">
</head>
<body>
  <orchestra-button text="Click me"></orchestra-button>
</body>
</html>

React

import React from 'react'
import { defineCustomElements } from '@orchestra-design-system/core/loader'
import '@orchestra-design-system/themes/light.css'

defineCustomElements()

export default function App() {
  return <orchestra-button text="Click me"></orchestra-button>
}

Vue

<script setup>
import { defineCustomElements } from '@orchestra-design-system/core/loader'
import '@orchestra-design-system/themes/light.css'

defineCustomElements()
</script>

<template>
  <orchestra-button text="Click me"></orchestra-button>
</template>

Angular

// app.module.ts
import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core'
import { defineCustomElements } from '@orchestra-design-system/core/loader'

defineCustomElements()

@NgModule({
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<orchestra-button text="Click me"></orchestra-button>

Components

Available Components

orchestra-button - Button component with variants
orchestra-icon - Icon component with library registry system

See Storybook for interactive documentation and examples.

Component Structure

Each component is located in src/components/{name}/:

src/components/button/
├── button.tsx           # Component implementation
├── button.css          # Shadow DOM styles
├── button.spec.ts      # Unit tests
├── readme.md           # Auto-generated docs
└── test/               # E2E tests (optional)

Icon Component

The icon component supports multiple icon libraries using a registry system.

Using Built-in Icons

<orchestra-icon name="checked" size="24px" fill="currentcolor"></orchestra-icon>

Available from @orchestra-design-system/icons-library:

import { iconNames } from '@orchestra-design-system/icons-library'

type IconName = typeof iconNames[number]

Registering Custom Icon Libraries

import { registerIconLibrary } from '@orchestra-design-system/core'

const myIcons = {
  'star': `<svg viewBox="0 0 24 24">...</svg>`,
  'heart': `<svg viewBox="0 0 24 24">...</svg>`,
}

registerIconLibrary('my-icons', {
  resolver: (name) => myIcons[name] ?? ''
})

Then use:

<orchestra-icon name="star" library="my-icons"></orchestra-icon>

See @orchestra-design-system/icons-library README for details on custom libraries and Storybook integration.

Theming

Components use CSS variables for theming. The recommended approach is to import the theme bundle from the dedicated themes package:

<!-- Light theme (default) -->
<link rel="stylesheet" href="https://unpkg.com/@orchestra-design-system/themes/light.css">

<!-- Dark theme -->
<link rel="stylesheet" href="https://unpkg.com/@orchestra-design-system/themes/dark.css">

Or use in JavaScript:

import '@orchestra-design-system/themes/light.css'

Best practice: use the themes package in applications. The themes package is the source of truth for token sources and generated theme CSS bundles.

Custom Themes

Override CSS variables in your styles:

:root {
  --primary-color: #007bff;
  --primary-color-hover: #0056b3;
  --text-color: #333;
  --background-color: #fff;
}

See Themes README for complete token and theme reference.

Development

Setup

cd packages/core
npm install

Build

npm run build:js        # Compile TypeScript → JavaScript
npm run build          # Full core build (JS + types)

Watch Mode

npm run start:js       # Watch Stencil build and docs
npm run start          # Alias of start:js

Theme CSS is owned by @orchestra-design-system/themes and should be imported at the application layer (for example Storybook or consuming apps), not generated by the core package.

Testing

npm run test           # Run full Stencil test suite
npm run test:watch     # Watch mode
npm run test:spec      # Unit/spec tests
npm run test:e2e       # Browser end-to-end tests

Storybook

See ../storybook/README.md for component development and testing with Storybook.

Building Components

Creating a New Component

Create component file - src/components/{name}/{name}.tsx
Define Stencil component:

import { Component, Prop, h } from '@stencil/core'

@Component({
  tag: 'orchestra-mycomponent',
  shadow: true,
  styleUrl: 'mycomponent.css',
})
export class MyComponent {
  @Prop() label!: string

  render() {
    return <button>{this.label}</button>
  }
}

Add styles - src/components/{name}/{name}.css (scoped to shadow DOM)
Export from index - src/index.ts
Add story - ../storybook/src/stories/components/{name}/{name}.stories.ts
Test in Storybook - npm run dev

Component Conventions

See .github/instructions/component-conventions.instructions.md for:

Naming conventions
Property/method patterns
Event handling
Accessibility requirements
Documentation standards

Output Targets

Components are compiled to multiple formats:

ESM - dist/orchestra-design-system/index.esm.js (modern browsers)
CommonJS - dist/index.cjs.js (Node.js)
UMD - dist/orchestra-design-system.js (browser globals)
Hydrate - hydrate/index.js (server-side rendering)
Loader - loader/index.js (lazy loading)

See stencil.config.ts for output target configuration.

Distribution

Packages are published to npm:

npm install @orchestra-design-system/core

CDN:

<script src="https://unpkg.com/@orchestra-design-system/core"></script>

File Structure

packages/core/
├── src/
│   ├── components/       # Component implementations
│   │   ├── button/
│   │   ├── icon/
│   │   └── ...
│   ├── utils/            # Utility functions
│   │   ├── a11y.ts      # Accessibility utilities
│   │   └── ...
│   ├── types/            # TypeScript type definitions
│   ├── themes/           # CSS theme files (generated)
│   ├── helpers.ts        # Helper functions
│   └── index.ts          # Package entry point
├── dist/                 # Build output (generated)
├── stencil.config.ts     # Stencil configuration
├── tsconfig.json
├── package.json
└── README.md

Learn More

Stencil Documentation
Web Components MDN
Orchestra Design System (replace with actual URL)

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@orchestra-design-system/core

Installation

Features

Quick Start

HTML

React

Vue

Angular

Components

Available Components

Component Structure

Icon Component

Using Built-in Icons

Registering Custom Icon Libraries

Theming

Custom Themes

Development

Setup

Build

Watch Mode

Testing

Storybook

Building Components

Creating a New Component

Component Conventions

Output Targets

Distribution

File Structure

Learn More