UI Kit

Theming API

@qalma/kit is Tailwind-first, but your application owns the brand. Provide the token contract once, then override classes or data hooks where your design system needs sharper control.

Tailwind source detection

@qalma/kit does not ship a compiled stylesheet. Its components render Tailwind utility classes, so your app's Tailwind build must scan the installed package. Add this to your global stylesheet, adjusting the relative path if your stylesheet lives somewhere other than src/styles.css.

CSS

@import 'tailwindcss';

/* Adjust the path if your global stylesheet is not src/styles.css. */
@source '../node_modules/@qalma/kit';

CSS variables

The kit reads shadcn-style variables through Tailwind classes. These names are the compatibility contract; their values should come from your product design system.

Token	Used for
--background	Page and editor surface background.
--foreground	Default readable text color.
--card	Buttons, framed previews, and neutral panels.
--card-foreground	Text rendered on card surfaces.
--popover	Floating menus, toolbars, and popovers.
--popover-foreground	Text and icons rendered inside floating surfaces.
--primary	Primary button background.
--primary-foreground	Text and icons on primary buttons.
--secondary	Subtle hover states and neutral fills.
--secondary-foreground	Text rendered on secondary surfaces.
--muted	Quiet backgrounds and code panels.
--muted-foreground	Muted labels, descriptions, and inactive icons.
--accent	Active command, focus, and highlight color.
--accent-foreground	Text and icons rendered on accent backgrounds.
--accent-subtle	Soft active states for selected commands and menu items.
--destructive	Danger actions such as unlink/delete.
--border	Component borders and separators.
--input	Input borders inside popovers.
--ring	Focus-visible rings.
--radius	Shared radius scale for rounded controls.

Tailwind mapping

With Tailwind v4, expose those variables through @theme. The palette below is intentionally generic; replace the values with your own visual identity.

CSS

:root {
  --radius: 0.625rem;
  --background: #ffffff;
  --foreground: #18181b;
  --card: #ffffff;
  --card-foreground: #18181b;
  --popover: #ffffff;
  --popover-foreground: #18181b;
  --primary: #18181b;
  --primary-foreground: #fafafa;
  --secondary: #f4f4f5;
  --secondary-foreground: #27272a;
  --muted: #f4f4f5;
  --muted-foreground: #71717a;
  --accent: #2563eb;
  --accent-foreground: #ffffff;
  --accent-subtle: #dbeafe;
  --destructive: #dc2626;
  --border: #e4e4e7;
  --input: #e4e4e7;
  --ring: #2563eb;
}

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-card: var(--card);
  --color-card-foreground: var(--card-foreground);
  --color-popover: var(--popover);
  --color-popover-foreground: var(--popover-foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  --color-secondary: var(--secondary);
  --color-secondary-foreground: var(--secondary-foreground);
  --color-muted: var(--muted);
  --color-muted-foreground: var(--muted-foreground);
  --color-accent: var(--accent);
  --color-accent-foreground: var(--accent-foreground);
  --color-accent-subtle: var(--accent-subtle);
  --color-destructive: var(--destructive);
  --color-border: var(--border);
  --color-input: var(--input);
  --color-ring: var(--ring);

  --radius-sm: calc(var(--radius) - 4px);
  --radius-md: calc(var(--radius) - 2px);
  --radius-lg: var(--radius);
  --radius-xl: calc(var(--radius) + 4px);
}

Avoiding token conflicts

These token names (--background, --accent, --border…) are the shadcn convention on purpose, so an app that already uses that convention themes the kit for free. There is no --qalma-* prefix. If your app instead defines those exact names on :root for something else, scope the kit's token block to a container that wraps your editor rather than :root. CSS custom properties inherit, so the Tailwind utilities inside that container resolve to your scoped values and never touch the rest of the page.

CSS

/* Scope the token contract to the editor surface instead of :root,
   so it never collides with your app's own --background, --accent, etc. */
.qalma-surface {
  --radius: 0.625rem;
  --background: #ffffff;
  --foreground: #18181b;
  --popover: #ffffff;
  --popover-foreground: #18181b;
  --accent: #2563eb;
  --accent-subtle: #dbeafe;
  --border: #e4e4e7;
  --ring: #2563eb;
  /* …the rest of the token contract… */
}

/* The @theme mapping stays global; only the raw values above are scoped. */
@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-popover: var(--popover);
  --color-accent: var(--accent);
  --color-accent-subtle: var(--accent-subtle);
  --color-border: var(--border);
  --color-ring: var(--ring);
  /* … */
}

Then wrap your editor surface with that class — <div class="qalma-surface"><qalma-editor>…</qalma-editor></div> — and the kit reads the scoped tokens while your app's own :root variables stay untouched.

Override hooks

Most styling should happen through tokens and host classes. These hooks exist for the cases where a product needs targeted overrides.

Hook	Use
.qalma-command-active	Added by QalmaCommand when a toolbar command is active; toolbar buttons style this class.
data-qalma-link-popover	Root element for the link preview/edit popover.
data-qalma-drag-handle	Root element for the floating block drag handle.
data-qalma-dragging-block-highlight	Block highlight displayed during drag sessions.
data-qalma-drag-drop-line	Drop indicator displayed during drag sessions.
data-suggestion-index	Applied to mention/slash options so keyboard navigation can focus an item by index.
data-suggestion-options	Optional scroll container used by slash-command menu active-item scrolling.

Consumer design systems

If your application uses PrimeNG, Angular Material, Kendo, ng-zorro, or another UI stack, the recommended path is still consumer-owned UI: bind your controls directly to editor.execute() and use @qalma/kit only for pieces you actually want to inherit.