[Draft] Introducing more granular CSS design tokens for UI.

[pszczesniak]

🚀 Summary

A brief summary of what this PR changes.

---

📌 Related issues

• Closes #000

---

💡 Additional information

Problem

CKEditor 5 exposes foundation CSS variables (--ck-border-radius, --ck-spacing-unit, etc.) that are too coarse-grained for fine-tuned customization. Changing one variable affects
all UI elements simultaneously, preventing selective customization of individual components.

Solution

A three-tier token hierarchy where each layer references the one above it:

Foundation (primitives)  →  Semantic (design intent)  →  Component (per-component API)

Layer	Purpose	Location	Example
Foundation	Raw primitives (scale, colors, geometry)	theme/globals/_*.css, theme/globals/colors/_foundation.css	--ck-spacing-sm, --ck-color-base-active,
--ck-radius-base
Semantic	Design-intent roles shared across components	theme/globals/_semantic-*.css, theme/globals/colors/_semantic-*.css	--ck-color-interactive-hover-surface,
--ck-border-radius-control
Component	Per-component customization API	theme/components/**/*.css	--ck-button-border-radius, --ck-toolbar-background-color

Naming convention

• Foundation: --ck-{domain}-{scale} — e.g., --ck-spacing-sm, --ck-duration-fast, --ck-radius-base
• Semantic: --ck-{domain}-{role}-{property} — e.g., --ck-color-surface-container, --ck-spacing-control-padding-inline
• Component: --ck-{component}-{part?}-{state?}-{property} — e.g., --ck-button-default-hover-background-color, --ck-dialog-border-radius

A full naming guide is in packages/ckeditor5-ui/docs/framework/theme-token-naming.md.

Key changes

• Foundation modernized — spacing (xs–xl), font sizes (xs–xl), shadows (shadow-md/lg), z-index (z-base/overlay/modal), focus, motion tokens renamed to match modern
  design system conventions (Tailwind, Spectrum, Atlassian)
• Color primitives extracted — all hardcoded hsl() values from semantic files moved to colors/_foundation.css, preparing for a future color palette system
• Component color tokens — legacy domain-first tokens (--ck-color-button-*) migrated to component-first naming (--ck-button-*-color) in their respective component files
• Focus border fix — focus states now change only border-color (not the full border shorthand), so customizing --ck-button-border-width no longer causes a visual jump on
  focus
• Composite border tokens — balloon panel and tooltip now have single overridable --ck-*-border tokens
• Backward compatibility — all old token names preserved as aliases in dedicated legacy files (_legacy-foundation-aliases.css, _legacy-component-aliases.css)
• Manual test — interactive Design Token Explorer at tests/manual/ui-customization/ with live editing, per-token reset, reference labels, and cascading value updates

Backward compatibility

All existing CSS custom property names continue to work. Legacy alias files map old names → new names:

/* Old name still works */
--ck-color-toolbar-background: var(--ck-toolbar-background-color);
--ck-border-radius: var(--ck-radius-base);
--ck-spacing-small: var(--ck-spacing-sm);

---

🧾 Checklists

Use the following checklists to ensure important areas were not overlooked.
This does not apply to feature-branch merges.
If an item is not relevant to this type of change, simply leave it unchecked.

Author checklist

• Is the changelog entry intentionally omitted?
• Is the change backward-compatible?
• Have you considered the impact on different editor setups and core interactions? (e.g., classic/inline/multi-root/many editors, typing, selection, paste, tables, lists, images, collaboration, pagination)
• Has the change been manually verified in the relevant setups?
• Does this change affect any of the above?
• Is performance impacted?
• Is accessibility affected?
• Have tests been added that fail without this change (against regression)?
• Have the API documentation, guides, feature digest, and related feature sections been updated where needed?
• Have metadata files (ckeditor5-metadata.json) been updated if needed?
• Are there any changes the team should be informed about (e.g. architectural, difficult to revert in future versions or having impact on other features)?
• Were these changes documented (in Logbook)?

Reviewer checklist

• PR description explains the changes and the chosen approach (especially when performance, API, or UX is affected).
• The changelog entry is clear, user‑ or integrator-facing, and it describes any breaking changes.
• All new external dependencies have been approved and mentioned in LICENSE.md (if any).
• All human-readable, translateable strings in this PR been introduced using t() (if any).
• I manually verified the change (e.g., in manual tests or documentation).
• The target branch is correct.