Website Design Update about gno HOT 5 OPEN

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!

from gno.

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.

from gno.

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.

from gno.

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

from gno.

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.

from gno.