Style guide

Code style

We follow modern JavaScript and TypeScript conventions while prioritizing accessibility and performance. Our code style ensures consistency and maintainability across all projects.

TypeScript

Use TypeScript for type safety and better developer experience. Document your interfaces and types with JSDoc comments:

/**
 * Button Component Props
 *
 * @description Props interface for the Button component
 */
interface ButtonProps {
  /** The button's label text */
  label: string;
  /** Optional click handler */
  onClick?: () => void;
  /** Visual style variant */
  variant?: 'primary' | 'secondary';
}

Component structure

Components should follow this structure:

---
/**
 * Component Name
 *
 * @description Brief description of the component's purpose
 */
interface Props {
  /** Prop description */
  propName: string;
}

const { propName } = Astro.props
---

<component-root>
  <slot />
</component-root>

<style>
  /* Component styles */
</style>

CSS guidelines

We use modern CSS features with a focus on accessibility:

/* Use logical properties */
.component {
  /* Layout */
  display: flex;
  flex-direction: column;
  gap: 0.5rem;

  /* Spacing */
  margin-block: 1rem;
  padding-inline: 1rem;

  /* Colors */
  color: light-dark(hsl(0 0% 10%), hsl(0 0% 90%));

  /* Transitions */
  @media (prefers-reduced-motion: no-preference) {
    transition: transform 0.2s ease;
  }
}

/* Use :where() for lower specificity */
:where(.component:hover) {
  transform: scale(1.02);
}

Documentation

Clear documentation helps others understand and use our code:

Component documentation

/**
 * Button Component
 *
 * @description A reusable button component with various styles and states
 * @example
 * ```astro
 * <Button variant="primary">Click me</Button>
 * ```
 */

Props documentation

interface Props {
  /** Additional classes to apply */
  class?: string;
  /** Visual style variant */
  variant?: 'primary' | 'secondary';
  /** Whether the button is disabled */
  disabled?: boolean;
}

Accessibility

Ensure all components are accessible:

Semantic HTML
- Use proper heading levels
- Use semantic elements (<button>, <nav>, etc.)
- Provide proper landmarks
ARIA attributes
- Add aria-label when needed
- Use aria-expanded for toggles
- Include aria-current for navigation
Keyboard navigation
- Ensure proper focus states
- Support arrow key navigation
- Implement focus traps when needed
Visual considerations
- Maintain sufficient color contrast
- Support reduced motion
- Provide visible focus indicators

Git workflow

Commit messages

Follow conventional commits:

# Format
type(scope): description

# Examples
feat(button): add loading state
fix(modal): improve keyboard navigation
docs(readme): update installation steps

Branch naming

Use descriptive branch names:

# Format
type/description

# Examples
feat/add-button-component
fix/modal-focus-trap
docs/improve-examples