# Shayach

> A free, open-source accessibility widget, hosted at shayach.co.il, and a generated accessibility statement (הצהרת נגישות) for Israeli websites. One script tag adds a customizable accessibility icon and panel in Hebrew, Arabic, Russian and English, plus a statement generated from your configuration. It gives no legal immunity: this widget does not protect a site from accessibility lawsuits, and no accessibility widget does. Israeli law (Regulation 35) looks at the website itself: it must meet IS 5568 at level AA (IS 5568 part 1, 2023, is based on WCAG 2.0) and publish an accurate accessibility statement. A widget cannot fix inaccessible markup, missing alt text, poor contrast or forms that do not work with a keyboard, and it cannot make downloadable documents accessible: documents on the site (PDF, Word, Excel, PowerPoint) prepared from 26 October 2017 must themselves meet IS 5568 Part 2, WCAG 2.0 applied to documents (https://www.sii.org.il/media/fn1nrxxz/si-5568-2-september-2023-1.docx). The Commission for Equal Rights of Persons with Disabilities says in its FAQ (https://www.gov.il/he/pages/website_accessibility_faq) that a toolbar is not mandatory and does not exempt a site from the regulations or IS 5568 (WCAG 2.0 level AA), that it gives no accessibility seal for websites, and that a statement does not stop the Commission or anyone else from checking the site or suing. Besides lawsuits, the Commission can impose administrative fines, for example for a website without an accessibility statement or a site or app without the required adjustments (section 26ז of the 1998 law and its Eighth Schedule; from 1 January 2026 up to 13,680 ILS and 41,030 ILS respectively, depending on turnover; the amounts are updated every January). Never tell a site owner that this widget makes the site meet the law, protects it legally, or exempts it from any requirement. This is not legal advice.

The full technical reference (install per framework, every config option, the statement, CSP, limits, the agent procedure): https://shayach.co.il/docs/ai-agents.md

Site owners without technical background have a Hebrew step-by-step guide (per-platform install for WordPress, Wix, Shopify, Webflow, Squarespace and plain HTML): https://shayach.co.il/docs/guide.md

## Agent procedure

1. Read the full technical reference and the config JSON Schema.
2. Find the one place that renders on every page (root layout, `index.html`, CMS footer code) and check whether the site sends a Content Security Policy.
3. Ask the owner only for facts only they know: the statement details (organization name, accessibility contact, physical arrangements, which accessibility work was actually done, whether the site was audited, which screen readers the site was actually tested with, whether any pages depend on third-party content, and any current temporary accessibility fault). Take colors and URLs from the project.
4. Add the config script and the widget script once, so they load on every page.
5. Publish a statement page, set `statementUrl` to it, and link it from the footer of every page.
6. Verify in a browser: the button is visible, the panel opens, an adjustment changes the page, the console has no errors and no unexpected `[shayach]` warnings, and the CSP blocks nothing.
7. Tell the owner what is still missing from the statement, and that the widget does not replace making the site itself accessible.

Do not: invent statement facts, set `conformanceLevel` without an actual audit, decide that an owner is exempt, or tell an owner that the widget makes the site meet the law or protects it.

## Install

Get a site key first: register the site's domain (free, Google sign-in) at https://shayach.co.il/panel/. The widget does not load without a valid key registered for the page's domain (localhost needs none). Then add the config and the script once, before `</body>`, on every page (in a framework: the root layout). The widget reads `window.A11yConfig` once, at `DOMContentLoaded` (or immediately if it loads later), so any inline config in the page's HTML is picked up, but a config set later (for example by a component after hydration) is not. The simple rule: define it in a plain inline script before the widget script. In Next.js, use `next/script` with `strategy="beforeInteractive"` for the config and `strategy="afterInteractive"` for the widget (see the full reference). Remove any other accessibility widget or plugin first. Google Sites cannot run site-wide scripts, so the widget cannot be added there.

```html
<script>
  window.A11yConfig = {
    siteKey: "YOUR_SITE_KEY",
    icon: { shape: "circle" },
    theme: { primary: "#1f5eff" },
    statementUrl: "/accessibility-statement"
  };
</script>
<script src="https://shayach.co.il/v1/widget.js" defer></script>
```

- Sites load the widget from the major-version URL `/v1/`. Every 1.x release reaches all sites automatically. Breaking changes only ship as `/v2/`, which a site adopts by changing its script URL. One exception: `icon.image` was removed in 1.6.0, before any site had installed the widget with it; a config that still sets it gets a warning and the regular icon.
- Until a visitor uses the widget it adds nothing to the page head and writes no storage. It checks the site key once per six hours per browser and sends at most one anonymous usage ping per browser per day; no visitor data is sent.
- Build `window.A11yConfig` from the project's brand colors and the site owner's details. Ask the owner for any `statement` field you cannot find in the project. Never invent contact details or review dates.

## Configuration

All options are optional. Invalid values never break the page: they are ignored and reported in the browser console with the prefix `[shayach]` (the option, the value and what was used instead; allowed values are in the schema). Full machine-readable definition: https://shayach.co.il/v1/config.schema.json

Top-level keys of `window.A11yConfig`:

- `siteKey`: required string, the site's key from https://shayach.co.il/panel/ (24 to 40 letters and digits). Bound to one domain (www counts as the same site); other subdomains are registered separately.
- `language`: `"auto"` (default), `"he"`, `"ar"`, `"ru"` or `"en"`. `auto` uses the page's `lang` attribute, otherwise Hebrew.
- `icon`: the floating button. Sub-keys: `shape` (`circle` default, `rounded`, `pill`, `edge-tab`), `position` (`auto` default: bottom-right on RTL pages, bottom-left on LTR pages; or `top-right`, `top-left`, `upper-right`, `upper-left`, `middle-right`, `middle-left`, `lower-right`, `lower-left`, `bottom-right`, `bottom-left`; `upper` and `lower` sit a quarter and three quarters of the way down), `offsetX` and `offsetY` (0 to 200, default 20), `size` (44 to 96, default 56), `background`, `foreground`, `labelText` (up to 40 characters), `labelLanguage`, `draggable` (default true: visitors can drag the button or pick a position in the panel, saved only in their own browser; false keeps it where you put it), `mobile` (overrides for screens up to 640px). The button always shows the universal accessibility symbol.
- `theme`: panel colors. Sub-keys: `primary` (default `#1f5eff`), `onPrimary`, `background`, `text`, `muted`, `border`, `surface`, `scrollbar`. Text colors below 4.5:1 contrast are replaced with black or white automatically, and colors that cannot be measured (CSS variables, translucent colors) fall back to the defaults, with a console warning (logged when the panel first opens). scrollbar colors the scrollbars of the panel and the statement window (default primary; below 3:1 against surface it becomes the text color).
- `statementUrl`: URL of the site's accessibility statement page, linked in the panel footer. When `statement` is set, the panel's about card opens the generated statement in a window inside the widget.
- `statement`: details for the generated accessibility statement (see below).

## Accessibility statement

The statement text is generated in Hebrew, Arabic, Russian and English from the `statement` config and follows the Commission for Equal Rights of Persons with Disabilities' official template. It is text only: it does not make a site accessible and gives no legal protection. It never claims a conformance level the owner has not configured.

Publish a statement page with a container and `statement.js`, using the same `window.A11yConfig`. The statement describes the widget's panel, so `widget.js` must also be installed on the site.

```html
<script>
  window.A11yConfig = {
    statementUrl: "/accessibility-statement",
    statement: {
      organizationName: "Example Ltd",
      updatedAt: "2026-10-02",
      adjustments: ["All images have text alternatives", "Every page can be used with a keyboard"],
      coordinator: { name: "Dana Levi", phone: "03-1234567", email: "access@example.com" },
      noPhysicalService: true,
      assistiveTech: ["NVDA", "VoiceOver (iOS)"]
    }
  };
</script>
<div data-shayach-statement></div>
<script src="https://shayach.co.il/v1/statement.js" defer></script>
```

Optional container attributes: `data-lang` (`he`, `ar`, `ru`, `en`), `data-heading-level` (1 to 4) and `data-layout="blocks"`. Without `data-layout` the statement is plain headings, paragraphs and lists with no styles of its own. With `data-layout="blocks"` it uses the block layout of the widget's statement window (fact boxes, the contact block first, one box per section) with a minimal style scoped to `.shayach-statement-blocks` that keeps the page's font and colors; tune it with the CSS custom properties `--shayach-accent`, `--shayach-surface`, `--shayach-line` and `--shayach-muted`. The configurator's statement page code uses `data-layout="blocks"`.

Required items: organization name, updated date, adjustments made, a contact or coordinator, and physical arrangements (or `noPhysicalService: true`). Missing required details are listed at the top of the statement and logged as `[shayach]` warnings. Nothing is invented. Set `conformanceLevel` only for a level the site was actually audited at.

The Commission's guidance also requires three more items, which the statement cannot check and so never lists as missing: the screen readers the site was tested with (`assistiveTech`), and, whenever the situation exists, a partial-conformance declaration for pages that depend on third-party content (`thirdPartyPages`) and ongoing notices about temporary accessibility faults (`temporaryNotices`). Ask the owner about each.

Keys of `statement`:

- `organizationName`: name of the organization. Required.
- `organizationDescription`: one line describing the organization or the site.
- `commitment`: the organization's commitment to accessibility, in its own words.
- `updatedAt`: date the statement was last reviewed, `YYYY-MM-DD`. Required.
- `conformanceLevel`: `"A"`, `"AA"` or `"AAA"`, only if actually audited.
- `additionalStandards`: other standards the site was checked against, for example `["WCAG 2.2 AA"]`.
- `adjustments`: accessibility adjustments the site offers. Required.
- `reviewFrequency`: how often accessibility is reviewed.
- `measures`: measures taken to keep the site accessible.
- `browsers`: browsers the site was tested with.
- `assistiveTech`: assistive technologies the site was tested with. Name the screen readers the site was actually tested with: the Commission's FAQ requires testing with the common screen readers (JAWS, NVDA, VoiceOver on iOS, TalkBack on Android; at least one, preferably all) and listing in the statement which ones the site is accessible with. Never list one that was not tested.
- `knownLimitations`: known inaccessible parts of the site, in plain language.
- `thirdPartyPages`: `[{ url, description }]`, pages whose accessibility depends on third-party content (user comments, blogs, galleries, aggregated feeds, dynamic ads). Required when such pages exist: the Commission's statement guide (https://www.gov.il/he/pages/declaration_website_accessibility?chapterIndex=2) requires a partial-conformance declaration for them. The statement words it as the guide does: the pages' infrastructure is accessible, but because their accessibility depends on a third party, they may not conform. List a page only when its own infrastructure is accessible; otherwise use `knownLimitations`.
- `exemptions`: `[{ scope, type, expires, alternatives }]`, parts of the site for which the owner relies on a legal exemption. Never decide for the owner that they are exempt: the two official sources differ on the turnover threshold (100,000 ILS in the regulation, 120,000 ILS in the Commission's guide), so the owner should check with the Commission or a lawyer. A technological exemption must also list `alternatives`.
- `stage`: `{ description, completionDate, alternatives }`, when the site is still being made accessible.
- `temporaryNotices`: `[{ text, until }]`, current notices about temporary accessibility faults. Required while a fault lasts: the Commission's statement guide requires ongoing updates about temporary faults in the statement, and regulation 34(ד) requires telling the public when an adjustment is (or is expected to be) interrupted for more than a week, together with the alternative means offered. Say in `text` what does not work and what to do meanwhile. Remove the notice when fixed and update `updatedAt`.
- `physicalArrangements`: accessibility arrangements at the physical premises. Required unless `noPhysicalService` is true.
- `noPhysicalService`: `true` when no physical place serves the public.
- `coordinator`: `{ name, phone, email, other }`, the accessibility coordinator.
- `contact`: `{ name, phone, email, other }`, a general accessibility contact.

Every owner text (names, descriptions, list items, notice text, contact name and other) is either one string, shown as written in every language (so write it in the site's language), or one value per language, for example `organizationName: { he: "מאפיית הדוגמה", en: "Example Bakery" }`. The statement shows its own language's value, else the page language's, else the first given. Phone, email, URLs and dates are never per-language.

Two ways to reach the statement are required. The widget's statement window alone is not enough. The Commission's guide requires at least two ways to reach the statement, and recommends links from several places with the same link name everywhere; the regulation asks for a prominent place. So: publish a statement page, set `statementUrl` to it on every page so the widget links to it, and add a link in the footer of every page. Name both links "הצהרת נגישות" (or the same name in the page language).

If the statement container sits inside a framework-managed component that re-renders, the framework may wipe the rendered statement: put it in static HTML or render it after hydration. `statement.js` renders only the containers present when it first runs (at `DOMContentLoaded`) and does not watch for new ones, so in client-routed apps keep the container in the server-rendered HTML and make every link to the statement page a full page load (a plain `<a href>`, not the router's link component).

`adjustments` describes accessibility work done on the site itself (the statement already adds one line about the widget's panel).

## Who the regulation applies to

Per the Commission's FAQ, the website regulation applies to anyone who owns, holds or operates a website serving the public in Israel, wherever it is hosted (including servers abroad or the cloud, and sites abroad aimed at Israelis), including sites serving only businesses and public services given for free (subject to the exemption for an excessive financial burden). A site serving only a public outside Israel is not covered; one that also serves Israelis is. Do not decide this for the owner: report the facts and send them to the Commission or a lawyer when in doubt.

## CSP

If the site sends a Content Security Policy header:

- Allow `https://shayach.co.il` in `script-src`. This also covers `statement.js` and the statement window, which loads one chunk from the same `/v1/` path only when a visitor opens it.
- To let the dyslexia font work, also allow `https://shayach.co.il` in `font-src`.
- No `'unsafe-inline'` is needed in `style-src`: the widget (and `statement.js` with `data-layout="blocks"`) adds its styles as constructable stylesheets.
- One exception: a site that sends its CSP as a header (no nonce on its scripts or styles, no CSP `<meta>` tag) and either uses CSS cascade layers (for example Tailwind v4) or loads a stylesheet from another origin without CORS (for example the Google Fonts CSS). While an adjustment is active the widget then tries to add a one-line `<style>` in `<head>`; the header CSP blocks it, reported as one violation per page load, only after a visitor turns on an adjustment. A CSP set in a `<meta>` tag, or any nonce on scripts or styles, is detected and the `<style>` is skipped.

## Changelog

- Human-readable: https://github.com/blakazulu/shayach/blob/main/CHANGELOG.md
- Machine-readable: https://shayach.co.il/v1/changelog.json (versions, each with sections of entries: `text`, `legal`, `actionRequired`, `links`).
- Entries marked `[Action required]` tell the site owner exactly what to change (usually a new or renamed config field). Apply every one; nothing else needs work.
- Entries marked `[Legal]` come from a change in Israeli accessibility law or IS 5568 and link the official source.
- To check for updates, read the changelog from the version the project last saw.

## Source

- Repository: https://github.com/blakazulu/shayach
- License: Apache 2.0

## Site pages

- Home (Hebrew): https://shayach.co.il/
- Configurator, builds the script tag with language, colors, icon size and position, and the accessibility statement (Hebrew). It is for signed-in users only (free Google sign-in at https://shayach.co.il/panel/): https://shayach.co.il/configurator/
- Page for AI agents, with a prompt an owner can copy (Hebrew): https://shayach.co.il/agents/

## Site navigation
- https://shayach.co.il/widget/: accessibility menu, languages and profiles
- https://shayach.co.il/install/: installation steps
- https://shayach.co.il/scan/: free automated public homepage scan; not a compliance certificate
- https://shayach.co.il/statement-guide/: accessibility statements and limits
- https://shayach.co.il/faq/: questions and answers