DEV Community: Measured

Puck v0.16: Permissions

Chris Villa — Tue, 17 Sep 2024 14:00:09 +0000

Puck is the open-source visual editor for React built by Measured - a self-hosted alternative to builder.io, WordPress and other WYSIWYG tools.

We're celebrating 5,000 stars on GitHub! Thank you to our wonderful community!

Puck v0.16 is a big release, introducing the headline permissions API and — you guessed it — quality of life improvements. This one took a while to put together, and we appreciate your patience and support.

Permissions: Toggle Puck features like duplication, dragging, deletion through the new permissions and resolvePermissions APIs.
Action bar override: Create custom action bars using the actionBar override, or extend the default one using the new <ActionBar> component.
iframe style injection: Access the iframe document to inject styles directly, or make other changes, via the new iframe override. We also introduced the emotion-cache plugin for the common Emotion use-case.
History injection: Inject the undo/redo history via the a series of new APIs
React to actions: React to actions dispatched by Puck via the onAction callback.
Optional fields: Optional props are no longer required to define in fields, since they may be defined

Upgrade today or get started with:

npx create-puck-app@latest

Permissions

Permissions enable you to toggle core Puck functionality globally, on a per-component basis or dynamically. Huge thanks to @xaviemirmon for his efforts on this.

export function Editor() {
  return (
    <Puck
      permissions={{
        delete: false,
        duplicate: true
      }}
    />
  );
}

Action bar override

The new actionBar override enables you to create a custom action bar overlay, or extend the default one using the <ActionBar> component:

const overrides = {
  actionBar: ({ children }) => (
    <ActionBar label="Actions">
      {/* Render default actions */}
      <ActionBar.Group>{children}</ActionBar.Group>

      {/* Render new actions */}
      <ActionBar.Group>
        <ActionBar.Action onClick={() => console.log("Clicked!")}>
          ★
        </ActionBar.Action>
      </ActionBar.Group>
    </ActionBar>
  ),
};

iframe style injection

The iframe override enables you to access the iframe document, making it possible to inject styles into the head:

const overrides = {
  iframe: ({ children, document }) => {
    useEffect(() => {
      if (document) {
        document.body.setAttribute("style", "background: hotpink;");
      }
    }, [document]);

    return <>{children}</>;
  },
};

The new emotion-cache plugin uses this API to create an emotion cache inside the iframe, making Puck easy to use with any Emotion-based component library.

History injection

Use the new history injection APIs to provide your own undo/redo history via the initialHistory prop, or dynamically via the setHistories and setHistoryIndex functions from usePuck().history.

const historyState = {
  data: {
    root: {
      props: { title: "My History" },
    },
  },
};

export function Editor() {
  return (
    <Puck
      initialHistory={{
        histories: [{ state: historyState }],
        index: 0,
      }}
      // ...
    />
  );
}

React to actions

The onAction API enables you to react to Puck’s internal actions as they’re dispatched:

export function Editor() {
  return (
    <Puck
      onAction={(action, appState, prevAppState) => {
        if (action.type === "insert") {
          console.log("New component was inserted", appState);
        }
      }}
    />
  );
}

Breaking changes

`history.data` is now `history.state`

When using the usePuck history API, data is now renamed state.

`history.id` is now optional (TypeScript)

When using the usePuck history API id is now optional. Puck will always generate an id, but TypeScript may complain.

`lastData` is now returned as `null` instead of `{}` when empty in resolvers

When using the lastData option provided to resolveData or resolveFields functions, and there is no previous data, lastData will now be null instead of {}.

Full changelog

Features

add actionBar override for adding component controls (48ec0d7)
add automatic RSC export, replacing /rsc bundle (d21eba6)
add isDisabled prop to Drawer.Item (cad95b8)
add generic type to usePuck hook (01703a9)
add iframe override for style injection (7cac376)
add initialHistory prop to Puck (54b5a87)
add onAction API to track and react to state changes (c7007ac)
add permissions API (a43914d)
add plugin for injecting Emotion cache (f8a88b9)
add resolvePermissions API (f0655f0)
add waitForStyles option to iframe config (bc81d9c)
call resolveData when new item inserted (3298831)
don't mandate fields for optional props (5a219ef)
export ActionBar component for use in overrides (04fd6c5)
infer Data type from user config (50045bb)
make ID optional in History type (BREAKING CHANGE) (d917229)
provide ES Module build (ff9076b)
rename history.data to history.state (BREAKING CHANGE) (b09244c)
show spinner if iframe load takes over 500ms (cfecf54)
streamline usePuck history API (c8b2807)
upgrade "next" recipe to typescript@5.5.4 (60fe631)

Bug Fixes

add favicon to next recipe to prevent Puck 404 (2c52d27)
add missing readOnly state to External fields (bf1449d)
always record history on component insert (88c5ab6)
don't cache /edit route in Next recipe (94f16b2)
don't submit buttons if Puck used in form (f761e5f)
ensure demo types are satisfied with TypeScript@5 (958dc25)
export missing Plugin type (eb42734)
fix crash if component in data is missing from config (0daf478)
improve resiliency of iframe CSS for some frameworks, like Mantine (538cb05)
make Config and Data types more robust (6bcf555)
prevent infinite loop when using plugins with some frameworks (3870871)
prevent Tailwind from clashing with viewport zoom select (9151255)
remove body margin in remix recipe (0898b26)
resize viewport when changed via app state (14419ec)
resolve fields when switching between items of same type (a3518ca)
return lastData as null instead of empty object in resolvers (BREAKING CHANGE) (648eb92)
show warning if heading-analyzer styles aren't loaded (4e7110b)
use correct color in FieldLabel labels (b0469a1)

New Contributors

