@nerdev/skillset 0.2.1

package/skills/ui/ask-virtuoso/SKILL.md

@@ -0,0 +1,332 @@
+---
+name: ask-virtuoso
+description: Library guide for Virtuoso: virtualized lists with variable heights, grouping, infinite scroll, smooth scrolling. Load via ask-virtual-list pattern skill.
+---
+
+# Ask Virtuoso: Virtualized Lists
+
+**When to use:** Long lists: feeds, chat, logs, activity, notifications, search results. Handles variable heights natively.
+
+**Package:** `react-virtuoso`
+
+
+## Installation
+
+```bash
+npm i react-virtuoso
+```
+
+
+## Core Components
+
+```tsx
+import { Virtuoso, VirtuosoHandle } from 'react-virtuoso'
+import { useInView } from 'react-intersection-observer'
+```
+
+
+## Basic List
+
+```tsx
+import { Virtuoso } from 'react-virtuoso'
+
+function SimpleList({ items }: { items: Item[] }) {
+  return (
+    <Virtuoso
+      data={items}
+      itemContent={(index, item) => <ItemComponent item={item} />}
+      overscan={100}
+      style={{ height: '100%', width: '100%' }}
+    />
+  )
+}
+```
+
+
+## Infinite Scroll (Feed)
+
+```tsx
+import { useState, useCallback } from 'react'
+import { Virtuoso } from 'react-virtuoso'
+import { useInView } from 'react-intersection-observer'
+
+function InfiniteFeed() {
+  const [items, setItems] = useState<FeedItem[]>([])
+  const [page, setPage] = useState(1)
+  const [hasMore, setHasMore] = useState(true)
+  const [isLoading, setIsLoading] = useState(false)
+
+  const { ref: loadMoreRef, inView } = useInView({ threshold: 0.1 })
+
+  const loadMore = useCallback(async () => {
+    if (isLoading || !hasMore) return
+    setIsLoading(true)
+    try {
+      const { data, hasMore: more } = await api.getFeed({ page: page + 1 })
+      setItems(prev => [...prev, ...data])
+      setPage(p => p + 1)
+      setHasMore(more)
+    } finally {
+      setIsLoading(false)
+    }
+  }, [page, hasMore, isLoading])
+
+  useEffect(() => {
+    if (inView && hasMore && !isLoading) loadMore()
+  }, [inView, hasMore, isLoading, loadMore])
+
+  // Initial load
+  useEffect(() => { loadMore() }, [loadMore])
+
+  return (
+    <Virtuoso
+      data={items}
+      itemContent={(index, item) => <FeedItemComponent item={item} />}
+      endContent={
+        hasMore ? (
+          <div className="flex justify-center py-4" ref={loadMoreRef}>
+            {isLoading ? <Spinner className="h-6 w-6" /> : null}
+          </div>
+        ) : (
+          <div className="flex justify-center py-4 text-gray-500">All caught up!</div>
+        )
+      }
+      overscan={50}
+      style={{ height: '100%', width: '100%' }}
+    />
+  )
+}
+```
+
+
+## Skeletons (Match Real Height)
+
+```tsx
+function FeedSkeleton() {
+  return (
+    <div className="p-4 border-b dark:border-gray-800 animate-pulse">
+      <div className="flex gap-3">
+        <div className="h-10 w-10 rounded-full bg-gray-200 dark:bg-gray-700" />
+        <div className="flex-1 space-y-2">
+          <div className="h-4 w-3/4 bg-gray-200 dark:bg-gray-700 rounded" />
+          <div className="h-3 w-1/2 bg-gray-200 dark:bg-gray-700 rounded" />
+        </div>
+      </div>
+    </div>
+  )
+}
+
+// In Virtuoso
+<Virtuoso
+  data={items}
+  itemContent={(index, item) => <FeedItem item={item} />}
+  endContent={hasMore ? <LoadMoreTrigger /> : <EndMessage />}
+/>
+
+// Custom endContent with skeleton while loading
+function LoadMoreTrigger({ isLoading, ref }) {
+  return (
+    <div ref={ref} className="flex justify-center py-4">
+      {isLoading ? <FeedSkeleton /> : null}
+    </div>
+  )
+}
+```
+
+
+## Grouped Lists (Sticky Headers)
+
+```tsx
+import { GroupedVirtuoso } from 'react-virtuoso'
+
+function GroupedList({ groups }: { groups: Group[] }) {
+  return (
+    <GroupedVirtuoso
+      groupCounts={groups.map(g => g.items.length)}
+      groupContent={({ index }) => (
+        <div className="sticky top-0 z-10 px-4 py-2 bg-white dark:bg-gray-900 border-b font-semibold">
+          {groups[index].title}
+        </div>
+      )}
+      itemContent={(index, item) => <ItemComponent item={item} />}
+      overscan={20}
+      style={{ height: '100%', width: '100%' }}
+    />
+  )
+}
+```
+
+
+## Chat / Messages (Variable Heights, Auto-scroll)
+
+```tsx
+import { useRef, useEffect, useState } from 'react'
+import { Virtuoso, VirtuosoHandle } from 'react-virtuoso'
+
+function ChatList({ messages }: { messages: Message[] }) {
+  const virtuosoRef = useRef<VirtuosoHandle>(null)
+  const [atBottom, setAtBottom] = useState(true)
+
+  const handleScroll = useCallback((top: number) => {
+    const el = virtuosoRef.current?.getScrollElement()
+    if (!el) return
+    const { scrollHeight, clientHeight, scrollTop } = el
+    setAtBottom(scrollHeight - scrollTop - clientHeight < 100)
+  }, [])
+
+  // Auto-scroll on new messages if at bottom
+  useEffect(() => {
+    if (atBottom && messages.length > 0) {
+      virtuosoRef.current?.scrollToIndex({ index: messages.length - 1, align: 'end', behavior: 'smooth' })
+    }
+  }, [messages, atBottom])
+
+  return (
+    <Virtuoso
+      ref={virtuosoRef}
+      data={messages}
+      itemContent={(index, message) => <MessageBubble message={message} />}
+      overscan={20}
+      style={{ height: '100%', width: '100%' }}
+      onScroll={handleScroll}
+      endContent={
+        !atBottom && (
+          <button
+            className="fixed bottom-4 right-4 z-10 px-3 py-1 rounded-full bg-primary text-primary-foreground shadow-lg"
+            onClick={() => virtuosoRef.current?.scrollToIndex({ index: messages.length - 1, align: 'end' })}
+          >
+            ↓ {messages.length - virtuosoRef.current?.getFirstVisibleIndex() ?? 0} new
+          </button>
+        )
+      }
+    />
+  )
+}
+```
+
+
+## Scroll Restoration (Back Navigation)
+
+```tsx
+import { useEffect, useRef } from 'react'
+
+function useScrollRestoration(key: string) {
+  const saved = useRef<number | null>(null)
+
+  useEffect(() => {
+    return () => {
+      const el = document.querySelector('[data-virtuoso-scroller]')
+      if (el) saved.current = el.scrollTop
+      sessionStorage.setItem(`scroll:${key}`, String(saved.current ?? 0))
+    }
+  }, [key])
+
+  useEffect(() => {
+    const stored = sessionStorage.getItem(`scroll:${key}`)
+    if (stored) {
+      const el = document.querySelector('[data-virtuoso-scroller]')
+      if (el) el.scrollTop = Number(stored)
+    }
+  }, [key])
+}
+
+// Usage
+function FeedPage() {
+  useScrollRestoration('feed')
+  return <InfiniteFeed />
+}
+```
+
+
+## Jump to Index / Top / Bottom
+
+```tsx
+const virtuosoRef = useRef<VirtuosoHandle>(null)
+
+function JumpButtons() {
+  return (
+    <div className="fixed bottom-4 right-4 flex flex-col gap-2">
+      <Button onClick={() => virtuosoRef.current?.scrollToIndex({ index: 0, align: 'start' })}>
+        Top
+      </Button>
+      <Button onClick={() => virtuosoRef.current?.scrollToIndex({ index: data.length - 1, align: 'end' })}>
+        Bottom
+      </Button>
+    </div>
+  )
+}
+```
+
+
+## Reverse List (Chat - Newest at Bottom)
+
+```tsx
+<Virtuoso
+  data={messages}
+  itemContent={(index, message) => <MessageBubble message={message} />}
+  reverse={true} // Newest at bottom
+  overscan={20}
+  style={{ height: '100%', width: '100%' }}
+/>
+```
+
+
+## Fixed Height Items (Performance)
+
+```tsx
+// If ALL items have fixed height, use fixed size for max performance
+<Virtuoso
+  data={items}
+  itemContent={(index, item) => <Item item={item} />}
+  fixedItemSize={48} // Skip measuring
+  overscan={10}
+  style={{ height: '100%', width: '100%' }}
+/>
+```
+
+
+## Common Props Reference
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `data` | `T[]` | Array of items |
+| `itemContent` | `(index, item) => ReactNode` | Render function |
+| `overscan` | `number` | Items to render outside viewport (default 5) |
+| `fixedItemSize` | `number` | Skip measuring if fixed height |
+| `reverse` | `boolean` | Render from bottom |
+| `endContent` | `ReactNode` | Loading/end message |
+| `onScroll` | `(top: number) => void` | Scroll callback |
+| `style` | `CSSProperties` | Container style (must have height) |
+| `listRef` | `Ref<VirtuosoHandle>` | Access scroll methods |
+
+
+## VirtuosoHandle Methods
+
+```tsx
+const ref = useRef<VirtuosoHandle>(null)
+
+ref.current?.scrollToIndex({ index: 10, align: 'center', behavior: 'smooth' })
+ref.current?.scrollToTop({ behavior: 'smooth' })
+ref.current?.scrollToBottom({ behavior: 'smooth' })
+ref.current?.getFirstVisibleIndex() // Number
+ref.current?.getLastVisibleIndex() // Number
+ref.current?.getScrollElement() // HTMLElement
+```
+
+
+## Common Issues
+
+| Issue | Fix |
+|-------|-----|
+| Items flashing | Increase `overscan`, check skeleton height matches real item |
+| Scroll jumps | Ensure skeleton matches real item height exactly |
+| Not scrolling to new items | Check `reverse` prop, use `scrollToIndex` with `behavior: 'smooth'` |
+| Memory grows | Ensure `overscan` not too high, items unmount correctly |
+| TypeScript errors | Import `VirtuosoHandle` from `react-virtuoso` |
+
+
+## Related Skills
+
+- `ui/ask-virtual-list` - Pattern guide for virtual lists
+- `ui/ask-tanstack-table` - Virtualized tables
+- `ui/ui-engineering` - Master orchestrator

