Portfolio presentation

• 1: Status treatments
• 2: Social previews
• 3: Diagrams and demos
• 4: Documents

1 - Status treatments

Required pattern

Every project presentation must show a status as text. Color, icons, position, and motion may reinforce the label but must never replace it.

Do not substitute broad claims such as “platform”, “production-ready”, or “enterprise” unless the owning repository publishes evidence for that claim. Prefer narrow artifact categories: CLI, process layer, applied research, prototype, library, or supporting asset.

Accessibility

• Keep the full status label visible at all viewport sizes.
• Pair every color with the status-specific shape in the table.
• Use normal text contrast of at least 4.5:1 and large-text/UI contrast of at least 3:1.
• Test light and dark variants independently.
• Do not encode a status change with animation alone.

The source templates use high-contrast neutral text and reserve accent color for a supporting rule. Maintainers must rerun local validation after changing colors.

Project examples

Examples are prompts for maintainers, not permanent factual claims. Confirm each status and limitation with the owning repository before publishing.

2 - Social previews

Content model

Every 1280×640 preview contains only:

1. Projectious organization mark and name.
2. Project name.
3. One narrow artifact category.
4. One complete maturity label from the status vocabulary.
5. An optional short limitation, never a marketing claim.

The editable source is brand/portfolio/social-preview-template.svg. Replace bracketed text, keep the status label intact, and save a project-specific SVG beside the template. Examples for aibox, processkit, ai-market-research, and KubeClaw demonstrate the content structure; they are not evidence of current maturity.

Export and validation

Run:

npm run portfolio:validate
npm run portfolio:export

The export script uses resvg when available and otherwise leaves the SVG source as the canonical reusable asset. Commit generated PNGs only when a repository needs them.

Source and generated exports use this repository’s split license. The Projectious name and marks remain subject to TRADEMARK.md. Record any third-party typeface, icon, logo, or screenshot in brand/PROVENANCE.md before use. The supplied templates contain no third-party logos or screenshots.

3 - Diagrams and demos

Architecture and flow diagrams

• Prefer left-to-right flow, explicit boundaries, and named protocols.
• Distinguish implemented components from planned components with text: implemented, external, or planned.
• Add a caption with repository, source path, commit or release, and capture date.
• Never infer architecture from a social preview or marketing page.
• Keep editable source beside the export and document the export command.

Suggested caption:

Source: owner/repository, docs/architecture.svg, release vX.Y.Z, captured YYYY-MM-DD. Planned elements are labelled.

The three diagram types

“Prefer diagrams over photographs” is only useful if the diagrams exist. Consulting deliverables need three, and they answer different questions:

Diagram gallery — all three, built from the brand tokens.

The drawing rules are the same in all three, and they are deliberately spare:

• Lines, not arrows, unless direction is the point. A sequence diagram’s messages are directional and get an arrowhead. An architecture diagram’s connections usually are not — a 1px slate-5 rule says “connected” without claiming a flow that may not exist.
• One accent per diagram, at most. The accent marks the focal node — the thing the surrounding paragraph is about. A diagram where three nodes are orange has no focus.
• Boxes carry a fill or a border, never both plus a shadow. Solid midnight-9 for the emphasised node, surface-2 with a slate-5 border for the rest.
• Labels are 12–13px and horizontal. No rotated text. A diagram whose labels need a head-tilt is a diagram that needed a different layout.
• Monospace for anything that is an identifier — a service name, a region, a hostname — and the body face for anything that is prose.

An org chart names roles, and names people only with their agreement. The portfolio identity rules apply: a chart is a public artefact, and a person’s name in one is a disclosure about them.

Screenshots and demos

• Show real output from a named build, commit, or release.
• Frame the output without modifying product state or hiding errors.
• State sample/synthetic data clearly.
• Do not fabricate dashboards, terminal output, customer logos, or product UI.
• Crop personal data, tokens, account identifiers, and unrelated windows.
• Record capture command, viewport, theme, and date in provenance.

When there is no real output yet, use a text-first project card labelled Idea / implementation starting. A truthful absence is better than a fictional interface.

4 - Documents

A document is not a screen that happens to be printed. It has a fixed page box, no hover state, no dark mode, and one shot at being legible on a printer nobody tested. This page defines the pattern the system uses for short, laid-out documents, and links the worked example.

Longer, flowing documents — reports and papers — use the LaTeX and Typst templates in brand/templates/ instead. The split is about pagination, not length; see below.

Decide the pagination first

Two kinds of document, and the choice is made before any layout happens:

Getting this wrong is expensive in one direction: a flowing document forced into fixed pages breaks the moment a paragraph grows, while a designed page that is allowed to reflow loses the arrangement that was its whole purpose.

Never pin a paper size on a flowing document. Letter and A4 differ, the reader’s printer knows which one it has, and the text should reflow onto it. A paginated document does pin a page box, and each page is designed to fill Letter and A4 alike without overlap.

The one-page document

Header, summary, body sections, and a footer region — with the whole thing constrained to fit a single page rather than allowed to run onto a second.

The section markers are the only accent on the page, and they are text. A document has no primary action, so there is nothing for a solid accent to mark — an accent-filled band on a CV is decoration claiming to be emphasis.

Entries are separated by space, not by rules. A one-page document accumulates horizontal rules faster than anything else in the system, and each one costs a line of content while adding a section break to a document with one section per heading — the same argument the signature makes, on a bigger sheet.

Dates and other data are set in IBM Plex Mono and right-aligned against the entry title, so a reader scanning chronology has a column to scan.

Fitting one page

The constraint that makes this pattern hard is that the content has to end where the page does.

• Cut content, not type. 14.5px body and 13.5px entries are the floor. A document set at 11px to fit is a document that will not be read.
• Cut the oldest entry first. A CV is not an archive; a proposal is not a contract.
• The two-up region is the pressure valve. Two short sections side by side recover roughly a third of a page against stacking them.
• Check it at 100%. A browser zoomed to 90% will happily show you a page that overflows in print.

Exporting

The example is HTML on the paged-document shell; the export route is the browser’s print dialogue, to PDF.

• Print backgrounds on, margins default, headers and footers off — the browser’s own header would print a URL across the top of a CV.
• Send the PDF, not the HTML. The HTML depends on a font load and a runtime; the PDF depends on nothing.
• Check the PDF at 100% and printed on plain paper before it goes anywhere.

Reusing the pattern

The resume is the worked example, but the pattern is not resume-specific. A one-page proposal, a project brief, and a decision memo are the same document with different section names:

Where the document makes a claim about a project’s maturity, the status vocabulary applies — a document is not exempt from it because it is prose.