@sableui/react 0.13.1 → 0.13.2

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # What's new
 
+## 0.13.2
+
+What to use instead, wherever a component is the wrong pick.
+
+- **New: a don't can name its replacement.** `usage.bestPractices` entries
+  take `instead: ["Banner", "Dialog"]`, set on 48 don'ts across the
+  families that get confused: Toast, Banner, Note and InlineStatus; Dialog,
+  Sheet and Popover; Select, Combobox and DisclosurePicker; Progress, Meter,
+  Spinner, Skeleton, PageLoader and ThinkingOrb; Tabs, Stepper and the
+  navs; Checkbox, Radio, Switch and Toggle. The build fails if a name isn't
+  a real component or subcomponent, so a rename can't leave a pointer to
+  nothing.
+- **`sable component <Name>` ends with "not for".** At compact detail, the
+  default, it now lists those don'ts in one line each with what to use
+  instead (`✗ Use Select for very large or fuzzy lists. → Combobox`). Before,
+  the don'ts only showed at `--detail full`. `--json` carries the same list
+  as `notFor`, and the markdown mirrors end each one with `→ use **X**`.
+
 ## 0.13.1
 
 Sable from any agent, and setup that starts with `sable init` everywhere an agent looks first.

package/CONTRIBUTING.md

@@ -223,7 +223,7 @@ The system grows **out of the apps**, not ahead of them. A component earns its w
 
 Each component ships `<name>.meta.ts` exporting a `ComponentMeta` object: `name`, `summary`, `keywords`, `usage` (intent, do/don't guidance, anatomy), `related`, `props` (name/type/default/description), `subcomponents`, `variants`, `tokensUsed` (semantic tokens it reads), `a11y` notes, and `examples` (label + code). Inline meta is the preferred **source of truth** and the contract other agents read; keep it in sync when you change a component. Existing guidance backfills may also live in `src/lib/component-guidance.ts`; the docs and registry generator merge that overlay so consumers read one resolved catalog.
 
-`usage.bestPractices` is where design judgment lives. Include concrete "do" and "dont" items that teach agents when to reach for the component, when to choose a neighboring component instead, and which visual/interaction anti-patterns to avoid. For composite components, include `usage.anatomy` so agents understand the required parts and slots before composing JSX.
+`usage.bestPractices` is where design judgment lives. Include concrete "do" and "dont" items that teach agents when to reach for the component, when to choose a neighboring component instead, and which visual/interaction anti-patterns to avoid. When a dont points at a neighbour, name it in `instead: ["Banner"]` as well as in the prose: the build checks each name is a real component or subcomponent, and `sable component` prints those donts as a short **not for** list at compact detail. For composite components, include `usage.anatomy` so agents understand the required parts and slots before composing JSX.
 
 Two rules that keep the contract unambiguous for consumers reading the registry:
 

package/bin/sable.mjs

@@ -855,6 +855,7 @@ function cmdComponent() {
 		data.subcomponents = c.subcomponents ?? []
 		data.related = c.related ?? []
 		if (!DENSE) data.usage = c.usage
+		data.notFor = notFor(c)
 	}
 	if (level === "full") {
 		data.a11y = c.a11y ?? []
@@ -873,6 +874,7 @@ function cmdComponent() {
 			`\n${data.import}`,
 			level === "brief" ? "" : renderProps(c),
 			level !== "full" || DENSE ? "" : renderUsage(c),
+			level === "full" && !DENSE ? "" : renderNotFor(data.notFor ?? []),
 			level === "full" ? section("a11y", (c.a11y ?? []).map(bullet)) : "",
 			level === "full" ? section("tokens", [`  ${(c.tokensUsed ?? []).join(", ")}`]) : "",
 			level === "full" ? renderExamples(c) : "",
@@ -896,9 +898,23 @@ function renderProps(c) {
 	return [section("props", lines), section("subcomponents", subs)].filter(Boolean).join("\n")
 }
 
+/* The donts that name a replacement, cut to their first sentence: the "when not
+ * to use this" an agent needs at compact detail, without the whole guidance list. */
+function notFor(c) {
+	return (c.usage?.bestPractices ?? [])
+		.filter((b) => b.guidance === "dont" && b.instead?.length)
+		.map((b) => ({ dont: b.description.split(/(?<=[.;])\s/)[0], use: b.instead }))
+}
+
+function renderNotFor(items) {
+	return section("not for", items.map((i) => `  ✗ ${i.dont} → ${i.use.join(", ")}`))
+}
+
 function renderUsage(c) {
 	if (!c.usage) return ""
-	const dos = (c.usage.bestPractices ?? []).map((b) => `  ${b.guidance === "do" ? "✓" : "✗"} ${b.description}`)
+	const dos = (c.usage.bestPractices ?? []).map(
+		(b) => `  ${b.guidance === "do" ? "✓" : "✗"} ${b.description}${b.instead ? ` → ${b.instead.join(", ")}` : ""}`,
+	)
 	return [c.usage.description ? `\nWhen to use:\n  ${c.usage.description}` : "", section("guidance", dos)]
 		.filter(Boolean)
 		.join("\n")

package/dist/blocks/index.d.ts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { B as BlockMeta } from '../meta-DVG8ceze.js';
+import { B as BlockMeta } from '../meta-DX5r5wQL.js';
 
 interface ApiKeysBlockProps {
     className?: string;

package/dist/components/accordion/accordion.meta.js

@@ -26,7 +26,8 @@ var accordionMeta = {
       },
       {
         guidance: "dont",
-        description: "Do not nest an Accordion inside an Accordion. Two layers of roving focus fight each other, and the arrow keys become ambiguous \u2014 flatten the hierarchy or use a Tree."
+        description: "Do not nest an Accordion inside an Accordion. Two layers of roving focus fight each other, and the arrow keys become ambiguous \u2014 flatten the hierarchy or use a Tree.",
+        instead: ["Tree"]
       }
     ],
     anatomy: [

package/dist/components/badge/badge.meta.js

@@ -30,7 +30,8 @@ var badgeMeta = {
       },
       {
         guidance: "dont",
-        description: "Use a Badge as a button. If it triggers an action, use Button, Toggle, or a menu item."
+        description: "Use a Badge as a button. If it triggers an action, use Button, Toggle, or a menu item.",
+        instead: ["Button", "Toggle"]
       },
       {
         guidance: "do",

package/dist/components/banner/banner.meta.js

@@ -34,11 +34,13 @@ var bannerMeta = {
       },
       {
         guidance: "dont",
-        description: "Use Banner for field-level validation, row status, or small local hints; use Field, InlineStatus, or Badge instead."
+        description: "Use Banner for field-level validation, row status, or small local hints; use Field, InlineStatus, or Badge instead.",
+        instead: ["InlineStatus", "Badge"]
       },
       {
         guidance: "dont",
-        description: "Use Banner inside a dialog, a form, or a section to qualify the content around it \u2014 that is Note. Banner is a full-width announcement strip for page- or app-level state, so in a modal it reads as a slab heavier than the fields it warns about, and its soft appearance has no border and no tone-colored icon: the severity survives only as a faint wash."
+        description: "Use Banner inside a dialog, a form, or a section to qualify the content around it \u2014 that is Note. Banner is a full-width announcement strip for page- or app-level state, so in a modal it reads as a slab heavier than the fields it warns about, and its soft appearance has no border and no tone-colored icon: the severity survives only as a faint wash.",
+        instead: ["Note"]
       }
     ],
     anatomy: [

package/dist/components/button-group/button-group.meta.js

@@ -25,7 +25,8 @@ var buttonGroupMeta = {
       },
       {
         guidance: "dont",
-        description: "Do not use it for a selection that stays on. That is ToggleGroup, which carries the pressed state."
+        description: "Do not use it for a selection that stays on. That is ToggleGroup, which carries the pressed state.",
+        instead: ["ToggleGroup"]
       }
     ]
   },

package/dist/components/checkbox/checkbox.meta.js

@@ -22,7 +22,8 @@ var checkboxMeta = {
       },
       {
         guidance: "dont",
-        description: "Do not use Checkbox for mutually exclusive choices; use Radio or Select instead."
+        description: "Do not use Checkbox for mutually exclusive choices; use Radio or Select instead.",
+        instead: ["Radio", "Select"]
       },
       {
         guidance: "dont",

package/dist/components/collapsible/collapsible.meta.js

@@ -22,7 +22,8 @@ var collapsibleMeta = {
       },
       {
         guidance: "dont",
-        description: "Do not use Collapsible for multi-section navigation; use Accordion or Tabs instead."
+        description: "Do not use Collapsible for multi-section navigation; use Accordion or Tabs instead.",
+        instead: ["Accordion", "Tabs"]
       },
       {
         guidance: "dont",

package/dist/components/combobox/combobox.meta.js

@@ -32,7 +32,8 @@ var comboboxMeta = {
       },
       {
         guidance: "dont",
-        description: "Use Combobox for tiny option sets where Select or Radio would be easier to scan."
+        description: "Use Combobox for tiny option sets where Select or Radio would be easier to scan.",
+        instead: ["Select", "Radio"]
       },
       {
         guidance: "do",
@@ -44,7 +45,8 @@ var comboboxMeta = {
       },
       {
         guidance: "dont",
-        description: "Use Combobox as a command launcher. Use CommandMenu for actions and navigation."
+        description: "Use Combobox as a command launcher. Use CommandMenu for actions and navigation.",
+        instead: ["CommandMenu"]
       },
       {
         guidance: "dont",

package/dist/components/command-menu/command-menu.meta.js

@@ -28,7 +28,8 @@ var commandMenuMeta = {
       },
       {
         guidance: "dont",
-        description: "Hand-style a <button> to look like a search field, or put a SearchInput in the header that opens a dialog when focused. The first drifts from the field it imitates; the second is a text box you cannot type in. A header search that opens the palette is CommandMenuTrigger."
+        description: "Hand-style a <button> to look like a search field, or put a SearchInput in the header that opens a dialog when focused. The first drifts from the field it imitates; the second is a text box you cannot type in. A header search that opens the palette is CommandMenuTrigger.",
+        instead: ["CommandMenuTrigger"]
       },
       {
         guidance: "do",
@@ -44,7 +45,8 @@ var commandMenuMeta = {
       },
       {
         guidance: "dont",
-        description: "Use CommandMenu as a replacement for every dropdown. Simple choices belong in Select, Menu, or Tabs."
+        description: "Use CommandMenu as a replacement for every dropdown. Simple choices belong in Select, Menu, or Tabs.",
+        instead: ["Select", "Menu", "Tabs"]
       },
       {
         guidance: "do",
@@ -64,7 +66,8 @@ var commandMenuMeta = {
       },
       {
         guidance: "dont",
-        description: "Hand-build a palette mock from a search glyph, a row of buttons and a highlight. That is CommandMenuPanel, and the hand-built one has no combobox, no filtering and no keyboard model."
+        description: "Hand-build a palette mock from a search glyph, a row of buttons and a highlight. That is CommandMenuPanel, and the hand-built one has no combobox, no filtering and no keyboard model.",
+        instead: ["CommandMenuPanel"]
       },
       {
         guidance: "dont",

package/dist/components/context-card/context-card.meta.js

@@ -26,7 +26,8 @@ var contextCardMeta = {
       },
       {
         guidance: "dont",
-        description: "Do not open it on click. It is a hover/focus preview; making it click-triggered gives you a Popover with no dismiss affordance and no way to reach the content it previews."
+        description: "Do not open it on click. It is a hover/focus preview; making it click-triggered gives you a Popover with no dismiss affordance and no way to reach the content it previews.",
+        instead: ["Popover"]
       }
     ],
     anatomy: [

package/dist/components/dialog/dialog.meta.js

@@ -38,7 +38,8 @@ var dialogMeta = {
       },
       {
         guidance: "dont",
-        description: "Put large multipage workflows in a centered dialog. Use Sheet or a page route when the task needs space."
+        description: "Put large multipage workflows in a centered dialog. Use Sheet or a page route when the task needs space.",
+        instead: ["Sheet"]
       },
       {
         guidance: "do",
@@ -46,7 +47,8 @@ var dialogMeta = {
       },
       {
         guidance: "dont",
-        description: `Use size="fullscreen" for forms, confirmations, or anything that isn't media. A dialog that happens to need room is a Sheet or a page; the fullscreen affordances (dark scrim, corner close, centred content) all assume something to look at.`
+        description: `Use size="fullscreen" for forms, confirmations, or anything that isn't media. A dialog that happens to need room is a Sheet or a page; the fullscreen affordances (dark scrim, corner close, centred content) all assume something to look at.`,
+        instead: ["Sheet"]
       },
       {
         guidance: "dont",
@@ -54,7 +56,8 @@ var dialogMeta = {
       },
       {
         guidance: "dont",
-        description: "Open a dialog for passive status updates. Use Toast, Banner, or InlineStatus instead."
+        description: "Open a dialog for passive status updates. Use Toast, Banner, or InlineStatus instead.",
+        instead: ["Toast", "Banner", "InlineStatus"]
       },
       {
         guidance: "do",

package/dist/components/disclosure-picker/disclosure-picker.meta.js

@@ -47,7 +47,8 @@ var disclosurePickerMeta = {
       },
       {
         guidance: "dont",
-        description: "Use it in a page-register form. A form field that pushes the form down on open reads as a layout jump; that is Select's job."
+        description: "Use it in a page-register form. A form field that pushes the form down on open reads as a layout jump; that is Select's job.",
+        instead: ["Select"]
       },
       {
         guidance: "dont",

package/dist/components/inline-status/inline-status.meta.js

@@ -22,7 +22,8 @@ var inlineStatusMeta = {
       },
       {
         guidance: "dont",
-        description: "Do not use InlineStatus for global announcements or page-level alerts."
+        description: "Do not use InlineStatus for global announcements or page-level alerts.",
+        instead: ["Banner"]
       },
       {
         guidance: "dont",

package/dist/components/menu/menu.meta.js

@@ -26,7 +26,8 @@ var menuMeta = {
       },
       {
         guidance: "dont",
-        description: "Do not build a Select out of it. A menu fires actions and has no value; a Select holds one and reports changes. Swapping them loses form semantics and keyboard type-ahead."
+        description: "Do not build a Select out of it. A menu fires actions and has no value; a Select holds one and reports changes. Swapping them loses form semantics and keyboard type-ahead.",
+        instead: ["Select"]
       },
       {
         guidance: "do",

package/dist/components/menubar/menubar.meta.js

@@ -25,7 +25,8 @@ var menubarMeta = {
       },
       {
         guidance: "dont",
-        description: "Do not use a menubar for site navigation. Its items are commands in menus (role=menuitem), not links between pages."
+        description: "Do not use a menubar for site navigation. Its items are commands in menus (role=menuitem), not links between pages.",
+        instead: ["NavigationMenu"]
       }
     ],
     anatomy: [

package/dist/components/meter/meter.meta.js

@@ -26,7 +26,8 @@ var meterMeta = {
       },
       {
         guidance: "dont",
-        description: "Do not use Meter for a task in flight \u2014 an upload, an install, a step count. That is Progress; Meter tells assistive tech nothing is happening."
+        description: "Do not use Meter for a task in flight \u2014 an upload, an install, a step count. That is Progress; Meter tells assistive tech nothing is happening.",
+        instead: ["Progress"]
       },
       {
         guidance: "dont",

package/dist/components/note/note.meta.js

@@ -33,7 +33,8 @@ var noteMeta = {
       },
       {
         guidance: "dont",
-        description: "Do not use Note for state the whole page or app is in (an outage, an offline session, a blocked account) \u2014 that is Banner \u2014 or for a message tied to one field, which is the field's own error text."
+        description: "Do not use Note for state the whole page or app is in (an outage, an offline session, a blocked account) \u2014 that is Banner \u2014 or for a message tied to one field, which is the field's own error text.",
+        instead: ["Banner"]
       },
       {
         guidance: "dont",

package/dist/components/page-loader/page-loader.meta.js

@@ -22,7 +22,8 @@ var pageLoaderMeta = {
       },
       {
         guidance: "dont",
-        description: "Do not use PageLoader for small inline waits; use Spinner, an indeterminate Progress, or Skeleton."
+        description: "Do not use PageLoader for small inline waits; use Spinner, an indeterminate Progress, or Skeleton.",
+        instead: ["Spinner", "Progress", "Skeleton"]
       },
       {
         guidance: "dont",

package/dist/components/pill/pill.meta.js

@@ -24,7 +24,8 @@ var pillMeta = {
       },
       {
         guidance: "dont",
-        description: "Do not use Pill as a static label. A pressable-looking chip that does nothing is the most common cause of dead clicks in a filter row \u2014 that is a Badge."
+        description: "Do not use Pill as a static label. A pressable-looking chip that does nothing is the most common cause of dead clicks in a filter row \u2014 that is a Badge.",
+        instead: ["Badge"]
       },
       {
         guidance: "dont",

package/dist/components/popover/popover.meta.js

@@ -22,11 +22,13 @@ var popoverMeta = {
       },
       {
         guidance: "dont",
-        description: "Do not use Popover for blocking confirmations, long forms, or critical information."
+        description: "Do not use Popover for blocking confirmations, long forms, or critical information.",
+        instead: ["Dialog"]
       },
       {
         guidance: "dont",
-        description: "Do not put a form that can fail validation inside one. A popover dismisses on outside click, which discards what the user typed with no warning \u2014 that is a Dialog."
+        description: "Do not put a form that can fail validation inside one. A popover dismisses on outside click, which discards what the user typed with no warning \u2014 that is a Dialog.",
+        instead: ["Dialog"]
       }
     ],
     anatomy: [

package/dist/components/progress/progress.meta.js

@@ -26,7 +26,8 @@ var progressMeta = {
       },
       {
         guidance: "dont",
-        description: "Do not use a determinate Progress for an unknown duration. A bar that sits at 90% is worse than a Spinner, because it makes a promise about time that you cannot keep."
+        description: "Do not use a determinate Progress for an unknown duration. A bar that sits at 90% is worse than a Spinner, because it makes a promise about time that you cannot keep.",
+        instead: ["Spinner"]
       }
     ],
     anatomy: [

package/dist/components/radio/radio.meta.js

@@ -22,7 +22,8 @@ var radioMeta = {
       },
       {
         guidance: "dont",
-        description: "Do not use Radio for independent toggles or multiple selection; use Checkbox or Switch."
+        description: "Do not use Radio for independent toggles or multiple selection; use Checkbox or Switch.",
+        instead: ["Checkbox", "Switch"]
       },
       {
         guidance: "dont",

package/dist/components/segmented-bar/segmented-bar.meta.js

@@ -16,7 +16,8 @@ var segmentedBarMeta = {
       },
       {
         guidance: "dont",
-        description: "Use it for a single value against a limit; that is Meter, which carries the meter role and its value."
+        description: "Use it for a single value against a limit; that is Meter, which carries the meter role and its value.",
+        instead: ["Meter"]
       },
       {
         guidance: "dont",

package/dist/components/select/select.meta.js

@@ -29,11 +29,13 @@ var selectMeta = {
       },
       {
         guidance: "dont",
-        description: "Use Select for very large or fuzzy lists. Use Combobox when typing is the primary way to find an option."
+        description: "Use Select for very large or fuzzy lists. Use Combobox when typing is the primary way to find an option.",
+        instead: ["Combobox"]
       },
       {
         guidance: "dont",
-        description: "Use Select for binary on/off settings. Use Switch or Checkbox instead."
+        description: "Use Select for binary on/off settings. Use Switch or Checkbox instead.",
+        instead: ["Switch", "Checkbox"]
       },
       {
         guidance: "do",

package/dist/components/sheet/sheet.meta.js

@@ -30,11 +30,13 @@ var sheetMeta = {
       },
       {
         guidance: "dont",
-        description: "Do not use Sheet for simple confirmations or deeply nested workflows."
+        description: "Do not use Sheet for simple confirmations or deeply nested workflows.",
+        instead: ["Dialog"]
       },
       {
         guidance: "dont",
-        description: "Do not use it on desktop where a Dialog fits. A sheet's affordance is edge-anchored travel for thumb reach; on a wide viewport it becomes a dialog that arrives from the wrong place."
+        description: "Do not use it on desktop where a Dialog fits. A sheet's affordance is edge-anchored travel for thumb reach; on a wide viewport it becomes a dialog that arrives from the wrong place.",
+        instead: ["Dialog"]
       }
     ],
     anatomy: [

package/dist/components/side-nav/side-nav.meta.js

@@ -33,7 +33,8 @@ var sideNavMeta = {
       },
       {
         guidance: "dont",
-        description: "Use SideNav for bottom mobile navigation; use BottomNav in AppShell's bottomNav slot."
+        description: "Use SideNav for bottom mobile navigation; use BottomNav in AppShell's bottomNav slot.",
+        instead: ["BottomNav"]
       },
       {
         guidance: "dont",

package/dist/components/skeleton/skeleton.meta.js

@@ -22,7 +22,8 @@ var skeletonMeta = {
       },
       {
         guidance: "dont",
-        description: "Do not leave Skeleton visible after an error or empty state; switch to EmptyState (tone='destructive' for an error)."
+        description: "Do not leave Skeleton visible after an error or empty state; switch to EmptyState (tone='destructive' for an error).",
+        instead: ["EmptyState"]
       },
       {
         guidance: "dont",

package/dist/components/spinner/spinner.meta.js

@@ -22,7 +22,8 @@ var spinnerMeta = {
       },
       {
         guidance: "dont",
-        description: "Do not use Spinner as the only content for long waits or full page loading."
+        description: "Do not use Spinner as the only content for long waits or full page loading.",
+        instead: ["Skeleton", "PageLoader"]
       },
       {
         guidance: "dont",

package/dist/components/stepper/stepper.meta.js

@@ -30,11 +30,13 @@ var stepperMeta = {
       },
       {
         guidance: "dont",
-        description: "Do not use Stepper for a task with unknown length or for a percentage. That is Progress; a stepper promises a fixed set of named stops."
+        description: "Do not use Stepper for a task with unknown length or for a percentage. That is Progress; a stepper promises a fixed set of named stops.",
+        instead: ["Progress"]
       },
       {
         guidance: "dont",
-        description: "Do not use it as navigation between independent sections. Sections the user can visit in any order are Tabs; a stepper implies each step depends on the one before."
+        description: "Do not use it as navigation between independent sections. Sections the user can visit in any order are Tabs; a stepper implies each step depends on the one before.",
+        instead: ["Tabs"]
       },
       {
         guidance: "dont",

package/dist/components/switch/switch.meta.js

@@ -26,7 +26,8 @@ var switchMeta = {
       },
       {
         guidance: "dont",
-        description: "Do not use Switch for one-time agreement, multi-select choices, or submit-only booleans."
+        description: "Do not use Switch for one-time agreement, multi-select choices, or submit-only booleans.",
+        instead: ["Checkbox", "Radio"]
       },
       {
         guidance: "dont",

package/dist/components/table/table.meta.js

@@ -34,7 +34,8 @@ var tableMeta = {
       },
       {
         guidance: "dont",
-        description: "Use Table for heterogeneous items with no stable columns. Use Card, Entity, or a list composition instead."
+        description: "Use Table for heterogeneous items with no stable columns. Use Card, Entity, or a list composition instead.",
+        instead: ["Card", "Entity"]
       },
       {
         guidance: "dont",

package/dist/components/tabs/tabs.meta.js

@@ -26,11 +26,13 @@ var tabsMeta = {
       },
       {
         guidance: "dont",
-        description: "Do not use Tabs for unrelated pages or primary navigation that needs distinct URLs."
+        description: "Do not use Tabs for unrelated pages or primary navigation that needs distinct URLs.",
+        instead: ["SideNav", "NavigationMenu"]
       },
       {
         guidance: "dont",
-        description: "Do not use tabs for sequential steps. Tabs are peer views the user returns to in any order; a process with an order needs a stepper, or the user will skip ahead."
+        description: "Do not use tabs for sequential steps. Tabs are peer views the user returns to in any order; a process with an order needs a stepper, or the user will skip ahead.",
+        instead: ["Stepper"]
       }
     ],
     anatomy: [

package/dist/components/thinking-orb/thinking-orb.meta.js

@@ -31,11 +31,13 @@ var thinkingOrbMeta = {
       },
       {
         guidance: "dont",
-        description: "Do not put one on every row of a list or in a repeated skeleton. Each orb runs its own animation frame loop painting hundreds of arcs; use Skeleton for content-shaped waits and Spinner inside buttons."
+        description: "Do not put one on every row of a list or in a repeated skeleton. Each orb runs its own animation frame loop painting hundreds of arcs; use Skeleton for content-shaped waits and Spinner inside buttons.",
+        instead: ["Skeleton", "Spinner"]
       },
       {
         guidance: "dont",
-        description: "Do not use it for a determinate wait. It carries no sense of how far along anything is \u2014 reach for Progress when a percentage exists."
+        description: "Do not use it for a determinate wait. It carries no sense of how far along anything is \u2014 reach for Progress when a percentage exists.",
+        instead: ["Progress"]
       },
       {
         guidance: "dont",

package/dist/components/toast/toast.meta.js

@@ -33,7 +33,8 @@ var toastMeta = {
       },
       {
         guidance: "dont",
-        description: "Use Toast for critical blockers or persistent outages. Use Banner or Dialog when the user must notice and act."
+        description: "Use Toast for critical blockers or persistent outages. Use Banner or Dialog when the user must notice and act.",
+        instead: ["Banner", "Dialog"]
       },
       {
         guidance: "dont",

package/dist/components/toggle/toggle.meta.js

@@ -31,7 +31,8 @@ var toggleMeta = {
       },
       {
         guidance: "dont",
-        description: "Do not use Toggle for persistent application settings; use Switch."
+        description: "Do not use Toggle for persistent application settings; use Switch.",
+        instead: ["Switch"]
       },
       {
         guidance: "dont",

package/dist/components/toolbar/toolbar.meta.js

@@ -43,7 +43,8 @@ var toolbarMeta = {
       },
       {
         guidance: "dont",
-        description: "Use Toolbar for navigation between pages or views. Links that go somewhere are Tabs, SideNav or Breadcrumbs; ToolbarLink is for the odd link that sits among actions, like Help."
+        description: "Use Toolbar for navigation between pages or views. Links that go somewhere are Tabs, SideNav or Breadcrumbs; ToolbarLink is for the odd link that sits among actions, like Help.",
+        instead: ["Tabs", "SideNav", "Breadcrumbs"]
       },
       {
         guidance: "dont",

package/dist/components/tooltip/tooltip.meta.js

@@ -22,7 +22,8 @@ var tooltipMeta = {
       },
       {
         guidance: "dont",
-        description: "Do not put critical instructions, errors, or interactive content inside Tooltip."
+        description: "Do not put critical instructions, errors, or interactive content inside Tooltip.",
+        instead: ["Popover", "InlineStatus"]
       },
       {
         guidance: "dont",