Installation and Usage

Installation and Usage

Installation

npm install interactive-surface-css

Supported import styles

Bundler entry

import "interactive-surface-css";

This works because the package entry file imports interactive-surface.css.

Direct CSS file import

import "interactive-surface-css/interactive-surface.css";

CSS-level import

@import "interactive-surface-css/interactive-surface.css";

No-build CDN usage

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/interactive-surface-css@latest/interactive-surface.css"
/>

Webpack setup

Install CSS loaders:

npm install -D css-loader style-loader

Example webpack.config.js rule:

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: ["style-loader", "css-loader"]
      }
    ]
  }
};

Then import in your app entry:

import "interactive-surface-css";

Common usage patterns

Standard action button

<button class="interactive-surface">Submit</button>

Variant-adjusted button

<button class="interactive-surface variant-accent">Learn more</button>

Data attribute surface hooks

<button class="interactive-surface" data-surface-variant="accent" data-surface-level="2">
  Learn more
</button>

Use data attributes when another library, renderer, or design-system adapter assigns semantic surface intent.

Large surface card

<button class="interactive-surface size-lg surface-card">
  <strong>Reusable elevation</strong>
  <span>Keep interaction behavior consistent across surfaces.</span>
</button>

Icon-only micro control

<button class="interactive-surface icon-only" aria-label="Search">
  <svg aria-hidden="true" viewBox="0 0 24 24">...</svg>
</button>

ARIA pressed state

<button class="interactive-surface" aria-pressed="true">Pinned</button>

Disabled state

<button class="interactive-surface" disabled>Unavailable</button>

or

<button class="interactive-surface is-disabled" aria-disabled="true">Unavailable</button>

Framework examples

React

import "interactive-surface-css";

export function SaveButton() {
  return <button className="interactive-surface variant-primary">Save</button>;
}

Vue

<script setup>
import "interactive-surface-css";
</script>

<template>
  <button class="interactive-surface variant-primary">Save</button>
</template>

Svelte

<script>
  import "interactive-surface-css";
</script>

<button class="interactive-surface variant-primary">Save</button>

Using with UI Style Kit CSS

interactive-surface-css and ui-style-kit-css can be used independently or together.

UI Style Kit owns visual theme tokens. Interactive Surface owns interaction behavior on .interactive-surface.

With ui-style-kit-css 2.x, the default full bundle does not include the bridge. Use the opt-in bridge bundle when you want runtime UI switching and Interactive Surface token mapping in one import:

import "ui-style-kit-css/with-bridge.css";
import "interactive-surface-css/interactive-surface.css";

With per-style UI Style Kit imports, include the bridge:

import "ui-style-kit-css/styles/minimal-saas.css";
import "ui-style-kit-css/interactive-surface-bridge";
import "interactive-surface-css/interactive-surface.css";

This order is also supported:

import "interactive-surface-css/interactive-surface.css";
import "ui-style-kit-css/styles/minimal-saas.css";
import "ui-style-kit-css/interactive-surface-bridge";

The bridge maps UI Style Kit theme roles into Interactive Surface tokens. UI Style Kit owns those visual token values; Interactive Surface owns the hover, focus, pressed, selected, disabled, and reduced-motion behavior on .interactive-surface. data-surface-variant and data-surface-level are safe standalone hooks, so bridge-generated markup keeps meaningful interaction behavior without requiring companion class names.

Motion guardrail

interactive-surface owns transform-based motion on the host element.

Avoid applying additional transform, translate, scale, or rotate rules directly to the same node. If you need extra animation, put it on a child element instead.