# Heyz / Portal · brand system v2

Heyz is a publishing place for people and their agents. Version 2 carries one connected world across the public site and product: a warm chalk canvas, forest structure, terracotta Portal, light paper artifacts and visible people and agent identities. The **Portal** is an open doorway with a point of connection. In the product story, it is the threshold an authorized artifact crosses on its way to readers. Its source geometry is the same on every surface.

The versioned reference is **`/brand`**. Start a page with [page-template.md](page-template.md). This directory, the master SVGs and the CSS tokens are the design source; generated downloads are build artifacts committed alongside them. The original orange, charcoal and ivory identity remains available as a documented legacy set during migration.

## Source and regeneration

| Source                                            | Responsibility                                                 |
| ------------------------------------------------- | -------------------------------------------------------------- |
| `public/brand/portal-source.svg`                  | The single editable Portal geometry.                           |
| `public/scroll-world/illustrated-v2/looks/*.webp` | Optimized illustrated scene specimens for the connected world. |
| `public/brand/landing-world-source.svg`           | The early composition study retained as a historical export.   |
| `app/design-tokens.css`                           | Canonical colors, type families, spacing, radii and motion.    |
| `docs/brand/page-template.md`                     | Reusable publishing-page brief, composition and review steps.  |
| `scripts/generate-brand.mjs`                      | Deterministic SVG, React, PNG and design-reference exports.    |

Run `node scripts/generate-brand.mjs` after changing a source. Run `node scripts/generate-brand.mjs --check` to detect drift without writing. The package aliases are `npm run brand:generate` and `npm run brand:check`. Commit sources and outputs together. Do not hand-edit generated icons or `components/brand-mark.tsx`. The script uses the repository's existing Sharp installation; it makes no network requests.

## Mark and wordmark

- Keep the Portal's 116:132 source aspect ratio. Never redraw it as a Unicode symbol, stretch it, rotate it or add strokes, gradients or glow.
- Clear space is at least **one connection-dot diameter** on all sides: 28 source units, approximately 21% of the displayed mark height. The source SVG's internal padding does not replace this external clear space.
- Minimum display height is **24px** for a standalone mark and **28px** beside the `Heyz` wordmark. Favicons are the deliberate 16px exception; do not add a wordmark at that size.
- Typeset the wordmark as lowercase **`heyz.`** in Inter, weight 600, with restrained tracking and a terracotta dot. Match the wordmark's visible height to approximately 55% of the symbol's height and separate it by at least half a dot diameter. Capitalized Heyz is correct in ordinary prose.
- The terracotta mark is the v2 site default. Use it on chalk or paper with a forest wordmark. It is decorative when its color alone has insufficient contrast; the visible wordmark or an accessible name carries the identity. On forest, use the paper monochrome mark where the mark must stand on its own.
- `BrandMark`, `app/icon.svg` and `app/apple-icon.png` use v2 terracotta. The source paths remain exact. The old orange, ivory and charcoal exports and the historical orange community assets remain downloadable and byte-identical.

## Public landing message

The homepage headline is **Your agents make it. Heyz brings it to people.** Its supporting line is **Create with agents. Publish for people.** These state the product's publishing proposition directly. “Ideas Alive.” is a historical identity phrase and is no longer the homepage headline. The public landing design presents the intended launch state; the [launch program](../launch/PROGRAM-STATUS.md) remains the source for release readiness.

## Palette and contrast

The `--heyz-*` tokens are canonical for the v2 site and product. `--landing-*` variables are compatibility aliases for the first landing implementation. The shared semantic aliases (`--background`, `--foreground`, `--primary`, `--card`, `--border` and related status tokens) map the product interface to v2. Use the semantic aliases for ordinary controls and surfaces; use the named `--heyz-*` colors when a composition needs a specific brand material.

| Token                    | Value     | Role                                |
| ------------------------ | --------- | ----------------------------------- |
| `--heyz-canvas`          | `#f1eee5` | Warm chalk page canvas.            |
| `--heyz-forest`          | `#23483c` | Headings and primary actions.       |
| `--heyz-sage`            | `#e8ede2` | Quiet supporting surfaces.          |
| `--heyz-terracotta`      | `#bf765a` | Portal and decorative material.     |
| `--heyz-paper`           | `#fffcf5` | Artifact sheets and inset panels.   |
| `--heyz-ink`             | `#1e3430` | Strong text on canvas or paper.     |
| `--heyz-secondary-ink`   | `#486459` | Supporting text on canvas or paper. |
| `--heyz-terracotta-text` | `#934d37` | Accent text on canvas or paper.     |
| `--heyz-rule`            | `#d4dace` | Decorative dividing lines.          |
| `--heyz-rule-strong`     | `#65826e` | Meaningful control boundaries.      |

Forest, ink, secondary ink and terracotta text meet the 4.5:1 normal-text target on both canvas and paper. Terracotta material is decorative; use the darker text token for words and meaningful small icons. Use `--heyz-rule-strong` for meaningful control boundaries and the lighter rule for decorative divisions. Normal text needs **4.5:1**; large text and meaningful control outlines need **3:1**. Check rendered pairs after opacity or overlays. The live `/brand` reference calculates the palette contrast from the generated source.

Success, warning, danger and information have separate semantic tokens and always include a label or icon. Do not introduce unregistered colors per feature.

### Legacy v1 palette

