Appfire UX Guidelines for Cursor

UX design system guidelines that make AI coding assistants (Cursor, Copilot, Codex) aware of Atlassian Design System foundations, content writing rules, messaging patterns, accessibility standards, and user personas.

Drop this kit into any repo building Appfire apps in the Atlassian ecosystem and your AI assistant will follow ADS guidelines automatically.

Quick start

Option A: npm (recommended)

npm install @appfire-ux/guidelines

This automatically copies .cursor/rules/ux-*.mdc and guidelines/ into your project root. To refresh after an update:

npx @appfire-ux/guidelines

Option B: Manual copy

git clone https://github.com/fuegokit/appfire-ux-guidelines.git

cp -r appfire-ux-guidelines/.cursor/rules/ux-*.mdc  <your-repo>/.cursor/rules/
cp -r appfire-ux-guidelines/guidelines/              <your-repo>/guidelines/

See guidelines/INSTALL.md for detailed setup, customization, and how the three-layer architecture works.

What's inside

.cursor/rules/ — AI rules (auto-loaded by Cursor)

| Rule | Activation | What it covers | |------|-----------|---------------| | ux-foundations.mdc | Always on | Color tokens, spacing (8px grid), typography, elevation, accessibility | | ux-content-writing.mdc | *.tsx, *.ts | Voice & tone, grammar, inclusive language, date/time formatting | | ux-messaging.mdc | *.tsx | Error/warning/success/info/empty state/feature discovery patterns | | ux-icons-visuals.mdc | *.tsx | Icons, illustrations, logos, border, radius | | ux-personas.mdc | Always on | 18 user personas, app-to-persona mapping, when to consult |

guidelines/ — Deep reference (read on demand)

• foundations/ — 29 files covering ADS visual styles (color, typography, spacing, elevation, border, radius, iconography, illustrations, logos), accessibility, and content guidelines (voice & tone, grammar, inclusive writing, date/time, 6 message type patterns)
• personas/ — 18 synthetic user personas with motivations, frustrations, evaluation criteria, and tone. Plus app-to-persona mapping for all Appfire products.
• Guidelines.md — Implementation guide with code examples (adapt to your stack)

How it works

Layer 1: .cursor/rules/ux-*.mdc  →  Cursor auto-loads these on every session
                                      Short, imperative rules with file references
                                             ↓
Layer 2: AGENTS.md (your repo)   →  Navigation map for AI agents
                                             ↓
Layer 3: guidelines/              →  Agent reads on demand when it needs depth
                                      Full ADS foundations + personas

The rules in Layer 1 contain condensed guidelines and explicit Full reference: links to Layer 3 files. When the AI agent needs more detail, it follows the link and reads the full guideline.

Keeping up to date

This repo is automatically synced from the source design system repo and published to npm.

npm — update the package and re-run the install script:

npm update @appfire-ux/guidelines
npx @appfire-ux/guidelines

Manual — pull and re-copy:

cd appfire-ux-guidelines && git pull
cp -r .cursor/rules/ux-*.mdc  <your-repo>/.cursor/rules/
cp -r guidelines/              <your-repo>/guidelines/

Source

Synced from fuegokit/appfire-ai-template. Guidelines based on atlassian.design.