ui-essentials/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

SSuite is an Angular workspace containing three libraries and a demo application:

• ui-design-system: UI design system with comprehensive SCSS styling, design tokens, and reusable components
• shared-utils: Common utilities and shared services
• ui-essentials: Essential UI components with comprehensive component library (buttons, forms, data-display, navigation, media, feedback, overlays, layout)
• demo-ui-essentials: Demo application showcasing all components with live examples

Development Commands

Building

# Build all libraries
ng build

# Build specific library
ng build ui-design-system
ng build shared-utils  
ng build ui-essentials

# Watch mode for development
ng build --watch --configuration development

Testing

# Run all tests
ng test

# Run tests for specific library
ng test ui-design-system
ng test shared-utils
ng test ui-essentials

Development Server

# Start demo application server
ng serve demo-ui-essentials

# Alternative start command
npm start

Architecture

Workspace Structure

projects/
├── ui-design-system/          - Design system and SCSS architecture
├── shared-utils/       - Common utilities and services  
├── ui-essentials/      - Component library with 8 major categories
└── demo-ui-essentials/ - Demo application with component examples

Library Structure

Each library follows Angular's standard structure:

• src/lib/ - Library source code
• src/public-api.ts - Public exports
• ng-package.json - Library packaging configuration
• package.json - Library metadata

TypeScript Path Mapping

Libraries are mapped in tsconfig.json paths:

"paths": {
  "ui-design-system": ["./dist/ui-design-system"],
  "shared-utils": ["./dist/shared-utils"], 
  "ui-essentials": ["./dist/ui-essentials"]
}

Component Categories (ui-essentials)

The component library is organized into these categories:

• buttons: Button variants and actions
• forms: Input, checkbox, radio, search, switch, autocomplete, date/time pickers, file upload, form fields
• data-display: Tables, lists, cards, chips, badges, avatars
• navigation: App bars, menus, pagination
• media: Image containers, carousels, video players
• feedback: Progress indicators, status badges, theme switchers, empty states, loading spinners, skeleton loaders
• overlays: Modals, drawers, backdrops, overlay containers
• layout: Containers, spacers, grid systems

Design System (ui-design-system)

Contains a comprehensive SCSS architecture:

• Base tokens: Colors, typography, spacing, motion, shadows
• Semantic tokens: High-level design tokens built on base tokens
• Components: Base buttons, cards, forms, navigation
• Layouts: Grid systems, dashboard layouts, responsive templates
• Utilities: Display, layout, spacing utilities
• Patterns: Content, interaction, and layout patterns
• Font faces: Extensive collection of web fonts

Style Import Options:

// Complete design system (includes semantic + base tokens + fonts)
@use 'ui-design-system/src/styles' as ui;

// Tokens only (semantic + base tokens)
@use 'ui-design-system/src/styles/tokens' as tokens;

// Semantic tokens only (includes base tokens)
@use 'ui-design-system/src/styles/semantic' as semantic;

// Base tokens only
@use 'ui-design-system/src/styles/base' as base;

// Components and utilities (import separately to avoid circular dependencies)
@use 'ui-design-system/src/styles/commons' as commons;

Entry points:

• Main: projects/ui-design-system/src/styles/index.scss
• Tokens: projects/ui-design-system/src/styles/tokens.scss
• Semantic: projects/ui-design-system/src/styles/semantic/index.scss

Development Workflow

Component Development

1. New components: Add to appropriate category in ui-essentials/src/lib/components/
2. Export new components: Update category index.ts files
3. Demo components: Create matching demo in demo-ui-essentials/src/app/demos/
4. Routing: Add demo routes to demos.routes.ts

Build Dependencies

• Libraries must be built before being consumed by other projects
• Demo application depends on built library artifacts in dist/
• Use watch mode (ng build --watch) for development iterations

Library Development

• All libraries use Angular 19.2+ with strict TypeScript configuration
• Use ng generate commands within library contexts for scaffolding
• Libraries are publishable to npm after building to dist/ directory
• Testing uses Karma with Jasmine framework
• FontAwesome icons integrated via @fortawesome/angular-fontawesome