From 82db3b9bf27f60168b90eb144527fc3eb2c1c117 Mon Sep 17 00:00:00 2001
From: amaan-bhati <amaanbhati49@gmail.com>
Date: Tue, 14 Apr 2026 18:48:31 +0530
Subject: [PATCH 1/2] feat: add design review skill for claude

Signed-off-by: amaan-bhati <amaanbhati49@gmail.com>
---
 .claude/skills/design-agent/SKILL.md          |  85 +++++
 .../design-agent/references/anti-patterns.md  | 299 +++++++++++++++
 .../references/component-library.md           | 354 ++++++++++++++++++
 .../design-agent/references/design-tokens.md  | 239 ++++++++++++
 4 files changed, 977 insertions(+)
 create mode 100644 .claude/skills/design-agent/SKILL.md
 create mode 100644 .claude/skills/design-agent/references/anti-patterns.md
 create mode 100644 .claude/skills/design-agent/references/component-library.md
 create mode 100644 .claude/skills/design-agent/references/design-tokens.md

diff --git a/.claude/skills/design-agent/SKILL.md b/.claude/skills/design-agent/SKILL.md
new file mode 100644
index 000000000..52dadcde8
--- /dev/null
+++ b/.claude/skills/design-agent/SKILL.md
@@ -0,0 +1,85 @@
+name: design-agent
+description: >
+  Use this skill when a contributor asks for /design-agent, design review, PR review, UI review, design feedback, visual QA, frontend consistency checks, component usage guidance, Tailwind review, CSS review, docs-site styling review, Docusaurus theme review, accessibility review, spacing review, typography review, or help matching Keploy Docs design conventions. Trigger this for PR review comments about design consistency, component usage, Tailwind/CSS conventions in this repo, hardcoded colors, inline styles, Docusaurus CSS variable usage, dark mode mismatches, focus states, and whether a page or component looks like the rest of the Keploy documentation site.
+
+Design Agent — Keploy Documentation
+This agent reviews UI and frontend changes in the Keploy docs site, which is built on Docusaurus 3 with React, Tailwind CSS, Docusaurus theme overrides, and a large set of MDX helper components. It checks whether changes align with the repo's actual design system: Docusaurus CSS variables for core theming, Tailwind utility patterns on newer pages, and existing reusable components for chips, cards, quickstart flows, glossary cards, and docs metadata.
+
+Trigger
+This skill is invoked when a contributor uses /design-agent or asks for design review, design feedback, or UI/UX guidance on a PR or commit.
+
+What to review in a PR
+When called on a PR or set of code changes, check for:
+
+1. Token compliance
+Colors must prefer the repo's existing theme tokens from `src/css/custom.css`: `--ifm-color-primary` `#ff914d`, `--ifm-color-primary-dark` `#e67643`, `--ifm-color-primary-darker` `#c95919`, `--ifm-color-primary-darkest` `#be2c1b`, `--ifm-color-primary-light` `#ffd0a0`, `--ifm-color-primary-lightest` `#ffceb1`, `--ifm-color` `#00163d` in light mode and `#f5f6f7` in dark mode, `--ifm-background-color` `rgb(249, 250, 251)` in light mode and `#141414` in dark mode, `--ifm-card-background-color`, and `--ifm-card-shadow-color`.
+Use custom Tailwind colors from `tailwind.config.js` only when they already match an established pattern: `offwhite`, `keployblue`, `keploybrightblue`, `keploypurple`, `keploybrightpurple`, `spaceblack`, `green1`, `green2`, `orange1`, `orange2`, `gray5`, `lightgray`, `lightteal`.
+Do not introduce arbitrary values such as `bg-[#3b82f6]`, `text-[#7c3aed]`, or new one-off RGB values when an existing Docusaurus variable or existing Tailwind palette class already fits.
+`[inferred]` Newer homepage sections frequently use Tailwind's default gray/orange/purple/indigo families. Reuse those exact class families when extending those sections instead of inventing a new accent system.
+Flag `style={{ color: "#..." }}`, `style={{ background: "#..." }}`, and ad hoc token maps with raw hex values unless the file is already following that legacy pattern and the PR cannot reasonably normalize it.
+
+2. Component usage
+Use `@docusaurus/Link` for internal navigation, not raw `<a href="/docs/...">`.
+Use `@theme/Heading` or markdown headings inside docs content so anchor links and scroll offsets keep working.
+Use `GlossaryCard` for glossary card grids.
+Use `DocHeaderChips`, `ProductTier`, or `TierCallout` for doc metadata chips instead of inventing another badge row.
+Use `QuickStartTabs` and `QuickStartFilter` when editing the quickstart entry experience; do not rebuild the same chooser pattern from scratch.
+Use `SidebarBadge` and `SidebarCategoryIcon` for sidebar labels/icons instead of ad hoc badge markup.
+`[inferred]` Reuse existing card anatomy from newer homepage sections: `rounded-2xl`, bordered surfaces, `p-6`, compact eyebrow pill, `text-3xl md:text-4xl` section headings, and dark-mode variants.
+There is no consistently enforced global button component in this repo. Do not force `src/components/shared/Button.js` everywhere, but do flag raw buttons/links that ignore existing CTA patterns, focus states, or dark-mode treatment.
+
+3. Typography
+Docs pages force `DM Sans` globally through `src/css/custom.css`; code blocks intentionally revert to the system monospace stack.
+Headings and the navbar use an `Aeonik`-first fallback stack in `src/css/custom.css`; body copy on docs pages is still forced to `DM Sans`.
+Review heading hierarchy carefully: section headers on newer landing sections usually use `text-3xl font-bold tracking-tight md:text-4xl`; subheads are commonly `text-lg` or `text-xl` with `font-bold` or `font-semibold`; supporting copy is usually `text-sm`, `text-base`, or `text-xs` in gray text classes.
+In docs markdown, prose styling comes from Tailwind Typography plus Docusaurus overrides in `tailwind.config.js` and `src/theme/DocItem/index.js`.
+Flag jumps in hierarchy like using `text-4xl` for small card titles or mixing legacy `tracking-wide font-semibold` headings with the newer `tracking-tight font-bold` marketing pattern in the same section.
+
+4. Spacing & layout
+The homepage shell uses `max-w-screen-lg` with `p-6 md:p-10` and stacked sections separated mostly by `mb-12` or `mb-16`.
+Common card spacing is `p-6`; compact nested options often use `p-3` or `p-4`.
+Common gaps are `gap-2`, `gap-3`, `gap-4`, and `gap-6`.
+Common max widths are `max-w-2xl`, `max-w-3xl`, `max-w-5xl`, and `max-w-6xl`.
+`[inferred]` Prefer `rounded-xl` or `rounded-2xl` on newer surfaces; `rounded-lg` appears mostly in older components.
+Flag new layouts that ignore the established page width, use inconsistent spacing steps, or introduce oversized padding/margins without a clear reason.
+
+5. Responsiveness
+This repo uses Tailwind's default responsive prefixes; no custom breakpoints are defined in `tailwind.config.js`.
+Common responsive patterns in source are `md:grid-cols-2`, `md:grid-cols-3`, `md:grid-cols-12`, `md:text-4xl`, `md:p-10`, `lg:gap-8`, `lg:px-10`, and Docusaurus' desktop breakpoint behavior around `997px` in `src/theme/DocItem/styles.module.css`.
+`[inferred]` New sections should collapse to one column on mobile, keep CTAs full-width or easy to tap, and avoid text that depends on hover-only disclosure.
+Flag any PR that adds fixed widths or desktop-only multi-column layouts without a mobile fallback.
+
+6. Accessibility
+Keep visible focus treatment. Global focus styles are defined in `src/css/custom.css`, and some components add stronger local rings with `focus-visible:ring-*`.
+Preserve `aria-label` usage for icon-only links and action buttons; examples already exist in `src/theme/DocItem/index.js`, `src/theme/Heading/index.js`, `src/pages/concepts/reference/glossary.js`, and `src/components/WhatIsKeploy.js`.
+Images should keep meaningful `alt` text unless decorative.
+Internal controls that behave like toggles or filters should keep state semantics such as `aria-pressed`.
+If a PR adds `target="_blank"`, require `rel="noopener noreferrer"`.
+Flag `focus:outline-none` when it is not paired with an equivalent replacement ring or outline.
+
+7. Anti-patterns to flag
+Inline styling for structure, spacing, or color in React components, especially in `InstallReminder`, `EnterpriseInstallReminder`, `SectionDivider`, `StartKeploy`, `StartKeployDocker`, and `ResponsivePlayer`.
+Hardcoded color maps and local `<style>` blocks for reusable chips/badges instead of shared tokens or CSS variables, as seen in `DocHeaderChips`, `SidebarBadge`, `ProductTier`, and `TierCallout`.
+Arbitrary value classes like `bg-[color:orange]`, `border-[color:orange]`, `bg-[var(--ifm-card-background-color)]`, and `shadow-[0_4px_12px_var(--ifm-card-shadow-color)]` when a standard class or central token would be clearer.
+Invalid or inconsistent JSX/SVG attributes such as raw `class=` and kebab-case `fill-rule` or `clip-rule`.
+Recreating cards, pill badges, or quickstart selectors that already exist in `src/components`.
+Mixing old `rounded-lg shadow-lg` legacy cards into newer `rounded-2xl border p-6` sections without an intentional visual reason.
+Introducing new font families or typography systems; this repo already has conflicting font choices and should not add more.
+
+How to deliver feedback
+When reviewing a PR, structure your feedback as follows:
+
+Summary — one paragraph overall design health assessment
+Critical issues — things that must be fixed before merge (broken design tokens, accessibility failures, missing required components)
+Suggestions — things that would improve consistency but aren't blockers
+Positive notes — what was done well (always include at least one)
+
+Be specific. Reference actual line numbers or file names from the diff.
+Compare against guidelines in the references/ files.
+Never give vague feedback like "improve spacing" — say exactly what class or token should be used instead.
+
+Reference files
+
+Read references/design-tokens.md for all color, spacing, and typography values
+Read references/component-library.md for component usage rules
+Read references/anti-patterns.md for patterns to flag in review
diff --git a/.claude/skills/design-agent/references/anti-patterns.md b/.claude/skills/design-agent/references/anti-patterns.md
new file mode 100644
index 000000000..0edf3e215
--- /dev/null
+++ b/.claude/skills/design-agent/references/anti-patterns.md
@@ -0,0 +1,299 @@
+# Keploy Docs anti-patterns
+
+These are patterns already present in the repo that a design-review agent should flag in PRs instead of normalizing as "okay".
+
+## 1. Inline styles for color, spacing, borders, or layout
+
+What it looks like:
+
+```jsx
+<div
+  style={{
+    padding: "1rem",
+    border: isDark ? "1px solid #333" : "1px solid #eee",
+    borderRadius: "10px",
+    background: isDark ? "#23272f" : "#fff8f5",
+  }}
+/>
+```
+
+Why it's wrong:
+
+- It bypasses both Docusaurus theme variables and Tailwind utility conventions.
+- It makes dark mode, token reuse, and visual consistency harder to review.
+
+Correct alternative:
+
+```jsx
+<div className="rounded-xl border border-gray-200 bg-[var(--ifm-card-background-color)] p-4 dark:border-gray-700" />
+```
+
+Seen in:
+
+- `src/components/InstallReminder.js`
+- `src/components/EnterpriseInstallReminder.js`
+- `src/components/SectionDivider.js`
+- `src/components/StartKeploy.js`
+- `src/components/StartKeployDocker.js`
+
+## 2. Hardcoded hex colors instead of repo tokens
+
+What it looks like:
+
+```jsx
+const chipStyles = {
+  enterprise: { label: "Enterprise", color: "#7c3aed", bg: "rgba(139, 92, 246, 0.1)" },
+  cloud: { label: "Cloud", color: "#2563eb", bg: "rgba(59, 130, 246, 0.1)" },
+};
+```
+
+Why it's wrong:
+
+- The repo already has Docusaurus CSS variables and a Tailwind palette.
+- Repeating hardcoded hex values in component-local maps creates token drift.
+
+Correct alternative:
+
+```jsx
+<span className="rounded-full bg-purple-100 px-2 py-1 text-purple-700 dark:bg-purple-900/30 dark:text-purple-200" />
+```
+
+Or, for doc-wide theming:
+
+```jsx
+<span style={{ color: "var(--ifm-color-primary)" }} />
+```
+
+Seen in:
+
+- `src/components/DocHeaderChips.js`
+- `src/components/SidebarBadge.js`
+- `src/components/ProductTier.js`
+- `src/components/TierCallout.js`
+- `src/components/SidebarCategoryIcon.js`
+
+## 3. Arbitrary-value classes where standard classes or shared tokens would be clearer
+
+What it looks like:
+
+```jsx
+className="bg-[color:orange] border-[color:orange] bg-[var(--ifm-card-background-color)] shadow-[0_4px_12px_var(--ifm-card-shadow-color)]"
+```
+
+Why it's wrong:
+
+- Arbitrary values make review harder because they hide the intended token or design choice.
+- Some are especially brittle or unclear, such as `bg-[color:orange]`.
+
+Correct alternative:
+
+```jsx
+className="bg-orange-500 border-orange-500"
+```
+
+Or:
+
+```jsx
+className="bg-[var(--ifm-card-background-color)]"
+```
+
+only when there is no standard class and the Docusaurus variable is intentional.
+
+Seen in:
+
+- `src/components/GSoC.js`
+- `src/components/Hacktoberfest.js`
+- `src/components/GitTogether.js`
+- `src/components/GlossaryCard.js`
+- `src/components/QuickStart.js`
+
+## 4. Invalid JSX or SVG attribute names
+
+What it looks like:
+
+```jsx
+<div class="flex gap-3">
+```
+
+```jsx
+<path fill-rule="evenodd" clip-rule="evenodd" />
+```
+
+Why it's wrong:
+
+- `class` should be `className` in JSX.
+- SVG attributes must use camelCase in React: `fillRule`, `clipRule`.
+- These issues are easy to miss visually but create avoidable warnings and inconsistency.
+
+Correct alternative:
+
+```jsx
+<div className="flex gap-3">
+```
+
+```jsx
+<path fillRule="evenodd" clipRule="evenodd" />
+```
+
+Seen in:
+
+- `src/components/QuickStart.js`
+- `src/components/Product.js`
+
+## 5. Mixing multiple styling systems inside one component without a clear reason
+
+What it looks like:
+
+```jsx
+<div className="quickstart-wizard">
+  <style>{`...large CSS block...`}</style>
+  <div className="wizard-option" style={{ flexDirection: "column" }} />
+</div>
+```
+
+Why it's wrong:
+
+- It combines Tailwind, large inline `<style>` blocks, and per-node inline styles.
+- That makes future edits slower and makes consistency review harder.
+
+Correct alternative:
+
+- Prefer one primary system per component.
+- In this repo, newer components are easiest to maintain when they stay Tailwind-first and only use CSS variables where theming requires it.
+
+Seen in:
+
+- `src/components/QuickStartFilter.js`
+
+## 6. Recreating badge, chip, and metadata systems instead of reusing the existing helpers
+
+What it looks like:
+
+```jsx
+<span className="rounded-full bg-orange-100 px-3 py-1 text-sm font-medium text-orange-600">
+  Custom status
+</span>
+```
+
+Why it's wrong:
+
+- This repo already has several metadata helpers: `DocHeaderChips`, `ProductTier`, `TierCallout`, and `SidebarBadge`.
+- Recreating them increases visual drift.
+
+Correct alternative:
+
+```jsx
+<TierCallout chips={["oss", "docker"]} />
+```
+
+or
+
+```jsx
+<DocHeaderChips tier="cloud" version="4.0.0" />
+```
+
+Seen in:
+
+- Repeated manually across several homepage sections
+
+## 7. Introducing more legacy card styles into new sections
+
+What it looks like:
+
+```jsx
+<div className="rounded-lg bg-[color:var(--ifm-card-background-color)] p-5 shadow-lg" />
+```
+
+Why it's wrong:
+
+- The repo already has a visible split between older card styling and newer homepage styling.
+- New work should follow the newer pattern unless it is intentionally editing a legacy section in place.
+
+Correct alternative:
+
+```jsx
+<div className="rounded-2xl border border-gray-200 bg-white p-6 shadow-sm dark:border-gray-700 dark:bg-gray-800/50" />
+```
+
+Seen in:
+
+- `src/components/QuickStart.js`
+- `src/components/SDKs.js`
+- `src/components/Intro.js`
+- `src/components/Product.js`
+- `src/components/UtgMethods.js`
+
+## 8. `focus:outline-none` without a clear replacement
+
+What it looks like:
+
+```jsx
+className="focus:outline-none"
+```
+
+Why it's wrong:
+
+- The repo already defines global focus styling and some components add stronger `focus-visible` rings.
+- Removing outlines without a replacement harms keyboard usability.
+
+Correct alternative:
+
+```jsx
+className="focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--ifm-color-primary)] focus-visible:ring-offset-2"
+```
+
+Seen in:
+
+- Any new PR that removes focus styling
+- Existing correct replacement examples: `src/components/WhatIsKeploy.js`, `src/components/GlossaryCard.js`, `src/pages/concepts/reference/glossary.js`, `src/components/shared/Button.js`
+
+## 9. Duplicated IDs inside reusable components
+
+What it looks like:
+
+```jsx
+<button id="copy-full-code">Copy</button>
+```
+
+Why it's wrong:
+
+- Reusable components may render multiple times on one page.
+- Duplicate IDs break DOM assumptions and make styling or scripting unreliable.
+
+Correct alternative:
+
+```jsx
+<button onClick={handleCopy}>Copy</button>
+```
+
+Or generate a unique ID per instance.
+
+Seen in:
+
+- `src/components/CollapsibleCode.js`
+
+## 10. Adding more one-off font systems
+
+What it looks like:
+
+```css
+h1,
+h2,
+h3 {
+  font-family: "SomeNewBrandFont", sans-serif;
+}
+```
+
+Why it's wrong:
+
+- The repo already mixes `DM Sans`, `Aeonik`, and local `Roboto`.
+- Adding another font family worsens inconsistency.
+
+Correct alternative:
+
+- Reuse the existing docs body and heading stacks.
+- If typography needs cleanup, centralize it in `src/css/custom.css` instead of per-component overrides.
+
+Seen in:
+
+- Existing font split between docs body and headings in `src/css/custom.css`
diff --git a/.claude/skills/design-agent/references/component-library.md b/.claude/skills/design-agent/references/component-library.md
new file mode 100644
index 000000000..733c3985d
--- /dev/null
+++ b/.claude/skills/design-agent/references/component-library.md
@@ -0,0 +1,354 @@
+# Keploy Docs component library
+
+This repo has two layers of reusable UI:
+
+1. `src/components/*` MDX and page-building helpers.
+2. `src/theme/*` Docusaurus theme overrides that contributors should preserve when editing docs UX.
+
+Files marked as legacy are still reusable, but they do not match the newer homepage design language as closely.
+
+## App components
+
+### `Button`
+
+- File: [`src/components/shared/Button.js`](/Users/amaan-bhati/Documents/docs/src/components/shared/Button.js)
+- Purpose: Simple shared `<button>` with Docusaurus variable-based colors and a focus ring.
+- Use when: You need a real `<button>` element inside a custom React component.
+- Do not use when: A navigation action should be a `Link`, or when an existing Docusaurus button style already matches the page.
+- Props: `children`, `type`, `name`, `className`
+- Example: `<Button type="button">Run test</Button>`
+
+### `CollapsibleCode`
+
+- File: [`src/components/CollapsibleCode.js`](/Users/amaan-bhati/Documents/docs/src/components/CollapsibleCode.js)
+- Purpose: Shows a preview of long code with Show More and Copy actions.
+- Use when: A doc needs to preview long code samples without overwhelming the page.
+- Do not use when: A normal `CodeBlock` is short enough to show in full.
+- Props: `code`, `language = "json"`, `previewLines = 10`
+- Example: `<CollapsibleCode code={payload} language="json" previewLines={12} />`
+
+### `Community`
+
+- File: [`src/components/Community.js`](/Users/amaan-bhati/Documents/docs/src/components/Community.js)
+- Purpose: Homepage section for community links and a demo CTA.
+- Use when: Editing the homepage or a page that intentionally mirrors the homepage marketing style.
+- Do not use when: A doc page only needs a simple inline support link block.
+- Props: none
+- Example: `<Community />`
+
+### `DocHeaderChips`
+
+- File: [`src/components/DocHeaderChips.js`](/Users/amaan-bhati/Documents/docs/src/components/DocHeaderChips.js)
+- Purpose: Compact metadata strip for doc pages.
+- Use when: A doc needs tier, version, or availability metadata near the title.
+- Do not use when: You only need a single badge or pill; prefer the simpler chip helpers.
+- Props: `tier`, `version`, `availability = []`
+- Example: `<DocHeaderChips tier="oss" version="4.0.0" availability={["cli", "cloud"]} />`
+
+### `EcosystemSupport`
+
+- File: [`src/components/EcosystemSupport.js`](/Users/amaan-bhati/Documents/docs/src/components/EcosystemSupport.js)
+- Purpose: Homepage section for sponsorship, storytelling, and GSoC programs.
+- Use when: Editing ecosystem/community marketing on the homepage.
+- Do not use when: A doc needs a small inline callout rather than a multi-card section.
+- Props: none
+- Example: `<EcosystemSupport />`
+
+### `EnterpriseInstallReminder`
+
+- File: [`src/components/EnterpriseInstallReminder.js`](/Users/amaan-bhati/Documents/docs/src/components/EnterpriseInstallReminder.js)
+- Purpose: Inline install reminder card for enterprise samples.
+- Use when: A guide assumes Keploy Enterprise is already installed.
+- Do not use when: The page is for OSS or when metadata chips are enough.
+- Props: none
+- Example: `<EnterpriseInstallReminder />`
+
+### `GSoC`
+
+- File: [`src/components/GSoC.js`](/Users/amaan-bhati/Documents/docs/src/components/GSoC.js)
+- Purpose: Legacy GSoC promo section.
+- Use when: Maintaining the existing GSoC landing content.
+- Do not use when: Building new homepage sections; it uses an older visual pattern.
+- Props: none
+- Example: `<GSoC />`
+
+### `GetStartedPaths`
+
+- File: [`src/components/GetStartedPaths.js`](/Users/amaan-bhati/Documents/docs/src/components/GetStartedPaths.js)
+- Purpose: Two-path homepage chooser for AI generation vs record/replay.
+- Use when: Editing the top-level onboarding decision on the homepage.
+- Do not use when: A page only needs a single CTA card or a tabbed quickstart.
+- Props: none
+- Example: `<GetStartedPaths />`
+
+### `GitTogether`
+
+- File: [`src/components/GitTogether.js`](/Users/amaan-bhati/Documents/docs/src/components/GitTogether.js)
+- Purpose: Legacy event promo section.
+- Use when: Maintaining GitTogether event content already using this block.
+- Do not use when: Creating new design-system exemplars; it follows older styling conventions.
+- Props: none
+- Example: `<GitTogether />`
+
+### `GlossaryCard`
+
+- File: [`src/components/GlossaryCard.js`](/Users/amaan-bhati/Documents/docs/src/components/GlossaryCard.js)
+- Purpose: Clickable glossary entry card with hover affordance.
+- Use when: Rendering glossary grids or term libraries.
+- Do not use when: A plain text list of links is sufficient.
+- Props: `name`, `description`, `link`
+- Example: `<GlossaryCard name="Mock" description="A simulated dependency." link="/docs/concepts/reference/glossary/mocks" />`
+
+### `Hacktoberfest`
+
+- File: [`src/components/Hacktoberfest.js`](/Users/amaan-bhati/Documents/docs/src/components/Hacktoberfest.js)
+- Purpose: Legacy Hacktoberfest promo block.
+- Use when: Updating the existing Hacktoberfest surface.
+- Do not use when: Building new generic community sections.
+- Props: none
+- Example: `<Hacktoberfest />`
+
+### `InstallReminder`
+
+- File: [`src/components/InstallReminder.js`](/Users/amaan-bhati/Documents/docs/src/components/InstallReminder.js)
+- Purpose: Inline install reminder card for OSS/local guides.
+- Use when: A page expects Keploy to be installed before the next steps.
+- Do not use when: A simple doc link is enough or when metadata chips are more appropriate.
+- Props: none
+- Example: `<InstallReminder />`
+
+### `Intro`
+
+- File: [`src/components/Intro.js`](/Users/amaan-bhati/Documents/docs/src/components/Intro.js)
+- Purpose: Legacy support matrix for languages and dependencies.
+- Use when: Maintaining the existing support overview.
+- Do not use when: Building new sections; it uses an older card pattern and has some incomplete links.
+- Props: none
+- Example: `<Intro />`
+
+### `KeployCloud`
+
+- File: [`src/components/KeployCloud.js`](/Users/amaan-bhati/Documents/docs/src/components/KeployCloud.js)
+- Purpose: Small support strip with Slack and demo CTAs.
+- Use when: A docs page needs the standard support footer strip.
+- Do not use when: The full homepage community section is more appropriate.
+- Props: none
+- Example: `<KeployCloud />`
+
+### `Products`
+
+- File: [`src/components/Product.js`](/Users/amaan-bhati/Documents/docs/src/components/Product.js)
+- Purpose: Legacy product card section.
+- Use when: Maintaining the current product overview if it is still needed.
+- Do not use when: Adding new marketing sections; it is visually older and contains invalid SVG JSX attributes.
+- Props: none
+- Example: `<Products />`
+
+### `ProductTier`
+
+- File: [`src/components/ProductTier.js`](/Users/amaan-bhati/Documents/docs/src/components/ProductTier.js)
+- Purpose: Compact inline chips for tiers and offerings.
+- Use when: Docs need product tier or hosting-mode metadata near headings or callouts.
+- Do not use when: A richer metadata strip such as `DocHeaderChips` is needed.
+- Props: `tiers`, `offerings`
+- Example: `<ProductTier tiers="Open Source, Enterprise" offerings="Dedicated" />`
+
+### `QuickStart`
+
+- File: [`src/components/QuickStart.js`](/Users/amaan-bhati/Documents/docs/src/components/QuickStart.js)
+- Purpose: Legacy welcome/intro section for docs onboarding.
+- Use when: Maintaining the current quickstart landing experience.
+- Do not use when: Adding modern homepage sections; it uses older typography and card styles.
+- Props: none
+- Example: `<QuickStart />`
+
+### `QuickStartFilter`
+
+- File: [`src/components/QuickStartFilter.js`](/Users/amaan-bhati/Documents/docs/src/components/QuickStartFilter.js)
+- Purpose: Three-step quickstart wizard by language and environment.
+- Use when: A page needs the established quickstart chooser UX.
+- Do not use when: A simple list or a two-option CTA is enough.
+- Props: `defaultLanguage = null`
+- Example: `<QuickStartFilter defaultLanguage="Go" />`
+
+### `QuickStartTabs`
+
+- File: [`src/components/QuickStartTabs.js`](/Users/amaan-bhati/Documents/docs/src/components/QuickStartTabs.js)
+- Purpose: Two-tile quickstart chooser for AI vs OSS paths.
+- Use when: Presenting the two main onboarding paths in a compact section.
+- Do not use when: The richer `GetStartedPaths` section is already present on the page.
+- Props: none
+- Example: `<QuickStartTabs />`
+
+### `Resources`
+
+- File: [`src/components/Resources.js`](/Users/amaan-bhati/Documents/docs/src/components/Resources.js)
+- Purpose: Legacy quick links list.
+- Use when: A page needs a small list of curated resources.
+- Do not use when: You need card-based marketing CTAs.
+- Props: none
+- Example: `<Resources />`
+
+### `ResponsivePlayer`
+
+- File: [`src/components/responsive-player/ResponsivePlayer.js`](/Users/amaan-bhati/Documents/docs/src/components/responsive-player/ResponsivePlayer.js)
+- Purpose: 16:9 responsive wrapper around `react-player`.
+- Use when: Embedding video that should keep aspect ratio responsively.
+- Do not use when: A static image or simple iframe embed is sufficient.
+- Props: `url`, `loop`, `playing`
+- Example: `<ResponsivePlayer url="https://youtu.be/example" playing={false} loop={false} />`
+
+### `SDKs`
+
+- File: [`src/components/SDKs.js`](/Users/amaan-bhati/Documents/docs/src/components/SDKs.js)
+- Purpose: Legacy supported-OS cards.
+- Use when: Maintaining the current OS chooser section.
+- Do not use when: Building new feature marketing or metadata chips.
+- Props: none
+- Example: `<SDKs />`
+
+### `SectionDivider`
+
+- File: [`src/components/SectionDivider.js`](/Users/amaan-bhati/Documents/docs/src/components/SectionDivider.js)
+- Purpose: Dashed horizontal divider.
+- Use when: You need a strong visual separation inside a long custom page.
+- Do not use when: Standard margin spacing is sufficient.
+- Props: none
+- Example: `<SectionDivider />`
+
+### `SidebarBadge`
+
+- File: [`src/components/SidebarBadge.js`](/Users/amaan-bhati/Documents/docs/src/components/SidebarBadge.js)
+- Purpose: Small badge/chip for sidebar labels.
+- Use when: Marking sidebar items as OSS, enterprise, cloud, beta, or new.
+- Do not use when: Metadata should appear inside page content instead of navigation.
+- Props: `type = "oss"`, `showIcon = true`
+- Example: `<SidebarBadge type="enterprise" />`
+
+### `SidebarCategoryIcon`
+
+- File: [`src/components/SidebarCategoryIcon.js`](/Users/amaan-bhati/Documents/docs/src/components/SidebarCategoryIcon.js)
+- Purpose: Icon resolver and wrapper for top-level sidebar categories.
+- Use when: Extending the icon mapping for top-level docs categories.
+- Do not use when: The category is not represented in the sidebar or the icon is not part of the established mapping.
+- Props: `category`, `size = 16`, `className = ""`
+- Example: `<SidebarCategoryIcon category="api-testing" />`
+
+### `StartKeploy`
+
+- File: [`src/components/StartKeploy.js`](/Users/amaan-bhati/Documents/docs/src/components/StartKeploy.js)
+- Purpose: Tabbed language-specific quick commands for local recording/testing.
+- Use when: A page needs the standard record/test command starter across languages.
+- Do not use when: The page is Docker-focused.
+- Props: none
+- Example: `<StartKeploy />`
+
+### `StartKeployDocker`
+
+- File: [`src/components/StartKeployDocker.js`](/Users/amaan-bhati/Documents/docs/src/components/StartKeployDocker.js)
+- Purpose: Tabbed starter commands for Docker and Docker Compose.
+- Use when: A page is specifically about containerized recording/testing.
+- Do not use when: A language-based local starter is more appropriate.
+- Props: none
+- Example: `<StartKeployDocker />`
+
+### `TestingCapabilities`
+
+- File: [`src/components/TestingCapabilities.js`](/Users/amaan-bhati/Documents/docs/src/components/TestingCapabilities.js)
+- Purpose: Homepage section showing functional tests and quality gates as chip groups.
+- Use when: Explaining the breadth of Keploy testing types in the current homepage style.
+- Do not use when: A page only needs a short feature list.
+- Props: none
+- Example: `<TestingCapabilities />`
+
+### `TierCallout`
+
+- File: [`src/components/TierCallout.js`](/Users/amaan-bhati/Documents/docs/src/components/TierCallout.js)
+- Purpose: Inline chips or a subtle note block for tier/platform/feature metadata.
+- Use when: A doc needs lightweight metadata like `oss`, `docker`, `k8s`, or `ai-gen`.
+- Do not use when: Full section callouts or admonitions are more appropriate.
+- Props: `chips = []`, `type`, `children`
+- Example: `<TierCallout chips={["oss", "docker", "record-replay"]} />`
+
+### `UTGMethods`
+
+- File: [`src/components/UtgMethods.js`](/Users/amaan-bhati/Documents/docs/src/components/UtgMethods.js)
+- Purpose: Legacy three-card overview of unit-test-generation entry points.
+- Use when: Maintaining UTG landing content.
+- Do not use when: Building new homepage-standard sections.
+- Props: none
+- Example: `<UTGMethods />`
+
+### `WhatIsKeploy`
+
+- File: [`src/components/WhatIsKeploy.js`](/Users/amaan-bhati/Documents/docs/src/components/WhatIsKeploy.js)
+- Purpose: Homepage "About Keploy" narrative plus trust/compliance banner.
+- Use when: Editing the homepage's main product narrative.
+- Do not use when: A page only needs a short intro paragraph or a simple trust badge.
+- Props: none
+- Example: `<WhatIsKeploy />`
+
+## Theme overrides
+
+### `@theme/Heading`
+
+- File: [`src/theme/Heading/index.js`](/Users/amaan-bhati/Documents/docs/src/theme/Heading/index.js)
+- Purpose: Wraps Docusaurus headings to preserve anchor links and scroll offsets.
+- Use when: Editing how headings render across docs.
+- Do not use when: Building custom standalone heading components inside page sections unless you understand the anchor behavior you are bypassing.
+- Props: `as`, `id`, plus heading props from Docusaurus
+- Example: `<Heading as="h2" id="install">Install Keploy</Heading>`
+
+### `@theme/DocBreadcrumbs`
+
+- File: [`src/theme/DocBreadcrumbs/index.js`](/Users/amaan-bhati/Documents/docs/src/theme/DocBreadcrumbs/index.js)
+- Purpose: Breadcrumb rendering plus breadcrumb structured data.
+- Use when: Editing docs navigation breadcrumbs globally.
+- Do not use when: A page only needs a local back link.
+- Props: internal Docusaurus props only
+- Example: Automatic inside `DocItem`
+
+### `@theme/DocItem`
+
+- File: [`src/theme/DocItem/index.js`](/Users/amaan-bhati/Documents/docs/src/theme/DocItem/index.js)
+- Purpose: Global doc page shell, SEO metadata, TOC behavior, inline footer, and prose wrapper.
+- Use when: Editing docs page structure or markdown container behavior.
+- Do not use when: A page-level component can solve the issue locally.
+- Props: Docusaurus `content`/doc props
+- Example: Automatic for docs pages
+
+### `@theme/DocSidebarItem/Category`
+
+- File: [`src/theme/DocSidebarItem/Category.js`](/Users/amaan-bhati/Documents/docs/src/theme/DocSidebarItem/Category.js)
+- Purpose: Adds icon treatment to top-level sidebar categories.
+- Use when: Editing sidebar category icon behavior.
+- Do not use when: Icons should appear inside doc content instead of nav.
+- Props: Docusaurus sidebar item props
+- Example: Automatic in the docs sidebar
+
+### `@theme/Footer`
+
+- File: [`src/theme/Footer/index.js`](/Users/amaan-bhati/Documents/docs/src/theme/Footer/index.js)
+- Purpose: Pass-through wrapper for the default footer.
+- Use when: A future global footer override is needed.
+- Do not use when: A page-specific CTA strip like `KeployCloud` is enough.
+- Props: Docusaurus footer props
+- Example: Automatic in site layout
+
+### `@theme/Navbar` and `@theme/NavbarItem/DropdownNavbarItem`
+
+- Files: [`src/theme/Navbar/index.js`](/Users/amaan-bhati/Documents/docs/src/theme/Navbar/index.js), [`src/theme/NavbarItem/DropdownNavbarItem.js`](/Users/amaan-bhati/Documents/docs/src/theme/NavbarItem/DropdownNavbarItem.js)
+- Purpose: Thin wrappers around the default navbar and dropdown item.
+- Use when: Editing global navbar behavior.
+- Do not use when: A page-specific menu is enough.
+- Props: Docusaurus navbar props
+- Example: Automatic in site layout
+
+### `@theme/NotFound`
+
+- File: [`src/theme/NotFound/index.js`](/Users/amaan-bhati/Documents/docs/src/theme/NotFound/index.js)
+- Purpose: Wraps the default 404 page with layout and metadata.
+- Use when: Editing 404 behavior globally.
+- Do not use when: A normal page route should handle the case.
+- Props: none
+- Example: Automatic on unmatched routes
diff --git a/.claude/skills/design-agent/references/design-tokens.md b/.claude/skills/design-agent/references/design-tokens.md
new file mode 100644
index 000000000..83aade9fa
--- /dev/null
+++ b/.claude/skills/design-agent/references/design-tokens.md
@@ -0,0 +1,239 @@
+# Keploy Docs design tokens
+
+This repo does not have a single token source of truth. Core theme tokens live in [`src/css/custom.css`](/Users/amaan-bhati/Documents/docs/src/css/custom.css), custom Tailwind extensions live in [`tailwind.config.js`](/Users/amaan-bhati/Documents/docs/tailwind.config.js), and newer components also use Tailwind's default palette directly. Sections marked `[inferred]` come from repeated class usage rather than explicit config.
+
+## Stack
+
+| Area | Value | Source |
+| --- | --- | --- |
+| Site framework | Docusaurus 3.9.2 with React 18 | `package.json`, `docusaurus.config.js` |
+| Styling system | Tailwind CSS 3 + Docusaurus/Infima + plain CSS + CSS Modules + component-local `<style>` blocks | `package.json`, `tailwind.config.js`, `src/css/custom.css` |
+| Tailwind plugin | `@tailwindcss/typography` | `tailwind.config.js` |
+| Tailwind preflight | Disabled | `tailwind.config.js` |
+| Component helpers | Docusaurus theme components, `react-icons`, `react-player` | `package.json`, `src/components`, `src/theme` |
+| Component library status | No external UI kit such as shadcn/ui, Radix, Chakra, or MUI | repo scan |
+
+## Theme colors
+
+### Docusaurus CSS variables
+
+| Token | Light value | Dark value | Source |
+| --- | --- | --- | --- |
+| `--ifm-color-primary` | `#ff914d` | `#ff914d` | `src/css/custom.css` |
+| `--ifm-color-primary-dark` | `#e67643` | `#e67643` | `src/css/custom.css` |
+| `--ifm-color-primary-darker` | `#c95919` | `#c95919` | `src/css/custom.css` |
+| `--ifm-color-primary-darkest` | `#be2c1b` | `#be2c1b` | `src/css/custom.css` |
+| `--ifm-color-primary-light` | `#ffd0a0` | `#ffd0a0` | `src/css/custom.css` |
+| `--ifm-color-primary-lightest` | `#ffceb1` | `#ffceb1` | `src/css/custom.css` |
+| `--ifm-color-primary-lighter` | `#fff` | `#fff` | `src/css/custom.css` |
+| `--ifm-color` | `#00163d` | `#f5f6f7` | `src/css/custom.css` |
+| `--ifm-background-color` | `rgb(249, 250, 251)` | `#141414` | `src/css/custom.css` |
+| `--ifm-footer-background-color` | `#ffffff` | `#000000` | `src/css/custom.css` |
+| `--ifm-card-background-color` | `#ffffff` | `#1a1a1a` | `src/css/custom.css` |
+| `--ifm-card-shadow-color` | `rgba(0, 0, 0, 0.2)` | `rgba(255, 255, 255, 0.2)` | `src/css/custom.css` |
+| `--ifm-badge-background-color` | `rgba(239, 246, 255)` | `#f88e34` | `src/css/custom.css` |
+| `--card-color` | `rgba(239, 246, 255)` | `rgba(17, 24, 39)` | `src/css/custom.css` |
+| `--ifm-code-background` | `#fff7ed` | `rgba(251, 146, 60, 0.2)` | `src/css/custom.css` |
+| `--ifm-code-color` | `#c2410c` | `#fb923c` | `src/css/custom.css` |
+| `--ifm-code-border-color` | not set | `rgba(251, 146, 60, 0.4)` | `src/css/custom.css` |
+| `--ifm-blockquote-color` | `#000000` | `#eeeeee` | `src/css/custom.css` |
+| `--ifm-color-emphasis-300` | `#505050` | inherited | `src/css/custom.css` |
+| `--ifm-color-input-background` | `#ffffff` | inherited | `src/css/custom.css` |
+| `--collapse-button-bg-color-dark` | inherited | `transparent` | `src/css/custom.css` |
+
+### Tailwind custom colors
+
+| Tailwind token | Value | Source |
+| --- | --- | --- |
+| `offwhite` | `#F2F2F2` | `tailwind.config.js` |
+| `keployblue` | `#B2E7EA` | `tailwind.config.js` |
+| `keploybrightblue` | `#127AE5` | `tailwind.config.js` |
+| `keploypurple` | `#B8B4DC` | `tailwind.config.js` |
+| `keploybrightpurple` | `#8F86DA` | `tailwind.config.js` |
+| `spaceblack` | `#141414` | `tailwind.config.js` |
+| `green1` | `#9EE587` | `tailwind.config.js` |
+| `green2` | `#32D67B` | `tailwind.config.js` |
+| `orange1` | `#FFA280` | `tailwind.config.js` |
+| `orange2` | `#FF7065` | `tailwind.config.js` |
+| `gray5` | `#E0E0E0` | `tailwind.config.js` |
+| `lightgray` | `rgba(242,242,242,0.5)` | `tailwind.config.js` |
+| `lightteal` | `#C7EDEF` | `tailwind.config.js` |
+
+### Tailwind default palettes actively used `[inferred]`
+
+These classes appear repeatedly in newer components. They are not customized in `tailwind.config.js`; values come from Tailwind defaults used by Tailwind CSS 3.
+
+| Family | Exact class/value mappings used in repo | Typical usage |
+| --- | --- | --- |
+| `gray` | `gray-50 #f9fafb`, `gray-100 #f3f4f6`, `gray-200 #e5e7eb`, `gray-300 #d1d5db`, `gray-400 #9ca3af`, `gray-500 #6b7280`, `gray-600 #4b5563`, `gray-700 #374151`, `gray-800 #1f2937`, `gray-900 #111827`, `gray-950 #030712` | text, borders, dark surfaces, neutral CTAs |
+| `orange` | `orange-50 #fff7ed`, `orange-100 #ffedd5`, `orange-300 #fdba74`, `orange-400 #fb923c`, `orange-500 #f97316`, `orange-600 #ea580c`, `orange-700 #c2410c`, `orange-900 #7c2d12` | primary accent, CTA backgrounds, highlight borders |
+| `purple` | `purple-50 #faf5ff`, `purple-100 #f3e8ff`, `purple-200 #e9d5ff`, `purple-300 #d8b4fe`, `purple-400 #c084fc`, `purple-500 #a855f7`, `purple-600 #9333ea`, `purple-700 #7e22ce`, `purple-800 #6b21a8`, `purple-900 #581c87` | secondary accent, chips, cards |
+| `indigo` | `indigo-100 #e0e7ff`, `indigo-200 #c7d2fe`, `indigo-300 #a5b4fc`, `indigo-400 #818cf8`, `indigo-500 #6366f1`, `indigo-600 #4f46e5`, `indigo-700 #4338ca`, `indigo-900 #312e81` | enterprise/security section accents |
+| `blue` | `blue-50 #eff6ff`, `blue-100 #dbeafe`, `blue-200 #bfdbfe`, `blue-300 #93c5fd`, `blue-400 #60a5fa`, `blue-500 #3b82f6`, `blue-600 #2563eb`, `blue-700 #1d4ed8`, `blue-900 #1e3a8a` | cloud and GSoC banners |
+| `green` | `green-100 #dcfce7`, `green-400 #4ade80`, `green-500 #22c55e`, `green-600 #16a34a`, `green-700 #15803d`, `green-900 #14532d` | success and checklist accents |
+| `amber` | `amber-50 #fffbeb`, `amber-100 #fef3c7`, `amber-200 #fde68a`, `amber-300 #fcd34d`, `amber-400 #fbbf24`, `amber-500 #f59e0b`, `amber-600 #d97706`, `amber-700 #b45309`, `amber-900 #78350f` | sponsorship program callouts |
+| `red` | `red-100 #fee2e2`, `red-400 #f87171`, `red-600 #dc2626`, `red-900 #7f1d1d` | YouTube and error-adjacent accent use |
+| `pink` | `pink-400 #f472b6`, `pink-600 #db2777`, `pink-900 #831843` | gradient support accents |
+| `cyan` | `cyan-50 #ecfeff` | secondary gradient support |
+
+## Typography
+
+### Font families
+
+| Usage | Value | Source |
+| --- | --- | --- |
+| Global docs body copy | `"DM Sans", sans-serif !important` | `docusaurus.config.js`, `src/css/custom.css` |
+| Code and preformatted text | `ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace` | `src/css/custom.css` |
+| Headings, navbar, menu | `"Aeonik", system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"` | `src/css/custom.css` |
+| Local font faces | `Roboto` weights `300`, `400`, `700`; `fontFamily.light = ["Roboto Light", "sans"]` | `src/css/custom.css`, `tailwind.config.js` |
+
+Note: `Aeonik` is referenced but not loaded anywhere in this repo. `DM Sans` is loaded via Google Fonts in `docusaurus.config.js`.
+
+### Font sizes and line heights
+
+#### Explicit custom Tailwind extensions
+
+| Token | Value | Source |
+| --- | --- | --- |
+| `text-17` | `17px` | `tailwind.config.js` |
+| `text-60` | `60px` | `tailwind.config.js` |
+| `text-144` | `144px` | `tailwind.config.js` |
+| `leading-25` | `25px` | `tailwind.config.js` |
+| `leading-36` | `36px` | `tailwind.config.js` |
+| `leading-48` | `48px` | `tailwind.config.js` |
+| `leading-60` | `60px` | `tailwind.config.js` |
+| `leading-72` | `72px` | `tailwind.config.js` |
+| `leading-144` | `144px` | `tailwind.config.js` |
+| Root font size | `18px` | `src/css/custom.css` |
+| Root line height | `1.6` | `src/css/custom.css` |
+
+#### Common text utilities in active components `[inferred]`
+
+| Utility | Meaning | Seen in |
+| --- | --- | --- |
+| `text-xs` | compact helper text, eyebrow metadata | section pills, chips, captions |
+| `text-sm` | card body, CTA labels, chip labels | most cards and option rows |
+| `text-base` | longer narrative copy | section intros, narrative blurbs |
+| `text-lg` | subheads and strong support text | card titles and banner headings |
+| `text-xl` | prominent card titles | feature cards and banners |
+| `text-2xl` | legacy section titles | older homepage/MDX helpers |
+| `text-3xl md:text-4xl` | current homepage section titles | `GetStartedPaths`, `QuickStartTabs`, `TestingCapabilities`, `Community`, `EcosystemSupport`, `WhatIsKeploy` |
+
+### Prose and markdown overrides
+
+| Rule | Value | Source |
+| --- | --- | --- |
+| `prose` wrapper | `md:prose-md prose mx-auto my-12 max-w-full px-2 lg:prose-lg md:px-6` | `src/theme/DocItem/index.js` |
+| Link color in prose | `#E67643`, hover `#C95919` | `tailwind.config.js` typography extension |
+| Heading prose color | `var(--ifm-color)` | `tailwind.config.js` typography extension |
+| Code radius | `0.25rem` | `tailwind.config.js` typography extension |
+| Inline code padding | `0.15rem 0.3rem` | `tailwind.config.js` typography extension |
+| Images in prose | `borderRadius: 0.5rem`, `display: inline` | `tailwind.config.js` typography extension |
+| `h1` docs header effect | soft gradient text fill | `src/css/custom.css` |
+
+## Spacing scale
+
+No custom spacing scale is defined in `tailwind.config.js`. The repo uses Tailwind's default spacing utilities heavily.
+
+### Most common spacing classes `[inferred]`
+
+| Utility | Default Tailwind value | Typical usage |
+| --- | --- | --- |
+| `p-3` | `0.75rem` | nested option rows |
+| `p-4` | `1rem` | smaller cards and nested panels |
+| `p-5` | `1.25rem` | older legacy cards |
+| `p-6` | `1.5rem` | primary card padding |
+| `px-3 py-1` | `0.75rem` x `0.25rem` | pills and eyebrow labels |
+| `px-5 py-2.5` | `1.25rem` x `0.625rem` | medium CTA buttons |
+| `px-5 py-3` | `1.25rem` x `0.75rem` | large CTA buttons |
+| `gap-2` | `0.5rem` | chips, inline metadata |
+| `gap-3` | `0.75rem` | option rows |
+| `gap-4` | `1rem` | icon/content rows |
+| `gap-6` | `1.5rem` | section grids |
+| `mb-2` | `0.5rem` | eyebrow-to-heading spacing |
+| `mb-3` | `0.75rem` | heading-to-copy spacing |
+| `mb-6` | `1.5rem` | content block spacing |
+| `mb-8` | `2rem` | section header spacing |
+| `mb-12` | `3rem` | section separation |
+| `mb-16` | `4rem` | large section separation |
+| `md:p-10` | `2.5rem` | homepage shell padding |
+
+## Radii
+
+| Token/class | Value | Source |
+| --- | --- | --- |
+| `--ifm-code-border-radius` | `6px` | `src/css/custom.css` |
+| `rounded-md` | Tailwind default `0.375rem` `[inferred]` | `shared/Button.js`, newer buttons |
+| `rounded-lg` | Tailwind default `0.5rem` `[inferred]` | legacy cards, player shell |
+| `rounded-xl` | Tailwind default `0.75rem` `[inferred]` | newer CTAs, nested cards |
+| `rounded-2xl` | Tailwind default `1rem` `[inferred]` | primary modern card surfaces |
+| `rounded-full` | full pill radius `[inferred]` | badges and pills |
+| image radius in prose | `0.5rem` | `tailwind.config.js` typography extension |
+
+## Shadows
+
+| Token/class | Value | Source |
+| --- | --- | --- |
+| `shadow-keployblue` | `0 25px 50px -12px rgba(178, 231, 234, 0.1)` | `tailwind.config.js` |
+| `shadow-sm` | Tailwind default `[inferred]` | newer cards |
+| `shadow-md` | Tailwind default `[inferred]` | hover states and glossary buttons |
+| `shadow-lg` | Tailwind default `[inferred]` | prominent cards and CTAs |
+| `shadow-[0_4px_12px_var(--ifm-card-shadow-color)]` | custom arbitrary value | `GlossaryCard.js` |
+| `shadow-[0_8px_20px_var(--ifm-card-shadow-color)]` | custom arbitrary value | `GlossaryCard.js` |
+
+## Layout widths and sizing
+
+### Explicit Tailwind extensions
+
+| Token | Value | Source |
+| --- | --- | --- |
+| `grid-cols-usecases` | `200px minmax(0, 1fr)` | `tailwind.config.js` |
+| `max-w-700` | `700px` | `tailwind.config.js` |
+| `w-200` | `200px` | `tailwind.config.js` |
+| `w-300` | `300px` | `tailwind.config.js` |
+| `w-700` | `700px` | `tailwind.config.js` |
+| `w-800` | `800px` | `tailwind.config.js` |
+| `w-3/1` | `300%` | `tailwind.config.js` |
+| `h-60` | `60px` | `tailwind.config.js` |
+| `h-200` | `200px` | `tailwind.config.js` |
+| `h-300` | `300px` | `tailwind.config.js` |
+| `h-400` | `400px` | `tailwind.config.js` |
+| `h-700` | `700px` | `tailwind.config.js` |
+| `h-800` | `800px` | `tailwind.config.js` |
+| `h-3/1` | `300%` | `tailwind.config.js` |
+
+### Common width patterns `[inferred]`
+
+| Utility | Typical usage |
+| --- | --- |
+| `max-w-screen-lg` | homepage container |
+| `max-w-2xl`, `max-w-3xl`, `max-w-5xl`, `max-w-6xl` | section copy and grid wrappers |
+| `w-full` | cards, sections, nav shell |
+| `min-h-[92px]` | nested quickstart option rows |
+
+## Breakpoints
+
+No custom `screens` are defined in `tailwind.config.js`; the repo relies on Tailwind defaults.
+
+| Breakpoint | Value | Evidence |
+| --- | --- | --- |
+| `md` | `768px` `[inferred]` | `md:grid-cols-2`, `md:grid-cols-3`, `md:text-4xl`, `md:p-10` across `src/components` and `src/pages/index.js` |
+| `lg` | `1024px` `[inferred]` | `lg:gap-8`, `lg:px-10`, `lg:prose-lg` |
+| `xl` | `1280px` `[inferred]` | `xl:gap-8` in legacy sections |
+| Docusaurus desktop layout breakpoint | `997px` | `src/theme/DocItem/styles.module.css` |
+
+## Motion
+
+| Token | Value | Source |
+| --- | --- | --- |
+| `transitionDelay.3000` | `3000ms` | `tailwind.config.js` |
+| `fade-in-down` keyframes | opacity `0` to `1`, translateY `-10px` to `0` | `tailwind.config.js` |
+| `animate-fade-in-down` | `fade-in-down 0.5s ease-out` | `tailwind.config.js` |
+
+## Focus and accessibility styling
+
+| Rule | Value | Source |
+| --- | --- | --- |
+| Global focus visible | `outline: 2px solid #2563eb; outline-offset: 2px` | `src/css/custom.css` |
+| Interactive overrides | `button:focus-visible`, `a:focus-visible`, `input:focus-visible` use orange outline `rgba(255, 145, 77, 0.5)` | `src/css/custom.css` |
+| Code block copy button visibility | visible on container focus-within and button focus-visible | `src/css/custom.css` |

