# Ant Design Repository Copilot Instructions

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 [`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.

## Project Context

- **Framework**: TypeScript + React (compatible with React 16-19)
- **Package**: Published as npm package `antd`
- **Purpose**: Enterprise-class UI components for React applications
- **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

// Icons live in a separate package
import { SearchOutlined } from '@ant-design/icons';
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';
// 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

- Always use TypeScript with strict type checking
- Never use `any` type - define precise types instead
- Use interfaces (not type aliases) for object structures
- Export all public interface types
- Component props interfaces should be named `ComponentNameProps`
- Component ref types should use `React.ForwardRefRenderFunction`
- Prefer union types over enums, use `as const` for constants

### React Component Guidelines

- Use functional components with hooks exclusively (no class components)
- Use early returns to improve readability
- Apply performance optimizations with React.memo, useMemo, useCallback appropriately
- Support server-side rendering
- Maintain backward compatibility - avoid breaking changes
- Components must support ref forwarding with this structure:
  ```tsx
  ComponentRef {
    nativeElement: HTMLElement;
    focus: VoidFunction;
    // other methods
  }
  ```

### Naming Conventions

- **Components**: PascalCase (e.g., `Button`, `DatePicker`)
- **Props**: camelCase with specific patterns:
  - Default values: `default` + `PropName` (e.g., `defaultValue`)
  - Force rendering: `forceRender`
  - Panel state: use `open` instead of `visible`
  - Display toggles: `show` + `PropName`
  - Capabilities: `PropName` + `able`
  - Data source: `dataSource`
  - Disabled state: `disabled`
  - Additional content: `extra`
  - Icons: `icon`
  - Triggers: `trigger`
  - CSS classes: `className`
- **Events**: `on` + `EventName` (e.g., `onClick`, `onChange`)
- **Sub-component events**: `on` + `SubComponentName` + `EventName`
- Use complete names, never abbreviations

### Styling Approach

- 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 (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

### Bundle & Performance

- Avoid introducing new dependencies
- Maintain strict bundle size control
- Support tree shaking
- Browser compatibility: Chrome 80+
- Optimize for minimal re-renders

### Testing Requirements

- Write comprehensive tests using Jest and React Testing Library
- 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 [`AGENTS.md`](../AGENTS.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 (`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 [`AGENTS.md`](../AGENTS.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:

- String defaults in backticks: `"default"`
- Boolean defaults as literal values: `true` or `false`
- Number defaults as literal values: `0`, `100`
- No default value: `-`
- Descriptions start with capital letter, no ending period
- 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 under `components/locale/`
- Locale content should be plain strings with `${}` placeholders for variables

### File Organization

- 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 exports through `components/[component-name]/index.tsx`

## Development Commands

- `npm start` - Development server
- `npm run build` - Build project
- `npm test` - Run tests
- `npm run lint` - Code linting
- `npm run format` - Code formatting

## Quality Standards

- Pass all ESLint and TypeScript checks
- Achieve 100% test coverage
- Support accessibility (WCAG 2.1 AA)
- Maintain cross-browser compatibility
- No console errors or warnings

When contributing code, ensure it follows these patterns and integrates seamlessly with the existing Ant Design ecosystem.