fe-inspector-mcp 0.1.0 → 0.2.0

package/README.md

@@ -159,6 +159,40 @@ Same as `inspect_html` but returns structured Markdown fix suggestions that codi
 
 List available categories and rule counts.
 
+### `review_design` ✨ (hallmark can't do this)
+
+**Pre-build design review.** Describe what you're about to build, and get a checklist of common frontend pitfalls BEFORE writing code.
+
+**Parameters:**
+- `description` (required): Describe the UI you're planning (e.g. "a login form with email and password, a navbar with dropdown menus, a pricing card grid")
+
+**Example:**
+```
+Agent: review_design description="a landing page with hero section, feature cards, testimonial carousel, and footer form"
+
+Result:
+[!] [a11y] MUST: Alt text on all images
+   Every <img> needs alt. Decorative images get alt="".
+
+[!] [responsive] MUST: Viewport meta tag
+   Every page needs <meta name="viewport">.
+
+[~] [responsive] SHOULD: Responsive grid breakpoints
+   Use grid-template-columns with auto-fit/auto-fill or add @media breakpoints.
+
+[~] [interaction] SHOULD: Loading states
+   Show skeleton screens or spinners during data fetch.
+
+[~] [semantic] SHOULD: Semantic HTML structure
+   Use <header>, <main>, <section> instead of generic <div>s.
+
+---
+
+3 must-fix, 4 should-fix, 7 total points to review.
+```
+
+**Why this matters:** hallmark only checks code after it's written. `review_design` checks your intent before you write a single line — catching issues at the design stage where they're cheapest to fix.
+
 ## Usage with agents
 
 **Claude Code:**

package/dist/design-review.d.ts

@@ -0,0 +1,11 @@
+export interface DesignReviewRequest {
+    description: string;
+}
+export interface DesignPoint {
+    category: 'a11y' | 'responsive' | 'interaction' | 'performance' | 'semantic';
+    severity: 'must' | 'should' | 'consider';
+    point: string;
+    detail: string;
+}
+export declare function reviewDesign(request: DesignReviewRequest): DesignPoint[];
+export declare function formatReview(points: DesignPoint[]): string;

package/dist/design-review.js

@@ -0,0 +1,133 @@
+// ── Pre-build design review
+// hallmark checks code AFTER it's written.
+// This checks BEFORE — given a description, it predicts common pitfalls.
+const designPatterns = [
+    // ── Forms ──
+    {
+        triggers: ['form', 'input', 'signup', 'login', 'register', 'contact', 'search box', 'enter', 'submit'],
+        points: [
+            { category: 'a11y', severity: 'must', point: 'Label every input', detail: 'Use <label for="id"> or aria-label. Placeholder is not a label.' },
+            { category: 'interaction', severity: 'must', point: 'Show validation inline', detail: 'Don\'t rely on alert() for errors. Show messages next to the field.' },
+            { category: 'a11y', severity: 'must', point: 'Error messages need aria-live', detail: 'Use aria-live="polite" so screen readers announce errors.' },
+            { category: 'responsive', severity: 'should', point: 'Inputs fill width on mobile', detail: 'Use width: 100% on small screens so inputs aren\'t tiny.' },
+            { category: 'interaction', severity: 'should', point: 'Disable submit while loading', detail: 'Prevent double-submission with disabled state + spinner.' },
+        ],
+    },
+    // ── Navigation / menus ──
+    {
+        triggers: ['nav', 'menu', 'sidebar', 'header', 'navigation', 'navbar', 'tabs', 'breadcrumb'],
+        points: [
+            { category: 'a11y', severity: 'must', point: 'Add skip-to-content link', detail: 'First focusable element should be "Skip to main content".' },
+            { category: 'a11y', severity: 'must', point: 'Keyboard navigation for menus', detail: 'Use arrow keys for submenu navigation. Escape closes.' },
+            { category: 'a11y', severity: 'should', point: 'Current page indicator', detail: 'Mark current page with aria-current="page" on the active link.' },
+            { category: 'responsive', severity: 'must', point: 'Mobile hamburger menu', detail: 'On screens < 768px, collapse nav into a toggleable menu.' },
+            { category: 'interaction', severity: 'should', point: 'Click outside closes menu', detail: 'Clicking outside an open dropdown/modal should close it.' },
+        ],
+    },
+    // ── Cards / grids / lists ──
+    {
+        triggers: ['card', 'grid', 'list', 'feed', 'gallery', 'features', 'pricing', 'showcase'],
+        points: [
+            { category: 'responsive', severity: 'must', point: 'Responsive grid breakpoints', detail: 'Use grid-template-columns with auto-fit/auto-fill or add @media breakpoints for mobile.' },
+            { category: 'interaction', severity: 'should', point: 'Clickable cards need visual feedback', detail: 'Add :hover transform/scale and :focus outline to card interactions.' },
+            { category: 'a11y', severity: 'should', point: 'Card text contrast', detail: 'Ensure text on colored card backgrounds meets WCAG AA (4.5:1).' },
+            { category: 'performance', severity: 'consider', point: 'Lazy-load images', detail: 'Use loading="lazy" on images below the fold.' },
+        ],
+    },
+    // ── Tables / data ──
+    {
+        triggers: ['table', 'data', 'spreadsheet', 'grid', 'report', 'chart'],
+        points: [
+            { category: 'semantic', severity: 'must', point: 'Use <th> for headers', detail: 'Header cells must use <th> with scope="col" or scope="row".' },
+            { category: 'a11y', severity: 'must', point: 'Add <caption> or aria-label', detail: 'Tables need a caption or aria-label describing their purpose.' },
+            { category: 'responsive', severity: 'must', point: 'Horizontally scrollable on mobile', detail: 'Wrap wide tables in overflow-x: auto container.' },
+            { category: 'interaction', severity: 'should', point: 'Row hover highlight', detail: 'Add :hover background to table rows for readability.' },
+        ],
+    },
+    // ── Modals / dialogs ──
+    {
+        triggers: ['modal', 'dialog', 'popup', 'overlay', 'lightbox', 'drawer'],
+        points: [
+            { category: 'a11y', severity: 'must', point: 'Trap focus inside modal', detail: 'When modal is open, Tab should cycle within it, not behind it.' },
+            { category: 'a11y', severity: 'must', point: 'Escape key closes modal', detail: 'Add keydown listener for Escape to close.' },
+            { category: 'interaction', severity: 'must', point: 'Backdrop click behavior', detail: 'Clicking the overlay should either close the modal or be clearly NOT clickable.' },
+            { category: 'a11y', severity: 'must', point: 'Restore focus on close', detail: 'When modal closes, return focus to the element that opened it.' },
+            { category: 'responsive', severity: 'should', point: 'Modal fits small screens', detail: 'On mobile, use full-screen or near-full-screen modal layout.' },
+        ],
+    },
+    // ── Images / media ──
+    {
+        triggers: ['image', 'photo', 'picture', 'avatar', 'thumbnail', 'carousel', 'slider'],
+        points: [
+            { category: 'a11y', severity: 'must', point: 'Alt text on all images', detail: 'Every <img> needs alt. Decorative images get alt="".' },
+            { category: 'responsive', severity: 'must', point: 'Responsive images', detail: 'Use max-width: 100% or srcset for responsive images.' },
+            { category: 'performance', severity: 'should', point: 'Optimize image loading', detail: 'Use width/height attributes to prevent layout shift.' },
+        ],
+    },
+    // ── Buttons / CTAs ──
+    {
+        triggers: ['button', 'cta', 'action', 'call to action', 'submit', 'click'],
+        points: [
+            { category: 'interaction', severity: 'must', point: 'Cursor pointer on buttons', detail: 'All clickable elements need cursor: pointer.' },
+            { category: 'interaction', severity: 'must', point: 'Hover and focus states', detail: 'Every interactive element needs :hover and :focus visual feedback.' },
+            { category: 'a11y', severity: 'must', point: 'Descriptive button text', detail: '"Click here" is bad. "Submit form" or "Open menu" is good.' },
+            { category: 'responsive', severity: 'should', point: 'Touch-friendly tap targets', detail: 'Minimum 44x44px tap target size for mobile.' },
+        ],
+    },
+    // ── Text content ──
+    {
+        triggers: ['article', 'blog', 'content', 'text', 'paragraph', 'typography', 'reading'],
+        points: [
+            { category: 'a11y', severity: 'must', point: 'Heading hierarchy', detail: 'Use h1 → h2 → h3 in order. Don\'t skip levels.' },
+            { category: 'responsive', severity: 'should', point: 'Readable line length', detail: 'Keep text containers at 60-75 characters max-width for readability.' },
+            { category: 'a11y', severity: 'should', point: 'Font size minimum', detail: 'Body text should be at least 16px to prevent mobile zoom issues.' },
+        ],
+    },
+    // ── Layout / page structure ──
+    {
+        triggers: ['landing', 'page', 'layout', 'homepage', 'dashboard', 'app'],
+        points: [
+            { category: 'responsive', severity: 'must', point: 'Viewport meta tag', detail: 'Every page needs <meta name="viewport" content="width=device-width, initial-scale=1">.' },
+            { category: 'semantic', severity: 'should', point: 'Semantic HTML structure', detail: 'Use <header>, <main>, <nav>, <section>, <article>, <footer> instead of generic <div>s.' },
+            { category: 'a11y', severity: 'should', point: 'Landmark regions', detail: 'Add aria-label to <nav> and <section> elements when multiple exist.' },
+            { category: 'interaction', severity: 'consider', point: 'Loading states', detail: 'Show skeleton screens or spinners during data fetch — don\'t leave users staring at blank space.' },
+        ],
+    },
+];
+export function reviewDesign(request) {
+    const desc = request.description.toLowerCase();
+    const matchedPoints = new Set();
+    const results = [];
+    for (const pattern of designPatterns) {
+        const matches = pattern.triggers.some(t => desc.includes(t));
+        if (matches) {
+            for (const point of pattern.points) {
+                if (!matchedPoints.has(point.point)) {
+                    matchedPoints.add(point.point);
+                    results.push(point);
+                }
+            }
+        }
+    }
+    return results;
+}
+export function formatReview(points) {
+    if (points.length === 0) {
+        return 'No pre-build review points matched. Describe more UI details for better suggestions.';
+    }
+    const lines = [];
+    lines.push('# Design Pre-Review\n');
+    const severityOrder = { must: 0, should: 1, consider: 2 };
+    const sorted = [...points].sort((a, b) => severityOrder[a.severity] - severityOrder[b.severity]);
+    for (const p of sorted) {
+        const icon = p.severity === 'must' ? '[!]' : p.severity === 'should' ? '[~]' : '[i]';
+        const tag = `[${p.category}]`;
+        lines.push(`${icon} ${tag} ${p.severity.toUpperCase()}: ${p.point}`);
+        lines.push(`   ${p.detail}`);
+        lines.push('');
+    }
+    const must = points.filter(p => p.severity === 'must').length;
+    const should = points.filter(p => p.severity === 'should').length;
+    lines.push(`---\n${must} must-fix, ${should} should-fix, ${points.length} total points to review.`);
+    return lines.join('\n');
+}

