UI Update discussion #5937

Open techknowlogick opened 5 years ago

Per discussion in #5932, and @kolaente's suggestion. I am opening this ticket so we can discuss future of Gitea UI

Yeah, we're already too heavily invested in server-side rendering, so I think a full conversation to SPA is almost certainly out of question.

I think it would be interesting if Gitea adopted a horizontal layout, similar to what Azure Repos uses. This layout is much more elegant and efficient imho, and uses screen real estate in a more intelligent way. Here are some screenshots to illustrate what I mean:

like every other UI does it because it also works on smaller devices and scrolling down is OK. Even GitHub starts to use 100% of the screen e.g. new notifications (or checks / file changes in a PR)

I like the curent stile - but this is only my opinion

I do not always like the view under "Changed files". From time to time I have pull requests where 20 files and more have been modified - which is not always avoidable (Migration PHP 5.6 -> 7.3).

The problem is that the browser needs a lot of time to show the changes. The Pull Request page loads fast. Only the syntax highlighting eats up a lot of time.

Here a view similar to Gitlab is recommended.

I'm talking about a pull request view like in this style: https://github.com/go-gitea/gitea/issues/5937#issuecomment-584859265

I'm still wondering if there is any UI framework out there that can really replace our use of Fomantic-UI. It needs to:

Be flexbox-based
Be themeable via CSS variables
If there are icons, they need to be SVG
Have full-featured dropdowns and menus with HTML content inside the dropdown
Work with server-side-rendering, e.g. no React/Vue/Angular-based stuff

Bootstrap 5 almost fits that bill but dropdowns would need to come from another library and their CSS variables are pretty much a work in progress.

why not build it on top of bulma? Clean and fully flexbox based :]

I wrote of Bulma because of icon fonts but it seems they do at least support SVG icons. E.g. https://bulma.io/documentation/components/dropdown/ has icon font stuff in the example code but if you check the live example, it's actually SVG and something (JS?) is hiding the icon font:

Only thing lacking in Bulma is CSS vars, but I guess that could be worked around, thought their Sass variables probably present the same issue with fomantic where one cannot specify CSS variables for colors because then Sass color variation functions would inevitably throw up.

Seems like CSS vars are on the table for Bulma at least, https://github.com/jgthms/bulma/pull/2981. We definitely want to wait on that.

Maybe take a look at Tailwindcss, I moved from Bulma to it recently, and it provides much more, with a cleaner code and a better DX.

Not sure about Tailwind. It would mean we have to litter our HTML with those helper classes and there's no more style sharing between components. It's a different paradigm that can work for small sites but I'd see it being a pain if you want for example to change all box headers which would previously be one line CSS change would now be a 100 line HTML change.

I would go with Bootstrap (v5 uses variables in FE).

V5 icon stuff is also svg https://icons.getbootstrap.com/#sprite
No jQuery in v5

It is the most common and known that increases the chances for a PR and also often different library offer Bootstrap class/template support.

@silverwind I'm happy to say that's not the case! That was my first impression as well. But once you're done prototyping, you copy all these classes and replace them with a single one. Here's an example from the docs.

@silverwind I'm happy to say that's not the case! That was my first impression as well. But once you're done prototyping, you copy all these classes and replace them with a single one. Here's an example from the docs.

I would still rather write css than have to lookup from tons of helpers :man_shrugging:

@lafriks TBH I sometimes look up normal CSS props, so I cannot see the problem with looking up the helpers. For me, it saves time to type px-4 instead of padding-right: 4px; padding-left: 4px or padding: 0 4px. It also helps with defining a design system, as px-4 doesn't actually mean 4px but a pre-defined value that you could change.

Values can be easily moved out to variables but knowing css is more useful to know in general but that's a bit off topic already

I think tailwind isn't right for us and this @apply just sounds like classes all over again (thought classes are also useful in JS).

I would go with Bootstrap (v5 uses variables in FE).

V5 icon stuff is also svg https://icons.getbootstrap.com/#sprite

No jQuery in v5

It is the most common and known that increases the chances for a PR and also often different library offer Bootstrap class/template support.

The first version of Gogs used Bootstrap ... :)

@wxiaoguang pointed me this way. I've read the thread and see, there's a lot to unpack. May I?

Tooling focused

From my observation here, the discussion is tooling-centric. That's okay, given the number of developers here, but perhaps not the best approach.

I'd like to take into account feedback gathering from User Research if possible: https://lab.fedeproxy.eu/fedeproxy/ux/-/wikis/2021-06-user-research-report

Branding

But also: Finding your own voice. This can feel a bit too corporate for some of the folks here, but bear with me. I have https://blog.mozilla.org/opendesign/our-brand-personality/ in vivid memory. From what I observed, it is an approach common in the industry, so might be worth a try (or could be discarded as too much).

Probing questions would be:

What is your personality? Which adjectives describe Gitea the best?
What is your offer?
What makes you different?

UX, not only UI

Based on that, you can derive some ideas. This affects different parts of the UI, like the chosen colour palette, typography, spacing, tone and voice etc.

Styleguide, Component Library oh my

Next thing I want to highlight is the migration to Vue. This could end up in a component library. Although worthy, I'm not sure, whether it is enough.

I spent some time the last days to triage confirmed UI issues on this repository and digged up, where to find the code in need of change and what remaining questions are open (for me personally if I were to work on it). This also led to observation, that some dependencies are not Vue3-ready (but community forked it). See for example https://github.com/go-gitea/gitea/issues/10669#issuecomment-1146889731

@lunny opened https://github.com/go-gitea/gitea/issues/19902 to track those.

