@gunkin/uiify 0.0.17-alpha → 0.0.19-alpha

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

@@ -0,0 +1,39 @@
+# toolbar
+
+Binding: toolbar
+
+Group three or more related controls with a compact keyboard navigation model.
+
+## Use when
+
+Group at least three related controls that act on the same object or task.
+
+## Avoid when
+
+Do not use toolbar semantics for a small set of unrelated actions or when controls need their own ordinary Tab stops.
+
+## Structure
+
+Use the documented Toolbar.Root with an accessible name and a consistent orientation. Use buttons for actions, links for navigation, and selected state only for toggle buttons.
+
+## Responsive
+
+Let controls wrap only if arrow-key movement still follows a predictable order; otherwise provide a scrollable group or switch to ordinary controls with Tab navigation.
+
+## States
+
+The toolbar uses one Tab stop with arrow-key movement among enabled controls. Disabled controls are skipped; expose toggle state with the documented selected button behavior.
+
+## Verify
+
+Test Tab entry/exit, arrow movement, orientation, disabled items, toggle announcements, and operation with a keyboard.
+
+## Common mistake
+
+Adding role="toolbar" without implementing its expected arrow-key focus management.
+
+## Sources
+
+- [www.w3.org](https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/) (verified 2026-10-17)
+- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html) (verified 2026-10-17)
+- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html) (verified 2026-10-17)

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

@@ -0,0 +1,38 @@
+# tooltip
+
+Binding: tooltip
+
+Add a brief supplemental label to a control without replacing its name.
+
+## Use when
+
+Add a short, supplemental explanation to an icon-only control or unfamiliar action. Keep the control's accessible name on the trigger; tooltip text does not replace it.
+
+## Avoid when
+
+Do not put essential instructions or interactive content in a tooltip. Keep field labels visible; use `popup` or `hover-card` for content that needs interaction.
+
+## Structure
+
+Nest `Tooltip.Root`, `Tooltip.Trigger`, and `Tooltip.Content` inside `Tooltip.Provider`. Content is a non-focusable tooltip associated with its trigger. For touch users, make the same information available without hover.
+
+## Responsive
+
+Keep tooltip text brief and ensure it remains within the viewport. Touch has no hover, so essential information must remain available through visible text or another deliberate interaction.
+
+## States
+
+UIify opens on mouse hover after the provider delay and immediately on keyboard focus; Escape closes it. Focus stays on the trigger. The WAI-ARIA APG tooltip pattern is still work in progress, so treat it as guidance rather than a settled standard.
+
+## Verify
+
+Focus the trigger with the keyboard and confirm the tooltip appears and is referenced by the trigger. Confirm Escape dismisses it, pointer movement between trigger and content does not close it prematurely, and the content is not clipped at viewport edges. Check the equivalent touch interaction.
+
+## Common mistake
+
+Using a tooltip as the only label for a field leaves the field unnamed when the tooltip is unavailable.
+
+## Sources
+
+- [www.w3.org](https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/) (verified 2026-10-17)
+- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/content-on-hover-or-focus.html) (verified 2026-10-17)

package/skills/uiify/references/elements/virtual-scroll.md

