@gunkin/uiify 0.0.17-alpha → 0.0.20-alpha

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

@@ -0,0 +1,41 @@
+# 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.
+
+Set `locale` to control both number formatting and parsing, including locale-specific digits and separators.
+
+## 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

@@ -2,13 +2,42 @@
 
 Binding: pagination
 
-Navigate the pages of a result set.
+Navigate between pages of a result set.
 
-Make the current page clear in text and expose it as the current page. Keep previous and next actions named and disable them at the ends.
+## Use when
+
+Let people move through a result set split into discrete pages.
+
+Set `locale` to format page numbers, and translate the `labels.page` template using its `{page}` placeholder.
+
+## 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/tutorials/forms/labels/) (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/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

@@ -2,18 +2,42 @@
 
 Binding: gap
 
-Collect a secret string while the browser masks entered characters.
+Collect a password while allowing password managers to help users enter it.
 
-Use a visible label, the appropriate autocomplete value, and nearby password requirements. Keep entered values when showing validation errors.
+## Use when
 
-```html
-<label for="account-password">Password</label>
-<input id="account-password" name="password" type="password" autocomplete="current-password" />
-```
+Collect a current or new account password.
 
-This is an app-level composition recipe; it does not add a component to UIify.
+## 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/Element/input/password) (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/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

@@ -4,10 +4,63 @@ Binding: gap
 
 Let visitors compare plan features and choose a plan.
 
