@gunkin/uiify 0.0.16-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 (98) hide show
  1. package/README.md +34 -9
  2. package/package.json +1 -1
  3. package/skills/uiify/SKILL.md +125 -125
  4. package/skills/uiify/references/compositions/card-rhythm.md +14 -0
  5. package/skills/uiify/references/compositions/destructive-confirmation.md +15 -0
  6. package/skills/uiify/references/compositions/form-grouping.md +14 -0
  7. package/skills/uiify/references/compositions/hero-actions.md +14 -0
  8. package/skills/uiify/references/compositions/page-frame.md +14 -0
  9. package/skills/uiify/references/compositions/pricing-actions.md +13 -0
  10. package/skills/uiify/references/compositions/save-feedback.md +13 -0
  11. package/skills/uiify/references/compositions/table-controls.md +14 -0
  12. package/skills/uiify/references/elements/accordion.md +38 -0
  13. package/skills/uiify/references/elements/alert-modal.md +42 -0
  14. package/skills/uiify/references/elements/avatar.md +47 -0
  15. package/skills/uiify/references/elements/badge.md +47 -0
  16. package/skills/uiify/references/elements/bar-chart.md +61 -0
  17. package/skills/uiify/references/elements/breadcrumb.md +38 -0
  18. package/skills/uiify/references/elements/button.md +49 -0
  19. package/skills/uiify/references/elements/candle-chart.md +38 -0
  20. package/skills/uiify/references/elements/card.md +51 -0
  21. package/skills/uiify/references/elements/carousel.md +38 -0
  22. package/skills/uiify/references/elements/checkbox.md +39 -0
  23. package/skills/uiify/references/elements/code-block.md +50 -0
  24. package/skills/uiify/references/elements/collapsible.md +38 -0
  25. package/skills/uiify/references/elements/color-picker.md +39 -0
  26. package/skills/uiify/references/elements/combobox.md +37 -0
  27. package/skills/uiify/references/elements/command-palette.md +43 -0
  28. package/skills/uiify/references/elements/context-menu.md +38 -0
  29. package/skills/uiify/references/elements/cookie-banner.md +51 -0
  30. package/skills/uiify/references/elements/date-picker.md +43 -0
  31. package/skills/uiify/references/elements/divider.md +46 -0
  32. package/skills/uiify/references/elements/drawer.md +38 -0
  33. package/skills/uiify/references/elements/dropdown-menu.md +38 -0
  34. package/skills/uiify/references/elements/empty-state.md +50 -0
  35. package/skills/uiify/references/elements/feature-grid.md +54 -0
  36. package/skills/uiify/references/elements/field.md +44 -0
  37. package/skills/uiify/references/elements/file-upload.md +40 -0
  38. package/skills/uiify/references/elements/footer.md +45 -0
  39. package/skills/uiify/references/elements/form.md +41 -0
  40. package/skills/uiify/references/elements/header.md +42 -0
  41. package/skills/uiify/references/elements/hero.md +54 -0
  42. package/skills/uiify/references/elements/hover-card.md +38 -0
  43. package/skills/uiify/references/elements/image-gallery.md +52 -0
  44. package/skills/uiify/references/elements/inline-alert.md +46 -0
  45. package/skills/uiify/references/elements/input.md +41 -0
  46. package/skills/uiify/references/elements/line-chart.md +38 -0
  47. package/skills/uiify/references/elements/logo-wall.md +49 -0
  48. package/skills/uiify/references/elements/modal.md +38 -0
  49. package/skills/uiify/references/elements/number-field.md +39 -0
  50. package/skills/uiify/references/elements/otp-input.md +39 -0
  51. package/skills/uiify/references/elements/pagination.md +41 -0
  52. package/skills/uiify/references/elements/password-input.md +43 -0
  53. package/skills/uiify/references/elements/popup.md +38 -0
  54. package/skills/uiify/references/elements/pricing-table.md +66 -0
  55. package/skills/uiify/references/elements/progress-bar.md +47 -0
  56. package/skills/uiify/references/elements/radio-group.md +39 -0
  57. package/skills/uiify/references/elements/rating.md +39 -0
  58. package/skills/uiify/references/elements/search-input.md +45 -0
  59. package/skills/uiify/references/elements/segmented-control.md +39 -0
  60. package/skills/uiify/references/elements/select.md +42 -0
  61. package/skills/uiify/references/elements/sidebar.md +43 -0
  62. package/skills/uiify/references/elements/skeleton.md +38 -0
  63. package/skills/uiify/references/elements/slider.md +39 -0
  64. package/skills/uiify/references/elements/spinner.md +38 -0
  65. package/skills/uiify/references/elements/stats-bar.md +49 -0
  66. package/skills/uiify/references/elements/stepper.md +43 -0
  67. package/skills/uiify/references/elements/switch.md +41 -0
  68. package/skills/uiify/references/elements/table-of-contents.md +39 -0
  69. package/skills/uiify/references/elements/table.md +43 -0
  70. package/skills/uiify/references/elements/tabs.md +38 -0
  71. package/skills/uiify/references/elements/tags-input.md +39 -0
  72. package/skills/uiify/references/elements/testimonial.md +52 -0
  73. package/skills/uiify/references/elements/textarea.md +41 -0
  74. package/skills/uiify/references/elements/timeline.md +48 -0
  75. package/skills/uiify/references/elements/toast.md +39 -0
  76. package/skills/uiify/references/elements/toggle-group.md +39 -0
  77. package/skills/uiify/references/elements/toggle.md +39 -0
  78. package/skills/uiify/references/elements/toolbar.md +39 -0
  79. package/skills/uiify/references/elements/tooltip.md +38 -0
  80. package/skills/uiify/references/elements/virtual-scroll.md +39 -0
  81. package/skills/uiify/references/examples/alert-confirmation.md +34 -0
  82. package/skills/uiify/references/examples/field-validation.md +37 -0
  83. package/skills/uiify/references/examples/select-basic.md +35 -0
  84. package/skills/uiify/references/examples/table-controls.md +40 -0
  85. package/skills/uiify/references/guides/assets.md +14 -0
  86. package/skills/uiify/references/guides/content.md +11 -0
  87. package/skills/uiify/references/guides/hierarchy.md +14 -0
  88. package/skills/uiify/references/guides/reference.md +9 -0
  89. package/skills/uiify/references/guides/states.md +12 -0
  90. package/skills/uiify/references/guides/surface.md +27 -0
  91. package/skills/uiify/references/laws/accessibility.md +11 -0
  92. package/skills/uiify/references/laws/error-prevention.md +12 -0
  93. package/skills/uiify/references/laws/feedback.md +9 -0
  94. package/skills/uiify/references/laws/proximity.md +10 -0
  95. package/skills/uiify/references/laws/readability.md +9 -0
  96. package/skills/uiify/references/laws/von-restorff.md +9 -0
  97. package/skills/uiify/scripts/lint.mjs +1 -1
  98. package/skills/uiify/scripts/static.mjs +71 -14
