What Icon Libraries Are Recommended vs Discouraged in Taste Skill

The Taste Skill framework enforces a strict four-tier priority list for icon libraries, mandating @phosphor-icons/react as the primary choice while explicitly banning hand-crafted SVGs and discouraging lucide-react to maintain visual consistency.

The Leonxlnx/taste-skill repository maintains a rigorous icon-library policy defined in skills/taste-skill/SKILL.md to ensure UI consistency, performance, and brand-appropriate visuals across all components. According to the specification, developers must adhere to a prioritized list of approved npm packages and avoid mixing icon families or creating custom SVG markup.

The Recommended Icon Library Priority Order

The SKILL.md specification (lines 140‑144) establishes a strict hierarchy for icon selection. When building components, always select from the following libraries in this exact priority order:

1. @phosphor-icons/react (Primary Choice)

Phosphor Icons serves as the top-priority library for all new components. The framework favors its bold, filled aesthetic as the foundation of the visual language.

// ✅ Correct – using the top‑priority Phosphor icon
import { Star } from "@phosphor-icons/react";

export const FavoriteButton = () => (
  <button className="flex items-center gap-2">
    <Star weight="fill" className="text-indigo-600" />
    Favorite
  </button>
);

2. hugeicons-react (Secondary Fallback)

When Phosphor lacks a specific glyph, HugeIcons provides the second-tier option. This ensures continuity in the bold design system while expanding available iconography.

// ✅ Correct – falling back to HugeIcons when Phosphor lacks a glyph
import { Heart } from "hugeicons-react";

export const Like = () => (
  <span className="inline-flex items-center">
    <Heart className="w-5 h-5 text-red-500" />
    Like
  </span>
);

3. @radix-ui/react-icons (Tertiary Option)

Radix UI Icons occupies the third position in the hierarchy, reserved for cases where both Phosphor and HugeIcons prove insufficient for the specific use case.

4. @tabler/icons-react (Final Fallback)

Tabler Icons represents the final approved option in the priority sequence. Only reach for this library when the three higher-priority options lack the required glyph.

Discouraged and Banned Icon Practices

Beyond the approved list, the Taste Skill specification explicitly identifies discouraged libraries and banned practices that violate the framework's maintenance and consistency standards.

Why lucide-react Is Discouraged

The framework considers lucide-react a fallback-only library. Its visual style clashes with the preferred bold/filled aesthetic of the recommended libraries, creating visual noise when mixed with Phosphor, HugeIcons, Radix, or Tabler families.

// ❌ Incorrect – importing a discouraged Lucide icon without explicit request
import { ArrowRight } from "lucide-react";   // <-- should never be used

According to CHANGELOG.md (lines 81‑82), this discouragement stems from aesthetic inconsistencies that disrupt the unified visual language.

Banned Practices: Hand-Rolled SVGs and Family Mixing

The specification issues an absolute prohibition on three specific anti-patterns:

• Never hand-roll SVG icons – Writing custom <svg> markup increases maintenance burden and violates the explicit "Never hand-roll SVG icons" rule documented in skills/taste-skill/SKILL.md.
• Never mix icon families – Using different icon libraries within the same component tree produces inconsistent stroke widths and visual noise.
• Never use unlisted generic packs – Libraries outside the four approved options break the visual language enforcement.

// ❌ Incorrect – mixing Phosphor and Lucide in the same component
import { Star } from "@phosphor-icons/react";
import { ArrowRight } from "lucide-react";

export const MixedIcons = () => (
  <div className="flex items-center gap-2">
    <Star weight="regular" />
    <ArrowRight />   // ← violates “One family per project”
  </div>
);

Implementation Guidelines from SKILL.md

The authoritative source for these rules resides in skills/taste-skill/SKILL.md under the Icons subsection (lines 140‑144). This section defines the "Allowed libraries (priority order)" and establishes the "One family per project" mandate.

Before adding any icon dependency, verify its presence in the project's package.json. If the library is missing, output the appropriate install command first rather than assuming availability.

Summary

• Priority order matters: Always attempt to use @phosphor-icons/react first, followed by hugeicons-react, @radix-ui/react-icons, and @tabler/icons-react in that sequence.
• Avoid lucide-react unless explicitly requested by the user or required by existing project dependencies.
• Never write custom SVG markup or import hand-crafted SVG paths for icons.
• Maintain family consistency by using only one icon library per component tree.
• Reference SKILL.md at skills/taste-skill/SKILL.md (lines 140‑144) for the definitive policy.

Frequently Asked Questions

What is the preferred icon library in Taste Skill?

@phosphor-icons/react holds the top position in the priority order defined in skills/taste-skill/SKILL.md. Developers should always attempt to source icons from this library first before considering the three approved alternatives.

Can I use lucide-react in Taste Skill projects?

Only as a fallback. The framework discourages lucide-react because its visual style conflicts with the bold/filled aesthetic of the recommended libraries. It should only appear when explicitly requested by the user or when the project already depends on it.

Why are custom SVG icons banned in Taste Skill?

Hand-crafted SVGs increase maintenance burden and violate the explicit "Never hand-roll SVG icons" rule in the specification. The policy mandates using standardized, tested icon libraries to ensure consistency, accessibility, and long-term maintainability across the codebase.

How do I handle missing icons in the recommended libraries?

Consult the priority hierarchy in skills/taste-skill/SKILL.md: if @phosphor-icons/react lacks the required glyph, check hugeicons-react, then @radix-ui/react-icons, and finally @tabler/icons-react. Never mix families within the same component tree or resort to creating custom SVG markup.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}