Skip to content

Add design-history-tracking Cursor rule #14

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
JustinXHale wants to merge 1 commit into
base: main
Choose a base branch
from
+46 −0
Open

Add design-history-tracking Cursor rule #14

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 46 additions & 0 deletions .cursor/rules/design-history-tracking.mdc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
---
Copy link
Copy Markdown
Collaborator

@jpuzz0 jpuzz0 Apr 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This needs to be a tool-agnostic agent (.md under plugins/<name>/agents/) rather than a .mdc rule - .mdc only works in Cursor, and this repo distributes to both Cursor and Claude Code. It also needs to move under a plugin directory to be discoverable by plugin users.

description: When making design-related UI/UX changes, automatically record what changed and why so designers don't have to manually track design justification.
globs: "**/*.{ts,tsx,js,jsx,css,scss}"
Copy link
Copy Markdown
Collaborator

@jpuzz0 jpuzz0 Apr 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

alwaysApply: true on all TS/JS/CSS files means this fires on every edit, even non-design ones. Would a conditional trigger be more appropriate here?

alwaysApply: true
---

# Design History Tracking

## Purpose

Designers often make many small design changes in a session. Manually tracking every change and the reasoning behind it is tedious and gets skipped. This rule ensures the agent records design changes and justification automatically—so there is a clear trail of what was done and why, without the designer having to maintain it.

## When This Applies

- You are adding, removing, or significantly changing UI components, layout, styling, or user flows.
- You are implementing a design decision or UX change (e.g. "make this button more prominent," "add a filter here," "use a card layout instead of a table").

## Rule

After completing design-related code changes:

1. **Summarize what changed and why** in your response. Include a short "Design change" note: what was updated and the design rationale (e.g. "Moved primary action to a prominent button per user feedback" or "Added filter bar to reduce table clutter"). This gives the designer a justification trail in the chat.

2. **If the project has a design-history file**, append a brief dated entry there instead of or in addition to the in-chat summary. Look for:
- `design-history.md` (project root)
- `.design/design-history.md`
- Or a path documented in the project README or CONTRIBUTING.

Entry format (keep it short):
- Date (YYYY-MM-DD)
- One line: what changed and why (e.g. `[Update] Primary CTA moved to PageHeader actions for visibility.`)

3. **If there is no design-history file**, rely on the in-chat summary. You may suggest adding a `design-history.md` if the designer wants a persistent log.
Comment on lines +24 to +33
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Apr 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Auto-appending project files needs an explicit safety gate.

“Append a brief dated entry” can trigger unintended repository writes during normal assistant usage. Add an explicit condition (user request or repo policy flag) before modifying files; otherwise keep to in-chat notes only.

Suggested rule hardening 
-2. **If the project has a design-history file**, append a brief dated entry there instead of or in addition to the in-chat summary.
+2. **If the project has a design-history file and the user explicitly requests file updates (or repo policy requires it)**, append a brief dated entry there. Otherwise, keep the update in-chat only.
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In @.cursor/rules/design-history-tracking.mdc around lines 24 - 33, The rule
that instructs the assistant to “append a brief dated entry” to project files
(see rule 2 referencing design-history.md and .design/design-history.md) must be
changed to require an explicit safety gate: update the text so the assistant
only auto-appends when there is an explicit user request or a repo-level
policy/flag authorizing file writes; otherwise the assistant should limit itself
to producing an in-chat summary and optionally suggesting adding a
design-history.md. Make this requirement clear and unambiguous in the rule
wording and include the exact trigger phrases (“explicit user request” or “repo
policy/flag”) so callers can detect and enforce the consent check.


## Example

After implementing a design change, include something like:

> **Design change:** Added an empty state to the table when there are no results, using PatternFly's `EmptyState` with a clear message and optional "Create" action—reduces confusion when the list is empty.

If the project has `design-history.md`, also append:

```markdown
## 2025-03-17
- [Update] Table empty state added (EmptyState component) to improve clarity when no results.
```