Merge branch 'main' into fix_accordion_story

Author: KostyaAvtushko

AGENTS.md

@@ -0,0 +1,15 @@
+## How should the AI use the Gravity UI design system?
+
+- **Repository and paths**: This repo implements `@gravity-ui/uikit`. When you see `uikit/src/...`, it refers to this repo’s `src/` directory.
+- **Components**: Design system components are in `uikit/src/components/`, each in its own folder `uikit/src/components/<ComponentName>/` with implementation (`<ComponentName>.tsx`) and styles (`<ComponentName>.scss`).
+- **Stories**: Per‑component Storybook files are in `uikit/src/components/<ComponentName>/__stories__/`, and higher‑level stories (branding, colors, typography) are in `uikit/src/stories/`.
+- **Hooks and utilities**: Shared hooks live in `uikit/src/hooks/`, and utilities in `uikit/src/utils/` and `uikit/src/components/utils/`.
+- **Styles and tokens**: Design tokens and themes are in `uikit/styles/` (including `uikit/styles/themes/...`); component SCSS is co‑located with each component.
+- **Usage in other repos**: In applications, import from `@gravity-ui/uikit` (and documented sub‑entries like `@gravity-ui/uikit/server`), not from `uikit/src/...`, and use the existing component patterns and props instead of re‑implementing them.
+- **Naming across repos**: You can refer to this and other design system repositories by their folder names (for example, `uikit/src/components/` or `design-system/src/stories/`) when describing code locations.
+
+### Example prompts for AI tools (Builder.io, Cursor, etc.)
+
+- **Create a new screen using UIKit**: “Build a responsive Billing Settings page using `@gravity-ui/uikit` components only. Use layout primitives (`Container`, `Row`, `Col`, `Flex`) plus `Card`, `Text`, `TextInput`, `Button`, and `Table` where appropriate. Import components only from `@gravity-ui/uikit`.”
+- **Refactor existing UI to use UIKit**: “Refactor this component to use `@gravity-ui/uikit` instead of raw HTML and inline styles. Replace buttons, text, inputs, and layout with UIKit components while keeping behavior and data flow the same.”
+- **Generate design‑system‑compliant variants**: “Generate three layout variants of this section using `@gravity-ui/uikit` only. Use existing layout components (`Container`, `Row`, `Col`, `Flex`) and typography/buttons from UIKit, and explain which components you chose and why.”