@mkilpatrick made their first contribution in https://github.com/measuredco/puck/pull/505
@nova4u made their first contribution in https://github.com/measuredco/puck/pull/538
@antonmalyavkin made their first contribution in https://github.com/measuredco/puck/pull/585

Full Changelog: https://github.com/measuredco/puck/compare/v0.15.0...v0.16.0

Don’t build a design system — build what you actually need

Paul Love — Mon, 09 Sep 2024 14:49:47 +0000

Saying you need a design system is like saying you need a vehicle. It might take you somewhere, but without a clear destination, you risk ending up lost.

This post looks at why the term design system isn’t that useful, and how to arrive at the outcomes your organisation needs.

Where design systems come from

Design systems evolved from the corporate identity manuals and style guides of the later 20th Century.

The NASA Graphics Standards Manual from 1976 is a notable example, prescribing everything from letterheads to spacecraft insignia in exacting detail.

Later, these guides became digital and began to include pattern and component libraries. In some cases, they merged into a comprehensive library and were given the name design system.

The Salesforce Lightning Design System, released in 2015, helped popularise the term. It’s a comprehensive tool to help teams design and build digital products and services as a whole.

More detailed accounts of the origins of design systems are available¹.

Siloed definitions

Holistic design systems are powerful, but not well-suited to the siloed disciplines we see in big organisations today. (That’s without considering broader systems that cover content strategy, voice and tone guides, internal processes, dishwasher policy…)

To be useful in their day to day work, individual disciplines have carved out their own versions. So design system has come to mean different things:

Brand identity systems. E.g. NASA’s Brand Guidelines.

Component libraries. E.g. The GOV.UK Design System is a well-considered case, but they can be more ad hoc.

Design components and standards. E.g. Volkswagen’s system for VW and sub-brands, discussed in Into Design Systems, presented by Matthias Fritsch and Thorsten Jankowski. It could also be for a product or single brand identity.

Design assets. E.g. Uber’s Base is Figma-heavy (which is usual) and geared towards designer needs. These may be organised to in varying degrees. The distinction is that there’s no accompanying technology implementation.

Fully-integrated design systems. E.g. Salesforce Lightning Design System, Google’s Material Design, IBM’s Carbon and Microsoft’s Fluent. These include guidelines, components and technology.

When a term means different things to different people, it’s risky to use in a general setting. Even the word design can imply ownership by one team. That sometimes makes sense, but it’s controversial as a universal rule.

Designers don’t want to worry about brand or engineering needs, just as engineering teams might overlook the needs of designers². For a design system to succeed, it must meet cross-functional needs.

Build the right thing

Instead of saying you need a design system, identify the problems you want to solve. Here’s how.

1. Set goals

Set clear, outcome-oriented goals that align with your organisation’s objectives and teams’ needs. Make sure everyone buys into them to the extent possible.

Identify non-goals too, like deprioritising internationalisation if you only serve UK users.

Ask questions to agree goals:

What does the business do?
What problem do you want to solve?
What are the user needs, internally and externally?
What results you want to see?
What are the accessibility implications?
What countries do you operate in?
What is your technology stack?
What are the brand implications?

When you set the right goals, it doesn’t matter if you call it a design system. Call it what you like.

2. Define terms

Clearly define what your solution does, and what it includes.

When we helped BT implement Arc, we called it a UI system³. And we defined this as:

… a collection of tools and practices that help teams working on BT Enterprise digital products build high quality web user interfaces at scale.

Adding a definition beyond the term helped everyone understand what Arc was supposed to achieve.

3. Communicate openly

Internal communication is vital. Everyone with a stake needs to know where they can see progress, and ask questions.

Consider week notes and frequent demos. These help communicate changes, from small refinements to what you’re building up to revisiting the main goals.

Having the project history in the open helps new joiners get up to speed. Sharing progress gives everyone the chance to flag issues at the first opportunity.

4. Expect change

Design your system with change in mind. The project should adapt as your understanding develops. This is especially important for projects that cut across many disciplines and teams.

Involve relevant people as early as possible, but understand that waiting for everyone can halt progress. Create processes that incorporate new information and perspectives as they emerge.

We sometimes hear that discovery work and goal-setting slows down work being done. Make it a goal to support the progress of the teams you’re working with. Design iterative processes, and avoid blocking other teams.

The most important thing

Unclear terminology shouldn’t stop you from doing good things. If you set goals, define terms and get the right people in the room, you stand every chance of building what your organisation actually needs.

Brad Frost explores the origins of design systems in the opening of his talk, A Global Design System. Jay Hoffman’s From designing interfaces to designing systems is worth a read. ↩
Tools like Figma and Storybook are powerful collaborative tools for designers and developers respectively, particularly in enabling feedback. But they can calcify design systems into something that solves the needs of one discipline while disenfranchising others. This isn’t an inherent weakness of these tools. They’re tailored to the needs of the relevant discipline, and not intended to house design systems for organisations. Yet, this is the reality of what happens in large organisations where siloed working is the norm. ↩
If they’d been called UI systems to begin with, we might have avoided this confusion. We’re not the only ones saying this: See this X thread with Nathan A. Curtis and Brad Frost. We tend to say UI system rather than design system. It’s a more accurate description of building systems to create web UI, and it helps set expectations. But if a client wants to call it a design system, we won’t argue. ↩

Puck 0.15: Dynamic fields

Chris Villa — Wed, 21 Aug 2024 08:31:11 +0000

Puck v0.15 introduces powerful new field APIs and numerous quality-of-life features.

Dynamic fields: Use the resolveFields API to dynamically define your fields - great for showing fields conditionally or loading external APIs.
AutoField component: Build custom fields using Puck's own field component for a seamless UI.
Override the Publish button: Swap out the publish button without swapping out the entire header.
Context-aware components: Modify component behaviour based on whether it's inside <Puck> or <Render>.

Upgrade today or get started with:

npx create-puck-app@latest

Dynamic fields

Dynamic field resolution via the resolveFields API allows you to change the field configuration whenever the props change. You can use this to show and hide fields or even load data from an API.

Code example:

const config = {
  components: {
    MyComponent: {
      // ...
      resolveFields: (data) => ({
        myField: {
          type: "radio",
          options: [],  // Populate dynamically
        },
      }),
    },
  },
};

AutoField component

The AutoField component lets you render a Puck field based on a Field object. Use this when building custom fields that need to use Puck-style fields internally.

const CustomField = ({ onChange, value }) => (
  <AutoField field={{ type: "text" }} onChange={onChange} value={value} />
);

Override the Publish button

It's now possible to implement a custom Publish button without overriding the entire header by using the headerActions override.

<Puck
  overrides={{
    headerActions: ({ children }) => (
      <>
        {/* children will render default Publish button */}
        {children}
        {/* Or you can define your own */}
        <button>Click me</button>
      </>
    ),
  }}
/>;

This creates a breaking change for existing headerActions overrides, which will now need to render children to show the default Publish button.

Context-aware components

Components now receive the puck.isEditing prop. Use this to toggle functionality based on whether the component is being rendered in the <Puck> or <Render> context.

const config = {
  components: {
    MyComponent: {
      render: ({ puck }) => (
        <div style={{ background: puck.isEditing ? "hotpink" : "transparent" }}>
          Hello, world
        </div>
      ),
    },
  },
};

Breaking changes & deprecations

`headerActions` override must now render `{children}` (BREAKING CHANGE)

In order to support custom Publish buttons, the headerActions override will no longer render the default Publish button unless children are rendered.

<Puck
  overrides={{
    headerActions: ({ children }) => (
      <>
        {/* Render default Publish button */}
        {children}
      </>
    ),
  }}
/>;

Undocumented `editMode` API deprecated

The undocumented editMode prop is now deprecated in favor of puck.isEditing.

Full Changelog

Features

add AutoField component for using Puck fields inside custom fields (106028b)
add isEditing flag to puck object prop (13bb1bd)
add resolveFields API for dynamic fields (0a18bdb)
allow data prop to accept an empty object (aedd401)
bump next recipe to Next@14 (47a27ed)
enable override of publish button (breaking change) (480467a)
expose previous data to resolveData via lastData param (dd7051e)
replace history chevrons with undo/redo icons (91dff22)

Bug Fixes

align Drawer behaviour and docs with expectation (e2cd445)
animate loader in iframe (151a267)
don't inline link stylesheets for more predictable behaviour (c0a331d)
don't overflow external inputs inside arrays/objects (42ef582)
don't throw warning when user is correctly specifying root props (46aa8ff)
don't unintentionally use read-only styles in external fields (acaf727)
fix defaultProps for root (9a1cc7c)
infer correct value types in Custom fields (5c8c0e1)
position field loader relative to sidebar, not fields (2e8936e)
show external field modal when using custom interfaces (6e97a0e)
show field loader when using field overrides (8ccfa4c)
still load iframe if styles fail to load (3e56bc1)

See the GitHub release for the full changelog.

Community

We're grateful for the community's support and contributions. Join the conversation on GitHub and Discord.

Contributors

A huge thanks to all our existing and new contributors:

@goynang made their first contribution in https://github.com/measuredco/puck/pull/487

Scott’s Law of Rebrands

Paul Love — Tue, 25 Jun 2024 09:14:23 +0000

Over time, the probability of a rebrand starting in the midst of a large web project approaches 1.

—Scott Boyle, Measured Co-Founder

Like any good axiom, Scott’s Law of Rebrands was borne of experience. We’ve seen it happen enough that we know to it be universally truthy. (We call it Scott’s Law with tongue lodged firmly in cheek, of course.)

For our purposes, this is a rebrand that falls outside the scope of your project, but which will affect it in myriad knotty ways.

Out-of-scope rebrands always pose challenges, but approaching them the right way can bring long-term benefits to your project.

The imbalance of probabilities

Rebrands happen, and for any number of reasons. It may be to reposition in the market, to serve a new or evolving context, or to breathe new life into a stale brand.

Even when a rebrand isn’t on the cards, people are always tinkering at the edges. Technology and humanity are never finished, and so brands continually evolve. Duncan Nguyen’s Medium post on the evolution of Apple’s design language captures this well.

Brand visual identities tend to have a shelf-life of 2 to 5 years. So the odds of one overlapping a major web project are high, and only grow higher with time.

Accept the cards you’re dealt

A major rebrand inevitably disrupts a large web project running in parallel. There will be weeping and gnashing of teeth—for at least a day or two.

Likely questions from your digital teams:

What is the scope of the rebrand?
When is it starting?
How long will it take?
What are the practical implications for my project?

No one has the answers to these questions at the point of a rebrand kick-off. All you know for sure is that it’s happening, you won’t have total control over it, and it will take as long as it takes.

Ongoing communication with brand and marketing teams is vital. They’re often siloed from the people that will implement, which only adds to the complexity. (Though this is mitigated for digital brands.)

So make friends with the brand and marketing teams. We’ve learned from experience how important it is to create two-way feedback mechanisms between these and your implementing teams over the course of the project or rebrand.

Get on the front foot

When you’re surrounded by uncertainty, a good approach is to mine that uncertainty for opportunities to build something better.

You can do that with some straightforward architectural thinking. Here are three things you can do to get on a positive footing.

1. Figure out what can be systematised

Start by looking at what aspects of the existing branding can be systematised. For example:

Colour schemes and their contextual uses
Typography (e.g. type sizes, typefaces, fallback font stacks)
Icons (size, location, design descriptors)
Spacing and alignment (e.g. margins, component spacing, vertical rhythm)
Motion (e.g. timing, duration, motion descriptors)

Systematising the brand helps with consistency which will lead to more-polished UI. It also makes the brand easier to understand as a whole, which helps to assess the impact that changes will have. This helps you move from the mindset of “oh no, there’s a whole bunch of stuff to do” to “here’s what we’ll need to do”.

2. Encode the brand

When you’ve identified what can be systematised, a logical next step is to derive variables for those systems. Do this everywhere possible.

This doesn’t necessarily mean creating design tokens, although it probably will. The aim is to make it easy to change any aspect of the brand identity as needed. We sometimes call this encoding the brand.

Some would say that this process can cover all aspects of a future rebrand, but that isn’t the case. There will always be outliers: things that can’t be made into variables, not to mention new emerging needs.

But it does make your implementation as rebrand-ready as possible, and it makes tweaks to the branding trivial to implement.

3. Plan for flux

This point is a bit more holistic. Avoid thinking that brand work, and the digital gubbins around it, is ever finished.

Versioning is essential. We label and communicate versions clearly, so everyone can see what’s changed, and make informed decisions about when to adopt. (We recommend Semantic Versioning.)

Communication is vital. Call out changes and updates in a visible and timely way for the people that need them.

With robust versioning and good communication, your organisation can safely manage changes to your system.

Strength from flexibility

Reality is always messy and the future is unknowable. But by doing everything you can to systematise your brand and plan for future change, you’re laying the best possible foundations for success.

Things will go better when you see curve balls like rebrands as a chance to make your systems robust. When you make things adaptable, you stand to save the organisation time and money in the long term.

How to do great live demos—and why they’re important to get right

Paul Love — Mon, 10 Jun 2024 09:05:29 +0000

Live demos are a staple of digital teams. They’re the most efficient way to show progress and get feedback about your project. Seeing working products, services and features in action is the best way to help people understand them quickly and easily, hence: show the thing.

And they’re important to do well. Good demos build trust in what you’re building, and the people building them. But because they’re so ingrained in our work cycles, they can become stale. Here’s what we’ve learned works well over our years of practice. Hopefully this will help keep your demos interesting and useful to others. (Feedback welcome!)

What we mean by live demo

By a live demo, we mean one that’s happening now. But not necessarily in person. Online demos have become normal. They’re easiest for large, distributed organisations, which is why we advocate for remote-friendly tools.

We’re working on the assumption you’ll use your organisation’s preferred calls and screen-sharing app, whether that’s Teams, Zoom, Hangouts or whatever.

What, when and who?

We recommend breaking out of the cycle of demoing anything just because a sprint schedule says it’s time. If you have something interesting to show at the end of a sprint: great.

If you find yourself wondering what to demo, that’s a sign that things can be improved. Do away with “demos” that amount to status updates. Status updates are useful, but not interesting. Write week notes instead.

Another benefit: you’ll break the pattern of different teams demoing at the same time. This can mean teams end up demoing to themselves, which is beyond pointless.

What to demo

So what should you demo? For us, there are three criteria:

Is it visual?
Is it interesting?
Will people understand it?

If the answer to all of these is yes, demo it. Especially if you’re showing something that’s new to the organisation. Design systems are a great example.

When we say visual, we don’t mean pretty. For example, we’ve found showing design tokens as text strings helps make them tangible and easy to understand. If you’re not familiar with design tokens, you can think of them as small pieces of a brand’s design system that are likely to be used again and again, like the font on a button. They’re easier to see than imagine:

It’s OK to show a small unit of work. It works well if it’s something people have been asking for. It shows you listen and sweat the details. So long as it’s interesting in some way, demo it.

But, if you don’t have at least 15 minutes of stuff to show and talk about, it’s not worth the time and effort—for you or others.

For example, code refactoring is important work, but doesn’t make a good demo. Neither do things you’ve built and thrown away. Unless they contribute to a broader narrative—and an interesting one—nobody cares. Gauge by interestingness of work, not value.

When to demo

Share things as soon as possible to get feedback early. Constructive feedback is like sunblock: better sooner than later.

Demo frequently. If a project is likely to run for a few months, demoing weekly is great. On longer projects, we tend to demo every few weeks. It can be OK to leave longer gaps over summer and winter festivities when people are less likely to be around, or as engaged. Trust your instincts around the organisation’s working culture.

Who to demo to

Invite everyone who may have interest in your project, however tangential. Prompt attendees to let other people know. In a big organisation, you won’t know everyone with a vested interest. Casting the net wide at the early stages gives you the best chance of winning hearts and minds, and can prevent friction later on.

If you can build a regular audience, you can build a positive culture around your demo series. That’s a good thing for visibility and trust.

Who should present

Try to never demo alone. Bring at least one pal. Wrap your demo inside a short presentation with a slide deck. This will help you figure out who does what and when. The wrap-around deck should tee up the demo, set context, and invite questions and feedback at the end. A non-demoing team member can do these bits.

Have a person who helped design or build the thing do the actual demo. They’re best placed to show the detail, explain the rationale of your approach, and field questions.

At any one time, the person speaking or presenting should focus only on that. The other person can assume a support role. They can note any questions dropped in chat, keep an eye on time, and deal with any issues that come up, technical or human.

It can be helpful to invite experts who aren’t part of your team. They can field broader questions about your project’s place in the organisation. You might invite engineers or brand people if your work has a bearing on their strategies.

Designing your deck

Your slide deck should introduce and set the context of your demo. It should explain:

What you’re demoing
Its purpose
Goals it contributes towards (this is persuasive and powerful)
Why it’s relevant to the audience

Our decks have slides that:

Name the thing we’re demoing, with the date
Show the agenda
Link to previous demo decks
Introduce the demo and change in speaker
Show a roadmap of what’s next
Prompt audience questions at the right time
Let people know where they can follow progress

Remember that you can’t control how your slides will be shared. Simple, concise slides are better, but each slide should have enough context to make sense to people who weren’t there.

Doing presentations has great advice for putting together slide decks. It’s optimised for "big" presentations, but there’s plenty of good stuff you can apply to demos, including how to make your deck a useful stand-alone resource.

How much to prepare

It’s hard to know how much to prepare. A demo isn’t a high-pressure presentation in the way that a sales pitch to a new client is. But it does need to be clear and concise, so take as much time as you need to do that.

New teams and projects will mean more prep time, but it does get easier and faster. In the past, we’ve taken a day or two to prepare to demo a new project. But we can get this down to a few hours as we find our groove.

Do a dry run

Do at least one practice run with everyone involved. If possible, invite a few people you trust to be the audience. Ask for frank feedback about what worked well and what didn’t. Then make any tweaks that are needed.

Get a feel for how long the demo will take and find ways to make it shorter. Cut flab. If you’re clocking in at over an hour, it’s too long. Make it as short as it can be but as long as it needs to be.

Have a contingency in case technology fails on the day. If you’re demoing live software, you’d ideally have backup screenshots or a pre-recorded screen capture if you have time.

The practical stuff

There are always practical considerations to think about. A tricky one is cameras on vs. cameras off. As presenters, you should have cameras on. If your work culture encourages it, you may like to suggest this to everyone attending. It’s easier to communicate, field question, get feedback and gauge the general vibe. But if the culture welcomes cameras off, do respect that.

You should also:

Present from a quiet location
Present from a well-lit location (but avoid having bright lights directly behind that make you hard to see)
Use the best camera and microphone you have
Avoid emphatically banging your desk (wobbles your camera)

We choose to avoid blurring our backgrounds on calls when possible. That’s an aesthetic choice, and we know there are very good reasons for people to mask their background. Do what’s best for you.

Doing the demo

Everyone presenting should join the call 10 minutes before start-time. If you’re demoing alone, ask a friend to join early. Test everything, including microphones, cameras and screen-sharing.

If you’re using Microsoft Teams, keep in mind that it will announce to everyone that the meeting has started. You might like to drop a “no need to join yet” message into a channel.

Unless policy prevents, record the demo so people can catch up. If you’re presenting to a new organisation, check that this is OK. You may prefer not to record if the topic is sensitive. If you are recording, let everyone on the call know before you push the button.

The rest comes down to how you present and communicate. There’s a world of considerations to developing these skills. A few things we’d highlight:

Pace is important—not too fast, not too slow
Doing presentations has great tips on the performance side of presenting
You’ll improve with practice (demos are a reasonably low-jeopardy way of developing presenting skills)

Fielding questions

Encourage questions, but on your terms. Decide in advance whether to allow them during the demo, or save them till the end. You may prefer to do them last if you’re presenting to:

A new, unknown group
A large group
People you know may derail the demo (in a charming, well-intended sort of way, of course)

Sticky wickets

It’s OK to pivot to questions at the end if things get tricky. A big risk is someone senior dominating with questions and feedback, or talking over your demo. If that person is an important stakeholder, you might decide to accept this. The important criterion is their role in your project, not their seniority.

If it’s not an important stakeholder, it’s best to politely but firmly insist on questions at the end. This will help your demo go smoothly, which is foremost a benefit to your audience.

An important skill to develop is being chill in the face of conflict. No one wants conflict, but it does happen. Being the unflappable person in the room will only build trust. That doesn’t mean having all the answers, but it does mean thinking then responding rather than reacting.

It helps to have your project spiel down pat. If questioned, be ready to articulate what you’re doing and why. These questions could come up when unfamiliar project teams and leads come along.

Duck into chat

You can prompt people to drop questions in chat. This can be distracting, but may be less distracting than letting chat go un-moderated. If you’re not presenting in that moment, reply to questions in the chat.

If someone voices a question when they shouldn’t, support the presenter by policing the situation. It will help them keep the thread.

At close of play

Leave at least 10 minutes for questions at the end. Less than that isn’t enough, and sends the message you’re not interested in feedback.

Let everyone know follow-up questions are welcome and where to put them. It’s good if this is in an open channel, so everyone can benefit.

Following up like a pro

Put your helpful hat on as soon as the demo’s over. Copy-paste the chat history somewhere safe so you can follow up on unanswered questions, or ones you can now answer more fully. It’s a nice touch to re-share contributions and links shared by attendees too.

Share the slide decks with everyone straight after the demo—and not only with people who attended. But check your speaker notes first. Some may not be useful. Some may cause embarrassment.

If you have time, review the recording to check that spoken questions were answered well. You might like to re-share the spoken questions and answers in text format. Share the recording too.

Track follow-up conversations in chat and field any new questions that come up.

If your demo was one in a series, ask attendees to let other people know about future demos.

Not following up properly can undo effort you’ve put into demoing well. It shows you value people’s time, and their right to be informed.

It gets easier

There’s a lot to think about, but demos don’t have to be scary. If we’ve given the impression that demos take a lot of time, it’s because they probably will for the first few goes.

But it gets easier. With practice, you’ll hone skills, processes and tools. When there’s a hitch, remember that people probably won’t notice, and almost certainly won’t care. People are kind, patient and understanding.

Try to have fun. You won’t get everything right in the early stages. But every hitch is a chance to do it better next time.

Accessible syntax highlighting colour schemes for developers

Paul Love — Fri, 19 Apr 2024 13:54:04 +0000

Why we designed and released two Base16 colour schemes for publishing code on the web.

When we started Measured, we knew we’d want to write things about technical aspects of our work. Inevitably, that means publishing code snippets.

We built our website to comply with WCAG AA accessibility, so we needed our code snippets to comply too. That meant applying a colour scheme to snippets to comply with the WCAG requirements for contrast.

More than that, we actually needed two schemes because our website adapts to visitor system preferences for day and night modes.

When we went looking at colour schemes already out there, we ran into one of two issues:

They weren’t AA-compliant
They were visually jarring (and in a way that wouldn’t work alongside our existing brand colours)

So Scott set about creating them instead. We collectively decided to release them as open source in case people shared our need for AA-compliant Base16 schemes that, not to put too fine a point on it, also look quite nice.

They’re available on GitHub for anyone to use. The obvious use cases are for either writing or publishing code, but the underlying schemes could be used for any lightweight web project.

Notes on development

A few more points for anyone interested in a bit more detail:

We didn’t start from scratch. We used Solarized as the basis of the project. It didn’t meet AA criteria, but it did give us a good platform to build from. From there, we essentially adapted our brand colours to meet Base16 needs.

Once we’d decided to share the schemes, we were keen to contribute to the Base16 ecosystem. To that end, we submitted pull requests to a couple of GitHub projects with mixed success. But the schemes are now included at Tinted Theming.

We’ve assumed this project will potentially interest developers, so we haven’t included much hand-holding in the README. That said, we did want to make this work immediately useful, so the repo includes files to get the schemes working with widely-used tools. Specifically:

We don’t plan to do more work on this project, but we welcome contributions. There is scope to support more tooling, for example.

You can start using the Base16 Measured Scheme via the GitHub repo.

Puck 0.13: Custom UIs, object fields & DropZone restrictions

Chris Villa — Wed, 20 Dec 2023 12:05:00 +0000

Puck is the open-source visual editor for React built by Measured - a self-hosted alternative to builder.io, WordPress and other WYSIWYG tools.

Puck v0.13.0 introduces some of our most powerful APIs yet, enabling completely custom interfaces, adding support for object fields and mechanisms to restrict DropZones.

TLDR

Custom interfaces: Take complete control of the Puck UI with the new custom interface APIs.
Object fields: Represent objects as fields with the new object field type.
DropZone restrictions: The new allow and disallow props allow you to restrict which components can be dropped into DropZones.
New plugin API (Breaking Change): The plugin API has been updated to align with the new custom interfaces API. This is a breaking change. The plugin API remains experimental.
New transformProps API: The new transformProps API makes it easier to rename props on your components without breaking your payload.
New ui prop: Set the initial UI state for the Puck editor on render.
Add search to external fields: Show a search input in the external field modal, enabling the user to query your external API.

Highlights

🎨 Custom interfaces

It's now possible to create completely custom Puck interfaces to integrate more deeply with your own UI and create a seamless experience for your users.

This can be achieved by passing children to the <Puck> component.

import { Puck } from "@measured/puck";

export function Editor() {
  return (
    <Puck>
      <div style={{ background: "hotpink" }}>
        <Puck.Preview />
      </div>
    </Puck>
  );
}

See this demo.

🪝 The `usePuck` hook

Access Puck's internals using the usePuck hook to extend Puck's functionality with powerful custom components.

import { Puck, usePuck } from "@measured/puck";

const JSONRenderer = () => {
  const { appState } = usePuck();

  return <div>{JSON.stringify(appState.data)}</div>;
};

export function Editor() {
  return (
    <Puck>
      <JSONRenderer />
    </Puck>
  );
}

🗃️ Object fields

Object fields enable you to represent your object types with the fields API. No more flattening your props!

const config = {
  components: {
    Example: {
      fields: {
        params: {
          type: "object",
          objectFields: {
            title: { type: "text" },
          },
        },
      },
      render: ({ params }) => {
        return <p>{params.title}</p>;
      },
    },
  },
};

🙅 DropZone restrictions

Restrict which components can be passed into a DropZone component with the allow and disallow props.

const MyComponent = () => (
  <DropZone zone="my-content" allow={["HeadingBlock"]} />
);

Deprecations

`renderHeader` deprecated

The renderHeader prop has been deprecated in favor of the overrides API.

// Before
export function Editor() {
  return (
    <Puck
      renderHeader={({ appState, dispatch }) => ()}
    />
  );
}

// After
export function Editor() {
  return (
    <Puck
      overrides={{
        header: ({ appState, dispatch }) => ()
      }}
    />
  );
}

`renderHeaderActions` deprecated

The renderHeaderActions prop has been deprecated in favor of the overrides API.

// Before
export function Editor() {
  return (
    <Puck
      renderHeaderActions={({ appState, dispatch }) => ()}
    />
  );
}

// After
export function Editor() {
  return (
    <Puck
      overrides={{
        headerActions: ({ appState, dispatch }) => ()
      }}
    />
  );
}

Breaking changes

`renderComponentList` removed

The renderComponentList prop has been removed in favor of the overrides API.

// Before
export function Editor() {
  return (
    <Puck
      renderComponentList={({ appState, dispatch }) => ()}
    />
  );
}

// After
export function Editor() {
  return (
    <Puck
      overrides={{
        componentList: ({ appState, dispatch }) => ()
      }}
    />
  );
}

Plugin API revamped

The plugin API has been significantly revamped to match the overrides API.

// Before
export function Editor() {
  return (
    <Puck
      plugins={[
        { renderFields: ({ appState, dispatch }) => () }
      ]}
    />
  );
}

// After
export function Editor() {
  return (
    <Puck
      plugins={[
        overrides: {
          form: ({ appState, dispatch }) => ()
        }
      ]}
    />
  );
}

Changelog

See the GitHub release for a full changelog.

Building a React Page Builder: An Introduction to Puck

Chris Villa — Thu, 28 Sep 2023 09:43:00 +0000

Page builders are great. They fill a gap once supported by the WYSIWYG CMS, enabling no/low-code creation of pages in a headless CMS world.

However, we’ve never found a page builder that works for our clients. They’re normally:

Proprietary, making them impossible to use for our larger clients, or
Difficult to integrate, often requiring us to interface with a Java-based CMS or introduce convoluted integration layers

After years of searching for a self-hosted, React-first solution for our clients, we eventually decided to build our own.

Introducing Puck

Puck is an open source page builder for React.

Puck enables you to create your own page builder and embed it directly inside your React application. Puck is:

Open-source under MIT
Self-hosted
Compatible with most existing headless CMS solutions
Extensible using plugins

Tell Puck what components you support, and Puck will provide a slick drag-and-drop interface for you or your content teams to create pages on-the-fly.

Puck also uses the permissive MIT license, so there’s nothing stopping you using it for commercial products.

Try the demo: http://puck-editor-demo.vercel.app

The launch

Since Puck’s launch less than a month ago, we’ve been overwhelmed with the response.

We hit the Hacker News front page, going from 8 to 1,800 stars on GitHub in 24 hours, continuing to grow to over 3,000 throughout September. Industry heavyweights like Simon Willison (co-creator of Django) and Guillermo Rauch (creator of Next.js and CEO of Vercel) both gave their praise.

// Detect dark theme var iframe = document.getElementById('tweet-1699106822698025103-488'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1699106822698025103&theme=dark" }

A quick look at the Puck API

Puck is React-first, and its core functionality is exposed via the <Puck> React component.

To render the Puck editor:

// Editor.jsx
import { Puck } from "@measured/puck";
import "@measured/puck/dist/index.css";

// Puck configuration, describing components to drag-and-drop
const config = {
  components: {
    HeadingBlock: {
      // Field types to render for each prop of your component
      fields: {
        children: {
          type: "text",
        },
      },
      // Your render function
      render: ({ children }) => {
        return <h1>{children}</h1>;
      },
    },
  },
};

// Describe the initial data
const initialData = {};

// Save the data to your database
const save = (data) => {};

// Render Puck editor
export function Editor() {
  return <Puck config={config} data={initialData} onPublish={save} />;
}

To render a page:

// Page.jsx
import { Render } from "@measured/puck";

export function Page() {
  return <Render config={config} data={data} />;
}

Setup

Installing Puck

If you have an existing application, you can install Puck via npm:

npm install @measured/puck

Or if you’re interested in spinning up a new application, you can run the generator

npm create puck-app

For this guide, we’re going to assume you’ve used the generator and chosen the next recipe, but most of it will apply to existing applications too.

Running the application

If you’re using the next recipe, navigate into your directory and run the application:

cd my-app
npm run dev

The server will start on port 3000. If you navigate to the homepage /, you’ll be prompted to redirect to the editor.

If you now navigate to edit you’ll see Puck rendering with a single component, HeadingBlock.

This is the Puck editor for our homepage, which contains a single HeadingBlock. If we click the component, we can update the text being rendered using the field on the right hand side.

If you hit Publish in the top-right corner, our homepage at / will be updated.

You can add /edit to any route in your application to spin up a Puck editor, whether or not the page already exists. This is thanks to the Next.js catch-all route under app/[…puckPath].

Understanding the Puck config

Let’s take a look at the puck.config.tsx file generated by the generator:

// puck.config.tsx
import type { Config } from "@measured/puck";

type Props = {
  HeadingBlock: { title: string };
};

export const config: Config<Props> = {
  components: {
    HeadingBlock: {
      fields: {
        title: { type: "text" },
      },
      defaultProps: {
        title: "Heading",
      },
      render: ({ title }) => (
        <div style={{ padding: 64 }}>
          <h1>{title}</h1>
        </div>
      ),
    },
  },
};

export default config;

This TypeScript file is pretty similar to the API example we shared above, with some type declarations. It exports a config object that matches Puck’s Config type.

Let’s break it down —

type Props = {
  HeadingBlock: { title: string };
};

This type definition allows us to tell Puck’s Config type what our underlying components are expecting. In this scenario, we’re defining one component, HeadingBlock, that accepts props title, which is a string.

We then pass this to our config, which tells Puck that we’re expecting to render a component called HeadingBlock that accepts the title: string prop.

export const config: Config<Props> = {
  components: {
    HeadingBlock: {
      fields: {
        title: { type: "text" },
      },
      defaultProps: {
        title: "Heading",
      },
      render: ({ title }) => (
        <div style={{ padding: 64 }}>
          <h1>{title}</h1>
        </div>
      ),
    },
  },
};

We use the extended Config type definition to create a config object. Our config object accepts the components key (see API reference), which must now define a HeadingBlock configuration.

Our HeadingBlock definition receives three keys: fields, defaultProps and render.

fields: {
  title: { type: "text" },
},

fields describes how to render the field for each prop passed to our component. In this case, we’re using a text field. See the field API reference for a full list of available field types.

defaultProps: {
  title: "Heading",
},

Because we’ve specified this as a required field, TypeScript will complain if we don’t configure default values for the props. Here, we’re setting the title to Heading.

We have to use the defaultProps key to set defaults so that Puck knows how to render the data in the fields.

render: ({ title }) => (
  <div style={{ padding: 64 }}>
    <h1>{title}</h1>
  </div>
),

Finally, we define a render function that tells Puck how to render the component.

Adding a Paragraph component

Let’s add a new component called Paragraph that accepts a text: string prop and renders a Paragraph element.

type Props = {
  HeadingBlock: { title: string };
  Paragraph: { text: string };
};

export const config: Config<Props> = {
  components: {
    //...existingComponents,

    Paragraph: {
      fields: {
        text: { type: "text" },
      },
      defaultProps: {
        text: "Paragraph",
      },
      render: ({ text }) => (
        <div style={{ padding: 64 }}>
          <p>{text}</p>
        </div>
      ),
    },
  },
};

We can now see this in the left hand side of the editor:

Let’s drag it onto our page and update it:

Great! Let’s add a text alignment property called textAlign, which accepts the values left, center or right.

type Props = {
  HeadingBlock: { title: string };
  Paragraph: {
    text: string;
    textAlign: "left" | "center" | "right";
  };
};

To render this, a radio field type would be better than a text input because it doesn’t allow for the input of arbitrary text:

export const config: Config<Props> = {
  components: {
    // ...existingComponents

    Paragraph: {
      fields: {
        text: { type: "text" },
        textAlign: {
          type: "radio",
          options: [
            { label: "Left", value: "left" },
            { label: "Center", value: "center" },
            { label: "Right", value: "right" },
          ],
        },
      },
      defaultProps: {
        text: "Paragraph",
        textAlign: "left",
      },
      render: ({ text, textAlign }) => (
        <div style={{ padding: 64 }}>
          <p style={{ textAlign }}>{text}</p>
        </div>
      ),
    },
  },
};

We’ve also set a default value of left, and mapped it straight to the textAlign CSS on our <p> element.

Deleting our existing Paragraph and drag a new one in shows us the new field on the right hand side. Toggling between the options works as expected!

Adding Tailwind

Let’s add Tailwind CSS to improve the styles:

npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

Add the Tailwind classes to app/styles.css:

@tailwind base;
@tailwind components;
@tailwind utilities;

Configure tailwind.config.js to process the Puck config:

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ["puck.config.tsx"],
  theme: {
    extend: {},
  },
  plugins: [],
};

Finally, let’s add some classes to our HeadingBlock and remove the padding on the wrapper:

    render: ({ title }) => (
      <div>
        <h1 className="text-4xl lg:text-5xl font-extrabold tracking-tight">
          {title}
        </h1>
      </div>
    ),

And our Paragraph:

    render: ({ text, textAlign }) => (
      <div>
        <p style={{ textAlign }} className="leading-7 mt-6">
          {text}
        </p>
      </div>
    ),

Let’s see how that looks:

Great! The styles are rendering, but things are looking a little cramped.

Rendering a custom root

To fix this, we’ll want to add a custom root. Puck allows us to change the default behaviour by overriding the root component of our page:

export const config: Config<Props> = {
  ... existingConfig

  root: {
    render: ({ children }) => {
      return <div className="p-16">{children}</div>;
    },
  },
}

This time we’re using Tailwind instead of inline styles.

Much better!

Taking it further

There are a bunch of Puck features that we won't cover in this tutorial that you could use to take your editor to the next level:

Adaptors - allow your users to select content from an existing headless CMS using adaptors
Plugins - the custom plugin API enables powerful new functionality. For example, the heading-analyzer plugin to analyse the document structure of your page and warn when you break WCAG2.1 guidelines
Custom fields - create your own input types for your users, like calendar widgets

You'll find documentation on all of these via our GitHub.

Closing words

We are committed to continuing the development of Puck, with features like multi-column layouts, more form inputs and new plugins in the works. After all, we need it for our clients too.

In the last month, our community has started building bespoke website builders, email builders and other innovative applications we never could have imagined.

If you like Puck, please throw us a star via our GitHub repository or come chat on our Discord server. For more information about our React services, please visit the Measured website.

Thank you for joining us on this journey. We're excited to see what you create with Puck!

DEV Community: Measured

Puck v0.16: Permissions

Permissions

Action bar override

iframe style injection

History injection

React to actions

Breaking changes

history.data is now history.state

history.id is now optional (TypeScript)

lastData is now returned as null instead of {} when empty in resolvers

Full changelog

Features

Bug Fixes

New Contributors

Don’t build a design system — build what you actually need

Where design systems come from

Siloed definitions

Build the right thing

1. Set goals

2. Define terms

3. Communicate openly

4. Expect change

The most important thing

Puck 0.15: Dynamic fields

Dynamic fields

AutoField component

Override the Publish button

Context-aware components

Breaking changes & deprecations

headerActions override must now render {children} (BREAKING CHANGE)

Undocumented editMode API deprecated

Full Changelog

Features

Bug Fixes

Community

Contributors

Scott’s Law of Rebrands

The imbalance of probabilities

Accept the cards you’re dealt

Get on the front foot

1. Figure out what can be systematised

2. Encode the brand

3. Plan for flux

Strength from flexibility

How to do great live demos—and why they’re important to get right

What we mean by live demo

What, when and who?

What to demo

When to demo

Who to demo to

Who should present

Designing your deck

How much to prepare

Do a dry run

The practical stuff

Doing the demo

Fielding questions

Sticky wickets

Duck into chat

At close of play

Following up like a pro

It gets easier

Accessible syntax highlighting colour schemes for developers

Notes on development

Puck 0.13: Custom UIs, object fields & DropZone restrictions

TLDR

Highlights

🎨 Custom interfaces

🪝 The usePuck hook

🗃️ Object fields

🙅 DropZone restrictions

Deprecations

renderHeader deprecated

renderHeaderActions deprecated

Breaking changes

renderComponentList removed

Plugin API revamped

Changelog

Building a React Page Builder: An Introduction to Puck

`history.data` is now `history.state`

`history.id` is now optional (TypeScript)

`lastData` is now returned as `null` instead of `{}` when empty in resolvers

`headerActions` override must now render `{children}` (BREAKING CHANGE)

Undocumented `editMode` API deprecated

🪝 The `usePuck` hook

`renderHeader` deprecated

`renderHeaderActions` deprecated

`renderComponentList` removed