Design language on vanityURLs Brand

Color

Mon, 01 Jan 0001 00:00:00 +0000

Use teal as an accent, not as the whole interface.
Keep status colors semantic and distinct from brand teal.
Preserve badge contrast on light and dark surfaces.
Pair brand accents with neutral gray, white, and dark ink surfaces so pages do not become one-note teal compositions.
Test color combinations against WCAG contrast requirements before publishing.

The vanityURLs palette follows the same intent as the Red Hat color foundation: color is a practical system for brand expression, hierarchy, state, and accessibility. Treat the palette as a set of named decisions, not a drawer of interchangeable decoration.

Fonts and typography

Mon, 01 Jan 0001 00:00:00 +0000

The website self-hosts Inter Variable for interface and prose text, plus JetBrains Mono for code. Font files live under static/fonts/ and are declared in assets/css/main.css.

The typographic model takes inspiration from the Red Hat font-family foundation: use one family for expressive and readable text, and one monospaced family for code and technical identifiers. vanityURLs uses Inter instead of Red Hat Display/Text, but keeps the same separation between human-readable prose and technical material.

Typeface samples

Inter Variable

Aa vanityURLs

Grid

Mon, 01 Jan 0001 00:00:00 +0000

Use a centered content column for documentation and reference pages. Keep long-form reading surfaces narrow enough to scan comfortably.

The standard documentation layout uses a left navigation, a main reading column, and an optional table of contents. Brand pages should reuse that layout unless the page is a special-purpose asset preview.

The grid approach is based on the Red Hat grid foundation: a predictable structure with responsive columns, margins, gutters, and constrained line length. vanityURLs keeps the same discipline but adapts it to a compact documentation site and generated redirect pages.

Spacing

Mon, 01 Jan 0001 00:00:00 +0000

Spacing should make the interface easy to scan. Use tighter spacing for operational tools and more generous spacing for page openings, brand summaries, and asset previews.

The website uses fluid documentation spacing tokens in assets/css/main.css, from --docs-space-2xs through --docs-space-l. Use those token relationships when adding new documentation components.

The spacing model follows the Red Hat spacing foundation: a small, named scale keeps rhythm consistent across components, patterns, and layouts. vanityURLs maps that idea to documentation prose, compact product UI, generated pages, and asset previews.

White space and text flow

Mon, 01 Jan 0001 00:00:00 +0000

White space is part of the interface, not decoration. It helps readers understand what belongs together, where a section starts, and which action is most important.

Prose flow

The documentation uses content-flow and docs-flow patterns to create steady spacing between paragraphs, headings, lists, code blocks, tables, and callouts.

Use that rhythm for long-form pages. Avoid manually stacking ad hoc margins unless a reusable component needs a new spacing rule.

Flow pattern rules

Use content-flow on Markdown-style content containers that need readable prose spacing. It sets the shared body size, line height, child spacing, heading rhythm, and list-item rhythm for paragraphs, lists, quotes, tables, code blocks, highlighted code, and non-prose inserts.

A11Y

Mon, 01 Jan 0001 00:00:00 +0000

Accessibility is part of the brand system, not an afterthought.

The main website publishes an Accessibility Statement and a Trust Center with the current conformance target, known gaps, and reporting channels. Brand work should preserve those commitments instead of treating them as a separate compliance page.

Requirements

Preserve visible focus states.
Use meaningful link text.
Keep color contrast readable.
Provide localized alternative text for badges and images.
Avoid layouts where text overlaps, clips, or becomes too small to read.

Site standards

The current website targets WCAG 2.1 Level AA and documents partial conformance publicly. That standard applies to brand pages, documentation, generated redirect pages, badges, and operator-facing product surfaces.

Components and patterns

Mon, 01 Jan 0001 00:00:00 +0000

The brand system should reuse existing components before creating new ones. Shared patterns keep pages predictable and reduce CSS drift.

Documentation patterns

Use existing Hugo shortcodes and CSS components for:

Callouts and notices.
Steps and ordered setup flows.
File trees and repository structure.
Code blocks with copy buttons.
Tables for tokens, assets, and compatibility notes.
Details sections for secondary explanation.
Cards for repeated navigation items or downloads.

Product patterns

Generated redirect and operator-facing surfaces should feel related to the documentation without becoming documentation pages.

Iconography

Mon, 01 Jan 0001 00:00:00 +0000

Iconography should clarify meaning, not decorate empty space. The vanityURLs system follows the practical shape of the Red Hat iconography foundation: choose icons from a known set, use them consistently, and make their purpose clear in context.

Icon roles

Role	Use	Guidance
Navigation	Section identity, previous/next cues, external links	Pair with text unless the icon is universally understood and labelled for assistive technology.
Actions	Copy, download, search, open, close, theme toggle	Use familiar symbols and preserve hover, pressed, and focus states.
Status	Success, warning, danger, blocked, expired, maintenance	Pair with visible text. Do not rely on color or icon shape alone.
Metadata	GitHub, RSS, social, file type, language	Keep small and subordinate to the label or value.
Illustration	Product concepts or brand storytelling	Use sparingly; documentation should remain useful before it becomes expressive.

Style

Prefer a consistent outline style for interface icons.
Use filled icons only when the state or icon set requires it, such as selected status or social marks.
Keep icon stroke, size, and optical weight balanced with adjacent text.
Use 1em icons inside inline text and stable square dimensions for icon buttons.
Do not mix unrelated icon libraries in the same control group.

Accessibility

Decorative icons should be hidden from assistive technology. Informative icons need an accessible name or nearby text that carries the same meaning.

Diagrams and code

Mon, 01 Jan 0001 00:00:00 +0000

vanityURLs is a technical product, so diagrams and code examples are part of the brand language. They should clarify behavior, not decorate the page.

Mermaid diagrams

Use Mermaid for redirect flows, deployment paths, routing decisions, and lifecycle diagrams.

Keep diagrams small enough to understand without zooming.
Label edges with real conditions such as alias found, blocked, expired, or fallback.
Prefer left-to-right flow for request pipelines.
Use diagrams to explain behavior that would be harder to parse as prose.

Code blocks

Code blocks use Chroma class-based highlighting and copy buttons. Keep examples complete enough to run or recognize.

Interaction

Mon, 01 Jan 0001 00:00:00 +0000

Interactions should be predictable, quick to understand, and visibly reversible when the action is local.

The interaction guidance builds from the Red Hat links foundation: links connect users to pages, sections, and resources; buttons perform actions on the current surface. That distinction matters on vanityURLs because generated pages often ask visitors to decide whether to continue, inspect, or report a link.

The documentation uses active sidebar states, mobile navigation, anchor links, previous and next links, and an optional table of contents. Preserve those patterns so users can move through reference content without relearning the site.

Dark mode and themes

Mon, 01 Jan 0001 00:00:00 +0000

The website uses Tailwind’s class-based dark mode. Theme changes should feel like the same system under different lighting, not like a separate brand.

Theme behavior

Initialize the selected theme before paint when possible.
Preserve active navigation, focus, hover, and selected states in both themes.
Keep code highlighting readable on light and dark backgrounds.
Avoid theme-specific content unless the asset itself requires a light or dark version.

Color in dark mode

Use teal accents sparingly on dark surfaces. Brand teal should identify links, selected states, and important accents; it should not become the background for every panel.

Design language on vanityURLs Brand

Color

Fonts and typography

Typeface samples

Inter Variable

Grid

Spacing

White space and text flow

Prose flow

Flow pattern rules

A11Y

Requirements

Site standards

Components and patterns

Documentation patterns

Product patterns

Iconography

Icon roles

Style

Accessibility

Diagrams and code

Mermaid diagrams

Code blocks

Interaction

Navigation

Dark mode and themes

Theme behavior

Color in dark mode