@triptease/design-system-mcp 1.0.18 → 1.0.20

package/src/manifests/components/entries/textarea.ts

@@ -1,56 +0,0 @@
-import { ComponentManifest } from '@/manifests/components/types.js';
-
-export default {
-  textarea: {
-    name: 'Textarea',
-    description: 'Multi-line text input field',
-    element: 'textarea',
-    usageGuidance: {
-      whenToUse: [
-        'Multi-line text input (comments, descriptions, messages)',
-        'Content length is unpredictable',
-        'Users need to review text while typing',
-        'Text may contain line breaks',
-      ],
-      avoid: [
-        'Single-line input (use text input)',
-        'Formatted text needed (use rich text editor)',
-        'Very long content (consider breaking into sections)',
-      ],
-    },
-    attributes: {
-      'aria-invalid': {
-        type: 'boolean',
-        description:
-          'Marks textarea as invalid for error styling. Pair with aria-describedby to associate error messages.',
-      },
-      disabled: {
-        type: 'boolean',
-        description: 'Disables the textarea',
-      },
-      placeholder: {
-        type: 'string',
-        description: 'Placeholder text. Should not replace label - always provide visible label element.',
-      },
-      rows: {
-        type: 'number',
-        description: 'Number of visible text lines',
-      },
-    },
-    states: ['default', 'hover', 'focus', 'disabled', 'invalid'],
-    examples: [
-      {
-        title: 'Basic usage',
-        code: `<label for="about">About</label>
-<textarea id="about" rows="4"></textarea>`,
-      },
-      {
-        title: 'Error state',
-        description: 'Use aria-invalid with aria-describedby to associate error messages for screen readers',
-        code: `<label for="description">Description</label>
-<textarea id="description" rows="4" aria-invalid aria-describedby="description-error"></textarea>
-<span id="description-error" class="text-error">Description is required</span>`,
-      },
-    ],
-  },
-} satisfies ComponentManifest;

package/src/manifests/components/entries/textinput.ts

@@ -1,55 +0,0 @@
-import { ComponentManifest } from '@/manifests/components/types.js';
-
-export default {
-  textinput: {
-    name: 'Text Input',
-    description: 'Text input field for single-line text entry with automatic validation styling',
-    element: 'input',
-    usageGuidance: {
-      whenToUse: [
-        'Single-line text entry (names, email, search)',
-        'Predictable, short text length',
-        'Specific input types (email, password, tel, url)',
-      ],
-      avoid: [
-        'Multi-line text (use textarea)',
-        'Selecting from options (use select, radio, or combobox)',
-        'Pure numeric entry (consider number input)',
-      ],
-    },
-    attributes: {
-      type: {
-        values: ['text', 'email', 'password', 'tel', 'url'],
-        default: 'text',
-      },
-      'aria-invalid': {
-        type: 'boolean',
-        description:
-          'Marks input as invalid for error styling. Pair with aria-describedby to associate error messages.',
-      },
-      disabled: {
-        type: 'boolean',
-        description: 'Disables the input',
-      },
-      placeholder: {
-        type: 'string',
-        description: 'Placeholder text. Should not replace label - always provide visible label element.',
-      },
-    },
-    states: ['default', 'hover', 'focus', 'disabled', 'invalid'],
-    examples: [
-      {
-        title: 'Basic usage',
-        code: `<label for="hotel-name">Hotel Name</label>
-<input id="hotel-name" />`,
-      },
-      {
-        title: 'Error state',
-        description: 'Use aria-invalid with aria-describedby to associate error messages for screen readers',
-        code: `<label for="email">Email</label>
-<input id="email" type="email" aria-invalid aria-describedby="email-error" />
-<span id="email-error" class="text-error">Please enter a valid email address</span>`,
-      },
-    ],
-  },
-} satisfies ComponentManifest;

package/src/manifests/components/entries/toggle.ts

