open-standards/aac/aac-rs/tools/symbols/README.md

Symbol sets

build.py turns three openly licensed symbol sets into one SVG sprite per set plus a concept → symbol index, so that every cell can show a picture. The app build never downloads symbols: it only reads the committed outputs.

set	licence	role
Mulberry Symbols 3.6.1 (commit 9cbab9f4)	CC BY-SA 4.0, and the symbols themselves must never be charged for	default style
OpenMoji 17.0.0 (colour SVG)	CC BY-SA 4.0	second style
Blissymbolics BCI-AV 2026-07-25	CC BY-SA 4.0	third style; covers function words the pictographic sets cannot draw

Licences were checked at the primary sources on 2026-09-29; the URLs and full attribution are in crates/aac-web/public/symbols/LICENSES.md. Proprietary sets (PCS, SymbolStix, Widgit) are never used. Two sets under non-commercial terms, ARASAAC and Sclera, are optional: see "Non-commercial sets" below.

Everything this tool writes from the sets is itself CC BY-SA 4.0, not the workspace's Apache-2.0: the sprites, the contact sheets (review/*.png, each titled with its set's attribution) and mapping-review.md. Mulberry's condition also binds the product: the symbols, and symbols derived from them, must stay free of cost and freely available to all, so they can never sit behind a paid tier or a paid hosted library. Only added value (hosting, curation) may be charged for.

Outputs

path	what
crates/aac-web/public/symbols/<set>.<sha256-12>.svg	sprite: <symbol id="<set>-<concept-slug>" viewBox="…"> per symbol
crates/aac-web/public/symbols/LICENSES.md	attribution for every set
crates/aac-core/src/symbols/index.json	sets (licence, attribution, file) and concept → {set: slug}
crates/aac-core/src/symbols/normalize_cases.json	parity fixture for normalize_concept in Python and Rust
tools/symbols/mapping-review.md	every concept, the symbol each set uses, and how it was chosen
tools/symbols/people-review.md	every symbol that draws a person, and whether it takes the chosen skin tone
tools/symbols/review/<set>.png	contact sheet of every mapped concept, labelled

Board cells are drawn with aac_core::symbols::lookup_for_cell(label, action, preferred) (plain lookup(label, preferred) for a bare word); the sprite file comes from set_info(set).file. Symbol ids carry their set as a prefix (mulberry-home), so sprites can be inlined into one page without clashes; referencing them by file (<use href="symbols/<file>#<id>">) works too.

Rebuilding

cd aac/aac-rs
(cd tools/symbols && npm ci)                            # once: svgo from package-lock.json
python3.14 tools/symbols/build.py                       # everything above
python3.14 tools/symbols/build.py --review-pages /tmp/p # plus 48-per-page sheets for close review
cargo test -p aac-core symbols && cargo test -p aac-web --test symbol_coverage

Needs Python ≥ 3.11 (standard library only), npm (svgo 4.1.0 and its whole dependency tree are pinned by package-lock.json; npm ci installs exactly that into the git-ignored node_modules/, and the build runs it with svgo.config.mjs), rsvg-convert for the contact sheets, and optionally the brotli CLI for size reporting. Sources are downloaded once into tools/symbols/.cache/ (git-ignored) and checked against the SHA-256 pinned in build.py on every run; a mismatch stops the build. The sprites, index, fixture and mapping-review.md are deterministic: rebuilding from the same sources reproduces the same hashes on any machine. The contact sheets depend on the local rasteriser and fonts (committed ones: rsvg-convert 2.63.2 with cairo 1.18.6, pango 1.58.2) and are review aids, not reproducible outputs. A rebuild deletes the previous hashed sprite of each set.

To move to a new release of a set, update its URL and SHA-256 in SOURCES (and the version in SET_INFO), rebuild, and review the contact sheets.

How concepts are mapped

1. Concepts are extracted from the code, not listed by hand: every cell label of every layout in crates/aac-web/src/defaults.rs and every word of the core vocabulary in crates/aac-core/src/vocabulary.rs, normalised with normalize_concept (lowercase, trim, collapse whitespace, strip trailing ?!.,;).
2. Automatic candidates come from each set's own index:
   • Mulberry: the symbol name (eat_,_to → "eat"; numbered variants rank after the plain one). Letters, flags, maps and anatomically rated symbols are excluded — Mulberry's "I" is the letter, not the pronoun.
   • OpenMoji: the CLDR annotation. Tags are listed in mapping-review.md as proposals but never accepted automatically (the tag "you" is on the waving hand). Skin-tone variants, flags and brand logos are excluded — the annotation "apple" is the Apple logo.
   • Bliss: the BCI-AV glosses, first gloss before later ones, verb forms (-(to)) for verbs. Gendered forms, (OLD) forms and letters are excluded. Where a vocabulary word is a verb, verb forms are preferred.
