Guidelines

Best practices and standards for contributing components to Shades By Jay.

Why Guidelines Matter

Following consistent guidelines ensures that all components in our library maintain high quality, work well together, and provide the best experience for developers using them.

Code Standards

HTML Best Practices

  • Use semantic HTML elements when appropriate
  • Keep markup clean and minimal
  • Use meaningful class names (e.g., .btn-primary not .b1)
  • Avoid inline styles - use CSS classes instead
  • Ensure proper nesting and indentation
  • Include necessary ARIA attributes for accessibility

CSS Best Practices

  • Use unique, descriptive class names to avoid conflicts
  • Avoid using IDs for styling
  • Keep specificity low when possible
  • Use CSS custom properties for colors when helpful
  • Include hover and focus states
  • Use relative units (rem, em, %) for sizing

Avoid

  • JavaScript dependencies (keep it CSS-only)
  • External image URLs that might break
  • Vendor prefixes (they're added automatically)
  • !important declarations unless absolutely necessary
  • Fixed pixel widths that break responsiveness

Naming Conventions

Good Examples

.btn-gradient-glow .card-profile .loader-dots .switch-ios .input-floating-label

Bad Examples

.btn1 .myCard .x .component .style
Naming Pattern: Use the format [component-type]-[descriptor] for clarity. For example: btn-neon, card-glass, loader-pulse.

Accessibility

Making components accessible ensures everyone can use them. Follow these guidelines:

Color Contrast

Ensure text has sufficient contrast against backgrounds. Aim for WCAG AA compliance (4.5:1 for normal text, 3:1 for large text).

Focus States

All interactive elements should have visible focus indicators. Never remove outlines without providing an alternative.

.btn:focus { outline: 2px solid var(--primary); outline-offset: 2px; }

Interactive Elements

Use appropriate HTML elements:

  • Use <button> for clickable actions
  • Use <a> for navigation links
  • Use <input> for form inputs

Responsiveness

Components should work well on all screen sizes:

Flexible Sizing

Use relative units and flexible layouts that adapt to container width.

Readable Text

Ensure text remains readable at all sizes. Use rem for font sizes.

Touch Friendly

Make touch targets at least 44x44 pixels for mobile users.

Animation Guidelines

Performance

  • Animate only transform and opacity for best performance
  • Keep animations under 300ms for UI feedback
  • Use will-change sparingly
  • Avoid animating layout properties (width, height, top, left)

Motion Preferences

Respect users who prefer reduced motion:

@media (prefers-reduced-motion: reduce) { .animated-element { animation: none; transition: none; } }

Submission Checklist

Before submitting a component, make sure it meets all these criteria:

Submit Your Component