Theming: make editor colors, borders and radii configurable

Aperta
#1,331 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
25/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
react, scss, typescript
Ambito
frontend

Direzione di ricerca

Start with docs/how-to-customize-the-editor.md and the proposed packages/editor/src/styles/tokens.scss, then inventory the listed consumption sites such as extensions/base/BaseStyles/index.scss, bundle/MarkdownEditorView.scss and markup/codemirror/gravity.ts. Before adding defaults, check CSS-variable inheritance on .g-md-editor-component and where uikit popups render, since per-editor values must reach floating UI. Done means documented --mde-* variables preserve current appearance through fallbacks, work for two differently styled editors on one page, and are covered by visual snapshots.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

enhancement
Description

The editor has no documented CSS variables for colors, radii or shadows. It has six public variables in docs/how-to-customize-the-editor.md, covering padding and sticky toolbar layout.

An app has no documented way to change most editor colors and shapes independently of the uikit theme.

Three problems come from this.

1. Some colors are written as values, not variables. They do not follow the theme. They stay the same in the light, the dark and both high-contrast themes.

Path Line Value
packages/editor/src/extensions/base/BaseStyles/index.scss 15, 19 #8cf
packages/editor/src/extensions/yfm/YfmTabs/index.scss 73 #027bf3
packages/editor/src/extensions/behavior/Resizable/Resizable.scss 46 rgba(127, 127, 127, 0.8)
packages/editor/src/bundle/MarkupEditorView.scss 4 rgba(98, 146, 255, 0.2), used at 43 and 48
packages/editor/src/styles/yfm-themes.scss 24, 28 rgba(255, 255, 255, 0.7) inside a base64 SVG
packages/editor/src/extensions/yfm/Color/colors.scss 3–10 8 hex values
packages/editor/src/icons/GPT.tsx 10–16 4 hex values

The first one is the outline around a selected node: #8cf in all four themes, on every image, table and note.

Markup mode has the same problem. packages/editor/src/markup/codemirror/gravity.ts:8 adds defaultHighlightStyle.specs from @codemirror/language. That style has 14 color rules with fixed hex values; its own doc comment says it "works well with light themes" (6.10.8, dist/index.d.ts:933). The file re-colors 11 tags, so 12 rules stay. This is why code colors in markup mode do not change in the dark theme.

2. Borders and radii are written as numbers. Border width is 1px in 18 places and 2px in 3 places, with no variable. Radius is split: 18 declarations use the uikit scale --g-border-radius-*, and 11 use plain pixels (4px, 6px, 8px, 16px).

3. The editor writes into CSS variables of other packages. It has no variable of its own, so it sets variables of uikit, @diplodoc/transform and @gravity-ui/components.

34 declarations in 14 files

Paths below start at packages/editor/src/.

Variable Owner Where Count
--g-button-padding, --g-button-icon-offset uikit bundle/MarkdownEditorView.scss:63-64, bundle/toolbar/ToolbarButtonWithPopupMenu.scss:4-5, toolbar/ToolbarListButton.scss:3-4, forms/Link.scss:16 7
--g-button-text-color, -hover uikit extensions/yfm/YfmNote/plugins/YfmNoteTooltipPlugin/YfmNoteToolbar.scss:7-20 8
--g-button-background-color, -hover, --g-button-border-color, --g-button-text-color uikit extensions/yfm/YfmTable/plugins/YfmTableControls/dnd/dnd.scss:39-42 4
--g-button-height uikit extensions/yfm/YfmTable/plugins/YfmTableControls/components/FloatingPlusButton/PlusButton.tsx:48, extensions/yfm/YfmTable/plugins/YfmTableControls/components/FloatingMenu/FloatingMenu.tsx:87 2
--_--background-color uikit, private extensions/yfm/YfmTable/plugins/YfmTableControls/components/FloatingMenu/FloatingMenu.tsx:88 1
--g-popup-border-width, --g-popup-border-radius uikit modules/search/components/SearchPopup.scss:2-3,7 3
--gc-form-row-label-width, --gc-form-row-field-height @gravity-ui/components modules/search/components/SearchCardView.scss:9-10 2
--yfm-color-border @diplodoc/transform extensions/yfm/YfmTable/plugins/YfmTableControls/nodeviews/yfm-table-view.scss:2 1
--yfm-hr-height, --yfm-hr-margin @diplodoc/transform styles/yfm-overrides.scss:2-3 2
--yfm-quote-link-background, -hover @diplodoc/transform extensions/additional/QuoteLink/index.scss:2,3,9 3
--yfm-file-icon-color @diplodoc/transform styles/yc-file.scss:4 1

