@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.
- package/README.md +34 -9
- package/package.json +1 -1
- package/skills/uiify/SKILL.md +125 -125
- package/skills/uiify/references/compositions/card-rhythm.md +14 -0
- package/skills/uiify/references/compositions/destructive-confirmation.md +15 -0
- package/skills/uiify/references/compositions/form-grouping.md +14 -0
- package/skills/uiify/references/compositions/hero-actions.md +14 -0
- package/skills/uiify/references/compositions/page-frame.md +14 -0
- package/skills/uiify/references/compositions/pricing-actions.md +13 -0
- package/skills/uiify/references/compositions/save-feedback.md +13 -0
- package/skills/uiify/references/compositions/table-controls.md +14 -0
- package/skills/uiify/references/elements/accordion.md +38 -0
- package/skills/uiify/references/elements/alert-modal.md +42 -0
- package/skills/uiify/references/elements/avatar.md +47 -0
- package/skills/uiify/references/elements/badge.md +47 -0
- package/skills/uiify/references/elements/bar-chart.md +61 -0
- package/skills/uiify/references/elements/breadcrumb.md +38 -0
- package/skills/uiify/references/elements/button.md +49 -0
- package/skills/uiify/references/elements/candle-chart.md +38 -0
- package/skills/uiify/references/elements/card.md +51 -0
- package/skills/uiify/references/elements/carousel.md +38 -0
- package/skills/uiify/references/elements/checkbox.md +39 -0
- package/skills/uiify/references/elements/code-block.md +50 -0
- package/skills/uiify/references/elements/collapsible.md +38 -0
- package/skills/uiify/references/elements/color-picker.md +39 -0
- package/skills/uiify/references/elements/combobox.md +37 -0
- package/skills/uiify/references/elements/command-palette.md +43 -0
- package/skills/uiify/references/elements/context-menu.md +38 -0
- package/skills/uiify/references/elements/cookie-banner.md +51 -0
- package/skills/uiify/references/elements/date-picker.md +43 -0
- package/skills/uiify/references/elements/divider.md +46 -0
- package/skills/uiify/references/elements/drawer.md +38 -0
- package/skills/uiify/references/elements/dropdown-menu.md +38 -0
- package/skills/uiify/references/elements/empty-state.md +50 -0
- package/skills/uiify/references/elements/feature-grid.md +54 -0
- package/skills/uiify/references/elements/field.md +44 -0
- package/skills/uiify/references/elements/file-upload.md +40 -0
- package/skills/uiify/references/elements/footer.md +45 -0
- package/skills/uiify/references/elements/form.md +41 -0
- package/skills/uiify/references/elements/header.md +42 -0
- package/skills/uiify/references/elements/hero.md +54 -0
- package/skills/uiify/references/elements/hover-card.md +38 -0
- package/skills/uiify/references/elements/image-gallery.md +52 -0
- package/skills/uiify/references/elements/inline-alert.md +46 -0
- package/skills/uiify/references/elements/input.md +41 -0
- package/skills/uiify/references/elements/line-chart.md +38 -0
- package/skills/uiify/references/elements/logo-wall.md +49 -0
- package/skills/uiify/references/elements/modal.md +38 -0
- package/skills/uiify/references/elements/number-field.md +39 -0
- package/skills/uiify/references/elements/otp-input.md +39 -0
- package/skills/uiify/references/elements/pagination.md +41 -0
- package/skills/uiify/references/elements/password-input.md +43 -0
- package/skills/uiify/references/elements/popup.md +38 -0
- package/skills/uiify/references/elements/pricing-table.md +66 -0
- package/skills/uiify/references/elements/progress-bar.md +47 -0
- package/skills/uiify/references/elements/radio-group.md +39 -0
- package/skills/uiify/references/elements/rating.md +39 -0
- package/skills/uiify/references/elements/search-input.md +45 -0
- package/skills/uiify/references/elements/segmented-control.md +39 -0
- package/skills/uiify/references/elements/select.md +42 -0
- package/skills/uiify/references/elements/sidebar.md +43 -0
- package/skills/uiify/references/elements/skeleton.md +38 -0
- package/skills/uiify/references/elements/slider.md +39 -0
- package/skills/uiify/references/elements/spinner.md +38 -0
- package/skills/uiify/references/elements/stats-bar.md +49 -0
- package/skills/uiify/references/elements/stepper.md +43 -0
- package/skills/uiify/references/elements/switch.md +41 -0
- package/skills/uiify/references/elements/table-of-contents.md +39 -0
- package/skills/uiify/references/elements/table.md +43 -0
- package/skills/uiify/references/elements/tabs.md +38 -0
- package/skills/uiify/references/elements/tags-input.md +39 -0
- package/skills/uiify/references/elements/testimonial.md +52 -0
- package/skills/uiify/references/elements/textarea.md +41 -0
- package/skills/uiify/references/elements/timeline.md +48 -0
- package/skills/uiify/references/elements/toast.md +39 -0
- package/skills/uiify/references/elements/toggle-group.md +39 -0
- package/skills/uiify/references/elements/toggle.md +39 -0
- package/skills/uiify/references/elements/toolbar.md +39 -0
- package/skills/uiify/references/elements/tooltip.md +38 -0
- package/skills/uiify/references/elements/virtual-scroll.md +39 -0
- package/skills/uiify/references/examples/alert-confirmation.md +34 -0
- package/skills/uiify/references/examples/field-validation.md +37 -0
- package/skills/uiify/references/examples/select-basic.md +35 -0
- package/skills/uiify/references/examples/table-controls.md +40 -0
- package/skills/uiify/references/guides/assets.md +14 -0
- package/skills/uiify/references/guides/content.md +11 -0
- package/skills/uiify/references/guides/hierarchy.md +14 -0
- package/skills/uiify/references/guides/reference.md +9 -0
- package/skills/uiify/references/guides/states.md +12 -0
- package/skills/uiify/references/guides/surface.md +27 -0
- package/skills/uiify/references/laws/accessibility.md +11 -0
- package/skills/uiify/references/laws/error-prevention.md +12 -0
- package/skills/uiify/references/laws/feedback.md +9 -0
- package/skills/uiify/references/laws/proximity.md +10 -0
- package/skills/uiify/references/laws/readability.md +9 -0
- package/skills/uiify/references/laws/von-restorff.md +9 -0
- package/skills/uiify/scripts/lint.mjs +1 -1
- 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)
|