Skip to content

armgit / memos

Public Imported from GitHub
0

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.

11.8 KB
Raw Blame

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/50 for dialogs and sheets, bg-overlay/20 for 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, and shadow-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

  1. Always pair colors correctly:

    /* Correct */
    background: var(--primary);
    color: var(--primary-foreground);
    
  2. Use semantic meaning:

    • Primary = main actions
    • Secondary = supporting actions
    • Destructive = dangerous/delete actions
    • Muted = less important content
  3. Respect the design system:

    • Use existing color tokens instead of custom colors
    • Maintain consistency across components

❌ Don'ts

  1. Don't mix incompatible pairs:

    /* Incorrect - poor contrast */
    background: var(--primary);
    color: var(--foreground);
    
  2. Don't use colors outside their intended purpose:

    • Don't use destructive colors for positive actions
    • Don't use primary colors for secondary elements
  3. 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:

  1. Test both light and dark themes
  2. Verify readability at different zoom levels
  3. Check with colorblind simulation tools
  4. 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

  1. Dialog/Sheet: Use z-overlay for both overlay and content
  2. Interactive Elements: Use z-dropdown for dropdowns inside dialogs
  3. Tooltips: Use z-tooltip to appear above all other elements
  4. 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.