tiptapify 0.3.3 → 0.3.4

package/src/skins/builtins.ts

@@ -0,0 +1,81 @@
+import { registerSkin } from './registry'
+
+/*
+ * The built-in skins are registered skins, not special cases: the custom-skin
+ * path resolves through exactly the same chain (spec: anti-goals).
+ * 'default' carries the classic shape and the base tokens, so it emits none.
+ */
+
+export function registerBuiltins(): void {
+  registerSkin('default', {})
+
+  registerSkin('pastel', {
+    toolbar: 'flat',
+    groups: 'flat',
+    buttons: 'quiet',
+    bubble: 'flat',
+    dialog: 'soft',
+    menu: 'soft',
+    colors: {
+      toolbarBg: 'rgba(var(--v-theme-on-surface), 0.03)',
+      toolbarBorderBottom: '1px solid rgba(var(--v-border-color), var(--v-border-opacity))',
+      toolbarFg: 'rgba(var(--v-theme-on-surface), var(--v-high-emphasis-opacity))',
+      groupBg: 'transparent',
+      groupShadow: 'none',
+      dividerColor: 'rgba(var(--v-border-color), var(--v-border-opacity))',
+      buttonFg: 'rgba(var(--v-theme-on-surface), var(--v-medium-emphasis-opacity))',
+      buttonHoverBg: 'rgba(var(--v-theme-on-surface), 0.07)',
+      buttonHoverFg: 'rgba(var(--v-theme-on-surface), var(--v-high-emphasis-opacity))',
+      buttonActiveBg: 'rgba(var(--v-theme-on-surface), 0.1)',
+      buttonActiveHoverBg: 'rgba(var(--v-theme-on-surface), 0.14)',
+      bubbleBorder: '1px solid rgba(var(--v-border-color), var(--v-border-opacity))',
+      bubbleShadow: '0 6px 20px rgba(0, 0, 0, 0.12)',
+      menuBorder: '1px solid rgba(var(--v-border-color), var(--v-border-opacity))',
+      menuShadow: '0 4px 16px rgba(0, 0, 0, 0.08)',
+      menuItemActiveBg: 'rgba(var(--v-theme-on-surface), 0.06)',
+      dialogShadow: '0 20px 48px rgba(0, 0, 0, 0.16), 0 2px 6px rgba(0, 0, 0, 0.06)',
+      frameBg: 'rgb(var(--v-theme-surface))',
+      frameShadow: '0 1px 2px rgba(0, 0, 0, 0.05)',
+      imageBg: 'rgba(var(--v-theme-on-surface), 0.04)',
+      imageOutline: '2px solid rgb(var(--v-theme-primary))',
+      imageOutlineHover: 'rgba(var(--v-theme-primary), 0.35)',
+      handleBg: 'rgb(var(--v-theme-primary))',
+      handleBgHover: 'rgb(var(--v-theme-primary))',
+      handleBorder: '2px solid rgb(var(--v-theme-surface))',
+      handleShadow: '0 0 0 1px rgba(0, 0, 0, 0.15)',
+    },
+    metrics: {
+      itemsPadding: '6px 8px',
+      itemsGap: '6px',
+      itemsRowGap: '4px',
+      groupGap: '2px',
+      groupHeight: 'auto',
+      groupRadius: '0px',
+      dividerWidth: '1px',
+      dividerHeight: '20px',
+      buttonRadius: '6px',
+      bubbleRadius: '10px',
+      bubblePadding: '4px',
+      bubbleGap: '2px',
+      menuListPadding: '4px',
+      menuRadius: '8px',
+      menuItemRadius: '6px',
+      menuItemPadding: '4px 8px',
+      menuItemMinHeight: '34px',
+      dialogRadius: '12px',
+      dialogHeaderPadding: '16px 12px 12px 20px',
+      dialogContentPadding: '4px 20px',
+      dialogActionsPadding: '16px 20px 20px',
+      dialogTitleSize: '1.125rem',
+      dialogTitleWeight: '600',
+      dialogFieldRadius: '8px',
+      dialogActionBtnMinHeight: '38px',
+      dialogActionBtnRadius: '8px',
+      dialogGridGap: '16px',
+      imageRadius: '4px',
+      handleRadius: '50%',
+    },
+  })
+}
+
+registerBuiltins()

package/src/skins/menu.css

