@gunkin/uiify 0.0.16-alpha → 0.0.19-alpha

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

@@ -0,0 +1,45 @@
+# search-input
+
+Binding: gap
+
+Find records in a collection or page.
+
+## 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
+
+- [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

@@ -0,0 +1,42 @@
+# select
+
+Binding: select
+
+Choose one value from a fixed list.
+
+## 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
+
+## 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)

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

@@ -0,0 +1,43 @@
+# sidebar
+
+Binding: gap
+
+Provide secondary navigation for a site or application section.
+
+## Use when
+
+Provide a stable set of destinations within a larger site or application section.
+
+## 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
+
+- [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)

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

@@ -0,0 +1,39 @@
+# slider
+
+Binding: slider
+
+Set a value within a continuous or stepped range.
+
+## Use when
+
+Let people adjust a value within meaningful lower and upper bounds.
+
+## Avoid when
+
+Use a number field when people need exact numeric entry or the range has too many meaningful values to scan.
+
+## Structure
+
+Use the documented Slider for one value and label it with the quantity and units. State the current value in adjacent text when it is not otherwise clear; set min, max, and step to match the task. Use SliderClient for a range with two thumbs, labels, or marks.
+
+## Responsive
+
+Keep the track and thumb operable at narrow widths. Do not communicate the selected value by thumb position or color alone.
+
+## States
+
+Expose the current value, bounds, step, and disabled state. Keep a numeric text entry alternative when precise adjustment is important.
+
+## Verify
+
+Test keyboard adjustment, endpoints, step increments, accessible name and value, touch screen-reader operation, and any alternative numeric entry.
+
+## Common mistake
+
+Showing a slider without a visible label or a way to understand its current value.
+
+## Sources
+
+- [www.w3.org](https://www.w3.org/WAI/ARIA/apg/patterns/slider/) (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/keyboard.html) (verified 2026-10-17)

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

@@ -0,0 +1,38 @@
+# spinner
+
+Binding: spinner
+
+A task is actively pending and there is no reliable completion percentage
+
+## Use when
+
+A task is actively pending and there is no reliable completion percentage. Pair the indicator with a short label that says what is waiting.
+
+## Avoid when
+
+Do not show a spinner for a task with measurable progress; use a labeled progress element. Avoid showing it for work that completes too quickly to perceive.
+
+## Structure
+
+Use `Spinner` with a specific label. Its status role and polite live region announce the label; use showLabel when the text should also be visible.
+
+## Responsive
+
+Keep the indicator near the task it describes, reserve enough space to prevent layout jumps, and do not let fixed positioning obscure controls.
+
+## States
+
+The delay prop writes a delayed state marker; shipped CSS disables animation in that state, but does not hide the element or schedule a timer. The component supports sm/md/lg sizes and center/fixed/absolute alignment. Motion respects reduced-motion preferences in UIify styles.
+
+## Verify
+
+Check the announced label, visible label when needed, the delayed marker behavior, alignment at narrow widths, and reduced-motion rendering. Ensure completion removes the status.
+
+## Common mistake
+
+A spinner without a meaningful label says that something is happening but not what the person is waiting for. Do not treat `delay` as a timer that hides the indicator.
+
+## 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)

package/skills/uiify/references/elements/stats-bar.md

@@ -0,0 +1,49 @@
+# stats-bar
+
+Binding: gap
+
+Summarize a few named values for one subject or time period.
+
+## Use when
+
+A few named values summarize one subject, population, and time period.
+
+## Avoid when
+
+Do not show unlabeled numbers, mix unlike periods/populations, or use a stats bar when people need detailed comparisons or exploration.
+
+## Structure
+
+This is an app-level composition, not a UIify component. Use a description list for term/value pairs and label units and the time period in text.
+
+## Responsive
+
+Let each label/value pair wrap and keep pairs together. Preserve source order as columns collapse.
+
+## States
+
+For values that update, explain their meaning and update timing; announce important changes without repeatedly interrupting users.
+
+## Verify
+
+Check labels, units, period, number formatting, reading order, and narrow layout. Ensure decoration does not carry the only meaning.
+
+## Common mistake
+
+“1,248” without a label, unit, or period is not an interpretable metric.
+
+## Custom implementation
+
+```html
+<dl>
+  <div><dt>Active users</dt><dd>1,248</dd></div>
+  <div><dt>Period</dt><dd>Last 30 days</dd></div>
+</dl>
+```
+
+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/dl) (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/stepper.md

@@ -0,0 +1,43 @@
+# stepper
+
+Binding: gap
+
+Show ordered steps and identify the current step in a multi-step task.
+
+## Use when
+
+Show the sequence and current position in a multi-step task.
+
+## Avoid when
+
+Do not use a stepper for unrelated navigation or suggest that future steps are already complete.
+
+## Structure
+
+Use an ordered list in task order. Identify the current step with aria-current="step" and provide concise step names.
+
+## Responsive
+
+Keep the current step and sequence understandable when labels wrap or the list becomes compact.
+
+## States
+
+Distinguish completed, current, and upcoming steps in text or semantics, not color alone. Update the current marker only when the task advances.
+
+## Verify
+
+Check list order, current-step announcement, keyboard sequence through any step links, and narrow-screen reading order.
+
+## Common mistake
+
+Marking every past step complete when users can still need to correct its information.
+
+## Custom implementation
+
+Render the sequence as an ol and set aria-current="step" on the current item. This task-progress pattern does not add a UIify component.
+
+## Sources
+
+- [www.w3.org](https://www.w3.org/TR/wai-aria-1.2/#aria-current) (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/switch.md

@@ -0,0 +1,41 @@
+# switch
+
+Binding: switch
+
+Expose a binary setting that takes effect immediately.
+
+## Use when
+
+Let a person turn a persistent setting on or off and apply the change immediately.
+
+## Avoid when
+
+Use a checkbox for a form choice that is applied on submit, or a button for a one-time action.
+
+## Structure
+
+Use the documented Switch with a stable visible label that describes the setting. Keep the label unchanged as the state changes, and expose the current checked state.
+
+## Responsive
+
+Keep the label and control together as they wrap. Ensure the complete control remains operable at narrow widths.
+
+## States
+
+Make on, off, and disabled states clear. If changing the setting triggers remote work, communicate pending and failure feedback in text.
+
+## Verify
+
+Test label activation, Space-key operation, checked-state announcement, persistence after navigation, and feedback for failed updates.
+
+## Common mistake
+
+Using a switch for a form value that does not take effect until the user submits.
+
+Related laws: references/laws/proximity.md, references/laws/accessibility.md
+
+## Sources
+
+- [www.w3.org](https://www.w3.org/WAI/ARIA/apg/patterns/switch/) (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/table-of-contents.md

@@ -0,0 +1,39 @@
+# table-of-contents
+
+Binding: table-of-contents
+
+Help readers navigate sections within a long page.
+
+## Use when
+
+Help readers jump among named sections in a long document or article.
+
+## Avoid when
+
+Do not add a contents rail to a short page or include headings that are not present in the content.
+
+## Structure
+
+Use the documented TableOfContents parts with a named navigation region and links whose fragments match stable heading IDs. Reflect heading hierarchy with the documented level.
+
+## Responsive
+
+Keep the links reachable on small screens. The native popover trigger can expose the contents without removing the in-page heading and fragment destinations.
+
+## States
+
+Use the base entry for native fragment navigation. The /client entry can add scroll tracking and controlled open/current state; it enhances the native shell after hydration.
+
+## Verify
+
+Follow each link and confirm its target exists, is visible after navigation, and is not obscured by a sticky header. Check the named landmark and keyboard operation of the popover trigger.
+
+## Common mistake
+
+Using scroll position alone to highlight a link while its fragment target is missing or unstable.
+
+## 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/table.md

@@ -0,0 +1,43 @@
+# table
+
+Binding: table
+
+Compare structured member records.
+
+## Use when
+
+Compare records across shared attributes in rows and columns. Use a list for a one-dimensional set of items and CSS grid for page layout.
+
+## Avoid when
+
+Do not use a table only to position content. Turn rows into cards only when people no longer need to compare values across records.
+
+## Structure
+
+Use `Table.Root`, `Table.Caption`, `Table.Header`, `Table.ColumnHeader`, `Table.Body`, `Table.Row`, and `Table.Cell` for native table structure. Give the table a caption or an accessible name and mark header cells so their relationship to data is clear. Keep action controls in a separate column. Align numbers to the end and use tabular numerals for easier comparison.
+
+## Responsive
+
+Preserve the table's row and column relationships. If columns need horizontal scrolling, prioritize which columns remain visible and make the overflow region usable with a keyboard. Do not squeeze text until values are unreadable.
+
+## States
+
+Distinguish an empty dataset from a filter with no matches. Communicate loading and errors, and keep selection or sort state visible when requested. The native table is Tier 0; row selection, sorting, and expansion require the `/client` entry.
+
+## Verify
+
+Inspect the accessibility tree for the caption, header cells, and their data relationships. Navigate through the table at a narrow viewport and check any horizontal overflow with a keyboard. Test empty, no-match, loading, error, selected, and sorted states that the page supports.
+
+## Common mistake
+
+A grid of `div` elements can look like a table but does not provide native row and column header relationships.
+
+Example: `references/examples/table-controls.md`.
+
+Related laws: references/laws/proximity.md, references/laws/accessibility.md
+
+## Sources
+
+- [www.w3.org](https://www.w3.org/WAI/tutorials/tables/) (verified 2026-10-17)
+- [www.w3.org](https://www.w3.org/WAI/ARIA/apg/patterns/table/) (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/tabs.md

@@ -0,0 +1,38 @@
+# tabs
+
+Binding: tabs
+
+Switch between alternate views of the same object.
+
+## Use when
+
+Switch between equivalent views of the same object when only one view needs to be visible at a time.
+
+## Avoid when
+
+Use links for navigation, a stepper for sequential tasks, and side-by-side content when people need to compare views.
+
+## Structure
+
+UIify `Tabs` takes an `id`, `items` with a `value`, `label`, and `panel`, and an optional `defaultValue` and `orientation`. It renders a native radio group with one label and panel per item; it does not implement the ARIA tablist pattern. Set `defaultValue` so a useful panel is selected initially. Keep labels short and make each panel's content match its label.
+
+## Responsive
+
+Let the radio labels wrap or scroll as a group on narrow screens; do not shrink them until they are hard to read. Keep the selected label and its panel visually connected.
+
+## States
+
+`defaultValue` selects the initial radio and panel; changing the native radio changes the visible panel. The panels are CSS-only and work without JavaScript. Use native radio keyboard behavior; do not assume the APG tablist arrow-key model.
+
+## Verify
+
+Check one radio is selected, each label selects its matching panel, and Tab and arrow keys work as they do for a native radio group. Verify the group at narrow widths and with long labels.
+
+## Common mistake
+
+Using tabs as the site's primary navigation hides the fact that each choice is a different page.
+
+## Sources
+
+- [www.w3.org](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/) (verified 2026-10-17)
+- [developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/radio) (verified 2026-10-17)

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

@@ -0,0 +1,39 @@
+# tags-input
+
+Binding: tags-input
+
+Enter and manage a set of text tokens such as recipients or filters.
+
+## Use when
+
+Let people enter multiple free-form values as removable tokens.
+
+## Avoid when
+
+Use a select or checkbox group for a fixed choice set. Do not add suggestion-list semantics unless the complete combobox interaction is implemented.
+
+## Structure
+
+Use TagsInput.Root with the documented List, Tag, TagRemove, and Input parts. Give the text input a clear accessible name and keep each remove control adjacent to its tag. UIify currently names each one “Remove tag”; verify that the tag context is announced when moving among removal controls.
+
+## Responsive
+
+Allow tags to wrap and the input to remain reachable as the list grows. Keep remove controls visible and operable at narrow widths.
+
+## States
+
+Communicate validation, duplicate values, and maximum-tag limits in text. Preserve existing tags when one value is rejected.
+
+## Verify
+
+Test adding, removing, paste and delimiter behavior, duplicate and limit cases, keyboard access, accessible names, and long lists. If removal controls are ambiguous in the target assistive technology, use custom controls with names that include the tag value.
+
+## Common mistake
+
+Rendering tags as decorative chips with no accessible way to identify or remove each value.
+
+## Sources
+
+- [www.w3.org](https://www.w3.org/WAI/tutorials/forms/labels/) (verified 2026-10-17)
+- [www.w3.org](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) (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/testimonial.md

@@ -0,0 +1,52 @@
+# testimonial
+
+Binding: gap
+
+Attribute a customer quote to a named source.
+
+## Use when
+
+A real customer quotation adds useful evidence to a product or service claim.
+
+## Avoid when
+
+Do not invent a quote, imply an endorsement that was not given, or use a testimonial as the only source for a factual claim.
+
+## Structure
+
+This is an app-level composition, not a UIify component. Mark the quoted words with blockquote and include a clear attribution in a nearby caption or paragraph. Keep the quote and its speaker together.
+
+## Responsive
+
+Let the quotation wrap at a readable line length. Keep attribution adjacent on narrow screens and do not crop text into an image.
+
+## States
+
+If quotes rotate, provide labeled controls and user control over rotation; otherwise prefer a static quote.
+
+## Verify
+
+Check quote accuracy and attribution, semantic quotation markup, text contrast, reading order, and keyboard access for any controls.
+
+## Common mistake
+
+A decorative quotation mark does not identify who said the words.
+
+## Custom implementation
+
+```html
+<figure>
+  <blockquote cite="/customers/acme">
+    <p>Our team can find the latest project status quickly.</p>
+  </blockquote>
+  <figcaption>Jordan Lee, Operations Lead</figcaption>
+</figure>
+```
+
+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/blockquote) (verified 2026-10-16)
+- [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)