When an agent writes a component call, it has the schema, your docstring, and zero context for "what's idiomatic here." The API either reads correctly or it doesn't.

What works

Typed enums beat conventions. tone="info" compiles or it doesn't, and the agent gets feedback at type-check time. CSS variables like --helix-color-tone-info-bg require the agent to grep your docs and guess.

Explicit names beat terse ones. appearance over variant. foreground over fg. width="standard" over width="md".

Inline literal unions on @property declarations expand into discrete enum metadata in the Custom Elements Manifest. Extracted type aliases often emit just the alias name, losing the value list.

What doesn't

Magic prop combinations. APIs where size="sm" appearance="ghost" silently means something different than size="md" appearance="ghost". Agents can't intuit that. Make it a separate appearance.

Booleans that fight. disabled and readonly and loading interacting in non-obvious ways. Each one should be independently addressable.