@gunkin/uiify 0.0.16-alpha → 0.0.19-alpha

package/README.md

@@ -46,11 +46,19 @@ In a monorepo with hoisted dependencies, point to the nearest `node_modules/@gun
 
 ### `/uiify` page-building skill
 
-The package also includes the `/uiify` AI skill. Use it when an agent is creating or improving a
-web page with UIify: it maps the brief to available components, plans the page in `DESIGN.md`,
-implements the page in `src/App.tsx` when that file exists, and reports the checks it could run.
-It uses the installed package's component references and follows UIify's public styling and
-accessibility contracts. Invoke it explicitly so it runs only for page-building work.
+The package also includes the `/uiify` AI skill. Invoke it explicitly when creating or improving a
+web page with UIify. It adds component and UX knowledge to your request while preserving the agent's
+normal workflow: no staged approvals, routine questions or special status output. It follows the
+requested framework route and existing workspace conventions, reads version-matched component
+references and supports custom UI for components UIify does not provide. Existing design decisions
+are reused; invoking the skill does not require creating `DESIGN.md`.
+
+The skill ships a compact index plus individually retrievable element, UX-law and composition
+references under `skills/uiify/references/`. During planning it reads recipes for the requested
+elements and relationships between them, then reads the public component docs for matched UIify
+components. It does not load the whole catalog into the prompt. The private harness catalog is the
+source for reviewed knowledge; the package contains only its curated public projection. Knowledge
+is delivered as files, so this workflow does not require an MCP server.
 
 Install the skill into the directory your agent reads:
 
@@ -64,10 +72,15 @@ mkdir -p .claude/skills/uiify
 cp -R node_modules/@gunkin/uiify/skills/uiify/. .claude/skills/uiify/
 ```
 
-Then invoke `/uiify <page brief>` in Claude Code, or use the explicit skill invocation supported by
-your agent. Add `--auto` to run all stages without confirmation gates. Interactive runs pause at
-each stage so you can stop before implementation. The skill writes its design state to `DESIGN.md`
-and page code under `src/`; it does not create a page when `src/App.tsx` is absent.
+Claude Code uses `/uiify <page brief>`; other agents use their documented explicit skill invocation.
+No special execution flag is needed. The repository's manual smoke harness exercises Claude Code
+only; activation syntax and token measurements do not establish behavior for other clients.
+
+For verification, the skill reuses project tooling. If missing Playwright or axe-core tooling or
+browser binaries are needed, the agent briefly explains what it will install and why before
+installation. This is a notice, not a routine confirmation question. Installation follows project
+rules, uses development dependencies and includes only what is needed. Unavailable checks are
+reported as not run.
 
 ### Keeping the skill current when developing UIify
 
@@ -77,6 +90,18 @@ usage changes, and update the harness catalog when its coverage or gap status ch
 skill, then checks their tests and freshness. Review and commit generated changes with the component
 change. `npm run check:ai-harness` runs the focused tests and freshness checks without rewriting files.
 
+For new design knowledge, inspect the component API and examples; record sourced evidence in the
+private catalog; write a concise `release_body`; review the public projection for privacy and
+usefulness; regenerate the skill; and run package-link and hygiene tests. Private evidence and owner
+rationale stay in the harness source; changing private notes alone does not change what consumers
+receive.
+
+The optional paid eval runner records each agent and judge call separately. An unknown cost reserves
+that call's configured cap and blocks later paid calls. `results.json` is atomically checkpointed
+before and after calls and throughout page verification; an existing non-empty output directory is
+not reused. This protects recorded progress but does not measure whether one skill produces better
+designs than another.
+
 Documentation: https://uiify.gunkin.dev/
 
 MIT © Anton Gunkin

package/package.json

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

package/skills/uiify/SKILL.md

@@ -8,160 +8,160 @@ disable-model-invocation: true
 
 # /uiify
 
-Brief and flags: $ARGUMENTS
+Page request: $ARGUMENTS
 
-This skill writes only DESIGN.md and files under src/.
+Add UIify component and UX knowledge to the user's request. Follow the agent's normal workflow and the project's instructions; this skill is a reference, not a separate interaction protocol. Do not add approval gates, fixed stages, routine questions or pauses. Use ordinary language in the user's language for useful progress and results, without internal stage names or machine-readable status markers. Proceed with authorized work autonomously; handle genuine missing requirements through the agent's normal workflow.
 
