`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:

Current theme: {{ themeService.themeName() }}


})
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:

English
Français
Español


})
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:
Back to Top
Go to Section 2

})
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:


Submit


})
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:
Open Modal

Are you sure?

`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';
}
`

$3

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: Show Toast
})
export class ExampleComponent {
// Modern injection syntax
private themeService = inject(ThemeService);
private toastService = inject(ToastService);

showToast() {
this.toastService.success('Hello from Helix!');
}
}
`

Available Components

Helix provides 28 production-ready components organized by category:

$3

- 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

$3

- 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

$3

- 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

$3

- 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

$3

- 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

Service APIs

$3

Manage application themes and custom brand colors.

Methods:
- setDarkTheme(isDark: boolean) - Set theme mode
- toggleTheme() - Toggle between light and dark
- updateTheme(name: 'light' | 'dark') - Update theme by name
- applyInsurerTheme() - Apply custom brand colors

Computed Signals:
- themeName() - Returns current theme name
- isDarkTheme() - Returns boolean for dark mode
- themeInfo() - 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();
}
}
`

$3

Display temporary notification messages.

Methods:
- success(message: string, options?) - Show success toast
- error(message: string, options?) - Show error toast
- warning(message: string, options?) - Show warning toast
- info(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'
});
}
}
`

$3

Utility service for scroll management and smooth scrolling.

Methods:
- scrollToTop() - Scroll to page top smoothly
- scrollToElement(selector: string) - Scroll to specific element
- disableScroll() - 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
}
}
`

$3

Wrapper service for ngx-translate functionality.

Methods:
- setLanguage(lang: string) - Change application language
- getTranslation(key: string) - Get translation for a key
- instant(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:

English
Français
Español
Deutsch


})
export class LanguageSelectorComponent {
private translationService = inject(TranslationService);

changeLanguage(event: Event) {
const selectedLang = (event.target as HTMLSelectElement).value;
this.translationService.setLanguage(selectedLang);
}
}
`

Exported Types

All component types and enums are exported for type-safe development:

$3

`typescript
import { AlertType, AlertVariant } from 'ps-helix';

const type: AlertType = 'success' | 'error' | 'warning' | 'info';
const variant: AlertVariant = 'solid' | 'outlined' | 'soft';
`

$3

`typescript
import { AvatarSize, AvatarShape } from 'ps-helix';

const size: AvatarSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
const shape: AvatarShape = 'circle' | 'square';
`

$3

`typescript
import { BadgeSize, BadgeVariant } from 'ps-helix';

const size: BadgeSize = 'sm' | 'md' | 'lg';
const variant: BadgeVariant = 'primary' | 'secondary' | 'success' | 'danger' | 'warning' | 'info';
`

$3

`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';
`

$3

`typescript
import { InputSize, InputType } from 'ps-helix';

const size: InputSize = 'small' | 'medium' | 'large';
const type: InputType = 'text' | 'password' | 'email' | 'number' | 'tel' | 'url' | 'search';
`

$3

`typescript
import { ModalSize } from 'ps-helix';

const size: ModalSize = 'small' | 'medium' | 'large' | 'fullscreen';
`

$3

`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';
`

$3

`typescript
import { StepperVariant } from 'ps-helix';

const variant: StepperVariant = 'default' | 'numbered' | 'progress';
`

$3

`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;
}
`

$3

`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';
`

$3

`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.

Theming

$3

Helix provides default theme colors:
- Primary: #0F02C4 (Deep Blue)
- Secondary: #7B3AEC (Purple)

$3

Customize to match your brand identity using the injection token pattern. See the complete guide in THEME.md.

$3

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

$3

`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.

Best Practices

$3

`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';
`

$3

`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
`

$3

`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
}
`

$3

`html









`

$3

`typescript
// ✅ Good: Reactive forms with FormControl
import { FormControl, Validators } from '@angular/forms';

export class MyComponent {
emailControl = new FormControl('', [
Validators.required,
Validators.email
]);
}
`

`html
label="Email"
[formControl]="emailControl"
[required]="true">

`

$3

`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) {
{{ item.name }}
}

})
export class ListComponent {
items = signal([]);
}
`

$3

`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();
});
});
`

Troubleshooting

$3

Problem: Components appear unstyled or broken.

Solution: Ensure you've imported the global stylesheet:

`css
/ In src/styles.css /
@import 'ps-helix/styles.css';
`

$3

Problem: Icons show as empty squares or missing glyphs.

Solution: Verify Phosphor Icons CDN links are in index.html:

`html




`

$3

Problem: Brand colors aren't being used.

Solution:
1. Verify your theme context service implements InsurerContextService
2. Check the provider configuration in main.ts or app.config.ts
3. Ensure you're using valid hex color codes (e.g., #FF0000)
4. Call themeService.applyInsurerTheme() after color changes

See THEME.md for complete theming documentation.

$3

Problem: TypeScript compilation errors with component imports.

Solution:
1. Verify Angular version is 21.0.3 or higher
2. Check tsconfig.json has "strict": true
3. Ensure all peer dependencies are installed
4. Clear node_modules and reinstall:
- Avec pnpm: rm -rf node_modules && pnpm install
- Avec npm: rm -rf node_modules && npm install

$3

Problem: Application feels slow or unresponsive.

Solution:
1. Use OnPush change detection strategy
2. Implement proper signal usage
3. Avoid unnecessary component re-renders
4. Use trackBy functions in @for loops
5. Lazy load routes and components where possible

$3

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

$3

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

Browser Support

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.

Development Scripts

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
`

Contributing

We welcome contributions! To contribute to Helix Design System:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make your changes and commit: git commit -am 'Add new feature'
4. Push to the branch: git push origin feature/my-feature
5. Submit a pull request

$3

- 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

License

MIT License - see LICENSE file for details.

Copyright (c) 2025 PACK Solutions

Resources

- 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