System Rename | Prisma Design System

System Rename — Universal Rename Tool

Rename anything in the Prisma Design System safely. This skill ensures that when a name changes, every reference across the entire project updates together — no orphaned refs, no broken token chains, no stale docs.

How to Use This Skill

This file (SKILL.md) — Protocol, safety rules, execution order. Read this first.
references/impact-map.md — Which files to scan for each target type. Read during Step 1.
references/naming-rules.md — Naming conventions to validate the new name. Read before Step 2.

1. What Can Be Renamed

Target Type	Example	Key Impact
Token key	`spacing.4` → `spacing.100`	JSON → CSS vars → HTML → docs → specs → ATOMIC-MAPPING
Component	`bottom-nav` → `navigation-bar`	Spec MD → CSS → HTML → docs → slots → ATOMIC-MAPPING → knowledge
CSS variable	`--comp-radius` → `--comp-border-radius`	variables.css → all CSS → HTML inline styles
CSS class	`.card-header` → `.surface-header`	CSS → HTML → docs templates → showcases
Theme	`prisma` → `prisma-core`	themes/*.json → showcase-config → CSS → HTML data-theme attrs
Style	`liquid` → `glass-liquid`	styles/*.json → showcase-config → CSS
Slot	`card-header` → `card-head`	slot-manifest → slot-api.d.ts → specs → HTML data-slot attrs
File	`bottom-nav.md` → `navigation-bar.md`	Physical file + all cross-references

2. The 5-Step Protocol

Every rename follows the same sequence. Never skip steps — the order prevents cascading breakage.

Step 1 — IMPACT SCAN

Identify every file that references the old name. This is the foundation — miss a file here and you'll have a broken reference that only surfaces later.

text

ACTION:
1. Read references/impact-map.md for the target type
2. Grep the entire project for the old name using the patterns from impact-map
3. Record: file path, line number, context snippet
4. Check for SUBSTRING CONFLICTS:
   - Is the old name a substring of another name?
     e.g., "card" appears in "card-header", "stat-card", "card-content"
   - If yes → flag these as "partial matches" — they need manual review
5. Check for NAME CONFLICTS:
   - Does the new name already exist in the system?
   - If yes → STOP and warn User

OUTPUT: Impact Report
┌────────────────────────────────┬───────────┐
│ File                           │ Matches   │
├────────────────────────────────┼───────────┤
│ tokens/shared/focus.tokens.json│ 3         │
│ components md/button.md        │ 1         │
│ ...                            │ ...       │
├────────────────────────────────┼───────────┤
│ TOTAL                          │ N files   │
│ Partial matches (review)       │ M         │
│ Name conflict                  │ YES / NO  │
└────────────────────────────────┴───────────┘

Step 2 — PREVIEW & CONFIRM

Present the Impact Report to the User. The goal is informed consent — the User should understand exactly what will change before anything happens.

text

ACTION:
1. Validate new name against references/naming-rules.md
   - If invalid → suggest corrections, ask User to pick
2. Show the Impact Report from Step 1
3. Highlight any partial matches that need manual decisions:
   "card" → "surface" — should "card-header" become "surface-header"?
4. Wait for User confirmation before proceeding

⚠️ TIER CHECK (from token-governance):
   - Renaming primitives → MUST get explicit User approval + reason
   - Renaming shared tokens → MUST get explicit User approval
   - Renaming modes/themes → MUST get explicit User approval
   - Renaming style-modes/styles/classes → can proceed with standard confirm

Step 3 — EXECUTE RENAME

Replace the old name with the new name across all files. The order matters — start from the source-of-truth files and work outward to consuming files. This way, if something goes wrong partway through, the source is already correct.

text

EXECUTION ORDER (source-of-truth first, consumers last):

1. Token JSON files (follow tier order):
   primitives/ → shared/ → modes/ → themes/ → density/ → styles/
   
2. ATOMIC-MAPPING.md — component↔token mapping

3. Component spec MDs — design-system/components md/*.md

4. Slot files — knowledge/slot-manifest.json + code-connect/slot-api.d.ts

5. CSS source files:
   - design-system/tailwind.css
   - design-system/creative-recipes/*.css
   - showcase/**/*.css (ONLY source CSS, not generated)
   
6. HTML source files:
   - showcase/**/*.html
   - design-system/scripts/docs-template/*.html
   - design-system/scripts/docs-template/*.js
   - design-system/scripts/docs-template/*.css

7. Build scripts — ONLY if they contain hardcoded references:
   - design-system/scripts/pipeline/*.js
   - design-system/scripts/config/showcase-config.json

8. Knowledge & docs:
   - knowledge/**/*.md
   - knowledge/**/*.json
   - docs guide useful-doc — markdown references

9. Physical file rename (if target type = FILE or COMPONENT):
   - Rename the file itself
   - Update any import/require/link that points to the old filename

🚫 DO NOT EDIT GENERATED FILES:
   - design-system/tokens/variables.css (generated by sync-tokens)
   - design-system/tokens/primitives.css (generated by sync-tokens)
   - design-system/dist/prisma.css (generated by TW build)
   - docs/assets/*.css (generated by build-docs)
   - docs/components/*.html (generated by build-docs)
   These will be regenerated in Step 4.

Step 4 — REBUILD + DOCS UPDATE

Run the pipeline so generated files pick up the new name. This is the same pipeline from post-change workflow, but mandatory here because rename affects source-of-truth files.

Additionally, the docs/ directory needs explicit cleanup — build-docs generates new files with new names but may leave orphaned files with old names.

text

ACTION:

4a. DELETE old generated doc files (before rebuild):
    - docs/components/{OLD}.html  → delete (will be regenerated as {NEW}.html)
    - docs/assets/ files are shared, no need to delete

4b. Run full pipeline:
    node design-system/scripts/pipeline/run-pipeline.js --all
    
    This rebuilds:
    - design-system/tokens/variables.css (sync-tokens)
    - design-system/dist/prisma.css (TW build)
    - docs/components/{NEW}.html (build-docs)
    - docs/index.html (build-docs — component list updates)
    - docs/assets/components.css (build-docs — from preview-extras.css)

4c. VERIFY docs updated:
    - docs/components/{NEW}.html exists → ✅
    - docs/components/{OLD}.html does NOT exist → ✅
    - docs/index.html component list shows new name → ✅

If pipeline fails, check if the failure is rename-related:

Missing variable reference → a file was missed in Step 3, go back and fix
Token not found → JSON key wasn't updated, check Step 3 tier 1

Step 5 — VALIDATE & LOG

Verify the rename is complete with zero stale references, then log the change.

text

ACTION:
1. Grep the entire project for the OLD name
   - Expected: 0 matches
   - Exceptions: CHANGELOG.md, dev-journal/, git history (these are OK)
   - If matches found → go back to Step 3 for missed files

2. Run verify-output.js
   node design-system/scripts/pipeline/verify-output.js
   - Expected: 0 errors

3. Write RENAME LOG entry:

RENAME LOG:
- Type: TOKEN | COMPONENT | CSS_VAR | CLASS | THEME | STYLE | SLOT | FILE
- Old: {old-name}
- New: {new-name}
- Files changed: {count}
- Reason: {user-provided reason}
- Validated: ✅ 0 stale references | ❌ N remaining (list them)

4. Chain workflows:
   → post-change (the pipeline already ran, but post-change handles extras)
   → dev-journal (record the rename)

3. Safety Rules

These exist because renames are high-blast-radius operations. A wrong rename can break the entire design system silently.

Rule	Why
Always preview before execute	User sees full impact before anything changes
Never rename primitives without User approval	Primitives affect every downstream token
Never edit generated files	They'll be overwritten — fix the source instead
Check for name conflicts first	Renaming to an existing name creates ambiguity
Check for substring conflicts	`card` → `surface` might unintentionally hit `card-header`
Follow execution order	Source-of-truth files first, consumers last
Validate after rebuild	Grep for old name must return 0 (excluding changelogs)
Log every rename	Traceability for debugging regressions

4. Batch Rename

When renaming multiple related items (e.g., renaming a component and all its tokens), group them into a single rename session:

text

1. Collect all old→new pairs
2. Run Step 1 for ALL pairs (combined impact scan)
3. Show combined preview to User
4. Execute ALL renames in one pass (still following execution order)
5. Run pipeline ONCE
6. Validate ALL pairs

This is faster than individual renames and reduces pipeline runs.

5. Anti-patterns

❌ Don't	✅ Do	Why
Find-and-replace without impact scan	Run Step 1 first	Blind replace hits substring matches
Rename in generated files	Rename in source, then rebuild	Generated files get overwritten
Rename without User confirmation	Always show preview	Renames are hard to undo
Skip validation after rename	Always grep for old name	Stale refs cause silent breakage
Rename one file and call it done	Follow the full 5-step protocol	Cross-references span many files
Rename primitives without asking	Check token-governance tier rules	High-blast-radius changes need approval

6. Reference Files

File	Read when...
impact-map.md	Step 1 — need file paths and grep patterns for each target type
naming-rules.md	Step 2 — validating that the new name follows conventions