@gunkin/uiify 0.0.17-alpha → 0.0.19-alpha

package/skills/uiify/references/elements/card.md

@@ -4,7 +4,44 @@ Binding: gap
 
 Group one feature heading and its explanation.
 
-Group related information under a heading. Give a card a link or control only when the entire surface has one clear destination or action.
+## Use when
+
+A small set of related content needs a clear grouping, with a heading and supporting detail.
+
+## Avoid when
+
+Do not wrap every paragraph or list item in a card. Avoid card-within-card nesting and whole-surface click behavior when the card contains multiple independent controls.
+
+## Structure
+
+This is an app-level composition, not a UIify component. Group one topic under a heading, add a concise description, and use a link for one clear destination. If the card has one destination, make the heading link the primary control; keep other controls separate.
+
+## Responsive
+
+Keep cards in reading order when the grid stacks. Let content determine height and align repeated actions without truncating essential labels.
+
+## States
+
+Use links for navigation and buttons for in-place actions. Add selected/pressed state only when the card itself represents a selectable item.
+
+## Verify
+
+Check heading hierarchy, reading order, single versus multiple actions, keyboard reachability, focus visibility, and one-column reflow.
+
+## Common mistake
+
+Making an entire card clickable while also placing buttons or links inside it creates nested, ambiguous controls.
+
+## Custom implementation
+
+```html
+<article aria-labelledby="plan-title">
+  <h2 id="plan-title"><a href="/plans/pro">Pro plan</a></h2>
+  <p>For teams that need shared workspaces.</p>
+</article>
+```
+
+This is an app-level composition; UIify does not currently ship this component.
 
 Related laws: references/laws/proximity.md, references/laws/readability.md
 

package/skills/uiify/references/elements/carousel.md

@@ -0,0 +1,38 @@
+# carousel
+
+Binding: carousel
+
+Present a labeled sequence of related slides with native scrolling and optional controls.
+
+## Use when
+
+A short sequence of related slides saves space and users benefit from viewing one or a subset at a time. Prefer direct scrolling when all items should remain discoverable together.
+
+## Avoid when
+
+Do not hide essential information in offscreen slides or auto-rotate content without a clear user need and an operable stop/restart control.
+
+## Structure
+
+Use `Carousel` with a stable id, descriptive aria-label, and items with unique ids and labels. The base entry is a native scroll-snap region with fragment links; navigation controls and synchronized state are in /client.
+
+## Responsive
+
+Use inline axis for horizontal slides and preserve native scrolling/scroll snap. Ensure neighboring content does not make the current slide ambiguous and controls remain reachable.
+
+## States
+
+Prefer manual operation. The client API supports autoplay with a rotation control and stops on keyboard focus, but it does not currently pause on pointer hover. Leave autoplay disabled unless the app adds hover pausing. The base entry works without JavaScript.
+
+## Verify
+
+Check accessible carousel label, slide labels, previous/next and pagination names, fragment navigation without JavaScript, keyboard control, focus behavior, and mobile scrolling. If autoplay is used, verify pause/restart and that rotation does not obscure slide reading.
+
+## Common mistake
+
+Dot-only controls with no meaningful accessible names do not tell users which slide they will select.
+
+## Sources
+
+- [www.w3.org](https://www.w3.org/WAI/ARIA/apg/patterns/carousel/) (verified 2026-10-17)
+- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html) (verified 2026-10-17)

package/skills/uiify/references/elements/checkbox.md

