{
  "$type": "site.standard.document",
  "canonicalUrl": "https://trysound.io/building-design-tokens-app",
  "description": "A story of how I started building Engramma, a design tokens app, to learn modern design systems and token-based workflows.",
  "path": "/building-design-tokens-app",
  "publishedAt": "2025-12-09T00:00:00.000Z",
  "site": "at://did:plc:ookzzzg4hc3mxf44jkocwiep/site.standard.publication/3mmgno6gxmw2z",
  "textContent": "Working on a large project requires a systematic design approach to keep the\nuser interface consistent. Often, this system is implemented as a set of\npre-styled components or UI kits.\n\nThe smallest piece of a design system is a token: a color, size, or typography\nconfiguration reusable across different components. In UI kits, themes with\ndozens of values are similar to tokens. You can override a theme and have your\ncomponents updated. However, once a project matures, the theme may contain\nhundreds of values, and without a strong system, they become unmanageable.\n\nA few years ago, a community of designers and developers (Design Tokens\nCommunity Group or DTCG) decided to formalize how design tokens are defined and\nexchanged across tools and platforms. Recently, they released\na stable design tokens format specification,\nwith strict types and more unified (less CSS-like) definitions.\n\nAnd I was very excited by how expressive it is compared to previous iterations\nand couldn't stop myself from creating an app around it. Especially since I have\na lot of experience building UI for web at Webstudio\nover the last three years and wanted to channel those ideas into something new.\n\nIt felt like a great opportunity to get better at design systems.\n\nPrototyping with Modern Tools\n\nUsing OpenCode for rapid prototyping and Svelte as a lightweight framework\n(already worked with it), I made a simple two-pane UI: a tokens tree on the left\nand generated CSS variables on the right. AI helps a ton with moving forward\nfrom \"blank pages\".\n\n!Early Engramma design tokens editor prototype UI\n\nTokens tree on the left is custom-built. I relied heavily on the\nWAI-ARIA recommendations\nand on Adam Argyle's advice to always support multi-select, based on his\nexperience working on VisBug. Multi-select can be\nuseful for bulk deleting or moving items into another folder with fewer\nrepetitive actions.\n\nWhile I was working on the prototype, Adam Argyle released a great new\ncolor picker with all modern\ncolor spaces like OKLCH, LAB etc. supported in CSS. By the way, the design\ntokens specification relies on those exact color spaces for color tokens.\nPerfect timing.\n\nBesides picking colors, I still needed a way to parse them and convert them to\nthe DTCG color format, so I needed a solid library to avoid getting lost in\ncolor specifications. color-input uses the super cool\ncolorjs.io library. I've been hearing about it for years\nbut never found it before, because I was spelling it wrong when searching :)\n\n!CSS color component picker showing modern color spaces\n\nFor UI components, I decided to go with HTML. Yeah, it got a lot of good stuff\nrecently.\n\n- Popover API for the app menu, adding tokens, and the token editor\n- The dialog element for \"About\" info\n- Invokers for declarative opening of dialogs and popovers\n- Will definitely use interest invokers for tooltips\n\nThese are very easy to polyfill, except for anchor positioning, but I worked\naround that with a custom\nfloating-ui setup.\n\nVisualizing design tokens\n\nNow we have a token editor and a CSS/JSON preview. That's useful for coding, but\nnot for visual exploration.\n\nWhat would be more helpful is an automatically generated style guide based on\ndesign tokens. All these values could be rendered as widgets and placed on a\nsingle page for designers to browse.\n\nThere's still room for improvement, though I already like the progress.\nEspecially happy with the cubic-bezier preview, planning to reuse it for a\nbezier editor later.\n\n!Generated style guide preview based on design tokens\n\nWhat about AI? Can design tokens improve the results of generated websites and\napplications? Experience shows that the more specific your question is, the\nbetter the results you get. Design tokens could help a lot with this, and it may\nbe interesting to explore later.\n\nDesign tokens architecture\n\nWhile researching I read a ton about design systems, especially recommend\nBrad Frost's book and articles. That's where I learned\nhow essential token aliasing is. One great concept is a 3-tier token\narchitecture which defines arbitrary, semantic, and component values, where each\nlayer maps to the next.\n\n- Tier 1 tokens define all available values in the design system, such as\n  color-blue-100 or color-white.\n- Tier 2 tokens map Tier 1 tokens to semantic roles in the UI, for example\n  text-color-primary or color-border-destructive.\n- Tier 3 tokens are component-specific, such as button-bg-color or\n  heading-text-color.\n\nThis component-specific tier can be leveraged even further by rendering a\ncombination of these tokens as a component widget in Style Guide.\n\nThe design tokens specification offers a few options for this. One is the\ntoken reference\nsyntax (I use this one in the app), another uses\nJSON Schema Pointer\n(which I find trickier to represent in a UI).\n\nIntroducing...\n\nBy the way, I called this tool Engramma. I wanted an original name, so I\nborrowed it from one of my favorite games and used the Italian variant. You can\ncheck it out at engramma.dev.\n\nFrom the start, the project has been completely open source, and I'm posting\nprogress everywhere Reddit can't block me (yep, they're super unfriendly to new\nusers). You can check it out on GitHub.\n\nWhat's Next\n\nGonna keep improving the tool and start using it for new projects. Here are the\nclosest ideas to implement:\n\n- Themes and light/dark modes support based on \"Resolver\" specification that\n  extends the DTCG format with \"Sets\" and \"Modifiers\" to partially override\n  values while reusing others.\n- Synchronize tokens with project code\n- Explore integrations with external graphics editors and website builders\n\nIf you work with design systems, I'd love your feedback on Engramma – try it at\nengramma.dev, import your JSON with tokens, and tell me\nwhat's missing.\n\n!Engramma design tokens app interface with tokens and preview",
  "title": "Building design tokens app"
}