component-authoring

Files (1)

• SKILL.md

SKILL.md (first lines)

# Core Principles for Using LLMs in Component & API Design

## 1) Optimize for *intent*, not implementation

Ask the LLM to reason about **what the component means**, not how it is rendered.

* Names should express *behavior and semantics* (`watch-toggle`, not `watch-button`)
* APIs should describe *what changes*, not *what is clicked*
* Prefer verbs and domain language over UI nouns

> Prompt framing tip:
> “What is the intent of this component?” yields better results than “What should I call this button?”

---

## 2) Explicit ownership beats implicit convention

Always clarify **who owns what**:

* Which component owns layout?
* Which component owns state?
* Which component owns slot placement?

Ambiguity causes LLMs (and humans) to drift into inconsistent abstractions.

> Good LLM prompts explicitly state:
> “Component X owns layout; Component Y owns behavior; slots belong to X.”

---

## 3) Slots are for authored content; attributes are for state & configuration

This separation consistently produced the cleanest outcomes.

**Use slots when:**

* Content may contain markup
* Text must be localized
* Consumers may want icons, emphasis, or structure

**Use attributes/properties when:**

* Representing state (`pressed`, `disabled`)
* Controlling behavior (`mode`, `variant`)
* Passing data used for computation (`price`, `base-price`)

> LLMs reason best when this boundary is explicit in the prompt.

---

## 4) Avoid ambiguous sources of truth

A recurring risk: mixing display text with computational inputs.

**Rule:**
If a component *computes*, its inputs must be unambiguous.

* Numbers → attributes / properties
* Formatting → component responsibility or clearly scoped slots
* Slots override behavior only when explicitly designed to do so

> When asking an LLM, explicitly ask:
> “What is the single source of truth here?”

---

## 5) Prefer controlled or controllable components

Even if state is “internal” today, design for:

* external updates
* synchronization
* deterministic rendering

Expose:

* a reflected state attribute
* an event that expresses intent (`change`, `toggle`)
* tolerance for external state driving

> LLMs tend to default to “self-contained”; steer them by stating future integration needs.

---

## 6) Default behavior + escape hatches

A strong pattern that emerged:

* Provide **sensible defaults** (implicit icon, default layout)
* Keep **explicit escape hatches** (slots, parts, CSS vars)

This avoids both over-configuration and dead-end APIs.

> Ask LLMs:
> “What’s the default 80% case, and what’s the minimal escape hatch?”

---

## 7) Composition over configuration

Your examples worked because composition stayed in markup, not attributes.

Prefer:

```html
<component>
  <icon></icon>
  <label></label>
</component>
```

over:

```html
<component icon="plus" label="Add"></component>
```

LLMs give better architectural guidance when composition is treated as the primary tool.

From nocksock/superpowers, MIT.

More from nocksock/superpowers