@@ -0,0 +1,39 @@
+# checkbox
+
+Binding: checkbox
+
+Select one or more independent options.
+
+## Use when
+
+Let people independently select any number of options, including none.
+
+## Avoid when
+
+Use a radio group when exactly one option can be selected. Use a switch for a single immediate on/off setting.
+
+## Structure
+
+Use the documented Checkbox with a stable id and a visible, descriptive label. Group related choices in a fieldset with a legend; use the indeterminate state only for an aggregate that represents mixed child selections.
+
+## Responsive
+
+Let each label wrap without reducing the control's usable hit area. Stack choices when inline labels no longer fit.
+
+## States
+
+Make checked, unchecked, disabled, and any mixed aggregate state clear. Preserve selections when validation or another field fails.
+
+## Verify
+
+Click both the control and its label, use Space from the keyboard, and test independent selection, group naming, disabled and indeterminate states.
+
+## Common mistake
+
+Using checkboxes for mutually exclusive options or showing mixed state without an aggregate relationship.
+
+## Sources
+
+- [www.w3.org](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/) (verified 2026-10-17)
+- [www.w3.org](https://www.w3.org/WAI/tutorials/forms/labels/) (verified 2026-10-17)
+- [www.w3.org](https://www.w3.org/WAI/tutorials/forms/grouping/) (verified 2026-10-17)

package/skills/uiify/references/elements/code-block.md

@@ -4,7 +4,35 @@ Binding: gap
 
 Present source text with preserved whitespace.
 
-Use preformatted code with a concise caption. Preserve whitespace and provide a separate, clearly named copy action only when copying is available.
+## Use when
+
+People need to read or copy source text while preserving whitespace and line breaks.
+
+## Avoid when
+
+Do not put prose in preformatted code or make copying the only way to access the content. Avoid horizontal overflow that hides important lines without an intentional scroll container.
+
+## Structure
+
+This is an app-level composition, not a UIify component. Use pre > code for code and a figure/figcaption when a caption identifies the example. Add a clearly named copy button only when copy is implemented; report success in a status region.
+
+## Responsive
+
+Allow code to wrap when that preserves readability, or provide a clearly scrollable region with keyboard access. Keep captions and copy controls reachable at narrow widths.
+
+## States
+
+Represent copy idle/success/failure in text. Do not announce every code line; preserve code as selectable text.
+
+## Verify
+
+Check whitespace, language/description context, keyboard scrolling, copy action name and announcement, zoom, and line wrapping.
+
+## Common mistake
+
+An icon-only copy button with no accessible name gives no indication of its action.
+
+## Custom implementation
 
 ```html
 <figure>
@@ -13,9 +41,10 @@ Use preformatted code with a concise caption. Preserve whitespace and provide a
 </figure>
 ```
 
-This is an app-level composition recipe; it does not add a component to UIify.
+This is an app-level composition; UIify does not currently ship this component.
 
 ## Sources
 
 - [developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/pre) (verified 2026-10-16)
+- [developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/code) (verified 2026-10-16)
 - [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (verified 2026-10-16)

package/skills/uiify/references/elements/collapsible.md

@@ -0,0 +1,38 @@
+# collapsible
+
+Binding: collapsible
+
+Reveal secondary content with a native details/summary disclosure.
+
+## Use when
+
+A section is secondary to the main flow and people benefit from choosing when to reveal it.
+
+## Avoid when
+
+Do not hide information people need to complete the primary task or expect users to open several sections to compare content. Use headings and visible content for essential information.
+
+## Structure
+
+Use `Collapsible` with a specific visible label and content. It uses native details/summary; give the root a stable id. Keep the disclosure label concise and informative.
+
+## Responsive
+
+Let revealed content reflow naturally and avoid fixed-height panels. Keep the summary hit area comfortably operable on touch.
+
+## States
+
+The native details element supports open/closed state without JavaScript. Enter/Space toggles the summary. 'defaultOpen' sets initial state; 'disabled' removes the summary from focus and marks it aria-disabled.
+
+## Verify
+
+Test keyboard and pointer toggle, open/closed announcement, initial open state, disabled state, multiple independent disclosures, and narrow content reflow.
+
+## Common mistake
+
+Do not use the disclosure label as a vague “More” when it can name the hidden content.
+
+## Sources
+
+- [www.w3.org](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/) (verified 2026-10-17)
+- [developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details) (verified 2026-10-17)

package/skills/uiify/references/elements/color-picker.md

@@ -0,0 +1,39 @@
+# color-picker
+
+Binding: color-picker
+
+Let people choose a color value for a specific purpose.
+
+## Use when
+
+Let people set a color such as a theme accent or drawing color.
+
+## Avoid when
+
+Do not use color as the only way to choose or identify a required category. Use a finite labelled choice set when only a few named colors are allowed.
+
+## Structure
+
+Use the documented ColorPicker with its required visible label. Choose the documented colorSpace and alpha options to match the stored value; show the current color value as text as well as a swatch.
+
+## Responsive
+
+Keep the label, picker control, and current value visible within narrow layouts.
+
+## States
+
+Preserve the selected color and communicate any invalid or disabled state. The native picker UI may vary by browser and operating system.
+
+## Verify
+
+Test the accessible name, keyboard use, color value serialization, alpha and color-space requirements, and the browser’s picker behavior. Check that meaning is not conveyed by color alone.
+
+## Common mistake
+
+Showing a swatch without text that lets people inspect or identify its value.
+
+## Sources
+
+- [developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input/color) (verified 2026-10-17)
+- [www.w3.org](https://www.w3.org/WAI/tutorials/forms/labels/) (verified 2026-10-17)
+- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html) (verified 2026-10-17)

package/skills/uiify/references/elements/combobox.md

@@ -0,0 +1,37 @@
+# combobox
+
+Binding: combobox
+
+Search and choose from a long set of known options.
+
+## Use when
+
+Let the person filter and choose from a long list of known options. Use a native `select` or radio group for a short list; use a text input for unrestricted text.
+
+## Avoid when
+
+Do not use a combobox when people need to compare all options at once or when typing is not a useful way to find an option.
+
+## Structure
+
+`Combobox.Root` receives `items` with `label` and `value`. Give `Combobox.Input` a visible associated label or accessible name. Render filtered items with `Combobox.Content` and `Combobox.Item`; render `Combobox.Empty` only when the filtered list is empty. The multi-value mode uses `multiple` and supports tags.
+
+## Responsive
+
+Keep the input and selected value visible when the option popup opens. Let the popup scroll when the filtered list is long and keep the current option in view.
+
+## States
+
+Typing filters options. Arrow keys move the active option while DOM focus stays on the input; Enter selects the active option and Escape closes the popup. Skip disabled options; provide loading feedback in the page. In Tier 2, filtering and selection require JavaScript hydration; before hydration only server-rendered markup is present.
+
+## Verify
+
+Type a partial match, use ArrowDown and ArrowUp to move through results, press Enter to select, and Escape to close without selecting. Check no matches, disabled options, loading, selected value, narrow viewport, and the accessible input name.
+
+## Common mistake
+
+A combobox for four choices adds typing and keyboard behavior without helping people find an option.
+
+## Sources
+
+- [www.w3.org](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) (verified 2026-10-17)

package/skills/uiify/references/elements/command-palette.md

@@ -2,21 +2,42 @@
 
 Binding: gap
 
-Let users find and invoke a small set of named commands.
+Let users search for and invoke a small set of named commands.
 
-For a non-interactive command list, use a labeled search form and links or buttons with clear names. A searchable list is not a command palette until keyboard navigation, selection, and dismissal behavior are implemented.
+## Use when
 
-```html
-<form role="search">
-  <label for="commands">Search commands</label>
-  <input id="commands" type="search" />
-  <ul><li><a href="/settings">Open settings</a></li></ul>
-</form>
-```
+Provide a keyboard-accessible way to find and invoke named commands across an application.
 
-This is an app-level composition recipe; it does not add a component to UIify.
+## Avoid when
+
+Do not call a static search form a command palette. Avoid menu/listbox semantics unless the complete keyboard and selection pattern is implemented.
+
+## Structure
+
+Give the search field a visible or programmatic label. A full palette must define how focus enters and leaves, how results are navigated and selected, and how the surface is dismissed; follow the applicable combobox and dialog pattern.
+
+## Responsive
+
+Keep the search field and results within the viewport, with a scrollable results region that does not trap page zoom.
+
+## States
+
+Provide clear no-results, loading, and execution feedback where applicable. Keep the query and focus behavior predictable when the palette closes.
+
+## Verify
+
+Test keyboard navigation, selection, Escape dismissal, focus restoration, screen-reader names, and narrow viewport behavior. A labeled search form alone does not pass this check.
+
+## Common mistake
+
+Adding arrow-key handlers to a list of buttons without implementing a coherent focus and selection model.
+
+## Custom implementation
+
+For a basic non-interactive list, use a labelled search form with ordinary links or buttons. Add command-palette behavior only with a complete, tested interaction model; UIify has no dedicated command-palette component.
 
 ## Sources
 
-- [developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/search) (verified 2026-10-16)
-- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (verified 2026-10-16)
+- [www.w3.org](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) (verified 2026-10-17)
+- [www.w3.org](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/) (verified 2026-10-17)
+- [www.w3.org](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/) (verified 2026-10-17)

package/skills/uiify/references/elements/context-menu.md

@@ -0,0 +1,38 @@
+# context-menu
+
+Binding: context-menu
+
+A specific object has a short set of actions that are useful at the point where the user invokes its context menu
+
+## Use when
+
+A specific object has a short set of actions that are useful at the point where the user invokes its context menu. Every action must also be available through a discoverable visible control or another accessible route.
+
+## Avoid when
+
+Do not make right-click the only way to reach an action, or use this for general navigation. On touch devices, users need a visible alternative.
+
+## Structure
+
+Wrap the object with `ContextMenu` Root, Trigger, Content, and concise action items. Use checkbox/radio items only for state choices and provide clear labels that make sense without pointer coordinates.
+
+## Responsive
+
+Context menus are supplementary on touch: expose the same actions through a visible button or menu. Check that pointer-anchored placement stays on screen.
+
+## States
+
+The trigger opens on the context-menu event and the menu focuses an item. Arrow keys move through items, Enter/Space selects, and Escape closes and returns focus.
+
+## Verify
+
+Test context-menu key/pointer opening, keyboard navigation and selection, Escape/focus return, outside dismissal, disabled items, and viewport-edge placement. Verify the same actions are reachable without a right-click.
+
+## Common mistake
+
+Do not hide the only route to an important action behind a context menu.
+
+## Sources
+
+- [www.w3.org](https://www.w3.org/WAI/ARIA/apg/patterns/menubar/) (verified 2026-10-17)
+- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html) (verified 2026-10-17)

package/skills/uiify/references/elements/cookie-banner.md

@@ -4,7 +4,35 @@ Binding: gap
 
 Explain cookie choices and provide consent actions.
 
-State which optional storage choices are available and link to the detailed policy. Offer distinct actions for consent choices without making one choice the only visible path.
+## Use when
+
+A product needs to explain its cookie/storage choices and provide a clear route to the detailed policy and preference controls.
+
+## Avoid when
+
+Do not obscure the primary task with a full-screen interruption when a compact notice works. Do not imply that a button choice is legally sufficient in every jurisdiction; match the product's actual consent policy.
+
+## Structure
+
+This is an app-level composition, not a UIify component. State what optional storage is used for, link to the policy, and present distinct choices with similarly clear labels.
+
+## Responsive
+
+Keep the notice readable at mobile widths and zoom; allow the page to remain usable and make every choice reachable without horizontal scrolling.
+
+## States
+
+Represent the actual consent state: undecided, accepted/rejected as supported by policy, and preference editing. Persist only the choice the person made, and provide a way to revisit preferences.
+
+## Verify
+
+Check keyboard operation, policy link, clear action labels, focus order, narrow layout, persistence behavior, and that the choices match the implementation and applicable policy.
+
+## Common mistake
+
+Do not hide rejection behind multiple steps while acceptance is a single prominent button.
+
+## Custom implementation
 
 ```html
 <aside aria-labelledby="cookie-title">
@@ -15,7 +43,7 @@ State which optional storage choices are available and link to the detailed poli
 </aside>
 ```
 
-This is an app-level composition recipe; it does not add a component to UIify.
+This is an app-level composition; UIify does not currently ship this component.
 
 ## Sources
 

package/skills/uiify/references/elements/date-picker.md

@@ -2,18 +2,42 @@
 
 Binding: gap
 
-Collect one calendar date using the native date control.
+Collect one calendar date using the browser’s native date control.
 
-Prefer the native date input for one date. Show date constraints in text and connect invalid-value feedback to the input.
+## Use when
 
-```html
-<label for="start-date">Start date</label>
-<input id="start-date" name="start-date" type="date" />
-```
+Collect one calendar date without a time, such as a start or due date.
 
-This is an app-level composition recipe; it does not add a component to UIify.
+## Avoid when
+
+Use a date-time control when time matters. Avoid replacing the native picker with a custom calendar unless the task requires behavior that has been tested for keyboard and assistive technology.
+
+## Structure
+
+Use a visible label with a native input of type date. Add min and max only when the constraints are real, explain them before entry, and associate error feedback with the field.
+
+## Responsive
+
+Allow the browser’s date UI to use the platform layout; keep the field within the available width and do not assume every browser displays the same picker.
+
+## States
+
+Distinguish an empty value, a valid date, and a date outside the allowed range. The submitted date value is a calendar date normalized as yyyy-mm-dd.
+
+## Verify
+
+Test keyboard entry and picker operation in target browsers, date bounds, visible format guidance, validation text, and narrow-screen behavior.
+
+## Common mistake
+
+Treating a date-only value as a timestamp with a time zone.
+
+## Custom implementation
+
+Use a labelled native input with type date. This app-level pattern does not add a UIify date-picker component.
 
 ## Sources
 
-- [developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/date) (verified 2026-10-16)
-- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (verified 2026-10-16)
+- [developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input/date) (verified 2026-10-17)
+- [www.w3.org](https://www.w3.org/WAI/tutorials/forms/labels/) (verified 2026-10-17)
+- [www.w3.org](https://www.w3.org/WAI/tutorials/forms/instructions/) (verified 2026-10-17)

package/skills/uiify/references/elements/divider.md

@@ -4,13 +4,41 @@ Binding: gap
 
 Separate adjacent thematic sections when a heading is not appropriate.
 
-Use a thematic separator only when it marks a real change of topic; leave purely decorative separators out of the accessibility tree.
+## Use when
+
+Adjacent sections change topic and a thematic break helps people understand the transition.
+
+## Avoid when
+
+Do not add a divider between every repeated item or use it in place of spacing. Decorative lines that convey no grouping should remain outside the accessibility tree.
+
+## Structure
+
+This is an app-level composition, not a UIify component. Use the native hr element for a thematic break; use CSS border for a purely decorative rule.
+
+## Responsive
+
+Use logical sizing and preserve separation as content wraps or stacks. Avoid rules that become ambiguous in vertical writing or dense layouts.
+
+## States
+
+A thematic break is static. If a separator labels a widget such as a menu, use that widget's separator semantics instead of hr.
+
+## Verify
+
+Check whether the line marks a real topic change, reading flow around it, and narrow layout.
+
+## Common mistake
+
+A visual border between every card is not automatically a thematic break.
+
+## Custom implementation
 
 ```html
 <hr />
 ```
 
-This is an app-level composition recipe; it does not add a component to UIify.
+This is an app-level composition; UIify does not currently ship this component.
 
 ## Sources
 

package/skills/uiify/references/elements/drawer.md

@@ -0,0 +1,38 @@
+# drawer
+
+Binding: drawer
+
+A focused secondary task or navigation surface should enter from an edge and temporarily cover or accompany the page
+
+## Use when
+
+A focused secondary task or navigation surface should enter from an edge and temporarily cover or accompany the page. Choose it when the task benefits from a sheet-like spatial relationship.
+
+## Avoid when
+
+Do not use a drawer for content that should remain visible beside the page, or for a compact anchored choice list. Avoid turning primary navigation into a blocking task without a clear need.
+
+## Structure
+
+Use `Drawer` with a specific title, optional description, focused content, visible close control, and optional footer. Select side and size to fit the task; use snap points only when the client interaction is needed.
+
+## Responsive
+
+Use a bottom sheet on narrow screens when the task reads naturally as a sheet; keep its content scrollable and close action reachable. Respect safe areas and test the selected side at mobile widths.
+
+## States
+
+The native Tier 0 shell opens a dialog. Choose 'dismiss' deliberately: 'any' permits backdrop/Escape, 'closerequest' allows close requests, and 'none' requires an explicit close. The compound client API adds controlled state and optional snap-point dragging.
+
+## Verify
+
+Check visible title, focus entry/containment/return, close control, configured dismissal, scrolling, and narrow viewport. If using drag, test the handle with touch and pointer and ensure an explicit close remains available.
+
+## Common mistake
+
+Do not rely on dragging as the only way to close or resize the drawer.
+
+## Sources
+
+- [www.w3.org](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/) (verified 2026-10-17)
+- [developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog) (verified 2026-10-17)

package/skills/uiify/references/elements/dropdown-menu.md

@@ -0,0 +1,38 @@
+# dropdown-menu
+
+Binding: dropdown-menu
+
+A button reveals a compact set of actions or settings for that button
+
+## Use when
+
+A button reveals a compact set of actions or settings for that button. Use menu items for commands, checkbox items for independent toggles, and radio items for one choice within a group.
+
+## Avoid when
+
+Do not use a menu for site navigation; use ordinary links and navigation landmarks. Do not use menu roles for a form or a list of links that should remain in the page's normal Tab sequence.
+
+## Structure
+
+Compose `DropdownMenu` Root, Trigger, Content, and named items. Give the trigger an action-oriented accessible name; group related actions with labels and separators, and use checkbox/radio items only for their matching state model.
+
+## Responsive
+
+Keep the menu within the viewport and ensure labels remain readable at zoom. Provide a touch-sized trigger and avoid making hover the only way to open it.
+
+## States
+
+The trigger opens the menu; keyboard interaction moves focus among items and Escape closes and returns focus. Selection closes by default. 'openOnHover' is optional enhancement; preserve the normal click and keyboard route.
+
+## Verify
+
+Test trigger by keyboard and pointer, arrow-key item navigation, Home/End where supported, Escape and focus return, disabled items, selection, and checked/radio state announcements. Check placement near viewport edges.
+
+## Common mistake
+
+A row of destination links is navigation, even if it visually resembles a dropdown menu.
+
+## Sources
+
+- [www.w3.org](https://www.w3.org/WAI/ARIA/apg/patterns/menubar/) (verified 2026-10-17)
+- [www.w3.org](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/) (verified 2026-10-17)

package/skills/uiify/references/elements/empty-state.md

@@ -4,7 +4,35 @@ Binding: gap
 
 Explain why a collection has no items and offer a relevant next step.
 
-Explain what is empty and why it matters, then offer one next action that addresses the empty state.
+## Use when
+
+A collection has no items and the person needs to understand what is empty and what useful step is available next.
+
+## Avoid when
+
+Do not show an empty state for loading, filtered no-results, access denial, and a genuinely new collection as though they were the same cause. Name the actual state.
+
+## Structure
+
+This is an app-level composition, not a UIify component. Give the section a heading that names the collection and one relevant next step; use a link for navigation or a button for an in-place action.
+
+## Responsive
+
+Keep the message and action close in reading order, use a concise line length, and do not center long explanatory copy in an unnecessarily narrow area.
+
+## States
+
+Distinguish first-use empty, filtered no-results, unavailable/error, and loading states. Explain a recovery action for filters and avoid suggesting creation when the person lacks permission.
+
+## Verify
+
+Check the heading and action name, real destination/behavior, keyboard access, state-specific copy, and narrow/zoom layout.
+
+## Common mistake
+
+“No results” should offer a way to clear or change filters, not a create action unrelated to the search.
+
+## Custom implementation
 
 ```html
 <section aria-labelledby="empty-title">
@@ -14,7 +42,7 @@ Explain what is empty and why it matters, then offer one next action that addres
 </section>
 ```
 
-This is an app-level composition recipe; it does not add a component to UIify.
+This is an app-level composition; UIify does not currently ship this component.
 
 ## Sources