Developer Tools

Shelf Skill Guide

Audience: Frontend Engineers | Repo: sp-claude-skills | Ticket: SPPLT-19926

TL;DR: Shelf audits your frontend code for things that should use @solidprofessorhub/* packages instead of hand-rolled implementations. Run /shelf in Claude Code to get an HTML report of what to swap.

The Problem

Why We Keep Reinventing the Wheel

Developers hand-roll code that already exists in shared packages because:

Discovery is hard — "I didn't know BaseButton existed"
Migration inertia — Code copied from platform-frontend brings old patterns
Time pressure — Writing a raw <button> feels faster than looking up the component API

The result: inconsistent UI, duplicated types, missed security policies (like PII scrubbing in observability), and more code to maintain.

The Solution

Two Skills Working Together

📘 solidprofessor-packages

Proactive guidance — loaded when writing code

Complete catalog of what exists
Decision tree: "Need a button? → BaseButton"
Prevents the problem before it happens

🔍 shelf

Reactive audit — run after code is written

Scans for anti-patterns
Generates actionable report
Catches what slipped through

STEP 1

Write Code

solidprofessor-packages guides choices

→

STEP 2

Run /shelf

Audit for missed opportunities

→

STEP 3

Review Report

Decide what to adopt

How to Use

Running a Shelf Scan

Basic Usage

# Scan entire app
/shelf

# Scan specific path
/shelf app/components/course/

# Scan specific file
/shelf app/components/course/CourseSectionsList.vue

What You Get

Shelf generates two outputs:

Console summary — Quick text overview of findings
HTML report — shelf-report.html at repo root, auto-opens in browser

Advisory Only

Shelf never edits files or blocks anything. It reports findings — you decide what to adopt.

Reading the HTML Report

The generated shelf-report.html has four main sections:

📊 Summary Stats

At-a-glance counts: swaps to make, available-but-unused, and installed shared packages.

📦 Package Versions

Shows installed vs latest for each @solidprofessorhub/* package. Highlights outdated packages with upgrade notes.

🔄 Findings by Category

Grouped by package (shared-components, icons, tokens, etc.). Each finding shows before → after code with file:line reference.

💡 Available But Not Used

Installed capabilities you're not taking advantage of — often the most valuable section for discovery.

Use the filter chips at the top to focus on one category at a time. Click through file references to locate code in your editor.

What It Detects

Detection Categories

UI Components

↓

Form Fields

↓

Design Tokens

text-[#121A26]

↓

text-neutral-90

Icons (Tokened)

↓

Observability

import * as Sentry from '@sentry/vue'

↓

import { captureException } from '@solidprofessorhub/observability'

Deprecated Imports

import { useAuth } from '@solidprofessorhub/shared-components'

↓

import { useAuth } from '@solidprofessorhub/auth'

Full Detection List

Category	Detects	Suggests
shared-components	Raw `<button>`, `<input>`, `<select>`, hand-built modals	BaseButton, BaseTextInput, TextField, FormModal, etc.
icons	FontAwesomeIcon for tokened icons	BaseIcon (angle-down, magnifying-glass, xmark, etc.)
tokens	Hardcoded hex colors, Tailwind arbitrary values	Design token classes (text-neutral-90, bg-primary-50)
http	axios, raw fetch for same-origin mutations	useHttp().postJson(), useHttp().getJson()
auth	localStorage token access, manual JWT parsing	useAuth().token, useAuth().isLoggedIn
types	Local interfaces duplicating shared types	Import from @solidprofessorhub/types
observability	Direct @sentry/vue usage	@solidprofessorhub/observability (includes PII scrubbing)
deprecation	useAuth/useHttp from shared-components	Standalone @solidprofessorhub/auth and /http packages

Configuration

Project-Specific Settings

Add a .shelfrc.json at repo root to customize behavior:

{
  "ignore": [
    "**/test/**",
    "**/stories/**",
    "**/*.spec.ts"
  ],

  "tokenDrift": "warn",

  "customTokenMap": {
    "#2d833f": "primary-50"
  },

  "allowedFontAwesomeIcons": [
    "graduation-cap",
    "bookmark"
  ],

  "framework": "nuxt"
}

Example: Nuxt Project

{
  "ignore": [
    "**/__tests__/**",
    "**/stories/**",
    "**/*.spec.ts",
    "**/*.test.ts",
    "server/**"
  ],
  "framework": "nuxt",
  "tokenDrift": "warn",
  "allowedFontAwesomeIcons": [
    "graduation-cap",
    "cloud-arrow-down",
    "bookmark"
  ]
}

Nuxt note: With "framework": "nuxt", shelf won't flag useFetch() for SSR data fetching — that's intentional in Nuxt. It will still flag fetch() and axios for client-side mutations.

Example: Vue SPA

{
  "ignore": [
    "**/__tests__/**",
    "**/stories/**",
    "**/*.spec.ts",
    "**/*.test.ts",
    "**/mocks/**"
  ],
  "framework": "vue",
  "tokenDrift": "strict"
}

Vue SPA note: All fetch() and axios calls to internal APIs should use @solidprofessorhub/http for consistent auth token injection and 401 refresh handling.

Option	Purpose
`ignore`	Glob patterns to skip (tests, stories, legacy code)
`tokenDrift`	"strict" \| "warn" \| "skip" — how to handle close-but-not-exact token matches
`customTokenMap`	Project-specific hex → token mappings (for projects with different token values)
`allowedFontAwesomeIcons`	Icons that aren't in BaseIcon's token set — don't flag these
`framework`	"nuxt" \| "vue" — affects rules (e.g., Nuxt useFetch() is not flagged)

Maintenance

Keeping the Skill Current

When to Update

Package version bumps — Update version references in the catalog
New components added — Add to the detection list
New integrations packages — Add detection for raw SDK usage
BaseIcon token set expands — Update the swappable icons list

Where It Lives

sp-claude-skills/
├── shelf/
│   ├── SKILL.md              # Main skill definition
│   └── report-template.html  # HTML report template
└── solidprofessor-packages/
    └── SKILL.md              # Proactive catalog

Keep Both Skills in Sync

When updating the package catalog in solidprofessor-packages, also update the detection rules in shelf. They reference the same packages.

Version References

Current versions documented in the skill:

Package	Version	Check Latest
@solidprofessorhub/shared-components	1.29.x	`npm view @solidprofessorhub/shared-components version`
@solidprofessorhub/auth	2.0.x	`npm view @solidprofessorhub/auth version`
@solidprofessorhub/http	1.0.x	`npm view @solidprofessorhub/http version`
@solidprofessorhub/types	1.0.x	`npm view @solidprofessorhub/types version`
@solidprofessorhub/observability	0.0.x	`npm view @solidprofessorhub/observability version`

Best Practices

Getting the Most from Shelf

When to Run

After migrating code from platform-frontend to an MFE
During PR review — quick check for missed opportunities
Periodic audits — monthly check on the whole codebase
Onboarding — show new devs what packages are available

Interpreting Results

Not Everything Needs to Change

Shelf flags opportunities, not requirements. Some findings are intentional (external URL fetch, Nuxt useFetch for SSR). Use judgment — the report is a starting point, not a mandate.

"Available But Not Used" Section

This section is often the most valuable — it surfaces capabilities you might not know exist:

"useModal()/FormModal installed but modals are hand-rolled" → You could simplify modal code
"TextField wraps input + label + validation" → Stop rebuilding form markup
"@solidprofessorhub/types exports ActiveUser" → Don't define local User interfaces

Common False Positives

Some findings are intentional and don't need action:

Finding	When It's Intentional	Fix
`fetch()` flagged	Nuxt `useFetch()` for SSR data, or fetching external URLs (transcripts, third-party APIs)	Add `"framework": "nuxt"` to .shelfrc.json; external URLs are noted as "confirm: external?"
FontAwesome icon flagged	Icon isn't in BaseIcon's token set (most icons)	Add to `allowedFontAwesomeIcons` in .shelfrc.json, or expand BaseIcon's token map
Hex color flagged	Project uses different token values than shared-components	Add mapping to `customTokenMap` in .shelfrc.json
Raw `<button>` in tests	Test files shouldn't use shared components	Add `"*/.test.ts"` and `"/__tests__/"` to ignore patterns
Local type definition	Type extends or differs from shared type intentionally	Review if you can import and extend vs. duplicate; shelf flags "overlaps" not "identical"
@sentry/vue direct usage	@solidprofessorhub/observability not installed yet	Shelf notes "consider installing" — not a bug, just an adoption opportunity

When in Doubt, Keep It

If a finding seems wrong, it probably is. Add an ignore pattern or allowlist entry rather than making a change you're not confident about. Shelf is advisory — false positives are expected and easy to suppress.

Links

Resources

shelf skill — SKILL.md and report template
solidprofessor-packages skill — Proactive package catalog
sp-claude-skills repo — All SolidProfessor Claude skills
shared-frontend repo — shared-components source
SPPLT-19926 — Shelf skill ticket

Engineering

Shelf Skill Guide

Why We Keep Reinventing the Wheel

Two Skills Working Together

📘 solidprofessor-packages

🔍 shelf

Running a Shelf Scan

Basic Usage

What You Get

Reading the HTML Report

📊 Summary Stats

📦 Package Versions

🔄 Findings by Category

💡 Available But Not Used

Detection Categories

UI Components

Form Fields

Design Tokens

Icons (Tokened)

Observability

Deprecated Imports

Full Detection List

Project-Specific Settings

Example: Nuxt Project

Example: Vue SPA

Keeping the Skill Current

When to Update

Where It Lives

Version References

Getting the Most from Shelf

When to Run

Interpreting Results

"Available But Not Used" Section

Common False Positives

Resources