Contributing Components

Use this checklist for every new or materially changed primitive.

Contract

Every primitive must satisfy the universal-component contract:

1. source implementation in src/packages/ui/src;
2. native variant or documented web-only rationale;
3. same prop API across platforms when native exists;
4. accepts className on every visual root and visual sub-component, merged last through cn(..., className);
5. accessible by default;
6. AI-UI Zod schema when descriptor-renderable;
7. Storybook story;
8. docs-site content;
9. wiki page;
10. docs/index.md row.

Naming

• Component: PascalCase.
• Hook: camelCase.
• File name matches the exported symbol.
• Package entry uses named exports only.

Design

• Use semantic tokens.
• Do not hardcode raw hex values in components.
• Use icons from @mihcm/icons or Lucide wrappers.
• Include empty, disabled, loading, error, long text, RTL, and mobile cases where relevant.

Accessibility

At minimum:

• keyboard navigation;
• visible focus;
• 44px touch targets for mobile actions;
• correct ARIA roles and labels;
• screen reader behavior documented;
• color contrast at WCAG 2.1 AA.

Required Files

Verification

Run:

cd src
pnpm build
pnpm typecheck
pnpm lint
pnpm test

Then use MCP:

• mihcm_search_components before building;
• mihcm_check_contract before finishing;
• mihcm_validate_descriptor for AI-UI schemas.