Skip to content

Commit 1d08655

Browse files
junaid7haquejunaid7haque
authored
Merge pull request #11 from reactome/updated-read-me
Updated read me
2 parents f348d25 + 23298dc commit 1d08655

File tree

1 file changed

+94
-10
lines changed

1 file changed

+94
-10
lines changed

‎README.md‎

Lines changed: 94 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,102 @@
11
# Reactome Illustrations
2-
32
SVG icons and EHLD diagrams for [Reactome](https://reactome.org/) pathway diagrams, sourced from Figma.
43

54
## Contents
6-
75
- `icons/` - SVG icons and XML metadata files (R-ICO-XXXXXX.svg and .xml)
86
- `ehld/` - EHLD diagram SVGs (R-HSA-XXXXXX.svg)
7+
- `statics/` - SVG static diagrams (R-HSA-XXXXXX.svg)
98
- `download_illustrations.py` - Script to download icons and EHLDs from Figma and validate them
109
- `VERSION` - Current release version number
1110

1211
## Prerequisites
13-
1412
- Python 3 with `requests` (`pip install requests`)
1513
- Docker (for the [illustration-validator](https://github.com/reactome/illustration-validator))
16-
- A Figma personal access token
14+
- A Figma personal access token — stored as a GitHub Actions secret (`FIGMA_TOKEN`) for the GitHub Actions workflow, or set as an environment variable for local use
15+
16+
---
1717

1818
## Usage
1919

20+
There are two ways to download and validate illustrations: via **GitHub Actions** (recommended) or **locally** via the command line.
21+
22+
---
23+
24+
### Option 1: GitHub Actions (Recommended)
25+
26+
This is the preferred method. Everything runs on GitHub's servers — no local setup required beyond having write access to the repo.
27+
28+
#### How to trigger a download
29+
30+
1. Go to the **Actions** tab in the repository
31+
2. Select **"Download illustrations from Figma"** from the left sidebar (it may be pinned at the top)
32+
3. Click **"Run workflow"**
33+
4. Fill in the options (see below) and click the green **"Run workflow"** button
34+
35+
#### Workflow options
36+
37+
- **What to download** — choose one of:
38+
- `everything` — downloads all EHLDs and all icons
39+
- `ehlds-only` — downloads EHLD diagrams only
40+
- `icons-only` — downloads icons only
41+
42+
- **Specific EHLDs to download** — optional. If you selected `ehlds-only` and only want to update certain diagrams, enter their IDs here space-separated (e.g. `R-HSA-1234567 R-HSA-9876543`). Leave blank to download all EHLDs.
43+
44+
- **Specific icons to download** — optional. If you selected `icons-only` and only want to update certain icons, enter their IDs here space-separated (e.g. `R-ICO-012345 R-ICO-012346`). Leave blank to download all icons.
45+
46+
> **Note:** The specific ID fields are always visible but only take effect when `ehlds-only` or `icons-only` is selected.
47+
48+
#### Use case 1: Full fresh download (new release)
49+
50+
Use this when preparing a new release and you want to pull everything fresh from Figma.
51+
52+
1. Make sure you are running the workflow from **main** (default)
53+
2. Select `everything`
54+
3. Leave both specific ID fields blank
55+
4. Click **Run workflow**
56+
57+
A new branch called `figma-download-YYYY-MM-DD-HHMM` will be created automatically with all the downloaded files. Validation runs automatically after the download. Once you're happy, open a pull request from that branch to main.
58+
59+
#### Use case 2: Updating specific files (e.g. fixing a single EHLD or icon)
60+
61+
Use this when an illustrator has updated a specific file in Figma and you just want to pull that one change without re-downloading everything.
62+
63+
1. If a download branch already exists (e.g. `figma-download-2026-03-13-1603`), select it from the **"Use workflow from"** dropdown — this will update files directly on that branch instead of creating a new one
64+
2. If starting fresh, leave it on **main** and a new branch will be created
65+
3. Select `ehlds-only` or `icons-only`
66+
4. Enter the specific ID(s) in the relevant field
67+
5. Click **Run workflow**
68+
69+
Only the specified files will be updated — everything else on the branch stays untouched.
70+
71+
#### After the workflow runs
72+
73+
- If **validation passed** → open a pull request from the download branch to main. The validator will run again automatically on the PR as a final check before merging.
74+
- If **validation failed** → the branch still exists. Fix the issue (e.g. drag a missing XML file into the `icons/` folder on GitHub), then manually re-run the **"Validate illustrations"** workflow on that branch from the Actions tab.
75+
76+
Once the PR is merged into main, files are automatically uploaded to S3.
77+
78+
---
79+
80+
### Option 2: Running locally
81+
82+
Use this if you prefer to run the download script directly on your machine.
83+
84+
#### Setup
85+
2086
```bash
87+
pip install requests
2188
export FIGMA_TOKEN="your_figma_token"
89+
```
90+
91+
On Windows (PowerShell):
92+
```powershell
93+
pip install requests
94+
$env:FIGMA_TOKEN = "your_figma_token"
95+
```
96+
97+
#### Commands
2298

99+
```bash
23100
# Download everything (icons + EHLDs) and validate
24101
python3 download_illustrations.py
25102

@@ -31,29 +108,37 @@ python3 download_illustrations.py --ehlds
31108

32109
# Download without validating
33110
python3 download_illustrations.py --skip-validation
111+
112+
# Download specific EHLDs only
113+
python3 download_illustrations.py --ehlds --only R-HSA-1234567 R-HSA-9876543
114+
115+
# Download specific icons only
116+
python3 download_illustrations.py --icons --only-icons R-ICO-012345 R-ICO-012346
34117
```
35118

36-
## What the script does
119+
After running, create a new branch, commit the changes, push, and open a pull request to main.
120+
121+
---
37122

123+
## What the script does
38124
1. Connects to the Figma API and finds all components/frames on the "Export" page
39125
2. Exports icons (`R-ICO-*`) and EHLD diagrams (`R-HSA-*`) as SVGs
40126
3. Clears existing SVGs and saves the new ones (icon XML metadata files are preserved)
41127
4. Runs the illustration-validator Docker container to validate:
42128
- **Icons**: XML metadata (categories, references, curator info)
43129
- **EHLDs**: SVG structure (BG, LOGO, REGION/OVERLAY groups)
44130

45-
## Icon XML Metadata
131+
---
46132

133+
## Icon XML Metadata
47134
Each icon has a corresponding XML metadata file (`R-ICO-XXXXXX.xml`) containing categories, curator/designer info, descriptions, and database references. These are stored alongside the SVGs in the `icons/` directory.
48135

49136
To create new XML metadata files, use the **Icon XML Metadata Generator** (see below).
50137

51138
## Icon XML Metadata Generator
52-
53139
`icon-xml-generator.html` is a self-contained HTML tool for generating icon XML metadata files. Open it in a browser — no build tools or dependencies required.
54140

55141
### Features
56-
57142
- **Category selection** — loaded from the [illustration-validator](https://github.com/reactome/illustration-validator) `categories.txt`
58143
- **Curator search** — searches the Reactome Content Service for people by name, auto-fills ORCID
59144
- **Designer info** — pre-filled with defaults (Cristoffer Sevilla)
@@ -63,10 +148,9 @@ To create new XML metadata files, use the **Icon XML Metadata Generator** (see b
63148
- **Download** — saves the XML file with the correct filename
64149

65150
### How to use
66-
67151
1. Open `icon-xml-generator.html` in a browser
68152
2. Enter the icon identifier (e.g. `R-ICO-012345`)
69153
3. Select a category, search for a curator, and fill in the remaining fields
70154
4. Add references and synonyms as needed
71155
5. Click **Download XML** to save the file
72-
6. Move the downloaded `.xml` file into the `icons/` directory
156+
6. Move the downloaded `.xml` file into the `icons/` directory

0 commit comments

Comments
 (0)