Get started

Design system for Retool: map brand decisions into the app

A design system for Retool depends on two separate decisions: which source is allowed to define the visual direction, and where each approved decision belongs inside Retool. Configure the theme, component styles, and any necessary CSS. Then verify a named app. Saved settings show configuration; they don't prove adoption.

Updated November 15, 2026

Choose the source before styling the app

Several resources are casually described as a Retool design system, but they answer different questions. Retool's official documentation tells you which application-design controls Retool provides. A commercial theme service supplies a visual direction and implementation help. A DESIGN.md reconstructed from retool.com describes a public website aesthetic for use elsewhere. Retool's IDE retrospective explains how Retool designed its own product. None of these sources inherits another's authority.

Decide which source governs what before entering any values. If an approved company brand system exists, it should govern portable identity decisions such as color roles, type roles, spacing intent, and visual motifs. Retool documentation governs how those decisions can be configured in Retool. The named application still owns its workflows, data presentation, component behavior, accessibility evaluation, and final acceptance.

Authoritative forUseful whenDo not treat it as
Current Retool documentationAvailable Retool controls and official application-design guidanceYou need to configure themes, component styling, layouts, or CSSYour organization's brand authority or proof that an app passed review
Commissioned Retool themeThe contracted design and implementation scopeYou want a prepared visual direction or hands-on implementationNeutral product documentation or automatic acceptance evidence
Approved portable brand systemThe identity decisions explicitly approved within its version and scopeYour company already has a direction that must survive implementationA Retool configuration or a guarantee that every role maps directly
Reconstructed website DESIGN.mdWhat its author observed and described about the public siteYou deliberately want a reference for another codebase and accept its provenanceAn official Retool app theme or evidence about Retool component behavior
Retool IDE retrospectiveRetool's stated rationale for its own IDE redesignYou are studying constraint-led product-design decisionsA customer-app token or component specification
2024 video or community postDated educational context and the capabilities shown at that timeYou need workflow context or historical guidanceA substitute for checking current documentation
Source selector, observed November 15, 2026

Do not collapse provenance

A resource can be accurate for its intended consumer and still be the wrong authority for your app. Website styling reconstructed for coding agents is not an official Retool application theme. Product-design rationale is not a configuration contract.

Map decisions to Retool's styling surfaces

Retool's official guide describes several styling surfaces: organization themes, component style configuration with theme references, organization-level CSS, app-level CSS, and dynamically computed styling. These are multiple possible destinations, not a universal order of precedence. Record the destination chosen for each decision and inspect the result instead of assuming which layer wins under every condition.

Best fitRecord explicitlyAcceptance question
Organization themeReusable organization-wide foundations supported by the current theme controlsSource role, source revision, configured value, applicable mode, and organizationDoes the named app receive the intended shared value?
Component style configurationA supported component property, variant, state, or deliberate local treatmentComponent identity, property, state, theme reference or literal value, and reasonDoes the representative component use the intended mapping in the tested state?
Organization-level CSSAn organization-wide styling need that the supported theme surface does not carrySelector or dependency, intended reach, owner, exception policy, and retest triggerDid the rule affect only its intended organization-wide consumers?
App-level CSSA bounded need owned by one applicationNamed app, selector or dependency, affected components, reason, and removal conditionIs the exception necessary, contained, and still current?
Dynamically computed stylingA style that must respond to application data or stateInput condition, output property, fallback, component state, and behavior ownerDo representative inputs produce the expected result without hiding meaning?
A source-to-surface crosswalk for planning and review

Use the broadest reusable layer only when the intended reach is genuinely broad. A shared background role may fit an organization theme. A status treatment driven by application data may require component or dynamic styling. Keep a one-off CSS rule visible as an exception so it doesn't become an undocumented second design system.

Prefer references over copied values

When Retool supports a theme reference in component styling, use it for decisions that should move together. If a literal value or CSS exception is necessary, record why it must diverge and which event should trigger another review.

Keep four evidence states separate

