@cssdoc/dtcg 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Danny Wahl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,24 @@
+# @cssdoc/dtcg
+
+Export the declared custom properties as [W3C Design Tokens](https://tr.designtokens.org/) (DTCG). Each
+`@property` becomes a token with `$value` (its `initial-value`), `$type` (mapped from its `syntax`), and
+`$description`, grouped by the record that declares it — so properties that double as design tokens
+interchange with the token ecosystem.
+
+## Usage
+
+```ts
+import { createIndex } from "@cssdoc/index";
+import { writeDtcg } from "@cssdoc/dtcg";
+import { readFileSync } from "node:fs";
+
+const index = createIndex(readFileSync("dist/components.css", "utf8"));
+writeDtcg({ index, outFile: "tokens.json" });
+```
+
+Syntax → `$type` mapping: `<color>` → `color`, `<length>` → `dimension`, `<time>` → `duration`,
+`<number>`/`<integer>`/`<percentage>` → `number`. Unmapped syntaxes omit `$type`.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,22 @@
+import { CssDocIndex } from "@cssdoc/index";
+
+//#region src/index.d.ts
+/** A single DTCG token. */
+interface DtcgToken {
+  $value: string;
+  $type?: string;
+  $description?: string;
+}
+/** A DTCG token document: a group per record, each holding its custom-property tokens. */
+type DtcgDocument = Record<string, Record<string, DtcgToken>>;
+/** Build a DTCG token document from the index's declared custom properties. */
+declare function toDtcg(index: CssDocIndex): DtcgDocument;
+/** Write the DTCG document to `outFile` (defaults to `tokens.json`). */
+declare function writeDtcg(options: {
+  index: CssDocIndex;
+  outFile?: string;
+}): {
+  outFile: string;
+};
+//#endregion
+export { DtcgDocument, DtcgToken, toDtcg, writeDtcg };

package/dist/index.mjs

@@ -0,0 +1,52 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+//#region src/index.ts
+/**
+* `@cssdoc/dtcg` — export the declared custom properties as W3C Design Tokens (DTCG). Each `@property`
+* becomes a token with `$value` (its `initial-value`), `$type` (mapped from its `syntax`), and
+* `$description`, grouped by the record that declares it — so properties that double as design tokens
+* interchange with the token ecosystem.
+*
+* @module @cssdoc/dtcg
+*/
+/** Map a CSS `@property` syntax descriptor to a DTCG `$type`, when there's a clear correspondence. */
+const SYNTAX_TO_TYPE = {
+	"<color>": "color",
+	"<length>": "dimension",
+	"<length-percentage>": "dimension",
+	"<percentage>": "number",
+	"<number>": "number",
+	"<integer>": "number",
+	"<time>": "duration",
+	"<angle>": "number"
+};
+function dtcgType(syntax) {
+	return syntax ? SYNTAX_TO_TYPE[syntax.trim()] : void 0;
+}
+/** Build a DTCG token document from the index's declared custom properties. */
+function toDtcg(index) {
+	const root = {};
+	for (const entry of index.entries) {
+		if (!entry.cssPropertiesDeclared.length) continue;
+		const group = {};
+		for (const property of entry.cssPropertiesDeclared) {
+			const type = dtcgType(property.syntax);
+			group[property.name.replace(/^--/u, "")] = {
+				$value: property.defaultValue ?? "",
+				...type ? { $type: type } : {},
+				...property.description ? { $description: property.description } : {}
+			};
+		}
+		root[entry.name] = group;
+	}
+	return root;
+}
+/** Write the DTCG document to `outFile` (defaults to `tokens.json`). */
+function writeDtcg(options) {
+	const outFile = options.outFile ?? "tokens.json";
+	mkdirSync(dirname(outFile), { recursive: true });
+	writeFileSync(outFile, `${JSON.stringify(toDtcg(options.index), null, 2)}\n`);
+	return { outFile };
+}
+//#endregion
+export { toDtcg, writeDtcg };

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@cssdoc/dtcg",
+  "version": "0.1.0",
+  "description": "Export cssdoc custom properties as W3C Design Tokens (DTCG): $value, $type, $description.",
+  "keywords": [
+    "css",
+    "cssdoc",
+    "design-tokens",
+    "dtcg"
+  ],
+  "homepage": "https://cssdoc.dev",
+  "bugs": "https://github.com/thedannywahl/cssdoc/issues",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thedannywahl/cssdoc.git",
+    "directory": "generators/dtcg"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@cssdoc/core": "0.1.0",
+    "@cssdoc/index": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "publint": "^0.3.21",
+    "typescript": "^6.0.3",
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.2.4",
+    "vite-plus": "0.2.4"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "check": "vp check",
+    "publint": "publint"
+  }
+}