@designtools/docs 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @designtools/docs
 
+## 0.3.1
+
+### Patch Changes
+
+- design.md is framed for slides, documents and images, not product pages, which are built from the components: its opening, the overview link, the page actions item and the README.
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -108,7 +108,7 @@ editorial: [{
 
 ## design.md
 
-`<basePath>/design.md` is the brand in one file, for anything made outside the repo's components: a page built in another stack, a slide, a document, a prompt to an image tool. `context.md` is for building in the repo, from the components; `design.md` is for everything else, from the values.
+`<basePath>/design.md` is the brand in one file, for what isn't built from the components: a slide, a document, an image, a brief to someone outside the repo. Product pages are built from the components, which carry all of it (`context.md` is the system for building them); `design.md` is for everything else, from the values.
 
 It has two halves. The first is written by people, in the client's voice, and comes from `designMd.body`: what comes first when guidance conflicts, how to work, the reflexes to avoid, what to check before calling it done. The second is generated from the manifest, so it is never stale: each colour role with the text that goes on it as hex in light and dark and their contrast, the hover and pressed shades, the ramps, type in rem and px, corners, the brand assets and their use, every rule with how it's checked, what each component is for, and the words to use and avoid. Without a `body` it still serves, with the values alone and a line saying the first half isn't written.
 

package/dist/lib/design-md.d.ts

@@ -1,13 +1,14 @@
 /**
  * design.md: the brand in one file, for making anything that should look and
- * sound like it outside the repo's components: a page built elsewhere, a slide,
- * a document. Two halves. The first is written by people, in the client's voice:
- * what comes first when guidance conflicts, how to work, the reflexes to avoid,
- * what to check. The second is generated from the manifest, so its values are
- * never stale: colour roles as hex in each mode with their contrast, type,
- * shape, the brand assets, the rules and what each component is for.
+ * sound like it that isn't built from the components: a slide, a document, an
+ * image, a brief to someone outside the repo. Two halves. The first is written
+ * by people, in the client's voice: what comes first when guidance conflicts,
+ * how to work, the reflexes to avoid, what to check. The second is generated
+ * from the manifest, so its values are never stale: colour roles as hex in each
+ * mode with their contrast, type, shape, the brand assets, the rules and what
+ * each component is for.
  *
- * `context.md` is for building in the repo, from the components; this is for
+ * `context.md` is for building the product, from the components; this is for
  * everything else, from the values.
  */
 import type { TokensManifest, AssetEntry, ComponentsManifest, RuleEntry, TermEntry } from "./manifest-types.js";

package/dist/lib/design-md.js

@@ -1,13 +1,14 @@
 /**
  * design.md: the brand in one file, for making anything that should look and
- * sound like it outside the repo's components: a page built elsewhere, a slide,
- * a document. Two halves. The first is written by people, in the client's voice:
- * what comes first when guidance conflicts, how to work, the reflexes to avoid,
- * what to check. The second is generated from the manifest, so its values are
- * never stale: colour roles as hex in each mode with their contrast, type,
- * shape, the brand assets, the rules and what each component is for.
+ * sound like it that isn't built from the components: a slide, a document, an
+ * image, a brief to someone outside the repo. Two halves. The first is written
+ * by people, in the client's voice: what comes first when guidance conflicts,
+ * how to work, the reflexes to avoid, what to check. The second is generated
+ * from the manifest, so its values are never stale: colour roles as hex in each
+ * mode with their contrast, type, shape, the brand assets, the rules and what
+ * each component is for.
  *
- * `context.md` is for building in the repo, from the components; this is for
+ * `context.md` is for building the product, from the components; this is for
  * everything else, from the values.
  */
 import { groupByCategory, ramps, semanticColours, shortName, tokensOfTier, typeScale, valueIn } from "./manifest.js";
@@ -17,8 +18,8 @@ export function designMarkdown({ title, base, provenance, components, tokens, ru
     const out = [`# ${title}: design.md`, ""];
     if (provenance)
         out.push(`> ${provenance}. The first half is written by people; the second is generated from the code.`, "");
-    out.push(`How to make anything in this brand: a page, a slide, a document. The first half is how to think. The second is the exact values, generated from the code, so they are always current. Building in the repo itself? Use the components instead: [the whole system](${base}/context.md).`, "");
-    out.push(body?.trim() || "## How to work\n\nNobody has written this half yet. Until they do, go by the brand pages and the values below.", "");
+    out.push(`How to make slides, documents and images in this brand. The first half is how to think. The second is the exact values, generated from the code, so they are always current. Building the product? Use the components instead, which carry all of this: [the whole system](${base}/context.md).`, "");
+    out.push(body?.trim() || "## How to work\n\nNobody has written this half yet. Until they do, go by the values below.", "");
     if (tokens)
         out.push(colourSection(tokens), typeSection(tokens), shapeSection(tokens));
     if (assets.length)

package/dist/next/config.d.ts

@@ -90,7 +90,7 @@ export interface DocsConfig {
     adherence?: AdherenceReport;
     /**
      * design.md, served at `<base>/design.md`: the brand in one file for anything made outside the repo's
-     * components (a page built elsewhere, a slide, a document). `body` is its hand-written half, in markdown
+     * components: a slide, a document, an image. `body` is its hand-written half, in markdown
      * `##` sections: what comes first when guidance conflicts, how to work, the reflexes to avoid, a review
      * list. The values after it are generated. Without a body the file still serves, with the values alone.
      */

package/dist/next/markdown.js

@@ -45,7 +45,7 @@ export function markdownFor(site, path) {
                 ...groupByCategory(components).flatMap((g) => g.components.map((c) => `- ${g.category}: [${c.name}](${base}/components/${slugOf(c)}.md), ${c.status ?? "status not set"}`)),
                 ...(nav.standards.length ? [`- Standards: ${links(nav.standards)}`] : []),
                 `- Everything in [one file](${base}/context.md)`,
-                `- The brand for work outside the repo, a page, a slide or a document: [design.md](${base}/design.md)`,
+                `- The brand for slides, documents and images, made outside the product: [design.md](${base}/design.md)`,
                 "",
                 manifestLinks(`${base}/manifest`),
             ].join("\n"));

package/dist/next/pages.js

@@ -162,5 +162,5 @@ function Overview({ site }) {
         ["Measured", "A report on every change shows how closely the product follows the system. It informs the conversation; it never blocks the work."],
     ];
     return (_jsxs(_Fragment, { children: [!config.hero && (_jsx(DocsHeader, { title: site.title, lead: config.lead ?? "The brand and the design system in one place, for the people who make the product and the agents that build it with them.", children: _jsx(PageActions, { basePath: base }) })), _jsx(DocsSection, { title: "What's here, and why", lead: "Each part of the system has one job. Together they mean the product, its people and its agents work from the same source.", children: _jsx("ul", { "data-slot": "overview-sections", className: "flex flex-col border-b border-border", children: sections.map((sec) => (_jsx("li", { className: "border-t border-border", children: _jsxs(Link, { href: sec.href, className: "group grid items-baseline gap-x-10 gap-y-2 py-6 focus-visible:outline-2 focus-visible:outline-offset-4 focus-visible:outline-ring md:grid-cols-[13rem_minmax(0,1fr)_auto]", children: [_jsx("span", { className: cx(display, "text-2xl leading-snug tracking-tight underline-offset-4 group-hover:underline"), children: sec.title }), _jsx("span", { className: "max-w-2xl text-base leading-relaxed text-muted-foreground", children: sec.why }), _jsx(ArrowUpRight, { "aria-hidden": true, className: "hidden size-(--dt-size-sm) translate-y-0.5 self-start text-muted-foreground transition duration-(--dt-duration-base) ease-(--dt-ease-out) group-hover:translate-x-1 group-hover:-translate-y-0.5 group-hover:text-canvas-foreground md:mt-1.5 md:block" })] }) }, sec.title))) }) }), config.overview?.agentic !== false && (_jsxs(DocsSection, { title: "Why this is agentic", lead: config.overview?.agenticLead ??
-                    "A design system used to be a document people were asked to follow. This one is the source the product, its people and its AI agents all work from, and it checks itself.", children: [_jsx("ol", { "data-slot": "overview-loop", className: "grid gap-x-6 gap-y-8 sm:grid-cols-2 xl:grid-cols-5", children: loop.map(([title, body], i) => (_jsxs("li", { className: "relative flex flex-col gap-3 xl:pr-2", children: [_jsxs("span", { className: "flex items-center gap-3", children: [_jsx("span", { className: "grid size-8 shrink-0 place-items-center rounded-full bg-canvas-foreground text-sm font-medium text-canvas tabular-nums", children: i + 1 }), i < loop.length - 1 && _jsx("span", { "aria-hidden": true, className: "hidden h-px flex-1 bg-border xl:block" })] }), _jsx("span", { className: "text-lg leading-snug tracking-tight", children: title }), _jsx("span", { className: "text-sm leading-relaxed text-muted-foreground", children: body })] }, title))) }), _jsxs("p", { className: "flex flex-wrap items-center gap-x-2 gap-y-1 text-sm text-muted-foreground", children: ["See it the way an agent does:", _jsxs("a", { href: base ? `${base}.md` : "/.md", className: "inline-flex items-center gap-1 font-medium text-canvas-foreground underline underline-offset-4 hover:decoration-2", children: ["this page as markdown ", _jsx(ArrowUpRight, { "aria-hidden": true, className: "size-3.5" })] }), "or, for a page, slide or document made outside the repo,", _jsxs("a", { href: `${base}/design.md`, className: "inline-flex items-center gap-1 font-medium text-canvas-foreground underline underline-offset-4 hover:decoration-2", children: ["design.md ", _jsx(ArrowUpRight, { "aria-hidden": true, className: "size-3.5" })] })] })] })), _jsx(DocsFooter, { provenance: config.provenance })] }));
+                    "A design system used to be a document people were asked to follow. This one is the source the product, its people and its AI agents all work from, and it checks itself.", children: [_jsx("ol", { "data-slot": "overview-loop", className: "grid gap-x-6 gap-y-8 sm:grid-cols-2 xl:grid-cols-5", children: loop.map(([title, body], i) => (_jsxs("li", { className: "relative flex flex-col gap-3 xl:pr-2", children: [_jsxs("span", { className: "flex items-center gap-3", children: [_jsx("span", { className: "grid size-8 shrink-0 place-items-center rounded-full bg-canvas-foreground text-sm font-medium text-canvas tabular-nums", children: i + 1 }), i < loop.length - 1 && _jsx("span", { "aria-hidden": true, className: "hidden h-px flex-1 bg-border xl:block" })] }), _jsx("span", { className: "text-lg leading-snug tracking-tight", children: title }), _jsx("span", { className: "text-sm leading-relaxed text-muted-foreground", children: body })] }, title))) }), _jsxs("p", { className: "flex flex-wrap items-center gap-x-2 gap-y-1 text-sm text-muted-foreground", children: ["See it the way an agent does:", _jsxs("a", { href: base ? `${base}.md` : "/.md", className: "inline-flex items-center gap-1 font-medium text-canvas-foreground underline underline-offset-4 hover:decoration-2", children: ["this page as markdown ", _jsx(ArrowUpRight, { "aria-hidden": true, className: "size-3.5" })] }), "or, for slides, documents and images,", _jsxs("a", { href: `${base}/design.md`, className: "inline-flex items-center gap-1 font-medium text-canvas-foreground underline underline-offset-4 hover:decoration-2", children: ["design.md ", _jsx(ArrowUpRight, { "aria-hidden": true, className: "size-3.5" })] })] })] })), _jsx(DocsFooter, { provenance: config.provenance })] }));
 }

