@cere/cere-design-system 0.0.11 → 0.0.15

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/{.agent/rules/AGENTS.md → .specify/memory/architecture.md}

@@ -1,6 +1,4 @@
-# AGENTS.md
-
-This file provides guidance to WARP (warp.dev) when working with code in this repository.
+# architecture.md
 
 ## Project Overview
 

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();
+  });
+});
+```

package/{.agent/rules/COMPONENTS.md → .specify/memory/components-reference.md}

@@ -1,3 +1,5 @@
+# Cere Design System - Component Reference
+
 You are a senior UI developer with expertise in React, TypeScript, Material-UI, and the Cere Design System. 
 When building applications using this design system, follow these guidelines and use the components documented below.
 
@@ -1348,4 +1350,4 @@ All icons are React components that accept standard SVG props (width, height, co
     </Grid>
   </Grid>
 </Container>
-```
+```

package/.specify/memory/constitution.md

@@ -0,0 +1,295 @@
+# Cere Design System Constitution
+
+This constitution defines the immutable principles and standards that govern the development of the Cere Design System (@cere/cere-design-system). All components, features, and changes must comply with these articles.
+
+## Article I: Material UI Foundation
+
+**All components MUST extend Material UI components using `styled()` or `sx` prop patterns.**
+
+### Requirements
+- Components must be built on top of Material UI base components
+- Use MUI's `styled()` API from `@mui/material/styles` or the `sx` prop for styling
+- Components must support MUI's theming system and be compatible with `ThemeProvider`
+- Follow MUI's component API conventions (props, variants, sizes, event handlers)
+- Maintain backward compatibility with existing component APIs unless a major version bump is warranted
+
+### Rationale
+Material UI provides a battle-tested foundation with accessibility, theming, and responsive design built-in. Extending MUI ensures consistency and reduces maintenance burden.
+
+## Article II: Component Modularity
+
+**Each component must be self-contained, independently exportable, and follow the established file structure.**
+
+### Requirements
+- Each component must reside in its appropriate category folder under `src/components/`:
+    - `buttons/`, `inputs/`, `navigation/`, `layout/`, `feedback/`, `charts/`, `third-party/`, `utilities/`
+- Components must export both the component itself and its TypeScript type interfaces
+- All public exports must be registered in `src/index.ts` (both component and type exports)
+- Components must not have tight coupling; prefer composition patterns and prop-based configuration
+- Each component must be independently importable: `import { Button } from '@cere/cere-design-system'`
+
+### File Structure
+```
+src/components/[category]/
+├── [ComponentName].tsx         # Component implementation
+├── [ComponentName].stories.tsx # Storybook documentation
+└── __tests__/
+    └── [ComponentName].test.tsx # Jest tests
+```
+
+## Article III: Testing Standards (NON-NEGOTIABLE)
+
+**Every component MUST have comprehensive test coverage before being merged.**
+
+### Requirements
+1. **Jest Unit Tests** (in `__tests__/` subdirectory):
+    - Target: 80%+ code coverage
+    - Test rendering, user interactions, prop variants, callbacks, disabled/error states
+    - Use React Testing Library idioms (prefer `getByRole`, `getByLabelText`, user-event)
+    - Tests must wrap components with `ThemeProvider` using the design system theme
+
+2. **Storybook Stories** (with all variants/states documented):
+    - Create stories for all visual variants, sizes, and states
+    - Include interaction tests using `play` functions from `@storybook/test`
+    - Document props with JSDoc comments that appear in Storybook
+
+3. **Accessibility Tests**:
+    - Storybook integration with axe-playwright automatically checks accessibility
+    - Run via `npm run test:storybook`
+    - All interactive components must pass WCAG AA standards
+
+### Test Pattern
+```typescript
+import { render, screen } from '@testing-library/react';
+import { ThemeProvider } from '@mui/material/styles';
+import { theme } from '@/theme';
+
+const renderWithTheme = (component: React.ReactElement) => {
+  return render(
+    <ThemeProvider theme={theme}>
+      {component}
+    </ThemeProvider>
+  );
+};
+```
+
+## Article IV: Type Safety
+
+**All components must be written in TypeScript with explicit, strict type definitions.**
+
+### Requirements
+- All components must be written in TypeScript (`.tsx` files)
+- Export all prop interfaces with `Props` suffix (e.g., `ButtonProps`, `TextFieldProps`)
+- Use strict TypeScript configuration; avoid `any` types
+- Provide comprehensive JSDoc comments for all public APIs and prop interfaces
+- Type exports must be separate from component exports in `src/index.ts`:
+  ```typescript
+  export { Button } from './components/buttons/Button';
+  export type { ButtonProps } from './components/buttons/Button';
+  ```
+
+### Type Definition Pattern
+```typescript
+import type { ButtonProps as MuiButtonProps } from '@mui/material/Button';
+
+export interface ButtonProps extends Omit<MuiButtonProps, 'variant'> {
+  variant?: 'primary' | 'secondary' | 'tertiary';
+  // Custom props with JSDoc
+}
+```
+
+## Article V: Build System Integrity
+
+**The package build system must produce optimized, tree-shakeable outputs with proper peer dependencies.**
+
+### Requirements
+- Package builds via `tsup` producing:
+    - CommonJS format (`dist/index.js`)
+    - ESM format (`dist/index.mjs`)
+    - TypeScript declarations (`dist/index.d.ts`)
+- All React, MUI, Monaco, and ReactFlow packages must be peer dependencies (not bundled)
+- No new dependencies without evaluating if they should be peer dependencies
+- Entry point is `src/index.ts` - all public APIs must export through this single file
+- Build must complete without errors: `npm run build`
+- Type checking must pass: `npm run type-check`
+- Linting must pass: `npm run lint`
+
+### Peer Dependencies
+```json
+{
+  "peerDependencies": {
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0",
+    "@mui/material": "^5.0.0",
+    "@emotion/react": "^11.0.0",
+    "@emotion/styled": "^11.0.0"
+  }
+}
+```
+
+## Article VI: Documentation Requirements
+
+**Every component must have comprehensive, up-to-date documentation.**
+
+### Requirements
+1. **Storybook Documentation**:
+    - Every component must have a `.stories.tsx` file
+    - Stories must demonstrate all variants, sizes, and states
+    - Include interactive examples and code snippets
+
+2. **Component Reference**:
+    - Keep `.specify/memory/components-reference.md` synchronized with all component changes
+    - Document all props, usage examples, and best practices
+    - Update after every component addition or API change
+
+3. **Type Documentation**:
+    - Add JSDoc comments to all exported interfaces and components
+    - Document prop purposes, default values, and constraints
+
+4. **Versioning**:
+    - Breaking changes require version updates following semver (MAJOR.MINOR.PATCH)
+    - Maintain a changelog documenting all changes
+
+## Article VII: Design Consistency
+
+**All components must follow the design tokens defined in the theme.**
+
+### Design Tokens (Defined in `src/theme/index.ts`)
+- **Primary color**: `#1976d2` (blue)
+- **Border radius**:
+    - Inputs/buttons: `12px`
+    - Cards/chips: `16px`
+- **Typography**: Inter font family
+- **Component variants**: primary, secondary, tertiary (where applicable)
+- **Spacing**: Use theme's spacing system (`theme.spacing(n)` where n is a multiple of 8px)
+
+### Requirements
+- Components must reference theme tokens, not hardcoded values
+- Use `useTheme()` hook or `colors` import for accessing theme values
+- Maintain visual consistency across the design system
+- Responsive design using MUI Grid system or custom responsive hooks
+
+### Theme Usage Pattern
+```typescript
+import { useTheme } from '@mui/material/styles';
+import { colors } from '@cere/cere-design-system';
+
+const theme = useTheme();
+// Use: theme.palette.primary.main
+// Use: colors.primary.main
+// Use: theme.spacing(2) // 16px
+```
+
+## Article VIII: Accessibility First
+
+**All interactive components must be fully accessible to keyboard and assistive technology users.**
+
+### Requirements
+- All interactive components must be keyboard navigable (Tab, Enter, Space, Arrow keys)
+- Provide proper ARIA labels, roles, and live regions
+- Ensure color contrast meets WCAG AA standards (4.5:1 for normal text, 3:1 for large text)
+- Support screen readers and assistive technologies
+- Test with Storybook's axe-playwright integration
+- Focus management for dialogs, drawers, and modals
+
+### Accessibility Checklist
+- [ ] Keyboard navigation works correctly
+- [ ] ARIA attributes are present and accurate
+- [ ] Color contrast passes WCAG AA
+- [ ] Screen reader announces changes appropriately
+- [ ] Focus indicators are visible
+- [ ] No keyboard traps
+
+## Article IX: Third-Party Integration
+
+**Third-party component wrappers must provide typed interfaces and maintain clear boundaries.**
+
+### Requirements
+For wrappers around third-party libraries (e.g., FlowEditor wrapping ReactFlow, CodeEditor wrapping Monaco):
+
+1. **Type Safety**:
+    - Provide typed interfaces aligned with the underlying library
+    - Re-export commonly used types from the third-party library
+    - Make wrapper-specific props clearly distinct from pass-through props
+
+2. **Theme Integration**:
+    - Include theme integration where applicable
+    - Respect design system colors, typography, and spacing
+
+3. **Documentation**:
+    - Maintain clear documentation of wrapper-specific vs. pass-through props
+    - Document which third-party features are exposed vs. hidden
+    - Provide migration guides if wrapper APIs change
+
+4. **Peer Dependencies**:
+    - Third-party libraries must be peer dependencies
+    - Document minimum required versions
+
+### Example: FlowEditor
+```typescript
+import type { Node, Edge, ReactFlowInstance } from 'reactflow';
+
+export interface FlowEditorProps {
+  nodes: Node[];        // From reactflow
+  edges: Edge[];        // From reactflow
+  height?: string;      // Wrapper-specific
+  showBackground?: boolean;  // Wrapper-specific
+  // ... other props
+}
+
+// Re-export common types
+export type { Node, Edge, NodeTypes, EdgeTypes, ReactFlowInstance } from 'reactflow';
+```
+
+## Development Workflow
+
+### Component Development Process
+1. **Specification**: Create a feature spec using `/speckit.specify`
+2. **Planning**: Generate implementation plan using `/speckit.plan`
+3. **Task Breakdown**: Create task checklist using `/speckit.tasks`
+4. **Implementation**: Follow the tasks, adhering to all articles above
+5. **Validation**: Run all checks before PR:
+   ```bash
+   npm run type-check && npm run lint && npm run test && npm run build && npm run test:storybook
+   ```
+6. **Review**: Code review must verify constitutional compliance
+7. **Documentation**: Update `components-reference.md` before merging
+
+### Quality Gates
+All PRs must pass:
+- ✅ TypeScript compilation
+- ✅ ESLint checks
+- ✅ Jest tests (80%+ coverage)
+- ✅ Build succeeds
+- ✅ Storybook accessibility tests
+- ✅ Component reference updated
+- ✅ Constitutional compliance verified
+
+## Governance
+
+### Constitutional Supremacy
+- This constitution supersedes all other development practices and guidelines
+- When in conflict, the constitution takes precedence
+- All code reviews must verify compliance with these articles
+
+### Amendments
+- Constitutional amendments require:
+    1. Documented rationale for the change
+    2. Team approval/consensus
+    3. Migration plan for existing components if needed
+    4. Version update in this document
+
+### Non-Negotiable Articles
+- **Article III (Testing Standards)**: Cannot be waived or reduced
+- **Article VIII (Accessibility First)**: Cannot be compromised
+
+### Guidance Documents
+For detailed development patterns and examples, consult:
+- `.specify/memory/architecture.md` - Component architecture patterns
+- `.specify/memory/design-tokens.md` - Complete design token reference
+- `.specify/memory/workflow.md` - Step-by-step development workflow
+- `.specify/memory/components-reference.md` - Complete component API documentation
+
+---
+
+**Version**: 1.0.0 | **Ratified**: 2026-02-03 | **Last Amended**: 2026-02-03

package/.specify/memory/design-tokens.md

@@ -0,0 +1,139 @@
+# Cere Design System - Design Tokens
+
+## Color Palette
+
+### Primary Colors
+- Primary Main: `#1976d2` (blue)
+- Primary Light: `#42a5f5`
+- Primary Dark: `#1565c0`
+- Primary Contrast Text: `#ffffff`
+
+### Secondary Colors
+- Secondary Main: `#dc004e`
+- Secondary Light: `#f50057`
+- Secondary Dark: `#9a0036`
+- Secondary Contrast Text: `#ffffff`
+
+### Tertiary Colors
+- Tertiary Main: `#ff9800` (orange/amber)
+
+### Semantic Colors
+- Error: `#f44336`
+- Warning: `#ff9800`
+- Info: `#2196f3`
+- Success: `#4caf50`
+
+### Grey Scale
+- Grey 50: `#fafafa`
+- Grey 100: `#f5f5f5`
+- Grey 200: `#eeeeee`
+- Grey 300: `#e0e0e0`
+- Grey 400: `#bdbdbd`
+- Grey 500: `#9e9e9e`
+- Grey 600: `#757575`
+- Grey 700: `#616161`
+- Grey 800: `#424242`
+- Grey 900: `#212121`
+
+### Background
+- Default: `#fafafa`
+- Paper: `#ffffff`
+- Selected: `rgba(25, 118, 210, 0.08)`
+
+### Text
+- Primary: `rgba(0, 0, 0, 0.87)`
+- Secondary: `rgba(0, 0, 0, 0.6)`
+- Disabled: `rgba(0, 0, 0, 0.38)`
+
+## Typography
+
+### Font Family
+- Primary: `'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', sans-serif`
+
+### Font Weights
+- Light: 300
+- Regular: 400
+- Medium: 500
+- Semi-Bold: 600
+- Bold: 700
+
+### Type Scale
+- h1: 2.5rem (40px), weight: 700
+- h2: 2rem (32px), weight: 700
+- h3: 1.75rem (28px), weight: 600
+- h4: 1.5rem (24px), weight: 600
+- h5: 1.25rem (20px), weight: 600
+- h6: 1rem (16px), weight: 600
+- subtitle1: 1rem (16px), weight: 500
+- subtitle2: 0.875rem (14px), weight: 500
+- body1: 1rem (16px), weight: 400
+- body2: 0.875rem (14px), weight: 400
+- caption: 0.75rem (12px), weight: 400
+- button: 0.875rem (14px), weight: 500, uppercase
+- overline: 0.625rem (10px), weight: 400, uppercase
+
+## Spacing System
+Based on 8px scale:
+- 0: 0px
+- 1: 8px
+- 2: 16px
+- 3: 24px
+- 4: 32px
+- 5: 40px
+- 6: 48px
+- 7: 56px
+- 8: 64px
+- 9: 72px
+- 10: 80px
+
+## Border Radius
+- Small (inputs, buttons): 12px
+- Medium (cards, chips): 16px
+- Large: 24px
+- Circle: 50%
+
+## Elevation (Shadows)
+Follows Material Design elevation levels:
+- Level 0: none
+- Level 1: `0px 2px 4px rgba(0,0,0,0.1)`
+- Level 2: `0px 4px 8px rgba(0,0,0,0.1)`
+- Level 3: `0px 6px 12px rgba(0,0,0,0.1)`
+- Level 24: Maximum elevation
+
+## Breakpoints
+- xs: 0px (mobile)
+- sm: 600px (tablet)
+- md: 960px (desktop)
+- lg: 1280px (large desktop)
+- xl: 1920px (extra large)
+
+## Custom Breakpoint Hooks
+- `useIsMobile()`: < 768px
+- `useIsTablet()`: 768px - 1024px
+- `useIsDesktop()`: > 1024px
+
+## Transitions
+- Duration: 300ms (standard)
+- Easing: cubic-bezier(0.4, 0, 0.2, 1)
+
+## Z-Index Scale
+- Drawer: 1200
+- AppBar: 1100
+- Modal: 1300
+- Snackbar: 1400
+- Tooltip: 1500
+
+## Implementation
+All tokens are defined in `src/theme/index.ts` using MUI's `createTheme()`.
+Components should reference theme tokens, not hardcoded values.
+
+Example:
+```typescript
+import { useTheme } from '@mui/material';
+import { colors } from '@cere/cere-design-system';
+
+const theme = useTheme();
+// Use: theme.palette.primary.main
+// Use: colors.primary.main
+// Use: theme.spacing(2) // 16px
+```

