Theme & media

ThemedHeroImage

A decorative, theme-aware hero background with coordinated overlays, fades, and optional light blending.

ThemedHeroImageThemedHeroImageProps

Component workbench

Configure the production component, inspect it at responsive widths, copy synchronized JSX, and share the exact state from one workspace.

Theme-aware media

Overlay and fade controls protect foreground contrast in both themes.

Generated example

This JSX stays synchronized with the controls and uses only public package APIs.

tsx

import { ThemedHeroImage } from '@ai-created/ui';

export function Example() {
  return (
    <section className="relative min-h-96 overflow-hidden">
      <ThemedHeroImage
        darkSrc="/hero-dark.jpg"
        lightSrc="/hero-light.jpg"
      />
      <h1 className="relative z-10">Build with confidence</h1>
    </section>
  );
}

Import

tsx

import { ThemedHeroImage } from '@ai-created/ui';

Install from a reviewed release

Replace the version placeholder with the release tag your product has reviewed.

shell

npm install --install-links "git+https://github.com/TheMarco/ai-created-ui.git#vX.Y.Z"

Load semantic tokens

css

@import '@ai-created/ui/styles/tokens.css';

@tailwind base;
@tailwind components;
@tailwind utilities;

Extend Tailwind

module.exports = {
  presets: [require('@ai-created/ui/tailwind-preset')],
  content: [
    './src/**/*.{js,ts,jsx,tsx,mdx}',
    './node_modules/@ai-created/ui/src/**/*.{js,ts,jsx,tsx}',
  ],
};

Anatomy

Named regions define what belongs to the component, what remains optional, and where semantic responsibility lives.

Positioning root

Required

Absolute full-bleed media container.

div

Dark image

Required

Required default decorative image.

Light image

Optional

Optional cross-faded light-theme image.

Overlay

Optional

Theme-aware contrast layer.

Top/bottom fades

Optional

Optional gradients blending into page background.

Construction and authoring

The Figma-equivalent asset model, auto-layout, resizing, properties, slots, content bounds, localization, and governance contract.

Asset kind

component

Design library name

Components/Media/Themed hero image

Maturity

stable

Last reviewed

2026-08-29

Canvas applicability

Publish a frame-filling media component with dark and light image swaps and overlay variants.

Auto layout

Direction: overlay
Gap: 0px
Padding: 0px
Alignment: Stretch to all frame edges
Wrap: Layers overlap

Layer order is media, theme alternative, overlay, top fade, then bottom fade.

Resizing

Width: fill
Height: fill
Minimum width: Parent controlled
Maximum width: Parent controlled
Minimum height: Parent controlled
Maximum height: Parent controlled
Overflow: clip

The parent must be positioned and have an explicit or content-derived height.

Exposed design properties

Property	Type	Default	Code mapping	Options or notes
Dark imageRequired	instance-swap	None	darkSrc	No additional constraint
Light image	instance-swap	None	lightSrc	No additional constraint
Overlay	variant	default	overlay	default, strong, soft, none
Top fade	boolean	false	fadeTop	No additional constraint
Bottom fade	boolean	false	fadeBottom	No additional constraint
Light blend	boolean	false	blendLight	No additional constraint
Focal point	text	center	objectPosition	No additional constraint

Nested assets and slots

Dark media

slot / required

Required decorative image.

darkSrc

Light media

slot

Optional light-theme image.

lightSrc

Overlay

primitive

Theme token overlay treatment.

Internal overlay layer

Fades

primitive

Top and bottom content-legibility fades.

Internal fade layers

Content limits

Media role

Decorative hero imagery only

Overflow: Use a semantic image component for meaningful content.

The implementation always uses empty alt text.

File weight

Use the smallest source that remains sharp at rendered sizes

Overflow: Create responsive optimized assets.

Hero media has high performance impact.

Localization and RTL

Image framing must preserve important subjects for both directions.
Do not place baked-in text in the source image.
Review focal points with right-to-left copy placement.
Test dark and light assets behind twice-length headings.

Responsive behavior

Absolute fill with object-cover.

Use sizes to describe actual layout breakpoints

Set a focal point that survives crop changes.
Parent owns aspect ratio and minimum content height.
Provide an accurate sizes value for image selection.

Authoring limits

Figma fills do not validate Next Image loading, responsive source selection, or blend behavior.
Always decorative; do not use for content that needs alternative text.

Accountable owner

Design systems media foundations owner

Canonical source: src/components/ThemedHeroImage.tsx

Overlay and blend changes require contrast review against representative hero copy.
A breaking property, token, or behavior change requires design and engineering approval, a migration note, and a major release.
The design asset, implementation, documentation, accessibility contract, and regression coverage must ship in the same change.

Read the system construction standard

Visual specification

These measurements and semantic tokens define the supported visual contract. Local overrides should preserve the same hierarchy and interaction cues.

Bounds

absolute inset 0

Image fit

cover

Theme cross-fade

500ms during theme transitions

Fade depth

one third of container height

Default quality

Rules

Parent must establish positioning and an explicit height.
Maintain sufficient text contrast over both images.
Use only for decorative imagery; content images require semantic Image usage.

Responsive behavior

sizes defaults to 100vw and should be narrowed when the image is not full viewport width.
objectPosition controls art-direction focus as the container crops.

Token dependencies

--hero-overlay-default / strong / soft

Theme-specific contrast overlays.

--hero-image-dark-opacity / --hero-image-light-opacity

Theme image swap.

--color-bg

Top and bottom fade destination.

--motion-slow

Theme cross-fade.

States and behavior

A component is not complete until its passive, interactive, disabled, and exceptional states remain understandable in both themes.

dark theme

Trigger: Root does not have light class.
Visual response: Dark source is opaque; optional light source is transparent; dark overlay values apply.
Behavior: Image remains decorative.

light theme

Trigger: Root has light class.
Visual response: Optional light source is opaque and dark source transparent; warm overlay values apply.
Behavior: blendLight can multiply the image into the light surface.

Accessibility contract

Semantics, accessible naming, keyboard behavior, focus and announcements are implementation requirements, not optional documentation.

Semantics: Next Image elements use empty alt and aria-hidden; overlays are plain decorative divs.
Accessible name: No accessible name by design.

Use only when the image conveys no information that is absent from nearby text.
Do not put interactive content inside the component.
Verify overlaid text contrast independently in both themes and crop sizes.

Keyboard behavior

No component-specific keyboard behavior. Native document behavior remains unchanged.

Implementation

Use the public package API and preserve the controlled-state, native-attribute, and ref contracts described below.

tsx

import { ThemedHeroImage } from '@ai-created/ui';

Server Component compatible

Requires Next.js Image configuration for external sources.
priority applies only to the dark image; use it for an above-the-fold hero.
If lightSrc is absent, the dark image remains fully visible in both themes.
overlay none deliberately renders no overlay node.

tsx

<ThemedHeroImage darkSrc="/hero-dark.jpg" lightSrc="/hero-light.jpg" fadeBottom />

Public API

These props and helpers are compatibility contracts. Changes require migration guidance and release notes.

Prop	Type	Default	Contract
darkSrc	string	required	Dark-theme image source.
lightSrc	string	undefined	Optional light-theme source.
overlay	default \| strong \| soft \| none	default	Overlay treatment.
priority	boolean	false	Next Image priority loading.
quality	number	85	Image quality.
sizes	string	100vw	Responsive image sizes.
objectPosition	string	undefined	Image object position.
fadeTop	boolean	false	Top fade.
fadeBottom	boolean	false	Bottom fade.
blendLight	boolean	false	Light-theme blend.

Usage guidance

These rules keep the component recognizable across products without preventing deliberate composition.

Do

Art-direct dark and light sources for comparable subject placement.
Set accurate sizes and use priority only above the fold.

Do not

Do not use for product screenshots or informative charts.
Do not assume an overlay guarantees accessible contrast.

Testing contract

The component should be verified as rendered UI, an interaction model, an accessibility surface, and a theme-aware visual artifact.

Unit

Maps overlay, fades, blend, sizes, quality, priority, and object position.
Renders one or two images as configured.

Interaction

Theme class changes swap opacity without affecting layout.

Accessibility

Images remain hidden from the accessibility tree and overlaid copy passes contrast.

Visual

Capture dark/light, every overlay, fades, blend, and representative crop ratios.

Related specifications

theme surface