madeenan

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.

export type CitationSource = {
source_id: string;
type: "quran" | "hadith" | "tafsir" | "dua";
citation_label: string;
title?: string | null;
arabic?: string | null;
translation?: string | null;
grade?: string | null;
metadata?: Record<string, unknown>;
};

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.

<article aria-labelledby="source-title">
<h3 id="source-title">Qur'an 2:255</h3>
<p lang="ar" dir="rtl">اللَّهُ لَا إِلَٰهَ إِلَّا هُوَ…</p>
<section aria-label="English translation">
<p>Allah, there is no deity except Him…</p>
</section>
</article>

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

Related

Source Topic

A Dua for Anxiety and Sorrow

Read the dua for anxiety and sorrow reported in Sahih al-Bukhari 6369, with Arabic, English translation, source links, and careful limits.

Read Topic

Documentation

Citation Documentation

Render inspectable source references from API results.

Read Docs

Tool

Embed Builder

Create an embeddable search, source card, or citation bundle.

Open Builder