3. overrides.toml decides everything ambiguous, one entry per concept per set with a reason: symbol = "<native id>" or none = true to reject a wrong automatic match. Where one label means different things on different boards, the default-board sense wins ("break" is the rest break of "I need a break", "chicken" is food).
4. Cell concepts. A cell whose picture must come from what it does gets its own concept instead of its label's: message-bar action cells are keyed by their action (action:speakall, action:clear), and navigation cells whose label is a homograph by their navigation sense (nav:back, an arrow; plain back stays the body part of "my back hurts"). cell_concept() in build.py and lookup_for_cell in Rust implement the same rule; add a label to NAV_SENSES when another navigation label needs its own sense.

A wrong picture is worse than none, so a concept stays unmapped in a set unless the match is confident; the runtime then falls back to the next set.

Sprite safety

Each symbol is optimised by svgo (styles inlined into presentation attributes), then rebuilt from an allow-list of drawing elements and attributes: no <script>, <style>, <foreignObject>, <image>, classes, event attributes or external references survive, and internal ids are prefixed with the symbol's slug so symbols sharing the sprite cannot collide. check_sprite() re-verifies the result and the Rust test sprites_exist_and_contain_every_symbol checks it again.

Locale-sensitive choices (Mulberry's beckoning "come", thumbs for good/bad, the left arrow for Back in right-to-left scripts) are listed at the top of overrides.toml for per-locale overrides later.

Known limits: three symbols carry text drawn in the viewer's fallback font (Mulberry's ambulance lettering and runner number, and Bliss 'count').

People

A board is used all over the world, so its people default to no one's skin, gender or age (SPEC §4.3), following Unicode's emoji model:

• Skin. Skin is written as the CSS custom property --aac-skin over a non-realistic neutral, #ffcc22 (UTS #51 §2.4's own example; OpenMoji's lemon #fcea2b would melt into Mulberry's lemon hair, clothes and objects), so a client draws every person in the skin tone the person chooses (aac_core::symbols::SkinTone: OpenMoji's colours for the five modifiers U+1F3FB–U+1F3FF). The neutral colour stays as the fill attribute under the property, so a renderer that ignores the style still draws a person neutral, never black. Hair keeps its colour whatever the tone: no hair colour belongs to a skin tone.
  • Mulberry draws skin in one colour, #ffeec8. Where its authors mark the skin (class="aac-skin-fill"), the build tones exactly those elements. Every other mapped symbol that uses #ffeec8 needs a decision in people.toml, checked on a contact sheet with that colour shown as magenta: tone = true when all of it is skin, tone = false with a reason when some is not (a cake's icing, a computer case). The build stops on a symbol without a decision, and on a decision for a symbol no longer drawn.
  • OpenMoji needs no list: its own skin-tone variants draw the same elements in the same order, so the build tones exactly the elements they change to the skin and shadow colours (--aac-skin, --aac-skin-shade), and leaves a badge that shares the skin's yellow alone. A person Unicode gives no skin tones (a family, a silhouette) is listed as drawn.
• Gender and age. A word that names no gender or age gets a neutral picture: where the default set draws a man's face or a child for such a word, overrides.toml maps it to OpenMoji's emoji face (no gender, age or skin) or to Unicode's gender-neutral person, and the feelings stay one face style. Mulberry's generic figure (bald, shirt and trousers) is kept.

people-review.md lists every symbol that draws a person, and how it is drawn.

Non-commercial sets

ARASAAC and Sclera are licensed for non-commercial use only. A free app with no adverts may offer them, as Cboard and AsTeRICS Grid do; they are never offered in anything paid for, and nothing falls back to them (aac_core::symbols::{SymbolSet::NONCOMMERCIAL, Offering}).

set	licence	source
ARASAAC (Government of Aragón; pictograms by Sergio Palao)	its own: CC BY-NC-SA (per arasaac.org/terms-of-use, no version); our adapted pack: CC BY-NC-SA 4.0	the API's catalogue (api.arasaac.org/v1/pictograms/all/<lang>) and 2500 px renders
Sclera (Sclera vzw)	CC BY-NC 2.0 BE	the sclera.be downloads picto_{en,nl,fr,de}.zip

The terms, read at the sources on 2026-10-10:

• ARASAAC (arasaac.org/terms-of-use): resources "are published under Creative Commons License BY-NC-SA, authorizing their use for non-profit purposes providing the source and the author, and are shared under the same license. Therefore, the use of these resources within any product or publication for commercial purposes is excluded." Derived works "must be distributed with the same Creative Commons License BY-NC-SA. The author (Sergio Palao), the owner (Gobierno de Aragón), their origin (ARASAAC) and the license under which is distributed ... must be cited." The ARASAAC logo is required only on signage of public spaces. Its API "is only available for non-commercial applications."
• Sclera (sclera.be/en/picto/copyright): free use with two conditions, credit "www.sclera.be" as the source, and non-commercial use; commercial use needs a signed agreement. The licence linked there is CC BY-NC 2.0 Belgium, whose section 4 asks for the licence's address with every copy.

Not in this repository. It is mirrored to Codeberg, whose terms of use (§2(1)1) do not accept NC licences, so the pictograms never enter it. build_nc.py writes them, with their review files, to a directory outside:

