unholy-design-tokens 1.0.0

package/.github/workflows/lint-format-build.yml

@@ -0,0 +1,35 @@
+name: Lint Format Build
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+# https://zellwk.com/blog/github-actions-deploy/
+jobs:
+  lint-format-build:
+    if: ${{ ! startsWith(github.event.pull_request.head.ref, 'renovate/') }}
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+
+      - name: Setup Node.js and pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Install dependencies
+        run: pnpm install --no-frozen-lockfile
+
+      - name: Lint
+        run: pnpm lint
+
+      - name: Format
+        if: ${{ always() }}
+        run: pnpm format
+
+      # - name: Build
+      #   if: ${{ always() }}
+      #   run: pnpm build

package/.github/workflows/publish_release.yml

@@ -0,0 +1,18 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  ci:
+    uses: arthur-plazanet/github-actions-kit/.github/workflows/reusable_release_publish.yml@main
+    # with:
+    # node-version: '20'
+    # publish: true
+    secrets:
+      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+    permissions:
+      contents: write # create releases/tags
+      id-token: write # npm provenance (OIDC)

package/.prettierrc

@@ -0,0 +1,9 @@
+{
+  "semi": false,
+  "tabWidth": 2,
+  "printWidth": 100,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "bracketSpacing": true,
+  "plugins": ["prettier-plugin-organize-imports"]
+}

package/ANALOGY_HOUSE.md

@@ -0,0 +1,139 @@
+# Analogy - 🏠 Building a House, and how the abstraction works
+
+Imagine that you want to build a house yourself, starting from the foundation up to the roof.
+
+## Step 1 — You make a decision on which materials to use
+
+You probably don't want to build your new house with not recognized materials.
+You start by knowing and choosing the _**raw materials**_ you will use, which can be:
+
+- 🪵 Wood
+- 🧱 Bricks
+- 🪨 Concrete
+- 🔩 Metal
+- 🪟 Glass
+
+---
+
+These are the basic ingredients of your house.
+While having them is technically enough to start building your house, but it's not very practical:
+
+- Every time you will need a wall, you will have to recalculate:
+
+  - how many bricks
+  - how much cement
+  - what thickness
+  - which type of reinforcement
+
+- Nothing is standardized or reusable
+- The house can be inconsistent
+- If someone else joins the project later, you will need to explain EVERYTHING from scratch.
+
+- If at some point you want to expand your house and involve other people, every new builder has to relearn everything
+
+## 🧱 Step 2 — You create building parts to go faster
+
+Instead of redefining everything every time, you create reusable parts:
+
+- 🟫 Some standard walls
+- 🚪 Standard doors
+- 🪟 Standard windows
+
+They allow you to be faster, and you don't have to worry about the raw materials anymore.
+
+Instead of thinking:
+
+> "How many bricks and cement do I need to build this wall?"
+
+You now think:
+
+> "I need this specific wall"
+
+These parts are reusable, consistent, and easier to understand.
+
+## 🚪 Step 3 — You want to create rooms with purpose
+
+Now that you have standard parts, you want to create rooms with specific purposes:
+
+- 🛏 bedroom (place to sleep)
+- 🍳 kitchen (place to cook)
+- 🚿 bathroom (place to wash)
+- 💼 office (place to work)
+
+All of these rooms are made of parts you defined earlier (walls, doors, windows, roofs), but they have a specific purpose.
+
+When you think about building a bedroom, you don't think
+
+> 4 blue walls, 1 red doors
+
+you think about
+
+> "a place to sleep".
+
+## 🛋️ Step 4 — People live inside (Components)
+
+Furniture, people, behavior — all of this sits on top of rooms.
+
+No one sleeping in the bedroom wonders:
+
+- “Is this wall brick or concrete?”
+
+- “What thickness is the insulation?”
+
+- “What type of screws did they use?”
+
+They only care that it's a bedroom, and it serves its purpose.
+They can then add furniture, decorate it, and use it as intended, according to the room's purpose.
+
+## What if you want to change something?
+
+When a house is finished, and you want to apport changes, you usually not:
+
+- Directly change raw materials
+- Rebuild rooms from scratch or change their purpose
+
+What you do is updating what is directly visible:
+
+- Change the paint color of the walls
+- Change the type of furniture
+- Swap a door for a bigger one
+- Add more windows for more light
+  etc.
+
+These pieces define the style, look and feel of the house without changing its fundamental structure, or the purpose of each room.
+
+So if you want:
+
+a modern house → update colors, finishes, fixtures
+
+a cozy house → use warm tones, wooden textures
+
+a minimalist house → simplify surfaces and spacing
+
+All these changes happen in the layer that controls the appearance,
+not in the foundation, not in the room layout,
+and not in the purpose of the spaces.
+
+It's the part that's meant to be changed later
+while everything else stays stable.
+
+- **Parts with purpose**: Is
+- **Abstraction layers**: Each step represents a layer of abstraction, from raw materials to functional spaces. This mirrors how design tokens abstract raw values into meaningful components.
+
+## 🪜 The abstraction protects the user
+
+Just like:
+
+Components don’t care about RGB values
+
+Developers don’t care about the exact blue hex
+
+Designers don’t want to debate spacing values every time
+
+The abstraction protects the user.
+
+- How to screw a simple door
+- Fix some wall together (which material is it even?)
+- or how to properly install and even isolate a window
+
+But for example, you don't need to know the raw material that was used to create the door,; neither

