Thinkmill

What AI use looks like in five enterprise design teams

Mon, 07 Sep 2026 00:00:00 GMT

At Thinkmill, we’ve been helping design system teams adopt AI-assisted design and development. These days, a lot of that work centres around one key question: how do you set up an AI agent to produce something genuinely useful?

Most of what’s been written about AI focuses on shiny demos or big predictions. I wanted to know how teams are actually working today. I scoured the web and watched many hours of interviews with designers and engineers at Stripe, Shopify, Ramp, Atlassian and Intercom. Each participant walked through their design process now that AI is part of the mix.

I found that each team had invested in three key areas:

Somewhere to prototype
A way of providing AI with the right context
The work of helping people adopt both

Here’s a quick snapshot of each team’s approach, based on publicly available information, at the time of publication:

Atlassian uses off-the-shelf tools including Figma Make and Replit, alongside fine-tuned design system documentation.
Intercom prototypes directly in their production codebase with Claude Code, Figma Code Connect and the Figma MCP server.
Stripe built their own prototyping environment, Protodash, which runs in its own environment outside of production.
Shopify uses an internal toolkit called Quick together with a playground that mirrors their admin interface.
Ramp built a custom platform called Inspect to action bug fixes and customer feedback in production.

Somewhere to prototype

Diverging approaches

Two things distinguish the approach to prototyping amongst the five teams.

Hand-rolled vs off-the-shelf tools

The first is whether a team rolled their own prototyping tool or reached for an existing one. Stripe and Ramp have invested in internal platforms. Atlassian leans more heavily on products such as Figma Make and Replit. Intercom and Shopify sit somewhere in the middle, with their own workflows and integrations.

There's been a mix of investing in off-the-shelf configuration and custom-made tooling.

Sandboxed vs wired to production

The second is how close the prototype is to production. Stripe appears to keep Protodash isolated in a sandbox, but builds it from the real design system, so what a designer ships in a review is the same code an engineer can pick up. Ramp goes even further and prototypes directly on a branch of production. Both approaches result in a prototype real enough for people to trust it.

Design teams have different postures when it comes to integrating prototyping into development pipelines.

Converging features

Despite these diverging approaches to prototype setups, many teams and tools are converging on similar features. Features which all work to make design conversations easier, help people align earlier, and explore ideas quickly.

Shareable, hosted URLs and CLI commands & helpers

All five teams have created a safe space for designers to store and share prototypes. This enables anyone in the org to view a prototype in their browser without installing anything or setting up a local environment.

Intercom and Shopify have optimised the prototype publising process by providing CLI commands to prototype creators.

Control panel UI

Another common feature was a UI panel to control application state. This lets prototype creators and reviewers switch between empty and populated states, test with messy data, preview a different language, or see how the interface behaves for a startup compared to an enterprise customer, without rebuilding the prototype. That makes the prototype more useful because it can quickly test the robustness of the design against common user scenarios.

Fidelity control and rules-based output adjustment

Stripe and Shopify deliberately signal when work is unfinished. Early concepts are shown in greyscale or using off-brand UI components so reviewers naturally treat them as early prototypes rather than polished ready-to-ship designs.

In prototype comments

To help facilitate design review, Stripe and Shopify both built commenting directly into the prototype. AI summarises the feedback, then acts on the requested changes. Atlassian leverages similar features with Figma Make.

A feature comparison of prototype tools and custom-built tools. Atlassian omitted above as they use Figma Make.

Each one of these ideas removes a little friction from the design prototyping process.

Context is what makes the difference

[An LLM] will just imagine the entire design system without telling you when it’s not there. – Owen Williams, Stripe Engineer

If the prototyping environment is where the work happens, context is what determines the quality of the result.

This was the strongest pattern across the five teams. The quality of the AI-generated work depended on the quality of the information it was given. Each team had invested in providing context across the design system, the project, and the customer.

Design system context

Design system context is where most of the effort has gone, and for good reason. The challenge is hallucination. As Stripe’s Owen Williams put it, an LLM “will just imagine the entire design system without telling you when it’s not there.” The output often looks believable, even when it’s built on components that don’t exist. The trap is that the work looks complete, so teams start building on it, then hit the gap when someone tries to ship the real thing and the component isn't there or it doesn't work that way.

Several teams had run into the same limitation. Design tokens translate reasonably well to AI tools. Composing real components is much harder.

Atlassian generates instruction files directly from their component packages, but only exposes a carefully selected subset to the model. They narrow it down to 20 to 30 components with clear examples for each. More context, they found, often produced worse results. They also built a “translating from Tailwind” table for every component. Since language models have seen so much Tailwind and React, Atlassian lets the model think in familiar terms before mapping those concepts back to the correct design system components.

Intercom uses Figma Code Connect across their component library. Instead of recreating components from scratch, the AI receives the real import paths from the production codebase and works with what’s already there.

Stripe exposes their design system through an MCP server and requires the AI to query it before writing any code. Just as importantly, it defines what should happen if that server isn’t available, so the model fails honestly instead of confidently inventing an answer.

The principle behind each of these approaches is consistent. AI performs better when it can rely on a trusted source of truth rather than trying to fill in the gaps itself. My colleague Joe Prisk explored this in his article, Why your design system is the most important input to Claude Code. Despite coming from different directions, each of these teams leveraged their existing design system as context for their AI prototyping tools.

Project context

Project context is much simpler. It’s the brief, the requirements and the background to the work. Stripe’s designers paste a product requirements document directly from Google Docs into their prototype. Some Shopify designers keep a small collection of markdown files alongside each project so the model starts with the right context before generating anything.

Customer context

At Ramp, designers begin by understanding what customers are experiencing. They review session recordings in LogRocket, use internal tools that summarise where people struggle, and query research transcripts with Notion AI. Those insights shape both the prototype and the prompts that generate it.

Most of that work is still manual. Designers read the research, identify the patterns and bring those insights into the prototyping process themselves.

The same discipline that’s emerging around design systems and project context can also be applied to customer understanding. As these workflows mature, AI won’t just have better information about how an interface should be built. It’ll have better information about the people it’s being designed for.

Supporting adoption

The least visible part of these workflows may be the most important.

Design teams bring together people with very different technical backgrounds. Some designers have never opened a code editor, while others are comfortable working in Git and the command line. Even small hurdles, like setting up permissions, installing tools, or deploying a prototype, can stop someone before they get to the work itself. The teams I observed don’t treat this as an afterthought. They invest in training just as deliberately as they invest in tooling.

At Shopify, AI adoption accelerated after its CEO, Tobi Lütke, set the expectation that using AI would become part of how people work and how performance is assessed. Intercom’s push came from its CTO and design leadership. Atlassian ran a company-wide “AI Builder Week” where, by their account, thousands of employees paused their usual work for a week to learn AI prototyping.

The strongest adopters also made it easy for people to learn from each other. Intercom created a Prototyping Hub with practical resources, including a plain-language “Code 101 for designers” guide and step-by-step videos. Shopify maintains an internal gallery of prototypes alongside a shared library of prompts that others can reuse. Atlassian even discovered that inviting people into a Slack channel wasn’t particularly effective, while sending a group direct message prompted much stronger engagement. They built a small bot around that insight.

The broader lesson is that the investment in tools and the investment in people need to move together. A sophisticated prototyping environment isn’t much use if only a handful of people feel confident enough to use it.

What to get right first

The teams making the fastest progress had one thing in common; they already had a strong design system before AI entered the workflow. A design system has always been about making one team’s decisions clear and reusable for everyone else. Tokens, components, documentation, and guidance exist to help people build consistently. We’ve been doing that work for well over a decade. AI agents are just another audience for the same clarity. If you’re exploring what this means for your own team, we’re always happy to talk it through.

From Vibes to Durable Context

Thu, 20 Aug 2026 00:00:00 GMT

In my article on where AI can help with quality engineering, I wrote about planning, testing, review, and the parts of software delivery where faster feedback can improve the result.

Since then, I have been thinking about the other side of that argument. AI can make implementation much faster, but the more I work with coding agents, the more I find that engineering discipline matters.

The structure of a codebase shapes what an agent can understand from it. Clear patterns and boundaries reduce the amount it has to infer or guess. When it does have to guess, those assumptions can turn into code very quickly.

Agents will fill the gaps

It is common to pick up a ticket and find something nobody has decided yet.

Maybe the design covers the happy path but says nothing about a partial failure. Maybe the API contract leaves room for interpretation. Or the change crosses a boundary that looks arbitrary in the code but exists for a reason that is no longer obvious.

In a large codebase, the ticket only tells you so much. You might need to dig through an old discussion, ask product what the expected behaviour should be, or talk to someone who remembers why a particular choice was made. Sometimes finding that missing context is the engineering work.

Coding agents often handle that differently. When a requirement has two plausible interpretations, an agent will often choose one and keep going. The choice may be perfectly reasonable given what it can see, even when the missing context is the part that matters most.

Ambiguity still needs judgment.

Engineering still happens before implementation

I have found planning with agents useful. Before implementation starts, I want the agent to show me where the task is still unclear. What assumptions is it making? Which behaviours are underspecified? Are there decisions that could materially change the solution?

Sometimes a short conversation is enough. Larger changes may benefit from a more structured approach such as spec-driven development.

Planning surfaces decisions that might otherwise be made implicitly during implementation. From there, someone still needs to decide the correct behaviour, weigh the trade-offs, and understand which constraints are intentional.

AI speeds up development, and that can make it easier to skip some of the decision-making because plausible assumptions can quickly turn into code.

Make the decisions executable

Context comes from many places.

Humans build up context over time through reviews, incidents, conversations, and experience with the codebase. An agent starts without that history, so it has to rely on the task, the context we give it, and what it can work out from the repository.

That makes the context in the codebase important. When a constraint matters enough to shape the implementation, I want to see whether the codebase can carry it directly.

A behaviour that must not regress can become a test. Types or validation can rule out invalid states. Linting or dependency rules can make architectural boundaries enforceable. These ordinary engineering practices give an agent immediate feedback when it gets something wrong, rather than relying on it to find and correctly interpret a Markdown file at the right moment.

Product reasoning, trade-offs, and historical context still need prose. Documentation is most useful when it captures what the code cannot, instead of becoming a second implementation of the system in English.

Faster implementation raises the stakes

I do not think coding agents require us to rethink software engineering from scratch. Faster implementation puts more pressure on the decisions around it: what gets clarified up front, what still needs human judgment, what is worth documenting, and what the codebase should enforce.

Good AI-assisted development comes from making the right context available where it matters, so fewer important decisions are left to guesswork.

Is Your Design System Ready for AI?

Thu, 13 Aug 2026 00:00:00 GMT

We recently used AI to build a new piece of UI using an existing design system. The first result looked good. It compiled, broadly matched the design and used familiar patterns from the product.

Then the design departed slightly from the existing system. It introduced a new border colour and a small variation on an existing component. Instead of treating them as extensions of existing patterns, the AI created new components from scratch.

Nothing it produced was obviously broken. The interface looked reasonable in isolation, but it was slowly building a design system of its own.

AI can generate interfaces, but getting it to generate interfaces that belong in your product is much harder.

A component library is not a design language

Most design systems give engineers a collection of components, tokens and documentation. They tell us what exists. The decisions around how those pieces should be used together are often less visible.

One of our form inputs had an option to preserve space for validation messages. The team had decided to always enable it because the form shifted whenever a message appeared beneath an input.

The component defaulted to leaving the space out. Engineers on the project knew to override the default. The decision had become part of the team’s shared knowledge, passed between people during implementation and code review. It wasn’t documented anywhere the AI could find.

Whenever the AI added a form, it used the default. It found the correct component and used its API correctly. It had no way to know that the team had established a convention beyond what the component expressed.

This is where a component library stops short of describing the full design language.

Components and tokens define the available vocabulary. Teams also make decisions about composition, hierarchy and behaviour. Which variants are preferred. How components should respond to loading and error states. Which optional properties should be used in almost every implementation.

People absorb these decisions over time. AI needs somewhere to find them.

What makes a design system AI-ready?

An AI-ready design system makes its components, rules and examples discoverable without relying on someone remembering whom to ask.

Components in design map cleanly to their production equivalents. Tokens are structured and consistently used. Component APIs guide consumers towards expected behaviour. Documentation stays close enough to the implementation to remain accurate. Examples show components working together in realistic situations. Tests verify some of these expectations.

These are familiar design system concerns and AI gives them a new consumer.

An engineer faced with a confusing API can search the codebase, inspect existing implementations or ask another engineer what the team normally does. An AI agent works from the context it has been given. If it finds three competing form patterns and incomplete examples, it has to choose between them.

It will usually choose something plausible. That can be difficult to catch because the resulting code often compiles, passes a quick visual check and looks reasonable in isolation. The inconsistency only becomes obvious when you understand the wider system.

An AI-ready design system makes those wider decisions visible.

Access is getting better

The tools around design systems are starting to expose more useful context to AI.

Figma’s MCP server can provide structured information about a design instead of requiring an agent to infer everything from a screenshot. Code Connect can link a component in Figma to its production implementation. Storybook can expose component APIs, stories and documentation. Its MCP integration also gives agents a way to render components and run tests. Component registries make existing implementations directly available.

An agent has a better chance of finding your Button when it can discover the real component and see how it is used, however that access only solves part of the problem.

It won’t explain why your team always preserves validation-message space unless the decision appears somewhere in the system. A Storybook story that demonstrates the default behaviour may even reinforce the wrong pattern. Several discoverable components that solve the same problem still leave the agent to decide which one to use.

The quality of the result depends on the quality of the system being exposed.

Defaults carry more weight now

Our form-input problem could have been addressed through documentation. The component API offered another place to capture the decision. If every implementation should preserve message space, the default should reflect that.

Component APIs already guide engineers towards particular outcomes. AI agents follow that guidance very literally. They reach for the available component, accept its defaults and continue building. A good API makes the expected behaviour the easiest path.

That might mean changing a default, removing an option with few valid uses or introducing a higher-level composition that encodes the team’s preferred layout. A recurring component variation might belong in the design system instead of being recreated with local styles each time.

Some decisions will always depend on product context and need explanation. Others can be captured directly in components, tokens and tests.

Every decision encoded in the system is one less decision an engineer or AI agent has to rediscover.

Start with the mistakes

Teams can start by looking at what AI already gets wrong. Ask it to implement a small workflow using the existing design system. Watch where it invents a component, reaches for a raw colour value or chooses an unwanted variation. Pay attention to the corrections an experienced engineer makes during review. Those corrections point towards specific gaps in the design system.

The agent may create a component because the existing one was difficult to discover. It may use a raw value because the appropriate token was unclear. It may choose the wrong variant because every documented example used the default. It may assemble the right components incorrectly because the expected composition lived only in the team’s shared knowledge.

Each mistake gives you something concrete to improve. Take the component and connect it to its implementation. Update the default, encode the common composition and add a test that captures the expected behaviour. Then run the same task again.

The useful measure is whether the system helped the agent make a better decision without another carefully worded prompt.

AI exposes the gaps

The real design system is usually spread across Figma libraries, production components, documentation, code review comments and the memories of people who have worked on the product for years.

AI has none of that shared history unless we make it available.

It will use the default. It will choose the first plausible component. It will recreate a pattern when the existing one is difficult to find. Those choices reveal where the system depends on knowledge it has never captured.

Preparing a design system for AI means making those decisions clear, discoverable and verifiable. That helps AI generate interfaces that belong in the product. It also helps the next engineer understand why they were built that way.

Build vs buy: AI code review for teams that have opinions

Thu, 30 Jul 2026 00:00:00 GMT

The trial is the visible part. Pick a tool like CodeRabbit, Greptile, Qodo or Copilot, install the GitHub App, and within an hour it’s leaving comments on your pull requests.

For anyone leading a medium-to-large engineering team, the demo only answers the easy question. The harder one is who controls the rules tomorrow – and that’s the question that splits build from buy. But before weighing either option, the second engineer deserves a closer look.

Your team is already doing AI review

That engineer is not an outlier. While you’re evaluating vendors, or if you’ve outgrown your current tool, people across most orgs are piping diffs through the desktop agent they use for everything else, skimming the output, and pasting the good comments into the PR.

It’s understandable, and it breaks the one thing PR approval is supposed to mean. When a reviewer approves a change, the org is recording that a human weighed it. Once model comments ship under human names, that record is unreliable. You can’t tell a considered approval from a laundered one, and neither can the incident review six months later that’s trying to work out who actually looked at the migration.

The secondary costs follow from there. Each engineer’s agent applies whatever conventions live in their local setup, so "review standards" fragment per laptop, and none of it accumulates anywhere the org can see, version, or correct.

This is the status quo any build-vs-buy decision replaces: ad-hoc, unattributed AI review, fragmenting one laptop at a time. The bought tools fix the attribution problem on day one, which is a genuine point in their favour. Where their judgement comes from is the more complicated part.

What buying gets you

The bought tools are good at what they do. Fast setup, polished PR integration, cost controls, comments that arrive under the bot’s name, and review quality that keeps improving as the underlying models improve. For a team of ten with no written conventions, they’re probably the right call and you can stop reading here.

But look at where their judgement comes from. Out of the box, an off-the-shelf reviewer evaluates your code against the model’s training data: the aggregate opinion of public GitHub. That opinion knows nothing about your architecture decision docs, the naming convention you settled after a three-week argument, or the incident last quarter that led you to ban a whole class of query pattern.

The vendors know this, which is why most now offer custom rules. CodeRabbit has a config file, Greptile learns from your reviewers’ comments. It helps. But your rules live inside their system, expressed in their format, evaluated by their harness. You’re configuring someone else’s product rather than encoding your organisation’s knowledge somewhere you own it. At ten engineers that distinction is academic. At fifty, it is the decision itself.

Centralised rules for the win

At 30, 50, 100 engineers, review consistency stops coming from individuals and has to come from encoded organisational knowledge, living in one versioned place that every review reads on every PR.

And rules, here, doesn’t mean lint rules. Formatting and static checks are a solved problem with deterministic tooling. It means the judgement layer above them: the reasoning behind your style guide, your security policies, decision docs, the incident learnings no linter can express. That layer is written as prose, and the model reads it alongside every diff.

When the rules source is yours, three things follow:

Rules changes ship like code. An engineer proposes a new convention as a PR to update the review skill. It gets reviewed, merged, and lands in every subsequent code review across every team. No admin console, no per-repo config drift.

The same source feeds everything. The rules that drive AI review also feed your coding agents. The convention that tells the reviewer "flag raw SQL in service handlers" is the same file that tells Claude Code not to write it in the first place. Vendors can’t do this, because their rules only exist inside their review product.

Nothing is trapped. When you leave a bought platform, your accumulated rules and reviewer feedback stay behind. When your rules are markdown files in a repo, they outlive any tool decision you make.

Built means model-agnostic. Bought means resold.

The second argument is about the models themselves.

A bought platform picks the model for you, wraps it, and resells it inside their subscription. When a better model ships, and one ships every few months, you wait for the vendor to evaluate it, integrate it, and pass it through on their schedule and their margin. You’ve bought code review. What you’re paying for is someone else’s model procurement.

Build behind an aggregator and the relationship inverts. Route your review harness through OpenRouter, Bedrock, Cloudflare, LiteLLM, or Vercel’s AI Gateway and switching from Claude to GPT to Gemini is a one-line config change. New frontier model ships on a Tuesday, you’re reviewing PRs with it on Wednesday. You can also A/B models against your own rules, which no vendor benchmark tells you: their evals measure generic bug-catching, not how well a model applies your conventions.

Model quality is the fastest-moving variable in the equation. A vendor’s release cycle means paying a margin to move slower on exactly that variable.

What the build "costs"

The harness is thin: a CI hook that fires on PR events, a loader that pulls the relevant rules for the changed files, a prompt that combines diff, context/rules, and an aggregator call.

The ongoing cost is real but it’s the useful kind. Someone owns the rules repo. Prompts get tuned when reviews miss things. Rules get pruned when they generate noise. Call it maintenance if you like, but it amounts to your organisation deliberately curating its own engineering standards, which is work a team your size should be doing anyway. The rules then show up as comments on every PR, rather than sitting in a document nobody opens.

My recommendation

Small team, no written standards, want review lift this week: buy. CodeRabbit or Greptile will serve you well. Better yet, if you’re on GitHub + Claude Code leverage Claude Code Review and land somewhere in the middle.

Medium-to-large team with real conventions, decision docs, and opinions about how your code should look: build the thin layer. Record your rules, route the models through an aggregator, and treat review intelligence the way you treat the rest of your infrastructure: rented compute, owned configuration.

There's a strong case for owning the rules while renting the models. But whichever path you choose, the unattributed AI reviews already happening on your team deserve some daylight – and of all the trust problems you could tackle, attribution is probably the cheapest.

Optimise Your Context, Not Your Prompts

Wed, 15 Jul 2026 00:00:00 GMT

On a recent project, we were rebuilding parts of an application using an established design system. Some of the designs deviated from the system, often in subtle ways. One example was a border token that the existing component didn’t support through its API.

An engineer looking at this would see a decision that needed to be made. Was the difference intentional? Should the component support a new variant? Could the existing token be used? Or had the design drifted away from the system without anyone noticing?

The AI didn’t see a decision. It saw that the design couldn’t be reproduced with the existing component, so it built a new one from scratch. Viewed in isolation, the resulting code was perfectly reasonable. It matched the design as specified, but it had also bypassed the design system entirely and introduced another component for the team to maintain.

The prompt wasn’t the problem

The obvious thing to do would be to add more instructions to the prompt: always use components from the design system; never create a new component when one already exists; follow the patterns established in the codebase.

That may have prevented this particular component from being created, but it still wouldn’t have resolved the conflict between the design and the design system.

Sometimes a new component is the right choice. Sometimes the existing component needs to support another variant. Sometimes the design has drifted and needs to be brought back into line. The important thing is recognising when there is a decision to make instead of blindly implementing what’s in front of you.

The AI couldn’t make that distinction because it didn’t have the context behind those decisions. Much of that knowledge existed in the heads of the people working on the project. We could keep adding that knowledge to the prompt, but at some point the prompt becomes a substitute for documenting how the organisation builds software.

Improving the environment

As the project progressed, we started documenting playbooks for common situations. We captured how to build a new page layout, how forms should be structured and which patterns we wanted engineers to follow.

We also brought the design system into the application’s monorepo. This made its source code, component APIs and existing usage easier for AI to discover alongside the application consuming it. The AI could inspect the system directly instead of relying on our prompts to explain how it worked.

It began following the established patterns more consistently. The playbooks and design-system changes also gave engineers clearer examples to work from and reviewers a shared understanding of what the implementation should look like. The whole project became easier to work with.

Let’s not get carried away

It’s tempting to solve this by giving AI access to everything. More documentation, more files, more examples and a larger context window. More context only helps when it is relevant, current and consistent.

If the documentation recommends one pattern, the codebase contains three others and the design system supports something else entirely, AI has to decide which source to trust. It will usually make that decision without telling you there was any ambiguity.

The codebase, design system, architecture documentation and project playbooks all contribute to how AI understands a system. The goal is to make the intended way of building software clear enough that both engineers and AI can follow it.

Look at what your team keeps correcting

A good place to start is with the mistakes your team repeatedly corrects in AI-generated code.

If AI keeps recreating components that already exist, adding another instruction to the prompt may stop it happening next time. However, it’s more useful to ask why the existing component was difficult to discover in the first place.

The answer tells you what needs to become clearer or easier to access. Whatever the fix, the repeated correction has exposed a gap in the context surrounding the work.

Closing that gap makes the right decision easier to reach before any code is generated.

Workarounds become part of the system

Teams get very good at navigating their own systems. Experienced engineers know which documentation is current, where the reliable examples live and who to ask when the code doesn’t tell the whole story.

After a while, those workarounds become part of how the team operates. AI exposes this hidden context because it doesn’t share the team’s history. When it struggles to find the right component or understand why the system is structured a certain way, it may be surfacing friction that engineers have simply learned to work around.

Optimise your context

The component from our project wasn’t a spectacular AI failure. It compiled, matched the design and looked reasonable in isolation. The problem only became visible when we considered how it fit into the wider system.

The next time AI produces reasonable code that still feels wrong, pay attention to the correction your team makes. Ask what information would have helped it recognise that a decision was needed, then put that information somewhere the next engineer or AI assistant can find it.

Repeated corrections will show you where the project’s architecture, conventions and shared knowledge are unclear or difficult to access. Start there. Choose one source, make it more reliable and easier to find, then see whether the same mistake happens again.

These gaps can be difficult to see when your team has learned to work around them. An outside perspective can help make them visible and identify which foundations are worth improving first.

The next prompt is one interaction. The context around it shapes every decision that follows.

Where AI Actually Helps Quality Engineering

Tue, 14 Jul 2026 00:00:00 GMT

AI can produce convincing work quickly, but confidence in its output has to be earned. The value of AI-assisted QA goes beyond faster test generation: it helps teams build and carry context from planning through to release, using checks and guardrails to validate the work along the way. This article takes a high-level view of how AI can support quality throughout that process.

On a recent project, we used AI to explore a codebase that had evolved over several years to uncover undocumented variations in fields and business rules. Surfacing them early gave us concrete behaviour to review and turn into testable requirements before those gaps became costly to fix. That understanding then carried into testing, review and release.

Making behaviour testable

Findings and decisions can be captured in many forms. In my experience, BDD scenarios make specifications easier for both the team and AI to understand and use because they describe what the product should do without prescribing how it should be built.

That shared language allows product, design, engineering and QA to work from the same expectations. The scenarios also document product behaviour, giving AI clearer constraints and a reliable source of context when it starts work on a new ticket.

They can become end-to-end tests and guide unit, integration and manual testing. Paired with Test-Driven Development (TDD), they create a continuous feedback loop for checking AI-assisted implementation against the intended behaviour. This increases confidence in the output, while human judgement remains essential for filtering out low-value or irrelevant tests that can make the coverage appear stronger than it is.

Shortening feedback loops

As those specifications move into implementation, AI can also help check the work against approved designs, accessibility requirements and acceptance criteria. Many of these checks are traditionally deferred until review or QA, but an AI agent with access to the relevant artefacts can perform an earlier first pass.

It can flag potential accessibility issues, design drift, missed requirements, likely bugs and code that no longer matches the intended behaviour before a pull request is opened or a task is marked complete. These findings are leads, not decisions; reviewers still determine whether they are valid and what action to take.

This shifts human attention away from routine checks and towards decisions that require experience, product knowledge and context. Running that first pass earlier and more often shortens feedback loops and gives the next stage fewer avoidable issues to resolve.

Carrying context into release and beyond

Once specifications and BDD scenarios are in place, AI can reuse them to generate smoke tests, release checklists and release criteria. Instead of starting from a generic template, these checks can reflect the behaviour, risks and edge cases already identified during planning and development.

AI can also help prioritise critical workflows, so the most important paths are validated first and release decisions are based on agreed behaviour rather than memory or assumptions.

After release, the same specifications provide a clear baseline during an incident. AI can compare the expected behaviour with logs, recent changes and production behaviour to help identify where the system diverged and narrow the investigation before detailed debugging begins. Human review remains essential: teams still need to validate the generated release checks, assess the incident findings and decide what action to take.

AI as a force multiplier

AI works best as a force multiplier, not a replacement for human judgement. With the right context, checks and guardrails, it can surface problems earlier and give teams greater confidence in their work. Used well, it helps teams anticipate risks, make better decisions and deliver higher-quality software.

Why Great Engineering Still Wins

Thu, 09 Jul 2026 00:00:00 GMT

AI is getting ridiculously good at smashing out code. Not long ago it was a juiced-up autocomplete tool. Now it'll happily build an entire feature, write the tests, and explain what it just did.

Impressive? Absolutely. Surprising? Not anymore. Either way, it's made people wonder what happens to software engineers once the code writes itself.

Writing code has never been the thing most engineering teams struggle with. It's the one skill most of us have spent our careers sharpening. Projects usually stall for entirely different reasons. Someone has to figure out the problem worth solving. Product and engineering have to agree on what a good outcome looks like. Architects have to decide where a new feature fits into an existing system. Everyone involved has different priorities, and they rarely align.

Then there are the things nobody plans for. Undocumented legacy behaviour. Third-party APIs that don't do what the docs promised. Performance issues that only show up once real customer data hits the system. Security requirements nobody mentioned until the last minute.

None of this disappears because AI can whip up a React component in a few seconds. These are the problems that have always defined software engineering. AI can produce the code. It still can't sit in a room with product, engineering and design and work through a messy problem together.

From implementation to judgement

AI has shifted where engineers spend their time. Less time writing boilerplate, more time reviewing it. Less time trawling documentation, more time deciding which approach fits. A CRUD endpoint used to eat an afternoon; now that afternoon goes into figuring out how the feature fits the wider architecture.

The best engineers I've worked with have always known when not to write code. They spot problems before they happen and recognise patterns others miss. Cleverness loses to consistency, and they've always known it.

AI has freed engineers to focus on the decisions that actually shape good software. The value has changed from implementation to judgement, collaboration, and technical leadership.

Better context, better outcomes

There's an old saying that content is king. In software engineering today, context is king. As engineers spend less time writing code and more time deciding, the quality of that context carries more weight.

Clean architecture. A well-maintained design system. Documentation people actually want to read. None of this is new. AI has just raised the cost of getting it wrong.

Watch an AI assistant confidently generate code that ignores your team's conventions, or duplicates something that already exists, and you've seen this play out. The model isn't the problem. It doesn't have enough context to make the call an experienced engineer would make.

It's no coincidence that the organisations getting the most out of AI are also investing in architecture and technical leadership. They're building the strongest possible foundation for both engineers and AI assistants.

Great engineering still wins

It’s so easy to slip into the same old technology rollout thinking with AI. Pick a model. Give everyone access. Measure how much faster the pull requests come in. That might lift productivity for a while, but it's not where the real gains come from.

The organisations pulling ahead are using AI as a multiplier to improve how software gets built. They're developing practices that make good decisions easier, codebases people can actually understand and architecture that evolves with the product. They're not chasing whatever model sits at the bleeding edge. They're building the environment where engineers and AI can both make good calls, consistently.

AI has made writing code faster and more accessible than it's been before. That was never the hardest part of building software. Great software engineers navigate ambiguity, balance competing priorities and solve the right problems. That’s not going anywhere.

The AI will keep getting better. Great engineering will always matter.

Designing beyond the median user

Thu, 04 Jun 2026 00:00:00 GMT

In the 1950s, US Air Force statistician Gilbert Daniels measured 4,063 active pilots across ten anthropometric dimensions: neck, chest, sleeve, leg, you name it. None of them fell within the average range on all ten. And when he narrowed the test to three dimensions, fewer than 3.5% of pilots met the average. Daniels “landed” with the following conclusion:

...the “average [hu]man” is a misleading and illusory concept as a basis for design criteria, and is particularly so when more than one dimension is being considered.

The Air Force had been designing cockpits around the average pilot for the better part of two decades. Daniels’ finding explained why so many pilots were dying in them. The military’s response was adjustable cockpits sized to the 5th–95th percentile range of each dimension. The shape of the cockpit became whatever shape any one pilot needed it to be. Accident rates plummeted.

It’s taken software a while to inherit Daniels’ lesson…

For most of its history, software has remained the inflexible cockpit: one interface, designed against a notional median user, shipped to everyone. It has no physical reason to be inflexible, but for the longest time the working assumption was that one shape per platform was both possible and good.

Designing for nobody

Platform documentation started the work of homogenising the end user. Apple’s original Human Interface Guidelines codified a vocabulary (menu bar, window controls, modal dialog) and laid out its rationale. Microsoft soon followed. Their existence produced more usable software than the chaotic alternative of every application inventing its own conventions. But what these guidelines also reified was a single monolithic shape, applied to every user.

Alan Cooper named the consequence in 1999. Without a specific person in mind, every stakeholder projects their own assumptions onto “the user”, and every feature becomes defensible because some user might want it. He called this fictional person the elastic user: the one who bends and stretches to fit whatever decision needs justifying. The elastic user is the median user’s quieter twin – the one who survives because nobody is being specific about who you’re designing for.

The near-solutions

Cooper’s solution was the persona: a named archetype that had concrete goals. Over time Cooper and others formalised the persona hierarchy into a primary persona (the design target, one per interface) surrounded by secondary, supplemental, customer, served, and negative personas. The axiom was that the primary persona’s needs and goals should be “completely and happily satisfied by a single interface without disenfranchising any of the other personas” (source).

Single interface is the clincher here. Personas force specificity about who you’re designing for, but the interface is still one shape, and the shape still has to accommodate everyone else. Cooper’s own framing that secondary personas receive “small additions that should not negatively affect the experience of the primary persona” names the compromise without quite admitting it. It’s the cockpit sized for one, and a sprinkling of affordances for the rest of us.

Jobs to the rescue?

Where Personas reframed who we were designing for, a parallel methodology reframed the what. Jobs to Be Done (Ulwick and Christensen) argued that people don’t buy products so much as hire them to do a job. And that the job, being more durable than any demographic, is the better unit to design around. JTBD fixed the weakness in Cooper’s framework but it left the architecture untouched. A product built around a primary job still ships one interface, optimised for that job, compromising on the rest. The decomposition improved, but the constraint stuck around.

Neither Cooper nor the jobs school was wrong. Each named something real, and each gave us tools that improved what came before. What neither could do was build a system where the interface itself adjusts.

A framework for the fringe dwellers

On most projects of any complexity, a lot of design time gets spent attending to edge cases: the fields, paths, and decisions that your average user is unlikely to make or take. The thing is, these aren’t actually edges, they’re just not the average. For some other person using the same software, those edge cases are the whole experience. The interface holds them; but the design discipline may not.

Jutta Treviranus, the field’s leading voice in inclusive design, built a design philosophy on that exact observation. Designing from the edges tends to produce better outcomes for everyone, because the edges are where the real constraints surface. Instead of sizing the cockpit to the 5th-to-95th percentile and accept the tails as casualties, design for the fringe dwellers and let the middle look after itself. She nailed the principle. But the thing nobody had was a different interface for each person. To get past it, you had to make the interface itself adapt.

The failed escape

The HCI field tried just this. Ernest Edmonds opened the door in 1981 with an essay called “Adaptive Man-Computer Interfaces,” and by 1990 the field had its first major synthesis in Browne, Totterdell and Norman’s Adaptive User Interfaces. The argument was straightforward: if the system can observe what the user is doing, it can also adapt the interface to match.

The argument became a public debate at CHI 1997, when Ben Shneiderman and Pattie Maes debated the competing paradigms of direct manipulation versus interface agents. Maes argued that as software environments grew more complex, users would need intelligent delegation; the system would need to do some of the work of inferring what they wanted. Shneiderman posited that users need control, predictability, and comprehensibility; and that adaptive systems are inherently unpredictable, because they change underneath you for reasons you can’t see.

Maes’ thesis crash-landed in the form of Lumière, Microsoft’s research project that incarnated as Clippy, Office 97’s desktop assistant. The research was technically sound, and Clippy’s underlying Bayesian model was capable of inferring what users were likely doing. But the user experience was widely loathed. Because the inference happened invisibly, Clippy’s behaviour felt unpredictable.

Embedded media — view this post on thinkmill.com.au.

Shneiderman’s argument largely prevailed for the next twenty-five years. Adaptive systems couldn’t reliably model intent, so users couldn’t predict what would happen. The cure was worse than the disease.

Three things converged

Since Clippy’s demise in 1997 three independent developments have occurred that together make it worth revisiting the median-user problem.

1. The atoms became reliable

Design systems started out as documentation: rules for designing the one shape, well. Twitter’s Bootstrap took consistency to industrial scale. Then along came Brad Frost’s Atomic Design which gave the practice a mental model of atoms, molecules, and organisms. Jina Anne followed up with design tokens to encode the subatomic particles of UI.

But the shift that mattered most for what comes next was when components stopped imposing their own visual style. Tools like Headless UI, Radix UI, and React Aria ushered in an era where atoms were standardised, accessibility-correct, and behaviour-complete in a way they had never been before. The atoms became reliable enough to compose across brands at configuration time. The interface stopped being a single thing the design team locks in. It became a space of possible shapes, bounded by the design system, that configuring users move within.

We’ve watched this play out in our own client work. Earth, the design system we built with AnywhereWorks, has a token architecture designed to let small business owners reshape the booking page (palette, logos, button shapes) to match their brand. This flexible configuration approach carries through our work with Rugby Australia and AusCycling: where themability unlocked scale for content managers.

2. The data became reachable

Headless content APIs are the second integral pillar. The design principle behind headless is to enable rendering flexibility from a single source of truth, so many frontends could consume the same content and present it in myriad ways. We open-sourced Keystone in 2013 as the first Node-based headless CMS of its kind. Contentful, Sanity, and others soon followed with their own unique spin on headless. A decade on, these platforms expose their data through schema-driven, self-documenting APIs and power many of the world’s interfaces. While they weren’t built with LLMs in mind, they happen to be exactly the kind of structured, front-end-agnostic context that LLMs thrive on.

3. The platforms met a new consumer

The third thread is the newest. The Model Context Protocol makes any platform agent-native so it is readable and operable by a language model, not just developer-written code. The MCP Apps Extension (late 2025) extends the pattern further, standardising how servers ship interactive UI back to clients.

The assumption that humans are the only consumers of the platform, implicit in seventy years of HCI, drops.

None of these three developments were aimed at where they’ve collectively arrived. Design systems matured so teams could ship faster without losing quality. Platforms went headless for channel flexibility. Agent-native exposure landed because the agents arrived. Nobody was coordinating any of it. Looking back, the through-line for adaptive UI is clear.

A new architectural response to the old debate

Bounded generation

The convergence of these three pieces asks new questions about what might be possible with composition. When:

The user states what they want to see, in plain language.
A language model reads a typed schema and a typed component catalogue, and emits a typed spec.
A deterministic renderer turns the spec into UI.

The LLM never writes the UI code in an unbound manner. It selects from the catalogue, binds to the schema, and describes the result.

Several independent versions of this bounded-generation pattern (Portal UX Agent, A2UI, json-render, MCP Apps) all landed within a four-month window in late 2025. It’s the same underlying principle each time: the model composes, the schema constrains, and the renderer executes.

Anchored intent

If we pair the productivity of bounded on-system UI generation with the tried-and-tested pinning metaphor where users save the composed view as a stable artefact they can return to, share, or evolve — the 1997 Shneiderman–Maes debate reframes in an interesting light.

Shneiderman’s primary concern was invisible inference: the system changing under you for reasons you can’t see. Today, when the user states intent (prompts for the view they want) that hidden and confusing inference moves into the open. His comprehensibility and predictability concerns find their footing in a composed interface where stating intent is visible and the result is pinnable. Maes’s case for adaptive delegation finds a new friend in the LLM who’s capable of doing the (bounded) composition at prompt time. Neither side won. But the terms certainly changed.

It’s worth notiing thay while architectural availability is one thing, the shape of such a paradigm in production is another. End-user just-in-time composition at this scale hasn’t yet shipped in any SaaS products I’m tracking. But what’s adjacent is real:

companies like Figma, Canva, and Box are shipping official components that render inside chat clients like Claude
vibe-coding sessions are producing hyperfunctional design artefacts that access platform data and solve for UX in ways that are truly centred around unique, non-average use cases

Some of the architectural responses to the median-user problem are now possible in a way they weren’t five years ago, even if whether they ship widely turns on things that aren’t architectural: economics, governance, accountability, or the cold-start problem of not knowing what to ask for.

What might change going forward

This shift changes the work of designing. The unit has been the interface for seventy years — what we’ve shipped, argued over, recruited for, charged for.

When composition at the moment of intent is possible, the unit moves toward the schema, the primitives, and the boundaries of what can be composed. The default interface a platform ships still matters because it bootstraps everyone, but it stops being the only shape your users will ever meet. Persona work aimed the whole effort at one representative user; our discipline can now hold the full spread of them, edge cases and all.

That’s a different design surface, and arguably a bigger one.

If you ship software, three questions start to matter:

What does your schema look like to a language model that’s never read your documentation?
Which of your "edge cases" stop being edges once users can compose what they need?
What’s the shape of the space your users should be able to move within?

The cockpit never had to be one shape. For the first time, it doesn’t have to be.

What engineering teams owe for the AI speed boost

Fri, 29 May 2026 00:00:00 GMT

The productivity gains were real. Worth saying that upfront, because a lot of the conversation right now sounds like revisionism – like the people who moved fast were somehow naive, and the people who stayed cautious were wise. That's not what happened. Teams shipped faster. Backlogs shrank. A mid-level engineer with decent prompting skills could scaffold a new service in an afternoon that would have taken a senior dev most of a week. Stakeholders loved it, of course they did.

The problem isn't that organisations moved fast. The problem is that some of them stopped there.

Here's what didn't show up in the velocity charts: code that nobody fully understood. Not "bad" code, necessarily – plausible-looking code, code that passed review, code that worked fine in staging. But when the 2am production incident happened, or the security review came around, the engineer who "wrote" it couldn't walk you through it. That's a different kind of risk than the ones most teams were tracking.

Review culture took a quiet hit too. PR turnaround times dropped, which looked like efficiency, and sometimes it was. But the second pair of eyes – the one that catches the auth bug, the injection vector, the edge case that only shows up under load – that pair of eyes started skimming. You can't really blame people. The volume went up, the review expectations didn't change, something had to give.

And then there's the dependency problem. AI-generated code reaches for libraries. Not always the right ones, not always maintained ones, not always the ones already in your stack. Over twelve months of moving fast, a lot of codebases got significantly wider and harder to reason about. Nobody planned for it. Nobody really noticed until they tried to upgrade something.

The architectural decisions are the most concerning. Using AI to generate a utility function is fine. Using it to design your data model or your service boundaries is a different proposition – one that requires understanding tradeoffs and consequences that LLMs don't reliably have. "It worked in the prototype" is doing a lot of heavy lifting in some engineering orgs right now.

None of this is a mystery in hindsight. You give people a powerful new tool and tell them to go faster, and they go faster. The debt accumulates quietly until it doesn't. Security incidents are often the first sign – not always dramatic ones, sometimes it's credentials in a repo, an open endpoint, an unvalidated input that sat there for months before someone noticed. Maintenance slows down. Engineers are slower in codebases they didn't really build, full of patterns that don't match the team's conventions. Abstractions that seemed clean in isolation that don't compose well.

There's also a talent problem that nobody wants to say out loud: junior engineers who spent the last year prompting rather than building are missing some foundational mental models. The ones that let you catch what the model gets wrong. That's not a gap you can hire your way out of quickly, and it's not really their fault – it's the environment they were put in.

So what now? There's no clean undo.

The teams I've seen handle this well aren't doing anything heroic. They're auditing their codebases without turning it into a blame exercise. They're asking which AI-assisted code hasn't had a real senior review, where the test coverage gaps are, what's in the dependency tree that shouldn't be there. They're reinvesting in review – not as a slowdown, but as a recognition that speed without it is just faster debt accumulation. They're being deliberate about the line between AI for implementation (good) and AI for architecture (milage may vary). And they're having the cross-functional conversation — engineering, security, and product in the same room, looking at the same numbers, instead of each optimising for their own metrics.

This is all easy to say in hindsight, the last twelve months weren't a mistake. The speed was real, the competitive pressure was real, and organisations that didn't move lost ground to ones that did. But there's a difference between "we moved fast" and "we're done." The bill for the speed is arriving now – not as punishment, just as the completely predictable consequence of how complex systems work. The organisations that come out of this well are the ones honest enough to look at what they actually built.

If any of this sounds familiar and you find yourself needing a little extra help let's talk.

A behavioural framework for the monsters in your team

Fri, 22 May 2026 00:00:00 GMT

Much of what the AI in Design 2026 report describes (designers shipping code, broader role definitions, the search for new team structures) isn’t new everywhere. We’ve been refining a cross-disciplinary practice for over a decade. The report charts its emergence in the mainstream, but one metaphor that’s followed it into the coverage ("Frankenjobs") doesn’t quite fit what the practice actually looks like.

What the report unearths

The AI in Design 2026 report, from Designer Fund in partnership with Foundation Capital, surveyed over 900 designers across 60+ countries. It catalogues a profession mid-mutation. 91% of respondents now use AI weekly, up from 54% last year. Half of them have shipped AI-generated code to production. The average designer toolstack has more than doubled, from three to seven tools.

The shape of design work itself is also shifting. Towards systems thinking, code, and cross-functional ownership:

Half of the leaders we surveyed report that when they hire designers now, they’re placing greater emphasis on AI fluency, followed by systems thinking and strategic skills. 22% are placing more emphasis on technical or coding skills.

Fast Company picked up the report under the headline AI imagineer. Design crafter. Builder. Why design is suddenly full of Frankenjobs.

"Frankenjob" puts a name to the discomfort of role-blurring vividly: parts forced into one body, stitched together, the results more contradiction than coherence. Hideous new titles are emerging from the laboratory floor: designer engineer, AI imagineer, builder, design crafter. Designers really are doing PM and engineering work, and vice versa...

Who’s the monster here?

In Mary Shelley’s epic tome, Frankenstein is the creator, not the monster. Victor built his creature and walked away from it:

Oh! no mortal could support the horror of that countenance. A mummy again endued with animation could not be so hideous as that wretch. I had gazed on him while unfinished; he was ugly then; but when those muscles and joints were rendered capable of motion, it became a thing such as even Dante could not have conceived.

The story’s horror lives equal parts within Victor’s abandonment as it does the unorthodox form of his nameless progeny.

Designer Fund’s Ben Blumenrose, in the same Fast Company piece, described the prior orthodoxy:

For the past two decades, the way we built software was the same for the most part. Someone came up with a concept of what they wanted to build, they’d work with a PM [project manager] to figure that out, they’d bring on a designer to give the visuals to that thing, then pass it to the engineer to build.

Stepping out of the laboratory: AI is clearly making designers more capable and fast, and the report captures that clearly.

What’s harder to see is the work that doesn’t get easier: building shared context, shared artefacts, and shared understanding between the people who now bring broader skills to the table. The "Frankenjob" feeling lands at that seam, not in the new roles themselves. That practice doesn’t take a multi-year cycle to form, but it does take intention.

The Fast Company article makes it sound like these monsters never existed, and that AI (Victor) is the sole progenitor of these cross-disciplinary forms. In truth, some teams of designers, engineers, and product people have been working this way for quite a while now. AI didn’t create the practice; it just made it visible at scale. We’re one of those teams.

How to do better than Victor

In 2017 we brought a credentialed designer into what was an engineering-led company. By 2020, our then-design director Lauren Argenta had distilled our practice into a five-behaviour framework called Engineering-led design:

Context together. Everyone attends early discovery, regardless of discipline. Designers learn the technical constraints in real time. Engineers see what designers see in user research.
Create a dictionary. Define shared vocabulary as you go. Acronyms get unpacked. Practice-specific jargon gets reserved meanings. The dictionary becomes a bridge between disciplines.
Teach as you work. Short, structured asides between disciplines. Thirty-minute sessions on graph theory, spatial localisation, or whatever the team needs to unlock. Framed as a first-class part of daily work, not a distraction.
Play it back to validate. Reveal your thinking before you commit to it. Surface hidden assumptions. The team catches what an individual would miss.
Break down language barriers. The majority discipline translates for the minority. In an engineering-led environment, that means engineers do the translating.

These five behaviours became the seed of a broader framework: the cross-disciplinary principles, mindsets, and approaches we use when helping clients. In a 2023 retrospective on a complex accounting app project, Ben Derham and Chris Dale described what happens when a team sets up using this framework: a core team of Product owner, UX lead, Tech lead, and Design-engineer, all co-piloting with equal responsibility. They worked directly in the browser wherever possible, and used a schema-first approach to surface dependencies and build a shared vocabulary. This way of working sounds eerily like the franken-practices that are emerging today!

Lab notes for the curious

If you’re running a design team and beginning to understand the value that this monstrous way of working offers teams like yours, here’s a few practical takeaways to help navigate the shift that we found meaningful:

Check out Shamsi Brinn’s No Handoff framework. A manifesto for replacing waterfall handovers with synchronous, cross-disciplinary collaboration.
Read the Thinkmill Method. It’s our synthesis and magnum opus of all things cross-disciplinarity.
Talk to engineers, often. Cross-disciplinary practice depends on small, frequent, low-stakes conversations more than formal handovers.
Work together in real time. The biggest gains we’ve seen come from designing and engineering in the same room (or the same call), in the same artefact, in the same conversation, not handing assets back and forth. As AI gets faster, and AI companies define better multi-player experiences (thanks Maggie!), this is becoming a lot easier to achieve.

Every team’s path to cross-disciplinary practice will look different. But the shape of the practice itself is familiar: people working together in shared language, building in parallel, learning from each other over time.

If you’re navigating this shift in your team and want a second pair of eyes (or hands), reach out for a chat.

Why your design system is the most important input to Claude Code

Thu, 05 Mar 2026 00:00:00 GMT

Claude Code can generate a working UI in seconds. Whether that UI is coherent with the rest of your product is a different question entirely, and the answer lives in your design system.

At Thinkmill, we’ve spent years thinking about the gap between how designers specify things and how developers implement them. Design systems were our answer to that gap. Now there’s a new actor in the room: AI-assisted development tools like Claude Code. And it turns out, design systems matter more in this context, not less.

Here’s why.

The problem with fast generation

Claude Code is remarkably good at producing UI from a short description. Ask it to build a user profile card and it will. Ask it to add a danger button and it will do that too. The problem is that without constraints, every one of those generation tasks involves Claude making dozens of micro-decisions: What shade of red? What padding? What border radius? What font size for the label?

Each individual decision is reasonable. Across fifty components generated over the course of a sprint, you end up with fifty islands of slightly different visual language. Buttons that are almost the same. Spacing that’s close but not quite. A red that’s near your brand red but isn’t.

This is what we think of as drift at speed. It’s not new, developers have always introduced inconsistency, but AI tools can produce it an order of magnitude faster.

What a design system actually gives Claude

A design system’s job, in the context of AI-assisted development, is to collapse the decision space. Instead of inventing, Claude composes.

This works across several layers:

Design tokens give Claude named values instead of raw numbers. When your CLAUDE.md says "never use raw hex, use CSS custom properties from @acme/tokens", Claude stops generating background-color: #dc2626 and starts generating background-color: var(--color-surface-danger). That one change means every piece of generated UI inherits your theming system for free.

Component APIs give Claude a vocabulary. When Button has variant="destructive" as a defined prop, Claude reaches for it. When it doesn’t exist, Claude invents something, usually a one-off styled <button> that will diverge from everything else. The specificity of your component API is the specificity of Claude’s output.

Layout primitives like Stack, Box, Grid mean Claude isn’t reasoning from scratch about flexbox every time it needs to position things. It picks from a set of named spatial patterns you’ve already sanctioned.

Storybook stories are, in practice, the most underrated input. Every story Claude can read is a worked example of correct usage. Think of them less as documentation for humans and more as training context for the AI.

The output quality difference is stark

Here’s an example of the same prompt, run with and without a design system in context.

Without:

<button
  style={{
    backgroundColor: '#dc2626',
    color: 'white',
    padding: '8px 16px',
    borderRadius: '4px',
    border: 'none',
    fontSize: '14px',
  }}
>
  Delete Account
</button>

With:

<Button variant="destructive" size="md" onClick={handleDelete}>
  Delete Account
</Button>

The second version is themeable, consistent with every other destructive action in the product, and has accessibility handled inside the component. Claude didn’t do less work, it did better work, because it had a better vocabulary to draw from.

How to wire this up with CLAUDE.md

Claude Code reads CLAUDE.md files up the directory tree as persistent context. This is the bridge between your design system and Claude’s behaviour.

For a design system consumed as an external package, a minimal but effective CLAUDE.md section looks like this:

## Design System

We use `@acme/design-system`. Always import from this package.
Never write inline styles or raw Tailwind classes.

### Imports
- Components: `import { Button, Input, Stack } from '@acme/design-system'`
- Tokens: `import { tokens } from '@acme/design-system/tokens'`

### Component variants
Button: primary | secondary | ghost | destructive (sizes: sm | md | lg)
Input: default | error | disabled
Badge: neutral | positive | warning | critical

### Rules
- Use design tokens for all colour, spacing, and type values
- Prefer layout primitives (Stack, Cluster, Grid) over custom flexbox
- All form inputs must use DS components, not native elements

That’s it. Claude will read this before generating any UI and will constrain itself accordingly.

If you’re in a monorepo where the design system lives in packages/design-system, add a CLAUDE.md inside that directory as well. Claude picks it up automatically and gets direct access to your component docs, token definitions, and any guidance you want to give about the system’s intent.

The design system is now the spec

There’s a wider shift worth naming here. In traditional product development, designers produce detailed specs (annotated Figma files, redlines, component documentation) that developers implement. The handoff is where things go wrong.

In a Claude Code workflow, that handoff changes shape. You write intent: "build a user settings page". Claude looks up your design system, understands the vocabulary, and composes. The detailed decisions (spacing, type scale, component selection) are handled by the system, not the spec.

This doesn’t mean you stop designing. It means the design system is the specification. The quality of your design system directly determines the quality of Claude’s output. Investing in clear token naming, well-documented component APIs, and good Storybook coverage isn’t just good hygiene anymore — it’s the highest-leverage thing you can do for AI-assisted development velocity.

What this means in practice

A few things shift when you take this seriously:

Write your design system docs as if Claude will read them, because it will. Be explicit about what variants exist. Name things semantically, not visually. destructive is better than red. surface.subtle is better than gray-100.

Enforce tokens with lint rules. Add an ESLint rule that flags raw hex values and hardcoded px strings. If Claude generates something invalid, your tooling catches it immediately.

Keep components small and composable. Claude is better at assembling ten clear primitives than reasoning about one complex component with forty props. If you’ve been deferring a refactor of a monolithic component, this is a good reason to move it up the list.

Review intent, not pixels. When you’re reviewing Claude’s output, you shouldn’t be checking whether the button is the right shade of blue. The design system handles that. You’re reviewing whether the right components were chosen, whether the interaction model makes sense, whether the data flow is correct. This is a better use of your attention.

Design systems have always been about reducing the cost of consistency at scale. AI-assisted development just raised the throughput, which makes a well-maintained design system more valuable than ever.

Faster CI Pipelines: Share build artifacts across independent jobs

Wed, 14 Jan 2026 00:00:00 GMT

As engineering teams scale, Continuous Integration (CI) pipelines often become a bottleneck. The feedback loop slows down, and compute costs rise linearly with the number of jobs. This challenge is particularly acute in monorepos, where a single commit often triggers a matrix of linting, testing, and analysis jobs across multiple packages. A common denominator I’ve noticed in many slower workflows is often either the redundancy of build steps across parallel jobs or the lack of parallel jobs to avoid redundant build steps.

Here’s an example of two workflows that demonstrate the impact of sharing build artifacts between independent jobs.

GitHub Actions workflow: Jobs with cached build artifacts

GitHub Actions workflow: Jobs without cached build artifacts

In a distributed workflow, you might have separate jobs for Unit Tests, E2E Tests, and Bundle Analysis. If these jobs run in parallel, they typically function as isolated environments. While modern package managers (like pnpm or npm) have excellent mechanisms for caching downloaded dependencies based on lockfiles, they don’t solve the redundancy of the build process.

If three parallel jobs need the compiled application to run their tests, they often end up running the build script three times. This redundancy introduces:

Wasted compute: compiling the same TypeScript/codebase multiple times.
Increased cost: linearly increasing billable minutes for CPU-intensive tasks.
Non-determinism: slight timing or environment differences could theoretically yield different build outputs.

The architectural approach: Build once, consume everywhere

The optimal architecture treats the build process as a distinct, upstream producer. We build the application once, package the generated artifacts (e.g., dist/, .next/, build/), and distribute them to downstream consumer jobs.

While standard dependency caching relies on pnpm-lock.yaml (which rarely changes), artifact caching needs to be strictly tied to the source code state. By using the specific git commit SHA as our cache key, we can safely share build outputs between jobs running on the same commit.

Diagram: Workflow Architecture

A contrived example

To demonstrate this, I set up a pnpm monorepo containing a Vite+React application and a Playwright test suite. The goal is to build in one job and test in another, without rebuilding.

Here’s the link to the repo: https://github.com/Thinkmill/demo-actions-cache

Step 1: The producer (Build job)

The Build job is responsible for the heavy lifting: installing dependencies and compiling the application.

We use actions/cache with a commit-specific key (${{ github.sha }}). This is the critical distinction from dependency caching. We aren’t just caching what we downloaded; we are caching what we generated.

# Build Job configuration
- name: Cache Build Artifacts
  uses: actions/cache@v3
  with:
    # We cache the build output (dist)
    # Dependencies are automatically cached using pnpm store cache
    path: |
      apps/example-react-app/dist
      node_modules
    # The commit SHA ensures a unique cache entry for this run
    key: ${{ runner.os }}-build-${{ github.sha }}

Step 2: The consumers (Test & Analysis jobs)

Downstream jobs declare a needs: build dependency. They don’t need to run pnpm install or pnpm build. They simply restore the "hydrated" workspace state—containing both the compiled artifacts and the runtime dependencies—and start testing immediately.

# E2E Tests Job configuration
needs: build
steps:
  - uses: actions/checkout@v3

  - name: Restore Build Artifacts
    uses: actions/cache@v3
    with:
      path: |
        apps/example-react-app/dist
        node_modules
      # Matching the key from the build job
      key: ${{ runner.os }}-build-${{ github.sha }}
      # Fail fast if the cache is missing, indicating an upstream failure
      fail-on-cache-miss: true

  - name: Run Playwright
    # Direct execution of tests without build overhead
    run: pnpm exec playwright test

Using fail-on-cache-miss: true is a good practice here. It ensures that if the artifact transfer fails, the job fails immediately rather than attempting to run tests against a non-existent build, providing clearer failure signals.

Wrapping up

Adopting this "Build Once, Consume Everywhere" pattern yields immediate benefits:

Cost savings: eliminating redundant build minutes directly reduces the billable time on GitHub Actions.
Determinism: every test job runs against the exact same binary artifacts, eliminating "flaky build" issues between parallel jobs.
Pipeline clarity: CI job logs are cleaner. Test jobs show only test output, making debugging significantly easier.

Building a faster CI pipeline is an iterative process and architectural changes like artifact caching often have highest impact on CI time and expense. By decoupling the build process from verification steps, you create a pipeline that is both faster and more reliable. We have seen upwards of 40% reduction in CI minutes in our client projects by sharing build artifacts between independent jobs, amongst other improvements.

For those looking to implement this in their own monorepos, the pattern is highly adaptable. I encourage you to audit your current workflows for redundant build steps, as it is often the lowest hanging fruit for CI optimisation.

Inclusive user testing with browser-based prototypes

Thu, 20 Mar 2025 00:00:00 GMT

At Thinkmill we care a lot about web accessibility and are lucky to have many accessibility experts on our team. This project provided a wonderful opportunity to deepen our accessibility understandings by designing and testing with Queenslanders who live with a disability, speak English as a second language, live in remote areas, or have varying levels of confidence in technology.

When we set out to design a site that is as inclusive as possible, I quickly realised that many of our go-to user testing tools — workshops, sticky notes, wireframes, Figma prototypes, and even Zoom calls — can unintentionally exclude people. So I had to adjust my design process to make the entire experience more accessible.

An accessible prototype

Before we started user testing we identified a series of questions our research should answer, such as:

“Can users achieve their goals on a website, or would a mobile app be better?”
“What accessibility features does the website need?”

Testing a prototype seemed like the best way to find out. But how do you create an accessible prototype?

The Swiss-Stack to the rescue

Thankfully, my teammates had already introduced me to a set of tools we have come to call the Swiss-Stack, which we affectionately named after Thinkmill alumni Simon Swiss.

The Swiss-Stack includes:

Astro: A powerful javascript framework used to build and deploy websites.
Tailwind: A popular and efficient tool for styling websites.
Keystatic: A lightweight, open-source content management system (developed by us).

After successfully using these tools to rebuild my personal website, I felt confident using them to create a prototype directly in the browser. Instead of testing pictures of a website in Figma, we would test an actual website experience in a real browser.

Designing and building the prototype

Our team mapped the user experience with wireframes and outlined the content structure with a data schema.

We used the Schema Nodes FigJam widget to create a diagram of the proposed data schema for the website.

I set up the schema in Keystatic, wrote some content, built the experience in Astro, and styled it to look like a wireframe with Tailwind. In just over a week, we had a low-fidelity, browser-based prototype ready for user testing.

The low-fidelity web prototype captured at the mobile (left) and desktop (right) breakpoints.

An accessible user testing environment

To capture feedback from a wide range of perspectives, we recruited a diverse group of Queenslanders — people with vision and hearing impairments, those who are non-verbal, neurodivergent, wheelchair users, and more.

We contacted participants in advance to understand their support needs and opted for one-on-one sessions, either in-person or over Zoom. The in-person sessions were held across four towns in accessible venues, and translators or support workers assisted when needed. Participants used their own devices, navigating the prototype with their assistive technologies and preferences.

Increasing prototype fidelity

We ran multiple rounds of testing. The initial low-fidelity prototype helped shape the project’s direction. Since the Queensland Government had a design system, we increased the design fidelity over time.

We used the same content model to render the website at two different levels of fidelity.

Astro made it easy to integrate the Queensland Government’s current and future design systems. We could quickly switch between different versions during testing, expanding the research to assess the accessibility of both systems and provide valuable feedback that could improve all Queensland Government websites which use the design systems.

For the high-fidelity round of testing, we were able to switch dynamically between the Queensland Government’s two design systems.

Concluding thoughts

Testing a browser-based prototype on a participant’s device was an invaluable method for obtaining rich, detailed feedback. If we had used a prototyping tool like Figma, the ability for our participants to engage meaningfully in testing would have been greatly diminished, and we would have missed out on many of the valuable insights we needed to design the right experience.

With a design system and open-source tools, browser-based prototypes can be a powerful, inclusive addition to the design process.

Progressive Web Apps (PWAs): A stepping stone towards a native mobile application

Fri, 16 Aug 2024 00:00:00 GMT

A Progressive Web App (PWA) is a type of web application, which means it’s accessible through a browser but can be installed onto the device to utilise modern web technologies to provide a rich and reliable experience. Features previously reserved for native mobile apps are now available to PWAs, including push notifications, offline functionality, and access to device features like the camera or GPS. This makes them a unique option for products or services looking to provide an amazing experience, without sacrificing the ease of access via the browser.

Because PWAs are an extension of an existing web application, they build off the same code, with a little bit of additional effort to take advantage of the native features of a device. Just like a website, they are accessible cross-device and cross-platform.

However, because they are still relatively unknown to users, the process of installing a PWA can be a hurdle. Though the power of PWAs has increased greatly over the last five years, this gap in understanding has had a substantial impact on their adoption.

History of PWAs

Progressive Web Apps have been around since 2015 and have been evolving ever since. In 2016, Google adapted PWAs as a new web development standard, including the ability to add an icon to the home screen, push notifications and background syncing. In 2017, Twitter/X launched its PWA, which loads faster than its native app and uses less data. With the release of Windows 10 in 2018, PWAs are now supported by Windows 10 devices. By 2019, Pinterest and Uber had both launched PWAs that showcased app-like experiences like real-time messaging and access to data offline. In 2021, Apple finally added support for PWAs in the Safari browser on iOS and macOS, allowing users to add them to their home screen and access them offline. Over this time, the user experience has become better and the gap between native mobile apps and PWAs has continuously closed.

State of PWAs

The term ‘Progressive Web App’, may not bring the smoothest of digital experiences to mind. However, as of 2024, PWAs have reached new levels of functionality and operating system support that means they can now be considered passable as native mobile applications. This is due to several key changes:

Hiding the URL bar

The URL bar is a telltale sign of a browser, and also breaks the immersive user experience by allowing the user to navigate away from your website. Hiding the URL bar is a simple feature that can be utilised to more closely mimic a native mobile application, and maintain the immersion of a PWA.

Screenshot of the X (Twitter) PWA with no URL bar visible

Retaining the sign-in

Historically, PWAs could not retain an account sign-in and a user would have to re-enter their details each time they launched the web app. As a poor user experience, this deterred many from using the PWA option. This has since been resolved, and a user’s sign-in remains when quitting and relaunching the PWA.

Easier installation

One of the main drawbacks of a PWA is that many users are not aware of their existence or how to install them. Web.dev have created a great development resource which details the recommended patterns for promoting a PWA, via placement of a straightforward ‘Install’ button. This button can be placed in a number of convenient locations such as on the landing screen, in the navigation menu, or at the completion of the user’s primary journey where they may be interested in coming back to the website. Pressing the ‘Install’ button will trigger the necessary modals for the user to confirm the installation, making this the most simple method for adding the PWA to the home screen of the mobile device.

‘Install’ button conveniently located in the navigation menu of a responsive mobile website.

Offline experience

Another difference in expectation from users between websites and mobile applications is support for an offline experience. When a website cannot connect to the internet, users are fine seeing nothing, however this is not the case for a mobile app. For many apps like Instagram or Facebook, when the device is unable to connect, cached data is displayed along with a connection error. Luckily, PWAs offer similar functionality where the offline experience can take advantage of caching and storage of data on the device to provide an experience when there is no connectivity.

Push notifications

As of Safari 16.4, Apple supports push notifications for PWAs. Push notifications are a powerful feature that enables PWAs to effectively communicate with users and provide real-time updates on their tasks and activities. Unlike traditional websites which often rely on email notifications, PWAs have the ability to leverage push notifications and thereby significantly enhance their usefulness. This recent decision from Apple improves the viability of PWAs cross-platform.

Splash screen

An often forgotten part of the mobile application experience is the presence of a splash screen which shows upon the tapping of the app’s icon on the home screen. When creating a PWA, developers are able to specify the splash screen behaviour to mimic a more native experience.

The X (Twitter) PWA’s splash screen experience.

Apple support on iOS

Finally, in February of 2024, Apple announced plans to remove the Home Screen web app capability for users in the European Union. After receiving pressure and feedback from developers and users alike, Apple reverted to its original stance of supporting Home Screen web apps in the EU. They emphasised that PWAs will be built directly on its WebKit browser engine, and align with the existing security and privacy models for native apps on iOS.

Making a responsive website into a PWA

One of the biggest benefits of PWAs is they can piggyback off the work already done for a responsive website. The steps involved with turning a responsive website into a PWA are minimal and include creating a manifest file which lets the browser know about your Progressive Web App, as well as some additional information about how it should behave when installed on a user’s device. The main components of a typical manifest file include the app name, the app icon, and the URL that should open when the app is launched.

{
  "name": "Example App",
  "short_name": "App",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "description": "An example of a Progressive Web App",
  "icons": [
    {
      "src": "icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "icon-256x256.png",
      "sizes": "256x256",
      "type": "image/png"
    },
    {
      "src": "icon-384x384.png",
      "sizes": "384x384",
      "type": "image/png"
    },
    {
      "src": "icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ],
}

From there, additional work to enable offline functionality and the caching of essential assets can be done to improve the feel of the PWA.

PWA vs. React Native vs. Native

Mobile phones offer a convenient and on-the-go experience for users. As user interaction on these devices continues to grow, it is important to provide a great mobile experience. However, it can be difficult to decide which avenue to take. There are three tiers of mobile experiences: Progressive Web Apps, React Native apps, and fully native apps.

	Progressive Web Apps	React Native Apps	Native Apps
Codebase	Uses the same code as a responsive website (HTML/CSS/Javascript).	Uses React Native which can be deployed across iOS and Android with minimal changes.	The codebase is specific to the operating system of the device, Java for Android and Swift for iOS.
Complexity of user interactions	Limited to user interactions available on the web, though these are getting more advanced each year.	Quite complex user interactions can be achieved, getting close to the fully native experience.	Provides the smoothest user experience and can handle the most complex user interactions.
Discoverability	Easy discovery for users through the web which can be accessed from any browser.	Users must download the app from the iOS or Android app store.	Users must download the app from the iOS or Android app store.
Updates	Updates are deployed to users immediately, same as a website.	Users must perform an app update.	Users must perform an app update.
Device feature integration	Progressive enhancement approach to feature detection. You should not expect your app to work the same way on every device. Good support for basic features via JavaScript APIs, but becomes more limited as you venture into hardware sensors and operating system features.	React Native offers a very similar level of integration to a truly native application. This comes at the expense of performance in more complex applications.	Highest level of integration with device features such as camera, GPS and fingerprint reader.
Security	Same security options as any web application. Must run under `https` to ensure a secure server/client connection.	Added benefit to include operating system/hardware security measures i.e biometric auth. Must pass the app store’s security standards before publication.	Added benefit to include operating system/hardware security measures i.e biometric auth. Must pass the app store’s security standards before publication.
Browser support	Not available on some browsers e.g. Firefox	Unrelated to the browser.	Unrelated to the browser.
Perceived trust	Less perceived trust from users.	Because these apps have to go through the app review process by iOS or Android, users tend to trust them more, especially for tasks that require higher-level of security like banking apps.	Because these apps have to go through the app review process by iOS or Android, users tend to trust them more, especially for tasks that require higher-level of security like banking apps.

One huge benefit of PWAs is that they leverage the investment made to build a mobile-responsive website. Building a robust and intuitive responsive website can be expensive, so adding PWA functionality can be a cost-effective option to provide a richer experience for early adopters.

Where do PWAs have a place?

All users have an existing mental model of how to access their digital products and services. Typically, this is done in one of two ways; via websites accessed through browsers such as Safari and Chrome, or via the icon of a mobile application which has been accessed through an app store and installed onto their device. Progressive Web Apps (PWAs) exist outside of this mental model, and although it is now simpler than ever to install a PWA onto a device, the process will be unfamiliar to most users. This is why it’s important to understand where PWAs sit within the mobile experience landscape and to have clarity on what offering this alternative will mean to users.

This group is less likely to mind the PWA installation process to enjoy a more app-like experience including an icon on their home screen for quick access to a web application they already navigate to often via their browser.

Additionally, building a native mobile application is more expensive, not just in terms of cost, but also because finding market fit is not usually a straightforward process. A PWA offers a unique solution for testing out ideas and integrating user feedback at a lower cost, making it a great stop-gap before moving to a more conventional application offering. This gives the team time to understand the problem space and the best way to direct development efforts.

Finally, because a PWA looks and feels so similar to a native mobile application, they are great at giving insight into what the future-state of the experience might look like. This makes them a powerful sales tool to help potential clients visualise where the product is headed, without having to invest in a separate native app up-front.

Conclusion

In conclusion, Progressive Web Apps have come a long way but still suffer from sitting outside the typical user’s mental model of how to access their digital products and services. However, in some select cases, they can be a practical way of leveraging the work done to build a mobile-responsive website to provide a more app-like experience for early adopters, until a native application can be built. Because they are easy to update and use the exact same codebase as the responsive website, they can empower teams to integrate user feedback quickly and find market fit. Additionally, they can be extremely effective as a low-cost sales tool to help visualise a future React Native or fully native mobile application.

Building a Multi Brand Design System with Tailwind: Tips, Tricks and Tradeoffs

Tue, 04 Jun 2024 00:00:00 GMT

Note: This article stems from a talk I gave at SydJS in 2024. This version has all the links and code snippets for you to follow along at home.

Why we chose Tailwind

As a consultant, one of my goals when helping clients build any product is to pick a set of tools that suit its specific needs. These need to fit the applications they’ll be used in and match the skills of the people who will maintain them after I leave. In this project, we aimed to create a design system that supports multiple brands for a team with developers of all skill levels.

After carefully considering several different styling solutions, we decided on Tailwind for a few key reasons:

Lowering the barrier to entry

For styling design systems, I usually reach for Emotion. It’s powerful, flexible, and battle-tested, allowing me to define CSS styles directly in the same file as my JSX. This co-location of markup, functionality, and styles also fits really well with React’s component model.

Still, Emotion on its own doesn’t really help when it comes to using design tokens, which is something you use a lot in a design system! Developers need to create their own system for using these tokens. Usually, you need to call a hook to get the theme out of context and map the token to the CSS property every time. Tailwind makes this a lot easier because you pull in your design tokens in the Tailwind config file and do the mapping upfront. Then you have classes made available to you with the tokens baked in. There’s also no runtime cost for this, which is another win.

Tailwind also simplifies complex tasks like responsive styles and state-based styling with its variants syntax. In other systems, writing what would otherwise be the same styles in different contexts can lead to a lot of extra code. With Tailwind, you can style states like :hover, :focus, :active, and :disabled, as well as responsive states, and more with a simple prefix to your class.

Customising app-specific components

Applications and design systems typically move at very different paces. With a design system, everything is slower and more deliberate. You’re working on components that will be used in multiple applications by different teams, considering factors like API design, accessibility, and bundle size (just to name a few). On the other hand, application development usually moves much faster, focusing on validating ideas and testing with users to ensure functionality and user satisfaction.

By using Tailwind, we have a great API for styling components consistently with the design system since most of Tailwind’s classes are based on your design tokens. This gives application developers the freedom to use other libraries that provide the functionality they need without being blocked by the design system team’s pace. This is crucial in the early stages of rolling out the design system when there aren’t as many components available.

This flexibility lets teams validate their ideas and get user feedback much earlier in the process. Once these custom components have proven effective, they can be refined, standardised, and incorporated back into the design system. This ensures that the design system evolves with real-world use cases, making it more robust and versatile while still supporting rapid prototyping in the browser.

Simplifying the technology stack

The company we were consulting for maintained an ecosystem of multiple websites and apps, using a variety of front-end technologies. Since they were already moving towards Tailwind elsewhere, consolidation on this choice for the design system was an added benefit.

Using Tailwind for styling in the design system reduced the need for extensive documentation. For example, if a developer had previous experience using Tailwind on one of the marketing sites, they would find it easy to adapt to styling components in the design system. This familiarity ensures they can quickly become productive and feel more at home in a new codebase.

Challenges of adopting Tailwind in a design system

Problem: Full class string must appear in markup

With CSS-in-JS libraries like Emotion, the CSS is generated at runtime, allowing for dynamic styles. You can use JavaScript libraries to do things like tint or shade colours, create complex responsive grid systems, and more.

Tailwind’s JIT compiler works differently. It scans all your template files for Tailwind classes to generate the required CSS, meaning the full class string needs to be present in the markup. Without it, your classes won’t produce the corresponding CSS.

To accommodate this limitation, you usually end up creating some pretty gnarly functions or lookup objects. In some cases, such as responsive props for layout components, there are just too many possible combinations for this to be a viable option.

Solution: Use classes instead of props for styling components

The solution is to do what we used to do — just use classes. This simplifies a lot of components since it offloads some of the work to the users. It doesn’t really degrade the developer experience either; it’s still fast and intuitive to style. If anything, it’s probably faster!

Problem: Loss of type safety and autocomplete

TypeScript provides valuable type safety and autocomplete, helping catch errors early and making refactoring much safer. With Tailwind, you lose some of these benefits. This can make it easier to overlook issues like typos in class names or classes that become invalid after making changes to your Tailwind config.

Solution (sort of): IntelliSense plugin

The IntelliSense plugin for VS Code helps mitigate this. It provides autocomplete, syntax highlighting, and linting for Tailwind classes. This means you can catch typos, see what each class does, and even get helpful hover previews showing the exact CSS that will be generated. While it doesn’t offer full type safety, it makes working with Tailwind much more manageable.

Problem: Overriding styles

With CSS-in-JS solutions like Emotion, overriding styles is easy because you’re working with objects and key/value pairs. To change the style, you can simply change the value of the CSS property. With Tailwind, you’re working with strings instead of objects, so you can’t just change a value directly. You might try using a different class that targets the same property, but there’s no guarantee the last class you apply will win, since specificity is based on the order of the classes in the stylesheet (which we don’t really control) and not the markup. Even if we did control the order of the classes, the point of Tailwind is that utility classes are as reusable as possible. Fixing a specificity issue in one place might break it in another, as you’re likely using the same class in multiple places.

Solution: Tailwind Merge

To handle style overrides in Tailwind, we use Tailwind Merge. This tool understands every Tailwind class and the properties they target. It checks for conflicts among the classes you provide and ensures that the correct styles are applied by removing conflicting classes and keeping the last one. This way, you can confidently override styles without manually managing conflicts.

Problem: One-off styles can’t be authored in the markup like your regular Tailwind classes

Every project has a few “one-off” styling exceptions that need special treatment. In earlier versions of Tailwind, handling these exceptions meant writing regular CSS elsewhere in your codebase, so your styles weren’t necessarily co-located with your markup anymore. Creating custom styles wasn’t easy and often required stepping outside the framework.

Solution: Arbitrary variants and arbitrary properties

Tailwind introduced arbitrary variants and arbitrary properties to address this issue. These features allow you to write custom styles directly in your markup using special syntax. This keeps your styles within the component, maintains the utility-first approach, and provides a flexible way to handle those unique styling needs without breaking the flow.

Even though the syntax might look a bit ugly, its distinctiveness is actually a benefit. It makes these classes easy to find and remove or replace if needed. By co-locating styles with your markup, you ensure that these custom styles can’t “leak out” of the component, keeping everything tidy and manageable.

Tailwind’s Evolution and Comparisons

As Tailwind has evolved, its utility has expanded across more projects. This evolution is similar to how GraphQL changed data querying in development.

Tailwind is like GraphQL for CSS

The JIT compiler and arbitrary values added in Tailwind 3 have broadened its practical use. As my boss Jed Watson aptly put it, “Tailwind is like GraphQL for CSS.”

In GraphQL, you have a schema, and in Tailwind, you have design tokens. GraphQL has a syntax to query for data, and in Tailwind, you query the JIT compiler for CSS by writing a class it recognises. Just like in GraphQL, where you never over-fetch data, in Tailwind, you only generate the CSS you need. This makes your styles more efficient and your development process more streamlined.

Getting the most out of Tailwind in your design system

Create a preset

Tailwind offers presets, which are pre-customised Tailwind configs. Using a preset simplifies setup and maintenance, as there’s less to change when updating core styles. By making the preset a function, you can pass in design tokens, meaning one preset can support multiple brands. This also cuts down on setup time and boilerplate code.

For example, here’s what the popular Tailwind-based component library shadcn/ui generates when you initialise a new project:

// tailwind.config.ts
import type { Config } from 'tailwindcss';

export default {
  darkMode: ['class'],
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    './node_modules/@acme-ds/core/dist/**/*.{js,ts,jsx,tsx}',
  ],
  prefix: '',
  theme: {
    container: {
      center: true,
      padding: '2rem',
      screens: {
        '2xl': '1400px',
      },
    },
    extend: {
      colors: {
        border: 'hsl(var(--border))',
        input: 'hsl(var(--input))',
        ring: 'hsl(var(--ring))',
        background: 'hsl(var(--background))',
        foreground: 'hsl(var(--foreground))',
        primary: {
          DEFAULT: 'hsl(var(--primary))',
          foreground: 'hsl(var(--primary-foreground))',
        },
        secondary: {
          DEFAULT: 'hsl(var(--secondary))',
          foreground: 'hsl(var(--secondary-foreground))',
        },
        destructive: {
          DEFAULT: 'hsl(var(--destructive))',
          foreground: 'hsl(var(--destructive-foreground))',
        },
        muted: {
          DEFAULT: 'hsl(var(--muted))',
          foreground: 'hsl(var(--muted-foreground))',
        },
        accent: {
          DEFAULT: 'hsl(var(--accent))',
          foreground: 'hsl(var(--accent-foreground))',
        },
        popover: {
          DEFAULT: 'hsl(var(--popover))',
          foreground: 'hsl(var(--popover-foreground))',
        },
        card: {
          DEFAULT: 'hsl(var(--card))',
          foreground: 'hsl(var(--card-foreground))',
        },
      },
      borderRadius: {
        lg: 'var(--radius)',
        md: 'calc(var(--radius) - 2px)',
        sm: 'calc(var(--radius) - 4px)',
      },
      keyframes: {
        'accordion-down': {
          from: { height: '0' },
          to: { height: 'var(--radix-accordion-content-height)' },
        },
        'accordion-up': {
          from: { height: 'var(--radix-accordion-content-height)' },
          to: { height: '0' },
        },
      },
      animation: {
        'accordion-down': 'accordion-down 0.2s ease-out',
        'accordion-up': 'accordion-up 0.2s ease-out',
      },
    },
  },
  plugins: [require('tailwindcss-animate')],
} satisfies Config;

/* tailwind.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

@layer base {
  :root {
    --background: 0 0% 100%;
    --foreground: 222.2 84% 4.9%;

    --card: 0 0% 100%;
    --card-foreground: 222.2 84% 4.9%;

    --popover: 0 0% 100%;
    --popover-foreground: 222.2 84% 4.9%;

    --primary: 222.2 47.4% 11.2%;
    --primary-foreground: 210 40% 98%;

    --secondary: 210 40% 96.1%;
    --secondary-foreground: 222.2 47.4% 11.2%;

    --muted: 210 40% 96.1%;
    --muted-foreground: 215.4 16.3% 46.9%;

    --accent: 210 40% 96.1%;
    --accent-foreground: 222.2 47.4% 11.2%;

    --destructive: 0 84.2% 60.2%;
    --destructive-foreground: 210 40% 98%;

    --border: 214.3 31.8% 91.4%;
    --input: 214.3 31.8% 91.4%;
    --ring: 222.2 84% 4.9%;

    --radius: 0.5rem;
  }

  .dark {
    --background: 222.2 84% 4.9%;
    --foreground: 210 40% 98%;

    --card: 222.2 84% 4.9%;
    --card-foreground: 210 40% 98%;

    --popover: 222.2 84% 4.9%;
    --popover-foreground: 210 40% 98%;

    --primary: 210 40% 98%;
    --primary-foreground: 222.2 47.4% 11.2%;

    --secondary: 217.2 32.6% 17.5%;
    --secondary-foreground: 210 40% 98%;

    --muted: 217.2 32.6% 17.5%;
    --muted-foreground: 215 20.2% 65.1%;

    --accent: 217.2 32.6% 17.5%;
    --accent-foreground: 210 40% 98%;

    --destructive: 0 62.8% 30.6%;
    --destructive-foreground: 210 40% 98%;

    --border: 217.2 32.6% 17.5%;
    --input: 217.2 32.6% 17.5%;
    --ring: 212.7 26.8% 83.9%;
  }
}

@layer base {
  * {
    @apply border-border;
  }
  body {
    @apply bg-background text-foreground;
  }
}

Compared to just this with our preset:

// tailwind.config.ts
import { tokens } from '@acme-ds/brands/my-brand';
import { createPreset } from '@acme-ds/core/tailwind';
import { type Config } from 'tailwindcss';

export default {
  content: [
    './node_modules/@acme-ds/core/src/**/*.{js,ts,jsx,tsx}',
    './src/**/*.{js,ts,jsx,tsx}',
  ],
  presets: [createPreset(tokens)],
} satisfies Config;

/* tailwind.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

Customising Tailwind’s default theme

Tailwind’s default theme is extensive but not overly opinionated. This is great for websites and small apps where getting started quickly is important, but for a design system, you’ll likely have strong opinions on things like colours and typography, so turning off many of Tailwind’s defaults is probably something you’ll want to do.

While Tailwind lets you disable built-in plugins using the corePlugins key, it’s best to avoid this. We wanted developers already familiar with Tailwind to use our design system without having to learn a bunch of new conventions, so keeping the same prefixes was important. Also, turning off core plugins means losing features like arbitrary variants.

Instead, the best thing to do is to remove the defaults from the theme object. If you create your preset function, you can even add flags to turn features on or off. This is useful if you want to incrementally add the design system to an app that’s already using Tailwind.

export function createPreset(
  tokens: Tokens,
  {
    shouldExcludeBaseStyles = false,
    shouldUseTailwindBorderRadius = false,
    shouldUseTailwindBoxShadows = false,
    shouldUseTailwindColors = false,
    shouldUseTailwindFontSize = false,
    shouldUseTailwindFontWeight = false,
  }: CreatePresetOptions = {}
): Config {
  return {
    content: [],
    theme: {
      ...defaultTheme,
      boxShadow: shouldUseTailwindBoxShadows ? defaultTheme.boxShadow : {},
      boxShadowColor: shouldUseTailwindBoxShadows ? defaultTheme.boxShadowColor : {},
      fontSize: shouldUseTailwindFontSize ? defaultTheme.fontSize : {},
      fontWeight: shouldUseTailwindFontWeight ? defaultTheme.fontWeight : {},
      ...getBorderRadiusThemeConfig(tokens, { shouldUseTailwindBorderRadius }),
      ...getColorThemeConfig({ shouldUseTailwindColors }),
    },
    plugins: [
      // ...
    ],
  };
}

Making the most of custom plugins

Tailwind plugins are a great way to add new styles. Don’t be afraid to reach for them when you need them. You even get IntelliSense for plugins you create, so the developer experience is still excellent.

Tailwind styles are split into base, component, and utility layers. In Tailwind, the base layer is for resets, global styles, and custom properties. The component layer targets multiple CSS properties, and the utility layer (with its higher specificity) overrides properties from the previous layers. Tailwind’s plugin function gives you a callback for adding styles to a layer, e.g. addComponents for the component layer.

Here are some examples of useful plugins we created:

Typography plugin

We created a typography plugin where we kept the familiar text- prefix, turned off Tailwind’s defaults, and set up styles for font-family, font-size, font-weight, line-height, and letter-spacing together, for both regular text and headings. This gave us a robust set of styles and reduced the need for a <Text> component.

export function createTypographyPlugin(typography: GlobalTokens["typography"]) {
  return plugin(({ addComponents, addUtilities }) => {
    const headingUtilities = Object.fromEntries(
      Object.entries(typography.heading).map(([key, value]) => [
        `.text-heading-${key}`,
        {
          fontFamily: [
            typography.fontFamily.heading,
            typography.fontFamily.fallback,
          ].join(", "),
          fontSize: value.fontSize,
          fontWeight: value.fontWeight,
          lineHeight: value.lineHeight,
          letterSpacing: value.letterSpacing,
        },
      ])
    );

    const bodyUtilities = Object.fromEntries(
      Object.entries(typography.body).map(([key, value]) => [
        `.text-body-${key}`,
        {
          fontFamily: [
            typography.fontFamily.body,
            typography.fontFamily.fallback,
          ].join(", "),
          fontSize: value.fontSize,
          fontWeight: value.fontWeight,
          lineHeight: value.lineHeight,
          letterSpacing: value.letterSpacing,
        },
      ])
    );

    addComponents({
      ...headingUtilities,
      ...bodyUtilities,
    });

    addUtilities({
      ".font-regular": {
        fontWeight: typography.fontWeight.regular,
      },
      ".font-strong": {
        fontWeight: typography.fontWeight.strong,
      },
      ".font-stronger": {
        fontWeight: typography.fontWeight.stronger,
      },
    });
  });
}

Tip: Use custom properties for font weights to style them differently between brands. For example, you might want bold headings in one brand and lighter headings in another.

Colour plugin

Next, we developed a colour plugin to manage colour schemes. By using custom properties for our colours, users don’t need to write any extra code to support switching between light and dark modes. We use both a prefers-color-scheme media query and .light/.dark classes so you can let users of your app manually set their preferred colour scheme or have it automatically switch based on system settings.

export function createColorPlugin(
  colorSchemes: Tokens['colorSchemes'],
  { shouldExcludeBaseStyles }: { shouldExcludeBaseStyles: boolean }
) {
  return plugin(({ addBase }) => {
    if (!shouldExcludeBaseStyles) {
      const colors = getColors(colorSchemes);
      addBase({
        ':root': {
          colorScheme: 'light dark',
          ...colors.light,
        },
        '@media (prefers-color-scheme: dark)': {
          ':root': {
            colorScheme: 'dark',
            ...colors.dark,
          },
        },
        '.light': {
          colorScheme: 'light',
          ...colors.light,
        },
        '.dark': {
          colorScheme: 'dark',
          ...colors.dark,
        },
      });
    }
  });
}

Tip: Set a color-scheme along with dark/light mode classes and media queries so browser chrome elements like scrollbars and native selects match your design.

Focus ring plugin

We also created a focus ring plugin to ensure consistent focus styles across our components. This is a component class since it targets lots of CSS properties. It handles different states and improves accessibility by providing clear visual feedback for focusable elements.

export const focusRingPlugin = plugin(({ addComponents, theme }) => {
  addComponents({
    '.focus-ring': {
      outline: 'none',
      '--tw-ring-color': theme('borderColor.focus'),
      '--tw-ring-offset-color': theme('backgroundColor.neutral'),
      '--tw-ring-offset-width': theme('ringWidth.1'),
      '--tw-ring-offset-shadow':
        '0 0 0 var(--tw-ring-offset-width) var(--tw-ring-offset-color)',
      '--tw-ring-shadow':
        '0 0 0 calc(2px + var(--tw-ring-offset-width)) var(--tw-ring-color)',
      'box-shadow':
        'var(--tw-ring-offset-shadow), var(--tw-ring-shadow), var(--tw-shadow, 0 0 rgb(0 0 0 / 0))',
      '@media (-ms-high-contrast: active), (forced-colors: active)': {
        'outline-color': theme('outlineColor.transparent'),
        'outline-offset': theme('outlineOffset.2'),
        'outline-style': 'solid',
        'outline-width': theme('outlineWidth.2'),
      },
    },

    '.no-focus-ring': {
      outline: 'revert',
      'box-shadow': 'revert',
      '@media (-ms-high-contrast: active), (forced-colors: active)': {
        'outline-color': 'revert',
        'outline-offset': 'revert',
        'outline-style': 'revert',
        'outline-width': 'revert',
      },
    },
  });
});

Tip: Creating the .focus-ring class with Tailwind’s plugin system means that it works for all valid Tailwind variants, e.g., using it with has-[:focus]: for a radio card.

Should you pick Tailwind for your design system?

Like anything in web development, the answer is “it depends.” The decision to use Tailwind should be based on your project’s specific needs and your team’s preferences and capabilities.

Reasons not to choose Tailwind

Lower type safety is a deal-breaker ❌
Long strings of classes make you feel physically ill 🤮
You’re aiming for a design system that enforces strict uniformity 📏
The black magic that Tailwind Merge must be doing to know what every class does terrifies you 🧙
You prefer using props over juggling classes 🎛

Reasons to choose Tailwind

Great documentation and a vast amount of online resources 📚
Fastest developer experience for building custom UI ⚡
Variants make it easy to reuse tokens 🔄
Arbitrary variants provide an escape hatch for one-off styles that don’t leak outside of your components 🛡
No runtime cost 💸 (unless you’re using Tailwind Merge)

Additional resources

When we started building this design system, there weren’t many projects using Tailwind for this kind of work that we could reference. That’s not the case anymore. If you’re considering building a design system using Tailwind, I’d highly recommend checking out the following:

Conclusion

Overall, using Tailwind on this project was a great experience, and I think it’s a solid choice for almost any application. It’s also proving to be a dominant force in the CSS framework space, and I’m confident it will remain that way for some time to come. With version 4 just around the corner, it’s only going to get better!

That said, alternatives like Emotion remain strong contenders. There are also a ton of great new libraries popping up all the time. Some promising options worth exploring include StyleX, Panda CSS, Tokenami, CSS-Hooks, and pigment-css. Each of these libraries brings its own unique features and philosophies to the table, potentially addressing specific pain points or aligning better with your team’s preferences.

If you’re considering using Tailwind for your design system, I hope this article has given you some valuable insights and tips to help you make the most of it.

Storybook and Mock APIs: A Powerful Prototyping Combo

Thu, 02 May 2024 00:00:00 GMT

You’re a Front-end Engineer tasked with implementing the UI for a killer new app feature. The design is solid, the data schema is ready to go, and everyone is excited to see the feature in action. There’s just one thing preventing you from fulfilling stakeholder dreams… the time it takes to develop the back-end of the API!

Sound familiar? There‘s a simple and effective way of getting around the API not being in place before UI development is complete… prototyping.

If you’re not familiar with the concept of prototyping in software development, it’s the process of creating an early model of a product or feature to test its design and functionality. Prototyping enables exploration and experimentation, highlights potential issues early, and is an incredible medium for communicating and presenting ideas to stakeholders.

In this tutorial we’ll be using Storybook and Mock Service Worker to create a prototype list of news articles for a React application that interfaces with a GraphQL API.

Storybook is a powerful tool for creating and testing UI components in isolation. It will help us focus on the building and iterating of individual components without having to worry about the larger context of the app.

Mock Service Worker is a library for mocking out a GraphQL API and testing app GraphQL queries and mutations in isolation. It is a powerful tool for enhancing prototypes, and will be especially useful in a scenario like this where we don’t have access to a deployed API.

Getting setup

Storybook needs to be installed in a project that is already setup with a framework, so before we dive into building our prototype we’ll want to spin up a new React project. We’ll be working from this Mantine Vite (Minimal) Template throughout this tutorial. So, grab a copy of the template and follow the steps below.

Want to dive straight into the complete code? Here’s some I prepared earlier!

Installing Storybook

First of all we’ll need to add Storybook to our project. Storybook provides a CLI allowing us to get setup with a single line command. From your project’s root directory run the following command in your terminal:

yarn dlx storybook@latest init

If all goes well, you should see a setup wizard that provides you with a short tour of Storybook’s main concepts and features.

The setup wizard will help you get started by introducing you to the main concepts and features of Storybook.

You’ll notice a couple of new folders in your project, .storybook and src/stories. .storybook is where Storybook’s configuration files are saved. src/stories contains some example component stories, which you can leave for reference when creating stories of your own or if you wish, delete this folder entirely.

Setup Mantine in Storybook

As we’re using the Mantine UI Component Library in our project, we’ll also need to setup Mantine in Storybook before creating our first story.

Install the Storybook add-on:

yarn add --dev storybook-dark-mode

Add storybook-dark-mode add-on to .storybook/main.ts:

import type { StorybookConfig } from '@storybook/react-vite';

import { join, dirname } from 'path';

/**
 * This function is used to resolve the absolute path of a package.
 * It is needed in projects that use Yarn PnP or are set up within a monorepo.
 */
function getAbsolutePath(value: string): any {
  return dirname(require.resolve(join(value, 'package.json')));
}

const config: StorybookConfig = {
  // ...config
  addons: [
    // ...addons
    getAbsolutePath('storybook-dark-mode'),
  ],
};

export default config;

Save the .storybook/preview.ts as .storybook/preview.tsx and replace the content with the following:

// Import styles of packages that you‘ve installed.
// All packages except `@mantine/hooks` require styles imports.
import '@mantine/core/styles.css';

import React, { useEffect } from 'react';
import { addons } from '@storybook/preview-api';
import { DARK_MODE_EVENT_NAME } from 'storybook-dark-mode';
import { MantineProvider, useMantineColorScheme } from '@mantine/core';

const channel = addons.getChannel();

function ColorSchemeWrapper({ children }: { children: React.ReactNode }) {
  const { setColorScheme } = useMantineColorScheme();
  const handleColorScheme = (value: boolean) =>
    setColorScheme(value ? 'dark' : 'light');

  useEffect(() => {
    channel.on(DARK_MODE_EVENT_NAME, handleColorScheme);
    return () => channel.off(DARK_MODE_EVENT_NAME, handleColorScheme);
  }, [channel]);

  return <>{children}</>;
}

export const decorators = [
  (renderStory: any) => (
    <ColorSchemeWrapper>{renderStory()}</ColorSchemeWrapper>
  ),
  (renderStory: any) => <MantineProvider>{renderStory()}</MantineProvider>,
];

Mock data

As we don’t have an API to fetch a list of news articles from as yet, we’ll create a “hard-coded” set of mock articles to represent the data we expect to receive from the API. Create a new file called src/mocks/articles.ts:

export const MOCK_ARTICLE_LIST_DATA = [
  {
    id: 1,
    date: '1st January 2024',
    slug: 'article-one',
    title: "Golf’s Worst Kept Secrets: Why We Really Wear Funny Pants",
    imageUrl:
      'https://images.unsplash.com/photo-1519682271141-57c25ad60410?crop=entropy&cs=tinysrgb&fit=crop&fm=jpg&h=540&ixid=MnwxfDB8MXxyYW5kb218MHwxMjAxNTQ0NXx8fHx8fHwxNzE0NjI4ODEy&ixlib=rb-4.0.3&q=80&w=720',
  },
  {
    id: 2,
    date: '10th February 2024',
    slug: 'article-two',
    title: 'Golf Cart Grand Prix: When Tee Time Turns into a Race',
    imageUrl:
      'https://images.unsplash.com/photo-1602991174407-a015b35a7b00?crop=entropy&cs=tinysrgb&fit=crop&fm=jpg&h=540&ixid=MnwxfDB8MXxyYW5kb218MHwxMjAxNTQ0NXx8fHx8fHwxNzE0NjI4ODUx&ixlib=rb-4.0.3&q=80&w=720',
  },
  {
    id: 3,
    date: '12th March 2024',
    slug: 'article-three',
    title:
      "Swing Like a Pro: How to Look Good Even When You’re Missing Every Shot",
    imageUrl:
      'https://images.unsplash.com/photo-1684144064253-bb3b4c8fc700?crop=entropy&cs=tinysrgb&fit=crop&fm=jpg&h=540&ixid=MnwxfDB8MXxyYW5kb218MHwxMjAxNTQ0NXx8fHx8fHwxNzE0NjI4ODEy&ixlib=rb-4.0.3&q=80&w=720',
  },
  // ...articles
]

Creating our component stories

Now that we have Storybook up and running in our React project along with some mock data, we can get into prototyping our news article components. We’re going to need a couple of UI components for our list of news articles: An ArticleCard to display a news articles overview, and an ArticleList to render our news articles in a grid.

src/components/ArticleCard.tsx

import { AspectRatio, Card, Image, Text } from '@mantine/core';

type Props = {
  slug: string;
  date: string;
  title: string;
  imageUrl: string;
};

export const ArticleCard = ({ slug, date, title, imageUrl }: Props) => {
  return (
    <Card p="md" radius="md" component="a" href={`#/articles/${slug}`}>
      <AspectRatio ratio={720 / 540}>
        <Image src={imageUrl} />
      </AspectRatio>
      <Text c="dimmed" size="xs" tt="uppercase" fw={700} mt="md">
        {date}
      </Text>
      <Text fw="bold" mt={5}>
        {title}
      </Text>
    </Card>
  );
};

src/components/ArticleList.tsx

import { Container, SimpleGrid } from '@mantine/core';

import { ArticleCard } from './ArticleCard';

type Props = {
  articles: {
    id: number;
    slug: string;
    date: string;
    title: string;
    imageUrl: string;
  }[];
};

export const ArticleList = ({ articles }: Props) => {
  return (
    <Container py="xl">
      <SimpleGrid cols={{ base: 1, sm: 2 }}>
        {articles.map((article) => (
          <ArticleCard key={article.id} {...article} />
        ))}
      </SimpleGrid>
    </Container>
  );
};

Alongside our ArticleCard and ArticleList components we now create a “story” file for each one like so:

src/components/ArticleCard.stories.tsx

import type { Meta, StoryObj } from '@storybook/react';

import { ArticleCard } from './ArticleCard';

const meta: Meta<typeof ArticleCard> = {
  component: ArticleCard,
};

export default meta;
type Story = StoryObj<typeof ArticleCard>;

export const Default: Story = {
  args: {
    date: '1st January 2024',
    slug: 'article-one',
    title: "Golf’s Worst Kept Secrets: Why We Really Wear Funny Pants",
    imageUrl:
      'https://images.unsplash.com/photo-1519682271141-57c25ad60410?crop=entropy&cs=tinysrgb&fit=crop&fm=jpg&h=540&ixid=MnwxfDB8MXxyYW5kb218MHwxMjAxNTQ0NXx8fHx8fHwxNzE0NjI4ODEy&ixlib=rb-4.0.3&q=80&w=720',
  },
  render: (args) => <ArticleCard {...args} />,
};

src/components/ArticleList.stories.tsx

import type { Meta, StoryObj } from '@storybook/react';

import { ArticleList } from './ArticleList';
import { MOCK_ARTICLE_LIST_DATA } from '../mocks/articles';

const meta: Meta<typeof ArticleList> = {
  component: ArticleList,
};

export default meta;
type Story = StoryObj<typeof ArticleList>;

export const Default: Story = {
  args: {
    articles: MOCK_ARTICLE_LIST_DATA,
  },
  render: (args) => <ArticleList {...args} />,
};

Now when we start up our Storybook using the yarn storybook command, we’ll be able to view and interact with our components.

ArticleList Storybook

Mocking the GraphQL API

Having our components available in Storybook provides an excellent way of testing, reviewing and iterating on them without having to integrate them into the application itself. We are however limited in our analysis of the components by the fact that they’re currently displaying hard-coded mock data. There’s no sense of what might happen if this data took a while to load, if the API was unable to return any data, or if the API returned an error. Let’s take a look at alleviating these shortfalls by setting up a Mock GraphQL API using Mock Service Worker and Apollo.

Installing Apollo Client

When interacting with a GraphQL API it can be beneficial to leverage the power of a state management library such as Apollo Client to help simplify the handling of remote and local data.

Install Apollo Client Dependencies

yarn add @apollo/client graphql

This will install the two dependencies required to use Apollo Client in our application: Apollo Client, which includes everything required to run itself; and GraphQL, which provides the logic required to parse GraphQL Queries and Mutations.

Add a Mock Apollo Client Provider

We’ll also need to setup an ApolloClient instance that we can use to interact with the Mock API we’re going to be creating shortly.

Inside our “mocks” folder, create a new file called src/mocks/MockApolloProvider.tsx

import { ApolloClient, InMemoryCache, ApolloProvider } from '@apollo/client';

type MockApolloProviderProps = {
  children: React.ReactElement;
};

const client = new ApolloClient({
  uri: '//fake.gql.server',
  cache: new InMemoryCache(),
  defaultOptions: {
    watchQuery: {
      fetchPolicy: 'no-cache',
      errorPolicy: 'all',
    },
    query: {
      fetchPolicy: 'no-cache',
      errorPolicy: 'all',
    },
  },
});

export const MockApolloProvider = ({ children }: MockApolloProviderProps) => {
  return <ApolloProvider client={client}>{children}</ApolloProvider>;
};

Install Mock Service Worker

Let’s go ahead and install Mock Service Worker into our project’s development dependencies:

yarn add --dev msw

Mock Service Worker is designed to intercept any client-side requests our application makes, and mock out a response. To enable this behaviour in the browser, we’ll need to create and register a service worker in our application. The great thing about the Mock Service Worker library is that we don’t actually have to write any code to create this worker ourselves, the library provides a CLI that generates a worker file into our application’s public directory, and registers it in our package.json:

yarn dlx msw init public/ --save

Mocking an API Request

Let’s say in our final application we’re expecting that a list of news articles will be populated by executing a GraphQL Query named GetNewsArticles. To enable the simulation of this query request and possible responses in Storybook, we’ll need to write a mock request handler, and resolver for the GetNewsArticles query.

Go ahead and create a new file src/mocks/handlers.ts with the following code:

import { graphql, HttpResponse } from 'msw'
import { MOCK_ARTICLE_LIST_DATA } from './articles';

export const handlers = [
  // Intercepts "GetNewsArticles" graphql query.
  graphql.query('GetNewsArticles', () => {
    return HttpResponse.json({
      data: {
        // Return MOCK_ARTICLE_LIST_DATA as the "articles" root-level property.
        articles: MOCK_ARTICLE_LIST_DATA,
      },
    });
  }),
];

Add Mock Service Worker & Apollo Client to Storybook

With our mocked request and response in place, we now need to configure Mock Service Worker to intercept any requests for GetNewsArticles made in Storybook and resolve them using our mocked handler. Storybook has a convenient add-on for Mock Service Worker that handles the configuration and initialisation of the service worker for us.

Install the storybook-msw-addon using the following command:

yarn add --dev storybook-msw-addon

And register storybook-msw-addon to ./storybook/main.ts

const config: StorybookConfig = {
  // ...config
  addons: [
    // ...addons
    getAbsolutePath('storybook-msw-addon'),
  ],
};

export default config;

Then update our ./storybook/preview.tsx to initiate the Mock Service Worker and include the mswLoader:

// ...imports
import { initialize, mswLoader} from 'storybook-msw-addon';

// initialise MSW addon.
initialize({
  onUnhandledRequest: 'bypass',
});


// provide the MSWloader globally.
export const loaders = [
  //...loaders
  mswLoader
];

After running yarn storybook and viewing the browser’s console you should see the message: [MSW] Mocking enabled. This indicates that the service worker is in place and listening for any requests to intercept.

Finally we must now wrap our stories with the MockApolloProvider, enabling our components to interact with the mock API. Add the following code to ./storybook/preview.tsx:

// ...imports
import { MockApolloProvider } from '../src/mocks/MockApolloProvider';

export const decorators = [
  // ...decorators
  (renderStory: any) => <MockApolloProvider>{renderStory()}</MockApolloProvider>
];

Using the Mock GraphQL API

With the setup behind us, all that’s left for us to do is configure the ArticleList component to make an API request to fetch the articles.

In GraphQL we describe our expected response in a query declaration. Let’s add a declaration to our src/components/ArticleList.tsx for the GetNewsArticles query:

import { gql } from '@apollo/client'

const GET_NEWS_ARTICLES = gql`
  query GetNewsArticles {
    articles {
      id
      date
      slug
      title
      imageUrl
    }
  }`;

Then we can use Apollo’s useQuery hook to execute the API request in src/components/ArticleList.tsx:

// ...imports
import { gql, useQuery } from '@apollo/client'
import { Container, SimpleGrid } from '@mantine/core';

import { ArticleCard } from './ArticleCard';

// ...GET_NEWS_ARTICLES

type Article = {
  id: number;
  slug: string;
  date: string;
  title: string;
  imageUrl: string;
};

export const ArticleList = () => {
  const { data, loading, error } = useQuery(GET_NEWS_ARTICLES);
  if (loading) return 'Loading...';
  if (error) return `Error! ${error.message}`;

  return (
    <Container py="xl">
      <SimpleGrid cols={{ base: 1, sm: 2 }}>
        {data.articles.map((article: Article) => (
          <ArticleCard key={article.id} {...article} />
        ))}
      </SimpleGrid>
    </Container>
  );
};

In the above example code, the useQuery hook is providing us with the returned data object, a loading boolean, and an error object. We’re then able to use these properties to conditionally render either a loading indicator, error notice, or the list of news articles.

We’ll also want to update our src/components/ArticleList.stories.tsx to reflect the above changes:

import type { Meta, StoryObj } from '@storybook/react';

import { handlers } from '../mocks/handlers';
import { ArticleList } from './ArticleList';

const meta: Meta<typeof ArticleList> = {
  component: ArticleList,
};

export default meta;
type Story = StoryObj<typeof ArticleList>;

export const Default: Story = {
  render: () => <ArticleList />,
};

Default.parameters = {
  msw: {
    handlers
  },
};

Note that we are now referencing the Mock Service Worker handlers. Fire up your Storybook and we should see something like this:

ArticleList component loading mock data in Storybook

And there we have it, a complete news article list that mimics the behaviour of a production ready component with no need for a deployed API to be in place. Of course we’ve only scratched the surface here of what’s possible when mocking out an API using Mock Service Worker. Why not go ahead and look at extending this example with more advanced GraphQL operations?

If you’re looking to get more from your prototyping efforts, we can help.

Building a Multi Brand Design System with Tailwind: Tips, Tricks and Tradeoffs

Wed, 01 May 2024 00:00:00 GMT

Note: This talk also comes in an article format where you’ll find links to resources and code examples you can try for yourself.

Unleashing Designers with Tailwind CSS

Fri, 12 Apr 2024 00:00:00 GMT

In April 2024, I flew to Park City, Utah, to give a talk at Epic Web Conf.

I, surprise surprise, did a talk on… Tailwind CSS.

This time around, I went for something a little different. I did not attempt to convince the audience that Tailwind is a good idea, and everyone should use it.

Instead, I explained how I personally think that Tailwind CSS is a design tool, and the ultimate "prototyping in the browser" solution — making it a great collaboration tool between designers and developers within a team.

You can watch the talk on the Epic Web platform.

Happy watching!

Design System kickoff checklist

Fri, 12 Apr 2024 00:00:00 GMT

We kicked off a new design system project this week. It provided a valuable opportunity to distil our thoughts and experiences around best practices for establishing a new project. We made ourselves a checklist of design system questions and tooling considerations which you may find helpful.

General questions

Below are some common questions to ask your project owner during kickoff. While some may seem obvious, it’s important to include them since the initial scramble can be chaotic and it’s easy to overlook things.

What are the stakeholder expectations?

As we’ve been making design systems a long time, it’s easy to presume what is expected of a design system, however the desired outcomes are likely nuanced. To avoid costly assumptions it’s good to scrutinise delivery expectations to distil the project’s scope. Discuss and document, at regular intervals, so that all relevant parties are aligned from the outset.

Who will use the design system?

While this might seem like a silly question, it’s vital that we understand who we’re building for. Consider the various disciplines that will use the design system e.g. designers, developers, content editors, product owners etc. and acknowledge that their expectations and competency will differ. Assuming too much about consumers risks alienating those who aren’t as familiar with design systems.

Where should we predominantly focus our time?

It’s often the case that more than one product will benefit from the design system. However, there’s typically one project that will be the “test-flight”. Make sure that the initial effort focuses almost exclusively on the requirements of that project. There’s no point spending time on e.g. a DatePicker when it won’t be necessary for 6 months.

Is there a requirement for language support i.e i18n?

Introducing support for localisation into a design system that’s in-flight is far more difficult than preparing for it from the start.

Is there a requirement for theme support? e.g. light/dark mode, multi-brand, etc.

If there’s even a hint that theme support will be required in the future, build support for it from the start. Trying to introduce theming later in the project is difficult.

What level of accessibility conformance is acceptable?

While we should strive for an inclusive web, the project’s needs and budget must be considered. Make sure stakeholders understand what is expected depending on their user requirements, and what is involved to meet those requirements.

Is there an existing system that must be extended?

Starting fresh will almost always be quicker and easier than updating existing systems. Somewhat counterintuitive, and difficult to sell to the project owner; modifying components etc., that are already in production adds a great deal of overhead to the build.

Is there an expectation that the design system will include a dedicated documentation website?

Building a documentation website is deceptively non-trivial. Where possible, avoid this investment until it’s warranted, Storybook is typically enough to begin building and sharing progress.

How much time should be invested building the thing VS defining a roadmap for next steps?

Ideally, depending on the length of the engagement, the implementation does most of the heavy lifting, laying foundational tooling and outlining best practices. Leaving breadcrumbs for other designers and developers to follow is more efficient than writing documents, but there’s definitely a balance to be struck.

Who, at Client Company, will be responsible for the design system?

This person should be a champion for the design system and promote adoption. Ideally they are competent in design and development, and capable of connecting the system with the teams and products that consume it. More people ≠ better outcomes: One person is capable of steering a ship, more than one increases the likelihood of indirection. We still want ambassadors to advocate for the design system, but a single person should be responsible for its direction.

Design system assets

What will be used for the assets below and where are the resources stored?

Iconography

Typically this will be a free and open-source library of SVG files. Though it could be a custom, in-house solution. Finding this out early will inform how you move forward with build steps etc., to keep design and development in sync.

Typography

Projects often require the use of one or more brand fonts. Make sure you see the license agreement: project owners sometimes assume that they have bought the font outright but in a lot of cases they only have a “desktop” license, not a web license. It’s our job to limit potential exposure for them.

Illustrations

These are often in-house designs, that compose SVG elements from open licensed libraries. Finding this out early will inform how you move forward with build steps etc., to keep design and development in sync.

Imagery

Ideally this can be avoided, better to inline SVGs where possible. When necessary, it’s important to make a plan for how images will be stored and served to the user.

Glossary

This one might seem out of place but it’s important to find or define as soon as possible. Every company uses their own jargon for miscellaneous terminology; when all parties are on the same page things move smoothly.

Design system tooling

Note: The design system tooling space moves fast. This list is representative at time of writing. Your mileage may vary down the track.

Baseline*

Project requirements and constraints will vary wildly but there’s a handful of tools that can hopefully* be assumed as a certainty.

Confirm the following with the project owner, and decide on versions where applicable:

Project dependent

While we all have preferences, many tools will be influenced by existing projects and the project owner’s familiarity + confidence.

The following list includes a handful of examples but is far from exhaustive. Choices here should be discussed with the owner to ensure that they fully understand the pros and cons of each decision with regard to their current and future requirements:

Styling
- Compiled, developed by Atlassian, is a styling solution designed to streamline the creation of consistent and maintainable UI components. It offers a declarative syntax for defining styles, enabling developers to encapsulate design decisions and enhance code reusability. Compiled prioritises performance and scalability, making it suitable for building large-scale applications with complex styling requirements.
- Emotion is popular in the React ecosystem, offering powerful features for styling components. It is a CSS-in-JS styling solution, allowing developers to write styles directly within their JavaScript code. Emotion emphasises flexibility, offering various utilities for managing styles, including theming, global styles, and dynamic styles based on component props.
- StyleX is a modern styling solution developed by Meta (formerly Facebook), optimised for building scalable and maintainable user interfaces. It introduces a new approach to styling components using JavaScript and CSS variables. With StyleX, developers can define styles programmatically and leverage composition to create reusable style components.
- Tailwind CSS is a utility-first CSS framework that provides a comprehensive set of pre-defined utility classes for building user interfaces. It emphasises simplicity and rapid development by enabling developers to apply styles directly to HTML elements. Tailwind’s utility-first approach facilitates quick prototyping and responsive design, offering a robust foundation for creating custom designs without the need for extensive CSS expertise.
- Vanilla Extract is a zero-runtime "stylesheets in TypeScript" solution that generates static CSS files at build time. It offers a type-safe approach to styling, enabling developers to write styles using familiar CSS syntax while leveraging the benefits of type checking. Vanilla Extract emphasizes performance and maintainability, producing optimized CSS output and enabling efficient caching and serving of stylesheets.
Framework
- Next.js is a mature web framework for building static and dynamic applications. Backed by Vercel.
- Remix is a full stack web framework that helps deliver a fast and resilient user experience. Backed by Shopify.
Package management
- npm or Node Package Manager, is a widely used JavaScript package manager integrated with Node.js. It offers a vast repository of open-source packages for developers and simplifies dependency management and project updates through its command-line interface.
- pnpm stands out with its symlink-based approach to dependency management, reducing disk space usage and speeding up installation times. It shares dependencies across projects, promoting resource efficiency without sacrificing project isolation.
- Yarn, developed by Facebook, Google, and others, prioritises performance, security, and consistency. It features fast dependency management, deterministic builds, and offline package installation, optimising development workflows and enabling developers to focus on coding.
Design tokens — assuming tokens will be stored and managed in Figma, you may want a tool to translate token data from one format to another.
- Diez (FOSS) is a design token framework focused on generating cross-platform design code using a single source of truth. It enables designers and developers to collaborate effectively by automatically synchronising design changes across multiple platforms, including iOS, Android, and web.
- Style Dictionary (FOSS), from Amazon, provides a flexible and customisable platform for managing design tokens and generating platform-specific output. It offers extensive configuration options and supports multiple platforms, making it suitable for large-scale design systems.
- Theo (FOSS), from SalesForce, facilitates the conversion of design tokens into various formats, such as JSON, SCSS, and CSS. It streamlines the process of maintaining design consistency across different platforms and environments.
- Specify (paid) is a design token engine designed to streamline the process of creating and managing design systems. It offers a user-friendly interface for defining and organising design tokens, allowing teams to efficiently generate platform-specific output for their projects.
- Supernova (paid) is a design system tool focused on bridging the gap between design and development workflows. It offers features such as automated code generation, version control, and integration with popular design tools, enabling teams to efficiently translate design decisions into production-ready code.
- ZeroHeight (paid) is a design system platform that centralises the documentation and distribution of design systems. It provides a collaborative space for designers and developers to create, organise, and share design tokens and components, ensuring consistency across projects.
Module bundler
- Parcel is a zero-config module bundler that simplifies the development process by automatically resolving dependencies and supporting various file formats out of the box. It offers fast and efficient builds with minimal configuration.
- Rollup is a module bundler known for its tree-shaking capabilities, which eliminate unused code to produce smaller bundles. It focuses on producing optimised output for libraries and packages, leveraging ES module syntax for efficient code splitting.
- Vite is a modern build tool that leverages native ES module imports to deliver lightning-fast development experiences. It offers instant server start times and supports hot module replacement, making it ideal for building Vue.js and React applications.
- Webpack is a powerful and highly configurable module bundler widely used in the JavaScript ecosystem. It offers extensive customisation options and supports a wide range of loaders and plugins for handling diverse project requirements, including code splitting, asset optimisation, and module bundling.
Component library
- React Aria Components is a robust and mature headless UI library from Adobe. Over 40 components with built-in behaviour, adaptive interactions, top-tier accessibility, and internationalisation out of the box.
- Radix UI is an open source component library optimised for fast development, easy maintenance, and accessibility.
- Ariakit is an unstyled open source library with a focus on accessibility and composability.
Testing
- Jest is the obvious candidate for a test runner, due to its wide usage, support for a variety of testing strategies, and ease of setup.
- Vitest is modern Jest-compatible test runner built on top of Vite with out-of-the-box support for ESM, TypeScript, and JSX.
- React Testing Library should be more than adequate for unit and integration tests. It encourages writing tests that focus on the behaviour of components from the user’s perspective, resulting in more robust and maintainable tests.
- Playwright tests are powerful but can be resource-intensive. They provide end-to-end testing capabilities, making them ideal for ensuring the functionality and usability of user journeys. However, due to their cost in terms of execution time and resources, we suggest limiting their usage to the most critical user journeys.
- Axe tests can be included with end-to-end tests to ensure user journeys contain no violations. Unit tests should cover discrete a11y support; they lack important context to be valuable candidates for Axe testing.

Got more questions about building your first design system? We can help.

Thinkmill turns 10

Thu, 07 Sep 2023 00:00:00 GMT

In September 2013, our Co-Founders Jed Watson and Boris Bozic officially registered Thinkmill’s ABN. From there, we begun our journey as a software consultancy powered by a skilled team of design-engineers, open-source enthusiasts, and problem-solvers. Today, we’re still that, with sharper tools and the same goal of building great software. Thank you to our team, friends, and clients who’ve been a part of our first decade. We naturally had cookies and cake to celebrate. Here’s to the next!

Designing at scale: an overview of Design Systems

Tue, 29 Aug 2023 00:00:00 GMT

Transcript

(00:22)

Awesome, thank you everyone for coming to my talk this evening. I’ll give a brief intro of myself first of all. My name’s Nathan, I’m a software developer at Thinkmill. I’m also an Orange local, I was born and raised here. I left in 2015 to study design at Western Sydney Uni and then I joined Thinkmill in 2018 as a junior designer and then moved into the development track from there. I’ve been working from home since March of 2020 and working from Orange since 2022 as well. We’re back to start a family and here’s that family: my wife Carrie, my four-month-old Sienna and my 15-month-old Winnie.

(01:07)

Thinkmill is a software development and design consultancy based in Sydney, we have 40 plus team members across Australia and New Zealand, founded in 2013. It’s actually our 10th anniversary next week. We’ve been recognised nationally for our open source contributions. We also run popular tech meetups like React Sydney, sponsor SydJS as well. We’re a lot of speakers at local and international events, such as this one. Lovely to be here, thank you for having me.

(01:38)

I’m going to be speaking today about designing applications with scale. We’re going to talk about what I do for work, an overview of design systems. So first, I want to solve the question: How do large organisations with multiple products — work done by several design and development teams — achieve consistency and a great user experience at scale? The answer is design systems.

A design system is a suite of design elements, guidelines, and standards that ensure visual and functional consistency in the creation of products or services. They’re used by product managers, designers, developers, writers, and managers to promote a unified and user-friendly experience across multiple touchpoints. At Thinkmill, we’ve worked on a bunch of design systems from startups to Atlassian, to the Australian government. We’ve led, shaped, and contributed to over a dozen design systems in our 10 years.

(02:30)

I’m going to be explaining design systems today while discussing what I’ve been working for the last two years at the Australian Department of Agriculture, Fisheries, and Forestry.

The export service is a digital transformation initiative designed to replace inefficient paper-based systems with digital apps to help Aussie producers sell to overseas markets.

Several teams were created to build various aspects of the export service, and it was imperative that measures were in place to ensure each piece of the experience was consistent and met accessibility targets.

These teams worked on various aspects of multiple different products designed for farmers and producers who are exporting goods overseas, whether it be food, grain, or animals. On-the-ground inspectors might visit the boats or the establishments to ensure that everything met standards and also to the internal staff who are processing the applications in the back end as well. To enable the development of all these products, we created AgDS or the Agriculture Design System.

(03:38)

Our design system is comprised of a few elements: the design language, the principles, and the guidelines of what it looks like to build something for this organisation; a library of components, templates, and patterns; and a community of users and contributors to the design system. I’ll go through each of these points.

First one is the design language. You may have an idea about what I mean by design language. I’ll throw up this slide. This is a brand-new design language. You probably know who this is already. I don’t even have to point out the logo mark in the bottom right corner for you to know that that is definitely Optus. This is the visual feel of the organisation. Design language can also be seen in product design as well. I just want to throw this up there because I’m a massive car guy, but basically, a design language can contain elements that are consistent across multiple product lines, including industrial designs such as the double kidney grill in a BMW. And design language can be seen in software as well.

(04:36)

I’ll take a tangent off Agriculture for a moment. This is some work that we worked on with Reckon. Reckon, a financial software company, based in Sydney. They’ve been around for a long time. They’ve been around since the days where you’d procure your accounting software, and it would arrive to you on a disk, and you’d install that onto your computer, and that was the computer with your accounting software on it, and you had to keep that very, very safe. Since then, the cloud has come in, they have cloud solutions, but they brought in Thinkmill.

We came in to help them form the new generation of their product lines – a suite of apps built for the mobile businesses of today. This is the App Store screenshots for the invoicing app, Reckon Invoices. You create your invoices, send to customers, receive payments, etc. We also built a payroll app, Reckon Payroll. You can set up your employees, you can pay them, you can track their leave, it’s got all the government reporting built in. There’s also a web experience as well (web and mobile).

Now, if you forget about the vibrant colour backgrounds, these apps are built using the same components, the same toolkit – all the buttons and the icons, the badges, the typography – they’re all from the same library. We also used the same library to build an employee experience. If an employer did a pay run, and paid your employees, the employee could open up their app, Reckon Mate, and they can see their payslips, they can do their expenses and see their leave entitlements, etc. We built the design language, a design system for Reckon, called Balance, an accounting pun for you, to enable the building of the mobile applications as well as the web apps as well.

(06:40)

Now, the design language for the Export Service is very pared back. It’s simple and easy to understand. That’s by design. It’s built for a variety of experience levels with computers, as well as for a variety of usability needs. I’ll talk a bit more about that after.

(07:00)

Part two – a design system includes a component library.

The component library is kind of like the lego blocks to make up an application. You can assemble them in a design tool or in code. These are generic components for building things like forms and content pages. They are built in Figma, which is the tool of choice for UI designers, and also in React, which is a user interface library for code in JavaScript. It’s built by Facebook actually, which means it’s the best thing to come out of Facebook.

A couple of practical examples of what implementing the components looks like. The developer would import this into their file. This is a button component. This button was designed with a few different variants. This is the primary button. It has an icon, it has a label. That’s probably the most simple version of a component we’ve got.

Here’s a slightly more complex version. Here’s a composition with a form stack, which ensures consistent spacing between each of the different elements. We have a text input with a few different props on that. We have a button group with a primary and a secondary button.

Up from the micro layer of the components, we also have a suite of templates as well. Here’s a multi-step form. If you’re registering for a business with the government, or if you’re processing an intent to export some livestock, you’ll probably see our multi-step form templates. We have a timeline of progress indicator on the left that shows you where you are in the process of building a form, and each of the pages are very simple. There’s only ever a couple of inputs on each page. And we have a suite of templates, some for forms, some for content pages.

We also are working on some for more dense dashboards for the internal staff who are reviewing the applications, etc. And then we have some design patterns as well.

So, what does it look like when a table is loading? If that was a gif, that’d be pulsing, but you get the idea. Or, what it looks like to filter data. So, we have a few patterns for table filtering as well.

(09:28)

Now, briefly on accessibility. Accessibility is something that’s really at the heart for not only Thinkmill, but also with the Department of Agriculture. You know, it’s not like, if your customer at Optus has a bad experience, they could like to go elsewhere. But unless you want to move the country, you don’t really have a choice of provider with the government. Typically when you’re interacting with the government, it’s always for something important. It’s something that you have to do. So, we want to make sure that people, no matter what their needs are, are able to achieve what they need to.

For instance, we’ve provided experiences or we’ve tested for people who have partial or full vision impairment, people who are colourblind or deaf, have a physical or motor skill impairment, cognitively divergent, or just have a different experience level with computers as well.

When we design anything, whether it be a component or a template, we ensure that screen readers can describe it clearly. Screen readers are software that’s built into your computer. You can turn it on if you have vision difficulties, and it will audibly describe what it’s seeing as you tab around the screen. We ensure that screen reader support is right up there. We ensure that we build everything with valid HTML, and we use the right properties to describe the elements as well. So, every element has correct colour contrast, anyone with low vision can discern text and foreground elements from backgrounds. And also, not using colour alone to convey meaning. If you imagine a red banner or a green banner to denote some sort of error state, we ensure that we use more than just colour because if you’re colourblind, you won’t be able to see the intent from that message.

One of the highlights of this project has been an accessibility audit. We engaged with a third-party consultant, Intopia. They’re an accessibility expert to audit our component library and also to enable user testing. We were able to observe people who were totally vision impaired or people who couldn’t use their arms at all and were actually looking at a camera and using facial expressions to move a cursor around. It was pretty amazing to see. We had that audit and we’re very proud that they noted us as an exemplary example of an accessible component library, which was great. With their other clients, they actually use us as an example, because it’s open source, they use us as an example to say, this is how you do it right with building for accessibility.

(12:28)

A design system includes a community of users.

Design systems are effectively products of their own, but they’re built to serve other products. Like any product, you want to understand your users’ needs and foster relationships with them. So, it’s important to create a dialogue with your users and get feedback or encourage contributions to the system. A good design team regularly engages in discussion with consumers to build a picture of their needs so they can be building valuable enhancements to the design system, creating value that way.

The individual product teams in the organisation could be siloed from each other, so they have their own backlogs, plans, goals for sprints or for quarters. What a design system does is it centralises design practices, enables collaboration, and overall raises the standard of design for the whole department.

A design system enables collaboration in a few ways. We have internal chat channels, so if people are having design problems they can get in contact with a designer or developer in the design system team to get feedback on how to solve design problems. We also have fortnightly shareback sessions called “guilds”. There’s Design Guild and Tech Guild, and people can share back what they’ve been working on. We also have design system office hours as well. Every week, there’ll be a session, people can just drop in to ask their design questions and drop out as they need. That’s been really valuable to build that community and get people excited about the design system and using it and get feedback that way.

(14:15)

Like I said before, a key part of the community-building aspect of the design system is the fact that it’s all open source. All the code for the component library and documentation site is all open source, it’s all published on GitHub, it’s all public access. That allows people to contribute to the design system, and it actually also enables other government departments to share their codes. We’ve had other government departments get in contact to use the design system as well.

Q: Are you telling me that I could go and regenerate an exactness like the Department of Agriculture website, the look, the feel, the design language, using all AGDS?

A: Yeah, in theory, depending on your skill level. But yes

Q: Let’s assume I’m extremely skilled. Surely there are intellectual property issues. The government would not police its entire IP for someone to create an incredible looking phishing site that looks just like the genuine. Isn’t there an issue there?

A: Short answer is no. I can try and answer that for you afterwards. Yeah, I’ve some [time for] questions at the end, but effectively, there’s no business domain logic in the design system, there’s nothing related to applications [with] important, sensitive information. There’s no data being stored in the design system. It’s purely the lego blocks used to assemble these websites. You can create a pretty credible-looking phishing scam without doing any of this as well.

(16:12)

With that, I might just show a quick demo of the documentation site. I’m just going to Google "Agriculture Design System" so you can play along at home. We got pretty good SEO as well, which we’re very proud of. Right, so this is the design system website. All of the internal teams use this.

As you’ve seen, it’s very accessible to get into it. A couple of notes that I’ll show you.

We have a schema of design tokens. For instance, how we use colour is very well thought out in the system. We describe what the text colours are and how they’re used. The different types of background colours. We don’t have red or green or blue. We have success, error and info because that denotes the intent of the colours and how they’re used in the system. This is always very fun to play with, there is a dark mode as well, and people really get excited by pressing stuff like that, usually.

Right, what else have I got there? You’ve seen the component library, so I’ll just show a page, if I can type, "page alert" as an example. Each of the components are thoroughly documented. We have do’s and don’ts on each of the components. We describe, for instance, the toned-alerts, when you should see something like this. Notice we have the different icons as well as talking about using colour alone before, so if you’re colourblind, you would see the difference between an error and a success state.

I won’t labor on this for too long but we do have, patterns for filtering, loading and empty states. There’s a gif I was promising here before. There are live examples as well, so they’re being rendered in this space and a developer could copy the code as well. Error states – we’ve thought about it and explained here, how to do those.

And there’s our suite of templates as well. So, yeah, feel free to take a look around it through that. You know how to Google it now. I’ll stop sharing. Now I’m back to my slides.

(19:40)

All right, quick word on who built the design system. The DS team, the A-Team, just not quite as jacked. A design system team requires a mix of unique skill sets. So, we have a product manager, we have interaction designers, front-end developers, and my personal favourite, design-engineers who kind of bridge both the design and the development space. We have a mix of full and part-time practitioners, so some people might be part-time on product teams as well. They fulfil a variety of responsibilities, like designing or building components, writing documentation, accessibility testing, providing design support, running the community engagement initiatives, surveying users for needs, or generally planning our sprints and running, the maintaining, the managing, a backlog of work.

(20:33)

All right, so I just wanted to end on some key success points. First of all, AGDS is already powering the export service portal. If you go to exports of agriculture, you actually see it being used in the real world. It’s also been used by other government partners around Australia as well, which is great. Home affairs, I believe, and the Northern Territory government also express interest as well.

We’ve also enabled collaboration across siloed teams, which we’re very proud of. A lot of teams who don’t have their own backlogs and planning and generally don’t talk to each other, the design system works to enable that collaboration.

We also enabled a departmental rebrand. So, interesting story, when the Labor government came into power, before the election, we were actually the Department of Agriculture, Water and the Environment; and then when Labor came in, we became Agriculture, Forestry, and Fisheries. And then there was Environment, they got split off. There was Department of Climate Change created as well. The teams that were already using the design system, that was just a software update, effectively, to ingest that new logo, and actually prompted other teams to start using the design system as well. So, that was good.

Like I said before, the biggest highlight for us was to have someone else, who is a real expert in the accessibility space, call us an exemplary accessible component library and they told all their friends about us.

All righty, that just about does it for me. Is there any other questions?

Audience Q&A

Q: Is it just a component library or is it built on a UI framework? Specifically, do you have support for flexbox or CSS grid to automatically resize? Now, I work with component libraries before, it’s just a library and you still need to go and use Bootstrap.

(22:42)

The primary touchpoint is the component library it’s built using React.js. It’s all CSS as well, so there’s flexbox and all those things that you mentioned as well, that’s all part of the system. But on top of that, there’s all the design principles, which I didn’t show in my demo, but we’ve got extensive documentation about what it looks like to build something with AGDS.

Q: I assume you have a core library and then you fork it or branch it for other clients, but do you keep that up to date and push revisions to change the core library?

(23:32)

A: Thinkmill doesn’t have a core library that all these other design systems are based off. They’re all independently built and ran. We actually make some open-source libraries that layers some of the foundation of them, but each of the libraries we’ve worked on, for the most part, independent of each other. We’ll share our ideas. A lot of the design systems we’ve worked on are open source. And the web development 10 years ago, it’s very different to what it is now. So, there’s always new things, and it would be more of a hindrance to have one central Thinkmill library that is always kept up to date. Frankly, we’re always fiddling with stuff, and we’re always wanting to try the new thing.

Q: Are these components just for web or mobile too?

(24:36)

A: In the case of Agriculture, there’s just web. For Reckon, which I spoke about before, there’s a core design language, of which we call Balance, and Balance has a React implementation as well as a React Native. Writing React Native is very similar to running regular React, but you run it through a different compiler, and it spits out an Android app and an iOS app.

Q: Have you done any design for wearables like an Apple Watch?

(25:11)

A: Not personally, but I think I’ve fiddled with a couple of apps just for fun before. Actually one of our guys, a couple weeks ago, was building a service that we use to basically build Lego characters inspired by each of the team members. And the website wasn’t very great. So he actually did a concept for building a new version where it was a 3D model in the browser. And it was like, what if I took that and put into the Apple Vision Pro headset and to Oculus, and he actually got a working prototype. We didn’t have the headset yet, but it was doing it in the simulator. Those libraries in the code were able to be shared between, web, iPhone, and VR systems.

Q: You were talking about the design language there. Is it actually is a language that helps to create the design elements that gets compiled down into other frameworks?

(26:20)

A: Essentially, yes. I didn’t labor on that part too much, but a really great thing about design systems is the shared handoff between designers and developers. What tends to happen without design systems is a designer will draw boxes and shapes, and developers have to translate that. As I showed a moment ago, the button with the variant primary and secondary, the same components effectively are built in Figma. A developer also calls that same thing a primary button as well. So, that makes the handoff a lot smoother.

Q: With Reckon, you created a language called Balance. Do you actually make a specific language for each product?

(27:12)

A: Not a coding language per se. The language is effectively what things are called. So, what do we call a badge or a button? It’s creating a shared vocabulary in all those elements between design and development. In terms of coding language, it’s all JavaScript, React and HTML.

Q: Can component libraries be integrated into online reporting and business analytics systems such as Power BI?

(28:30)

A: In theory, yes. That depends on the capabilities of things like Power BI. I have heard of people spending a bunch of time creating really nice Power BI dashboards. They’re not necessarily compatible with React, but they might be compatible with CSS and different styling frameworks as well.

Q: You mentioned Figma at the start. Assume you know that Adobe is buying them out, and that seems to be moving to two trains of thought - either Adobe is going to ruin the software, or pump it full of AI and all their own stuff. Any thoughts, concerns?

(29:42)

A: I guess when we originally read on the merger or the buyout, there were a few jokes like that being thrown around. I will say that recently, with the investment, they’ve developed a lot of really cool features like the design tokens. I don’t pay for the licenses, so I don’t think they’ve necessarily upped the price or anything like that yet or forced you to have a Creative Cloud subscription. I think if they did that, they would destroy their business and their customers, but so far, so good.

Q: Just in terms of the AI technology [...] what’s Thinkmill going to do in the future?

(31:18)

A: Thinkmill is really open-minded on AI. We have people that are experimenting with it, like what it could look like to integrate something like that into various products or systems, but nothing tangible at this point. We’re definitely remaining open-minded, and I’m sure we’ll have customers and clients who are interested in that space as well. That’s all I can say at this point.

Q: Around generative AI, you’ve already made a lot of these very deliberate design decisions about these components and you could feed that into AI and say, go and build me a website and that would go and automate something [...]

(32:10)

A: I guess I can say that the majority of problems that, as consultants, we’re there to solve most the time are more organisational or people problems than technology. Technology is certainly a factor of it, and there’s plenty of white label component libraries out there that people can adopt but rarely for large organisations. Those white label systems are great for startups or for getting something up and running, but for large organisations, typically, they need elements that are more opinionated, or templates that solve problems for their specific business needs. So we’re not too worried about our jobs at the moment.

Q: The components you shared with us are largely static. Do you have any more interactive ones like sliders and date pickers?

(33:15)

A: I can show you if you’d like. We have a date picker that when you click on the little icon, it has a little fly out. And there’s a calendar, accordions and modals as well. The accessibility challenges of modals in particular are really interesting and complex, and so we spend a bunch of time labouring over what an accessible implementation of a modal looks like.

Q: The experience on mobile is completely different because you can’t click, right?

(33:55)

A: There’s some components that, such as a tooltip, you hover over something, and then that a little fly out comes out. You can’t hover anything on a mobile device, so our design system team on top of building value and building components, you also need to have an idea of what not to do as well, and develop those design principles to inform direction.

Q: What trade-offs you’ve seen with having a design system [like a government service] that enables you to move to high fidelity so quickly?

(34:55)

A:There are certainly growing pains. I’ll answer the question I think you’re asking. Once you’ve got the critical mass of a design system and you’ve got templates that are tried and tested, then product teams are able to use those templates or contribute new ones. At the initial stage where you’re building a design system, you need to be informed by products and understand their needs to build something like that. If you’re building those things in parallel, there are trade-offs in terms of velocity to build and design something right, and making sure that it’s done in a systematic way rather than building a one-off prototype or a standalone product that doesn’t necessarily need a design system.

Q: In contrast, the trade-offs that I’ve seen is that going to high fidelity really quickly means that the feedback that you get, whether it’s from users or other stakeholders in your organisation, ends up just kind of fiddling around the edges. Where the feedback that you’re after, whether this is meeting the needs as opposed to does this look right, and the trade-offs around going to high fidelity very quickly, whether it’s stakeholders or customers, they quickly go to, does this look right, yes, or I’ll just kind of adjust things on the page a little bit, as opposed to thinking about, does this actually meet my needs? It’s an interesting challenge that the benefits that you have of being able to move to high fidelity quickly versus stripping that back and making sure that the service is actually as effective as it needs to be. Probably less of a question and more of a comment.

A: I guess our core clientele at the moment is large corporate entities that have a suite of existing products or existing systems as well. A lot of the time, you’re not just finding design and what looks right, but also, you know, we’ve got tech debt of a 30-year-old accounting software or something like that as well.

Q: Is it the staff at the Department of AG using your design system and building their pages, or does Thinkmill also do that?

(37:45)

A: In the case of AG, they are the staff of Agriculture, and Agriculture have a mix of contractors and full-time staff. But our work at Thinkmill is just on the design system front.

Q: Have you had any external contributors to your open-source repos yet?

(38:06)

A: We’ve had a lot of interest. The design language I was speaking about was actually very inspired by the former Australian government design system that was run by the DTA. That got defunded and turned to a community-driven model. It was also a 10-year-old tech stack so we wanted to take what that stood for – the design language, the thinking and the investment behind that – but re-implement it in modern React. We’ve had some really good feedback from people that used to work on that system as well.

Boris was a panellist at Design x Engineering Co-Lab

Tue, 15 Aug 2023 00:00:00 GMT

Our Co-CEO, Boris Bozic, was one of three expert panellists who spoke at the first Design x Engineering Co-Lab on Design Systems, in Sydney. We’re proud to have his serious design systems knowledge at the helm of our design-engineering practice. Thank you for the words of wisdom and experience shared by the other panellists Dominik Wilkowski and Maria Christley; and to Morgan Fletcher for MC-ing the event, and Atlassian for hosting us with an impressive pizza spread. We’ll be there for the next.

7 Things I Love About Keystatic — A Thread...

Fri, 23 Jun 2023 00:00:00 GMT

First of all, shoutout to the SydJS Meetup and Sharkie for hosting the event, and to Atlassian for providing the awesome venue!

You can also read the Twitter thread version of this post.

Over the past months, I’ve done a whole lot of exploration/prototyping with Keystatic. But I have also shipped real things.

Real production projects, with real clients. With real needs/shoulder tapping.

A few websites I built with Keystatic

One of these clients is... my wife Heather. She can literally shoulder tap 24/7 😅

My wife’s website, Star Athletics

These months of exploration and shipping stuff give me a well-deserved certification star ⭐️ to talk with "authority" about Keystatic, and what I really love about it.

Let’s dive in 🤗

#1 — Keystatic doesn’t really change how I would build websites for myself

After showing off my puppies in slow motion on the big screen, I presented my first key point I love about Keystatic: the fact that Keystatic doesn’t really change how I would build a website for myself.

I used this Tailwind UI component as an example:

The way I’d build this is exactly how the code is set up: a JavaScript array of objects to manage the "data" for each pricing plan:

That’s great and easy to edit for developers. But what if my non-technical friend wants to edit?

You could argue that it’s "not that hard" to edit strings inside a JS object.

And you’re right.

But there’s a lot of "baggage" that comes with it for non-technical folks:

open a JSX file in a code editor
push the code to GitHub

We take those things for granted.

To help my friend out, I will re-create the pricing plan data structure in a Keystatic schema.

I create a "pricing" singleton in the Keystatic config, and set the schema to mirror the shape of the pricing tiers.

With that config in place, I can tell my friend to visit the /keystatic route on the website. They’ll find a Pricing section where they can create some pricing tiers ✨

Data entry in the Keystatic Admin UI

And here’s what Keystatic outputs:

The generated JSON file

A pricing.json file inside src/content, just like we defined in our config.

This is pretty neat!

But my friend still needs to manually enter the pricing tiers... which already exist in code.

What if instead we made the existing tiers the thing that Keystatic can edit?

Keystatic now writes (but also reads!) from that "pricing.json" file. Let’s move our tiers in that file!

Porting the hardcoded JavaScript tiers array into our Keystatic-managed JSON file

And just like that, we made our hardcoded tiers array editable with Keystatic!

Our original pricing tiers now in Keystatic!

All the data shows up in the Admin UI, and my friend can start editing the plans, instead of creating them again from scratch.

Neat 🎉

Ok, so my friend did some changes. Renamed the "Basic" plan to "Keystatic", and added a feature item.

Before we can see this on the front end, we need to adjust our template code.

And it’s a very minimal change!

All we need to do is replace the hardcoded tiers array with the new tiers from the "pricing.json" file.

Minimal code change in our template

That’s it. Same variable name, so the rest of the code still works exactly the same way!

Now, if we visit our Pricing page once again, we can verify that the plans are indeed showing the changes made in Keystatic:

Our UI is updated ✨

All we did was create a schema mirroring the data shape, and import the JSON output in our page. That’s it.

We’ve made life infinitely better for our non-technical friends.

But as developers, we can still work the same way, and edit the JSON data manually. We don’t have to use the Admin UI.

It’s there for those who need it.

And that’s pretty cool 😎

#2 — The TypeScript self-documenting dev experience

When I learned Keystatic (very early days), there was absolutely no documentation.

Besides asking questions to the core team — and I sure did 😅 — my primary way to learn: autocomplete TypeScript discovery.

Autocomplete suggestions from Types

Here’s a video recording of creating a new schema in the Keystatic config. It almost feels like between GitHub Copilot and TypeScript, all I need to do to write a schema is hit one key and then press "tab tab tab" to let AI build my schema 🤣

TypeScript and GitHub Copilot doing all the work for me

Those Types also come handy when pulling content in the frontend!

#3 — Keystatic works well with the tool I already use and love.

So far, I built sites with Next.js and Astro. Keystatic’s flexibility makes it pair with those really nicely.

Let’s take the example of Astro. Astro has that built-in concept of "Content Collections". Essentially a "content" directory in your project, that will let you create "query-able" data collections:

It allows you to query data from files in your file system using built-in helpers:

---
import { getCollection } from 'astro:content'
const blogPosts = await getCollection('blog')
---

<ul>
  {blogPosts.map(post => <li>{post.title}</li>)}
</ul>

We had already built the Thinkmill website with Astro and Content Collections before thinking about bringing Keystatic into the picture. And so, we wanted to keep leveraging those content collections.

By setting the output "path" to "src/content/blog" in our Kesytatic config, we were able to do just that:

We did the same for authors, tags, etc:

And It Just Worked™

Out of the box.

🤯

And that’s probably the coolest thing about Keystatic:

It can meet you where you are.

Whatever way you’re building stuff — it find ways to adapt, and be helpful without getting in the way.

Keystatic actually does have its own powerful Reader API to query the file system... But it’s not needed here!

#4 — Keystatic travels light, doesn’t bring much "devOps baggage"

Traditionally, bringing content editing to a project means:

bringing a database
needing to maintain said database
refactoring a bunch of stuff

What about our Astro Content Collections? Most CMS won’t output their content inside the src/content/blog directory like we want.

You’ll have an API or ORM to hit to get your data. Which is fine, but it may be a departure from your existing setup.

Thanks to Keystatic’s flexibility, in my experience, you often don’t need to add that extra "baggage".

#5 — With Keystatic, you include non-technical folks within your developer-first workflow

You don’t invent/force a new system to allow content editing, and then force the dev team to use that new system.

You stay in your wheelhouse, and bring new folks along.

If you’re using MDX, you may assume that it’s fine for non-technical devs to edit MDX file.

It’s really not.

There’s a bunch of weirdness, module imports, bracket syntax, passing props etc.

Markdown could work with non-technical people, but MDX probably not.

So, if non-technical colleagues can’t do copy changes... instead they’ll do "change requests" tickets. In Notion, Jira, on your desk.

Post-It on your screen.

Weird feelings of "nagging" will creep in. Both ways.

Trust me, your non-technical colleagues don’t enjoy nagging you. They want autonomy!

Keystatic allows you to empower them to make these changes, without making sweeping changes to the way you work as a developer.

It makes your codebase more inclusive and accessible.

Is this... a11y? 😮🫱🦋

What do I mean by "bring non-technical folks in our dev-first workflow"?

Keystatic deeply integrates with GitHub. When a non-technical person edits content in Keystatic, they actually create a branch, make commits, open a PR, etc.

Deploy previews, CI pipeline, all of it ✨

Let’s take a fictive character for a non-technical person interacting with Keystatic.

We’ll call our character Sharkie.

Oh, hey @twalve 👋

Sharkie has a GitHub account with access to our repo, so they can "log in" and access the Admin UI.

GitHub login to access the Keystatic Admin UI

Keystatic lets you teach lightweight concepts about dev workflows — in an environment that feels comfortable for folks like Sharkie ❤️

Concept like branches.

I explain that instead of changing the live site (main branch), they should create a new "branch" (preview).

Watch video

After creating a new branch, Sharkie can create a new author, and write a blog post:

Watch video

After creating the author and the post, the UI shows two little 1️⃣ badges.

We, as developers, can read through this: The "demo-sharkie" branch is two commits ahead of main.

Sharkie doesn’t need to know this. The info here is:

Authors and Blog Popsts have both 1 new thing

I explain to Sharkie that to suggest adding those changes to the live site, they should "create a pull request".

This is how developers communicate intent to "pull" new code into a project.

Still a weird concept for non-devs, but at least wrapped in a non-intimidating UI ✨

Sharkie opens a pull request without needing to care about GIT stuff

The Pull Request video in the previous tweet is a great reminder that Keystatic is "just a wrapper" around GitHub workflows.

Without knowing it, Sharkie has created two Markdoc files with frontmatter metadata, and prepared those files into a PR.

Just as if it was done manually!

Who does the next step is up to you.

We can take over and handle the PR. But it’s a nice opportunity to teach a bit more about GitHub workflows to our friend Sharkie.

The reward? They can discover the world of deploy previews, GitHub Actions etc.

You can blow their mind with that 🤯

Triggering a deploy preview build

Not only does this make Sharkie more fluent with dev jargon — and a better communicator with dev teams...

It also gives them insights on where to find the preview URL. And also answer their "why are my changes not showing up immediately" question.

They see the build process 👀

When the site has finished deploying, Sharkie can visit the deploy preview:

Branch preview on Vercel

Knowing that this version of the site is not live, but they can see it and share it with the stakeholders, board of directors, their neighbour, or anyone...

... is fundamentally cool.

Look at Sharkie go...

Opening PRs and triggering Vercel deploys 👏👏👏

Note: Yes, Sharkie got a round of applause from the audience at that point of the talk. Well deserved!

#6 — Local mode is my JAM 🍯

As cool as that GitHub integration is… my JAM in Keystatic is local mode 👀

Think of it as a stripped-down, minimal, "power user" version of Keystatic.

No GitHub, no PRs.

Editing your file system directly.

Switching Keystatic to `local` mode

Minimal UI without GitHub context

Why do I love this?

The feedback loop (hot reload on changes) is much faster.

This is amazing for prototyping, and also teaching/demo-ing Keystatic 🔥

You’ll rarely catch me using Keystatic in another mode 😅

A great setup is to do local mode for dev, github mode for pro ⭐️

Here’s a demo of that immediate feedback loop I am talking about.

Edit content, and the UI is instantly updated:

Content editing DX with local mode

Remember: this is a two-way street: edit the code — and the UI is also immediately updated!

Instant update when editing the code as well!

#7 — Flexibility of config settings for file location, format

As we’ve seen, you can decide where you output any collection.

You can also choose where images go, independently of the collection settings.

Helps you fit framework-specific needs 👍

Path configuration

Image directory configuration

You can also pick between various format (YAML, JSON) for your data.

Format configuration

And choose if you want multiple files, or a single "Frontmatter + content" output, via the "contentField" option.

Keystatic collection multi-file output

contentField configuration

Single file output

Again, this lets you fit a wide range of scenarios!

Here’s a pretty advanced use-case, inside a monorepo

This is a prototype for the Earth Design System, for one of the clients we work with Thinkmill.

We use Keystatic to power the documentation of Design Systems components.

We want to collocate the docs with each component:

Earth Design System — Component documentation managed by Keystatic

Noticed the Button components inside the WYSIWYG document field in the previous video?

Yeah, those are the real buttons — not some screenshots or representations of the Buttons.

You can use React components as custom blocks inside the document editor.

Anyway — at the end of that video we set the path to packages/core/src/*/docs.

Let’s find why.

The * symbol is where the slug for each collection entry will go.

If you edit the Button docs page, it will go in packages/core/src/button/docs.

Here’s our project tree:

The monorepo project tree

See what happens?

From the Keystatic site, located in a very different place in the monorepo, we’re able to output the Keystatic-generated documentation for each component alongside the button source code, tests, stories...

How cool is that?!

Despite the fact that Keystatic and the UI components are in totally different folders, we retain this "two-way editing" experience.

Change code via code, or via the Admin UI. It hot reloads immediately either way.

🤯

Two-way editing within a monorepo

Single file output

#8 — The new Keystatic CLI 😻

Yes — I know the title says "7 Things".

But a new one came up recently, and it definitely belongs as the grand finale!

(That, plus I have 8 puppies — which makes this whole count increment decoration concept work great 😅)

Introducing... the new Keystatic CLI 🔥

It encapsulates all of the great little things I love about Keystatic:

lightweight, no "baggage", get started in seconds. It underlines and promotes the "two-way" editing experience

It is sweet as hell!

npm create @keystatic

This is definitely the recommended way to try Keystatic out.

You can try it right now!

It will spin up a brand new Next.js project with Keystatic setup in local mode.

We plan to support more frameworks (Astro, Remix, ...) or existing projects soon ✨

New Keystatic project from the CLI

The project it spins up is delightfully minimal:

Posts collection in Keystatic
homepage listing that one post
"single post" view to read the post

The code is simple enough to immediately grasp how to read/render Keystatic data with the built-in Reader & Renderer APIs 🔥

Reader API code snippet

Renderer API code snippet

As I mentioned, I like how the single post page invites you to think about this "two-way" editing.

Let’s try both — and see how fast the UI updates for us!

Two-way editing in the Keystatic CLI new project

Aaaannnd... that’s it!

I’ve got PLENTY more to say about Keystatic. So please, ask us anything, would love to hear your thoughts.

Check out Keystatic.com’s docs, try out the new CLI, and tell us what you think in the GitHub discussions.

Help us shape Keystatic ❤️

GitHub Discussions are a great place to get involved!

If you’ve made it to the end of this MEGA post...

... I’m impressed.

You’re a LEGEND.

To reward you, here’s a fairly cute "Thank You" slide I used last night to wrap up my talk 🤗

The cutest closing slide you will ever see 🤗

Seeya! ❤️

Accessibility at Thinkmill

Fri, 26 May 2023 00:00:00 GMT

This piece was written after a conversation with Matt Stow and Joss Mackison — two of Thinkmill’s most experienced engineers on the topic of accessibility.

At Thinkmill, we believe accessibility touches every facet of the design of web and mobile interfaces. By making websites and applications accessible, we can ensure all users are able to access the information and services they deserve. This includes, but is not limited to: people with colour blindness and/or vision impairments, cognitive and/or neurological impairments, and impaired motor function.

Building accessible products is a shared responsibility between our stakeholders, designers and developers. Because a good user experience benefits all users, its functionality and usability should take priority over how an interface looks. However, it can sometimes be tough to bring this perspective to clients. Still, we aim to champion accessibility within project teams, helping others to become comfortable using the tools and techniques needed to build accessible interfaces while also adopting an inclusive mindset. Check out our Accessibility page to learn how we help teams with this journey or continue reading for a quick rundown of some accessibility considerations.

Designing for assistive technologies

To design accessible experiences, we must be aware of the various input methods and assistive technologies available to our end users, such as mouth wands, eye-tracking software, screen readers, alternative keyboards, on-screen magnifiers and voice recognition. Where necessary, we’ll add (often invisible) affordances for users of assistive technologies as we know it will benefit all users, regardless of whether they have a permanent disability, a situational impairment or no restriction at all.

Many accessibility considerations relate to meeting users’ basic expectations, for example, using simple wording, ordering the interface in a logical way, highlighting where a user’s current focus is, using colour in a discernible manner, announcing additional context and sizing elements appropriately. We also strive to create lean applications since network accessibility and reliability can negatively affect accessibility and usability.

Style guides & design systems

Style guides are an excellent tool for upholding accessible designs and documenting patterns. A style guide can be abstracted into something functional, like a component library or design system that future projects can use to speed up development time and ensure consistent, accessible functionality throughout interfaces. Many accessibility considerations can be built into a component library and/or design system, including visual considerations (such as sufficient text contrast and indication of focus on interactive elements), screen reader considerations (such as the use of roles, states and landmarks), and physical considerations (such as ensuring an interface is keyboard navigable and sufficient hit area for click/press targets).

Web Content Accessibility Guidelines (WCAG)

At Thinkmill, we go beyond the WCAG 2.0 AA guidelines as a simple compliance checklist. We aim to understand how real-world users interact with our interfaces by utilising a range of accessibility tools and manual testing throughout development. Our designers and developers integrate plugins into their environments (like Figma and Storybook) and use browser extensions such as axe DevTools and WebAIM’s Wave Web Accessibility Evaluation Tool. However, automated tools generally find high-level accessibility issues only, so cross-platform, cross-browser manual testing is vital. We regularly test with screen readers such as JAWS, NVDA, VoiceOver, and TalkBack and work with accessibility consultants such as Intopia to ensure our interfaces meet our users’ needs.

Designing for different screen sizes

As a baseline, we ensure our products and services work across every screen size, from the smallest mobile to the largest desktop. We then optimise the experience based on the devices and screen sizes from which users will most likely access the application. We also group breakpoints into categories to ensure the experience is fluid and coherent between them, a feature important for users who move between devices and those who change their browser/device zoom level from the default.

Designing for native

Building accessible native mobile applications allows us to consider additional interactions to enhance the experience that aren’t readily available for web experiences. For example, we can take advantage of a swipe on the screen or the device’s physical volume controls to change a star rating component where appropriate. Of course, screen readers are heavily used by vision impaired mobile users, so we ensure they’re able to understand and navigate between all elements and screens.

Talk to us about accessibility

This post speaks to just a few areas to consider when designing an accessible product. By bringing empathy and care to product design and development, we can all benefit from better digital experiences. If you’d like to learn more about the importance of accessibility, reach out to Thinkmill today.

What we learned applying the Thinkmill Method to a complex accounting app

Thu, 25 May 2023 00:00:00 GMT

About the Thinkmill Method

If you haven’t heard of the Thinkmill Method, it’s a combination of principles, mindsets, and approaches to teamwork that we use to build what we call “good and compelling software”. We’ve spent over 10 years helping clients develop apps and platforms, and we’ve distilled our learnings and techniques into a practice that we can pull from and add to as we evolve. Learn more about the Thinkmill Method.

Project & team setup

The project was a four-month initiative to deliver a self-service feature that let accountants import legacy ledgers from their personal computers into our client’s new cloud-based application. We set out with the intention to collaborate around a functional prototype at the earliest opportunity and iterate on it over time; improving fidelity and functionality until it became complete. This approach represented a departure from some more established ways of working that relied on designing high-fidelity mockups in tools like Figma, and the sequential handing over of work from design to development.

Initially we set up the core team following the Thinkmill Method, with a Product owner, UX lead, Tech lead and Design-engineer all co-piloting the project with equal responsibility. However, due to shifting project priorities, we (the UX lead and Design-engineer) ended up becoming more responsible for guiding the project and making design decisions. Though this team structure wasn’t ideal, we were able to bring in the full team during key collaborative stages, allowing us to ensure all the questions and concerns were (mostly) covered.

This core squad was supported by a delivery squad consisting of additional designers and engineers who helped complete the work and bring it to production.

The team setup according to the Thinkmill Method vs what worked best for our team.

Our findings

Our journey to build a ledger feature through application of the Thinkmill Method gave us the following key insights:

Collaborating around the design in code helped us move fast and improved project visibility for stakeholders

We strive to keep design as close to the finished thing as early, and as much as possible. Our team was comfortable with this as a standing goal, and throughout the project we were able to do just that. This mostly looked like prioritising design effort towards working in the browser, instead of static tools like Figma. By working this way:

We reduced confusion related to what the source of truth was. (Hint…it was mostly the code).
Instead of spending time drawing high fidelityUI in Figma, we focused the conversation around the functional prototype. This meant more time improving upon the real thing so we could see results faster.
Our non-technical stakeholders had access to what was being built. Work-in-progress was not a black box, but something they could interact with, and generate informed opinions about along the way.
We let the code do more heavy lifting. We leaned into the Design System instead of creating throwaway components in Figma; pulling data from a mock API instead of spending time manually populating Figma assets with realistic data.

Cross-disciplinary collaboration can’t be assumed as a given, but your choice of tools can be transformational

Our team set out with the mutual agreement to work in an open and cross-disciplinary manner, but living up to our plan ended up being more difficult than we’d anticipated for. In the early phase of the project we found it hard (as consultants) to make an impact on what appeared to be a cultural preference for our client-colleagues to stay in their respective roles (preferring more siloed ways of working).

After finding that mutual intent wasn’t enough to get us where we wanted to be, we managed to find a breakthrough by co-designing the feature‘s user journey from beginning to end in a collaborative white-boarding tool.

Timelapse of the core team co-designing the user flow from a user experience, technical and business perspective.

As the process evolved we found that our team had a range of differing mental models around the what and how of the user journey. By documenting it as a cross-functional team, and working from an empty canvas, we were able to fast-track our shared understandings, check our assumptions, and bring one another into a deeper and more trusting engagement with the project. We came out of the journey-mapping exercise in a much better place, and working across roles and silos got progressively easier as time went on.

Even for an existing system, a schema-first approach can bring shared clarity

Even though we were working within a well established architecture, we still wanted to gain a deep understanding of the existing systems, processes, and user experiences that informed it. A schema-first approach helped us unravel the complexities of the current environment, and let the team connect to the user’s domain more comprehensively.

By employing a schema-first approach to this project we were able to:

Build and iterate quickly on the frontend. Having a schema made it possible to mock data and test the frontend with no dependency on a server-side API being ready. In simulating the behaviour and responses of a real server-side API, our mock API let the team interact with the data to understand how it would flow through the application, so they could make improvements along the way.
Speak the same language. By defining a schema we were able to establish a common vocabulary and reduce the likelihood of confusion arising as a result of team members using terms from their own disciplines to describe the same thing.
Surface data dependencies. Through the process of defining a schema, we were able to identify data dependencies and interactions that may have otherwise been obscured until later in the project. Determining how different entities rely on each other, and how changes to one entity may affect another, meant that we were making informed design decisions as a team.
Visualise the data structure. By presenting an object schema in a visual design tool, we were able to show team members and stakeholders how different entities within the system related to one another. This helped us see the system as a whole, rather than just individual components.

Object model diagram of the ledger product core entities and how they relate to one and another.

Produce documentation and reference artefacts. The process of defining and visualising the schema produced artefacts that also served as documentation materials for the import feature. These artefacts provided a comprehensive overview of the schema which team members could use to gain insights into the feature‘s structure and behaviour – even when working on different parts of the products.

The benefits of our schema-first approach were key to “winning-over” some team members who were accustomed to a code-first mindset, and gave them the courage and inspiration to opt for a better way of working in the future.

Conclusions

The Thinkmill Method is a useful way to work, and has the potential to create an environment where teams become more productive and empowered over time.

Every project brings its own unique challenges and team dynamics. Understanding how the method can and should adapt to meet those unique needs is just as valuable as possessing knowledge of the method‘s fundamentals.

Cultural habits can be hard to change within a short span of time, but moving towards more synchronous, trust-based, cross-functional ways of working always provides some degree of benefit.

The task of creating optimal conditions for fully empowered cross-functional teams is never ending! But that‘s a big part of what makes our work so fascinating.

Visualising a schema-led approach using FigJam

Wed, 24 May 2023 00:00:00 GMT

At Thinkmill, we believe in taking a schema-led approach to design. This approach involves building visual representations of data structures to help teams understand the underlying relationships and dependencies.

Recently, we applied this approach while working on a piece of accounting software. Our goal was to simplify and streamline the process of disbursing funds from a trust account to third-party creditors.

To achieve this, we needed the entire team to understand the underlying data structure and relationships. We decided to use fellow Thinkmiller @jordangeizer’s Schema Nodes FigJam Widget to visualise the GraphQL schema and establish a common vocabulary between team members.

Using the widget, we listed each entity and built out each data object with its respective type. We then highlighted any dependencies or relationships between them.

GraphQL Schema presented using Schema Nodes FigJam Widget

We also used the widget to identify any queries or mutations required, as well as their resulting data object.

GraphQL Operations presented using Schema Nodes FigJam Widget

A visual representation of the GraphQL schema, in a shareable format such as FigJam, is much more accessible to all team members than coding it up or scribbling it on a whiteboard.

This approach helped us establish a common vocabulary and shared understanding of the data structure among the team. By visualising the schema and relationships, we were able to simplify and streamline the process of disbursing funds from a trust account to third-party creditors.

If you’re interested in trying out a schema-led approach in your team, check out @jordangeizer’s Schema Nodes FigJam Widget here.

How we think about research at Thinkmill

Tue, 23 May 2023 00:00:00 GMT

Research at Thinkmill is actionable

The product development process is rarely a linear affair. With new problems and solutions being discovered each day, user research needs to be flexible and pragmatic to aid the creative process, rather than hinder it. That’s why at Thinkmill, we focus on research that delivers actionable insights – outcomes that can be directly and immediately translated into the project and across the team.

We focus on uncovering concrete improvements that will move the project forward today.

To ensure the research outcomes are actionable, there are few techniques we employ. We always use the current project context and timeline to develop a realistic research plan to ensure timely feedback. Because all our researchers are also practitioners, they understand the type of insights required to progress the project. Additionally, we involve engineers and leadership in the research sessions and playbacks so they can hear what real-world users have to say, deepening their empathy and understanding of the users’ needs, drivers and pain points. This first-hand experience also helps to ensure the research findings are taken onboard and have a meaningful impact within the organisation.

A typical research cycle

Though we will design each research plan to fit the context of the project, our typical research cycle normally includes the following steps:

Understanding the ask - Through discussion and conversation with project stakeholders, we uncover the questions we’re looking to answer through the research effort, as well as the level of clarity we need to get to.
Designing the research - Our research specialists decide on the best research methodologies and approach to answer the defined questions. The methodologies we specialise in can be found on our User Research page.
Defining participants - In collaboration with project stakeholders and subject-matter experts, we identify the types of participants who will best help us uncover the insights we seek, as well as whether an incentive will be provided. The metrics for defining the participants are based on the context of the research project and can include things like level of expertise, company size, familiarity with the product or service, etc. We then define a plan to recruit them.
Recruitment and set up - We create the parameters to recruit the desired participants and organise the recruitment through either third-party user research services, or the existing user base of the product or service. We also create any artefacts needed for the sessions based on the selected research methodologies and designed session structure.
Facilitate the sessions - Now it’s time to conduct the sessions with the recruited participants. We take detailed notes, and where permitted and appropriate, record the sessions. We encourage key stakeholders to attend sessions as a learning exercise and to increase the impact of the findings within the team.
Analyse to establish actionable insights - Our research specialists then synthesise the recordings and notes to uncover patterns and insights from the sessions. The findings come with actionable insights that teams can apply to the project immediately.
Document and playback - We also prepare the insights into a report that is presented back to the key stakeholders and the broader team. This document acts as a stand-alone report of the research findings which the team can refer to in the future.

Growing user research maturity

At Thinkmill we have experience working with organisations that are taking their first steps into research, as well as ones that are looking to build a permanent research capability within their team.

First steps into user research

When working with an organisation that is new to user research, our goal is to help build an understanding of the value of research within the team. Research can help to achieve the following:

Ensure the product or service meets users’ needs
De-risk projects by validating with real users
Provide guidance for product direction
Give confidence to project teams
Create alignment through research-backed data
Reduce prevalence of personal opinions and biases in product discussions
Establish a process that will enable future rounds of research
Present findings in a standalone report that can be referred to again and again

Building a culture of UX research

Once the initial value of user research has been accepted by the team, we can begin to embed it into the product development cycle, which means:

Small and iterative research cycles that guide product decisions
A culture of using research to answer product questions rather than relying on opinion
An understanding that a week of research upfront will save time and cost later in the project

Talk to us about user research

If the principles and methodology outlined here sounds like something that could benefit your project, have a chat with us today. We believe that user research can bring valuable insights to any stage of a project and are excited to work with teams who are ready to reach out to their user base and uncover how to improve their products.

Jordan Geizer has made another Figma plugin that’s near and dear to our heart.

Thu, 11 May 2023 00:00:00 GMT

Checkout Jordan‘s Schema Nodes plugin here.

We travelled to Chennai to present a progress update of the work we’re doing for the team at Anywhere Works

Mon, 01 May 2023 00:00:00 GMT

A group of Thinkmillers returned to Chennai to present a progress update of the work we’re doing for the team at Anywhere Works, and share our thoughts on effective cross–functional product design & development.

Meet Keystatic

Thu, 13 Apr 2023 00:00:00 GMT

For more information on Keystatic, checkout the website.

Accessibility in Design Systems

Thu, 13 Apr 2023 00:00:00 GMT

Read our case study to learn more about our our collaboration with the Australian Government’s Department of Agriculture, Fisheries & Forestry.

Transcript

(00:05)

Thank you. As Jed said, I’m from Queensland on the Sunshine Coast. This is actually my first React Sydney event ever. Thank you all for having me. Very exciting to be here tonight. I’m going to be talking about Accessibility and Design Systems, so let’s get into it. I’m Jordan, and I work at a company called Thinkmill. For the last year, I’ve been working with the Federal Australian Government’s Department of Agriculture, Fisheries, and Forestry on a new open-source design system. As it is open source, all the code is available to view on GitHub, and we publish everything into npm as well. So, I’ve put a little link there if anyone’s interested in checking that out.

At the end of last year, we undertook a big accessibility and usability audit which was facilitated by a company called Intopia. Tonight, we’ll talk about what the Agriculture Design System (AGDS) is, followed by a summary of the accessibility and usability audit last year. And finally, we’ll look at how our team approaches accessibility and usability at a design system level.

(01:15)

Let’s get into it by looking at what AGDS is. To give you some visual context, this is our Storybook kitchen sink example, essentially a dump of all our components in the system in no particular order. We’re using Storybook here because it’s a great tool for switching between our light and dark palettes. AGDS is also a themeable system. In this video right now, I’m switching between what we call the “Agriculture” theme (which is what we use in the department), and to what is known as the “Gold” theme (we’ll take a look at gold in just a minute).

As you can see one part of AGDS is a React component Library, but at a higher level it’s really a shared language between the design, development, and content practitioners at the department. As well as the components that you just saw we do have templates for common page compositions and patterns that exist in the department and for the designers we have a Figma library where all the components and tokens live.

(02:24)

In the video I demonstrated switching between the Agriculture theme and the Gold theme. A lot of you probably don’t know what Gold is so we’re going to look into that right now. Gold is an open-source design system for building government services and products. It’s designed to replace the former Australian government design system which was being funded by the DTA but unfortunately decommissioned in 2021.

Gold and AuDS have been widely used across many government products before: the Department of Health, the Department of Veterans Affairs, as well as the New South Wales government at some point have used Gold or AuDS before.

It’s no secret that Gold has been the inspiration for AGDS. We’ve really tried to take the aesthetic and design principles but extend that to meet the needs of the department. The main reason for that is because Gold did a really good job in terms of usability and accessibility, so a lot of research went into the development of Gold and we wanted to leverage as much of that as possible. But gold was built a long time ago and things move very quickly in Tech, so I like to think of AGDS as a modern interpretation of Gold. We’ve built everything from the ground up using React and TypeScript and all the styling is done with Emotion which is another Thinkmill package for CSS-inJS, and we have a bunch of really cool shiny toys for our monorepo setup and documentation site.

(04:05)

At a really high level this is the architecture of the design system. We have the components which are things that you typically think of when you think of a design system – things like a button, or accordion, or a select component. But really they are a composition of our primitive components: things like box and columns and text.

We expose these components to our consumers to also build components that we don’t have in the system. The cool thing with primitive components are they’re really flexible and they have style props which allow us to interact with our design tokens, so the values for a colour, typography, border, etc., we have a nice way of of referencing those values in React in a way that’s both type-safe and works in a responsive way as well.

(04:52)

As an example of that here’s our global alert component that typically sits at the top of the page, you can see it’s got a background colour with an icon and some typography. The code for this component is pretty simple, it’s just a composition of flex-box, an icon, and a couple of buttons in there as well. This syntax might look weird at first for people who aren’t familiar with this, but it is a really powerful and flexible way for handling styling in our design system. As I mentioned before it’s really good to be able to make sure everything’s mapped back to our tokens correctly.

(05:37)

Now, let’s get into the Accessibility audit. As mentioned, it was facilitated by a third-party company called Intopia. Neither the department nor Thinkmill has any affiliation with them whatsoever, and they did a fantastic job. The audit was split up into three phases. We did an audit of the components in isolation, followed by an audit of our page templates and documentation site, which is built using the design system components. Finally, we had some usability sessions. These sessions were with the users who had specific accessibility requirements: things like [requiring] a screen reader (we had some low vision users who needed screen magnification software), and neurodivergent users as well. Having Storybook for this phase was amazing because it does such a good job at being able to provide a playground for testing components in isolation. In this video, I’m just stepping through our text input component, seeing all the different variations that it can be in, and the auditors had a nice little playground down the bottom for changing all the props and performing their checks.

(06:46)

Phase one. What we were looking for here is making sure the components respond nicely to both screen-reader and keyboard input, making sure the components respond nicely when placed in Windows high contrast mode. When you zoom up all the way to 400%, make sure everything responds nicely. Of course, making sure that colors have sufficient contrast between background and foreground elements, and just making sure the HTML is valid. There were some cases where we were rendering a div instead of a span which yielded some HTML validation errors that can cause a lot of issues for screen readers. I’m pretty proud to say our team got an 80% pass for AA compliance before we did any remediation work.

A couple of issues that came out of this phase were things like a button loading state. What we were doing is we have a loading prop on the button, and when that’s true, we just overlay the text with some loading dots. But what we actually had to do was make sure there was our Aria-live region inside the button, and when the loading prop is true, we insert the text that we want to be announced to the screen reader, because simply just toggling the buttons on and off with the ternary operator wasn’t enough for some screen readers.

(08:11)

Things like Windows high contrast mode – our date range picker, the selected date range, you can’t see in Windows high contrast mode because we were relying on background colour alone. So what we had to do was make sure we put a font weight to indicate that as well as an outline on the selected dates. Here’s an example of content not reflowing when you zoom all the way to 400%. So we forgot to add some scrolling to our main nav component on the left here, so you couldn’t see the items that were cut off by your screen.

Then phase two, once we made all the fixes in that were caught there, we moved on to phase two where we audited the templates and documentation site.

(08:48)

Here’s an example of one of the templates we offer. It’s just a simple sign-in form. Although it is a really simple layout, it does a good job of demonstrating how different components can be composed together on a page. We have some skip links at the top of the page followed by main nav, followed by main content area, and a footer. Then we have a form with client-side validation. We have a button with a loading state to mimic an API call, and then we have an API response returning an error. We’re just testing here that our components fit nicely when placed together on a page and that we’re managing focus correctly as well. We did a pretty good job in that phase as well. We got an 86% pass for AA compliance [WCAG 2.1]. A lot of the issues that came out of this were on our documentation. We have a live code editor for some snippets, and there’s a couple of issues there with keyboard input.

(09:50)

Once that was done, we moved on to the usability sessions. What we were doing, we were observing users with specific accessibility requirements: screen readers, etc. What we asked them to do was register a pet for a fake government service we created. I’m just going to let this video play and talk a little bit about what’s going on. This is a form flow for registering a pet for a fake government service. The reason why we built this instead of using a product that exists in the department already, was that in order to use some of these products, you need quite specific domain knowledge in agriculture, which is really hard to recruit for. So what we decided to do was take the UI and UX patterns that exist in the department, which is taking these huge forms, hundreds of form fields long, and they get split up into multiple tasks, which then gets further split up into multiple sections. The user has stepped through that in a flow. We tried to mimic that as best as we could using something that a regular user could understand. Here, we’re just registering a fake pet.

(11:02)

The findings that came out of this were really fascinating. The screen reader users, they provided overall positive feedback. They were able to navigate around the page using shortcuts and interact with our components using keyboard inputs as expected. But the visual users were pretty confused by some elements on the page. They were confused by some icons looking like radio buttons or unclear with some copy that was on the page as well. So we knew we had to do some work for our visual users. Before we made any changes, here’s what one page in that form looked like, and here it is after. I’ll just quickly show before and after again. Some things to note, we added some colour and made the progress indicator (which is what you see on the left) to make it more look like a timeline of step test rather than just these individual tasks that can be completed in any order. Added some subheading above the progress indicator as well to make it more clear what step you’re on. We consulted with the content team to make our labels in that component as clear as possible. And finally, down the bottom here, this is our summary list component. We made sure that the key and the value were as close together as possible because a lot of users were confused. They weren’t sure that the key and the value were related. They were like, "Well, this one thing’s all the way over here, and this is over here." This was really interesting to me because it showed that accessibility does not mean usability. You can spend a lot of time making everything as accessible as possible, but as soon as you get it in front of your users, they might not understand what that means. It’s really important that usability sessions happen early.

(13:07)

At the end of this three-phase approach, Intopia gave the AGDS team a certificate of compliance, and they said, "Hey, you guys did a great job." Because it’s open source, we can now show any issues that come up in the future to potential future clients as well, saying, "Here’s how you can implement an accessible React-based design system in the future." So that was great, but that was no accident. There was a lot of hard work that went into making that possible. I wanted to share with you how we tackle that as a team.

(13:27)

Let’s get into it. I think the main reason for this is that we make accessibility a core pillar of AGDS. It’s really fundamental to everything that we do. Whenever a design decision is made or a code change is made, we’re asking ourselves, "Is this the most accessible thing we can do, or is there an alternative solution?" It does take a lot of time, but it is really fundamental to what we do, and we have that printed on our website, so it’s really easy to rationalise that. It is quite easy to justify this time spent in doing that because, yeah, it is a government service, and we are legally obliged to make it as accessible as possible. But I think for private companies who don’t have that same requirement, you still have to find a reason why accessibility is important to you and write that somewhere because if you don’t, it can very easily fall through the cracks.

(14:35)

Another thing we do is our way of working. We have a philosophy that design is everyone’s job, and by design, I don’t really mean jumping into Figma and changing border radii of components and things like that. I mean design as in the act of problem solving. Whenever a problem is brought to us, we jump on a call together and discuss what needs to be done (both engineers and designers). This gives everyone an opportunity to bring their areas of expertise in and just catch things early rather than a traditional software setup where you have designers in one room and developers in another room, and the developers just do whatever the designers say and slap some ARIA tags on the end and try to make it accessible. We try to do everything in a collaborative manner.

(15:32)

The other thing that we do is we try to get things into code as quickly as possible. While Figma is an awesome tool for coming up with ideas, and testing ideas quickly, it is just a picture at the end of the day (it’s not what the end user is going to see). Being able to get ideas into code quickly, testing with a screen reader, testing with a keyboard, seeing how it behaves in a real browser is amazing for us. That’s not just unique to our team; it’s just the standard way of working at Thinkmill. Boris and Jed have done a great job of publishing that on the Thinkmill website. If anyone is interested, there’s a link available.

(16:19)

Here’s a tool we use for prototyping in code. It’s called Playroom, it’s a website you can visit where you get a code editor at the bottom with all your components loaded in, providing autocomplete and snippets you can use. The top section shows a live demo of your code, and you can preview it in various screen sizes that you can configure. You can share that [demo] with your team as well - the URL syncs up with the code, making it easy to share around the team.

This an awesome tool for us to use internally (to be able to just jump into this write some code share it with the designers) but usually we have some designers or developers come to us and say “Hey like what’s the most accessible way to to do this or or do that” and it’s awesome just to jump on a call with them show them playroom do it together and then they can fix the problem in their code base. This has been an amazing tool for us.

(17:24)

Another thing we do is make sure to manually test in as many different browsers and assistive technologies as possible. I know as Engineers we love to automate as much as possible but unfortunately there are just so many issues that aren’t captured in automated testing. Gov.uk published an article saying that only something like 30% of accessibility issues can be captured with automated tests so there’s just no way around not doing manual testing. We try and do a bunch of different manual testing with every code change or design change.

I just wanted to give a shout out to this website called Assistiv Labs. It’s like Browser Stack but for screen readers so you can remotely log on test a website in NVDA, or Jaws, or voiceover, Windows high contrast as well, so that’s that’s a really great tool for testing.

(18:30)

And finally, having multiple respected accessibility references. Whenever you want to build something new it’s it’s good to reference someone has someone’s done it before. I always love to reference the Working Aria Initiative (WAI-ARIA) authoring practice guides. They have really clear guidance on how to implement modern components such as dialogue, sliders, carousels, or anything like that. But it is quite verbose, and the code is very outdated at times, so seeing how people tackle those issues in a more modern application like WK or Reach UI, React ARIA, Radix UI s is really useful as well.

To wrap up um I think accessibility needs to be made a priority not just a nice to have. Check out the Thinkmill Method because this method of working has a direct impact on the accessibility of an application. And finally, do not solely rely on automated testing – there’s there’s just no way around it yet.

Thank you so much. Any questions or otherwise I’ll leave it at that

[Applause].

Audience Q&A

Q: What are the most suitable methods for testing different screen resolutions across devices?

(19:53)

A: A bunch of different devices. A phone, iPad, a laptop, a smaller tablet as well. I try to do a bunch of Windows [testing] as well as Apple. I don’t think there’s like a silver bullet or anything just yet.

Q: Is the primary motivation of making AGDS open source for others outside government to use?

(20:22)

A: Mainly for other government departments to use as well that are not in the Department of Agriculture. The government are trying to work more in the open, but a lot of a lot of people don’t. Mainly to allow other government departments to pick it up in the future (hopefully as a Gold replacement one day potentially).

Q: What kind of tools can you use for testing Accessibility?

(21:10)

Good question. Engaging with a third-party accessibility company would be good because they can perform audits and give you that certificate of compliance. But if you’re just doing it on your own, you’re kind of just saying yeah like trust me in a way. You can use the WCAG guidelines as your Baseline, they they do have pretty clear guidance like saying this type of component needs to respond to these keyboard events, in order to do this pattern you need these elements, you can follow that but it is quite verbose.

What inspiration from React Aria, Radix UI, Radix Primitives, Reach UI were used to save development time?

(21:53)

We decided to try not to use any external libraries at first because we we were trying to be a Gold replacement at first (which had almost zero dependencies), but as the design system grew we needed a combobox component, so in that case we use uh Downshift. There’s like some things where we would save a lot of time by using like Radix or Reach UI but we didn’t want to be locked in to to their way of thinking. I think Reach UI is great but they just like got deprecated and don’t support React 18 which is like... oh man like if you’re relying on them what do you do?

Q: From a managing multiple design systems perspective with Gold and AGDS now. Do you think more departments will branch out and invest in their own design system?

(22:50)

I don’t think we’ve we’ve reached that bridge yet, but hopefully other departments can can take this as a starting point and extend it and change it to meet the needs of their department, because every department has quite specialised requirements. It is possible now for another department to pick it up and and theme it, but we haven’t seen that just yet.

Q: Why did you use Emotion, and did you evaluate anything else? What are your thoughts on CSS-in-JS?

(24:05)

Emotion is great for design systems right now. It doesn’t really require tooling so getting it into existing products that have ways of styling - we can incrementally adopt components without having to change too much. I know a lot of Thinkmill people are exploring Vanilla Extract and some other cool styling libraries but we’ve gone with the classic Emotion for now.

Integrating Keystatic with Astro’s Content Collections

Sun, 02 Apr 2023 00:00:00 GMT

Simon has a new video walking you through the process of implementing Keystatic to power parts of the site you’re on right now! Built with Astro, the Thinkmill website site leverages the power of two new features recently added to the framework: Markdoc, and Content Collections.

How a well thought out design system is turbocharging Keystatic development

Fri, 31 Mar 2023 00:00:00 GMT

Learn more about Keystatic here.

Route Map - a lightweight schema for defining a UX blueprint

Mon, 20 Mar 2023 00:00:00 GMT

Let’s talk process and methods.

We recently published our basic methodology for making good and compelling software, and alongside the principles, we have an extensive playbook/toolbox for tackling different kinds of problems when making software.

We’ll be publishing these as we go, but for today, here’s a quick look at one of these tools – a Route Map.

A Route Map is essentially a lightweight URL schema for an app or experience. We think of them like a UX blueprint.

An example to illustrate: say we sell a suite or products to professional service companies who themselves have clients – eg. law firms or similar. Consider the administration needs of this setup:

Account administration – management of the relationship between software provider and the prof. services company.
Org administration – management of organisation matters by eg staff members
Client experience – the app used by clients of the prof. services company.

First, we need to describe this conceptually – that is, what are the jobs that fall under each of these three top level concerns.

That’s useful ☝️ Now we can start to categorise related jobs and start inferring an IA and UX. But this conceptual view lacks opinions about UX, UI or technical design concerns.

So we can articulate this same thing in a route map to start to express some of these opinions – not to lock them in, but to facilitate the conversation and help make trade-offs between the UX / engineering / business perspective which are in a (hopefully healthy) tension.

A route map – a light-weight URL schema – is a bit special because it’s accessible enough to all practices in a cross functional team. To create it, we use a small set of basic concepts...

With that, we build up a picture that looks like this:

This is an example of a Route Map ☝️

Now we are beginning to express initial opinions about the UX and IA of this system.

We’re also starting to think about UI functionality by addressing CRUD patterns. Eg. we think a user should view a list of contacts on the Contacts page. And perform bulk actions on it in the same page. But should edit the details of the contact on a separate page.

The cross functional team can shape these opinions and iterate on it together, bringing in their respective perspectives.

Like most artefacts, a route map is a point-in-time artefact. It takes forward the shared understanding of a cross-functional team that is designing a new product or experience.

Related: @GiselleStidston wrote a piece on this topic titled All about artefacts. Worth a read.

A fleshed out route map becomes a UX blueprint for:

interface prototyping
app scaffolding and draft APIs
product and business stakeholders, who can more easily picture the product and refine the ambition and scope

Finally – why not just draw a typical IA diagram? You can if that’s your jam. Our view is that defining an IA is a process best informed by synthesising multiple takes on a problem – conceptual, route-based, flows, etc. But that’s another thread.

That’s all on Route Maps. Thanks for reading. We’re publishing our ways of working and how we build shared understanding in our Method page ✌️

Celebrating a decade of partnership with P.JOHNSON

Wed, 15 Mar 2023 00:00:00 GMT

This month, we celebrated P.Johnson being a Thinkmill client for 10+ years — and a true partner. Not only did our co-founder’s wedding see the groom and his groomsmen don P.Johnson suits, but we’re proud to have grown together with them over this decade of learning and progress. Here’s to the next decade of success (and weddings).

Project walkthrough: Agriculture Design System

Wed, 08 Mar 2023 00:00:00 GMT

Watch Jordan Overbye and Nathan Simpson outline the origins of our recent collaboration with the Australian Government’s Department of Agriculture, Fisheries & Forestry to implement a modern and accessible React Design System.

The $64,000 question to create more accessible and inclusive experiences

Fri, 03 Mar 2023 00:00:00 GMT

Catering to the needs of all your users can be difficult. However, as you design and build software, asking one straightforward question focused on blind screen reader users will help improve the experiences you create for all.

As you continue to ask this question, “accessibility” should become an opportunity for creating great experiences rather than a burden. You’ll learn which patterns to use or avoid, and reduce the anxiety felt should you need to “make things accessible” after the fact.

Okay, so what’s the question? Unashamedly, it’s surprisingly simple: If I couldn’t see the screen, how would I…?

Then, for every element and interaction in your interface, you’d expand on the question with one or more of the following:

If I couldn’t see the screen, how would I know what this is?
If I couldn’t see the screen, how would I know what this does?
If I couldn’t see the screen, how would I know what just happened?

In my experience, we ensure we design and build the right, most usable features by regularly asking these questions.

However, if you can’t answer a question easily or at all, something is amiss with your solution.

If you can’t answer a question in the design phase, you may need to re-think the user experience. If you can’t answer them during development, solutions may come from correctly using semantic HTML, applying necessary ARIA attributes, or managing a user’s focus.

If you still don’t have answers after making changes, your feature may be unfit for purpose and could unnecessarily exclude some users.

On the plus side, needing to redesign or rebuild the feature will often result in a better experience, which is the ultimate goal for our users.

Practising asking the questions

Let’s look at a standard pattern of navigation and wayfinding, and see how we would answer these questions.

Imagine this screenshot of browsing XYZ Corp’s website.

Mockup of a website Best Sellers page for XYZ corporation showing a list of product results.

Sighted users can see that they are currently on the Best Sellers page, and it has four additional navigation items. By clicking one of the other links, they would know they have navigated to a new page.

But as a blind screen reader user, how would they be informed of this? Let’s examine the code and explain how it answers the essential questions.

<title>Best Sellers - XYZ Corp</title>

…

<header>
  <a href="/">
    <img src="/images/logo.svg" alt="XYZ Corp" />
  </a>
  <nav aria-labelledby="main-navigation">
    <h2 id="main-navigation">Main navigation</h2>
    <ul>
      <li><a href="/">Home</a></li>
      <li><a aria-current="page" href="/best-sellers">Best Sellers</a></li>
      <li><a href="/new-arrivals">New Arrivals</a></li>
      <li><a href="/about-us">About Us</a></li>
      <li><a href="/contact-us">Contact Us</a></li>
    </ul>
  </nav>
</header>

…

<main aria-labelledby="main-heading" tabindex="-1">
  <h1 id="main-heading">Best Sellers</h1>
</main>

How does this implementation answer the $64,000 question?

We have a <title> element that is essential to providing a concise means of wayfinding. Not only can screen reader users choose to hear the title at any time, but average users also benefit by seeing this in their browser’s tabs UI. Notice how the site/company’s name comes last because it’s less important information as you browse the site. The critical part is the unique page name, which you want to see/hear first.

We also have a matching navigation link, which includes the aria-current="page" attribute. This announces that this link is the current page within the complete set of links, again reinforcing that we’re on Best Sellers.

Our URLs are also indicative of the page’s name. While not all devices and browsers expose them by default, a relevant, meaningful URL is yet another great indicator of where you are.

And finally, we have a single <h1> with matching content that’s associated with the <main> element using the aria-labelledby attribute. So regardless of whether a screen reader user navigated to the <h1> directly or via landmarks to the <main>, they would know that this page is about Best Sellers.

We have now answered the question: If I couldn’t see the screen, would I know what this (page) is?

What about the actual navigation?

The <nav> element describes that the links within it are for navigation. The <ul> and <li> elements will announce that the navigation is a list with a specific number of options, and of course, the <a> lets users know that these are links to another page.

Similar to the <main> element earlier, we add a visually hidden heading and associate that to the <nav> with an aria-labelledby attribute. This lets screen reader users quickly find the main navigation via headings or landmarks.

Here we’ve answered the first and second questions. If you couldn’t see the screen and were using a screen reader, you’d know exactly what the links are and what they do.

That leaves one final question for the navigation: If I couldn’t see the screen, how would I know what just happened?

If you’re building a traditional server or statically-rendered page, using <a> elements will automatically solve this for you. The browser will inform the screen reader to announce a navigation event, put the user’s focus at the root of the next page, and often start reading.

However, you may have additional work to do if the site/app’s navigation requires or is enhanced with client-side JavaScript.

At a minimum, you should add a visually hidden element that announces the route change by hooking into your route change’s success event, similar to:

<div role="alert">
  {routeHasChanged ? `Navigated to ${pageTitle} - XYZ Corp` : ''}
</div>

Because of the role="alert" attribute, a screen reader would immediately broadcast “Navigated to Best Sellers - XYZ Corp”, thus satisfying the question of knowing what just happened.

As with a traditional site, you should move the user’s focus to the first element on the page so they fully understand that a change has occurred, and can start navigating.

If you’re using Next.js, it has a similar feature out of the box, albeit not quite up to my standards for two reasons:

It doesn’t include the “Navigated to” prefix, thus making it slightly less contextually useful for users; and
The focus isn’t always set, so a screen reader user may sometimes be left on a phantom element, thus making their Previous and Next commands not behave as expected.

Alternatively, you could improve the experience further by focusing on the <main> element when navigating forward, so users are instantly taken to the new page’s content. When navigating back, automatically focusing on the element that caused the original route change would allow users to continue from where they left off.

Unfortunately, while I have previously implemented this behaviour in a custom Vue.js application, I haven’t found a similar drop-in solution for common React-based frameworks.

Hopefully, you can appreciate how much thinking goes into making a ubiquitous, seemingly simple pattern accessible to screen reader users and improving the UX for all users.

Questioning another pattern

With this awareness, imagine you continue developing XYZ Corp’s online store. You’re asked to implement a set of two icon buttons that change the search results to display as either a grid or list view, with grid selected by default. This pattern should be obvious for sighted users, but what other things should you consider?

Mockup of a website Best Sellers page for XYZ corporation with list/grid toggle buttons to alter the way Best Seller results are displayed.

You, of course, need to ask the $64,000 question.

In this context, you may take the questions and reframe them as: If I couldn’t see the screen:

How would I know what the buttons do?
How would I know when one is pressed?
How would I know that the results view has changed?

Happily, this pattern requires minimal effort:

<button
  aria-controls="results-view"
  aria-label="Display as grid view"
  aria-pressed="true"
  onClick="handleToggleResultsView"
>
  <svg aria-hidden="true" focusable="false" role="img">…</svg>
</button>

<button
  aria-controls="results-view"
  aria-label="Display as list view"
  aria-pressed="false"
  onClick="handleToggleResultsView"
>
  <svg aria-hidden="true" focusable="false" role="img">…</svg>
</button>

<div id="”results-view”">… list of results…</div>

By providing <button> elements whose aria-pressed attributes change appropriately in handleToggleResultsView, we create accessible toggle buttons that automatically indicate which is pressed. Of course, sighted users need to be made aware which is pressed by changing its appearance, and not just its colour.

The buttons use aria-label as a descriptive label for screen readers, and various attributes on the SVG to ensure they’re not accidentally reachable by screen readers and keyboard users of various devices and browsers.

The buttons also have an aria-controls attribute which points to the id of the element containing the results. While this attribute isn’t supported in all screen readers, it’s still worthwhile creating this explicit relationship between elements.

We’ve successfully answered the $64,000 question! A user will know what the buttons are, what they do and what happens when you press them.

Conclusion

Hopefully, I’ve demonstrated that by thinking about software in terms of how its elements and actions are conveyed, and not just by how it looks, you can create accessible and usable experiences for a much wider range of your user base.

Luckily, you don’t have to work out accessible solutions for many standard patterns, as there are well-tested and documented approaches in the ARIA Authoring Practices Guide and elsewhere.

However, sometimes the things you work on don’t have an agreed-upon, accessible solution. In these cases, ask yourself one question: If I couldn’t see the screen, how would I…?

Serverless website & booking system with Keystone, Planetscale, Vercel, & Next.js

Tue, 28 Feb 2023 00:00:00 GMT

Josh Calder has open-sourced a new website he built for his wife’s performing arts business. It lets students view a timetable, check fees, find available lesson times, and enrol through a portal. It combines Planetscale and Vercel to make for a fully “serverless” Keystone stack.

Shared understanding: why it’s important and how to fast-track it in your project

Thu, 23 Feb 2023 00:00:00 GMT

When it comes to building digital products and experiences, the amount of time it takes teams to find shared understanding can have a big impact on delivering outcomes.

This article explores how creating an environment where psychological safety and active learning are supported can help teams accelerate early alignment; leading to better outcomes, happier teams, and improved time-to-market. Included are tips and tricks to help you accelerate alignment within your own unique team and delivery context.

Shared understanding in a nutshell

You may have encountered the term shared understanding by other labels such as “unified mental model”, “hive mind”, or “collective intelligence”. From the perspective of shipping software, we see it as a product team having shared sense of:

What’s to be built.
How it relates to the business domain and users it’s in service to.
How and where the needs and constraints of the business, users, and the underlying tech are in conflict with one another (tradeoffs!).

Here’s a simplistic illustration of a how a team with no shared understandings might start out before a project kickoff:

This is an image

Here the needs and concerns of practitioners who are in service to Business, UX, and Tech exist apart from one another. This leaves room for gaps (in understanding, and execution) to manifest, which can negatively impact outcomes, team health, and perhaps even exacerbate feelings of isolation that team members might already be feeling.

Here’s those same three concerns operating when a critical mass of shared understanding has been reached. There are less gaps, and practitioners in any one of the three domains have greater overlap with the needs and constraints of that which exists outside their zone.

Why finding shared understanding early is important

If you’ve worked on dynamic cross-functional projects you might be thinking that shared understandings evolve throughout the entire project. In our experience, you’re 100% right! Understandings do need updating and re-qualification throughout. However, just because they change doesn’t mean that you can’t be more effective by striving for a “critical mass” of alignment early. Here’s a handful of reasons why:

You’re more likely to identify and close the big (and expensive to fix) gaps sooner.
Less gaps often increase the possibility of achieving better outcomes, and reducing time-to-market.
You’re more likely to develop actionable empathy for the needs and constraints of your cross-functional teammates.
Being more tuned-in to your colleagues means you’re less reliant on specification documents as everybody is in sync, and on the same page.
You’re more likely to enjoy the making process, which can increase employee retention and build a better organisational culture.

We’ve found that in order to fast-track the path to a unified mental image, a few things need to be in place:

Organisational and cultural support for engaging in active learning in the early stages of the project.
The ability for teams to self-select tools and processes that are inclusive and match the unique composition of their team.

Impediments to shared understanding, and how to overcome them

Here’s a list of obstacles you may encounter on your quest, and some suggestions for how to sidestep them:

Tricky terms and domain logic

Getting aligned can be tough if you don’t know exactly what it is that you’re talking about! Setting aside access to the right users and stakeholders for a moment – collaboratively building a dictionary of terms and core concepts can go a long way to improving alignment in the first weeks of your project.

A perceived need to demonstrate measurable progress early

Tech teams often experience pressure to appear as if they are being productive in easy-to-measure ways on day one. This pressure often manifests as rushing into code or wireframing. It can be a real dampener for reaching alignment, and often ends up manifesting as increased learning debt across the life of the project, inferior outcomes, and poor team health.

Talk to your teammates and superiors about the value of starting slow to go fast, avoid learning debt by making the practice of active learning visible early, and nudge your collaborators in the direction of making your alignment-generating efforts both valued and measurable. The cost of dealing with last-minute gaps can get a lot more expensive that the effort you put in here!

Existing predispositions towards siloed and linear ways of working

If you’re in a team dynamic where tasks are handed over the fence to you (waterfall model, we’re looking at you), it can be hard to find a holistic sense of what it is y’all are working on. Gaps arise, the blame game sets in, you may have experienced how the rest of that story goes...

Talk to one another, and talk often. Check out our thoughts on the value of working synchronously, and be sure to dive in to Shamsi Brinn’s excellent No-Handoff Manifesto.

A preference for sharing polished work over work-in-progress

You may practice your craft in an environment where formal, polished presentations are highly sought after. These certainly have their place. But if you’re not careful, overemphasising on bulletproof presentations can slow your journey to common ground.

Can you skip the prep time required to make polished thing, and instead opt for sharing your unvarnished work and thoughts in a quick huddle? It might just bring you closer to a solution and build more trust while you’re at it.

Confusing documentation with understanding

Our instinctive reaction to the knowledge gap is to seek more information. We confuse understanding with information.
Steven Bangay, Executing Strategy

Documentation can play an important role in how shared understanding is created within a team. However, there can be be subtle, yet meaningful differences between (a) documentation in service to advancing understandings, and (b) documentation in service to specification. The former can be very helpful for improving alignment (and these kinds of artifacts often lose relevance and value as shared understanding increases, while the latter is often better suited to situations where things are less likely to change.

If you’re reaching for a documentation effort – ask yourself which of the two outcomes you’re in service to. When your cause is in service to advancing understandings – use tools that are accessible to all disciplines in your team to find flow faster.

A lack of psychological safety

Many of us have struggled with imposter syndrome in some way, shape, or form. One could argue that it’s both a symptom of, and contributor to, all the preceding items in this list!

Creating a psychologically safe environment can take time and genuine effort. It’s hard to offer a prescription for achieving this within the bounds of this article; but if you’re able to make progress on some of the other obstacles throughout your next project – re-check your vibes at the end. You may just find that your team feels safer and more excited about what’s next. That’s a good sign that trust and safety are on the improve.

How to gauge the health of your team’s shared understanding

Every project brings its own unique variables to bear on what “enough shared understanding” might look and feel like. While there’s no one-size-fits-all solution to lean on, this doesn’t mean you can’t find your own way to confidence and consensus. Here’s some questions you might like to ask yourselves in order to evaluate the state of your team’s hive mind:

As a team:
- Are we confident that the most opaque parts of this project are sufficiently transparent from the perspective of all participants?
- Have we generated enough trust and safety to openly explore our thinking and work in the open from here on out?
- Will the mindshare we have empower us to work in a highly synchronous manner going forward?
- Are we aware of, and agreed upon, the key tradeoffs that are stake within the stated ambitions of the project?
As an individual:
- Do I know enough about the cross-functional needs and constraints of my colleagues such that my work will help (and not hinder) them in their goals?

If you’re interested to learn more about how we apply these principles at Thinkmill, checkout The Thinkmill Method. If you’re running a project and feel like you’d benefit from seeing this way of working applied in a more hands-on, context specific manner, we can augment your delivery team and help improve your delivery culture while we’re there. Get in touch to learn more.

Credits and recommended reading

The following resources have made a valuable contribution to the way we reason about effective collaboration within cross-functional software environments:

Shamsi Brinn’s No-handoff manifesto offers a way out of waterfall inspired our way of working.
Dr Cat Hicks’ research into the value active learning and psychological safety in developer teams is excellent reading.
John Cutler’s “Go slower to go fast” advocates for spending meaningful time on finding shared understanding in order to mitigate the many pitfalls of misaligned teams. His product-management substack is top-shelf.
Strategy boffin Steven Bungay has summarised his key thoughts on executing strategy which overlap with many of the pillars of cross-functional product development.

Keystatic is now in early access

Thu, 23 Feb 2023 00:00:00 GMT

For more information on Keystatic, checkout the website, and give us a star on GitHub.

Orienteering: A framing for software consultancy

Wed, 22 Feb 2023 00:00:00 GMT

Introduction

Whether you are just starting out on your consulting journey or have been away from the game for a while, the unpredictable nature of being a consultant can be a bit of a shock. We learn that product development is straightforward, that if we follow the steps we will deliver an amazing product - but this is simply not how things work in the real-world.

Orienteering aims to better align a consultant’s mindset with the real-world experience and evolve their way of thinking in a more sustainable way.

Why orienteering?

Orienteering is the process of navigating through unfamiliar terrain which is a useful way to think about consulting projects. Orienteers know the value of planning and are prepared to meet obstacles along the journey. Most of all, orienteers are adventurous, practical and inherently curious and this is the mindset that will both preserve the orienteer’s well-being and lead to a successful outcome. So grab a map and compass and get ready for an adventure!

The basics

Before the orienteer starts the adventure, it is important to know a bit about what is expected of them and the environment they are heading into. The basics cover the three main areas:

Role
Terrain
Experience

👤 Role

The role is the set of responsibilities that the orienteer is expected to fulfil. Often this can manifest as dual-responsibilities, with the internal role playing in concert with the external role.

Your internal role are the expectations of you from your consultancy’s perspective. This includes what your consultancy has been engaged to work on, your consultancy’s vision and overarching objectives, as well as evolving your own experience as an orienteer. Your internal role tends to stay constant throughout the adventure and can be used as a north star if your responsibilities become fuzzy.

At Thinkmill, consultants can play a different role from one project to another depending on the type of engagement that was agreed upon with the client. The engagement could be:
Augment - Become part of the client’s team and take direction from them.
Augment & Lead - Become a leader in the client’s team and take on responsibility for an initiative or area of work.
Outsource - Become part of a Thinkmill team working autonomously on the initiative.

Your external role are the expectations of you from the client’s perspective. This includes what the client believes they have engaged you on and the varying levels of understanding from your team members on the client side. Your external role tends to change as the adventure progresses and the orienteer should be ready to adapt as required.

Understanding your role will help to calibrate what is expected of you so you can perform accordingly, reducing friction between the team and your consultancy and have a better chance of a successful adventure.

⛰️ Terrain

The terrain describes the company environment the orienteer is dropped into. This means the way the company works and what they value, including accepted level of communication, inclination to collaboration and proficiency with the product development process. This is often referred to as company culture.

The terrain makes it easier or harder to reach your destination and depending on the environment, will require you to draw on a different mix of skills and tools. Harder terrains have a bigger impact on the wellbeing of orienteers, so newer orienteers should be paired with someone more experienced as a guide. The complexity of the company’s subject-matter adds another dimension to the terrain and orienteers should be prepared to spend ample time getting across complex subjects.

Each terrain falls into one of the following grades:

🟩 Grade 1 – A friendly, proficient and collaborative team with a high-level of communication and context sharing. Clearly defined goals, scope and timeline.
🟦 Grade 2 – A relatively collaborative and proficient team with adequate communication and context sharing. Goals, scope and timeline are defined but may be prone to changes.
🟥 Grade 3 – Some difficult members on the team that make communication and context sharing hard. General lack of confidence around the defined goals, scope and timeline.
⬛ Grade 4 – A potentially unskilled team that does not want to cooperate and has very little communication or context sharing. Poorly defined goals, scope or timeline.

At Thinkmill, we have experienced all grades of terrain. In practice, a Grade 1 terrain may be the result of a well-timed engagement with a client who is ready to do great work us. The team has been prepped for collaboration and the expectations are clear.
A Grade 4 terrain may be the result of a client who has initiated the engagement at the wrong time and didn’t get buy-in internally. This could lead to stakeholders who feel threatened by the consultant and are unwilling to cooperate, creating roadblocks either actively or due to inaction.

⭐ Experience

The more adventures the orienteer completes, the more experience they gain with tackling different terrains and applying their skills. Experience allows an orienteer to more quickly predict or identify obstacles and expertly apply the appropriate tools to guide the team successfully. Therefore it’s important for orienteers to view each adventure as an opportunity to learn, experiment and develop their craft. This is the secret to sustainable consulting and embracing this mindset will serve the orienteer time and time again.

Stages of the adventure

Author’s depiction of the stages of the adventure.

Once the orienteer is across the basics, they can start their adventure! The adventure is broken up into three distinct stages:

The drop-in
The journey
The destination

🪂 The drop-in

The drop-in is the point where the orienteer starts their adventure, noting that the rest of the team may have already begun. The orienteer can expect to spend a period of time getting across the context, subject-matter and processes that the internal team members may already understand.

If you find yourself in a Grade 3 or Grade 4 terrain, the drop-in can feel a bit like groping around in the dark. This is to be expected and let’s just say it’s hard to stick the landing at night. Experience with getting your bearings will help in these situations.

Getting your bearings

Getting your bearings is the process of figuring out which direction to take the project first. This means determining:

Who is involved
Where work takes place
What work has already been done
What are the expectations
What is the desired destination

This process separates the drop-in stage from the journey stage and orienteers should ensure the above questions have been answered before they take their first steps. You want to be sure your chosen route isn’t taking you towards a cliff!

At Thinkmill, we also call this step the reverse brief. Once the project has kicked off, we often find that the work initially scoped is a little different to the work required. This may be because the person involved in defining the engagement doesn’t have enough context to properly explain the brief, or it may be because we’ve seen this situation before and know how we can be most effective.
Either way, playing our answers to the above questions back to the client is a great way to ensure everyone is on the same page and set the project up for success.

🏃‍♀️ The journey

Once the orienteer is confident in which direction to head, they can take their first step. The journey represents the work the orienteer does to progress the project, applying their expertise as required and working with the team to move towards the destination.

Expect the unexpected

One thing every orienteer should expect to encounter is obstacles. Even if the terrain seems familiar, the conditions are always different and things don’t go according to plan. Bringing a sense of adventure and curiosity will go a long way in staying resilient in the face of the unexpected.

Share the load

Though each team member usually has their own responsibilities, seeking feedback from others can ensure that blind spots are covered and obstacles are identified ahead of time. The most robust ideas always come through brainstorming with others.

At Thinkmill, we love to collaborate and test the strength of our ideas in a process we call Sparring. It can be a bit daunting to share evolving concepts with team mates, but this process always results in a better outcome overall. Additionally, being able to give and receive feedback gracefully is a valuable skill to practise.

Valley of Despair

Author’s depiction of the Valley of Despair.

There’s an upcoming deadline and the designer is producing concept after concept but the team cannot seem to agree on how a feature is supposed to work - everyone’s patience is wearing thin. You’re beginning to wonder whether the whole project was a waste of time and maybe this was all for nothing. You’ve reached the Valley of Despair.

Sometimes a project can lose momentum due to changing priorities or requirements, and the team may find that morale and team synergy is running low. The Valley of Despair can be a tough place to recover from. Even for experienced orienteers, one of the most effective ways to navigate out is to talk through the situation with someone senior outside the immediate team. Sometimes someone with a bit of distance can provide a better vantage point and a new perspective.

At Thinkmill, we have walked the end to end product development journey enough times to know that it’s often the strength of your team that gets you through the Valley of Despair in one piece. This is why building rapport and trust early-on is fundamental (/method#fundamentals) to how we work.

🏁 The destination

The completion of an adventure is something to celebrate as the orienteer will have gained experience and practiced their skills. To preserve learning, it is encouraged that the orienteer documents any interesting and useful thoughts to feed back to the rest of the team.

It is also important to remember that not all adventures will end at the destination that was initially set out for and it is never the orienteer’s fault if things do not go as expected. The orienteer can only do the best with what they have and the learnings gathered along the way are valuable in themselves. Even a short time spent looking back on the journey will surface things to be proud of, so use this time to reflect and synthesise before starting on the next adventure!

All about Artefacts

Wed, 22 Feb 2023 00:00:00 GMT

During the product development process, supporting documents and visuals are created as we take an idea from conception to delivery – we call these artefacts. Artefacts serve as the physical and digital touch points whose combined information conceive the final product. They are where problems are uncovered and resolved, where solutions are created and tested, and where knowledge is recorded for future use. Artefacts are as much of the product development process as the product itself.

As we move to a more remote way of working, we reduce face-to-face time and begin to rely more heavily on asynchronous methods of communication such as artefacts. Understanding their strengths and limitations will ensure your team uses artefacts effectively and hopefully also help them to avoid the common frustrations.

What is an artefact?

Artefact is a broad term used to describe any supporting material that aids the process of building a product or service. They vary hugely in form and function, but all exist on a spectrum of symbolic to practical *:

Symbolic artefacts are used to represent an aspect of the product or service, as a way of visualising what the final experience could be like.
Practical artefacts are more concerned with the logistical side of the project. There are many artefacts that sit within these bounds that serve to bridge the gap between domains.

By understanding where an artefact sits on this scale, it can give an indication on who will be likely to engage with it. For example, a designer would be happy looking at a symbolic artefact such as a user flow diagram as a way of understanding the intended journey through the product, whilst a senior operations person would be more interested in a practical artefact such as a roadmap or timeline, as they are responsible for delivery. Thinking about who your audience is will help you to be more effective when using artefacts to collaborate with others.

Examples of artefacts sitting on the scale of symbolic to practical.

Additionally, artefacts can be divided into two main categories; personal artefacts and shared artefacts.

Personal artefacts

As creators, we are in a constant cycle of materialising our thoughts – this means getting ideas out of our heads and onto paper. Artefacts provide our thinking with a medium, allowing us to mull over and iterate on an idea, pushing and pulling on it until it becomes something with enough form to share with others.

Shared artefacts

We also create artefacts to clarify and explain concepts to others, covering everything from project timelines to the technical feasibility of a feature. They serve as communication tools between peers to present our point of view and the trade-offs we are grappling with. Most importantly, they contribute to the shared understanding of the team, which grows as more shared artefacts are created.

The lifecycle of a shared artefact

Throughout the lifetime of a project, many artefacts are created and shared as part of the product development process. A wireframe is utilised to get consensus on how a user would move through a product, or a component is published on Storybook to get feedback on an animation.

Artefacts are created throughout the lifetime of a project.

Together these artefacts contribute to the team’s overall understanding of the final product, until it reaches its peak at the end of a project. Naturally, this means that artefacts created later will have been created with a greater level of understanding than earlier ones.

Understanding increases over the lifetime of a project.

Later artefacts are created with a greater understanding than earlier ones.

Artefact accuracy diminishes over time

Though an artefact may have represented an accurate view of things when it was created, as the project and the team’s understanding progresses, the accuracy of that artefact diminishes over time until it eventually becomes stale. For some artefacts like project plans, it’s practical to keep them updated, but for others they may have served their purpose as a communication tool and can be left to retire. These retired artefacts still serve as a reference point to an earlier stage of the project.

The accuracy of artefacts diminishes over time.

The above graph reveals a critical limitation of artefacts which is often overlooked. Artefacts can only contain the level of understanding that the creator/s possess at that point in time. This is completely OK but is something to be aware of as sometimes too much weight can be placed on an artefact that has been created at a time when the team had less understanding.

Let’s look at an example. A head of product asks a developer to create a timeline to show how long each stage of the project will take to complete. Based on the current requirements, the developer maps out a 6 month timeline. However, as the project progresses, a new requirement is added and it becomes clear that one of the chosen technologies can’t support this additional feature. The developer tries to pivot to a new technology but the 6 month deadline arrives and the project is not complete. The head of product gets frustrated that the timeline was incorrect.

Let’s take another example. A company has an active design system that is used across their products. A designer uses it to create UI specifications for a new feature, but there’s no available development resource and the UI specifications are put on hold for a few months. Once a developer is ready to pick up the designs, the design system has evolved and some components used in the UI specification are now out of date. The developer gets frustrated that the designs are incorrect.

In both examples there is no wrongdoing by anyone involved. The frustration stems from the belief that artefacts remain as accurate as on the day they were created. However because the accuracy of artefacts diminishes over time, these and similar scenarios are bound to occur if the team isn’t aware of this limitation. An artefact created today will be different to a artefact created tomorrow, simply because we gain more information as time goes on.

At Thinkmill, we’ve been documenting our way of working that combat a lot of the issues seen in the above examples. Learn more about how we approach about product development at The Thinkmill Method.

So what should be done about it? (Alt: “How to guard against reliance on stale artefacts)

Artefacts can sometimes be a seemingly strong foothold in the midst of the unknown nature of product development. However, to avoid frustration we should be wary of putting too much weight on artefacts which are best consumed in the context of evolving understanding. Here are a few strategies to try.

1. Refer to the codebase more

Unlike artefacts, the codebase of the product is being actively worked on throughout its life. Once a product or service starts to be realised in code, shifting the reference point here is a great way to ensure you’re always looking at what’s most up-to-date. This is just one of the many reasons to start building things in code as soon as possible, as it gives the team a great early reference point to see how the product is progressing.

However, code is often not accessible by everyone on the team. Tools like Storybook and TestFlight, can reduce the barrier to entry for non-technical people, and give them a way to interact with the codebase.

2. Increase the synchrony of your team

From our experience, the less a team stays in-sync, the more artefacts are relied on as a form of communication. Because of this, increasing real-time collaboration and focussing attention on a few key shared artefacts, will help to prevent the creation of too many artefacts that fall out of relevance and become stale.

Additionally, by having representation from different domains engaged and contributing throughout the development of the product, the blind spots in artefacts can be addressed early making them more resistant to diminishing accuracy.

3. Add context to artefacts

An example of statuses used to communicate the state of a Figma page.

Creating a system that communicates the lifecycle of an artefact is not just useful for collaboration, it’s also useful to warn others when an artefact may have gone stale. This is important because stale artefacts can have unintended consequences if picked up by someone who doesn’t have the current context. By communicating the condition of artefacts with something like a status or creation date, other team members will have an indication on the accuracy level of the information they are looking at.

Summary

In this article we’ve explored what an artefact is as well as how understanding its purpose can maximise engagement from an audience. We’ve also looked at the lifecycle of an artefact and how its accuracy naturally diminishes over time unless its maintained. We’ve discussed the key shortcoming of artefacts which is that they can only contain the level of understanding that the creator(s) possess at that point in time and worked through some scenarios where this limitation can result in frustration from team members. Finally, we’ve looked at some strategies to reduce the reliance on artefacts as well as ideas for communicating the diminishing accuracy and reduce the likelihood of these frustrations occurring.

Hopefully this article has provided a renewed respect for the role that artefacts play and how they can be utilised in projects today and in the future.

Notes:

* The idea for the symbolic to practical artefact categorisation came from the article The Importance Of An Artifact In The Software Development Process by GN. It was remixed and turned into a scale for this article.

Building layouts with placeholder components

Tue, 21 Feb 2023 00:00:00 GMT

We’re in the early stages of building a complex application for a client. While we figure out how the underlying schema will work, we thought it would be a good idea to build the layout with placeholder components in place:

A responsive app layout using placeholder components

The placeholders give us a nice baseline to build from, and will provide obvious visual indication of progress to stakeholders as the real components replace them. We included image dimensions to help us make sure we use correct aspect ratios, and indicate to devs at a glance what sizes we’ll be needing.

Image component

The Image component simply takes width and height props and returns a placeholder image which automatically adds the dimensions. We used images instead of a styled HTML element to better understand how the layout might shift as they load.

function PlaceholderImage({ height, width, ...consumerProps }) {
  return (
    <Image
      {...consumerProps}
      alt=""
      src={`https://placehold.co/${width}x${height}.png`}
    />
  )
}

View this snippet as a Gist

Text component

We have a Text component that takes a number of characters and visually hides Lorem Ipsum up to that length and sets a repeating grey/white background to simulate text. Because it uses Plain Text under the hood, it responds and wraps sensibly.

const lipsum =
  'Lorem ipsum dolor sit amet consectetur adipisicing elit. Molestias quo voluptas fugit quidem nemo autem eos reprehenderit voluptatum nam. Error odio repellendus quisquam magni rerum hic facere laboriosam, aspernatur fugiat.'

function PlaceholderText({ characters, ...consumerProps }) {
  const string =
    characters <= lipsum.length
      ? lipsum.slice(0, characters)
      : lipsum
          .repeat(Math.ceil(characters / lipsum.length))
          .slice(0, characters)

  return (
    <span
      {...consumerProps}
      style={{
        backgroundImage:
          'repeating-linear-gradient(to bottom, #fff 0px, #fff 2px, #bbb 2px, #bbb 10px, #fff 10px, #fff 18px)',
        display: 'inline-block',
        fontSize: 12,
        lineHeight: 1,
      }}
    >
      <span style={{ visibility: 'hidden' }}>{string}</span>
    </span>
  )
}

View this snippet as a Gist

All in all, it’s been a handy way to create momentum on layout without adding a lot of technical debt.

Keystatic is now on Twitter/X

Mon, 20 Feb 2023 00:00:00 GMT

Follow along to stay connected to the latest news.

Livestream: landing page with Keystatic, Tailwind, and Next.js

Sun, 19 Feb 2023 00:00:00 GMT

We’re working on a few Keystatic starter templates for devs interested in early access. Watch Simon livestream the build of our first example – a marketing website landing page.

Our new database-free CMS experiment is up on GitHub

Sat, 11 Feb 2023 00:00:00 GMT

For more information on Keystatic, checkout the GitHub repo.

The Thinkmill Learning Loop

Fri, 10 Feb 2023 00:00:00 GMT

Many people who don’t know much about Thinkmill perceive us as a classic agency with all the classic agency problems like short term projects, churn, and superficial work.

While our commercial model is one of a classic agency (we sell time for money), how we create value, is not. We take a longer term view of developing knowledge, which is enabled through our work with clients. This knowledge is the product of Thinkmill, one that we work hard to improve over time.

We get to practice and innovate over and over again, reinforcing a learning loop that means over time, we collectively get better at a certain set of things: product design and design systems to name a few.

We get to practice doing the thing in a wide variety of environments, under many different constraints – technology, people, culture, budgets, ambition, industry, etc.

With each iteration of the loop (client engagement) we accumulate new experience, and refine what we know. We get opportunities to innovate and try out new approaches and methods. Sometimes we get long stretches, sometimes we get short bursts. This is the innovation wheel that causes our product knowledge to get better over time.

This is also why all of Thinkmill is a team, and why we invest a lot in breaking down silos and spreading knowledge. We all contribute to the turning of the innovation wheel.

If we get too caught up in any individual project, we may lose sight of the value we gain from the engagement. But if we keep the bigger picture in view, and remember that each experience is additive, it’s easier to remember that the challenges of any engagement are transient, and always present an opportunity to improve our craft.

Getting better at our craft over time is the goal. It’s the whole game. This perspective is crucial for growing at Thinkmill and having a good time with amazing people (both clients, and colleagues) throughout.

Our Philosophy of Working

Wed, 08 Feb 2023 00:00:00 GMT

Over the last decade, Thinkmill has organically evolved a set of mindsets that inform how we build products. Together, these mindsets form a Philosophy of Working that permeates our daily practice and shapes the tools we make in open source. This article unpacks our mindsets to give you a better sense of how we bring value to the work of product, and offer a case for adopting them in your own team.

Thinkmill mindsets

Engineering-led

Originally coined by our Design Director Lauren Argenta, engineering-led emerged as a product-building mindset stemming from the fact that most Thinkmill practitioners are engineers.

In practical terms, engineering-led means that we tend to think about how the schema, database, and system architecture are going to be developed as a way of informing and shaping (sometimes constraining) the products that we then end up designing. Engineering-led has been a useful way for us to differentiate our way of working from a design-led one, which you may find in other organisations.

For a deeper dive into the engineering-led mindset, watch Lauren talk about how we design in an engineering-led way at ReactConf AU.

Embedded media — view this post on thinkmill.com.au.

Code is the source of truth

This mindset is especially important to the work we do in design. It conveys the idea that in a world of abstractions, converging on code as the primary source of truth — wherever possible — is the least problematic way to build products.

Practitioners who don’t subscribe to this approach might be of the opinion that the artefacts of a design tool like Figma represent the source of truth. In our view they make for a brittle source of truth because they’re a static picture of the dynamic thing that will exist as code running on the internet.

We’ve developed the mindset that as technical designers, all the stuff we’re creating and expressing will ultimately live as code in a repo. So we should work with this reality and limit the abstractions by understanding, referencing, subscribing to, and contributing to – the code. As much and as soon as possible.

As an example, our goal is not to maintain perfect synchrony between Figma components, and the components in the code repository or Storybook; but rather to be comfortable using and improving those components in their native context.

Schema-first

We often talk about schema-first as an extension of the engineering-led mindset. In some ways it’s an expression of how we learned to build software. We found that by describing the data model or a schema for an application first, it serves as middleware to align a product’s back-end infrastructure, API, and front-end needs.

If the practitioners involved in delivering those aspects can converge and collaborate on the schema – it ends up being a useful way of aligning those different practices. Such that you can then go away and work relatively independently and come back to the schema when the need to update shared understandings arises.

Keystone is an open source framework we maintain that’s predicated on this schema-first way of working. With Keystone you literally write schema and it gives you back a database, GraphQL API, and Admin UI.

As opposed to starting with the interface or elsewhere, we strive to start with schema-related questions as much as possible. These questions look something like:

How do we describe the world that we’re building this product in?
What are the core concepts that underpin this world?
What’s the underlying data model that could capably represent those concepts?

Answering these questions in the form of a schema gives us a really good idea of how to design interfaces and flows that are inherently aware of the data that underpins the user experience. The result is fewer gaps when we’re delivering the thing we designed.

Cross-functional collaboration

We’ve found that it’s really hard (if not impossible) to build good software and products if we’re not intentionally working in a deeply collaborative and cross-functional way. Getting people from different practices collaborating effectively is something we think a lot about. Two extensions of this cross-functional mindset are Design Engineering and Code ♥ Design.

Design Engineering

Invision coined this term in their excellent Design Engineering Handbook. We subscribe to this mindset, and have embedded it as a central concept in the Thinkmill Method. Design Engineering to us is not about filling the gaps between the disciplines of design and engineering, but rather acknowledging and optimising their overlap.

As designers, the more we care about accessibility and API design, the better. As engineers, the more we care about interface quality, usability principles and heuristics, the better. The more we overlap, the more we reduce the likelihood of gaps both technical and experiential. Where technical gaps are what we might miss on the path to delivery, and experiential gaps arise from a designer creating without due consideration of something like performance, or conversely, an engineer building something that’s really performant without considering how useable that performant thing is.

Code ♥ Design

Code ♥ Design is another shorthand for our cross-functional way of working across design and engineering that we’re known for. In 2018 we partnered on a mini-conf to bring greater awareness to cross functional collaboration, so there’s a literal physical expression of our mindset out there.

Our Philosophy of Working

This cloud of mindsets comes together to form our Philosophy of Working. Most of these mindsets have been around for a while. They’re robust, proven, and hang together in such a way that we, as a group of people, can channel and embody them to build great things. Feel free to adopt or remix them to meet your own team needs.

If you’re interested in learning more about how we embody our philosophy in the work of building products, watch my talk from Dovetail’s Delighter’s conference:

Embedded media — view this post on thinkmill.com.au.

To explore how we can help you build great products and delivery culture within your organisation – get in touch.

Design, content, & code in parallel: Thinkmill’s new website

Wed, 25 Jan 2023 00:00:00 GMT

Simon made a playback of an internal team presentation we did this week. It looks at how we built the new Thinkmill website in a hyper-iterative way; with content, design, and code evolving in parallel streams. Our journey to launch presented an interesting set of challenges and learning opportunities.

How we built our website newsfeed

Fri, 13 Jan 2023 00:00:00 GMT

Here’s Tom Whitaker with an inside look at how we built the Thinkmill website news feed to surface material from a wide range of content types including articles, snippets, events, case studies, and more.

Dinesh has released a series of blog templates for Astro

Thu, 22 Dec 2022 00:00:00 GMT

You can clone the templates from Dinesh’s Github Repo.

Using CSS logical properties for internationalisation

Wed, 21 Dec 2022 00:00:00 GMT

We discuss the juiciest bits of an internal Slack conversation on design systems and logical properties. Served up with a dose of casual chat, two of our design systems experts – Joss Mackison and Luke Bennett – unpack best practices for the use of CSS logical properties for better internationalisation in design systems.

Building a share text selection to Twitter feature in React

Tue, 13 Dec 2022 00:00:00 GMT

What our end result will look like when selecting text

The likely result: social sharing takes a hit (or, it takes forever). So, what if there was a solution to take the great content you’re engaging with, and share it to a social platform really quickly — and really easily?

We recently created a version of this solution on a Thinkmill project, finding a way to improve the experience for users who prefer keyboard-based navigation when sharing to Twitter. This article will show you how to build your own using PopperJS and the native Selection API with improved accessibility for keyboard-based users thanks to your web browser’s Caret Browsing capability.

Getting started

You can try this out now, by selecting this paragraph and, with any luck, being presented with a popover interface that builds the tweet, and takes you to Twitter:

Share text selection to Twitter

To build this feature we’ll need to accomplish the following:

Show the user a popover interface when they’ve selected some text
Get the page URL for the tweet
Extract the selected text using the native selection API
Build the tweet to send through to Twitter’s URL API

We’ll use PopperJS to display the sharing interface at the location where the user selected the text. We’ll also tie this up into a reusable hook in order to access it across many parts of a project. To do this we’ll break the feature into 2 parts:

A hook called useShareToSocial that will do all the heavy lifting of building the tweet and sharing it to Twitter.
A wrapper component which we’ll use to handle the PopperJS reference for our popover.

Capturing selected text with the Selection API

First things first, let’s get text highlight selection in place. To do this we need to reach for the HTML spec’s Selection API. As well as getting the selected text we want to also get the coordinates to pass through to PopperJS.

const selectionChange = React.useCallback(() => {
  const selection = window.getSelection();
  if (selection) {
    const selectedText = selection.toString();
    if (selection.isCollapsed || !selectedText.length) {
      setSelectedText('');
    }
    setSelectedText(selectedText);
  }
  const virtualReference: NullableVirtualElement = {
    getBoundingClientRect: () => {
      return window
        .getSelection()
        ?.getRangeAt(0)
        .getBoundingClientRect() as DOMRect | null;
    }
  };
  setReferenceElement(virtualReference);
}, [setSelectedText]);

In the above we are also resetting our text selection when we have de-selected text on the screen.

Extracting the page URL with window.location.href

While we’re at it, let’s grab the URL of the page we’re on to include it in the tweet. To do that we can call window.location.href. Then we pass that to the encodeURIComponent() method, which converts it to UTF-8 encoding to put in our URL bar.

const pageUrl = encodeURIComponent(window.location.href)

Supporting keyboard-based selection with Caret Browsing

We can improve the accessibility of this feature by taking advantage of a browser setting called Caret Browsing. Available in Chrome, Firefox and Edge through the F7 keyboard shortcut - Caret Browsing lets users navigate the page and select text with directional keys like they are in a MS Word or Google document. We will also trigger the function to fire on text selection change.

Caret browsing setting in Chrome

Using Caret Browsing to select text with keyboard and share to Twitter

Positioning the popover

PopperJS provides us with a virtualReference of the selected text which we can use to position the popover. We’re going to use the coordinates Popper provides to set our reference element by passing it up to the parent to be set as the ref.

return () => ({
  width: 0,
  height: 0,
  top: y,
  right: x,
  bottom: y,
  left: x,
})

Limiting tweets to 280 characters

Now that we have the main pieces, we can put them together to build that tweet!

We need to ensure that the selected text fits within Twitter’s tweet limit of 280 characters. By including the truncated text in the popover’s preview, we’ll avoid any last-minute surprises that the user might encounter when they go to share their tweet.

const buildTweet = ({
  pageUrl,
  tweetContent,
}: {
  tweetContent: string | undefined
  pageUrl: string
}) => {
  if (tweetContent !== undefined) {
    const characterTotal = tweetContent.length + pageUrl.length
    if (characterTotal + 19 < 280) {
      return encodeURIComponent(`"${tweetContent}" – `)
    }
    const amountToTrim = 280 - (pageUrl.length + 19)
    return encodeURIComponent(`"${tweetContent.slice(0, amountToTrim)}…" – `)
  }
  return ''
}

export const buildTargetLink = ({ quote }: ShareQuoteProps) => {
  const pageUrl = encodeURIComponent(window.location.href)
  const twitterLink = (tweetContent: string) =>
    `https://twitter.com/intent/tweet?text=${tweetContent}&url=${pageUrl}&via=thethinkmill`
  const tweet = buildTweet({
    pageUrl,
    tweetContent: quote,
  })
  return twitterLink(tweet)
}

Let’s go through some of the numbers in the snippet above:

We add 19 to the characterTotal to reflect the number of characters we wrap the text selection with "" – via @thethinkmill. If we have too many characters with the wrapping text included, we move to the alternate option in the function.
Where we have the 19 added to the page URL but we cut the string and truncate. We then run it through the encodeURIComponent() to make it appropriate to pass to the URL.

Sharing the tweet with Twitter’s URL API

Now that we have our page URL and our built tweet at the right length we can use Twitter’s intent/tweet URL to fire off the tweet. The function we have above builds this URL in this way:

https://twitter.com/intent/tweet – our main starting point
text=${tweetContent} – the built quote at the correct length
&url=${pageUrl} – the page URL we are on taken from window.location
&via=thethinkmill – adding the intended account to be tagged when someone shares from an article

Bringing it all together

Now that we have done all the heavy lifting of selecting the text and building our tweet. All that’s left is to wrap it all up and be ready to ship this feature. To do this we will make a component to wrap our content and trigger the share function. Below is the whole component and then we will go into it more in-depth.

export const ShareableText = ({
  wrapperId,
  children,
}: {
  wrapperId: string
  children: React.ReactElement
}) => {
  const { textElementRef, textElementSelectionChangeHandler, popupElement } =
    useShareableText({ wrapperId })
  const childrenWithProps = React.Children.map(children, (child) =>
    React.cloneElement(child, {
      id: wrapperId,
      ref: textElementRef,
      onMouseUp: textElementSelectionChangeHandler,
    })
  )
  return (
    <React.Fragment>
      {childrenWithProps}
      {popupElement}
    </React.Fragment>
  )
}

We are pulling in the pieces we need out of the useShareableText hook. We grab the selection handler function and the relevant parts used by PopperJS.

const { textElementRef, textElementSelectionChangeHandler, popupElement } =
  useShareableText({ wrapperId })

Then we use the cloneElement method from React and attach the required props needed.

const childrenWithProps = React.Children.map(children, (child) =>
  React.cloneElement(child, {
    id: wrapperId,
    ref: textElementRef,
    onMouseUp: textElementSelectionChangeHandler,
  })
)

Now we can return a fragment with the props for the wrapper and the PopperJS element.

return(
  {childrenWithProps}
  {popupElement}
);

The result is a convenient wrapper around our content, which is the final piece of the share-to-Twitter puzzle. That gets placed around our content and we’re done.

return <ShareableText wrapperId="shareable-wrapper">{content}</ShareableText>

What we’ve learned

We used the selection API to get selected text from the page. We took advantage of PopperJS’ virtualReference function to know where on the page our selected text was located. And finally, we built a neat function that creates the tweet with some wrapping text and fits it within Twitter‘s 280 character limit. The end result is a seamless sharing experience you can use across mouse, touch, and keyboard inputs to let readers share their favourite excerpt of an article without having to copy, paste and edit.

Working example

You can check out the CodeSandbox here, and the working example page here. If you have more questions about the implementation you can find me on Twitter.

GraphQL for designers

Mon, 14 Nov 2022 00:00:00 GMT

Why do developers love GraphQL and how can designers best work with them?

Dinesh has released an app for sharing social notes

Wed, 02 Nov 2022 00:00:00 GMT

Dinesh made a handy tool to let you embed text into Open Graph images for social sharing purposes. Pocketnotes lets you quickly create and share notes to platforms like Twitter/Slack/Discord and the text will show up in the link preview.

Talking remote-first work at the Tech Council of Australia

Tue, 01 Nov 2022 00:00:00 GMT

Jed was invited by The Tech Council of Australia to talk at their showcase on the future of work. As a panel member, Jed shared Thinkmill’s experience of working in a Covid-era, how our business has been successfully navigating a remote-first approach since 2019, and what the future of our HQ may be. As a member of the TCA, we’re able to give a voice to software R&D and tech, from the trenches of community and innovation.

Luke Bennett special guests on The NavBar pod

Thu, 27 Oct 2022 00:00:00 GMT

Luke Bennett joined Simon & John from The NavBar to review the exciting new announcements at Next Conf 2022, and the release of Next.js 13.

Delightful products, the Antifragile way

Thu, 27 Oct 2022 00:00:00 GMT

Boris recently spoke at Dovetail’s Delighters Conference about our method for building great products within cross-functional teams.

Jed & Alex traveled to India for a week-long code/design audit and training workshop with a new client.

Tue, 25 Oct 2022 00:00:00 GMT

We’re helping AnywhereWorks find better ways of working and levelling-up their codebase and design system to support future growth.

Schema-driven Development

Sun, 09 Oct 2022 00:00:00 GMT

Dinesh recently gave a lightning talk at Sydney’s Web Directions Meetup on schema-driven development. Here’s a quick recap in case you missed it.

A day out at DDD Perth 2022

Tue, 20 Sep 2022 00:00:00 GMT

DDD Perth is an inclusive conference for the Perth tech community, packed with incredible speakers, and only costs $60! This year it was held at the Perth Convention and Exhibition Centre on Saturday 10th September. I woke up terribly early for a Saturday morning and headed into town to soak up some knowledge.

DDD Perth Neon Light Sign on stage at Perth Convention and Exhibition Centre

Learning from previous years, I got in early to have my Keep Cup filled with coffee. I’m glad I did, as the queue grew rapidly behind me. Coffee in hand (huge shoutout to the coffee cart sponsors MOQ Digital, PlanIt and Bunnings), I made my way around the sponsor stands to collect my prize draw stamps. One of the great things about DDD is being able to chat to representatives from some awesome tech organisations (and of course pick up some swag), and ask them about their services and/or products. After learning a bit about Twilio Studio, using Auth0 with Next.js and raiding Github’s sticker collection, it was time to head into the main auditorium for the opening keynote.

Christina Aldan delivered an opening keynote centred around understanding how our memories are stored and processed, and how to train our brain to store and process the memories more efficiently. This practical soft-skills talk helped me to understand some of the ways in which my own brain prefers to encode, process and retrieve information, as well as acknowledge how practicing mindfulness can boost my brain’s efficiency.

Pro tip: The brain isn’t always ready to roll, providing up front information, reference materials and facilitating async collaboration goes a long way in helping us to process information efficiently.

For the first breakout session of the day I headed to Phil Wild’s talk on Doodling and Drawing which for me was a perfect way to start the day as I’ve always been interested in using drawings to show my ideas, but I’ve never been any good at drawing. Phil took us through a series of practical tips and exercises in using the Bikablo drawing technique to communicate ideas and concepts. He demonstrated that simply using a few primitive shapes, it’s possible to create almost any visual to support an idea or concept.

After a quick coffee refill (again, huge shoutout to the coffee cart sponsors!), I listened to Kristy Haines clear up any confusion about what design is. The great thing for me about Kristy’s talk was its timing. Personally I’ve worked in close collaboration with a design team for most of my career, so sharing ideas and feedback throughout a project feels quite natural to me by now. Recently I’ve been working with engineering teams that haven’t had as much experience working with designers and Kristy dropped some great explanations that I can use in helping them understand the benefits of working as a cross-functional team.

Pro tip: Design is never complete. Design and engineering collaboration continues throughout the lifecycle of a product, innovation is the responsibility of the entire team, not only the designers.

I’m pretty sure we’ve all experienced that feeling that we’re not good enough, or don’t deserve to be in the position we are. I know I certainly have and apparently so have 58% of tech workers. Former psychologist turned software engineer, Cristi Middag detailed the journey of her career change and how she navigated the feeling of being an imposter. Her talk also included some tools and techniques that can be used to help ban out imposter feelings individually including Cognitive Restructuring and Dysfunctional Thought Records, as well as insights for team leaders to help reduce the effect of Imposter Syndrome on individual and team performance.

As a recent convert to full time remote work I was super keen to hear Ming Johanson’s talk on productivity when working remotely. Throughout the talk were a number of tips and tricks for employers, as well as some great testimonials from Ming’s own team members, however the key takeaway here was clear as day. Trust your team, if you can’t trust your team, you have the wrong team!

After a delicious conference lunch and a cheeky pint across the road with some fellow devs, I headed back inside the Convention Centre for the last couple of talks. One of the things no one tells you as a junior developer is that as you become more senior, you write less code and have to explain your solutions to everybody in the organisation. Fortunately there are folks out there like Trent Jones who are willing to share their techniques in how best to explain yourself. In a short session, Trent unpacked an example architecture diagram for a fictional cannery, breaking it down into a simple yet detailed chart that anyone from engineers to product owners and stakeholders could understand. Combining the learnings from this talk with some of the drawing tips from Phil’s earlier talk could make for some excellent artefacts in my daily work.

That lunchtime pint was a mistake, feeling sleepy I headed back to the coffee cart for round 3, then into the main auditorium for the locknote. Chris Ferrie’s presentation was an energetic and entertaining explanation of the complex concept of Schrodinger’s cat and quantum physics, which in addition to the caffeine hit, perked me right up.

All that was left now was the prize draw, in which I didn’t win one of the amazing prizes on offer, a couple of beers and some pizza at the after-party. Once again I was blown away by the incredible experience of attending DDD Perth. For $60 the conference is on par or better than conferences that charge a lot more than that. For that you get loads of international and local speakers, way too much swag, coffee, lunch, snacks and drinks. No wonder it sells out so quickly. Thank you to everyone involved in making DDD happen, I’ll see you next year.

We’re really proud to see so much adoption of our OSS tools

Thu, 15 Sep 2022 00:00:00 GMT

Our ability to do great work is inseparable from the communities we’re a part of. Seeing our open-source projects used by so many people remains a constant source of inspiration.

Single source of truth development

Thu, 15 Sep 2022 00:00:00 GMT

Jed demonstrates an end-to-end project using Prisma, Keystone, GraphQL, TypeScript and Next.js where everything is derived from a single source of truth for the schema and types.

How to establish multi-disciplinary teams to effectively design and build products

Fri, 09 Sep 2022 00:00:00 GMT

Lauren recently co-presented with Paul Merrell from Meld Studios at UX Australia 2022 about how Thinkmill & Meld established a multi-disciplinary team to effectively design and build a product.

New TypeScript utilities released as OSS

Thu, 08 Sep 2022 00:00:00 GMT

Checkout Emery on GitHub.

Jordan’s Automatic Style Guides plugin now supports hsla()

Thu, 08 Sep 2022 00:00:00 GMT

Jordan Geizer has released an update to his awesome Automatic Style Guides plugin. Now with hsla() support.

The State of Headless CMS

Wed, 27 Jul 2022 00:00:00 GMT

Jed joined a panel of experts to discusses the current state of Headless CMS and what lies over the horizon.

Simon Vrachliotis has launched a Podcast series

Tue, 19 Jul 2022 00:00:00 GMT

Simon Vrachliotis and his friend John Myers from Supabase have launched the NavBar – a podcast dedicated to web development and content creation. Check out the teaser.

Introducing KeystoneJS, the CMS & API Platform for Prisma

Sat, 02 Jul 2022 00:00:00 GMT

Jed’s workshop on how to build a polling system into a blog with Keystone, NextJs, GraphQL & Prisma.

Keystone 6 is now in General Availability!

Tue, 21 Dec 2021 00:00:00 GMT

For more information visit https://keystonejs.com/.

Keystone, GraphQL & Prisma

Sat, 09 Oct 2021 00:00:00 GMT

Jed discusses the new Keystone 6 at Prisma’s Korea Meetup

We’ve joined the Tech Council of Australia

Tue, 05 Oct 2021 00:00:00 GMT

We’ve joined the Tech Council of Australia to help reach 1m tech jobs by 2025

Next-gen CMS & GraphQL API with Keystone & Prisma

Fri, 16 Jul 2021 00:00:00 GMT

Jed shared our freshly minted Keystone 6 with the world at Prisma Day conference in July 2021. His talk is a great way learn how Keystones combination of features and flexibility set it apart from other backend frameworks and Content Management Systems

ReactConf AU, one year later

Fri, 26 Feb 2021 00:00:00 GMT

Dinesh Pandiyan & Dominik Wilkowski having fun at ReactConf AU in front of a ReactConf AU banner poster

There’s nothing like an anniversary to remind us how fast time moves, and just how much things change. And that’s just in a normal year!

Following a tough start to the year with bushfires raging across Australia, we had no real idea what 2020 had in store when we hosted Australia’s first ever React Conference on the 27th & 28th of February.

Overseas speakers flew in, old friends reacquainted and new connections were made. Close to 600 local and international developers gathered at Sydney Harbour to connect with, listen to, and learn from members of the React community.

Looking back, it was truly amazing that all this happened just two weeks before we all went remote and had to stop seeing each other in person for the rest of the year.

We realise this made us twice as lucky — not only did we manage to wrangle such an awesome event, but we threw one of the last parties Australia’s React Community could enjoy for a while!

Since then, we’ve been reflecting on the 2020 rollercoaster, plans that were made, and what we have achieved since.

Plans Made

As the event was closing, 93% of our attendees said they’d come to the next ReactConf AU, and our keynote speaker Max Stoiber ranked it as one of the top four conferences he’s ever been to globally 😍
While 2021 may not be the year, we do look forward to hosting another ReactConf AU again when the time is right. And in the meantime we’re all exploring new ways of connecting with each other from home 🏡
Our second keynote speaker Diana Mounter gave a talk on how Themeability is the path to Dark Mode, with a wealth of insight into how GitHub are building themeing foundations and applying colour theory to deliver their most-requested UI update ever
Our co-founder Jed closed the conference with a talk on The Value of Open Source, and surprised the audience with a voucher taped under their seat, to donate to a project that matters to them on Open Collective 💵
And of course, just a few weeks after the conference we were all making plans on how to keep our heads down and survive the new reality we found ourselves in

Jed Watson presenting on stage at ReactConf AU with a screen next to him displaying 'Satisfaction ☺️'

Goals Kicked

It didn’t feel like the rest of the year was going to plan at all, so it’s been great to reflect on how things actually played out:

Despite everything, we’re proud to say that with the support and flexibility of our team and partners, Thinkmill not only survived 2020 but continued to grow (even if only slightly compared to past years) 🙏🏻
After the conference, several hundred developers donated to open source projects on Open Collective for the first (and not last) time! It was brilliant watching the donations show up in unexpected places as our community paid them forward ⭐️
More broadly, we saw groups and fiscal hosts coming together on Open Collective’s platform to help each other through the economic fallout from COVID-19, including their UPLIFT! event which raised $105K to support the open source ecosystem 📈
We applied our Budget for Open Source initiative internally, renewing our commitment to maintaining projects like react-select and funding a dedicated team (for the first time!) to focus on developing KeystoneJS — our open source Headless CMS, empowering front-end developers to build powerful, easy to manage, content-driven websites 🌏
AirBnB got a special shout for their $100k open source funding initiative, and this year have increased that by 50%. It’s absolutely worth reading about the impact this has has on open source projects.
And delivering on Diana’s promise, GitHub finally launched their Dark Mode to great acclaim across the internet 👏🏻

In Case You Missed It

Last year’s event was packed with incredible talks, well worth a watch (or re-watch). Browse them all right here: reactconfau.com/talks
Possibly our most artistic developer, Tom Walker prepared unique, inspired artworks for each of the talks, and followed up with a whole write-up about the process. See and read about them in our blog!
We’re glad to see more companies prioritising open source funding and sustainability, but there is still a long way to go. Big things start small, so remember to advocate for the value you get from open source and help your company dedicate some budget to sustaining it.

Thanks again to everyone who was part of the event — including the organising team (especially our indomitable duo Debbie and Kim), the support crew who made each day run smoothly, the speakers both local and international who put so much effort into preparing great talks, our sponsors who made the whole thing possible, and of course everyone who came to the event. We couldn’t have done it without any of you.

And for everyone who watched the conference, either online or in person, we’re glad you enjoyed it, and look forward to seeing you again one day!

Jordan Geizer has released an automated style guide plugin for Figma

Mon, 22 Feb 2021 00:00:00 GMT

Jordan Geizer has released an Automatic Style Guide plugin for Figma that generates (and keeps up to date) formal style guide documentation based on your local Figma styles. Now you can prepare a clean and functional style guide for clients & developers with a click of a button.

All the ReactConf AU talks are available online

Sun, 01 Nov 2020 00:00:00 GMT

All the recordings from ReactConf AU are available on YouTube. Here’s the full playlist.

The "state" of UI

Tue, 09 Jun 2020 00:00:00 GMT

This will come as a surprise to many of you, but user interfaces on the web, have different types of state. It might be that "State", much like "Design Systems", is a word that has lost all meaning for you, but regardless, I think you will agree the UI state designers talk about is different from the application state developers refer to. Let’s figure out how to have a discussion about these similar sounding but very different concepts for the sake of our sanity and better design system components.

Illustrations for ReactConf AU 2020

Tue, 17 Mar 2020 00:00:00 GMT

About

ReactConf AU 2020 was recently held in Sydney, Australia. Presented by Thinkmill — ReactConf AU is a tech conference featuring domestic and international speakers. I helped organise the conference, provided gelato for attendees, and created the illustrations above.

The goal was to illustrate each of the 23 presentations at the conference and then combine them into one mega illustration.

Illustrations were based on talk titles and descriptions, and it’s worth mentioning that these presentations were very technical and abstract at times, so interpretation varied wildly.

It was completed a few days before the conference, printed onto stretch fabric, and displayed at the conference! Each illustration was also shown on stage immediately before each presentation, including the time lapses videos found below.

Dinesh Pandiyan and Dominik Wilkowski at ReactConf AU, 27th February 2020

Thanks

The illustrations would not have been possible without the help of Dominik Wilkowski — who brainstormed ideas with me for hours throughout the illustration process and provided lots of great feedback after each illustration was completed.

Daniel Cousens and Alex Walker were also a great help, especially with perspective — one of the hardest aspects to get right and something I’ll keep improving on.

Illustrations

Here’s a one-by-one overview of all 23 illustrations, which talk they were paired with, and the story I was telling in each one.

1. Themeability is the path to dark mode

Diana Mounter

When the design systems team at GitHub implemented their colour system in 2017 they were working with Sass, trying to wrangle thousands of disconnected colour values into… <a class="external-article" target="_blank" rel="noopener noreferrer" href="https://reactconfau.com/talks/themeability-is-the-path-to-dark-mode?from=talks">Read more<span class="sr-only"> about this talk</span></a>

Engineers take the existing light theme on the GitHub website and produce a dark theme from it. Processing power is focused on getting dark mode code output.

Printers print the code necessary to be input with hashes depicting hex colour codes. It’s a lot to keep track of, so why are they printing this on paper anyway?

Watch time-lapse

2. (Proto)typing innovation in BBC News

James Dooley

BBC News Labs explore, prototype and incubate new ways to tell stories, reach audiences and create cutting edge journalism. James will demonstrate how his team… <a class="external-article" target="_blank" rel="noopener noreferrer" href="https://reactconfau.com/talks/prototyping-innovation-in-bbc-news?from=talks">Read more<span class="sr-only"> about this talk</span></a>

A famous presenter with a British accent interviews a bear with the help of a real-time transcribing computer (with support for translation too), beaming the results real time to back to the broadcaster.

Due to its remote location, equipment — including a satellite — has to be brought in to beam the signal back. The bears are mischievous; they have taken off with the BBC sign.

Inspirations: BBC documentaries (TV)

Watch time-lapse

3. Modern Forms in React

Erik Rasmussen

If the new React Context API and Suspense killed Redux (they didn’t), surely Hooks kill the need for a form library, right? Well, not exactly. Managing form state is more than just holding… <a class="external-article" target="_blank" rel="noopener noreferrer" href="https://reactconfau.com/talks/modern-forms-in-react?from=talks">Read more<span class="sr-only"> about this talk</span></a>

Developers are using fishing rods and hooks to collect form fields to use in their forms.

They’re looking for buttons, drop downs, toggles, radio buttons, check boxes, range sliders, and password fields.

It’s a lucrative business; the checked radio button is rare and sells for many credits.

Watch time-lapse

4. react-beautiful-dnd: Behind the magic

Alex Reardon

react-beautiful-dnd (rbd) is a successful open source project that aims to provide performant, beautiful and accessible drag and drop. In this talk, Alex will break… <a class="external-article" target="_blank" rel="noopener noreferrer" href="https://reactconfau.com/talks/react-beautiful-dnd-behind-the-magic?from=talks">Read more<span class="sr-only"> about this talk</span></a>

An architectural design reminiscent of drag and drop lists, each item being an occupied space.

Each block can move up, down, left, and right — even to an entirely different building by going straight down and detaching.

Occupants include: VR chamber, an industrial house, gelato factory, tropics, magician, gelato store, and a home with lots of plants — which is currently moving to another space.

Inspirations: Drag and drop lists (web)

Watch time-lapse

5. 10 x your teamwork through pair programming

Michael Milewski & Selena Small

Selena and Michael take you on a roller coaster journey of getting into and getting the most out of pair programming. Live on stage trying to deliver a feature whilst coding in React… <a class="external-article" target="_blank" rel="noopener noreferrer" href="https://reactconfau.com/talks/10-x-your-teamwork-through-pair-programming?from=talks">Read more<span class="sr-only"> about this talk</span></a>

A roller coaster just for pair programming! Two seats, one keyboard, and one screen in each carriage. Riders often reach peak productivity at the top of the coaster.

It has got some very tight turns, though. It’s no wonder that guy feels ill after riding.

Inspirations: Roller Coaster Tycoon (game)

Watch time-lapse

6. The first two seconds: Faster page loads with React

Josh Duck

We’re often told it’s impossible to create React pages that load quickly. Are React developers really doomed to a life of embarrassing Lighthouse scores? Working with the ABC… <a class="external-article" target="_blank" rel="noopener noreferrer" href="https://reactconfau.com/talks/the-first-two-seconds-faster-page-loads-with-react?from=talks">Read more<span class="sr-only"> about this talk</span></a>

Website performance equipment is perched atop Lighthouse Beach. Today. the ABC News website is being tested. Once the tests are run, the lighthouse projects a score from 0 to 100, which indicates how well the website performs.

Inspirations: Lighthouse analysis tool (web)

Watch time-lapse

7. Engineering led design

Lauren Argenta

Designers and engineers: we have different experiences, different skills, different mindsets, and yet bridging these differences effectively, and making the most of this inherent diversity is the secret sauce in making good software… <a class="external-article" target="_blank" rel="noopener noreferrer" href="https://reactconfau.com/talks/engineering-led-design?from=talks">Read more<span class="sr-only"> about this talk</span></a>

Engineers guide designers up a mountain, sharing their experience and skills. It’s rough terrain, cold, and snowing, but everyone is doing their best to work together!

Watch time-lapse

8. Take a load off with React

Jake Moxey

When designing asynchronous operations in a React application (such as data fetching), it’s easy to overlook the confusing and inconsistent user experience it can result… <a class="external-article" target="_blank" rel="noopener noreferrer" href="https://reactconfau.com/talks/take-a-load-off-with-react?from=talks">Read more<span class="sr-only"> about this talk</span></a>

A React artifact has been discovered inside a cave — but it’s being crushed by the severe load above it! Things don’t look good; it’s starting to show signs of stress — but a crew of engineers are working together to rectify the problem.

Watch time-lapse

9. Senior to leader: Taking the next step

Cathy Lill

The path to senior, cross disciplinary, technical leadership can be difficult to navigate as a front-end specialist. Will my skills be valued? Will I be considered… <a class="external-article" target="_blank" rel="noopener noreferrer" href="https://reactconfau.com/talks/senior-to-leader-taking-the-next-step?from=talks">Read more<span class="sr-only"> about this talk</span></a>

When seniors become leaders, they must take a journey to prove themselves. It’s tough. There are 3 levels:

Defeat a barrage of difficult and challenging bugs
Fight your way through the wooden barricade, defended by small bears
Prove that you have the experience necessary for the job.

Inspirations: Super Mario (game)

Watch time-lapse

10. Targeted extensibility: Lessons learned from building Atlaskit

Charles Lee

Often when building a design system we face tension between consistent and resilient API’s that encapsulate valuable and reusable logic, and sufficient flexibility to ensure that… <a class="external-article" target="_blank" rel="noopener noreferrer" href="https://reactconfau.com/talks/targeted-extensibility-lessons-learned-from-building-atlaskit?from=talks">Read more<span class="sr-only"> about this talk</span></a>

The React Swiss Army Knife Ship or the RSAK Ship can adapt to many different situations for extensibility! Screw laser, drone launcher, reamer satellite, and large knives are at hand to help any situation.

Inspirations: Swiss Army Knives

Watch time-lapse

11. What is an XSS attack — and why should you care?

Carmen Chung

XSS (Cross-Site Scripting) attacks are often referred to as the “most common vulnerability online”. With victims like eBay, McAfee, and Yahoo, these attacks involve injecting… <a class="external-article" target="_blank" rel="noopener noreferrer" href="https://reactconfau.com/talks/what-is-an-xss-attack-and-why-should-you-care?from=talks">Read more<span class="sr-only"> about this talk</span></a>

Dangerous drones are staging an XSS attack from multiple angles on a React ship. They’re exposing holes in the shield!

Engineers are closing the vulnerabilities as fast as possible using shield repair plasma guns.

Inspirations: Team Fortress 2 (game), Faster Than Light (game)

Watch time-lapse

12. Creating a custom form handler with hooks

Hannah Thompson

What do you do when your new application is just a bunch of forms? Well, in the past you’d probably use a library, but now you can lean on react hooks and create a custom form… <a class="external-article" target="_blank" rel="noopener noreferrer" href="https://reactconfau.com/talks/creating-a-custom-form-handler-with-hooks?from=talks">Read more<span class="sr-only"> about this talk</span></a>

This multi-load crane helps engineers implement validation into their forms, with each block configured for a different purpose.

Assassins are sabotaging the validation blocks by slashing the cables holding it all up, but security are throwing out hooks to catch them in the act.

Watch time-lapse

13. Reactronica: Music as a Function of State

Kaho Cheung

React treats UI as a function of state. What if React’s declarative programming model could be applied to music as well? Reactronica aims to treat music as a function of state…

It’s Reactronica! The best musical act in the React universe. Ukulele, piano, giant horn, and percussion combine to produce some sweet beats for its fans.

Watch time-lapse

14. Redux Connect vs Redux Hooks: A play

Terence Jeong

Redux Connect vs Redux Hooks is an enchanting tale about going from the Redux Higher Order Component to the new Redux Hooks. Our hero, a Class Component is connected to… <a class="external-article" target="_blank" rel="noopener noreferrer" href="https://reactconfau.com/talks/redux-connect-vs-redux-hooks-a-play?from=talks">Read more<span class="sr-only"> about this talk</span></a>

Watch out! Redux Hooks has arrived in town, taking on the Redux Connect sheriff.

Redux Hooks swarms its hook-like tentacles. Onlookers heckle nearby. It’s going to be a bloody fight.

Inspirations: Western Movies (genre)

Watch time-lapse

15. Rethinking Design Practices

Mark Dalgleish

In a world of components, how should our design processes change? How should our tooling change? How should we, as front-end developers, better enable this change? In this talk… <a class="external-article" target="_blank" rel="noopener noreferrer" href="https://reactconfau.com/talks/rethinking-design-practices?from=talks">Read more<span class="sr-only"> about this talk</span></a>

The small bears are enforcing status quo design practices on the engineers: get dumped out, learn the current state of design, and get sucked back in.

A small group of resistance fighters are trying to stop the drone-like people. “Wake up” they scream. “We can do better!”.

Peeling back the guide rail, they direct them into a waiting escape ship.

Inspirations: Lemmings (game)

Watch time-lapse

16. 5 things you should know about WordPress… wait, what?

Isabel Brison

Did you know a large chunk of WordPress is now built in React? WordPress is a 16 year old open source project with hundreds of contributors, most of whom came from a PHP, HTML… <a class="external-article" target="_blank" rel="noopener noreferrer" href="https://reactconfau.com/talks/5-things-you-should-know-about-wordpress-wait-what?from=talks">Read more<span class="sr-only"> about this talk</span></a>

After years of planning, WordPress has been split open to consume React itself!

It’s a messy operation — fires break out, radioactive material is exposed, electric surges and smoke is pouring out. It won’t be easy, but it’s for the best, taking the platform forward.

Watch time-lapse

17. Write fewer tests! Model-based testing in React

David Khourshid

What if you could automatically generate hundreds of integration and end-to-end tests, instead of manually coding them? Discover how model-based testing greatly improves… <a class="external-article" target="_blank" rel="noopener noreferrer" href="https://reactconfau.com/talks/write-fewer-tests-model-based-testing-in-react?from=talks">Read more<span class="sr-only"> about this talk</span></a>

The Jest ship travels around and produces hundreds of tests on command to help engineers.

Many tests in a fraction of a second — with no manual work required. Just hit a button and they’re swarming, ready to expose the most hidden edge-cases.

Watch time-lapse

18. The tragedy of scale

Hannes Obweger & Nadia Makarevich

What do farmers 200 years ago and today’s software developers have in common? Why use the word “tragedy” to describe it when it’s not tragic at all? Join us for this tale… <a class="external-article" target="_blank" rel="noopener noreferrer" href="https://reactconfau.com/talks/the-tragedy-of-scale?from=talks">Read more<span class="sr-only"> about this talk</span></a>

It’s 200 years ago and rapid growth has produced too many bugs - they’re infiltrating farms and crops the world over!

The only way to contain them is to catch and secure them, preventing reproduction. Latching onto your body is one of their favourite things to do.

Watch time-lapse

19. Building with Monorepos

Emma Hamilton

Monorepos are everywhere in the React community from design systems and apps to open source libraries. Being able to work on multiple packages together is powerful, but… <a class="external-article" target="_blank" rel="noopener noreferrer" href="https://reactconfau.com/talks/building-with-monorepos?from=talks">Read more<span class="sr-only"> about this talk</span></a>

After a long journey through the jungle searching for a React artifact, our adventurer arrives at a mysterious door. What lies behind it?

In front of them is a puzzle. They’re going to have to move each piece to gain access to what lies within.

Inspirations: Jurassic Park

Watch time-lapse

20. How to teach an old dev new tech: Learning React as a senior developer

Trent Willis

Have you ever learned a new technology? Were you uncomfortable? Intimidated? That was Trent’s recent experience when he had to learn a new framework… <a class="external-article" target="_blank" rel="noopener noreferrer" href="https://reactconfau.com/talks/how-to-teach-an-old-dev-new-tech-learning-react-as-a-senior-developer?from=talks">Read more<span class="sr-only"> about this talk</span></a>

A React entity intimidates and stares down on the battle-worn engineer. Its intense glare can see all the way into the engineer’s soul.

This is the final battle step to conquer React.

Inspirations: Eye of Sauron from LOTR (movie)

Watch time-lapse

21. A GraphQL Survival Kit

Petra Gulicher

GraphQL lets us model our business domain as a graph, but what does that mean? What are the tools we need to design a model that works for our business, products and users both… <a class="external-article" target="_blank" rel="noopener noreferrer" href="https://reactconfau.com/talks/a-graphql-react-survival-kit-how-to-avoid-the-pitfalls-and-level-up-your-teams-creativity?from=talks">Read more<span class="sr-only"> about this talk</span></a>

After venturing from base camp in the jungle, an engineer comes across a very protective elder bear guarding their offspring.

Rushing back to their camp, the bridge collapses under the stress. Using knowledge and equipment from the GraphQL Survival Guide, they throw a rope device to avoid sudden death below from raging waters and poisonous snakes.

Inspirations: Indiana Jones (movie)

Watch time-lapse

22. Powerful REST in a GraphQL world

Tejas Kumar

As a startup that integrates with larger, often older enterprises, we have to integrate with a number of RESTful services (against our will). This technical talk will outline how we are… <a class="external-article" target="_blank" rel="noopener noreferrer" href="https://reactconfau.com/talks/powerful-rest-in-a-graphql-world?from=talks">Read more<span class="sr-only"> about this talk</span></a>

On top of an aging REST API facility, a large GraphQL satellite has been built to act as a reliable and easy-to-use single end-point.

In the depths below, maintenance staff battle creatures in the dark, fending off fast growing vines and repairing equipment that is constantly malfunctioning.

Watch time-lapse

Bonus Drawing

For a presentation that had to be cancelled at short notice.

Three civilizations from around the universe meet to declare peace and work with one another.

Watch time-lapse

Thinkmill Spaceship

ReactConf AU was presented by Thinkmill. Take a look at my Thinkmill In Space 🛸 for a complete explanation of the back story for this illustration.

Process

Illustrations were created on an iPad Pro with an Apple Pencil using Adobe Draw. It took about 120 hours to complete.

My two favourite creations are: Rethinking Design Practices (Lemmings inspiration) and How to teach an old dev new tech (Eye of Sauron inspiration).

Thanks for reading!

Thanks to Dominik Wilkowski

The Value of Open Source

Wed, 04 Mar 2020 00:00:00 GMT

Jed wraps up ReactConf AU by discussing the sustainability of open source, the value OSS creates for us all individually and as a collective, and then proposes some small steps we can all take to ensure the future of our vibrant community.

Engineering-led design

Wed, 04 Mar 2020 00:00:00 GMT

Transcript

(00:02)

My name is Lauren, and I am the design director at Thinkmill. I think you’ve heard about them, a software company. Before we go any further, I’ve got to disclose to you, I’m actually in a new job at the minute. I started five and a half months ago when we welcomed a small little humanoid into the house who doesn’t pay rent, and last night decided to wake up and be like, “hiya!”, every two hours. So, yeah, feeling great today. I’m having a new problem now where I literally can’t remember words I’m trying to say. So, when that happens invariably in the next 20 minutes, heckle me, please. I actually appreciate it. Yesterday when I was trying to practice for this, I kept getting the wrong word in place of another – differential and deferential, and difference, they all got mixed up. In your brains, just go, I think she meant this. And I would really appreciate it. If you are parents and have looked after small children and know how to make them sleep, please come talk to me afterwards because I can’t figure it out. So yeah, in this new role... failing at it. But when I come back to work, not too bad at it.

(01:14)

As I said, I’m a designer. Product designer. I specialise in user experience and user research and generally for functional products. That’s my happy space. Give me a form and I’m your gal. I get overly excited about sorting content into simple flows and making sense of it. Or really nailing an information architecture. Or even, you know, you can see me having a little dance if I’ve reduced the certain amount of clicks it takes to enable a user to achieve an action.

But I’m just a designer. And I’ve been just a designer since I graduated in 2008. And was recently, up until very recently, working in design-led environments. What I mean is design-first. We start with design before we start talking to any engineers. And then in 2017, I had this bright idea to join Thinkmill. And Thinkmill was a pure engineering-led company. At the time we were mostly software engineers. There were few of those engineers who’ve come from design, and then shunned it and gone, yeah, no. And rock star into the engineering space (generally in the React space as well, just saying). There was a lot of design that was happening every day, but it was kind of happening in pockets. And it is fair to say that the design practice was somewhat basic, somewhat scrappy, and somewhat meek.

Basic in that, yeah, it was UX/UI. But there was only a little bit of research (not in a rigorous way) going on, and it was heavily informed on intuition. Which isn’t always a bad thing. Scrappy in that there wasn’t a shared, cohesive view of what design at Thinkmill was. And meek in that it just wasn’t confident that it played a crucial role in making good software.

(03:19)

Now, I was invited in to change that. To develop a more mature shared and confident design practice in that engineering-led environment. So, that kind of became my brief. Introduce a proper design practice in an engineering-led environment. So, not scary at all. And not terrifying.

A quick note before I go any further. These things [Components, GraphQL, React], they are absolutely lovely. And I think they’re absolutely amazing, but I’m not going to talk about any of them whatsoever. Because everyone else who will be up here at this conference will do so much more knowledgeably and eloquently than I could. It would be funny to see me try to do it, admittedly but I’m not going to. I think they’re amazing tools to work efficiently at scale. But I’m going to talk about engineering-led design.

(04:09)

Engineering-led design as we see it is a mindset. It is a mindset embedded into shared behaviours. Now, these behaviours are what we’ve established and identified along the journey since I joined Thinkmill in 2017. They are becoming the vehicle in helping us to introduce a proper design practice into a company full of engineers.

These are particularly useful to use when you are in the context of solution design. In an engineering-led environment which many of you I imagine are, or when you have designers on your team. And I am hoping there are a few designers here. But if not, it’s when you come into contact with them.

Please bear in mind the other thing. I am a designer talking to a room full of engineers, I’m guessing. And these are basically going to be practical things that you can do as an engineer. But especially as an engineering leader. But they are just the starting point. And this mindset does run a whole lot more deeper. And if you want to talk about it in more specific detail later on, we can do so. These behaviors are a starting point for you to get going with.

(05:37)

So, let’s dive into them. There are five that we’re going to cover:

Context together.
Create a dictionary
Teach as you work
Play it back to validate
Break down language barriers

I’m gonna kind of unpack them as we go.

(05:53)

Context together

Shared context isn’t just valuable. It’s really, really valuable. When adopting an engineering-led design mindset, we gather context together. In the early stages of a project, when we’re still discovering the requirements, the constraints, the opportunities, all the unknowns, the known unknowns, etc., getting this shared context as a team is really hard.

It takes time, it takes focus, and it takes a lot of brain power and attention. But so much depends on having shared context for making good decisions. Technical decisions, product decisions, business decisions, strategic decisions, timing decisions, release decisions, all the decisions.

If we can ensure that we have shared context as a multidisciplinary team, we can be confident that when we’re making decisions, that are design, or technical decisions we’re using the same inputs and parameters. So, what does it mean to context together in practice? Well, context together means everyone, and I mean everyone, attends all context-gathering meetings early on – regardless of if the focus is design or engineering.

This is vital because what it results in is on one hand, you’ll have designers like me who immediately become informed about technical constraints. And about what hard problems are going to be as we go into them. And for me, I get a bunch of engineers who become very acutely aware of user needs. And what they’re going to have to have down the track.

So, that means that those engineers are in a much stronger position to be able to spot relevant technical overlaps much, much, much sooner. Context together means engineers are in the room when we do research. This is key. We need engineers to see what designers are seeing.

A quick interlude here. This is some research that we ran. And the majority of the team that attended that research are engineers. They saw what we saw. There was zero translation needed after the fact. And the last thing is that context together means educating your designer about the hard problems in software, in real time.

Designing with dates? Help a designer understand why time zones are hard and why you can’t just use server time. Because I know you guys know that. But we probably don’t. Contexting together prevents gaps, prevents rabbit holes, and tangents in the early stages of a design project.

(08:54)

Create a dictionary

I hope that’s self-explanatory. Naming is hard. Using precise language is very important. But in design and technical practices, the same terms such as users often have different meanings but come up quite often. And I think it’s fair to say that we’re both quite guilty of using jargon from time to time. And look, creating a dictionary, you might be sitting there going “You know what? That sounds like busy work” and I can absolutely assure it is not. It is really simple. Yes, it takes some time to maintain. But the payback is absolutely huge. So, what this means in practice:

We create a shared document using a low friction tool that everyone can use. By low friction, what I mean is that if you guys have some designers on your team and they’re not comfortable on markdown or GitHub, please use that. Use something they are comfortable in so that they can be part that have club. We define project-specific terms. Like data structure, interface elements, etc. This is because using accurate language is very important. What this dictionary gives you (even a rudimentary dictionary) is it makes using that accurate language much easier, and makes sure that the team can adopt it much, much faster.

This next one is really important. Always be a diva when defining your freakin’ acronyms. We all have them. I got them, you got them, everybody got them. And sometimes, you know, it’s a little embarrassing to put your hand up, I’m sorry, what does HTTP mean? But it is important for us to be able to have those conversations. And it’s also important for us to realise that, *“oh, your acronym is the same as mine, but they mean completely different things”,*because that’s expensive down the track. Such is why we need to REST all the time (yes, I did ask that question once; don’t laugh; it’s not nice; safe space).

And lastly, define practice-specific jargon and note reserved words. So, in user research, for example, there are these three words: Observation, finding, and insight. They mean completely different things. An observation is a similar thing, a finding is a group of observations, and if you take the time to figure out what that means, it might turn into an insight. That’s pretty loaded. These are also everyday words. If we don’t reserve those meanings how will they know what we mean with an observation versus an insight. The weighting is very different.

Equally, accessibility, it’s got a lot of meaning behind it from both a technical and design point of view. We need to make sure we reserve words like that so that everyone is on the same page at all times.

This is an example of a dictionary that we did for a project. You can see some definitions around the schema and acronyms, etc. And we just used Notion for this tool. The important thing here is that we created and maintain this across practices, both in design and engineering. And we pretty much used this every day. We use this every day from the beginning of the schema design through to the design system build.

And this wasn’t just a nice to have. It was a foundational item. Now I want to note that this kind of basic dictionary evolves into a much more sophisticated source of truth that will be housed in many places such as the design system, schema, and now the documentation. But at the start, it’s just a page with definitions. But don’t underestimate that page. Because it is a crucial bridge between design and engineering.

(12:50)

Teach as you work

What this refers to is the acknowledgment that as designers and engineers, we have deep knowledge and expertise and that we cannot become experts of each other’s domain.

I’m not going to become a React engineer. And you probably don’t want to become what I do. And that’s okay. That’s cool. But what we both need to do is learn from each other.

Because you know what? When we do, that’s when the magic really happens. In practical terms, what this means is injecting short, structured lessons into your day-to-day work. In Thinkmill we tend to call them like little asides. They’re usually 30-minute sessions, delivered by an expert on the team, whoever is most knowledgeable, into a topic that unlocks something so that we can actually make sure that we’ve moved forward from not being able to understand to all going, ah, the pennies drop.

The trick here, though, is to frame them not as a distraction, but to make them a key part and a first-class citizen of every day work. This is just an example of some work that we did on a medical annotation platform. For those who don’t know what a medical annotation platform is (and that was once myself) that is when you go for a scan and they take the scan, a radiographer has to go through it and mark it up later. Now, there’s a lot of UI work based around processing radiological images in this. And if you know anything about radiology, you know that involves basically finding something in a 3D space A.K.A. spatial localization.

So, this is a bit of a whiteboard session with myself and the lead architect on the project called Tim. He’s basically breaking down the concept of spatial localization, so that we together could potentially construct the rudimentary form of the UI. From a design point of view, what this unlocked was an underlying foundation that I could use as constraints as an inspiration to fly forward though. It was time well spent.

This is another example, Tim the architect explaining the basics of graph theory. I didn’t need to know the whole shebang, but I needed to know some of it to move forward.

(15:40)

Play it back to validate

No matter how much we context together, and create our shared language through this diligent use of a dictionary, or be open to teaching each other in all of these little asides; we will always carry a lot of assumptions.

Sometimes these are explicit and documented. And that’s fabulous. But sometimes they are implicit and hidden, which is less fabulous. Playing it back is a way to reveal your thought, rationale, your logic, your steps. The parts that got you to that point. And doing so with your team regularly is a great way to uncover the hidden assumptions. Those unknown unknowns which help you to avoid very expensive mistakes.

In practice, what this looks like is: I’ve just designed a UX workflow. Awesome. Before I lock it in, I play back the thinking to the engineers or the architect on the team, so that we can validate my thinking and assumptions against things like the data model. What this might show is, ah, the data model doesn’t actually have a provision for this at this moment, we can’t account for that. Which may mean that I need to change my design. Or it might mean that we need to change the data model. But either way, we spotted it early.

The second thing to think about is begin a sentence with, “let me play that back to you”. Actually have a go at playing back what you understand back to them. So if an engineer makes a change to the data model - how might this impact the UX or the UI and play it back and check that we’ve both got it. And the other thingto do is keeping this front of mind. Do I need to go and talk to the engineer? Do I need to talk to the designer? Will this impact? If you get that gut niggling feeling, do it. It might take 10 to 15 minutes, but you might find that you have a big saving after it.

(17:33)

Break down language barriers

Now, between our two practices, there’s a language barrier problem. I know we all know this. And in an engineering-led environment, when it’s actually engineers who are the majority, and designers that are the minority, you, the engineer, need to be the translator. That’s on you. You need to be in a heightened state of awareness. Taking extra care with empathy to rephrase or reframe in a way that your designers can come to the table and actually get on board. Because if the designers aren’t understanding, it’s not because they’re dumb. It’s because it just hasn’t been explained well enough for them to be able to make sense of it.

So, here’s a few sentences you can try to get over this hurdle.

“Did that make sense?”
“Can you play that back to me?”
“Can I explain it in another way?”

You’ll be really surprised how powerful doing this can actually be.

And pro tip. Most designers, they actually think visually first. Stick men are fine. If you can draw this, it will actually help to unlock it a lot quicker so don’t hesitate to pick up that pen and go to that whiteboard. Let me just give you an example. And this is a real-world example. Take the concept of one to many [relationship]. Imagine we’re in a conversation where Content is 1, and Author is N. That all makes sense to you. That doesn’t make sense to me. News flash, I went to art school. I understand a lot about products, a lot about people, and how to get people and products to work together. But I didn’t study relational databases, and I’m probably not going to either. So, we’re in a bit of a gulf here. Sorry. You, the engineer, [need to] unpack this for me. Ah, a Post has a single Author, an Author can have many Posts - amazing, I got this. Now I can contribute. When the Author wants to transfer the Authorship to somebody else, what happens? Is there a provision for that? What if the Author wants to edit that later? How do they do that? Is that sorted? How are we going to grouped these, under the author or something else? Can I have categories?

(20:01)

And suddenly we’re back to beautiful greatness, heading towards the product of our dreams.

So, engineering-led design. These are the five very early stage kind of behaviors that you can really champion. So why bother?

Well, as engineers, what you’ll get out of this is you’ll receive designs that are much more in line with engineering thinking. They’ll be more viable for the schema that you have actually undertaken. As a multidisciplinary team, you’re going to be able to discuss constraints and negotiate tradeoffs much more effectively and efficiently than ever before. You will be able to make better decisions in a faster context. And you’re going to uncover things that you didn’t know were there.

(21:06)

You’re going to get a lot more wins, a lot more bang for your buck. And ultimately, I promise, you will have a better time doing it. I’m no longer just a designer. I’m an engineering-led designer these days. And when we adopt an engineering-led mindset, design can thrive within an engineering-led environment. And as engineers, you’ve got the power and are crucial to making this change. Give these behaviors a go. You’d be amazed at how much it’s going to improve your products. And when you do, come and tell me about it because I will be dying to know. Thanks so much.

Building with Monorepos

Wed, 04 Mar 2020 00:00:00 GMT

Monorepos are everywhere in the React community from design systems and apps to open source libraries. Being able to work on multiple packages together is powerful, but it’s not without its problems. Emma Hamilton shows you how to solve these problems by exploring the evolution of Emotion’s monorepo.

Targeted extensibility: Lessons learned from building Atlaskit

Tue, 04 Feb 2020 00:00:00 GMT

Often when building a design system we face tension between consistent and resilient API’s that encapsulate valuable and reusable logic, and sufficient flexibility to ensure that our components can be customised to fit bespoke product use cases. Towing this line is difficult, and becomes more difficult as a design system scales. Charles uncovers some of the hard-learned lessons towing this line in React-Select, and Atlaskit – Atlassian’s Design System.

Keystone 6 featured on the SyntaxFM podcast

Mon, 30 Dec 2019 00:00:00 GMT

Wes Bos talks about Keystone. Best practices, things to avoid, and why you should check it out.

How to safely inject HTML in React using an iframe

Fri, 13 Dec 2019 00:00:00 GMT

Why (in most cases) you shouldn’t use dangerouslySetInnerHTML

As the react documentation says, dangerouslySetInnerHTML is React’s replacement for using innerHTML in the browser DOM. In general, setting HTML from code is risky because it’s easy to inadvertently expose your users to a cross-site scripting (XSS) attack.

In fewer words, dangerouslySetInnerHTML isn’t safe.

Why?

let’s say that you have a database with a bunch of article in HTML format that you want to display in your React app. Using dangerouslySetInnerHTML that would be quite easy to achieve:

function MyArticle({ articleId }) {
  return <div dangerouslySetInnerHTML={getArticleFromDB(articleId)} />
}

The problem with this is that the HTML you are injecting to your app could be malformed, it could have CSS/JS that breaks your app, or even worse, JS that steals data from your app.

How to make an iframe secure?

In order to make the iframe really safe, you need to add extra restrictions to the content inside of it. To do that, you should use the sandbox attribute.

<iframe id={IFRAME_ID} name={IFRAME_ID} sandbox="allow-same-origin" />

You should avoid using both allow-scripts and allow-same-origin, as that lets the embedded document remove the sandbox attribute — making it no more secure than not using the sandbox attribute at all.

How to inject and update the content in an iframe?

Here you have two options:

by using the iframe attribute srcdoc (which is not supported by IE and Edge)
by using the iframe.document.open()/write()/close()

Using srcdoc

the srcdoc property allows you to specify the content of the iframe, so using it is quite simple:

<iframe
  id={IFRAME_ID}
  name={IFRAME_ID}
  sandbox="allow-same-origin"
  srcDoc={iframeContent}
/>

Unfortunately srcdoc isn’t supported in IE and Edge. There is a polyfill but it isn’t useful in this case because it requires allow-scripts (and remember that’s not safe)

Using iframe.document.open()/write()/close()

This method is not straightforward as using srcdoc, but it works the good thing is that works in all browsers.

const IFRAME_ID = 'my-iframe'
const IFRAME_CONTAINER_ID = 'my-iframe-container'

export const ArticleBody = (props: Props) => {
  useEffect(() => {
    const setIframeContent = (body) => {
      const currentIframe = document.getElementById(IFRAME_ID)
      const iframeContainer = document.getElementById(IFRAME_CONTAINER_ID)
      if (iframeContainer) {
        const newIframe = frames[IFRAME_ID]
        if (newIframe !== null) {
          const iframeDocument = newIframe.document
          iframeDocument.open()
          iframeDocument.write(`${body}`)
          iframeDocument.close()
        }
      }
    }

    setIframeContent(props.body)
  }, [props.body])
}

Conclusion

I hope you’ve found this article useful! Start a conversation with the author in Twitter on what you think about this article.

Thinkmill in Space

Thu, 21 Nov 2019 00:00:00 GMT

Borg Cube

Ever since I saw this particular variation of the Thinkmill logo, a cube-shaped ship travelling through space came to mind.

I’ve always wanted to base a drawing on Thinkmill, and this logo was the key! The spaceship idea manifested inside my head.

Months passed, gathering ideas in my head for what else could be drawn beside the spaceship. What came to mind were the tools we use day-to-day.

The Thinkmill spaceship dominates the middle of the picture. A fleet of support ships nearby.

What follows is a breakdown of everything in the picture, piece by piece!

Thinkmill
Gelato Refill
Node.js
GraphQL
React
Keystone
Design
Explorer
Gelato Servery
Satellite
Moon Base
Other

1. Thinkmill

The largest ship of the fleet

Front Top Deck — From here commands are given to the crew and the rest of the armada by the captain and senior members. A wide variety of informational displays show ship status, planets in range, map coordinates and so on.

Back Top Deck — Engine columns, one of which is currently experiencing issues. Stasis tubes positioned behind, where crew members float in a deep sleep, receiving nutrients via a variety of tubes.

A gelato dispenser sits serving coconut and dark chocolate gelato — a staple of the crew.

A door leads into the gelato manufacturing room, taking in ingredients from tubes connected to the roof from a supply ship.

The ship departure date from Earth is above the sliding back door, currently displaying 24th June 2019. The date the drawing was completed.

Current versions of Keystone, GraphQL and React display on information panels on the back wall as well as other stats.

Bottom Deck — The lower deck of the ship, used for transport and storage — a one-man scout ship is departing, a Node harvesting ship lies dormant.

Roof — A variety of antennas and radio communication equipment. A hatch for repair drones. Intake points for milk, cream and sugar lead to the gelato manufacturing plant.

An array of solar panels power the ship and store energy in large battery arrays.

2. Gelato Refill

Crew members have nightmares about the tentacle-like tubes

The Thomas Walker Gelato refill ship supplies the ingredients for gelato manufacturing on the main ship.

While refilling, the ship hovers close by, extending its three floating tentacles and pumping milk, cream and sugar into the main ship.

The ship can move both in space and a planet’s atmosphere, allowing it to refill with supplies.

This ship is also featured in my other drawings and is a recurring feature.

3. Node.js

The crew have started observing strange side effects from handling pieces of Node

Throughout the galaxy are crater-filled Node asteroids. This is the main source of fuel aside from React.

Harvesters dispatched from the main ship have a crew of miners inside. Their job: dislodging chunks of Node material from the craters using specialised jackhammers.

While the crew are outside, suits and helmets protect the crew from the harshness of space, providing oxygen and life support systems.

Once the Node material is collected, it’s taken back to the harvester and finally hauled back to the main ship for processing.

The Node asteroids are the shape and pattern of the Node.js logo

4. GraphQL

Space is limited, the crew often don’t last more than a few days

Another hexagon-shaped ship called the GraphQL is a ship computer system used to define, process and output data based on parameters.

Linked to the main ship and used for most of the calculation and data storage work to help traverse space.

The GraphQL ship resembles the shape of the GraphQL logo

5. React

Crew members enjoy swimming through the React material — the material eventually floats back into its original position

React, like Node.js, is a critical part of the equation of ship refuelling.

Floating in space often shaped like an atom symbol, these resource particles are most abundant and plentiful in the middle of the ring.

Pockets of them are also found orbiting planets in a ring shape.

A vacuum ship nearby extends a tube, sucking all the React particles into the ship’s storage and then back to the main ship for processing.

The atom shape resembles the shape of the React logo

6. Keystone

Here we see a ship disappearing into the portal for destination [ ‘ | + * && / : !! == ‘ ; — ] ? ! { . ‘ “ — who knows what they’ll find!

Discovered on a recent trip light-years away: the Keystone object.

An ancient artefact of unknown origin and time, it is a critical tool that allows Thinkmill to explore the universe.

A circular gate-like device marked with punctuation stones, that allow the crew to form a set of coordinates.

Once a sequence is locked and the destination exists, a portal opens to travel at faster-than-light speeds to unknown lands.

More and more punctuation symbols are being found as time goes on, increasing the many different places the crew can travel to.

A major downside to the device is that it is only big enough to fit transport ships. So it is only used scouting purposes.

When the entire armada needs to travel, it can often take months to reach the destination.

The Keystone name comes from the four keystone objects with the letter K lodged into them.

keystone | ˈkiːstəʊn | noun
a central stone at the summit of an arch, locking the whole together.
• the central principle or part of a policy, system, etc., on which all else depends: cooperation remains the keystone of the government’s security policy.

The four keystones on the circular object resemble the K in the Keystone logo

7. Design

Pushing around these anchors points is hard work, they keep floating away

Thinkmill’s design efforts are lead by the crew working together, using a series of anchor points and paths in space.

Here we can see the crew creating a large Thinkmill logo.

Once anchor points are set, the object gets analysed, minified, and used on various ships akin to a 3D printer.

8. Explorer

A stark piece of design paving the way for the future of the Thinkmill fleet

Made possible by Keystone’s technological findings, Node.js and React fuel deposits, and the design teams expertise, the Explorer is a brand new class of ship, designed to explore the universe at much faster speeds than before.

The Explorer is T-shaped as homage to the Thinkmill name.

Command resides at the top of the ship behind a giant class facade, traditional telescopes and paper maps have been digitised for navigation.

9. Gelato Servery

Eating 3 cups or more induces a euphoric effect

Besides serving gelato on the main ship, Thinkmill also has a dedicated gelato servery ship.

Usually manned by Thomas Walker himself, the zero gravity gelato cups float inside the gelato cup-shaped ship.

Crew members who are out and about stop at the servery whenever they feel like taking a break during the working day.

10. Satellite

10,000 down / 10,000 up

Long-range communications are the job for the satellite ship, square in shape with two solar panel arrays and a powerful satellite dish.

Along with an array of monitoring equipment — this ship provides a lifeline back home when light-years away in space.

11. Moon Base

Reminiscing of Total Recall

Still under construction, the Thinkmill Moon Base has become a launchpad to other planets in the system and an important supply hub.

Mining machines have excavated two craters thus far: one an access hatch, and another an exhaust system.

12. Other

Watch out for those moving traffic lights in 3D space

An array of other objects have their place around the Thinkmill fleet. Nearby Saturn provides an alternative source of React material. Transport ships cruise around with mobile traffic light systems. Comets are a regular sight, and another moon resides in the distance.

That about wraps it up for the drawing. I had a lot of fun creating it. It’s my biggest drawing yet with another one in the works.

Progressive Rendering — The Key to Faster Web

Thu, 21 Nov 2019 00:00:00 GMT

Note: The content of this post may be relevant to all types of servers but written within the context of a node.js server. The perf metrics are assumptive and may differ based on network bandwidth and latency.

To understand progressive rendering we must first understand how client side rendering and server side rendering work.

Client Side Rendering

Client side rendering is the technique in which the server sends a simple HTML without any content in the body and script tags in the head. This is what create-react-app builds output.

Typical page load behaviour in CSR —

Browser requests the server for HTML
Server sends HTML with script tags in head and no content in body
Browser parses the HTML and makes http requests to load the scripts
Once the scripts are loaded, the browser parses them and makes API requests and loads all the content asynchronously

Client side rendering

Since the all the content starts loading only after loading the initial JavaScript, it takes a longer time to show any content on the page. If the user is on a slow network, the content is blocked for an even longer time due to lower bandwidth and higher latency.

Client side rendering FP metric

Pros

Once the initial JavaScript is loaded, the content can be loaded asynchronously. We can load the critical content first and then load non-critical content later.
Server serves static HTML and initial load JavaScript bundles can be cached in the browsers which may benefit frequent users.

Cons

Initial load JavaScript blocks content load. The larger your bundle size is, the longer it will take to show content on the page.
API requests to load content have to travel all over the world to fetch data as they are not co-located with the browser location. This may take even longer in slower networks due to high latency and low bandwidth.
SEO scores take a huge hit since search engines don’t execute JavaScript (arguably) and only an empty page is indexed. This matters when you want your page to be public and searchable.

Server Side Rendering

Server side rendering is the technique in which the whole HTML is rendered on the server and sent to client. This is what Next.js or Gatsby (build time server render) does.

Typical page load behaviour in SSR —

Browser requests the server for HTML.
Server makes API requests (usually co-located) and renders the content in the server.
Once the page is ready, the server sends it to the browser.
The browser loads and parses the HTML and paints the content on the screen without waiting for the JavaScript bundle(s) to load.
Once the JavaScript bundle(s) are loaded, the browser hydrates interactivity to DOM elements, which is usually attaching event handlers and other interactive behaviours.

Server side rendering

Since the APIs are usually co-located with the server, the content is loaded super fast (faster than CSR) and the HTML is sent to the browser. Initial JavaScript load doesn’t block content load as the HTML sent by the server already has the content.

Server side rendering FP metric

Pros

Since the server serves HTML with content, neither the browser nor search engines have to depend on JavaScript for the content.
Content is not blocked by the time taken to load JavaScript bundle(s).
Page loads a lot faster than CSR.

Cons

The entire HTML has to be rendered on the server before sending it to the client. This means, even the non-critical content has to rendered on the server to before sending the response HTML to the client.

Progressive Rendering

Progressive Rendering (aka Progressive Server Side Rendering) is a technique in which once you render the critical content on the server, you start streaming it to the client without waiting for non-critical content. You then stream the non-critical content later once it’s rendered on the server. The browser starts to progressively render (paint) the HTML on the page as soon as a chunk for critical content is received. Non-critical content is then later rendered (paint) on the page when the browser receives it from the server.

Typical page load behaviour in PSSR —

Browser requests the server for HTML.
Server makes API requests (usually co-located) and renders the critical content first in the server and streams it to the browser.
The browser receives the chunk of HTML and renders (paints) it on the screen.
The server renders non-critical content after rendering critical content and streams it to the client.
The browser receives and renders (paints) the non-critical content later.
Once the entire page is loaded, the browser hydrates interactivity to DOM elements, which is usually attaching event handlers and other interactive behaviours.

Progressive rendering

Progressive rendering bridges the benefits of both CSR and SSR. Content is rendered quickly since the APIs are co-located in the server and at the same time, critical content can be rendered quickly without having to wait for non-critical content.

With Progressive Rendering, you can make your site load faster asynchronously without relying on JavaScript to load content.

Progressive rendering FP metric

The whole idea of progressive rendering depends on the concept of streaming HTML from the server to client. You can read more about it here.

You often get magnitudes of performance boost if you do PSSR right. Here’s an example of the same website rendered with SSR vs PSSR. (Assuming the site is loaded over a low bandwidth network with high latency).

SSR vs PSSR

How to progressively render a page?

Node.js has this Readable API which will let you pipe a readable stream. An example code to stream HTML might look like this

router.get('/stream', async function (req, res, next) {
  res.status(200)
  res.type('text/html; charset=utf-8')

  // myRendered renders the HTML content
  const DOCTYPE = await myRendered.DOCTYPE()
  const openHTML = await myRendered.openHTML()
  const head = await myRendered.head()
  const openBody = await myRendered.openBody()

  res.write(`${DOCTYPE}${openHTML}`)
  res.write(head)
  res.write(openBody)

  const pageChunks = [
    myRendered.header,
    myRendered.criticalContentOpen,
    myRendered.nonCriticalContentOpen,
    myRendered.nonCriticalContentClose,
    myRendered.criticalContentClose,
    myRendered.closeBody,
    myRendered.closeHTML,
  ]

  const pageStream = new Readable({
    async read(size) {
      if (!pageChunks.length) {
        pageStream.push(null)
      } else {
        const chunkToRender = pageChunks.shift()
        const renderedChunk = await chunkToRender()
        pageStream.push(renderedChunk)
      }
    },
  })

  // stream content as soon as they are rendered
  pageStream.pipe(res)
})

The example for this website built with Express and vanilla JS is here —

https://github.com/flexdinesh/progressive-rendering

The idea is you predictably slice portions of your HTML content and stream it to the browser as soon as it is rendered.

Pros

Render on server but stream critical content to client without waiting for non-critical content.
Content is not blocked by the time taken to load JavaScript bundle(s).
Page loads a lot faster than both CSR and SSR.
Build fruitful user experiences even for users on slower networks.

Cons

The browser will hydrate the DOM and attach event listeners only after the whole page is loaded. Even though content shows up quickly, interactivity will be enabled only after non-critical content is loaded. (But showing up content a lot quicker is still a win).
There is no established framework for progressive rendering and is highly dependent on the web application and its limitations.

Tips for effective progressive rendering

Load critical CSS in the head
Using CSS grid for layouts removes the dependency on the order of how the content is streamed

That’s all folks.

Drop a comment below or start a conversation with the author in Twitter on what you think about this article.

Introducing Preconstruct

Wed, 06 Nov 2019 00:00:00 GMT

A year ago, I was experiencing lots of problems maintaining Emotion’s build system so I set out to make a build system to solve the consistency and reliability problems in a repo with many packages and this eventually turned into Preconstruct. It’s working really well on projects like Emotion and React Select so I’m super excited to finally share it!

What Does Preconstruct Do?

More than just bundling, environment-specific builds, and ES Module + CommonJS targets, Preconstruct also takes the pain out of setting up your package.json, and just Works when importing your unbuilt files from within both single-package repos and monorepos. It might be a bit more opinionated than other tools so it might not work for every possible use case but we think that supporting fewer use cases in a more complete way is better than supporting every possible use case in non-ideal ways.

Supporting fewer use cases in a more complete way is better than supporting every possible use case in non-ideal ways.

Preconstruct’s model

Preconstruct has a concept of a project which contains one or more packages with one or more entrypoints which lets it work on small and large projects. For some projects, you might only have a single package which only has one entrypoint. Some projects might have many packages with lots of entrypoints.

Example of Preconstruct projects

Source Module Resolution

Because Preconstruct is designed with monorepos in mind, it handles the problem of “I want to test/use a package but when I import it I get the dist file so I have to rebuild it everytime“. With the preconstruct dev. command, Preconstruct will create files that redirect back to your source code so you can import those. When running in Node, Preconstruct will even use a require hook to compile your code with Babel automatically.

Multiple Entrypoints

Packages can have multiple entrypoints(e.g. react-dom and react-dom/server). Entrypoints are first-class citizens in Preconstruct so they have all the same multiple module formats as a package with a single entrypoint has.

Strict Validation and Auto Fixing

Preconstruct will validate as much as it can to make sure your package works. This includes making sure the values of your main and module fields are correct and fixing them if they’re not which is especially helpful when managing a large number of packages. It’ll also make sure that your dist files will be included when your package is publishedOn so you’ll never publish a package but forget to add the dist files to your package’s files field again.

Getting Started

Assuming you already have a source file at src/index.js (or src/index.ts) or you’re using Yarn Workspaces and have packages with src/index.js (or src/index.ts), you can setup Preconstruct like this.

yarn add --dev @preconstruct/cli
yarn preconstruct init

If you’re in a monorepo, you should also run yarn preconstruct dev and add it to a postinstall script("postinstall": "preconstruct dev") that runs preconstruct dev so that you can import your code without having to rebuild your project every time in changes.

Publishing packages

Before you publish packages to npm, run yarn preconstruct build. Preconstruct will use your Babel config and build flat bundles so make sure to configure Babel with the transforms you want.

We strongly recommend making a single script in your package.json that runs both build and publish, to stop broken publishes, such as "release": "preconstruct build && yarn publish:packages". If you’re in a single-package repo, you could instead run preconstruct build in a prepare or prepublishOnly script.

Try going through the docs to learn more:

Preconstruct is built with a ton of amazing tools like Rollup and so many others!! Preconstruct also wouldn’t have been possible without the support of Thinkmill. 💝🎁

Building React Select

Thu, 31 Oct 2019 00:00:00 GMT

Jed talks about how he accidentally built the most popular React component, experienced death by a hundred props, got buried under hundreds of PRs, invented a component extension API, learned that styles are also a function of state, influenced some major design systems and finally got some sleep.

React Dev Tools - Debug like a ninja

Sat, 14 Sep 2019 00:00:00 GMT

React team launched a new version of the React Dev Tools (v4) a few weeks ago and it’s fantabulous. It gives you debugging superpowers to navigate through your tree, trace data flow, spot weak links and optimise for perf.

There are two separate tabs (Components, Profiler) now as opposed to the old version which had only one React tab.

React dev tools tab

New Dev Tools has great many improvements over the old version. To highlight a few —

🏎 Faster
🎣 Hooks support
🧐 Advanced tree filter
🤠 Better search UX
👮‍♀️ Badges for HOCs
🎯 Remembers selection after page reload

Top 10 Features

Dev Tools can do a lot of things. We’re are not going to dive into the nitty gritty details of each and every feature. Instead we’ll take a look at the top 10 helpful features that help us save time and write better React code.

Components Tab

Live edit state/props
Search through tree
Advanced tree filter
Rendered by
Owners tree
Quick Navigation
Utils

Profiler Tab

Profile initial mount
Why did this render?
Rendered at

1. Live Edit State/Props

You can live edit the state and props of a component and instantly see the results in the page.

Watch video

2. Search Through Tree

The search bar comes handy when you want to quickly find and jump to a component in the tree. Now that the Dev Tools can remember stuff the selected node is saved between reloads and you don’t have to repeat the action every time you reload the page.

Watch video

3. Component Filter

Filter is a powerful feature to reduce visual noise and focus on what matters at the moment in a huge tree. You can filter with a variety of options like context, HOCs, host(DOM) nodes, component name, etc.

Watch video

4. Rendered By

Rendered By is a list of owner/parent components that rendered the selected component. You can quickly jump to a parent component by selecting an entry from the list.

Watch video

5. Owners Tree

Owners Tree gives you an eagle eye view of a particular component and its sub-tree and hides the rest of the component tree.

To enter into owners tree view, you have to double click a component in the tree.

Watch video

6. Quick Navigation

Switching between Elements tab (browser dev tools) and Components tab (react dev tools) is pretty easy and the corresponding node is auto selected in these tabs.

To find the corresponding DOM node in the Elements tab, select the component and click the small eye icon on the right pane. It will take you to the Elements tab with the corresponding DOM node selected.

To find the corresponding React node from Elements tab, just select a node in Elements tab and click the Components tab. React Dev Tools will automatically select the corresponding component.

Watch video

7. Utils

Components tab offers three small handy utils.

Suspend component
Inspect matching DOM element
Log component data to console

Suspend Component

You can easily switch between the waiting(loading) and resolved states of Suspense components.

Watch video

Inspect matching DOM element

We already saw this in Quick Navigation. You can select a component and click the eye icon on the right pane to jump to its corresponding node in Elements tab to inspect it.

Watch video

Log component data to console

This is a handy utility that logs the entire component meta data to the console. The log gives details like props, hooks, corresponding DOM nodes and the component file location in the file system.

To log component data to console, select the component and click the small bug icon in the right pane.

Watch video

Intro to Profiler

The next three features are going to be about the Profiler. Before diving into them, we’ll take a look at how profiler works and the key metrics that are used during profiling.

Every profiling session has two important colour graphs —

Commit graph
Component graph

Dev tools profiler breakdown

Commit Graph

Commit graph gives you a list of commits (whole tree) during the session. Each commit denotes a user activity or side-effect that triggered a render in the tree .You will see it coloured from orange to green with orange denoting the costliest (took most time) commit and green denoting the cheapest (took least time) commit.

Component Graph

Component graph gives you info on which component rendered during a single commit. You can select each commit from the commit graph to see its component graph. It is also colour coded with cost information —

Dark Grey — Component did not render but a part of its sub-tree rendered
Transparent Grey — Neither the component nor its subtree rendered
Coloured — Both the component and its entire subtree rendered

8. Profile Initial Mount

Initial mount and first render is usually a perf heavy op in most React applications. In older versions of Dev Tools, it was impossible to profile and audit the initial mount phase. But the latest version provides an option to profile and audit the initial mount.

Watch video

9. Why Did This Render?

This is the most powerful feature of the Dev Tools yet and it tells you why a component rendered during a profiling session. A component might have rendered for one or many of these reasons —

Props changed
State changed
Hooks changed
Parent component rendered

You can profile an activity and see why a component rendered during the profiling session to spot weak links and prevent unnecessary renders in the tree.

Watch video

Note: You have check this setting — “Record why each component rendered while profiling” to see this info in the right pane of the Profiler Tab.

10. Rendered At

Rendered At info on the right pane gives you two time metrics —

When exactly the component rendered during the profiling session
How long it took for the component to render during the profiling session

Eg. 2.2s for 2.3ms

Here, 2.2s means the component rendered at 2.2s(2200ms) from the start of the profiling session which is 0s. And 2.3ms is the amount of time it took for the component to render.

Watch video

That’s all folks.

If you’re interested in exploring all the features, the React team has built a site just for that — Interactive Dev Tools.

Play around with Dev Tools and drop a comment below or start a conversation with the author in Twitter on what you think.

Introducing Keystone 5

Thu, 15 Aug 2019 00:00:00 GMT

It’s not just a new version of Keystone, but a complete re-imagining of KeystoneJS for the future.

Keystone 5 builds on the lessons learned over the last 5 years of the Keystone’s history and focuses on what we believe are the most powerful features for modern web and mobile applications.

This means less focus on template-driven websites and more focus on a flexible architecture, a powerful GraphQL API with deep access control features, an extensible Admin UI and plugins for rich field types, file and database adapters, and session management.

We believe it’s the ideal back-end for React, Vue or Angular applications, Gatsby and Next.js websites, Static sites, Mobile applications and more.

Open source

Keystone is proudly open-source and allows individual and commercial reuse and modification. The code is freely available on GitHub.

Zero assumptions

Keystone is not opinionated about your front-end architecture. It works great with React, Vue, Angular, or anything else you like to use.

Keystone also tries to make zero assumptions about your data structure allowing you to build any type of application. It achieves flexibility through small, highly composable parts that allow you to build a foundation for any application.

Don’t need ‘Users’ or ‘Posts’? Not a problem! Keystone’s extensible architecture means you choose the features you need. Pick an ideal starting point, rather than working hard to adapt an opinionated framework.

Fully featured

Zero assumptions doesn’t mean zero features. Keystone comes with dozens of features out of the box including Lists, Fields, Access Control, Authentication, and Apps. You can add and configure each these, as well as extend, modify or build your own.

Lists

Lists define a set of Fields that make up a collection in Keystone. A List might represent a content type, such as a “Page” or “Post”, but they can be any collection of data. Creating a List is how you define the data structure of your application.

Fields

Fields represent a data type. They are used in Keystone for everything from rendering components in the Admin UI, to configuring Access Controls, to generating a GraphQL API. Keystone has dozens of built-in Field types and as always, you can create your own.

Access Control

Keystone has powerful Access controls that can be configured on Lists and Fields to define the specific actions authenticated and anonymous users can take within the Admin UI or GraphQL Apps.

Authentication

Authentication refers to a user identifying themselves and “logging in” to an application. Keystone provides multiple authentication strategies including a basic password or third-party authentication services, such as Twitter and Google.

Once again, authentication strategies are configurable and extensible allowing you to create your own login methods.

Apps

Keystone uses Apps to compose high-level features into a larger application.

A Keystone index.js file exports two things, a Keystone instance, and Apps:

module.exports = {
  keystone,
  apps: [
    new GraphQLApp(),
    new StaticApp({ path: '/', src: 'public' }),
    new AdminUIApp({ enableDefaultRoute: true }),
  ],
}

From a technical perspective Apps are simply bundled express middleware that accept configuration options. Essential Keystone Apps include the GraphQL App, Admin UI App, and Static App.

GraphQL App

The GraphQL App is the keystone App of KeystoneJS. It provides a powerful GraphQL API with CRUD operations and powerful filtering options for all your lists.

Admin UI App

The Admin App is a fully functional administration UI to help you manage your data.

Static App

The Static App allows you to serve content from a folder using an express static server. This can be quick and easy way to deploy a simple front-end with a Keystone application.

The Static App, along with other Keystone Apps, can decoupled from the main application and deployed separately if required.

Note: Apps like the Static App provides an alternative to Keystone 4’s views and templates engine.

Headless

Keystone is headless, meaning it requires no front-end application. Keystone 5’s primary focus is on the API and Admin UI. It is non-prescriptive about your front-end application. Because of this Keystone 5 works with all major front-end frameworks.

Self host

Own your own data and host Keystone anywhere. Have complete freedom of choice when hosting your data, admin application, API and front-end applications.

BYO Database

Keystone allows you to choose different storage methods. Adapters for MongoDB and Postgres are available now, with additional adapters in development.

Because of its extensible architecture, Keystone is not even explicitly tied to a database. You could create adapters for file-system storage such as SQLite or even JSON and cloud storage options. We hope to see many more adapter options in the future.

Field level adapters allow you to fetch or store data for specific fields separately from your main storage location. Examples include uploading images to Cloudinary or fetching information via o-embed links.

Getting Started

Keystone has a high level of configurability when you need it, but most customisations are opt-in and Keystone provides sensible defaults to help you get started quickly.

Create your first Keystone 5 project in seconds:

npm init keystone-app my-app
cd my-app
npm run dev

This will configure a simple Todo application. Then visit http://localhost:3000 to see it in action. 🎉

See the complete Getting Started Guide for more details.

🙏 Thank you

A huge thanks to our Core Contributors, who have been working hard on tackling all the challenges that come with building such a powerful CMS like Keystone 5:

Tim Leslie (@timl)
Jess Telford (@jesstelford)
Emma Hamilton (@emmahamiltown)
Joss Mackison (@jossmackison)
Jed Watson (@jedwatson)

And all those who have supported the development; Nathan Simpson, Mike Hazell, John Molomby, Dominik Wilkowski, Ben Connolly, Jared Crowe, Luke Batchelor, Ticiana de Andrade, Gautam Singh, and Ajay Narain Mathur.

And of course, a massive thank you to the Keystone Community; without you, none of this would be possible ❤️

What about Keystone 4?

Keystone 4 is alive and well! Going forward, we will hand the npm packages over to our community leaders who can continue to help it grow, merge bug fixes, and add new features. As the Keystone 5 alpha nears stable release, we will communicate more details.

Thanks to Emma Hamilton, Jess Telford, and Joss Mackison

How I prototyped a social network with Keystone

Sun, 23 Jun 2019 00:00:00 GMT

Nathan Simpson shares how he built "The Garage" – a social network for car lovers, using Keystone 5 and React Native.

On design systems legibility

Mon, 14 Jan 2019 00:00:00 GMT

A design system that nobody can understand is a design system nobody can use. This is why good documentation is so key to having a well-used and well-loved design system. Noviny walks you through two of Atlassian’s documentation sites for the company-wide design system & component library Atlaskit, showing how the content is built and written, and the practical steps you can take immediately to tackle the hard problems around large documentation projects.

Rebuilding React-Select

Fri, 16 Mar 2018 00:00:00 GMT

Jed discusses the upcoming React Select 2 and his experiences working in open source.

Creating Apps with JavaScript

Wed, 18 Nov 2015 00:00:00 GMT

Tom and Boris discuss and demonstrate how (and why) to prototype UI animations and interactions before development, and how to build a native-quality app for SydJS using web technologies.

Content Management & Node.js

Wed, 18 Nov 2015 00:00:00 GMT

Jed Watson talks about Content Management Systems in Node.js.

Prototyping: Solutions vs. Interactions

Thu, 22 Oct 2015 00:00:00 GMT

As prototyping apps and tools become increasingly common, they are also becoming increasingly sophisticated. When I wrote the post about prototyping UI animation, Origami had just been released, Pixate was in early private beta (and not yet owned by Google), and you could still count the number of dedicated prototyping tools on one hand.

Now, there’s an abundance of tools to suit your approach.

All of these tools are good at some things. Many of them are excellent at lots of things, and in the right hands, add immense value to the design and development of an application.

I head up UX and Interaction design at thinkmill so I spend a good portion of my time translating ideas and concepts into interfaces and interactions. Over time the distinction between prototyping a solution vs. prototyping interactions has become very clear, and with it, the appreciation of which tools are best suit to each function.

While both solution and interaction prototyping are part of the broader design function, but they are not the same thing. They are complimentary but distinct, like designing the database schema is complimentary but distinct from architecting the system.

Why is the distinction important?

There’s nothing revelatory above, so why does it matter? With better tools, those of us who were previously restricted to paper sketches, Photoshop/Sketch and hand waving can get a little over-excited. It becomes tempting to attempt to prototype everything. However well intentioned, avoid the temptation. Diminishing returns kick in very quickly when prototyping.

The trick is to prototype the right things — the necessary things — rather than all the things.

The Solution Prototype

In the very early stages of a project, the first milestone is articulating a sane, high-level solution. Put another way, I’m trying to answer two questions:

how could this system work?
how could the user interact with this interface? q (Note could rather than should above. Assume you don’t know what anything should be like just yet).

At this stage we’re trying to articulate a solution that doesn’t have glaring holes, and weed out obvious problems in the user experience. A solution prototype (as opposed to an interaction prototype) allows others to provide meaningful feedback with the benefit of a bird’s eye view.

I’ll use Sketch and Flinto to quickly stitch together static screens into a user flow, and sanity check the interface.

(Side note: I used to hand sketch on the iPad and then jump into Photoshop, but the Sketch workflow has made this step largely redundant — in case you need another reason to use Sketch).

It’s important to note that at this early stage, I’m not particularly concerned with optimising anything, only articulating the solution as completely as possible, based on limited information.

Parts that obviously don’t flow or make sense are quickly identified and fixed through iteration. With each iteration the prototype gets more refined and detailed (bot not very detailed yet) and comprehensive. Then, at some point, with enough iteration and feedback, I reach that magical point when I can run through the solution prototype and have it “hang together”

This is the time to switch gears and dive into interaction prototyping.

(I am, of course, over-simplifying here. There’s a ton of evaluation, testing and discussion of the solution prototype that goes on between these two stages).

When the system architecture and information architecture hangs together well enough, I use interaction prototyping tools like Edge Animate and more recently Flinto for Mac, to develop the feel and flow of the interface. This happens in “spots”, meaning I’ll take the key views and view transition and visualise those particular interactions. For example:

Watch video

To repeat the point above: do not try and build an app inside a prototyping tool. Worrying about managing application state while prototyping interactions is the worst kind of quicksand.

How do the tools compare?

While I could write a post for each — and others have done — here’s a few quick thoughts for now:

Solution Prototyping

Flinto / InVision / Marvel / …others

Actually, Sketch is the most useful solution prototyping tool, but in order to validate UX flow, Flinto is my personal preference here. Between dropbox integration that automatically updates screens as you export, scroll slices and the magic connector, it’s very fast to string together screens into a navigable interface. It’s bare bones otherwise as far as features go. There’s a handful of views transitions available and a neat preview. The fact that I can’t get fancier than navigating between screens is a good thing at this stage. I get to a “yep this works at a high level” point faster.

InVision has been around the longest (citation needed) and was a little late to the mobile prototyping game. I find the featureset richer, but the workflow slower. Marvel I’ve only recently started playing with and have little to say other than it seems nice.

Interaction Prototyping

Flinto for Mac / Edge Animate / Framer / Origami / …others

This field is a lot broader and your tool of choice will depend very much on how comfortable (or not) you are with writing code.

If you are familiar with JavaScript (erm, CoffeeScript specifically), there is arguably no better interaction design tool than Framer. It has very good Photoshop and Sketch integration and writing code means there’s little you can’t do. On the other hand, if you can’t or don’t want to code, it’s not for you.

I’ve written about working with Edge Animate in-depth previously. It’s an under-rated (un-cool) interaction design tool, and is all the more attractive because it caters to both comfortable coders and those who are not, with timeline-driven interactions. Gesture design can be harder to do compared to Framer, but that might not be a deal-breaker for you. Compositions can also easily be compiled into native apps using PhoneGap Build.

More recently, the folks at Flinto released Flinto for Mac. The most striking thing about it is that it’s not just a desktop client for web app, rather it’s a fully-fledged interaction design tool, with an excellent Export from Sketch plugin that preserves layers and groups from your Sketch files. I design with interaction in mind, so going from layer groups in Sketch to animatable layer groups in Flinto is a huge time saver. Perhaps most interestingly, there’s no concept of a timeline, as there is in just about every other tool. Instead you define a start and end states, and then control the delays + easing curves between the scenes. I’ll admit it took a while to wrap my head around the concept, but once I did, it makes a lot of sense.

(I discovered later that there are good tutorial videos explaining everything on Flinto’s site).

What about Origami? Origami is actually a patch library for Apple’s Quartz Composer node animation tool. Credit to the Facebook team, Origami makes Quartz Composer usable/useful and being a node animation tool there is no code or coding required — everything is point-and-click. When you wrap your head around the sequences of patches that are required to achieve an effect or design an interaction, it becomes a pretty powerful tool. On the other hand it is one of the most frustrating interfaces you’ll ever use. Changing values requires a double click on a tiny number field. To add a patch shortcut you must hover a mouse pointer precisely over a ~5px circle, lest it insert the patch in the wrong place. And Quartz Composer is such a resource hog that my MacBook Pro (i7, 16gb ram) spins its fans hard enough to reach low earth orbit. It’s not for me, but I suggest you try it for yourself in any case.

It feels like Origami / Quartz Composer proved that there is clear and present need for dedicated interaction prototyping tools, based on which a a new wave of tools has come into existence. Kudos for that. It’s certainly getting better every day.

Summary

Understand the difference between prototyping a solution vs prototyping interactions within that solution
Use the right tool for the job (you should use at least two different tools)
Avoid the temptation to build a complete app in prototype — only build the important stuff
Bonus point: try Origami and see if you can work out why anyone would.

Going Mobile with React

Thu, 11 Jun 2015 00:00:00 GMT

Jed shares what we’ve learned approaching the unique challenges of building mobile web apps with React.

Making the case for Progressive Javascript

Tue, 17 Feb 2015 00:00:00 GMT

Read on to learn why.

Quick background

The web development community has been in love forever with the idea of writing code that can be shared across the server and the client. Or maybe that’s just me? Nope, not just me.

We’ve flirted with technology for a while now that we’ve hoped will achieve this holy grail, but recently between node.js and React.js it’s become a reality we can reach out and touch. (er, write. In JavaScript.)

Which means we’re up to the second Hard Problem In Computer Science: naming things.

I mean, instead of “transferring JSON to and from the server without a page refresh” we have AJAX. There’s no way “writing JavaScript that we can run on the Server and the Client” is going to fly.

So far, for lack of a better term, we’ve mostly been calling it “Isomorphic Javascript”. And then arguing about how that’s a terrible term for it.

Remember Progressive Enhancement?

It was a Good Thing. We started understanding how we could write web apps that were baseline-level functional without JavaScript, while being “progressively” enhanced with richer functionality as the visitors’ platform of choice (probably not IE6) supported it.

Apps like Flickr and Basecamp showed us the future, and jQuery helped us implement it ourselves. Capable browser? here’s a nice date picker! oh, no JavaScript? that’s cool, we’ll validate your input on the server.

Accessibility loved it! Good semantic markup makes screen readers happy.

Google loved it! Quality HTML is King for ranking in search results.

Users loved it! Apps were faster, and more interactive.

Web Developers loved it! … well … sort of.

Yes, it was great we could launch an MVP and progressively enhance it with fancy client-side coolness. And oh, all those plugins!

But… all of a sudden we’re writing all our code twice. For the client, and the server. We’re also testing our code twice. And designing two user experiences. And we’re forking our UI; some things work with JavaScript, others don’t.

Actually… that’s a lot of work.

Enter Progressive Javascript

The name works for me on a number of levels.

Firstly, it’s the best description I’ve heard of what’s going on.

Here’s the Wikipedia definition of Isomorphism:

Isomorphism is a very general concept that appears in several areas of mathematics. The word derives from the Greek iso, meaning “equal,” and morphosis, meaning “to form” or “to shape.”

So I guess Isomorphic Javascript has equal shape on the server and the client? Nope. It doesn’t. Different code paths will run; different features are available. It’s just that you can write one set of code that executes in both environment and shares as much as possible.

The JavaScript runs on the server. Then it’s sent to the client and continues. There it does more. Handles interactivity. Takes over.

Here’s a definition of Progressive:

Progressive; adj. happening or developing gradually or in stages.

Sounds pretty spot on to me.

Secondly, this whole concept seems like the natural evolution of what we were solving with Progressive Enhancement.

The Web Platform has come a long way. Chances are we’re supporting IE9 and wishing it was just IE10+. We’ve got grids for responsive resizing, and flex-box will soon help us forget we ever used tables for layout.

But mainly, it’s pretty safe to assume JavaScript will just work. Everywhere. On the client, and on the server (and the database, and your drone, and…)

There are still important reasons for server-side rendering. Deep links. Accessibility. Faster page loading. And, of course, SEO.

But since we can run JavaScript everywhere, we now have better solutions to the same problems we were encountering with Progressive Enhancement.

We can stop designing two user experiences. We can stop writing everything twice. And since we have less to worry about, we can be more productive. This will literally help us progress faster.

This is Progressive JavaScript.

Love it? Hate it? Have a better idea? Let me know on Twitter: @JedWatson

My first year of Open Source Commitment and KeystoneJS

Mon, 01 Sep 2014 00:00:00 GMT

Today marks one year of my GitHub streak, and coincidentally the first birthday of my company Thinkmill.

It’s also, roughly, a year since I released the first prototype of KeystoneJS, the open source Node.js CMS / web application framework I created.

When I started KeystoneJS it was to enable myself and others to develop node.js projects more efficiently, and I had no idea how it would be received by the Javascript community or other developers.

I was totally new to Open Source, and with no profile, followers or momentum I decided that committing to working on it every day (regardless of what I was doing commercially or personally) would be a great way to establish trust with other developers interested in using it. It was my way of saying “this isn’t just a throwaway project from someone you haven’t heard of that could be abandoned next month”.

It turned out to be so much more, and has been an amazing experience — definitely one of the best things I’ve ever done.

In the last year, Keystone has gained over 1,700 stars on GitHub, 260 forks, over 50 contributors, nearly a thousand followers on Twitter (@KeystoneJS), and is downloaded over 4,000 times a month.

We have used it to power websites and apps with hundreds of thousands of users in production, and other companies large and small are adopting it as a base for their own projects.

But the real surprise has been the impact that maintaining my streak has had on my life.

Most days its easy; I’ve got lots to do on Keystone, and love working on it.

Some days its hard; I’ve worked all-nighters, gone on a family holiday to China, or had nothing I can think of doing in the time I’ve got to do it.

But I’ve made a commitment so I do it anyway. And looking back, the hard days are the ones that have made the experience great.

When I’m not inspired, I’ll go through issues and find something minor that I can fix. Or I’ll write some tests. Or I’ll add something simple that’s been requested that I haven’t gotten around to while working on larger issues. This happens every day. And the great thing is the sum of all these little things.

This story wouldn’t be complete without explaining my wife’s support. About a week in, I told her what I was doing, and she was on board.

She’s seen the excitement when I think I’ve done something cool. And the joy when someone I don’t know submits a great PR. And the pain when I’m flat out and stressed and tired and need to do something in the next 30 minutes because otherwise I’ll break my streak.

Earlier this year, when we landed in China on holiday (and I thought I’d take a break) my wife challenged me about why I’m doing this, and encouraged me not to break my streak. She made me realise:

I’m no longer doing this to prove something and I’m not doing it for anyone else. I’m doing it for myself.

I’ve learned the power of sharing your work with others and becoming part of a community. I’ve had the opportunity to solve interesting and challenging problems. I’ve had the opportunity to give talks and workshops at meetups and conferences. And I’ve had the opportunity to meet (and collaborate with) amazing people from all over the world.

And now, almost every day, something happens with Keystone that just makes me happy. All because of something I created, and my commitment to it.

About a hundred days in, I found out I wasn’t alone. John Resig (@jeresig, author of jQuery) wrote an excellent post on his commitment to code every day and the impacts it has had (he is currently at 280 consecutive days).

These ideas aren’t actually specific to open source or even programming. If you have anything you’re passionate about — whether it’s writing, music, learning, or anything — committing to doing something every day is a powerful way to achieve it.

And it’s surprisingly easy. You get used to it. It becomes part of your rhythm. You get over the hard parts, and enjoy the result.

My streak won’t continue forever; I’ll have a proper day off again when I’m ready. But the experience has changed my life for the better, and KeystoneJS has taken on a life of its own with new core contributors, and major improvements in the works.

To celebrate, and to acknowledge that KeystoneJS is now the sum of many developers, community members and users, I’ve graduated it out of my personal profile and into its own organisation on GitHub.

We’ve got big plans for what to do with it from here. We’re rebuilding the Admin UI in React to enable developers to rapidly build web apps more effectively, and creating a whole plugin / customisation system. We’re abstracting common (or what should be common) functionality into separate packages. We’re going to enable model-based API creation with much less work, and a whole lot more.

I’m so excited about what we can do to make node.js so much more streamlined to develop apps with, as well as the teaching aspect of what we’re doing, that my wish for KeystoneJS on its first birthday is just that I can spend more time working on it.

In the meantime, it’s been a great first year!

Prototyping UI Animation

Sun, 03 Aug 2014 00:00:00 GMT

Interaction design with Edge Animate

Update: this post is now a couple of years old. Tools for prototyping UI animation have (happily) improved greatly since I wrote this, and certainly Edge Animate and PhoneGap belong more in 2014 than 2017. FWIW Sketch + Flinto is my current preferred pairing. Happy reading.

As an interaction designer who is more comfortable with pixels than code, I use Animate to quickly turn sketches and Photoshop comps into interactive and animated UI prototypes that run as “native” apps on mobile devices.

Below is my process for designing the interactions and animations for a simple app–for SydJS, a local JavaScript meetup–that allows members to confirm attendance, view upcoming talks, get reminders when meetups are scheduled, etc.

Get the source PSD + Edge Animate composition
Get the app source code (we open sourced everything)

The state of prototyping tools

Flinto and InVision excel at quickly wireframing an app using only screenshots.
Framer is a prototyping framework targeted at designers that can do basic JavaScript (CoffeeScript)
Quartz Composer is Apple’s node editor for masochists (kidding) that was recently popularised by the Facebook Paper team. However it’s quite old, buggy and comes with a particularly steep learning curve (though it’s very powerful once mastered).

Edge Animate is in a kind of sweet spot at the moment. You can do most things visually, but if you’re also comfortable with basic JavaScript, you can make sophisticated interactions and take many shortcuts.

My object here is not to persuade you to use any one tool over another. In fact I strongly encourage you to try them all. Designing interactions and animations for user interfaces is a relatively young discipline and the ecosystem of tools is both very young and changing rapidly.

Edge Animate 101

Animate is the spiritual successor to Adobe’s Flash (complete with timeline, symbols and javascript) that outputs HTML5/CSS3/JS which can be quickly deployed as a native app using PhoneGap.

It’s not for making production-ready apps. But it is very useful for designing and prototyping app interactions and animations as an input into the development process.

If you’re entirely new to Edge Animate, I recommend you check out the getting started resources from Adobe and get familiar with the basics. There are a lot of great video tutorials to get you comfortable with the interface and basic concepts.

If you’ve used Flash before, you’ll feel right at home.

Timelines & Keyframes

Here we’re saying: 'When we touch the btn-talks symbol, set its opacity to 50%'

Timelines and Keyframes are central to the composition.

At its most basic, a timeline is simply visualisation of changes in properties over time.

Keyframes define the “extremes” — the start and end values of properties, such as X/Y coordinates, opacity, etc. Together they are the buildng blocks of all animations.

Symbols

Think of symbols as encapsulated objects that have their own independent timeline. In our context, symbols typically represent interactions or views within an app. Symbols are particularly useful because they can be manipulated with user-triggered actions (eg. tapping a button causes a view to slide in from the bottom).

Here we’re saying: “When we touch the btn-talks symbol, set its opacity to 50%”

Triggers and Actions are what gives the composition interactivity. Triggers are events that exist on a timeline (e.g., at 500ms stop playback). Actions are usually user-triggered events (e.g., on touchstart, set opacity of element to 50%).

Part 1. Setting up

I prefer to get into Animate after a stint in Photoshop where I’ve designed the main views in the app and exported assets like icons and images.

Nothing like a blank canvas. Here we’re setting up the composition dimensions to represent an iPhone 5 portrait view.

Nothing like a blank canvas. Here we’re setting up the composition dimensions to represent an iPhone 5 portrait view.

We’re prototyping for iOS here, so I’ve set the dimensions of the composition to 640 x 1136px for an iPhone 5.

There’s an amount of pre-planning that should go into the composition before you start. I’ll typically break up the comp into its primary views:

Loading view (transitions to the Home screen)
Home screen (w/ RSVP buttons, reminder prompt)
Upcoming talks (overlay)
About the meetup (overlay)
With a mental map of how the comp will be organised, we can play.

Part 2. Animating

Home screen

Before adding actions and triggers that control interactions, I start by building the animations that I want to see and to get the timing right.

When the app starts up, I want a seamless and continuous transition from the initial loading screen that displays a static logo while the app is loading, to the main view where the user can begin using the app.

As the Home screen is loaded, I want to move and fade several UI elements into place. I start by laying out the ‘end’ view, then I work backwards, plotting keyframes on the timeline to define when and how I want elements to transition into view.

For example, the RSVP buttons slide it from the bottom, followed shortly by the buttons at the top of the UI.

Here’s the keyframe view, slowed down:

Watch video

Even though the entire transition lasts less than ½ of one second, animating elements in, rather than simply making them appear, gives the interface a far more natural feeling. Remember that in the real world, few things appear before your eyes instantly.

RSVP buttons

The buttons in this composition are a little fancier than your average button. I want them to transition from their neutral state to a representation of the user’s RSVP.

Here’s what we’re doing here:

Changing the relative width of the two buttons and their text label
Changing the colour of the button to indicate state
Hiding the unnecessary label and showing an ‘x’ in its place
Showing the ‘add to calendar’ button (if attending)

The 5 states and 4 animations for our buttons

The 5 states and 4 animations for our buttons

There are 5 states these buttons can be in, which gives us 4 sets of animations, like so:

There are “stop” points between each transition that represent the 5 button states from the previous image.

There are “stop” points between each transition that represent the 5 button states from the previous image.

Next, we want to make sure the button labels animate with the button widths. The attending label will get wider, while the not attending label will be animated out of view. In its place we’ll fade in an ‘X’ to indicate that this area of the button will now cancel the previous action.

Rather than simply hiding the label and showing the ‘X’, we’ll tween the transitions with easing.

Avoid hard cuts as much as possible. In the real world, nothing ever appears

Avoid hard cuts as much as possible. In the real world, nothing ever appears

Part 3. Adding interactions

Triggers and Actions allow us to control the timeline based on predefined events and user input, which in turn adds interactivity to what would otherwise be a movie.

Depending on how interactive you want your app prototype to be, you can add as many or as few actions and triggers as you like.

I prefer to be conservative and add interactions only where necessary. The point of prototyping is to move rapidly and have the freedom to experiment broadly. Adding interactivity can quickly add unwanted overhead in the form of having to maintain an complex composition. Leave this to the development stage.

My rule of thumb is if it’s obvious what action precedes the animation, it doesn’t need to be made interactive. Save your efforts for other things.

Let’s look at the RSVP button interactions in detail.

The RSVP button interaction is encapsulated in a symbol with an independent timeline. We have 5 keyframes representing all the states that these buttons can be in. At each point we have a stop(); trigger.

At each of the marked points above, the trigger is simply sym.stop();

At each of the marked points above, the trigger is simply sym.stop();

After 200ms, stop playing the timeline

“After 200ms, stop playing the timeline”

Why? Because we want the animation to be paused between state changes until the user taps on the button again.

To achieve this, we’ll bind a “play” action to the “on-click” event for the button. It looks like this.

Animation action

The action above simply causes the playhead in the symbol’s timeline to play, until it reaches the next “stop” trigger.

Remember: we’re working within the timeline of the symbol and not the main timeline, so this action is relative to this symbol. These actions are not affecting the main stage timeline.

We now have an interactive element that plays through a scripted timeline in response to a user action.

Hit ⌘+Return to preview the comp and interactions in the browser. When you’re ready to see how it feels in your hand, you can deploy it as a native app relatively quickly and easily.

Part 4. From Edge Animate to an App

This is the most valuable step and one of the main reasons I like Edge Animate. It’s one of the easiest methods for quickly bringing an idea to life with interactions and animations that you can install as a native app.

Interactive prototypes are a great test of the hidden assumptions in a design. You’ll quickly discover poor UX and conceptual gaps, which is the main reason this kind of prototyping is so useful.

Prototyping consistently creates better interaction designers as well as better apps.

You’ll need a PhoneGap account, and an Android and/or iOS developer account for the next part.

Prepare your composition and assets

After you hit publish, you should have a folder that looks something like this:

After you hit publish, you should have a folder that looks something like this:

First, your composition must be saved as index.html. This is what PhoneGap will look for at runtime. When you’ve saved your comp, use the Publish option to compile all the assets you need in PhoneGap.

Go ahead and compress the folder now. The zip file is what you’ll upload to PhoneGap in a minute.

Certificates & Keystores

This is the only tricky part of this process. Because we’re effectively creating a “real” app, we need to have our papers in order.

If you’re deploying to iOS, you’ll need a .p12 certificate and a provisioning profile. Check out the PhoneGap docs for help with this step.

If you’re deploying to Android, Lynda.com has a handy video tutorial

To create the .keystore file that you’ll need, plug this into your terminal window (replacing “app_name” with your app’s name):

keytool -genkey -v -keystore app_name.keystore -alias app_name -keyalg RSA -keysize 2048 -validity 10000

You should end up with a app_name.keystore file. Drag it into your folder above.

Adobe BD screen

PhoneGap

Create a new app in PhoneGap. Install the .p12 certificate and then upload the .zip file you created above as the source. (If you’re building an Android app,follow these steps in the Lynda video)
Enable hydration. This will check for a new build in PhoneGap every time you open the app on your device. A time saver when you deploy new builds. Upload an app icon. There’s no excuse not to with icon templates aplenty. Pro tip: don’t upload a rounded, transparent .png because you’ll get ugly edge ghosting in iOS. Upload a square icon and let iOS do the rounding for you.
Install the app to your device by logging in to the PhoneGap website using your phone and simply hit the download button. If you’ve done it right, you should now see your Edge Animate comp installed as an app.
Rinse & Repeat. As this will probably be the first time you get to touch your prototype, you’ll probably want to go back into Animate (or maybe even Photoshop) and start tweaking, iterating and redeploying. If you feel like you nailed it first go, you’re doing it wrong. I’ll typically go through this cycle ~20 times before I’m happy.

To deploy a new build of the app:

Re-publish from Animate (don’t just hit ‘save’, use Publish)
Zip the folder as before
Upload new .zip to PhoneGap
Relaunch your app

The hydra process should alert you to a new build and show you your latest version.

To wrap up

This is just one example of one process for prototyping animations and interactions for mobile apps. Edge Animate is one of the tools that suits my way of thinking and my skill set. (I’m learning JS so will play with Framerjs next). There’s no perfect tool for our discipline so open your mind and experiment until you find a tool (or two, or three) that suits you.

It’s a bloody exciting time to be an interaction designer!

Thinkmill

What AI use looks like in five enterprise design teams

Somewhere to prototype

Diverging approaches

Hand-rolled vs off-the-shelf tools

Sandboxed vs wired to production

Converging features

Shareable, hosted URLs and CLI commands & helpers

Control panel UI

Fidelity control and rules-based output adjustment

In prototype comments

Context is what makes the difference

Design system context

Project context

Customer context

Supporting adoption

What to get right first

From Vibes to Durable Context

Agents will fill the gaps

Engineering still happens before implementation

More documentation is not always more context

Make the decisions executable

Faster implementation raises the stakes

Is Your Design System Ready for AI?

A component library is not a design language

What makes a design system AI-ready?

Access is getting better

Defaults carry more weight now

Start with the mistakes

AI exposes the gaps

Build vs buy: AI code review for teams that have opinions

Your team is already doing AI review

What buying gets you

Centralised rules for the win

Built means model-agnostic. Bought means resold.

What the build "costs"

My recommendation

Optimise Your Context, Not Your Prompts

The prompt wasn’t the problem

Improving the environment

Let’s not get carried away

Look at what your team keeps correcting

Workarounds become part of the system

Optimise your context

Where AI Actually Helps Quality Engineering

Making behaviour testable

Shortening feedback loops

Carrying context into release and beyond

AI as a force multiplier

Why Great Engineering Still Wins

From implementation to judgement

Better context, better outcomes

Great engineering still wins

Designing beyond the median user

Designing for nobody

The near-solutions

Jobs to the rescue?

A framework for the fringe dwellers

The failed escape

Three things converged

1. The atoms became reliable

2. The data became reachable

3. The platforms met a new consumer

A new architectural response to the old debate

Bounded generation

Anchored intent

What might change going forward

What engineering teams owe for the AI speed boost

A behavioural framework for the monsters in your team

What the report unearths

Who’s the monster here?

How to do better than Victor

Lab notes for the curious

Why your design system is the most important input to Claude Code

The problem with fast generation

What a design system actually gives Claude

The output quality difference is stark

How to wire this up with CLAUDE.md

The design system is now the spec

What this means in practice