What is Perfection.dev?

Have you ever created — or worked with — a website with multiple data-sources? Then you've probably experienced some frustration ... at least from the content creators!

In modern, headless solutions, data come from multiple sources. You might have content coming from both ContentStack and Contentful, while product-data are coming from Commercetools, assets from Cloudinary etc.

For content creators, this can be a frustrating experience: the simple task of knowing where a piece of content is coming from, can be a daunting experience.

Perfection.dev is a collection of tools designed to ease the workflow of content creators in the preview-environment†) of your website:

1. Deep Links
2. Section Designer
3. Component Designer
4. Collaboration
5. Launchpad

†) It's important to mention, that all the code and examples below, are only necessary in the preview-environment of your website. In your framework of choice, simply add a method to only add the required data-attributes in preview-mode.

Install

To install Perfection.dev, simply run:

npm install @perfectiondev/oversite

You then initialize the script:

if ('oversite' in window) 
  window.oversite.initialize([config])

Now, when loading your site, you'll see a dock at the bottom of the screen:

Let's dive further into each feature.

Deep Links

Finding the right content record to edit in your commerce, DAM or CMS can be challenging. Save time and reduce risk of errors with Perfection.dev's Deep Links, that leads you straight to the live content in the underlying system.

Perfection.dev comes with an Admin Panel where you can set up and configure our services. Here, you can add providers (ContentStack, Commercetools etc.), and then — in the code of your website — simply add a data-pf-attribute with required information for each piece of content, you want a deep link to.

As an example, here's Contentful:

<div data-pf='{
  "providerId": "contentful",
  "entryId": "abc1234"}'>
  <h1>Hero Title</h1>
  <p>Hero Description</p>
</div>

With just this little snippet, Perfection.dev adds outlines around selectable content, and a small "Edit button" (top left):

ContentStack requires a few more parameters: contentType, locale and entryId — and so on.

Perfection.dev comes with configuration-examples for:

• Contentful
• Contentstack
• Commercetools
• Kontent.ai
• Prismic
• Content Hub One
• Sitecore XM Cloud (Content Editor)
• Sitecore XM Cloud (Pages)
• Storyblok

... but you can easily add your own provider.

Section Designer

The Section Designer comes with 70 out-of-the-box section-types, which contain column- or grid-based layouts for your content:

Most sites only require a few section-types, so you simply add the ones you need in the Admin Panel.

A Section consists of an outer and an inner part. A decoration can be applied to the outer-part only. That's a custom CSS-class, you add in your own code — and can be whatever you desire: a background-color, a linear-gradient, a box-shadow etc.

Decorations can then be synced with Perfection.dev's CLI (more on that later), and they'll show up in the decorations-tab:

Finally, the Section Designer allows you to control the width of both the outer- and inner parts:

These widths can be configured through seven CSS Custom Properties.

If the 70 out-of-the-box types are not enough, you can easily create your own section-types:

Creating a Bento-Layout with Perfection.dev

Mads Stoumann for Perfection.DEV ・ Nov 14

#webdev #css #tutorial

To manage custom section-types and decorations, you create a theme.json file:

{
  "name": "Your Theme",
  "description": "",
  "key": "your-theme",
  "decorations": [],
  "layouts": {
    "prebuilt": [
      "col_100",
      "col_50_50",
      "col_25_25_50"
    ],
    "custom": []
  }
}

You then run a command to sync with the CLI, and the theme will appear in the Admin Panel.

Component Designer

The Component Designer is a tool to create visual editors for content creators. As a developer, you decide which parts of a component should be modifable by a content creator. This can be as simple as changing the font-size for a headline from a list of allowed values — to a full-fledged, advanced component.

In the example below, content creators are only allowed to change the color of the banner, and change the font-sizes of the price and title-fields:

The visual editor is generated automatically based on a [component-name].json-file for the given component.

In this case, the file looks like this (excerpt):

{
  "key": "card-component",
  "name": "Card Component",
  "description": "A Simple Card",

  "elements": [
    {
      "name": "Banner",
      "selector": ".card__banner",
      "properties": [
        {
          "name": "Color",
          "values": [
            {
              "name": "Black",
              "value": "bg-black",
              "display": "#000"
            },
            {
              "name": "Gold",
              "value": "bg-gold",
              "display": "#ba933e",
              "default": true
            }
          ],
          "ui": "ui-colorgroup"
        }
      ]
    },
    {
      "name": "Title",
      "selector": ".card__title",
      "properties": [...]
    },
  ]
}

ui-colorgroup is just one of the many ui-elements that Perfection.dev provides, so developers can create rich, visual experiences for content creators.

You place all the [component-name].json-files in a folder, that you then add to the theme.json-file:

{
  "name": "Your Theme",
  "description": "",
  "key": "your-theme",
  "decorations": [],
  "layouts": {},
  "componentFolders": [
    "./components/"
  ]
}

Next, you sync with the CLI, and the components will appear in the Admin Panel.

Styles or Presets

Sometimes, having too much creative freedom, can result in components deviating too much from the brand style-guidelines.

In these cases, it's better if content creators can simply toggle between various "style configurations", instead of picking styles themselves.

These are called "presets" in Perfection.dev — and are added as an array of configuration-objects in the [component-name].json-file — and appear like this in the app:

Collaboration

Until now, it's been almost next-to-impossible to collaborate on content coming from multiple sources.

With Perfection.dev, you can add comments and assign tasks directly on your web pages, ensuring context-driven discussions and quicker resolution of issues.

Unlike Deep Links, Section Designer and Component Designer, you don't need to do anything in your source-code to enable Collaboration.

You simply toggle the feature on in the Admin Panel.

Launchpad

The Launchpad distribute essential links to your organization's tools and systems to your teams via a centralized hub, available from Perfection.dev's dock:

You manage the links and icons in the Admin Panel.

In the next post, we'll look into how you use Perfection.dev run-time.