Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?
Design document for Bedrock 2.0.

Design document: Bedrock 2.0

Version 1.0. Sunday, May 3, 2020 / Johan Ronsse

Bedrock is a prototyping tool to empower designers to help ship real software. It focusses on the design perspective while at the same time providing an immensely helpful deliverable for development.

Nature of this document

This document is intended as a design document to talk about the reasoning behind the Bedrock 2.0 project.

Request for Comments

Your feedback on this design document is more than welcome. What do you think of the ideas in this document? Is solving this problem appealing to you? How would you contribute?

Problem statement

In order to make highly interactive experiences that have a great user experience, designers and developers need to work together.

However, they often have a different angle when working. Bedrock 2.0 aims to provide designers with an environment where they can meaningfully contribute to development, while providing tools that help with their mindset: feature validation, prototyping (i.e. figuring out the problem) and finally the quality of the end result.

A product designer typically meaningfully contributes to app development in 3 ways:

  1. by providing static designs using a design app
  2. by providing static HTML/CSS to development
  3. by directly working in the development environment

Bedrock 2.0 aims to provide a bridge between (2) and (3) by providing product designers with an environment where:

  1. They are writing front-end code that directly works with the development stack (i.e. using the templating logic of the framework used)
  2. They can create prototypes that can be tested before development to validate feature requests
  3. They can show new designs simply by sharing a URL, through branch-based deployment
  4. They can profit from existing component libraries on the development side to create designs that are integrated with the development workflow

Bedrock 1.0 features

If you are not familiar with Bedrock 1.0, this might be good to read.

In this section, you will find a listing of the two major features of Bedrock 1.0. All of these features should be part of Bedrock 2.0.

  • Prototype navigation
    • Automatic prototype navigation based on a dynamic route listing, with a hideable page tree
    • Page states: show the different routes in their different states (e.g. empty state, succsss state, error state)
    • A page index which lists all the possible pages in the prototype
  • Documentation (style guide): static pages where documentation can live, with the following categories
    1. Static documentation: simple pages, written in Markdown
    2. Component pages: a dynamic listing of components based on a set of file structure and metadata rules, which shows the different variations of a component, e.g. a button
      1. This documentation is enhanced with code examples
      2. Components are linkable with a # link
    3. Listing pages: a dynamic listing of design tokens, with typically 3 important pages: a list of used colors in the project, used typographic styles, and a list of icons
    4. Design pattern pages, which are a combination of (1) and (2)
  • Deployable: Bedrock is architected in such a way that the resulting prototype deployable on a URL. Using a branch-based system, several versions of the design can be compared to each other.

Differences with Bedrock 1.0

The difference with Bedrock 1.0 is that Bedrock 2.0 will consist of different variants. A Bedrock variant will work together with a parent framework (e.g. Vue, React) to provide an environment to develop code in that can be re-used in the actual development environment.

Three workflow examples

The following workflow examples show how Bedrock 2.0 can help with its 3 features, while being conceptually integrated in the development environment (as opposed to Bedrock 1.X, which generates a static website totally separate from the dev environment).

1. An example workflow for Ember.js using Bedrock 2.0 (Exhibit: prototyping)

Let us give an example of how you might use Bedrock 2.0 in practice.

The design team has designs in Figma. The development stack is Ember.js.

The developers have a production application that uses Ember. It uses Ember 3.X but the view layer doesn't use Ember Octane components yet.

The designers prepare new designs in their visual design app Figma. After a while, they have a need to prototype a new feature. They develop their visual design into HTML/CSS pages.

To develop their HTML/CSS pages in a productive way, they employ bedrock2-ember. This package provides them with an environment where they can develop components.

It contains the features from Bedrock 1 (see above), but applied to an Ember environment. This effectively means the designers use the same tools as the developers to create their code. They use ember serve, they write templates in Handlebars, they create Glimmer components.

The designers go on to test their product designs with real users. In lieu of a working backend they have provided fake data using placeholder JS objects. The users give their feedback on the demo, and the designers go on to implement the feedback. A 2nd test is held, and the feature is deemed ready to build.

The designers then make their HTML/CSS production ready. A design-savvy developer helps with some guidance regarding Ember Octane and its new syntax.

The design-savvy developer takes the prototype templates, which are already using Ember Octane components, and uses this prototype as a base to build out the feature in the real production app.

2. An example workflow for Vue.js (Exhibit: documentation)

Let's give another example, this time for Vue.js.

The design team has designs in Framer X.

The development stack is Laravel and Vue.js. Some parts of the application are pure Laravel, some are combined with Vue.js, some are using the new Livewire. There are also mini-apps within the overall architecture that are pure Vue.js and use the API directly.

The new designs are for a highly interactive part of the application that will be written in pure Vue.js as an SPA.

The designers prepare new designs in their visual design app FramerX. After a while, they have a need to prototype a new feature. They develop their visual design into HTML/CSS pages.

