@designtools/docs 0.0.0-stage → 0.1.0

package/src/next/site.ts

@@ -0,0 +1,173 @@
+import type { DocsLink } from "../shell";
+import { findBySlug, readComponents, readTokens, slugOf } from "../lib/manifest";
+import type {
+  AssetsManifest,
+  ComponentEntry,
+  ComponentsManifest,
+  PatternEntry,
+  PatternsManifest,
+  RulesManifest,
+  TaxonomyManifest,
+  TokensManifest,
+} from "../lib/manifest-types";
+import type { BuiltInPage, DocsConfig, EditorialPage } from "./config";
+
+/** The config, read once: the manifest typed and checked, and what is shown. */
+export interface Site {
+  config: DocsConfig;
+  base: string;
+  title: string;
+  components: ComponentsManifest;
+  tokens: TokensManifest;
+  rules: RulesManifest;
+  patterns: PatternsManifest;
+  taxonomy: TaxonomyManifest;
+  assets: AssetsManifest;
+  editorial: EditorialPage[];
+  shows: (page: BuiltInPage) => boolean;
+}
+
+export function siteOf(config: DocsConfig): Site {
+  const hidden = new Set(config.hide ?? []);
+  return {
+    config,
+    base: (config.basePath ?? "/design/system").replace(/\/$/, ""),
+    title: config.title,
+    components: readComponents(config.manifest.components),
+    tokens: readTokens(config.manifest.tokens),
+    rules: (config.manifest.rules as RulesManifest | undefined) ?? ({ rules: [] } as unknown as RulesManifest),
+    patterns: (config.manifest.patterns as PatternsManifest | undefined) ?? ({ patterns: [] } as unknown as PatternsManifest),
+    taxonomy: (config.manifest.taxonomy as TaxonomyManifest | undefined) ?? ({ terms: [] } as unknown as TaxonomyManifest),
+    assets: (config.manifest.assets as AssetsManifest | undefined) ?? ({ assets: [] } as unknown as AssetsManifest),
+    editorial: config.editorial ?? [],
+    shows: (page) => !hidden.has(page),
+  };
+}
+
+/** One page of the docs, by what it shows. */
+export type PageRef =
+  | { kind: "overview" }
+  | { kind: "editorial"; page: EditorialPage }
+  | { kind: "logo" | "imagery" | "voice" | "colour" | "type" | "scale" | "rules" | "standards" | "vocabulary" }
+  | { kind: "component"; entry: ComponentEntry }
+  | { kind: "pattern"; pattern: PatternEntry };
+
+const BUILT_IN: Record<string, Exclude<PageRef["kind"], "overview" | "editorial" | "component" | "pattern">> = {
+  "brand/logo": "logo",
+  "brand/imagery": "imagery",
+  "brand/voice": "voice",
+  colour: "colour",
+  type: "type",
+  scale: "scale",
+  rules: "rules",
+  standards: "standards",
+  vocabulary: "vocabulary",
+};
+
+/** Whether a built-in page has anything to show, as well as not being hidden. */
+function has(site: Site, kind: keyof typeof KIND_NEEDS): boolean {
+  return site.shows(kind as BuiltInPage) && KIND_NEEDS[kind](site);
+}
+
+const KIND_NEEDS = {
+  logo: (s: Site) => s.assets.assets.some((a) => a.kind === "logo"),
+  imagery: (s: Site) => s.assets.assets.some((a) => a.kind !== "logo"),
+  voice: (s: Site) => s.taxonomy.terms.some((t) => t.kind === "product" || t.wrong?.length),
+  colour: () => true,
+  type: () => true,
+  scale: () => true,
+  rules: (s: Site) => s.rules.rules.length > 0,
+  standards: (s: Site) => !!s.config.baselines || !!s.config.adherence,
+  vocabulary: (s: Site) => s.taxonomy.terms.length > 0,
+};
+
+/** The page at a path under the docs, or nothing. */
+export function resolve(site: Site, slug: string[] = []): PageRef | undefined {
+  const path = slug.join("/");
+  if (!path) return { kind: "overview" };
+  const editorial = site.editorial.find((p) => p.slug === path);
+  if (editorial) return { kind: "editorial", page: editorial };
+  const builtIn = BUILT_IN[path];
+  if (builtIn) return has(site, builtIn) ? { kind: builtIn } : undefined;
+  const [section, id] = slug;
+  if (section === "components" && id && site.shows("components")) {
+    const entry = findBySlug(site.components, id);
+    return entry ? { kind: "component", entry } : undefined;
+  }
+  if (section === "patterns" && id && site.shows("patterns")) {
+    const pattern = site.patterns.patterns.find((p) => p.id === id);
+    return pattern ? { kind: "pattern", pattern } : undefined;
+  }
+  return undefined;
+}
+
+/** Every page's path, for static generation. */
+export function allSlugs(site: Site): string[][] {
+  const out: string[][] = [[]];
+  for (const p of site.editorial) out.push(p.slug.split("/"));
+  for (const [path, kind] of Object.entries(BUILT_IN)) if (has(site, kind)) out.push(path.split("/"));
+  if (site.shows("components")) for (const c of site.components.components) out.push(["components", slugOf(c)]);
+  if (site.shows("patterns")) for (const p of site.patterns.patterns) out.push(["patterns", p.id]);
+  return out;
+}
+
+/** The navigation's editorial and generated groups: brand, foundations, standards. Rules, patterns and components the shell adds from the manifest. */
+export function navOf(site: Site): { brand: DocsLink[]; foundations: DocsLink[]; standards: DocsLink[] } {
+  const link = (label: string, path: string) => ({ label, href: `${site.base}/${path}` });
+  const written = (section: EditorialPage["section"]) =>
+    site.editorial.filter((p) => (p.section ?? "brand") === section).map((p) => link(p.nav ?? p.title, p.slug));
+  return {
+    brand: [
+      ...written("brand"),
+      ...(has(site, "logo") ? [link("Logo", "brand/logo")] : []),
+      ...(has(site, "imagery") ? [link("Imagery and icons", "brand/imagery")] : []),
+      ...(has(site, "voice") ? [link("Voice and terms", "brand/voice")] : []),
+    ],
+    foundations: [...written("foundations"), link("Colour", "colour"), link("Type", "type"), link("Scale", "scale")].filter(
+      (l) => !["colour", "type", "scale"].some((k) => l.href.endsWith(`/${k}`) && !site.shows(k as BuiltInPage)),
+    ),
+    standards: [
+      ...written("standards"),
+      ...(has(site, "standards") ? [link("Standards", "standards")] : []),
+      ...(has(site, "vocabulary") ? [link("Vocabulary", "vocabulary")] : []),
+    ],
+  };
+}
+
+/** Each built-in page's title and lead: what the page says it is, which is also its description. */
+export const COPY: Record<Exclude<PageRef["kind"], "overview" | "editorial" | "component" | "pattern">, { title: string; lead: string }> = {
+  logo: { title: "Logo", lead: "Each logo on the surfaces it may sit on, at its smallest, with its clear space." },
+  imagery: { title: "Imagery and icons", lead: "The approved icons and imagery, and how to use each." },
+  voice: { title: "Voice and terms", lead: "The words we use, beside the ones we do not." },
+  colour: {
+    title: "Colour",
+    lead: "Generated from the brand colour by @designtools/tokens. Write the semantic names in components; the ramps are what they point at.",
+  },
+  type: { title: "Type", lead: "Each family, then the scale: a size is never set without its leading." },
+  scale: { title: "Scale", lead: "Space, size, radius, elevation and motion, each drawn the way it is used." },
+  rules: {
+    title: "Rules",
+    lead: "Brand and interface rules in one format, each with the check that proves it. Written for people; agents read the same rule.",
+  },
+  standards: {
+    title: "Standards",
+    lead: "The budgets and targets the project holds itself to, read from .mxa/stack.json, where the checks read them too.",
+  },
+  vocabulary: { title: "Vocabulary", lead: "Every name in the system. Search by a wrong name and it finds the right one." },
+};
+
+/** A page's title and description, for its metadata. */
+export function metaOf(site: Site, ref: PageRef): { title: string; description?: string } {
+  switch (ref.kind) {
+    case "overview":
+      return { title: site.title, description: site.config.lead ?? `${site.title}: the brand and the design system in one place.` };
+    case "editorial":
+      return { title: ref.page.title, description: ref.page.lead };
+    case "component":
+      return { title: `${ref.entry.name} · Components`, description: ref.entry.description };
+    case "pattern":
+      return { title: `${ref.pattern.name} · Patterns`, description: ref.pattern.description };
+    default:
+      return { title: COPY[ref.kind].title, description: COPY[ref.kind].lead };
+  }
+}

