@gunkin/uiify 0.0.17-alpha → 0.0.19-alpha

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (91) hide show
  1. package/package.json +1 -1
  2. package/skills/uiify/SKILL.md +55 -33
  3. package/skills/uiify/references/compositions/card-rhythm.md +0 -2
  4. package/skills/uiify/references/compositions/destructive-confirmation.md +1 -3
  5. package/skills/uiify/references/compositions/form-grouping.md +0 -2
  6. package/skills/uiify/references/compositions/hero-actions.md +3 -5
  7. package/skills/uiify/references/compositions/page-frame.md +0 -2
  8. package/skills/uiify/references/compositions/pricing-actions.md +0 -2
  9. package/skills/uiify/references/compositions/save-feedback.md +1 -3
  10. package/skills/uiify/references/compositions/table-controls.md +1 -3
  11. package/skills/uiify/references/elements/accordion.md +38 -0
  12. package/skills/uiify/references/elements/alert-modal.md +32 -5
  13. package/skills/uiify/references/elements/avatar.md +31 -2
  14. package/skills/uiify/references/elements/badge.md +32 -3
  15. package/skills/uiify/references/elements/bar-chart.md +39 -7
  16. package/skills/uiify/references/elements/breadcrumb.md +38 -0
  17. package/skills/uiify/references/elements/button.md +38 -3
  18. package/skills/uiify/references/elements/candle-chart.md +38 -0
  19. package/skills/uiify/references/elements/card.md +38 -1
  20. package/skills/uiify/references/elements/carousel.md +38 -0
  21. package/skills/uiify/references/elements/checkbox.md +39 -0
  22. package/skills/uiify/references/elements/code-block.md +31 -2
  23. package/skills/uiify/references/elements/collapsible.md +38 -0
  24. package/skills/uiify/references/elements/color-picker.md +39 -0
  25. package/skills/uiify/references/elements/combobox.md +37 -0
  26. package/skills/uiify/references/elements/command-palette.md +33 -12
  27. package/skills/uiify/references/elements/context-menu.md +38 -0
  28. package/skills/uiify/references/elements/cookie-banner.md +30 -2
  29. package/skills/uiify/references/elements/date-picker.md +33 -9
  30. package/skills/uiify/references/elements/divider.md +30 -2
  31. package/skills/uiify/references/elements/drawer.md +38 -0
  32. package/skills/uiify/references/elements/dropdown-menu.md +38 -0
  33. package/skills/uiify/references/elements/empty-state.md +30 -2
  34. package/skills/uiify/references/elements/feature-grid.md +41 -1
  35. package/skills/uiify/references/elements/field.md +33 -3
  36. package/skills/uiify/references/elements/file-upload.md +40 -0
  37. package/skills/uiify/references/elements/footer.md +35 -4
  38. package/skills/uiify/references/elements/form.md +31 -4
  39. package/skills/uiify/references/elements/header.md +31 -3
  40. package/skills/uiify/references/elements/hero.md +43 -3
  41. package/skills/uiify/references/elements/hover-card.md +38 -0
  42. package/skills/uiify/references/elements/image-gallery.md +36 -4
  43. package/skills/uiify/references/elements/inline-alert.md +30 -2
  44. package/skills/uiify/references/elements/input.md +31 -4
  45. package/skills/uiify/references/elements/line-chart.md +38 -0
  46. package/skills/uiify/references/elements/logo-wall.md +31 -2
  47. package/skills/uiify/references/elements/modal.md +38 -0
  48. package/skills/uiify/references/elements/number-field.md +39 -0
  49. package/skills/uiify/references/elements/otp-input.md +39 -0
  50. package/skills/uiify/references/elements/pagination.md +31 -4
  51. package/skills/uiify/references/elements/password-input.md +33 -9
  52. package/skills/uiify/references/elements/popup.md +38 -0
  53. package/skills/uiify/references/elements/pricing-table.md +55 -2
  54. package/skills/uiify/references/elements/progress-bar.md +32 -4
  55. package/skills/uiify/references/elements/radio-group.md +39 -0
  56. package/skills/uiify/references/elements/rating.md +39 -0
  57. package/skills/uiify/references/elements/search-input.md +35 -4
  58. package/skills/uiify/references/elements/segmented-control.md +39 -0
  59. package/skills/uiify/references/elements/select.md +29 -1
  60. package/skills/uiify/references/elements/sidebar.md +33 -10
  61. package/skills/uiify/references/elements/skeleton.md +38 -0
  62. package/skills/uiify/references/elements/slider.md +39 -0
  63. package/skills/uiify/references/elements/spinner.md +38 -0
  64. package/skills/uiify/references/elements/stats-bar.md +30 -2
  65. package/skills/uiify/references/elements/stepper.md +32 -9
  66. package/skills/uiify/references/elements/switch.md +31 -4
  67. package/skills/uiify/references/elements/table-of-contents.md +39 -0
  68. package/skills/uiify/references/elements/table.md +32 -3
  69. package/skills/uiify/references/elements/tabs.md +38 -0
  70. package/skills/uiify/references/elements/tags-input.md +39 -0
  71. package/skills/uiify/references/elements/testimonial.md +35 -4
  72. package/skills/uiify/references/elements/textarea.md +30 -3
  73. package/skills/uiify/references/elements/timeline.md +31 -3
  74. package/skills/uiify/references/elements/toast.md +27 -1
  75. package/skills/uiify/references/elements/toggle-group.md +39 -0
  76. package/skills/uiify/references/elements/toggle.md +39 -0
  77. package/skills/uiify/references/elements/toolbar.md +39 -0
  78. package/skills/uiify/references/elements/tooltip.md +38 -0
  79. package/skills/uiify/references/elements/virtual-scroll.md +39 -0
  80. package/skills/uiify/references/examples/alert-confirmation.md +34 -0
  81. package/skills/uiify/references/examples/field-validation.md +37 -0
  82. package/skills/uiify/references/examples/select-basic.md +35 -0
  83. package/skills/uiify/references/examples/table-controls.md +40 -0
  84. package/skills/uiify/references/guides/assets.md +14 -0
  85. package/skills/uiify/references/guides/content.md +11 -0
  86. package/skills/uiify/references/guides/hierarchy.md +14 -0
  87. package/skills/uiify/references/guides/reference.md +9 -0
  88. package/skills/uiify/references/guides/states.md +12 -0
  89. package/skills/uiify/references/guides/surface.md +27 -0
  90. package/skills/uiify/scripts/lint.mjs +1 -1
  91. package/skills/uiify/scripts/static.mjs +71 -14
