Design system for Base44: choose the right control and verify the app

A design system can fail quietly when the same decision appears in several places. A workspace color may be correct, but an app theme replaces it. A local Select-mode change may then replace the app theme. A prompt can request another treatment, while a breakpoint rule changes the final layout. Editing the most visible layer first may hide the symptom without resolving who owns the decision.

The selector below organizes the documented surfaces around one question: how far should this decision reach? It reflects the captured documentation as observed on November 13, 2026. Check Base44's current documentation before relying on a control name, permission, plan boundary, or API detail that may have changed.

Treat the rendered app as the end of a chain, not the source of truth. The approved external system establishes intent. Base44 receives selected decisions through workspace or white-label configuration, and a named app may add global theme choices. Selected elements can carry local exceptions. Responsive rules can alter the presentation under specific conditions. The rendered result is evidence about that chain, not a replacement for it.

1. 1

   Approved source

   Record the exact source and revision that governs the decision. This may be a maintained internal system or an implementation-ready kit. Don't substitute a screenshot, remembered value, or reconstructed style when an approved source exists.

2. 2

   Base44 workspace or white-label configuration

   Map only the decisions supported by the selected Base44 surface. Leave unsupported or unresolved fields open instead of forcing an approximate value.

3. 3

   Named app configuration

   Record the app Theme settings and any other app-wide choices separately from the shared configuration.

4. 4

   Local and responsive exceptions

   List Select-mode changes, component-specific differences, and viewport-dependent rules. Give every intentional exception an owner and a review condition.

5. 5

   Rendered observation

   Inspect a named component, state, mode, viewport, and content condition. Record what happened without rewriting the expectation after seeing the result.

When records conflict, stop at the first disagreement and resolve it with the owner of that layer. Don't let a downstream observation silently redefine an approved source. But don't claim adoption merely because the source is clear. You need evidence of both intent and implementation.

Before opening Base44 controls, turn the source into decisions that a receiving app can evaluate. A palette and two font names aren't enough. The input should state which modes apply, which resources and weights exist, how spacing and layout behave, which component rules are approved, and what remains undecided.

• Source identity, revision, approval state, owner, and date.
• Color roles with applicable light or dark values, permitted uses, and unresolved roles.
• Typography roles, font resources, available weights, sizes, line heights, tracking, and fallbacks when approved.
• Spacing scale plus rules for fixed, stepped, fluid, or component-scoped use where the source actually defines them.
• Layout constraints, container behavior, breakpoints or responsive conditions, and ownership of missing cases.
• Radii, borders, shadows, imagery, motifs, and usage restrictions.
• Component styling rules for representative variants and states, without assuming that a visual rule defines product behavior.
• Explicit unresolved decisions, approved exceptions, and named Base44 consumers.

Identity Forge is one optional upstream source. Its kits can include semantic light and dark color roles, typography, spacing, layout, motifs, usage guidance, DESIGN.md, and portable token exports. Those artifacts make decisions available for mapping. They don't establish a verified Base44 importer, direct integration, or automatic compatibility.

For example, the public Ambient Sage kit identifies a warm-sage visual direction, semantic colors, Plus Jakarta Sans for body and heading roles, JetBrains Mono for technical strings, and a compact product-oriented scale. Those are source facts. The Base44 record must still show where each decision goes, whether the destination supports it, and what the named app ultimately renders.

Use one row for every decision that matters to the acceptance scope. Don't reduce the work to a single done checkbox. A row can be mapped while its observation remains open, or observed while its source authority is disputed. Those are different problems.

SOURCE-TO-BASE44 MAPPING RECORD

Record ID:
Recorded on:
Named Base44 app:
Workspace:
Owner:

SOURCE
Decision name:
Approved source:
Source revision or date:
Source authority:
Source value or rule:
Applicable mode, state, or condition:
Source status: approved | candidate | unresolved | not applicable

