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/

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

scripts/setup.sh

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

bottom: 90px; right: 40px;

bottom: 90px; left: 40px;

top: 40px; right: 40px;

top: 40px; left: 40px;

Built-In Templates

clock.jsx

horizon-clock.jsx

pomodoro.jsx

now-playing.jsx

system-stats.jsx

weather-canvas.jsx

git-pulse.jsx

memo-capsule.jsx

volume-knob.jsx

tap-counter.jsx

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()