ui-essentials/CONSUMER_INTEGRATION_GUIDE.md

Angular Library Consumer Integration Guide

🚀 Complete Guide: Creating a New Angular Project with SSuite Libraries

This guide shows you how to create a fresh Angular project and integrate any combination of the 12 SSuite libraries using Git submodules.

---

📋 Prerequisites

• Node.js 18+ and npm
• Angular CLI (npm install -g @angular/cli)
• Git configured with access to git.sky-ai.com

---

🏗️ Step 1: Create New Angular Project

# Create new Angular project
ng new my-awesome-app
cd my-awesome-app

# Create libs directory for submodules
mkdir libs

---

📦 Step 2: Choose Your Libraries

Select libraries based on your needs:

🎨 Foundation (Required for most projects)

• ui-design-system - SCSS design tokens, colors, typography, fonts

🛠️ Essential Components

• ui-essentials - Buttons, forms, tables, cards, navigation, etc.
• shared-utils - Common utilities and shared services

🎯 Specialized Libraries

• auth-client - Authentication guards, services, interceptors
• ui-landing-pages - Hero sections, pricing tables, testimonials
• ui-code-display - Syntax highlighting for code blocks
• ui-accessibility - WCAG compliance tools and utilities
• hcl-studio - Advanced color management system

🎭 Enhancement Libraries

• ui-animations - CSS animation utilities
• ui-backgrounds - Background generators and effects
• ui-font-manager - Advanced font management
• ui-data-utils - Data manipulation utilities

---

⚡ Step 3: Add Libraries as Submodules

IMPORTANT: Always add ui-design-system first, as other libraries depend on it.

Minimal Setup (Design System + Components):

# Add foundation (required)
git submodule add https://git.sky-ai.com/jules/ui-design-system.git libs/ui-design-system

# Add essential components
git submodule add https://git.sky-ai.com/jules/ui-essentials.git libs/ui-essentials
git submodule add https://git.sky-ai.com/jules/shared-utils.git libs/shared-utils

# Initialize submodules
git submodule update --init --recursive

Full-Featured Setup (All Libraries):

# Foundation (required first)
git submodule add https://git.sky-ai.com/jules/ui-design-system.git libs/ui-design-system

# Core libraries
git submodule add https://git.sky-ai.com/jules/ui-essentials.git libs/ui-essentials
git submodule add https://git.sky-ai.com/jules/shared-utils.git libs/shared-utils
git submodule add https://git.sky-ai.com/jules/auth-client.git libs/auth-client

# Specialized libraries
git submodule add https://git.sky-ai.com/jules/ui-landing-pages.git libs/ui-landing-pages
git submodule add https://git.sky-ai.com/jules/ui-code-display.git libs/ui-code-display
git submodule add https://git.sky-ai.com/jules/ui-accessibility.git libs/ui-accessibility
git submodule add https://git.sky-ai.com/jules/hcl-studio.git libs/hcl-studio

# Enhancement libraries
git submodule add https://git.sky-ai.com/jules/ui-animations.git libs/ui-animations
git submodule add https://git.sky-ai.com/jules/ui-backgrounds.git libs/ui-backgrounds
git submodule add https://git.sky-ai.com/jules/ui-font-manager.git libs/ui-font-manager
git submodule add https://git.sky-ai.com/jules/ui-data-utils.git libs/ui-data-utils

# Initialize all submodules
git submodule update --init --recursive

---

🔨 Step 4: Build Libraries

Build libraries in dependency order:

# Build ui-design-system first (required by others)
cd libs/ui-design-system
npm install
npm run build
cd ../..

# Build other libraries
cd libs/ui-essentials && npm install && npm run build && cd ../..
cd libs/shared-utils && npm install && npm run build && cd ../..
cd libs/auth-client && npm install && npm run build && cd ../..

# Continue for other libraries as needed...

📜 Automation Script:

Create build-libs.sh:

#!/bin/bash
echo "🏗️ Building all libraries..."

# Array of libraries in dependency order
LIBS=("ui-design-system" "shared-utils" "ui-essentials" "auth-client" "ui-landing-pages" "ui-code-display" "ui-accessibility" "hcl-studio" "ui-animations" "ui-backgrounds" "ui-font-manager" "ui-data-utils")

for lib in "${LIBS[@]}"; do
  if [ -d "libs/$lib" ]; then
    echo "📦 Building $lib..."
    cd libs/$lib
    npm install
    npm run build
    cd ../..
    echo "✅ $lib built successfully"
  else
    echo "⚠️ Skipping $lib (not found)"
  fi
done

echo "🎉 All libraries built!"

Make executable: chmod +x build-libs.sh && ./build-libs.sh

---

⚙️ Step 5: Configure TypeScript Paths

Update tsconfig.json:

