Core Concepts

Sharing & Context Saving

Share your designs and save context to improve AI model accuracy. The sharing system uses the MCP API with a fallback to the Phorm share form.

Why Save Context?

When you share a design with context, the AI learns from your intent, style choices, and feedback. This improves future suggestions and generates more relevant designs that match your preferences.

Sharing Architecture

How the dual-API sharing system works

┌─────────────────────────────────────────────────────────────────────┐
│                        SHARING FLOW                                  │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  User clicks "Share" → ShareDialog opens                             │
│                ↓                                                     │
│  ┌────────────────────────────────────────────────────────────┐     │
│  │  1. PRIMARY: MCP API                                        │     │
│  │     POST https://docs.platphormnews.com/api/docs/api/mcp    │     │
│  │     - Design data (elements, canvas settings)               │     │
│  │     - Context for model accuracy                            │     │
│  │     - Metadata (author, tags, timestamp)                    │     │
│  └───────────────────┬────────────────────────────────────────┘     │
│                      │                                               │
│         Success? ────┼──── Yes → Return share URL ✓                 │
│                      │                                               │
│                     No (timeout/error)                               │
│                      ↓                                               │
│  ┌────────────────────────────────────────────────────────────┐     │
│  │  2. FALLBACK: Phorm Share Form                              │     │
│  │     https://phorm.platphormnews.com/share                   │     │
│  │     - Opens in modal or new tab                             │     │
│  │     - Pre-filled with design data                           │     │
│  │     - User completes submission manually                    │     │
│  └────────────────────────────────────────────────────────────┘     │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

Share Dialog

The main interface for sharing designs

┌──────────────────────────────────────────┐
│ Share Design                        [X]  │
├──────────────────────────────────────────┤
│ [MCP API] [Direct Link] [Embed Code]     │  ← Tabs
├──────────────────────────────────────────┤
│                                          │
│ Design Name                              │
│ ┌──────────────────────────────────────┐ │
│ │ My Awesome Design                    │ │
│ └──────────────────────────────────────┘ │
│                                          │
│ Description                              │
│ ┌──────────────────────────────────────┐ │
│ │ Landing page hero section for...     │ │
│ └──────────────────────────────────────┘ │
│                                          │
│ Context for AI (improves accuracy)       │
│ ┌──────────────────────────────────────┐ │
│ │ • Marketing campaign for tech startup│ │
│ │ • Modern, clean aesthetic            │ │
│ │ • Target: developers                 │ │
│ └──────────────────────────────────────┘ │
│                                          │
│ Tags                                     │
│ [marketing] [hero] [landing] [+]         │
│                                          │
│ Visibility                               │
│ ○ Public  ● Private  ○ Team Only         │
│                                          │
│ ┌────────────────────────────────────┐   │
│ │        Share to MCP API            │   │  ← Primary
│ └────────────────────────────────────┘   │
│                                          │
│ ─────────── or ───────────               │
│                                          │
│ Share via phorm.platphormnews.com →      │  ← Fallback
└──────────────────────────────────────────┘

Primary: MCP API Integration

Share via docs.platphormnews.com/api/docs/api/mcp

// POST https://docs.platphormnews.com/api/docs/api/mcp

interface MCPShareRequest {
  type: "design_share"
  
  design: {
    id: string
    name: string
    description?: string
    elements: DesignElement[]
    canvas: {
      width: number
      height: number
      background: string
    }
    svgContent: string  // Rendered SVG
  }
  
  context: {
    // Design intent - what the user was trying to create
    intent: string
    
    // Style notes - color choices, typography decisions
    styleNotes?: string
    
    // Tags for categorization
    tags: string[]
    
    // Use case classification
    useCase: "marketing" | "social" | "documentation" | 
             "presentation" | "ui" | "illustration" | "other"
    
    // AI interaction history (for learning)
    aiInteractions?: {
      suggestionId: string
      type: "layout" | "color" | "typography" | "content"
      status: "applied" | "rejected" | "modified"
      feedback?: string
    }[]
  }
  
  metadata: {
    author?: string
    source: "platphorm-design"
    version: string
    timestamp: string
    visibility: "public" | "private" | "team"
  }
}

Fallback: Phorm Share Form

When MCP API fails, use phorm.platphormnews.com

// Redirect to Phorm share form with pre-filled data
function openPhormFallback(design: Design, context: ShareContext) {
  const params = new URLSearchParams({
    // Design info
    name: design.name,
    description: design.description || '',
    
    // Pre-serialized design data
    data: btoa(JSON.stringify({
      elements: design.elements,
      canvas: design.canvas
    })),
    
    // Context
    intent: context.intent,
    tags: context.tags.join(','),
    useCase: context.useCase,
    
    // Return URL for callback
    callback: window.location.href,
    source: 'platphorm-design'
  })
  
  window.open(
    `https://phorm.platphormnews.com/share?${params}`,
    '_blank',
    'width=600,height=800'
  )
}

Context Data for Model Accuracy

What context to collect and why it matters

interface DesignContext {
  // What the user was trying to create
  // Helps AI understand creative goals
  intent: string
  // Example: "Hero section for SaaS landing page"

  // Style decisions and rationale
  // Helps AI learn aesthetic preferences
  styleNotes?: string
  // Example: "Minimalist, tech-forward, blue accent colors"

  // Categorization for clustering similar designs
  useCase: "marketing" | "social" | "documentation" | 
           "presentation" | "ui" | "illustration" | "other"

  // Searchable/filterable tags
  tags: string[]
  // Example: ["hero", "landing", "saas", "dark-mode"]

  // AI interaction feedback - most valuable for learning!
  aiInteractions?: {
    // Which suggestion was shown
    suggestionId: string
    
    // What type of suggestion
    type: "layout" | "color" | "typography" | "content"
    
    // User's response
    status: "applied" | "rejected" | "modified"
    
    // Optional detailed feedback
    feedback?: string
    // Example: "Good color but too bright"
  }[]

  // Element roles for semantic understanding
  semanticRelationships?: {
    elementId: string
    role: "heading" | "subheading" | "body" | "cta" | 
          "decoration" | "logo" | "image" | "icon"
    relatedTo?: string[]  // IDs of related elements
  }[]
}

// This data helps the AI:
// 1. Learn user preferences over time
// 2. Understand what "good" looks like for specific use cases
// 3. Improve suggestion relevance
// 4. Generate better initial designs

useShare Hook

React hook for sharing functionality

import { useShare } from '@/hooks/use-share'

function ShareButton() {
  const {
    share,           // Main share function
    isSharing,       // Loading state
    shareResult,     // Last share result
    shareError,      // Last error
    usedFallback,    // Whether fallback was used
    retryCount,      // Number of retries attempted
    copyShareUrl,    // Copy URL to clipboard
    getEmbedCode,    // Get embed code
  } = useShare()

  const handleShare = async () => {
    const result = await share({
      design: currentDesign,
      context: {
        intent: "Marketing hero section",
        useCase: "marketing",
        tags: ["hero", "landing"],
        aiInteractions: getAIHistory()
      },
      visibility: "public"
    })

    if (result.success) {
      toast.success(`Shared! ${result.shareUrl}`)
    }
  }

  return (
    <div>
      <Button onClick={handleShare} disabled={isSharing}>
        {isSharing ? 'Sharing...' : 'Share'}
      </Button>
      
      {shareResult && (
        <div className="mt-2">
          <p>Shared via: {shareResult.method}</p>
          <Button variant="ghost" onClick={() => copyShareUrl()}>
            Copy Link
          </Button>
        </div>
      )}
      
      {usedFallback && (
        <p className="text-sm text-muted-foreground">
          Shared via fallback (Phorm)
        </p>
      )}
    </div>
  )
}

Retrieving Shared Designs

Load designs from share URLs

// GET https://docs.platphormnews.com/api/docs/api/mcp/share/:shareId

const response = await fetch(
  'https://docs.platphormnews.com/api/docs/api/mcp/share/share_abc123'
)

const sharedDesign = await response.json()
// {
//   shareId: "share_abc123",
//   design: {
//     name: "Marketing Hero",
//     elements: [...],
//     canvas: { width: 1200, height: 630, ... }
//   },
//   context: {
//     intent: "Marketing hero section",
//     useCase: "marketing",
//     tags: ["hero", "landing"]
//   },
//   metadata: {
//     author: "designer@example.com",
//     createdAt: "2024-01-15T10:30:00Z",
//     visibility: "public"
//   }
// }

// Import into editor
const importSharedDesign = (shareId: string) => {
  router.push(`/?import=${shareId}`)
}

Best Practices

Tips for effective sharing and context saving

Provide Detailed Intent

Be specific about what you were trying to create. Instead of "a button", say "primary CTA button for SaaS pricing page".

Include AI Feedback

Always submit AI interaction history. This is the most valuable data for improving suggestions.

Use Meaningful Tags

Tags help categorize designs and improve search. Use consistent, descriptive tags across your designs.

Set Appropriate Visibility

Use public for portfolio pieces, private for client work, and team for collaborative projects.

Sharing & Context Saving

Provide Detailed Intent

Include AI Feedback

Use Meaningful Tags

Set Appropriate Visibility

Related Documentation