@@ -1,31 +0,0 @@
-import { ComponentManifest } from '@/manifests/components/types.js';
-
-export default {
-  toggle: {
-    name: 'Toggle',
-    description: 'Toggle switch for binary on/off states with immediate effect',
-    element: "input[type='checkbox'][data-theme='toggle']",
-    usageGuidance: {
-      whenToUse: ['Binary on/off states', 'Changes take effect immediately', 'System or feature settings'],
-      avoid: [
-        'Changes require saving (use checkbox in form)',
-        'More than two options exist (use radio buttons or select)',
-        "Relationship between on/off isn't clear",
-      ],
-    },
-    dataAttributes: {
-      'data-theme': {
-        type: 'enum',
-        values: ['toggle'],
-        description: "Use 'toggle' for switch style",
-      },
-    },
-    examples: [
-      {
-        title: 'Toggle switch',
-        code: `<input type="checkbox" id="weekly-parity-report" data-theme="toggle" />
-<label for="weekly-parity-report">Weekly Parity Report</label>`,
-      },
-    ],
-  },
-} satisfies ComponentManifest;

package/src/manifests/components/entries/typography.ts

@@ -1,33 +0,0 @@
-import { ComponentManifest } from '@/manifests/components/types.js';
-
-export default {
-  typography: {
-    name: 'Typography',
-    description: 'Text styling using semantic HTML elements and utility classes',
-    element: 'h1-h4, p, strong, a',
-    usageGuidance: {
-      whenToUse: [
-        'Use semantic elements (h1-h4, strong, a) for document structure and accessibility',
-        'Use utility classes (.heading-1 through .heading-4, .display, .body, .small, .strong, .text-error) when visual styling must differ from semantic meaning',
-        "Follow heading hierarchy - don't skip levels (h1 → h2 → h3, not h1 → h3)",
-        'Use <strong> for semantic importance, .strong for visual styling only',
-      ],
-      avoid: [
-        'Using heading classes for document structure (use semantic h1-h4 elements)',
-        'Skipping heading levels (breaks accessibility)',
-        'Using buttons styled as links or links styled as buttons (use correct semantic element)',
-      ],
-    },
-    classes: {
-      display: 'Largest text size for hero sections and prominent headlines',
-      'heading-1': 'h1 visual styling',
-      'heading-2': 'h2 visual styling',
-      'heading-3': 'h3 visual styling',
-      'heading-4': 'h4 visual styling',
-      body: 'Standard body text styling',
-      strong: 'Bold text styling without semantic importance',
-      small: 'Smaller text for captions, helper text, fine print',
-      'text-error': 'Error text color for validation messages',
-    },
-  },
-} satisfies ComponentManifest;

package/src/manifests/components/index.ts

@@ -1,45 +0,0 @@
-import type { ComponentManifest } from './types.js';
-
-import button from '@/manifests/components/entries/button.js';
-import textinput from '@/manifests/components/entries/textinput.js';
-import numberinput from '@/manifests/components/entries/numberinput.js';
-import textarea from '@/manifests/components/entries/textarea.js';
-import select from '@/manifests/components/entries/select.js';
-import checkbox from '@/manifests/components/entries/checkbox.js';
-import radio from '@/manifests/components/entries/radio.js';
-import toggle from '@/manifests/components/entries/toggle.js';
-import badge from '@/manifests/components/entries/badge.js';
-import card from '@/manifests/components/entries/card.js';
-import table from '@/manifests/components/entries/table.js';
-import typography from '@/manifests/components/entries/typography.js';
-import dialog from '@/manifests/components/entries/dialog.js';
-import combobox from '@/manifests/components/entries/combobox.js';
-import datePicker from '@/manifests/components/entries/datePicker.js';
-import dateRangePicker from '@/manifests/components/entries/dateRangePicker.js';
-import barChart from '@/manifests/components/entries/barChart.js';
-import lineChart from '@/manifests/components/entries/lineChart.js';
-import statistic from '@/manifests/components/entries/statistic.js';
-import banner from '@/manifests/components/entries/banner.js';
-
-export const componentManifest: ComponentManifest = {
-  ...button,
-  ...textinput,
-  ...numberinput,
-  ...textarea,
-  ...select,
-  ...checkbox,
-  ...radio,
-  ...toggle,
-  ...badge,
-  ...card,
-  ...table,
-  ...typography,
-  ...dialog,
-  ...combobox,
-  ...datePicker,
-  ...dateRangePicker,
-  ...barChart,
-  ...lineChart,
-  ...statistic,
-  ...banner,
-};

