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
• 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

Built-In Templates

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.