@maccesar/titools 3.2.0 → 3.3.0

package/skills/purgetss/references/custom-fonts.md

@@ -0,0 +1,289 @@
+# Custom Fonts
+
+Use the `purgetss/fonts/` folder and the `build-fonts` command to register any font in your Titanium app: brand typefaces, custom icon fonts, or community icon libraries that PurgeTSS no longer bundles.
+
+For the 4 official icon families that ship with PurgeTSS (Font Awesome 7, Material Icons, Material Symbols, Framework7), see [Icon Fonts](./icon-fonts.md) — they use the `icon-library` command and do **not** require `build-fonts`.
+
+## The `fonts` folder
+
+Place `.ttf` or `.otf` files in `./purgetss/fonts/`. For icon fonts, also include the `.css` file that ships with the library. PurgeTSS reads it to extract the Unicode characters for each icon class.
+
+This example uses [Bevan and Dancing Script](https://fonts.google.com/share?selection.family=Bevan:ital@0;1%7CDancing%20Script:wght@400;500;600;700) from Google Fonts:
+
+`./purgetss/fonts/`
+```bash
+purgetss
+└─ fonts
+   ├─ Bevan-Italic.ttf
+   ├─ Bevan-Regular.ttf
+   ├─ DancingScript-Bold.ttf
+   ├─ DancingScript-Medium.ttf
+   ├─ DancingScript-Regular.ttf
+   └─ DancingScript-SemiBold.ttf
+```
+
+### Organizing the fonts folder
+
+If you prefer to keep things tidy, group each family in a subfolder. The output is the same.
+
+`./purgetss/fonts/`
+```bash
+purgetss
+└─ fonts
+   └─ bevan
+      ├─ Bevan-Italic.ttf
+      └─ Bevan-Regular.ttf
+   └─ dancing-script
+      ├─ DancingScript-Bold.ttf
+      ├─ DancingScript-Medium.ttf
+      ├─ DancingScript-Regular.ttf
+      └─ DancingScript-SemiBold.ttf
+```
+
+## The `build-fonts` command
+
+```bash
+$ purgetss build-fonts [-m] [-f]
+
+# alias:
+$ purgetss bf [-m] [-f]
+```
+
+What it does:
+
+1. Creates `./purgetss/styles/fonts.tss` with one `fontFamily` class per file.
+2. Copies the font files into `./app/assets/fonts/`, renamed to their PostScript names so they work on both iOS and Android.
+
+After running `purgetss build-fonts` with the Bevan and Dancing Script example above:
+
+`./purgetss/styles/fonts.tss`
+```css
+// Fonts TSS file generated with PurgeTSS
+// https://purgetss.com/docs/customization/custom-fonts
+
+'.bevan-italic': { font: { fontFamily: 'Bevan-Italic' } }
+'.bevan-regular': { font: { fontFamily: 'Bevan-Regular' } }
+
+'.dancingscript-bold': { font: { fontFamily: 'DancingScript-Bold' } }
+'.dancingscript-medium': { font: { fontFamily: 'DancingScript-Medium' } }
+'.dancingscript-regular': { font: { fontFamily: 'DancingScript-Regular' } }
+'.dancingscript-semibold': { font: { fontFamily: 'DancingScript-SemiBold' } }
+```
+
+You can now use these classes on any Titanium component with a `font` property: Labels, Buttons, TextFields, TextAreas, ListItems, TableViewRows, and ActivityIndicators.
+
+### Renaming the class
+
+To use a shorter or different class name, rename the font file. For example:
+
+`./purgetss/fonts/`
+```bash
+purgetss
+└─ fonts
+   └─ dancing-script
+      ├─ Script-Bold.ttf
+      ├─ Script-Medium.ttf
+      ├─ Script-Regular.ttf
+      └─ Script-SemiBold.ttf
+```
+
+Running `build-fonts` produces:
+
+`./purgetss/styles/fonts.tss`
+```css
+'.script-bold': { font: { fontFamily: 'DancingScript-Bold' } }
+'.script-medium': { font: { fontFamily: 'DancingScript-Medium' } }
+'.script-regular': { font: { fontFamily: 'DancingScript-Regular' } }
+'.script-semibold': { font: { fontFamily: 'DancingScript-SemiBold' } }
+```
+
+The class name changes, but the actual `fontFamily` value (the PostScript name) stays the same.
+
+## Adding icon fonts
+
+Any icon font that ships a `.ttf` (or `.otf`) plus a `.css` file with Unicode characters works the same way.
+
+This example uses [map-icons](http://map-icons.com) and [microns](https://www.s-ings.com/projects/microns-icon-font/):
+
+`./purgetss/fonts/`
+```bash
+purgetss
+└─ fonts
+   └─ bevan
+   └─ dancing-script
+   └─ map-icons
+      ├─ map-icons.css
+      └─ map-icons.ttf
+   └─ microns
+      ├─ microns.css
+      └─ microns.ttf
+```
+
+After `purgetss build-fonts`, the generated `fonts.tss` includes the family classes and one class per icon:
+
+`./purgetss/styles/fonts.tss`
+```css
+// Fonts TSS file generated with PurgeTSS
+// https://purgetss.com/docs/customization/custom-fonts
+
+'.map-icons': { font: { fontFamily: 'map-icons' } }
+'.microns': { font: { fontFamily: 'microns' } }
+
+/* Unicode Characters */
+/* To use your Icon Fonts in Buttons AND Labels each class sets 'text' and 'title' properties */
+
+/* map-icons/map-icons.css */
+'.map-icon-abseiling': { text: '', title: '' }
+'.map-icon-accounting': { text: '', title: '' }
+'.map-icon-airport': { text: '', title: '' }
+'.map-icon-amusement-park': { text: '', title: '' }
+'.map-icon-aquarium': { text: '', title: '' }
+/* ... */
+
+/* microns/microns.css */
+'.mu-arrow-left': { text: '', title: '' }
+'.mu-arrow-right': { text: '', title: '' }
+'.mu-arrow-up': { text: '', title: '' }
+'.mu-arrow-down': { text: '', title: '' }
+'.mu-left': { text: '', title: '' }
+/* ... */
+```
+
+## Options
+
+Two optional flags adjust what `build-fonts` generates:
+
+- `-m, --module`: generates a CommonJS module in `./app/lib/purgetss.fonts.js` that exposes each icon's Unicode string to JavaScript. Handy when you set `label.text` from a controller.
+- `-f, --font-class-from-filename`: uses the font's filename as the font class name and icon prefix instead of the font family name. Useful when you want shorter prefixes. Replaces the old `-p` flag.
+
+### Using `--module`
+
+```bash
+$ purgetss build-fonts --module
+
+# alias:
+$ purgetss bf -m
+```
+
+To avoid prefix conflicts between libraries, each icon keeps its prefix as a nested object. Both `icons` and `families` are exported:
+
+`./app/lib/purgetss.fonts.js`
+```javascript
+const icons = {
+  // map-icons/map-icons.css
+  'mapIcon': {
+    'abseiling': '',
+    'accounting': '',
+    'airport': '',
+    'amusementPark': '',
+    // ...
+  },
+  // microns/microns.css
+  'mu': {
+    'arrowLeft': '',
+    'arrowRight': '',
+    'arrowUp': '',
+    'arrowDown': '',
+    // ...
+  }
+};
+exports.icons = icons;
+
+const families = {
+  // map-icons/map-icons.css
+  'mapIcon': 'map-icons',
+  // microns/microns.css
+  'mu': 'microns'
+};
+exports.families = families;
+```
+
+### Using `--font-class-from-filename`
+
+When you want the class name and the icon prefix to come from the **filename** of the `.ttf` and `.css` instead of the font family, use `-f`.
+
+`./purgetss/fonts/`
+```bash
+purgetss
+└─ fonts
+   └─ map-icons
+      ├─ map.ttf
+      └─ mp.css
+   └─ microns
+      ├─ mic.ttf
+      └─ mc.css
+```
+
+`./purgetss/styles/fonts.tss`
+```css
+/* "fontFamily" classes use the font's filename */
+'.map': { font: { fontFamily: 'map-icons' } }
+'.mic': { font: { fontFamily: 'microns' } }
+
+/* map-icons/mp.css */
+'.mp-abseiling': { text: '', title: '' }
+'.mp-accounting': { text: '', title: '' }
+'.mp-airport': { text: '', title: '' }
+'.mp-amusement-park': { text: '', title: '' }
+'.mp-aquarium': { text: '', title: '' }
+/* ... */
+
+/* microns/mc.css */
+'.mc-arrow-left': { text: '', title: '' }
+'.mc-arrow-right': { text: '', title: '' }
+'.mc-arrow-up': { text: '', title: '' }
+'.mc-arrow-down': { text: '', title: '' }
+'.mc-left': { text: '', title: '' }
+/* ... */
+```
+
+`./app/lib/purgetss.fonts.js`
+```javascript
+const icons = {
+  // map-icons/mp.css
+  'mp': {
+    'abseiling': '',
+    'accounting': '',
+    'airport': '',
+    'amusementPark': '',
+    // ...
+  },
+  // microns/mc.css
+  'mc': {
+    'arrowLeft': '',
+    'arrowRight': '',
+    'arrowUp': '',
+    'arrowDown': '',
+    // ...
+  }
+};
+exports.icons = icons;
+
+const families = {
+  // map-icons/mp.css
+  'mp': 'map-icons',
+  // microns/mc.css
+  'mc': 'microns'
+};
+exports.families = families;
+```
+
+> 🛑 **DANGER**
+> Make sure the new prefix is unique and does not conflict with other class prefixes. A duplicate prefix will silently overwrite earlier rules in the generated `fonts.tss`, leaving you with icons that render the wrong glyph at runtime.
+
+## Custom proprietary icon fonts
+
+If your design system ships its own icon font, treat it like any other icon library: drop the `.ttf` + `.css` pair into `./purgetss/fonts/<name>/` and run `build-fonts`. The classes are then available in your TSS.
+
+## Community-Discovered Patterns
+
+The following notes reflect community experience with `build-fonts` against real-world Titanium projects.
+
+> **💡 PostScript renaming**
+> `build-fonts` copies `.ttf`/`.otf` files into `./app/assets/fonts/` renamed to their **PostScript names**. iOS reads PostScript names while Android tolerates filenames; by renaming both platforms work from the same `fontFamily` value.
+
+> **🛑 Font Awesome Duotone**
+> Titanium cannot render Font Awesome duotone icons because each icon uses two glyphs. If you work with Font Awesome Pro, avoid documenting duotone as supported.
+
+> **💡 Use `--module` to set `text`/`title` from JavaScript**
+> Hardcoding `` in a controller is brittle. The `-m` flag generates a `purgetss.fonts.js` you can `require()` and reference by friendly name: `label.text = icons.fa.home`. Combine with `families` to set `font.fontFamily` programmatically.

package/skills/purgetss/references/icon-fonts.md

@@ -1,176 +1,264 @@
 # Icon Font Libraries
 
+PurgeTSS ships with four official icon font families, each preconfigured with the TSS classes and `fontFamily` mappings you need to drop icons into Buttons, Labels, and TextFields.
+
+For user-defined fonts (Google Fonts, brand typefaces, community icon libraries like map-icons or microns), see [Custom Fonts](./custom-fonts.md) — those use `build-fonts`, not `icon-library`.
+
 > ℹ️ **INFO — Official Icon Fonts for PurgeTSS**
->
-> Older versions of PurgeTSS bundled additional icon font libraries — Bootstrap Icons, Boxicons, LineIcons, and Tabler Icons among them. **Those libraries have been deprecated and removed from the official distribution** to keep maintenance under control. They are still usable, but you must rebuild them yourself with `build-fonts` (see below).
->
-> The icon fonts officially supported and shipped by PurgeTSS today are:
->
 > - [Font Awesome 7 Free](https://fontawesome.com) (upgrade with `purgetss il -v=fa`)
-> - [Framework 7](https://framework7.io/icons/)
+> - [Framework 7 Icons](https://framework7.io/icons/)
 > - [Material Icons](https://fonts.google.com/icons?icon.set=Material+Icons)
 > - [Material Symbols](https://fonts.google.com/icons?icon.set=Material+Symbols)
+>
+> Older versions of PurgeTSS bundled additional libraries (Bootstrap Icons, Boxicons, LineIcons, Tabler Icons). They were removed to keep maintenance under control, but you can [recreate them at the bottom of this page](#recreating-removed-icon-libraries).
 
-For the official install flow for the supported vendors, see [CLI Commands](./cli-commands.md#icon-library-command).
+## Icon families reference
 
-## Recreate Removed Libraries
+Each family ships one or more variant classes, each pointing to a specific font file. Combine a variant class with an icon class to render a glyph. For example, `msr ms-home` uses the Material Symbols Rounded font with the `home` icon.
 
-You can recreate any deprecated library using the `build-fonts` command.
+| Family | Variant | Class | `fontFamily` |
+|---|---|---|---|
+| **Material Symbols** | Outlined (default) | `.ms` | `MaterialSymbolsOutlined-Regular` |
+| Material Symbols | Outlined (alias) | `.mso` | `MaterialSymbolsOutlined-Regular` |
+| Material Symbols | Rounded | `.msr` | `MaterialSymbolsRounded-Regular` |
+| Material Symbols | Sharp | `.mss` | `MaterialSymbolsSharp-Regular` |
+| **Font Awesome** | Solid (default) | `.fa` | `FontAwesome7Free-Solid` |
+| Font Awesome | Solid (alias) | `.fas` | `FontAwesome7Free-Solid` |
+| Font Awesome | Regular | `.far` | `FontAwesome7Free-Regular` |
+| Font Awesome | Brands | `.fab` | `FontAwesome7Brands-Regular` |
+| **Material Icons** | Regular | `.mi` | `MaterialIcons-Regular` |
+| **Framework 7** | Regular | `.f7` | `Framework7-Icons` |
 
-### 1. Download the Libraries
+> 💡 **TIP — Icon class names**
+> Across a family, the icon class is shared by every variant. For Material Symbols, there is one `ms-home` class; pair it with `.ms`, `.mso`, `.msr`, or `.mss` to pick the shape (outlined, rounded, or sharp). FontAwesome works the same way: `fa-home` pairs with `.fa`/`.fas` (Solid) or `.far` (Regular), while brand icons like `fa-github` need `.fab`. **The variant class chooses the font file. The icon class chooses the glyph.**
 
-Start by downloading the libraries from their official websites:
+### Full class lists
 
-- [Bootstrap Icons](https://icons.getbootstrap.com)
-- [Boxicons](https://boxicons.com)
-- [LineIcons](https://lineicons.com/icons/?type=free)
-- [Tabler Icons](https://tabler-icons.io)
+The complete class definitions live in the PurgeTSS `dist/` folder:
 
-### 2. The `fonts` Folder
+- [fontawesome.tss](https://github.com/macCesar/purgeTSS/blob/main/dist/fontawesome.tss)
+- [materialicons.tss](https://github.com/macCesar/purgeTSS/blob/main/dist/materialicons.tss)
+- [materialsymbols.tss](https://github.com/macCesar/purgeTSS/blob/main/dist/materialsymbols.tss)
+- [framework7icons.tss](https://github.com/macCesar/purgeTSS/blob/main/dist/framework7icons.tss)
 
-Put the desired libraries in the `./purgetss/fonts` folder.
+## Installing the icon fonts
 
-> ℹ️ **INFO**
-> Copy the TrueType or OpenType font files and the `.css` file.
+Run `icon-library` to copy the `.ttf` files into `./app/assets/fonts/`. That is the only step you need. Once the fonts are in place, the icon classes from the table above work out of the box.
 
 ```bash
-purgetss
-└─ fonts
-   └─ boxicons
-      ├─ boxicons.css
-      └─ boxicons.ttf
-   └─ lineicons
-      ├─ lineicons.css
-      └─ lineicons.ttf
+# All four families
+$ purgetss icon-library
+
+# Selective install
+$ purgetss il -v=fa,mi,ms,f7
 ```
 
-### 3. The `build-fonts` Command
+> ℹ️ **INFO — You do not need the `.tss` files in `./purgetss/styles/`**
+> PurgeTSS already knows every official icon class and resolves them at compile time from its own bundled `dist/` files. You do not need `fontawesome.tss`, `materialsymbols.tss`, `materialicons.tss`, or `framework7icons.tss` inside `./purgetss/styles/` for `class="fas fa-home"` (or any other icon class) to work in your XML and controllers. Install the `.ttf` files with `icon-library` and the classes are ready.
+
+### Optional flags
 
-Run the `build-fonts` command to create a custom `fonts.tss` file.
+Two optional flags adjust what `icon-library` copies into your project:
+
+- `-s, --styles`: copies the official `.tss` source files into `./purgetss/styles/` for reference only. Useful if you want to grep the full class list, see how a class is defined, or override a specific class in your own project.
+- `-m, --module`: copies the matching CommonJS module into `./app/lib/`, which exposes each icon's Unicode string to JavaScript. Handy when you set `label.text` from a controller and prefer a friendly name like `icons.fa.home` over a raw ``.
 
 ```bash
-purgetss build-fonts [--modules]
+# Add either flag when you want them
+$ purgetss il -s
+$ purgetss il -m
+$ purgetss il -m -s
+```
+
+### Vendor aliases
+
+`--vendor` accepts the short or long forms:
+
+- `fa`, `fontawesome` = Font Awesome Icons
+- `mi`, `materialicons` = Material Icons
+- `ms`, `materialsymbol` = Material Symbols
+- `f7`, `framework7` = Framework7 Icons
+
+## Using icons in XML
+
+The variant class sets the `fontFamily`. The icon class sets the glyph (`text` / `title`). Apply both together:
+
+`index.xml`
+```xml
+<Alloy>
+  <Window>
+    <View class="grid">
+      <View class="vertical mx-auto grid-cols-2 gap-y-2">
+        <!-- Material Symbols variants -->
+        <Label class="mt-2 text-gray-700" text="Material Symbols" />
+        <Button class="ms ms-home my-1 h-10 w-10 text-xl text-blue-500" />
+        <Button class="msr ms-home my-1 h-10 w-10 text-xl text-blue-500" />
+        <Button class="mss ms-home my-1 h-10 w-10 text-xl text-blue-500" />
+      </View>
+
+      <View class="vertical mx-auto grid-cols-2 gap-y-2">
+        <!-- FontAwesome variants -->
+        <Label class="mt-2 text-gray-700" text="Font Awesome" />
+        <Button class="fas fa-home my-1 h-10 w-10 text-xl text-blue-500" />
+        <Button class="far fa-bell my-1 h-10 w-10 text-xl text-blue-500" />
+        <Button class="fab fa-github my-1 h-10 w-10 text-xl text-blue-500" />
+      </View>
+    </View>
+  </Window>
+</Alloy>
+```
 
-# alias:
-purgetss bf [-m]
+## Complete example with all four families
+
+A side-by-side example using all four official families.
+
+To use this file:
+
+- Copy the content of `index.xml` into a new Alloy project.
+- Install the official icon font files using `purgetss icon-library` (without `--vendor`, PurgeTSS copies all official icon fonts).
+- Run `purgetss` once to generate the required files.
+- Compile your app as usual.
+- Use `liveview` if you want faster testing.
+
+`index.xml`
+```xml
+<Alloy>
+  <Window>
+    <View class="grid">
+      <View class="vertical mx-auto grid-cols-2 gap-y-2">
+        <!-- FontAwesome -->
+        <Label class="mt-2 text-gray-700" text="FontAwesome" />
+        <Button class="fa fa-home my-1 h-10 w-10 text-xl text-blue-500" />
+        <Button class="fa fa-home my-1 h-10 w-10 rounded bg-blue-500 text-xl text-white" />
+      </View>
+
+      <View class="vertical mx-auto grid-cols-2 gap-y-2">
+        <!-- Material Icons -->
+        <Label class="mt-2 text-gray-700" text="Material Icons" />
+        <Button class="mi mi-home my-1 h-10 w-10 text-xl text-blue-500" />
+        <Button class="mi mi-home my-1 h-10 w-10 rounded bg-blue-500 text-xl text-white" />
+      </View>
+
+      <View class="vertical mx-auto grid-cols-2 gap-y-2">
+        <!-- Material Symbols -->
+        <Label class="mt-2 text-gray-700" text="Material Symbol" />
+        <Button class="ms ms-home my-1 h-10 w-10 text-xl text-blue-500" />
+        <Button class="ms ms-home my-1 h-10 w-10 rounded bg-blue-500 text-xl text-white" />
+      </View>
+
+      <View class="vertical mx-auto grid-cols-2 gap-y-2">
+        <!-- Framework7-Icons -->
+        <Label class="mt-2 text-gray-700" text="Framework7-Icons" />
+        <Button class="f7 f7-house my-1 h-10 w-10 text-xl text-blue-500" />
+        <Button class="f7 f7-house my-1 h-10 w-10 rounded bg-blue-500 text-xl text-white" />
+      </View>
+    </View>
+  </Window>
+</Alloy>
 ```
 
-### The `fonts.tss` File
+Generated `app.tss` excerpt:
+```css
+// PurgeTSS v7.10.2
+// Created by César Estrada
+// https://purgetss.com
 
-The `build-fonts` command generates `./purgetss/styles/fonts.tss` with Unicode characters and style rules.
+/* Ti Elements */
+'View': { width: Ti.UI.SIZE, height: Ti.UI.SIZE }
+'Window': { backgroundColor: '#FFFFFF' }
 
-`./purgetss/styles/fonts.tss`
-```tss
-'.boxicons': { font: { fontFamily: 'boxicons' } }
-'.lineicons': { font: { fontFamily: 'LineIcons' } }
+/* Default Font Awesome */
+'.fa': { font: { fontFamily: 'FontAwesome7Free-Solid' } }
+'.fa-home': { text: '', title: '' }
 
-/* Unicode Characters */
-/* To use your Icon Fonts in Buttons AND Labels each class sets 'text' and 'title' properties */
+/* Material Icons */
+'.mi': { font: { fontFamily: 'MaterialIcons-Regular' } }
+'.mi-home': { text: '', title: '' }
 
-/* boxicons.css */
-'.bxl-meta': { text: '', title: '' }
-'.bx-lemon': { text: '', title: '' }
-/* ... */
+/* Material Symbols */
+'.ms': { font: { fontFamily: 'MaterialSymbolsOutlined-Regular' } }
+'.ms-home': { text: '', title: '' }
 
-/* lineicons.css */
-'.lni-500px': { text: '', title: '' }
-'.lni-add-files': { text: '', title: '' }
-/* ... */
+/* Framework7 */
+'.f7': { font: { fontFamily: 'Framework7-Icons' } }
+'.f7-house': { text: 'house', title: 'house' }
 ```
 
-### Rename the Style Rule Name
+## Customizing Font Awesome
 
-PurgeTSS uses the font file name as the style rule name. You can change it by renaming the font file.
+If you have a [Font Awesome Pro account](https://fontawesome.com/pro) or want to try the Beta, PurgeTSS can generate a custom `./purgetss/styles/fontawesome.tss` with the Pro or Beta classes.
 
-`./purgetss/fonts/`
-```bash
-purgetss
-└─ fonts
-   └─ boxicons
-      └─ bx.ttf
-```
+### Font Awesome Pro
 
-New style rule name: `'.bx'`
+After setting the [@fortawesome scope](https://fontawesome.com/how-to-use/on-the-web/setup/using-package-managers#installing-pro) with your token, install it in your project's root folder with `npm init` and `npm install --save-dev @fortawesome/fontawesome-pro` (current version 7.1.0).
 
-```tss
-'.bx': { font: { fontFamily: 'boxicons' } }
-```
+To generate a new `purgetss/styles/fontawesome.tss`, run `purgetss build`. It also copies the Pro font files into `./app/assets/fonts` if needed.
 
-### The `assets/fonts` Folder
+Note: Titanium cannot use Font Awesome duotone icons because each icon uses two glyphs.
 
-The `build-fonts` command copies the font files to `./app/assets/fonts` and renames them to their PostScript names so they work on both iOS and Android.
+### Font Awesome 7 Beta
 
-```bash
-app
-└─ assets
-   └─ fonts
-      ├─ boxicons.ttf
-      └─ LineIcons.ttf
-```
+To generate a custom `fontawesome.tss` file from [Font Awesome 7 Beta](https://fontawesome.com/download):
 
-### The `--modules` Option
-
-When you use the `--modules` option, it generates a `./app/lib/purgetss.fonts.js` CommonJS module file.
-
-`./app/lib/purgetss.fonts.js`
-```javascript
-const icons = {
-  /* boxicons */
-  boxicons: {
-    bxlMeta: '',
-    bxLemon: ''
-    /* ... */
-  },
-  /* lineicons */
-  lni: {
-    '500px': '',
-    addFiles: ''
-    /* ... */
-  }
-};
-exports.icons = icons;
-```
+Move the `css` and `webfonts` folders from `fontawesome-pro-7.0.0-beta3-web/`:
 
-### The `--prefix` Option
+```bash
+fontawesome-pro-7.0.0-beta3-web
+└─ css
+└─ webfonts
+```
 
-PurgeTSS determines the group's prefix for each icon family and class name. Use `--prefix` to apply the style's filename as the prefix for class names in `fonts.tss` and property names in `purgetss.fonts.js`.
+Into `./purgetss/fontawesome-beta`:
 
-`./purgetss/fonts/`
 ```bash
 purgetss
-└─ fonts
-   └─ lineicons
-      └─ li.css
+└─ fontawesome-beta
+   ├─ css
+   └─ webfonts
 ```
 
-New group prefix: `li`
+Then run `purgetss build` to generate your custom `fontawesome.tss` file and test the new icons.
+
+## Recreating removed icon libraries
+
+Older versions of PurgeTSS bundled Bootstrap Icons, Boxicons, LineIcons, and Tabler Icons. The list was trimmed to make maintenance easier, but you can rebuild any of them:
+
+1. Download the library from its official site:
+   - [Bootstrap Icons](https://icons.getbootstrap.com)
+   - [Boxicons](https://boxicons.com)
+   - [LineIcons](https://lineicons.com/icons/?type=free)
+   - [Tabler Icons](https://tabler-icons.io)
+2. Place the `.ttf`/`.otf` and `.css` files into `./purgetss/fonts/<library>/`.
+3. Run `purgetss build-fonts`.
+
+For the underlying mechanics (how `build-fonts` reads the `.css`, options like `-m` and `-f`), see [Custom Fonts](./custom-fonts.md).
+
+### `fonts.tss` example
+
+```css
+'.boxicons': { font: { fontFamily: 'boxicons' } }
+'.lineicons': { font: { fontFamily: 'LineIcons' } }
+
+/* Unicode Characters */
+/* To use your Icon Fonts in Buttons AND Labels each class sets 'text' and 'title' properties */
 
-`./purgetss/styles/fonts.tss`
-```tss
-/* lineicons/li.css */
-'.li-zoom-out': { text: '', title: '' }
-'.li-zoom-in': { text: '', title: '' }
+/* boxicons.css */
+'.bxl-meta': { text: '', title: '' }
+'.bx-lemon': { text: '', title: '' }
 /* ... */
-```
 
-`./app/lib/purgetss.fonts.js`
-```javascript
-const icons = {
-  /* lineicons/li.css */
-  li: {
-    /* ... */
-  }
-};
-exports.icons = icons;
+/* lineicons.css */
+'.lni-500px': { text: '', title: '' }
+'.lni-add-files': { text: '', title: '' }
+/* ... */
 ```
 
-> 🛑 **DANGER**
->
-> Make sure the new prefix stays unique so it does not collide with other class prefixes. A duplicate prefix will silently overwrite earlier rules in the generated `fonts.tss`, leaving you with icons that render the wrong glyph at runtime.
-
 ## Community-Discovered Patterns
 
 The following note reflects community experience working with icon fonts that depend on multiple glyphs per icon.
 
 > 🛑 **DANGER — Font Awesome Duotone**
 > Titanium cannot render Font Awesome duotone icons correctly because each icon uses two glyphs. If you work with Font Awesome Pro, avoid documenting duotone as supported.
+
+> 💡 **Mixing variant + icon in `class=`**
+> A common mistake is omitting the variant class and writing just `class="fa-github"`. The icon class only sets `text`/`title` (the glyph) — without the variant class (`.fa`, `.fas`, `.fab`, etc.) the `fontFamily` is missing and the glyph renders as the system font's fallback character. Always include both: `class="fab fa-github"` or `class="msr ms-home"`.