Alternative Text for CSS-Generated Content

Matheus Richard learned that the CSS content property accepts alternative text for screen readers, separated by a /:

.warning::before {
  content: "⚠️" / "Warning";
}

Without the alt text, assistive technology either reads out the emoji name or skips it entirely. More details in Stefan Judis’ article.

A Faster UI for Large GitHub Diffs

Matheus Richard shares diffshub, a tool that renders PR diffs GitHub struggles with. It’s a drop-in replacement: swap github.com for diffshub.com in any PR URL, like https://diffshub.com/oven-sh/bun/pull/30412.

Aube, a New JavaScript Package Manager

Jared Turner shares Aube, a JavaScript package manager from the creator of Mise. It’s pitched as fast, compatible with existing lockfiles, and security-focused, including a 24-hour cooldown before newly published versions can be installed.

Thanks

This edition was brought to you by Jared Turner and Matheus Richard. Thanks to all contributors! 🎉

Data attributes should be lowercase

data-dialogOpen is invalid - it should be data-dialogopen. But did you know that all HTML attribute names get automatically lowercased? I didn’t.

HTTP headers are also case-insensitive except in HTTP2 where they MUST be lowercase.

Invalid id attributes

I learned that in HTML5, an id can be anything as long as it’s 1 character with no whitespace (and it’s unique). id="_0$!11" is totally valid and I think even emojis are ok!.

However, in HTML4 ,ids need to start with a letter and can only contain letters, numbers, and a few punctuation symbols. So it’s probably best not to go too wild. Backwards compatibility is nice.

Oh, and the uniqueness requirement? ids inside iFrames only need to be unique within their document. Otherwise, imagine how tricky it would be to iFrame in an arbitrary page.

Redundant for attributes

A bit of a nitpick: when you label an input by putting it inside a label, the for attribute is redundant. When the input is outside the label, you definitely need that for!

<!-- Rails-style: no `for=""` needed -->
<label>
  Username <input type="text" name="username" />
</label>

<!-- non-Rails-style: don't forget the `for=""`! -->
<label for="username>Username</label>
<input type="text" name="username" id="username" />

Some reasons that thoughtbot prefers inputs inside labels:

• it reduces the need for an extra wrapper div
• since the label is clickable, this often results in a bigger click/tap area
• you don’t need to generate unique IDs for inputs

Extra whitespace in a textarea

Claude spotted this one: I accidentally had a blank space inside a textarea.

<textarea name="explain"> </textarea>

An easy mistake to make and kind of annoying to an end user, especially because it will cause the required validation to be skipped. I wish one of my automated scanners had caught it.

False positive: aria-label misuse

HTML-validate told me that using the aria-label attribute on <search> is invalid. Nope - I was using it correctly!

W3c explicitly recommends it:

If a page includes more than one search landmark, each should have a unique label.

<search aria-label="Site-wide">
  <form>
    ...
  </form>
</search>

I filed a bug report.

iFrames with unique names

I had trouble with this one, but I’m glad Axe caught it because it’s genuinely useful for screen reader users.

Every iFrame needs a title, and those titles should be unique so they can be differentiated. But also, landmarks INSIDE the iFrames must be unique across the entire page, including the parent document.

I had 3 iFrames on a page, all with <main aria-label="Component Example">. Sure enough, when I opened Voiceover it read out 3 of the same landmark:

• Component Example main
• Component Example main
• Component Example main

That’s not a great experience.

First, I tried to fix it by removing the aria-labels, but Axe warns me that the document has multiple <main>s without unique labels. I had to refactor how the iFrames were generated so that each one had both a unique title and <main> label.

Color contrast issues

Automated scanners are the best at finding contrast issues. I happened to have a link state that used a slightly-too-light purple on white. It didn’t pass WCAG’s minimum contrast levels. Easy for me to miss, but troublesome for someone with reduced vision.

Keyboard-accessible overflow scrolling

This was a new one for me! Axe tells me that when a region scrolls using overflow: scroll or similar, it must contain a focusable element. This seems to be a Safari-specific bug.

