bluefly/llm_platform_manager

Professional admin theme for AI/LLM platform management. Extends Gin with AI-specific components, real-time monitoring, and accessibility compliance.

0.1.0 2025-07-27 13:38 UTC

This package is auto-updated.

Last update: 2025-07-29 20:02:46 UTC


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

  1. Copy examples/starter_subtheme to your theme directory
  2. Update my_theme.info.yml with your theme details
  3. Set base theme: llm_platform_manager
  4. 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

๐Ÿ“„ 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