-## Stage chain
+## Project context
 
-Run the stages R0 to R4 in order and never skip or reorder one. Each stage has a marker line, a result and, except R4, a gate line after it. Every marker, state and gate line is exact and alone on its own line. The first gate, for example, is `UIIFY:GATE R0>R1 auto`. How you output them depends on the flags above.
+Use the explicit request in the conversation if the client does not substitute `$ARGUMENTS`. Read repository instructions, the relevant package manifest and framework config, and a route example as needed. Resolve `@gunkin/uiify` from the selected workspace, including hoisted dependencies in parent workspaces. Follow the requested framework's route conventions and RSC/client boundaries. Create the requested route rather than replacing the home page; `src/App.tsx` is a destination only when it matches the request.
 
-**Interactive (no `--auto`).** Follow this protocol for every stage:
+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.
 
-1. Output the stage marker as plain text before you call any tool for that stage.
-2. Do the stage's work; tools are allowed.
-3. Output the stage's result.
-4. Run the gate: ask once with AskUserQuestion ("Continue to the next stage?" with the options Continue and Stop). On Continue print `UIIFY:GATE <from>><to> asked` and go on. On Stop print `UIIFY:STOPPED` and end the run.
+## Choose an approach before composition
 
-Do not call any tool for a later stage until the current stage's gate line is output. A stage whose marker was not output did not happen.
+Use the request to choose an internal approach; do not ask the user to choose a mode:
 
-**Auto (`--auto`).** Ask nothing. Do all tool work first without commentary: read the project (R0) and create `DESIGN.md` when R2 says to. Then output the whole chain in one final message, in stage order: each stage's marker and result, with `UIIFY:GATE <from>><to> auto` between stages, ending as R4 says. Output nothing else before that message.
+- 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.
 
-### R0 activate
+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.
 
-Marker `UIIFY:R0 activate`. Work: read the project. Does `package.json` list `@gunkin/uiify` under `dependencies` or `devDependencies`, and does `DESIGN.md` exist at the project root? Result: `UIIFY:STATE uiify=<yes|no> design=<found|missing>`.
+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.
 
-### R1 coverage
+## Select knowledge for the page
 
-Marker `UIIFY:R1 coverage`. Work: split the brief into the page elements it needs and match each one to the index below by name or alias. Result: one line per element, `UIIFY:ELEMENT <name>|<binding>`. For an element the index lists, use its index name and its uiify column as the binding (a uiify component name or `gap`). For an element the index does not list, use a kebab-case name and the binding `unknown`.
+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.
 
-### R2 design
+For each selected element with a fourth-column reference path, read that file once. A blank path means no curated recipe is available. From the Composition index, read only relationships where both elements are needed on the page. Read each selected reference and linked law once, including the related laws named by element recipes. Do not load the complete catalog or unrelated component references.
 
-Marker `UIIFY:R2 design`. Work:
+For mapped components, read the resolved package's `agents/index.md` once and the relevant `agents/reference/components/<name>.md`, then adapt a documented example. Import from `@gunkin/uiify/components/<name>`. Inspect Runtime exports and the Types/declaration file before rendering: use the explicit `NameRoot` export when available. A namespace export is not itself a JSX component; use its `.Root` or an explicit root export. Prefer these version-matched references over memory. Use UIify wherever its documented API covers the interaction; for gaps, use semantic native HTML or custom components following UIify's public styling and accessibility contracts.
 
-1. Read `DESIGN.md` and reuse its recorded decisions. If missing, create exactly the skeleton below. Preserve the YAML `tokens` and every byte outside the managed block. If its structure or existing managed block is malformed, report the problem and leave it unchanged.
-2. Use the R1 bindings as the coverage map. The skill package intentionally contains no private element, law or composition catalog files; do not search for `references/elements/`, `references/laws/` or `references/compositions/` under the skill directory. R3 reads UIify's public component documentation when implementing mapped elements.
-3. Consult the `frontend-design` skill when it is available for design direction. Use `web-design-guidelines` only when the task asks for a review, and consult `vercel-react-best-practices` only for a relevant performance decision. These optional skills are references, not dependencies; if absent, use the built-in guidance below. UIify's public component and styling contracts take precedence over any conflicting advice.
-4. Ground the page in its actual subject, audience and primary job. Choose a visual direction that follows the brief and is specific to that subject. Plan a clear typography hierarchy, palette using the project's existing semantic roles, responsive layout, purposeful copy and one memorable signature detail. Use restraint around that signature; don't default to a gradient hero, repeated equal cards or decorative numbering without a reason. Preserve visible focus, keyboard-sized targets and reduced-motion behavior.
-5. Example: for a settings page, group fields by the decision the person is making, keep labels and validation close to each control, and give one `Button` the save action. Use the package's documented anatomy:
+## Design guidance
 
-   ```tsx
-   <Field.Root id="email" invalid={invalid} required>
-     <Field.Label fieldId="email" required>Email</Field.Label>
-     <Field.Control as="input" fieldId="email" type="email" invalid={invalid} required />
-     <Field.Error fieldId="email" invalid={invalid}>Enter a valid email address</Field.Error>
-   </Field.Root>
-   <Button type="submit">Save changes</Button>
-   ```
+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.
 
-   Don't add an unrelated marketing hero or make every field group an equally prominent card.
-6. Keep existing decisions and plan the page's element order, hierarchy, grouping, actions and visual direction as a decision with id `page-plan`, a concrete `decision`, `why` and `references`. Reuse an existing plan unless the brief requires an explicit revision; retain other decisions. Research only unresolved gaps or open decisions in a subagent, if both delegation and primary-source retrieval tools are available. Request a short summary with dated primary-source links. If those tools are unavailable, report unresolved gaps and keep them `proposed`. Record dates alongside the source URLs in `sources`. Only explicit owner approval can make a gap `accepted`; `--auto` never grants approval. Follow owner prose and report conflicts with the brief; interactive mode can clarify at the normal gate, while `--auto` preserves recorded choices.
-7. Store state only in one JSON block beneath `## Decisions`, delimited by an opening `<!-- uiify:state -->` line and a closing `<!-- /uiify:state -->` line. Its exact shape is `{ "version": 1, "elements": ["R1-name"], "decisions": [{ "id": "page-plan", "decision": "concrete page plan and visual direction", "why": "reason", "references": ["public UIify docs or dated source URLs"] }], "gaps": [{ "element": "gap-name", "status": "proposed", "sources": [] }] }`. Empty lists are allowed; IDs and elements are unique; strings are nonempty. Do not put prose or fences inside the JSON block. Reject duplicate, unclosed, misplaced or invalid blocks. Insert the block immediately after the Decisions heading's newline, without changing surrounding bytes; replace only an existing block and its following newline. If state is unchanged, leave the whole file byte-identical. Keep existing gap acceptance and sources; do not infer approval from research.
+After the page renders, review it with a guide only when its question applies:
 
-Result: summarize the stored page plan, reused decisions and unresolved gaps, including research limitations.
+- `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?
 
-```markdown
----
-tokens: {}
----
-
-# Design
+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.
 
-## Decisions
+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:
 
-## Gaps
+```tsx
+<Field.Root id="email" invalid={invalid} required>
+  <Field.Label fieldId="email" required>Email</Field.Label>
+  <Field.Control as="input" fieldId="email" type="email" invalid={invalid} required />
+  <Field.Error fieldId="email" invalid={invalid}>Enter a valid email address</Field.Error>
+</Field.Root>
+<Button type="submit">Save changes</Button>
 ```
 
-### R3 build
+Do not add an unrelated marketing hero or make every field group an equally prominent card. For unresolved gaps, explain material limitations in plain language; research only when it helps the request. Research does not grant approval to change the library's public API or mark a catalog gap accepted.
 
-Marker `UIIFY:R3 build`. Work: if `src/App.tsx` exists, write the page into it (new components go under `src/`), following the R1 table and the stored `page-plan` in `DESIGN.md`. Read `node_modules/@gunkin/uiify/agents/index.md` once and adapt a relevant documented example when it matches the page; for each mapped component, read `node_modules/@gunkin/uiify/agents/reference/components/<name>.md`, then import it from `@gunkin/uiify/components/<name>`. Before rendering an export, inspect its Runtime exports and the Types/declaration file for component shape; use the explicit `NameRoot` export when available. A namespace export is not itself a JSX component; use its `.Root` or the explicit root export. For a `gap` or `unknown` element, use semantic native HTML and UIify's public styling contract, and consult public design-system or platform guidance for unresolved behavior when retrieval is available. Write no file outside `src/` and leave `DESIGN.md` as it is. If `src/App.tsx` does not exist, write nothing. Result: one sentence naming what you wrote and where, or where the page would go.
+## Verification guidance
 
