Closed
Conversation
Signed-off-by: amaan-bhati <amaanbhati49@gmail.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new .claude “design-agent” skill intended to guide design/UI-focused PR reviews in this docs repo by documenting the current design tokens, reusable component inventory, and common frontend anti-patterns.
Changes:
- Introduces
design-agentskill definition and review checklist (.claude/skills/design-agent/SKILL.md). - Adds design token reference documentation for theme variables, Tailwind extensions, and inferred usage (
references/design-tokens.md). - Adds component inventory and anti-pattern guidance for consistent UI contributions (
references/component-library.md,references/anti-patterns.md).
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| .claude/skills/design-agent/SKILL.md | Defines when/how to invoke the design review skill and what to check. |
| .claude/skills/design-agent/references/design-tokens.md | Documents the repo’s theme variables, Tailwind tokens, typography, spacing, and related conventions. |
| .claude/skills/design-agent/references/component-library.md | Catalogs reusable src/components/* and src/theme/* building blocks and when to use them. |
| .claude/skills/design-agent/references/anti-patterns.md | Lists existing styling/UX pitfalls to flag during reviews and suggests alternatives. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Signed-off-by: amaan-bhati <amaanbhati49@gmail.com>
Signed-off-by: amaan-bhati <amaanbhati49@gmail.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new .claude “design-agent” skill to capture keploy/docs-specific design system guidance for design/UI reviews (tokens, components, accessibility patterns, and known anti-patterns), extending beyond shared Keploy commons.
Changes:
- Introduces a
design-agentskill definition (SKILL.md) describing when/how to use it for docs design reviews. - Adds repo-specific reference docs covering docs styling model, tokens, component inventory, and anti-patterns.
- Documents Docusaurus/Tailwind/Infima conventions and accessibility patterns observed in this repo to guide consistent reviews.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| .claude/skills/design-agent/SKILL.md | Defines the Claude skill scope, trigger conditions, and review rubric for keploy/docs design changes. |
| .claude/skills/design-agent/references/docs-specific.md | Captures docs-site-specific styling/tokens/layout/component rules unique to this repository. |
| .claude/skills/design-agent/references/design-tokens.md | Documents token sources (Infima vars + Tailwind extensions) and commonly used palette/typography utilities. |
| .claude/skills/design-agent/references/component-library.md | Inventories reusable components/theme overrides to encourage reuse and consistency. |
| .claude/skills/design-agent/references/anti-patterns.md | Lists repo-known styling/JSX anti-patterns to flag in future PRs. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a repo-specific “design-agent” Claude skill package for keploy/docs, capturing local design tokens, component inventory, and known UI anti-patterns to guide design-focused PR reviews in this repo.
Changes:
- Introduces the
design-agentskill definition (SKILL.md) describing when/how to apply docs-specific design review rules. - Adds repo-specific reference docs covering docs-shell guidance, design tokens, component library inventory, and anti-patterns.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
.claude/skills/design-agent/SKILL.md |
Defines the design-agent skill and its review scope for keploy/docs. |
.claude/skills/design-agent/references/docs-specific.md |
Captures Docusaurus/docs-shell specific guidance and conventions unique to this repo. |
.claude/skills/design-agent/references/design-tokens.md |
Documents token sources (Infima variables + Tailwind extensions) and commonly used styling primitives. |
.claude/skills/design-agent/references/component-library.md |
Inventories reusable components and theme overrides with usage guidance. |
.claude/skills/design-agent/references/anti-patterns.md |
Lists existing repo anti-patterns the agent should flag to prevent further spread. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new .claude “design-agent” skill package intended to guide Claude-driven design reviews for the keploy/docs Docusaurus site, capturing repo-specific tokens, styling conventions, reusable components, and known UI anti-patterns.
Changes:
- Introduces the
design-agentskill definition (SKILL.md) describing when/how to apply docs-specific design review guidance. - Adds repo-scoped reference docs for design tokens, component inventory, docs-specific conventions, and anti-patterns.
- Centralizes citations to existing
src/*implementation details to support consistent future reviews.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| .claude/skills/design-agent/SKILL.md | Defines the design-agent skill purpose, scope, and review checklist for this repo. |
| .claude/skills/design-agent/references/docs-specific.md | Documents keploy/docs-specific styling model, tokens, layout rules, and UX constraints. |
| .claude/skills/design-agent/references/design-tokens.md | Catalogs Docusaurus CSS variables and Tailwind extensions used as the docs token layer. |
| .claude/skills/design-agent/references/component-library.md | Lists reusable src/components/* and src/theme/* building blocks and usage guidance. |
| .claude/skills/design-agent/references/anti-patterns.md | Enumerates known styling/JSX/accessibility anti-patterns that reviewers should flag. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new Claude skill (design-agent) to provide keploy/docs-specific design review guidance, consolidating docs UI conventions, tokens, component inventory, accessibility considerations, and known anti-patterns into referenceable documents.
Changes:
- Add
design-agentskill manifest describing when/how to apply docs-specific design review rules. - Add repo-specific references for docs styling model, design tokens, component inventory, and anti-patterns.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| .claude/skills/design-agent/SKILL.md | Defines the design-agent skill scope and review checklist for keploy/docs. |
| .claude/skills/design-agent/references/docs-specific.md | Captures repo-specific docs UX rules (stack, layout, typography, components, accessibility). |
| .claude/skills/design-agent/references/design-tokens.md | Documents theme variables + Tailwind extensions/tokens used in the docs site. |
| .claude/skills/design-agent/references/component-library.md | Inventories reusable src/components and src/theme elements with usage guidance. |
| .claude/skills/design-agent/references/anti-patterns.md | Lists patterns to flag during design review (inline styles, hardcoded colors, invalid JSX, etc.). |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Signed-off-by: amaan-bhati <amaanbhati49@gmail.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a repo-specific Claude “design-agent” skill under .claude/skills/design-agent/ to guide design/UI reviews for this Docusaurus docs site, capturing Keploy Docs–specific tokens, component reuse guidance, and known UI anti-patterns.
Changes:
- Introduces the
design-agentskill definition (SKILL.md) describing when/how to apply the skill. - Adds repo-specific design guidance (
docs-specific.md) focused on Docusaurus/Tailwind/Infima usage, layout rules, and accessibility considerations. - Adds supporting reference docs: design tokens, component library inventory, and anti-patterns.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
.claude/skills/design-agent/SKILL.md |
Defines the scope, triggers, and review checklist for the design-agent skill. |
.claude/skills/design-agent/references/docs-specific.md |
Documents keploy/docs-specific design rules (stack, tokens, typography, layout, accessibility, anti-patterns). |
.claude/skills/design-agent/references/design-tokens.md |
Catalogs theme variables and Tailwind extensions used as effective design tokens in this repo. |
.claude/skills/design-agent/references/component-library.md |
Lists reusable components/theme overrides and when to reuse vs avoid them. |
.claude/skills/design-agent/references/anti-patterns.md |
Records known styling/UX pitfalls to flag during reviews to avoid spreading legacy issues. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new .claude “design-agent” skill to codify keploy/docs-specific design review guidance (tokens, component reuse, theme overrides, and known UI anti-patterns) so future PR reviews can be more consistent with this repo’s Docusaurus/Tailwind patterns.
Changes:
- Introduces the
design-agentskill definition (SKILL.md) describing when/how to apply docs-specific design review rules. - Adds repo-specific references covering docs styling model, tokens/theme variables, component inventory, and anti-patterns.
- Documents existing accessibility and navigation semantics that are customized in this repo (e.g., focus-visible behavior, sidebar/breadcrumb semantics).
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| .claude/skills/design-agent/SKILL.md | Defines the skill scope and review checklist for keploy/docs design/UI changes. |
| .claude/skills/design-agent/references/docs-specific.md | Captures repo-specific design rules (Docusaurus shell, typography, layout, component usage). |
| .claude/skills/design-agent/references/design-tokens.md | Documents the effective token sources (CSS vars + Tailwind extensions + inferred usage). |
| .claude/skills/design-agent/references/component-library.md | Inventories reusable components and theme overrides to encourage reuse over duplication. |
| .claude/skills/design-agent/references/anti-patterns.md | Lists existing UI/code anti-patterns to flag so they don’t spread to new work. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
nehagup
reviewed
Apr 15, 2026
Member
nehagup
left a comment
nehagup
left a comment
There was a problem hiding this comment.
Summary
The skill is technically rigorous but vibe-blind. It does a solid job cataloguing what already exists in keploy/docs (tokens,
components, anti-patterns), but it reviews the plumbing of design, not design itself. Run as-is, it will produce reviews like "use
--ifm-card-background-color instead of #fff" — useful, but it will never push a PR from "functional" to "feels expensive." For an
enterprise + PLG dev-tool aesthetic, that's a miss.
Critical issues (must fix before merge)
- SKILL.md is missing YAML frontmatter fences. Lines 7–9 start with name: / description: but there are no --- delimiters. Claude Code
skills won't load the metadata correctly without them. This is a structural bug, not a style nit. - The "commons" it depends on doesn't exist in this PR. SKILL.md repeatedly says "load commons first, then apply overrides" — but
there's no shared Keploy design-commons skill linked, vendored, or referenced by path. Right now this is half a system. Either inline
the commons rules or commit them in the same PR (or in keploy/landing and reference the path). - It never references the canonical brand guideline (context/design-and-content-guidelines.md: light-premium,
Linear/Vercel/Stripe/Resend inspiration, brand #FF914D + #00163D, no orange-50 gradients, etc.). The skill should explicitly defer to
that document as the north star.
Major gaps for "premium dev-tool feel"
- No design philosophy section. A reviewer needs principles, not just tokens: restraint over decoration, whitespace as a feature,
depth via shadow not borders, typographic rhythm, one accent color used sparingly. Without these, the agent will green-light
technically-correct-but-ugly PRs. - No exemplar references. Add 4–6 named "look at how X does this" pointers — Vercel docs, Stripe docs, Linear changelog, Resend docs,
Supabase docs, Raycast. Reviewer should compare against these explicitly. - Color sprawl is documented but not flagged. design-tokens.md lists 9 Tailwind families + 13 keploy* custom colors + Docusaurus vars.
A senior reviewer would mark keployblue/keploypurple/keploybrightpurple/lightteal/orange1/orange2/green1/green2 as legacy,
do-not-use-in-new-work and pin the palette to: brand orange #FF914D, dark blue #00163D, neutral grays, and semantic green/red. Right
now the skill just inventories sprawl instead of pruning it. - Code blocks get zero attention. This is a docs site — code rendering is the #1 visual element. Nothing on syntax theme, file-name
headers, copy-button placement, line wrapping, language label chips, or dark/light parity. Add a whole "code surface" section. - Typography rhythm is missing. Tokens are listed; rules aren't: target line length 65–75ch, body line-height 1.6–1.75, heading
line-height 1.1–1.25, weight pairing (avoid 400 next to 700, prefer 500/600 contrast), tracking on display sizes. The DM Sans / Aeonik
split is documented as "intentional" but Aeonik isn't even loaded — that's a bug the skill should flag, not normalize. - Motion principles are absent. "Fluid, good vibes" is mostly motion. Add: easing curves (no linear, prefer cubic-bezier(0.4, 0, 0.2,
1)), durations (150–250ms micro, 400–600ms macro), hover lift on cards, prefers-reduced-motion respect, no parallax in docs. - Dark mode discipline is missing. No rules for: avoid pure #000, use #0a0a0a/#18181b, elevate dark cards via 1px hairline border not
heavy shadow, image/illustration swaps for dark, contrast checks. Premium dark mode is the #1 thing that separates Linear/Vercel from
average dev tools. - No information-design review. A docs-design reviewer should also evaluate: page has a clear job, scannability (TL;DR/key-takeaway
blocks), heading hierarchy, code-to-prose ratio, callouts used appropriately, every page answers "what / why / how / next." None of
this is in scope right now. - No diagram/illustration standards. Engineering docs live or die on diagrams. Add: mermaid theme override, SVG line weights,
consistent palette, dark-mode diagram swaps, no rasterized text in PNGs. - No accessibility beyond focus. Add WCAG AA contrast checks (4.5:1 body, 3:1 large), 44×44 touch targets, no color-as-only-signal,
alt text on prose images. - The "don't require rewrites of legacy" escape hatch is too generous. As written, it bakes mediocrity in forever. Tighten to: if a
PR adds new content to a legacy section, the legacy markup in the immediate scope must be upgraded to the modern pattern; standalone
unrelated legacy is left alone. Otherwise the modern/legacy split never closes.
Smaller suggestions
- Add a worked example. Include one full sample PR review in the skill so the agent has a concrete output to imitate (with file:line
references, severity calibration, and gh pr review --comment style suggestions). - Severity ladder. Define blocking / should-fix / nit / praise so the agent doesn't treat hex-color-vs-token at the same level as
"this section has no visual hierarchy." - Component library file is missing 4 things per entry: a screenshot or ASCII sketch, the visual purpose ("brand moment vs utility"),
accessibility notes, and "last reviewed" date so legacy callouts decay correctly. - anti-patterns.md should also list "good patterns to copy" — right now it's all "don't." Pair each anti-pattern with a 1-line "this
is the modern equivalent in this repo." - Mention the inspiration sheet (context/Website inspirations.xlsx) as required reading before any visual review.
- Add a "first impression" heuristic check: agent should answer "if a Staff Engineer at Stripe/Vercel landed on this page cold, would
they think 'serious infra' or 'side project'?" Force the qualitative judgment.
Positive notes
- The scoping discipline (only docs-specific overrides, defer to commons) is exactly right — keeps the skill maintainable and stops it
duplicating cross-repo rules. - design-tokens.md distinguishing [explicit] vs [inferred] is genuinely good practice and rare in design-system docs. Keep that.
- anti-patterns.md with real Seen in: file lists makes the agent's feedback actionable instead of abstract.
- The accessibility-focus and aria-current discipline section shows the intern noticed real Docusaurus-specific failure modes.
- Acknowledging the legacy/modern card-style split honestly (rather than pretending it's uniform) is mature.
Bottom line
Ship it after fixing the YAML frontmatter and the missing-commons gap (critical issues 1–3). But before you actually use it as your
design reviewer, layer on a references/design-principles.md that encodes the Linear/Vercel/Stripe vibe, the pruned palette, motion
rules, dark-mode discipline, code-surface rules, and the "first impression" heuristic. Without that layer, this skill will keep your
docs consistent but it won't make them premium.
Member
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What has changed?
will update the pr descriptio once completed
Please include a summary of the change.
This PR Resolves #(issue)
Type of change
Please delete options that are not relevant.
How Has This Been Tested?
Please run npm run build and npm run serve to check if the changes are working as expected. Please include screenshots of the output of both the commands. Add screenshots/gif of the changes if possible.
Checklist: