setup translations, and grammar/structure pass

Co-authored-by: jncrabb <[email protected]>

Author: corwintines

public/content/developers/docs/design-and-ux/dex-design-best-practice/index.md

@@ -1,19 +1,20 @@
 ---
-title: Decentralised Exchange (DEX) Design Best Practice
+title: Decentralized exchange (DEX) design best practices
 description: A guide explaining UX/UI decisions for swapping tokens.
 lang: en
 ---
-# Introduction to Decentralised Exchanges
 
-Since the launch of Uniswap in 2018, there have been hundreds of Decentralised Exchanges launched across dozens of different chains.
+# Introduction to decentralized exchanges {#introduction-to-decentralized-exchanges}
+
+Since the launch of Uniswap in 2018, there have been hundreds of decentralized exchanges launched across dozens of different chains.
 Many of these have introduced new elements or added their own twist, but the interface has remained generally the same.
 
 One reason for this is [Jakob’s Law](https://lawsofux.com/jakobs-law/):
 
 > Users spend most of their time on other sites. This means that users prefer your site to work the same way as all the other sites they already know.
 
 Thanks to early innovators like Uniswap, Pancakeswap, and Sushiswap, DeFi users have a collective idea of what a DEX looks like.
-For this reason, something like “best practice” is now emerging. We see more and more design decisions being standardised across sites. You can see the evolution of DEXes as a giant example of testing it live. Things that worked stayed, things that didn’t, got tossed out. There’s still room for personality, but there are certain standards a DEX should conform to.
+For this reason, something like “best practice” is now emerging. We see more and more design decisions being standardized across sites. You can see the evolution of DEXes as a giant example of testing it live. Things that worked stayed, things that didn’t, got tossed out. There’s still room for personality, but there are certain standards a DEX should conform to.
 
 This article is a summary of:
 - what to include
@@ -24,7 +25,7 @@ All of the example wireframes were made specifically for this article, although
 
 The Figma kit is also included at the bottom - feel free to use it and speed up your own wireframes!
 
-## Basic Anatomy of a DEX
+## Basic anatomy of a DEX {#basic-anatomy-of-a-dex}
 
 The UI generally contains three elements:
 1. Main form
@@ -34,25 +35,25 @@ The UI generally contains three elements:
 ![Generic DEX UI, showing the three main elements](./1.png)
 
 
-## Variations
+## Variations {#variations}
 
-This will be a common theme in this article, but there are various different ways these elements can be organised. The “details panel” can be:
+This will be a common theme in this article, but there are various different ways these elements can be organized. The “details panel” can be:
 - Above the button
 - Below the button
 - Hidden in an accordion panel
 - And/or on a “preview” modal
 
 N.B. A “preview” modal is optional, but if you are showing very few details on the main UI, it becomes essential.
 
-## Structure of the Main Form
+## Structure of the main form {#structure-of-the-main-form}
 
 This is the box where you actually choose which token you want to swap. The component consists of an input field and a small button in a row.
 
 DEXes typically display additional details in one row above and one row below, although this can be configured differently.
 
 ![Input row, with a details row above and below](./2.png)
 
-## Variations
+## Variations {#variations2}
 
 Two UI variations are shown here; one without any borders, creating a very open design, and one where the input row has a border, creating a focus on that element.
 
@@ -62,7 +63,7 @@ This basic structure allows **four key pieces of info** to be shown in the desig
 
 During the evolution of DeFi, lots of different things have been included here.
 
-## Key Info to Include
+## Key info to include {#key-info-to-include}
 
 - Balance in wallet
 - Max button
@@ -81,7 +82,7 @@ Extra details can be shown below the main form. As this type of info is mostly f
 
 ![Details shown in the corners of that main form](./4.png)
 
-## Extra Info to Include
+## Extra info to include {#extra-info-to-include}
 
 - Token price
 - Slippage
@@ -117,7 +118,8 @@ Entering numbers in Main Form → Scanning Details → Clicking to Preview Scree
 Should the details panel be visible at all times, or does the user need to click it to expand?
 Should you create friction by adding a preview screen? This forces the user to slow down and consider their trade, which can be useful. But do they want to see all the same info again? What is most useful to them at this point?
 
-## Design Options
+## Design options {#design-options}
+
 As mentioned, a lot of this comes down to your personal style
 Who is your user?
 What is your brand?
@@ -126,13 +128,15 @@ Even if you’re aiming for the pro users who want all info possible, you should
 
 > No matter how beautiful, no matter how cool your interface, it would be better if there were less of it.
 
-### Structure
+### Structure {#structure}
+
 - tokens on the left, or tokens on the right
 - 2 rows or 3
 - details above or below the button
 - details expanded, minimized, or not shown
 
-### Component Style
+### Component style {#component-style}
+
 - empty
 - outlined
 - filled
@@ -157,7 +161,7 @@ Take a look at the below examples to see different ways you can put it all toget
 
 ![2 rows in a filled style](./12.png)
 
-## But which side should the token go on?
+## But which side should the token go on? {#but-which-side-should-the-token-go-on}
 
 The bottom line is that it probably doesn’t make a huge difference to usability. There are a few things to bear in mind, however, which might sway you one way or the other.
 
@@ -175,15 +179,15 @@ The law of proximity states that items that are close together are perceived as
 
 Ultimately, there are pluses and minuses for both options, but it is interesting how the trend appears to be towards token on the right.
 
-# Button Behaviour
+# Button behavior {#button-behavior}
 
 Don’t have a separate button for Approve. Also don’t have a separate click for Approve. The user wants to Swap, so just say “swap” on the button and initiate the approval as the first step. A modal can show progress with a stepper, or a simple “tx 1 of 2 - approving” notification.
 
 ![A UI with separate buttons for approve and swap](./14.png)
 
 ![A UI with one button that says approve](./15.png)
 
-## Button as contextual help
+## Button as contextual help {#button-as-contextual-help}
 
 The button can do double duty as an alert!
 
@@ -197,11 +201,11 @@ If the main action - SWAP - is unavailable due to an error, the reason why can b
 
 The button can also be **mapped to the action** that needs to be performed. For example, if the user cannot swap because they are on the wrong network, the button should say “switch to Ethereum”, and when the user clicks on the button, it should switch the network to Ethereum. This speeds up the user flow significantly.
 
-![Key ctions being initated from the main CTA](./16.png)
+![Key actions being initiated from the main CTA](./16.png)
 
 ![Error message shown within the main CTA](./17.png)
 
-## Build Your Own with this Figma File
+## Build your own with this figma file {#build-your-own-with-this-figma-file}
 
 Thanks to the hard work of multiple protocols, DEX design has improved a lot. We know what info the user needs, how we should show it, and how to make the flow as smooth as possible.
 Hopefully this article provides a solid overview of the UX principles. 

public/content/developers/docs/design-and-ux/heuristics-for-web3/index.md

@@ -4,12 +4,12 @@ description: Principles to improve the usability of Web3
 lang: en
 ---
 
-# Heuristics for Web3
+# Heuristics for Web3 {#heuristics-for-web3}
 
 Usability heuristics are broad “rules of thumb” that you can use to measure the usability of your site.
 These heuristics are specifically tailored for Web3 and should be used alongside Jakob Nielsen's [10 general principles for interaction design](https://www.nngroup.com/articles/ten-usability-heuristics/).
 
-## Seven Usability Heuristics for Web3
+## Seven usability heuristics for web3 {#seven-usability-heuristics-for-web3}
 
 1. Feedback follows action
 2. Security and trust
@@ -20,9 +20,9 @@ These heuristics are specifically tailored for Web3 and should be used alongside
 7. Control from the app, not the wallet
 
 
-## Definitions and Examples
+## Definitions and examples {#definitions-and-examples}
 
-### 1. Feedback Follows Action
+### 1. Feedback follows action {#feedback-follows-action}
 
 **It should be obvious when something has happened, or is happening.**
 
@@ -39,10 +39,10 @@ Showing each step involved in a transaction helps users know where they are in t
 
 ![Informing the user about each step when swapping tokens](./Image1.png)
 
-### 2. Security and Trust are Baked in
+### 2. Security and trust are baked in {#security-and-trust-are-backed-in}
 
-Security should be prioritised, and this should be emphasised for the user. 
-People care deeply about their data. Safety is often a primary concern for users, so it should be considered at all levels of the design. You should always be seeking to earn the trust of your users, but the way you do this can mean different things on different apps. It should not be an afterthought, but should be designed consciously throughout. Build trust throughout the user experience, including social channels and documentation, as well as the final UI. Things like the level of decentralisation, the treasury multi-sig status, and whether the team is doxxed, all affect users' trust
+Security should be prioritized, and this should be emphasized for the user. 
+People care deeply about their data. Safety is often a primary concern for users, so it should be considered at all levels of the design. You should always be seeking to earn the trust of your users, but the way you do this can mean different things on different apps. It should not be an afterthought, but should be designed consciously throughout. Build trust throughout the user experience, including social channels and documentation, as well as the final UI. Things like the level of decentralization, the treasury multi-sig status, and whether the team is doxxed, all affect users' trust
 
 **Tips:**
 - List your audits proudly
@@ -57,24 +57,24 @@ Include your audits in the footer, at a prominent size.
 
 ![Audits refernced in the website footer](./Image2.png)
 
-### 3. The Most Important Info is Obvious
+### 3. The most important info is obvious {#the-most-important-info-is-obvious}
 
-For complex systems, show only the most relevant data. Determine what is most important, and prioritise its display. 
+For complex systems, show only the most relevant data. Determine what is most important, and prioritize its display. 
 Too much information is overwhelming and users typically anchor on one piece of information when making decisions. In DeFi, this will probably be APR on yield apps and LTV on lending apps.
 
 **Tips:**
 - User research will uncover the most important metric
 - Make the key info big, and the other details small and unobtrusive
 - People don’t read, they scan; ensure your design is scannable
 
-**Example:** Large tokens in full colour are easy to find when scanning. The APR is big and highlighted in an accent colour.
+**Example:** Large tokens in full color are easy to find when scanning. The APR is big and highlighted in an accent color.
 
 ![The token and APR are easy to find](./Image3.png)
 
-### 4. Clear Terminology
+### 4. Clear terminology {#clear-terminology}
 
 Terminology should be understandable and appropriate.
-Technical jargon can be a huge blocker, because it requires the construction of a completely new mental model. Users are unable to relate the design to words, phrases and concepts they already know. Everything seems confusing and unfamiliar, and there is a steep learning curve before they can even attempt to use it. A users might approach DeFi wanting to save some money, and what they find is: Mining, farming, staking, emissions, bribes, vaults, lockers, veTokens, vesting, epochs, decentralised algorithms, protocol-owned liquidity…
+Technical jargon can be a huge blocker, because it requires the construction of a completely new mental model. Users are unable to relate the design to words, phrases and concepts they already know. Everything seems confusing and unfamiliar, and there is a steep learning curve before they can even attempt to use it. A users might approach DeFi wanting to save some money, and what they find is: Mining, farming, staking, emissions, bribes, vaults, lockers, veTokens, vesting, epochs, decentralized algorithms, protocol-owned liquidity…
 Try to use simple terms that will be understood by the broadest group of people. Do not invent brand new terms just for your project.
 
 **Tips:**
@@ -89,22 +89,20 @@ Try to use simple terms that will be understood by the broadest group of people.
 
 ![Token rewards, displayed in U.S. dollars](./Image4.png)
 
-### 5. Actions are as Short as Possible
+### 5. Actions are as short as possible {#actions-are-as-short-as-possible}
 
 Speed up the user’s interactions by grouping sub actions. 
 This may be done on the smart contract level, as well as the UI. The user should not have to move from one part of the system to another – or leave the system entirely – to complete a common action. 
 
 **Tips:**
-- Incorporate zappers for adding liquidity
-- Combine “Approve” with the “Deposit” action
-- Combine “Deposit” and “Stake” actions
-- Allow the user to close a loan position and withdraw collateral entirely
+- Combine "Approve" with other actions where possible
+- Bundle signing steps as close together as possible
 
 **Example:** Combining “add liquidity” and “stake” is a simple example of an accelerator that saves a user both time and gas.
 
 ![Modal showing a switch to combine the deposit and stake actions](./Image5.png)
 
-### 6. Network Connections are Visible and Flexible
+### 6. Network connections are visible and flexible {#network-connections-are-visible-and-flexible}
 
 Inform the user about what network they are connected to, and provide clear shortcuts to change network. 
 This is especially important on multichain apps. The main functions of the app should still be visible while disconnected or connected to a non-supported network.
@@ -120,7 +118,7 @@ This is especially important on multichain apps. The main functions of the app s
 
 ![Dropdown button showing the connected network](./Image6.png)
 
-### 7. Control from the App, not the Wallet
+### 7. Control from the app, not the wallet {#control-from-the-app-not-the-wallet}
 
 The UI should tell the user everything they need to know and give them control over everything they need to do. 
 In Web3, there are actions you take in the UI, and actions you take in the wallet. Generally, you initiate an action in the UI, and then confirm it in the wallet. Users can feel uncomfortable if these two strands are not integrated carefully.
@@ -133,4 +131,4 @@ In Web3, there are actions you take in the UI, and actions you take in the walle
 
 **Example:** A subtle container shows the user what relevant tokens they have in their wallet, and the main CTA provides a shortcut to change the network.
 
-![Main CTA is promptinng the user to switch network](./Image7.png)
+![Main CTA is prompting the user to switch network](./Image7.png)

src/data/placeholders/content-developers-docs-design-and-ux-heuristics-for-web3-data.json

@@ -0,0 +1,30 @@
+{
+  "/content/developers/docs/design-and-ux/heuristics-for-web3/Image1.png": {
+    "hash": "55375e45",
+    "base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAMCAYAAABr5z2BAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAyklEQVR4nK1SsQ2DQAx8iQ3ov0bQJPlUKdiCARiAAWgpfgEWYAEWQBRJKiZgAga56Kw8IpFDEyydbNnvO+ttkyQJ/oE5nMBau4tdgqIoUNe1wHuPtm3FEyHPNyqBtRZd14E2TZPEoZlE8zxLrWmaj0mMRjAMA/I8R1mWqKpKlJmj8c0uQd/3osiGrTJtfIy43K7I0kwn8O+RqRqUl2VZCe7PB07ujCxN9U+M4xhRFMEYI2DMXECo/dwCp9g2aPhepXpIzrnVazj0El+ZhVZirq6olgAAAABJRU5ErkJggg=="
+  },
+  "/content/developers/docs/design-and-ux/heuristics-for-web3/Image2.png": {
+    "hash": "01ef6abc",
+    "base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAMCAYAAABr5z2BAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAfElEQVR4nO3QMQpDIQwG4IAXcHLwCOLk5CBOIt7/GiKCmwj+xQwPSmkpvK10+Ej4EzKE5py4g/4H8As/WGvhW3vvl4xaa+i9s9N/UmvlOsa4Mso5I6XESilvWWvhnOPee3/t0xkopdhZiDEihPDkZFJKEBG01lyFEDDG4AEPnqP0wGBwIQAAAABJRU5ErkJggg=="
+  },
+  "/content/developers/docs/design-and-ux/heuristics-for-web3/Image3.png": {
+    "hash": "d138e577",
+    "base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAMCAYAAABr5z2BAAAACXBIWXMAAAsTAAALEwEAmpwYAAABBUlEQVR4nLWSMUvDQBSAb/Mf+Gv8A+7uUh0c1CFDoEGaQt0C2iVDxoCdAqWT4BAkQkUpbZcribSXJlmyZNT9k14pUqwKVYePe+/u+Hjv3YkkSfgN4k8FUk40WwvyfE6eZyilPl2cvkyZp6lmo0CpGd3eHd3eLYPBM1JKzfJMMRwNue8/0H961LI1gZQT3l4rxM4eQuzSbJh6r6oqsjwjnSmsqyb7pwccWidrVYiPChRn5wZ164LxeITneRiGQRiGBEFA7fiIm06HKIqI43jzDNrta2y7geu6WmCaJo7j4Ps+tm1z2Wrp+MshlmWpKYpCr4sWVvkqXrT0zTMuB/cT//eRthG8AwK9igcsxSbkAAAAAElFTkSuQmCC"
+  },
+  "/content/developers/docs/design-and-ux/heuristics-for-web3/Image4.png": {
+    "hash": "a31435f1",
+    "base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAMCAYAAABr5z2BAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAk0lEQVR4nGM4d+7cf0owA1UNOHr0KGUG3Ll75//9+/f/X7l6hTQDrly98n/dqjX/y4vK/udkZP0/d/r0/+vXrxNnwOnTp/8/e/Lsv2uw538GBob/rBLc//UdzP6DxIk24OWzF/+tfRzBBjBIsv2X1JYnOjwYYIy9u/b8nz119v+VS1aAvUNyIF65egUFD0w6GBADAFHYe2AWjEaDAAAAAElFTkSuQmCC"
+  },
+  "/content/developers/docs/design-and-ux/heuristics-for-web3/Image5.png": {
+    "hash": "7319d43a",
+    "base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAMCAYAAABr5z2BAAAACXBIWXMAAAsTAAALEwEAmpwYAAABIUlEQVR4nK2SUUrDQBRF59cV6FJcQwXrCkTwV7CtLsYFCKLVuop++anVSTKNheQ5SZoO00hTsKS3zNQWg6k/duAyzH3vHt7AY67r4j9iWwVwzivlug6E8MC58/3eAAiCAEmS/FJIEUR/AKIQRLQZIKWE1hqrUxRzez+/Jbh97CKSBKW0nagSEMeRheR5jtnsywqYI8vGSNMhKNYgOYTwvGqAUgpjrTFKU3zICCOlUBTFepKnFwl/EMPvizKg98ox0YSDRgeMnYDtnIHtXSy121rexmPHqDU6ttdk1gDOHUT0jqubLvZPr1E7v0P98gFHrXscNtuoN9vWMzXTY3pNpvQFY1DgY5oRJjrEpwpKMp6pmZ5VuGIPHDvaX/oZ3somLgAMnZccaZ58ywAAAABJRU5ErkJggg=="
+  },
+  "/content/developers/docs/design-and-ux/heuristics-for-web3/Image6.png": {
+    "hash": "d858f18e",
+    "base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAMCAYAAABr5z2BAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAcUlEQVR4nGP4TwAwMDCAsbau7v+pU6eC2QEBAf8tLCz+b9q06T9Dc3Pzf3xYXkjkv6629n8HB4f/mZmZ/w0MDMAGeHh4/C8qKvrPEBER8R8fLiwp+Z9fkA/WDOKDaBhOSEj4zwAiKMEMowb8Hw2DhP8AmHCj3m1Q35sAAAAASUVORK5CYII="
+  },
+  "/content/developers/docs/design-and-ux/heuristics-for-web3/Image7.png": {
+    "hash": "c87680a1",
+    "base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAMCAYAAABr5z2BAAAACXBIWXMAAAsTAAALEwEAmpwYAAABzUlEQVR4nH2RzW/TQBDF94TEAQnxx6HeuJWPf4BrlCtXLiiHKqK0UqhLQXVyaCQqNwYFS5bjJk4aI6XaRm6Ds3WdGNfFCQ/NhJSKr5GetOPV/t68sWi321jK87xrjUYjxHGMJEn+qSAIIN7vH2B9fQOGYcA0TWiaBsdxUK/XUSgUUCwWMRwOQfUdv+pYSgwGxxDmgYlqtcqulmVB13U0m01EUcQOpCzLMJ/PWTcrDEMIY+8dqrsaOl6XnQlAIIpAPbkTYJbnuMwyuH0JKSVHYMCzF2U8L63h0G3B87qo1Wo8gVKKIxEkjifsmH2bofzWwK6uQ8ohTs/OIDYr29h6rfESe70e74IAywXmec6jR9EF0vQSSTLleJPkagHodDw4Tuv6L5Cj67o8HsVI0/Rn3jEDb5ZSYwjf78P3fXYnLc8EsG2b4XReRLiCbpkwGg0GkoFYPvxdRHccG5/9Ix6bKp/N8KHf4u8ncvAfQLeLsYoQqinOoxQq+orgS4yRmmA6yXAep3wXBKd/Ag7bHi5CiftPdyDECsTdxxC3ViHuPYG4/RDizqNFLx6gVPn09wl8/wj7poPSpoGNnY8obzXw6o2Jl9sLUb9WMWHZLn4ALXmazS7QbyEAAAAASUVORK5CYII="
+  }
+}

src/intl/en/page-developers-docs.json

@@ -30,6 +30,7 @@
   "docs-nav-development-frameworks-description": "Tools that make developing with Ethereum easier",
   "docs-nav-development-networks": "Development networks",
   "docs-nav-development-networks-description": "Local blockchain environments used to test dapps before deployment",
+  "docs-nav-dex-design-best-practice": "Decentralized Exchange (DEX) design best practices",
   "docs-nav-dot-net": ".NET",
   "docs-nav-erc-20": "ERC-20: Fungible Tokens",
   "docs-nav-erc-721": "ERC-721: NFTs",
@@ -45,6 +46,7 @@
   "docs-nav-gas": "Gas",
   "docs-nav-gas-description": "Computational power required to process transactions, paid for in ETH by transaction senders",
   "docs-nav-golang": "Golang",
+  "docs-nav-heuristics-for-web3": "Heuristics for Web3",
   "docs-nav-integrated-development-environments-ides": "Integrated Development Environments (IDEs)",
   "docs-nav-integrated-development-environments-ides-description": "The best environments to write dapp code",
   "docs-nav-intro-to-dapps": "Intro to dapps",