diff --git a/CHANGELOG.md b/CHANGELOG.md index cea58bc..62a9609 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,16 +2,15 @@ All notable changes to this package are documented in this file. -## 1.0.0 - 2026-04-01 +## 1.1.0 - 2026-04-09 -- Initial public package release for `interactive-surface.css` -- Added standalone demo page (`example.html`) -- Added package-local Playwright coverage for: - - state behavior and accessibility media features - - demo rendering and keyboard focus checks -- Added package metadata (`package.json`, exports, scripts, license) +- 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. -## 1.0.2 - 2026-05-01 +## 1.0.2 - 2026-04-02 - Added webpack compatibility via a CommonJS entrypoint (`index.cjs`) and `exports.require` mapping. - Updated package metadata for dual ESM/CommonJS consumption (`main`, `files`, and `sideEffects` updates). @@ -20,3 +19,12 @@ All notable changes to this package are documented in this file. - Added and corrected GitHub templates: issue templates under `.github/ISSUE_TEMPLATE/` and PR template. - Added and aligned comprehensive wiki pages for API, tokens, accessibility, testing, publishing, FAQ, and roadmap. - Reworked README structure for clearer usage, publishing, and documentation navigation. + +## 1.0.0 - 2026-04-01 + +- Initial public package release for `interactive-surface.css` +- Added standalone demo page (`example.html`) +- Added package-local Playwright coverage for: + - state behavior and accessibility media features + - demo rendering and keyboard focus checks +- Added package metadata (`package.json`, exports, scripts, license) diff --git a/README.md b/README.md index 9b472b1..b442852 100644 --- a/README.md +++ b/README.md @@ -81,8 +81,8 @@ Webpack: CDN: ```html - - + + ``` ## Quick Start @@ -101,7 +101,13 @@ CDN: ``` -Demo page: `example.html` +Demo page: `index.html` + +`index.html` 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. +- It helps reduce manual entry mistakes when creating app-level theme overrides. ## Class API @@ -162,6 +168,7 @@ See [Accessibility](./wiki/Accessibility.md) for implementation guidance. ## Testing ```bash +npm run check:no-hex-colors npm run lint:css npm test npm run test:chromium @@ -178,11 +185,11 @@ Release checklist: 2. Bump `version` in `package.json`. 3. Update `CHANGELOG.md`. 4. Push to `main`. -5. Create and publish a GitHub Release tag (for example `v1.0.1`). +5. Create and publish a GitHub Release tag (for example `v1.1.0`). 6. Verify the `Publish to npm` workflow succeeds. 7. Verify CDN availability: - - `https://cdn.jsdelivr.net/npm/interactive-surface-css@1.0.2/interactive-surface.css` - - `https://unpkg.com/interactive-surface-css@1.0.2/interactive-surface.css` + - `https://cdn.jsdelivr.net/npm/interactive-surface-css@/interactive-surface.css` + - `https://unpkg.com/interactive-surface-css@/interactive-surface.css` Manual fallback: diff --git a/example.html b/example.html deleted file mode 100644 index 2661c38..0000000 --- a/example.html +++ /dev/null @@ -1,262 +0,0 @@ - - - - - - Interactive Surface Library Demo - - - - - - -
-
-

Interactive Surface Library

-

- A drop-in CSS interaction primitive for buttons, cards, and icon controls. This demo - shows theme overrides, state helpers, and accessibility-friendly defaults. -

- -
- Standalone defaults - Token override ready - Keyboard focus visible - Reduced-motion aware -
-
- -
-

Buttons and states

-
- - - - - - -
-
- -
-

Card surfaces

-
- - - -
-
- -
-

Icon micro controls

-
- - - - -
-
- -
-

Accessibility highlights

-
    -
  • Focus ring is visible for keyboard users (`:focus-visible` with fallback).
    • -
  • Reduced-motion users get non-animated state transitions.
    • -
  • Forced-colors and high-contrast modes are supported.
    • -
  • Icon-only controls keep a minimum 44px target size.
    • -
-
-
- - diff --git a/index.html b/index.html new file mode 100644 index 0000000..cdd4e93 --- /dev/null +++ b/index.html @@ -0,0 +1,2173 @@ + + + + + + Interactive Surface Library Demo + + + + + + + +
+ +
+

Interactive Surface Library

+

+ A drop-in CSS interaction primitive for buttons, cards, and icon controls. This page + makes each feature visible: token values, state behavior, accessibility outcomes, and + creative ways to compose the same primitive. +