From 5a77b9b9954277616a54cfc5f806e59256ea0223 Mon Sep 17 00:00:00 2001
From: amaan-bhati <amaanbhati49@gmail.com>
Date: Wed, 15 Apr 2026 04:11:42 +0530
Subject: [PATCH 2/2] feat: add repo specific skill and improve skill.md

Signed-off-by: amaan-bhati <amaanbhati49@gmail.com>
---
 .claude/skills/design-agent/SKILL.md          | 104 +++----
 .../design-agent/references/docs-specific.md  | 266 ++++++++++++++++++
 2 files changed, 303 insertions(+), 67 deletions(-)
 create mode 100644 .claude/skills/design-agent/references/docs-specific.md

diff --git a/.claude/skills/design-agent/SKILL.md b/.claude/skills/design-agent/SKILL.md
index 52dadcde8..6d9879d87 100644
--- a/.claude/skills/design-agent/SKILL.md
+++ b/.claude/skills/design-agent/SKILL.md
@@ -1,85 +1,55 @@
 name: design-agent
 description: >
-  Use this skill when a contributor asks for /design-agent, design review, PR review, UI review, design feedback, visual QA, frontend consistency checks, component usage guidance, Tailwind review, CSS review, docs-site styling review, Docusaurus theme review, accessibility review, spacing review, typography review, or help matching Keploy Docs design conventions. Trigger this for PR review comments about design consistency, component usage, Tailwind/CSS conventions in this repo, hardcoded colors, inline styles, Docusaurus CSS variable usage, dark mode mismatches, focus states, and whether a page or component looks like the rest of the Keploy documentation site.
+  Use this skill when a contributor asks for /design-agent, docs design review, PR design feedback, Docusaurus UI review, docs-page consistency review, MDX component review, docs theme review, docs accessibility review, or help checking whether a change matches keploy/docs conventions beyond the shared Keploy design commons. Trigger it for reviews of docs-specific layout, Docusaurus theme overrides, sidebar/navigation behavior, docs metadata chips, prose styling, global docs CSS, and repo-local Tailwind/CSS patterns that are unique to keploy/docs.
 
