@czi-sds/mcp 0.4.0 → 0.5.0

package/data/resources/figma-rules.md

@@ -0,0 +1,101 @@
+# Figma to Code Translation Rules
+
+These rules guide Claude Code when translating Figma designs to code using the CZI Science Design System (SDS).
+
+## Design Token Priority
+
+### Spacing Values
+
+- **ALWAYS use SDS spacing tokens** instead of hardcoded pixel values
+- Map Figma spacing to SDS Tailwind classes: `p-sds-{size}`, `m-sds-{size}`, `gap-sds-{size}`
+- SDS spacing scale: `xs`, `s`, `m`, `l`, `xl`
+- Examples: `mb-sds-xs`, `px-sds-l`, `gap-sds-xl`
+
+### Color Values
+
+- **Prefer SDS color tokens** over hardcoded hex values from Figma
+- Use SDS semantic color classes: `text-light-sds-color-semantic-base-text-primary`
+- Include dark mode variants: `dark:text-dark-sds-color-semantic-base-text-primary`
+- Only use Figma hex values when no appropriate SDS token exists
+
+### Typography
+
+- **Map Figma text styles to SDS typography classes**
+- Format: `prose-sds-{type}-{size}-{weight}-{variant}`
+- Examples: `prose-sds-header-xl-600-wide`, `prose-sds-body-s-400-wide`
+- Use SDS font families: `font-sds-body`, `font-sds-header`, `font-sds-code`
+- Use SDS font weights: `font-sds-regular`, `font-sds-semibold`
+
+## Component Mapping Rules
+
+### SDS Component Priority
+
+- **Always prefer SDS components** over custom implementations
+- Import from `@czi-sds/components`: `import { Button, Icon, Link } from "@czi-sds/components"`
+- Use SDS-specific props: `sdsStyle`, `sdsType`, `sdsSize`, `sdsIcon`
+
+### Common Figma → SDS Mappings
+
+- **Figma Buttons** → `<Button sdsStyle="square|rounded|minimal" sdsType="primary|secondary">`
+- **Figma Icons** → `<Icon sdsIcon="IconName" sdsSize="xs|s|m|l|xl">`
+- **Figma Input Fields** → `<InputText>`, `<InputSlider>`, `<Autocomplete>`
+- **Figma Cards/Containers** → Use SDS spacing classes with `<div>` elements
+
+### Layout Translation
+
+- **Figma Auto Layout** → Tailwind Flexbox: `flex`, `flex-col`, `items-center`, `justify-between`
+- **Figma Grid** → Tailwind Grid: `grid`, `grid-cols-{n}`, `gap-sds-{size}`
+- **Figma Constraints** → Tailwind responsive utilities: `w-full`, `max-w-{size}`, `mx-auto`
+
+## Implementation Guidelines
+
+### Code Structure
+
+- Follow fractal file structure with colocated components
+- Use TypeScript interfaces for props
+- Implement responsive design with SDS breakpoints: `sm`, `md`, `lg`
+
+### Accessibility
+
+- Include ARIA labels and semantic HTML
+- Use SDS color tokens that meet contrast requirements
+- Follow SDS accessibility patterns for interactive elements
+
+### Best Practices
+
+- Extract repeated spacing patterns into reusable components
+- Use SDS design tokens consistently across related components
+- Document any deviations from SDS patterns with comments explaining why
+- Test components in both light and dark modes
+
+## Examples
+
+### Good - Using SDS Values
+
+```tsx
+import { Button, Icon } from "@czi-sds/components";
+
+<div className="flex items-center gap-sds-m p-sds-l">
+  <Button sdsStyle="square" sdsType="primary" className="font-sds-semibold">
+    Save Changes
+  </Button>
+  <Icon sdsIcon="Save" sdsSize="s" />
+</div>;
+```
+
+### Avoid - Hardcoded Values
+
+```tsx
+// Don't do this
+<div className="flex items-center gap-4 p-6">
+  <button className="bg-blue-500 px-4 py-2 font-bold">Save Changes</button>
+  <svg className="w-4 h-4">...</svg>
+</div>
+```
+
+## Design System Integration
+
+- Always check Zeroheight documentation for component usage guidelines
+- Verify SDS component APIs before implementing
+- Use SDS Storybook for component examples and prop references
+- When in doubt, prefer SDS patterns over custom solutions

