--- name: component-usage-ux description: > Use as the app-side UI-kit usage orchestrator. Chooses which @techsio/ui-kit component and per-component *-usage skill to load before selecting props, variants, themes, sizes, slots, framework adapters, and token overrides. metadata: type: "composition" library: "@techsio/ui-kit" library_version: "0.3.2" requires: "app-token-overrides" resources: "../ux-guidelines/references/component-selection.md ../../references/component-contracts.md ../../references/consumer_app_usage_rules.md" sources: "../../references/consumer_app_usage_rules.md ../../references/component-contracts.md https://zagjs.com/components/react/combobox" audience: "consumer" --- > Portable scope: Use the installed package's exported types and bundled sibling skills. Repository source paths are optional contributor evidence, not consumer prerequisites; use the consuming app's own checks. Resolve ../../references/ paths from this skill's folder, not the app working directory. # @techsio/ui-kit Component Usage UX Use this in apps. It is a router, not a complete component manual. Load order for any UI work: ```text component-usage-ux -> which component fits the intent ux-guidelines -> house UX rules: copy, dates/numbers, alignment, states, where actions and feedback live, component selection -usage -> the component API, plus its "UX/UI guidelines" section ``` ## Setup ### Installed consumer (default) Load the sibling `-usage` skill from the installed skill library. For a standalone plugin, resolve the following paths **from this SKILL.md's folder**, never from the consuming application's current working directory: - `../../references/consumer_app_usage_rules.md` — consumer rules. - `../../references/component-contracts.md` — shared field/focus contracts. - `../ux-guidelines/references/component-selection.md` — intent/component map. The portable generator bundles the first two resources from their canonical repository sources. In a source checkout, read the `sources` entries above. Use the installed `@techsio/ui-kit/package.json` exports and the exported `.d.ts` props (through editor/type navigation) to verify the **installed version**. No `libs/ui/src`, `_artifacts`, monorepo checkout or kit build command is required. For example, `React.ComponentProps` checks the public Button API. ### Kit contributor only When deliberately changing the kit in its source checkout, explore `libs/ui/src/{atoms,molecules,organisms}` and `libs/ui/skills`. Source paths cited as evidence below are contributor provenance, not installed-consumer prerequisites. Run repository commands only for contributor work; app work uses its own type, lint and test scripts. Never patch package internals in an installed app. Then choose the exact skill: ```text Button action -> button-usage Dialog confirmation -> dialog-usage Date or date-time selection -> date-picker-usage Toast feedback -> toast-usage Guided walkthrough -> tour-usage Wizard/progress workflow -> steps-usage Hierarchical choice -> cascade-select-usage Nested site/category links -> vertical-navigation-usage Tree widget with arrow-key selection -> tree-view-usage Loading placeholder -> skeleton-usage Catalog search navigation -> search-suggestions-usage Catalog facet filtering -> facet-filter-panel-usage Cart/order product row -> line-item-usage Prepared amount breakdown and total -> totals-summary-usage Quantity with unit/help/error/pending -> quantity-field-usage Bare numeric draft or stepper -> numeric-input-usage Shortcut hint or keyboard registration -> hotkeys-usage Searchable action panel -> command-usage (plus dialog-usage for a modal shell) ``` ## Core Patterns ### Start from UX intent The full intent → component table (with the look-alikes to avoid) is `../ux-guidelines/references/component-selection.md`. ```text Destructive action -> Button danger, maybe Dialog confirmation CRUD success/error -> Toast or StatusText depending persistence and context Where the CRUD buttons go -> ux-guidelines (page actions top-right, form actions bottom-right) Hierarchical form choice -> CascadeSelect Hierarchical page/category navigation -> VerticalNavigation Tree widget selection -> TreeView Page trail -> Breadcrumb with framework link adapter when needed ``` Do not begin by writing native HTML. ### Verify props before use Use the installed declaration for the component subpath, not a repository search command. For example: ```tsx import type { ComponentProps } from "react" import { Button } from "@techsio/ui-kit/atoms/button" type AppButtonProps = ComponentProps ``` Never invent props such as `variant="ghost"` unless the installed public props support them. Contributors may also inspect the matching TSX source. ### Read Zag docs for Zag-backed components ```text Combobox usage -> inspect the installed @techsio/ui-kit/molecules/combobox declaration -> read https://zagjs.com/components/react/combobox -> compare our wrapper props/slots to Zag machine props and anatomy ``` Use Zag docs to understand machine capabilities such as collections, controlled `value`/`inputValue`, `defaultValue`, `multiple`, disabled items, `closeOnSelect`, open state, and required part props. Then use only the API that `@techsio/ui-kit` exposes. ### Let tokens handle appearance ```tsx ``` Do not duplicate the component's background, foreground, padding, radius, or font className when props and tokens already provide it. ### Avoid wrappers before API review ```text Need NextLink in Breadcrumb? -> check Breadcrumb.Link props and Link as prop support -> use framework-consumer-integration -> wrapper only after proving the component cannot support it ``` Local wrappers are a last resort. ## Common Mistakes ### HIGH Generic usage without component skill Wrong: ```text Choose Button props from memory and skip button-usage. ``` Correct: ```text Load button-usage, inspect Button props, then choose variant/theme/size. ``` Usage rules are intentionally per-component because props differ. Contributor provenance: libs/ui/skills/_artifacts/skill_spec.md ### HIGH Native or custom primitive Wrong: ```tsx ``` Correct: ```tsx ``` Apps should use UI-kit components when the library already has the primitive. Source: ../../references/consumer_app_usage_rules.md ### HIGH Hallucinated component prop Wrong: ```tsx ``` Correct: ```tsx ``` The Button source defines `appearance="ghost"`; there is no `variant="ghost"`. Source: libs/ui/src/atoms/button.tsx ### HIGH Duplicate prop styling Wrong: ```tsx