@taprootio/site-authoring 0.8.0 → 0.8.2

package/README.md

@@ -79,16 +79,34 @@ upgrade available to anyone the deploy refuses.
 
 `taproot-site --help` lists every verb and the configuration contract.
 `taproot-site help` is the offline reference family agents read before
-authoring: page types, components, navigation, media, previews, themes,
+authoring: page types, composable design blueprints, components, navigation, media, previews, themes,
 appearance, the footer, and the offline fixture contract, each with `--json`
 for stable machine-readable output.
 
 ```bash
 taproot-site help
+taproot-site help designs
+taproot-site help design professional-portfolio
 taproot-site help page free-form
 taproot-site help component hero-section --json
 ```
 
+Design help separates three choices that agents should make deliberately:
+site purpose, visual language, and interaction intensity. The six blueprints
+cover professional portfolios, bold consumer brands, editorial publications,
+local services, cultural events, and community directories. Each describes a
+content model, representative pages, navigation shape, theme direction,
+component recipes, a motion ceiling, media guidance, integration boundaries,
+and accessibility cautions. They are composable starting points—not templates
+or permission to copy another site's protected assets or trade dress. Use
+`--json` when an agent needs the stable recipe structure.
+
+Before pushing appearance, use `taproot-site help appearance` and preview both
+schemes. A light logo must remain distinct on the rendered light header and a
+dark logo on the rendered dark header at desktop and compact/mobile widths;
+transparent canvas pixels do not count as contrast. Supply separate
+scheme-specific assets when one visible mark cannot satisfy both surfaces.
+
 `taproot-site validate <fixture-directory>` checks a complete offline fixture
 with no credential, no network, and no write: a directory laid out like a
 pulled workspace — `pages/`, `nav.json`, `redirects.json`, and the four

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taprootio/site-authoring",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "Taproot site authoring CLI: sign in once in the browser, then pull, validate, push, preview, approve, and deploy a site from the terminal",
   "type": "module",
   "license": "ISC",
@@ -28,7 +28,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@taprootio/espalier": "4.12.0"
+    "@taprootio/espalier": "4.13.0"
   },
   "scripts": {
     "test": "node --test",

package/src/cli.js

@@ -49,12 +49,15 @@ import {
   formatReferenceResult,
   getAppearanceReference,
   getComponentReference,
+  getDesignBlueprint,
   getFooterReference,
   getPageTypeReference,
   getThemeReference,
   getWorkflowReference,
   listComponentTypeReferences,
+  listDesignBlueprints,
   listPageTypeReferences,
+  DESIGN_TYPES,
   PAGE_TYPES,
   REFERENCE_TOPICS,
   REFERENCE_VERSION,
@@ -628,6 +631,7 @@ function parseReferenceArguments(arguments_) {
     (
       topic === "pages"
       || topic === "components"
+      || topic === "designs"
       || topic === "nav"
       || topic === "media"
       || topic === "preview"
@@ -641,7 +645,7 @@ function parseReferenceArguments(arguments_) {
   ) {
     throw usageError("help.usage", `The '${topic}' topic does not accept a name.`);
   }
-  if ((topic === "page" || topic === "component") && (subject === undefined || extra.length > 0)) {
+  if ((topic === "page" || topic === "component" || topic === "design") && (subject === undefined || extra.length > 0)) {
     throw usageError("help.usage", `The '${topic}' topic requires exactly one name.`);
   }
   return { mode: "reference", topic, subject, json };
@@ -662,6 +666,8 @@ function referenceResult(parsed) {
       return { ...result, topic: "page-types", pageTypes: listPageTypeReferences() };
     case "components":
       return { ...result, topic: "component-types", components: listComponentTypeReferences() };
+    case "designs":
+      return { ...result, topic: "design-types", designs: listDesignBlueprints() };
     case "page": {
       const page = getPageTypeReference(parsed.subject);
       if (!page) {
@@ -685,6 +691,17 @@ function referenceResult(parsed) {
       }
       return { ...result, topic: "component", component };
     }
+    case "design": {
+      const design = getDesignBlueprint(parsed.subject);
+      if (!design) {
+        throw usageError(
+          "help.design_type_unknown",
+          `Unknown design type. Expected one of: ${DESIGN_TYPES.join(", ")}.`,
+          { alternatives: DESIGN_TYPES },
+        );
+      }
+      return { ...result, topic: "design", design };
+    }
     case "nav":
     case "redirects":
     case "media":

package/src/constants.js

@@ -1,5 +1,5 @@
 export const CLI_NAME = "@taprootio/site-authoring";
-export const CLI_VERSION = "0.8.0";
+export const CLI_VERSION = "0.8.2";
 export const CLI_BINARY_NAME = "taproot-site";
 export const RESULT_SCHEMA_VERSION = 1;
 export const CONFIG_FILE_NAME = "taproot-site.json";

package/src/content/components.js

@@ -226,6 +226,9 @@ const CARD_GRID = Object.freeze({
     { kind: "value", value: Object.freeze([]) },
   ),
   columns: num({ values: Object.freeze([2, 3]) }),
+  presentation: enumOf("cards", "editorial", "featured", "poster"),
+  imageAspect: enumOf("auto", "landscape", "square", "portrait"),
+  interaction: enumOf("none", "lift", "zoom", "caption-reveal"),
   borderWidth: num({
     integer: true,
     minimum: 0,
@@ -257,6 +260,7 @@ const IMAGE_BANNER = Object.freeze({
   // A built-in or application-registered Espalier texture name.
   texture: textureName(),
   textureScale: enumOf("fine", "medium", "coarse"),
+  imageMotion: enumOf("none", "slow-zoom", "drift-start", "drift-end"),
 });
 
 const SPACER = Object.freeze({
@@ -444,6 +448,9 @@ const COMPONENT_DEFINITIONS = Object.freeze({
     {
       cards: [{ image: null, title: "", description: "", linkUrl: "" }],
       columns: 3,
+      presentation: "cards",
+      imageAspect: "landscape",
+      interaction: "lift",
       borderWidth: 0,
     },
     [
@@ -467,6 +474,9 @@ const COMPONENT_DEFINITIONS = Object.freeze({
         },
       ],
       columns: 2,
+      presentation: "featured",
+      imageAspect: "landscape",
+      interaction: "lift",
       borderWidth: 1,
     },
   ),
@@ -490,6 +500,7 @@ const COMPONENT_DEFINITIONS = Object.freeze({
       textShadow: "none",
       texture: "none",
       textureScale: "medium",
+      imageMotion: "none",
     },
     [
       "Set altText to describe meaningful banner imagery; leave it empty only when the image is decorative.",
@@ -505,6 +516,7 @@ const COMPONENT_DEFINITIONS = Object.freeze({
       scrim: "bottom",
       scrimStrength: "medium",
       texture: "paper",
+      imageMotion: "slow-zoom",
     },
   ),
 });
@@ -829,6 +841,23 @@ export function validateComponentBlock(componentType, componentData, basePath) {
   const fields = isComponentType(componentType) ? COMPONENT_SHAPES[componentType] : undefined;
   if (!fields) return errors;
   validateFields(fields, parsed, dataPath, errors);
+  if (componentType === "card-grid" && Array.isArray(parsed.cards)) {
+    for (const [index, card] of parsed.cards.entries()) {
+      if (
+        isPlainObject(card)
+        && typeof card.linkUrl === "string"
+        && card.linkUrl.trim().length > 0
+        && isSafeUrl(card.linkUrl)
+        && (typeof card.title !== "string" || card.title.trim().length === 0)
+      ) {
+        errors.push(contentError(
+          `${dataPath}/cards/${index}/title`,
+          CODES.componentData,
+          "A linked card must have a visible title.",
+        ));
+      }
+    }
+  }
   return errors;
 }
 

package/src/content/free-form-section-registry.json

@@ -1,5 +1,5 @@
 {
-  "version": 5,
+  "version": 6,
   "section": {
     "nodeType": "section",
     "label": "Section",
@@ -38,6 +38,33 @@
           "elevated"
         ]
       },
+      "entrance": {
+        "label": "Entrance",
+        "help": "Optional CSS-only reveal for the section content. Unsupported browsers render the content statically and reduced-motion preferences disable the effect.",
+        "type": "enum",
+        "required": false,
+        "default": "none",
+        "values": [
+          "none",
+          "fade",
+          "rise",
+          "scale",
+          "slide-start",
+          "slide-end"
+        ]
+      },
+      "entranceStagger": {
+        "label": "Entrance stagger",
+        "help": "Optional bounded delay between the section's direct content blocks. It has no effect when entrance is none and becomes static under reduced-motion preferences.",
+        "type": "enum",
+        "required": false,
+        "default": "none",
+        "values": [
+          "none",
+          "tight",
+          "relaxed"
+        ]
+      },
       "background": {
         "label": "Photo background",
         "help": "Optional site-owned responsive photograph behind the section band, with normalized focal points and a context-derived readability scrim.",

package/src/content/markdown.js

@@ -656,7 +656,7 @@ function sectionHeaderAttrs(text, line) {
     );
   }
 
-  for (const name of ["contentPadding", "surface"]) {
+  for (const name of ["contentPadding", "surface", "entrance", "entranceStagger"]) {
     const definition = definitions[name];
     const value = parsed[name];
     if (value !== undefined && (typeof value !== "string" || !definition.values.includes(value))) {
@@ -691,6 +691,8 @@ function sectionHeaderAttrs(text, line) {
     ...(typeof context === "string" ? { context } : {}),
     contentPadding: parsed.contentPadding ?? definitions.contentPadding.default,
     surface: parsed.surface ?? definitions.surface.default,
+    ...(parsed.entrance === undefined ? {} : { entrance: parsed.entrance }),
+    ...(parsed.entranceStagger === undefined ? {} : { entranceStagger: parsed.entranceStagger }),
     ...(normalizedBackground.background ? { background: normalizedBackground.background } : {}),
     ...(normalizedDecoration.decoration ? { decoration: normalizedDecoration.decoration } : {}),
   };

package/src/content/tiptap-prosemirror.ts

@@ -624,6 +624,13 @@ function renderSection(
   const surface = attrs.surface === "raised" || attrs.surface === "elevated"
     ? attrs.surface
     : definitions.surface.default;
+  const entrance = typeof attrs.entrance === "string" && definitions.entrance.values.includes(attrs.entrance as never)
+    ? attrs.entrance
+    : definitions.entrance.default;
+  const entranceStagger = typeof attrs.entranceStagger === "string"
+      && definitions.entranceStagger.values.includes(attrs.entranceStagger as never)
+    ? attrs.entranceStagger
+    : definitions.entranceStagger.default;
   const contextValue = kind === "explicit" ? stringAttr(attrs.context) : undefined;
   const context = contextValue
       && countUnicodeScalars(contextValue) <= definitions.context.maximumLength
@@ -672,6 +679,8 @@ function renderSection(
       "data-taproot-section": kind,
       "data-content-padding": contentPadding,
       "data-surface": surface,
+      "data-entrance": entrance,
+      "data-entrance-stagger": entranceStagger,
       context,
       style: sectionStyle,
     },

package/src/content/validate-document.js

@@ -227,6 +227,8 @@ const SECTION_ATTRS = Object.freeze({
   }),
   contentPadding: optionalEnum(FREE_FORM_SECTION_REGISTRY.section.attrs.contentPadding.values),
   surface: optionalEnum(FREE_FORM_SECTION_REGISTRY.section.attrs.surface.values),
+  entrance: optionalEnum(FREE_FORM_SECTION_REGISTRY.section.attrs.entrance.values),
+  entranceStagger: optionalEnum(FREE_FORM_SECTION_REGISTRY.section.attrs.entranceStagger.values),
   // Nested field diagnostics are owned by
   // `normalizeFreeFormSectionBackground` below.
   background: spec(() => null),

package/src/presentation-reference.js

@@ -334,6 +334,11 @@ export function getAppearanceReference() {
       "Use site-owned image ids retained from pull or returned by media upload. URLs are server projections, never authored inputs.",
     logoContract:
       "lightLogoId and darkLogoId are the current scheme-specific logo fields; there is no separate compact-logo setting.",
+    logoContrastContract:
+      "Evaluate lightLogoId against the rendered light-scheme header and darkLogoId against the rendered dark-scheme "
+      + "header at desktop and compact/mobile widths. Transparent pixels provide no contrast: inspect the visible mark, "
+      + "not its canvas bounds. When one asset does not remain distinct in both schemes, supply scheme-specific logo "
+      + "assets rather than relying on a shadow, outline, or header color that has not been previewed.",
     headerWidthContract:
       "headerWidth 'contained' keeps the brand and the header buttons at the page content edges; "
       + "'wide' moves them to the viewport edges. Pages with root-band components (image-banner) span the viewport, "
@@ -596,6 +601,7 @@ export function formatPresentationReference(reference) {
       + "\n\nRead-only server projections:\n"
       + reference.readOnlyProjections.map((field) => "  " + field.file + " :: " + field.path).join("\n")
       + "\n\nImages: " + reference.imageReferences + "\nLogos: " + reference.logoContract
+      + "\nLogo contrast: " + reference.logoContrastContract
       + "\nHeader width: " + reference.headerWidthContract
       + "\nMobile menu and menu font: " + reference.menuContract
       + "\nFooter: " + reference.footerBoundary

package/src/reference-help.js

@@ -51,8 +51,290 @@ import {
 
 export { getAppearanceReference, getFooterReference, getThemeReference };
 
-export const REFERENCE_VERSION = 21;
+export const REFERENCE_VERSION = 23;
 export const PAGE_TYPES = Object.freeze(["free-form"]);
+
+function deepFreeze(value) {
+  if (value === null || typeof value !== "object" || Object.isFrozen(value)) return value;
+  for (const child of Object.values(value)) deepFreeze(child);
+  return Object.freeze(value);
+}
+
+export const DESIGN_TYPES = Object.freeze([
+  "professional-portfolio",
+  "bold-consumer-brand",
+  "editorial-publication",
+  "local-service",
+  "cultural-events",
+  "community-directory",
+]);
+
+const DESIGN_BLUEPRINTS = deepFreeze([
+  {
+    type: "professional-portfolio",
+    displayName: "Professional portfolio",
+    summary: "A focused body of selected work, credibility, and a clear route to start a conversation.",
+    sitePurpose: "Present an individual or small practice's work and make its expertise easy to evaluate.",
+    visualLanguage: "Quiet editorial spacing, confident typography, and a restrained image rhythm that lets work lead.",
+    interactionIntensity: "Low: direct reading and deliberate links, with modest affordances only where they clarify a destination.",
+    contentModel: { primary: ["selected projects", "case studies", "profile and approach"], supporting: ["services", "testimonials", "contact details"] },
+    representativePages: [
+      { title: "Home", purpose: "State the practice and foreground a small selection of work." },
+      { title: "Work", purpose: "Browse projects by discipline, sector, or outcome." },
+      { title: "Case study", purpose: "Explain the brief, process, collaboration, and result for one project." },
+      { title: "About", purpose: "Introduce the practitioner, perspective, and capabilities." },
+      { title: "Contact", purpose: "Offer one obvious, accessible way to begin an enquiry." },
+    ],
+    navigationShape: "A compact primary set: Work, About, Services, Contact; case studies remain one level below Work.",
+    themeDirection: "A calm light/dark pair with generous contrast, one measured accent, and roomy display/body type scale.",
+    recipes: [
+      {
+        name: "Selected-work opening",
+        purpose: "Introduce the practice, then make the first few destinations tangible.",
+        section: { entrance: "rise", entranceStagger: "tight" },
+        components: [
+          { type: "hero-section", properties: { titleSize: "display", alignment: "start", mediaArrangement: "split", mediaWidth: "wide" } },
+          { type: "card-grid", properties: { columns: 2, presentation: "editorial", imageAspect: "landscape", interaction: "lift" } },
+        ],
+      },
+      {
+        name: "Capability proof",
+        purpose: "Pair concise service language with independently readable client evidence.",
+        section: { entrance: "fade", entranceStagger: "relaxed" },
+        components: [
+          { type: "feature-grid", properties: { columns: 3, iconSize: "small", borderWidth: 0 } },
+          { type: "testimonial", properties: { columns: 2, carousel: false, borderWidth: 0 } },
+        ],
+      },
+    ],
+    motionCeiling: "One entrance family per section; no autoplaying carousels, parallax, or motion that competes with the work.",
+    mediaBrief: "Use original project imagery, credited photography, and outcome-oriented captions; keep decorative media clearly optional.",
+    integrationBoundaries: "Link to an external booking, portfolio-hosting, or contact service when needed. This blueprint does not provide custom code or built-in commerce, search, scheduling, or synchronization.",
+    accessibilityCautions: ["Make each card title identify its destination without relying on its image.", "Keep case-study headings logical and give meaningful work images useful alt text."],
+  },
+  {
+    type: "bold-consumer-brand",
+    displayName: "Bold consumer brand",
+    summary: "A product- and campaign-led presence that builds recognition while keeping the next step unmistakable.",
+    sitePurpose: "Introduce a consumer offering, its point of view, and paths people can take to learn or buy elsewhere.",
+    visualLanguage: "Large type, high-contrast fields, assertive image crops, and a small, consistent set of branded shapes.",
+    interactionIntensity: "Medium: purposeful hover and reveal feedback, never required to understand the product or complete a task.",
+    contentModel: { primary: ["product or collection stories", "brand promise", "campaign landing pages"], supporting: ["stockist links", "press", "frequently asked questions"] },
+    representativePages: [
+      { title: "Home", purpose: "Lead with a proposition, featured collection, and one primary action." },
+      { title: "Products", purpose: "Orient visitors to product families without claiming a built-in shop." },
+      { title: "Story", purpose: "Explain origins, materials, values, or makers." },
+      { title: "Stockists", purpose: "Link people to approved places to purchase or visit." },
+    ],
+    navigationShape: "A short, campaign-aware primary nav; collection and story pages use local in-page links instead of deep menus.",
+    themeDirection: "A distinctive accent against neutral surfaces, strong semantic contrast, and display typography balanced by practical body text.",
+    recipes: [
+      {
+        name: "Campaign landing",
+        purpose: "Make a single product story legible before offering supporting choices.",
+        section: { entrance: "scale", entranceStagger: "none" },
+        components: [
+          { type: "image-banner", properties: { ratio: "3/1", heightMode: "viewport", contentPosition: "bottom-start", scrim: "bottom", imageMotion: "slow-zoom" } },
+          { type: "cta", properties: { variant: "primary", imagePosition: "right", borderWidth: 0 } },
+        ],
+      },
+      {
+        name: "Collection browse",
+        purpose: "Offer product families as clear destinations with visible labels before interaction.",
+        section: { entrance: "rise", entranceStagger: "tight" },
+        components: [
+          { type: "card-grid", properties: { columns: 3, presentation: "featured", imageAspect: "square", interaction: "zoom" } },
+          { type: "feature-grid", properties: { columns: 3, iconSize: "medium", borderWidth: 0 } },
+        ],
+      },
+    ],
+    motionCeiling: "Use one slow image movement or short hover response per view; never conceal names, price context, or actions behind motion.",
+    mediaBrief: "Commission or license product, material, and in-use photography; document crop-safe banner areas and supply alt text for informative images.",
+    integrationBoundaries: "Use outbound links for retail, commerce, search, or booking providers. This blueprint includes none of those systems and no custom code.",
+    accessibilityCautions: ["Preserve text contrast over imagery with a tested scrim and do not make text depend on hover.", "Respect reduced-motion preferences and give every campaign action a visible text label."],
+  },
+  {
+    type: "editorial-publication",
+    displayName: "Editorial publication",
+    summary: "A reading-first publication that organizes recurring coverage, authorship, and archives without turning discovery into noise.",
+    sitePurpose: "Publish a coherent body of reporting, criticism, essays, or institutional editorial work.",
+    visualLanguage: "Measured typographic hierarchy, generous reading measure, structured metadata, and images that support rather than interrupt reading.",
+    interactionIntensity: "Low: browsing aids and clear links, with no kinetic treatment that interrupts sustained reading.",
+    contentModel: { primary: ["articles", "series or sections", "author bylines"], supporting: ["issue introductions", "archive pathways", "about and submission information"] },
+    representativePages: [
+      { title: "Home", purpose: "Feature current coverage and point to durable sections." },
+      { title: "Section", purpose: "Collect related work with short editorial framing." },
+      { title: "Article", purpose: "Support long-form reading with attribution and related destinations." },
+      { title: "Archive", purpose: "Provide chronological or thematic browse paths without promising built-in search." },
+      { title: "About", purpose: "Explain editorial purpose, contributors, and contact routes." },
+    ],
+    navigationShape: "Sections at the top level, with Archive and About as utilities; article-level navigation stays contextual and modest.",
+    themeDirection: "Reading-optimized light and dark contexts, durable link contrast, restrained accents, and distinct display and body faces.",
+    recipes: [
+      {
+        name: "Lead story and desk",
+        purpose: "Set a lead story beside a calm selection of current work.",
+        section: { entrance: "fade", entranceStagger: "tight" },
+        components: [
+          { type: "image-banner", properties: { ratio: "2/1", heightMode: "ratio", contentPosition: "bottom-start", scrim: "bottom", imageMotion: "none" } },
+          { type: "latest-posts", properties: { count: 6, columns: 3, highlightFirst: false, showDescription: true, showDate: true } },
+        ],
+      },
+      {
+        name: "Section archive",
+        purpose: "Make recurring coverage browsable without a fabricated search interface.",
+        section: { entrance: "none", entranceStagger: "none" },
+        components: [{ type: "card-grid", properties: { columns: 3, presentation: "editorial", imageAspect: "landscape", interaction: "none" } }],
+      },
+    ],
+    motionCeiling: "No motion within article reading; entrances may be brief and nonessential on index pages only.",
+    mediaBrief: "Use licensed or commissioned lead images with accurate captions and credits; optimize portraits and illustrations for editorial role, not decoration.",
+    integrationBoundaries: "Link to an external newsletter, membership, submission, or search provider where appropriate. This blueprint does not add custom code or built-in commerce, search, scheduling, or event synchronization.",
+    accessibilityCautions: ["Maintain readable line length, heading order, and visible links in both theme modes.", "Do not encode section, author, or date only by color, position, or image treatment."],
+  },
+  {
+    type: "local-service",
+    displayName: "Local service",
+    summary: "A practical local presence that explains services, establishes trust, and points visitors to an appropriate external next step.",
+    sitePurpose: "Help nearby people understand a service business, its coverage, and how to make contact or arrange service.",
+    visualLanguage: "Warm, legible, place-aware imagery with plain-language hierarchy and reassuring, lightly structured surfaces.",
+    interactionIntensity: "Low: fast orientation, stable calls to action, and no flourishes that delay contact information.",
+    contentModel: { primary: ["services", "service areas", "trust signals"], supporting: ["team", "frequently asked questions", "contact and external booking links"] },
+    representativePages: [
+      { title: "Home", purpose: "State who the business serves, where, and how to get help." },
+      { title: "Services", purpose: "Explain services, scope, and suitable next steps." },
+      { title: "Service area", purpose: "Clarify locations, travel expectations, or local context." },
+      { title: "About", purpose: "Introduce people, qualifications, and operating principles." },
+      { title: "Contact", purpose: "Surface phone, email, hours, and external scheduling or enquiry destinations." },
+    ],
+    navigationShape: "Service-led primary nav with a persistent Contact action; service-area detail stays shallow and predictable.",
+    themeDirection: "High-clarity neutral surfaces, a trustworthy accent, comfortable body text, and a light/dark pair tested for contact content.",
+    recipes: [
+      {
+        name: "Service reassurance",
+        purpose: "State the offer, locality, and first action before presenting proof points.",
+        section: { entrance: "rise", entranceStagger: "tight" },
+        components: [
+          { type: "hero-section", properties: { titleSize: "display", alignment: "start", mediaArrangement: "split", mediaWidth: "equal" } },
+          { type: "feature-grid", properties: { columns: 3, iconSize: "medium", borderWidth: 1 } },
+        ],
+      },
+      {
+        name: "Service finder",
+        purpose: "Direct people to the right service without pretending to provide a booking engine.",
+        section: { entrance: "fade", entranceStagger: "relaxed" },
+        components: [
+          { type: "card-grid", properties: { columns: 3, presentation: "cards", imageAspect: "landscape", interaction: "lift" } },
+          { type: "cta", properties: { variant: "primary", imagePosition: "left", borderWidth: 0 } },
+        ],
+      },
+    ],
+    motionCeiling: "Keep motion nearly absent; service, phone, hours, and access information remain immediately available.",
+    mediaBrief: "Prioritize real people, local context, and service-in-progress photography; avoid generic imagery that could misrepresent the service or area.",
+    integrationBoundaries: "Use direct links to an external scheduler, map, payments, or service portal if the business has one. This blueprint does not include those capabilities, custom code, or synchronization.",
+    accessibilityCautions: ["Expose contact information as real text and use tel/mailto only where destination is clear.", "Do not rely on a map image alone to communicate service area or physical access information."],
+  },
+  {
+    type: "cultural-events",
+    displayName: "Cultural events",
+    summary: "A program-led cultural presence that foregrounds what is happening, why it matters, and where people can learn more or reserve elsewhere.",
+    sitePurpose: "Present a venue, festival, institution, or program with clear event context and durable cultural framing.",
+    visualLanguage: "Expressive but disciplined poster energy, flexible image crops, and strong date/place typography.",
+    interactionIntensity: "Medium: responsive cards and subtle image movement add vitality while core event information stays static and complete.",
+    contentModel: { primary: ["program highlights", "event or exhibition pages", "artist or participant context"], supporting: ["visit information", "institutional story", "external ticket links"] },
+    representativePages: [
+      { title: "Home", purpose: "Introduce the current season, program, or headline event." },
+      { title: "Program", purpose: "Collect upcoming and recurring activity as labelled destinations." },
+      { title: "Event", purpose: "Explain dates, venue, access, participants, and external reservation options." },
+      { title: "Visit", purpose: "Share access, location, and practical preparation information." },
+      { title: "About", purpose: "Frame the organization's mission and cultural context." },
+    ],
+    navigationShape: "Program and Visit remain top-level; event pages are reached from program groupings rather than a deep date-only hierarchy.",
+    themeDirection: "A flexible, high-contrast light/dark pair that supports poster-like color while reserving reliable semantic colors for text, links, and status.",
+    recipes: [
+      {
+        name: "Season opening",
+        purpose: "Give a headline program visual presence with readable event context.",
+        section: { entrance: "slide-start", entranceStagger: "none" },
+        components: [
+          { type: "image-banner", properties: { ratio: "2/1", heightMode: "ratio", contentPosition: "bottom-end", scrim: "radial", imageMotion: "drift-end" } },
+          { type: "cta", properties: { variant: "primary", imagePosition: "top", borderWidth: 1 } },
+        ],
+      },
+      {
+        name: "Program cards",
+        purpose: "Make event destinations readable by name, date, and place before visual interaction.",
+        section: { entrance: "rise", entranceStagger: "tight" },
+        components: [
+          { type: "card-grid", properties: { columns: 3, presentation: "poster", imageAspect: "portrait", interaction: "caption-reveal" } },
+          { type: "feature-grid", properties: { columns: 3, iconSize: "small", borderWidth: 0 } },
+        ],
+      },
+    ],
+    motionCeiling: "Use one restrained banner drift or card reveal at a time; dates, venue, access, and reservation links never depend on it.",
+    mediaBrief: "Use commissioned or cleared event imagery, poster art, and artist-approved materials with credits, rights notes, and legible crops.",
+    integrationBoundaries: "Point to an external ticketing, calendar, reservation, or streaming service where needed. This blueprint offers no built-in commerce, scheduling, event synchronization, search, or custom code.",
+    accessibilityCautions: ["Put event date, time, venue, and access information in text, not only poster imagery.", "Ensure caption-reveal content is also available without hover, and reduce decorative motion when requested."],
+  },
+  {
+    type: "community-directory",
+    displayName: "Community directory",
+    summary: "A trustworthy guide to people, places, and resources, designed for clear browsing rather than an implied live database.",
+    sitePurpose: "Help a defined community discover organizations, resources, and ways to participate.",
+    visualLanguage: "Friendly utility, distinct category cues, calm card rhythm, and readable metadata over decorative spectacle.",
+    interactionIntensity: "Low to medium: useful card feedback and filters represented as navigation, not as a claim of built-in search.",
+    contentModel: { primary: ["directory entries", "category landing pages", "resource guides"], supporting: ["community story", "contribution guidance", "contact and external services"] },
+    representativePages: [
+      { title: "Home", purpose: "Explain who the directory is for and highlight useful routes in." },
+      { title: "Categories", purpose: "Offer a stable, readable way to browse resource groups." },
+      { title: "Directory entry", purpose: "Describe one organization, service, or place with clear ownership and contact context." },
+      { title: "Guides", purpose: "Publish curated orientation for common community needs." },
+      { title: "Contribute", purpose: "Explain how people can suggest updates through a contact route." },
+    ],
+    navigationShape: "Category-led browsing with Guides and Contribute as utilities; keep entry pages shallow and avoid pretending categories are live filters.",
+    themeDirection: "Accessible category accents against dependable neutral layers, a high-legibility type scale, and dark-mode states tested for links and card boundaries.",
+    recipes: [
+      {
+        name: "Directory orientation",
+        purpose: "Give newcomers a clear explanation and several approachable browse routes.",
+        section: { entrance: "fade", entranceStagger: "tight" },
+        components: [
+          { type: "hero-section", properties: { titleSize: "normal", alignment: "center", mediaArrangement: "stacked", mediaWidth: "narrow" } },
+          { type: "feature-grid", properties: { columns: 3, iconSize: "large", borderWidth: 1 } },
+        ],
+      },
+      {
+        name: "Resource categories",
+        purpose: "Present curated categories as explicit destinations, with enough text to distinguish them.",
+        section: { entrance: "slide-end", entranceStagger: "relaxed" },
+        components: [
+          { type: "card-grid", properties: { columns: 3, presentation: "cards", imageAspect: "auto", interaction: "lift" } },
+          { type: "cta", properties: { variant: "primary", imagePosition: "right", borderWidth: 0 } },
+        ],
+      },
+    ],
+    motionCeiling: "Limit feedback to short card affordances; never represent category navigation as a live filter or conceal names in animation.",
+    mediaBrief: "Use community-supplied or properly licensed images only with permission, contextual captions, and alternatives for entries without photography.",
+    integrationBoundaries: "Link out to external maps, forms, search, calendars, or member systems if the community operates them. This blueprint includes no custom code, built-in search, commerce, scheduling, or synchronization.",
+    accessibilityCautions: ["Do not use color alone to identify a category or resource type.", "Keep each entry's name, purpose, contact route, and eligibility information available as semantic text."],
+  },
+]);
+
+export function listDesignBlueprints() {
+  return DESIGN_BLUEPRINTS.map((blueprint) => Object.freeze({
+    type: blueprint.type,
+    displayName: blueprint.displayName,
+    summary: blueprint.summary,
+    sitePurpose: blueprint.sitePurpose,
+    visualLanguage: blueprint.visualLanguage,
+    interactionIntensity: blueprint.interactionIntensity,
+    helpCommand: `${CLI_BINARY_NAME} help design ${blueprint.type}`,
+  }));
+}
+
+export function getDesignBlueprint(type) {
+  return DESIGN_BLUEPRINTS.find((blueprint) => blueprint.type === type);
+}
 export const REFERENCE_TOPICS = Object.freeze([
   Object.freeze({ name: "pages", usage: `${CLI_BINARY_NAME} help pages`, summary: "List authorable page types." }),
   Object.freeze({
@@ -70,6 +352,12 @@ export const REFERENCE_TOPICS = Object.freeze([
     usage: `${CLI_BINARY_NAME} help component <component-type>`,
     summary: "Describe one component schema and show a valid example.",
   }),
+  Object.freeze({ name: "designs", usage: `${CLI_BINARY_NAME} help designs`, summary: "List composable design blueprints." }),
+  Object.freeze({
+    name: "design",
+    usage: `${CLI_BINARY_NAME} help design <design-type>`,
+    summary: "Describe one composable design blueprint.",
+  }),
   Object.freeze({ name: "nav", usage: `${CLI_BINARY_NAME} help nav`, summary: "Describe nav.json item shapes." }),
   Object.freeze({
     name: "redirects",
@@ -1132,6 +1420,14 @@ function formatPlacement(row) {
   }; ${row.contentPadding}; ${row.well}; measure ${row.measure}`;
 }
 
+function formatDesignRecipe(recipe) {
+  return `  ${recipe.name}: ${recipe.purpose}\n    section entrance ${recipe.section.entrance}; stagger ${recipe.section.entranceStagger}\n${
+    recipe.components.map((component) =>
+      `    ${component.type}: ${Object.entries(component.properties).map(([name, value]) => `${name}=${JSON.stringify(value)}`).join(", ")}`
+    ).join("\n")
+  }`;
+}
+
 export function formatReferenceResult(result) {
   switch (result.topic) {
     case "topics":
@@ -1150,6 +1446,22 @@ export function formatReferenceResult(result) {
           `  ${component.type.padEnd(16)} ${component.summary}\n${" ".repeat(19)}Help: ${component.helpCommand}`
         ).join("\n")
       }\n`;
+    case "design-types":
+      return `Composable design blueprints:\nThese are starting points, not templates or instructions to copy protected assets or trade dress. Site purpose, visual language, and interaction intensity are intentionally orthogonal decisions.\n\n${
+        result.designs.map((design) =>
+          `  ${design.type.padEnd(24)} ${design.summary}\n${" ".repeat(27)}Purpose: ${design.sitePurpose}\n${" ".repeat(27)}Visual language: ${design.visualLanguage}\n${" ".repeat(27)}Interaction intensity: ${design.interactionIntensity}\n${" ".repeat(27)}Help: ${design.helpCommand}`
+        ).join("\n")
+      }\n`;
+    case "design": {
+      const design = result.design;
+      return `${design.displayName} (${design.type})\n${design.summary}\n\nThese are composable starting points, not templates or instructions to copy protected assets or trade dress.\n\nSite purpose: ${design.sitePurpose}\nVisual language: ${design.visualLanguage}\nInteraction intensity: ${design.interactionIntensity}\n\nContent model:\n  Primary: ${design.contentModel.primary.join("; ")}\n  Supporting: ${design.contentModel.supporting.join("; ")}\n\nRepresentative pages:\n${
+        design.representativePages.map((page) => `  ${page.title}: ${page.purpose}`).join("\n")
+      }\n\nNavigation shape: ${design.navigationShape}\nTheme direction: ${design.themeDirection}\n\nComponent and section recipes:\n${
+        design.recipes.map(formatDesignRecipe).join("\n")
+      }\n\nMotion ceiling: ${design.motionCeiling}\nMedia brief: ${design.mediaBrief}\nIntegration boundaries: ${design.integrationBoundaries}\n\nAccessibility cautions:\n${
+        design.accessibilityCautions.map((caution) => `  - ${caution}`).join("\n")
+      }\n\nUse --json for the stable structured recipes.\n`;
+    }
     case "page": {
       const page = result.page;
       const markdownFormat = page.workspace.formats.find((format) => format.extension === ".md");