README

Overview

The LLM Platform Manager is a sophisticated Drupal base theme designed specifically for AI and machine learning platforms. It extends the Gin admin theme with intelligent, context-aware components that adapt to user needs and provide AI-enhanced workflow optimization.

🎯 Design Philosophy

API-First: All components designed with OpenAPI 3.1 specifications
Builder-First: Single Directory Components (SDC) with Experience Builder compatibility
TDD-Centric: Comprehensive testing framework integration
Accessibility-First: WCAG 2.2 AA compliance throughout
AI-Optional: Smart features that enhance without requiring AI
Compliance-Built-In: Regional compliance support (GDPR, CCPA, HIPAA)

🚀 Key Features

Smart Admin Components

1. Smart Admin Form 🎯

Intelligent forms that adapt based on user context:

Role-Based Field Display: Different fields for admins, editors, managers, developers
Experience-Level Adaptation: Beginner to expert interface complexity
AI-Powered Assistance: Field suggestions, auto-complete, contextual help
Advanced Conditional Logic: Smart field visibility and validation
Progress Tracking: Visual indicators for multi-step forms
Full Accessibility: Keyboard navigation, screen readers, high contrast

2. Contextual Admin Panel 🧠

Adaptive sidebar with intelligent tools:

Context-Aware Tools: Shows relevant actions based on current page
AI-Powered Suggestions: Real-time workflow optimization hints
Smart Quick Actions: Prioritized actions with relevance badges
Resizable Interface: User-customizable panel width
Responsive Behavior: Adapts to mobile/tablet screens
Integrated Help: Contextual documentation and guidance

Enhanced Theme Architecture

Modern SCSS Structure (ITCSS)

scss/
├── 01-abstracts/     # Variables, functions, mixins
├── 02-base/          # Base styles and resets  
├── 03-components/    # UI components
├── 04-layout/        # Layout patterns
├── 05-pages/         # Page-specific styles
└── 06-utilities/     # Utility classes

Modular JavaScript Framework

Smart Form Handling: Real-time validation and conditional logic
AI Integration: Ready for actual AI service connections
Responsive Components: Touch-friendly with mobile optimization
Analytics Ready: Built-in usage tracking and optimization

📦 Installation

Prerequisites

Drupal 10.4+ or 11.x
PHP 8.1+
Gin admin theme
Node.js 18+ (for build tools)

Setup

# 1. Install the theme
composer require drupal/gin
drush theme:enable gin
drush theme:enable llm_platform_manager

# 2. Set as admin theme
drush config:set system.theme admin llm_platform_manager

# 3. Install build dependencies
cd web/themes/custom/llm_platform_manager
npm install

# 4. Build assets
npm run build

# 5. Enable smart features
drush config:set llm_platform_manager.settings ai_features_enabled true

🛠️ Development

Build Process

# Development mode with file watching
npm run dev

# Production build
npm run build

# Lint and format code
npm run lint
npm run format

# Run accessibility tests
npm run test:a11y

# Visual regression tests  
npm run test:visual

Creating Subthemes

Automated Scaffolding

# Use the automated scaffolding tool
cd web/themes/custom/llm_platform_manager/examples/starter_subtheme
php scaffolding/scaffold-subtheme.php my_theme_name --type=admin --with-ai

# Or create manually
cp -r examples/starter_subtheme themes/custom/my_theme_name
cd themes/custom/my_theme_name
# Follow instructions in SUBTHEME_GUIDE.md

Manual Setup

Copy examples/starter_subtheme to your theme directory
Update my_theme.info.yml with your theme details
Set base theme: llm_platform_manager
Follow the comprehensive guide in examples/starter_subtheme/SUBTHEME_GUIDE.md

🧩 Component Usage

Smart Admin Form

In Twig Templates

{{ include('@llm_platform_manager/SmartAdminForm/SmartAdminForm.twig', {
  form_id: 'ai_config_form',
  form_title: 'AI Configuration',
  context: {
    user_role: 'admin',
    experience_level: 'intermediate',
    module_context: 'ai_management'
  },
  ai_assistance: {
    enabled: true,
    suggestions: true,
    auto_complete: false
  },
  field_groups: [
    {
      id: 'basic_settings',
      title: 'Basic Settings',
      required_role: 'any',
      fields: [
        {
          name: 'api_key',
          type: 'password',
          label: 'API Key',
          required: true,
          ai_suggestions: {
            enabled: true,
            source: 'best_practices'
          }
        }
      ]
    }
  ]
}) }}