package/src/manifests/components/types.ts

@@ -1,65 +0,0 @@
-interface UsageGuidance {
-  whenToUse: string[];
-  bestPractices?: string[];
-  accessibility?: string[];
-  avoid?: string[];
-}
-
-interface PackageInstallationBase {
-  includesTypes: boolean;
-  optional: boolean;
-  guidance?: string;
-}
-
-interface NPMPackage extends PackageInstallationBase {
-  name: string;
-}
-
-interface CDNPackage extends PackageInstallationBase {
-  name: string;
-  latestVersionUrl: string;
-  pinnedMajorVersionUrl: string;
-  pinnedVersionUrl: string;
-  moduleFormat?: string;
-}
-
-interface InstallationOptions {
-  npm?: NPMPackage[];
-  cdn?: CDNPackage[];
-}
-
-interface DataAttribute {
-  type: string;
-  values?: (string | undefined)[];
-  default?: string;
-  description: string;
-}
-
-interface HTMLAttribute {
-  type?: string;
-  values?: string[];
-  default?: string;
-  description?: string;
-}
-
-interface ExampleUsage {
-  title: string;
-  description?: string;
-  code: string;
-}
-
-export interface ComponentConfig {
-  name: string;
-  description: string;
-  ssrSafe?: boolean;
-  element: string;
-  usageGuidance?: UsageGuidance;
-  installationOptions?: InstallationOptions;
-  dataAttributes?: Record<string, DataAttribute>;
-  classes?: Record<string, string>;
-  attributes?: Record<string, HTMLAttribute>;
-  states?: string[];
-  examples?: ExampleUsage[];
-}
-
-export type ComponentManifest = Record<string, ComponentConfig>;

package/src/resources/components/get.test.ts

@@ -1,39 +0,0 @@
-import { getComponentDocs } from './get.js';
-import { describe, expect, it } from 'vitest';
-
-describe('getComponentDocs resource', () => {
-  it('should return error for non-existent component', async () => {
-    const result = await getComponentDocs('foo');
-    const data = JSON.parse(result.contents[0].text);
-
-    expect(data.error).toBe("Component 'foo' not found");
-    expect(data.available).toBeDefined();
-    expect(Array.isArray(data.available)).toBe(true);
-  });
-
-  it('should return component manifest for valid component', async () => {
-    const result = await getComponentDocs('button');
-    const data = JSON.parse(result.contents[0].text);
-
-    expect(data.name).toBe('Button');
-    expect(data.element).toBe('button');
-    expect(data.description).toBeDefined();
-    expect(data.dataAttributes).toBeDefined();
-  });
-
-  it('should return contents with correct URI and mimeType', async () => {
-    const result = await getComponentDocs('button');
-
-    expect(result.contents).toBeDefined();
-    expect(result.contents).toHaveLength(1);
-    expect(result.contents[0].uri).toBe('designsystem://components/button');
-    expect(result.contents[0].mimeType).toBe('application/json');
-  });
-
-  it('should handle case-insensitive component names', async () => {
-    const lowerResult = await getComponentDocs('button');
-    const upperResult = await getComponentDocs('BUTTON');
-
-    expect(JSON.parse(lowerResult.contents[0].text)).toEqual(JSON.parse(upperResult.contents[0].text));
-  });
-});

package/src/resources/components/get.ts

