Learnify - Edgeless Theme Behavior Analysis

Problem Description

Edgeless background color behaves inconsistently between edit mode and preview mode:

  • Edit Mode: When users create an edgeless in light mode and switch to dark mode, the background remains white
  • Preview Mode: Shared read-only preview correctly follows the current theme color

Root Cause

1. Different Theme Extension Implementations

Edit Mode - AffineThemeExtension (/packages/frontend/core/src/blocksuite/view-extensions/theme/theme.ts):

1
2
3
4
5
6
7
8
9
10
getEdgelessTheme(docId?: string) {
  // Combines app theme and document theme
  const theme$ = combineLatest([appTheme$, docTheme$]).pipe(
    map(([appTheme, docTheme]) => {
      // If document theme is not 'system', use document theme
      const theme = docTheme === 'system' ? appTheme : docTheme;
      return theme === ColorScheme.Dark ? ColorScheme.Dark : ColorScheme.Light;
    })
  );
}

Preview Mode - AffinePagePreviewThemeExtension (/packages/frontend/core/src/blocksuite/view-extensions/theme/preview-theme.ts):

1
2
3
4
getEdgelessTheme() {
  // Directly returns app theme, ignoring document settings
  return this.theme;
}

2. Theme Settings During Document Creation

EditorSettingDocCreateMiddleware (/packages/frontend/core/src/modules/editor-setting/impls/doc-create-middleware.ts):

  • When creating new documents, the edgelessColorTheme property is set based on edgelessDefaultTheme setting
  • If set to 'specified', it sets to 'light' or 'dark' based on current app theme
  • This causes the document theme to be "locked" to the theme at creation time

3. CSS Variable Application

Edgeless background uses CSS variables:

  • --affine-background-primary-color: Primary background color
  • --affine-edgeless-grid-color: Grid color

Theme values:

  • Light Theme: Background is white (255,255,255), grid is light gray (230,230,230)
  • Dark Theme: Background is dark gray (20,20,20), grid is transparent dark gray (49,49,49,0.35)

Key File Locations

  1. Edgeless Components:

    • Edit mode: /blocksuite/affine/blocks/root/src/edgeless/edgeless-root-block.ts
    • Preview mode: /blocksuite/affine/blocks/root/src/preview/edgeless-root-preview-block.ts

  2. Theme Services:

    • /packages/frontend/core/src/blocksuite/view-extensions/theme/theme.ts
    • /packages/frontend/core/src/blocksuite/view-extensions/theme/preview-theme.ts

  3. Document Creation Middleware:

    • /packages/frontend/core/src/modules/editor-setting/impls/doc-create-middleware.ts

  4. Share Page:

    • /packages/frontend/core/src/desktop/pages/workspace/share/share-page.tsx

Solution Suggestions

  1. Short-term Solution: Modify document's edgelessColorTheme property to 'system'
  2. Long-term Solutions:
    • Unify theme behavior between edit mode and preview mode
    • Consider adding user option to let users decide whether to lock document theme
    • Or modify default settings to make new documents use 'system' theme by default
  • edgelessColorTheme: Document-level theme setting ('light' | 'dark' | 'system')
  • edgelessDefaultTheme: Default theme preference in user settings ('auto' | 'light' | 'dark' | 'specified')
  • AppThemeService: Global application theme service