package/data/resources/sds-component-rules.md

@@ -0,0 +1,189 @@
+# SDS Component Usage Rules
+
+These rules guide Claude Code when working with the CZI Science Design System (SDS) components.
+
+## Component Library Enforcement
+
+### Import Patterns
+
+- **Always prefer SDS components** over custom implementations or third-party alternatives
+- Use named imports: `import { Button, Icon, Link } from "@czi-sds/components"`
+- Avoid importing individual component files directly
+
+### SDS-Specific Props
+
+- **Use SDS-specific prop patterns** for consistent styling:
+  - `sdsStyle`: Controls visual style variants (`"square"`, `"rounded"`, `"minimal"`)
+  - `sdsType`: Controls semantic variants (`"primary"`, `"secondary"`, `"tertiary"`)
+  - `sdsSize`: Controls component sizing (`"xs"`, `"s"`, `"m"`, `"l"`, `"xl"`)
+  - `sdsIcon`: Specifies icon names for Icon components
+
+### Component Composition Patterns
+
+- **Follow SDS recommended composition patterns**:
+  - Use `Button` with `Icon` for button-icon combinations
+  - Use `InputText` with proper validation states
+  - Use `Tooltip` with appropriate trigger components
+
+## Design Token Usage
+
+### Spacing and Layout
+
+- **Use SDS spacing tokens** via Tailwind classes:
+  - Padding: `p-sds-xs`, `px-sds-m`, `py-sds-l`
+  - Margin: `m-sds-xs`, `mx-sds-m`, `my-sds-l`
+  - Gap: `gap-sds-xs`, `gap-x-sds-m`, `gap-y-sds-l`
+- Available spacing values: `xxs`, `xs`, `s`, `m`, `l`, `xl`, `xxl`
+
+### Typography
+
+- **Use SDS typography classes** for consistent text styling:
+  - Format: `prose-sds-{type}-{size}-{weight}-{variant}`
+  - Examples: `prose-sds-header-xl-600-wide`, `prose-sds-body-s-400-wide`
+- **Use SDS font families**: `font-sds-body`, `font-sds-header`, `font-sds-code`
+- **Use SDS font weights**: `font-sds-regular`, `font-sds-semibold`
+
+### Colors
+
+- **Use SDS semantic color tokens** for theme consistency:
+  - Text: `text-light-sds-color-semantic-base-text-primary`
+  - Backgrounds: `bg-light-sds-color-semantic-base-background-primary`
+  - **Always include dark mode variants**: `dark:text-dark-sds-color-semantic-base-text-primary`
+
+## Component-Specific Guidelines
+
+### Buttons
+
+```tsx
+// Preferred patterns
+<Button sdsStyle="square" sdsType="primary" onClick={handleClick}>
+  Primary Action
+</Button>
+
+<Button sdsStyle="minimal" sdsType="secondary" startIcon={<Icon sdsIcon="Add" sdsSize="xs" />}>
+  Secondary Action
+</Button>
+```
+
+### Icons
+
+```tsx
+// Use SDS icon names
+<Icon sdsIcon="CheckCircle" sdsSize="s" />
+<Icon sdsIcon="ExternalLink" sdsSize="xs" />
+
+// With interactive elements
+<Button startIcon={<Icon sdsIcon="Download" sdsSize="xs" />}>
+  Download
+</Button>
+```
+
+### Form Components
+
+```tsx
+// Use SDS form components
+<InputText
+  label="Email Address"
+  placeholder="Enter your email"
+  intent="default"
+/>
+
+<Autocomplete
+  label="Select Option"
+  options={options}
+  multiple={false}
+/>
+```
+
+## Accessibility Requirements
+
+### ARIA and Semantic HTML
+
+- **Use SDS components' built-in accessibility features**
+- Add custom ARIA attributes only when SDS components don't provide them
+- Use semantic HTML elements with SDS styling rather than generic divs when possible
+
+### Color Contrast
+
+- **SDS color tokens meet WCAG requirements** - use them instead of custom colors
+- Test components in both light and dark modes
+- Ensure sufficient contrast for interactive states
+
+## Code Quality Patterns
+
+### TypeScript Integration
+
+- **Use SDS component TypeScript interfaces** for prop typing
+- Import types when needed: `import { ButtonProps, IconName } from "@czi-sds/components"`
+- Extend SDS interfaces for custom component props
+
+### Responsive Design
+
+- **Use SDS breakpoint system** with Tailwind responsive prefixes:
+  - `xs:`, `sm:`, `md:`, `lg:`, `xl:`
+- Follow mobile-first responsive design patterns
+- Use SDS spacing tokens at all breakpoints
+
+### Testing Considerations
+
+- **SDS components are pre-tested** - focus tests on your business logic
+- Test accessibility using SDS components' built-in features
+- Use SDS Storybook for component API reference during development
+
+## Anti-Patterns to Avoid
+
+### Don't Override SDS Styles
+
+```tsx
+// ❌ Avoid overriding SDS component styles
+<Button className="!bg-red-500 !p-4">Bad</Button>
+
+// ✅ Use SDS props and tokens instead
+<Button sdsType="primary" className="p-sds-m">Good</Button>
+```
+
+### Don't Mix Design Systems
+
+```tsx
+// ❌ Don't mix SDS with other component libraries
+<MuiButton>Mixed</MuiButton>
+<Button>SDS Button</Button>
+
+// ✅ Use SDS consistently
+<Button sdsType="primary">Primary</Button>
+<Button sdsType="secondary">Secondary</Button>
+```
+
+### Don't Hardcode Design Tokens
+
+```tsx
+// ❌ Avoid hardcoded spacing/colors
+<div className="p-4 text-blue-600">Bad</div>
+
+// ✅ Use SDS tokens
+<div className="p-sds-m text-light-sds-color-semantic-accent-text-primary">Good</div>
+```
+
+## Integration with Other Systems
+
+### With Tailwind CSS
+
+- SDS provides Tailwind configuration - use it as the foundation
+- SDS classes take precedence over generic Tailwind classes
+- Use SDS breakpoints for responsive design
+
+### With React Frameworks
+
+- SDS components work with Next.js, React Router, etc.
+- Use SDS Link component for navigation when possible
+- Maintain SDS patterns in framework-specific code
+
+## Best Practices Summary
+
+1. **Component First**: Always check if SDS has a component before building custom
+2. **Tokens Always**: Use SDS design tokens (spacing, colors, typography) consistently
+3. **Props Over Classes**: Use SDS-specific props rather than overriding with classes
+4. **Accessibility Built-in**: Leverage SDS components' accessibility features
+5. **Dark Mode Ready**: Always include dark mode color variants
+6. **TypeScript Friendly**: Use SDS TypeScript interfaces and types
+7. **Test Integration**: Focus tests on business logic, rely on SDS component testing

