@designtools/docs 0.0.0-stage → 0.1.0

package/dist/lib/manifest-types.d.ts

@@ -0,0 +1,253 @@
+/**
+ * The manifest schema: what `designtools-manifest build` writes to
+ * `<system>/manifest/`: components.json, tokens.json, rules.json,
+ * patterns.json, taxonomy.json and assets.json.
+ *
+ * This file has no imports on purpose. @designtools/docs carries a byte-identical
+ * copy, so a project's docs read the manifest through the same types the tool
+ * wrote it with, and a test in this repo fails if the two drift.
+ *
+ * Every path is relative to the project root, with forward slashes. Arrays keep
+ * source order where order means something (variant axes, fixture states, token
+ * ramps); everything else is sorted, so a diff of the files shows only real changes.
+ */
+export declare const MANIFEST_SCHEMA = "designtools.manifest/1";
+/** What every manifest file opens with. */
+interface ManifestFile {
+    /** `@designtools/manifest@<version>`, so `check` can tell a tool upgrade from an edit. */
+    generator: string;
+    schema: string;
+}
+/** components.json */
+export interface ComponentsManifest extends ManifestFile {
+    /** The system folder the components were read from. */
+    system: string;
+    /** Sorted by name, then source. */
+    components: ComponentEntry[];
+}
+export interface ComponentEntry {
+    /** The export name, or `@name` when the JSDoc gives one. */
+    name: string;
+    /** The exported identifier to import. Equals `name` unless `@name` renamed it. */
+    export: string;
+    /** The file that exports it. */
+    source: string;
+    /**
+     * The module specifier an app imports it by, through the tsconfig path alias
+     * that reaches the system folder (`@ds/button/button`). Absent when no alias does,
+     * in which case `source` is the only honest answer.
+     */
+    import?: string;
+    /** The component's JSDoc, or its variant config's when the component has none. */
+    description?: string;
+    /** `@category`. Blocks group components without one under "Components". */
+    category?: string;
+    /** `@status`, or `deprecated` from `@deprecated`. Absent until someone decides it. */
+    status?: Status;
+    /** Why it has that status: the `@deprecated` reason, or text after `@status`. */
+    statusNote?: string;
+    /** `@use`, `@avoid`, `@instead`: when to reach for it, when not, and what instead. */
+    usage?: Usage;
+    /** `@example` snippets in the JSDoc, each one JSX. */
+    snippets?: string[];
+    /** `@see`, each one a link or a component name. */
+    see?: string[];
+    /** `@primitive`: the primitive it wraps, as a link or a package path. */
+    primitive?: string;
+    /** `@aria`: the ARIA pattern it follows, usually a link. */
+    aria?: string;
+    /** `@role` and `@keyboard`: what assistive technology meets, and the keys it answers. */
+    a11y?: {
+        role?: string;
+        keyboard?: string[];
+    };
+    /** `@replaces`: raw elements this component stands in for, which the adherence report counts. */
+    replaces?: string[];
+    /**
+     * What it also accepts beyond its own props: an intrinsic element (`"span"`)
+     * or a wrapped primitive (`"@base-ui/react/select:Root"`).
+     */
+    inherits?: string[];
+    /** Its own props, and those of a primitive it wraps. Inherited DOM props are left out. */
+    props: Record<string, PropEntry>;
+    /** Absent when it has no variants by any route. */
+    variants?: VariantsEntry;
+    /** Every `data-slot` it renders, sorted. */
+    slots: string[];
+    /** Absent when the component has no examples file. */
+    examples?: ExamplesEntry;
+}
+export type Status = "stable" | "emerging" | "deprecated";
+export interface Usage {
+    use?: string;
+    avoid?: string;
+    /** Components, or other things, to use instead. */
+    instead?: string[];
+}
+export interface PropEntry {
+    /** The type as written or resolved, e.g. `string`, `"sm" | "md"`, `(v: string) => void`. */
+    type: string;
+    /** Present when the type is a union of literals: each value, unquoted. */
+    values?: string[];
+    required: boolean;
+    /** The default, as source text, when the component destructures one. */
+    default?: string;
+    description?: string;
+    deprecated?: string;
+    /** The package that declares it, when it comes from a wrapped primitive rather than the project. */
+    from?: string;
+}
+export interface VariantsEntry {
+    /** Where the axes came from: a `tv()` or `cva()` config, or the props' literal union types. */
+    from: "tv" | "cva" | "props";
+    /** The config's variable name. Absent when `from` is `"props"`. */
+    config?: string;
+    /** Source order. */
+    axes: VariantAxis[];
+    /** Conditions only, without their classes, in source order. */
+    compound?: Record<string, string | string[]>[];
+    /** A `tv()` config's named parts, in source order. */
+    parts?: string[];
+}
+export interface VariantAxis {
+    name: string;
+    /** Source order. */
+    options: VariantOption[];
+    default?: string;
+}
+export interface VariantOption {
+    name: string;
+    description?: string;
+}
+/**
+ * A co-located `*.examples.tsx`: `canonical` is the one to copy, `do*` and
+ * `dont*` render as pairs in order, anything else is a further example.
+ */
+export interface ExamplesEntry {
+    source: string;
+    canonical?: ExampleRef;
+    do: ExampleRef[];
+    dont: ExampleRef[];
+    other: ExampleRef[];
+}
+export interface ExampleRef {
+    /** The export name. */
+    name: string;
+    /** Its JSDoc: why to do it, or why not. */
+    description?: string;
+    /** The JSX it returns, as written, for agents and code views. */
+    code?: string;
+}
+/** tokens.json */
+export interface TokensManifest extends ManifestFile {
+    /** The stylesheets read, in the order given. */
+    sources: string[];
+    /** Source order: file by file, declaration by declaration. */
+    tokens: TokenEntry[];
+}
+export type TokenTier = "color" | "font" | "font-weight" | "text" | "leading" | "tracking" | "spacing" | "size" | "radius" | "shadow" | "ease" | "duration" | "motion" | "breakpoint" | "container" | "other";
+export interface TokenEntry {
+    /** The custom property, with its dashes: `--color-primary-500`. */
+    name: string;
+    tier: TokenTier;
+    /**
+     * The value in each context it is declared in. `default` is `@theme` or `:root`;
+     * `light` and `dark` are the mode blocks; a `p3:` prefix marks the
+     * `@media (color-gamut: p3)` layer. Any other selector is kept as written.
+     */
+    values: Record<string, string>;
+    /** The comment above it, or above the run of declarations it belongs to. */
+    description?: string;
+    /** The stylesheet that first declares it. */
+    source: string;
+    /** Later stylesheets whose declaration replaced a value, in the order read: an override layer. */
+    overriddenIn?: string[];
+}
+/** rules.json: brand and interface rules in one format. */
+export interface RulesManifest extends ManifestFile {
+    /** Sorted by id. */
+    rules: RuleEntry[];
+}
+export interface RuleEntry {
+    /** The file name without `.rule.json`, used as its anchor: `touch-target`. */
+    id: string;
+    kind: "brand" | "interface";
+    title: string;
+    /** The rule, in one or two sentences, for people first. */
+    statement: string;
+    /** Why it exists. */
+    rationale?: string;
+    /** The measurable line, e.g. `44 × 44 CSS px`. */
+    threshold?: string;
+    /** Components, elements, assets or pages it governs. */
+    appliesTo?: string[];
+    exceptions?: string[];
+    /** Tokens it rests on, e.g. `--size-2xl`. */
+    tokens?: string[];
+    /**
+     * Confirmed with the client, an assumption still to confirm, or measured: generated from the
+     * tokens (where a colour can be text), a fact that changes when they do, not a decision.
+     */
+    status: "confirmed" | "assumption" | "measured";
+    /** How it is proved: a test, a lint rule, an audit, or a person. */
+    check?: {
+        kind: "test" | "lint" | "audit" | "manual";
+        ref?: string;
+        description?: string;
+    };
+    source: string;
+}
+/** patterns.json: the product's recurring screen compositions. */
+export interface PatternsManifest extends ManifestFile {
+    /** Sorted by name. */
+    patterns: PatternEntry[];
+}
+export interface PatternEntry {
+    /** From the file name: `checkout` for `checkout.pattern.tsx`. */
+    id: string;
+    name: string;
+    description?: string;
+    status?: Status;
+    /** The system components it imports, by name, sorted. */
+    components: string[];
+    /** Each named export is a composition, in source order. */
+    examples: ExampleRef[];
+    source: string;
+}
+/** taxonomy.json: one vocabulary, with the wrong forms to avoid. */
+export interface TaxonomyManifest extends ManifestFile {
+    /** Sorted by name. */
+    terms: TermEntry[];
+}
+export interface TermEntry {
+    /** The canonical form. */
+    name: string;
+    kind: "component" | "variant" | "token" | "pattern" | "rule" | "product";
+    /** Known wrong forms: `error` for `destructive`, `Modal` for `Dialog`, "log in" for "sign in". */
+    wrong?: string[];
+    note?: string;
+    /** Where it is defined: a component's source, a token's name, a rule's id. */
+    ref?: string;
+}
+/** assets.json: logos, icons and imagery, with how to use them. */
+export interface AssetsManifest extends ManifestFile {
+    /** Sorted by file. */
+    assets: AssetEntry[];
+}
+export interface AssetEntry {
+    file: string;
+    kind: "logo" | "icon" | "image" | "other";
+    name: string;
+    usage?: string;
+    /** e.g. `24px tall` */
+    minSize?: string;
+    /** e.g. `the height of the wordmark's x` or a length */
+    clearSpace?: string;
+    /** Surfaces it may sit on, as semantic colour names: `canvas`, `primary`. */
+    surfaces?: string[];
+    alt?: string;
+    /** Intrinsic size, read from an SVG's viewBox or a PNG's header. */
+    width?: number;
+    height?: number;
+}
+export {};

