Design system for Replit: choose the right source and verify the app

Decide where the approved visual decisions live before generating anything. Replit documents prompt-led creation and extraction from a mockup. Its broader design tools also accept material such as Figma sources, websites, screenshots, code, reference images, brand assets, briefs, and existing DESIGN.md. These inputs serve different purposes. A screenshot may show a treatment without explaining its rules. A DESIGN.md may explain intent without containing the exact application mapping. A prompt is useful precisely when no approved system exists yet.

Replit documents creation, saved-system use, and stored artifacts on separate pages. For implementation work, connect them as one chain. Each layer has its own authority and gives a decision another place to change before it reaches the screen.

Suppose the approved source assigns a semantic primary action role. The saved system may describe that role, tokens.json may carry its value, CSS may expose it as a variable, and a button may consume it. A screen-level class can still replace the button color. The final screenshot tells you the result is wrong. The chain shows where it first went wrong.

Write this record before you create or regenerate the system. It gives designers, developers, and reviewers a shared boundary. Mark unknown fields as "unresolved" so the generator doesn't make an invisible policy decision.

DESIGN SYSTEM SOURCE RECORD

Record ID:
Recorded on:
Owner:
Named consumer: [exact Replit app and project]

SOURCE
Source type: [brief | approved mockup | Figma | website | code | screenshot | assets | DESIGN.md | other]
Source identity:
Source revision or date:
Canonical authority: [source name and owner]
Supporting references:

DECISIONS
Approved decisions:
Unresolved decisions:
Replit may propose:
Replit must preserve:
Out of scope:

EXPECTED REPLIT OUTPUT
Saved system name:
Expected DESIGN.md or guidance:
Expected tokens.json roles:
Expected CSS or project mapping:
Expected example components or assets:

PRECEDENCE
If source and generated output disagree:
If tokens and guidance disagree:
Local overrides allowed when:
Approved exception owner:
Exception review date:

VERIFICATION
Representative components:
Required states:
Required modes:
Viewports:
Font-loading conditions:
Expected results:
Evidence location:
Reviewer:

RETEST TRIGGERS
Source revision changes:
System regeneration:
Token or CSS mapping changes:
Component changes:
Local override changes:
Font-delivery changes:
Viewport or mode behavior changes:

FINAL DISPOSITION
[adopt | revise | block]
Reason:
Open findings and owners:

Use this route when the brand or product direction exists as intent but the visual system remains open. Supply the audience, product character, approved assets, constraints, required surfaces, prohibited treatments, and named app. Separate fixed decisions from choices Replit may propose. After generation, treat colors, typography, token roles, spacing, component examples, and guidance as proposals. Approve or revise them before using the saved system as reusable context.

1. 1

   Freeze the brief

   Record approved constraints, unresolved choices, the named app, and the person who may approve generated decisions.

2. 2

   Generate a proposal

   Use Replit's current creation workflow, referring to its documentation for current controls and platform behavior.

3. 3

   Review the system, not only the sample screen

   Inspect the generated roles, typography, tokens, assets, guidance, and representative components. A polished sample screen can hide missing states or vague mappings.

4. 4

   Save only the reviewed revision

   Record the saved-system identity and the decisions accepted, revised, or left unresolved.

5. 5

   Verify the named app

   Trace representative decisions into the project and record rendered observations before broader reuse.

Use extraction when a particular mockup has already been approved as the visual reference. Record its exact revision and the surfaces it covers. Then list what it cannot establish. One desktop screen rarely defines narrow layouts, focus states, validation, loading, empty content, dark mode, typography fallback, or the behavior of components absent from the sample.

Review the extracted system against two lists: decisions visibly supported by the mockup and decisions inferred beyond it. The first group still needs accurate translation. The second needs explicit approval. If the generated system assigns a rule to a state the mockup never showed, label it as a proposal instead of claiming it was extracted.

Use external-system intake when approved guidelines, tokens, assets, code, or DESIGN.md already govern the product. Record the canonical revision and expected Replit artifacts. Treat Replit's generated files as downstream representations unless the system owner deliberately transfers authority. Compare the generated output with the source, paying close attention to renamed roles, omitted modes, substituted fonts, flattened aliases, and rules that exist only in prose.

Ambient Sage is a concrete source record, not a compatibility result. Its public kit uses Plus Jakarta Sans for heading and body roles at weights 400, 500, 600, and 700. JetBrains Mono supplies the mono role at weights 400, 500, and 700. The published system has a compact-product typography scale and 28 semantic color tokens across light and dark modes.

