Claude Code से accessible breadcrumbs बनाएं

Breadcrumbs title के ऊपर दिखने वाली छोटी navigation line लगती है, लेकिन production site में यह site structure, internal links, accessibility, structured data और mobile layout को जोड़ती है। कमजोर implementation दिखने में ठीक हो सकती है, पर screen reader current page नहीं समझता, JSON-LD में relative URL चला जाता है, या लंबा title mobile पर intro को नीचे धकेल देता है।

ClaudeCodeLab templates पर मैंने Claude Code से सिर्फ “breadcrumb बनाओ” कहा तो पहली draft ने Home > Blog > Title बना दिया, पर aria-current missing था, JSON-LD में absolute URL नहीं था, mobile wrapping खराब थी और slug सीधे दिख रहे थे। इसलिए prompt में पहले ही पूरा contract देना जरूरी है।

यह guide React, Next.js-like और Astro sites के लिए practical breadcrumb implementation दिखाती है। साथ में SEO optimization, accessibility implementation, Astro development और React development भी देखें।

Design contract

Breadcrumb browser back button का replacement नहीं है। यह hierarchy दिखाता है, parent pages तक जाने का रास्ता देता है और search engines को page relation समझाता है। WAI-ARIA APG का Breadcrumb Pattern labelled navigation region और current page के लिए aria-current="page" बताता है।

Structured data के लिए schema.org BreadcrumbList follow करें। हर item में position order बताता है। Google Search appearance के लिए official breadcrumb structured data documentation देखें।

फैसला	क्या तय करें	common failure
Labels	title, category या dictionary	raw slug दिखता है
URLs	HTML links और JSON-LD absolute URLs	structured data में relative path
Current page	last item link या text	सिर्फ color से current state
Mobile	full trail या middle collapse	breadcrumb कई lines लेता है
Locales	route prefix और translated labels	languages mix हो जाती हैं

Claude Code prompt

React/Next.js या Astro site के लिए breadcrumbs implement करें।
Requirements:
- items को { label: string; href: string }[] की तरह accept करें।
- last item पर aria-current="page" जोड़ें।
- nav aria-label="Breadcrumb" use करें।
- separators को aria-hidden="true" करें।
- उसी items array से JSON-LD BreadcrumbList generate करें।
- JSON-LD URLs को siteUrl से absolute बनाएं।
- pathname से items बनाने वाला helper जोड़ें।
- slugs को readable text में format करें और label dictionary override दें।
- mobile पर middle items hide करें, current page readable रहे।
- Vitest tests root, nested paths, localized labels और query strings के लिए जोड़ें।
- implementation के बाद accessibility और structured-data checks list करें।

बड़े changes के लिए review workflow checklist से second pass करवाएं।

React component

import type { ReactNode } from "react";

export type BreadcrumbItem = {
  label: string;
  href: string;
};

type BreadcrumbProps = {
  items: BreadcrumbItem[];
  siteUrl: string;
  ariaLabel?: string;
};

function toAbsoluteUrl(siteUrl: string, href: string) {
  return new URL(href, siteUrl).toString();
}

function Separator(): ReactNode {
  return (
    <span className="breadcrumb__separator" aria-hidden="true">
      /
    </span>
  );
}

export function Breadcrumb({
  items,
  siteUrl,
  ariaLabel = "Breadcrumb",
}: BreadcrumbProps) {
  if (items.length <= 1) return null;

  const jsonLd = {
    "@context": "https://schema.org",
    "@type": "BreadcrumbList",
    itemListElement: items.map((item, index) => ({
      "@type": "ListItem",
      position: index + 1,
      item: {
        "@id": toAbsoluteUrl(siteUrl, item.href),
        name: item.label,
      },
    })),
  };

  return (
    <>
      <nav className="breadcrumb" aria-label={ariaLabel}>
        <ol className="breadcrumb__list">
          {items.map((item, index) => {
            const isCurrent = index === items.length - 1;
            return (
              <li className="breadcrumb__item" key={item.href}>
                {index > 0 ? <Separator /> : null}
                {isCurrent ? (
                  <span className="breadcrumb__current" aria-current="page">
                    {item.label}
                  </span>
                ) : (
                  <a className="breadcrumb__link" href={item.href}>
                    {item.label}
                  </a>
                )}
              </li>
            );
          })}
        </ol>
      </nav>
      <script
        type="application/ld+json"
        dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
      />
    </>
  );
}

Route helper

import type { BreadcrumbItem } from "@/components/Breadcrumb";

export type BreadcrumbLabels = Record<string, string>;

function titleize(segment: string) {
  return decodeURIComponent(segment)
    .replace(/[-_]+/g, " ")
    .replace(/\b\w/g, (char) => char.toUpperCase());
}

