Box

Use the box when you need a container with optional background, border, and spacing around a parsys.

AEM publisher guidelines

View the component in Figma

Usage

A box is a framed region for any components you drop inside: optional background, border, spacing, and text colour. Visitors experience it as a grouped block (for example a promo or callout). Optionally the whole box can act as one large link.

Behaviour

Background, border, and spacing change how the region reads against the rest of the page.
Optional Active times can show or hide the box on publish based on hours and date ranges; authors may still see warnings in edit mode when constraints are not met.
When a link wraps the whole box, treat the region as one large control (see Accessibility before adding nested links or buttons).

Anatomy

Box anatomy

Outer wrapper: HTML tag classes c-box box (see _cq_htmlTag).
Inner block: div.bloc or a.bloc (when Link is set), with inline styles for background, margin, padding, and optional text colour; classes such as with-border, box-text-white, box-text-black, box-link-white, box-link-black, and extraClass from the dialog.
Optional heading: An h2.section-header when a legacy title property exists on the node, or the placeholder text “Box” in edit mode when the title is empty (the JSP notes this path should migrate to the Title component).
Parsys: box-parsys (concordia/components/parsys) holds nested components.

(Placeholder asset: add a diagram of Box with border vs full-bleed background.)

Content guidelines

Configure the Box in the component dialog (Classic UI). There is no title field in dialog.xml; any stored title on the content node is legacy; prefer the Title component in the parsys.
Use Active times for short-lived promos when editorial control should stay in the component.

When to use

To group related components with a shared background, border, or spacing in a parsys.
To time-box promotional or seasonal content using Active times without separate launch workflows.
When a single full-card click target is acceptable (link wrapper), provided inner content does not introduce nested links that would break accessibility (see Accessibility).

When not to use

For layout grids alone; use Column control, Grid container, or patterns that match the page template.
When you need an accessible title in the design system sense; prefer the Title component in the parsys instead of relying on legacy Box title properties.
If the Box would wrap many separate links or form controls; the whole-box link pattern conflicts with nested interactive elements.

Best practices

Do

Pick background colours from the approved palette in the dialog; box.jsp maps legacy colours and forces readable text and link helper classes for known dark and light backgrounds.
Use Data attributes for analytics or test hooks when agreed with the team.

Don't

Do not add nested links or buttons inside a Box that is also a single link without reviewing Accessibility.
Do not rely on Additional class for the link variant until behaviour is confirmed in code (classes apply to the div path only).

	Resource
!AEM	Help: `dialog.xml` `helpPath` → `/content/concordia/en/web/design/components/box.html?wcmmode=disabled`.
!CDS	Align background and text choices with design system colour guidance and project rules for card-like surfaces.

Design