-Design Agent — Keploy Documentation
-This agent reviews UI and frontend changes in the Keploy docs site, which is built on Docusaurus 3 with React, Tailwind CSS, Docusaurus theme overrides, and a large set of MDX helper components. It checks whether changes align with the repo's actual design system: Docusaurus CSS variables for core theming, Tailwind utility patterns on newer pages, and existing reusable components for chips, cards, quickstart flows, glossary cards, and docs metadata.
+Design Agent — Keploy Docs overrides
+This skill reviews only the design-system rules that are specific to the `keploy/docs` repository. It assumes the shared Keploy commons are already loaded, then applies the Docusaurus-specific, docs-shell-specific, and repo-local component/style overrides found in this repository.
 
-Trigger
-This skill is invoked when a contributor uses /design-agent or asks for design review, design feedback, or UI/UX guidance on a PR or commit.
+Loading order
+Load commons guidelines first, then apply these repo-specific overrides. In case of conflict, repo-specific rules take precedence.
 
-What to review in a PR
-When called on a PR or set of code changes, check for:
+When to use
+Use this skill for PRs or commits in `keploy/docs` that touch Docusaurus pages, MDX helpers, docs theme overrides, sidebar or breadcrumb behavior, docs layout, `src/css/custom.css`, `tailwind.config.js`, or any reusable component under `src/components` or `src/theme`.
 