Via PHP Form API

<?php
function my_module_form($form, FormStateInterface $form_state) {
  $form['#theme'] = 'smart_admin_form';
  $form['#smart_form_config'] = [
    'context' => [
      'user_role' => 'admin',
      'experience_level' => 'intermediate'
    ],
    'ai_assistance' => ['enabled' => TRUE]
  ];
  
  return $form;
}

Contextual Admin Panel

In Page Templates

{{ include('@llm_platform_manager/ContextualAdminPanel/ContextualAdminPanel.twig', {
  current_context: {
    page_type: 'content',
    operation: 'edit',
    entity_type: 'node'
  },
  panel_config: {
    position: 'sidebar',
    auto_hide: false,
    sticky: true
  },
  ai_suggestions: {
    enabled: true,
    update_interval: 30000
  },
  quick_actions: [
    {
      id: 'save_draft',
      label: 'Save Draft',
      url: '/node/1/edit',
      icon: '💾',
      context_relevance: 9
    }
  ]
}) }}

⚙️ Configuration

Theme Settings

Access via Appearance → Settings → LLM Platform Manager

AI & LLM Configuration

Enable AI Features: Toggle AI-enhanced components
Default AI Provider: Choose between Ollama, OpenAI, Anthropic
Real-time Updates: Enable WebSocket connections
AI Analytics: Track AI component usage

Design & Layout

Color Scheme: Auto, Light, Dark, High Contrast
Layout Density: Comfortable, Compact, Spacious
Animation Level: None, Minimal, Standard, Enhanced
Sidebar Behavior: Auto-collapse, Always visible, Overlay

Component Configuration

LLM UI Integration: Enable React component integration
Component Fallbacks: CSS-only fallbacks when React unavailable
Toast Notifications: System event notifications

Advanced Configuration

Enable Smart Forms Globally

// In settings.php
$config['llm_platform_manager.settings']['smart_forms_enabled'] = TRUE;
$config['llm_platform_manager.settings']['ai_suggestions_enabled'] = TRUE;

Custom AI Provider Integration

// Custom AI provider configuration
Drupal.behaviors.customAIProvider = {
  attach: function (context, settings) {
    if (settings.llmPlatformManager?.aiProvider) {
      // Initialize custom AI provider
      CustomAI.init(settings.llmPlatformManager.aiProvider);
    }
  }
};

🎨 Customization

CSS Custom Properties

The theme uses CSS custom properties for easy customization:

:root {
  --llm-primary-color: #2563eb;
  --llm-secondary-color: #64748b;
  --llm-success-color: #10b981;
  --llm-warning-color: #f59e0b;
  --llm-error-color: #ef4444;
  --llm-bg-color: #ffffff;
  --llm-surface-color: #f8fafc;
  --llm-border-color: #e2e8f0;
  --llm-text-color: #0f172a;
  --llm-text-muted: #64748b;
  --llm-focus-color: #3b82f6;
}

Dark Mode Support

@media (prefers-color-scheme: dark) {
  :root {
    --llm-bg-color: #1e293b;
    --llm-surface-color: #334155;
    --llm-border-color: #475569;
    --llm-text-color: #f1f5f9;
    --llm-text-muted: #94a3b8;
  }
}

Custom Component Styling

// Override smart form styling
.smart-admin-form {
  &--my-custom-variant {
    border-left: 4px solid var(--my-brand-color);
    
    .form-field__input {
      border-radius: 8px;
    }
  }
}

🧪 Testing

Unit Tests

# Run all tests
npm run test

# Run specific test suites
npm run test:forms
npm run test:panels
npm run test:ai-components

Accessibility Testing

# Pa11y accessibility testing
npm run test:a11y

# Axe-core integration tests
npm run test:axe

# Keyboard navigation tests
npm run test:keyboard

Visual Regression Testing

# BackstopJS visual regression tests
npm run test:visual

# Generate new reference images
npm run test:visual:reference

# Compare against reference
npm run test:visual:test

Performance Testing

# Lighthouse performance audits
npm run test:performance

# Bundle size analysis
npm run analyze:bundle

🔌 API Integration

