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
- 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
# 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
// 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
// Bad
import { useState } from 'react'
// Good
import { React } from 'uebersicht'
Rule 2: Never call hooks directly inside render
// 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
// 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
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:
pointer-events: none;
Useful macOS Shell Commands
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.
