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