@@ -0,0 +1,87 @@
+/*
+ * Menu skin rules (spec 2026-10-18-skins-design.md, "Menu CSS strategy").
+ * Each tiptapify menu wraps its content in SkinScope: the scope div carries
+ * the skin tokens, so the menu rules hang off the content-class element
+ * through it. The soft block rides the `tiptapify-menu--soft` carrier, which
+ * the menu shape flag drives (`shape.menu === 'soft'`); tokens paint it, the
+ * fallbacks are the soft shape's base (the 0.3.3 look). Doubled classes: the
+ * admin theme pads menu lists and items with its own !important rules (the
+ * defense of the base commit).
+ *
+ * The five remaining !importants are the admin-theme defense set, kept
+ * deliberately (spec: "no new !important beyond what exists today"):
+ * - list `padding`, item `margin`, item `padding`: the consumer admin theme
+ *   pads Vuetify lists with its own !important rules (documented in the
+ *   Toolbar/Index.vue comment); token-reading does not beat !important,
+ *   only !important does.
+ * - spacer `width`: the admin theme sizes list spacers; the soft menu owns
+ *   this pixel (icon-to-label gap).
+ * - active item `color`: the admin theme repaints active list items
+ *   (`.v-list-item--active { color: ... !important }`-style rules); the
+ *   soft menu's high-emphasis text is part of the skin contract.
+ * Everything else (border, radius, shadow, min-height, active background) is
+ * plain specificity: the doubled classes + scope segment (0-5-0+) outrank
+ * Vuetify's component rules and need no !important.
+ */
+
+/*
+ * Classic skin: Vuetify's own `.v-menu > .v-overlay__content > .v-list` radius/elevation
+ * is a child rule (0-3-0), and the scope div inserts itself between them, so the child
+ * combinator no longer matches. This restoration rule re-arms those two pixels for the
+ * default menu (0-4-0 beats what the content class alone gets), reading the menu tokens
+ * with the fixture-canonical classic fallbacks. Under the soft shape the block below
+ * paints the same properties from the shape's base (equal specificity, later source order).
+ * The classic menu list is therefore a skin rule today: the reachability note "classic
+ * menu metrics = native Vuetify" holds for the item pixels only.
+ */
+.tiptapify-menu > .tiptapify-skin-scope > .v-list.v-list {
+  border-radius: var(--tf-menu-radius, 4px);
+  box-shadow: var(--tf-menu-shadow, 0 5px 5px -3px rgba(0, 0, 0, 0.2), 0 8px 10px 1px rgba(0, 0, 0, 0.14), 0 3px 14px 2px rgba(0, 0, 0, 0.12));
+}
+
+.tiptapify-menu--soft > .tiptapify-skin-scope > .v-list.v-list {
+  padding: var(--tf-menu-list-padding, 4px) !important;
+  border: var(--tf-menu-border, 1px solid rgba(var(--v-border-color), var(--v-border-opacity)));
+  border-radius: var(--tf-menu-radius, 8px);
+  box-shadow: var(--tf-menu-shadow, 0 4px 16px rgba(0, 0, 0, 0.08));
+}
+
+.tiptapify-menu--soft > .tiptapify-skin-scope > .v-list.v-list > .v-list-item.v-list-item {
+  min-height: var(--tf-menu-item-min-height, 34px);
+  margin: 0 !important;
+  padding: var(--tf-menu-item-padding, 4px 8px) !important;
+  border-radius: var(--tf-menu-item-radius, 6px);
+  color: rgba(var(--v-theme-on-surface), var(--v-high-emphasis-opacity));
+}
+
+.tiptapify-menu--soft > .tiptapify-skin-scope > .v-list.v-list > .v-list-item.v-list-item .v-list-item__prepend > .v-icon {
+  margin-inline-end: 0;
+  opacity: 0.6;
+}
+
+.tiptapify-menu--soft > .tiptapify-skin-scope > .v-list.v-list > .v-list-item.v-list-item .v-list-item__spacer {
+  width: 10px !important;
+}
+
+.tiptapify-menu--soft > .tiptapify-skin-scope > .v-list.v-list > .v-list-item.v-list-item .v-list-item-title {
+  font-size: 14px;
+  font-weight: 500;
+}
+
+.tiptapify-menu--soft > .tiptapify-skin-scope > .v-list.v-list > .v-list-item.v-list-item.v-list-item--active {
+  background: var(--tf-menu-item-active-bg, rgba(var(--v-theme-on-surface), 0.06));
+  color: rgba(var(--v-theme-on-surface), var(--v-high-emphasis-opacity)) !important;
+}
+
+.tiptapify-menu--soft > .tiptapify-skin-scope > .v-list.v-list > .v-list-item.v-list-item.v-list-item--active > .v-list-item__overlay {
+  opacity: 0;
+}
+
+/* The list-style grid inside the soft menu; the feature layout stays in ListStyleButton.vue */
+.tiptapify-menu--soft > .tiptapify-skin-scope > .tiptapify-list-style-grid {
+  padding: 6px;
+  border: 1px solid rgba(var(--v-border-color), var(--v-border-opacity));
+  border-radius: 8px;
+  background: rgb(var(--v-theme-surface));
+  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.08);
+}

