Surfaces and chrome
Cards, chart containers and their titles
A surface is a card or panel on the page. Chrome is the header and footer around a card, chart or table: the header has its title, and the footer has its source and actions.
Canvas and surface
The canvas is the page background, coloured --color-canvas. A surface sits on the canvas and is coloured --color-surface. Use --color-surface-muted for a surface that needs to stand apart from what is around it, such as a panel inside a card.
A surface's level above the canvas is set by its elevation. A card sits at elevation-1, a tooltip or popover at elevation-4 and a modal at elevation-5. Surfaces have square corners (visual rules).
Cards
A card groups related content under one title, such as a chart, a table or several panels. It has the surface colour, a border, elevation-1 and 16px of padding. The space between its header, content and footer is the default flow step of the context.
Use Card from @ldn-viz/ui. The content goes in its children, and the title group and footnotes are props:
<Card
title="Rough sleeping"
subtitle="People seen sleeping rough, by quarter"
source="GLA City Intelligence"
hint="Counts include people seen more than once."
>
<div class="h-40"><PlaceholderImage /></div>
</Card>People seen sleeping rough, by quarter
- Source:GLA City Intelligence
Storybook lists the props.
Title groups
A title group is the text at the top of a card, chart, table or panel. It has up to three parts, stacked in this order: an optional eyebrow, a title and an optional subtitle. The title uses title-md unless the design needs a larger one. The title sits 4px below the eyebrow, the tight flow step. The subtitle has no space above it, and line height sets the distance.
A component with one title group can use all three parts. A card that contains other titled components, such as a chart, has several groups. Choose one to be dominant. The dominant group has a title and an optional subtitle, and no eyebrow. Each other group shows only an eyebrow, with the text that would have been its title.
In the components, emphasis="primary" makes a group dominant and emphasis="secondary" reduces it to an eyebrow.
A card with one chart
When the chart is the main subject, its group is dominant. The card's title becomes an eyebrow directly above the chart's title:
<Card title="Housing" emphasis="secondary">
<ChartContainer
title="Net additional dwellings"
subtitle="London, 2015 to 2024"
source="GLA"
dataDownload={false}
imageDownload={false}
>
<PlaceholderImage />
</ChartContainer>
</Card>Housing
London, 2015 to 2024
- Source:GLA
A card with two related charts
The card's group is dominant, and each chart's title becomes an eyebrow:
<Card title="Housing" subtitle="London, 2015 to 2024">
<div class="gap-flow grid grid-cols-2">
<ChartContainer title="Completions" emphasis="secondary" …>…</ChartContainer>
<ChartContainer title="Approvals" emphasis="secondary" …>…</ChartContainer>
</div>
</Card>London, 2015 to 2024
Completions
Approvals
A card with only text has no other title group, so its group can have an eyebrow, a title and a subtitle.
Chrome
Card, ChartContainer and TableContainer share the same chrome: a header above the content and a footer below it, built from three parts:
ChromeHeaderhas the title group at the left and an optional hint at the right. The hint is an information icon that opens a help overlay.ChromeFooterhas the footnotes at the left: a byline, the source, a note and, on a chart or table, a button that opens its description. The actions sit at the right, such as the download button. The footnotes usecaption-smin the muted text colour.TitleGrouprenders the eyebrow, title and subtitle, or only an eyebrow when the group isn't dominant.
<Card
title="Rough sleeping"
byline="GLA City Intelligence"
source="GLA City Intelligence"
note="Provisional"
>
…
{#snippet actions()}
<Button variant="outline" emphasis="secondary" size="sm">Download CSV</Button>
{/snippet}
</Card>- GLA City Intelligence
- Source:GLA City Intelligence
- Note:Provisional
ChartContainer adds the download button and the description button. Its downloadButtonVariant prop sets the download button to a button with the text "Download" (standard, the default), an icon (compact), or an outline button with the text "Download" (outline). The middle of a chart container has separate slots for the controls, the legend and the plot, so that plots side by side stay aligned when their legends wrap to different heights. The Data visualisation pages describe the plot.
Storybook lists the props of Card, ChartContainer, ChromeHeader, ChromeFooter and TitleGroup.