@@ -0,0 +1,51 @@
1
+ # cookie-banner
2
+
3
+ Binding: gap
4
+
5
+ Explain cookie choices and provide consent actions.
6
+
7
+ ## Use when
8
+
9
+ A product needs to explain its cookie/storage choices and provide a clear route to the detailed policy and preference controls.
10
+
11
+ ## Avoid when
12
+
13
+ Do not obscure the primary task with a full-screen interruption when a compact notice works. Do not imply that a button choice is legally sufficient in every jurisdiction; match the product's actual consent policy.
14
+
15
+ ## Structure
16
+
17
+ This is an app-level composition, not a UIify component. State what optional storage is used for, link to the policy, and present distinct choices with similarly clear labels.
18
+
19
+ ## Responsive
20
+
21
+ Keep the notice readable at mobile widths and zoom; allow the page to remain usable and make every choice reachable without horizontal scrolling.
22
+
23
+ ## States
24
+
25
+ Represent the actual consent state: undecided, accepted/rejected as supported by policy, and preference editing. Persist only the choice the person made, and provide a way to revisit preferences.
26
+
27
+ ## Verify
28
+
29
+ Check keyboard operation, policy link, clear action labels, focus order, narrow layout, persistence behavior, and that the choices match the implementation and applicable policy.
30
+
31
+ ## Common mistake
32
+
33
+ Do not hide rejection behind multiple steps while acceptance is a single prominent button.
34
+
35
+ ## Custom implementation
36
+
37
+ ```html
38
+ <aside aria-labelledby="cookie-title">
39
+ <h2 id="cookie-title">Cookie choices</h2>
40
+ <p>Choose whether to allow optional cookies.</p>
41
+ <button type="button">Allow optional cookies</button>
42
+ <button type="button">Reject optional cookies</button>
43
+ </aside>
44
+ ```
45
+
46
+ This is an app-level composition; UIify does not currently ship this component.
47
+
48
+ ## Sources
49
+
50
+ - [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-in-context.html) (verified 2026-10-16)
51
+ - [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (verified 2026-10-16)
@@ -0,0 +1,43 @@
1
+ # date-picker
2
+
3
+ Binding: gap
4
+
5
+ Collect one calendar date using the browser’s native date control.
6
+
7
+ ## Use when
8
+
9
+ Collect one calendar date without a time, such as a start or due date.
10
+
11
+ ## Avoid when
12
+
13
+ Use a date-time control when time matters. Avoid replacing the native picker with a custom calendar unless the task requires behavior that has been tested for keyboard and assistive technology.
14
+
15
+ ## Structure
16
+
17
+ Use a visible label with a native input of type date. Add min and max only when the constraints are real, explain them before entry, and associate error feedback with the field.
18
+
19
+ ## Responsive
20
+
21
+ Allow the browser’s date UI to use the platform layout; keep the field within the available width and do not assume every browser displays the same picker.
22
+
23
+ ## States
24
+
25
+ Distinguish an empty value, a valid date, and a date outside the allowed range. The submitted date value is a calendar date normalized as yyyy-mm-dd.
26
+
27
+ ## Verify
28
+
29
+ Test keyboard entry and picker operation in target browsers, date bounds, visible format guidance, validation text, and narrow-screen behavior.
30
+
31
+ ## Common mistake
32
+
33
+ Treating a date-only value as a timestamp with a time zone.
34
+
35
+ ## Custom implementation
36
+
37
+ Use a labelled native input with type date. This app-level pattern does not add a UIify date-picker component.
38
+
39
+ ## Sources
40
+
41
+ - [developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input/date) (verified 2026-10-17)
42
+ - [www.w3.org](https://www.w3.org/WAI/tutorials/forms/labels/) (verified 2026-10-17)
43
+ - [www.w3.org](https://www.w3.org/WAI/tutorials/forms/instructions/) (verified 2026-10-17)
@@ -0,0 +1,46 @@
1
+ # divider
2
+
3
+ Binding: gap
4
+
5
+ Separate adjacent thematic sections when a heading is not appropriate.
6
+
7
+ ## Use when
8
+
9
+ Adjacent sections change topic and a thematic break helps people understand the transition.
10
+
11
+ ## Avoid when
12
+
13
+ Do not add a divider between every repeated item or use it in place of spacing. Decorative lines that convey no grouping should remain outside the accessibility tree.
14
+
15
+ ## Structure
16
+
17
+ This is an app-level composition, not a UIify component. Use the native hr element for a thematic break; use CSS border for a purely decorative rule.
18
+
19
+ ## Responsive
20
+
21
+ Use logical sizing and preserve separation as content wraps or stacks. Avoid rules that become ambiguous in vertical writing or dense layouts.
22
+
23
+ ## States
24
+
25
+ A thematic break is static. If a separator labels a widget such as a menu, use that widget's separator semantics instead of hr.
26
+
27
+ ## Verify
28
+
29
+ Check whether the line marks a real topic change, reading flow around it, and narrow layout.
30
+
31
+ ## Common mistake
32
+
33
+ A visual border between every card is not automatically a thematic break.
34
+
35
+ ## Custom implementation
36
+
37
+ ```html
38
+ <hr />
39
+ ```
40
+
41
+ This is an app-level composition; UIify does not currently ship this component.
42
+
43
+ ## Sources
44
+
45
+ - [developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/hr) (verified 2026-10-16)
46
+ - [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (verified 2026-10-16)
@@ -0,0 +1,38 @@
1
+ # drawer
2
+
3
+ Binding: drawer
4
+
5
+ A focused secondary task or navigation surface should enter from an edge and temporarily cover or accompany the page
6
+
7
+ ## Use when
8
+
9
+ A focused secondary task or navigation surface should enter from an edge and temporarily cover or accompany the page. Choose it when the task benefits from a sheet-like spatial relationship.
10
+
11
+ ## Avoid when
12
+
13
+ Do not use a drawer for content that should remain visible beside the page, or for a compact anchored choice list. Avoid turning primary navigation into a blocking task without a clear need.
14
+
15
+ ## Structure
16
+
17
+ Use `Drawer` with a specific title, optional description, focused content, visible close control, and optional footer. Select side and size to fit the task; use snap points only when the client interaction is needed.
18
+
19
+ ## Responsive
20
+
21
+ Use a bottom sheet on narrow screens when the task reads naturally as a sheet; keep its content scrollable and close action reachable. Respect safe areas and test the selected side at mobile widths.
22
+
23
+ ## States
24
+
25
+ The native Tier 0 shell opens a dialog. Choose 'dismiss' deliberately: 'any' permits backdrop/Escape, 'closerequest' allows close requests, and 'none' requires an explicit close. The compound client API adds controlled state and optional snap-point dragging.
26
+
27
+ ## Verify
28
+
29
+ Check visible title, focus entry/containment/return, close control, configured dismissal, scrolling, and narrow viewport. If using drag, test the handle with touch and pointer and ensure an explicit close remains available.
30
+
31
+ ## Common mistake
32
+
33
+ Do not rely on dragging as the only way to close or resize the drawer.
34
+
35
+ ## Sources
36
+
37
+ - [www.w3.org](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/) (verified 2026-10-17)
38
+ - [developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog) (verified 2026-10-17)
@@ -0,0 +1,38 @@
1
+ # dropdown-menu
2
+
3
+ Binding: dropdown-menu
4
+
5
+ A button reveals a compact set of actions or settings for that button
6
+
7
+ ## Use when
8
+
9
+ A button reveals a compact set of actions or settings for that button. Use menu items for commands, checkbox items for independent toggles, and radio items for one choice within a group.
10
+
11
+ ## Avoid when
12
+
13
+ Do not use a menu for site navigation; use ordinary links and navigation landmarks. Do not use menu roles for a form or a list of links that should remain in the page's normal Tab sequence.
14
+
15
+ ## Structure
16
+
17
+ Compose `DropdownMenu` Root, Trigger, Content, and named items. Give the trigger an action-oriented accessible name; group related actions with labels and separators, and use checkbox/radio items only for their matching state model.
18
+
19
+ ## Responsive
20
+
21
+ Keep the menu within the viewport and ensure labels remain readable at zoom. Provide a touch-sized trigger and avoid making hover the only way to open it.
22
+
23
+ ## States
24
+
25
+ The trigger opens the menu; keyboard interaction moves focus among items and Escape closes and returns focus. Selection closes by default. 'openOnHover' is optional enhancement; preserve the normal click and keyboard route.
26
+
27
+ ## Verify
28
+
29
+ Test trigger by keyboard and pointer, arrow-key item navigation, Home/End where supported, Escape and focus return, disabled items, selection, and checked/radio state announcements. Check placement near viewport edges.
30
+
31
+ ## Common mistake
32
+
33
+ A row of destination links is navigation, even if it visually resembles a dropdown menu.
34
+
35
+ ## Sources
36
+
37
+ - [www.w3.org](https://www.w3.org/WAI/ARIA/apg/patterns/menubar/) (verified 2026-10-17)
38
+ - [www.w3.org](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/) (verified 2026-10-17)
@@ -0,0 +1,50 @@
1
+ # empty-state
2
+
3
+ Binding: gap
4
+
5
+ Explain why a collection has no items and offer a relevant next step.
6
+
7
+ ## Use when
8
+
9
+ A collection has no items and the person needs to understand what is empty and what useful step is available next.
10
+
11
+ ## Avoid when
12
+
13
+ Do not show an empty state for loading, filtered no-results, access denial, and a genuinely new collection as though they were the same cause. Name the actual state.
14
+
15
+ ## Structure
16
+
17
+ This is an app-level composition, not a UIify component. Give the section a heading that names the collection and one relevant next step; use a link for navigation or a button for an in-place action.
18
+
19
+ ## Responsive
20
+
21
+ Keep the message and action close in reading order, use a concise line length, and do not center long explanatory copy in an unnecessarily narrow area.
22
+
23
+ ## States
24
+
25
+ Distinguish first-use empty, filtered no-results, unavailable/error, and loading states. Explain a recovery action for filters and avoid suggesting creation when the person lacks permission.
26
+
27
+ ## Verify
28
+
29
+ Check the heading and action name, real destination/behavior, keyboard access, state-specific copy, and narrow/zoom layout.
30
+
31
+ ## Common mistake
32
+
33
+ “No results” should offer a way to clear or change filters, not a create action unrelated to the search.
34
+
35
+ ## Custom implementation
36
+
37
+ ```html
38
+ <section aria-labelledby="empty-title">
39
+ <h2 id="empty-title">No invoices yet</h2>
40
+ <p>Create an invoice to see it listed here.</p>
41
+ <a href="/invoices/new">Create invoice</a>
42
+ </section>
43
+ ```
44
+
45
+ This is an app-level composition; UIify does not currently ship this component.
46
+
47
+ ## Sources
48
+
49
+ - [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/headings-and-labels.html) (verified 2026-10-16)
50
+ - [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (verified 2026-10-16)
@@ -0,0 +1,54 @@
1
+ # feature-grid
2
+
3
+ Binding: gap
4
+
5
+ Present related product capabilities as a coherent set.
6
+
7
+ ## Use when
8
+
9
+ Several related capabilities have equal importance and repeat the same content shape.
10
+
11
+ ## Avoid when
12
+
13
+ Do not force unequal priorities or long-form explanations into a uniform grid. Use a comparison table when people must compare values across features.
14
+
15
+ ## Structure
16
+
17
+ This is an app-level composition, not a UIify component. Render a labeled section containing a list of items; give each item a heading and short explanation. Use the same order and content hierarchy for every item.
18
+
19
+ ## Responsive
20
+
21
+ Collapse to one column on narrow screens and retain source order. Avoid fixed heights that clip translated or zoomed text.
22
+
23
+ ## States
24
+
25
+ Keep item actions consistent. If each feature links to detail, link its heading and retain a clear focus indicator.
26
+
27
+ ## Verify
28
+
29
+ Check section label, heading levels, source order, one-column reflow, link names, and the card spacing at mobile width.
30
+
31
+ ## Common mistake
32
+
33
+ Do not use three equal cards to imply equal priority when one feature is the primary action.
34
+
35
+ ## Custom implementation
36
+
37
+ ```html
38
+ <section aria-labelledby="features-title">
39
+ <h2 id="features-title">Built for daily work</h2>
40
+ <ul>
41
+ <li><article><h3>Shared workspace</h3><p>Keep team work together.</p></article></li>
42
+ <li><article><h3>Clear history</h3><p>See what changed and when.</p></article></li>
43
+ </ul>
44
+ </section>
45
+ ```
46
+
47
+ This is an app-level composition; UIify does not currently ship this component.
48
+
49
+ Related laws: references/laws/proximity.md, references/laws/readability.md
50
+
51
+ ## Sources
52
+
53
+ - [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (verified 2026-10-16)
54
+ - [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/visual-presentation.html) (verified 2026-10-16)
@@ -0,0 +1,44 @@
1
+ # field
2
+
3
+ Binding: field
4
+
5
+ Keep a label and its form control together.
6
+
7
+ ## Use when
8
+
9
+ Keep a form control, its label, instructions, and any validation message connected. Use visible labels that name the expected information; a placeholder is not a substitute.
10
+
11
+ ## Avoid when
12
+
13
+ Do not use a field wrapper without a real form control, or hide instructions needed before the person enters a value.
14
+
15
+ ## Structure
16
+
17
+ Use `Field.Root`, `Field.Label`, `Field.Control`, `Field.Description`, and `Field.Error` with the same `id` on Root and `fieldId` on every part. Put native props such as `name`, `type`, and `autoComplete` on `Field.Control`. Pass `invalid`, `required`, and `disabled` to the parts that need those states; Root does not inject props into them.
18
+
19
+ ## Responsive
20
+
21
+ Keep labels and help text close to the control at narrow widths. Let long instructions and error messages wrap without clipping.
22
+
23
+ ## States
24
+
25
+ Native required validation works without JavaScript. For application validation, set `invalid` on Root and Control and render `Field.Error` with the same state after validation. The control's accessible description includes the error while invalid.
26
+
27
+ ## Verify
28
+
29
+ Click the label and confirm its control receives focus. Inspect the accessibility tree for the control's name and associated description; submit an invalid value and confirm a textual error appears and is announced. Check required, disabled, read-only, and long-message states.
30
+
31
+ ## Common mistake
32
+
33
+ A label and control with different `fieldId` values disconnect the visible label from the input and its instructions.
34
+
35
+ Example: `references/examples/field-validation.md`.
36
+
37
+ Related laws: references/laws/proximity.md, references/laws/accessibility.md
38
+
39
+ ## Sources
40
+
41
+ - [www.w3.org](https://www.w3.org/WAI/tutorials/forms/grouping/) (verified 2026-10-17)
42
+ - [www.w3.org](https://www.w3.org/WAI/tutorials/forms/labels/) (verified 2026-10-17)
43
+ - [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/error-identification.html) (verified 2026-10-17)
44
+ - [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/error-suggestion.html) (verified 2026-10-17)
@@ -0,0 +1,40 @@
1
+ # file-upload
2
+
3
+ Binding: file-upload
4
+
5
+ Let people select and manage files for a form or task.
6
+
7
+ ## Use when
8
+
9
+ Let people attach one or more files to a form or task.
10
+
11
+ ## Avoid when
12
+
13
+ Do not require drag and drop as the only way to choose files. Avoid asking for files unrelated to the task.
14
+
15
+ ## Structure
16
+
17
+ Use FileUpload.Root with a labelled HiddenInput and an optional Trigger or Dropzone. Explain allowed formats, size limits, and maximum file count before selection; show selected filenames and provide a named remove action for each file.
18
+
19
+ ## Responsive
20
+
21
+ Keep the browse control and selected-file list usable at narrow widths. Do not rely on a large drop target that pushes the file picker off screen.
22
+
23
+ ## States
24
+
25
+ Report rejected files with the reason, including type, size, or count limits. Keep the accepted files and let people remove them. Treat accept as a picker hint; validate file type and size on the server.
26
+
27
+ ## Verify
28
+
29
+ Test keyboard file selection, the accessible input name, multiple-file selection, dropzone as an optional path, rejected-file feedback, removal, and server-side validation.
30
+
31
+ ## Common mistake
32
+
33
+ Treating the accept attribute as security validation or failing silently when a file is rejected.
34
+
35
+ ## Sources
36
+
37
+ - [developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input/file) (verified 2026-10-17)
38
+ - [developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/accept) (verified 2026-10-17)
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)
@@ -0,0 +1,45 @@
1
+ # footer
2
+
3
+ Binding: gap
4
+
5
+ Offer secondary navigation and supporting information at the end of a page.
6
+
7
+ ## Use when
8
+
9
+ Collect site-wide destinations, contact details, and supporting information after the main content.
10
+
11
+ ## Avoid when
12
+
13
+ Do not use the footer to repeat every page section or create a landmark for a small local card footer.
14
+
15
+ ## Structure
16
+
17
+ Use a page-level footer landmark and group related destinations into labelled navigation lists. Keep repeated link order consistent across pages.
18
+
19
+ ## Responsive
20
+
21
+ Allow link groups to wrap or stack while preserving their source order. Avoid clipped columns and tiny tap targets.
22
+
23
+ ## States
24
+
25
+ Keep destinations available at every viewport; do not hide essential links behind hover-only behavior.
26
+
27
+ ## Verify
28
+
29
+ Check the landmark structure, labels for multiple navigation regions, keyboard access, and reflow at narrow widths and zoom.
30
+
31
+ ## Common mistake
32
+
33
+ Using a page-level footer inside a card and unintentionally creating a landmark.
34
+
35
+ ## Custom implementation
36
+
37
+ Use a semantic footer with headings and navigation lists. This app-level pattern does not add a UIify component.
38
+
39
+ Related laws: references/laws/readability.md, references/laws/accessibility.md
40
+
41
+ ## Sources
42
+
43
+ - [www.w3.org](https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/) (verified 2026-10-17)
44
+ - [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/consistent-navigation.html) (verified 2026-10-17)
45
+ - [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html) (verified 2026-10-17)
@@ -0,0 +1,41 @@
1
+ # form
2
+
3
+ Binding: form
4
+
5
+ Collect the information needed to complete one task.
6
+
7
+ ## Use when
8
+
9
+ Collect the information needed to complete one task, such as signing in, registering, or purchasing. Ask only for information the task needs.
10
+
11
+ ## Avoid when
12
+
13
+ Do not make a form for a collection of unrelated actions or for navigation alone.
14
+
15
+ ## Structure
16
+
17
+ `Form` renders a native `<form>` and uses browser validation by default. Label every control; group related choices with `fieldset` and `legend`. Put one clearly named submit action after the fields. `validationBehavior="aria"` sets `noValidate`, so the page must provide its own accessible validation.
18
+
19
+ ## Responsive
20
+
21
+ A single column is a useful default on narrow screens. Keep each label, control, and its instructions together when the layout changes; UIify `Form` does not impose visual layout.
22
+
23
+ ## States
24
+
25
+ Support invalid submission, pending submission, success, and server error. Show detected errors in text, identify each affected field, and keep entered values after failure so the person can correct them.
26
+
27
+ ## Verify
28
+
29
+ Submit empty and malformed values. Confirm browser validation or the page's own validation is active, errors identify the affected controls in text, values remain available after failure, and success and server-error messages are clear.
30
+
31
+ ## Common mistake
32
+
33
+ Disabling submit before explaining validation can leave people stuck. Let the form explain what needs correction.
34
+
35
+ Related laws: references/laws/proximity.md, references/laws/accessibility.md
36
+
37
+ ## Sources
38
+
39
+ - [www.w3.org](https://www.w3.org/WAI/tutorials/forms/grouping/) (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/error-identification.html) (verified 2026-10-17)
@@ -0,0 +1,42 @@
1
+ # header
2
+
3
+ Binding: header
4
+
5
+ Orient visitors with stable top-level navigation.
6
+
7
+ ## Use when
8
+
9
+ Orient people with site identity and primary navigation that stays in a consistent place and order across pages.
10
+
11
+ ## Avoid when
12
+
13
+ Do not turn the header into a second page body or hide all navigation behind a menu on wide screens.
14
+
15
+ ## Structure
16
+
17
+ `Header.Root` renders a semantic `<header>`. Place a home link for the site identity, a named `<nav>` with primary links, and at most one prominent action. Mark the current page link with `aria-current="page"`. Give repeated navigation landmarks distinct names when their link sets differ.
18
+
19
+ ## Responsive
20
+
21
+ Keep the logo and one useful action visible on narrow screens. Move secondary navigation behind a clearly named button that opens a `Modal`; leave the full navigation visible on wide screens.
22
+
23
+ ## States
24
+
25
+ Keep navigation order consistent between pages. The `Header` component itself is static; use `@gunkin/uiify/components/header/client` only when scroll hide/reveal is requested.
26
+
27
+ ## Verify
28
+
29
+ Inspect the accessibility tree for the banner and named navigation landmarks. Tab through the logo, links, and action in reading order; on narrow screens open and close the menu with the keyboard and check its focus and accessible name.
30
+
31
+ ## Common mistake
32
+
33
+ Hiding the entire navigation behind a hamburger on desktop makes common destinations harder to scan.
34
+
35
+ Related laws: references/laws/readability.md, references/laws/accessibility.md
36
+
37
+ ## Sources
38
+
39
+ - [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/consistent-navigation.html) (verified 2026-10-17)
40
+ - [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (verified 2026-10-17)
41
+ - [www.w3.org](https://www.w3.org/WAI/ARIA/apg/practices/landmark-regions/) (verified 2026-10-17)
42
+ - [www.w3.org](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/examples/disclosure-navigation/) (verified 2026-10-17)
@@ -0,0 +1,54 @@
1
+ # hero
2
+
3
+ Binding: gap
4
+
5
+ Introduce the product and its next action.
6
+
7
+ ## Use when
8
+
9
+ Use a hero on a page whose goal is to help people decide what to do next, such as a landing, pricing, or campaign page. Do not add one to settings, dashboards, or docs; start with the task's content.
10
+
11
+ ## Avoid when
12
+
13
+ Do not lead with a generic slogan, a large decorative image, or multiple equally prominent actions.
14
+
15
+ ## Structure
16
+
17
+ Start with one specific `h1` that states the page's purpose, one supporting sentence, and one main action. Add a secondary action only for a different useful path. Use an image only when it shows the product or subject and supports the page's claim; prefer existing assets from the project, preserve the focal point across responsive crops, and provide suitable alternative text. If no suitable asset exists, keep the layout complete without inventing one.
18
+
19
+ ## Responsive
20
+
21
+ On narrow screens, order the text, action, then image. Let translated or long headings wrap, and keep the main action visible without horizontal scrolling.
22
+
23
+ ## States
24
+
25
+ Check a long or translated heading and the layout when no image is available. Keep action labels and focus states clear in both light and dark themes.
26
+
27
+ ## Verify
28
+
29
+ Confirm there is one `h1`, the main action is visible at 390×844 and 1440×900, and content reflows at 320 CSS px without two-dimensional scrolling. Check image alternative text against its purpose.
30
+
31
+ ## Common mistake
32
+
33
+ A generic slogan, decorative gradient, and two equal buttons do not explain the page or the next step.
34
+
35
+ ## Custom implementation
36
+
37
+ Use a named section, semantic heading, supporting copy, and the documented Button. The main action usually opens another page, so render it as a link. Add only static CSS for layout.
38
+
39
+ ```tsx
40
+ <section aria-labelledby="page-title">
41
+ <h1 id="page-title">Plan releases your whole team can follow</h1>
42
+ <p>Orbit turns scattered tasks into one shared release timeline.</p>
43
+ <Button as="a" href="/signup">Start a free trial</Button>
44
+ </section>
45
+ ```
46
+
47
+ Related laws: references/laws/von-restorff.md, references/laws/accessibility.md
48
+
49
+ ## Sources
50
+
51
+ - [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html) (verified 2026-10-17)
52
+ - [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (verified 2026-10-17)
53
+ - [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html) (verified 2026-10-17)
54
+ - [www.w3.org](https://www.w3.org/WAI/tutorials/images/) (verified 2026-10-17)
@@ -0,0 +1,38 @@
1
+ # hover-card
2
+
3
+ Binding: hover-card
4
+
5
+ A link or control has useful supplementary detail that a person may inspect on hover or keyboard focus without leaving the current page
6
+
7
+ ## Use when
8
+
9
+ A link or control has useful supplementary detail that a person may inspect on hover or keyboard focus without leaving the current page. Keep it optional and short.
10
+
11
+ ## Avoid when
12
+
13
+ Do not place essential instructions, required actions, or the only copy of important information in a hover card. Do not use it for a brief label (tooltip) or a menu of actions.
14
+
15
+ ## Structure
16
+
17
+ Compose `HoverCard` Root, Trigger, and Content. Give the trigger a meaningful name on its own; the card supplements it rather than repairing an ambiguous link label.
18
+
19
+ ## Responsive
20
+
21
+ The card opens on mouse hover and keyboard focus. Touch users need the same essential information elsewhere in the page and a usable trigger. Keep content narrow enough to fit without obscuring nearby controls.
22
+
23
+ ## States
24
+
25
+ Focus or mouse hover opens the card; pointer movement into the content keeps it open, and leaving schedules close. Configure open/close delays only when they improve pointer travel without making content feel unresponsive.
26
+
27
+ ## Verify
28
+
29
+ Test keyboard focus, mouse travel from trigger to card, dismissibility, persistence while moving the pointer, narrow viewports, and that all essential content remains available without hover.
30
+
31
+ ## Common mistake
32
+
33
+ A hover card that closes while the pointer travels from its trigger to its content fails the hover/focus content requirements.
34
+
35
+ ## Sources
36
+
37
+ - [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/content-on-hover-or-focus.html) (verified 2026-10-17)
38
+ - [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html) (verified 2026-10-17)