UI Update discussion

[techknowlogick]

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

[sondr3]

I would love to see this happen as Gitea isn't very usable on mobile devices, but this would be a massive undertaking and one that I hope would not take away all the developers from maintaining and working on regular features for Gitea. 😃

[silverwind]

Focusing only on CSS now, I have two primary concerns:

1. semantic-ui is a dead end technology-wise. It does not embrace flexbox and I generally think it's doing to much on its own. I'd prefer to be in a bit more control, maybe just by adding some helper classes.

2. less is probably not needed. I think selector nesting is a bad because it leads to uselessly long selectors that are hard to search for in the source. With CSS supporting variables, I don't really see much use in having a preprocessor. I'd suggest converting to plain CSS.

[kolaente]

Dropping less in favour of native css variables would mean dropping support for some browsers, but I guess I'd be okay with that since most of the people using Gitea are devs anyways who usually are using up to date browsers.
A bigger problem for me would be to not be able to use things like darken($color) and being able to split the css in multiple files which would then be combined into one single css (I know native css can do that too... kind of)

A new design might also help to make it more clear Gitea is much different from Gogs because as of now, both share pretty much the same ui.

Framkework-wise, I'd throw bulma.io in the mix as that is something I've used in the past and found it pretty good. I takes the hassle out of most things while still allowing high custimization and therefore easy theming.

[tankerkiller125]

I think that giving Gitea its own unique UI is something that would certainly help show the difference between it and Gogs, At the same time I have to say that less or scss is probably something that should continue to exist in this project as some of their functionality is not available in CSS, framework wise I have no opinion that would benefit this discussion since I personally just use Bootstrap 4 for my projects (not something that should be used here)

[lafriks]

Bulma sounds good to me :) thought it means full UI rewrite sadly

[andrewbanchich]

I am definitely in favor of plain CSS and using standards like Flexbox and Grid over frameworks. Grid provides a lot of features that non-Grid frameworks cannot.

[lafriks]

@andrewbanchich Bulma is based on flexbox

[andrewbanchich]

Yes, but if it isn't based on Grid then it's still a framework that is using something in a way it wasn't meant for. First, grid frameworks used floats for layout, which was a workaround since floats weren't meant for any kind of layout. Now they are using Flexbox for the full 2D layout, but Flexbox is only meant for 1D layouts. Grid is meant for 2D layouts, and it can do things Flexbox cannot very easily, so I feel like we should just use the standard CSS Grid. In my opinion, there isn't much need for a grid framework anymore.

[lafriks]

Bulma is very lightweight and gives you quite nice looking style out of box, I don't think we have designer who could do us nice looking design for gitea here

[techknowlogick]

@lafriks I really liked @kolaente's design.

[silverwind]

A bigger problem for me would be to not be able to use things like darken($color)

Agree, I certainly need those as well and there is no clean CSS solution for color adjustments like this. I personally prefer SCSS over LESS, but for light usage, both should be about equal.

but if it isn't based on Grid then it's still a framework that is using something in a way it wasn't meant for

Grid is certainly an option, but are there any suitable frameworks based around it available?

[kolaente]

Here's a draft I played around with: (written in Bulma)

I'm not quite happy with it.

[lafriks]

@kolaente can you share it in some separate git repo somewhere? As I have been playing with bulma also and would be nice to work on this together

[kolaente]

@lafriks Sure: https://kolaente.dev/konrad/gitea-design

[mbedded]

The design made by @kolaente reminds me of Gitlab a little bit. It's great that there is a topic to discuss an enhancement of the UI. Personally i like the desktop design because it is close to Github. I guess this may help many developers to get started with the service.

Sometimes i add issues via my phone. The UI can be used, yes. But some other services have a better responsive UI. Unfortunately i am not that good with CSS.

Maybe Twitter Bootstrap could be used to be responsive (you can only select grid for example) and the other components like buttons have the custom layout.

[mrg0lden]

@mbedded it uses @jgthms's Bulma, which is a responsive CSS framework as well.

[mrg0lden]

Here's a draft I played around with: (written in Bulma)

I like GitHub's (everything in the middle) design more than GitLab's. I find it less distracting.

[xf-]

I'm new here - it started with opening issue #6687 and looked at less code and ask about a solution in sass. Afterwards @techknowlogick pointed me to this issue.

GitHub
I like design of GitHub, but lately with many new features it gets crowded. Status setting in drop-down, new experimental features in sidebar. -> Many different menu types. Most stuff moves to a side menu like new checks feature (also breaks the design in width). Looks like Github has a problem to fit everything into the website.

GitLab/Bitbucket
Not only GitLab uses the sidebar. Many Services switched to a sidebar, because it is easy to find & expand. Every entry and sub-entry on same element. It works on mobile up to 5k display (little bit lost) and easy to integrate outside of main content. The header area starts with information of this current page topic.
If you add a new feature or provide a plugin system, it is enough space to add a new (sub-)menu entry.

Css/ vs. sass
Use a compiler :) Css various from browser to browser and tools like a autoprefixer fixes a lot of small issues without writing multiple lines for every browser and dropping it later. Also features like nesting color variables and functions like darker/lighter, rgba($color, .8). With a linter you can enforce to only use colors as variables max nesting depth. Adjusting variables for a new theme is really easy.

Bulma theme
Looks good (single maintainer/no organization account), not standard bootstrap, material-design or (zurb-)foundation. Would only import the wanted components. Bulma sass syntax is uncommon. Compared with bootstrap more sizes are hardcoded.

I will use gitea either way, but i would like a improved dark theme (no stylus patch) and without variables more work to adjust something and get every page. Maybe i can help a little bit with style stuff, it it is wanted.

[silverwind]

On topic of a sidebar or other major redesigns: I think a main appeal to many users is that Gitea's UI is so similar to GitHub. If we change layout fundamentals like adding a sidebar, it will be very disruptive to users accommodated to the current layout and GitHub. I'm not sure I would accept it.

[mbedded]

Like @silverwind said: I guess it's very easy for users to switch or use Gitea if they are familiar with Github because the UI looks nearly same.
On the other hand (as @xf- said): Putting the menu on the left side makes it easier to group settings or menu items. Furthermore most screens are wide ones. So a menu on the left side gives permanent access to these items and doesn't discrupt the content. Maybe the topic "where to put the menue" has to be discussed at a later point if there are more than only 3-4 items.

[xf-]

Maybe starting with using variables and mixins for more consistency in current theme.

For Example. A private repo in sidebar hat 36px height and a public repo or organization 35px. Also Organization have less margin to left side. Also the width of both container is different. In profile second row of organizations has no margin t first row.

About the menu: Most navigation is OK and intuitive, but the Menus on top in settings/admin are really strange. I prefer the Menus in a list. Much easier/faster to find the wanted entry.

Also font-face is a complete mess. Lato is defined in sematic-ui.css and in index.css. I don't mean the :lang switches. I would use Noto font - Nearly every language is available, Monospaced and also emojis. (Maybe a little bit offtopic)
https://en.wikipedia.org/wiki/Noto_fonts
https://www.google.com/get/noto/

[mbedded]

That's true. From my experience (i am just doing a little web design because i am more a programmer than a designer): Tools like SASS or LESS are making using CSS so easy. The possibility to use and update variables code like is awesome.

Most IDEs include a SALL/LESS compiler by default or can be added as a plugin to update the css file when the source code file is saved. True the font may be off-topic here. But it's a part of the initial post to

I am opening this ticket so we can discuss future of Gitea UI

Maybe i can help a little bit with organizing some files or convert some parts to SASS. From my point of view (opinions may differ) there are two important things which should be updated:

• Responsive layout when using gitea at your mobile phone (e.g. to add issues while you are not able to use your normal device)
• Improve the display of admin-settings (or personal settings, as well) because there are many many settings. A vertical menu may be better than horizontal. Some may be added depending on planned or wished features.

As example: In Github (if Gitea likes to have a design similar to Github) your "normal" items are horizontal for code, issues, wiki, milestones..

Other settings of your repository, organization or personal account are vertically listed. From my point of view this is a great design decision. In Gitea there are not that many settings yet. But compared to github (if gitea grows much) the horizontal space won't be enough or we have all to switch to 16:10 screens or television screens :)

As you can see in the following screenshots:

Github settings, personal account:

Gitea settings, system administration:

What do you think?

[lunny]

I think we should always keep less items on menus to handle that. Less is more. :)

[NetOpWibby]

Something that'd make development of custom front-ends super easy would be the (not easy) task of creating an API for Gitea servers. That way, the front-end could be written in whatever framework people are comfortable with - Mithril, React, vanilla JS, whatever.

[kolaente]

@NetOperatorWibby Gitea has an api, it is just not feature-complete as of now, see https://try.gitea.io/api/swagger

[balthild]

I'm developing a bitbucket-like custom theme for gitea.

Preview:

The UI library that bitbucket used is built on top of React (Ref: Atlaskit), so I integrated React into Go template with some "dirty" means.

I maintained a string-to-module mapping in JS, and exposed a render() function to window. I can call the function in every template corresponding to a page, passing a unique string and some context variables required by the page as arguments. Then, the render() function finds out which React component should be mounted onto the page and renders it with those variables as props.

Honestly, the current implementation doesn't really meet the philosophy of React apps, but it works, and in fact, it's simpler than a "real" React SPA, because you don't need to care about routers and global states.

[kolaente]

@balthild Looks awesome! So this is essentially a "translation layer" put on top of Gitea which translates the Gitea Template to React?

[balthild]

@kolaente Yes. The reason is not only about the lack of APIs, but also the internationalization library. There's no JS equivalence for github.com/Unknwon/i18n, so I must format the strings in Go.

[xf-]

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)

[6543]

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

[turbopixel]

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: #5937 (comment)

[silverwind]

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.

[lafriks]

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

[silverwind]

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.

[silverwind]

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

[mrg0lden]

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.

[silverwind]

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.

[xf-]

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.

[mrg0lden]

@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.

[lafriks]

@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 🤷‍♂️

[mrg0lden]

@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.

[lafriks]

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

[silverwind]

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).

[lunny]

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 ... :)

[Ryuno-Ki]

@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:

1. What is your personality? Which adjectives describe Gitea the best?
2. What is your offer?
3. 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 #10669 (comment)

@lunny opened #19902 to track those.

I've also learned about inconsistencies of elements, not yet turned into a Vue component, e.g. #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.

[wxiaoguang]

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.

[morki]

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.

[Ryuno-Ki]

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.

[6543]

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

[6543]

#19650 , #19901

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

[philip-peterson]

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

[dorianim]

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?

[kecrily]

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

[gnat]

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/

[philip-peterson]

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.