An educational design system to teach developers how to build their own
Prism is not just another design system; it's a learning resource. Every architectural decision, pattern, and convention is documented to help you understand why design systems are built the way they are.
AI tools are excellent at generating UI — until your product needs to be yours. Companies like IBM (Carbon), Microsoft (Fluent), and Anthropic (Claude's UI) invest in design systems precisely because a shared visual language can't be prompt-engineered on the fly. When your team scales, or your brand needs to be consistent across dozens of surfaces, you need a foundation that's explicit, versioned, and owned.
That said, Prism fully embraces AI workflows. Drop llms.txt into your editor context and your AI assistant can generate new components that match your exact token values, naming conventions, and patterns — no hallucinated class names, no inconsistent spacing. The design system becomes the ruleset; AI becomes the speed multiplier.
Most design systems (Material-UI, Ant Design, Carbon) are production-ready but challenging to learn from. Their codebases are complex, and architectural decisions aren't always clear. Prism takes the opposite approach:
- Education First: Inline documentation explains the "why" behind every pattern
- Simple Architecture: Easy to understand, not over-engineered
- Progressive Complexity: Start simple, add complexity only when needed
- Real-World Patterns: Learn industry-standard practices used by major design systems
By studying and contributing to Prism, you'll understand:
The foundation of any design system
- Color systems and semantic naming
- Spacing scales and mathematical ratios
- Typography scales and font hierarchies
- API design patterns
- Composition vs configuration
- Polymorphic components
- Compound components
- CSS-in-JS vs CSS variables
- Light/dark mode implementation
- Custom theme creation
- ARIA patterns
- Keyboard navigation
- Screen reader support
- Focus management
- Monorepo management with Turborepo
- Package bundling with tsup
- Tree-shaking and code-splitting
- Publishing to npm
- Interactive documentation with Storybook
- Component API documentation
- Usage examples and patterns
This monorepo contains:
Core Packages:
@prism/tokens- Design tokens (colors, spacing, typography)@prism/core- Core utilities and types@prism/react- React component library
Applications:
apps/docs- Storybook documentation siteapps/examples- Real-world usage examples (planned)
Tooling:
@prism/typescript-config- Shared TypeScript configurations@prism/eslint-config- Shared ESLint configurations@prism/vitest-config- Shared Vitest testing configurations
- Turborepo - High-performance monorepo build system
- TypeScript - Type safety and developer experience
- React - Component framework
- tsup - Fast TypeScript bundler (powered by esbuild)
- Vitest - Unit testing framework
- Testing Library - Component testing utilities
- Storybook - Component documentation and development
- Tailwind CSS v4 - Utility-first CSS framework
- Changesets - Version management and changelogs
- pnpm - Fast, efficient package manager
- Node.js >= 18
- pnpm >= 8
# Clone the repository
git clone https://github.com/design-sparx/prism-designs.git
cd prism
# Install dependencies
pnpm install
# Build all packages
pnpm build
# Start Storybook in development mode
pnpm devVisit http://localhost:6006 to see the component documentation.
# Development
pnpm dev # Run all packages in watch mode + start Storybook
pnpm build # Build all packages (respects dependency order)
# Testing & Quality
pnpm lint # Lint all packages
pnpm format # Format code with Prettier
pnpm format:check # Check code formatting without modifying
# Package-specific commands
pnpm --filter @prism/react test # Run tests
pnpm --filter @prism/react test:watch # Watch mode
pnpm --filter @prism/react test:coverage # Generate coverage report
pnpm --filter @prism/tokens build # Build specific package
# Versioning & Publishing
pnpm changeset # Create a changeset for version bumping
pnpm version-packages # Update package versions based on changesets
pnpm release # Build and publish packages to npm
# Theme Generation
pnpm generate:theme # Regenerate Tailwind theme CSS from design tokens
# Cleanup
pnpm clean # Remove all node_modules and dist foldersprism/
├── apps/
│ ├── docs/ # Storybook documentation
│ │ ├── stories/ # Component stories
│ │ └── .storybook/ # Storybook configuration
│ └── examples/ # Real-world usage examples (planned)
│
├── packages/
│ ├── tokens/ # Design tokens
│ │ └── src/
│ │ ├── colors.ts # Color palette
│ │ ├── spacing.ts # Spacing scale
│ │ └── typography.ts # Font system
│ │
│ ├── core/ # Core utilities and types
│ │ └── src/
│ │ ├── utils.ts # Utility functions
│ │ └── types.ts # Shared TypeScript types
│ │
│ ├── react/ # React components
│ │ ├── src/
│ │ │ ├── components/ # Component implementations
│ │ │ ├── test/ # Shared test utilities
│ │ │ └── styles/ # Global styles & theme
│ │ └── TESTING.md # Testing guide
│ │
│ ├── eslint-config/ # Shared ESLint config
│ ├── typescript-config/ # Shared TypeScript config
│ └── vitest-config/ # Shared Vitest config
│
├── turbo.json # Turborepo configuration
├── package.json # Root package configuration
├── pnpm-workspace.yaml # pnpm workspace configuration
└── CLAUDE.md # Developer instructions for Claude Code
New here? Follow these steps in order. Each step builds on the previous one — don't skip ahead.
Goal: By the end you'll have built a component from scratch, tested it, and documented it in Storybook.
Run the project and see what you're building toward:
pnpm install && pnpm build && pnpm devOpen http://localhost:6006. Browse the components. This is your destination.
Tokens are the foundation. Everything else — components, themes, Tailwind classes — derives from them.
Create card.tsx, card.spec.tsx, index.ts, then apps/docs/stories/card.stories.tsx.
All components require tests with 80% coverage minimum. See packages/react/TESTING.md for:
- Testing setup and utilities
- Component testing patterns
- Accessibility testing
- Coverage requirements
# Run tests for React package
pnpm --filter @prism/react test
# Watch mode for active development
pnpm --filter @prism/react test:watch
# Generate coverage report
pnpm --filter @prism/react test:coverageContributions are welcome! This project is designed to be a learning resource, so:
- Add inline documentation explaining your decisions
- Keep it simple - avoid over-engineering
- Focus on education - prioritize clarity over cleverness
- Write tests - maintain the 80% coverage standard
- Follow conventions - use Conventional Commits format
This project uses Conventional Commits:
feat(button): add loading state
fix(tokens): correct spacing scale values
docs(readme): update installation instructions
chore(deps): update typescript to 5.5.4Git hooks automatically lint and format your code before commits.
Components are automatically discovered by the build system—no manual configuration needed:
- Add a component folder to
packages/react/src/components/ - Run
pnpm build - The build scripts auto-generate exports and configuration
Design tokens from @prism/tokens are automatically converted to Tailwind CSS custom properties:
- Single source of truth in TypeScript
- Generated CSS files for both React package and Storybook
- Full Tailwind v4 compatibility
Turborepo intelligently orchestrates builds:
- Respects package dependencies
- Caches unchanged outputs
- Parallel execution where possible
- Turborepo Documentation
- Design Tokens Specification
- Storybook Documentation
- TypeScript Handbook
- Vitest Documentation
- Testing Library
MIT – Feel free to use this for learning and building your own design systems!
Built to help developers learn design systems