| Reference | Value |
|---|---|
| Subject and boundary | Contracts of the five non-visual packages: what each guarantees, what it leaves to the product and how it fails. |
| Verified source | Package READMEs and source under packages/ at tag v0.40.0, including motion policy and headers.ts. Verified tag v0.40.0, commit 43bba26a73dd0f7aa01cb7c8f37d697734b367ad, checked 2026-11-10; earlier pass checked November 7, 2026. |
| Support state | Non-visual package contracts in published v0.40.0. Product configuration and delivery monitoring remain local. |
| Concern | Contract |
|---|---|
| Policy | shouldAnimate(tier, input?) from the root or ./policy combines mount-time motion tiers and optional input capability. Omitting input keeps motion-only behavior. safe-always permits small feedback under reduce; motion-gated disables large/scroll/ambient effects under reduce. |
| Actions | boop, cardParallax, cursorGlow, magnetic, pressBounce, scrollChain, sectionGlow, wordmarkHover. Each guards browser access and cleans up its listeners. magnetic, boop and cursorGlow read duration, easing and colour variables from tokens.css at runtime. |
| GSAP | ./utils/gsap imports ScrollTrigger and SplitText eagerly, but importing it registers nothing. Call initScrollTriggerConfig() before creating a ScrollTrigger (it registers the plugin and sets ignoreMobileResize) and ensureSplitTextRegistered() before SplitText; both are idempotent. loadDrawSVG, loadMorphSVG and loadCustomEase import their plugin on first call. GSAP keeps its own licence (NOTICE). |
| Smooth scroll | initLenis() drives Lenis from the GSAP ticker and bridges ScrollTrigger; it does nothing under reduced motion or on touch. Nested scrollers use scrollChain; wheel-owning elements such as maps use data-lenis-prevent. lenis.css ships in the package and @yesid/ui/base.css imports it. |
| Route transitions | viewTransition for SvelteKit onNavigate crossfades client navigations and skips same-path navigations, browsers without the API and reduced motion. The crossfade CSS lives in UI base.css. |
| Blueprint scrub | blueprintScrub(band, trigger) draws blueprint paths as the trigger scrolls; inactive under reduced motion and at 1023px and below. |
| Opt-in CSS | tap-feedback.css, ripple.css, lenis.css. globalRipple is a utility, not an action; nothing runs or injects CSS on import. |
| Generated tokens | src/tokens.ts comes from the root token build. |
| Product owns | Page choreography, scroll narratives, morphHover, art direction and reduced-motion behavior of its own animations. |
| Input | Mount-time contract |
|---|---|
pointer |
Requires (any-hover: hover) and (any-pointer: fine), including a secondary mouse on a touch-primary device. Used by all six pointer effects. |
touch-only |
Requires touch capability without that pointer capability. Used by pressBounce; it cannot activate alongside boop. |
| Safe-always | boop, cursorGlow, sectionGlow; pressBounce on touch-only devices. |
| Motion-gated | cardParallax, magnetic, wordmarkHover. |
| No browser or matchMedia | Input-gated actions are inert. Changes to input or motion settings take effect at the next initialization/mount. Lenis uses its own touch-device test. |
| Consumer press baseline | Keep tap-press or an intentional CSS alternative. Hybrids use the desktop CSS baseline. Device-table and synthetic hybrid browser tests are emulation, not physical-hardware proof. |
| Subpath | Contract and failure behavior |
|---|---|
./jsonld |
Node builders and serializeJsonLd(nodes): one @graph body with < escaped. Callers own identifiers and schema composition. |
./sitemap |
Alternate-locale entries, XML-escaped sitemap, robotsTxt. Invalid dates are omitted; a robots file without indexing disallows everything. |
./share-copy |
resolveShareCopy(input) (also in the root export) resolves two independent outputs from ordered per-locale content fields: a bounded description (default 50 to 200 code points, optional localized CTA) and the card's ogLine (the full primary text). Each carries rule, candidate and source-locale provenance; a status: 'missing' result needs caller handling. OG_LINE_MAX_LENGTH (200) is the content validation limit. No copy is built in; products write share copy in content fields. |
./og, ./og/fonts, ./og/files |
renderOgPng(card, fonts, rasterize) draws the share card at OG_WIDTH x OG_HEIGHT in the dark token palette with bundled Inter and JetBrains Mono TTFs. The caller injects rasterization. Satori and rasterizer errors reject to the caller. The card draws a 40px/200px blueprint grid behind the content at 0.04/0.07 accent opacity. Card text starts at 32px and steps down using Satori's measured layout to OG_LINE_MIN_FONT_SIZE (24px); text that cannot fit at 24px rejects instead of clipping. |
./icons |
brandMarkSvg(color) and touchIconSvg(ground, color). |
./headers |
SECURITY_HEADERS: two-year HSTS with includeSubDomains and preload, nosniff, strict-origin-when-cross-origin referrer, DENY framing, same-origin COOP and a Permissions-Policy denying listed features. Products serialize their own CSP and own any header overrides; these defaults do not establish deployed product headers. |
./highlight |
Server-only highlight(code, lang) with Shiki's JavaScript regex engine (no WASM), one cached highlighter per process, syn-* classes, unknown languages escaped. There is no per-line time limit (tokenizeTimeLimit: 0), so highlight only content you trust; escaping the output doesn't bound processing time. Not in the root export. |
| Peers | Same-release @yesid/tokens; required satori >=0.33.5 <1; optional shiki >=4 <5 for server highlighting. The product guide pins the sampled Satori version, 0.33.5. |
| Concern | Contract |
|---|---|
| Start | createAnalytics(preset, { domain }) once per page load in the browser; a second start throws. defineAnalyticsPreset({ events }) types the product's custom events. Optional endpoint (a same-origin path such as /relay/e, otherwise it throws) sends events there instead of plausible.io; optional reducePath maps each page path before campaign tags are reduced, and an event is dropped if it throws or returns a non-root-relative path. |
| Relay | ./relay: relayAnalyticsEvent(request, { domain, clientAddress }) serves the endpoint from any Fetch-API runtime. POST only, body at most 4 KiB (RELAY_MAX_BODY_BYTES); the event's domain must match exactly and its page must be on the receiving site or a subdomain, so previews are refused. It forwards once to Plausible with the visitor's user agent and IP, using CF-Connecting-IP only when clientAddress is in Cloudflare's published ranges. 202 on acceptance, 502 on failure or after 5 seconds; no retry and no direct fallback. |
| Silence | Sends nothing without a domain, with a domain that is not one plain host, on a foreign host or without a browser location. Local, preview and fork deployments stay silent when PUBLIC_PLAUSIBLE_DOMAIN is unset. |
| Privacy | Cookieless; no storage writes. Requests carry the path, bounded campaign tags and referrer origin. An unreducible URL drops the event. Custom properties must match the preset's allowlisted keys and values; context is read on every event/pageview. No revenue is sent. Referrer reduction and property filtering are private helpers behind createAnalytics. |
| Web vitals | ./vitals: startVitals({ endpoint, load }) keeps up to 12 samples and sends one beacon on page hide (sendBeacon or keepalive fetch); it never throws. parseVitalsBeacon and parseVitalsSample validate on the receiving endpoint. |
| Product owns | Domain, event catalogue, the relay route if used, CSP connect-src ('self' with the relay endpoint, https://plausible.io without it), whether vitals run and where samples go, delivery monitoring. |
| Concern | Contract |
|---|---|
| Routing | createLocaleRouting: prefix parsing, localize and delocalize, URL-state preservation, locale-switch detection, route-ID normalization. A default locale that is also prefixed throws at construction; only rooted, non-protocol-relative hrefs are localized; exempt paths pass through. |
| Formatting | createIntl returns number, dateTime, collator and plural objects cached per locale and options, plus relativeTime (signed seconds; offsets under 5 seconds use the locale's present-time label; a non-finite offset throws RangeError). |
| Copy | createCopy types every locale against the source locale's keys and function signatures at compile time. |
| SvelteKit | Kit 3 defineParams returns the prefix when valid or undefined. Since Node loads src/params.ts natively, that file uses a dependency-free prefix module rather than importing installed TypeScript from i18n-core. |
| Boundary | No framework import, virtual module, browser state, filesystem or network. Locale context and <html lang> live in @yesid/ui. |
| Concern | Contract |
|---|---|
| Engines | Root export only: filesystem walk, comment stripping, brand hex, style regressions, contrast pairs, identities, dataviz doctrine, Tailwind-variant placement and SEO coverage. Deterministic findings; no test-runner dependency. |
| Policy | The product passes palettes, thresholds, forbidden patterns, allowlists and exclusions from its own gate runner and runs them as lint:design. Rendered contrast is checked in product browser suites; percentage-only color-mix source heuristics are not a contrast proof. |
| Walk limits | Rejects symbolic links and non-regular entries, stays inside the canonical root, sorts paths, and stops beyond 16 levels, 8,192 entries, 4,096 files or 32 MiB. Comment stripping reads at most 1,048,576 UTF-16 code units. |
| Paths | Style-regression hits use src/ plus root-relative paths with / on every OS, including roots with trailing separators. |
| Failure modes | A scan of zero files means the wrong root or extensions, not compliance. The walk cannot protect against a tree rewritten while the caller reads the returned paths. |