package/src/skins/menu.ts

@@ -0,0 +1,10 @@
+/*
+ * The shared `content-class` of the four tiptapify menus (heading, align,
+ * bullet, list-styles): the base class plus the soft menu carrier, which
+ * anchors the soft menu rules in src/skins/menu.css through the SkinScope
+ * wrapper. Driven by the menu shape flag (`shape.menu === 'soft'`), not the
+ * skin name: a custom skin extending pastel keeps the carrier.
+ */
+export function menuContentClass(menuSoft: boolean): string {
+  return menuSoft ? 'tiptapify-menu tiptapify-menu--soft' : 'tiptapify-menu'
+}

package/src/skins/registry.test.ts

@@ -0,0 +1,180 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { registerSkin, defineSkin, resolveSkin, resetSkins, registeredSkins, CLASSIC_SHAPE } from '@tiptapify/skins/registry'
+import { baseColors, baseMetrics, skinColorKeys, skinMetricKeys, cssVarName } from '@tiptapify/skins/tokens'
+import { registerBuiltins } from '@tiptapify/skins/builtins'
+
+describe('skin registry', () => {
+  beforeEach(() => {
+    resetSkins()
+    registerBuiltins()
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('resolves the default skin to the classic shape and emits no tokens', () => {
+    const skin = resolveSkin('default')
+
+    expect(skin.name).toBe('default')
+    expect(skin.className).toBe('tiptapify-skin-default')
+    expect(skin.shape).toEqual(CLASSIC_SHAPE)
+    expect(skin.tokens).toEqual({})
+  })
+
+  it('resolves the pastel skin to the quiet shape with its tokens', () => {
+    const skin = resolveSkin('pastel')
+
+    expect(skin.shape).toEqual({
+      toolbar: 'flat', groups: 'flat', buttons: 'quiet',
+      bubble: 'flat', dialog: 'soft', menu: 'soft',
+    })
+    expect(skin.tokens['--tf-toolbar-bg']).toBe('rgba(var(--v-theme-on-surface), 0.03)')
+    expect(skin.tokens['--tf-button-radius']).toBe('6px')
+    expect(skin.tokens['--tf-dialog-grid-gap']).toBe('16px')
+  })
+
+  it('falls back to default for an unregistered name with a dev warning', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+    const skin = resolveSkin('nope')
+
+    expect(skin.name).toBe('default')
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('nope'))
+  })
+
+  it('merges an inline skin over the default base', () => {
+    const skin = resolveSkin({ colors: { toolbarBg: 'rebeccapurple' }, metrics: { groupRadius: '10px' } })
+
+    expect(skin.className).toBe('tiptapify-skin-inline')
+    expect(skin.tokens['--tf-toolbar-bg']).toBe('rebeccapurple')
+    expect(skin.tokens['--tf-group-radius']).toBe('10px')
+    expect(skin.shape).toEqual(CLASSIC_SHAPE)
+  })
+
+  it('drops an override that equals the base value (emit-skip-equal-to-base)', () => {
+    // a skin that re-states the classic values is a twin of default: nothing to emit
+    registerSkin('twin', {
+      colors: { toolbarBg: baseColors.toolbarBg, handleBg: baseColors.handleBg },
+      metrics: { itemsGap: baseMetrics.itemsGap, buttonRadius: '9px' },
+    })
+
+    const skin = resolveSkin('twin')
+
+    // the base-valued keys are excluded; the one real override rides through
+    expect(skin.tokens).toEqual({ '--tf-button-radius': '9px' })
+  })
+
+  it('inherits shape and tokens through extends, own members win', () => {
+    registerSkin('mint', {
+      extends: 'pastel',
+      colors: { toolbarBg: 'rgba(0, 128, 0, 0.05)', handleBg: 'rgb(0, 100, 0)' },
+      metrics: { dialogRadius: '14px' },
+    })
+
+    const skin = resolveSkin('mint')
+
+    expect(skin.shape).toEqual(resolveSkin('pastel').shape)
+    expect(skin.tokens['--tf-toolbar-bg']).toBe('rgba(0, 128, 0, 0.05)')
+    expect(skin.tokens['--tf-handle-bg']).toBe('rgb(0, 100, 0)')
+    expect(skin.tokens['--tf-dialog-radius']).toBe('14px')
+    // untouched pastel tokens are inherited
+    expect(skin.tokens['--tf-button-radius']).toBe('6px')
+  })
+
+  it('an inline object may extend a registered skin', () => {
+    const skin = resolveSkin({ extends: 'pastel', metrics: { bubbleRadius: '2px' } })
+
+    expect(skin.className).toBe('tiptapify-skin-inline')
+    expect(skin.shape.bubble).toBe('flat')
+    expect(skin.tokens['--tf-bubble-radius']).toBe('2px')
+    expect(skin.tokens['--tf-bubble-padding']).toBe('4px')
+  })
+
+  it('ignores unknown token keys in dev with a warning', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+    const skin = resolveSkin({ colors: { notAToken: 'red' } as never })
+
+    expect(skin.tokens['--tf-not-a-token']).toBeUndefined()
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('notAToken'))
+  })
+
+  it('resolves a missing extends to default with a dev warning', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+    const skin = resolveSkin({ extends: 'ghost' })
+
+    expect(skin.shape).toEqual(CLASSIC_SHAPE)
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('ghost'))
+  })
+
+  it('resolves a circular extends chain to default with a dev warning', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    registerSkin('a', { extends: 'b' })
+    registerSkin('b', { extends: 'a' })
+
+    const skin = resolveSkin('a')
+
+    expect(skin.name).toBe('a')
+    expect(skin.shape).toEqual(CLASSIC_SHAPE)
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('a'))
+  })
+
+  it('inline skins never enter the global registry', () => {
+    resolveSkin({ name: 'mint', colors: { toolbarBg: 'green' } })
+
+    expect(registeredSkins()).not.toContain('mint')
+    const registered = registerSkin('mint', { colors: { toolbarBg: 'lime' } })
+    expect(registered).toBeUndefined()
+    expect(registeredSkins()).toContain('mint')
+  })
+
+  it('defineSkin is identity typed', () => {
+    const cfg = defineSkin({ extends: 'pastel', metrics: { itemsPadding: '1px 2px' } })
+
+    expect(cfg).toEqual({ extends: 'pastel', metrics: { itemsPadding: '1px 2px' } })
+  })
+
+  it('emits css variables only for keys present in the typed catalogs', () => {
+    expect(cssVarName('toolbarBg')).toBe('--tf-toolbar-bg')
+    expect(cssVarName('itemsRowGap')).toBe('--tf-items-row-gap')
+    expect(skinColorKeys.length).toBeGreaterThan(10)
+    expect(skinMetricKeys.length).toBeGreaterThan(10)
+    // every catalog key has a base value
+    for (const key of skinColorKeys) expect(typeof baseColors[key]).toBe('string')
+    for (const key of skinMetricKeys) expect(typeof baseMetrics[key]).toBe('string')
+  })
+})
+
+describe('skin registry without builtins', () => {
+  // The registry used standalone (no builtins.ts load): 'default' is the implicit
+  // root of every extends chain, so walking to it must not warn about a missing link
+  beforeEach(() => {
+    resetSkins()
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('treats the implicit default root as present, no dev warning', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+    const skin = resolveSkin({ extends: 'default', colors: { toolbarBg: 'red' } })
+    const inline = resolveSkin({ colors: { toolbarBg: 'blue' } })
+
+    expect(skin.shape).toEqual(CLASSIC_SHAPE)
+    expect(skin.tokens['--tf-toolbar-bg']).toBe('red')
+    expect(inline.tokens['--tf-toolbar-bg']).toBe('blue')
+    expect(warn).not.toHaveBeenCalled()
+  })
+
+  it('still warns for a genuinely missing extends link', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+    resolveSkin({ extends: 'ghost' })
+
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('ghost'))
+  })
+})