Start with one decision that crosses several layers, such as the primary action treatment or heading typography. Write the expected result before inspecting the generated app. Then work from the approved source toward the screen. This order stops a plausible rendering from retroactively defining what the system was supposed to do.

1. 1

   Confirm the approved source

   Find the exact decision, revision, applicable mode, and owner. If the source is silent, stop calling the decision approved.

2. 2

   Inspect the saved Replit system

   Check whether the intended decision appears in the saved visual context and whether the selected revision is identifiable.

3. 3

   Inspect the generated artifacts

   Find the corresponding guidance and token entry. Record renaming, translation, omission, or fallback rather than assuming equivalence.

4. 4

   Inspect the project mapping

   Confirm which CSS variable, font resource, theme value, or other project-level mechanism carries the decision.

5. 5

   Inspect component adoption

   Check whether the named component consumes the intended mapping in the required state and mode.

6. 6

   Inspect exceptions and overrides

   Identify narrower styles, wrappers, breakpoint rules, or approved exceptions that can change the result.

7. 7

   Record the rendered observation

   Capture what happened for the named screen, component, state, mode, viewport, content, and font-loading condition.

If the source and generated token agree but the component uses a local color, the first divergence is component adoption. Editing the upstream token might fix the screenshot, but it would also change unrelated consumers. The narrower fix belongs where the divergence began.

Saving or selecting a design system confirms configuration. Verification asks whether the intended decisions reached the actual interface. Choose a small, representative set instead of inspecting only the most polished default screen. A useful first pass might include a primary button, text input, card, navigation item, heading, and data value.

Include default, hover, focus, disabled, and error states where they apply. Check light and dark modes if both are in scope. Use narrow and wide viewports, with realistic content rather than short labels chosen to fit. For typography, inspect loaded-font and fallback behavior separately. For overrides, record whether each difference is approved, accidental, or unresolved.

When a screen looks wrong, inspect the chain in order. Stop at the first layer where the recorded expectation and actual state differ. Later differences may be consequences rather than causes.

1. Approved source: Is the decision explicit, current, approved, and applicable to this condition?
2. Saved Replit system: Does the selected system carry the intended decision and revision?
3. Generated artifact: Do DESIGN.md, tokens.json, assets, and examples preserve or correctly translate it?
4. Project mapping: Does the app load and expose the intended value, font, asset, or rule?
5. Component implementation: Does the component use the mapping for this variant and state?
6. Application override: Does a local class, wrapper, breakpoint rule, or exception replace it?
7. Rendered observation: Under the recorded mode, viewport, content, and loading conditions, does the result match the expectation?

Fix the earliest layer that owns the mismatch. Revise the source only when its decision is wrong. Regenerate when the derivative is stale or mistranslated. Correct the project mapping when the right artifact exists but isn't connected. Change the component or local override when the divergence begins there.

Adopt the system for the named scope when you can trace the required source decisions, the expected artifacts exist, representative components use the intended mappings, and recorded observations match expectations. Revise when the route is sound but a bounded mismatch has an owner and a clear correction. Block when authority is unknown, required decisions disappeared during translation, the app uses a different system, or evidence required for the named scope is missing.

Keep the completed source record with the system revision. When the source, generated artifacts, component implementation, override, font delivery, mode behavior, or viewport behavior changes, rerun the affected cases. Next, choose one named Replit app and complete one acceptance row from approved source to rendered observation before approving the system more broadly.

• Create a design system - Replit Docs: Replit documents creating a design system from a prompt or extracting one from a mockup, followed by review and saving.
• Use a design system - Replit Docs: Replit describes a saved design system as reusable visual context for colors, typography, spacing, components, and later visual work.
• Design system contents and DESIGN.md - Replit Docs: Replit documents design-system contents and a storage chain in which tokens.json feeds CSS variables consumed by components, and it identifies existing DESIGN.md as possible source material.
• Design systems, explained - Replit Docs: Replit describes design systems as capturing tokens, colors, typography, components, and supplied brand assets, with several possible creation sources.
• AI Design Tool - Replit: The Replit Design page presents prompt, URL, Figma, screenshot, and design-system starting routes alongside its interactive design experience.
• Ambient Sage Design Kit: The public Ambient Sage kit provides Plus Jakarta Sans for heading and body roles, JetBrains Mono for technical strings, a compact product-oriented treatment, and 28 semantic light and dark tokens.