Sections and devices
A case study is a list of sections: a hero, the challenge, the strategy, results, a testimonial and so on. This page covers reading them in the right order, pulling out one section's data with its type, borrowing the client's brand colour, and deciding whether the hero shows one laptop or three devices.
Everything here is pure and imports from
@sonordev/agency-site-kit/portfolio.
What a section looks like
PortfolioItemFull.sections is an array of PortfolioSection:
interface PortfolioSection<T extends PortfolioSectionType = PortfolioSectionType> {
sectionType: T; // 'portfolioHero', 'portfolioResults', ...
displayName: string;
data: T extends keyof PortfolioSectionDataMap ? PortfolioSectionDataMap[T] : PortfolioSectionData;
}In an array of sections, data is the union of every shape, so check
sectionType and cast (as the example below does), or use sectionData.
PORTFOLIO_SECTION_TYPES lists all 22 section types. Nineteen have a typed
data shape in PortfolioSectionDataMap (see Types).
portfolioSpeedComparison, portfolioSiteArchitecture and
portfolioDesignSystem don't yet, so read their data defensively.
The four stages of the story
Every case study reads in four stages, whatever your site calls them:
| Stage id | Question it answers | Sections in it, in reading order |
|---|---|---|
problem | What did the client come in with, and what was in the way? | portfolioChallenges, portfolioBeforeAfter |
build | What did we plan and make, and out of what? | portfolioStrategy, portfolioSiteArchitecture, portfolioDesignSystem, portfolioFeatureSpotlight, portfolioGallery, portfolioVideo, portfolioTechStack |
proof | How does the finished build hold up when measured? | portfolioPerformance, portfolioSpeedComparison, portfolioVerification |
outcome | What is the work doing for the client now? | portfolioResults, portfolioMetricsTimeline, portfolioConversionFunnel, portfolioServices, portfolioTeam, portfolioTestimonial, portfolioDetails |
The hero sits above the first stage and portfolioCTA below the last;
portfolioSeo is metadata and never renders as a section. CASE_STUDY_STAGES
is the four ids in order, CASE_STUDY_STAGE_COPY gives each a generic name
and its question, and sectionStage(type) returns a section's stage (null
for the hero, SEO and CTA). The stages are the same ones Sonor's generator
writes to and the dashboard edits by, so a case study arrives already in
this shape.
The ids are fixed; what people see isn't. You name the four stages for the
site in Sonor (Portfolio settings, per project like the brand), and
getPortfolioStageNames() (see
Fetching) returns that map.
stageName(names, stage) reads it and falls back to the generic name for any
stage left unnamed, so a site that hasn't named them still reads "The
problem", "The build", "The proof", "The outcome".
Reading order: orderedSections and groupedSections
orderedSections(item: Pick<PortfolioItemFull, 'sections' | 'sectionsOrdered'>): PortfolioSection[]
groupedSections(item: Pick<PortfolioItemFull, 'sections' | 'sectionsOrdered'>): CaseStudyStageGroup<PortfolioSection>[]- The stages always read in order: hero, problem, build, proof, outcome, CTA. Nothing stored can put the results above the challenges.
- If someone reordered the sections in the Sonor dashboard
(
sectionsOrderedis true), their order is kept within each stage. - Otherwise sections follow the canonical order in the table above. A section type the kit doesn't know sorts last.
groupedSections returns one group per stage the case study actually has
({ stage, index, sections }), numbered 1 to 4 in order; a stage with no
sections is left out and the numbering follows. Both return new arrays and
never change the item. The canonical positions are also exported as
PORTFOLIO_SECTION_ORDER, a record keyed by section type.
stageLede(item, stage) is the sentence that opens a stage: the case
study's own (item.narrative.stages, written by Sonor for this project)
when there is one, else the stage's generic question. item.narrative.thesis
is the one line for the whole case study. caseStudyStageStatus(sections)
reports which stages are complete, if you want to show that in a preview.
The story is threaded: a challenge has an id, a strategy phase names the
challenges it cleared in resolves, a result names the ones it proves in
proves. challengeRefs(item) lists the challenges with the id each is
named by (its own, else challengeId(position), "c1", "c2"…, which is what
Sonor mints), and linkedChallenges(refs, phase.resolves) resolves a
phase's or a result's links to those challenges in order, dropping any that
match nothing. Anchor each challenge by its id and a phase can print "clears
01, 03" as links back to the problems it answered. Case studies written
before the thread existed carry no links and render as before.
The Verification section
A Lighthouse run can only score what a browser reaches without signing in. For
an app whose screens sit behind a login, that's the sign-in page, so the proof
stage is a Verification section instead: a list of checks, each saying what
it covers and, in its required scope, what it doesn't.
interface VerificationCheck {
label: string; // 'Sign-in page, mobile speed'
result: string; // 'Performance 89'
measured: string; // what was measured
where: string; // a URL, a screen or a file
method: string; // the tool and settings
date: string; // YYYY-MM-DD
scope: string; // what the check does NOT cover
}- Read a section's checks with
readVerificationChecks(section.data)inside yourswitch. You get the checks the contract accepts, in their stored order.verificationChecks(item)does the same for the item's first Verification section; use it only if you render one.getPortfolioItemhas already applied the same rules, so a check with no scope line, a placeholderwhereor a date in the future never reaches your renderer, and a Verification section with none left is gone, which skips the stage it would have opened. - Print the
scopebeside theresult, not behind a toggle or in a tooltip. That line is why the section exists: a result without it reads as a claim about the whole app. The starter labels it "Scope" and prints it straight under the result. - Link
whereonly when it is an address.verificationLink(where)returns the URL for a plainhttporhttpsaddress with a public host and null for a screen name, a file path or localhost, which you print as text. - Print
datewithformatIsoDate. It's a day (2026-10-20), read in UTC like every other date the kit prints. - A Verification section completes the proof stage on its own once it has a
check that can be shown, so
caseStudyStageStatusdoesn't ask for a Performance section as well. Pass each section'sdataalong with itssectionType; a verification without it counts as empty. It doesn't replace Performance: a public site keeps its Performance section.
A renderer is a loop over the groups, each a loop over its sections with a
switch on the type. Return null for types you don't render yet:
import {
curatePortfolioProof,
groupedSections,
sectionData,
stageLede,
stageName,
type CaseStudyStageNames,
type PortfolioItemFull,
type PortfolioSection,
type PortfolioSectionDataMap,
} from '@sonordev/agency-site-kit/portfolio';
type Data<T extends keyof PortfolioSectionDataMap> = PortfolioSectionDataMap[T];
// stageNames comes from getPortfolioStageNames() in the page: what this
// site calls the stages in Sonor. Null reads as the generic names.
export function CaseStudy({
item,
stageNames,
}: {
item: PortfolioItemFull;
stageNames?: CaseStudyStageNames | null;
}) {
const curated = curatePortfolioProof(item);
const hero = sectionData(curated, 'portfolioHero');
const cta = sectionData(curated, 'portfolioCTA');
return (
<article>
{hero ? <Hero data={hero} /> : null}
{curated.narrative?.thesis ? <p>{curated.narrative.thesis}</p> : null}
{groupedSections(curated).map((group) => (
<section key={group.stage}>
<h2>{group.index}. {stageName(stageNames, group.stage)}</h2>
<p>{stageLede(curated, group.stage)}</p>
{group.sections.map((section, i) => (
<Section key={`${section.sectionType}-${i}`} section={section} />
))}
</section>
))}
{cta ? <Cta data={cta} /> : null}
</article>
);
}
function Section({ section }: { section: PortfolioSection }) {
switch (section.sectionType) {
case 'portfolioChallenges': {
const data = section.data as Data<'portfolioChallenges'>;
return (
<section>
<h2>The challenge</h2>
{data.items.map((c) => (
<p key={c.title}>{c.description}</p>
))}
</section>
);
}
// ...one case per section you render
default:
return null;
}
}Run curatePortfolioProof first, so the hero and results already follow the
proof rules.
One section's data: sectionData
sectionData(item, type): PortfolioSectionDataMap[type] | undefinedThe data of the item's first section of that type, typed for it, or
undefined when the case study doesn't have one. Handy when a page needs one
section outside the main loop, like a hero above everything else or a
testimonial in the sidebar:
import { sectionData } from '@sonordev/agency-site-kit/portfolio';
const hero = sectionData(item, 'portfolioHero');
const quote = sectionData(item, 'portfolioTestimonial');The client's colour: projectBrandColor
projectBrandColor(sections: PortfolioSection[] | null | undefined): string | undefinedThe client's own brand colour, read from the case study's Design System
section: the colour whose context mentions a button, link, primary or brand,
else the first colour listed. It's undefined when there's no Design System
section or it has no colours.
Use it for one thing: the light behind the device stage, so each case study glows in its client's colour. Everything else on the page stays in your agency's colours.
const glow = projectBrandColor(item.sections);
<div
className="device-stage"
style={glow ? ({ '--stage-glow': glow } as React.CSSProperties) : undefined}
>
{/* devices */}
</div>One laptop or three devices
A website case study usually shows a laptop, a tablet and a phone. Some case studies should show one laptop instead: software with no real phone view, or a product behind a login that only has a hand-taken desktop screenshot. Two functions make that call, and Sonor makes the same call when it draws the case study's social card, so the post and the page always show the same picture.
import { resolveSoloScreenshot, shouldRenderSoloDevice } from '@sonordev/agency-site-kit/portfolio';
const input = {
category: item.category,
screenshots: item.hero_screenshots,
heroImage: item.hero_image,
};
if (shouldRenderSoloDevice(input)) {
const screen = resolveSoloScreenshot(input); // defined whenever solo is true
// render one laptop showing `screen`
} else {
// render the three-device stage from item.hero_screenshots
}shouldRenderSoloDevice is true when there's something to show and either:
- the screenshots are desktop only (no tablet and no mobile shot), or
- the category is software, not a website.
It's false when there's no image at all: an empty laptop is worse than whatever your fallback is. A live URL doesn't change the answer, because framing a product behind a login shows its sign-in screen.
resolveSoloScreenshot returns the desktop screenshot, else heroImage, else
undefined. Render exactly what it returns: it's the image the decision was
made on.
isSoftwareCategory(category) is the category half on its own. These count
as software once lowercased and slugified (so Application Development,
application_development and application-development all match):
application-development, app-development, software-development,
software, saas, mobile-app, mobile-app-development,
web-application and platform.
SoloDeviceInput is the input type: category, screenshots and
heroImage, all optional and nullable.
Case studies that cover several sites
PortfolioItem.showcase_sites is set when one case study covers more than one
site. With two or more entries, each has its own name, url and
screenshots, so each device frame can show its own site. Absent, or fewer
than two entries, means a single site: use hero_screenshots.
To show a client's live site inside a frame instead of a screenshot, see Live device frames.