skillshare-ui-website-style

Enforce the skillshare design system across the two frontends. $ARGUMENTS is the file or area being worked on.

**Companion skill**: For UX design decisions beyond token/component usage — layout strategy, information hierarchy, interaction patterns, micro-copy, or when designing a new page from scratch — also invoke `/ui-ux-pro-max` for higher-level design guidance. This skill handles *what components and tokens to use*; `/ui-ux-pro-max` handles *how to design the experience*.

The project has **two distinct design systems** sharing semantic color names but with different visual treatments:

| Aspect | UI Dashboard (`ui/`) | Website (`website/`) |
|--------|---------------------|----------------------|
| Stack | React 19 + Vite + Tailwind CSS v4 | Docusaurus 3 + custom CSS |
| Font body | DM Sans | IBM Plex Sans |
| Font heading | DM Sans | Inter |
| Font mono | SFMono-Regular, Menlo | JetBrains Mono |
| Border-radius | Clean: `4px`/`8px`/`12px`/pill | Wobbly: `255px 15px 225px 15px / ...` |
| Shadows | Subtle blur: `0 1px 3px rgba(...)` | Hard offset: `4px 4px 0px 0px #2d2d2d` |
| Background | Flat `#f7f6f3` | Dot grid on `#fdfbf7` |
| Philosophy | skillshare-inspired minimal | Hand-drawn sketchy organic |

---

## UI Dashboard (`ui/`)

Reference implementation: `ui/src/pages/LogPage.tsx`

> For the full human-readable style guide (design philosophy, visual rules, anti-patterns), see `references/STYLE_GUIDE.md` bundled with this skill.

### Design Tokens

Defined in `ui/src/index.css` (@theme) and `ui/src/design.ts`:

```ts
// ui/src/design.ts
import { radius, shadows, palette } from '../design';

radius.sm   // '4px'  — badges, chips
radius.md   // '8px'  — cards, containers
radius.lg   // '12px' — modals, panels
radius.btn  // '9999px' — pill buttons (skillshare style)
radius.full // '9999px' — avatars

shadows.sm / .md / .lg / .hover / .active / .accent / .blue
palette.accent / .info / .success / .warning / .danger
```

### Color Tokens (Tailwind classes)

| Role | Class | When |
|------|-------|------|
| Primary text | `text-pencil` | Titles, names, values |
| Secondary | `text-pencil-light` | Descriptions, timestamps, labels |
| Tertiary | `text-muted-dark` | Hints, placeholders |
| Success | `text-success` | Passed, synced, clean |
| Warning | `text-warning` | Dirty, behind, partial |
| Danger | `text-danger` | Failed, blocked, critical |
| Info / Blue | `text-blue` | Links, info badges, repo URLs |
| Background | `bg-surface` | Cards, inputs |
| Page bg | `bg-paper` | Root background |
| Borders | `border-muted` | Default borders |

**Rule**: Max one accent color per visual region. Don't double up — if a row has a colored dot, skip the colored badge (or vice versa).

### Typography

- Body: DM Sans (via `--font-hand`)
- `font-mono`: timestamps, file paths, durations, code, hashes
- `uppercase tracking-wider`: command names, stat labels
- Size: `text-2xl` > `text-xl` > `text-base` > `text-sm` > `text-xs`

### Page Structure (mandatory order)

Every page follows this layout:

```tsx
<div className="space-y-5 animate-fade-in">
  <PageHeader icon={<Icon />} title="..." subtitle="..." actions={<>...</>} />

  {/* Toolbar: tabs + filters */}
  <div className="flex flex-wrap items-end gap-3">
    <SegmentedControl ... />
    <Select ... />
  </div>

  {/* Summary line or stat cards */}
  <SummaryLine ... />

  {/* Content: table, card list, or card grid */}
  {empty ? <EmptyState ... /> : <ContentArea />}

  {/* Dialogs (rendered at bottom, portal via DialogShell) */}
  <ConfirmDialog ... />
</div>
```

### Component Library