@@ -1,35 +0,0 @@
-import { componentManifest } from '@/manifests/components/index.js';
-
-export const getComponentDocs = async (name: string) => {
-  const componentName = name.toLowerCase();
-  const component = componentManifest[componentName];
-
-  if (!component) {
-    return {
-      contents: [
-        {
-          uri: `designsystem://components/${name}`,
-          mimeType: 'application/json',
-          text: JSON.stringify(
-            {
-              error: `Component '${componentName}' not found`,
-              available: Object.keys(componentManifest),
-            },
-            null,
-            2
-          ),
-        },
-      ],
-    };
-  }
-
-  return {
-    contents: [
-      {
-        uri: `designsystem://components/${name}`,
-        mimeType: 'application/json',
-        text: JSON.stringify(component, null, 2),
-      },
-    ],
-  };
-};

package/src/resources/components/index.ts

@@ -1,2 +0,0 @@
-export { listComponents } from './list.js';
-export { getComponentDocs } from './get.js';

package/src/resources/components/list.test.ts

@@ -1,40 +0,0 @@
-import { listComponents } from './list.js';
-import { describe, expect, it } from 'vitest';
-
-describe('listComponents resource', () => {
-  it('should return contents with correct URI and mimeType', async () => {
-    const result = await listComponents();
-
-    expect(result.contents).toBeDefined();
-    expect(result.contents).toHaveLength(1);
-    expect(result.contents[0].uri).toBe('designsystem://components');
-    expect(result.contents[0].mimeType).toBe('application/json');
-  });
-
-  it('should return all 20 components', async () => {
-    const result = await listComponents();
-    const data = JSON.parse(result.contents[0].text);
-
-    expect(data.components).toHaveLength(20);
-  });
-
-  it('should include component key, name, description, and element', async () => {
-    const result = await listComponents();
-    const data = JSON.parse(result.contents[0].text);
-    const firstComponent = data.components[0];
-
-    expect(firstComponent).toHaveProperty('key');
-    expect(firstComponent).toHaveProperty('name');
-    expect(firstComponent).toHaveProperty('description');
-    expect(firstComponent).toHaveProperty('element');
-  });
-
-  it('should include button component', async () => {
-    const result = await listComponents();
-    const data = JSON.parse(result.contents[0].text);
-    const buttonComponent = data.components.find((c: any) => c.key === 'button');
-
-    expect(buttonComponent).toBeDefined();
-    expect(buttonComponent.name).toBe('Button');
-  });
-});

package/src/resources/components/list.ts

@@ -1,20 +0,0 @@
-import { componentManifest } from '@/manifests/components/index.js';
-
-export const listComponents = async () => {
-  const components = Object.entries(componentManifest).map(([key, comp]) => ({
-    key,
-    name: comp.name,
-    description: comp.description,
-    element: comp.element,
-  }));
-
-  return {
-    contents: [
-      {
-        uri: 'designsystem://components',
-        mimeType: 'application/json',
-        text: JSON.stringify({ components }, null, 2),
-      },
-    ],
-  };
-};

package/src/resources/guides/index.ts

@@ -1,2 +0,0 @@
-export { getSetupGuide } from './setup.js';
-export { getPrinciplesGuide } from './principles.js';

package/src/resources/guides/principles.ts

