--- name: component-consistency-validation description: > Use after changing @techsio/ui-kit component TSX, token CSS, Storybook stories, Figma Code Connect files, package exports, or validation scripts. Checks prop/variant/token/story/Figma consistency and recommends focused commands before maintainer handoff. metadata: type: "core" library: "@techsio/ui-kit" library_version: "0.3.2" sources: "" contributor_sources: "libs/ui/package.json libs/ui/project.json libs/ui/.storybook/main.ts libs/ui/scripts/validate-token-usage.js libs/ui/scripts/validate-token-definitions.js libs/ui/scripts/run-component-tests.mjs libs/ui/figma.config.json libs/ui/skills/_artifacts/domain_map.yaml" resources: "../../references/component-contracts.md ../../references/consumer_app_usage_rules.md" audience: "contributor" --- > Portable scope: Source-authoring steps and monorepo commands require an explicit kit source checkout. In an installed consumer app, route to ../component-usage-ux/SKILL.md instead; do not run contributor commands or require repository artifacts. Resolve ../../references/ paths from this skill's folder, not the app working directory. # @techsio/ui-kit Component Consistency Validation Use this as the validation pass after changing a component slice. ## Setup Pick checks by touched area: ```text TSX only -> Biome + build Token CSS -> token validators + build Stories -> Biome + Storybook build when visual/docs behavior changed Zag/compound -> build + Storybook/a11y or component tests when practical Figma mapping -> figma connect parse Release -> ui-kit-publish-readiness ``` ## Core Patterns ### Compare TSX props to stories ```text src/atoms/button.tsx: severity: primary | secondary | tertiary | danger | warning appearance: solid | subtle | outline | ghost unstyled: boolean size: sm | md | lg | current stories/atoms/button.stories.tsx: argTypes.severity.options must match real severities argTypes.appearance.options must match real appearances argTypes.size.options must match real sizes ``` Stories must not document variants or props that the component cannot accept. ### Compare classes to token CSS ```text TSX class: bg-button-bg-primary CSS token: --color-button-bg-primary TSX class: p-button-md CSS token: --padding-button-md ``` Use the validators for missing token classes and unused token definitions. ### Check package exports by subpath ```tsx import { Button } from "@techsio/ui-kit/atoms/button" import { Carousel } from "@techsio/ui-kit/molecules/carousel" ``` The package exports wildcard subpaths for atoms, molecules, organisms, templates, tokens, and utils. Do not expect a root barrel export. ### Check Code Connect when public props change ```sh pnpm --dir libs/ui figma:connect:parse ``` Use `figma-sync-handoff` for follow-up ownership. Do not publish or edit Figma unless the maintainer asks. ## Common Mistakes ### HIGH Variant drift between code and docs Wrong: ```tsx argTypes: { severity: { options: ["primary", "ghost"] }, } ``` Correct: ```tsx argTypes: { severity: { options: ["primary", "secondary", "tertiary", "warning", "danger"] }, } ``` Storybook controls are copied by app developers, so undocumented or nonexistent options become app bugs. Source: libs/ui/src/atoms/button.tsx and libs/ui/stories/atoms/button.stories.tsx ### HIGH Token validation ignored Wrong: ```text Add className "z-(--z-index)" and skip token validation. ``` Correct: ```sh pnpm --dir libs/ui validate:tokens ``` The token usage validator maps Tailwind utility namespaces to required CSS custom properties. Source: libs/ui/scripts/validate-token-usage.js ### HIGH Compound context hole Wrong: ```tsx ``` Correct: ```tsx ``` Compound children rely on context guards such as `Carousel components must be used within Carousel.Root`. Source: libs/ui/src/molecules/carousel.tsx ## Validation Commands ```sh bunx biome check --write libs/ui/src/atoms/button.tsx libs/ui/stories/atoms/button.stories.tsx pnpm --dir libs/ui validate:tokens pnpm --dir libs/ui build pnpm --dir libs/ui figma:connect:parse pnpm --dir libs/ui build:storybook pnpm --dir libs/ui storybook:a11y pnpm --dir libs/ui test:components ``` Run only commands relevant to the changed area unless the maintainer asks for a full readiness pass. ## Shared-contract review (required) Check `../../references/component-contracts.md` alongside API/token matching: - StatusText icons default on for error/warning/success, decorative ARIA, multiline first-line alignment, unique message IDs and merged descriptions. - Every value control has true readOnly behavior (typing, keyboard, clear, steppers, triggers, chips, paste/drop, controlled/uncontrolled); focus and copy remain available. Disabled removes tab stops. CSS-only inertness is a failure. - Canonical size controls/stories use sm/md/lg and one consistently labeled Sizes story, with compatibility exceptions documented rather than removed silently. - Popup Content and Positioner agree on popup-layer, use opaque surfaces and border/shadow aliases, and preserve nested --layer-index. - All components have autodocs plus a useful component description; every story has a what/why description and working controls, realistic content and action hierarchy, no navigation away or foreign-component demo. - Review Business/light, Akros/light and N1/light. During the shared overhaul do not run Storybook builds/servers or launch browsers. Use the supplied ds-page runner; Playwright suites require Docker and its serial lock. Ignore the generic Storybook-build recommendation above when this restriction applies.