Best Practices

Use this skill for guidance on developing with @inkcre/web-design.

Component Development

1. Single Responsibility: Each component does one thing well
2. High Cohesion, Low Coupling: Keep related code together, minimize dependencies
3. Clear API: Props and events should be intuitive
4. Avoid Prop Drilling: Use provide/inject for deeply nested data
5. Testable: Write components that are easy to test

Naming Conventions

• Components: camelCase (e.g., inkButton)
• CSS Classes: kebab-case (e.g., ink-button)
• Props/Variables: camelCase (e.g., isLoading)
• Events: kebab-case (e.g., update:modelValue)

Error Handling

• Use graceful degradation
• Provide user-friendly error messages
• Log errors appropriately
• Validate inputs and provide defaults

Accessibility

• Use semantic HTML elements
• Provide ARIA labels where needed
• Ensure keyboard navigation works
• Test with screen readers
• Maintain proper color contrast

Performance

• Use v-if vs v-show appropriately
• Avoid unnecessary watchers
• Use computed for derived state
• Lazy load components when possible
• Optimize large lists with virtual scrolling

Code for Human Brains

Write code that's easy to understand:

• Keep it simple: Prefer straightforward solutions
• Limit cognitive load: Keep functions simple (≤4 concepts to hold in memory)
• Use meaningful names: Variables should be self-documenting
• Prefer early returns: Avoid deeply nested conditions
• Comment the "why": Explain motivation, not just what

Example

❌ Hard to understand:

if (val > someConstant && (condition2 || condition3) && (condition4 && !condition5)) {
  // What are we checking?
}

✅ Easy to understand:

const isValid = val > someConstant;
const isAllowed = condition2 || condition3;
const isSecure = condition4 && !condition5;

if (isValid && isAllowed && isSecure) {
  // Clear what each condition means
}