package/dist/lib/manifest-types.js

@@ -0,0 +1,14 @@
+/**
+ * The manifest schema: what `designtools-manifest build` writes to
+ * `<system>/manifest/`: components.json, tokens.json, rules.json,
+ * patterns.json, taxonomy.json and assets.json.
+ *
+ * This file has no imports on purpose. @designtools/docs carries a byte-identical
+ * copy, so a project's docs read the manifest through the same types the tool
+ * wrote it with, and a test in this repo fails if the two drift.
+ *
+ * Every path is relative to the project root, with forward slashes. Arrays keep
+ * source order where order means something (variant axes, fixture states, token
+ * ramps); everything else is sorted, so a diff of the files shows only real changes.
+ */
+export const MANIFEST_SCHEMA = "designtools.manifest/1";

package/dist/lib/manifest.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Reading the manifest: grouping components for navigation, and sorting tokens
+ * into the shapes the token blocks draw (semantic pairs, ramps, a type scale).
+ * Pure functions over the JSON; nothing here touches the DOM.
+ */
+import { type ComponentEntry, type ComponentsManifest, type TokenEntry, type TokenTier, type TokensManifest } from "./manifest-types.js";
+/**
+ * A `components.json` import, typed and checked. A JSON import is typed by its
+ * literal contents, which do not line up with the schema, so read it through here.
+ */
+export declare function readComponents(json: unknown): ComponentsManifest;
+/** A `tokens.json` import, typed and checked. */
+export declare function readTokens(json: unknown): TokensManifest;
+/** Where components without `@category` are listed. */
+export declare const DEFAULT_CATEGORY = "Components";
+/** The key the generated registry files a component under: `src/ds/badge/badge.tsx#Badge`. */
+export declare function componentKey(entry: Pick<ComponentEntry, "source" | "export">): string;
+/** `RadioGroup` → `radio-group`, for URLs. */
+/**
+ * What an app writes to import it: the alias the manifest found (`@ds/button/button`),
+ * or the file's path when no alias reaches the system folder.
+ */
+export declare function importOf(entry: Pick<ComponentEntry, "import" | "source">): string;
+export declare function slugOf(entry: Pick<ComponentEntry, "name">): string;
+export declare function findBySlug(manifest: ComponentsManifest, slug: string): ComponentEntry | undefined;
+export interface CategoryGroup {
+    category: string;
+    components: ComponentEntry[];
+}
+/**
+ * Categories in name order, uncategorised last; components by name within each.
+ * A part without its own `@category` (CardHeader) joins the category of a
+ * component in the same file (Card), so a family stays together.
+ */
+export declare function groupByCategory(manifest: ComponentsManifest): CategoryGroup[];
+export interface Family {
+    /** The component with the `@category`: Card. */
+    head: ComponentEntry;
+    /** The rest of its file, which has none of its own: CardHeader, CardTitle. */
+    parts: ComponentEntry[];
+}
+/**
+ * Each category's components with their parts folded under them, so a reader
+ * sees nine components rather than fourteen pages. A part is a component with
+ * no `@category` of its own in a file whose first categorised component heads it.
+ */
+export declare function groupFamilies(manifest: ComponentsManifest): {
+    category: string;
+    families: Family[];
+}[];
+export declare function tokensOfTier(manifest: TokensManifest, tier: TokenTier): TokenEntry[];
+export type Mode = "light" | "dark";
+/** A token's value in a mode, falling back to its mode-invariant value. */
+export declare function valueIn(token: TokenEntry, mode: Mode): string | undefined;
+export interface Ramp {
+    /** `primary` for `--color-primary-500`. */
+    family: string;
+    steps: {
+        step: string;
+        token: TokenEntry;
+    }[];
+}
+/** `--color-<family>-<step>` primitives, families in source order, steps as declared. */
+export declare function ramps(manifest: TokensManifest): Ramp[];
+export interface SemanticColour {
+    /** `--primary` */
+    name: string;
+    background: TokenEntry;
+    /** `--primary-foreground`, when the generator paired one. */
+    foreground?: TokenEntry;
+}
+/**
+ * Semantic colours (unprefixed, mode-aware: `--primary`, `--canvas`), each with
+ * its foreground when it has one. The `--color-*` bridge that points Tailwind
+ * at them is left out: it is the same colour under a second name.
+ */
+export declare function semanticColours(manifest: TokensManifest): SemanticColour[];
+export interface TypeStep {
+    /** `--text-sm` */
+    name: string;
+    size: TokenEntry;
+    lineHeight?: TokenEntry;
+    letterSpacing?: TokenEntry;
+    fontWeight?: TokenEntry;
+}
+/** `--text-*` sizes with the `--text-*--line-height` (and tracking, weight) Tailwind pairs with them. */
+export declare function typeScale(manifest: TokensManifest): TypeStep[];
+/** `--radius-md` → `md`; `--spacing` → `spacing`. */
+export declare function shortName(token: Pick<TokenEntry, "name">, prefix?: string): string;
+/**
+ * Descriptions run over several tokens (one comment above a group), so show a
+ * description only where it changes.
+ */
+export declare function withGroupDescriptions<T extends {
+    description?: string;
+}>(items: T[]): (T & {
+    groupDescription?: string;
+})[];

