@gunkin/uiify 0.0.16-alpha → 0.0.19-alpha

package/skills/uiify/references/elements/image-gallery.md

@@ -0,0 +1,52 @@
+# image-gallery
+
+Binding: gap
+
+Show related images with useful captions or alternatives.
+
+## 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="/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; 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)
+- [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

@@ -0,0 +1,46 @@
+# inline-alert
+
+Binding: gap
+
+Give a short message context beside the content it affects.
+
+## 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; UIify does not currently ship this component.
+
+## Sources
+
+- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html) (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/input.md

@@ -0,0 +1,41 @@
+# input
+
+Binding: input
+
+Accept a short, single-line value.
+
+## 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/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

@@ -0,0 +1,49 @@
+# logo-wall
+
+Binding: gap
+
+Show organizations associated with a product or event.
+
+## 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">
+  <li><img src="/logos/acme.svg" width="120" height="40" alt="Acme" /></li>
+</ul>
+```
+
+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)

package/skills/uiify/references/elements/number-field.md

@@ -0,0 +1,39 @@
+# number-field
+
+Binding: number-field
+
+Enter a numeric quantity with optional bounds and step controls.
+
+## Use when
+
+Enter a quantity for which numeric stepping and bounds are meaningful.
+
+## Avoid when
+
+Do not use a number field for identifiers, postal codes, card numbers, or values where spinbutton behavior is not useful; use a text input instead.
+
+## Structure
+
+Use NumberField.Root with NumberField.Input and the documented increment/decrement buttons when those actions help. Give the input an a clear visible label and explain units, min/max, and step before entry. Give icon-only increment/decrement buttons accessible names.
+
+## Responsive
+
+Keep the input and controls operable at narrow widths; do not make the input so small that the value is hard to inspect or edit.
+
+## States
+
+Show the current value and bounds clearly. Validate the same constraints on the server; browser-side constraints alone do not protect submitted data.
+
+## Verify
+
+Test typing, increment/decrement, keyboard operation, min/max/step boundaries, invalid values, and the accessible name of each icon-only control.
+
+## Common mistake
+
+Using number input for a numeric-looking identifier that must retain leading zeroes.
+
+## Sources
+
+- [developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input/number) (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/otp-input.md

@@ -0,0 +1,39 @@
+# otp-input
+
+Binding: otp-input
+
+Collect a one-time verification code as one value.
+
+## Use when
+
+Collect a short one-time code as one verification value.
+
+## Avoid when
+
+Do not split a code into independently labelled fields that require users to move between separate controls. Do not rely on SMS codes as the only factor for account security.
+
+## Structure
+
+Use OtpInput.Root, one OtpInput.Slot per position, and OtpInput.HiddenInput. UIify HiddenInput exposes the accessible name “One-time code” and uses autocomplete one-time-code. Keep visible instructions beside the slots that explain where the code comes from.
+
+## Responsive
+
+Keep every slot visible and large enough to inspect at narrow widths and zoom. Do not force horizontal page scrolling.
+
+## States
+
+Distinguish incomplete, complete, disabled, and invalid submission feedback. Keep the single code value available for paste and autofill.
+
+## Verify
+
+Test typing, paste, one-time-code autofill, keyboard navigation, accessible naming, invalid attempts, and the complete value reaching the form.
+
+## Common mistake
+
+Making each visual digit a separate text field that interrupts autofill and paste.
+
+## Sources
+
+- [developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/Security/Authentication/OTP) (verified 2026-10-17)
+- [developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/autocomplete) (verified 2026-10-17)
+- [www.w3.org](https://www.w3.org/WAI/tutorials/forms/labels/) (verified 2026-10-17)

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

@@ -0,0 +1,41 @@
+# pagination
+
+Binding: pagination
+
+Navigate between pages of a result set.
+
+## Use when
+
+Let people move through a result set split into discrete pages.
+
+## Avoid when
+
+Do not paginate a small result set that is easier to scan as one list, or imply that ellipses are links.
+
+## Structure
+
+Use Pagination.Root with a specific navigation label and the documented count. Provide descriptive names for previous/next controls, expose the current page with selected, and use getPageHref when pages are navigable URLs.
+
+## Responsive
+
+Keep the current page and adjacent navigation available; reduce distant page links before shrinking targets or labels.
+
+## States
+
+Disable controls at the ends of the range and preserve the current page when results update. If the result set changes, announce the updated result context.
+
+## Verify
+
+Check the navigation name, current-page semantics, end states, keyboard focus order, and that each URL or action reaches the stated page.
+
+## Common mistake
+
+Showing a selected page only by color or leaving a previous/next control active at a boundary.
+
+Related laws: references/laws/proximity.md, references/laws/accessibility.md
+
+## Sources
+
+- [www.w3.org](https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/examples/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/WCAG22/Understanding/focus-order.html) (verified 2026-10-17)

package/skills/uiify/references/elements/password-input.md

@@ -0,0 +1,43 @@
+# password-input
+
+Binding: gap
+
+Collect a password while allowing password managers to help users enter it.
+
+## Use when
+
+Collect a current or new account password.
+
+## Avoid when
+
+Do not disable password managers or hide password requirements until after submission.
+
+## Structure
+
+Use a labelled native password input. Set autocomplete to current-password for sign-in or new-password when creating or changing a password. Present requirements before entry.
+
+## Responsive
+
+Keep the label, requirements, reveal control, and error text visible at narrow widths and zoom.
+
+## States
+
+If a show/hide control is provided, make it a keyboard-operable button with an action-specific accessible name and preserve the entered value when toggling. Keep errors next to the field.
+
+## Verify
+
+Test label association, password-manager autofill, keyboard operation of any reveal button, preservation of the value, and clear validation feedback.
+
+## Common mistake
+
+Setting autocomplete to off or clearing a valid password when another field fails.
+
+## Custom implementation
+
+Use a label and native input with type password; choose current-password or new-password to match the form. This app-level recipe does not add a UIify password-input component.
+
+## Sources
+
+- [developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input/password) (verified 2026-10-17)
+- [developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/autocomplete) (verified 2026-10-17)
+- [www.w3.org](https://www.w3.org/WAI/tutorials/forms/labels/) (verified 2026-10-17)

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

@@ -0,0 +1,38 @@
+# popup
+
+Binding: popup
+
+A small, optional piece of contextual content belongs beside its trigger and can be opened without blocking the page
+
+## Use when
+
+A small, optional piece of contextual content belongs beside its trigger and can be opened without blocking the page. Use it for a short explanation, compact detail, or lightweight choice.
+
+## Avoid when
+
+Do not use a popup for an urgent alert, a task requiring modal focus containment, or essential information available only on hover. Use a menu for a set of commands.
+
+## Structure
+
+Use `PopupTrigger` with a stable target id and matching PopupContent; add PopupClose when users need an explicit close action. Keep content concise and label interactive controls.
+
+## Responsive
+
+Let content wrap and keep it within the viewport at narrow widths and zoom. Check the chosen side and alignment around viewport edges.
+
+## States
+
+Tier 0 native popover parts work without client JavaScript. 'mode="auto"' supports light dismissal; 'manual' requires explicit dismissal. The parts do not set 'aria-expanded'; cross-engine exposure is not yet established.
+
+## Verify
+
+Test invoker by pointer and keyboard, close behavior for the chosen mode, focus order, target id wiring, and placement at narrow widths. Inspect the accessibility tree in each supported browser; do not assume expanded state is exposed identically.
+
+## Common mistake
+
+Do not put essential instructions only in content that appears on hover.
+
+## Sources
+
+- [developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/popover) (verified 2026-10-17)
+- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/content-on-hover-or-focus.html) (verified 2026-10-17)

package/skills/uiify/references/elements/pricing-table.md

@@ -0,0 +1,66 @@
+# pricing-table
+
+Binding: gap
+
+Let visitors compare plan features and choose a plan.
+
+## Use when
+
+Help people compare two to four plans and choose one. Show the same categories in the same order so meaningful differences are easy to find.
+
+## Avoid when
+
+Do not present plans as cards if the contents cannot be compared, or use color alone to identify a recommended option.
+
+## Structure
+
+For each plan, show its name, price and billing period, who it suits, key feature differences, and one action. Give each action a name that identifies its plan, such as “Choose Pro.” Mark a recommended plan with visible text as well as any styling.
+
+## Responsive
+
+Stack plans on narrow screens in the same reading order. Keep plan names, prices, differences, and actions together; allow long names and feature descriptions to wrap.
+
+## States
+
+If people can switch billing periods, use the documented `segmented-control` and update both the price and its period label. Check long plan names and feature lists without clipping.
+
+## Verify
+
+Compare all plans at desktop and narrow widths. Confirm that each price has a period, each action's accessible name identifies its plan, and any recommended plan is identified in text.
+
+## Common mistake
+
+Giving every plan an identical “Get started” action makes it unclear which option the action will select.
+
+## Custom implementation
+
+Use a named section with one article per plan, a comparable list of features, and a documented Button with a plan-specific label.
+
+```tsx
+<section aria-labelledby="plans-heading">
+  <h2 id="plans-heading">Choose a plan</h2>
+  <div className="plans">
+    <article aria-labelledby="starter-name">
+      <h3 id="starter-name">Starter</h3>
+      <p>$12 per month</p>
+      <ul><li>Three projects</li><li>Email support</li></ul>
+      <Button>Choose Starter</Button>
+    </article>
+    <article aria-labelledby="pro-name">
+      <h3 id="pro-name">Pro</h3>
+      <p>$24 per month</p>
+      <p>Recommended</p>
+      <ul><li>Unlimited projects</li><li>Priority support</li></ul>
+      <Button>Choose Pro</Button>
+    </article>
+  </div>
+</section>
+```
+
+Related laws: references/laws/proximity.md
+
+## Sources
+
+- [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/use-of-color.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/progress-bar.md

@@ -0,0 +1,47 @@
+# progress-bar
+
+Binding: gap
+
+Show determinate completion of a task.
+
+## Use when
+
+A task has measurable completion with a known range. Use native <progress> and provide a programmatic label.
+
+## Avoid when
+
+Do not use it for a quantity like disk space or a score; use <meter>. For unknown duration, omit value for indeterminate progress or use a labeled spinner.
+
+## Structure
+
+This is an app-level composition, not a UIify component. Associate a visible <label> with <progress>, set max and the current value, and add a text status if the exact progress matters to the task.
+
+## Responsive
+
+Keep the label and progress indicator together in reading order; allow the label and textual status to wrap on narrow screens.
+
+## States
+
+A present value is determinate; omit value when the amount completed is not known. Use a positive max and keep value within 0..max. Mark the described region busy while it is updating when appropriate.
+
+## Verify
+
+Check accessible name, min/max/current values, determinate and indeterminate states, changing value, completion message, and responsive layout.
+
+## Common mistake
+
+Fallback text inside <progress> is not its accessible label; associate an actual label or aria-label.
+
+## Custom implementation
+
+```html
+<label for="upload-progress">Upload</label>
+<progress id="upload-progress" value="3" max="5"></progress>
+```
+
+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/Reference/Elements/progress) (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/radio-group.md

@@ -0,0 +1,39 @@
+# radio-group
+
+Binding: radio-group
+
+Choose exactly one option from a related set.
+
+## Use when
+
+Ask people to select one value from a small, mutually exclusive set.
+
+## Avoid when
+
+Use checkboxes for independent options and a select when the choice set is too long to scan inline.
+
+## Structure
+
+Use RadioGroup with a stable id, a name, and items that each have a value and descriptive label. Give the group a visible legend or an accessible name that describes the question.
+
+## Responsive
+
+Use the documented orientation that matches the layout, and let long labels wrap without changing the option order.
+
+## States
+
+Keep exactly one selected value when a selection is required; if the form requires a choice, state that before entry. Preserve selection when validation fails.
+
+## Verify
+
+Test arrow-key movement, Tab entry/exit, label activation, disabled options, group naming, and submitted value.
+
+## Common mistake
+
+Presenting visually grouped radios without a programmatic group name.
+
+## Sources
+
+- [www.w3.org](https://www.w3.org/WAI/ARIA/apg/patterns/radio/) (verified 2026-10-17)
+- [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)

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

@@ -0,0 +1,39 @@
+# rating
+
+Binding: rating
+
+Collect a numeric rating on a short ordered scale.
+
+## Use when
+
+Collect one value on a short ordered rating scale, such as a one-to-five star rating.
+
+## Avoid when
+
+Do not use stars for a binary choice or as the only way to report a detailed evaluation.
+
+## Structure
+
+Use the documented Rating with a stable id, a group name in aria-label, and an appropriate max. Each radio option exposes its star count as text; pair the scale with visible instructions that explain what low and high values mean.
+
+## Responsive
+
+Keep every rating option visible and large enough to select at narrow widths.
+
+## States
+
+Distinguish an unanswered rating from a selected value. Use readOnly for display-only ratings; use the client entry only when controlled updates are required.
+
+## Verify
+
+Test arrow-key selection, group and option names, value submission, read-only and disabled states, and whether users can tell what each end of the scale means.
+
+## Common mistake
+
+Showing decorative stars without a text name for the group or the value of each option.
+
+## Sources
+
+- [www.w3.org](https://www.w3.org/WAI/ARIA/apg/patterns/radio/) (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/info-and-relationships.html) (verified 2026-10-17)