| Color    | Value     | Historical use              |
| -------- | --------- | --------------------------- |
| Orange   | `#ed7650` | Portal and primary actions. |
| Charcoal | `#181816` | Main canvas.                |
| Ivory    | `#f4f0e7` | Text and paper surfaces.    |

The original fixed-color SVG and PNG exports remain available for existing integrations. Do not read their old colors as the current page template. Orange and ivory do not meet normal-text contrast against each other; old surfaces still need accessible pairings while they are being migrated.

## Typography

Inter is the interface and editorial family. Use weights 400 for text, 500 for headings/actions and 600 sparingly for emphasis. JetBrains Mono is for code, IDs and small technical labels. Fonts are bundled locally; do not add remote font dependencies.

Aim for 16px body text with 1.6 line height, 14px supporting UI text with 1.5, and no less than 12px for ancillary metadata. Display headings can scale from 36–40px on mobile to 80px on wide canvases, with compact 1.05 line height. Keep paragraphs around 60–75 characters per line and headings in sentence case.

## Layout, spacing and controls

Use the 4px spacing scale in the tokens. Typical gaps: 8px within controls, 16px in a field group, 24–32px between groups and 64–96px between page sections. Use `--content-width` (1248px) for broad layouts and `--reading-width` (720px) for prose. Mobile outer gutters are 20px; desktop gutters grow to 48px. Keep the content order meaningful when columns stack.

Use the shared Button and Input components. Prefer one primary action per decision. Controls must have real behavior, visible keyboard focus, persistent field labels and connected help/error messages. **44px is our comfortable touch target**; it is not the WCAG AA minimum. The [WCAG target-size requirement](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html) is 24px, with spacing and other exceptions. Compact desktop controls need adequate separation. Rounded corners are quiet and consistent: 8–12px for small details and controls, 18px for major panels. Avoid decorating every line of content as a card.

## Publishing-page composition

Keep the artifact at the center. Its title, selected revision, published revision and next action should remain easy to find. Use open space and quiet separators around the conversation; a different background is often enough to separate a supporting area. Human and agent identities carry explicit labels. A conversation message does not imply agent execution, approval or reading.

As of 2026-09-27, the softer D direction is the working product direction. The final hero composition and film are deferred until the actual collaboration journey can be recorded. The older illustrated scenes remain comparison material, not proof of working collaboration. Do not commission new media to fill an unfinished interaction.

A product capture follows one artifact: a contributor selects an authorized agent, sends an explicit request, the external agent proposes a draft, and an authorized human reviews and publishes the exact revision. The timeline connects the request, agent, draft, publication and any reinstatement using stored events. On mobile it becomes the same chronological list; no information depends on graphics or color alone. The storyboard and claim sources are in [scroll-world-proposal.md](scroll-world-proposal.md).

Keep the literal promise and real destinations in server-rendered HTML. Motion must have a static, readable equivalent. The IT brief illustrates a separate explicit agent request followed by human review and publication. Standing internal agent publication under M24 remains gated roadmap work and must not be presented as available before verification, activation and the required legal review.

## Motion and accessibility

Keep feedback transitions around `--duration-fast` (160ms). Animate opacity or transform only when it helps explain a state change. Avoid looping decorative motion. Respect `prefers-reduced-motion: reduce`; state changes must remain legible without animation.

Use semantic headings, meaningful links and visible focus. Status combines a written label with color; invalid fields use `aria-invalid` and `aria-describedby`. Test keyboard use, 200% zoom, 320px width, reduced motion, Chromium and WebKit. Do not apply automatic dark/light recoloring to logos or the fixed brand palette.

## Discord and exports

The v2 site favicon uses a terracotta Portal. The **180 × 180** Apple home-screen icon has the same terracotta mark on paper, is opaque, and has no pre-rounded corners. Download it as `public/brand/portal-apple-v2-180.png`.

The Discord kit in `community/discord/assets/` retains the **512 × 512** orange Portal on charcoal, with circle-safe margins; `public/brand/portal-discord-512.png` is the same legacy file for downloading. `public/brand/portal-apple-180.png` retains the legacy orange Apple icon. Updating a local kit does not change a provider account or live community icon.

Previous green/lavender star artwork is archived under `community/discord/assets/archive/` for provenance only. Dated Discord setup records describe the historical live state. Generating this kit does not upload or change the live server, webhook or community icon; deployment is a separate action.

## Working with the system

1. Start with the page template and existing components.
2. Use semantic tokens for ordinary UI, and `--heyz-*` tokens for named brand materials. Keep `--landing-*` aliases only for compatibility.
3. If the design source changes, regenerate the kit and inspect SVG and raster outputs.
4. Review the live `/brand` specimens and the affected product view at mobile and desktop widths.
5. Commit the design decision, source and generated output in the same change. Record substantive direction changes as a new brand-system version in this manual.

## Version history

- **v2 refinement · 2026-09-27:** softened the D-direction product surfaces with warm chalk, lighter paper, quiet decorative rules and shared 8/12/18px corner tokens. Artifact conversation and revision controls establish the capture before final hero media.

- **v2 · 2026-09-26–27:** introduced the connected publishing world, the literal publishing message, the site-wide palette, terracotta site mark and illustrated scene studies. Legacy orange exports remain byte-identical; earlier composition and photographic studies remain separate historical comparisons.
- **v1:** established the orange Portal, charcoal and ivory interface palette, and shared exports.