-### R4 verify
+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.
 
-Marker `UIIFY:R4 verify`. Work: when commands are permitted and an execution tool is available, run `node <this-skill-directory>/scripts/lint.mjs <project-root>` and report its actual output. The script runs only the static subset enabled by accepted laws; no enabled checks is not proof of accessibility. Missing TypeScript/parser or another execution failure is unavailable, never a pass. If the consuming task prohibits commands, report "lint not run" with that reason; if no execution tool is available, report that limitation. When a browser tool is available and permitted, inspect the page and requested interactions without creating screenshot artifacts; otherwise report that browser verification was not run. Repair findings only under `src/` in at most two rounds, rerunning available checks after each. Do not edit DESIGN.md during repairs. Result: report executed checks, unavailable checks with reasons, repairs and remaining issues; never claim a check passed without running it. Then print `UIIFY:DONE` and stop.
+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.
 
-## Hard rules
-
-- Prefer published UIify component documentation over memory when implementing a mapped element.
-- Use a uiify component whenever the index names one for the element.
-- Ground visual choices in the brief and subject; don't impose one preferred palette or page template.
-- Apply optional frontend skills only when available and relevant; UIify's public contracts override generic advice.
-- Match elements only against the index: never invent a binding and never use an alias as the element name.
-- Run every stage in this conversation and never use context: fork.
-- Write only `DESIGN.md` and files under `src/`; R2 changes only its managed state block, R4 repairs only `src/` in at most two rounds.
+Repair findings within the task's scope and rerun the affected checks. If commands, installation or browser execution are unavailable or prohibited, report those checks as not run and explain the limitation. Report actual checks and remaining issues in ordinary language; never claim a check passed without running it.
 
 ## Index
 
-One line per element: `element|aliases|uiify component or gap|` (the final field is reserved and empty).
+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|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|references/elements/breadcrumb.md
+button|cta-button,icon-button,primary-button|button|references/elements/button.md
+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|references/elements/carousel.md
+checkbox||checkbox|references/elements/checkbox.md
+code-block|code-snippet|gap|references/elements/code-block.md
+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|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|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|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|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|references/elements/line-chart.md
+logo-wall|logo-cloud,customer-logos|gap|references/elements/logo-wall.md
+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|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|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|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|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|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|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
+
+One line per accepted relationship: `name|element,element|reference path`.
 
 ```text
-accordion|faq-accordion,disclosure|accordion|
-alert-modal|confirmation-dialog,alert-dialog|alert-modal|
-avatar|profile-picture|gap|
-badge|chip,tag|gap|
-bar-chart|column-chart|gap|
-breadcrumb|breadcrumbs|breadcrumb|
-button|cta-button,icon-button,primary-button|button|
-candle-chart|candlestick-chart|candle-chart|
-card|content-card|gap|
-carousel|testimonial-carousel,image-slider|carousel|
-checkbox||checkbox|
-code-block|code-snippet|gap|
-collapsible|expandable-section|collapsible|
-color-picker||color-picker|
-combobox|autocomplete,typeahead|combobox|
-command-palette|spotlight-search|gap|
-context-menu|right-click-menu|context-menu|
-cookie-banner|cookie-consent|gap|
-date-picker|calendar-picker|gap|
-divider|separator|gap|
-drawer|sheet,off-canvas-menu|drawer|
-dropdown-menu|menu|dropdown-menu|
-empty-state|no-results|gap|
-feature-grid|feature-cards,feature-list|gap|
-field|form-field|field|
-file-upload|file-input,dropzone|file-upload|
-footer|site-footer|gap|
-form||form|
-header|navbar,top-nav|header|
-hero|hero-section,hero-banner|gap|
-hover-card||hover-card|
-image-gallery|gallery,lightbox|gap|
-inline-alert|banner-alert,callout|gap|
-input|text-input|input|
-line-chart|sparkline|line-chart|
-logo-wall|logo-cloud,customer-logos|gap|
-modal|dialog|modal|
-number-field|number-input|number-field|
-otp-input|pin-input|otp-input|
-pagination||pagination|
-password-input|show-hide-password|gap|
-popup|popover|popup|
-pricing-table|pricing,plan-cards,pricing-plans|gap|
-progress-bar|progress,linear-progress|gap|
-radio-group|radio|radio-group|
-rating|star-rating|rating|
-search-input|search-box|gap|
-segmented-control||segmented-control|
-select|native-select|select|
-sidebar|sidebar-nav,side-nav|gap|
-skeleton|skeleton-loader|skeleton|
-slider|range-slider|slider|
-spinner|loading-indicator|spinner|
-stats-bar|stat-card,metrics|gap|
-stepper|step-indicator,wizard-steps|gap|
-switch|toggle-switch|switch|
-table|data-table,comparison-table|table|
-table-of-contents|toc,in-page-nav|table-of-contents|
-tabs|tab-navigation|tabs|
-tags-input|token-input|tags-input|
-testimonial|testimonials,quote-card|gap|
-textarea||textarea|
-timeline||gap|
-toast|snackbar,toast-notification|toast|
-toggle|toggle-button|toggle|
-toggle-group|button-group|toggle-group|
-toolbar||toolbar|
-tooltip||tooltip|
-virtual-scroll|virtualized-list|virtual-scroll|
+card-rhythm|feature-grid,card|references/compositions/card-rhythm.md
+destructive-confirmation|alert-modal,button|references/compositions/destructive-confirmation.md
+form-grouping|form,field|references/compositions/form-grouping.md
+hero-actions|hero,button|references/compositions/hero-actions.md
+page-frame|header,footer|references/compositions/page-frame.md
+pricing-actions|pricing-table,button|references/compositions/pricing-actions.md
+save-feedback|button,toast|references/compositions/save-feedback.md
+table-controls|table,pagination|references/compositions/table-controls.md
 ```

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