package/.specify/memory/package-usage-guide.md

@@ -0,0 +1,99 @@
+# Using Cere Design System in Your Application's Spec Kit
+
+## Overview
+This guide shows how to reference and use the Cere Design System (@cere/cere-design-system) in your application's Spec-Driven Development workflow.
+
+## Installation
+```bash
+npm install @cere/cere-design-system
+```
+
+## Referencing in Your Application's Specs
+
+### Method 1: Direct Reference in Constitution
+In your application's `.specify/memory/constitution.md`, add an article requiring the design system:
+
+```markdown
+# Application Constitution
+
+## Article: UI Component Standards
+
+### Design System Requirement
+All UI components MUST use the Cere Design System (@cere/cere-design-system).
+
+### Component Reference
+Available components and their APIs are documented at:
+`node_modules/@cere/cere-design-system/.specify/memory/components-reference.md`
+
+All developers and AI agents MUST consult this reference before implementing UI features.
+
+### Usage Requirements
+1. Always wrap application with ThemeProvider:
+   ```tsx
+   import { ThemeProvider, theme } from '@cere/cere-design-system';
+   
+   <ThemeProvider theme={theme}>
+     <App />
+   </ThemeProvider>
+   ```
+
+2. Import components from the package:
+   ```tsx
+   import { Button, TextField, Card } from '@cere/cere-design-system';
+   import type { ButtonProps } from '@cere/cere-design-system';
+   ```
+```
+
+### Method 2: Create Design System Memory Reference
+Create `.specify/memory/design-system.md` in your application:
+
+```markdown
+# Cere Design System Reference
+
+This application uses @cere/cere-design-system
+
+## Quick Reference
+See complete component reference:
+`node_modules/@cere/cere-design-system/.specify/memory/components-reference.md`
+
+## Example Usage
+```tsx
+import { Card, TextField, LoadingButton, Alert } from '@cere/cere-design-system';
+
+<Card>
+  <CardContent>
+    <Stack spacing={2}>
+      <TextField label="Email" />
+      <LoadingButton variant="primary">Submit</LoadingButton>
+    </Stack>
+  </CardContent>
+</Card>
+```
+```
+
+## AI Agent Instructions
+
+When AI agents work on specs that use the Cere Design System:
+
+### 1. Always Reference Component Documentation
+Before suggesting code, agents should reference:
+`node_modules/@cere/cere-design-system/.specify/memory/components-reference.md`
+
+### 2. Follow Design System Patterns
+- Use ThemeProvider wrapper
+- Import components from package root
+- Use design system colors/theme tokens
+
+### 3. Type Safety
+Always import TypeScript types:
+```tsx
+import type { ButtonProps, TextFieldProps } from '@cere/cere-design-system';
+```
+
+## Best Practices Summary
+
+1. ✅ **Always reference** `components-reference.md` before using components
+2. ✅ **Import types** for TypeScript safety
+3. ✅ **Use ThemeProvider** at application root
+4. ✅ **Follow design system patterns** for consistency
+5. ✅ **Include design system requirements** in feature specs