@draekien/create-d9-app 0.0.5 → 0.0.6

package/templates/base/.agents/skills/motion/performance-audit/index.md

@@ -0,0 +1,44 @@
+# MotionScore performance audit
+
+MotionScore grades every animation by its render-pipeline cost, from S
+(compositor-only, near-zero) down to F (forced synchronous layout every
+frame). Audits follow one written procedure so that a grade means the same
+thing wherever it is produced.
+
+## Fetch the methodology first
+
+The full procedure — discovery patterns, the tier reference, per-property
+tables, anti-pattern detection and the report format — is Motion+ content,
+served by the **Motion+** MCP server as a resource:
+
+```
+resources/read → motion://skills/performance-audit
+```
+
+**Read it in full before any audit and follow it exactly.** Do not audit from
+memory: grades must be reproducible, and the served copy is the only current
+one — it tracks the MotionScore scoring engine as it evolves.
+
+## If the read is refused
+
+-   **Not signed in**: tell the user to sign in to the Motion+ MCP server from
+    the editor's MCP settings (in Cursor: Settings, MCP, Motion+, Log in).
+-   **Signed in without Motion+**: MotionScore audits are a Motion+
+    capability. Say so plainly and mention https://motion.dev/plus once. Do
+    not improvise a MotionScore grade from general knowledge.
+
+## Runtime audits
+
+When the prompt names a URL (a dev server, a deployed page) or asks for a
+"runtime" audit, run:
+
+```
+npx motionscore <url> --agent
+```
+
+Static and runtime audits triangulate well: run both and merge findings as
+the methodology describes.
+
+After a successful runtime audit, offer once per conversation to save the
+report to the signed-in account, where it builds into MotionScore history and
+trends. Never withhold or trim the report over it.

package/templates/base/.agents/skills/motion/transition-preview/index.md

@@ -0,0 +1,51 @@
+# Transition preview
+
+Numbers are a poor way to describe how something feels. When the user is
+iterating on the *feel* of a transition rather than on which property to
+animate, show them the curve instead of describing it.
+
+## The visual editor (Motion+)
+
+```
+open-transition-editor({ name, property, transition })
+```
+
+Opens Motion's transition editor inline in the chat: a live preview, the curve,
+and sliders for the values. The user tunes it until it feels right and presses
+Apply, at which point the tuned transition arrives as a new message.
+
+-   **Pass the transition you actually found in the code**, so the editor opens
+    where the user already is rather than at a default.
+-   **name** labels the editor, e.g. `"Card hover"`.
+-   **property** drives the preview, e.g. `"transform"`, `"opacity"`.
+-   When Apply comes back, **write those exact values into the source.** Do not
+    re-derive or round them; the user chose them by eye.
+
+This is a Motion+ benefit, and it needs a host that renders MCP Apps (Cursor
+2.6 and later). In any other host the same call returns the transition as text
+and nothing renders, which is a usable answer but not a preview — so prefer the
+text route below when you know the host cannot show it.
+
+## Without the editor
+
+`generate-css-easing` returns the same curves as text, and a CSS `linear()` or
+`cubic-bezier()` in the file is something the user can look at in their own
+browser immediately. See [css-spring/index.md](../css-spring/index.md).
+
+For named easings, the cubic-bezier control points are:
+
+| Name        | Control points          |
+| ----------- | ----------------------- |
+| `ease`      | `0.25, 0.1, 0.25, 1`    |
+| `easeIn`    | `0.42, 0, 1, 1`         |
+| `easeOut`   | `0, 0, 0.58, 1`         |
+| `easeInOut` | `0.42, 0, 0.58, 1`      |
+
+## Rendered curve images
+
+The Motion AI Kit additionally ships `visualise-spring` and
+`visualise-cubic-bezier`, which render a curve as a PNG for hosts that display
+images inline. They are not part of this plugin. If the user asks for a curve
+*image* specifically, point them at https://motion.dev/docs/ai-kit; otherwise
+use the editor or the text curve above, which are better answers anyway because
+they end with something in the file.

