🤖 AI Design Guidelines v3.0

This guide provides explicit instructions for AI agents generating UI components within the GoGrab Space ecosystem.

📚 Core Principles

1. Theme-First Approach: Always use theme variables (var(--ux-*)) and utility classes (.ux-*) instead of hardcoded values.
2. Variant System: Use the centralized variant registry for component styling.
3. Modular Imports: Import only what you need from @theme-system/styles.
4. Semantic HTML: Use proper HTML5 elements enhanced with theme classes.
5. WCAG Compliance: All components must meet WCAG AA contrast standards (4.5:1).

🎨 VARIANT SYSTEM (v3.0 - THE KEY TO EASY STYLING)

The variant system is the easiest way to style components consistently. Use it for all component creation.

Quick Start: TypeScript

import {
  composeVariants,
  ColorVariant,
  SizeVariant,
  EffectVariant,
  ShapeVariant
} from '@theme-system';

// In your component
variant = input<ColorVariant>('primary');
size = input<SizeVariant>('md');
effect = input<EffectVariant>('elevated');
shape = input<ShapeVariant>('rounded');

// Compose final classes
readonly hostClasses = computed(() => composeVariants('button', {
  color: this.variant(),
  size: this.size(),
  effect: this.effect(),
  shape: this.shape()
}));

Quick Start: SCSS Mixins

@use '@theme-system/styles/mixins' as *;

// Create a button with variants
.my-button {
  @include button-variant(
    $color: 'primary',
    $size: 'md',
    $effect: 'elevated',
    $shape: 'rounded'
  );
}

// Create a card with variants
.my-card {
  @include card-variant(
    $color: 'surface',
    $effect: 'elevated',
    $size: 'md'
  );
}

// Create a badge
.my-badge {
  @include badge-variant(
    $color: 'success',
    $size: 'sm',
    $shape: 'pill'
  );
}

Available Variant Types

Common Variant Combinations (Presets)

// CTA Button - High visibility action
.cta-button {
  @include button-variant('primary', 'lg', 'gradient', 'pill');
}

// Subtle Button - Low priority action
.subtle-button {
  @include button-variant('neutral', 'sm', 'ghost', 'rounded');
}

// Destructive Button - Dangerous action
.delete-button {
  @include button-variant('error', 'md', 'flat', 'rounded');
}

// Glass Card - Modern aesthetic
.glass-card {
  @include card-variant('surface', 'glass', 'lg');
}

// Status Badge - Small indicator
.status-badge {
  @include badge-variant('success', 'xs', 'pill');
}

Individual Variant Mixins

For more control, use individual mixins:

// Color variants
@include solid-color-variant('primary');     // Full background
@include tinted-color-variant('primary');    // Light tint (5-20% opacity)
@include outlined-color-variant('primary');  // Border only
@include ghost-color-variant('primary');     // Transparent with hover

// Size variants
@include size-variant('lg', 'button');
@include size-variant('md', 'input');
@include size-variant('sm', 'badge');

// Effect variants
@include effect-variant('elevated');
@include effect-variant('glass');
@include effect-variant('neumorphic');
@include effect-variant('gradient', 'primary');

// Shape variants
@include shape-variant('pill');
@include shape-variant('rounded');

🎨 Design Token Manifest

The source of truth for all design tokens is located at: libs/theme-system/theme-runtime/src/lib/models/ai-design-tokens.const.ts

Reference this file to know:

• Available Spacing Steps (3xs to 3xl)
• Z-Index Layers
• Typography Scales
• Color Semantics

🛠️ styling Strategy

1. SCSS Imports

Do NOT import the monolithic index.scss in component files. Use granular imports:

// ✅ CORRECT
@use '@theme-system/styles/core';
@use '@theme-system/styles/utilities';
@use '@theme-system/styles/components';

// ❌ WRONG
@use '@theme-system/styles'; 

2. Using Variables

Always use the CSS variables defined in core.

.my-component {
  // Colors
  background: var(--ux-surface);
  color: var(--ux-text);
  border: 1px solid var(--ux-border);
  
  // Spacing
  padding: var(--ux-space-md);
  gap: var(--ux-space-sm);
  
  // Typography
  font-family: var(--ux-font-family-base);
}

3. Utility Classes

Prefer utility classes for layout and common patterns.

<div class="ux-flex ux-flex-col ux-gap-md ux-p-lg">
  <h2 class="ux-text-xl ux-font-bold">Title</h2>
  <button class="ux-btn ux-btn-primary">Action</button>
</div>

🧩 Component Patterns

Buttons

Use the standard button classes:

• .ux-btn (Base)
• .ux-btn-primary, .ux-btn-secondary, .ux-btn-ghost, etc. (Variants)
• .ux-btn-sm, .ux-btn-md, .ux-btn-lg (Sizes)

Cards

