@gunkin/uiify 0.0.17-alpha → 0.0.19-alpha

package/skills/uiify/references/elements/feature-grid.md

@@ -4,7 +4,47 @@ Binding: gap
 
 Present related product capabilities as a coherent set.
 
-Use a repeated grid when the features share the same level and structure. Keep each feature’s heading and explanation in reading order at narrow widths.
+## Use when
+
+Several related capabilities have equal importance and repeat the same content shape.
+
+## Avoid when
+
+Do not force unequal priorities or long-form explanations into a uniform grid. Use a comparison table when people must compare values across features.
+
+## Structure
+
+This is an app-level composition, not a UIify component. Render a labeled section containing a list of items; give each item a heading and short explanation. Use the same order and content hierarchy for every item.
+
+## Responsive
+
+Collapse to one column on narrow screens and retain source order. Avoid fixed heights that clip translated or zoomed text.
+
+## States
+
+Keep item actions consistent. If each feature links to detail, link its heading and retain a clear focus indicator.
+
+## Verify
+
+Check section label, heading levels, source order, one-column reflow, link names, and the card spacing at mobile width.
+
+## Common mistake
+
+Do not use three equal cards to imply equal priority when one feature is the primary action.
+
+## Custom implementation
+
+```html
+<section aria-labelledby="features-title">
+  <h2 id="features-title">Built for daily work</h2>
+  <ul>
+    <li><article><h3>Shared workspace</h3><p>Keep team work together.</p></article></li>
+    <li><article><h3>Clear history</h3><p>See what changed and when.</p></article></li>
+  </ul>
+</section>
+```
+
+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/field.md

@@ -4,11 +4,41 @@ Binding: field
 
 Keep a label and its form control together.
 
-Keep each label next to its control. Put a group label on related controls and show validation beside the field it describes.
+## Use when
+
+Keep a form control, its label, instructions, and any validation message connected. Use visible labels that name the expected information; a placeholder is not a substitute.
+
+## Avoid when
+
+Do not use a field wrapper without a real form control, or hide instructions needed before the person enters a value.
+
+## Structure
+
+Use `Field.Root`, `Field.Label`, `Field.Control`, `Field.Description`, and `Field.Error` with the same `id` on Root and `fieldId` on every part. Put native props such as `name`, `type`, and `autoComplete` on `Field.Control`. Pass `invalid`, `required`, and `disabled` to the parts that need those states; Root does not inject props into them.
+
+## Responsive
+
+Keep labels and help text close to the control at narrow widths. Let long instructions and error messages wrap without clipping.
+
+## States
+
+Native required validation works without JavaScript. For application validation, set `invalid` on Root and Control and render `Field.Error` with the same state after validation. The control's accessible description includes the error while invalid.
+
+## Verify
+
+Click the label and confirm its control receives focus. Inspect the accessibility tree for the control's name and associated description; submit an invalid value and confirm a textual error appears and is announced. Check required, disabled, read-only, and long-message states.
+
+## Common mistake
+
+A label and control with different `fieldId` values disconnect the visible label from the input and its instructions.
+
+Example: `references/examples/field-validation.md`.
 
 Related laws: references/laws/proximity.md, references/laws/accessibility.md
 
 ## Sources
 
