designmd-forge 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 adelpro
+
+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,119 @@
+# designmd-forge
+
+A free, local MCP server for browsing and searching **DESIGN.md** files — plain-text design-system documents (colors, typography, components, layout) that AI coding agents read to generate UI matching a target visual style.
+
+Data is a bundled, offline snapshot of three MIT-licensed sources — 74 **web** design systems from [VoltAgent/awesome-design-md](https://github.com/VoltAgent/awesome-design-md), 10 **mobile** archetypes from [TrustOtc/awesome-mobile-design-md](https://github.com/TrustOtc/awesome-mobile-design-md), and 200 **iOS** app design systems from [Meliwat/awesome-ios-design-md](https://github.com/meliwat/awesome-ios-design-md) (284 design specs). No paid API, no rate limits, no network calls at runtime. The sources extract only publicly visible CSS / app values (colors, type scale, spacing) or are original DESIGN.md documents — no logos, trademarks, or copyrighted imagery, so it's safe to redistribute and reuse.
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `designmd_list_categories` | List all categories with counts, optionally filtered by platform (e.g. "Fintech & Crypto", "Automotive", "Mobile") |
+| `designmd_list_designs` | List all designs, optionally filtered by category and/or platform (`web` / `mobile` / `ios`) — title, slug, one-line description |
+| `designmd_search_designs` | Free-text search over title/slug/category/description, ranked by relevance, optionally filtered by category/platform |
+| `designmd_get_design_md` | Fetch the full DESIGN.md, one section, one component sub-group, or an iOS framework flavor (swiftui/expo/android) for one design by slug |
+| `designmd_get_guardrails` | Fetch only the "Do's and Don'ts" section — behavioral rules, not token values |
+| `designmd_lint` | Validate a DESIGN.md's structure using the official `@google/design.md` linter |
+| `designmd_diff` | Compare two DESIGN.md files (token-level) with the official CLI and flag regressions |
+| `designmd_get_authoring_guide` | Fetch condensed, field-tested guidance on *writing* a DESIGN.md's prose |
+| `designmd_scaffold_template` | Generate a fill-in-the-blank DESIGN.md skeleton, prompted around the highest-leverage sections |
+
+Two flows this server supports:
+
+- **Reference an existing design system**: `designmd_search_designs` or `designmd_list_designs` to find a slug → `designmd_get_design_md` to pull the full file (or `designmd_get_guardrails` for just the usage rules) → paste into your project root and tell your coding agent to follow it.
+- **Author your own**: `designmd_get_authoring_guide` → `designmd_scaffold_template` → fill in the prose (see the companion skill below) → `designmd_lint` before committing.
+
+### Why there's a dedicated guardrails tool, and a linter, and an authoring guide
+
+Color hex codes and type scales tell an agent *what* the values are, not *how* to use them. Token-only DESIGN.md files reliably produce token-correct but decision-wrong output — an agent applying a brand accent color as a background tint on every info banner, or giving every card the same shadow regardless of hierarchy. Two things address this from different angles:
+
+- Each bundled file's "Do's and Don'ts" section is where usage rules and anti-patterns live — `designmd_get_guardrails` (or `designmd_get_design_md` with `section: "dos_and_donts"`) pulls just that.
+- `designmd_lint` wraps the format spec's own official CLI (`@google/design.md`, npm-published, MIT-adjacent to the spec itself) to catch structural issues — missing frontmatter, orphaned tokens never referenced by any component — before you commit a file. It validates structure only, not whether your prose constraints are the right ones.
+- `designmd_get_authoring_guide` and `designmd_scaffold_template` exist for writing your *own* file well in the first place, since the reference collection is only useful as structural inspiration — copying another brand's prose into your file doesn't help, because it describes a different product.
+
+### Section-level fetching
+
+`designmd_get_design_md` accepts an optional `section` param to avoid pulling the whole file when only one part is relevant. Web sections: `overview`, `colors`, `typography`, `layout`, `elevation`, `shapes`, `components`, `dos_and_donts`, `responsive`, `iteration_guide`, `known_gaps`, `agent_prompt_guide`. Mobile archetypes use their own headings, mapped to compatible canonicals where possible (`color system`→`colors`, `spacing system`→`layout`, `do / don't`→`dos_and_donts`) plus mobile-specific ones (`design_principles`, `safe_area`, `touch_interaction`, `navigation`, `motion`, `iconography`, `accessibility`, `platform_adaptation`). Not every file has every section — omitting `section` always returns the full file as a fallback.
+
+### iOS framework flavors
+
+Every iOS design (`platform: ios`, slug like `ios-spotify`) ships four files: the framework-neutral `DESIGN.md` plus paste-ready `DESIGN-swiftui.md`, `DESIGN-expo.md`, and `DESIGN-android.md` implementations. `designmd_get_design_md` indexes the neutral spec; pass `flavor: "swiftui" | "expo" | "android"` to fetch the framework implementation instead. iOS slugs are prefixed `ios-` so they never collide with web/mobile slugs (e.g. `spotify` is web, `ios-spotify` is the iOS app).
+
+### Component sub-groups
+
+The framework-neutral "Component Stylings" section breaks into `### ` sub-groups (Buttons, Cards & Containers, Navigation, Input Fields, Distinctive Components — names vary per design). Pass `component: "navigation"` etc. to `designmd_get_design_md` to fetch just that one sub-group instead of the whole section. The match is best-effort against the file's sub-headings and is only valid on the neutral spec (not combined with `flavor`).
+
+## Companion skill: designmd-authoring
+
+`skill/designmd-authoring/SKILL.md` is a Claude skill that wires these tools into an actual authoring workflow — interviewing for the prose that matters (Overview, Colors, Do's and Don'ts) rather than just generating a token dump, diagnosing why an existing file isn't changing agent output, and linting before treating a draft as done. Drop the `skill/designmd-authoring/` folder into wherever your Claude setup looks for skills (e.g. `.claude/skills/` for Claude Code) alongside this MCP server being connected.
+
+## Setup
+
+```bash
+npm install
+npm run build
+```
+
+This compiles TypeScript to `dist/` and copies the bundled data (`src/data/index.json` + `src/data/designs/*.md`) alongside it.
+
+## Transports
+
+Two entry points, both built from `npm run build`:
+
+- **stdio** (`dist/index.js`, `npm start`) — for local MCP clients (Claude Desktop, Claude Code) that spawn the server as a subprocess.
+- **Streamable HTTP** (`dist/httpServer.js`, `npm run start:http`) — for remote hosting as a connector, stateless mode, no auth. Env vars: `PORT` (default 3000), `MCP_PATH` (default `/mcp`). See `DEPLOY.md` for hosting this behind a Cloudflare Tunnel on a custom domain, matching the pattern used for `mcp.quran.us.kg`.
+
+## Use with an MCP client (e.g. Claude Desktop, Claude Code) — stdio, local
+
+Add to your MCP client config (for Claude Desktop, `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "designmd": {
+      "command": "node",
+      "args": ["/absolute/path/to/designmd-forge/dist/index.js"]
+    }
+  }
+}
+```
+
+Restart the client. You should see the nine `designmd_*` tools available.
+
+## Refreshing the data
+
+The upstream repos add new sites over time. Each source has its own build script and npm task:
+
+```bash
+npm run refresh-data:web     # VoltAgent/awesome-design-md  -> .staging/web.json
+npm run refresh-data:mobile  # TrustOtc/awesome-mobile-design-md -> .staging/mobile.json
+npm run refresh-data:ios     # Meliwat/awesome-ios-design-md -> .staging/ios.json
+npm run load-data            # merge all staged sources -> src/data/index.json
+npm run build
+```
+
+`npm run refresh-data` runs all four steps in sequence. Each build script re-clones its upstream repo into a temp dir, writes the design files to `src/data/designs/`, emits the source fragment to `.staging/`, then cleans up the clone; `npm run load-data` merges every staged fragment into `src/data/index.json` and clears `.staging/`. Run the individual `refresh-data:<source>` scripts to refresh only one source.
+
+## Testing
+
+```bash
+npm test
+```
+
+Runs the suite in `src/__tests__/` via Node's built-in test runner (`node --test`) — no extra test framework dependency. Covers the section parser across both bundled file formats, the search/lookup logic, the linter service (real CLI invocation, not mocked), and full tool behavior through a real MCP client connected via `InMemoryTransport` (tool list, successful calls, and error paths). `npm test` runs `npm run build` first via a `pretest` hook.
+
+CI (`.github/workflows/ci.yml`) runs build + test on Node 18/20/22 on every push and PR, plus a smoke check that the HTTP server actually boots and responds on `/health`.
+
+## Contributing
+
+See `CONTRIBUTING.md`.
+
+## License
+
+MIT — see `LICENSE`. That covers this project's own code. The bundled reference files under `src/data/designs/` are a snapshot of [VoltAgent/awesome-design-md](https://github.com/VoltAgent/awesome-design-md), also MIT licensed, with attribution and the license note preserved in `src/data/index.json`.
+
+## Notes
+
+- **License of the tool data**: MIT, per upstream's `LICENSE`. Their README states the extracted tokens "represent publicly visible CSS values" and they "do not claim ownership of any site's visual identity."
+- Categories currently bundled: AI & LLM Platforms, Developer Tools & IDEs, Backend/Database & DevOps, Productivity & SaaS, Design & Creative Tools, Fintech & Crypto, E-commerce & Retail, Media & Consumer Tech, Automotive, Retro Web (plus any not-yet-categorized additions upstream hasn't sorted into the README yet).
+- This server does not call any external API at runtime — it's entirely local, so there's nothing to rate-limit or pay for.

package/dist/__tests__/designStore.test.js

@@ -0,0 +1,41 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { loadIndex, getEntryBySlug, searchDesigns, listCategories, } from '../services/designStore.js';
+test('loadIndex returns the bundled 74-design index', () => {
+    const index = loadIndex();
+    assert.ok(index.count >= 70, `expected at least 70 designs, got ${index.count}`);
+    assert.ok(index.designs.length === index.count);
+    assert.equal(index.license, 'MIT');
+});
+test('listCategories returns a non-empty, deduplicated list', () => {
+    const categories = listCategories();
+    assert.ok(categories.length > 0);
+    assert.equal(new Set(categories).size, categories.length, 'categories should be unique');
+});
+test('getEntryBySlug finds a known slug case-insensitively', () => {
+    const exact = getEntryBySlug('stripe');
+    assert.ok(exact, 'stripe should exist');
+    const upper = getEntryBySlug('STRIPE');
+    assert.ok(upper, 'slug lookup should be case-insensitive');
+    assert.equal(exact.slug, upper.slug);
+});
+test('getEntryBySlug returns undefined for an unknown slug', () => {
+    assert.equal(getEntryBySlug('definitely-not-a-real-site'), undefined);
+});
+test('searchDesigns ranks title matches above description-only matches', () => {
+    const results = searchDesigns('stripe');
+    assert.ok(results.length > 0);
+    assert.equal(results[0].slug, 'stripe', 'exact title match should rank first');
+});
+test('searchDesigns respects the category filter', () => {
+    const categories = listCategories();
+    const someCategory = categories[0];
+    const results = searchDesigns('', { category: someCategory, limit: 50 });
+    for (const r of results) {
+        assert.equal(r.category, someCategory);
+    }
+});
+test('searchDesigns returns empty array for a nonsense query', () => {
+    const results = searchDesigns('zzzzznonexistentqueryxyz123');
+    assert.equal(results.length, 0);
+});

package/dist/__tests__/linter.test.js

@@ -0,0 +1,23 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { lintDesignMdContent } from '../services/linter.js';
+test('lintDesignMdContent returns structured findings for content with no frontmatter', async () => {
+    const result = await lintDesignMdContent('just some text, no yaml at all');
+    assert.ok(Array.isArray(result.findings));
+    assert.ok(result.summary);
+    assert.ok(result.summary.warnings >= 1, 'should warn about missing YAML');
+});
+test('lintDesignMdContent returns zero errors for a well-formed file', async () => {
+    const wellFormed = `---
+name: Test
+colors:
+  primary: "#000000"
+---
+
+## Overview
+
+A test design system.
+`;
+    const result = await lintDesignMdContent(wellFormed);
+    assert.equal(result.summary.errors, 0);
+});

package/dist/__tests__/sectionParser.test.js

@@ -0,0 +1,60 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { parseSections, getSection } from '../services/sectionParser.js';
+const numberedFormat = `---
+name: Test
+---
+
+## 1. Visual Theme & Atmosphere
+
+This is the overview text.
+It spans two lines.
+
+## 2. Color Palette & Roles
+
+Primary is reserved for buttons.
+
+## 7. Do's and Don'ts
+
+Never use gradients.
+`;
+const plainFormat = `---
+name: Test
+---
+
+## Overview
+
+Plain overview text.
+
+## Colors
+
+Plain colors text.
+
+## Do's and Don'ts
+
+Plain dos and donts text.
+`;
+test('parseSections extracts sections from numbered format', () => {
+    const sections = parseSections(numberedFormat);
+    const overview = sections.find((s) => s.canonical === 'overview');
+    assert.ok(overview, 'overview section should be found');
+    assert.match(overview.content, /This is the overview text/);
+});
+test('parseSections extracts sections from plain format', () => {
+    const sections = parseSections(plainFormat);
+    const colors = sections.find((s) => s.canonical === 'colors');
+    assert.ok(colors, 'colors section should be found');
+    assert.match(colors.content, /Plain colors text/);
+});
+test('getSection returns dos_and_donts for both formats', () => {
+    const numbered = getSection(numberedFormat, 'dos_and_donts');
+    const plain = getSection(plainFormat, 'dos_and_donts');
+    assert.ok(numbered);
+    assert.ok(plain);
+    assert.match(numbered.content, /Never use gradients/);
+    assert.match(plain.content, /Plain dos and donts text/);
+});
+test('getSection returns undefined for a section not present', () => {
+    const result = getSection(plainFormat, 'shapes');
+    assert.equal(result, undefined);
+});

package/dist/__tests__/server.test.js

@@ -0,0 +1,129 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import { createServer } from '../server.js';
+async function withConnectedClient(fn) {
+    const server = createServer();
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    const client = new Client({ name: 'test-client', version: '1.0.0' });
+    await server.connect(serverTransport);
+    await client.connect(clientTransport);
+    try {
+        return await fn(client);
+    }
+    finally {
+        await client.close();
+        await server.close();
+    }
+}
+test('server exposes exactly the 9 expected tools', async () => {
+    await withConnectedClient(async (client) => {
+        const { tools } = await client.listTools();
+        const names = tools.map((t) => t.name).sort();
+        assert.deepEqual(names, [
+            'designmd_diff',
+            'designmd_get_authoring_guide',
+            'designmd_get_design_md',
+            'designmd_get_guardrails',
+            'designmd_lint',
+            'designmd_list_categories',
+            'designmd_list_designs',
+            'designmd_scaffold_template',
+            'designmd_search_designs',
+        ]);
+    });
+});
+test('designmd_get_design_md returns full content for a known slug', async () => {
+    await withConnectedClient(async (client) => {
+        const result = await client.callTool({
+            name: 'designmd_get_design_md',
+            arguments: { slug: 'stripe' },
+        });
+        assert.equal(result.isError, undefined);
+        const content = result.content[0].text;
+        assert.ok(content.length > 100);
+    });
+});
+test('designmd_get_design_md errors cleanly on an unknown slug', async () => {
+    await withConnectedClient(async (client) => {
+        const result = await client.callTool({
+            name: 'designmd_get_design_md',
+            arguments: { slug: 'not-a-real-site' },
+        });
+        assert.equal(result.isError, true);
+    });
+});
+test('designmd_search_designs returns ranked results', async () => {
+    await withConnectedClient(async (client) => {
+        const result = await client.callTool({
+            name: 'designmd_search_designs',
+            arguments: { query: 'stripe' },
+        });
+        const text = result.content[0].text;
+        const parsed = JSON.parse(text);
+        assert.ok(parsed.total_matches >= 1);
+        assert.equal(parsed.results[0].slug, 'stripe');
+    });
+});
+test('designmd_lint requires exactly one of content/slug', async () => {
+    await withConnectedClient(async (client) => {
+        const neither = await client.callTool({ name: 'designmd_lint', arguments: {} });
+        assert.equal(neither.isError, true);
+        const both = await client.callTool({
+            name: 'designmd_lint',
+            arguments: { content: 'x', slug: 'stripe' },
+        });
+        assert.equal(both.isError, true);
+    });
+});
+test('designmd_scaffold_template includes the requested product name', async () => {
+    await withConnectedClient(async (client) => {
+        const result = await client.callTool({
+            name: 'designmd_scaffold_template',
+            arguments: { product_name: 'Test Product XYZ' },
+        });
+        const text = result.content[0].text;
+        assert.match(text, /Test Product XYZ/);
+    });
+});
+test('designmd_diff reports token changes and regression between two drafts', async () => {
+    await withConnectedClient(async (client) => {
+        const before = `---
+version: alpha
+name: Test
+colors:
+  primary: "#0A2540"
+---
+## Overview
+x`;
+        const after = `---
+version: alpha
+name: Test
+colors:
+  primary: "#FF0000"
+---
+## Overview
+x`;
+        const result = await client.callTool({
+            name: 'designmd_diff',
+            arguments: {
+                before: { content: before },
+                after: { content: after },
+            },
+        });
+        assert.equal(result.isError, undefined);
+        const sc = result.structuredContent;
+        assert.ok(typeof sc.regression === 'boolean');
+        assert.deepEqual(sc.tokens.colors.modified, ['primary']);
+    });
+});
+test('designmd_diff errors when a side has no content or slug', async () => {
+    await withConnectedClient(async (client) => {
+        const result = await client.callTool({
+            name: 'designmd_diff',
+            arguments: { before: {}, after: { content: '---\nversion: alpha\n---' } },
+        });
+        assert.equal(result.isError, true);
+    });
+});

package/dist/constants.js

@@ -0,0 +1,12 @@
+export const CHARACTER_LIMIT = 25000;
+export const SOURCE_REPO = 'https://github.com/VoltAgent/awesome-design-md';
+export const SOURCE_LICENSE = 'MIT';
+export const MOBILE_SOURCE_REPO = 'https://github.com/TrustOtc/awesome-mobile-design-md';
+export const IOS_SOURCE_REPO = 'https://github.com/meliwat/awesome-ios-design-md';
+export const PLATFORMS = ['web', 'mobile', 'ios'];
+/** Upstream repo URL for each platform, for source attribution in tool output. */
+export const SOURCE_BY_PLATFORM = {
+    web: SOURCE_REPO,
+    mobile: MOBILE_SOURCE_REPO,
+    ios: IOS_SOURCE_REPO,
+};

package/dist/data/authoring-guide.md

@@ -0,0 +1,113 @@
+# Writing a DESIGN.md That Actually Changes Output
+
+This is a condensed set of principles for writing the prose half of a
+DESIGN.md file — not the YAML token block, the markdown body underneath it.
+It's synthesized from practitioner reports of running a DESIGN.md against a
+real coding agent daily for a month and tracking which changes actually
+moved generated output, plus the official format spec's own guidance.
+
+## The core finding: tokens describe values, prose describes decisions
+
+A DESIGN.md with a complete, accurate YAML token block (hex colors, a type
+scale, spacing units) is not sufficient on its own. A coding agent given
+only tokens tends to produce output where every individual value is
+correct but the decisions around those values are generic: a brand accent
+color gets used as a decorative background tint instead of being reserved
+for interactive elements; every card gets the same soft shadow regardless
+of whether the product's actual visual language uses shadows at all.
+
+The fix isn't more tokens. It's prose that states what each token means
+and where it's allowed to appear — not just what its value is.
+
+## Three sections tend to carry most of the weight
+
+Not all sections of a DESIGN.md contribute equally. In practice, three
+sections tend to account for the large majority of the improvement in
+generated output:
+
+- **Overview** — sets the product's overall visual personality. Without
+  it, an agent falls back on generic training-data defaults for anything
+  the tokens don't explicitly cover. A vague overview ("clean and modern")
+  performs about as poorly as no overview at all — it has to be concrete
+  enough to rule things out (e.g. "information-dense, no gradients, no
+  decorative illustration, closer to a financial terminal than a consumer
+  app" rather than "clean and modern").
+- **Colors** — the YAML gives hex values; the prose here is what assigns
+  each color a *role* and a *boundary* ("reserved for interactive
+  elements, never for decorative use or backgrounds"). This is usually
+  where the most direct, traceable cause-and-effect between a prose
+  addition and a corrected output shows up.
+- **Do's and Don'ts** — this is where negative constraints live, and
+  negative constraints ("never use gradients on interactive elements",
+  "no box shadows on cards, use a 1px neutral border instead") tend to be
+  followed more reliably than positively-framed preferences. This section
+  grows best empirically — added to after watching an agent actually get
+  something wrong, not written speculatively up front.
+
+Typography, Layout, Elevation, Components, and Agent Instructions still
+matter, but tend to be secondary to the three above.
+
+## Principles for writing the prose
+
+- **Be specific, not descriptive.** "Minimal aesthetic" gives an agent
+  almost nothing to act on. "Flat design, no gradients, consistent 1px
+  borders in neutral-200, no decorative elements" does.
+- **Explain intent, not just instructions.** A sentence like "this
+  product prioritizes information density over whitespace" generalizes to
+  situations the file never explicitly covers (tighter tables, denser
+  forms) in a way that a fixed instruction can't.
+- **Cover edge cases explicitly.** Empty states, error messages, long
+  text in constrained spaces, multi-line labels — these are exactly where
+  agents guess worst, because nothing in a token list addresses them.
+  A single sentence on what an empty state should contain (a message, an
+  optional subtle illustration, a primary recovery action) tends to fix
+  the pattern for every future generation.
+- **State what should never happen.** Negative, specific constraints
+  ("never appears on backgrounds") outperform positive, general ones
+  ("used for interactive elements") for getting an agent to actually
+  follow the rule consistently.
+- **Keep it concise.** This is a working configuration file competing for
+  space in a finite context window, not a brand book. Effective files
+  tend to land in the range of a couple hundred lines of prose. If a
+  sentence hasn't earned its place by changing an actual output, cut it.
+
+## Process that tends to work
+
+1. Auto-generate a first pass (from Figma exports, existing CSS, or an
+   agent) purely for the YAML token extraction and section scaffolding.
+   Treat the auto-generated prose as a placeholder, not a draft — it
+   reliably has the tokens right and the reasoning missing.
+2. Rewrite the prose yourself, pulling in whoever actually holds the
+   relevant context: a designer for color/typography boundaries, a PM for
+   overall product personality, QA for accessibility and contrast
+   constraints. None of that shows up in an auto-extracted token dump.
+3. Generate real UI with the file in place, watch where the agent gets a
+   decision wrong (not a token wrong), and add the specific constraint
+   that would have prevented it. The Do's and Don'ts section especially
+   should grow from observed failures, not speculation.
+4. Run the structural linter (`designmd_lint` in this MCP server, or
+   `npx @google/design.md lint DESIGN.md` directly) before committing —
+   it catches frontmatter issues and orphaned tokens, though it can't
+   evaluate whether your prose constraints are the right ones.
+5. Bridge it into your existing agent config (CLAUDE.md / AGENTS.md) with
+   one line telling the agent to follow the DESIGN.md for UI generation —
+   DESIGN.md and CLAUDE.md/AGENTS.md are complementary, not overlapping;
+   one covers how to write code, the other covers what the product should
+   look like.
+
+## Known limitations, so expectations stay calibrated
+
+- An agent following a DESIGN.md's prose constraints is not deterministic
+  — expect it to be followed well but not universally, especially on
+  complex, multi-component screens. Review generated output; don't skip
+  that step because a DESIGN.md exists.
+- The format (as of mid-2026) has real gaps around responsive breakpoints
+  and dark-mode tokens — there's no clean standardized way to express
+  either yet.
+- Using a DESIGN.md instead of a purpose-built, codebase-aware MCP tool
+  is not free: in at least one reported production comparison it used
+  meaningfully more LLM processing per task and had more run-to-run
+  variance than a dedicated tool integration. For a small team without
+  that infrastructure already built, a markdown file is still usually the
+  highest-leverage option available; for an organization with an existing
+  component-library-aware tool, that trade-off is worth weighing.