macOS Voice Dictionary Generator

A specialized skill for working with a dictionary project that generates vCard (.vcf) files to improve Japanese voice recognition on macOS. The system leverages how macOS voice input uses contacts from the Contacts app to create custom dictionaries for technical terms and programming vocabulary.

Architecture Understanding

This is a React Router v7 SPA that:

**Key directories:**

**vCard Output Format:**

Development Workflow

When making changes to this codebase:

1. **Before modifying dictionary files**, read `dictionaries/README.md` for:

- File naming conventions (`{category}-{domain}.csv`)

- Content policies

- Format guidelines

2. **Available commands:**

- `npm run dev` - Start development server

- `npm run build` - Build for production (GitHub Pages at `/dictionary.vcf/`)

- `npm run typecheck` - Run TypeScript type checking

- `npm run preview` - Preview production build locally

- `npm start` - Start production server

3. **When working with vCard output:**

- Check `docs/vcf-format.md` for format specification and examples

- Ensure vCard files follow macOS Contacts compatibility requirements

4. **Deployment considerations:**

- Production builds use base path `/dictionary.vcf/` (configured in `vite.config.ts`)

- Target deployment platform is GitHub Pages

Common Tasks

Adding/Modifying Dictionary Entries

1. Read `dictionaries/README.md` for guidelines

2. Locate or create appropriate CSV file in `dictionaries/`

3. Follow format: word-pronunciation pairs

4. Test generation by running dev server and checking output

Updating React Components

1. Navigate to `app/` directory

2. Make changes to React Router v7 components

3. Run `npm run typecheck` to verify types

4. Test with `npm run dev`

Adjusting vCard Output

1. Reference `docs/vcf-format.md` for format requirements

2. Locate vCard generation logic in application code

3. Ensure `FN` and `X-PHONETIC-LAST-NAME` fields are properly formatted

4. Test output can be imported into macOS Contacts

Deployment

1. Run `npm run build` to create production bundle

2. Verify base path configuration in `vite.config.ts` (`/dictionary.vcf/`)

3. Deploy `dist/` contents to GitHub Pages

Important Constraints

Examples

**Adding a new programming terms dictionary:**

```bash

1. Create new CSV file following naming convention

dictionaries/programming-javascript.csv

2. Add word-pronunciation pairs in CSV format

3. Test generation

npm run dev

4. Verify vCard output can be imported to Contacts

```

**Modifying the React UI:**

```bash

1. Navigate to component in app/

2. Make changes

npm run typecheck

npm run dev

3. Build and preview

npm run build

npm run preview

```