I've also learned about inconsistencies of elements, not yet turned into a Vue component, e.g. https://github.com/go-gitea/gitea/issues/3605 Some other parts came on my radar, but I haven't filed issues for them. Question here could be to utilise the time and port code to Vue3 instead of turning everything into a Vue2 component and then migrate the codebase to Vue3.

Speaking of components, I noticed that https://storybook.js.org is gaining traction in the community. Utilising that could help also documenting and testing components (in isolation, as screenshot etc). The biggest hurdle I can see here is the interplay with Go templates.

If you want to develop more than a component library, take a look at styleguide. The community collects examples over at http://styleguides.io

Tooling

Regarding the tooling question: It depends. I would look for a CSS only library to handle the grid and smooth over browser inconsistencies. Interactive elements can be handled by Vue (or as Web Components?). Keep in mind that dependencies also introduce a maintenance burden as you need to follow the version upgrades there … Homebrewing something could be harder than visible from the outset. I would advise against it until more knowledge is insourced. I can see some potential (for example, designating CSS Grid areas that allow for moving elements around to allow for themes like the Bitbucket one above). Take a look at https://gridbyexample.com if you want to learn about options.

Listening to the audience

I suggest to track user feedback as issues. For example https://news.ycombinator.com/item?id=31633837 mentioned that the org UI has potential for improvements. Would be great to reach out and ask for concrete issues (I'm not on Hacker News, though).

Potential roadmap

If I were to advise, I would move away to Fomantic, but keep their CSS classes for now. Interactive components should be refactored into Vue components (but using HTML classes for styling). Once those are complete, use a converter (like https://jsonformatter.org/less-to-scss ?) and turn the Fomantic LESS files into SCSS files in this repository. The architecture should follow the 7-1 pattern: https://sass-guidelin.es/#the-7-1-pattern

During this migration, listen to complaints (not only about Gitea, but also other Forges) to detect areas, that could be done better.

A clear and feasible roadmap is the key to success. I have closed #18302, just copy my thoughts here, the uncertain problems without answers on the roadmap in my mind.

Background

Gitea frontend now uses Fomantic-UI components heavily, ex: Dropdown, Modal, Checkbox, etc. Almost all pages are written in MVC (Go template + Fomantic-UI).
Fomanic-UI heavily uses jQuery, many components only work with its jQuery code.

Questions

Gitea has a lot of legacy MVC code and uses many jQuery features: event system, ajax, filter, chained-call $().parent().foo().bar() and batch DOM modification. If Fomantic-UI jQuery are dropped, all related code should be rewritten, maybe it would result in a house-made jQuery-like framework in the end.
If migration starts, then new PRs using jQuery come, what is expected to do? Force the contributor to rewrite (not friendly)? or maintainers rewrite for them (does everyone agree to help)? or just accept it (nightmare for the migration)?
Continuity, if the migration starts, it must be guaranteed to succeed. Otherwise if it stops half-way, then more and more frameworks would be mixed together, it would be a big disaster.
And one more thing, how to use Vue properly for Gitea frontend? The Vue-based repo-search (DashboardRepoList.js & user/dashboard/repolist.tmpl) is a bad example IMO.

What about using alpine.js for the JS part? It is conceptually pretty close to Gitea's server rendered templates and only enhances it. It has very simple learning curve to new contributors too.

I was in favour if alpine for a long time. However, I feel they pivoted into a direction I can no longer recommend. Instead HTMX might be more in line if there is only a small interactivity needed.

That being said, looking at the current Vue components, I feel like we should pick something with a vibrant ecosystem, that already provides parts of what we need.

didn't we agree to move more stuff into VUE3 components we do include?

19650 , #19901

https://docs.gitea.io/en-us/guidelines-frontend/

One thing I haven't seen mention of is Custom Elements, which lets you get a Vue/React style component interface without all the overhead. Custom Elements are native to the browser and have very good support across vendors. This would lend itself well to being instantiated across the many templates Gitea has. One example framework is lit or lit-html.

https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements https://caniuse.com/custom-elementsv1

I'm not really sure, if this is the right place for this, but I'd like to bring some attention to the theme of Freeplay over here: https://codeberg.org/Freeplay/Gitea-Modern

I think, it looks really cool and unique. Maybe a UI/UX makeover could take some inspiration from this?

Maybe we can start by converting css to tailwind/windicss/unocss/etc?

This will likely hurt some feelings, but as an actual gitea feature contributor myself (who plans to contribute more in the future, too), it has to be said..

The only frontend that has staying power is vanilla CSS / JS, ideally zero build

Non-vanilla front ends change on a monthly basis and can put Gitea on a dependency death clock at worst- Like most other projects in this space.. these dependencies can be difficult or impossible to remove in the future.

Added layers will cause friction and new barriers for contribution-- New gitea features will be at risk of never happening. Don't let the architecture astronauts junk up the front-end with unnecessary complexity.

Gitea currently has excellent long term staying power because of it's simplicity, few dependencies, ultra-low friction to contribute or debug.

Article on this subject: https://htmx.org/essays/no-build-step/

It’s true, you can never rely on dependencies that change every few months. That’s why we should ditch Go and adopt C, as it’s far more mature and static. 😉

On a serious note though, I don’t think this issue (which probably could be split into several issues) has to be about “which technology do we add?”; rather it can be something about consolidation, organization, and simplification. Right now we are already on a ‘dependency death clock’ with Fomantic and Normalize.css, and we suffer from fragmentation between Vue and jQuery. IMO, reducing fragmentation is far more important than going zero build or even picking the "right" technology.

It’s worth noting that the splay of logic between frontend and backend is its own kind of fragmentation as well.

go-gitea / gitea