@cere/cere-design-system

v0.0.24

Published

2 days ago

Cere Network Design System - UI component library built with Material UI and React

0High
0Medium
0Low

cere-io

design-system ui-components material-ui react cere-network

Cere Design System

Cere Network Design System built with Material UI and React.

Installation

npm install @cere/cere-design-system

Usage

Basic Setup

Wrap your application with the ThemeProvider:

import { ThemeProvider } from '@mui/material';
import CssBaseline from '@mui/material/CssBaseline';
import { theme } from '@cere-network/cere-design-system';
import { Button, TextField } from '@cere-network/cere-design-system';

function App() {
  return (
    <ThemeProvider theme={theme}>
      <CssBaseline />
      <Button variant="primary">Click me</Button>
      <TextField label="Enter text" />
    </ThemeProvider>
  );
}

Using Components

import { 
  // Buttons
  Button,
  IconButton,
  // Inputs
  TextField,
  SearchField,
  Dropdown,
  Switch,
  Checkbox,
  Radio,
  ToggleButton,
  ToggleButtonGroup,
  // Navigation
  Sidebar,
  SidebarItem,
  Tab,
  Menu,
  MenuItem,
  Pagination,
  Selector,
  // Layout
  Dialog,
  Card,
  CardContent,
  List,
  ListItem,
  Avatar,
  Table,
  TableHeader,
  AppBar,
  Toolbar,
  Breadcrumbs,
  Accordion,
  Paper,
  Divider,
  Stack,
  Box,
  Typography,
  Link,
  Container,
  // Feedback
  Badge,
  Chip,
  Tooltip,
  Progress,
  Alert,
  Snackbar,
  EmptyState,
  Loading
} from '@cere-network/cere-design-system';

// Buttons
<Button variant="primary">Save</Button>
<IconButton variant="primary"><SettingsIcon /></IconButton>

// Inputs
<TextField label="Name" />
<SearchField placeholder="Search..." onSearch={(v) => console.log(v)} />
<Dropdown label="Select" options={[{ value: '1', label: 'Option 1' }]} />

// Navigation
<Sidebar items={[
  { label: 'Dashboard', icon: <DashboardIcon />, selected: true }
]} />
<Selector
  options={[{ id: '1', name: 'Service 1' }]}
  selectedId="1"
  onSelect={(id) => console.log(id)}
/>

// Layout
<Dialog open={true} title="Dialog" onClose={() => {}}>
  Content
</Dialog>
<Card hoverable clickable>
  <CardContent>Card content</CardContent>
</Card>
<AppBar>
  <Toolbar>Navigation</Toolbar>
</AppBar>

// Feedback
<Badge variant="primary" badgeContent={5}>Notifications</Badge>
<Alert severity="success">Success message</Alert>
<EmptyState title="No items" description="Create your first item" />

Development

# Install dependencies
npm install

# Run Storybook
npm run storybook

# Build package
npm run build

# Type checking
npm run type-check

# Linting
npm run lint

Components

Buttons (2)

Button - Primary, Secondary, Tertiary variants
- Sizes: small, medium, large
- Support for icons (start/end)
IconButton - Icon-only button with variants (default, primary, secondary)

Inputs (9)

TextField - Text input with validation states
SearchField - Search input with search icon
Dropdown - Select dropdown with options
Switch - Toggle switch with label positioning
Checkbox - Checkbox with label positioning and indeterminate state
Radio - Radio button with RadioGroup support
ToggleButton/ToggleButtonGroup - Toggle buttons for view modes
FormControl/FormLabel/FormHelperText - Form field wrappers

Navigation (6)

Sidebar/SidebarItem - Navigation sidebar with items (different sizes)
Tab - Tab component with badge support
Menu/MenuItem - Dropdown menu with icons and dividers
Pagination - Pagination controls
Selector - Universal selector with search, compact mode, and custom rendering

Layout (16)

Dialog - Modal dialog with actions and loading states
Card/CardContent/CardHeader/CardActions - Card container (hoverable, clickable)
List/ListItem - List with icons and actions
Avatar - Avatar with sizes (small, medium, large, custom)
Table/TableHeader - Table with sorting support
Grid - Grid layout system
AppBar/Toolbar - Top navigation bar
Breadcrumbs - Navigation breadcrumbs
Accordion - Expandable sections
Paper - Container with elevation or outline
Divider - Section divider
Stack - Flexbox layout component
Box - Universal container component
Typography - Text component
Link - Styled link component
Container - Centered container

Feedback (8)

Badge - Badge indicators (default, primary, success, error)
Chip - Chip component (default, active) with icons
Tooltip - Tooltip component
Progress - Linear and circular progress indicators
Alert/Snackbar - Alert messages and notifications
EmptyState - Empty state with icon and action
Loading - Loading spinner (fullScreen or inline)

Color Scheme

Primary: Purple (#7B2CBF)
Success: Green (#10B981)
Error: Red (#EF4444)
Warning: Orange/Yellow (#F59E0B)
Tertiary: Orange/Yellow (#F59E0B)

Spec-Driven Development

This project uses 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:

Specs define features - Write clear specifications before coding
Plans outline architecture - Technical designs guide implementation
Tasks break down work - Granular checklists ensure completeness
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):

uv tool install specify-cli

Or with pipx/npm:

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:

/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:

/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:

/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:

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:

## 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:

# 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:

Direct reference - Copy the file content into your AI conversation
Project rules - Add to .cursorrules or .agent/rules/
Auto-inject - Use a postinstall script to copy to your project

See .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:

# After installing the package
cat node_modules/@cere/cere-design-system/.agent/rules/COMPONENTS.md