Add language to Units & Symbols page describing new ₿-only convention for displaying bitcoin quantities #1171
Conversation
✅ Deploy Preview for bitcoin-design-site ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
There was a problem hiding this comment.
Pull Request Overview
This PR introduces a new section to the Units & Symbols page to describe an emerging ₿-only convention for representing bitcoin quantities.
- Added a new image set (images_b) to support the visual mockup.
- Inserted a detailed section including motivation, best practices, examples, a sample mockup, and early adoption details.
GBKS
added
the
Design bitcoin products
There was a problem hiding this comment.
Thanks for creating this PR. I like the addition overall, but I think we need to clarify the framing. The title and first sentence read a bit promotional. And as I mention in one of the comments, the "inspired by" and "emerging among a small handful of forward-looking wallets" are a bit vague. As a reader, I can't tell if it this is about BIP 177 or some interpretation of it, and emerging sounds like the details are not well-defined yet.
Hope the feedback is helpful.
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
|
Independent of the content, can you please remove the Gemfile changes from this PR? It is breaking the build system, and updates to those dependencies should be done separately from any content changes, since they require everyone who runs things locally to update their dev environment accordingly. |
|
ok i have attempted to revert those 2 gemfiles. please let me know if that looks good? |
|
@GBKS I have tried to address all of your points of feedback on the PR. I believe the current state strikes a good balance of presenting the rationale for this new/emerging convention and guiding the ₿-curious on how to adopt it. Let me know if you have any further feedback? |
There was a problem hiding this comment.
Thanks for tackling this deceptive and tricky topic, and opening the PR so quickly.
That said, a few things tripped me up, so have dropped comments. Forgive me & ignore comments if I completely missed the boat on something fundamental. It all starts with the naming of the format... I suggest calling it "base unit format" as it is simple yet gets to the heart of the matter.
|
Thank you for your review and suggestions @yashrajd Your feedback was valuable! I have adopted a handful of suggestions you made that I think make the content clearer and more helpful, updated with a couple of commits. Thank you. In cases where I didn't agree with your suggestions, I have provided rationale and resolved the comments. If you feel strongly that I am off the mark, please feel free to re-open and we can solicit opinions from others and/or discuss further. |
|
Are you happy with the latest changes @GBKS? Can this be merged now? |
|
I don’t think the design guide needs to provide guidance on use of spoken
language.
People can/should speak it the way they want. Bitcoin naturally for some,
or bits for others (slang) or “sats” for the OGs. This design guide is not
going to change how people speak, but it might influence how people build
product UIs.
…On Mon, Jun 16, 2025 at 3:53 PM ***@***.*** ***@***.***> wrote:
***@***.**** commented on this pull request.
------------------------------
In guide/designing-products/units-and-symbols.md
<#1171 (comment)>:
> @@ -245,6 +252,53 @@ Typically, the word "bitcoin" can mean a singular or a plural. In the early days
Whatever pluralization scheme you choose, it's good to be consistent with this choice throughout your product.
+## New convention: ₿-only format
Fair enough. I do think we should provide explicit guidance that ₿ should
be pronounced "bitcoin". It seems obvious, but might not be. I find folks &
myself using it as a "B".
—
Reply to this email directly, view it on GitHub
<#1171 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AORAHDZBWUABNZJJTTC453T3D5DHDAVCNFSM6AAAAAB6SEXP5OVHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHMZDSMZTG4YTINZTGY>
.
You are receiving this because you authored the thread.Message ID:
***@***.***>
|
|
I don’t see that recommendation as a critical part of the design guidance
for implementing ₿-format.
If you’re an existing wallet with options already, then yes obviously you
will provide legacy options alongside that in your options UI, I don’t
think the Design Guide needs to speak to it.
If you’re a new wallet adopting this convention out of the gates, I think
it is a very reasonable product decision to not provide that unit format
optionality.
…On Mon, Jun 16, 2025 at 4:10 PM ***@***.*** ***@***.***> wrote:
***@***.**** commented on this pull request.
------------------------------
In guide/designing-products/units-and-symbols.md
<#1171 (comment)>:
> +2. **Meaning of "sats".** "The word "satoshis" or "sats" appearing in product UIs, often alongside BTC or bitcoin, raises the question for new users: what are these units and how do they relate to bitcoin? It presents an eduation/understanding hurdle that can be avoided.
+3. **Inconsistency.** The current dual convention that is typically employed by wallets sometimes shows quantities in decimal representation (typically if larger) and other times integer quantities (typically if smaller). This inconsistency creates unpredictability in the product experience.
+
+The BEFORE & AFTER [sample mockups](#sample-mockup) below demonstrate how these points of potential confusion are manifest in traditional wallet UIs and might be remedied under this new ₿-only format.
+
+### Proposed best practices
+
+The following best practices are proposed for products wanting to adopt the ₿-only format:
+
+- Show quantities only in integers form, representing the number of base units of bitcoin
+- Label quantities with ₿ symbol (either pre-fix or post-fix per local custom)
+- Include a fiat value below the bitcoin quantity for maximum clarity
+- Use 'BTC' to refer to 100M base units (i.e. 1BTC = ₿100,000,000)
+- Deprecate use of decimal representation
+- Deprecate explicit use of "satoshis" or "sats" in product UIs
+
I don't think that it's a good practice to allow users to choose. I think
it's unnecessary mental load. There's already enough complexity in bitcoin
wallets. Off loading this decision to the user doesn't sit right with me.
Just my opinion though, I can see the other side.
It sounds crazy to me to not recommend providing users an option to change
unit. Many popular bitcoin wallets (including bitkey) already allow
changing bitcoin unit. The very page this PR updates recommends this
<https://bitcoin.design/guide/designing-products/units-and-symbols/#setting-the-preferred-unit>
.
—
Reply to this email directly, view it on GitHub
<#1171 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AORAHD5ZO6OI7Y3BI6YYAXT3D5FHPAVCNFSM6AAAAAB6SEXP5OVHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHMZDSMZTG4ZTSOJQGM>
.
You are receiving this because you authored the thread.Message ID:
***@***.***>
|
Per @GBKS suggestion, I went with an approach that adds a section to the Units & Symbols page, rather than create an entirely new page.
However, the existing Units & Symbols page leans heavily on existing conventions, so it did not seem natural to inject this alternative convention in the middle of the content. So I opted to introduce a new section at the end of the page that describes this new, emergent convention as being adopted by a small handful of wallets. I describe some of the rationale for the change, provide examples, and a mockup to illustrate what this would look like.
Because this is not a "consensus view" of the design guide, I did not try to represent it as such. Instead I tried to make this informational, and explain that some wallets are starting to adopt this convention. Having this content here in the Design Guide could be helpful for other wallets who might be considering adopting this approach as well.
This is my first PR on the Design Guide so please let me know if I've missed anything.
Closes #1168