-1. Token compliance
-Colors must prefer the repo's existing theme tokens from `src/css/custom.css`: `--ifm-color-primary` `#ff914d`, `--ifm-color-primary-dark` `#e67643`, `--ifm-color-primary-darker` `#c95919`, `--ifm-color-primary-darkest` `#be2c1b`, `--ifm-color-primary-light` `#ffd0a0`, `--ifm-color-primary-lightest` `#ffceb1`, `--ifm-color` `#00163d` in light mode and `#f5f6f7` in dark mode, `--ifm-background-color` `rgb(249, 250, 251)` in light mode and `#141414` in dark mode, `--ifm-card-background-color`, and `--ifm-card-shadow-color`.
-Use custom Tailwind colors from `tailwind.config.js` only when they already match an established pattern: `offwhite`, `keployblue`, `keploybrightblue`, `keploypurple`, `keploybrightpurple`, `spaceblack`, `green1`, `green2`, `orange1`, `orange2`, `gray5`, `lightgray`, `lightteal`.
-Do not introduce arbitrary values such as `bg-[#3b82f6]`, `text-[#7c3aed]`, or new one-off RGB values when an existing Docusaurus variable or existing Tailwind palette class already fits.
-`[inferred]` Newer homepage sections frequently use Tailwind's default gray/orange/purple/indigo families. Reuse those exact class families when extending those sections instead of inventing a new accent system.
-Flag `style={{ color: "#..." }}`, `style={{ background: "#..." }}`, and ad hoc token maps with raw hex values unless the file is already following that legacy pattern and the PR cannot reasonably normalize it.
+What to review
+Review only docs-specific overrides beyond the commons:
 
