General

• Following Atomic Design principles, start from building up the atoms, molecules, organisms and layouts.

  • Making sure that the building blocks look good first is going to help composing them later.
  • Glue code should be done last, when we already figured out the assumptions required by the UI components.
    • If we build the glue code as we go, without complete knowledge, we are risking causing bugs and not handling edge cases correctly.

• Work from Storybook first, without any CMS assumptions.

  • We can build up whole pages in Storybook and demonstrate our progress independently from the CMS.
  • When the content managers come and start working in the CMS close to the release date, we will be safe to continue demoing without them interrupting our “demo pages”.
    • The CMS demo becomes a cherry on top of the pie instead of a necessity and a maintenance burden on us before the whole thing is even released.
    • This is a specific case of Separation of Concerns

• When implementing a specific component you see that the mobile and desktop layouts are way different - opt for splitting it to file-per-layout to keep the mental overhead lower.

  • Example (hiding/showing is implemented in the sub-layouts here, but can be done in index too):

    

  

• Build your website with JavaScript disabled in the browser by default. Enable JavaScript for client-side only rich components.

  • Doing otherwise enables forgetfulness — you may take shortcuts that will diminish SEO.
  • Remember that the initial render must be considered having JavaScript disabled. All the page content must be accessible then too.

CMS

• Remember that the resulting webpage is not the only User Interface we’re building. The CMS configuration is also a User Interface for content managers. Building a good experience includes making sure that the setup of the CMS and the content blocks supports and simplifies their workflow and doesn’t get in their way.
• When implementing components that take CMS data, always handle edge cases where the data may be missing. Everything is optional if the CMS does not enforce it.
  • Prismic doesn't enforce required data at all by design.
• Components must not accept CMS types as props. They should be built in a decoupled fashion. For connecting them with the CMS, a mapping layer should be implemented.
  • CMS-specific types cannot be imported into any files that live within components/.
    • There should be a separate directory for components that bind CMS data to JSX components, for Prismic it would be slices, for Storyblok - blocks. The code in there uses the mapping layer to bridge the gap.
  • Within the mapping layer, transform the data to conform to any requirements that cannot be enforced in the CMS. Otherwise you have to do it N times in the downstream code. Example:
    • Some text fields should have character limits, but the CMS does not support it (ahem, Prismic).
• Do not mutate data coming from the CMS. Create new types that get passed around.
  • Mutating the data at such a high level causes unforeseen, arcane bugs in random places of the code.
  • If we have a codebase that depends on data being mutated, changing things becomes a game of Russian roulette. 🙂 There is no easy way to debug problem causes.
• For each page, make room in the CMS for customizable SEO and Social Media metadata.
  • In Prismic, it’s customary to create slices for SEO and Social Media (twitter/og) and put them in a separate tab for each custom type that has a page in the codebase.

Tailwind

• Do not create classes that correspond directly to components. The CSS should be a grab-bag of utilities we compose to achieve needed results in atoms, molecules, organisms, layouts.
  • Example: we received in the requirements a font style called heading-3.
    • In the designs it’s used for H3s... for now. In time it will probably get re-used in other components. The style cannot be tightly coupled to a given component.
    • Some components using that font may need to look like headline-4 in given breakpoints. If we implemented headline-3 as a custom css class to define how the thing should look across all breakpoints (seems like a good idea at first), now we need to duplicate the element in JSX and start hiding/showing one of the versions for different screen sizes.
  • Regardless of whether the style looks like it fits a single type of component or not, our job is to break it down into its constituents.
    • Style headline-3 contains a font-size, font-weight, line-height and whatever else? Implement each of those properties in the tailwind config separately. Then in the H3 component, compose the right style.
      • If the designers provide a constrained set of values then great — but that doesn’t change the approach. The values must be implemented in tailwind config and composed from.
    • That way we can re-use existing styles for different purposes and not tie ourselves to just the given use-case.
    • “Building from lego blocks” starts on the atom level — in JSX. In Tailwind, we define a dictionary of properties the blocks can be built from.

Tailwind 2.x

• Do not use string interpolation to generate classnames. All Tailwind classes must be pre-generated before the React runtime. Failing to do this will result in bugs in the built website (not on dev) where some CSS is missing.
  • More details: https://v2.tailwindcss.com/docs/optimizing-for-production
• Remember to revise the purgelist and safelist in order to have your custom classes generated on build. Pay attention that it doesn’t generate classes you don’t use anymore, to keep bundle sizes low.

Deployment

Vercel