@cere/cere-design-system 0.0.9 → 0.0.13

package/.specify/memory/agent-factory.md

@@ -0,0 +1,44 @@
+# Multi-Agent Factory Pattern
+
+## Purpose
+Allow different AI coding agents (Warp, Claude Code, Cursor, Copilot, etc.) to work with this design system using standardized interfaces while leveraging agent-specific capabilities.
+
+## Agent Capabilities Matrix
+
+| Agent | Strengths | Best For |
+|-------|-----------|----------|
+| Warp Agent Mode | Shell integration, file operations | Build automation, testing workflows |
+| Claude Code | Long context, complex reasoning | Architecture, refactoring, documentation |
+| GitHub Copilot | Code completion, patterns | Rapid prototyping, boilerplate |
+| Cursor | IDE integration, inline edits | Component implementation, quick fixes |
+
+## Agent Configuration Files
+Spec Kit supports multiple agents through dedicated command files:
+- `.claude/` - Claude-specific commands
+- `.github/copilot-instructions.md` - Copilot context
+- `.cursor/rules` - Cursor IDE rules
+- `.warp/` - Warp agent configuration
+
+All agents should reference:
+- `.specify/memory/constitution.md` - Core principles
+- `.specify/memory/toolkits.md` - Available toolkits
+- `.specify/templates/` - Spec templates
+
+## Pluggable Toolkit Loading
+Each spec can declare required toolkits in frontmatter:
+```yaml
+---
+toolkits:
+  - mui-component-generator
+  - storybook-docs
+agent_hints:
+  preferred: claude
+  complexity: high
+---
+```
+
+Agents read this metadata and activate appropriate specialized knowledge.
+
+## Implementation
+No code changes required - this is a documentation and organizational pattern.
+Agents interpret these files as context when working on specs.

package/.specify/memory/architecture.md

@@ -0,0 +1,143 @@
+# architecture.md
+
+## Project Overview
+
+This is a React-based design system library built with Material UI and TypeScript. It's distributed as an npm package (@cere/cere-design-system) containing 40+ reusable UI components organized into categories: buttons, inputs, navigation, layout, and feedback components. The library also includes third-party integrations for ReactFlow (FlowEditor) and Monaco Editor (CodeEditor).
+
+## Architecture
+
+### Component Structure
+- All components are in `src/components/` organized by category:
+  - `buttons/` - Button, IconButton, LoadingButton, ButtonGroup
+  - `inputs/` - TextField, SearchField, Dropdown, Switch, Checkbox, Radio, ToggleButton
+  - `navigation/` - Sidebar, Tab, Menu, Pagination, Selector, Stepper
+  - `layout/` - Dialog, Drawer, Card, List, Avatar, Table, Grid, AppBar, Paper, etc.
+  - `feedback/` - Badge, Chip, Tooltip, Progress, Alert, EmptyState, Loading
+  - `third-party/` - FlowEditor (ReactFlow wrapper), CodeEditor (Monaco wrapper)
+
+### Component Pattern
+Each component follows this structure:
+- Main component file (e.g., `Button.tsx`) exports component and TypeScript types
+- Storybook story file (e.g., `Button.stories.tsx`) for documentation/testing
+- Jest test file in `__tests__/` subdirectory (e.g., `__tests__/Button.test.tsx`)
+- Components use styled MUI components, not custom CSS files
+
+### Theme System
+- Theme defined in `src/theme/index.ts` using Material UI's `createTheme()`
+- Primary color: #1976d2 (blue, not purple as README mentions)
+- Export both `theme` and `colors` objects from theme file
+- Components extend MUI components with custom styled variants (primary, secondary, tertiary)
+- Border radius: 12px for inputs/buttons, 16px for cards/chips
+- Typography: Inter font family, specific font weights/sizes for each variant
+
+### Build System
+- Uses `tsup` for bundling (see `tsup.config.ts`)
+- Outputs CommonJS (`dist/index.js`), ESM (`dist/index.mjs`), and TypeScript declarations (`dist/index.d.ts`)
+- All React, MUI, Monaco, and ReactFlow packages are marked as external dependencies (peer dependencies)
+- Entry point: `src/index.ts` - ALL exports must be added here
+
+## Development Commands
+
+### Build & Development
+```bash
+# Build the library (produces dist/ folder)
+npm run build
+
+# Build in watch mode
+npm run dev
+
+# Run Storybook for component development
+npm run storybook
+
+# Build Storybook for deployment
+npm run build-storybook
+```
+
+### Testing
+```bash
+# Run Jest unit tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Generate coverage report
+npm run test:coverage
+
+# Run tests in CI mode
+npm run test:ci
+
+# Run Storybook interaction tests (includes a11y checks)
+npm run test:storybook
+```
+
+### Code Quality
+```bash
+# Run ESLint
+npm run lint
+
+# Fix ESLint issues automatically
+npm run lint:fix
+
+# TypeScript type checking
+npm run type-check
+
+# Type checking for CI
+npm run check-types:ci
+```
+
+## Testing Requirements
+
+### Test Structure
+- Unit tests: Use Jest + React Testing Library in `__tests__/` subdirectories
+- Interaction tests: Use Storybook's `play` function in `.stories.tsx` files
+- All components must wrap with `<ThemeProvider theme={theme}>` in tests
+- Standard test helper pattern:
+  ```tsx
+  const renderWithTheme = (component: React.ReactElement) => {
+    return render(<ThemeProvider theme={theme}>{component}</ThemeProvider>);
+  };
+  ```
+
+### Test Coverage
+- Target: 80%+ coverage for component logic
+- Test files should cover: rendering, user interactions, prop variants, callbacks, disabled/error states
+- Storybook Test Runner automatically runs accessibility (a11y) checks using axe-playwright
+
+## Adding New Components
+
+When adding new components:
+1. Create component file in appropriate category folder in `src/components/`
+2. Export component and TypeScript types (props interface)
+3. Add exports to `src/index.ts` (both component and type exports)
+4. Create Storybook story with examples of all variants/states
+5. Write Jest unit tests in `__tests__/` subdirectory
+6. Follow existing component patterns:
+   - Use MUI components as base, extend with `styled()`
+   - Support custom variants (primary, secondary, tertiary) where applicable
+   - Include proper TypeScript types and JSDoc comments
+   - Handle theme integration using `useTheme()` hook or `colors` import
+
+## Third-Party Components
+
+### FlowEditor (ReactFlow)
+- Wrapper around ReactFlow with theme integration
+- ReactFlow CSS imported in Storybook's preview.tsx
+- Custom props: height, showBackground, showControls, showMinimap
+- Re-exports commonly used ReactFlow types (Node, Edge, NodeTypes, etc.)
+
+### CodeEditor (Monaco)
+- Wrapper around Monaco Editor
+- Supports fullscreen mode, validation, type definitions injection
+- TypeScript configuration in `configureTypeScript()` function
+- Monaco loads from node_modules automatically (no loader configuration needed)
+- Supports multiple languages: typescript, javascript, json, yaml, python, etc.
+
+## Important Notes
+
+- This package uses peer dependencies - consumers must install React, MUI, ReactFlow, and Monaco themselves
+- Do NOT add new dependencies without considering if they should be peer dependencies
+- The package name is `@cere/cere-design-system`
+- When updating MUI components, ensure backward compatibility or update version appropriately
+- ESLint ignores: dist/, config files, and .stories files
+- Jest ignores: stories, test files, index.ts, and .d.ts files for coverage

