Solara: Developer documentation made coherent by one visual system, from page layout to component spec.

A developer should be able to find a function, understand it and question the code.

Solara's documentation had to help developers both evaluate the framework and work with it. Its growing audience, then over 2,000 GitHub stars, encountered jargon-heavy reference pages without a clear browse structure.

As the sole designer on a five-person product team, I connected the documentation's page layouts to a 100+ component Figma library. The same type, spacing and interaction rules carried from Quickstart to API reference; error reports and GitHub links sat beside the code they concerned. Separate Figma files kept exploration apart from the designs engineering could build.

My Solara work covered two parts of the same brand. The marketing site helped visitors understand the framework and decide whether to use it. This study covers the documentation developers use to find functions, read code and work through errors.

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

Solara bridges notebook work and web applications. Built on ipywidgets, it runs in Jupyter Notebook, JupyterLab and standalone servers. Following Widgetti's Q4 2023 framework update, the team was preparing the website to support enterprise licenses.

We researched Next.js and Retool as competitors. For the documentation itself, I used Stripe as a structural benchmark: a three-column page, errors treated as part of the reference, and information organized around the reader's task.

A written spec set the scope before any layout did.

Before drawing layouts, I wrote a functional spec for product and engineering to challenge. It defined goals, non-goals, success measures and risks without asking anyone to commit to a visual direction.

The scope covered navigation, a dashboard-like API reference and a consistent experience across solara.dev. Content creation stayed out. That boundary concentrated my work on taxonomy and browse paths; rewriting technical explanations would require a separate content effort.

Existing research pointed to logs, code review and a clearer route into the framework.

I started with discovery interviews another team had conducted for the beta launch. I organized those notes and existing feedback, used them to recruit survey participants, and asked a customer-success teammate to review my questions.

Three priorities emerged: useful text logs, less friction in code review, and onboarding that made functions easier to find. Requests for external-facing apps and a mobile app builder also suggested that the documentation would need to serve more than internal-tool use cases.

I used those priorities in reviews with product and engineering to decide which pages and interactions to develop next.

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

I used three columns to keep navigation, reference content and page anchors distinct. Typography and spacing gave long technical pages a consistent rhythm; the component library carried those rules into each template.

The harder visual decision was where to use orange. Solara's brand color did not provide enough contrast for critical interface elements on light backgrounds. Dulling it would weaken the identity, so I used neutrals for essential controls and reserved orange for hover and active treatments on known backgrounds. The documentation could remain quiet at rest while still belonging to the same brand.

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

Feedback about text logs led me to give errors a place in the page design. The design names and links errors within the prose, and a “Report incorrect code” modal lets a developer flag the code block they are reading. The report starts with the relevant content already in view. The interaction recordings on this page come from the Figma prototype.

I treated GitHub as a destination for a specific task. “Edit on GitHub” appeared in the fixed sidebar, on section-header hover and in the page-footer feedback block. Each placement offered a route from the passage a developer was reading to a correction.

The proposed navigation put component reference two clicks from Quickstart.

I reviewed the navigation redesign with product and engineering. 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

The redesigned navigation stayed at the prototype stage; the recordings below come from that prototype.

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

I prototyped the API reference, component dashboard, docs homepage, content pages and Quickstart at four breakpoints. Mobile covered 320–767px and tablet 768–1023px, followed by desktop and large desktop.

The annotations specified behavior across each range: minimum widths, what could stretch, and where horizontal auto-layouts became vertical. Local variables set command-bar and frame padding to 48px on desktop and tablet, 24px on mobile. Desktop prose stayed between 500 and 750px wide so extra screen space didn't turn into longer lines.

“Ready for dev” frames included those rules beside the design, with both ends of wide breakpoint ranges shown.

The documentation carries Solara's visual identity into everyday development work.

I carried the typography, spacing and color language from the marketing site into the documentation, then specified the components and states that documentation work needed.

As the sole designer, I developed the library from named styles to semantic variables and then component-level tokens. Ridd's Figma Academy 2.0, which I was taking at the time, gave me a useful vocabulary for that increasing specificity.

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

Once the same system had to serve the documentation as well as the marketing site, I rebuilt it 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.

I chose that precision knowing component-level tokens would multiply and cover less of the system. The library reached 49 semantic colors, 27 mode-aware primitives and over a hundred specified components.

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

A standing review document linked every prototype, its four breakpoints and the design files. I divided the work across seven files:

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

The boundaries mattered more than the file count. Playground and sprint work was outside development scope; final pages lived in Dev handoff. Foundations supplied the primitives used by the style guide. All-caps pages identified prototypes. I documented the temporary exception of keeping product and marketing color styles in the handoff file while the work was mostly in design.

A shared Google Workspace queue and Slack discussions kept review decisions visible to the team. The files gave those decisions a stable destination.

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.

Reviews with product and engineering checked the API taxonomy, component pages and handoff specs against how developers looked for functions. Research feedback kept Quickstart, reference pages and contribution paths in focus while the layouts changed.

I presented the prototype at an all-hands in Q2 2024. Every screen mapped to a documented Figma component, so the team could review both the experience and the system behind it. Calls to action and core information were validated against WCAG 2.1 AA in the design.

The design gave the team a shared reference, and the relaunch brought developers to Solara.

The prototype and library gave product and engineering a documented direction for continued work, and the components that were cheapest to implement were built first.

In October 2024, solara.dev received 96,231 referral visits from 137 referring websites, led by design communities, developer-software directories and programming resources. That traffic followed a relaunch of Solara I worked on with the team. I designed the new brand, marketing site and documentation, and built the slide deck Maarten Breddels and Iisakki Rotko presented at PyData Paris 2024 in late September. Solara's leadership promoted the framework at the same time, and both efforts fed the growth.

By November 2024, after the marketing site launched, Solara reached 170,000 monthly downloads. That milestone belongs to the whole product, with the framework engineering behind much 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.

Solara changed how I size a design system. Each architectural upgrade answered a real need, but the library grew faster than one engineer could implement it. A Storybook pipeline worked, and a small share of the library went through it, starting with the components that were cheapest to build. A system's useful scope is what the team can adopt and maintain.

The written spec and the separate files, each with one job, helped us review the work together. I would keep that clarity while matching the depth of component tokens more closely to the engineering capacity available.