Merge pull request #7 from Foscat/polished

chore: polish package metadata and README for public release

Updates interaction-state styling and release-facing documentation/metadata in preparation for a public release, with a focus on accessibility and state rendering changes in interactive-surface.css.

Changes:

Refactors hover/focus/active styling to use inset “state layers” (instead of host-level filter) and updates disabled/ARIA-disabled semantics.
Updates README and CHANGELOG to reflect the intended shipped behavior and release notes.
Removes obsolete wiki setup guidance and tweaks the PR template formatting.

Author: Foscat

.github/pull_request_template.md

@@ -1,4 +1,4 @@
-## Summary
+## Summary
 
 Describe the change and why it is needed.
 

CHANGELOG.md

@@ -2,13 +2,36 @@
 
 All notable changes to this package are documented in this file.
 
+## 1.1.1 - 2026-04-24
+
+### Improved
+
+- Refined interaction-state rendering to improve accessibility across varied site themes and token sets
+- Replaced whole-element filter-based state styling with safer state-layer treatment
+- Improved disabled-state behavior to better support real-world semantics and integration patterns
+- Strengthened high-contrast handling for `prefers-contrast: more`
+
+### Changed
+
+- Native disabled controls (`:disabled`) and `.is-disabled` now use stricter non-interactive behavior
+- `[aria-disabled="true"]` receives the same visual disabled appearance and sets `pointer-events: none`; keyboard focus is still reachable so the focus ring remains visible
+- Touch feedback now uses a tokenized tap highlight instead of fully removing native tap indication
+
+### Fixed
+
+- Fixed a bug where certain state combinations could cause unintended visual results with specific token sets
+- Reduced the risk of contrast loss caused by whole-element brightness and contrast filters
+- Reduced the chance of child text and icons being unintentionally affected by state styling
+- Softened disabled-state degradation to avoid overly washed-out presentation
+
 ## 1.1.0 - 2026-04-09
 
 - Standardized color usage to functional notation by converting remaining hex fallbacks in `interactive-surface.css` to `rgb(...)`.
 - Added a color-format guard script (`npm run check:no-hex-colors`) to fail builds when hex literals are introduced in `interactive-surface.css`.
 - Integrated the color-format guard into `prepublishOnly` so release builds validate RGB/HSL notation before publish.
 - Promoted `index.html` as the primary demo/customization app, with `example.html` retained as a backward-compatible export alias.
 - Updated docs and wiki guidance for the new color standard, release checklist updates, and demo customization workflow.
+- Updated the README demo section to better highlight the live demo and customization workflow.
 
 ## 1.0.2 - 2026-04-02
 

README.md

@@ -1,8 +1,8 @@
-# Interactive Surface
+# Interactive Surface
 
 Interactive Surface is a framework-agnostic CSS interaction primitive for buttons, cards, icon controls, and similar click targets.
 
-It provides consistent hover, focus-visible, active, press, and disabled behavior with token-driven theming and accessibility guardrails.
+It provides consistent hover, focus-visible, active, press, and disabled behavior with token-driven theming, accessibility guardrails, and minimal integration friction.
 
 ## Documentation
 
@@ -28,8 +28,9 @@ Community and governance docs:
 ## Package
 
 - Package name: `interactive-surface-css`
-- Style entry: `interactive-surface.css`
-- JS entry: `index.js` (imports CSS)
+- Primary stylesheet: `interactive-surface.css`
+- JavaScript entry: `index.js` (imports CSS for bundler-friendly usage)
+- Live demo: `https://foscat.github.io/Interactive-Surface-CSS/`
 
 Install:
 
@@ -49,6 +50,8 @@ Or import CSS directly:
 import "interactive-surface-css/interactive-surface.css";
 ```
 
+Note: The JavaScript entry imports CSS, so it should be used in bundlers or toolchains that support CSS imports. If you want the most portable, framework-agnostic path, import `interactive-surface-css/interactive-surface.css` directly. The package supports both approaches to accommodate different project setups and preferences.
+
 Webpack:
 
 1. Install loaders:
@@ -101,9 +104,9 @@ CDN:
 </button>
 ```
 
-Demo page: `index.html`
+Live demo: [Interactive Surface Demo](https://foscat.github.io/Interactive-Surface-CSS/)
 
-`index.html` is a practical customization playground for this library:
+The demo page is a practical customization playground for this library:
 
 - It provides guided token editing controls instead of freehand CSS typing.
 - It supports importing and exporting token CSS so teams can reuse exact values.

interactive-surface.css

@@ -42,8 +42,25 @@
     var(--shadow-active, 0 6px 18px rgba(0, 0, 0, 0.3), 0 1px 4px rgba(0, 0, 0, 0.2))
   );
 
+  /*
+   * Legacy brightness tokens are preserved, but state rendering now uses
+   * a ::before state-layer pseudo-element instead of host-level filters so
+   * text and icons are less likely to lose contrast in consumer themes.
+   * The state layer is decoupled from box-shadow so shadow tokens set to
+   * `none` (e.g. in prefers-contrast: more) cannot invalidate the
+   * box-shadow declaration.
+   */
   --_is-darken-hover: var(--interactive-surface-darken-hover, var(--surface-darken-hover, 0.96));
   --_is-darken-active: var(--interactive-surface-darken-active, var(--surface-darken-active, 0.98));
+  --_is-state-layer-hover-opacity: var(
+    --interactive-surface-state-layer-hover-opacity,
+    calc(1 - var(--_is-darken-hover))
+  );
+  --_is-state-layer-active-opacity: var(
+    --interactive-surface-state-layer-active-opacity,
+    calc(1 - var(--_is-darken-active))
+  );
+  --_is-state-layer-color: var(--interactive-surface-state-layer-color, rgb(0 0 0));
 
   --_is-motion-default: var(--interactive-surface-motion-default, var(--motion-default, 140ms));
   --_is-motion-press: var(--interactive-surface-motion-press, var(--motion-press, 60ms));
@@ -69,8 +86,10 @@
   --_is-focus-ring-width: var(--interactive-surface-focus-ring-width, 2px);
   --_is-focus-ring-offset: var(--interactive-surface-focus-ring-offset, 2px);
   --_is-disabled-opacity: var(--interactive-surface-disabled-opacity, 0.72);
+  --_is-tap-highlight: var(--interactive-surface-tap-highlight-color, rgb(11 99 246 / 0.18));
 
   position: relative;
+  isolation: isolate;
   box-sizing: border-box;
   border: var(--_is-border-width) solid var(--_is-border-color);
   border-radius: var(--_is-radius);
@@ -82,28 +101,32 @@
   -webkit-appearance: none;
   appearance: none;
   touch-action: manipulation;
-  -webkit-tap-highlight-color: transparent;
+  -webkit-tap-highlight-color: var(--_is-tap-highlight);
+  background-clip: padding-box;
   transform: translateY(var(--_is-lift-base)) translateZ(0) !important;
   box-shadow: var(--_is-shadow-base);
   transition:
     transform var(--_is-motion-default) var(--_is-ease-standard),
     box-shadow var(--_is-motion-default) var(--_is-ease-standard),
-    filter var(--_is-motion-default) linear,
     background-color var(--_is-motion-default) linear,
-    color var(--_is-motion-default) linear;
+    border-color var(--_is-motion-default) linear,
+    color var(--_is-motion-default) linear,
+    outline-color var(--_is-motion-default) linear;
   will-change: auto;
 }
 
-@media (hover: hover) and (pointer: fine) {
-  .interactive-surface {
-    will-change: transform, box-shadow;
-  }
+/* 2a) State-layer pseudo-element */
 
-  .interactive-surface:hover {
-    transform: translateY(var(--_is-lift-hover)) translateZ(0) !important;
-    box-shadow: var(--_is-shadow-hover);
-    filter: brightness(var(--_is-darken-hover));
-  }
+.interactive-surface::before {
+  content: "";
+  position: absolute;
+  inset: 0;
+  border-radius: inherit;
+  background-color: var(--_is-state-layer-color);
+  opacity: 0;
+  pointer-events: none;
+  z-index: -1;
+  transition: opacity var(--_is-motion-default) var(--_is-ease-standard);
 }
 
 /* 3) Keyboard focus visibility */
@@ -119,33 +142,63 @@
   }
 }
 
