raunofreiberg/ui-playbook

The documented collection of UI components 🤓

UI Playbook

WIP

UI Playbook is an effort to document common UI components, their functionality, best practices, accessibility requirements, and examples.

Motivation 🤔

While kick-starting my first design system, most of the time I would reference other design systems for inspiration and direction, only to find varying implementations of a single user interface pattern. There was no centralized specification as to how a certain component should be implemented or behave, which would have made my life a lot easier by being aware of various pitfalls and intricacies.

UI Playbook is an attempt to document common UI components based on learnings regarding the aforementioned things. This may or may not prove itself to be helpful to others, and I might be missing certain aspects — so I invite you to improve this and hopefully the next person tasked with building a component library will find this somewhat useful! ✌️

Plays 📖

• Tooltip
• Button
• Select
• Notification
• TextField
• Avatar
• Checkbox
• Motion
• Popover

Contributing

Wish to submit a new component for UI Playbook? Read our contributing guide for some ideas on how to do so.

Support

I work on this project in my spare time, so if you'd like to show support, you can do so by buying me a coffee 🖤 !

ui-playbook's Issues

Why not storybook.js ?

I see lot's of similarities with https://storybook.js.org/

Any thoughts on why it didn't work for you?

Thanks!

Stray console log of API key -nothing really compromising

ui-playbook/src/pages/api/subscribe.ts

Line 10 in a474e3a

console.log(process.env.MAILCHIMP_API_KEY);

Dark mode

Would be cool to add a dark mode for those night owls out there!

I've got something like this atm, but I'm open to ideas here! ✌️

Use MDX

I'd like to explore using MDX to write the plays!

Extend to general purpose plays

I started using the definition "play" instead of "component" with the intention of possibly not only covering UI components but primitives (techniques? I really can't think of a suitable noun here) such as animation, typography, colors, spacing.

I think there's a lot of valuable information to gather from various folks and sources and merge them into nicely organized plays as follows:

• Animation (distinguish separate tiers of animation: transitions, entry-exit animations, complex coordinated animations etc) live at https://uiplaybook.dev/play/motion!
• Typography (mention capsize?)
• Colors (provide guidelines on how to create a harmonic palette from a single primary color)
• Spacing (emphasize the usage of modular scales for spacing, instead of raw values)

Additional plays

In no particular order, here's a list of components that I think are worth covering:

• Breadcrumbs
• Modal
• Autocomplete (or Combobox)
• Menu (basically the menu button WAI-ARIA design pattern)
• Accordion
• Tabs

Primitives (I dunno how much content would these actually have, but worth exploring):

• Radio
• Checkbox
• Toggle

---

If you'd like to work on any of these, drop a comment below, and create an issue with the "New play" issue template.

Add a donation / support option

This is such a valuable project, I reference and share it quite often as a quick overview.

I'd love to buy you a coffee!

Outline key points for a play

There's probably room for improvement, but my current structure is something like this:

1. Component name, with visual, and concise description which could be reused throughout design systems, so it should be on point!
2. Functionality (describe how the component should behave)
3. Best practices (cover pitfalls, intricacies or any other non-obvious things to keep in mind)
4. Implementation (a bit more technical than the previous chapters, possibly get into framework-specific nuances, etc)
5. Examples (render a few well-implemented examples of the component from various frameworks)
6. Accessibility (basically links to WAI-ARIA docs for the component; it's probably redundant to duplicate the same info here)
7. Resources (any resources used to put the play together)

I'm very open to suggestions and feedback on this!

Button

Some rough notes:

• Cover different states (active, loading, disabled)
• Cover usage and implementation of "link buttons"
• Cover "fake div buttons" and how to make them accessible

TextField

TextField

TextField is an input field that users can type into.

Functionality

Rough notes:

• Emphasize using the native <input> element.
• Cover different states (hover, active, focus, disabled, read-only)
• Field label, caption, error

Best practices

Rough notes:

• Using <label> along with <input>
• Using icons with TextField
• Marking a field as optional or required
• Field validation feedback
• How to use field label or placeholder (maybe some copywriting tips)
• Cover naming (a la. Input vs TextField)

Implementation

• Cover using <input type="text" /> for numeric inputs

Examples

If possible, provide links to a few implementations of this component.

Accessibility

• Mention relevant accessibility attributes when used with an Autocomplete component.

Resources

• Why the GOV.UK Design System team changed the input type for numbers
• W3 - Labeling Controls

Visuals

Any relevant visuals that help describe the component.

Additional context

Anything that does not fit into the other categories.

Popover

Popover

Popover is an overlay that appears on top of the page.

Functionality

TODO

Best practices

TODO

Implementation

TODO

Examples

TODO

Accessibility

TODO

Resources

TODO

Visuals

TODO

Additional context

TODO

Radio Button

Radio Button

A radio button or option button is a graphical control element that allows the user to choose only one of a predefined set of mutually exclusive options.

Functionality

This component should use the HTML <input type="radio" /> element under the hood.

Best practices

TODO

Cover best practices, pitfalls, intricacies or any other non-obvious things to keep in mind.

Implementation

TODO

Cover implementation details, possibly get into framework specific nuances.

Examples

TODO

If possible, provide links to a few implementations of this component.

Accessibility

TODO

Cover relevant accessibility requirements. If a WAI-ARIA design pattern exists for this component, provide links to the relevant sections.

Resources

TODO

List the resources used to put the play together.

Visuals

TODO

Any relevant visuals that help describe the component.

Additional context

TODO

Anything that does not fit into the other categories.

Modal

Modal

A modal is a dialog box that is displayed on top of the current page or another dialog box.

Functionality

→ Appear as a result of user interaction.

→ Used to provide additional information in context.

→ Used when you want to interrupt the user flow to something more important (e.g alertdialog)

→ Used for requesting input from the user.

Best practices

1. always give clear exit routes to the user.
2. give a descriptive title
3. give the action buttons inside the modal clear names
4. give context to the modal (it should never occupy the whole screen)
5. add a darkened/dimmed layer underneath the modal
6. never disrupt the user journey, the modal should be triggered as a result of user interaction with the page, such as a button click.

Implementation

TODO

Examples

https://react-bootstrap.github.io/components/modal/
https://reach.tech/dialog/
https://www.w3.org/TR/wai-aria-practices/examples/dialog-modal/dialog.html

https://design.nib.com.au/language/master/#/organism/modal?_k=bezgi3

Accessibility

https://www.w3.org/TR/wai-aria-practices-1.1/#dialog_modal
https://www.w3.org/TR/wai-aria-1.1/#dialog

Resources

https://uxplanet.org/best-practices-for-modals-overlays-dialog-windows-c00c66cddd8c
https://xd.adobe.com/ideas/process/ui-design/best-practices-for-designing-overlays/
https://www.w3.org/TR/wai-aria-practices-1.1/#dialog_modal
https://www.w3.org/TR/wai-aria-1.1/#dialog

Visuals

Any relevant visuals that help describe the component.

Additional context

Anything that does not fit into the other categories.

Notification

Some rough notes:

• The optimal duration for the automatic dismissal
• Pausing the timer via mouseover
• API design - to expose a component or imperative API to dispatch notifications?
• Stacking notifications (a la. should they appear on top of each other, or alongside?)
• Copywriting
• Positioning

This is great work!

I really appreciate the thought and detail you're putting into the explanation of each component.

Motion

Motion

WIP

Linked to #20

Principles

Motion should:

1. Be educative
2. Be informative and provide feedback
3. Draw attention and provide focus
4. Be playful, have character
5. Not be overwhelming or distracting

Types of motion

Tier A

Basic CSS animations & transitions

1. Component hovers
2. Checkbox check
3. Spinner
4. Toggle

Tier B

1. Entry/exit animations such as Modal, Notification

• CSS animations for mount animations
• Mention techniques to animate already unmounted components

Tier C

Interactive animations

1. Stacked notifications
2. Dynamic height opening

Tier D

SVG animations

1. Stroke/fill with CSS

Contributors guide?

Are you looking for help? You might want to make a guide about what you're looking for help with.