@gunkin/uiify 0.0.20-alpha → 0.0.22-alpha

package/skills/uiify/SKILL.md

@@ -10,38 +10,47 @@ disable-model-invocation: true
 
 Page request: $ARGUMENTS
 
-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.
+Add UIify knowledge using the agent's normal workflow and project instructions. Do not add approval gates, fixed stages, routine questions or pauses. Work autonomously. Use ordinary language in the user's language, without internal stage names or machine-readable status markers.
 
 ## Project context
 
-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.
+If `$ARGUMENTS` is not substituted, use the explicit conversation request. Inspect repository instructions and relevant manifest, framework config and route examples. Resolve `@gunkin/uiify` from the selected workspace, including hoisted dependencies. Follow the framework's route conventions and RSC/client boundaries; `src/App.tsx` is a destination only when requested. Preserve the home page when creating another route.
 
-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.
+Reuse existing design decisions, tokens and conventions, including `DESIGN.md` when present. Do not create `DESIGN.md` or managed state merely for this skill. Setup, dependencies and planning files follow project rules and the request. Preserve unrelated files, routes and content.
 
 ## Choose an approach before composition
 
-Use the request to choose an internal approach; do not ask the user to choose a mode:
+Choose internally: reproduce a supplied reference; extend the existing UI for scoped work; create/redesign for a new direction; audit for findings only. For a reference, read its guide before composition and compare again after rendering.
 
-- 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.
+For a compact plan or handoff, use a UI brief:
 
-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.
+```text
+Place + job: /settings/profile — edit delivery preferences.
+Keep + UI: existing routes/theme; Field email, Select frequency, Checkbox marketing, Button save.
+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.
+
+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. Skip it for routine UI changes where imagery and type are not part of the design decision.
+When images or typography shape the composition, read `references/guides/assets.md` before choosing material.
 
 ## 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.
+`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.
 
-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.
+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.
 
-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.
+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.
+
+For mapped components, read the package's `agents/index.md` and relevant `agents/reference/components/<name>.md`, then adapt a documented example. Check its Runtime exports 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. Import from `@gunkin/uiify/components/<name>`. If the reference leaves an export, required prop or part relationship ambiguous, inspect its listed Types/declaration file and runtime exports before using it. Prefer these version-matched references over memory.
+
+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.
 
 ## Design guidance
 
-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.
+Consult `frontend-design` for visual direction; if absent, use the built-in guidance below. Optional: `vercel-react-best-practices` for React performance, `web-design-guidelines` for reviews. 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:
 
@@ -53,30 +62,21 @@ After the page renders, review it with a guide only when its question applies:
 - `references/guides/states.md` — does the page still work outside the happy path?
 - `references/guides/i18n.md` — only when the page is localized, the project has an i18n setup, or the request mentions languages, RTL or CJK.
 
-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.
+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 the decision the person makes, keep labels and validation close to controls, and give one `Button` the save action. Use documented anatomy:
+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.
 
-```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>
-```
+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.
 
 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.
 
 ## Verification guidance
 
-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.
+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`.
 
-For localized pages, also render once with `dir="rtl"` and once with a long-text locale.
+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.
 
-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.
+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.
 
 ## Index
 
@@ -85,13 +85,14 @@ One line per element: `element|aliases|uiify component or gap|reference path`. A
 ```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
+aspect-ratio|media-frame,responsive-embed|aspect-ratio|references/elements/aspect-ratio.md
+avatar|profile-picture|avatar|references/elements/avatar.md
+badge|chip,tag|badge|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
+card|content-card|card|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
@@ -101,22 +102,27 @@ 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
+date-picker|native-date-field,calendar-picker|date-picker|references/elements/date-picker.md
+description-list|definition-list,key-value-list|description-list|references/elements/description-list.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
+empty-state|empty-state|empty|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
+fieldset|fieldset-legend|fieldset|references/elements/fieldset.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
+form-error-summary|error-summary|form-error-summary|references/elements/form-error-summary.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
+inline-alert|banner-alert,callout|alert|references/elements/inline-alert.md
 input|text-input|input|references/elements/input.md