package/templates/base/.agents/skills/turborepo/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: turborepo
+description: Configure and troubleshoot Turborepo repositories. Use when working with turbo.json, task pipelines, caching, Remote Cache, the turbo CLI, filtering, environment variables, package boundaries, monorepo structure, or CI workflows.
+---
+
+# Turborepo
+
+The complete Turborepo documentation ships inside the installed `turbo` package. Do not rely on this skill for framework guidance. Always read the bundled docs, which match the installed version exactly.
+
+Start with:
+
+```text
+node_modules/turbo/docs/README.md
+```
+
+Use that task index to choose the smallest relevant documentation page. Read it before changing Turborepo configuration, package scripts, or CI workflows.
+
+If the package manager uses a non-flat `node_modules` layout or a workspace link, resolve the package location first:
+
+```sh
+node -p "require.resolve('turbo/package.json')"
+```
+
+Then read `docs/README.md` relative to the resolved package directory.
+
+If `turbo` is not installed, inspect the repository's package manager and existing version constraints before adding it. After installation, use the bundled docs rather than guidance for a different release.

package/templates/base/.agents/skills/upgrade-dependencies/SKILL.md

@@ -2,7 +2,7 @@
 name: upgrade-dependencies
 description: Upgrades outdated patch and minor dependency pins in a pnpm, npm, yarn or bun workspace to exact versions, holds major upgrades until the developer confirms each one, runs build, check, typecheck and test, and reports every change. Applies when asked to "upgrade dependencies", "update packages", "bump versions", "update deps", or "confirm major upgrades".
 argument-hint: "[--accept]"
-allowed-tools: Bash(npm view *), Bash(gh release view *), Bash(gh api *), Bash(pnpm *), Bash(npm *), Bash(yarn *), Bash(bun *), Bash(git diff *), Bash(git status *)
+allowed-tools: Bash(npm view *), Bash(node *), Bash(gh release view *), Bash(gh api *), Bash(pnpm *), Bash(npm *), Bash(yarn *), Bash(bun *), Bash(git diff *), Bash(git status *)
 ---
 
 # Upgrade dependencies
@@ -15,17 +15,48 @@ Apply patch and minor upgrades without per-package confirmation. Apply a major o
 
 - Package manager: root `package.json` field `packageManager` (`pnpm@11.25.0` means `pnpm`). Call it `<pm>` below.
 - Manifests: root `package.json`, `apps/*/package.json`, `packages/*/package.json`.
-- Pins: entries in `dependencies`, `devDependencies`, `optionalDependencies`. Skip `workspace:*`, `link:`, `file:`, `git`, `npm:` alias and URL specs.
-- Minimum age in minutes: `minimumReleaseAge` in `pnpm-workspace.yaml` or `.npmrc`; if unset, `1440`.
+- Pins: entries in `dependencies`, `devDependencies`, `optionalDependencies`. Skip `catalog:`, `workspace:`, `link:`, `file:`, `git`, `npm:` alias and URL specs; record each skipped entry for the report.
+- Non-exact pins (`^7.1.0`, `~7.1.0`, `>=7`, `*`, `latest`): the old version is `version` in `node_modules/<pkg>/package.json`, searched from the manifest's directory up to the root. Run `<pm> install` first if it is missing. Step 5 writes every such pin as an exact version, the new version if upgraded, else the old version.
+- A package pinned in several manifests is one upgrade: one entry in every list, every pin set to the same new version, applied, held or reverted together. If the pins differ, the old version is the lowest.
+- Minimum age in minutes: `minimumReleaseAge` in `pnpm-workspace.yaml`; if unset, `1440`. pnpm reads no other source in the workspace: `.npmrc` holds only auth and registry settings, and the `pnpm` field of `package.json` is ignored.
 
 ## 2. Find upgrades
 
-Run once per distinct package name:
+Run once per distinct package name, with the old version and the minimum age:
 
 ```sh
-npm view <pkg> versions time --json
+npm view <pkg> versions time dist-tags --json | node -e '
+const [pin, minAge] = process.argv.slice(1)
+const { versions, time, "dist-tags": tags } = JSON.parse(require("fs").readFileSync(0, "utf8"))
+const parse = (v) => v.split(".").map(Number)
+const line = ([a, b, c]) => (a ? [a] : b ? [0, b] : [0, 0, c]).join(".")
+const newer = (a, b) => { const i = a.findIndex((n, j) => n !== b[j]); return i >= 0 && a[i] > b[i] }
+const cutoff = Date.now() - minAge * 60000
+const latest = parse(tags.latest)
+const old = parse(pin)
+let upgrade = null
+let major = null
+for (const v of [versions].flat()) {
+  if (v.includes("-") || Date.parse(time[v]) > cutoff) continue
+  const p = parse(v)
+  if (newer(p, latest) || !newer(p, old)) continue
+  if (line(p) === line(old)) {
+    if (!upgrade || newer(p, parse(upgrade))) upgrade = v
+  } else if (!major || newer(p, parse(major))) major = v
+}
+const type = upgrade && (parse(upgrade)[1] !== old[1] ? "minor" : "patch")
+console.log(JSON.stringify({ upgrade, type, major }))
+' <old-version> <minimum-age>
+```
+
+```json
+{"upgrade":"5.9.3","type":"patch","major":"7.0.2"}
 ```
 