-2. Component usage
-Use `@docusaurus/Link` for internal navigation, not raw `<a href="/docs/...">`.
-Use `@theme/Heading` or markdown headings inside docs content so anchor links and scroll offsets keep working.
-Use `GlossaryCard` for glossary card grids.
-Use `DocHeaderChips`, `ProductTier`, or `TierCallout` for doc metadata chips instead of inventing another badge row.
-Use `QuickStartTabs` and `QuickStartFilter` when editing the quickstart entry experience; do not rebuild the same chooser pattern from scratch.
-Use `SidebarBadge` and `SidebarCategoryIcon` for sidebar labels/icons instead of ad hoc badge markup.
-`[inferred]` Reuse existing card anatomy from newer homepage sections: `rounded-2xl`, bordered surfaces, `p-6`, compact eyebrow pill, `text-3xl md:text-4xl` section headings, and dark-mode variants.
-There is no consistently enforced global button component in this repo. Do not force `src/components/shared/Button.js` everywhere, but do flag raw buttons/links that ignore existing CTA patterns, focus states, or dark-mode treatment.
+1. Docusaurus-specific tokens and theme variables
+Check whether changes use the repo’s Docusaurus token layer in `src/css/custom.css` when editing docs surfaces, markdown content, inline code, cards, navbar, footer, or docs background treatment.
+Flag changes that bypass docs-specific variables like `--ifm-color-primary`, `--ifm-color`, `--ifm-background-color`, `--ifm-card-background-color`, and `--ifm-card-shadow-color` when the change is clearly part of the docs shell rather than a one-off marketing section.
 
-3. Typography
-Docs pages force `DM Sans` globally through `src/css/custom.css`; code blocks intentionally revert to the system monospace stack.
-Headings and the navbar use an `Aeonik`-first fallback stack in `src/css/custom.css`; body copy on docs pages is still forced to `DM Sans`.
-Review heading hierarchy carefully: section headers on newer landing sections usually use `text-3xl font-bold tracking-tight md:text-4xl`; subheads are commonly `text-lg` or `text-xl` with `font-bold` or `font-semibold`; supporting copy is usually `text-sm`, `text-base`, or `text-xs` in gray text classes.
-In docs markdown, prose styling comes from Tailwind Typography plus Docusaurus overrides in `tailwind.config.js` and `src/theme/DocItem/index.js`.
-Flag jumps in hierarchy like using `text-4xl` for small card titles or mixing legacy `tracking-wide font-semibold` headings with the newer `tracking-tight font-bold` marketing pattern in the same section.
+2. Docs-shell components and theme overrides
+Check whether PRs preserve the behavior of `src/theme/DocItem`, `src/theme/Heading`, `src/theme/DocBreadcrumbs`, and `src/theme/DocSidebarItem/Category`.
+Flag raw replacements that break heading anchors, TOC behavior, breadcrumb semantics, sidebar icon treatment, or doc-page footer behavior.
 
