npm package: @hugodouchet/design-kit
Description: A customizable design kit for SvelteKit with CSS variables and RGAA accessibility
Author: Hugo Douchet
Latest version: 0.3.3

# Design Kit

A customizable design kit for SvelteKit with Tailwind CSS, providing a set of reusable and easily customizable components following RGAA accessibility standards.

## Features

- 🎨 **Svelte 5** - Built with the latest Svelte 5 runes syntax
- 🎯 **TypeScript** - Fully typed components
- 🌊 **Tailwind CSS v4** - Using the new CSS-first configuration
- ♿ **RGAA Accessible** - Follows French accessibility guidelines (WCAG 2.1 Level AA equivalent)
- 📚 **Storybook** - Interactive component documentation
- 📦 **NPM Package** - Easy to install and use in your projects

## Installation

```bash
npm install @yourscope/design-kit
```

## Prerequisites

This package requires:
- Svelte 5+
- SvelteKit 2+
- Tailwind CSS 4.0+

## Configuration

### 1. Install Tailwind CSS v4 in your project

If not already installed:

```bash
npm install -D tailwindcss@next @tailwindcss/vite@next
```

### 2. Configure Vite

Update your `vite.config.js` to add the Tailwind plugin:

```js
import { sveltekit } from '@sveltejs/kit/vite';
import tailwindcss from '@tailwindcss/vite';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [sveltekit(), tailwindcss()]
});
```

### 3. Import Tailwind in your application

In your `src/app.css` file:

```css
@import 'tailwindcss';
```

Then import this file in your root layout (`src/routes/+layout.svelte`):

```svelte
<script>
  import '../app.css';
</script>

<slot />
```

## Usage

### Basic Usage

```svelte
<script>
  import { Button } from '@yourscope/design-kit';
</script>

<Button>My Button</Button>
```

### With label prop

```svelte
<Button label="My Button" />
```

### Disabled button

```svelte
<Button disabled>Disabled</Button>
```

### With event handler

```svelte
<script>
  function handleClick() {
    console.log('Button clicked!');
  }
</script>

<Button onclick={handleClick}>Click me</Button>
```

### Button types

```svelte
<Button type="submit">Submit</Button>
<Button type="reset">Reset</Button>
```

## Customization

Currently, the Button uses a simple black background with white text style. Token-based customization will be added in future versions.

## Available Components

### Button

A simple button with black background and white text.

**Props:**

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `label` | `string` | - | Button text label (alternative to children) |
| `disabled` | `boolean` | `false` | Disables the button |
| `type` | `'button' \| 'submit' \| 'reset'` | `'button'` | HTML button type |
| `onclick` | `(event: MouseEvent) => void` | - | Click event handler |
| `children` | `Snippet` | - | Button content (slot) |

**Accessibility:**
- Uses semantic `<button>` element (RGAA 7.1)
- Includes `aria-disabled` attribute for screen readers (RGAA 7.1)
- Visible focus indicator with ring (RGAA 10.7)
- Keyboard accessible by default (RGAA 12.8)

## Development

### Install dependencies

```bash
npm install
```

**Note**: A `prepare` script automatically runs after installation to generate necessary SvelteKit files (`svelte-kit sync`).

### Run Storybook

```bash
npm run storybook
```

Storybook will be accessible at `http://localhost:6006` and allows you to view and test all components.

**Accessibility Testing**: Storybook includes the **a11y addon** which automatically checks for accessibility issues using axe-core. Click on the "Accessibility" tab in any story to view:
- ✅ Violations (must be fixed)
- ⚠️ Incomplete checks (need manual verification)
- ✅ Passes (all good!)

**Tip**: If you encounter errors on first launch, make sure SvelteKit configuration files have been generated by running:

```bash
npm run prepare
```

### Build the package

```bash
npm run build
```

### Publish to npm

1. Update the version in `package.json`
2. Change the package name from `@yourscope/design-kit` to your npm scope
3. Login to npm: `npm login`
4. Publish: `npm publish --access public`

## Troubleshooting

### Error: Cannot find base config file "./.svelte-kit/tsconfig.json"

This error occurs when SvelteKit configuration files haven't been generated. Solution:

```bash
npm run prepare
```

or

```bash
npx svelte-kit sync
```

### Storybook won't start

If Storybook doesn't start properly:

1. Verify all dependencies are installed: `npm install`
2. Generate SvelteKit files: `npm run prepare`
3. Restart Storybook: `npm run storybook`

### Error with Tailwind CSS v4

Make sure you have the correct versions installed:

```bash
npm install -D tailwindcss@next @tailwindcss/vite@next
```

And that your `vite.config.js` contains the Tailwind plugin:

```js
import tailwindcss from '@tailwindcss/vite';
plugins: [sveltekit(), tailwindcss()]
```

## Accessibility (RGAA)

This design kit follows **RGAA 4.1** standards (French accessibility guidelines equivalent to WCAG 2.1 Level AA).

### Key Accessibility Features

- **Semantic HTML**: All components use appropriate HTML elements
- **ARIA Attributes**: Screen reader support with proper ARIA attributes
- **Keyboard Navigation**: All interactive elements are keyboard accessible
- **Focus Indicators**: Visible focus indicators for keyboard users
- **Color Contrast**: Text meets minimum contrast ratios (4.5:1)

### RGAA Compliance

| Component | RGAA Criteria | Status |
|-----------|---------------|--------|
| Button | 7.1, 10.7, 12.8 | ✅ Compliant |

For more information on RGAA: https://accessibilite.numerique.gouv.fr/

## Contributing

Please read `AGENTS.md` for guidelines on:
- Code style and conventions
- Accessibility requirements (RGAA)
- Language requirements (English)
- Component structure
- Testing procedures

## License

MIT