{"owner":"thedaviddias","repo":"Front-End-Checklist","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["CLAUDE.md","AGENTS.md"],"files":{"CLAUDE.md":"# Project Guidance\n\nUse [AGENTS.md](AGENTS.md) for repository conventions, workflows, and tool setup.\n\nLocal Claude Code session state belongs in `.claude/`, which is ignored by git and should not be committed.\n","AGENTS.md":"# AGENTS.md — Front-End Checklist\n\nRepository rules and conventions for contributors and automation tools.\n\n## Project Overview\n\n**Front-End Checklist** is an open-source monorepo providing 385 quality-gated frontend best practice rules with an MCP server for structured review workflows.\n\n- **MCP Server**: `https://mcp.frontendchecklist.io` (11 tools)\n- **Rules**: `packages/content/rules/en/<category>/<slug>.mdx`\n- **Web App**: `apps/web/` (Next.js App Router)\n- **MCP Package**: `packages/mcp/` (TypeScript)\n- **Package Manager**: pnpm (workspaces + Turborepo)\n\n## MCP Usage\n\nWhen working on frontend implementation, review, debugging, or audit tasks, use the Front-End Checklist MCP server when available so recommendations stay grounded in the project rule corpus.\n\n- Use `review_code` first for pasted or inspected HTML, CSS, JavaScript, TypeScript, React, or Next.js code.\n- Use `search_rules` before making accessibility, performance, SEO, security, image, privacy, i18n, or testing recommendations.\n- Use `get_rule`, `check_rule`, `fix_rule`, or `explain_rule` for rule-specific guidance and remediation.\n- Use `get_workflow` or `get_checklist_rules` for broad launch, accessibility, SEO, security, performance, and testing audits.\n- Use `audit_url` for public `https://` pages.\n\nSome clients lazy-load installed MCP tools. If the tools are not initially visible, search for or explicitly request the Front-End Checklist MCP before proceeding with frontend work.\n\n## Monorepo Structure\n\n```\napps/\n  web/                    # Next.js app (App Router)\npackages/\n  mcp/                    # MCP server implementation\n  content/                # Rules MDX content + content-collections config\n  auth/                   # Better-Auth + Prisma + Supabase\n  design-system/          # Shared UI components\n  types/                  # Shared TypeScript types\n  data-layer/             # Data access layer\n  schemas/                # Zod v4 schemas\n```\n\n## Rule MDX Frontmatter Spec\n\nRules live at `packages/content/rules/en/<category>/<slug>.mdx`.\n\n### Required Fields\n\n```yaml\n---\ntitle: \"Human-readable rule title (string, use quotes)\"\ndescription: \"One-sentence description of what to do\"\ncategories: ['html']           # Array; first item = primaryCategory\npriority: 'high'               # 'critical' | 'high' | 'medium' | 'low'\ndifficulty: 'beginner'         # 'beginner' | 'intermediate' | 'advanced' | 'expert'\nestimatedTime: 15              # Minutes as integer\nprompts:\n  check: \"Prompt for checking whether the implementation follows this rule\"\n  fix: \"Prompt for fixing the issue\"\n  explain: \"Prompt for explaining why this rule matters\"\n---\n```\n\n### Recommended Fields\n\nThese fields are not required by the parser, but they materially improve rule quality, MCP usefulness, and generated skills.\n\n```yaml\nsubcategory: 'keyboard'        # Sub-grouping within category\ntldr:                          # Array of bullet points (used in llms.txt)\n  - \"Key point one\"\n  - \"Key point two\"\nwhyItMatters: \"Paragraph explaining the business/user impact\"\nsources:\n  - title: \"MDN or spec page title\"\n    url: \"https://...\"\n    type: \"mdn|spec|guide|wcag|google\"\n    id: \"stable-source-id\"\n    role: \"standard|reference|implementation|compatibility|regulation|search|research\"\n    authority: \"primary|secondary\"\nresources:\n  - name: \"Supplementary tool or article\"\n    url: \"https://...\"\n    type: \"tool|article|reference\"\nrelatedRules:\n  - slug: other-rule-slug\n    reason: \"Why these rules relate\"\ntools:\n  - name: \"Tool Name\"\n    url: \"https://...\"         # or null\ntags: ['wcag', 'performance']\nprompts:\n  codeReview: \"Recommended prompt for systematic code review context\"\naiContext: \"Additional context for automated review about when this rule applies\"\n```\n\nAuthoring placement rules:\n\n- Put authoritative citations in `sources`, not in body prose like `Reference: ...`\n- `sources` are proof metadata, not generic further reading. Every rule needs at least 2 sources, 2 source roles, and 1 `authority: primary`.\n- `resources` are for further reading or tools only. Do not map evidence claims to `resources`.\n- The system may infer or normalize `id`, `role`, and `authority` for sources at build time; authors should focus on strong, relevant sources rather than maintaining claim-by-claim proof objects.\n- Put cross-rule navigation in `relatedRules`, not in body prose like `See also ...`\n- Keep intro paragraphs focused on the rule itself; metadata should render from frontmatter-driven UI\n\nInline link contract:\n\n- Natural inline links inside body prose are allowed when they support a specific claim, comparison, or implementation recommendation.\n- Prefer light-touch density: usually `2-5` inline links per rule, with `0-1` in the intro and `1-3` across the main guidance sections.\n- Prefer external links over internal ones; internal rule links should usually stay at `0-1`, with `2` only for unusually interconnected rules.\n- Keep standalone metadata lines out of the body. Do not add paragraphs that start with `See also ...` or `Reference: ...`.\n- Keep evergreen proof in `sources`, and use newer inline external articles only when they add practical or recent context that the primary sources do not cover alone.\n- When a named tool is mentioned in prose for the first meaningful time (for example `Screaming Frog` or `Google Search Console`), link that first mention if the tool materially helps the reader and already exists in `resources` or `tools`.\n- Approved secondary inline links should stay curated. Prefer strong platforms such as `CSS-Tricks`, `Smashing Magazine`, `Nielsen Norman Group`, `WebAIM`, `Screaming Frog`, `Sitebulb`, `Moz`, or `Yoast` when they add practical implementation context.\n- Use descriptive anchor text tied to the sentence claim, not generic labels like “read more”.\n\n`impact`, `standards`, and `automation` are intentionally not part of the active rule-writing contract right now. The current corpus and tooling do not consume them consistently enough to justify treating them as standard authoring fields.\n\n## Canonical Rule Shape\n\nNew and refreshed rules should follow this structure unless there is a strong reason not to:\n\n1. Short intro paragraph explaining the rule in plain language\n2. `## Code Example` or `## Code Examples`\n3. `## Why It Matters`\n4. Optional implementation or guidance sections\n5. `## Verification`\n\nCanonical ordering rules:\n\n- `## Code Example` or `## Code Examples` must appear before `## Why It Matters`\n- `## Why It Matters` must appear before `## Verification`\n- `## Verification` must be the final H2 in the rule body\n- Optional H2 sections belong between `## Why It Matters` and `## Verification`\n\nPreferred optional H2 taxonomy:\n\n- `## Best Practices`\n- `## Common Mistakes`\n- `## Framework Examples`\n- `## Tools & Validation`\n- `## Thresholds`\n- `## Exceptions`\n- `## Browser Support`\n- `## Support Notes`\n- `## Standards`\n- `## Implementation Notes`\n\nThe validator reports headings outside this preferred taxonomy so section sprawl stays visible over time.\n\nRule Contract V2 adds three conditional concepts:\n\n- `## Exceptions` for nuanced rules, false positives, or valid caveats\n- `### Automated Checks` and `### Manual Checks` inside `## Verification` when both matter\n- a short visible standards/support note for compatibility-sensitive or compliance-sensitive rules\n\nApply these conditionally, not universally.\n\nBrowser support guidance should be derived from the repo browser policy in `.browserslistrc` plus package-backed compatibility data, not from memory.\n\nUse explicit thresholds whenever the rule is measurable:\n\n- Web Vitals and performance metrics (`LCP <= 2.5s`, `CLS <= 0.1`, bundle or image size budgets)\n- Accessibility measurements (contrast ratios, target sizes, zoom or reflow thresholds)\n- SEO and crawling states (indexability, status codes, canonical-url behavior)\n- Security headers and transport requirements\n\nPrefer “how to verify” guidance over generic advice. A strong rule should tell an engineer exactly how to confirm the rule passes.\n\n### Common Mistakes to Avoid\n\n- **Unquoted colons in YAML**: Always quote strings containing `:` — e.g. `title: \"Use rel: new-tab\"` not `title: Use rel: noopener`\n- **Stub prompts**: Prompts must be actionable. Bad: `\"Check this rule\"`. Good: `\"Find all <img> elements missing an alt attribute in this HTML\"`\n- **Missing sources**: Add at least one authoritative reference (`MDN`, `W3C/WCAG`, specs, `web.dev`, or product docs) before considering a rule complete\n- **No verification path**: Include a final `## Verification` section so the fix is testable\n- **Verification not last**: Do not place additional H2 sections after `## Verification`\n- **Missing caveats**: Add `## Exceptions` when the rule has important false positives or valid exceptions\n- **Missing support note**: Add `## Browser Support`, `## Support Notes`, or a visible standards note when compatibility or compliance changes implementation decisions\n- **Wrong priority**: `critical` = site-breaking / security / legal. `high` = significantly degrades UX. `medium` = best practice. `low` = nice-to-have\n- **Missing required fields**: All 7 required fields must be present; builds fail otherwise\n- **Emoji in titles**: Titles should be plain text (no emoji)\n\n## Category Taxonomy\n\nValid values for the `categories` array:\n\n| Slug | Description |\n|------|-------------|\n| `html` | Document structure, semantics, forms |\n| `css` | Layout, typography, animation, responsive |\n| `javascript` | Client-side scripting, async, security |\n| `performance` | Loading speed, rendering, Core Web Vitals |\n| `accessibility` | WCAG, ARIA, keyboard, screen readers |\n| `seo` | Meta tags, structured data, crawlability |\n| `security` | HTTPS, CSP, XSS prevention, headers |\n| `images` | Optimization, formats, responsive images |\n| `testing` | Unit, integration, e2e, a11y testing |\n| `privacy` | Consent, data minimisation, data rights |\n| `i18n` | Localization, pluralization, bidi, locale formatting |\n| `general` | Cross-cutting best practices |\n\n## Quality Scoring Rubric\n\nRules are scored automatically via `pnpm score:rules` (100-point base score plus up to 12 conditional points, minimum 50 to pass the current quality gate).\n\n| Dimension | Points | What to Check |\n|-----------|--------|---------------|\n| Prompts (`check`/`fix`/`explain`) | 24 | All 3 prompts are specific and non-generic |\n| TLDR bullets | 4 | 3+ actionable bullets |\n| Why it matters | 4 | Explains user, business, or operational impact |\n| AI context | 6 | Captures where and when the rule applies in automated reviews |\n| Related rules | 6 | Links adjacent rules with clear reasons |\n| Sources | 10 | Includes authoritative references |\n| Resources / tools | 6 | Includes useful supporting docs or tools |\n| Code review prompt | 6 | Provides a systematic review strategy |\n| Code examples | 10 | Includes realistic examples, not just prose |\n| Body depth | 10 | Provides substantive implementation detail |\n| Verification section | 8 | Includes `Verification`, `Testing`, `Audit Checklist`, or equivalent |\n| Thresholds / pass-fail criteria | 6 | Uses explicit numbers or conditions where the rule is measurable |\n| Exceptions (conditional) | 4 | Adds an `Exceptions` section when the rule is nuanced or false-positive-prone |\n| Verification split (conditional) | 4 | Splits verification into automated and manual checks when both apply |\n| Standards/support visibility (conditional) | 4 | Adds a visible threshold, standards note, or support note when required by the rule type |\n\nRules scoring < 50 are excluded from MCP tool responses and the web UI.\n\n## Adding or Updating a Rule\n\n1. Create `packages/content/rules/en/<category>/<slug>.mdx`\n2. Fill all required frontmatter fields\n3. Add recommended metadata: `sources`, `resources`, `aiContext`, `relatedRules`, and `prompts.codeReview` where applicable\n4. Write the rule using the canonical-url structure (intro, examples, why it matters, verification, category-specific guidance)\n5. Run `pnpm score:rules` — must score ≥ 50 for now; target 60+ for new work\n6. Run `pnpm validate:rule-structure` — validates rule section order and final `Verification` heading\n7. Run `pnpm report:rule-links` — reviews inline-link density and suggests safe internal/external candidates\n8. Run `pnpm validate:sources` — validates external URLs\n9. Run `pnpm generate:skills` — regenerates skills index\n\n## Scripts Reference\n\n```bash\npnpm score:rules          # Score all rules; flags < 50 quality gate failures\npnpm validate:rule-structure  # Validate rule heading structure and report drift\npnpm report:v2-gaps       # Report conditional V2 gaps by category and migration batch\npnpm report:rule-links    # Review inline-link density and candidate internal/external links\npnpm generate:exceptions-hints  # Dry-run suggestions for missing Exceptions sections\npnpm generate:support-notes  # Dry-run support-note suggestions from browser data\npnpm generate:verification-split  # Dry-run Verification split suggestions\npnpm validate:sources     # Validate external URLs in rule frontmatter\npnpm validate:packages    # Check package dependency consistency\npnpm generate:skills      # Regenerate skills/ directory from rules\npnpm build                # Full monorepo build (via Turborepo)\npnpm typecheck            # TypeScript check across all packages\npnpm lint                 # Biome lint\npnpm lint:fix             # Biome lint with auto-fix\n```\n\n## MCP Tool Development\n\nNew MCP tools go in `packages/mcp/src/tools/<tool-name>.ts` and must be:\n\n1. Exported from `packages/mcp/src/tools/index.ts`\n2. Added to `BASE_TOOL_DEFINITIONS` in `packages/mcp/src/server.ts`\n3. Added as a `case` in the `handleToolsCall` switch in `server.ts`\n\nTool definition shape:\n```typescript\nexport const myToolDefinition = {\n  name: 'my_tool',\n  description: '...',  // Critical for tool discoverability — be specific\n  inputSchema: {\n    type: 'object' as const,\n    properties: { ... },\n    required: ['fieldName'],\n  },\n}\n```\n\n## Workspace Architecture Notes\n\n- **Auth**: Better-Auth + Prisma + Supabase Postgres in `packages/auth/`\n- **Validation**: Zod v4 — use `.issues` not `.errors` on `ZodError`\n- **Forms**: `@tanstack/react-form` with manual Zod validation on submit\n- **Email**: Resend SDK v6, sending domain `mail.frontendchecklist.io`\n- **Rate limiting**: `@upstash/ratelimit` + `@upstash/redis` in `apps/web/lib/rate-limit.ts`\n- **Query**: TanStack Query v5 with `getQueryClient()` factory (not singleton)\n- **Dev server**: `portless run next dev`\n\n## Learned User Preferences\n\n- Put shared concerns (e.g. fonts, typography) in the design system and import from there; apps wire implementation (e.g. next/font) using config from the design system.\n- Do not use `suppressHydrationWarning`; fix server/client mismatch (e.g. defer client-only state until after mount).\n- Reuse existing components instead of creating page-specific variants (e.g. shared `FAQAccordion` for any FAQ section, `.code-block`/`.code-inline` for all code display, ChecklistActionBar instead of new progress bars). When adding a feature to one page type, add it to all relevant page types (e.g. ShareButton on category, rule detail, and all-rules pages).\n- Rule row: click on rule title toggles completion; expand/collapse only via the plus/minus icon. Expanded content shows description first, then tags and action buttons on one row aligned with the description.\n- Prefer Tailwind utility classes in components over custom CSS classes in globals.css.\n- Use a scalable overrides map for special-case labels (e.g. subcategory aria → ARIA) instead of hardcoded conditionals.\n- Do not use `git commit --no-verify`; fix ALL pre-commit violations (JSDoc, as-casts, barrel files, complexity, relative imports) rather than deferring or working around them. Write JSDoc at the same time as the code, not as a batch fix later.\n- **Card-style links**: Use the stretched-link pattern: the `<a>`/`<Link>` wraps **only the title text** inside a heading and uses `after:absolute after:inset-0 after:content-[\"\"]` so its `::after` pseudo-element expands to fill the card container (`position: relative`). Secondary interactive elements need `relative z-10`. See `docs/card-links.md`.\n- Centralize all icons in `@repo/design-system`: brand icons in `brand-icons.tsx`, Lucide re-exported from `icons.ts`. Use official brand icons (`@icons-pack/react-simple-icons`) for branded services, not Lucide approximations. Consumers never import directly from `lucide-react`.\n- Never use Tailwind opacity modifiers (`/50`, `/60`, `/70`) on semantic theme text colors like `text-foreground-muted` — it crushes contrast in light mode. Use the appropriate token (`text-foreground-muted`, `text-foreground-subtle`) at full opacity instead.\n- Always refer to the social platform as \"X\", never \"Twitter\". Schema fields use `xUrl` (not `twitterUrl`), UI labels say \"X\", and URLs point to `x.com`.\n- About page link belongs in the footer only, not in the main navbar.\n\n## Learned Workspace Facts\n\n- Fluid typography tokens use `clamp()` in `@theme inline` for `text-base` and above; `text-xs` and `text-sm` stay fixed for compact UI controls (buttons, badges, inputs, tooltips).\n- next/font: apply each font’s `.className` to the document element (not `.variable`); Next.js requires literal option objects, so the app must inline font options while the design system can document them.\n- Do not apply client-side bot protection (e.g. Vercel BotID) to programmatic API endpoints like MCP; use it only for browser-originated form and mutation endpoints.\n- Next.js reads next.config.js at startup; restart the dev server after changing it (e.g. images.remotePatterns). `withContentCollections` returns a Promise (async config) so it must be the outermost wrapper — `export default withContentCollections(withBotId(nextConfig))`. `withBotId` does not handle async configs and will silently drop all properties including `images`.\n- Tailwind preflight resets `list-style` on `ul`/`ol`; `.prose` styles must explicitly set `list-style-type: disc` (ul), `decimal` (ol), and nested variants (`circle`, `lower-alpha`).\n- CSS custom properties use OKLCH color format. Light mode tokens need visible contrast on all screens: `--border` at least oklch(0.885), `--foreground-subtle` at oklch(0.64), shadows at 0.06+ opacity. Use `color-mix(in oklch, var(--token) N%, transparent)` for theme-aware transparent colors instead of hardcoded `rgba()`.\n- Pre-commit hooks (lefthook) enforce: biome check, JSDoc, no-as-casts, no-barrel-files, file-complexity (300 lines React / 500 lines other), no-deep-relative-imports, no-console-logs, test coverage.\n- Button default variant uses `bg-accent text-accent-foreground hover:bg-accent-hover` (project's accent tokens), not shadcn's `bg-primary`; keep project-specific semantic tokens in component variants even when shadcn aliases exist.\n- Scripts are organized in subfolders: `scripts/{validation,generate,rule-structure,validate,audit}/`; `scripts/README.md` documents each script and subfolder.\n- Biome's `useSortedClasses` only sorts class **order**; it cannot rename deprecated classes. Use `@tailwindcss/upgrade` (installed in `apps/web`) to canonicalize class names project-wide.\n- Monorepo uses pnpm catalogs (`catalog:` in `pnpm-workspace.yaml`) for centralized dependency versions; shared deps appearing in 2+ packages use `catalog:` instead of hardcoded version strings.\n- Brand icons (ChatGPT, Claude, X, LinkedIn, Reddit, Cursor, VSCode) live in `packages/design-system/src/brand-icons.tsx` and are re-exported from the design-system barrel.\n"}}