The worst one is --_--background-color: a private uikit variable (@gravity-ui/uikit 7.13.1, build/esm/components/Button/Button.css:5). uikit can rename it in any release, and the editor breaks with no warning.

The editor also reads 6 private uikit palette entries (--g-color-private-*): packages/editor/src/extensions/additional/QuoteLink/index.scss, packages/editor/src/extensions/additional/GPT/gptExtension/view.scss and packages/editor/src/styles/yc-colors.scss.

Proposal

Add a layer of CSS variables for the editor. An app sets them on an editor instance. Introducing a variable can preserve the current appearance by keeping the existing value as its fallback. Replacing a fixed value with a uikit color is a separate visual change that needs approval and snapshots.

One prefix: --mde-. It is free. --g- belongs to uikit, --gc- to @gravity-ui/components, --yfm- to @diplodoc/transform.

Name shape: --mde-[<block>-]<property>[-<state>]. One word per meaning: a background is always bg, a text color is always text-color, a line color is always border-color. A state is always last.

Two layers. A small shared set, and block variables that fall back to it.

border-bottom-color: var(--mde-tab-active-underline-color, var(--mde-accent-color, #027bf3));

One change for the whole editor: set --mde-accent-color. One change in one place: set --mde-tab-active-underline-color.

Fallbacks follow the current rule. Existing uikit colors remain uikit fallbacks. Fixed values remain literal fallbacks until a theme-aware replacement is approved. This gives two things:

  • adding a variable alone does not change the current appearance;
  • existing uikit-based values continue to follow uikit themes.

The tables below retain proposed names and theme-aware defaults. Where a proposed default differs from the current value, it is a decision for discussion, not part of the appearance-preserving first step.

Where the variables live. Use var(--mde-…, <current value>) where each property is consumed. Do not declare default --mde-* values on inner .g-md-editor or .yfm selectors: those declarations would override values inherited from an app's wrapper. MarkdownEditorView has an outer .g-md-editor-component element; the toolbar is outside the inner .g-md-editor. Decide whether styles/tokens.scss should contain shared definitions or only source data for documentation after checking inheritance and popup placement. The public example must work with two differently styled editors on one page.

Before adding tokens for floating UI, check where uikit Popup and DropdownMenu render and whether they inherit variables from the editor instance. If they render outside that subtree, specify how per-editor values reach them.

Shared variables

Candidate shared names. Their fallbacks and interactions with block variables need to be checked at each consumption site; this table does not prescribe CSS declarations on inner editor elements.

18 variables
Variable Proposed default
--mde-bg var(--g-color-base-background)
--mde-bg-float var(--g-color-base-float)
--mde-text-color var(--g-color-text-primary)
--mde-text-color-secondary var(--g-color-text-secondary)
--mde-text-color-hint var(--g-color-text-hint)
--mde-border-color var(--g-color-line-generic)
--mde-border-color-solid var(--g-color-line-generic-solid)
--mde-accent-color var(--g-color-line-brand)
--mde-selection-bg var(--g-color-base-selection)
--mde-focus-outline-color var(--g-color-line-focus)
--mde-danger-color var(--g-color-text-danger)
--mde-border-width 1px
--mde-border-width-accent 2px
--mde-radius-xs var(--g-border-radius-xs)
--mde-radius-s var(--g-border-radius-s)
--mde-radius-m var(--g-border-radius-m)
--mde-radius-l var(--g-border-radius-l)
--mde-shadow-color var(--g-color-sfx-shadow)
Colors to replace

The names and locations are actionable. Defaults that replace a fixed color or a different uikit variable are proposed visual changes. Keep the current value as the first implementation's fallback until those changes are reviewed. The base64 chevrons also need a different rendering method before --mde-yfm-chevron-color can control them.

Value, variable, default, place

Paths below start at packages/editor/src/.

Current value Variable Proposed default Place
#8cf --mde-node-selected-outline-color var(--g-color-line-brand) extensions/base/BaseStyles/index.scss:15,19
var(--g-color-text-info) --mde-node-selected-ring-color var(--g-color-line-brand) extensions/behavior/Selection/selection.scss:2
#027bf3 --mde-tab-active-underline-color var(--g-color-line-brand) extensions/yfm/YfmTabs/index.scss:73
rgba(127, 127, 127, 0.8) --mde-resize-handle-color var(--g-color-base-generic-accent) extensions/behavior/Resizable/Resizable.scss:46
rgba(98, 146, 255, 0.2) --mde-markup-selection-bg var(--g-color-base-selection) bundle/MarkupEditorView.scss:4,43
color.adjust(…) --mde-markup-selection-bg-inactive var(--g-color-base-generic) bundle/MarkupEditorView.scss:48
transparent --mde-block-hover-border-color transparent styles/mixins.scss:2
base64 SVG with rgba(255,255,255,0.7) --mde-yfm-chevron-color var(--g-color-text-secondary) styles/yfm-themes.scss:24,28
var(--g-color-sfx-shadow) --mde-drag-ghost-shadow the current value extensions/yfm/YfmTable/plugins/YfmTableControls/dnd/dnd.scss:27
2 private purple and blue entries --mde-gpt-popup-shadow the current value extensions/additional/GPT/gptExtension/view.scss:19-21
2 private black and white entries --mde-quote-link-bg the current values extensions/additional/QuoteLink/index.scss:2,9
4 hex values --mde-gpt-icon-gradient-start, -end the current hex per theme icons/GPT.tsx:10-11,15-16
12 color rules from @codemirror/language --mde-markup-token-<tag> nearest var(--g-color-text-*) markup/codemirror/gravity.ts:8
marktext, mark --mde-markup-mark-color, --mde-markup-mark-bg var(--g-color-text-primary), var(--g-color-base-warning-light) markup/codemirror/gravity.ts:22

A selected node gets two variables, because two rules draw it and both can be on screen at once: extensions/base/BaseStyles/index.scss:15 is the ProseMirror node selection, extensions/behavior/Selection/selection.scss:2 is the editor's own selection plugin.

The two gradient variables also remove the useTheme() call at icons/GPT.tsx:5, the only place in the editor that checks the theme in JavaScript.

Borders and radii

The inventory and names can guide implementation. Decide which widths and radii should share a public token before replacing every 1px or 4px; a value's repetition alone does not establish that it has the same meaning. Preserve each current value until any visual change is approved.

Value, variable, default, count

Paths below start at packages/editor/src/.

Current value Variable Proposed default Places
1px --mde-border-width 1px 18
2px --mde-border-width-accent 2px 3
8px --mde-split-divider-width 8px bundle/MarkupEditorView.scss:132
4px --mde-radius-s 4px 4
6px --mde-radius-m var(--g-border-radius-m) extensions/behavior/Resizable/Resizable.scss:45
8px --mde-radius-l var(--g-border-radius-l) extensions/yfm/YfmTable/plugins/YfmTableControls/dnd/dnd.scss:89,93,97,101
16px --mde-search-popup-radius 16px modules/search/components/SearchPopup.scss:3,4
var(--g-spacing-2) --mde-gpt-popup-radius var(--g-border-radius-l) extensions/additional/GPT/gptExtension/view.scss:10
100px --mde-table-plus-button-radius 100px extensions/yfm/YfmTable/plugins/YfmTableControls/components/FloatingPlusButton/PlusButton.tsx:31

Use the uikit radius scale --g-border-radius-xs|s|m|l|xl. Do not add a second scale; 18 declarations already use it.

The four 4px radii keep 4px as the default, because --g-border-radius-s is 5px and a switch would change the picture by 1px. That can be a separate step.

uikit has no border-width scale, so --mde-border-width and --mde-border-width-accent have plain defaults.

Variables for writes into other packages

These are proposed editor-facing names. Replacing the private uikit variable and other component variables requires checking each component's public styling API. Some --g-button-* writes will remain necessary because UIKit Button reads them.

8 variables
Need Variable Default Replaces
Toolbar button padding --mde-toolbar-button-padding 2px --g-button-padding, 3 places
Toolbar button icon offset --mde-toolbar-button-icon-offset 0px --g-button-icon-offset, 3 places
Note toolbar color --mde-note-toolbar-text-color var(--yfm-color-note-*) --g-button-text-color, 8 places
Drag ghost button --mde-drag-ghost-button-bg, -border-color, -text-color current values --g-button-*, 4 places
Collapsed table control --mde-table-control-collapsed-height, -bg 4px/5px, var(--g-color-base-background) --g-button-height, --_--background-color
Search popup shape --mde-search-popup-radius, -border-width 16px, 0 --g-popup-*, 3 places
Table border color --mde-table-border-color var(--g-color-line-generic) --yfm-color-border
Horizontal rule --mde-hr-height, --mde-hr-margin 4px, 24px 0 --yfm-hr-*

Two of these still write --g-button-* in the end, because that is how a uikit Button takes color. The change is that an app now sets one editor variable, and the --g-button-* write stays inside one rule.

Renames

Keep the concrete mapping below. The six documented --g-md-* names need a compatibility period. The other names are undocumented, but applications may still use them; decide the migration policy before removing them.

19 names
Current New
--g-md-toolbar-padding --mde-toolbar-padding
--g-md-editor-padding --mde-editor-padding
--g-md-toolbar-sticky-padding --mde-toolbar-sticky-padding
--g-md-toolbar-sticky-inset --mde-toolbar-sticky-inset
--g-md-toolbar-sticky-offset --mde-toolbar-sticky-offset
--g-md-toolbar-sticky-border --mde-toolbar-sticky-border-width, -style, -color
--g-md-math-back-color --mde-math-bg
--g-md-math-hover-color --mde-math-bg-hover
--toolbar-item-preview-width --mde-toolbar-preview-width
--toolbar-item-preview-height --mde-toolbar-preview-height
--toolbar-item-preview-h1-margin … -h6-margin --mde-toolbar-preview-h1-margin … -h6-margin
--img-skeleton-width --mde-image-skeleton-width
--img-skeleton-height --mde-image-skeleton-height
--layer-navigation-bar delete

Two reasons.

A name with no prefix can clash with a name in an app. --img-skeleton-width is the clearest case. There are 11 such names, in packages/editor/src/bundle/config/previews/ActionPreview.scss:2-10, packages/editor/src/extensions/yfm/ImgSize/ImagePaste/skeleton.scss:2-3 and packages/editor/src/extensions/additional/GPT/gptExtension/view.scss:6.

--g- belongs to uikit, and the editor uses it for 8 names of its own. These 8 also show why the name rule is needed: the editor writes a background three ways — back-color, background and color — and puts hover in the middle of one name and at the end of another.

--layer-navigation-bar is set in packages/editor/src/extensions/additional/GPT/gptExtension/view.scss:6 and never read.

Discussion: work without a uikit wrapper

Right now the editor needs a g-root ancestor:

  • packages/editor/src/styles/yfm-themes.scss puts the whole --yfm-* bridge under four .g-root_theme_* rules, so with no g-root none of them match;
  • packages/editor/src/styles/yc-colors.scss:11,17 puts --yfm-color-text-* and --yfm-colorify-* under .g-root;
  • packages/editor/src/styles/yc-file.scss:3 puts --yfm-file-icon-color under .g-root .yfm;
  • uikit declares every --g-color-* inside .g-root — @gravity-ui/uikit 7.13.1, styles/styles.scss:3-24.

The proposed plain-value fallbacks and selector changes need a separate compatibility check. UIKit components and the four YFM theme mixins also depend on g-root; CSS fallbacks in editor rules alone do not establish that the entire editor works without it. Decide whether supporting that environment belongs in this issue.

The Color extension palette

--yfm-colorify-* is document content, not interface. A color saved in a document must look the same when @diplodoc/transform renders it outside the editor, so these names keep the --yfm- prefix.

One thing needs a fix. The palette is declared twice. packages/editor/src/extensions/yfm/Color/colors.scss:15 sets it on :root with hex values; packages/editor/src/styles/yc-colors.scss:22 sets it on .g-root with uikit colors. packages/editor/src/styles/markdown.scss imports both, and .g-root wins. packages/editor/src/styles/styles.scss — the bundle that packages/editor/src/bundle/MarkdownEditorView.tsx:36 imports — takes only the second file, so there the Color extension has no color at all outside a g-root subtree.

Consolidating the declarations is useful, but the target selector and fallback need a decision: document colors must also render outside the editor. A candidate is --yfm-colorify-red: var(--g-color-text-danger, #c00); verify that it preserves the intended result in an editor, preview and standalone @diplodoc/transform output.

The cell background palette in packages/editor/src/styles/yc-table-cell-bg.scss is document content too. It already uses only uikit variables, so it needs the plain-value fallback and nothing else.

Discussion: the CodeMirror theme in markup mode
  1. Before removing defaultHighlightStyle.specs in packages/editor/src/markup/codemirror/gravity.ts:8, list the tags produced by the markdown grammar and embedded languages and agree on their colors in all four themes. Candidate variable names follow the lezer tags: --mde-markup-token-keyword, -comment, -string, -number, -variable, -property, -operator, -type, -link, -url, -heading, -meta, -escape, -invalid.
  2. Replace color: 'marktext', backgroundColor: 'mark' at packages/editor/src/markup/codemirror/gravity.ts:22. These are CSS system colors: they follow the operating system and ignore the editor theme.
  3. Remove the old CodeMirror 5 block in packages/editor/src/bundle/MarkupEditorView.scss:41-119, or finish it. It has a TODO: use own theme at line 93, 17 commented-out lines at 101–117, and the last two plain color values in the bundle.
State outlines

Four states draw a frame today, each in a different way.

State Place How
ProseMirror node selection packages/editor/src/extensions/base/BaseStyles/index.scss:15,19 outline: 2px solid #8cf
Editor node selection packages/editor/src/extensions/behavior/Selection/selection.scss:2 box-shadow: … 0 0 0 1px
Table cell selection packages/editor/src/extensions/yfm/YfmTable/plugins/YfmTableControls/dnd/dnd.scss:57,69 border-color plus ::after with border
Keyboard focus packages/editor/src/extensions/yfm/YfmTable/plugins/YfmTableControls/components/CellBgPalette/CellBgPalette.scss:32 outline: 1px solid var(--g-color-line-focus)

Discuss whether all four states should use outline with outline-offset. The current rules differ in layout and stacking; verify table-cell selection and focus in browsers before changing them. Their colors and widths can be exposed independently of that decision.

Drag and drop and the GPT popup keep box-shadow, one variable each: --mde-drag-ghost-shadow, --mde-gpt-popup-shadow.

Compatibility

The six documented names are --g-md-toolbar-padding, --g-md-toolbar-sticky-padding, --g-md-toolbar-sticky-inset, --g-md-toolbar-sticky-offset, --g-md-toolbar-sticky-border, --g-md-editor-padding. The rename table also contains undocumented names that may be used by applications. Adding new variables does not break them; removing old names requires a migration plan.

If the documented names are renamed, read both during a compatibility period. For example:

padding: var(--mde-toolbar-padding, var(--g-md-toolbar-padding, 0px));

The package is at 15.48.2; removing --g-md-* is a candidate for 16.0.0. Decide the compatibility period and treatment of the undocumented names before committing to that change.

The proposal intends to retain --yfm-* document colors, class names and the TypeScript API. Verify integrations that currently set other CSS variables.

Any approved default change needs visual snapshots, including #8cf, #027bf3, markup colors and the two base64 chevrons.

How to check it
  1. A stylelint rule against new fixed UI colors. The repo already runs stylelint through stylelint.config.mjs and infra/linters/stylelint.js. Scope any rule to UI declarations after accounting for the document palette, TSX icons, base64 images and legitimate fixed fallbacks; a blanket color-no-hex rule would flag intentional values and miss some of these cases.
  2. Visual tests. demo/tests/visual-tests/** already runs in Docker. Check unchanged defaults and non-default variables in all four themes, with two editors on one page. Include popup styles if they become configurable.
  3. A demo page with a theme switch. demo/src/stories/css-variables/CSSVariables.stories.tsx already shows the six padding variables as Storybook controls. Add the color, border and radius variables there. demo/src/hocs/withThemeProvider.tsx:9 already switches the uikit theme per story.
  4. Accurate docs defaults. infra/docs-gen already exists; decide whether generation is useful once token fallbacks have a stable source. The current table in docs/how-to-customize-the-editor.md is wrong: three var() calls have no fallback, so the corresponding declarations are invalid when unset. For --g-md-toolbar-sticky-padding, it says -4px, while the resulting padding is 0.
Order of work

Proposed sequence. Rows marked discussion need the corresponding decisions above before implementation. Paths start at packages/editor/src/.

# What Size Status
1 Fix the docs defaults; add an instance-scoped demo and baseline visual checks. Decide the role of styles/tokens.scss before using it as a source for docs. small ready
2 Add variables for the selected-node outline, active-tab underline, resize handle and markup selection, preserving their current fallbacks. Other color changes follow the decisions above. small ready
3 Border width and radius variables: styles/mixins.scss and about 20 call sites. Preserve current values; decide which uses share a token. medium discussion
4 Review writes into other packages: --_--background-color, --g-button-*, --g-popup-*, --gc-form-row-*. medium discussion
5 Replace the CodeMirror 6 palette in markup/codemirror/gravity.ts after choosing colors for all tags. large discussion
6 Confirm the old CodeMirror 5 block in bundle/MarkupEditorView.scss:41-119 is unused, then remove it. small ready after verification
7 Rename variables with both names read; delete --layer-navigation-bar and the two unused variables in styles/_zindex.scss. medium discussion
8 Investigate whether the uikit wrapper can be optional, including styles/yc-colors.scss, styles/yfm-themes.scss and the --yfm-colorify-* declaration. large separate decision
9 Drop --g-md-* in a major release after the compatibility period. small depends on 7
Modules to touch

Inventory for the full proposal, including items marked for discussion. Paths start at packages/editor/src/.

Directory What is in it Size
styles The whole system goes here. New styles/tokens.scss. styles/yc-colors.scss and styles/yfm-themes.scss move off .g-root. styles/mixins.scss takes variables. styles/yfm-overrides.scss gets variables instead of 4px and 24px 0. styles/_zindex.scss loses two unused variables. large
extensions 47 style files and most of the findings. Each extension is on its own. The biggest is extensions/yfm/YfmTable: 4 plain radii, 4 --g-button-* writes, the private --_--background-color, a shadow, --yfm-color-border. large
markup markup/codemirror/gravity.ts is the whole markup theme. The tag list has to be written from the start and checked in four themes. large
bundle The two remaining SCSS color values, the old CodeMirror 5 block, four of the six public --g-md-*, the 8 preview variables with no prefix. Carries the public contract. medium
toolbar A 1px separator and --g-button-* writes. small
modules modules/search: --g-popup-*, --gc-form-row-*, a plain 16px. small
icons icons/GPT.tsx, the only JavaScript theme check in the package. small
plugins, forms, view One border-style: ridge with no width and no color, one --g-button-padding. small

packages/latex-extension/src has no style files. packages/page-constructor-extension/src has one, and it already uses variables everywhere.

Lingua principale
TypeScript
Stelle
428
Fork
48
Merge medio
5g 15h
PR unite (30g)
47

Preparare l'ambiente

Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di gravity-ui/markdown-editor

Tutte le issue di gravity-ui/markdown-editor

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.