@gunkin/uiify 0.0.26-alpha → 0.0.27-alpha

package/skills/uiify/SKILL.md

@@ -30,23 +30,27 @@ Keep + UI: existing routes/theme; Field email, Select frequency, Checkbox market
 Flow + proof: invalid → inline error; valid → demo confirmation + retained values; keyboard, narrow layout.
 ```
 
-Adapt or reuse the brief in the user's language; no parser, required file or output. Keep exact API names; expand ambiguity before coding.
+Adapt the brief to the user's language. Keep exact API names; expand ambiguity before coding.
 
 Use this precedence: explicit brief or reference → existing project → selected recipes → aesthetic guidance.
 
 When images or typography shape the composition, read `references/guides/assets.md` before choosing material.
 
-## Select knowledge for the page
+## Write the page as a UI document
 
-`references/` paths are relative to this skill directory; `agents/` paths are relative to the resolved package root. Read each distinct file once, reusing it across selected elements.
+`references/` paths are relative to this skill directory; `dist/` and `agents/` paths to the package root. Read each distinct file once.
 
-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 composed from available UIify controls or semantic native HTML, not a guessed UIify API.
+1. Match the needed elements to the Index by name or alias; never invent a binding. A `gap` or an unlisted element needs the catalog's native elements (`p`, `ul`, `a`, `label`, headings…) or other available parts. For each selected element with a reference path, read that file once and carry its structure and ids over to nodes; its JSX is a recipe, not code to paste. From the Composition index, read only relationships where both elements are needed. Follow linked laws.
+2. Next, read the part types and TSDoc in the package's `dist/ai/catalog.generated.d.ts`, but only `UiType` and the selected parts' `<Name>Props`, not the whole file. Use nothing it lacks.
+3. Next, write the page as a UI document with `satisfies UiNodeInput`: nodes are `{ type, props, children }`; children are nodes or strings. Values and `.map` over data are plain TypeScript; annotate callbacks `(row): UiNodeInput => …`. Import types from `@gunkin/uiify/ai`.
+4. Then render it with `UiDocument` from `@gunkin/uiify/ai`: `<Suspense><UiDocument node={page} /></Suspense>`.
+5. Last, run the project's typecheck, then validate and check the rendered HTML (Verification guidance).
 
-For each selected element with a fourth-column reference path, read that file once. A blank path means no curated recipe. Read and adapt its linked example for part wiring. From the Composition index, read only relationships where both elements are needed. Follow each selected reference and linked law, including laws named by element recipes. Do not load unrelated references or the complete catalog.
+Label a control with a native `{ type: "label", props: { htmlFor } }` node and the control's `id`. No component part takes `as`; `Field.Label` labels only `Field.Control` (a `div`); inputs and selects need a native label. Interactivity is native only: `href`, form `method`/`action`, invoker `commandfor`/`command` (for example `ModalTrigger`); `popoverTarget` is not available on parts.
 
-For mapped components, read the package's `agents/index.md` and `agents/reference/components/<name>.md`. Related knowledge links locate selected packaged recipes/examples. Check Runtime exports: use the explicit `NameRoot` export when available. A namespace export is not itself a JSX component; use its `.Root` or an explicit root export. Import from `@gunkin/uiify/components/<name>`. If the reference leaves an export, required prop or part wiring ambiguous, inspect its listed Types/declaration file and runtime exports. Prefer version-matched references over memory.
+Not available to documents yet: Tier 2 components and the parts, with reasons, in `uiUnavailableParts` in `dist/ai/catalog.generated.d.ts` (Tabs, charts, Toast, Breadcrumb.Ellipsis…). When a page needs one, write ordinary JSX for that piece outside the document, imported from `@gunkin/uiify/components/<name>` (see `agents/components.md`), and say so.
 
-Reuse documented UIify components, including controls inside custom gaps. Check `agents/components.md` for controls absent from recipes. Do not replace an available Button, Input, Checkbox or AlertModal with a raw-tag lookalike. Keep native HTML when no component fits, the page demonstrates native semantics, or layer rules prohibit the import; preserve semantic structures such as `fieldset`, `dl` and forms.
+Use a part, not a raw-tag lookalike of `Button`, `Input`, `Checkbox` or `AlertModal`. Keep native elements when no part fits or the page demonstrates native semantics; keep `fieldset`, `dl` and forms.
 
 ## Design guidance
 
@@ -64,7 +68,7 @@ After the page renders, review it with a guide only when its question applies:
 
 Ground visual direction in the subject, audience and primary job. Use clear typography, hierarchy, grouping, purposeful copy, responsive layout and existing semantic color roles. Choose one signature detail; keep the rest restrained. Avoid automatic gradient heroes, equal cards or decorative numbering. Preserve visible focus, keyboard-sized targets and reduced-motion behavior.
 
-For a settings page, group fields by decision and give one `Button` the save action. Adapt the Field example in `agents/index.md`: Root gets `id`, Label/Control/Description/Error get the same `fieldId`. Pass `invalid`/`required` to both Root and Control. `Field.Control as="input"` supplies UIify Input and its ID. Keep Field's ID/ARIA wiring and Description mounted when showing Error. Wrap standalone `Select.Root` in a native `<label>`; Field.Label wires only Field.Control.
+For a settings page, group fields by decision and give one `Button` the save action.
 
 Wire each requested action through its outcome: a dialog closing is not a mutation. Keep cancel/error paths safe; if an action removes its opener, focus a surviving target, including the empty state. Describe in-memory demos as demos; claim persistence only when implemented.
 
@@ -72,9 +76,9 @@ Do not add an unrelated marketing hero or make every field group an equally prom
 
 ## Verification guidance
 
-Finish the edits before running applicable project build, typecheck and test commands. Run relevant verification once against the stable result. On failure, fix related findings together, diagnose with focused checks, then rerun the required final gate. For the optional static lint and its limits, read `references/guides/verification.md`.
+Finish the edits first, then verify the stable result once: the project's typecheck (`tsc`), `validateDocument` on the document, then html-validate and axe-core on its rendered HTML, using the project's tooling. On failure, fix related findings together, diagnose with focused checks, then rerun the required gate. For these steps and the optional static lint and its limits, read `references/guides/verification.md`.
 
-Reuse existing browser and accessibility tooling for responsive layouts, keyboard access and requested interactions. Before installing missing Playwright or axe-core tooling or browser binaries, notify the user what is needed and why. This is a notification, not a confirmation question; follow project rules, its package manager and development dependencies. Use Playwright for browser checks and axe-core for accessibility.
+Reuse existing browser and accessibility tooling for responsive layouts, keyboard access and requested interactions. Before installing missing Playwright or axe-core tooling, html-validate or browser binaries, notify the user what is needed and why. This is a notification, not a confirmation question; follow project rules, its package manager and development dependencies. Use Playwright for browser checks.
 
 Repair findings within scope and rerun affected checks. Report unavailable or prohibited checks as not run, with the reason; never claim a check passed without running it.
 

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

@@ -1,9 +1,20 @@
-# Optional static lint
+# Verify a UI document
+
+Run in this order, with the project's own tooling, after the document and its route are written. Fix findings, then rerun from the failing step.
+
+1. **`tsc`** (the project's typecheck script): `satisfies UiNodeInput` reports an unknown part, prop or value at the offending node. Run it before the other checks, which assume a typed document.
+2. **`validateDocument`**: call it from `@gunkin/uiify/ai` on the document object, in a test or one-off script the project can run (for example vitest or `tsx`). It must return `ok: true`; otherwise each issue has a breadcrumb such as `form › Field.Root › Button.props.variant` and the allowed values. It also enforces rules `tsc` cannot: a part sits inside its root, a `fieldId` names the enclosing root's `id`, ids are unique, nesting stays as the HTML parser keeps it (no block or component inside `p`, headings, `a` or `label`; no form inside a form; only items in lists), and depth, node count and string length stay within limits. It does not check `htmlFor`: a dangling `htmlFor` or a missing label is caught by html-validate and axe-core.
+3. **html-validate** on the rendered HTML: render the route or document to a string (for example `renderToReadableStream` from `react-dom/server`, inside `Suspense`), place it in a page with `lang`, `title` and `main`, and run html-validate with the project's configuration.
+4. **axe-core** on the same HTML, in jsdom or a Playwright page. Disable `color-contrast` in jsdom, which has no layout; check contrast in a real browser.
+
+A passing run proves valid markup and no detectable axe violations, not good design: review the page with the design guides, and test keyboard use and responsive layout in a browser. Report any check you could not run, and why.
+
+## Optional static lint
 
 Run `node <resolved-skill-directory>/scripts/lint.mjs <project-root>` when the project's existing checks do not cover the relevant JSX attributes. Resolve the script from this skill directory, not the project root.
 
 It 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 and computed attribute values are not analyzed.
+It does not analyze UI documents, which are object literals; 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 and computed attribute values are not analyzed.
 
 No findings is not proof of accessibility. Missing parsers or execution failures mean unavailable, never a pass. Reuse project build, typecheck and tests, browser interaction checks, and axe coverage for the requested page; this lint does not replace them.