Framework Agnostic Integration Guide
Build Citation Cards for Quran and Hadith Results
A framework-agnostic citation UI pattern designed for inspection, accessibility, and religious-source clarity.
What You Will Build
A citation card contract that works across web and mobile interfaces without hiding the source behind a small footnote.
Prerequisites
- A Madeenan Search or Chat response
- A UI that supports bidirectional text
- Keyboard and screen-reader testing
Start With the Source Contract
A citation card needs a stable label, source type, source text, translation, and optional grade. Keep unknown values nullable rather than replacing them with guesses.
Make Arabic and Translation Distinct
Set lang=ar and dir=rtl on the Arabic passage. Place the translation in its own block and label it as a translation so a reader cannot confuse it with Quran wording or a generated explanation.
Keep Grade and Provenance Visible
For Hadith, show the grade when the API returns one. A report number without grade or collection context can create more confidence than the product has earned.
If you display source edition or retrieval metadata, place it in a disclosure below the core text rather than crowding the citation label.
Security Boundary
Citation UI does not make a generated answer authoritative. Keep product limitations visible and route sensitive questions to qualified people.
Test Before Shipping
- Navigate every interactive card by keyboard
- Verify Arabic direction and font fallback
- Check long references on a 320px viewport
- Hide empty grade fields
- Confirm citation links have standalone text