Colorffy

Complete framework for building Vue 3 and Nuxt 3 applications with Colorffy UI (component library) and Colorffy CSS (utility framework).

Quick Reference Index

| Category | Guide | Description | |----------|-------|-------------| | Getting Started | Installation & Setup | Install packages, configure Vue 3/Nuxt 3 | | | Component Selection Guide | Choose the right components for your needs | | | Styling Guide | Colorffy CSS integration, custom styling approaches | | Theming | Theming System | Customize colors, typography, spacing, dark mode | | Reference | Components API | Full reference for 70+ components | | | CSS Utilities | Complete utility class reference | | | Layout Systems | Grid and Flexbox layout utilities | | | Official Documentation | Hosted Colorffy documentation | | | Changelog | Notable changes per release, newest first | | Patterns | Best Practices | Common patterns, workflows, tips |

Framework Overview

Colorffy UI (@colorffy/ui)

70+ Vue 3 components (buttons, forms, cards, dialogs, navigation, tables, etc.)
Unstyled/headless by default - full control over styling
TypeScript support, tree-shakeable
Works with any styling approach

Colorffy CSS (@colorffy/css)

Expressive SCSS framework with tonal color system
Complete utility class library
Flexible grid and flexbox layouts
Dark mode support, customizable at runtime through --cffy-* CSS tokens

Key Insight: Colorffy UI components are unstyled by default. Style with Colorffy CSS, custom CSS, or any CSS framework.

Quick Start

Vue 3

npm install @colorffy/ui @colorffy/css
npm install @vueuse/core @vueuse/components floating-vue

// main.ts
import { createApp } from 'vue'
import ColorffyUI from '@colorffy/ui'
import '@colorffy/css'

const app = createApp(App)
app.use(ColorffyUI)
app.mount('#app')

Nuxt 3 / 4

// nuxt.config.ts: the module registers every Ui* component and auto-imports the composables, no plugin needed
export default defineNuxtConfig({
  css: ['@colorffy/css'],
  modules: ['@colorffy/ui/nuxt'],
  colorffyUI: { locale: 'es-SV', labels: 'es' } // optional
})

See complete installation guide →

Usage Example

<script setup lang="ts">
import { ref } from 'vue'
import { UiButton, UiCard, UiInputText, UiModal } from '@colorffy/ui'

const modal = ref()
const name = ref('')
</script>

<template>
  <!-- Components with Colorffy CSS styling -->
  <UiCard class="shadow-lg rounded-lg">
    <template #body>
      <h2 class="text-primary fw-bold mb-3">Welcome</h2>
      <UiInputText
        id="name"
        v-model="name"
        label="Name"
        placeholder="Enter your name"
        class="mb-3"
      />
      <UiButton
        variant="filled"
        color="primary"
        text="Open Modal"
        @click="modal.showDialog()"
      />
    </template>
  </UiCard>

  <!-- Dialogs open through their exposed showDialog() / closeDialog() -->
  <UiModal ref="modal" title="Hello" size="sm">
    <template #body>
      <p>Hello, {{ name }}!</p>
    </template>
  </UiModal>
</template>

When to Read Each Guide

Installation & Setup - When you need to:

Install Colorffy in Vue 3 or Nuxt 3
Configure SCSS customization
Setup auto-imports
Troubleshoot installation issues

Component Selection Guide - When you need to:

Choose the right component for a UI pattern
Understand when to use one component vs another
Find components by use case (forms, navigation, feedback, etc.)
See component decision trees

Styling Guide - When you need to:

Understand styling approaches (Colorffy CSS, custom, hybrid)
Style components with Colorffy CSS utilities
Write custom CSS for components
Integrate with Tailwind, UnoCSS, or other frameworks

Theming System - When you need to:

Customize colors, typography, spacing
Setup dark mode
Override SCSS variables
Configure design tokens

Components API - When you need to:

Complete component API reference
Specific props, slots, events documentation
Component-specific features and options

CSS Utilities - When you need to:

Specific utility class names
Class patterns for spacing, colors, typography
Responsive utility variants

Layout Systems - When you need to:

Build responsive layouts with grid or flexbox
Understand column configurations
Create complex layouts with alignment and gap utilities

Best Practices - When you need to:

Common patterns (forms, modals, tables, toasts)
Code examples for typical use cases
Performance tips and anti-patterns to avoid

Component Categories Quick Reference