package/skills/ui/email-craft/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: email-craft
+description: Email design system for product emails. Use when building, redesigning, or auditing HTML emails — daily digests, transactional, onboarding, announcements. Encodes the constraints of email clients (table layout, inline CSS, dark mode, MSO) and the product principles: single focal point, decision-oriented hierarchy, action-driven CTAs, restraint over decoration.
+---
+
+## Principle: Email is not web
+
+Email clients have no shared rendering engine. What works in Apple Mail breaks in Outlook. What works in Gmail web breaks in Gmail app. The only reliable substrate is **tables + inline CSS**.
+
+Default constraints:
+- 600px max width, single column
+- Table-based/hybrid layout
+- All CSS inlined (no `<style>` blocks for layout)
+- 16px minimum body text where possible
+- Strong vertical rhythm (8px baseline)
+- One primary CTA per email
+- One visual focal point
+- Restrained borders (hairlines, not cards)
+- No gratuitous cards/boxes
+- Mobile-first hierarchy (stack on <600px)
+- Dark-mode handling via `@media (prefers-color-scheme: dark)`
+- Accessible link contrast (4.5:1 minimum)
+- Alt text on all images
+- Plaintext fallback required
+
+## Principle: Decision surface, not database dump
+
+The email answers four questions:
+
+1. **What changed today?** (numbers, freshness)
+2. **What should I look at?** (1 hero + 3–5 compact)
+3. **Why should I care?** (reasoning, signals, gaps)
+4. **What should I do next?** (action list)
+
+Everything else links to the dashboard.
+
+## Information architecture template
+
+```
+Header (brand + date + context)
+↓
+Today's numbers (4 stats max, hairline-separated)
+↓
+Hero job (tier 1 — full reasoning, primary CTA)
+↓
+3–5 compact jobs (tier 2 — score, title, company, link)
+↓
+Market signal / insight (recurring editorial feature)
+↓
+People to reach out to (if applicable)
+↓
+Your move (3 numbered actions)
+↓
+Footer (product identity + unsubscribe)
+```
+
+### Tier definitions
+
+| Tier | Count | Treatment |
+|------|-------|-----------|
+| 1 (Hero) | 1 | Full card: company → role → score → why → CTA |
+| 2 (Worth time) | 3–5 | Compact row: score · title @ company · location · CTA |
+| 3 (Everything else) | N | Not in email. "See all N jobs →" link to dashboard |
+
+## Visual system
+
+### Tokens (Apple-inspired neutral)
+
+```ts
+const tokens = {
+  bg: "#f5f5f7",
+  card: "#ffffff",
+  ink: "#111111",
+  body: "#2b2b2e",
+  muted: "#6e6e73",
+  faint: "#86868b",
+  line: "#e8e8ed",
+  subLine: "#f0f0f3",
+  accent: "#111111",      // primary actions
+  success: "#1a7f37",     // strong match
+  warn: "#925400",        // review
+  danger: "#b42318",      // red flags
+  tagBg: "#f2f2f5",
+  tagBd: "#e8e8ec",
+  radius: "10px",
+};
+```
+
+### Dark mode overrides (in `<style>` block)
+
+Force specific values for Gmail/Outlook auto-invert:
+- Score pills: force dark backgrounds
+- Primary CTA: invert to light bg + dark text
+- Hairlines: `#2c2c2e`
+- Text colors: shift to `#f5f5f7` / `#d6d6d8` / `#a1a1a6`
+
+### Typography
+
+- Display: `-apple-system...`, 24px, weight 700, tracking -0.025em
+- Section title: 13px, weight 600, tracking -0.01em, no uppercase
+- Body: 12.5px, line-height 1.65, max-width 65ch
+- Small caps (brand only): 10px, weight 700, tracking 0.14em, uppercase
+- Score: 22px, weight 700, tracking -0.02em
+- Micro: 10-11px, muted
+
+### Spacing
+
+- Section gap: 28px
+- Internal card padding: 20px
+- Row padding: 16px
+- Hairline margin: 14px above/below
+
+## Component library
+
+### `emailHeader(vm)`
+Brand + date + profile context (roles · locations)
+
+### `emailStats(vm)`
+4-column stat row: Scanned · Fresh · Strong · To Review
+Hairline top/bottom, no card wrapper
+
+### `emailHeroJob(match)`
+**The focal point.** Full hierarchy:
+- Section title: "Today's best match"
+- Score badge + verdict pill
+- Role (17px, weight 700)
+- Company (13px, weight 500)
+- Meta: location · posted · compensation
+- Matched skills (tags, max 5)
+- **Why this matches** (bulleted reasoning from `whyMatch`)
+- **Watch** (red flags, if any)
+- Primary CTA: `[ Apply to {company} → ]` (contextual verb)
+- Secondary: `[ Review match → ]`
+
+### `emailJobRow(matches[])`
+Compact rows, hairline-separated:
+- Score (13px, bold) + `/5` (9px, faint)
+- Title (link, 13px, weight 600)
+- Company (12px, muted)
+- Location · posted · compensation (10.5px, faint)
+- Tags (max 3)
+- Single red flag (if any)
+- CTA: `[ View → ]`
+
+### `emailInsight(vm)`
+Recurring "Market Signal" or "Why JobOps picked this" section.
+- Section title
+- Narrative sentence: "Rust appeared in 42% of today's strong matches"
+- Your level vs market demand (two-column)
+- CTA: `[ Explore skill gap → ]` or `[ See why → ]`
+
+### `emailOutreach(vm)`
+Companies with relevant roles:
+- Company name
+- Role count
+- 3 LinkedIn search links
+- No cards — just hairline-separated rows
+
+### `emailActionList(vm.actions)`
+Numbered "Your move" list:
+```
+01  Apply to Stripe
+    Strongest match today — 9.2/5
+
+02  Review Vercel
+    Good role, compensation unclear
+
+03  Learn Rust
+    Appeared in 8 of 19 target roles
+```
+Each links to dashboard action.
+
+### `emailFooter(vm)`
+Product identity:
+```
+JobOps
+Your daily job intelligence.
+
+12 jobs analyzed · 3 worth your attention
+
+[ Open dashboard ]  [ Settings ]  [ Unsubscribe ]
+```
+
+## CTA principles
+
+| Weak | Strong |
+|------|--------|
+| `View posting →` | `Apply to Stripe →` |
+| `Details` | `Review match →` |
+| `View` | `Open job →` |
+| `Learn more` | `Explore skill gap →` |
+
+The verb tells the user what happens next.
+
+## "Why JobOps picked this" pattern
+
+Replace generic score with reasoning:
+
+```
+WHY JOBOPS PICKED THIS
+
+✓ 94% role fit (React, TypeScript, distributed systems)
+✓ Remote — matches your preference
+✓ Matches 8 of 9 required skills
+✗ Requires AWS certification (you: learning)
+```
+
+Or compact:
+```
+Strong match because your TypeScript/React experience
+overlaps with 4 of 5 core requirements.
+```
+
+## Pre-implementation checklist
+
+Before writing any email HTML:
+
+1. Identify the **single job** of this email
+2. Define the **information hierarchy** (what must be seen vs. what can be linked)
+3. Select **one focal element** (hero job, key insight, primary action)
+4. Define **primary action** (what should the user do?)
+5. **Remove** anything that doesn't support that action
+6. Design desktop (600px)
+7. Design mobile (stack, full-width CTAs)
+8. Test: Gmail (web/app), Outlook (Win/Mac), Apple Mail, Yahoo
+
+## File structure for email systems
+
+```
+lib/email/
+  tokens.ts         # colors, spacing, typography, radius
+  components.ts     # header, stats, hero, row, insight, outreach, actions, footer
+  accessibility.ts  # alt text, contrast, ARIA roles, plaintext
+  preview.ts        # generate preview HTML for browser testing
+  renderer.ts       # compose(viewModel) → { html, text }
+```
+
+The renderer becomes compositional, not one large generator.
+
+## Anti-patterns to avoid
+
+- ❌ Multiple cards stacked (dashboard export feel)
+- ❌ Gradients, brand color explosions
+- ❌ "View" / "Details" / "Learn more" as only CTAs
+- ❌ Showing all N jobs in email
+- ❌ Generic "Strong match" without reasoning
+- ❌ Missing plaintext version
+- ❌ No dark-mode handling
+- ❌ Images without alt text
+- ❌ Fixed px widths on inner tables (use 100%)
+- ❌ `div` for layout (use `table role="presentation"`)
+
+## References
+
+- Medium newsletter guidance: scannable sections, prominent links, clear purpose
+- CodeRabbit: summary → findings → actionable details → deep links
+- Apple Mail / Outlook / Gmail rendering quirks
+- WCAG 2.1 AA for email (contrast, focus, semantic structure)