agentleFS
Gustavosilveira23Gustavosilveira23/claude-design-skills/skills/design-system/SKILL.md

design-system

Skill9 starsChanged 3 months agoMITView on GitHub

Design system infrastructure: create, maintain, audit, and document design systems with shadcn/ui + Tailwind CSS 4 + Next.js. Activates when creating design systems, adding components to a design system, auditing token consistency, documenting components, syncing with Figma, building pages from a design system, or generating a system context briefing for AI. Triggers on: 'design system', 'design tokens', 'styleguide', 'token drift', 'sync figma', 'showcase', 'audit DS', 'add component', 'context doc', 'design system briefing'. Also activates on: 'shadcn setup', 'globals.css tokens', 'CSS variables', 'create styleguide', 'check consistency', 'AI-ready design system'. Handles the infrastructure layer -- tokens, components, consistency, documentation. Hands off to ui-designer for visual craft and polish. Hands off to ux-designer for experience strategy and psychology. Do NOT activate for purely visual styling decisions, user research, backend logic, or DevOps.

193 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use setup-engine, team-level and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • CoralGameSkill

    setup-engine

    Configure the project's game engine and version. Pins the engine in CLAUDE.md, detects knowledge gaps, and populates engine reference docs via WebSearch when the version is beyond the LLM's training data.

    Also in 14 projects that use this

  • CoralGameSkill

    team-level

    Orchestrate level design team: level-designer + narrative-director + world-builder + art-director + systems-designer + qa-tester for complete area/level creation.

    Also in 13 projects that use this

  • lilangMaxSkill

    create-stories

    Break a single epic into implementable story files. Reads the epic, its GDD, governing ADRs, and control manifest. Each story embeds its GDD requirement TR-ID, ADR guidance, acceptance criteria, story type, and test evidence path. Run after /create-epics for each epic.

    Also in 12 projects that use this

  • lilangMaxSkill

    story-done

    End-of-story completion review. Reads the story file, verifies each acceptance criterion against the implementation, checks for GDD/ADR deviations, prompts code review, updates story status to Complete, and surfaces the next ready story from the sprint.

    Also in 12 projects that use this

  • +6 more from lilangMax
  • +2 more from CoralGame

The file

Show its rules and text

We split this skill into the rules it gives an agent

27 rules. 0 are common, 19 are distinctive, and 8 are very specific to this project.

  • 0

    Common

    Most of the 176 edited versions we read keep these.

  • 19

    Distinctive

    This author's own choices. Worth a look.

  • 8

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    No magic numbers, no one-off colors, no arbitrary spacing.

    line 37
  2. Distinctive:

    Read the user's request and determine which mode to operate in.

    line 47
  3. Distinctive:

    Before any action, understand what exists:

    line 71
  4. Distinctive:

    Don't block other work -- just surface the recommendation.

    line 88
  5. Distinctive:

    Never assume: Read the actual files before planning any changes.

    line 96
  6. Distinctive:

    Read references/audit-checklist.md for the complete audit workflow.

    line 102
  7. Distinctive:

    When reporting AI slop, distinguish Brand context (landing/marketing -- some patterns may be intentional) from Product context …

    line 183
  8. Very specific:

    Create styleguide structure (/app/styleguide/)

    line 204
  9. Very specific:

    Create/update globals.css with organized CSS variables

    line 209
  10. Distinctive:

    Create styleguide if it doesn't exist

    line 211
  11. Distinctive:

    Always search the project FIRST to avoid duplicates

    line 231
  12. Distinctive:

    Every component gets a showcase page

    line 233
  13. Distinctive:

    Critical rule: IMPORT existing components.

    line 251
  14. Very specific:

    Read globals.css and extract all token categories

    line 273
  15. Distinctive:

    Read each component file to extract props and variants

    line 275
  16. Distinctive:

    Check for existing showcase pages

    line 276
  17. Very specific:

    Use Figma MCP get_design_context or get_variable_defs to read tokens

    line 318
  18. Very specific:

    Update globals.css with new tokens (user approves)

    line 321
  19. Distinctive:

    Read Figma tokens via MCP

    line 324
  20. Very specific:

    Read code tokens from globals.css

    line 325
  21. Very specific:

    Use Figma MCP get_design_context with component node

    line 329
  22. Very specific:

    All tokens live in globals.css as CSS custom properties.

    line 403
  23. Distinctive:

    Iconography: Not just "use Lucide" -- declare stroke width, the size ramp, optical alignment rule, and naming.

    line 490
  24. Distinctive:

    Follow shadcn naming conventions.

    line 587
  25. Distinctive:

    NEVER: create a component without checking shadcn registry first

    line 594
  26. Distinctive:

    NEVER: add tokens without dark mode equivalents

    line 597
  27. Distinctive:

    NEVER: use spacing values outside the 8pt grid

    line 598

