GitHub Copilot Rules for UnoCSS Inspector

Project Context

This is a Vue 3 + TypeScript project for a UnoCSS Inspector tool that allows developers to inspect and analyze UnoCSS classes and styles on web elements.

Code Style Guidelines

General Principles

• Use TypeScript for all new code
• Follow Vue 3 Composition API patterns
• Use <script setup> syntax for Vue components
• Prefer explicit type annotations over any
• Use ESLint and follow the existing linting rules

Vue Component Patterns

• Use defineModel<T>() with TypeScript interfaces for modelValue
• Use defineProps<T>() with TypeScript interfaces for props
• Use defineEmits<T>() for component events
• Prefer ref() and reactive() over data() options
• Use computed() for derived state
• Use watch() and watchEffect() for side effects

State Management

• Use provide/inject pattern for sharing state between components
• Use the useElement() composable for accessing current element context
• Avoid prop drilling - prefer injection for deeply nested data

Naming Conventions

• Use camelCase for variables and functions
• Use PascalCase for Vue components
• Use kebab-case for CSS classes and file names
• Prefix composables with use (e.g., useElement, useTabs)

Import Organization

• Group imports by: Vue imports, external libraries, internal composables, components
• Use relative imports for local files
• Sort imports alphabetically within each group

Architecture Guidelines

Component Structure

<script setup lang="ts">
// 1. Imports (Vue, external libs, composables, components)
// 2. ModelValue, Props and emits definitions
// 3. Reactive state
// 4. Computed properties
// 5. Methods/functions
// 6. Lifecycle hooks
// 7. Event listeners
</script>

<template>
  <div>
    <!-- Use semantic HTML and accessibility attributes -->
  </div>
</template>

<style scoped>
  /* Use CSS custom properties for theming */
  /* Follow existing color scheme patterns */
</style>

Composables

• Keep composables focused on single responsibilities
• Return objects with named properties, not arrays
• Use TypeScript interfaces for return types
• Include proper error handling

File Organization

• Components in /src/components/
• Composables in /src/composables/
• Types in /src/types/
• Icons in /src/icons/

Performance Guidelines

• Use v-memo for expensive computations in templates
• Prefer shallowRef() for large objects that don't need deep reactivity
• Use markRaw() for non-reactive objects
• Implement proper cleanup in onUnmounted()

Error Handling

• Provide meaningful error messages
• Use try-catch blocks for DOM operations
• Validate props and inject dependencies
• Handle edge cases gracefully

Testing Considerations

• Write testable code with clear separation of concerns
• Mock external dependencies
• Test both happy path and error scenarios
• Use descriptive test names

CSS and Styling

• Use scoped styles by default
• Follow the existing CSS custom property naming
• Use CSS Grid/Flexbox for layouts
• Maintain consistent spacing and typography scales

Browser Compatibility

• Target modern browsers (ES2020+)
• Use progressive enhancement for advanced features
• Test cross-browser compatibility for DOM manipulation

Documentation

• Use JSDoc comments for public APIs
• Include usage examples in complex composables
• Document component props and events
• Keep README.md updated with setup instructions

Security

• Sanitize user inputs
• Be careful with innerHTML - prefer textContent
• Validate data from external sources
• Use Content Security Policy friendly practices

Don't Do

• Don't use any type unless absolutely necessary
• Don't mutate props directly
• Don't use global variables
• Don't ignore TypeScript errors
• Don't use document.querySelector without proper guards
• Don't forget to clean up event listeners
• Don't use !important in CSS unless necessary
• Don't hardcode magic numbers or strings