diff --git a/.claude/skills/design-agent/SKILL.md b/.claude/skills/design-agent/SKILL.md new file mode 100644 index 000000000..6f343d8cc --- /dev/null +++ b/.claude/skills/design-agent/SKILL.md @@ -0,0 +1,57 @@ +name: design-agent +description: > + 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 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. + +Loading order +Load commons guidelines first, then apply these repo-specific overrides. In case of conflict, repo-specific rules take precedence. + +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`. +Evaluate the current file contents in the PR diff before repeating feedback from earlier review rounds; do not assume an older comment still applies if the relevant text or implementation has already changed. + +What to review +Review only docs-specific overrides beyond the commons: + +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. + +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. + +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. + +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. + +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. + +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. +When a PR edits an older helper component, prefer small consistency fixes over opportunistic visual rewrites unless the PR is explicitly modernizing that surface. + +How to deliver feedback +When reviewing a PR, structure feedback as: + +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 + +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/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/anti-patterns.md b/.claude/skills/design-agent/references/anti-patterns.md new file mode 100644 index 000000000..5118f9d43 --- /dev/null +++ b/.claude/skills/design-agent/references/anti-patterns.md @@ -0,0 +1,306 @@ +# 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". + +These examples are primarily copy-forward risks. Their presence in existing legacy files does not automatically mean every touched file should be rewritten unless the PR is already changing that surface in a meaningful way. + +## 1. Inline styles for color, spacing, borders, or layout + +What it looks like: + +```jsx +
+``` + +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 +
+``` + +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 + +``` + +Or, for doc-wide theming, prefer a class that references the theme variable: + +```jsx + +``` + +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 +
+``` + +```jsx + +``` + +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 +
+``` + +```jsx + +``` + +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 +
+ +
+
+``` + +Why it's wrong: + +- It combines Tailwind, large inline `