+input-group|input-prefix-suffix|input-group|references/elements/input-group.md
+item|list-item|item|references/elements/item.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
@@ -126,7 +132,7 @@ 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
+progress-bar|progress,linear-progress|progress|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

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

@@ -6,7 +6,7 @@ A short, important message requires an immediate response, especially confirmati
 
 ## 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.
+Confirm a consequential action. Use a regular modal for a task or optional information, inline validation for recoverable form errors.
 
 ## Avoid when
 
@@ -14,19 +14,19 @@ Do not use alert dialogs for routine notices or long, structured content. Do not
 
 ## 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.
+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. When composing parts, give the title and description unique IDs and put matching `aria-labelledby` and `aria-describedby` on `AlertModalContent`; the parts do not infer them.
 
 ## 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.
+Keep the message concise and wrapping at narrow widths and zoom. Explain consequences in text.
 
 ## 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.
+Tier 0 uses a native [dialog role=alertdialog] opened by invokers. Cancel and Action request close; the convenience shell does not perform an application action. For mutations, compose `AlertModalTrigger`, `AlertModalContent`, `AlertModalCancel`, `AlertModalAction` from `@gunkin/uiify/components/alert-modal`: Content's `id` matches each button's `target`. Connect Action's native `onClick` to the effect in your application's client boundary. There is no `alert-modal/client` entry. `onClose` alone does not mean confirmation: Cancel and Escape also close. Keep those paths free of mutations.
 
 ## 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.
+Check name/description, keyboard opening/closing, containment, return and 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. Cancel/Escape retain native opener focus. Only when confirmation removes that opener, focus the next/previous row or an empty-state heading with `tabIndex={-1}`. An unconditional `onClose` focus override also runs after Cancel/Escape and breaks their return.
 
 ## Common mistake
 

package/skills/uiify/references/elements/aspect-ratio.md

