Skip to content

quran-ws/qurantech-skill / plugins/qurantech/skills/quran-tajweed

quran-tajweed

Verified

Use 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.

FileKindSize
SKILL.mdskill md4.3 KB
references/spans.mdmarkdown3.8 KB
---
name: quran-tajweed
description: Use 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`/`end` are half-open code-point positions: index with `[...text]`, never UTF-16 `slice`.
- `ruleIndex` indexes `annotations.ruleIds`; `corpus` (rules package) resolves rule to hukum, category, topic (7 topics).
- Offsets are measured against one edition, `editions/uthmani-hafs.json` in the repo (not in the npm packages). Its SHA-256 is `annotations.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-rules` and `@quran.ws/tajwid-annotations` ship 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-cli` were published without a built `dist/` (checked 2026-09-29: 2 files each, `main` points at a missing `./dist/index.js`), so importing them fails. Until a fixed version ships, build them from `packages/*` in the repo, or read the data packages directly. Re-check with `npm view` and `npm 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 with `bridgeJoins`, 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)
```tsx
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 are `needsReview`: 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`.
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall