# Building Social Widgets
> Building social widgets for StickerNest's default social experience. Use when the user asks to create feed widgets, chat widgets, notification widgets, profile widgets, friends list, or any social UI that plugs into the social layer. Covers widget-based social UI, Protocol integration, and theming.
- Skill: `majiayu000/building-social-widgets` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/building-social-widgets`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/building-social-widgets/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/building-social-widgets
---
# Building Social Widgets for StickerNest
This skill covers creating the default social widget set that provides the built-in social experience. All social UI is widget-based, making it customizable and replaceable.
## Philosophy
> "The built-in social experience is just a pre-installed widget set using the same Protocol as any custom widget."
- Default widgets prove the API works
- Users can replace/augment with custom widgets
- Everything is themeable via CSS variables
- Widgets connect to public and friends-only feeds
---
## Default Social Widget Set
| Widget ID | Purpose | Feed Type |
|-----------|---------|-----------|
| `social-feed-public` | Global activity feed | Public |
| `social-feed-friends` | Friends-only activity feed | Friends |
| `social-chat` | Canvas chat room | Canvas-scoped |
| `social-notifications` | Notification center | User-scoped |
| `social-profile-card` | User profile display | Per-user |
| `social-friends-list` | Online friends list | User-scoped |
| `social-who-online` | Canvas presence | Canvas-scoped |
| `social-dm-inbox` | Direct messages | User-scoped |
---
## Widget Manifest Template (Social)
```json
{
"id": "social-feed-public",
"name": "Public Feed",
"version": "1.0.0",
"description": "Shows public activity from all users",
"kind": "2d",
"entry": "index.html",
"category": "social",
"tags": ["social", "feed", "activity"],
"author": "StickerNest",
"capabilities": {
"draggable": true,
"resizable": true,
"rotatable": false
},
"defaultSize": {
"width": 320,
"height": 480
},
"permissions": [
"social:read",
"social:subscribe"
],
"inputs": {
"feedType": {
"type": "string",
"description": "Feed type: 'public' or 'friends'",
"default": "public"
},
"limit": {
"type": "number",
"description": "Number of items to show",
"default": 20
}
},
"outputs": {
"activitySelected": {
"type": "object",
"description": "When user clicks an activity"
}
}
}
```
---
## Social Widget HTML Template
```html
Social Feed
```
---
## Social Protocol Messages
### Widget → Host Requests
| Action | Payload | Response |
|--------|---------|----------|
| `social:getFeed` | `{ type, limit, offset }` | `{ activities: [...] }` |
| `social:getProfile` | `{ userId }` | `{ profile: {...} }` |
| `social:follow` | `{ userId }` | `{ success: boolean }` |
| `social:unfollow` | `{ userId }` | `{ success: boolean }` |
| `social:sendMessage` | `{ channelId, content }` | `{ message: {...} }` |
| `social:getMessages` | `{ channelId, limit }` | `{ messages: [...] }` |
| `social:getNotifications` | `{ limit }` | `{ notifications: [...] }` |
| `social:markRead` | `{ notificationId }` | `{ success: boolean }` |
| `social:getOnlineUsers` | `{ canvasId }` | `{ users: [...] }` |
### Host → Widget Events
| Event | Payload | When |
|-------|---------|------|
| `social:feed-update` | `{ activity }` | New activity posted |
| `social:message-new` | `{ message }` | New chat message |
| `social:notification-new` | `{ notification }` | New notification |
| `social:presence-update` | `{ userId, status }` | User online/offline |
| `social:typing` | `{ userId, isTyping }` | Typing indicator |
---
## Chat Widget Example
```html
```
---
## Notification Widget Example
```javascript
class NotificationWidget {
async init() {
await this.loadNotifications();
WidgetAPI.subscribeTo('social:notification-new', (notif) => {
this.addNotification(notif, true);
this.playSound();
this.showBadge();
});
}
async markAsRead(notificationId) {
await WidgetAPI.request('social:markRead', { notificationId });
this.updateNotification(notificationId, { read: true });
}
async markAllRead() {
await WidgetAPI.request('social:markAllRead', {});
this.notifications.forEach(n => n.read = true);
this.render();
}
}
```
---
## Theming Social Widgets
### Required CSS Variables
```css
/* Base widget tokens (inherited from canvas theme) */
--widget-bg
--widget-text
--widget-text-muted
--widget-border
--widget-accent
--widget-item-bg
--widget-item-hover
/* Social-specific tokens */
--social-avatar-size: 40px;
--social-avatar-border: 2px solid var(--widget-accent);
--social-online-color: #22c55e;
--social-offline-color: #6b7280;
--social-unread-bg: rgba(99, 102, 241, 0.1);
--social-typing-color: var(--widget-text-muted);
--social-chat-bubble-self: var(--widget-accent);
--social-chat-bubble-other: var(--widget-item-bg);
```
### Theme Inheritance
```javascript
// Host sends theme tokens on init and updates
WidgetAPI.applyTheme({
'widget-bg': '#1a1a2e',
'widget-text': '#ffffff',
'widget-accent': '#6366f1',
// ...
});
```
---
## Widget Set Registration
```typescript
// src/widgets/builtin/social/index.ts
export const socialWidgetSet = {
id: 'social-default',
name: 'StickerNest Social',
description: 'Default social widgets for feeds, chat, and notifications',
widgets: [
{
id: 'social-feed-public',
path: '/widgets/social/feed-public/',
},
{
id: 'social-feed-friends',
path: '/widgets/social/feed-friends/',
},
{
id: 'social-chat',
path: '/widgets/social/chat/',
},
{
id: 'social-notifications',
path: '/widgets/social/notifications/',
},
{
id: 'social-profile-card',
path: '/widgets/social/profile-card/',
},
{
id: 'social-friends-list',
path: '/widgets/social/friends-list/',
},
{
id: 'social-who-online',
path: '/widgets/social/who-online/',
},
{
id: 'social-dm-inbox',
path: '/widgets/social/dm-inbox/',
},
],
};
```
---
## Testing Social Widgets
```typescript
// tests/social-widgets.spec.ts
import { test, expect } from '@playwright/test';
test.describe('Social Feed Widget', () => {
test('loads public feed', async ({ page }) => {
await page.goto('/canvas/test');
// Add feed widget
await page.click('[data-widget="social-feed-public"]');
// Wait for feed to load
await expect(page.locator('.feed-item')).toBeVisible();
});
test('receives realtime updates', async ({ page }) => {
// Setup feed widget
await page.goto('/canvas/test');
// Post activity from another context
await postTestActivity();
// Verify feed updates
await expect(page.locator('.feed-item').first())
.toContainText('published');
});
});
```
---
## Reference Files
| File | Purpose |
|------|---------|
| `public/test-widgets/activity-feed/` | Existing feed widget |
| `public/test-widgets/chat-room/` | Existing chat widget |
| `public/test-widgets/notification-center/` | Existing notification widget |
| `src/widgets/builtin/social/` | Built-in social widgets |
| `src/runtime/WidgetHost.ts` | Widget sandbox host |
| `src/services/social/` | Social backend services |
---
## Best Practices
1. **Always use Protocol requests** - Never call services directly
2. **Subscribe to realtime events** - Keep UI in sync
3. **Theme with CSS variables** - Inherit from host theme
4. **Handle empty states** - Show helpful messages
5. **Optimistic updates** - Instant feedback before server confirms
6. **Accessible markup** - Proper ARIA labels, keyboard nav
7. **Mobile-friendly** - Touch targets, responsive layout
8. **Error boundaries** - Graceful degradation on failures