I tested with Safari and confirmed that it’s true: using the keyboard I was unable to scroll down to see the cut-off content.

The simplest solution is to add tabindex="0" to an element inside the scrolling region.

Forgotten SVGs

I’m constantly forgetting to check that SVGs have the right label and role. With images it’s easy: just make sure you’ve got an alt tag. But inline SVGs can either be decorative or presentational.

Decorative SVGs must use aria-hidden="true" to keep them out of the accessibility tree.

Presentational ones must use role="image and NEED a <title> tag to serve the same function as alt text. And since not all screen readers catch the <title> tag, you usually want to associate it with the <svg> tag using aria-labelledby. And if the SVG contains multiple images, text blocks, or interactivity, there’s even more to consider.

I dug into the WAI-ARIA rabbit hole and learned that maybe some of my SVGs could be role="graphics-symbol"

A graphical object used to convey a simple meaning or category, where the meaning is more important than the particular visual appearance.

Axe missed all this, but Claude caught it. I wonder if there’s an automated scanner that could help me out.

Explain your asterisks

If you’re going to denote require inputs using an asterisk * in the label, you’d better provide a legend that explains it. Even better, replace asterisk with (required).

Oops, thanks for the reminder, Claude. I added an explainer to the form:

<small>* asterisks denote required fields</small>

Punctuation as labels

I built a pagination component that looked like this:

< 1 … 45 46 47 … 104 >

Claude reminded me that when a screen reader reads out those angle brackets and ellipses, it’s going to sound weird. I opened Voiceover and sure enough - it sounds weird.

I followed Pagy’s example: the ellipses get role="separator" and the buttons get aria-label="Next"/aria-label="Previous".

Table header cell scopes

A blind spot for me: I didn’t know about the scope attribute. WCAG recommends using scope="col" on table header <th> cells to associate them with their column. And also using <th scope="row"> for table body cells that identify the subject of the row.

Probably more useful for complex tables than simple ones. I’ll have to remember this.

Thank goodness for automated scanners and the people who maintain them[^2]! The stuff I build is better for it. I was impressed by the bugs Claude caught, even though it surely wasn’t comparable to an accessibility audit by a real person.

[^1] My prompt: “You are an accessibility expert. Please review all the pages on this site and create a table of accessibility and WCAG violations”

[^2] By the way: thoughtbot maintains CapybaraAccessibilityAudit which uses Axe under the hood!

Since Duck Typer launched, there’s been some discussion about the validity of interface testing. In this post, I want to make the case for it.

“Interface tests are fragile, so you shouldn’t write them”

That’s not true without context. How is your test suite structured? What do you test? Obviously, if you write only interface tests like this:

def test_interfaces_match
  assert_interfaces_match [StripeProcessor, PaypalProcessor]
end

With no behavior tests to accompany it, that quote will be true. Why? Because you’re not testing actual code behavior. Alone, Duck Typer tests are fragile. So why should you still write them?

“But I already have behavior tests that catch mismatches”

You do, and they will catch mismatches eventually, assuming you have good test coverage. The problem is how they catch them. A behavior test will blow up with a NoMethodError or an ArgumentError, but nothing about that tells you it’s an interface problem across a group of classes. You have to figure that out yourself, then work backwards to find which class drifted and what changed.

Duck Typer short-circuits that investigation. It tells you what drifted and where, in a single message, before you ever hit a behavioral failure:

Expected StripeProcessor and PaypalProcessor to implement compatible
interfaces, but the following method signatures differ:

StripeProcessor: refund(transaction_id)
PaypalProcessor: refund not defined

There’s also a sharper version of this objection: “You can remove the implementation and the test still passes, so it’s not a good test.” That’s true, and it’s by design. Duck Typer checks shape, not behavior. It explicitly marks that a set of classes is expected to evolve together, and when one changes, the failure makes it clear. That’s a different job than verifying correctness, and both are worth doing.

It’s about quality of life

At thoughtbot, we always valued testing UX and clear error reporting. We care about the details. For example, this is a style of test generally not encouraged here:

expect(objects).to eq([post_1, post_2, post_3])

