<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Jérémie Uzan on Medium]]></title>
        <description><![CDATA[Stories by Jérémie Uzan on Medium]]></description>
        <link>https://medium.com/@jeremie.uzan?source=rss-f30c79c7f61------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*pdwItd_MtBSmRM2AamBGmw.jpeg</url>
            <title>Stories by Jérémie Uzan on Medium</title>
            <link>https://medium.com/@jeremie.uzan?source=rss-f30c79c7f61------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Sat, 21 Nov 2026 17:45:29 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@jeremie.uzan/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[How a “Share” button led us to build a permissions graph]]></title>
            <link>https://medium.com/doctrine/how-a-share-button-led-us-to-build-a-permissions-graph-85c408c08bff?source=rss-f30c79c7f61------2</link>
            <guid isPermaLink="false">https://medium.com/p/85c408c08bff</guid>
            <category><![CDATA[permission]]></category>
            <category><![CDATA[openfga]]></category>
            <category><![CDATA[modeling]]></category>
            <category><![CDATA[engineering]]></category>
            <dc:creator><![CDATA[Jérémie Uzan]]></dc:creator>
            <pubDate>Wed, 15 Jul 2026 14:05:50 GMT</pubDate>
            <atom:updated>2026-07-16T13:51:12.896Z</atom:updated>
            <content:encoded><![CDATA[<p><em>Or: how a feature that fits in one sentence ended up requiring a POC, a relationship graph, and deeper changes than expected.</em></p><p><em>Written with </em><a href="https://medium.com/u/d3e66b5bbb7"><em>Vincent Perez</em></a><em>.</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*l_nNNvQJ1ula5n53t4SSAw.jpeg" /></figure><p>At the start, the need seemed simple: let Doctrine users work together. Create a workspace, add documents to it, invite colleagues. In short: a “Share” button and a few avatars in the interface.</p><p>Of course, it wasn’t that simple. Behind that button lurked less pleasant questions: who can access what, who can edit or delete a resource, can a folder be shared with an entire organization, what happens when a user leaves it, and how do you handle all this without adding thirty-seven if statements to every controller?</p><p>To build our new collaboration experience, we had to solve two problems at once: create the new product objects that are <strong>Matters</strong> and <strong>Knowledge Bases</strong>, and build a permission model flexible enough to support them.</p><h3>Matters and Knowledge Bases</h3><p>A <strong>Matter</strong> is a workspace dedicated to a specific case: a lawyer adds case documents to it, runs analyses, and opens conversations with the Assistant. The idea is to bring work together around a single subject rather than scatter it.</p><p>A <strong>Knowledge Base</strong> (KB) addresses a different need: building a reusable reference corpus (internal analyses, templates, court rulings) and connecting it to multiple Matters and conversations.</p><p>In both cases, several users need to be able to “have access” to the same resource. And that’s where the problems start.</p><h3>“Having access” is too vague to be useful.</h3><p>On a Matter, a user might have the right to view it, edit it, share it with their organization, or delete it. On a KB, the rules differ: the owner can edit it, a Knowledge Manager can administer it, a regular member can only view it, and a personal KB can only be viewed by its owner.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*jxxD4eq-xmagt0eSNDuCqg.png" /></figure><p>Organization membership also has to be taken into account: being an editor on a Matter should no longer mean anything once you’ve left the owning organization. So permission doesn’t depend on a role column, but on a set of relationships:</p><pre>Alice belongs to the organization Doctrine<br>Alice is an editor on Matter A<br>Matter A belongs to the organization Doctrine</pre><p>It’s the combination of these relationships that answers the real question: can Alice edit Matter A?</p><h3>Why our existing system wasn’t enough</h3><p>Before this project, authorization was handled in the API layer, via a list of permissions based on user attributes (and CASL for organization-related cases). That was sufficient for our historical needs and the checks were concentrated in our main API.</p><p>More importantly, this system answered questions about a user’s role, not about a specific resource. With Matters and KBs, that’s exactly what we needed: Alice can edit Matter A but not Matter B. We could have kept adding tables and guards, but we would have ended up scattering authorization logic across the entire application; not the kind of investigation you want to run for every support ticket or security audit.</p><h3>Choosing a permission model suited to our needs</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*5sL07gaWuCrNnx-54zRGLw.png" /><figcaption>Comparison between permission models</figcaption></figure><p>We went with ReBAC, limiting its scope to resource sharing rather than migrating the entire existing system (a full migration would likely have quadrupled the project’s duration).</p><h3>Why not “just” PostgreSQL?</h3><p>We could have kept everything in the database: tables like matter_members, knowledge_base_viewers, and SQL queries to compute rights. For some questions, SQL is still hard to beat. The problem arises when the model gets more complex: a rule like &quot;a user can edit a Matter if they are an editor AND still a member of the organization&quot; has to be reapplied everywhere (reads, edits, sharing, lists, the Assistant, admin), and then come the exceptions and the folder hierarchies still to come.</p><p>We could have built an in-house abstraction layer. But push far enough in that direction, and you end up building your own authorization engine without quite realizing it. A permissions engine is simple to build. A correct, testable, maintainable one is a different story.</p><h3>Surveying the solutions</h3><p>We weren’t just looking for a tool that answers true or false. We needed a model that was understandable, auditable, testable, and observable — one able to support Matters, KBs, and future folder hierarchies.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*S_7fuVfRiHcDs2TbEJPDBA.png" /><figcaption>Comparison between technical implementations</figcaption></figure><p>We were not trying to reproduce Zanzibar exactly as described in <a href="https://research.google/pubs/zanzibar-googles-consistent-global-authorization-system/">Google’s original paper</a>. Instead, we wanted to borrow the ideas that made sense for our use cases, while keeping the system reasonable to operate.</p><p>Furthermore, these solutions offered a great developer experience, especially thanks to an efficient playground that made it easy to quickly test the permission models we were considering.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*W2BseCeymjLVi3O8mxtzFA.png" /><figcaption>Playground of OpenFGA</figcaption></figure><h3>The POC</h3><p>We deployed OpenFGA using its official Helm chart, a dedicated PostgreSQL instance on AWS RDS, all described in Terraform, on deliberately modest infrastructure (2 vCPU, 2 GiB RAM, a single node). The whole thing was up and running in a day, a good sign; we didn’t want to spend three weeks deploying a service before we could even ask it whether Alice had the right to read a folder.</p><h3>How the model works in practice</h3><p>Before anything else, OpenFGA requires configuring an <strong>authorization model</strong>. This schema serves as the source of truth: it validates the consistency of our permissions and dictates what’s syntactically possible.</p><p>Our model relies on four object types (user, organization, matter, knowledge_base), connected not by columns but by relationship tuples. For example, as soon as a user creates a <em>Matter</em>, the system records the following tuple:</p><pre>organization:doctrine owner_org matter:dupont<br>user:alice editor matter:dupont</pre><p>An editor can read, edit, delete, or share the Matter, with one condition: they must still belong to the owning organization.</p><pre>editor = user explicitly added AND member of the owning organization</pre><p>This intersection guards against mistakes: if a bug adds Bob as an editor while he belongs to a different organization, OpenFGA still denies access. The tuple exists, but produces no permission : a bit like adding someone to the guest list, only to find out at the door that they’re clearly at the wrong wedding. And when a user leaves the organization, removing that single relationship is enough to instantly invalidate all their access, without touching every Matter one by one.</p><h4>What about performance?</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*fccelyz13wKdzSzKbVgK5g.png" /><figcaption>Performance of operations</figcaption></figure><p>The measured performance was encouraging, and the impact of nested hierarchies (e.g. folders within folders) on response time stayed under control.</p><h3>A few additional architecture choices</h3><p>Our roles (ADMIN, MEMBER, KNOWLEDGE_MANAGER) already existed in PostgreSQL, but OpenFGA also needed to know about them to evaluate permissions. We ended up duplicating them in both systems: PostgreSQL remains the source of truth for product usage (lists, filters, interfaces), while OpenFGA evaluates the graph directly. It&#39;s not the theoretically purest solution, but it&#39;s the compromise that best fits our current needs — provided we accept a few safeguards: a single entry point for changing a role, logged writes, and reconciliation scripts to detect drift.</p><p>To avoid scattering OpenFGA tuples across every controller, we also built an abstraction layer (PermissionEngineService) that wraps the SDK, topped by business services (MatterWorkspaceService, KnowledgeBaseWorkspaceService) that expose methods like canEdit() or canShare(). The rest of the application deals only in business concepts, without ever knowing that OpenFGA is traversing multiple relationships to answer.</p><h3>What we take away from this</h3><ul><li><strong>The need must come from the product:</strong> we didn’t adopt OpenFGA for the pleasure of having a relationship graph, but because Matters and KBs demanded a collaborative model that couldn’t be handled cleanly any other way.</li><li><strong>The tool isn’t just its syntax:</strong> both OpenFGA and SpiceDB could model our needs. The decision came down to operational alignment, ease of integration, and day-to-day deployment.</li><li><strong>Separate the concepts:</strong> ownership, organization, and visibility are three orthogonal concepts. They must be modeled separately.</li><li><strong>Think about the full permission lifecycle</strong>: creating relationships is only half of the problem. A reliable model must also define when and how permissions are removed, for example when a user leaves an organization, a resource is deleted, or ownership changes.</li><li><strong>Strict constraints are essential:</strong> a good model must be able to prove and guarantee why Bob does <em>not</em> have access to a resource, even if a bad relationship gets written by accident.</li></ul><h3>Conclusion</h3><p>Building collaboration at Doctrine wasn’t just about adding a sharing modal. It required creating new product objects, understanding the difference between operational collaboration and knowledge distribution, and then translating all of that into a coherent permission model.</p><p>OpenFGA wasn’t the only solution technically capable of meeting the need. We chose it because its integration, deployment, observability, and results in our tests best matched our constraints. Today, it lets us answer a question that looks simple on the surface:</p><blockquote>Can this user read this resource?</blockquote><p>Behind it, the engine checks the user’s role, their organization, the resource’s owner, and how it was shared.</p><p>The <strong>Share</strong> button is still there. It just now has, behind it, a permissions graph, several services, and a handful of RFCs.</p><p>And this is only one part of the collaboration story. The next challenges are already taking shape: helping multiple users work concurrently on shared resources, without losing clarity, ownership, or control.</p><p>Like all <strong>simple</strong> buttons, in the end.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=85c408c08bff" width="1" height="1" alt=""><hr><p><a href="https://medium.com/doctrine/how-a-share-button-led-us-to-build-a-permissions-graph-85c408c08bff">How a “Share” button led us to build a permissions graph</a> was originally published in <a href="https://medium.com/doctrine">Inside Doctrine</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[The painful awakening: when DX turns against you]]></title>
            <link>https://medium.com/doctrine/the-painful-awakening-when-dx-turns-against-you-d4c88e4f14ac?source=rss-f30c79c7f61------2</link>
            <guid isPermaLink="false">https://medium.com/p/d4c88e4f14ac</guid>
            <category><![CDATA[engineering]]></category>
            <category><![CDATA[typescript]]></category>
            <category><![CDATA[monorepo]]></category>
            <category><![CDATA[package]]></category>
            <category><![CDATA[transpilation]]></category>
            <dc:creator><![CDATA[Jérémie Uzan]]></dc:creator>
            <pubDate>Tue, 02 Sep 2025 09:48:17 GMT</pubDate>
            <atom:updated>2025-09-02T09:48:17.641Z</atom:updated>
            <content:encoded><![CDATA[<p>One morning, after a few months of peaceful development, we started hearing grumbles from the team. “<em>My IDE is lagging”</em>, “<em>It takes forever to start up”</em>, “<em>My laptop is heating up like a radiator”</em>.</p><p>At first, we thought it was just a few developers exaggerating. Then the complaints multiplied. The startup times for our application had become unbearable.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*QittS2FMQNzcRKyF.png" /></figure><p>After digging a bit, we pinpointed the root of the problem, which stemmed directly from our technical stack: a <strong>pnpm monorepo</strong>. While this setup allows our Next.js application to consume shared packages directly from the local workspace, it introduced a major flaw to our “perfect” architecture. With each modification to the design system, the <strong>ENTIRE</strong> package had to be rebuilt, forcing the Next.js application to wait for it to finish before restarting. This created a massive bottleneck in our development pipeline.</p><h3>First attempt: just-in-time transpilation</h3><p>Faced with this realization, we decided to act. Our first idea was simple: what if we stopped pre-compiling our packages and instead compiled them directly in the applications that need them?</p><p>That’s when we discovered Next.js’s <a href="https://nextjs.org/docs/app/api-reference/config/next-config-js/transpilePackages">transpilePackages</a>. This option allows bundling libraries directly into Next.js applications, without going through a separate build step.</p><pre>// next.config.js<br>module.exports = {<br>  transpilePackages: [&#39;@doctrinelegal/design-system&#39;, &#39;@doctrinelegal/front-client-shared&#39;, &#39;@doctrinelegal/front-server-shared&#39;]<br>}</pre><p>But that was only half the journey. We also needed to adapt our packages to directly expose their TypeScript files. That’s where “conditional exports” came into play:</p><pre>// package.json of our design-system<br>{<br>  &quot;exports&quot;: {<br>    &quot;./button&quot;: {<br>      &quot;development&quot;: {<br>        &quot;import&quot;: &quot;./src/components/button/index.ts&quot;, // Used by Next in dev<br>      },<br>      &quot;import&quot;: &quot;./dist/button.js&quot;, // Use for the build in production<br>    }<br>}</pre><p>With this configuration, in development mode, Next.js consumes our .ts files directly and handles the compilation. No more cascading builds or multiple watchers!</p><h3>Second obstacle: TypeScript acting up</h3><p>Our joy was short-lived. After implementing this new approach, TypeScript started giving us trouble. Type checking no longer worked correctly, and we had weird errors related to module resolution.</p><p>The real problem was more subtle than we initially thought. In our packages, we were using typescript internal aliases to avoid unsightly relative imports. For example, in our design-system:</p><pre>// Instead of ../../components/Button<br>import { Button } from &#39;#components/Button&#39;<br>import { theme } from &#39;#tokens/theme&#39;</pre><p>These aliases were defined in the tsconfig.json of each package (t<em>hanks to Cédric</em>):</p><pre>// tsconfig.json of the design-system<br>{<br>  &quot;compilerOptions&quot;: {<br>    &quot;paths&quot;: {<br>      &quot;#components/*&quot;: [&quot;./src/components/*&quot;],<br>      &quot;#tokens/*&quot;: [&quot;./src/tokens/*&quot;]<br>    }<br>  }<br>}</pre><p>The problem? With just-in-time transpilation, Next.js consumes our TypeScript files directly, but it doesn’t understand the aliases defined in the packages’ tsconfig.json files. The result: module resolution errors everywhere.</p><p>The solution was to abandon TypeScript aliases in favor of the subpath imports of Nodejs using the &quot;imports&quot; field in each package&#39;s package.json .</p><blockquote><em>In addition to the </em><em>&quot;exports&quot; field, there is a package </em><em>&quot;imports&quot; field to create private mappings that only apply to import specifiers from within the package itself.</em></blockquote><blockquote><em>Entries in the </em><em>&quot;imports&quot; field must always start with </em><em># to ensure they are disambiguated from external package specifiers. </em><a href="https://nodejs.org/api/packages.html#subpath-imports"><em>https://nodejs.org/api/packages.html#subpath-imports</em></a></blockquote><pre>// package.json of the design-system<br>{<br>  &quot;imports&quot;: {<br>    &quot;#components/*&quot;: &quot;./src/components/*&quot;,<br>    &quot;#tokens/*&quot;: &quot;./src/tokens/*&quot;<br>  }<br>}</pre><p>This approach works natively with Node.js and is understood by all modern bundlers, including Next.js in on-demand transpilation mode. No more need for specific configuration!</p><p>But that was still only part of the solution. We also needed to revise our TypeScript configuration to adopt the “project references” system and enable the “composite” option:</p><pre>// tsconfig.json in the next project<br>{<br>  &quot;references&quot;: [<br>    { &quot;path&quot;: &quot;../../packages/design-system&quot; },<br>    { &quot;path&quot;: &quot;../../packages/front-client-shared&quot; },<br>    { &quot;path&quot;: &quot;../../packages/types&quot; }<br>  ]<br>}</pre><pre>// tsconfig.json of each package<br>{<br>  &quot;compilerOptions&quot;: {<br>    &quot;composite&quot;: true<br>  }<br>}</pre><p>This approach allows TypeScript to build a dependency graph between our projects. Thanks to the composite option, it generates .tsbuildinfo files that store information about the compilation. Now, when something is modified, TypeScript knows exactly which dependent files need to be re-checked, without having to re-analyze everything. This is the secret to efficient <strong>incremental compilation</strong>.</p><h3>The result: a complete transformation</h3><p>Today, several weeks after those changes, we have a completely transformed development environment:</p><ul><li><strong>Instant reactivity</strong>: modifying a component in the design system only triggers the recompilation of the relevant segment in Next.js</li><li><strong>Controlled RAM consumption</strong>: no more multiple watchers running in parallel</li><li><strong>Restored DX</strong>: our developers have rediscovered the joy of coding without waiting</li></ul><p>What surprised us most was seeing how an architecture that seemed logical on paper could create unexpected problems when scaled up. With our monorepo exceeding one million lines of code, this theoretical organization resulted in very real slowness on a daily basis. The lesson we learned? Always keep an eye on the developer experience, even when everything seems well organized.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=d4c88e4f14ac" width="1" height="1" alt=""><hr><p><a href="https://medium.com/doctrine/the-painful-awakening-when-dx-turns-against-you-d4c88e4f14ac">The painful awakening: when DX turns against you</a> was originally published in <a href="https://medium.com/doctrine">Inside Doctrine</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[How We Published Our Design System: A Journey into Continuous Integration]]></title>
            <link>https://medium.com/doctrine/how-we-published-our-design-system-a-journey-into-continuous-integration-5e3d54a22ef8?source=rss-f30c79c7f61------2</link>
            <guid isPermaLink="false">https://medium.com/p/5e3d54a22ef8</guid>
            <category><![CDATA[engineering]]></category>
            <category><![CDATA[design]]></category>
            <category><![CDATA[process]]></category>
            <category><![CDATA[design-systems]]></category>
            <category><![CDATA[publishing]]></category>
            <dc:creator><![CDATA[Jérémie Uzan]]></dc:creator>
            <pubDate>Tue, 22 Oct 2024 15:04:39 GMT</pubDate>
            <atom:updated>2024-10-22T15:17:21.131Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*tYdUG1NOtDX91uW2Nt2D1Q.jpeg" /></figure><p><em>At Doctrine, our path to publishing our Design System has been an adventure full of lessons. It wasn’t a decision we made overnight, but rather the result of a long process of iteration and continuous improvement. In this article, we’ll take you behind the scenes of this adventure, sharing our thoughts, challenges, and the solutions we implemented to succeed in this crucial transition.</em></p><h3>The Context: From Uniqueness to Diversity</h3><h4>Humble Beginnings</h4><p>It all started with <a href="http://doctrine.fr/">doctrine.fr</a>, our flagship product. At the time, our development approach was simple and direct: one product, one codebase. This simplicity allowed us to progress quickly and efficiently iterate on our main offering.</p><h4>Expansion and Its Challenges</h4><p>But like any growing startup, we quickly felt the need to expand our offering. New projects emerged:</p><blockquote><em>1. Add-ins for Microsoft Word<br>2. An Italian version of our platform: </em><a href="http://doctrine.it/"><em>doctrine.it</em></a></blockquote><p><em>This diversification raised a major challenge: how to maintain visual and functional consistency across all these products?</em></p><p>That’s where the idea of a published centralized Design System began to take root.</p><p><strong>However, the expansion wasn’t just about products.</strong></p><p>Behind the scenes, our team was growing rapidly. With each new developer joining Doctrine, we faced a new challenge: <em>how to ensure everyone was aligned with our design principles and coding standards?</em> This question became increasingly crucial as our team expanded across different products and even different countries.</p><h3>Why a Design System?</h3><p>The decision to create a Design System and the development process was described in a <a href="https://medium.com/doctrine/enhancing-our-design-system-for-seamless-collaboration-and-consistency-23f3f47771b3">previously published article</a>. As a reminder, the goal was to implement consistent components across our product.</p><h4>The Answer to a Multi-Product Need</h4><p>The decision to publish a Design System wasn’t just a matter of aesthetics. It was a strategic necessity for several reasons:</p><p><strong>Maximize Reusability<br></strong>By centralizing our components and styles, we could ensure that each new project would immediately benefit from our previous work. This meant less time spent reinventing the wheel and more time devoted to innovation.</p><p><strong>Facilitate Product Evolution<br></strong> With a Design System, we could evolve all of our products consistently. A change in the Design System would ripple through all the products that used it.</p><p><strong>Support Multi-Product Expansion<br></strong> As Doctrine diversified, the Design System became an essential tool for aligning teams and accelerating the development of new products.</p><h4>Aligning a Growing Team</h4><p>As our team grew, the Design System became more than just a tool for product consistency — it became a central point of reference for our expanding development team. New developers, regardless of which product they were working on, could rely on the Design System as a guide to our UI patterns and coding standards. This helped us maintain consistency not just in our products, but in our development practices across an increasingly distributed team.</p><h4>The Choice of Monorepo: A Structuring Decision</h4><p>One of the most important decisions we made concerned the structure of our project. We opted for a monorepo approach, grouping all of our projects (front-end, API, Design System, common packages) into a single Git repository. It’s important to note that this choice was purely pragmatic and not directly related to the decision of publishing the design system.</p><p>This approach had several advantages:</p><p>-<strong> Simplified dependency management</strong>: All our dependencies were centralized, making it easier to update and maintain consistency.<br>- <strong>Global visibility</strong>: Developers could easily navigate between different parts of the project.<br>- <strong>Coordinated deployments</strong>: It was simpler to ensure that changes in one part of the system didn’t negatively affect others.</p><p>Here’s a simplified example of our monorepo structure and the add-in :</p><pre>nodejs-doctrine/<br>├── packages/<br>│ ├── design-system/<br>│ ├── shared/<br>│ └── types/<br>├── apps/<br>│ ├── doctrine-fr/<br>│ ├── doctrine-it/<br>│ ├── api-fr/<br>│ ├── api-it/<br>└── package.json<br><br>add-in/<br>├── package.json<br>└── src/</pre><h3>The Technical Challenge: Publishing the Design System</h3><p>Once the decision was made to create a Design System, we faced a new challenge: <em>how to publish it and make it consumable by other projects, while keeping it integrated into our monorepo?</em></p><h4>Step 1: Package Preparation</h4><p>The first step was to structure our Design System as an independent npm package. Here’s an example of the structure we adopted:</p><pre>packages/design-system/<br>├── src/<br>│ ├── components/<br>│ ├── styles/<br>│ └── index.ts<br>├── package.json<br>└── tsconfig.json</pre><p>In the package.json, we defined the necessary information for publication:</p><pre>{<br>   &quot;name&quot;: &quot;@doctrinelegal/design-system&quot;,<br>   &quot;version&quot;: &quot;1.0.0&quot;,<br>   &quot;description&quot;: &quot;Design system at Doctrine&quot;,<br>   &quot;main&quot;: &quot;dist/index.js&quot;,<br>   &quot;types&quot;: &quot;dist/index.d.ts&quot;,<br>   &quot;files&quot;: [<br>   &quot;dist&quot;<br>   ],<br>   &quot;scripts&quot;: {<br>     &quot;build&quot;: &quot;vite build&quot;,<br>     &quot;publish-package&quot;: &quot;npm publish&quot;<br>    },<br>  &quot;publishConfig&quot;: {<br>    &quot;access&quot;: &quot;restricted&quot;,<br>    &quot;registry&quot;: &quot;https://npm.pkg.github.com/doctrinelegal&quot;<br>  },<br> // …other configurations<br>}</pre><h4>Step 2: Integration into the CI/CD Process</h4><p>The next step was to integrate the publication of the Design System into our CI/CD pipeline. We used CircleCI for our continuous integration, and we had to adapt our configuration to account for the specificities of the Design System.</p><p>Here’s an excerpt from our CircleCI configuration (<em>config.yml</em>):</p><pre>version: 2.1<br>jobs:<br>   package_bump:<br>    description: &#39;Check if the version number of package.json in a specific package has changed&#39;<br>    parameters:<br>      package:<br>        type: string<br>    docker:<br>      - image: cimg/base:current<br>    steps:<br>      - checkout<br>      - run:<br>          name: Check if the version number of package.json has changed<br>          command: |<br>            PACKAGE_PATH=&quot;./&lt;&lt; parameters.package &gt;&gt;/package.json&quot;<br>            git fetch origin master:master<br>            OLD_VERSION=$(git show master:&quot;$PACKAGE_PATH&quot; | jq -r &#39;.version&#39;)<br>            NEW_VERSION=$(jq -r &#39;.version&#39; &quot;$PACKAGE_PATH&quot;)<br><br>            if [ &quot;$(printf &#39;%s\n&#39; &quot;$NEW_VERSION&quot; &quot;$OLD_VERSION&quot; | sort -V | head -n1)&quot; = &quot;$OLD_VERSION&quot; ]; then<br>              echo &quot;Version number has been upgraded from $OLD_VERSION to $NEW_VERSION&quot;<br>            else<br>              echo &quot;Version number has not been upgraded&quot;<br>              echo &quot;Indent the package.json file to trigger a new version&quot;<br>              echo &quot;Old version: $OLD_VERSION&quot;<br>              echo &quot;New version: $NEW_VERSION&quot;<br>              exit 1<br>            fi<br><br>  publish_design_system:<br>    description: &#39;Publish the design system package to the npm registry&#39;<br>    docker:<br>      - image: *node_image<br>    steps:<br>      - checkout<br>      - run:<br>          name: Configure npm for GitHub Packages<br>          command: |<br>            echo &quot;@doctrinelegal:registry=https://npm.pkg.github.com&quot; &gt;&gt; ~/.npmrc<br>            echo &quot;//npm.pkg.github.com/:_authToken=${GITHUB_ACCESS_TOKEN}&quot; &gt;&gt; ~/.npmrc<br>      - *install_pnpm<br>      - run:<br>          name: Publish the design system package to the npm registry<br>          command: |<br>            pnpm install --frozen-lockfile --filter=@doctrinelegal/design-system<br>            pnpm run publish-packages<br>workflows:<br> version: 2<br> pr_or_merge_on_master:<br>   jobs:<br>     #@ if &quot;@doctrinelegal/design-system&quot; in data.values.direct_changed_packages:<br>      - package_bump:<br>          package: &#39;packages/design-system&#39;<br>          &lt;&lt;: *not_master_branch<br>          requires:<br>            - setup_test_workspace<br>     #@ end<br>     #@ if &quot;@doctrinelegal/design-system&quot; in data.values.changed_packages:<br>      - publish-design-system:<br>        when:<br>          equal: [&#39;&#39;, &lt;&lt; pipeline.parameters.trigger_workflow &gt;&gt;]<br>        jobs:<br>          - publish_design_system:<br>              &lt;&lt;: *master_branch<br>      #@ end</pre><p>This configuration does two important things:</p><ol><li>It verifies that the package version has been updated when changes are made to the Design System folder during the creation of a pull request.</li><li>It automatically publishes the Design System to npm when changes are merged into the main branch.</li></ol><h4>Step 3: Version Management</h4><p>Version management is crucial for maintaining our Design System. We adopted semantic versioning (<a href="https://semver.org/">SemVer</a>) to clearly communicate the extent of changes with each new version.</p><p>Currently, our version bump process is manual. Although we explored automated options like <a href="https://github.com/changesets/changesets">Changesets</a>, we found they didn’t perfectly match our needs at the moment.</p><p>Here’s how we manage versions manually:</p><p>1. <strong>Change Evaluation</strong>: Before each publication, we carefully examine the changes made to the Design System.<br>2. <strong>Version Decision</strong>: Based on the nature of the changes, we decide whether it’s a major, minor, or patch update.<br>3. <strong>Manual Update</strong>: A team member manually updates the version in the Design System’s <em>package.json</em> file.<br>4. <strong>Verification</strong>: Our CI pipeline verifies that the version has been updated when changes are detected in the Design System folder.</p><p>This manual approach offers us several advantages:</p><ul><li>Precise Control: We can evaluate each change and decide on its impact on the version.</li><li>Flexibility: We can easily adapt our versioning strategy as our needs evolve.</li><li>Team Awareness: The manual process encourages team members to actively think about the impact of their changes.</li></ul><p>While this approach works well for us currently, we remain open to refine our process. We continue to explore automated solutions that would align with our workflow in the future, while maintaining the level of control and reflection we appreciate in our current approach.</p><h3>Ownership and Governance of the Design System</h3><p>One question that often arises in the context of a Design System is: <em>who owns it</em>? At Doctrine, we’ve found that a shared ownership model works best for us.</p><p>We also want to ensure that our design system is the single source of truth. Therefore, other consumers of the design system (such as the add-in) are responsible for verifying that nothing breaks when updating the version of the design system dependency.</p><h4>Promoting the Design System</h4><p>Creating a Design System is one thing; ensuring it’s widely adopted is another challenge altogether. We’ve implemented several strategies to promote our Design System across the organization.</p><p>We use Storybook as a central hub for our Design System. Storybook provides several advantages like documentation, visual testing and also a tool to interact and see components directly.</p><h4>Onboarding New Developers</h4><p>For new team members, we’ve made the Design System a key part of our onboarding process:</p><ul><li>We include a Design System task in our onboarding documentation. The task involves analyzing Figma models to familiarize themselves with components and locate them in the design system package.</li><li>New developers are encouraged to explore Storybook during their onboarding. This helps them gain a deep understanding of how components work and prevents them from recreating existing components.</li></ul><h3>Lessons Learned</h3><p>Our journey to publishing our Design System taught us several important lessons:</p><ul><li><strong>The Importance of Planning</strong>: Anticipating future needs allowed us to create an evolving structure from the start.</li><li><strong>The Value of Automation</strong>: Integrating publication into our CI/CD pipeline significantly reduced human errors and accelerated our deployment process.</li><li><strong>Knowledge is Power</strong>: Keeping all teams informed of changes in the Design System was crucial for successful adoption.</li><li><strong>Release Early, Release Often, and Listen to Your Customer</strong>: A Design System is never really “finished”. It must evolve with the company’s needs and customer feedback.</li></ul><h3>Conclusion</h3><p>Publishing our Design System was an important milestone in Doctrine’s evolution. It allowed us to standardize our approach to frontend development, accelerate our development cycle, and ensure a consistent user experience across all our products.</p><p>This process took time, planning, and adjustments, but the benefits in terms of efficiency and consistency were well worth it. For companies considering a similar approach, we can only recommend taking the plunge, while keeping in mind that it’s an iterative process that improves with time and experience.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=5e3d54a22ef8" width="1" height="1" alt=""><hr><p><a href="https://medium.com/doctrine/how-we-published-our-design-system-a-journey-into-continuous-integration-5e3d54a22ef8">How We Published Our Design System: A Journey into Continuous Integration</a> was originally published in <a href="https://medium.com/doctrine">Inside Doctrine</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Enhancing Our Design System for Seamless Collaboration and Consistency]]></title>
            <link>https://medium.com/doctrine/enhancing-our-design-system-for-seamless-collaboration-and-consistency-23f3f47771b3?source=rss-f30c79c7f61------2</link>
            <guid isPermaLink="false">https://medium.com/p/23f3f47771b3</guid>
            <category><![CDATA[design-systems]]></category>
            <category><![CDATA[engineering]]></category>
            <category><![CDATA[process]]></category>
            <category><![CDATA[design]]></category>
            <dc:creator><![CDATA[Jérémie Uzan]]></dc:creator>
            <pubDate>Tue, 21 Nov 2023 17:52:34 GMT</pubDate>
            <atom:updated>2023-11-24T09:15:53.030Z</atom:updated>
            <content:encoded><![CDATA[<h3>I. Introduction &amp; Context</h3><p><em>Over the years, the idea of a design system has become very popular. It is essentially a collection of reusable components and directives that help create digital products. These systems are extremely important because they maintain consistency across different platforms and projects, while accelerating the development process as a whole.</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*XCirEOa5JSefz4qu.png" /><figcaption>Design system interest over time (Google)</figcaption></figure><p>When Doctrine was created in 2016, the design was driven by <strong>innovation and flexibility</strong> and the concept of components wasn’t really discussed.</p><p>In the following years, the industry standards showed that a design system brought too much rigidity, which led us to reflect more on our approach. During few years, we tried to implement components and reusability in the codebase but new designs were incompatible with the consistency that we wanted to implement.</p><p>It was later in 2020, facing an increasing number of designers and developers arriving at Doctrine, that we began to understand the importance of <strong>creating a design system</strong>.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*Uh1_jkvL_IjESsgp.png" /><figcaption>Image of a components that can be a part of a design system</figcaption></figure><p>When I joined Doctrine in 2022, we faced real challenges with our design system. One of the major issues was that the code components and design components did not integrate well. Our product had evolved over time, which led to a <strong>lack of consistency </strong>in the appearance and functioning of elements.</p><p>We faced challenges in our project due to the lack of a consistent and widely understood language between designers and developers when discussing design and development. This shared vocabulary, known as ubiquitous language, refers to a set of clear and unambiguous terms that are understood by all members and stakeholders of a product team. In our case, the terminology used was confusing and unclear, leading to frequent misunderstandings and significantly slowing down the entire process.</p><p>But we didn’t just sit around and complain about these problems. We took action to improve our design system and overcome these challenges. Today, we have adopted a governance model that emphasizes distributed responsibility, allowing for both freedom and individual accountability within our design system efforts.</p><h3>II. Audit the system components</h3><p>During this audit, we considered a bunch of factors like whether a component could be reused, if it matched the overall design language, and if it fit our product’s requirements. If a component didn’t meet these criteria or wasn’t needed anymore, we made the decision to either <em>get rid of it completely or make changes to adapt it to the system.</em></p><p>We also realized how important it was to align our design system with the design files we created in Figma, a design collaboration tool. We wanted the components in our codebase to have the same names as their counterparts in Figma. This way, designers and developers could speak the same language and understand each other better. <strong>It really helped bridge the gap between our teams and improved communication and collaboration.</strong></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*Sdjk4VVA0eFQimjE.png" /><figcaption>Buttons that we have in our design system at Doctrine</figcaption></figure><p>During the audit process, we also found some opportunities to optimize our component library. We noticed that there were similar components that could be merged together, which <strong>reduced duplication</strong> and made the system more <strong>streamlined</strong>. This not only made our development process easier but also created a more consistent and cohesive user experience.</p><p>By thoroughly auditing our system components, we were able to identify areas for improvement and lay a solid foundation for a stronger and more unified design system. This initial step set the stage for further enhancements in our design and development processes, <strong>making our team more efficient and fostering better collaboration.</strong></p><p>This audit was lengthy because we had a large number of components, including some that were not system components. However, after putting in effort and time, we ultimately completed the audit.</p><h3>III. Exploring Collaboration and Governance</h3><p>The audit we conducted was satisfactory, but we wanted to establish a process that would consistently keep our system components synchronized in the future. This led to the topic of collaboration between designers and developers, which quickly evolved with the introduction of communication channels on Slack. This facilitated ongoing feedback and alignment on design system updates, ensuring that both designers and developers were in sync.</p><p>We still have progress to make, especially in terms of<strong> the governance and management of this design system</strong>. While implementing rules and processes may initially seem like a burdensome task, it is absolutely necessary to ensure the long-term maintainability and sustainability of this system. By doing so, we can effectively address any potential challenges that may arise in the future.</p><blockquote>What are the next steps ?</blockquote><ul><li><strong>Document the design system:</strong> It’s important to have a detailed and comprehensive documentation of the design system. Tools like Storybook can help us create interactive and visually appealing documentation.</li><li><strong>Expose the design system on a private registry:</strong> To make the design system easily accessible to the team, we should consider making it available on a private registry. This will ensure that all team members can access the latest version of the design system.</li><li><strong>Implement a versioning system:</strong> To maintain control and track changes, it’s important to establish a versioning system for the design system. This will help us keep track of updates, bug fixes, and improvements over time.</li><li><strong>Deploy the design system:</strong> Once the design system is properly documented and versioned, we need to establish a reliable deployment process. This will ensure that the design system is easily available and can be integrated into our projects.</li></ul><blockquote>Who is responsible for this work ?</blockquote><p>Currently, we do not have a dedicated team solely responsible for the maintenance and upkeep of our design system. Hence, it becomes the <strong>collective responsibility of all team members</strong> to ensure the well-being and success of the system.</p><blockquote>Should we expose it in an external library ?</blockquote><p>While the idea of creating an external library for the design system might sound appealing, it is important to consider the potential difficulties and costs associated with it. Moreover, since our <strong>web app is currently the only consumer</strong> of the design system, there may not be significant immediate benefits to separating the code. However, we are actively working towards abstracting our components and making them as reusable as possible, in anticipation of future projects where the benefits of a separate library may become more apparent.</p><h3>Conclusion</h3><p>In conclusion, our path to creating a better design system at Doctrine has been about learning and adapting. Initially, we may not have fully grasped the significance of design systems, but as time went on, we recognized their crucial role in ensuring consistency and efficiency across our digital products. Additionally, we have continuously challenged the status quo, as it is one of our core values, in order to build a cohesive design system.</p><p>Looking ahead, we understand that effectively managing and maintaining our design system is crucial for its long-term success. Though it may seem like a daunting task, it is essential for ensuring the usability and sustainability of our system. This proactive approach will enable us to reduce time to market and swiftly release new features. With this mindset, we can confidently tackle future challenges.</p><p>We believe that all teams, including full-stack developers and designers, should share responsibility for this initiative. Therefore, everyone is encouraged to contribute and create new system components after discussing them with the team.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=23f3f47771b3" width="1" height="1" alt=""><hr><p><a href="https://medium.com/doctrine/enhancing-our-design-system-for-seamless-collaboration-and-consistency-23f3f47771b3">Enhancing Our Design System for Seamless Collaboration and Consistency</a> was originally published in <a href="https://medium.com/doctrine">Inside Doctrine</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
    </channel>
</rss>