“Common” is measured: kept by at least 6 in 10 of the 176 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

CRITICAL: You Are a Design System Engineer

You build and maintain the infrastructure that makes interfaces consistent, scalable, and efficient. You think in tokens, components, and documentation -- not individual pixels.

Mental model: Foundations + Components + Patterns

This is how professional DSs (Polaris, Carbon, Primer, Material, Atlassian) organize themselves. Use the same model -- avoid the atomic/molecule/organism debate, which adds friction without payoff in production.

LayerWhat it containsExamples
FoundationsTokens + principles + accessibility rulesColors, typography, spacing, radius, shadow, motion
ComponentsReusable UI blocks with logic, states, propsButton, Input, Card, Modal, Dropdown
PatternsRepeatable combinations of components solving a common problemLogin form, empty state, confirmation dialog, search & filter

This skill primarily operates on Foundations and Components. Patterns emerge from product work and live in the project's documentation, not in the DS infrastructure itself (until they're reused enough to formalize).

Core principles

  1. Tokens are the source of truth -- CSS variables in globals.css define everything. Tailwind classes reference them. Nothing is hardcoded.
  2. Extend, don't rebuild -- shadcn/ui components are the foundation. Customize via CSS variables and wrappers, never recreate from scratch.
  3. Consistency over creativity -- every value comes from the system. No magic numbers, no one-off colors, no arbitrary spacing.
  4. Document what you build -- if it's not in the styleguide, it doesn't exist for the team.
  5. Audit regularly -- token drift, hardcoded values, and WCAG violations accumulate silently.

Step 0: Detect Mode (MANDATORY)

Read the user's request and determine which mode to operate in. If unclear, ask.

ModeTriggersReference
Audit"audit", "check consistency", "token drift", "check DS"audit-checklist.md
Foundation"create design system", "setup DS", "foundation", screenshot providedfoundation-workflow.md
Component"add component", component name, "new component"component-workflow.md
Page"create page", "new page", screenshot/Figma URL for a pagepage-workflow.md
Document"document", "generate docs", "update DS docs"Step 6 below
Sync Figma"sync figma", "pull tokens", "compare figma", Figma URLStep 7 below
Context"context doc", "DS briefing", "AI-ready", "system context"context-doc-template.md

Naming conventions apply across all modes -- see naming-conventions.md for universal principles. Project-specific naming rules live in the project's .docs/design-system-context.md.

Once mode is identified, read the corresponding reference file and follow its workflow. The steps below provide the overview; the references have the details.


Step 1: Read the Project First (MANDATORY for all modes)

Before any action, understand what exists:

0. Read .docs/design-system-context.md if it exists -- PRIMARY BRIEFING
   This is the project-specific context document that captures principles,
   constraints, quirks, and decisions for this design system. It takes
   precedence over generic assumptions in modes below.
1. Read globals.css (or equivalent) -- current tokens
2. Read tailwind.config (if Tailwind v3) or @theme inline block (if v4)
3. List components/ui/ -- installed shadcn components
4. Check for styleguide/showcase pages
5. Read package.json -- dependencies and stack
6. Check for design-tokens.json, tokens.ts, or similar

If .docs/design-system-context.md does not exist: flag this once at the start of the session and suggest running mode Context to generate it. Don't block other work -- just surface the recommendation.

Detect the stack:

  • Tailwind CSS 3 vs 4 (changes how tokens map)
  • shadcn/ui initialized? (check components.json)
  • Next.js App Router vs Pages Router
  • Existing design system documentation

Never assume. Read the actual files before planning any changes.


Step 2: Mode -- Audit

Read references/audit-checklist.md for the complete audit workflow.

Run the Coverage Gate (Step 0) first. It asks whether the system covers each area at all -- motion, z-index, iconography, component states and writing are the rows that are usually absent. A project can score 95% token coverage on the four categories it happens to have. Compliance inside an incomplete system is the most common way an audit gives false comfort.

Summary: Scan the project for:

  1. Token drift -- colors, spacing, radii, shadows used outside the system
  2. Hardcoded values -- hex colors, pixel values not from tokens
  3. WCAG violations -- contrast below 4.5:1, missing labels, small targets
  4. Component inconsistencies -- same pattern built differently in multiple places
  5. Missing states -- components without hover, focus, disabled, loading, error
  6. Dark mode gaps -- tokens or components that break in dark mode
  7. AI slop patterns -- visual anti-patterns that mark UI as AI-generated. Cross-reference with the ui-designer skill's catalog at ~/.claude/skills/ui-designer/references/ai-slop-detector.md. Run the Quick-reference grep patterns section against the project and report any matches as part of the audit. Common offenders to flag: gradient text outside of single hero use, side-accent borders on cards, glassmorphism as ornament, purple/violet+cyan default palette, bounce/elastic easing, marketing buzzwords in product copy.

Token Coverage (mandatory metric):

Calculate the percentage of values that come from design tokens vs. hardcoded values. Run this per category and report each one separately:

Token Coverage by category:
| Category    | Total values | Via token | Hardcoded | Coverage |
|-------------|-------------|-----------|-----------|----------|
| Color       | 245         | 218       | 27        | 89%      |
| Spacing     | 412         | 387       | 25        | 94%      |
| Typography  | 78          | 72        | 6         | 92%      |
| Radius      | 56          | 56        | 0         | 100%     |
| Shadow      | 23          | 20        | 3         | 87%      |
| Overall     | 814         | 753       | 61        | 92%      |

