connors/photon: an Electron UI toolkit built from HTML and CSS

What connors/photon is for

Photon is a UI toolkit for building desktop apps with Electron. The README states that purpose in one line, and the repository backs it up with a stylesheet, an icon font and a runnable example. The intended user is someone who wants a desktop application to look like a macOS window: title bars, toolbars, sidebars, buttons and form controls drawn in CSS rather than assembled from a native widget set. The selling point in the project description is speed of construction, and the mechanism is that you write ordinary HTML and link one stylesheet. There is no JavaScript component runtime, no virtual DOM and no build step required to consume the output. If your application is already an Electron shell rendering an HTML document, Photon is a drop-in visual layer. If you are writing a native macOS app in Swift or a web app that never leaves the browser, the toolkit has nothing to offer you.

How the toolkit is put together

The repository separates source from output. The sass/ directory holds the source styles, Gruntfile.js drives the build, and dist/ holds what consumers actually load. The package.json points at both ends: the "style" key names dist/css/photon.css and the "sass" key names sass/photon.scss. The README lists what a download contains: a css/ directory with photon.css, a fonts/ directory with four Entypo files (eot, svg, ttf, woff), and a template-app/ directory holding js/menu.js, app.js, index.html and package.json. The template app is a working Electron application, not a snippet collection, so the fastest way to see the toolkit in motion is to run that directory rather than to assemble a page yourself. The icon font is a separate asset from the stylesheet, which means copying photon.css alone gives you the layout but not the glyphs. The README notes that master is the active, unstable development branch and directs anyone wanting a stable copy to the tagged downloads, which is a meaningful distinction: the repository layout you clone today is not necessarily the 0.1.2 build.

Installing Photon and running the template app

There is no package published for consumption; the README's getting-started path is to clone the repository. Once cloned, the development section gives two commands. The first installs the Node dependencies, which include Grunt, the Sass compiler task and electron-prebuilt. The second launches the example app from dist/template-app.

git clone https://github.com/connors/photon.git
cd photon
npm install
npm start

After npm start, an Electron window should open showing the template application. That window is your reference for what the components look like. If you change anything under sass/, the README says to open a second terminal tab and run the Grunt build, which recompiles photon.css. Without that step your edits to the Sass sources will not appear in the running app, because the app loads the compiled file.

npm run build

The README also documents running the documentation site locally. That path is separate from the app and requires Jekyll 2.5.x plus the Rouge syntax highlighter, installed as a Ruby gem. From the repository root you run jekyll serve and open http://localhost:4000. This is only worth doing if you want to read the component docs offline; it is not part of consuming the toolkit.

Where Photon stops being the right tool

The most concrete limitation is the release history. The newest release listed is v0.1.2-alpha, dated 2015-10-18, and it carries an alpha label. The last push to the repository was on 2026-04-03, so the code has moved since that tag, but no later release has been cut. Anyone who pins to the tagged stable copy is pinning to an alpha build from 2015; anyone who tracks master is told by the README itself that they are on an unstable branch. That is a real fork in the road, and the project does not resolve it for you.

The second limitation is the dependency surface. The devDependencies in package.json include electron-prebuilt ^0.36.0 and Grunt ~0.4.5. Electron's major version has moved far past 0.36 since, and Grunt 0.4 is an old line. The README does not document an upgrade path for either, and the versioning section only commits to Semantic Versioning for Photon's own releases, not for its toolchain. If your application already runs a modern Electron release, expect to reconcile the template app's package.json against your own before npm start does anything useful.

Third, Photon is a stylesheet and an icon font. It has no accessibility documentation, no theming API beyond editing Sass, and no component behaviour layer. Anything interactive, such as a menu that opens or a dialog that traps focus, is your code. The template app's js/menu.js is the only behavioural example the README mentions, and it is a single file.

Photon against a general CSS framework

The obvious alternative for someone who wants prebuilt styling in an Electron app is a general-purpose CSS framework such as Bootstrap or Foundation. The difference in approach is the target, not the technology. A general framework styles web pages: responsive grids, breakpoints, mobile-first layout, typography for long-form content. Photon styles desktop chrome. Its components map to window furniture (toolbars, sidebars, title bars) and its icon font ships with the toolkit instead of being pulled from a separate icon library. A general framework will give you a grid system you do not need in a fixed-size desktop window and will not give you a title bar that matches macOS. Photon gives you the title bar and no grid. If your Electron app also has a marketing site or a web dashboard, a general framework covers both surfaces with one dependency, while Photon covers only the desktop shell. That is the trade: narrower scope, closer fit, and a dependency that has not seen a tagged release since 2015.

Licence, maintenance and upgrade cost

Photon is released under the MIT licence, and package.json carries "license": "MIT". MIT permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained; the LICENSE file at the repository root is where that text lives. This is a permissive licence with no copyleft obligation, but it says nothing about the licences of the bundled Entypo font files, which are separate assets under fonts/ and are not addressed in the README. If you redistribute the font, check its terms yourself; the README does not state them. On maintenance, the last push was on 2026-04-03, so the repository is not archived and code has been committed within the last six months. That is not the same as an active release cadence: the release list stops at v0.1.2-alpha in 2015. The upgrade cost follows from that. There are no changelogs or migration notes in the repository, so moving from the 0.1.2 tag to current master means reading commits. Vendoring dist/css/photon.css into your project, rather than depending on the repository, is the lower-risk path, because it freezes the stylesheet you have actually looked at.

What to check before you build on it

The README's own warning is the place to start: master is the unstable branch and stable copies live in the tags. Clone the repository, then compare the dist/ directory on master with the v0.1.2 build to see how much has changed since the last release. Next, open dist/template-app/package.json and read the Electron version it pins; that number tells you how much work stands between the example and your runtime. Then run npm start and click through the components you intend to use. The documentation site at photonkit.com is built from the docs/ directory with Jekyll, so the local copy is the same content, and it is the only component reference the project ships.

Editorial conclusion

Adopt connors/photon if you are building an Electron app that should look like a native macOS window and you are willing to vendor the compiled photon.css into your own repository rather than track it as a dependency. Do not adopt it if you need an actively maintained component library, a documented upgrade path, or support for frameworks beyond plain HTML and CSS. Before committing, clone the repository, check what the master branch actually contains against the tagged 0.1.2 build, and confirm that the template app's Electron version in package.json still matches the runtime you plan to ship.

Frequently asked questions

Official sources

1. connors/photon on GitHub
2. Issues
3. License: MIT
4. README
5. Releases