Website Design Update

[moul]

We aim to update the design of our main website. The current design could benefit from a more minimal, simple, and efficient approach in terms of space and speed. We invite you to propose solutions and be considered to take ownership of this project component.

---

We're looking for someone to:

1. Migrate the design: The new design should be more similar to suckless.org. It should be super minimal, simple, straightforward, clean in hierarchy, and efficient in space. The emphasis should be on the content rather than flashy visuals.
2. Optimize the HTML/CSS/JS: The website's code should be minimal and optimized for speed.
3. QA everything: This includes the site itself and the func helpers. We want to ensure that everything is working as expected and providing a good user experience.
4. Switch to a non-monospace font: By default, the website should use a non-monospace font. However, code blocks should still use a monospace font.

---

Before starting, we'd like you to give feedback on these proposed changes and define your plan to tackle this project. Once we agree on the plan, you can proceed with the redesign.

[amritkumarj]

Sounds like a great idea! We've created a preliminary design to showcase our vision for the website and would love the opportunity to contribute to its development. Thanks!

[alexiscolin]

Hey team, @moul, @gfanton , @zivkovicmilos, @leohhhn

To bootstrap this FE/design project, we should consider the following elements:

Given that gnoweb is a web tool used by developers during the smart-contract creation workflow (localhost focused), but also by general users to view the render of all indexed realms (kind of smart contract browsing):

1. Browser Compatibility

• One of the most important question: what are the minimum versions of each browser we aim to target (IE, Edge, Safari, etc.)?
• If we want to be universal, targeting a broad set of browsers makes sense. However, even if the website is straightforward, some parts could be improved by using modern CSS or JS features.
• Consider using a tool like Babel for JavaScript transpiling and Autoprefixer for CSS to ensure compatibility with older browser versions.
• Images: Ensure compatibility with modern image formats like WebP while providing fallbacks for older browsers. Use responsive images with srcset and sizes.

2. Accessibility:

• Do we want to be 100% compliant with ARIA and A11y recommendations? (This would be beneficial for this project, in my opinion.). This involves keyboard navigation, color contrast checks, descriptive content, semantic html, text alternative, clean and valid html/Css etc.
• If yes, do we want to implement accessibility tests, with predefined standard (WCAG 2.1 guidelines would be great)?

3. SEO

• Do we want the website to be fully indexed?
• If yes, we might want to create dynamic meta properties (allowing smart-contract creators to customize realm metadata).
• If not, we need a strategy to create default, automated meta titles, descriptions, canonical tags, etc.
• What is our strategy for handling sitemap and robots.txt files?
• Should we include Open Graph tags and Twitter cards for better social media sharing?
• Might be great to use structured data (such as jsonlp) to help search engines understand our content better
• Performance and Mobile Optimization is a good consideration. Having a website in mobil first could help improving the ranking as many search engine bots are testing website in mobile first today. It's also a good practice (keeping in mind our users may be not on mobile)

4. Security

• What level of security and which security measures should we implement (XSS, CSRF, etc.) to address threats that could arise from form components and other components ?
• How will we handle authentication and authorization if needed?
• Should we use Content Security Policy (CSP) headers to mitigate XSS attacks? Maybe it's already the case (this question is far beyond this front-end dev issue but good to keep in mind if it's not already the case).

5. Third-Party Scripts

