> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mantle.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# Best Practices

> Guidelines and principles

Learn the core principles for building consistent, accessible interfaces.

## Quick Start

<Steps>
  <Step title="Install Dependencies">
    Add Spartan UI and required dependencies to your Angular project.

    ```bash theme={null}
    ng add @spartan-ng/cli
    ```
  </Step>

  <Step title="Configure Tailwind">
    Set up Tailwind CSS with our design tokens and theme configuration.

    ```bash theme={null}
    npx @spartan-ng/cli@latest add ui-button
    ```
  </Step>

  <Step title="Start Building">
    Import components and start building with our design system.

    ```typescript theme={null}
    import { HlmButtonDirective } from "@spartan-ng/helm/button"
    ```
  </Step>
</Steps>

## Design Principles

<CardGroup cols={2}>
  <Card title="Consistency" icon="equals">
    Maintain visual and functional consistency across all components and interactions.

    * Use the same colors from our palette
    * Apply consistent spacing scale
    * Follow typography hierarchy
  </Card>

  <Card title="Accessibility" icon="universal-access">
    Ensure all components are accessible by default with proper ARIA labels and keyboard navigation.

    * WCAG AA contrast ratios
    * Keyboard navigation support
    * Screen reader compatibility
  </Card>

  <Card title="Performance" icon="gauge-high">
    Optimize components for fast loading and smooth interactions.

    * Lazy load heavy components
    * Optimize bundle sizes
    * Use Angular signals for reactivity
  </Card>

  <Card title="Flexibility" icon="layer-group">
    Build components that can adapt to different contexts and use cases.

    * Responsive by default
    * Dark mode support
    * Customizable with variants
  </Card>
</CardGroup>

## Implementation Tips

<AccordionGroup>
  <Accordion title="Always use Spartan UI components first" icon="check">
    Check if a component exists in `@spartan-ng` before creating custom ones. This ensures consistency and reduces maintenance burden.
  </Accordion>

  <Accordion title="Use semantic color tokens" icon="palette">
    Use `foreground`, `background`, `primary`, etc. instead of hard-coded colors. This ensures proper dark mode support
    and maintainability.
  </Accordion>

  <Accordion title="Follow the spacing scale" icon="ruler">
    Use Tailwind's spacing utilities (`p-4`, `m-2`, `gap-6`) for consistent spacing throughout the application.
  </Accordion>

  <Accordion title="Test in both light and dark modes" icon="circle-half-stroke">
    Ensure your components look good in both themes. Always test with the theme toggle to catch any issues.
  </Accordion>

  <Accordion title="Mobile-first responsive design" icon="mobile">
    Design for mobile by default, then enhance for larger screens with `md:`, `lg:` prefixes.
  </Accordion>
</AccordionGroup>

## Code Examples

### Using Color Tokens

```html theme={null}
<!-- Correct: Use semantic tokens -->
<div class="bg-card text-card-foreground border border-border">Content</div>

<!-- Incorrect: Hard-coded colors -->
<div class="bg-white text-gray-900 border border-gray-200">Content</div>
```

### Responsive Design

```html theme={null}
<!-- Mobile-first approach -->
<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
  <Card />
  <Card />
  <Card />
</div>
```

### Dark Mode Support

```html theme={null}
<!-- Automatic dark mode with semantic tokens -->
<div class="bg-background text-foreground">
  <!-- Uses light colors in light mode, dark colors in dark mode -->
</div>

<!-- Manual dark mode override when needed -->
<div class="bg-white dark:bg-gray-900">Content</div>
```

## Checklist

Before shipping any feature, ensure you've covered:

<Checklist>
  * [ ] Components use Spartan UI when available - \[ ] Colors use semantic tokens (not hard-coded values) - \[ ] Layout
    is responsive (mobile-first) - \[ ] Dark mode works correctly - \[ ] Accessibility requirements met (WCAG AA) - \[ ]
    Loading states implemented - \[ ] Error states handled - \[ ] Touch targets are 44px minimum
</Checklist>