package/dist/lib/manifest.js

@@ -0,0 +1,173 @@
+/**
+ * Reading the manifest: grouping components for navigation, and sorting tokens
+ * into the shapes the token blocks draw (semantic pairs, ramps, a type scale).
+ * Pure functions over the JSON; nothing here touches the DOM.
+ */
+import { MANIFEST_SCHEMA, } from "./manifest-types.js";
+/**
+ * A `components.json` import, typed and checked. A JSON import is typed by its
+ * literal contents, which do not line up with the schema, so read it through here.
+ */
+export function readComponents(json) {
+    checkSchema(json, "components.json");
+    return json;
+}
+/** A `tokens.json` import, typed and checked. */
+export function readTokens(json) {
+    checkSchema(json, "tokens.json");
+    return json;
+}
+function checkSchema(json, file) {
+    const schema = json?.schema;
+    if (schema !== MANIFEST_SCHEMA) {
+        throw new Error(`${file} has schema ${String(schema)}; these blocks read schema ${MANIFEST_SCHEMA}. Rebuild it with a matching @designtools/manifest.`);
+    }
+}
+/** Where components without `@category` are listed. */
+export const DEFAULT_CATEGORY = "Components";
+/** The key the generated registry files a component under: `src/ds/badge/badge.tsx#Badge`. */
+export function componentKey(entry) {
+    return `${entry.source}#${entry.export}`;
+}
+/** `RadioGroup` → `radio-group`, for URLs. */
+/**
+ * What an app writes to import it: the alias the manifest found (`@ds/button/button`),
+ * or the file's path when no alias reaches the system folder.
+ */
+export function importOf(entry) {
+    return entry.import ?? entry.source.replace(/\.(tsx?|jsx?)$/, "");
+}
+export function slugOf(entry) {
+    return entry.name
+        .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+        .replace(/[^A-Za-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "")
+        .toLowerCase();
+}
+export function findBySlug(manifest, slug) {
+    return manifest.components.find((c) => slugOf(c) === slug);
+}
+/**
+ * Categories in name order, uncategorised last; components by name within each.
+ * A part without its own `@category` (CardHeader) joins the category of a
+ * component in the same file (Card), so a family stays together.
+ */
+export function groupByCategory(manifest) {
+    const fileCategory = new Map();
+    for (const c of manifest.components)
+        if (c.category && !fileCategory.has(c.source))
+            fileCategory.set(c.source, c.category);
+    const groups = new Map();
+    for (const c of manifest.components) {
+        const key = c.category ?? fileCategory.get(c.source) ?? DEFAULT_CATEGORY;
+        groups.set(key, [...(groups.get(key) ?? []), c]);
+    }
+    return [...groups.entries()]
+        .sort(([a], [b]) => (a === DEFAULT_CATEGORY ? 1 : b === DEFAULT_CATEGORY ? -1 : a < b ? -1 : a > b ? 1 : 0))
+        .map(([category, components]) => ({ category, components }));
+}
+/**
+ * Each category's components with their parts folded under them, so a reader
+ * sees nine components rather than fourteen pages. A part is a component with
+ * no `@category` of its own in a file whose first categorised component heads it.
+ */
+export function groupFamilies(manifest) {
+    return groupByCategory(manifest).map(({ category, components }) => {
+        const families = [];
+        const heads = new Map();
+        for (const c of components) {
+            const head = heads.get(c.source);
+            if (head && !c.category) {
+                head.parts.push(c);
+                continue;
+            }
+            const family = { head: c, parts: [] };
+            families.push(family);
+            if (c.category && !heads.has(c.source))
+                heads.set(c.source, family);
+        }
+        // a part whose name sorts before its head's was listed before the head was known: it joins it now
+        const kept = families.filter((f) => {
+            const head = heads.get(f.head.source);
+            if (!head || head === f || f.head.category)
+                return true;
+            head.parts.push(f.head);
+            return false;
+        });
+        for (const f of kept)
+            f.parts.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+        return { category, families: kept };
+    });
+}
+export function tokensOfTier(manifest, tier) {
+    return manifest.tokens.filter((t) => t.tier === tier);
+}
+/** A token's value in a mode, falling back to its mode-invariant value. */
+export function valueIn(token, mode) {
+    return token.values[mode] ?? token.values.default;
+}
+/** `--color-<family>-<step>` primitives, families in source order, steps as declared. */
+export function ramps(manifest) {
+    const out = new Map();
+    for (const t of manifest.tokens) {
+        const m = /^--color-([a-z][\w-]*?)-(\d+)$/.exec(t.name);
+        if (!m)
+            continue;
+        const ramp = out.get(m[1]) ?? { family: m[1], steps: [] };
+        ramp.steps.push({ step: m[2], token: t });
+        out.set(m[1], ramp);
+    }
+    return [...out.values()];
+}
+/**
+ * Semantic colours (unprefixed, mode-aware: `--primary`, `--canvas`), each with
+ * its foreground when it has one. The `--color-*` bridge that points Tailwind
+ * at them is left out: it is the same colour under a second name.
+ */
+export function semanticColours(manifest) {
+    const colours = manifest.tokens.filter((t) => t.tier === "color" && !t.name.startsWith("--color-"));
+    const byName = new Map(colours.map((t) => [t.name, t]));
+    return colours
+        .filter((t) => !t.name.endsWith("-foreground"))
+        .map((background) => {
+        const foreground = byName.get(`${background.name}-foreground`);
+        return foreground ? { name: background.name, background, foreground } : { name: background.name, background };
+    });
+}
+/** `--text-*` sizes with the `--text-*--line-height` (and tracking, weight) Tailwind pairs with them. */
+export function typeScale(manifest) {
+    const text = tokensOfTier(manifest, "text");
+    const byName = new Map(text.map((t) => [t.name, t]));
+    return text
+        .filter((t) => !t.name.includes("--", 2) && !/shadow/.test(t.name))
+        .map((size) => {
+        const step = { name: size.name, size };
+        const lh = byName.get(`${size.name}--line-height`);
+        const ls = byName.get(`${size.name}--letter-spacing`);
+        const fw = byName.get(`${size.name}--font-weight`);
+        if (lh)
+            step.lineHeight = lh;
+        if (ls)
+            step.letterSpacing = ls;
+        if (fw)
+            step.fontWeight = fw;
+        return step;
+    });
+}
+/** `--radius-md` → `md`; `--spacing` → `spacing`. */
+export function shortName(token, prefix) {
+    const name = token.name.replace(/^--/, "");
+    return prefix && name.startsWith(`${prefix}-`) ? name.slice(prefix.length + 1) : name;
+}
+/**
+ * Descriptions run over several tokens (one comment above a group), so show a
+ * description only where it changes.
+ */
+export function withGroupDescriptions(items) {
+    let last;
+    return items.map((item) => {
+        const changed = item.description !== last;
+        last = item.description;
+        return changed && item.description ? { ...item, groupDescription: item.description } : item;
+    });
+}

package/dist/lib/markdown.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The markdown form of every block, generated from the manifest rather than
+ * converted from HTML, so the same manifest always gives the same markdown.
+ * A docs page answers `Accept: text/markdown` (or `.md`) with these; the agent
+ * tabs show them; copy-page copies them.
+ *
+ * Structure survives as typed fences (```rule, ```example, ```do, ```dont) so
+ * an agent can tell what each part is. Status travels with everything.
+ */
+import { slugOf } from "./manifest.js";
+import type { AdherenceReport } from "./adherence-types.js";
+import type { AssetEntry, ComponentEntry, ComponentsManifest, PatternEntry, RuleEntry, TermEntry, TokensManifest } from "./manifest-types.js";
+/** A generated page: the system version and commit it came from. Never a review date, which would be invented. */
+export declare function generatedHeader(provenance: string): string;
+/** An editorial page: who wrote it, when it was last reviewed, and whether it is settled. */
+export declare function editorialHeader({ author, reviewer, reviewed, status }: {
+    author: string;
+    reviewer?: string;
+    reviewed: string;
+    status: "draft" | "published";
+}): string;
+/**
+ * A component as an agent reads it. `level` is its heading's: 1 when it is the
+ * whole page (`/components/button.md`), 2 inside a longer document (`context.md`),
+ * so a page never opens with the same heading twice.
+ */
+export declare function componentMarkdown(entry: ComponentEntry, level?: 1 | 2): string;
+export declare function coloursMarkdown(tokens: TokensManifest): string;
+export declare function typeMarkdown(tokens: TokensManifest): string;
+export declare function scaleMarkdown(tokens: TokensManifest): string;
+export declare function ruleMarkdown(rule: RuleEntry): string;
+/** A pattern; `level` as for `componentMarkdown`. */
+export declare function patternMarkdown(pattern: PatternEntry, level?: 1 | 2): string;
+export declare function glossaryMarkdown(terms: TermEntry[]): string;
+export declare function assetsMarkdown(assets: AssetEntry[]): string;
+/** `.mxa/stack.json` baselines, or anything shaped like them: a table of name and target. */
+export declare function standardsMarkdown(baselines: Record<string, unknown>): string;
+/** The adherence report, as a page: totals, then routes. It informs; it never blocks. */
+export declare function adherenceMarkdown(report: AdherenceReport): string;
+/** Everything an agent needs, in one file: tokens first, then rules, patterns and components by category. */
+export declare function systemMarkdown(input: {
+    components: ComponentsManifest;
+    tokens?: TokensManifest;
+    rules?: RuleEntry[];
+    patterns?: PatternEntry[];
+    terms?: TermEntry[];
+}, title?: string, provenance?: string): string;
+/** Links an agent outside the repo can follow to the exact data. */
+export declare function manifestLinks(base: string): string;
+export { slugOf };