# Parameter Design

> Parameter Design is an Agent Skill for design published in the dylanroscover/Embody repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

MUST READ before creating or designing custom parameters on any COMP: pages, styles, ranges, help text, naming, ParGroup gotchas.

- Skill name: `parameter-design`
- Category: [Design](https://www.openparable.com/skill/design/1)
- Source: https://github.com/dylanroscover/Embody/blob/HEAD/.claude/skills/parameter-design/SKILL.md
- Repository: dylanroscover/Embody (140 GitHub stars when collected)

## SKILL.md

<!-- Generated by Embody/Envoy - Do not remove this comment -->

# Parameter Design

## Help Text

Every custom parameter MUST have `help` text set via `par.help = "..."`. Help text appears as a tooltip when users hover the parameter name in the dialog. Describe what the parameter controls and what its values mean.

- Good: `"Maximum number of rows displayed in the manager list. Set to 0 for unlimited."`
- Bad: `"Max rows"` (just restates the label)
- Unacceptable: no help text at all

In TDN files, include `"help": "..."` in the parameter definition. Embody exports and imports help text automatically.

## Section Breaks

Use `par.startSection = True` on the first parameter of each logical group. This draws a horizontal separator line above the parameter, visually grouping related controls.

In TDN: `"startSection": true` in the parameter definition.

## Parameter Ordering

Parameters appear in the order they are appended. Keep related parameters together and maintain a logical flow within each page:

1. Primary controls first (what users interact with most)
2. Secondary/advanced settings after
3. Read-only status/info parameters last

If reordering after creation, use `par.order` (accepts float values like `11.5` to insert between existing positions).

## Page Organization

Group parameters into pages by function. Use `comp.appendCustomPage('PageName')` -- pages appear in creation order.

Common patterns:

| Page | Purpose |
|------|---------|
| Main / Settings | Primary configuration |
| Tags | Externalization tags, strategies |
| UI | Visual and display options |
| About | Version, build, author (read-only) |

## Naming

- First letter MUST be uppercase, rest lowercase letters and numbers only
- No underscores, spaces, or special characters
- Examples: `Speed`, `Maxrows`, `Autosave`, `Envoyenable`

## Style Selection

| Use case | Style | Notes |
|----------|-------|-------|
| On/off toggle | `Toggle` | Values are `0`/`1` |
| Fire-once action | `Pulse` | No persistent value |
| Enumerated choices | `Menu` | Set `menuNames` and `menuLabels` separately |
| Editable dropdown | `StrMenu` | Free-text input with suggestions |
| Numeric value | `Float` or `Int` | Set range properties (see below) |
| Text input | `Str` | Free-form string |
| File/folder path | `File` / `Folder` | Opens system dialog |
| Operator reference | `OP`, `COMP`, `TOP`, `CHOP`, `SOP`, `DAT`, `MAT` | Filtered by family |
| Section header | `Header` | Visual label only, no value |

## Numeric Ranges

For `Float` and `Int` parameters, configure the range:

| Property | Purpose |
|----------|---------|
| `min` / `max` | Minimum and maximum values |
| `clampMin` / `clampMax` | Whether to enforce min/max as hard limits (`True`) or allow values outside (`False`) |
| `normMin` / `normMax` | Slider range in the UI (what the slider covers visually) |

Example:
```python
p = page.appendFloat('Speed', label='Speed')[0]
p.default = 1.0
p.min = 0.0
p.max = 10.0
p.clampMin = True
p.clampMax = False    # Allow values above 10 via manual entry
p.normMin = 0.0
p.normMax = 5.0       # Slider covers 0-5, but values up to 10+ accepted
p.help = "Playback speed multiplier. 1.0 = normal speed."
```

## Read-Only Parameters

Use `par.readOnly = True` for status and informational parameters that users should see but not edit (version, build number, connection status).

## Defaults

Always set `par.default = value`. This enables "Revert to Default" in the TD parameter dialog and ensures TDN round-trips produce consistent results.

## Creating Custom Parameters

All `page.append*()` methods return a **ParGroup** (tuple-like), not a single `Par`. Index with `[0]` to get the `Par` object:

```python
page = comp.appendCustomPage('Settings')
pg = page.appendFloat('Speed', label='Speed')  # Returns ParGroup
p = pg[0]                                        # Get the Par
p.default = 1.0
p.help = "Playback speed multiplier."
p.startSection = True
```

---

Source: https://www.openparable.com/skill/design/parameter-design (OpenParable). Cite the canonical URL above.
