Skip to content

UI Styleguide ​

Every workspace with a ui layer carries a styleguide: one place to check all the ui components quickly, the way a component library's site does (Vuetify, Bootstrap).

Why ​

Every component is judged on its own, edges included.

How To Apply ​

  • Every ui component gets its page as it is built. A new variant lands with its entry.
  • A component's page shows at least:
    • The name
    • A description of what it is: a pure component, agnostic of the feature it serves, with no business logic
    • The main variants at a glance
    • A testbox, a playground to set each variant and try odd combinations, to spot complexities and edge cases
  • Pick the tooling per workspace: Storybook, a gallery route in the app, a sandbox widget in the wiki.
  • A complex dynamic piece, such as a canvas scene or an animated avatar, gets a page too, so it is judged and played with apart from its context first.
  • The description stays feature-agnostic. One that needs the feature to make sense means the component is not pure enough.
  • The canvas is the app: load the app's global styles, palette, theme defaults and root rem into the preview, and give it the app's own background. A story on a bare canvas looks broken even when the component is fine.
  • Verify a styleguide by a sweep, never by clicking around: a Playwright probe lists every entry of the styleguide, from the story index where it is Storybook, screenshots each and tiles the shots into contact sheets to review.
  • A story that shows nothing on its own, such as a one-shot animation or a closed pop-up, gets a version that shows its thing, with a play function or a repeating render.
  • A component judged through its feature hides its edges, since the feature only ever reaches a few combinations.