fe-inspector-mcp 0.1.0 → 0.3.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

@@ -2,9 +2,14 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { createRequire } from 'module';
 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';
+// 从 package.json 动态读取版本号
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+const { version, name } = { version: pkg.version, name: pkg.name };
 const server = new Server({ name, version }, { capabilities: { tools: {} } });
 // ── Tool definitions ──
 server.setRequestHandler(ListToolsRequestSchema, async () => {
@@ -70,6 +75,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 +143,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/dist/inspector/a11y.js

@@ -1,4 +1,5 @@
-import { load } from 'cheerio';
+import { parseHtml } from '../utils/parser.js';
+import { buildSelector } from '../utils/dom.js';
 const category = 'a11y';
 const rules = [
     {
@@ -118,16 +119,8 @@ const rules = [
         },
     },
 ];
-function buildSelector($el) {
-    const tag = typeof $el.prop === 'function' ? ($el.prop('tagName')?.toLowerCase() || 'div') : 'div';
-    const id = $el.attr?.('id');
-    if (id)
-        return `#${id}`;
-    const cls = ($el.attr?.('class') || '').split(/\s+/).filter(Boolean).slice(0, 2).join('.');
-    return cls ? `${tag}.${cls}` : tag;
-}
 export function inspectA11y(html) {
-    const $ = load(html);
+    const $ = parseHtml(html);
     const results = [];
     for (const rule of rules) {
         results.push(...rule.check($));

package/dist/inspector/aesthetic.js

@@ -1,4 +1,5 @@
-import { load } from 'cheerio';
+import { parseHtml } from '../utils/parser.js';
+import { buildSelector } from '../utils/dom.js';
 const category = 'aesthetic';
 const rules = [
     {
@@ -122,16 +123,8 @@ const rules = [
         },
     },
 ];
-function buildSelector($el) {
-    const tag = typeof $el.prop === 'function' ? ($el.prop('tagName')?.toLowerCase() || 'div') : 'div';
-    const id = $el.attr?.('id');
-    if (id)
-        return `#${id}`;
-    const cls = ($el.attr?.('class') || '').split(/\s+/).filter(Boolean).slice(0, 2).join('.');
-    return cls ? `${tag}.${cls}` : tag;
-}
 export function inspectAesthetic(html) {
-    const $ = load(html);
+    const $ = parseHtml(html);
     const results = [];
     for (const rule of rules) {
         results.push(...rule.check($));

package/dist/inspector/index.js

@@ -1,7 +1,9 @@
+import { parseHtml } from '../utils/parser.js';
 import { inspectAesthetic, aestheticMeta } from './aesthetic.js';
 import { inspectA11y, a11yMeta } from './a11y.js';
 import { inspectResponsive, responsiveMeta } from './responsive.js';
 import { inspectInteraction, interactionMeta } from './interaction.js';
+import { inspectPerformance, performanceMeta } from './performance.js';
 const inspectors = {
     aesthetic: {
         ...aestheticMeta,
@@ -19,10 +21,16 @@ const inspectors = {
         ...interactionMeta,
         inspect: inspectInteraction,
     },
+    performance: {
+        ...performanceMeta,
+        inspect: inspectPerformance,
+    },
 };
 export function runInspection(input) {
     const { html, url } = input;
     const categories = input.categories || Object.keys(inspectors);
+    // 使用缓存解析 HTML，避免重复解析
+    const $ = parseHtml(html);
     const categoryResults = {};
     let total = 0;
     let passed = 0;

package/dist/inspector/interaction.js

@@ -1,4 +1,5 @@
-import { load } from 'cheerio';
+import { parseHtml } from '../utils/parser.js';
+import { buildSelector } from '../utils/dom.js';
 const category = 'interaction';
 const rules = [
     {
@@ -117,16 +118,8 @@ const rules = [
         },
     },
 ];
-function buildSelector($el) {
-    const tag = typeof $el.prop === 'function' ? ($el.prop('tagName')?.toLowerCase() || 'div') : 'div';
-    const id = $el.attr?.('id');
-    if (id)
-        return `#${id}`;
-    const cls = ($el.attr?.('class') || '').split(/\s+/).filter(Boolean).slice(0, 2).join('.');
-    return cls ? `${tag}.${cls}` : tag;
-}
 export function inspectInteraction(html) {
-    const $ = load(html);
+    const $ = parseHtml(html);
     const results = [];
     for (const rule of rules) {
         results.push(...rule.check($));

package/dist/inspector/performance.d.ts

@@ -0,0 +1,8 @@
+import type { Detection } from '../types.js';
+export declare function inspectPerformance(html: string): Detection[];
+export declare const performanceMeta: {
+    category: "performance";
+    label: string;
+    description: string;
+    ruleCount: number;
+};

package/dist/inspector/performance.js

@@ -0,0 +1,157 @@
+import { parseHtml } from '../utils/parser.js';
+import { buildSelector } from '../utils/dom.js';
+const category = 'performance';
+const rules = [
+    {
+        id: 'pf-001',
+        title: 'Large image without width/height',
+        check: ($) => {
+            const results = [];
+            $('img').each((_i, el) => {
+                const width = $(el).attr('width');
+                const height = $(el).attr('height');
+                if (!width && !height) {
+                    results.push({
+                        ruleId: 'pf-001',
+                        severity: 'warning',
+                        title: 'Image missing dimensions',
+                        message: 'Image has no width/height attributes — causes layout shift (CLS).',
+                        element: buildSelector($(el)),
+                        recommendation: 'Add explicit width and height attributes to prevent Cumulative Layout Shift.',
+                    });
+                }
+            });
+            return results;
+        },
+    },
+    {
+        id: 'pf-002',
+        title: 'Render-blocking external CSS/JS in <head>',
+        check: ($) => {
+            const results = [];
+            // Check for render-blocking stylesheets
+            $('head link[rel="stylesheet"]').each((_i, el) => {
+                const href = $(el).attr('href');
+                const media = $(el).attr('media');
+                if (href && !media) {
+                    results.push({
+                        ruleId: 'pf-002',
+                        severity: 'warning',
+                        title: 'Render-blocking stylesheet',
+                        message: `Stylesheet ${href} blocks rendering.`,
+                        element: buildSelector($(el)),
+                        recommendation: 'Use media="print" for non-critical CSS, or load asynchronously.',
+                    });
+                }
+            });
+            // Check for render-blocking scripts
+            $('head script[src]').each((_i, el) => {
+                const defer = $(el).attr('defer');
+                const async = $(el).attr('async');
+                if (!defer && !async) {
+                    results.push({
+                        ruleId: 'pf-002',
+                        severity: 'warning',
+                        title: 'Render-blocking script',
+                        message: 'Script in <head> without defer/async blocks rendering.',
+                        element: buildSelector($(el)),
+                        recommendation: 'Add defer or async attribute to non-critical scripts.',
+                    });
+                }
+            });
+            return results;
+        },
+    },
+    {
+        id: 'pf-003',
+        title: 'Image not optimized (no loading=lazy below fold)',
+        check: ($) => {
+            const results = [];
+            const images = $('img').toArray();
+            // Skip first 2 images (likely above fold)
+            images.slice(2).forEach((el, index) => {
+                const loading = $(el).attr('loading');
+                if (!loading || loading !== 'lazy') {
+                    results.push({
+                        ruleId: 'pf-003',
+                        severity: 'info',
+                        title: 'Below-fold image missing lazy loading',
+                        message: `Image #${index + 3} should use loading="lazy".`,
+                        element: buildSelector($(el)),
+                        recommendation: 'Add loading="lazy" to images below the fold for faster initial load.',
+                    });
+                }
+            });
+            return results;
+        },
+    },
+    {
+        id: 'pf-004',
+        title: 'Too many HTTP requests (css/js/img count)',
+        check: ($) => {
+            const results = [];
+            const cssCount = $('link[href][rel="stylesheet"]').length;
+            const jsCount = $('script[src]').length;
+            const imgCount = $('img[src]').length;
+            const total = cssCount + jsCount + imgCount;
+            if (total > 30) {
+                results.push({
+                    ruleId: 'pf-004',
+                    severity: 'info',
+                    title: 'Too many HTTP requests',
+                    message: `Found ${total} external resources (${cssCount} CSS, ${jsCount} JS, ${imgCount} images).`,
+                    element: 'head',
+                    recommendation: 'Bundle CSS/JS files and use image sprites or lazy loading to reduce requests.',
+                });
+            }
+            return results;
+        },
+    },
+    {
+        id: 'pf-005',
+        title: 'DOM depth too deep (> 15 levels)',
+        check: ($) => {
+            const results = [];
+            function getMaxDepth(el, currentDepth) {
+                let maxDepth = currentDepth;
+                const children = $(el).children().toArray();
+                for (const child of children) {
+                    const childDepth = getMaxDepth(child, currentDepth + 1);
+                    if (childDepth > maxDepth) {
+                        maxDepth = childDepth;
+                    }
+                }
+                return maxDepth;
+            }
+            const body = $('body').get(0);
+            if (body) {
+                const depth = getMaxDepth(body, 0);
+                if (depth > 15) {
+                    results.push({
+                        ruleId: 'pf-005',
+                        severity: 'info',
+                        title: 'DOM depth too deep',
+                        message: `DOM nesting depth is ${depth} levels (max recommended: 15).`,
+                        element: 'body',
+                        recommendation: 'Flatten HTML structure — deep nesting slows rendering and hurts maintainability.',
+                    });
+                }
+            }
+            return results;
+        },
+    },
+];
+export function inspectPerformance(html) {
+    const $ = parseHtml(html);
+    const results = [];
+    for (const rule of rules) {
+        results.push(...rule.check($));
+    }
+    return results;
+}
+export const performanceMeta = {
+    category,
+    label: 'Performance',
+    description: 'Page speed — image optimization, render blocking, DOM depth, HTTP requests',
+    ruleCount: rules.length,
+};

package/dist/inspector/responsive.js

@@ -1,4 +1,5 @@
-import { load } from 'cheerio';
+import { parseHtml } from '../utils/parser.js';
+import { buildSelector } from '../utils/dom.js';
 const category = 'responsive';
 const rules = [
     {
@@ -125,16 +126,8 @@ const rules = [
         },
     },
 ];
-function buildSelector($el) {
-    const tag = typeof $el.prop === 'function' ? ($el.prop('tagName')?.toLowerCase() || 'div') : 'div';
-    const id = $el.attr?.('id');
-    if (id)
-        return `#${id}`;
-    const cls = ($el.attr?.('class') || '').split(/\s+/).filter(Boolean).slice(0, 2).join('.');
-    return cls ? `${tag}.${cls}` : tag;
-}
 export function inspectResponsive(html) {
-    const $ = load(html);
+    const $ = parseHtml(html);
     const results = [];
     for (const rule of rules) {
         results.push(...rule.check($));

package/dist/types.d.ts

@@ -1,4 +1,7 @@
 export type Severity = 'error' | 'warning' | 'info';
+export type CheerioElement = any;
+export type CheerioSelection = any;
+export type CheerioAPI = any;
 export interface Detection {
     ruleId: string;
     severity: Severity;
@@ -7,7 +10,7 @@ export interface Detection {
     element?: string;
     recommendation: string;
 }
-export type InspectCategory = 'aesthetic' | 'a11y' | 'responsive' | 'interaction';
+export type InspectCategory = 'aesthetic' | 'a11y' | 'responsive' | 'interaction' | 'performance';
 export interface InspectReport {
     url?: string;
     totalElements: number;

package/dist/utils/dom.d.ts

@@ -0,0 +1,7 @@
+import type { CheerioSelection } from '../types.js';
+/**
+ * 构建元素的 CSS 选择器
+ * @param $el Cheerio 元素对象
+ * @returns CSS 选择器字符串
+ */
+export declare function buildSelector($el: CheerioSelection): string;

package/dist/utils/dom.js

@@ -0,0 +1,13 @@
+/**
+ * 构建元素的 CSS 选择器
+ * @param $el Cheerio 元素对象
+ * @returns CSS 选择器字符串
+ */
+export function buildSelector($el) {
+    const tag = typeof $el.prop === 'function' ? ($el.prop('tagName')?.toLowerCase() || 'div') : 'div';
+    const id = $el.attr?.('id');
+    if (id)
+        return `#${id}`;
+    const cls = ($el.attr?.('class') || '').split(/\s+/).filter(Boolean).slice(0, 2).join('.');
+    return cls ? `${tag}.${cls}` : tag;
+}

package/dist/utils/parser.d.ts

@@ -0,0 +1,31 @@
+/**
+ * HTML 解析缓存
+ * 避免同一个 HTML 字符串被多次解析
+ */
+declare class ParserCache {
+    private cache;
+    private maxSize;
+    constructor(maxSize?: number);
+    /**
+     * 获取解析后的 Cheerio 实例
+     * @param html HTML 字符串
+     * @returns CheerioAPI 实例
+     */
+    parse(html: string): any;
+    /**
+     * 清空缓存
+     */
+    clear(): void;
+    /**
+     * 获取缓存大小
+     */
+    get size(): number;
+}
+export declare const parserCache: ParserCache;
+/**
+ * 解析 HTML 并缓存结果
+ * @param html HTML 字符串
+ * @returns CheerioAPI 实例
+ */
+export declare function parseHtml(html: string): any;
+export {};

package/dist/utils/parser.js

@@ -0,0 +1,56 @@
+// ── HTML 解析缓存模块 ──
+import { load } from 'cheerio';
+/**
+ * HTML 解析缓存
+ * 避免同一个 HTML 字符串被多次解析
+ */
+class ParserCache {
+    cache = new Map();
+    maxSize;
+    constructor(maxSize = 10) {
+        this.maxSize = maxSize;
+    }
+    /**
+     * 获取解析后的 Cheerio 实例
+     * @param html HTML 字符串
+     * @returns CheerioAPI 实例
+     */
+    parse(html) {
+        const cached = this.cache.get(html);
+        if (cached) {
+            return cached;
+        }
+        // 如果缓存已满，删除最旧的条目
+        if (this.cache.size >= this.maxSize) {
+            const firstKey = this.cache.keys().next().value;
+            if (firstKey !== undefined) {
+                this.cache.delete(firstKey);
+            }
+        }
+        const $ = load(html);
+        this.cache.set(html, $);
+        return $;
+    }
+    /**
+     * 清空缓存
+     */
+    clear() {
+        this.cache.clear();
+    }
+    /**
+     * 获取缓存大小
+     */
+    get size() {
+        return this.cache.size;
+    }
+}
+// 导出全局缓存实例
+export const parserCache = new ParserCache();
+/**
+ * 解析 HTML 并缓存结果
+ * @param html HTML 字符串
+ * @returns CheerioAPI 实例
+ */
+export function parseHtml(html) {
+    return parserCache.parse(html);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fe-inspector-mcp",
-  "version": "0.1.0",
+  "version": "0.3.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": {
@@ -15,6 +15,9 @@
     "build": "tsc",
     "start": "node dist/index.js",
     "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -38,6 +41,7 @@
     "@types/cheerio": "^0.22.35",
     "@types/node": "^22.20.1",
     "tsx": "^4.19.0",
-    "typescript": "^5.7.0"
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.10"
   }
 }

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.