Freddy Plugins

A lightweight, dynamic, and feature-rich component library that provides a comprehensive set of UI components, icons, animations, and utilities. Built with Vue 3 and designed to work seamlessly across multiple frameworks including Vue, Angular, React, and vanilla JavaScript applications.

✨ Features

| Environment | URL | Branch | Status | | --------------- | -------------------------------------------------------------------------- | --------- | ---------- | | Development | dev-components.aitronos.com | develop | ✅ Live | | Staging | staging-components.aitronos.com | staging | 🚧 Pending | | Production | components.aitronos.com | main | 🚧 Pending |

• 🚀 Lightweight: Optimized bundle size with tree-shaking support
• 🔄 Dynamic: Auto-updating components with new features and improvements
• 🎨 Rich: 20+ components, 120+ icons, animations, and utilities
• 🌐 Universal: Works with Vue, Angular, React, and any JavaScript framework
• 📱 Responsive: Mobile-first design with modern CSS
• 🎯 TypeScript: Full TypeScript support with type definitions
• 🎭 Web Components: Framework-agnostic custom elements
• 📚 Storybook: Interactive documentation and live demos

📦 Installation

# npm
npm install @aitronos/freddy-plugins

| Environment     | Memory | CPU | Max Instances | Estimated Cost/Month |
| --------------- | ------ | --- | ------------- | -------------------- |
| **Development** | 1Gi    | 1   | 10            | ~$15-25              |
| **Staging**     | 1Gi    | 1   | 10            | ~$15-25              |
| **Production**  | 1Gi    | 1   | 10            | ~$15-25              |
# yarn
yarn add @aitronos/freddy-plugins

# pnpm
pnpm add @aitronos/freddy-plugins

Google Cloud Run Pricing (Switzerland - europe-west6):

• CPU: $0.00002400 per vCPU-second
• Memory: $0.00000250 per GiB-second
• Requests: $0.40 per million requests

🔄 Updating to New Version

Estimated Monthly Costs:

• Development: $15-25 (low traffic, testing)
• Staging: $15-25 (pre-production testing)
• Production: $15-25 (package visualization)
• Total Estimated: $45-75/month To get the latest features, components, and bug fixes, simply update the package:

Additional Costs:

• Artifact Registry: ~$5-10/month (Docker images)
• Cloud Build: ~$5-15/month (CI/CD builds)
• Network Egress: ~$5-10/month (traffic)

# npm - Update to latest version
npm update @aitronos/freddy-plugins

# npm - Install specific version
npm install @aitronos/[email protected]

# yarn - Update to latest version
yarn upgrade @aitronos/freddy-plugins

# yarn - Install specific version
yarn add @aitronos/[email protected]

# pnpm - Update to latest version
pnpm update @aitronos/freddy-plugins

# pnpm - Install specific version
pnpm add @aitronos/[email protected]

🎨 Color System

Multi-Brand Color Architecture

The Storybook implements a sophisticated color system that supports multiple brands (Contentplate, Flowplate, Freddy) with different color modes (light/dark).

Brand Color Palettes