export function buildBreadcrumbs(
  pathname: string,
  labels: BreadcrumbLabels = {},
): BreadcrumbItem[] {
  const cleanPath = pathname.split(/[?#]/)[0].replace(/\/+$/, "") || "/";
  const segments = cleanPath.split("/").filter(Boolean);
  const items: BreadcrumbItem[] = [
    { label: labels["/"] ?? "Home", href: "/" },
  ];

  let href = "";

  for (const segment of segments) {
    href += `/${segment}`;
    items.push({
      label: labels[href] ?? labels[segment] ?? titleize(segment),
      href,
    });
  }

  return items;
}

import { Breadcrumb } from "@/components/Breadcrumb";
import { buildBreadcrumbs } from "@/lib/breadcrumbs";

const siteUrl = "https://claudecodelab.com";

export default async function ArticlePage() {
  const pathname = "/hi/blog/claude-code-breadcrumb-navigation";
  const labels = {
    "/": "Home",
    "/hi": "हिंदी",
    "/hi/blog": "Articles",
    "/hi/blog/claude-code-breadcrumb-navigation":
      "Claude Code से accessible breadcrumbs बनाएं",
  };
  const items = buildBreadcrumbs(pathname, labels);

  return (
    <main>
      <Breadcrumb items={items} siteUrl={siteUrl} ariaLabel="Breadcrumb" />
      <h1>Claude Code से accessible breadcrumbs बनाएं</h1>
    </main>
  );
}

Astro में यही data shape रखें, Astro.url.pathname से path लें और JSON-LD को set:html={JSON.stringify(jsonLd)} से output करें।

Mobile CSS

.breadcrumb { margin-block: 0 1rem; font-size: 0.875rem; color: #4b5563; }
.breadcrumb__list { display: flex; flex-wrap: wrap; gap: 0.25rem; list-style: none; margin: 0; padding: 0; }
.breadcrumb__item { align-items: center; display: inline-flex; min-width: 0; }
.breadcrumb__link { color: #2563eb; text-decoration: underline; text-underline-offset: 0.15em; }
.breadcrumb__current { color: #111827; font-weight: 600; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
.breadcrumb__separator { color: #9ca3af; margin-inline: 0.35rem; }
@media (max-width: 640px) {
  .breadcrumb__list { flex-wrap: nowrap; }
  .breadcrumb__item:not(:first-child):not(:nth-last-child(-n + 2)) { display: none; }
  .breadcrumb__item:nth-last-child(2)::after { color: #9ca3af; content: "..."; margin-inline: 0.35rem; }
  .breadcrumb__current { max-width: 58vw; }
}

Tests

import { describe, expect, it } from "vitest";
import { buildBreadcrumbs } from "./breadcrumbs";

describe("buildBreadcrumbs", () => {
  it("returns only Home for the root path", () => {
    expect(buildBreadcrumbs("/")).toEqual([{ label: "Home", href: "/" }]);
  });

  it("builds nested breadcrumbs and ignores query strings", () => {
    expect(buildBreadcrumbs("/blog/claude-code?page=2")).toEqual([
      { label: "Home", href: "/" },
      { label: "Blog", href: "/blog" },
      { label: "Claude Code", href: "/blog/claude-code" },
    ]);
  });

  it("uses localized labels when provided", () => {
    expect(
      buildBreadcrumbs("/hi/blog/claude-code-breadcrumb-navigation", {
        "/": "Home",
        "/hi": "हिंदी",
        "/hi/blog": "Articles",
        "/hi/blog/claude-code-breadcrumb-navigation": "Breadcrumb guide",
      }),
    ).toEqual([
      { label: "Home", href: "/" },
      { label: "हिंदी", href: "/hi" },
      { label: "Articles", href: "/hi/blog" },
      { label: "Breadcrumb guide", href: "/hi/blog/claude-code-breadcrumb-navigation" },
    ]);
  });
});

E2E में nav[aria-label], single aria-current="page", parseable JSON-LD, absolute URLs और mobile overlap check करें। अगला step Playwright testing है।

Use cases और pitfalls

Blogs/documentation में breadcrumbs topic pages तक वापस ले जाते हैं। Ecommerce और paid training pages में वे tutorial traffic को training/consultation तक naturally ले जा सकते हैं। SaaS admin screens में Organization > Project > Settings > Billing जैसा trail sensitive screens में context देता है। Multilingual sites में visible label और JSON-LD name दोनों localize करें।

Common failures हैं: current page को सिर्फ color से दिखाना, JSON-LD में relative URL, raw slug output, mobile पर लंबी wrapping, और UI/JSON-LD के लिए अलग data arrays. Publish से पहले aria-label, aria-current, hidden separators, BreadcrumbList, ordered position, absolute URLs, UI/JSON-LD consistency, mobile, locale और Search Console validation check करें।

CTA और verification

ClaudeCodeLab में breadcrumbs readers को free cheatsheet, products और Claude Code training/consultation तक guide करते हैं। मैंने examples को React component, route helper और Vitest tests में अलग करके verify किया। सबसे उपयोगी निर्णय था UI और JSON-LD को एक ही items array से generate करना; अलग arrays में category rename के बाद mismatch हो गया था।

Summary

Accessible breadcrumb सिर्फ links के बीच separator नहीं है। Claude Code को labels, routes, aria-current, JSON-LD, absolute URLs, mobile behavior और tests एक साथ दें, फिर official sources के against critical review करें।