# Heyz / Portal · brand system v1

Heyz is a calm, capable home for useful ideas. The identity is warm orange, charcoal and ivory: direct, spacious and professional. The **Portal** symbol is an open doorway with a point of connection. Use the same vector on the web, iOS home screens and community surfaces.

The live reference is **`/brand`**. Start a new page with [page-template.md](page-template.md). This directory, the master SVG and the CSS tokens are the versioned design source; generated downloads are build artifacts committed alongside them.

## Source and regeneration

| Source                           | Responsibility                                              |
| -------------------------------- | ----------------------------------------------------------- |
| `public/brand/portal-source.svg` | The single editable Portal geometry.                        |
| `app/design-tokens.css`          | Canonical colors, type families, spacing, radii and motion. |
| `docs/brand/page-template.md`    | Reusable page brief, composition and review checklist.      |
| `scripts/generate-brand.mjs`     | Deterministic fixed-color SVG, React and PNG 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 an orange 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 orange mark is the default on charcoal. Use charcoal on ivory, or ivory on charcoal, when a monochrome mark is needed. An orange mark on ivory is decorative, never the sole indicator of an action or state.
- The application `BrandMark` has a literal orange fill generated from the token. It never inherits text color or changes with operating-system theme. Give standalone logo links an accessible name; the SVG itself is decorative when adjacent to visible `Heyz` text.

## Slogan

The canonical slogan is **Ideas Alive.** Preserve the capitalization and punctuation: no period after Ideas, one period after Alive. In the homepage hero, place **Ideas** on the first line in ivory and **Alive.** on the second line in orange. Keep the wording static.

## Palette and contrast

| Color    | Value     | Use                                          |
| -------- | --------- | -------------------------------------------- |
| Orange   | `#ed7650` | Portal, primary actions, focus accents.      |
| Charcoal | `#181816` | Main canvas and text on orange.              |
| Ivory    | `#f4f0e7` | Primary text and intentional paper surfaces. |

Use semantic aliases (`--background`, `--foreground`, `--primary`, `--text-secondary`, `--border`) in components. Orange is an accent, not a full-page wash. Do not introduce new brand colors per feature. Success, warning, danger and information have separate semantic tokens and always include a label or icon.

Normal text needs **4.5:1** contrast; large text and meaningful control outlines need **3:1**. Orange and ivory do not meet normal-text contrast against each other. On ivory, use `--paper-ink` for body text and `--paper-accent` for accent text. On charcoal, use ivory or `--text-secondary`. Primary buttons use the shared dark `--primary-foreground`. Check the rendered color pair when introducing a state, opacity or overlay. See [WCAG text contrast guidance](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html).

## 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 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: 6px for small details, 10–12px for controls, 16px for major panels. Avoid decorating every line of content as a card.

## 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

Use `community/discord/assets/heyz-discord-icon.png`: a **512 × 512** orange Portal on charcoal, with circle-safe margins. `public/brand/portal-discord-512.png` is the same file for downloading. The Apple home-screen icon is **180 × 180**, opaque, and uses the same geometry and colors. Do not pre-round either image; each platform applies its own mask.

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. Choose semantic tokens before adding CSS literals.
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.