docs
    agency-site-kit: Sections and devices
    v0.14.2.md

    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 idQuestion it answersSections in it, in reading order
    problemWhat did the client come in with, and what was in the way?portfolioChallenges, portfolioBeforeAfter
    buildWhat did we plan and make, and out of what?portfolioStrategy, portfolioSiteArchitecture, portfolioDesignSystem, portfolioFeatureSpotlight, portfolioGallery, portfolioVideo, portfolioTechStack
    proofHow does the finished build hold up when measured?portfolioPerformance, portfolioSpeedComparison, portfolioVerification
    outcomeWhat 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 (sectionsOrdered is 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 your switch. 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. getPortfolioItem has already applied the same rules, so a check with no scope line, a placeholder where or 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 scope beside the result, 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 where only when it is an address. verificationLink(where) returns the URL for a plain http or https address with a public host and null for a screen name, a file path or localhost, which you print as text.
    • Print date with formatIsoDate. 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 caseStudyStageStatus doesn't ask for a Performance section as well. Pass each section's data along with its sectionType; 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] | undefined

    The 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 | undefined

    The 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.