-- [www.w3.org](https://www.w3.org/WAI/tutorials/forms/grouping/) (verified 2026-10-16)
-- [www.w3.org](https://www.w3.org/WAI/tutorials/forms/labels/) (verified 2026-10-16)
+- [www.w3.org](https://www.w3.org/WAI/tutorials/forms/grouping/) (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/error-identification.html) (verified 2026-10-17)
+- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/error-suggestion.html) (verified 2026-10-17)

package/skills/uiify/references/elements/file-upload.md

@@ -0,0 +1,40 @@
+# file-upload
+
+Binding: file-upload
+
+Let people select and manage files for a form or task.
+
+## Use when
+
+Let people attach one or more files to a form or task.
+
+## Avoid when
+
+Do not require drag and drop as the only way to choose files. Avoid asking for files unrelated to the task.
+
+## Structure
+
+Use FileUpload.Root with a labelled HiddenInput and an optional Trigger or Dropzone. Explain allowed formats, size limits, and maximum file count before selection; show selected filenames and provide a named remove action for each file.
+
+## Responsive
+
+Keep the browse control and selected-file list usable at narrow widths. Do not rely on a large drop target that pushes the file picker off screen.
+
+## States
+
+Report rejected files with the reason, including type, size, or count limits. Keep the accepted files and let people remove them. Treat accept as a picker hint; validate file type and size on the server.
+
+## Verify
+
+Test keyboard file selection, the accessible input name, multiple-file selection, dropzone as an optional path, rejected-file feedback, removal, and server-side validation.
+
+## Common mistake
+
+Treating the accept attribute as security validation or failing silently when a file is rejected.
+
+## Sources
+
+- [developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input/file) (verified 2026-10-17)
+- [developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/accept) (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/footer.md

@@ -2,13 +2,44 @@
 
 Binding: gap
 
-Offer secondary navigation at the end of a page.
+Offer secondary navigation and supporting information at the end of a page.
 
-Use a named footer landmark for site-wide information and group its links by destination. Preserve the site’s repeated navigation order.
+## Use when
+
+Collect site-wide destinations, contact details, and supporting information after the main content.
+
+## Avoid when
+
+Do not use the footer to repeat every page section or create a landmark for a small local card footer.
+
+## Structure
+
+Use a page-level footer landmark and group related destinations into labelled navigation lists. Keep repeated link order consistent across pages.
+
+## Responsive
+
+Allow link groups to wrap or stack while preserving their source order. Avoid clipped columns and tiny tap targets.
+
+## States
+
+Keep destinations available at every viewport; do not hide essential links behind hover-only behavior.
+
+## Verify
+
+Check the landmark structure, labels for multiple navigation regions, keyboard access, and reflow at narrow widths and zoom.
+
+## Common mistake
+
+Using a page-level footer inside a card and unintentionally creating a landmark.
+
+## Custom implementation
+
+Use a semantic footer with headings and navigation lists. This app-level pattern does not add a UIify component.
 
 Related laws: references/laws/readability.md, references/laws/accessibility.md
 
 ## Sources
 
-- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/consistent-navigation.html) (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/landmarks/) (verified 2026-10-17)
+- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/consistent-navigation.html) (verified 2026-10-17)
+- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html) (verified 2026-10-17)

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

@@ -2,13 +2,40 @@
 
 Binding: form
 
-Collect related workspace preferences.
+Collect the information needed to complete one task.
 
-Group related controls and explain the form’s purpose before its fields. Keep submit, validation, and success feedback connected to the form.
+## Use when
+
+Collect the information needed to complete one task, such as signing in, registering, or purchasing. Ask only for information the task needs.
+
+## Avoid when
+
+Do not make a form for a collection of unrelated actions or for navigation alone.
+
+## Structure
+
+`Form` renders a native `<form>` and uses browser validation by default. Label every control; group related choices with `fieldset` and `legend`. Put one clearly named submit action after the fields. `validationBehavior="aria"` sets `noValidate`, so the page must provide its own accessible validation.
+
+## Responsive
+
+A single column is a useful default on narrow screens. Keep each label, control, and its instructions together when the layout changes; UIify `Form` does not impose visual layout.
+
+## States
+
+Support invalid submission, pending submission, success, and server error. Show detected errors in text, identify each affected field, and keep entered values after failure so the person can correct them.
+
+## Verify
+
+Submit empty and malformed values. Confirm browser validation or the page's own validation is active, errors identify the affected controls in text, values remain available after failure, and success and server-error messages are clear.
+
+## Common mistake
+
+Disabling submit before explaining validation can leave people stuck. Let the form explain what needs correction.
 
 Related laws: references/laws/proximity.md, references/laws/accessibility.md
 
 ## Sources
 
