### Module Name Examples

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/types.md

Illustrates example string values for the ModuleName type.

```plaintext
- "Add"
- "CheckmarkFilled"
- "ArrowRight"
- "StatusGlyph"

```

--------------------------------

### Install carbon-icons-svelte

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/README.md

Install the library using npm, pnpm, Yarn, or Bun.

```sh
# npm
npm i carbon-icons-svelte

# pnpm
pnpm i carbon-icons-svelte

# Yarn
yarn add carbon-icons-svelte

# Bun
bun add carbon-icons-svelte
```

--------------------------------

### Clone and Setup Repository

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/CONTRIBUTING.md

Clone the Carbon Icons Svelte repository and set up the upstream remote for future synchronization.

```bash
git clone <YOUR_FORK>
cd carbon-icons-svelte
git remote add upstream git@github.com:carbon-design-system/carbon-icons-svelte.git
git remote -v
```

--------------------------------

### TypeScript Import Examples with Path Aliases

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/configuration.md

Demonstrates how path aliases resolve imports for 'carbon-icons-svelte' and its submodules.

```typescript
// Both resolve to ./lib during development
import { Add } from "carbon-icons-svelte";
import Add from "carbon-icons-svelte/lib/Add.svelte";
```

--------------------------------

### Main Package Usage Example (TypeScript)

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/api-reference/module-graph.md

Demonstrates how to import icon components and their types from the main package entry point in a TypeScript project.

```typescript
import { Add, CheckmarkFilled } from "carbon-icons-svelte";
import type { CarbonIconProps } from "carbon-icons-svelte";
```

--------------------------------

### Release Process Steps

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/CONTRIBUTING.md

Steps for maintainers to prepare and publish a new release, including installing dependencies, building, committing, tagging, and pushing.

```bash
# 1. Install and re-build the library.
bun install; bun prepack;

# 2. Commit the changes using the new version as the commit message.
git commit -am "v12.3.0"

# 3. Create a tag.
git tag v12.3.0

# 4. Push the tag to the remote.
# This will trigger the `release.yml` workflow to publish a new package to NPM (with provenance).
git push origin v12.3.0
```

--------------------------------

### Icon Button Example

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/REFERENCE-GUIDE.md

Combine an icon with text to create an interactive button. Ensure the icon is appropriately sized for the button.

```svelte
<script>
  import Add from "carbon-icons-svelte/lib/Add.svelte";
</script>

<button>
  <Add size={20} />
  Add Item
</button>
```

--------------------------------

### Accessibility Examples

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/REFERENCE-GUIDE.md

Demonstrates how to ensure icons are accessible to screen readers and keyboard users by utilizing ARIA attributes and the title element.

```APIDOC
## Accessibility

Icons automatically adapt based on context:

**Labelled icons (screen-reader accessible):**
```svelte
<Add aria-label="Add new item" />
<!-- role="img", not aria-hidden -->

<Add aria-labelledby="button-label" />
<!-- role="img", not aria-hidden -->

<Add title="Add new item" />
<!-- <title> element included -->
```

**Unlabelled icons (decorative):**
```svelte
<Add />
<!-- aria-hidden="true", no role -->
```

**Focusable icons (for keyboard interaction):**
```svelte
<Add aria-label="Add new item" tabindex={0} />
<!-- focusable attribute set to true -->
```
```

--------------------------------

### Direct Import Type Definition Example

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/api-reference/module-graph.md

Shows the type definition for an icon component when imported directly from its file path.

```typescript
import Add from "carbon-icons-svelte/lib/Add.svelte";
// Type: Component<CarbonIconProps>
```

--------------------------------

### Direct Component Import Example

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/configuration.md

Imports a specific icon component directly. This is the recommended approach for development as it improves tree-shaking and reduces bundle size.

```javascript
import Add from "carbon-icons-svelte/lib/Add.svelte";
```

--------------------------------

### TypeScript Definitions Example

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/configuration.md

Demonstrates how to import TypeScript definitions and a specific icon component. Ensures type safety when using icons in a TypeScript project.

```typescript
import type { CarbonIconProps } from "carbon-icons-svelte";
import Add from "carbon-icons-svelte/lib/Add.svelte";
```

--------------------------------

### Barrel Import Example

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/configuration.md

Imports all icons from the library using a barrel import. This is suitable for projects where many icons are needed.

```javascript
import { Add, CheckmarkFilled } from "carbon-icons-svelte";
```

--------------------------------

### Example Return Value of buildIcons

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/api-reference/build-process.md

Illustrates the expected output format from the `buildIcons` function, which is a sorted array of icon module names, including aliases.

```typescript
[
  "A11y",
  "A11yAlt",
  "Add",
  "AddAlt",
  // ... 2,689 total icons
  "ZoomOut"
]
```

--------------------------------

### Accessible Icon Example

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/REFERENCE-GUIDE.md

Demonstrates an icon used with an accessible label, ensuring it's understandable for users relying on screen readers.

```svelte
<script>
  import Search from "carbon-icons-svelte/lib/Search.svelte";
</script>

<Search aria-label="Search" />
```

--------------------------------

### Type Definition File Structure

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/api-reference/build-process.md

Example of a generated type definition file for a Svelte component, which is a simple re-export.

```typescript
lib/{IconName}.svelte.d.ts
```

--------------------------------

### Icon Index Markdown Format

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/api-reference/internal-mechanisms.md

Example of the markdown format for the `ICON_INDEX.md` file, including a header and a list of icons with optional alias information.

```markdown
# Icon Index
> 2689 icons from [@carbon/icons@11.82.0](https://unpkg.com/browse/@carbon/icons@11.82.0/)

- A11y
- A11yAlt
- Add
- NavaidVordme (alias of NavaidVorDme)
```

--------------------------------

### Common Use Cases

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/REFERENCE-GUIDE.md

Provides practical examples of integrating icons into Svelte components for common scenarios like icon buttons, colored icons, and dynamic sizing.

```APIDOC
## Common Use Cases

### Icon Button
```svelte
<script>
  import Add from "carbon-icons-svelte/lib/Add.svelte";
</script>

<button>
  <Add size={20} />
  Add Item
</button>
```

### Icon with Color
```svelte
<script>
  import CheckmarkFilled from "carbon-icons-svelte/lib/CheckmarkFilled.svelte";
</script>

<CheckmarkFilled fill="#24a148" size={24} />
```

### Accessible Icon
```svelte
<script>
  import Search from "carbon-icons-svelte/lib/Search.svelte";
</script>

<Search aria-label="Search" />
```

### Dynamic Size
```svelte
<script>
  import Add from "carbon-icons-svelte/lib/Add.svelte";
  
  let iconSize = 16;
</script>

<Add size={iconSize} />
<select bind:value={iconSize}>
  <option value={16}>Small</option>
  <option value={24}>Medium</option>
  <option value={32}>Large</option>
</select>
```

### Reusable Icon Component
```svelte
<script lang="ts">
  import Add from "carbon-icons-svelte/lib/Add.svelte";
  import type { CarbonIconProps } from "carbon-icons-svelte";
  
  interface ButtonProps extends CarbonIconProps {
    label: string;
  }
  
  let { label, ...iconProps }: ButtonProps = $props();
</script>

<button>
  <Add {...iconProps} />
  {label}
</button>
```
```

--------------------------------

### Initialize Metadata Object

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/api-reference/internal-mechanisms.md

Starts the metadata merging process by creating a copy of the latest icon metadata. This ensures all current icons are included.

```typescript
const metadata = { ...metadata_latest };
```

--------------------------------

### Usage Example: Generating a Svelte Icon Component

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/api-reference/templates.md

Demonstrates how to use the `template` function with an `IconOutput` object to generate the complete Svelte component code as a string. Ensure correct imports for `template` and `IconOutput`.

```typescript
import { template } from "carbon-icons-svelte/src/template.ts";
import type { IconOutput } from "@carbon/icons";

const iconOutput: IconOutput = {
  moduleName: "Add",
  filepath: "src/icons/Add.tsx",
  size: 32,
  descriptor: {
    elem: "svg",
    name: "add",
    size: 32,
    attrs: {
      xmlns: "http://www.w3.org/2000/svg",
      viewBox: "0 0 32 32",
      fill: "currentColor",
      width: 32,
      height: 32
    },
    content: [
      { elem: "path", attrs: { d: "M17 15H32v2H17v15h-2V17H0v-2h15V0h2z" } }
    ]
  }
};

const componentCode = template(iconOutput);
console.log(componentCode);
// Outputs the complete Svelte component as a string
```

--------------------------------

### TypeScript Usage Example

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/api-reference/icon-components.md

Demonstrates how to import and use CarbonIconProps with a Svelte icon component. Allows setting custom properties like size, fill, and class.

```typescript
import type { CarbonIconProps } from "carbon-icons-svelte";
import Add from "carbon-icons-svelte/lib/Add.svelte";

const iconProps: CarbonIconProps = {
  size: 24,
  fill: "#0f62fe",
  "data-testid": "my-icon",
  class: "my-class",
};
```

--------------------------------

### Svelte Component File Structure

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/api-reference/build-process.md

Example of a generated Svelte component file for an icon, including the standard template with embedded SVG content.

```svelte
lib/{IconName}.svelte
```

--------------------------------

### Icon Component Props

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/REFERENCE-GUIDE.md

Example of using an icon component with its standard and inherited SVG attributes. Customize size, title, and styling as needed.

```svelte
<Add 
  size={16 | 20 | 24 | 32 | number}
  title="Optional title"
  fill="currentColor"
  aria-label="Accessible label"
  class="custom-class"
  data-testid="test-id"
/>
```

--------------------------------

### Generate Compact SVG Output

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/api-reference/templates.md

Example demonstrating the usage of the templateSvg function with a sample icon output, showing the input and the resulting compacted single-line SVG.

```typescript
const iconOutput = {
  moduleName: "Add",
  descriptor: {
    elem: "svg",
    attrs: {
      xmlns: "http://www.w3.org/2000/svg",
      viewBox: "0 0 32 32",
      fill: "currentColor",
      width: 32,
      height: 32
    },
    content: [
      { elem: "path", attrs: { d: "M17 15H32v2H17v15h-2V17H0v-2h15V0h2z" } }
    ]
  }
};

const result = templateSvg(iconOutput);
```

```xml
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" fill="currentColor" preserveAspectRatio="xMidYMid meet" width="16" height="16"><path d="M17 15H32v2H17v15h-2V17H0v-2h15V0h2z"/></svg>
```

--------------------------------

### Exported Icon Components

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/api-reference/module-graph.md

The library exports 2,689 canonical icons, all of which are Svelte Components compatible with `CarbonIconProps`. Examples include `Add`, `AddAlt`, `A11y`, `CheckmarkFilled`, `Close`, and `ChevronDown`. A complete list can be found in ICON_INDEX.md.

```APIDOC
## Exported Icon Components

**Count:** 2,689 canonical icons

**All are `Component<CarbonIconProps>`** from Svelte 4/5

**Examples:**
- `Add`
- `AddAlt`
- `A11y`
- `CheckmarkFilled`
- `Close`
- `ChevronDown`
- etc. (complete list in ICON_INDEX.md)
```

--------------------------------

### Perform Clean Build

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/REFERENCE-GUIDE.md

Removes the 'lib' directory and then runs 'prepack' to ensure a fresh build from scratch.

```bash
rm -rf lib
bun prepack
```

--------------------------------

### Run Build Script

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/REFERENCE-GUIDE.md

Executes the 'prepack' script using bun, typically for building icons and running tests.

```bash
bun prepack
```

--------------------------------

### Generated File Structure

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/REFERENCE-GUIDE.md

Illustrates the file structure after the project is built, including individual icon components and exports.

```bash
lib/
├── index.js          # Barrel export (all icons)
├── index.d.ts        # Type definitions
├── Add.svelte        # Individual icon component
├── Add.svelte.d.ts   # Type definition
└── ... (2,689 icons + 3 aliases)
```

--------------------------------

### Build Output Module Structure

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/api-reference/module-graph.md

Shows the generated module structure after the `buildIcons()` function executes, detailing the icon components and type definitions.

```text
lib/ (generated)
├── index.js
│   └── exports all icon components
├── index.d.ts
│   └── type definitions for all icons
├── Add.svelte
│   └── Icon component
├── Add.svelte.d.ts
│   └── Type definition
├── AddAlt.svelte
│   └── Icon component
├── AddAlt.svelte.d.ts
│   └── Type definition
├── NavaidVordme.svelte (alias file on case-sensitive systems)
│   └── Re-exports NavaidVorDme
├── NavaidVordme.svelte.d.ts
│   └── Type definition
// ... 2,689 icon components + 3 aliases (if case-sensitive)
```

--------------------------------

### Optimized Component Import

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/REFERENCE-GUIDE.md

Demonstrates the recommended way to import individual icons for faster development builds.

```typescript
// Fast (only imports one icon)
import Add from "carbon-icons-svelte/lib/Add.svelte";
```

--------------------------------

### Package JSON Build Scripts

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/configuration.md

Defines npm scripts for building documentation assets, running tests, and preparing the package for publishing. The `prepack` script ensures tests pass before publishing.

```json
{
  "scripts": {
    "prepack": "bun test",
    "build:docs-assets": "bun -e \"import { buildIcons } from './src/index.ts'; await buildIcons();\"",
    "test:types": "bun tests/test-types.ts"
  }
}
```

--------------------------------

### Configure npm prepack script

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/api-reference/build-process.md

Integrates the build process into the npm build pipeline by invoking the `prepack` script. This script is typically run before packaging for distribution.

```json
{
  "scripts": {
    "prepack": "bun test"
  }
}
```

--------------------------------

### Clean and Recreate Output Directory

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/api-reference/build-process.md

Removes the existing `lib/` directory and creates a new one to ensure a clean build state before generating new files.

```bash
rm -rf lib
mkdir lib
```

--------------------------------

### Full Component Library Import

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/REFERENCE-GUIDE.md

Shows an alternative import method that loads all icons, potentially slowing down development builds.

```typescript
// Slower (imports all 2,689 icons for tree-shaking)
import { Add } from "carbon-icons-svelte";
```

--------------------------------

### Leading Underscore Regex Pattern

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/configuration.md

A regular expression to detect if an icon name starts with an underscore, used for formatting icon indexes to escape markdown.

```typescript
const LEADING_UNDERSCORE_PATTERN = /^\_/;
```

--------------------------------

### Log Build Timing Information

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/api-reference/build-process.md

Logs timing information for the build process to the console. Use this to monitor performance.

```javascript
console.time("buildIcons");
// ... processing ...
console.timeEnd("buildIcons");
// Output: buildIcons: 234ms
```

--------------------------------

### Escaping Icon Names in Markdown

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/api-reference/internal-mechanisms.md

JavaScript code snippet demonstrating how to escape icon names starting with an underscore using a regular expression. This prevents markdown from misinterpreting underscores as emphasis.

```typescript
const escaped = moduleName.replace(LEADING_UNDERSCORE_PATTERN, "\\_");
```

--------------------------------

### Cleanup Directories with Bun

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/api-reference/internal-mechanisms.md

Uses Bun's template string syntax to execute shell commands for cleaning up and creating directories.

```typescript
await $`rm -rf lib`;
await $`mkdir lib`;
```

--------------------------------

### buildIcons Function

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/api-reference/build-process.md

The `buildIcons` function is the main export used to generate the icon component library. It reads configuration from package.json, metadata from installed @carbon/icons packages, and predefined constants to create the icon modules.

```APIDOC
## buildIcons Function

### Description
Orchestrates the generation of the complete icon component library from @carbon/icons metadata. This is the primary public export from the source code and is executed as part of the package build pipeline.

### Module
`carbon-icons-svelte/src/index.ts`

### Export
Named export `buildIcons`

### Kind
Async function

### Signature
```typescript
export const buildIcons = async (): Promise<string[]>
```

### Parameters
None. The function reads configuration from:
- `package.json` (devDependencies for @carbon/icons version)
- Metadata JSON files from installed @carbon/icons packages
- Predefined constants (DEPRECATED_ICONS, RENAMED_ICONS)

### Return Value
**Type:** `Promise<string[]>`

A promise that resolves to an array of icon module names (strings) in sorted order. The array includes both canonical icon names and deprecated/renamed icon aliases.

**Example return value:**
```typescript
[
  "A11y",
  "A11yAlt",
  "Add",
  "AddAlt",
  // ... 2,689 total icons
  "ZoomOut"
]
```

### Throws
The function throws synchronously or via promise rejection in these conditions:

| Condition |
|----------- |
| Rename alias target missing |
| File system errors |

#### Error Details
- **Rename alias target missing:** `Error` - Message: `"Rename alias target missing: {newName} for {oldName}"`. Thrown when a RENAMED_ICONS entry references a target icon that doesn't exist in the metadata.
- **File system errors:** `Error` - Thrown by `readdir()` or `unlink()` operations on the file system.
```

--------------------------------

### Basic Icon Usage

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/api-reference/icon-components.md

Render an icon component using its default size. Import the desired icon and include it in your template.

```svelte
<script>
  import Add from "carbon-icons-svelte/lib/Add.svelte";
</script>

<Add />
```

--------------------------------

### buildIcons() Function

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/COMPLETION-SUMMARY.txt

Documentation for the main build function used to generate icon components.

```APIDOC
## buildIcons() Function

### Description
The `buildIcons()` function is the primary tool for generating Svelte icon components from SVG assets. It processes SVG files, applies transformations, and outputs ready-to-use Svelte components.

### Function Signature

```typescript
function buildIcons(options: BuildIconsOptions): Promise<void>;
```

### Parameters

#### options (BuildIconsOptions)

- **inputDir** (string) - Required - The directory containing the source SVG files.
- **outputDir** (string) - Required - The directory where the generated Svelte components will be saved.
- **componentNamePrefix** (string) - Optional - A prefix to add to all generated component names.
- **template** (Function) - Optional - A custom template function for generating component code.
- **svgToComponent** (Function) - Optional - A custom function to transform SVG data into component code.

### Usage Example

```javascript
import { buildIcons } from 'carbon-icons-svelte/build';

buildIcons({
  inputDir: './svgs',
  outputDir: './src/icons',
  componentNamePrefix: 'MyIcon'
}).catch(console.error);
```

### Return Value

- Returns a `Promise<void>` that resolves when the build process is complete.
```

--------------------------------

### Source File Structure

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/REFERENCE-GUIDE.md

Overview of the directory structure for the source files of the Carbon Icons Svelte project.

```bash
src/
├── index.ts          # buildIcons() function
├── template.ts       # Component template generation
└── global.d.ts       # Type augmentations for @carbon/icons
```

--------------------------------

### Import Icons from Main Package

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/REFERENCE-GUIDE.md

Import icons and types from the main package entry point. This is a general import method.

```typescript
import { Add } from "carbon-icons-svelte";
import type { CarbonIconProps } from "carbon-icons-svelte";
```

--------------------------------

### Icon Component API Reference

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/COMPLETION-SUMMARY.txt

Documentation for the API of individual icon components, including their props and usage.

```APIDOC
## Icon Components API Reference

### Description
This section provides a detailed API reference for all icon components available in the carbon-icons-svelte library. It covers the props that can be passed to each icon component, their types, and default values, along with usage examples.

### Component Props

#### CarbonIconProps

- **size** (number | string) - Optional - The size of the icon. Can be a number for pixel value or a string like '16', '20', '24'.
- **ariaLabel** (string) - Optional - Accessibility label for the icon.
- **ariaHidden** (boolean) - Optional - Hides the icon from assistive technologies if true.
- **title** (string) - Optional - Provides a tooltip or title for the icon.
- **class** (string) - Optional - Custom CSS classes to apply to the icon.
- **style** (string) - Optional - Custom inline styles to apply to the icon.

### Usage Example

```svelte
<script>
  import Add24 from 'carbon-icons-svelte/lib/add/24';
</script>

<Add24 size={32} ariaLabel="Add item" />
```

### Response

#### Success Response (200)
Icon components render an SVG element with the specified props applied.
```

--------------------------------

### Documentation File Structure

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/REFERENCE-GUIDE.md

Lists the key Markdown files included in the project for documentation purposes.

```markdown
ICON_INDEX.md        # Complete list of all icons
CHANGELOG.md         # Version history
CONTRIBUTING.md      # Development guide
```

--------------------------------

### Build Icon Library and Log Count

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/api-reference/build-process.md

Builds the icon library by calling `buildIcons()` and logs the total number of icons built along with the first five icon names. This demonstrates basic usage of the function.

```typescript
import { buildIcons } from "carbon-icons-svelte/src/index.ts";

// Build the icon library and get all icon names
const iconNames = await buildIcons();

console.log(`Built ${iconNames.length} icons`);
console.log("First 5 icons:", iconNames.slice(0, 5));
// Output:
// Built 2689 icons
// First 5 icons: ['A11y', 'A11yAlt', 'Add', 'AddAlt', 'AddComment']
```

--------------------------------

### Write Icon Files with Bun

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/api-reference/internal-mechanisms.md

Uses `Bun.write()` to asynchronously write icon component files and their corresponding TypeScript definition files. Returns a Promise that resolves when the write operation is complete.

```typescript
writePromises.push(Bun.write(fileName, template(icon)));
writePromises.push(Bun.write(fileName + ".d.ts", `export { ... }`));
```

--------------------------------

### Optimize Imports with carbon-preprocess-svelte

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/README.md

Use optimizeImports preprocessor to enable concise barrel file import syntax while only importing necessary icons, improving development speed.

```diff
- import { Add } from "carbon-icons-svelte";
+ import Add from "carbon-icons-svelte/lib/Add.svelte";
```

--------------------------------

### Component Direct Import

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/api-reference/module-graph.md

Allows importing individual icon components directly from their specific file paths within the library.

```APIDOC
## Component Direct Import: `carbon-icons-svelte/lib/{IconName}.svelte`

### Description
Allows importing individual icon components directly from their specific file paths within the library. Each icon component is of type `Component<CarbonIconProps>`.

### Usage
```typescript
import Add from "carbon-icons-svelte/lib/Add.svelte";
import AddAlt from "carbon-icons-svelte/lib/AddAlt.svelte";
import CheckmarkFilled from "carbon-icons-svelte/lib/CheckmarkFilled.svelte";
```

### Pattern Match
`carbon-icons-svelte/lib/*.svelte`

### Type Definitions
Type definitions for individual icon components are available via `{IconName}.svelte.d.ts`.
```

--------------------------------

### Importing Svelte Component Type

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/types.md

Demonstrates how to import the Component type from 'svelte' to properly type Carbon Icon components.

```typescript
import type { Component } from "svelte";

```

--------------------------------

### Basic Icon Usage in Svelte

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/START-HERE.md

Demonstrates how to import and use an icon component in a Svelte application. Ensure the icon is imported from 'carbon-icons-svelte/lib/'.

```svelte
<script>
  import Add from "carbon-icons-svelte/lib/Add.svelte";
</script>

<Add size={24} aria-label="Add item" />
```

--------------------------------

### Dependency Graph for carbon-icons-svelte

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/api-reference/module-graph.md

Illustrates the internal dependencies within the carbon-icons-svelte package, including source files, helper modules, and external dependencies.

```text
carbon-icons-svelte (package root)
├── src/
│   ├── index.ts
│   │   ├── @carbon/icons (metadata)
│   │   ├── @carbon/icons-11.80 (metadata)
│   │   ├── @carbon/icons-11.31 (metadata)
│   │   ├── @carbon/icon-helpers (formatAttributes, toString)
│   │   ├── node:crypto (createHash)
│   │   ├── node:fs/promises (readdir, unlink)
│   │   ├── bun (shell commands)
│   │   └── src/template.ts
│   ├── template.ts
│   │   ├── @carbon/icon-helpers (formatAttributes, toString)
│   │   └── @carbon/icons (IconOutput type)
│   └── global.d.ts
│       └── @carbon/icons (type augmentations)
└── tests/
    ├── index.test.ts
    │   └── src/index.ts
    └── template.test.ts
        ├── @carbon/icons (IconOutput type)
        └── src/template.ts
```

--------------------------------

### Build Information JSON Structure

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/api-reference/build-process.md

A JSON file containing structured build metadata, including total icon count, categorization by size, SVG content, and renamed icons.

```json
{
  "total": 2689,
  "bySize": {
    "order": ["glyph", "icon"],
    "sizes": {
      "glyph": ["A11y", "A11yAlt", ...],
      "icon": ["Add", "AddAlt", ...]
    }
  },
  "byModuleName": {
    "Add": "<svg ...>...</svg>",
    // ... SVG string per icon
  },
  "renamedIcons": {
    "NavaidVordme": "NavaidVorDme",
    // ...
  }
}
```

--------------------------------

### Main Export File

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/api-reference/build-process.md

Contains export statements for all canonical icons, allowing them to be imported from the library.

```javascript
export { default as Add } from "./Add.svelte";
export { default as AddAlt } from "./AddAlt.svelte";
// ... one per icon
```

--------------------------------

### Using IconOutput with Template Functions

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/types.md

Demonstrates how to import and use the IconOutput type with template functions for rendering Svelte components or SVG strings.

```typescript
import { template, templateSvg } from "./template.js";
import type { IconOutput } from "@carbon/icons";

const iconOutput: IconOutput = { /* ... */ };
const svelteComponent = template(iconOutput);
const svgString = templateSvg(iconOutput);
```

--------------------------------

### Main Package Exports (JavaScript)

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/api-reference/module-graph.md

Exports all icon components as named exports from the main package entry point. This is a generated file at build time.

```javascript
export { default as Add } from "./Add.svelte";
export { default as AddAlt } from "./AddAlt.svelte";
// ... 2,687 more icons
```

--------------------------------

### Importing Icon Metadata in Library

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/types.md

Demonstrates how to import icon metadata JSON files from different versions of the `@carbon/icons` package. These imports are used during the build process to load and process icon definitions.

```typescript
import metadata_latest from "@carbon/icons/metadata.json" with { type: "json" };
import metadata_11_80 from "@carbon/icons-11.80/metadata.json" with { type: "json" };
import metadata_11_31 from "@carbon/icons-11.31/metadata.json" with { type: "json" };