A clear review requires precise status language. Available, implemented, populated, and observed describe different facts. Combining them into one done flag makes a saved setting look like proof of adoption.

  • Available upstream: the approved source contains a decision that could be mapped, such as a semantic foreground role or a heading font family.
  • Implemented mapping: the team selected a Retool destination and configured or documented the translation.
  • Populated in the named app: the application currently resolves the expected theme value, component setting, or CSS dependency.
  • Observed rendering: a reviewer inspected the named component, state, mode, content, and viewport and recorded what appeared.

These states also prevent false absence claims. A role missing from the current app may still be available in the upstream system. A configured theme value may be populated but unused by the component under review. The rendered result may look correct while relying on an undocumented local override. Record the full path before deciding what to correct.

Token specimen · real values

Ambient Sage

Live render

Ambient Sage's actual tokens — the same values its exports use.

Color tokensSemantic roles with HEX / HSL / CMYK

Color tokens

Ambient Sage
light · HEX · HSL · CMYK

Core

#F3F4EF

background

H 72 · C0, 0, 2, 4

#1A1C17

foreground

H 84 · C7, 0, 18, 89

#E5E6E0

card

H 70 · C0, 0, 3, 10

#ECEEE8

muted

H 80 · C1, 0, 3, 7

#D8D9D2

border

H 68.57 · C0, 0, 3, 15

Brand

#FEE951

primary

H 52.72 · C0, 8, 68, 0

#1A1C17

primary-fg

H 84 · C7, 0, 18, 89

#E5E6E0

secondary

H 70 · C0, 0, 3, 10

#F7E464

accent

H 52.24 · C0, 8, 60, 3

#FEE951

ring

H 52.72 · C0, 8, 68, 0

Semantic

#C0392B

destructive

H 5.64 · C0, 70, 78, 25

#FFFFFF

destructive-fg

H 0 · C0, 0, 0, 0

#2D7238

success

H 129.57 · C61, 0, 51, 55

#C97D12

warning

H 35.08 · C0, 38, 91, 21

#545651

muted-fg

H 84 · C2, 0, 6, 66

Charts

#FEE951

chart-1

H 52.72 · C0, 8, 68, 0

#4A8FD4

chart-2

H 210 · C65, 33, 0, 17

#6BBF8A

chart-3

H 142.14 · C44, 0, 28, 25

#E07498

chart-4

H 340 · C0, 48, 32, 12

#E8A24B

chart-5

H 33.25 · C0, 30, 68, 9

Type scaleHeading, body, and mono in the kit's fonts

Typography

Ambient Sage

Scale: compact-product

Density: balanced

Heading · Plus Jakarta Sans · 1.875rem

Ship beautiful product faster

Subheading · Plus Jakarta Sans · 1.375rem

A warm-sage neutral-surface mobile kit with a single vivid yellow accent, flat tonal cards, and oversized display numerals.

Body · Plus Jakarta Sans · 1rem

Ambient Sage uses a near-white warm-sage canvas (#f3f4ef) with card panels distinguished only by a tonal shift to #e5e6e0, never by shadows or borders. A single vivid yellow (#fee951) is the only saturated color and appears sparingly at component scale as orbs, button fills, and focus rings. Primary data values render as oversized bold hero numerals with a small superscript unit. Typography is a friendly rounded geometric (Plus Jakarta Sans) with no uppercase and no tight tracking, while JetBrains Mono is reserved for hex codes and technical strings. Generous rounding and luminance-only contrast give the whole system a calm, minimal feel.

Mono · JetBrains Mono · 0.8125rem

npx shadcn add ambientsage.json

Aa

Plus Jakarta Sans · Heading

400500600700

Aa

Plus Jakarta Sans · Body

400500600700

ABCDEFGHIJKLM NOPQRSTUVWXYZ

abcdefghijklmnopqrstuvwxyz

0123456789 & @ # % →

Radius & spacingCorner radius, elevation, and spacing steps

Tokens

Ambient Sage primitives
density: balanced

Radius scale

sm · 0.375rem
md · 0.75rem
lg · 1.25rem
xl · 1.75rem

Component radius

button
card
input

Elevation

level 1
level 2
level 3
level 4

Spacing · base 4px

1x
2x
3x
4x
6x
8x
Ambient Sage can supply bounded upstream roles and values. This specimen does not represent a completed or verified Retool mapping.

Use Ambient Sage as bounded upstream intake

Ambient Sage v1 works as a concrete input because its public kit records specific decisions. It assigns Plus Jakarta Sans to heading and body roles at weights 400, 500, 600, and 700. JetBrains Mono fills the mono role at weights 400, 500, and 700. The kit also includes a compact-product typography scale and 28 semantic light and dark color roles.

That's enough to begin a mapping discussion. It does not show that Retool imports the kit, exposes a destination for every role, loads every font and weight as intended, or renders an accessible application. Identity Forge can provide upstream typography, semantic colors, spacing, layout guidance, DESIGN.md, and DTCG artifacts. Retool configuration and the application-specific result remain separate work.

  • Available: the source records the type families, supported weights, scale, and semantic color roles.
  • Unresolved: which current Retool destinations can carry each required decision.
  • Unexecuted: font delivery, value entry, component mapping, CSS work, mode behavior, and application review.
  • Not claimed: a direct Retool importer, automatic token transfer, or verified Identity Forge-to-Retool compatibility.

Start from a complete upstream record

Review Ambient Sage's color, typography, spacing, and usage guidance before deciding how each role should map into Retool. Keep the kit revision attached to your mapping record.

Copy the source-to-Retool record

Create one record for each important role or rule. The row should be reviewable before implementation and completed after observation. Unknown fields should remain unresolved. Don't add a plausible value merely to make the document look complete.

Source-to-Retool record

Record ID:
Named Retool app:
Review date:

Approved source:
Source revision:
Decision owner:
Semantic role or rule:
Applicable mode or condition:
Upstream value or instruction:

Retool destination:
Mapping state: unresolved | configured | populated
Configured value or reference:
Component and property:
Variant or state:
Organization CSS dependency:
App CSS dependency:
Dynamic styling dependency:
Approved exception:

Expected result:
Observed result:
Evidence state: untested | pass | revise | block | not applicable
Evidence reference:
Observation environment:

Implementation owner:
Review owner:
Disposition:
Retest trigger:
Notes:
Copyable record. The blank observation fields are intentional until someone checks the named app.

Write the expected result in the record before inspection. Otherwise, the reviewer can unconsciously turn whatever appears into the requirement. Keep the observed result factual: name the app, component, state, mode, viewport, and content condition. A screenshot can support the observation, but it doesn't explain which upstream source or override produced it.

One row can expose a large governance problem

If no one can name the source revision or the owner of a CSS exception, visual polish isn't the immediate issue. The application has no reliable way to distinguish a deliberate exception from drift.

Verify one named Retool app

Start the review with one named application, not an abstract Retool workspace. Choose representative cases that exercise the styling surfaces the app actually uses. This procedure is intentionally unexecuted. It defines what to inspect; it does not report a compatibility result.

  1. 1

    Freeze the acceptance scope

    Record the app, source revision, Retool environment, configured modes, representative viewport widths, content conditions, and review date.

  2. 2

    Write expectations first

    For every selected case, state the expected role, component or surface, state, and visible result before opening the rendered app.

  3. 3

    Confirm the recorded destination

    Check that the intended organization theme value, component setting, CSS dependency, or dynamic styling rule is present in the destination named by the record.

  4. 4

    Inspect representative surfaces

    Review navigation, forms, tables, charts or status feedback, dialogs, and any repeated layout shell. Use realistic content instead of an empty default screen.

  5. 5

    Exercise states and modes

    Inspect default, hover where relevant, keyboard focus, disabled, validation or error, loading, empty, and selected states. Check each configured visual mode without assuming that one mode proves the other.

  6. 6

    Check constrained layouts

    Use at least one narrow layout and one representative wider layout. Look for clipped labels, unreadable density, broken hierarchy, and local spacing changes.

  7. 7

    Record observations and disposition

    Write what rendered, attach the evidence reference, and choose pass, revise, block, or not applicable. Do not mark a required but untested case as passed.

  8. 8

    Set the retest trigger

    Retest when the source revision, theme, component configuration, relevant CSS, dynamic styling, app layout, or Retool behavior changes.

Expectation to write firstWhat to observe
NavigationSelected, default, and focus treatments use the recorded rolesHierarchy, selection, focus visibility, label fit, and narrow-layout behavior
FormLabels, inputs, validation, actions, and disabled controls follow their mapped rolesDefault, focus, error, disabled, loading, and submitted feedback
TableHeaders, rows, selection, status cells, and density follow recorded decisionsLong values, empty data, selected rows, scrolling, and narrow space
Chart or status feedbackColor communicates the recorded role without becoming the only source of meaningLegend, labels, low-volume cases, status distinction, and configured modes
DialogSurface, hierarchy, actions, and focus treatment match the recordOpen state, long content, keyboard path, destructive or secondary action, and narrow layout
Mode changeEvery required semantic role resolves to the expected mode-specific resultBackground and foreground pairings, borders, focus, status, charts, and local exceptions
Minimum representative case set

This is not an accessibility certification

A design-system mapping can improve consistency, but it doesn't prove that the resulting Retool app is accessible. Accessibility evaluation must cover the actual application, content, interactions, states, modes, and supported user conditions.

Find the first divergent layer

When the result differs from the expectation, trace the decision from source to screen. Correct the first layer that no longer supports the recorded intent. Don't weaken the approved brand decision merely because a downstream override is easier to edit.

  1. 1

    Approved source

    Confirm that the decision is explicit, current, approved, and applicable to the tested mode or condition.

  2. 2

    Recorded Retool destination

    Check whether the role was sent to the intended theme, component, CSS, or dynamic styling surface.

  3. 3

    Configured and populated value

    Confirm that the destination contains the expected reference or value in the named organization and app.

  4. 4

    Component styling

    Inspect the representative component, property, variant, and state. A component-level value may diverge from the shared mapping.

  5. 5

    CSS dependency

    Inspect the recorded organization-level and app-level CSS dependencies. Look for stale selectors, excessive reach, and unrecorded exceptions.

  6. 6

    Dynamic condition

    If styling depends on data or state, reproduce the recorded input and confirm that the expected branch was selected.

  7. 7

    Rendered observation

    Verify that the review used the correct app, mode, viewport, content, and state. Then record the earliest confirmed divergence and assign it to its owner.

This order is diagnostic, not a claim about universal CSS or Retool precedence. The frozen evidence shows that several styling layers coexist. It does not establish one precedence rule for every component, state, and Retool version. Inspect the actual path named in your record.

Make one bounded adoption decision

Keep the mapping only after one named Retool app passes the recorded representative cases. Revise it when the intended mapping is sound but a correctable downstream layer diverges. Block adoption when a required decision has no supported destination, an important state remains untested, or a CSS dependency cannot be bounded and owned.

The next step is concrete: choose one reused semantic role, complete its source-to-Retool record, and trace it through one component in every required state and mode. Expand the mapping only after that row has observed evidence.

Sources

  • Design | Retool Docs: Retool's official design guidance covers themes, theme references in component styles, organization-level and app-level custom CSS, dynamically computed styling, layouts, and component practices.
  • Retool UI Themes and Dashboard Templates: Retoolers presents commercial dashboard themes as starting directions and offers customization of colors, typography, layouts, and component styling for Retool applications.
  • Retool DESIGN.md for AI coding agents - DesignMD Directory: The listed DESIGN.md is a third-party reconstruction extracted from the public retool.com website, not an official specification for styling a Retool application.
  • Reimagining the Retool IDE: A journey to bring big changes to life: Retool's 2023 retrospective explains the constraints and incremental decisions behind the redesign of its own IDE, rather than specifying customer app themes.
  • Best practices for designing in Retool - YouTube: Retool's 2024 educational presentation covers theme creation alongside layouts, tables, charts, and other application-design concerns.
  • Best practices for designing in Retool (Summer 2024): This dated Retool team post discusses the 2024 Theme editor, custom design tokens or variables, and a Figma-related workflow, so its current applicability should be checked against current documentation.
  • Ambient Sage Design Kit: The public Ambient Sage kit provides a bounded upstream visual system with Plus Jakarta Sans, JetBrains Mono, semantic color roles, typography, and implementation guidance.
  • Semantic color tokens explained: Identity Forge defines semantic color tokens by interface role, including paired light and dark values, rather than by visual color names alone.