Theming

ParaPort exposes design tokens as CSS variables under the .paraport root and ships its styles in named cascade layers to avoid clashes with host apps. You can theme globally or per instance.

Global CSS layers (recommended)

If your app uses Tailwind or other utility CSS, declare a global layer order and import ParaPort CSS into its own layer to keep utility precedence predictable.

/* e.g., src/styles.css or assets/main.css */
@layer base, components, paraport-base, paraport-components, utilities, paraport-utilities;

/* Import the SDK CSS into the paraport-base layer */
@import '@paraport/vue/style' layer(paraport-base);

/* Optional minimal reset */
@layer base {
  *, *::before, *::after { box-sizing: border-box; }
  body { margin: 0; }
}

Import this stylesheet once in your app entry (Nuxt/Nuxt Content: add to nuxt.config.ts via css: ['~/assets/main.css']).

Tip: Avoid unlayered global resets like * { margin:0 } outside a layer — they will outrank layered utilities and can break spacing.

Per‑instance overrides (appearance)

Override tokens on a single component using the appearance prop (or option) — a map of CSS variables to values.

• Vue (@paraport/vue):

  <Paraport
    :appearance="{ '--radius': '12px', '--accent-blue': '#4f46e5' }"
    themeMode="auto"
    ...
  />
  

• React (@paraport/react):

  <Paraport
    appearance={{ '--radius': '12px', '--accent-blue': '#4f46e5' }}
    themeMode="dark"
    {...otherProps}
  />
  

• Vanilla SDK (@paraport/sdk):

  paraport.init({
    integratedTargetId: 'paraport-root',
    appearance: { '--radius': '12px', '--accent-blue': '#4f46e5' },
    themeMode: 'auto', // 'light' | 'dark' | 'auto'
    ...
  })
  

Common variables include border radii, colors, and surfaces. Inspect the .paraport node in DevTools to discover applied variables.

Theme mode (themeMode)

Control tokens with themeMode:

• auto (default) — follows the system preference. The SDK listens for dark‑mode changes.
• light — forces light tokens.
• dark — forces dark tokens.

Use either globally (by setting variables under .paraport) or per instance via the prop.

Importing styles by framework

• Vue 3: import '@paraport/vue/style' (in main.ts or global stylesheet). For Tailwind, prefer the layered @import approach above.
• React: import '@paraport/react/style' in your root entry. With Tailwind, you may also import the Vue style into a global stylesheet with layer(paraport-base) to control precedence.
• Vanilla SDK: import '@paraport/sdk/style' before init().

Design tokens reference

The full list of CSS variables used by the SDK (tokens and component styles) lives in the Vue package stylesheet:

• https://github.com/exezbcz/paraport/blob/main/packages/vue/src/assets/index.css

Use this as the canonical reference to see available variables and their defaults.

Troubleshooting

• Utilities not applying (e.g., padding classes): ensure a global @layer order is declared and avoid unlayered resets.
• Centering/positioning shifts after adding the plugin: import SDK CSS from your global stylesheet with layer(paraport-base) so Tailwind defaults don’t override your utilities.

Tailwind utility precedence (translate/centering)

If you import @paraport/vue/style from a plugin, it can load after your Tailwind utilities. Tailwind’s universal variables rule inside the SDK (*,::before,::after { --tw-translate-...: 0; }) may then reset translate variables and break centering like -translate-1/2.

Fix: import the SDK CSS earlier and within a named layer so your utilities win:

/* Keep existing order */
@layer base, components, paraport-base, paraport-components, utilities, paraport-utilities;
@import '@paraport/vue/style' layer(paraport-base);

@import 'tailwindcss';
/* your app styles */
@import '@nuxt/ui';
@import './theme-new-york.css';

This preserves Tailwind utility precedence while keeping ParaPort styles safely layered.