@czi-sds/mcp 0.3.0 → 0.5.0

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"
 }