mirror of
https://github.com/fmhy/edit.git
synced 2026-01-12 15:01:06 +11:00
d4d4ad0d85
* Add files for christmas theme, theme handler, feedback revamp and cattpuccin theme * Add files via upload * update image on home page * add tree logo for faster loading * change link to raw github
109 lines
4.7 KiB
Markdown
109 lines
4.7 KiB
Markdown
# Theme System
|
||
|
||
This document explains the updated theme architecture, display modes, and integration components in the site.
|
||
|
||
## Architecture
|
||
|
||
- Display modes: `light` and `dark`.
|
||
- AMOLED: an enhancement of `dark` mode (pure black backgrounds) toggled on top of dark — not a separate mode.
|
||
- Themes: color schemes and optional design tokens that apply across modes.
|
||
- Modes are independent from themes; themes define colors and tokens for light/dark.
|
||
|
||
## File Structure
|
||
|
||
```
|
||
docs/.vitepress/theme/themes/
|
||
├── types.ts // Type definitions
|
||
├── themeHandler.ts // Theme handler logic & DOM/CSS application
|
||
├── index.ts // Exports
|
||
└── configs/
|
||
├── index.ts // Theme registry (default + named themes)
|
||
└── catppuccin.ts // Example theme (default)
|
||
```
|
||
|
||
## Core Types
|
||
|
||
- `DisplayMode`: `'light' | 'dark'`.
|
||
- `Theme`: `{ name, displayName, preview?, logo?, modes: { light, dark }, ... }`.
|
||
- `ModeColors`:
|
||
- `brand?`: optional brand colors (`1`, `2`, `3`, `soft`). If omitted, the ColorPicker controls brand.
|
||
- `bg`, `bgAlt`, `bgElv`, `bgMark?`.
|
||
- `text?`: optional (`1`, `2`, `3`). If omitted, VitePress defaults are used.
|
||
- `button`: `brand` and `alt` sub-objects with `bg`, `border`, `text`, `hover*`, `active*`.
|
||
- `customBlock`: `info`, `tip`, `warning`, `danger` with `bg`, `border`, `text`, `textDeep`.
|
||
- `selection`: `{ bg }`.
|
||
- `home?`: optional hero styles.
|
||
|
||
## Handler Behavior (`themeHandler.ts`)
|
||
|
||
- Persists `theme` (`vitepress-theme-name`) and `mode` (`vitepress-display-mode`).
|
||
- Applies HTML classes: always the current mode; adds `dark` for compatibility; adds `amoled` when dark + AMOLED enabled.
|
||
- AMOLED handling: overrides dark backgrounds to pure black while retaining other dark tokens.
|
||
- Brand colors:
|
||
- If theme provides brand colors, inline CSS variables are set.
|
||
- If theme omits brand colors, inline brand variables are removed so the ColorPicker stylesheet takes effect.
|
||
- Text colors:
|
||
- Applied only if defined in the theme; otherwise defaults are used.
|
||
- Custom logo:
|
||
- If theme provides `logo`, sets `--vp-theme-logo: url(...)` for downstream usage.
|
||
|
||
## UI Components
|
||
|
||
- `ThemeDropdown.vue`: replaces the appearance toggle.
|
||
- Options: Light, Dark, AMOLED (as dark variant).
|
||
- Stores/reads mode and AMOLED-enabled state.
|
||
- Aliased via `docs/.vitepress/config.mts` to override `VPSwitchAppearance.vue`.
|
||
- `ColorPicker.vue`:
|
||
- Controls brand color CSS variables via a stylesheet tag (`#brand-color`).
|
||
- Reapplies colors on a custom event `theme-changed-apply-colors` when switching to themes without brand.
|
||
- `ThemeSelector.vue`:
|
||
- Shows circular previews per theme (image via `preview` or gradient fallback).
|
||
- Calls `setTheme(name)`; independent from ColorPicker.
|
||
|
||
## Theme Registry (`configs/index.ts`)
|
||
|
||
- Example:
|
||
```ts
|
||
import { catppuccinTheme } from './catppuccin'
|
||
|
||
export const themeRegistry = {
|
||
default: catppuccinTheme,
|
||
catppuccin: catppuccinTheme
|
||
}
|
||
```
|
||
|
||
## Creating a Theme (`configs/<name>.ts`)
|
||
|
||
- Export a `Theme` object with:
|
||
- `name`, `displayName`, optional `preview` (image URL/data) and `logo`.
|
||
- `modes.light` and `modes.dark` objects.
|
||
- Optional `fonts`, `spacing`, `borderRadius`, `customProperties`.
|
||
- Register it in `configs/index.ts`.
|
||
- If you omit `brand` in a mode, the ColorPicker-selected brand colors will be used.
|
||
- If you omit `text` in a mode, VitePress default text colors will be used.
|
||
|
||
## CSS Variables
|
||
|
||
- Brand: `--vp-c-brand-1`, `--vp-c-brand-2`, `--vp-c-brand-3`, `--vp-c-brand-soft`.
|
||
- Background: `--vp-c-bg`, `--vp-c-bg-alt`, `--vp-c-bg-elv`, `--vp-c-bg-mark`.
|
||
- Text: `--vp-c-text-1`, `--vp-c-text-2`, `--vp-c-text-3`.
|
||
- Buttons: `--vp-button-brand-*`, `--vp-button-alt-*`.
|
||
- Custom blocks: `--vp-custom-block-{type}-*`.
|
||
- Selection: `--vp-c-selection-bg`.
|
||
- Home hero: `--vp-home-hero-*`.
|
||
- Custom props: all keys in `customProperties`.
|
||
- Optional: `--vp-theme-logo` (when theme defines `logo`).
|
||
|
||
## Migration Notes
|
||
|
||
- AMOLED is no longer a separate mode; it’s a dark enhancement (pure black backgrounds) toggled in the dropdown.
|
||
- The legacy `Appearance.vue` toggle is replaced by `ThemeDropdown.vue` via alias in `config.mts`.
|
||
- Themes can rely on the ColorPicker for brand colors by omitting `brand`.
|
||
|
||
## Troubleshooting
|
||
|
||
- Theme not applying: ensure it’s added to `themeRegistry` and named correctly.
|
||
- Brand not changing: if a theme sets inline brand variables, ColorPicker won’t override; remove `brand` from the theme to defer to ColorPicker.
|
||
- Colors not updating after theme switch: ColorPicker listens for `theme-changed-apply-colors`; make sure that event dispatch remains in `setTheme()`.
|
||
- AMOLED not pure black: confirm dark mode is active and AMOLED toggle is enabled; handler overrides backgrounds when enabled.
|
||
|