+ +
+ + + Tokens are shown with live values and color codes. +
+
+ + + + + +
+

Token map: color codes and vars

+

+ These are the same variables consumed by interactive-surface.css. Each card + includes the variable and its current value in this demo theme. +

+
+
+
+
+

--interactive-surface-bg

+ +
+

+
+
+
+
+

--interactive-surface-fg

+ +
+

+
+
+
+
+

--interactive-surface-border-color

+ +
+

+
+
+
+
+

--interactive-surface-focus-ring-color

+ +
+

+
+
+
+
+

--accent-main

+ +
+

+
+
+
+
+

--accent-soft

+ +
+

+
+
+
+ + .my-control { --interactive-surface-bg:rgb(15 79 127); --interactive-surface-fg:rgb(244 251 255); + --interactive-surface-focus-ring-color:rgb(30 91 240); } + +
+
+ + + Editing Light theme token overrides. +
+
+ + +
+

Buttons and states

+

Hover, focus, active, pressed, and disabled are all handled by one class.

+
+ + + + + + + + +
+
+ + +
+

Card surfaces

+

The same primitive works for card-like affordances with no extra runtime logic.

+
+ + + + +
+
+ + +
+

Icon micro controls

+

Role-based icon colors can change by mode while keeping a consistent hit target.

+
+
+ +

light-icon: var(--icon-light)

+
+
+ +

dark-icon: var(--icon-dark)

+
+
+ +

accessibility-icon: var(--icon-accessibility)

+
+
+ +

icon-only keeps 44px minimum target

+
+
+ +

disabled + aria-disabled support

+
+
+
+ + +
+

Accessibility highlights

+

+ Side-by-side comparison: left inherits the full interaction/accessibility model; right is a + plain control baseline. +

+
+
+

With interactive-surface

+
+ + + +
+
    +
  • Focus ring is visible with :focus-visible fallback.
    • +
  • Pressed and disabled states map directly to ARIA attributes.
    • +
  • Reduced motion and forced colors are supported by default.
    • +
+
+
+

Plain controls baseline

+
+ + + +
+
    +
  • No unified hover/active model.
    • +
  • No tokenized theming contract.
    • +
  • Requires extra CSS to reach parity with contrast and motion handling.
    • +
+
+
+
+ + +
+

Creative composition ideas

+

Use the same primitive for launcher bars, filters, and dashboard cards.

+
+
+

Command launcher

+
+ +
+
+
+

Filter chip row

+
+ + + +
+
+
+

Playlist card

+ +
+
+
+ + +
+

README and wiki links

+

+ This section mirrors README content so GitHub Pages users can test the library and read docs without + switching pages. +

+
+ + +
+

Loading README.md...