{
  "compilerOptions": {
    "baseUrl": "./",
    "paths": {
      // Foundation (required)
      "ui-design-system": ["./libs/ui-design-system/dist"],
      "ui-design-system/*": ["./libs/ui-design-system/dist/*", "./libs/ui-design-system/src/*"],
      
      // Core libraries
      "ui-essentials": ["./libs/ui-essentials/dist"],
      "ui-essentials/*": ["./libs/ui-essentials/dist/*"],
      "shared-utils": ["./libs/shared-utils/dist"],
      "shared-utils/*": ["./libs/shared-utils/dist/*"],
      "auth-client": ["./libs/auth-client/dist"],
      "auth-client/*": ["./libs/auth-client/dist/*"],
      
      // Specialized libraries
      "ui-landing-pages": ["./libs/ui-landing-pages/dist"],
      "ui-landing-pages/*": ["./libs/ui-landing-pages/dist/*"],
      "ui-code-display": ["./libs/ui-code-display/dist"],
      "ui-code-display/*": ["./libs/ui-code-display/dist/*"],
      "ui-accessibility": ["./libs/ui-accessibility/dist"],
      "ui-accessibility/*": ["./libs/ui-accessibility/dist/*"],
      "hcl-studio": ["./libs/hcl-studio/dist"],
      "hcl-studio/*": ["./libs/hcl-studio/dist/*"],
      
      // Enhancement libraries
      "ui-animations": ["./libs/ui-animations/dist"],
      "ui-animations/*": ["./libs/ui-animations/dist/*"],
      "ui-backgrounds": ["./libs/ui-backgrounds/dist"],
      "ui-backgrounds/*": ["./libs/ui-backgrounds/dist/*"],
      "ui-font-manager": ["./libs/ui-font-manager/dist"],
      "ui-font-manager/*": ["./libs/ui-font-manager/dist/*"],
      "ui-data-utils": ["./libs/ui-data-utils/dist"],
      "ui-data-utils/*": ["./libs/ui-data-utils/dist/*"]
    }
  }
}