@@ -0,0 +1,39 @@
1
+ # slider
2
+
3
+ Binding: slider
4
+
5
+ Set a value within a continuous or stepped range.
6
+
7
+ ## Use when
8
+
9
+ Let people adjust a value within meaningful lower and upper bounds.
10
+
11
+ ## Avoid when
12
+
13
+ Use a number field when people need exact numeric entry or the range has too many meaningful values to scan.
14
+
15
+ ## Structure
16
+
17
+ 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.
18
+
19
+ ## Responsive
20
+
21
+ Keep the track and thumb operable at narrow widths. Do not communicate the selected value by thumb position or color alone.
22
+
23
+ ## States
24
+
25
+ Expose the current value, bounds, step, and disabled state. Keep a numeric text entry alternative when precise adjustment is important.
26
+
27
+ ## Verify
28
+
29
+ Test keyboard adjustment, endpoints, step increments, accessible name and value, touch screen-reader operation, and any alternative numeric entry.
30
+
31
+ ## Common mistake
32
+
33
+ Showing a slider without a visible label or a way to understand its current value.
34
+
35
+ ## Sources
36
+
37
+ - [www.w3.org](https://www.w3.org/WAI/ARIA/apg/patterns/slider/) (verified 2026-10-17)
38
+ - [www.w3.org](https://www.w3.org/WAI/tutorials/forms/labels/) (verified 2026-10-17)
39
+ - [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html) (verified 2026-10-17)
@@ -0,0 +1,38 @@
1
+ # spinner
2
+
3
+ Binding: spinner
4
+
5
+ A task is actively pending and there is no reliable completion percentage
6
+
7
+ ## Use when
8
+
9
+ A task is actively pending and there is no reliable completion percentage. Pair the indicator with a short label that says what is waiting.
10
+
11
+ ## Avoid when
12
+
13
+ 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.
14
+
15
+ ## Structure
16
+
17
+ 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.
18
+
19
+ ## Responsive
20
+
21
+ Keep the indicator near the task it describes, reserve enough space to prevent layout jumps, and do not let fixed positioning obscure controls.
22
+
23
+ ## States
24
+
25
+ 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.
26
+
27
+ ## Verify
28
+
29
+ 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.
30
+
31
+ ## Common mistake
32
+
33
+ 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.
34
+
35
+ ## Sources
36
+
37
+ - [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html) (verified 2026-10-17)
38
+ - [developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion) (verified 2026-10-17)
@@ -4,7 +4,35 @@ Binding: gap
4
4
 
5
5
  Summarize a few named values for one subject or time period.
6
6
 
7
- Pair each metric with a clear label and value. Use a description list when the content consists of term-and-value pairs.
7
+ ## Use when
8
+
9
+ A few named values summarize one subject, population, and time period.
10
+
11
+ ## Avoid when
12
+
13
+ Do not show unlabeled numbers, mix unlike periods/populations, or use a stats bar when people need detailed comparisons or exploration.
14
+
15
+ ## Structure
16
+
17
+ 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.
18
+
19
+ ## Responsive
20
+
21
+ Let each label/value pair wrap and keep pairs together. Preserve source order as columns collapse.
22
+
23
+ ## States
24
+
25
+ For values that update, explain their meaning and update timing; announce important changes without repeatedly interrupting users.
26
+
27
+ ## Verify
28
+
29
+ Check labels, units, period, number formatting, reading order, and narrow layout. Ensure decoration does not carry the only meaning.
30
+
31
+ ## Common mistake
32
+
33
+ “1,248” without a label, unit, or period is not an interpretable metric.
34
+
35
+ ## Custom implementation
8
36
 
9
37
  ```html
10
38
  <dl>
@@ -13,7 +41,7 @@ Pair each metric with a clear label and value. Use a description list when the c
13
41
  </dl>
14
42
  ```
15
43
 
16
- This is an app-level composition recipe; it does not add a component to UIify.
44
+ This is an app-level composition; UIify does not currently ship this component.
17
45
 
18
46
  ## Sources
19
47
 
@@ -4,17 +4,40 @@ Binding: gap
4
4
 
5
5
  Show ordered steps and identify the current step in a multi-step task.
6
6
 
7
- Present ordered steps in their actual sequence and identify the current step in text. Do not imply that future steps are completed.
7
+ ## Use when
8
8
 
9
- ```html
10
- <ol aria-label="Application progress">
11
- <li>Account</li><li aria-current="step">Profile</li><li>Review</li>
12
- </ol>
13
- ```
9
+ Show the sequence and current position in a multi-step task.
14
10
 
15
- This is an app-level composition recipe; it does not add a component to UIify.
11
+ ## Avoid when
12
+
13
+ Do not use a stepper for unrelated navigation or suggest that future steps are already complete.
14
+
15
+ ## Structure
16
+
17
+ Use an ordered list in task order. Identify the current step with aria-current="step" and provide concise step names.
18
+
19
+ ## Responsive
20
+
21
+ Keep the current step and sequence understandable when labels wrap or the list becomes compact.
22
+
23
+ ## States
24
+
25
+ Distinguish completed, current, and upcoming steps in text or semantics, not color alone. Update the current marker only when the task advances.
26
+
27
+ ## Verify
28
+
29
+ Check list order, current-step announcement, keyboard sequence through any step links, and narrow-screen reading order.
30
+
31
+ ## Common mistake
32
+
33
+ Marking every past step complete when users can still need to correct its information.
34
+
35
+ ## Custom implementation
36
+
37
+ 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.
16
38
 
17
39
  ## Sources
18
40
 
19
- - [www.w3.org](https://www.w3.org/TR/wai-aria-1.2/#aria-current) (verified 2026-10-16)
20
- - [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (verified 2026-10-16)
41
+ - [www.w3.org](https://www.w3.org/TR/wai-aria-1.2/#aria-current) (verified 2026-10-17)
42
+ - [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (verified 2026-10-17)
43
+ - [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html) (verified 2026-10-17)
@@ -2,13 +2,40 @@
2
2
 
3
3
  Binding: switch
4
4
 
5
- Expose a binary preference with a clear label.
5
+ Expose a binary setting that takes effect immediately.
6
6
 
7
- Label the setting by the result it controls and show its current on or off state. Use a switch only for an immediate binary setting.
7
+ ## Use when
8
+
9
+ Let a person turn a persistent setting on or off and apply the change immediately.
10
+
11
+ ## Avoid when
12
+
13
+ Use a checkbox for a form choice that is applied on submit, or a button for a one-time action.
14
+
15
+ ## Structure
16
+
17
+ 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.
18
+
19
+ ## Responsive
20
+
21
+ Keep the label and control together as they wrap. Ensure the complete control remains operable at narrow widths.
22
+
23
+ ## States
24
+
25
+ Make on, off, and disabled states clear. If changing the setting triggers remote work, communicate pending and failure feedback in text.
26
+
27
+ ## Verify
28
+
29
+ Test label activation, Space-key operation, checked-state announcement, persistence after navigation, and feedback for failed updates.
30
+
31
+ ## Common mistake
32
+
33
+ Using a switch for a form value that does not take effect until the user submits.
8
34
 
9
35
  Related laws: references/laws/proximity.md, references/laws/accessibility.md
10
36
 
11
37
  ## Sources
12
38
 
13
- - [www.w3.org](https://www.w3.org/WAI/tutorials/forms/grouping/) (verified 2026-10-16)
14
- - [www.w3.org](https://www.w3.org/WAI/tutorials/forms/labels/) (verified 2026-10-16)
39
+ - [www.w3.org](https://www.w3.org/WAI/ARIA/apg/patterns/switch/) (verified 2026-10-17)
40
+ - [www.w3.org](https://www.w3.org/WAI/tutorials/forms/labels/) (verified 2026-10-17)
41
+ - [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html) (verified 2026-10-17)
@@ -0,0 +1,39 @@
1
+ # table-of-contents
2
+
3
+ Binding: table-of-contents
4
+
5
+ Help readers navigate sections within a long page.
6
+
7
+ ## Use when
8
+
9
+ Help readers jump among named sections in a long document or article.
10
+
11
+ ## Avoid when
12
+
13
+ Do not add a contents rail to a short page or include headings that are not present in the content.
14
+
15
+ ## Structure
16
+
17
+ 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.
18
+
19
+ ## Responsive
20
+
21
+ Keep the links reachable on small screens. The native popover trigger can expose the contents without removing the in-page heading and fragment destinations.
22
+
23
+ ## States
24
+
25
+ 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.
26
+
27
+ ## Verify
28
+
29
+ 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.
30
+
31
+ ## Common mistake
32
+
33
+ Using scroll position alone to highlight a link while its fragment target is missing or unstable.
34
+
35
+ ## Sources
36
+
37
+ - [www.w3.org](https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/examples/navigation.html) (verified 2026-10-17)
38
+ - [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (verified 2026-10-17)
39
+ - [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html) (verified 2026-10-17)
@@ -4,11 +4,40 @@ Binding: table
4
4
 
5
5
  Compare structured member records.
6
6
 
7
- Use a table for related row-and-column data, with a caption and header cells that identify the data. Associate search and filters with this table.
7
+ ## Use when
8
+
9
+ 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.
10
+
11
+ ## Avoid when
12
+
13
+ Do not use a table only to position content. Turn rows into cards only when people no longer need to compare values across records.
14
+
15
+ ## Structure
16
+
17
+ 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.
18
+
19
+ ## Responsive
20
+
21
+ 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.
22
+
23
+ ## States
24
+
25
+ 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.
26
+
27
+ ## Verify
28
+
29
+ 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.
30
+
31
+ ## Common mistake
32
+
33
+ A grid of `div` elements can look like a table but does not provide native row and column header relationships.
34
+
35
+ Example: `references/examples/table-controls.md`.
8
36
 
9
37
  Related laws: references/laws/proximity.md, references/laws/accessibility.md
10
38
 
11
39
  ## Sources
12
40
 
13
- - [www.w3.org](https://www.w3.org/WAI/tutorials/forms/labels/) (verified 2026-10-16)
14
- - [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (verified 2026-10-16)
41
+ - [www.w3.org](https://www.w3.org/WAI/tutorials/tables/) (verified 2026-10-17)
42
+ - [www.w3.org](https://www.w3.org/WAI/ARIA/apg/patterns/table/) (verified 2026-10-17)
43
+ - [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (verified 2026-10-17)
@@ -0,0 +1,38 @@
1
+ # tabs
2
+
3
+ Binding: tabs
4
+
5
+ Switch between alternate views of the same object.
6
+
7
+ ## Use when
8
+
9
+ Switch between equivalent views of the same object when only one view needs to be visible at a time.
10
+
11
+ ## Avoid when
12
+
13
+ Use links for navigation, a stepper for sequential tasks, and side-by-side content when people need to compare views.
14
+
15
+ ## Structure
16
+
17
+ 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.
18
+
19
+ ## Responsive
20
+
21
+ 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.
22
+
23
+ ## States
24
+
25
+ `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.
26
+
27
+ ## Verify
28
+
29
+ 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.
30
+
31
+ ## Common mistake
32
+
33
+ Using tabs as the site's primary navigation hides the fact that each choice is a different page.
34
+
35
+ ## Sources
36
+
37
+ - [www.w3.org](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/) (verified 2026-10-17)
38
+ - [developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/radio) (verified 2026-10-17)
@@ -0,0 +1,39 @@
1
+ # tags-input
2
+
3
+ Binding: tags-input
4
+
5
+ Enter and manage a set of text tokens such as recipients or filters.
6
+
7
+ ## Use when
8
+
9
+ Let people enter multiple free-form values as removable tokens.
10
+
11
+ ## Avoid when
12
+
13
+ Use a select or checkbox group for a fixed choice set. Do not add suggestion-list semantics unless the complete combobox interaction is implemented.
14
+
15
+ ## Structure
16
+
17
+ 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.
18
+
19
+ ## Responsive
20
+
21
+ Allow tags to wrap and the input to remain reachable as the list grows. Keep remove controls visible and operable at narrow widths.
22
+
23
+ ## States
24
+
25
+ Communicate validation, duplicate values, and maximum-tag limits in text. Preserve existing tags when one value is rejected.
26
+
27
+ ## Verify
28
+
29
+ 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.
30
+
31
+ ## Common mistake
32
+
33
+ Rendering tags as decorative chips with no accessible way to identify or remove each value.
34
+
35
+ ## Sources
36
+
37
+ - [www.w3.org](https://www.w3.org/WAI/tutorials/forms/labels/) (verified 2026-10-17)
38
+ - [www.w3.org](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) (verified 2026-10-17)
39
+ - [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html) (verified 2026-10-17)
@@ -4,18 +4,49 @@ Binding: gap
4
4
 
5
5
  Attribute a customer quote to a named source.
6
6
 
7
- Use a quotation with a clear attribution. Include the speaker and relevant affiliation in text when the quotation needs that context.
7
+ ## Use when
8
+
9
+ A real customer quotation adds useful evidence to a product or service claim.
10
+
11
+ ## Avoid when
12
+
13
+ Do not invent a quote, imply an endorsement that was not given, or use a testimonial as the only source for a factual claim.
14
+
15
+ ## Structure
16
+
17
+ 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.
18
+
19
+ ## Responsive
20
+
21
+ Let the quotation wrap at a readable line length. Keep attribution adjacent on narrow screens and do not crop text into an image.
22
+
23
+ ## States
24
+
25
+ If quotes rotate, provide labeled controls and user control over rotation; otherwise prefer a static quote.
26
+
27
+ ## Verify
28
+
29
+ Check quote accuracy and attribution, semantic quotation markup, text contrast, reading order, and keyboard access for any controls.
30
+
31
+ ## Common mistake
32
+
33
+ A decorative quotation mark does not identify who said the words.
34
+
35
+ ## Custom implementation
8
36
 
9
37
  ```html
10
38
  <figure>
11
- <blockquote><p>Setup took minutes.</p></blockquote>
12
- <figcaption>— Ada Lovelace, Acme</figcaption>
39
+ <blockquote cite="/customers/acme">
40
+ <p>Our team can find the latest project status quickly.</p>
41
+ </blockquote>
42
+ <figcaption>Jordan Lee, Operations Lead</figcaption>
13
43
  </figure>
14
44
  ```
15
45
 
16
- This is an app-level composition recipe; it does not add a component to UIify.
46
+ This is an app-level composition; UIify does not currently ship this component.
17
47
 
18
48
  ## Sources
19
49
 
20
50
  - [developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/blockquote) (verified 2026-10-16)
51
+ - [developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/figure) (verified 2026-10-16)
21
52
  - [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (verified 2026-10-16)
@@ -4,11 +4,38 @@ Binding: textarea
4
4
 
5
5
  Accept a longer free-text value.
6
6
 
7
- Give the multiline control a visible label. State length or format limits before entry and keep any validation message beside the control.
7
+ ## Use when
8
+
9
+ Collect a response that may span multiple lines, such as a message or description.
10
+
11
+ ## Avoid when
12
+
13
+ Use a single-line input for short values and avoid imposing a character limit that the task does not require.
14
+
15
+ ## Structure
16
+
17
+ Associate the documented Textarea with a visible label. State length or format limits before entry and place validation feedback next to the control.
18
+
19
+ ## Responsive
20
+
21
+ Let the field grow to the available inline size and allow entered text to wrap. Use the documented autoSize option when content-driven height is appropriate.
22
+
23
+ ## States
24
+
25
+ Preserve text after an error and identify invalid content in text; do not rely on a color change alone.
26
+
27
+ ## Verify
28
+
29
+ Check the visible label, instructions, keyboard editing, error association, long content, and narrow-width reflow.
30
+
31
+ ## Common mistake
32
+
33
+ Using placeholder text as a substitute for the label or hiding the only copy of a length limit.
8
34
 
9
35
  Related laws: references/laws/proximity.md, references/laws/accessibility.md
10
36
 
11
37
  ## Sources
12
38
 
13
- - [www.w3.org](https://www.w3.org/WAI/tutorials/forms/grouping/) (verified 2026-10-16)
14
- - [www.w3.org](https://www.w3.org/WAI/tutorials/forms/labels/) (verified 2026-10-16)
39
+ - [www.w3.org](https://www.w3.org/WAI/tutorials/forms/labels/) (verified 2026-10-17)
40
+ - [www.w3.org](https://www.w3.org/WAI/tutorials/forms/instructions/) (verified 2026-10-17)
41
+ - [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html) (verified 2026-10-17)
@@ -4,15 +4,43 @@ Binding: gap
4
4
 
5
5
  Show dated events in chronological order.
6
6
 
7
- Use an ordered list when sequence matters. Encode machine-readable dates with time and keep each event’s date attached to its description.
7
+ ## Use when
8
+
9
+ Events have a meaningful chronological sequence and each date needs to stay attached to its description.
10
+
11
+ ## Avoid when
12
+
13
+ Do not use a timeline to decorate unrelated facts or imply chronology when events are unordered. Use a table when people need to compare attributes across events.
14
+
15
+ ## Structure
16
+
17
+ This is an app-level composition, not a UIify component. Use an ordered list when sequence matters, and a time element with machine-readable datetime for each date. Keep event title and details in the same list item.
18
+
19
+ ## Responsive
20
+
21
+ Preserve chronological reading order as a vertical list on narrow screens. Do not rely on left/right placement or connecting lines to communicate sequence.
22
+
23
+ ## States
24
+
25
+ Distinguish past, current, and upcoming events in text when those states matter; color and position alone are insufficient.
26
+
27
+ ## Verify
28
+
29
+ Check ordering, machine-readable dates, date format, current/upcoming meaning, list semantics, and narrow layout.
30
+
31
+ ## Common mistake
32
+
33
+ A reverse chronological visual layout can conflict with DOM reading order if the markup is not ordered intentionally.
34
+
35
+ ## Custom implementation
8
36
 
9
37
  ```html
10
38
  <ol>
11
- <li><time datetime="2026-10-16">October 16, 2026</time><p>Release published</p></li>
39
+ <li><time datetime="2026-10-17">October 17, 2026</time><p>Release published</p></li>
12
40
  </ol>
13
41
  ```
14
42
 
15
- This is an app-level composition recipe; it does not add a component to UIify.
43
+ This is an app-level composition; UIify does not currently ship this component.
16
44
 
17
45
  ## Sources
18
46
 
@@ -4,7 +4,33 @@ Binding: toast
4
4
 
5
5
  Confirm the result of a completed save.
6
6
 
7
- Use a status message for brief feedback that should not interrupt the current task. Keep essential errors visible until the user can address them.
7
+ ## Use when
8
+
9
+ A brief, non-blocking update confirms a completed action or reports a change while the person continues working. Use assertive priority only when the message is urgent.
10
+
11
+ ## Avoid when
12
+
13
+ Do not use a timed toast for errors that require correction, critical information, or a decision. Put actionable errors in the relevant form or page and keep them visible.
14
+
15
+ ## Structure
16
+
17
+ Place a live `ToastViewport` beside the client provider and enqueue a concise title/description. Include an explicit close control; add one short action only when undo or a direct follow-up is useful.
18
+
19
+ ## Responsive
20
+
21
+ Keep notifications clear of controls and safe areas, allow text to wrap, and limit simultaneous messages so the queue stays readable.
22
+
23
+ ## States
24
+
25
+ Toasts default to polite announcements and a 4-second duration. Hover and focus pause the timer; set duration to 0 for persistent feedback. The client island is required for the queue; the exported shell alone does not enqueue messages.
26
+
27
+ ## Verify
28
+
29
+ Check that a save message is announced without moving focus, pause on pointer/focus, close control, queue behavior, persistent duration, and a narrow viewport. Confirm assertive announcements are reserved for urgent messages.
30
+
31
+ ## Common mistake
32
+
33
+ Do not auto-dismiss an error before the person can read and act on it.
8
34
 
9
35
  Related laws: references/laws/feedback.md
10
36
 
@@ -0,0 +1,39 @@
1
+ # toggle-group
2
+
3
+ Binding: toggle-group
4
+
5
+ Select one or several related options as a group of toggles.
6
+
7
+ ## Use when
8
+
9
+ Present a compact set of related options whose selected values affect the same view or object.
10
+
11
+ ## Avoid when
12
+
13
+ Use ordinary links for navigation, Tabs for switching associated panels, and checkboxes for a form list that benefits from visible labels and descriptions.
14
+
15
+ ## Structure
16
+
17
+ Use ToggleGroup with a stable id, a group name, and items with values and labels. Set type to single for one choice or multiple for independent choices.
18
+
19
+ ## Responsive
20
+
21
+ Let labels wrap or stack without changing the option order or hiding selected values. Keep targets usable at narrow widths.
22
+
23
+ ## States
24
+
25
+ Show selected and unselected values clearly. In single mode, keep a valid selection when one is required; in multiple mode, allow the documented independent selection behavior.
26
+
27
+ ## Verify
28
+
29
+ Test arrow-key operation, group name, single/multiple selection, disabled items, selected-state announcement, and keyboard focus.
30
+
31
+ ## Common mistake
32
+
33
+ Using a toggle group for navigation or tabs when options do not represent selection on the same content.
34
+
35
+ ## Sources
36
+
37
+ - [www.w3.org](https://www.w3.org/WAI/ARIA/apg/patterns/radio/) (verified 2026-10-17)
38
+ - [www.w3.org](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/) (verified 2026-10-17)
39
+ - [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html) (verified 2026-10-17)
@@ -0,0 +1,39 @@
1
+ # toggle
2
+
3
+ Binding: toggle
4
+
5
+ Expose a binary value with a toggle-style presentation.
6
+
7
+ ## Use when
8
+
9
+ Present one reversible binary value, such as whether a formatting option is active.
10
+
11
+ ## Avoid when
12
+
13
+ Use a switch for a persistent on/off setting and ordinary buttons for one-time actions.
14
+
15
+ ## Structure
16
+
17
+ Use the documented Toggle with its required id and label. It is backed by a native checkbox; keep the label stable so the checked state conveys the change.
18
+
19
+ ## Responsive
20
+
21
+ Keep the label visible or provide an accessible name for an icon-only control. Preserve an adequate target at narrow widths.
22
+
23
+ ## States
24
+
25
+ Expose checked and unchecked state and show it visually without relying on color alone. Disabled state should remain distinguishable.
26
+
27
+ ## Verify
28
+
29
+ Use Space to toggle, check the announced checkbox state and stable name, and test keyboard focus and disabled behavior.
30
+
31
+ ## Common mistake
32
+
33
+ Styling a checkbox as a toggle button while hiding its checked state from the visual presentation.
34
+
35
+ ## Sources
36
+
37
+ - [www.w3.org](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/) (verified 2026-10-17)
38
+ - [www.w3.org](https://www.w3.org/WAI/ARIA/apg/patterns/switch/) (verified 2026-10-17)
39
+ - [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html) (verified 2026-10-17)