Skip to content

AGENTS.md

Latest commit

 

History

History
114 lines (81 loc) · 7.56 KB

AGENTS.md

File metadata and controls

114 lines (81 loc) · 7.56 KB
Raw

AI Agent Reference — Cube UI Kit

Entry point for AI agents working on @cube-dev/ui-kit.

Maintenance note: The design-system reference (tokens, presets, colors, modifiers, state syntax, form system, icons) lives in src/stories/Usage.docs.mdx (Storybook → Getting Started / Usage). The component creation guide lives in src/stories/CreateComponent.docs.mdx (Getting Started / Create Component). Update these whenever you add components, change the API surface, or modify tokens/presets.

Rules

Project-specific working rules for AI agents. Not published with the package.

Changesets

When making code changes that affect end users or the public API, always add a new changeset or update an existing one in .changeset/ as part of the same task. Do not wait to be asked.

  • Prefer updating an existing open changeset that already covers the same work/PR; otherwise add a new .md file.
  • Use patch for bug fixes and small changes; minor for new features and noticeable breaking changes.
  • Keep the summary concise and user-focused ("@cube-dev/ui-kit": patch|minor frontmatter).
  • Skip changesets for docs-only, test-only, Storybook-only, or internal tooling that does not affect package consumers. Also skip fixes for issues introduced and resolved within the same PR.
  • Add changeset manually (no CLI) — full guidelines: .cursor/commands/add-changeset.md.

Project Structure

src/
├── components/        # actions, content, fields, form, layout, navigation,
│                      # organisms, overlays, status, helpers, portal, other, shared
├── icons/             # 130+ icon components
├── shared/            # Form types (FieldBaseProps, FormBaseProps, FieldCoreProps)
├── tokens/            # Design tokens (colors, typography, spacing, sizes, shadows, layout)
├── stories/           # Storybook guides and documentation pages
├── _internal/         # Internal hooks (useEvent, etc.)
├── tasty-augment.d.ts # TypeScript module augmentation for tasty
└── index.ts           # Public barrel export

Each component lives in src/components/{category}/{ComponentName}/ and ships ComponentName.tsx, .stories.tsx, .docs.mdx, .test.tsx, and index.tsx.

Commands

  • pnpm storybook — start Storybook on port 6060
  • pnpm build — build library (tsdown, unbundled ESM)
  • pnpm test — run all tests (Vitest); add -- ComponentName to filter, -u to update snapshots
  • pnpm fix — lint + format (Oxlint + Prettier)
  • pnpm size — check bundle size limits
  • pnpm chromatic — visual regression
  • pnpm add-icons — add new icons from tabler
  • pnpm audit-docs — audit component API ↔ docs ↔ argTypes sync. Options: --component=Name, --fix-stories, --fix-docs, --json, --verbose, --all-props. Run after changing a component's API or adding a new component.
  • pnpm run update-tasty / pnpm run update-glaze — bump and pin @tenphi/tasty or @tenphi/glaze to the latest version. Pass --version=X.Y.Z to pin a specific version.

Environment

  • Node >=22.0.0, pnpm ^10 (pinned to pnpm@10.32.0). The publish workflow (publish.yml) still runs on Node 24 because OIDC trusted publishing requires npm ≥ 11.5.1+, which Node 24 ships natively (Node 22 ships npm 10.x).
  • After pnpm install, run pnpm rebuild esbuild (postinstall is blocked in pnpm-workspace.yaml).
  • Husky hooks: pre-commit runs pnpm lint-staged; pre-push runs pnpm test. Skip only intentionally (--no-verify or HUSKY=0).
  • No external services or databases required for local development.

Tasty Documentation

Bundled in docs/tasty/ (symlinked from node_modules/@tenphi/tasty/docs in dev, copied at pack time by scripts/prepare-docs.mjs). Consult these when authoring components or working with style props:

Internal-only references (pipeline.md, injector.md), positioning material (comparison.md, adoption.md), and modes the UI Kit does not ship (tasty-static.md, ssr.md) are intentionally omitted; read them directly in docs/tasty/ if needed.

Glaze Documentation

Bundled in docs/glaze/ (same symlink/copy mechanism). Consult when working on color tokens, theme generation, or contrast tuning — Glaze powers src/tokens/palette.ts.

Stack

  • Styling: @tenphi/tasty (declarative token-aware CSS-in-JS)
  • Accessibility: react-aria + react-stately
  • Icons: @tabler/icons-react + custom icons in src/icons/
  • Testing: Vitest + React Testing Library + Chromatic
  • Build: tsdown (unbundled ESM, es2022)
  • Storybook: v10 (@storybook/react-vite)
  • React: 18 and 19 supported

Creating Components

See src/stories/CreateComponent.docs.mdx (Storybook → Getting Started / Create Component) for the full guide: styleProps vs extractStyles, filterBaseProps, modifiers, sub-elements, React Aria integration, variants, useEvent, and complete examples.

Design System Reference

See src/stories/Usage.docs.mdx (Storybook → Getting Started / Usage) for units, base/spacing/size/shadow/layout tokens, color tokens, typography presets, themes, recipes, modifiers, state syntax, icons, and the form system.

TypeScript & Exports

  • Module augmentation: src/tasty-augment.d.ts extends @tenphi/tasty with project-specific color tokens, preset names, and theme names.
  • Props naming: Cube{ComponentName}Props. Extend BaseProps/AllBaseProps from @tenphi/tasty; mix in style-prop interfaces (ContainerStyleProps, OuterStyleProps, ColorStyleProps, …) as needed. Form types live in src/shared/.
  • Barrel exports: every category has an index.ts; everything re-exports through src/index.ts.
  • Compound components: Object.assign(Button, { Group: ButtonGroup, Split: ButtonSplit }).
  • Tasty re-exports: only types are re-exported. Runtime imports (tasty, extractStyles, filterBaseProps) come directly from @tenphi/tasty.

Testing

  • Helpers: renderWithRoot (wraps with <Root>), renderWithForm (returns { formInstance, ...renderResult }).
  • QA selectors: qa prop → data-qa attribute → screen.getByTestId('name') (testIdAttribute is configured to data-qa).
  • Tasty snapshots: toMatchTastySnapshot() captures markup + CSS together.
  • Patterns: see docs/rules/tests.md.