net/docs/COMPONENT_LIBRARY.md

COMPONENT LIBRARY: Spark Platform UI Catalog

BLUF: 182 React components in 14 directories. Admin (95 files), Blocks (25 files), UI (18 files).

---

1. Component Organization

frontend/src/components/
├── admin/              # 95 files - Dashboard components
├── analytics/          # 4 files - Analytics widgets
├── assembler/          # 8 files - Article assembly
├── automations/        # 1 file - Workflow automation
├── blocks/             # 25 files - Page builder blocks
├── collections/        # 1 file - Generic collection UI
├── debug/              # 1 file - Debug utilities
├── engine/             # 4 files - Rendering engine
├── factory/            # 9 files - Content Factory
├── intelligence/       # 7 files - Intelligence Library
├── layout/             # 1 file - Layout components
├── providers/          # 1 file - React providers
├── testing/            # 7 files - Test utilities
└── ui/                 # 18 files - Shadcn primitives

---

2. Admin Components

Location: frontend/src/components/admin/

2.1 Intelligence Managers

Component	File	Purpose
AvatarIntelligenceManager	intelligence/AvatarIntelligenceManager.tsx	Avatar CRUD + stats
GeoIntelligenceManager	intelligence/GeoIntelligenceManager.tsx	Map + location CRUD
SpintaxManager	intelligence/SpintaxManager.tsx	Dictionary editor
CartesianManager	intelligence/CartesianManager.tsx	Pattern builder
PatternAnalyzer	intelligence/PatternAnalyzer.tsx	Pattern testing
OfferBlocksManager	intelligence/OfferBlocksManager.tsx	Offer template CRUD
IntelligenceDashboard	intelligence/IntelligenceDashboard.tsx	Module overview

2.2 Factory Components

Component	File	Purpose
KanbanBoard	factory/KanbanBoard.tsx	Drag-drop workflow
ArticleWorkbench	factory/ArticleWorkbench.tsx	Article editing
BulkGrid	factory/BulkGrid.tsx	Multi-select operations
JobsMonitor	factory/JobsMonitor.tsx	Queue status
SendToFactoryButton	factory/SendToFactoryButton.tsx	Factory trigger

2.3 SEO Components

Component	File	Purpose
CampaignWizard	seo/CampaignWizard.tsx	Campaign creation wizard
ArticleList	seo/ArticleList.tsx	Article table
HeadlineGenerator	seo/HeadlineGenerator.tsx	Headline permutation UI
FragmentsManager	seo/FragmentsManager.tsx	Fragment CRUD
ArticleEditor	seo/ArticleEditor.tsx	Single article edit
ArticlePreview	seo/ArticlePreview.tsx	Preview renderer

2.4 Sites Components

Component	File	Purpose
SitesManager	sites/SitesManager.tsx	Site list + actions
SiteEditor	sites/SiteEditor.tsx	Site settings
SiteDashboard	sites/SiteDashboard.tsx	Site overview
PagesList	sites/PagesList.tsx	Page management
NavigationEditor	sites/NavigationEditor.tsx	Menu builder
ThemeSettings	sites/ThemeSettings.tsx	Theme configuration

2.5 Content Components

Component	File	Purpose
PageEditor	content/PageEditor.tsx	Block-based editor
PostEditor	content/PostEditor.tsx	Blog post editor
ContentFactoryDashboard	content/ContentFactoryDashboard.tsx	Factory overview
VisualBlockEditor	content/VisualBlockEditor.tsx	Visual editor

2.6 System Components

Component	File	Purpose
SystemMonitor	system/SystemMonitor.tsx	Health dashboard
SystemStatusBar	system/SystemStatusBar.tsx	Status indicator
SettingsManager	SettingsManager.tsx	Platform settings
LogViewer	system/LogViewer.tsx	Work log viewer
WPImporter	import/WPImporter.tsx	WordPress import
JumpstartWizard	jumpstart/JumpstartWizard.tsx	Quick site setup

2.7 Testing Components

Component	File	Purpose
TestRunner	testing/TestRunner.tsx	Test executor
TestResults	testing/TestResults.tsx	Results display
ConnectionTester	testing/ConnectionTester.tsx	API tests

---

3. Block Components

Location: frontend/src/components/blocks/

Page Builder Blocks

