playbooks

home / skills / petekp / claude-code-setup / tuning-panel

tuning-panel skill

/skills/tuning-panel

This skill creates interactive tuning panels to adjust parameters visually and export changes in an LLM-friendly format for debugging.

npx playbooks add skill petekp/claude-code-setup --skill tuning-panel

Review the files below or copy the command above to add this skill to your agents.

Files (8)
SKILL.md
4.6 KB
---
name: tuning-panel
description: Create visual parameter tuning panels for iterative adjustment of animations, layouts, colors, typography, physics, or any numeric/visual values. Use when the user asks to "create a tuning panel", "add parameter controls", "build a debug panel", "tweak parameters visually", "fine-tune values", "dial in the settings", or "adjust parameters interactively". Also triggers on mentions of "leva", "dat.GUI", or "tweakpane".
---

# Tuning Panel Skill

Create bespoke parameter tuning panels that give users visual control over values they're iterating on. These panels surface all relevant parameters for the current task, enable real-time adjustment, and export tuned values in an LLM-friendly format.

## Core Philosophy

**Err on the side of exhaustive.** When a user is tuning something, surface every parameter that could reasonably affect the outcome. Missing a parameter forces context-switching; having "too many" parameters costs only scroll distance.

**Debug-mode only.** Tuning panels should never appear in production. Use environment checks, build flags, or URL parameters.

**Export changed values only.** LLM exports should show only what was tuned, not all 100+ parameters.

## Platform Selection

| Platform | Library | Reference |
|----------|---------|-----------|
| **React** | Leva (recommended) | [references/react-leva.md](references/react-leva.md) |
| **SwiftUI** | Native controls | [references/swiftui.md](references/swiftui.md) |
| **Vanilla JS** | Tweakpane or dat.GUI | [references/vanilla-js.md](references/vanilla-js.md) |

## Implementation Workflow

### Step 1: Identify All Tunable Parameters

Analyze the code being tuned and extract every parameter that affects the output. See [references/parameter-categories.md](references/parameter-categories.md) for exhaustive lists by domain.

**Common categories:**
- **Animation**: duration, delay, easing, spring physics (stiffness, damping, mass)
- **Layout**: padding, margin, gap, width, height, position
- **Visual**: colors, opacity, shadows, borders, transforms
- **Typography**: font size, line height, letter spacing, weight

**Discovery strategies:**
1. Search for magic numbers (any hardcoded numeric value)
2. Look for style objects (CSS-in-JS, inline styles, theme values)
3. Find animation definitions (Framer Motion, CSS transitions, SwiftUI animations)
4. Identify color values (hex, RGB, HSL anywhere in the file)
5. Check component props with numeric or color defaults
6. Examine CSS custom properties (`--var-name` declarations)

### Step 2: Create Debug-Mode Panel

Wrap the tuning panel so it only appears in development:

- **React**: `process.env.NODE_ENV === 'development'`
- **SwiftUI**: `#if DEBUG`
- **Vanilla JS**: URL parameter `?debug` or environment check

See platform-specific references for code patterns.

### Step 3: Implement Controls

Follow these principles:

1. **Group related parameters** using folders/sections
2. **Use appropriate control types**: sliders for numbers, color pickers for colors, dropdowns for enums
3. **Set sensible min/max/step values** based on the parameter domain
4. **Include presets** for common configurations
5. **Add reset buttons** to return to defaults

### Step 4: Add LLM Export

**Critical requirements:**

1. **Store defaults** at initialization for comparison
2. **Use tolerance for floats** (e.g., `Math.abs(a - b) > 0.001`)
3. **Filter to changed values only** - don't show unchanged parameters
4. **Format for readability** - group by category, use human-readable names

**Export format:**

```markdown
## Tuned Parameters for [ComponentName]

### Changed Values
- Duration: 300 → 450
- Spring Damping: 0.80 → 0.65
- Corner Radius: 12 → 16

### Apply These Values
Update the component at `src/components/Card.tsx:42` with the values above.
```

**Why this matters:**
- A panel might expose 100+ parameters
- Exporting all values wastes tokens and obscures what changed
- The `default → current` format makes diffs scannable

## Additional Resources

### Reference Files
- **[references/react-leva.md](references/react-leva.md)** - Complete React/Leva implementation guide
- **[references/swiftui.md](references/swiftui.md)** - SwiftUI native controls and export patterns
- **[references/vanilla-js.md](references/vanilla-js.md)** - Tweakpane and dat.GUI for plain JS
- **[references/parameter-categories.md](references/parameter-categories.md)** - Exhaustive parameter lists by domain

### Example Files
- **[examples/react-leva-animation.tsx](examples/react-leva-animation.tsx)** - Complete animation tuning panel
- **[examples/export-format.md](examples/export-format.md)** - Full LLM export template

Overview

This skill creates visual parameter tuning panels that surface every numeric or visual value you might iterate on, enabling real-time adjustment and export of only the values that changed. It targets animations, layouts, colors, typography, physics, and any other tunable properties across React, SwiftUI, and vanilla JS. Panels are designed for debug/dev use and produce an LLM-friendly export summarizing changes.

How this skill works

The skill scans the code or UI for tunable parameters (magic numbers, style objects, animation definitions, component props, CSS variables) and generates grouped controls (sliders, color pickers, dropdowns) with sensible ranges and presets. It runs in debug mode only, tracks initial defaults, applies a tolerance for floats, and exports a compact report showing only default → current differences grouped by category.

When to use it

  • When a designer or engineer asks to "create a tuning panel" or "add parameter controls" to speed iteration.
  • When you need a debug-only UI to dial in animation, layout, or visual values without rebuilding code.
  • When fine-tuning physics or motion parameters (spring stiffness, damping, mass) interactively.
  • When you want to share a concise list of changed values with an LLM or teammate for follow-up edits.
  • When using or considering Leva, dat.GUI, or Tweakpane and need an implementation pattern.

Best practices

  • Err on the side of exhaustive: surface every parameter that reasonably affects the result.
  • Only enable panels in debug builds or via an explicit URL flag to avoid shipping to production.
  • Group related controls, choose appropriate control types, and set sensible min/max/step values.
  • Store initial defaults and export only changed values using a numeric tolerance for floats.
  • Provide presets and a reset-to-default action to speed experimentation and recovery.

Example use cases

  • Create a Leva panel in a React animation component to tune durations, easings, and spring values live.
  • Add a debug panel to tweak layout properties (padding, gap, width) while observing responsive behavior.
  • Expose color, opacity, and shadow controls to rapidly iterate visual design without editing CSS.
  • Build a Tweakpane/dat.GUI panel for a canvas-based physics simulation to adjust mass and damping interactively.
  • Export tuned values as a concise default → current report to paste into an issue or instruct an LLM to apply changes.

FAQ

Will the panel ship to production?

No. Panels should be gated to debug builds or visible only when a debug flag or URL parameter is present.

How are exports formatted for an LLM?

Exports list only changed values grouped by category in a default → current format and include human-readable names and location hints.