@maccesar/titools 3.2.0 → 3.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,25 +1,6 @@
1
1
  # PurgeTSS CLI Commands
2
2
 
3
- > **Info: What's new in v7.5.3 / v7.6.x / v7.7.0 / v7.8.0 / v7.9.0**
4
- > - **Opacity modifiers on semantic colors (v7.9.0)** — writing `bg-surface/65` (or any opacity modifier on a class mapped to a name in `semantic.colors.json`) now produces a working rule with Light/Dark switching preserved. PurgeTSS auto-derives a `<originalKey>_<alphaPercent>` entry in `semantic.colors.json` with the original `light`/`dark` hex values plus the requested alpha for both modes, then emits the rule against the derived key. Re-runs are idempotent; manual edits with conflicting values halt the build with a `Conflict` error. New alpha entries require one full Titanium build to be picked up — Liveview hot-reload alone does not refresh `semantic.colors.json`.
5
- > - **Gradient + Window/View/ImageView preset fixes (v7.9.0)** — `theme.Window` / `theme.View` / `theme.ImageView` no longer leak the framework presets (white background, `Ti.UI.SIZE`, iOS `hires: true`) when defined at the top level (replace mode), so a Window declared at `theme.Window` with a `backgroundGradient` no longer ghosts on top of a default `backgroundColor: '#FFFFFF'`. `theme.extend.Window` keeps merging with the defaults as before. Also fixed: tonal palette inversion bug, position-dependent `from`/`to` color ordering after `sort()`, and `bg-gradient-to-X` direction silently dropped when combined with `from-X to-Y` colors.
6
- > - **Glossary path renamed (v7.9.0, breaking)** — the user-facing glossary output path was renamed from `purgetss/experimental/tailwind-classes/` to `purgetss/glossary/tailwind-classes/`. Tooling or CI that reads from the old path needs updating on upgrade — no transition shim. The `--glossary` flag and command surface are unchanged.
7
- > - **`images --width <n>` flag (v7.8.0)** — pins Android `mdpi` (= iPhone `@1x`) to a specific pixel width, with larger scales deriving as ×1.5, ×2, ×3, ×4 from that base. Use it for SVG sources from vector editors with disproportionate viewBoxes (Affinity, Illustrator). CLI-only; there is no matching `images:` config property because the right width is per-asset. See [`images` Command](#images-command).
8
- > - **Class syntax pre-validation (v7.8.0)** — `purgetss` now stops with a structured `Class Syntax Error` block (file + line + suggested fix) when it detects known class-name mistakes: inverted negative sign (`top-(-10)` → `-top-(10)`), Tailwind-style brackets (`top-[10px]` → `top-(10px)`), empty parentheses (`wh-()`), whitespace inside parentheses (`wh-( 200 )`), and redundant `px` unit (`top-(10px)` → `top-(10)`). All offenders are reported in one run. Generic unknown classes still flow into the `// Unused or unsupported classes` block in `app.tss`.
9
- > - **Negative-values-in-parens parser fix (v7.8.0)** — classes like `top-(-10)`, `mt-(-5)`, and `origin-(-10,-20)` no longer crash with `Cannot read properties of null (reading 'pop')`. The parser now extracts the `(...)` portion first, so a `-` inside the value does not break the split.
10
- > - **`brand:` config grouped (v7.7.0)** — the flat `brand:` block from v7.6.0 was reorganized into purpose-based sections: `brand.logos`, `brand.padding`, `brand.android`, `brand.ios`, and `brand.colors`. Old projects keep working — newly-generated configs use the grouped form.
11
- > - **Separate Android brand inputs (v7.7.0)** — `brand` can now use one logo for the general brand set, another for Android launcher icons (`logos.androidLauncher` / `--icon-logo`), and another for Android 12+ splash artwork (`logos.androidSplash` / `--splash-logo`). Drop `logo-icon.*` and `logo-splash.*` into `purgetss/brand/` or set the paths in `config.cjs`.
12
- > - **Legacy Android splash fallback (v7.7.0)** — `purgetss brand` now regenerates `app/assets/android/default.png` (Alloy) or `Resources/android/default.png` (Classic). `cleanup-legacy` no longer removes `default.png`.
13
- > - **`semantic` works in Classic projects (v7.6.2)** — writes to `Resources/semantic.colors.json` for Classic, keeps writing to `app/assets/semantic.colors.json` for Alloy.
14
- > - **Confirmation prompt for destructive writes (v7.6.1)** — `brand` and `images` ask `[y/N/a]` before overwriting (auto-skipped on non-TTY, with `-y`/`--yes`, or `PURGETSS_YES=1`).
15
- > - **New `brand` command (v7.6.0)** — generates the complete Titanium branding set (launcher icons, adaptive icons, iOS 18+ Dark/Tinted variants, marketplace artwork, optional notification/splash) from a single SVG or PNG logo. See [`brand` Command](#brand-command) and the deep-dive [app-branding.md](./app-branding.md).
16
- > - **New `images` command (v7.6.0)** — generates multi-density UI images (Android `res-*` densities + iPhone `@1x`/`@2x`/`@3x` scales) from sources in `./purgetss/images/`. See [`images` Command](#images-command) and the deep-dive [multi-density-images.md](./multi-density-images.md).
17
- > - **New `semantic` command (v7.6.0)** — generates Titanium semantic colors (Light/Dark) into `app/assets/semantic.colors.json` with two modes (tonal palette vs. single purpose-based color). See [`semantic` Command](#semantic-command) and the deep-dive [semantic-colors.md](./semantic-colors.md).
18
- > - **`brand:` and `images:` config sections** auto-injected into `purgetss/config.cjs` on first run. Percentages may be written as quoted strings like `'15%'` or as plain numbers.
19
- > - **Default font family classes (v7.5.3)** — `font-sans`, `font-serif`, and `font-mono` generated automatically with platform-appropriate values.
20
- > - **XML validation (v7.5.3)** — detects illegal `--` sequences inside XML comments during pre-validation.
21
-
22
- This page lists the commands available in PurgeTSS.
3
+ This page lists the commands available in PurgeTSS. For release-by-release feature additions and behavior changes, see [Version History](./version-history.md).
23
4
 
24
5
  ## Setup Commands
25
6
 
@@ -506,7 +487,7 @@ purgetss id
506
487
 
507
488
  ## `icon-library` Command
508
489
 
509
- The `icon-library` command copies the free font files for Font Awesome, Material Icons, Material Symbols, and/or Framework7 Icons into `./app/assets/fonts`.
490
+ Copies the bundled free font files (Font Awesome 7, Material Icons, Material Symbols, Framework7 Icons) into `./app/assets/fonts/`. Once the fonts are in place, every official icon class (`fa-home`, `ms-home`, `mi-home`, `f7-house`, etc.) works out of the box — PurgeTSS resolves them at compile time from its own bundled `dist/` files.
510
491
 
511
492
  ```bash
512
493
  purgetss icon-library [--vendor=fa,mi,ms,f7] [--module] [--styles]
@@ -515,412 +496,47 @@ purgetss icon-library [--vendor=fa,mi,ms,f7] [--module] [--styles]
515
496
  purgetss il [-v=fa,mi,ms,f7] [-m] [-s]
516
497
  ```
517
498
 
518
- ### Options and Flags
519
-
520
- - `-v, --vendor [fa,mi,ms,f7]` to copy specific font vendors.
521
- - `-m, --module` to copy the corresponding CommonJS module into the `./app/lib/` folder.
522
- - `-s, --styles` to copy the corresponding `.tss` files into the `./purgetss/styles/` folder for your review.
523
-
524
- `./app/assets/fonts/`
525
- ```bash
526
- FontAwesome7Brands-Regular.ttf
527
- FontAwesome7Free-Regular.ttf
528
- FontAwesome7Free-Solid.ttf
529
- Framework7-Icons.ttf
530
- MaterialIcons-Regular.ttf
531
- MaterialIconsOutlined-Regular.otf
532
- MaterialIconsRound-Regular.otf
533
- MaterialIconsSharp-Regular.otf
534
- MaterialIconsTwoTone-Regular.otf
535
- MaterialSymbolsOutlined-Regular.ttf
536
- MaterialSymbolsRounded-Regular.ttf
537
- MaterialSymbolsSharp-Regular.ttf
538
- ```
539
-
540
- After copying the fonts, you can use them in Buttons and Labels. For example, for Font Awesome, set the font family to `fa` (Solid icons) and use a class like `fa-home`.
541
-
542
- ### Available Font Classes
543
-
544
- - [fontawesome.tss](https://github.com/macCesar/purgeTSS/blob/main/dist/fontawesome.tss)
545
- - [materialicons.tss](https://github.com/macCesar/purgeTSS/blob/main/dist/materialicons.tss)
546
- - [materialsymbols.tss](https://github.com/macCesar/purgeTSS/blob/main/dist/materialsymbols.tss)
547
- - [framework7icons.tss](https://github.com/macCesar/purgeTSS/blob/main/dist/framework7icons.tss)
548
-
549
- ### Copying Specific Font Vendors
550
-
551
- ```bash
552
- purgetss icon-library --vendor="fontawesome, materialicons, materialsymbols, framework7"
553
-
554
- # alias:
555
- purgetss il -v=fa,mi,ms,f7
556
- ```
557
-
558
- Available names and aliases:
559
-
560
- - `fa`, `fontawesome` = Font Awesome Icons
561
- - `mi`, `materialicons` = Material Icons
562
- - `ms`, `materialsymbol` = Material Symbols
563
- - `f7`, `framework7` = Framework7 Icons
564
-
565
- ### CommonJS Module
566
-
567
- You can use the `--module` option to copy the corresponding CommonJS module into the `./app/lib/` folder.
568
-
569
- ```bash
570
- purgetss icon-library --module [--vendor="fontawesome, materialicons, materialsymbols, framework7"]
571
-
572
- # alias:
573
- purgetss il -m [-v=fa,mi,ms,f7]
574
- ```
575
-
576
- Each library includes a CommonJS module that exposes Unicode strings for the icon fonts.
577
-
578
- All prefixes are stripped from their class names and camel-cased. For example:
579
-
580
- - Font Awesome: `fa-flag` becomes `flag`.
581
- - Material Icons: `mi-flag` becomes `flag`.
582
- - Material Symbols: `ms-flag` becomes `flag`.
583
- - Framework7 Icons: `f7-alarm_fill` becomes `alarmFill` and `f7-clock_fill` becomes `clockFill`.
584
-
585
- ### Font Awesome Pro
586
-
587
- If you have a [Font Awesome Pro account](https://fontawesome.com/pro), you can generate a custom `./purgetss/styles/fontawesome.tss` file with the Pro-only classes (except duotone icons; see note below).
588
-
589
- 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 using `npm init` and `npm install --save-dev @fortawesome/fontawesome-pro` (current version 7.1.0).
590
-
591
- To generate a new `purgetss/styles/fontawesome.tss`, run `purgetss build`. It also copies the Pro font files into `./app/assets/fonts` if needed.
592
-
593
- > **Caution**
594
- > Titanium cannot use Font Awesome duotone icons because each icon uses two glyphs.
595
-
596
- ### Font Awesome 7 Beta
597
-
598
- To generate a custom `fontawesome.tss` file from [Font Awesome 7 Beta](https://fontawesome.com/download):
599
-
600
- Move the `css` and `webfonts` folders from `fontawesome-pro-7.0.0-beta3-web/`:
601
-
602
- ```bash
603
- fontawesome-pro-7.0.0-beta3-web/
604
- ├─ css/
605
- └─ webfonts/
606
- ```
607
-
608
- Into `./purgetss/fontawesome-beta/`:
499
+ ### Flags
609
500
 
610
- ```bash
611
- purgetss/
612
- └─ fontawesome-beta/
613
- ├─ css/
614
- └─ webfonts/
615
- ```
501
+ | Flag | Purpose |
502
+ | --- | --- |
503
+ | `-v, --vendor [fa,mi,ms,f7]` | Copy specific font vendors only (default copies all four). |
504
+ | `-m, --module` | Copy the matching CommonJS module into `./app/lib/` so you can reference icons by name from controllers (`icons.fa.home`). |
505
+ | `-s, --styles` | Copy the official `.tss` source files into `./purgetss/styles/` for reference only — not needed for the classes to work. |
616
506
 
617
- Then run `purgetss build` to generate your custom `fontawesome.tss` file and test the new icons.
618
-
619
- ### Font Example File
620
-
621
- To use this file:
622
-
623
- 1. Copy the content of `index.xml` into a new Alloy project.
624
- 2. Install the official icon font files using `purgetss icon-library`.
625
- - Without `--vendor`, PurgeTSS copies all official icon fonts.
626
- 3. Run `purgetss` once to generate the required files.
627
- 4. Compile your app as usual.
628
- 5. Use `liveview` for faster testing.
629
-
630
- ```xml
631
- <Alloy>
632
- <Window>
633
- <View class="grid">
634
- <View class="vertical mx-auto grid-cols-2 gap-y-2">
635
- <Label class="mt-2 text-gray-700" text="FontAwesome" />
636
- <Button class="fa fa-home my-1 h-10 w-10 text-xl text-blue-500" />
637
- <Button class="fa fa-home my-1 h-10 w-10 rounded bg-blue-500 text-xl text-white" />
638
- </View>
639
-
640
- <View class="vertical mx-auto grid-cols-2 gap-y-2">
641
- <Label class="mt-2 text-gray-700" text="Material Icons" />
642
- <Button class="mi mi-home my-1 h-10 w-10 text-xl text-blue-500" />
643
- <Button class="mi mi-home my-1 h-10 w-10 rounded bg-blue-500 text-xl text-white" />
644
- </View>
645
-
646
- <View class="vertical mx-auto grid-cols-2 gap-y-2">
647
- <Label class="mt-2 text-gray-700" text="Material Symbol" />
648
- <Button class="ms ms-home my-1 h-10 w-10 text-xl text-blue-500" />
649
- <Button class="ms ms-home my-1 h-10 w-10 rounded bg-blue-500 text-xl text-white" />
650
- </View>
651
-
652
- <View class="vertical mx-auto grid-cols-2 gap-y-2">
653
- <Label class="mt-2 text-gray-700" text="Framework7-Icons" />
654
- <Button class="f7 f7-house my-1 h-10 w-10 text-xl text-blue-500" />
655
- <Button class="f7 f7-house my-1 h-10 w-10 rounded bg-blue-500 text-xl text-white" />
656
- </View>
657
- </View>
658
- </Window>
659
- </Alloy>
660
- ```
507
+ Vendor aliases: `fa`/`fontawesome`, `mi`/`materialicons`, `ms`/`materialsymbol`, `f7`/`framework7`.
661
508
 
662
- ```tss
663
- /* PurgeTSS v7.2.7
664
- * Created by Cesar Estrada
665
- * https://github.com/macCesar/purgeTSS
666
- */
667
-
668
- /* Ti Elements */
669
- 'View': { width: Ti.UI.SIZE, height: Ti.UI.SIZE }
670
- 'Window': { backgroundColor: '#FFFFFF' }
671
-
672
- /* Main Styles */
673
- '.bg-blue-500': { backgroundColor: '#3b82f6' }
674
- '.gap-y-2': { top: 8, bottom: 8 }
675
- '.grid': { layout: 'horizontal', width: '100%' }
676
- '.grid-cols-2': { width: '50%' }
677
- '.h-10': { height: 40 }
678
- '.mt-2': { top: 8 }
679
- '.mx-auto': { right: null, left: null }
680
- '.my-1': { top: 4, bottom: 4 }
681
- '.rounded': { borderRadius: 4 }
682
- '.text-blue-500': { color: '#3b82f6', textColor: '#3b82f6' }
683
- '.text-gray-700': { color: '#374151', textColor: '#374151' }
684
- '.text-white': { color: '#ffffff', textColor: '#ffffff' }
685
- '.text-xl': { font: { fontSize: 20 } }
686
- '.vertical': { layout: 'vertical' }
687
- '.w-10': { width: 40 }
688
-
689
- /* Default Font Awesome */
690
- '.fa': { font: { fontFamily: 'FontAwesome7Free-Solid' } }
691
- '.fa-home': { text: '\uf015', title: '\uf015' }
692
-
693
- /* Material Icons */
694
- '.mi': { font: { fontFamily: 'MaterialIcons-Regular' } }
695
- '.mi-home': { text: '\ue88a', title: '\ue88a' }
696
-
697
- /* Material Symbols */
698
- '.ms': { font: { fontFamily: 'MaterialSymbolsOutlined-Regular' } }
699
- '.ms-home': { text: '\ue88a', title: '\ue88a' }
700
-
701
- /* Framework7 */
702
- '.f7': { font: { fontFamily: 'Framework7-Icons' } }
703
- '.f7-house': { text: 'house', title: 'house' }
704
- ```
509
+ > **Tip**
510
+ > This is a quick reference. See [Icon Fonts](./icon-fonts.md) for the complete guide — variant tables (`.ms`/`.mso`/`.msr`/`.mss`, `.fa`/`.fas`/`.far`/`.fab`), XML usage patterns, the side-by-side four-family example, Font Awesome Pro / Beta workflow, and instructions for recreating removed libraries.
705
511
 
706
512
  ## `build-fonts` Command
707
513
 
708
- The `build-fonts` command generates a `fonts.tss` file with class definitions and `fontFamily` selectors for serif, sans-serif, cursive, fantasy, or monospace fonts.
709
-
710
- Place all `.ttf` or `.otf` files in `./purgetss/fonts/`, then run the command. You can also use `--module` to generate a CommonJS module in `./app/lib/`.
514
+ Generates `./purgetss/styles/fonts.tss` with class definitions and `fontFamily` selectors for any user-defined fonts dropped into `./purgetss/fonts/` (Google Fonts, brand typefaces, community icon libraries with `.ttf` + `.css` pairs).
711
515
 
712
516
  ```bash
713
- purgetss build-fonts
517
+ purgetss build-fonts [-m] [-f]
714
518
 
715
519
  # alias:
716
- purgetss bf
717
- ```
718
-
719
- 1. Creates `./purgetss/styles/fonts.tss` with all class definitions and `fontFamily` selectors.
720
- 2. Copies the font files into `./app/assets/fonts`.
721
- 3. Renames the font files to match their PostScript names so they work on both iOS and Android.
722
-
723
- Example using Bevan and Dancing Script from Google Fonts.
724
-
725
- `./purgetss/fonts/`
726
- ```bash
727
- purgetss
728
- └─ fonts
729
- ├─ Bevan-Italic.ttf
730
- ├─ Bevan-Regular.ttf
731
- ├─ DancingScript-Bold.ttf
732
- ├─ DancingScript-Medium.ttf
733
- ├─ DancingScript-Regular.ttf
734
- └─ DancingScript-SemiBold.ttf
520
+ purgetss bf [-m] [-f]
735
521
  ```
736
522
 
737
- After running `purgetss build-fonts`:
738
-
739
- `./purgetss/styles/fonts.tss`
740
- ```tss
741
- /* Fonts TSS file generated with PurgeTSS
742
- * https://github.com/macCesar/purgeTSS
743
- */
744
-
745
- '.bevan-italic': { font: { fontFamily: 'Bevan-Italic' } }
746
- '.bevan-regular': { font: { fontFamily: 'Bevan-Regular' } }
747
-
748
- '.dancingscript-bold': { font: { fontFamily: 'DancingScript-Bold' } }
749
- '.dancingscript-medium': { font: { fontFamily: 'DancingScript-Medium' } }
750
- '.dancingscript-regular': { font: { fontFamily: 'DancingScript-Regular' } }
751
- '.dancingscript-semibold': { font: { fontFamily: 'DancingScript-SemiBold' } }
752
- ```
753
-
754
- ### Organizing the Fonts Folder
755
-
756
- For better organization, group each font family in subfolders:
757
-
758
- `./purgetss/fonts/`
759
- ```bash
760
- purgetss
761
- └─ fonts
762
- ├─ bevan
763
- │ ├─ Bevan-Italic.ttf
764
- │ └─ Bevan-Regular.ttf
765
- └─ dancing-script
766
- ├─ DancingScript-Bold.ttf
767
- ├─ DancingScript-Medium.ttf
768
- ├─ DancingScript-Regular.ttf
769
- └─ DancingScript-SemiBold.ttf
770
- ```
771
-
772
- Subfolders don't change the output -- you get the same `fonts.tss` as the flat layout above.
773
-
774
- ### Renaming `fontFamily` Classes
775
-
776
- To use a shorter or different class name, rename the font file.
777
-
778
- `./purgetss/fonts/`
779
- ```bash
780
- purgetss
781
- └─ fonts
782
- └─ dancing-script
783
- ├─ Script-Bold.ttf
784
- ├─ Script-Medium.ttf
785
- ├─ Script-Regular.ttf
786
- └─ Script-SemiBold.ttf
787
- ```
788
-
789
- Running `build-fonts` adjusts the class name accordingly:
790
-
791
- ```tss
792
- '.script-bold': { font: { fontFamily: 'DancingScript-Bold' } }
793
- '.script-medium': { font: { fontFamily: 'DancingScript-Medium' } }
794
- '.script-regular': { font: { fontFamily: 'DancingScript-Regular' } }
795
- '.script-semibold': { font: { fontFamily: 'DancingScript-SemiBold' } }
796
- ```
797
-
798
- ### Icon Font Libraries
799
-
800
- You can add any icon font library that includes a `.ttf` or `.otf` file and a `.css` file with Unicode characters.
801
-
802
- `./purgetss/fonts/`
803
- ```bash
804
- purgetss
805
- └─ fonts
806
- ├─ bevan
807
- ├─ dancing-script
808
- ├─ map-icons
809
- │ ├─ map-icons.css
810
- │ └─ map-icons.ttf
811
- └─ microns
812
- ├─ microns.css
813
- └─ microns.ttf
814
- ```
815
-
816
- After running `purgetss build-fonts`, `fonts.tss` will include the `fontFamily` class definitions and Unicode characters.
817
-
818
- `./purgetss/styles/fonts.tss`
819
- ```tss
820
- /* Fonts TSS file generated with PurgeTSS */
821
- /* https://github.com/macCesar/purgeTSS */
822
-
823
- '.map-icons': { font: { fontFamily: 'map-icons' } }
824
- '.microns': { font: { fontFamily: 'microns' } }
825
-
826
- /* Unicode Characters */
827
- /* To use your Icon Fonts in Buttons and Labels each class sets 'text' and 'title' properties */
828
-
829
- /* map-icons/map-icons.css */
830
- '.map-icon-abseiling': { text: '\ue800', title: '\ue800' }
831
- '.map-icon-accounting': { text: '\ue801', title: '\ue801' }
832
- '.map-icon-airport': { text: '\ue802', title: '\ue802' }
833
- '.map-icon-amusement-park': { text: '\ue803', title: '\ue803' }
834
- '.map-icon-aquarium': { text: '\ue804', title: '\ue804' }
835
-
836
- /* microns/microns.css */
837
- '.mu-arrow-left': { text: '\ue700', title: '\ue700' }
838
- '.mu-arrow-right': { text: '\ue701', title: '\ue701' }
839
- '.mu-arrow-up': { text: '\ue702', title: '\ue702' }
840
- '.mu-arrow-down': { text: '\ue703', title: '\ue703' }
841
- '.mu-left': { text: '\ue704', title: '\ue704' }
842
- ```
843
-
844
- ### Options
845
-
846
- - `-m, --module`: Generate a CommonJS module in `./app/lib/`.
847
- - `-f, --filename`: Use filenames as both font class names and icon prefixes (replaces the old `-p` flag).
848
-
849
- ### CommonJS Module
850
-
851
- Use the `--module` option to generate a CommonJS module called `purgetss.fonts.js` in `./app/lib/`.
852
-
853
- To avoid conflicts with other icon libraries, PurgeTSS keeps each icon's prefix.
854
-
855
- ```bash
856
- purgetss build-fonts --module
857
-
858
- # alias:
859
- purgetss bf -m
860
- ```
861
-
862
- `./app/lib/purgetss.fonts.js`
863
- ```javascript
864
- const icons = {
865
- // map-icons/map-icons.css
866
- mapIcon: {
867
- abseiling: '\ue800',
868
- accounting: '\ue801',
869
- airport: '\ue802',
870
- amusementPark: '\ue803'
871
- },
872
- // microns/microns.css
873
- mu: {
874
- arrowLeft: '\ue700',
875
- arrowRight: '\ue701',
876
- arrowUp: '\ue702',
877
- arrowDown: '\ue703'
878
- }
879
- };
880
- exports.icons = icons;
881
-
882
- const families = {
883
- // map-icons/map-icons.css
884
- mapIcon: 'map-icons',
885
- // microns/microns.css
886
- mu: 'microns'
887
- };
888
- exports.families = families;
889
- ```
890
-
891
- ### Using Filenames for Class Names and Icon Prefixes
892
-
893
- The `--filename` option uses the style's filename as both the font class name and the icon prefix in `fonts.tss` and `purgetss.fonts.js`.
894
-
895
- `./purgetss/fonts/`
896
- ```bash
897
- purgetss
898
- └─ fonts
899
- ├─ map-icons
900
- │ ├─ map.ttf
901
- │ └─ mp.css
902
- └─ microns
903
- ├─ mic.ttf
904
- └─ mc.css
905
- ```
523
+ ### Flags
906
524
 
907
- This generates:
525
+ | Flag | Purpose |
526
+ | --- | --- |
527
+ | `-m, --module` | Also generates a CommonJS module in `./app/lib/purgetss.fonts.js` exposing `exports.icons` and `exports.families` for use from controllers. |
528
+ | `-f, --font-class-from-filename` | Uses the font filename as the class name and icon prefix instead of the font family. Replaces the old `-p` flag. |
908
529
 
909
- ```tss
910
- /* fontFamily classes use the font's filename */
911
- '.map': { font: { fontFamily: 'map-icons' } }
912
- '.mic': { font: { fontFamily: 'microns' } }
530
+ ### What it does
913
531
 
914
- /* map-icons/mp.css */
915
- '.mp-abseiling': { text: '\ue800', title: '\ue800' }
916
- '.mp-accounting': { text: '\ue801', title: '\ue801' }
532
+ 1. Creates `./purgetss/styles/fonts.tss` with one `fontFamily` class per file.
533
+ 2. Copies the font files into `./app/assets/fonts/`, renamed to their PostScript names so they work on both iOS and Android.
917
534
 
918
- /* microns/mc.css */
919
- '.mc-arrow-left': { text: '\ue700', title: '\ue700' }
920
- '.mc-arrow-right': { text: '\ue701', title: '\ue701' }
921
- ```
535
+ > **Tip**
536
+ > This is a quick reference. See [Custom Fonts](./custom-fonts.md) for the complete guide — folder organization, class renaming, adding icon libraries, the `--module` output structure, and `--font-class-from-filename` workflow.
922
537
 
923
- Make sure the new prefix is unique and does not conflict with other class prefixes.
538
+ > **Note**
539
+ > `build-fonts` is for **user-defined fonts only**. The 4 official icon families (Font Awesome 7, Material Icons, Material Symbols, Framework7) are bundled with PurgeTSS and installed via [`icon-library`](#icon-library-command), not `build-fonts`. See [Icon Fonts](./icon-fonts.md).
924
540
 
925
541
  ## `shades` Command
926
542