chore(docs): add design md file

.vale.ini

@@ -21,6 +21,9 @@ Elements.SummaryImplementation = NO
 [NOTICE.md]
 BasedOnStyles =
 
+[DESIGN.md]
+BasedOnStyles =
+
 [**/NOTICE.md]
 BasedOnStyles =
 

README.md

@@ -13,6 +13,7 @@ NVIDIA Design System and UI Agent Harness for AI/ML Factories, Robotics, and Aut
 - [Contribution Guidelines](https://NVIDIA.github.io/elements/docs/about/contributions/)
 - [Feature request](https://github.com/NVIDIA/elements/issues/new?issuable_template=feature)
 - [Bug report](https://github.com/NVIDIA/elements/issues/new?issuable_template=default)
+- [Official NVIDIA Elements DESIGN.md](https://NVIDIA.github.io/elements/docs/design-md/)
 
 ## Organization
 

package.json

@@ -102,6 +102,7 @@
         "./projects/starters/vue:ci",
         "./projects/styles:ci",
         "./projects/themes:ci",
+        "./projects/internals/design:ci",
         "./projects/internals/metadata:ci",
         "./projects/internals/patterns:ci",
         "./projects/internals/testing:ci",
@@ -262,6 +263,7 @@
         "./projects/create:lint:fix",
         "./projects/core:lint:fix",
         "./projects/forms:lint:fix",
+        "./projects/internals/design:lint:fix",
         "./projects/internals/metadata:lint:fix",
         "./projects/internals/patterns:lint:fix",
         "./projects/internals/testing:lint:fix",

pnpm-workspace.yaml

@@ -33,6 +33,7 @@ packages:
   - projects/forms
   - projects/styles
   - projects/themes
+  - projects/internals/design
   - projects/internals/eslint
   - projects/internals/metadata
   - projects/internals/patterns
@@ -126,6 +127,7 @@ minimumReleaseAgeExclude:
   - publint
   - typescript
   - vite
+  - '@google/design.md@0.4.0'
 
 allowBuilds:
   '@modelcontextprotocol/ext-apps': true

projects/internals/design/README.md

@@ -0,0 +1,11 @@
+# Elements design artifacts
+
+This private workspace project owns build-time design analysis and generated artifacts that describe the NVIDIA Elements design system as a whole.
+
+## DESIGN.md
+
+`src/design-md.js` resolves maintained Elements theme tokens and combines them with reviewed design and component guidance. The build writes the result to `dist/DESIGN.md`.
+
+Run `pnpm build` to generate the internal artifact. Run `pnpm sync:root` when an intentional generator change should update the checked-in `DESIGN.md` at the repository root.
+
+Tests verify that the built and repository artifacts match the generator. The site consumes the built artifact and publishes it at `/DESIGN.md`.

projects/internals/design/eslint.config.js

@@ -0,0 +1,13 @@
+import { nodeJavaScriptConfig } from '@internals/eslint';
+
+/** @type {import('eslint').Linter.Config[]} */
+export default [
+  ...nodeJavaScriptConfig,
+  {
+    files: ['src/design-md.js'],
+    rules: {
+      'max-lines': 'off',
+      'max-lines-per-function': 'off'
+    }
+  }
+];

projects/internals/design/package.json

@@ -0,0 +1,106 @@
+{
+  "name": "@internals/design",
+  "version": "0.0.0",
+  "private": true,
+  "description": "Build-time analysis and generated design artifacts for NVIDIA Elements.",
+  "type": "module",
+  "scripts": {
+    "ci": "wireit",
+    "build": "wireit",
+    "sync:root": "wireit",
+    "lint": "wireit",
+    "lint:fix": "wireit",
+    "test": "wireit",
+    "test:spec": "wireit"
+  },
+  "exports": {
+    "./DESIGN.md": "./dist/DESIGN.md"
+  },
+  "devDependencies": {
+    "@google/design.md": "0.4.0",
+    "@internals/eslint": "workspace:*",
+    "@nvidia-elements/themes": "workspace:*",
+    "eslint": "catalog:",
+    "vitest": "catalog:"
+  },
+  "wireit": {
+    "ci": {
+      "dependencies": [
+        "lint",
+        "test"
+      ]
+    },
+    "build": {
+      "command": "node ./scripts/write-design-md.js dist/DESIGN.md",
+      "files": [
+        "src/design-md.js",
+        "scripts/write-design-md.js",
+        "../../themes/dist/index.json",
+        "package.json"
+      ],
+      "output": [
+        "dist/DESIGN.md"
+      ],
+      "dependencies": [
+        {
+          "script": "../../themes:build",
+          "cascade": false
+        }
+      ]
+    },
+    "sync:root": {
+      "command": "node ./scripts/write-design-md.js ../../../DESIGN.md",
+      "files": [
+        "src/design-md.js",
+        "../../themes/dist/index.json"
+      ],
+      "output": [
+        "./dist/DESIGN.md"
+      ],
+      "dependencies": [
+        "build"
+      ]
+    },
+    "lint": {
+      "command": "eslint -c ./eslint.config.js --color --cache --cache-location .eslintcache/",
+      "files": [
+        "src/**/*.js",
+        "src/**/*.ts",
+        "scripts/**/*.js",
+        "eslint.config.js"
+      ],
+      "output": [],
+      "dependencies": [
+        "../eslint:ci"
+      ]
+    },
+    "lint:fix": {
+      "command": "eslint -c ./eslint.config.js --fix",
+      "dependencies": [
+        "../eslint:ci"
+      ]
+    },
+    "test": {
+      "command": "vitest run",
+      "files": [
+        "dist/DESIGN.md",
+        "src/**/*.test.js"
+      ],
+      "output": [],
+      "dependencies": [
+        "build",
+        "test:spec"
+      ]
+    },
+    "test:spec": {
+      "command": "designmd lint dist/DESIGN.md",
+      "files": [
+        "dist/DESIGN.md"
+      ],
+      "output": [],
+      "dependencies": [
+        "build"
+      ]
+    }
+  }
+}

projects/internals/design/scripts/write-design-md.js

@@ -0,0 +1,8 @@
+import { promises as fsp } from 'node:fs';
+import nodePath from 'node:path';
+import { createDesignMdContent } from '../src/design-md.js';
+
+const outputPath = nodePath.resolve(process.argv[2] ?? 'dist/DESIGN.md');
+
+await fsp.mkdir(nodePath.dirname(outputPath), { recursive: true });
+await fsp.writeFile(outputPath, createDesignMdContent(), 'utf-8');