package/src/page-actions.tsx

@@ -0,0 +1,92 @@
+"use client";
+
+import { Menu } from "@base-ui/react/menu";
+import { Braces, Check, ChevronDown, Copy, FileText, Files } from "lucide-react";
+import { usePathname } from "next/navigation";
+import { useState } from "react";
+
+/**
+ * What a reader can take from a page, as one split button: copy the page as
+ * markdown, the same markdown any agent gets at `.md`, with a menu beside it to
+ * view that markdown, copy the whole system as one file, or open the manifest.
+ * Put it in a `DocsHeader`.
+ */
+export function PageActions({ basePath = "/design/system" }: { basePath?: string }) {
+  const path = usePathname().replace(/\/$/, "");
+  const [done, setDone] = useState<string | null>(null);
+
+  const copyFrom = async (url: string, what: string) => {
+    try {
+      const res = await fetch(url);
+      if (!res.ok) throw new Error(String(res.status));
+      await navigator.clipboard.writeText(await res.text());
+      setDone(what);
+    } catch {
+      setDone("Could not copy");
+    }
+    setTimeout(() => setDone(null), 1600);
+  };
+
+  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 (
+    <div data-slot="page-actions" className="inline-flex items-stretch rounded-lg border border-border bg-canvas text-sm shadow-xs">
+      <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"
+      >
+        {done === "Page copied" ? <Check aria-hidden className="size-4" /> : <Copy aria-hidden className={icon} />}
+        {done === "Page copied" ? "Copied" : "Copy page"}
+      </button>
+      <Menu.Root>
+        <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"
+        >
+          <ChevronDown aria-hidden className="size-4" />
+        </Menu.Trigger>
+        <Menu.Portal>
+          <Menu.Positioner data-designtools="" align="end" sideOffset={6} className="z-50">
+            <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">
+              <Menu.Item className={item} onClick={() => copyFrom(`${path}.md`, "Page copied")}>
+                <Copy aria-hidden className={icon} />
+                <span className="flex flex-col">
+                  Copy page
+                  <span className="text-xs text-muted-foreground">As markdown, for an assistant</span>
+                </span>
+              </Menu.Item>
+              <Menu.LinkItem className={item} href={`${path}.md`} target="_blank" rel="noreferrer">
+                <FileText aria-hidden className={icon} />
+                <span className="flex flex-col">
+                  View as markdown
+                  <span className="text-xs text-muted-foreground">What an agent reads at this address</span>
+                </span>
+              </Menu.LinkItem>
+              <Menu.Separator className="my-1.5 h-px bg-border" />
+              <Menu.Item className={item} onClick={() => copyFrom(`${basePath}/context.md`, "System copied")}>
+                <Files aria-hidden className={icon} />
+                <span className="flex flex-col">
+                  Copy the whole system
+                  <span className="text-xs text-muted-foreground">Every page in one markdown file</span>
+                </span>
+              </Menu.Item>
+              <Menu.LinkItem className={item} href={`${basePath}/manifest/components.json`} target="_blank" rel="noreferrer">
+                <Braces aria-hidden className={icon} />
+                <span className="flex flex-col">
+                  Open the manifest
+                  <span className="text-xs text-muted-foreground">Components, tokens and rules as JSON</span>
+                </span>
+              </Menu.LinkItem>
+            </Menu.Popup>
+          </Menu.Positioner>
+        </Menu.Portal>
+      </Menu.Root>
+      <span className="sr-only" aria-live="polite">
+        {done ?? ""}
+      </span>
+    </div>
+  );
+}

package/src/pattern.tsx

@@ -0,0 +1,67 @@
+"use client";
+
+import { ArrowUpRight } from "lucide-react";
+import Link from "next/link";
+import { ExampleFrame } from "./examples";
+import { Missing, renderExample, useLookup } from "./lib/lookup";
+import { slugOf } from "./lib/manifest";
+import type { ComponentsManifest, PatternEntry } from "./lib/manifest-types";
+import { StatusBadge } from "./lib/status";
+
+/** A recurring screen composition: what it is made of, then each composition live in its frame, with its code. */
+export function Pattern({
+  pattern,
+  manifest,
+  basePath = "/design/system",
+}: {
+  pattern: PatternEntry;
+  /** To link the components it uses to their pages. */
+  manifest?: ComponentsManifest;
+  basePath?: string;
+}) {
+  const lookup = useLookup();
+  const module = lookup.compositionsFor(pattern);
+  const known = new Map((manifest?.components ?? []).map((c) => [c.name, c]));
+  return (
+    <div data-slot="pattern" className="flex flex-col gap-10">
+      <div className="flex flex-col gap-3 rounded-xl border border-border bg-surface p-4 text-surface-foreground sm:flex-row sm:items-center sm:gap-6">
+        <span className="flex items-center gap-2">
+          <span className="text-xs font-medium text-muted-foreground">Status</span>
+          <StatusBadge status={pattern.status} />
+        </span>
+        {pattern.components.length > 0 && (
+          <span className="flex flex-wrap items-center gap-2">
+            <span className="text-xs font-medium text-muted-foreground">Made of</span>
+            {pattern.components.map((name) => {
+              const c = known.get(name);
+              const chip = "inline-flex min-h-8 items-center gap-1 rounded-full border border-border px-3 text-xs font-medium";
+              return c ? (
+                <Link
+                  key={name}
+                  href={`${basePath}/components/${slugOf(c)}`}
+                  className={`${chip} relative hover:bg-muted focus-visible:outline-2 focus-visible:outline-ring after:absolute after:-inset-y-1.5 after:inset-x-0 after:content-['']`}
+                >
+                  {name}
+                  <ArrowUpRight aria-hidden className="size-3.5 text-muted-foreground" />
+                </Link>
+              ) : (
+                <span key={name} className={chip}>
+                  {name}
+                </span>
+              );
+            })}
+          </span>
+        )}
+      </div>
+      {!module ? (
+        <Missing name={pattern.name} what="compositions" />
+      ) : (
+        pattern.examples.map((ex, i) => (
+          <ExampleFrame key={ex.name} name={ex.name} kind={i === 0 ? "canonical" : "other"} description={ex.description} code={ex.code}>
+            {renderExample(module[ex.name], ex.name)}
+          </ExampleFrame>
+        ))
+      )}
+    </div>
+  );
+}