@vadenai/mcp-server 0.1.0

package/dist/guides/component-metadata.js

@@ -0,0 +1,789 @@
+/**
+ * 全コンポーネントの構造メタデータ
+ *
+ * ComponentStyleConfig から抽出した静的情報。
+ * MCP Server 側でコンポーネントガイドを生成するためのデータソース。
+ *
+ * - type: "single" (cva ベース) / "multipart" (slots ベース)
+ * - variants: バリアントキーとそのオプション
+ * - slots: multipart の構成パーツ
+ * - dependencies: Radix UI 等の実行時依存
+ * - a11y: アクセシビリティ上の注意事項
+ * - states: 対応する UI ステート
+ * - doNot: よくある誤用・禁止事項
+ */
+export const componentMetadata = {
+    // --- form ---
+    button: {
+        type: "single",
+        variants: {
+            variant: [
+                "default",
+                "destructive",
+                "outline",
+                "secondary",
+                "ghost",
+                "link",
+            ],
+            size: ["default", "sm", "lg", "icon"],
+        },
+        dependencies: ["@radix-ui/react-slot"],
+        a11y: [
+            "Use <button> for actions, <a> for navigation (use asChild with Link)",
+            "Always provide accessible label: visible text or aria-label for icon buttons",
+            "Disabled buttons must use disabled attribute, not aria-disabled",
+        ],
+        states: ["hover", "focus-visible", "active", "disabled"],
+        doNot: [
+            "Do not use color props — use variant instead",
+            "Do not hardcode border-radius — it comes from design tokens",
+            "Do not nest interactive elements inside a button",
+            "Do not use ghost/link variant for primary actions",
+            'Do not omit the variant prop — always specify variant explicitly (e.g. variant="default") for clarity',
+        ],
+    },
+    input: {
+        type: "single",
+        variants: {},
+        dependencies: [],
+        a11y: [
+            "Prefer pairing with <Label> using htmlFor; if not possible, provide aria-label or aria-labelledby",
+            "Use aria-describedby for help text or error messages",
+            "Ensure visible focus ring (provided by default styles)",
+        ],
+        states: ["hover", "focus-visible", "disabled", "placeholder"],
+        doNot: [
+            "Do not use placeholder as label replacement — every input must have an accessible name (prefer visible Label with htmlFor; fallback to sr-only Label, aria-label, or aria-labelledby)",
+            "Do not remove the focus ring",
+        ],
+    },
+    textarea: {
+        type: "single",
+        variants: {},
+        dependencies: [],
+        a11y: [
+            "Always pair with <Label> using htmlFor",
+            "Use aria-describedby for character count or error messages",
+        ],
+        states: ["hover", "focus-visible", "disabled", "placeholder"],
+        doNot: ["Do not use placeholder as label replacement"],
+    },
+    label: {
+        type: "single",
+        variants: {},
+        dependencies: ["@radix-ui/react-label"],
+        a11y: ["Must be associated with a form control via htmlFor"],
+        states: ["peer-disabled"],
+    },
+    checkbox: {
+        type: "multipart",
+        slots: ["root", "indicator"],
+        dependencies: ["@radix-ui/react-checkbox"],
+        a11y: [
+            "Must have an accessible label (adjacent <Label> or aria-label)",
+            "Supports aria-checked='indeterminate' for tri-state",
+        ],
+        states: ["hover", "focus-visible", "checked", "disabled"],
+    },
+    "radio-group": {
+        type: "multipart",
+        slots: ["root", "item", "indicator"],
+        dependencies: ["@radix-ui/react-radio-group"],
+        a11y: [
+            "Group must have aria-label or aria-labelledby",
+            "Each item must have a value and accessible label",
+        ],
+        states: ["hover", "focus-visible", "checked", "disabled"],
+    },
+    select: {
+        type: "multipart",
+        slots: [
+            "trigger",
+            "content",
+            "item",
+            "label",
+            "separator",
+            "scrollUpButton",
+            "scrollDownButton",
+        ],
+        dependencies: ["@radix-ui/react-select"],
+        a11y: [
+            "Trigger must have an accessible label",
+            "Items support keyboard navigation by default",
+        ],
+        states: ["hover", "focus-visible", "open", "disabled"],
+    },
+    switch: {
+        type: "multipart",
+        slots: ["root", "thumb"],
+        dependencies: ["@radix-ui/react-switch"],
+        a11y: [
+            "Must have an accessible label",
+            "Use aria-checked (managed by Radix)",
+        ],
+        states: ["hover", "focus-visible", "checked", "disabled"],
+    },
+    slider: {
+        type: "multipart",
+        slots: ["root", "track", "range", "thumb"],
+        dependencies: ["@radix-ui/react-slider"],
+        a11y: [
+            "Must have aria-label or aria-labelledby",
+            "Supports keyboard arrows for value adjustment",
+        ],
+        states: ["hover", "focus-visible", "disabled"],
+    },
+    toggle: {
+        type: "single",
+        variants: {
+            variant: ["default", "outline"],
+            size: ["default", "sm", "lg"],
+        },
+        dependencies: ["@radix-ui/react-toggle"],
+        a11y: ["Use aria-pressed (managed by Radix)", "Provide accessible label"],
+        states: ["hover", "focus-visible", "pressed", "disabled"],
+    },
+    "toggle-group": {
+        type: "multipart",
+        slots: ["root", "item"],
+        dependencies: ["@radix-ui/react-toggle-group"],
+        a11y: [
+            "Group must have aria-label",
+            "Supports single or multiple selection",
+        ],
+        states: ["hover", "focus-visible", "pressed", "disabled"],
+    },
+    form: {
+        type: "multipart",
+        slots: ["item", "label", "control", "description", "message"],
+        dependencies: ["react-hook-form", "@hookform/resolvers"],
+        a11y: [
+            "FormField auto-connects label, description, and error message via aria attributes",
+            "Error messages announced via aria-live",
+        ],
+        states: ["error", "disabled"],
+    },
+    field: {
+        type: "multipart",
+        slots: [
+            "fieldSet",
+            "fieldLegend",
+            "fieldGroup",
+            "field",
+            "fieldContent",
+            "fieldLabel",
+            "fieldTitle",
+            "fieldDescription",
+            "fieldSeparator",
+            "fieldSeparatorContent",
+            "fieldError",
+        ],
+        variants: {
+            fieldOrientation: ["vertical", "horizontal", "responsive"],
+            legendVariant: ["legend", "label"],
+        },
+        dependencies: [],
+        a11y: ["Use fieldset/legend for grouping related fields"],
+        states: ["error", "disabled"],
+    },
+    "input-group": {
+        type: "multipart",
+        slots: ["root", "addon", "button", "text", "input", "textarea"],
+        variants: {
+            addonAlign: ["inline-start", "inline-end", "block-start", "block-end"],
+            buttonSize: ["xs", "sm", "icon-xs", "icon-sm"],
+        },
+        dependencies: [],
+        states: ["focus-within", "disabled"],
+    },
+    "input-otp": {
+        type: "multipart",
+        slots: [
+            "root",
+            "container",
+            "group",
+            "slot",
+            "slotActive",
+            "caret",
+            "caretBlink",
+            "separator",
+        ],
+        dependencies: ["input-otp"],
+        a11y: ["Auto-focuses next input on entry", "Supports paste for full code"],
+        states: ["focus-visible", "active", "disabled"],
+    },
+    calendar: {
+        type: "multipart",
+        slots: [
+            "root",
+            "months",
+            "month",
+            "caption",
+            "nav",
+            "table",
+            "head",
+            "row",
+            "cell",
+            "day",
+            "dayButton",
+            "dayButtonSelected",
+            "dayButtonToday",
+            "dayButtonRangeStart",
+            "dayButtonRangeMiddle",
+            "dayButtonRangeEnd",
+        ],
+        dependencies: ["react-day-picker"],
+        a11y: [
+            "Full keyboard navigation",
+            "Announces selected date to screen readers",
+        ],
+        states: [
+            "selected",
+            "today",
+            "range-start",
+            "range-middle",
+            "range-end",
+            "disabled",
+            "outside",
+        ],
+    },
+    combobox: {
+        type: "multipart",
+        slots: ["trigger", "input", "content", "item", "empty"],
+        dependencies: ["@radix-ui/react-popover", "cmdk"],
+        a11y: ["Supports typeahead search", "Keyboard navigation in list"],
+        states: ["open", "selected", "disabled"],
+    },
+    "date-picker": {
+        type: "multipart",
+        slots: ["trigger", "content", "calendar"],
+        dependencies: ["react-day-picker", "@radix-ui/react-popover"],
+        a11y: ["Combines popover + calendar accessibility"],
+        states: ["open", "selected", "disabled"],
+    },
+    "button-group": {
+        type: "multipart",
+        slots: ["root", "text", "separator"],
+        variants: {
+            orientation: ["horizontal", "vertical"],
+        },
+        dependencies: [],
+        states: ["hover", "focus-visible", "disabled"],
+    },
+    // --- data-display ---
+    badge: {
+        type: "single",
+        variants: {
+            variant: ["default", "secondary", "destructive", "outline"],
+        },
+        dependencies: [],
+        a11y: ["Use aria-label if badge content is not self-explanatory"],
+        states: [],
+        doNot: [
+            "Do not use badge for interactive elements — it is display-only",
+            "Do not override colors directly — use variant",
+            'Do not use variant="default" for supplementary info — use variant="default" for primary categories and variant="secondary" for supplementary attributes or status labels',
+        ],
+    },
+    accordion: {
+        type: "multipart",
+        slots: ["item", "trigger", "content"],
+        dependencies: ["@radix-ui/react-accordion"],
+        a11y: [
+            "Trigger uses aria-expanded",
+            "Content uses role='region' with aria-labelledby",
+            "Full keyboard navigation (Arrow keys, Home, End)",
+        ],
+        states: ["open", "hover", "focus-visible", "disabled"],
+    },
+    avatar: {
+        type: "multipart",
+        slots: ["root", "image", "fallback"],
+        dependencies: ["@radix-ui/react-avatar"],
+        a11y: [
+            "Image must have alt text",
+            "Fallback shown when image fails to load",
+        ],
+        states: [],
+    },
+    carousel: {
+        type: "multipart",
+        slots: ["root", "content", "item", "previous", "next"],
+        dependencies: ["embla-carousel-react"],
+        a11y: [
+            "Previous/Next buttons must have aria-label",
+            "Use aria-roledescription='carousel' on root",
+        ],
+        states: ["hover", "focus-visible", "dragging"],
+    },
+    chart: {
+        type: "multipart",
+        slots: [
+            "container",
+            "tooltip",
+            "tooltipContent",
+            "legend",
+            "legendContent",
+        ],
+        dependencies: ["recharts"],
+        a11y: ["Provide text alternative or data table for charts"],
+        states: [],
+    },
+    collapsible: {
+        type: "multipart",
+        slots: ["root", "trigger", "content"],
+        dependencies: ["@radix-ui/react-collapsible"],
+        a11y: ["Trigger uses aria-expanded", "Content can be animated"],
+        states: ["open", "hover", "focus-visible"],
+    },
+    "data-table": {
+        type: "multipart",
+        slots: [
+            "root",
+            "header",
+            "body",
+            "footer",
+            "row",
+            "head",
+            "cell",
+            "caption",
+        ],
+        dependencies: ["@tanstack/react-table"],
+        a11y: ["Must have caption or aria-label", "Use <th> scope attribute"],
+        states: ["hover", "selected"],
+    },
+    table: {
+        type: "multipart",
+        slots: [
+            "root",
+            "header",
+            "body",
+            "footer",
+            "row",
+            "head",
+            "cell",
+            "caption",
+        ],
+        dependencies: [],
+        a11y: [
+            "Must have caption or aria-label",
+            "Use semantic <thead>/<tbody>/<tfoot>",
+        ],
+        states: ["hover"],
+    },
+    item: {
+        type: "multipart",
+        slots: [
+            "group",
+            "separator",
+            "item",
+            "media",
+            "content",
+            "title",
+            "description",
+            "actions",
+            "header",
+            "footer",
+        ],
+        variants: {
+            itemVariant: ["default", "outline", "muted"],
+            itemSize: ["default", "sm"],
+            mediaVariant: ["default", "icon", "image"],
+        },
+        dependencies: [],
+        states: ["hover", "focus-visible"],
+    },
+    kbd: {
+        type: "multipart",
+        slots: ["kbd", "group"],
+        dependencies: [],
+        a11y: ["Use <kbd> semantic element for keyboard shortcuts"],
+        states: [],
+    },
+    typography: {
+        type: "single",
+        variants: {},
+        dependencies: [],
+        states: [],
+    },
+    // --- feedback ---
+    alert: {
+        type: "multipart",
+        slots: ["root", "title", "description"],
+        variants: {
+            variant: ["default", "destructive"],
+        },
+        dependencies: [],
+        a11y: [
+            "Use role='alert' for urgent messages (destructive)",
+            "Use role='status' for informational messages",
+        ],
+        states: [],
+        doNot: ["Do not use alert for toast notifications — use sonner instead"],
+    },
+    progress: {
+        type: "multipart",
+        slots: ["root", "indicator"],
+        dependencies: ["@radix-ui/react-progress"],
+        a11y: [
+            "Uses role='progressbar' with aria-valuenow/aria-valuemin/aria-valuemax",
+            "Add aria-label describing what is loading",
+        ],
+        states: ["indeterminate"],
+    },
+    skeleton: {
+        type: "single",
+        variants: {},
+        dependencies: [],
+        a11y: ["Use aria-hidden='true' and provide sr-only loading text"],
+        states: ["animate-pulse"],
+    },
+    sonner: {
+        type: "multipart",
+        slots: ["toaster", "toast", "description", "actionButton", "cancelButton"],
+        dependencies: ["sonner"],
+        a11y: [
+            "Toasts announced via aria-live",
+            "Action buttons must be keyboard accessible",
+        ],
+        states: [],
+    },
+    spinner: {
+        type: "single",
+        variants: {},
+        dependencies: [],
+        a11y: ["Use aria-hidden='true' and provide sr-only loading text nearby"],
+        states: ["animate-spin"],
+    },
+    empty: {
+        type: "multipart",
+        slots: ["root", "header", "media", "title", "description", "content"],
+        dependencies: [],
+        states: [],
+    },
+    // --- overlay ---
+    dialog: {
+        type: "multipart",
+        slots: [
+            "root",
+            "trigger",
+            "portal",
+            "overlay",
+            "content",
+            "header",
+            "title",
+            "description",
+            "footer",
+            "close",
+        ],
+        dependencies: ["@radix-ui/react-dialog"],
+        a11y: [
+            "Focus trapped inside dialog when open",
+            "Must have title (DialogTitle required)",
+            "Escape key closes dialog",
+            "Returns focus to trigger on close",
+        ],
+        states: ["open"],
+        doNot: [
+            "Do not nest dialogs",
+            "Do not use dialog for simple confirmations — use alert-dialog",
+        ],
+    },
+    "alert-dialog": {
+        type: "multipart",
+        slots: [
+            "overlay",
+            "content",
+            "header",
+            "title",
+            "description",
+            "footer",
+            "action",
+            "cancel",
+        ],
+        dependencies: ["@radix-ui/react-alert-dialog"],
+        a11y: [
+            "Focus trapped inside dialog",
+            "Must have title and description",
+            "Cannot be dismissed by clicking overlay (intentional)",
+        ],
+        states: ["open"],
+    },
+    sheet: {
+        type: "multipart",
+        slots: ["overlay", "content", "header", "title", "description", "footer"],
+        dependencies: ["@radix-ui/react-dialog"],
+        a11y: ["Same as dialog: focus trap, title required, escape to close"],
+        states: ["open"],
+    },
+    drawer: {
+        type: "multipart",
+        slots: [
+            "root",
+            "trigger",
+            "portal",
+            "overlay",
+            "content",
+            "header",
+            "footer",
+            "title",
+            "description",
+            "close",
+        ],
+        dependencies: ["vaul"],
+        a11y: ["Supports drag-to-dismiss gesture", "Focus trapped when open"],
+        states: ["open", "dragging"],
+    },
+    "dropdown-menu": {
+        type: "multipart",
+        slots: [
+            "content",
+            "item",
+            "checkboxItem",
+            "radioItem",
+            "label",
+            "separator",
+            "shortcut",
+            "subTrigger",
+            "subContent",
+        ],
+        dependencies: ["@radix-ui/react-dropdown-menu"],
+        a11y: [
+            "Full keyboard navigation (arrows, type-ahead)",
+            "Items have role='menuitem'",
+        ],
+        states: ["open", "hover", "focus-visible"],
+    },
+    "context-menu": {
+        type: "multipart",
+        slots: [
+            "content",
+            "item",
+            "checkboxItem",
+            "radioItem",
+            "label",
+            "separator",
+            "shortcut",
+            "subTrigger",
+            "subContent",
+        ],
+        dependencies: ["@radix-ui/react-context-menu"],
+        a11y: ["Opened via right-click", "Full keyboard navigation"],
+        states: ["open", "hover", "focus-visible"],
+    },
+    popover: {
+        type: "multipart",
+        slots: ["trigger", "content"],
+        dependencies: ["@radix-ui/react-popover"],
+        a11y: ["Focus managed when open", "Escape to close"],
+        states: ["open"],
+    },
+    "hover-card": {
+        type: "multipart",
+        slots: ["trigger", "content"],
+        dependencies: ["@radix-ui/react-hover-card"],
+        a11y: [
+            "Content must be accessible without hover (keyboard/touch)",
+            "Do not put essential info only in hover card",
+        ],
+        states: ["open"],
+        doNot: ["Do not use for critical information that must be always visible"],
+    },
+    tooltip: {
+        type: "multipart",
+        slots: ["trigger", "content"],
+        dependencies: ["@radix-ui/react-tooltip"],
+        a11y: [
+            "Shown on hover AND focus",
+            "Content set as aria-describedby on trigger",
+            "Escape key dismisses tooltip",
+        ],
+        states: ["open"],
+        doNot: [
+            "Do not put interactive content in tooltips",
+            "Do not use tooltip as a replacement for labels",
+        ],
+    },
+    menubar: {
+        type: "multipart",
+        slots: [
+            "root",
+            "trigger",
+            "content",
+            "item",
+            "checkboxItem",
+            "radioItem",
+            "label",
+            "separator",
+            "shortcut",
+            "subContent",
+            "subTrigger",
+        ],
+        dependencies: ["@radix-ui/react-menubar"],
+        a11y: [
+            "Full keyboard navigation between menus",
+            "Follows WAI-ARIA menu pattern",
+        ],
+        states: ["open", "hover", "focus-visible"],
+    },
+    // --- navigation ---
+    breadcrumb: {
+        type: "multipart",
+        slots: ["root", "list", "item", "link", "page", "separator", "ellipsis"],
+        dependencies: [],
+        a11y: [
+            "Use <nav aria-label='Breadcrumb'>",
+            "Current page uses aria-current='page'",
+        ],
+        states: ["hover"],
+    },
+    "navigation-menu": {
+        type: "multipart",
+        slots: [
+            "root",
+            "list",
+            "item",
+            "trigger",
+            "content",
+            "link",
+            "indicator",
+            "viewport",
+        ],
+        dependencies: ["@radix-ui/react-navigation-menu"],
+        a11y: ["Full keyboard navigation", "Uses WAI-ARIA navigation pattern"],
+        states: ["open", "hover", "focus-visible", "active"],
+    },
+    pagination: {
+        type: "multipart",
+        slots: [
+            "root",
+            "content",
+            "item",
+            "link",
+            "linkDisabled",
+            "previous",
+            "next",
+            "ellipsis",
+        ],
+        dependencies: [],
+        a11y: [
+            "Use <nav aria-label='Pagination'>",
+            "Current page uses aria-current='page'",
+        ],
+        states: ["hover", "focus-visible", "disabled", "active"],
+    },
+    tabs: {
+        type: "multipart",
+        slots: ["root", "list", "trigger", "content"],
+        dependencies: ["@radix-ui/react-tabs"],
+        a11y: [
+            "TabList uses role='tablist'",
+            "Tabs use role='tab' with aria-selected",
+            "Content uses role='tabpanel' with aria-labelledby",
+            "Arrow keys navigate between tabs",
+        ],
+        states: ["hover", "focus-visible", "active", "disabled"],
+        doNot: [
+            "Do not use Tabs without TabsList and TabsTrigger — always include the full sub-component structure (Tabs > TabsList > TabsTrigger + TabsContent)",
+            "Do not use arbitrary tab values — use descriptive string IDs that match TabsTrigger value and TabsContent value",
+        ],
+    },
+    command: {
+        type: "multipart",
+        slots: [
+            "root",
+            "inputWrapper",
+            "input",
+            "list",
+            "empty",
+            "group",
+            "item",
+            "shortcut",
+            "separator",
+        ],
+        dependencies: ["cmdk"],
+        a11y: [
+            "Typeahead search",
+            "Keyboard navigation in list",
+            "Announcements via aria-live",
+        ],
+        states: ["hover", "focus-visible", "selected"],
+    },
+    sidebar: {
+        type: "multipart",
+        slots: [
+            "provider",
+            "sidebar",
+            "trigger",
+            "header",
+            "footer",
+            "content",
+            "group",
+            "groupLabel",
+            "groupContent",
+            "menu",
+            "menuItem",
+            "menuButton",
+        ],
+        variants: {
+            menuButtonVariant: ["default", "outline"],
+            menuButtonSize: ["default", "sm", "lg"],
+        },
+        dependencies: [],
+        a11y: [
+            "Use <aside> with aria-label",
+            "Toggle button must indicate expanded state",
+        ],
+        states: ["expanded", "collapsed", "hover", "focus-visible"],
+    },
+    // --- layout ---
+    card: {
+        type: "multipart",
+        slots: ["root", "header", "title", "description", "content", "footer"],
+        dependencies: [],
+        a11y: [
+            "If card is clickable, use <a> or <button> as root with asChild",
+            "Card title should be a heading element for document outline",
+        ],
+        states: ["hover"],
+        doNot: [
+            "Do not nest cards",
+            "Do not put too many actions in a single card",
+            "Do not use Card without CardHeader and CardTitle — always include them for consistent structure and accessibility",
+            "Do not place action buttons (submit, cancel) in CardContent — place actions in CardFooter for consistent layout",
+        ],
+    },
+    "aspect-ratio": {
+        type: "single",
+        variants: {},
+        dependencies: ["@radix-ui/react-aspect-ratio"],
+        a11y: ["Image inside must have alt text"],
+        states: [],
+    },
+    separator: {
+        type: "single",
+        variants: {
+            orientation: ["horizontal", "vertical"],
+        },
+        dependencies: ["@radix-ui/react-separator"],
+        a11y: ["Uses role='separator' with aria-orientation"],
+        states: [],
+        doNot: [
+            "Do not use <hr> or border classes for visual separation — use Separator component for semantic and accessible dividers",
+        ],
+    },
+    "scroll-area": {
+        type: "multipart",
+        slots: ["root", "viewport", "scrollbar", "thumb"],
+        dependencies: ["@radix-ui/react-scroll-area"],
+        a11y: ["Keyboard scrollable", "Scrollbar visible on hover/focus"],
+        states: ["hover"],
+    },
+    resizable: {
+        type: "multipart",
+        slots: ["panelGroup", "panel", "handle", "handleIcon", "handleIconSvg"],
+        dependencies: ["react-resizable-panels"],
+        a11y: ["Handle is keyboard accessible", "Supports arrow keys for resizing"],
+        states: ["hover", "focus-visible", "dragging"],
+    },
+};