notion-design-system
Version:
A comprehensive Notion-inspired design system built with React, TypeScript, and Tailwind CSS
549 lines (431 loc) ā¢ 13.6 kB
Markdown
# Notion Design System
A comprehensive Notion-inspired design system built with React, TypeScript, and Tailwind CSS. This library provides a collection of reusable components that replicate the look and feel of Notion's interface.
## Features
- šØ **Notion-inspired Design**: Carefully crafted components that match Notion's visual style
- š **Dark Mode Support**: Built-in dark mode with seamless theme switching
- šÆ **TypeScript Support**: Fully typed components with excellent IntelliSense
- š¦ **Tree Shaking**: Optimized bundle size with ES modules
- š **Tailwind CSS**: Utility-first CSS framework integration
- š **Storybook**: Interactive component documentation
- āæ **Accessibility**: WCAG compliant components with proper ARIA attributes
## Installation
```bash
npm install notion-design-system
```
## Quick Start
### 1. Install the package and its peer dependencies
```bash
npm install notion-design-system react react-dom
```
### 2. Add Tailwind CSS to your project
If you don't have Tailwind CSS installed:
```bash
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p
```
### 3. Configure Tailwind CSS
Update your `tailwind.config.js` to include the Notion design system configuration:
```javascript
/** @type {import('tailwindcss').Config} */
module.exports = {
content: [
"./src/**/*.{js,ts,jsx,tsx}",
"./node_modules/notion-design-system/dist/**/*.js"
],
theme: {
extend: {
colors: {
notion: {
// Light theme colors
'bg-primary': '#ffffff',
'bg-secondary': '#f7f6f3',
'bg-tertiary': '#f1f1ef',
'text-primary': '#37352f',
'text-secondary': '#6f6e69',
'text-tertiary': '#9b9a97',
'border': '#e9e9e7',
'border-hover': '#d3d1cb',
// Dark theme colors
'dark-bg-primary': '#191919',
'dark-bg-secondary': '#2f3437',
'dark-bg-tertiary': '#373c41',
'dark-text-primary': '#ffffff',
'dark-text-secondary': '#9b9998',
'dark-text-tertiary': '#6f6e69',
'dark-border': '#373c41',
'dark-border-hover': '#4a5055',
// Accent colors
'blue': '#2383e2',
'blue-light': '#e7f3ff',
'blue-dark': '#1a6bb8',
'red': '#e03e3e',
'red-light': '#ffeaea',
'red-dark': '#b83232',
'yellow': '#ffb700',
'yellow-light': '#fff8e1',
'yellow-dark': '#cc9200',
'green': '#0f7b0f',
'green-light': '#e8f5e8',
'green-dark': '#0c5e0c',
'purple': '#9065b0',
'purple-light': '#f4f0f7',
'purple-dark': '#6b4884',
'pink': '#e255a1',
'pink-light': '#fdf0f8',
'pink-dark': '#b54081',
'orange': '#d9730d',
'orange-light': '#fef2e8',
'orange-dark': '#ad5a0a',
},
},
fontFamily: {
'notion': [
'ui-sans-serif',
'-apple-system',
'BlinkMacSystemFont',
'"Segoe UI"',
'Helvetica',
'"Apple Color Emoji"',
'Arial',
'sans-serif',
'"Segoe UI Emoji"',
'"Segoe UI Symbol"',
],
},
fontSize: {
'notion-xs': ['12px', '16px'],
'notion-sm': ['14px', '20px'],
'notion-base': ['16px', '24px'],
'notion-lg': ['18px', '28px'],
'notion-xl': ['20px', '28px'],
'notion-2xl': ['24px', '32px'],
'notion-3xl': ['30px', '36px'],
},
spacing: {
'notion-xs': '4px',
'notion-sm': '8px',
'notion-md': '12px',
'notion-lg': '16px',
'notion-xl': '24px',
'notion-2xl': '32px',
'notion-3xl': '48px',
},
borderRadius: {
'notion': '3px',
'notion-md': '6px',
'notion-lg': '8px',
},
boxShadow: {
'notion': '0 1px 3px rgba(15, 15, 15, 0.1)',
'notion-md': '0 4px 6px rgba(15, 15, 15, 0.1)',
'notion-lg': '0 10px 15px rgba(15, 15, 15, 0.1)',
'notion-hover': '0 2px 4px rgba(15, 15, 15, 0.15)',
},
},
},
plugins: [],
darkMode: 'class',
}
```
### 4. Add the CSS
Import the required styles in your main CSS file:
```css
@tailwind base;
@tailwind components;
@tailwind utilities;
@layer base {
body {
@apply bg-notion-bg-primary text-notion-text-primary font-notion;
font-feature-settings: "rlig" 1, "calt" 1;
}
.dark body {
@apply bg-notion-dark-bg-primary text-notion-dark-text-primary;
}
}
```
### 5. Start using components
```jsx
import { Button, Card, Typography } from '@sh20raj/notion-design-system';
function App() {
return (
<div className="p-4">
<Card className="max-w-md mx-auto">
<Typography variant="h1" className="mb-4">
Welcome to Notion Design System
</Typography>
<Typography variant="body" className="mb-4">
This is a sample implementation using the Notion-inspired components.
</Typography>
<Button variant="primary" size="md">
Get Started
</Button>
</Card>
</div>
);
}
```
## Available Components
### Button
Notion-style buttons with multiple variants and sizes.
```jsx
import { Button } from '@sh20raj/notion-design-system';
// Basic usage
<Button variant="primary" size="md">
Primary Button
</Button>
// With icon
<Button variant="secondary" size="sm" icon="plus">
Add Item
</Button>
```
### Card
Container component for grouping content.
```jsx
import { Card } from '@sh20raj/notion-design-system';
<Card className="p-4">
<p>Card content goes here</p>
</Card>
```
### Typography
Text components with consistent styling.
```jsx
import { Typography } from '@sh20raj/notion-design-system';
<Typography variant="h1">Main Heading</Typography>
<Typography variant="body">Body text</Typography>
<Typography variant="caption">Caption text</Typography>
```
### Input
Form input components with Notion styling.
```jsx
import { Input } from '@sh20raj/notion-design-system';
<Input
placeholder="Enter your text..."
value={value}
onChange={(e) => setValue(e.target.value)}
/>
```
### Avatar
User avatar component with fallback support.
```jsx
import { Avatar } from '@sh20raj/notion-design-system';
<Avatar
src="https://example.com/avatar.jpg"
alt="User Avatar"
size="md"
/>
```
### Badge
Small labels for status, categories, etc.
```jsx
import { Badge } from '@sh20raj/notion-design-system';
<Badge variant="success">Published</Badge>
<Badge variant="warning">Draft</Badge>
```
### Tooltip
Contextual information on hover.
```jsx
import { Tooltip } from '@sh20raj/notion-design-system';
<Tooltip content="This is a tooltip">
<button>Hover me</button>
</Tooltip>
```
### Sidebar
Navigation sidebar component.
```jsx
import { Sidebar } from '@sh20raj/notion-design-system';
<Sidebar>
<Sidebar.Item icon="home" active>
Home
</Sidebar.Item>
<Sidebar.Item icon="settings">
Settings
</Sidebar.Item>
</Sidebar>
```
### Block
Notion-style block component for content organization.
```jsx
import { Block } from '@sh20raj/notion-design-system';
<Block type="text">
This is a text block
</Block>
```
## Dark Mode
The components support dark mode out of the box. Toggle dark mode by adding the `dark` class to your root element:
```jsx
// Toggle dark mode
const toggleDarkMode = () => {
document.documentElement.classList.toggle('dark');
};
```
## TypeScript Support
All components are fully typed with TypeScript. You'll get excellent IntelliSense and type checking:
```tsx
import { Button, ButtonProps } from '@sh20raj/notion-design-system';
const CustomButton: React.FC<ButtonProps> = (props) => {
return <Button {...props} />;
};
```
## Customization
### Extending Colors
You can extend the color palette by adding custom colors to your Tailwind configuration:
```javascript
// tailwind.config.js
module.exports = {
theme: {
extend: {
colors: {
notion: {
// Add custom colors
'custom-blue': '#1e40af',
'custom-green': '#059669',
},
},
},
},
};
```
### Custom Styling
All components accept a `className` prop for custom styling:
```jsx
<Button className="my-custom-class bg-blue-500 hover:bg-blue-600">
Custom Styled Button
</Button>
```
## Storybook
Explore all components interactively in Storybook:
```bash
npm run storybook
```
## Contributing
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## License
MIT Ā© [Rovo Dev](https://github.com/rovo-dev)
## Support
- [GitHub Issues](https://github.com/shade-solutions/notion-design-system/issues)
- [Documentation](https://github.com/shade-solutions/notion-design-system#readme)
- [Storybook](https://rovo-dev.github.io/notion-design-system/)
- āæ **Accessibility** - WCAG compliant with keyboard navigation and screen reader support
- š§ **TypeScript** - Full type safety and excellent developer experience
- š **Storybook** - Comprehensive documentation and interactive examples
- šÆ **Customizable** - Easy theming with CSS custom properties
## š Quick Start
### Installation
```bash
npm install @sh20raj/notion-design-system
# or
yarn add @sh20raj/notion-design-system
# or
pnpm add @sh20raj/notion-design-system
```
### Basic Usage
```tsx
import { Button, Typography, Card } from '@sh20raj/notion-design-system';
import '@sh20raj/notion-design-system/dist/styles.css';
function App() {
return (
<Card>
<Typography variant="h2">Welcome to Notion</Typography>
<Typography variant="body1" color="gray">
Start building your next great idea.
</Typography>
<Button variant="primary">Get Started</Button>
</Card>
);
}
```
## š¦ Components
### Core Components
- **Button** - Various styles, sizes, and states
- **Input** - Text inputs with validation and icons
- **Typography** - Consistent text styling with multiple variants
- **Card** - Flexible content containers
- **Badge** - Labels, tags, and status indicators
### Notion-Specific Components
- **Block** - Editable content blocks (text, headings, lists, todos, toggles, quotes, code)
- **Sidebar** - Hierarchical navigation with search and nested items
## šØ Theming
The design system uses CSS custom properties for easy customization:
```css
:root {
/* Light theme */
--notion-bg-primary: #ffffff;
--notion-text-primary: #37352f;
--notion-blue: #2383e2;
/* Dark theme */
--notion-dark-bg-primary: #191919;
--notion-dark-text-primary: #ffffff;
}
.dark {
/* Dark theme variables are automatically applied */
}
```
## š Dark Mode
Toggle dark mode by adding the `dark` class to your root element:
```tsx
// Toggle dark mode
document.documentElement.classList.toggle('dark');
```
## š Development
### Prerequisites
- Node.js 16+
- npm, yarn, or pnpm
### Setup
```bash
# Clone the repository
git clone https://github.com/your-username/notion-design-system.git
cd notion-design-system
# Install dependencies
npm install
# Start Storybook
npm run storybook
```
### Available Scripts
- `npm run storybook` - Start Storybook development server
- `npm run build-storybook` - Build Storybook for production
- `npm run dev` - Start Next.js development server
- `npm run build` - Build for production
- `npm run lint` - Run ESLint
## šļø Project Structure
```
src/
āāā components/ # React components
ā āāā Button/ # Button component and stories
ā āāā Input/ # Input component and stories
ā āāā Typography/ # Typography component and stories
ā āāā Card/ # Card component and stories
ā āāā Badge/ # Badge component and stories
ā āāā Block/ # Block component and stories
ā āāā Sidebar/ # Sidebar component and stories
ā āāā index.ts # Component exports
āāā styles/ # Global styles and Tailwind config
āāā types/ # TypeScript type definitions
āāā stories/ # Storybook documentation stories
```
## š¤ Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
### Development Workflow
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Add tests and stories for new components
5. Commit your changes (`git commit -m 'Add amazing feature'`)
6. Push to the branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request
## š License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## š Acknowledgments
- Inspired by [Notion](https://notion.so)'s beautiful and functional design
- Built with [Storybook](https://storybook.js.org/) for component development
- Styled with [Tailwind CSS](https://tailwindcss.com/) for utility-first styling
- Icons from [Lucide React](https://lucide.dev/)
## š Support
- š [Documentation](https://your-storybook-url.com)
- š [Issue Tracker](https://github.com/your-username/notion-design-system/issues)
- š¬ [Discussions](https://github.com/your-username/notion-design-system/discussions)
---
Made with ā¤ļø by the Notion Design System team