# 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. 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). 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

Add the config (optional) 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 = {
    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, makes no other requests and writes no storage.
- 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`:

- `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
    }
  };
</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.

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.
- `knownLimitations`: known inaccessible parts of the site, in plain language.
- `thirdPartyPages`: `[{ url, description }]`, pages with third-party content (partial conformance is declared for them).
- `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 faults. Remove them when fixed.
- `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 asks for at least two ways to reach the statement, with consistent link names, and 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).

## 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): https://shayach.co.il/configurator/
- Page for AI agents, with a prompt an owner can copy (Hebrew): https://shayach.co.il/agents/