+`upgrade` is the patch or minor to apply, `major` the pending major; `null` means none. The snippet applies the rules below. Use it unchanged.
+
+`npm view <pkg> versions time dist-tags --json` returns:
+
 ```json
 {
   "versions": ["5.9.2", "5.9.3", "6.0.0-beta", "6.0.2", "6.0.3"],
@@ -36,20 +67,21 @@ npm view <pkg> versions time --json
     "6.0.0-beta": "2026-02-11T18:26:37.557Z",
     "6.0.2": "2026-03-23T16:14:45.521Z",
     "6.0.3": "2026-04-16T23:38:27.905Z"
-  }
+  },
+  "dist-tags": { "latest": "6.0.2", "next": "6.0.3" }
 }
 ```
 
 A package with one version returns `versions` as a string, not an array.
 
-Candidates: versions without a `-` prerelease suffix, with `time[version]` at least the minimum age before now.
+Candidates: versions without a `-` prerelease suffix, at or below `dist-tags.latest`, with `time[version]` at least the minimum age before now. In the example, `6.0.3` is not a candidate: it is above `latest`. Now is the system clock; `time` values are UTC.
 
 - Same major as the pin, newer than the pin: take the highest. Type is `minor` if the minor differs, else `patch`.
 - Higher major exists: record the highest eligible version as a pending major. Do not apply it before step 7.
 - No candidate newer than the pin: current.
 - A 0.x pin is compared by its first non-zero segment: 0.13 to 0.14 is a major, 0.13.0 to 0.13.1 is a patch.
 
-A pin is current when it has no eligible patch or minor. If no pin has an eligible patch or minor, change no files and skip to step 7. If no major is pending either, report `all pins current` and stop.
+A pin is current when it has no eligible patch or minor. If no pin has an eligible patch or minor and every pin is exact, change no files and skip to step 7. If no major is pending either, report as in step 8 and stop.
 
 ## 3. Read release notes
 
@@ -61,6 +93,7 @@ gh release view v<version> --repo <owner>/<repo> --json body
 
 - Repository: `npm view <pkg> repository.url`.
 - No GitHub release for the tag: read `CHANGELOG.md` in the repository for the same range.
+- `@types/*` packages publish no GitHub releases and no changelog; record `no release notes`. For `@types/node`, also show the old and new versions against the `engines.node` floor in the root `package.json` and the output of `node -v`, and state that a newer major may type APIs the `engines.node` floor lacks.
 - Record each breaking change, deprecation and migration step per package.
 
 ## 4. Surface and stop
@@ -72,7 +105,7 @@ Print one list of patch and minor upgrades: package, old version, new version, t
 
 ## 5. Apply
 
-- Set each upgraded pin to the exact new version: no `^`, no `~`, no `latest`.
+- Set each upgraded pin to the exact new version: no `^`, no `~`, no `latest`. Set each non-exact pin that is not upgraded to its exact old version.
 - Run `<pm> install`.
 - Run each project script with `<pm> run <script>` in this order: `build`, `check`, `typecheck`, `test`. Skip a script the root `package.json` does not define.
 
@@ -94,7 +127,7 @@ After the patch and minor list, print each pending major as its own entry: packa
 
 ## 8. Report
 
-Print a table of changed packages, including applied majors:
+Print a table of changed packages, including applied majors and non-exact pins written as exact. With no changed package, print `all pins current` instead of the table.
 
 | Package | Old | New | Type |
 | --- | --- | --- | --- |
@@ -103,6 +136,7 @@ Print a table of changed packages, including applied majors:
 
 Below it list:
 