Block	File	Description
HeroBlock	HeroBlock.tsx	Full-width header with CTA
RichTextBlock	RichTextBlock.tsx	SEO-optimized prose
ColumnsBlock	ColumnsBlock.tsx	Multi-column layout
MediaBlock	MediaBlock.tsx	Image/video with caption
StepsBlock	StepsBlock.tsx	Numbered process
QuoteBlock	QuoteBlock.tsx	Testimonial/blockquote
GalleryBlock	GalleryBlock.tsx	Image grid
FAQBlock	FAQBlock.tsx	Accordion with schema.org
PostsBlock	PostsBlock.tsx	Blog listing
FormBlock	FormBlock.tsx	Lead capture form
CTABlock	CTABlock.tsx	Call-to-action
MapBlock	MapBlock.tsx	Embedded map
CardBlock	CardBlock.tsx	Card layout
DividerBlock	DividerBlock.tsx	Section separator
SpacerBlock	SpacerBlock.tsx	Vertical spacing
HeaderBlock	HeaderBlock.tsx	Section header
ListBlock	ListBlock.tsx	Bullet/numbered list
TableBlock	TableBlock.tsx	Data table
CodeBlock	CodeBlock.tsx	Code snippet
EmbedBlock	EmbedBlock.tsx	External embed

Block Renderer

Component	File	Purpose
BlockRenderer	engine/BlockRenderer.tsx	JSON → component mapper
BlockWrapper	engine/BlockWrapper.tsx	Styling container

---

4. UI Components (Shadcn-style)

Location: frontend/src/components/ui/

Form Controls

Component	File	Usage
Button	button.tsx	<Button variant="default">
Input	input.tsx	<Input type="text">
Textarea	textarea.tsx	<Textarea rows={4}>
Select	select.tsx	<Select><SelectItem>
Switch	switch.tsx	<Switch checked={}>
Slider	slider.tsx	<Slider value={}>
Label	label.tsx	<Label htmlFor="">

Layout

Component	File	Usage
Card	card.tsx	<Card><CardHeader>...
Dialog	dialog.tsx	<Dialog><DialogContent>
Sheet	sheet.tsx	<Sheet><SheetContent>
Table	table.tsx	<Table><TableRow>
Tabs	tabs.tsx	<Tabs><TabsContent>
Separator	separator.tsx	<Separator>

Feedback

Component	File	Usage
Toast	toast.tsx	toast({ title, description })
Tooltip	tooltip.tsx	<Tooltip><TooltipContent>
DropdownMenu	dropdown-menu.tsx	<DropdownMenu><DropdownMenuItem>

---

5. Analytics Components

Location: frontend/src/components/analytics/

Component	File	Purpose
MetricsDashboard	MetricsDashboard.tsx	Analytics overview
ChartWidget	ChartWidget.tsx	Data visualization
StatCard	StatCard.tsx	Single metric display

---

6. Engine Components

Location: frontend/src/components/engine/

Component	File	Purpose
BlockRenderer	BlockRenderer.tsx	Renders JSON blocks
PageRenderer	PageRenderer.tsx	Full page rendering
ArticleRenderer	ArticleRenderer.tsx	Article display
PreviewFrame	PreviewFrame.tsx	Preview container

---

7. Automations Components

Location: frontend/src/components/automations/

Component	File	Purpose
AutomationBuilder	AutomationBuilder.tsx	Workflow editor

---

8. Usage Examples

Using Admin Components

import { SitesManager } from '@/components/admin/sites/SitesManager';

export default function SitesPage() {
    return <SitesManager client:load />;
}

Using UI Components

import { Button } from '@/components/ui/button';
import { Card, CardHeader, CardContent } from '@/components/ui/card';

function MyComponent() {
    return (
        <Card>
            <CardHeader>Title</CardHeader>
            <CardContent>
                <Button variant="default">Click</Button>
            </CardContent>
        </Card>
    );
}

Using Blocks

import { BlockRenderer } from '@/components/engine/BlockRenderer';

function PageContent({ blocks }) {
    return <BlockRenderer blocks={blocks} />;
}

---

9. Design System

Colors (Titanium Pro)

Name	Value	Usage
Background	#09090b (zinc-950)	Page background
Primary	#eab308 (yellow-500)	Accent, buttons
Success	#22c55e (green-500)	Positive actions
Accent	#a855f7 (purple-500)	Highlights
Text	#ffffff / #94a3b8	Primary / secondary

Typography

Element	Class
Heading 1	text-4xl font-bold
Heading 2	text-2xl font-semibold
Body	text-base text-slate-300
Small	text-sm text-slate-400

Spacing

Size	Value	Usage
xs	4px	Tight padding
sm	8px	Compact spacing
md	16px	Standard spacing
lg	24px	Section spacing
xl	32px	Large sections

---

10. Component Creation Guidelines

File Structure

// components/admin/MyFeature/MyComponent.tsx

import { useState } from 'react';
import { Button } from '@/components/ui/button';

interface MyComponentProps {
    data: MyType;
    onAction?: () => void;
}

export function MyComponent({ data, onAction }: MyComponentProps) {
    const [state, setState] = useState(false);
    
    return (
        <div className="p-4 bg-zinc-900 rounded-lg">
            {/* Component content */}
        </div>
    );
}

Naming Conventions

Type	Convention	Example
Component	PascalCase	MyComponent.tsx
Hook	camelCase, use-prefix	useMyHook.ts
Utility	camelCase	formatDate.ts
Type	PascalCase	MyComponentProps