Helix Design System - A comprehensive Angular component library
npm install ps-helixA comprehensive Angular component library built with Angular 21+ featuring modern design patterns, accessibility-first development, and optimal developer experience.




- Overview
- Prerequisites
- Installation
- Quick Start
- Configuration
- Global Styles
- Phosphor Icons Setup
- Theme Service
- Translation Service
- Scroll Service
- Core Concepts
- Standalone Components
- Signal-Based Reactivity
- Type Safety
- Dependency Injection
- Available Components
- Service APIs
- ThemeService
- ToastService
- ScrollService
- TranslationService
- Exported Types
- Theming
- Best Practices
- Troubleshooting
- Browser Support
- Development Scripts
- Contributing
- License
- Resources
Helix is a production-ready design system that provides:
- 28 Standalone Components - All components are standalone, no NgModules required
- Signal-Based Reactivity - Built with Angular 21 signals for optimal performance
- Accessibility First - WCAG 2.1 AA compliant out of the box
- TypeScript Strict Mode - Full type safety and IntelliSense support
- Complete Type Exports - All component types and enums exported for type-safe development
- Customizable Theming - Light/dark modes with brand color customization
- Phosphor Icons - 6000+ icons with multiple weight variants
- i18n Support - Built-in internationalization with ngx-translate
- Responsive Design - Mobile-first approach with comprehensive breakpoint system
- Modern Architecture - Built with Angular 21 standalone components and signals
Before installing Helix, ensure your development environment meets these requirements:
- Node.js: 18.x or higher
- npm: 9.x or higher
- Angular: 21.0.3 or higher
- Angular CLI: 21.0.3 or higher
- TypeScript: 5.9.0 or higher
``json`
{
"@angular/common": "^21.0.3",
"@angular/core": "^21.0.3",
"@angular/forms": "^21.0.3",
"@ngx-translate/core": "^15.0.0",
"rxjs": "^7.8.0"
}
The following dependencies are bundled with ps-helix:
- @phosphor-icons/web: 2.0.3 - Icon library
- date-fns: ^3.3.1 - Date utility functions
- tslib: ^2.6.0 - TypeScript runtime library
Install the package via your preferred package manager:
Avec pnpm (recommandé) :
`bash`
pnpm add ps-helix
Avec npm :
`bash`
npm install ps-helix
All peer dependencies should be automatically installed. If not, install them manually:
Avec pnpm :
`bash`
pnpm add @angular/common@^21.0.3 @angular/core@^21.0.3 @angular/forms@^21.0.3 @ngx-translate/core@^15.0.0 rxjs@^7.8.0
Avec npm :
`bash`
npm install @angular/common@^21.0.3 @angular/core@^21.0.3 @angular/forms@^21.0.3 @ngx-translate/core@^15.0.0 rxjs@^7.8.0
After installation, verify that ps-helix is in your package.json:
`json`
{
"dependencies": {
"ps-helix": "^3.0.7"
}
}
In your main styles.css file, import the Helix stylesheet:
`css`
@import 'ps-helix/styles.css';
This single import includes:
- CSS Reset (normalize styles across browsers)
- Design Tokens (spacing, typography, colors, etc.)
- Light and Dark theme variables
- Utility classes (spacing, typography, layout, etc.)
- Responsive breakpoints and grid system
- Animation utilities
- Focus management styles
Add Phosphor Icons CDN links to your src/index.html in the
section:`html
Your App
`$3
All components are standalone. Import them directly where needed:
`typescript
import { Component } from '@angular/core';
import { PshButtonComponent } from 'ps-helix';@Component({
selector: 'app-root',
imports: [PshButtonComponent],
template:
})
export class AppComponent {
handleClick() {
console.log('Button clicked!');
}
}
`$3
If you want to use theme switching, inject the ThemeService:
`typescript
import { Component, inject, OnInit } from '@angular/core';
import { ThemeService } from 'ps-helix';@Component({
selector: 'app-root',
template:
})
export class AppComponent implements OnInit {
themeService = inject(ThemeService); ngOnInit() {
// Theme is initialized automatically
console.log('Current theme:', this.themeService.themeName());
}
}
`$3
Create a simple test component to ensure the library is working:
`typescript
import { Component } from '@angular/core';
import { PshButtonComponent, PshCardComponent, PshAlertComponent } from 'ps-helix';@Component({
selector: 'app-test',
imports: [PshButtonComponent, PshCardComponent, PshAlertComponent],
template:
})
export class TestComponent {}
`Configuration
$3
The design system provides a comprehensive set of CSS custom properties (CSS variables) that you can use in your own styles:
`css
/ Using design tokens in your custom styles /
.my-custom-component {
padding: var(--spacing-md);
margin-bottom: var(--spacing-lg);
background: var(--surface-card);
color: var(--text-color);
border-radius: var(--border-radius);
box-shadow: var(--shadow-md);
}
`$3
After adding the CDN links, use icons in your templates:
`html
`Browse all 6000+ icons at: https://phosphoricons.com/
$3
The
ThemeService manages light/dark theme switching and custom brand colors.#### Basic Theme Switching
`typescript
import { Component, inject } from '@angular/core';
import { ThemeService } from 'ps-helix';@Component({
selector: 'app-root',
template:
})
export class AppComponent {
themeService = inject(ThemeService); toggleTheme() {
this.themeService.toggleTheme();
}
}
`For complete theming documentation including custom brand colors, see THEME.md.
$3
Configure internationalization with ngx-translate:
`typescript
// src/main.ts
import { bootstrapApplication } from '@angular/platform-browser';
import { provideHttpClient } from '@angular/common/http';
import { TranslateModule, TranslateLoader, TranslateService } from '@ngx-translate/core';
import { TranslateHttpLoader } from '@ngx-translate/http-loader';
import { HttpClient } from '@angular/common/http';
import { AppComponent } from './app/app.component';export function HttpLoaderFactory(http: HttpClient) {
return new TranslateHttpLoader(http, './assets/i18n/', '.json');
}
bootstrapApplication(AppComponent, {
providers: [
provideHttpClient(),
...TranslateModule.forRoot({
defaultLanguage: 'en',
loader: {
provide: TranslateLoader,
useFactory: HttpLoaderFactory,
deps: [HttpClient]
}
}).providers || []
]
}).then(ref => {
const translateService = ref.injector.get(TranslateService);
translateService.use('en');
});
`#### Using TranslationService in Components
`typescript
import { Component, inject } from '@angular/core';
import { TranslationService } from 'ps-helix';@Component({
selector: 'app-example',
template:
})
export class ExampleComponent {
private translationService = inject(TranslationService); changeLanguage(event: Event) {
const lang = (event.target as HTMLSelectElement).value;
this.translationService.setLanguage(lang);
}
}
`$3
The
ScrollService provides utilities for scroll management:`typescript
import { Component, inject } from '@angular/core';
import { ScrollService } from 'ps-helix';@Component({
selector: 'app-example',
template:
})
export class ExampleComponent {
private scrollService = inject(ScrollService); scrollToTop() {
this.scrollService.scrollToTop();
}
scrollToElement(selector: string) {
this.scrollService.scrollToElement(selector);
}
}
`Core Concepts
$3
All Helix components are standalone (no NgModules required):
`typescript
import { Component } from '@angular/core';
import {
PshButtonComponent,
PshInputComponent,
PshCardComponent
} from 'ps-helix';@Component({
selector: 'app-form',
imports: [
PshButtonComponent,
PshInputComponent,
PshCardComponent
],
template:
})
export class FormComponent {}
`$3
Components use Angular signals for optimal change detection:
`typescript
import { Component, signal } from '@angular/core';
import { PshModalComponent } from 'ps-helix';@Component({
selector: 'app-example',
imports: [PshModalComponent],
template:
Are you sure?
`
})
export class ExampleComponent {
isOpen = signal(false);
}
All components export TypeScript types for type-safe development:
`typescript
import { Component } from '@angular/core';
import { PshButtonComponent, ButtonVariant, ButtonSize } from 'ps-helix';
@Component({
selector: 'app-example',
imports: [PshButtonComponent],
template:
{{ buttonText }}
`
})
export class ExampleComponent {
variant: ButtonVariant = 'primary'; // Type-safe
size: ButtonSize = 'medium'; // Type-safe
buttonText = 'Click Me';
}
Use modern inject() function instead of constructor injection:
`typescript
import { Component, inject } from '@angular/core';
import { ThemeService, ToastService } from 'ps-helix';
@Component({
selector: 'app-example',
template:
})
export class ExampleComponent {
// Modern injection syntax
private themeService = inject(ThemeService);
private toastService = inject(ToastService);
showToast() {
this.toastService.success('Hello from Helix!');
}
}
`
Helix provides 28 production-ready components organized by category:
- PshButtonComponent - Versatile button with multiple variants, sizes, and states
- PshInputComponent - Text input with validation, error messages, and form control integration
- PshCheckboxComponent - Checkbox with customizable states and labels
- PshRadioComponent - Radio button for single selection from a group
- PshSelectComponent - Dropdown select with search, filtering, and custom rendering
- PshSwitchComponent - Toggle switch with on/off states
- PshCardComponent - Flexible content container with header, body, and footer sections
- PshModalComponent - Modal dialog overlay with backdrop and keyboard navigation
- PshSidebarComponent - Collapsible sidebar navigation with responsive behavior
- PshCollapseComponent - Expandable/collapsible content section with animation
- PshTabsComponent + PshTabComponent - Tabbed content organization with keyboard navigation
- PshTabBarComponent - Bottom tab bar navigation for mobile-first applications
- PshAlertComponent - Alert messages with severity levels (success, info, warning, error)
- PshToastComponent + ToastService - Toast notification system with queue management
- PshSpinloaderComponent - Loading spinner with various sizes
- PshProgressbarComponent - Progress indicator with percentage display
- PshTooltipComponent - Contextual tooltips with multiple positions
- PshTableComponent - Data table with sorting, pagination, and custom rendering
- PshBadgeComponent - Status badges and indicators with various colors
- PshTagComponent - Removable tags for labels and filters
- PshAvatarComponent - User avatar with image, initials, or icon fallback
- PshStatCardComponent - Statistical card for dashboards
- PshInfoCardComponent - Information card with icon and content
- PshHorizontalCardComponent - Horizontal layout card component
- PshMenuComponent - Dropdown menu with nested items
- PshPaginationComponent - Pagination controls with page numbers
- PshStepperComponent + PshStepComponent - Step-by-step wizard navigation with validation
- PshDropdownComponent - Dropdown trigger and content container
Manage application themes and custom brand colors.
Methods:
- setDarkTheme(isDark: boolean) - Set theme modetoggleTheme()
- - Toggle between light and darkupdateTheme(name: 'light' | 'dark')
- - Update theme by nameapplyInsurerTheme()
- - Apply custom brand colors
Computed Signals:
- themeName() - Returns current theme nameisDarkTheme()
- - Returns boolean for dark modethemeInfo()
- - Returns complete theme information
Example:
`typescript
import { inject } from '@angular/core';
import { ThemeService } from 'ps-helix';
export class MyComponent {
themeService = inject(ThemeService);
get currentTheme() {
return this.themeService.themeName(); // 'light' or 'dark'
}
get isDark() {
return this.themeService.isDarkTheme(); // boolean
}
switchTheme() {
this.themeService.toggleTheme();
}
}
`
Display temporary notification messages.
Methods:
- success(message: string, options?) - Show success toasterror(message: string, options?)
- - Show error toastwarning(message: string, options?)
- - Show warning toastinfo(message: string, options?)
- - Show info toast
Options:
- duration?: number - Display duration in milliseconds (default: 3000)position?: ToastPosition
- - 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left'
Example:
`typescript
import { inject } from '@angular/core';
import { ToastService } from 'ps-helix';
export class MyComponent {
private toastService = inject(ToastService);
saveData() {
try {
// Save logic
this.toastService.success('Data saved successfully!');
} catch (error) {
this.toastService.error('Failed to save data');
}
}
showCustom() {
this.toastService.info('Processing...', {
duration: 5000,
position: 'bottom-right'
});
}
}
`
Utility service for scroll management and smooth scrolling.
Methods:
- scrollToTop() - Scroll to page top smoothlyscrollToElement(selector: string)
- - Scroll to specific elementdisableScroll()
- - Disable page scrolling (useful for modals)enableScroll()
- - Re-enable page scrolling
Example:
`typescript
import { inject } from '@angular/core';
import { ScrollService } from 'ps-helix';
export class MyComponent {
private scrollService = inject(ScrollService);
backToTop() {
this.scrollService.scrollToTop();
}
goToSection(sectionId: string) {
this.scrollService.scrollToElement(#${sectionId});
}
openModal() {
this.scrollService.disableScroll();
// Show modal
}
closeModal() {
this.scrollService.enableScroll();
// Hide modal
}
}
`
Wrapper service for ngx-translate functionality.
Methods:
- setLanguage(lang: string) - Change application languagegetTranslation(key: string)
- - Get translation for a keyinstant(key: string)
- - Get instant translation (synchronous)
Example:
`typescript
import { Component, inject } from '@angular/core';
import { TranslationService } from 'ps-helix';
@Component({
selector: 'app-language-selector',
template:
})
export class LanguageSelectorComponent {
private translationService = inject(TranslationService);
changeLanguage(event: Event) {
const selectedLang = (event.target as HTMLSelectElement).value;
this.translationService.setLanguage(selectedLang);
}
}
`
All component types and enums are exported for type-safe development:
`typescript
import { AlertType, AlertVariant } from 'ps-helix';
const type: AlertType = 'success' | 'error' | 'warning' | 'info';
const variant: AlertVariant = 'solid' | 'outlined' | 'soft';
`
`typescript
import { AvatarSize, AvatarShape } from 'ps-helix';
const size: AvatarSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
const shape: AvatarShape = 'circle' | 'square';
`
`typescript
import { BadgeSize, BadgeVariant } from 'ps-helix';
const size: BadgeSize = 'sm' | 'md' | 'lg';
const variant: BadgeVariant = 'primary' | 'secondary' | 'success' | 'danger' | 'warning' | 'info';
`
`typescript
import { ButtonAppearance, ButtonSize, ButtonVariant } from 'ps-helix';
const appearance: ButtonAppearance = 'filled' | 'outlined' | 'text' | 'ghost';
const size: ButtonSize = 'small' | 'medium' | 'large';
const variant: ButtonVariant = 'primary' | 'secondary' | 'success' | 'danger' | 'warning' | 'info';
`
`typescript
import { InputSize, InputType } from 'ps-helix';
const size: InputSize = 'small' | 'medium' | 'large';
const type: InputType = 'text' | 'password' | 'email' | 'number' | 'tel' | 'url' | 'search';
`
`typescript
import { ModalSize } from 'ps-helix';
const size: ModalSize = 'small' | 'medium' | 'large' | 'fullscreen';
`
`typescript
import { SelectOption, SelectOptionGroup, SelectSize, SearchConfig } from 'ps-helix';
interface SelectOption
label: string;
value: T;
icon?: string;
disabled?: boolean;
description?: string;
}
interface SelectOptionGroup
label: string;
options: SelectOption
disabled?: boolean;
}
interface SearchConfig {
debounceTime: number;
placeholder: string;
minLength: number;
}
type SelectSize = 'small' | 'medium' | 'large';
`
`typescript
import { StepperVariant } from 'ps-helix';
const variant: StepperVariant = 'default' | 'numbered' | 'progress';
`
`typescript
import { TableColumn, TableSortDirection } from 'ps-helix';
const sortDirection: TableSortDirection = 'asc' | 'desc' | null;
interface TableColumn
key: string;
label: string;
sortable?: boolean;
width?: string;
align?: 'left' | 'center' | 'right';
render?: (item: T) => string;
}
`
`typescript
import { ToastPosition, ToastVariant } from 'ps-helix';
const position: ToastPosition = 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left';
const variant: ToastVariant = 'success' | 'error' | 'warning' | 'info';
`
`typescript
import { TooltipPlacement, TooltipTrigger } from 'ps-helix';
const placement: TooltipPlacement = 'top' | 'bottom' | 'left' | 'right';
const trigger: TooltipTrigger = 'hover' | 'click' | 'focus';
`
For a complete list of all exported types, see the type definitions.
Helix provides default theme colors:
- Primary: #0F02C4 (Deep Blue)#7B3AEC
- Secondary: (Purple)
Customize to match your brand identity using the injection token pattern. See the complete guide in THEME.md.
Once configured, numerous CSS variables are available:
Primary Color:
- --primary-color--primary-color-light
- --primary-color-lighter
- --primary-color-dark
- --primary-color-darker
- --primary-color-text
- --primary-color-rgb
-
Secondary Color:
- --secondary-color--secondary-color-light
- --secondary-color-lighter
- --secondary-color-dark
- --secondary-color-darker
- --secondary-color-text
- --secondary-color-rgb
-
`css
.my-button {
background: var(--primary-color);
color: var(--primary-color-text);
}
.my-button:hover {
background: var(--primary-color-light);
}
`
For complete theming guide including custom colors, dynamic changes, and advanced configurations, see THEME.md.
`typescript
// ✅ Good: Import only what you need
import { PshButtonComponent, PshInputComponent } from 'ps-helix';
// ❌ Avoid: Don't import entire module
import * as Helix from 'ps-helix';
`
`typescript
// ✅ Good: Use exported types
import { ButtonVariant, ButtonSize } from 'ps-helix';
const variant: ButtonVariant = 'primary';
const size: ButtonSize = 'medium';
// ❌ Avoid: Magic strings without types
const variant = 'primary'; // No type checking
`
`typescript
// ✅ Good: Use signals for reactive state
import { signal } from '@angular/core';
export class MyComponent {
isVisible = signal(false);
toggle() {
this.isVisible.update(v => !v);
}
}
// ❌ Avoid: Traditional properties for reactive UI
export class MyComponent {
isVisible = false; // Won't trigger change detection optimally
}
`
`html
`
`typescript
// ✅ Good: Reactive forms with FormControl
import { FormControl, Validators } from '@angular/forms';
export class MyComponent {
emailControl = new FormControl('', [
Validators.required,
Validators.email
]);
}
`
`html`
[formControl]="emailControl"
[required]="true">
`typescript
// ✅ Good: Use OnPush change detection
import { ChangeDetectionStrategy } from '@angular/core';
@Component({
selector: 'app-example',
changeDetection: ChangeDetectionStrategy.OnPush,
template: ...
})
export class ExampleComponent {}
// ✅ Good: Use trackBy for lists
@Component({
template:
@for (item of items(); track item.id) {
}
`
})
export class ListComponent {
items = signal
}
`typescript
// ✅ Good: Test components with TestBed
import { ComponentFixture, TestBed } from '@angular/core/testing';
import { PshButtonComponent } from 'ps-helix';
describe('MyComponent', () => {
let component: MyComponent;
let fixture: ComponentFixture
beforeEach(async () => {
await TestBed.configureTestingModule({
imports: [MyComponent, PshButtonComponent]
}).compileComponents();
fixture = TestBed.createComponent(MyComponent);
component = fixture.componentInstance;
fixture.detectChanges();
});
it('should create', () => {
expect(component).toBeTruthy();
});
});
`
Problem: Components appear unstyled or broken.
Solution: Ensure you've imported the global stylesheet:
`css`
/ In src/styles.css /
@import 'ps-helix/styles.css';
Problem: Icons show as empty squares or missing glyphs.
Solution: Verify Phosphor Icons CDN links are in index.html:
`html`
Problem: Brand colors aren't being used.
Solution:
1. Verify your theme context service implements InsurerContextServicemain.ts
2. Check the provider configuration in or app.config.ts#FF0000
3. Ensure you're using valid hex color codes (e.g., )themeService.applyInsurerTheme()
4. Call after color changes
See THEME.md for complete theming documentation.
Problem: TypeScript compilation errors with component imports.
Solution:
1. Verify Angular version is 21.0.3 or higher
2. Check tsconfig.json has "strict": truerm -rf node_modules && pnpm install
3. Ensure all peer dependencies are installed
4. Clear node_modules and reinstall:
- Avec pnpm: rm -rf node_modules && npm install
- Avec npm:
Problem: Application feels slow or unresponsive.
Solution:
1. Use OnPush change detection strategytrackBy
2. Implement proper signal usage
3. Avoid unnecessary component re-renders
4. Use functions in @for loops
5. Lazy load routes and components where possible
Problem: Build fails with module resolution errors.
Solution:
1. Verify package.json includes ps-helix in dependencies
2. Clear Angular cache: ng cache clean
3. Delete .angular folder and rebuild
4. Check that all peer dependencies match required versions
Problem: Errors in browser console at runtime.
Solution:
1. Check browser console for specific error messages
2. Verify all required services are provided
3. Ensure ThemeService is initialized if using custom themes
4. Check that ngx-translate is properly configured if using i18n
Helix Design System supports:
- Chrome: Latest 2 versions
- Firefox: Latest 2 versions
- Safari: Latest 2 versions
- Edge: Latest 2 versions
- Mobile browsers: iOS Safari 14+, Chrome Android latest
Note: Internet Explorer is not supported.
The following scripts are available for library development:
Avec pnpm (recommandé) :
`bash`
pnpm run build:lib # Build the library
pnpm run watch:lib # Watch for changes and rebuild
pnpm run publish:lib # Publish to npm registry
pnpm run build # Build demo application
pnpm run dev # Run demo application in dev mode
Avec npm :
`bash`
npm run build:lib # Build the library
npm run watch:lib # Watch for changes and rebuild
npm run publish:lib # Publish to npm registry
npm run build # Build demo application
npm run dev # Run demo application in dev mode
We welcome contributions! To contribute to Helix Design System:
1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-featuregit commit -am 'Add new feature'
3. Make your changes and commit: git push origin feature/my-feature
4. Push to the branch:
5. Submit a pull request
- Follow Angular style guide
- Use TypeScript strict mode
- Write tests for new components
- Document all public APIs
- Ensure accessibility compliance (WCAG 2.1 AA)
- Keep components small and focused
- Use signals for reactive state
MIT License - see LICENSE file for details.
Copyright (c) 2025 PACK Solutions
- Theme Customization Guide: THEME.md
- Component Documentation: Individual component README files in /lib/components/`
- Phosphor Icons: https://phosphoricons.com/
- Angular Documentation: https://angular.dev/
- TypeScript Documentation: https://www.typescriptlang.org/
- ngx-translate: https://github.com/ngx-translate/core
---
Version: 3.0.7
Built with: Angular 21.0.3, TypeScript 5.9.0, Phosphor Icons 2.0.3
Author: Fabrice PEREZ | Product Designer at PACK Solutions
Last Updated: January 2026