Handoff Handbook

Goals

Building a bespoke, high-performance site is a cross-team effort. Blinkk will work closely with the design team to ensure we faithfully execute the designs and work with the client team to ensure we meet business goals.

In the project, Blinkk’s focus is on writing code and performing configuration to build and launch the website. We can provide guidance and education on best practices for designs and content, but our primary involvement is execution. As a result, we look to the design team to conduct all design work, and the client team to write copy.

The Handoff Guide will provide a foundation for partners creating design deliverables while working with Blinkk, helping both teams:

  • Reduce onboarding, design, & development time
  • Reduce bugs / VQA time
  • Decrease design & code redundancy
  • Use a common design language across teams

Design-to-development handoff

New page creation and reusable modules

Blinkk builds every module to be reusable from a technical standpoint. Modules are the building blocks of a page. They can be mixed and matched across existing pages, and on new pages, with important caveats:

  • While modules can be reused from a technical standpoint, they may not be easily reused from a design standpoint. For example, two modules may have been initially designed to be adjacent to each other, and due to their specific design, it may not be appropriate to reuse those modules in other places.
  • Once a design is created and modules are built, they may be reused, and mixed and matched in unexpected ways in the future. As a result, in practice, module reuse may not always be practical, unless the module was specifically designed to be re-used.

What makes a module reusable?

  • From a design standpoint, it should stand well on its own, and not have any dependencies on modules before or after it. For example, the module shouldn’t bleed or extend onto its neighbors.
  • It should have clear, consistent padding and spacing, so it looks “correct” amongst its neighbors.
  • It shouldn’t make any assumptions about the modules that come before or after it. If a module only works amongst certain neighbors, and if we want it to be reused elsewhere, rules should be created around its reuse.

What makes a module unique versus a variant?

Modules in nature, should be designed with some level of flexibility. Certain components can be removed, added, or rearranged while still being considered a variation of the same module. Some examples of module variants:

  • Text alignment (left/center/right)
  • Image and text placement (left/right)
  • If an component can be removed or added without affecting the alignment of the other module components (e.g. icon, image, text, button, etc.)

However, there are some things that distinguish one module from another module:

  • Functionality
  • Animation
  • Layout shifts within the module's grid
  • If a component is removed or added and it does affect the other module components
  • Responsiveness as it relates to the grid
  • Max-width or tablet strategy

Naming modules

Why and when we name modules

  • As part of the development handoff, the cross-team should define module names for each section of the website. We will leverage the module names in the code, inside issue tracking, and verbally when referring to modules.
  • The naming exercise is critical to project maintainability and efficiency before and after launch. Basically, the purpose of naming modules together is to get designers and engineers speaking the same language.

How we name modules

There isn't a singular module library or module naming convention that can be applied to all projects. Instead, teams can use certain principles to help them create their shared language for any given project. Module names should be:

  • Intuitive — Naming across the design system should be simple and clear while offering guidance when possible. Clarity is a better measuring stick than accuracy.
  • Consistent — Design documentation and the component code library should follow the same structure and labeling.
  • Scalable — Maintain broad naming structures, flexible labels, and flat organization to optimize for scalability.

What to avoid

When naming modules and components, teams should avoid:

  • Using code names for confidential products and features or using project-specific puns and cryptic language
  • Using numbers and symbols
  • Focusing on the module role
  • Using the module placement (remember that modules should be able to be moved and used almost anywhere on a page)

What we need the design team to do

  • Provide high fidelity designs in Figma
  • Provide style guidelines or a style sheet within the design file
  • Export assets (i.e. background colors and content): the design team should export files for Blinkk, so our developers do not need to undergo the activities of a production designer.
  • Work with the dev team throughout the course of the project to ensure all files are formatted correctly and that modules are being built to design’s specifications.

