Discuss the app settings layout pattern

[johanstromqvist]

Welcome to the app settings layout pattern discussion!

Here are some things you can do here:

💡 Share ideas on how to make this pattern, or its documentation, better.

❓ Ask a specific question about this pattern.

---

Tips before posting:

• Remember Polaris and our discussions are public. If you work for Shopify and have an externally sensitive topic, please reach out in #polaris in Slack
• Please report bugs here
• Contributions are always welcome
• Learn more about Polaris discussions

💜👩‍🚀✌️ the Polaris team

[javl]

The link underneath the code brings you to a broken sandbox.

[johanstromqvist]

Thanks @javl! On it.

[javl]

Also, am I correct in thinking some of these objects like AlphaCard don't work with @shopify/polaris currently because they are part of Polaris Alpha? If so, it might be worth mentioning this on the page.

The code does have a comment saying there are some 'caveats' when implementing the example in your own project but it doesn't say what or why. I have to say as a Polaris novice I'm having a very bad time getting the recommended layouts to work because documentation seems very sparse.

Maybe this is all a bit off topic but I do feel something like a settings page is the perfect beginners page (as most apps will need this) and as such could be a great entry point into using Polaris with Shopify.

[johanstromqvist]

Great feedback! We very much appreciate that.

These pattern pages are new and we're actively working on improving them. Our aspiration is to make it really easy for developers like yourself to find and build the patterns that merchants love. As a part of that, we want to provide code that is easy to install and use, but we're not there yet. I get that it's frustrating. Meanwhile, we could definitely make it clearer why the code examples are for guidance purposes only for now. Thanks!

[johanstromqvist]

The sandbox has been fixed. Thanks again for bringing it to our attention!

[javl]

@johanstromqvist What would be the best way to provide some feedback on all this? Separate issues, or one larger one explaining what I'm trying to achieve and the problems I'm facing along the way?

I've created an app using shopify-cli and polaris (10.49.1), and the default pages work, but as soon as I try to import elements from the settings page pattern, like import { AlphaCard } from "@shopify/polaris"; the page stops working because it can't seem to find those components. Related to that I'm having a very hard time debugging; the page basically works or it doesn't and I can't seem to find any usable info in either the terminal, browser console or Redux DevTools.

I really don't want to come across as a thankless, disgruntled user, but I am getting a bit frustrated by different 'how to' pages pointing to each other so if there is any way I can help fix that I'm all ears ;)

edit after creating a new app using the QR Code tutorial I'm able to import AlphaCard... No idea what happened that's different from the other app I had, made using the App-Bridge tutorial, but I still can't load useBreakpoints (which isn't mentioned anywhere in the docs), so yeah, still confused ;)

Also, the example pages generated by init @shopify/app@latest creates use a bunch of deprecated components, like Card, Stack, and TextStyle, but I guess that would be an issue for some other Shopify repo?

[johanstromqvist]

Yes, separate and purposeful issues enables us to triage and take action.

I'm sorry that the experience is frustrating right now. The pattern pages are new and there are a lot of kinks to iron out. I recommend checking out the Shopify dev discord for help building apps and troubleshoot. In the meantime we'll clarify that the example code on the pattern page is for guidance purposes only.

[javl]

There is a difference between the screenshot and the code in this example:

The example screenshot at the top seems to show two lists:

While the example code renders two textfields:

[johanstromqvist]

Thanks @javl! I agree that those examples ideally show the same elements. That's an oversight by us. However, the cards on the settings pages could contain a variety of different form fields and form layouts, but the choice of forms doesn't affect the page layout pattern itself.

[cherrychau]

Hey @johanstromqvist - curious about what the rationale is for using a 2-column layout for in-app settings rather than 1 column? I'm working on Marketplace Connect (1P app) and found that maintaining the recommended 2-column layout feels extra redundant since there's not a lot of context needed for each section. In this case, would the team be open to designers making their own judgement on whether or not to maintain the recommended 2-column layout or explore other options?

By no means is this final, but here's an example of what it might look like if I were to use the suggested polaris pattern.

[johanstromqvist]

Hi @cherrychau! Thanks for checking in, great question!

The rationale behind the two-column layout is scannability, helping merchants easily glance multiple topics and find their configurations quickly. Secondly, when providing section descriptions it separates the "understanding" from the "configuring". Granted, this is optimized for larger numbers of configurations that often require descriptions. Improvements can always be made, the Admin Settings is a good example of that.

The intent behind the pattern documentation is to raise the quality floor and make it easier for builders to align behind a single pattern so that merchants always know what to expect and how to use it. It's not always the best solution, but it being a shared solution has a lot of merchant value in itself.

In this case, would the team be open to designers making their own judgement on whether or not to maintain the recommended 2-column layout or explore other options?

Patterns are defaults and strong recommendations based on what's most effective for merchants most of the time. You and your team are always ultimately responsible for the experience you build and your perspective and knowledge about your specific users is the most important one. Think of patterns as an opinion about what merchants will expect, and deeply consider that when you're designing your experience. If the value of deviating outweighs the value of consistency, then it sounds like a good idea to deviate.

Perhaps more importantly, if you think a pattern is suboptimal in general, then the best thing to do is to document your observations and alternative designs. Then share that and get feedback from teams around you. If multiple teams tend to agree, then you can open an issue to contribute it back to Polaris. For merchants' sake, it's important that we don't branch off the product experience into multiple different directions based on local opinions.

[idokutela]

Hi there! I'm new to developing shopify apps, and I find the publication of these patterns a great help in understanding how the different components of Polaris fit together: thanks! I have a technical question: in the example code, you use a combination of BlockStack, InlineGrid and Box to achieve the desired layout. Why do you not just use Layout with Layout.AnnotatedSection children (as here )? In other words, why not have a hierarchy Page > Layout > ...Layout.AnnotatedSection? To a newcomer like me, this looks tailormade for a settings page. Are those components set to be deprecated? Do they have tradeoffs that make them unsuitable? Or is it just a matter of preference?