# Keep designs consistent across projects

> Keep separate websites and dashboards visually consistent with shared design tokens, reusable components and a small, versioned design reference.

Canonical page: https://sitepeel.dev/guides/keep-ai-ui-consistent-across-projects/

Give each project the same source for design values and reusable patterns. Repeatedly describing how another project looks leaves too much room for small differences.

## Choose the approved implementation

Start with one real screen that already represents the intended design. Identify its navigation, text hierarchy, form controls and feedback states. If every project is slightly different, choose the version you want to maintain before attempting to synchronize them. Otherwise the inconsistencies become the source material.

Use Sitepeel’s Design MD tool to document visible patterns in that screen, then compare the reference with the source code. Name the approved component variants and record the paths where they live. Screenshots explain the appearance; implementation files explain what other projects can actually reuse.

## Share values before duplicating entire screens

A small token file is a practical first step. It can define color roles, spacing, radii and text styles without imposing a framework. CSS custom properties let multiple rules refer to a named value. Keeping names tied to purpose makes a change easier to understand than repeatedly replacing anonymous color codes.

For a few small projects, you can distribute a versioned token file and update each project deliberately. As maintenance grows, package it through your existing dependency workflow. Document who owns changes and which projects have adopted them. Copying a file once is distribution, but it is not an ongoing update process.

Example: design-tokens.css

```
/* Example values: replace with your approved design. */
:root {
  --color-page: #0b0a0d;
  --color-surface: #131016;
  --color-text: #f5f0f8;
  --color-accent: #c4a5ed;
  --space-control: 0.75rem;
  --space-section: 2rem;
  --radius-control: 0.5rem;
}

.action {
  padding: var(--space-control) 1rem;
  border-radius: var(--radius-control);
  background: var(--color-accent);
  color: var(--color-page);
}
```

## Reuse components where behavior should match

Tokens alone will not make two sidebars behave identically. If several projects use the same framework and need the same navigation, table or dialog, a shared component can keep structure, interactions and visual states together. Define a small set of supported variants instead of exposing every CSS property as an option.

Projects using different frameworks can still share tokens, design decisions and test examples. They may need separate component implementations. Keep the common behavior explicit: which element receives focus, how a menu closes, and where validation appears. A shared color palette cannot communicate those details by itself.

## Tell the agent what it should reuse

In each project’s design instructions, point to the current token file and component entry points. State which components should be extended and where new variants belong. Give the agent a representative screen to inspect before it starts. This is more actionable than asking it to make one dashboard look like another.

Record intentional differences, such as a compact operations table or a larger public-facing form. Consistency does not require every screen to have the same density. The shared system should explain which variations are supported so a local requirement does not quietly create another unrelated design.

## Review changes against a few representative states

Maintain a small reference set: a dense screen, a form, an empty state and a narrow layout. When you change a shared token or component, review these states in the affected projects. Include long labels and validation text, since those often reveal spacing and wrapping problems that a perfect sample hides.

Version changes that require consumers to adapt, and keep a brief migration note. For example, explain which button variant replaces a retired one rather than asking every project to infer the new rule. Update DESIGN.md after the approved implementation changes. The reference, shared code and actual screens should tell the same story.

## Further reading

- [Reddit: consistency across separate project repositories](https://www.reddit.com/r/ClaudeCode/comments/1uebye4/how_do_you_maintain_design_consistency_across/)
- [MDN: using CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Cascading_variables/Using_custom_properties)

## Related pages

- [Design MD generator](https://sitepeel.dev/design-md-generator/index.md): Generate a Design MD reference from a website. Extract typography, colors and spacing into a visual guide and Markdown for your next project.
- [Extract a design reference](https://sitepeel.dev/guides/extract-website-design-system/index.md): Audit a website’s colors, typography, spacing and components. Turn repeated patterns into a practical design system reference with Sitepeel.
- [When AI ignores DESIGN.md](https://sitepeel.dev/guides/ai-ignoring-design-md/index.md): Check whether your agent reads DESIGN.md, resolve conflicting instructions and connect design rules to real components and visual checks.