From 7f7bc0209efd4ac2f257191d74947425b973898c Mon Sep 17 00:00:00 2001 From: Ryan Dombrowski Date: Wed, 22 Jul 2026 14:18:26 -0400 Subject: [PATCH] docs(DX-1): single-source tool docs, rename v0.1 example, breadcrumb + charter MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - D1: docs/README.md carried a stale seven-tool table contradicting the main README and architecture.md (eleven); it now defers to the main README's table, which is maintained in exactly one place. - D4 (compatibility-aware): examples/shadcn-ui.dspack.json (v0.1) -> examples/shadcn-ui-v01.dspack.json, so no unversioned filename can mean a different spec version than the dspack repository's v0.4 file of the same name. Dependents inventoried and updated in the same change (README, demo-shadcn walkthrough, pre-merge checklist, smoke.sh — which now exercises the synced v0.4 example); no sibling repository references the old path; deprecation recorded in README and CHANGELOG (Unreleased). - Breadcrumb to the org overview + kind/audience/neighbors charter; studio backlink with the hosted replay URL; export description catches up to Vue 3 + Vuetify 3 and DTCG import. Verified: npm test 94/94; scripts/smoke.sh end-to-end pass (11 tools). Co-Authored-By: Claude Fable 5 --- CHANGELOG.md | 11 ++++++++++ README.md | 20 +++++++++++++------ docs/README.md | 15 ++++---------- docs/demo-shadcn.md | 2 +- docs/pre-merge-checklist.md | 2 +- ....dspack.json => shadcn-ui-v01.dspack.json} | 0 scripts/smoke.sh | 2 +- 7 files changed, 32 insertions(+), 20 deletions(-) rename examples/{shadcn-ui.dspack.json => shadcn-ui-v01.dspack.json} (100%) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2c4ad1c..4d159fd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,16 @@ # Changelog +## Unreleased + +- The v0.1 example `examples/shadcn-ui.dspack.json` is renamed to + `examples/shadcn-ui-v01.dspack.json` (DX-1, D4): the old unversioned + filename collided with the dspack repository's v0.4 + `examples/shadcn-ui.dspack.json`, so the same path could silently mean + two different spec versions depending on the repository. All in-repo + references (README, demo walkthrough, pre-merge checklist, smoke + script) are updated; `scripts/smoke.sh` now exercises the v0.4 synced + example. No published-package behavior changes. + ## 0.3.2 The vendored `@aestheticfunction/dspack-gen/core` bundle moves from the diff --git a/README.md b/README.md index 024895c..541cb31 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,10 @@ **Stop asking AI agents to guess your design system. Give them a contract they can query.** +> Part of the [dspack ecosystem](https://github.com/aestheticfunction) — the organization profile has the full map of how the repositories fit together. +> +> **Kind:** application (MCP server, npm `@aestheticfunction/ds-mcp`, bin `ds-mcp`) · **Audience:** people using AI coding agents against a design system, and MCP client authors · **Neighbors:** implements the [dspack](https://github.com/aestheticfunction/dspack) spec; vendors its generation core from [dspack-gen](https://github.com/aestheticfunction/dspack-gen); bootstrap a contract with [dspack-export](https://github.com/aestheticfunction/dspack-export); see the full chain running in [dspack-studio](https://github.com/aestheticfunction/dspack-studio) ([hosted replay](https://studio.aesthetic-function.com)) + --- ## The problem @@ -46,8 +50,10 @@ https://github.com/user-attachments/assets/510a781b-4214-49b3-b997-9cbecdc36961 [shadcn/ui v0.4 example](examples/shadcn-ui-v04.dspack.json) to try it now — it carries the governance blocks the generation tools need. The [v0.2](examples/shadcn-ui-v02.dspack.json) and - [v0.1](examples/shadcn-ui.dspack.json) examples remain for the minimal - format. Have a React + Tailwind/shadcn codebase? You can + [v0.1](examples/shadcn-ui-v01.dspack.json) examples remain for the minimal + format. (The v0.1 example was previously named `shadcn-ui.dspack.json`; + it was renamed so that no unversioned filename can be confused with the + v0.4 contract of the same name in the dspack repository.) Have a React + Tailwind/shadcn codebase? You can generate a starting file from it — see [Don't have a dspack file yet?](#dont-have-a-dspack-file-yet) below.) 2. **Start ds-mcp** with the dspack file. It loads the file once and @@ -75,11 +81,13 @@ Configure your MCP client to connect to ds-mcp. See ## Don't have a dspack file yet? -If your design system is a React + Tailwind/shadcn codebase, the -experimental [dspack-export](https://github.com/aestheticfunction/dspack-export) +If your design system is a React + Tailwind/shadcn or Vue 3 + Vuetify 3 +codebase, the experimental +[dspack-export](https://github.com/aestheticfunction/dspack-export) tool can generate a starting dspack file from it — components, props (with -cva variant enums and defaults), color/radius tokens from your CSS custom -properties, dark-theme overrides, and breakpoints: +cva variant enums and defaults, and Vue `defineProps`/emits/slots), +color/radius tokens from your CSS custom properties or an imported DTCG +design-token file, dark-theme overrides, and breakpoints: ```bash git clone https://github.com/aestheticfunction/dspack-export diff --git a/docs/README.md b/docs/README.md index 89a7659..5acc06d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -116,17 +116,10 @@ See [GitHub's MCP documentation](https://docs.github.com/en/copilot/customizing- ## Tools -ds-mcp exposes seven read-only tools: - -| Tool | Input | Description | -|------|-------|-------------| -| `get-token` | `{ category, name }` | Retrieve a single design token by category and name | -| `search-tokens` | `{ query }` | Search tokens by name, category, description, or type | -| `get-component` | `{ id }` | Retrieve a full component definition by ID | -| `list-components` | none | List all components with ID, name, description, and deprecation status | -| `get-pattern` | `{ id }` | Retrieve a documented usage pattern by ID | -| `list-antipatterns` | none | List all anti-patterns the design system has identified | -| `get-framework-mapping` | `{ framework, componentId? }` | Retrieve framework-specific information, optionally merged with a component binding | +The complete tool table — eleven read-only tools, with inputs and +descriptions — lives in the [main README](../README.md#tools). It is +maintained in exactly one place so the two documents cannot disagree; +this page covers client configuration only. ## Security Posture diff --git a/docs/demo-shadcn.md b/docs/demo-shadcn.md index 3f01b43..88165b3 100644 --- a/docs/demo-shadcn.md +++ b/docs/demo-shadcn.md @@ -140,7 +140,7 @@ the current answer. ## v0.1 compatibility -The v0.1 example ([shadcn-ui.dspack.json](../examples/shadcn-ui.dspack.json)) +The v0.1 example ([shadcn-ui-v01.dspack.json](../examples/shadcn-ui-v01.dspack.json)) still works with ds-mcp. When loaded, the agent gets the same 13 components, 4 patterns, 3 anti-patterns, and framework bindings — but without lifecycle status, accessibility constraints, composition rules, diff --git a/docs/pre-merge-checklist.md b/docs/pre-merge-checklist.md index 60e3b38..5820590 100644 --- a/docs/pre-merge-checklist.md +++ b/docs/pre-merge-checklist.md @@ -8,7 +8,7 @@ ## Example dspack -- [ ] `examples/shadcn-ui.dspack.json` loads without errors +- [ ] `examples/shadcn-ui-v01.dspack.json` loads without errors - [ ] 13 components - [ ] 4 patterns (destructive-action-confirmation, form-field-layout, contextual-actions-menu, settings-form) - [ ] 3 anti-patterns diff --git a/examples/shadcn-ui.dspack.json b/examples/shadcn-ui-v01.dspack.json similarity index 100% rename from examples/shadcn-ui.dspack.json rename to examples/shadcn-ui-v01.dspack.json diff --git a/scripts/smoke.sh b/scripts/smoke.sh index 422b7ad..2b9d739 100755 --- a/scripts/smoke.sh +++ b/scripts/smoke.sh @@ -4,7 +4,7 @@ set -euo pipefail SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" PROJECT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)" EXAMPLE_DIR="$PROJECT_DIR/examples" -DSPACK_FILE="$EXAMPLE_DIR/shadcn-ui.dspack.json" +DSPACK_FILE="$EXAMPLE_DIR/shadcn-ui-v04.dspack.json" SERVER="$PROJECT_DIR/dist/index.js" echo "=== ds-mcp smoke test ==="