+
+
+
+
+ + + + + + + diff --git a/interactive-surface.css b/interactive-surface.css index 285204b..256c3d9 100644 --- a/interactive-surface.css +++ b/interactive-surface.css @@ -56,8 +56,8 @@ var(--ease-press, cubic-bezier(0.4, 0, 0.6, 1)) ); - --_is-bg: var(--interactive-surface-bg, var(--surface-bg, var(--bg-surface, #f8fafc))); - --_is-fg: var(--interactive-surface-fg, var(--surface-fg, var(--text-primary, #111827))); + --_is-bg: var(--interactive-surface-bg, var(--surface-bg, var(--bg-surface, rgb(248 250 252)))); + --_is-fg: var(--interactive-surface-fg, var(--surface-fg, var(--text-primary, rgb(17 24 39)))); --_is-border-color: var( --interactive-surface-border-color, var(--surface-border, var(--border-color, rgba(15, 23, 42, 0.2))) @@ -65,7 +65,7 @@ --_is-border-width: var(--interactive-surface-border-width, 1px); --_is-radius: var(--interactive-surface-radius, 0.75rem); - --_is-focus-ring-color: var(--interactive-surface-focus-ring-color, var(--focus-ring, #0b63f6)); + --_is-focus-ring-color: var(--interactive-surface-focus-ring-color, var(--focus-ring, rgb(11 99 246))); --_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); @@ -179,6 +179,63 @@ border-radius: 0.5rem; } +/* Optional icon-role hooks for theme toggles and accessibility controls. */ +.interactive-surface.icon-only .light-icon, +.interactive-surface.icon-only [data-icon-role="light"] { + color: var(--interactive-surface-light-icon-color, rgb(212 175 55)); +} + +.interactive-surface.icon-only .dark-icon, +.interactive-surface.icon-only [data-icon-role="dark"] { + color: var(--interactive-surface-dark-icon-color, rgb(0 0 0)); +} + +.interactive-surface.icon-only .accessibility-icon, +.interactive-surface.icon-only [data-icon-role="accessibility"] { + color: var(--interactive-surface-accessibility-icon-color, rgb(59 130 246)); + border-radius: 0; +} + +@media (prefers-color-scheme: dark) { + .interactive-surface.icon-only .light-icon, + .interactive-surface.icon-only [data-icon-role="light"] { + color: var(--interactive-surface-light-icon-color-dark, rgb(255 255 255)); + } + + .interactive-surface.icon-only .dark-icon, + .interactive-surface.icon-only [data-icon-role="dark"] { + color: var(--interactive-surface-dark-icon-color-dark, rgb(30 58 138)); + } + + .interactive-surface.icon-only .accessibility-icon, + .interactive-surface.icon-only [data-icon-role="accessibility"] { + color: var(--interactive-surface-accessibility-icon-color-dark, rgb(156 163 175)); + } +} + +:where([data-theme="dark"], .theme-dark, .dark-mode, .dark) .interactive-surface.icon-only .light-icon, +:where([data-theme="dark"], .theme-dark, .dark-mode, .dark) + .interactive-surface.icon-only + [data-icon-role="light"] { + color: var(--interactive-surface-light-icon-color-dark, rgb(255 255 255)); +} + +:where([data-theme="dark"], .theme-dark, .dark-mode, .dark) .interactive-surface.icon-only .dark-icon, +:where([data-theme="dark"], .theme-dark, .dark-mode, .dark) + .interactive-surface.icon-only + [data-icon-role="dark"] { + color: var(--interactive-surface-dark-icon-color-dark, rgb(30 58 138)); +} + +:where([data-theme="dark"], .theme-dark, .dark-mode, .dark) + .interactive-surface.icon-only + .accessibility-icon, +:where([data-theme="dark"], .theme-dark, .dark-mode, .dark) + .interactive-surface.icon-only + [data-icon-role="accessibility"] { + color: var(--interactive-surface-accessibility-icon-color-dark, rgb(156 163 175)); +} + /* 8) Visual variant token modifiers */ .interactive-surface.variant-primary { diff --git a/package-lock.json b/package-lock.json index c9af631..2cda82d 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "interactive-surface-css", - "version": "1.0.2", + "version": "1.1.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "interactive-surface-css", - "version": "1.0.2", + "version": "1.1.0", "license": "MIT", "devDependencies": { "@playwright/test": "^1.57.0", diff --git a/package.json b/package.json index 89cd54c..8cbf5f3 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "interactive-surface-css", - "version": "1.0.2", + "version": "1.1.0", "description": "A framework-agnostic, accessible CSS interaction primitive for buttons, cards, and icon controls with token-driven theming.", "keywords": [ "css", @@ -41,7 +41,8 @@ }, "./package.json": "./package.json", "./interactive-surface.css": "./interactive-surface.css", - "./example.html": "./example.html" + "./index.html": "./index.html", + "./example.html": "./index.html" }, "sideEffects": [ "./index.js", @@ -52,20 +53,21 @@ "index.js", "index.cjs", "interactive-surface.css", - "README.md", - "CHANGELOG.md", + "*.md", + "wiki", "LICENSE", - "example.html" + "index.html" ], "engines": { "node": ">=18" }, "scripts": { + "check:no-hex-colors": "node ./scripts/check-no-hex-colors.mjs", "lint:css": "stylelint interactive-surface.css", "test": "playwright test --config=./playwright.config.mjs", "test:chromium": "playwright test --config=./playwright.config.mjs --project=chromium", "pack:dry": "npm pack --dry-run --cache ./.npm-cache", - "prepublishOnly": "npm run lint:css && npm test && npm run pack:dry" + "prepublishOnly": "npm run check:no-hex-colors && npm run lint:css && npm test && npm run pack:dry" }, "devDependencies": { "@playwright/test": "^1.57.0", diff --git a/scripts/check-no-hex-colors.mjs b/scripts/check-no-hex-colors.mjs new file mode 100644 index 0000000..c7a2fe4 --- /dev/null +++ b/scripts/check-no-hex-colors.mjs @@ -0,0 +1,36 @@ +import fs from "node:fs"; +import path from "node:path"; +import { fileURLToPath } from "node:url"; + +const __filename = fileURLToPath(import.meta.url); +const __dirname = path.dirname(__filename); +const targetFile = path.resolve(__dirname, "..", "interactive-surface.css"); + +const source = fs.readFileSync(targetFile, "utf8"); +const hexPattern = /#[0-9a-fA-F]{3,8}\b/g; +const lines = source.split(/\r?\n/); +const violations = []; + +lines.forEach((line, index) => { + let match = hexPattern.exec(line); + while (match) { + violations.push({ + line: index + 1, + value: match[0] + }); + match = hexPattern.exec(line); + } + hexPattern.lastIndex = 0; +}); + +if (!violations.length) { + console.log("No hex color literals found in interactive-surface.css."); + process.exit(0); +} + +console.error("Hex color literals are not allowed in interactive-surface.css:"); +violations.forEach((violation) => { + console.error(`- line ${violation.line}: ${violation.value}`); +}); +console.error("Use CSS functional color notation instead (for example, rgb(...), rgb(... / ), or hsl(...))."); +process.exit(1); diff --git a/tests/example.spec.ts b/tests/example.spec.ts index 8d82a87..b6c46af 100644 --- a/tests/example.spec.ts +++ b/tests/example.spec.ts @@ -9,7 +9,7 @@ const packageRoot = path.resolve(__dirname, ".."); const css = fs.readFileSync(path.join(packageRoot, "interactive-surface.css"), "utf8"); const exampleHtml = fs - .readFileSync(path.join(packageRoot, "example.html"), "utf8") + .readFileSync(path.join(packageRoot, "index.html"), "utf8") .replace('', ``); test.describe("example page", () => { @@ -27,6 +27,6 @@ test.describe("example page", () => { test("example exposes a variety of interactive surfaces", async ({ page }) => { const controls = page.locator(".interactive-surface"); - await expect(controls).toHaveCount(13); + await expect(await controls.count()).toBeGreaterThanOrEqual(27); }); }); diff --git a/wiki/API-Reference.md b/wiki/API-Reference.md index 397337b..3a011dd 100644 --- a/wiki/API-Reference.md +++ b/wiki/API-Reference.md @@ -97,7 +97,8 @@ The CSS state model is: - `interactive-surface-css` - `interactive-surface-css/interactive-surface.css` - `interactive-surface-css/package.json` -- `interactive-surface-css/example.html` +- `interactive-surface-css/index.html` (primary demo/customization app) +- `interactive-surface-css/example.html` (backward-compatible alias to `index.html`) ## Non-goals diff --git a/wiki/Contributing.md b/wiki/Contributing.md index cb6dc45..9e7f307 100644 --- a/wiki/Contributing.md +++ b/wiki/Contributing.md @@ -11,11 +11,13 @@ For the full policy and expectations, see: - keep API growth intentional and minimal - preserve accessibility behavior - prefer token-driven extensions over one-off classes +- use functional color notation (`rgb(...)`, `hsl(...)`) instead of hex literals - update docs and tests when behavior changes ## Local Validation ```bash +npm run check:no-hex-colors npm run lint:css npm test npm run pack:dry diff --git a/wiki/FAQ.md b/wiki/FAQ.md index 8431765..cee8aaa 100644 --- a/wiki/FAQ.md +++ b/wiki/FAQ.md @@ -18,6 +18,12 @@ No. The stylesheet does not declare global `:root` tokens. It resolves values in No. The variant classes primarily tune brightness behavior. They are designed to sit on top of your own color tokens. +## Is there a safe way to customize tokens without manual copy/paste errors? + +Yes. Use the package demo app at `index.html`. + +It includes token editing controls and CSS import/export helpers so you can generate a token stylesheet without hand-editing every variable. + ## Can I use it on cards as well as buttons? Yes. That is one of the intended use cases. diff --git a/wiki/Getting-Started.md b/wiki/Getting-Started.md index 304d21f..969c039 100644 --- a/wiki/Getting-Started.md +++ b/wiki/Getting-Started.md @@ -33,14 +33,14 @@ import "interactive-surface-css/interactive-surface.css"; ```html ``` ```html ``` @@ -91,10 +91,10 @@ That one class gives the element: ```css :root { - --interactive-surface-bg: #0f172a; - --interactive-surface-fg: #e2e8f0; - --interactive-surface-border-color: #334155; - --interactive-surface-focus-ring-color: #38bdf8; + --interactive-surface-bg: rgb(15 23 42); + --interactive-surface-fg: rgb(226 232 240); + --interactive-surface-border-color: rgb(51 65 85); + --interactive-surface-focus-ring-color: rgb(56 189 248); --interactive-surface-radius: 12px; } ``` diff --git a/wiki/Home.md b/wiki/Home.md index ce382d1..b9ff8f4 100644 --- a/wiki/Home.md +++ b/wiki/Home.md @@ -31,8 +31,10 @@ Interactive Surface CSS centralizes that logic into a single reusable primitive: - **Package name:** `interactive-surface-css` - **Entry style file:** `interactive-surface.css` - **JS entry:** `index.js` (imports the stylesheet) +- **Demo/customization page:** `index.html` - **License:** MIT -- **Current version in repo:** `1.0.0` +- **Current version in repo:** `1.1.0` +- **Release tag:** `v1.1.0` ## Documentation map diff --git a/wiki/Installation-and-Usage.md b/wiki/Installation-and-Usage.md index 7d08a0b..ff05f06 100644 --- a/wiki/Installation-and-Usage.md +++ b/wiki/Installation-and-Usage.md @@ -33,7 +33,7 @@ import "interactive-surface-css/interactive-surface.css"; ```html ``` diff --git a/wiki/Publishing-and-Releases.md b/wiki/Publishing-and-Releases.md index 1b470cd..c835076 100644 --- a/wiki/Publishing-and-Releases.md +++ b/wiki/Publishing-and-Releases.md @@ -24,13 +24,14 @@ Add this secret in GitHub repository settings: 4. Run local checks: ```bash +npm run check:no-hex-colors npm run lint:css npm test npm run pack:dry ``` 5. Push changes to `main`. -6. Create and publish a GitHub Release for that version tag (for example `v1.0.1`). +6. Create and publish a GitHub Release for that version tag (for example `v1.1.0`). 7. Confirm `Publish to npm` workflow succeeds. 8. Verify distribution: diff --git a/wiki/Testing-and-Quality.md b/wiki/Testing-and-Quality.md index 2e480f4..cab3a22 100644 --- a/wiki/Testing-and-Quality.md +++ b/wiki/Testing-and-Quality.md @@ -5,6 +5,7 @@ The repository includes both CSS linting and Playwright-based behavioral tests. ## Available scripts ```bash +npm run check:no-hex-colors npm run lint:css npm test npm run test:chromium @@ -13,6 +14,10 @@ npm run pack:dry ## What each script does +### `npm run check:no-hex-colors` + +Runs a guard script that fails if hex color literals are present in `interactive-surface.css`. + ### `npm run lint:css` Runs Stylelint against `interactive-surface.css`. @@ -39,7 +44,7 @@ Current Playwright tests validate: - `aria-disabled` non-interactivity - reduced-motion transform removal - icon-only minimum target size -- example page rendering and control count +- index demo page rendering and control count ## Relevant test files @@ -55,6 +60,7 @@ This library is visual and state-driven. Browser-level validation is more useful Run this sequence before publishing: ```bash +npm run check:no-hex-colors npm run lint:css npm test npm run pack:dry @@ -69,4 +75,4 @@ Review the dry-run output and confirm that only intended public files are includ - `README.md` - `CHANGELOG.md` - `LICENSE` -- `example.html` +- `index.html` diff --git a/wiki/Token-Reference.md b/wiki/Token-Reference.md index e0c82d2..4fdf855 100644 --- a/wiki/Token-Reference.md +++ b/wiki/Token-Reference.md @@ -63,15 +63,25 @@ The package does **not** define global `:root` tokens. Instead, values are resolved inline through fallback chains. That makes the stylesheet safer to drop into an existing app without unexpectedly redefining the global token layer. +## Color notation standard + +Use functional color notation for token values: + +- `rgb(255 255 255)` +- `rgb(15 23 42 / 80%)` +- `hsl(200deg 100% 50%)` + +Avoid hex literals in examples and production token files so palette updates are easier to audit and automate. + ## Starter theme example ```css :root { - --interactive-surface-bg: #ffffff; - --interactive-surface-fg: #102a43; - --interactive-surface-border-color: #d5dfe8; + --interactive-surface-bg: rgb(255 255 255); + --interactive-surface-fg: rgb(16 42 67); + --interactive-surface-border-color: rgb(213 223 232); --interactive-surface-radius: 14px; - --interactive-surface-focus-ring-color: #007e8a; + --interactive-surface-focus-ring-color: rgb(0 126 138); --interactive-surface-lift-hover: -4px; --interactive-surface-lift-active: -2px;