Skip to content

Commit d5ab970

Browse files
MoOxMoOx
committed
Initial release
0 parents  commit d5ab970

File tree

14 files changed

+9474
-0
lines changed

14 files changed

+9474
-0
lines changed

‎.github/workflows/build.yml

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
name: Build
2+
3+
on:
4+
pull_request:
5+
branches: [main]
6+
push:
7+
branches: [main]
8+
9+
jobs:
10+
test:
11+
runs-on: macos-latest
12+
13+
steps:
14+
- uses: actions/checkout@v4
15+
16+
- name: Use Node.js
17+
uses: actions/setup-node@v4
18+
with:
19+
node-version-file: "package.json"
20+
cache: "npm"
21+
22+
- name: Handle Next.js Cache
23+
uses: actions/cache@v4
24+
with:
25+
path: .next/cache
26+
key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-${{ hashFiles('**/*.js', '**/*.jsx', '**/*.ts', '**/*.tsx') }}
27+
restore-keys: |
28+
${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-
29+
30+
- name: Download and install SF Pro fonts
31+
run: |
32+
echo "Downloading SF Pro fonts..."
33+
curl -L https://devimages-cdn.apple.com/design/resources/download/SF-Pro.dmg -o SF-Pro.dmg
34+
35+
echo "Mounting DMG file..."
36+
hdiutil attach SF-Pro.dmg -nobrowse
37+
38+
echo "Installing SF Pro fonts package..."
39+
sudo installer -pkg "/Volumes/SFProFonts/SF Pro Fonts.pkg" -target /
40+
41+
echo "Unmounting DMG..."
42+
hdiutil detach "/Volumes/SFProFonts" -force
43+
44+
echo "Listing installed fonts..."
45+
ls -la /Library/Fonts/SF-Pro*
46+
47+
- name: Install dependencies
48+
run: npm ci
49+
50+
- name: Test
51+
run: npm run test

‎.gitignore

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
2+
/node_modules
3+
.DS_Store
4+
dist
5+
test-output
6+
sf-symbols-svgs
7+

‎.husky/pre-push

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
npm test

‎CHANGELOG.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Changelog of `sf-symbols-svg`
2+
3+
## 6.0.0 - 2025-05-15
4+
5+
Initial release

‎LICENSE

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
The MIT License (MIT)
2+
3+
Copyright (c) 2025 Maxime Thirouin
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
# SF Symbols to SVG
2+
3+
<a href="https://github.com/MoOx/sf-symbols-svg?sponsor=1">
4+
<img width="140" align="right" alt="Sponsoring button" src="https://github.com/moox/.github/raw/main/FUNDING.svg">
5+
</a>
6+
7+
[![GitHub package.json version](https://img.shields.io/github/package-json/v/MoOx/sf-symbols-svg) ![npm downloads](https://img.shields.io/npm/dm/sf-symbols-svg)](https://www.npmjs.com/package/sf-symbols-svg)
8+
[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/MoOx/sf-symbols-svg/build.yml?branch=main)](https://github.com/MoOx/sf-symbols-svg/actions)
9+
[![License](https://img.shields.io/github/license/MoOx/sf-symbols-svg)](https://github.com/MoOx/sf-symbols-svg)
10+
![My website moox.io](https://img.shields.io/badge/%F0%9F%8C%8D%20-https%3A%2F%2Fmoox.io-gray?style=social)
11+
[![GitHub followers](https://img.shields.io/github/followers/MoOx?style=social&label=GitHub)](https://github.com/MoOx)
12+
[![LinkedIn Follow](https://img.shields.io/badge/LinkedIn-%20?style=social&logo=invision&logoColor=%230077B5)](https://www.linkedin.com/in/maxthirouin/)
13+
[![BlueSky Follow](https://img.shields.io/badge/BlueSky-%20?style=social&logo=bluesky)](https://bsky.app/profile/moox.io)
14+
[![X Follow](https://img.shields.io/twitter/follow/MoOx?style=social&label=)](https://x.com/MoOx)
15+
16+
> SF Symbols to SVGs. Period.
17+
18+
[Apple SF Symbols](https://developer.apple.com/sf-symbols/) is an icon set with more thant 6,000 symbols.
19+
Unfortunately, this are not available on the web.
20+
This tool solve this.
21+
22+
> [!WARNING]
23+
> This tool requires you to have the [_SF Pro Text_ font](https://developer.apple.com/fonts/) installed on your system or in a custom directory.
24+
25+
> [!TIP]
26+
> SF Symbols to SVG can be coupled with [React from SVG](https://github.com/MoOx/react-from-svg) to generate React components from SVGs.
27+
28+
## Usage
29+
30+
SF Symbols to SVG is available as a CLI tool:
31+
32+
```console
33+
npx sf-symbols-svg --help
34+
```
35+
36+
#### Available Options
37+
38+
```console
39+
--size, -s Font size for symbols (default: 24)
40+
--padding, -p Padding in pixels (default: 2)
41+
--weight, -w Font weights to include (default: regular)
42+
Can specify multiple: -w regular -w bold
43+
--output, -o Output directory (default: ./sf-symbols-svgs)
44+
--fonts-dir, -f Directory containing SF Pro Text fonts (default: /Library/Fonts)
45+
--sf-version SF Symbols version to use (default: latest)
46+
--sources-dir Directory containing SF Symbols data files (default: ./sources)
47+
--icons-list Path to a file containing a list of icons to process, one name per line (optional)
48+
--help, -h Show this help message
49+
--version Show version of SF Symbols supported by this tool.
50+
```
51+
52+
> [!NOTE]
53+
> SF Symbols to SVG will always try to use the latest version of SF Symbols supported by this tool.
54+
> You can check in the `sources/` directory to see which versions are supported.
55+
56+
#### Examples
57+
58+
```console
59+
# Generate SVGs for the latest version of SF Symbols, in 24x24 SVGs with 2px padding, in ./svg-symbols-svgs folder
60+
npx sf-symbols-svg --weight all
61+
62+
# Generate SVGs with larger size and padding
63+
sf-symbols-svg --size 32 --padding 4
64+
65+
# Generate SVGs for multiple weights
66+
sf-symbols-svg --weight bold --weight black
67+
68+
# Specify custom output directory
69+
sf-symbols-svg --output ./my-icons
70+
71+
# Specify a different SF Symbols version (if available)
72+
sf-symbols-svg --sf-version 6.0
73+
74+
# Combine options
75+
sf-symbols-svg --size 48 --padding 8 --weight light --weight regular --weight bold --output ./custom-icons --fonts-dir /Users/moox/Library/Fonts
76+
77+
# Process only specific icons
78+
sf-symbols-svg --icons-list /path/to/your/icons-list.txt
79+
```
80+
81+
## Creating a new version
82+
83+
## About SF Symbols Versions and Font Compatibility
84+
85+
### SF Symbols Versions
86+
87+
This tool automatically detects supported SF Symbols versions by scanning the `sources/` directory. Each version requires its own data files (`symbols.txt` and `names.txt`) which are already included in the repository for some versions.
88+
89+
The tool will automatically use the most recent version as the default, but you can specify a different version using the `--sf-version` option. If no matching versions are detected in the `sources/` directory, the tool will display an error message.
90+
91+
If you want to use a different version (when new SF Symbols versions are released):
92+
93+
1. Create a new directory in `sources/{version}/` (example: `sources/7.0/`)
94+
2. Extract the character mappings:
95+
- Get the [SF Symbols app](https://developer.apple.com/sf-symbols/) and open the app
96+
- Select all symbols (`cmd + A` or `Edit` > `Select All`)
97+
- Right click on the selection, and press `Copy all {x} symbols`
98+
- Paste the symbols into a file at `sources/{version}/symbols.txt`
99+
- Right click again on the selection, and press `Copy all {x} names`
100+
- Paste the names into a file at `sources/{version}/names.txt`
101+
102+
That's it! The tool will automatically detect the new version and use it as the default (since it's the most recent).
103+
104+
### Using a Custom Sources Directory
105+
106+
If you want to use a different directory for your SF Symbols data files, you can specify it with the `--sources-dir` option:
107+
108+
```sh
109+
sf-symbols-svg --sources-dir /path/to/your/sources
110+
```
111+
112+
The custom sources directory must follow the same structure as the default one:
113+
114+
```
115+
sources/
116+
├── 6.0/
117+
│ ├── symbols.txt
118+
│ └── names.txt
119+
├── 6.1/
120+
│ ├── symbols.txt
121+
│ └── names.txt
122+
└── ...
123+
```
124+
125+
The tool will automatically detect available versions from the provided directory and use the most recent one as the default.
126+
127+
## Processing Only Specific Icons
128+
129+
If you want to process only a limited subset of icons, you can create a text file with one icon name per line and use the `--icons-list` option:
130+
131+
```sh
132+
sf-symbols-svg --icons-list /path/to/your/icons-list.txt
133+
```
134+
135+
Example of an icons list file:
136+
137+
```
138+
moon.stars.fill
139+
puzzlepiece
140+
amplifier
141+
figure.hiking
142+
```
143+
144+
This is particularly useful for:
145+
146+
- Testing the tool with a smaller set of icons
147+
- Generating only the specific icons you need for your project
148+
- Reducing processing time when you only need a few symbols
149+
150+
### Font Compatibility
151+
152+
> [!WARNING] SF Symbols requires specific _SF Pro Text_ font versions that match the SF Symbols version you're using. If the font versions don't match, the symbols may not render correctly.
153+
154+
> [!CAUTION]
155+
> The Apple SF Symbols app will display a warning at the top of the application if your installed fonts don't match the expected version. Make sure to check this warning and install the appropriate font version from [Apple's website](https://developer.apple.com/fonts/).
156+
157+
### About Font Files
158+
159+
To use this script, you need to have the SF Pro Text fonts installed on your system or in a custom directory.
160+
161+
#### Using system-installed fonts (recommended)
162+
163+
If you have SF Pro Text fonts installed on your system (typically in `/Library/Fonts`), the script will automatically find and use them. This is the default behavior.
164+
165+
````console
166+
# Use fonts from the default location (/Library/Fonts)
167+
sf-symbols-svg`
168+
169+
#### Using fonts from a custom directory
170+
171+
If your fonts are installed in a different location, you can specify it with the `--fonts-dir` option:
172+
173+
```console
174+
# Use fonts from a custom location
175+
sf-symbols-svg --fonts-dir ~/Library/Fonts
176+
````
177+
178+
#### Installing SF Pro Text fonts
179+
180+
If you don't have the fonts installed:
181+
182+
1. Download SF Pro font from [Apple's website](https://developer.apple.com/fonts/).
183+
2. Install the font using the provided installer.
184+
3. The fonts will be installed in `/Library/Fonts` by default.
185+
186+
---
187+
188+
> [!NOTE]
189+
> For legal reasons, this repository does not include the SF Pro Text font files. You must download and install them from Apple's website. Make sure to use font versions that are compatible with the SF Symbols version you are using (check for warnings in the SF Symbols app).

0 commit comments

Comments
 (0)