Assume that the post objects are complex Active Record instances. Can you imagine what the error message will look like if one object has differences? It will dump a huge blob of text that incurs overhead to parse. What are we really testing there? That we’re getting the right objects! Instead, we can use named identifiers to make error reporting more actionable and crystal clear:

expect(objects.map(&:title)).to eq(["Post 1", "Post 2", "Post 3"])

Duck Typer applies the same principle to interface errors. Without it, you only get generic Ruby errors that say nothing about interface drift across classes. With Duck Typer, you also get a clear, targeted failure:

Expected StripeProcessor and BraintreeProcessor to implement compatible
interfaces, but the following method signatures differ:

StripeProcessor: charge(amount, currency:)
BraintreeProcessor: charge(amount, currency:, description:)

StripeProcessor: refund(transaction_id)
BraintreeProcessor: refund(transaction_id, amount)

It communicates design intent as actionable errors

I wish Ruby had interfaces. As I said in the introductory post, I want to be alerted of interface drift because it’s a great developer experience feature.

It’s not always obvious when classes are supposed to be used interchangeably. A clear error message communicates which classes share a role and what shape their interfaces should have.

What if you join a legacy project where the original developers left a long time ago? Duck Typer would be super helpful there too.

A concrete example: Null Objects. You add a deactivate method to User, and your behavior tests for User pass. But NullUser, which is supposed to be interchangeable with User, silently drifts because nobody remembered to update it. Behavior tests on User won’t catch that. Duck Typer will, immediately, because it treats those classes as a group that must stay in sync. It also reminds you to write the actual behavior test for NullUser#deactivate.

As a developer who loves targeted feedback, that is right up my alley.

It helps you think about design

Let’s say that introducing a do_stuff public method in StripeProcessor is the easiest way to accomplish a goal. You add it, but get a test failure like the following:

Expected StripeProcessor and PaypalProcessor to implement compatible
interfaces, but the following method signatures differ:

StripeProcessor: do_stuff(data)
PaypalProcessor: do_stuff not defined

That message doesn’t just report interface drift. It actually asks:

Why are you doing that? A public method in StripeProcessor should also exist in the other processors.

Most likely, your do_stuff method is not in the right place. Maybe it belongs in a collaborator object, or maybe it should be a private method that isn’t part of the public interface at all.

The same applies to differing method parameters; if you introduce a parameter in one class but it is not needed in another class from the same interface, you are probably doing something wrong.

“But that’s just like shoulda-matchers”

Not quite. Shoulda Matchers are great for shortening TDD feedback loops when working with Rails conventions. They verify a single object’s declarations: does this model have_many :posts? Does it validate_presence_of :email? That’s inward-facing: one object, one declaration.

In fact, once the code has enough behavior coverage, you could delete the shoulda-matchers tests entirely. They’ve done their job.

Duck Typer is cross-cutting. It checks whether a group of objects agrees on a shared interface. The question isn’t “does StripeProcessor have a charge method?” but “do StripeProcessor, PaypalProcessor, and BraintreeProcessor all define charge with the same signature?” That’s a fundamentally different concern, and one that single-object matchers can’t express.

“But it doesn’t catch errors in production”

Some prefer an approach where the interface is validated at class load time: declare the contract, and if a class doesn’t conform, raise a RuntimeError immediately. That way, mismatches surface as errors in production rather than only in tests.

That’s a valid approach, although not exactly great. In a typed language, an interface mismatch would never be deployed because the code wouldn’t compile. Ruby doesn’t have a compiler, but it has its own equivalent: the test suite. And guess what inhibits bad deployments in Ruby projects? In all my years working with Ruby, I’ve never seen a project without a CI pipeline. If tests fail, your code doesn’t get deployed. In practice, the safety net is the same.

On top of that, runtime checks add metaprogramming to your production code, and you’d still need tests to verify the setup is correct.

That’s why Duck Typer deliberately stays in the test suite: it’s Ruby’s natural place to enforce constraints like this, and your implementation stays clean, without workarounds that try to mimic static typing at runtime.

