widget

# WidgetDesk Skill

## Environment
- Widget directory: `~/Library/Application Support/Übersicht/widgets/`
- Template directory: `~/.claude/skills/widget/templates/` after install, or `.claude/skills/widget/templates/` inside this repo
- Host requirement: Übersicht is installed and available at `/Applications/Übersicht.app` or `/Applications/Uebersicht.app`

## First Step
- When working inside a WidgetDesk repo clone, run `bash scripts/setup.sh` first
- `scripts/setup.sh` is the default entrypoint: it installs missing host dependencies, starts Übersicht, prepares the widget directory, installs the skill, and verifies the result
- Use `bash scripts/setup.sh --check` only when the user explicitly wants a dry-run check or when you are diagnosing an installation problem
- Use `bash ~/.claude/skills/widget/scripts/doctor.sh` only for a fast post-install health check
- After setup, use the installed skill path under `~/.claude/skills/widget/`

## Reference Files
- Reusable implementation patterns: [patterns.md](patterns.md)
- Host management scripts: `scripts/` for setup, starting Übersicht, checking the environment, installing widgets, and listing widgets

---

## Hard Constraints

### 1. Layout
- All widgets should default to `position: fixed`
- Any bottom-aligned widget must keep `bottom >= 90px`
- Default edge spacing is `40px`
- Default width should stay within `140px` to `360px`
- Default height should stay within `48px` to `220px`
- Only exceed these dimensions when the user explicitly asks for a large widget

### 2. Interaction
- Display-only widgets should default to `pointer-events: none`
- Only enable interaction when the widget truly needs clicking, dragging, or text input
- Interactive controls must stay easy to hit
- Avoid complex multi-step desktop interactions by default

### 3. Refresh
- Command-driven widgets should normally refresh between `1000ms` and `600000ms`
- Refresh below `1000ms` only for clocks or clearly time-sensitive UI
- Pure frontend widgets should use `refreshFrequency = false`
- Avoid high-frequency network requests

### 4. Implementation
- Use lowercase kebab-case filenames
- Prefer existing templates and `patterns.md` before inventing new structure
- Prefer built-in macOS capabilities over extra dependencies
- Do not hardcode secrets
- Keep widgets single-file by default unless the user explicitly asks for more complexity

### 5. Visual Style
- Keep the style consistent, restrained, and macOS-like
- Default to dark translucent cards
- Recommended corner radius: `14px` to `20px`
- Prefer `SF Pro Display` and `SF Mono`
- Keep motion short, light, and purposeful
- Do not invent a brand-new visual language for every widget

---

## Operations

```bash
# First-time setup inside this repo
bash scripts/setup.sh
bash scripts/setup.sh --check

# Fast post-install health check
bash ~/.claude/skills/widget/scripts/doctor.sh

# Start Übersicht
bash ~/.claude/skills/widget/scripts/start-uebersicht.sh

# Install or update a template widget
bash ~/.claude/skills/widget/scripts/install-widget.sh \
  ~/.claude/skills/widget/templates/clock.jsx

# List installed widgets
bash ~/.claude/skills/widget/scripts/list-widgets.sh

# Write a brand-new custom widget
cat > ~/Library/Application\ Support/Übersicht/widgets/{name}.jsx << 'EOF'
{widget_code}
EOF

# Hide a widget without deleting it
mv ~/Library/Application\ Support/Übersicht/widgets/{name}.jsx \
   ~/Library/Application\ Support/Übersicht/widgets/{name}.jsx.disabled

# Show a hidden widget
mv ~/Library/Application\ Support/Übersicht/widgets/{name}.jsx.disabled \
   ~/Library/Application\ Support/Übersicht/widgets/{name}.jsx

# Delete a widget
rm ~/Library/Application\ Support/Übersicht/widgets/{name}.jsx
```

Prefer the `scripts/` helpers for host operations. Only write raw widget files directly when creating or replacing actual JSX content.

When the user asks for a standard widget that already exists as a built-in template, do not rewrite it from scratch. Run `scripts/setup.sh` if needed, then install the matching template.
Do not install or copy any widget file until `scripts/setup.sh` has completed successfully and the host app is available.

---

## Widget Format

```jsx
// Optional shell command. stdout is passed into render as output.
export const command = "date '+%H:%M:%S'"

// Refresh frequency in milliseconds. Pure frontend widgets should use false.
export const refreshFrequency = 1000

// CSS positioning. Use position: fixed.
export const className = `
  position: fixed;
  bottom: 90px;
  right: 40px;
`

// render receives { output, error }
export const render = ({ output }) => {
  return <div>{output?.trim()}</div>
}
```

---

## Required Rules

### Rule 1: Never import React from `react`
```jsx
// Bad
import { useState } from 'react'

// Good
import { React } from 'uebersicht'
```

### Rule 2: Never call hooks directly inside `render`
```jsx
// Bad
export const render = () => {
  const [n, setN] = React.useState(0)
}

// Good
const Widget = () => {
  const { useState } = React
  const [n, setN] = useState(0)
  return <div>{n}</div>
}

export const render = () => <Widget />
```

### Rule 3: Never return a function from a state updater
```jsx
// Bad
setRemaining(r => {
  if (r <= 1) return p => p === 'work' ? BREAK : WORK
})

// Good
useEffect(() => {
  if (remaining !== 0) return
  setPhase(p => p === 'work' ? 'break' : 'work')
  setRemaining(p => p === 'work' ? BREAK : WORK)
}, [remaining])
```

---

## Position Cheatsheet

| Position | CSS |
|----------|-----|
| Bottom right | `bottom: 90px; right: 40px;` |
| Bottom left | `bottom: 90px; left: 40px;` |
| Top right | `top: 40px; right: 40px;` |
| Top left | `top: 40px; left: 40px;` |

---

## Built-In Templates

| File | Purpose | Default Position |
|------|---------|------------------|
| `clock.jsx` | Clock and date | Bottom right |
| `horizon-clock.jsx` | Alternate horizontal clock | Bottom right |
| `pomodoro.jsx` | Pomodoro timer | Bottom left |
| `now-playing.jsx` | Apple Music now playing | Bottom center |
| `system-stats.jsx` | CPU, memory, battery | Top right |
| `weather-canvas.jsx` | Animated weather card | Top left |
| `git-pulse.jsx` | Local Git activity heatmap | Top right |
| `memo-capsule.jsx` | Local quick-note capsule | Top center |
| `volume-knob.jsx` | System volume control knob | Right side |
| `tap-counter.jsx` | Simple interactive counter with persisted local state | Bottom right |

Copy a template directly when it already matches the request, or use it as the starting point for a custom widget.

---

## Style Baseline

```css
background: rgba(8, 12, 20, 0.72);
backdrop-filter: blur(24px);
-webkit-backdrop-filter: blur(24px);
border-radius: 18px;
border: 1px solid rgba(255, 255, 255, 0.08);
box-shadow: 0 14px 40px rgba(0, 0, 0, 0.35);
font-family: -apple-system, BlinkMacSystemFont, 'SF Pro Display', sans-serif;
color: rgba(255, 255, 255, 0.92);
```

Add this for display-only widgets:

```css
pointer-events: none;
```

---

## Useful macOS Shell Commands

```bash
date '+%H:%M:%S'
date '+%Y年%-m月%-d日 %A'
pmset -g batt | grep -o '[0-9]*%' | head -1
top -l 1 | grep "CPU usage" | awk '{print $3}'
curl -s "wttr.in/?format=%t+%C"
```

Remember to `.trim()` command output before rendering it.