docs: apply custom theme from a Gist

[tomchentw]

📝 Description

I've extracted the key feature from #4292 :

Apply custom theme from a Gist

🚀 New behavior

It starts with the newly added icon on the header. It renders a <Popover /> with an <input /> asking for the Gist URL.

The user should provide a Gist URL. It should contain one CommonJS module defined the custom theme. For example,
https://gist.github.com/tomchentw/989ad340001061726bf2c0734d3739cf

🚀 New behavior

We could paste the Gist URL to the input and hit Apply. Since the custom theme above changes the xs size of the <Button />, It updates the icon size as expected:

A static image:

💣 Is this a breaking change (Yes/No):

No

📝 Additional Information

Let me know if this is easier to review, @with-heart . We could ship the localStorage feature or `live editing feature later on with more thorough thinking.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 9b53014

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[vercel]

This pull request is being automatically deployed with Vercel (learn more).
To see the status of your deployment, click below or on the icon next to each commit.

🔍 Inspect: https://vercel.com/chakra-ui/chakra-ui/5Y4tjHvFRA6bC82sjPSkMvw4MrYA
✅ Preview: https://chakra-ui-git-fork-tomchentw-docs-gist-theme-popover-chakra-ui.vercel.app

[lgtm-com]

This pull request introduces 1 alert when merging 9b53014 into 33b1919 - view on LGTM.com

new alerts:

• 1 for Unused variable, import, function or class

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit 9b53014:

Sandbox	Source
create-react-app-ts	Configuration

[with-heart]

Hi @tomchentw! You're really crushing it with your PRs related to this functionality and I really love the work you've been doing. After @segunadebayo and I discussed this yesterday on our Maintaining Chakra UI livestream, we feel like this functionality would make more sense as its own standalone app rather than being embedded in the docs.

In my view, this is for a few reasons:

1. This functionality feels awkward in the docs site. Since the user's theme isn't built for the purpose of styling the Chakra docs, the output would be inconsistent and potentially confusing for users.
2. We've always wanted to have a "theme explorer" app that provides users with a way to customize their theme and see immediate results, so they can explore their theme and experience changes in output as they happen.
3. The docs site isn't built to support this functionality. We use a lot of custom styling that isn't connected to the theme—and while we could fix this—I would hate for a user's custom theme to then break the docs site in subtle ways that they might not notice.

Would you be interested in working on a project to build a fully-fledged theme explorer type of app instead?

[segunadebayo]

Totally agree with @with-heart, this should be a standalone app, perhaps you can call it "Theme Explorer".

Kindly consider this and let us know what you think (here or via Discord).

In the meantime, we'll close this

[anubra266]

Hi @tomchentw I'm working on Chakra Play, though I've not done much on it recently, College troubles.🙂
But I'll love if we could work on it together, this being a part of it. The user can view his chakra code live, customize the theme with code(this two being what the chakra play does for now), and with this; also import his theme from a gist.
Let me know what you think.🙂

[tomchentw]

Intentions

@with-heart @segunadebayo I'd like to share my intentions of creating #4292 and #4345 :

Having a customized Chakra-UI docs site for YOUR COMPANY/ORGANIZATION

Imagine one organization who's leveraging Chakra-UI. They want to customize theme with a few values: sizes, spacings, colors. It does take efforts to host a custom Chakra-UI docs site, and not to mention they have to keep up with the upstream branch updates.

If the docs site allows to import theme from gist, they could simply setup something like:

1. https://chakra-ui.organization.com -> points to https://chakra-ui.com/apply-theme?fromGistId=989ad340001061726bf2c0734d3739cf
2. Whoever in the organization visit that page will automatically get the organization specific Chakra-UI docs site.

Want to use a different red color palette and wondering how it affects <Button /> or error toast? No problem. The UI change could be shown directly to non-engineering departments and get immediate feedbacks.

To prevent confusion, we could add a top-banner indicating that a custom theme is currently applied like I did in #4292 or GIF here:

Since the changes are all running locally, the user could always reset to the default theme.

Perhaps the real question here: how would you setup a customized Chakra-UI docs site for your organization?

Theme Explorer

A theme explorer is definitely useful for a playground situation. When I was reading the customize-theme page in the first place, I'm already imagine having a theme explorer right at that page so that I could try it out directly. Maybe this is one approach we could take from here?

On the other hand, I imagine a theme explorer would look similar to a CodeSandbox, leaving this playground more engineering-centered approach compared to the docs site. Plus, the best of the Chakra-UI docs site lies within its massive examples (with various variants and real-world usages). I would imaging it takes efforts to leverage (import) these examples as a separate theme explorer App.

Given these, I'm still convinced having a customized theme feature directly in the docs site adds value to it. :)

[tomchentw]

@anubra266 I'm impressed with the choc-autocomplete package. Haven't had a chance to try it but looking forward to! I also checked Chakra Play you mentioned here and yeah I'm open to see how it could play together!

[anubra266]

@tomchentw I definitely love this idea. It'll be awesome on Choc UI too.