@geonosis/themekit 1.0.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 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 [yyyy] [name of copyright owner]
+
+   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,226 @@
+# `@geonosis/themekit`
+
+The tokens contract, a variable map that is data, and DTCG in and out. **Themes are files; the
+components are yours** (D-010) — nothing here renders, and nothing here is React.
+
+Extracted from dielime's `packages/ui/src/theme/{contract,define-theme}.ts`, measured first in
+[`docs/themekit-inventory-2026-08-30.md`](../../docs/themekit-inventory-2026-08-30.md). Zero runtime
+dependencies.
+
+## The gate this package is held to
+
+`src/byte-identity.test.ts` runs **dielime's own compiler on dielime's own storefront theme**, both
+copied verbatim into `src/__fixtures__`, and requires the kit's output to match it variable for
+variable, value for value, **in order** — 36 custom properties, three of them derived
+`color-mix()` strings, two of them camelCase escape-hatch keys.
+
+Not a recorded snapshot. A snapshot proves the kit still agrees with itself; this proves it agrees
+with the implementation it replaces, and it goes red the day the two diverge.
+
+## The three inputs
+
+```ts
+import { compile, defineTheme } from '@geonosis/themekit'
+
+const theme = defineTheme({
+  id: 'die-lime',
+  name: 'dielime',
+  colors: { primary: 'oklch(0.91 0.17 102)', onPrimary: 'oklch(0.22 0.02 140)', /* … */ },
+  fonts: { body: "'Millrope', Helvetica, Arial, sans-serif", display: "'Bluungezi', Georgia, serif" },
+  radii: { none: '0px', sm: '4px', md: '8px', lg: '16px', full: '9999px' },
+  shadows: { level1: '0 1px 5px rgb(0 0 0 / 0.12)' },
+  extra: { limeWilt: 'linear-gradient(100deg, …)' },
+})
+```
+
+1. **The theme** — the values. Colour roles are a named set (they are design-system vocabulary, not
+   any repo's); `fonts`, `radii` and `shadows` are open maps, because font roles are data and
+   during.day has no radii at all. Anything the contract does not model goes in `extra`.
+2. **The emission map** — *which* custom properties those values compile to, in what order. This is
+   the part that is one repo's stylesheet, so it is data and never a default (law 6):
+
+   ```ts
+   compile(theme, {
+     emit: [
+       { role: 'colors.primary', variable: '--mc-primary' },
+       { mix: { role: 'colors.primary', amount: '85%', with: '#000000' }, variable: '--mc-primary-hover' },
+       { each: 'extra', prefix: '--mc-' },
+     ],
+   })
+   ```
+
+   Three entry kinds: `role` copies a value, `mix` writes
+   `color-mix(in <space>, <value> <amount>, <with>)`, `each` writes one variable per key of an open
+   map, **verbatim** — `--mc-limeWilt` stays camelCase, because it is what the stylesheet already
+   ships is reading.
+
+   Two behaviours that look like details and are not: an emission whose role resolves to nothing is
+   **skipped** (that is how `--accent` stays conditional, with no special case — and why nothing
+   ever emits `--accent: ;`), and a later entry naming an earlier variable replaces its **value**
+   while keeping its **position** (that is how `extra` overrides a derived colour).
+
+   `defaultEmission('--theme-')` is what a repo that has declared nothing gets: one variable per
+   role, complete, and nobody's house style.
+3. **The `themeBlock` namer** — Tailwind v4 has no config file, so a utility exists because a
+   variable exists. Hand it a function and it generates the `@theme inline` block from the same
+   emission list, so a variable can never be mapped that was never written.
+
+## The four outputs
+
+| | what it is | who reads it |
+|---|---|---|
+| `cssVariables` | `Record<'--…', string>`, in emission order | spread straight into a `style` prop |
+| `css` | `<selector> { … }`, default `:root` | a stylesheet, a `<style>` tag |
+| `themeBlock` | `@theme inline { --color-…: var(--…); }` | Tailwind v4 |
+| `plain` | role path → value: `plain['colors.primary']` | react-email inline styles, `<svg fill>`, canvas |
+| `object` | the theme, unchanged | a switcher, a logo lookup |
+
+`plain` is keyed by **role**, not by variable, on purpose: a mail client that drops `var()` needs
+the value, and which variable a repo calls it by is not its business. It also carries roles no
+variable was emitted for — dielime's map emits nothing for `success` or `warning`, and an email that
+wants the success green must still be able to ask.
+
+## DTCG, and the one place this deviates
+
+`toDtcg(theme)` and `fromDtcg(document)`. Groups, `$value`, `$type`, `$extensions` — the Design
+Tokens Community Group draft, with **one deliberate deviation**: `$value` is the **CSS string,
+exactly as authored**, where the draft wants an object.
+
+The draft types a colour as `{ colorSpace, components }`, a dimension as `{ value, unit }`, a shadow
+as five named fields. Three kinds of real value cannot become those objects at all:
+
+- `var(--mc-gray-c)` has no colour space — and a DTCG `{alias}` is not a substitute, because an
+  alias resolves inside the file while `var()` resolves in the browser, and that late binding is the
+  whole point of a palette layer;
+- `color-mix(in srgb, … 85%, #000000)` is a computation, not a colour;
+- `0 1px 5px rgb(0 0 0 / 0.12)` is a *spelling* — parse it into five fields, print it back, and you
+  have the same colour and different bytes.
+
+Different bytes is the whole problem: the gate on this extraction is that a consumer's stylesheet is
+unchanged afterwards, so a format that re-spells a value on the way through is not an interchange,
+it is a rewrite.
+
+So the deviation is **declared and measured**, never assumed:
+
+```ts
+validateDtcg(document)                    // is it this profile? errors + `lossy`
+validateDtcg(document, { strict: true })  // which values could the DRAFT not hold?
+```
+
+`strict` names them one by one — the extension the draft would need, per token, instead of a
+paragraph in a README nobody diffs. `lossy` names what a round trip through the contract would drop
+(today: `$description`, which the contract has nowhere to put), so nothing evaporates quietly.
+
+Two laws hold and are tested: `toDtcg(fromDtcg(x))` is `x`, and a theme that has been through
+`JSON.parse(JSON.stringify(toDtcg(…)))` still compiles byte-identically. Brand identity (`id`,
+`name`) rides in the root group's `$extensions` under `com.microcompanies.geonosis`, because it is
+metadata with no `$value` — a logo, likewise, belongs in `brand.json` beside the tokens and not in
+the token file.
+
+## The registry
+
+```ts
+import { compile, loadThemekit } from '@geonosis/themekit'
+
+const kit = loadThemekit('themekits/dielime', { pinned: '1.0.0' })
+const { css } = compile(kit.theme, { emit: kit.emit, selector: `[data-brand="${kit.brand.id}"]` })
+```
+
+A themekit is a **directory** — `themekit.json` (name, version, `complete`, which map to compile
+through), `theme.tokens.json`, `brand.json`, `CHANGELOG.md`. This package ships none of them
+(`files: ["dist"]`), so installing a tokens compiler never installs somebody else's palette; see
+[`themekits/`](../../themekits/README.md) for why that follows from D-010, D-026 and D-027.
+
+`{ pinned }` is what makes a bump **invisible until the consumer moves the pin**: a directory whose
+version has moved is refused, naming both. A pin nobody checks is a comment.
+
+`loadThemekit` validates and refuses; it never repairs. It stops on a directory that is not a
+themekit, a manifest with no version, tokens that are not this profile (naming the token), a
+manifest that claims `complete` while a required role is empty, and a JSON file that will not parse
+— read as `{}`, that last one is a themekit that compiles to nothing and a page that renders
+unstyled with nothing in the log.
+
+An incomplete themekit is allowed and is reported: `missingRoles` names each required role the theme
+does not fill. `themekits/during-day` is one — two colour roles out of fourteen, because during.day
+styles the rest from Tailwind classes directly, and inventing its `primary` is the one thing a
+registry must never do.
+
+## Figma variables in
+
+```ts
+import { fromFigmaVariables } from '@geonosis/themekit'
+
+const { themes, unmapped, unsupported } = fromFigmaVariables(payload, {
+  map: { 'color/primary': 'colors.primary', 'radius/md': 'radii.md' },
+  floatUnit: 'px',
+})
+```
+
+Over the shape `GET /v1/files/:key/variables/local` documents. **Modes become themes**: a file's
+`Semantic` collection with Light and Dark yields two DTCG documents, each of which validates and
+compiles. Pulling the payload is your step — this package makes no network calls.
+
+**Aliases are resolved**, which is most of the work. A real Figma file is a `Primitives` collection
+nobody themes and a `Semantic` one whose every variable aliases into it; an importer that did not
+follow those would write `VariableID:1` where a colour goes and — worse — every mode would come out
+identical, because an id does not change per mode. The chain is followed in the mode being imported,
+falling back to a collection's own default when it does not have that mode (`Primitives` has never
+heard of `Dark`), and a cycle is reported rather than run.
+
+**Nothing is dropped quietly.** `map` is the designer's vocabulary meeting the repo's, and it is
+data you pass (law 6). A variable nobody mapped goes into `extra` and is listed in `unmapped`. A
+variable that cannot become a token at all is listed in `unsupported`, with the reason:
+
+- a `BOOLEAN` is not a design token;
+- a `FLOAT` carries **no unit** — Figma has `8` and nothing anywhere says px or rem. Guessing px is
+  right most of the time and produces, the rest of the time, a layout nobody can trace to an import.
+  Pass `floatUnit` and it imports;
+- a `STRING` mapped where a colour goes, named with the variable rather than surfacing later as an
+  anonymous validation error.
+
+## The migration, for a repo that has a theme object already
+
+```ts
+const asTheme = (brand: BrandTheme): Theme => ({
+  ...brand,
+  fonts: { ...brand.fonts },
+  radii: { ...brand.radii },
+  shadows: { ...brand.shadows },
+})
+```
+
+That is all of it, and the spreads are not ceremony: this contract widened those three to open maps,
+and TypeScript will not let an `interface` stand in for a `Record<string, string>` — an interface can
+be augmented later, so it carries no implicit index signature. Spreading copies strings, so the
+compiled output does not move.
+
+## Adoption status — **NOT adopted** (D-027)
+
+A package is DONE when every consumer depends on the published version and has deleted its copy.
+Neither has, yet:
+
+| consumer | today | the five-line migration |
+|---|---|---|
+| **dielime** | ships `packages/ui/src/theme/{contract,define-theme}.ts` (294 lines) | (1) depend on `@geonosis/themekit`; (2) `const asTheme = (b: BrandTheme): Theme => ({ ...b, fonts: { ...b.fonts }, radii: { ...b.radii }, shadows: { ...b.shadows } })`; (3) `const kit = loadThemekit('themekits/dielime', { pinned: '1.0.0' })`; (4) `themeToCssVars(t)` → `compile(asTheme(t), { emit: kit.emit }).cssVariables`; (5) delete `contract.ts` and `define-theme.ts`, keep `provider.tsx` — it is React and stays. `styles.css` is untouched. |
+| **during.day** | no theme object at all; three CSS variables and a light/dark class | (1) depend on `@geonosis/themekit`; (2) `const kit = loadThemekit('themekits/during-day')`; (3) read `kit.missingRoles` — twelve, and they are honest; (4) `compile(kit.theme, { emit: defaultEmission('--color-') })` for the light mode; (5) nothing to delete. The two dark themes wait on a mode axis the contract does not have. |
+
+The byte-identity evidence for step (4) is [`proofs/022-W6-byte-identity`](../../proofs/022-W6-byte-identity/README.md);
+what the two conformance rules find in each tree, read-only, is
+[`proofs/022-W6-consumers`](../../proofs/022-W6-consumers/README.md).
+
+## What is deliberately not here
+
+- **No components, no React, no provider.** D-010: the factory stores themes and the contract, never
+  components. A provider is 70 lines a consumer writes against its own framework.
+- **No browser and no capture.** Per-theme visual baselines are `@geonosis/visual-diff`'s job, and
+  what to capture is yours. The recipe — one baseline per `<surface>@<brand>` per breakpoint, at
+  `threshold: 0`, with the compiled CSS injected rather than re-implemented — is in
+  [`docs/themekit-visual-and-switcher.md`](../../docs/themekit-visual-and-switcher.md), together
+  with the three non-obvious parts of a Storybook switcher (the portal/`document.body` mirror above
+  all).
+- **No brand names, no token names, no font roles as defaults.** They are data in
+  `themekits/<brand>/` or options. The default emission map is deliberately generic and deliberately
+  not dielime's.
+- **No dependencies.** The moment this package grew a colour library to parse `oklch()`, it would
+  also grow that library's opinion about how to print one back — the byte-identity gate lost to a
+  transitive dependency.