WidgetDesk Skill

Environment

• - Widget directory: INLINECODE0
• 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 INLINECODE4

First Step

• - When working inside a WidgetDesk repo clone, run bash scripts/setup.sh first
• INLINECODE6 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 INLINECODE9

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 INLINECODE11
• Any bottom-aligned widget must keep INLINECODE12
• Default edge spacing is INLINECODE13
• Default width should stay within 140px to INLINECODE15
• Default height should stay within 48px to INLINECODE17
• Only exceed these dimensions when the user explicitly asks for a large widget

2. Interaction

• - Display-only widgets should default to INLINECODE18
• 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 INLINECODE20
• Refresh below 1000ms only for clocks or clearly time-sensitive UI
• Pure frontend widgets should use INLINECODE22
• 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 INLINECODE25
• Prefer SF Pro Display and INLINECODE27
• Keep motion short, light, and purposeful
• Do not invent a brand-new visual language for every widget

Operations

CODEBLOCK0

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

CODEBLOCK1

Required Rules

Rule 1: Never import React from react

Rule 2: Never call hooks directly inside render

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

CODEBLOCK5

Add this for display-only widgets:

CODEBLOCK6

Useful macOS Shell Commands

CODEBLOCK7

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