Framer design system: what belongs in styles, components, and DESIGN.md

A design-system decision can appear in several parts of Framer. Its official AI page says the canvas can refine typography, components, breakpoints, spacing, color, effects, and layouts. The page also describes AI-authored code components and connections to external agents. Across the broader platform, design, code, collaboration, and publishing share one working environment.

Those capabilities tell you what can be edited. On their own, they don't decide where a rule should originate or what wins when two layers disagree. The responsibility and precedence model below is a working contract for teams, not a Framer-native standard.

Choose the authority based on the decision's scope. A rule that should survive a change of page, agent, or implementation tool belongs in portable guidance such as DESIGN.md. Implement a reusable value inside the Framer project as a shared style. When a decision defines a recurring unit with structure or behavior, put that implementation in a component.

A mapping isn't a second authority. For example, DESIGN.md may specify that muted text uses a semantic foreground role. A Framer text style can implement that role under a project-specific name. The written rule owns the meaning, while the Framer style owns the local reusable value. The handoff record connects them.

When two layers disagree, don't accept whichever one renders last. Trace the decision to its declared authority, check whether the downstream mapping is current, and classify any deviation as an approved exception or a defect.

1. Check the authoritative decision and its scope.
2. Check the recorded mapping to the Framer style, component, breakpoint, or code component.
3. Check whether a narrower exception was explicitly permitted.
4. If the authority is ambiguous, pause the change and assign it before editing more surfaces.
5. Update the owning layer first, then update affected mappings and record the observed evidence.

An agent needs more than a design request. Give it a short acceptance record that names the authoritative decision, intended consumers, unchanged surfaces, and evidence required for review.

change_id: nav-muted-text
objective: Align secondary navigation text with the declared muted-text role.

source:
  authority: DESIGN.md > Color roles > Muted content
  owner: Design systems owner
  decision: Secondary navigation labels use the muted foreground role.

targets:
  framer_styles:
    - Secondary / Navigation
  components:
    - Site Header
    - Footer Navigation
  representative_pages:
    - Home
    - Pricing
  breakpoints:
    - Desktop
    - Smallest supported phone width

allowed_exceptions:
  - Active navigation item uses the primary foreground role.

must_remain_unchanged:
  - Primary navigation labels
  - Button labels
  - CMS article body text
  - Header spacing and interaction behavior

agent_context:
  include:
    - Relevant DESIGN.md color-role section
    - Target text style
    - Site Header and Footer Navigation components
    - Home and Pricing pages
  exclude:
    - Unrelated pages, CMS content, and global layout changes

evidence:
  intended_change:
    - Before and after capture for each representative page and breakpoint
  unrelated_drift:
    - Comparison of named unchanged surfaces
  unresolved:
    - Record any mapping or behavior that could not be inspected

disposition: pass | revise | block
reviewer:
reviewed_at:

The record separates intention from observation. A target listed under framer_styles is expected to change. Its presence there isn't evidence that the mapping exists or that the result matches the source. Fill the evidence section only after inspection.

Representative pages should exercise real reuse. Choose at least one page where the target is prominent and another where it appears in a different composition. For breakpoints, cover the responsive condition most likely to change the component instead of checking every arbitrary canvas width.

Framer describes project context, editable styles and assets, external-agent connections, and agent-authored changes. More context isn't automatically better. A bounded context makes it easier to see whether the agent followed the intended rule and whether unrelated work slipped into the branch.

1. 1

   Select the source decision

   Provide the relevant DESIGN.md section or other declared authority. Don't send an entire library when only one color role or component rule is in scope.

2. 2

   Name the Framer consumers

   Identify the shared styles, components, pages, layers, and breakpoints expected to implement the decision. Mark unknown mappings as unknown instead of guessing their names.

3. 3

   State the non-goals

   List nearby surfaces the agent must not redesign, rename, restructure, or restyle. Include unrelated components that share the page.

4. 4

   Define observable acceptance

   Describe what a reviewer must see on representative pages and small breakpoints. Name the unrelated surfaces that should remain unchanged.

5. 5

   Open a bounded branch change

   Ask for the named change only. If the agent finds a missing mapping or ambiguous authority, require it to report the gap instead of inventing a new system.

A good-looking desktop canvas is weak evidence. Review the intended change wherever it's reused, inspect a smaller breakpoint, and check named unrelated surfaces for drift. The goal is traceability, not a claim that one review certifies the whole site.

1. 1

   Confirm the source and mapping

   Verify that the branch brief points to the current authoritative decision and intended Framer consumers. If either is missing, revise the brief before judging the rendering.

