Phila Button Component

A flexible, accessible button component built with Vue 3 and TypeScript, implementing the Philadelphia Design System.

Features

• 🎨 Multiple variants: primary, secondary, destructive, standard
• 📐 Multiple sizes: extra-large, large, medium (default), small, extra-small
• 🎯 Icon support: left icons, right icons, and icon-only buttons
• ♿ Full accessibility: ARIA attributes, focus states, disabled state
• 🔧 Flexible API: Props or slots for content
• 💅 Design system integration: Uses Core package styles

Installation

npm install @phila/phila-ui-button @phila/phila-ui-core
# or
pnpm add @phila/phila-ui-button @phila/phila-ui-core

Import core styles in your main entry file (e.g., main.js|ts):

import "@phila/phila-ui-core/styles/template-light.css";

Vue Component Usage

Basic Usage

<script setup lang="ts">
import { PhilaButton } from "@phila/phila-ui-button";

const handleClick = () => {
  console.log("Button clicked!");
};
</script>

<template>
  <PhilaButton variant="primary" @click="handleClick"> Click Me </PhilaButton>
</template>

With Props

<PhilaButton variant="primary" size="medium" text="Click Me" @click="handleClick" />

With Icons

<script setup lang="ts">
import { PhilaButton } from "@phila/phila-ui-button";
import { faPencil, faArrowRight } from "@fortawesome/pro-solid-svg-icons";
</script>

<template>
  <!-- Left Icon -->
  <PhilaButton variant="primary" :icon="faPencil" text="Edit" />

  <!-- Right Icon -->
  <PhilaButton variant="primary" :icon="faArrowRight" icon-right text="Continue" />

  <!-- Icon Only -->
  <PhilaButton variant="primary" icon-only :icon="faPencil" />
</template>

Props

| Prop | Type | Default | Description | | ----------- | ------------------------------------------------------------------ | ----------- | ------------------------------------------------------------- | | variant | "primary" \| "secondary" \| "destructive" \| "standard" | "primary" | Button style variant | | size | "extra-large" \| "large" \| "medium" \| "small" \| "extra-small" | "medium" | Button size | | disabled | boolean | false | Whether the button is disabled | | iconOnly | boolean | false | Whether to display only an icon | | icon | IconDefinition | undefined | FontAwesome icon definition | | iconClass | string | undefined | FontAwesome icon class name | | iconRight | boolean | false | Whether to position the icon on the right side | | text | string | undefined | Button text (alternative to slot) | | className | string | undefined | Additional CSS classes | | href | string | undefined | URL for link buttons (renders as <a> instead of <button>) | | target | string | undefined | Link target attribute (e.g., "_blank") | | rel | string | undefined | Link rel attribute (e.g., "noopener noreferrer") |

Variants

<PhilaButton variant="primary">Primary</PhilaButton>
<PhilaButton variant="secondary">Secondary</PhilaButton>
<PhilaButton variant="destructive">Destructive</PhilaButton>
<PhilaButton variant="standard" icon-only :left-icon="faSearch">Standard Icon</PhilaButton>

Sizes

<PhilaButton size="extra-large">Extra Large</PhilaButton>
<PhilaButton size="large">Large</PhilaButton>
<PhilaButton size="medium">Medium (default)</PhilaButton>
<PhilaButton size="small">Small</PhilaButton>
<PhilaButton size="extra-small">Extra Small</PhilaButton>

Link Buttons

Buttons can also render as links by providing an href prop:

<script setup lang="ts">
import { PhilaButton } from "@phila/phila-ui-button";
import { faArrowRight } from "@fortawesome/pro-solid-svg-icons";
</script>

<template>
  <!-- Internal link -->
  <PhilaButton href="/about" text="Learn More" />

  <!-- External link -->
  <PhilaButton
    href="https://example.com"
    target="_blank"
    rel="noopener noreferrer"
    text="Visit Site"
    :icon="faArrowRight"
    icon-right
  />
</template>

States

<PhilaButton disabled>Disabled Button</PhilaButton>

Using CSS Classes Directly

You can also use the button styles directly without the Vue component by applying CSS classes to any element:

<template>
  <button class="phila-button phila-button--primary is-medium" @click="handleClick">Medium primary button</button>

  <a class="phila-button phila-button--primary" href="#" @click.prevent="handleClick"> Link as a button </a>
</template>

Button Classes

The Phila UI button requires the phila-button class and one modifier class. You can apply the following modifier classes:

Variants

• phila-button--primary
• phila-button--secondary
• phila-button--destructive

Sizes

• is-extra-small
• is-small
• is-medium
• is-large (optional, large is default)

States

• Disabled: apply the disabled attribute to the button element.

Button layouts

There are three main layouts for the Phila UI button:

1. Text: The default layout, displaying only text.
2. Text + Icon: Displays both text and an icon.
3. Icon Button: Displays only an icon.

Text

<button class="phila-button phila-button--primary">
  Button text
  </button>

Note: Overflow text will not be truncated with ellipsis unless the button text is wrapped in a span.

Text + Icon

Icons require manual installation of FontAwesome.

<button class="phila-button phila-button--primary">
  <span class="icon">
    <i class="fas fa-search"></i>
  </span>
  <span>Button text</span>
</button>

Icon + Text

<button class="phila-button phila-button--primary">
  <span>Button text</span>
  <span class="icon">
    <i class="fas fa-search"></i>
  </span>
</button>

Icon Button

Icon buttons require the icon-button class. The default size is "extra-large". For other sizes, include the appropriate size class. To use the "standard" variant, replace phila-button--primary|secondary|destructive with icon-button--standard.

<button class="phila-button phila-button--primary icon-button">
  <span class="icon">
    <i class="fas fa-search"></i>
  </span>
</button>

Development

Install Dependencies

pnpm install

Run Storybook demo

npm run storybook

Run lint

npm run lint

Create Production Build

npm run build

Test locally in your development environment

npm pack
cp ./dist/*.tgz ~/path/to/your/local/npm/repo
cd ~/path/to/your/local/npm/repo
npm install *.tgz

Publishing to NPM

Follow the release instructions using changesets.

License

MIT