Copilot instructions

1# Ant Design Repository Copilot Instructions
2 
3This is the Ant Design (antd) repository - a React component library with enterprise-class UI design language, widely used for building professional web applications.
4 
5> For deeper, project-wide conventions (demo/test import rules, documentation format, changelog rules, PR templates, etc.), see [`AGENTS.md`](../AGENTS.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.
6 
7## Project Context
8 
9- **Framework**: TypeScript + React (compatible with React 16-19)
10- **Package**: Published as npm package `antd`
11- **Purpose**: Enterprise-class UI components for React applications
12- **Design System**: Follows Ant Design specifications
13- **Internationalization**: Full i18n support
14 
15## Authoritative Component List
16 
17The 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.).
18 
19`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`.
20 
21Function exports (lowercase): `message`, `notification`, `theme`, `version`, `unstableSetRender`.
22 
23When 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`.
24 
25## Import Patterns
26 
27```tsx
28// Components and types
29 
30// Icons live in a separate package
31import { SearchOutlined } from '@ant-design/icons';
32import { Button, Form, Input, type FormProps } from 'antd';
33// Locales live under antd/locale (not from the main entry)
34import enUS from 'antd/locale/en_US';
35// DatePicker / TimePicker / Calendar require a date library wrapper.
36// The default uses dayjs — moment is no longer the default since v5.
37import dayjs from 'dayjs';
38```
39 
40## API Migration Notes (Do Not Hallucinate the Old Names)
41 
42The current major version uses these renames. Use the **new** API in suggestions:
43 
44| Component | Deprecated (do not suggest) | Use instead |
45| --- | --- | --- |
46| Modal, Drawer, Dropdown, Tooltip, Popover, Popconfirm, Cascader, Select, AutoComplete, TreeSelect, etc. | `visible`, `onVisibleChange` | `open`, `onOpenChange` |
47| Modal, Drawer, Tabs, etc. | `destroyOnClose` | `destroyOnHidden` |
48| Tabs | `<Tabs><Tabs.TabPane /></Tabs>` (children API) | `<Tabs items={[{ key, label, children }]} />` |
49| Menu | `<Menu><Menu.Item /></Menu>` (children API) | `<Menu items={[{ key, label }]} />` |
50| Breadcrumb | `routes`, `<Breadcrumb.Item />` (children API) | `items={[{ title }]}` |
51| Anchor | children-based `<Anchor.Link />` | `items={[{ key, href, title }]}` |
52| AutoComplete, Cascader, Select | `dropdownClassName`, `dropdownStyle`, `dropdownRender`, `dropdownMatchSelectWidth` | `classNames.popup.root`, `styles.popup.root`, `popupRender`, `popupMatchSelectWidth` |
53| AutoComplete, Cascader | `onDropdownVisibleChange` | `onOpenChange` |
54| Card | `bordered` | `variant` |
55| Avatar.Group | `maxCount`, `maxStyle`, `maxPopoverPlacement` | `max={{ count, style, popover }}` |
56| BackTop | top-level `BackTop` | `FloatButton.BackTop` |
57| Calendar | `dateCellRender`, `dateFullCellRender` | `cellRender`, `fullCellRender` |
58 
59Internally these are flagged via `warning.deprecated(...)` and `@deprecated` JSDoc tags; check the component's `interface.ts` / `index.tsx` if unsure.
60 
61## Code Standards & Best Practices
62 
63### TypeScript Requirements
64 
65- Always use TypeScript with strict type checking
66- Never use `any` type - define precise types instead
67- Use interfaces (not type aliases) for object structures
68- Export all public interface types
69- Component props interfaces should be named `ComponentNameProps`
70- Component ref types should use `React.ForwardRefRenderFunction`
71- Prefer union types over enums, use `as const` for constants
72 
73### React Component Guidelines
74 
75- Use functional components with hooks exclusively (no class components)
76- Use early returns to improve readability
77- Apply performance optimizations with React.memo, useMemo, useCallback appropriately
78- Support server-side rendering
79- Maintain backward compatibility - avoid breaking changes
80- Components must support ref forwarding with this structure:
81```tsx
82  ComponentRef {
83    nativeElement: HTMLElement;
84    focus: VoidFunction;
85    // other methods
86  }
87```
88 
89### Naming Conventions
90 
91- **Components**: PascalCase (e.g., `Button`, `DatePicker`)
92- **Props**: camelCase with specific patterns:
93  - Default values: `default` + `PropName` (e.g., `defaultValue`)
94  - Force rendering: `forceRender`
95  - Panel state: use `open` instead of `visible`
96  - Display toggles: `show` + `PropName`
97  - Capabilities: `PropName` + `able`
98  - Data source: `dataSource`
99  - Disabled state: `disabled`
100  - Additional content: `extra`
101  - Icons: `icon`
102  - Triggers: `trigger`
103  - CSS classes: `className`
104- **Events**: `on` + `EventName` (e.g., `onClick`, `onChange`)
105- **Sub-component events**: `on` + `SubComponentName` + `EventName`
106- Use complete names, never abbreviations
107 
108### Styling Approach
109 
110- Use `@ant-design/cssinjs` for all styling
111- Place component styles in `style/` directory
112- Generate styles with functions named `gen[ComponentName]Style`
113- 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
114- Support both light and dark themes
115- Use CSS logical properties for RTL support (e.g., `margin-inline-start` instead of `margin-left`)
116- Respect `prefers-reduced-motion` for animations
117 
118### Bundle & Performance
119 
120- Avoid introducing new dependencies
121- Maintain strict bundle size control
122- Support tree shaking
123- Browser compatibility: Chrome 80+
124- Optimize for minimal re-renders
125 
126### Testing Requirements
127 
128- Write comprehensive tests using Jest and React Testing Library
129- Target 100% test coverage
130- Place tests in `__tests__` directory as `index.test.tsx` or `componentName.test.tsx`
131- Include snapshot tests for UI components
132- Inside `components/**/__tests__/` use **relative** paths (`../`, `../../_util/...`) — never `antd`, `antd/es/*`, or path aliases. See [`AGENTS.md`](../AGENTS.md) for the full rule.
133 
134### Demo & Documentation
135 
136- Keep demo code concise and copy-pasteable
137- Focus each demo on a single feature
138- Provide both English and Chinese documentation (`index.en-US.md` and `index.zh-CN.md`)
139- 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 [`AGENTS.md`](../AGENTS.md) for the full rule.
140- Follow import order: React → dependencies → antd components → custom components → types → styles
141- Use 2-space indentation
142- Prefer antd built-in components over external dependencies
143 
144### Type Checks (Utility)
145 
146Prefer 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.
147 
148### API Documentation Format
149 
150When documenting component APIs, use this table structure:
151 
152- String defaults in backticks: `"default"`
153- Boolean defaults as literal values: `true` or `false`
154- Number defaults as literal values: `0`, `100`
155- No default value: `-`
156- Descriptions start with capital letter, no ending period
157- Sort API properties alphabetically (ignoring common props like `className`, `style`; place event callbacks last)
158 
159### Internationalization
160 
161- Locale configuration files use pattern: `locale_COUNTRY.ts` (e.g., `zh_CN.ts`)
162- Use `useLocale` hook from `components/locale/index.tsx`
163- When modifying locale strings, update ALL language files under `components/locale/`
164- Locale content should be plain strings with `${}` placeholders for variables
165 
166### File Organization
167 
168- Components in `components/[component-name]/` directory (kebab-case directory name, PascalCase implementation file)
169- Demos in `components/[component-name]/demo/` as `.tsx` files paired with `.md` documentation
170- Use kebab-case for demo filenames: `basic.tsx`, `custom-filter.tsx`
171- Each component exports through `components/[component-name]/index.tsx`
172 
173## Development Commands
174 
175- `npm start` - Development server
176- `npm run build` - Build project
177- `npm test` - Run tests
178- `npm run lint` - Code linting
179- `npm run format` - Code formatting
180 
181## Quality Standards
182 
183- Pass all ESLint and TypeScript checks
184- Achieve 100% test coverage
185- Support accessibility (WCAG 2.1 AA)
186- Maintain cross-browser compatibility
187- No console errors or warnings
188 
189When contributing code, ensure it follows these patterns and integrates seamlessly with the existing Ant Design ecosystem.
190