If you want compile-time or runtime guarantees, tools like Sorbet or RBS take a fundamentally different approach to the same problem and you wouldn’t need Duck Typer. That said, Duck Typer gives you some of those benefits with a fraction of the effort, at least when it comes to interfaces.

Wrapping up

Duck Typer won’t replace your behavior tests, and it was never meant to. It’s a small, focused tool that gives you targeted feedback when interfaces drift. It’s usually a one-liner to add, has no runtime dependencies, and lives only in your test environment. If you value clear error messages and care about keeping polymorphic classes in sync, give it a try.

In this blog post, I’m going to share three approaches that we evaluated for a recent project. All three approaches can enable a smooth authentication experience, but they come with different tradeoffs in terms of implementation complexity, user experience, and security implications. If you are building this feature for a banking/financial services app, a healthcare app, or a product handling sensitive user data, these tradeoffs matter a lot. In this post, for each approach of biometrics authentication, we’ll explore how they work, where they fall short, and when each makes sense.

Simple Prompt (Approach 1)

The simplest way to add biometrics to your app is to use it as a UI level gate:

• Prompt the user to authenticate with their biometrics (face or fingerprint).
• On success, read the auth token from secure storage

This is what simplePrompt in react-native-biometrics does. It triggers the native biometric dialog and returns a boolean indicating success or failure. The critical thing to understand about this approach is that the biometric check and the token retrieval are two separate, unlinked operations. The app calls simplePrompt, gets back true, then independently reads the token from storage. There is no cryptographic connection between them and the biometric result is merely a signal to our code, not a hardware enforced gate on the data itself.

// Pseudocode showing how this works
const success = await biometrics.prompt('Confirm your identity')

if (success) {
  const token = await secureStorage.read('auth_token')
  // log user in
}

Expo vs React Native CLI (Approach 1)

With Expo managed workflow, you’d reach for expo-local-authentication rather than react-native-biometrics. The API is nearly identical, returns a result object with a success boolean, and it works without ejecting or adding any native configuration. To store and retrieve the auth token securely, pair it with expo-secure-store, which writes to the iOS Keychain and Android Keystore under the hood.

With React Native CLI (bare workflow), react-native-biometrics is the natural choice for the biometric prompt. For token storage, the equivalent is react-native-keychain, which gives you direct access to the iOS Keychain and Android Keystore and supports more granular security configuration than expo-secure-store.

Pros (Approach 1)

• Easy to implement with minimal boilerplate and works out of the box on both platforms
• Supports Face ID, Touch ID, and fingerprint without extra configuration
• Works across iOS and Android with a consistent API
• No backend required
• Multi device support as each device independently manages its own stored token

Cons (Approach 1)

• Biometric enforcement happens at the App level, not the OS or hardware level. The biometric check and the token read are two independent steps with no cryptographic coupling between them
• On a jailbroken or rooted device, tools like Frida can be used to hook into the app at runtime, force simplePrompt to return true, and retrieve the token without the user actually authenticating
• Does not meet FIDO2 or WebAuthn standards as there is no challenge-response, no server side verification, and no cryptographic proof that a real biometric event occurred on the device
• The stored token is not hardware locked. Code that bypasses the biometric gate can read it directly from storage
• Not appropriate for apps handling sensitive financial, healthcare, or regulated data

Cryptographic Key Pair (Approach 2)

This approach upgrades biometrics from a UI gate to something the server can independently verify. The createKeys() method in react-native-biometrics generates an asymmetric key pair. The device holds a private key locked behind biometrics and the server holds the matching public key. Login is just the device signing a challenge and the server verifying the signature.

What makes each piece do its job:

• Private key — Created inside the device chip at enrollment and never exported. It is only unlocked by a passing biometric scan.
• Public key — Returned to the app and registered on the server. It is used only to verify signatures.
• Challenge — A one-time UUID issued by the server at login. The server enforces an expires_at field so late or replayed submissions are rejected.
• Signature — The chip’s signed challenge sent to the server. The server checks it against the stored public key and issues an access token.

