b24ui AGENTS.md

AGENTS.md

This file provides guidance for AI coding agents working on the Bitrix24 UI repository.

Project Overview

Bitrix24 UI is a component library built on Reka UI, Tailwind CSS, and Tailwind Variants. It provides accessible, themeable components for both Nuxt and Vue applications.

Project Structure

src/
├── runtime/
│   ├── components/     # Vue components (PascalCase.vue)
│   ├── composables/    # Composables (use*.ts)
│   ├── types/          # TypeScript types
│   └── utils/          # Utility functions
├── theme/              # Tailwind Variants themes (kebab-case.ts)
└── module.ts
test/
├── components/         # Component tests (*.spec.ts)
│   └── __snapshots__/  # Auto-generated snapshots
└── component-render.ts
docs/
└── content/docs/2.components/  # Documentation (*.md)
playgrounds/
└── nuxt/app/pages/components/  # Playground pages

Commands

pnpm run dev:prepare  # Generate type stubs (run after install)
pnpm run dev          # Nuxt playground
pnpm run dev:vue      # Vue playground
pnpm run repl         # REPL playground
pnpm run demo         # Demo playground
pnpm run docs         # Documentation site
pnpm run lint         # Check linting
pnpm run lint:fix     # Fix linting
pnpm run typecheck    # Type checking
pnpm run test         # Run tests
pnpm run skill:sync   # Regenerate skills/index.json from the skill tree

CLI for Scaffolding

Link the CLI first (one-time setup):

npm link

Then use it to create new components:

bitrix24-ui make component <name> [options]

Options:

• --primitive - Primitive component (uses Reka UI Primitive)
• --prose - Prose/typography component
• --content - Content component
• --template - Generate specific template only (playground, docs, test, theme, component)

Key Conventions

• Conventional commits: All commit messages must follow conventional commits, and the type must have a section in changelog-sections (release-please-config.json) — one that does not is dropped from the changelog, or, if the commit is breaking, rendered under a raw lowercase heading above every real section. assert-commit-parses.mjs rejects it, and rejects a port whose subject does not name the upstream commit as (nuxt/ui@<sha>) (e.g. fix(Button): resolve hover state, feat(Modal): add fullscreen prop). A revert must be titled revert(Scope): … — GitHub's revert button produces Revert "…", which release-please rejects outright, so the revert reaches no changelog and, if it is the only commit since the last tag, opens no release PR at all.
• Releases are automated: merging work into main publishes nothing; release-please keeps one release PR open and merging that tags, releases and publishes to npm. Version arithmetic (feat/feature -> minor, fix -> patch), the release cadence commitment, the severity:crash hotfix policy, the revert: subject a revert PR must carry, and the manual CI approval the release PR needs before it can merge all live in releasing.md. Filed here rather than in the References table below, which is scoped to src/ and test/ work.
• Semantic colors: Use text-description, bg-elevated, etc. — never raw Tailwind palette colors like text-gray-500.
• Dependency pins are not ours to move: reka-ui and vaul-vue are exact-pinned in package.json because upstream pins them at those exact versions; they change through a port, never through a local bump. And vue is declared as a required peer (^3.5.0) even though upstream does not declare it — src/ uses useTemplateRef and useId, both Vue 3.5. Both facts are invariants in .sync/PORTING.md §2 and guarded by test/utils/peer-dependencies.spec.ts.
• Soon badge on docs headings: PRs that introduce a new feature or fix often add :badge{label="Soon" class="align-text-top"} to the relevant docs heading. This is intentional: the docs site redeploys on merge, but the feature only ships on the next npm release — the badge bridges that gap. Do NOT flag this as inconsistent in reviews. See documentation.md for details.
• Skill files live in skills/: Whenever a request mentions editing, adding, or refining a skill (SKILL.md, references, recipes, guidelines, layouts), modify the tracked tree under skills/<skill-name>/ — NOT under .claude/skills/ (which is gitignored and local-only). The exception is when the user explicitly names the .claude/skills/ path. If both copies exist, treat skills/ as the source of truth and ignore .claude/skills/. skills/index.json is generated — after adding, removing or renaming a file there, run pnpm run skill:sync rather than editing it by hand; test/utils/skill-manifest.spec.ts fails if the committed file is stale, because npx skills add installs exactly what it lists and an unlisted file is silently never delivered.