Design file formats

  • Figma files
    • Final design files should include both desktop and mobile mocks
    • Include tablet mocks if any designs use “50/50” modules, e.g. if any modules may not work well on tablet-sized screens. See example
    • Max width: Illustrate the “max width” strategy for the designs. Ensure the following questions are answered:
      • Is there a site max width? If so, is it applied to all elements, or just some?
      • Is there a content max width? (On different viewports)
      • Typically, projects will have a site max width of 1920px. Some projects will have “fullbleed” modules whose background image or color extend to the sides of the max width, or viewport.
    • Ensure that the grid overlay is applied to all files and can be toggled on/off
    • Style guidelines/style sheets
      • Create an artboard that outlines all the different type styles and apply those styles across all modules/pages (i.e. desktop mock will show LG/Heading 1, same mock on mobile will show SM/Heading 1, etc.)
      • Consolidate type styles and avoid using one-off or custom cases
  • Exported files should be delivered into a Google Drive folder. One folder per page.
  • Exported files should follow the below specs:
    • Images
      • 2x the natural size: as defined by the design
      • Cropped to correct aspect ratio as defined by the design
      • Separate files for desktop and mobile
        • If the aspect ratio/crop is identical between desktop and mobile, only the desktop asset is needed
      • JPG for lifestyle photography
      • PNG for product UI and/or anything that requires transparency
      • SVG for icons and most logos
    • Motion
      • Provide a motion study to use as reference for on-page motion
      • Easing and timing specifications
    • Videos
      • Web-ready MP4 files: small file size ( i.e. ~2 MB of less)
      • Larger files can be provided and used, but larger files will cause the page to load more slowly
  • Exported images and videos should follow consistent naming conventions:

Pattern:

{page}_{module number}_{template name}_{image name}

Example:

homepage_m1_hero_welcome.png

If an instance has multiple images:

{page}_m{number}_{template}_{image name}-1
{page}_m{number}_{template}_{image name}-2
If cropping differs between desktop and mobile:
{page}_m{number}_{template}_{image name}-desktop-1
{page}_m{number}_{template}_{image name}-mobile-1
{page}_m{number}_{template}_{image name}-desktop-2
{page}_m{number}_{template}_{image name}-mobile-2
  • Animations in Lottie (see Lottie website)
    • Designing
      • Lottie files are exported, and then sized to a specific sizing strategy. Put simply, in most cases, Lotties will be sized similarly to either CSS background cover or CSS background contain, plus vertical or horizontal centering.
      • Full-screen Lotties (or Lotties that cover the background of a page element) should be designed with this assumption.
      • Inline Lotties should be designed as normal inline assets, and cropped appropriately.
    • Exporting
      • The exported Lottie file must work with Lottie’s Canvas renderer in order to maximize performance. The SVG renderer can only be used for small Lottie animations, and generally should be avoided. Unfortunately, Canvas mode doesn’t support the same features as SVG. It’s recommended to test your file early to ensure it works with Canvas mode, and avoid After Effects features that are unsupported in it.
      • Avoid Track/Alpha Mattes and other features that are incompatible with Canvas mode. See full supported features.
      • Review supported blend modes.
      • Minimize (avoid if possible) use of blurs and blurred shadows. They are expensive and reduce performance.
      • For any embedded assets (i.e. raster images or videos), export them separately and do not embed them directly within the Lottie data. Exported assets should be sized to 2x their natural size.

Accessibility

Blinkk builds to be accessible, but accessibility is a team effort. In addition to the above technical considerations, we need the following from the cross-functional teams to reach proper accessibility:

  • Color contrast of designs and UI components (text, etc.) must be sufficiently high
  • Focus states for custom components user dependent on keyboard navigation
  • Proper alt text (copy) must be written for images
  • Proper error states for form fields must be designed and written
  • Aria labels in website copy should be clear and actionable

--

Communicate design changes

  • New versions of existing designs
  • Creating alternate designs
  • Deprecating old designs
  • Unused / hidden layers in designs

Annotate final designs

  • Communicate design options
  • Interactions / animations
  • Define template/module/asset name

Export assets

  • File types
  • File size (performance)
  • File naming convention
  • TODO: Sample asset folder

VQA

  • Enable grid overlays on staging URLs
  • Screenshot staging at breakpoints defined in designs

The design team will be responsible for filing VQA bugs in Asana/Buganizer once staging is completed. In order to swiftly fix issues, we ask the design team to provide:

  • A description and screenshot of the issue as it exists on staging
  • The URL to the page where the issue is present
  • Redlines or written guidelines of the expected fix
  • Links to updated exports or materials

--

Figma project template

  • Copying the template
  • Using Figma styles vs components
  • Defining grid styles
    • Defining breakpoints
    • Breakpoints vs page layout widths
  • Defining color styles
  • Defining type styles
  • Creating components
    • Reusability
    • Variations
  • Using Figma pages vs frames
    • Use single Figma page for all web page designs
    • Use Figma frames for individual web pages

Additional resources

Design handoff checklist

Click to copy Blinkk design handoff checklist in Google Sheets