openstatus.dev
Openstatus
www.openstatus.dev
1# Community Themes
2
3**Help us build epic status page themes!**
4
5This directory contains community-contributed themes for openstatus status pages. These themes allow users to customize the visual appearance of their status pages with different color schemes and design styles.
6
7## What are Community Themes?
8
9Community themes are predefined color schemes that users can apply to their status pages. Each theme includes:
10- **Light mode** colors for bright environments
11- **Dark mode** colors for low-light environments
12- **Consistent design** that works across all status page components
13- **Accessibility** considerations for better readability
14
15## Themes Examples
16
17- **Openstatus** - The standard openstatus theme
18- **Openstatus (Rounded)** - The rounded openstatus theme (similar to the legacy page)
19- **Supabase** - Theme matching Supabase's brand colors
20- **GitHub (High Contrast)** - High contrast theme inspired by GitHub's design
21
22## Creating a New Theme
23
24Want to contribute a theme?
25
26We only support themes via GitHub contributions to keep a certain version control. You can:
27
28- Configure your [themes.openstatus.dev](https://themes.openstatus.dev/?b=true) and copy the configuration
29- Directly test by running it locally
30
31### 1. Run the project
32
33Start by forking the openstatus repository to your GitHub account and run the command `dev:status-page` locally following [Getting Started](https://github.com/openstatusHQ/openstatus?tab=readme-ov-file#getting-started-) steps.
34
35Once you run the `@openstatus/status-page` app, e.g. via the following command in the root directory:
36
37```bash
38pnpm dev:status-page
39```
40
41You can either access [localhost:3000](http://localhost:3000) to see the theme explorer or [localhost:3000/status](http://localhost:3000/status) to have a status page with seeded entries. On the bottom right is a configration button which has access to settings, including the community theme.
42
43> If something is off, our you think improvements can be made, feel free to raise an issue, join Discord, or DM us!
44
45### 2. Create Your Theme File
46
47Create a new TypeScript file in this directory (e.g., `my-theme.ts`). You can copy an existing theme file as a starting template.
48
49### 3. Define Your Theme
50
51Your theme file should export a constant that matches the `Theme` interface:
52
53```typescript
54import type { Theme } from "./types";
55
56export const MY_THEME = {
57 id: "my-theme", // Unique identifier (kebab-case)
58 name: "My Awesome Theme", // Display name
59 author: {
60 name: "@yourusername",
61 url: "https://github.com/yourusername" // Add your personal website or a social link
62 },
63 light: {
64 // CSS custom properties for light mode
65 "--background": "oklch(100% 0 0)",
66 "--foreground": "oklch(20% 0 0)",
67 // ... more variables
68 },
69 dark: {
70 // CSS custom properties for dark mode
71 "--background": "oklch(10% 0 0)",
72 "--foreground": "oklch(90% 0 0)",
73 // ... more variables
74 },
75} as const satisfies Theme;
76```
77
78You don't need to add every single css var from the `THEME_VAR_NAMES` list.
79
80### 4. Add to Theme Registry
81
82Update `index.ts` to include your theme in the `THEMES_LIST` array.
83
84```typescript
85const THEMES_LIST = [
86 OPENSTATUS_THEME,
87 OPENSTATUS_ROUNDED_THEME,
88 //...
89 MY_THEME
90] satisfies Theme[];
91
92```
93
94### 5. Submit a Pull Request
95
96Create a pull request with your theme for review.
97
98## Design Guidelines
99
100### Color System
101- Use **OKLCH color space** for better perceptual uniformity (but all css color specs are supported)
102- Ensure sufficient contrast ratios for accessibility
103- Test both light and dark modes thoroughly
104
105### Theme Requirements
106- ✅ **Consistent design** - All components should feel cohesive
107- ✅ **Both modes** - Must support light and dark variants
108- ✅ **Accessibility** - Meet WCAG contrast guidelines
109- ✅ **Unique ID** - Use descriptive, kebab-case identifiers
110- ❌ **No "Christmas tree"** - Avoid overly colorful or distracting designs
111
112### Available CSS Variables
113Themes can customize these CSS custom properties:
114- `--background`, `--foreground` - Base colors
115- `--primary`, `--secondary`, `--accent` - Brand colors
116- `--success`, `--warning`, `--destructive` - Status colors
117- `--border`, `--input`, `--ring` - Interactive elements
118- `--muted`, `--muted-foreground` - Subtle text and backgrounds
119- And many more... (see `types.ts` for the complete list)
120
121## Testing Your Theme
122
123Before submitting:
1241. Test your theme on a status page
1252. Verify both light and dark modes work correctly
1263. Check accessibility with browser dev tools
1274. Ensure all status indicators (operational, degraded, etc.) are clearly distinguishable
128
129To test a theme on non-development environment, you can use the `sessionStorage.setItem("community-theme", "true");`. It will open a floating button on the right left corner where you can choose between the themes and dark/light mode.
130
131## Questions?
132
133Need help creating a theme? Open an issue or reach out to the openstatus community!