BASE44 MAPPING
Intended Base44 surface: workspace system | white-label default | app Theme | Select mode | AI guidance | responsive layout
Destination field or control:
Mapped value or instruction:
Mapping status: not started | mapped | unsupported | unresolved
Mapping evidence:

DOWNSTREAM CONDITIONS
App-wide override:
Local element override:
Responsive or viewport rule:
Approved exception:
Precedence if values conflict:

OBSERVATION
Named component or surface:
State and content condition:
Viewport and mode:
Expected result:
Observed result:
Evidence location:
Evidence state: unexecuted | observed-pass | observed-divergence | inconclusive
First divergent layer:

DECISION
Disposition: accept | revise | block
Owner of next action:
Retest trigger:
Retest due or review condition:
Notes:

Suppose an approved source defines a semantic primary action role. Don't jump straight from that role to a screenshot. First decide whether it belongs in a workspace foundation or one app's Theme panel, then record the mapped destination and value. List any selected button with a local treatment. Inspect a representative default, hover, focus, and disabled state where those states are available. If only one button differs, the first divergence may be a local override. If every button differs, inspect the shared mapping before changing individual elements.

Use this workflow when the decision should affect one named app rather than every app in a workspace. Freeze the approved source revision, inventory the app's current Theme settings, and list known Select-mode or responsive exceptions. Map app-wide decisions to the Theme panel. Reserve Select mode for intentional local differences, and put responsive behavior in the layout controls. AI guidance can carry broader contextual instructions, but you still need to verify exact results in the editor and rendered preview.

This workflow can show that one app has a recorded configuration and a bounded acceptance result. It can't prove that another app shares the system, that a workspace default is correct, or that later AI changes will preserve every decision.

Use the workspace design-system route when several apps should share foundations or reusable components. First record which decisions are genuinely shared. A workspace default shouldn't absorb product-specific behavior, a campaign-only exception, or a mobile layout rule that belongs to one app.

After configuration, inspect at least one named app that should consume the system. Existing app settings and local styles may still matter, so the presence of a workspace system isn't sufficient acceptance evidence. Record whether the app received the intended values, whether app-wide or local overrides exist, and which change should trigger a retest.

Use the white-label route when the app-building experience should start with a defined brand and default design context. Keep design values separate from additional agent guidance because exact reusable decisions and contextual instructions do different jobs. Follow Base44's current documentation for eligibility, roles, settings, API requests, and how changes affect new or existing apps.

This route establishes defaults for the configured building experience. It doesn't prove that every generated component matches the intended system, that app-specific overrides are absent, or that responsive behavior is acceptable. Run the same named-app acceptance procedure after generation or a later build turn.

Several kinds of evidence can inform a Base44 design system, but each answers a different question. Label the evidence before you copy anything.

The Refero page, for example, presents a reconstructed Base44 style with interpreted roles and copy-ready values. It can be useful for visual analysis. It isn't an official Base44 token contract and shouldn't displace a team's approved source. Apply the same caution to short tutorials: use them to discover a possible workflow, then check the current official documentation and your own app.

Write the expectations before opening the preview. Choose cases that cross the layers most likely to diverge: a reused action, a form control, a surface or card, a text hierarchy, and one responsive layout. Include relevant states and modes, but don't claim to test combinations that the app doesn't support.

The record below is intentionally unexecuted. It's a test plan, not evidence that Identity Forge artifacts interoperate with Base44 or that a particular Base44 app passed.

NAMED-APP DESIGN-SYSTEM ACCEPTANCE RECORD

Status: UNEXECUTED
Recorded on:
Named app:
Workspace:
App revision or build:
Approved source and revision:
Reviewer:

ACCEPTANCE SCOPE
Representative flow:
Supported theme variants in scope:
Desktop viewport and environment:
Mobile viewport and environment:
Known app-wide overrides:
Known Select-mode overrides:
Known responsive exceptions:
Out-of-scope cases and reason:

CASE 1: PRIMARY ACTION
Named screen and component:
State: default | hover | focus | disabled | other
Mode:
Viewport:
Expected source decision:
Expected Base44 mapping:
Expected local exception:
Observed result: NOT RUN
Evidence: NOT CAPTURED
First divergence: UNKNOWN
Disposition: pending

CASE 2: FORM CONTROL
Named screen and component:
State: default | focus | error | disabled | other
Mode:
Viewport:
Expected source decision:
Expected Base44 mapping:
Expected local exception:
Observed result: NOT RUN
Evidence: NOT CAPTURED
First divergence: UNKNOWN
Disposition: pending

CASE 3: SURFACE OR CARD
Named screen and component:
Content condition:
Mode:
Viewport:
Expected background, border, radius, spacing, and type treatment:
Expected local exception:
Observed result: NOT RUN
Evidence: NOT CAPTURED
First divergence: UNKNOWN
Disposition: pending

CASE 4: RESPONSIVE LAYOUT
Named screen:
Desktop expectation:
Mobile expectation:
Relevant layout control or rule:
Expected exception:
Desktop observation: NOT RUN
Mobile observation: NOT RUN
Evidence: NOT CAPTURED
First divergence: UNKNOWN
Disposition: pending

FINAL DECISION
Required cases passed:
Accepted exceptions:
Open divergences:
Overall disposition: accept | revise | block
Decision owner:
Next action owner:
Retest triggers:
Evidence locations:

Choose accept when every required case has suitable evidence and any differences are approved, bounded exceptions. Choose revise when the intended result is clear and the responsible layer can be corrected without invalidating the adoption approach. Choose block when a required decision has no authority, a necessary mapping is unsupported or unresolved, evidence is missing for a required case, or the rendered result creates a material failure that shouldn't ship.

When a result looks wrong, inspect the chain in a fixed order. This keeps a local restyle from hiding a bad shared mapping and prevents a workspace edit from disturbing an intentional app exception.

1. Approved source: Is the decision current, explicit, approved, and applicable to this mode or condition?
2. Base44 mapping: Was the decision sent to the correct workspace, white-label, Theme, guidance, or layout destination?
3. Workspace or white-label default: Does the named app receive the intended shared context under the documented behavior?
4. App Theme: Is an app-wide value replacing or translating the shared decision?
5. Local override: Did Select mode or another element-level treatment create a deliberate or accidental exception?
6. Responsive behavior: Does a viewport-dependent layout or style rule change the result under the tested condition?
7. Rendered observation: Did the expected component, state, content, mode, and viewport actually render, and is the evidence tied to the right revision?

Correct the first layer that diverges from its recorded expectation, then retest the downstream cases. If the source is unresolved, pause the styling work until someone makes the decision. If the mapping is wrong, fix it before touching components. If only one element has an accidental override, removing or revising that exception is narrower than changing the shared foundation.

Complete one mapping row and one acceptance case before declaring adoption. That small record makes the important distinctions visible: what was approved, where Base44 received it, what overrode it, what rendered, and who owns the next decision.

• Design system - Base44 Support Documentation: Base44 documents a workspace design-system route for shared brand foundations and components.
• Design system - Base44 white-label documentation: Base44 documents white-label branding and a default design system for an app-building agent, with role, plan, and configuration boundaries.
• Customizing the design of your app - Base44 Support Documentation: Base44 documents the Theme panel for global styling, Select mode for individual elements, and AI chat for broader design changes.
• Design foundations and layout - Base44 Support Documentation: Base44 documents responsive layout behavior, mobile preview, and tools for refining an app across device sizes.
• Base44 design system - Refero Styles: Refero presents a third-party reconstruction of Base44's public visual style, including interpreted roles and downloadable artifacts.
• Identity Forge: Identity Forge provides complete design kits with visual decisions, tokens, written guidance, and agent-ready delivery artifacts.
• Ambient Sage Design Kit: The public Ambient Sage kit supplies a concrete upstream example with semantic colors, typography, spacing, and usage guidance.