-- [www.w3.org](https://www.w3.org/WAI/tutorials/forms/grouping/) (verified 2026-10-16)
-- [www.w3.org](https://www.w3.org/WAI/tutorials/forms/labels/) (verified 2026-10-16)
+- [www.w3.org](https://www.w3.org/WAI/tutorials/forms/grouping/) (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/error-identification.html) (verified 2026-10-17)

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

@@ -4,11 +4,39 @@ Binding: header
 
 Orient visitors with stable top-level navigation.
 
-Use the header for the site identity and primary navigation. Keep repeated navigation in a consistent order and give each navigation landmark a distinct name when there are several.
+## Use when
+
+Orient people with site identity and primary navigation that stays in a consistent place and order across pages.
+
+## Avoid when
+
+Do not turn the header into a second page body or hide all navigation behind a menu on wide screens.
+
+## Structure
+
+`Header.Root` renders a semantic `<header>`. Place a home link for the site identity, a named `<nav>` with primary links, and at most one prominent action. Mark the current page link with `aria-current="page"`. Give repeated navigation landmarks distinct names when their link sets differ.
+
+## Responsive
+
+Keep the logo and one useful action visible on narrow screens. Move secondary navigation behind a clearly named button that opens a `Modal`; leave the full navigation visible on wide screens.
+
+## States
+
+Keep navigation order consistent between pages. The `Header` component itself is static; use `@gunkin/uiify/components/header/client` only when scroll hide/reveal is requested.
+
+## Verify
+
+Inspect the accessibility tree for the banner and named navigation landmarks. Tab through the logo, links, and action in reading order; on narrow screens open and close the menu with the keyboard and check its focus and accessible name.
+
+## Common mistake
+
+Hiding the entire navigation behind a hamburger on desktop makes common destinations harder to scan.
 
 Related laws: references/laws/readability.md, references/laws/accessibility.md
 
 ## Sources
 
-- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/consistent-navigation.html) (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/WCAG22/Understanding/consistent-navigation.html) (verified 2026-10-17)
+- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (verified 2026-10-17)
+- [www.w3.org](https://www.w3.org/WAI/ARIA/apg/practices/landmark-regions/) (verified 2026-10-17)
+- [www.w3.org](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/examples/disclosure-navigation/) (verified 2026-10-17)

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

@@ -4,11 +4,51 @@ Binding: gap
 
 Introduce the product and its next action.
 
-Lead with the page’s primary purpose, a specific heading, and its main action. Add a secondary action only when it serves a different useful path.
+## Use when
+
+Use a hero on a page whose goal is to help people decide what to do next, such as a landing, pricing, or campaign page. Do not add one to settings, dashboards, or docs; start with the task's content.
+
+## Avoid when
+
+Do not lead with a generic slogan, a large decorative image, or multiple equally prominent actions.
+
+## Structure
+
+Start with one specific `h1` that states the page's purpose, one supporting sentence, and one main action. Add a secondary action only for a different useful path. Use an image only when it shows the product or subject and supports the page's claim; prefer existing assets from the project, preserve the focal point across responsive crops, and provide suitable alternative text. If no suitable asset exists, keep the layout complete without inventing one.
+
+## Responsive
+
+On narrow screens, order the text, action, then image. Let translated or long headings wrap, and keep the main action visible without horizontal scrolling.
+
+## States
+
+Check a long or translated heading and the layout when no image is available. Keep action labels and focus states clear in both light and dark themes.
+
+## Verify
+
+Confirm there is one `h1`, the main action is visible at 390×844 and 1440×900, and content reflows at 320 CSS px without two-dimensional scrolling. Check image alternative text against its purpose.
+
+## Common mistake
+
+A generic slogan, decorative gradient, and two equal buttons do not explain the page or the next step.
+
+## Custom implementation
+
+Use a named section, semantic heading, supporting copy, and the documented Button. The main action usually opens another page, so render it as a link. Add only static CSS for layout.
+
+```tsx
+<section aria-labelledby="page-title">
+  <h1 id="page-title">Plan releases your whole team can follow</h1>
+  <p>Orbit turns scattered tasks into one shared release timeline.</p>
+  <Button as="a" href="/signup">Start a free trial</Button>
+</section>
+```
 
 Related laws: references/laws/von-restorff.md, references/laws/accessibility.md
 
 ## Sources
 
-- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html) (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/WCAG22/Understanding/use-of-color.html) (verified 2026-10-17)
+- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (verified 2026-10-17)
+- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html) (verified 2026-10-17)
+- [www.w3.org](https://www.w3.org/WAI/tutorials/images/) (verified 2026-10-17)

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

@@ -0,0 +1,38 @@
+# hover-card
+
+Binding: hover-card
+
+A link or control has useful supplementary detail that a person may inspect on hover or keyboard focus without leaving the current page
+
+## Use when
+
+A link or control has useful supplementary detail that a person may inspect on hover or keyboard focus without leaving the current page. Keep it optional and short.
+
+## Avoid when
+
+Do not place essential instructions, required actions, or the only copy of important information in a hover card. Do not use it for a brief label (tooltip) or a menu of actions.
+
+## Structure
+
+Compose `HoverCard` Root, Trigger, and Content. Give the trigger a meaningful name on its own; the card supplements it rather than repairing an ambiguous link label.
+
+## Responsive
+
+The card opens on mouse hover and keyboard focus. Touch users need the same essential information elsewhere in the page and a usable trigger. Keep content narrow enough to fit without obscuring nearby controls.
+
+## States
+
+Focus or mouse hover opens the card; pointer movement into the content keeps it open, and leaving schedules close. Configure open/close delays only when they improve pointer travel without making content feel unresponsive.
+
+## Verify
+
+Test keyboard focus, mouse travel from trigger to card, dismissibility, persistence while moving the pointer, narrow viewports, and that all essential content remains available without hover.
+
+## Common mistake
+
+A hover card that closes while the pointer travels from its trigger to its content fails the hover/focus content requirements.
+
+## Sources
+
+- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/content-on-hover-or-focus.html) (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/image-gallery.md

@@ -4,17 +4,49 @@ Binding: gap
 
 Show related images with useful captions or alternatives.
 
-Represent a gallery as a list of figures. Give each image an alternative that conveys its content and use a caption when the surrounding text needs context.
+## Use when
+
+A related set of images benefits from being browsed together with captions or contextual text.
+
+## Avoid when
+
+Do not build a gallery if one image answers the need. Do not hide the only useful visual information behind a lightbox with no inline alternative.
+
+## Structure
+
+This is an app-level composition, not a UIify component. Use a list of figures. Write alt text for the image's purpose; use figcaption for additional context, avoiding redundant repetition.
+
+## Responsive
+
+Prefer existing project assets. Keep images within their container, preserve intrinsic ratio and important content in responsive crops, and allow the list to stack. Provide intrinsic width and height to reduce layout shift.
+
+## States
+
+If images open a larger view, use a real link or button with an accessible name and a way back. Do not imply gallery navigation when items are static.
+
+## Verify
+
+Check informative/decorative alternatives, captions, loading and intrinsic dimensions, keyboard access for interactive images, and narrow reflow.
+
+## Common mistake
+
+Using the same sentence as both alt text and caption can produce repetitive announcements when both convey identical information.
+
+## Custom implementation
 
 ```html
 <ul>
-  <li><figure><img src="/place.webp" width="640" height="400" alt="Stone bridge over a river" /><figcaption>Old town bridge</figcaption></figure></li>
+  <li><figure>
+    <img src="/bridge.webp" width="640" height="400" alt="Stone bridge over a river" />
+    <figcaption>Old town bridge at dusk</figcaption>
+  </figure></li>
 </ul>
 ```
 
-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/figure) (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/Element/img) (verified 2026-10-16)
+- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/non-text-content.html) (verified 2026-10-16)