• Are we going to use third-party scripts in addition to Simple Analytics, etc.? I guess we should avoid as much as we can (for security and performance mattersà but it's still a question

6. Front-End Tooling

• We should implement a front-end workflow with a bundler, a linter, and testing tools. For example:
  • Bundler: Use a modern bundler like Vite, Webpack, or Parcel to bundle and minify our assets efficiently, enabling features like code splitting and hot module replacement. The one we should use would be related to the browser compatibility.
  • Linter: Implement ESLint for JavaScript and Stylelint for CSS to ensure code quality and consistency across the codebase. We will need a standard to follow.
  • Formatter: Use Prettier for automatic code formatting to maintain a consistent style. We will need a standard to follow.
  • Testing: Integrate a testing framework such as Jest or Mocha for unit tests, and tools like Cypress or Playwright for end-to-end tests.
  • Browser Compatibility Tools: Do we want to use tools like Browserslist to manage and query the list of target browsers and check the render for all of them. May be too much for this website though.
  • Build Performance: Optimize build performance by using caching strategies and efficient plugins. Is it something we can do?

7. Code Structure

• How are we going to set up our CSS and JS code?
• For CSS, using a clear semantic architecture (BEM, SMACSS, Atomic, etc.) would help us maintain consistency in the long term, avoid DRY violations, and address web performance issues while improving codebase maintainability.
• We need a good and agnostic naming convention.
• Another question is the use of a CSS preprocessor, which may be unnecessary for a tool that aims to be simple and straightforward.
• How will we structure our components? (e.g., Atomic Design, Component-based architecture)
• Should we use Typescript to get a more robust and organized code? How to organize and document code to ensure readability and maintainability? Might be a good idea anyway.
• Should we use tools for documentation? (e.g., Storybook for UI components, JSDoc for code documentation)

8. Performance

• How will we test and optimize the performance of the website? Do we want a webperf budget (score)?
• What tools and metrics will we use to ensure the site loads quickly and efficiently? I would recommend Lighthouse, WebPageTest to start, they can also be added to the CI.
• How will we implement lazy loading and code splitting to improve load times if it's something we want to add (depending on browser compatibility)
• Minification and Compression need to be kept in mind. Minify CSS, JavaScript, and HTML files using tools like UglifyJS and cssnano, and enable Gzip or Brotli compression on the server.
• Even if the website content is mostly made by texts, Image Optimization for modern formats like WebP, optimize images with tools like ImageOptim, and implement responsive images using srcset and sizes could also help.
• A good Font Loading strategy should be used. Using default OS font might improve the loading speed, while a swapping strategy in the CSS to ensure text remains visible during webfont load could be another idea.
• Implement effective caching strategies with HTTP headers for static assets and leverage service workers for offline caching.

9. Developer Experience

• Could wee add the front-end workflow within gnodev? To ensure rapid feedback loops during development (e.g., hot module replacement, fast build times)?

I will take care of addressing these questions and providing solutions with a plan next week. I have many ideas for these. But some are important such as the browser compatibility. I would recommend a good balance to target JS/CSS feature used by more than 95~96% of users. Also maybe targeting IE might be too much mut maybe we want to target more and even 100%.
Anyway, this is just an initial list of considerations, a task list that I'm sharing with everyone. Let's collaborate and refine these points together to ensure our project is robust, user-friendly, and maintainable.

Feel free to discuss further.

[alexiscolin]

We've started working on a setup with @gfanton. We've started setting up the project and decided that rendering the front-end via Go on the back-end would be most efficient (with a good Ops of course). Given the UI/UX and goal of Gnoweb, this approach allows us to avoid frameworks, speeding up development and keeping the project lightweight. Especially with a general Gno / Gno codebase and associated developers who are more familiar with Go language. Also, by rendering Markdown on the server-side, we eliminate front-end delays, providing several benefits for SEO, UX, and UI. Server-side rendering ensures faster page loads and better SEO by delivering content-rich pages to search engines directly. It also enhances the user experience by reducing perceived load times and improving UI consistency.

Additionally, we'll handle code syntax highlighting on the server-side instead of using Highlight.js, ensuring consistent and fast rendering. We'll utilize vanilla JavaScript (TypeScript) for adding web components to enrich the Markdown rendering. Therefore, this plan will mostly focus on CSS rendering while leaving JavaScript for enhancing UI components (in a next PR).

Finally, here is a draft of propositions. Some may be challenged as there is always pitfalls and other ways to structure the projects.

1. Browser Compatibility:

• Minimum Browser Versions:
  • Target Browsers: Chrome, Firefox, Safari, Edge (latest versions), with fallback support for IE11 if necessary.
  • Tooling: Use esBuild as JS/TS bundler for transpiling, minification, and Autoprefixing for CSS in order to ensure compatibility with older browser versions but in a very fast way. Also esBuild being written in Go, it allows a good interoperability with gno codebase.

2. Accessibility Compliance:

• Target: Aim for 100% compliance with ARIA and A11y recommendations.
• Testing Tools: Implement accessibility tests using axe-core and Lighthouse.
• Standards: Follow WCAG 2.1 guidelines for keyboard navigation, color contrast, semantic HTML, text alternatives, and valid HTML/CSS.

3. Front-End Workflow:

• Bundler: As said before, use esBuild + Vite (for HMR and maybe dev mode) for efficient asset management, code splitting, and hot module replacement.
• Linters: Implement ESLint for JavaScript and Stylelint for CSS.
• Formatter: Use Prettier for consistent code formatting.
• Testing: Integrate Jest for unit tests
• Browser Compatibility: Use Browserslist to manage and query target browsers.
• Build Optimization: Optimize build performance with caching strategies and efficient plugins.
• Front-End Integration: Integrate the front-end workflow with Gnodev for rapid feedback loops (low prio).

4. Code Organization:

Class Abstraction vs. Utility Classes: Discuss the preference between using many utility classes directly in HTML or abstracting them into custom classes with the @apply directive. This decision should be based on team consensus, considering the project's needs for readability, maintainability, and scalability.

• Tailwind CSS: We will use Tailwind CSS for its utility-first approach, which allows us to create clear, maintainable, and scalable CSS. Tailwind enables us to apply styles directly within the HTML, reducing the need for writing custom CSS and improving development speed and consistency. It also allow us to share the design config file to other projects (such as playground one) super easily, to be consumed on the fly (it avoids duplication and error, but need a discipline in the way it's used).

• Guidelines for Using Tailwind CSS:

  • Utility Classes: Make use of Tailwind’s utility classes for most styling needs, keeping the CSS within the HTMLclean and concise.
  • Custom Configuration: Customize the Tailwind configuration file (tailwind.config.js) to define project-specific colors, fonts, spacing, and other design tokens.
  • JIT Mode: Use Tailwind’s Just-In-Time (JIT) mode to generate styles on-demand, resulting in faster build times and smaller CSS bundles.
  • Purging Unused Styles: Configure Tailwind to purge unused styles in production builds to minimize the CSS file size.
  • Consistent Design System: Utilize Tailwind’s design tokens and extend functionality to ensure a consistent design system across the project.

• Naming Conventions:

  • Establish consistent and descriptive naming conventions for classes and components to enhance readability and maintainability. Follow Tailwind's recommended class naming practices for utility-first styling.
  • BEM Methodology: When writing custom classes using the @apply directive (what should be avoided when possible), adopt the BEM methodology to provide additional structure and clarity. If a block is purely styled with Tailwind utilities, document it clearly in HTML to avoid confusion (by using it anyways).

Blocks: High-level components (e.g., .card).
Elements: Parts of the block (e.g., .card__title).
Modifiers: Variations of the block or element (e.g., .card--highlighted).

• Preprocessor: Given that the site is minimalistic and Tailwind provides a comprehensive utility-first approach, using Sass, Stylus or another preprocessor may not be necessary. Tailwind’s configuration and utility classes should cover most styling needs, reducing the need to write additional CSS.

5. Performance Optimization:

(bundler related)

• Performance Budget: Set and adhere to a web performance budget (TODO).
• Testing Tools: Use Lighthouse and WebPageTest for performance testing.
• Lazy Loading: Implement lazy loading and code splitting.
• Minification and Compression: Minify CSS, JavaScript, and HTML. Enable Gzip/Brotli compression.
• Image Optimization: Optimize images with modern formats and responsive techniques.
• Font Loading: Use font-display: swap and consider system fonts for better performance.
• Caching: Implement effective caching strategies and service workers for offline support (low prio).

6. SEO Strategy:

• Indexing: Ensure the website is fully indexed.
• Meta Properties: Create dynamic meta properties for better customization.
• Default Metadata: Generate default meta titles, descriptions, and canonical tags automatically.
• Sitemap and Robots.txt: Regularly update XML sitemap and manage robots.txt to guide search engine crawling.
• Social Media Tags: Include Open Graph and Twitter cards.
• Structured Data: Implement JSON-LD for structured data to enhance search engine understanding.
• Mobile Optimization: Ensure the site is mobile-friendly and responsive, adhering to mobile-first indexing principles.

7. Third-Party Scripts:

• Usage: Minimize use of third-party scripts to maintain performance and security.
• Assessment: Evaluate necessity and impact of each script. Less is better

8. Security Measures:

• Preventative Measures: Implement XSS and CSRF protections.
• CSP Headers: Use Content Security Policy (CSP) headers.

9. Documentation:

Tools: Us JSDoc for code documentation (JS/TS files).

10. Design and UX:

Design System: Create a design system or component library to ensure a consistent and intuitive user experience.

[alexiscolin]

Since the server-side development might be stalled because @gfanton is busy and to keep things moving forward, I propose that we finish the design this week and work on the front-end using static mockup data. We can focus on HTML and CSS only.

This approach has several advantages IMO:

• It allows us to make progress without waiting for the server side to be finished.
• It gives us the opportunity to design and finalize the user interface with mock data.
• @gfanton will be able to use this static mockup to split the go templates / partials which will save time.

I think this is a practical way to proceed and would appreciate your thoughts on this proposal.
What do you think? @leohhhn @gfanton

[gfanton]

Sounds super cool !

Linters: Implement ESLint for JavaScript and Stylelint for CSS.
Formatter: Use Prettier for consistent code formatting.

I suggest checking out https://biomejs.dev/ for the linting and formatting part. I haven't personally tried it, but I like the idea of having a single opinionated tool for both linting and formatting.

For the server-side, I recommend using https://github.com/a-h/templ as a templating system:

• It generates Go files, inheriting Go's safety when building.
• It includes a watch feature.
• You can generate static HTML code.
• You can import Go code directly into template function.
• It has no dependencies. Despite its go.mod showing some direct/indirect dependencies, they are only used for the generation tool within templ. With the generated files only relying on the https://github.com/a-h/templ package, which itself has no other dependencies.

For Markdown rendering, I suggest using https://github.com/yuin/goldmark. We need to keep in mind how to extend the Markdown syntax (#439). My goal is using this library to extend the Markdown capacity and create a library that we can easily use for gnoweb to render custom components, as well as for external use, by leveraging goldmark's custom rendering feature.
Also this lib has no direct dependencies.

Since the server-side development might be stalled because @gfanton is busy and to keep things moving forward, I propose that we finish the design this week and work on the front-end using static mockup data. We can focus on HTML and CSS only.

Yes, unfortunately I will be quite busy this month and may move slowly. If you can start working on this without relying on me, that would be fantastic.

[alexiscolin]

Hey 👋

After some exchanges with @gfanton, here is a list of design proposals for this refactoring to address the requirements in this issue.

Goals:

• Incorporate the gno.land rebranding: Apply the new colors while keeping the light and dark theme options available + adding an agnostic flat, minimal and polished shell around the page.

• Optimize space: Reduce purely UI elements and spaces to prioritize textual content (markdown first approach in order to have a clean content focused on realm content by default).

• Enhance navigation: Update the menu with an additional lateral navigation (content to be dynamic or static?) to improve UX by allowing more entries on the page, making it easier for users to navigate through gnoweb.

• Refine the header: Highlight the realm address and related options (help, source...) as a sub-navigation to let user quickly understand where he is and how to deal with the content at first glance (made for localhost first - as dev tool)

• Standardize content width: Use a dedicated UI component to maintain consistent content width for better readability.

• Simplify UI elements in the content: Preserve the clean essence of markdown by default, focusing on readability improvements rather than stylistic elements. UI components will be enabled later to minimize UI code and enhance website speed.

• Introduce a panel logic (to be discussed): Would allow inspection of the current page realm (next to the page) or help users visually understand how the realm is created. This panel can also be full-screen. It aims to show a better code transparency through gnoweb. @gfanton also shared the idea of having (later) the realm variables values displayed in this kind of panel in order to improve further the transparency.

These changes aim to address the issues raised by improving both the visual consistency and the user experience across the site. By focusing on minimalistic design (easy to maintain by default and to update), optimizing HTML/CSS/JS, and ensuring a seamless user experience, I hope to create a more efficient and user-friendly website. @gfanton

---

However, one thing we should consider is the shell (header, navs, footer). They are currently tied to the gno.land website. As a gnoweb user, I would prefer to avoid having gno.land menus visible. This could be confusing if I'm building my own website (DAO, etc.) on gnoweb, as my users might see the gno.land navigation at the top, which they may not be interested in. In my opinion, we should keep these elements in the footer for consistency but avoid including them in the default navigation. The default navigation should be clean and either customizable or very relevant to the realm itself. It something we should think about.

---

---

Regarding the design/branding itself, the green color might also be too opinionated and a very clean/refined version could looks like that:

cc @zivkovicmilos, @leohhhn

Of course I would be happy to iterate over this concept (and ideas) to refine and polish it.

[grepsuzette]

Looks great at a first glance.

• The daylight version in particular with its solid color header is very appealing.
• The source code panel on the right looks awesome.
• Good layout, I think this is a good design.

Neats:

• Regarding the use of green in the dark theme, to me black + green at night is too "narrow".
• Should probably remove the rectangular gray borders on the dark theme (they are absent on the daylight version and it's better).
• Not completely about the design, but there is a major clash between the blue gopher and the website. Colors and styles are too different.

[alexiscolin]

Thank you for your feedback @grepsuzette!

Few words regarding your neats:

• Yeah I do agree regarding the green+dark (I made some tests and tried with a lighter green but we can improve it).
• The rectangle is just an illustration of the jumbotron UI element (not added by default) as we currently have on the homepage. For sure both themes will have the same render at the end.
• I should have mentioned it but the blue gopher is just a fake placeholder that should not appear here in the end. That a way to see how it looks, even with a random image (what we should avoid in the end).

[alexiscolin]

I'm redesigning a bit the layout to avoid opinionated design like mentioned above. The idea would be to get something lighter and more agnostic in order to host any kind of design from the render function (a PR with web-component to create UI like bootstrap should come soon). Again, feedbacks are welcome.

Regarding the design/branding itself, the green color might also be too opinionated and a very clean/refined version could looks like that: