What is Perfection.dev?
Tags: webdev, headless
Published: 2023-11-18 14:31:10

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:

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

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

![Dock](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/iqfb4itun36nmrrbvhvq.png)

---


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:_

```html
<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):

![Deep Links](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/4eb4et6flpx1vzp8tmdv.png)

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:

![Section Designer](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/l76anvgztfmor7e4qn2a.png)

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:

![Decorations](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ul95ftaeofsoq8dcsin7.png)

Finally, the _Section Designer_ allows you to control the **width** of both the **outer-** and **inner** parts:

![Widths](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/jmimv2rnxwzqy67nd51c.png)

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:

{% link https://dev.to/perfectiondev/creating-a-bento-layout-with-perfectiondev-39jj %}

---

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

```json
{
  "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:

![Component Designer](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/cbpfnymwh9fqwbj0sp6q.png)

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):

```json
{
  "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:

```json
{
  "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:


![Presets](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/72z8dwceolo9t2nu8jp4.png)

---

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

![Comments](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/5rlay78ulml4zoy3darv.png)

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:

![Launchpad](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/b2ra5776ickxhy9c3f1r.png)

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