@@ -0,0 +1,59 @@
+# aspect-ratio
+
+Binding: aspect-ratio
+
+Frame media at a preferred proportion as available inline size changes.
+
+## Use when
+
+Media needs a stable shape as available inline size changes.
+
+## Avoid when
+
+Text or controls must determine height. Keep captions outside the frame; preserve meaningful image detail.
+
+## Structure
+
+```tsx
+import { AspectRatio } from "@gunkin/uiify";
+import "@gunkin/uiify/components/behavior.css";
+
+<AspectRatio ratio={16 / 9} className="media-frame">
+  <img src="/landscape.jpg" alt="Mountain lake" width={1600} height={900} />
+</AspectRatio>
+```
+
+Direct import: `@gunkin/uiify/components/aspect-ratio`. This reusable layout Component is Tier 0. It renders two wrappers: root `data-uiify-aspect-ratio`, then `data-part="content"` around children. Root forwards native props, events, `className`, `style`, `ref`, `as` and `render`; custom renderers must forward props/ref. Owned markers cannot be overridden.
+
+`ratio?: number` accepts a positive finite number (width/height). Square default: `1`; invalid numbers fall back to `1`. Omission leaves the stylesheet default and permits a CSS `--uiify-aspect-ratio` override; an explicit ratio writes that property.
+
+## Responsive
+
+Let the parent constrain width. Required behavior CSS uses native `aspect-ratio` and absolute content to isolate intrinsic child sizing. Media fit and visuals are optional consumer CSS:
+
+```css
+.media-frame [data-part="content"] > img {
+  inline-size: 100%;
+  block-size: 100%;
+  object-fit: cover;
+}
+```
+
+Use `contain` to retain the whole image. The component imposes no fitting or clipping on arbitrary children.
+
+## States
+
+Static sizing has no loading, playback, focus or hydration state and needs no client JavaScript.
+
+## Verify
+
+Check square, 16:9 and 4:5 frames with scripts disabled at narrow/wide widths, oversized intrinsic media, cover/contain crops, RTL and CJK captions at 200% text size. Check embeds' keyboard behavior separately.
+
+## Common mistake
+
+Definite width and height defeat preferred-ratio sizing. Avoid JS measurement, padding emulation, or meaningful text inside the media area.
+
+## Sources
+
+- [www.radix-ui.com](https://www.radix-ui.com/primitives/docs/components/aspect-ratio) (verified 2026-10-19)
+- [developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/aspect-ratio) (verified 2026-10-19)

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

@@ -1,47 +1,38 @@
 # avatar
 
-Binding: gap
+Binding: avatar
 
 Identify a person or account with a compact image and fallback.
 
 ## Use when
 
-A person's identity helps distinguish nearby content, such as a participant list or comment author.
+A compact portrait or initials help distinguish a person near comments, participants, or account details.
 
 ## 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.
+Do not rely on the avatar as the only visible way to identify a person. Skip it when it adds no information.
 
 ## 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.
+`Avatar` requires `name` and `fallback`; the root is named as an image. Without `src`, it displays the fallback. With `src`, it renders an empty-alt image. Set `aria-hidden="true"` when adjacent visible text already names the person.
 
 ## Responsive
 
-Set intrinsic dimensions to reserve space, preserve a consistent crop, and avoid shrinking the image below its useful size.
+Choose `size` (`sm`, `md`, or `lg`) for a consistent compact footprint. Keep the person's visible name available in reading order where the surrounding composition needs it.
 
 ## States
 
-Provide a stable initials or generic fallback when no usable image exists. If the image fails, keep the person's visible name.
+The fallback is chosen when `src` is absent at render time. A later image-load failure does not replace it automatically.
 
 ## Verify
 
-Check image alternative against nearby text, loading/failure fallback, intrinsic dimensions, and list reading order.
+Unit and public-page tests check the accessible image name, fallback and empty-alt image markup, size attributes, and the adjacent visible-name pattern.
 
 ## 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>
-```
-
-This is an app-level composition; UIify does not currently ship this component.
+Repeating the adjacent person's name in image alt text can announce the identity twice.
 
 ## 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)
+- [developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img) (verified 2026-10-19)
+- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/non-text-content.html) (verified 2026-10-19)

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

@@ -1,47 +1,39 @@
 # badge
 
-Binding: gap
+Binding: badge
 
 Mark a short status or category beside related content.
 
 ## Use when
 
-A short status or category qualifies nearby content and helps people scan it.
+A short visible label helps people scan the state or category of nearby content.
 
 ## Avoid when
 
-Do not use a badge for a control, long explanation, or decoration that repeats an adjacent heading without adding meaning.
+Do not use Badge as a control, for long explanations, or for status conveyed by color alone.
 
 ## 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.
+`Badge` renders a text `span`. Its `variant` (`secondary`, `success`, `warning`, or `destructive`) and `size` (`sm`, `md`, or `lg`) write `data-variant` and `data-size`. Keep the state or category in the text.
 
 ## 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.
+Keep labels concise and attached to the related content in reading order. Check long translated text and zoom.
 
 ## 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.
+Badge is static text. It does not add a role, keyboard behavior, selection state, or live announcement.
 
 ## Verify
 
-Check text contrast, status conveyed without color, association with the item, zoom, and dynamic announcement only when needed.
+Unit tests check the native span, text, optional attributes, root props and ref. Check contrast and meaning without color in the consumer's chosen theme.
 
 ## Common mistake
 
-A green dot without a textual status does not explain what “active” means.
-
-## Custom implementation
-
-```html
-<p>Deployment <span>Pending review</span></p>
-```
-
-This is an app-level composition; UIify does not currently ship this component.
+A colored dot or a green background without a textual status does not explain the state.
 
 ## 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)
+- [developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span) (verified 2026-10-19)
+- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (verified 2026-10-19)
+- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html) (verified 2026-10-19)

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

@@ -1,51 +1,40 @@
 # card
 
-Binding: gap
+Binding: card
 
 Group one feature heading and its explanation.
 
 ## Use when
 
-A small set of related content needs a clear grouping, with a heading and supporting detail.
+A related heading, explanation, and optional links or actions need a clear content group.
 
 ## Avoid when
 
-Do not wrap every paragraph or list item in a card. Avoid card-within-card nesting and whole-surface click behavior when the card contains multiple independent controls.
+Do not wrap every paragraph or list item in a card. Avoid whole-surface click behavior when the card contains independent controls.
 
 ## Structure
 
-This is an app-level composition, not a UIify component. Group one topic under a heading, add a concise description, and use a link for one clear destination. If the card has one destination, make the heading link the primary control; keep other controls separate.
+`Card` renders a `div` by default and accepts `as` for a semantic root such as `article`. Compose native headings, text, links, and buttons as children; each control remains independent.
 
 ## Responsive
 
-Keep cards in reading order when the grid stacks. Let content determine height and align repeated actions without truncating essential labels.
+Let content set the height. Keep links readable and allow the layout around cards to stack in source order at narrow widths and zoom.
 
 ## States
 
-Use links for navigation and buttons for in-place actions. Add selected/pressed state only when the card itself represents a selectable item.
+Card has no selection or interaction state. Add interactive semantics to a link, button, or other child only.
 
 ## Verify
 
-Check heading hierarchy, reading order, single versus multiple actions, keyboard reachability, focus visibility, and one-column reflow.
+Unit and public-page tests check the content root and independent link. Check heading order, focus visibility on child controls, and one-column reflow in the consumer layout.
 
 ## Common mistake
 
-Making an entire card clickable while also placing buttons or links inside it creates nested, ambiguous controls.
-
-## Custom implementation
-
-```html
-<article aria-labelledby="plan-title">
-  <h2 id="plan-title"><a href="/plans/pro">Pro plan</a></h2>
-  <p>For teams that need shared workspaces.</p>
-</article>
-```
-
-This is an app-level composition; UIify does not currently ship this component.
+Making the whole card a link while also nesting other links or buttons creates ambiguous interactive content.
 
 Related laws: references/laws/proximity.md, references/laws/readability.md
 
 ## 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)
+- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (verified 2026-10-19)
+- [www.w3.org](https://www.w3.org/WAI/WCAG22/Understanding/visual-presentation.html) (verified 2026-10-19)

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

@@ -14,7 +14,7 @@ Use a radio group when exactly one option can be selected. Use a switch for a si
 
 ## Structure
 
-Use the documented Checkbox with a stable id and a visible, descriptive label. Group related choices in a fieldset with a legend; use the indeterminate state only for an aggregate that represents mixed child selections.
+Use the documented Checkbox with a stable id and a visible, descriptive label. For form submission, provide its native `name` and `value`. Group related choices in a fieldset with a legend; use the indeterminate state only for an aggregate that represents mixed child selections.
 
 ## Responsive
 

package/skills/uiify/references/elements/date-picker.md

@@ -1,8 +1,8 @@
 # date-picker
 
-Binding: gap
+Binding: date-picker
 
-Collect one calendar date using the browser’s native date control.
+Collect one calendar date with the browser’s native date input.
 
 ## Use when
 
@@ -10,34 +10,30 @@ Collect one calendar date without a time, such as a start or due date.
 
 ## Avoid when
 
-Use a date-time control when time matters. Avoid replacing the native picker with a custom calendar unless the task requires behavior that has been tested for keyboard and assistive technology.
+Use a date-time control when time matters. Do not replace the native picker with a custom calendar unless its keyboard and assistive-technology behavior is in scope and tested.
 
 ## Structure
 
-Use a visible label with a native input of type date. Add min and max only when the constraints are real, explain them before entry, and associate error feedback with the field.
+`DatePicker` renders a native `input[type="date"]`. It accepts native input props and ref except `type`, which is fixed; `invalid` sets `aria-invalid` and `data-invalid`. Add a separate visible label and caller-owned help/error relationships. Use `min`, `max`, `required`, `name`, and `value` only as needed. The submitted date is `yyyy-mm-dd`; display and picker UI belong to the browser and locale.
 
 ## Responsive
 
-Allow the browser’s date UI to use the platform layout; keep the field within the available width and do not assume every browser displays the same picker.
+The optional stylesheet styles only the outer control: border, surface/text, typography, logical padding, minimum inline size, focus, invalid, and disabled state. Preserve native `appearance`, picker icon, and calendar internals.
 
 ## States
 
-Distinguish an empty value, a valid date, and a date outside the allowed range. The submitted date value is a calendar date normalized as yyyy-mm-dd.
+Preserve native empty/value, required, bounds, disabled, and invalid behavior. Revalidate on the server; a date-only value is not a timestamp or time-zone value.
 
 ## Verify
 
-Test keyboard entry and picker operation in target browsers, date bounds, visible format guidance, validation text, and narrow-screen behavior.
+Test label, native entry/picker, submitted value, required/bounds, visible focus, invalid/disabled style, and narrow layout with JavaScript disabled. Browser picker operation and visuals remain unverified until each target engine is exercised.
 
 ## Common mistake
 
-Treating a date-only value as a timestamp with a time zone.
-
-## Custom implementation
-
-Use a labelled native input with type date. This app-level pattern does not add a UIify date-picker component.
+Do not add a custom calendar, convert the date to a time-zone timestamp, style vendor-only picker pseudo-elements, or use a placeholder as the only label.
 
 ## Sources
 
-- [developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input/date) (verified 2026-10-17)
-- [www.w3.org](https://www.w3.org/WAI/tutorials/forms/labels/) (verified 2026-10-17)
-- [www.w3.org](https://www.w3.org/WAI/tutorials/forms/instructions/) (verified 2026-10-17)
+- [developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input/date) (verified 2026-10-19)
+- [html.spec.whatwg.org](https://html.spec.whatwg.org/multipage/input.html) (verified 2026-10-19)
+- [www.w3.org](https://www.w3.org/WAI/tutorials/forms/labels/) (verified 2026-10-19)

package/skills/uiify/references/elements/description-list.md

@@ -0,0 +1,38 @@
+# description-list
+
+Binding: description-list
+
+Present descriptive terms and their associated values.
+
+## Use when
+
+Show descriptive metadata as terms with associated values, such as status and owner.
+
+## Avoid when
+
+Use a table for tabular data and a list for tasks or actions. Do not use `dl` as a generic visual grid without term/value relationships.
+
+## Structure
+
+`DescriptionList` renders `dl`; compose `DescriptionTerm` (`dt`) and `DescriptionDetails` (`dd`) in consumer-authored source order. Keep each term adjacent to its description. Multiple terms or descriptions may be grouped when the content calls for it; no table roles or action-column API is added.
+
+## Responsive
+
+Let terms and long values wrap. A visual grid may stack at narrow widths, but DOM order remains term then details and uses logical CSS.
+
+## States
+
+This is static descriptive content with no selection or interaction state.
+
+## Verify
+
+Check source order, term/value pairing, long and CJK values, RTL, and zoom reflow. Assistive-technology announcements vary; no browser or screen-reader verification is recorded.
+
+## Common mistake
+
+Do not replace the native `dl`/`dt`/`dd` structure with table roles or make values depend on visual column alignment.
+
+## Sources
+
+- [design-system.service.gov.uk](https://design-system.service.gov.uk/components/summary-list/) (verified 2026-10-19)
+- [developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/dl) (verified 2026-10-19)