The server never learned your biometric, your private key, or even your password. It just confirmed the right chip signed the right challenge at the right time.

Enrollment

The device generates a key pair inside the hardware chip. The private key never leaves. The public key gets sent to the server.

Private key example: Stays on device, locked by biometrics, never transmitted.

-----BEGIN RSA PRIVATE KEY-----
MIIEowIBAAKCAQEA2a2rwplBQLF29amygykEMmYz0+Ik9e8bKGFCNSGBaGMq
mMV5FBtLGMGMmFnMjQKFMkBHiNIEuAsYhVMqAC+XAAA...
-----END RSA PRIVATE KEY-----

Public key example: Sent to server at enrollment, stored against the user’s account.

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA2a2rwplBQLzamygyk
EMmYz0+Ik9e8bKGFCNSGBaGMqmMV5FBtLGJmFnMjQKF...
-----END PUBLIC KEY-----

Authentication

Step 1: User on the device says: “I want to log in.”

Step 2: Server generates a fresh challenge and sends it back:

{
  "challenge": "a3f8c2d1-9b4e-4f7a-8c3d-2e1f0a9b8c7d",
  "expires_at": "2026-05-01T10:00:30Z"
}

Just a random UUID. Expires in 30 seconds, useless after that.

Step 3: Device prompts Face ID / fingerprint.

Biometric passes → chip unlocks private key → signs the challenge:

{
  "challenge": "a3f8c2d1-9b4e-4f7a-8c3d-2e1f0a9b8c7d",
  "signature": "XrAGWHSPpnmqzQxL3kVt9Yw2NcBdEfUoRiMaTlKsPqJhGvCxZnWbOuIyDe..."
}

This is sent over the network. No password or token or private key. Just the challenge and its signature.

Step 4: Server verifies:

verify(
  publicKey  = <the one stored at enrollment>,
  challenge  = "a3f8c2d1-9b4e-4f7a-8c3d-2e1f0a9b8c7d",
  signature  = "XrAGWHSP..."
) → ✅ true

Server responds:

{
  "access_token": "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ1c2VyXzEyMyJ9...",
  "expires_in": 720 // 12 hours
}

Expo vs React Native CLI (Approach 2)

expo-local-authentication implements the simple prompt pattern from Approach 1 and exposes no key management APIs. There is no createKeys() or createSignature() equivalent in the Expo SDK, so you cannot implement the cryptographic flow with the standard managed workflow or Expo Go.

With React Native CLI, react-native-biometrics links natively on install and gives you direct access to createKeys(), createSignature(), and deleteKeys(). Your server needs three endpoints: one to store the public key at enrollment, one to issue a challenge, and one to verify the signature and return an access token.

Pros (Approach 2)

• The biometric check and authentication are cryptographically coupled: a valid signature can only be produced if the biometric passes, enforced by the hardware chip, not App code.
• Protects against replay attacks: every challenge is a one-time UUID with a short expiry window.
• Closest to FIDO2 of the three approaches with hardware backed keys, biometric gated signing, and server-side challenge-response compared to the other approaches.
• Resistant to runtime hooking tools like Frida as any spoofed signature here fails server-side verification because producing a valid signature requires the private key, which never leaves the hardware chip.

Cons (Approach 2)

• More complex to implement than Approach 1 as it requires backend work for key enrollment, challenge-response, and server-side verification.
• Multi device support is slightly complex as it requires the server to manage, store, and revoke a separate public key for every enrolled device per user.
• expo-local-authentication does not support this flow; Expo users need a bare React Native workflow, which adds build infrastructure overhead compared to the other two approaches.

Keychain (Approach 3)

This approach sits between the previous two. Like Approach 1, the auth token lives on the device. Like Approach 2, the biometric check is enforced by the OS at the hardware level, not by the React Native JS code.

When the token is written to the iOS Keychain or Android Keystore with a biometric access control flag, the OS will refuse to decrypt and return the value unless a successful biometric scan happens. The biometric prompt and the token decryption become a single OS-level operation. The App does not call a separate prompt API and then read the value, it just reads the value, and the OS shows the biometric prompt as part of completing that read.