@@ -0,0 +1,39 @@
+# virtual-scroll
+
+Binding: virtual-scroll
+
+A genuinely large list or grid needs to render only the visible range and nearby rows to keep scrolling responsive
+
+## Use when
+
+A genuinely large list or grid needs to render only the visible range and nearby rows to keep scrolling responsive.
+
+## Avoid when
+
+Do not virtualize short lists. Avoid it when users need browser find-in-page, a complete static/print view, or reliable access to all rows without JavaScript unless you provide an alternative.
+
+## Structure
+
+Use `VirtualScroll` with stable unique item ids and a renderRow function. Keep the default list role for lists; use grid only when each row supplies the correct grid structure and keyboard model. Name the scroll region and provide a useful height/size estimate.
+
+## Responsive
+
+Choose vertical or horizontal orientation deliberately, set rowHeight or estimateRowHeight to match actual content, and test at narrow widths and zoom.
+
+## States
+
+This is a Tier 2 client component. It exposes visible rows with aria-posinset/aria-setsize; rows outside the rendered window are absent from the DOM. For high-value data, provide a non-virtualized route or export.
+
+## Verify
+
+Check keyboard scrolling/focus, screen-reader item positions and total size, first/last rows, dynamic row measurement, list updates with stable ids, anchor/follow behavior if used, and no-JS/print alternatives.
+
+## Common mistake
+
+A scroll container that exposes only visible rows can make the rest of the collection unreachable to find-in-page and some assistive workflows.
+
+## Sources
+
+- [developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-posinset) (verified 2026-10-17)
+- [developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-setsize) (verified 2026-10-17)
+- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html) (verified 2026-10-17)

package/skills/uiify/references/examples/alert-confirmation.md

@@ -0,0 +1,34 @@
+# Example: alert-confirmation
+
+Element: references/elements/alert-modal.md
+
+Export: `AlertConfirmation`
+
+## Source
+
+```tsx
+import { AlertModal } from "@gunkin/uiify";
+
+export function AlertConfirmation() {
+  return (
+    <AlertModal
+      id="delete-draft"
+      title="Delete draft?"
+      description="This permanently removes the draft."
+      trigger="Delete draft"
+      cancelLabel="Keep draft"
+      actionLabel="Delete"
+    />
+  );
+}
+```
+
+## CSS
+
+```css
+[data-uiify-field] { display: grid; gap: 0.5rem; }
+[data-uiify-field] input,
+[data-uiify-select] { min-block-size: 2.75rem; padding-inline: 0.75rem; }
+table { border-collapse: collapse; inline-size: 100%; }
+th, td { padding: 0.5rem; text-align: start; }
+```

package/skills/uiify/references/examples/field-validation.md

@@ -0,0 +1,37 @@
+# Example: field-validation
+
+Element: references/elements/field.md
+
+Export: `FieldValidation`
+
+## Source
+
+```tsx
+"use client";
+
+import { useState } from "react";
+import { Field } from "@gunkin/uiify";
+
+export function FieldValidation() {
+  const [email, setEmail] = useState("");
+  const invalid = email.length > 0 && !email.includes("@");
+  return (
+    <Field.Root id="email" invalid={invalid}>
+      <Field.Label fieldId="email">Email</Field.Label>
+      <Field.Control fieldId="email" as="input" type="email" invalid={invalid} value={email} onChange={(event) => setEmail(event.currentTarget.value)} />
+      <Field.Description fieldId="email">We will send your receipt here.</Field.Description>
+      {invalid ? <Field.Error fieldId="email" invalid>Enter a valid email address.</Field.Error> : null}
+    </Field.Root>
+  );
+}
+```
+
+## CSS
+
+```css
+[data-uiify-field] { display: grid; gap: 0.5rem; }
+[data-uiify-field] input,
+[data-uiify-select] { min-block-size: 2.75rem; padding-inline: 0.75rem; }
+table { border-collapse: collapse; inline-size: 100%; }
+th, td { padding: 0.5rem; text-align: start; }
+```

package/skills/uiify/references/examples/select-basic.md

@@ -0,0 +1,35 @@
+# Example: select-basic
+
+Element: references/elements/select.md
+
+Export: `SelectBasic`
+
+## Source
+
+```tsx
+import { Select } from "@gunkin/uiify";
+
+export function SelectBasic() {
+  return (
+    <label>
+      Plan
+      <Select.Root name="plan" defaultValue="monthly">
+        <Select.Content>
+          <Select.Item value="monthly">Monthly</Select.Item>
+          <Select.Item value="annual">Annual</Select.Item>
+        </Select.Content>
+      </Select.Root>
+    </label>
+  );
+}
+```
+
+## CSS
+
+```css
+[data-uiify-field] { display: grid; gap: 0.5rem; }
+[data-uiify-field] input,
+[data-uiify-select] { min-block-size: 2.75rem; padding-inline: 0.75rem; }
+table { border-collapse: collapse; inline-size: 100%; }
+th, td { padding: 0.5rem; text-align: start; }
+```

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

