Match Lexicon site menu

[victorvalle]

I've received this feedback today

What is your proposal?

Matching Lexicon and Clay IA

Why would adopting this proposal be beneficial?

It looks like Clay has flattened their IA (i.e. there aren't any groupings inside ‘’Components’) and I’m wondering if someone could link me to discussions/rationale behind the decision to diverge. It’s creating some issues (from fairly simple, like broken links) to more complex (creating and maintaining two different mental models leads to higher costs)

Example:
In Lexicon there are Selectors, but in Clay there is Select and Multi Select.

[matuzalemsteles]

Hey @victorvalle this has been changed recently, you can find all the discussions we had about this change here #3117

[bryceosterhaus]

creating and maintaining two different mental models leads to higher costs

This thought intrigues me, should we expect that both Clay and Lexicon have the same mental models? I would expect that they would be slightly different since Clay and Lexicon are similar, but catered to different audiences, devs vs designers.

[victorvalle]

The intention was to always have at least the components section the most similar possible. They are different audiences and therefore the content on each page is different. But I don't know if just different audiences justify a change in our previous IA agreement. Anyway, @drakonux said is ok, so it is ok for me too.

Consumers of both sites will provide more insights I guess.

[plhnk]

@bryceosterhaus echoing @victorvalle — the audiences are different in some respects, but IMHO that's more relevant on a micro level (specific content on the page), rather than the macro.

TL;DR — these small problems seem to be symptoms of a bigger issue, how might we take steps to fix it?

Also — I'm not saying "Lexicon is doing it best, Clay should follow it" or vice-versa. My questions/points are more to highlight current issues. I'm also not pointing fingers, I know on my side there are plenty of broken links on the design site that I don't always catch or fix in a timely manner — we're all busy and often the websites are first to lose the attention (speaking for myself 😅).

Designers and developers use both — in different ways — but having them organized separately creates a barrier that designers have to overcome when communicating with developers.

You've probably seen some or all of these before — IMHO these are four of the best:

• Atlassian
• Ant
• IBM
• Elastic

Lightning Design is probably the closest mental model to where we are currently (although they are in the same site) — and I found it confusing to use when I was recently doing some updates for Sales Ops.

I'm not sure this is the best place to start the discussion, but it may be worth considering how we can evolve Clay and Lexicon together in the future...at the very least we should have some alignment or fail-safes in place to prevent small (but frustrating) errors like broken links.

[pat270]

@plhnk 🤔 It seems like what you're suggesting is combining https://liferay.design/lexicon/ with https://clayui.com/.

[plhnk]

@pat270 that's a great idea! 😬 ...I'm not sure that's really feasible right now, I think that would involve more than just the websites 😄 .

I didn't really have a concrete suggestion — just providing more input/perspective.

[jonmwood]

As a designer for DXP, I often have both the lexicon and clay sites open and toggling back and forth between the two when evaluating components on what the ux/interaction should be for a feature I'm building. There's often gaps in terms of what is displayed between the sites and so I will bring it up in the lexicon slack channel and sometimes the frontend channel if need be to get clarification.

Ideally, it'd be great if they were consolidated into one place, but yeah that's definitely an undertaking. I don't know how many devs look at lexicon, although they are very welcome to. 😄

That being said, as @plhnk mentioned the core issue is about alignment so this ticket about matching IA is good idea to address consistency for those that need to use both. 'Evolving together' as @plhnk put it is really key because of there's a co-dependency of designers relying on implemented components in Clay as well providing requests to the lexicon & clay teams to implement from their product design process. I hope my perspective was helpful. 😬

[matuzalemsteles]

I agree that this can be a problem for people who consume both sites, and I see more Designers doing this than developers but we should try to make it easier for both, especially from the perspective of when the design finds a gap between the implementations and can request changes in advance before arriving in development.

But really I think that joining the two sites is a big job and would also require a lot of other changes, as I remember the idea of ​​the two being separate was because it caused a lot of confusion, maybe the information didn't help to separate things... but @jbalsas can have more context about that.

On Clay's side, I think we can commit to helping the Lexicon website with the links, whenever we change or add new components and also create the redirect links when they change, I think that can reduce frustration.

[jbalsas]

Lightning Design is probably the closest mental model to where we are currently (although they are in the same site) — and I found it confusing to use when I was recently doing some updates for Sales Ops.

I think this is a bit misleading, since Lightning Design System and Lightning Component Library are also different sites.

The one thing that I see in the Design System are the Component Blueprints, which in our case are akin to the HTML/CSS tabs we have in Clay. This is actually something we've been struggling with for a while so that could address some of the issues but also bring others as you I explain below.

We decided to split the sites (and names) back then because:

• Lexicon was being conflated to mean both design system and implementation. Bugs would be reported against design when they were caused by a specific implementation and vice-versa making issues very hard to track and address.
• Each project evolves at a different pace. Decoupling gave Lexicon freedom to evolve at its own speed.
• Each team has different priorities and skillsets. Decoupling the sites allows each team to make their own decisions based on their strengths.

In the initial versions, we closely matched the outlines to simplify navigating back and forth on the assumption that that was what was needed. As pointed out, this assumption was challenged while working on Move component docs from clayui.com to their respective packages. Flattening the component hierarchy was validated by Lexicon at the time, so we went ahead with it.

As you can see there, my comment at the time was:

Just a consideration... we need to make it easier to navigate back and forth from Lexicon, so people know how to match patterns and components and get their job done. That's my opinion. How we make that happen is up to you. There's definitely more than one way to achieve it (better search, cheatsheet, cross-links...)

I stand by this. Maybe there's more ways in which we can achieve a better correlation between Lexicon and Clay.

I'm not sure this is the best place to start the discussion, but it may be worth considering how we can evolve Clay and Lexicon together in the future...

This sounds like a perfect place to start to me! Feel free to open a different channel to go over ideas if you think there's a better way to approach this. We probably want to also involve developers in the conversation to understand how their workflow (if any) is different than that of designers so we don't target just a subset of our potential audience.

[bryceosterhaus]

I remember this being brought up before, the idea of lexicon, clay-css, and the react components all living together and being sync'd in terms of docs and features, and I think one of the big hurdles was versioning. I think clay tends to be more locked into a certain design since we can't really making breaking changes to the UI often, whereas the lexicon design system was more fluid from case to case. There was also difficulty of delay. The react components depend on clay-css and clay-css depends on lexicon. It's really difficult to keep those all consistent and sync'd when they are dependent on one another.

As a designer for DXP, I often have both the lexicon and clay sites open and toggling back and forth between the two when evaluating components on what the ux/interaction should be for a feature I'm building.

I wasn't aware that designers would often frequent the Clay site. I'm really curious how you use it within your workflow, @jonmwood could you elaborate a bit on how you are using it from a designers perspective?

IMO, I think it'd be really cool to have it all unified in a single site, but I'm just not sure how feasible it is. I think on the Clay side, we can commit to keeping our links up to date and add a redirect when we change a url. I think we can also commit to improving the experience for designers who use our site, currently I think our main focus has been solely on the liferay developer.

[matuzalemsteles]

In closing, we are working on unifying Clay and Lexicon right now https://liferay.atlassian.net/browse/LPS-189335.