To develop their HTML/CSS pages in a productive way, they employ bedrock2-vue. This package provides them with an environment where they can develop components. Instead of static HTML, they write Vue.js SFCs (Single File Components).

During the process, they also document the components using the styleguide feature of Bedrock 2.0.

Illustration: Bedrock 2.0 styleguide in action.

The bedrock2-vue package employs Nuxt.js to provide a Vue environment in which a demo can be developed. Nuxt.js takes care of the routing and serves an as example of a typical Vue app.

As it happens, the development team also has taken a liking to Nuxt.js. After the feature has been validated, they use it to develop the real application. The developers employ the styleguide as a reference to build out the real app, and make an npm package out the Vue components.

In a next projects, the designers load in the npm package directly, providing a great link for a source of truth between design and development.

3. An example workflow for Svelte.js (Exhibit: deployable)

Let us take another look at working with another framework. Every framework is different, and every version of Bedrock aims to work in the “spirit of the framework”.

The design team has designs in Sketch. The development uses Svelte with Routify.

The new designs are for a documentation part of the application that will be written in Svelte + Routify using MDSvx.

The designers prepare a single design of one page in their visual design app Sketch. To build out the rest of the design, they feel it would be more interesting to work in the browser from an efficiency perspective.

To develop their HTML/CSS pages in a productive way, they employ bedrock2-svelte. This is essentially a modified version of the Routify starter package.

This package provides them with an environment where they can develop the documentation. They write a combination of Svelte components (which essentially consist of HTML), CSS and also provide some basic content.

When the designers are ready, they deploy their work using a simple command:

npm run deploy:now

The design for the documentation is deployed to a CI URL e.g. https://master.my-manual-demo.now.sh/ .

This URL is sent to the manual writer for reference of in what kind of enviroment his content would land. This eases the communication and through working together and seeing each others perspectives, a great documentation site takes shape.

Implementations

Existing implementations

Planned implementations

  • A version using Routify + Svelte
  • A version using Ember.js 3

How to implement a bedrock2-variant

In this section, some general thoughts about how to go about implementing a bedrock2-variant.

What is a bedrock2-variant?

A bedrock2-variant is a version of Bedrock that builds on a certain framework, and provides the expected features of Bedrock:

  1. Page tree
  2. Style guide
  3. Deployment

Providing either 1 or 2 is already of value.

Providing 1 with manual creation is also already of value.

Providing all 3 features with deep automation (like in Bedrock 1.0) delivers the ultimate value.

Naming a variant

A variant preferably takes on the name of:

bedrock2-[parent-framework]-[child-framework]

For example

  • bedrock2-vuejs-nuxt
  • bedrock2-svelte-routify
  • bedrock2-svelte-sapper
  • bedrock2-react-next

General

  • Consider the relationship between the templating logic and the expected output of a production app
Framework Templating logic
Vue.js Vue.js SFC
React JSX
Ember.js Handlebars
Svelte Svelte templates
Angular Angular SFC
  • Consider existing tools that are already maintained in their respective communities
Framework Existing tools
Vue.js Nuxt.js, Gridsome
React Next.js
Ember.js Empress, Ember itself
Svelte Routify, Sapper
Angular ?
  • Consider what a designer has to know to use the tools, and try to find a balance between what they would have to learn vs. how a simplified workflow would imply a worse deliverable
    • CLI: run a certain command or series of commands
      • Ideally, a single command to run a dev workflow, with no extra tools to install
      • Having to install LiveReload or BrowserSync is definitely acceptable & normal
    • Template language: learn a certain template language or logic?
      • It's inevitable to have to learn something new
    • Setup: go through a wizard with unknown options
      • E.g. nuxt.js runs you through a wizard with a bunch of options, but the designer does not care about the middleware used, do a bedrock2-variant for nuxt could already have sensible defaults

Feature: page tree - extended description

This section describes how one would implement the page tree feature.

It is described in a framework-agnostic manner, and thus it might feel a bit abstract.

Feature description

The page tree allows the user to view a list of possible pages (routes) by pressing a keyboard shortcut on any page.

The shortcut is Ctrl+M, but an alternative Ctrl+B shortcut also needs to be implemented for browsers where Ctrl+M is already mapped to another function.

Invoking this shortcut shows a list of pages. Ideally this list of pages is automatically generated from the routes, but a manual list in an include is definitely acceptable for a first implementation.

The fact that the page tree is visible or not has to be remembered across route changes. This can be implemented with a localStorage item that remembers the visible state. It is useful to tie this localStorage to the project name or a local variable (e.g. a random string) so that there is no chance storage item conflict when multiple prototypes are opened.

The styles from the page tree are ideally shielded from the rest of the implementation. In Bedrock 1.0 this is done by scoping everything to a .br namespace and providing SCSS variables to make sure the page tree can render correctly regardless of font sizing strategy. In Bedrock 1.0, we also provide variables to customize the page tree look.