package/skills/uiify/references/elements/inline-alert.md

@@ -4,13 +4,41 @@ Binding: gap
 
 Give a short message context beside the content it affects.
 
-Use a status announcement for non-urgent updates and an alert only for information requiring immediate attention. Keep the message visible in context.
+## Use when
+
+A message belongs beside the content or control it explains. Use status for a non-urgent update and alert only when the information requires immediate attention.
+
+## Avoid when
+
+Do not use assertive announcements for routine success, or a toast for an error that must remain visible while the person fixes it.
+
+## Structure
+
+This is an app-level composition, not a UIify component. Place concise text in a semantic status/alert element next to the affected content; include a heading when it helps identify the issue.
+
+## Responsive
+
+Keep the message in reading order beside the affected field or section. Let text wrap and do not communicate severity by color alone.
+
+## States
+
+Use role=status for dynamic, non-urgent updates; use role=alert for urgent messages that should be announced immediately. Keep the message visible until the related issue can be addressed.
+
+## Verify
+
+Check announcement timing and role, reading order, message visibility, color contrast, and the relationship to its field/section. Avoid repeating the same announcement through multiple live regions.
+
+## Common mistake
+
+Do not move focus to routine status text; the live region should announce the update while focus stays on the user's task.
+
+## Custom implementation
 
 ```html
 <p role="status">Changes saved.</p>
 ```
 
-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/input.md

@@ -2,13 +2,40 @@
 
 Binding: input
 
-Accept a short text value.
+Accept a short, single-line value.
 
-Give each text input a persistent visible label. Use helper and error text for format or validation details rather than relying on a placeholder.
+## Use when
+
+Collect one short value such as a name, email address, or search query.
+
+## Avoid when
+
+Use a textarea for longer free text and a purpose-specific control when it provides a more suitable native input mode.
+
+## Structure
+
+Use the documented Input component with an associated visible label. Put format instructions before entry and connect them to the field; keep validation feedback beside the control.
+
+## Responsive
+
+Let the field and label reflow within the available width. Keep the label visible and avoid horizontal page scrolling.
+
+## States
+
+Preserve entered values when validation fails. Distinguish disabled, read-only, and invalid states, and explain the correction in text.
+
+## Verify
+
+Check the label association, input purpose and autocomplete where relevant, keyboard access, error description, and narrow-screen reflow.
+
+## Common mistake
+
+Using a placeholder as the only label or instruction.
 
 Related laws: references/laws/proximity.md, references/laws/accessibility.md
 
 ## Sources
 