type MetadataSource = typeof metadata_latest | typeof metadata_11_80 | typeof metadata_11_31;
type IconEntry = (typeof metadata_latest.icons)[number];
```

--------------------------------

### Package JSON Main Entry Points

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/configuration.md

Defines the main entry points for the Svelte library, including Svelte-specific, CommonJS, and TypeScript definitions. It also configures conditional exports for direct icon component imports.

```json
{
  "svelte": "./lib/index.js",
  "main": "./lib/index.js",
  "types": "./lib/index.d.ts",
  "exports": {
    ".": {
      "types": "./lib/index.d.ts",
      "svelte": "./lib/index.js"
    },
    "./lib/*.svelte": {
      "types": "./lib/*.svelte.d.ts",
      "import": "./lib/*.svelte"
    }
  }
}
```

--------------------------------

### Generating Icons with buildIcons

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/START-HERE.md

Shows how to use the buildIcons function to generate icons programmatically. This is typically used for integrating the build process into a system.

```typescript
import { buildIcons } from "carbon-icons-svelte/src/index.ts";

const iconNames = await buildIcons();
console.log(`Generated ${iconNames.length} icons`);
```

--------------------------------

### Import Icon Components

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/api-reference/icon-components.md

Import specific icon components from the carbon-icons-svelte library. Ensure the correct path is used for each icon.

```svelte
<script>
  import Add from "carbon-icons-svelte/lib/Add.svelte";
  import ArrowRight from "carbon-icons-svelte/lib/ArrowRight.svelte";
  import CheckmarkFilled from "carbon-icons-svelte/lib/CheckmarkFilled.svelte";
</script>
```

--------------------------------

### Create Alias File for Case-Sensitive File Systems

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/api-reference/internal-mechanisms.md

Generates a separate alias file for icon names on case-sensitive file systems like Linux.

```typescript
// lib/{OldName}.svelte
export { default as ${oldName} } from "./${newName}.svelte";
```

--------------------------------

### Apply Theme from Local Storage in Svelte

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/docs/index.html

This script attempts to retrieve a theme from local storage and apply it to the document's root element. It supports specific theme names and sets the color scheme accordingly. It includes basic error handling for local storage access.

```javascript
try {
  const theme = localStorage.getItem("theme");
  if (["white", "g10", "g80", "g90", "g100"].includes(theme)) {
    document.documentElement.setAttribute("theme", theme);
    document.documentElement.style.setProperty(
      "color-scheme",
      ["white", "g10"].includes(theme) ? "light" : "dark"
    );
  }
} catch (e) {}

```

--------------------------------

### Importing Icons: Direct Component Import

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/api-reference/module-graph.md

Imports a specific icon component directly from its file path within the library. This is the recommended approach for better tree-shaking and performance.

```typescript
import Add from "carbon-icons-svelte/lib/Add.svelte";
// Resolves to: lib/Add.svelte
```

--------------------------------

### Test buildIcons function

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/api-reference/module-graph.md

Verifies that the build process correctly generates the expected number of icons and matches a snapshot.

```typescript
test("imports", async () => {
  const icons = await buildIcons();
  expect(icons.length).toEqual(2689);
  expect(icons).toMatchSnapshot();
});
```

--------------------------------

### Build Info URL Export

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/api-reference/build-process.md

Auto-generated TypeScript file providing the URL for the build info JSON, used for documentation purposes.

```typescript
// @generated
// This file was automatically generated and should not be edited.
// @see src/index.ts

export const BUILD_INFO_URL = "/build-info.{HASH}.json";
```

--------------------------------

### Build Icons Library

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/REFERENCE-GUIDE.md

Use this function to generate the complete icon library. It reads metadata, deduplicates icons, generates component and definition files, and creates export files and documentation.

```typescript
import { buildIcons } from "carbon-icons-svelte/src/index.ts";

const iconNames = await buildIcons();
console.log(`Generated ${iconNames.length} icons`);
// Output: Generated 2689 icons
```

--------------------------------

### Path Aliases for carbon-icons-svelte

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/configuration.md

Configures TypeScript path aliases to map 'carbon-icons-svelte' imports to the local './lib' directory.

```json
{
  "paths": {
    "carbon-icons-svelte": ["./lib"],
    "carbon-icons-svelte/lib/*": ["./lib/*"]
  }
}
```

--------------------------------

### Main Package Exports (TypeScript Definitions)

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/api-reference/module-graph.md

Provides TypeScript type definitions for icon components and their props, exported from the main package entry point.

```typescript
export type CarbonIconProps = SvelteHTMLElements["svg"] & {
  title?: string;
  size?: 16 | 20 | 24 | 32 | (number & {});
};

export declare const Add: Component<CarbonIconProps>;
export declare const AddAlt: Component<CarbonIconProps>;
// ... 2,687 more icons
```

--------------------------------

### Using CarbonIconProps Type

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/types.md

Shows how to import and use the CarbonIconProps type for defining icon components.

```typescript
import type { Component } from "svelte";
import type { CarbonIconProps } from "carbon-icons-svelte";
import Add from "carbon-icons-svelte/lib/Add.svelte";

// Add is typed as Component<CarbonIconProps>
const icon: Component<CarbonIconProps> = Add;

// Can be used with Svelte's component constructor types
type IconComponent = typeof Add; // Component<CarbonIconProps>

```

--------------------------------

### Package JSON Build Dependencies

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/configuration.md

Lists the development and build dependencies required for the carbon-icons-svelte library. This includes icon helpers, icon packages, Svelte, and TypeScript.

```json
{
  "@carbon/icon-helpers": "^10.73.0",
  "@carbon/icons": "11.82.0",
  "@carbon/icons-11.31": "npm:@carbon/icons@~11.31.0",
  "@carbon/icons-11.80": "npm:@carbon/icons@11.80.0",
  "@types/bun": "^1.3.9",
  "culls": "^0.2.0",
  "svelte": "^5.53.6",
  "typescript": "^6.0.3"
}
```

--------------------------------

### Usage of ModuleName in buildIcons

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/types.md

Demonstrates how the buildIcons() function returns an array of ModuleName strings, representing icon names.

```typescript
const iconNames: ModuleName[] = await buildIcons();
// Returns: ["A11y", "A11yAlt", "Add", "AddAlt", ...]

```

--------------------------------

### Main Export: carbon-icons-svelte

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/api-reference/module-graph.md

Exports all icon components as named exports from the main package entry point. Also provides type definitions for icon props.

```APIDOC
## Main Export: `carbon-icons-svelte`

### Description
Exports all 2,689 icon components as named exports from the main package entry point. Also provides type definitions for icon props.

### Usage
```typescript
import { Add, CheckmarkFilled } from "carbon-icons-svelte";
import type { CarbonIconProps } from "carbon-icons-svelte";
```

### Exports
- `Add` (Component)
- `AddAlt` (Component)
- ... (2,687 more icons)

### Type Definitions
- `CarbonIconProps`: Type for icon component props, including standard SVG attributes plus `title` and `size`.
```

--------------------------------

### Dynamic Icon Sizing

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/REFERENCE-GUIDE.md

Control the size of an icon dynamically using a reactive variable. This allows for responsive icon sizing based on user interaction or application state.

```svelte
<script>
  import Add from "carbon-icons-svelte/lib/Add.svelte";
  
  let iconSize = 16;
</script>

<Add size={iconSize} />
<select bind:value={iconSize}>
  <option value={16}>Small</option>
  <option value={24}>Medium</option>
  <option value={32}>Large</option>
</select>
```

--------------------------------

### Component Type Annotation

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/REFERENCE-GUIDE.md

Illustrates how to type an icon component using the Component generic with CarbonIconProps.

```typescript
import type { Component } from "svelte";
import Add from "carbon-icons-svelte/lib/Add.svelte";

// Type annotation:
const icon: Component<CarbonIconProps> = Add;
```

--------------------------------

### Focusable Icons for Keyboard Interaction

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/REFERENCE-GUIDE.md

Make icons focusable for keyboard navigation by adding a `tabindex` attribute. This also sets the `focusable` attribute to `true`.

```svelte
<Add aria-label="Add new item" tabindex={0} />
```

--------------------------------

### Importing Icons: Barrel Import

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/api-reference/module-graph.md

Imports all icons from the library's barrel file. This method is less recommended due to potential performance implications compared to direct imports.

```typescript
import { Add } from "carbon-icons-svelte";
// Resolves to: lib/index.js → lib/Add.svelte
```

--------------------------------

### Remove Old Build Info Files

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/api-reference/internal-mechanisms.md

Iterates through a directory and removes old `build-info.json` files before writing a new one to prevent accumulation.

```typescript
for (const file of await readdir(docsPublicDir)) {
  if (
    file === "build-info.json" ||
    (file.startsWith("build-info.") && file.endsWith(".json"))
  ) {
    await unlink(`${docsPublicDir}/${file}`);
  }
}
```

--------------------------------

### Direct Icon Import in Svelte

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/README.md

Import individual icons directly from the 'carbon-icons-svelte/lib' folder. Refer to the Icon Index for available icons.

```svelte
<script>
  import Add from "carbon-icons-svelte/lib/Add.svelte";
</script>

