Flowra design system

Every Flowra screen is built from one shared set of pieces: a few color and size tokens, a few semantic classes, and a few React components. These pages show those pieces live, running the same code as the app itself, and explain why each one looks the way it does.

In codeapp/globals.csscomponents/

What it's made of

The Flowra design system has three layers. The bottom layer is tokens: CSS variables in app/globals.css for color, each with a light value and a dark value. The second layer is semantic classes, like .btn, .card, .pill, and .modal, which define appearance once. The third layer is React components, like TextField, DropdownField, Floating, Dialog, and EmptyState, which define behavior once: keyboard, focus, text direction, and how they adapt on phones.

Alongside these three layers, Tailwind utilities are used only for one-off layout: spacing, columns, order. Any appearance repeated in two places belongs in a semantic class, not in scattered utilities.

Live example

1Tokensapp/globals.css

--bg--card--text--accent--dark--border--green--red

2Semantic classesapp/globals.css

.btn.card.pill.modal.dropdown-menu.sheet-menu.tabbar.badge-soft

3Componentscomponents/

TextFieldDropdownFieldFloatingOptionListDialogActionMenuEmptyStatePageHeaderAvatarIcon

One way to do each thing

The most important rule in this system is simple: one piece for each need. One confirmation dialog, one empty state, one toast, one picker, one avatar. Every time a page wrote its own version, the versions drifted apart; the avatar was once hand-written in 29 different places, and the profile photo only showed up in one of them.

If a piece is missing, add it to the system, then use it on the page.

Don't

Don't build a hand-made, slightly different version of an existing component on a page.

Define a new token with both a light and a dark value in globals.css.

Don't

Don't hard-code color values in a component; they break in dark mode.

How these pages are written

Every component page follows the same order: what it is and when to use it, its anatomy, states with live examples, rules and the reasons behind them, do's and don'ts, accessibility, RTL notes, and the code you write in the project. Each page ends with related pages, linked in both directions.

The examples aren't screenshots. Buttons click, fields accept typing, menus open, and dialogs slide up from the bottom on phones; if you switch the theme or language, everything switches with you.

Where the numbers come from

Every number on these pages is read from app/globals.css or from the component itself, not from a mockup. A selector can be defined several times in globals.css; the last definition with the same specificity wins, and a rule inside @media applies only when its condition holds. That's why every size is stated with its condition: phone, desktop, or touch screen.

Phonemax-width: 640pxPHONE_QUERY in lib/use-phone.ts

Desktop sidebarmin-width: 900px

Touch screenpointer: coarseTouch sizes, independent of width

Real hoverhover: hoverRow hover color only here

Focus ringoutline: 2px solid var(--accent)offset 1px or 2px

Reduced motion0.01ms !importantAll animation and transition

Contrast ratios are calculated with the WCAG 2.1 formula from the light and dark hex values in globals.css. Semi-transparent dark soft colors were composited on --card and then measured.
Wherever a component is still missing something, like a field hint that isn't yet wired up with aria-describedby, it's stated right here, and when it's fixed it changes right here too; the list of gaps is part of the system, not its secret.

PrinciplesSeven principles that all the other rules come from.ColorThe foundation of everything: color tokens in both themes.ButtonsThe most-used component, so you can see what a component page contains.Flowra brandThe Brand kit and its rules, alongside the product design system.

Design system map

Start with Foundations if you want to know why things look the way they do; jump straight to Components if you're looking for a specific piece.

Fundamentals 8

The principles every design decision grows out of: voice, language and direction, numbers and dates, and accessibility.

PrinciplesSeven principles we draw the answer from when there's no rule yet for a new situation.Voice and writingText is part of the interface, not something poured on at the end. Flowra speaks in a friendly, short, precise way, and every string people see goes through one path: tr().Copy rules for each surfaceEvery surface in the interface has its own sentence shape: an empty state says what's missing and what to do, an error says what happened and what now, a confirmation says what will be lost, and a toast says only what actually happened.GlossaryEvery part of Flowra has one name in each language, and it's the same everywhere: in menus, in copy, in email, and in the docs. This table is read from the app's own catalogs.RTL and languagesFlowra speaks nine languages, and two of them, Persian and Arabic, are written right to left. Layout is written once, with logical properties, so it sits correctly in both directions on its own.Numbers and datesNumbers use each language's own digits and separators, numeric inputs accept all three digit systems, and dates inside the app default to the Solar Hijri calendar.AccessibilityEvery component works with a keyboard, tells screen readers what it is, is sized for fingers, and respects a preference for reduced motion. These are built into the components themselves so no page has to remember them.

Foundations 12

The tokens every component is built from: color, typography, spacing, radius and shadow, motion, and icons.

ColorEighteen color tokens, each with a light value and a dark value. No component hard-codes a color; they all read from these tokens, and switching themes just means these variables change value.Dark modeDark mode isn't a second version: it's the same tokens with a second value. data-theme="dark" on html, and a script before hydration reads the preference so the page never flashes light for a moment.PrintingReports and pages are printable: the header, dock, toasts, dialogs, and anything with the .no-print class are hidden in print, the background turns white, and the page column takes the full width of the paper.TypographyOne font family for everything, a short scale of sizes, and weight instead of color to build hierarchy.Spacing and layoutOne 740px column, three breakpoints, and a short ruler of spacing values. Layout starts on the phone and opens up on larger screens.Radius and shadowThe smaller and more interactive something is, the rounder its corners; the higher it sits in the layers, the longer its shadow. All buttons are pills.LayersAnything floating on the page has a fixed layer. The dialog is the highest interactive layer, and only the toast sits above it, because it reports what the dialog just did.MotionMotion in Flowra is short and explains something: where it came from, where it went, and whether it did its job. Five curves and a few durations make up all of it.Notification soundFlowra has two sounds, and both are generated on the spot with Web Audio, with no files: a double chime for a new message and a triple sparkle for an assistant reply.Keyboard shortcutsA few shortcuts that work everywhere. Each one is read by its physical key (e.code), not by the letter, so it works on a Persian keyboard too.IconsEvery icon in the app comes from one source: the paths map in components/icons.tsx, where each is a stroke drawn on a 24px grid and rendered with <Icon>.Service logosThe Google Drive or Zoom logo isn't an icon; it's a trademark, and it's only itself when it's exact. Flowra takes these logos from each company's own published files and never redraws them.

Components 23

The ready-made pieces every Flowra screen is built with, each with a live example, its states, and its rules.

ButtonsOne family, one shape: the pill. Three variants for three levels of importance, one red variant only for destructive actions, and three sizes for three contexts. Every button is a verb.Text fieldTextField is the field in every Flowra form: a label that sits inside the field and rises as you type, and a line beneath it that ripples like water on focus.PickerThere's no native <select> in Flowra. The browser draws its list with the system font, Latin digits, and no dark mode, so every selection comes from one designed list that's a menu on desktop and a bottom sheet on phones.Date and timeDateField opens the Solar Hijri calendar as a floating field, and TimeField opens two columns for hours and minutes. Both use the same floating panel and the same phone sheet.CheckboxA checkbox turns an independent choice on or off in a form that gets submitted later. The box is 20px, but the whole labeled row, at least 44px, is the tap target.RadioA radio picks one of several options when every option needs to be visible with its description. A 20px circle, an 8px dot, and a fieldset with a title.KeyA switch turns a setting on or off immediately, with no save button. It's the same old .toggle, which now has the switch role, the aria-checked state, a focus ring, and a disabled state.Segmented controlA pill with two to five segments for switching the view of one thing: list or board, day or week or month. To a screen reader it's a radio group.SliderA slider sets a continuous value by dragging: field width in Folio, audio playback position. A 6px track whose filled part is orange and an 18px knob; 8 and 24 on phones.Menu and sheetActionMenu is Flowra's "•••" menu: a dropdown under the button on desktop, and an action sheet with finger-sized rows on phones.DialogThe dialog is the app's highest interactive layer: it opens centered on desktop and rises from the bottom like a sheet on phones, with a handle you can drag down.Card and listThe card is the base surface: white on the paper background, with a thin border and a quiet shadow. Lists inside cards are built from rows separated by dashed lines.Tables and data listsFlowra has few tables, on purpose: most data is card rows that read well on phones too. Real tables exist only where columns mean something: the Knowledge table block, Folio, and pitch documents.Badge, pill, and switchA badge labels something, a pill is a control that selects, and a switch turns something on and off. They look alike, but they do different jobs.Tabs and filtersTabs switch the view, and a pill bar filters the content of that view. Tabs have an orange underline; the active pill is charcoal.AvatarOne way to draw anyone's face: their photo if there is one, otherwise the first letter of their name on a circle. Before this component, 29 different places hand-wrote avatars, and an uploaded photo only showed up on the profile page.Empty and loading statesA page that has nothing yet shows an empty box and one sentence: what's missing and how to create the first one. A page that's loading shows the shape of what's coming.Progress and stepsA progress bar shows a known amount: Library storage, seats, a file upload. Steps tell people where they are in a multi-step flow.ToastA small charcoal pill that rises from the bottom of the screen, says what happened, and leaves on its own after a few seconds. For reporting an action that just happened.Floating helpA tooltip is a short charcoal label that appears under the pointer after a brief pause. Since fingers can't hover, it's never the only carrier of information.NavigationOn desktop, two columns at the start edge of the screen: services, and whatever the current service opens into. On phones and tablets, the dock at the bottom of the screen. On desktop, the top bar shows the page name and its main action.Page headerPageHeader heads every page in the app: the title on its own line, one line of description below it, and actions in a separate row. Stacking is what lets a long title and a full row of buttons live together.AssistantsOne pill in the page header opens every assistant, and the whole conversation lives in one window: a dialog sized to the conversation on desktop, and a full-height sheet on phones. One component for every page that has an assistant.

Patterns 8

Combinations that come up again and again: the connector page, filtered lists, creation flows, upgrade prompts, irreversible actions, and the phone layout.

Connector pageEvery tool that connects to external services has a connector page with a fixed shape: live cards at the top, and a "Soon" shelf below that looks exactly like them but has no Connect button.List, filter, and searchMost pages in the app are a list. The pattern is fixed: a compact search box, a pill bar for filters, and a list of rows in a card, with two separate empty states for "nothing here yet" and "nothing found."Form layoutA form in Flowra is a single column, with floating fields and 14px spacing; short labels, hints under the field, errors only on the field they're about, and a submit button that stays enabled until the person presses it.Creation flowCreating something new in Flowra is either a short dialog or a few clear steps. In both, the main action is in the footer, defaults are sensible, and nothing is created until the final confirmation.Upgrade promptWhen a feature isn't in the current plan, the same prompt appears everywhere: the feature name, the name of the plan that includes it, an upgrade button, and, if there's another way, that way.Confirmation and irreversible actionsAn action that can't be undone has a confirmation dialog, and only one: ConfirmDialog, with a red trash can avatar, a sentence that says what will be lost, and two full-width buttons.Phone layoutThe phone isn't a shrunken desktop. Below 640px, a few things change across the whole app at once, in CSS, so no page has to remember them.Fixed bars and scrollingAnything that must always be reachable stays fixed, and only the content scrolls: the dialog header and footer, the app header, the dock, the docs sidebar. The page never scrolls horizontally.

Brand 5

Every Brand kit rule and the reason behind it: name, mark and logo, clear space and size, color, typography, and misuse.

Flowra brandThe Brand kit is what someone outside the team needs to write about Flowra or work with it. This page lays out all its rules and the reasons behind them; the files themselves are downloaded from the Brand kit page.Mark and logoThe mark is one continuous line on a charcoal tile, and the logo is that same mark to the left of the Flowra wordmark. Seven files for light and dark backgrounds, and two rules that keep the logo legible: clear space and minimum size.Brand colorThe brand palette is the same as the product tokens, with names for use outside the code. Tap any color to copy its code.Brand typographyOne family for everything: Estedad, for headings, body text, numbers, and the wordmark, which is Estedad Bold. Open SIL license; free for any use.MisuseSo that Flowra is always itself, don't do these nine things with the logo. Each example is the real file used the wrong way.

What it's made of

One way to do each thing

How these pages are written

Where the numbers come from

Design system map

Related pages

What it's made of

One way to do each thing

How these pages are written

Where the numbers come from

Design system map

Related pages