@@ -0,0 +1,14 @@
+# card-rhythm
+
+Use when both feature-grid and card are present.
+
+Law: references/laws/proximity.md
+
+## 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
+
+- [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/visual-presentation.html) (verified 2026-10-16)

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

@@ -0,0 +1,15 @@
+# destructive-confirmation
+
+Use when both alert-modal and button are present.
+
+Law: references/laws/error-prevention.md
+
+## Rule
+
+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
+
+- [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)

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

@@ -0,0 +1,14 @@
+# form-grouping
+
+Use when both form and field are present.
+
+Law: references/laws/proximity.md
+
+## Rule
+
+Group related controls with a fieldset and legend. Keep each control labelled and present groups in the order people complete them.
+
+## Sources
+
+- [www.w3.org](https://www.w3.org/WAI/tutorials/forms/grouping/) (verified 2026-10-16)
+- [www.w3.org](https://www.w3.org/WAI/tutorials/forms/labels/) (verified 2026-10-16)

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

@@ -0,0 +1,14 @@
+# hero-actions
+
+Use when both hero and button are present.
+
+Law: references/laws/von-restorff.md
+
+## Rule
+
+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-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

@@ -0,0 +1,14 @@
+# page-frame
+
+Use when both header and footer are present.
+
+Law: references/laws/readability.md
+
+## 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
+
+- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/consistent-navigation.html) (verified 2026-10-16)
+- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (verified 2026-10-16)

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

@@ -0,0 +1,13 @@
+# pricing-actions
+
+Use when both pricing-table and button are present.
+
+Law: references/laws/proximity.md
+
+## 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
+
+- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (verified 2026-10-16)

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

@@ -0,0 +1,13 @@
+# save-feedback
+
+Use when both button and toast are present.
+
+Law: references/laws/feedback.md
+
+## Rule
+
+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
+
+- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html) (verified 2026-10-16)

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

@@ -0,0 +1,14 @@
+# table-controls
+
+Use when both table and pagination are present.
+
+Law: references/laws/proximity.md
+
+## Rule
+
+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
+
+- [www.w3.org](https://www.w3.org/WAI/tutorials/forms/labels/) (verified 2026-10-16)
+- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (verified 2026-10-16)

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

@@ -0,0 +1,42 @@
+# alert-modal
+
+Binding: alert-modal
+
+A short, important message requires an immediate response, especially confirmation before a consequential action
+
+## 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-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)