<Add />
```

--------------------------------

### Icon Index Markdown

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/api-reference/build-process.md

A markdown file listing all canonical icons, organized by name, with annotations for aliases.

```markdown
# Icon Index
> 2689 icons from [@carbon/icons@11.82.0](https://unpkg.com/browse/@carbon/icons@11.82.0/)

- A11y
- A11yAlt
- Add
// ...
- NavaidVordme (alias of NavaidVorDme)
// ...
- ZoomOut
```

--------------------------------

### Basic TypeScript Type Annotation for Icon Props

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/types.md

Demonstrates how to annotate a variable with the CarbonIconProps type for basic usage. Ensure the 'carbon-icons-svelte' package is imported.

```typescript
import type { CarbonIconProps } from "carbon-icons-svelte";
import Add from "carbon-icons-svelte/lib/Add.svelte";

const props: CarbonIconProps = {
  size: 24,
  fill: "red",
  class: "my-icon"
};
```

--------------------------------

### Sync Fork with Upstream

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/CONTRIBUTING.md

Update your local master branch with the latest changes from the upstream repository before submitting a pull request.

```bash
git fetch upstream
git checkout master
git merge upstream/master
```

--------------------------------

### Configure Published Assets

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/configuration.md

Define which files and directories are included in the NPM package. This configuration in package.json restricts published assets to the 'lib/' directory, excluding source and documentation files.

```json
{
  "files": ["lib"]
}
```

--------------------------------

### Run Type Checking Script

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/REFERENCE-GUIDE.md

Verifies the validity of TypeScript type definitions using the 'test:types' script.

```bash
bun test:types
```

--------------------------------

### Package JSON Metadata

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/configuration.md

Standard npm package metadata including name, version, license, description, module type, and repository information. The 'files' field specifies which directories are included when publishing to npm.

```json
{
  "name": "carbon-icons-svelte",
  "version": "13.12.0",
  "license": "Apache-2.0",
  "description": "Carbon Design System SVG icons as Svelte components",
  "type": "module",
  "repository": {
    "type": "git",
    "url": "git+https://github.com/carbon-design-system/carbon-icons-svelte.git"
  },
  "homepage": "https://carbon-icons-svelte.onrender.com/",
  "bugs": "https://github.com/carbon-design-system/carbon-icons-svelte/issues",
  "files": ["lib"]
}
```

--------------------------------

### Direct Icon Component Import (TypeScript)

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/api-reference/module-graph.md

Imports individual icon components directly from their specific file paths within the lib directory. This method is useful for importing only the necessary icons.

```typescript
import Add from "carbon-icons-svelte/lib/Add.svelte";
import AddAlt from "carbon-icons-svelte/lib/AddAlt.svelte";
import CheckmarkFilled from "carbon-icons-svelte/lib/CheckmarkFilled.svelte";
```

--------------------------------

### Parallelize File Writes

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/api-reference/internal-mechanisms.md

Collects all file write promises into an array and awaits them in parallel using `Promise.all` for improved performance.

```typescript
const writePromises: Promise<number>[] = [];
// ... collect promises ...
await Promise.all(writePromises);
```

--------------------------------

### Exported Aliases (Renamed Icons)

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/api-reference/module-graph.md

The library provides 3 aliases for backward compatibility, allowing the use of old names alongside new ones. Both the old and new names are exported and can be imported independently.

```APIDOC
## Exported Aliases (Renamed Icons)

**Count:** 3 aliases for backwards compatibility

| Old Name | New Name |
|----------|----------|
| `NavaidVordme` | `NavaidVorDme` |
| `NavaidVortac` | `NavaidVorTac` |
| `SoftwareResourceResource` | `SoftwareResourceReference` |

Both names are exported and can be imported independently.
```

--------------------------------

### template() Function

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/COMPLETION-SUMMARY.txt

Documentation for the Svelte component template generator function.

```APIDOC
## template() Function

### Description
The `template()` function is a utility for generating the Svelte component template string. It takes SVG data and component metadata to produce the final Svelte component code.

### Function Signature

```typescript
function template(data: TemplateData): string;
```

### Parameters

#### data (TemplateData)

- **svg** (string) - Required - The SVG content as a string.
- **props** (string[]) - Required - An array of prop names to be included in the component.
- **componentName** (string) - Required - The name of the Svelte component.
- **moduleName** (string) - Required - The module name for the icon.

### Usage Example

```javascript
import { template } from 'carbon-icons-svelte/build';

const svgContent = '<svg>...</svg>';
const componentCode = template({
  svg: svgContent,
  props: ['size', 'ariaLabel'],
  componentName: 'MyIcon',
  moduleName: 'my-icon'
});
console.log(componentCode);
```

### Return Value

- Returns a `string` representing the Svelte component's template.
```

--------------------------------

### Focusable Icon with Custom Styling

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/api-reference/icon-components.md

Make an icon focusable by setting `tabindex={0}` and apply custom styles using `fill` and `class` props. This allows the icon to be interactive and visually distinct.

```svelte
<script>
  import Add from "carbon-icons-svelte/lib/Add.svelte";
</script>

<Add 
  aria-label="Add item" 
  tabindex={0} 
  fill="red" 
  class="custom-icon"
/>
```

--------------------------------

### Reusable Icon Component

Source: https://github.com/carbon-design-system/carbon-icons-svelte/blob/master/_autodocs/REFERENCE-GUIDE.md

Create a reusable component that encapsulates an icon and its associated props, along with additional functionality like a label. This promotes code reuse and maintainability.

```svelte
<script lang="ts">
  import Add from "carbon-icons-svelte/lib/Add.svelte";
  import type { CarbonIconProps } from "carbon-icons-svelte";
  
  interface ButtonProps extends CarbonIconProps {
    label: string;
  }
  
  let { label, ...iconProps }: ButtonProps = $props();
</script>

<button>
  <Add {...iconProps} />
  {label}
</button>
```