package/dist/index.js

@@ -4,7 +4,8 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { runInspection, getInspectorMeta } from './inspector/index.js';
 import { generateTextReport, generateJsonReport } from './reporter/index.js';
-const { version, name } = { version: '0.1.0', name: 'fe-inspector-mcp' };
+import { reviewDesign, formatReview } from './design-review.js';
+const { version, name } = { version: '0.2.0', name: 'fe-inspector-mcp' };
 const server = new Server({ name, version }, { capabilities: { tools: {} } });
 // ── Tool definitions ──
 server.setRequestHandler(ListToolsRequestSchema, async () => {
@@ -70,6 +71,20 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     required: ['html'],
                 },
             },
+            {
+                name: 'review_design',
+                description: 'Pre-build design review. Given a description of what you\'re about to build, returns a checklist of common frontend pitfalls to avoid. Use this BEFORE writing code to catch issues early — hallmark only checks after.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        description: {
+                            type: 'string',
+                            description: 'Describe what you\'re about to build (e.g. "a login form with email and password, a navbar with dropdown menus, a pricing card grid")',
+                        },
+                    },
+                    required: ['description'],
+                },
+            },
         ],
     };
 });
@@ -124,6 +139,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 content: [{ type: 'text', text: fixLines.join('\n') }],
             };
         }
+        case 'review_design': {
+            const description = String(args?.description || '');
+            const points = reviewDesign({ description });
+            const output = formatReview(points);
+            return {
+                content: [{ type: 'text', text: output }],
+            };
+        }
         default:
             throw new Error(`Unknown tool: ${toolName}`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fe-inspector-mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "MCP Server for frontend quality inspection — catches aesthetic flaws, a11y issues, responsive breaks, and interaction bugs in AI-generated HTML.",
   "type": "module",
   "bin": {

package/rules/community/README.md

@@ -0,0 +1,46 @@
+# Community Rules
+
+This directory contains community-contributed inspection rules for FE Inspector MCP.
+
+## How to contribute
+
+1. Create a new `.ts` file in this directory following the rule template below
+2. Each file should export a `rules` array and a `meta` object
+3. Submit a PR to the [GitHub repo](https://github.com/Erich956389473/fe-inspector-mcp)
+
+## Rule template
+
+```typescript
+import type { Detection } from '../../src/types.js';
+import { load } from 'cheerio';
+
+export const meta = {
+  category: 'aesthetic',        // aesthetic | a11y | responsive | interaction
+  label: 'Your Rule Category',
+  description: 'Short description',
+};
+
+export const rules = [{
+  id: 'community-001',          // community-NNN format
+  title: 'Your rule title',
+  severity: 'warning',          // error | warning | info
+  check: ($: ReturnType<typeof load>): Detection[] => {
+    const results: Detection[] = [];
+    // Your detection logic here
+    return results;
+  },
+}];
+```
+
+## Guidelines
+
+- Use `community-NNN` rule ID format (NNN = 3-digit number)
+- Each rule must have a clear fix recommendation
+- Test your rule against real HTML before submitting
+- Keep rules focused — one check per rule
+
+## Review process
+
+1. PR received → automated test run
+2. Manual review within 7 days
+3. Approved rules merged into next release

package/skills/fe-inspect.md

@@ -35,9 +35,11 @@ Run fe-inspect on the most recent HTML output and report issues.
 - `inspect_html` — run all checks on HTML, get a full report
 - `inspect_html_fix` — run all checks, get structured fix suggestions the agent can apply
 - `inspect_categories` — list available categories and rule counts
+- `review_design` — **before writing code**, describe what you're building and get a checklist of common pitfalls. hallmark can't do this.
 
 ## Design principles
 
 1. **hallmark covered aesthetic only.** This skill extends to behavior-level checks that hallmark ignores.
 2. **Report is actionable.** Every detection includes a specific fix recommendation.
-3. **Not a style guide.** It detects anti-patterns, not taste choices.
+3. **Pre-check before code.** Use `review_design` before writing any HTML to catch issues at design stage.
+4. **Not a style guide.** It detects anti-patterns, not taste choices.