@cere/cere-design-system 0.0.9 → 0.0.13

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