2. 2

   Inspect the primary representative page

   Check the intended style or component on the page where its effect is easiest to see. Record what changed instead of relying on memory.

3. 3

   Inspect another real consumer

   Open a second representative page or composition that uses the same style or component. A mismatch often reveals a detached local value or duplicated component.

4. 4

   Check the responsive adaptation

   Inspect the smallest named breakpoint and any breakpoint where arrangement, visibility, or sizing intentionally changes. Confirm that the base rule still holds unless the brief permits an adaptation.

5. 5

   Look for unrelated drift

   Compare the surfaces listed under must_remain_unchanged. Check the style values, component structure, layout, content, and interactions relevant to the branch scope.

6. 6

   Assign a disposition

   Pass when the intended mappings match and no in-scope drift remains. Revise for a correctable mismatch. Block when authority is ambiguous, required evidence is unavailable, or the branch changes protected non-goals.

When a Framer page looks inconsistent, another broad prompt often makes the evidence harder to interpret. Walk through the layers in ownership order and stop at the first unsupported or contradictory mapping.

1. Source decision: Is the intended role or rule explicit, current, and owned?
2. Selected context: Did the agent receive the relevant rule, targets, exceptions, and non-goals?
3. Shared style mapping: Does the target element use the Framer style mapped to the source role?
4. Component use: Is the page using the shared component and intended variant, or a detached copy?
5. Breakpoint adaptation: Does a responsive override intentionally change the value or structure?
6. Generated code: Does a code component contain a duplicated value or behavior that conflicts with the source?
7. Page-level override: Is there a local value masking the shared implementation?

Fix the owning layer, not the first visible symptom. If a component uses the wrong shared style, correct the component mapping. If the source rule is genuinely wrong, change it through the team's normal design-system process and then update every affected consumer. Don't rewrite the source merely to legitimize an accidental local value.

The public Ambient Sage kit works as an example because its source facts are inspectable. Its published page provides a DESIGN.md, semantic light and dark tokens, a 31-color palette, and typography roles. Plus Jakarta Sans is used for headings and body, while JetBrains Mono fills the mono role. The kit also describes warm sage surfaces, tonal cards, and a restrained yellow accent.

A handoff might map the kit's background role to a Framer color style, its body role to a text style using Plus Jakarta Sans, and its tonal-card guidance to a reusable card component. These are example mappings, not facts about an existing Framer project. The project owner must choose the actual names and verify the resulting pages.

The responsibility map and branch record improve traceability. They don't replace specialist review or prove that the result is good. A consistent implementation can still apply a poor design decision consistently.

• It does not certify accessibility conformance, including contrast, keyboard behavior, focus treatment, semantics, or assistive-technology support.
• It does not prove every page, content state, locale, or viewport is responsive.
• It does not assess generated-code quality, runtime behavior, performance, security, or maintainability outside the declared change.
• It does not prove that a source artifact was imported automatically or reproduced with visual parity.
• It does not authorize publication. The branch still needs the project's normal review and release process.

Keep separate evidence tracks when the risk requires them. Design-system conformance asks whether the implementation follows its declared source. Accessibility, resilience, behavior, and production readiness require their own checks.

Choose one existing decision that appears on more than one Framer page, such as muted navigation text or card surface color. Declare its authoritative source, record the exact Framer style or component mapping, name two representative pages and one small breakpoint, then test one bounded branch change. Expand the system only when the record is clear enough for another reviewer to reproduce.

• AI Website Builder for Designers & Teams | Framer: Framer documents AI-created editable pages and the ability to refine layouts, typography, components, breakpoints, spacing, color, effects, and code components within the project.
• Framer: AI website builder for professional sites: Framer presents agents, design, code, collaboration, and publishing as parts of the same website-building platform.
• Web Design Tools in Framer: The captured design overview describes layer styling, grids, stacks, responsive screen adaptation, built-in fonts, and breakpoint-oriented collaboration surfaces.
• Ambient Sage Design Kit: The public Ambient Sage kit provides a DESIGN.md, semantic light and dark tokens, Plus Jakarta Sans typography, JetBrains Mono, and several developer export formats.
• How to generate a DESIGN.md (and what it is): Identity Forge defines DESIGN.md as a written design brief covering intent, tokens, typography, layout, component treatments, motifs, and explicit usage rules for coding agents.
• AI UI review checklist: test generated interfaces before you ship: The review guide separates task, design-system, resilience, and accessibility evidence and recommends testing representative states and controlled changes before release.