cd aac/aac-rs
AAC_SYMBOLS_NC_CACHE=/path/to/cache python3.14 tools/symbols/build_nc.py --out ../../../aac-symbol-packs [--refresh]
python3 tools/symbols/check_packs_nc.py ../../../aac-symbol-packs   # what a deployment checks

What is committed here is ours, or a fact about theirs: build_nc.py, overrides-nc.toml (decisions by pictogram number), nc-sources.lock.json (every source file's URL, date and SHA-256; a rebuild stops on any change), crates/aac-core/src/symbols/index-nc.json (the sets, their licences, concept → symbol id, and each pack's name, size and SHA-256), and the NC part of LICENSES.md. Needs Python ≥ 3.11 with PyYAML, Pillow and NumPy, and cwebp (the libwebp version is recorded in the catalogue).

Mapping by meaning. The concepts are build.py's plus the page sets' words (tools/pagesets/data/lexicon.en.yaml) and the symbols the phrase sets ask for (symbol, want_symbol). A candidate's keywords in every language both sides have (23 for ARASAAC; nl, fr and de for Sclera, whose four downloads are joined by identical images) are compared with the app's audited glosses: a match needs an English keyword and at least two other languages agreeing (a quarter of those compared), or, without an English keyword, more than half of at least four. Among equals, ARASAAC's own core-vocabulary pictograms (its aac drawings: a plain figure, no gender or age) are preferred, and a child figure is passed over unless the concept is about children. Sclera's "allowed" (green ground) and "not allowed" (red cross) versions are never used: its file names often omit the qualifier ("eat" is a crossed-out plate).

Checks that stop the build.

• One picture per board. No two concepts on one board may draw the same pictogram: two cells would look the same. The boards are every default board (defaults.rs, board by board) and every page set's boards (the page-set generators are run into a scratch directory). Where ARASAAC draws two words of a board with one picture, overrides-nc.toml gives the second its own picture in the right sense, or none (an open set draws it).
• No drawn words. The words drawn in every chosen pictogram are read with Apple Vision (ocr_vision.swift, built with swiftc into the cache; macOS only, elsewhere the build says the check did not run). Words a reader of another language would need (Spanish forms, "School") mean another picture or none. What may stay (sums on a blackboard, "BLA BLA", the euro on ARASAAC's money) is listed with a reason in [arasaac-text] and [sclera-text]; readers on different Macs see different things, so what any of them reads is listed. The Spanish ¡ and ¿, which the reader does not report, are checked by eye on the contact sheets. Where the reader cannot run (not macOS) the build stops, unless --skip-drawn-text-check says the packs are not being rebuilt for a release.

Not in a build without them. The optional sets' catalogue, the pack loader and every word about them are behind the nc-symbols cargo feature (aac-core and aac-web). The standard's own build, and a deployment's build without it, hold nothing that names them; their section of LICENSES.md is LICENSES-nc.md beside the packs, which a deployment that ships them appends. prerender-static.sh stops if its site holds a pack (under models/symbols/, named *.pack, or starting with a pack's magic bytes AACSYMP1 as stored or, for a .br/.gz sidecar, once decompressed, wherever it is), if sw.js precaches one, if a file in any folder is named for a set, or if any file of the app's own names a set in its content (.gz/.br sidecars decompressed; the third-party data in voices/, ai/, asr/, ae/, vendor/ and models/lang/ is left out of that word scan only): node tools/symbols/check-no-nc.mjs <site> [app/], tested with planted files by node --test tools/symbols/check-no-nc.test.mjs.

People drawn without skin. A few ARASAAC people are line drawings with no skin colour, so they never take the chosen tone (the family-tree aunt, uncle and cousin; nobody; the hands of hard and soft). They are kept only where ARASAAC has no picture in the same sense that takes the tone, each with its reason in [arasaac-people], and listed in people-review-nc.md.

People. ARASAAC's API draws a pictogram's skin in a colour it is asked for. The skin=white and skin=black renders differ exactly where skin is drawn; each pixel is unmixed linearly between the two skin colours, so a pack carries the picture with its skin cut out and a grey mask of the skin. The app paints the chosen tone through the mask (--aac-skin, Unicode's neutral by default, as for the other sets); every pictogram is checked by re-drawing ARASAAC's own skin=white render from the two layers. Hair keeps ARASAAC's colour: no hair colour belongs to a skin tone.

Packs. <set>.<sha256-12>.pack: a JSON header (the licence it is shared under, the set's own where it differs, attribution, conditions, source and its version, the changes made, symbols) and WebP images: ARASAAC's at 320 px, near-lossless, with lossless skin masks; Sclera's at its own 283 px, lossless. A deployment serves them under {base}/models/symbols/ and builds the app with AAC_SYMBOL_PACKS=arasaac,sclera. The app offers them only while the device is signed out or on a free plan (aac-web account.rs: any paid plan hides them and draws the open sets). It downloads one only when a person chooses its set, checks its size and SHA-256, keeps it in IndexedDB (never Cache Storage, which iPad Safari evicts), and puts its symbols in the page, so cells, the picker, print and OBF export draw them like any other. Print credits and every exported picture carry the set's attribution, conditions and licence.