-Compare plans using the same feature order and clearly associate each action with its plan. Explain meaningful differences without making color the only signal.
+## 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-16)
+- [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

@@ -4,16 +4,44 @@ Binding: gap
 
 Show determinate completion of a task.
 
-Give the progress value a visible label and range. Include text that explains completion when the visual meter is unavailable.
+## 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">3 of 5</progress>
+<progress id="upload-progress" value="3" max="5"></progress>
 ```
 
-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/progress) (verified 2026-10-16)
+- [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)

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

@@ -2,13 +2,44 @@
 
 Binding: gap
 
-Find records within the current table.
+Find records in a collection or page.
 
-Give search a visible label and identify the collection it searches. Keep filters and pagination near the result list and announce result changes when they update.
+## Use when
+
+Help people find a record or content within a defined collection.
+
+## Avoid when
+
+Do not use a search field when the collection is small and browsing its links is clearer.
+
+## Structure
+
+Use a labelled search form and a native search input. Identify the collection being searched and keep filters, results, and pagination in a clear reading order.
+
+## Responsive
+
+Allow the field and result controls to wrap without clipping. Keep result content usable at narrow widths and zoom.
+
+## States
+
+Explain empty and no-match results separately. When results update without a page navigation, announce a concise result status.
+
+## Verify
+
+Check the visible label, submitted query behavior, empty/no-match states, keyboard access, and result announcement when updates are dynamic.
+
+## Common mistake
+
+Showing a magnifying-glass icon without an accessible name for the search field.
+
+## Custom implementation
+
+Use a search form with an associated label and an input of type search. This app-level recipe does not add a UIify search-input component.
 
 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-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/search) (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/status-messages.html) (verified 2026-10-17)

package/skills/uiify/references/elements/segmented-control.md

@@ -0,0 +1,39 @@
+# segmented-control
+
+Binding: segmented-control
+
+Choose one value from a short set of mutually exclusive options.
+
+## Use when
+
+Let people switch among a few short, mutually exclusive values, such as a billing period or view mode.
+
+## Avoid when
+
+Use ordinary links for navigation and Tabs only when each choice opens a corresponding panel. Prefer a select for many options or long labels.
+
+## Structure
+
+Use SegmentedControl with a stable id and items that each have a value and label. Give the group an accessible name, and show the selected option with the component's native radio semantics.
+
+## Responsive
+
+Allow the group to fit or stack at narrow widths without truncating labels or shrinking the targets.
+
+## States
+
+Keep one value selected and update the associated content or setting when the selection changes. Use the documented client entry only when controlled state is required.
+
+## Verify
+
+Test arrow-key selection, keyboard focus, group name, visible selected state, narrow-width layout, and that dependent content reflects the chosen value.
+
+## Common mistake
+
+Styling unrelated navigation links as segmented options and hiding their link behavior.
+
+## 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/WCAG22/Understanding/reflow.html) (verified 2026-10-17)

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

@@ -4,7 +4,35 @@ Binding: select
 
 Choose one value from a fixed list.
 
-Use a visible label and choose a native select for a finite list of options unless the task needs a different interaction. Preserve the selected value when validation fails.
+## Use when
+
+Choose one value from a finite list, especially when the form benefits from a native control.
+
+## Avoid when
+
+Avoid a select when users must compare several options at once or when the task needs a richer search or selection interaction.
+
+## Structure
+
+Associate a visible label with the select. Group related options with `optgroup` and provide an empty prompt only when the value is genuinely optional.
+
+## Responsive
+
+Keep the native control usable at narrow widths and browser zoom; do not depend on a fixed-width option label.
+
+## States
+
+Preserve the selected value after validation errors. Use native disabled, required, and invalid form semantics.
+
+## Verify
+
+Confirm the label is announced, options can be selected by keyboard, and the chosen value survives an invalid submission.
+
+## Common mistake
+
+Replacing a native select with a custom popup without a clear interaction need.
+
+Example: `references/examples/select-basic.md`.
 
 Related laws: references/laws/proximity.md, references/laws/accessibility.md
 

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

@@ -2,19 +2,42 @@
 
 Binding: gap
 
-Provide a secondary set of links for a site or application section.
+Provide secondary navigation for a site or application section.
 
-Use a named navigation landmark with a list of destinations. Mark the current destination and keep the link order consistent across pages.
+## Use when
 
-```html
-<nav aria-label="Workspace">
-  <ul><li><a href="/projects" aria-current="page">Projects</a></li></ul>
-</nav>
-```
+Provide a stable set of destinations within a larger site or application section.
 
-This is an app-level composition recipe; it does not add a component to UIify.
+## Avoid when
+
+Do not use a sidebar for a short set of links that fits naturally in the page header or content.
+
+## Structure
+
+Use a nav landmark with a concise accessible name and a list of links. Group links under headings only when the groups help people find destinations. Mark the current destination with aria-current="page".
+
+## Responsive
+
+At narrow widths, place navigation in the document flow or expose it through a clearly named disclosure control. Keep DOM and keyboard order aligned with the page.
+
+## States
+
+Show the current location in text or semantics, and preserve it when the navigation collapses or expands.
+
+## Verify
+
+Check the landmark name when the page has multiple navigation regions, the current link state, keyboard access, and narrow-screen reflow.
+
+## Common mistake
+
+Using a second navigation landmark with the same name for a different set of destinations.
+
+## Custom implementation
+
+Use a named nav containing grouped lists of ordinary links. This app-level pattern does not add a UIify component.
 
 ## Sources
 
-- [developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/nav) (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/examples/navigation.html) (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/info-and-relationships.html) (verified 2026-10-17)

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

@@ -0,0 +1,38 @@
+# skeleton
+
+Binding: skeleton
+
+A known content layout is temporarily loading and a close shape preview can reduce the perception of a blank page
+
+## Use when
+
+A known content layout is temporarily loading and a close shape preview can reduce the perception of a blank page.
+
+## Avoid when
+
+Do not use skeletons for unknown layout, short waits, or as a substitute for an announced loading state. Do not present a false preview that suggests content is already available.
+
+## Structure
+
+Use `Skeleton` only around content that will occupy the same space. Match the approximate width, height, and shape; keep a separate status message when the loading state needs announcement.
+
+## Responsive
+
+Match the real content's responsive geometry and reserve its space so the page does not shift when it arrives.
+
+## States
+
+While loading, Skeleton is aria-hidden and does not render children. When loading becomes false, it renders the actual children. Pulse/shimmer/none variants are available; motion is reduced by shipped styles.
+
+## Verify
+
+Check loading and loaded transitions, no duplicate announcements, geometry at narrow widths, reduced motion, and that the final content replaces the placeholder.
+
+## Common mistake
+
+Do not expose placeholder blocks as meaningful content or rely on their movement to announce progress.
+
+## Sources
+
+- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html) (verified 2026-10-17)
+- [developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion) (verified 2026-10-17)