|
| 1 | +# AI Assistant Project Guide: Fluent UI System Icons |
| 2 | + |
| 3 | +Purpose: Enable rapid, correct contributions across multi-platform icon packages (web React, React Native, SVG assets/sprites, Android, iOS, Flutter) generated from a single `assets/` source. |
| 4 | + |
| 5 | +## Core Architecture |
| 6 | +- Targeted package instructions: see `./react-icons.instructions.md` (auto-applies when working inside `packages/react-icons`). |
| 7 | +- Source of truth: Raw SVG design assets in `assets/` (folder names = icon groups). Each icon has metadata (directionality handled via RTL processing scripts) and fixed primary fill `#212121` (validation enforced in CI). |
| 8 | +- Generated outputs per platform: |
| 9 | + - React web: `@fluentui/react-icons` → JSX components + optional font implementation. Build pipeline: asset -> optimized SVG (`intermediate/`) -> component TS in `src/` -> compiled output in `lib/` (ESM) & `lib-cjs/` (CJS) + `fonts/` bundle + merged `metadata.json`. |
| 10 | + - React Native: Similar SVG -> `intermediate/` -> RN components in `src/`; styling more limited (no Griffel styling utilities). |
| 11 | + - Plain SVG package: `@fluentui/svg-icons` emits optimized renamed raw SVGs in `packages/svg-icons/icons/` following `[name]_[size]_[style].svg`. |
| 12 | + - Sprites: `@fluentui/svg-sprites` converts single SVGs to per-icon sprite files: `<icon>.sprite.svg` for on-demand `<use href="/sprites/{id}.sprite.svg#id" />` consumption. |
| 13 | + - Fonts: Generated via `importer/generateFont.js` (Regular/Filled/Light/Resizable) feeding React font condition and Flutter/iOS/Android. |
| 14 | + - Native (Android/iOS/Flutter): Produced by `importer` deployment scripts (`deploy:android`, `deploy:ios`, `deploy:flutter`) which transform assets into vector drawables / PDF assets / Dart classes. |
| 15 | + |
| 16 | +## Key Workflows (Local) |
| 17 | +- Install deps (root + packages): `npm ci` at repo root (Yarn/PNPM NOT configured; uses npm workspaces). |
| 18 | +- React icons build (full): `cd packages/react-icons && npm run build` (runs font + svg generation + JS emission). Quick validation only: `npm run build:verify` (Vitest metadata checks). |
| 19 | +- React Native icons build: `cd packages/react-native-icons && npm run build`. |
| 20 | +- SVG raw assets: `cd packages/svg-icons && npm run build`. |
| 21 | +- Sprites: `cd packages/svg-sprites && npm run build`. |
| 22 | +- Importer operations (multi-platform generation & version bumps): `cd importer && npm run deploy:android|deploy:ios|deploy:fonts`. |
| 23 | +- Clean React icons intermediates: `npm run clean` in each package (removes generated `lib*` and `intermediate/`). Avoid manual deletion to keep scripts deterministic. |
| 24 | + |
| 25 | +## CI Expectations / Pitfalls |
| 26 | +- PR validation (`.github/workflows/pr.yml`) enforces: (1) asset folder names not ending with space; (2) all non-color SVGs include `fill="#212121"` (except `*_color.svg` which are skipped). Maintain fill when editing SVGs; use scripts (`optimize`, `unfill`) instead of hand-edits. |
| 27 | +- React build job runs `lint`, full `build`, and `build:verify`; keep TypeScript version constraints (TS ~4.1) when adding language features. |
| 28 | +- iOS/Android build jobs rely on importer output; ensure importer scripts still produce expected file layout when modifying generation logic. |
| 29 | + |
| 30 | +## Conventions & Patterns |
| 31 | +- Icon naming (React / RN): `AccessTimeFilled` (state suffix) and sized variants `AccessTime24Filled`. General (resizable) variant without size preferred for flexible UI. |
| 32 | +- Plain SVG file naming: lowercase + underscores from original asset folder; pattern: `mail_24_filled.svg`. |
| 33 | +- Sprite consumption id pattern: `{name}_{size}_{style}` (mirrors SVG file stem) reused inside `#symbol` id. |
| 34 | +- Directionality: `rtlMetadata.js` generates `intermediate/rtl.json`; keep this in sync when adding new directional icons. Metadata merging occurs via `convert:merge-metadata`. |
| 35 | +- Fonts: Four iconType variants (Regular/Filled/Light/Resizable). New styles require updating font generation pipeline (all `generate:font-*` scripts and metadata merge). |
| 36 | +- Export map (`packages/react-icons/package.json` `exports`) uses conditional `fluentIconFont`; when adjusting build output paths, update both `lib` and `lib-cjs` mappings consistently. |
| 37 | +- React styling: Components accept `primaryFill`, `className`; compound icon pattern uses `bundleIcon(Filled, Regular)` plus `iconFilledClassName` / `iconRegularClassName` for state toggling. |
| 38 | + |
| 39 | +## Typical Change Flow (Add / Update Icons) |
| 40 | +1. Add raw SVG(s) to appropriate new/existing folder in `assets/` (ensure fill `#212121`). |
| 41 | +2. If direction-specific, set metadata / ensure RTL logic recognizes (inspect or extend `rtlMetadata.js`). |
| 42 | +3. Run relevant package builds (e.g., `packages/react-icons` build) to regenerate components and fonts. |
| 43 | +4. Run `npm run build:verify` in React icons to confirm metadata & generation integrity. |
| 44 | +5. Commit generated outputs (generated code is tracked—do not manually edit `lib/` outputs; edit sources or generation scripts instead). |
| 45 | +6. Let CI validate fills & builds. |
| 46 | + |
| 47 | +## When Modifying Generators |
| 48 | +- Prefer changes inside `importer/` scripts (e.g., `generate.js`, `generateFont.js`) to altering per-package build steps; keep script flags consistent (`--source`, `--dest`, `--extension`, `--target`, `--iconType`). |
| 49 | +- After script changes, rebuild at least one consumer package to ensure no path/flag regressions. |
| 50 | + |
| 51 | +## Platform-Specific Notes |
| 52 | +- React Native: Limited styling (no Griffel). Avoid introducing DOM-specific props. |
| 53 | +- iOS: Enum-based access (`UIImage(fluent: .appStore24Filled)`); asset stripping tool in `ios/remove-unused-fluent-icons` must still find & parse asset names—keep naming stable. |
| 54 | +- Android: Vector drawable tint placeholder replaced (`@color/fluent_default_icon_tint`) during finalize step; avoid hardcoding other colors. |
| 55 | +- Flutter: Icon classes generated from font codepoint JSON; if glyph sets change, regenerate fonts first then Flutter classes. |
| 56 | + |
| 57 | +## Safe Extensions / Additions |
| 58 | +- New icon style variant: add generation script, extend metadata merge, update exports if needed. |
| 59 | +- New distribution format (e.g., consolidated sprite index): create new package under `packages/` and reuse `importer/generate.js` with new flags. |
| 60 | + |
| 61 | +## Avoid |
| 62 | +- Manual edits to generated `lib/`, `lib-cjs/`, `icons/`, `sprites/` files. |
| 63 | +- Upgrading TypeScript/Babel broadly without verifying downstream package constraints & CI. |
| 64 | +- Introducing SVG fills other than `#212121` (unless *_color.svg purposefully multi-colored). |
| 65 | + |
| 66 | +## Quick Validation Checklist Before PR |
| 67 | +- Builds succeed for changed packages. |
| 68 | +- No asset directories with trailing spaces. |
| 69 | +- All new SVGs pass fill rule. |
| 70 | +- React icons `build:verify` passes. |
| 71 | +- Metadata (`metadata.json`) updated if generation logic changed. |
0 commit comments