User manual
SOP Studio.
User manual for SOP Studio v0.15 — the authoring tool for multilingual factory work instructions accessed by QR code.
This manual is for the people who build the work instructions. Production supervisors, line leaders, engineers, anyone on your factory floor who needs to turn a piece of equipment into something a worker can use safely after a thirty-second scan.
You do not need to know how to code. You do not need to install anything. SOP Studio is a single HTML file. You open it in Chrome or Edge, you point it at a folder on your computer, and you start writing. Photos, drawings, multilingual text, animations on top of the photos to point at the right button — all of it ends up in one self-contained file you can stick on a domain and a QR code on the machine.
Read the Quick start if you want to be authoring in five minutes. Read the rest of the manual when something does not behave the way you expect, or when you want to know what is happening under the surface.
A note on languages
SOP Studio ships with four languages baked in: English, Polish, Romanian, Russian. The manual itself stays in English for now — translations follow once the editor is settled. If a worker scans the QR code on their phone, the viewer auto-detects their phone's language and shows the instruction in that language. You write each instruction once, in as many of the four as you have time for.
## 01 —Quick start
There are three ways to use SOP Studio. Most users will pick Folder mode on day one and never look back. The other two exist for cases where Folder mode is not available or not wanted.
Recommended
Folder mode
Connect a project folder on your computer. Saves, exports, templates, images — everything lives in the folder, on your machine. Files survive between sessions. The editor remembers the folder and reopens it next time.
- One-click save
- Templates auto-loaded
- Image library on disk
- Automatic backups in 99_Backups/
Quick test
Local mode
Skip the folder. Work in memory. Saves trigger browser downloads. Good for a quick experiment, a demo to a colleague, or when you want to try the tool before committing.
- No setup
- Works in Firefox & Safari
- Templates start empty
- Each save = a download
First time
Starter pack
Click Download starter pack. You get a zip with a pre-stocked SOP_Studio/ folder: example templates, a sample instruction, this manual. Unzip, open SOP_Studio.html inside, hit Connect, point at the same folder.
- Everything pre-wired
- Example templates pre-filled
- Generic Acme demo SOP included
1.1The five-minute path
If you have ten minutes spare and the starter pack downloaded, this is the shortest route to a working QR code on a real machine:
- Unzip the starter pack somewhere you can find it. The desktop is fine. A shared network drive is better if more than one person will author.
- Open SOP_Studio.html in Chrome or Edge. Double-click works.
- Click Connect folder. Pick the SOP_Studio/ folder you just unzipped. Click Allow on every visit when Chrome asks.
- Click New instruction. Fill in the title in English. Pick equipment from the dropdown — or type a new one.
- Add one action. Add one step. Pick a photo from 03_Images/. Draw a rectangle on the photo to point at the relevant button.
- Click Save & export. Set the deploy URL. Generate the QR code. Download the PNG.
- Upload the exported HTML to your domain. Print the QR. Stick it on the machine.
That is the whole tool. Everything after this section is depth on each part.
If Connect folder does nothing
You are probably opening the file from an unusual location (a network share, a deeply nested SharePoint path, or via file:// in a Chrome build that locks the File System Access API down). Move the folder to C:\Users\you\Documents\, or run it through a local web server, or fall back to Local mode. The editor will switch automatically and tell you it did.
## 02 —The folder structure
When you connect a folder, SOP Studio expects to see a specific layout inside it. If any subfolders are missing, the editor creates them silently the first time you save. You never have to make folders by hand.
2.1What lives in each subfolder
- 01_Data/ The source of truth for every instruction. Each instruction is one .json file containing the SOP number, title, metadata, signatures, action list, step list with multilingual fields, highlights, points, and references to images. You can open these in Notepad if you ever need to. The editor reads them on Connect and rewrites them on Save. Filenames are derived from the SOP number (sop-north-prod-001.json, sop-north-assy-014.json), so two SOPs with the same title but different SOP numbers always live in different files.
- 02_Templates/ Five CSV files that feed the dropdown menus in the wizard: sites.csv, areas.csv, equipment.csv, people.csv, companies.csv. Edit them in Excel or Notepad. See section 04.
- 03_Images/ Every photo you want to use in a step. Drop files in here with sensible names — camera-power-switch.jpg not IMG_20250413_0832.jpg. Accepts JPG, PNG, WebP. The editor compresses large images on import so the exported HTML stays small.
- 04_Logos/ Company logos, site logos, anything brand-related. Used on the export cover sheet and optionally in the viewer footer. PNG with transparent background works best.
- 05_Exports/ The finished, self-contained HTML files. One per instruction. These are the files you upload to your web host. The QR codes point at URLs that serve these files.
- 06_Translations/ Optional. If you want to override viewer UI strings (button labels, status messages) for a specific language, drop a .json file here. The starter pack ships with sensible defaults baked in; you only touch this folder when a default reads wrong in your language.
- 99_Backups/ Automatic snapshots. Every time the editor overwrites an instruction JSON, the previous version is copied here first with a timestamp suffix. You will rarely look in this folder, but it is there for the day someone deletes a step they later wanted back.
Naming the folder
The folder can be called anything you like. SOP_Studio/ is a sensible default. On a shared drive you might call it SOPs/ or Work_Instructions/. The editor does not care about the outer name — it only looks at the subfolders inside.
2.2Putting the folder on a shared drive
If two or more people will author instructions, put the folder on a shared drive both can reach. OneDrive, SharePoint, a mapped network drive — they all work, as long as Chrome can read and write to the path.
A few things to know if you go this route:
- One editor at a time per instruction. If you and a colleague both have the same instruction open and both save, the last save wins. The editor does not currently lock files. Co-ordinate with each other.
- OneDrive sync is fine. The editor writes JSON files; OneDrive syncs them like any other file. There may be a brief lag before your colleague sees your save.
- SharePoint can be slow. Cold-loading a folder with hundreds of images can take ten or twenty seconds the first time. Once cached, it is instant.
## 03 —The wizard, step by step
Every instruction is built inside a four-step wizard. You move forward when each step is complete; you can jump back to any earlier step at any time. Progress is saved continuously to memory; you hit Save (or CtrlS) to write it to the JSON file on disk.
The wizard always shows the four steps in the left rail. The current step is highlighted in the muted teal accent. Completed steps show a green check on the number badge. You can click any badge to jump to that step.
Step 1Metadata
The bones of the instruction. SOP number, title, equipment, area, site, who made it, who authorised it. None of this changes after step 1 unless you come back and edit it.
SOP Number is the first field, required, globally unique. Format suggestion: SOP-<SITE>-<AREA>-<NNN> — for example SOP-NORTH-PROD-001. As soon as you pick a site and an area, the editor offers a click-to-copy suggestion below the field. If you type a number that's already used by another instruction, you get an inline red banner naming the colliding SOP — the wizard blocks you from moving on (and from saving) until the number is unique. The SOP number is what drives the exported filename, the legal footer on every viewer screen, and the per-page footer on every A3 print.
The title is multilingual — type it in English, switch the global language picker to Polish, type it in Polish, and so on. Every multilingual field below uses the same language picker, so you fill everything in EN first, then everything in PL, rather than jumping back and forth.
Equipment, Area, Site, Company are comboboxes. That means you can either pick a value from the dropdown (the suggestions come from the CSVs in 02_Templates/) or type a new value the user wants to use. If you type something new, the editor accepts it and silently adds the new value back to the relevant CSV on next save.
Made by / Authorised by at the SOP level default to the signed-in user and a blank authoriser. Each individual action on step 2 carries its own Made-by / Authorised-by inputs that override these SOP-level defaults — useful when different actions in the same instruction were authored or signed off by different people. The values on each action surface on that action's printed A3 page footer; the SOP-level defaults are the fallback when an action has no signatures of its own.
Revision is a short optional code (default A) that appears alongside the SOP number in the legal footer. Bump it when you reissue the instruction.
Step 2Actions
An action is one thing a worker might want to do with the equipment. Switch it on. Switch it off. Empty the conveyor. Clean the camera lens. Change the cutting blade. Each action is a separate sequence of steps.
Why this matters: when a worker scans the QR code on the machine, the first thing they see is the list of actions. They tap the one they need to do. They do not have to scroll through one giant instruction looking for the right part.
On this screen you add actions, reorder them with the up/down icons, delete the ones you do not need, and rename them. Each action has a multilingual title. The order matters — the most common task should be at the top.
Each action carries its own Made-by and Authorised-by signatures. The card for every action has four inline inputs: Made-by name, Made-by date, Authorised-by name, Authorised-by date. These override the SOP-level defaults set on step 1, and they're what gets printed in the footer of that action's A3 page. Leave them blank to fall back to the SOP-level signatures. Use them when one instruction legitimately has more than one authoriser — for example, an engineering authority on the startup action and a hygiene authority on the cleaning action.
You typically have between three and seven actions per piece of equipment. If you find yourself adding twenty, you probably want to split the equipment into two separate instructions.
Step 3Steps & highlights
This is where you do the real work. Pick one action from step 2, and build the sequence of steps a worker follows to perform it.
Each step has five pieces:
- A multilingual title — three to seven words. "Open the inspection panel". Not a sentence.
- A multilingual instruction — one or two short sentences. Active voice. "Press the green button. Wait for the red light to turn green." This is a first-class field on the step, not part of a text-box. It sits next to the title in the editor and prints above the image in the viewer.
- An image — a photo from 03_Images/ (or any subfolder inside it — see section 4.5). One photo per step. Use a real photo of the actual machine, not a stock image. Workers trust their eyes more than they trust your prose. From v0.15 the editor opens a crop modal the moment you pick an image. The crop is locked to 4:3 landscape and is mandatory — drag the rectangle to frame the part of the photo you want the worker to see, then click Crop to 4:3. Cancel aborts the pick (the step stays without an image). Every render surface in the tool is locked to 4:3, so the cropped photo lines up pixel-for-pixel between the editor canvas, the worker viewer, the all-steps grid, and the A3 PNG cell.
- Highlights — zero or more shapes drawn directly on the image to point at shapes on the image. The green button. The red light. The cable. Rectangle, ellipse, arrow, or brush stroke.
- Points — zero or more numbered teardrop pins dropped directly on the image to mark specific spots that need their own description. Each point gets a numbered legend underneath the photo with a multilingual sentence explaining what's at that pin. Best when a single step needs to call out three or four discrete features on the same photo without drawing four overlapping rectangles.
Reading order in the viewer is title → instruction → image (with highlights and pins) → numbered point legend → navigation. The instruction sits above the photo so the worker reads what they need to do before their eye lands on the image. (Earlier builds had image first, then description; that was swapped in v0.6 after worker testing showed they were conflating step description with point captions.)
The canvas at the top of the step has six drawing tools — Select V, Rectangle M, Ellipse E, Line/arrow L, Brush B, Point P. For the four shape tools, pick the tool then drag on the image — the new highlight appears with default colour and animation. For Point, pick the tool then click once on the image — a numbered teardrop drops at the click. With Select active, click any existing highlight or pin to see move/resize handles; drag the handles (or drag a pin) to reposition. Press Del to remove the selected item. CtrlZ undoes the last canvas action; CtrlY redoes.
Each highlight has an animation. The default is pulse — a gentle scale-in-scale-out that catches the eye without screaming. Seven animations are available; see section 5. Each point has its own simpler three-way animation control: none, pulse, ring-pulse (the radar-ping expanding ring under the pin).
The right-hand properties panel changes shape depending on what's selected. For a highlight it shows the animation picker and a delete button. For a point it shows the per-language Label (the short text inside the teardrop — usually auto-numbered 1.1, 1.2, but editable per language), a per-language Description textarea (what shows up in the numbered legend), the animation picker, and a delete button.
Brush strokes are a special case — once drawn, they can't be edited. To change the shape of a brush stroke, delete it and redraw.
Step 4Export
You are done authoring. Now you produce the artefacts a worker will actually scan, print, or read on screen.
Save & export writes two files:
- The source JSON in 01_Data/ — so you can re-edit later.
- The single-file HTML in 05_Exports/ — this is what gets uploaded to your domain. It contains everything: the viewer code, the instruction data, all images embedded as base64, the design tokens, and the typography (Inter Tight, Geist Mono, IBM Plex Sans, IBM Plex Mono are bundled as base64-embedded woff2 inside the file). No external CDN, no Google Fonts request, no network call needed to render — the export works fully offline from the moment it's first opened.
The exported filename is derived from the SOP number (slug-cased), so two SOPs with the same title but different SOP numbers always export to different files. If you re-save an existing SOP its filename is preserved.
Set the deploy URL — the URL where the HTML will live on your web host. Typical pattern: https://sops.example.com/cb01-startup or whatever fits your domain setup. The URL is baked into the QR code, so set it before generating the QR.
Generate QR code renders a 1024×1024 PNG. Download it. Print it. Stick it on the equipment near the relevant panel. Done.
A3 instruction sheet (PNG)
Step 4 also has an A3 instruction sheet card. Pick an output language (EN / PL / RO / RU) and click Export A3 PNG. The editor lays out every action's steps on portrait A3 pages. The grid is locked at 3 columns of 4:3 landscape cells — up to nine cells per page (3×3) — with the title, SOP number, action name, step images with highlights and numbered pins, per-step instruction, the numbered point legend, and a legal footer on every page (SOP number, made-by, authorised-by, revision, page X of Y). Pages fill top-to-bottom; if an action has fewer than nine steps, the remaining cells stay blank. If the SOP fits on one page you get one PNG; otherwise the editor builds a STORED-method ZIP containing one PNG per page, named <sopnumber>_A3_<lang>.zip. Per-action signatures (set on step 2) override the SOP-level signatures on a per-page basis.
You can come back to this screen any time by reopening the instruction from the Library. The QR PNG and the A3 PNG can be regenerated independently, so reprinting after a content edit re-bakes the new content into the artefacts but the QR URL never changes — the same printed sticker keeps working.
## 04 —Templates: the CSV dropdown lists
The dropdowns in the wizard — Equipment, Area, Site, Made-by, Authorised-by, Company — are fed from five CSV files in 02_Templates/. These are plain text. You can open them in Excel, Notepad, VS Code, or any text editor.
Adding a row in equipment.csv adds that equipment to the dropdown the next time you click Refresh in the topbar (or press R). You do not need to restart the editor.
4.1The five files
- sites.csvProduction sites — e.g. North Plant, Central Plant, South Plant.
- areas.csvAreas within a site — Production, Assembly, Packing, Quality Assurance, Warehouse, Maintenance.
- equipment.csvIndividual machines, sensors, cameras, conveyors. The longest of the five files, typically.
- people.csvStaff who might appear as Author or Authoriser on an instruction. Name plus role.
- companies.csvThe company name on the cover sheet. Most users only need one row here.
4.2Example: equipment.csv
The first row is the header — leave it as-is. Each subsequent row is one piece of equipment. Columns are id, name, area, site, notes. Only name is required; the rest help with sorting and filtering.
| id | name | area | site | notes |
|---|---|---|---|---|
| eq-001 | Conveyor CB-01 | Production | North Plant | Belt conveyor, 10m |
| eq-002 | Press P-01 | Assembly | North Plant | Hydraulic press, 50T |
| eq-003 | Heat Sealer HS-01 | Assembly | North Plant | Continuous band sealer |
If you edit this file in Excel and save back as CSV, watch out for two things: Excel often saves as "CSV UTF-8" with a byte-order mark — that is fine, the editor handles it. Excel also sometimes converts numeric-looking IDs (001) into actual numbers (1) and drops the leading zeros. Format the column as text before saving, or just use IDs that are obviously strings (eq-001).
Templates are suggestions, not enforcement
Any combobox field in the wizard accepts free-form input. If you start typing a new equipment name that does not exist in equipment.csv, the dropdown still lets you save it. You will see a small hint underneath: New — will be added to suggestions on next save. The editor writes the new value back to equipment.csv so it appears in the dropdown next time. This makes the templates self-growing: you start with nothing, you add equipment as you go, by the end of a year the file is the de-facto equipment registry for the site.
4.3Editing in Excel — the safe path
- Do close the file in Excel before clicking Refresh in the editor. Excel locks the file while it is open and the editor cannot write back to it.
- Do save as CSV UTF-8 (Comma delimited). Not CSV (Macintosh) or CSV (MS-DOS).
- Do not add columns the editor did not put there. Extra columns are ignored on read and lost on write.
- Do not rename columns. The editor matches by column name. Rename name to Equipment Name and the column disappears from the editor's view.
- Do use Notepad if you only have one or two rows to add. It is faster and avoids Excel quirks.
4.4What if the templates folder is empty?
The first time you connect a fresh folder, 02_Templates/ contains the five CSVs with only the header row — no data. The dropdowns will be empty but still accept free-form input. As you author instructions, every new equipment name, site name, or area name you type is silently added to the relevant CSV. After a few instructions, the dropdowns fill themselves up.
The starter pack ships with example rows pre-filled so you can see what good data looks like. If you want a clean start, delete the example rows but keep the header.
4.5Photos: subfolders are encouraged
The image picker on step 3 walks 03_Images/ recursively. You can — and should — organise your photos in subfolders. The editor will find them.
A practical layout for a busy site:
03_Images/
Production/
Conveyor_CB01/
panel-open.jpg
e-stop.jpg
Press_P01/
hydraulic-lockout.jpg
Assembly/
Heat_Sealer_HS01/
belt-clean.jpg
Maintenance/
quarterly-inspection.jpgWhen you open the image picker, it groups the results by parent folder — root-level images appear in a "Top level" group, each subfolder gets its own labelled section. The image reference stored on the step (step.image.ref) is the relative path under 03_Images/ — e.g. Production/Conveyor_CB01/panel-open.jpg. Move a photo to a different subfolder and existing instructions break; rename a folder and existing instructions break. Pick a layout, stick with it.
Hidden folders (anything starting with .) and Mac's __MACOSX noise folders are skipped automatically. Supported formats: .jpg, .jpeg, .png, .webp.
## 05 —Highlights and animations
A highlight is a shape drawn on a step image to point at something the worker needs to find. Highlights are the difference between "press the button" and "press this button". They are the single most useful feature in SOP Studio because they translate a 1000-word paragraph into a glance.
SOP Studio gives you four shape tools, one freehand brush, one numbered-pin tool, and seven animations to apply to any of the shapes.
5.1The six drawing tools
The default. Click a highlight to select it; drag its handles to move or resize it. Esc or click empty space to deselect. With nothing selected, Del does nothing — safe.
Draw a rectangle. Best for buttons, panels, screens, anything with straight edges. The most-used tool by a wide margin.
Draw an ellipse or circle. Best for round things — dials, knobs, indicator lights, emergency-stop buttons.
Draw a line with an arrowhead. Best for pointing at something from a distance, or showing direction of motion. Toggle arrowhead on/off in the properties panel.
Free-hand drawing. Use sparingly. Best for circling irregularly-shaped things, or scribbling out a sensitive serial number for a screenshot. Brush strokes can't be edited once drawn — delete and redraw to change shape.
Drop a numbered teardrop pin on a specific spot. Auto-numbered stepNum.pointNum (1.1, 1.2, 2.1, 2.2…). Each pin can carry a per-language label inside the teardrop and a per-language description that appears in the numbered legend under the photo. Best when one image needs three or four discrete callouts without four overlapping rectangles.
Pick the simplest tool that works
If a rectangle fits, use a rectangle. Workers parse shape, position, and colour faster than they parse art. The freehand brush exists because sometimes you need it, but most steps look better with two or three clean rectangles than with one elaborate scribble.
5.2The seven animations
Every highlight has an animation that plays in the viewer. The animation is what catches a worker's eye when the step first loads. Match the animation to the urgency of the thing being pointed at.
Static outline. Use when the highlight is a frame around an area of context (e.g. "this whole panel is the control panel") rather than an action point.
On and off, once every 1.2 seconds. General attention. Use as a fallback when none of the other modes feels right.
Urgent, dangerous. Reserve for lockout/tagout points, emergency-stop buttons, danger zones. Do not overuse — if everything blinks fast, nothing does.
Gentle scale-in-scale-out. The default. Catches the eye without screaming. 90% of highlights should be pulse.
Soft halo that brightens and dims. Premium feel. Best for indicator lights and screens — things that themselves glow in real life.
Dashed outline that scrolls along the edge. Direction of motion. Use on arrows showing the flow of product, or on rectangles around a moving belt.
Expanding ring like a radar ping. Use on a precise spot — the exact pixel a worker should press. Pairs well with a static label next to it.
5.3Colour and line width
Every highlight uses the locked brand-terracotta accent at 2.5px stroke, tuned for visibility against the widest range of real factory photos. Per-highlight colour and line-width overrides aren't exposed in the current build — they're on the future-release list. Until then, the single locked palette is the design floor: consistent across every SOP, every site, every print artefact, every viewer screen. If a particular photo fights the colour (extremely red backgrounds, fully terracotta machinery), redraw the highlight against a different framing of the same equipment.
5.4How many highlights per step?
Zero is fine. One is best. Two is acceptable. Three is the upper limit. Beyond that, split the step into two steps.
A step is a single small action: "press the green button". If you have three separate things to point at, you have three separate steps.
## 06 —Multilingual content
SOP Studio supports four languages out of the box: English, Polish, Romanian, Russian. These reflect the languages most commonly spoken on factory floors across the UK and Northern Europe. Adding a fifth is a future-release feature.
6.1The global language picker
At the top of every wizard screen there is a global language picker — four small mono-font tabs showing EN, PL, RO, RU. Click one and every multilingual field below switches to that language at once. You do not switch language field by field.
The recommended workflow:
- Pick EN. Fill in the title, all action names, all step titles and instructions in English. Get the structure right.
- Switch to PL. Translate everything. Or hand the editor to a Polish-speaking colleague and let them do this pass.
- Switch to RO. Same. Then RU.
You can ship an instruction with only one or two languages filled in. The viewer falls back: if the worker's phone is Romanian but you only filled in English and Polish, the worker sees English (the universal fallback).
6.2Fill-state dots
Each language tab has a small dot inside it. Solid dot = that language has content. Hollow dot = empty. This is your at-a-glance audit: open an instruction, look at the tabs, see which languages still need work.
The dots are per-instruction-wide, not per-field. If you have filled the title in Polish but not the step instructions, the PL dot stays solid — open the instruction and you will see which fields are still empty (they show placeholder text in muted grey).
6.3How workers see the language
When a worker scans the QR code, the viewer reads the language preference of their phone's operating system. If the phone is in Polish, they see the Polish version. If the phone is in English, they see English.
The viewer also shows four small language chips in the top-right corner. A worker can tap a chip to switch — useful when a phone is shared, or when the OS language is set wrong.
An example of the same step in all four languages:
EN: Press the green button. Wait for the light to turn green.
PL: Naciśnij zielony przycisk. Poczekaj, aż lampka zaświeci na zielono.
RO: Apăsați butonul verde. Așteptați ca lumina să devină verde.
RU: Нажмите зелёную кнопку. Дождитесь, пока индикатор станет зелёным.6.4Tips for good translations
- Write English first, simple. Short sentences. Active voice. The simpler the English, the simpler the other three become.
- Get a native speaker on each pass. Machine translation is a starting point, not a finish line. Polish, Romanian and Russian all have gender, case and aspect features that machine translators get wrong in ways that matter on a factory floor.
- Read the translation back out loud with the speaker. If they pause or wince, the sentence needs another pass.
- Use the same word for the same thing. If "the green button" is zielony przycisk in step 2, do not let it become zielony guzik in step 5. Workers learn the word in the first step and look for it later.
Do not skip Polish
On many UK factory floors, Polish is the most-spoken non-English language. An instruction without a Polish translation is an instruction that excludes a third of its potential users. Make Polish the second language you fill in, every time.
## 07 —Export and round-trip
The export is the most important file SOP Studio produces. Everything else exists to make this file good.
7.1What is in the exported HTML
The exported file is a single self-contained HTML document. Everything a phone needs to display the instruction is embedded inside it:
- The instruction JSON — title, SOP number, revision, signatures, action list, steps with their per-step instruction text, highlight coordinates, point pins with multilingual labels and descriptions, and all animation settings. Roughly 5-30 KB.
- The step images — base64-encoded inside the HTML. Each image is cropped to 4:3 landscape in the editor (mandatory crop on pick) before embedding; expect ~80-200 KB per photo for a typical 1920×1080 source cropped to roughly 1920×1440 or smaller. Every render surface — editor canvas, worker viewer, all-steps grid, A3 PNG cell — locks its image container to 4:3, so pin coordinates land on the exact pixel the author chose.
- The viewer code — the JavaScript that renders the steps, switches language, draws highlights and pins, plays animations, and powers the cover screen's all-steps grid view. About 80 KB unminified.
- The design tokens, viewer CSS, and fonts — the four typefaces (Inter Tight, Geist Mono, IBM Plex Sans, IBM Plex Mono) are base64-embedded woff2 inside the file. About 150 KB combined. No CDN request needed to render — the export works fully offline from the first open.
A typical exported file with eight steps and one photo per step lands between 500 KB and 1.1 MB. Big enough that you would not email it casually, small enough that a phone on a slow connection still loads it in well under a second.
7.2Offline behaviour
The viewer is fully self-contained — once the HTML file has loaded once, every subsequent page interaction (language switch, action navigation, step navigation, all-steps view, print, A3 PNG export) runs purely against in-memory data. No network request is made after the initial load. A worker who scanned the QR earlier in the day can open the instruction again with no network — useful in a warehouse with poor reception or a cold store with metal walls. Phones cache the HTML through their own browser cache the same way they cache any static page.
Re-exporting the same instruction (same URL, same SOP number) is the update path: the next time the worker's browser fetches the URL, it picks up the new version. There's no service-worker layer in the current build — every load comes straight from the browser cache or the network.
7.2aWhat workers can do from the cover screen
The viewer's cover screen (the first thing a worker sees after scanning the QR) has three action buttons above the legal footer, alongside the list of actions:
- View all steps — switches to an A3-grid view of every action's steps on a single scrollable page. Each step shows its image with highlights and pins, the step instruction, and the numbered point legend. Useful for a worker who wants to scan ahead before starting, or for a supervisor reviewing the full procedure at a glance.
- Print all steps — opens the all-steps view and triggers the browser's print dialog. A @media print stylesheet forces a light palette, A3 portrait orientation, full page width, and one page per action block. Workers can print the whole SOP, or use the dialog's "Save as PDF" option for a digital copy.
- Export PNG — lazy-fetches a small image-rendering library that sits next to the deployed HTML, then captures the all-steps view as one PNG per page. Single page → direct PNG download; multiple pages → a ZIP bundle. Filename follows <sopnumber>_A3_<lang>.png or .zip. If the export is opened as a standalone file with no sibling library present, the Print button still works — the PNG button toasts a graceful fallback message.
All three buttons honour the worker's currently-selected language. Print all and Export PNG render in whichever language the viewer is currently displaying.
7.3Round-trip — re-editing an exported file
The exported HTML can be re-imported into the editor. This matters for two cases:
- You lost the source JSON. The folder got deleted, the laptop died, the colleague who built it has left. As long as you have the exported HTML, you can recover the instruction.
- Someone else built the instruction and only sent you the HTML. A contractor, another site, a vendor. Drag their HTML onto your editor and you can read, edit, re-export.
To round-trip: open the editor, go to Library, drag the exported HTML file onto the dropzone. The editor extracts the embedded JSON, embedded images, and opens the wizard with the instruction loaded as if you had just authored it. Save and it lands back in 01_Data/ as a fresh JSON source.
Round-trip is lossless
Nothing is lost in the round-trip. The exported HTML contains the complete source data, not just a rendered view. Re-export after editing and the file is bit-for-bit equivalent (modulo a new timestamp and a new export hash).
7.4What the export does not contain
- The CSV templates. The exported viewer does not need dropdown suggestions — it just displays the instruction. Templates stay in 02_Templates/.
- The backups. 99_Backups/ never goes near the export.
- Other instructions. Each instruction exports as its own file. There is no "publish everything" button. This is deliberate — one URL per instruction means one QR per instruction.
7.5Deploying the exported file
Drop the exported HTML on any web host. The viewer is fully static — no server-side anything required. Common hosting options:
- Netlify — drag-and-drop the entire 05_Exports/ folder onto Netlify's drop zone. Within ten seconds you have a public URL for each file. Free tier is more than enough.
- A company-owned subdomain. If you have sops.yourcompany.com set up, each export file goes there and the URL is just sops.yourcompany.com/cb01-startup.html.
- SharePoint. Works but the URLs are ugly and the QR code becomes large and hard to scan. Avoid if you can.
## 08 —QR codes
A QR code is a printed square that, when scanned by a phone camera, opens a URL. SOP Studio generates a QR for every exported instruction. The QR points at the URL where the exported HTML lives.
The shop-floor experience looks like this:
8.1How the QR is generated
In step 4 of the wizard, you enter a deploy URL — the URL where the exported HTML will live. When you click Generate QR, the editor produces a 1024×1024 PNG that encodes that URL.
The QR uses error-correction level Q — it stays scannable even if a quarter of the image is damaged, scratched, or partly covered by tape. This matters in a factory environment where stickers get sprayed, wiped, and scuffed.
8.2Printing the QR
Print at 5×5 cm or larger. Smaller works for a phone held close, but workers often scan from arm's length with one hand, while the other hand holds something. Bigger is more forgiving.
Print on adhesive paper. A common choice is 80×80mm white vinyl labels printed on a label-printer like the Brother QL-820NWB — survives weekly washdown and the QR stays scannable. Other options:
- Laminated paper — cheap, fine for non-wash areas (offices, engineering workshop).
- Engraved metal plate — overkill for most cases, but the right choice for wet areas where adhesives fail. Engineering can quote one for ~£12 each.
- Polypropylene tag, cable-tied — for moving equipment, or equipment with no flat surface to stick to.
8.3Where to stick the QR
The QR goes near the action point — the panel, the button, the place where the worker will need the instruction. Not on the side of the machine where the QR is hidden behind packaging. Not on the back where you would have to crawl to reach it.
If the same equipment has multiple QR codes (one per action), put them in a row, each labelled with the action they cover. Workers learn to scan the right one quickly.
8.4What happens after the scan
A worker points their phone camera at the QR. iOS and Android both recognise QR codes natively — there is no special app needed. The phone shows a notification: "Open in browser". The worker taps it.
The page loads in 600-900 ms on 4G, faster on Wi-Fi. The progress bar at the top is truthful — it reflects actual download progress, not a fake animation. As soon as the instruction is ready, the action list appears.
The worker taps the action they want. The first step appears with its image, its highlight animating gently, and the instruction text in their phone's language. They do the step, swipe left, see the next step. At the end of the action, a green tick and the option to start another action.
Test the QR before printing 50 of them
Always scan the QR with a real phone before bulk-printing stickers. The most common failure mode is the URL not being deployed yet — the QR scans fine, the phone opens a browser, the browser shows 404. Better to find that in your office than on the shop floor.
## 09 —Local-only mode
Local-only mode is what SOP Studio does when there is no connected folder. It is a real, supported way to use the tool — not a fallback to feel guilty about. Use it when:
- You are demonstrating SOP Studio to someone and do not want to commit to a folder.
- You are on a machine where the File System Access API does not work (Firefox, Safari, mobile).
- You are building a one-off instruction that does not need to live alongside the other instructions.
- You want to round-trip an exported HTML someone sent you, edit it, and send it back, without leaving traces on disk.
9.1What is different in Local-only mode
| Feature | Folder mode | Local-only mode |
|---|---|---|
| Connect a folder | Required | Not needed |
| Templates (dropdowns) | Loaded from 02_Templates/ | Empty — free-form input only |
| Image source | Pick from 03_Images/ | Choose image file from disk |
| Save | Writes to 01_Data/ | Triggers browser download |
| Export | Writes to 05_Exports/ | Triggers browser download |
| Library | Lists files in 01_Data/ | Lists in-memory drafts only |
| Round-trip import | Yes | Yes |
| Auto-backup | Yes (99_Backups/) | No |
9.2The workflow
Open SOP Studio. Instead of clicking Connect folder on the gate screen, click Skip — work locally (the smaller button beneath). You go straight into the editor.
Click New instruction. Fill in the wizard exactly as in Folder mode. Comboboxes have no dropdown suggestions (templates are empty) but they accept any text you type.
For step images, instead of Pick from 03_Images/, you get Choose image file. Pick a file from anywhere on your computer. The image is read into memory and embedded in the draft.
When you save, the browser downloads a JSON file. Keep it somewhere. When you export, the browser downloads the HTML. That is your QR target.
9.3The trade-off
Local-only mode is fast and dependency-free, but it has no persistence. If you close the tab without exporting, your work is gone. The editor warns you before tab close, but the warning is easy to dismiss accidentally.
For anything beyond a quick test, switch to Folder mode. It takes one extra click and you get auto-save, templates, image library, backups, and a permanent home for the work.
## 10 —Keyboard shortcuts
SOP Studio is designed to be drivable from the keyboard. The most-used commands all have shortcuts. The full list is also available in-app — press ? at any time to bring up the overlay.
The shortcuts follow conventions from professional design tools: g followed by a letter for navigation (g-l for Library, g-n for New), single-letter shortcuts for canvas tools (V, M, E, L, B), and Ctrl-combinations for global commands (Ctrl+S to save, Ctrl+E to export).
| Action | Shortcut |
|---|---|
| Navigation | |
| Go to Library | GL |
| New instruction | GN |
| Go to Templates | GT |
| Go to Images | GI |
| Go to Settings | GS |
| Refresh folder | R |
| Wizard | |
| Next step | Alt→ |
| Previous step | Alt← |
| Jump to step 1 / 2 / 3 / 4 | Alt1 … Alt4 |
| Add action / step | Ctrl↵ |
| Switch language | Ctrl1 EN, 2 PL, 3 RO, 4 RU |
| Canvas (step 3) | |
| Select tool | V |
| Rectangle | M |
| Ellipse | E |
| Line / arrow | L |
| Brush | B |
| Delete selected highlight | Del or ⌫ |
| Undo | CtrlZ |
| Redo | CtrlY or Ctrl⇧Z |
| Duplicate highlight | CtrlD |
| Deselect | Esc |
| Global | |
| Save current | CtrlS |
| Save & export | CtrlE |
| Show shortcuts overlay | ? |
| Dismiss overlay / modal | Esc |
| Toggle theme (dark / light / auto) | Ctrl⇧L |
| Switch user | Ctrl⇧S |
| Focus search (Library) | / |
Mac users
Wherever the table shows Ctrl, use ⌘ instead. Wherever it shows Alt, use ⌥. The shortcuts are the same otherwise. SOP Studio detects your OS at load and shows the right key labels in the in-app shortcut overlay.
## 11 —Troubleshooting
The honest list of things that go wrong, and what to do when they do. If your problem is not here, the version field at the bottom of every editor screen has the build hash — paste it in a message to the SOP Studio maintainer along with what you were trying to do.
Connect folder does nothing
You are probably opening the editor from file:// in a Chrome build that has locked down the File System Access API. The clearest fix: serve the editor from a real URL — Netlify, an internal web host, or run a local web server (npx http-server in the folder containing SOP_Studio.html). If that is not possible, fall back to Local-only mode — click Skip — work locally on the gate screen.
Permission denied when picking a folder
Chrome asks for permission when you connect a folder. If you clicked Block, or closed the prompt, the editor never gets access. Click Connect folder again and this time pick Allow on every visit. If you cannot find the prompt, look at the address bar — there is usually a small icon you can click to revisit folder permissions.
QR scan goes to a 404 page
The exported HTML has not been uploaded to the URL yet, or it has been uploaded to the wrong URL. Open the URL from the QR in a normal browser to check. If you see 404 there too, upload the file in 05_Exports/ to the deploy URL you entered in step 4 of the wizard. If you see a different page, the URL you entered does not match where the file actually lives — re-enter the URL in step 4, re-generate the QR.
An imported instruction shows weird characters (Ł becomes ?, ć becomes Ä)
The JSON file has been edited outside the editor with a non-UTF-8 encoding — Notepad on older Windows builds is the usual culprit. Open the file in a UTF-8-capable editor (VS Code, Notepad++, modern Notepad with the Save As → UTF-8 option), re-save, and re-import. If the original is unrecoverable, re-export from the editor to regenerate a clean file.
Image does not appear in the exported HTML
The image file referenced by the step has been deleted from 03_Images/ after the wizard linked it. Open the step in the wizard — it will show a broken-image placeholder. Either put the original file back in 03_Images/, or click Replace image and pick a different one. Save and re-export.
Editor says "folder out of sync" on Refresh
Files in 01_Data/ have been edited or deleted by someone else (or by you in a different tab) while the editor was open. Click Reload on the warning to pick up the disk state, or Keep mine to overwrite the disk on next save. There is no automatic merge.
Highlights are not animating in the exported viewer
The worker's phone has Reduce motion enabled in its accessibility settings. This is intentional — the viewer respects prefers-reduced-motion and switches animated highlights to static outlines. The highlight is still visible; it just does not move. If you want to verify, turn off Reduce motion in your phone's settings and re-scan.
Export file is unexpectedly large (more than 2 MB)
You have very high-resolution source images. The editor compresses on import but cannot shrink a 24 MP photo down to phone-screen size without quality loss. Either accept the size (most networks handle 2-3 MB fine), or re-export the same photos at 1920×1080 before importing. The viewer never needs more than 1920 pixels wide.
Save fails with "quota exceeded"
Local-only mode keeps drafts in browser storage, which is limited to about 5 MB per origin in some browsers. Export what you have, close the tab, and start fresh. Or switch to Folder mode where this limit does not apply.
Theme keeps switching back to dark
Auto mode follows your operating system's appearance preference. If Windows is set to Dark, the editor goes dark every time Auto resolves. Click the theme button until it shows the sun icon — that pins it to Light regardless of OS. The choice is stored in sop_manual_theme in localStorage.
Dropdown is empty for Equipment / Site / Area
In Folder mode: 02_Templates/equipment.csv has only the header row, no data. Open it, add rows, save, press R in the editor to refresh. In Local-only mode: dropdowns are always empty by design — type the value directly into the field.
## 12 —Browser compatibility
SOP Studio comes in two halves: the editor (what you author with) and the viewer (what workers scan). They have different compatibility needs because they do different things.
12.1The editor
The editor needs the File System Access API to read and write the project folder. That API is currently in Chromium-family browsers only.
Version 86+. Folder mode, Local-only mode, everything works. Tested through Chrome 132.
Version 86+. Identical to Chrome — same engine. A safe default on Windows-managed sites where Edge is the corporate browser.
Built on Chromium. Folder mode works. Fonts are self-hosted inside the editor, so Brave's Shields do not interfere with typography.
No File System Access API. The editor detects this and switches to Local-only mode automatically. Authoring still works; just no folder persistence.
No File System Access API. Same Local-only fallback as Firefox. Drag-and-drop import works.
Phone keyboards make wizard-style authoring painful. Use a desktop for the editor. The viewer is built for phones.
12.2The viewer (what workers see)
The exported viewer HTML is plain modern web — HTML, CSS, JavaScript, no fancy APIs. It works on every browser that has been updated in the last five years.
iOS 14+. Service worker caches the viewer for offline use.
Chrome 90+. Service worker, offline, language auto-detect — all work.
When workers scan a QR via certain apps (WhatsApp, Telegram) the viewer opens in WebView — that is fine.
Most ruggedised tablets ship with Android Chrome or Edge. The viewer works fine on cracked-screen Zebra TC22 units and similar factory-grade handhelds.
Why Chromium for the editor?
The File System Access API lets the editor read and write a folder you choose, without uploading anything to a server. Firefox and Safari do not implement it yet — they prefer a different model where every save is a download. Local-only mode in SOP Studio uses that download model and is the right fallback. We will move to the WICG-standard File System Handle API across all browsers when it ships, but that is not 2026 yet.
## 13 —Privacy and data
SOP Studio is built to keep your data on your machine. The default mode is local-first by design.
13.1Where the data lives
- In Folder mode: every instruction, image, template, and export lives in the folder you connected. The editor reads and writes files on disk through your browser's permission. Nothing is uploaded anywhere.
- In Local-only mode: drafts live in your browser's memory and IndexedDB. Saves are downloaded as files to your Downloads folder. Nothing leaves the browser.
- Author identity: the sign-in modal stores your chosen name in browser localStorage (key sop_studio_user). It is used to stamp the "Made by" field on instructions. Nothing more.
13.2What goes out to the network
Nothing. The editor and the exported viewer ship every typeface they use as base64-embedded woff2 inside the file — Inter Tight, Geist Mono, IBM Plex Sans, IBM Plex Mono. Zero font CDN calls. No fonts.googleapis.com, no fonts.gstatic.com, no jsDelivr, no unpkg. The only sibling files an export needs to render are itself; the only sibling files a deployed export will ever fetch are the optional html2canvas.min.js for the worker-side PNG export (lazy-loaded only when the Export PNG button is clicked, and self-hosted next to the HTML if you deploy the editor's output/ folder wholesale).
That is the entire network footprint. No analytics. No telemetry. No crash reporting. No "anonymous usage data". No cloud sync. No phone-home for license checks. The editor and viewer are static files that do not talk to any SOP-Studio-owned servers because there are no SOP-Studio-owned servers.
Air-gapped install
The current build is already air-gappable. Copy the editor HTML and (optionally) html2canvas.min.js to a USB stick, plug into an isolated PC, open in Chrome or Edge, work. Exports are equally self-contained — drop one on a private intranet and workers' phones render it without ever leaving the LAN.
13.3What the exported viewer contains
An exported HTML file contains, in plain (decompiled-readable) form:
- The instruction title, in every language you filled in.
- The action and step titles and texts, multilingual.
- Author name, authoriser name, equipment ID, area, site, company name.
- All step images, base64-encoded.
- The viewer code (open-source-style, readable).
Treat the exported HTML the way you would treat the paper SOP it replaces. If the paper SOP would not be posted publicly, neither should the HTML. The author and authoriser names are personal data under UK GDPR; if you deploy the HTML on a publicly-reachable URL, the QR scanner gets to see those names. That is usually fine inside a company intranet, but consider whether you want every contractor with a phone to see "Authorised by J. Lee, 2026-04-13" if the QR ends up on equipment a contractor scans.
13.4Version history — every save is a numbered version
From v0.15, every SOP carries a monotonic version number in meta.version. A brand-new instruction starts at v1. Every save bumps the number by one — the second save produces v2, the third v3, and so on. The Library row shows the current version next to the equipment/area/site metadata, like "Conveyor CB-01 · Production · North Plant · v3".
Before each overwrite, the editor reads the existing file's version and writes the old bytes to 99_Backups/<slug>__v<N>.bak.json (and the same for the HTML export, ending .bak.html). After v3 is overwritten by v4, you get conveyor-cb01-startup__v3.bak.json in 99_Backups/. After v4 → v5, you get __v4.bak.json alongside the v3. Nothing is destroyed.
The Library row has a History button that opens a modal listing every version of the SOP — v1, v2, v3, ..., latest. Each row shows the version number, when it was saved, who saved it, and how many actions/steps it had. Click Load on any earlier row to load that version into the wizard. A banner appears on the saved-pill telling you which version you are editing and what version the next save will create. Loading v1 then clicking Save does not overwrite v1 — it creates v(latest+1), so the timeline only ever grows. You can pull yesterday's version back out, tweak one number, and save the patched version as v(latest+1).
The round-trip is preserved: an exported HTML's embedded JSON includes its meta.version, so re-importing an exported file picks up where the source left off.
The editor never prunes 99_Backups/ — over a year you might accumulate dozens of files per SOP. The folder is plain JSON and HTML; deleting old backups manually is safe. A reasonable rule: keep the last ten versions per SOP, clear older ones during a quarterly housekeeping pass.
13.5Compliance with corporate IT policy
SOP Studio runs entirely client-side. No data leaves your machine without your action (the only action being "upload the exported HTML to a web host you control"). The editor does not write to the Windows registry, does not call out to system APIs, and does not install anything. It is one HTML file.
If IT requires an air-gapped review, give them the editor's source and let them grep for fetch(, XMLHttpRequest, WebSocket, and navigator.sendBeacon. The only matches sit inside the viewer's optional Export-PNG path, which calls fetch('./html2canvas.min.js') against the same directory as the deployed HTML — same-origin, no cross-domain traffic, and never invoked unless a user clicks Export PNG.
## 14 —Glossary
The words SOP Studio uses, and what they mean inside this tool. If a word here means something different elsewhere in your organisation (or in your previous job), the definition below is the one that applies inside the editor.