@cere/cere-design-system 0.0.11 → 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/{.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

package/.specify/memory/toolkits.md

@@ -0,0 +1,57 @@
+# AI Coding Agent Toolkits for Material UI Design Systems
+
+## Supported Toolkits
+
+### 1. Material UI Component Generator (Primary)
+**Specialization:** MUI-based React component development
+**Use Cases:** Creating new components, extending MUI components
+**Configuration:**
+- Base library: @mui/material
+- Styling approach: styled-components + emotion
+- Theme system: MUI theming
+
+### 2. Storybook Documentation Toolkit
+**Specialization:** Component documentation and interaction testing
+**Use Cases:** Creating stories, play functions, a11y tests
+**Configuration:**
+- Framework: Storybook 7+
+- Testing: @storybook/test, axe-playwright
+
+### 3. Jest Testing Toolkit
+**Specialization:** Unit and integration testing
+**Use Cases:** Writing tests, achieving coverage targets
+**Configuration:**
+- Framework: Jest + React Testing Library
+- Coverage target: 80%+
+- Setup: src/setupTests.ts
+
+### 4. TypeScript Type System Toolkit
+**Specialization:** Type definitions and interfaces
+**Use Cases:** Creating types, ensuring type safety
+**Configuration:**
+- Strict mode: enabled
+- Export pattern: ComponentProps interfaces
+
+## Toolkit Selection Strategy
+Based on the feature type, select appropriate toolkit(s):
+
+| Feature Type | Primary Toolkit | Secondary Toolkits |
+|--------------|----------------|---------------------|
+| New Component | MUI Component Generator | Storybook, Jest, TypeScript |
+| Component Enhancement | MUI Component Generator | Jest, TypeScript |
+| Documentation | Storybook | - |
+| Testing | Jest | - |
+| Type Updates | TypeScript | - |
+| Integration | All | - |
+
+## Dynamic Loading
+Toolkits can be referenced in specs using:
+```yaml
+required_toolkits:
+  - mui-component-generator
+  - storybook-docs
+  - jest-testing
+  - typescript-types
+```
+
+The AI agent should activate appropriate context and specialized knowledge for each toolkit.

package/.specify/memory/workflow.md

@@ -0,0 +1,87 @@
+# Spec-Driven Development Workflow for Cere Design System
+
+## Workflow Phases
+
+### 1. Constitution (One-time Setup)
+Run once when starting spec-driven development:
+```bash
+/speckit.constitution
+```
+Review and customize the constitution to match team principles.
+
+### 2. Specify (Feature Definition)
+For each new component or feature:
+```bash
+/speckit.specify Create a [ComponentName] component that...
+```
+
+This creates:
+- New git branch: `001-component-name`
+- Spec file: `specs/001-component-name/spec.md`
+- Populates spec from template with feature details
+
+**Review the spec:**
+- Verify component category
+- Confirm Material UI base component
+- Review props interface
+- Validate accessibility requirements
+
+### 3. Plan (Technical Design)
+After spec is approved:
+```bash
+/speckit.plan
+```
+
+This creates:
+- Plan file: `specs/001-component-name/plan.md`
+- Technical implementation details
+- Phase-by-phase breakdown
+
+### 4. Tasks (Implementation Breakdown)
+After plan is approved:
+```bash
+/speckit.tasks
+```
+
+This creates:
+- Tasks file: `specs/001-component-name/tasks.md`
+- Granular checklist of implementation steps
+
+### 5. Implement (Execution)
+Work through tasks systematically:
+
+**Setup Phase:**
+- Create component file
+- Create test file
+- Create story file
+
+**Implementation Phase:**
+- Define TypeScript interfaces
+- Implement component logic
+- Add theme integration
+
+**Testing Phase:**
+- Write unit tests
+- Create Storybook stories
+- Run accessibility checks
+
+**Validation Phase:**
+```bash
+npm run type-check && npm run lint && npm test && npm run build && npm run test:storybook
+```
+
+### 6. Review (Quality Assurance)
+- Code review on PR
+- Visual design review in Storybook
+- Accessibility audit results
+
+### 7. Merge & Document
+- Merge feature branch to main
+- Update package version if needed
+- Update changelog
+
+## Best Practices
+1. Always start with a spec - don't code directly
+2. One component per spec/branch
+3. Keep specs focused and atomic
+4. Update components-reference.md after merging

package/README.md

@@ -201,6 +201,141 @@ npm run lint
 - **Warning**: Orange/Yellow (#F59E0B)
 - **Tertiary**: Orange/Yellow (#F59E0B)
 
+## Spec-Driven Development
+
+This project uses [GitHub Spec Kit](https://github.com/github/spec-kit) (`specify-cli`) for spec-driven development - a methodology where every feature starts with a specification document before implementation.
+
+### What is Spec-Driven Development?
+
+Spec-Driven Development (SDD) is a structured approach to software development where:
+1. **Specs define features** - Write clear specifications before coding
+2. **Plans outline architecture** - Technical designs guide implementation
+3. **Tasks break down work** - Granular checklists ensure completeness
+4. **AI agents assist** - Specs provide context for AI-powered development
+
+This ensures consistency, clarity, and maintainability across the entire design system.
+
+### Using Specify CLI
+
+Install `specify-cli` (recommended via `uv`):
+```bash
+uv tool install specify-cli
+```
+
+Or with pipx/npm:
+```bash
+pipx install specify-cli
+# or
+npm install -g specify-cli
+```
+
+### Development Workflow
+
+#### 1. **Create a Specification**
+Use AI agents (Cursor, Warp, Claude, etc.) with the `/speckit.specify` command:
+```bash
+/speckit.specify Create a [ComponentName] component that [does something]
+```
+
+This creates:
+- New git branch: `001-component-name`
+- Spec file: `specs/001-component-name/spec.md`
+- Populated template with requirements, APIs, and acceptance criteria
+
+#### 2. **Generate Implementation Plan**
+After spec approval:
+```bash
+/speckit.plan
+```
+
+Creates `specs/001-component-name/plan.md` with:
+- Technical architecture decisions
+- Implementation phases
+- Dependencies and considerations
+
+#### 3. **Break Down into Tasks**
+After plan approval:
+```bash
+/speckit.tasks
+```
+
+Creates `specs/001-component-name/tasks.md` with:
+- Granular implementation checklist
+- Testing requirements
+- Documentation updates
+
+#### 4. **Implement & Validate**
+Follow the tasks checklist and validate:
+```bash
+npm run type-check && npm run lint && npm test && npm run build
+```
+
+### Key Files
+
+- `.specify/memory/constitution.md` - Project governing principles
+- `.specify/memory/components-reference.md` - Complete component API reference
+- `.specify/memory/workflow.md` - Step-by-step development workflow
+- `.specify/memory/package-usage-guide.md` - How to use this package in other projects
+- `.specify/templates/` - Spec, plan, and task templates
+- `specs/` - Feature specifications and implementation plans
+
+### Using This Package in Your Application's SpecKit
+
+If you're building an application that uses this design system and also uses Spec Kit, you can reference the design system's component documentation in your specs and AI agent context.
+
+#### Method 1: Reference in Your Constitution
+
+Add to your application's `.specify/memory/constitution.md`:
+
+```markdown
+## 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.
+```
+
+#### Method 2: Create a Design System Memory File
+
+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`
+
+Also see package usage guide:
+`node_modules/@cere/cere-design-system/.specify/memory/package-usage-guide.md`
+
+## Installation & Setup
+```tsx
+import { ThemeProvider, theme } from '@cere/cere-design-system';
+import { Button, TextField, Card } from '@cere/cere-design-system';
+
+<ThemeProvider theme={theme}>
+  <App />
+</ThemeProvider>
+```
+```
+
+#### AI Agent Instructions
+
+When AI agents work on your application specs:
+1. They can reference `components-reference.md` for complete component APIs
+2. They should follow design system patterns and use existing components
+3. They get TypeScript types and usage examples from the reference
+
+See `.specify/memory/package-usage-guide.md` (included in the npm package) for detailed integration instructions.
+
 ## Documentation
 
 - [Full Components Reference](./COMPONENTS.md) - Complete API documentation
@@ -236,6 +371,35 @@ Paste the output into your AI conversation to give the agent complete knowledge
 
 See [.agent/README.md](./.agent/README.md) for detailed setup instructions and examples.
 
+## AI-Assisted Development
+
+This design system includes comprehensive AI agent context to accelerate development with AI coding assistants.
+
+### For AI Agents (Cursor, Claude, GPT-4, etc.)
+
+The package includes a complete component reference optimized for AI agents at `.agent/rules/COMPONENTS.md`.
+
+**Quick Start:**
+```bash
+# After installing the package
+cat node_modules/@cere/cere-design-system/.agent/rules/COMPONENTS.md
+```
+
+Paste the output into your AI conversation to give the agent complete knowledge of:
+- All 70+ available components
+- Props and TypeScript types
+- Usage examples and patterns
+- Theme configuration
+- Best practices
+
+**Setup Methods:**
+
+1. **Direct reference** - Copy the file content into your AI conversation
+2. **Project rules** - Add to `.cursorrules` or `.agent/rules/`
+3. **Auto-inject** - Use a postinstall script to copy to your project
+
+See [.agent/README.md](./.agent/README.md) for detailed setup instructions and examples.
+
 ## Integration with Existing Projects
 
 To use this package in `dynamic-indexer-client` or other projects:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cere/cere-design-system",
-  "version": "0.0.11",
+  "version": "0.0.13",
   "description": "Cere Network Design System - UI component library built with Material UI and React",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -14,7 +14,7 @@
   },
   "files": [
     "dist",
-    ".agent"
+    ".specify/memory"
   ],
   "scripts": {
     "build": "tsup",

package/.agent/README.md

@@ -1,154 +0,0 @@
-# Cere Design System - AI Agent Context
-
-This folder contains documentation and context optimized for AI agents to effectively work with the Cere Design System.
-
-## Files
-
-### `rules/COMPONENTS.md`
-**Comprehensive component reference** for AI agents building applications with the Cere Design System.
-
-This file provides:
-- Complete listing of all 70+ available components
-- Detailed props and usage examples for each component
-- TypeScript type information
-- Theme and styling guidelines
-- Best practices and common patterns
-- Installation and setup instructions
-
-**Use Case:** Feed this document to AI agents (like Claude, GPT-4, etc.) as context when building React applications. The agent will have immediate access to all component APIs, props, and usage patterns without needing to search documentation or source code.
-
-### `rules/AGENTS.md`
-Development guidelines and architecture documentation for AI agents working on the design system codebase itself.
-
-### `rules/guidelines.md`
-General coding guidelines and conventions.
-
-## Usage Examples
-
-### For Building Applications
-
-When using an AI agent to build a React application with the Cere Design System:
-
-1. **Include the context**: Upload or paste `rules/COMPONENTS.md` into your AI conversation
-2. **Reference components**: Ask the agent to build UI using specific components from the design system
-3. **Get accurate code**: The agent will generate TypeScript/React code with correct imports, props, and patterns
-
-Example prompts:
-```
-"Build a login form using TextField, LoadingButton, and Alert components"
-"Create a dashboard with Grid, Card, ChartWidget, and MetricsChart"
-"Implement a data table with pagination using Table and Pagination components"
-```
-
-#### Injecting Context into Project Prompts
-
-You can provide the component reference to AI agents in several ways:
-
-**Method 1: Direct File Reference (Recommended)**
-```bash
-# After installing the package, reference the file directly
-cat node_modules/@cere/cere-design-system/.agent/rules/COMPONENTS.md
-```
-
-Then paste the output into your AI conversation or include it in your project's AI configuration.
-
-**Method 2: Project .cursorrules or .agent Files**
-
-Create a rule file in your project root that references the design system components:
-
-`.cursorrules` or `.agent/rules/design-system.md`:
-```markdown
-# Design System Components
-
-When building UI components, use the Cere Design System.
-
-Available components reference:
-
-{PASTE CONTENTS OF node_modules/@cere/cere-design-system/.agent/rules/COMPONENTS.md HERE}
-```
-
-**Method 3: Dynamic Import Script**
-
-Create a script to automatically inject the context:
-
-`scripts/inject-design-system-context.sh`:
-```bash
-#!/bin/bash
-# Inject Cere Design System component reference into project AI context
-
-COMPONENTS_FILE="node_modules/@cere/cere-design-system/.agent/rules/COMPONENTS.md"
-OUTPUT_FILE=".agent/rules/cere-components.md"
-
-if [ -f "$COMPONENTS_FILE" ]; then
-  echo "Copying Cere Design System component reference..."
-  mkdir -p .agent/rules
-  cp "$COMPONENTS_FILE" "$OUTPUT_FILE"
-  echo "✓ Component reference available at $OUTPUT_FILE"
-else
-  echo "Error: Design system not found. Run 'npm install' first."
-  exit 1
-fi
-```
-
-Make it executable and run after installation:
-```bash
-chmod +x scripts/inject-design-system-context.sh
-npm install && ./scripts/inject-design-system-context.sh
-```
-
-**Method 4: Package.json Postinstall Hook**
-
-Automatically copy the component reference after package installation:
-
-`package.json`:
-```json
-{
-  "scripts": {
-    "postinstall": "mkdir -p .agent/rules && cp node_modules/@cere/cere-design-system/.agent/rules/COMPONENTS.md .agent/rules/cere-components.md || true"
-  }
-}
-```
-
-**Method 5: AI Tool Configuration**
-
-For tools like Cursor, Cline, or Windsurf, add to your configuration:
-
-`.cursor/rules` or `.windsurfrules`:
-```
-When building React components, always use components from @cere/cere-design-system.
-Refer to the complete component API documentation at:
-node_modules/@cere/cere-design-system/.agent/rules/COMPONENTS.md
-```
-
-### For Package Installation
-
-After installing the package:
-```bash
-npm install @cere/cere-design-system
-```
-
-The `.agent` folder will be available at:
-```
-node_modules/@cere/cere-design-system/.agent/
-```
-
-You can reference it in AI agent contexts or documentation tools.
-
-## Benefits
-
-- **Faster Development**: AI agents have immediate access to all component APIs
-- **Consistency**: Ensures AI-generated code follows design system patterns
-- **Type Safety**: All TypeScript types and interfaces are documented
-- **Best Practices**: Common patterns and usage guidelines included
-- **Complete Reference**: No need to browse Storybook or source code during AI-assisted development
-
-## Updating
-
-This documentation is maintained alongside the component source code. When components are added or updated, the `COMPONENTS.md` file should be updated to reflect the changes.
-
-## Package Information
-
-- **Package**: `@cere/cere-design-system`
-- **Version**: 0.0.10
-- **Repository**: https://github.com/cere-io/cere-design-system
-- **License**: MIT

package/.agent/rules/guidelines.md

@@ -1,111 +0,0 @@
-### Cere Design System — Development Guidelines (Material UI, Vite, Storybook, Jest)
-
-These notes capture project-specific details for developing this Material UI–based design system. Components should be implemented first, then covered with comprehensive tests. They complement README/TESTING docs with nuances from this repo's configuration.
-
-#### Build and Configuration
-- Build tool: `tsup`
-  - Entry: `src/index.ts`
-  - Formats: CJS + ESM, with type declarations (`dts: true`)
-  - Externalized peer deps to keep bundle lean: `react`, `react-dom`, `@mui/*`, `@emotion/*`, `reactflow`, `@monaco-editor/react`
-  - Command: `npm run build`
-- Type checking: `npm run type-check` (and `npm run check-types:ci` in CI)
-- Linting: `npm run lint` or `npm run lint:fix`
-- Vite (for Storybook and local tooling): minimal plugin setup in `vite.config.ts`
-- Package entrypoints are defined in `package.json` `exports`, with `main/module/types` pointing to `dist/*`
-- Peer dependencies (must be present in consumer app and in local dev):
-  - `@emotion/react`, `@emotion/styled`, `@mui/material`, `@mui/icons-material`, `@mui/lab`, `react`, `react-dom`, plus `reactflow`, `@monaco-editor/react` for third-party components
-
-#### Storybook Setup (Vite)
-- Start: `npm run storybook`
-- Build: `npm run build-storybook`
-- Customizations in `.storybook/main.ts`:
-  - CSS modules `localsConvention: 'camelCase'` to align class name access patterns
-  - `optimizeDeps.include` for `@monaco-editor/react`, `reactflow`, `monaco-editor`
-  - `define: { 'process.env': {} }` to satisfy Monaco in Vite/Storybook
-- Accessibility: `.storybook/test-runner.ts` integrates `@axe-core/playwright` checks for every story root (`#storybook-root`). Run with `npm run test:storybook`.
-
-#### Jest and RTL Configuration
-- Jest setup in `jest.config.js`:
-  - Preset: `ts-jest`
-  - Environment: `jsdom`
-  - Roots: `<rootDir>/src`
-  - Test discovery: `**/__tests__/**/*.test.{ts,tsx}` and `**/*.test.{ts,tsx}` under `src/`
-  - Path alias: `^@/(.*)$ -> <rootDir>/src/$1`
-  - CSS modules auto-mocked via `identity-obj-proxy`
-  - Coverage excludes stories, test files, `src/index.ts`, and type decls
-  - Transform configured to ensure `jsx: 'react-jsx'`
-- Test setup file: `src/setupTests.ts`
-  - Imports `@testing-library/jest-dom`
-  - Mocks `window.matchMedia` (important for MUI internals and components using media queries)
-- Commands:
-  - All tests: `npm test`
-  - Watch: `npm run test:watch`
-  - Coverage: `npm run test:coverage`
-  - CI mode: `npm run test:ci`
-
-#### Verified test run (local sanity)
-A minimal Jest test was added temporarily at `src/__tests__/sanity.test.ts` and executed with:
-```
-npm test -- src/__tests__/sanity.test.ts
-```
-It passed (`1 passed`). The file was removed after verification to keep the repo clean. Use this pattern to quickly validate the test harness when needed.
-
-#### Writing Tests (Pragmatic Workflow)
-- Principle: Implement components first, then write comprehensive tests to ensure quality and prevent regressions.
-- Where to put tests:
-  - Preferred: colocate under the component area using `__tests__` with `*.test.tsx` naming. Example: `src/components/layout/__tests__/Avatar.test.tsx`
-  - Alternatively: place a direct `*.test.tsx` beside the component; Jest will still pick it up.
-- Wrap components with theme in tests:
-```
-import { ThemeProvider } from '@mui/material';
-import { theme } from '@/theme';
-import { render } from '@testing-library/react';
-
-const renderWithTheme = (ui: React.ReactElement) =>
-  render(<ThemeProvider theme={theme}>{ui}</ThemeProvider>);
-```
-- Use React Testing Library idioms:
-  - Prefer `getByRole`, `getByText`, `getByLabelText` and user-level interactions via `@testing-library/user-event`
-  - Use `@testing-library/jest-dom` matchers (already configured)
-- Snapshot testing: Avoid broad snapshots for MUI; assert semantics and key props/attributes instead
-- Accessibility: Validate roles, names, disabled state, focus management
-- Example patterns already in repo: see `src/components/**/__tests__/*.test.tsx` (e.g., `Avatar.test.tsx`)
-
-#### Adding Storybook Interaction Tests
-- Add `play` functions to stories using `@storybook/test` utilities (e.g., `within`, `userEvent`)
-- Run with: `npm run test:storybook`
-- These tests also run automatic axe accessibility checks via the configured test runner
-
-#### Component Authoring Conventions
-- Material UI theming
-  - Use the shared `theme` from `src/theme` and expose component tokens via theme when practical
-  - Respect MUI variants/sizes; provide sensible defaults and typed props
-- Public exports
-  - Ensure all new components are exported from `src/index.ts` and surfaced in the package
-- CSS and classNames
-  - MUI’s `sx` and `styled` utilities are preferred; if class-based styling is necessary, remember Storybook’s CSS module config uses camelCase
-- Third-party components
-  - If components integrate `reactflow` or `@monaco-editor/react`, keep their imports dynamic-friendly and avoid relying on Node globals; Storybook’s `process.env` shim is in place
-
-#### Common Pitfalls and Fixes
-- matchMedia not defined in JSDOM
-  - Already handled in `src/setupTests.ts`. If adding features that rely on different media APIs, extend this mock
-- Failing to wrap with ThemeProvider in tests
-  - Most MUI components require theme context; tests should wrap components with `ThemeProvider`
-- Missing peer dependencies in consumer app or local dev
-  - Install all listed peer deps to avoid runtime errors
-- Class name expectations
-  - RTL queries should target roles and text over MUI-generated class names; class selectors may be brittle across MUI versions
-
-#### Release Hygiene
-- Run `npm run type-check && npm run lint && npm test && npm run build` before publishing
-- Storybook should render locally (`npm run storybook`) for visual checks; optionally run `npm run test:storybook` for a11y/interaction coverage
-
-#### Quick Development Loop
-1) Implement component following existing patterns and conventions
-2) Create Storybook story with all variants and states
-3) Write comprehensive tests under the component's `__tests__` folder
-4) Run `npm test -- componentPathOrPattern` to verify coverage
-5) Add `play` interaction tests to Storybook stories if relevant
-6) Verify accessibility with `npm run test:storybook`
-