| Brand | Primary Color | Theme Focus | Style | Use Case | | ---------------- | ------------------------------------ | ----------- | ---------------------------- | ----------------------------- | | Contentplate | Purple (#7c3aed) | Light mode | Clean, modern, professional | Content management platforms | | Flowplate | Purple gradient (#6366f1 to #8b5cf6) | Dark mode | Dynamic, flowing, elegant | Workflow automation platforms | | Freddy | Blue (#00aeef) | Dark mode | Technical, precise, reliable | AI and automation tools |

Color Categories

Each brand supports comprehensive color categories:

• Primary Colors: Main brand colors with full scales (50-900)
• Secondary Colors: Supporting colors for accents
• Neutral Colors: Grays and whites for backgrounds
• Semantic Colors: Success, warning, error, info states
• Interactive Colors: Hover, focus, active, disabled states
• Background Colors: Page and component backgrounds
• Text Colors: Typography and content colors
• Border Colors: Dividers and outlines

Color Modes

Each brand supports multiple color modes:

• Light Mode: Traditional light theme with dark text
• Dark Mode: Dark theme with light text and appropriate contrast ...

Color Configuration

The color system uses static configuration files for reliable theming:

Configuration Files:

• src/dist/clean-configuration.json - Main theme configuration
• src/dist/master-configuration.json - Source configuration
• src/dist/complete-configuration.json - Complete configuration

Features:

• Total colors: 50+ per brand/mode
• Interactive states: Included
• Brands: Freddy, Contentplate, Flowplate
• Modes: Default, Light, Dark

Available CSS Variables

The system provides 43+ CSS variables that automatically update based on the selected brand and color mode:

Text Colors:

var(--text-primary)          /* Main text content */
var(--text-secondary)        /* Secondary/subtle text */
var(--text-accent)          /* Accent text */
var(--text-error)           /* Error text */
var(--text-success)         /* Success text */
var(--text-warning)         /* Warning text */
var(--text-info)            /* Info text */
var(--text-link)            /* Link text */
var(--text-inverse)         /* Text on colored backgrounds */

Interactive States:

var(--text-primary-hover)   /* Primary text on hover */
var(--text-primary-active)  /* Primary text when active */
var(--text-primary-focus)   /* Primary text when focused */
var(--text-secondary-hover) /* Secondary text on hover */
var(--text-secondary-focus) /* Secondary text when focused */
var(--text-link-hover)      /* Link text on hover */

Background Colors:

var(--bg-primary)           /* Main background */
var(--bg-secondary)         /* Secondary background */
var(--bg-surface)           /* Surface/card background */

Brand Colors:

var(--primary-color)        /* Primary actions */
var(--error-color)          /* Error states */
var(--success-color)        /* Success states */
var(--warning-color)        /* Warning states */

Usage in Components:

<style scoped>
.my-component {
  background-color: var(--bg-primary);
  color: var(--text-primary);
  border: 2px solid var(--border-color);
}

.my-button:hover {
  color: var(--text-primary-hover);
}
</style>

Development Rules

All components must follow the theme development rules:

• ✅ Use CSS variables - Never hardcode colors
• ✅ Dynamic theming - Colors change based on brand/mode
• ✅ Interactive states - Use hover, active, focus variables
• ✅ Accessibility - Maintain proper contrast ratios

See THEME_DEVELOPMENT_RULES.md for complete guidelines.

# Generate static color configuration
yarn generate:color-config

Generated Files

• dist/colors.json - Static color configuration
• src/dist/clean-configuration.json - Main theme configuration
• src/dist/master-configuration.json - Source configuration

🎨 Brand Switching & Theme Management

Theme Management

The project uses a sophisticated theme management system providing dynamic brand switching and theme management capabilities.

Available Brands

| Brand | Description | Primary Use Case | | ---------------- | ----------------------- | ------------------------------------- | | Freddy | AI and automation tools | Technical interfaces, AI platforms | | Flowplate | Workflow automation | Process management, automation tools | | Contentplate | Content management | CMS platforms, content creation tools |

Available Modes

| Mode | Description | Best For | | ----------- | -------------------------- | ------------------------------------ | | Light | Traditional light theme | Daytime use, professional interfaces | | Dark | Dark theme with light text | Night use, modern interfaces | | Default | Brand-specific default | General use, brand consistency |

Runtime Brand Switching

Using the ThemeSwitcher Component

<template>
  <ThemeSwitcher
    :initial-brand="'freddy'"
    :initial-mode="'light'"
    @theme-changed="handleThemeChange"
    @theme-applied="handleThemeApplied"
  />
</template>

<script setup>
import { ThemeSwitcher } from "@/components";

const handleThemeChange = (brand, mode) => {
  console.log("Theme changed:", { brand, mode });
  // Update your app's theme state
};

const handleThemeApplied = (brand, mode) => {
  console.log("Theme applied:", { brand, mode });
  // Apply the theme to your application
};
</script>

Using the Theme Service

import { useTheme } from "@/composables/useTheme";

// Get theme service
const {
  currentBrandId,
  currentModeId,
  availableBrands,
  availableModes,
  setBrand,
  setMode,
} = useTheme();

// Get available brands and modes
console.log("Available brands:", availableBrands.value);
console.log("Available modes:", availableModes.value);

// Switch brand and mode
setBrand("freddy-public-id");
setMode("light-mode-id");

CSS Custom Properties Integration

The system automatically generates CSS custom properties for each brand and mode:

/* Freddy Light Mode */
.freddy-light {
  --color-primary-500: #00aeef;
  --color-background-50: #ffffff;
  --color-text-900: #111827;
  --color-border-200: #e5e7eb;
}

/* Flowplate Dark Mode */
.flowplate-dark {
  --color-primary-500: #6366f1;
  --color-background-50: #0f172a;
  --color-text-50: #f8fafc;
  --color-border-700: #374151;
}

/* Contentplate Default Mode */
.contentplate-default {
  --color-primary-500: #7c3aed;
  --color-background-50: #ffffff;
  --color-text-900: #111827;
  --color-border-200: #e5e7eb;
}

Component-Level Brand Switching

<template>
  <div :class="`component--${currentBrand}--${currentMode}`">
    <Button :style="{ backgroundColor: primaryColor }" @click="switchBrand">
      Switch to {{ nextBrand }}
    </Button>
  </div>
</template>

<script setup>
import { ref, computed } from "vue";
import { useTheme } from "@/composables/useTheme";

const { setBrand, setMode, availableBrands } = useTheme();

const currentBrand = ref("freddy");
const currentMode = ref("light");

const brands = ["freddy", "flowplate", "contentplate"];
const currentBrandIndex = computed(() => brands.indexOf(currentBrand.value));
const nextBrand = computed(
  () => brands[(currentBrandIndex.value + 1) % brands.length]
);

const switchBrand = () => {
  currentBrand.value = nextBrand.value;

  // Find the brand ID and set it
  const targetBrand = availableBrands.value.find((b) =>
    b.name.toLowerCase().includes(currentBrand.value)
  );
  if (targetBrand) {
    setBrand(targetBrand.id);
  }
};
</script>

Global Theme State Management

The theme system uses Vue's reactivity system for state management. See the ThemeService.ts for the complete implementation.

Usage Examples

Component Integration

<template>
  <div :class="`component--${brand}--${mode}`">
    <button :style="{ backgroundColor: primaryColor }">Primary Button</button>
  </div>
</template>

<script setup>
import { useColorSystem } from "@/config/colors";

const { getColor } = useColorSystem();

const primaryColor = getColor({
  brand: "contentplate",
  mode: "light",
  category: "primary",
  scale: 500,
});
</script>

CSS Custom Properties

.contentplate-light {
  --color-primary-500: #7c3aed;
  --color-background-50: #ffffff;
  --color-text-900: #111827;
}

.flowplate-dark {
  --color-primary-500: #6366f1;
  --color-background-50: #0f172a;
  --color-text-50: #f8fafc;
}

TypeScript Support

import { getColor, validateColorContrast } from "@/config/colors";

// Get a specific color
const primaryColor = getColor({
  brand: "contentplate",
  mode: "light",
  category: "primary",
  scale: 500,
});

// Validate contrast
const result = validateColorContrast("#7c3aed", "#ffffff");
if (!result.isAccessible) {
  console.warn("Low contrast detected");
}

Accessibility Features

• WCAG Compliance: AA standard (4.5:1) and AAA standard (7:1)
• Contrast Validation: Automatic validation of color combinations
• Color Blindness Support: High contrast ratios for all color combinations
• Semantic Colors: Clear distinction between success, warning, error states

Performance Optimizations

• Static Configuration: Reliable theme configuration from JSON files
• Fallback System: Graceful degradation with default themes
• Efficient Processing: Optimized color scale generation
• Minimal Network Requests: Smart caching reduces API calls

📦 Components

✨ No code changes needed! New components and features are automatically available after updating.

Core Components

• Button - Primary action buttons
• InputField - Form input components
• Modal - Dialog and modal components
• Dropdown - Selection components
• Pagination - Navigation components

🎨 Storybook Documentation

Specialized Components

• ChatInterface - Real-time chat components
• ApiInteraction - API testing interface
• LoginRegister - Authentication components
• IconLibrary - Complete icon set (100+ icons) Explore all components, icons, and utilities with interactive demos:

Utility Components

• Spinner - Loading indicators
• ToastMessage - Notification system
• Tooltip - Information overlays
• CodeBlock - Syntax highlighting 📚 View Storybook →

The Storybook provides:

• Live component demos
• Interactive controls and props
• Code examples for each component
• Icon gallery with search functionality
• Animation showcases
• Utility function documentation

🟢 Usage in Vue 3 and Nuxt 3

Installation

npm install @aitronos/freddy-plugins
# or
yarn add @aitronos/freddy-plugins
# or
pnpm add @aitronos/freddy-plugins

Vue 3 Usage

Basic Setup

1. Import CSS - Always import the CSS file first:

import "@aitronos/freddy-plugins/freddy-plugins.css";

2. Register Plugin - In your main.ts:

// main.ts
import { createApp } from 'vue';
import App from './App.vue';
import FreddyPlugin from '@aitronos/freddy-plugins';
import '@aitronos/freddy-plugins/freddy-plugins.css';

const app = createApp(App);
app.use(FreddyPlugin);
app.mount('#app');

Using Components

After registering the plugin, all components and icons are available globally:

<!-- MyComponent.vue -->
<template>
  <div>
    <!-- Use components directly -->
    <BaseButton @click="handleClick">Click Me</BaseButton>
    <InputField v-model="inputValue" placeholder="Enter text" />
    
    <!-- Use icons directly -->
    <IconSearch />
    <IconUser />
    <IconSettings />
    
    <!-- Use other components -->
    <ModalBox v-model="showModal">
      <p>Modal content</p>
    </ModalBox>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const inputValue = ref('');
const showModal = ref(false);

const handleClick = (): void => {
  console.log('Button clicked');
};
</script>

Importing Individual Components (Tree-shaking)

If you prefer to import components individually for better tree-shaking:

<!-- MyComponent.vue -->
<template>
  <div>
    <BaseButton>Click Me</BaseButton>
    <IconSearch />
  </div>
</template>

<script setup lang="ts">
import { BaseButton, IconSearch } from '@aitronos/freddy-plugins';
import '@aitronos/freddy-plugins/freddy-plugins.css';
</script>

Using Directives

<template>
  <div>
    <!-- Use fr-sanitize directive -->
    <div v-fr-sanitize="htmlContent"></div>
    
    <!-- Use icon-style directive -->
    <IconSearch v-icon-style="{ color: 'blue', size: '24px' }" />
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import '@aitronos/freddy-plugins/freddy-plugins.css';

const htmlContent = ref('<p>Safe HTML content</p>');
</script>

Nuxt 3 Usage

Basic Setup

1. Install the package (if not already installed):

npm install @aitronos/freddy-plugins

2. Add CSS to nuxt.config.ts:

// nuxt.config.ts
export default defineNuxtConfig({
  css: [
    '@aitronos/freddy-plugins/freddy-plugins.css'
  ],
  // ... other config
});

3. Create a plugin file - Create plugins/freddy-plugins.client.ts:

// plugins/freddy-plugins.client.ts
export default defineNuxtPlugin(async (nuxtApp) => {
  // Import and register the plugin on client side
  const { default: FreddyPlugin } = await import('@aitronos/freddy-plugins');
  nuxtApp.vueApp.use(FreddyPlugin);
});

Note: The .client.ts suffix ensures the plugin only runs on the client side, which is recommended for SSR compatibility.

Using Components in Nuxt 3

After setting up the plugin, components are available globally:

<!-- pages/index.vue -->
<template>
  <div>
    <BaseButton @click="handleClick">Click Me</BaseButton>
    <InputField v-model="inputValue" placeholder="Enter text" />
    <IconSearch />
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const inputValue = ref('');

const handleClick = (): void => {
  console.log('Button clicked');
};
</script>

Alternative: Import Individual Components

For better tree-shaking and explicit imports:

<!-- pages/about.vue -->
<template>
  <div>
    <BaseButton>Click Me</BaseButton>
    <IconUser />
  </div>
</template>

<script setup lang="ts">
import { BaseButton, IconUser } from '@aitronos/freddy-plugins';
</script>

Using Directives in Nuxt 3

<!-- components/MyComponent.vue -->
<template>
  <div>
    <!-- fr-sanitize directive -->
    <div v-fr-sanitize="sanitizedHtml"></div>
    
    <!-- icon-style directive -->
    <IconSearch v-icon-style="{ color: 'blue' }" />
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const sanitizedHtml = ref('<p>Safe HTML</p>');
</script>

SSR-Safe Plugin Registration

If you need SSR support, you can register the plugin conditionally:

// plugins/freddy-plugins.ts
export default defineNuxtPlugin(async (nuxtApp) => {
  // Only load on client side for SSR compatibility
  if (process.client) {
    const { default: FreddyPlugin } = await import('@aitronos/freddy-plugins');
    nuxtApp.vueApp.use(FreddyPlugin);
  }
});

TypeScript Support

The library includes full TypeScript definitions. Make sure your tsconfig.json includes:

{
  "compilerOptions": {
    "types": ["@aitronos/freddy-plugins"]
  }
}

Available Exports

// Main plugin (default export)
import FreddyPlugin from '@aitronos/freddy-plugins';

// Individual plugins
import { frSanitizePlugin, iconStylePlugin } from '@aitronos/freddy-plugins';

// Directives
import { IconStyleDirective, vFrSanitize } from '@aitronos/freddy-plugins';

// Components
import { BaseButton, InputField, ModalBox } from '@aitronos/freddy-plugins';

// Icons
import { IconSearch, IconUser, IconSettings } from '@aitronos/freddy-plugins';

// Composables
import { useErrorHandler, usePerformance } from '@aitronos/freddy-plugins';

// Helpers
import { sanitizeHTML, formatDate } from '@aitronos/freddy-plugins';

SSL Certificates

• Automatically managed by Google Cloud
• Custom domains require verification in Google Cloud Console

🎯 Available Components

Core Components

Health Checks

• Endpoint: /health - Returns 200 OK
• Auto-restart: Failed instances restart automatically
• Logging: Cloud Run logs available in Google Cloud Console
• freddy-button - Interactive freddy-buttons with multiple variants
• freddy-input-field - Form input fields
• freddy-modal-box - Modal dialogs
• freddy-dropdown - Dropdown menus
• freddy-pagination - Pagination controls
• freddy-tab-list - Tab navigation
• freddy-switch - Toggle switches
• freddy-checkbox - Custom checkboxes
• freddy-spinner - Loading spinners
• freddy-skeleton-loader - Skeleton loading states

Performance Metrics

• Response time: < 200ms average
• Uptime: 99.9% SLA with Cloud Run
• Availability: Multi-zone deployment

Icons (120+ available)

• icon-search - Search icon
• icon-user - User icon
• icon-settings - Settings icon
• icon-home - Home icon
• icon-arrow-left - Arrow left
• icon-arrow-right - Arrow right
• icon-plus - Plus icon
• icon-edit - Edit icon
• icon-delete - Delete icon
• And many more...

Animations

Build Failures:

# Check TypeScript errors
yarn vue-tsc --noEmit
- `freddy-anime-spaceman` - Spaceman animation

### Utilities

- `sanitizeHTML()` - HTML sanitization
- Helper functions for dates, validation, colors
- Vue directives and plugins

## 🎨 Styling

**Important**: Always import the CSS file for proper styling:

```javascript
import "@aitronos/freddy-plugins/dist/freddy-plugins.css";

Deployment Issues:

# Check GitHub Actions logs
# Verify GCP_SA_KEY secret is set
# Ensure Docker build succeeds locally
### Custom Theming

```css
/* Using CSS custom properties */
freddy-button {
  --freddy-button-bg-color: #007bff;
  --freddy-button-text-color: white;
  --freddy-button-border-radius: 8px;
}

icon-search {
  --icon-color: #28a745;
  --icon-size: 24px;
}

Domain Issues:

• Verify DNS propagation (can take 24-48 hours)
• Check custom domain verification in Google Cloud Console
• Ensure CNAME records are correct

📚 Documentation

• Storybook Demo - Interactive component documentation
• GitHub Repository - Source code and issues
• NPM Package - Package information

🤝 Support & Help

• GitHub Issues: Report bugs or request features
• Discussions: Community discussions
• Email: [email protected]

🎉 Hurray!

You're all set! Freddy Plugins provides everything you need to build beautiful, consistent user interfaces across any framework. Start building amazing apps with our comprehensive component library!

Made with ❤️ by the Aitronos team