Note: The ui-design-system/* includes both dist/* and src/* to support SCSS imports.

---

🎨 Step 6: Import Styles

Option A: Complete Design System

In your src/styles.scss:

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

// Optional: Additional component styles
@use 'ui-animations/src/styles' as animations;
@use 'ui-backgrounds/src/styles' as backgrounds;

Option B: Selective Imports

// Just semantic tokens (most common)
@use 'ui-design-system/src/styles/semantic' as tokens;

// Or just base tokens
@use 'ui-design-system/src/styles/base' as base;

// Add specific libraries
@use 'ui-accessibility/src/lib/utilities/a11y-utilities' as a11y;

---

💻 Step 7: Use Libraries in Your Components

Example Component using multiple libraries:

// src/app/app.component.ts
import { Component } from '@angular/core';
import { ButtonComponent } from 'ui-essentials';
import { AuthService } from 'auth-client';
import { HeroSectionComponent } from 'ui-landing-pages';
import { CodeSnippetComponent } from 'ui-code-display';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [
    ButtonComponent,
    HeroSectionComponent, 
    CodeSnippetComponent
  ],
  template: `
    <div class="app-container">
      <!-- Hero Section -->
      <ui-hero-section
        title="Welcome to My App"
        subtitle="Built with SSuite Libraries"
        [cta]="{ text: 'Get Started', action: 'primary' }">
      </ui-hero-section>

      <!-- Content Section -->
      <main class="content">
        <!-- Buttons from ui-essentials -->
        <ui-button variant="primary" (click)="handleClick()">
          Primary Action
        </ui-button>
        
        <ui-button variant="secondary" [disabled]="!isLoggedIn">
          Secondary Action  
        </ui-button>

        <!-- Code Display -->
        <ui-code-snippet 
          language="typescript"
          [code]="exampleCode">
        </ui-code-snippet>
      </main>
    </div>
  `,
  styles: [`
    .app-container {
      min-height: 100vh;
    }
    .content {
      padding: 2rem;
      max-width: 1200px;
      margin: 0 auto;
    }
  `]
})
export class AppComponent {
  isLoggedIn = false;
  exampleCode = `
import { ButtonComponent } from 'ui-essentials';
import { AuthService } from 'auth-client';

// Your code here...
  `;

  constructor(private auth: AuthService) {
    this.isLoggedIn = this.auth.isAuthenticated();
  }

  handleClick() {
    console.log('Button clicked!');
  }
}

Component with Authentication:

// src/app/protected/dashboard.component.ts
import { Component } from '@angular/core';
import { AuthGuard } from 'auth-client';
import { TableComponent, CardComponent } from 'ui-essentials';
import { StatisticsDisplayComponent } from 'ui-landing-pages';

@Component({
  selector: 'app-dashboard',
  standalone: true,
  imports: [TableComponent, CardComponent, StatisticsDisplayComponent],
  template: `
    <div class="dashboard">
      <!-- Stats Cards -->
      <div class="stats-grid">
        <ui-statistics-display
          [statistics]="stats"
          variant="cards">
        </ui-statistics-display>
      </div>

      <!-- Data Table -->
      <ui-card>
        <ui-enhanced-table
          [data]="userData"
          [columns]="tableColumns"
          [searchable]="true"
          [sortable]="true">
        </ui-enhanced-table>
      </ui-card>
    </div>
  `,
  styles: [`
    .dashboard {
      padding: 1.5rem;
    }
    .stats-grid {
      margin-bottom: 2rem;
    }
  `]
})
export class DashboardComponent {
  stats = [
    { label: 'Users', value: '1,234', change: '+12%' },
    { label: 'Revenue', value: '$45,678', change: '+8%' },
    { label: 'Orders', value: '892', change: '+15%' }
  ];

  userData = [
    { id: 1, name: 'John Doe', email: 'john@example.com', status: 'active' },
    { id: 2, name: 'Jane Smith', email: 'jane@example.com', status: 'inactive' }
  ];

  tableColumns = [
    { key: 'id', label: 'ID' },
    { key: 'name', label: 'Name' },
    { key: 'email', label: 'Email' },
    { key: 'status', label: 'Status' }
  ];
}

---

🔄 Step 8: Library Management

Update a Single Library:

cd libs/ui-essentials
git pull origin main
npm run build
cd ../..

Update All Libraries:

git submodule update --remote
./build-libs.sh  # Rebuild all libraries

Lock Library to Specific Version:

cd libs/ui-essentials
git checkout v1.2.0  # Specific tag
cd ../..
git add libs/ui-essentials
git commit -m "Lock ui-essentials to v1.2.0"

Remove Unused Library:

git submodule deinit libs/ui-backgrounds
git rm libs/ui-backgrounds
git commit -m "Remove ui-backgrounds library"

---

📁 Final Project Structure

my-awesome-app/
├── src/
│   ├── app/
│   │   ├── app.component.ts
│   │   ├── protected/
│   │   │   └── dashboard.component.ts
│   │   └── ...
│   ├── styles.scss
│   └── ...
├── libs/                          # Git submodules
│   ├── ui-design-system/         # Foundation
│   ├── ui-essentials/            # Components
│   ├── auth-client/              # Authentication
│   ├── ui-landing-pages/         # Landing components
│   └── [other-libraries]/
├── package.json
├── tsconfig.json
├── angular.json
├── build-libs.sh                 # Build automation
├── .gitmodules                   # Auto-generated
└── README.md

---

⚡ Quick Start Commands

Minimal Project (Design System + Components):

ng new my-app && cd my-app
mkdir libs
git submodule add https://git.sky-ai.com/jules/ui-design-system.git libs/ui-design-system
git submodule add https://git.sky-ai.com/jules/ui-essentials.git libs/ui-essentials
git submodule update --init --recursive
cd libs/ui-design-system && npm install && npm run build && cd ../..
cd libs/ui-essentials && npm install && npm run build && cd ../..

Add TypeScript paths and styles, then start developing!

---

🎯 Common Patterns

Landing Page Project:

# Essential for marketing sites
git submodule add https://git.sky-ai.com/jules/ui-design-system.git libs/ui-design-system
git submodule add https://git.sky-ai.com/jules/ui-essentials.git libs/ui-essentials
git submodule add https://git.sky-ai.com/jules/ui-landing-pages.git libs/ui-landing-pages
git submodule add https://git.sky-ai.com/jules/ui-animations.git libs/ui-animations

Documentation Site:

# Perfect for docs with code examples
git submodule add https://git.sky-ai.com/jules/ui-design-system.git libs/ui-design-system
git submodule add https://git.sky-ai.com/jules/ui-essentials.git libs/ui-essentials
git submodule add https://git.sky-ai.com/jules/ui-code-display.git libs/ui-code-display
git submodule add https://git.sky-ai.com/jules/ui-accessibility.git libs/ui-accessibility

Enterprise Application:

# Full-featured business app
git submodule add https://git.sky-ai.com/jules/ui-design-system.git libs/ui-design-system
git submodule add https://git.sky-ai.com/jules/ui-essentials.git libs/ui-essentials
git submodule add https://git.sky-ai.com/jules/shared-utils.git libs/shared-utils
git submodule add https://git.sky-ai.com/jules/auth-client.git libs/auth-client
git submodule add https://git.sky-ai.com/jules/ui-data-utils.git libs/ui-data-utils

---

🚀 You're Ready!

Your new Angular project is now set up with the SSuite library ecosystem. You have:

• ✅ Modular architecture - Only include libraries you need
• ✅ Professional design system - Consistent styling and components
• ✅ Independent updates - Update libraries separately
• ✅ Clean imports - TypeScript paths configured
• ✅ Version control - Lock libraries to specific versions
• ✅ Scalable structure - Add/remove libraries as needed

Happy coding! 🎉