@cere/cere-design-system 0.0.11 → 0.0.15

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,11 +201,156 @@ npm run lint
 - **Warning**: Orange/Yellow (#F59E0B)
 - **Tertiary**: Orange/Yellow (#F59E0B)
 
-## Documentation
+## Spec-Driven Development
 
-- [Full Components Reference](./COMPONENTS.md) - Complete API documentation
-- [Integration Guide](./INTEGRATION.md) - Step-by-step integration instructions
-- **[AI Agent Context](./.agent/README.md)** - Component reference optimized for AI agents (Claude, GPT-4, Cursor, etc.)
+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.
+```
+
+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.
 
 ## AI-Assisted Development