@@ -0,0 +1,40 @@
+# Example: table-controls
+
+Element: references/elements/table.md
+
+Export: `TableControls`
+
+## Source
+
+```tsx
+"use client";
+
+import { useState } from "react";
+import { Table } from "@gunkin/uiify";
+
+const people = ["Ada Lovelace", "Grace Hopper", "Katherine Johnson"];
+
+export function TableControls() {
+  const [query, setQuery] = useState("");
+  const visible = people.filter((person) => person.toLowerCase().includes(query.toLowerCase()));
+  return (
+    <section>
+      <label>Filter people <input value={query} onChange={(event) => setQuery(event.currentTarget.value)} /></label>
+      <Table.Root>
+        <Table.Header><Table.Row id="header"><Table.ColumnHeader id="name-heading">Name</Table.ColumnHeader></Table.Row></Table.Header>
+        <Table.Body>{visible.map((person) => <Table.Row id={person} key={person}><Table.Cell>{person}</Table.Cell></Table.Row>)}</Table.Body>
+      </Table.Root>
+    </section>
+  );
+}
+```
+
+## CSS
+
+```css
+[data-uiify-field] { display: grid; gap: 0.5rem; }
+[data-uiify-field] input,
+[data-uiify-select] { min-block-size: 2.75rem; padding-inline: 0.75rem; }
+table { border-collapse: collapse; inline-size: 100%; }
+th, td { padding: 0.5rem; text-align: start; }
+```

package/skills/uiify/references/guides/assets.md

@@ -0,0 +1,14 @@
+# Choose image and type material
+
+Read this guide only when images or typography carry the page's composition. Start with project assets and the requested brand; do not require image generation, network access or new font downloads.
+
+| Material | Use when | Composition and responsive check |
+| --- | --- | --- |
+| Photography | A real person, place or physical subject is evidence for the message. | Preserve the subject's focal point in each crop; use a ratio that suits the section and stack or reframe at narrow widths. |
+| Product screenshot | The actual interface explains the product or task. | Keep essential UI legible and intact; do not replace a product screenshot with decorative imagery. At mobile widths, stack it or crop only if the important controls remain visible. |
+| Illustration | An abstract idea benefits from a simple visual explanation. | Keep style and color consistent with the product; avoid inventing interface details, customer logos or testimonials. |
+| Typographic composition | The words themselves are the main visual material. | Preserve supplied brand fonts and established roles. Check line breaks, long strings and fallback metrics at narrow widths; never rewrite factual copy just to fit. |
+
+When assets are missing, do not invent reviews, testimonials, customer logos or product screens. Use existing fonts first and preserve supplied brand fonts. A font fallback should remain close enough in width and weight to avoid a layout jump while the chosen font loads. Test long headings and labels; use tabular numerals when aligned values benefit from equal-width digits, not as a universal setting.
+
+Motion should explain a state change or guide attention. Keep it brief and honor `prefers-reduced-motion`; decorative movement should not compete with reading or controls.

package/skills/uiify/references/guides/content.md

@@ -0,0 +1,11 @@
+# Does the copy say what this page and each action actually do?
+
+Read the page at its default viewport and in its relevant form or overlay states. Check that:
+
+- Headings identify the subject or decision on this page, not a generic slogan. A settings page should name the setting group; a pricing page should name the offer.
+- Action labels name the result. “Save changes” tells the user more than “Submit”; verify the label still fits at 390×844.
+- An automatically detected input error identifies what happened and, when known, how to correct it. This follows [WCAG 2.2 Success Criterion 3.3.3](https://www.w3.org/WAI/WCAG22/Understanding/error-suggestion.html); do not invent a correction when the cause is unknown.
+- Example content is plausible for the page and its audience. Replace lorem ipsum and repeated placeholder values, then inspect the populated state for wrapping and density.
+- One term names one concept throughout the page. Compare navigation, headings, controls, confirmation, and errors for competing labels.
+
+Use a real task sentence and realistic values to test the copy. If the same label could describe several different outcomes, make the result explicit.

package/skills/uiify/references/guides/hierarchy.md

@@ -0,0 +1,14 @@
+# What leads the eye, and do the parts read in the right order?
+
+At 1440×900 and 390×844, inspect the initial viewport and one scrolled section. Check these visible relationships:
+
+- One item leads each screen. Squint at the screenshot or blur it; the primary heading or task should remain the first clear anchor.
+- Neighboring text roles differ by size or weight, not color alone. Compare computed font size and weight in the heading, body, label, and helper text.
+- A supplied brand font and existing type roles remain intact. Test long headings and labels at narrow widths; use tabular numerals only when aligned values need them.
+- Main text lines average 45–75 characters as a readability heuristic and do not exceed 80 characters as a ceiling. [WCAG 1.4.8](https://www.w3.org/WAI/WCAG22/Understanding/visual-presentation.html) describes 80 characters as one available text-presentation requirement; it does not make 45–75 a rule.
+- Related items sit closer together than unrelated groups. Check the grouping against the `proximity` law in the relevant page design.
+- Space above a heading exceeds the space below it; treat this as a grouping heuristic and compare computed margins.
+- Density matches the page surface in `surface.md`; a work screen can be denser than a reading page without losing clear groups.
+- Heading levels follow the visible and document order without skipped levels. Inspect the heading outline as well as the screenshot.
+
+If one relation fails, name the viewport and state, then make one correction and inspect both viewports again.

package/skills/uiify/references/guides/reference.md

@@ -0,0 +1,9 @@
+# Compare against a visual reference
+
+Use this guide only when matching a supplied screenshot or comparing an existing page. Keep the requested scope: a reference is evidence for the requested work, not permission to redesign unrelated parts.
+
+Compare the same route at the same viewport, the same state and the same scale. Note the page's grid and proportions, text roles, spacing rhythm, color roles, section order, image role and crop. Separate observed differences from assumptions; keep the notes concise and actionable.
+
+Inspect project assets before choosing replacements. Use local assets such as images and fonts when available, and preserve recognizable content and crop where the reference calls for it. Do not invent an asset, brand detail or unavailable content. A mobile adaptation inferred from a desktop screenshot is not verified until checked at a real narrow viewport.
+
+If the reference cannot be opened, continue with the accessible request and existing project. Say that visual fidelity could not be checked; do not claim to have inspected an unavailable image.

package/skills/uiify/references/guides/states.md

@@ -0,0 +1,12 @@
+# Does the page still work outside the happy path?
+
+Use the browser to create these test inputs and states, then record which you checked:
+
+- Double the content length in headings, button labels, and primary text. Add a long unbroken value such as a URL or identifier and inspect wrapping at 390×844.
+- Set `dir="rtl"` on `html`; inspect alignment, order, icons, and navigation at 1440×900 and 390×844.
+- Check a 320 CSS pixel viewport and browser zoom at 200%. Confirm content and actions remain available without unintended horizontal scrolling. [WCAG 2.2 Success Criterion 1.4.10](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html) requires reflow at a 320 CSS pixel width for vertically scrolling content, except content that needs two-dimensional layout.
+- Use only the keyboard: follow Tab order, activate with Enter or Space, dismiss overlays with Escape where supported, and confirm focus returns to the opener.
+- Exercise loading, empty, error, and disabled states where they exist. Submit an invalid form and check the message, focus location, and preservation of valid values.
+- If motion communicates a state or transition, verify its reduced-motion behavior; do not make essential information depend on animation.
+
+Record the viewport, input, and state for each check. A screenshot shows appearance only; it does not prove keyboard operation, focus return, or touch and pointer behavior.

package/skills/uiify/references/guides/surface.md

@@ -0,0 +1,27 @@
+# What kind of page is this, and how expressive should it be?
+
+Treat this classification as a heuristic about the requested page, not the product. Choose the surface that best describes the page being built; a product may contain several kinds.
+
+Follow the request's scope: a reference sets a visual target, a narrow fix stays narrow, and a new page within an existing product follows that project's design decisions. Use surface guidance for the part being created or changed; an audit reports evidence without expanding into a redesign.
+
+## Decide
+
+For a landing, pricing, or campaign page, prioritize one clear next step per screen and make the evidence supporting its claim easy to find. Avoid competing primary actions and decorative imagery that does not support the message. Typical catalog choices include `hero`, `hero-actions`, `pricing-table`, `testimonial`, `feature-grid`, and `logo-wall`.
+
+## Work
+
+For settings, dashboards, admin tools, and tables, prioritize scanning, predictable controls, and information density. Avoid turning navigation or controls into decoration. Use typography, semantic color roles, density, and one distinctive detail for character. Typical choices include `header`, `sidebar`, `table`, `form`, `field`, `tabs`, `toolbar`, and `pagination`.
+
+## Read
+
+For documentation, articles, and changelogs, prioritize a readable line length, clear heading structure, and navigation within the page. Avoid narrow columns that make code or data unusable and headings that skip levels. Typical choices include `table-of-contents`, `code-block`, `accordion`, `breadcrumb`, and `pagination`.
+
+## View
+
+For galleries and portfolios, let the work lead and keep surrounding chrome quiet. Avoid controls or labels that compete with the work, while keeping meaningful descriptions and navigation available. Typical choices include `image-gallery`, `carousel`, `card`, `badge`, and `divider`.
+
+## Review with evidence
+
+At 320 CSS pixels wide, confirm that content and functionality reflow without two-dimensional scrolling except where the content genuinely requires it. This reflects [WCAG 2.2 Success Criterion 1.4.10](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html); it does not prescribe a visual style.
+
+After inspecting a rendered page, change a detail only when you can name the visible problem, the state and viewport where it appears, and one correction. If you cannot point to all three, keep the design as it is.

package/skills/uiify/scripts/lint.mjs

@@ -44,7 +44,7 @@ async function lint() {
       }
     }
   }
