Foundations

Family page design — the shared public-facing language

Established 2 October 2026 from the current Amoleo · Pets and Amoleo · Connections root-page redesigns and the Amoleo · Pets public-profile redesign. This is the family-level page language those implementations revealed; it is not a command to clone Pets.

Current reference implementations:

• Amoleo · Pets root page — Amoleo-Pets#353 (29 September 2026): one image-led hero, real/example product visuals, three explanatory sections, shared auth box, mobile pre-auth bar.
• Amoleo · Connections root page — Amoleo-Connections#23/#27 (29 September 2026): deliberately brought onto the same broad pattern while keeping its own content and composition.
• Amoleo · Pets public profile — Amoleo-Pets#374 onward, including the cover-photo hero work in #394 (1 October 2026): subject-first identity hero, modular cards, restrained product promotion.

This document covers public-facing page composition and visual hierarchy. The literal shared primitives still live in family-theme.md, family-header.md, family-footer.md, family-auth-box.md, family-accessibility.md and family-css-system.md.

1. Family resemblance, not one template

An Amoleo page should feel related to the other products before somebody notices why: the same neutral base, typography, borders, spacing discipline, header/footer language and restrained use of the product accent. The page's subject, imagery and composition may still be unmistakably its own.

Do not turn the reference pages into a fixed landing-page component. Pets, Connections and future products can arrange the same ideas differently. Shared rules describe hierarchy and behaviour; app-specific docs decide the exact grid, copy, photography, illustrations and feature examples.

Likewise, this is the default public-page language, not a ban on stronger product-specific art direction. A product may use its accent more heavily where its own documented design calls for it. Deliberate exceptions are better than forcing every product into the same accent ratio.

2. Root and marketing pages: explain the product before asking for an account

The signed-out root is a product page first and an authentication surface second.

• Start with one clear h1 that says what the product is useful for in concrete language. Prefer a specific user problem or outcome over generic brand language.
• Put the existing family auth box inside the overall hero composition on wider screens, rather than making the login form the whole page. On mobile, use the family pre-auth bar/panel pattern so sign-in stays reachable without interrupting the pitch.
• Use one strong hero rather than several competing banners. The hero may combine copy, a product example, auth and decorative imagery, but the reading order must remain obvious.
• Follow the hero with a small number of explanatory sections: what it does, how it works, what matters to know, or how to start. Prefer three useful sections to a long marketing catalogue.
• Demonstrate the product with real components or honest static examples, not invented screenshots of features that do not exist. Dummy/example data is allowed only when it is visibly labelled as example data.
• Claims must match shipped behaviour. If the implementation says “warning” rather than “notification”, or requires an opt-in, the marketing copy says that too.

Typical page width is about 1120–1200px, centred, with 16px mobile gutters and roughly 20–24px desktop/tablet gutters. This is a working range, not a new token; choose the width that suits the page's content.

3. Public subject/profile pages: make the subject the hero

On a public profile, record, title, person, place or similar page, the thing being viewed outranks Amoleo promotion.

• Use the standard family shell and wordmark, but let the subject own the top of the content.
• The identity hero can be more expressive than ordinary cards: larger type, a product/subject tint, subtle pattern, or a user-owned cover image.
• If a premium or optional image replaces a free/default hero treatment, the geometry and information hierarchy stay the same. Paid presentation can be richer without making the free version look unfinished or changing the page structure.
• Keep promotional material restrained. The Pets public profile's single low-page banner is the model: useful content first, Amoleo acquisition second.
• Build the body from clear modules/cards so optional sections can appear or disappear without collapsing the page into an improvised layout.

For profile-style cards, the current useful baseline is a --panel surface, 1px --border, about 16px radius, 24px padding on mobile and 32px on wider screens. Section titles are usually around 24px and may pair with a simple accent-coloured icon. Treat these as the current visual language, not hard-coded family CSS until more than one independent implementation genuinely needs the exact same rule.

4. Imagery should carry mood or identity, never information the page depends on

The September 2026 root redesigns deliberately moved Amoleo's public pages away from form-first utility screens toward more human, image-led pages.

