API Reference

API Reference

Interactive Surface CSS exposes a class-based API. The package is intentionally small and does not ship JavaScript behavior beyond importing the stylesheet.

Core class

.interactive-surface

Base interaction primitive. Apply this class to any interactive host element that should receive the package's shared state behavior.

Provides:

• base surface appearance
• hover elevation
• focus-visible ring
• pressed feedback
• active/toggled styling
• disabled handling

Size modifiers

.size-sm

Reduces hover and active lift values and uses a smaller shadow profile.

.size-lg

Increases hover and active lift values and uses a larger shadow profile.

Default medium size

There is no .size-md class requirement. Medium behavior is the base default when no size modifier is applied.

State helpers

.is-active

Applies the active/toggled state styling.

.is-disabled

Applies disabled styling and disables interaction by setting pointer-events: none.

Semantic state attributes

[aria-pressed="true"]

Receives the same active styling as .is-active.

[aria-disabled="true"]

Receives the same visual disabled styling as .is-disabled (reduced opacity, no transform or shadow, cursor: not-allowed, pointer-events: none). Unlike native :disabled controls, [aria-disabled="true"] elements can still receive keyboard focus, so the focus ring remains visible when the element is focused via Tab.

:disabled

Native disabled controls also receive disabled styling.

Visual variants

These classes only tune brightness behavior. They do not define complete color themes by themselves.

• .variant-primary
• .variant-secondary
• .variant-accent
• .variant-subtle
• .variant-warning
• .variant-danger

These are best understood as behavioral modifiers layered on top of your own theme tokens.

Icon micro pattern

.icon-only

Optimizes the host element for icon-only controls.

Behavior includes:

• 44px minimum width
• 44px minimum height
• centered inline-flex layout
• adjusted lift and shadow profile
• tighter radius profile

State model summary

The CSS state model is:

• base
• hover / focus-visible
• active / toggled
• press
• disabled

Exported package entry points

• interactive-surface-css
• interactive-surface-css/interactive-surface.css
• interactive-surface-css/package.json
• interactive-surface-css/index.html (primary demo/customization app)
• interactive-surface-css/example.html (backward-compatible alias to index.html)

Non-goals

This package does not provide:

• JavaScript state management
• component rendering helpers
• framework bindings
• layout utilities
• global design tokens