-4. Spacing & layout
-The homepage shell uses `max-w-screen-lg` with `p-6 md:p-10` and stacked sections separated mostly by `mb-12` or `mb-16`.
-Common card spacing is `p-6`; compact nested options often use `p-3` or `p-4`.
-Common gaps are `gap-2`, `gap-3`, `gap-4`, and `gap-6`.
-Common max widths are `max-w-2xl`, `max-w-3xl`, `max-w-5xl`, and `max-w-6xl`.
-`[inferred]` Prefer `rounded-xl` or `rounded-2xl` on newer surfaces; `rounded-lg` appears mostly in older components.
-Flag new layouts that ignore the established page width, use inconsistent spacing steps, or introduce oversized padding/margins without a clear reason.
+3. Docs-specific reusable components
+Prefer the existing docs metadata and helper components when they match the job: `DocHeaderChips`, `ProductTier`, `TierCallout`, `SidebarBadge`, `SidebarCategoryIcon`, `GlossaryCard`, `QuickStartFilter`, `QuickStartTabs`, `StartKeploy`, `StartKeployDocker`, and `CollapsibleCode`.
+Do not require these components outside their scope, but do flag duplicate implementations of the same docs-specific patterns.
 
-5. Responsiveness
-This repo uses Tailwind's default responsive prefixes; no custom breakpoints are defined in `tailwind.config.js`.
-Common responsive patterns in source are `md:grid-cols-2`, `md:grid-cols-3`, `md:grid-cols-12`, `md:text-4xl`, `md:p-10`, `lg:gap-8`, `lg:px-10`, and Docusaurus' desktop breakpoint behavior around `997px` in `src/theme/DocItem/styles.module.css`.
-`[inferred]` New sections should collapse to one column on mobile, keep CTAs full-width or easy to tap, and avoid text that depends on hover-only disclosure.
-Flag any PR that adds fixed widths or desktop-only multi-column layouts without a mobile fallback.
+4. Docs typography and prose behavior
+Review changes against the docs-specific typography stack and prose rules in `src/css/custom.css`, `tailwind.config.js`, and `src/theme/DocItem/index.js`.
+Flag changes that break the docs body font override, code-font reset, heading anchor behavior, prose container sizing, or docs-specific gradient H1 treatment.
 
-6. Accessibility
-Keep visible focus treatment. Global focus styles are defined in `src/css/custom.css`, and some components add stronger local rings with `focus-visible:ring-*`.
-Preserve `aria-label` usage for icon-only links and action buttons; examples already exist in `src/theme/DocItem/index.js`, `src/theme/Heading/index.js`, `src/pages/concepts/reference/glossary.js`, and `src/components/WhatIsKeploy.js`.
-Images should keep meaningful `alt` text unless decorative.
-Internal controls that behave like toggles or filters should keep state semantics such as `aria-pressed`.
-If a PR adds `target="_blank"`, require `rel="noopener noreferrer"`.
-Flag `focus:outline-none` when it is not paired with an equivalent replacement ring or outline.
+5. Docs layout and responsiveness
+Check whether changes preserve the established docs layout model: centered long-form content, Docusaurus doc shell, and homepage sections that fit within the existing `max-w-screen-lg` / `max-w-*` patterns.
+Flag fixed-width layouts, desktop-only docs UI, or spacing that departs from the repo’s repeated docs patterns without reason.
 
-7. Anti-patterns to flag
-Inline styling for structure, spacing, or color in React components, especially in `InstallReminder`, `EnterpriseInstallReminder`, `SectionDivider`, `StartKeploy`, `StartKeployDocker`, and `ResponsivePlayer`.
-Hardcoded color maps and local `<style>` blocks for reusable chips/badges instead of shared tokens or CSS variables, as seen in `DocHeaderChips`, `SidebarBadge`, `ProductTier`, and `TierCallout`.
-Arbitrary value classes like `bg-[color:orange]`, `border-[color:orange]`, `bg-[var(--ifm-card-background-color)]`, and `shadow-[0_4px_12px_var(--ifm-card-shadow-color)]` when a standard class or central token would be clearer.
-Invalid or inconsistent JSX/SVG attributes such as raw `class=` and kebab-case `fill-rule` or `clip-rule`.
-Recreating cards, pill badges, or quickstart selectors that already exist in `src/components`.
-Mixing old `rounded-lg shadow-lg` legacy cards into newer `rounded-2xl border p-6` sections without an intentional visual reason.
-Introducing new font families or typography systems; this repo already has conflicting font choices and should not add more.
+6. Docs accessibility and navigation behavior
+Check icon links, toggle/filter controls, focus states, copy-button visibility, `aria-current` handling, and sidebar semantics.
+Flag regressions in keyboard focus visibility, missing accessible names on icon-only actions, or changes that weaken Docusaurus navigation semantics.
+
+7. Docs-specific anti-patterns
+Flag repo-local issues already present here and likely to spread: inline visual styles in React helpers, duplicated chip systems with local color maps, arbitrary-value classes for visual tokens, invalid JSX/SVG attributes, and mixing legacy `rounded-lg shadow-lg` cards into newer docs homepage sections without intent.
 
 How to deliver feedback
-When reviewing a PR, structure your feedback as follows:
+When reviewing a PR, structure feedback as:
 
-Summary — one paragraph overall design health assessment
-Critical issues — things that must be fixed before merge (broken design tokens, accessibility failures, missing required components)
-Suggestions — things that would improve consistency but aren't blockers
-Positive notes — what was done well (always include at least one)
+Summary — one paragraph on docs-specific design health
+Critical issues — docs-specific blockers that should be fixed before merge
+Suggestions — non-blocking consistency improvements
+Positive notes — at least one concrete thing done well
 
-Be specific. Reference actual line numbers or file names from the diff.
-Compare against guidelines in the references/ files.
-Never give vague feedback like "improve spacing" — say exactly what class or token should be used instead.
+Reference actual file names and line numbers from the diff. Keep comments specific to this repo’s docs overrides rather than restating the shared commons.
 
 Reference files