box.less (#boot .c-box) sets overflow: visible, makes the direct child div or a a block with bottom margin, background repeat/position, and a small border radius using var(--cds-border-radius-sm).
.with-border uses 1px solid var(--cds-border-color-primary).
.box-text-white sets body text and link colours to white with a hover treatment on links inside the Box.
.box-link-black adjusts underline link styling for RTE and list content on pale backgrounds.

box.jsp adds box-text-white / box-link-white or box-text-black / box-link-black automatically for a fixed list of background hex values (dark vs pale), so contrast stays predictable. Author-chosen text colour is also validated and some values are remapped for text (for example certain bright colours map to darker text colours).

Design tokens

Source	Role
`--cds-border-radius-sm`	Inner block corner radius.
`--cds-border-color-primary`	Border colour when Show border is on.
`@color-white` / `@color-black`	Text and link colours in helper classes.

Variants

Background: None, solid colour (# + validated hex), or image (URL in inline style, smart image pipeline).
Border: Optional with-border.
Link wrapper: Inner element is <a class="bloc …"> vs <div class="bloc …">.
Contrast helpers: Automatic box-text- / box-link- classes from background colour switches in box.jsp.

Behaviours

Column control: container.less can treat .box as a flex child so the inner .bloc fills width in some column layouts.
Hidden when inactive: If Active times hide the Box on publish, a placeholder image may render in edit mode so authors still see a drop target.

Accessibility

The Box is a layout and presentation wrapper; accessibility of the page depends on child components (headings, links, images, forms).
Whole-box link: When Link is set, the entire content area is one <a>. Do not place other links or buttons inside that Box unless you resolve nested interactive control issues (see WCAG references below).
Contrast: Automatic text/link helper classes help with common background colours; still verify contrast if authors override text colour or use Additional CSS.

Semantics

Prefer a Title component or proper heading inside the parsys rather than relying on legacy title on the Box node.
Background images: Ensure text over images remains readable; the dialog exposes alt-related fields under the image tab for asset metadata (use as appropriate for the image component pattern).

Keyboard

When the Box is a link, one tab stop may cover the whole region; nested focusable elements inside a single large anchor are problematic in HTML and for assistive technology.
When the Box is a div, focus moves through child controls in DOM order.

Screen reader

Data attributes on the inner block are exposed in the DOM; use meaningful names and values if they affect assistive customisation (usually they are for scripting).
Active times remove content from the publish DOM when constraints fail; do not use them as the only way to convey critical information without a fallback if that content must always be discoverable.

Testing

Test	Status
Keyboard and screen reader with Box as link and with rich content inside	Required before shipping link-wrapped Boxes
Contrast for text and links on chosen background	Recommended
Behaviour when Active times hide content (publish vs author)	Recommended

WCAG / guidelines

Understanding 2.4.4 Link purpose (in context): the link wrapping the Box should describe the destination when the whole region is clickable.
Understanding 4.1.2 Name, role, value: avoid invalid nesting of interactive elements inside the link Box.

Card deck (grid of cards; different layout role).
Title (preferred for section headings instead of legacy Box title).

	Resource
!AEM	Component: `apps/concordia/components/box`; styles: `apps.concordia.box`.

Code

CRXDE Lite query

Use this query in CRXDE Lite to find instances of this component.

/jcr:root/content//*[@sling:resourceType = 'concordia/components/box/box.jsp']

Authoring fields

Authors configure the Box in the component dialog (Classic UI). There is no title field in dialog.xml; any stored title on the content node is legacy.

Tab	Field	Purpose
Settings	Background type	None, Colour, or Image (drives inline `background-color` or `background-image`).
Settings	Background colour	Colour picker when type is Colour; values are validated and some deprecated hex values are remapped in `box.jsp`.
Settings	Additional CSS	Extra rules merged into the inner block’s `style` (see Code for publish vs edit behaviour on the link variant).
Settings	Additional class	Extra classes on the `div.bloc` only (not applied when the Box is a link; the link variant does not output `extraClass` in current markup).
Settings	Link	If set, the inner wrapper is an anchor to this path; `/content` paths get `.html` appended when missing.
Settings	Link target	Optional Open in new tab (`target="_blank"`).
Settings	Margin / Padding	Free-text CSS box values (for example `10px 20px`).
Settings	Show border	Adds class `with-border`.
Settings	Text colour	Optional inline text colour; combined with automatic light/dark helper classes based on background (see Style).
Background image	Smart image	Image asset for background; JSP builds `background-image` from `*.img.png` and sets repeat/position via styles in `box.less`.
Active times	Hours	Multifield of day + open/close time; leave empty for no time-of-day gating.
Active times	Date range(s)	Multifield of start/end datetimes; leave empty for no date gating.
Active times	Debug	Logs constraint evaluation (disabled on publish).
Advanced	Data attributes	Multifield **name \

Technical behaviour

The Box wraps authored content in a block-level element (bloc) inside a root that carries c-box and box classes. Authors pick background treatment, colours, border, margin and padding, and may set a link so the inner block renders as an <a> instead of a <div>.

Active times (optional): when Hours and/or Date range(s) are configured, the Box is shown to visitors only when the server’s current time falls inside a matching schedule or inside at least one date range. In author mode, if constraints fail, authors still see the Box plus a warning that the content will not publish until constraints are met.

Component entry points

Authorable component: concordia/components/box (box.jsp).
Sling resource type: concordia/components/box (component extends foundation/components/parbase, allowedParents include /parsys).
Clientlib: apps.concordia.box (etc/designs/concordia/clientlibs/box/less/box.less), embedded from concordia master clientlibs for typical page loads.

Implementation

File	Purpose
`apps/concordia/components/box/box.jsp`	Visibility logic (hours, dates), colour validation, markup for `div`/`a.bloc`, `cq:include` of `box-parsys`, helper `buildDataAttributesFromMultifield`.
`apps/concordia/components/box/dialog.xml`	Tabs: Settings, Background image, Active times, Advanced.
`apps/concordia/components/box/_cq_htmlTag/.content.xml`	Root classes `c-box box`.
`etc/designs/concordia/clientlibs/box/less/box.less`	Layout, border, text/link helper styles under `#boot .c-box`.
`etc/designs/concordia/concordia-master-clientlibs/.content.xml`	Embeds `apps.concordia.box` with other component clientlibs.

Anatomy (markup)

Root: component tag with class="c-box box".
Inner: <a class="bloc …"> if Link is set, else <div class="bloc …"> with extraClass on the div path only.
Optional <h2 class="section-header"> from legacy title or edit placeholder.
<cq:include path="box-parsys" resourceType="concordia/components/parsys" />.

Authoring (dialog) summary

Properties map to JCR as ./backgroundType, ./backgroundColor, ./image/…, ./extraCss, ./extraClass, ./link, ./linkTargetBlank, ./margin, ./padding, ./showBorder, ./textColor, ./hours, ./dates, ./debug, ./dataAttributes (see dialog.xml for widget types).

Dependencies

Design Image API for background image URL and crop metadata.
JSONObject multifield values for hours and date ranges.
Parsys for all in-flow content.