OpenAPI Specifications

The theme includes complete OpenAPI 3.1 specifications:

Smart Admin Form API: /components/SmartAdminForm/SmartAdminForm.openapi.yml
Contextual Panel API: /components/ContextualAdminPanel/ContextualAdminPanel.openapi.yml

REST Endpoints

# Get form configuration
GET /api/v1/theme/admin/forms/{form_id}/config

# Update panel preferences  
PUT /api/v1/theme/admin/panel/preferences

# Get AI suggestions
GET /api/v1/theme/admin/ai/suggestions?context={page_type}

# Submit feedback
POST /api/v1/theme/admin/ai/feedback

JavaScript API

// Access smart form instance
const smartForm = document.querySelector('.smart-admin-form')._smartFormInstance;

// Request AI suggestions
smartForm.requestFieldSuggestion('api_key');

// Update conditional fields
smartForm.updateConditionalFields();

// Access contextual panel
const panel = document.querySelector('.contextual-admin-panel')._contextualAdminPanel;

// Load AI suggestions
panel.loadAISuggestions();

// Resize panel
panel.resizePanel(400);

🌐 Accessibility

WCAG 2.2 AA Compliance

Keyboard Navigation: Full keyboard accessibility
Screen Reader Support: Comprehensive ARIA labels and live regions
Color Contrast: Minimum 4.5:1 contrast ratios
Focus Management: Visible focus indicators
Reduced Motion: Respects user motion preferences
High Contrast: System high contrast mode support

Accessibility Features

Skip Links: Jump to main content
Live Regions: Dynamic content announcements
Focus Trapping: Modal and panel focus management
Semantic HTML: Proper heading hierarchy and landmarks
Alternative Text: Meaningful descriptions for icons and images

🌍 Internationalization

Translation Support

# Extract translatable strings
drush locale:check

# Import translations
drush locale:import [langcode] translations.po

# Export translations
drush locale:export [langcode] --types=customized

RTL Support

The theme includes comprehensive right-to-left language support:

[dir="rtl"] {
  .smart-admin-form {
    border-left: none;
    border-right: 4px solid var(--llm-primary-color);
  }
}

🔧 Troubleshooting

Common Issues

Smart Forms Not Loading

# Check if libraries are loaded
drush cache:rebuild
npm run build

# Verify JavaScript console for errors
# Ensure 'once' library is available

AI Features Not Working

# Verify AI features are enabled
drush config:get llm_platform_manager.settings ai_features_enabled

# Check WebSocket connections
# Review browser network tab for failed requests

Style Issues

# Rebuild SCSS
npm run build:css

# Clear Drupal caches
drush cache:rebuild

# Check for CSS compilation errors
npm run lint:css

Debug Mode

// Enable debug mode in settings.php
$config['llm_platform_manager.settings']['debug_mode'] = TRUE;

📚 Documentation

Additional Resources

Component API Documentation: /docs/api/
Accessibility Guide: /docs/accessibility.md
Performance Guide: /docs/performance.md
Contribution Guidelines: /docs/contributing.md
Subtheme Development: /examples/starter_subtheme/SUBTHEME_GUIDE.md

Support

Issue Tracker: GitHub Issues
Documentation: Theme Documentation
Community: Drupal Slack #llm-platform

📄 License

This theme is licensed under the GPL-2.0+ license. See LICENSE.txt for details.

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines on:

Code standards and formatting
Testing requirements
Pull request process
Accessibility requirements
Documentation standards

🏗️ Architecture

Component Structure

components/
├── SmartAdminForm/
│   ├── SmartAdminForm.component.yml    # SDC metadata
│   ├── SmartAdminForm.twig            # Template
│   ├── SmartAdminForm.scss            # Styles
│   └── SmartAdminForm.stories.js      # Storybook stories
└── ContextualAdminPanel/
    ├── ContextualAdminPanel.component.yml
    ├── ContextualAdminPanel.twig
    ├── ContextualAdminPanel.scss
    └── ContextualAdminPanel.stories.js

Library Dependencies

llm_platform_manager/global
├── core (base functionality)
├── components (UI components)
├── smart-forms (intelligent forms)
├── ai-assistance (AI features)
└── admin (admin enhancements)

Built with ❤️ for the Drupal community and AI innovation

bluefly / llm_platform_manager

Maintainers

Details