quran-ws/qurantech-skill / plugins/qurantech/skills/quran-tajweed
quran-tajweed
VerifiedUse when adding tajweed or tajwid colouring to Quran text, explaining a recitation rule while reading, building tajweed-learning tools, or reading, projecting or validating tajweed annotation spans (start/end/rule) from Quran.ws quran-tajweed.
quran-tajweed
Follow the qurantech skill's adab rules (never alter or truncate Quranic text).
Model
Annotations are positions, never markup. The text stays unchanged; spans [start, end, ruleIndex] map to a presentation (colour, tooltip, legend). The data holds no Quranic text.
Addressing and edition
- Spans are keyed
"surah:ayah"(Hafs count, 6,236 ayahs).start/endare half-open code-point positions: index with[...text], never UTF-16slice. ruleIndexindexesannotations.ruleIds;corpus(rules package) resolves rule to hukum, category, topic (7 topics).- Offsets are measured against one edition,
editions/uthmani-hafs.jsonin the repo (not in the npm packages). Its SHA-256 isannotations.edition.sha256. - Verify first:
await assertEdition(edition, annotations.edition.sha256). If the app's text differs by one code point, do not use the precomputed spans; render the tajweed edition's text, or run@quran.ws/tajwid(new Tajweed(corpus).analyze(text)) over the app's own text. - Hafs only; other riwayat are unsupported.
Packages
- npm 0.1.0:
@quran.ws/tajwid-rulesand@quran.ws/tajwid-annotationsship their data and work today. The code packages@quran.ws/tajwid(engine:unpack,resolveOverlaps,clusterEnd,bridgeJoins),@quran.ws/tajwid-react(TajweedText,TajweedLegend) and@quran.ws/tajwid-cliwere published without a builtdist/(checked 2026-09-29: 2 files each,mainpoints at a missing./dist/index.js), so importing them fails. Until a fixed version ships, build them frompackages/*in the repo, or read the data packages directly. Re-check withnpm viewandnpm pack. - Python reader: not published. Take the dataset from a GitHub release:
gh release download v0.4.3 -R quran-ws/quran-tajweed.
Projecting
- Text: split into runs and colour by topic. Break runs only before a base letter, extend each boundary with
clusterEnd, and join cuts withbridgeJoins, so shadda and harakat stay on their letter and words stay joined. Keep joiners out of offsets and clipboard. - Overlaps are normal (1:6 has eleven spans). Keep them for teaching, or flatten with
resolveOverlaps. - quran-svg / quran-svg-elements: spans address characters, not printed shapes. Do not apply offsets to SVG paths. Style marks through Quran SVG Elements by name; the joining of characters to shapes is unverified here (see references/spans.md).
Minimal example (React: colour ayah 1:1)
import corpus from '@quran.ws/tajwid-rules'
// `edition`: load editions/uthmani-hafs.json from the repo; `corpus`: from @quran.ws/tajwid-rules
// The three imports below need the built packages (see Packages: build from the repo until a fixed npm release ships).
import annotations from '@quran.ws/tajwid-annotations'
import { unpack, assertEdition } from '@quran.ws/tajwid'
import { TajweedText, TajweedLegend } from '@quran.ws/tajwid-react'
await assertEdition(edition, annotations.edition.sha256)
const text = edition.ayahs['1:1']
<TajweedText text={text} corpus={corpus} spans={unpack(annotations, corpus, '1:1')} colors={MY_COLOURS} />
<TajweedLegend corpus={corpus} colors={MY_COLOURS} />
Real data: annotations.spans['1:1'] is [[8,10,52],[17,18,22],[22,25,129],[30,31,22],[33,36,131]]; index 52 is mutamathilain-idgham-kamil.23.
Licence
Corpus, annotations, editions, docs: CC BY 4.0 (attribute). Engine, tools, React, Python: MIT.
Maturity and gotchas
- Colour by topic (Arabic labels only; add your own English mapping keyed on ids). The palette is yours: label it as your own, never as a printed mushaf's scheme; always ship a legend.
- Silence is not "no rule applies": only 7 topics are covered; named gaps exist (e.g. 20:1 has no spans).
- Rule status:
stable,disabled(silent gap),disputed(spans ship; surface the objection when naming the ruling). Some rules areneedsReview: not signed off by a qualified reviewer. - Never edit the text to add colour or wrapper characters.
- Present output as a study aid, not a substitute for a qualified teacher.
Details: references/spans.md.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |