# Components

Gears provides a foundation for building reusable UI components using the BEM (Block-Element-Modifier) naming convention. Components are self-contained, modular pieces of UI that can be easily dropped into any part of your application.

## General Approach

-   **BEM Naming**: All components should follow the BEM naming convention for their classes (e.g., `.block`, `.block__element`, `.block--modifier`). This ensures clarity, modularity, and reduces the likelihood of CSS conflicts.
-   **Theming**: Components should leverage CSS custom properties (defined in `css.config.json`) for their styling, allowing them to automatically adapt to the active theme.
-   **Composition**: Components are designed to be composed with utility classes for additional styling needs (e.g., spacing, alignment) without modifying the component's core CSS.
-   **Accessibility**: Focus on semantic HTML and include accessibility considerations like focus states.

## Example Components

### Button (`src/components/button.css`)

The `btn` component is a basic interactive element. It demonstrates how to use design tokens for `font-family`, `background`, `color`, `padding`, and `border-radius`.

#### CSS

```css
.btn {
  font-family: var(--g-font-base);
  background: var(--g-colors-primary);
  color: var(--g-colors-text-on-primary, #fff); /* Fallback for text color on primary */
  padding: var(--g-space-2);
  border-radius: var(--g-radius-md);
  display: inline-flex;
  gap: 0.5rem;
  align-items: center;
  border: none;
  cursor: pointer;
}

.btn__icon { display: inline-block; }

.btn--ghost {
  background: transparent;
  border: 1px solid currentColor;
  color: var(--g-colors-primary);
}
```

#### HTML Usage

```html
<button class="btn">Default Button</button>
<button class="btn btn--ghost">Ghost Button</button>
<button class="btn g-m-2 g-p-3">Button with Utilities</button>
<button class="btn">
  <span class="btn__icon">&#9733;</span>
  Button with Icon
</button>
```

### Card (`src/components/card.css`)

The `card` component is a flexible container for grouping related content. It showcases the use of background, text color, border-radius, padding, and shadow tokens.

#### CSS

```css
.card {
  background: var(--g-colors-bg);
  color: var(--g-colors-text);
  border-radius: var(--g-radius-md);
  padding: var(--g-space-4);
  box-shadow: 0 2px 4px rgba(0,0,0,0.1);
}

.card__header {
  font-size: 1.2em;
  margin-bottom: var(--g-space-2);
}

.card__body {
  line-height: 1.6;
}

.card--compact {
  padding: var(--g-space-2);
}
```

#### HTML Usage

```html
<div class="card">
  <div class="card__header">Card Title</div>
  <div class="card__body">This is the main content of the card.</div>
</div>

<div class="card card--compact g-m-4">
  <div class="card__header">Compact Card</div>
  <div class="card__body">A smaller version of the card, with some margin.</div>
</div>
```

## Creating New Components

When creating new components, follow these guidelines:

1.  **Create a new CSS file** in the `src/components/` directory (e.g., `src/components/my-component.css`).
2.  **Define your component's styles** using BEM naming conventions.
3.  **Utilize CSS custom properties** (e.g., `var(--g-colors-primary)`) for all design-related values to ensure theme compatibility.
4.  **Import your new component's CSS** into `src/index.css` in the `/* 6. components */` section.
5.  **Consider accessibility** from the start, including keyboard navigation and focus states.