@gunkin/uiify 0.0.17-alpha → 0.0.19-alpha

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gunkin/uiify",
-  "version": "0.0.17-alpha",
+  "version": "0.0.19-alpha",
   "description": "Native-first, accessible React 19 components that work before hydration.",
   "keywords": [
     "accessibility",

package/skills/uiify/SKILL.md

@@ -18,6 +18,19 @@ Use the explicit request in the conversation if the client does not substitute `
 
 Reuse existing design decisions, tokens and conventions, including `DESIGN.md` when present. Do not create `DESIGN.md` or a managed state block merely because this skill was invoked. Create or update planning files only when the user or project workflow calls for them, preserving unrelated content. Keep changes within the requested page and necessary source files; setup and dependency changes follow the user's request and project rules.
 
+## Choose an approach before composition
+
+Use the request to choose an internal approach; do not ask the user to choose a mode:
+
+- Reproduce an explicit visual reference while preserving its layout, content and recognizable details; read the reference guide before choosing composition and compare again after rendering.
+- Extend the existing UI for a scoped change; keep surrounding routes and established design choices intact.
+- Create or redesign when the request asks for a new page or a broad visual change.
+- Audit when the user asks for findings rather than implementation; report observed issues and evidence.
+
+Use this precedence: explicit brief or reference → existing project → selected recipes → aesthetic guidance. This classification only guides the work; continue the agent's normal workflow.
+
+When images or typography shape the composition, read `references/guides/assets.md` before choosing material. Skip it for routine UI changes where imagery and type are not part of the design decision.
+
 ## Select knowledge for the page
 
 Match the needed elements to the Index by name or alias. Use the listed component binding; never invent a binding. A `gap` or an unlisted element needs custom UI, not a guessed UIify API.
@@ -30,6 +43,15 @@ For mapped components, read the resolved package's `agents/index.md` once and th
 
 Consult `frontend-design` when available for design direction; if absent, use the built-in guidance below. Consult `vercel-react-best-practices` for relevant React performance decisions and `web-design-guidelines` for reviews. These skills are optional references. UIify's public component and styling contracts take precedence over conflicting advice.
 
+After the page renders, review it with a guide only when its question applies:
+
+- `references/guides/surface.md` — what kind of page is this, and how expressive should it be?
+- `references/guides/reference.md` — only when a reference or existing page is being compared.
+- `references/guides/assets.md` — only when images or typography shape the composition.
+- `references/guides/hierarchy.md` — what leads the eye, and do the parts read in the right order?
+- `references/guides/content.md` — does the copy say what this page and each action actually do?
+- `references/guides/states.md` — does the page still work outside the happy path?
+
 Ground the visual direction in the subject, audience and primary job. Plan clear typography, hierarchy, grouping, purposeful copy and responsive layout using existing semantic color roles. Choose one signature detail appropriate to the subject and keep the rest restrained. Avoid defaulting to a gradient hero, repeated equal cards or decorative numbering without a reason. Preserve visible focus, keyboard-sized targets and reduced-motion behavior.
 
 For a settings page, group fields by the decision the person makes, keep labels and validation close to controls, and give one `Button` the save action. Use documented anatomy:
@@ -47,7 +69,7 @@ Do not add an unrelated marketing hero or make every field group an equally prom
 
 ## Verification guidance
 
-Use applicable project build, typecheck and test commands when permitted. The optional `node <resolved-skill-directory>/scripts/lint.mjs <project-root>` checks only the static subset enabled by accepted laws in existing design state. No enabled checks is not proof of accessibility. Missing parsers or execution failures mean unavailable, never a pass.
+Use applicable project build, typecheck and test commands when permitted. The optional `node <resolved-skill-directory>/scripts/lint.mjs <project-root>` runs the static checks compiled from the published laws when this skill was built and prints their names; it does not read `DESIGN.md` or other design files. It inspects literal attributes of lowercase intrinsic JSX tags and of parts imported from `@gunkin/uiify/components` or `@gunkin/uiify/elements` (for example `Button` or `Field.Control`); other custom components are not analyzed. No findings is not proof of accessibility. Missing parsers or execution failures mean unavailable, never a pass.
 
 Reuse existing browser and accessibility tooling to inspect responsive layouts, keyboard access and requested interactions. When missing tools are needed for quality verification, use Playwright for browser checks and axe-core (or the project's axe integration) for accessibility checks. Before installing missing Playwright or axe-core packages or downloading browser binaries, notify the user briefly in their language, explaining what will be installed and why. For example: “I'll install Playwright and axe-core as development tools to check the page in a browser and catch accessibility issues.” This is a notification, not a confirmation question; continue within existing authorization and respect project installation rules. Use the project's package manager and development dependencies, reuse existing integrations, and install only what is needed.
 
@@ -58,75 +80,75 @@ Repair findings within the task's scope and rerun the affected checks. If comman
 One line per element: `element|aliases|uiify component or gap|reference path`. A blank final field means no curated reference.
 
 ```text
-accordion|faq-accordion,disclosure|accordion|
+accordion|faq-accordion,disclosure|accordion|references/elements/accordion.md
 alert-modal|confirmation-dialog,alert-dialog|alert-modal|references/elements/alert-modal.md
 avatar|profile-picture|gap|references/elements/avatar.md
 badge|chip,tag|gap|references/elements/badge.md
 bar-chart|column-chart|gap|references/elements/bar-chart.md
-breadcrumb|breadcrumbs|breadcrumb|
+breadcrumb|breadcrumbs|breadcrumb|references/elements/breadcrumb.md
 button|cta-button,icon-button,primary-button|button|references/elements/button.md
-candle-chart|candlestick-chart|candle-chart|
+candle-chart|candlestick-chart|candle-chart|references/elements/candle-chart.md
 card|content-card|gap|references/elements/card.md
-carousel|testimonial-carousel,image-slider|carousel|
-checkbox||checkbox|
+carousel|testimonial-carousel,image-slider|carousel|references/elements/carousel.md
+checkbox||checkbox|references/elements/checkbox.md
 code-block|code-snippet|gap|references/elements/code-block.md
-collapsible|expandable-section|collapsible|
-color-picker||color-picker|
-combobox|autocomplete,typeahead|combobox|
+collapsible|expandable-section|collapsible|references/elements/collapsible.md
+color-picker||color-picker|references/elements/color-picker.md
+combobox|autocomplete,typeahead|combobox|references/elements/combobox.md
 command-palette|spotlight-search|gap|references/elements/command-palette.md
-context-menu|right-click-menu|context-menu|
+context-menu|right-click-menu|context-menu|references/elements/context-menu.md
 cookie-banner|cookie-consent|gap|references/elements/cookie-banner.md
 date-picker|calendar-picker|gap|references/elements/date-picker.md
 divider|separator|gap|references/elements/divider.md
-drawer|sheet,off-canvas-menu|drawer|
-dropdown-menu|menu|dropdown-menu|
+drawer|sheet,off-canvas-menu|drawer|references/elements/drawer.md
+dropdown-menu|menu|dropdown-menu|references/elements/dropdown-menu.md
 empty-state|no-results|gap|references/elements/empty-state.md
 feature-grid|feature-cards,feature-list|gap|references/elements/feature-grid.md
 field|form-field|field|references/elements/field.md
-file-upload|file-input,dropzone|file-upload|
+file-upload|file-input,dropzone|file-upload|references/elements/file-upload.md
 footer|site-footer|gap|references/elements/footer.md
 form||form|references/elements/form.md
 header|navbar,top-nav|header|references/elements/header.md
 hero|hero-section,hero-banner|gap|references/elements/hero.md
-hover-card||hover-card|
+hover-card||hover-card|references/elements/hover-card.md
 image-gallery|gallery,lightbox|gap|references/elements/image-gallery.md
 inline-alert|banner-alert,callout|gap|references/elements/inline-alert.md
 input|text-input|input|references/elements/input.md
-line-chart|sparkline|line-chart|
+line-chart|sparkline|line-chart|references/elements/line-chart.md
 logo-wall|logo-cloud,customer-logos|gap|references/elements/logo-wall.md
-modal|dialog|modal|
-number-field|number-input|number-field|
-otp-input|pin-input|otp-input|
+modal|dialog|modal|references/elements/modal.md
+number-field|number-input|number-field|references/elements/number-field.md
+otp-input|pin-input|otp-input|references/elements/otp-input.md
 pagination||pagination|references/elements/pagination.md
 password-input|show-hide-password|gap|references/elements/password-input.md
-popup|popover|popup|
+popup|popover|popup|references/elements/popup.md
 pricing-table|pricing,plan-cards,pricing-plans|gap|references/elements/pricing-table.md
 progress-bar|progress,linear-progress|gap|references/elements/progress-bar.md
-radio-group|radio|radio-group|
-rating|star-rating|rating|
+radio-group|radio|radio-group|references/elements/radio-group.md
+rating|star-rating|rating|references/elements/rating.md
 search-input|search-box|gap|references/elements/search-input.md
-segmented-control||segmented-control|
+segmented-control||segmented-control|references/elements/segmented-control.md
 select|native-select|select|references/elements/select.md
 sidebar|sidebar-nav,side-nav|gap|references/elements/sidebar.md
-skeleton|skeleton-loader|skeleton|
-slider|range-slider|slider|
-spinner|loading-indicator|spinner|
+skeleton|skeleton-loader|skeleton|references/elements/skeleton.md
+slider|range-slider|slider|references/elements/slider.md
+spinner|loading-indicator|spinner|references/elements/spinner.md
 stats-bar|stat-card,metrics|gap|references/elements/stats-bar.md
 stepper|step-indicator,wizard-steps|gap|references/elements/stepper.md
 switch|toggle-switch|switch|references/elements/switch.md
 table|data-table,comparison-table|table|references/elements/table.md
-table-of-contents|toc,in-page-nav|table-of-contents|
-tabs|tab-navigation|tabs|
-tags-input|token-input|tags-input|
+table-of-contents|toc,in-page-nav|table-of-contents|references/elements/table-of-contents.md
+tabs|tab-navigation|tabs|references/elements/tabs.md
+tags-input|token-input|tags-input|references/elements/tags-input.md
 testimonial|testimonials,quote-card|gap|references/elements/testimonial.md
 textarea||textarea|references/elements/textarea.md
 timeline||gap|references/elements/timeline.md
 toast|snackbar,toast-notification|toast|references/elements/toast.md
-toggle|toggle-button|toggle|
-toggle-group|button-group|toggle-group|
-toolbar||toolbar|
-tooltip||tooltip|
-virtual-scroll|virtualized-list|virtual-scroll|
+toggle|toggle-button|toggle|references/elements/toggle.md
+toggle-group|button-group|toggle-group|references/elements/toggle-group.md
+toolbar||toolbar|references/elements/toolbar.md
+tooltip||tooltip|references/elements/tooltip.md
+virtual-scroll|virtualized-list|virtual-scroll|references/elements/virtual-scroll.md
 ```
 
 ## Composition index

package/skills/uiify/references/compositions/card-rhythm.md

@@ -6,8 +6,6 @@ Law: references/laws/proximity.md
 
 ## Rule
 
-## Rule
-
 Keep cards in one group only when the items share a purpose and hierarchy. Preserve readable separation and source order as the layout becomes a single column.
 
 ## Sources

package/skills/uiify/references/compositions/destructive-confirmation.md

@@ -6,9 +6,7 @@ Law: references/laws/error-prevention.md
 
 ## Rule
 
-## Rule
-
-State the consequence in the dialog title or message. Name both the destructive action and the safe way to cancel, identify the dialog, and follow the modal-dialog focus and keyboard pattern.
+State the consequence in the dialog title or message. Name both the destructive action and the safe way to cancel. Put initial focus on the safe action; Cancel and Escape preserve the item and return focus. After confirmation removes the item, move focus to a connected element. Identify the dialog and follow the modal-dialog keyboard pattern.
 
 ## Sources
 

package/skills/uiify/references/compositions/form-grouping.md

@@ -6,8 +6,6 @@ Law: references/laws/proximity.md
 
 ## Rule
 
-## Rule
-
 Group related controls with a fieldset and legend. Keep each control labelled and present groups in the order people complete them.
 
 ## Sources

package/skills/uiify/references/compositions/hero-actions.md

@@ -6,11 +6,9 @@ Law: references/laws/von-restorff.md
 
 ## Rule
 
-## Rule
-
-Make the primary action easy to identify and keep the secondary action visually quieter. Use concrete action labels and retain visible keyboard focus.
+Place the main action beside the hero message it advances, give it the clearest emphasis and an outcome-specific label, then place any secondary action after it with quieter treatment. Preserve that reading order when actions stack.
 
 ## Sources
 
-- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html) (verified 2026-10-16)
-- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (verified 2026-10-16)
+- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html) (verified 2026-10-17)
+- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (verified 2026-10-17)

package/skills/uiify/references/compositions/page-frame.md

@@ -6,8 +6,6 @@ Law: references/laws/readability.md
 
 ## Rule
 
-## Rule
-
 Use consistent page landmarks and repeated navigation order. Align header, main content and footer to one responsive content measure without clipping narrow screens.
 
 ## Sources

package/skills/uiify/references/compositions/pricing-actions.md

@@ -6,8 +6,6 @@ Law: references/laws/proximity.md
 
 ## Rule
 
-## Rule
-
 Keep each plan action associated with the plan name, price and included features. Let the page stack plans at narrow widths without changing their reading order.
 
 ## Sources

package/skills/uiify/references/compositions/save-feedback.md

@@ -6,9 +6,7 @@ Law: references/laws/feedback.md
 
 ## Rule
 
-## Rule
-
-Place save feedback near the action it describes and announce the update as a status message. Keep the message understandable without color or motion.
+Place save feedback near the action it describes and announce the update as a status message. Preserve valid field values when validation fails; allow correction and a successful save. Keep the message understandable without color or motion.
 
 ## Sources
 

package/skills/uiify/references/compositions/table-controls.md

@@ -6,9 +6,7 @@ Law: references/laws/proximity.md
 
 ## Rule
 
-## Rule
-
-Keep labeled search and filters associated with the table they change. Identify the current page and preserve a clear sequence from controls to rows to pagination.
+Keep labeled search and filters associated with the table they change. Applying a filter returns to a valid page with matching rows; Reset restores the original result set and first page. Identify the current page and preserve a clear sequence from controls to rows to pagination.
 
 ## Sources
 

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

@@ -0,0 +1,38 @@
+# accordion
+
+Binding: accordion
+
+Reveal optional sections without hiding content most visitors need.
+
+## Use when
+
+Use for FAQs or optional details when visitors need only a small subset. Keep content visible when most visitors need it; use `stepper` for sequential tasks.
+
+## Avoid when
+
+Do not hide the page's main explanation or an action that is the only way to continue inside a closed section.
+
+## Structure
+
+`Accordion` takes an `id`, `items` with a `value`, `label`, and `panel`, and `type="single"` or `"multiple"`. The visible summary is the question or section title; make it describe the revealed content. Single mode uses native `<details name>` grouping, so opening one section closes the other.
+
+## Responsive
+
+Let long summaries wrap and preserve a clear open/closed cue. Keep summaries and their focus indicators visible at narrow widths.
+
+## States
+
+Items start closed unless selected by `defaultValue`. Native `<details>` supports keyboard activation; its `name` group permits only one open section at a time. Search behavior for text inside closed sections can vary, so verify it in target browsers when page search matters.
+
+## Verify
+
+Use Tab to reach each summary, Enter or Space to toggle it, and confirm the focus indicator remains visible. Check long labels, single and multiple modes, and whether browser find-in-page reveals matching closed content in supported target browsers.
+
+## Common mistake
+
+Hiding the only primary action in a section that starts closed makes the page's next step easy to miss.
+
+## Sources
+
+- [developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details) (verified 2026-10-17)
+- [www.w3.org](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/) (verified 2026-10-17)

package/skills/uiify/references/elements/alert-modal.md

@@ -2,14 +2,41 @@
 
 Binding: alert-modal
 
-Confirm an irreversible action before executing it.
+A short, important message requires an immediate response, especially confirmation before a consequential action
 
-Explain the consequence before asking for a decision. Give the dialog a clear title, keep the safe action available, and return focus after the choice.
+## Use when
+
+A short, important message requires an immediate response, especially confirmation before a consequential action. Use a regular modal for a task or optional information, and inline validation for recoverable form errors.
+
+## Avoid when
+
+Do not use alert dialogs for routine notices or long, structured content. Do not make a destructive choice the default or leave consequences implicit.
+
+## Structure
+
+The convenience `AlertModal` provides a trigger, visible title, optional short description, Cancel, and Action. State the consequence in the description and make both choices explicit; the action uses the destructive variant.
+
+## Responsive
+
+Keep the message concise so it remains understandable in the modal at narrow widths and zoom. Allow the text to wrap; do not rely on color or icon alone to explain the consequence.
+
+## States
+
+Tier 0 uses a native modal [dialog role=alertdialog] opened by native invokers. Cancel and Action request close. Use the client entry only when application-controlled state is required.
+
+## Verify
+
+Check the accessible name and description, opening and closing by keyboard, focus containment and return, both explicit choices, and the narrow/zoomed layout. Confirm initial focus lands on Cancel, the safe choice: `AlertModal` renders Cancel before Action, so keep focusable content out of the dialog body above them.
+
+## Common mistake
+
+A red Delete button is not enough: name what will be deleted and what happens after each choice.
+Example: `references/examples/alert-confirmation.md`.
 
 Related laws: references/laws/error-prevention.md, references/laws/accessibility.md
 
 ## Sources
 
-- [www.w3.org](https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/) (verified 2026-10-16)
-- [www.w3.org](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/) (verified 2026-10-16)
-- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html) (verified 2026-10-16)
+- [www.w3.org](https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/) (verified 2026-10-17)
+- [www.w3.org](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/) (verified 2026-10-17)
+- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html) (verified 2026-10-17)

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

@@ -4,15 +4,44 @@ Binding: gap
 
 Identify a person or account with a compact image and fallback.
 
-When text beside the image already identifies the person, use an empty alt value; otherwise write a concise alternative that identifies the person without repeating nearby text.
+## Use when
+
+A person's identity helps distinguish nearby content, such as a participant list or comment author.
+
+## Avoid when
+
+Do not add a portrait when the name already provides all needed context and the image adds no information. Do not use an avatar as the only way to identify a person.
+
+## Structure
+
+This is an app-level composition, not a UIify component. Use an img with concise alt text when the portrait adds identity; use alt="" when visible adjacent text already names the person. Keep the name as text.
+
+## Responsive
+
+Set intrinsic dimensions to reserve space, preserve a consistent crop, and avoid shrinking the image below its useful size.
+
+## States
+
+Provide a stable initials or generic fallback when no usable image exists. If the image fails, keep the person's visible name.
+
+## Verify
+
+Check image alternative against nearby text, loading/failure fallback, intrinsic dimensions, and list reading order.
+
+## Common mistake
+
+Repeating the adjacent name in alt text makes assistive technology announce the same identity twice.
+
+## Custom implementation
 
 ```html
 <img src="/people/ada.webp" width="40" height="40" alt="" />
 <span>Ada Lovelace</span>
 ```
 
-The empty alternative is appropriate here because the adjacent text already names the person.
+This is an app-level composition; UIify does not currently ship this component.
 
 ## Sources
 
 - [developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img) (verified 2026-10-16)
+- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/non-text-content.html) (verified 2026-10-16)

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

@@ -4,15 +4,44 @@ Binding: gap
 
 Mark a short status or category beside related content.
 
-Keep a badge short and attach it to the item it qualifies. If the text conveys status, include the status in words and do not rely on color alone.
+## Use when
+
+A short status or category qualifies nearby content and helps people scan it.
+
+## Avoid when
+
+Do not use a badge for a control, long explanation, or decoration that repeats an adjacent heading without adding meaning.
+
+## Structure
+
+This is an app-level composition, not a UIify component. Use non-interactive text beside the item it qualifies. Include the status in words; color and shape are supplementary.
+
+## Responsive
+
+Allow text to wrap or choose a concise label that remains readable at zoom. Keep the badge attached to its related heading or value in reading order.
+
+## States
+
+For status changes, update the text and announce meaningful dynamic changes in an appropriate status region. Do not use badge styling alone to indicate selection.
+
+## Verify
+
+Check text contrast, status conveyed without color, association with the item, zoom, and dynamic announcement only when needed.
+
+## Common mistake
+
+A green dot without a textual status does not explain what “active” means.
+
+## Custom implementation
 
 ```html
-<span>Pending review</span>
+<p>Deployment <span>Pending review</span></p>
 ```
 
-This is an app-level composition recipe; it does not add a component to UIify.
+This is an app-level composition; UIify does not currently ship this component.
 
 ## Sources
 
 - [developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span) (verified 2026-10-16)
 - [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (verified 2026-10-16)
+- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html) (verified 2026-10-16)

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

@@ -4,26 +4,58 @@ Binding: gap
 
 Compare values across a small set of named categories.
 
-Give the chart a concise caption and provide the same values in a readable table. Treat chart color and geometry as supporting views of the values.
+## Use when
+
+Values are best compared across a modest set of named categories.
+
+## Avoid when
+
+Do not use a chart when a labeled table communicates the values more clearly, or when the category count makes bars and labels unreadable.
+
+## Structure
+
+This is an app-level composition, not a UIify component. Give the chart a concise title and text summary, label units and the compared period, and provide the same data in a readable table. Use SVG as a visual summary with a short accessible name.
+
+## Responsive
+
+Keep category names and values available when the graphic scales down. If the plot becomes cramped, allow a scrollable plot while leaving its data table readable.
+
+## States
+
+If values update, identify the period/version and expose the updated data in the table. Do not use color alone to distinguish series.
+
+## Verify
+
+Compare every plotted value with the table, check chart title/summary, units, axis labels, color contrast, and narrow viewport access.
+
+## Common mistake
+
+An SVG label such as “Sales chart” names the image but does not provide its values or trend.
+
+## Custom implementation
 
 ```html
 <figure>
-  <figcaption>Signups by month</figcaption>
-  <svg role="img" aria-label="January 12, February 19">…</svg>
+  <figcaption>Signups by month, Q1 2026</figcaption>
+  <svg role="img" aria-label="Signups rise from 12 in January to 19 in February and 24 in March">
+    <!-- Render bars with category/value labels or a clear axis. -->
+  </svg>
   <table>
-    <caption>Signups by month</caption>
+    <caption>Signups by month (number of accounts)</caption>
     <thead><tr><th scope="col">Month</th><th scope="col">Signups</th></tr></thead>
     <tbody>
       <tr><th scope="row">January</th><td>12</td></tr>
       <tr><th scope="row">February</th><td>19</td></tr>
+      <tr><th scope="row">March</th><td>24</td></tr>
     </tbody>
   </table>
 </figure>
 ```
 
-This is an app-level composition recipe; it does not add a component to UIify.
+This is an app-level composition; UIify does not currently ship this component.
 
 ## Sources
 
-- [developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/figure) (verified 2026-10-16)
-- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (verified 2026-10-16)
+- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/non-text-content.html) (verified 2026-10-16)
+- [www.w3.org](https://www.w3.org/WAI/tutorials/images/complex/) (verified 2026-10-16)
+- [developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/img_role) (verified 2026-10-16)

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

@@ -0,0 +1,38 @@
+# breadcrumb
+
+Binding: breadcrumb
+
+Show the current page within a hierarchy of parent pages.
+
+## Use when
+
+Show where the current page sits in a hierarchy and provide links to parent pages.
+
+## Avoid when
+
+Do not use breadcrumbs as the only way to navigate or show unrelated destinations.
+
+## Structure
+
+Use BreadcrumbRoot, BreadcrumbList, BreadcrumbItem, and BreadcrumbLink inside a labelled navigation landmark. Keep items in ancestor order, use current to identify the current page, and use links for ancestors.
+
+## Responsive
+
+Let long labels wrap or collapse middle ancestors with the documented items and maxItems props. Keep the current page visible.
+
+## States
+
+For a short trail, render each item. For a collapsed trail, make the omitted ancestors available through the documented native disclosure.
+
+## Verify
+
+Check that the navigation landmark has a name, ancestors are links, and the current page is announced as current. Test a long trail with keyboard and at a narrow viewport.
+
+## Common mistake
+
+Making the current page look like a link when it does not navigate.
+
+## Sources
+
+- [www.w3.org](https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/) (verified 2026-10-17)
+- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (verified 2026-10-17)

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

@@ -4,11 +4,46 @@ Binding: button
 
 Expose a clear action with its native interaction semantics.
 
-Name the action with a concrete verb. Use one visually prominent action for the current decision and keep secondary actions understandable.
+## Use when
+
+The person triggers an action on this page: submit a form, save, confirm, open a dialog or start a flow. `as="a"` gives a link the Button skin; the element stays a link.
+
+## Avoid when
+
+The control moves to another page: use a link (`<a href>` or `Button as="a"`). A choice between options is a `segmented-control` or `toggle-group`, not several buttons.
+
+## Structure
+
+One visible label names the result with a verb: "Save changes", "Invite member". An icon-only button (`size="icon"`) needs an accessible name through `aria-label`.
+
+```tsx
+<Button type="submit">Save changes</Button>
+<Button variant="ghost">Cancel</Button>
+```
+
+`Button` renders a native `<button>` with `type="button"` unless `type` is given; pass `type="submit"` inside a form.
+
+## Responsive
+
+Labels fit at 320 CSS px without truncation; shorten the copy rather than the target. In a narrow action row keep the primary action first in reading order and let the buttons wrap or stack instead of hiding one.
+
+## States
+
+Disabled: say nearby why the action is unavailable, or keep it enabled and validate on submit. Busy: keep the label and width, show progress text such as "Saving…" and ignore a second press. `selected` only for a toggle that stays on.
+
+## Verify
+
+Tab reaches every button in reading order with a visible focus indicator; Enter and Space activate it. One default (solid) button per decision area. Icon-only buttons have a non-empty name in the accessibility tree.
+
+## Common mistake
+
+Two solid buttons side by side, such as "Save" and "Delete", make people compare colors instead of labels. Keep one solid action, use `variant="outline"` or `"ghost"` for the alternative and `variant="destructive"` only where data is removed.
 
 Related laws: references/laws/von-restorff.md, references/laws/accessibility.md
 
 ## Sources
 
-- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html) (verified 2026-10-16)
-- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (verified 2026-10-16)
+- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html) (verified 2026-10-17)
+- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (verified 2026-10-17)
+- [www.w3.org](https://www.w3.org/WAI/ARIA/apg/patterns/button/) (verified 2026-10-17)
+- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html) (verified 2026-10-17)

package/skills/uiify/references/elements/candle-chart.md

@@ -0,0 +1,38 @@
+# candle-chart
+
+Binding: candle-chart
+
+Ordered market-style observations need open, high, low, and close values in each time interval
+
+## Use when
+
+Ordered market-style observations need open, high, low, and close values in each time interval.
+
+## Avoid when
+
+Do not use candlesticks for generic category comparisons or hide exact values in a visual glyph. This component visualizes data; it does not provide financial recommendations.
+
+## Structure
+
+Use `CandleChart` with ordered time/open/high/low/close data, a descriptive label, and axis labels. UIify includes a data table fallback. Use /client for interactive crosshair/readout or live virtualized history.
+
+## Responsive
+
+Keep exact OHLC values available when candles become narrow. In live mode, the table follows the visible candles; provide another way to reach full history if needed.
+
+## States
+
+The static chart works without JavaScript. Interactive candles support pointer selection and an announced readout; suppress high-frequency readout announcements for streaming data.
+
+## Verify
+
+Check each candle's values against the table, chronological ordering, axis/time labels, keyboard access to interactive controls, update behavior, and mobile viewport.
+
+## Common mistake
+
+Coloring rising and falling candles without a table and explicit value labels makes the chart's information unavailable to many users.
+
+## Sources
+
+- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/non-text-content.html) (verified 2026-10-17)
+- [www.w3.org](https://www.w3.org/WAI/tutorials/images/complex/) (verified 2026-10-17)