package/ANALOGY_I18NEXT.md

@@ -0,0 +1,160 @@
+# i18next analogy with Design Tokens
+
+## Hard-coded-string: the "old way”
+
+Before having translation tools, you hard-code strings directly in components:
+
+```tsx
+// React, Vue, whatever
+<Alert type="success">Profile updated successfully!</Alert>
+```
+
+Strings are hard-coded:
+
+- Not reusable
+- Not translatable
+- Not themeable per language/brand/product
+
+So you introduce **i18next**.
+
+---
+
+## Layer 1 – Translation resources (raw data)
+
+You define your resources:
+
+```tsx
+// en/translation.json
+{
+  "profile": {
+    "updated": "Profile updated successfully!"
+  },
+  "errors": {
+    "network": "Something went wrong. Please try again."
+  }
+}
+
+```
+
+```tsx
+// fr/translation.json
+{
+  "profile": {
+    "updated": "Profil mis à jour avec succès !"
+  },
+  "errors": {
+    "network": "Une erreur est survenue. Veuillez réessayer."
+  }
+}
+
+```
+
+This is just **structured data**:
+
+- One language per file
+- Raw strings
+- No component logic
+
+Think of it as **your translation “database”**, nothing more.
+
+---
+
+## Layer 2 – Meaningful keys & namespaces
+
+Then you start organizing things:
+
+```tsx
+// common.json
+{
+  "actions": {
+    "save": "Save",
+    "cancel": "Cancel"
+  },
+  "status": {
+    "success": "Success",
+    "error": "Error"
+  }
+}
+
+// profile.json
+{
+  "messages": {
+    "updated": "Profile updated successfully!"
+  }
+}
+
+```
+
+You now have:
+
+- **Namespaces**: `common`, `profile`, `errors`
+- **Meaningful keys**: `actions.save`, `status.success`, `messages.updated`
+
+Developers don’t write “Sauvegarder” or “Speichern” —
+
+they write:
+
+```tsx
+t('common.actions.save');
+t('profile.messages.updated');
+```
+
+You’ve created a **semantic layer** of _meaningful keys_ above raw strings.
+
+---
+
+## Layer 3 – Component usage / intent
+
+Now imagine an `Alert`:
+
+```tsx
+function Alert({ intent }: { intent: 'success' | 'error' | 'warning' }) {
+  const { t } = useTranslation('common');
+
+  const titleKey = {
+    success: 'status.success',
+    error: 'status.error',
+    warning: 'status.warning',
+  }[intent];
+
+  return (
+    <div className={`alert alert--${intent}`}>
+      <strong>{t(titleKey)}</strong>
+      {/* ... */}
+    </div>
+  );
+}
+```
+
+From the component’s perspective:
+
+- It doesn’t know the language
+- It doesn’t know the string content
+- It only knows **“I am an alert with `intent='success'`”**
+
+And that **intent** is mapped to a key like `status.success`,
+
+which resolves, via resources, to the actual text.
+
+---
+
+## 🧩 Put it all together
+
+We essentially have:
+
+1. **Raw translations (resources)**
+   - JSON per language
+   - Strings only
+2. **Meaningful keys / namespaces**
+   - `common.actions.save`
+   - `status.success`
+   - `profile.messages.updated`
+3. **Component-facing API (intent / usage)**
+   - Components call `t(key)`
+   - Or even higher-level things like `getAlertCopy('success')`
+
+No one doing UI work should touch the raw strings directly anymore.
+
+They work with **keys and intent**.
+
+> resources = raw values, keys = semantic meaning, `t()` calls = component intent.