| Component | File | API |
|-----------|------|-----|
| `Card` | `Card.tsx` | `variant="default\|accent\|outlined"`, `hover`, `overflow`, `tilt?`, `padding="none\|sm\|md"` — accent uses thicker border for emphasis (no stripe) |
| `Button` | `Button.tsx` | `variant="primary\|secondary\|danger\|ghost\|link"`, `size="sm\|md\|lg"`, `loading?` |
| `Badge` | `Badge.tsx` | `variant="default\|success\|warning\|danger\|info\|accent"`, `size="sm\|md"`, `dot?` |
| `PageHeader` | `PageHeader.tsx` | `icon`, `title`, `subtitle?`, `actions?`, `backTo?` (styled back arrow) |
| `EmptyState` | `EmptyState.tsx` | `icon` (LucideIcon), `title`, `description?`, `action?` |
| `ConfirmDialog` | `ConfirmDialog.tsx` | `open`, `onConfirm`, `onCancel`, `title`, `message`, `variant="default\|danger"` |
| `DialogShell` | `DialogShell.tsx` | `open`, `onClose`, `maxWidth`, `preventClose` (backdrop blur + dialog-in animation) |
| `Input` | `Input.tsx` | `label?` + standard input props (re-exports Checkbox, Select) |
| `Textarea` | `Input.tsx` | `label?` + standard textarea props |
| `Select` | `Select.tsx` | `label?`, `value`, `onChange`, `options[]`, `size="sm\|md"` |
| `Checkbox` | `Checkbox.tsx` | `label`, `checked`, `onChange`, `indeterminate?`, `disabled?`, `size="sm\|md"` |
| `Spinner` | `Spinner.tsx` | `size="sm\|md\|lg"` — use instead of `<RefreshCw className="animate-spin">` |
| `Tooltip` | `Tooltip.tsx` | `content: string`, `side="top\|bottom"` — portal-based, 200ms delay |
| `SegmentedControl` | `SegmentedControl.tsx` | `value`, `onChange`, `options[]`, `connected?`, `colorFn?` |
| `Pagination` | `Pagination.tsx` | `page`, `totalPages`, `onPageChange`, `rangeText?`, `pageSize?` |
| `StatusBadge` | `StatusBadge.tsx` | Status display |
| `Skeleton` / `PageSkeleton` | `Skeleton.tsx` | Shimmer animation loading states |
| `Toast` / `useToast` | `Toast.tsx` | `toast(message, 'success'\|'error')` — exit animation, progress bar, hover pause |
| `FilterTagInput` | `FilterTagInput.tsx` | Tag-based filter input |
| `IconButton` | `IconButton.tsx` | Icon-only button with `aria-label` |

### Stats Patterns (choose one)

| Pattern | When |
|---------|------|
| **Inline summary text** | 1-3 stats: `"42 ops · 3 errors · last: 2m ago"` |
| **Stat card grid** | Dashboard overview KPIs only |

### Status Patterns (choose one per element)

| Pattern | Markup | When |
|---------|--------|------|
| Colored dot | `w-2 h-2 rounded-full` | Table rows, list items, audit findings/rules |
| Badge | `<Badge variant="...">` | Standalone labels |

### List Patterns

| Pattern | When |
|---------|------|
| Table | Uniform rows, sortable columns, many items |
| Card list (vertical) | Mixed content per row, expandable |
| Card grid | Visual overview, few fields per item |

### Button Variants

| Variant | When |
|---------|------|
| `danger` | Permanent destructive: clear log, empty trash, delete forever |
| `secondary` | Reversible removal: uninstall, remove, restore |
| `ghost` | Cancel, clear filter, reset |
| `primary` | Positive action: save, sync, install, run |

### Separator

Always: `border-dashed border-pencil-light/30` (unified opacity, not `/20` or `/40`)

### Animations

| Context | Value |
|---------|-------|
| Card rotation | `rotate(+-0.15deg)` via `:nth-child(odd/even)` |
| Standalone accent | Max `rotate(+-0.3deg)` |
| Hover | `transition-all duration-150` |
| Page entry | `animate-fade-in` (0.2s ease-out) |

### Keyboard Shortcuts

Registered in `KeyboardShortcutsModal.tsx` and `useGlobalShortcuts.ts`:
- `?` — shortcuts modal
- `/` — focus search
- `g d/s/t/l` — go to Dashboard/Skills/Targets/Log
- `r` — refresh page
- Only fire when no `<input>` / `<textarea>` focused
- Chord timeout: 500ms
- New shortcuts must be added to `KeyboardShortcutsModal`
- Never override browser-native shortcuts (`Cmd+C`, etc.)

### Accessibility

| Concern | Requirement |
|---------|-------------|
| Focus ring | `focus:ring-2 focus:ring-blue/20` |
| Touch target | Min 44x44px |
| Color contrast | 4.5:1 (WCAG AA) |
| Icon buttons | `aria-label` required |
| Modals | `role="dialog"` + `aria-modal="true"` + `useFocusTrap` |
| Select | `role="combobox"` + `aria-expanded` + `role="listbox/option"` |

