docs: add copilot-instructions file to reduce AI hallucinations (ant-design#58101)

Author: yogeshwaran-c

.github/copilot-instructions.md

@@ -2,6 +2,8 @@
 
 This is the Ant Design (antd) repository - a React component library with enterprise-class UI design language, widely used for building professional web applications.
 
+> For deeper, project-wide conventions (demo/test import rules, documentation format, changelog rules, PR templates, etc.), see [`CLAUDE.md`](../CLAUDE.md) at the repository root. This file is a concise, suggestion-time reference designed to keep AI tools from hallucinating non-existent components or APIs.
+
 ## Project Context
 
 - **Framework**: TypeScript + React (compatible with React 16-19)
@@ -10,6 +12,54 @@ This is the Ant Design (antd) repository - a React component library with enterp
 - **Design System**: Follows Ant Design specifications
 - **Internationalization**: Full i18n support
 
+## Authoritative Component List
+
+The following are the **only** top-level exports of `antd`. Do **not** invent components outside this list (e.g. `antd` does not export `Container`, `Stack`, `Heading`, `Box`, `Sidebar`, `Navbar`, `IconButton`, etc.).
+
+`Affix`, `Alert`, `Anchor`, `App`, `AutoComplete`, `Avatar`, `BackTop` (deprecated — use `FloatButton.BackTop`), `Badge`, `BorderBeam`, `Breadcrumb`, `Button`, `Calendar`, `Card`, `Carousel`, `Cascader`, `Checkbox`, `Col`, `Collapse`, `ColorPicker`, `ConfigProvider`, `DatePicker`, `Descriptions`, `Divider`, `Drawer`, `Dropdown`, `Empty`, `Flex`, `FloatButton`, `Form`, `Grid`, `Image`, `Input`, `InputNumber`, `Layout`, `List`, `Masonry`, `Mentions`, `Menu`, `Modal`, `Pagination`, `Popconfirm`, `Popover`, `Progress`, `QRCode`, `Radio`, `Rate`, `Result`, `Row`, `Segmented`, `Select`, `Skeleton`, `Slider`, `Space`, `Spin`, `Splitter`, `Statistic`, `Steps`, `Switch`, `Table`, `Tabs`, `Tag`, `TimePicker`, `Timeline`, `Tooltip`, `Tour`, `Transfer`, `Tree`, `TreeSelect`, `Typography`, `Upload`, `Watermark`.
+
+Function exports (lowercase): `message`, `notification`, `theme`, `version`, `unstableSetRender`.
+
+When in doubt, verify against `components/index.ts` (the source of truth for public exports). Icons live in a **separate** package: `@ant-design/icons` — never import icons from `antd`.
+
+## Import Patterns
+
+```tsx
+// Components and types
+import { Button, Form, Input, type FormProps } from 'antd';
+
+// Locales live under antd/locale (not from the main entry)
+import enUS from 'antd/locale/en_US';
+
+// Icons live in a separate package
+import { SearchOutlined } from '@ant-design/icons';
+
+// DatePicker / TimePicker / Calendar require a date library wrapper.
+// The default uses dayjs — moment is no longer the default since v5.
+import dayjs from 'dayjs';
+```
+
+## API Migration Notes (Do Not Hallucinate the Old Names)
+
+The current major version uses these renames. Use the **new** API in suggestions:
+
+| Component | Deprecated (do not suggest) | Use instead |
+| --- | --- | --- |
+| Modal, Drawer, Dropdown, Tooltip, Popover, Popconfirm, Cascader, Select, AutoComplete, TreeSelect, etc. | `visible`, `onVisibleChange` | `open`, `onOpenChange` |
+| Modal, Drawer, Tabs, etc. | `destroyOnClose` | `destroyOnHidden` |
+| Tabs | `<Tabs><Tabs.TabPane /></Tabs>` (children API) | `<Tabs items={[{ key, label, children }]} />` |
+| Menu | `<Menu><Menu.Item /></Menu>` (children API) | `<Menu items={[{ key, label }]} />` |
+| Breadcrumb | `routes`, `<Breadcrumb.Item />` (children API) | `items={[{ title }]}` |
+| Anchor | children-based `<Anchor.Link />` | `items={[{ key, href, title }]}` |
+| AutoComplete, Cascader, Select | `dropdownClassName`, `dropdownStyle`, `dropdownRender`, `dropdownMatchSelectWidth` | `classNames.popup.root`, `styles.popup.root`, `popupRender`, `popupMatchSelectWidth` |
+| AutoComplete, Cascader | `onDropdownVisibleChange` | `onOpenChange` |
+| Card | `bordered` | `variant` |
+| Avatar.Group | `maxCount`, `maxStyle`, `maxPopoverPlacement` | `max={{ count, style, popover }}` |
+| BackTop | top-level `BackTop` | `FloatButton.BackTop` |
+| Calendar | `dateCellRender`, `dateFullCellRender` | `cellRender`, `fullCellRender` |
+
+Internally these are flagged via `warning.deprecated(...)` and `@deprecated` JSDoc tags; check the component's `interface.ts` / `index.tsx` if unsure.
+
 ## Code Standards & Best Practices
 
 ### TypeScript Requirements
@@ -62,8 +112,7 @@ This is the Ant Design (antd) repository - a React component library with enterp
 - Use `@ant-design/cssinjs` for all styling
 - Place component styles in `style/` directory
 - Generate styles with functions named `gen[ComponentName]Style`
-- Use design tokens from the Ant Design token system
-- Never hardcode colors, sizes, or spacing values
+- Use design tokens from the Ant Design token system (read tokens via the `theme.useToken()` hook, or `token` argument inside style functions) — never hardcode colors, sizes, or spacing values
 - Support both light and dark themes
 - Use CSS logical properties for RTL support (e.g., `margin-inline-start` instead of `margin-left`)
 - Respect `prefers-reduced-motion` for animations
@@ -82,16 +131,22 @@ This is the Ant Design (antd) repository - a React component library with enterp
 - Target 100% test coverage
 - Place tests in `__tests__` directory as `index.test.tsx` or `componentName.test.tsx`
 - Include snapshot tests for UI components
+- Inside `components/**/__tests__/` use **relative** paths (`../`, `../../_util/...`) — never `antd`, `antd/es/*`, or path aliases. See [`CLAUDE.md`](../CLAUDE.md) for the full rule.
 
 ### Demo & Documentation
 
 - Keep demo code concise and copy-pasteable
 - Focus each demo on a single feature
-- Provide both English and Chinese documentation
+- Provide both English and Chinese documentation (`index.en-US.md` and `index.zh-CN.md`)
+- Inside `components/**/demo/` use **absolute** imports (`antd`, `antd/es/*`, `antd/locale/*`) — never relative paths to component internals. The semantic demos (`_semantic*.tsx`) are an exception. See [`CLAUDE.md`](../CLAUDE.md) for the full rule.
 - Follow import order: React → dependencies → antd components → custom components → types → styles
 - Use 2-space indentation
 - Prefer antd built-in components over external dependencies
 
+### Type Checks (Utility)
+
+Prefer the helpers in `components/_util/is.ts` (`isNumber`, `isString`, `isPlainObject`, `isFunction`, `isThenable`, `isPrimitive`, `isNonNullable`) over inline `typeof` / `instanceof` checks when the helper covers the case.
+
 ### API Documentation Format
 
 When documenting component APIs, use this table structure:
@@ -101,21 +156,21 @@ When documenting component APIs, use this table structure:
 - Number defaults as literal values: `0`, `100`
 - No default value: `-`
 - Descriptions start with capital letter, no ending period
-- Sort API properties alphabetically
+- Sort API properties alphabetically (ignoring common props like `className`, `style`; place event callbacks last)
 
 ### Internationalization
 
 - Locale configuration files use pattern: `locale_COUNTRY.ts` (e.g., `zh_CN.ts`)
 - Use `useLocale` hook from `components/locale/index.tsx`
-- When modifying locale strings, update ALL language files
+- When modifying locale strings, update ALL language files under `components/locale/`
 - Locale content should be plain strings with `${}` placeholders for variables
 
 ### File Organization
 
-- Components in `components/[component-name]/` directory
-- Demos in `components/[component-name]/demo/` as `.tsx` files
+- Components in `components/[component-name]/` directory (kebab-case directory name, PascalCase implementation file)
+- Demos in `components/[component-name]/demo/` as `.tsx` files paired with `.md` documentation
 - Use kebab-case for demo filenames: `basic.tsx`, `custom-filter.tsx`
-- Each component demo includes both `.md` documentation and `.tsx` code
+- Each component exports through `components/[component-name]/index.tsx`
 
 ## Development Commands