A clock based on Cistercian numerals
Published: 2021-03-17 00:39:14

---
date: 20210317
---
<p>Let me tell you the story of when I tried Twitch for the first time to live-code a Web Component that displays numbers with Cistercian numerals, so I could build a clock like this:</p>
<p><img src="https://www.hsablonniere.com/a-clock-based-on-cistercian-numerals--hptit8/cistercian-clock-time.26388cd3.png" alt="Clock displaying the time at 23:38:51 with colored Cistercian numerals"></p>
<h2>Yet another side project idea</h2>
<p>Back in January 2021, I saw <a href="https://twitter.com/Rainmaker1973/status/1348307518045507584">a tweet</a> about Cistercian numerals.
I was very intrigued.
If you don't know about them, here's the introduction from the <a href="https://en.wikipedia.org/wiki/Cistercian_numerals">Wikipedia page</a>:</p>
<blockquote>
<p>The medieval Cistercian numerals, or &quot;ciphers&quot; in nineteenth-century parlance, were developed by the Cistercian monastic order in the early thirteenth century at about the time that Arabic numerals were introduced to northwestern Europe. They are more compact than Arabic or Roman numerals, with a single character able to indicate any integer from 1 to 9,999.</p>
</blockquote>
<p>They look like this:</p>
<p><img src="https://www.hsablonniere.com/a-clock-based-on-cistercian-numerals--hptit8/wikipedia-cistercian-numerals.d5586008.png" alt="Some numbers represented with cistercian numerals: 1, 20, 400, 4000, 5555, 6789, 9394"></p>
<p>I really like how compact and elegant it is to display a big number with just one symbol, especially when there is some symmetry.</p>
<p>A few days later, I saw <a href="https://twitter.com/aqandrew/status/1349762018639638528">a tweet</a> from <a href="https://twitter.com/aqandrew">Andrew Aquino</a> saying he created a React component to display any number with Cistercian numerals.
My <a href="https://twitter.com/hsablonniere/status/1357079582499876867">first reaction</a> was to tweet:</p>
<blockquote>
<p>sudo make web-component</p>
</blockquote>
<p>I was expecting someone to create a Web Component, so we could all have a standard compatible way to display Cistercian numbers on our websites, even if we don't use React.
Instead, out of distaste for <code>sudo</code>, my wonderful colleague <a href="https://twitter.com/Keruspe/">Marc-Antoine Perennou</a> created <a href="https://github.com/Keruspe/sudo-ng">sudo-ng</a>.
Nothing happened, so I guess I was left with yet another side project idea.
Although this time, I decided to do it live with an audience.</p>
<h2>Trying Twitch for the first time</h2>
<p>In the pre-pandemic world, I used to give talks at conferences and share my knowledge and passion for Web development.
When you code in front of hundreds of people in a conference room, everything is well-prepared and rehearsed many times.
There is a kind of illusion of simplicity, but it's the best way to go straight to the point and focus on the new stuff the audience wants to learn about.
The minor drawback is that people miss everything that happens in real life when you write code.
You read some docs, you make mistakes, you try something, you go back, you get stuck on a silly bug...</p>
<p>Watching someone thinking out loud and writing code without preparation is a wonderful way to learn.
You discover new IDE keyboard shortcuts.
You learn about some unknown language pattern or feature.
It feels a bit like pair-programming with a mentor.</p>
<p>Following a few <a href="https://www.twitch.tv/nullpointeur">fellow</a> <a href="https://www.twitch.tv/k33g_org">speakers</a> that got into Twitch during the first lockdown, I decided to create <a href="https://www.twitch.tv/hsablonniere">my channel</a> and try the platform for this side project idea.</p>
<p>My main goal was to create a Web Component to display a number with Cistercian numerals and then reuse it to create a clock component that displays three Cistercian numbers: hours, minutes and seconds.
Bonus points if I could animate the lines of the symbols.</p>
<h2>The live-coding session</h2>
<p><img src="https://www.hsablonniere.com/a-clock-based-on-cistercian-numerals--hptit8/twitch-session-screencap.10dcfe87.png" alt="Screenshot of the Twich session with an IDE on the left, the browser on the right, and my webcam in the bottom right corner"></p>
<p>If you're interested, I posted a <a href="https://www.youtube.com/watch?v=88AKamcJ-bY">recording of the session</a> on YouTube but beware:</p>
<ul>
<li>👂 It's in French.</li>
<li>⌛ It's 2 hours long (120 minutes)</li>
<li>💬 The chat is NOT displayed.</li>
<li>😱 I spent way too much time on Inkscape trying to generate the initial SVG design.</li>
<li>🚧 I should have built both components before thinking about animating them.</li>
</ul>
<p>Despite those, I really enjoyed giving this session.
Mistakes were made, but we finished with some kind of achievement.
The clock design was a bit clunky, but it worked.
It looked like this:</p>
<video controls="">
  <source src="https://www.hsablonniere.com/a-clock-based-on-cistercian-numerals--hptit8/cistercian-clock-at-the-end-of-the-stream.8e11234e.mp4" type="video/mp4">
  Sorry, your browser doesn't support embedded videos.
