Memos is an open-source, self-hosted note-taking app that brings your everyday thoughts together in a personal timeline. Your data stays yours, and you choose what to keep private or share.
Color System Guide
This document explains the color system used in the Memos application, built with OKLCH color space for better perceptual uniformity and accessibility.
Overview
The color system supports both light and dark themes automatically through CSS custom properties. All colors are defined using OKLCH (Oklab LCH) color space, which provides better perceptual uniformity than traditional RGB/HSL.
Color Categories
π¨ Primary Brand Colors
| Variable | Light Theme | Dark Theme | Usage |
|---|---|---|---|
--primary |
Golden yellow | Brighter golden | Main brand color, primary CTAs |
--primary-foreground |
White | White | Text on primary backgrounds |
When to use:
- Call-to-action buttons
- Active navigation items
- Important links and highlights
- Brand elements
/* Example usage */
.cta-button {
background: var(--primary);
color: var(--primary-foreground);
}
π Secondary Colors
| Variable | Light Theme | Dark Theme | Usage |
|---|---|---|---|
--secondary |
Light gray | Very light gray | Supporting actions |
--secondary-foreground |
Dark gray | Dark gray | Text on secondary backgrounds |
When to use:
- Secondary buttons
- Less important actions
- Alternative navigation items
- Subtle highlights
π Background & Surface Colors
| Variable | Light Theme | Dark Theme | Usage |
|---|---|---|---|
--background |
Near white | Dark gray | Main page background |
--card |
Near white | Dark gray | Card/container backgrounds |
--card-foreground |
Very dark | Near white | Text on card backgrounds |
--popover |
Pure white | Graphite | Floating surface backgrounds |
--popover-foreground |
Dark gray | Light gray | Text on overlay backgrounds |
--overlay |
Pure black | Pure black | Scrim behind modals |
When to use:
- Page backgrounds (
--background) - Content cards and panels (
--card) - Tooltips, dropdowns, modals (
--popover) - Modal scrims (
--overlay, always with an alpha utility:bg-overlay/50for dialogs and sheets,bg-overlay/20for focus mode)
Floating surface details
Tooltip, popover, dropdown menu, and select surfaces use the --popover / --popover-foreground pair in every theme. Keep primary color for actions and selection, rather than ordinary hints.
- Tooltips: 12px text / 16px line height, 8px horizontal and 4px vertical padding, 6px radius, no arrow, and
shadow-md. Long hints wrap at 16rem or the available viewport width. - Interactive popups:
text-ui(13px / 20px), 8px radius,border-border/70, andshadow-float. Default padding is 6px; content such as maps and search lists can own its padding. - Menu and select rows: 32px default minimum height; compact menus retain 28px rows. Section labels and shortcuts use smaller, muted text.
- Default trigger gap: 6px. Submenus stay adjacent to their parent menu so the pointer can cross safely.
- Shared motion: 150ms, 2% scale and 4px travel; reduced-motion users get no transition. Positioning, collision handling, and keyboard behavior stay with Base UI.
The editor owns a separate set of floating elements. MemoEditor/edit/editor.css aligns their surfaces and tooltips with these values while preserving document typography.
Form controls
Form fields share a visible keyboard outline and semantic invalid styling. Resting fields use a subtle border without a shadow; disabled fields use a muted surface. Small checkbox/radio/switch controls put their outline outside the glyph.
--control-thumb gives switch thumbs enough separation from the track in each scheme: it follows --card in light/paper and --foreground in dark. It reuses the theme palette rather than introducing a fixed white. The 32Γ20px switch has a 16px thumb and a 2px visual inset.
βοΈ Text & Content Colors
| Variable | Light Theme | Dark Theme | Usage |
|---|---|---|---|
--foreground |
Dark gray | Light gray | Primary text color |
--muted |
Light gray | Very dark | Subtle background areas |
--muted-foreground |
Medium gray | Medium light | Secondary text, captions |
When to use:
- Main body text (
--foreground) - Helper text, placeholders (
--muted-foreground) - Disabled text states
- Subtle background sections (
--muted)
π― Interactive Elements
| Variable | Light Theme | Dark Theme | Usage |
|---|---|---|---|
--accent |
Light gray | Very dark | Hover states, selected items |
--accent-foreground |
Dark gray | Light gray | Text on accent backgrounds |
--border |
Medium light | Medium dark | Dividers, input borders |
--input |
Medium light | Medium dark | Form input backgrounds |
When to use:
- Hover states (
--accent) - Form field borders (
--border) - Input field backgrounds (
--input)
β οΈ Feedback Colors
| Variable | Light Theme | Dark Theme | Usage |
|---|---|---|---|
--destructive |
Very dark | Red | Error states, dangerous actions |
--destructive-foreground |
White | White | Text on destructive backgrounds |
--success |
Green | Brighter green | Confirmation states (copied, saved) |
--success-foreground |
Near white | Near black | Text on success backgrounds |
--warning |
Amber | Brighter amber | Caution states (unused, deprecated) |
--warning-foreground |
Dark | Dark | Text on warning backgrounds |
When to use:
- Error messages, delete buttons, validation failures β
--destructive - Success confirmations (e.g. "copied β", saved) β
--success - Non-critical caution (e.g. unused attachments) β
--warning
For tinted treatments (badges, panels), pair the token with an opacity modifier
the same way --destructive is used, e.g. border-warning/30 bg-warning/10 text-warning.
This auto-adapts across themes β never hardcode amber-* / green-* palette classes
or add manual dark: overrides for feedback states.
π Data Visualization
| Variable | Purpose |
|---|---|
--chart-1 |
Primary data series (golden) |
--chart-2 |
Secondary data series (purple) |
--chart-3 |
Tertiary data series (light) |
--chart-4 |
Quaternary data series (purple variant) |
--chart-5 |
Quinary data series (golden variant) |
When to use:
- Charts and graphs
- Data visualization
- Progress indicators
- Statistical displays
π§ Sidebar System
| Variable | Usage |
|---|---|
--sidebar |
Sidebar background |
--sidebar-foreground |
Sidebar text |
--sidebar-primary |
Active sidebar items |
--sidebar-primary-foreground |
Text on active sidebar items |
--sidebar-accent |
Sidebar hover states |
--sidebar-accent-foreground |
Text on sidebar hover states |
--sidebar-border |
Sidebar dividers |
Best Practices
β Do's
Always pair colors correctly:
/* Correct */ background: var(--primary); color: var(--primary-foreground);Use semantic meaning:
- Primary = main actions
- Secondary = supporting actions
- Destructive = dangerous/delete actions
- Muted = less important content
Respect the design system:
- Use existing color tokens instead of custom colors
- Maintain consistency across components
β Don'ts
Don't mix incompatible pairs:
/* Incorrect - poor contrast */ background: var(--primary); color: var(--foreground);Don't use colors outside their intended purpose:
- Don't use destructive colors for positive actions
- Don't use primary colors for secondary elements
Don't hardcode color values:
/* Bad */ color: #333333; /* Good */ color: var(--foreground);
Theme Switching
A theme is a stylesheet in this folder, selected by the data-theme attribute on <html>; utils/theme.ts sets the attribute and the document's color-scheme, and the memo editor follows that color-scheme. There is no .dark or .light class: do not add one to a container, since the editor would switch its own scheme on it.
Accessibility
- All color pairs meet WCAG contrast requirements
- Color is never the only means of conveying information
Implementation Examples
Button Variants
/* Primary button */
.btn-primary {
background: var(--primary);
color: var(--primary-foreground);
border: 1px solid var(--primary);
}
/* Secondary button */
.btn-secondary {
background: var(--secondary);
color: var(--secondary-foreground);
border: 1px solid var(--border);
}
/* Destructive button */
.btn-destructive {
background: var(--destructive);
color: var(--destructive-foreground);
border: 1px solid var(--destructive);
}
Form Elements
/* Input field */
.input {
background: var(--input);
color: var(--foreground);
border: 1px solid var(--border);
}
Cards and Containers
/* Content card */
.card {
background: var(--card);
color: var(--card-foreground);
border: 1px solid var(--border);
}
/* Popover/Modal */
.popover {
background: var(--popover);
color: var(--popover-foreground);
box-shadow: var(--shadow-lg);
}
Color Testing
To ensure proper contrast and accessibility:
- Test both light and dark themes
- Verify readability at different zoom levels
- Check with colorblind simulation tools
- Validate WCAG contrast ratios
Z-Index Hierarchy
The layering tiers are defined once as Tailwind tokens in default.css
(--z-index-overlay/dropdown/tooltip) and consumed via named utilities β do not
hardcode z-[60]-style literals.
| Component Type | Utility | Value | Usage |
|---|---|---|---|
| Base Content | z-0 |
0 | Normal page content |
| Overlays | z-overlay |
50 | Dialog/Sheet backgrounds |
| Modal Content | z-overlay |
50 | Dialog/Sheet content |
| Dropdowns | z-dropdown |
60 | Select, DropdownMenu, Popover content |
| Tooltips | z-tooltip |
70 | Tooltip content (highest priority) |
Rules
- Dialog/Sheet: Use
z-overlayfor both overlay and content - Interactive Elements: Use
z-dropdownfor dropdowns inside dialogs - Tooltips: Use
z-tooltipto appear above all other elements - Always test: Ensure Select/DropdownMenu works inside Dialog/Sheet
These are already the defaults baked into the ui/ primitives, so a Select
inside a Dialog renders above the overlay without any extra z-* class.
This color system is designed to provide a consistent, accessible, and beautiful user experience across all themes and components.