@@ -1,160 +0,0 @@
-export const designSystemPrinciples = {
-  overview: {
-    corePrinciple:
-      'Trust the design system. Components and classes are fully styled and production-ready. Use them as-is.',
-    philosophy:
-      'The design system handles styling, spacing, colors, and layouts. Your role is to compose components, not recreate their styling.',
-  },
-  cssClassUsage: {
-    defaultApproach: 'Use existing classes without writing additional CSS',
-    do: [
-      'Use classes as-is without extra styling (e.g., <div class="card">)',
-      'Check component documentation BEFORE writing any custom CSS',
-      'Compose with multiple classes when needed (e.g., class="card stat-card")',
-      'Override using CSS variables when provided (e.g., style="--card-padding: var(--space-scale-4)")',
-      'Trust that design system classes include ALL necessary styling (layout, spacing, colors, shadows)',
-    ],
-    dont: [
-      "Don't duplicate CSS that classes already provide (border, background, padding, etc.)",
-      "Don't create new classes without checking if design system has it",
-      "Don't assume classes need additional styling - verify in docs first",
-      "Don't override design tokens with hardcoded values (use CSS variables instead)",
-      "Don't add wrapper divs just to style - compose classes directly",
-    ],
-  },
-  verificationWorkflow: {
-    description: 'Follow this workflow BEFORE writing any custom CSS',
-    steps: [
-      '1. Check: Does the design system have this component? (Query designsystem://components)',
-      '2. Read: What does the component provide? (Check component docs)',
-      '3. Use: Apply the class without custom CSS first',
-      '4. Test: Does it work as-is? (Usually yes!)',
-      '5. Customize: Only if truly needed, use CSS variables or add modifier classes',
-    ],
-  },
-  whenToWriteCustomCSS: {
-    description: 'Write custom CSS only in these scenarios',
-    scenarios: [
-      'User explicitly requests custom/unique styling',
-      'Design system genuinely lacks the needed component',
-      'Truly unique layout requirements that cannot be solved with existing classes or composition',
-      'Dashboard-specific or app-specific layout patterns (grids, specialized containers)',
-    ],
-    notValidReasons: [
-      'Not valid: "I need a card with padding" - .card already has padding',
-      'Not valid: "I need a button with a border" - button already has borders',
-      'Not valid: "I need spacing between elements" - use design system spacing tokens',
-    ],
-  },
-  compositionPatterns: {
-    description: 'How to combine design system classes effectively',
-    patterns: [
-      {
-        pattern: 'Base + Modifier',
-        example: '<div class="card stat-card">',
-        explanation: 'Use base design system class (card) + your modifier class (stat-card) for extensions',
-      },
-      {
-        pattern: 'CSS Variable Override',
-        example: '<div class="card" style="--card-padding: var(--space-scale-5)">',
-        explanation: 'Override CSS variables for customization without duplicating styles',
-      },
-      {
-        pattern: 'Multiple Design System Classes',
-        example: '<button class="primary large">',
-        explanation: 'Compose multiple utility/variant classes from design system',
-      },
-    ],
-  },
-  designTokens: {
-    description: 'Use design tokens instead of hardcoded values',
-    principle: 'All spacing, colors, typography should use CSS custom properties (--*)',
-    examples: [
-      {
-        wrong: 'padding: 24px',
-        right: 'padding: var(--space-scale-3)',
-        why: 'Tokens ensure consistency and enable theming',
-      },
-      {
-        wrong: 'color: #DA0707',
-        right: 'color: var(--color-alert-400)',
-        why: 'Semantic tokens communicate intent and adapt to themes',
-      },
-      {
-        wrong: 'font-size: 16px',
-        right: 'font-size: var(--font-size-300)',
-        why: 'Typography scale ensures visual hierarchy',
-      },
-    ],
-  },
-  commonMistakes: {
-    description: 'Common mistakes developers make (and how to avoid them)',
-    mistakes: [
-      {
-        mistake: 'Recreating .card styling',
-        problem: 'Duplicating background, border, padding, shadows that .card already provides',
-        solution: 'Use <div class="card"> directly. It includes everything.',
-        prevention: 'Read component docs BEFORE writing CSS',
-      },
-      {
-        mistake: 'Adding wrapper divs for styling',
-        problem: '<div class="my-wrapper"><div class="card">...</div></div>',
-        solution: 'Style the card directly: <div class="card my-modifier">',
-        prevention: 'Compose classes instead of wrapping',
-      },
-      {
-        mistake: 'Hardcoding spacing values',
-        problem: 'margin: 16px; gap: 12px;',
-        solution: 'margin: var(--space-scale-2); gap: var(--space-scale-1-5);',
-        prevention: 'Query designsystem://tokens/space for available values',
-      },
-      {
-        mistake: 'Assuming classes are incomplete',
-        problem: 'Adding display: flex, border: 1px solid, etc. to classes that already have these',
-        solution: "Trust the design system. Check docs to see what's included.",
-        prevention: 'Default assumption: classes are complete, not partial',
-      },
-    ],
-  },
-  resources: {
-    description: 'MCP resources for discovering design system capabilities',
-    available: [
-      {
-        resource: 'designsystem://components',
-        purpose: 'List all available components',
-      },
-      {
-        resource: 'designsystem://components/{name}',
-        purpose: 'Get detailed component documentation',
-      },
-      {
-        resource: 'designsystem://tokens',
-        purpose: 'List all token categories',
-      },
-      {
-        resource: 'designsystem://tokens/{category}',
-        purpose: 'Get tokens for specific category (color, space, font, etc.)',
-      },
-      {
-        resource: 'designsystem://guides/setup',
-        purpose: 'Installation instructions',
-      },
-      {
-        resource: 'designsystem://guides/principles',
-        purpose: 'This guide - design system usage principles',
-      },
-    ],
-  },
-};
-
-export const getPrinciplesGuide = async () => {
-  return {
-    contents: [
-      {
-        uri: 'designsystem://guides/principles',
-        mimeType: 'application/json',
-        text: JSON.stringify(designSystemPrinciples, null, 2),
-      },
-    ],
-  };
-};

