diff --git a/docs/markdown/pages/components/index.md b/docs/markdown/pages/components/index.md index d7d1120b..173f56b5 100644 --- a/docs/markdown/pages/components/index.md +++ b/docs/markdown/pages/components/index.md @@ -11,7 +11,7 @@ Component API schemas for Spectrum. diff --git a/docs/markdown/pages/index.md b/docs/markdown/pages/index.md index 5723eadc..2c03f034 100644 --- a/docs/markdown/pages/index.md +++ b/docs/markdown/pages/index.md @@ -17,7 +17,4 @@ API documentation, design tokens, and registry for **Spectrum**, Adobe's design ## Tools -* [S2 Tokens Viewer](/s2-tokens-viewer/) — Browse Spectrum 2 tokens -* [S2 Visualizer](/s2-visualizer/) — Token dependency graph (Spectrum 2) -* [Visualizer](/visualizer/) — Token dependency graph (Spectrum 1) -* [Release Timeline](/release-timeline/) — Release history +See the [Tools](/tools/) page for web-based tools and developer utilities. diff --git a/docs/markdown/pages/tokens/index.md b/docs/markdown/pages/tokens/index.md index 6076f293..35a0daf5 100644 --- a/docs/markdown/pages/tokens/index.md +++ b/docs/markdown/pages/tokens/index.md @@ -11,7 +11,7 @@ Design tokens (color, typography, layout, etc.). diff --git a/docs/markdown/tokens/color-aliases.md b/docs/markdown/tokens/color-aliases.md index cdd83b66..e4b7993b 100644 --- a/docs/markdown/tokens/color-aliases.md +++ b/docs/markdown/tokens/color-aliases.md @@ -1,6 +1,6 @@ --- -title: color aliases -description: Design tokens from color-aliases.json +title: Color aliases +description: "Semantic color tokens that reference the palette (e.g. focus, overlay)." tags: - tokens - color-aliases diff --git a/docs/markdown/tokens/color-component.md b/docs/markdown/tokens/color-component.md index a1af1dd8..a4cbb5fb 100644 --- a/docs/markdown/tokens/color-component.md +++ b/docs/markdown/tokens/color-component.md @@ -1,6 +1,6 @@ --- -title: color component -description: Design tokens from color-component.json +title: Color component +description: "Component-specific color tokens." tags: - tokens - color-component diff --git a/docs/markdown/tokens/color-palette.md b/docs/markdown/tokens/color-palette.md index df13f612..2a50aec4 100644 --- a/docs/markdown/tokens/color-palette.md +++ b/docs/markdown/tokens/color-palette.md @@ -1,6 +1,6 @@ --- -title: color palette -description: Design tokens from color-palette.json +title: Color palette +description: "Raw color values (hex/rgb) for the Spectrum palette." tags: - tokens - color-palette diff --git a/docs/markdown/tokens/icons.md b/docs/markdown/tokens/icons.md index 4271a13a..ab4fb38e 100644 --- a/docs/markdown/tokens/icons.md +++ b/docs/markdown/tokens/icons.md @@ -1,6 +1,6 @@ --- -title: icons -description: Design tokens from icons.json +title: Icons +description: "Color tokens for Spectrum icons (primary, hover, down, background, disabled)." tags: - tokens - icons diff --git a/docs/markdown/tokens/layout-component.md b/docs/markdown/tokens/layout-component.md index 592a85b4..1eaa3e25 100644 --- a/docs/markdown/tokens/layout-component.md +++ b/docs/markdown/tokens/layout-component.md @@ -1,6 +1,6 @@ --- -title: layout component -description: Design tokens from layout-component.json +title: Layout component +description: "Component-specific layout tokens." tags: - tokens - layout-component diff --git a/docs/markdown/tokens/layout.md b/docs/markdown/tokens/layout.md index 9a469853..abf76c21 100644 --- a/docs/markdown/tokens/layout.md +++ b/docs/markdown/tokens/layout.md @@ -1,6 +1,6 @@ --- -title: layout -description: Design tokens from layout.json +title: Layout +description: "Spacing, dimensions, corner radius, and other layout primitives." tags: - tokens - layout diff --git a/docs/markdown/tokens/semantic-color-palette.md b/docs/markdown/tokens/semantic-color-palette.md index a73ca18c..ac4319fb 100644 --- a/docs/markdown/tokens/semantic-color-palette.md +++ b/docs/markdown/tokens/semantic-color-palette.md @@ -1,6 +1,6 @@ --- -title: semantic color palette -description: Design tokens from semantic-color-palette.json +title: Semantic color palette +description: "Semantic palette tokens (e.g. semantic blue, semantic red)." tags: - tokens - semantic-color-palette diff --git a/docs/markdown/tokens/typography.md b/docs/markdown/tokens/typography.md index 5283e804..4d8028dc 100644 --- a/docs/markdown/tokens/typography.md +++ b/docs/markdown/tokens/typography.md @@ -1,6 +1,6 @@ --- -title: typography -description: Design tokens from typography.json +title: Typography +description: "Font families, weights, sizes, letter spacing, and text alignment." tags: - tokens - typography diff --git a/docs/site/eleventy.config.js b/docs/site/eleventy.config.js index 39ecd514..ec14e8c9 100644 --- a/docs/site/eleventy.config.js +++ b/docs/site/eleventy.config.js @@ -37,6 +37,9 @@ export default async function (eleventyConfig) { eleventyConfig.addGlobalData("navigation", navigation); eleventyConfig.addPassthroughCopy({ "public/favicon.png": "favicon.png" }); + eleventyConfig.addPassthroughCopy({ + "public/adobe_logo.svg": "adobe_logo.svg", + }); eleventyConfig.addPassthroughCopy({ "public/.nojekyll": ".nojekyll" }); eleventyConfig.addCollection("components", function (api) { diff --git a/docs/site/moon.yml b/docs/site/moon.yml index 8a799fc3..f801abf9 100644 --- a/docs/site/moon.yml +++ b/docs/site/moon.yml @@ -17,6 +17,14 @@ fileGroups: - "eleventy.config.js" - "package.json" tasks: + generateToolsPage: + command: + - pnpm + - run + - generate:tools + platform: node + outputs: + - "src/tools.md" copyContent: command: - node @@ -24,6 +32,7 @@ tasks: platform: system deps: - "markdown-generator:generate" + - "~:generateToolsPage" build: command: - pnpm diff --git a/docs/site/package.json b/docs/site/package.json index 4ee46548..9ad521a8 100644 --- a/docs/site/package.json +++ b/docs/site/package.json @@ -20,7 +20,8 @@ "scripts": { "build": "eleventy", "start": "eleventy --serve", - "clean": "rimraf ../../site .cache" + "clean": "rimraf ../../site .cache", + "generate:tools": "node scripts/generate-tools-page.js" }, "dependencies": { "@11ty/eleventy": "^3.0.0", diff --git a/docs/site/public/adobe_logo.svg b/docs/site/public/adobe_logo.svg new file mode 100644 index 00000000..2ad05c8c --- /dev/null +++ b/docs/site/public/adobe_logo.svg @@ -0,0 +1,13 @@ + + + + + + + + + + diff --git a/docs/site/scripts/generate-tools-page.js b/docs/site/scripts/generate-tools-page.js new file mode 100644 index 00000000..7f840d27 --- /dev/null +++ b/docs/site/scripts/generate-tools-page.js @@ -0,0 +1,151 @@ +/* +Copyright 2024 Adobe. All rights reserved. +This file is licensed to you 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 REPRESENTATIONS +OF ANY KIND, either express or implied. See the License for the specific language +governing permissions and limitations under the License. +*/ + +import { readFileSync, readdirSync, writeFileSync } from "fs"; +import { join, dirname } from "path"; +import { fileURLToPath } from "url"; + +const __dirname = dirname(fileURLToPath(import.meta.url)); + +const REPO_ROOT = join(__dirname, "../../.."); +const SITE_SRC = join(__dirname, "../src"); +const GITHUB_BASE = "https://github.com/adobe/spectrum-design-data"; +const NPM_BASE = "https://www.npmjs.com/package"; + +/** Web tools: deployed apps with fixed path and optional display label. */ +const WEB_TOOLS_CONFIG = [ + { + dir: "s2-tokens-viewer", + path: "/s2-tokens-viewer/", + label: "S2 Tokens Viewer", + }, + { dir: "s2-visualizer", path: "/s2-visualizer/", label: "S2 Visualizer" }, + { dir: "visualizer", path: "/visualizer/", label: "S1 Visualizer" }, + { + dir: "release-timeline", + path: "/release-timeline/", + label: "Release Timeline", + }, +]; + +const WEB_TOOLS_FALLBACK_DESCRIPTIONS = { + "s2-tokens-viewer": "Browse and inspect Spectrum 2 design token values", + "s2-visualizer": + "Interactive dependency graph for Spectrum 2 tokens showing ancestor/descendant relationships, value filters, and search", + visualizer: "Interactive dependency graph for Spectrum 1 (legacy) tokens", + "release-timeline": + "Interactive visualization of Spectrum Tokens release history across legacy, stable, beta, and snapshot formats", +}; + +function readJson(path) { + try { + return JSON.parse(readFileSync(path, "utf-8")); + } catch { + return null; + } +} + +function getDescription(pkg, fallback) { + if (pkg?.description && typeof pkg.description === "string") { + return pkg.description.trim(); + } + return fallback || "No description."; +} + +function isPrivatePackage(pkg) { + return pkg?.private === true || pkg?.access === "restricted"; +} + +function buildWebToolsSection(docsDir) { + const lines = [ + "## Web Tools", + "", + "Interactive tools deployed with this site:", + "", + ]; + for (const { dir, path, label } of WEB_TOOLS_CONFIG) { + const pkgPath = join(docsDir, dir, "package.json"); + const pkg = readJson(pkgPath); + const desc = getDescription(pkg, WEB_TOOLS_FALLBACK_DESCRIPTIONS[dir]); + lines.push(`* **[${label}](${path})** — ${desc}`); + } + return lines.join("\n"); +} + +function buildDeveloperToolsSection(toolsDir) { + const dirs = readdirSync(toolsDir, { withFileTypes: true }) + .filter((d) => d.isDirectory()) + .map((d) => d.name); + + const entries = []; + for (const dir of dirs) { + const pkgPath = join(toolsDir, dir, "package.json"); + const pkg = readJson(pkgPath); + if (!pkg?.name) continue; + + const description = getDescription(pkg); + const name = pkg.name; + const url = isPrivatePackage(pkg) + ? `${GITHUB_BASE}/tree/main/tools/${dir}` + : `${NPM_BASE}/${encodeURIComponent(name)}`; + + entries.push({ name, url, description }); + } + + entries.sort((a, b) => + a.name.localeCompare(b.name, undefined, { sensitivity: "base" }), + ); + + const lines = [ + "## Developer Tools", + "", + "Packages under `tools/` in the repo:", + "", + ]; + + for (const { name, url, description } of entries) { + lines.push(`* **[${name}](${url})** — ${description}`); + } + + return lines.join("\n"); +} + +function generateToolsPage() { + const docsDir = join(REPO_ROOT, "docs"); + const toolsDir = join(REPO_ROOT, "tools"); + const outPath = join(SITE_SRC, "tools.md"); + + const frontmatter = `--- +title: Tools +layout: base.liquid +permalink: /tools/ +--- + + + +`; + + const webSection = buildWebToolsSection(docsDir); + const devSection = buildDeveloperToolsSection(toolsDir); + + const content = `${frontmatter}# Tools + +${webSection} + +${devSection} +`; + + writeFileSync(outPath, content, "utf-8"); + console.log("Generated:", outPath); +} + +generateToolsPage(); diff --git a/docs/site/src/assets/css/base/index.css b/docs/site/src/assets/css/base/index.css index 06d416d1..b180a660 100644 --- a/docs/site/src/assets/css/base/index.css +++ b/docs/site/src/assets/css/base/index.css @@ -73,6 +73,9 @@ menu, header { margin: var(--spacing-large) 0; + flex-direction: column; + align-items: flex-start; + gap: var(--spacing-default); } header a:has(h1) { @@ -82,6 +85,7 @@ header a:has(h1) { header h1 { display: flex; gap: var(--spacing-default); + font-weight: 700 !important; } header h1 img { @@ -90,8 +94,6 @@ header h1 img { @media screen and (max-width: 768px) { header { - justify-content: baseline; - flex-direction: column; align-items: start; } } @@ -174,9 +176,15 @@ footer .footer-label { footer menu { justify-content: center; + flex-wrap: wrap; margin-bottom: var(--spacing-large); } +footer menu a { + font-weight: normal; + white-space: nowrap; +} + footer p:not(.footer-label) { text-align: center; font-style: italic; diff --git a/docs/site/src/data/navigation.js b/docs/site/src/data/navigation.js index ecea83d9..1acabdf4 100644 --- a/docs/site/src/data/navigation.js +++ b/docs/site/src/data/navigation.js @@ -12,16 +12,11 @@ governing permissions and limitations under the License. export default { top: [ - { text: "Home", url: "/" }, { text: "Components", url: "/components/" }, { text: "Tokens", url: "/tokens/" }, { text: "Registry", url: "/registry/" }, { text: "AI", url: "/ai/" }, + { text: "Tools", url: "/tools/" }, ], - bottom: [ - { text: "S2 Tokens Viewer", url: "/s2-tokens-viewer/" }, - { text: "S2 Visualizer", url: "/s2-visualizer/" }, - { text: "Visualizer", url: "/visualizer/" }, - { text: "Release Timeline", url: "/release-timeline/" }, - ], + bottom: [], }; diff --git a/docs/site/src/includes/layout/footer.liquid b/docs/site/src/includes/layout/footer.liquid index f8394da1..3be719b6 100644 --- a/docs/site/src/includes/layout/footer.liquid +++ b/docs/site/src/includes/layout/footer.liquid @@ -11,11 +11,10 @@ governing permissions and limitations under the License. --> diff --git a/docs/site/src/includes/layout/header.liquid b/docs/site/src/includes/layout/header.liquid index e350eb35..3a244508 100644 --- a/docs/site/src/includes/layout/header.liquid +++ b/docs/site/src/includes/layout/header.liquid @@ -12,13 +12,16 @@ governing permissions and limitations under the License.
-

Spectrum Design Data

+

+ Adobe logo + Spectrum Design Data +

-
  • Home
  • Components
  • Tokens
  • Registry
  • AI
    • +
  • Tools
    •
    diff --git a/docs/site/src/layouts/base.liquid b/docs/site/src/layouts/base.liquid index 4c994ace..682529d8 100644 --- a/docs/site/src/layouts/base.liquid +++ b/docs/site/src/layouts/base.liquid @@ -8,6 +8,8 @@ {% if title %}{{ title }} | {% endif %}{{ siteName }} + + diff --git a/docs/site/src/pages/components/index.md b/docs/site/src/pages/components/index.md index d7d1120b..173f56b5 100644 --- a/docs/site/src/pages/components/index.md +++ b/docs/site/src/pages/components/index.md @@ -11,7 +11,7 @@ Component API schemas for Spectrum. diff --git a/docs/site/src/pages/index.md b/docs/site/src/pages/index.md index 5723eadc..2c03f034 100644 --- a/docs/site/src/pages/index.md +++ b/docs/site/src/pages/index.md @@ -17,7 +17,4 @@ API documentation, design tokens, and registry for **Spectrum**, Adobe's design ## Tools -* [S2 Tokens Viewer](/s2-tokens-viewer/) — Browse Spectrum 2 tokens -* [S2 Visualizer](/s2-visualizer/) — Token dependency graph (Spectrum 2) -* [Visualizer](/visualizer/) — Token dependency graph (Spectrum 1) -* [Release Timeline](/release-timeline/) — Release history +See the [Tools](/tools/) page for web-based tools and developer utilities. diff --git a/docs/site/src/pages/tokens/index.md b/docs/site/src/pages/tokens/index.md index 6076f293..35a0daf5 100644 --- a/docs/site/src/pages/tokens/index.md +++ b/docs/site/src/pages/tokens/index.md @@ -11,7 +11,7 @@ Design tokens (color, typography, layout, etc.). diff --git a/docs/site/src/tools.md b/docs/site/src/tools.md new file mode 100644 index 00000000..7f36261f --- /dev/null +++ b/docs/site/src/tools.md @@ -0,0 +1,38 @@ +--- +title: Tools +layout: base.liquid +permalink: /tools/ +--- + + + +# Tools + +## Web Tools + +Interactive tools deployed with this site: + +* **[S2 Tokens Viewer](/s2-tokens-viewer/)** — Browse and inspect Spectrum 2 design token values +* **[S2 Visualizer](/s2-visualizer/)** — Interactive dependency graph for Spectrum 2 tokens showing ancestor/descendant relationships, value filters, and search +* **[S1 Visualizer](/visualizer/)** — Interactive dependency graph for Spectrum 1 (legacy) tokens +* **[Release Timeline](/release-timeline/)** — Interactive timeline visualization of Spectrum Tokens release history + +## Developer Tools + +Packages under `tools/` in the repo: + +* **[@adobe/changeset-linter](https://www.npmjs.com/package/%40adobe%2Fchangeset-linter)** — Linting tool to enforce concise changeset files +* **[@adobe/optimized-diff](https://www.npmjs.com/package/%40adobe%2Foptimized-diff)** — High-performance deep object diff algorithm with significant performance improvements over generic libraries +* **[@adobe/s2-docs-mcp](https://www.npmjs.com/package/%40adobe%2Fs2-docs-mcp)** — MCP server for Spectrum 2 documentation +* **[@adobe/spectrum-component-diff-generator](https://www.npmjs.com/package/%40adobe%2Fspectrum-component-diff-generator)** — Generates diff reports for Spectrum component schema changes with breaking change analysis +* **[@adobe/spectrum-design-data-mcp](https://www.npmjs.com/package/%40adobe%2Fspectrum-design-data-mcp)** — Model Context Protocol server for Spectrum design data including tokens, schemas, and component anatomy +* **[@adobe/spectrum-diff-core](https://www.npmjs.com/package/%40adobe%2Fspectrum-diff-core)** — Shared core library for Spectrum diff generation tools (tokens, component schemas, etc.) +* **[@adobe/token-diff-generator](https://www.npmjs.com/package/%40adobe%2Ftoken-diff-generator)** — Generate comprehensive diffs between design token sets with support for multiple output formats including CLI, JSON, and Markdown. Detects added, deleted, renamed, deprecated, and updated tokens across different schema versions. +* **[component-options-editor](https://github.com/adobe/spectrum-design-data/tree/main/tools/component-options-editor)** — Figma plugin for authoring Spectrum component option schemas +* **[markdown-generator](https://github.com/adobe/spectrum-design-data/tree/main/tools/markdown-generator)** — Generate markdown files from tokens, component-schemas, and design-system-registry for docs and chatbot indexing +* **[release-analyzer](https://github.com/adobe/spectrum-design-data/tree/main/tools/release-analyzer)** — Analyzes Spectrum Tokens release history and generates data for change frequency visualization +* **[s2-docs-transformer](https://github.com/adobe/spectrum-design-data/tree/main/tools/s2-docs-transformer)** — Tools for scraping and transforming Spectrum 2 documentation +* **[token-changeset-generator](https://github.com/adobe/spectrum-design-data/tree/main/tools/token-changeset-generator)** — Generate changeset files for Spectrum token changes from tokens studio PR data +* **[token-csv-generator](https://github.com/adobe/spectrum-design-data/tree/main/tools/token-csv-generator)** — A simple tool to generate a CSV from the tokens +* **[token-manifest-builder](https://github.com/adobe/spectrum-design-data/tree/main/tools/token-manifest-builder)** — Builds a JSON manifest file from the source of a Style Dictionary project. +* **[transform-tokens-json](https://github.com/adobe/spectrum-design-data/tree/main/tools/transform-tokens-json)** — A simple tool to make one time changes in Spectrum Tokens diff --git a/tools/component-options-editor/package.json b/tools/component-options-editor/package.json index ac99c08c..ee1d6f1c 100644 --- a/tools/component-options-editor/package.json +++ b/tools/component-options-editor/package.json @@ -1,5 +1,5 @@ { - "name": "@adobe/component-options-editor", + "name": "component-options-editor", "version": "1.1.0", "description": "Figma plugin for authoring Spectrum component option schemas", "type": "module", diff --git a/tools/markdown-generator/src/tokens.js b/tools/markdown-generator/src/tokens.js index acf1ddd8..953dd770 100644 --- a/tools/markdown-generator/src/tokens.js +++ b/tools/markdown-generator/src/tokens.js @@ -27,6 +27,22 @@ import { dirname } from "path"; const ALIAS_PATTERN = /^\{([^}]+)\}$/; +/** Short descriptions for each token file so the tokens list differentiates them. */ +const TOKEN_FILE_DESCRIPTIONS = { + "color-aliases": + "Semantic color tokens that reference the palette (e.g. focus, overlay).", + "color-palette": "Raw color values (hex/rgb) for the Spectrum palette.", + "color-component": "Component-specific color tokens.", + "semantic-color-palette": + "Semantic palette tokens (e.g. semantic blue, semantic red).", + typography: + "Font families, weights, sizes, letter spacing, and text alignment.", + layout: "Spacing, dimensions, corner radius, and other layout primitives.", + "layout-component": "Component-specific layout tokens.", + icons: + "Color tokens for Spectrum icons (primary, hover, down, background, disabled).", +}; + function formatValueDisplay(value, valueLink) { if (value == null) return "-"; const str = String(value); @@ -69,8 +85,11 @@ export async function generateTokenMarkdown(outputDir) { let total = 0; for (const [fileKey, tokens] of fileToTokens) { - const title = fileKey.replace(/-/g, " "); - const description = `Design tokens from ${fileKey}.json`; + const rawTitle = fileKey.replace(/-/g, " "); + const title = + rawTitle.charAt(0).toUpperCase() + rawTitle.slice(1).toLowerCase(); + const description = + TOKEN_FILE_DESCRIPTIONS[fileKey] || `Design tokens from ${fileKey}.json`; const tags = ["tokens", fileKey]; const rows = []; @@ -94,9 +113,10 @@ export async function generateTokenMarkdown(outputDir) { const table = `\n| Token | Value | Resolved | Deprecated | Deprecated comment | Replaced by |\n| --- | --- | --- | --- | --- | --- |\n${rows.join("\n")}\n`; + const safeDesc = description.replace(/"/g, '\\"'); const frontmatter = `--- title: ${title} -description: ${description} +description: "${safeDesc}" tags: ${tags.map((t) => ` - ${t}`).join("\n")} --- diff --git a/tools/release-analyzer/package.json b/tools/release-analyzer/package.json index c14a1d10..727b4663 100644 --- a/tools/release-analyzer/package.json +++ b/tools/release-analyzer/package.json @@ -1,5 +1,5 @@ { - "name": "@adobe/spectrum-tokens-release-analyzer", + "name": "release-analyzer", "private": true, "version": "0.2.0", "description": "Analyzes Spectrum Tokens release history and generates data for change frequency visualization", diff --git a/tools/s2-docs-transformer/package.json b/tools/s2-docs-transformer/package.json index b3923f0a..9d4aba81 100644 --- a/tools/s2-docs-transformer/package.json +++ b/tools/s2-docs-transformer/package.json @@ -1,5 +1,5 @@ { - "name": "@adobe/s2-docs-transformer", + "name": "s2-docs-transformer", "version": "1.0.0", "private": true, "description": "Tools for scraping and transforming Spectrum 2 documentation", diff --git a/tools/token-changeset-generator/package.json b/tools/token-changeset-generator/package.json index c876e835..a0ee615f 100644 --- a/tools/token-changeset-generator/package.json +++ b/tools/token-changeset-generator/package.json @@ -1,5 +1,5 @@ { - "name": "@adobe/token-changeset-generator", + "name": "token-changeset-generator", "version": "0.2.6", "description": "Generate changeset files for Spectrum token changes from tokens studio PR data", "keywords": [