Solara: A visual system that makes a Python framework feel ready for production.

Documentation is where a developer decides whether to trust a framework. I redesigned Solara's.

Solara lets developers build web applications in pure Python. For an open-source framework, the documentation is where a developer decides, often within minutes, whether to trust it with production code. Solara had a growing user base (2,000+ GitHub stars), but its reference pages leaned on jargon and lacked a clear browse structure.

I was the sole designer on a five-person product team. I organized the documentation around three developer tasks: finding a function, understanding how to use it, and reporting a problem without leaving the page. A 100+ component Figma library, a semantic color system and seven purpose-specific Figma files gave engineering one consistent reference for that work.

The visual identity and marketing homepage from the same engagement are covered in the Solara marketing site case study.

As Solara matured, its documentation had to support enterprise adoption.

Developers often stall when moving a data project from a Jupyter notebook to a scalable web application, because the work belongs to a different discipline. Solara closes that gap. Built on ipywidgets, it runs in Jupyter Notebook, JupyterLab and standalone servers.

Widgetti, Solara's parent company, shipped a well-received major update in Q4 2023, before I joined. As the framework matured, the team began preparing its website and design operation to support enterprise licenses. We researched competitors such as Next.js and Retool.

For the documentation, I benchmarked against Stripe, whose developer docs are a strong example of documentation that helps people evaluate a product as well as use it. I borrowed its structure rather than its look: a three-column page, errors treated as first-class content, and writing organized around the reader's task.

A written spec set the scope before any layout did.

I scoped the work in a functional spec shared with product and engineering: goals, non-goals, success measures and risks. I kept it in prose for as long as possible, so engineering and product could challenge the scope without reading a design file, and so no early layout became the model everyone anchored to.

The spec had two goals: make the documentation intuitive to navigate, with a dashboard-like API reference, and keep one cohesive experience across solara.dev. Content creation was explicitly out of scope. That made one boundary important: voice and plain language belonged to content, while taxonomy, browse structure and the distance to the right page belonged to the design. The redesign addressed jargon through that structure.

Developer feedback pointed to three priorities: text logs, code review and onboarding.

A different team had run discovery interviews for Solara's beta launch before I joined. I organized their notes and existing feedback, used them to recruit survey participants, and had a customer-success teammate review my questions before they went out.

Insights

1. Developers highly value text logs.
2. A smoother code review process leads to higher developer efficiency.
3. An efficient onboarding experience makes Solara functions easier to find.

Respondents also named external-facing apps and a mobile app builder as future priorities, so the documentation structure had to scale beyond internal-tool use cases. From there, design reviews with product and engineering set priorities as feedback came in.

Neutral surfaces carry the content; Solara's orange appears on interaction.

Every page follows the three-column documentation convention: navigation rail, reference body and on-this-page anchors. The dark-mode interface, typography, spacing and interaction patterns stay consistent from Quickstart to component reference, all built from the Figma library.

The brand color explains why the interface looks quieter than the brand. Solara's orange is central to the identity, but it fails contrast against light backgrounds and against text at interface sizes. Using it on every button would have meant either an inaccessible page or a duller orange that no longer matched the brand. So neutrals carry critical elements, where contrast requirements are strict, and orange appears on hover and active states, against a known background on an element the developer has already found.

Error reports and GitHub links sit next to the content they concern.

The strongest research insight, that developers value text logs, shaped the error design. Errors are named in the prose and linked to their explanations. A developer who distrusts a code block can report it from the page it sits on, without leaving the documentation.

GitHub links followed the same principle. Most documentation sites pin a GitHub link to the top navigation, which puts an external link in the most prominent position on the page. I placed "Edit on GitHub" in three spots instead: the fixed sidebar, the hover state of each section header, and the feedback block at the foot of every page. Each sits beside the content a developer is reading, so leaving for GitHub comes with a specific reason, such as a correction.

The proposed navigation put component reference two clicks from Quickstart.

The navigation redesign was reviewed with product and engineering and remained a prototype. It addressed three problems in the existing structure:

Before

• API reference buried in generic Quickstart pages
• No taxonomy for browsing components
• Unclear path from install to production code

Proposed

• Component pages one click from API navigation
• An Input / Output / Viz browse structure
• Quickstart to API reference in two clicks

Four breakpoints, one template, with each range designed around its worst case.

Every core page was prototyped at four breakpoints: mobile (320–767), tablet (768–1023), desktop and large desktop. That covered the API reference, component dashboard, docs homepage, content pages and Quickstart.

Responsive behavior was specified on the canvas beside the frames. The dev notes defined one fully responsive template, command-bar and frame padding driven by local variables (48px on desktop and tablet, 24px on mobile), and auto-layouts that switched from horizontal to vertical on mobile. Each page carried a "Ready for dev" status.

On desktop, prose columns stayed between 500 and 750px, so wider viewports added margin and figure space rather than longer lines. Because a breakpoint is a range, the notes also said which elements held a minimum width and which could stretch, and wide ranges were shown at both their narrowest and widest points.

Three token-architecture upgrades, each reasonable, together more than one engineer could implement.

As the sole designer, I made the design system's architectural decisions. The token architecture changed three times as the scope grew. I use the specificity ladder from Ridd's Figma Academy 2.0, which I was taking at the time, to describe the stages: value, primitive, semantic, component.

Stage 1: styles only

The system began with semantically named Figma styles such as bg-base and border-strong, each documented with a hand-maintained light and dark swatch pair. Styles have no mode axis, so dark mode meant maintaining a duplicate palette by hand. That suited the early scope and was archived once the scope changed.

Stage 2: semantic variables

When one brand had to cover both the documentation and the marketing site, I rebuilt the system on variables, with a semantic layer between raw values and usage. The Product Color Palette changelog dates it: "July 4, 2024 — tons of styles → variables."

Stage 3: component-level variables and modes

Dark mode added a mode axis. The "Primitives reversed" collection mapped neutrals/50 in light mode to neutrals/950 in dark, 100 to 900 and so on, so one semantic token produced both themes without duplicate palettes. I then went further, down to component-level tokens such as input-bg.

The course warned that tokens this specific cover less of the system and multiply quickly. I chose them because dark mode seemed worth the precision. The result was 49 semantic colors resolving through 27 mode-aware primitives and 100+ specified components. It was also more than one developer could implement. The components engineering could build cheaply shipped; most of the library stayed in Figma, despite a working Storybook pipeline.

Seven Figma files, each with one job, told engineering which designs to trust.

A standing design review document gave engineering one entry point to every prototype, each at all four breakpoints, and to every design file. The project ran across seven Figma files:

• Sprint strategy and branding
• Global UI kit
• Global components and assets
• Marketing playground
• Foundations
• Style guide
• Dev handoff

Playground and sprint files were out of development scope. Dev handoff files held the final pages. Foundations held the color and size primitives behind the style guide, and all-caps pages inside a file marked prototypes. While the project was still largely in design, I kept product and marketing color styles in the dev handoff file for convenience, and documented that deviation on the Product Color Palette card.

Team tasks lived in one Google Workspace queue: meeting topics, critique guests and rotating note-taking, groomed during Slack morning warm-ups. I also documented the Figma files, supported UI development in Storybook, ran research in Maze and FigJam, and kept decisions in Slack channels the whole team could read.

Component specs written for the developers who would build them.

Specs lived on the canvas beside the components they governed. The card family is one example: a Big card for marketing pages such as Showcase and a Small card for dense product pages such as the API reference overview, each with a maximum paragraph width (400 vs. 290) and a three-line truncation rule. Status chips marked what was ready, changelogs recorded revisions, and each spec linked to related designs.

Designed for consumption

I didn't optimize component properties for the smallest possible matrix. Collapsing two variants into one clever property can mean fewer components that are harder to use. The most-used components got the most attention, with properties ordered the way designers reach for them; the long tail got correctness. Where two variants were interchangeable, the handoff said so, so developers wouldn't search for a difference that didn't exist.

Annotated for back-end specialists

Solara's implementation sat mostly with back-end specialists, so I annotated further into implementation detail than I would for a front-end team. Ahead of each flow, I answered the questions developers would hit:

• Does this have a maximum or minimum width?
• Is this a fixed width or a percentage?
• What is the copy for the error message?
• What is the empty state here?
• What is the logic for when we show toast messages?
• Which of these fields are required to submit?

Reviews with product and engineering tested the design before handoff.

I took the API reference prototype through structured reviews with engineering and product. We tested the navigation taxonomy, component page structure and handoff specs against how Solara developers search for functions. Survey and interview feedback set page priorities: Quickstart, component reference and GitHub contribution paths came up repeatedly as friction points, and the information architecture changed before visual details were finalized.

By Q2 2024, I presented the prototype at an all-hands, where the team responded positively. The design system gave engineering a shared vocabulary: every screen mapped to a documented Figma component. WCAG 2.1 AA was validated across calls to action and core information in the design.

Solara.dev drew 96,231 referral visits in October 2024, much of it through work I led.

In October 2024, solara.dev received 96,231 referral visits from 137 referring websites, led by design communities, developer-software directories and programming resources. I count that as impact my work largely drove, with contributions from the rest of the team. It is not a result of the proposed navigation, which stayed a prototype.

The reviewed prototype, component library and documented interaction patterns gave the team a foundation for continued product work. Later that year, after the marketing site went live, Solara reached 170,000 monthly downloads by November 2024. That milestone belongs to the whole product, especially its framework engineering, and is context for this work rather than a measured effect of it.

Maarten announced the milestone publicly, describing Solara as a framework teams use "as a replacement for Streamlit when an app grows larger and more complex". A Solara tutorial series also appeared on the official Jupyter Blog.

Bring cross-functional partners in early

When content strategy and engineering constraints arrive in the same conversation, the design stops proposing things that can't be built.

Write the scope before drawing it

The spec's non-goals mattered as much as its goals. Ruling out content creation kept the redesign focused on structure, and the risk register put GitHub-first users, snippet errors and report abuse into the design from the start.

Match system depth to implementation capacity

Each token-architecture upgrade solved a real problem. Together they produced a precise system that one developer could only partly implement, which is now part of how I size a design system.