-  console.log(`${count} findings (${checks.length} accepted static checks).`);
+  console.log(`${count} findings (${checks.length} accepted static checks: ${checks.map((check) => check.id).join(", ") || "none"}).`);
   process.exitCode = count > 0 ? 1 : 0;
 }
 

package/skills/uiify/scripts/static.mjs

@@ -41,6 +41,62 @@ function positiveLiteral(attribute, typescript) {
   );
 }
 
+const UIIFY_MODULE = /^@gunkin\/uiify\/(?:components|elements)(?:\/[a-z0-9-]+)?$/;
+
+function uiifyBindings(tree, typescript) {
+  const bindings = new Set();
+  for (const statement of tree.statements) {
+    if (
+      !typescript.isImportDeclaration(statement) ||
+      !typescript.isStringLiteral(statement.moduleSpecifier) ||
+      !UIIFY_MODULE.test(statement.moduleSpecifier.text)
+    ) continue;
+    const clause = statement.importClause;
+    if (!clause || clause.isTypeOnly) continue;
+    if (clause.name) bindings.add(clause.name.text);
+    const namedBindings = clause.namedBindings;
+    if (namedBindings && typescript.isNamespaceImport(namedBindings)) {
+      bindings.add(namedBindings.name.text);
+    } else if (namedBindings && typescript.isNamedImports(namedBindings)) {
+      for (const specifier of namedBindings.elements) {
+        if (!specifier.isTypeOnly) bindings.add(specifier.name.text);
+      }
+    }
+  }
+
+  const shadowable = new Set([
+    typescript.SyntaxKind.VariableDeclaration,
+    typescript.SyntaxKind.BindingElement,
+    typescript.SyntaxKind.Parameter,
+    typescript.SyntaxKind.FunctionDeclaration,
+    typescript.SyntaxKind.FunctionExpression,
+    typescript.SyntaxKind.ClassDeclaration,
+    typescript.SyntaxKind.ClassExpression,
+  ]);
+  const visit = (node) => {
+    if (shadowable.has(node.kind) && node.name && typescript.isIdentifier(node.name)) {
+      bindings.delete(node.name.text);
+    }
+    typescript.forEachChild(node, visit);
+  };
+  visit(tree);
+  return bindings;
+}
+
+function jsxTarget(tagName, bindings, typescript) {
+  if (typescript.isIdentifier(tagName)) {
+    if (/^[a-z][a-z0-9-]*$/.test(tagName.text)) return { kind: "intrinsic", tag: tagName.text };
+    if (bindings.has(tagName.text)) return { kind: "uiify", name: tagName.text };
+    return null;
+  }
+  if (!typescript.isPropertyAccessExpression(tagName)) return null;
+  let root = tagName.expression;
+  while (typescript.isPropertyAccessExpression(root)) root = root.expression;
+  return typescript.isIdentifier(root) && bindings.has(root.text)
+    ? { kind: "uiify", name: tagName.getText() }
+    : null;
+}
+
 function sourceCheck(id, law, message, violates) {
   return {
     id,
@@ -49,20 +105,19 @@ function sourceCheck(id, law, message, violates) {
     run(input) {
       const tree = parse(input);
       const { file, typescript } = input;
+      const bindings = uiifyBindings(tree, typescript);
       const findings = [];
       const visit = (node) => {
-        if (
-          (typescript.isJsxOpeningElement(node) || typescript.isJsxSelfClosingElement(node)) &&
-          typescript.isIdentifier(node.tagName) &&
-          /^[a-z][a-z0-9-]*$/.test(node.tagName.text) &&
-          violates(node.tagName.text, attributes(node, typescript), typescript)
-        ) {
-          findings.push({
-            file,
-            line: tree.getLineAndCharacterOfPosition(node.getStart(tree)).line + 1,
-            rule: id,
-            message,
-          });
+        if (typescript.isJsxOpeningElement(node) || typescript.isJsxSelfClosingElement(node)) {
+          const target = jsxTarget(node.tagName, bindings, typescript);
+          if (target && violates(target, attributes(node, typescript), typescript)) {
+            findings.push({
+              file,
+              line: tree.getLineAndCharacterOfPosition(node.getStart(tree)).line + 1,
+              rule: id,
+              message,
+            });
+          }
         }
         typescript.forEachChild(node, visit);
       };
@@ -84,12 +139,14 @@ export const staticChecks = [
     "button-type",
     "error-prevention",
     "Give the intrinsic button an explicit type.",
-    (tag, attrs) => tag === "button" && !attrs.some((attr) => attr.name.text === "type"),
+    (target, attrs) =>
+      target.kind === "intrinsic" && target.tag === "button" && !attrs.some((attr) => attr.name.text === "type"),
   ),
   sourceCheck(
     "image-alt",
     "accessibility",
     "Give the intrinsic image an alt attribute (empty for decoration).",
-    (tag, attrs) => tag === "img" && !attrs.some((attr) => attr.name.text === "alt"),
+    (target, attrs) =>
+      target.kind === "intrinsic" && target.tag === "img" && !attrs.some((attr) => attr.name.text === "alt"),
   ),
 ];