Skip to content

AGENTS.md

Latest commit

 

History

History
133 lines (101 loc) · 4.81 KB

AGENTS.md

File metadata and controls

133 lines (101 loc) · 4.81 KB
Raw

Agent Guide

This file is the shared operating guide for AI coding agents working in this repository. Tool-specific files such as CLAUDE.md and CODEX.md should point back here instead of duplicating instructions.

Repository Shape

  • Root package: @open-ui-kit/monorepo
  • Published package: @open-ui-kit/core
  • Core library source: packages/open-ui-kit/src
  • Storybook config and stories: packages/open-ui-kit/.storybook and component stories files
  • Docs app: docs
  • Example consumer app: playground/vite-ts
  • Release packaging scripts: scripts

This repo uses Yarn 4, Turborepo, React, TypeScript, Material UI, Storybook, Jest, and semantic-release.

Important Branches

  • main is the primary release branch.
  • beta is a protected long-lived branch used for prereleases.
  • Do not delete beta.
  • Prefer dedicated short-lived branches for changes.

Common Commands

Use the root workspace unless a task explicitly needs a package directory.

yarn install --immutable
yarn typecheck
yarn lint
yarn test
yarn build
yarn storybook
yarn storybook:build
yarn docs:build

Focused core package commands:

yarn workspace @open-ui-kit/core typecheck
yarn workspace @open-ui-kit/core lint
yarn workspace @open-ui-kit/core test
yarn workspace @open-ui-kit/core storybook
yarn workspace @open-ui-kit/core storybook:build

Change Guidelines

  • Follow existing component, theme, Storybook, and docs patterns before introducing new ones.
  • Keep changes scoped to the requested area.
  • Add or update tests when changing behavior, public APIs, themes, or shared helpers.
  • Update Storybook stories and docs when component behavior, props, examples, or theme behavior changes.
  • Optional React component props should also accept undefined as a value to support exactOptionalPropertyTypes.
  • Do not edit generated build output such as docs/export, packages/open-ui-kit/dist, .next, or temporary QA output.
  • Do not manually edit yarn.lock unless dependency metadata changed through Yarn.
  • Prefer rg for repository search.

Components

Most component work belongs under packages/open-ui-kit/src/components/<component>.

Use the established component structure:

packages/open-ui-kit/src/components/<component>/
├── __tests__/
├── components/
│   ├── elements.tsx
│   └── <component>.tsx
├── stories/
│   └── <component>.stories.tsx
└── index.ts

When changing a component, check for:

  • component implementation
  • exported types
  • stories
  • tests
  • docs page under docs/data/material/components
  • docs route page under docs/pages/open-ui-kit-core
  • package barrel exports

Component visual styles should live with the component, usually in components/elements.tsx. Keep src/theme/mui/<component>.tsx only for true theme-level defaults that cannot safely live in the component. Remove empty theme override files and references.

Themes

Theme logic lives mainly in:

  • packages/open-ui-kit/src/theme
  • packages/open-ui-kit/src/theme-provider
  • packages/open-ui-kit/.storybook/preview.ts
  • docs theme integration under docs/src and docs/vendor/mui-internal-core-docs

The library currently supports direct theme modes, including Open UI Kit light/dark and IoC. Components should consume theme tokens through the existing theme vars and local style helpers, not hardcoded one-off colors.

When changing theme behavior, check:

  • theme vars and theme objects
  • ThemeProvider behavior
  • Storybook globals and backgrounds
  • docs theme controls and examples
  • representative component docs in light, dark, and IoC modes

Docs And Storybook

  • Docs site runs on port 3000.
  • Storybook runs on port 6006.
  • Published docs live at https://open-ui-kit.outshift.ai/.
  • Published Storybook is served from https://open-ui-kit.outshift.ai/storybook/.
  • Component docs Storybook links should deep-link to matching Storybook docs IDs.
  • Internal docs links generally require trailing slashes.

Release And CI

  • Releases are handled by semantic-release from .github/workflows/release.yml.
  • npm publishing uses Trusted Publishing/OIDC through release.yml.
  • Release commits are generated by semantic-release and should not be hand-edited.
  • PR titles must follow Conventional Commits.
  • A fix: PR can trigger a patch release when merged to main.
  • A feat: PR can trigger a minor release when merged to main.
  • ci:, docs:, and chore: changes usually do not publish a package release.

Safety Rules

  • Never revert user changes unless explicitly asked.
  • Never run destructive Git commands such as git reset --hard without explicit approval.
  • If the worktree is dirty, inspect changes before editing and keep unrelated work intact.
  • Prefer small, reviewable PRs.
  • If a branch-protection or release change is needed, verify the workflow behavior before merging.