Feature: style guide - extended description

This section describes how one would implement the styleguide feature.

It is described in a framework-agnostic manner, and thus it might feel a bit abstract.

Feature description

The styleguide is a separate route which lives as /styleguide.

Within the styleguide, the user sees an entirely custom layout which consists of a sidebar and a content area. The sidebar contains a list of static pages and components. The content area contains the content of the selected page.

There are 4 types of pages.

  1. Static documentation: simple pages, typically written in Markdown
  2. Component pages: a dynamic listing of components based on a set of file structure and metadata rules, which shows the different variations of a component, e.g. a button
    1. This documentation is enhanced with code examples
    2. Components are linkable with a # link
  3. Listing pages: a dynamic listing of design tokens, with typically 3 important pages: a list of used colors in the project, used typographic styles, and a list of icons
  4. Design pattern pages, which are a combination of (1) and (2)

The Bedrock2-variant should provide the user (designer) with an easy way to create a new page. An ideal implementation updates the navigation of the styleguide automatically based on the existence of files.

Feature: deployable - extended description [INCOMPLETE]

This section describes how one would implement the deployable feature.

It is described in a framework-agnostic manner, and thus it might feel a bit abstract.

A Bedrock2-variant should ideally come with a deployment strategy.

This section has to be expanded upon, but the easy way to describe this is that there should be a command to create a deploy, or that the deploy should be git-backed, after which a build can be created through the use of a continuous integration service such as Github Actions or CircleCI.

Addenda

Addendum A: Product team perspectives

This section is part of the reasoning why Bedrock exists, but currently has no specific place.

Developers are tasked with making the application work. Designers are tasked with the visual design and the user experience.

Now, this is a vast simplification. In a mature product team, everyone cares about the user experience, from the product manager to the backend engineer. There's also a lot of designers that have learnt parts of the development workflow, and the reverse: developers who are design-savvy.

The current development landscape (see addendum B. Development landscape) has moved towards Javascript-heavy applications.

Addendum B: Development landscape

This section can be helped to explain why Bedrock 2.0 could exist alongside Bedrock 1.X.

Over the past few years, the world of front-end development has moved to Javascript-heavy frameworks. Nowadays, people are building web apps in different frameworks. The most popular frameworks are React.js and Vue.js. Next there is Angular, Ember and some newcomers like Svelte.

These frameworks have their differences. Ember.js and Angular.js can be categorized under the "full-stack" frameworks in the sense that they can be used to build a complete application, end-to-end. Vue.js is marketed as the progressive Javascript framework, and can be used to enhance a web development stack that relies on traditional server-rendered languages, such as Ruby or PHP.

Vue.js can be put next Svelte, and to React, as frameworks which only concern themself with the view layer. If you need a server, or backend connectivity, you're going to have to make a combination with something else.

Intent of open source community logic

By providing a design document, and being open about our goals, the story of Bedrock becomes bigger than being an internal tool at our company.

What's in it for you (possible contributor)

As a contributor

  • you can learn about better design/dev workflows, design systems, prototyping by helping to build the tools used for this exact reason
  • you can work on a side project which might help in your main project
  • you can give back to open source

What's in it for Mono?

Why are we doing this?

We would love for more software companies to build software with an eye for design. We see a clear need to provide tools to make the design/development workflow process smoother. By providing this kind of tooling in the open, we are serving different goals at the same time

  • We profit from open source, by doing this, we give back to open source
  • If the quality is high, Bedrock is also an advertisement for the design services of Mono. We want to design at a very high quality level.

Code of conduct

We want working on Bedrock2 to be a friendly and welcome environment, and we will not tolerate any harassment or unwanted behavior. Be human, be nice to each other.

Intent of license

Bedrock2 will be MIT licensed and publicly available.

Proof of OSS stewardship

We have worked on Bedrock 1.0 for five years, pushing out 19 feature releases which have been versioned semantically.

A marketing site was created at https://bedrockapp.org/ including documentation and a blog.

We've created a CLI tool to upgrade Bedrock (bedrock-cli) and informed users of breaking changes.

We never reached a tipping point of external usage with Bedrock 1.0, but we are hoping to take the lessons learned and apply these to Bedrock 2.0.

Answers to possible questions

Why not simply branch off of the development environment?

  1. Designers typically want to focus on solving the design problem at hand, and not focus on:
    • Complex setups with Docker
    • Complex authentication setups
    • Private npm packages
    • Long build processes
  2. It is unlikely that the development setup matches the needs of prototyping.

Why not build out Bedrock 1.X to support other languages than Pug?

You can't simply integrate style templating into another environment without creating a massive development task, one that is in fact already handled by the frameworks build on top of frameworks (such as Nuxt.js).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment