seek-oss/playroom

Simultaneously design across a variety of themes and screen sizes, powered by JSX and your own component library.

Playroom allows you to create a zero-install code-oriented design environment, built into a standalone bundle that can be deployed alongside your existing design system documentation.

• Iterate on your designs in the final medium.
• Create quick mock-ups and interactive prototypes with real code.
• Exercise and evaluate the flexibility of your design system.
• Share your work with others by simply copying the URL.

Demos

Braid Design System (Themed)

Cubes (Themed)

Mesh Design System (Themed)

Mística Design System (Themed)

Shopify Polaris

Agriculture Design System

Send us a PR if you'd like to be in this list!

Getting Started

$ npm install --save-dev playroom

Add the following scripts to your package.json:

{
  "scripts": {
    "playroom:start": "playroom start",
    "playroom:build": "playroom build"
  }
}

Add a playroom.config.js file to the root of your project:

module.exports = {
  components: './src/components',
  outputPath: './dist/playroom',

  // Optional:
  title: 'My Awesome Library',
  themes: './src/themes',
  widths: [320, 768, 1024],
  snippets: './playroom/snippets.js',
  frameComponent: './playroom/FrameComponent.js',
  frameSettings: [{ id: 'rtl', label: 'RTL Layout', defaultValue: false }],
  exampleCode: `
    <Button>
      Hello World!
    </Button>
  `,
  cwd: './playroom',
  scope: './playroom/useScope.js',
  port: 9000,
  openBrowser: true,
  paramType: 'search', // default is 'hash'
  baseUrl: '/playroom/',
  webpackConfig: () => ({
    // Custom webpack config goes here...
  }),
  iframeSandbox: 'allow-scripts',
  defaultVisibleWidths: [
    // subset of widths to display on first load
  ],
  defaultVisibleThemes: [
    // subset of themes to display on first load
  ],
};

Note: port and openBrowser options will be set to 9000 and true (respectively) by default whenever they are omitted from the config above.

Your components file is expected to export a single object or a series of named exports. For example:

export { default as Text } from '../Text'; // Re-exporting a default export
export { Button } from '../Button'; // Re-exporting a named export
// etc...

The iframeSandbox option can be used to set the sandbox attribute on Playroom's iframe. A minimum of allow-scripts is required for Playroom to work.

Now that your project is configured, you can start a local development server:

$ npm run playroom:start

To build your assets for production:

$ npm run playroom:build

Snippets

Playroom allows you to quickly insert predefined snippets of code, providing live previews across themes and viewports as you navigate the list. These snippets can be configured via a snippets file that looks like this:

export default [
  {
    group: 'Components',
    name: 'Button',
    description: 'Strong weight',
    code: `
      <Button weight="strong">
        Button
      </Button>
    `,
  },
  // etc...
];

The group property is optional, but if provided, snippets will be grouped together in the UI under the specified group name. The description property is also optional and can be used to help differentiate similar snippets.

Custom Frame Component

If your components need to be nested within custom provider components, you can provide a custom React component file via the frameComponent option, which is a path to a file that exports a component. For example, if your component library has multiple themes:

import React from 'react';
import { ThemeProvider } from '../path/to/your/theming-system';

export default function FrameComponent({ theme, children }) {
  return <ThemeProvider theme={theme}>{children}</ThemeProvider>;
}

The FrameComponent receives the following props:

• theme - The currently selected theme (if themes are configured)
• themeName - The name of the currently selected theme
• frameSettings - An object containing the current values of frame settings (if configured)
• children - The rendered playroom code

Custom Scope

You can provide extra variables within the scope of your JSX via the scope option, which is a path to a file that exports a useScope Hook that returns a scope object. For example, if you wanted to expose a context-based theme variable to consumers of your Playroom:

// scope.js

import { useTheme } from '../path/to/your/theming-system';

export default function useScope() {
  return {
    theme: useTheme(),
  };
}

Embedded CSS Formatting

CSS authored inside style tags with a jsx attribute will be formatted as CSS. This takes advantage of prettier's embedded language formatting capabilities.

For example:

<style jsx>
  {`
    .foo {
      color: red;
    }
  `}
</style>

Theme Support

If your component library has multiple themes, you can customise Playroom to render every theme simultaneously via the themes configuration option.

Similar to your components file, your themes file is expected to export a single object or a series of named exports. For example:

export { themeA } from './themeA';
export { themeB } from './themeB';
// etc...

Frame Settings

Playroom allows you to define configurable boolean toggles that users can control for each frame independently. This is useful for testing components under different conditions (e.g., RTL layout, debugging touch targets, etc).

You can configure frame settings via the frameSettings option in your config:

module.exports = {
  // ...
  frameSettings: [
    {
      id: 'rtl',
      label: 'RTL Layout',
      defaultValue: false,
    },
    {
      id: 'showTouchTargets',
      label: 'Show Touch Targets',
      defaultValue: false,
    },
  ],
};

When frame settings are configured, a settings icon will appear in each frame's action bar enabling users to toggle individual settings.

Using Frame Settings in Your Frame Component

Frame settings are passed to your custom FrameComponent as the frameSettings prop, which is an object mapping setting IDs to their boolean values:

import React from 'react';
import { ThemeProvider } from '../path/to/your/theming-system';

export default function FrameComponent({ theme, frameSettings, children }) {
  return (
    <ThemeProvider theme={theme} rtl={frameSettings?.rtl}>
      <div
        className={
          frameSettings?.showTouchTargets ? 'showTouchTargets' : undefined
        }
      >
        {children}
      </div>
    </ThemeProvider>
  );
}

Frame Settings Behavior

• Per-frame state: Each frame (theme/width combination) maintains independent settings
• Session-only: Settings are stored in memory and reset on page refresh
• Not persisted: Settings are not included in shared URLs or local storage

This allows users to quickly compare how components behave under different configurations across multiple frames simultaneously.

TypeScript Support

If a tsconfig.json file is present in your project, static prop types are parsed using react-docgen-typescript to provide better autocompletion in the Playroom editor.

[!NOTE] By default, all .ts and .tsx files in the current working directory are included, excluding node_modules.

If you need to customise this behaviour, you set the typeScriptFiles property in your playroom.config.js. This property accepts an array of tinyglobby-compatible globs.

module.exports = {
  // ...
  typeScriptFiles: ['src/components/**/*.{ts,tsx}', '!**/node_modules'],
};

If you need to customise the parser options, you can set the reactDocgenTypescriptConfig property in your playroom.config.js.

For example:

module.exports = {
  // ...
  reactDocgenTypescriptConfig: {
    propFilter: (prop, component) => {
      // ...
    },
  },
};

ESM Support

Playroom supports loading ESM configuration files. By default, Playroom will look for a playroom config file with either a .js, .mjs or .cjs file extension.

Storybook Integration

If you are interested in integrating Playroom into Storybook, check out storybook-addon-playroom.

Browser Support

Playroom is built to work on the latest stable versions of all major browsers. Some features may not work as expected in older browsers.

License

MIT.