package/dist/page-actions.js

@@ -29,5 +29,5 @@ export function PageActions({ basePath = "/design/system" }) {
     };
     const item = "flex min-h-(--docs-target,2.75rem) cursor-pointer items-center gap-3 rounded-md px-3 text-sm outline-none select-none data-highlighted:bg-muted";
     const icon = "size-4 shrink-0 text-muted-foreground";
-    return (_jsxs("div", { "data-slot": "page-actions", className: "inline-flex items-stretch rounded-lg border border-border bg-canvas text-sm shadow-xs", children: [_jsxs("button", { type: "button", onClick: () => copyFrom(`${path}.md`, "Page copied"), className: "inline-flex min-h-9 cursor-pointer items-center gap-2 rounded-l-lg py-1.5 pr-3 pl-3 font-medium hover:bg-muted focus-visible:outline-2 focus-visible:outline-ring", children: [done === "Page copied" ? _jsx(Check, { "aria-hidden": true, className: "size-4" }) : _jsx(Copy, { "aria-hidden": true, className: icon }), done === "Page copied" ? "Copied" : "Copy page"] }), _jsxs(Menu.Root, { children: [_jsx(Menu.Trigger, { "aria-label": "More ways to take this page", className: "inline-flex min-h-9 w-9 cursor-pointer items-center justify-center rounded-r-lg border-l border-border text-muted-foreground hover:bg-muted hover:text-canvas-foreground focus-visible:outline-2 focus-visible:outline-ring data-popup-open:bg-muted", children: _jsx(ChevronDown, { "aria-hidden": true, className: "size-4" }) }), _jsx(Menu.Portal, { children: _jsx(Menu.Positioner, { "data-designtools": "", align: "end", sideOffset: 6, className: "z-50", children: _jsxs(Menu.Popup, { className: "w-72 rounded-xl border border-border bg-overlay p-1.5 text-overlay-foreground shadow-lg transition-[opacity,scale] duration-(--dt-duration-fast) data-ending-style:scale-95 data-ending-style:opacity-0 data-starting-style:scale-95 data-starting-style:opacity-0", children: [_jsxs(Menu.Item, { className: item, onClick: () => copyFrom(`${path}.md`, "Page copied"), children: [_jsx(Copy, { "aria-hidden": true, className: icon }), _jsxs("span", { className: "flex flex-col", children: ["Copy page", _jsx("span", { className: "text-xs text-muted-foreground", children: "As markdown, for an assistant" })] })] }), _jsxs(Menu.LinkItem, { className: item, href: `${path}.md`, target: "_blank", rel: "noreferrer", children: [_jsx(FileText, { "aria-hidden": true, className: icon }), _jsxs("span", { className: "flex flex-col", children: ["View as markdown", _jsx("span", { className: "text-xs text-muted-foreground", children: "What an agent reads at this address" })] })] }), _jsx(Menu.Separator, { className: "my-1.5 h-px bg-border" }), _jsxs(Menu.Item, { className: item, onClick: () => copyFrom(`${basePath}/context.md`, "System copied"), children: [_jsx(Files, { "aria-hidden": true, className: icon }), _jsxs("span", { className: "flex flex-col", children: ["Copy the whole system", _jsx("span", { className: "text-xs text-muted-foreground", children: "Every page in one markdown file" })] })] }), _jsxs(Menu.Item, { className: item, onClick: () => copyFrom(`${basePath}/design.md`, "design.md copied"), children: [_jsx(Palette, { "aria-hidden": true, className: icon }), _jsxs("span", { className: "flex flex-col", children: ["Copy design.md", _jsx("span", { className: "text-xs text-muted-foreground", children: "The brand for a page, slide or document made elsewhere" })] })] }), _jsxs(Menu.LinkItem, { className: item, href: `${basePath}/manifest/components.json`, target: "_blank", rel: "noreferrer", children: [_jsx(Braces, { "aria-hidden": true, className: icon }), _jsxs("span", { className: "flex flex-col", children: ["Open the manifest", _jsx("span", { className: "text-xs text-muted-foreground", children: "Components, tokens and rules as JSON" })] })] })] }) }) })] }), _jsx("span", { className: "sr-only", "aria-live": "polite", children: done ?? "" })] }));
+    return (_jsxs("div", { "data-slot": "page-actions", className: "inline-flex items-stretch rounded-lg border border-border bg-canvas text-sm shadow-xs", children: [_jsxs("button", { type: "button", onClick: () => copyFrom(`${path}.md`, "Page copied"), className: "inline-flex min-h-9 cursor-pointer items-center gap-2 rounded-l-lg py-1.5 pr-3 pl-3 font-medium hover:bg-muted focus-visible:outline-2 focus-visible:outline-ring", children: [done === "Page copied" ? _jsx(Check, { "aria-hidden": true, className: "size-4" }) : _jsx(Copy, { "aria-hidden": true, className: icon }), done === "Page copied" ? "Copied" : "Copy page"] }), _jsxs(Menu.Root, { children: [_jsx(Menu.Trigger, { "aria-label": "More ways to take this page", className: "inline-flex min-h-9 w-9 cursor-pointer items-center justify-center rounded-r-lg border-l border-border text-muted-foreground hover:bg-muted hover:text-canvas-foreground focus-visible:outline-2 focus-visible:outline-ring data-popup-open:bg-muted", children: _jsx(ChevronDown, { "aria-hidden": true, className: "size-4" }) }), _jsx(Menu.Portal, { children: _jsx(Menu.Positioner, { "data-designtools": "", align: "end", sideOffset: 6, className: "z-50", children: _jsxs(Menu.Popup, { className: "w-72 rounded-xl border border-border bg-overlay p-1.5 text-overlay-foreground shadow-lg transition-[opacity,scale] duration-(--dt-duration-fast) data-ending-style:scale-95 data-ending-style:opacity-0 data-starting-style:scale-95 data-starting-style:opacity-0", children: [_jsxs(Menu.Item, { className: item, onClick: () => copyFrom(`${path}.md`, "Page copied"), children: [_jsx(Copy, { "aria-hidden": true, className: icon }), _jsxs("span", { className: "flex flex-col", children: ["Copy page", _jsx("span", { className: "text-xs text-muted-foreground", children: "As markdown, for an assistant" })] })] }), _jsxs(Menu.LinkItem, { className: item, href: `${path}.md`, target: "_blank", rel: "noreferrer", children: [_jsx(FileText, { "aria-hidden": true, className: icon }), _jsxs("span", { className: "flex flex-col", children: ["View as markdown", _jsx("span", { className: "text-xs text-muted-foreground", children: "What an agent reads at this address" })] })] }), _jsx(Menu.Separator, { className: "my-1.5 h-px bg-border" }), _jsxs(Menu.Item, { className: item, onClick: () => copyFrom(`${basePath}/context.md`, "System copied"), children: [_jsx(Files, { "aria-hidden": true, className: icon }), _jsxs("span", { className: "flex flex-col", children: ["Copy the whole system", _jsx("span", { className: "text-xs text-muted-foreground", children: "Every page in one markdown file" })] })] }), _jsxs(Menu.Item, { className: item, onClick: () => copyFrom(`${basePath}/design.md`, "design.md copied"), children: [_jsx(Palette, { "aria-hidden": true, className: icon }), _jsxs("span", { className: "flex flex-col", children: ["Copy design.md", _jsx("span", { className: "text-xs text-muted-foreground", children: "The brand for slides, documents and images" })] })] }), _jsxs(Menu.LinkItem, { className: item, href: `${basePath}/manifest/components.json`, target: "_blank", rel: "noreferrer", children: [_jsx(Braces, { "aria-hidden": true, className: icon }), _jsxs("span", { className: "flex flex-col", children: ["Open the manifest", _jsx("span", { className: "text-xs text-muted-foreground", children: "Components, tokens and rules as JSON" })] })] })] }) }) })] }), _jsx("span", { className: "sr-only", "aria-live": "polite", children: done ?? "" })] }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@designtools/docs",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Design system docs as a package: pages, navigation, search, a workbench per component, rules, patterns, brand pages and markdown for agents, generated from the @designtools/manifest and themed by your tokens. One Next adapter serves them inside your app or as a standalone site.",
   "type": "module",
   "license": "MIT",

package/src/lib/design-md.ts

@@ -1,13 +1,14 @@
 /**
  * design.md: the brand in one file, for making anything that should look and
- * sound like it outside the repo's components: a page built elsewhere, a slide,
- * a document. Two halves. The first is written by people, in the client's voice:
- * what comes first when guidance conflicts, how to work, the reflexes to avoid,
- * what to check. The second is generated from the manifest, so its values are
- * never stale: colour roles as hex in each mode with their contrast, type,
- * shape, the brand assets, the rules and what each component is for.
+ * sound like it that isn't built from the components: a slide, a document, an
+ * image, a brief to someone outside the repo. Two halves. The first is written
+ * by people, in the client's voice: what comes first when guidance conflicts,
+ * how to work, the reflexes to avoid, what to check. The second is generated
+ * from the manifest, so its values are never stale: colour roles as hex in each
+ * mode with their contrast, type, shape, the brand assets, the rules and what
+ * each component is for.
  *
- * `context.md` is for building in the repo, from the components; this is for
+ * `context.md` is for building the product, from the components; this is for
  * everything else, from the values.
  */
 
@@ -34,11 +35,11 @@ export function designMarkdown({ title, base, provenance, components, tokens, ru
   const out = [`# ${title}: design.md`, ""];
   if (provenance) out.push(`> ${provenance}. The first half is written by people; the second is generated from the code.`, "");
   out.push(
-    `How to make anything in this brand: a page, a slide, a document. The first half is how to think. The second is the exact values, generated from the code, so they are always current. Building in the repo itself? Use the components instead: [the whole system](${base}/context.md).`,
+    `How to make slides, documents and images in this brand. The first half is how to think. The second is the exact values, generated from the code, so they are always current. Building the product? Use the components instead, which carry all of this: [the whole system](${base}/context.md).`,
     "",
   );
 
-  out.push(body?.trim() || "## How to work\n\nNobody has written this half yet. Until they do, go by the brand pages and the values below.", "");
+  out.push(body?.trim() || "## How to work\n\nNobody has written this half yet. Until they do, go by the values below.", "");
 
   if (tokens) out.push(colourSection(tokens), typeSection(tokens), shapeSection(tokens));
   if (assets.length) out.push(assetsMarkdown(assets));

package/src/next/config.ts

@@ -87,7 +87,7 @@ export interface DocsConfig {
   adherence?: AdherenceReport;
   /**
    * design.md, served at `<base>/design.md`: the brand in one file for anything made outside the repo's
-   * components (a page built elsewhere, a slide, a document). `body` is its hand-written half, in markdown
+   * components: a slide, a document, an image. `body` is its hand-written half, in markdown
    * `##` sections: what comes first when guidance conflicts, how to work, the reflexes to avoid, a review
    * list. The values after it are generated. Without a body the file still serves, with the values alone.
    */

package/src/next/markdown.ts

@@ -65,7 +65,7 @@ export function markdownFor(site: Site, path: string): string | undefined {
           ),
           ...(nav.standards.length ? [`- Standards: ${links(nav.standards)}`] : []),
           `- Everything in [one file](${base}/context.md)`,
-          `- The brand for work outside the repo, a page, a slide or a document: [design.md](${base}/design.md)`,
+          `- The brand for slides, documents and images, made outside the product: [design.md](${base}/design.md)`,
           "",
           manifestLinks(`${base}/manifest`),
         ].join("\n"),

package/src/next/pages.tsx

@@ -412,7 +412,7 @@ function Overview({ site }: { site: Site }) {
             <a href={base ? `${base}.md` : "/.md"} className="inline-flex items-center gap-1 font-medium text-canvas-foreground underline underline-offset-4 hover:decoration-2">
               this page as markdown <ArrowUpRight aria-hidden className="size-3.5" />
             </a>
-            or, for a page, slide or document made outside the repo,
+            or, for slides, documents and images,
             <a href={`${base}/design.md`} className="inline-flex items-center gap-1 font-medium text-canvas-foreground underline underline-offset-4 hover:decoration-2">
               design.md <ArrowUpRight aria-hidden className="size-3.5" />
             </a>

package/src/page-actions.tsx

@@ -78,7 +78,7 @@ export function PageActions({ basePath = "/design/system" }: { basePath?: string
                 <Palette aria-hidden className={icon} />
                 <span className="flex flex-col">
                   Copy design.md
-                  <span className="text-xs text-muted-foreground">The brand for a page, slide or document made elsewhere</span>
+                  <span className="text-xs text-muted-foreground">The brand for slides, documents and images</span>
                 </span>
               </Menu.Item>
               <Menu.LinkItem className={item} href={`${basePath}/manifest/components.json`} target="_blank" rel="noreferrer">