package/LICENSE

@@ -0,0 +1,201 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction,
+and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by
+the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all
+other entities that control, are controlled by, or are under common
+control with that entity. For the purposes of this definition,
+"control" means (i) the power, direct or indirect, to cause the
+direction or management of such entity, whether by contract or
+otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity
+exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation
+source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical
+transformation or translation of a Source form, including but
+not limited to compiled object code, generated documentation,
+and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or
+Object form, made available under the License, as indicated by a
+copyright notice that is included in or attached to the work
+(an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object
+form, that is based on (or derived from) the Work and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship. For the purposes
+of this License, Derivative Works shall not include works that remain
+separable from, or merely link (or bind by name) to the interfaces of,
+the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including
+the original version of the Work and any modifications or additions
+to that Work or Derivative Works thereof, that is intentionally
+submitted to Licensor for inclusion in the Work by the copyright owner
+or by an individual or Legal Entity authorized to submit on behalf of
+the copyright owner. For the purposes of this definition, "submitted"
+means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems,
+and issue tracking systems that are managed by, or on behalf of, the
+Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity
+on behalf of whom a Contribution has been received by Licensor and
+subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the
+Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+(except as stated in this section) patent license to make, have made,
+use, offer to sell, sell, import, and otherwise transfer the Work,
+where such license applies only to those patent claims licensable
+by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s)
+with the Work to which such Contribution(s) was submitted. If You
+institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work
+or a Contribution incorporated within the Work constitutes direct
+or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate
+as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+Work or Derivative Works thereof in any medium, with or without
+modifications, and in Source or Object form, provided that You
+meet the following conditions:
+
+(a) You must give any other recipients of the Work or
+Derivative Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices
+stating that You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works
+that You distribute, all copyright, patent, trademark, and
+attribution notices from the Source form of the Work,
+excluding those notices that do not pertain to any part of
+the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its
+distribution, then any Derivative Works that You distribute must
+include a readable copy of the attribution notices contained
+within such NOTICE file, excluding those notices that do not
+pertain to any part of the Derivative Works, in at least one
+of the following places: within a NOTICE text file distributed
+as part of the Derivative Works; within the Source form or
+documentation, if provided along with the Derivative Works; or,
+within a display generated by the Derivative Works, if and
+wherever such third-party notices normally appear. The contents
+of the NOTICE file are for informational purposes only and
+do not modify the License. You may add Your own attribution
+notices within Derivative Works that You distribute, alongside
+or as an addendum to the NOTICE text from the Work, provided
+that such additional attribution notices cannot be construed
+as modifying the License.
+
+You may add Your own copyright statement to Your modifications and
+may provide additional or different license terms and conditions
+for use, reproduction, or distribution of Your modifications, or
+for any such Derivative Works as a whole, provided Your use,
+reproduction, and distribution of the Work otherwise complies with
+the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+any Contribution intentionally submitted for inclusion in the Work
+by You to the Licensor shall be under the terms and conditions of
+this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify
+the terms of any separate license agreement you may have executed
+with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+names, trademarks, service marks, or product names of the Licensor,
+except as required for reasonable and customary use in describing the
+origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+agreed to in writing, Licensor provides the Work (and each
+Contributor provides its Contributions) on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied, including, without limitation, any warranties or conditions
+of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any
+risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+whether in tort (including negligence), contract, or otherwise,
+unless required by applicable law (such as deliberate and grossly
+negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special,
+incidental, or consequential damages of any character arising as a
+result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill,
+work stoppage, computer failure or malfunction, or any and all
+other commercial damages or losses), even if such Contributor
+has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+the Work or Derivative Works thereof, You may choose to offer,
+and charge a fee for, acceptance of support, warranty, indemnity,
+or other liability obligations and/or rights consistent with this
+License. However, in accepting such obligations, You may act only
+on Your own behalf and on Your sole responsibility, not on behalf
+of any other Contributor, and only if You agree to indemnify,
+defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason
+of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following
+boilerplate notice, with the fields enclosed by brackets "{}"
+replaced with your own identifying information. (Don't include
+the brackets!)  The text should be enclosed in the appropriate
+comment syntax for the file format. We also recommend that a
+file or class name and description of purpose be included on the
+same "printed page" as the copyright notice for easier
+identification within third-party archives.
+
+Copyright 2017 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,90 @@
+# 🗿 Unholy Design Tokens - A Practical Guide to Design Tokens (Without the Fluff)
+
+<img width="2550" height="920" alt="MacBook Pro 16_ - 6" src="https://github.com/user-attachments/assets/03a1b857-0881-4ad9-b14e-4480b5e181ad" />
+
+See [Figma](https://www.figma.com/design/ALxCJnoWLP4kBiYr59tHqG/useSimpleDesignTokens?node-id=1-5537&t=perH3yNxowfIDyWu-1)
+
+_A brutally clear, developer-friendly design token system using Style Dictionary._
+
+This project is a playground to try to simplify the concept of design tokens and provide a practical framework for implementing and customize them using Style Dictionary.
+
+## 🏠 Understanding Design Tokens through a House
+
+To represent the concept of design tokens, you can use the following analogies:
+
+→ [**House-Building Analogy** (practical approach)](ANALOGY_HOUSE.md)
+
+---
+
+## Goals:
+
+- Avoid abstraction and provide a short and practical definition of design tokens.
+- Propose a clear structure for organizing design tokens.
+- Clarify **_who owns what_** between **Designers** and **Developers** regarding token levels
+
+---
+
+## 📁 Repository Structure
+
+```graphql
+/
+├─ README.md                ← you're here
+├─ ANALOGY_HOUSE.md         ← build a house analogy for design tokens
+├─ ANALOGY_I18NEXT.md       ← analogy applied to translations
+├─ WHY_THIS_EXISTS.md       ← motivation behind the repo
+│
+└─ src/
+    └─ tokens/
+        ├─ README.md                    ← token system overview
+        ├─ 1-primitives/                ← raw values (colors, spacing…)
+        ├─ 2-semantic/                  ← meaningful roles
+        ├─ 3-intent/                    ← purpose/state
+        ├─ 4-cube/                      ← layout primitives
+        └─ component/                   ← per-component token mapping
+
+```
+
+## 🗂 Token source
+
+Tokens live here:  
+👉 [`src/tokens`](./src/tokens)
+
+---
+
+## 📘 Explanations
+
+- ❓ Why this repo exists → [`WHY_THIS_EXISTS.md`](WHY_THIS_EXISTS.md)
+- ⚙️ Style Dictionary pipeline → [`STYLE_DICTIONARY.md`](STYLE_DICTIONARY.md)
+- i18n analogy → [`ANALOGY_I18NEXT.md`](ANALOGY_I18NEXT.md)
+- 🏠 House-building analogy → [`ANALOGY_HOUSE.md`](ANALOGY_HOUSE.md)
+
+---
+
+## Use the package
+
+### A) Local dev (TS, no install)
+
+```bash
+pnpm exec tsx bin/build-tokens.ts ../../lib
+
+```
+
+### B) Local project (compiled CLI)
+
+```bash
+pnpm exec build-tokens ../../lib
+
+```
+
+### C) As a dependency in another repo
+
+```bash
+pnpm add style-dictionary-example-complete
+pnpm exec build-tokens ./tokens
+```
+
+### D) One-off usage
+
+```bash
+npx style-dictionary-example-complete ./tokens
+```