### Card Overflow Gotcha

`Card.tsx` has `overflow-hidden` by default for border-radius clipping. Absolute-positioned children (dropdowns, tooltips) get clipped. Fix: pass `overflow` prop or add `className="!overflow-visible"`.

### Data Fetching Pattern

Pages use `@tanstack/react-query`:
```tsx
const { data, isPending } = useQuery({
  queryKey: queryKeys.someKey(...),
  queryFn: () => api.someEndpoint(...),
  staleTime: staleTimes.someCategory,
});
```
- Query keys: `ui/src/lib/queryKeys.ts`
- API client: `ui/src/api/client.ts`
- App context: `ui/src/context/AppContext.tsx` provides `{ isProjectMode, projectRoot }`

---

## Website (`website/`)

Docusaurus with hand-drawn "sketchy organic" design in `website/src/css/custom.css`.

### Key Differences from UI Dashboard

- **Wobbly borders**: `border-radius: var(--radius-wobbly)` (not clean px values)
- **Hard shadows**: `4px 4px 0px 0px #2d2d2d` (no blur)
- **Dot grid bg**: `radial-gradient(var(--color-muted) 1px, transparent 1px)` on body
- **Post-it yellow**: `--color-postit: #fff9c4` for highlights
- **Dashed borders everywhere**: navbar, sidebar, tables, pagination, code blocks
- **Button hover**: `transform: translate(2px, 2px)` + shadow shrinks (press-down feel)
- **Links**: wavy underline (`text-decoration-style: wavy`)
- **Dark mode**: amber/gold primary (`#e8a84c`) instead of blue

### CSS Variables

See `website/src/css/custom.css` for full list. Key additions beyond shared palette:
- `--radius-wobbly[-sm|-md|-btn]` — hand-drawn border-radius
- `--color-postit[-dark]` — yellow highlight
- `--shadow-md: 4px 4px 0px 0px #2d2d2d` — hard offset
- `--card-bg`, `--card-border`, `--install-bg` — component-specific

### Docusaurus Classes

- `.button--primary` — green bg, pencil border, hard shadow
- `.button--secondary` — dashed border, no fill
- `.markdown h2` — dashed bottom border
- `.admonition` — wobbly border-radius, left stripe
- `.menu__link--active` — post-it yellow background
- `.target-badge` — wobbly border for target grid
- Code blocks get `box-shadow: 4px 4px 0px 0px #101827`

### Homepage Components (`website/src/pages/index.tsx`)

- `CARD_ROTATIONS` array for random hand-drawn tilt
- `WavyDivider` — SVG dashed wavy line between sections
- `InstallTabs` — tabbed install commands with copy button
- Hero has hand-drawn SVG connector + underline

---

## Anti-Patterns (Both Systems)

| Don't | Do Instead |
|-------|------------|
| Emojis as status icons | Colored dots, badges, or semantic icons |
| Stat cards for 1-3 values | Inline summary text |
| Left-border colored stripes (`border-l-*`) | Colored dots or badges — never use left stripe for emphasis or status |
| Stripe + badge for same status | Pick one per element |
| Mixed separator opacity (`/20`, `/40`) | Always `border-pencil-light/30` |
| `window.confirm()` | `<ConfirmDialog>` component |
| Custom empty-state markup | `<EmptyState>` component |
| Inline styles for design tokens | Use Tailwind classes or `design.ts` exports |
| `overflow-visible` on Card without `overflow` prop | Pass `overflow` prop to Card |
| Dropdowns inside `flex-wrap` title rows | Put dropdowns on their own row |

## Checklist Before Submitting

- [ ] Uses existing components (Card, Badge, Button, etc.) — no custom markup for solved patterns
- [ ] Page follows PageHeader → Toolbar → Summary → Content structure
- [ ] Color tokens from Tailwind (`text-pencil`, not hardcoded `#141312`)
- [ ] Separator is `border-dashed border-pencil-light/30`
- [ ] Empty states use `<EmptyState>`
- [ ] Destructive actions use `<ConfirmDialog>`
- [ ] All icon buttons have `aria-label`
- [ ] New shortcuts registered in `KeyboardShortcutsModal`
- [ ] `animate-fade-in` on root container
- [ ] Dark mode works (check both themes)