Layout: UiHeaderContent, UiPaneContent, UiCard Navigation: UiNavbar (with UiNavbarBrand, UiNavbarTitle, UiNavbarToggle, UiNavbarCollapse, UiNavbarNav, UiNavbarLink, UiNavbarItem, UiNavbarAvatar, UiNavbarMobileMenu), UiTabs, UiNavigationBar, UiSegmentedControls, UiBreadcrumb, UiPagination, UiPopoverMenu Sidebar: UiSidebar (#header / #body / #footer slots), UiSidebarGroup, UiSidebarLink, UiSidebarText, UiSidebarDropdown Buttons: UiButton, UiButtonMenu, UiButtonMenuSubmenu, UiButtonToggleGroup, UiButtonTooltip Forms: UiInputText, UiInputTextarea, UiInputSelect, UiInputCombobox, UiInputMultiSelect, UiInputDate, UiInputCheck, UiInputRadio, UiInputRange, UiInputFile, UiInputPassword, UiInputSearch, UiInputTags, UiInputOtp, UiInputColorPicker, UiInputPhoneNumber Dialogs: UiModal, UiConfirmModal Feedback: UiAlert, UiAlertToast, UiLoading, UiEmpty Data: UiDatatable, UiListGroup, UiAccordion, UiCalendar, UiStepper, UiTimeline Config: UiConfigProvider (locale and labels for a subtree) Media: UiAvatar, UiIconMaterial

See complete component list →

Utility Class Categories Quick Reference

Spacing: m-*, p-* (px, 0–10, responsive), gap-* (0–10, responsive) Colors: text-*, bg-*, border-* (primary, success, danger, etc.) Typography: display-1–display-4 (prominent headings), fs-* (t-shirt: 4xs–5xl, anchored at base), fw-* (400-800), text-{align} Layout: d-flex, d-grid, justify-content-*, align-items-* Borders: border, rounded-{size} Effects: shadow-*, opacity-*, filter-*, mask-shape shape-*

See complete utilities reference →

Design Tokens

Custom CSS written alongside Colorffy should consume the design tokens instead of hardcoded values. Every public token is --cffy-*; never write an unprefixed Colorffy name, and never set a private --_* variable (set the component's --cffy-<component>-<property> hook instead).

Spacing: var(--cffy-space-4/6/8/12/14/16/20/24/28/32/36/40/48/72/96/120/144/192) — number = px at a 16px root; all derived from --cffy-space-unit (set it on :root; on a wrapper it does nothing)
Density: data-density="compact | comfortable | spacious" on <html> or any element re-derives the spacing and sets --cffy-field-height-sm|md|lg (inputs) and --cffy-control-height-sm|md|lg (buttons, chips, calendar days); --cffy-density set from CSS does the same where container style queries are supported (see references/theming.md)
Font sizes: var(--cffy-fs-4xs…5xl) + var(--cffy-fs-{step}--line-height) companions
Widths: var(--cffy-container-3xs…7xl) (16rem … 80rem), also as max-w-{size} utilities
Colors: --cffy-<color>-a10 for a solid fill with --cffy-on-<color> text; --cffy-<color>-container for a tinted surface with --cffy-on-<color>-container text

See theming reference →

Upgrading from 2.x

3.0 is a breaking release. When existing code uses a 2.x name, rewrite it following the migration guide, in this order:

Deprecations removed: ordinal font sizes (--fs-100, .fs-500, …) → the t-shirt scale (--cffy-fs-4xl, .fs-lg; the classes also set the paired line-height). $space-1/2/3 → var(--cffy-space-16/32/48). The $primary … $muted, $primary-colors and $font-* SCSS variables are gone → set the --cffy-color-brand-* / --cffy-font-* tokens.
Namespace: --theme-* swapped theme- for --cffy- (--theme-primary-a10 → --cffy-primary-a10); every other public name gained the prefix (--space-16 → --cffy-space-16, --card-bg-color → --cffy-card-bg-color). --theme-nav-drawer-width → --cffy-sidebar-width. Private --_* variables were renamed after their hooks, so overrides of old privates silently stop applying: set the public hook. The PrimeVue skin (_prime.scss, --p-*) is gone: move to UiInputCombobox / UiInputMultiSelect / UiInputDate, or copy the partial from @colorffy/css@2.8.
Tonal colors: text on a tinted surface reads --cffy-on-<color>-container, not a90 (now the darkest ramp step in both modes). --cffy-on-<color>-inverse → --cffy-on-background. SCSS btn-tonal() / container-tonal() take the container token instead of an $isDark flag.
Removed component API: UiPopoverMenu user / avatarUrl / avatarCustomClass / subtitle (→ UiPopoverMenuUser in #header), #body-extra and the default slot (→ #body); UiSidebarHeader / Body / Footer and UiSidebar's default slot (→ #header / #body / #footer, with header-class / body-class / footer-class); UiEmpty #button (→ #action); UiInputFile large (→ size="lg"); BaseSkeleton isThumbnail (→ variant="thumbnail"); ISegmentedTab.position; UiButtonToggleGroup groupLabel (→ ariaLabel); UiModal isHeadless (→ mode="headless"); UiDatatable skeletonCols / skeletonColExpanded / isExpanded (the skeleton matches the visible columns).
Events: no on prefix — @click, @update, @close (dialogs), @option-click. Tabs and segmented controls use v-model:active-tab, the stepper v-model:active-step.
ids: the id prop renders unchanged on the main element or field (2.x wrote button-<id>, <id>-input-text, …); the color picker's text field is <id>-text.

Hand-written @colorffy/css markup also needs, since 2.5:

Tabs: .tabs-navigation draws its active indicator with CSS anchor positioning, so the list needs a final <li class="tab-indicator" aria-hidden="true" role="presentation"></li>. UiTabs renders it already.
Chips: .btn-chip is the outline container and .chip-elevated the raised one; a color class (.chip-secondary, .chip-neutral) only applies together with .chip-active.
Cards: .card-outline / .card-pane / .card-elevated are static surfaces (one per card); add .card-selectable or .card-link for hover and press feedback.
Popover menu: in browsers with the Popover API and CSS anchor positioning the panel is a top-layer popover="auto"; custom CSS that repositioned .popover-menu must target .popover-menu[popover], or opt out with :native-popover="false".

See the migration guide → · Changelog →

Support

Issues: GitHub Issues
Discussions: GitHub Discussions