// Pseudocode showing how this works
const token = await secureStorage.read('auth_token', {
  requireAuthentication: true,
})
// log user in

In practice, most apps store only a refresh token behind this gate and keep the access token in memory. The refresh token is long lived but never leaves the device, while the access token is short lived (~12 hours), lives in memory only, and is obtained by exchanging the refresh token at the start of each session. If an access token leaks, it expires quickly on its own. The refresh token, the more powerful credential, is hardware protected and never transmitted after the initial login.

Expo vs React Native CLI (Approach 3)

With Expo, expo-secure-store implements this pattern via requireAuthentication: true. The biometric prompt fires automatically on read, and SecureStore.canUseBiometricAuthentication() lets you check up front whether the device has biometrics enrolled before opting the user into biometric sign in. No native modules to install, and it works inside the managed workflow.

With React Native CLI, react-native-keychain gives the same OS enforced gate but with more granular controls. You pass accessControl: ACCESS_CONTROL.BIOMETRY_CURRENT_SET and securityLevel: SECURITY_LEVEL.SECURE_HARDWARE to setGenericPassword, which guarantees the key is stored securely.

Pros (Approach 3)

• Biometric enforcement happens at the OS/hardware level, not the App level. A patched App using tools like Frida that bypasses the biometric call still cannot read the token because the OS will not release the encryption key.
• No backend work required, unlike Approach 2. Only the token storage layer changes, the rest of the auth stack stays the same.
• Works inside the Expo managed workflow via expo-secure-store, so we don’t need a Bare workflow for this to be implemented.
• Multi device support is easy. Each device stores its own copy of the token encrypted securely.
• BIOMETRY_CURRENT_SET invalidates the stored token automatically when a new biometric is enrolled, which is a sensible default for apps handling sensitive data.

Cons (Approach 3)

• The token still lives on the device. If the access token is compromised through a network breach or server side leak, biometrics on the device cannot help. This can be mitigated by using a refresh token.
• Token expiry and rotation has to be handled in the App, typically by pairing this with a refresh token pattern explained above.
• There is no server side proof that biometrics were used. The server sees a normal token request and trusts the client. Approach 2 is the only one of the three that gives the server, cryptographic evidence of a real biometric event.
• Does not meet FIDO2 or WebAuthn standards as there is no challenge-response and no asymmetric key pair, just hardware backed symmetric storage.

Conclusion

If your app is relatively simple (a productivity tool, social app or utility), and biometrics is primarily a convenience feature for a fast login, Approach 1 is a reasonable choice. The implementation is straightforward and the tradeoffs are acceptable when there is no sensitive financial or personal data at stake.

If you are building a banking app, a financial services product, a healthcare app, or anything that handles regulated personal data, the bar is higher. Approach 1 is not appropriate here. Between Approaches 2 and 3, the deciding factor is usually team capability and backend access. Approach 3 requires no backend changes, making it the practical default for most teams. Approach 2 is the strongest option but requires a backend. If your team has the backend access and is comfortable with the added complexity, Approach 2 is the right call for maximum security for the mobile app.

In practice, most apps in sensitive industries start with Approach 3 and move toward Approach 2 if compliance requirements or a security audit demands server side verification.

What is this post about?:

In June 2025, Figma announced the beta release of their MCP server, a connection that lets AI coding tools read your Figma files directly. Claude Code, Anthropic’s agentic coding tool, was one of the first supported clients. Instead of describing a design to an AI in words, you give it a link to a Figma frame. It reads the components, the spacing, the design tokens, the structure, and builds the HTML and CSS from that.

That was interesting. But having tried it out previously, I found I’d often want to jump back into Figma to make changes to the Claude Code output. While it was possible to do this directly in the code, it wasn’t my strong suit and I found designing in Figma to be a lot faster.

Now Figma have gone one step further. You can now take a live, running interface built in Claude Code and send it back to Figma as editable layers. The workflow is no longer one-way. Design becomes code which becomes design again.

Who this workflow might suit:

Designers in thoughtbot are pretty unique in that for years, they have been writing and building prototypes in code. But for many designers who do not have a technical background, perfecting CSS, running commands in the terminal, opening PRs; these might all have seemed daunting.

If you’re an experienced technical designer, you probably won’t need this workflow. If you’re a designer who likes to design by prompt, directly in Claude Code, you also probably won’t need this workflow.

But if, like me, you are quite a visual designer who is not especially technical, these new advancements open up some exciting possibilities for shifting your designs to code and back, allowing you to make precise changes in a medium that you’re more comfortable with (Figma) and still ship some usable code.

Why I like it:

I like this workflow because I am not especially technical as a designer. I always found the terminal quite intimidating. This allows me to create prototypes in code.

However, I also like starting out in Figma because I don’t want Claude to do my thinking for me.

For example, let’s say I prompt Claude to create a website where users can search for properties in their area. Claude might create features that come as standard on many property sites, like searching for properties in a map view. Each pan/drag that changes the viewport means a new API call to fetch properties in that bounding box. But in my specific case, I may not want the expense of that API, especially at MVP stage. But if I prompt on autopilot, there is a risk that kind of feature would sneak in there without me actually spending the time considering it in detail.

So personally, I find that prompting from the get-go can introduce scope creep and lead to bloated projects.

I like to do the thinking behind the product myself (the really hard part of Product Design). This involves prioritisation, cutting scope, assessing technical feasibility and asking “should we build this?”. After this, I can use Figma and Claude Code as tools to help me with the execution (which is now a less hard part than previously).

What you need:

• A paid Figma account
• A paid Claude Code / Anthropic account.
• Node.js

How to set it up:

Step 1 - Install Claude Code

I promise this is not as scary as it sounds.

You open the Terminal on your Mac (Applications > Utilities > Terminal). Paste in the following command and hit enter:

npm install -g @anthropic-ai/claude-code

You’ll see some text scrolling; that’s normal. When it finishes and gives you a $ prompt back, try typing:

claude

Hit enter and you should be in.

Step 2 - Project Storage

Next, you need to create a folder for your project and then open Claude Code inside it.

Submit this into your terminal and hit enter:

mkdir ~/Desktop/my-projectcd ~/Desktop/my-projectclaude

Follow the first-time setup to log in. When you see a > prompt, you’re in!

Step 3 - Connect Figma

At the > prompt, paste in and hit enter on:

claude mcp add --transport http figma https://mcp.figma.com/mcp

Type claude to reopen, then /mcp, select Figma, and press Enter. It will open your browser to authorise the connection.

Set your standards

Before converting anything, create a CLAUDE.md file in your project folder. This is a plain text brief that Claude Code reads at the start of every session. It should contain what kind of code you want, naming conventions, how hover states should work, what a developer will need to wire up later and so on. If your company has specific development standards, this is the place to add them.

Getting this right once means every screen you build will follow the same rules.

Start building

Once you have designed a frame in Figma you can hit “Command + L” on Mac to copy a link to the frame.

Then you simply paste it directly into the next line of the terminal that is running Claude Code. You can add some additional instructions here too such as:

Build this design as clean, semantic HTML and CSS following the instructions in CLAUDE.md. Here's the frame: [your link]

It’s also a good idea to ask for a preview with a command like:

Start a local server so I can preview this in my browser

You can then see what Claude cooks up in your browser. And when you are ready to send it back to Figma, keep the browser preview open and go back to Terminal. At the Claude Code > prompt, type:

Send this to Figma

Claude Code is watching the browser preview it started, so you can tell it there what you want to capture. It will create a new frame in your Figma file with editable layers. From there, you can correct the issues you see, and then start the process again by sending your redesign back to Claude Code.

The GIF below shows a wonky mobile navigation Claude created being sent to Figma, and then the adjustments made to this directly in Figma iteself.

Conclusion:

And that’s it, that is the loop. It takes a session or two to feel natural. But after that, it becomes a fun new way of working.

In the next blog we will share how to correctly map your design tokens and components so that Claude uses them correctly when sending files over and back to take this workflow to the next level.