From d5da91c1fda05d5286b9faf75905edb8d47e3c08 Mon Sep 17 00:00:00 2001
From: Mohammad Moradi <mohammad.moradi@outlook.com>
Date: Sat, 11 Jul 2026 13:12:11 +0300
Subject: [PATCH 1/7] docs: Create Skills

---
 .claude/skills/adapter-parity/SKILL.md | 56 ++++++++++++++++++++++
 .claude/skills/changeset/SKILL.md      | 59 +++++++++++++++++++++++
 .claude/skills/new-block-type/SKILL.md | 66 ++++++++++++++++++++++++++
 .claude/skills/release-check/SKILL.md  | 62 ++++++++++++++++++++++++
 .claude/skills/theming/SKILL.md        | 63 ++++++++++++++++++++++++
 5 files changed, 306 insertions(+)
 create mode 100644 .claude/skills/adapter-parity/SKILL.md
 create mode 100644 .claude/skills/changeset/SKILL.md
 create mode 100644 .claude/skills/new-block-type/SKILL.md
 create mode 100644 .claude/skills/release-check/SKILL.md
 create mode 100644 .claude/skills/theming/SKILL.md

diff --git a/.claude/skills/adapter-parity/SKILL.md b/.claude/skills/adapter-parity/SKILL.md
new file mode 100644
index 0000000..d9731ac
--- /dev/null
+++ b/.claude/skills/adapter-parity/SKILL.md
@@ -0,0 +1,56 @@
+---
+name: adapter-parity
+description: Use whenever you change editor *behavior* (keyboard shortcuts, markdown shortcuts, selection handling, table operations, drag/drop, paste handling) in either the Vue or React adapter, or when auditing whether the two adapters have drifted apart. Ports the change to the sibling adapter and verifies the two state machines still mirror each other function-for-function.
+---
+
+# Keeping the Vue and React adapters in sync
+
+xproeditor intentionally keeps two state machines — `BlockEditor.vue`'s
+`<script setup>` (Vue) and `useBlockEditor` in
+`packages/react/src/hooks/useBlockEditor.ts` (React) — structurally
+near-identical: same function names, same call sites into
+`@xproeditor/core`. See [docs/architecture.md](../../docs/architecture.md).
+This lets a behavior change be ported by shape-matching instead of
+re-deriving the logic from scratch.
+
+## When you change one adapter
+
+1. Identify the exact function(s) touched in
+   `packages/vue/src/components/BlockEditor.vue` or
+   `packages/react/src/hooks/useBlockEditor.ts`.
+2. Find the same-named function/handler in the sibling file. If none exists
+   yet, that's the drift to fix, not a sign the other adapter doesn't need it.
+3. Port the change preserving the same control flow and the same
+   `@xproeditor/core` calls (same function name, same argument shape) — do
+   not "improve" the logic differently per framework; behavioral differences
+   between adapters are bugs users will file.
+4. If the change touches the toolbar surfaces, update both pairs:
+   - `EditorFormatToolbar.vue` ↔ `FormatToolbar.tsx`
+   - `EditorBubbleToolbar.vue` ↔ `BubbleToolbar.tsx`
+   - `EditorSlashMenu.vue` ↔ `SlashMenu.tsx`
+5. If the change touches read-only rendering, update
+   `DocRenderer.vue` ↔ `DocRenderer.tsx`.
+
+## Auditing for existing drift
+
+When asked to check whether the adapters have drifted:
+
+1. List the exported/internal function names in `BlockEditor.vue`'s
+   `<script setup>` and in `useBlockEditor.ts`.
+2. Diff the two name sets — anything present in one but not the other is a
+   parity gap. Flag it; don't assume it's intentional.
+3. For functions present in both, skim for behavioral divergence (different
+   keyboard shortcut, different core function called, different edge-case
+   handling) rather than just name matching.
+4. Report gaps with file:line references rather than silently fixing large
+   amounts of behavior — parity fixes can be subtle and are worth a
+   confirmation before landing.
+
+## Verifying
+
+- `npm run dev:vue` and `npm run dev:react` (ports 5173/5174 per
+  `.claude/launch.json`) — exercise the same interaction in both demos.
+- `npm run typecheck && npm test` from the repo root.
+- Public API shape should stay symmetric between packages "where the
+  framework allows it" (CONTRIBUTING.md) — same prop/option names, same
+  `toolbar` prop semantics on `<ProEditor>`.
diff --git a/.claude/skills/changeset/SKILL.md b/.claude/skills/changeset/SKILL.md
new file mode 100644
index 0000000..342af08
--- /dev/null
+++ b/.claude/skills/changeset/SKILL.md
@@ -0,0 +1,59 @@
+---
+name: changeset
+description: Use before finishing any PR that changes the behavior of a published package (@xproeditor/core, @xproeditor/vue, or @xproeditor/react) — decide whether a changeset is needed, which packages/semver bump it should declare, and write it correctly. Also use when asked to prepare a release.
+---
+
+# Writing a changeset for xproeditor
+
+This repo publishes `@xproeditor/core`, `@xproeditor/vue`, and
+`@xproeditor/react` independently via [Changesets](https://github.com/changesets/changesets),
+fully automated through `.github/workflows/release.yml`. See
+[docs/releasing.md](../../docs/releasing.md) for the full pipeline.
+
+## Decide if a changeset is needed
+
+Needed when the change affects published package *behavior* or public API:
+new block type, new prop/option, bug fix in editor behavior, new exported
+core function, styling change visible in `dist/style.css`, etc.
+
+Not needed for: internal refactors with no observable behavior change,
+`examples/*` or `site/` changes, docs, CI/tooling, test-only changes.
+
+## Which packages to bump
+
+Because `@xproeditor/vue` and `@xproeditor/react` both depend on
+`@xproeditor/core`'s compiled `dist/`:
+
+- A change inside `packages/core/src` → bump `@xproeditor/core`, and bump
+  whichever adapter(s) actually consume the changed core surface (if the
+  change is purely internal to core with no adapter-visible effect, core
+  alone is enough).
+- A change inside `packages/vue/src` only → bump `@xproeditor/vue` only.
+- A change inside `packages/react/src` only → bump `@xproeditor/react` only.
+- A behavior change ported to both adapters (see the `adapter-parity`
+  skill) → bump `@xproeditor/vue` and `@xproeditor/react` together (and
+  `@xproeditor/core` too if the core layer changed).
+
+## Semver bump
+
+- `patch` — bug fix, no API change.
+- `minor` — new backward-compatible feature (new block type, new prop, new
+  exported function).
+- `major` — breaking change to a public export, prop, or persisted
+  `BlocksContent`/`Block` shape. Flag this explicitly to the user before
+  writing it — a major bump on any of these packages is a deliberate,
+  user-facing decision, not a default.
+
+## Writing it
+
+Run `npx changeset`, select the affected package(s) and bump, and write a
+one-line, user-facing summary (it becomes the changelog entry verbatim —
+write it as "what changed for the consumer," not as an implementation note).
+Commit the generated `.changeset/*.md` file as part of the PR.
+
+## What happens next (informational — do not act on this yourself)
+
+On merge to `main`, CI either opens/updates a "Version Packages" PR (bumping
+versions + writing `CHANGELOG.md`) or, once that PR is merged, publishes to
+npm automatically. Never hand-bump `package.json` versions or hand-edit
+`CHANGELOG.md` — that's the bot's job.
diff --git a/.claude/skills/new-block-type/SKILL.md b/.claude/skills/new-block-type/SKILL.md
new file mode 100644
index 0000000..4b33b24
--- /dev/null
+++ b/.claude/skills/new-block-type/SKILL.md
@@ -0,0 +1,66 @@
+---
+name: new-block-type
+description: Use when adding a brand-new block type (like a new BlockType such as "callout" or "table") to xproeditor. Walks through every layer that must change — core model/serialization, Vue adapter, React adapter, toolbar and slash menu — so no adapter is left half-implemented.
+---
+
+# Adding a new block type
+
+xproeditor stores documents as a flat `Block[]` (see [docs/block-model.md](../../docs/block-model.md)).
+A new `BlockType` touches four layers, in this order. Do not skip a layer —
+a block type that only exists in `core` renders nowhere, and a block type
+that only exists in one adapter breaks parity (see the `adapter-parity` skill).
+
+## 1. `@xproeditor/core` (framework-agnostic)
+
+- `packages/core/src/types.ts` — add the new literal to the `BlockType` union
+  and any new fields to `BlockProps`.
+- `packages/core/src/normalize.ts` — default/normalize the new props when a
+  block is created or loaded (e.g. defaults for `checked`, `collapsed`, `width`).
+- `packages/core/src/serialize.ts` and `packages/core/src/html.ts` — how the
+  block round-trips to/from `BlocksContent` and HTML (`blocksToHtmlContent`,
+  `htmlToBlocks`).
+- `packages/core/src/clipboard.ts` — copy/paste (de)serialization if the
+  block carries non-text data.
+- Add/extend a test in `packages/core/src/*.test.ts` covering
+  normalize → serialize → round-trip for the new type.
+- Rebuild core before touching adapters: `npm run build -w @xproeditor/core`
+  (adapters import core's compiled `dist/`, not its source).
+
+## 2. Vue adapter (`packages/vue/src`)
+
+- Rendering: add a new block component under `components/` (pattern:
+  `EditorImageBlock.vue`, `EditorTableBlock.vue`) or extend
+  `EditorTextBlock.vue` if it's a text-like block, and wire it into
+  `EditorBlockItem.vue`'s type switch.
+- Behavior: extend `BlockEditor.vue`'s `<script setup>` state machine —
+  keydown/markdown-shortcut handling, `turnIntoBlock`, table-style ops as
+  precedent.
+- Discoverability: add a slash-menu entry in `EditorSlashMenu.vue` and, if the
+  block has a distinct toolbar action, a control in
+  `components/toolbar/` / `EditorFormatToolbar.vue` / `EditorBubbleToolbar.vue`.
+
+## 3. React adapter (`packages/react/src`)
+
+Mirror step 2 exactly, function-for-function:
+
+- Rendering: a new component under `components/` (pattern: `ImageBlock.tsx`,
+  `TableBlock.tsx`), wired into `BlockItem.tsx`'s type switch.
+- Behavior: the equivalent addition in `hooks/useBlockEditor.ts` — same
+  function names and call sites into `@xproeditor/core` as the Vue version.
+- Discoverability: `SlashMenu.tsx` and, if applicable,
+  `components/toolbar/` / `FormatToolbar.tsx` / `BubbleToolbar.tsx`.
+
+## 4. Cross-cutting
+
+- `DocRenderer.vue` / `DocRenderer.tsx` — the read-only renderer needs to know
+  how to display the new block type too.
+- Styling: if the block needs new visual chrome, follow
+  [docs/theming.md](../../docs/theming.md) — Tailwind utility classes authored
+  in each package's own `src`, no new CSS variables unless the value is meant
+  to be end-user themeable (background/foreground/border/primary/mono font).
+- Update [docs/block-model.md](../../docs/block-model.md) with the new
+  `BlockType`/`BlockProps` fields.
+- Run `npm run lint && npm run typecheck && npm test` from the repo root
+  before considering the change done.
+- Add a changeset (see the `changeset` skill) — a new block type is a
+  user-visible feature in all three published packages.
diff --git a/.claude/skills/release-check/SKILL.md b/.claude/skills/release-check/SKILL.md
new file mode 100644
index 0000000..8dd9da4
--- /dev/null
+++ b/.claude/skills/release-check/SKILL.md
@@ -0,0 +1,62 @@
+---
+name: release-check
+description: Use before merging a PR into main, before merging the bot-generated "Version Packages" PR, or when explicitly asked to prepare/verify a release of xproeditor's packages. Runs the same gates CI runs plus the repo-specific checks CI can't (adapter parity, changeset correctness) so nothing broken reaches npm.
+---
+
+# Pre-release / pre-merge checklist
+
+xproeditor auto-publishes on merge to `main` once a "Version Packages" PR is
+merged (see [docs/releasing.md](../../docs/releasing.md)). Because publishing
+is automatic, catch problems *before* merge — there's no manual publish gate
+after.
+
+## Build order matters
+
+`@xproeditor/vue` and `@xproeditor/react` import `@xproeditor/core`'s
+compiled `dist/`, not its source. Always:
+
+```bash
+npm run build      # builds core, then vue, then react, in that order
+npm run typecheck
+npm test
+npm run lint
+```
+
+Running `typecheck`/`test` without building core first can pass locally on
+stale `dist/` output and still fail in CI — don't skip the build step even
+for a "small" change.
+
+## Repo-specific checks CI doesn't fully cover
+
+1. **Changeset correctness** — every PR that changes published behavior has
+   a `.changeset/*.md` file naming the right package(s) and a semver bump
+   that matches the change (see the `changeset` skill). A missing changeset
+   means the fix ships silently with no changelog entry on the next release.
+2. **Adapter parity** — if the PR touched `BlockEditor.vue` or
+   `useBlockEditor.ts`, confirm the sibling adapter got the equivalent change
+   (see the `adapter-parity` skill). CI's typecheck/test/lint will not catch
+   a Vue-only fix that should also apply to React.
+3. **Demo apps still work** — `npm run dev:vue` / `npm run dev:react` /
+   `npm run dev:site` and manually exercise the changed behavior; these
+   import the workspace packages directly and are the fastest way to catch a
+   broken build before it's live.
+
+## Reviewing the bot's "Version Packages" PR
+
+Before merging it:
+
+- Confirm the version bumps match what you'd expect from the changesets
+  that went in (no unexpected `major`).
+- Skim the generated `CHANGELOG.md` entries for clarity — they're copied
+  verbatim from changeset summaries, so a vague summary written earlier
+  becomes a vague changelog entry now; fix it in the changeset source if
+  still possible, otherwise flag it.
+- Merging this PR triggers the actual `npm publish` on the next workflow
+  run — treat the merge itself as the release action and confirm with the
+  user first if there's any doubt about timing.
+
+## First-time / infra checks (rarely needed)
+
+If publishing fails, check the `NPM_TOKEN` repo secret (Settings → Secrets
+and variables → Actions) has publish rights to the `@xproeditor` npm org
+before assuming a code problem.
diff --git a/.claude/skills/theming/SKILL.md b/.claude/skills/theming/SKILL.md
new file mode 100644
index 0000000..c71d47c
--- /dev/null
+++ b/.claude/skills/theming/SKILL.md
@@ -0,0 +1,63 @@
+---
+name: theming
+description: Use when styling anything inside packages/vue or packages/react — new components, visual tweaks, dark-mode support, or CSS variable additions. Keeps the zero-Tailwind-dependency build intact and decides whether a value belongs in a CSS variable (user-themeable) or plain scoped CSS (internal chrome).
+---
+
+# Styling inside the adapters
+
+Full background: [docs/theming.md](../../docs/theming.md).
+
+## The constraint
+
+`@xproeditor/vue` and `@xproeditor/react` are authored with Tailwind utility
+classes, but consumers never install Tailwind. Each package runs the
+Tailwind CLI over its own `src` at build time (`corePlugins.preflight`
+disabled) and ships one `dist/style.css`. This means:
+
+- Only use Tailwind utility classes that exist in each package's own
+  `tailwind.config.js` content globs — classes assembled dynamically at
+  runtime via string concatenation (`` `text-${color}-500` ``) won't be
+  picked up by the Tailwind CLI's static scan and will silently not ship.
+  Use the full class name literally, or a lookup table of full class names.
+- Don't add a runtime dependency on Tailwind, PostCSS plugins, or any CSS
+  framework that isn't already bundled into `dist/style.css` — it would
+  leak a peer dependency onto every consumer.
+- Global element selectors are off-limits (`corePlugins.preflight: false`
+  is deliberate) — never reset margins/box-sizing/etc. globally; scope
+  everything to `.ebi-*` / `.etb-*` / `.xpe-*`-prefixed classes or the
+  component's own root class.
+
+## CSS variable vs. plain scoped CSS
+
+Ask: would a consuming app plausibly want to override this without
+forking the stylesheet?
+
+- **Yes → CSS variable** on `:root`, following the existing
+  `--xpe-*` naming (`--xpe-background`, `--xpe-foreground`,
+  `--xpe-muted-foreground`, `--xpe-muted`, `--xpe-border`, `--xpe-primary`,
+  `--xpe-font-mono`). Define both packages' `styles/theme.css` in lockstep —
+  a variable added to one adapter should exist in the other too, since apps
+  often use both.
+- **No (internal chrome: toolbar/popover/table-gutter/syntax palette/etc.)
+  → plain scoped CSS** with an `.ebi-*`/`.etb-*`/`.xpe-*` class, no
+  `!important` (consumers rely on being able to override these by loading
+  their own stylesheet after `style.css`).
+
+## Dark mode
+
+Dark mode is just a second set of `--xpe-*` values scoped under whatever
+selector the consuming app uses (commonly `.dark`) — don't build a
+dark-mode switch into the package itself; document the override in
+`docs/theming.md` if you add new variables.
+
+## Verifying
+
+- Rebuild the affected package(s) so `dist/style.css` regenerates:
+  `npm run build -w @xproeditor/vue` / `-w @xproeditor/react`.
+- Check both demos (`npm run dev:vue`, `npm run dev:react`) since Tailwind's
+  static class scanning can behave differently per package's `tailwind.config.js`
+  content globs — a class that resolves in one adapter's demo can be missing
+  from the other's `dist/style.css` if its config wasn't updated too.
+- If you added/changed a `--xpe-*` variable, update
+  [docs/theming.md](../../docs/theming.md)'s reference table for both light
+  and dark examples.

From 0e6b64888dce2f5669a4368691e09e2c7e7fa633 Mon Sep 17 00:00:00 2001
From: Mohammad Moradi <mohammad.moradi@outlook.com>
Date: Sat, 11 Jul 2026 13:17:53 +0300
Subject: [PATCH 2/7] Update package.json

---
 package.json | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/package.json b/package.json
index d7a93fc..5e0a350 100644
--- a/package.json
+++ b/package.json
@@ -17,9 +17,9 @@
   "scripts": {
     "build": "npm run build -w @xproeditor/core && npm run build -w @xproeditor/vue && npm run build -w @xproeditor/react",
     "build:site": "npm run build -w @xproeditor/core && npm run build -w @xproeditor/react && npm run build -w site",
-    "dev:vue": "npm run dev -w vue-demo",
-    "dev:react": "npm run dev -w react-demo",
-    "dev:site": "npm run dev -w site",
+    "dev:vue": "npm run build -w @xproeditor/core && npm run build -w @xproeditor/vue && npm run dev -w @xproeditor/vue -w vue-demo",
+    "dev:react": "npm run build -w @xproeditor/core && npm run build -w @xproeditor/react && npm run dev -w @xproeditor/react -w react-demo",
+    "dev:site": "npm run build -w @xproeditor/core && npm run build -w @xproeditor/react && npm run dev -w site",
     "typecheck": "npm run typecheck --workspaces --if-present",
     "test": "npm run test --workspaces --if-present",
     "lint": "eslint .",

From a2089e189098f787f373fd7eac77871108e7fcb6 Mon Sep 17 00:00:00 2001
From: Mohammad Moradi <mohammad.moradi@outlook.com>
Date: Sat, 11 Jul 2026 13:56:00 +0300
Subject: [PATCH 3/7] Add audio/file blocks, pro media import, caret-anchored
 slash menu, dark theme, and live RTL

- New `audio` and `file` block types across core, Vue, and React: upload /
  library / URL insertion, file metadata (name, size, MIME), download card,
  DocRenderer support, and HTML export/import round-trip.
- Media import overhaul: works with zero config (object-URL fallback when no
  `upload` prop), paste files from clipboard, drop OS files onto the editor
  at a precise position, and a paste-URL tab for images.
- Slash menu now measures itself and anchors to the caret: flips above near
  the viewport bottom, clamps to edges, aligns correctly in RTL, and shows a
  "No results" state instead of closing abruptly.
- Theming: minimal token set (--xpe-surface, --xpe-primary-muted, --xpe-ring,
  --xpe-radius, --xpe-shadow, ...) with a built-in dark theme via `xpe-dark`
  class or `data-xpe-theme="dark"`; slash menu and media blocks fully
  token-driven for easy custom themes.
- RTL: text direction now resolves live from content instead of locking on
  first keystroke, and remaining physical CSS converted to logical properties.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .changeset/media-blocks-and-theming.md        |   7 +
 .changeset/slash-menu-theming-rtl.md          |   6 +
 docs/block-model.md                           |  10 +-
 docs/theming.md                               |  59 ++--
 packages/core/src/clipboard.ts                |  20 ++
 packages/core/src/index.ts                    |   1 +
 packages/core/src/media.test.ts               |  54 ++++
 packages/core/src/media.ts                    |  78 +++++
 packages/core/src/normalize.ts                |   9 +
 packages/core/src/ops.ts                      |   2 +-
 packages/core/src/serialize.ts                |   6 +-
 packages/core/src/types.ts                    |  10 +-
 packages/react/src/components/AudioBlock.tsx  | 270 ++++++++++++++++++
 packages/react/src/components/BlockEditor.tsx |   1 +
 packages/react/src/components/BlockItem.tsx   |  22 ++
 .../react/src/components/BubbleToolbar.tsx    |   2 +-
 packages/react/src/components/DocRenderer.tsx |  33 ++-
 packages/react/src/components/FileBlock.tsx   | 185 ++++++++++++
 packages/react/src/components/ImageBlock.tsx  | 166 ++++++++---
 packages/react/src/components/SlashMenu.tsx   | 101 ++++++-
 packages/react/src/components/VideoBlock.tsx  |  36 +--
 .../components/toolbar/TableStylePanel.tsx    |   2 +-
 .../components/toolbar/ToolbarColorPanel.tsx  |   6 +-
 packages/react/src/hooks/useBlockEditor.ts    | 109 ++++---
 packages/react/src/styles/components.css      |   7 +
 packages/react/src/styles/theme.css           |  38 +++
 packages/vue/src/components/BlockEditor.vue   | 125 +++++---
 packages/vue/src/components/DocRenderer.vue   |  53 +++-
 .../vue/src/components/EditorAudioBlock.vue   | 242 ++++++++++++++++
 .../vue/src/components/EditorBlockItem.vue    |  24 ++
 .../src/components/EditorBubbleToolbar.vue    |   2 +-
 .../vue/src/components/EditorFileBlock.vue    | 168 +++++++++++
 .../vue/src/components/EditorImageBlock.vue   | 128 +++++++--
 .../vue/src/components/EditorSlashMenu.vue    |  83 ++++--
 .../vue/src/components/EditorVideoBlock.vue   |  40 +--
 .../toolbar/EditorTableStylePanel.vue         |   2 +-
 .../toolbar/EditorToolbarColorPanel.vue       |   6 +-
 packages/vue/src/styles/theme.css             |  38 +++
 38 files changed, 1903 insertions(+), 248 deletions(-)
 create mode 100644 .changeset/media-blocks-and-theming.md
 create mode 100644 .changeset/slash-menu-theming-rtl.md
 create mode 100644 packages/core/src/media.test.ts
 create mode 100644 packages/core/src/media.ts
 create mode 100644 packages/react/src/components/AudioBlock.tsx
 create mode 100644 packages/react/src/components/FileBlock.tsx
 create mode 100644 packages/vue/src/components/EditorAudioBlock.vue
 create mode 100644 packages/vue/src/components/EditorFileBlock.vue

diff --git a/.changeset/media-blocks-and-theming.md b/.changeset/media-blocks-and-theming.md
new file mode 100644
index 0000000..8b3e1dd
--- /dev/null
+++ b/.changeset/media-blocks-and-theming.md
@@ -0,0 +1,7 @@
+---
+'@xproeditor/core': minor
+'@xproeditor/vue': minor
+'@xproeditor/react': minor
+---
+
+Add `audio` and `file` block types with upload / library / URL insertion, per-file metadata (name, size, MIME), download card UI, and read-only rendering in `DocRenderer`. Media import now works out of the box without an `upload` prop (object-URL fallback), supports pasting files from the clipboard, and dropping OS files directly onto the editor at a precise position. Image blocks gain a paste-URL tab. Core exports new media helpers: `blockTypeForFile`, `formatFileSize`, `mediaPropsFromFile`, `fileToObjectUrl`, `acceptForBlockType`.
diff --git a/.changeset/slash-menu-theming-rtl.md b/.changeset/slash-menu-theming-rtl.md
new file mode 100644
index 0000000..0d67624
--- /dev/null
+++ b/.changeset/slash-menu-theming-rtl.md
@@ -0,0 +1,6 @@
+---
+'@xproeditor/vue': minor
+'@xproeditor/react': minor
+---
+
+Slash-command menu now measures itself and positions precisely at the caret — flipping above when near the viewport bottom, clamping to the viewport edges, staying aligned in RTL, and showing a "No results" state instead of abruptly closing. Theming: a richer minimal token set (`--xpe-surface`, `--xpe-surface-hover`, `--xpe-primary-muted`, `--xpe-primary-foreground`, `--xpe-ring`, `--xpe-danger`, `--xpe-radius`, `--xpe-shadow`) plus a built-in dark theme via the `xpe-dark` class or `data-xpe-theme="dark"`; the slash menu and all media blocks are fully token-driven. Remaining physical CSS (left/right) converted to logical properties for correct RTL layout.
diff --git a/docs/block-model.md b/docs/block-model.md
index 0d23b51..63fcc00 100644
--- a/docs/block-model.md
+++ b/docs/block-model.md
@@ -32,7 +32,8 @@ interface Block {
 type BlockType =
   | 'paragraph' | 'heading_1' | 'heading_2' | 'heading_3'
   | 'bulleted_list_item' | 'numbered_list_item' | 'to_do' | 'toggle'
-  | 'quote' | 'callout' | 'code' | 'divider' | 'image' | 'video' | 'table'
+  | 'quote' | 'callout' | 'code' | 'divider'
+  | 'image' | 'video' | 'audio' | 'file' | 'table'
 ```
 
 ## `InlineSpan` (rich text)
@@ -64,8 +65,11 @@ interface BlockProps {
   collapsed?: boolean       // toggle
   language?: string         // code
   code?: string             // code
-  url?: string              // image/video
-  caption?: string          // image/video
+  url?: string              // image/video/audio/file
+  caption?: string          // image/video/audio
+  name?: string              // audio/file: original file name
+  size?: number              // audio/file: size in bytes
+  mime?: string              // audio/file: MIME type
   width?: number             // image/video width percent (10–100)
   provider?: 'file' | 'youtube' | 'vimeo' // video
   icon?: string              // callout
diff --git a/docs/theming.md b/docs/theming.md
index 034b0cf..1f4a335 100644
--- a/docs/theming.md
+++ b/docs/theming.md
@@ -20,36 +20,59 @@ classes are just standard Tailwind utilities (`flex`, `rounded-xl`, `text-gray-6
 
 ## CSS variables
 
-A handful of design tokens are exposed as CSS custom properties with sensible
-defaults, used by the read-only `<DocRenderer>` and a couple of editor
-surfaces. Override them on `:root` or any ancestor of the editor:
+A small set of design tokens is exposed as CSS custom properties with
+sensible defaults, used by the read-only `<DocRenderer>`, the slash-command
+menu, media blocks, and other editor surfaces. Override them on `:root` or
+any ancestor of the editor:
 
 ```css
 :root {
-  --xpe-background: #ffffff;       /* editor canvas background */
-  --xpe-foreground: #1f2937;       /* body text color */
-  --xpe-muted-foreground: #6b7280; /* secondary text */
-  --xpe-muted: #f3f4f6;            /* subtle backgrounds (quotes, callouts) */
-  --xpe-border: #e5e7eb;           /* hairline borders */
-  --xpe-primary: #4f46e5;          /* links, active states, quote bar */
+  --xpe-background: #ffffff;         /* editor canvas background */
+  --xpe-foreground: #1f2937;         /* body text color */
+  --xpe-muted-foreground: #6b7280;   /* secondary text */
+  --xpe-muted: #f3f4f6;              /* subtle backgrounds (quotes, callouts, media cards) */
+  --xpe-border: #e5e7eb;             /* hairline borders */
+  --xpe-primary: #4f46e5;            /* links, active states, quote bar */
+  --xpe-primary-foreground: #ffffff; /* text on primary buttons */
+  --xpe-primary-muted: #eef2ff;      /* tint behind active menu rows / drop zones */
+  --xpe-surface: #ffffff;            /* elevated surfaces: popovers, menus */
+  --xpe-surface-hover: #f9fafb;      /* hover rows inside menus */
+  --xpe-ring: #818cf8;               /* focus/selection ring around media blocks */
+  --xpe-danger: #ef4444;             /* validation errors */
+  --xpe-radius: 12px;                /* corner radius of cards, menus, media */
+  --xpe-shadow: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.05);
   --xpe-font-mono: ui-monospace, SFMono-Regular, Menlo, monospace;
 }
 ```
 
-For dark mode, scope an override under whatever selector your app uses to
-toggle themes:
+## Dark mode (built in)
+
+A complete dark theme ships in `style.css`. Add the `xpe-dark` class — or
+`data-xpe-theme="dark"` — to any ancestor of the editor, typically alongside
+your app's own dark-mode toggle:
+
+```html
+<body class="dark xpe-dark">
+  <!-- editor renders dark -->
+</body>
+```
+
+## Making your own theme
+
+A theme is just a scoped set of the same variables — no build step needed:
 
 ```css
-.dark {
-  --xpe-background: #111827;
-  --xpe-foreground: #e5e7eb;
-  --xpe-muted-foreground: #9ca3af;
-  --xpe-muted: #1f2937;
-  --xpe-border: #374151;
-  --xpe-primary: #818cf8;
+.theme-forest {
+  --xpe-primary: #059669;
+  --xpe-primary-muted: #ecfdf5;
+  --xpe-ring: #34d399;
+  --xpe-radius: 6px;
 }
 ```
 
+Any variable you don't set falls back to the default (or to `.xpe-dark`'s
+value if that scope is also active).
+
 ## Everything else
 
 The bulk of the editor's visual design (buttons, popovers, block gutter,
diff --git a/packages/core/src/clipboard.ts b/packages/core/src/clipboard.ts
index 42ef476..d47c326 100644
--- a/packages/core/src/clipboard.ts
+++ b/packages/core/src/clipboard.ts
@@ -90,6 +90,26 @@ return ''
 
       return `<img src="${escapeHtml(url)}" alt="${alt}">`
     }
+    case 'audio': {
+      const url = block.props.url ?? ''
+
+      if (!url) {
+return ''
+}
+
+      return `<audio controls src="${escapeHtml(url)}"></audio>`
+    }
+    case 'file': {
+      const url = block.props.url ?? ''
+
+      if (!url) {
+return ''
+}
+
+      const name = escapeHtml(block.props.name ?? block.props.caption ?? 'Download file')
+
+      return `<a href="${escapeHtml(url)}" download>${name}</a>`
+    }
     case 'table': {
       const table = normalizeTableData(block.props.table)
 
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 533478b..5b3efa8 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -19,4 +19,5 @@ export * from './html'
 export * from './serialize'
 export * from './table'
 export * from './video-embed'
+export * from './media'
 export * from './doc-heading-id'
diff --git a/packages/core/src/media.test.ts b/packages/core/src/media.test.ts
new file mode 100644
index 0000000..a2eada9
--- /dev/null
+++ b/packages/core/src/media.test.ts
@@ -0,0 +1,54 @@
+import { describe, expect, it } from 'vitest'
+import { blocksToHtmlContent } from './clipboard'
+import { blockTypeForFile, formatFileSize } from './media'
+import { createBlock } from './ops'
+import { blockToPlainText, buildBlocksContent } from './serialize'
+
+describe('audio/file block model', () => {
+  it('createBlock defaults url for audio and file', () => {
+    expect(createBlock('audio').props.url).toBe('')
+    expect(createBlock('file').props.url).toBe('')
+  })
+
+  it('plain text uses caption for audio and name for file', () => {
+    const audio = createBlock('audio', { props: { url: 'a.mp3', caption: 'My song' } })
+    const file = createBlock('file', { props: { url: 'r.pdf', name: 'report.pdf' } })
+    expect(blockToPlainText(audio)).toBe('My song')
+    expect(blockToPlainText(file)).toBe('report.pdf')
+  })
+
+  it('exports audio and file blocks to HTML', () => {
+    const blocks = [
+      createBlock('audio', { props: { url: 'https://x.test/a.mp3' } }),
+      createBlock('file', { props: { url: 'https://x.test/r.pdf', name: 'report.pdf' } }),
+    ]
+    const html = blocksToHtmlContent(blocks)
+    expect(html).toContain('<audio controls src="https://x.test/a.mp3">')
+    expect(html).toContain('<a href="https://x.test/r.pdf" download>report.pdf</a>')
+  })
+
+  it('round-trips through buildBlocksContent', () => {
+    const blocks = [createBlock('file', { props: { url: 'f.zip', name: 'f.zip', size: 2048 } })]
+    const content = buildBlocksContent(blocks)
+    expect(content.blocks[0].type).toBe('file')
+    expect(content.text).toBe('f.zip')
+  })
+})
+
+describe('media helpers', () => {
+  it('maps MIME types to block types', () => {
+    expect(blockTypeForFile({ type: 'image/png' })).toBe('image')
+    expect(blockTypeForFile({ type: 'video/mp4' })).toBe('video')
+    expect(blockTypeForFile({ type: 'audio/mpeg' })).toBe('audio')
+    expect(blockTypeForFile({ type: 'application/pdf' })).toBe('file')
+    expect(blockTypeForFile({})).toBe('file')
+  })
+
+  it('formats file sizes', () => {
+    expect(formatFileSize(0)).toBe('0 B')
+    expect(formatFileSize(999)).toBe('999 B')
+    expect(formatFileSize(2048)).toBe('2 KB')
+    expect(formatFileSize(3.4 * 1024 * 1024)).toBe('3.4 MB')
+    expect(formatFileSize(undefined)).toBe('')
+  })
+})
diff --git a/packages/core/src/media.ts b/packages/core/src/media.ts
new file mode 100644
index 0000000..8e427fd
--- /dev/null
+++ b/packages/core/src/media.ts
@@ -0,0 +1,78 @@
+import type { BlockType } from './types'
+
+/** Media block types whose main body is a URL-backed asset. */
+export const MEDIA_BLOCK_TYPES: BlockType[] = ['image', 'video', 'audio', 'file']
+
+/** Pick the block type that best represents a dropped/pasted file. */
+export function blockTypeForFile(file: { type?: string }): BlockType {
+  const mime = file.type ?? ''
+
+  if (mime.startsWith('image/')) {
+return 'image'
+}
+
+  if (mime.startsWith('video/')) {
+return 'video'
+}
+
+  if (mime.startsWith('audio/')) {
+return 'audio'
+}
+
+  return 'file'
+}
+
+/** Human-readable file size, e.g. "3.4 MB". */
+export function formatFileSize(bytes: number | undefined): string {
+  if (bytes === undefined || !Number.isFinite(bytes) || bytes < 0) {
+return ''
+}
+
+  if (bytes < 1024) {
+return `${bytes} B`
+}
+
+  const units = ['KB', 'MB', 'GB', 'TB']
+  let value = bytes / 1024
+  let unit = 0
+
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024
+    unit++
+  }
+
+  return `${value >= 10 ? Math.round(value) : Math.round(value * 10) / 10} ${units[unit]}`
+}
+
+/** Accept string for a file input, per media block type. */
+export function acceptForBlockType(type: BlockType): string {
+  switch (type) {
+    case 'image':
+      return 'image/*'
+    case 'video':
+      return 'video/*'
+    case 'audio':
+      return 'audio/*'
+    default:
+      return '*/*'
+  }
+}
+
+/**
+ * Default upload when the host app provides no `upload` prop: an object URL
+ * kept alive for the session. Works out of the box in demos and local-first
+ * apps; persistent apps should pass a real `upload` that stores the file.
+ */
+export function fileToObjectUrl(file: File): Promise<string> {
+  return Promise.resolve(URL.createObjectURL(file))
+}
+
+/** Props patch for a media block created from a File. */
+export function mediaPropsFromFile(file: File, url: string): Record<string, unknown> {
+  return {
+    url,
+    name: file.name,
+    size: file.size,
+    mime: file.type || undefined,
+  }
+}
diff --git a/packages/core/src/normalize.ts b/packages/core/src/normalize.ts
index 528cacc..dac6b69 100644
--- a/packages/core/src/normalize.ts
+++ b/packages/core/src/normalize.ts
@@ -368,6 +368,15 @@ convertHtmlElement(nested, indent + 1, out)
 
       if (src) {
 out.push(createBlock('image', { props: { url: src, caption: el.getAttribute('alt') ?? '' } }))
+}
+
+      break
+    }
+    case 'audio': {
+      const src = el.getAttribute('src') ?? el.querySelector('source')?.getAttribute('src')
+
+      if (src) {
+out.push(createBlock('audio', { props: { url: src } }))
 }
 
       break
diff --git a/packages/core/src/ops.ts b/packages/core/src/ops.ts
index e2be18f..9c2f110 100644
--- a/packages/core/src/ops.ts
+++ b/packages/core/src/ops.ts
@@ -54,7 +54,7 @@ props.checked = false
 props.icon = '💡'
 }
 
-  if (type === 'video' && props.url === undefined) {
+  if ((type === 'video' || type === 'audio' || type === 'file') && props.url === undefined) {
 props.url = ''
 }
 
diff --git a/packages/core/src/serialize.ts b/packages/core/src/serialize.ts
index 139889a..075809e 100644
--- a/packages/core/src/serialize.ts
+++ b/packages/core/src/serialize.ts
@@ -8,8 +8,12 @@ export function blockToPlainText(block: Block): string {
 return block.props.code ?? ''
 }
 
-  if (block.type === 'image') {
+  if (block.type === 'image' || block.type === 'video' || block.type === 'audio') {
 return block.props.caption ?? ''
+}
+
+  if (block.type === 'file') {
+return block.props.name ?? block.props.caption ?? ''
 }
 
   if (block.type === 'table') {
diff --git a/packages/core/src/types.ts b/packages/core/src/types.ts
index c6d2b40..f0f8a4d 100644
--- a/packages/core/src/types.ts
+++ b/packages/core/src/types.ts
@@ -19,6 +19,8 @@ export type BlockType =
   | 'divider'
   | 'image'
   | 'video'
+  | 'audio'
+  | 'file'
   | 'table'
 
 export interface InlineMarks {
@@ -94,9 +96,15 @@ export interface BlockProps {
   /** code */
   language?: string
   code?: string
-  /** image */
+  /** image / video / audio / file */
   url?: string
   caption?: string
+  /** audio / file: original file name */
+  name?: string
+  /** audio / file: size in bytes */
+  size?: number
+  /** audio / file: MIME type */
+  mime?: string
   /** image width percent (10-100) */
   width?: number
   /** video */
diff --git a/packages/react/src/components/AudioBlock.tsx b/packages/react/src/components/AudioBlock.tsx
new file mode 100644
index 0000000..3f7b79c
--- /dev/null
+++ b/packages/react/src/components/AudioBlock.tsx
@@ -0,0 +1,270 @@
+import { useEffect, useRef, useState } from 'react'
+import { FolderOpen, Link2, Loader2, Music, Upload } from 'lucide-react'
+import type { Block } from '@xproeditor/core'
+import { fileToObjectUrl, formatFileSize, mediaPropsFromFile } from '@xproeditor/core'
+import type { PickMediaFn, UploadFn } from '../types'
+
+export interface AudioBlockProps {
+  block: Block
+  selected?: boolean
+  readonly?: boolean
+  upload?: UploadFn
+  pickMedia?: PickMediaFn
+  onPatch: (patch: Record<string, unknown>) => void
+  onSelect: () => void
+}
+
+type InsertMode = 'upload' | 'library' | 'embed'
+
+export function AudioBlock({
+  block,
+  selected,
+  readonly,
+  upload,
+  pickMedia,
+  onPatch,
+  onSelect,
+}: AudioBlockProps) {
+  const [mode, setMode] = useState<InsertMode>('upload')
+  const [uploading, setUploading] = useState(false)
+  const [picking, setPicking] = useState(false)
+  const [dragOver, setDragOver] = useState(false)
+  const [embedInput, setEmbedInput] = useState('')
+  const [embedError, setEmbedError] = useState('')
+  const embedInputRef = useRef<HTMLInputElement | null>(null)
+  const fileInput = useRef<HTMLInputElement | null>(null)
+
+  const busy = uploading || picking
+
+  useEffect(() => {
+    if (mode === 'embed') embedInputRef.current?.focus()
+  }, [mode])
+
+  async function uploadFile(file: File) {
+    if (!file.type.startsWith('audio/')) return
+
+    setUploading(true)
+    try {
+      const url = await (upload ?? fileToObjectUrl)(file)
+      onPatch(mediaPropsFromFile(file, url))
+    } finally {
+      setUploading(false)
+    }
+  }
+
+  async function pickFromLibrary() {
+    if (!pickMedia) return
+
+    setPicking(true)
+    try {
+      const result = await pickMedia({ accept: ['audio/*'], title: 'Choose audio' })
+      if (result?.url)
+        onPatch({ url: result.url, ...(result.caption ? { caption: result.caption } : {}) })
+    } finally {
+      setPicking(false)
+    }
+  }
+
+  function applyEmbed() {
+    setEmbedError('')
+    const url = embedInput.trim()
+
+    if (!/^https?:\/\//i.test(url)) {
+      setEmbedError('Enter a valid audio file URL')
+      return
+    }
+
+    onPatch({ url })
+    setEmbedInput('')
+  }
+
+  function onFilePicked(e: React.ChangeEvent<HTMLInputElement>) {
+    const file = e.target.files?.[0]
+    if (file) uploadFile(file)
+  }
+
+  function onDrop(e: React.DragEvent) {
+    setDragOver(false)
+    const file = e.dataTransfer?.files?.[0]
+    if (file) uploadFile(file)
+  }
+
+  const stop = (e: React.SyntheticEvent) => e.stopPropagation()
+
+  if (!block.props.url && !readonly) {
+    const tabClass = (active: boolean) =>
+      `rounded-lg px-2.5 py-1 text-xs font-medium ${active ? 'bg-[var(--xpe-primary-muted)] text-[var(--xpe-primary)]' : 'text-[var(--xpe-muted-foreground)] hover:bg-[var(--xpe-surface-hover)]'}`
+
+    return (
+      <div className="my-1">
+        <div
+          className={`flex flex-col gap-3 rounded-[var(--xpe-radius)] border-2 border-dashed py-6 transition-colors ${dragOver ? 'border-[var(--xpe-ring)] bg-[var(--xpe-primary-muted)]' : 'border-[var(--xpe-border)] bg-[var(--xpe-muted)]'}`}
+          onClick={onSelect}
+          onDragOver={(e) => {
+            e.preventDefault()
+            setDragOver(true)
+          }}
+          onDragLeave={() => setDragOver(false)}
+          onDrop={(e) => {
+            e.preventDefault()
+            e.stopPropagation()
+            onDrop(e)
+          }}
+        >
+          <div className="flex items-center justify-center gap-2 text-[var(--xpe-muted-foreground)]">
+            {busy ? (
+              <Loader2 className="h-5 w-5 animate-spin text-[var(--xpe-primary)]" />
+            ) : (
+              <Music className="h-5 w-5" />
+            )}
+            <span className="text-sm">{busy ? 'Working...' : 'Add audio'}</span>
+          </div>
+
+          {!busy && (
+            <div
+              className="flex justify-center gap-1 px-4"
+              onClick={stop}
+              onMouseDown={stop}
+              onPointerDown={stop}
+            >
+              <button type="button" className={tabClass(mode === 'upload')} onClick={() => setMode('upload')}>
+                Upload
+              </button>
+              {pickMedia && (
+                <button type="button" className={tabClass(mode === 'library')} onClick={() => setMode('library')}>
+                  Library
+                </button>
+              )}
+              <button type="button" className={tabClass(mode === 'embed')} onClick={() => setMode('embed')}>
+                Link
+              </button>
+            </div>
+          )}
+
+          {!busy && (
+            <div className="px-4" onClick={stop} onMouseDown={stop} onPointerDown={stop}>
+              {mode === 'upload' && (
+                <div className="flex justify-center">
+                  <button
+                    type="button"
+                    className="inline-flex items-center gap-1.5 rounded-lg border border-[var(--xpe-border)] bg-[var(--xpe-surface)] px-3 py-1.5 text-xs font-medium text-[var(--xpe-foreground)] hover:bg-[var(--xpe-surface-hover)]"
+                    onClick={() => fileInput.current?.click()}
+                  >
+                    <Upload className="h-3.5 w-3.5" />
+                    Choose audio file
+                  </button>
+                  <input
+                    ref={fileInput}
+                    type="file"
+                    accept="audio/*"
+                    className="hidden"
+                    onChange={onFilePicked}
+                  />
+                </div>
+              )}
+
+              {mode === 'library' && (
+                <div className="flex justify-center">
+                  <button
+                    type="button"
+                    className="inline-flex items-center gap-1.5 rounded-lg border border-[var(--xpe-border)] bg-[var(--xpe-surface)] px-3 py-1.5 text-xs font-medium text-[var(--xpe-foreground)] hover:bg-[var(--xpe-surface-hover)]"
+                    onClick={pickFromLibrary}
+                  >
+                    <FolderOpen className="h-3.5 w-3.5" />
+                    Open media library
+                  </button>
+                </div>
+              )}
+
+              {mode === 'embed' && (
+                <div className="space-y-2">
+                  <div className="flex items-center gap-2">
+                    <Link2 className="h-4 w-4 shrink-0 text-[var(--xpe-muted-foreground)]" />
+                    <input
+                      ref={embedInputRef}
+                      value={embedInput}
+                      type="url"
+                      className="min-w-0 flex-1 rounded-lg border border-[var(--xpe-border)] bg-[var(--xpe-surface)] px-2.5 py-1.5 text-xs text-[var(--xpe-foreground)] outline-none focus:border-[var(--xpe-ring)]"
+                      placeholder="Audio file URL (.mp3, .ogg, ...)"
+                      onChange={(e) => setEmbedInput(e.target.value)}
+                      onKeyDown={(e) => {
+                        if (e.key === 'Enter') {
+                          e.preventDefault()
+                          applyEmbed()
+                        }
+                      }}
+                    />
+                    <button
+                      type="button"
+                      className="rounded-lg bg-[var(--xpe-primary)] px-2.5 py-1.5 text-xs text-[var(--xpe-primary-foreground)]"
+                      onClick={applyEmbed}
+                    >
+                      Add
+                    </button>
+                  </div>
+                  {embedError && (
+                    <p className="text-center text-xs text-[var(--xpe-danger)]">{embedError}</p>
+                  )}
+                </div>
+              )}
+            </div>
+          )}
+        </div>
+      </div>
+    )
+  }
+
+  return (
+    <div className="my-1">
+      <figure className="group/audio relative">
+        <div
+          className={`flex flex-col gap-2 rounded-[var(--xpe-radius)] border bg-[var(--xpe-muted)] p-3 transition-shadow ${selected ? 'border-[var(--xpe-ring)] ring-1 ring-[var(--xpe-ring)]' : 'border-[var(--xpe-border)]'}`}
+          onClick={onSelect}
+        >
+          {(block.props.name || block.props.size) && (
+            <div className="flex items-center gap-2 text-xs text-[var(--xpe-muted-foreground)]">
+              <Music className="h-3.5 w-3.5 shrink-0" />
+              <span className="truncate font-medium text-[var(--xpe-foreground)]">
+                {block.props.name}
+              </span>
+              {block.props.size ? (
+                <span className="shrink-0">{formatFileSize(block.props.size)}</span>
+              ) : null}
+            </div>
+          )}
+          <audio src={block.props.url} className="w-full" controls preload="metadata" />
+        </div>
+
+        {!readonly && (
+          <div className="absolute end-2 top-2 hidden items-center gap-0.5 rounded-lg bg-black/60 p-0.5 backdrop-blur group-hover/audio:flex">
+            <button
+              className="rounded-md px-1.5 py-0.5 text-[10px] text-white/80 hover:bg-white/20"
+              title="Remove audio"
+              onClick={(e) => {
+                e.stopPropagation()
+                onPatch({ url: '', name: undefined, size: undefined, mime: undefined })
+              }}
+            >
+              ✕
+            </button>
+          </div>
+        )}
+
+        <figcaption
+          onMouseDown={(e) => e.stopPropagation()}
+          onClick={(e) => e.stopPropagation()}
+          onPointerDown={(e) => e.stopPropagation()}
+        >
+          <input
+            className="mt-1.5 w-full bg-transparent text-center text-xs text-[var(--xpe-muted-foreground)] outline-none placeholder:opacity-60"
+            defaultValue={block.props.caption ?? ''}
+            placeholder="Add caption..."
+            readOnly={readonly}
+            onFocus={onSelect}
+            onChange={(e) => onPatch({ caption: e.target.value })}
+          />
+        </figcaption>
+      </figure>
+    </div>
+  )
+}
diff --git a/packages/react/src/components/BlockEditor.tsx b/packages/react/src/components/BlockEditor.tsx
index fa2544f..ac9c3d8 100644
--- a/packages/react/src/components/BlockEditor.tsx
+++ b/packages/react/src/components/BlockEditor.tsx
@@ -148,6 +148,7 @@ export const BlockEditor = forwardRef<BlockEditorHandle, BlockEditorProps>(funct
           ref={ed.slashMenuApiRef}
           query={ed.slashState.query}
           position={ed.slashState.position}
+          dir={ed.editorDir ?? 'ltr'}
           onSelect={ed.onSlashSelect}
           onClose={ed.closeSlash}
         />
diff --git a/packages/react/src/components/BlockItem.tsx b/packages/react/src/components/BlockItem.tsx
index 11aa753..2f230cc 100644
--- a/packages/react/src/components/BlockItem.tsx
+++ b/packages/react/src/components/BlockItem.tsx
@@ -10,6 +10,8 @@ import {
   IconEmojiPicker,
 } from '../ui'
 import { CodeBlock, type CodeBlockHandle } from './CodeBlock'
+import { AudioBlock } from './AudioBlock'
+import { FileBlock } from './FileBlock'
 import { ImageBlock } from './ImageBlock'
 import { SelectionHighlight } from './SelectionHighlight'
 import { TableBlock, type TableBlockHandle } from './TableBlock'
@@ -401,6 +403,26 @@ export const BlockItem = forwardRef<BlockItemHandle, BlockItemProps>(
                 onPatch={onPatch}
                 onSelect={onSelect}
               />
+            ) : block.type === 'audio' ? (
+              <AudioBlock
+                block={block}
+                selected={selected}
+                readonly={readonly}
+                upload={upload}
+                pickMedia={pickMedia}
+                onPatch={onPatch}
+                onSelect={onSelect}
+              />
+            ) : block.type === 'file' ? (
+              <FileBlock
+                block={block}
+                selected={selected}
+                readonly={readonly}
+                upload={upload}
+                pickMedia={pickMedia}
+                onPatch={onPatch}
+                onSelect={onSelect}
+              />
             ) : block.type === 'table' ? (
               <TableBlock
                 ref={innerRef as React.Ref<TableBlockHandle>}
diff --git a/packages/react/src/components/BubbleToolbar.tsx b/packages/react/src/components/BubbleToolbar.tsx
index e00f4ea..4bd00f1 100644
--- a/packages/react/src/components/BubbleToolbar.tsx
+++ b/packages/react/src/components/BubbleToolbar.tsx
@@ -205,7 +205,7 @@ export function BubbleToolbar({
               <button
                 key={t.type}
                 type="button"
-                className={`flex w-full items-center gap-2.5 px-3 py-2 text-left text-[13px] transition-colors ${t.type === blockType ? 'bg-indigo-50/60 text-indigo-600' : 'text-gray-700 hover:bg-gray-50'}`}
+                className={`flex w-full items-center gap-2.5 px-3 py-2 text-start text-[13px] transition-colors ${t.type === blockType ? 'bg-indigo-50/60 text-indigo-600' : 'text-gray-700 hover:bg-gray-50'}`}
                 onClick={() => {
                   onTurnInto(t.type)
                   setPanel('none')
diff --git a/packages/react/src/components/DocRenderer.tsx b/packages/react/src/components/DocRenderer.tsx
index 45ebac1..e182e23 100644
--- a/packages/react/src/components/DocRenderer.tsx
+++ b/packages/react/src/components/DocRenderer.tsx
@@ -5,6 +5,7 @@ import { ChevronRight, Link as LinkIcon, X } from 'lucide-react'
 import {
   computeListNumbering,
   escapeHtml,
+  formatFileSize,
   headingAnchorIds,
   isAllowedEmbedUrl,
   normalizeTableData,
@@ -305,6 +306,36 @@ export function DocRenderer({ blocks, editorDir }: DocRendererProps) {
           )
         }
 
+        if (block.type === 'audio' && block.props.url) {
+          return (
+            <figure key={idx} className="db-figure">
+              <div className="db-audio-wrap">
+                {block.props.name && <div className="db-audio-name">{block.props.name}</div>}
+                <audio src={block.props.url} controls preload="metadata" className="w-full" />
+              </div>
+              {block.props.caption && (
+                <figcaption className="db-caption">{block.props.caption}</figcaption>
+              )}
+            </figure>
+          )
+        }
+
+        if (block.type === 'file' && block.props.url) {
+          return (
+            <a
+              key={idx}
+              href={block.props.url}
+              download={block.props.name ?? true}
+              className="db-file"
+            >
+              <span className="db-file-name">{block.props.name || 'Download file'}</span>
+              {block.props.size ? (
+                <span className="db-file-size">{formatFileSize(block.props.size)}</span>
+              ) : null}
+            </a>
+          )
+        }
+
         if (block.type === 'table' && block.props.table) {
           const table = normalizeTableData(block.props.table)
 
@@ -352,7 +383,7 @@ export function DocRenderer({ blocks, editorDir }: DocRendererProps) {
             onClick={() => setLightboxUrl(null)}
           >
             <img src={lightboxUrl} className="max-w-full max-h-full rounded-lg shadow-2xl" alt="" />
-            <button className="absolute top-4 right-4 text-white/80 hover:text-white">
+            <button className="absolute top-4 end-4 text-white/80 hover:text-white">
               <X className="w-6 h-6" />
             </button>
           </div>,
diff --git a/packages/react/src/components/FileBlock.tsx b/packages/react/src/components/FileBlock.tsx
new file mode 100644
index 0000000..9177568
--- /dev/null
+++ b/packages/react/src/components/FileBlock.tsx
@@ -0,0 +1,185 @@
+import { useRef, useState } from 'react'
+import { Download, FileText, FolderOpen, Loader2, Paperclip, Upload } from 'lucide-react'
+import type { Block } from '@xproeditor/core'
+import { fileToObjectUrl, formatFileSize, mediaPropsFromFile } from '@xproeditor/core'
+import type { PickMediaFn, UploadFn } from '../types'
+
+export interface FileBlockProps {
+  block: Block
+  selected?: boolean
+  readonly?: boolean
+  upload?: UploadFn
+  pickMedia?: PickMediaFn
+  onPatch: (patch: Record<string, unknown>) => void
+  onSelect: () => void
+}
+
+export function FileBlock({
+  block,
+  selected,
+  readonly,
+  upload,
+  pickMedia,
+  onPatch,
+  onSelect,
+}: FileBlockProps) {
+  const [uploading, setUploading] = useState(false)
+  const [picking, setPicking] = useState(false)
+  const [dragOver, setDragOver] = useState(false)
+  const fileInput = useRef<HTMLInputElement | null>(null)
+
+  const busy = uploading || picking
+
+  async function uploadFile(file: File) {
+    setUploading(true)
+    try {
+      const url = await (upload ?? fileToObjectUrl)(file)
+      onPatch(mediaPropsFromFile(file, url))
+    } finally {
+      setUploading(false)
+    }
+  }
+
+  async function pickFromLibrary() {
+    if (!pickMedia) return
+
+    setPicking(true)
+    try {
+      const result = await pickMedia({ accept: ['*/*'], title: 'Choose file' })
+      if (result?.url) onPatch({ url: result.url, ...(result.caption ? { name: result.caption } : {}) })
+    } finally {
+      setPicking(false)
+    }
+  }
+
+  function onFilePicked(e: React.ChangeEvent<HTMLInputElement>) {
+    const file = e.target.files?.[0]
+    if (file) uploadFile(file)
+  }
+
+  function onDrop(e: React.DragEvent) {
+    setDragOver(false)
+    const file = e.dataTransfer?.files?.[0]
+    if (file) uploadFile(file)
+  }
+
+  const stop = (e: React.SyntheticEvent) => e.stopPropagation()
+
+  if (!block.props.url && !readonly) {
+    return (
+      <div className="my-1">
+        <div
+          className={`flex flex-col items-center justify-center gap-3 rounded-[var(--xpe-radius)] border-2 border-dashed py-6 transition-colors ${dragOver ? 'border-[var(--xpe-ring)] bg-[var(--xpe-primary-muted)]' : 'border-[var(--xpe-border)] bg-[var(--xpe-muted)]'}`}
+          onClick={onSelect}
+          onDragOver={(e) => {
+            e.preventDefault()
+            setDragOver(true)
+          }}
+          onDragLeave={() => setDragOver(false)}
+          onDrop={(e) => {
+            e.preventDefault()
+            e.stopPropagation()
+            onDrop(e)
+          }}
+        >
+          <div className="flex items-center gap-2 text-[var(--xpe-muted-foreground)]">
+            {busy ? (
+              <Loader2 className="h-5 w-5 animate-spin text-[var(--xpe-primary)]" />
+            ) : (
+              <Paperclip className="h-5 w-5" />
+            )}
+            <span className="text-sm">{busy ? 'Working...' : 'Attach a file'}</span>
+          </div>
+          {!busy && (
+            <div
+              className="flex flex-wrap items-center justify-center gap-2"
+              onClick={stop}
+              onMouseDown={stop}
+              onPointerDown={stop}
+            >
+              <button
+                type="button"
+                className="inline-flex items-center gap-1.5 rounded-lg border border-[var(--xpe-border)] bg-[var(--xpe-surface)] px-3 py-1.5 text-xs font-medium text-[var(--xpe-foreground)] hover:bg-[var(--xpe-surface-hover)]"
+                onClick={() => fileInput.current?.click()}
+              >
+                <Upload className="h-3.5 w-3.5" />
+                Upload
+              </button>
+              {pickMedia && (
+                <button
+                  type="button"
+                  className="inline-flex items-center gap-1.5 rounded-lg border border-[var(--xpe-border)] bg-[var(--xpe-surface)] px-3 py-1.5 text-xs font-medium text-[var(--xpe-foreground)] hover:bg-[var(--xpe-surface-hover)]"
+                  onClick={pickFromLibrary}
+                >
+                  <FolderOpen className="h-3.5 w-3.5" />
+                  Library
+                </button>
+              )}
+            </div>
+          )}
+          <input ref={fileInput} type="file" className="hidden" onChange={onFilePicked} />
+        </div>
+      </div>
+    )
+  }
+
+  return (
+    <div className="my-1">
+      <div className="group/file relative">
+        <div
+          className={`flex items-center gap-3 rounded-[var(--xpe-radius)] border bg-[var(--xpe-muted)] px-3.5 py-2.5 transition-shadow ${selected ? 'border-[var(--xpe-ring)] ring-1 ring-[var(--xpe-ring)]' : 'border-[var(--xpe-border)]'}`}
+          onClick={onSelect}
+        >
+          <span className="flex h-9 w-9 shrink-0 items-center justify-center rounded-lg bg-[var(--xpe-surface)] text-[var(--xpe-primary)]">
+            <FileText className="h-5 w-5" />
+          </span>
+          <span className="min-w-0 flex-1">
+            <span className="block truncate text-sm font-medium text-[var(--xpe-foreground)]">
+              {block.props.name || 'File'}
+            </span>
+            {block.props.size ? (
+              <span className="block text-xs text-[var(--xpe-muted-foreground)]">
+                {formatFileSize(block.props.size)}
+              </span>
+            ) : null}
+          </span>
+          <a
+            href={block.props.url}
+            download={block.props.name ?? true}
+            className="flex h-8 w-8 shrink-0 items-center justify-center rounded-lg text-[var(--xpe-muted-foreground)] hover:bg-[var(--xpe-surface-hover)] hover:text-[var(--xpe-foreground)]"
+            title="Download"
+            onClick={(e) => e.stopPropagation()}
+          >
+            <Download className="h-4 w-4" />
+          </a>
+        </div>
+
+        {!readonly && (
+          <div className="absolute end-12 top-1/2 hidden -translate-y-1/2 items-center gap-0.5 rounded-lg bg-black/60 p-0.5 backdrop-blur group-hover/file:flex">
+            <button
+              className="rounded-md px-1.5 py-0.5 text-[10px] text-white/80 hover:bg-white/20"
+              title="Replace file"
+              onClick={(e) => {
+                e.stopPropagation()
+                fileInput.current?.click()
+              }}
+            >
+              ↻
+            </button>
+            <button
+              className="rounded-md px-1.5 py-0.5 text-[10px] text-white/80 hover:bg-white/20"
+              title="Remove file"
+              onClick={(e) => {
+                e.stopPropagation()
+                onPatch({ url: '', name: undefined, size: undefined, mime: undefined })
+              }}
+            >
+              ✕
+            </button>
+            <input ref={fileInput} type="file" className="hidden" onChange={onFilePicked} />
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}
diff --git a/packages/react/src/components/ImageBlock.tsx b/packages/react/src/components/ImageBlock.tsx
index 66255a6..8826136 100644
--- a/packages/react/src/components/ImageBlock.tsx
+++ b/packages/react/src/components/ImageBlock.tsx
@@ -1,6 +1,7 @@
-import { useRef, useState } from 'react'
-import { FolderOpen, ImagePlus, Loader2, Upload } from 'lucide-react'
+import { useEffect, useRef, useState } from 'react'
+import { FolderOpen, ImagePlus, Link2, Loader2, Upload } from 'lucide-react'
 import type { Block } from '@xproeditor/core'
+import { fileToObjectUrl, mediaPropsFromFile } from '@xproeditor/core'
 import type { PickMediaFn, UploadFn } from '../types'
 
 export interface ImageBlockProps {
@@ -15,6 +16,8 @@ export interface ImageBlockProps {
 
 const WIDTHS = [40, 60, 80, 100]
 
+type InsertMode = 'upload' | 'library' | 'embed'
+
 export function ImageBlock({
   block,
   selected,
@@ -24,20 +27,28 @@ export function ImageBlock({
   onPatch,
   onSelect,
 }: ImageBlockProps) {
+  const [mode, setMode] = useState<InsertMode>('upload')
   const [uploading, setUploading] = useState(false)
   const [picking, setPicking] = useState(false)
   const [dragOver, setDragOver] = useState(false)
+  const [embedInput, setEmbedInput] = useState('')
+  const [embedError, setEmbedError] = useState('')
+  const embedInputRef = useRef<HTMLInputElement | null>(null)
   const fileInput = useRef<HTMLInputElement | null>(null)
 
   const busy = uploading || picking
 
+  useEffect(() => {
+    if (mode === 'embed') embedInputRef.current?.focus()
+  }, [mode])
+
   async function uploadFile(file: File) {
-    if (!upload || !file.type.startsWith('image/')) return
+    if (!file.type.startsWith('image/')) return
 
     setUploading(true)
     try {
-      const url = await upload(file)
-      onPatch({ url })
+      const url = await (upload ?? fileToObjectUrl)(file)
+      onPatch(mediaPropsFromFile(file, url))
     } finally {
       setUploading(false)
     }
@@ -56,6 +67,19 @@ export function ImageBlock({
     }
   }
 
+  function applyEmbed() {
+    setEmbedError('')
+    const url = embedInput.trim()
+
+    if (!/^https?:\/\//i.test(url)) {
+      setEmbedError('Enter a valid image URL')
+      return
+    }
+
+    onPatch({ url })
+    setEmbedInput('')
+  }
+
   function onFilePicked(e: React.ChangeEvent<HTMLInputElement>) {
     const file = e.target.files?.[0]
     if (file) uploadFile(file)
@@ -67,11 +91,16 @@ export function ImageBlock({
     if (file) uploadFile(file)
   }
 
+  const stop = (e: React.SyntheticEvent) => e.stopPropagation()
+
   if (!block.props.url && !readonly) {
+    const tabClass = (active: boolean) =>
+      `rounded-lg px-2.5 py-1 text-xs font-medium ${active ? 'bg-[var(--xpe-primary-muted)] text-[var(--xpe-primary)]' : 'text-[var(--xpe-muted-foreground)] hover:bg-[var(--xpe-surface-hover)]'}`
+
     return (
       <div className="my-1">
         <div
-          className={`flex flex-col items-center justify-center gap-3 rounded-xl border-2 border-dashed py-8 transition-colors ${dragOver ? 'border-indigo-400 bg-indigo-50/50' : 'border-gray-200 bg-gray-50 hover:border-gray-300'}`}
+          className={`flex flex-col gap-3 rounded-[var(--xpe-radius)] border-2 border-dashed py-6 transition-colors ${dragOver ? 'border-[var(--xpe-ring)] bg-[var(--xpe-primary-muted)]' : 'border-[var(--xpe-border)] bg-[var(--xpe-muted)]'}`}
           onClick={onSelect}
           onDragOver={(e) => {
             e.preventDefault()
@@ -84,47 +113,104 @@ export function ImageBlock({
             onDrop(e)
           }}
         >
-          {busy ? (
-            <Loader2 className="h-6 w-6 animate-spin text-indigo-500" />
-          ) : (
-            <ImagePlus className="h-6 w-6 text-gray-400" />
-          )}
-          <span className="text-sm text-gray-500">{busy ? 'Working...' : 'Add an image'}</span>
+          <div className="flex items-center justify-center gap-2 text-[var(--xpe-muted-foreground)]">
+            {busy ? (
+              <Loader2 className="h-5 w-5 animate-spin text-[var(--xpe-primary)]" />
+            ) : (
+              <ImagePlus className="h-5 w-5" />
+            )}
+            <span className="text-sm">{busy ? 'Working...' : 'Add an image'}</span>
+          </div>
+
           {!busy && (
-            <div className="flex flex-wrap items-center justify-center gap-2">
-              <button
-                type="button"
-                className="inline-flex items-center gap-1.5 rounded-lg border border-gray-200 bg-white px-3 py-1.5 text-xs font-medium text-gray-700 hover:bg-gray-50"
-                onClick={(e) => {
-                  e.stopPropagation()
-                  fileInput.current?.click()
-                }}
-              >
-                <Upload className="h-3.5 w-3.5" />
+            <div
+              className="flex justify-center gap-1 px-4"
+              onClick={stop}
+              onMouseDown={stop}
+              onPointerDown={stop}
+            >
+              <button type="button" className={tabClass(mode === 'upload')} onClick={() => setMode('upload')}>
                 Upload
               </button>
               {pickMedia && (
-                <button
-                  type="button"
-                  className="inline-flex items-center gap-1.5 rounded-lg border border-gray-200 bg-white px-3 py-1.5 text-xs font-medium text-gray-700 hover:bg-gray-50"
-                  onClick={(e) => {
-                    e.stopPropagation()
-                    pickFromLibrary()
-                  }}
-                >
-                  <FolderOpen className="h-3.5 w-3.5" />
+                <button type="button" className={tabClass(mode === 'library')} onClick={() => setMode('library')}>
                   Library
                 </button>
               )}
+              <button type="button" className={tabClass(mode === 'embed')} onClick={() => setMode('embed')}>
+                Link
+              </button>
+            </div>
+          )}
+
+          {!busy && (
+            <div className="px-4" onClick={stop} onMouseDown={stop} onPointerDown={stop}>
+              {mode === 'upload' && (
+                <div className="flex justify-center">
+                  <button
+                    type="button"
+                    className="inline-flex items-center gap-1.5 rounded-lg border border-[var(--xpe-border)] bg-[var(--xpe-surface)] px-3 py-1.5 text-xs font-medium text-[var(--xpe-foreground)] hover:bg-[var(--xpe-surface-hover)]"
+                    onClick={() => fileInput.current?.click()}
+                  >
+                    <Upload className="h-3.5 w-3.5" />
+                    Choose image
+                  </button>
+                  <input
+                    ref={fileInput}
+                    type="file"
+                    accept="image/*"
+                    className="hidden"
+                    onChange={onFilePicked}
+                  />
+                </div>
+              )}
+
+              {mode === 'library' && (
+                <div className="flex justify-center">
+                  <button
+                    type="button"
+                    className="inline-flex items-center gap-1.5 rounded-lg border border-[var(--xpe-border)] bg-[var(--xpe-surface)] px-3 py-1.5 text-xs font-medium text-[var(--xpe-foreground)] hover:bg-[var(--xpe-surface-hover)]"
+                    onClick={pickFromLibrary}
+                  >
+                    <FolderOpen className="h-3.5 w-3.5" />
+                    Open media library
+                  </button>
+                </div>
+              )}
+
+              {mode === 'embed' && (
+                <div className="space-y-2">
+                  <div className="flex items-center gap-2">
+                    <Link2 className="h-4 w-4 shrink-0 text-[var(--xpe-muted-foreground)]" />
+                    <input
+                      ref={embedInputRef}
+                      value={embedInput}
+                      type="url"
+                      className="min-w-0 flex-1 rounded-lg border border-[var(--xpe-border)] bg-[var(--xpe-surface)] px-2.5 py-1.5 text-xs text-[var(--xpe-foreground)] outline-none focus:border-[var(--xpe-ring)]"
+                      placeholder="Paste an image URL"
+                      onChange={(e) => setEmbedInput(e.target.value)}
+                      onKeyDown={(e) => {
+                        if (e.key === 'Enter') {
+                          e.preventDefault()
+                          applyEmbed()
+                        }
+                      }}
+                    />
+                    <button
+                      type="button"
+                      className="rounded-lg bg-[var(--xpe-primary)] px-2.5 py-1.5 text-xs text-[var(--xpe-primary-foreground)]"
+                      onClick={applyEmbed}
+                    >
+                      Add
+                    </button>
+                  </div>
+                  {embedError && (
+                    <p className="text-center text-xs text-[var(--xpe-danger)]">{embedError}</p>
+                  )}
+                </div>
+              )}
             </div>
           )}
-          <input
-            ref={fileInput}
-            type="file"
-            accept="image/*"
-            className="hidden"
-            onChange={onFilePicked}
-          />
         </div>
       </div>
     )
@@ -137,7 +223,7 @@ export function ImageBlock({
           <img
             src={block.props.url}
             alt={block.props.caption || ''}
-            className={`w-full rounded-xl transition-shadow ${selected ? 'ring-2 ring-indigo-400' : ''}`}
+            className={`w-full rounded-[var(--xpe-radius)] transition-shadow ${selected ? 'ring-2 ring-[var(--xpe-ring)]' : ''}`}
             draggable={false}
           />
         </div>
@@ -192,7 +278,7 @@ export function ImageBlock({
           onPointerDown={(e) => e.stopPropagation()}
         >
           <input
-            className="mt-1.5 w-full bg-transparent text-center text-xs text-gray-400 outline-none placeholder:text-gray-300"
+            className="mt-1.5 w-full bg-transparent text-center text-xs text-[var(--xpe-muted-foreground)] outline-none placeholder:opacity-60"
             defaultValue={block.props.caption ?? ''}
             placeholder="Add caption..."
             readOnly={readonly}
diff --git a/packages/react/src/components/SlashMenu.tsx b/packages/react/src/components/SlashMenu.tsx
index bb2632d..3c00bf9 100644
--- a/packages/react/src/components/SlashMenu.tsx
+++ b/packages/react/src/components/SlashMenu.tsx
@@ -1,4 +1,12 @@
-import { forwardRef, useEffect, useImperativeHandle, useMemo, useRef, useState } from 'react'
+import {
+  forwardRef,
+  useEffect,
+  useImperativeHandle,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react'
 import { createPortal } from 'react-dom'
 import {
   Type,
@@ -18,6 +26,9 @@ import {
   Table2,
   Smile,
   Blocks,
+  Music,
+  Paperclip,
+  SearchX,
 } from 'lucide-react'
 import type { SlashItem } from '../types'
 
@@ -152,6 +163,22 @@ const ITEMS: SlashItem[] = [
     keywords: ['video', 'youtube', 'vimeo', 'movie'],
     icon: Video,
   },
+  {
+    id: 'audio',
+    type: 'audio',
+    label: 'Audio',
+    description: 'Upload or link audio',
+    keywords: ['audio', 'music', 'song', 'sound', 'mp3'],
+    icon: Music,
+  },
+  {
+    id: 'file',
+    type: 'file',
+    label: 'File',
+    description: 'Attach a downloadable file',
+    keywords: ['file', 'attachment', 'pdf', 'document', 'download'],
+    icon: Paperclip,
+  },
   {
     id: 'table',
     type: 'table',
@@ -169,17 +196,24 @@ export interface SlashMenuHandle {
 
 export interface SlashMenuProps {
   query: string
-  position: { x: number; y: number }
+  /** Caret anchor in viewport coordinates: menu opens below `y`, flips above `top` when needed. */
+  position: { x: number; y: number; top?: number }
+  dir?: 'ltr' | 'rtl'
   onSelect: (item: SlashItem) => void
   onClose: () => void
 }
 
 export const SlashMenu = forwardRef<SlashMenuHandle, SlashMenuProps>(function SlashMenu(
-  { query, position, onSelect, onClose },
+  { query, position, dir, onSelect },
   ref,
 ) {
   const [activeIndex, setActiveIndex] = useState(0)
+  const [placed, setPlaced] = useState<{ left: number; top: number }>({
+    left: position.x,
+    top: position.y,
+  })
   const listRef = useRef<HTMLDivElement | null>(null)
+  const menuRef = useRef<HTMLDivElement | null>(null)
 
   const filtered = useMemo(() => {
     const q = query.toLowerCase().trim()
@@ -191,10 +225,37 @@ export const SlashMenu = forwardRef<SlashMenuHandle, SlashMenuProps>(function Sl
 
   useEffect(() => setActiveIndex(0), [query])
 
-  useEffect(() => {
-    if (filtered.length === 0) onClose()
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [filtered])
+  // Place the menu with its real measured size: below the caret when it fits,
+  // flipped above otherwise, clamped to the viewport. In RTL the menu grows
+  // toward the start (its end edge hugs the caret).
+  useLayoutEffect(() => {
+    function place() {
+      const el = menuRef.current
+      if (!el) return
+
+      const margin = 8
+      const gap = 6
+      const { width, height } = el.getBoundingClientRect()
+      const anchorTop = position.top ?? position.y
+      let left = dir === 'rtl' ? position.x - width : position.x
+      left = Math.max(margin, Math.min(left, window.innerWidth - width - margin))
+      let top = position.y + gap
+
+      if (top + height > window.innerHeight - margin) {
+        top = Math.max(margin, anchorTop - height - gap)
+      }
+
+      setPlaced({ left, top })
+    }
+
+    place()
+    window.addEventListener('resize', place)
+    window.addEventListener('scroll', place, true)
+    return () => {
+      window.removeEventListener('resize', place)
+      window.removeEventListener('scroll', place, true)
+    }
+  }, [position, dir, filtered.length])
 
   function scrollActiveIntoView() {
     requestAnimationFrame(() => {
@@ -222,32 +283,44 @@ export const SlashMenu = forwardRef<SlashMenuHandle, SlashMenuProps>(function Sl
 
   return createPortal(
     <div
-      className="fixed z-[80] w-72 max-h-80 overflow-y-auto bg-white border border-gray-100 rounded-xl shadow-xl py-1.5"
-      style={{ left: position.x, top: position.y }}
+      ref={menuRef}
+      className="fixed z-[80] w-72 max-h-80 overflow-y-auto border py-1.5 bg-[var(--xpe-surface)] border-[var(--xpe-border)] rounded-[var(--xpe-radius)] [box-shadow:var(--xpe-shadow)]"
+      style={{ left: placed.left, top: placed.top }}
+      dir={dir}
       onMouseDown={(e) => e.preventDefault()}
     >
-      <p className="px-3 pt-1 pb-1.5 text-[10px] font-semibold uppercase tracking-wider text-gray-400">
+      <p className="px-3 pt-1 pb-1.5 text-[10px] font-semibold uppercase tracking-wider text-[var(--xpe-muted-foreground)]">
         Blocks
       </p>
+      {filtered.length === 0 && (
+        <div className="flex items-center gap-2 px-3 py-3 text-[13px] text-[var(--xpe-muted-foreground)]">
+          <SearchX className="w-4 h-4" />
+          No results for “{query}”
+        </div>
+      )}
       <div ref={listRef}>
         {filtered.map((item, idx) => {
           const Icon = item.icon
           return (
             <button
               key={item.id}
-              className={`flex items-center gap-3 w-full px-3 py-1.5 text-left transition-colors ${idx === activeIndex ? 'bg-indigo-50' : 'hover:bg-gray-50'}`}
+              className={`flex items-center gap-3 w-full px-3 py-1.5 text-start transition-colors ${idx === activeIndex ? 'bg-[var(--xpe-primary-muted)]' : 'hover:bg-[var(--xpe-surface-hover)]'}`}
               data-active={idx === activeIndex}
               onMouseEnter={() => setActiveIndex(idx)}
               onClick={() => onSelect(item)}
             >
               <span
-                className={`flex items-center justify-center w-8 h-8 rounded-lg border shrink-0 ${idx === activeIndex ? 'border-indigo-100 bg-white text-indigo-600' : 'border-gray-100 bg-gray-50 text-gray-500'}`}
+                className={`flex items-center justify-center w-8 h-8 rounded-lg border shrink-0 ${idx === activeIndex ? 'border-[var(--xpe-border)] bg-[var(--xpe-surface)] text-[var(--xpe-primary)]' : 'border-[var(--xpe-border)] bg-[var(--xpe-muted)] text-[var(--xpe-muted-foreground)]'}`}
               >
                 <Icon className="w-4 h-4" />
               </span>
               <span className="min-w-0">
-                <span className="block text-[13px] font-medium text-gray-800">{item.label}</span>
-                <span className="block text-[11px] text-gray-400 truncate">{item.description}</span>
+                <span className="block text-[13px] font-medium text-[var(--xpe-foreground)]">
+                  {item.label}
+                </span>
+                <span className="block text-[11px] text-[var(--xpe-muted-foreground)] truncate">
+                  {item.description}
+                </span>
               </span>
             </button>
           )
diff --git a/packages/react/src/components/VideoBlock.tsx b/packages/react/src/components/VideoBlock.tsx
index 38945e3..fdd194b 100644
--- a/packages/react/src/components/VideoBlock.tsx
+++ b/packages/react/src/components/VideoBlock.tsx
@@ -1,6 +1,6 @@
 import { useRef, useState } from 'react'
 import { FolderOpen, Link2, Loader2, Upload, Video } from 'lucide-react'
-import { isAllowedEmbedUrl, parseVideoEmbed } from '@xproeditor/core'
+import { fileToObjectUrl, isAllowedEmbedUrl, mediaPropsFromFile, parseVideoEmbed } from '@xproeditor/core'
 import type { Block } from '@xproeditor/core'
 import type { PickMediaFn, UploadFn } from '../types'
 
@@ -43,12 +43,12 @@ export function VideoBlock({
   }
 
   async function uploadFile(file: File) {
-    if (!upload || !file.type.startsWith('video/')) return
+    if (!file.type.startsWith('video/')) return
 
     setUploading(true)
     try {
-      const url = await upload(file)
-      onPatch({ url, provider: 'file' })
+      const url = await (upload ?? fileToObjectUrl)(file)
+      onPatch({ ...mediaPropsFromFile(file, url), provider: 'file' })
     } finally {
       setUploading(false)
     }
@@ -104,7 +104,7 @@ export function VideoBlock({
     return (
       <div className="my-1">
         <div
-          className={`flex flex-col gap-3 rounded-xl border-2 border-dashed py-6 transition-colors ${dragOver ? 'border-indigo-400 bg-indigo-50/50' : 'border-gray-200 bg-gray-50 hover:border-gray-300'}`}
+          className={`flex flex-col gap-3 rounded-[var(--xpe-radius)] border-2 border-dashed py-6 transition-colors ${dragOver ? 'border-[var(--xpe-ring)] bg-[var(--xpe-primary-muted)]' : 'border-[var(--xpe-border)] bg-[var(--xpe-muted)]'}`}
           onClick={onSelect}
           onDragOver={(e) => {
             e.preventDefault()
@@ -117,9 +117,9 @@ export function VideoBlock({
             onDrop(e)
           }}
         >
-          <div className="flex items-center justify-center gap-2 text-gray-500">
+          <div className="flex items-center justify-center gap-2 text-[var(--xpe-muted-foreground)]">
             {busy ? (
-              <Loader2 className="h-5 w-5 animate-spin text-indigo-500" />
+              <Loader2 className="h-5 w-5 animate-spin text-[var(--xpe-primary)]" />
             ) : (
               <Video className="h-5 w-5" />
             )}
@@ -134,7 +134,7 @@ export function VideoBlock({
             >
               <button
                 type="button"
-                className={`rounded-lg px-2.5 py-1 text-xs font-medium ${mode === 'upload' ? 'bg-indigo-100 text-indigo-700' : 'text-gray-500 hover:bg-gray-100'}`}
+                className={`rounded-lg px-2.5 py-1 text-xs font-medium ${mode === 'upload' ? 'bg-[var(--xpe-primary-muted)] text-[var(--xpe-primary)]' : 'text-[var(--xpe-muted-foreground)] hover:bg-[var(--xpe-surface-hover)]'}`}
                 onClick={(e) => {
                   e.stopPropagation()
                   switchMode('upload')
@@ -145,7 +145,7 @@ export function VideoBlock({
               {pickMedia && (
                 <button
                   type="button"
-                  className={`rounded-lg px-2.5 py-1 text-xs font-medium ${mode === 'library' ? 'bg-indigo-100 text-indigo-700' : 'text-gray-500 hover:bg-gray-100'}`}
+                  className={`rounded-lg px-2.5 py-1 text-xs font-medium ${mode === 'library' ? 'bg-[var(--xpe-primary-muted)] text-[var(--xpe-primary)]' : 'text-[var(--xpe-muted-foreground)] hover:bg-[var(--xpe-surface-hover)]'}`}
                   onClick={(e) => {
                     e.stopPropagation()
                     switchMode('library')
@@ -156,7 +156,7 @@ export function VideoBlock({
               )}
               <button
                 type="button"
-                className={`rounded-lg px-2.5 py-1 text-xs font-medium ${mode === 'embed' ? 'bg-indigo-100 text-indigo-700' : 'text-gray-500 hover:bg-gray-100'}`}
+                className={`rounded-lg px-2.5 py-1 text-xs font-medium ${mode === 'embed' ? 'bg-[var(--xpe-primary-muted)] text-[var(--xpe-primary)]' : 'text-[var(--xpe-muted-foreground)] hover:bg-[var(--xpe-surface-hover)]'}`}
                 onClick={(e) => {
                   e.stopPropagation()
                   switchMode('embed')
@@ -177,7 +177,7 @@ export function VideoBlock({
                 <div className="flex justify-center">
                   <button
                     type="button"
-                    className="inline-flex items-center gap-1.5 rounded-lg border border-gray-200 bg-white px-3 py-1.5 text-xs font-medium text-gray-700 hover:bg-gray-50"
+                    className="inline-flex items-center gap-1.5 rounded-lg border border-[var(--xpe-border)] bg-[var(--xpe-surface)] px-3 py-1.5 text-xs font-medium text-[var(--xpe-foreground)] hover:bg-[var(--xpe-surface-hover)]"
                     onClick={(e) => {
                       e.stopPropagation()
                       fileInput.current?.click()
@@ -200,7 +200,7 @@ export function VideoBlock({
                 <div className="flex justify-center">
                   <button
                     type="button"
-                    className="inline-flex items-center gap-1.5 rounded-lg border border-gray-200 bg-white px-3 py-1.5 text-xs font-medium text-gray-700 hover:bg-gray-50"
+                    className="inline-flex items-center gap-1.5 rounded-lg border border-[var(--xpe-border)] bg-[var(--xpe-surface)] px-3 py-1.5 text-xs font-medium text-[var(--xpe-foreground)] hover:bg-[var(--xpe-surface-hover)]"
                     onClick={(e) => {
                       e.stopPropagation()
                       pickFromLibrary()
@@ -215,11 +215,11 @@ export function VideoBlock({
               {mode === 'embed' && (
                 <div className="space-y-2">
                   <div className="flex items-center gap-2">
-                    <Link2 className="h-4 w-4 shrink-0 text-gray-400" />
+                    <Link2 className="h-4 w-4 shrink-0 text-[var(--xpe-muted-foreground)]" />
                     <input
                       ref={embedInputRef}
                       type="url"
-                      className="min-w-0 flex-1 rounded-lg border border-gray-200 bg-white px-2.5 py-1.5 text-xs outline-none focus:border-indigo-300"
+                      className="min-w-0 flex-1 rounded-lg border border-[var(--xpe-border)] bg-[var(--xpe-surface)] px-2.5 py-1.5 text-xs text-[var(--xpe-foreground)] outline-none focus:border-[var(--xpe-ring)]"
                       placeholder="YouTube or Vimeo URL"
                       value={embedInput}
                       onChange={(e) => setEmbedInput(e.target.value)}
@@ -232,7 +232,7 @@ export function VideoBlock({
                     />
                     <button
                       type="button"
-                      className="rounded-lg bg-gray-800 px-2.5 py-1.5 text-xs text-white"
+                      className="rounded-lg bg-[var(--xpe-primary)] px-2.5 py-1.5 text-xs text-[var(--xpe-primary-foreground)]"
                       onClick={(e) => {
                         e.stopPropagation()
                         applyEmbed()
@@ -241,7 +241,7 @@ export function VideoBlock({
                       Add
                     </button>
                   </div>
-                  {embedError && <p className="text-center text-xs text-red-500">{embedError}</p>}
+                  {embedError && <p className="text-center text-xs text-[var(--xpe-danger)]">{embedError}</p>}
                 </div>
               )}
             </div>
@@ -256,7 +256,7 @@ export function VideoBlock({
       <figure className="group/video relative" style={{ width: `${block.props.width ?? 100}%` }}>
         <div onClick={onSelect}>
           <div
-            className={`overflow-hidden rounded-xl bg-black ${selected ? 'ring-2 ring-indigo-400' : ''}`}
+            className={`overflow-hidden rounded-[var(--xpe-radius)] bg-black ${selected ? 'ring-2 ring-[var(--xpe-ring)]' : ''}`}
           >
             {isEmbed && safeEmbedUrl() ? (
               <iframe
@@ -305,7 +305,7 @@ export function VideoBlock({
           onPointerDown={(e) => e.stopPropagation()}
         >
           <input
-            className="mt-1.5 w-full bg-transparent text-center text-xs text-gray-400 outline-none placeholder:text-gray-300"
+            className="mt-1.5 w-full bg-transparent text-center text-xs text-[var(--xpe-muted-foreground)] outline-none placeholder:opacity-60"
             defaultValue={block.props.caption ?? ''}
             placeholder="Add caption..."
             readOnly={readonly}
diff --git a/packages/react/src/components/toolbar/TableStylePanel.tsx b/packages/react/src/components/toolbar/TableStylePanel.tsx
index 8366e2e..06c8f42 100644
--- a/packages/react/src/components/toolbar/TableStylePanel.tsx
+++ b/packages/react/src/components/toolbar/TableStylePanel.tsx
@@ -129,7 +129,7 @@ export function TableStylePanel({
             >
               A
               {isPresetActive(color, currentColor) && (
-                <Check className="absolute -top-1 -right-1 size-3 rounded-full bg-indigo-500 p-0.5 text-white" />
+                <Check className="absolute -top-1 -end-1 size-3 rounded-full bg-indigo-500 p-0.5 text-white" />
               )}
             </button>
           ))}
diff --git a/packages/react/src/components/toolbar/ToolbarColorPanel.tsx b/packages/react/src/components/toolbar/ToolbarColorPanel.tsx
index 09b9f6f..66d6d2f 100644
--- a/packages/react/src/components/toolbar/ToolbarColorPanel.tsx
+++ b/packages/react/src/components/toolbar/ToolbarColorPanel.tsx
@@ -131,7 +131,7 @@ export function ToolbarColorPanel({
             >
               A
               {isPresetActive(color, activeTextColor) && (
-                <Check className="absolute -top-1 -right-1 size-3 rounded-full bg-indigo-500 p-0.5 text-white" />
+                <Check className="absolute -top-1 -end-1 size-3 rounded-full bg-indigo-500 p-0.5 text-white" />
               )}
             </button>
           ))}
@@ -176,7 +176,7 @@ export function ToolbarColorPanel({
               onClick={() => selectHighlight(color)}
             >
               {isPresetActive(color, activeHighlight) && (
-                <Check className="absolute -top-1 -right-1 size-3 rounded-full bg-indigo-500 p-0.5 text-white" />
+                <Check className="absolute -top-1 -end-1 size-3 rounded-full bg-indigo-500 p-0.5 text-white" />
               )}
             </button>
           ))}
@@ -204,7 +204,7 @@ export function ToolbarColorPanel({
             className="h-7 w-full text-xs text-gray-500"
             onClick={resetCurrent}
           >
-            <Highlighter className="mr-1.5 size-3" />
+            <Highlighter className="me-1.5 size-3" />
             Remove highlight
           </Button>
         )}
diff --git a/packages/react/src/hooks/useBlockEditor.ts b/packages/react/src/hooks/useBlockEditor.ts
index 41f52d4..bbe0258 100644
--- a/packages/react/src/hooks/useBlockEditor.ts
+++ b/packages/react/src/hooks/useBlockEditor.ts
@@ -2,14 +2,15 @@ import { useEffect, useMemo, useRef, useState } from 'react'
 import {
   applyMarkToRange,
   applyMarkToTextRange,
+  blockTypeForFile,
   caretPointFromClient,
   cloneBlock,
   computeListNumbering,
   createBlock,
   deleteRangeInSpans,
   deleteTextRange,
-  detectDir,
   extractTextRangeAsBlocks,
+  fileToObjectUrl,
   fullBlockTextRange,
   getCaretClientRect,
   getSelectionClientRect,
@@ -19,6 +20,7 @@ import {
   isCrossBlockTextRange,
   isTextBlock,
   isTextRangeCollapsed,
+  mediaPropsFromFile,
   normalizeSpans,
   normalizeTableData,
   nextVisibleCellCoord,
@@ -73,7 +75,7 @@ interface SlashState {
   blockId: string
   index: number
   query: string
-  position: { x: number; y: number }
+  position: { x: number; y: number; top?: number }
 }
 
 interface BubbleState {
@@ -526,12 +528,10 @@ export function useBlockEditor(options: UseBlockEditorOptions) {
     setSlashState(null)
   }
 
-  function slashPosition(): { x: number; y: number } {
+  function slashPosition(): { x: number; y: number; top?: number } {
+    // Raw caret anchor; the menu measures itself and flips/clamps to the viewport.
     const rect = getCaretClientRect()
-    const x = Math.min(rect?.left ?? 100, window.innerWidth - 300)
-    let y = (rect?.bottom ?? 100) + 6
-    if (y + 330 > window.innerHeight) y = Math.max(8, (rect?.top ?? 100) - 336)
-    return { x, y }
+    return { x: rect?.left ?? 100, y: rect?.bottom ?? 100, top: rect?.top ?? 100 }
   }
 
   function updateSlash(block: Block, spans: InlineSpan[], caret: number | null) {
@@ -569,7 +569,7 @@ export function useBlockEditor(options: UseBlockEditorOptions) {
 
     const removeEnd = state.index + 1 + state.query.length
     const spans = deleteRangeInSpans(block.content, state.index, removeEnd)
-    const isInsertType = ['divider', 'image', 'video', 'table', 'code'].includes(item.type)
+    const isInsertType = ['divider', 'image', 'video', 'audio', 'file', 'table', 'code'].includes(item.type)
 
     if (!isInsertType) {
       const defaults = makeBlockLocal(item.type)
@@ -651,12 +651,9 @@ export function useBlockEditor(options: UseBlockEditorOptions) {
 
     block.content = spans
 
-    if (isTextBlock(block.type)) {
-      const text = spansToText(spans)
-      if (!block.props.dir || block.props.dir === 'auto') {
-        if (text.trim()) block.props.dir = detectDir(text)
-      }
-    }
+    // Direction stays 'auto' unless the user sets it explicitly — rendering
+    // resolves it live from content (resolveBlockDirection), so a block flips
+    // between RTL and LTR as its text changes instead of locking on first input.
 
     if (tryMarkdownShortcut(block, spans, caret)) {
       closeSlash()
@@ -825,6 +822,21 @@ export function useBlockEditor(options: UseBlockEditorOptions) {
     return normalizeSpans([...before, ...inserted, ...after])
   }
 
+  /** Insert dropped/pasted files as media blocks (image/video/audio/file by MIME). */
+  async function insertFileBlocks(files: File[], at: number) {
+    const doUpload = upload ?? fileToObjectUrl
+
+    for (const [i, file] of files.entries()) {
+      const type = blockTypeForFile(file)
+      const url = await doUpload(file)
+      const media = mediaPropsFromFile(file, url)
+      const extra = type === 'video' ? { provider: 'file' as const } : {}
+      blocksRef.current.splice(at + i, 0, makeBlockLocal(type, { props: { ...media, ...extra } }))
+    }
+
+    pushHistory(true)
+  }
+
   async function handlePasted(
     block: Block,
     payload: { html: string; text: string; files: File[]; offsets: { start: number; end: number } },
@@ -832,28 +844,9 @@ export function useBlockEditor(options: UseBlockEditorOptions) {
     const idx = blocksRef.current.indexOf(block)
     if (idx === -1) return
 
-    const imageFiles = payload.files.filter((f) => f.type.startsWith('image/'))
-    const videoFiles = payload.files.filter((f) => f.type.startsWith('video/'))
-
-    if (videoFiles.length > 0 && upload) {
-      for (const [i, file] of videoFiles.entries()) {
-        const url = await upload(file)
-        blocksRef.current.splice(
-          idx + 1 + i,
-          0,
-          makeBlockLocal('video', { props: { url, provider: 'file' } }),
-        )
-      }
-      pushHistory(true)
-      return
-    }
-
-    if (imageFiles.length > 0 && upload) {
-      for (const [i, file] of imageFiles.entries()) {
-        const url = await upload(file)
-        blocksRef.current.splice(idx + 1 + i, 0, makeBlockLocal('image', { props: { url } }))
-      }
-      pushHistory(true)
+    // Files (image / video / audio / anything else) become media blocks
+    if (payload.files.length > 0) {
+      await insertFileBlocks(payload.files, idx + 1)
       return
     }
 
@@ -1773,8 +1766,31 @@ export function useBlockEditor(options: UseBlockEditorOptions) {
     }
   }
 
+  function isExternalFileDrag(e: React.DragEvent): boolean {
+    return !draggingId && Array.from(e.dataTransfer?.types ?? []).includes('Files')
+  }
+
   function onDragOver(e: React.DragEvent) {
-    if (readonly || !draggingId) return
+    if (readonly) return
+
+    if (isExternalFileDrag(e)) {
+      e.preventDefault()
+      if (e.dataTransfer) e.dataTransfer.dropEffect = 'copy'
+
+      const target = (e.target as HTMLElement).closest('[data-block-id]')
+      const id = target?.getAttribute('data-block-id')
+
+      if (id) {
+        const rect = target!.getBoundingClientRect()
+        setDropTarget({ id, position: e.clientY < rect.top + rect.height / 2 ? 'before' : 'after' })
+      } else {
+        setDropTarget(null)
+      }
+
+      return
+    }
+
+    if (!draggingId) return
 
     e.preventDefault()
     if (e.dataTransfer) e.dataTransfer.dropEffect = 'move'
@@ -1800,6 +1816,25 @@ export function useBlockEditor(options: UseBlockEditorOptions) {
     if (readonly) return
 
     e.preventDefault()
+
+    // External OS files dropped onto the editor become media blocks
+    const externalFiles = !draggingId ? Array.from(e.dataTransfer?.files ?? []) : []
+
+    if (externalFiles.length > 0) {
+      const target = dropTarget
+      setDropTarget(null)
+      let at = blocksRef.current.length
+
+      if (target) {
+        const idx = blocksRef.current.findIndex((b) => b.id === target.id)
+        if (idx !== -1) at = target.position === 'before' ? idx : idx + 1
+      }
+
+      void insertFileBlocks(externalFiles, at)
+
+      return
+    }
+
     const from = draggingId
     const target = dropTarget
     setDraggingId(null)
diff --git a/packages/react/src/styles/components.css b/packages/react/src/styles/components.css
index 387ccff..5ef767c 100644
--- a/packages/react/src/styles/components.css
+++ b/packages/react/src/styles/components.css
@@ -259,6 +259,13 @@
 .db-figure { margin: 1.4em 0; }
 .db-img { border-radius: 0.75rem; cursor: zoom-in; display: block; margin: 0 auto; height: auto; max-width: 100%; }
 .db-caption { margin-top: 0.5em; text-align: center; font-size: 0.8em; color: var(--xpe-muted-foreground); }
+.db-audio-wrap { background: var(--xpe-muted); border: 1px solid var(--xpe-border); border-radius: var(--xpe-radius, 0.75rem); padding: 0.75rem; }
+.db-audio-wrap audio { width: 100%; }
+.db-audio-name { font-size: 0.85em; font-weight: 500; margin-bottom: 0.5em; color: var(--xpe-foreground); }
+.db-file { display: flex; align-items: center; gap: 0.75rem; margin: 0.75em 0; padding: 0.65rem 0.9rem; background: var(--xpe-muted); border: 1px solid var(--xpe-border); border-radius: var(--xpe-radius, 0.75rem); text-decoration: none; color: var(--xpe-foreground); }
+.db-file:hover { border-color: var(--xpe-primary); }
+.db-file-name { font-size: 0.9em; font-weight: 500; flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.db-file-size { font-size: 0.8em; color: var(--xpe-muted-foreground); flex-shrink: 0; }
 .db-table-wrap { overflow-x: auto; margin: 1.25em 0; }
 .db-table { width: 100%; border-collapse: collapse; border-radius: 0.5rem; overflow: hidden; }
 .db-table th, .db-table td { padding: 0.55em 1em; text-align: start; vertical-align: top; line-height: 1.6; font-size: 0.9em; }
diff --git a/packages/react/src/styles/theme.css b/packages/react/src/styles/theme.css
index 9bc7128..2a6d63d 100644
--- a/packages/react/src/styles/theme.css
+++ b/packages/react/src/styles/theme.css
@@ -10,5 +10,43 @@
   --xpe-muted: #f3f4f6;
   --xpe-border: #e5e7eb;
   --xpe-primary: #4f46e5;
+  --xpe-primary-foreground: #ffffff;
+  /* subtle tint behind active/selected menu rows and drop zones */
+  --xpe-primary-muted: #eef2ff;
+  /* elevated surfaces: popovers, menus, dialogs */
+  --xpe-surface: #ffffff;
+  --xpe-surface-hover: #f9fafb;
+  /* focus/selection ring around media blocks */
+  --xpe-ring: #818cf8;
+  --xpe-danger: #ef4444;
+  --xpe-radius: 12px;
+  --xpe-shadow:
+    0 10px 15px -3px rgb(0 0 0 / 0.1),
+    0 4px 6px -4px rgb(0 0 0 / 0.05);
   --xpe-font-mono: ui-monospace, SFMono-Regular, Menlo, monospace;
 }
+
+/**
+ * Built-in dark theme. Add the `xpe-dark` class (or `data-xpe-theme="dark"`)
+ * to any ancestor of the editor — typically alongside your app's own dark
+ * mode toggle. Apps with custom palettes can override the same variables
+ * under their own selector instead.
+ */
+.xpe-dark,
+[data-xpe-theme='dark'] {
+  --xpe-background: #111827;
+  --xpe-foreground: #e5e7eb;
+  --xpe-muted-foreground: #9ca3af;
+  --xpe-muted: #1f2937;
+  --xpe-border: #374151;
+  --xpe-primary: #818cf8;
+  --xpe-primary-foreground: #111827;
+  --xpe-primary-muted: rgb(129 140 248 / 0.15);
+  --xpe-surface: #1f2937;
+  --xpe-surface-hover: #273449;
+  --xpe-ring: #6366f1;
+  --xpe-danger: #f87171;
+  --xpe-shadow:
+    0 10px 15px -3px rgb(0 0 0 / 0.5),
+    0 4px 6px -4px rgb(0 0 0 / 0.4);
+}
diff --git a/packages/vue/src/components/BlockEditor.vue b/packages/vue/src/components/BlockEditor.vue
index 61c6ea0..7b9460b 100644
--- a/packages/vue/src/components/BlockEditor.vue
+++ b/packages/vue/src/components/BlockEditor.vue
@@ -8,7 +8,7 @@ import {
   getSelectionClientRect,
   htmlToBlocks,
   createBlock, cloneBlock, spansToText, splitSpansAt, normalizeSpans,
-  deleteRangeInSpans, applyMarkToRange, rangeHasMark, rangeMarkValue, sliceSpans, detectDir,
+  deleteRangeInSpans, applyMarkToRange, rangeHasMark, rangeMarkValue, sliceSpans,
   applyMarkToTextRange,
   deleteTextRange,
   extractTextRangeAsBlocks,
@@ -26,6 +26,9 @@ import {
   patchTableCellsBackground,
   patchTableStyle,
   isTextBlock,
+  blockTypeForFile,
+  fileToObjectUrl,
+  mediaPropsFromFile,
 } from '@xproeditor/core'
 import type { TextPoint, TextRangeSelection, Block, BlockType, InlineSpan, MarkName, TableCellCoord, TableCellAlign, TableStyle } from '@xproeditor/core'
 import EditorBlockItem from './EditorBlockItem.vue'
@@ -525,7 +528,7 @@ interface SlashState {
   blockId: string
   index: number
   query: string
-  position: { x: number; y: number }
+  position: { x: number; y: number; top?: number }
 }
 
 const slashState = ref<SlashState | null>(null)
@@ -536,16 +539,11 @@ function closeSlash() {
   slashState.value = null
 }
 
-function slashPosition(): { x: number; y: number } {
+function slashPosition(): { x: number; y: number; top?: number } {
+  // Raw caret anchor; the menu measures itself and flips/clamps to the viewport.
   const rect = getCaretClientRect()
-  const x = Math.min(rect?.left ?? 100, window.innerWidth - 300)
-  let y = (rect?.bottom ?? 100) + 6
-
-  if (y + 330 > window.innerHeight) {
-y = Math.max(8, (rect?.top ?? 100) - 336)
-}
 
-  return { x, y }
+  return { x: rect?.left ?? 100, y: rect?.bottom ?? 100, top: rect?.top ?? 100 }
 }
 
 function updateSlash(block: Block, spans: InlineSpan[], caret: number | null) {
@@ -597,7 +595,7 @@ return
 
   const removeEnd = state.index + 1 + state.query.length
   const spans = deleteRangeInSpans(block.content, state.index, removeEnd)
-  const isInsertType = ['divider', 'image', 'video', 'table', 'code'].includes(item.type)
+  const isInsertType = ['divider', 'image', 'video', 'audio', 'file', 'table', 'code'].includes(item.type)
 
   if (!isInsertType) {
     const defaults = makeBlock(item.type)
@@ -703,15 +701,9 @@ return
 
   block.content = spans
 
-  if (isTextBlock(block.type)) {
-    const text = spansToText(spans)
-
-    if (!block.props.dir || block.props.dir === 'auto') {
-      if (text.trim()) {
-        block.props.dir = detectDir(text)
-      }
-    }
-  }
+  // Direction stays 'auto' unless the user sets it explicitly — rendering
+  // resolves it live from content (resolveBlockDirection), so a block flips
+  // between RTL and LTR as its text changes instead of locking on first input.
 
   if (tryMarkdownShortcut(block, spans, caret)) {
     closeSlash()
@@ -933,6 +925,21 @@ function insertSpansAt(content: InlineSpan[], offset: number, inserted: InlineSp
   return normalizeSpans([...before, ...inserted, ...after])
 }
 
+/** Insert dropped/pasted files as media blocks (image/video/audio/file by MIME). */
+async function insertFileBlocks(files: File[], at: number) {
+  const doUpload = props.upload ?? fileToObjectUrl
+
+  for (const [i, file] of files.entries()) {
+    const type = blockTypeForFile(file)
+    const url = await doUpload(file)
+    const media = mediaPropsFromFile(file, url)
+    const extra = type === 'video' ? { provider: 'file' as const } : {}
+    blocks.value.splice(at + i, 0, makeBlock(type, { props: { ...media, ...extra } }))
+  }
+
+  pushHistory(true)
+}
+
 async function handlePasted(
   block: Block,
   payload: { html: string; text: string; files: File[]; offsets: { start: number; end: number } },
@@ -943,28 +950,9 @@ async function handlePasted(
 return
 }
 
-  // Image files
-  const imageFiles = payload.files.filter(f => f.type.startsWith('image/'))
-  const videoFiles = payload.files.filter(f => f.type.startsWith('video/'))
-
-  if (videoFiles.length > 0 && props.upload) {
-    for (const [i, file] of videoFiles.entries()) {
-      const url = await props.upload(file)
-      blocks.value.splice(idx + 1 + i, 0, makeBlock('video', { props: { url, provider: 'file' } }))
-    }
-
-    pushHistory(true)
-
-    return
-  }
-
-  if (imageFiles.length > 0 && props.upload) {
-    for (const [i, file] of imageFiles.entries()) {
-      const url = await props.upload(file)
-      blocks.value.splice(idx + 1 + i, 0, makeBlock('image', { props: { url } }))
-    }
-
-    pushHistory(true)
+  // Files (image / video / audio / anything else) become media blocks
+  if (payload.files.length > 0) {
+    await insertFileBlocks(payload.files, idx + 1)
 
     return
   }
@@ -2064,8 +2052,36 @@ e.dataTransfer.setDragImage(blockEl as HTMLElement, 0, 12)
   }
 }
 
+function isExternalFileDrag(e: DragEvent): boolean {
+  return !draggingId.value && Array.from(e.dataTransfer?.types ?? []).includes('Files')
+}
+
 function onDragOver(e: DragEvent) {
-  if (props.readonly || !draggingId.value) {
+  if (props.readonly) {
+return
+}
+
+  if (isExternalFileDrag(e)) {
+    e.preventDefault()
+
+    if (e.dataTransfer) {
+e.dataTransfer.dropEffect = 'copy'
+}
+
+    const target = (e.target as HTMLElement).closest('[data-block-id]')
+    const id = target?.getAttribute('data-block-id')
+
+    if (id) {
+      const rect = target!.getBoundingClientRect()
+      dropTarget.value = { id, position: e.clientY < rect.top + rect.height / 2 ? 'before' : 'after' }
+    } else {
+      dropTarget.value = null
+    }
+
+    return
+  }
+
+  if (!draggingId.value) {
 return
 }
 
@@ -2102,6 +2118,28 @@ return
 }
 
   e.preventDefault()
+
+  // External OS files dropped onto the editor become media blocks
+  const externalFiles = !draggingId.value ? Array.from(e.dataTransfer?.files ?? []) : []
+
+  if (externalFiles.length > 0) {
+    const target = dropTarget.value
+    dropTarget.value = null
+    let at = blocks.value.length
+
+    if (target) {
+      const idx = blocks.value.findIndex(b => b.id === target.id)
+
+      if (idx !== -1) {
+at = target.position === 'before' ? idx : idx + 1
+}
+    }
+
+    void insertFileBlocks(externalFiles, at)
+
+    return
+  }
+
   const from = draggingId.value
   const target = dropTarget.value
   draggingId.value = null
@@ -2654,6 +2692,7 @@ focusBlock(last.id, 'end')
       ref="slashMenuRef"
       :query="slashState.query"
       :position="slashState.position"
+      :dir="editorDir ?? 'ltr'"
       @select="onSlashSelect"
       @close="closeSlash"
     />
diff --git a/packages/vue/src/components/DocRenderer.vue b/packages/vue/src/components/DocRenderer.vue
index 94afbab..e26033a 100644
--- a/packages/vue/src/components/DocRenderer.vue
+++ b/packages/vue/src/components/DocRenderer.vue
@@ -5,6 +5,7 @@ import { ref, computed } from 'vue'
 import {
   computeListNumbering,
   escapeHtml,
+  formatFileSize,
   headingAnchorIds,
   isAllowedEmbedUrl,
   normalizeTableData,
@@ -275,6 +276,26 @@ function safeVideoEmbedUrl(block: Block): string {
         <figcaption v-if="block.props.caption" class="db-caption">{{ block.props.caption }}</figcaption>
       </figure>
 
+      <!-- Audio -->
+      <figure v-else-if="block.type === 'audio' && block.props.url" class="db-figure">
+        <div class="db-audio-wrap">
+          <div v-if="block.props.name" class="db-audio-name">{{ block.props.name }}</div>
+          <audio :src="block.props.url" controls preload="metadata" class="w-full" />
+        </div>
+        <figcaption v-if="block.props.caption" class="db-caption">{{ block.props.caption }}</figcaption>
+      </figure>
+
+      <!-- File -->
+      <a
+        v-else-if="block.type === 'file' && block.props.url"
+        :href="block.props.url"
+        :download="block.props.name ?? true"
+        class="db-file"
+      >
+        <span class="db-file-name">{{ block.props.name || 'Download file' }}</span>
+        <span v-if="block.props.size" class="db-file-size">{{ formatFileSize(block.props.size) }}</span>
+      </a>
+
       <!-- Table -->
       <div
         v-else-if="block.type === 'table' && block.props.table"
@@ -317,7 +338,7 @@ function safeVideoEmbedUrl(block: Block): string {
         @click="lightboxUrl = null"
       >
         <img :src="lightboxUrl" class="max-w-full max-h-full rounded-lg shadow-2xl" alt="" />
-        <button class="absolute top-4 right-4 text-white/80 hover:text-white">
+        <button class="absolute top-4 end-4 text-white/80 hover:text-white">
           <X class="w-6 h-6" />
         </button>
       </div>
@@ -518,6 +539,36 @@ function safeVideoEmbedUrl(block: Block): string {
   color: var(--xpe-muted-foreground);
 }
 
+/* --- Audio / file --- */
+.db-audio-wrap {
+  background: var(--xpe-muted);
+  border: 1px solid var(--xpe-border);
+  border-radius: var(--xpe-radius, 0.75rem);
+  padding: 0.75rem;
+}
+.db-audio-wrap audio { width: 100%; }
+.db-audio-name {
+  font-size: 0.85em;
+  font-weight: 500;
+  margin-bottom: 0.5em;
+  color: var(--xpe-foreground);
+}
+.db-file {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+  margin: 0.75em 0;
+  padding: 0.65rem 0.9rem;
+  background: var(--xpe-muted);
+  border: 1px solid var(--xpe-border);
+  border-radius: var(--xpe-radius, 0.75rem);
+  text-decoration: none;
+  color: var(--xpe-foreground);
+}
+.db-file:hover { border-color: var(--xpe-primary); }
+.db-file-name { font-size: 0.9em; font-weight: 500; flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.db-file-size { font-size: 0.8em; color: var(--xpe-muted-foreground); flex-shrink: 0; }
+
 /* --- Table --- */
 .db-table-wrap { overflow-x: auto; margin: 1.25em 0; }
 .db-table {
diff --git a/packages/vue/src/components/EditorAudioBlock.vue b/packages/vue/src/components/EditorAudioBlock.vue
new file mode 100644
index 0000000..4836964
--- /dev/null
+++ b/packages/vue/src/components/EditorAudioBlock.vue
@@ -0,0 +1,242 @@
+<script setup lang="ts">
+import { FolderOpen, Link2, Loader2, Music, Upload } from 'lucide-vue-next';
+import { nextTick, ref, watch } from 'vue';
+import type { Block } from '@xproeditor/core';
+import { fileToObjectUrl, formatFileSize, mediaPropsFromFile } from '@xproeditor/core';
+
+const props = defineProps<{
+    block: Block;
+    selected?: boolean;
+    readonly?: boolean;
+    upload?: (file: File) => Promise<string>;
+    pickMedia?: (options: {
+        accept: string[];
+        title?: string;
+    }) => Promise<{ url: string; alt?: string; caption?: string } | null>;
+}>();
+
+const emit = defineEmits<{
+    patch: [patch: Record<string, unknown>];
+    select: [];
+}>();
+
+type InsertMode = 'upload' | 'library' | 'embed';
+
+const mode = ref<InsertMode>('upload');
+const uploading = ref(false);
+const picking = ref(false);
+const dragOver = ref(false);
+const embedInput = ref('');
+const embedError = ref('');
+const embedInputRef = ref<HTMLInputElement | null>(null);
+const fileInput = ref<HTMLInputElement | null>(null);
+
+async function uploadFile(file: File) {
+    if (!file.type.startsWith('audio/')) {
+        return;
+    }
+
+    uploading.value = true;
+
+    try {
+        const url = await (props.upload ?? fileToObjectUrl)(file);
+        emit('patch', mediaPropsFromFile(file, url));
+    } finally {
+        uploading.value = false;
+    }
+}
+
+async function pickFromLibrary() {
+    if (!props.pickMedia) {
+        return;
+    }
+
+    picking.value = true;
+
+    try {
+        const result = await props.pickMedia({ accept: ['audio/*'], title: 'Choose audio' });
+
+        if (result?.url) {
+            emit('patch', {
+                url: result.url,
+                ...(result.caption ? { caption: result.caption } : {}),
+            });
+        }
+    } finally {
+        picking.value = false;
+    }
+}
+
+function applyEmbed() {
+    embedError.value = '';
+    const url = embedInput.value.trim();
+
+    if (!/^https?:\/\//i.test(url)) {
+        embedError.value = 'Enter a valid audio file URL';
+
+        return;
+    }
+
+    emit('patch', { url });
+    embedInput.value = '';
+}
+
+function onFilePicked(e: Event) {
+    const file = (e.target as HTMLInputElement).files?.[0];
+
+    if (file) {
+        uploadFile(file);
+    }
+}
+
+function onDrop(e: DragEvent) {
+    dragOver.value = false;
+    const file = e.dataTransfer?.files?.[0];
+
+    if (file) {
+        uploadFile(file);
+    }
+}
+
+const busy = () => uploading.value || picking.value;
+
+watch(mode, (next) => {
+    if (next === 'embed') {
+        nextTick(() => embedInputRef.value?.focus());
+    }
+});
+</script>
+
+<template>
+    <div class="my-1">
+        <div
+            v-if="!block.props.url && !readonly"
+            class="flex flex-col gap-3 rounded-[var(--xpe-radius)] border-2 border-dashed py-6 transition-colors"
+            :class="dragOver ? 'border-[var(--xpe-ring)] bg-[var(--xpe-primary-muted)]' : 'border-[var(--xpe-border)] bg-[var(--xpe-muted)]'"
+            @click="emit('select')"
+            @dragover.prevent="dragOver = true"
+            @dragleave="dragOver = false"
+            @drop.prevent.stop="onDrop"
+        >
+            <div class="flex items-center justify-center gap-2 text-[var(--xpe-muted-foreground)]">
+                <Loader2 v-if="busy()" class="h-5 w-5 animate-spin text-[var(--xpe-primary)]" />
+                <Music v-else class="h-5 w-5" />
+                <span class="text-sm">{{ busy() ? 'Working...' : 'Add audio' }}</span>
+            </div>
+
+            <div v-if="!busy()" class="flex justify-center gap-1 px-4" @click.stop @mousedown.stop @pointerdown.stop>
+                <button
+                    type="button"
+                    class="rounded-lg px-2.5 py-1 text-xs font-medium"
+                    :class="mode === 'upload' ? 'bg-[var(--xpe-primary-muted)] text-[var(--xpe-primary)]' : 'text-[var(--xpe-muted-foreground)] hover:bg-[var(--xpe-surface-hover)]'"
+                    @click.stop="mode = 'upload'"
+                >
+                    Upload
+                </button>
+                <button
+                    v-if="pickMedia"
+                    type="button"
+                    class="rounded-lg px-2.5 py-1 text-xs font-medium"
+                    :class="mode === 'library' ? 'bg-[var(--xpe-primary-muted)] text-[var(--xpe-primary)]' : 'text-[var(--xpe-muted-foreground)] hover:bg-[var(--xpe-surface-hover)]'"
+                    @click.stop="mode = 'library'"
+                >
+                    Library
+                </button>
+                <button
+                    type="button"
+                    class="rounded-lg px-2.5 py-1 text-xs font-medium"
+                    :class="mode === 'embed' ? 'bg-[var(--xpe-primary-muted)] text-[var(--xpe-primary)]' : 'text-[var(--xpe-muted-foreground)] hover:bg-[var(--xpe-surface-hover)]'"
+                    @click.stop="mode = 'embed'"
+                >
+                    Link
+                </button>
+            </div>
+
+            <div v-if="!busy()" class="px-4" @click.stop @mousedown.stop @pointerdown.stop>
+                <div v-if="mode === 'upload'" class="flex justify-center">
+                    <button
+                        type="button"
+                        class="inline-flex items-center gap-1.5 rounded-lg border border-[var(--xpe-border)] bg-[var(--xpe-surface)] px-3 py-1.5 text-xs font-medium text-[var(--xpe-foreground)] hover:bg-[var(--xpe-surface-hover)]"
+                        @click.stop="fileInput?.click()"
+                    >
+                        <Upload class="h-3.5 w-3.5" />
+                        Choose audio file
+                    </button>
+                    <input ref="fileInput" type="file" accept="audio/*" class="hidden" @change="onFilePicked" />
+                </div>
+
+                <div v-else-if="mode === 'library'" class="flex justify-center">
+                    <button
+                        type="button"
+                        class="inline-flex items-center gap-1.5 rounded-lg border border-[var(--xpe-border)] bg-[var(--xpe-surface)] px-3 py-1.5 text-xs font-medium text-[var(--xpe-foreground)] hover:bg-[var(--xpe-surface-hover)]"
+                        @click.stop="pickFromLibrary"
+                    >
+                        <FolderOpen class="h-3.5 w-3.5" />
+                        Open media library
+                    </button>
+                </div>
+
+                <div v-else class="space-y-2" @click.stop @mousedown.stop @pointerdown.stop>
+                    <div class="flex items-center gap-2">
+                        <Link2 class="h-4 w-4 shrink-0 text-[var(--xpe-muted-foreground)]" />
+                        <input
+                            ref="embedInputRef"
+                            v-model="embedInput"
+                            type="url"
+                            class="min-w-0 flex-1 rounded-lg border border-[var(--xpe-border)] bg-[var(--xpe-surface)] px-2.5 py-1.5 text-xs text-[var(--xpe-foreground)] outline-none focus:border-[var(--xpe-ring)]"
+                            placeholder="Audio file URL (.mp3, .ogg, ...)"
+                            @keydown.enter.prevent="applyEmbed"
+                        />
+                        <button
+                            type="button"
+                            class="rounded-lg bg-[var(--xpe-primary)] px-2.5 py-1.5 text-xs text-[var(--xpe-primary-foreground)]"
+                            @click.stop="applyEmbed"
+                        >
+                            Add
+                        </button>
+                    </div>
+                    <p v-if="embedError" class="text-center text-xs text-[var(--xpe-danger)]">{{ embedError }}</p>
+                </div>
+            </div>
+        </div>
+
+        <figure v-else class="group/audio relative">
+            <div
+                class="flex flex-col gap-2 rounded-[var(--xpe-radius)] border bg-[var(--xpe-muted)] p-3 transition-shadow"
+                :class="selected ? 'border-[var(--xpe-ring)] ring-1 ring-[var(--xpe-ring)]' : 'border-[var(--xpe-border)]'"
+                @click="emit('select')"
+            >
+                <div v-if="block.props.name || block.props.size" class="flex items-center gap-2 text-xs text-[var(--xpe-muted-foreground)]">
+                    <Music class="h-3.5 w-3.5 shrink-0" />
+                    <span class="truncate font-medium text-[var(--xpe-foreground)]">{{ block.props.name }}</span>
+                    <span v-if="block.props.size" class="shrink-0">{{ formatFileSize(block.props.size) }}</span>
+                </div>
+                <audio :src="block.props.url" class="w-full" controls preload="metadata" />
+            </div>
+
+            <div
+                v-if="!readonly"
+                class="absolute end-2 top-2 hidden items-center gap-0.5 rounded-lg bg-black/60 p-0.5 backdrop-blur group-hover/audio:flex"
+            >
+                <button
+                    class="rounded-md px-1.5 py-0.5 text-[10px] text-white/80 hover:bg-white/20"
+                    title="Remove audio"
+                    @click.stop="emit('patch', { url: '', name: undefined, size: undefined, mime: undefined })"
+                >
+                    ✕
+                </button>
+            </div>
+
+            <figcaption @mousedown.stop @click.stop @pointerdown.stop>
+                <input
+                    class="mt-1.5 w-full bg-transparent text-center text-xs text-[var(--xpe-muted-foreground)] outline-none placeholder:opacity-60"
+                    :value="block.props.caption ?? ''"
+                    placeholder="Add caption..."
+                    :readonly="readonly"
+                    @focus="emit('select')"
+                    @input="emit('patch', { caption: ($event.target as HTMLInputElement).value })"
+                />
+            </figcaption>
+        </figure>
+    </div>
+</template>
diff --git a/packages/vue/src/components/EditorBlockItem.vue b/packages/vue/src/components/EditorBlockItem.vue
index 87e66ab..488e90c 100644
--- a/packages/vue/src/components/EditorBlockItem.vue
+++ b/packages/vue/src/components/EditorBlockItem.vue
@@ -11,7 +11,9 @@ import {
   IconEmojiPicker,
   IconValueDisplay,
 } from '../ui'
+import EditorAudioBlock from './EditorAudioBlock.vue'
 import EditorCodeBlock from './EditorCodeBlock.vue'
+import EditorFileBlock from './EditorFileBlock.vue'
 import EditorImageBlock from './EditorImageBlock.vue'
 import EditorSelectionHighlight from './EditorSelectionHighlight.vue'
 import EditorTableBlock from './EditorTableBlock.vue'
@@ -374,6 +376,28 @@ defineExpose({
           @select="emit('select')"
         />
 
+        <EditorAudioBlock
+          v-else-if="block.type === 'audio'"
+          :block="block"
+          :selected="selected"
+          :readonly="readonly"
+          :upload="upload"
+          :pick-media="pickMedia"
+          @patch="p => emit('patch', p)"
+          @select="emit('select')"
+        />
+
+        <EditorFileBlock
+          v-else-if="block.type === 'file'"
+          :block="block"
+          :selected="selected"
+          :readonly="readonly"
+          :upload="upload"
+          :pick-media="pickMedia"
+          @patch="p => emit('patch', p)"
+          @select="emit('select')"
+        />
+
         <!-- Table -->
         <EditorTableBlock
           v-else-if="block.type === 'table'"
diff --git a/packages/vue/src/components/EditorBubbleToolbar.vue b/packages/vue/src/components/EditorBubbleToolbar.vue
index b43d9bc..50135d5 100644
--- a/packages/vue/src/components/EditorBubbleToolbar.vue
+++ b/packages/vue/src/components/EditorBubbleToolbar.vue
@@ -214,7 +214,7 @@ function turnIntoLabel(): string {
                     v-for="t in TURN_INTO"
                     :key="t.type"
                     type="button"
-                    class="flex w-full items-center gap-2.5 px-3 py-2 text-left text-[13px] transition-colors"
+                    class="flex w-full items-center gap-2.5 px-3 py-2 text-start text-[13px] transition-colors"
                     :class="
                         t.type === blockType
                             ? 'bg-indigo-50/60 text-indigo-600'
diff --git a/packages/vue/src/components/EditorFileBlock.vue b/packages/vue/src/components/EditorFileBlock.vue
new file mode 100644
index 0000000..da311bf
--- /dev/null
+++ b/packages/vue/src/components/EditorFileBlock.vue
@@ -0,0 +1,168 @@
+<script setup lang="ts">
+import { Download, FileText, FolderOpen, Loader2, Paperclip, Upload } from 'lucide-vue-next';
+import { ref } from 'vue';
+import type { Block } from '@xproeditor/core';
+import { fileToObjectUrl, formatFileSize, mediaPropsFromFile } from '@xproeditor/core';
+
+const props = defineProps<{
+    block: Block;
+    selected?: boolean;
+    readonly?: boolean;
+    upload?: (file: File) => Promise<string>;
+    pickMedia?: (options: {
+        accept: string[];
+        title?: string;
+    }) => Promise<{ url: string; alt?: string; caption?: string } | null>;
+}>();
+
+const emit = defineEmits<{
+    patch: [patch: Record<string, unknown>];
+    select: [];
+}>();
+
+const uploading = ref(false);
+const picking = ref(false);
+const dragOver = ref(false);
+const fileInput = ref<HTMLInputElement | null>(null);
+
+async function uploadFile(file: File) {
+    uploading.value = true;
+
+    try {
+        const url = await (props.upload ?? fileToObjectUrl)(file);
+        emit('patch', mediaPropsFromFile(file, url));
+    } finally {
+        uploading.value = false;
+    }
+}
+
+async function pickFromLibrary() {
+    if (!props.pickMedia) {
+        return;
+    }
+
+    picking.value = true;
+
+    try {
+        const result = await props.pickMedia({ accept: ['*/*'], title: 'Choose file' });
+
+        if (result?.url) {
+            emit('patch', {
+                url: result.url,
+                ...(result.caption ? { name: result.caption } : {}),
+            });
+        }
+    } finally {
+        picking.value = false;
+    }
+}
+
+function onFilePicked(e: Event) {
+    const file = (e.target as HTMLInputElement).files?.[0];
+
+    if (file) {
+        uploadFile(file);
+    }
+}
+
+function onDrop(e: DragEvent) {
+    dragOver.value = false;
+    const file = e.dataTransfer?.files?.[0];
+
+    if (file) {
+        uploadFile(file);
+    }
+}
+
+const busy = () => uploading.value || picking.value;
+</script>
+
+<template>
+    <div class="my-1">
+        <div
+            v-if="!block.props.url && !readonly"
+            class="flex flex-col items-center justify-center gap-3 rounded-[var(--xpe-radius)] border-2 border-dashed py-6 transition-colors"
+            :class="dragOver ? 'border-[var(--xpe-ring)] bg-[var(--xpe-primary-muted)]' : 'border-[var(--xpe-border)] bg-[var(--xpe-muted)]'"
+            @click="emit('select')"
+            @dragover.prevent="dragOver = true"
+            @dragleave="dragOver = false"
+            @drop.prevent.stop="onDrop"
+        >
+            <div class="flex items-center gap-2 text-[var(--xpe-muted-foreground)]">
+                <Loader2 v-if="busy()" class="h-5 w-5 animate-spin text-[var(--xpe-primary)]" />
+                <Paperclip v-else class="h-5 w-5" />
+                <span class="text-sm">{{ busy() ? 'Working...' : 'Attach a file' }}</span>
+            </div>
+            <div v-if="!busy()" class="flex flex-wrap items-center justify-center gap-2" @click.stop @mousedown.stop @pointerdown.stop>
+                <button
+                    type="button"
+                    class="inline-flex items-center gap-1.5 rounded-lg border border-[var(--xpe-border)] bg-[var(--xpe-surface)] px-3 py-1.5 text-xs font-medium text-[var(--xpe-foreground)] hover:bg-[var(--xpe-surface-hover)]"
+                    @click.stop="fileInput?.click()"
+                >
+                    <Upload class="h-3.5 w-3.5" />
+                    Upload
+                </button>
+                <button
+                    v-if="pickMedia"
+                    type="button"
+                    class="inline-flex items-center gap-1.5 rounded-lg border border-[var(--xpe-border)] bg-[var(--xpe-surface)] px-3 py-1.5 text-xs font-medium text-[var(--xpe-foreground)] hover:bg-[var(--xpe-surface-hover)]"
+                    @click.stop="pickFromLibrary"
+                >
+                    <FolderOpen class="h-3.5 w-3.5" />
+                    Library
+                </button>
+            </div>
+            <input ref="fileInput" type="file" class="hidden" @change="onFilePicked" />
+        </div>
+
+        <div v-else class="group/file relative">
+            <div
+                class="flex items-center gap-3 rounded-[var(--xpe-radius)] border bg-[var(--xpe-muted)] px-3.5 py-2.5 transition-shadow"
+                :class="selected ? 'border-[var(--xpe-ring)] ring-1 ring-[var(--xpe-ring)]' : 'border-[var(--xpe-border)]'"
+                @click="emit('select')"
+            >
+                <span class="flex h-9 w-9 shrink-0 items-center justify-center rounded-lg bg-[var(--xpe-surface)] text-[var(--xpe-primary)]">
+                    <FileText class="h-5 w-5" />
+                </span>
+                <span class="min-w-0 flex-1">
+                    <span class="block truncate text-sm font-medium text-[var(--xpe-foreground)]">
+                        {{ block.props.name || 'File' }}
+                    </span>
+                    <span v-if="block.props.size" class="block text-xs text-[var(--xpe-muted-foreground)]">
+                        {{ formatFileSize(block.props.size) }}
+                    </span>
+                </span>
+                <a
+                    :href="block.props.url"
+                    :download="block.props.name ?? true"
+                    class="flex h-8 w-8 shrink-0 items-center justify-center rounded-lg text-[var(--xpe-muted-foreground)] hover:bg-[var(--xpe-surface-hover)] hover:text-[var(--xpe-foreground)]"
+                    title="Download"
+                    @click.stop
+                >
+                    <Download class="h-4 w-4" />
+                </a>
+            </div>
+
+            <div
+                v-if="!readonly"
+                class="absolute end-12 top-1/2 hidden -translate-y-1/2 items-center gap-0.5 rounded-lg bg-black/60 p-0.5 backdrop-blur group-hover/file:flex"
+            >
+                <button
+                    class="rounded-md px-1.5 py-0.5 text-[10px] text-white/80 hover:bg-white/20"
+                    title="Replace file"
+                    @click.stop="fileInput?.click()"
+                >
+                    ↻
+                </button>
+                <button
+                    class="rounded-md px-1.5 py-0.5 text-[10px] text-white/80 hover:bg-white/20"
+                    title="Remove file"
+                    @click.stop="emit('patch', { url: '', name: undefined, size: undefined, mime: undefined })"
+                >
+                    ✕
+                </button>
+                <input ref="fileInput" type="file" class="hidden" @change="onFilePicked" />
+            </div>
+        </div>
+    </div>
+</template>
diff --git a/packages/vue/src/components/EditorImageBlock.vue b/packages/vue/src/components/EditorImageBlock.vue
index 0124e34..45f99ef 100644
--- a/packages/vue/src/components/EditorImageBlock.vue
+++ b/packages/vue/src/components/EditorImageBlock.vue
@@ -1,7 +1,8 @@
 <script setup lang="ts">
-import { FolderOpen, ImagePlus, Loader2, Upload } from 'lucide-vue-next';
-import { ref } from 'vue';
+import { FolderOpen, ImagePlus, Link2, Loader2, Upload } from 'lucide-vue-next';
+import { nextTick, ref, watch } from 'vue';
 import type { Block } from '@xproeditor/core';
+import { fileToObjectUrl, mediaPropsFromFile } from '@xproeditor/core';
 
 const props = defineProps<{
     block: Block;
@@ -19,21 +20,27 @@ const emit = defineEmits<{
     select: [];
 }>();
 
+type InsertMode = 'upload' | 'library' | 'embed';
+
+const mode = ref<InsertMode>('upload');
 const uploading = ref(false);
 const picking = ref(false);
 const dragOver = ref(false);
+const embedInput = ref('');
+const embedError = ref('');
+const embedInputRef = ref<HTMLInputElement | null>(null);
 const fileInput = ref<HTMLInputElement | null>(null);
 
 async function uploadFile(file: File) {
-    if (!props.upload || !file.type.startsWith('image/')) {
+    if (!file.type.startsWith('image/')) {
         return;
     }
 
     uploading.value = true;
 
     try {
-        const url = await props.upload(file);
-        emit('patch', { url });
+        const url = await (props.upload ?? fileToObjectUrl)(file);
+        emit('patch', mediaPropsFromFile(file, url));
     } finally {
         uploading.value = false;
     }
@@ -60,6 +67,20 @@ async function pickFromLibrary() {
     }
 }
 
+function applyEmbed() {
+    embedError.value = '';
+    const url = embedInput.value.trim();
+
+    if (!/^https?:\/\//i.test(url)) {
+        embedError.value = 'Enter a valid image URL';
+
+        return;
+    }
+
+    emit('patch', { url });
+    embedInput.value = '';
+}
+
 function onFilePicked(e: Event) {
     const file = (e.target as HTMLInputElement).files?.[0];
 
@@ -79,44 +100,105 @@ function onDrop(e: DragEvent) {
 
 const widths = [40, 60, 80, 100];
 const busy = () => uploading.value || picking.value;
+
+watch(mode, (next) => {
+    if (next === 'embed') {
+        nextTick(() => embedInputRef.value?.focus());
+    }
+});
 </script>
 
 <template>
     <div class="my-1">
         <div
             v-if="!block.props.url && !readonly"
-            class="flex flex-col items-center justify-center gap-3 rounded-xl border-2 border-dashed py-8 transition-colors"
-            :class="dragOver ? 'border-indigo-400 bg-indigo-50/50' : 'border-gray-200 bg-gray-50 hover:border-gray-300'"
+            class="flex flex-col gap-3 rounded-[var(--xpe-radius)] border-2 border-dashed py-6 transition-colors"
+            :class="dragOver ? 'border-[var(--xpe-ring)] bg-[var(--xpe-primary-muted)]' : 'border-[var(--xpe-border)] bg-[var(--xpe-muted)]'"
             @click="emit('select')"
             @dragover.prevent="dragOver = true"
             @dragleave="dragOver = false"
             @drop.prevent.stop="onDrop"
         >
-            <Loader2 v-if="busy()" class="h-6 w-6 animate-spin text-indigo-500" />
-            <ImagePlus v-else class="h-6 w-6 text-gray-400" />
-            <span class="text-sm text-gray-500">
-                {{ busy() ? 'Working...' : 'Add an image' }}
-            </span>
-            <div v-if="!busy()" class="flex flex-wrap items-center justify-center gap-2">
+            <div class="flex items-center justify-center gap-2 text-[var(--xpe-muted-foreground)]">
+                <Loader2 v-if="busy()" class="h-5 w-5 animate-spin text-[var(--xpe-primary)]" />
+                <ImagePlus v-else class="h-5 w-5" />
+                <span class="text-sm">{{ busy() ? 'Working...' : 'Add an image' }}</span>
+            </div>
+
+            <div v-if="!busy()" class="flex justify-center gap-1 px-4" @click.stop @mousedown.stop @pointerdown.stop>
                 <button
                     type="button"
-                    class="inline-flex items-center gap-1.5 rounded-lg border border-gray-200 bg-white px-3 py-1.5 text-xs font-medium text-gray-700 hover:bg-gray-50"
-                    @click.stop="fileInput?.click()"
+                    class="rounded-lg px-2.5 py-1 text-xs font-medium"
+                    :class="mode === 'upload' ? 'bg-[var(--xpe-primary-muted)] text-[var(--xpe-primary)]' : 'text-[var(--xpe-muted-foreground)] hover:bg-[var(--xpe-surface-hover)]'"
+                    @click.stop="mode = 'upload'"
                 >
-                    <Upload class="h-3.5 w-3.5" />
                     Upload
                 </button>
                 <button
                     v-if="pickMedia"
                     type="button"
-                    class="inline-flex items-center gap-1.5 rounded-lg border border-gray-200 bg-white px-3 py-1.5 text-xs font-medium text-gray-700 hover:bg-gray-50"
-                    @click.stop="pickFromLibrary"
+                    class="rounded-lg px-2.5 py-1 text-xs font-medium"
+                    :class="mode === 'library' ? 'bg-[var(--xpe-primary-muted)] text-[var(--xpe-primary)]' : 'text-[var(--xpe-muted-foreground)] hover:bg-[var(--xpe-surface-hover)]'"
+                    @click.stop="mode = 'library'"
                 >
-                    <FolderOpen class="h-3.5 w-3.5" />
                     Library
                 </button>
+                <button
+                    type="button"
+                    class="rounded-lg px-2.5 py-1 text-xs font-medium"
+                    :class="mode === 'embed' ? 'bg-[var(--xpe-primary-muted)] text-[var(--xpe-primary)]' : 'text-[var(--xpe-muted-foreground)] hover:bg-[var(--xpe-surface-hover)]'"
+                    @click.stop="mode = 'embed'"
+                >
+                    Link
+                </button>
+            </div>
+
+            <div v-if="!busy()" class="px-4" @click.stop @mousedown.stop @pointerdown.stop>
+                <div v-if="mode === 'upload'" class="flex justify-center">
+                    <button
+                        type="button"
+                        class="inline-flex items-center gap-1.5 rounded-lg border border-[var(--xpe-border)] bg-[var(--xpe-surface)] px-3 py-1.5 text-xs font-medium text-[var(--xpe-foreground)] hover:bg-[var(--xpe-surface-hover)]"
+                        @click.stop="fileInput?.click()"
+                    >
+                        <Upload class="h-3.5 w-3.5" />
+                        Choose image
+                    </button>
+                    <input ref="fileInput" type="file" accept="image/*" class="hidden" @change="onFilePicked" />
+                </div>
+
+                <div v-else-if="mode === 'library'" class="flex justify-center">
+                    <button
+                        type="button"
+                        class="inline-flex items-center gap-1.5 rounded-lg border border-[var(--xpe-border)] bg-[var(--xpe-surface)] px-3 py-1.5 text-xs font-medium text-[var(--xpe-foreground)] hover:bg-[var(--xpe-surface-hover)]"
+                        @click.stop="pickFromLibrary"
+                    >
+                        <FolderOpen class="h-3.5 w-3.5" />
+                        Open media library
+                    </button>
+                </div>
+
+                <div v-else class="space-y-2" @click.stop @mousedown.stop @pointerdown.stop>
+                    <div class="flex items-center gap-2">
+                        <Link2 class="h-4 w-4 shrink-0 text-[var(--xpe-muted-foreground)]" />
+                        <input
+                            ref="embedInputRef"
+                            v-model="embedInput"
+                            type="url"
+                            class="min-w-0 flex-1 rounded-lg border border-[var(--xpe-border)] bg-[var(--xpe-surface)] px-2.5 py-1.5 text-xs text-[var(--xpe-foreground)] outline-none focus:border-[var(--xpe-ring)]"
+                            placeholder="Paste an image URL"
+                            @keydown.enter.prevent="applyEmbed"
+                        />
+                        <button
+                            type="button"
+                            class="rounded-lg bg-[var(--xpe-primary)] px-2.5 py-1.5 text-xs text-[var(--xpe-primary-foreground)]"
+                            @click.stop="applyEmbed"
+                        >
+                            Add
+                        </button>
+                    </div>
+                    <p v-if="embedError" class="text-center text-xs text-[var(--xpe-danger)]">{{ embedError }}</p>
+                </div>
             </div>
-            <input ref="fileInput" type="file" accept="image/*" class="hidden" @change="onFilePicked" />
         </div>
 
         <figure v-else class="group/img relative" :style="{ width: `${block.props.width ?? 100}%` }">
@@ -124,8 +206,8 @@ const busy = () => uploading.value || picking.value;
                 <img
                     :src="block.props.url"
                     :alt="block.props.caption || ''"
-                    class="w-full rounded-xl transition-shadow"
-                    :class="selected ? 'ring-2 ring-indigo-400' : ''"
+                    class="w-full rounded-[var(--xpe-radius)] transition-shadow"
+                    :class="selected ? 'ring-2 ring-[var(--xpe-ring)]' : ''"
                     draggable="false"
                 />
             </div>
@@ -165,7 +247,7 @@ const busy = () => uploading.value || picking.value;
             </div>
             <figcaption @mousedown.stop @click.stop @pointerdown.stop>
                 <input
-                    class="mt-1.5 w-full bg-transparent text-center text-xs text-gray-400 outline-none placeholder:text-gray-300"
+                    class="mt-1.5 w-full bg-transparent text-center text-xs text-[var(--xpe-muted-foreground)] outline-none placeholder:opacity-60"
                     :value="block.props.caption ?? ''"
                     placeholder="Add caption..."
                     :readonly="readonly"
diff --git a/packages/vue/src/components/EditorSlashMenu.vue b/packages/vue/src/components/EditorSlashMenu.vue
index 467b183..40e2854 100644
--- a/packages/vue/src/components/EditorSlashMenu.vue
+++ b/packages/vue/src/components/EditorSlashMenu.vue
@@ -2,9 +2,9 @@
 import {
   Type, Heading1, Heading2, Heading3, List, ListOrdered, CheckSquare,
   ChevronRight, Quote, Lightbulb, Code2, Minus, Image as ImageIcon, Video, Table2,
-  Smile, Blocks,
+  Smile, Blocks, Music, Paperclip, SearchX,
 } from 'lucide-vue-next'
-import { ref, computed, watch, nextTick } from 'vue'
+import { ref, computed, watch, nextTick, onMounted, onBeforeUnmount } from 'vue'
 import type { BlockType } from '@xproeditor/core'
 
 export interface SlashItem {
@@ -35,12 +35,16 @@ const ITEMS: SlashItem[] = [
   { id: 'divider', type: 'divider', label: 'Divider', description: 'Horizontal line', keywords: ['divider', 'hr', 'separator', 'line'], icon: Minus },
   { id: 'image', type: 'image', label: 'Image', description: 'Upload an image', keywords: ['image', 'photo', 'picture', 'upload'], icon: ImageIcon },
   { id: 'video', type: 'video', label: 'Video', description: 'Upload or embed a video', keywords: ['video', 'youtube', 'vimeo', 'movie'], icon: Video },
+  { id: 'audio', type: 'audio', label: 'Audio', description: 'Upload or link audio', keywords: ['audio', 'music', 'song', 'sound', 'mp3'], icon: Music },
+  { id: 'file', type: 'file', label: 'File', description: 'Attach a downloadable file', keywords: ['file', 'attachment', 'pdf', 'document', 'download'], icon: Paperclip },
   { id: 'table', type: 'table', label: 'Table', description: 'Simple table', keywords: ['table', 'grid'], icon: Table2 },
 ]
 
 const props = defineProps<{
   query: string
-  position: { x: number; y: number }
+  /** Caret anchor in viewport coordinates: menu opens below `bottom`, flips above `top` when needed. */
+  position: { x: number; y: number; top?: number }
+  dir?: 'ltr' | 'rtl'
 }>()
 
 const emit = defineEmits<{
@@ -50,6 +54,8 @@ const emit = defineEmits<{
 
 const activeIndex = ref(0)
 const listEl = ref<HTMLElement | null>(null)
+const menuEl = ref<HTMLElement | null>(null)
+const placed = ref<{ left: number; top: number }>({ left: props.position.x, top: props.position.y })
 
 const filtered = computed(() => {
   const q = props.query.toLowerCase().trim()
@@ -63,15 +69,52 @@ return ITEMS
   )
 })
 
-watch(() => props.query, () => {
- activeIndex.value = 0 
-})
-watch(filtered, (items) => {
-  if (items.length === 0) {
-emit('close')
+/**
+ * Place the menu with its real measured size: below the caret when it fits,
+ * flipped above otherwise, clamped to the viewport. In RTL the menu grows
+ * toward the start (its end edge hugs the caret).
+ */
+function place() {
+  const el = menuEl.value
+
+  if (!el) {
+return
+}
+
+  const margin = 8
+  const gap = 6
+  const { width, height } = el.getBoundingClientRect()
+  const anchorTop = props.position.top ?? props.position.y
+  let left = props.dir === 'rtl' ? props.position.x - width : props.position.x
+  left = Math.max(margin, Math.min(left, window.innerWidth - width - margin))
+  let top = props.position.y + gap
+
+  if (top + height > window.innerHeight - margin) {
+    top = Math.max(margin, anchorTop - height - gap)
+  }
+
+  placed.value = { left, top }
 }
+
+onMounted(() => {
+  nextTick(place)
+  window.addEventListener('resize', place)
+  window.addEventListener('scroll', place, true)
+})
+
+onBeforeUnmount(() => {
+  window.removeEventListener('resize', place)
+  window.removeEventListener('scroll', place, true)
 })
 
+watch(() => props.query, () => {
+  activeIndex.value = 0
+  nextTick(place)
+})
+watch(() => props.position, () => {
+ nextTick(place)
+}, { deep: true })
+
 function scrollActiveIntoView() {
   nextTick(() => {
     listEl.value?.querySelector('[data-active="true"]')?.scrollIntoView({ block: 'nearest' })
@@ -103,30 +146,36 @@ defineExpose({ move, confirm })
 <template>
   <Teleport to="body">
     <div
-      class="fixed z-[80] w-72 max-h-80 overflow-y-auto bg-white border border-gray-100 rounded-xl shadow-xl py-1.5"
-      :style="{ left: `${position.x}px`, top: `${position.y}px` }"
+      ref="menuEl"
+      class="fixed z-[80] w-72 max-h-80 overflow-y-auto border py-1.5 bg-[var(--xpe-surface)] border-[var(--xpe-border)] rounded-[var(--xpe-radius)] [box-shadow:var(--xpe-shadow)]"
+      :style="{ left: `${placed.left}px`, top: `${placed.top}px` }"
+      :dir="dir"
       @mousedown.prevent
     >
-      <p class="px-3 pt-1 pb-1.5 text-[10px] font-semibold uppercase tracking-wider text-gray-400">Blocks</p>
+      <p class="px-3 pt-1 pb-1.5 text-[10px] font-semibold uppercase tracking-wider text-[var(--xpe-muted-foreground)]">Blocks</p>
+      <div v-if="filtered.length === 0" class="flex items-center gap-2 px-3 py-3 text-[13px] text-[var(--xpe-muted-foreground)]">
+        <SearchX class="w-4 h-4" />
+        No results for “{{ query }}”
+      </div>
       <div ref="listEl">
         <button
           v-for="(item, idx) in filtered"
           :key="item.id"
-          class="flex items-center gap-3 w-full px-3 py-1.5 text-left transition-colors"
-          :class="idx === activeIndex ? 'bg-indigo-50' : 'hover:bg-gray-50'"
+          class="flex items-center gap-3 w-full px-3 py-1.5 text-start transition-colors"
+          :class="idx === activeIndex ? 'bg-[var(--xpe-primary-muted)]' : 'hover:bg-[var(--xpe-surface-hover)]'"
           :data-active="idx === activeIndex"
           @mouseenter="activeIndex = idx"
           @click="emit('select', item)"
         >
           <span
             class="flex items-center justify-center w-8 h-8 rounded-lg border shrink-0"
-            :class="idx === activeIndex ? 'border-indigo-100 bg-white text-indigo-600' : 'border-gray-100 bg-gray-50 text-gray-500'"
+            :class="idx === activeIndex ? 'border-[var(--xpe-border)] bg-[var(--xpe-surface)] text-[var(--xpe-primary)]' : 'border-[var(--xpe-border)] bg-[var(--xpe-muted)] text-[var(--xpe-muted-foreground)]'"
           >
             <component :is="item.icon" class="w-4 h-4" />
           </span>
           <span class="min-w-0">
-            <span class="block text-[13px] font-medium text-gray-800">{{ item.label }}</span>
-            <span class="block text-[11px] text-gray-400 truncate">{{ item.description }}</span>
+            <span class="block text-[13px] font-medium text-[var(--xpe-foreground)]">{{ item.label }}</span>
+            <span class="block text-[11px] text-[var(--xpe-muted-foreground)] truncate">{{ item.description }}</span>
           </span>
         </button>
       </div>
diff --git a/packages/vue/src/components/EditorVideoBlock.vue b/packages/vue/src/components/EditorVideoBlock.vue
index bc9829e..34d9a13 100644
--- a/packages/vue/src/components/EditorVideoBlock.vue
+++ b/packages/vue/src/components/EditorVideoBlock.vue
@@ -2,7 +2,7 @@
 import { FolderOpen, Link2, Loader2, Upload, Video } from 'lucide-vue-next';
 import { nextTick, ref, watch } from 'vue';
 import type { Block } from '@xproeditor/core';
-import { isAllowedEmbedUrl, parseVideoEmbed } from '@xproeditor/core';
+import { fileToObjectUrl, isAllowedEmbedUrl, mediaPropsFromFile, parseVideoEmbed } from '@xproeditor/core';
 
 const props = defineProps<{
     block: Block;
@@ -32,15 +32,15 @@ const embedInputRef = ref<HTMLInputElement | null>(null);
 const fileInput = ref<HTMLInputElement | null>(null);
 
 async function uploadFile(file: File) {
-    if (!props.upload || !file.type.startsWith('video/')) {
+    if (!file.type.startsWith('video/')) {
         return;
     }
 
     uploading.value = true;
 
     try {
-        const url = await props.upload(file);
-        emit('patch', { url, provider: 'file' });
+        const url = await (props.upload ?? fileToObjectUrl)(file);
+        emit('patch', { ...mediaPropsFromFile(file, url), provider: 'file' });
     } finally {
         uploading.value = false;
     }
@@ -122,15 +122,15 @@ watch(mode, (next) => {
     <div class="my-1">
         <div
             v-if="!block.props.url && !readonly"
-            class="flex flex-col gap-3 rounded-xl border-2 border-dashed py-6 transition-colors"
-            :class="dragOver ? 'border-indigo-400 bg-indigo-50/50' : 'border-gray-200 bg-gray-50 hover:border-gray-300'"
+            class="flex flex-col gap-3 rounded-[var(--xpe-radius)] border-2 border-dashed py-6 transition-colors"
+            :class="dragOver ? 'border-[var(--xpe-ring)] bg-[var(--xpe-primary-muted)]' : 'border-[var(--xpe-border)] bg-[var(--xpe-muted)]'"
             @click="emit('select')"
             @dragover.prevent="dragOver = true"
             @dragleave="dragOver = false"
             @drop.prevent.stop="onDrop"
         >
-            <div class="flex items-center justify-center gap-2 text-gray-500">
-                <Loader2 v-if="busy()" class="h-5 w-5 animate-spin text-indigo-500" />
+            <div class="flex items-center justify-center gap-2 text-[var(--xpe-muted-foreground)]">
+                <Loader2 v-if="busy()" class="h-5 w-5 animate-spin text-[var(--xpe-primary)]" />
                 <Video v-else class="h-5 w-5" />
                 <span class="text-sm">{{ busy() ? 'Working...' : 'Add a video' }}</span>
             </div>
@@ -139,7 +139,7 @@ watch(mode, (next) => {
                 <button
                     type="button"
                     class="rounded-lg px-2.5 py-1 text-xs font-medium"
-                    :class="mode === 'upload' ? 'bg-indigo-100 text-indigo-700' : 'text-gray-500 hover:bg-gray-100'"
+                    :class="mode === 'upload' ? 'bg-[var(--xpe-primary-muted)] text-[var(--xpe-primary)]' : 'text-[var(--xpe-muted-foreground)] hover:bg-[var(--xpe-surface-hover)]'"
                     @click.stop="mode = 'upload'"
                 >
                     Upload
@@ -148,7 +148,7 @@ watch(mode, (next) => {
                     v-if="pickMedia"
                     type="button"
                     class="rounded-lg px-2.5 py-1 text-xs font-medium"
-                    :class="mode === 'library' ? 'bg-indigo-100 text-indigo-700' : 'text-gray-500 hover:bg-gray-100'"
+                    :class="mode === 'library' ? 'bg-[var(--xpe-primary-muted)] text-[var(--xpe-primary)]' : 'text-[var(--xpe-muted-foreground)] hover:bg-[var(--xpe-surface-hover)]'"
                     @click.stop="mode = 'library'"
                 >
                     Library
@@ -156,7 +156,7 @@ watch(mode, (next) => {
                 <button
                     type="button"
                     class="rounded-lg px-2.5 py-1 text-xs font-medium"
-                    :class="mode === 'embed' ? 'bg-indigo-100 text-indigo-700' : 'text-gray-500 hover:bg-gray-100'"
+                    :class="mode === 'embed' ? 'bg-[var(--xpe-primary-muted)] text-[var(--xpe-primary)]' : 'text-[var(--xpe-muted-foreground)] hover:bg-[var(--xpe-surface-hover)]'"
                     @click.stop="mode = 'embed'"
                 >
                     Embed
@@ -167,7 +167,7 @@ watch(mode, (next) => {
                 <div v-if="mode === 'upload'" class="flex justify-center">
                     <button
                         type="button"
-                        class="inline-flex items-center gap-1.5 rounded-lg border border-gray-200 bg-white px-3 py-1.5 text-xs font-medium text-gray-700 hover:bg-gray-50"
+                        class="inline-flex items-center gap-1.5 rounded-lg border border-[var(--xpe-border)] bg-[var(--xpe-surface)] px-3 py-1.5 text-xs font-medium text-[var(--xpe-foreground)] hover:bg-[var(--xpe-surface-hover)]"
                         @click.stop="fileInput?.click()"
                     >
                         <Upload class="h-3.5 w-3.5" />
@@ -179,7 +179,7 @@ watch(mode, (next) => {
                 <div v-else-if="mode === 'library'" class="flex justify-center">
                     <button
                         type="button"
-                        class="inline-flex items-center gap-1.5 rounded-lg border border-gray-200 bg-white px-3 py-1.5 text-xs font-medium text-gray-700 hover:bg-gray-50"
+                        class="inline-flex items-center gap-1.5 rounded-lg border border-[var(--xpe-border)] bg-[var(--xpe-surface)] px-3 py-1.5 text-xs font-medium text-[var(--xpe-foreground)] hover:bg-[var(--xpe-surface-hover)]"
                         @click.stop="pickFromLibrary"
                     >
                         <FolderOpen class="h-3.5 w-3.5" />
@@ -189,24 +189,24 @@ watch(mode, (next) => {
 
             <div v-else class="space-y-2" @click.stop @mousedown.stop @pointerdown.stop>
                     <div class="flex items-center gap-2">
-                        <Link2 class="h-4 w-4 shrink-0 text-gray-400" />
+                        <Link2 class="h-4 w-4 shrink-0 text-[var(--xpe-muted-foreground)]" />
                         <input
                             ref="embedInputRef"
                             v-model="embedInput"
                             type="url"
-                            class="min-w-0 flex-1 rounded-lg border border-gray-200 bg-white px-2.5 py-1.5 text-xs outline-none focus:border-indigo-300"
+                            class="min-w-0 flex-1 rounded-lg border border-[var(--xpe-border)] bg-[var(--xpe-surface)] px-2.5 py-1.5 text-xs text-[var(--xpe-foreground)] outline-none focus:border-[var(--xpe-ring)]"
                             placeholder="YouTube or Vimeo URL"
                             @keydown.enter.prevent="applyEmbed"
                         />
                         <button
                             type="button"
-                            class="rounded-lg bg-gray-800 px-2.5 py-1.5 text-xs text-white"
+                            class="rounded-lg bg-[var(--xpe-primary)] px-2.5 py-1.5 text-xs text-[var(--xpe-primary-foreground)]"
                             @click.stop="applyEmbed"
                         >
                             Add
                         </button>
                     </div>
-                    <p v-if="embedError" class="text-center text-xs text-red-500">{{ embedError }}</p>
+                    <p v-if="embedError" class="text-center text-xs text-[var(--xpe-danger)]">{{ embedError }}</p>
                 </div>
             </div>
         </div>
@@ -214,8 +214,8 @@ watch(mode, (next) => {
         <figure v-else class="group/video relative" :style="{ width: `${block.props.width ?? 100}%` }">
             <div @click="emit('select')">
                 <div
-                    class="overflow-hidden rounded-xl bg-black"
-                    :class="selected ? 'ring-2 ring-indigo-400' : ''"
+                    class="overflow-hidden rounded-[var(--xpe-radius)] bg-black"
+                    :class="selected ? 'ring-2 ring-[var(--xpe-ring)]' : ''"
                 >
                     <iframe
                         v-if="isEmbed() && safeEmbedUrl()"
@@ -263,7 +263,7 @@ watch(mode, (next) => {
 
             <figcaption @mousedown.stop @click.stop @pointerdown.stop>
                 <input
-                    class="mt-1.5 w-full bg-transparent text-center text-xs text-gray-400 outline-none placeholder:text-gray-300"
+                    class="mt-1.5 w-full bg-transparent text-center text-xs text-[var(--xpe-muted-foreground)] outline-none placeholder:opacity-60"
                     :value="block.props.caption ?? ''"
                     placeholder="Add caption..."
                     :readonly="readonly"
diff --git a/packages/vue/src/components/toolbar/EditorTableStylePanel.vue b/packages/vue/src/components/toolbar/EditorTableStylePanel.vue
index a3d18dd..622da17 100644
--- a/packages/vue/src/components/toolbar/EditorTableStylePanel.vue
+++ b/packages/vue/src/components/toolbar/EditorTableStylePanel.vue
@@ -177,7 +177,7 @@ function selectBorderStyle(style: TableBorderStyleKind): void {
                     A
                     <Check
                         v-if="isPresetActive(color, currentColor)"
-                        class="absolute -top-1 -right-1 size-3 rounded-full bg-indigo-500 p-0.5 text-white"
+                        class="absolute -top-1 -end-1 size-3 rounded-full bg-indigo-500 p-0.5 text-white"
                     />
                 </button>
             </div>
diff --git a/packages/vue/src/components/toolbar/EditorToolbarColorPanel.vue b/packages/vue/src/components/toolbar/EditorToolbarColorPanel.vue
index 559c2e5..ddf32f8 100644
--- a/packages/vue/src/components/toolbar/EditorToolbarColorPanel.vue
+++ b/packages/vue/src/components/toolbar/EditorToolbarColorPanel.vue
@@ -145,7 +145,7 @@ function isPresetActive(color: string, active: string | null): boolean {
                     A
                     <Check
                         v-if="isPresetActive(color, activeTextColor)"
-                        class="absolute -top-1 -right-1 size-3 rounded-full bg-indigo-500 p-0.5 text-white"
+                        class="absolute -top-1 -end-1 size-3 rounded-full bg-indigo-500 p-0.5 text-white"
                     />
                 </button>
             </div>
@@ -196,7 +196,7 @@ function isPresetActive(color: string, active: string | null): boolean {
                 >
                     <Check
                         v-if="isPresetActive(color, activeHighlight)"
-                        class="absolute -top-1 -right-1 size-3 rounded-full bg-indigo-500 p-0.5 text-white"
+                        class="absolute -top-1 -end-1 size-3 rounded-full bg-indigo-500 p-0.5 text-white"
                     />
                 </button>
             </div>
@@ -224,7 +224,7 @@ function isPresetActive(color: string, active: string | null): boolean {
                 class="h-7 w-full text-xs text-gray-500"
                 @click="resetCurrent"
             >
-                <Highlighter class="mr-1.5 size-3" />
+                <Highlighter class="me-1.5 size-3" />
                 Remove highlight
             </Button>
         </TabsContent>
diff --git a/packages/vue/src/styles/theme.css b/packages/vue/src/styles/theme.css
index 957a3dc..f2fe722 100644
--- a/packages/vue/src/styles/theme.css
+++ b/packages/vue/src/styles/theme.css
@@ -10,5 +10,43 @@
   --xpe-muted: #f3f4f6;
   --xpe-border: #e5e7eb;
   --xpe-primary: #4f46e5;
+  --xpe-primary-foreground: #ffffff;
+  /* subtle tint behind active/selected menu rows and drop zones */
+  --xpe-primary-muted: #eef2ff;
+  /* elevated surfaces: popovers, menus, dialogs */
+  --xpe-surface: #ffffff;
+  --xpe-surface-hover: #f9fafb;
+  /* focus/selection ring around media blocks */
+  --xpe-ring: #818cf8;
+  --xpe-danger: #ef4444;
+  --xpe-radius: 12px;
+  --xpe-shadow:
+    0 10px 15px -3px rgb(0 0 0 / 0.1),
+    0 4px 6px -4px rgb(0 0 0 / 0.05);
   --xpe-font-mono: ui-monospace, SFMono-Regular, Menlo, monospace;
 }
+
+/**
+ * Built-in dark theme. Add the `xpe-dark` class (or `data-xpe-theme="dark"`)
+ * to any ancestor of the editor — typically alongside your app's own dark
+ * mode toggle. Apps with custom palettes can override the same variables
+ * under their own selector instead.
+ */
+.xpe-dark,
+[data-xpe-theme='dark'] {
+  --xpe-background: #111827;
+  --xpe-foreground: #e5e7eb;
+  --xpe-muted-foreground: #9ca3af;
+  --xpe-muted: #1f2937;
+  --xpe-border: #374151;
+  --xpe-primary: #818cf8;
+  --xpe-primary-foreground: #111827;
+  --xpe-primary-muted: rgb(129 140 248 / 0.15);
+  --xpe-surface: #1f2937;
+  --xpe-surface-hover: #273449;
+  --xpe-ring: #6366f1;
+  --xpe-danger: #f87171;
+  --xpe-shadow:
+    0 10px 15px -3px rgb(0 0 0 / 0.5),
+    0 4px 6px -4px rgb(0 0 0 / 0.4);
+}

From 59a11bdda2e5e3166089a906f5ac0e4a105fe041 Mon Sep 17 00:00:00 2001
From: Mohammad Moradi <mohammad.moradi@outlook.com>
Date: Sat, 11 Jul 2026 14:25:27 +0300
Subject: [PATCH 4/7] Bento site redesign + fully token-driven editor chrome
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Site restyled to the Bento reference: monochrome soft-neumorphic palette
  (no accent color), soft gray gradient canvas, pill surfaces with large
  radii and layered shadows, and a light/dark toggle with a diagonal
  View-Transitions sweep between themes.
- Live demo gains an editor theme switcher (Bento / Default) proving the
  editor restyles with a handful of --xpe-* variables, and follows the
  site's dark mode via the packages' built-in xpe-dark scope.
- All remaining hardcoded editor colors converted to theme tokens across
  both adapters: text blocks, headings, toolbars (fixed + bubble),
  popovers, dropdown menus, inputs, tabs, color/emoji pickers, table
  controls, gutter buttons, drop indicators, and callout defaults — the
  dark theme and custom themes now cover the entire editor surface.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .changeset/slash-menu-theming-rtl.md          |   2 +-
 packages/react/src/components/BlockItem.tsx   |  26 +-
 .../react/src/components/BubbleToolbar.tsx    |  22 +-
 .../react/src/components/FormatToolbar.tsx    |  12 +-
 packages/react/src/components/ImageBlock.tsx  |   2 +-
 packages/react/src/components/TableBlock.tsx  |  14 +-
 packages/react/src/components/TableCell.tsx   |   4 +-
 packages/react/src/components/VideoBlock.tsx  |   2 +-
 .../components/toolbar/TableStylePanel.tsx    |  26 +-
 .../src/components/toolbar/ToolbarButton.tsx  |   2 +-
 .../components/toolbar/ToolbarColorPanel.tsx  |  16 +-
 .../src/components/toolbar/ToolbarPopover.tsx |   4 +-
 .../components/toolbar/ToolbarSeparator.tsx   |   2 +-
 packages/react/src/styles/components.css      |  94 +++----
 .../vue/src/components/EditorBlockItem.vue    |  38 +--
 .../src/components/EditorBubbleToolbar.vue    |  34 +--
 .../src/components/EditorFormatToolbar.vue    |  14 +-
 .../vue/src/components/EditorImageBlock.vue   |   2 +-
 .../vue/src/components/EditorTableBlock.vue   |  26 +-
 .../vue/src/components/EditorTableCell.vue    |  16 +-
 .../vue/src/components/EditorTextBlock.vue    |  20 +-
 .../vue/src/components/EditorVideoBlock.vue   |   2 +-
 .../toolbar/EditorTableStylePanel.vue         |  26 +-
 .../toolbar/EditorToolbarButton.vue           |  12 +-
 .../toolbar/EditorToolbarColorPanel.vue       |  16 +-
 .../toolbar/EditorToolbarPopover.vue          |   4 +-
 .../toolbar/EditorToolbarSeparator.vue        |   2 +-
 packages/vue/src/ui/Button.vue                |  18 +-
 packages/vue/src/ui/ColorPickerPanel.vue      |   6 +-
 packages/vue/src/ui/DropdownMenuItem.vue      |   4 +-
 packages/vue/src/ui/IconEmojiPicker.vue       |  12 +-
 packages/vue/src/ui/Input.vue                 |  10 +-
 packages/vue/src/ui/PopoverContent.vue        |   4 +-
 packages/vue/src/ui/TabsList.vue              |   2 +-
 packages/vue/src/ui/TabsTrigger.vue           |   8 +-
 site/src/App.css                              | 252 +++++++++++++-----
 site/src/components/LiveDemo.tsx              |  21 +-
 site/src/components/Nav.tsx                   |  38 +++
 site/src/theme.ts                             |  36 +++
 39 files changed, 531 insertions(+), 320 deletions(-)
 create mode 100644 site/src/theme.ts

diff --git a/.changeset/slash-menu-theming-rtl.md b/.changeset/slash-menu-theming-rtl.md
index 0d67624..8012e6d 100644
--- a/.changeset/slash-menu-theming-rtl.md
+++ b/.changeset/slash-menu-theming-rtl.md
@@ -3,4 +3,4 @@
 '@xproeditor/react': minor
 ---
 
-Slash-command menu now measures itself and positions precisely at the caret — flipping above when near the viewport bottom, clamping to the viewport edges, staying aligned in RTL, and showing a "No results" state instead of abruptly closing. Theming: a richer minimal token set (`--xpe-surface`, `--xpe-surface-hover`, `--xpe-primary-muted`, `--xpe-primary-foreground`, `--xpe-ring`, `--xpe-danger`, `--xpe-radius`, `--xpe-shadow`) plus a built-in dark theme via the `xpe-dark` class or `data-xpe-theme="dark"`; the slash menu and all media blocks are fully token-driven. Remaining physical CSS (left/right) converted to logical properties for correct RTL layout.
+Slash-command menu now measures itself and positions precisely at the caret — flipping above when near the viewport bottom, clamping to the viewport edges, staying aligned in RTL, and showing a "No results" state instead of abruptly closing. Theming: a richer minimal token set (`--xpe-surface`, `--xpe-surface-hover`, `--xpe-primary-muted`, `--xpe-primary-foreground`, `--xpe-ring`, `--xpe-danger`, `--xpe-radius`, `--xpe-shadow`) plus a built-in dark theme via the `xpe-dark` class or `data-xpe-theme="dark"`; the slash menu, media blocks, and all editor chrome (toolbars, popovers, dropdown menus, inputs, tabs, table controls, gutter, text blocks) are fully token-driven, so the built-in dark theme and custom themes restyle the entire editor. Remaining physical CSS (left/right) converted to logical properties for correct RTL layout.
diff --git a/packages/react/src/components/BlockItem.tsx b/packages/react/src/components/BlockItem.tsx
index 2f230cc..5528bc5 100644
--- a/packages/react/src/components/BlockItem.tsx
+++ b/packages/react/src/components/BlockItem.tsx
@@ -234,10 +234,10 @@ export const BlockItem = forwardRef<BlockItemHandle, BlockItemProps>(
                   </DropdownMenuTrigger>
                   <DropdownMenuContent align={isRtl ? 'end' : 'start'} className="w-36">
                     <DropdownMenuItem onClick={onDuplicate}>
-                      <Copy className="w-3.5 h-3.5 text-gray-400" />
+                      <Copy className="w-3.5 h-3.5 text-[var(--xpe-muted-foreground)]" />
                       Duplicate
                     </DropdownMenuItem>
-                    <DropdownMenuItem className="text-red-500" onClick={onRemove}>
+                    <DropdownMenuItem className="text-[var(--xpe-danger)]" onClick={onRemove}>
                       <Trash2 className="w-3.5 h-3.5" />
                       Delete
                     </DropdownMenuItem>
@@ -249,13 +249,13 @@ export const BlockItem = forwardRef<BlockItemHandle, BlockItemProps>(
 
           <div className="relative flex-1 min-w-0 py-[3px]">
             {block.type === 'quote' ? (
-              <div className="flex gap-3 border-s-[3px] border-gray-800 ps-3.5">
+              <div className="flex gap-3 border-s-[3px] border-[var(--xpe-foreground)] ps-3.5">
                 {renderTextBlock('flex-1', 'Quote')}
               </div>
             ) : block.type === 'callout' ? (
               <div
-                className="flex items-start gap-2.5 rounded-xl border border-gray-100 px-3.5 py-3"
-                style={{ background: block.props.color ?? '#f8fafc' }}
+                className="flex items-start gap-2.5 rounded-xl border border-[var(--xpe-border)] px-3.5 py-3"
+                style={{ background: block.props.color ?? 'var(--xpe-muted)' }}
               >
                 <div
                   className="relative shrink-0"
@@ -289,14 +289,14 @@ export const BlockItem = forwardRef<BlockItemHandle, BlockItemProps>(
                   {!readonly && (
                     <button
                       type="button"
-                      className="mt-1 block w-full text-[10px] text-gray-400 hover:text-gray-600"
+                      className="mt-1 block w-full text-[10px] text-[var(--xpe-muted-foreground)] hover:text-[var(--xpe-foreground)]"
                       onClick={() => setShowCalloutColors((v) => !v)}
                     >
                       Color
                     </button>
                   )}
                   {showCalloutColors && !readonly && (
-                    <div className="absolute start-0 top-full z-[60] mt-1 rounded-xl border border-gray-100 bg-white p-2 shadow-xl">
+                    <div className="absolute start-0 top-full z-[60] mt-1 rounded-xl border border-[var(--xpe-border)] bg-[var(--xpe-surface)] p-2 shadow-xl">
                       <div className="flex gap-1">
                         {CALLOUT_COLORS.map((c) => (
                           <button
@@ -323,16 +323,16 @@ export const BlockItem = forwardRef<BlockItemHandle, BlockItemProps>(
                   suppressContentEditableWarning
                 >
                   {block.type === 'bulleted_list_item' && (
-                    <span className="text-gray-800 text-base leading-none mt-1">•</span>
+                    <span className="text-[var(--xpe-foreground)] text-base leading-none mt-1">•</span>
                   )}
                   {block.type === 'numbered_list_item' && (
-                    <span className="text-gray-700 text-[14px] leading-snug tabular-nums">
+                    <span className="text-[var(--xpe-foreground)] text-[14px] leading-snug tabular-nums">
                       {number ?? 1}.
                     </span>
                   )}
                   {block.type === 'to_do' && (
                     <button
-                      className={`w-[15px] h-[15px] mt-1 rounded-[4px] border flex items-center justify-center transition-colors ${block.props.checked ? 'bg-indigo-600 border-indigo-600' : 'border-gray-300 hover:border-indigo-400 bg-white'}`}
+                      className={`w-[15px] h-[15px] mt-1 rounded-[4px] border flex items-center justify-center transition-colors ${block.props.checked ? 'bg-[var(--xpe-primary)] border-[var(--xpe-primary)]' : 'border-[var(--xpe-border)] hover:border-[var(--xpe-ring)] bg-[var(--xpe-surface)]'}`}
                       disabled={readonly}
                       onClick={() => onPatch({ checked: !block.props.checked })}
                     >
@@ -351,7 +351,7 @@ export const BlockItem = forwardRef<BlockItemHandle, BlockItemProps>(
                   )}
                   {block.type === 'toggle' && (
                     <button
-                      className="w-5 h-5 mt-0.5 rounded flex items-center justify-center text-gray-500 hover:bg-gray-100 transition-transform"
+                      className="w-5 h-5 mt-0.5 rounded flex items-center justify-center text-[var(--xpe-muted-foreground)] hover:bg-[var(--xpe-surface-hover)] transition-transform"
                       disabled={readonly}
                       onClick={() => onPatch({ collapsed: !block.props.collapsed })}
                     >
@@ -363,7 +363,7 @@ export const BlockItem = forwardRef<BlockItemHandle, BlockItemProps>(
                 </div>
                 {renderTextBlock(
                   block.type === 'to_do' && block.props.checked
-                    ? 'line-through !text-gray-400'
+                    ? 'line-through !text-[var(--xpe-muted-foreground)]'
                     : undefined,
                   block.type === 'to_do'
                     ? 'To-do'
@@ -438,7 +438,7 @@ export const BlockItem = forwardRef<BlockItemHandle, BlockItemProps>(
               />
             ) : block.type === 'divider' ? (
               <div className="py-2.5 cursor-pointer" onClick={onSelect}>
-                <hr className={`border-gray-200 rounded${selected ? ' !border-indigo-400' : ''}`} />
+                <hr className={`border-[var(--xpe-border)] rounded${selected ? ' !border-[var(--xpe-ring)]' : ''}`} />
               </div>
             ) : (
               renderTextBlock()
diff --git a/packages/react/src/components/BubbleToolbar.tsx b/packages/react/src/components/BubbleToolbar.tsx
index 4bd00f1..b754df1 100644
--- a/packages/react/src/components/BubbleToolbar.tsx
+++ b/packages/react/src/components/BubbleToolbar.tsx
@@ -85,15 +85,15 @@ export function BubbleToolbar({
       style={{ left: position.x, top: position.y, transform: 'translate(-50%, calc(-100% - 8px))' }}
       onMouseDown={(e) => e.preventDefault()}
     >
-      <div className="flex items-center gap-0.5 rounded-xl border border-gray-100 bg-white px-1 py-1 shadow-xl">
+      <div className="flex items-center gap-0.5 rounded-xl border border-[var(--xpe-border)] bg-[var(--xpe-surface)] px-1 py-1 shadow-xl">
         <button
-          className="ebt-btn !w-auto gap-1 px-2 text-[12px] font-medium text-gray-600"
+          className="ebt-btn !w-auto gap-1 px-2 text-[12px] font-medium text-[var(--xpe-muted-foreground)]"
           onClick={() => setPanel((p) => (p === 'turninto' ? 'none' : 'turninto'))}
         >
           {turnIntoLabel}
           <ChevronDown className="size-3" />
         </button>
-        <div className="mx-0.5 h-5 w-px bg-gray-100" />
+        <div className="mx-0.5 h-5 w-px bg-[var(--xpe-muted)]" />
 
         <button
           className={`ebt-btn${activeMarks.bold ? ' ebt-active' : ''}`}
@@ -131,7 +131,7 @@ export function BubbleToolbar({
           <Code className="size-3.5" />
         </button>
 
-        <div className="mx-0.5 h-5 w-px bg-gray-100" />
+        <div className="mx-0.5 h-5 w-px bg-[var(--xpe-muted)]" />
 
         <button
           className={`ebt-btn${panel === 'link' || currentLink ? ' ebt-active' : ''}`}
@@ -150,7 +150,7 @@ export function BubbleToolbar({
       </div>
 
       {panel === 'link' && (
-        <div className="mt-1.5 flex items-center gap-1.5 rounded-xl border border-gray-100 bg-white p-2 shadow-xl">
+        <div className="mt-1.5 flex items-center gap-1.5 rounded-xl border border-[var(--xpe-border)] bg-[var(--xpe-surface)] p-2 shadow-xl">
           <Input
             className="h-8 w-52 text-xs"
             placeholder="https://..."
@@ -172,7 +172,7 @@ export function BubbleToolbar({
             <Button
               variant="ghost"
               size="sm"
-              className="h-8 px-2 text-xs text-red-500 hover:bg-red-50 hover:text-red-600"
+              className="h-8 px-2 text-xs text-[var(--xpe-danger)] hover:bg-red-50 hover:text-red-600"
               onClick={() => {
                 onMark('link', null)
                 setPanel('none')
@@ -186,7 +186,7 @@ export function BubbleToolbar({
 
       {panel === 'color' && (
         <div
-          className="mt-1.5 rounded-xl border border-gray-100 bg-white p-2 shadow-xl"
+          className="mt-1.5 rounded-xl border border-[var(--xpe-border)] bg-[var(--xpe-surface)] p-2 shadow-xl"
           onMouseDown={(e) => e.stopPropagation()}
         >
           <ToolbarColorPanel
@@ -198,22 +198,22 @@ export function BubbleToolbar({
       )}
 
       {panel === 'turninto' && (
-        <div className="mt-1.5 w-48 rounded-xl border border-gray-100 bg-white py-1 shadow-xl">
+        <div className="mt-1.5 w-48 rounded-xl border border-[var(--xpe-border)] bg-[var(--xpe-surface)] py-1 shadow-xl">
           {TURN_INTO.map((t) => {
             const Icon = t.icon
             return (
               <button
                 key={t.type}
                 type="button"
-                className={`flex w-full items-center gap-2.5 px-3 py-2 text-start text-[13px] transition-colors ${t.type === blockType ? 'bg-indigo-50/60 text-indigo-600' : 'text-gray-700 hover:bg-gray-50'}`}
+                className={`flex w-full items-center gap-2.5 px-3 py-2 text-start text-[13px] transition-colors ${t.type === blockType ? 'bg-[var(--xpe-primary-muted)] text-[var(--xpe-primary)]' : 'text-[var(--xpe-foreground)] hover:bg-[var(--xpe-surface-hover)]'}`}
                 onClick={() => {
                   onTurnInto(t.type)
                   setPanel('none')
                 }}
               >
-                <Icon className="size-3.5 shrink-0 text-gray-400" />
+                <Icon className="size-3.5 shrink-0 text-[var(--xpe-muted-foreground)]" />
                 <span className="flex-1">{t.label}</span>
-                {t.type === blockType && <Check className="size-3.5 shrink-0 text-indigo-500" />}
+                {t.type === blockType && <Check className="size-3.5 shrink-0 text-[var(--xpe-primary)]" />}
               </button>
             )
           })}
diff --git a/packages/react/src/components/FormatToolbar.tsx b/packages/react/src/components/FormatToolbar.tsx
index 6486e36..85e5360 100644
--- a/packages/react/src/components/FormatToolbar.tsx
+++ b/packages/react/src/components/FormatToolbar.tsx
@@ -139,7 +139,7 @@ export function FormatToolbar({
   const tableActionsDisabled = disabled || !isTable
 
   return (
-    <div className="border-b border-gray-100 bg-white px-4 py-2" data-pro-editor-toolbar>
+    <div className="border-b border-[var(--xpe-border)] bg-[var(--xpe-surface)] px-4 py-2" data-pro-editor-toolbar>
       <div className="mx-auto flex max-w-4xl flex-wrap items-center gap-0.5">
         <ToolbarPopover
           open={turnIntoOpen}
@@ -158,16 +158,16 @@ export function FormatToolbar({
               <button
                 key={t.type}
                 type="button"
-                className={`flex w-full items-center gap-2.5 px-3 py-2 text-start text-[13px] transition-colors ${t.type === state?.blockType ? 'bg-indigo-50/60 text-indigo-600' : 'text-gray-700 hover:bg-gray-50'}`}
+                className={`flex w-full items-center gap-2.5 px-3 py-2 text-start text-[13px] transition-colors ${t.type === state?.blockType ? 'bg-[var(--xpe-primary-muted)] text-[var(--xpe-primary)]' : 'text-[var(--xpe-foreground)] hover:bg-[var(--xpe-surface-hover)]'}`}
                 onClick={() => {
                   onTurnInto(t.type)
                   setTurnIntoOpen(false)
                 }}
               >
-                <Icon className="size-3.5 shrink-0 text-gray-400" />
+                <Icon className="size-3.5 shrink-0 text-[var(--xpe-muted-foreground)]" />
                 <span className="flex-1">{t.label}</span>
                 {t.type === state?.blockType && (
-                  <Check className="size-3.5 shrink-0 text-indigo-500" />
+                  <Check className="size-3.5 shrink-0 text-[var(--xpe-primary)]" />
                 )}
               </button>
             )
@@ -255,7 +255,7 @@ export function FormatToolbar({
               <Button
                 variant="ghost"
                 size="sm"
-                className="h-8 px-2 text-xs text-red-500 hover:bg-red-50 hover:text-red-600"
+                className="h-8 px-2 text-xs text-[var(--xpe-danger)] hover:bg-red-50 hover:text-red-600"
                 onClick={() => {
                   onMark('link', null)
                   setLinkOpen(false)
@@ -317,7 +317,7 @@ export function FormatToolbar({
                   onPointerDown={(e) => e.stopPropagation()}
                 >
                   <IconValueDisplay icon={selected ?? '💡'} className="size-4" />
-                  <ChevronDown className="size-3 text-gray-400" />
+                  <ChevronDown className="size-3 text-[var(--xpe-muted-foreground)]" />
                 </ToolbarButton>
               )}
             />
diff --git a/packages/react/src/components/ImageBlock.tsx b/packages/react/src/components/ImageBlock.tsx
index 8826136..7ab6ea4 100644
--- a/packages/react/src/components/ImageBlock.tsx
+++ b/packages/react/src/components/ImageBlock.tsx
@@ -232,7 +232,7 @@ export function ImageBlock({
             {WIDTHS.map((w) => (
               <button
                 key={w}
-                className={`rounded-md px-1.5 py-0.5 text-[10px] font-medium transition-colors ${(block.props.width ?? 100) === w ? 'bg-white text-gray-900' : 'text-white/80 hover:bg-white/20'}`}
+                className={`rounded-md px-1.5 py-0.5 text-[10px] font-medium transition-colors ${(block.props.width ?? 100) === w ? 'bg-[var(--xpe-surface)] text-[var(--xpe-foreground)]' : 'text-white/80 hover:bg-white/20'}`}
                 onClick={(e) => {
                   e.stopPropagation()
                   onPatch({ width: w })
diff --git a/packages/react/src/components/TableBlock.tsx b/packages/react/src/components/TableBlock.tsx
index 2af0f81..6eec56c 100644
--- a/packages/react/src/components/TableBlock.tsx
+++ b/packages/react/src/components/TableBlock.tsx
@@ -190,7 +190,7 @@ export const TableBlock = forwardRef<TableBlockHandle, TableBlockProps>(function
           <button className="etable-btn" disabled={!unmergeEnabled} onClick={handleUnmerge}>
             <SplitSquareHorizontal className="inline h-3 w-3" /> Unmerge
           </button>
-          <div className="flex items-center gap-1 rounded-md border border-gray-100 bg-gray-50 px-1 py-0.5">
+          <div className="flex items-center gap-1 rounded-md border border-[var(--xpe-border)] bg-[var(--xpe-muted)] px-1 py-0.5">
             <button
               className={`etable-btn${getResolvedTableWidth(table.width).mode === 'percent' ? ' etable-btn-active' : ''}`}
               onClick={() => setWidthMode('percent')}
@@ -218,7 +218,7 @@ export const TableBlock = forwardRef<TableBlockHandle, TableBlockProps>(function
                 type="number"
                 min={200}
                 max={2000}
-                className="w-16 rounded border border-gray-200 px-1 py-0.5 text-[11px]"
+                className="w-16 rounded border border-[var(--xpe-border)] px-1 py-0.5 text-[11px]"
                 value={getResolvedTableWidth(table.width).value}
                 onChange={(e) => setWidthValue(Number(e.target.value))}
               />
@@ -229,7 +229,7 @@ export const TableBlock = forwardRef<TableBlockHandle, TableBlockProps>(function
 
       <div className="flex items-start">
         <div
-          className="flex-1 overflow-x-auto rounded-lg border border-gray-200"
+          className="flex-1 overflow-x-auto rounded-lg border border-[var(--xpe-border)]"
           style={wrapperStyle}
         >
           <table className="w-full border-collapse">
@@ -273,7 +273,7 @@ export const TableBlock = forwardRef<TableBlockHandle, TableBlockProps>(function
                   <td className="w-6 border-0 align-middle">
                     {!readonly && (
                       <button
-                        className="hidden h-5 w-5 items-center justify-center rounded text-gray-300 hover:text-red-500 group-hover/row:flex"
+                        className="hidden h-5 w-5 items-center justify-center rounded text-gray-300 hover:text-[var(--xpe-danger)] group-hover/row:flex"
                         title="Remove row"
                         onClick={() => updateTable(removeTableRow(table, rowIdx))}
                       >
@@ -287,7 +287,7 @@ export const TableBlock = forwardRef<TableBlockHandle, TableBlockProps>(function
           </table>
           {!readonly && (
             <button
-              className="flex w-full items-center justify-center py-1 text-gray-300 transition-colors hover:bg-indigo-50/40 hover:text-indigo-500"
+              className="flex w-full items-center justify-center py-1 text-gray-300 transition-colors hover:bg-[var(--xpe-primary-muted)]/40 hover:text-[var(--xpe-primary)]"
               title="Add row"
               onClick={() => updateTable(addTableRow(table))}
             >
@@ -298,7 +298,7 @@ export const TableBlock = forwardRef<TableBlockHandle, TableBlockProps>(function
         {!readonly && (
           <div className="ms-1 flex flex-col gap-1 self-stretch">
             <button
-              className="flex items-center rounded px-1 text-gray-300 transition-colors hover:bg-indigo-50/40 hover:text-indigo-500"
+              className="flex items-center rounded px-1 text-gray-300 transition-colors hover:bg-[var(--xpe-primary-muted)]/40 hover:text-[var(--xpe-primary)]"
               title="Add column"
               onClick={() => updateTable(addTableColumn(table))}
             >
@@ -306,7 +306,7 @@ export const TableBlock = forwardRef<TableBlockHandle, TableBlockProps>(function
             </button>
             {table.rows[0]?.length ? (
               <button
-                className="flex items-center rounded px-1 text-gray-300 transition-colors hover:bg-red-50/40 hover:text-red-500"
+                className="flex items-center rounded px-1 text-gray-300 transition-colors hover:bg-red-50/40 hover:text-[var(--xpe-danger)]"
                 title="Remove last column"
                 onClick={() =>
                   updateTable(removeTableColumn(table, (table.rows[0]?.length ?? 1) - 1))
diff --git a/packages/react/src/components/TableCell.tsx b/packages/react/src/components/TableCell.tsx
index 8cc3c12..555475e 100644
--- a/packages/react/src/components/TableCell.tsx
+++ b/packages/react/src/components/TableCell.tsx
@@ -221,7 +221,7 @@ export const TableCell = forwardRef<TableCellHandle, TableCellProps>(function Ta
 
   return (
     <Tag
-      className={`etc-cell border border-gray-150 p-0 relative min-w-[100px] align-top ${isHeader ? 'bg-gray-50/80' : ''} ${selected ? 'ring-2 ring-indigo-400 ring-inset' : ''}`}
+      className={`etc-cell border border-gray-150 p-0 relative min-w-[100px] align-top ${isHeader ? 'bg-[var(--xpe-muted)]/80' : ''} ${selected ? 'ring-2 ring-[var(--xpe-ring)] ring-inset' : ''}`}
       style={cellStyle}
       colSpan={cell.colspan && cell.colspan > 1 ? cell.colspan : undefined}
       rowSpan={cell.rowspan && cell.rowspan > 1 ? cell.rowspan : undefined}
@@ -231,7 +231,7 @@ export const TableCell = forwardRef<TableCellHandle, TableCellProps>(function Ta
         ref={el}
         contentEditable={!readonly}
         suppressContentEditableWarning
-        className={`etc-editor outline-none w-full px-3 py-2 text-sm text-gray-700 min-h-[2.25rem] ${isHeader ? 'font-semibold text-gray-800' : ''}`}
+        className={`etc-editor outline-none w-full px-3 py-2 text-sm text-[var(--xpe-foreground)] min-h-[2.25rem] ${isHeader ? 'font-semibold text-[var(--xpe-foreground)]' : ''}`}
         style={cell.align ? { textAlign: cell.align as TableCellAlign } : undefined}
         dir="auto"
         spellCheck={false}
diff --git a/packages/react/src/components/VideoBlock.tsx b/packages/react/src/components/VideoBlock.tsx
index fdd194b..e933e28 100644
--- a/packages/react/src/components/VideoBlock.tsx
+++ b/packages/react/src/components/VideoBlock.tsx
@@ -277,7 +277,7 @@ export function VideoBlock({
             {WIDTHS.map((w) => (
               <button
                 key={w}
-                className={`rounded-md px-1.5 py-0.5 text-[10px] font-medium transition-colors ${(block.props.width ?? 100) === w ? 'bg-white text-gray-900' : 'text-white/80 hover:bg-white/20'}`}
+                className={`rounded-md px-1.5 py-0.5 text-[10px] font-medium transition-colors ${(block.props.width ?? 100) === w ? 'bg-[var(--xpe-surface)] text-[var(--xpe-foreground)]' : 'text-white/80 hover:bg-white/20'}`}
                 onClick={(e) => {
                   e.stopPropagation()
                   onPatch({ width: w })
diff --git a/packages/react/src/components/toolbar/TableStylePanel.tsx b/packages/react/src/components/toolbar/TableStylePanel.tsx
index 06c8f42..e037458 100644
--- a/packages/react/src/components/toolbar/TableStylePanel.tsx
+++ b/packages/react/src/components/toolbar/TableStylePanel.tsx
@@ -115,7 +115,7 @@ export function TableStylePanel({
       </TabsList>
 
       <TabsContent value="text" className="mt-0 space-y-3">
-        <p className="text-[10px] font-semibold tracking-wider text-gray-400 uppercase">
+        <p className="text-[10px] font-semibold tracking-wider text-[var(--xpe-muted-foreground)] uppercase">
           Text color
         </p>
         <div className="grid grid-cols-5 gap-1.5">
@@ -129,13 +129,13 @@ export function TableStylePanel({
             >
               A
               {isPresetActive(color, currentColor) && (
-                <Check className="absolute -top-1 -end-1 size-3 rounded-full bg-indigo-500 p-0.5 text-white" />
+                <Check className="absolute -top-1 -end-1 size-3 rounded-full bg-[var(--xpe-primary-muted)]0 p-0.5 text-white" />
               )}
             </button>
           ))}
         </div>
 
-        <p className="text-[10px] font-semibold tracking-wider text-gray-400 uppercase">
+        <p className="text-[10px] font-semibold tracking-wider text-[var(--xpe-muted-foreground)] uppercase">
           Highlight
         </p>
         <div className="grid grid-cols-4 gap-1.5">
@@ -150,7 +150,7 @@ export function TableStylePanel({
           ))}
         </div>
 
-        <div className="border-t border-gray-100 pt-3">
+        <div className="border-t border-[var(--xpe-border)] pt-3">
           <ColorPickerPanel
             value={pickerColor}
             onChange={onPickerInput}
@@ -216,7 +216,7 @@ export function TableStylePanel({
       </TabsContent>
 
       <TabsContent value="table" className="mt-0 space-y-3">
-        <p className="text-[10px] font-semibold tracking-wider text-gray-400 uppercase">
+        <p className="text-[10px] font-semibold tracking-wider text-[var(--xpe-muted-foreground)] uppercase">
           Table background
         </p>
         <div className="grid grid-cols-5 gap-1.5">
@@ -231,7 +231,7 @@ export function TableStylePanel({
           ))}
         </div>
 
-        <p className="text-[10px] font-semibold tracking-wider text-gray-400 uppercase">
+        <p className="text-[10px] font-semibold tracking-wider text-[var(--xpe-muted-foreground)] uppercase">
           Header background
         </p>
         <div className="grid grid-cols-5 gap-1.5">
@@ -266,12 +266,12 @@ export function TableStylePanel({
 
       <TabsContent value="border" className="mt-0 space-y-3">
         <div
-          className="rounded-md border bg-white p-3"
+          className="rounded-md border bg-[var(--xpe-surface)] p-3"
           style={{
             border: `${resolvedBorder.width}px ${resolvedBorder.style} ${resolvedBorder.color}`,
           }}
         >
-          <div className="text-xs text-gray-500">Preview</div>
+          <div className="text-xs text-[var(--xpe-muted-foreground)]">Preview</div>
         </div>
 
         <div className="grid grid-cols-4 gap-1.5">
@@ -279,20 +279,20 @@ export function TableStylePanel({
             <button
               key={color}
               type="button"
-              className={`relative size-7 rounded-md border-2 bg-white ${isPresetActive(color, resolvedBorder.color) ? 'ring-2 ring-indigo-500 ring-offset-1' : ''}`}
+              className={`relative size-7 rounded-md border-2 bg-[var(--xpe-surface)] ${isPresetActive(color, resolvedBorder.color) ? 'ring-2 ring-indigo-500 ring-offset-1' : ''}`}
               style={{ borderColor: color }}
               onClick={() => onTableStyle({ border: { color } })}
             />
           ))}
         </div>
 
-        <p className="text-[10px] font-semibold tracking-wider text-gray-400 uppercase">Width</p>
+        <p className="text-[10px] font-semibold tracking-wider text-[var(--xpe-muted-foreground)] uppercase">Width</p>
         <div className="flex flex-wrap gap-1">
           {TABLE_BORDER_WIDTHS.map((width: TableBorderWidth) => (
             <button
               key={width}
               type="button"
-              className={`rounded-md border px-2 py-1 text-[11px] ${resolvedBorder.width === width ? 'border-indigo-300 bg-indigo-50 text-indigo-600' : 'border-gray-200 text-gray-600'}`}
+              className={`rounded-md border px-2 py-1 text-[11px] ${resolvedBorder.width === width ? 'border-indigo-300 bg-[var(--xpe-primary-muted)] text-[var(--xpe-primary)]' : 'border-[var(--xpe-border)] text-[var(--xpe-muted-foreground)]'}`}
               onClick={() => onTableStyle({ border: { width } })}
             >
               {width}px
@@ -300,13 +300,13 @@ export function TableStylePanel({
           ))}
         </div>
 
-        <p className="text-[10px] font-semibold tracking-wider text-gray-400 uppercase">Style</p>
+        <p className="text-[10px] font-semibold tracking-wider text-[var(--xpe-muted-foreground)] uppercase">Style</p>
         <div className="flex flex-wrap gap-1">
           {TABLE_BORDER_STYLES.map((style: TableBorderStyleKind) => (
             <button
               key={style}
               type="button"
-              className={`rounded-md border px-2 py-1 text-[11px] capitalize ${resolvedBorder.style === style ? 'border-indigo-300 bg-indigo-50 text-indigo-600' : 'border-gray-200 text-gray-600'}`}
+              className={`rounded-md border px-2 py-1 text-[11px] capitalize ${resolvedBorder.style === style ? 'border-indigo-300 bg-[var(--xpe-primary-muted)] text-[var(--xpe-primary)]' : 'border-[var(--xpe-border)] text-[var(--xpe-muted-foreground)]'}`}
               onClick={() => onTableStyle({ border: { style } })}
             >
               {style}
diff --git a/packages/react/src/components/toolbar/ToolbarButton.tsx b/packages/react/src/components/toolbar/ToolbarButton.tsx
index ff99319..36346b9 100644
--- a/packages/react/src/components/toolbar/ToolbarButton.tsx
+++ b/packages/react/src/components/toolbar/ToolbarButton.tsx
@@ -13,7 +13,7 @@ export function ToolbarButton({ active, wide, className, ...rest }: ToolbarButto
       className={cn(
         'ebt-btn',
         active && 'ebt-active',
-        wide && '!w-auto gap-1 px-2 text-xs font-medium text-gray-600',
+        wide && '!w-auto gap-1 px-2 text-xs font-medium text-[var(--xpe-muted-foreground)]',
         className,
       )}
       {...rest}
diff --git a/packages/react/src/components/toolbar/ToolbarColorPanel.tsx b/packages/react/src/components/toolbar/ToolbarColorPanel.tsx
index 66d6d2f..3098443 100644
--- a/packages/react/src/components/toolbar/ToolbarColorPanel.tsx
+++ b/packages/react/src/components/toolbar/ToolbarColorPanel.tsx
@@ -131,14 +131,14 @@ export function ToolbarColorPanel({
             >
               A
               {isPresetActive(color, activeTextColor) && (
-                <Check className="absolute -top-1 -end-1 size-3 rounded-full bg-indigo-500 p-0.5 text-white" />
+                <Check className="absolute -top-1 -end-1 size-3 rounded-full bg-[var(--xpe-primary-muted)]0 p-0.5 text-white" />
               )}
             </button>
           ))}
         </div>
 
-        <div className="border-t border-gray-100 pt-3">
-          <p className="mb-2 text-[10px] font-semibold tracking-wider text-gray-400 uppercase">
+        <div className="border-t border-[var(--xpe-border)] pt-3">
+          <p className="mb-2 text-[10px] font-semibold tracking-wider text-[var(--xpe-muted-foreground)] uppercase">
             Custom
           </p>
           <div onFocus={() => (isEditingPicker.current = true)}>
@@ -156,7 +156,7 @@ export function ToolbarColorPanel({
           <Button
             variant="ghost"
             size="sm"
-            className="h-7 w-full text-xs text-gray-500"
+            className="h-7 w-full text-xs text-[var(--xpe-muted-foreground)]"
             onClick={resetCurrent}
           >
             Reset text color
@@ -176,14 +176,14 @@ export function ToolbarColorPanel({
               onClick={() => selectHighlight(color)}
             >
               {isPresetActive(color, activeHighlight) && (
-                <Check className="absolute -top-1 -end-1 size-3 rounded-full bg-indigo-500 p-0.5 text-white" />
+                <Check className="absolute -top-1 -end-1 size-3 rounded-full bg-[var(--xpe-primary-muted)]0 p-0.5 text-white" />
               )}
             </button>
           ))}
         </div>
 
-        <div className="border-t border-gray-100 pt-3">
-          <p className="mb-2 text-[10px] font-semibold tracking-wider text-gray-400 uppercase">
+        <div className="border-t border-[var(--xpe-border)] pt-3">
+          <p className="mb-2 text-[10px] font-semibold tracking-wider text-[var(--xpe-muted-foreground)] uppercase">
             Custom
           </p>
           <div onFocus={() => (isEditingPicker.current = true)}>
@@ -201,7 +201,7 @@ export function ToolbarColorPanel({
           <Button
             variant="ghost"
             size="sm"
-            className="h-7 w-full text-xs text-gray-500"
+            className="h-7 w-full text-xs text-[var(--xpe-muted-foreground)]"
             onClick={resetCurrent}
           >
             <Highlighter className="me-1.5 size-3" />
diff --git a/packages/react/src/components/toolbar/ToolbarPopover.tsx b/packages/react/src/components/toolbar/ToolbarPopover.tsx
index 30043bf..43494d7 100644
--- a/packages/react/src/components/toolbar/ToolbarPopover.tsx
+++ b/packages/react/src/components/toolbar/ToolbarPopover.tsx
@@ -30,11 +30,11 @@ export function ToolbarPopover({
         align={align}
         side={side}
         sideOffset={6}
-        className={cn('w-auto rounded-xl border-gray-100 p-2 shadow-xl', contentClassName)}
+        className={cn('w-auto rounded-xl border-[var(--xpe-border)] p-2 shadow-xl', contentClassName)}
         onMouseDown={(e) => e.stopPropagation()}
       >
         {title && (
-          <p className="mb-2 px-1 text-[11px] font-semibold tracking-wide text-gray-500 uppercase">
+          <p className="mb-2 px-1 text-[11px] font-semibold tracking-wide text-[var(--xpe-muted-foreground)] uppercase">
             {title}
           </p>
         )}
diff --git a/packages/react/src/components/toolbar/ToolbarSeparator.tsx b/packages/react/src/components/toolbar/ToolbarSeparator.tsx
index a6afbf5..04e0c18 100644
--- a/packages/react/src/components/toolbar/ToolbarSeparator.tsx
+++ b/packages/react/src/components/toolbar/ToolbarSeparator.tsx
@@ -1,3 +1,3 @@
 export function ToolbarSeparator() {
-  return <div className="xpe-toolbar-separator mx-0.5 h-5 w-px bg-gray-100" />
+  return <div className="xpe-toolbar-separator mx-0.5 h-5 w-px bg-[var(--xpe-muted)]" />
 }
diff --git a/packages/react/src/styles/components.css b/packages/react/src/styles/components.css
index 5ef767c..e4b05f4 100644
--- a/packages/react/src/styles/components.css
+++ b/packages/react/src/styles/components.css
@@ -21,30 +21,30 @@
 .xpe-btn--md { height: 36px; padding: 0 14px; font-size: 13px; }
 .xpe-btn--sm { height: 28px; padding: 0 10px; font-size: 12px; }
 .xpe-btn--icon { height: 32px; width: 32px; padding: 0; }
-.xpe-btn--default { background: #4f46e5; color: #fff; }
+.xpe-btn--default { background: var(--xpe-primary, #4f46e5); color: var(--xpe-primary-foreground, #fff); }
 .xpe-btn--default:hover:not(:disabled) { background: #4338ca; }
-.xpe-btn--outline { background: #fff; border-color: #e5e7eb; color: #374151; }
-.xpe-btn--outline:hover:not(:disabled) { background: #f9fafb; }
-.xpe-btn--ghost { background: transparent; color: #374151; }
-.xpe-btn--ghost:hover:not(:disabled) { background: #f3f4f6; }
+.xpe-btn--outline { background: var(--xpe-surface, #fff); border-color: var(--xpe-border, #e5e7eb); color: var(--xpe-foreground, #374151); }
+.xpe-btn--outline:hover:not(:disabled) { background: var(--xpe-surface-hover, #f9fafb); }
+.xpe-btn--ghost { background: transparent; color: var(--xpe-foreground, #374151); }
+.xpe-btn--ghost:hover:not(:disabled) { background: var(--xpe-muted, #f3f4f6); }
 
 /* ── ui/Input ──────────────────────────────────────────────────────────── */
 .xpe-input {
   width: 100%;
   border-radius: 8px;
-  border: 1px solid #e5e7eb;
+  border: 1px solid var(--xpe-border, #e5e7eb);
   padding: 0 10px;
   font-size: 13px;
-  color: #111827;
-  background: #fff;
+  color: var(--xpe-foreground, #111827);
+  background: var(--xpe-surface, #fff);
   outline: none;
   transition: border-color 0.12s, box-shadow 0.12s;
 }
-.xpe-input:focus { border-color: #6366f1; box-shadow: 0 0 0 3px rgb(99 102 241 / 0.15); }
-.xpe-input::placeholder { color: #9ca3af; }
+.xpe-input:focus { border-color: var(--xpe-ring, #6366f1); box-shadow: 0 0 0 3px rgb(99 102 241 / 0.15); }
+.xpe-input::placeholder { color: var(--xpe-muted-foreground, #9ca3af); }
 
 /* ── ui/Tabs ───────────────────────────────────────────────────────────── */
-.xpe-tabs-list { display: grid; gap: 4px; background: #f3f4f6; border-radius: 8px; padding: 3px; }
+.xpe-tabs-list { display: grid; gap: 4px; background: var(--xpe-muted, #f3f4f6); border-radius: 8px; padding: 3px; }
 .xpe-tabs-trigger {
   border: none;
   background: transparent;
@@ -52,20 +52,20 @@
   padding: 5px 8px;
   font-size: 12px;
   font-weight: 500;
-  color: #6b7280;
+  color: var(--xpe-muted-foreground, #6b7280);
   cursor: pointer;
   transition: background 0.12s, color 0.12s;
 }
-.xpe-tabs-trigger:hover { color: #111827; }
-.xpe-tabs-trigger--active { background: #fff; color: #111827; box-shadow: 0 1px 2px rgb(0 0 0 / 0.06); }
+.xpe-tabs-trigger:hover { color: var(--xpe-foreground, #111827); }
+.xpe-tabs-trigger--active { background: var(--xpe-surface, #fff); color: var(--xpe-foreground, #111827); box-shadow: 0 1px 2px rgb(0 0 0 / 0.06); }
 
 /* ── ui/Popover & DropdownMenu ─────────────────────────────────────────── */
 .xpe-popover-content {
   z-index: 80;
   border-radius: 12px;
-  border: 1px solid #f3f4f6;
-  background: #fff;
-  box-shadow: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1);
+  border: 1px solid var(--xpe-border, #f3f4f6);
+  background: var(--xpe-surface, #fff);
+  box-shadow: var(--xpe-shadow, 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1));
 }
 .xpe-dropdown-content { padding: 4px; }
 .xpe-dropdown-item {
@@ -78,26 +78,26 @@
   background: transparent;
   border-radius: 6px;
   font-size: 13px;
-  color: #374151;
+  color: var(--xpe-foreground, #374151);
   cursor: pointer;
   text-align: start;
 }
-.xpe-dropdown-item:hover { background: #f9fafb; }
+.xpe-dropdown-item:hover { background: var(--xpe-surface-hover, #f9fafb); }
 
 /* ── ui/ColorPickerPanel ───────────────────────────────────────────────── */
 .xpe-color-picker { display: flex; align-items: center; gap: 8px; }
-.xpe-color-swatch { width: 32px; height: 32px; padding: 0; border: 1px solid #e5e7eb; border-radius: 8px; cursor: pointer; background: none; }
+.xpe-color-swatch { width: 32px; height: 32px; padding: 0; border: 1px solid var(--xpe-border, #e5e7eb); border-radius: 8px; cursor: pointer; background: none; }
 .xpe-color-hex {
   flex: 1;
   height: 32px;
-  border: 1px solid #e5e7eb;
+  border: 1px solid var(--xpe-border, #e5e7eb);
   border-radius: 8px;
   padding: 0 8px;
   font-size: 12px;
   font-family: var(--xpe-font-mono, ui-monospace, monospace);
   outline: none;
 }
-.xpe-color-hex:focus { border-color: #6366f1; }
+.xpe-color-hex:focus { border-color: var(--xpe-ring, #6366f1); }
 
 /* ── ui/IconEmojiPicker & IconValueDisplay ────────────────────────────── */
 .xpe-icon-value { display: inline-flex; align-items: center; justify-content: center; line-height: 1; }
@@ -105,11 +105,11 @@
 .xpe-icon-popover { padding: 10px; width: 232px; }
 .xpe-icon-grid { display: grid; grid-template-columns: repeat(8, 1fr); gap: 2px; }
 .xpe-icon-cell { display: flex; align-items: center; justify-content: center; height: 26px; border-radius: 6px; border: none; background: transparent; font-size: 15px; cursor: pointer; }
-.xpe-icon-cell:hover { background: #f3f4f6; }
-.xpe-icon-cell--active { background: #eef2ff; }
-.xpe-icon-custom { display: flex; gap: 6px; margin-top: 8px; padding-top: 8px; border-top: 1px solid #f3f4f6; }
-.xpe-icon-custom-input { flex: 1; height: 28px; border: 1px solid #e5e7eb; border-radius: 6px; padding: 0 8px; font-size: 12px; outline: none; }
-.xpe-icon-custom-apply { height: 28px; padding: 0 10px; border-radius: 6px; border: none; background: #4f46e5; color: #fff; font-size: 12px; cursor: pointer; }
+.xpe-icon-cell:hover { background: var(--xpe-muted, #f3f4f6); }
+.xpe-icon-cell--active { background: var(--xpe-primary-muted, #eef2ff); }
+.xpe-icon-custom { display: flex; gap: 6px; margin-top: 8px; padding-top: 8px; border-top: 1px solid var(--xpe-border, #f3f4f6); }
+.xpe-icon-custom-input { flex: 1; height: 28px; border: 1px solid var(--xpe-border, #e5e7eb); border-radius: 6px; padding: 0 8px; font-size: 12px; outline: none; }
+.xpe-icon-custom-apply { height: 28px; padding: 0 10px; border-radius: 6px; border: none; background: var(--xpe-primary, #4f46e5); color: var(--xpe-primary-foreground, #fff); font-size: 12px; cursor: pointer; }
 
 /* ── toolbar/ToolbarButton (also used standalone in BubbleToolbar) ──────── */
 .ebt-btn {
@@ -121,18 +121,18 @@
   border-radius: 8px;
   border: none;
   background: transparent;
-  color: #4b5563;
+  color: var(--xpe-muted-foreground, #4b5563);
   cursor: pointer;
   transition: background 0.1s, color 0.1s;
 }
-.ebt-btn:hover:not(:disabled) { background: #f3f4f6; color: #111827; }
+.ebt-btn:hover:not(:disabled) { background: var(--xpe-muted, #f3f4f6); color: var(--xpe-foreground, #111827); }
 .ebt-btn:disabled { opacity: 0.35; cursor: not-allowed; }
-.ebt-active { background: #eef2ff; color: #4f46e5; }
+.ebt-active { background: var(--xpe-primary-muted, #eef2ff); color: var(--xpe-primary, #4f46e5); }
 .xpe-toolbar-separator { flex-shrink: 0; }
 
 /* ── EditorBlockItem ───────────────────────────────────────────────────── */
-.ebi-selected { background: rgb(99 102 241 / 0.06); border-radius: 6px; }
-.ebi-drop { position: absolute; inset-inline-start: 28px; inset-inline-end: 0; height: 3px; background: #818cf8; border-radius: 2px; z-index: 10; pointer-events: none; }
+.ebi-selected { background: var(--xpe-primary-muted, rgb(99 102 241 / 0.06)); border-radius: 6px; }
+.ebi-drop { position: absolute; inset-inline-start: 28px; inset-inline-end: 0; height: 3px; background: var(--xpe-ring, #818cf8); border-radius: 2px; z-index: 10; pointer-events: none; }
 .ebi-gutter-btn {
   display: flex;
   align-items: center;
@@ -142,12 +142,12 @@
   border-radius: 6px;
   border: none;
   background: transparent;
-  color: #c0c4cc;
+  color: var(--xpe-muted-foreground, #c0c4cc);
   cursor: pointer;
   transition: background 0.1s, color 0.1s;
   padding: 0;
 }
-.ebi-gutter-btn:hover { background: #f3f4f6; color: #6b7280; }
+.ebi-gutter-btn:hover { background: var(--xpe-muted, #f3f4f6); color: var(--xpe-foreground, #6b7280); }
 .ebi-chevron-rtl { transform: scaleX(-1); }
 .ebi-chevron-rtl.rotate-90 { transform: scaleX(-1) rotate(90deg); }
 
@@ -156,22 +156,22 @@
   min-height: 1.6em;
   line-height: 1.65;
   font-size: 16px;
-  color: #1f2937;
+  color: var(--xpe-foreground, #1f2937);
   white-space: pre-wrap;
   word-break: break-word;
-  caret-color: #4f46e5;
+  caret-color: var(--xpe-primary, #4f46e5);
   --pro-editor-selection: rgb(35 131 226 / 0.18);
 }
 .etb::selection { background: var(--pro-editor-selection); }
 .etb-readonly { cursor: default; user-select: text; }
-.etb:empty::before { content: attr(data-placeholder); color: #c4c8d0; pointer-events: none; float: inline-start; }
-.etb-heading_1 { font-size: 28px; font-weight: 700; line-height: 1.3; color: #111827; }
-.etb-heading_2 { font-size: 22px; font-weight: 650; line-height: 1.35; color: #111827; }
-.etb-heading_3 { font-size: 18px; font-weight: 600; line-height: 1.4; color: #111827; }
-.etb-quote { font-style: italic; color: #4b5563; }
+.etb:empty::before { content: attr(data-placeholder); color: var(--xpe-muted-foreground, #c4c8d0); opacity: 0.55; pointer-events: none; float: inline-start; }
+.etb-heading_1 { font-size: 28px; font-weight: 700; line-height: 1.3; color: var(--xpe-foreground, #111827); }
+.etb-heading_2 { font-size: 22px; font-weight: 650; line-height: 1.35; color: var(--xpe-foreground, #111827); }
+.etb-heading_3 { font-size: 18px; font-weight: 600; line-height: 1.4; color: var(--xpe-foreground, #111827); }
+.etb-quote { font-style: italic; color: var(--xpe-muted-foreground, #4b5563); }
 .etb-callout { font-size: 15px; }
-.etb code { background: #f1f3f5; border: 1px solid #e9ecef; border-radius: 4px; padding: 1px 5px; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 0.85em; color: #e0316e; }
-.etb a { color: #4f46e5; text-decoration: underline; text-underline-offset: 2px; cursor: pointer; }
+.etb code { background: var(--xpe-muted, #f1f3f5); border: 1px solid var(--xpe-border, #e9ecef); border-radius: 4px; padding: 1px 5px; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 0.85em; color: #e0316e; }
+.etb a { color: var(--xpe-primary, #4f46e5); text-decoration: underline; text-underline-offset: 2px; cursor: pointer; }
 
 /* ── EditorCodeBlock ───────────────────────────────────────────────────── */
 .ecb textarea { min-height: 48px; tab-size: 2; }
@@ -182,8 +182,8 @@
   align-items: center;
   gap: 4px;
   font-size: 11px;
-  color: #9ca3af;
-  background: #f9fafb;
+  color: var(--xpe-muted-foreground, #9ca3af);
+  background: var(--xpe-muted, #f9fafb);
   border: 1px solid #f3f4f6;
   border-radius: 6px;
   padding: 2px 8px;
@@ -194,9 +194,9 @@
 .etable-btn-active { color: #4f46e5; border-color: #c7d2fe; background: #eef2ff; }
 
 /* ── EditorTableCell ───────────────────────────────────────────────────── */
-.etc-editor { white-space: pre-wrap; word-break: break-word; caret-color: #4f46e5; }
+.etc-editor { white-space: pre-wrap; word-break: break-word; caret-color: var(--xpe-primary, #4f46e5); }
 .etc-editor:empty::before { content: ' '; pointer-events: none; }
-.etc-editor code { background: #f1f3f5; border: 1px solid #e9ecef; border-radius: 4px; padding: 1px 5px; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 0.85em; color: #e0316e; }
+.etc-editor code { background: var(--xpe-muted, #f1f3f5); border: 1px solid var(--xpe-border, #e9ecef); border-radius: 4px; padding: 1px 5px; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 0.85em; color: #e0316e; }
 .etc-editor a { color: #4f46e5; text-decoration: underline; text-underline-offset: 2px; }
 .border-gray-150 { border-color: #eceef1; }
 
diff --git a/packages/vue/src/components/EditorBlockItem.vue b/packages/vue/src/components/EditorBlockItem.vue
index 488e90c..10fd777 100644
--- a/packages/vue/src/components/EditorBlockItem.vue
+++ b/packages/vue/src/components/EditorBlockItem.vue
@@ -181,10 +181,10 @@ defineExpose({
             </DropdownMenuTrigger>
             <DropdownMenuContent :align="isRtl ? 'end' : 'start'" class="w-36">
               <DropdownMenuItem @click="emit('duplicate')">
-                <Copy class="w-3.5 h-3.5 text-gray-400" />
+                <Copy class="w-3.5 h-3.5 text-[var(--xpe-muted-foreground)]" />
                 Duplicate
               </DropdownMenuItem>
-              <DropdownMenuItem class="text-red-500 focus:text-red-500" @click="emit('remove')">
+              <DropdownMenuItem class="text-[var(--xpe-danger)] focus:text-[var(--xpe-danger)]" @click="emit('remove')">
                 <Trash2 class="w-3.5 h-3.5" />
                 Delete
               </DropdownMenuItem>
@@ -196,7 +196,7 @@ defineExpose({
       <!-- Block body -->
       <div class="relative flex-1 min-w-0 py-[3px]">
         <!-- Quote -->
-        <div v-if="block.type === 'quote'" class="flex gap-3 border-s-[3px] border-gray-800 ps-3.5">
+        <div v-if="block.type === 'quote'" class="flex gap-3 border-s-[3px] border-[var(--xpe-foreground)] ps-3.5">
           <EditorTextBlock
             ref="inner"
             :block="block"
@@ -220,8 +220,8 @@ defineExpose({
         <!-- Callout -->
         <div
           v-else-if="block.type === 'callout'"
-          class="flex items-start gap-2.5 rounded-xl border border-gray-100 px-3.5 py-3"
-          :style="{ background: block.props.color ?? '#f8fafc' }"
+          class="flex items-start gap-2.5 rounded-xl border border-[var(--xpe-border)] px-3.5 py-3"
+          :style="{ background: block.props.color ?? 'var(--xpe-muted)' }"
         >
           <div class="relative shrink-0" contenteditable="false" @click.stop @pointerdown.stop>
             <IconEmojiPicker
@@ -250,14 +250,14 @@ defineExpose({
             <button
               v-if="!readonly"
               type="button"
-              class="mt-1 block w-full text-[10px] text-gray-400 hover:text-gray-600"
+              class="mt-1 block w-full text-[10px] text-[var(--xpe-muted-foreground)] hover:text-[var(--xpe-foreground)]"
               @click="showCalloutColors = !showCalloutColors"
             >
               Color
             </button>
             <div
               v-if="showCalloutColors && !readonly"
-              class="absolute start-0 top-full z-[60] mt-1 rounded-xl border border-gray-100 bg-white p-2 shadow-xl"
+              class="absolute start-0 top-full z-[60] mt-1 rounded-xl border border-[var(--xpe-border)] bg-[var(--xpe-surface)] p-2 shadow-xl"
             >
               <div class="flex gap-1">
                 <button
@@ -293,12 +293,12 @@ defineExpose({
         <!-- Lists / to-do / toggle -->
         <div v-else-if="['bulleted_list_item', 'numbered_list_item', 'to_do', 'toggle'].includes(block.type)" class="ebi-list-row flex items-start gap-1.5">
           <div class="shrink-0 flex items-center justify-center w-6 pt-[5px] select-none" contenteditable="false">
-            <span v-if="block.type === 'bulleted_list_item'" class="text-gray-800 text-base leading-none mt-1">•</span>
-            <span v-else-if="block.type === 'numbered_list_item'" class="text-gray-700 text-[14px] leading-snug tabular-nums">{{ number ?? 1 }}.</span>
+            <span v-if="block.type === 'bulleted_list_item'" class="text-[var(--xpe-foreground)] text-base leading-none mt-1">•</span>
+            <span v-else-if="block.type === 'numbered_list_item'" class="text-[var(--xpe-foreground)] text-[14px] leading-snug tabular-nums">{{ number ?? 1 }}.</span>
             <button
               v-else-if="block.type === 'to_do'"
               class="w-[15px] h-[15px] mt-1 rounded-[4px] border flex items-center justify-center transition-colors"
-              :class="block.props.checked ? 'bg-indigo-600 border-indigo-600' : 'border-gray-300 hover:border-indigo-400 bg-white'"
+              :class="block.props.checked ? 'bg-[var(--xpe-primary)] border-[var(--xpe-primary)]' : 'border-[var(--xpe-border)] hover:border-[var(--xpe-ring)] bg-[var(--xpe-surface)]'"
               :disabled="readonly"
               @click="emit('patch', { checked: !block.props.checked })"
             >
@@ -306,7 +306,7 @@ defineExpose({
             </button>
             <button
               v-else
-              class="w-5 h-5 mt-0.5 rounded flex items-center justify-center text-gray-500 hover:bg-gray-100 transition-transform"
+              class="w-5 h-5 mt-0.5 rounded flex items-center justify-center text-[var(--xpe-muted-foreground)] hover:bg-[var(--xpe-surface-hover)] transition-transform"
               :disabled="readonly"
               @click="emit('patch', { collapsed: !block.props.collapsed })"
             >
@@ -325,7 +325,7 @@ defineExpose({
             :readonly="readonly"
             :placeholder="placeholder ?? (block.type === 'to_do' ? 'To-do' : block.type === 'toggle' ? 'Toggle' : 'List item')"
             class="flex-1"
-            :class="{ 'line-through !text-gray-400': block.type === 'to_do' && block.props.checked }"
+            :class="{ 'line-through !text-[var(--xpe-muted-foreground)]': block.type === 'to_do' && block.props.checked }"
             @input="(s, c) => emit('input', s, c)"
             @enter="o => emit('enter', o)"
             @backspace-start="emit('backspaceStart')"
@@ -419,7 +419,7 @@ defineExpose({
           class="py-2.5 cursor-pointer"
           @click="emit('select')"
         >
-          <hr class="border-gray-200 rounded" :class="{ '!border-indigo-400': selected }" />
+          <hr class="border-[var(--xpe-border)] rounded" :class="{ '!border-[var(--xpe-ring)]': selected }" />
         </div>
 
         <!-- Plain text blocks -->
@@ -455,7 +455,7 @@ defineExpose({
 
 <style scoped>
 .ebi-selected {
-  background: rgb(99 102 241 / 0.06);
+  background: var(--xpe-primary-muted, rgb(99 102 241 / 0.06));
   border-radius: 6px;
 }
 .ebi-drop {
@@ -463,7 +463,7 @@ defineExpose({
   inset-inline-start: 28px;
   inset-inline-end: 0;
   height: 3px;
-  background: #818cf8;
+  background: var(--xpe-ring, #818cf8);
   border-radius: 2px;
   z-index: 10;
   pointer-events: none;
@@ -477,12 +477,12 @@ defineExpose({
   border-radius: 6px;
   border: none;
   background: transparent;
-  color: #c0c4cc;
+  color: var(--xpe-muted-foreground, #c0c4cc);
   cursor: pointer;
   transition: background 0.1s, color 0.1s;
   padding: 0;
 }
-.ebi-gutter-btn:hover { background: #f3f4f6; color: #6b7280; }
+.ebi-gutter-btn:hover { background: var(--xpe-muted, #f3f4f6); color: var(--xpe-foreground, #6b7280); }
 .ebi-chevron-rtl {
   transform: scaleX(-1);
 }
@@ -496,11 +496,11 @@ defineExpose({
   width: 100%;
   padding: 6px 12px;
   font-size: 13px;
-  color: #374151;
+  color: var(--xpe-foreground, #374151);
   background: transparent;
   border: none;
   cursor: pointer;
   text-align: left;
 }
-.ebi-menu-item:hover { background: #f9fafb; }
+.ebi-menu-item:hover { background: var(--xpe-surface-hover, #f9fafb); }
 </style>
diff --git a/packages/vue/src/components/EditorBubbleToolbar.vue b/packages/vue/src/components/EditorBubbleToolbar.vue
index 50135d5..a954deb 100644
--- a/packages/vue/src/components/EditorBubbleToolbar.vue
+++ b/packages/vue/src/components/EditorBubbleToolbar.vue
@@ -92,16 +92,16 @@ function turnIntoLabel(): string {
             @mousedown.prevent
         >
             <div
-                class="flex items-center gap-0.5 rounded-xl border border-gray-100 bg-white px-1 py-1 shadow-xl"
+                class="flex items-center gap-0.5 rounded-xl border border-[var(--xpe-border)] bg-[var(--xpe-surface)] px-1 py-1 shadow-xl"
             >
                 <button
-                    class="ebt-btn !w-auto gap-1 px-2 text-[12px] font-medium text-gray-600"
+                    class="ebt-btn !w-auto gap-1 px-2 text-[12px] font-medium text-[var(--xpe-muted-foreground)]"
                     @click="panel = panel === 'turninto' ? 'none' : 'turninto'"
                 >
                     {{ turnIntoLabel() }}
                     <ChevronDown class="size-3" />
                 </button>
-                <div class="mx-0.5 h-5 w-px bg-gray-100" />
+                <div class="mx-0.5 h-5 w-px bg-[var(--xpe-muted)]" />
 
                 <button
                     class="ebt-btn"
@@ -144,7 +144,7 @@ function turnIntoLabel(): string {
                     <Code class="size-3.5" />
                 </button>
 
-                <div class="mx-0.5 h-5 w-px bg-gray-100" />
+                <div class="mx-0.5 h-5 w-px bg-[var(--xpe-muted)]" />
 
                 <button
                     class="ebt-btn"
@@ -169,7 +169,7 @@ function turnIntoLabel(): string {
 
             <div
                 v-if="panel === 'link'"
-                class="mt-1.5 flex items-center gap-1.5 rounded-xl border border-gray-100 bg-white p-2 shadow-xl"
+                class="mt-1.5 flex items-center gap-1.5 rounded-xl border border-[var(--xpe-border)] bg-[var(--xpe-surface)] p-2 shadow-xl"
             >
                 <Input
                     v-model="linkInput"
@@ -187,7 +187,7 @@ function turnIntoLabel(): string {
                     type="button"
                     variant="ghost"
                     size="sm"
-                    class="h-8 px-2 text-xs text-red-500 hover:bg-red-50 hover:text-red-600"
+                    class="h-8 px-2 text-xs text-[var(--xpe-danger)] hover:bg-red-50 hover:text-red-600"
                     @click="emit('mark', 'link', null); panel = 'none'"
                 >
                     Remove
@@ -196,7 +196,7 @@ function turnIntoLabel(): string {
 
             <div
                 v-if="panel === 'color'"
-                class="mt-1.5 rounded-xl border border-gray-100 bg-white p-2 shadow-xl"
+                class="mt-1.5 rounded-xl border border-[var(--xpe-border)] bg-[var(--xpe-surface)] p-2 shadow-xl"
                 @mousedown.stop
             >
                 <EditorToolbarColorPanel
@@ -208,7 +208,7 @@ function turnIntoLabel(): string {
 
             <div
                 v-if="panel === 'turninto'"
-                class="mt-1.5 w-48 rounded-xl border border-gray-100 bg-white py-1 shadow-xl"
+                class="mt-1.5 w-48 rounded-xl border border-[var(--xpe-border)] bg-[var(--xpe-surface)] py-1 shadow-xl"
             >
                 <button
                     v-for="t in TURN_INTO"
@@ -217,16 +217,16 @@ function turnIntoLabel(): string {
                     class="flex w-full items-center gap-2.5 px-3 py-2 text-start text-[13px] transition-colors"
                     :class="
                         t.type === blockType
-                            ? 'bg-indigo-50/60 text-indigo-600'
-                            : 'text-gray-700 hover:bg-gray-50'
+                            ? 'bg-[var(--xpe-primary-muted)] text-[var(--xpe-primary)]'
+                            : 'text-[var(--xpe-foreground)] hover:bg-[var(--xpe-surface-hover)]'
                     "
                     @click="emit('turnInto', t.type); panel = 'none'"
                 >
-                    <component :is="t.icon" class="size-3.5 shrink-0 text-gray-400" />
+                    <component :is="t.icon" class="size-3.5 shrink-0 text-[var(--xpe-muted-foreground)]" />
                     <span class="flex-1">{{ t.label }}</span>
                     <Check
                         v-if="t.type === blockType"
-                        class="size-3.5 shrink-0 text-indigo-500"
+                        class="size-3.5 shrink-0 text-[var(--xpe-primary)]"
                     />
                 </button>
             </div>
@@ -244,18 +244,18 @@ function turnIntoLabel(): string {
     border-radius: 8px;
     border: none;
     background: transparent;
-    color: #4b5563;
+    color: var(--xpe-muted-foreground, #4b5563);
     cursor: pointer;
     transition:
         background 0.1s,
         color 0.1s;
 }
 .ebt-btn:hover {
-    background: #f3f4f6;
-    color: #111827;
+    background: var(--xpe-muted, #f3f4f6);
+    color: var(--xpe-foreground, #111827);
 }
 .ebt-active {
-    background: #eef2ff;
-    color: #4f46e5;
+    background: var(--xpe-primary-muted, #eef2ff);
+    color: var(--xpe-primary, #4f46e5);
 }
 </style>
diff --git a/packages/vue/src/components/EditorFormatToolbar.vue b/packages/vue/src/components/EditorFormatToolbar.vue
index 77f22b1..76d195e 100644
--- a/packages/vue/src/components/EditorFormatToolbar.vue
+++ b/packages/vue/src/components/EditorFormatToolbar.vue
@@ -155,7 +155,7 @@ const tableActionsDisabled = () => disabled() || !isTable();
 </script>
 
 <template>
-    <div class="border-b border-gray-100 bg-white px-4 py-2" data-pro-editor-toolbar>
+    <div class="border-b border-[var(--xpe-border)] bg-[var(--xpe-surface)] px-4 py-2" data-pro-editor-toolbar>
         <div class="mx-auto flex max-w-4xl flex-wrap items-center gap-0.5">
             <EditorToolbarPopover
                 v-model:open="turnIntoOpen"
@@ -175,16 +175,16 @@ const tableActionsDisabled = () => disabled() || !isTable();
                     class="flex w-full items-center gap-2.5 px-3 py-2 text-start text-[13px] transition-colors"
                     :class="
                         t.type === state?.blockType
-                            ? 'bg-indigo-50/60 text-indigo-600'
-                            : 'text-gray-700 hover:bg-gray-50'
+                            ? 'bg-[var(--xpe-primary-muted)] text-[var(--xpe-primary)]'
+                            : 'text-[var(--xpe-foreground)] hover:bg-[var(--xpe-surface-hover)]'
                     "
                     @click="emit('turnInto', t.type); turnIntoOpen = false"
                 >
-                    <component :is="t.icon" class="size-3.5 shrink-0 text-gray-400" />
+                    <component :is="t.icon" class="size-3.5 shrink-0 text-[var(--xpe-muted-foreground)]" />
                     <span class="flex-1">{{ t.label }}</span>
                     <Check
                         v-if="t.type === state?.blockType"
-                        class="size-3.5 shrink-0 text-indigo-500"
+                        class="size-3.5 shrink-0 text-[var(--xpe-primary)]"
                     />
                 </button>
             </EditorToolbarPopover>
@@ -265,7 +265,7 @@ const tableActionsDisabled = () => disabled() || !isTable();
                         type="button"
                         variant="ghost"
                         size="sm"
-                        class="h-8 px-2 text-xs text-red-500 hover:bg-red-50 hover:text-red-600"
+                        class="h-8 px-2 text-xs text-[var(--xpe-danger)] hover:bg-red-50 hover:text-red-600"
                         @click="emit('mark', 'link', null); linkOpen = false"
                     >
                         Remove
@@ -316,7 +316,7 @@ const tableActionsDisabled = () => disabled() || !isTable();
                             @pointerdown.stop
                         >
                             <IconValueDisplay :icon="selected ?? '💡'" class="size-4" />
-                            <ChevronDown class="size-3 text-gray-400" />
+                            <ChevronDown class="size-3 text-[var(--xpe-muted-foreground)]" />
                         </EditorToolbarButton>
                     </template>
                 </IconEmojiPicker>
diff --git a/packages/vue/src/components/EditorImageBlock.vue b/packages/vue/src/components/EditorImageBlock.vue
index 45f99ef..bbb32d0 100644
--- a/packages/vue/src/components/EditorImageBlock.vue
+++ b/packages/vue/src/components/EditorImageBlock.vue
@@ -221,7 +221,7 @@ watch(mode, (next) => {
                     class="rounded-md px-1.5 py-0.5 text-[10px] font-medium transition-colors"
                     :class="
                         (block.props.width ?? 100) === w
-                            ? 'bg-white text-gray-900'
+                            ? 'bg-[var(--xpe-surface)] text-[var(--xpe-foreground)]'
                             : 'text-white/80 hover:bg-white/20'
                     "
                     @click.stop="emit('patch', { width: w })"
diff --git a/packages/vue/src/components/EditorTableBlock.vue b/packages/vue/src/components/EditorTableBlock.vue
index 6ba2cff..04b10bd 100644
--- a/packages/vue/src/components/EditorTableBlock.vue
+++ b/packages/vue/src/components/EditorTableBlock.vue
@@ -175,7 +175,7 @@ defineExpose({
       <button class="etable-btn" :disabled="!unmergeEnabled" @click="handleUnmerge">
         <SplitSquareHorizontal class="inline h-3 w-3" /> Unmerge
       </button>
-      <div class="flex items-center gap-1 rounded-md border border-gray-100 bg-gray-50 px-1 py-0.5">
+      <div class="flex items-center gap-1 rounded-md border border-[var(--xpe-border)] bg-[var(--xpe-muted)] px-1 py-0.5">
         <button
           class="etable-btn"
           :class="getResolvedTableWidth(table.width).mode === 'percent' ? 'etable-btn-active' : ''"
@@ -206,7 +206,7 @@ defineExpose({
           type="number"
           min="200"
           max="2000"
-          class="w-16 rounded border border-gray-200 px-1 py-0.5 text-[11px]"
+          class="w-16 rounded border border-[var(--xpe-border)] px-1 py-0.5 text-[11px]"
           :value="getResolvedTableWidth(table.width).value"
           @change="setWidthValue(Number(($event.target as HTMLInputElement).value))"
         />
@@ -214,7 +214,7 @@ defineExpose({
     </div>
 
     <div class="flex items-start">
-      <div class="flex-1 overflow-x-auto rounded-lg border border-gray-200" :style="wrapperStyle">
+      <div class="flex-1 overflow-x-auto rounded-lg border border-[var(--xpe-border)]" :style="wrapperStyle">
         <table class="w-full border-collapse">
           <tbody>
             <tr v-for="(row, rowIdx) in table.rows" :key="rowIdx" class="group/row">
@@ -243,7 +243,7 @@ defineExpose({
               <td class="w-6 border-0 align-middle">
                 <button
                   v-if="!readonly"
-                  class="hidden h-5 w-5 items-center justify-center rounded text-gray-300 hover:text-red-500 group-hover/row:flex"
+                  class="hidden h-5 w-5 items-center justify-center rounded text-gray-300 hover:text-[var(--xpe-danger)] group-hover/row:flex"
                   title="Remove row"
                   @click="patchTable(removeTableRow(table, rowIdx))"
                 >
@@ -255,7 +255,7 @@ defineExpose({
         </table>
         <button
           v-if="!readonly"
-          class="flex w-full items-center justify-center py-1 text-gray-300 transition-colors hover:bg-indigo-50/40 hover:text-indigo-500"
+          class="flex w-full items-center justify-center py-1 text-gray-300 transition-colors hover:bg-[var(--xpe-primary-muted)]/40 hover:text-[var(--xpe-primary)]"
           title="Add row"
           @click="patchTable(addTableRow(table))"
         >
@@ -264,7 +264,7 @@ defineExpose({
       </div>
       <div v-if="!readonly" class="ms-1 flex flex-col gap-1 self-stretch">
         <button
-          class="flex items-center rounded px-1 text-gray-300 transition-colors hover:bg-indigo-50/40 hover:text-indigo-500"
+          class="flex items-center rounded px-1 text-gray-300 transition-colors hover:bg-[var(--xpe-primary-muted)]/40 hover:text-[var(--xpe-primary)]"
           title="Add column"
           @click="patchTable(addTableColumn(table))"
         >
@@ -272,7 +272,7 @@ defineExpose({
         </button>
         <button
           v-if="table.rows[0]?.length"
-          class="flex items-center rounded px-1 text-gray-300 transition-colors hover:bg-red-50/40 hover:text-red-500"
+          class="flex items-center rounded px-1 text-gray-300 transition-colors hover:bg-red-50/40 hover:text-[var(--xpe-danger)]"
           title="Remove last column"
           @click="patchTable(removeTableColumn(table, (table.rows[0]?.length ?? 1) - 1))"
         >
@@ -289,15 +289,15 @@ defineExpose({
   align-items: center;
   gap: 4px;
   font-size: 11px;
-  color: #9ca3af;
-  background: #f9fafb;
-  border: 1px solid #f3f4f6;
+  color: var(--xpe-muted-foreground, #9ca3af);
+  background: var(--xpe-surface-hover, #f9fafb);
+  border: 1px solid var(--xpe-muted, #f3f4f6);
   border-radius: 6px;
   padding: 2px 8px;
   cursor: pointer;
 }
 .etable-btn:hover:not(:disabled) {
-  color: #4f46e5;
+  color: var(--xpe-primary, #4f46e5);
   border-color: #e0e7ff;
 }
 .etable-btn:disabled {
@@ -305,8 +305,8 @@ defineExpose({
   cursor: not-allowed;
 }
 .etable-btn-active {
-  color: #4f46e5;
+  color: var(--xpe-primary, #4f46e5);
   border-color: #c7d2fe;
-  background: #eef2ff;
+  background: var(--xpe-primary-muted, #eef2ff);
 }
 </style>
diff --git a/packages/vue/src/components/EditorTableCell.vue b/packages/vue/src/components/EditorTableCell.vue
index 2b7fa52..8d5c68d 100644
--- a/packages/vue/src/components/EditorTableCell.vue
+++ b/packages/vue/src/components/EditorTableCell.vue
@@ -234,8 +234,8 @@ defineExpose({ focusAt, getSelection, setSelection, el })
     :is="isHeader ? 'th' : 'td'"
     class="etc-cell border border-gray-150 p-0 relative min-w-[100px] align-top"
     :class="[
-      isHeader ? 'bg-gray-50/80' : '',
-      selected ? 'ring-2 ring-indigo-400 ring-inset' : '',
+      isHeader ? 'bg-[var(--xpe-muted)]/80' : '',
+      selected ? 'ring-2 ring-[var(--xpe-ring)] ring-inset' : '',
     ]"
     :style="cellStyle"
     :colspan="cell.colspan && cell.colspan > 1 ? cell.colspan : undefined"
@@ -245,8 +245,8 @@ defineExpose({ focusAt, getSelection, setSelection, el })
     <div
       ref="el"
       :contenteditable="!readonly"
-      class="etc-editor outline-none w-full px-3 py-2 text-sm text-gray-700 min-h-[2.25rem]"
-      :class="isHeader ? 'font-semibold text-gray-800' : ''"
+      class="etc-editor outline-none w-full px-3 py-2 text-sm text-[var(--xpe-foreground)] min-h-[2.25rem]"
+      :class="isHeader ? 'font-semibold text-[var(--xpe-foreground)]' : ''"
       :style="cell.align ? { textAlign: cell.align as TableCellAlign } : undefined"
       dir="auto"
       spellcheck="false"
@@ -262,15 +262,15 @@ defineExpose({ focusAt, getSelection, setSelection, el })
 .etc-editor {
   white-space: pre-wrap;
   word-break: break-word;
-  caret-color: #4f46e5;
+  caret-color: var(--xpe-primary, #4f46e5);
 }
 .etc-editor:empty::before {
   content: ' ';
   pointer-events: none;
 }
 .etc-editor :deep(code) {
-  background: #f1f3f5;
-  border: 1px solid #e9ecef;
+  background: var(--xpe-muted, #f1f3f5);
+  border: 1px solid var(--xpe-border, #e9ecef);
   border-radius: 4px;
   padding: 1px 5px;
   font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
@@ -278,7 +278,7 @@ defineExpose({ focusAt, getSelection, setSelection, el })
   color: #e0316e;
 }
 .etc-editor :deep(a) {
-  color: #4f46e5;
+  color: var(--xpe-primary, #4f46e5);
   text-decoration: underline;
   text-underline-offset: 2px;
 }
diff --git a/packages/vue/src/components/EditorTextBlock.vue b/packages/vue/src/components/EditorTextBlock.vue
index 6bfb753..ca2b5ee 100644
--- a/packages/vue/src/components/EditorTextBlock.vue
+++ b/packages/vue/src/components/EditorTextBlock.vue
@@ -274,10 +274,10 @@ defineExpose({ focusAt, getSelection, setSelection, el })
   min-height: 1.6em;
   line-height: 1.65;
   font-size: 16px;
-  color: #1f2937;
+  color: var(--xpe-foreground, #1f2937);
   white-space: pre-wrap;
   word-break: break-word;
-  caret-color: #4f46e5;
+  caret-color: var(--xpe-primary, #4f46e5);
   --pro-editor-selection: rgb(35 131 226 / 0.18);
 }
 .etb::selection {
@@ -289,20 +289,20 @@ defineExpose({ focusAt, getSelection, setSelection, el })
 }
 .etb:empty::before {
   content: attr(data-placeholder);
-  color: #c4c8d0;
+  color: var(--xpe-muted-foreground, #c4c8d0);
   pointer-events: none;
   float: inline-start;
 }
 
-.etb-heading_1 { font-size: 28px; font-weight: 700; line-height: 1.3; color: #111827; }
-.etb-heading_2 { font-size: 22px; font-weight: 650; line-height: 1.35; color: #111827; }
-.etb-heading_3 { font-size: 18px; font-weight: 600; line-height: 1.4; color: #111827; }
-.etb-quote { font-style: italic; color: #4b5563; }
+.etb-heading_1 { font-size: 28px; font-weight: 700; line-height: 1.3; color: var(--xpe-foreground, #111827); }
+.etb-heading_2 { font-size: 22px; font-weight: 650; line-height: 1.35; color: var(--xpe-foreground, #111827); }
+.etb-heading_3 { font-size: 18px; font-weight: 600; line-height: 1.4; color: var(--xpe-foreground, #111827); }
+.etb-quote { font-style: italic; color: var(--xpe-muted-foreground, #4b5563); }
 .etb-callout { font-size: 15px; }
 
 .etb :deep(code) {
-  background: #f1f3f5;
-  border: 1px solid #e9ecef;
+  background: var(--xpe-muted, #f1f3f5);
+  border: 1px solid var(--xpe-border, #e9ecef);
   border-radius: 4px;
   padding: 1px 5px;
   font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
@@ -310,7 +310,7 @@ defineExpose({ focusAt, getSelection, setSelection, el })
   color: #e0316e;
 }
 .etb :deep(a) {
-  color: #4f46e5;
+  color: var(--xpe-primary, #4f46e5);
   text-decoration: underline;
   text-underline-offset: 2px;
   cursor: pointer;
diff --git a/packages/vue/src/components/EditorVideoBlock.vue b/packages/vue/src/components/EditorVideoBlock.vue
index 34d9a13..8f3b88a 100644
--- a/packages/vue/src/components/EditorVideoBlock.vue
+++ b/packages/vue/src/components/EditorVideoBlock.vue
@@ -245,7 +245,7 @@ watch(mode, (next) => {
                     class="rounded-md px-1.5 py-0.5 text-[10px] font-medium transition-colors"
                     :class="
                         (block.props.width ?? 100) === w
-                            ? 'bg-white text-gray-900'
+                            ? 'bg-[var(--xpe-surface)] text-[var(--xpe-foreground)]'
                             : 'text-white/80 hover:bg-white/20'
                     "
                     @click.stop="emit('patch', { width: w })"
diff --git a/packages/vue/src/components/toolbar/EditorTableStylePanel.vue b/packages/vue/src/components/toolbar/EditorTableStylePanel.vue
index 622da17..5a50e29 100644
--- a/packages/vue/src/components/toolbar/EditorTableStylePanel.vue
+++ b/packages/vue/src/components/toolbar/EditorTableStylePanel.vue
@@ -163,7 +163,7 @@ function selectBorderStyle(style: TableBorderStyleKind): void {
         </TabsList>
 
         <TabsContent value="text" class="mt-0 space-y-3">
-            <p class="text-[10px] font-semibold tracking-wider text-gray-400 uppercase">Text color</p>
+            <p class="text-[10px] font-semibold tracking-wider text-[var(--xpe-muted-foreground)] uppercase">Text color</p>
             <div class="grid grid-cols-5 gap-1.5">
                 <button
                     v-for="color in TEXT_COLOR_PRESETS"
@@ -177,12 +177,12 @@ function selectBorderStyle(style: TableBorderStyleKind): void {
                     A
                     <Check
                         v-if="isPresetActive(color, currentColor)"
-                        class="absolute -top-1 -end-1 size-3 rounded-full bg-indigo-500 p-0.5 text-white"
+                        class="absolute -top-1 -end-1 size-3 rounded-full bg-[var(--xpe-primary-muted)]0 p-0.5 text-white"
                     />
                 </button>
             </div>
 
-            <p class="text-[10px] font-semibold tracking-wider text-gray-400 uppercase">Highlight</p>
+            <p class="text-[10px] font-semibold tracking-wider text-[var(--xpe-muted-foreground)] uppercase">Highlight</p>
             <div class="grid grid-cols-4 gap-1.5">
                 <button
                     v-for="color in HIGHLIGHT_PRESETS"
@@ -195,7 +195,7 @@ function selectBorderStyle(style: TableBorderStyleKind): void {
                 />
             </div>
 
-            <div class="border-t border-gray-100 pt-3">
+            <div class="border-t border-[var(--xpe-border)] pt-3">
                 <ColorPickerPanel
                     v-model="pickerColor"
                     compact
@@ -242,7 +242,7 @@ function selectBorderStyle(style: TableBorderStyleKind): void {
         </TabsContent>
 
         <TabsContent value="table" class="mt-0 space-y-3">
-            <p class="text-[10px] font-semibold tracking-wider text-gray-400 uppercase">Table background</p>
+            <p class="text-[10px] font-semibold tracking-wider text-[var(--xpe-muted-foreground)] uppercase">Table background</p>
             <div class="grid grid-cols-5 gap-1.5">
                 <button
                     v-for="color in TABLE_BG_PRESETS"
@@ -255,7 +255,7 @@ function selectBorderStyle(style: TableBorderStyleKind): void {
                 />
             </div>
 
-            <p class="text-[10px] font-semibold tracking-wider text-gray-400 uppercase">Header background</p>
+            <p class="text-[10px] font-semibold tracking-wider text-[var(--xpe-muted-foreground)] uppercase">Header background</p>
             <div class="grid grid-cols-5 gap-1.5">
                 <button
                     v-for="color in TABLE_BG_PRESETS"
@@ -278,10 +278,10 @@ function selectBorderStyle(style: TableBorderStyleKind): void {
 
         <TabsContent value="border" class="mt-0 space-y-3">
             <div
-                class="rounded-md border bg-white p-3"
+                class="rounded-md border bg-[var(--xpe-surface)] p-3"
                 :style="{ border: `${resolvedBorder.width}px ${resolvedBorder.style} ${resolvedBorder.color}` }"
             >
-                <div class="text-xs text-gray-500">Preview</div>
+                <div class="text-xs text-[var(--xpe-muted-foreground)]">Preview</div>
             </div>
 
             <div class="grid grid-cols-4 gap-1.5">
@@ -289,35 +289,35 @@ function selectBorderStyle(style: TableBorderStyleKind): void {
                     v-for="color in TABLE_BORDER_PRESETS"
                     :key="color"
                     type="button"
-                    class="relative size-7 rounded-md border-2 bg-white"
+                    class="relative size-7 rounded-md border-2 bg-[var(--xpe-surface)]"
                     :class="cn(isPresetActive(color, resolvedBorder.color) && 'ring-2 ring-indigo-500 ring-offset-1')"
                     :style="{ borderColor: color }"
                     @click="selectBorderColor(color)"
                 />
             </div>
 
-            <p class="text-[10px] font-semibold tracking-wider text-gray-400 uppercase">Width</p>
+            <p class="text-[10px] font-semibold tracking-wider text-[var(--xpe-muted-foreground)] uppercase">Width</p>
             <div class="flex flex-wrap gap-1">
                 <button
                     v-for="width in TABLE_BORDER_WIDTHS"
                     :key="width"
                     type="button"
                     class="rounded-md border px-2 py-1 text-[11px]"
-                    :class="resolvedBorder.width === width ? 'border-indigo-300 bg-indigo-50 text-indigo-600' : 'border-gray-200 text-gray-600'"
+                    :class="resolvedBorder.width === width ? 'border-indigo-300 bg-[var(--xpe-primary-muted)] text-[var(--xpe-primary)]' : 'border-[var(--xpe-border)] text-[var(--xpe-muted-foreground)]'"
                     @click="selectBorderWidth(width)"
                 >
                     {{ width }}px
                 </button>
             </div>
 
-            <p class="text-[10px] font-semibold tracking-wider text-gray-400 uppercase">Style</p>
+            <p class="text-[10px] font-semibold tracking-wider text-[var(--xpe-muted-foreground)] uppercase">Style</p>
             <div class="flex flex-wrap gap-1">
                 <button
                     v-for="style in TABLE_BORDER_STYLES"
                     :key="style"
                     type="button"
                     class="rounded-md border px-2 py-1 text-[11px] capitalize"
-                    :class="resolvedBorder.style === style ? 'border-indigo-300 bg-indigo-50 text-indigo-600' : 'border-gray-200 text-gray-600'"
+                    :class="resolvedBorder.style === style ? 'border-indigo-300 bg-[var(--xpe-primary-muted)] text-[var(--xpe-primary)]' : 'border-[var(--xpe-border)] text-[var(--xpe-muted-foreground)]'"
                     @click="selectBorderStyle(style)"
                 >
                     {{ style }}
diff --git a/packages/vue/src/components/toolbar/EditorToolbarButton.vue b/packages/vue/src/components/toolbar/EditorToolbarButton.vue
index e4e9309..917fd19 100644
--- a/packages/vue/src/components/toolbar/EditorToolbarButton.vue
+++ b/packages/vue/src/components/toolbar/EditorToolbarButton.vue
@@ -21,7 +21,7 @@ withDefaults(
     <button
         type="button"
         class="ebt-btn"
-        :class="cn(active && 'ebt-active', wide && '!w-auto gap-1 px-2 text-xs font-medium text-gray-600')"
+        :class="cn(active && 'ebt-active', wide && '!w-auto gap-1 px-2 text-xs font-medium text-[var(--xpe-muted-foreground)]')"
         :disabled="disabled"
         :title="title"
     >
@@ -39,22 +39,22 @@ withDefaults(
     border-radius: 8px;
     border: none;
     background: transparent;
-    color: #4b5563;
+    color: var(--xpe-muted-foreground, #4b5563);
     cursor: pointer;
     transition:
         background 0.1s,
         color 0.1s;
 }
 .ebt-btn:hover:not(:disabled) {
-    background: #f3f4f6;
-    color: #111827;
+    background: var(--xpe-muted, #f3f4f6);
+    color: var(--xpe-foreground, #111827);
 }
 .ebt-btn:disabled {
     opacity: 0.35;
     cursor: not-allowed;
 }
 .ebt-active {
-    background: #eef2ff;
-    color: #4f46e5;
+    background: var(--xpe-primary-muted, #eef2ff);
+    color: var(--xpe-primary, #4f46e5);
 }
 </style>
diff --git a/packages/vue/src/components/toolbar/EditorToolbarColorPanel.vue b/packages/vue/src/components/toolbar/EditorToolbarColorPanel.vue
index ddf32f8..26a1cbb 100644
--- a/packages/vue/src/components/toolbar/EditorToolbarColorPanel.vue
+++ b/packages/vue/src/components/toolbar/EditorToolbarColorPanel.vue
@@ -145,13 +145,13 @@ function isPresetActive(color: string, active: string | null): boolean {
                     A
                     <Check
                         v-if="isPresetActive(color, activeTextColor)"
-                        class="absolute -top-1 -end-1 size-3 rounded-full bg-indigo-500 p-0.5 text-white"
+                        class="absolute -top-1 -end-1 size-3 rounded-full bg-[var(--xpe-primary-muted)]0 p-0.5 text-white"
                     />
                 </button>
             </div>
 
-            <div class="border-t border-gray-100 pt-3">
-                <p class="mb-2 text-[10px] font-semibold tracking-wider text-gray-400 uppercase">
+            <div class="border-t border-[var(--xpe-border)] pt-3">
+                <p class="mb-2 text-[10px] font-semibold tracking-wider text-[var(--xpe-muted-foreground)] uppercase">
                     Custom
                 </p>
                 <div @focusin="onPickerFocus">
@@ -170,7 +170,7 @@ function isPresetActive(color: string, active: string | null): boolean {
                 type="button"
                 variant="ghost"
                 size="sm"
-                class="h-7 w-full text-xs text-gray-500"
+                class="h-7 w-full text-xs text-[var(--xpe-muted-foreground)]"
                 @click="resetCurrent"
             >
                 Reset text color
@@ -196,13 +196,13 @@ function isPresetActive(color: string, active: string | null): boolean {
                 >
                     <Check
                         v-if="isPresetActive(color, activeHighlight)"
-                        class="absolute -top-1 -end-1 size-3 rounded-full bg-indigo-500 p-0.5 text-white"
+                        class="absolute -top-1 -end-1 size-3 rounded-full bg-[var(--xpe-primary-muted)]0 p-0.5 text-white"
                     />
                 </button>
             </div>
 
-            <div class="border-t border-gray-100 pt-3">
-                <p class="mb-2 text-[10px] font-semibold tracking-wider text-gray-400 uppercase">
+            <div class="border-t border-[var(--xpe-border)] pt-3">
+                <p class="mb-2 text-[10px] font-semibold tracking-wider text-[var(--xpe-muted-foreground)] uppercase">
                     Custom
                 </p>
                 <div @focusin="onPickerFocus">
@@ -221,7 +221,7 @@ function isPresetActive(color: string, active: string | null): boolean {
                 type="button"
                 variant="ghost"
                 size="sm"
-                class="h-7 w-full text-xs text-gray-500"
+                class="h-7 w-full text-xs text-[var(--xpe-muted-foreground)]"
                 @click="resetCurrent"
             >
                 <Highlighter class="me-1.5 size-3" />
diff --git a/packages/vue/src/components/toolbar/EditorToolbarPopover.vue b/packages/vue/src/components/toolbar/EditorToolbarPopover.vue
index 1d43db9..07fa53d 100644
--- a/packages/vue/src/components/toolbar/EditorToolbarPopover.vue
+++ b/packages/vue/src/components/toolbar/EditorToolbarPopover.vue
@@ -33,12 +33,12 @@ const emit = defineEmits<{
             :align="align"
             :side="side"
             :side-offset="6"
-            :class="cn('w-auto rounded-xl border-gray-100 p-2 shadow-xl', contentClass)"
+            :class="cn('w-auto rounded-xl border-[var(--xpe-border)] p-2 shadow-xl', contentClass)"
             @mousedown.stop
         >
             <p
                 v-if="title"
-                class="mb-2 px-1 text-[11px] font-semibold tracking-wide text-gray-500 uppercase"
+                class="mb-2 px-1 text-[11px] font-semibold tracking-wide text-[var(--xpe-muted-foreground)] uppercase"
             >
                 {{ title }}
             </p>
diff --git a/packages/vue/src/components/toolbar/EditorToolbarSeparator.vue b/packages/vue/src/components/toolbar/EditorToolbarSeparator.vue
index 942bfa2..24642b1 100644
--- a/packages/vue/src/components/toolbar/EditorToolbarSeparator.vue
+++ b/packages/vue/src/components/toolbar/EditorToolbarSeparator.vue
@@ -1,5 +1,5 @@
 <template>
-    <div class="xpe-toolbar-separator mx-0.5 h-5 w-px bg-gray-100" />
+    <div class="xpe-toolbar-separator mx-0.5 h-5 w-px bg-[var(--xpe-muted)]" />
 </template>
 
 <style scoped>
diff --git a/packages/vue/src/ui/Button.vue b/packages/vue/src/ui/Button.vue
index 669052b..e2e74c3 100644
--- a/packages/vue/src/ui/Button.vue
+++ b/packages/vue/src/ui/Button.vue
@@ -61,25 +61,25 @@ withDefaults(
   padding: 0;
 }
 .xpe-btn--default {
-  background: #4f46e5;
-  color: #fff;
+  background: var(--xpe-primary, #4f46e5);
+  color: var(--xpe-primary-foreground, #fff);
 }
 .xpe-btn--default:hover:not(:disabled) {
-  background: #4338ca;
+  background: var(--xpe-primary, #4338ca);
 }
 .xpe-btn--outline {
-  background: #fff;
-  border-color: #e5e7eb;
-  color: #374151;
+  background: var(--xpe-surface, #fff);
+  border-color: var(--xpe-border, #e5e7eb);
+  color: var(--xpe-foreground, #374151);
 }
 .xpe-btn--outline:hover:not(:disabled) {
-  background: #f9fafb;
+  background: var(--xpe-surface-hover, #f9fafb);
 }
 .xpe-btn--ghost {
   background: transparent;
-  color: #374151;
+  color: var(--xpe-foreground, #374151);
 }
 .xpe-btn--ghost:hover:not(:disabled) {
-  background: #f3f4f6;
+  background: var(--xpe-muted, #f3f4f6);
 }
 </style>
diff --git a/packages/vue/src/ui/ColorPickerPanel.vue b/packages/vue/src/ui/ColorPickerPanel.vue
index 1aa9f65..c18ba2b 100644
--- a/packages/vue/src/ui/ColorPickerPanel.vue
+++ b/packages/vue/src/ui/ColorPickerPanel.vue
@@ -58,7 +58,7 @@ function onNativeColorInput(event: Event): void {
   width: 32px;
   height: 32px;
   padding: 0;
-  border: 1px solid #e5e7eb;
+  border: 1px solid var(--xpe-border, #e5e7eb);
   border-radius: 8px;
   cursor: pointer;
   background: none;
@@ -66,7 +66,7 @@ function onNativeColorInput(event: Event): void {
 .xpe-color-hex {
   flex: 1;
   height: 32px;
-  border: 1px solid #e5e7eb;
+  border: 1px solid var(--xpe-border, #e5e7eb);
   border-radius: 8px;
   padding: 0 8px;
   font-size: 12px;
@@ -74,6 +74,6 @@ function onNativeColorInput(event: Event): void {
   outline: none;
 }
 .xpe-color-hex:focus {
-  border-color: #6366f1;
+  border-color: var(--xpe-ring, #6366f1);
 }
 </style>
diff --git a/packages/vue/src/ui/DropdownMenuItem.vue b/packages/vue/src/ui/DropdownMenuItem.vue
index e9f5d14..3314e16 100644
--- a/packages/vue/src/ui/DropdownMenuItem.vue
+++ b/packages/vue/src/ui/DropdownMenuItem.vue
@@ -22,11 +22,11 @@ const ctx = inject(popoverContextKey)
   background: transparent;
   border-radius: 6px;
   font-size: 13px;
-  color: #374151;
+  color: var(--xpe-foreground, #374151);
   cursor: pointer;
   text-align: start;
 }
 .xpe-dropdown-item:hover {
-  background: #f9fafb;
+  background: var(--xpe-surface-hover, #f9fafb);
 }
 </style>
diff --git a/packages/vue/src/ui/IconEmojiPicker.vue b/packages/vue/src/ui/IconEmojiPicker.vue
index 4170fce..6690fa1 100644
--- a/packages/vue/src/ui/IconEmojiPicker.vue
+++ b/packages/vue/src/ui/IconEmojiPicker.vue
@@ -118,22 +118,22 @@ defineExpose({
   cursor: pointer;
 }
 .xpe-icon-cell:hover {
-  background: #f3f4f6;
+  background: var(--xpe-muted, #f3f4f6);
 }
 .xpe-icon-cell--active {
-  background: #eef2ff;
+  background: var(--xpe-primary-muted, #eef2ff);
 }
 .xpe-icon-custom {
   display: flex;
   gap: 6px;
   margin-top: 8px;
   padding-top: 8px;
-  border-top: 1px solid #f3f4f6;
+  border-top: 1px solid var(--xpe-muted, #f3f4f6);
 }
 .xpe-icon-custom-input {
   flex: 1;
   height: 28px;
-  border: 1px solid #e5e7eb;
+  border: 1px solid var(--xpe-border, #e5e7eb);
   border-radius: 6px;
   padding: 0 8px;
   font-size: 12px;
@@ -144,8 +144,8 @@ defineExpose({
   padding: 0 10px;
   border-radius: 6px;
   border: none;
-  background: #4f46e5;
-  color: #fff;
+  background: var(--xpe-primary, #4f46e5);
+  color: var(--xpe-primary-foreground, #fff);
   font-size: 12px;
   cursor: pointer;
 }
diff --git a/packages/vue/src/ui/Input.vue b/packages/vue/src/ui/Input.vue
index e1aaa73..6dbc54a 100644
--- a/packages/vue/src/ui/Input.vue
+++ b/packages/vue/src/ui/Input.vue
@@ -14,19 +14,19 @@ const model = defineModel<string>({ default: '' })
 .xpe-input {
   width: 100%;
   border-radius: 8px;
-  border: 1px solid #e5e7eb;
+  border: 1px solid var(--xpe-border, #e5e7eb);
   padding: 0 10px;
   font-size: 13px;
-  color: #111827;
-  background: #fff;
+  color: var(--xpe-foreground, #111827);
+  background: var(--xpe-surface, #fff);
   outline: none;
   transition: border-color 0.12s, box-shadow 0.12s;
 }
 .xpe-input:focus {
-  border-color: #6366f1;
+  border-color: var(--xpe-ring, #6366f1);
   box-shadow: 0 0 0 3px rgb(99 102 241 / 0.15);
 }
 .xpe-input::placeholder {
-  color: #9ca3af;
+  color: var(--xpe-muted-foreground, #9ca3af);
 }
 </style>
diff --git a/packages/vue/src/ui/PopoverContent.vue b/packages/vue/src/ui/PopoverContent.vue
index 49ed6ab..471f571 100644
--- a/packages/vue/src/ui/PopoverContent.vue
+++ b/packages/vue/src/ui/PopoverContent.vue
@@ -116,8 +116,8 @@ onBeforeUnmount(() => {
 .xpe-popover-content {
   z-index: 80;
   border-radius: 12px;
-  border: 1px solid #f3f4f6;
-  background: #fff;
+  border: 1px solid var(--xpe-muted, #f3f4f6);
+  background: var(--xpe-surface, #fff);
   box-shadow:
     0 10px 15px -3px rgb(0 0 0 / 0.1),
     0 4px 6px -4px rgb(0 0 0 / 0.1);
diff --git a/packages/vue/src/ui/TabsList.vue b/packages/vue/src/ui/TabsList.vue
index 4afa2f6..717f7a7 100644
--- a/packages/vue/src/ui/TabsList.vue
+++ b/packages/vue/src/ui/TabsList.vue
@@ -8,7 +8,7 @@
 .xpe-tabs-list {
   display: grid;
   gap: 4px;
-  background: #f3f4f6;
+  background: var(--xpe-muted, #f3f4f6);
   border-radius: 8px;
   padding: 3px;
 }
diff --git a/packages/vue/src/ui/TabsTrigger.vue b/packages/vue/src/ui/TabsTrigger.vue
index 7452b31..fc8621f 100644
--- a/packages/vue/src/ui/TabsTrigger.vue
+++ b/packages/vue/src/ui/TabsTrigger.vue
@@ -31,16 +31,16 @@ const isActive = computed(() => ctx.active.value === props.value)
   padding: 5px 8px;
   font-size: 12px;
   font-weight: 500;
-  color: #6b7280;
+  color: var(--xpe-muted-foreground, #6b7280);
   cursor: pointer;
   transition: background 0.12s, color 0.12s;
 }
 .xpe-tabs-trigger:hover {
-  color: #111827;
+  color: var(--xpe-foreground, #111827);
 }
 .xpe-tabs-trigger--active {
-  background: #fff;
-  color: #111827;
+  background: var(--xpe-surface, #fff);
+  color: var(--xpe-foreground, #111827);
   box-shadow: 0 1px 2px rgb(0 0 0 / 0.06);
 }
 </style>
diff --git a/site/src/App.css b/site/src/App.css
index 70a8e17..73fbdd7 100644
--- a/site/src/App.css
+++ b/site/src/App.css
@@ -1,16 +1,48 @@
+/*
+ * Bento theme — monochrome, soft-neumorphic, no accent color.
+ * Light and dark palettes flip via [data-theme='dark'] on <html>;
+ * the same toggle adds `xpe-dark` so the live editor follows along.
+ */
 :root {
-  --ink: #0f172a;
-  --muted: #64748b;
-  --line: #e5e7eb;
-  --surface: #ffffff;
-  --canvas: #fafafa;
-  --accent: #4f46e5;
-  --accent-2: #7c3aed;
-  --accent-soft: #eef2ff;
-  --radius: 16px;
+  --ink: #262626;
+  --muted: #8b8b8b;
+  --line: rgba(0, 0, 0, 0.08);
+  --line-strong: rgba(0, 0, 0, 0.14);
+  --surface: rgba(255, 255, 255, 0.78);
+  --surface-solid: #f7f7f7;
+  --chip: #ffffff;
+  --canvas: #ededed;
+  --canvas-gradient: linear-gradient(165deg, #f3f3f3 0%, #ebebeb 55%, #e4e4e4 100%);
+  --shadow-soft:
+    0 24px 48px -24px rgba(0, 0, 0, 0.28),
+    0 2px 6px rgba(0, 0, 0, 0.04);
+  --shadow-chip:
+    0 2px 6px rgba(0, 0, 0, 0.1),
+    0 0 0 1px rgba(0, 0, 0, 0.05);
+  --radius: 18px;
+  --radius-chip: 12px;
   color-scheme: light;
 }
 
+:root[data-theme='dark'] {
+  --ink: #ececec;
+  --muted: #9a9a9a;
+  --line: rgba(255, 255, 255, 0.09);
+  --line-strong: rgba(255, 255, 255, 0.16);
+  --surface: rgba(58, 58, 58, 0.82);
+  --surface-solid: #3a3a3a;
+  --chip: #4a4a4a;
+  --canvas: #2d2d2d;
+  --canvas-gradient: linear-gradient(165deg, #323232 0%, #2c2c2c 55%, #272727 100%);
+  --shadow-soft:
+    0 24px 48px -24px rgba(0, 0, 0, 0.6),
+    0 2px 6px rgba(0, 0, 0, 0.3);
+  --shadow-chip:
+    0 2px 6px rgba(0, 0, 0, 0.35),
+    0 0 0 1px rgba(255, 255, 255, 0.07);
+  color-scheme: dark;
+}
+
 * {
   box-sizing: border-box;
 }
@@ -23,6 +55,8 @@ body {
 
 body {
   background: var(--canvas);
+  background-image: var(--canvas-gradient);
+  background-attachment: fixed;
   color: var(--ink);
   font-family:
     'Inter',
@@ -31,6 +65,27 @@ body {
     'Segoe UI',
     sans-serif;
   -webkit-font-smoothing: antialiased;
+  transition: color 0.4s ease;
+}
+
+/* Diagonal sweep between themes (View Transitions API) */
+::view-transition-old(root),
+::view-transition-new(root) {
+  animation: none;
+  mix-blend-mode: normal;
+}
+
+::view-transition-new(root) {
+  animation: xpe-sweep 0.55s ease-in-out both;
+}
+
+@keyframes xpe-sweep {
+  from {
+    clip-path: polygon(120% -20%, 140% -20%, 20% 120%, 0% 120%);
+  }
+  to {
+    clip-path: polygon(-40% -20%, 140% -20%, 140% 120%, -60% 120%);
+  }
 }
 
 .site {
@@ -64,10 +119,10 @@ pre,
   align-items: center;
   justify-content: space-between;
   padding: 16px 24px;
-  backdrop-filter: blur(10px);
-  background: rgba(250, 250, 250, 0.75);
+  backdrop-filter: blur(12px);
+  background: color-mix(in srgb, var(--canvas) 72%, transparent);
   border-bottom: 1px solid transparent;
-  transition: border-color 0.2s ease;
+  transition: border-color 0.2s ease, background-color 0.4s ease;
 }
 
 .nav.scrolled {
@@ -91,11 +146,12 @@ pre,
   justify-content: center;
   width: 26px;
   height: 26px;
-  border-radius: 8px;
-  background: linear-gradient(135deg, var(--accent), var(--accent-2));
-  color: #fff;
+  border-radius: 9px;
+  background: var(--ink);
+  color: var(--canvas);
   font-size: 13px;
   font-weight: 800;
+  transition: background-color 0.4s ease, color 0.4s ease;
 }
 
 .nav-links {
@@ -106,26 +162,50 @@ pre,
 
 .nav-link {
   padding: 8px 12px;
-  border-radius: 8px;
+  border-radius: 10px;
   font-size: 13px;
   font-weight: 500;
   color: var(--muted);
   text-decoration: none;
+  border: none;
+  background: transparent;
+  cursor: pointer;
   transition: background 0.15s, color 0.15s;
 }
 
 .nav-link:hover {
-  background: rgba(15, 23, 42, 0.05);
+  background: var(--line);
   color: var(--ink);
 }
 
 .nav-link.cta {
   background: var(--ink);
-  color: #fff;
+  color: var(--canvas);
 }
 
 .nav-link.cta:hover {
-  background: #1e293b;
+  opacity: 0.88;
+}
+
+.theme-toggle {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 34px;
+  height: 34px;
+  margin-inline-start: 4px;
+  border: 1px solid var(--line);
+  border-radius: 999px;
+  background: var(--chip);
+  color: var(--muted);
+  cursor: pointer;
+  box-shadow: var(--shadow-chip);
+  transition: color 0.15s, transform 0.15s, background-color 0.4s ease;
+}
+
+.theme-toggle:hover {
+  color: var(--ink);
+  transform: translateY(-1px);
 }
 
 /* ─── Hero ─────────────────────────────────────────────────────────────── */
@@ -142,13 +222,19 @@ pre,
   inset: -20% -10% auto -10%;
   height: 480px;
   background:
-    radial-gradient(circle at 30% 30%, rgba(79, 70, 229, 0.16), transparent 55%),
-    radial-gradient(circle at 70% 20%, rgba(124, 58, 237, 0.14), transparent 55%);
-  filter: blur(10px);
+    radial-gradient(circle at 30% 30%, rgba(255, 255, 255, 0.55), transparent 55%),
+    radial-gradient(circle at 70% 20%, rgba(0, 0, 0, 0.05), transparent 55%);
+  filter: blur(12px);
   pointer-events: none;
   z-index: 0;
 }
 
+:root[data-theme='dark'] .hero-glow {
+  background:
+    radial-gradient(circle at 30% 30%, rgba(255, 255, 255, 0.06), transparent 55%),
+    radial-gradient(circle at 70% 20%, rgba(0, 0, 0, 0.35), transparent 55%);
+}
+
 .hero-inner {
   position: relative;
   z-index: 1;
@@ -172,10 +258,12 @@ pre,
   padding: 6px 12px;
   border-radius: 999px;
   border: 1px solid var(--line);
-  background: var(--surface);
+  background: var(--chip);
   font-size: 12px;
   font-weight: 600;
   color: var(--muted);
+  box-shadow: var(--shadow-chip);
+  transition: background-color 0.4s ease;
 }
 
 .pill img {
@@ -192,7 +280,7 @@ pre,
 }
 
 .hero h1 .grad {
-  background: linear-gradient(100deg, var(--accent), var(--accent-2));
+  background: linear-gradient(105deg, var(--ink) 30%, var(--muted) 90%);
   -webkit-background-clip: text;
   background-clip: text;
   color: transparent;
@@ -219,13 +307,13 @@ pre,
   align-items: center;
   gap: 8px;
   padding: 11px 20px;
-  border-radius: 10px;
+  border-radius: 12px;
   font-size: 14px;
   font-weight: 600;
   text-decoration: none;
   border: 1px solid transparent;
   cursor: pointer;
-  transition: transform 0.12s ease, box-shadow 0.12s ease, background 0.12s ease;
+  transition: transform 0.12s ease, box-shadow 0.12s ease, background 0.12s ease, opacity 0.12s;
 }
 
 .btn:active {
@@ -234,23 +322,23 @@ pre,
 
 .btn-primary {
   background: var(--ink);
-  color: #fff;
-  box-shadow: 0 8px 20px -8px rgba(15, 23, 42, 0.5);
+  color: var(--canvas);
+  box-shadow: 0 10px 24px -10px rgba(0, 0, 0, 0.5);
 }
 
 .btn-primary:hover {
-  background: #1e293b;
+  opacity: 0.9;
 }
 
 .btn-outline {
-  background: var(--surface);
+  background: var(--chip);
   border-color: var(--line);
   color: var(--ink);
+  box-shadow: var(--shadow-chip);
 }
 
 .btn-outline:hover {
-  border-color: #cbd5e1;
-  background: #f8fafc;
+  border-color: var(--line-strong);
 }
 
 /* ─── Section shell ────────────────────────────────────────────────────── */
@@ -271,7 +359,7 @@ section {
   font-weight: 700;
   letter-spacing: 0.08em;
   text-transform: uppercase;
-  color: var(--accent);
+  color: var(--muted);
   margin-bottom: 10px;
 }
 
@@ -291,10 +379,12 @@ section {
 
 .demo-frame {
   border: 1px solid var(--line);
-  border-radius: 20px;
+  border-radius: var(--radius);
   background: var(--surface);
-  box-shadow: 0 30px 60px -30px rgba(15, 23, 42, 0.25);
+  backdrop-filter: blur(14px);
+  box-shadow: var(--shadow-soft);
   overflow: hidden;
+  transition: background-color 0.4s ease, border-color 0.4s ease;
 }
 
 .demo-toolbar {
@@ -304,7 +394,8 @@ section {
   gap: 12px;
   padding: 12px 18px;
   border-bottom: 1px solid var(--line);
-  background: #fcfcfd;
+  background: color-mix(in srgb, var(--surface-solid) 65%, transparent);
+  transition: background-color 0.4s ease, border-color 0.4s ease;
 }
 
 .demo-toolbar-dots {
@@ -316,14 +407,14 @@ section {
   width: 9px;
   height: 9px;
   border-radius: 50%;
-  background: #e2e8f0;
+  background: var(--line-strong);
 }
 
 .mode-switch {
   display: inline-flex;
   padding: 3px;
-  border-radius: 9px;
-  background: #f1f5f9;
+  border-radius: 11px;
+  background: var(--line);
   gap: 2px;
 }
 
@@ -334,15 +425,15 @@ section {
   font-size: 12px;
   font-weight: 600;
   color: var(--muted);
-  border-radius: 7px;
+  border-radius: 9px;
   cursor: pointer;
   transition: background 0.15s, color 0.15s;
 }
 
 .mode-switch button.active {
-  background: #fff;
+  background: var(--chip);
   color: var(--ink);
-  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.08);
+  box-shadow: var(--shadow-chip);
 }
 
 .demo-body {
@@ -353,6 +444,7 @@ section {
 
 .demo-body :where(.block-editor) {
   padding: 8px 28px 60px;
+  background: transparent;
 }
 
 .demo-hint {
@@ -363,22 +455,46 @@ section {
 }
 
 .demo-hint code {
-  background: var(--accent-soft);
-  color: var(--accent);
+  background: var(--line);
+  color: var(--ink);
   padding: 2px 6px;
-  border-radius: 5px;
+  border-radius: 6px;
   font-size: 12px;
 }
 
+/*
+ * Bento editor theme — the live proof that the editor is themable with a
+ * handful of CSS variables (see docs/theming.md). Toggled from the demo
+ * toolbar; "Default" removes this class to show the stock look.
+ */
+.demo-body.editor-theme-bento {
+  --xpe-background: transparent;
+  --xpe-foreground: var(--ink);
+  --xpe-muted-foreground: var(--muted);
+  --xpe-muted: color-mix(in srgb, var(--ink) 5%, transparent);
+  --xpe-border: var(--line-strong);
+  --xpe-primary: var(--ink);
+  --xpe-primary-foreground: var(--canvas);
+  --xpe-primary-muted: color-mix(in srgb, var(--ink) 8%, transparent);
+  --xpe-surface: var(--surface-solid);
+  --xpe-surface-hover: color-mix(in srgb, var(--ink) 6%, transparent);
+  --xpe-ring: var(--muted);
+  --xpe-radius: 14px;
+  --xpe-shadow: var(--shadow-soft);
+}
+
 /* ─── Install tabs ─────────────────────────────────────────────────────── */
 
 .install-card {
   border: 1px solid var(--line);
   border-radius: var(--radius);
   background: var(--surface);
+  backdrop-filter: blur(14px);
+  box-shadow: var(--shadow-soft);
   overflow: hidden;
   max-width: 620px;
   margin: 0 auto;
+  transition: background-color 0.4s ease;
 }
 
 .install-tabs {
@@ -401,13 +517,13 @@ section {
 
 .install-tabs button.active {
   color: var(--ink);
-  border-bottom-color: var(--accent);
+  border-bottom-color: var(--ink);
 }
 
 .code-block {
   position: relative;
-  background: #0f172a;
-  color: #e2e8f0;
+  background: #1f1f1f;
+  color: #dcdcdc;
 }
 
 .code-block pre {
@@ -424,11 +540,11 @@ section {
   right: 10px;
   border: 1px solid rgba(255, 255, 255, 0.15);
   background: rgba(255, 255, 255, 0.06);
-  color: #cbd5e1;
+  color: #c5c5c5;
   font-size: 11px;
   font-weight: 600;
   padding: 5px 9px;
-  border-radius: 6px;
+  border-radius: 7px;
   cursor: pointer;
   transition: background 0.15s;
 }
@@ -438,19 +554,20 @@ section {
 }
 
 .code-comment {
-  color: #64748b;
+  color: #7d7d7d;
 }
 .code-kw {
-  color: #c4b5fd;
+  color: #d0d0d0;
+  font-weight: 700;
 }
 .code-str {
-  color: #86efac;
+  color: #b5c9b7;
 }
 .code-tag {
-  color: #93c5fd;
+  color: #c9c9c9;
 }
 .code-fn {
-  color: #7dd3fc;
+  color: #bdbdbd;
 }
 
 /* ─── Features ─────────────────────────────────────────────────────────── */
@@ -463,16 +580,18 @@ section {
 
 .feature-card {
   border: 1px solid var(--line);
-  border-radius: 14px;
+  border-radius: var(--radius-chip);
   background: var(--surface);
+  backdrop-filter: blur(10px);
   padding: 20px;
-  transition: transform 0.15s ease, box-shadow 0.15s ease, border-color 0.15s ease;
+  transition: transform 0.15s ease, box-shadow 0.15s ease, border-color 0.15s ease,
+    background-color 0.4s ease;
 }
 
 .feature-card:hover {
   transform: translateY(-2px);
-  box-shadow: 0 16px 30px -20px rgba(15, 23, 42, 0.3);
-  border-color: #dbe1ea;
+  box-shadow: var(--shadow-soft);
+  border-color: var(--line-strong);
 }
 
 .feature-icon {
@@ -481,9 +600,9 @@ section {
   justify-content: center;
   width: 36px;
   height: 36px;
-  border-radius: 10px;
-  background: var(--accent-soft);
-  color: var(--accent);
+  border-radius: 11px;
+  background: var(--line);
+  color: var(--ink);
   margin-bottom: 12px;
 }
 
@@ -511,16 +630,17 @@ section {
 .package-card {
   display: block;
   border: 1px solid var(--line);
-  border-radius: 14px;
+  border-radius: var(--radius-chip);
   background: var(--surface);
+  backdrop-filter: blur(10px);
   padding: 18px 20px;
   text-decoration: none;
   color: var(--ink);
-  transition: border-color 0.15s, transform 0.15s;
+  transition: border-color 0.15s, transform 0.15s, background-color 0.4s ease;
 }
 
 .package-card:hover {
-  border-color: var(--accent);
+  border-color: var(--line-strong);
   transform: translateY(-2px);
 }
 
@@ -528,7 +648,7 @@ section {
   font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
   font-size: 13.5px;
   font-weight: 600;
-  color: var(--accent);
+  color: var(--ink);
   display: block;
   margin-bottom: 6px;
 }
diff --git a/site/src/components/LiveDemo.tsx b/site/src/components/LiveDemo.tsx
index 5124e18..4282009 100644
--- a/site/src/components/LiveDemo.tsx
+++ b/site/src/components/LiveDemo.tsx
@@ -29,8 +29,11 @@ const MODES: { value: ToolbarMode; label: string }[] = [
   { value: 'both', label: 'Both' },
 ]
 
+type EditorTheme = 'bento' | 'default'
+
 export function LiveDemo() {
   const [mode, setMode] = useState<ToolbarMode>('floating')
+  const [editorTheme, setEditorTheme] = useState<EditorTheme>('bento')
   const [resetKey, setResetKey] = useState(0)
   const initialBlocks = useMemo(() => seed(), [resetKey])
 
@@ -62,6 +65,18 @@ export function LiveDemo() {
                 </button>
               ))}
             </div>
+            <div className="mode-switch" role="tablist" aria-label="Editor theme">
+              {(['bento', 'default'] as const).map((t) => (
+                <button
+                  key={t}
+                  type="button"
+                  className={editorTheme === t ? 'active' : ''}
+                  onClick={() => setEditorTheme(t)}
+                >
+                  {t === 'bento' ? 'Bento theme' : 'Default'}
+                </button>
+              ))}
+            </div>
             <button
               type="button"
               className="nav-link"
@@ -71,12 +86,14 @@ export function LiveDemo() {
               Reset
             </button>
           </div>
-          <div className="demo-body">
+          <div className={`demo-body${editorTheme === 'bento' ? ' editor-theme-bento' : ''}`}>
             <ProEditor key={`${mode}-${resetKey}`} defaultValue={initialBlocks} toolbar={mode} editorDir="ltr" />
           </div>
         </div>
         <p className="demo-hint">
-          Press <code>/</code> for the block menu, or select text for the floating toolbar.
+          Press <code>/</code> for the block menu, or select text for the floating toolbar. The
+          “Bento theme” switch above restyles the editor with just a few <code>--xpe-*</code> CSS
+          variables — no rebuild, no fork.
         </p>
       </div>
     </section>
diff --git a/site/src/components/Nav.tsx b/site/src/components/Nav.tsx
index 546419f..a8fb48d 100644
--- a/site/src/components/Nav.tsx
+++ b/site/src/components/Nav.tsx
@@ -1,9 +1,32 @@
 import { useEffect, useState } from 'react'
+import { applyTheme, initialTheme, transitionTheme, type SiteTheme } from '../theme'
 
 const REPO_URL = 'https://github.com/xofdev/xproeditor'
 
+function SunIcon() {
+  return (
+    <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round">
+      <circle cx="12" cy="12" r="4" />
+      <path d="M12 2v2m0 16v2M4.93 4.93l1.41 1.41m11.32 11.32 1.41 1.41M2 12h2m16 0h2M4.93 19.07l1.41-1.41M17.66 6.34l1.41-1.41" />
+    </svg>
+  )
+}
+
+function MoonIcon() {
+  return (
+    <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+      <path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z" />
+    </svg>
+  )
+}
+
 export function Nav() {
   const [scrolled, setScrolled] = useState(false)
+  const [theme, setTheme] = useState<SiteTheme>(() => initialTheme())
+
+  useEffect(() => {
+    applyTheme(theme)
+  }, [theme])
 
   useEffect(() => {
     function onScroll() {
@@ -13,6 +36,12 @@ export function Nav() {
     return () => window.removeEventListener('scroll', onScroll)
   }, [])
 
+  function toggleTheme() {
+    const next = theme === 'light' ? 'dark' : 'light'
+    setTheme(next)
+    transitionTheme(next)
+  }
+
   return (
     <header className={`nav${scrolled ? ' scrolled' : ''}`}>
       <a className="nav-brand" href="#top">
@@ -40,6 +69,15 @@ export function Nav() {
         <a className="nav-link cta" href={REPO_URL} target="_blank" rel="noreferrer">
           GitHub
         </a>
+        <button
+          type="button"
+          className="theme-toggle"
+          title={theme === 'light' ? 'Switch to dark theme' : 'Switch to light theme'}
+          aria-label="Toggle theme"
+          onClick={toggleTheme}
+        >
+          {theme === 'light' ? <MoonIcon /> : <SunIcon />}
+        </button>
       </nav>
     </header>
   )
diff --git a/site/src/theme.ts b/site/src/theme.ts
new file mode 100644
index 0000000..a3c584b
--- /dev/null
+++ b/site/src/theme.ts
@@ -0,0 +1,36 @@
+export type SiteTheme = 'light' | 'dark'
+
+const STORAGE_KEY = 'xpe-site-theme'
+
+export function initialTheme(): SiteTheme {
+  const stored = localStorage.getItem(STORAGE_KEY)
+
+  if (stored === 'light' || stored === 'dark') return stored
+
+  return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
+}
+
+export function applyTheme(theme: SiteTheme) {
+  const root = document.documentElement
+  root.dataset.theme = theme
+  // Drive the editor packages' built-in dark theme from the same toggle
+  root.classList.toggle('xpe-dark', theme === 'dark')
+  localStorage.setItem(STORAGE_KEY, theme)
+}
+
+/**
+ * Swap themes with the diagonal sweep from the reference design — a
+ * View Transitions clip-path wipe. Falls back to an instant swap.
+ */
+export function transitionTheme(next: SiteTheme) {
+  const doc = document as Document & {
+    startViewTransition?: (cb: () => void) => void
+  }
+
+  if (!doc.startViewTransition || window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
+    applyTheme(next)
+    return
+  }
+
+  doc.startViewTransition(() => applyTheme(next))
+}

From 12c180be492cb7aa8e80e4a4e7c15d5b706fe983 Mon Sep 17 00:00:00 2001
From: Mohammad Moradi <mohammad.moradi@outlook.com>
Date: Sat, 11 Jul 2026 16:42:38 +0300
Subject: [PATCH 5/7] Add button block, standalone emoji picker with ':'
 trigger, and fix slash menu/theming/checkmark bugs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- New `button` block type: editable label, link URL, open-in-new-tab,
  primary/outline/ghost style, alignment — settings popover in both
  adapters, read-only rendering in DocRenderer, core model + tests.
- Standalone emoji picker (search, 7 categories, recents), used by the
  callout icon button and by a new ':' inline trigger (Slack/Discord-style)
  that searches and inserts an emoji directly into text.
- Fix: slash-menu ArrowUp/ArrowDown/Enter never worked — the root keydown
  handler bailed out for any key typed inside the contenteditable block the
  menu lives in, which is the only place slash state exists. Same fix
  applied to the new ':' trigger.
- Fix: floating UI (slash menu, bubble toolbar, popovers, dropdowns) is
  portaled to document.body, silently escaping any theme class scoped to
  an ancestor of the editor. These now resync --xpe-* variables onto the
  portaled node so scoped custom themes apply everywhere.
- Fix: to-do checkbox checkmark and toggle chevron were sized via Tailwind
  classes that weren't reliably taking effect on raw SVGs — both now use
  explicit width/height so the checkmark is always visible.
- Fix: Vue's button-block label lost all styling because it reused
  ui/Button.vue's scoped .xpe-btn classes on a plain div — Vue scoped CSS
  only applies to elements a component itself renders. Replaced with
  locally-scoped styles.
- Slash menu now groups items into Basic/Lists/Media/Advanced sections,
  locks page scroll while open (Notion-style), and flips above the caret
  when there's no room below.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .changeset/button-block-fixes-and-polish.md   |  17 +
 packages/core/src/button.test.ts              |  41 ++
 packages/core/src/clipboard.ts                |  10 +
 packages/core/src/dom.ts                      |  79 ++++
 packages/core/src/ops.ts                      |  15 +-
 packages/core/src/types.ts                    |   8 +-
 packages/react/src/components/BlockEditor.tsx |  13 +
 packages/react/src/components/BlockItem.tsx   |  29 +-
 .../react/src/components/BubbleToolbar.tsx    |  15 +-
 packages/react/src/components/ButtonBlock.tsx | 134 +++++++
 packages/react/src/components/DocRenderer.tsx |  23 ++
 .../react/src/components/EmojiTriggerMenu.tsx |  70 ++++
 packages/react/src/components/SlashMenu.tsx   | 168 +++++---
 packages/react/src/hooks/useBlockEditor.ts    | 158 ++++++--
 packages/react/src/index.ts                   |   6 +
 packages/react/src/styles/components.css      |  38 +-
 packages/react/src/types.ts                   |   3 +
 packages/react/src/ui/EmojiPicker.tsx         | 175 ++++++++
 packages/react/src/ui/IconEmojiPicker.tsx     |  15 +-
 packages/react/src/ui/Popover.tsx             |   6 +
 packages/react/src/ui/emojiData.ts            | 372 ++++++++++++++++++
 packages/react/src/ui/index.ts                |   3 +
 packages/vue/src/components/BlockEditor.vue   | 178 +++++++--
 packages/vue/src/components/DocRenderer.vue   |  33 +-
 .../vue/src/components/EditorBlockItem.vue    |  31 +-
 .../src/components/EditorBubbleToolbar.vue    |  21 +-
 .../vue/src/components/EditorButtonBlock.vue  | 186 +++++++++
 .../src/components/EditorEmojiTriggerMenu.vue |  83 ++++
 .../vue/src/components/EditorSlashMenu.vue    | 122 ++++--
 packages/vue/src/ui/EmojiPicker.vue           | 192 +++++++++
 packages/vue/src/ui/IconEmojiPicker.vue       |  48 +--
 packages/vue/src/ui/PopoverContent.vue        |   6 +
 packages/vue/src/ui/emojiData.ts              | 372 ++++++++++++++++++
 packages/vue/src/ui/index.ts                  |   2 +
 34 files changed, 2444 insertions(+), 228 deletions(-)
 create mode 100644 .changeset/button-block-fixes-and-polish.md
 create mode 100644 packages/core/src/button.test.ts
 create mode 100644 packages/react/src/components/ButtonBlock.tsx
 create mode 100644 packages/react/src/components/EmojiTriggerMenu.tsx
 create mode 100644 packages/react/src/ui/EmojiPicker.tsx
 create mode 100644 packages/react/src/ui/emojiData.ts
 create mode 100644 packages/vue/src/components/EditorButtonBlock.vue
 create mode 100644 packages/vue/src/components/EditorEmojiTriggerMenu.vue
 create mode 100644 packages/vue/src/ui/EmojiPicker.vue
 create mode 100644 packages/vue/src/ui/emojiData.ts

diff --git a/.changeset/button-block-fixes-and-polish.md b/.changeset/button-block-fixes-and-polish.md
new file mode 100644
index 0000000..ad94174
--- /dev/null
+++ b/.changeset/button-block-fixes-and-polish.md
@@ -0,0 +1,17 @@
+---
+'@xproeditor/core': minor
+'@xproeditor/vue': minor
+'@xproeditor/react': minor
+---
+
+Add a new `button` block type (label, link URL, open-in-new-tab, primary/outline/ghost style, alignment) with a settings popover in both adapters and read-only rendering in `DocRenderer`.
+
+Add a standalone, categorized emoji picker (search, 7 categories, recents) usable both from the callout icon button and via a Slack/Discord-style `:` inline trigger that searches and inserts an emoji directly into text.
+
+Fix several real bugs surfaced while building the Bento showcase theme:
+- Slash-menu arrow-key/Enter navigation was dead on arrival — the root keydown handler bailed out for any key typed inside the contenteditable block the menu lives in, which is the only place slash state ever exists.
+- Floating UI (slash menu, bubble toolbar, popovers, dropdowns) is portaled to `document.body`, which silently escaped any theme class scoped to an ancestor of the editor — these now resync `--xpe-*` variables onto the portaled node so scoped custom themes apply everywhere, not just inline.
+- The to-do checkbox's checkmark and the toggle chevron were sized via Tailwind utility classes that weren't reliably taking effect on raw SVGs — both now use explicit width/height so the checkmark is always visible.
+- Vue's button-block label lost all styling because it reused `ui/Button.vue`'s scoped `.xpe-btn` class names on a plain `<div>` — Vue scoped CSS only applies to elements a component itself renders, so the classes were dead. Replaced with locally-scoped styles.
+
+Slash menu now groups items into Basic/Lists/Media/Advanced sections, locks page scroll while open (Notion-style), and flips above the caret when there's no room below.
diff --git a/packages/core/src/button.test.ts b/packages/core/src/button.test.ts
new file mode 100644
index 0000000..bcd4008
--- /dev/null
+++ b/packages/core/src/button.test.ts
@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest'
+import { blocksToHtmlContent } from './clipboard'
+import { createBlock } from './ops'
+import { blockToPlainText, buildBlocksContent } from './serialize'
+
+describe('button block model', () => {
+  it('createBlock defaults url, style, and alignment', () => {
+    const block = createBlock('button')
+    expect(block.props.url).toBe('')
+    expect(block.props.buttonStyle).toBe('primary')
+    expect(block.props.align).toBe('left')
+  })
+
+  it('plain text uses the label content', () => {
+    const block = createBlock('button', { content: [{ text: 'Click me' }] })
+    expect(blockToPlainText(block)).toBe('Click me')
+  })
+
+  it('exports a linked button to HTML', () => {
+    const block = createBlock('button', {
+      content: [{ text: 'Visit site' }],
+      props: { url: 'https://example.com', openInNewTab: true },
+    })
+    const html = blocksToHtmlContent([block])
+    expect(html).toContain('<a href="https://example.com" target="_blank" rel="noopener noreferrer">Visit site</a>')
+  })
+
+  it('exports a button with no url as plain text', () => {
+    const block = createBlock('button', { content: [{ text: 'No link yet' }] })
+    const html = blocksToHtmlContent([block])
+    expect(html).not.toContain('<a ')
+    expect(html).toContain('No link yet')
+  })
+
+  it('round-trips through buildBlocksContent', () => {
+    const blocks = [createBlock('button', { content: [{ text: 'Go' }], props: { url: '/go' } })]
+    const content = buildBlocksContent(blocks)
+    expect(content.blocks[0].type).toBe('button')
+    expect(content.text).toBe('Go')
+  })
+})
diff --git a/packages/core/src/clipboard.ts b/packages/core/src/clipboard.ts
index d47c326..86535e2 100644
--- a/packages/core/src/clipboard.ts
+++ b/packages/core/src/clipboard.ts
@@ -110,6 +110,16 @@ return ''
 
       return `<a href="${escapeHtml(url)}" download>${name}</a>`
     }
+    case 'button': {
+      const url = block.props.url ?? ''
+      const label = spansToHtml(block.content) || 'Button'
+      const target = block.props.openInNewTab ? ' target="_blank" rel="noopener noreferrer"' : ''
+      const alignStyle = block.props.align ? `text-align:${block.props.align};` : ''
+
+      return url
+        ? `<p style="${alignStyle}"><a href="${escapeHtml(url)}"${target}>${label}</a></p>`
+        : `<p style="${alignStyle}">${label}</p>`
+    }
     case 'table': {
       const table = normalizeTableData(block.props.table)
 
diff --git a/packages/core/src/dom.ts b/packages/core/src/dom.ts
index 8637b7b..49309cf 100644
--- a/packages/core/src/dom.ts
+++ b/packages/core/src/dom.ts
@@ -1,5 +1,84 @@
 /** Caret/selection helpers for per-block contenteditable elements. */
 
+// ─── Theme variable sync across portal boundaries ─────────────────────────────
+
+/** Every `--xpe-*` custom property the editor packages read for theming. */
+export const XPE_THEME_VARS = [
+  '--xpe-background',
+  '--xpe-foreground',
+  '--xpe-muted-foreground',
+  '--xpe-muted',
+  '--xpe-border',
+  '--xpe-primary',
+  '--xpe-primary-foreground',
+  '--xpe-primary-muted',
+  '--xpe-surface',
+  '--xpe-surface-hover',
+  '--xpe-ring',
+  '--xpe-danger',
+  '--xpe-radius',
+  '--xpe-shadow',
+  '--xpe-font-mono',
+] as const
+
+/**
+ * Copy resolved `--xpe-*` values from `source` onto `target` as inline
+ * custom properties. Needed because floating UI (slash menu, popovers,
+ * bubble toolbar) is portaled to `document.body` to escape clipping/overflow
+ * — which also escapes any scoped theme class applied to an ancestor of the
+ * editor, breaking CSS variable inheritance. Call this once the portaled
+ * element exists, using any element still inside the themed scope (e.g. the
+ * popover trigger, or the editor root) as `source`.
+ */
+export function syncThemeVars(source: Element, target: HTMLElement): void {
+  const computed = getComputedStyle(source)
+
+  for (const name of XPE_THEME_VARS) {
+    const value = computed.getPropertyValue(name).trim()
+
+    if (value) {
+      target.style.setProperty(name, value)
+    }
+  }
+}
+
+// ─── Page scroll lock (for floating menus like the slash command popover) ────
+
+let scrollLockCount = 0
+let savedBodyOverflow = ''
+
+/**
+ * Reference-counted page-scroll lock: while any caller holds a lock, the
+ * document can't scroll behind an open popover (Notion-style). Call the
+ * returned function to release — safe to call multiple times.
+ */
+export function lockPageScroll(): () => void {
+  if (typeof document === 'undefined') {
+return () => {}
+}
+
+  if (scrollLockCount === 0) {
+    savedBodyOverflow = document.body.style.overflow
+    document.body.style.overflow = 'hidden'
+  }
+
+  scrollLockCount++
+  let released = false
+
+  return () => {
+    if (released) {
+return
+}
+
+    released = true
+    scrollLockCount = Math.max(0, scrollLockCount - 1)
+
+    if (scrollLockCount === 0) {
+      document.body.style.overflow = savedBodyOverflow
+    }
+  }
+}
+
 /** Text offset of a (node, nodeOffset) position inside `el`. BR elements count as 1 char. */
 function positionToOffset(el: HTMLElement, node: Node, nodeOffset: number): number {
   const range = document.createRange()
diff --git a/packages/core/src/ops.ts b/packages/core/src/ops.ts
index 9c2f110..df4395c 100644
--- a/packages/core/src/ops.ts
+++ b/packages/core/src/ops.ts
@@ -33,7 +33,8 @@ export function createBlock(
       type === 'to_do' ||
       type === 'toggle' ||
       type === 'quote' ||
-      type === 'callout')
+      type === 'callout' ||
+      type === 'button')
   ) {
     props.dir = options.defaultDir
   }
@@ -66,6 +67,18 @@ props.provider = 'file'
     props.table = createDefaultTableData()
   }
 
+  if (type === 'button' && props.url === undefined) {
+props.url = ''
+}
+
+  if (type === 'button' && props.buttonStyle === undefined) {
+props.buttonStyle = 'primary'
+}
+
+  if (type === 'button' && props.align === undefined) {
+props.align = 'left'
+}
+
   return {
     id: partial.id ?? generateBlockId(),
     type,
diff --git a/packages/core/src/types.ts b/packages/core/src/types.ts
index f0f8a4d..1eee6cb 100644
--- a/packages/core/src/types.ts
+++ b/packages/core/src/types.ts
@@ -22,6 +22,7 @@ export type BlockType =
   | 'audio'
   | 'file'
   | 'table'
+  | 'button'
 
 export interface InlineMarks {
   bold?: boolean
@@ -96,7 +97,7 @@ export interface BlockProps {
   /** code */
   language?: string
   code?: string
-  /** image / video / audio / file */
+  /** image / video / audio / file / button */
   url?: string
   caption?: string
   /** audio / file: original file name */
@@ -114,6 +115,10 @@ export interface BlockProps {
   color?: string
   /** table */
   table?: TableData
+  /** button: visual style */
+  buttonStyle?: 'primary' | 'outline' | 'ghost'
+  /** button: open url in a new tab */
+  openInNewTab?: boolean
   /** text direction */
   dir?: 'auto' | 'ltr' | 'rtl'
   align?: 'left' | 'center' | 'right'
@@ -146,6 +151,7 @@ export const TEXT_BLOCK_TYPES: BlockType[] = [
   'toggle',
   'quote',
   'callout',
+  'button',
 ]
 
 /** Block types that participate in flat indent nesting. */
diff --git a/packages/react/src/components/BlockEditor.tsx b/packages/react/src/components/BlockEditor.tsx
index ac9c3d8..9fff6ff 100644
--- a/packages/react/src/components/BlockEditor.tsx
+++ b/packages/react/src/components/BlockEditor.tsx
@@ -3,6 +3,7 @@ import type { Block } from '@xproeditor/core'
 import { useBlockEditor, type UseBlockEditorOptions } from '../hooks/useBlockEditor'
 import { BlockItem } from './BlockItem'
 import { BubbleToolbar } from './BubbleToolbar'
+import { EmojiTriggerMenu } from './EmojiTriggerMenu'
 import { SlashMenu } from './SlashMenu'
 import type { FormatToolbarState } from '../types'
 
@@ -149,11 +150,22 @@ export const BlockEditor = forwardRef<BlockEditorHandle, BlockEditorProps>(funct
           query={ed.slashState.query}
           position={ed.slashState.position}
           dir={ed.editorDir ?? 'ltr'}
+          themeSource={ed.rootRef.current}
           onSelect={ed.onSlashSelect}
           onClose={ed.closeSlash}
         />
       )}
 
+      {ed.emojiTriggerState && !ed.readonly && (
+        <EmojiTriggerMenu
+          query={ed.emojiTriggerState.query}
+          position={ed.emojiTriggerState.position}
+          dir={ed.editorDir ?? 'ltr'}
+          themeSource={ed.rootRef.current}
+          onSelect={ed.onEmojiTriggerSelect}
+        />
+      )}
+
       {ed.showBubbleToolbar && ed.bubble && !ed.readonly && (
         <BubbleToolbar
           position={ed.bubble.position}
@@ -162,6 +174,7 @@ export const BlockEditor = forwardRef<BlockEditorHandle, BlockEditorProps>(funct
           currentColor={ed.bubble.currentColor}
           currentHighlight={ed.bubble.currentHighlight}
           blockType={ed.bubble.blockType}
+          themeSource={ed.rootRef.current}
           onMark={ed.onBubbleMark}
           onTurnInto={ed.onBubbleTurnInto}
         />
diff --git a/packages/react/src/components/BlockItem.tsx b/packages/react/src/components/BlockItem.tsx
index 5528bc5..4e2d1fa 100644
--- a/packages/react/src/components/BlockItem.tsx
+++ b/packages/react/src/components/BlockItem.tsx
@@ -11,6 +11,7 @@ import {
 } from '../ui'
 import { CodeBlock, type CodeBlockHandle } from './CodeBlock'
 import { AudioBlock } from './AudioBlock'
+import { ButtonBlock } from './ButtonBlock'
 import { FileBlock } from './FileBlock'
 import { ImageBlock } from './ImageBlock'
 import { SelectionHighlight } from './SelectionHighlight'
@@ -332,13 +333,15 @@ export const BlockItem = forwardRef<BlockItemHandle, BlockItemProps>(
                   )}
                   {block.type === 'to_do' && (
                     <button
-                      className={`w-[15px] h-[15px] mt-1 rounded-[4px] border flex items-center justify-center transition-colors ${block.props.checked ? 'bg-[var(--xpe-primary)] border-[var(--xpe-primary)]' : 'border-[var(--xpe-border)] hover:border-[var(--xpe-ring)] bg-[var(--xpe-surface)]'}`}
+                      className={`appearance-none w-[15px] h-[15px] mt-1 rounded-[4px] border flex items-center justify-center transition-colors ${block.props.checked ? 'bg-[var(--xpe-primary)] border-[var(--xpe-primary)]' : 'border-[var(--xpe-border)] hover:border-[var(--xpe-ring)] bg-[var(--xpe-surface)]'}`}
                       disabled={readonly}
                       onClick={() => onPatch({ checked: !block.props.checked })}
                     >
                       {block.props.checked && (
                         <svg
-                          className="w-2.5 h-2.5 text-white"
+                          width={10}
+                          height={10}
+                          className="shrink-0 text-[var(--xpe-primary-foreground)]"
                           fill="none"
                           stroke="currentColor"
                           strokeWidth={3}
@@ -356,7 +359,8 @@ export const BlockItem = forwardRef<BlockItemHandle, BlockItemProps>(
                       onClick={() => onPatch({ collapsed: !block.props.collapsed })}
                     >
                       <ChevronRight
-                        className={`h-3.5 w-3.5 transition-transform${!block.props.collapsed ? ' rotate-90' : ''}${isRtl ? ' ebi-chevron-rtl' : ''}`}
+                        size={14}
+                        className={`shrink-0 transition-transform${!block.props.collapsed ? ' rotate-90' : ''}${isRtl ? ' ebi-chevron-rtl' : ''}`}
                       />
                     </button>
                   )}
@@ -440,6 +444,25 @@ export const BlockItem = forwardRef<BlockItemHandle, BlockItemProps>(
               <div className="py-2.5 cursor-pointer" onClick={onSelect}>
                 <hr className={`border-[var(--xpe-border)] rounded${selected ? ' !border-[var(--xpe-ring)]' : ''}`} />
               </div>
+            ) : block.type === 'button' ? (
+              <ButtonBlock
+                ref={innerRef as React.Ref<TextBlockHandle>}
+                block={block}
+                readonly={readonly}
+                onInput={onInput}
+                onEnter={onEnter}
+                onBackspaceStart={onBackspaceStart}
+                onDeleteEnd={onDeleteEnd}
+                onArrowUp={onArrowUp}
+                onArrowDown={onArrowDown}
+                onTab={onTab}
+                onFormat={onFormat}
+                onPasted={onPasted}
+                onFocus={onFocus}
+                onSelectionPointerDown={onSelectionPointerDown}
+                onPatch={onPatch}
+                onSelect={onSelect}
+              />
             ) : (
               renderTextBlock()
             )}
diff --git a/packages/react/src/components/BubbleToolbar.tsx b/packages/react/src/components/BubbleToolbar.tsx
index b754df1..680ee7e 100644
--- a/packages/react/src/components/BubbleToolbar.tsx
+++ b/packages/react/src/components/BubbleToolbar.tsx
@@ -1,5 +1,6 @@
-import { useEffect, useState } from 'react'
+import { useEffect, useRef, useState } from 'react'
 import { createPortal } from 'react-dom'
+import { syncThemeVars } from '@xproeditor/core'
 import {
   Bold,
   Check,
@@ -31,6 +32,9 @@ export interface BubbleToolbarProps {
   currentColor?: string | null
   currentHighlight?: string | null
   blockType: BlockType
+  /** Element still inside the editor's themed DOM scope — used to resync
+   * `--xpe-*` variables onto this toolbar once it's portaled to `<body>`. */
+  themeSource?: HTMLElement | null
   onMark: (mark: MarkName, value: boolean | string | null) => void
   onTurnInto: (type: BlockType) => void
 }
@@ -56,15 +60,21 @@ export function BubbleToolbar({
   currentColor,
   currentHighlight,
   blockType,
+  themeSource,
   onMark,
   onTurnInto,
 }: BubbleToolbarProps) {
   const [panel, setPanel] = useState<Panel>('none')
   const [linkInput, setLinkInput] = useState('')
+  const toolbarRef = useRef<HTMLDivElement | null>(null)
 
   useEffect(() => {
     setPanel('none')
-  }, [position])
+
+    if (themeSource && toolbarRef.current) {
+      syncThemeVars(themeSource, toolbarRef.current)
+    }
+  }, [position, themeSource])
 
   function openLinkPanel() {
     setLinkInput(currentLink ?? '')
@@ -81,6 +91,7 @@ export function BubbleToolbar({
 
   return createPortal(
     <div
+      ref={toolbarRef}
       className="fixed z-[70] flex flex-col items-stretch"
       style={{ left: position.x, top: position.y, transform: 'translate(-50%, calc(-100% - 8px))' }}
       onMouseDown={(e) => e.preventDefault()}
diff --git a/packages/react/src/components/ButtonBlock.tsx b/packages/react/src/components/ButtonBlock.tsx
new file mode 100644
index 0000000..94217af
--- /dev/null
+++ b/packages/react/src/components/ButtonBlock.tsx
@@ -0,0 +1,134 @@
+import { forwardRef, useState } from 'react'
+import { Link2, SquareArrowOutUpRight } from 'lucide-react'
+import type { Block, InlineSpan, MarkName } from '@xproeditor/core'
+import { Button, Input, Popover, PopoverContent, PopoverTrigger } from '../ui'
+import { TextBlock, type TextBlockHandle } from './TextBlock'
+
+export interface ButtonBlockProps {
+  block: Block
+  readonly?: boolean
+  onInput: (spans: InlineSpan[], caret: number | null) => void
+  onEnter: (offsets: { start: number; end: number }) => void
+  onBackspaceStart: () => void
+  onDeleteEnd: () => void
+  onArrowUp: () => void
+  onArrowDown: () => void
+  onTab: (shift: boolean) => void
+  onFormat: (mark: MarkName) => void
+  onPasted: (payload: {
+    html: string
+    text: string
+    files: File[]
+    offsets: { start: number; end: number }
+  }) => void
+  onFocus: () => void
+  onSelectionPointerDown: (payload: { shiftKey: boolean; clientX: number; clientY: number }) => void
+  onPatch: (patch: Record<string, unknown>) => void
+  onSelect: () => void
+}
+
+const STYLE_TO_VARIANT: Record<string, 'default' | 'outline' | 'ghost'> = {
+  primary: 'default',
+  outline: 'outline',
+  ghost: 'ghost',
+}
+
+const ALIGN_TO_JUSTIFY: Record<string, string> = {
+  left: 'justify-start',
+  center: 'justify-center',
+  right: 'justify-end',
+}
+
+export const ButtonBlock = forwardRef<TextBlockHandle, ButtonBlockProps>(function ButtonBlock(
+  { block, readonly, onPatch, onSelect, ...textEvents },
+  ref,
+) {
+  const [open, setOpen] = useState(false)
+  const variant = STYLE_TO_VARIANT[block.props.buttonStyle ?? 'primary'] ?? 'default'
+  const justify = ALIGN_TO_JUSTIFY[block.props.align ?? 'left'] ?? 'justify-start'
+
+  return (
+    <div className={`my-1 flex items-center gap-1.5 ${justify}`} onClick={onSelect}>
+      <div className={`xpe-btn xpe-btn--${variant} xpe-btn--md min-w-[64px]`}>
+        <TextBlock
+          ref={ref}
+          block={block}
+          readonly={readonly}
+          placeholder="Button"
+          className="min-w-0 text-center outline-none"
+          {...textEvents}
+        />
+      </div>
+
+      {!readonly && (
+        <Popover open={open} onOpenChange={setOpen}>
+          <PopoverTrigger>
+            <button
+              type="button"
+              className="flex h-7 w-7 shrink-0 items-center justify-center rounded-lg text-[var(--xpe-muted-foreground)] hover:bg-[var(--xpe-surface-hover)] hover:text-[var(--xpe-foreground)]"
+              title="Button link & style"
+              onClick={() => setOpen((o) => !o)}
+            >
+              <Link2 className="h-3.5 w-3.5" />
+            </button>
+          </PopoverTrigger>
+          <PopoverContent align="start" className="xpe-button-settings">
+            <div className="flex flex-col gap-2.5 p-3 w-64">
+              <label className="flex flex-col gap-1">
+                <span className="text-[11px] font-medium text-[var(--xpe-muted-foreground)]">Link URL</span>
+                <Input
+                  type="url"
+                  placeholder="https://..."
+                  defaultValue={block.props.url ?? ''}
+                  onChange={(e) => onPatch({ url: e.target.value })}
+                />
+              </label>
+
+              <label className="flex items-center gap-2 text-[12px] text-[var(--xpe-foreground)]">
+                <input
+                  type="checkbox"
+                  checked={!!block.props.openInNewTab}
+                  onChange={(e) => onPatch({ openInNewTab: e.target.checked })}
+                />
+                <SquareArrowOutUpRight className="h-3.5 w-3.5 text-[var(--xpe-muted-foreground)]" />
+                Open in new tab
+              </label>
+
+              <div className="flex flex-col gap-1">
+                <span className="text-[11px] font-medium text-[var(--xpe-muted-foreground)]">Style</span>
+                <div className="flex gap-1">
+                  {(['primary', 'outline', 'ghost'] as const).map((s) => (
+                    <Button
+                      key={s}
+                      size="sm"
+                      variant={block.props.buttonStyle === s ? 'default' : 'outline'}
+                      onClick={() => onPatch({ buttonStyle: s })}
+                    >
+                      {s === 'primary' ? 'Primary' : s === 'outline' ? 'Outline' : 'Ghost'}
+                    </Button>
+                  ))}
+                </div>
+              </div>
+
+              <div className="flex flex-col gap-1">
+                <span className="text-[11px] font-medium text-[var(--xpe-muted-foreground)]">Alignment</span>
+                <div className="flex gap-1">
+                  {(['left', 'center', 'right'] as const).map((a) => (
+                    <Button
+                      key={a}
+                      size="sm"
+                      variant={(block.props.align ?? 'left') === a ? 'default' : 'outline'}
+                      onClick={() => onPatch({ align: a })}
+                    >
+                      {a[0].toUpperCase() + a.slice(1)}
+                    </Button>
+                  ))}
+                </div>
+              </div>
+            </div>
+          </PopoverContent>
+        </Popover>
+      )}
+    </div>
+  )
+})
diff --git a/packages/react/src/components/DocRenderer.tsx b/packages/react/src/components/DocRenderer.tsx
index e182e23..9ad5d80 100644
--- a/packages/react/src/components/DocRenderer.tsx
+++ b/packages/react/src/components/DocRenderer.tsx
@@ -336,6 +336,29 @@ export function DocRenderer({ blocks, editorDir }: DocRendererProps) {
           )
         }
 
+        if (block.type === 'button') {
+          const variant = block.props.buttonStyle ?? 'primary'
+          const justify =
+            block.props.align === 'center' ? 'center' : block.props.align === 'right' ? 'flex-end' : 'flex-start'
+          const label = spansToHtml(block.content) || 'Button'
+
+          return (
+            <div key={idx} className="db-button-row" style={{ justifyContent: justify }}>
+              {block.props.url ? (
+                <a
+                  href={block.props.url}
+                  target={block.props.openInNewTab ? '_blank' : undefined}
+                  rel={block.props.openInNewTab ? 'noopener noreferrer' : undefined}
+                  className={`db-button db-button--${variant}`}
+                  dangerouslySetInnerHTML={{ __html: label }}
+                />
+              ) : (
+                <span className={`db-button db-button--${variant}`} dangerouslySetInnerHTML={{ __html: label }} />
+              )}
+            </div>
+          )
+        }
+
         if (block.type === 'table' && block.props.table) {
           const table = normalizeTableData(block.props.table)
 
diff --git a/packages/react/src/components/EmojiTriggerMenu.tsx b/packages/react/src/components/EmojiTriggerMenu.tsx
new file mode 100644
index 0000000..5df08f3
--- /dev/null
+++ b/packages/react/src/components/EmojiTriggerMenu.tsx
@@ -0,0 +1,70 @@
+import { useLayoutEffect, useRef, useState } from 'react'
+import { createPortal } from 'react-dom'
+import { lockPageScroll, syncThemeVars } from '@xproeditor/core'
+import { EmojiPicker } from '../ui'
+
+export interface EmojiTriggerMenuProps {
+  query: string
+  /** Caret anchor in viewport coordinates: menu opens below `y`, flips above `top` when needed. */
+  position: { x: number; y: number; top?: number }
+  dir?: 'ltr' | 'rtl'
+  themeSource?: HTMLElement | null
+  onSelect: (emoji: string) => void
+}
+
+export function EmojiTriggerMenu({ query, position, dir, themeSource, onSelect }: EmojiTriggerMenuProps) {
+  const menuRef = useRef<HTMLDivElement | null>(null)
+  const [placed, setPlaced] = useState<{ left: number; top: number }>({
+    left: position.x,
+    top: position.y,
+  })
+
+  useLayoutEffect(() => {
+    const unlock = lockPageScroll()
+    return unlock
+  }, [])
+
+  useLayoutEffect(() => {
+    function place() {
+      const el = menuRef.current
+      if (!el) return
+
+      if (themeSource) syncThemeVars(themeSource, el)
+
+      const margin = 8
+      const gap = 6
+      const { width, height } = el.getBoundingClientRect()
+      const anchorTop = position.top ?? position.y
+      let left = dir === 'rtl' ? position.x - width : position.x
+      left = Math.max(margin, Math.min(left, window.innerWidth - width - margin))
+      let top = position.y + gap
+
+      if (top + height > window.innerHeight - margin) {
+        top = Math.max(margin, anchorTop - height - gap)
+      }
+
+      setPlaced({ left, top })
+    }
+
+    place()
+    window.addEventListener('resize', place)
+    window.addEventListener('scroll', place, true)
+    return () => {
+      window.removeEventListener('resize', place)
+      window.removeEventListener('scroll', place, true)
+    }
+  }, [position, dir, themeSource, query])
+
+  return createPortal(
+    <div
+      ref={menuRef}
+      className="fixed z-[80] border bg-[var(--xpe-surface)] border-[var(--xpe-border)] rounded-[var(--xpe-radius)] [box-shadow:var(--xpe-shadow)] overflow-hidden"
+      style={{ left: placed.left, top: placed.top }}
+      dir={dir}
+      onMouseDown={(e) => e.preventDefault()}
+    >
+      <EmojiPicker query={query} onSelect={onSelect} />
+    </div>,
+    document.body,
+  )
+}
diff --git a/packages/react/src/components/SlashMenu.tsx b/packages/react/src/components/SlashMenu.tsx
index 3c00bf9..5439b7a 100644
--- a/packages/react/src/components/SlashMenu.tsx
+++ b/packages/react/src/components/SlashMenu.tsx
@@ -8,6 +8,7 @@ import {
   useState,
 } from 'react'
 import { createPortal } from 'react-dom'
+import { lockPageScroll, syncThemeVars } from '@xproeditor/core'
 import {
   Type,
   Heading1,
@@ -29,8 +30,16 @@ import {
   Music,
   Paperclip,
   SearchX,
+  SquareMousePointer,
 } from 'lucide-react'
-import type { SlashItem } from '../types'
+import type { SlashGroup, SlashItem } from '../types'
+
+const GROUP_LABELS: Record<SlashGroup, string> = {
+  basic: 'Basic blocks',
+  lists: 'Lists & tasks',
+  media: 'Media',
+  advanced: 'Advanced',
+}
 
 const ITEMS: SlashItem[] = [
   {
@@ -40,6 +49,7 @@ const ITEMS: SlashItem[] = [
     description: 'Plain paragraph',
     keywords: ['text', 'paragraph', 'p'],
     icon: Type,
+    group: 'basic',
   },
   {
     id: 'heading_1',
@@ -48,6 +58,7 @@ const ITEMS: SlashItem[] = [
     description: 'Large section heading',
     keywords: ['h1', 'heading', 'title'],
     icon: Heading1,
+    group: 'basic',
   },
   {
     id: 'heading_2',
@@ -56,6 +67,7 @@ const ITEMS: SlashItem[] = [
     description: 'Medium section heading',
     keywords: ['h2', 'heading', 'subtitle'],
     icon: Heading2,
+    group: 'basic',
   },
   {
     id: 'heading_3',
@@ -64,6 +76,7 @@ const ITEMS: SlashItem[] = [
     description: 'Small section heading',
     keywords: ['h3', 'heading'],
     icon: Heading3,
+    group: 'basic',
   },
   {
     id: 'bulleted_list_item',
@@ -72,6 +85,7 @@ const ITEMS: SlashItem[] = [
     description: 'Simple bullet list',
     keywords: ['bullet', 'list', 'ul'],
     icon: List,
+    group: 'lists',
   },
   {
     id: 'numbered_list_item',
@@ -80,6 +94,7 @@ const ITEMS: SlashItem[] = [
     description: 'Ordered list',
     keywords: ['number', 'ordered', 'ol'],
     icon: ListOrdered,
+    group: 'lists',
   },
   {
     id: 'to_do',
@@ -88,6 +103,7 @@ const ITEMS: SlashItem[] = [
     description: 'Checkbox task',
     keywords: ['todo', 'check', 'task'],
     icon: CheckSquare,
+    group: 'lists',
   },
   {
     id: 'toggle',
@@ -96,6 +112,43 @@ const ITEMS: SlashItem[] = [
     description: 'Collapsible content',
     keywords: ['toggle', 'collapse', 'accordion'],
     icon: ChevronRight,
+    group: 'lists',
+  },
+  {
+    id: 'image',
+    type: 'image',
+    label: 'Image',
+    description: 'Upload an image',
+    keywords: ['image', 'photo', 'picture', 'upload'],
+    icon: ImageIcon,
+    group: 'media',
+  },
+  {
+    id: 'video',
+    type: 'video',
+    label: 'Video',
+    description: 'Upload or embed a video',
+    keywords: ['video', 'youtube', 'vimeo', 'movie'],
+    icon: Video,
+    group: 'media',
+  },
+  {
+    id: 'audio',
+    type: 'audio',
+    label: 'Audio',
+    description: 'Upload or link audio',
+    keywords: ['audio', 'music', 'song', 'sound', 'mp3'],
+    icon: Music,
+    group: 'media',
+  },
+  {
+    id: 'file',
+    type: 'file',
+    label: 'File',
+    description: 'Attach a downloadable file',
+    keywords: ['file', 'attachment', 'pdf', 'document', 'download'],
+    icon: Paperclip,
+    group: 'media',
   },
   {
     id: 'quote',
@@ -104,6 +157,7 @@ const ITEMS: SlashItem[] = [
     description: 'Capture a quote',
     keywords: ['quote', 'blockquote'],
     icon: Quote,
+    group: 'advanced',
   },
   {
     id: 'callout',
@@ -112,6 +166,7 @@ const ITEMS: SlashItem[] = [
     description: 'Highlighted note',
     keywords: ['callout', 'note', 'info', 'warning'],
     icon: Lightbulb,
+    group: 'advanced',
   },
   {
     id: 'emoji',
@@ -120,6 +175,7 @@ const ITEMS: SlashItem[] = [
     description: 'Callout with emoji icon',
     keywords: ['emoji', 'emoticon', 'smile'],
     icon: Smile,
+    group: 'advanced',
     pickIcon: 'emoji',
   },
   {
@@ -129,6 +185,7 @@ const ITEMS: SlashItem[] = [
     description: 'Callout with vector icon',
     keywords: ['icon', 'symbol', 'lucide'],
     icon: Blocks,
+    group: 'advanced',
     pickIcon: 'icon',
   },
   {
@@ -138,6 +195,7 @@ const ITEMS: SlashItem[] = [
     description: 'Code block with syntax',
     keywords: ['code', 'snippet', 'pre'],
     icon: Code2,
+    group: 'advanced',
   },
   {
     id: 'divider',
@@ -146,38 +204,7 @@ const ITEMS: SlashItem[] = [
     description: 'Horizontal line',
     keywords: ['divider', 'hr', 'separator', 'line'],
     icon: Minus,
-  },
-  {
-    id: 'image',
-    type: 'image',
-    label: 'Image',
-    description: 'Upload an image',
-    keywords: ['image', 'photo', 'picture', 'upload'],
-    icon: ImageIcon,
-  },
-  {
-    id: 'video',
-    type: 'video',
-    label: 'Video',
-    description: 'Upload or embed a video',
-    keywords: ['video', 'youtube', 'vimeo', 'movie'],
-    icon: Video,
-  },
-  {
-    id: 'audio',
-    type: 'audio',
-    label: 'Audio',
-    description: 'Upload or link audio',
-    keywords: ['audio', 'music', 'song', 'sound', 'mp3'],
-    icon: Music,
-  },
-  {
-    id: 'file',
-    type: 'file',
-    label: 'File',
-    description: 'Attach a downloadable file',
-    keywords: ['file', 'attachment', 'pdf', 'document', 'download'],
-    icon: Paperclip,
+    group: 'advanced',
   },
   {
     id: 'table',
@@ -186,6 +213,16 @@ const ITEMS: SlashItem[] = [
     description: 'Simple table',
     keywords: ['table', 'grid'],
     icon: Table2,
+    group: 'advanced',
+  },
+  {
+    id: 'button',
+    type: 'button',
+    label: 'Button',
+    description: 'A clickable link styled as a button',
+    keywords: ['button', 'link', 'cta', 'action'],
+    icon: SquareMousePointer,
+    group: 'advanced',
   },
 ]
 
@@ -199,12 +236,15 @@ export interface SlashMenuProps {
   /** Caret anchor in viewport coordinates: menu opens below `y`, flips above `top` when needed. */
   position: { x: number; y: number; top?: number }
   dir?: 'ltr' | 'rtl'
+  /** Element still inside the editor's themed DOM scope — used to resync
+   * `--xpe-*` variables onto this menu once it's portaled to `<body>`. */
+  themeSource?: HTMLElement | null
   onSelect: (item: SlashItem) => void
   onClose: () => void
 }
 
 export const SlashMenu = forwardRef<SlashMenuHandle, SlashMenuProps>(function SlashMenu(
-  { query, position, dir, onSelect },
+  { query, position, dir, themeSource, onSelect },
   ref,
 ) {
   const [activeIndex, setActiveIndex] = useState(0)
@@ -225,6 +265,14 @@ export const SlashMenu = forwardRef<SlashMenuHandle, SlashMenuProps>(function Sl
 
   useEffect(() => setActiveIndex(0), [query])
 
+  // Lock page scroll while the menu is open (Notion-like) — a scrollable
+  // ancestor outside document.body can still move, so `place` below still
+  // listens for scroll to keep the menu anchored if that happens.
+  useEffect(() => {
+    const unlock = lockPageScroll()
+    return unlock
+  }, [])
+
   // Place the menu with its real measured size: below the caret when it fits,
   // flipped above otherwise, clamped to the viewport. In RTL the menu grows
   // toward the start (its end edge hugs the caret).
@@ -233,6 +281,8 @@ export const SlashMenu = forwardRef<SlashMenuHandle, SlashMenuProps>(function Sl
       const el = menuRef.current
       if (!el) return
 
+      if (themeSource) syncThemeVars(themeSource, el)
+
       const margin = 8
       const gap = 6
       const { width, height } = el.getBoundingClientRect()
@@ -255,7 +305,7 @@ export const SlashMenu = forwardRef<SlashMenuHandle, SlashMenuProps>(function Sl
       window.removeEventListener('resize', place)
       window.removeEventListener('scroll', place, true)
     }
-  }, [position, dir, filtered.length])
+  }, [position, dir, themeSource, filtered.length])
 
   function scrollActiveIntoView() {
     requestAnimationFrame(() => {
@@ -289,11 +339,8 @@ export const SlashMenu = forwardRef<SlashMenuHandle, SlashMenuProps>(function Sl
       dir={dir}
       onMouseDown={(e) => e.preventDefault()}
     >
-      <p className="px-3 pt-1 pb-1.5 text-[10px] font-semibold uppercase tracking-wider text-[var(--xpe-muted-foreground)]">
-        Blocks
-      </p>
       {filtered.length === 0 && (
-        <div className="flex items-center gap-2 px-3 py-3 text-[13px] text-[var(--xpe-muted-foreground)]">
+        <div className="flex items-center gap-2 px-3 py-4 text-[13px] text-[var(--xpe-muted-foreground)]">
           <SearchX className="w-4 h-4" />
           No results for “{query}”
         </div>
@@ -301,28 +348,35 @@ export const SlashMenu = forwardRef<SlashMenuHandle, SlashMenuProps>(function Sl
       <div ref={listRef}>
         {filtered.map((item, idx) => {
           const Icon = item.icon
+          const showHeader = idx === 0 || filtered[idx - 1].group !== item.group
           return (
-            <button
-              key={item.id}
-              className={`flex items-center gap-3 w-full px-3 py-1.5 text-start transition-colors ${idx === activeIndex ? 'bg-[var(--xpe-primary-muted)]' : 'hover:bg-[var(--xpe-surface-hover)]'}`}
-              data-active={idx === activeIndex}
-              onMouseEnter={() => setActiveIndex(idx)}
-              onClick={() => onSelect(item)}
-            >
-              <span
-                className={`flex items-center justify-center w-8 h-8 rounded-lg border shrink-0 ${idx === activeIndex ? 'border-[var(--xpe-border)] bg-[var(--xpe-surface)] text-[var(--xpe-primary)]' : 'border-[var(--xpe-border)] bg-[var(--xpe-muted)] text-[var(--xpe-muted-foreground)]'}`}
+            <div key={item.id}>
+              {showHeader && (
+                <p className="px-3 pt-2.5 pb-1 text-[10px] font-semibold uppercase tracking-wider text-[var(--xpe-muted-foreground)] first:pt-1">
+                  {GROUP_LABELS[item.group]}
+                </p>
+              )}
+              <button
+                className={`flex items-center gap-3 w-full px-3 py-1.5 text-start transition-colors ${idx === activeIndex ? 'bg-[var(--xpe-primary-muted)]' : 'hover:bg-[var(--xpe-surface-hover)]'}`}
+                data-active={idx === activeIndex}
+                onMouseEnter={() => setActiveIndex(idx)}
+                onClick={() => onSelect(item)}
               >
-                <Icon className="w-4 h-4" />
-              </span>
-              <span className="min-w-0">
-                <span className="block text-[13px] font-medium text-[var(--xpe-foreground)]">
-                  {item.label}
+                <span
+                  className={`flex items-center justify-center w-8 h-8 rounded-lg border shrink-0 ${idx === activeIndex ? 'border-[var(--xpe-border)] bg-[var(--xpe-surface)] text-[var(--xpe-primary)]' : 'border-[var(--xpe-border)] bg-[var(--xpe-muted)] text-[var(--xpe-muted-foreground)]'}`}
+                >
+                  <Icon className="w-4 h-4" />
                 </span>
-                <span className="block text-[11px] text-[var(--xpe-muted-foreground)] truncate">
-                  {item.description}
+                <span className="min-w-0">
+                  <span className="block text-[13px] font-medium text-[var(--xpe-foreground)]">
+                    {item.label}
+                  </span>
+                  <span className="block text-[11px] text-[var(--xpe-muted-foreground)] truncate">
+                    {item.description}
+                  </span>
                 </span>
-              </span>
-            </button>
+              </button>
+            </div>
           )
         })}
       </div>
diff --git a/packages/react/src/hooks/useBlockEditor.ts b/packages/react/src/hooks/useBlockEditor.ts
index bbe0258..62eb201 100644
--- a/packages/react/src/hooks/useBlockEditor.ts
+++ b/packages/react/src/hooks/useBlockEditor.ts
@@ -1,4 +1,5 @@
 import { useEffect, useMemo, useRef, useState } from 'react'
+import { ALL_EMOJIS } from '../ui/emojiData'
 import {
   applyMarkToRange,
   applyMarkToTextRange,
@@ -78,6 +79,13 @@ interface SlashState {
   position: { x: number; y: number; top?: number }
 }
 
+interface EmojiTriggerState {
+  blockId: string
+  index: number
+  query: string
+  position: { x: number; y: number; top?: number }
+}
+
 interface BubbleState {
   blockId: string
   range: { start: number; end: number }
@@ -149,6 +157,7 @@ export function useBlockEditor(options: UseBlockEditorOptions) {
   const [textRangeSelection, setTextRangeSelection] = useState<TextRangeSelection | null>(null)
   const [managedTextSelection, setManagedTextSelectionFlag] = useState(false)
   const [slashState, setSlashState] = useState<SlashState | null>(null)
+  const [emojiTriggerState, setEmojiTriggerState] = useState<EmojiTriggerState | null>(null)
   const [iconPickerRequest, setIconPickerRequest] = useState<{
     blockId: string
     tab: 'emoji' | 'icon'
@@ -601,6 +610,52 @@ export function useBlockEditor(options: UseBlockEditorOptions) {
     else selectBlock(newBlock.id)
   }
 
+  // ─── Inline emoji trigger (":" — Slack/Discord-style) ─────────────────────
+
+  function closeEmojiTrigger() {
+    setEmojiTriggerState(null)
+  }
+
+  function updateEmojiTrigger(block: Block, spans: InlineSpan[], caret: number | null) {
+    const text = spansToText(spans)
+
+    setEmojiTriggerState((state) => {
+      if (state && state.blockId === block.id) {
+        if (caret === null || caret <= state.index || text[state.index] !== ':') return null
+
+        const query = text.slice(state.index + 1, caret)
+        if (/\s/.test(query) || query.length > 20) return null
+
+        return { ...state, query }
+      }
+
+      if (caret !== null && caret > 0 && text[caret - 1] === ':') {
+        const before = caret >= 2 ? text[caret - 2] : ''
+
+        if (before === '' || /\s/.test(before)) {
+          return { blockId: block.id, index: caret - 1, query: '', position: slashPosition() }
+        }
+      }
+
+      return state
+    })
+  }
+
+  function onEmojiTriggerSelect(emoji: string) {
+    const state = emojiTriggerState
+    if (!state) return
+
+    const block = byId(state.blockId)
+    closeEmojiTrigger()
+    if (!block) return
+
+    const removeEnd = state.index + 1 + state.query.length
+    const withoutTrigger = deleteRangeInSpans(block.content, state.index, removeEnd)
+    block.content = insertSpansAt(withoutTrigger, state.index, [{ text: emoji }])
+    pushHistory(true)
+    focusBlock(block.id, state.index + emoji.length)
+  }
+
   // ─── Markdown shortcuts ────────────────────────────────────────────────────
 
   function tryMarkdownShortcut(block: Block, spans: InlineSpan[], caret: number | null): boolean {
@@ -657,10 +712,18 @@ export function useBlockEditor(options: UseBlockEditorOptions) {
 
     if (tryMarkdownShortcut(block, spans, caret)) {
       closeSlash()
+      closeEmojiTrigger()
       return
     }
 
     updateSlash(block, spans, caret)
+
+    if (slashState) {
+      closeEmojiTrigger()
+    } else {
+      updateEmojiTrigger(block, spans, caret)
+    }
+
     pushHistory()
   }
 
@@ -1960,7 +2023,65 @@ export function useBlockEditor(options: UseBlockEditorOptions) {
   }
 
   function onKeydownCapture(e: React.KeyboardEvent) {
-    if (readonly || isNativeInputTarget(e.target)) return
+    if (readonly) return
+
+    // Slash menu lives inside the contenteditable block being typed into, so
+    // this must run before the isNativeInputTarget bail-out below (which
+    // exists to let text blocks handle their own keys normally).
+    if (slashState) {
+      if (e.key === 'ArrowDown') {
+        e.preventDefault()
+        e.stopPropagation()
+        slashMenuApiRef.current?.move(1)
+        return
+      }
+
+      if (e.key === 'ArrowUp') {
+        e.preventDefault()
+        e.stopPropagation()
+        slashMenuApiRef.current?.move(-1)
+        return
+      }
+
+      if (e.key === 'Enter' || e.key === 'Tab') {
+        e.preventDefault()
+        e.stopPropagation()
+        slashMenuApiRef.current?.confirm()
+        return
+      }
+
+      if (e.key === 'Escape') {
+        e.preventDefault()
+        e.stopPropagation()
+        closeSlash()
+        return
+      }
+    }
+
+    if (emojiTriggerState) {
+      if (e.key === 'Enter' || e.key === 'Tab') {
+        e.preventDefault()
+        e.stopPropagation()
+        const q = emojiTriggerState.query.toLowerCase()
+        const match = q
+          ? ALL_EMOJIS.find((en) => en.name.includes(q) || en.keywords.some((k) => k.includes(q)))
+          : null
+
+        if (match) onEmojiTriggerSelect(match.char)
+        else closeEmojiTrigger()
+
+        return
+      }
+
+      if (e.key === 'Escape') {
+        e.preventDefault()
+        e.stopPropagation()
+        closeEmojiTrigger()
+        return
+      }
+    }
+
+    if (isNativeInputTarget(e.target)) return
 
     const mod = e.ctrlKey || e.metaKey
 
@@ -2030,35 +2151,7 @@ export function useBlockEditor(options: UseBlockEditorOptions) {
       return
     }
 
-    if (slashState) {
-      if (e.key === 'ArrowDown') {
-        e.preventDefault()
-        e.stopPropagation()
-        slashMenuApiRef.current?.move(1)
-        return
-      }
-
-      if (e.key === 'ArrowUp') {
-        e.preventDefault()
-        e.stopPropagation()
-        slashMenuApiRef.current?.move(-1)
-        return
-      }
-
-      if (e.key === 'Enter' || e.key === 'Tab') {
-        e.preventDefault()
-        e.stopPropagation()
-        slashMenuApiRef.current?.confirm()
-        return
-      }
-
-      if (e.key === 'Escape') {
-        e.preventDefault()
-        e.stopPropagation()
-        closeSlash()
-        return
-      }
-    } else if (e.key === 'Escape' && bubble) {
+    if (e.key === 'Escape' && bubble) {
       setBubble(null)
     }
   }
@@ -2153,6 +2246,8 @@ export function useBlockEditor(options: UseBlockEditorOptions) {
 
     if (slashState && !target.closest('.fixed')) closeSlash()
 
+    if (emojiTriggerState && !target.closest('.fixed')) closeEmojiTrigger()
+
     if (selectedBlockId && !target.closest(`[data-block-id="${selectedBlockId}"]`)) {
       setSelectedBlockId(null)
     }
@@ -2227,6 +2322,7 @@ export function useBlockEditor(options: UseBlockEditorOptions) {
     dropTarget,
     slashState,
     slashMenuApiRef,
+    emojiTriggerState,
     bubble,
     iconPickerRequest,
     setIconPickerRequest,
@@ -2277,6 +2373,8 @@ export function useBlockEditor(options: UseBlockEditorOptions) {
     onDragHandleStart,
     onSlashSelect,
     closeSlash,
+    onEmojiTriggerSelect,
+    closeEmojiTrigger,
     onBubbleMark,
     onBubbleTurnInto,
     handleInput,
diff --git a/packages/react/src/index.ts b/packages/react/src/index.ts
index 9699f2f..5d5ab52 100644
--- a/packages/react/src/index.ts
+++ b/packages/react/src/index.ts
@@ -24,6 +24,12 @@ export { ImageBlock } from './components/ImageBlock'
 export type { ImageBlockProps } from './components/ImageBlock'
 export { VideoBlock } from './components/VideoBlock'
 export type { VideoBlockProps } from './components/VideoBlock'
+export { AudioBlock } from './components/AudioBlock'
+export type { AudioBlockProps } from './components/AudioBlock'
+export { FileBlock } from './components/FileBlock'
+export type { FileBlockProps } from './components/FileBlock'
+export { ButtonBlock } from './components/ButtonBlock'
+export type { ButtonBlockProps } from './components/ButtonBlock'
 export { TableBlock } from './components/TableBlock'
 export type { TableBlockHandle, TableBlockProps } from './components/TableBlock'
 export { TableCell } from './components/TableCell'
diff --git a/packages/react/src/styles/components.css b/packages/react/src/styles/components.css
index e4b05f4..cd25731 100644
--- a/packages/react/src/styles/components.css
+++ b/packages/react/src/styles/components.css
@@ -102,15 +102,27 @@
 /* ── ui/IconEmojiPicker & IconValueDisplay ────────────────────────────── */
 .xpe-icon-value { display: inline-flex; align-items: center; justify-content: center; line-height: 1; }
 .xpe-icon-trigger { display: inline-flex; align-items: center; justify-content: center; font-size: 18px; line-height: 1; background: transparent; border: none; cursor: pointer; padding: 0; }
-.xpe-icon-popover { padding: 10px; width: 232px; }
-.xpe-icon-grid { display: grid; grid-template-columns: repeat(8, 1fr); gap: 2px; }
-.xpe-icon-cell { display: flex; align-items: center; justify-content: center; height: 26px; border-radius: 6px; border: none; background: transparent; font-size: 15px; cursor: pointer; }
-.xpe-icon-cell:hover { background: var(--xpe-muted, #f3f4f6); }
-.xpe-icon-cell--active { background: var(--xpe-primary-muted, #eef2ff); }
-.xpe-icon-custom { display: flex; gap: 6px; margin-top: 8px; padding-top: 8px; border-top: 1px solid var(--xpe-border, #f3f4f6); }
+.xpe-icon-popover { padding: 0; width: 300px; overflow: hidden; }
+.xpe-icon-custom { display: flex; gap: 6px; margin: 0; padding: 8px 10px; border-top: 1px solid var(--xpe-border, #f3f4f6); }
 .xpe-icon-custom-input { flex: 1; height: 28px; border: 1px solid var(--xpe-border, #e5e7eb); border-radius: 6px; padding: 0 8px; font-size: 12px; outline: none; }
 .xpe-icon-custom-apply { height: 28px; padding: 0 10px; border-radius: 6px; border: none; background: var(--xpe-primary, #4f46e5); color: var(--xpe-primary-foreground, #fff); font-size: 12px; cursor: pointer; }
 
+/* ── ui/EmojiPicker (standalone: callout icon, ':' inline trigger) ──────── */
+.xpe-emoji-picker { display: flex; flex-direction: column; width: 300px; height: 340px; }
+.xpe-emoji-picker--controlled { height: auto; max-height: 260px; width: 280px; }
+.xpe-emoji-search { display: flex; align-items: center; gap: 6px; padding: 8px 10px; border-bottom: 1px solid var(--xpe-border, #e5e7eb); flex-shrink: 0; }
+.xpe-emoji-search-input { flex: 1; border: none; background: transparent; outline: none; font-size: 13px; color: var(--xpe-foreground, #111827); }
+.xpe-emoji-search-input::placeholder { color: var(--xpe-muted-foreground, #9ca3af); }
+.xpe-emoji-scroll { flex: 1; overflow-y: auto; padding: 6px 8px; }
+.xpe-emoji-heading { padding: 6px 4px 4px; font-size: 10px; font-weight: 700; text-transform: uppercase; letter-spacing: 0.06em; color: var(--xpe-muted-foreground, #9ca3af); }
+.xpe-emoji-grid { display: grid; grid-template-columns: repeat(8, 1fr); gap: 2px; }
+.xpe-emoji-cell { display: flex; align-items: center; justify-content: center; height: 32px; border-radius: 8px; border: none; background: transparent; font-size: 19px; line-height: 1; cursor: pointer; transition: background 0.1s, transform 0.1s; }
+.xpe-emoji-cell:hover { background: var(--xpe-muted, #f3f4f6); transform: scale(1.12); }
+.xpe-emoji-empty { padding: 24px 8px; text-align: center; font-size: 12px; color: var(--xpe-muted-foreground, #9ca3af); }
+.xpe-emoji-catbar { display: flex; align-items: center; justify-content: space-between; gap: 2px; padding: 6px 8px; border-top: 1px solid var(--xpe-border, #e5e7eb); flex-shrink: 0; }
+.xpe-emoji-catbar button { display: flex; align-items: center; justify-content: center; width: 26px; height: 26px; border-radius: 6px; border: none; background: transparent; color: var(--xpe-muted-foreground, #9ca3af); cursor: pointer; transition: background 0.1s, color 0.1s; }
+.xpe-emoji-catbar button:hover { background: var(--xpe-muted, #f3f4f6); color: var(--xpe-foreground, #111827); }
+
 /* ── toolbar/ToolbarButton (also used standalone in BubbleToolbar) ──────── */
 .ebt-btn {
   display: flex;
@@ -240,9 +252,8 @@
   margin-top: 0.45em;
   border-radius: 4px;
   border: 1.5px solid var(--xpe-border);
-  color: white;
 }
-.db-todo-checked { background: var(--xpe-primary); border-color: var(--xpe-primary); }
+.db-todo-checked { background: var(--xpe-primary); border-color: var(--xpe-primary); color: var(--xpe-primary-foreground); }
 .db-todo-box svg { width: 10px; height: 10px; }
 .db-toggle { cursor: pointer; user-select: none; }
 .db-toggle-chevron { flex-shrink: 0; display: inline-flex; margin-top: 0.4em; color: var(--xpe-muted-foreground); transition: transform 0.15s; }
@@ -266,6 +277,17 @@
 .db-file:hover { border-color: var(--xpe-primary); }
 .db-file-name { font-size: 0.9em; font-weight: 500; flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
 .db-file-size { font-size: 0.8em; color: var(--xpe-muted-foreground); flex-shrink: 0; }
+.db-button-row { display: flex; margin: 0.75em 0; }
+.db-button { display: inline-flex; align-items: center; justify-content: center; min-width: 64px; padding: 0.5em 1.1em; border-radius: var(--xpe-radius, 0.6rem); font-size: 0.9em; font-weight: 600; text-decoration: none; cursor: pointer; border: 1px solid transparent; transition: opacity 0.12s; }
+.db-button:hover { opacity: 0.88; }
+.db-button--primary { background: var(--xpe-primary); color: var(--xpe-primary-foreground); }
+.db-button--outline { background: transparent; border-color: var(--xpe-border); color: var(--xpe-foreground); }
+.db-button--ghost { background: var(--xpe-muted); color: var(--xpe-foreground); }
+
+/* Button block label: the editable .etb always sets its own color, so the
+   button variant's contrast-correct text color needs a more specific rule
+   to win the cascade instead of being silently overridden. */
+.xpe-btn .etb { color: inherit; }
 .db-table-wrap { overflow-x: auto; margin: 1.25em 0; }
 .db-table { width: 100%; border-collapse: collapse; border-radius: 0.5rem; overflow: hidden; }
 .db-table th, .db-table td { padding: 0.55em 1em; text-align: start; vertical-align: top; line-height: 1.6; font-size: 0.9em; }
diff --git a/packages/react/src/types.ts b/packages/react/src/types.ts
index 1e08c8a..38c5326 100644
--- a/packages/react/src/types.ts
+++ b/packages/react/src/types.ts
@@ -19,6 +19,8 @@ export interface FormatToolbarState {
   cellBackground?: string | null
 }
 
+export type SlashGroup = 'basic' | 'lists' | 'media' | 'advanced'
+
 export interface SlashItem {
   id: string
   type: BlockType
@@ -26,6 +28,7 @@ export interface SlashItem {
   description: string
   keywords: string[]
   icon: React.ComponentType<{ className?: string }>
+  group: SlashGroup
   /** After applying the block, open the icon picker on this tab. */
   pickIcon?: 'emoji' | 'icon'
 }
diff --git a/packages/react/src/ui/EmojiPicker.tsx b/packages/react/src/ui/EmojiPicker.tsx
new file mode 100644
index 0000000..e554fb1
--- /dev/null
+++ b/packages/react/src/ui/EmojiPicker.tsx
@@ -0,0 +1,175 @@
+import { useEffect, useMemo, useRef, useState } from 'react'
+import { Clock, Hash, Lightbulb, Leaf, Music, Plane, Search, Smile, UtensilsCrossed } from 'lucide-react'
+import { ALL_EMOJIS, EMOJI_CATEGORIES, type EmojiEntry } from './emojiData'
+
+const RECENTS_KEY = 'xpe-emoji-recents'
+const MAX_RECENTS = 24
+
+function readRecents(): string[] {
+  try {
+    const raw = localStorage.getItem(RECENTS_KEY)
+    const parsed = raw ? JSON.parse(raw) : []
+    return Array.isArray(parsed) ? parsed.filter((v) => typeof v === 'string') : []
+  } catch {
+    return []
+  }
+}
+
+function pushRecent(char: string) {
+  try {
+    const next = [char, ...readRecents().filter((c) => c !== char)].slice(0, MAX_RECENTS)
+    localStorage.setItem(RECENTS_KEY, JSON.stringify(next))
+  } catch {
+    /* storage unavailable */
+  }
+}
+
+const CATEGORY_ICONS: Record<string, typeof Smile> = {
+  smileys: Smile,
+  nature: Leaf,
+  food: UtensilsCrossed,
+  activities: Music,
+  travel: Plane,
+  objects: Lightbulb,
+  symbols: Hash,
+}
+
+export interface EmojiPickerProps {
+  onSelect: (emoji: string) => void
+  /** Focus the search input as soon as the picker mounts. */
+  autoFocus?: boolean
+  /**
+   * Controlled query, driving the grid without rendering an internal search
+   * input — used by the ':' inline trigger, where the query is typed
+   * directly into the text block rather than into the popover itself.
+   */
+  query?: string
+}
+
+export function EmojiPicker({ onSelect, autoFocus, query: externalQuery }: EmojiPickerProps) {
+  const controlled = externalQuery !== undefined
+  const [internalQuery, setInternalQuery] = useState('')
+  const query = controlled ? externalQuery : internalQuery
+  const [recents, setRecents] = useState<string[]>(() => readRecents())
+  const searchRef = useRef<HTMLInputElement | null>(null)
+  const scrollRef = useRef<HTMLDivElement | null>(null)
+  const sectionRefs = useRef<Record<string, HTMLDivElement | null>>({})
+
+  useEffect(() => {
+    if (autoFocus && !controlled) searchRef.current?.focus()
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [autoFocus])
+
+  const filtered = useMemo(() => {
+    const q = query.trim().toLowerCase()
+    if (!q) return null
+    return ALL_EMOJIS.filter(
+      (e) => e.name.includes(q) || e.keywords.some((k) => k.includes(q)),
+    ).slice(0, 60)
+  }, [query])
+
+  function pick(entry: EmojiEntry) {
+    pushRecent(entry.char)
+    setRecents(readRecents())
+    onSelect(entry.char)
+  }
+
+  function scrollToCategory(id: string) {
+    setInternalQuery('')
+    requestAnimationFrame(() => {
+      sectionRefs.current[id]?.scrollIntoView({ block: 'start' })
+    })
+  }
+
+  const categoriesToRender =
+    recents.length > 0
+      ? [{ id: 'recents', label: 'Recently used', emojis: recents.map(charToEntry).filter(Boolean) as EmojiEntry[] }, ...EMOJI_CATEGORIES]
+      : EMOJI_CATEGORIES
+
+  return (
+    <div className={`xpe-emoji-picker${controlled ? ' xpe-emoji-picker--controlled' : ''}`}>
+      {!controlled && (
+        <div className="xpe-emoji-search">
+          <Search className="h-3.5 w-3.5 shrink-0 text-[var(--xpe-muted-foreground)]" />
+          <input
+            ref={searchRef}
+            type="text"
+            value={internalQuery}
+            placeholder="Search emoji..."
+            className="xpe-emoji-search-input"
+            onChange={(e) => setInternalQuery(e.target.value)}
+            onKeyDown={(e) => {
+              if (e.key === 'Enter' && filtered && filtered[0]) {
+                e.preventDefault()
+                pick(filtered[0])
+              }
+            }}
+          />
+        </div>
+      )}
+
+      <div ref={scrollRef} className="xpe-emoji-scroll">
+        {controlled && !filtered ? (
+          <p className="xpe-emoji-empty">Keep typing to search emoji…</p>
+        ) : filtered ? (
+          filtered.length === 0 ? (
+            <p className="xpe-emoji-empty">No emoji found</p>
+          ) : (
+            <div className="xpe-emoji-grid">
+              {filtered.map((entry) => (
+                <button
+                  key={entry.char}
+                  type="button"
+                  className="xpe-emoji-cell"
+                  title={entry.name}
+                  onClick={() => pick(entry)}
+                >
+                  {entry.char}
+                </button>
+              ))}
+            </div>
+          )
+        ) : (
+          categoriesToRender.map((cat) => (
+            <div key={cat.id} ref={(el) => { sectionRefs.current[cat.id] = el }}>
+              <p className="xpe-emoji-heading">{cat.label}</p>
+              <div className="xpe-emoji-grid">
+                {cat.emojis.map((entry) => (
+                  <button
+                    key={entry.char}
+                    type="button"
+                    className="xpe-emoji-cell"
+                    title={entry.name}
+                    onClick={() => pick(entry)}
+                  >
+                    {entry.char}
+                  </button>
+                ))}
+              </div>
+            </div>
+          ))
+        )}
+      </div>
+
+      {!controlled && (
+        <div className="xpe-emoji-catbar">
+          <button type="button" title="Recently used" onClick={() => scrollToCategory('recents')}>
+            <Clock className="h-4 w-4" />
+          </button>
+          {EMOJI_CATEGORIES.map((cat) => {
+            const Icon = CATEGORY_ICONS[cat.id] ?? Hash
+            return (
+              <button key={cat.id} type="button" title={cat.label} onClick={() => scrollToCategory(cat.id)}>
+                <Icon className="h-4 w-4" />
+              </button>
+            )
+          })}
+        </div>
+      )}
+    </div>
+  )
+}
+
+function charToEntry(char: string): EmojiEntry | undefined {
+  return ALL_EMOJIS.find((e) => e.char === char)
+}
diff --git a/packages/react/src/ui/IconEmojiPicker.tsx b/packages/react/src/ui/IconEmojiPicker.tsx
index 76301ef..ce6cd33 100644
--- a/packages/react/src/ui/IconEmojiPicker.tsx
+++ b/packages/react/src/ui/IconEmojiPicker.tsx
@@ -1,5 +1,5 @@
 import { forwardRef, useImperativeHandle, useState, type ReactNode } from 'react'
-import { EMOJI_PRESETS } from './emojiPresets'
+import { EmojiPicker } from './EmojiPicker'
 import { Popover, PopoverContent, PopoverTrigger } from './Popover'
 
 export interface IconEmojiPickerHandle {
@@ -61,18 +61,7 @@ export const IconEmojiPicker = forwardRef<IconEmojiPickerHandle, IconEmojiPicker
           )}
         </PopoverTrigger>
         <PopoverContent align={align} side={side} className="xpe-icon-popover">
-          <div className="xpe-icon-grid">
-            {EMOJI_PRESETS.map((emoji) => (
-              <button
-                key={emoji}
-                type="button"
-                className={`xpe-icon-cell${emoji === value ? ' xpe-icon-cell--active' : ''}`}
-                onClick={() => pick(emoji)}
-              >
-                {emoji}
-              </button>
-            ))}
-          </div>
+          <EmojiPicker onSelect={pick} />
           <div className="xpe-icon-custom">
             <input
               type="text"
diff --git a/packages/react/src/ui/Popover.tsx b/packages/react/src/ui/Popover.tsx
index e585c4d..d99d4ae 100644
--- a/packages/react/src/ui/Popover.tsx
+++ b/packages/react/src/ui/Popover.tsx
@@ -9,6 +9,7 @@ import {
   type ReactNode,
 } from 'react'
 import { createPortal } from 'react-dom'
+import { syncThemeVars } from '@xproeditor/core'
 
 export interface PopoverContextValue {
   open: boolean
@@ -83,6 +84,11 @@ export function PopoverContent({
     const content = contentRef.current
     if (!trigger || !content) return
 
+    // The popover is portaled to <body>, which escapes any scoped theme
+    // class applied to an ancestor of the editor — resync inline so it
+    // still picks up a custom --xpe-* theme.
+    syncThemeVars(trigger, content)
+
     const anchor = (trigger.firstElementChild as HTMLElement | null) ?? trigger
     const rect = anchor.getBoundingClientRect()
     const contentRect = content.getBoundingClientRect()
diff --git a/packages/react/src/ui/emojiData.ts b/packages/react/src/ui/emojiData.ts
new file mode 100644
index 0000000..50e0047
--- /dev/null
+++ b/packages/react/src/ui/emojiData.ts
@@ -0,0 +1,372 @@
+export interface EmojiEntry {
+  char: string
+  name: string
+  keywords: string[]
+}
+
+export interface EmojiCategoryData {
+  id: string
+  label: string
+  emojis: EmojiEntry[]
+}
+
+export const EMOJI_CATEGORIES: EmojiCategoryData[] = [
+  {
+    id: 'smileys',
+    label: 'Smileys & People',
+    emojis: [
+      { char: '😀', name: 'grinning face', keywords: ['smile', 'happy', 'grin'] },
+      { char: '😃', name: 'grinning face with big eyes', keywords: ['smile', 'happy'] },
+      { char: '😄', name: 'grinning face with smiling eyes', keywords: ['smile', 'happy', 'laugh'] },
+      { char: '😁', name: 'beaming face', keywords: ['smile', 'happy', 'grin'] },
+      { char: '😆', name: 'grinning squinting face', keywords: ['laugh', 'happy'] },
+      { char: '😅', name: 'grinning face with sweat', keywords: ['laugh', 'nervous', 'sweat'] },
+      { char: '🤣', name: 'rolling on the floor laughing', keywords: ['lol', 'laugh', 'rofl'] },
+      { char: '😂', name: 'face with tears of joy', keywords: ['lol', 'laugh', 'cry'] },
+      { char: '🙂', name: 'slightly smiling face', keywords: ['smile'] },
+      { char: '🙃', name: 'upside-down face', keywords: ['silly', 'sarcasm'] },
+      { char: '😉', name: 'winking face', keywords: ['wink', 'flirt'] },
+      { char: '😊', name: 'smiling face with smiling eyes', keywords: ['smile', 'happy', 'blush'] },
+      { char: '😇', name: 'smiling face with halo', keywords: ['angel', 'innocent'] },
+      { char: '🥰', name: 'smiling face with hearts', keywords: ['love', 'crush'] },
+      { char: '😍', name: 'heart eyes', keywords: ['love', 'crush', 'adore'] },
+      { char: '🤩', name: 'star-struck', keywords: ['wow', 'excited'] },
+      { char: '😘', name: 'face blowing a kiss', keywords: ['kiss', 'love'] },
+      { char: '😗', name: 'kissing face', keywords: ['kiss'] },
+      { char: '😋', name: 'face savoring food', keywords: ['yum', 'tasty', 'delicious'] },
+      { char: '😛', name: 'face with tongue', keywords: ['tongue', 'silly'] },
+      { char: '😜', name: 'winking face with tongue', keywords: ['silly', 'joke'] },
+      { char: '🤪', name: 'zany face', keywords: ['crazy', 'silly'] },
+      { char: '😝', name: 'squinting face with tongue', keywords: ['silly', 'joke'] },
+      { char: '🤑', name: 'money-mouth face', keywords: ['money', 'rich'] },
+      { char: '🤗', name: 'hugging face', keywords: ['hug', 'embrace'] },
+      { char: '🤭', name: 'face with hand over mouth', keywords: ['giggle', 'oops'] },
+      { char: '🤫', name: 'shushing face', keywords: ['quiet', 'secret'] },
+      { char: '🤔', name: 'thinking face', keywords: ['think', 'hmm', 'consider'] },
+      { char: '🤐', name: 'zipper-mouth face', keywords: ['quiet', 'silence'] },
+      { char: '🙄', name: 'face with rolling eyes', keywords: ['annoyed', 'eyeroll'] },
+      { char: '😏', name: 'smirking face', keywords: ['smug', 'sly'] },
+      { char: '😣', name: 'persevering face', keywords: ['struggle', 'annoyed'] },
+      { char: '😥', name: 'sad but relieved face', keywords: ['sad', 'relief'] },
+      { char: '😮', name: 'face with open mouth', keywords: ['wow', 'surprise'] },
+      { char: '🤐', name: 'zipper mouth', keywords: ['secret'] },
+      { char: '😯', name: 'hushed face', keywords: ['surprise', 'silent'] },
+      { char: '😪', name: 'sleepy face', keywords: ['tired', 'sleep'] },
+      { char: '😫', name: 'tired face', keywords: ['exhausted', 'tired'] },
+      { char: '🥱', name: 'yawning face', keywords: ['tired', 'sleepy', 'bored'] },
+      { char: '😴', name: 'sleeping face', keywords: ['sleep', 'zzz'] },
+      { char: '😌', name: 'relieved face', keywords: ['calm', 'relief'] },
+      { char: '😛', name: 'tongue out', keywords: ['silly'] },
+      { char: '😒', name: 'unamused face', keywords: ['annoyed', 'meh'] },
+      { char: '😓', name: 'downcast face with sweat', keywords: ['stressed', 'sweat'] },
+      { char: '😔', name: 'pensive face', keywords: ['sad', 'thoughtful'] },
+      { char: '😕', name: 'confused face', keywords: ['confused', 'unsure'] },
+      { char: '🙁', name: 'slightly frowning face', keywords: ['sad', 'frown'] },
+      { char: '😖', name: 'confounded face', keywords: ['frustrated'] },
+      { char: '😞', name: 'disappointed face', keywords: ['sad', 'disappointed'] },
+      { char: '😟', name: 'worried face', keywords: ['worried', 'concerned'] },
+      { char: '😤', name: 'face with steam from nose', keywords: ['angry', 'proud'] },
+      { char: '😢', name: 'crying face', keywords: ['sad', 'cry', 'tear'] },
+      { char: '😭', name: 'loudly crying face', keywords: ['sad', 'cry', 'sob'] },
+      { char: '😦', name: 'frowning face with open mouth', keywords: ['shock'] },
+      { char: '😧', name: 'anguished face', keywords: ['shock', 'pain'] },
+      { char: '😨', name: 'fearful face', keywords: ['scared', 'fear'] },
+      { char: '😩', name: 'weary face', keywords: ['tired', 'stressed'] },
+      { char: '🤯', name: 'exploding head', keywords: ['mind blown', 'shock'] },
+      { char: '😬', name: 'grimacing face', keywords: ['awkward', 'nervous'] },
+      { char: '😰', name: 'anxious face with sweat', keywords: ['nervous', 'anxious'] },
+      { char: '😱', name: 'face screaming in fear', keywords: ['scream', 'shock'] },
+      { char: '🥵', name: 'hot face', keywords: ['hot', 'heat'] },
+      { char: '🥶', name: 'cold face', keywords: ['cold', 'freeze'] },
+      { char: '😳', name: 'flushed face', keywords: ['embarrassed', 'blush'] },
+      { char: '🤪', name: 'zany', keywords: ['crazy'] },
+      { char: '😵', name: 'dizzy face', keywords: ['dizzy', 'confused'] },
+      { char: '🥴', name: 'woozy face', keywords: ['dizzy', 'drunk'] },
+      { char: '😠', name: 'angry face', keywords: ['angry', 'mad'] },
+      { char: '😡', name: 'pouting face', keywords: ['angry', 'rage'] },
+      { char: '🤬', name: 'face with symbols on mouth', keywords: ['angry', 'swear'] },
+      { char: '😷', name: 'face with medical mask', keywords: ['sick', 'mask'] },
+      { char: '🤒', name: 'face with thermometer', keywords: ['sick', 'fever'] },
+      { char: '🤕', name: 'face with head-bandage', keywords: ['hurt', 'injured'] },
+      { char: '🤢', name: 'nauseated face', keywords: ['sick', 'gross'] },
+      { char: '🤮', name: 'face vomiting', keywords: ['sick', 'gross'] },
+      { char: '🤧', name: 'sneezing face', keywords: ['sick', 'sneeze'] },
+      { char: '😇', name: 'angel', keywords: ['innocent'] },
+      { char: '🥳', name: 'partying face', keywords: ['party', 'celebrate'] },
+      { char: '🥸', name: 'disguised face', keywords: ['disguise', 'incognito'] },
+      { char: '😎', name: 'smiling face with sunglasses', keywords: ['cool'] },
+      { char: '🤓', name: 'nerd face', keywords: ['nerd', 'geek'] },
+      { char: '🧐', name: 'face with monocle', keywords: ['inspect', 'curious'] },
+      { char: '👋', name: 'waving hand', keywords: ['wave', 'hello', 'bye'] },
+      { char: '👍', name: 'thumbs up', keywords: ['like', 'yes', 'approve'] },
+      { char: '👎', name: 'thumbs down', keywords: ['dislike', 'no'] },
+      { char: '👏', name: 'clapping hands', keywords: ['applause', 'clap', 'bravo'] },
+      { char: '🙌', name: 'raising hands', keywords: ['celebrate', 'hooray'] },
+      { char: '🙏', name: 'folded hands', keywords: ['please', 'pray', 'thanks'] },
+      { char: '💪', name: 'flexed biceps', keywords: ['strong', 'muscle'] },
+      { char: '👌', name: 'OK hand', keywords: ['ok', 'perfect'] },
+      { char: '✌️', name: 'victory hand', keywords: ['peace', 'victory'] },
+      { char: '🤝', name: 'handshake', keywords: ['deal', 'agreement'] },
+      { char: '❤️', name: 'red heart', keywords: ['love', 'heart'] },
+      { char: '💔', name: 'broken heart', keywords: ['heartbreak', 'sad'] },
+    ],
+  },
+  {
+    id: 'nature',
+    label: 'Animals & Nature',
+    emojis: [
+      { char: '🐶', name: 'dog face', keywords: ['dog', 'puppy', 'pet'] },
+      { char: '🐱', name: 'cat face', keywords: ['cat', 'kitten', 'pet'] },
+      { char: '🐭', name: 'mouse face', keywords: ['mouse'] },
+      { char: '🐹', name: 'hamster', keywords: ['hamster', 'pet'] },
+      { char: '🐰', name: 'rabbit face', keywords: ['rabbit', 'bunny'] },
+      { char: '🦊', name: 'fox', keywords: ['fox'] },
+      { char: '🐻', name: 'bear', keywords: ['bear'] },
+      { char: '🐼', name: 'panda', keywords: ['panda'] },
+      { char: '🐨', name: 'koala', keywords: ['koala'] },
+      { char: '🐯', name: 'tiger face', keywords: ['tiger'] },
+      { char: '🦁', name: 'lion', keywords: ['lion'] },
+      { char: '🐮', name: 'cow face', keywords: ['cow'] },
+      { char: '🐷', name: 'pig face', keywords: ['pig'] },
+      { char: '🐸', name: 'frog', keywords: ['frog'] },
+      { char: '🐵', name: 'monkey face', keywords: ['monkey'] },
+      { char: '🐔', name: 'chicken', keywords: ['chicken'] },
+      { char: '🐧', name: 'penguin', keywords: ['penguin'] },
+      { char: '🐦', name: 'bird', keywords: ['bird'] },
+      { char: '🦄', name: 'unicorn', keywords: ['unicorn', 'magic'] },
+      { char: '🐝', name: 'honeybee', keywords: ['bee', 'insect'] },
+      { char: '🐢', name: 'turtle', keywords: ['turtle'] },
+      { char: '🐍', name: 'snake', keywords: ['snake'] },
+      { char: '🐳', name: 'spouting whale', keywords: ['whale', 'ocean'] },
+      { char: '🐬', name: 'dolphin', keywords: ['dolphin', 'ocean'] },
+      { char: '🐠', name: 'tropical fish', keywords: ['fish', 'ocean'] },
+      { char: '🦋', name: 'butterfly', keywords: ['butterfly'] },
+      { char: '🌸', name: 'cherry blossom', keywords: ['flower', 'spring'] },
+      { char: '🌹', name: 'rose', keywords: ['flower', 'rose'] },
+      { char: '🌻', name: 'sunflower', keywords: ['flower', 'sun'] },
+      { char: '🌵', name: 'cactus', keywords: ['plant', 'desert'] },
+      { char: '🌲', name: 'evergreen tree', keywords: ['tree', 'forest'] },
+      { char: '🍀', name: 'four leaf clover', keywords: ['luck', 'clover'] },
+      { char: '🌈', name: 'rainbow', keywords: ['rainbow', 'colorful'] },
+      { char: '☀️', name: 'sun', keywords: ['sun', 'sunny'] },
+      { char: '⭐', name: 'star', keywords: ['star'] },
+      { char: '🌙', name: 'crescent moon', keywords: ['moon', 'night'] },
+      { char: '☁️', name: 'cloud', keywords: ['cloud', 'weather'] },
+      { char: '⚡', name: 'high voltage', keywords: ['lightning', 'zap', 'energy'] },
+      { char: '🔥', name: 'fire', keywords: ['fire', 'hot', 'lit'] },
+      { char: '❄️', name: 'snowflake', keywords: ['snow', 'cold', 'winter'] },
+    ],
+  },
+  {
+    id: 'food',
+    label: 'Food & Drink',
+    emojis: [
+      { char: '🍎', name: 'red apple', keywords: ['apple', 'fruit'] },
+      { char: '🍊', name: 'tangerine', keywords: ['orange', 'fruit'] },
+      { char: '🍋', name: 'lemon', keywords: ['lemon', 'fruit'] },
+      { char: '🍌', name: 'banana', keywords: ['banana', 'fruit'] },
+      { char: '🍉', name: 'watermelon', keywords: ['watermelon', 'fruit'] },
+      { char: '🍇', name: 'grapes', keywords: ['grapes', 'fruit'] },
+      { char: '🍓', name: 'strawberry', keywords: ['strawberry', 'fruit'] },
+      { char: '🍑', name: 'peach', keywords: ['peach', 'fruit'] },
+      { char: '🥝', name: 'kiwi fruit', keywords: ['kiwi', 'fruit'] },
+      { char: '🍍', name: 'pineapple', keywords: ['pineapple', 'fruit'] },
+      { char: '🥑', name: 'avocado', keywords: ['avocado'] },
+      { char: '🍅', name: 'tomato', keywords: ['tomato'] },
+      { char: '🌽', name: 'ear of corn', keywords: ['corn'] },
+      { char: '🥕', name: 'carrot', keywords: ['carrot'] },
+      { char: '🍕', name: 'pizza', keywords: ['pizza', 'food'] },
+      { char: '🍔', name: 'hamburger', keywords: ['burger', 'food'] },
+      { char: '🍟', name: 'french fries', keywords: ['fries', 'food'] },
+      { char: '🌭', name: 'hot dog', keywords: ['hotdog', 'food'] },
+      { char: '🥪', name: 'sandwich', keywords: ['sandwich', 'food'] },
+      { char: '🌮', name: 'taco', keywords: ['taco', 'food'] },
+      { char: '🍣', name: 'sushi', keywords: ['sushi', 'food'] },
+      { char: '🍜', name: 'steaming bowl', keywords: ['noodles', 'ramen', 'food'] },
+      { char: '🍝', name: 'spaghetti', keywords: ['pasta', 'food'] },
+      { char: '🍦', name: 'soft ice cream', keywords: ['icecream', 'dessert'] },
+      { char: '🍩', name: 'doughnut', keywords: ['donut', 'dessert'] },
+      { char: '🍪', name: 'cookie', keywords: ['cookie', 'dessert'] },
+      { char: '🎂', name: 'birthday cake', keywords: ['cake', 'birthday'] },
+      { char: '🍰', name: 'shortcake', keywords: ['cake', 'dessert'] },
+      { char: '🍫', name: 'chocolate bar', keywords: ['chocolate', 'dessert'] },
+      { char: '☕', name: 'hot beverage', keywords: ['coffee', 'tea'] },
+      { char: '🍵', name: 'teacup without handle', keywords: ['tea'] },
+      { char: '🍺', name: 'beer mug', keywords: ['beer', 'drink'] },
+      { char: '🍷', name: 'wine glass', keywords: ['wine', 'drink'] },
+      { char: '🥂', name: 'clinking glasses', keywords: ['cheers', 'toast', 'drink'] },
+    ],
+  },
+  {
+    id: 'activities',
+    label: 'Activities',
+    emojis: [
+      { char: '⚽', name: 'soccer ball', keywords: ['soccer', 'football', 'sport'] },
+      { char: '🏀', name: 'basketball', keywords: ['basketball', 'sport'] },
+      { char: '🏈', name: 'american football', keywords: ['football', 'sport'] },
+      { char: '⚾', name: 'baseball', keywords: ['baseball', 'sport'] },
+      { char: '🎾', name: 'tennis', keywords: ['tennis', 'sport'] },
+      { char: '🏐', name: 'volleyball', keywords: ['volleyball', 'sport'] },
+      { char: '🏉', name: 'rugby football', keywords: ['rugby', 'sport'] },
+      { char: '🎱', name: 'pool 8 ball', keywords: ['billiards', 'pool'] },
+      { char: '🏓', name: 'ping pong', keywords: ['tabletennis', 'sport'] },
+      { char: '🏸', name: 'badminton', keywords: ['badminton', 'sport'] },
+      { char: '🥅', name: 'goal net', keywords: ['goal', 'sport'] },
+      { char: '⛳', name: 'flag in hole', keywords: ['golf'] },
+      { char: '🏹', name: 'bow and arrow', keywords: ['archery'] },
+      { char: '🎣', name: 'fishing pole', keywords: ['fishing'] },
+      { char: '🤿', name: 'diving mask', keywords: ['diving', 'snorkel'] },
+      { char: '🥊', name: 'boxing glove', keywords: ['boxing'] },
+      { char: '🥋', name: 'martial arts uniform', keywords: ['karate', 'judo'] },
+      { char: '🎽', name: 'running shirt', keywords: ['running', 'race'] },
+      { char: '🛹', name: 'skateboard', keywords: ['skateboard'] },
+      { char: '🛼', name: 'roller skate', keywords: ['skating'] },
+      { char: '🎿', name: 'skis', keywords: ['ski', 'snow'] },
+      { char: '⛸️', name: 'ice skate', keywords: ['iceskating'] },
+      { char: '🥌', name: 'curling stone', keywords: ['curling'] },
+      { char: '🎯', name: 'direct hit', keywords: ['target', 'dart', 'goal'] },
+      { char: '🎮', name: 'video game', keywords: ['gaming', 'controller'] },
+      { char: '🎲', name: 'game die', keywords: ['dice', 'game'] },
+      { char: '🧩', name: 'puzzle piece', keywords: ['puzzle'] },
+      { char: '🎨', name: 'artist palette', keywords: ['art', 'paint'] },
+      { char: '🎭', name: 'performing arts', keywords: ['theater', 'drama'] },
+      { char: '🎪', name: 'circus tent', keywords: ['circus'] },
+      { char: '🎬', name: 'clapper board', keywords: ['movie', 'film'] },
+      { char: '🎤', name: 'microphone', keywords: ['sing', 'music'] },
+      { char: '🎧', name: 'headphone', keywords: ['music', 'audio'] },
+      { char: '🎼', name: 'musical score', keywords: ['music'] },
+      { char: '🎹', name: 'musical keyboard', keywords: ['piano', 'music'] },
+      { char: '🥁', name: 'drum', keywords: ['drum', 'music'] },
+      { char: '🎸', name: 'guitar', keywords: ['guitar', 'music'] },
+      { char: '🏆', name: 'trophy', keywords: ['trophy', 'award', 'win'] },
+      { char: '🥇', name: 'gold medal', keywords: ['medal', 'first', 'win'] },
+    ],
+  },
+  {
+    id: 'travel',
+    label: 'Travel & Places',
+    emojis: [
+      { char: '🚗', name: 'car', keywords: ['car', 'drive'] },
+      { char: '🚕', name: 'taxi', keywords: ['taxi', 'cab'] },
+      { char: '🚌', name: 'bus', keywords: ['bus'] },
+      { char: '🚓', name: 'police car', keywords: ['police'] },
+      { char: '🚑', name: 'ambulance', keywords: ['ambulance'] },
+      { char: '🚒', name: 'fire engine', keywords: ['firetruck'] },
+      { char: '🚲', name: 'bicycle', keywords: ['bike', 'cycle'] },
+      { char: '🛵', name: 'motor scooter', keywords: ['scooter'] },
+      { char: '✈️', name: 'airplane', keywords: ['flight', 'travel', 'plane'] },
+      { char: '🚀', name: 'rocket', keywords: ['rocket', 'launch', 'space'] },
+      { char: '🚁', name: 'helicopter', keywords: ['helicopter'] },
+      { char: '⛵', name: 'sailboat', keywords: ['boat', 'sailing'] },
+      { char: '🚢', name: 'ship', keywords: ['ship', 'cruise'] },
+      { char: '🚂', name: 'locomotive', keywords: ['train'] },
+      { char: '🚆', name: 'train', keywords: ['train', 'rail'] },
+      { char: '🚊', name: 'tram', keywords: ['tram'] },
+      { char: '🗺️', name: 'world map', keywords: ['map', 'travel'] },
+      { char: '🗽', name: 'statue of liberty', keywords: ['newyork', 'landmark'] },
+      { char: '🗼', name: 'tokyo tower', keywords: ['tower', 'landmark'] },
+      { char: '🏰', name: 'castle', keywords: ['castle'] },
+      { char: '🏯', name: 'japanese castle', keywords: ['castle', 'japan'] },
+      { char: '🏟️', name: 'stadium', keywords: ['stadium'] },
+      { char: '🎡', name: 'ferris wheel', keywords: ['carnival'] },
+      { char: '🎢', name: 'roller coaster', keywords: ['coaster'] },
+      { char: '⛱️', name: 'umbrella on ground', keywords: ['beach'] },
+      { char: '🏖️', name: 'beach with umbrella', keywords: ['beach', 'vacation'] },
+      { char: '🏝️', name: 'desert island', keywords: ['island', 'beach'] },
+      { char: '⛰️', name: 'mountain', keywords: ['mountain'] },
+      { char: '🏔️', name: 'snow-capped mountain', keywords: ['mountain', 'snow'] },
+      { char: '🌋', name: 'volcano', keywords: ['volcano'] },
+      { char: '🏕️', name: 'camping', keywords: ['camp', 'tent'] },
+      { char: '🏙️', name: 'cityscape', keywords: ['city'] },
+      { char: '🌃', name: 'night with stars', keywords: ['night', 'city'] },
+      { char: '🌍', name: 'globe showing europe-africa', keywords: ['world', 'earth', 'globe'] },
+    ],
+  },
+  {
+    id: 'objects',
+    label: 'Objects',
+    emojis: [
+      { char: '💡', name: 'light bulb', keywords: ['idea', 'light', 'bulb'] },
+      { char: '📌', name: 'pushpin', keywords: ['pin', 'note'] },
+      { char: '📎', name: 'paperclip', keywords: ['attach', 'clip'] },
+      { char: '📝', name: 'memo', keywords: ['note', 'write'] },
+      { char: '📋', name: 'clipboard', keywords: ['list', 'tasks'] },
+      { char: '📁', name: 'file folder', keywords: ['folder', 'files'] },
+      { char: '📂', name: 'open file folder', keywords: ['folder', 'files'] },
+      { char: '🗂️', name: 'card index dividers', keywords: ['organize', 'files'] },
+      { char: '📅', name: 'calendar', keywords: ['calendar', 'date'] },
+      { char: '📆', name: 'tear-off calendar', keywords: ['calendar', 'date'] },
+      { char: '📊', name: 'bar chart', keywords: ['chart', 'graph', 'stats'] },
+      { char: '📈', name: 'chart increasing', keywords: ['growth', 'stats'] },
+      { char: '📉', name: 'chart decreasing', keywords: ['decline', 'stats'] },
+      { char: '💻', name: 'laptop', keywords: ['computer', 'laptop'] },
+      { char: '🖥️', name: 'desktop computer', keywords: ['computer', 'monitor'] },
+      { char: '⌨️', name: 'keyboard', keywords: ['keyboard', 'type'] },
+      { char: '🖱️', name: 'computer mouse', keywords: ['mouse'] },
+      { char: '📱', name: 'mobile phone', keywords: ['phone', 'mobile'] },
+      { char: '☎️', name: 'telephone', keywords: ['phone', 'call'] },
+      { char: '🔋', name: 'battery', keywords: ['battery', 'power'] },
+      { char: '🔌', name: 'electric plug', keywords: ['plug', 'power'] },
+      { char: '💾', name: 'floppy disk', keywords: ['save', 'disk'] },
+      { char: '💿', name: 'optical disk', keywords: ['cd', 'disk'] },
+      { char: '🔍', name: 'magnifying glass', keywords: ['search', 'find', 'zoom'] },
+      { char: '🔒', name: 'locked', keywords: ['lock', 'secure', 'private'] },
+      { char: '🔓', name: 'unlocked', keywords: ['unlock', 'open'] },
+      { char: '🔑', name: 'key', keywords: ['key', 'password'] },
+      { char: '🔨', name: 'hammer', keywords: ['tool', 'build', 'fix'] },
+      { char: '🛠️', name: 'hammer and wrench', keywords: ['tools', 'fix', 'settings'] },
+      { char: '⚙️', name: 'gear', keywords: ['settings', 'config'] },
+      { char: '🧰', name: 'toolbox', keywords: ['tools'] },
+      { char: '🔗', name: 'link', keywords: ['link', 'chain', 'url'] },
+      { char: '📦', name: 'package', keywords: ['box', 'delivery', 'package'] },
+      { char: '💰', name: 'money bag', keywords: ['money', 'rich'] },
+      { char: '💳', name: 'credit card', keywords: ['card', 'payment'] },
+      { char: '🎁', name: 'wrapped gift', keywords: ['gift', 'present'] },
+      { char: '🔔', name: 'bell', keywords: ['notification', 'alert'] },
+      { char: '📢', name: 'loudspeaker', keywords: ['announce', 'megaphone'] },
+      { char: '🧭', name: 'compass', keywords: ['compass', 'direction'] },
+      { char: '⏰', name: 'alarm clock', keywords: ['clock', 'alarm', 'time'] },
+      { char: '⏳', name: 'hourglass not done', keywords: ['time', 'wait'] },
+    ],
+  },
+  {
+    id: 'symbols',
+    label: 'Symbols',
+    emojis: [
+      { char: '✅', name: 'check mark button', keywords: ['check', 'done', 'yes'] },
+      { char: '❌', name: 'cross mark', keywords: ['no', 'wrong', 'x'] },
+      { char: '❗', name: 'exclamation mark', keywords: ['important', 'warning'] },
+      { char: '❓', name: 'question mark', keywords: ['question', 'help'] },
+      { char: '⚠️', name: 'warning', keywords: ['warning', 'caution', 'alert'] },
+      { char: '🚫', name: 'prohibited', keywords: ['no', 'banned', 'forbidden'] },
+      { char: '♻️', name: 'recycling symbol', keywords: ['recycle', 'green'] },
+      { char: '💯', name: 'hundred points', keywords: ['100', 'perfect'] },
+      { char: '✨', name: 'sparkles', keywords: ['sparkle', 'new', 'shiny'] },
+      { char: '⭐', name: 'star', keywords: ['star', 'favorite'] },
+      { char: '🌟', name: 'glowing star', keywords: ['star', 'shine'] },
+      { char: '💫', name: 'dizzy', keywords: ['star', 'sparkle'] },
+      { char: '🔴', name: 'red circle', keywords: ['red', 'circle', 'dot'] },
+      { char: '🟠', name: 'orange circle', keywords: ['orange', 'circle'] },
+      { char: '🟡', name: 'yellow circle', keywords: ['yellow', 'circle'] },
+      { char: '🟢', name: 'green circle', keywords: ['green', 'circle'] },
+      { char: '🔵', name: 'blue circle', keywords: ['blue', 'circle'] },
+      { char: '🟣', name: 'purple circle', keywords: ['purple', 'circle'] },
+      { char: '⚫', name: 'black circle', keywords: ['black', 'circle'] },
+      { char: '⚪', name: 'white circle', keywords: ['white', 'circle'] },
+      { char: '🔺', name: 'red triangle pointed up', keywords: ['triangle', 'warning'] },
+      { char: '💠', name: 'diamond with a dot', keywords: ['diamond'] },
+      { char: '🔶', name: 'large orange diamond', keywords: ['diamond'] },
+      { char: '➕', name: 'plus', keywords: ['add', 'plus'] },
+      { char: '➖', name: 'minus', keywords: ['subtract', 'minus'] },
+      { char: '➗', name: 'divide', keywords: ['divide'] },
+      { char: '✖️', name: 'multiply', keywords: ['multiply', 'times'] },
+      { char: '♾️', name: 'infinity', keywords: ['infinite', 'infinity'] },
+      { char: '💤', name: 'zzz', keywords: ['sleep', 'tired'] },
+      { char: '💬', name: 'speech balloon', keywords: ['chat', 'comment', 'talk'] },
+      { char: '💭', name: 'thought balloon', keywords: ['think', 'idea'] },
+    ],
+  },
+]
+
+/** Flat lookup used by search across all categories. */
+export const ALL_EMOJIS: EmojiEntry[] = EMOJI_CATEGORIES.flatMap((c) => c.emojis)
diff --git a/packages/react/src/ui/index.ts b/packages/react/src/ui/index.ts
index 12df592..a52dd1e 100644
--- a/packages/react/src/ui/index.ts
+++ b/packages/react/src/ui/index.ts
@@ -13,5 +13,8 @@ export { ColorPickerPanel } from './ColorPickerPanel'
 export { IconEmojiPicker } from './IconEmojiPicker'
 export type { IconEmojiPickerHandle, IconEmojiPickerProps } from './IconEmojiPicker'
 export { IconValueDisplay } from './IconValueDisplay'
+export { EmojiPicker } from './EmojiPicker'
+export type { EmojiPickerProps } from './EmojiPicker'
 export * from './colorPresets'
 export * from './emojiPresets'
+export * from './emojiData'
diff --git a/packages/vue/src/components/BlockEditor.vue b/packages/vue/src/components/BlockEditor.vue
index 7b9460b..fb7ff8e 100644
--- a/packages/vue/src/components/BlockEditor.vue
+++ b/packages/vue/src/components/BlockEditor.vue
@@ -33,9 +33,12 @@ import {
 import type { TextPoint, TextRangeSelection, Block, BlockType, InlineSpan, MarkName, TableCellCoord, TableCellAlign, TableStyle } from '@xproeditor/core'
 import EditorBlockItem from './EditorBlockItem.vue'
 import EditorBubbleToolbar from './EditorBubbleToolbar.vue'
+import EditorEmojiTriggerMenu from './EditorEmojiTriggerMenu.vue'
 import type { FormatToolbarAlign, FormatToolbarState } from './EditorFormatToolbar.vue'
 import EditorSlashMenu from './EditorSlashMenu.vue'
 import type {SlashItem} from './EditorSlashMenu.vue';
+import { EmojiPicker } from '../ui'
+import { ALL_EMOJIS } from '../ui/emojiData'
 
 const props = defineProps<{
   /** Live block array — the editor mutates it in place. */
@@ -632,6 +635,75 @@ selectBlock(newBlock.id)
 }
 }
 
+// ─── Inline emoji trigger (":" — Slack/Discord-style) ──────────────────────────
+
+interface EmojiTriggerState {
+  blockId: string
+  index: number
+  query: string
+  position: { x: number; y: number; top?: number }
+}
+
+const emojiTriggerState = ref<EmojiTriggerState | null>(null)
+
+function closeEmojiTrigger() {
+  emojiTriggerState.value = null
+}
+
+function updateEmojiTrigger(block: Block, spans: InlineSpan[], caret: number | null) {
+  const text = spansToText(spans)
+  const state = emojiTriggerState.value
+
+  if (state && state.blockId === block.id) {
+    if (caret === null || caret <= state.index || text[state.index] !== ':') {
+      closeEmojiTrigger()
+
+      return
+    }
+
+    const query = text.slice(state.index + 1, caret)
+
+    if (/\s/.test(query) || query.length > 20) {
+      closeEmojiTrigger()
+
+      return
+    }
+
+    state.query = query
+
+    return
+  }
+
+  if (caret !== null && caret > 0 && text[caret - 1] === ':') {
+    const before = caret >= 2 ? text[caret - 2] : ''
+
+    if (before === '' || /\s/.test(before)) {
+      emojiTriggerState.value = { blockId: block.id, index: caret - 1, query: '', position: slashPosition() }
+    }
+  }
+}
+
+function onEmojiTriggerSelect(emoji: string) {
+  const state = emojiTriggerState.value
+
+  if (!state) {
+return
+}
+
+  const block = byId(state.blockId)
+  closeEmojiTrigger()
+
+  if (!block) {
+return
+}
+
+  const removeEnd = state.index + 1 + state.query.length
+  const withoutTrigger = deleteRangeInSpans(block.content, state.index, removeEnd)
+  block.content = insertSpansAt(withoutTrigger, state.index, [{ text: emoji }])
+  pushHistory(true)
+  focusBlock(block.id, state.index + emoji.length)
+}
+
 // ─── Markdown shortcuts ───────────────────────────────────────────────────────
 
 const MD_PATTERNS: Array<{ prefix: string; type: BlockType }> = [
@@ -707,11 +779,19 @@ return
 
   if (tryMarkdownShortcut(block, spans, caret)) {
     closeSlash()
+    closeEmojiTrigger()
 
     return
   }
 
   updateSlash(block, spans, caret)
+
+  if (slashState.value) {
+    closeEmojiTrigger()
+  } else {
+    updateEmojiTrigger(block, spans, caret)
+  }
+
   pushHistory()
 }
 
@@ -2301,7 +2381,62 @@ function handleSelectAllShortcut(target: HTMLElement) {
 }
 
 function onKeydownCapture(e: KeyboardEvent) {
-  if (props.readonly || isNativeInputTarget(e.target)) {
+  if (props.readonly) {
+return
+}
+
+  // Slash menu lives inside the contenteditable block being typed into, so
+  // this must run before the isNativeInputTarget bail-out below (which
+  // exists to let text blocks handle their own keys normally).
+  if (slashState.value) {
+    if (e.key === 'ArrowDown') {
+ e.preventDefault(); e.stopPropagation(); slashMenuRef.value?.move(1);
+
+ return
+}
+
+    if (e.key === 'ArrowUp') {
+ e.preventDefault(); e.stopPropagation(); slashMenuRef.value?.move(-1);
+
+ return
+}
+
+    if (e.key === 'Enter' || e.key === 'Tab') {
+ e.preventDefault(); e.stopPropagation(); slashMenuRef.value?.confirm();
+
+ return
+}
+
+    if (e.key === 'Escape') {
+ e.preventDefault(); e.stopPropagation(); closeSlash();
+
+ return
+}
+  }
+
+  if (emojiTriggerState.value) {
+    if (e.key === 'Enter' || e.key === 'Tab') {
+      e.preventDefault(); e.stopPropagation()
+      const q = emojiTriggerState.value.query.toLowerCase()
+      const match = q ? ALL_EMOJIS.find(en => en.name.includes(q) || en.keywords.some(k => k.includes(q))) : null
+
+      if (match) {
+onEmojiTriggerSelect(match.char)
+} else {
+closeEmojiTrigger()
+}
+
+      return
+    }
+
+    if (e.key === 'Escape') {
+ e.preventDefault(); e.stopPropagation(); closeEmojiTrigger();
+
+ return
+}
+  }
+
+  if (isNativeInputTarget(e.target)) {
 return
 }
 
@@ -2386,31 +2521,7 @@ undo()
     return
   }
 
-  if (slashState.value) {
-    if (e.key === 'ArrowDown') {
- e.preventDefault(); e.stopPropagation(); slashMenuRef.value?.move(1);
-
- return 
-}
-
-    if (e.key === 'ArrowUp') {
- e.preventDefault(); e.stopPropagation(); slashMenuRef.value?.move(-1);
-
- return 
-}
-
-    if (e.key === 'Enter' || e.key === 'Tab') {
- e.preventDefault(); e.stopPropagation(); slashMenuRef.value?.confirm();
-
- return 
-}
-
-    if (e.key === 'Escape') {
- e.preventDefault(); e.stopPropagation(); closeSlash();
-
- return 
-}
-  } else if (e.key === 'Escape' && bubble.value) {
+  if (e.key === 'Escape' && bubble.value) {
     bubble.value = null
   }
 }
@@ -2530,6 +2641,10 @@ function onDocMouseDown(e: MouseEvent) {
 
   if (slashState.value && !target.closest('.fixed')) {
 closeSlash()
+}
+
+  if (emojiTriggerState.value && !target.closest('.fixed')) {
+closeEmojiTrigger()
 }
 
   if (selectedBlockId.value && !target.closest(`[data-block-id="${selectedBlockId.value}"]`)) {
@@ -2693,10 +2808,20 @@ focusBlock(last.id, 'end')
       :query="slashState.query"
       :position="slashState.position"
       :dir="editorDir ?? 'ltr'"
+      :theme-source="rootEl"
       @select="onSlashSelect"
       @close="closeSlash"
     />
 
+    <EditorEmojiTriggerMenu
+      v-if="emojiTriggerState && !readonly"
+      :query="emojiTriggerState.query"
+      :position="emojiTriggerState.position"
+      :dir="editorDir ?? 'ltr'"
+      :theme-source="rootEl"
+      @select="onEmojiTriggerSelect"
+    />
+
     <EditorBubbleToolbar
       v-if="showBubbleToolbar && bubble && !readonly"
       :position="bubble.position"
@@ -2705,6 +2830,7 @@ focusBlock(last.id, 'end')
       :current-color="bubble.currentColor"
       :current-highlight="bubble.currentHighlight"
       :block-type="bubble.blockType"
+      :theme-source="rootEl"
       @mark="onBubbleMark"
       @turn-into="onBubbleTurnInto"
     />
diff --git a/packages/vue/src/components/DocRenderer.vue b/packages/vue/src/components/DocRenderer.vue
index e26033a..6a8a76f 100644
--- a/packages/vue/src/components/DocRenderer.vue
+++ b/packages/vue/src/components/DocRenderer.vue
@@ -296,6 +296,29 @@ function safeVideoEmbedUrl(block: Block): string {
         <span v-if="block.props.size" class="db-file-size">{{ formatFileSize(block.props.size) }}</span>
       </a>
 
+      <!-- Button -->
+      <div
+        v-else-if="block.type === 'button'"
+        class="db-button-row"
+        :style="{ justifyContent: block.props.align === 'center' ? 'center' : block.props.align === 'right' ? 'flex-end' : 'flex-start' }"
+      >
+        <a
+          v-if="block.props.url"
+          :href="block.props.url"
+          :target="block.props.openInNewTab ? '_blank' : undefined"
+          :rel="block.props.openInNewTab ? 'noopener noreferrer' : undefined"
+          class="db-button"
+          :class="`db-button--${block.props.buttonStyle ?? 'primary'}`"
+          v-html="inlineHtml(block) || 'Button'"
+        />
+        <span
+          v-else
+          class="db-button"
+          :class="`db-button--${block.props.buttonStyle ?? 'primary'}`"
+          v-html="inlineHtml(block) || 'Button'"
+        />
+      </div>
+
       <!-- Table -->
       <div
         v-else-if="block.type === 'table' && block.props.table"
@@ -433,11 +456,11 @@ function safeVideoEmbedUrl(block: Block): string {
   margin-top: 0.45em;
   border-radius: 4px;
   border: 1.5px solid var(--xpe-border);
-  color: white;
 }
 .db-todo-checked {
   background: var(--xpe-primary);
   border-color: var(--xpe-primary);
+  color: var(--xpe-primary-foreground);
 }
 .db-todo-box svg { width: 10px; height: 10px; }
 
@@ -569,6 +592,14 @@ function safeVideoEmbedUrl(block: Block): string {
 .db-file-name { font-size: 0.9em; font-weight: 500; flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
 .db-file-size { font-size: 0.8em; color: var(--xpe-muted-foreground); flex-shrink: 0; }
 
+/* --- Button --- */
+.db-button-row { display: flex; margin: 0.75em 0; }
+.db-button { display: inline-flex; align-items: center; justify-content: center; min-width: 64px; padding: 0.5em 1.1em; border-radius: var(--xpe-radius, 0.6rem); font-size: 0.9em; font-weight: 600; text-decoration: none; cursor: pointer; border: 1px solid transparent; transition: opacity 0.12s; }
+.db-button:hover { opacity: 0.88; }
+.db-button--primary { background: var(--xpe-primary); color: var(--xpe-primary-foreground); }
+.db-button--outline { background: transparent; border-color: var(--xpe-border); color: var(--xpe-foreground); }
+.db-button--ghost { background: var(--xpe-muted); color: var(--xpe-foreground); }
+
 /* --- Table --- */
 .db-table-wrap { overflow-x: auto; margin: 1.25em 0; }
 .db-table {
diff --git a/packages/vue/src/components/EditorBlockItem.vue b/packages/vue/src/components/EditorBlockItem.vue
index 10fd777..627c0bb 100644
--- a/packages/vue/src/components/EditorBlockItem.vue
+++ b/packages/vue/src/components/EditorBlockItem.vue
@@ -12,6 +12,7 @@ import {
   IconValueDisplay,
 } from '../ui'
 import EditorAudioBlock from './EditorAudioBlock.vue'
+import EditorButtonBlock from './EditorButtonBlock.vue'
 import EditorCodeBlock from './EditorCodeBlock.vue'
 import EditorFileBlock from './EditorFileBlock.vue'
 import EditorImageBlock from './EditorImageBlock.vue'
@@ -69,7 +70,7 @@ const emit = defineEmits<{
 
 const CALLOUT_COLORS = ['#f8fafc', '#fefce8', '#fff7ed', '#fef2f2', '#f0fdf4', '#eff6ff', '#faf5ff']
 
-const inner = ref<InstanceType<typeof EditorTextBlock> | InstanceType<typeof EditorCodeBlock> | InstanceType<typeof EditorTableBlock> | null>(null)
+const inner = ref<InstanceType<typeof EditorTextBlock> | InstanceType<typeof EditorCodeBlock> | InstanceType<typeof EditorTableBlock> | InstanceType<typeof EditorButtonBlock> | null>(null)
 const calloutIconPickerRef = ref<InstanceType<typeof IconEmojiPicker> | null>(null)
 const showCalloutColors = ref(false)
 
@@ -297,12 +298,12 @@ defineExpose({
             <span v-else-if="block.type === 'numbered_list_item'" class="text-[var(--xpe-foreground)] text-[14px] leading-snug tabular-nums">{{ number ?? 1 }}.</span>
             <button
               v-else-if="block.type === 'to_do'"
-              class="w-[15px] h-[15px] mt-1 rounded-[4px] border flex items-center justify-center transition-colors"
+              class="appearance-none w-[15px] h-[15px] mt-1 rounded-[4px] border flex items-center justify-center transition-colors"
               :class="block.props.checked ? 'bg-[var(--xpe-primary)] border-[var(--xpe-primary)]' : 'border-[var(--xpe-border)] hover:border-[var(--xpe-ring)] bg-[var(--xpe-surface)]'"
               :disabled="readonly"
               @click="emit('patch', { checked: !block.props.checked })"
             >
-              <svg v-if="block.props.checked" class="w-2.5 h-2.5 text-white" fill="none" stroke="currentColor" stroke-width="3" viewBox="0 0 24 24"><path d="M5 13l4 4L19 7" /></svg>
+              <svg v-if="block.props.checked" width="10" height="10" class="shrink-0 text-[var(--xpe-primary-foreground)]" fill="none" stroke="currentColor" stroke-width="3" viewBox="0 0 24 24"><path d="M5 13l4 4L19 7" /></svg>
             </button>
             <button
               v-else
@@ -311,7 +312,8 @@ defineExpose({
               @click="emit('patch', { collapsed: !block.props.collapsed })"
             >
               <ChevronRight
-                class="h-3.5 w-3.5 transition-transform"
+                :size="14"
+                class="shrink-0 transition-transform"
                 :class="{
                   'rotate-90': !block.props.collapsed,
                   'ebi-chevron-rtl': isRtl,
@@ -422,6 +424,27 @@ defineExpose({
           <hr class="border-[var(--xpe-border)] rounded" :class="{ '!border-[var(--xpe-ring)]': selected }" />
         </div>
 
+        <!-- Button -->
+        <EditorButtonBlock
+          v-else-if="block.type === 'button'"
+          ref="inner"
+          :block="block"
+          :readonly="readonly"
+          @input="(s, c) => emit('input', s, c)"
+          @enter="o => emit('enter', o)"
+          @backspace-start="emit('backspaceStart')"
+          @delete-end="emit('deleteEnd')"
+          @arrow-up="emit('arrowUp')"
+          @arrow-down="emit('arrowDown')"
+          @tab="s => emit('tab', s)"
+          @format="m => emit('format', m)"
+          @pasted="p => emit('pasted', p)"
+          @focus="emit('focus')"
+          @selection-pointer-down="p => emit('selectionPointerDown', p)"
+          @patch="p => emit('patch', p)"
+          @select="emit('select')"
+        />
+
         <!-- Plain text blocks -->
         <EditorTextBlock
           v-else
diff --git a/packages/vue/src/components/EditorBubbleToolbar.vue b/packages/vue/src/components/EditorBubbleToolbar.vue
index a954deb..b491775 100644
--- a/packages/vue/src/components/EditorBubbleToolbar.vue
+++ b/packages/vue/src/components/EditorBubbleToolbar.vue
@@ -19,7 +19,8 @@ import {
     Lightbulb,
     Underline,
 } from 'lucide-vue-next';
-import { ref, watch } from 'vue';
+import { nextTick, ref, watch } from 'vue';
+import { syncThemeVars } from '@xproeditor/core';
 import type { BlockType, MarkName } from '@xproeditor/core';
 import { Button, Input } from '../ui';
 import EditorToolbarColorPanel from './toolbar/EditorToolbarColorPanel.vue';
@@ -31,8 +32,25 @@ const props = defineProps<{
     currentColor?: string | null;
     currentHighlight?: string | null;
     blockType: BlockType;
+    /** Element still inside the editor's themed DOM scope — used to resync
+     * `--xpe-*` variables onto this toolbar once it's teleported to `<body>`. */
+    themeSource?: HTMLElement | null;
 }>();
 
+const toolbarEl = ref<HTMLElement | null>(null);
+
+watch(
+    [() => props.position, () => props.themeSource],
+    async () => {
+        await nextTick();
+
+        if (props.themeSource && toolbarEl.value) {
+            syncThemeVars(props.themeSource, toolbarEl.value);
+        }
+    },
+    { immediate: true },
+);
+
 const emit = defineEmits<{
     mark: [mark: MarkName, value: boolean | string | null];
     turnInto: [type: BlockType];
@@ -83,6 +101,7 @@ function turnIntoLabel(): string {
 <template>
     <Teleport to="body">
         <div
+            ref="toolbarEl"
             class="fixed z-[70] flex flex-col items-stretch"
             :style="{
                 left: `${position.x}px`,
diff --git a/packages/vue/src/components/EditorButtonBlock.vue b/packages/vue/src/components/EditorButtonBlock.vue
new file mode 100644
index 0000000..0c34a44
--- /dev/null
+++ b/packages/vue/src/components/EditorButtonBlock.vue
@@ -0,0 +1,186 @@
+<script setup lang="ts">
+import { Link2, SquareArrowOutUpRight } from 'lucide-vue-next'
+import { ref, computed } from 'vue'
+import type { Block, InlineSpan, MarkName } from '@xproeditor/core'
+import { Button, Input, Popover, PopoverContent, PopoverTrigger } from '../ui'
+import EditorTextBlock from './EditorTextBlock.vue'
+
+const props = defineProps<{
+  block: Block
+  readonly?: boolean
+}>()
+
+const emit = defineEmits<{
+  input: [spans: InlineSpan[], caret: number | null]
+  enter: [offsets: { start: number; end: number }]
+  backspaceStart: []
+  deleteEnd: []
+  arrowUp: []
+  arrowDown: []
+  tab: [shift: boolean]
+  format: [mark: MarkName]
+  pasted: [payload: { html: string; text: string; files: File[]; offsets: { start: number; end: number } }]
+  focus: []
+  selectionPointerDown: [payload: { shiftKey: boolean; clientX: number; clientY: number }]
+  patch: [patch: Record<string, unknown>]
+  select: []
+}>()
+
+const STYLE_TO_VARIANT: Record<string, 'default' | 'outline' | 'ghost'> = {
+  primary: 'default',
+  outline: 'outline',
+  ghost: 'ghost',
+}
+
+const ALIGN_TO_JUSTIFY: Record<string, string> = {
+  left: 'justify-start',
+  center: 'justify-center',
+  right: 'justify-end',
+}
+
+const open = ref(false)
+const variant = computed(() => STYLE_TO_VARIANT[props.block.props.buttonStyle ?? 'primary'] ?? 'default')
+const justify = computed(() => ALIGN_TO_JUSTIFY[props.block.props.align ?? 'left'] ?? 'justify-start')
+
+const STYLES = ['primary', 'outline', 'ghost'] as const
+const ALIGNS = ['left', 'center', 'right'] as const
+
+function capitalize(s: string) {
+  return s[0].toUpperCase() + s.slice(1)
+}
+
+defineExpose({
+  focusAt: (pos: number | 'start' | 'end') => textRef.value?.focusAt?.(pos),
+  getSelection: () => textRef.value?.getSelection?.() ?? null,
+  setSelection: (start: number, end?: number) => textRef.value?.setSelection?.(start, end),
+})
+
+const textRef = ref<InstanceType<typeof EditorTextBlock> | null>(null)
+</script>
+
+<template>
+  <div class="my-1 flex items-center gap-1.5" :class="justify" @click="emit('select')">
+    <div class="ebtn-preview" :class="`ebtn-preview--${variant}`">
+      <EditorTextBlock
+        ref="textRef"
+        :block="block"
+        :readonly="readonly"
+        placeholder="Button"
+        class="min-w-0 text-center outline-none"
+        @input="(s, c) => emit('input', s, c)"
+        @enter="o => emit('enter', o)"
+        @backspace-start="emit('backspaceStart')"
+        @delete-end="emit('deleteEnd')"
+        @arrow-up="emit('arrowUp')"
+        @arrow-down="emit('arrowDown')"
+        @tab="s => emit('tab', s)"
+        @format="m => emit('format', m)"
+        @pasted="p => emit('pasted', p)"
+        @focus="emit('focus')"
+        @selection-pointer-down="p => emit('selectionPointerDown', p)"
+      />
+    </div>
+
+    <Popover v-if="!readonly" v-model:open="open">
+      <PopoverTrigger>
+        <button
+          type="button"
+          class="flex h-7 w-7 shrink-0 items-center justify-center rounded-lg text-[var(--xpe-muted-foreground)] hover:bg-[var(--xpe-surface-hover)] hover:text-[var(--xpe-foreground)]"
+          title="Button link & style"
+          @click="open = !open"
+        >
+          <Link2 class="h-3.5 w-3.5" />
+        </button>
+      </PopoverTrigger>
+      <PopoverContent align="start">
+        <div class="flex flex-col gap-2.5 p-3 w-64">
+          <label class="flex flex-col gap-1">
+            <span class="text-[11px] font-medium text-[var(--xpe-muted-foreground)]">Link URL</span>
+            <Input
+              type="url"
+              placeholder="https://..."
+              :model-value="block.props.url ?? ''"
+              @input="emit('patch', { url: ($event.target as HTMLInputElement).value })"
+            />
+          </label>
+
+          <label class="flex items-center gap-2 text-[12px] text-[var(--xpe-foreground)]">
+            <input
+              type="checkbox"
+              :checked="!!block.props.openInNewTab"
+              @change="emit('patch', { openInNewTab: ($event.target as HTMLInputElement).checked })"
+            />
+            <SquareArrowOutUpRight class="h-3.5 w-3.5 text-[var(--xpe-muted-foreground)]" />
+            Open in new tab
+          </label>
+
+          <div class="flex flex-col gap-1">
+            <span class="text-[11px] font-medium text-[var(--xpe-muted-foreground)]">Style</span>
+            <div class="flex gap-1">
+              <Button
+                v-for="s in STYLES"
+                :key="s"
+                size="sm"
+                :variant="block.props.buttonStyle === s ? 'default' : 'outline'"
+                @click="emit('patch', { buttonStyle: s })"
+              >
+                {{ capitalize(s) }}
+              </Button>
+            </div>
+          </div>
+
+          <div class="flex flex-col gap-1">
+            <span class="text-[11px] font-medium text-[var(--xpe-muted-foreground)]">Alignment</span>
+            <div class="flex gap-1">
+              <Button
+                v-for="a in ALIGNS"
+                :key="a"
+                size="sm"
+                :variant="(block.props.align ?? 'left') === a ? 'default' : 'outline'"
+                @click="emit('patch', { align: a })"
+              >
+                {{ capitalize(a) }}
+              </Button>
+            </div>
+          </div>
+        </div>
+      </PopoverContent>
+    </Popover>
+  </div>
+</template>
+
+<style scoped>
+/* Mirrors ui/Button.vue's look — can't reuse its scoped .xpe-btn classes
+   directly since this is a plain div, not a <Button>, and Vue scoped CSS
+   only applies to elements rendered by the component that declares it. */
+.ebtn-preview {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 64px;
+  height: 36px;
+  padding: 0 14px;
+  border-radius: 8px;
+  border: 1px solid transparent;
+  font-weight: 500;
+  font-size: 13px;
+}
+.ebtn-preview--default {
+  background: var(--xpe-primary, #4f46e5);
+  color: var(--xpe-primary-foreground, #fff);
+}
+.ebtn-preview--outline {
+  background: var(--xpe-surface, #fff);
+  border-color: var(--xpe-border, #e5e7eb);
+  color: var(--xpe-foreground, #374151);
+}
+.ebtn-preview--ghost {
+  background: transparent;
+  color: var(--xpe-foreground, #374151);
+}
+/* EditorTextBlock's .etb always sets its own color; force the label to
+   inherit the button variant's contrast-correct text color instead. */
+.ebtn-preview :deep(.etb) {
+  color: inherit;
+}
+</style>
diff --git a/packages/vue/src/components/EditorEmojiTriggerMenu.vue b/packages/vue/src/components/EditorEmojiTriggerMenu.vue
new file mode 100644
index 0000000..438e451
--- /dev/null
+++ b/packages/vue/src/components/EditorEmojiTriggerMenu.vue
@@ -0,0 +1,83 @@
+<script setup lang="ts">
+import { nextTick, onBeforeUnmount, onMounted, ref, watch } from 'vue'
+import { lockPageScroll, syncThemeVars } from '@xproeditor/core'
+import { EmojiPicker } from '../ui'
+
+const props = defineProps<{
+  query: string
+  /** Caret anchor in viewport coordinates: menu opens below `y`, flips above `top` when needed. */
+  position: { x: number; y: number; top?: number }
+  dir?: 'ltr' | 'rtl'
+  themeSource?: HTMLElement | null
+}>()
+
+const emit = defineEmits<{
+  select: [emoji: string]
+}>()
+
+const menuEl = ref<HTMLElement | null>(null)
+const placed = ref<{ left: number; top: number }>({ left: props.position.x, top: props.position.y })
+
+function place() {
+  const el = menuEl.value
+
+  if (!el) {
+return
+}
+
+  if (props.themeSource) {
+syncThemeVars(props.themeSource, el)
+}
+
+  const margin = 8
+  const gap = 6
+  const { width, height } = el.getBoundingClientRect()
+  const anchorTop = props.position.top ?? props.position.y
+  let left = props.dir === 'rtl' ? props.position.x - width : props.position.x
+  left = Math.max(margin, Math.min(left, window.innerWidth - width - margin))
+  let top = props.position.y + gap
+
+  if (top + height > window.innerHeight - margin) {
+    top = Math.max(margin, anchorTop - height - gap)
+  }
+
+  placed.value = { left, top }
+}
+
+let unlockScroll: (() => void) | null = null
+
+onMounted(() => {
+  nextTick(place)
+  window.addEventListener('resize', place)
+  window.addEventListener('scroll', place, true)
+  unlockScroll = lockPageScroll()
+})
+
+onBeforeUnmount(() => {
+  window.removeEventListener('resize', place)
+  window.removeEventListener('scroll', place, true)
+  unlockScroll?.()
+  unlockScroll = null
+})
+
+watch(() => props.position, () => {
+ nextTick(place)
+}, { deep: true })
+watch(() => props.query, () => {
+ nextTick(place)
+})
+</script>
+
+<template>
+  <Teleport to="body">
+    <div
+      ref="menuEl"
+      class="fixed z-[80] border bg-[var(--xpe-surface)] border-[var(--xpe-border)] rounded-[var(--xpe-radius)] [box-shadow:var(--xpe-shadow)] overflow-hidden"
+      :style="{ left: `${placed.left}px`, top: `${placed.top}px` }"
+      :dir="dir"
+      @mousedown.prevent
+    >
+      <EmojiPicker :query="query" @select="emoji => emit('select', emoji)" />
+    </div>
+  </Teleport>
+</template>
diff --git a/packages/vue/src/components/EditorSlashMenu.vue b/packages/vue/src/components/EditorSlashMenu.vue
index 40e2854..da36e10 100644
--- a/packages/vue/src/components/EditorSlashMenu.vue
+++ b/packages/vue/src/components/EditorSlashMenu.vue
@@ -2,11 +2,14 @@
 import {
   Type, Heading1, Heading2, Heading3, List, ListOrdered, CheckSquare,
   ChevronRight, Quote, Lightbulb, Code2, Minus, Image as ImageIcon, Video, Table2,
-  Smile, Blocks, Music, Paperclip, SearchX,
+  Smile, Blocks, Music, Paperclip, SearchX, SquareMousePointer,
 } from 'lucide-vue-next'
 import { ref, computed, watch, nextTick, onMounted, onBeforeUnmount } from 'vue'
+import { lockPageScroll, syncThemeVars } from '@xproeditor/core'
 import type { BlockType } from '@xproeditor/core'
 
+export type SlashGroup = 'basic' | 'lists' | 'media' | 'advanced'
+
 export interface SlashItem {
   id: string
   type: BlockType
@@ -14,30 +17,39 @@ export interface SlashItem {
   description: string
   keywords: string[]
   icon: unknown
+  group: SlashGroup
   /** After applying the block, open the icon picker on this tab. */
   pickIcon?: 'emoji' | 'icon'
 }
 
+const GROUP_LABELS: Record<SlashGroup, string> = {
+  basic: 'Basic blocks',
+  lists: 'Lists & tasks',
+  media: 'Media',
+  advanced: 'Advanced',
+}
+
 const ITEMS: SlashItem[] = [
-  { id: 'paragraph', type: 'paragraph', label: 'Text', description: 'Plain paragraph', keywords: ['text', 'paragraph', 'p'], icon: Type },
-  { id: 'heading_1', type: 'heading_1', label: 'Heading 1', description: 'Large section heading', keywords: ['h1', 'heading', 'title'], icon: Heading1 },
-  { id: 'heading_2', type: 'heading_2', label: 'Heading 2', description: 'Medium section heading', keywords: ['h2', 'heading', 'subtitle'], icon: Heading2 },
-  { id: 'heading_3', type: 'heading_3', label: 'Heading 3', description: 'Small section heading', keywords: ['h3', 'heading'], icon: Heading3 },
-  { id: 'bulleted_list_item', type: 'bulleted_list_item', label: 'Bulleted list', description: 'Simple bullet list', keywords: ['bullet', 'list', 'ul'], icon: List },
-  { id: 'numbered_list_item', type: 'numbered_list_item', label: 'Numbered list', description: 'Ordered list', keywords: ['number', 'ordered', 'ol'], icon: ListOrdered },
-  { id: 'to_do', type: 'to_do', label: 'To-do', description: 'Checkbox task', keywords: ['todo', 'check', 'task'], icon: CheckSquare },
-  { id: 'toggle', type: 'toggle', label: 'Toggle', description: 'Collapsible content', keywords: ['toggle', 'collapse', 'accordion'], icon: ChevronRight },
-  { id: 'quote', type: 'quote', label: 'Quote', description: 'Capture a quote', keywords: ['quote', 'blockquote'], icon: Quote },
-  { id: 'callout', type: 'callout', label: 'Callout', description: 'Highlighted note', keywords: ['callout', 'note', 'info', 'warning'], icon: Lightbulb },
-  { id: 'emoji', type: 'callout', label: 'Emoji', description: 'Callout with emoji icon', keywords: ['emoji', 'emoticon', 'smile'], icon: Smile, pickIcon: 'emoji' },
-  { id: 'icon', type: 'callout', label: 'Icon', description: 'Callout with vector icon', keywords: ['icon', 'symbol', 'lucide'], icon: Blocks, pickIcon: 'icon' },
-  { id: 'code', type: 'code', label: 'Code', description: 'Code block with syntax', keywords: ['code', 'snippet', 'pre'], icon: Code2 },
-  { id: 'divider', type: 'divider', label: 'Divider', description: 'Horizontal line', keywords: ['divider', 'hr', 'separator', 'line'], icon: Minus },
-  { id: 'image', type: 'image', label: 'Image', description: 'Upload an image', keywords: ['image', 'photo', 'picture', 'upload'], icon: ImageIcon },
-  { id: 'video', type: 'video', label: 'Video', description: 'Upload or embed a video', keywords: ['video', 'youtube', 'vimeo', 'movie'], icon: Video },
-  { id: 'audio', type: 'audio', label: 'Audio', description: 'Upload or link audio', keywords: ['audio', 'music', 'song', 'sound', 'mp3'], icon: Music },
-  { id: 'file', type: 'file', label: 'File', description: 'Attach a downloadable file', keywords: ['file', 'attachment', 'pdf', 'document', 'download'], icon: Paperclip },
-  { id: 'table', type: 'table', label: 'Table', description: 'Simple table', keywords: ['table', 'grid'], icon: Table2 },
+  { id: 'paragraph', type: 'paragraph', label: 'Text', description: 'Plain paragraph', keywords: ['text', 'paragraph', 'p'], icon: Type, group: 'basic' },
+  { id: 'heading_1', type: 'heading_1', label: 'Heading 1', description: 'Large section heading', keywords: ['h1', 'heading', 'title'], icon: Heading1, group: 'basic' },
+  { id: 'heading_2', type: 'heading_2', label: 'Heading 2', description: 'Medium section heading', keywords: ['h2', 'heading', 'subtitle'], icon: Heading2, group: 'basic' },
+  { id: 'heading_3', type: 'heading_3', label: 'Heading 3', description: 'Small section heading', keywords: ['h3', 'heading'], icon: Heading3, group: 'basic' },
+  { id: 'bulleted_list_item', type: 'bulleted_list_item', label: 'Bulleted list', description: 'Simple bullet list', keywords: ['bullet', 'list', 'ul'], icon: List, group: 'lists' },
+  { id: 'numbered_list_item', type: 'numbered_list_item', label: 'Numbered list', description: 'Ordered list', keywords: ['number', 'ordered', 'ol'], icon: ListOrdered, group: 'lists' },
+  { id: 'to_do', type: 'to_do', label: 'To-do', description: 'Checkbox task', keywords: ['todo', 'check', 'task'], icon: CheckSquare, group: 'lists' },
+  { id: 'toggle', type: 'toggle', label: 'Toggle', description: 'Collapsible content', keywords: ['toggle', 'collapse', 'accordion'], icon: ChevronRight, group: 'lists' },
+  { id: 'image', type: 'image', label: 'Image', description: 'Upload an image', keywords: ['image', 'photo', 'picture', 'upload'], icon: ImageIcon, group: 'media' },
+  { id: 'video', type: 'video', label: 'Video', description: 'Upload or embed a video', keywords: ['video', 'youtube', 'vimeo', 'movie'], icon: Video, group: 'media' },
+  { id: 'audio', type: 'audio', label: 'Audio', description: 'Upload or link audio', keywords: ['audio', 'music', 'song', 'sound', 'mp3'], icon: Music, group: 'media' },
+  { id: 'file', type: 'file', label: 'File', description: 'Attach a downloadable file', keywords: ['file', 'attachment', 'pdf', 'document', 'download'], icon: Paperclip, group: 'media' },
+  { id: 'quote', type: 'quote', label: 'Quote', description: 'Capture a quote', keywords: ['quote', 'blockquote'], icon: Quote, group: 'advanced' },
+  { id: 'callout', type: 'callout', label: 'Callout', description: 'Highlighted note', keywords: ['callout', 'note', 'info', 'warning'], icon: Lightbulb, group: 'advanced' },
+  { id: 'emoji', type: 'callout', label: 'Emoji', description: 'Callout with emoji icon', keywords: ['emoji', 'emoticon', 'smile'], icon: Smile, group: 'advanced', pickIcon: 'emoji' },
+  { id: 'icon', type: 'callout', label: 'Icon', description: 'Callout with vector icon', keywords: ['icon', 'symbol', 'lucide'], icon: Blocks, group: 'advanced', pickIcon: 'icon' },
+  { id: 'code', type: 'code', label: 'Code', description: 'Code block with syntax', keywords: ['code', 'snippet', 'pre'], icon: Code2, group: 'advanced' },
+  { id: 'divider', type: 'divider', label: 'Divider', description: 'Horizontal line', keywords: ['divider', 'hr', 'separator', 'line'], icon: Minus, group: 'advanced' },
+  { id: 'table', type: 'table', label: 'Table', description: 'Simple table', keywords: ['table', 'grid'], icon: Table2, group: 'advanced' },
+  { id: 'button', type: 'button', label: 'Button', description: 'A clickable link styled as a button', keywords: ['button', 'link', 'cta', 'action'], icon: SquareMousePointer, group: 'advanced' },
 ]
 
 const props = defineProps<{
@@ -45,6 +57,9 @@ const props = defineProps<{
   /** Caret anchor in viewport coordinates: menu opens below `bottom`, flips above `top` when needed. */
   position: { x: number; y: number; top?: number }
   dir?: 'ltr' | 'rtl'
+  /** Element still inside the editor's themed DOM scope — used to resync
+   * `--xpe-*` variables onto this menu once it's teleported to `<body>`. */
+  themeSource?: HTMLElement | null
 }>()
 
 const emit = defineEmits<{
@@ -69,6 +84,15 @@ return ITEMS
   )
 })
 
+/** Same items, annotated with a group header wherever the group changes. */
+const grouped = computed(() =>
+  filtered.value.map((item, idx) => ({
+    item,
+    idx,
+    headerLabel: idx === 0 || filtered.value[idx - 1].group !== item.group ? GROUP_LABELS[item.group] : null,
+  })),
+)
+
 /**
  * Place the menu with its real measured size: below the caret when it fits,
  * flipped above otherwise, clamped to the viewport. In RTL the menu grows
@@ -79,6 +103,10 @@ function place() {
 
   if (!el) {
 return
+}
+
+  if (props.themeSource) {
+syncThemeVars(props.themeSource, el)
 }
 
   const margin = 8
@@ -96,15 +124,22 @@ return
   placed.value = { left, top }
 }
 
+let unlockScroll: (() => void) | null = null
+
 onMounted(() => {
   nextTick(place)
   window.addEventListener('resize', place)
+  // Body scroll is locked below, but a scrollable ancestor of the editor
+  // (e.g. an app's own scroll container) can still move — reposition if so.
   window.addEventListener('scroll', place, true)
+  unlockScroll = lockPageScroll()
 })
 
 onBeforeUnmount(() => {
   window.removeEventListener('resize', place)
   window.removeEventListener('scroll', place, true)
+  unlockScroll?.()
+  unlockScroll = null
 })
 
 watch(() => props.query, () => {
@@ -152,32 +187,37 @@ defineExpose({ move, confirm })
       :dir="dir"
       @mousedown.prevent
     >
-      <p class="px-3 pt-1 pb-1.5 text-[10px] font-semibold uppercase tracking-wider text-[var(--xpe-muted-foreground)]">Blocks</p>
-      <div v-if="filtered.length === 0" class="flex items-center gap-2 px-3 py-3 text-[13px] text-[var(--xpe-muted-foreground)]">
+      <div v-if="filtered.length === 0" class="flex items-center gap-2 px-3 py-4 text-[13px] text-[var(--xpe-muted-foreground)]">
         <SearchX class="w-4 h-4" />
         No results for “{{ query }}”
       </div>
       <div ref="listEl">
-        <button
-          v-for="(item, idx) in filtered"
-          :key="item.id"
-          class="flex items-center gap-3 w-full px-3 py-1.5 text-start transition-colors"
-          :class="idx === activeIndex ? 'bg-[var(--xpe-primary-muted)]' : 'hover:bg-[var(--xpe-surface-hover)]'"
-          :data-active="idx === activeIndex"
-          @mouseenter="activeIndex = idx"
-          @click="emit('select', item)"
-        >
-          <span
-            class="flex items-center justify-center w-8 h-8 rounded-lg border shrink-0"
-            :class="idx === activeIndex ? 'border-[var(--xpe-border)] bg-[var(--xpe-surface)] text-[var(--xpe-primary)]' : 'border-[var(--xpe-border)] bg-[var(--xpe-muted)] text-[var(--xpe-muted-foreground)]'"
+        <template v-for="entry in grouped" :key="entry.item.id">
+          <p
+            v-if="entry.headerLabel"
+            class="px-3 pt-2.5 pb-1 text-[10px] font-semibold uppercase tracking-wider text-[var(--xpe-muted-foreground)] first:pt-1"
+          >
+            {{ entry.headerLabel }}
+          </p>
+          <button
+            class="flex items-center gap-3 w-full px-3 py-1.5 text-start transition-colors"
+            :class="entry.idx === activeIndex ? 'bg-[var(--xpe-primary-muted)]' : 'hover:bg-[var(--xpe-surface-hover)]'"
+            :data-active="entry.idx === activeIndex"
+            @mouseenter="activeIndex = entry.idx"
+            @click="emit('select', entry.item)"
           >
-            <component :is="item.icon" class="w-4 h-4" />
-          </span>
-          <span class="min-w-0">
-            <span class="block text-[13px] font-medium text-[var(--xpe-foreground)]">{{ item.label }}</span>
-            <span class="block text-[11px] text-[var(--xpe-muted-foreground)] truncate">{{ item.description }}</span>
-          </span>
-        </button>
+            <span
+              class="flex items-center justify-center w-8 h-8 rounded-lg border shrink-0"
+              :class="entry.idx === activeIndex ? 'border-[var(--xpe-border)] bg-[var(--xpe-surface)] text-[var(--xpe-primary)]' : 'border-[var(--xpe-border)] bg-[var(--xpe-muted)] text-[var(--xpe-muted-foreground)]'"
+            >
+              <component :is="entry.item.icon" class="w-4 h-4" />
+            </span>
+            <span class="min-w-0">
+              <span class="block text-[13px] font-medium text-[var(--xpe-foreground)]">{{ entry.item.label }}</span>
+              <span class="block text-[11px] text-[var(--xpe-muted-foreground)] truncate">{{ entry.item.description }}</span>
+            </span>
+          </button>
+        </template>
       </div>
     </div>
   </Teleport>
diff --git a/packages/vue/src/ui/EmojiPicker.vue b/packages/vue/src/ui/EmojiPicker.vue
new file mode 100644
index 0000000..373a200
--- /dev/null
+++ b/packages/vue/src/ui/EmojiPicker.vue
@@ -0,0 +1,192 @@
+<script setup lang="ts">
+import { Clock, Hash, Leaf, Lightbulb, Music, Plane, Search, Smile, UtensilsCrossed } from 'lucide-vue-next'
+import { computed, nextTick, onMounted, ref } from 'vue'
+import { ALL_EMOJIS, EMOJI_CATEGORIES, type EmojiEntry } from './emojiData'
+
+const RECENTS_KEY = 'xpe-emoji-recents'
+const MAX_RECENTS = 24
+
+function readRecents(): string[] {
+  try {
+    const raw = localStorage.getItem(RECENTS_KEY)
+    const parsed = raw ? JSON.parse(raw) : []
+
+    return Array.isArray(parsed) ? parsed.filter(v => typeof v === 'string') : []
+  } catch {
+    return []
+  }
+}
+
+function pushRecent(char: string) {
+  try {
+    const next = [char, ...readRecents().filter(c => c !== char)].slice(0, MAX_RECENTS)
+    localStorage.setItem(RECENTS_KEY, JSON.stringify(next))
+  } catch {
+    /* storage unavailable */
+  }
+}
+
+const CATEGORY_ICONS: Record<string, unknown> = {
+  smileys: Smile,
+  nature: Leaf,
+  food: UtensilsCrossed,
+  activities: Music,
+  travel: Plane,
+  objects: Lightbulb,
+  symbols: Hash,
+}
+
+const props = defineProps<{
+  autoFocus?: boolean
+  /**
+   * Controlled query, driving the grid without rendering an internal search
+   * input — used by the ':' inline trigger, where the query is typed
+   * directly into the text block rather than into the picker itself.
+   */
+  query?: string
+}>()
+
+const emit = defineEmits<{
+  select: [emoji: string]
+}>()
+
+const controlled = computed(() => props.query !== undefined)
+const internalQuery = ref('')
+const query = computed(() => (controlled.value ? props.query ?? '' : internalQuery.value))
+const recents = ref<string[]>(readRecents())
+const searchEl = ref<HTMLInputElement | null>(null)
+const sectionEls = ref<Record<string, HTMLElement | null>>({})
+
+onMounted(() => {
+  if (props.autoFocus && !controlled.value) {
+    nextTick(() => searchEl.value?.focus())
+  }
+})
+
+const filtered = computed(() => {
+  const q = query.value.trim().toLowerCase()
+
+  if (!q) {
+return null
+}
+
+  return ALL_EMOJIS.filter(e => e.name.includes(q) || e.keywords.some(k => k.includes(q))).slice(0, 60)
+})
+
+function charToEntry(char: string): EmojiEntry | undefined {
+  return ALL_EMOJIS.find(e => e.char === char)
+}
+
+const categoriesToRender = computed(() => {
+  if (recents.value.length === 0) {
+return EMOJI_CATEGORIES
+}
+
+  const recentEntries = recents.value.map(charToEntry).filter((e): e is EmojiEntry => !!e)
+
+  return [{ id: 'recents', label: 'Recently used', emojis: recentEntries }, ...EMOJI_CATEGORIES]
+})
+
+function pick(entry: EmojiEntry) {
+  pushRecent(entry.char)
+  recents.value = readRecents()
+  emit('select', entry.char)
+}
+
+function confirmSearch() {
+  if (filtered.value && filtered.value[0]) {
+    pick(filtered.value[0])
+  }
+}
+
+function scrollToCategory(id: string) {
+  internalQuery.value = ''
+  nextTick(() => {
+    sectionEls.value[id]?.scrollIntoView({ block: 'start' })
+  })
+}
+</script>
+
+<template>
+  <div class="xpe-emoji-picker" :class="{ 'xpe-emoji-picker--controlled': controlled }">
+    <div v-if="!controlled" class="xpe-emoji-search">
+      <Search class="h-3.5 w-3.5 shrink-0 text-[var(--xpe-muted-foreground)]" />
+      <input
+        ref="searchEl"
+        v-model="internalQuery"
+        type="text"
+        placeholder="Search emoji..."
+        class="xpe-emoji-search-input"
+        @keydown.enter.prevent="confirmSearch"
+      />
+    </div>
+
+    <div class="xpe-emoji-scroll">
+      <p v-if="controlled && !filtered" class="xpe-emoji-empty">Keep typing to search emoji…</p>
+      <template v-else-if="filtered">
+        <p v-if="filtered.length === 0" class="xpe-emoji-empty">No emoji found</p>
+        <div v-else class="xpe-emoji-grid">
+          <button
+            v-for="entry in filtered"
+            :key="entry.char"
+            type="button"
+            class="xpe-emoji-cell"
+            :title="entry.name"
+            @click="pick(entry)"
+          >
+            {{ entry.char }}
+          </button>
+        </div>
+      </template>
+      <template v-else>
+        <div v-for="cat in categoriesToRender" :key="cat.id" :ref="(el) => { sectionEls[cat.id] = el as HTMLElement }">
+          <p class="xpe-emoji-heading">{{ cat.label }}</p>
+          <div class="xpe-emoji-grid">
+            <button
+              v-for="entry in cat.emojis"
+              :key="entry.char"
+              type="button"
+              class="xpe-emoji-cell"
+              :title="entry.name"
+              @click="pick(entry)"
+            >
+              {{ entry.char }}
+            </button>
+          </div>
+        </div>
+      </template>
+    </div>
+
+    <div v-if="!controlled" class="xpe-emoji-catbar">
+      <button type="button" title="Recently used" @click="scrollToCategory('recents')">
+        <Clock class="h-4 w-4" />
+      </button>
+      <button
+        v-for="cat in EMOJI_CATEGORIES"
+        :key="cat.id"
+        type="button"
+        :title="cat.label"
+        @click="scrollToCategory(cat.id)"
+      >
+        <component :is="CATEGORY_ICONS[cat.id] ?? Hash" class="h-4 w-4" />
+      </button>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.xpe-emoji-picker { display: flex; flex-direction: column; width: 300px; height: 340px; }
+.xpe-emoji-picker--controlled { height: auto; max-height: 260px; width: 280px; }
+.xpe-emoji-search { display: flex; align-items: center; gap: 6px; padding: 8px 10px; border-bottom: 1px solid var(--xpe-border, #e5e7eb); flex-shrink: 0; }
+.xpe-emoji-search-input { flex: 1; border: none; background: transparent; outline: none; font-size: 13px; color: var(--xpe-foreground, #111827); }
+.xpe-emoji-search-input::placeholder { color: var(--xpe-muted-foreground, #9ca3af); }
+.xpe-emoji-scroll { flex: 1; overflow-y: auto; padding: 6px 8px; }
+.xpe-emoji-heading { padding: 6px 4px 4px; font-size: 10px; font-weight: 700; text-transform: uppercase; letter-spacing: 0.06em; color: var(--xpe-muted-foreground, #9ca3af); }
+.xpe-emoji-grid { display: grid; grid-template-columns: repeat(8, 1fr); gap: 2px; }
+.xpe-emoji-cell { display: flex; align-items: center; justify-content: center; height: 32px; border-radius: 8px; border: none; background: transparent; font-size: 19px; line-height: 1; cursor: pointer; transition: background 0.1s, transform 0.1s; }
+.xpe-emoji-cell:hover { background: var(--xpe-muted, #f3f4f6); transform: scale(1.12); }
+.xpe-emoji-empty { padding: 24px 8px; text-align: center; font-size: 12px; color: var(--xpe-muted-foreground, #9ca3af); }
+.xpe-emoji-catbar { display: flex; align-items: center; justify-content: space-between; gap: 2px; padding: 6px 8px; border-top: 1px solid var(--xpe-border, #e5e7eb); flex-shrink: 0; }
+.xpe-emoji-catbar button { display: flex; align-items: center; justify-content: center; width: 26px; height: 26px; border-radius: 6px; border: none; background: transparent; color: var(--xpe-muted-foreground, #9ca3af); cursor: pointer; transition: background 0.1s, color 0.1s; }
+.xpe-emoji-catbar button:hover { background: var(--xpe-muted, #f3f4f6); color: var(--xpe-foreground, #111827); }
+</style>
diff --git a/packages/vue/src/ui/IconEmojiPicker.vue b/packages/vue/src/ui/IconEmojiPicker.vue
index 6690fa1..befe839 100644
--- a/packages/vue/src/ui/IconEmojiPicker.vue
+++ b/packages/vue/src/ui/IconEmojiPicker.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import { ref } from 'vue'
-import { EMOJI_PRESETS } from './emojiPresets'
+import EmojiPicker from './EmojiPicker.vue'
 import Popover from './Popover.vue'
 import PopoverContent from './PopoverContent.vue'
 import PopoverTrigger from './PopoverTrigger.vue'
@@ -58,18 +58,7 @@ defineExpose({
       </slot>
     </PopoverTrigger>
     <PopoverContent :align="align" :side="side" class="xpe-icon-popover">
-      <div class="xpe-icon-grid">
-        <button
-          v-for="emoji in EMOJI_PRESETS"
-          :key="emoji"
-          type="button"
-          class="xpe-icon-cell"
-          :class="{ 'xpe-icon-cell--active': emoji === model }"
-          @click="pick(emoji)"
-        >
-          {{ emoji }}
-        </button>
-      </div>
+      <EmojiPicker @select="pick" />
       <div class="xpe-icon-custom">
         <input
           v-model="customValue"
@@ -98,37 +87,16 @@ defineExpose({
   padding: 0;
 }
 .xpe-icon-popover {
-  padding: 10px;
-  width: 232px;
-}
-.xpe-icon-grid {
-  display: grid;
-  grid-template-columns: repeat(8, 1fr);
-  gap: 2px;
-}
-.xpe-icon-cell {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  height: 26px;
-  border-radius: 6px;
-  border: none;
-  background: transparent;
-  font-size: 15px;
-  cursor: pointer;
-}
-.xpe-icon-cell:hover {
-  background: var(--xpe-muted, #f3f4f6);
-}
-.xpe-icon-cell--active {
-  background: var(--xpe-primary-muted, #eef2ff);
+  padding: 0;
+  width: 300px;
+  overflow: hidden;
 }
 .xpe-icon-custom {
   display: flex;
   gap: 6px;
-  margin-top: 8px;
-  padding-top: 8px;
-  border-top: 1px solid var(--xpe-muted, #f3f4f6);
+  margin: 0;
+  padding: 8px 10px;
+  border-top: 1px solid var(--xpe-border, #f3f4f6);
 }
 .xpe-icon-custom-input {
   flex: 1;
diff --git a/packages/vue/src/ui/PopoverContent.vue b/packages/vue/src/ui/PopoverContent.vue
index 471f571..09541eb 100644
--- a/packages/vue/src/ui/PopoverContent.vue
+++ b/packages/vue/src/ui/PopoverContent.vue
@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import { inject, nextTick, onBeforeUnmount, ref, watch } from 'vue'
+import { syncThemeVars } from '@xproeditor/core'
 import { popoverContextKey } from './popoverContext'
 
 const props = withDefaults(
@@ -30,6 +31,11 @@ function reposition(): void {
   const content = contentEl.value
   if (!trigger || !content) return
 
+  // The popover is teleported to <body>, which escapes any scoped theme
+  // class applied to an ancestor of the editor — resync inline so it still
+  // picks up a custom --xpe-* theme.
+  syncThemeVars(trigger, content)
+
   const anchor = (trigger.firstElementChild as HTMLElement | null) ?? trigger
   const rect = anchor.getBoundingClientRect()
   const contentRect = content.getBoundingClientRect()
diff --git a/packages/vue/src/ui/emojiData.ts b/packages/vue/src/ui/emojiData.ts
new file mode 100644
index 0000000..50e0047
--- /dev/null
+++ b/packages/vue/src/ui/emojiData.ts
@@ -0,0 +1,372 @@
+export interface EmojiEntry {
+  char: string
+  name: string
+  keywords: string[]
+}
+
+export interface EmojiCategoryData {
+  id: string
+  label: string
+  emojis: EmojiEntry[]
+}
+
+export const EMOJI_CATEGORIES: EmojiCategoryData[] = [
+  {
+    id: 'smileys',
+    label: 'Smileys & People',
+    emojis: [
+      { char: '😀', name: 'grinning face', keywords: ['smile', 'happy', 'grin'] },
+      { char: '😃', name: 'grinning face with big eyes', keywords: ['smile', 'happy'] },
+      { char: '😄', name: 'grinning face with smiling eyes', keywords: ['smile', 'happy', 'laugh'] },
+      { char: '😁', name: 'beaming face', keywords: ['smile', 'happy', 'grin'] },
+      { char: '😆', name: 'grinning squinting face', keywords: ['laugh', 'happy'] },
+      { char: '😅', name: 'grinning face with sweat', keywords: ['laugh', 'nervous', 'sweat'] },
+      { char: '🤣', name: 'rolling on the floor laughing', keywords: ['lol', 'laugh', 'rofl'] },
+      { char: '😂', name: 'face with tears of joy', keywords: ['lol', 'laugh', 'cry'] },
+      { char: '🙂', name: 'slightly smiling face', keywords: ['smile'] },
+      { char: '🙃', name: 'upside-down face', keywords: ['silly', 'sarcasm'] },
+      { char: '😉', name: 'winking face', keywords: ['wink', 'flirt'] },
+      { char: '😊', name: 'smiling face with smiling eyes', keywords: ['smile', 'happy', 'blush'] },
+      { char: '😇', name: 'smiling face with halo', keywords: ['angel', 'innocent'] },
+      { char: '🥰', name: 'smiling face with hearts', keywords: ['love', 'crush'] },
+      { char: '😍', name: 'heart eyes', keywords: ['love', 'crush', 'adore'] },
+      { char: '🤩', name: 'star-struck', keywords: ['wow', 'excited'] },
+      { char: '😘', name: 'face blowing a kiss', keywords: ['kiss', 'love'] },
+      { char: '😗', name: 'kissing face', keywords: ['kiss'] },
+      { char: '😋', name: 'face savoring food', keywords: ['yum', 'tasty', 'delicious'] },
+      { char: '😛', name: 'face with tongue', keywords: ['tongue', 'silly'] },
+      { char: '😜', name: 'winking face with tongue', keywords: ['silly', 'joke'] },
+      { char: '🤪', name: 'zany face', keywords: ['crazy', 'silly'] },
+      { char: '😝', name: 'squinting face with tongue', keywords: ['silly', 'joke'] },
+      { char: '🤑', name: 'money-mouth face', keywords: ['money', 'rich'] },
+      { char: '🤗', name: 'hugging face', keywords: ['hug', 'embrace'] },
+      { char: '🤭', name: 'face with hand over mouth', keywords: ['giggle', 'oops'] },
+      { char: '🤫', name: 'shushing face', keywords: ['quiet', 'secret'] },
+      { char: '🤔', name: 'thinking face', keywords: ['think', 'hmm', 'consider'] },
+      { char: '🤐', name: 'zipper-mouth face', keywords: ['quiet', 'silence'] },
+      { char: '🙄', name: 'face with rolling eyes', keywords: ['annoyed', 'eyeroll'] },
+      { char: '😏', name: 'smirking face', keywords: ['smug', 'sly'] },
+      { char: '😣', name: 'persevering face', keywords: ['struggle', 'annoyed'] },
+      { char: '😥', name: 'sad but relieved face', keywords: ['sad', 'relief'] },
+      { char: '😮', name: 'face with open mouth', keywords: ['wow', 'surprise'] },
+      { char: '🤐', name: 'zipper mouth', keywords: ['secret'] },
+      { char: '😯', name: 'hushed face', keywords: ['surprise', 'silent'] },
+      { char: '😪', name: 'sleepy face', keywords: ['tired', 'sleep'] },
+      { char: '😫', name: 'tired face', keywords: ['exhausted', 'tired'] },
+      { char: '🥱', name: 'yawning face', keywords: ['tired', 'sleepy', 'bored'] },
+      { char: '😴', name: 'sleeping face', keywords: ['sleep', 'zzz'] },
+      { char: '😌', name: 'relieved face', keywords: ['calm', 'relief'] },
+      { char: '😛', name: 'tongue out', keywords: ['silly'] },
+      { char: '😒', name: 'unamused face', keywords: ['annoyed', 'meh'] },
+      { char: '😓', name: 'downcast face with sweat', keywords: ['stressed', 'sweat'] },
+      { char: '😔', name: 'pensive face', keywords: ['sad', 'thoughtful'] },
+      { char: '😕', name: 'confused face', keywords: ['confused', 'unsure'] },
+      { char: '🙁', name: 'slightly frowning face', keywords: ['sad', 'frown'] },
+      { char: '😖', name: 'confounded face', keywords: ['frustrated'] },
+      { char: '😞', name: 'disappointed face', keywords: ['sad', 'disappointed'] },
+      { char: '😟', name: 'worried face', keywords: ['worried', 'concerned'] },
+      { char: '😤', name: 'face with steam from nose', keywords: ['angry', 'proud'] },
+      { char: '😢', name: 'crying face', keywords: ['sad', 'cry', 'tear'] },
+      { char: '😭', name: 'loudly crying face', keywords: ['sad', 'cry', 'sob'] },
+      { char: '😦', name: 'frowning face with open mouth', keywords: ['shock'] },
+      { char: '😧', name: 'anguished face', keywords: ['shock', 'pain'] },
+      { char: '😨', name: 'fearful face', keywords: ['scared', 'fear'] },
+      { char: '😩', name: 'weary face', keywords: ['tired', 'stressed'] },
+      { char: '🤯', name: 'exploding head', keywords: ['mind blown', 'shock'] },
+      { char: '😬', name: 'grimacing face', keywords: ['awkward', 'nervous'] },
+      { char: '😰', name: 'anxious face with sweat', keywords: ['nervous', 'anxious'] },
+      { char: '😱', name: 'face screaming in fear', keywords: ['scream', 'shock'] },
+      { char: '🥵', name: 'hot face', keywords: ['hot', 'heat'] },
+      { char: '🥶', name: 'cold face', keywords: ['cold', 'freeze'] },
+      { char: '😳', name: 'flushed face', keywords: ['embarrassed', 'blush'] },
+      { char: '🤪', name: 'zany', keywords: ['crazy'] },
+      { char: '😵', name: 'dizzy face', keywords: ['dizzy', 'confused'] },
+      { char: '🥴', name: 'woozy face', keywords: ['dizzy', 'drunk'] },
+      { char: '😠', name: 'angry face', keywords: ['angry', 'mad'] },
+      { char: '😡', name: 'pouting face', keywords: ['angry', 'rage'] },
+      { char: '🤬', name: 'face with symbols on mouth', keywords: ['angry', 'swear'] },
+      { char: '😷', name: 'face with medical mask', keywords: ['sick', 'mask'] },
+      { char: '🤒', name: 'face with thermometer', keywords: ['sick', 'fever'] },
+      { char: '🤕', name: 'face with head-bandage', keywords: ['hurt', 'injured'] },
+      { char: '🤢', name: 'nauseated face', keywords: ['sick', 'gross'] },
+      { char: '🤮', name: 'face vomiting', keywords: ['sick', 'gross'] },
+      { char: '🤧', name: 'sneezing face', keywords: ['sick', 'sneeze'] },
+      { char: '😇', name: 'angel', keywords: ['innocent'] },
+      { char: '🥳', name: 'partying face', keywords: ['party', 'celebrate'] },
+      { char: '🥸', name: 'disguised face', keywords: ['disguise', 'incognito'] },
+      { char: '😎', name: 'smiling face with sunglasses', keywords: ['cool'] },
+      { char: '🤓', name: 'nerd face', keywords: ['nerd', 'geek'] },
+      { char: '🧐', name: 'face with monocle', keywords: ['inspect', 'curious'] },
+      { char: '👋', name: 'waving hand', keywords: ['wave', 'hello', 'bye'] },
+      { char: '👍', name: 'thumbs up', keywords: ['like', 'yes', 'approve'] },
+      { char: '👎', name: 'thumbs down', keywords: ['dislike', 'no'] },
+      { char: '👏', name: 'clapping hands', keywords: ['applause', 'clap', 'bravo'] },
+      { char: '🙌', name: 'raising hands', keywords: ['celebrate', 'hooray'] },
+      { char: '🙏', name: 'folded hands', keywords: ['please', 'pray', 'thanks'] },
+      { char: '💪', name: 'flexed biceps', keywords: ['strong', 'muscle'] },
+      { char: '👌', name: 'OK hand', keywords: ['ok', 'perfect'] },
+      { char: '✌️', name: 'victory hand', keywords: ['peace', 'victory'] },
+      { char: '🤝', name: 'handshake', keywords: ['deal', 'agreement'] },
+      { char: '❤️', name: 'red heart', keywords: ['love', 'heart'] },
+      { char: '💔', name: 'broken heart', keywords: ['heartbreak', 'sad'] },
+    ],
+  },
+  {
+    id: 'nature',
+    label: 'Animals & Nature',
+    emojis: [
+      { char: '🐶', name: 'dog face', keywords: ['dog', 'puppy', 'pet'] },
+      { char: '🐱', name: 'cat face', keywords: ['cat', 'kitten', 'pet'] },
+      { char: '🐭', name: 'mouse face', keywords: ['mouse'] },
+      { char: '🐹', name: 'hamster', keywords: ['hamster', 'pet'] },
+      { char: '🐰', name: 'rabbit face', keywords: ['rabbit', 'bunny'] },
+      { char: '🦊', name: 'fox', keywords: ['fox'] },
+      { char: '🐻', name: 'bear', keywords: ['bear'] },
+      { char: '🐼', name: 'panda', keywords: ['panda'] },
+      { char: '🐨', name: 'koala', keywords: ['koala'] },
+      { char: '🐯', name: 'tiger face', keywords: ['tiger'] },
+      { char: '🦁', name: 'lion', keywords: ['lion'] },
+      { char: '🐮', name: 'cow face', keywords: ['cow'] },
+      { char: '🐷', name: 'pig face', keywords: ['pig'] },
+      { char: '🐸', name: 'frog', keywords: ['frog'] },
+      { char: '🐵', name: 'monkey face', keywords: ['monkey'] },
+      { char: '🐔', name: 'chicken', keywords: ['chicken'] },
+      { char: '🐧', name: 'penguin', keywords: ['penguin'] },
+      { char: '🐦', name: 'bird', keywords: ['bird'] },
+      { char: '🦄', name: 'unicorn', keywords: ['unicorn', 'magic'] },
+      { char: '🐝', name: 'honeybee', keywords: ['bee', 'insect'] },
+      { char: '🐢', name: 'turtle', keywords: ['turtle'] },
+      { char: '🐍', name: 'snake', keywords: ['snake'] },
+      { char: '🐳', name: 'spouting whale', keywords: ['whale', 'ocean'] },
+      { char: '🐬', name: 'dolphin', keywords: ['dolphin', 'ocean'] },
+      { char: '🐠', name: 'tropical fish', keywords: ['fish', 'ocean'] },
+      { char: '🦋', name: 'butterfly', keywords: ['butterfly'] },
+      { char: '🌸', name: 'cherry blossom', keywords: ['flower', 'spring'] },
+      { char: '🌹', name: 'rose', keywords: ['flower', 'rose'] },
+      { char: '🌻', name: 'sunflower', keywords: ['flower', 'sun'] },
+      { char: '🌵', name: 'cactus', keywords: ['plant', 'desert'] },
+      { char: '🌲', name: 'evergreen tree', keywords: ['tree', 'forest'] },
+      { char: '🍀', name: 'four leaf clover', keywords: ['luck', 'clover'] },
+      { char: '🌈', name: 'rainbow', keywords: ['rainbow', 'colorful'] },
+      { char: '☀️', name: 'sun', keywords: ['sun', 'sunny'] },
+      { char: '⭐', name: 'star', keywords: ['star'] },
+      { char: '🌙', name: 'crescent moon', keywords: ['moon', 'night'] },
+      { char: '☁️', name: 'cloud', keywords: ['cloud', 'weather'] },
+      { char: '⚡', name: 'high voltage', keywords: ['lightning', 'zap', 'energy'] },
+      { char: '🔥', name: 'fire', keywords: ['fire', 'hot', 'lit'] },
+      { char: '❄️', name: 'snowflake', keywords: ['snow', 'cold', 'winter'] },
+    ],
+  },
+  {
+    id: 'food',
+    label: 'Food & Drink',
+    emojis: [
+      { char: '🍎', name: 'red apple', keywords: ['apple', 'fruit'] },
+      { char: '🍊', name: 'tangerine', keywords: ['orange', 'fruit'] },
+      { char: '🍋', name: 'lemon', keywords: ['lemon', 'fruit'] },
+      { char: '🍌', name: 'banana', keywords: ['banana', 'fruit'] },
+      { char: '🍉', name: 'watermelon', keywords: ['watermelon', 'fruit'] },
+      { char: '🍇', name: 'grapes', keywords: ['grapes', 'fruit'] },
+      { char: '🍓', name: 'strawberry', keywords: ['strawberry', 'fruit'] },
+      { char: '🍑', name: 'peach', keywords: ['peach', 'fruit'] },
+      { char: '🥝', name: 'kiwi fruit', keywords: ['kiwi', 'fruit'] },
+      { char: '🍍', name: 'pineapple', keywords: ['pineapple', 'fruit'] },
+      { char: '🥑', name: 'avocado', keywords: ['avocado'] },
+      { char: '🍅', name: 'tomato', keywords: ['tomato'] },
+      { char: '🌽', name: 'ear of corn', keywords: ['corn'] },
+      { char: '🥕', name: 'carrot', keywords: ['carrot'] },
+      { char: '🍕', name: 'pizza', keywords: ['pizza', 'food'] },
+      { char: '🍔', name: 'hamburger', keywords: ['burger', 'food'] },
+      { char: '🍟', name: 'french fries', keywords: ['fries', 'food'] },
+      { char: '🌭', name: 'hot dog', keywords: ['hotdog', 'food'] },
+      { char: '🥪', name: 'sandwich', keywords: ['sandwich', 'food'] },
+      { char: '🌮', name: 'taco', keywords: ['taco', 'food'] },
+      { char: '🍣', name: 'sushi', keywords: ['sushi', 'food'] },
+      { char: '🍜', name: 'steaming bowl', keywords: ['noodles', 'ramen', 'food'] },
+      { char: '🍝', name: 'spaghetti', keywords: ['pasta', 'food'] },
+      { char: '🍦', name: 'soft ice cream', keywords: ['icecream', 'dessert'] },
+      { char: '🍩', name: 'doughnut', keywords: ['donut', 'dessert'] },
+      { char: '🍪', name: 'cookie', keywords: ['cookie', 'dessert'] },
+      { char: '🎂', name: 'birthday cake', keywords: ['cake', 'birthday'] },
+      { char: '🍰', name: 'shortcake', keywords: ['cake', 'dessert'] },
+      { char: '🍫', name: 'chocolate bar', keywords: ['chocolate', 'dessert'] },
+      { char: '☕', name: 'hot beverage', keywords: ['coffee', 'tea'] },
+      { char: '🍵', name: 'teacup without handle', keywords: ['tea'] },
+      { char: '🍺', name: 'beer mug', keywords: ['beer', 'drink'] },
+      { char: '🍷', name: 'wine glass', keywords: ['wine', 'drink'] },
+      { char: '🥂', name: 'clinking glasses', keywords: ['cheers', 'toast', 'drink'] },
+    ],
+  },
+  {
+    id: 'activities',
+    label: 'Activities',
+    emojis: [
+      { char: '⚽', name: 'soccer ball', keywords: ['soccer', 'football', 'sport'] },
+      { char: '🏀', name: 'basketball', keywords: ['basketball', 'sport'] },
+      { char: '🏈', name: 'american football', keywords: ['football', 'sport'] },
+      { char: '⚾', name: 'baseball', keywords: ['baseball', 'sport'] },
+      { char: '🎾', name: 'tennis', keywords: ['tennis', 'sport'] },
+      { char: '🏐', name: 'volleyball', keywords: ['volleyball', 'sport'] },
+      { char: '🏉', name: 'rugby football', keywords: ['rugby', 'sport'] },
+      { char: '🎱', name: 'pool 8 ball', keywords: ['billiards', 'pool'] },
+      { char: '🏓', name: 'ping pong', keywords: ['tabletennis', 'sport'] },
+      { char: '🏸', name: 'badminton', keywords: ['badminton', 'sport'] },
+      { char: '🥅', name: 'goal net', keywords: ['goal', 'sport'] },
+      { char: '⛳', name: 'flag in hole', keywords: ['golf'] },
+      { char: '🏹', name: 'bow and arrow', keywords: ['archery'] },
+      { char: '🎣', name: 'fishing pole', keywords: ['fishing'] },
+      { char: '🤿', name: 'diving mask', keywords: ['diving', 'snorkel'] },
+      { char: '🥊', name: 'boxing glove', keywords: ['boxing'] },
+      { char: '🥋', name: 'martial arts uniform', keywords: ['karate', 'judo'] },
+      { char: '🎽', name: 'running shirt', keywords: ['running', 'race'] },
+      { char: '🛹', name: 'skateboard', keywords: ['skateboard'] },
+      { char: '🛼', name: 'roller skate', keywords: ['skating'] },
+      { char: '🎿', name: 'skis', keywords: ['ski', 'snow'] },
+      { char: '⛸️', name: 'ice skate', keywords: ['iceskating'] },
+      { char: '🥌', name: 'curling stone', keywords: ['curling'] },
+      { char: '🎯', name: 'direct hit', keywords: ['target', 'dart', 'goal'] },
+      { char: '🎮', name: 'video game', keywords: ['gaming', 'controller'] },
+      { char: '🎲', name: 'game die', keywords: ['dice', 'game'] },
+      { char: '🧩', name: 'puzzle piece', keywords: ['puzzle'] },
+      { char: '🎨', name: 'artist palette', keywords: ['art', 'paint'] },
+      { char: '🎭', name: 'performing arts', keywords: ['theater', 'drama'] },
+      { char: '🎪', name: 'circus tent', keywords: ['circus'] },
+      { char: '🎬', name: 'clapper board', keywords: ['movie', 'film'] },
+      { char: '🎤', name: 'microphone', keywords: ['sing', 'music'] },
+      { char: '🎧', name: 'headphone', keywords: ['music', 'audio'] },
+      { char: '🎼', name: 'musical score', keywords: ['music'] },
+      { char: '🎹', name: 'musical keyboard', keywords: ['piano', 'music'] },
+      { char: '🥁', name: 'drum', keywords: ['drum', 'music'] },
+      { char: '🎸', name: 'guitar', keywords: ['guitar', 'music'] },
+      { char: '🏆', name: 'trophy', keywords: ['trophy', 'award', 'win'] },
+      { char: '🥇', name: 'gold medal', keywords: ['medal', 'first', 'win'] },
+    ],
+  },
+  {
+    id: 'travel',
+    label: 'Travel & Places',
+    emojis: [
+      { char: '🚗', name: 'car', keywords: ['car', 'drive'] },
+      { char: '🚕', name: 'taxi', keywords: ['taxi', 'cab'] },
+      { char: '🚌', name: 'bus', keywords: ['bus'] },
+      { char: '🚓', name: 'police car', keywords: ['police'] },
+      { char: '🚑', name: 'ambulance', keywords: ['ambulance'] },
+      { char: '🚒', name: 'fire engine', keywords: ['firetruck'] },
+      { char: '🚲', name: 'bicycle', keywords: ['bike', 'cycle'] },
+      { char: '🛵', name: 'motor scooter', keywords: ['scooter'] },
+      { char: '✈️', name: 'airplane', keywords: ['flight', 'travel', 'plane'] },
+      { char: '🚀', name: 'rocket', keywords: ['rocket', 'launch', 'space'] },
+      { char: '🚁', name: 'helicopter', keywords: ['helicopter'] },
+      { char: '⛵', name: 'sailboat', keywords: ['boat', 'sailing'] },
+      { char: '🚢', name: 'ship', keywords: ['ship', 'cruise'] },
+      { char: '🚂', name: 'locomotive', keywords: ['train'] },
+      { char: '🚆', name: 'train', keywords: ['train', 'rail'] },
+      { char: '🚊', name: 'tram', keywords: ['tram'] },
+      { char: '🗺️', name: 'world map', keywords: ['map', 'travel'] },
+      { char: '🗽', name: 'statue of liberty', keywords: ['newyork', 'landmark'] },
+      { char: '🗼', name: 'tokyo tower', keywords: ['tower', 'landmark'] },
+      { char: '🏰', name: 'castle', keywords: ['castle'] },
+      { char: '🏯', name: 'japanese castle', keywords: ['castle', 'japan'] },
+      { char: '🏟️', name: 'stadium', keywords: ['stadium'] },
+      { char: '🎡', name: 'ferris wheel', keywords: ['carnival'] },
+      { char: '🎢', name: 'roller coaster', keywords: ['coaster'] },
+      { char: '⛱️', name: 'umbrella on ground', keywords: ['beach'] },
+      { char: '🏖️', name: 'beach with umbrella', keywords: ['beach', 'vacation'] },
+      { char: '🏝️', name: 'desert island', keywords: ['island', 'beach'] },
+      { char: '⛰️', name: 'mountain', keywords: ['mountain'] },
+      { char: '🏔️', name: 'snow-capped mountain', keywords: ['mountain', 'snow'] },
+      { char: '🌋', name: 'volcano', keywords: ['volcano'] },
+      { char: '🏕️', name: 'camping', keywords: ['camp', 'tent'] },
+      { char: '🏙️', name: 'cityscape', keywords: ['city'] },
+      { char: '🌃', name: 'night with stars', keywords: ['night', 'city'] },
+      { char: '🌍', name: 'globe showing europe-africa', keywords: ['world', 'earth', 'globe'] },
+    ],
+  },
+  {
+    id: 'objects',
+    label: 'Objects',
+    emojis: [
+      { char: '💡', name: 'light bulb', keywords: ['idea', 'light', 'bulb'] },
+      { char: '📌', name: 'pushpin', keywords: ['pin', 'note'] },
+      { char: '📎', name: 'paperclip', keywords: ['attach', 'clip'] },
+      { char: '📝', name: 'memo', keywords: ['note', 'write'] },
+      { char: '📋', name: 'clipboard', keywords: ['list', 'tasks'] },
+      { char: '📁', name: 'file folder', keywords: ['folder', 'files'] },
+      { char: '📂', name: 'open file folder', keywords: ['folder', 'files'] },
+      { char: '🗂️', name: 'card index dividers', keywords: ['organize', 'files'] },
+      { char: '📅', name: 'calendar', keywords: ['calendar', 'date'] },
+      { char: '📆', name: 'tear-off calendar', keywords: ['calendar', 'date'] },
+      { char: '📊', name: 'bar chart', keywords: ['chart', 'graph', 'stats'] },
+      { char: '📈', name: 'chart increasing', keywords: ['growth', 'stats'] },
+      { char: '📉', name: 'chart decreasing', keywords: ['decline', 'stats'] },
+      { char: '💻', name: 'laptop', keywords: ['computer', 'laptop'] },
+      { char: '🖥️', name: 'desktop computer', keywords: ['computer', 'monitor'] },
+      { char: '⌨️', name: 'keyboard', keywords: ['keyboard', 'type'] },
+      { char: '🖱️', name: 'computer mouse', keywords: ['mouse'] },
+      { char: '📱', name: 'mobile phone', keywords: ['phone', 'mobile'] },
+      { char: '☎️', name: 'telephone', keywords: ['phone', 'call'] },
+      { char: '🔋', name: 'battery', keywords: ['battery', 'power'] },
+      { char: '🔌', name: 'electric plug', keywords: ['plug', 'power'] },
+      { char: '💾', name: 'floppy disk', keywords: ['save', 'disk'] },
+      { char: '💿', name: 'optical disk', keywords: ['cd', 'disk'] },
+      { char: '🔍', name: 'magnifying glass', keywords: ['search', 'find', 'zoom'] },
+      { char: '🔒', name: 'locked', keywords: ['lock', 'secure', 'private'] },
+      { char: '🔓', name: 'unlocked', keywords: ['unlock', 'open'] },
+      { char: '🔑', name: 'key', keywords: ['key', 'password'] },
+      { char: '🔨', name: 'hammer', keywords: ['tool', 'build', 'fix'] },
+      { char: '🛠️', name: 'hammer and wrench', keywords: ['tools', 'fix', 'settings'] },
+      { char: '⚙️', name: 'gear', keywords: ['settings', 'config'] },
+      { char: '🧰', name: 'toolbox', keywords: ['tools'] },
+      { char: '🔗', name: 'link', keywords: ['link', 'chain', 'url'] },
+      { char: '📦', name: 'package', keywords: ['box', 'delivery', 'package'] },
+      { char: '💰', name: 'money bag', keywords: ['money', 'rich'] },
+      { char: '💳', name: 'credit card', keywords: ['card', 'payment'] },
+      { char: '🎁', name: 'wrapped gift', keywords: ['gift', 'present'] },
+      { char: '🔔', name: 'bell', keywords: ['notification', 'alert'] },
+      { char: '📢', name: 'loudspeaker', keywords: ['announce', 'megaphone'] },
+      { char: '🧭', name: 'compass', keywords: ['compass', 'direction'] },
+      { char: '⏰', name: 'alarm clock', keywords: ['clock', 'alarm', 'time'] },
+      { char: '⏳', name: 'hourglass not done', keywords: ['time', 'wait'] },
+    ],
+  },
+  {
+    id: 'symbols',
+    label: 'Symbols',
+    emojis: [
+      { char: '✅', name: 'check mark button', keywords: ['check', 'done', 'yes'] },
+      { char: '❌', name: 'cross mark', keywords: ['no', 'wrong', 'x'] },
+      { char: '❗', name: 'exclamation mark', keywords: ['important', 'warning'] },
+      { char: '❓', name: 'question mark', keywords: ['question', 'help'] },
+      { char: '⚠️', name: 'warning', keywords: ['warning', 'caution', 'alert'] },
+      { char: '🚫', name: 'prohibited', keywords: ['no', 'banned', 'forbidden'] },
+      { char: '♻️', name: 'recycling symbol', keywords: ['recycle', 'green'] },
+      { char: '💯', name: 'hundred points', keywords: ['100', 'perfect'] },
+      { char: '✨', name: 'sparkles', keywords: ['sparkle', 'new', 'shiny'] },
+      { char: '⭐', name: 'star', keywords: ['star', 'favorite'] },
+      { char: '🌟', name: 'glowing star', keywords: ['star', 'shine'] },
+      { char: '💫', name: 'dizzy', keywords: ['star', 'sparkle'] },
+      { char: '🔴', name: 'red circle', keywords: ['red', 'circle', 'dot'] },
+      { char: '🟠', name: 'orange circle', keywords: ['orange', 'circle'] },
+      { char: '🟡', name: 'yellow circle', keywords: ['yellow', 'circle'] },
+      { char: '🟢', name: 'green circle', keywords: ['green', 'circle'] },
+      { char: '🔵', name: 'blue circle', keywords: ['blue', 'circle'] },
+      { char: '🟣', name: 'purple circle', keywords: ['purple', 'circle'] },
+      { char: '⚫', name: 'black circle', keywords: ['black', 'circle'] },
+      { char: '⚪', name: 'white circle', keywords: ['white', 'circle'] },
+      { char: '🔺', name: 'red triangle pointed up', keywords: ['triangle', 'warning'] },
+      { char: '💠', name: 'diamond with a dot', keywords: ['diamond'] },
+      { char: '🔶', name: 'large orange diamond', keywords: ['diamond'] },
+      { char: '➕', name: 'plus', keywords: ['add', 'plus'] },
+      { char: '➖', name: 'minus', keywords: ['subtract', 'minus'] },
+      { char: '➗', name: 'divide', keywords: ['divide'] },
+      { char: '✖️', name: 'multiply', keywords: ['multiply', 'times'] },
+      { char: '♾️', name: 'infinity', keywords: ['infinite', 'infinity'] },
+      { char: '💤', name: 'zzz', keywords: ['sleep', 'tired'] },
+      { char: '💬', name: 'speech balloon', keywords: ['chat', 'comment', 'talk'] },
+      { char: '💭', name: 'thought balloon', keywords: ['think', 'idea'] },
+    ],
+  },
+]
+
+/** Flat lookup used by search across all categories. */
+export const ALL_EMOJIS: EmojiEntry[] = EMOJI_CATEGORIES.flatMap((c) => c.emojis)
diff --git a/packages/vue/src/ui/index.ts b/packages/vue/src/ui/index.ts
index cf4c681..8f4b425 100644
--- a/packages/vue/src/ui/index.ts
+++ b/packages/vue/src/ui/index.ts
@@ -14,5 +14,7 @@ export { default as DropdownMenuItem } from './DropdownMenuItem.vue'
 export { default as ColorPickerPanel } from './ColorPickerPanel.vue'
 export { default as IconEmojiPicker } from './IconEmojiPicker.vue'
 export { default as IconValueDisplay } from './IconValueDisplay.vue'
+export { default as EmojiPicker } from './EmojiPicker.vue'
 export * from './colorPresets'
 export * from './emojiPresets'
+export * from './emojiData'

From d987bf01aafdd335016df72c861ab20b167d74f3 Mon Sep 17 00:00:00 2001
From: Mohammad Moradi <mohammad.moradi@outlook.com>
Date: Sat, 11 Jul 2026 17:22:20 +0300
Subject: [PATCH 6/7] Add block context menu, custom scrollbars, softer
 corners, and fix color popover bug
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- New right-click context menu on blocks: Duplicate, Delete, and — for
  callout blocks — a Color flyout reusing the existing background presets.
  Clean two-level menu, no extra clutter.
- Custom slim scrollbars (token-driven via --xpe-*, `.xpe-scroll` class
  for custom containers) replace the browser default across popovers,
  dropdowns, slash/emoji menus, tables, code blocks, the editor root, the
  doc renderer, and the site itself.
- Popover/dropdown/button/input/callout/table/code corners now scale off
  --xpe-radius instead of hardcoded pixel values, so one token change
  reshapes the whole editor consistently.
- Fix: the bubble toolbar's color popover could never actually be used —
  clicking a swatch closed the panel instantly. Root cause: the panel's
  "stay open" effect compared toolbar position by object reference, and a
  same-range selectionchange fired by clicking inside the toolbar always
  produces a fresh position object, closing the panel before a color could
  register.
- Fix: a malformed Tailwind class left the "active color" checkmark badge
  invisible in the color/table-style panels; replaced along with a few
  remaining hardcoded indigo accents with theme tokens.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 ...ontext-menu-scrollbars-radius-color-fix.md |  13 ++
 .../react/src/components/BlockContextMenu.tsx | 140 ++++++++++++++++++
 packages/react/src/components/BlockEditor.tsx |   1 +
 packages/react/src/components/BlockItem.tsx   |  30 +++-
 .../react/src/components/BubbleToolbar.tsx    |  15 +-
 packages/react/src/components/SlashMenu.tsx   |   2 +-
 packages/react/src/components/TableBlock.tsx  |   2 +-
 .../components/toolbar/TableStylePanel.tsx    |  14 +-
 .../components/toolbar/ToolbarColorPanel.tsx  |   8 +-
 packages/react/src/styles/components.css      |  24 +--
 packages/react/src/styles/theme.css           |  56 +++++++
 packages/vue/src/components/BlockEditor.vue   |   1 +
 packages/vue/src/components/DocRenderer.vue   |  10 +-
 .../src/components/EditorBlockContextMenu.vue | 132 +++++++++++++++++
 .../vue/src/components/EditorBlockItem.vue    |  30 +++-
 .../src/components/EditorBubbleToolbar.vue    |  16 +-
 .../vue/src/components/EditorSlashMenu.vue    |   2 +-
 .../vue/src/components/EditorTableBlock.vue   |   2 +-
 .../toolbar/EditorTableStylePanel.vue         |  14 +-
 .../toolbar/EditorToolbarColorPanel.vue       |   8 +-
 packages/vue/src/styles/theme.css             |  56 +++++++
 packages/vue/src/ui/Button.vue                |   2 +-
 packages/vue/src/ui/ColorPickerPanel.vue      |   4 +-
 packages/vue/src/ui/DropdownMenuItem.vue      |   2 +-
 packages/vue/src/ui/Input.vue                 |   2 +-
 packages/vue/src/ui/PopoverContent.vue        |   2 +-
 packages/vue/src/ui/TabsList.vue              |   2 +-
 packages/vue/src/ui/TabsTrigger.vue           |   2 +-
 site/src/App.css                              |  22 +++
 29 files changed, 555 insertions(+), 59 deletions(-)
 create mode 100644 .changeset/context-menu-scrollbars-radius-color-fix.md
 create mode 100644 packages/react/src/components/BlockContextMenu.tsx
 create mode 100644 packages/vue/src/components/EditorBlockContextMenu.vue

diff --git a/.changeset/context-menu-scrollbars-radius-color-fix.md b/.changeset/context-menu-scrollbars-radius-color-fix.md
new file mode 100644
index 0000000..9826aa3
--- /dev/null
+++ b/.changeset/context-menu-scrollbars-radius-color-fix.md
@@ -0,0 +1,13 @@
+---
+'@xproeditor/core': minor
+'@xproeditor/vue': minor
+'@xproeditor/react': minor
+---
+
+Add a right-click context menu on blocks (Notion-style): Duplicate, Delete, and — for callout blocks — a Color flyout with the existing background presets, all in a clean two-level menu with no extra clutter.
+
+Add slim, theme-token-driven custom scrollbars across every scrollable surface (popovers, dropdowns, the slash/emoji menus, tables, code blocks, the editor root, and the doc renderer) instead of the browser default — add the `.xpe-scroll` class to any other scrollable container you build to match.
+
+Soften corners across the whole popover/menu/button/input/callout/table/code family to scale off `--xpe-radius` instead of hardcoded pixel values, so a single token change now reshapes the entire editor consistently.
+
+Fix: the text/highlight color popover in the floating bubble toolbar could never actually be used — clicking a swatch immediately closed the panel. The panel's "stay open" effect compared the toolbar's position by object reference, and a same-range `selectionchange` event (fired by clicking inside the toolbar itself) always produces a fresh position object, so the panel closed itself before a color could register. Also fixed a malformed Tailwind class that left the "active color" checkmark badge invisible, and replaced a few remaining hardcoded indigo accents with theme tokens.
diff --git a/packages/react/src/components/BlockContextMenu.tsx b/packages/react/src/components/BlockContextMenu.tsx
new file mode 100644
index 0000000..1695468
--- /dev/null
+++ b/packages/react/src/components/BlockContextMenu.tsx
@@ -0,0 +1,140 @@
+import { useLayoutEffect, useRef, useState } from 'react'
+import { createPortal } from 'react-dom'
+import { ChevronLeft, ChevronRight, Copy, Palette, Trash2 } from 'lucide-react'
+import { syncThemeVars } from '@xproeditor/core'
+
+export interface BlockContextMenuProps {
+  position: { x: number; y: number }
+  /** Background color swatches — only shown when the block supports one (e.g. callout). */
+  colorPresets?: string[]
+  currentColor?: string
+  themeSource?: HTMLElement | null
+  onColor?: (color: string) => void
+  onDuplicate: () => void
+  onDelete: () => void
+  onClose: () => void
+}
+
+type View = 'root' | 'color'
+
+export function BlockContextMenu({
+  position,
+  colorPresets,
+  currentColor,
+  themeSource,
+  onColor,
+  onDuplicate,
+  onDelete,
+  onClose,
+}: BlockContextMenuProps) {
+  const [view, setView] = useState<View>('root')
+  const menuRef = useRef<HTMLDivElement | null>(null)
+  const [placed, setPlaced] = useState({ left: position.x, top: position.y })
+
+  useLayoutEffect(() => {
+    const el = menuRef.current
+    if (!el) return
+
+    if (themeSource) syncThemeVars(themeSource, el)
+
+    const margin = 8
+    const { width, height } = el.getBoundingClientRect()
+    const left = Math.max(margin, Math.min(position.x, window.innerWidth - width - margin))
+    const top = Math.max(margin, Math.min(position.y, window.innerHeight - height - margin))
+    setPlaced({ left, top })
+  }, [position, themeSource, view])
+
+  useLayoutEffect(() => {
+    function onOutside(e: MouseEvent) {
+      if (!menuRef.current?.contains(e.target as Node)) onClose()
+    }
+    function onKey(e: KeyboardEvent) {
+      if (e.key === 'Escape') onClose()
+    }
+    window.addEventListener('mousedown', onOutside, true)
+    window.addEventListener('keydown', onKey)
+    return () => {
+      window.removeEventListener('mousedown', onOutside, true)
+      window.removeEventListener('keydown', onKey)
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
+  return createPortal(
+    <div
+      ref={menuRef}
+      className="xpe-popover-content xpe-scroll fixed z-[80] w-52 overflow-y-auto py-1.5"
+      style={{ left: placed.left, top: placed.top }}
+      onMouseDown={(e) => e.stopPropagation()}
+    >
+      {view === 'root' ? (
+        <>
+          {colorPresets && (
+            <button
+              type="button"
+              className="flex w-full items-center gap-2.5 px-3 py-1.5 text-start text-[13px] text-[var(--xpe-foreground)] hover:bg-[var(--xpe-surface-hover)]"
+              onClick={() => setView('color')}
+            >
+              <Palette className="h-3.5 w-3.5 text-[var(--xpe-muted-foreground)]" />
+              <span className="flex-1">Color</span>
+              <ChevronRight className="h-3.5 w-3.5 text-[var(--xpe-muted-foreground)]" />
+            </button>
+          )}
+          <button
+            type="button"
+            className="flex w-full items-center gap-2.5 px-3 py-1.5 text-start text-[13px] text-[var(--xpe-foreground)] hover:bg-[var(--xpe-surface-hover)]"
+            onClick={() => {
+              onDuplicate()
+              onClose()
+            }}
+          >
+            <Copy className="h-3.5 w-3.5 text-[var(--xpe-muted-foreground)]" />
+            Duplicate
+          </button>
+          <button
+            type="button"
+            className="flex w-full items-center gap-2.5 px-3 py-1.5 text-start text-[13px] text-[var(--xpe-danger)] hover:bg-[var(--xpe-surface-hover)]"
+            onClick={() => {
+              onDelete()
+              onClose()
+            }}
+          >
+            <Trash2 className="h-3.5 w-3.5" />
+            Delete
+          </button>
+        </>
+      ) : (
+        <>
+          <button
+            type="button"
+            className="flex w-full items-center gap-2 px-3 py-1.5 text-start text-[12px] font-medium text-[var(--xpe-muted-foreground)] hover:text-[var(--xpe-foreground)]"
+            onClick={() => setView('root')}
+          >
+            <ChevronLeft className="h-3.5 w-3.5" />
+            Color
+          </button>
+          <div className="grid grid-cols-7 gap-1.5 px-3 py-1.5">
+            {colorPresets?.map((color) => (
+              <button
+                key={color}
+                type="button"
+                className={`h-6 w-6 rounded-full border transition-transform hover:scale-110 ${
+                  currentColor === color
+                    ? 'border-[var(--xpe-ring)] ring-2 ring-[var(--xpe-ring)]'
+                    : 'border-[var(--xpe-border)]'
+                }`}
+                style={{ background: color }}
+                title={color}
+                onClick={() => {
+                  onColor?.(color)
+                  onClose()
+                }}
+              />
+            ))}
+          </div>
+        </>
+      )}
+    </div>,
+    document.body,
+  )
+}
diff --git a/packages/react/src/components/BlockEditor.tsx b/packages/react/src/components/BlockEditor.tsx
index 9fff6ff..90ac691 100644
--- a/packages/react/src/components/BlockEditor.tsx
+++ b/packages/react/src/components/BlockEditor.tsx
@@ -109,6 +109,7 @@ export const BlockEditor = forwardRef<BlockEditorHandle, BlockEditorProps>(funct
           pickMedia={ed.pickMedia}
           editorDir={ed.editorDir}
           readonly={ed.readonly}
+          themeSource={ed.rootRef.current}
           iconPickerRequest={
             ed.iconPickerRequest && ed.iconPickerRequest.blockId === block.id
               ? { tab: ed.iconPickerRequest.tab }
diff --git a/packages/react/src/components/BlockItem.tsx b/packages/react/src/components/BlockItem.tsx
index 4e2d1fa..9933393 100644
--- a/packages/react/src/components/BlockItem.tsx
+++ b/packages/react/src/components/BlockItem.tsx
@@ -11,6 +11,7 @@ import {
 } from '../ui'
 import { CodeBlock, type CodeBlockHandle } from './CodeBlock'
 import { AudioBlock } from './AudioBlock'
+import { BlockContextMenu } from './BlockContextMenu'
 import { ButtonBlock } from './ButtonBlock'
 import { FileBlock } from './FileBlock'
 import { ImageBlock } from './ImageBlock'
@@ -34,6 +35,7 @@ export interface BlockItemProps {
   pickMedia?: PickMediaFn
   editorDir?: 'ltr' | 'rtl'
   readonly?: boolean
+  themeSource?: HTMLElement | null
   iconPickerRequest?: { tab: 'emoji' | 'icon' } | null
   onInput: (spans: InlineSpan[], caret: number | null) => void
   onEnter: (offsets: { start: number; end: number }) => void
@@ -89,6 +91,7 @@ export const BlockItem = forwardRef<BlockItemHandle, BlockItemProps>(
       pickMedia,
       editorDir,
       readonly,
+      themeSource,
       iconPickerRequest,
       onInput,
       onEnter,
@@ -120,6 +123,15 @@ export const BlockItem = forwardRef<BlockItemHandle, BlockItemProps>(
     const innerRef = useRef<TextBlockHandle | CodeBlockHandle | TableBlockHandle | null>(null)
     const calloutIconPickerRef = useRef<{ open: (tab?: 'emoji' | 'icon') => void } | null>(null)
     const [showCalloutColors, setShowCalloutColors] = useState(false)
+    const [contextMenuPos, setContextMenuPos] = useState<{ x: number; y: number } | null>(null)
+
+    function onContextMenu(e: React.MouseEvent) {
+      if (readonly) return
+
+      e.preventDefault()
+      onSelect()
+      setContextMenuPos({ x: e.clientX, y: e.clientY })
+    }
 
     useEffect(() => {
       if (!iconPickerRequest || readonly || block.type !== 'callout') return
@@ -201,6 +213,7 @@ export const BlockItem = forwardRef<BlockItemHandle, BlockItemProps>(
         dir={blockDir}
         style={{ paddingInlineStart: `${indent * 28}px` }}
         onPointerDown={onPointerDown}
+        onContextMenu={onContextMenu}
       >
         {dropPosition === 'before' && <div className="ebi-drop -top-[2px]" />}
         {dropPosition === 'after' && <div className="ebi-drop -bottom-[2px]" />}
@@ -255,7 +268,7 @@ export const BlockItem = forwardRef<BlockItemHandle, BlockItemProps>(
               </div>
             ) : block.type === 'callout' ? (
               <div
-                className="flex items-start gap-2.5 rounded-xl border border-[var(--xpe-border)] px-3.5 py-3"
+                className="flex items-start gap-2.5 rounded-[var(--xpe-radius)] border border-[var(--xpe-border)] px-3.5 py-3"
                 style={{ background: block.props.color ?? 'var(--xpe-muted)' }}
               >
                 <div
@@ -297,7 +310,7 @@ export const BlockItem = forwardRef<BlockItemHandle, BlockItemProps>(
                     </button>
                   )}
                   {showCalloutColors && !readonly && (
-                    <div className="absolute start-0 top-full z-[60] mt-1 rounded-xl border border-[var(--xpe-border)] bg-[var(--xpe-surface)] p-2 shadow-xl">
+                    <div className="absolute start-0 top-full z-[60] mt-1 rounded-[var(--xpe-radius)] border border-[var(--xpe-border)] bg-[var(--xpe-surface)] p-2 shadow-xl">
                       <div className="flex gap-1">
                         {CALLOUT_COLORS.map((c) => (
                           <button
@@ -476,6 +489,19 @@ export const BlockItem = forwardRef<BlockItemHandle, BlockItemProps>(
             )}
           </div>
         </div>
+
+        {contextMenuPos && (
+          <BlockContextMenu
+            position={contextMenuPos}
+            themeSource={themeSource}
+            colorPresets={block.type === 'callout' ? CALLOUT_COLORS : undefined}
+            currentColor={block.props.color}
+            onColor={(color) => onPatch({ color })}
+            onDuplicate={onDuplicate}
+            onDelete={onRemove}
+            onClose={() => setContextMenuPos(null)}
+          />
+        )}
       </div>
     )
   },
diff --git a/packages/react/src/components/BubbleToolbar.tsx b/packages/react/src/components/BubbleToolbar.tsx
index 680ee7e..91e3572 100644
--- a/packages/react/src/components/BubbleToolbar.tsx
+++ b/packages/react/src/components/BubbleToolbar.tsx
@@ -67,13 +67,24 @@ export function BubbleToolbar({
   const [panel, setPanel] = useState<Panel>('none')
   const [linkInput, setLinkInput] = useState('')
   const toolbarRef = useRef<HTMLDivElement | null>(null)
+  const lastPositionKey = useRef<string | null>(null)
 
   useEffect(() => {
-    setPanel('none')
-
     if (themeSource && toolbarRef.current) {
       syncThemeVars(themeSource, toolbarRef.current)
     }
+
+    // `position` is a fresh object on every parent render (e.g. a
+    // same-range `selectionchange`), so only close an open panel when the
+    // selection actually moved — comparing by reference would close the
+    // color/link panel the instant a swatch inside it is clicked.
+    const key = `${position.x},${position.y}`
+
+    if (lastPositionKey.current !== null && lastPositionKey.current !== key) {
+      setPanel('none')
+    }
+
+    lastPositionKey.current = key
   }, [position, themeSource])
 
   function openLinkPanel() {
diff --git a/packages/react/src/components/SlashMenu.tsx b/packages/react/src/components/SlashMenu.tsx
index 5439b7a..b891dc7 100644
--- a/packages/react/src/components/SlashMenu.tsx
+++ b/packages/react/src/components/SlashMenu.tsx
@@ -334,7 +334,7 @@ export const SlashMenu = forwardRef<SlashMenuHandle, SlashMenuProps>(function Sl
   return createPortal(
     <div
       ref={menuRef}
-      className="fixed z-[80] w-72 max-h-80 overflow-y-auto border py-1.5 bg-[var(--xpe-surface)] border-[var(--xpe-border)] rounded-[var(--xpe-radius)] [box-shadow:var(--xpe-shadow)]"
+      className="xpe-scroll fixed z-[80] w-72 max-h-80 overflow-y-auto border py-1.5 bg-[var(--xpe-surface)] border-[var(--xpe-border)] rounded-[var(--xpe-radius)] [box-shadow:var(--xpe-shadow)]"
       style={{ left: placed.left, top: placed.top }}
       dir={dir}
       onMouseDown={(e) => e.preventDefault()}
diff --git a/packages/react/src/components/TableBlock.tsx b/packages/react/src/components/TableBlock.tsx
index 6eec56c..ae42420 100644
--- a/packages/react/src/components/TableBlock.tsx
+++ b/packages/react/src/components/TableBlock.tsx
@@ -229,7 +229,7 @@ export const TableBlock = forwardRef<TableBlockHandle, TableBlockProps>(function
 
       <div className="flex items-start">
         <div
-          className="flex-1 overflow-x-auto rounded-lg border border-[var(--xpe-border)]"
+          className="xpe-scroll flex-1 overflow-x-auto rounded-lg border border-[var(--xpe-border)]"
           style={wrapperStyle}
         >
           <table className="w-full border-collapse">
diff --git a/packages/react/src/components/toolbar/TableStylePanel.tsx b/packages/react/src/components/toolbar/TableStylePanel.tsx
index e037458..4463798 100644
--- a/packages/react/src/components/toolbar/TableStylePanel.tsx
+++ b/packages/react/src/components/toolbar/TableStylePanel.tsx
@@ -123,13 +123,13 @@ export function TableStylePanel({
             <button
               key={color}
               type="button"
-              className={`relative flex size-7 items-center justify-center rounded-md border border-black/5 text-xs font-bold ${isPresetActive(color, currentColor) ? 'ring-2 ring-indigo-500 ring-offset-1' : ''}`}
+              className={`relative flex size-7 items-center justify-center rounded-md border border-black/5 text-xs font-bold ${isPresetActive(color, currentColor) ? 'ring-2 ring-[var(--xpe-ring)] ring-offset-1' : ''}`}
               style={{ color }}
               onClick={() => selectTextColor(color)}
             >
               A
               {isPresetActive(color, currentColor) && (
-                <Check className="absolute -top-1 -end-1 size-3 rounded-full bg-[var(--xpe-primary-muted)]0 p-0.5 text-white" />
+                <Check className="absolute -top-1 -end-1 size-3 rounded-full bg-[var(--xpe-primary)] p-0.5 text-[var(--xpe-primary-foreground)]" />
               )}
             </button>
           ))}
@@ -143,7 +143,7 @@ export function TableStylePanel({
             <button
               key={color}
               type="button"
-              className={`relative size-7 rounded-md border border-black/10 ${isPresetActive(color, currentHighlight) ? 'ring-2 ring-indigo-500 ring-offset-1' : ''}`}
+              className={`relative size-7 rounded-md border border-black/10 ${isPresetActive(color, currentHighlight) ? 'ring-2 ring-[var(--xpe-ring)] ring-offset-1' : ''}`}
               style={{ backgroundColor: color }}
               onClick={() => selectHighlight(color)}
             />
@@ -190,7 +190,7 @@ export function TableStylePanel({
             <button
               key={color}
               type="button"
-              className={`relative size-7 rounded-md border border-black/10 ${isPresetActive(color, cellBackground) ? 'ring-2 ring-indigo-500 ring-offset-1' : ''}`}
+              className={`relative size-7 rounded-md border border-black/10 ${isPresetActive(color, cellBackground) ? 'ring-2 ring-[var(--xpe-ring)] ring-offset-1' : ''}`}
               style={{ backgroundColor: color }}
               onClick={() => onCellBackground(color)}
             />
@@ -224,7 +224,7 @@ export function TableStylePanel({
             <button
               key={`table-${color}`}
               type="button"
-              className={`relative size-7 rounded-md border border-black/10 ${isPresetActive(color, tableStyle?.background) ? 'ring-2 ring-indigo-500 ring-offset-1' : ''}`}
+              className={`relative size-7 rounded-md border border-black/10 ${isPresetActive(color, tableStyle?.background) ? 'ring-2 ring-[var(--xpe-ring)] ring-offset-1' : ''}`}
               style={{ backgroundColor: color }}
               onClick={() => onTableStyle({ background: color })}
             />
@@ -239,7 +239,7 @@ export function TableStylePanel({
             <button
               key={`header-${color}`}
               type="button"
-              className={`relative size-7 rounded-md border border-black/10 ${isPresetActive(color, tableStyle?.headerBackground) ? 'ring-2 ring-indigo-500 ring-offset-1' : ''}`}
+              className={`relative size-7 rounded-md border border-black/10 ${isPresetActive(color, tableStyle?.headerBackground) ? 'ring-2 ring-[var(--xpe-ring)] ring-offset-1' : ''}`}
               style={{ backgroundColor: color }}
               onClick={() => onTableStyle({ headerBackground: color })}
             />
@@ -279,7 +279,7 @@ export function TableStylePanel({
             <button
               key={color}
               type="button"
-              className={`relative size-7 rounded-md border-2 bg-[var(--xpe-surface)] ${isPresetActive(color, resolvedBorder.color) ? 'ring-2 ring-indigo-500 ring-offset-1' : ''}`}
+              className={`relative size-7 rounded-md border-2 bg-[var(--xpe-surface)] ${isPresetActive(color, resolvedBorder.color) ? 'ring-2 ring-[var(--xpe-ring)] ring-offset-1' : ''}`}
               style={{ borderColor: color }}
               onClick={() => onTableStyle({ border: { color } })}
             />
diff --git a/packages/react/src/components/toolbar/ToolbarColorPanel.tsx b/packages/react/src/components/toolbar/ToolbarColorPanel.tsx
index 3098443..c8799f1 100644
--- a/packages/react/src/components/toolbar/ToolbarColorPanel.tsx
+++ b/packages/react/src/components/toolbar/ToolbarColorPanel.tsx
@@ -124,14 +124,14 @@ export function ToolbarColorPanel({
             <button
               key={color}
               type="button"
-              className={`relative flex size-7 items-center justify-center rounded-md border border-black/5 text-xs font-bold transition-transform hover:scale-105 ${isPresetActive(color, activeTextColor) ? 'ring-2 ring-indigo-500 ring-offset-1' : ''}`}
+              className={`relative flex size-7 items-center justify-center rounded-md border border-black/5 text-xs font-bold transition-transform hover:scale-105 ${isPresetActive(color, activeTextColor) ? 'ring-2 ring-[var(--xpe-ring)] ring-offset-1' : ''}`}
               style={{ color }}
               title={color}
               onClick={() => selectTextColor(color)}
             >
               A
               {isPresetActive(color, activeTextColor) && (
-                <Check className="absolute -top-1 -end-1 size-3 rounded-full bg-[var(--xpe-primary-muted)]0 p-0.5 text-white" />
+                <Check className="absolute -top-1 -end-1 size-3 rounded-full bg-[var(--xpe-primary)] p-0.5 text-[var(--xpe-primary-foreground)]" />
               )}
             </button>
           ))}
@@ -170,13 +170,13 @@ export function ToolbarColorPanel({
             <button
               key={color}
               type="button"
-              className={`relative size-7 rounded-md border border-black/10 transition-transform hover:scale-105 ${isPresetActive(color, activeHighlight) ? 'ring-2 ring-indigo-500 ring-offset-1' : ''}`}
+              className={`relative size-7 rounded-md border border-black/10 transition-transform hover:scale-105 ${isPresetActive(color, activeHighlight) ? 'ring-2 ring-[var(--xpe-ring)] ring-offset-1' : ''}`}
               style={{ backgroundColor: color }}
               title={color}
               onClick={() => selectHighlight(color)}
             >
               {isPresetActive(color, activeHighlight) && (
-                <Check className="absolute -top-1 -end-1 size-3 rounded-full bg-[var(--xpe-primary-muted)]0 p-0.5 text-white" />
+                <Check className="absolute -top-1 -end-1 size-3 rounded-full bg-[var(--xpe-primary)] p-0.5 text-[var(--xpe-primary-foreground)]" />
               )}
             </button>
           ))}
diff --git a/packages/react/src/styles/components.css b/packages/react/src/styles/components.css
index cd25731..0436940 100644
--- a/packages/react/src/styles/components.css
+++ b/packages/react/src/styles/components.css
@@ -10,7 +10,7 @@
   align-items: center;
   justify-content: center;
   gap: 6px;
-  border-radius: 8px;
+  border-radius: calc(var(--xpe-radius, 12px) * 0.66);
   border: 1px solid transparent;
   font-weight: 500;
   cursor: pointer;
@@ -31,7 +31,7 @@
 /* ── ui/Input ──────────────────────────────────────────────────────────── */
 .xpe-input {
   width: 100%;
-  border-radius: 8px;
+  border-radius: calc(var(--xpe-radius, 12px) * 0.66);
   border: 1px solid var(--xpe-border, #e5e7eb);
   padding: 0 10px;
   font-size: 13px;
@@ -44,11 +44,11 @@
 .xpe-input::placeholder { color: var(--xpe-muted-foreground, #9ca3af); }
 
 /* ── ui/Tabs ───────────────────────────────────────────────────────────── */
-.xpe-tabs-list { display: grid; gap: 4px; background: var(--xpe-muted, #f3f4f6); border-radius: 8px; padding: 3px; }
+.xpe-tabs-list { display: grid; gap: 4px; background: var(--xpe-muted, #f3f4f6); border-radius: calc(var(--xpe-radius, 12px) * 0.66); padding: 3px; }
 .xpe-tabs-trigger {
   border: none;
   background: transparent;
-  border-radius: 6px;
+  border-radius: calc(var(--xpe-radius, 12px) * 0.5);
   padding: 5px 8px;
   font-size: 12px;
   font-weight: 500;
@@ -62,7 +62,7 @@
 /* ── ui/Popover & DropdownMenu ─────────────────────────────────────────── */
 .xpe-popover-content {
   z-index: 80;
-  border-radius: 12px;
+  border-radius: var(--xpe-radius, 12px);
   border: 1px solid var(--xpe-border, #f3f4f6);
   background: var(--xpe-surface, #fff);
   box-shadow: var(--xpe-shadow, 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1));
@@ -76,7 +76,7 @@
   padding: 6px 10px;
   border: none;
   background: transparent;
-  border-radius: 6px;
+  border-radius: calc(var(--xpe-radius, 12px) * 0.5);
   font-size: 13px;
   color: var(--xpe-foreground, #374151);
   cursor: pointer;
@@ -86,7 +86,7 @@
 
 /* ── ui/ColorPickerPanel ───────────────────────────────────────────────── */
 .xpe-color-picker { display: flex; align-items: center; gap: 8px; }
-.xpe-color-swatch { width: 32px; height: 32px; padding: 0; border: 1px solid var(--xpe-border, #e5e7eb); border-radius: 8px; cursor: pointer; background: none; }
+.xpe-color-swatch { width: 32px; height: 32px; padding: 0; border: 1px solid var(--xpe-border, #e5e7eb); border-radius: calc(var(--xpe-radius, 12px) * 0.66); cursor: pointer; background: none; }
 .xpe-color-hex {
   flex: 1;
   height: 32px;
@@ -259,16 +259,16 @@
 .db-toggle-chevron { flex-shrink: 0; display: inline-flex; margin-top: 0.4em; color: var(--xpe-muted-foreground); transition: transform 0.15s; }
 .db-toggle-chevron--rtl { transform: scaleX(-1); }
 .db-toggle-chevron--rtl.rotate-90 { transform: scaleX(-1) rotate(90deg); }
-.db-quote { border-inline-start: 3px solid var(--xpe-primary); padding: 0.4em 1.1em; margin: 1em 0; color: var(--xpe-muted-foreground); font-style: italic; background: var(--xpe-muted); border-radius: 0.5rem; }
-.db-callout { display: flex; align-items: flex-start; gap: 0.7em; padding: 0.85em 1.1em; margin: 1em 0; border-radius: 0.75rem; border: 1px solid var(--xpe-border); background: var(--xpe-muted); }
+.db-quote { border-inline-start: 3px solid var(--xpe-primary); padding: 0.4em 1.1em; margin: 1em 0; color: var(--xpe-muted-foreground); font-style: italic; background: var(--xpe-muted); border-radius: calc(var(--xpe-radius, 0.75rem) * 0.66); }
+.db-callout { display: flex; align-items: flex-start; gap: 0.7em; padding: 0.85em 1.1em; margin: 1em 0; border-radius: var(--xpe-radius, 0.75rem); border: 1px solid var(--xpe-border); background: var(--xpe-muted); }
 .db-callout-icon { font-size: 1.15em; line-height: 1.5; }
-.db-code { margin: 1.25em 0; border-radius: 0.75rem; overflow: hidden; border: 1px solid var(--xpe-border); }
+.db-code { margin: 1.25em 0; border-radius: var(--xpe-radius, 0.75rem); overflow: hidden; border: 1px solid var(--xpe-border); }
 .db-code-header { display: flex; align-items: center; justify-content: space-between; padding: 0.4em 1em; background: #16182a; color: #8b8fa3; font-size: 0.72em; font-family: var(--xpe-font-mono, ui-monospace, monospace); text-transform: lowercase; }
 .db-code pre { margin: 0; padding: 1.1em 1.25em; background: #1e1e2e; color: #cdd6f4; overflow-x: auto; font-size: 0.85em; line-height: 1.7; }
 .db-code code { background: none; padding: 0; border: none; font-family: var(--xpe-font-mono, ui-monospace, monospace); }
 .db-divider { border: none; border-top: 1px solid var(--xpe-border); margin: 1.8em 0; }
 .db-figure { margin: 1.4em 0; }
-.db-img { border-radius: 0.75rem; cursor: zoom-in; display: block; margin: 0 auto; height: auto; max-width: 100%; }
+.db-img { border-radius: var(--xpe-radius, 0.75rem); cursor: zoom-in; display: block; margin: 0 auto; height: auto; max-width: 100%; }
 .db-caption { margin-top: 0.5em; text-align: center; font-size: 0.8em; color: var(--xpe-muted-foreground); }
 .db-audio-wrap { background: var(--xpe-muted); border: 1px solid var(--xpe-border); border-radius: var(--xpe-radius, 0.75rem); padding: 0.75rem; }
 .db-audio-wrap audio { width: 100%; }
@@ -289,7 +289,7 @@
    to win the cascade instead of being silently overridden. */
 .xpe-btn .etb { color: inherit; }
 .db-table-wrap { overflow-x: auto; margin: 1.25em 0; }
-.db-table { width: 100%; border-collapse: collapse; border-radius: 0.5rem; overflow: hidden; }
+.db-table { width: 100%; border-collapse: collapse; border-radius: calc(var(--xpe-radius, 0.75rem) * 0.66); overflow: hidden; }
 .db-table th, .db-table td { padding: 0.55em 1em; text-align: start; vertical-align: top; line-height: 1.6; font-size: 0.9em; }
 .db-table th { font-weight: 600; }
 .doc-blocks strong { font-weight: 700; }
diff --git a/packages/react/src/styles/theme.css b/packages/react/src/styles/theme.css
index 2a6d63d..1a14841 100644
--- a/packages/react/src/styles/theme.css
+++ b/packages/react/src/styles/theme.css
@@ -50,3 +50,59 @@
     0 10px 15px -3px rgb(0 0 0 / 0.5),
     0 4px 6px -4px rgb(0 0 0 / 0.4);
 }
+
+/**
+ * Custom scrollbars for the editor's own scrollable surfaces — slim and
+ * token-driven instead of the browser default. Add `.xpe-scroll` to any
+ * other scrollable container you build against these tokens.
+ */
+.xpe-scroll,
+.block-editor,
+.doc-blocks,
+.xpe-popover-content,
+.xpe-emoji-scroll,
+.db-table-wrap,
+.db-code pre {
+  scrollbar-width: thin;
+  scrollbar-color: var(--xpe-border) transparent;
+}
+.xpe-scroll::-webkit-scrollbar,
+.block-editor::-webkit-scrollbar,
+.doc-blocks::-webkit-scrollbar,
+.xpe-popover-content::-webkit-scrollbar,
+.xpe-emoji-scroll::-webkit-scrollbar,
+.db-table-wrap::-webkit-scrollbar,
+.db-code pre::-webkit-scrollbar {
+  width: 10px;
+  height: 10px;
+}
+.xpe-scroll::-webkit-scrollbar-track,
+.block-editor::-webkit-scrollbar-track,
+.doc-blocks::-webkit-scrollbar-track,
+.xpe-popover-content::-webkit-scrollbar-track,
+.xpe-emoji-scroll::-webkit-scrollbar-track,
+.db-table-wrap::-webkit-scrollbar-track,
+.db-code pre::-webkit-scrollbar-track {
+  background: transparent;
+}
+.xpe-scroll::-webkit-scrollbar-thumb,
+.block-editor::-webkit-scrollbar-thumb,
+.doc-blocks::-webkit-scrollbar-thumb,
+.xpe-popover-content::-webkit-scrollbar-thumb,
+.xpe-emoji-scroll::-webkit-scrollbar-thumb,
+.db-table-wrap::-webkit-scrollbar-thumb,
+.db-code pre::-webkit-scrollbar-thumb {
+  background-color: var(--xpe-border);
+  border-radius: 999px;
+  border: 2px solid transparent;
+  background-clip: padding-box;
+}
+.xpe-scroll::-webkit-scrollbar-thumb:hover,
+.block-editor::-webkit-scrollbar-thumb:hover,
+.doc-blocks::-webkit-scrollbar-thumb:hover,
+.xpe-popover-content::-webkit-scrollbar-thumb:hover,
+.xpe-emoji-scroll::-webkit-scrollbar-thumb:hover,
+.db-table-wrap::-webkit-scrollbar-thumb:hover,
+.db-code pre::-webkit-scrollbar-thumb:hover {
+  background-color: var(--xpe-muted-foreground);
+}
diff --git a/packages/vue/src/components/BlockEditor.vue b/packages/vue/src/components/BlockEditor.vue
index fb7ff8e..4f2aa5f 100644
--- a/packages/vue/src/components/BlockEditor.vue
+++ b/packages/vue/src/components/BlockEditor.vue
@@ -2770,6 +2770,7 @@ focusBlock(last.id, 'end')
       :pick-media="pickMedia"
       :editor-dir="editorDir"
       :readonly="readonly"
+      :theme-source="rootEl"
       :class="{ 'opacity-40': draggingId === block.id }"
       :icon-picker-request="iconPickerRequest && iconPickerRequest.blockId === block.id ? { tab: iconPickerRequest.tab } : null"
       @input="(s, c) => handleInput(block, s, c)"
diff --git a/packages/vue/src/components/DocRenderer.vue b/packages/vue/src/components/DocRenderer.vue
index 6a8a76f..1dfdc35 100644
--- a/packages/vue/src/components/DocRenderer.vue
+++ b/packages/vue/src/components/DocRenderer.vue
@@ -487,7 +487,7 @@ function safeVideoEmbedUrl(block: Block): string {
   color: var(--xpe-muted-foreground);
   font-style: italic;
   background: var(--xpe-muted);
-  border-radius: 0.5rem;
+  border-radius: calc(var(--xpe-radius, 0.75rem) * 0.66);
 }
 
 /* --- Callout --- */
@@ -497,7 +497,7 @@ function safeVideoEmbedUrl(block: Block): string {
   gap: 0.7em;
   padding: 0.85em 1.1em;
   margin: 1em 0;
-  border-radius: 0.75rem;
+  border-radius: var(--xpe-radius, 0.75rem);
   border: 1px solid var(--xpe-border);
   background: var(--xpe-muted);
 }
@@ -507,7 +507,7 @@ function safeVideoEmbedUrl(block: Block): string {
 /* --- Code --- */
 .db-code {
   margin: 1.25em 0;
-  border-radius: 0.75rem;
+  border-radius: var(--xpe-radius, 0.75rem);
   overflow: hidden;
   border: 1px solid var(--xpe-border);
 }
@@ -548,7 +548,7 @@ function safeVideoEmbedUrl(block: Block): string {
 /* --- Image --- */
 .db-figure { margin: 1.4em 0; }
 .db-img {
-  border-radius: 0.75rem;
+  border-radius: var(--xpe-radius, 0.75rem);
   cursor: zoom-in;
   display: block;
   margin: 0 auto;
@@ -605,7 +605,7 @@ function safeVideoEmbedUrl(block: Block): string {
 .db-table {
   width: 100%;
   border-collapse: collapse;
-  border-radius: 0.5rem;
+  border-radius: calc(var(--xpe-radius, 0.75rem) * 0.66);
   overflow: hidden;
 }
 .db-table th,
diff --git a/packages/vue/src/components/EditorBlockContextMenu.vue b/packages/vue/src/components/EditorBlockContextMenu.vue
new file mode 100644
index 0000000..0784b9f
--- /dev/null
+++ b/packages/vue/src/components/EditorBlockContextMenu.vue
@@ -0,0 +1,132 @@
+<script setup lang="ts">
+import { ChevronLeft, ChevronRight, Copy, Palette, Trash2 } from 'lucide-vue-next'
+import { nextTick, onBeforeUnmount, onMounted, ref } from 'vue'
+import { syncThemeVars } from '@xproeditor/core'
+
+const props = defineProps<{
+  position: { x: number; y: number }
+  /** Background color swatches — only shown when the block supports one (e.g. callout). */
+  colorPresets?: string[]
+  currentColor?: string
+  themeSource?: HTMLElement | null
+}>()
+
+const emit = defineEmits<{
+  color: [color: string]
+  duplicate: []
+  delete: []
+  close: []
+}>()
+
+const view = ref<'root' | 'color'>('root')
+const menuEl = ref<HTMLElement | null>(null)
+const placed = ref({ left: props.position.x, top: props.position.y })
+
+function place() {
+  const el = menuEl.value
+
+  if (!el) {
+return
+}
+
+  if (props.themeSource) {
+syncThemeVars(props.themeSource, el)
+}
+
+  const margin = 8
+  const { width, height } = el.getBoundingClientRect()
+  const left = Math.max(margin, Math.min(props.position.x, window.innerWidth - width - margin))
+  const top = Math.max(margin, Math.min(props.position.y, window.innerHeight - height - margin))
+  placed.value = { left, top }
+}
+
+function onOutside(e: MouseEvent) {
+  if (!menuEl.value?.contains(e.target as Node)) {
+emit('close')
+}
+}
+
+function onKey(e: KeyboardEvent) {
+  if (e.key === 'Escape') {
+emit('close')
+}
+}
+
+onMounted(() => {
+  nextTick(place)
+  window.addEventListener('mousedown', onOutside, true)
+  window.addEventListener('keydown', onKey)
+})
+
+onBeforeUnmount(() => {
+  window.removeEventListener('mousedown', onOutside, true)
+  window.removeEventListener('keydown', onKey)
+})
+
+function openColor() {
+  view.value = 'color'
+  nextTick(place)
+}
+</script>
+
+<template>
+  <Teleport to="body">
+    <div
+      ref="menuEl"
+      class="xpe-popover-content xpe-scroll fixed z-[80] w-52 overflow-y-auto py-1.5"
+      :style="{ left: `${placed.left}px`, top: `${placed.top}px` }"
+      @mousedown.stop
+    >
+      <template v-if="view === 'root'">
+        <button
+          v-if="colorPresets"
+          type="button"
+          class="flex w-full items-center gap-2.5 px-3 py-1.5 text-start text-[13px] text-[var(--xpe-foreground)] hover:bg-[var(--xpe-surface-hover)]"
+          @click="openColor"
+        >
+          <Palette class="h-3.5 w-3.5 text-[var(--xpe-muted-foreground)]" />
+          <span class="flex-1">Color</span>
+          <ChevronRight class="h-3.5 w-3.5 text-[var(--xpe-muted-foreground)]" />
+        </button>
+        <button
+          type="button"
+          class="flex w-full items-center gap-2.5 px-3 py-1.5 text-start text-[13px] text-[var(--xpe-foreground)] hover:bg-[var(--xpe-surface-hover)]"
+          @click="emit('duplicate'); emit('close')"
+        >
+          <Copy class="h-3.5 w-3.5 text-[var(--xpe-muted-foreground)]" />
+          Duplicate
+        </button>
+        <button
+          type="button"
+          class="flex w-full items-center gap-2.5 px-3 py-1.5 text-start text-[13px] text-[var(--xpe-danger)] hover:bg-[var(--xpe-surface-hover)]"
+          @click="emit('delete'); emit('close')"
+        >
+          <Trash2 class="h-3.5 w-3.5" />
+          Delete
+        </button>
+      </template>
+      <template v-else>
+        <button
+          type="button"
+          class="flex w-full items-center gap-2 px-3 py-1.5 text-start text-[12px] font-medium text-[var(--xpe-muted-foreground)] hover:text-[var(--xpe-foreground)]"
+          @click="view = 'root'"
+        >
+          <ChevronLeft class="h-3.5 w-3.5" />
+          Color
+        </button>
+        <div class="grid grid-cols-7 gap-1.5 px-3 py-1.5">
+          <button
+            v-for="color in colorPresets"
+            :key="color"
+            type="button"
+            class="h-6 w-6 rounded-full border transition-transform hover:scale-110"
+            :class="currentColor === color ? 'border-[var(--xpe-ring)] ring-2 ring-[var(--xpe-ring)]' : 'border-[var(--xpe-border)]'"
+            :style="{ background: color }"
+            :title="color"
+            @click="emit('color', color); emit('close')"
+          />
+        </div>
+      </template>
+    </div>
+  </Teleport>
+</template>
diff --git a/packages/vue/src/components/EditorBlockItem.vue b/packages/vue/src/components/EditorBlockItem.vue
index 627c0bb..8be39b0 100644
--- a/packages/vue/src/components/EditorBlockItem.vue
+++ b/packages/vue/src/components/EditorBlockItem.vue
@@ -12,6 +12,7 @@ import {
   IconValueDisplay,
 } from '../ui'
 import EditorAudioBlock from './EditorAudioBlock.vue'
+import EditorBlockContextMenu from './EditorBlockContextMenu.vue'
 import EditorButtonBlock from './EditorButtonBlock.vue'
 import EditorCodeBlock from './EditorCodeBlock.vue'
 import EditorFileBlock from './EditorFileBlock.vue'
@@ -36,6 +37,7 @@ const props = defineProps<{
   /** Shell / language direction fallback when block dir is auto. */
   editorDir?: 'ltr' | 'rtl'
   readonly?: boolean
+  themeSource?: HTMLElement | null
   /** When set, opens the callout icon picker (slash command / programmatic). */
   iconPickerRequest?: { tab: 'emoji' | 'icon' } | null
 }>()
@@ -73,6 +75,17 @@ const CALLOUT_COLORS = ['#f8fafc', '#fefce8', '#fff7ed', '#fef2f2', '#f0fdf4', '
 const inner = ref<InstanceType<typeof EditorTextBlock> | InstanceType<typeof EditorCodeBlock> | InstanceType<typeof EditorTableBlock> | InstanceType<typeof EditorButtonBlock> | null>(null)
 const calloutIconPickerRef = ref<InstanceType<typeof IconEmojiPicker> | null>(null)
 const showCalloutColors = ref(false)
+const contextMenuPos = ref<{ x: number; y: number } | null>(null)
+
+function onContextMenu(e: MouseEvent) {
+  if (props.readonly) {
+return
+}
+
+  e.preventDefault()
+  emit('select')
+  contextMenuPos.value = { x: e.clientX, y: e.clientY }
+}
 
 const calloutIcon = computed({
   get: () => props.block.props.icon ?? '💡',
@@ -147,6 +160,7 @@ defineExpose({
     :dir="blockDir"
     :style="{ paddingInlineStart: `${indent * 28}px` }"
     @pointerdown="emit('pointerdown', $event)"
+    @contextmenu="onContextMenu"
   >
     <!-- Drop indicator -->
     <div v-if="dropPosition === 'before'" class="ebi-drop -top-[2px]" />
@@ -221,7 +235,7 @@ defineExpose({
         <!-- Callout -->
         <div
           v-else-if="block.type === 'callout'"
-          class="flex items-start gap-2.5 rounded-xl border border-[var(--xpe-border)] px-3.5 py-3"
+          class="flex items-start gap-2.5 rounded-[var(--xpe-radius)] border border-[var(--xpe-border)] px-3.5 py-3"
           :style="{ background: block.props.color ?? 'var(--xpe-muted)' }"
         >
           <div class="relative shrink-0" contenteditable="false" @click.stop @pointerdown.stop>
@@ -258,7 +272,7 @@ defineExpose({
             </button>
             <div
               v-if="showCalloutColors && !readonly"
-              class="absolute start-0 top-full z-[60] mt-1 rounded-xl border border-[var(--xpe-border)] bg-[var(--xpe-surface)] p-2 shadow-xl"
+              class="absolute start-0 top-full z-[60] mt-1 rounded-[var(--xpe-radius)] border border-[var(--xpe-border)] bg-[var(--xpe-surface)] p-2 shadow-xl"
             >
               <div class="flex gap-1">
                 <button
@@ -473,6 +487,18 @@ defineExpose({
         />
       </div>
     </div>
+
+    <EditorBlockContextMenu
+      v-if="contextMenuPos"
+      :position="contextMenuPos"
+      :theme-source="themeSource"
+      :color-presets="block.type === 'callout' ? CALLOUT_COLORS : undefined"
+      :current-color="block.props.color"
+      @color="c => emit('patch', { color: c })"
+      @duplicate="emit('duplicate')"
+      @delete="emit('remove')"
+      @close="contextMenuPos = null"
+    />
   </div>
 </template>
 
diff --git a/packages/vue/src/components/EditorBubbleToolbar.vue b/packages/vue/src/components/EditorBubbleToolbar.vue
index b491775..7d1de2f 100644
--- a/packages/vue/src/components/EditorBubbleToolbar.vue
+++ b/packages/vue/src/components/EditorBubbleToolbar.vue
@@ -70,11 +70,23 @@ const TURN_INTO: Array<{ type: BlockType; label: string; icon: unknown }> = [
 
 const panel = ref<'none' | 'link' | 'color' | 'turninto'>('none');
 const linkInput = ref('');
+let lastPositionKey: string | null = null;
 
 watch(
     () => props.position,
-    () => {
-        panel.value = 'none';
+    (position) => {
+        // `position` is a fresh object on every parent update (e.g. a
+        // same-range selectionchange), so only close an open panel when the
+        // selection actually moved — Vue's default watch compares by
+        // reference, which would close the color/link panel the instant a
+        // swatch inside it is clicked.
+        const key = `${position.x},${position.y}`;
+
+        if (lastPositionKey !== null && lastPositionKey !== key) {
+            panel.value = 'none';
+        }
+
+        lastPositionKey = key;
     },
 );
 
diff --git a/packages/vue/src/components/EditorSlashMenu.vue b/packages/vue/src/components/EditorSlashMenu.vue
index da36e10..7c44d0e 100644
--- a/packages/vue/src/components/EditorSlashMenu.vue
+++ b/packages/vue/src/components/EditorSlashMenu.vue
@@ -182,7 +182,7 @@ defineExpose({ move, confirm })
   <Teleport to="body">
     <div
       ref="menuEl"
-      class="fixed z-[80] w-72 max-h-80 overflow-y-auto border py-1.5 bg-[var(--xpe-surface)] border-[var(--xpe-border)] rounded-[var(--xpe-radius)] [box-shadow:var(--xpe-shadow)]"
+      class="xpe-scroll fixed z-[80] w-72 max-h-80 overflow-y-auto border py-1.5 bg-[var(--xpe-surface)] border-[var(--xpe-border)] rounded-[var(--xpe-radius)] [box-shadow:var(--xpe-shadow)]"
       :style="{ left: `${placed.left}px`, top: `${placed.top}px` }"
       :dir="dir"
       @mousedown.prevent
diff --git a/packages/vue/src/components/EditorTableBlock.vue b/packages/vue/src/components/EditorTableBlock.vue
index 04b10bd..32af3ac 100644
--- a/packages/vue/src/components/EditorTableBlock.vue
+++ b/packages/vue/src/components/EditorTableBlock.vue
@@ -214,7 +214,7 @@ defineExpose({
     </div>
 
     <div class="flex items-start">
-      <div class="flex-1 overflow-x-auto rounded-lg border border-[var(--xpe-border)]" :style="wrapperStyle">
+      <div class="xpe-scroll flex-1 overflow-x-auto rounded-lg border border-[var(--xpe-border)]" :style="wrapperStyle">
         <table class="w-full border-collapse">
           <tbody>
             <tr v-for="(row, rowIdx) in table.rows" :key="rowIdx" class="group/row">
diff --git a/packages/vue/src/components/toolbar/EditorTableStylePanel.vue b/packages/vue/src/components/toolbar/EditorTableStylePanel.vue
index 5a50e29..793ee9f 100644
--- a/packages/vue/src/components/toolbar/EditorTableStylePanel.vue
+++ b/packages/vue/src/components/toolbar/EditorTableStylePanel.vue
@@ -170,14 +170,14 @@ function selectBorderStyle(style: TableBorderStyleKind): void {
                     :key="color"
                     type="button"
                     class="relative flex size-7 items-center justify-center rounded-md border border-black/5 text-xs font-bold"
-                    :class="cn(isPresetActive(color, currentColor) && 'ring-2 ring-indigo-500 ring-offset-1')"
+                    :class="cn(isPresetActive(color, currentColor) && 'ring-2 ring-[var(--xpe-ring)] ring-offset-1')"
                     :style="{ color }"
                     @click="selectTextColor(color)"
                 >
                     A
                     <Check
                         v-if="isPresetActive(color, currentColor)"
-                        class="absolute -top-1 -end-1 size-3 rounded-full bg-[var(--xpe-primary-muted)]0 p-0.5 text-white"
+                        class="absolute -top-1 -end-1 size-3 rounded-full bg-[var(--xpe-primary)] p-0.5 text-[var(--xpe-primary-foreground)]"
                     />
                 </button>
             </div>
@@ -189,7 +189,7 @@ function selectBorderStyle(style: TableBorderStyleKind): void {
                     :key="color"
                     type="button"
                     class="relative size-7 rounded-md border border-black/10"
-                    :class="cn(isPresetActive(color, currentHighlight) && 'ring-2 ring-indigo-500 ring-offset-1')"
+                    :class="cn(isPresetActive(color, currentHighlight) && 'ring-2 ring-[var(--xpe-ring)] ring-offset-1')"
                     :style="{ backgroundColor: color }"
                     @click="selectHighlight(color)"
                 />
@@ -223,7 +223,7 @@ function selectBorderStyle(style: TableBorderStyleKind): void {
                     :key="color"
                     type="button"
                     class="relative size-7 rounded-md border border-black/10"
-                    :class="cn(isPresetActive(color, cellBackground) && 'ring-2 ring-indigo-500 ring-offset-1')"
+                    :class="cn(isPresetActive(color, cellBackground) && 'ring-2 ring-[var(--xpe-ring)] ring-offset-1')"
                     :style="{ backgroundColor: color }"
                     @click="selectCellBackground(color)"
                 />
@@ -249,7 +249,7 @@ function selectBorderStyle(style: TableBorderStyleKind): void {
                     :key="`table-${color}`"
                     type="button"
                     class="relative size-7 rounded-md border border-black/10"
-                    :class="cn(isPresetActive(color, tableStyle?.background) && 'ring-2 ring-indigo-500 ring-offset-1')"
+                    :class="cn(isPresetActive(color, tableStyle?.background) && 'ring-2 ring-[var(--xpe-ring)] ring-offset-1')"
                     :style="{ backgroundColor: color }"
                     @click="selectTableBackground(color)"
                 />
@@ -262,7 +262,7 @@ function selectBorderStyle(style: TableBorderStyleKind): void {
                     :key="`header-${color}`"
                     type="button"
                     class="relative size-7 rounded-md border border-black/10"
-                    :class="cn(isPresetActive(color, tableStyle?.headerBackground) && 'ring-2 ring-indigo-500 ring-offset-1')"
+                    :class="cn(isPresetActive(color, tableStyle?.headerBackground) && 'ring-2 ring-[var(--xpe-ring)] ring-offset-1')"
                     :style="{ backgroundColor: color }"
                     @click="selectHeaderBackground(color)"
                 />
@@ -290,7 +290,7 @@ function selectBorderStyle(style: TableBorderStyleKind): void {
                     :key="color"
                     type="button"
                     class="relative size-7 rounded-md border-2 bg-[var(--xpe-surface)]"
-                    :class="cn(isPresetActive(color, resolvedBorder.color) && 'ring-2 ring-indigo-500 ring-offset-1')"
+                    :class="cn(isPresetActive(color, resolvedBorder.color) && 'ring-2 ring-[var(--xpe-ring)] ring-offset-1')"
                     :style="{ borderColor: color }"
                     @click="selectBorderColor(color)"
                 />
diff --git a/packages/vue/src/components/toolbar/EditorToolbarColorPanel.vue b/packages/vue/src/components/toolbar/EditorToolbarColorPanel.vue
index 26a1cbb..b109fae 100644
--- a/packages/vue/src/components/toolbar/EditorToolbarColorPanel.vue
+++ b/packages/vue/src/components/toolbar/EditorToolbarColorPanel.vue
@@ -135,7 +135,7 @@ function isPresetActive(color: string, active: string | null): boolean {
                     :class="
                         cn(
                             isPresetActive(color, activeTextColor) &&
-                                'ring-2 ring-indigo-500 ring-offset-1',
+                                'ring-2 ring-[var(--xpe-ring)] ring-offset-1',
                         )
                     "
                     :style="{ color }"
@@ -145,7 +145,7 @@ function isPresetActive(color: string, active: string | null): boolean {
                     A
                     <Check
                         v-if="isPresetActive(color, activeTextColor)"
-                        class="absolute -top-1 -end-1 size-3 rounded-full bg-[var(--xpe-primary-muted)]0 p-0.5 text-white"
+                        class="absolute -top-1 -end-1 size-3 rounded-full bg-[var(--xpe-primary)] p-0.5 text-[var(--xpe-primary-foreground)]"
                     />
                 </button>
             </div>
@@ -187,7 +187,7 @@ function isPresetActive(color: string, active: string | null): boolean {
                     :class="
                         cn(
                             isPresetActive(color, activeHighlight) &&
-                                'ring-2 ring-indigo-500 ring-offset-1',
+                                'ring-2 ring-[var(--xpe-ring)] ring-offset-1',
                         )
                     "
                     :style="{ backgroundColor: color }"
@@ -196,7 +196,7 @@ function isPresetActive(color: string, active: string | null): boolean {
                 >
                     <Check
                         v-if="isPresetActive(color, activeHighlight)"
-                        class="absolute -top-1 -end-1 size-3 rounded-full bg-[var(--xpe-primary-muted)]0 p-0.5 text-white"
+                        class="absolute -top-1 -end-1 size-3 rounded-full bg-[var(--xpe-primary)] p-0.5 text-[var(--xpe-primary-foreground)]"
                     />
                 </button>
             </div>
diff --git a/packages/vue/src/styles/theme.css b/packages/vue/src/styles/theme.css
index f2fe722..e65389b 100644
--- a/packages/vue/src/styles/theme.css
+++ b/packages/vue/src/styles/theme.css
@@ -50,3 +50,59 @@
     0 10px 15px -3px rgb(0 0 0 / 0.5),
     0 4px 6px -4px rgb(0 0 0 / 0.4);
 }
+
+/**
+ * Custom scrollbars for the editor's own scrollable surfaces — slim and
+ * token-driven instead of the browser default. Add `.xpe-scroll` to any
+ * other scrollable container you build against these tokens.
+ */
+.xpe-scroll,
+.block-editor,
+.doc-blocks,
+.xpe-popover-content,
+.xpe-emoji-scroll,
+.db-table-wrap,
+.db-code pre {
+  scrollbar-width: thin;
+  scrollbar-color: var(--xpe-border) transparent;
+}
+.xpe-scroll::-webkit-scrollbar,
+.block-editor::-webkit-scrollbar,
+.doc-blocks::-webkit-scrollbar,
+.xpe-popover-content::-webkit-scrollbar,
+.xpe-emoji-scroll::-webkit-scrollbar,
+.db-table-wrap::-webkit-scrollbar,
+.db-code pre::-webkit-scrollbar {
+  width: 10px;
+  height: 10px;
+}
+.xpe-scroll::-webkit-scrollbar-track,
+.block-editor::-webkit-scrollbar-track,
+.doc-blocks::-webkit-scrollbar-track,
+.xpe-popover-content::-webkit-scrollbar-track,
+.xpe-emoji-scroll::-webkit-scrollbar-track,
+.db-table-wrap::-webkit-scrollbar-track,
+.db-code pre::-webkit-scrollbar-track {
+  background: transparent;
+}
+.xpe-scroll::-webkit-scrollbar-thumb,
+.block-editor::-webkit-scrollbar-thumb,
+.doc-blocks::-webkit-scrollbar-thumb,
+.xpe-popover-content::-webkit-scrollbar-thumb,
+.xpe-emoji-scroll::-webkit-scrollbar-thumb,
+.db-table-wrap::-webkit-scrollbar-thumb,
+.db-code pre::-webkit-scrollbar-thumb {
+  background-color: var(--xpe-border);
+  border-radius: 999px;
+  border: 2px solid transparent;
+  background-clip: padding-box;
+}
+.xpe-scroll::-webkit-scrollbar-thumb:hover,
+.block-editor::-webkit-scrollbar-thumb:hover,
+.doc-blocks::-webkit-scrollbar-thumb:hover,
+.xpe-popover-content::-webkit-scrollbar-thumb:hover,
+.xpe-emoji-scroll::-webkit-scrollbar-thumb:hover,
+.db-table-wrap::-webkit-scrollbar-thumb:hover,
+.db-code pre::-webkit-scrollbar-thumb:hover {
+  background-color: var(--xpe-muted-foreground);
+}
diff --git a/packages/vue/src/ui/Button.vue b/packages/vue/src/ui/Button.vue
index e2e74c3..173bf6d 100644
--- a/packages/vue/src/ui/Button.vue
+++ b/packages/vue/src/ui/Button.vue
@@ -34,7 +34,7 @@ withDefaults(
   align-items: center;
   justify-content: center;
   gap: 6px;
-  border-radius: 8px;
+  border-radius: calc(var(--xpe-radius, 12px) * 0.66);
   border: 1px solid transparent;
   font-weight: 500;
   cursor: pointer;
diff --git a/packages/vue/src/ui/ColorPickerPanel.vue b/packages/vue/src/ui/ColorPickerPanel.vue
index c18ba2b..cf0f46b 100644
--- a/packages/vue/src/ui/ColorPickerPanel.vue
+++ b/packages/vue/src/ui/ColorPickerPanel.vue
@@ -59,7 +59,7 @@ function onNativeColorInput(event: Event): void {
   height: 32px;
   padding: 0;
   border: 1px solid var(--xpe-border, #e5e7eb);
-  border-radius: 8px;
+  border-radius: calc(var(--xpe-radius, 12px) * 0.66);
   cursor: pointer;
   background: none;
 }
@@ -67,7 +67,7 @@ function onNativeColorInput(event: Event): void {
   flex: 1;
   height: 32px;
   border: 1px solid var(--xpe-border, #e5e7eb);
-  border-radius: 8px;
+  border-radius: calc(var(--xpe-radius, 12px) * 0.66);
   padding: 0 8px;
   font-size: 12px;
   font-family: var(--xpe-font-mono, ui-monospace, monospace);
diff --git a/packages/vue/src/ui/DropdownMenuItem.vue b/packages/vue/src/ui/DropdownMenuItem.vue
index 3314e16..781c7e4 100644
--- a/packages/vue/src/ui/DropdownMenuItem.vue
+++ b/packages/vue/src/ui/DropdownMenuItem.vue
@@ -20,7 +20,7 @@ const ctx = inject(popoverContextKey)
   padding: 6px 10px;
   border: none;
   background: transparent;
-  border-radius: 6px;
+  border-radius: calc(var(--xpe-radius, 12px) * 0.5);
   font-size: 13px;
   color: var(--xpe-foreground, #374151);
   cursor: pointer;
diff --git a/packages/vue/src/ui/Input.vue b/packages/vue/src/ui/Input.vue
index 6dbc54a..15a55fc 100644
--- a/packages/vue/src/ui/Input.vue
+++ b/packages/vue/src/ui/Input.vue
@@ -13,7 +13,7 @@ const model = defineModel<string>({ default: '' })
 <style scoped>
 .xpe-input {
   width: 100%;
-  border-radius: 8px;
+  border-radius: calc(var(--xpe-radius, 12px) * 0.66);
   border: 1px solid var(--xpe-border, #e5e7eb);
   padding: 0 10px;
   font-size: 13px;
diff --git a/packages/vue/src/ui/PopoverContent.vue b/packages/vue/src/ui/PopoverContent.vue
index 09541eb..cfaa801 100644
--- a/packages/vue/src/ui/PopoverContent.vue
+++ b/packages/vue/src/ui/PopoverContent.vue
@@ -121,7 +121,7 @@ onBeforeUnmount(() => {
 <style scoped>
 .xpe-popover-content {
   z-index: 80;
-  border-radius: 12px;
+  border-radius: var(--xpe-radius, 12px);
   border: 1px solid var(--xpe-muted, #f3f4f6);
   background: var(--xpe-surface, #fff);
   box-shadow:
diff --git a/packages/vue/src/ui/TabsList.vue b/packages/vue/src/ui/TabsList.vue
index 717f7a7..0a5b899 100644
--- a/packages/vue/src/ui/TabsList.vue
+++ b/packages/vue/src/ui/TabsList.vue
@@ -9,7 +9,7 @@
   display: grid;
   gap: 4px;
   background: var(--xpe-muted, #f3f4f6);
-  border-radius: 8px;
+  border-radius: calc(var(--xpe-radius, 12px) * 0.66);
   padding: 3px;
 }
 </style>
diff --git a/packages/vue/src/ui/TabsTrigger.vue b/packages/vue/src/ui/TabsTrigger.vue
index fc8621f..4fa8679 100644
--- a/packages/vue/src/ui/TabsTrigger.vue
+++ b/packages/vue/src/ui/TabsTrigger.vue
@@ -27,7 +27,7 @@ const isActive = computed(() => ctx.active.value === props.value)
 .xpe-tabs-trigger {
   border: none;
   background: transparent;
-  border-radius: 6px;
+  border-radius: calc(var(--xpe-radius, 12px) * 0.5);
   padding: 5px 8px;
   font-size: 12px;
   font-weight: 500;
diff --git a/site/src/App.css b/site/src/App.css
index 73fbdd7..b7705af 100644
--- a/site/src/App.css
+++ b/site/src/App.css
@@ -47,6 +47,28 @@
   box-sizing: border-box;
 }
 
+/* Slim, theme-matched scrollbars across the whole site */
+html {
+  scrollbar-width: thin;
+  scrollbar-color: var(--line-strong) transparent;
+}
+::-webkit-scrollbar {
+  width: 10px;
+  height: 10px;
+}
+::-webkit-scrollbar-track {
+  background: transparent;
+}
+::-webkit-scrollbar-thumb {
+  background-color: var(--line-strong);
+  border-radius: 999px;
+  border: 2px solid transparent;
+  background-clip: padding-box;
+}
+::-webkit-scrollbar-thumb:hover {
+  background-color: var(--muted);
+}
+
 html,
 body {
   margin: 0;

From 6fb7a1a0cdffee27c6106c670c379a637037eac8 Mon Sep 17 00:00:00 2001
From: Mohammad Moradi <mohammad.moradi@outlook.com>
Date: Sat, 11 Jul 2026 17:24:32 +0300
Subject: [PATCH 7/7] fix: build and dev

---
 examples/react-demo/vite.config.ts | 2 ++
 examples/vue-demo/vite.config.ts   | 2 ++
 package.json                       | 4 ++--
 site/vite.config.ts                | 2 ++
 4 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/examples/react-demo/vite.config.ts b/examples/react-demo/vite.config.ts
index 04203cb..82a7cba 100644
--- a/examples/react-demo/vite.config.ts
+++ b/examples/react-demo/vite.config.ts
@@ -4,6 +4,8 @@ import { defineConfig } from 'vite'
 export default defineConfig({
   plugins: [react()],
   server: {
+    host: true,
     port: 5174,
+    strictPort: true,
   },
 })
diff --git a/examples/vue-demo/vite.config.ts b/examples/vue-demo/vite.config.ts
index d38f871..ff1658b 100644
--- a/examples/vue-demo/vite.config.ts
+++ b/examples/vue-demo/vite.config.ts
@@ -4,6 +4,8 @@ import { defineConfig } from 'vite'
 export default defineConfig({
   plugins: [vue()],
   server: {
+    host: true,
     port: 5173,
+    strictPort: true,
   },
 })
diff --git a/package.json b/package.json
index 5e0a350..cceb87a 100644
--- a/package.json
+++ b/package.json
@@ -17,8 +17,8 @@
   "scripts": {
     "build": "npm run build -w @xproeditor/core && npm run build -w @xproeditor/vue && npm run build -w @xproeditor/react",
     "build:site": "npm run build -w @xproeditor/core && npm run build -w @xproeditor/react && npm run build -w site",
-    "dev:vue": "npm run build -w @xproeditor/core && npm run build -w @xproeditor/vue && npm run dev -w @xproeditor/vue -w vue-demo",
-    "dev:react": "npm run build -w @xproeditor/core && npm run build -w @xproeditor/react && npm run dev -w @xproeditor/react -w react-demo",
+    "dev:vue": "npm run build -w @xproeditor/core && npm run build -w @xproeditor/vue && npm run dev -w @xproeditor/vue & npm run dev -w vue-demo",
+    "dev:react": "npm run build -w @xproeditor/core && npm run build -w @xproeditor/react && npm run dev -w @xproeditor/react & npm run dev -w react-demo",
     "dev:site": "npm run build -w @xproeditor/core && npm run build -w @xproeditor/react && npm run dev -w site",
     "typecheck": "npm run typecheck --workspaces --if-present",
     "test": "npm run test --workspaces --if-present",
diff --git a/site/vite.config.ts b/site/vite.config.ts
index bebb4e7..6d9ac90 100644
--- a/site/vite.config.ts
+++ b/site/vite.config.ts
@@ -7,6 +7,8 @@ export default defineConfig({
   base: process.env.BASE_PATH ?? '/xproeditor/',
   plugins: [react()],
   server: {
+    host: true,
     port: 5175,
+    strictPort: true,
   },
 })