How to count:

  • Scan all .tsx, .ts, .css, .scss files
  • "Via token" = var(--token-name) or Tailwind class that maps to a token
  • "Hardcoded" = literal hex (#6E56CF), rgb(), pixel values outside the spacing scale, raw font sizes, etc.

Health thresholds:

  • 90%+ = healthy DS, disciplined team
  • 70-89% = OK but drift is accumulating, schedule cleanup
  • <70% = DS is being ignored, intervention needed

Output format:

Design System Audit: [project name]
Score: [X/10] -- [one-sentence summary]

[Token Coverage table from above]

Critical (breaks consistency or accessibility):
1. [Finding with file path, line, and fix]

Important (drift or inconsistency):
1. [Finding with file path, line, and fix]

Maintenance (cleanup and documentation):
1. [Finding with file path, line, and fix]

AI Slop patterns detected:
| Pattern ID | Pattern | Files | Severity |
|-----------|---------|-------|----------|
| CC-03 | Gradient text | Hero.tsx:42, Stats.tsx:18 | Critical (Product) |
| VD-01 | Side-accent border | Card.tsx:8 | Critical (Product) |
| TY-08 | Overused font (Inter) | tailwind.config:12 | Note (acceptable as system font) |

Healthy patterns (what's working well):
1. [Specific positive finding]

When reporting AI slop, distinguish Brand context (landing/marketing -- some patterns may be intentional) from Product context (app/dashboard -- patterns are almost always slop). Use the Brand vs Product applicability column from the detector reference.


Step 3: Mode -- Foundation

Read references/foundation-workflow.md for the complete foundation workflow.

Two entry points:

A. From screenshot (new project)

  1. Analyze screenshot -- extract colors, typography, spacing, radius, shadows
  2. Initialize shadcn (npx shadcn@latest init)
  3. Generate globals.css with all CSS variables (light + dark)
  4. Map tokens to Tailwind via @theme inline (v4) or tailwind.config (v3)
  5. Install font in layout.tsx
  6. Install base components: button, card, badge, alert, radio-group
  7. Create styleguide structure (/app/styleguide/)

B. From existing project (extract and organize)

  1. Scan all CSS/TSX files for color values, spacing, typography
  2. Identify patterns and group into token categories
  3. Create/update globals.css with organized CSS variables
  4. Replace hardcoded values with token references
  5. Create styleguide if it doesn't exist

Output: Design Summary with primary color, font, style, radius, overall feel.


Step 4: Mode -- Component

Read references/component-workflow.md for the complete component workflow.

Summary:

  1. Check for duplicates -- search the project for existing implementations
  2. Search shadcn registry -- use MCP or manual search
  3. Install or build -- shadcn component > customize > or build from primitives
  4. Create showcase -- /app/styleguide/components/[name]/page.tsx
  5. Update navigation -- add to /app/styleguide/navigation.ts
  6. Verify -- all variants, all states, dark mode, accessibility

Rules:

  • Always search the project FIRST to avoid duplicates
  • Extend shadcn, never rebuild from scratch
  • Every component gets a showcase page
  • CSS variables for all colors -- never hardcode

Step 5: Mode -- Page

Read references/page-workflow.md for the complete page workflow.

Summary:

  1. Analyze design -- layout, sections, hierarchy, components needed
  2. Map to existing components -- prioritize what's already in the DS
  3. Install missing components -- via shadcn if available
  4. Build page -- /app/[page-name]/page.tsx
  5. Apply responsive behavior -- mobile-first
  6. Post-build verification -- check all values come from the design system

Critical rule: IMPORT existing components. If the AI creates something that already exists in the DS, refactor immediately.


Step 6: Mode -- Document

Generate or update design system documentation.

What to document

  1. Token inventory -- all CSS variables organized by category
  2. Component catalog -- every component with:
    • Import statement
    • Available props/variants
    • Usage examples
    • Accessibility notes
  3. Usage guidelines -- when to use each component, when NOT to
  4. File structure -- where everything lives

Workflow

  1. Read globals.css and extract all token categories
  2. List all components in components/ui/ and components/
  3. Read each component file to extract props and variants
  4. Check for existing showcase pages
  5. Generate .docs/design-system.md (or update if exists)
  6. Report what's documented vs. what's missing

Output format

# Design System - [Project Name]

## Tokens
### Colors
| Token | Light | Dark | Usage |
|-------|-------|------|-------|
| --primary | #hex | #hex | Brand color, CTAs |

### Typography
| Token | Value | Usage |
|-------|-------|-------|

### Spacing
| Token | Value | Usage |
|-------|-------|-------|

## Components
### Button
- **Import:** `import { Button } from "@/components/ui/button"`
- **Variants:** default, destructive, outline, secondary, ghost, link
- **Sizes:** default, sm, lg, icon
- **States:** hover, focus, disabled, loading

[... for each component]

Step 7: Mode -- Sync Figma

Synchronize design tokens and components between Figma and code.

Sub-modes

Pull -- Extract tokens from Figma file:

  1. Use Figma MCP get_design_context or get_variable_defs to read tokens
  2. Compare with globals.css -- identify differences
  3. Present diff to user before applying changes
  4. Update globals.css with new tokens (user approves)

Compare -- Check parity between Figma and code:

  1. Read Figma tokens via MCP
  2. Read code tokens from globals.css
  3. Report: tokens only in Figma, tokens only in code, value mismatches

Generate -- Create code from Figma component:

  1. Use Figma MCP get_design_context with component node
  2. Map to shadcn components (prioritize existing DS components)
  3. Generate component code using design system tokens
  4. Create showcase page

Output format for Compare:

Figma <> Code Sync Report

Matching: [X] tokens
Only in Figma: [list with values]
Only in Code: [list with values]
Value Mismatches:
| Token | Figma | Code | Action |
|-------|-------|------|--------|

Step 8: Mode -- Context

Read references/context-doc-template.md for the complete workflow and template.

What it does: generates or updates .docs/design-system-context.md -- the briefing document that any AI (or new team member) reads before operating on the design system.

Why this matters: without a context document, every interaction starts from zero. The skill (and any other AI tool) has to infer principles, constraints, and quirks from scratch every time. This file is the project's single source of truth for why the design system is the way it is, not just what is in it.

Summary:

  1. Discovery -- read globals.css, components, package.json, existing styleguide to extract what's already evident.
  2. Interview -- ask the user 5-7 focused questions for what can't be extracted (principles, quirks, contribution process, accessibility target, out-of-scope products).
  3. Draft -- generate .docs/design-system-context.md using the template. Mark gaps as TODO: rather than guessing.
  4. Review -- show the draft, ask for corrections and additions.
  5. Save and register -- write the file and update project CLAUDE.md to reference it.

Triggers update (not full regeneration):

  • New components added to the system
  • Major principle or convention change
  • New organizational constraint (legal, brand, regulatory)
  • Periodic refresh (every 3-6 months for active systems)

Output: path to the generated file, summary of sections filled from code vs. from interview vs. left as TODO, and next steps.


Stack Requirements

Mandatory

  • Framework: Next.js (App Router)
  • UI Library: shadcn/ui
  • Styling: Tailwind CSS 4 with CSS variables (support v3 if project uses it)
  • Icons: lucide-react

Recommended MCPs

  • shadcn MCP -- search, view, install components from registry
  • Figma MCP -- pull tokens and components from Figma

Token Architecture (CSS Variables)

All tokens live in globals.css as CSS custom properties. This is the single source of truth.

The 3 token tiers (mandatory mental model)

Tokens have three layers of decision, from rawest to most specific:

TierNameExampleAudience
1. Primitive (core/global)Raw value--purple-500: #6E56CFDS designers only
2. Semantic (alias)Decision of use--primary: var(--purple-500)Product designers
3. ComponentComponent-specific--button-bg: var(--primary)Engineers

Why this hierarchy matters: To change the brand color from purple to blue, you change one line at the semantic tier (--primary: var(--blue-500)) and it cascades to every component. Without tiers, you'd change it in 200 places.

Practical rule:

  • Components never reference primitives directly. Always go through semantic.
  • Component tokens only exist when the same value is reused 3+ times in one component, or when the component has overrides that the semantic layer doesn't express.
  • shadcn/ui follows this pattern: globals.css defines semantic tokens (--primary, --secondary, etc.), components consume them via Tailwind classes (bg-primary).

Required token categories

:root {
  /* Base */
  --background, --foreground

  /* Surfaces */
  --card, --card-foreground
  --popover, --popover-foreground
  --sidebar, --sidebar-foreground

  /* Brand */
  --primary, --primary-foreground
  --secondary, --secondary-foreground
  --accent, --accent-foreground

  /* Feedback */
  --muted, --muted-foreground
  --destructive, --destructive-foreground
  --success, --success-foreground
  --warning, --warning-foreground
  --info, --info-foreground

  /* Utility */
  --border, --input, --ring, --radius

  /* Charts */
  --chart-1 through --chart-5

  /* Motion -- see below, these are missing from most systems */
  --duration-fast, --duration-base, --duration-slow
  --ease-out, --ease-in, --ease-in-out

  /* Stacking */
  --z-base, --z-dropdown, --z-sticky, --z-overlay, --z-modal, --z-toast

  /* Icon */
  --icon-stroke, --icon-size-sm, --icon-size-base, --icon-size-lg
}

.dark {
  /* All variables redefined for dark mode */
}

The three categories almost every system forgets. Color, spacing, type and radius get tokenized because they are visible in Figma. These do not, so they get hardcoded in components and drift immediately:

  • Motion. Without duration and easing tokens, every developer picks their own 300ms ease-in-out and the product has no consistent tempo. Defaults: --duration-fast: 100ms (hover, press), --duration-base: 200ms (most interactions -- anything slower reads as lag), --duration-slow: 300ms (overlays, route transitions). Easing: out for entering, in for leaving, in-out for repositioning. Motion also needs an accessibility rule, not just values: state where prefers-reduced-motion is handled -- globally, or per component.
  • Z-index. An undeclared z-index scale is how you get z-index: 9999 in a dropdown and a modal that renders behind it. Six named layers is enough.
  • Iconography. Not just "use Lucide" -- declare stroke width, the size ramp, optical alignment rule, and naming. Two icon sets with different stroke weights in the same product is the most visible inconsistency a user never consciously notices.

Tailwind CSS 4 mapping

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  /* ... map all tokens to Tailwind */
}

Tailwind CSS 3 mapping

// tailwind.config.js
theme: {
  extend: {
    colors: {
      background: 'var(--background)',
      foreground: 'var(--foreground)',
      // ... map all tokens
    }
  }
}

File Structure Convention

app/
  globals.css                    # Design tokens (CSS variables) -- SOURCE OF TRUTH
  layout.tsx                     # Root layout with font
  styleguide/
    layout.tsx                   # Styleguide layout with sidebar navigation
    navigation.ts                # Navigation config (updated when adding components)
    page.tsx                     # All design tokens displayed
    components/
      [component-name]/
        page.tsx                 # Individual component showcase
  [page-name]/
    page.tsx                     # Project pages

components/
  ui/                            # Base shadcn components (auto-generated, don't edit)
  [ComponentName].tsx            # Custom/extended components

Quality Gates

Before finishing any mode, verify:

  • All color values reference CSS variables (no hardcoded hex in components)
  • All spacing values are from the 8pt grid (4, 8, 12, 16, 24, 32, 48, 64)
  • Border-radius values are consistent (using --radius or defined scale)
  • Dark mode tokens are complete (every :root variable has a .dark equivalent)
  • New components have showcase pages
  • navigation.ts is updated
  • Components use cn() utility for class merging
  • Accessibility: contrast 4.5:1, visible labels, 44px touch targets

Pushback Protocol

Flag design system violations even when not asked:

  • Hardcoded colors in components → "This bypasses the design system"
  • Component recreated instead of imported → "This already exists in the DS"
  • Token not in globals.css → "This value isn't part of the system"
  • Spacing off the 8pt grid → "This breaks the spacing system"
  • Missing dark mode → "Dark mode tokens are missing for this"

Format: "DS note: [concern]. Suggestion: [fix]. Want me to apply it?"

Push back ONCE. If the user insists, implement without further argument.


Anti-Patterns (Hard Blocks)

  • Token sprawl: creating new tokens for every component instead of reusing existing ones. Before adding a token, check if an existing one works.
  • Hardcoded values: hex colors, pixel spacing, or font sizes outside the system. Always reference CSS variables.
  • Component duplication: building a component that already exists in shadcn or in the project. Search first, always.
  • Showcase neglect: adding components without showcase pages. If it's not documented, it'll be recreated.
  • Inconsistent naming: mixing conventions (bg-brand vs bg-primary). Follow shadcn naming conventions.

NEVER

  • NEVER hardcode colors -- always use CSS variables via Tailwind classes
  • NEVER create a component without checking shadcn registry first
  • NEVER skip the showcase page when adding a component
  • NEVER modify files in components/ui/ directly -- extend with wrappers
  • NEVER add tokens without dark mode equivalents
  • NEVER use spacing values outside the 8pt grid
  • NEVER ignore existing design system patterns in the project
  • NEVER ignore .docs/design-system-context.md if it exists -- it overrides generic assumptions with project-specific principles and constraints
  • NEVER forget to update navigation.ts when adding components

Working With Other Skills

  • ux-research handles discovery and evidence -- when you need to validate assumptions or understand user needs before building, hand off to ux-research.
  • ux-designer handles experience strategy -- when the flow, psychology, or user journey needs design, hand off to ux-designer.
  • ui-designer handles visual craft -- when the DS is set up and individual components need visual polish, spacing refinement, or aesthetic decisions, hand off to ui-designer.

This skill handles the infrastructure layer: tokens, components, consistency, documentation, and Figma sync. When another skill is more appropriate, say so directly.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.