package/src/skins/registry.ts

@@ -0,0 +1,132 @@
+import { TiptapifyShape, TiptapifySkinConfig, TiptapifySkinInput } from '@tiptapify/types/editor'
+import { baseColors, baseMetrics, skinColorKeys, skinMetricKeys, cssVarName } from './tokens'
+
+export type ResolvedSkin = {
+  name: string
+  // root class for the escape hatch: `tiptapify-skin-{name}`
+  className: string
+  shape: Required<TiptapifyShape>
+  // css variable name -> value; only overrides, base values are the css fallbacks
+  tokens: Record<string, string>
+}
+
+// The classic structure: every skin resolves over it (base tokens → extends chain → own)
+export const CLASSIC_SHAPE: Required<TiptapifyShape> = {
+  toolbar: 'raised',
+  groups: 'box',
+  buttons: 'vuetify',
+  bubble: 'card',
+  dialog: 'classic',
+  menu: 'vuetify',
+}
+
+const registry = new Map<string, TiptapifySkinConfig>()
+
+export function registerSkin(name: string, skin: TiptapifySkinConfig): void {
+  registry.set(name, { ...skin, name })
+}
+
+// Identity for typed const definitions; the object never enters the registry
+export function defineSkin(skin: TiptapifySkinConfig): TiptapifySkinConfig {
+  return skin
+}
+
+export function registeredSkins(): string[] {
+  return [...registry.keys()]
+}
+
+// Dev/test isolation: drop all registrations
+export function resetSkins(): void {
+  registry.clear()
+}
+
+const devWarn = (msg: string) => {
+  if (import.meta.env.DEV) console.warn(`[tiptapify] ${msg}`)
+}
+
+const isConfig = (skin: TiptapifySkinInput): skin is TiptapifySkinConfig => typeof skin === 'object' && skin !== null
+
+const SHAPE_KEYS = ['toolbar', 'groups', 'buttons', 'bubble', 'dialog', 'menu'] as const
+
+// Walk the extends chain root-first: [default, base…, self]. A missing link
+// resolves to the accumulated chain (warn); a cycle resolves to classic (warn).
+// 'default' is the implicit root of every chain: a bare registry without the
+// builtins must not warn about walking to it.
+function chainOf(config: TiptapifySkinConfig): { chain: TiptapifySkinConfig[], cyclic: boolean } {
+  const chain: TiptapifySkinConfig[] = []
+  const visited = new Set<string>()
+  let link: string | undefined = config.extends ?? 'default'
+  while (link) {
+    if (visited.has(link)) return { chain, cyclic: true }
+    visited.add(link)
+    const registered = registry.get(link)
+    if (!registered) {
+      if (link !== 'default') devWarn(`skin extends "${link}" is not registered; resolving without it`)
+      break
+    }
+    chain.unshift(registered)
+    link = registered.extends ?? 'default'
+    if (link === 'default' && registered.name === 'default') break
+  }
+  return { chain, cyclic: false }
+}
+
+export function resolveSkin(skin?: TiptapifySkinInput): ResolvedSkin {
+  let config: TiptapifySkinConfig
+  let name: string
+
+  if (skin === undefined || skin === null || skin === '') {
+    config = {}
+    name = 'default'
+  } else if (typeof skin === 'string') {
+    const registered = registry.get(skin)
+    if (!registered) {
+      devWarn(`unknown skin "${skin}"; falling back to "default"`)
+      config = {}
+      name = 'default'
+    } else {
+      config = registered
+      name = skin
+    }
+  } else {
+    config = skin
+    name = config.name ?? 'inline'
+  }
+
+  const { chain, cyclic } = chainOf(config)
+  if (cyclic) devWarn(`circular "extends" in skin "${name}"; falling back to classic`)
+
+  // base: classic shape + classic tokens (not emitted — they are the css fallbacks)
+  const shape: Required<TiptapifyShape> = { ...CLASSIC_SHAPE }
+  const colors: Record<string, string> = {}
+  const metrics: Record<string, string> = {}
+  const sources = cyclic ? [] : [...chain, config]
+  for (const source of sources) {
+    for (const key of SHAPE_KEYS) {
+      const value = source[key]
+      if (value) shape[key] = value as never
+    }
+    for (const [key, value] of Object.entries(source.colors ?? {})) {
+      if (!skinColorKeys.includes(key as never)) {
+        devWarn(`unknown skin color token "${key}" on skin "${name}"; ignored`)
+        continue
+      }
+      if (value !== undefined) colors[key] = value
+    }
+    for (const [key, value] of Object.entries(source.metrics ?? {})) {
+      if (!skinMetricKeys.includes(key as never)) {
+        devWarn(`unknown skin metric token "${key}" on skin "${name}"; ignored`)
+        continue
+      }
+      if (value !== undefined) metrics[key] = value
+    }
+  }
+
+  const tokens: Record<string, string> = {}
+  for (const [key, value] of Object.entries({ ...colors, ...metrics })) {
+    const base = (baseColors as Record<string, string>)[key] ?? (baseMetrics as Record<string, string>)[key]
+    if (value !== base) tokens[cssVarName(key)] = value
+  }
+
+  return { name, className: `tiptapify-skin-${name}`, shape, tokens }
+}

package/src/skins/tokens.reachability.test.ts

@@ -0,0 +1,43 @@
+import { readFileSync } from 'node:fs'
+import { describe, expect, it } from 'vitest'
+import { skinColorKeys, skinMetricKeys, cssVarName } from '@tiptapify/skins/tokens'
+
+/*
+ * Reachability contract guard (spec 2026-10-18-skins-design.md, task 7): every catalog
+ * token must have at least one CSS consumer in the skin layer. Gating is per shape:
+ * quiet-button tokens are consumed under the quiet gates, menu-soft tokens under the
+ * `--soft` menu rules, dialog-soft tokens under the `--soft` dialog rules, and the
+ * default-path tokens in the base rules — this guard checks consumption, the fixture
+ * gate (skin-baseline.json) checks the painted result.
+ *
+ * Parsing the SOURCE files (not dist): the source is where a token can be dropped;
+ * dist adds noise (bundling, minification) and is produced by the build anyway.
+ */
+const SOURCES = [
+  '../components/Tiptapify.vue',
+  '../components/Toolbar/Index.vue',
+  '../components/Toolbar/Items.vue',
+  '../components/MenuBubble.vue',
+  '../components/ImageBubbleMenu.vue',
+  '../components/UI/TiptapifyDialog.vue',
+  './menu.css',
+  '../extensions/components/list/styles/ListStyleButton.vue',
+]
+
+const css = SOURCES.map((file) => readFileSync(new URL(file, import.meta.url), 'utf8')).join('\n')
+
+describe('skin token reachability', () => {
+  for (const key of [...skinColorKeys, ...skinMetricKeys]) {
+    it(`consumes ${cssVarName(key)} (from ${key})`, () => {
+      expect(css).toContain(`var(${cssVarName(key)}`)
+    })
+  }
+
+  it('has no library rule keyed on a built-in skin name (escape hatch has no consumers)', () => {
+    // `.tiptapify-skin-{name}` is the documented escape hatch for consumer CSS; the
+    // library itself gates on shape classes and tokens only (spec: Layered model).
+    const rule = css.match(/\.tiptapify-skin-(pastel|default)\b[^{]*\{/g)
+
+    expect(rule).toBeNull()
+  })
+})

package/src/skins/tokens.ts

@@ -0,0 +1,92 @@
+import { TiptapifySkinColors, TiptapifySkinMetrics } from '@tiptapify/types/editor'
+
+/*
+ * The typed token catalog (public contract; spec 2026-10-18-skins-design.md).
+ * Every skin rule consumes its tokens as CSS custom properties with a fallback
+ * equal to the base (classic) value: the values below. Cells of the spec table
+ * reading "Vuetify" / "VCard elevation" are filled by the committed baseline
+ * fixture (src/skins/__fixtures__/skin-baseline.json) — its measured value
+ * at that selector is canonical and is the fallback stored here.
+ *
+ * Key naming: the camelCase key is the CSS suffix — `groupShadow` ↔
+ * `--tf-group-shadow`. Composite values split by nature: `--tf-items-gap`
+ * expands to `itemsGap` (column) + `itemsRowGap` (the classic row gap).
+ * Colors are paint (including full border shorthands and shadows); lengths,
+ * paddings, gaps, radii, min-heights are metrics.
+ */
+
+// Base values = the classic look. Button tokens paint only when the shape
+// activates the quiet buttons; the classic values below are the native vuetify
+// rendering the fixture measures (reachability contract: inert under
+// buttons:'vuetify'). The quiet/pastel values ship with the pastel skin.
+export const baseColors: TiptapifySkinColors = {
+  toolbarBg: 'rgb(var(--v-theme-surface))',
+  toolbarBorderBottom: 'none',
+  toolbarFg: 'inherit',
+  groupBg: 'rgb(var(--v-theme-surface))',
+  groupShadow: '0 3px 1px -2px var(--v-shadow-key-umbra-opacity, rgba(0, 0, 0, 0.2)), 0 2px 2px 0 var(--v-shadow-key-penumbra-opacity, rgba(0, 0, 0, 0.14)), 0 1px 5px 0 var(--v-shadow-key-ambient-opacity, rgba(0, 0, 0, 0.12))',
+  dividerColor: 'transparent',
+  buttonFg: 'inherit',
+  buttonHoverBg: 'rgba(var(--v-theme-on-surface), var(--v-hover-opacity))',
+  buttonHoverFg: 'inherit',
+  buttonActiveBg: 'rgb(var(--v-theme-primary))',
+  buttonActiveHoverBg: 'rgb(var(--v-theme-primary))',
+  bubbleBg: 'rgb(var(--v-theme-surface))',
+  bubbleBorder: 'none',
+  bubbleShadow: '4px 4px 20px var(--dark-gray)',
+  menuBorder: 'none',
+  menuShadow: '0 5px 5px -3px rgba(0, 0, 0, 0.2), 0 8px 10px 1px rgba(0, 0, 0, 0.14), 0 3px 14px 2px rgba(0, 0, 0, 0.12)',
+  menuItemActiveBg: 'rgba(0, 0, 0, 0)',
+  dialogShadow: '0 11px 15px -7px rgba(0, 0, 0, 0.2), 0 24px 38px 3px rgba(0, 0, 0, 0.14), 0 9px 46px 8px rgba(0, 0, 0, 0.12)',
+  frameBg: 'transparent',
+  frameShadow: 'none',
+  // the classic frame: a hairline around the editor, the toolbar edge on top of it (border-top removed by the rule)
+  frameBorder: '1px solid rgba(var(--v-border-color), var(--v-border-opacity))',
+  imageBg: 'transparent',
+  imageOutline: '1px solid rgba(0, 0, 0, 0.25)',
+  imageOutlineHover: 'transparent',
+  handleBg: 'rgba(0, 0, 0, 0.5)',
+  handleBgHover: 'rgba(0, 0, 0, 0.8)',
+  handleBorder: 'none',
+  handleShadow: 'none',
+}
+
+export const baseMetrics: TiptapifySkinMetrics = {
+  itemsPadding: '12px 16px',
+  itemsGap: '0px',
+  itemsRowGap: '5px',
+  groupGap: '0px',
+  groupHeight: '32px',
+  groupRadius: '4px',
+  dividerWidth: '0px',
+  dividerHeight: '0px',
+  buttonRadius: '4px',
+  bubbleRadius: '6px',
+  bubblePadding: '0px',
+  bubbleGap: '0px',
+  menuListPadding: '8px 0px',
+  menuRadius: '4px',
+  menuItemRadius: '0px',
+  menuItemPadding: '4px 16px',
+  menuItemMinHeight: '40px',
+  dialogRadius: '4px',
+  dialogHeaderPadding: '8px 16px',
+  dialogContentPadding: '16px 24px 24px',
+  dialogActionsPadding: '8px',
+  dialogTitleSize: '1.25rem',
+  dialogTitleWeight: '400',
+  dialogFieldRadius: '4px',
+  dialogActionBtnMinHeight: 'auto',
+  dialogActionBtnRadius: '4px',
+  dialogGridGap: '24px',
+  imageRadius: '0.125rem',
+  handleRadius: '2px',
+}
+
+export const skinColorKeys = Object.keys(baseColors) as (keyof TiptapifySkinColors)[]
+export const skinMetricKeys = Object.keys(baseMetrics) as (keyof TiptapifySkinMetrics)[]
+
+// 'toolbarBg' -> '--tf-toolbar-bg', 'itemsRowGap' -> '--tf-items-row-gap'
+export function cssVarName(key: string): string {
+  return '--tf-' + key.replace(/[A-Z]/g, (c) => '-' + c.toLowerCase())
+}