package/data/resources/zeroheight-rules.md

@@ -0,0 +1,180 @@
+# Zeroheight Documentation Adherence Rules
+
+These rules guide Claude Code when using Zeroheight documentation to ensure accurate implementation of the CZI Science Design System (SDS).
+
+## Documentation as Source of Truth
+
+### Component Usage Guidelines
+
+- **Always reference Zeroheight documentation** for component usage guidelines
+- Follow documented usage patterns and restrictions
+- Respect component do's and don'ts specified in documentation
+- Use documented prop combinations and avoid deprecated patterns
+
+### API Documentation Priority
+
+- **Zeroheight component documentation overrides assumptions**
+- Check documented prop options before implementing
+- Follow documented accessibility requirements
+- Use documented examples as implementation templates
+
+## Component Implementation Rules
+
+### Props and Configuration
+
+- **Use only documented prop values** and combinations
+- Follow documented prop hierarchies (e.g., `sdsStyle` + `sdsType` combinations)
+- Respect documented prop requirements (required vs optional)
+- Check Zeroheight for component-specific prop validation rules
+
+### Usage Patterns
+
+- **Follow documented composition patterns**:
+  - How components should be combined (e.g., Button + Icon)
+  - Proper nesting relationships (e.g., AccordionHeader in Accordion)
+  - Layout recommendations for component groups
+
+### Accessibility Requirements
+
+- **Implement documented accessibility patterns**
+- Use documented ARIA patterns and labels
+- Follow documented keyboard navigation requirements
+- Implement documented focus management patterns
+
+## Content and Copy Guidelines
+
+### Terminology
+
+- **Use SDS-approved terminology** from Zeroheight glossary
+- Follow documented naming conventions for UI elements
+- Use consistent language patterns across components
+- Respect documented content guidelines (e.g., button text patterns)
+
+### Microcopy Standards
+
+- **Follow documented content standards** for:
+  - Error messages and validation text
+  - Placeholder text patterns
+  - Help text and tooltips
+  - Loading and empty states
+
+## Visual Implementation
+
+### Design Specifications
+
+- **Extract exact specifications** from Zeroheight:
+  - Spacing measurements and relationships
+  - Typography specifications
+  - Color usage in different contexts
+  - Component states and variations
+
+### Responsive Behavior
+
+- **Implement documented responsive patterns**
+- Follow documented breakpoint behavior
+- Use documented mobile adaptations
+- Implement documented touch interaction patterns
+
+## Integration Guidelines
+
+### Framework Integration
+
+- **Follow documented framework-specific guidance**
+- Use documented integration patterns for React/Next.js
+- Implement documented data binding patterns
+- Follow documented performance recommendations
+
+### State Management
+
+- **Implement documented state patterns**:
+  - Form state management recommendations
+  - Loading and error state handling
+  - User interaction state patterns
+  - Data validation approaches
+
+## Quality Assurance
+
+### Implementation Validation
+
+- **Cross-reference implementation with Zeroheight examples**
+- Verify component behavior matches documented examples
+- Test edge cases mentioned in documentation
+- Validate accessibility implementation against documented requirements
+
+### Documentation Gaps
+
+- **When documentation is unclear or missing**:
+  - Use SDS Storybook as secondary reference
+  - Follow established SDS patterns from similar components
+  - Document any assumptions made for future clarification
+  - Prefer conservative/minimal implementations
+
+## Best Practices
+
+### Documentation Workflow
+
+1. **Always check Zeroheight first** before implementing any SDS component
+2. **Read the full component documentation** including usage guidelines
+3. **Review examples and code snippets** provided in documentation
+4. **Check for any usage restrictions** or warnings
+5. **Validate implementation** against documented examples
+
+### Staying Current
+
+- **Documentation updates**: Assume Zeroheight content is most current
+- **Version compatibility**: Check documented version compatibility
+- **Deprecation notices**: Follow documented migration paths for deprecated patterns
+- **New features**: Use documented new features rather than workarounds
+
+### Implementation Priority Order
+
+1. **Zeroheight documentation** (primary source of truth)
+2. **SDS Storybook** (implementation examples and edge cases)
+3. **TypeScript interfaces** (technical prop definitions)
+4. **Existing codebase patterns** (established usage in project)
+
+## Common Documentation Patterns
+
+### Component Pages Structure
+
+- **Overview**: Component purpose and when to use
+- **Usage Guidelines**: Do's and don'ts with examples
+- **Props/API**: Detailed prop documentation
+- **Examples**: Code snippets and live examples
+- **Accessibility**: ARIA patterns and keyboard navigation
+- **Related Components**: Integration recommendations
+
+### Information Hierarchy
+
+- **Design Guidelines** → Visual specifications and usage
+- **Development Guidelines** → Implementation requirements
+- **Accessibility Guidelines** → WCAG compliance patterns
+- **Content Guidelines** → Copy and terminology standards
+
+## Troubleshooting with Documentation
+
+### When Implementation Doesn't Match Design
+
+1. **Check Zeroheight for variant documentation**
+2. **Look for conditional usage patterns**
+3. **Verify responsive behavior specifications**
+4. **Check for theme-specific implementations**
+
+### When Behavior Seems Unexpected
+
+1. **Review documented component lifecycle**
+2. **Check for documented state management patterns**
+3. **Verify prop combination compatibility**
+4. **Look for documented browser-specific considerations**
+
+## Documentation-Driven Development
+
+### Implementation Process
+
+1. **Read documentation thoroughly** before writing code
+2. **Plan implementation** based on documented patterns
+3. **Code with documentation open** for reference
+4. **Test against documented examples**
+5. **Document any deviations** with rationale
+
+This ensures all SDS implementations are consistent with the official design system documentation and reduces implementation errors.

