Avelune web style

The website exists to help someone understand, try, use, evaluate, or contribute to Avelune. It is not a record of the conversations, reviews, and implementation steps that produced it.

Design and copy should be judged in the context where a visitor encounters them. A technically true sentence or visually polished component can still be wrong when it does not help the reader at that point on the page.

Write every public surface for a cold reader who knows none of the project’s prior discussion. Conversation history is evidence for making decisions, not source text to paraphrase into the site.

Before rewriting weak prose, ask whether it should exist. Deleting an unnecessary explanation is better than making it sound smoother.

Watch for language that assumes an unstated previous state or objection, including words such as still, remain, now, larger, actually, not hidden, and similar constructions. These words are not forbidden; they are review signals when the local page does not supply the comparison or antecedent.

Use the language appropriate to the artifact:

Do not use claims such as known facts only, real controls, or actually selected to certify that an interface is trustworthy. Make the behavior accurate and let diagnostics show concrete facts when the user asks for them.

Give each page one primary job. Put the information and controls required for that job before secondary architecture, provenance, diagnostics, or project-history material.

Do not expose internal content-model labels, test terminology, implementation boundaries, or release incident history merely because those facts are available. Examples include repository-native Markdown, development-guide, regression-fixture history, one CI runner’s graphics failure, or a conformance-oracle distinction on a page where the reader only needs an API entry point.

Historical material remains available but must be clearly separated from current guidance.

Avelune uses IBM Plex Sans for prose and interface text and IBM Plex Mono for code, identifiers, byte ranges, compact measurements, and other genuinely data-like values. Fonts are bundled with the site. Monospace is not a generic marker for technical content.

The existing neutral palette and restrained cool/warm accents are the default visual foundation. Color never carries state alone. Focus, selection, links, errors, warnings, and status must remain understandable without relying only on hue.

Thin rules and bordered regions are useful when they mark a real structure: a table, source listing, video viewport, form control, diagnostic group, or format diagram. Do not segment every section with rules merely to make the page look technical.

Small metadata text should remain comfortably readable. Avoid accumulating 9–10px uppercase monospace labels across an interface. A category kicker is useful only when it adds information that the adjacent heading does not already provide.

Do not preserve a particular grid, hero illustration, card count, or component choreography as a brand rule. Page structure follows the information hierarchy.

Motion communicates state, position, progress, or direct interaction. It is not decoration for an otherwise static fact.

Do not type a known command character by character, animate data-flow dashes indefinitely, or reveal ordinary sections on scroll only to make the site feel active. When motion is useful, respect prefers-reduced-motion and provide the same information without animation.

The homepage should answer, in order appropriate to the design:

Do not make 4:2:0 plane geometry, generation-state labels, registry identifiers, implementation metadata, or installation theatrics more prominent than the project itself unless the page has a specific communicative reason.

Technical diagrams are welcome when they teach an Avelune-specific idea. Decorative codec imagery is not a substitute for explanation.

The demo’s primary job is to let a visitor play Avelune media and evaluate a conversion. Keep the player, ordinary-media input, important encoding choices, result, and download path easy to find.

Conversion defaults should preserve source characteristics unless the user explicitly chooses a transformation. Settings that affect quality, encoder effort, geometry, frame rate, audio, and seek structure must be distinguishable from one another.

Codec execution choices such as scalar versus SIMD128 and presentation choices such as Canvas2D versus WebGPU are separate concepts. Their selected/active values may remain visible without making a large decoder-debugging inspector the dominant page element.

Detailed range counts, epoch IDs, front-index sizes, event logs, FFmpeg output, OPFS behavior, and similar information belongs in diagnostics or architecture documentation. A privacy statement such as your media stays in this browser is useful in the primary interface; WORKERFS device plumbing is not.

Representative showcase media, synthetic stress material, and tiny deterministic regression vectors are different categories. Label them honestly and do not present a synthetic diagnostic scene as representative gameplay or 3D footage.

Documentation favors a calm reading layout with a clear current document, collection navigation, and on-page outline. Mobile layouts must not force the reader through an expanded catalog before reaching the document they opened.

Normative pages identify their draft status and source provenance. Ordinary guides need not expose internal page-type=current metadata or use normative-sounding authoritative language unless that information helps the reader.

Tables may scroll horizontally where necessary. Code listings, admonitions, source links, stable anchors, current/historical distinction, and print output should remain functional and readable.

Layouts become simpler as space decreases. Controls wrap into readable rows or columns rather than shrinking labels until they collide. Long identifiers wrap or scroll without widening the page. Navigation must make off-screen choices discoverable rather than relying on a hidden horizontal scrollbar.

Review intermediate widths around actual breakpoints, not only a wide desktop and one narrow phone. High browser zoom is part of responsive behavior.

Target WCAG 2.2 AA. Preserve semantic landmarks and heading order, a skip link, keyboard operation, visible focus, non-obscured anchors, appropriate text and non-text contrast, reflow at narrow widths and zoom, accessible names, and adequate control targets.

Error, loading, conversion, and playback states are communicated in text as well as visually. Respect system reduced-motion preferences.

Review a page as though it were opened directly from a search result with no project history. For each visible block ask:

Automated checks should verify structural/accessibility invariants and rendered layout. Editorial heuristics may flag suspicious back-reference wording, repeated metadata labels, or unusually long UI help text for review, but must not become a blacklist of AI words.

Run npm run check:content, the site build, link/semantic checks, and browser smoke for affected changes. For meaningful visual work, inspect rendered screenshots at desktop, intermediate, mobile, and zoomed layouts in addition to CI geometry checks.