From dc056196e03ae8c4ea7b843d81fe2d2dfb5406ce Mon Sep 17 00:00:00 2001 From: m2rt Date: Fri, 16 Oct 2026 16:42:46 +0300 Subject: [PATCH] docs: migrate CLAUDE.md to AGENTS.md #1005 --- .claude/skills/contributing/SKILL.md | 2 +- .coderabbit.yaml | 2 +- AGENTS.md | 102 ++++++++++++++++++++++++++ CLAUDE.md | 103 +-------------------------- 4 files changed, 105 insertions(+), 104 deletions(-) create mode 100644 AGENTS.md diff --git a/.claude/skills/contributing/SKILL.md b/.claude/skills/contributing/SKILL.md index 17afe9c60..7f596ba18 100644 --- a/.claude/skills/contributing/SKILL.md +++ b/.claude/skills/contributing/SKILL.md @@ -14,7 +14,7 @@ You are a senior React and TypeScript engineer specializing in accessible UI com ## Before Any Code -1. Read `CLAUDE.md` at the project root for commands, architecture, and conventions. +1. Read `AGENTS.md` at the project root for commands, architecture, and conventions. 2. Read [best-practices](references/best-practices.md) for coding patterns. 3. If creating or modifying a component, check if TEDI Angular (`../angular/tedi/components/`) has an equivalent — use as behavioral reference. 4. Check TEDI Core (`../core/src/`) for available design tokens, mixins, and shared styles. diff --git a/.coderabbit.yaml b/.coderabbit.yaml index 17854e078..2a57f0aae 100644 --- a/.coderabbit.yaml +++ b/.coderabbit.yaml @@ -24,7 +24,7 @@ reviews: - path: "**" instructions: | Read and enforce the project conventions from these files: - - `CLAUDE.md` — project overview, architecture, component patterns, styling rules, testing setup, and "Do NOT" list. + - `AGENTS.md` — project overview, architecture, component patterns, styling rules, testing setup, and "Do NOT" list. - `.claude/skills/contributing/references/best-practices.md` — detailed coding patterns for components, SCSS, testing, stories, and barrel exports. Key things to NOT flag as issues: diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..d3d89c806 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,102 @@ +# AGENTS.md + +Guidance for AI coding agents working in this repository. + +> **Design system for AI/UI generation:** read [`DESIGN.md`](./DESIGN.md) (tokens + tedi-ready component rules) before generating or modifying UI. It complements the `tedi-react` skill. + +## Project Overview + +TEDI Design System React — a React component library (`@tedi-design-system/react`) providing accessible, reusable UI components. Two export namespaces: +- **`/tedi`** — TEDI-Ready components (production-grade, stricter rules) +- **`/community`** — Community/extended components (relaxed linting rules, NOT a reference for TEDI patterns) + +## Common Commands + +```bash +npm start # Storybook dev server on port 4400 +npm run build # Production build with Vite +npm test # Run all Jest tests +npm test -- --testPathPattern="button" # Run tests matching path pattern +npm run lint # ESLint + Stylelint with auto-fix +npm run test:coverage # Tests with 80% coverage threshold +npm run build:sb # Build static Storybook +``` + +## Architecture + +### Source Structure + +Components live in `src/tedi/components/` and `src/community/components/`, organized by category: `base/`, `buttons/`, `cards/`, `content/`, `form/`, `layout/`, `loaders/`, `misc/`, `navigation/`, `notifications/`, `overlays/`, `tags/`. + +Each component directory follows this pattern: +- `component-name.tsx` — Component implementation +- `component-name.spec.tsx` — Tests (Jest + React Testing Library) +- `component-name.stories.tsx` — Storybook stories + +Barrel exports: `src/tedi/index.ts` and `src/community/index.ts`. + +### Key Patterns + +- **Polymorphic components**: Many components accept an `as` prop via `forwardRef` and generic typing (``). See `helpers/polymorphic/`. +- **Breakpoint support**: Responsive props via `useBreakpointProps` hook — components accept per-breakpoint prop overrides. +- **CSS Modules with SCSS**: Styles use CSS modules with hash-based class names. SCSS files live alongside components or in `styles/` directories. +- **Providers**: `ThemeProvider`, `StyleProvider`, `AccessibilityProvider`, `LabelProvider` in `src/tedi/providers/`. + +### Build Output + +Vite builds two entry points to ES + CJS formats. Types generated via `vite-plugin-dts`. Output goes to `dist/`. Design tokens come from `@tedi-design-system/core`. + +## Commit Convention + +Conventional commits enforced by commitlint (husky pre-commit hook). Rules: +- Format: `type(scope): Subject text #issue-ref` +- Subject must be Start Case, minimum 10 characters +- **Issue reference is required** (`references-empty: never`) +- Example: `feat(button): Add Loading State Support #123` + +## Code Style + +- Single quotes, semicolons required, print width 120 +- JSX uses double quotes +- Import sorting enforced by `simple-import-sort` (packages → `@ria.*` → relative → absolute → side-effects) +- Unused imports are errors; unused vars are warnings (prefix with `_` to ignore) +- SCSS follows BEM naming convention, enforced by Stylelint +- Pre-commit hook runs lint-staged (ESLint + Stylelint + Prettier on staged files) + +## Testing + +- Framework: Jest + jsdom + React Testing Library +- Coverage collected only from `src/tedi/components/**/*.{js,ts,tsx}` (excludes stories) +- Coverage threshold: 80% for branches, functions, lines, and statements +- `jest-setup.js` includes `@testing-library/jest-dom` matchers and `window.matchMedia` mock + +## Related Repositories + +- **TEDI Angular** (`../angular/`) — Angular implementation of the same design system. Useful as behavioral reference. +- **TEDI Core** (`../core/`) — Shared design tokens, SCSS variables, fonts, and icons. + +> **Note:** These sibling repositories are available in local development only. They are NOT present in CI/CD environments — do not rely on `../angular/` or `../core/` paths in build scripts, tests, or imports that run in CI. + +## Do NOT + +- Use `src/community/` components as reference for coding patterns or style — they are community-contributed and not always reviewed +- Hardcode color values — always use design tokens from `@tedi-design-system/core` +- Use fallback values in CSS `var()` functions — write `var(--token-name)`, not `var(--token-name, fallback)` +- Forget `displayName` on exported components +- Create form controls that only support controlled mode — always support both controlled and uncontrolled +- Use non-semantic queries in tests (`getByTestId`) when semantic ones work (`getByRole`, `getByLabelText`) +- Skip `forwardRef` when a component needs ref forwarding +- Use inline styles instead of CSS Modules with SCSS +- Forget to mock `useBreakpointProps` in tests for components that use breakpoint support +- Add `@ts-ignore` or `any` types — use proper TypeScript generics + +## Release + +Semantic Release on `main` (stable) and `rc` (prerelease) branches. Tag format: `react-${version}`. Publishes to npm from `dist/`. + +## For Code Review Agents (CodeRabbit, etc.) + +Read `.claude/skills/contributing/references/best-practices.md` for the full set of coding patterns and rules to enforce during review. + +Key things to **not** flag: +- Missing CSS `var()` fallback values — intentionally omitted. diff --git a/CLAUDE.md b/CLAUDE.md index c4bdf0d17..43c994c2d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,102 +1 @@ -# CLAUDE.md - -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. - -> **Design system for AI/UI generation:** read [`DESIGN.md`](./DESIGN.md) (tokens + tedi-ready component rules) before generating or modifying UI. It complements the `tedi-react` skill. - -## Project Overview - -TEDI Design System React — a React component library (`@tedi-design-system/react`) providing accessible, reusable UI components. Two export namespaces: -- **`/tedi`** — TEDI-Ready components (production-grade, stricter rules) -- **`/community`** — Community/extended components (relaxed linting rules, NOT a reference for TEDI patterns) - -## Common Commands - -```bash -npm start # Storybook dev server on port 4400 -npm run build # Production build with Vite -npm test # Run all Jest tests -npm test -- --testPathPattern="button" # Run tests matching path pattern -npm run lint # ESLint + Stylelint with auto-fix -npm run test:coverage # Tests with 80% coverage threshold -npm run build:sb # Build static Storybook -``` - -## Architecture - -### Source Structure - -Components live in `src/tedi/components/` and `src/community/components/`, organized by category: `base/`, `buttons/`, `cards/`, `content/`, `form/`, `layout/`, `loaders/`, `misc/`, `navigation/`, `notifications/`, `overlays/`, `tags/`. - -Each component directory follows this pattern: -- `component-name.tsx` — Component implementation -- `component-name.spec.tsx` — Tests (Jest + React Testing Library) -- `component-name.stories.tsx` — Storybook stories - -Barrel exports: `src/tedi/index.ts` and `src/community/index.ts`. - -### Key Patterns - -- **Polymorphic components**: Many components accept an `as` prop via `forwardRef` and generic typing (``). See `helpers/polymorphic/`. -- **Breakpoint support**: Responsive props via `useBreakpointProps` hook — components accept per-breakpoint prop overrides. -- **CSS Modules with SCSS**: Styles use CSS modules with hash-based class names. SCSS files live alongside components or in `styles/` directories. -- **Providers**: `ThemeProvider`, `StyleProvider`, `AccessibilityProvider`, `LabelProvider` in `src/tedi/providers/`. - -### Build Output - -Vite builds two entry points to ES + CJS formats. Types generated via `vite-plugin-dts`. Output goes to `dist/`. Design tokens come from `@tedi-design-system/core`. - -## Commit Convention - -Conventional commits enforced by commitlint (husky pre-commit hook). Rules: -- Format: `type(scope): Subject text #issue-ref` -- Subject must be Start Case, minimum 10 characters -- **Issue reference is required** (`references-empty: never`) -- Example: `feat(button): Add Loading State Support #123` - -## Code Style - -- Single quotes, semicolons required, print width 120 -- JSX uses double quotes -- Import sorting enforced by `simple-import-sort` (packages → `@ria.*` → relative → absolute → side-effects) -- Unused imports are errors; unused vars are warnings (prefix with `_` to ignore) -- SCSS follows BEM naming convention, enforced by Stylelint -- Pre-commit hook runs lint-staged (ESLint + Stylelint + Prettier on staged files) - -## Testing - -- Framework: Jest + jsdom + React Testing Library -- Coverage collected only from `src/tedi/components/**/*.{js,ts,tsx}` (excludes stories) -- Coverage threshold: 80% for branches, functions, lines, and statements -- `jest-setup.js` includes `@testing-library/jest-dom` matchers and `window.matchMedia` mock - -## Related Repositories - -- **TEDI Angular** (`../angular/`) — Angular implementation of the same design system. Useful as behavioral reference. -- **TEDI Core** (`../core/`) — Shared design tokens, SCSS variables, fonts, and icons. - -> **Note:** These sibling repositories are available in local development only. They are NOT present in CI/CD environments — do not rely on `../angular/` or `../core/` paths in build scripts, tests, or imports that run in CI. - -## Do NOT - -- Use `src/community/` components as reference for coding patterns or style — they are community-contributed and not always reviewed -- Hardcode color values — always use design tokens from `@tedi-design-system/core` -- Use fallback values in CSS `var()` functions — write `var(--token-name)`, not `var(--token-name, fallback)` -- Forget `displayName` on exported components -- Create form controls that only support controlled mode — always support both controlled and uncontrolled -- Use non-semantic queries in tests (`getByTestId`) when semantic ones work (`getByRole`, `getByLabelText`) -- Skip `forwardRef` when a component needs ref forwarding -- Use inline styles instead of CSS Modules with SCSS -- Forget to mock `useBreakpointProps` in tests for components that use breakpoint support -- Add `@ts-ignore` or `any` types — use proper TypeScript generics - -## Release - -Semantic Release on `main` (stable) and `rc` (prerelease) branches. Tag format: `react-${version}`. Publishes to npm from `dist/`. - -## For Code Review Agents (CodeRabbit, etc.) - -Read `.claude/skills/contributing/references/best-practices.md` for the full set of coding patterns and rules to enforce during review. - -Key things to **not** flag: -- Missing CSS `var()` fallback values — intentionally omitted. +@AGENTS.md