• .ux-card (Base container)
• .ux-card-header, .ux-card-content, .ux-card-actions (Structure)
• .ux-card-elevated, .ux-card-outlined (Variants)

Inputs

• .ux-input or .ux-form-control

🚀 Creating New Components

When asking to create a new component:

1. Check ai-design-tokens.const.ts for available tokens.
2. Structure the SCSS using the modular imports.
3. Define a "Preview Card" in the theme-showcase if it's a reusable pattern.

⚠️ CRITICAL: Text Color Contrast Rules

The Problem

Using generic --text-color directly on components that may have colored backgrounds results in unreadable text. The text color must be context-aware.

Solution: Semantic Color Variables

ALWAYS use semantic "on-*" variables when text appears on colored backgrounds:

// ❌ WRONG - Generic variable ignores background context
.my-card {
  background: var(--ux-primary);
  color: var(--text-color, #333); // Will be dark on dark background!
}

// ✅ CORRECT - Semantic variable adapts to background
.my-card {
  background: var(--ux-primary);
  color: var(--ux-on-primary); // Calculated for contrast!
}

Text Color Variable Hierarchy

Component Pattern for Colored Cards

.tool-card {
  // Default: surface background
  background: var(--ux-surface);

  // Children use surface-aware colors
  .tool-title {
    color: var(--ux-on-surface, var(--text-color, #333));
  }

  .tool-desc {
    color: var(--ux-text-secondary);
  }

  // Variant: Primary colored background
  &.primary {
    background: var(--ux-primary);
    border-color: var(--ux-primary);

    // CRITICAL: Override child text colors for contrast
    .tool-title {
      color: var(--ux-on-primary);
    }

    .tool-desc {
      color: var(--ux-on-primary);
      opacity: 0.85;
    }
  }
}

Quick Reference: Background → Text Color Mapping

🔄 Theme Designer Integration

The Theme Designer (/space/:id/theme-designer) allows users to visualize these patterns. Ensure any new component supports:

• Dark/Light Mode: By using semantic variables (--ux-surface, --ux-text).
• Theme Colors: By using --ux-primary, etc.

💾 Flash-Persistence Integration

Offline-First Principle

The theme system uses flash-persistence for instant loading and reduced server calls:

1. Read from local storage first (instant, < 1ms)
2. Sync with backend asynchronously (non-blocking)
3. Only call backend when necessary (authenticated users, space-specific data)

Best Practices for Theme State

// ✅ CORRECT - Use flash-persisted signals
import { autoFlashState } from '@storage-system';

readonly activeThemeId = autoFlashState<string | null>('active-theme-id', null, {
  database: 'theme-system',
  collection: 'preferences',
  priority: 'critical',      // Instant sync
  ttl: 90 * 24 * 60 * 60 * 1000, // 90 days
  debounceMs: 50             // Fast persistence
});

// Setting a value automatically persists + syncs cross-tab
setTheme(themeId: string) {
  this.activeThemeId.set(themeId);
  // Done! No manual persistence needed
}

Priority Levels

🛠️ Extended Utility Classes

The theme system includes comprehensive utility classes. Use these for rapid prototyping and consistent styling.

Text & Overflow

<p class="ux-truncate">Single line truncation...</p>
<p class="ux-line-clamp-2">Multi-line truncation with 2 lines...</p>
<p class="ux-line-clamp-3">Multi-line truncation with 3 lines...</p>
<p class="ux-text-nowrap">No wrapping</p>
<p class="ux-break-words">Break words for long content</p>

Cursor & Interaction

<div class="ux-cursor-pointer">Clickable</div>
<div class="ux-cursor-grab">Draggable</div>
<div class="ux-cursor-not-allowed">Disabled</div>
<div class="ux-pointer-events-none">Non-interactive</div>
<div class="ux-select-none">Non-selectable</div>

Transforms

<div class="ux-scale-105 ux-transition">Hover scale</div>
<div class="ux-rotate-45">Rotated</div>
<div class="ux-translate-y-2">Shifted down</div>
<div class="ux-origin-center">Transform origin</div>

Transitions

<div class="ux-transition ux-duration-300 ux-ease-out">Smooth transition</div>
<div class="ux-transition-colors ux-duration-150">Color transition only</div>
<div class="ux-transition-transform ux-duration-200 ux-ease-bounce">Bounce effect</div>

Filters

<div class="ux-blur-sm">Slightly blurred</div>
<div class="ux-backdrop-blur-lg">Glass background</div>
<div class="ux-brightness-110">Brightened</div>
<div class="ux-grayscale">Grayscale image</div>

Scroll Behavior

<div class="ux-scroll-smooth">Smooth scrolling</div>
<div class="ux-overscroll-contain">Contain overscroll</div>
<div class="ux-snap-y">Vertical snap scroll</div>

📁 Key Files Reference

🎯 Quick Decision Guide