Skip to content

Latest commit

 

History

History
83 lines (66 loc) · 3.61 KB

CLAUDE.md

File metadata and controls

83 lines (66 loc) · 3.61 KB

AI Agent Guidelines

UIID is a modular React component library. Follow these conventions to maintain consistency across the codebase.

Stack

  • React 19 with TypeScript 5.8
  • Vite 7 for builds
  • Base UI (@base-ui-components/react) for accessible primitives
  • CSS Modules with design tokens
  • pnpm workspaces + Turbo for monorepo management
  • Vitest for testing, Storybook for documentation

Monorepo Structure

design-system/
├── apps/
│   ├── docs/          # Documentation site
│   ├── blocks/        # AI-powered UI composer
│   └── storybook/     # Component documentation
├── packages/          # Component packages (@uiid/*)
│   ├── buttons/, cards/, forms/, layout/, typography/, ...
│   ├── registry/      # Component metadata for AI tools
│   └── tokens/        # Design tokens (JSON → CSS)
├── scripts/           # Token generation, changelog, registry scripts
├── .claude/
│   ├── guides/        # Detailed guides (imported below)
│   └── templates/     # Code templates for components, tests, stories, registry entries
└── docs/
    └── architecture/  # Architecture decision docs (token system, MCP server)

Root Config Files

File Purpose
vite.config.ts Shared Vite build config factory
vitest.config.ts Test configuration for all packages
vitest.setup.ts Test setup (jest-dom matchers)
tsconfig.json Base TypeScript config (packages extend it)
turbo.json Turbo task orchestration
eslint.config.js Shared ESLint configuration

Commit Policy

  • Never add yourself as co-author. Do not include Co-Authored-By trailers in commit messages. The repo owner maintains sole authorship of all commits.

Quick Reference

Task Command
Install dependencies pnpm install
Build all packages pnpm run build
Build single package pnpm run build --filter=@uiid/{package}
Run tests pnpm test:run
Run tests (watch) pnpm test
Start Storybook pnpm run storybook
Lint pnpm run lint

Core Guides (always loaded)

@.claude/guides/registry.md

On-Demand Guides

Read these files when the task requires them — do not import by default:

Guide Read when...
.claude/guides/components.md Building, modifying, or reviewing components
.claude/guides/styling.md Working with styles, layout, CSS modules, or design tokens
.claude/guides/testing.md Writing or reviewing tests
.claude/guides/storybook.md Creating or updating stories
.claude/guides/figma.md Building or inspecting Figma components
.claude/guides/pull-requests.md Creating a PR
.claude/guides/pull-reviews.md Reviewing a PR
.claude/guides/workflow.md Running the agent pipeline or grooming tickets
apps/blocks/BLOCKS_GUIDE.md Working on the blocks app (tree format, rules, patterns)
apps/blocks/COMPONENT_REFERENCE.md Looking up component props for block tree generation
apps/docs/DOCS_GUIDE.md Working on the documentation site