package/.specify/memory/component-architecture.md

@@ -0,0 +1,73 @@
+# Component Architecture Patterns
+
+## File Structure Convention
+```
+src/
+├── components/
+│   ├── buttons/
+│   │   ├── Button.tsx
+│   │   ├── Button.stories.tsx
+│   │   └── __tests__/
+│   │       └── Button.test.tsx
+│   ├── inputs/
+│   ├── navigation/
+│   ├── layout/
+│   ├── feedback/
+│   ├── charts/
+│   ├── third-party/
+│   └── utilities/
+├── theme/
+│   └── index.ts (theme definition)
+├── hooks/
+│   └── useResponsive.ts
+└── index.ts (public API)
+```
+
+## Component Template Pattern
+```typescript
+import { styled } from '@mui/material/styles';
+import MuiButton from '@mui/material/Button';
+import type { ButtonProps as MuiButtonProps } from '@mui/material/Button';
+
+export interface ButtonProps extends Omit<MuiButtonProps, 'variant'> {
+  variant?: 'primary' | 'secondary' | 'tertiary';
+}
+
+const StyledButton = styled(MuiButton)<ButtonProps>(({ theme, variant }) => ({
+  borderRadius: theme.spacing(1.5),
+  ...(variant === 'primary' && {
+    // Primary styles
+  }),
+}));
+
+export const Button: React.FC<ButtonProps> = ({ variant = 'primary', ...props }) => {
+  return <StyledButton variant={variant} {...props} />;
+};
+```
+
+## Export Pattern
+All components must be exported from `src/index.ts`:
+```typescript
+export { Button } from './components/buttons/Button';
+export type { ButtonProps } from './components/buttons/Button';
+export { theme, colors } from './theme';
+```
+
+## Testing Pattern
+```typescript
+import { render, screen } from '@testing-library/react';
+import { ThemeProvider } from '@mui/material/styles';
+import { theme } from '@/theme';
+import { Button } from '../Button';
+
+const renderWithTheme = (component: React.ReactElement) => {
+  return render(<ThemeProvider theme={theme}>{component}</ThemeProvider>);
+};
+
+describe('Button', () => {
+  it('renders primary variant', () => {
+    renderWithTheme(<Button variant="primary">Test</Button>);
+    expect(screen.getByRole('button')).toBeInTheDocument();
+  });
+});
+```