@port60/template-kit 0.4.2 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@port60/template-kit",
-  "version": "0.4.2",
+  "version": "0.6.0",
   "description": "Build Port60 site templates locally: scaffold, live-preview, validate against the platform contract, and package for studio upload. AI-agent ready — every scaffold ships AGENTS.md and validate emits machine-readable JSON.",
   "type": "module",
   "bin": {

package/src/lib/agentsMd.mjs

@@ -70,6 +70,9 @@ platform accepts it; if it fails here, the upload will fail identically.
   behaviourally.
 - "Looks" = named one-click bundles of knob values in \`manifest.looks\`.
 - Fonts: only families from the platform font catalogue, declared with the weights you use.
+- \`manifest.imagery.hero\` (optional but recommended): declare the photo shape YOUR hero
+  composes best with (\`idealAspect\`, \`minWidth\`, a one-line \`note\`) — the charity's editor
+  measures their actual upload against it and advises. Advice, never enforcement.
 
 ## Which contract this is
 

package/src/vendor/contract/v1/imagery.json

@@ -0,0 +1,23 @@
+{
+ "description": "Platform imagery envelopes — ADVICE, never enforcement. Entity images (events, courses, articles) render on SEVERAL surfaces at once (cards, carousel slides, detail banners), including platform-owned components, so their guidance is platform-level: the envelope every surface can live with. Template-composed slots (the home hero) are different — their ideal is the TEMPLATE's own design call, declared per-template in manifest.imagery and surfaced beside the upload. Editors measure the actual upload against the relevant guidance and advise; the charity always decides.",
+ "entityImages": {
+  "eventPromo": {
+   "idealAspect": "3:2",
+   "aspectRange": ["4:3", "16:9"],
+   "minWidth": 1600,
+   "note": "One photo, several surfaces: the events card, the home carousel slide, and the event page banner — each crops differently, so keep the subject centred and avoid text baked into the image."
+  },
+  "courseImage": {
+   "idealAspect": "3:2",
+   "aspectRange": ["4:3", "16:9"],
+   "minWidth": 1600,
+   "note": "Renders as the course card and the course page opener — subject centred, no baked-in text."
+  },
+  "articleCover": {
+   "idealAspect": "16:9",
+   "aspectRange": ["3:2", "2:1"],
+   "minWidth": 1600,
+   "note": "The article card thumbnail and the article page cover — wide editorial shots sit best."
+  }
+ }
+}

package/src/vendor/contract/v1/manifest.schema.json

@@ -78,6 +78,35 @@
         }
       }
     },
+    "imagery": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "The template's OWN image advice, surfaced beside uploads in the charity's editor — a design statement (what shape suits THIS composition), advisory only, never enforced. Entity images (events, courses, articles) are platform-scoped instead: see the contract's imagery.json envelopes.",
+      "properties": {
+        "hero": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["idealAspect", "minWidth"],
+          "properties": {
+            "idealAspect": {
+              "type": "string",
+              "pattern": "^\\d+:\\d+$",
+              "description": "The aspect this hero composes best with, e.g. \"16:9\"."
+            },
+            "minWidth": {
+              "type": "integer",
+              "minimum": 800,
+              "description": "Below this pixel width the photo may look soft full-bleed."
+            },
+            "note": {
+              "type": "string",
+              "maxLength": 240,
+              "description": "One human line of advice, e.g. how panoramas or portraits behave in this hero."
+            }
+          }
+        }
+      }
+    },
     "fonts": {
       "type": "array",
       "items": {

package/src/vendor/contract/v1/sections.json

@@ -142,7 +142,7 @@
      "name": "buttonHref",
      "kind": "url",
      "required": true,
-     "description": "The button's destination (scheme-guarded on save)."
+     "description": "The button's destination (scheme-guarded on save). The editor's cause picker writes /donate/{slug} here and records causeId beside it (editor bookkeeping — renderers use buttonHref only and may ignore causeId)."
     }
    ],
    "minimal": {
@@ -575,7 +575,7 @@
        "name": "buttonHref",
        "kind": "url",
        "required": false,
-       "description": "Card action link (default: /donate). Scheme-guarded on save."
+       "description": "Card action link (default: /donate). Scheme-guarded on save. The cause picker writes /donate/{slug} and records causeId beside it (editor bookkeeping; renderers use buttonHref only)."
       }
      ]
     }
@@ -606,6 +606,96 @@
      }
     ]
    }
+  },
+  {
+   "type": "people",
+   "label": "People / team",
+   "pages": [
+    "about"
+   ],
+   "description": "The key people behind the charity — trustees, staff, volunteers — as simple cards: name, position, an optional photograph (uploaded through the platform pipeline) and an optional one-line statement. Templates render a card grid that collapses to a single column on small screens; a card without a photo renders cleanly (initials or plain), never a placeholder face.",
+   "fields": [
+    {
+     "name": "eyebrow",
+     "kind": "text",
+     "required": false,
+     "description": "Short kicker, e.g. Who we are."
+    },
+    {
+     "name": "heading",
+     "kind": "text",
+     "required": false,
+     "description": "The section heading, e.g. Our team."
+    },
+    {
+     "name": "text",
+     "kind": "text",
+     "required": false,
+     "description": "An optional intro line."
+    },
+    {
+     "name": "items",
+     "kind": "items",
+     "required": true,
+     "description": "The people.",
+     "itemFields": [
+      {
+       "name": "name",
+       "kind": "text",
+       "required": true,
+       "description": "The person's name."
+      },
+      {
+       "name": "role",
+       "kind": "text",
+       "required": true,
+       "description": "Their position, e.g. Chair of Trustees."
+      },
+      {
+       "name": "imageUrl",
+       "kind": "image",
+       "required": false,
+       "description": "A photograph (platform pipeline). Absent renders cleanly — never a placeholder face."
+      },
+      {
+       "name": "statement",
+       "kind": "text",
+       "required": false,
+       "description": "One line in their voice, e.g. why they serve."
+      }
+     ]
+    }
+   ],
+   "minimal": {
+    "items": [
+     {
+      "name": "Amina Khan",
+      "role": "Chair of Trustees"
+     }
+    ]
+   },
+   "sample": {
+    "eyebrow": "Who we are",
+    "heading": "The people behind the work",
+    "text": "A small team and a lot of volunteers, accountable to you.",
+    "items": [
+     {
+      "name": "Amina Khan",
+      "role": "Chair of Trustees",
+      "imageUrl": "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 96 96'%3E%3Crect width='96' height='96' fill='%23355e4b'/%3E%3Ccircle cx='48' cy='38' r='16' fill='%23e8e2d4'/%3E%3Cpath d='M16 88c4-20 18-28 32-28s28 8 32 28z' fill='%23e8e2d4'/%3E%3C/svg%3E",
+      "statement": "Every pound is a trust — we treat it that way."
+     },
+     {
+      "name": "Daniel Osei",
+      "role": "Treasurer"
+     },
+     {
+      "name": "Sara Malik",
+      "role": "Volunteer Coordinator",
+      "statement": "Fifty pairs of hands, one purpose."
+     }
+    ]
+   }
   }
  ]
 }

package/starter/assets/theme.css

@@ -160,3 +160,30 @@ body { font-family: ' IBM Plex Sans Arabic', var(--p60s-siteFont, 'Inter'), ui-s
 @media (max-width: 899px) {
   .lq-vista-overlap { margin-top: 0; padding-top: 1.6rem; }
 }
+
+/* People / team cards — grid to single column on phones. */
+.lq-people {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
+  gap: 1.2rem;
+  text-align: center;
+}
+.lq-person {
+  background: var(--surface);
+  border: 1px solid var(--line);
+  border-radius: 12px;
+  padding: 1.4rem 1.1rem;
+}
+.lq-person-photo {
+  width: 88px;
+  height: 88px;
+  border-radius: 50%;
+  object-fit: cover;
+  display: block;
+  margin: 0 auto 0.8rem;
+}
+.lq-person-role { margin: 0.15rem 0 0; font-size: 0.9rem; color: var(--muted); }
+.lq-person-statement { margin: 0.7rem 0 0; font-style: italic; color: var(--muted); }
+@media (max-width: 640px) {
+  .lq-people { grid-template-columns: 1fr; }
+}

package/starter/manifest.json

@@ -1,6 +1,6 @@
 {
  "name": "starter",
- "version": "1.5.2",
+ "version": "1.5.4",
  "format": "port60-liquid@1",
  "label": "Starter",
  "description": "The reference template for the Port60 dialect — the developer docs' worked example and the base to copy when building your own. 1.1.0 adds the layout slot: the template owns the header, navigation and footer chrome.",
@@ -13,7 +13,8 @@
    "homeHero",
    "hero",
    "values",
-   "cta"
+   "cta",
+   "people"
   ],
   "islands": [
    "donation_widget",
@@ -40,5 +41,12 @@
    }
   ]
  },
- "changelog": "Vista + giving form: the donation widget returns to the right-hand column, riding over the photograph and continuing onto the gradient below it — nothing stacks, nothing pushes."
+ "changelog": "People / team: the new About-page section — the key people behind the charity as cards, stacking on phones.",
+ "imagery": {
+  "hero": {
+   "idealAspect": "16:9",
+   "minWidth": 1600,
+   "note": "Landscape around 16:9 fills the hero cleanly; panoramas suit the whole-photo framing."
+  }
+ }
 }

package/starter/sections/people.liquid

@@ -0,0 +1,26 @@
+{% comment %}
+  People / team — the reference implementation: simple cards (name, role, optional photo and
+  one-line statement), a grid that collapses to one column on phones. No placeholder faces:
+  a person without a photo just renders text (derive or omit, never fabricate).
+{% endcomment %}
+<section class="lq-section">
+  <div class="container">
+    {% if section.eyebrow or section.heading or section.text %}
+    <div class="lq-section-head">
+      {% if section.eyebrow %}<p class="lq-kicker">{{ section.eyebrow }}</p>{% endif %}
+      {% if section.heading %}<h2>{{ section.heading }}</h2>{% endif %}
+      {% if section.text %}<p class="lq-muted">{{ section.text }}</p>{% endif %}
+    </div>
+    {% endif %}
+    <div class="lq-people">
+      {% for person in section.items %}
+      <article class="lq-person">
+        {% if person.imageUrl %}<img class="lq-person-photo" src="{{ person.imageUrl }}" alt="" loading="lazy">{% endif %}
+        <h3>{{ person.name }}</h3>
+        <p class="lq-person-role">{{ person.role }}</p>
+        {% if person.statement %}<p class="lq-person-statement">“{{ person.statement }}”</p>{% endif %}
+      </article>
+      {% endfor %}
+    </div>
+  </div>
+</section>