[edonghyun]

Why

The live demo at https://edonghyun.github.io/overlapmark/ showed every feature but read as a dashboard. Toggles, an inspector panel, sliders and a nine-color legend competed with the one thing the library does. Its mixed palette also made deep overlaps under multiply look muddy gray-brown. There was also nowhere to read usage and the API outside the README.

This PR replaces the demo with a two-page static site:

• a white "numbered specimens" demo at /overlapmark/;
• a single-page docs reference at /overlapmark/docs/.

Approach

• One Vite multi-page app in site/. It is renamed from examples/vanilla, because it is no longer an example. Both pages are plain TypeScript and DOM on top of @overlapmark/dom, as the old demo was. A docs framework (VitePress) was considered and dropped, since one reference page doesn't need one.

• The demo follows a mockup the owner picked over a warm-paper alternative:

  • a hero sentence that gains a highlight per button press or selection;
  • then 01 a layers slider, 02 click/Enter listing every covering highlight, 03 preset classes, and 04 framework tabs.

  Color appears only inside highlights.

• The docs. A sticky table of contents, which collapses at narrow widths, beside:

  • Usage;
  • the Highlight type, createHighlighter, options, events;
  • overlap modes, styling, accessibility, SSR, Shadow DOM, limitations and migration.

  Overlap modes, styling and events each have a live example.

• The docs can't drift silently.

  • The options, Highlight fields, events and Highlighter methods tables are typed against the library's exported types (site/src/api-data.ts). An invented or missing option fails pnpm typecheck.
  • A unit test requires every --om-* property in styles.css to be documented.
  • check:readme now also compares the site's quick starts with the README.

• Palette rule. At any character, the stacked colors must lie within a 75° arc of hue. A unit test checks every sample. Mixing complementary hues under multiply is what produced the mud.

• Pages under /overlapmark/. All links are relative. A Playwright suite builds with --base /overlapmark/, serves the build, and fetches every same-origin link and asset on both pages. ci.yml now runs it.

No library code changed.

Trade-offs and known issues

• Merging redeploys the live site. Pages is enabled. To roll back, revert this PR.
• The docs condense Limitations, Migrating and Browser support, and link to the README for the full lists.
• Deferred minors from the final review:
  • a highlight added by selection stays under the browser's selection until you click elsewhere;
  • the code tabs are not the full ARIA tabs pattern (no tabpanel or arrow keys);
  • the last TOC entries may never show as current;
  • @playwright/test comes from the root package.json, not site/package.json;
  • CONTRIBUTING doesn't list the site e2e command.
• Size. +2,889 / −1,765 across 52 files. The deletions are mostly the old demo. Of the additions, 526 lines are tests and about 2,250 are the two pages and their modules.

How to review

1. Shared data:
   • site/src/samples.ts, palette.ts and quick-starts.ts, with their tests;
   • the check-readme.ts change.
2. The demo: site/index.html, site/src/demo.ts and site/e2e/demo.spec.ts.
3. The docs:
   • site/src/api-data.ts, where the facts live; check them against packages/*/src;
   • site/docs/index.html and site/src/docs.ts;
   • site/e2e/docs.spec.ts.
4. Build and deploy:
   • site/vite.config.ts, site/playwright.config.ts and site/e2e/pages.spec.ts;
   • .github/workflows/pages.yml and ci.yml;
   • the .gitignore negation !site/docs/.
5. Safe to skim:
   • docs-assets/*.png, regenerated by pnpm docs:images;
   • pnpm-lock.yaml;
   • the CSS files.

Testing

Local, Node 22.22.0, pnpm 10.26.2, Playwright Chromium. Run on the final head:

• pnpm lint, pnpm format:check, pnpm typecheck, pnpm test, pnpm build and pnpm check:readme: all pass.
• pnpm --filter overlapmark-site test: 45 unit tests pass.
• pnpm --filter overlapmark-site test:e2e: 25 pass against the /overlapmark/ build. They cover:
  • every link and asset resolving;
  • hero button, selection and reset;
  • the layers slider;
  • click and Enter listing layers;
  • presets and tabs;
  • no horizontal scroll at 390px;
  • stages staying white under a dark OS theme;
  • the TOC.

Live controls:

• A root-relative /docs/ link fails the link crawl.
• An invented option and a missing option each fail typecheck.
• A one-character drift in a site quick start fails check:readme.

Each fix from the final review has a test that failed first.

The pages were screenshotted at 1280px and 390px and checked by eye.

Deliberately untested: Firefox and WebKit for the site (the e2e runs Chromium only), and real devices.

Follow-ups

• The deferred minors above.

🤖 Generated with Claude Code