-
-Read references/design-tokens.md for all color, spacing, and typography values
-Read references/component-library.md for component usage rules
-Read references/anti-patterns.md for patterns to flag in review
+Read `references/docs-specific.md` for the repo-specific rules, tokens, components, and anti-patterns that apply only to `keploy/docs`.
diff --git a/.claude/skills/design-agent/references/docs-specific.md b/.claude/skills/design-agent/references/docs-specific.md
new file mode 100644
index 000000000..eabaf8c4e
--- /dev/null
+++ b/.claude/skills/design-agent/references/docs-specific.md
@@ -0,0 +1,266 @@
+# `keploy/docs` repo-specific design guidance
+
+This file contains only design-system rules and review guidance that are specific to `keploy/docs`, beyond the shared Keploy commons.
+
+## Stack and styling model
+
+- [explicit] This repo is a Docusaurus documentation site.
+  Evidence: `package.json` includes `@docusaurus/core`, `@docusaurus/preset-classic`, and `docusaurus.config.js`; `README.md` and `CONTRIBUTING.md` both describe the site as Docusaurus-based.
+
+- [explicit] Styling is split across Tailwind CSS 3, Docusaurus/Infima variables, global CSS in `src/css/custom.css`, CSS Modules in `src/theme/*/*.module.css`, and local `<style>` blocks inside React components.
+  Evidence: `tailwind.config.js`, `src/css/custom.css`, `src/theme/Heading/styles.module.css`, `src/theme/DocItem/styles.module.css`, `src/theme/DocBreadcrumbs/styles.module.css`, and component source such as `DocHeaderChips.js` and `QuickStartFilter.js`.
+
+- [explicit] Tailwind preflight is disabled because the repo relies on Docusaurus base styles.
+  Evidence: `tailwind.config.js`.
+
+- [explicit] Tailwind Typography is extended for docs prose.
+  Evidence: `tailwind.config.js`.
+
+## Docs-specific tokens and theme variables
+
+- [explicit] The docs repo defines Docusaurus theme variables that should be treated as the primary token layer for docs-shell surfaces:
+  - `--ifm-color-primary: #ff914d`
+  - `--ifm-color-primary-dark: #e67643`
+  - `--ifm-color-primary-darker: #c95919`
+  - `--ifm-color-primary-darkest: #be2c1b`
+  - `--ifm-color-primary-light: #ffd0a0`
+  - `--ifm-color-primary-lightest: #ffceb1`
+  - `--ifm-color: #00163d` in light mode and `#f5f6f7` in dark mode
+  - `--ifm-background-color: rgb(249, 250, 251)` in light mode and `#141414` in dark mode
+  - `--ifm-card-background-color: #ffffff` in light mode and `#1a1a1a` in dark mode
+  - `--ifm-card-shadow-color: rgba(0, 0, 0, 0.2)` in light mode and `rgba(255, 255, 255, 0.2)` in dark mode
+  Evidence: `src/css/custom.css`.
+
+- [explicit] Inline code gets repo-specific docs styling:
+  - light background `#fff7ed`
+  - light text `#c2410c`
+  - radius `6px`
+  Evidence: `src/css/custom.css`.
+
+- [explicit] This repo also extends Tailwind with docs-local colors not part of the shared commons:
+  - `offwhite #F2F2F2`
+  - `keployblue #B2E7EA`
+  - `keploybrightblue #127AE5`
+  - `keploypurple #B8B4DC`
+  - `keploybrightpurple #8F86DA`
+  - `spaceblack #141414`
+  - `green1 #9EE587`
+  - `green2 #32D67B`
+  - `orange1 #FFA280`
+  - `orange2 #FF7065`
+  - `gray5 #E0E0E0`
+  - `lightgray rgba(242,242,242,0.5)`
+  - `lightteal #C7EDEF`
+  Evidence: `tailwind.config.js`.
+
+- [explicit] Tailwind also defines repo-local sizing and motion extensions:
+  - `fontSize`: `17`, `60`, `144`
+  - `lineHeight`: `25`, `36`, `48`, `60`, `72`, `144`
+  - widths and heights: `200`, `300`, `700`, `800`, `3/1`
+  - `maxWidth.700`
+  - `gridTemplateColumns.usecases`
+  - `transitionDelay.3000`
+  - `animation.fade-in-down`
+  Evidence: `tailwind.config.js`.
+
+## Typography and prose behavior
+
+- [explicit] Docs pages forcibly apply `"DM Sans", sans-serif` across docs UI and markdown content.
+  Evidence: `src/css/custom.css`.
+
+- [explicit] Code blocks and inline code are forcibly reset to a monospace stack.
+  Evidence: `src/css/custom.css`.
+
+- [explicit] Headings, the menu, and the navbar use an `Aeonik`-first font stack, separate from docs body text.
+  Evidence: `src/css/custom.css`.
+
+- [inferred] Reviewers should treat the body/heading font split as an intentional docs-specific override in this repo, even though the font system is internally inconsistent and `Aeonik` is not loaded in the repo.
+  Evidence: `src/css/custom.css`, `docusaurus.config.js`.
+
+- [explicit] The docs markdown container is wrapped with:
+  - `prose`
+  - `md:prose-md`
+  - `lg:prose-lg`
+  - `mx-auto my-12 max-w-full px-2 md:px-6`
+  Evidence: `src/theme/DocItem/index.js`.
+
+- [explicit] Tailwind Typography overrides docs prose to use Docusaurus variables for text and headings, orange link color, rounded inline code, and rounded inline images.
+  Evidence: `tailwind.config.js`.
+
+- [explicit] Docs H1 headings receive a gradient text treatment in the docs shell.
+  Evidence: `src/css/custom.css`.
+
+## Layout and page-shell rules
+
+- [explicit] The homepage uses a centered container with `max-w-screen-lg`, `px-8` at the `Layout` level, and `p-6 md:p-10` inside `<main>`.
+  Evidence: `src/pages/index.js`.
+
+- [explicit] On docs pages, `DocItem` constrains the main column to `75%` on desktop when TOC is present.
+  Evidence: `src/theme/DocItem/styles.module.css`.
+
+- [explicit] The navbar is forced to full viewport width and the docs page shell backgrounds are overridden in global CSS.
+  Evidence: `src/css/custom.css`.
+
+- [explicit] Sidebar behavior is heavily customized in `src/css/custom.css`:
+  - active category labels should not be highlighted like leaf pages
+  - categories with their own landing pages should preserve normal text color
+  - hover backgrounds are unified on collapsible category rows
+  - caret icon sizing is normalized
+  Evidence: `src/css/custom.css`.
+
+- [inferred] For new homepage-style sections in this repo, the dominant modern pattern is:
+  - centered section headers
+  - `text-3xl font-bold tracking-tight md:text-4xl`
+  - compact eyebrow pills
+  - cards using `rounded-2xl`, border, `p-6`, and dark-mode variants
+  Evidence: `GetStartedPaths.js`, `QuickStartTabs.js`, `TestingCapabilities.js`, `Community.js`, `EcosystemSupport.js`, `WhatIsKeploy.js`.
+
+- [inferred] Older sections still use `rounded-lg`, `shadow-lg`, and simpler card markup; reviewers should avoid spreading that older pattern into new work unless the PR is editing the legacy section in place.
+  Evidence: `QuickStart.js`, `SDKs.js`, `Intro.js`, `Product.js`, `UtgMethods.js`, `GSoC.js`, `Hacktoberfest.js`, `GitTogether.js`.
+
+## Docs-specific component inventory and usage rules
+
+### Theme overrides
+
+- [explicit] `src/theme/Heading/index.js`
+  - Wraps headings to preserve anchor behavior and collect broken-link anchors.
+  - Adds a hidden hash-link target with `aria-label` and `title`.
+  - Review rule: do not replace docs headings with raw elements in theme-level code if that would bypass anchor-link behavior.
+
+- [explicit] `src/theme/DocItem/index.js`
+  - Owns doc-page SEO metadata, breadcrumb rendering, TOC behavior, prose wrapper, version badge row, inline footer, and the `KeployCloud` strip.
+  - Review rule: treat this as the canonical docs page shell; avoid duplicating page-shell concerns elsewhere.
+
+- [explicit] `src/theme/DocBreadcrumbs/index.js`
+  - Adds breadcrumb structured data and breadcrumb nav markup with an ARIA label.
+  - Review rule: preserve breadcrumb semantics if editing.
+
+- [explicit] `src/theme/DocSidebarItem/Category.js`
+  - Adds top-level sidebar category icon treatment via `SidebarCategoryIcon`.
+  - Review rule: extend the icon mapping rather than duplicating top-level category icon markup.
+
+### Reusable docs components
+
+- [explicit] `DocHeaderChips`
+  - Props: `tier`, `version`, `availability = []`
+  - Use for compact doc metadata rows.
+  - Source: `src/components/DocHeaderChips.js`
+
+- [explicit] `ProductTier`
+  - Props: `tiers`, `offerings`
+  - Use for compact tier/offering chips.
+  - Source: `src/components/ProductTier.js`
+
+- [explicit] `TierCallout`
+  - Props: `chips = []`, `type`, `children`
+  - Can render either inline chips or a subtle note block with chips.
+  - Source: `src/components/TierCallout.js`
+
+- [explicit] `SidebarBadge`
+  - Props: `type = "oss"`, `showIcon = true`
+  - Use for sidebar-specific labels such as `oss`, `enterprise`, `cloud`, `beta`, `new`.
+  - Source: `src/components/SidebarBadge.js`
+
+- [explicit] `SidebarCategoryIcon`
+  - Props: `category`, `size = 16`, `className = ""`
+  - Use for top-level sidebar category icon mapping.
+  - Source: `src/components/SidebarCategoryIcon.js`
+
+- [explicit] `GlossaryCard`
+  - Props: `name`, `description`, `link`
+  - Use for glossary card grids.
+  - Source: `src/components/GlossaryCard.js`
+
+- [explicit] `QuickStartFilter`
+  - Props: `defaultLanguage = null`
+  - Multi-step quickstart wizard.
+  - Source: `src/components/QuickStartFilter.js`
+
+- [explicit] `QuickStartTabs`
+  - No props.
+  - Two-path quickstart chooser for AI vs OSS flow.
+  - Source: `src/components/QuickStartTabs.js`
+
+- [explicit] `CollapsibleCode`
+  - Props: `code`, `language = "json"`, `previewLines = 10`
+  - Use for long code samples with preview/copy behavior.
+  - Source: `src/components/CollapsibleCode.js`
+
+- [explicit] `StartKeploy`
+  - No props.
+  - Tabbed starter commands for local language runtimes.
+  - Source: `src/components/StartKeploy.js`
+
+- [explicit] `StartKeployDocker`
+  - No props.
+  - Tabbed starter commands for Docker/Docker Compose flows.
+  - Source: `src/components/StartKeployDocker.js`
+
+- [inferred] When a PR creates a new metadata strip, tier chip, glossary card, quickstart chooser, or sidebar badge/icon treatment, reviewers should first check whether one of the components above already solves the problem.
+
+## Accessibility and interaction patterns unique to this repo
+
+- [explicit] Code-block copy buttons are made visible on keyboard focus via `:focus-within` and `:focus-visible` in global CSS.
+  Evidence: `src/css/custom.css`.
+
+- [explicit] The repo defines a global `:focus-visible` outline and then adds orange-focused overrides for `button`, `a`, and `input`.
+  Evidence: `src/css/custom.css`.
+
+- [explicit] Docs heading anchors have accessible names through `aria-label` and `title`.
+  Evidence: `src/theme/Heading/index.js`.
+
+- [explicit] Glossary navigation uses `role="navigation"`, `aria-label`, and `aria-pressed`.
+  Evidence: `src/pages/concepts/reference/glossary.js`.
+
+- [explicit] The docs sidebar styling explicitly relies on `aria-current="page"` to differentiate category links from leaf-page active states.
+  Evidence: `src/css/custom.css`.
+
+- [inferred] Reviewers should treat docs navigation semantics as fragile because this repo customizes Docusaurus sidebar and breadcrumb behavior more than a default docs site.
+
+## Authoring and docs-specific constraints
+
+- [explicit] The repo has a written style guide for docs writing in `STYLE.md`.
+  It requires:
+  - sentence case headings
+  - infinitive verb forms in headings
+  - capitalization of Keploy-specific terms
+  - active voice
+  - globally readable language
+  Evidence: `STYLE.md`.
+
+- [explicit] Contributors are told in `CONTRIBUTING.md` and `README.md` to follow the style guide and the existing docs structure/design.
+
+- [inferred] For design review, that means UI or MDX changes should avoid introducing heading or metadata treatments that fight the repo’s documentation-oriented content structure.
+
+## Docs-specific anti-patterns to flag
+
+- [explicit] Inline visual styling is common in legacy helper components and should be flagged when newly introduced:
+  - `InstallReminder.js`
+  - `EnterpriseInstallReminder.js`
+  - `SectionDivider.js`
+  - `StartKeploy.js`
+  - `StartKeployDocker.js`
+  - `ResponsivePlayer.js`
+
+- [explicit] Several metadata and badge helpers use hardcoded local color maps rather than the docs variable layer:
+  - `DocHeaderChips.js`
+  - `SidebarBadge.js`
+  - `ProductTier.js`
+  - `TierCallout.js`
+  - `SidebarCategoryIcon.js`
+
+- [explicit] Invalid JSX/SVG attributes already exist and should not spread:
+  - raw `class` in `QuickStart.js`
+  - kebab-case `fill-rule` and `clip-rule` in `Product.js`
+
+- [explicit] `CollapsibleCode.js` uses a hardcoded DOM id `copy-full-code`, which is risky for a reusable component.
+
+- [explicit] `QuickStartFilter.js` mixes Tailwind, component-local `<style>` rules, and multiple inline styles in one component.
+
+- [inferred] New PRs should not copy the legacy pattern of large one-off CSS-in-JS objects or local color dictionaries when the change belongs to the docs shell or a reusable docs helper.
+
+- [inferred] New PRs should not introduce more visual divergence between:
+  - older docs helper sections using `rounded-lg shadow-lg`
+  - newer homepage sections using `rounded-2xl border p-6`
+
+- [inferred] When editing newer homepage sections, prefer extending the existing newer pattern rather than backsliding to the older helper-card style.