package/data/zeroheight-cache.json

@@ -5191,5 +5191,5 @@
       "lastUpdated": "2025-07-07T20:31:06.751Z"
     }
   },
-  "lastFetch": "2025-08-20T17:39:49.547Z"
+  "lastFetch": "2025-08-21T19:18:43.698Z"
 }

package/data/zeroheight-exports/README.md

@@ -1,6 +1,6 @@
 # Exported Zeroheight Pages
 
-Generated on: 2025-08-20T17:39:49.546Z
+Generated on: 2025-08-21T19:18:43.696Z
 Styleguide ID: 66099
 Total files exported: 56
 Total pages combined: 164

package/dist/stdio.js

@@ -2,8 +2,8 @@
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
-import fs from 'fs';
-import path from 'path';
+import fs, { readFileSync } from 'fs';
+import path, { dirname as dirname$1, join } from 'path';
 import { fileURLToPath } from 'url';
 
 var server = new McpServer({
@@ -11,7 +11,10 @@ var server = new McpServer({
   version: "0.1.0",
   capabilities: {
     prompts: {},
-    resources: {},
+    resources: {
+      subscribe: true,
+      listChanged: true
+    },
     tools: {}
   }
 });
@@ -759,10 +762,96 @@ var initializeTools = async (server2, config) => {
     })
   );
 };