-.interactive-surface:focus-visible {
+.interactive-surface:not(.is-disabled, :disabled, [aria-disabled="true"]):focus-visible {
   transform: translateY(var(--_is-lift-hover)) translateZ(0) !important;
   box-shadow: var(--_is-shadow-hover);
-  filter: brightness(var(--_is-darken-hover));
+  outline: var(--_is-focus-ring-width) solid var(--_is-focus-ring-color);
+  outline-offset: var(--_is-focus-ring-offset);
+}
+
+.interactive-surface:not(.is-disabled, :disabled, [aria-disabled="true"]):focus-visible::before {
+  opacity: var(--_is-state-layer-hover-opacity);
+}
+
+.interactive-surface[aria-disabled="true"]:focus-visible {
   outline: var(--_is-focus-ring-width) solid var(--_is-focus-ring-color);
   outline-offset: var(--_is-focus-ring-offset);
 }
 
 /* 4) Active and toggled states */
 
-.interactive-surface.is-active,
-.interactive-surface[aria-pressed="true"] {
+.interactive-surface.is-active:not(.is-disabled, [aria-disabled="true"]),
+.interactive-surface[aria-pressed="true"]:not(.is-disabled, :disabled, [aria-disabled="true"]) {
   transform: translateY(var(--_is-lift-active)) translateZ(0) !important;
   box-shadow: var(--_is-shadow-active);
-  filter: brightness(var(--_is-darken-active));
 }
 
-/* 5) Press feedback */
+.interactive-surface.is-active:not(.is-disabled, [aria-disabled="true"])::before,
+.interactive-surface[aria-pressed="true"]:not(.is-disabled, :disabled, [aria-disabled="true"])::before {
+  opacity: var(--_is-state-layer-active-opacity);
+}
+
+/* 5) Pointer hover and press feedback */
+
+@media (hover: hover) and (pointer: fine) {
+  .interactive-surface {
+    will-change: transform, box-shadow;
+  }
+
+  .interactive-surface:not(.is-disabled, :disabled, [aria-disabled="true"]):hover {
+    transform: translateY(var(--_is-lift-hover)) translateZ(0) !important;
+    box-shadow: var(--_is-shadow-hover);
+  }
+
+  .interactive-surface:not(.is-disabled, :disabled, [aria-disabled="true"]):hover::before {
+    opacity: var(--_is-state-layer-hover-opacity);
+  }
+}
 
-.interactive-surface:active {
+.interactive-surface:not(.is-disabled, :disabled, [aria-disabled="true"]):active {
   transform: translateY(var(--_is-lift-base)) translateZ(0) !important;
   box-shadow: var(--_is-shadow-base);
-  filter: brightness(1);
   transition-duration: var(--_is-motion-press);
   transition-timing-function: var(--_is-ease-press);
 }
 
+.interactive-surface:not(.is-disabled, :disabled, [aria-disabled="true"]):active::before {
+  opacity: 0;
+}
+
 /* 6) Size modifiers */
 
 .interactive-surface.size-sm {
@@ -271,17 +324,23 @@
 /* 9) Disabled states */
 
 .interactive-surface.is-disabled,
-.interactive-surface:disabled,
-.interactive-surface[aria-disabled="true"] {
+.interactive-surface:disabled {
   cursor: not-allowed;
   pointer-events: none;
   transform: none !important;
   box-shadow: none;
-  filter: saturate(0.6) contrast(0.9) brightness(0.92);
   opacity: var(--_is-disabled-opacity);
   transition: none;
 }
 
+.interactive-surface[aria-disabled="true"] {
+  cursor: not-allowed;
+  pointer-events: none;
+  transform: none !important;
+  box-shadow: none;
+  opacity: var(--_is-disabled-opacity);
+}
+
 /* Guardrail: this class owns motion on the host element. */
 .interactive-surface,
 .interactive-surface:hover,
@@ -301,14 +360,25 @@
     transition: none;
   }
 
+  .interactive-surface::before {
+    transition: none;
+  }
+
   .interactive-surface:hover,
   .interactive-surface:focus-visible,
   .interactive-surface:active,
   .interactive-surface.is-active,
   .interactive-surface[aria-pressed="true"] {
     transform: none !important;
     box-shadow: none;
-    filter: none;
+  }
+
+  .interactive-surface:hover::before,
+  .interactive-surface:focus-visible::before,
+  .interactive-surface:active::before,
+  .interactive-surface.is-active::before,
+  .interactive-surface[aria-pressed="true"]::before {
+    opacity: 0;
   }
 }
 
@@ -319,6 +389,10 @@
     --interactive-surface-darken-hover: 1;
     --interactive-surface-darken-active: 1;
     --interactive-surface-focus-ring-width: 3px;
+    --interactive-surface-border-width: 2px;
+    --interactive-surface-shadow-base: none;
+    --interactive-surface-shadow-hover: none;
+    --interactive-surface-shadow-active: none;
   }
 }
 
@@ -329,7 +403,10 @@
     color: ButtonText;
     border-color: ButtonText;
     box-shadow: none;
-    filter: none;
+  }
+
+  .interactive-surface::before {
+    display: none;
   }
 
   .interactive-surface:hover,
@@ -339,7 +416,6 @@
   .interactive-surface:active {
     transform: none !important;
     box-shadow: none;
-    filter: none;
   }
 
   .interactive-surface:focus,

wiki/API-Reference.md

@@ -49,7 +49,7 @@ Receives the same active styling as `.is-active`.
 
 ### `[aria-disabled="true"]`
 
-Receives the same disabled styling as `.is-disabled`.
+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`
 

wiki/Token-Reference.md

@@ -27,6 +27,7 @@ These are the primary public tokens:
 - `--interactive-surface-focus-ring-width`
 - `--interactive-surface-focus-ring-offset`
 - `--interactive-surface-disabled-opacity`
+- `--interactive-surface-tap-highlight-color`
 
 ## Legacy fallback tokens
 
@@ -128,5 +129,8 @@ Use these carefully:
 - focus ring width
 - focus ring offset
 - disabled opacity
+- tap highlight color
 
 Avoid reducing focus visibility below practical usability.
+
+`--interactive-surface-tap-highlight-color` controls the native mobile tap flash color applied via `-webkit-tap-highlight-color`. The default is a semi-transparent blue (`rgb(11 99 246 / 0.18)`). Set to `transparent` to suppress the flash entirely (not recommended for touch-only contexts), or set to a brand color to align tap feedback with your theme.