</video>
<p>If I were to do it again, I would prioritize the different steps, so the progress is more linear for the audience.
I would also improve the way I timebox steps, so I would stop insisting on some details.
This retrospective analysis reflects the constructive feedbacks I got from audience members afterwards.</p>
<p>As a host, this session was really pleasant to give, and it almost didn't require any preparation.
Between 60 and 70 people attended the stream, and some of them really helped me through the chat.
Apart from the code and tips, I think I managed to share the fun I had working on this side project.</p>
<p>I really want to do it again with other side projects ideas.
I could try more interactivity with the audience through the chat (and maybe some sounds/music).
It's very different from what I'm used to with conference talks.
The number of interesting information per minute is clearly not the same, but I don't think it's a problem in itself.
I think it's just a different way of sharing knowledge with others.
A bit slower, more interactive, less magic but definitely more authentic.</p>
<h2>Post-stream improvements</h2>
<p>After the stream, I decided to improve the project:</p>
<ul>
<li>Implement the numbers after 99</li>
<li>Fix the positioning of the different lines</li>
<li>Add some animations using the <a href="https://jakearchibald.com/2013/animated-line-drawing-svg/">animated line drawing SVG</a> technique</li>
</ul>
<p>A few weeks after, I added a few more features:</p>
<ul>
<li>Use CSS custom properties to allow color customization of each lines</li>
<li>Use CSS custom properties to allow line width customization</li>
<li>Add <code>date</code> mode for the clock to display year, month, day before hours, minutes, seconds</li>
<li>Add <code>no-seconds</code> mode for the clock to remove the seconds</li>
<li>Add <code>inline</code> mode for the number, so you can use a number inside a paragraph of text (as featured in this article if you're reading it from my site)</li>
<li>Try to improve the accessibility (any feedbacks on this is welcome)</li>
</ul>
<p>I published the source on GitHub at <a href="https://github.com/hsablonniere/cistercian-numerals">hsablonniere/cistercian-numerals</a> if you're curious.</p>
<h2>Web Components are awesome!</h2>
<p>Because they're exposed as Web Components, you can use them in any Web project, whatever the stack/framework you're using.
You can install them <a href="https://www.npmjs.com/package/cistercian-numerals">from npm</a> but it's not mandatory at all.</p>
<p>As described in the <a href="https://github.com/hsablonniere/cistercian-numerals/blob/master/README.md">README</a>, you can use these components in your HTML without any <code>npm install</code>, without any build step or bundler.
All you need is a <code>&lt;script&gt;</code> tag sourcing a modern smart CDN like jspm:</p>

```html
<!-- put this in <head> -->
<script type="module" src="https://jspm.dev/cistercian-numerals"> </script>
```

<p>Then you'll be able to use the number component in your HTML like this:</p>

```html
<cistercian-number inline value="12"></cistercian-number>
```

<p>You'll also be able to use the clock component in your HTML like this:</p>

```html
<cistercian-clock></cistercian-clock>
```

<p>Because it's just HTML, it's also very easy to integrate in a Markdown document.
It's exactly what I'm doing right now with this article, but you need to browse it from <a href="https://www.hsablonniere.com">my site</a>.
Here's the date + time (without seconds) example:</p>
<p><img src="https://www.hsablonniere.com/a-clock-based-on-cistercian-numerals--hptit8/cistercian-clock-datetime.d0d6ca63.png" alt="Clock displaying the date at 2021-3-16 and the time at 23:39 with colored Cistercian numerals"></p>
<p>Please see the <a href="https://github.com/hsablonniere/cistercian-numerals/blob/master/README.md#components">README</a> for more details about how to use and customize the components.</p>
<h2>References &amp; Links</h2>
<ul>
<li><a href="https://en.wikipedia.org/wiki/Cistercian_numerals">Cistercian numerals</a> on Wikipedia</li>
<li><a href="https://www.youtube.com/watch?v=88AKamcJ-bY">Recording of the Twitch session</a> on YouTube</li>
<li><a href="https://github.com/hsablonniere/cistercian-numerals">Source code</a> on GitHub
<ul>
<li><a href="https://github.com/hsablonniere/cistercian-numerals/blob/master/src/cistercian-number.js">Source code for &lt;cistercian-number&gt;</a> on GitHub</li>
<li><a href="https://github.com/hsablonniere/cistercian-numerals/blob/master/src/cistercian-clock.js">Source code for &lt;cistercian-clock&gt;</a> on GitHub</li>
</ul>
</li>
<li><a href="https://www.npmjs.com/package/cistercian-numerals">JavaScript package</a> on npm</li>
<li><a href="https://jakearchibald.com/2013/animated-line-drawing-svg/">Animated line drawing SVG</a> by Jake Archibald</li>
<li><a href="https://lit.dev/">Lit (formerly LitElement)</a>, the library I used to build the Web Components</li>
<li><a href="https://modern-web.dev/docs/dev-server/overview/">Web Dev Server</a>, the dev server I use for live preview</li>
<li><a href="https://adrianroselli.com/2021/02/cistercian-svg.html">Cistercian SVG</a> by Adrian Roselli</li>
<li><a href="https://ednl.github.io/cistercian-clock/?size=80">p5js based cistercian clock</a> by E. Dronkert</li>
<li><a href="https://hackaday.io/project/178131-monklock">Arduino + dot matrix cistercian clock</a> by Danjovic</li>
<li><a href="https://getwatchmaker.com/watchface/cistercian-clock">Smart watch face cistercian clock</a> by Philip McGeehan</li>
<li><a href="https://matthewfelgate.wordpress.com/2023/06/26/the-revival-of-cistercian-numerals-a-journey-from-the-15th-century-to-modern-smartwatch/">Smart watch face cisterian clock (inspired by my design)</a> by Matthew Felgate</li>
<li><a href="https://twitter.com/aqandrew/status/1349762018639638528">React based cistercian number component</a> by Andrew Aquino</li>
<li><a href="https://mz8i.com/cistercian">React based cistercian number component</a> by Maciej Ziarkowski</li>
<li><a href="https://github.com/TiroTypeworks/Clairvo">Clairvo</a>, a proof-of-concept font that uses OpenType Layout to implement Cistercian numerals</li>
</ul>
<h2>Thank you</h2>
<p>😍 Thank you wonderful people who attended the stream and thank you wonderful reviewers for your time: <a href="https://alexandre.berthaud.me/">Alexandre Berthaud</a>.</p>

  <div class="edit-link-wrapper">
    <a href="https://github.com/hsablonniere/hsablonniere.com/blob/master/pages/a-clock-based-on-cistercian-numerals--hptit8/index.md">Edit this page on GitHub</a>
  </div>