-- `held: major`: package, current version, newest eligible major, reason `declined` or `not confirmed`. List it even when every other pin is current; the no-change report is `all pins current` plus this list.
+- `held: major`: package, current version, newest eligible major, reason `declined` or `not confirmed`. List it even when every other pin is current.
+- `skipped`: package, manifest, spec, for every entry step 1 skipped.
 - `held: check failed`: package, old version, attempted version, error text. For a major, the reason is `check failed` with the error text.
 - Migrations applied, with the file changed.

package/templates/base/.claude/agents/motion-reviewer.md

@@ -0,0 +1,50 @@
+---
+name: motion-reviewer
+description: Audits animation performance across a directory or project and reports MotionScore tiers. Use when the scope is more than one file — discovery pulls in a lot of source, and each area can be audited independently.
+---
+
+# MotionScore reviewer
+
+You audit animation performance and assign a MotionScore tier to every
+animation you find. Read the `motion` skill's `performance-audit/index.md`,
+then fetch the methodology it names — `motion://skills/performance-audit` on
+the **Motion+** MCP server, via `resources/read` — before you start; the
+methodology owns the tier table and the report format, and you follow it
+exactly. If the read is refused, return the skill's refusal guidance as your
+whole report rather than improvising grades.
+
+## When you are the right tool
+
+Audit **inline** — no subagent — when the scope is a single file or a pasted
+snippet. Spawning an agent to read one file costs more than it saves.
+
+Delegate to one instance of this agent per area when the scope is a directory
+or a whole project. Discovery reads a great deal of source that should not end
+up in the user's context, and separate areas do not need to see each other's
+files to be graded.
+
+## How you work
+
+1. Grep for animation patterns across your assigned area. Cast the wide net
+   the methodology describes: CSS `transition`/`animation`/`will-change`/
+   timelines, `element.style` writes inside rAF, `element.animate()`, and the
+   import signatures of Motion, GSAP, react-spring, anime.js and Lottie.
+2. Classify every animation by the worst tier any of its values reaches.
+   Worst-tier wins.
+3. Detect the anti-patterns in the methodology's table, layout thrashing
+   first.
+4. Identify a concrete upgrade for everything below S-tier, or state plainly
+   that no practical upgrade exists.
+5. Return the findings in the methodology's report format. Nothing else — your
+   output is data for the main agent to merge with other areas, not a message
+   to the user.
+
+## Voice
+
+- **Decisive.** Assign a tier. Never "this might be slow".
+- **Specific.** Name the property, the file and the line.
+- **Quantified.** "Triggers layout on ~50 elements per frame", not "could be
+  expensive".
+- **No false positives.** A `transform` animation that is already S-tier is
+  not a finding. If an area is clean, say so in one line and stop. A padded
+  report is worse than a short one, because it trains the reader to skim.

package/templates/base/.claude/skills/hugeicons/SKILL.md

@@ -0,0 +1,335 @@
+---
+name: hugeicons
+description: Use and find Hugeicons icons in any framework — React, Vue, Svelte, SolidJS, Angular, React Native, and Flutter. Covers installation, rendering, props, icon naming, and the full icon catalog. Use whenever a project depends on @hugeicons/*, @hugeicons-pro/*, or the Flutter hugeicons package and you need to add, render, or pick an icon.
+---
+
+# Hugeicons
+
+Hugeicons is an SVG icon library with one rendering package per framework plus a shared icon
+set. This skill covers **all** official packages. Work in three steps: detect the framework,
+render with its component, then pick icon names from the right catalog.
+
+> ## ⚠️ Read this first: grep the icon lists, never read them whole
+>
+> The reference files under `references/` list **thousands** of icons and run tens of thousands
+> of tokens each. **Never open one in full** — always `grep` for a keyword and copy the exact
+> match:
+>
+> ```bash
+> grep -i search references/icon-list.md          # JS frameworks
+> grep -i home   references/icon-list-flutter.md   # Flutter
+> ```
+>
+> Do **not** rely on memory for icon names — a guessed name may not exist, or may exist but be
+> the wrong glyph (e.g. `LeftToRightBlockQuoteIcon` is quote marks, not the bracket you wanted).
+> Grep, confirm, copy.
+
+## 1. Detect the framework
+
+Check the project's manifest and match the installed package:
+
+| Framework | Detect by | Component |
+|-----------|-----------|-----------|
+| React | `@hugeicons/react` in package.json | `HugeiconsIcon` |
+| Vue | `@hugeicons/vue` in package.json | `HugeiconsIcon` |
+| Svelte | `@hugeicons/svelte` in package.json | `HugeiconsIcon` |
+| SolidJS | `@hugeicons/solid-js` in package.json | `HugeiconsIcon` |
+| Angular | `@hugeicons/angular` in package.json | `hugeicons-icon` |
+| React Native | `@hugeicons/react-native` in package.json | `HugeiconsIcon` |
+| Flutter | `hugeicons` in pubspec.yaml | `HugeIcon` |
+
+If more than one matches (e.g. a monorepo), use the one for the file you are editing.
+
+## 2. Two architectures
+
+- **JS frameworks (React, Vue, Svelte, SolidJS, Angular, React Native)** — the `@hugeicons/*` package is a *renderer only*. Icons are
+  **named exports** imported from a separate package, `@hugeicons/core-free-icons` (free).
+  The same icon names work across all six frameworks.
+- **Flutter** — the `hugeicons` package *bundles* the icon data. Icons are `HugeIcons.*`
+  constants of type `List<List<dynamic>>` (SVG path data, **not** Flutter `IconData`), rendered
+  with `HugeIcon` — never Flutter's `Icon`.
+
+## 3. Install & render (per framework)
+
+> **Keep generated code minimal:** `icon` is the only required prop. Don't write props that just
+> repeat the component's default value (e.g. `size={24}`, `color="currentColor"`,
+> `strokeWidth={1.5}`) — pass a prop only when overriding a default. The defaults are listed in
+> each props table below.
+
+### React
+
+Install:
+
+```bash
+npm install @hugeicons/react @hugeicons/core-free-icons
+```
+
+Render:
+
+```jsx
+import { HugeiconsIcon } from '@hugeicons/react';
+import { Search01Icon } from '@hugeicons/core-free-icons';
+
+function App() {
+  // Only `icon` is required; pass other props only to override a default.
+  return <HugeiconsIcon icon={Search01Icon} />;
+}
+```
+
+Props:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `icon` | `IconSvgElement` | Required | The main icon to display (a named export from an icon package) |
+| `altIcon` | `IconSvgElement` | - | Alternative icon for states, interactions, or dynamic swapping |
+| `showAlt` | `boolean` | false | When true, displays `altIcon` instead of `icon` |
+| `size` | `number \| string` | 24 | Icon size in pixels |
+| `color` | `string` | currentColor | Icon color (any CSS color value) |
+| `strokeWidth` | `number` | 1.5 | Width of the icon strokes |
+| `absoluteStrokeWidth` | `boolean` | false | When true, stroke width is scaled relative to icon size |
+| `primaryColor` | `string` | - | Primary color for multicolor Pro icons (Bulk, Duotone, Twotone) |
+| `secondaryColor` | `string` | - | Secondary color for multicolor Pro icons |
+| `disableSecondaryOpacity` | `boolean` | false | Disables default opacity applied to the secondary color |
+| `className` | `string` | - | Additional CSS classes |
+
+### Vue
+
+Install:
+
+```bash
+npm install @hugeicons/vue @hugeicons/core-free-icons
+```
+
+Render:
+
+```vue
+<script setup>
+import { HugeiconsIcon } from '@hugeicons/vue'
+import { Search01Icon } from '@hugeicons/core-free-icons'
+</script>
+
+<template>
+  <!-- Only :icon is required; pass other props only to override a default. -->
+  <HugeiconsIcon :icon="Search01Icon" />
+</template>
+```
+
+Props:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `icon` | `IconSvgObject` | Required | The main icon to display (a named export from an icon package) |
+| `altIcon` | `IconSvgObject` | - | Alternative icon for states, interactions, or animations |
+| `showAlt` | `boolean` | false | When true, displays `altIcon` instead of `icon` |
+| `size` | `number` | 24 | Icon size in pixels |
+| `color` | `string` | currentColor | Icon color (any CSS color value) |
+| `strokeWidth` | `number` | 1.5 | Width of the icon strokes |
+| `class` | `string` | - | Additional CSS classes |
+
+### Svelte
+
+Install:
+
+```bash
+npm install @hugeicons/svelte @hugeicons/core-free-icons
+```
+
+Render:
+
+```svelte
+<script>
+  import { HugeiconsIcon } from '@hugeicons/svelte'
+  import { Search01Icon } from '@hugeicons/core-free-icons'
+</script>
+
+<!-- Only icon is required; pass other props only to override a default. -->
+<HugeiconsIcon icon={Search01Icon} />
+```
+
+Props:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `icon` | `IconSvgObject` | Required | The main icon to display (a named export from an icon package) |
+| `altIcon` | `IconSvgObject` | - | Alternative icon for states, interactions, or animations |
+| `showAlt` | `boolean` | false | When true, displays `altIcon` instead of `icon` |
+| `size` | `number` | 24 | Icon size in pixels |
+| `color` | `string` | currentColor | Icon color (any CSS color value) |
+| `strokeWidth` | `number` | 1.5 | Width of the icon strokes |
+| `class` | `string` | - | Additional CSS classes |
+
+### SolidJS
+
+Install:
+
+```bash
+npm install @hugeicons/solid-js @hugeicons/core-free-icons
+```
+
+> **Note:** The package is `@hugeicons/solid-js` — not `@hugeicons/solid`. "Solid" is also an icon
+> style (`@hugeicons-pro/core-solid-*`), so don't confuse the two.
+
+Render:
+
+```jsx
+import { HugeiconsIcon } from '@hugeicons/solid-js';
+import { Search01Icon } from '@hugeicons/core-free-icons';
+
+function App() {
+  // Only `icon` is required; pass other props only to override a default.
+  return <HugeiconsIcon icon={Search01Icon} />;
+}
+```
+
+Props:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `icon` | `IconSvgElement` | Required | The main icon to display (a named export from an icon package) |
+| `altIcon` | `IconSvgElement` | - | Alternative icon for states, interactions, or dynamic swapping |
+| `showAlt` | `boolean` | false | When true, displays `altIcon` instead of `icon` |
+| `size` | `number \| string` | 24 | Icon size in pixels |
+| `color` | `string` | currentColor | Icon color (any CSS color value) |
+| `strokeWidth` | `number` | 1.5 | Width of the icon strokes |
+| `absoluteStrokeWidth` | `boolean` | false | When true, stroke width is scaled relative to icon size |
+| `primaryColor` | `string` | - | Primary color for multicolor Pro icons (Bulk, Duotone, Twotone) |
+| `secondaryColor` | `string` | - | Secondary color for multicolor Pro icons |
+| `disableSecondaryOpacity` | `boolean` | false | Disables default opacity applied to the secondary color |
+| `class` | `string` | - | Additional CSS classes |
+
+### Angular
+
+Install:
+
+```bash
+npm install @hugeicons/angular @hugeicons/core-free-icons
+```
+
+> **Note:** The component is `HugeiconsIconComponent`, rendered via the `<hugeicons-icon>` selector. Import the icon in the component class and bind it with `[icon]`.
+
+Render:
+
+```typescript
+// example.component.ts
+import { Component } from '@angular/core'
+import { HugeiconsIconComponent } from '@hugeicons/angular'
+import { Search01Icon } from '@hugeicons/core-free-icons'
+
+@Component({
+  selector: 'app-example',
+  standalone: true,
+  imports: [HugeiconsIconComponent],
+  // Only [icon] is required; bind other props only to override a default.
+  template: `<hugeicons-icon [icon]="searchIcon" />`,
+})
+export class ExampleComponent {
+  searchIcon = Search01Icon
+}
+```
+
+Props:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `icon` | `IconSvgObject` | Required | The main icon to display (a named export from an icon package) |
+| `altIcon` | `IconSvgObject` | - | Alternative icon for states, interactions, or animations |
+| `showAlt` | `boolean` | false | When true, displays `altIcon` instead of `icon` |
+| `size` | `number` | 24 | Icon size in pixels |
+| `color` | `string` | currentColor | Icon color (any CSS color value) |
+| `strokeWidth` | `number` | 1.5 | Width of the icon strokes |
+| `class` | `string` | - | Additional CSS classes |
+
+### React Native
+
+Install:
+
+```bash
+npm install @hugeicons/react-native @hugeicons/core-free-icons
+```
+
+> **Note:** Color defaults to `#000000` (not `currentColor`) because React Native has no CSS color inheritance.
+
+Render:
+
+```jsx
+import { HugeiconsIcon } from '@hugeicons/react-native'
+import { Search01Icon } from '@hugeicons/core-free-icons'
+
+export default function App() {
+  // Only `icon` is required; pass other props only to override a default.
+  return <HugeiconsIcon icon={Search01Icon} />
+}
+```
+
+Props:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `icon` | `IconSvgObject` | Required | The main icon to display (a named export from an icon package) |
+| `altIcon` | `IconSvgObject` | - | Alternative icon for states, interactions, or animations |
+| `showAlt` | `boolean` | false | When true, displays `altIcon` instead of `icon` |
+| `size` | `number` | 24 | Icon size in pixels |
+| `color` | `string` | #000000 | Icon color (color string) |
+| `strokeWidth` | `number` | 1.5 | Width of the icon strokes |
+
+### Flutter
+
+Install:
+
+```bash
+flutter pub add hugeicons
+```
+
+> **Note:** Flutter bundles the icon data directly: `HugeIcons.*` constants are `List<List<dynamic>>` SVG path data, not `IconData`. Render with `HugeIcon`, never Flutter's `Icon`.
+
+Render:
+
+```dart
+import 'package:hugeicons/hugeicons.dart';
+
+// Only `icon` is required; color and size fall back to the ambient IconTheme.
+// Pass color/size only to override those defaults.
+HugeIcon(
+  icon: HugeIcons.strokeRoundedHome01,
+  color: Colors.black,
+)
+```
+
+Props:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `icon` | `List<List<dynamic>>` | Required | The icon data (a `HugeIcons.*` constant) — NOT a Flutter `IconData` |
+| `color` | `Color` | IconTheme color | Icon color; falls back to the ambient `IconTheme` |
+| `size` | `double` | 24.0 | Icon size in logical pixels; falls back to `IconTheme` size |
+| `strokeWidth` | `double` | - | Stroke thickness for stroke-style icons |
+
+
+## 4. Find an icon
+
+- **React, Vue, Svelte, SolidJS, Angular, React Native** — PascalCase named exports ending in `Icon` (e.g. `Search01Icon`, `Home01Icon`,
+  `Notification03Icon`). Number words are spelled out: `1st-bracket` → `FirstBracketIcon`,
+  `3d-view` → `ThreeDViewIcon`. Import from `@hugeicons/core-free-icons`.
+  Full list: [references/icon-list.md](references/icon-list.md) (5,471 icons).
+- **Flutter** — `HugeIcons.strokeRounded<Name>` constants (e.g. `HugeIcons.strokeRoundedSearch01`).
+  Full list: [references/icon-list-flutter.md](references/icon-list-flutter.md) (4,547 icons).
+
+**Grep these files — don't read them whole** (see the warning at the top). Search for a term,
+copy the **exact** matching name, and don't guess: many icons have numbered variants (`01`, `02`,
+`03`) — pick the one that best fits.
+
+## 5. Free vs Pro icons
+
+- **Free** (default): `@hugeicons/core-free-icons` — 6,000+ stroke-rounded icons. Suggest only these
+  unless the user has a Pro license.
+- **Pro** (license required, authenticated install): `@hugeicons-pro/core-stroke-rounded`, `@hugeicons-pro/core-stroke-sharp`, `@hugeicons-pro/core-stroke-standard`, `@hugeicons-pro/core-solid-rounded`, `@hugeicons-pro/core-solid-sharp`, `@hugeicons-pro/core-solid-standard`, `@hugeicons-pro/core-bulk-rounded`, `@hugeicons-pro/core-duotone-rounded`, `@hugeicons-pro/core-duotone-standard`, `@hugeicons-pro/core-twotone-rounded`.
+
+Never suggest a Pro-only icon to a free user — the import will fail.
+
+## Troubleshooting
+
+- **Icon not rendering**: confirm `icon` is a valid export/constant and not null.
+- **JS import fails**: the name is misspelled or Pro-only. Check the exact export in
+  `references/icon-list.md`.
+- **Flutter type error expecting `IconData`**: wrong type — Hugeicons constants are
+  `List<List<dynamic>>`. Render with `HugeIcon`, not `Icon`.