Taste Skill Icon Library Recommendations: Hierarchy, Policy, and Lucide Restrictions

The Taste Skill framework mandates a strict four-tier icon library hierarchy topped by Phosphor Icons, explicitly restricts Lucide React to explicit user requests only, and enforces single-family usage per project to eliminate visual inconsistency and reduce bundle size.

The Leonxlnx/taste-skill repository defines rigorous standards for iconography in modern React applications. Understanding these Taste Skill icon library recommendations ensures your components remain consistent, accessible, and performant while avoiding the "sloppiness" that comes from mixing disparate visual languages.

The Four-Tier Icon Hierarchy Defined in SKILL.md

According to the core skill definition in skills/taste-skill/SKILL.md (lines 40-46), the framework prioritizes specific libraries in strict order:

1. @phosphor-icons/react
2. hugeicons-react
3. @radix-ui/react-icons
4. @tabler/icons-react

This priority list is formally documented in the changelog at CHANGELOG.md (line 81), establishing Phosphor as the default choice unless specific project constraints require alternatives.

Priority Placement and Bundle Considerations

The hierarchy reflects not merely aesthetic preference but performance characteristics and consistency guarantees. Phosphor Icons offer the most comprehensive weight system (thin, light, regular, bold, fill, duotone), while Huge Icons and Radix provide lighter alternatives when bundle size is critical. The source code explicitly discourages deviating from this order without justification.

The Lucide Policy: Discouraged by Default

Unlike the preferred libraries, Lucide (lucide-react) carries explicit restrictions under the Taste Skill policy. The framework permits Lucide only under two specific conditions:

• When the user explicitly requests it
• When the target project already depends on it

This "on-request only" stance prevents accidental style mixing and maintains the visual coherence that defines Taste Skill projects. The policy is designed to prevent developers from defaulting to Lucide when higher-priority alternatives exist in the hierarchy.

Core Enforcement Rules

Beyond library selection, the framework imposes strict implementation standards derived from the source analysis.

Single Family Per Project

Mixing Phosphor with Lucide (or any combination of families) within the same component tree is strictly forbidden. This rule eliminates visual incoherence and prevents the bundle bloat that occurs when multiple icon libraries load conflicting SVG path definitions. The assertSingleIconFamily utility demonstrated below shows how projects can enforce this at build time.

Standardized Stroke Width

The skill mandates a uniform strokeWidth across all icons—typically 1.5 or 2.0. This requirement ensures visual harmony regardless of which approved library you select, preventing jarring differences between icons from different sources.

No Hand-Rolled SVGs

When a required glyph is missing from your chosen library, you must add a second approved library or compose the icon from primitives. Hand-crafted SVG paths are banned to avoid inconsistent quality, scaling issues, and accessibility pitfalls that often accompany custom implementations.

Implementation Examples

The following patterns demonstrate compliant usage according to the Taste Skill source code.

Standard Phosphor Implementation

When using the top-priority library, maintain consistent stroke width as dictated by the skill:

"use client";

import { ArrowRight } from "@phosphor-icons/react";

export function CTAButton({ children }: { children: React.ReactNode }) {
  return (
    <button className="flex items-center gap-2 rounded-md bg-primary-600 px-4 py-2 text-white">
      {children}
      <ArrowRight weight="regular" className="stroke-[1.5]" />
    </button>
  );
}

Conditional Lucide Usage

Lucide is allowed only on explicit request, requiring conditional imports:

"use client";

let Icon;
if (userWantsLucide) {
  // eslint-disable-next-line @typescript-eslint/no-var-requires
  Icon = require("lucide-react").User;
} else {
  // Default to Phosphor as per the hierarchy
  Icon = require("@phosphor-icons/react").User;
}

export function AvatarIcon() {
  return <Icon className="stroke-[1.5]" />;
}

Pre-Flight Validation and Enforcement

The skill implements automated guards to prevent policy violations. Before emitting code, the agent validates the chosen icon set against the hierarchy and raises warnings for unauthorized libraries used without explicit permission.

Build-Time Validation Utility

You can enforce the "one family per project" rule programmatically using a validation function:

// utils/validate-icons.ts
export function assertSingleIconFamily(imports: string[]) {
  const families = imports.filter((i) =>
    ["phosphor", "hugeicons", "radix", "tabler", "lucide"].some((f) => i.includes(f))
  );
  const uniqueFamilies = new Set(families.map((i) => i.split("/")[0]));
  if (uniqueFamilies.size > 1) {
    throw new Error(
      `Multiple icon families detected (${[...uniqueFamilies].join(
        ", "
      )}). Use only one per project.`
    );
  }
}

Summary

• The skills/taste-skill/SKILL.md file defines a strict four-tier hierarchy led by @phosphor-icons/react, with alternatives listed in descending priority.
• Lucide React is explicitly discouraged unless the user specifically requests it or the project already depends on it.
• Only one icon family may exist per project to prevent visual incoherence and bundle inflation.
• All icons must use a standardized strokeWidth of 1.5 or 2.0 to ensure visual harmony.
• Hand-rolled SVG icons are prohibited; use approved libraries or compose from primitives instead.

Frequently Asked Questions

Can I mix different icon libraries in the same Taste Skill project?

No. The framework strictly forbids mixing icon families such as Phosphor and Lucide within the same component tree. This "one family per project" rule is enforced by pre-flight checks and build-time validation utilities to maintain visual consistency and minimize bundle size, as documented in SKILL.md.

Why is Lucide React discouraged in Taste Skill?

Lucide is restricted to "on-request only" usage to prevent accidental mixing of icon styles and maintain strict visual coherence. According to the source code in SKILL.md and CHANGELOG.md, Lucide may only be used when explicitly requested by the user or when the target project already contains it as a dependency, ensuring developers default to the preferred hierarchy.

What should I do if an icon is missing from the approved libraries?

If a required glyph is not available in your chosen library, you must either add a second approved library from the hierarchy (while maintaining the single-family rule per project) or compose the icon from primitive components. Hand-crafted SVG paths are explicitly banned to avoid accessibility pitfalls and quality inconsistencies.

How does Taste Skill enforce the stroke width standard?

The skill mandates a uniform strokeWidth—typically 1.5 or 2.0—across all icons through documentation in SKILL.md. While the framework includes pre-flight checks for library selection, stroke width consistency is maintained through code review standards and the use of Tailwind patterns like className="stroke-[1.5]" as shown in the official examples.

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