Refactor playground to be more useful

[amannn]

Currently, https://github.com/amannn/next-intl/tree/main/examples/example-app-router-playground is used for e2e testing.

That's absolutely fine, but I think if we'd refactor it to something like https://app-router.vercel.app it could also be helpful to document more advanced use cases.

Therefore, I'd propose to refactor the playground example to:

1. Look nicer and be approachable to users
2. Keep all existing tests
3. Group tests logically into different sections of the app (i.e. no home page that demonstrates all kinds of wild patterns)

---

Related to this, https://next-intl-example-app-router.vercel.app is also a bit random in what it demonstrates. It's a basic test for i18n routing, it might make sense to clarify which patterns to demonstrate on this example and potentially include a few more features like date formatting. This is TBD.

[Adebesin-Cell]

Hi @amannn, this sounds like a great improvement! I’d like to take this on. Could you please assign me to the issue?

Thanks!

[amannn]

Hey @Adebesin-Cell, thanks for proposing to help here! If you're interested in refactoring the playground, that would be awesome!

It will definitely be a somewhat involved task, if you'd like to discuss some ideas or get feedback on an early draft, please just get in touch!

I'm not sure yet how designed this needs needs to be, it's absolutely fine for me if it looks a bit bare bones, but clean.

Alternatively, in preparation for learn.next-intl.dev I've started setting up a design system for next-intl:

If you'd like to use the colors and typography from that for the playground, I can share the specs or a Tailwind config.

[Adebesin-Cell]

Hey @amannn, thanks for assigning this to me! I’d love to review the design system you’re developing, which’ll help me keep things aligned. I’ll start digging into the current playground and then kick off the refactor with the new structure in mind.
I’ll share early drafts along the way to get your thoughts. 🚀

[amannn]

Awesome! 🙌

I've just set up the docs/refactor-playground with two commits:

1. Set up a new example example-app-router-patterns in 59842d7
2. Add spec and draft for the design system in 5b23c25

You can branch away from there or just continue working on the branch in a fork.

I think having a separate example to begin with could be handy, so that patterns from the playground can be moved there step by step, and we're not forced to replace the whole thing at once. If it eventually replaces the playground, I'm more than happy with that, but this might give us some flexibility. We can also do this in multiple steps and merge something useful to main once it's ready.

As mentioned further above, I'm also not too happy with https://next-intl-example-app-router.vercel.app/ currently, as it's a bit random in what it showcases. I think having some kind of hello-world-y example is helpful, as it can be useful for people to compare their setups with in case they run into an error. But if the new patterns example turns out good, I think maybe we could consider linking to that instead from the home page. But let's take this one step at a time.

Regarding the design system: It's not set in stone. I think it's good to push for a shared direction here, so that various examples, docs etc. from next-intl will have a look & feel that feels consistent. But I'm e.g. not sure yet if surfaces really need a border. For learn.next-intl.dev I definitely took some liberty in a few places, so use as much as it helps, but if something really asks to make an exception, then surely go for it. I'd also not over-abstract the code too much currently, e.g. a set of typography class names that produce a good result for a particular use case might be more helpful than a heavy "text-title-large" abstraction that might be hard to tweak for certain cases.

That's at least my thoughts on this so far, let me know what you think and in case you have any questions I'll make sure to be quick to respond!

Oh, one minor note: In case you need icons, I tried Heroicons before, but wasn't entirely happy due to it being somewhat limited. I had better experiences with Lucide, so I'd probably vote for that.

[Adebesin-Cell]

Hey @amannn, how’s it going? I put together this layout, which is quite similar to https://app-router.vercel.app/, but styled with the design system you provided. What do you think, should we go with a fresher design direction, or continue with this approach?

[amannn]

Hey @Adebesin-Cell, that looks really, really cool! 💯 For me the direction looks solid.

I'm just curious, did have something entirely different in mind about a "fresher design direction"? Certainly open to discuss!

Looking the current state, here are a few ideas that come to my mind:

Information hierarchy

Currently, the playground is structured into "getting started", "formatting" and "advanced". I wonder if this structure might help to align with the docs:

1. Translations: How to use basic translations, how to use them in (async) server components (users typically need this quite early, I wouldn't consider it "advanced"), ICU features like plurals & more
2. Formatting: Basically what you have right now, but plurals are covered in "translations", but instead also list formatting is included here
3. Routing: Maybe we could set up this example similar to the mixed routing example, in that there's a section that doesn't use locale-based routing, but this section could use it
4. Patterns (or maybe "use cases", or something like that?): Locale switcher, Server Actions, Metadata, error files etc.

But again, we don't have to do all at once, I think a first iteration that e.g. covers the first two would be a great starting point to validate the direction of this example. Open to your thoughts though!

A side note: Regarding number/date formatting, I've been wondering for a longer time if next-intl could provide a playground similar to https://intl-explorer.com/Playground that allows users to tweak config easily to find a desired format. It's just a very rough idea at this point and I'm not sure if it needs to be as comprehensive as the one I've linked to. But this might be something for another iteration, showcasing a typical use case is totally fine for a first step.

Design

Nice, first impression is really cool from my perspective! Also I see a toggle for dark mode, so nice! 👀

A few nits:

1. If blue is used on a dark background, it should use the lighter shade 300—see the design system examples (in your case for the logo)
2. You could try using the blue color for captions. An idea: we could use blue captions if they're used in the main content, but use a darker shade of gray in the sidebar to provide more visual hierarchy and draw focus to concrete pages while deemphasizing the headline (like the Next.js playground does it)
3. "Playground" could be left-aligned with "next-intl", while decreasing vertical spacing, making the two form a unit. Or: like the Next.js playground does it, just use the logo and the wording "playground". Might needs to be tried out to see what works better.
4. On a first look, it seems like there are a couple of shades of grey floating around that don't match the design system (see e.g. the background colors of the panel)
5. Might be personal taste, but potentially all of the side navigation items could be left-aligned

---

Those are my first few thoughts, let me know what you think!

[Adebesin-Cell]

Hey @Adebesin-Cell, that looks really, really cool! 💯 For me the direction looks solid.

I'm just curious, did have something entirely different in mind about a "fresher design direction"? Certainly open to discuss!

Looking the current state, here are a few ideas that come to my mind:

Information hierarchy

Currently, the playground is structured into "getting started", "formatting" and "advanced". I wonder if this structure might help to align with the docs:

1. Translations: How to use basic translations, how to use them in (async) server components (users typically need this quite early, I wouldn't consider it "advanced"), ICU features like plurals & more
2. Formatting: Basically what you have right now, but plurals are covered in "translations", but instead also list formatting is included here
3. Routing: Maybe we could set up this example similar to the mixed routing example, in that there's a section that doesn't use locale-based routing, but this section could use it
4. Patterns (or maybe "use cases", or something like that?): Locale switcher, Server Actions, Metadata, error files etc.

But again, we don't have to do all at once, I think a first iteration that e.g. covers the first two would be a great starting point to validate the direction of this example. Open to your thoughts though!

A side note: Regarding number/date formatting, I've been wondering for a longer time if next-intl could provide a playground similar to intl-explorer.com/Playground that allows users to tweak config easily to find a desired format. It's just a very rough idea at this point and I'm not sure if it needs to be as comprehensive as the one I've linked to. But this might be something for another iteration, showcasing a typical use case is totally fine for a first step.

Design

Nice, first impression is really cool from my perspective! Also I see a toggle for dark mode, so nice! 👀

A few nits:

1. If blue is used on a dark background, it should use the lighter shade 300—see the design system examples (in your case for the logo)
2. You could try using the blue color for captions. An idea: we could use blue captions if they're used in the main content, but use a darker shade of gray in the sidebar to provide more visual hierarchy and draw focus to concrete pages while deemphasizing the headline (like the Next.js playground does it)
3. "Playground" could be left-aligned with "next-intl", while decreasing vertical spacing, making the two form a unit. Or: like the Next.js playground does it, just use the logo and the wording "playground". Might needs to be tried out to see what works better.
4. On a first look, it seems like there are a couple of shades of grey floating around that don't match the design system (see e.g. the background colors of the panel)
5. Might be personal taste, but potentially all of the side navigation items could be left-aligned

Those are my first few thoughts, let me know what you think!

Thanks a lot for the thoughtful feedback! 🙌 Really appreciate how detailed your notes are.

Most of the texts on the UI right now are just placeholders—I mainly wanted to share the layout and get a first impression, so this is super helpful. I’ll work on refining the copy to better align with the docs and the hierarchy you suggested. I think starting with translations + formatting as the first iteration makes a lot of sense.

On the design side, your points are spot on. I’ll adjust the colors to follow the system more closely and try out the alignment/caption ideas you mentioned. That should help give it a cleaner hierarchy and flow.

Excited to push the next iteration with these improvements! 🚀

[amannn]

Awesome, sounds great! 🙌

[Adebesin-Cell]

Awesome, sounds great! 🙌

Hey @amannn, how’s it going?

Just wanted to reach out here about the next-intl playground. I had made some solid progress on the codebase, but my MacBook broke down before I could commit anything (I was holding off since it wasn’t quite ready to push). Ended up losing everything, which is super painful 😅.

Looks like I’ll have to restart from scratch, but I’m still on it and determined to rebuild. Just wanted to give you a heads-up on why there’ll be a bit of a reset on my end.

[amannn]

Oh no, sorry to hear! Hope you didn't lose other work as well. Generally, don't worry about pushing something half-finished, we can leave it in a WIP state until it's ready.

But glad to hear you're still on it! There's no pressure for this task, so take your time. I think it will be really helpful for people though once it's ready 😊

[Adebesin-Cell]

Oh no, sorry to hear! Hope you didn't lose other work as well. Generally, don't worry about pushing something half-finished, we can leave it in a WIP state until it's ready.

But glad to hear you're still on it! There's no pressure for this task, so take your time. I think it will be really helpful for people though once it's ready 😊

Yeah, I did lose some files, not going to be easy to recover them, but I’m hoping I can get at least some of it back. Really appreciate the reassurance 🙏. Thanks a lot, I’ll take my time and get back into it.

No worries, I’ll be back with even better inspiration 😛

[Adebesin-Cell]

Hey @amannn,

It’s been a while! I was able to recover a few of my files, so I’ll continue working with what I have for now.

I’ve updated the look of the homepage, and I’m planning to start on the basic playground next.
I was wondering, should we move the playground chat to a discussion?

Screenshots

💻 Desktop

📱 iPad

Do you have an idea of how you’d like the basic page to look?