• Decorative hero photography should be product-relevant and composed around the UI: keep the subject out from under important copy and controls.
• Decorative images use empty alt text. Do not make accessibility depend on describing mood photography.
• Protect text with a local surface, scrim or gradient. Prefer darkening/blurring only where copy needs it rather than flattening the whole image.
• For user-owned cover photos, calculate or otherwise choose enough local overlay to keep text at WCAG AA contrast; do not assume white text is safe on every image.
• Decorative generated imagery must not contain readable UI, brand names, logos or fake product claims. Product examples belong in HTML/SVG/real components where they are controllable and accessible.
• On narrower layouts, the hero image may become its own rounded banner/card above the copy rather than being forced to remain a desktop background.

5. Surfaces, shape and spacing

Use the shared neutral theme as the canvas. Product colour is an accent and identity signal, not normally the page background.

• Ordinary modules: --panel on --bg, a subtle 1px border, moderate rounding, generous interior space.
• 16px radius is the current card/module baseline. Larger identity/hero surfaces may use roughly 20–28px. Fully rounded pills are for compact chips, badges and small actions, not every container.
• Prefer borders and spacing to heavy shadows. A surface should feel separated without looking like a floating dashboard tile collection.
• Use whitespace to group sections before adding another container. Not every paragraph needs a card.
• Accent colour belongs on high-signal elements: primary actions, icons, numbered steps, eyebrows, selected states, links and small highlights. Avoid colouring whole ordinary cards just because a product has a brand colour.

6. Typography

The family base remains the system-ui stack, 17px / 1.65 as the shared default where family CSS owns the body. Public page components should not drop readable prose below 16px.

Current useful scales:

• marketing/root h1: roughly clamp(28px, …, 42px);
• subject/profile identity name: may be larger, roughly 36–56px;
• section h2: generally 22–24px;
• card h3: generally 16–18px;
• body, captions that carry meaning, and example labels: 16px minimum.

Keep long explanatory copy to about 46–60 characters per line where practical. A short uppercase accent eyebrow can introduce a section, but it is an optional hierarchy device rather than mandatory decoration.

7. Responsive composition: rearrange, do not remove the proposition

768px is the family mobile header boundary and should be treated carefully (max-width: 768px includes exactly 768). Content-specific breakpoints around 960px or 1024px are fine when a two- or three-column layout genuinely needs them.

• Preserve the same content hierarchy across widths. Mobile can stack or reorder visual regions, but it should not lose the product explanation.
• A desktop image backdrop can become a standalone image card/banner; a three-column hero can become two rows, then one column.
• Do not hide the main pitch merely because the login box consumes the first viewport.
• Touch controls stay at least 44px and focus must move sensibly when a mobile auth panel/drawer opens and return when it closes.

8. Accessibility, privacy and truth are part of the visual language

The polished look is not allowed to come from hiding caveats or private state.

• One page h1; semantic section headings underneath.
• Provide the family skip-link pattern and a focusable main target.
• Meet WCAG AA contrast on the rendered combination, including text over imagery and tinted heroes.
• Never rely on colour alone for state or meaning.
• Label examples explicitly (Example, Example data, not your account, or equivalent).
• Public/profile pages render only data intended for that visitor. Hidden/private values do not get visually blurred or ghosted for anonymous visitors; they do not reach the DOM.
• Decorative content is decorative; meaningful charts or product states need a textual equivalent when the visual itself is hidden from assistive technology.

9. What is deliberately not standardised

This document does not standardise:

• one hero grid for every product;
• one photography style or subject matter;
• exact crop positions, scrim strengths or image assets;
• all card widths or every radius as shared tokens;
• the layout of authenticated application screens;
• an app's documented exceptional use of its own accent;
• product-specific illustrations, graphs, maps, pet imagery or other domain language.

When two products independently converge on the same literal CSS or component behaviour, promote that piece into family-css/family-ui through the existing extraction process. Until then, keep the page-level rule here and the implementation local.

10. New-page checklist

When designing a new public/root/profile surface:

1. Start from the shared theme, header, footer, wordmark and accessibility rules.
2. Decide what the page is about before deciding where auth or promotion sits.
3. Give the first screen one strong hierarchy and, where appropriate, one strong visual.
4. Use real product behaviour for examples and label dummy data.
5. Use panel + border + moderate radius as the default module language; reserve stronger colour/image treatment for identity and key actions.
6. Check the composition at phone, 768px, tablet and wide desktop sizes.
7. Measure contrast on the rendered page, especially over imagery.
8. If the design establishes a pattern that should apply beyond that repo, update this document rather than leaving the decision trapped in app CSS.

Generated from docs/family-page-design.md. Edit there and re-run npm run build in docs-site-src/ — never hand-edit a page.