# Naming intents

The names are the product. A good intent can be chosen from facts in the code, without judging how anything should look.

## The test

Ask: could someone pick this intent by reading the code and the content alone? “This handler shares the article” points to [`action.share`](https://www.prongs.dev/docs/intents/action/share.md). “This should be a secondary pill” is a visual judgement, and visual judgements are exactly what drift. Name meaning intents for what the element is or does. Put every look decision in the look layer.

## Look words are rejected

The UI profile refuses meaning intents whose names describe a look or a widget: words like primary, ghost, muted, bold, small, compact, hero, card, chip, pill, tab, button, row, stack, grid, centered and colour names. Look intents ([`control.pill`](https://www.prongs.dev/docs/intents/ui.md#control-pill), [`arrange.grid`](https://www.prongs.dev/docs/intents/ui.md#arrange-grid)) may use any words. The list is configurable.

Instead of action.primary · action.save, action.create, action.start

Instead of layout.card · layout.panel (one self-contained thing)

Instead of layout.stack, layout.row · layout.group, layout.actions

Instead of nav.tab · nav.view (switches which view you see)

Instead of choice.chip · choice.option, choice.filter

Instead of heading.hero · heading.pitch (the persuasive headline)

## Neighbours must contrast

In any domain with more than two intents, each one needs a “not for… use instead” link to or from a sibling. Otherwise the registry warns. [`text.caption`](https://www.prongs.dev/docs/intents/text/caption.md) says it is not for a few words that name a value ([`text.label`](https://www.prongs.dev/docs/intents/text/label.md)), nor for dates and counts ([`text.meta`](https://www.prongs.dev/docs/intents/text/meta.md)). Those links are what an agent reads when two intents look close, and they are what each intent’s page shows.

## Use the product’s own verbs

Generic intents like [`action.toggle`](https://www.prongs.dev/docs/intents/action/toggle.md) are a start, but the names your product already uses are better. Feedspace’s registry adds `action.follow`, `action.subscribe`, `action.bookmark` and `action.clap` (they are not among the starter intents). They match the handlers (`toggleFollow`, `toggleSave`), and they remove an ambiguity: “save settings” and “save an article” are different intents, so they can look different and neither can be mistaken for the other.

Keywords make the match checkable. When an action’s handler, label or text points to another intent, `check` says so:

```
app/feed.tsx:42:9  warning  name-mismatch  The code says "share article", which points to
  action.share, not action.navigate.
    → <Action intent="action.share">: Sends something to other people or copies a link to it
```

## Variants are structural

A third part is for a structural difference or a state, never a restyle: [`field.password.shown`](https://www.prongs.dev/docs/intents/field/password-shown.md) (the input type changes, and it is a starter intent), or names you might add like `nav.step.done` (a completed step) and `action.open.item` (the whole row is the link). If you want a variant only because something should look different, the intent is missing a meaning. Name that instead.