-- [www.w3.org](https://www.w3.org/WAI/tutorials/forms/grouping/) (verified 2026-10-16)
-- [www.w3.org](https://www.w3.org/WAI/tutorials/forms/labels/) (verified 2026-10-16)
+- [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)
+- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html) (verified 2026-10-17)

package/skills/uiify/references/elements/line-chart.md

@@ -0,0 +1,38 @@
+# line-chart
+
+Binding: line-chart
+
+A measured value changes over an ordered time or numeric axis and the trend is useful
+
+## Use when
+
+A measured value changes over an ordered time or numeric axis and the trend is useful.
+
+## Avoid when
+
+Do not connect unrelated categories with a line or imply precision/time continuity the data does not have. For a few independent categories, use a table or bar chart.
+
+## Structure
+
+Use `LineChart` with ordered time/value data, a descriptive accessible label, and axis labels that include units/context. UIify renders a data table fallback. Import the component entry for static rendering; use /client only for interactive points or live history.
+
+## Responsive
+
+Keep the data table available as the plot narrows. For live history, 'visibleCount' virtualizes older points and the table follows the visible window; provide another route to full history when users need it.
+
+## States
+
+The static component needs no JavaScript. Interactive points use labeled buttons; the client entry adds live readout behavior. Disable announcements for high-frequency streaming updates when repeated speech would overwhelm.
+
+## Verify
+
+Check exact values in the table, time/unit labels, trend description, keyboard point controls if enabled, data updates, and narrow viewport.
+
+## Common mistake
+
+A default “Line chart” name does not explain which measure, unit, or period the chart shows.
+
+## Sources
+
+- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/non-text-content.html) (verified 2026-10-17)
+- [www.w3.org](https://www.w3.org/WAI/tutorials/images/complex/) (verified 2026-10-17)

package/skills/uiify/references/elements/logo-wall.md

@@ -4,7 +4,35 @@ Binding: gap
 
 Show organizations associated with a product or event.
 
-Give each meaningful organization logo an identifying alternative. If the adjacent text already names it, use an empty alternative to avoid repetition.
+## Use when
+
+A small collection of customer, partner, or member organizations provides relevant context.
+
+## Avoid when
+
+Do not present logos as proof of endorsement without permission, or include a large wall of brands that does not help the current decision.
+
+## Structure
+
+This is an app-level composition, not a UIify component. Use a list. Give each informative logo an alt text with the organization's name; use empty alt only when adjacent text already names it.
+
+## Responsive
+
+Preserve recognizable proportions and allow the list to wrap. Avoid raster logos that become blurry or require horizontal scrolling.
+
+## States
+
+If a logo links somewhere, give the link a meaningful accessible name and a real destination. If not interactive, do not make it look like a control.
+
+## Verify
+
+Check each image alternative, adjacent duplicate text, logo proportions, list reading order, link purpose, and mobile wrapping.
+
+## Common mistake
+
+An empty alt on an informative logo hides the organization name from screen readers.
+
+## Custom implementation
 
 ```html
 <ul aria-label="Organizations using the product">
@@ -12,9 +40,10 @@ Give each meaningful organization logo an identifying alternative. If the adjace
 </ul>
 ```
 
-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/img) (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/WCAG22/Understanding/non-text-content.html) (verified 2026-10-16)

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

@@ -0,0 +1,38 @@
+# modal
+
+Binding: modal
+
+Hold attention on a task that must be completed before returning to the page.
+
+## Use when
+
+The person must finish or dismiss a focused task before returning to the page. Use inline content when they need to compare it with the page; use `toast` for brief feedback and `alert-modal` for an irreversible decision.
+
+## Avoid when
+
+Do not open a modal automatically on page load or use one for content most visitors need to read.
+
+## Structure
+
+`Modal` provides a trigger, named dialog, title, optional description and body, close control, and optional footer. Give it a specific title, concise body, and clearly labeled actions. A modal dialog contains its Tab sequence; include a visible way to close it.
+
+## Responsive
+
+On narrow screens the default modal becomes a full-width bottom sheet. Its body scrolls while the header and footer remain visible. Keep the task short enough to understand and complete in this space.
+
+## States
+
+The native `show-modal` dialog blocks interaction with the page. Its default dismissal allows Escape; `dismiss="none"` requires an explicit close action. Controlled or initially open state requires `ModalClientContent` from `@gunkin/uiify/components/modal/client`.
+
+## Verify
+
+Open from the keyboard. Confirm focus enters the dialog, stays within its Tab sequence, Escape closes it when dismissal is enabled, focus returns to the trigger, and the dialog has its visible title as its accessible name. Check long content and footer actions at a narrow viewport.
+
+## Common mistake
+
+A generic title such as “Notice” does not explain the task. Name the decision or activity instead.
+
+## 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)