package/src/resources/guides/setup.test.ts

@@ -1,72 +0,0 @@
-import { getSetupGuide } from './setup.js';
-import { describe, expect, it } from 'vitest';
-
-describe('getSetupGuide resource', () => {
-  it('should return all guides when no type is specified', async () => {
-    const result = await getSetupGuide();
-    const data = JSON.parse(result.contents[0].text);
-
-    expect(data.message).toBeDefined();
-    expect(data.options).toBeDefined();
-    expect(Array.isArray(data.options)).toBe(true);
-    expect(data.options).toHaveLength(2);
-    expect(data.options.some((opt: any) => opt.type === 'npm')).toBe(true);
-    expect(data.options.some((opt: any) => opt.type === 'cdn')).toBe(true);
-  });
-
-  it('should return npm guide with correct structure', async () => {
-    const result = await getSetupGuide('npm');
-    const data = JSON.parse(result.contents[0].text);
-
-    expect(data.name).toBe('NPM Stylesheet Setup');
-    expect(data.description).toBeDefined();
-    expect(Array.isArray(data.steps)).toBe(true);
-    expect(data.steps.length).toBeGreaterThan(0);
-    expect(data.notes).toBeDefined();
-  });
-
-  it('should return cdn guide with correct structure', async () => {
-    const result = await getSetupGuide('cdn');
-    const data = JSON.parse(result.contents[0].text);
-
-    expect(data.name).toBe('CDN Stylesheet Setup');
-    expect(data.description).toBeDefined();
-    expect(Array.isArray(data.steps)).toBe(true);
-    expect(data.steps.length).toBeGreaterThan(0);
-  });
-
-  it('should return error for invalid guide type', async () => {
-    const result = await getSetupGuide('invalid');
-    const data = JSON.parse(result.contents[0].text);
-
-    expect(data.error).toBe("Setup guide 'invalid' not found");
-    expect(data.available).toBeDefined();
-    expect(Array.isArray(data.available)).toBe(true);
-  });
-
-  it('should include code snippets in steps', async () => {
-    const result = await getSetupGuide('npm');
-    const data = JSON.parse(result.contents[0].text);
-    const firstStep = data.steps[0];
-
-    expect(firstStep).toHaveProperty('title');
-    expect(firstStep).toHaveProperty('code');
-    expect(firstStep).toHaveProperty('language');
-  });
-
-  it('should return contents with correct URI and mimeType for npm', async () => {
-    const result = await getSetupGuide('npm');
-
-    expect(result.contents).toBeDefined();
-    expect(result.contents).toHaveLength(1);
-    expect(result.contents[0].uri).toBe('designsystem://guides/setup/npm');
-    expect(result.contents[0].mimeType).toBe('application/json');
-  });
-
-  it('should handle case-insensitive guide type', async () => {
-    const lowerResult = await getSetupGuide('npm');
-    const upperResult = await getSetupGuide('NPM');
-
-    expect(JSON.parse(lowerResult.contents[0].text)).toEqual(JSON.parse(upperResult.contents[0].text));
-  });
-});