+var FILENAME = fileURLToPath(import.meta.url);
+var DIRNAME = dirname$1(FILENAME);
+var dataDir = join(DIRNAME, "../../data/resources");
+var MIME_TYPE_MARKDOWN = "text/markdown";
+var UNKNOWN_ERROR = "Unknown error";
+function initializeResources(server2) {
+  server2.resource(
+    "Figma to Code Translation Rules",
+    "sds://rules/figma",
+    {
+      mimeType: MIME_TYPE_MARKDOWN,
+      description: "Rules for translating Figma designs to SDS code"
+    },
+    async () => {
+      try {
+        const filePath = join(dataDir, "figma-rules.md");
+        const content = readFileSync(filePath, "utf-8");
+        return {
+          contents: [
+            {
+              uri: "sds://rules/figma",
+              mimeType: MIME_TYPE_MARKDOWN,
+              text: content
+            }
+          ]
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : UNKNOWN_ERROR;
+        throw new Error("Failed to read Figma rules: " + message);
+      }
+    }
+  );
+  server2.resource(
+    "SDS Component Usage Rules",
+    "sds://rules/components",
+    {
+      mimeType: MIME_TYPE_MARKDOWN,
+      description: "Guidelines for using SDS components correctly"
+    },
+    async () => {
+      try {
+        const filePath = join(dataDir, "sds-component-rules.md");
+        const content = readFileSync(filePath, "utf-8");
+        return {
+          contents: [
+            {
+              uri: "sds://rules/components",
+              mimeType: MIME_TYPE_MARKDOWN,
+              text: content
+            }
+          ]
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : UNKNOWN_ERROR;
+        throw new Error("Failed to read component rules: " + message);
+      }
+    }
+  );
+  server2.resource(
+    "Zeroheight Documentation Rules",
+    "sds://rules/zeroheight",
+    {
+      mimeType: MIME_TYPE_MARKDOWN,
+      description: "Rules for following Zeroheight documentation"
+    },
+    async () => {
+      try {
+        const filePath = join(dataDir, "zeroheight-rules.md");
+        const content = readFileSync(filePath, "utf-8");
+        return {
+          contents: [
+            {
+              uri: "sds://rules/zeroheight",
+              mimeType: MIME_TYPE_MARKDOWN,
+              text: content
+            }
+          ]
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : UNKNOWN_ERROR;
+        throw new Error("Failed to read Zeroheight rules: " + message);
+      }
+    }
+  );
+}
 
 // src/stdio.ts
 async function main() {
   await initializeTools(server, {});
+  initializeResources(server);
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@czi-sds/mcp",
   "description": "The official MCP server for SDS",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "main": "dist/stdio.js",
   "files": [
     "dist",
@@ -62,5 +62,5 @@
     "tsx": "^4.20.3",
     "typescript": "^5.9.2"
   },
-  "gitHead": "1545afb7ac457bc1dab40856fe5d5b7e22186318"
+  "gitHead": "0d113d49faf2a30e2a557450cf2deaecf830656b"
 }