# 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
```bash
# 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
```bash
# 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
```bash
# 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:
```json
"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:
```scss
// 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`